mega-framework 0.1.9 → 0.1.11

package/src/core/bus/cluster-bus.js

@@ -0,0 +1,190 @@
+// @ts-check
+/**
+ * ClusterBusDriver — Node `cluster` IPC 기반 메시지 버스 driver (ADR-227).
+ *
+ * NATS 가 없지만 **클러스터**(`mega start --cluster=N`)로 도는 환경용. 워커들이 **master 프로세스를 fan-out
+ * 라우터**로 쓴다 — 워커가 IPC 로 master 에 구독/발행을 보내고, master 가 구독 레지스트리를 관리하며 매칭되는
+ * 모든 워커에 메시지를 배달한다. wildcard 매칭은 master 가 {@link matchSubject} 로 수행한다.
+ *
+ * # ⚠️ 멀티 노드 미보장
+ *   cluster IPC 는 **한 노드(master + 그 워커들)** 안에서만 닿는다. 노드가 여러 대면 master 도 여러 개라 서로의
+ *   구독을 모른다 — **노드 간 전달은 안 된다**. 진짜 분산 버스는 nats-bus 를 쓴다. 영속(persist)도 미지원
+ *   (메모리 라우팅 — `persist:true` 면 manager 가 경고 후 비영속 전달). factory 가 부팅 경고로 알린다.
+ *
+ * # 구성
+ *   - **master 측**: {@link installClusterBusMaster} 를 master 프로세스에서 1회 호출 — 구독 레지스트리 +
+ *     fan-out + request/reply 라우팅. 워커 종료 시 그 워커 구독 자동 정리(`mega start` 클러스터 분기).
+ *   - **worker 측**: {@link ClusterBusDriver} 가 `process.send` 로 구독/발행하고, master 의 'deliver' 를 받아
+ *     로컬 핸들러를 호출한다. ordered 직렬화·request 응답 대기는 worker 가 로컬 처리한다.
+ *
+ * driver 계약은 {@link import('./contract.js').BusDriver} 를 따른다(typedef — 런타임 implements 아님).
+ * @module core/bus/cluster-bus
+ */
+import nodeCluster from 'node:cluster'
+import { matchSubject } from './contract.js'
+import { MegaInternalError } from '../../errors/http-errors.js'
+
+/** IPC 메시지 마커 — 다른 cluster 메시지(metrics·lock 등)와 섞이지 않게. */
+const BUS_MSG = 'mega:bus'
+/** master responder 설치 여부(멱등 가드). @type {boolean} */
+let masterInstalled = false
+
+/**
+ * master 프로세스에 버스 라우터를 설치한다(멱등). 워커들의 구독을 모아 발행 시 fan-out 한다.
+ * `mega start` 클러스터 분기에서 master 가 1회 호출한다.
+ * @param {import('node:cluster').Cluster} [cluster] - 테스트 주입용(기본 node:cluster).
+ * @returns {{ subscriptions: () => number } | null} 관측용 핸들(테스트). 이미 설치됐으면 null.
+ */
+export function installClusterBusMaster(cluster = nodeCluster) {
+  if (masterInstalled) return null
+  masterInstalled = true
+  /** @type {Array<{ worker: any, subId: number, pattern: string }>} 구독 레지스트리. */
+  const subs = []
+  /** @type {Map<string, any>} reqId → 요청 보낸 worker(reply 라우팅용). */
+  const requests = new Map()
+
+  cluster.on('message', (worker, msg) => {
+    if (!msg || msg.t !== BUS_MSG) return
+    if (msg.op === 'subscribe') {
+      subs.push({ worker, subId: msg.subId, pattern: msg.pattern })
+    } else if (msg.op === 'unsubscribe') {
+      const i = subs.findIndex((s) => s.worker === worker && s.subId === msg.subId)
+      if (i >= 0) subs.splice(i, 1)
+    } else if (msg.op === 'publish') {
+      for (const s of subs) {
+        if (matchSubject(s.pattern, msg.subject)) s.worker.send?.({ t: BUS_MSG, op: 'deliver', subId: s.subId, envelope: msg.envelope, subject: msg.subject })
+      }
+    } else if (msg.op === 'request') {
+      const matches = subs.filter((s) => matchSubject(s.pattern, msg.subject))
+      if (matches.length === 0) {
+        worker.send?.({ t: BUS_MSG, op: 'no_responders', reqId: msg.reqId })
+        return
+      }
+      requests.set(msg.reqId, worker)
+      for (const s of matches) s.worker.send?.({ t: BUS_MSG, op: 'deliver', subId: s.subId, envelope: msg.envelope, reqId: msg.reqId, subject: msg.subject })
+    } else if (msg.op === 'reply') {
+      const requester = requests.get(msg.reqId)
+      if (requester) {
+        requests.delete(msg.reqId) // 첫 응답만 라우팅(요청자도 settled 가드).
+        requester.send?.({ t: BUS_MSG, op: 'deliver-reply', reqId: msg.reqId, envelope: msg.envelope })
+      }
+    }
+  })
+
+  // 워커 종료 시 그 워커의 구독 정리(stale fan-out 방지).
+  cluster.on('exit', (worker) => {
+    for (let i = subs.length - 1; i >= 0; i--) {
+      if (subs[i].worker === worker) subs.splice(i, 1)
+    }
+  })
+
+  return { subscriptions: () => subs.length }
+}
+
+/** 테스트 격리용 — master 설치 플래그 초기화. @returns {void} */
+export function _resetClusterBusMaster() {
+  masterInstalled = false
+}
+
+/**
+ * 워커 측 cluster 버스 driver — master 에 IPC 위임 + master 의 deliver 를 로컬 핸들러로 디스패치.
+ */
+export class ClusterBusDriver {
+  /** @type {NodeJS.Process} master 와의 IPC 채널. */ #proc
+  /** @type {(msg: any) => void} 'message' 리스너 참조(close 에서 제거). */ #onMessage
+  /** @type {number} 구독 id 시퀀스(워커 로컬). */ #subSeq = 0
+  /** @type {number} 요청 id 시퀀스. */ #reqSeq = 0
+  /** @type {Map<number, { handler: Function, ordered: boolean, tail: Promise<void> }>} subId → 로컬 핸들러. */ #handlers = new Map()
+  /** @type {Map<string, { resolve: (v: any) => void, reject: (e: any) => void, timer: any }>} reqId → 응답 대기. */ #pending = new Map()
+
+  /**
+   * @param {{ proc?: NodeJS.Process }} [opts] - `proc` 테스트 주입용(기본 process). cluster 워커여야 send 존재.
+   * @throws {Error} proc.send 가 없으면(cluster 워커 아님).
+   */
+  constructor({ proc = process } = {}) {
+    if (typeof proc.send !== 'function') {
+      throw new Error('ClusterBusDriver requires an IPC channel (process.send) — only valid in a cluster worker.')
+    }
+    this.#proc = proc
+    this.#onMessage = (msg) => this.#receive(msg)
+    proc.on('message', this.#onMessage)
+  }
+
+  /** @type {'cluster'} */
+  get name() {
+    return 'cluster'
+  }
+
+  /** master 의 deliver/deliver-reply/no_responders 를 처리. @param {any} msg @returns {void} */
+  #receive(msg) {
+    if (!msg || msg.t !== BUS_MSG) return
+    if (msg.op === 'deliver') {
+      const local = this.#handlers.get(msg.subId)
+      if (!local) return
+      // request 면(reqId 동봉) reply 를 master 로 돌려보내는 replyFn 제공.
+      const reply = msg.reqId !== undefined ? (/** @type {any} */ env) => this.#proc.send?.({ t: BUS_MSG, op: 'reply', reqId: msg.reqId, envelope: env }) : undefined
+      if (local.ordered) local.tail = local.tail.then(() => local.handler(msg.envelope, reply, msg.subject))
+      else void local.handler(msg.envelope, reply, msg.subject)
+    } else if (msg.op === 'deliver-reply') {
+      const p = this.#pending.get(msg.reqId)
+      if (!p) return
+      this.#pending.delete(msg.reqId)
+      clearTimeout(p.timer)
+      p.resolve(msg.envelope)
+    } else if (msg.op === 'no_responders') {
+      const p = this.#pending.get(msg.reqId)
+      if (!p) return
+      this.#pending.delete(msg.reqId)
+      clearTimeout(p.timer)
+      p.reject(new MegaInternalError('bus.no_responders', 'bus request: no subscriber matches the subject (cluster).', { details: {} }))
+    }
+  }
+
+  /** cluster 는 persist 무시(opts 는 계약 정합용). @param {string} subject @param {import('./contract.js').BusEnvelope} envelope @param {{ persist?: boolean }} [_opts] @returns {Promise<void>} */
+  async publish(subject, envelope, _opts = {}) {
+    this.#proc.send?.({ t: BUS_MSG, op: 'publish', subject, envelope })
+  }
+
+  /** @param {string} pattern @param {Function} handler @param {{ ordered?: boolean }} opts @returns {Promise<import('./contract.js').Subscription>} */
+  async subscribe(pattern, handler, { ordered = false } = {}) {
+    const subId = ++this.#subSeq
+    this.#handlers.set(subId, { handler, ordered, tail: Promise.resolve() })
+    this.#proc.send?.({ t: BUS_MSG, op: 'subscribe', subId, pattern })
+    return {
+      unsubscribe: async () => {
+        this.#handlers.delete(subId)
+        this.#proc.send?.({ t: BUS_MSG, op: 'unsubscribe', subId })
+      },
+    }
+  }
+
+  /** @param {string} subject @param {import('./contract.js').BusEnvelope} envelope @param {{ timeout: number }} opts @returns {Promise<import('./contract.js').BusEnvelope>} */
+  async request(subject, envelope, { timeout }) {
+    const reqId = `${process.pid}:${++this.#reqSeq}`
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.#pending.delete(reqId)
+        reject(new MegaInternalError('bus.request_timeout', `bus request("${subject}") timed out after ${timeout}ms.`, { details: { subject, timeout } }))
+      }, timeout)
+      timer.unref?.()
+      this.#pending.set(reqId, { resolve, reject, timer })
+      this.#proc.send?.({ t: BUS_MSG, op: 'request', reqId, subject, envelope })
+    })
+  }
+
+  /** @returns {Promise<{ driver: string, subscriptions: number }>} */
+  async stats() {
+    return { driver: 'cluster', subscriptions: this.#handlers.size }
+  }
+
+  /** 정리 — IPC 리스너 제거 + 대기 요청 reject + 핸들러 비움. @returns {Promise<void>} */
+  async close() {
+    this.#proc.off?.('message', this.#onMessage)
+    for (const [, p] of this.#pending) {
+      clearTimeout(p.timer)
+      p.reject(new MegaInternalError('bus.closed', 'bus closed while request was pending.', { details: {} }))
+    }
+    this.#pending.clear()
+    this.#handlers.clear()
+  }
+}

package/src/core/bus/contract.js

@@ -0,0 +1,123 @@
+// @ts-check
+/**
+ * 메시지 버스 공통 contract — driver 인터페이스 + subject 검증/정규화 + NATS 식 wildcard 매처 (ADR-227).
+ *
+ * `ctx.bus.emit/.on/.request` 사용자 API 는 {@link import('./index.js').BusManager} 가 제공하고, 실제
+ * 전달(fan-out·request/reply·영속)은 **driver**(nats/cluster/memory)가 담당한다. driver 는 전송만 하고,
+ * subject prefix·envelope(payload+meta) 포장·핸들러 등록부 같은 ergonomics 는 manager 가 driver 위에 얹는다.
+ *
+ * # 기존 `ctx.bus(alias)` 와의 관계 (ADR-110 ↔ ADR-227)
+ *   `ctx.bus` 는 **callable object** 다 — `ctx.bus(alias)` 는 종전대로 설정된 `MegaBusAdapter`(NATS 등)를
+ *   반환하고(기존 사용처 무변경), 거기에 `.emit/.on/.off/.request/.with` 메서드가 붙어 사용자 메시지 버스 API 가
+ *   된다. 락(ADR-226)의 `ctx.lock` 콜러블 공존과 같은 패턴이다.
+ *
+ * # subject 와 wildcard (NATS 의미 그대로)
+ *   subject 는 `.` 으로 구분된 토큰열(`order.created`). 구독 패턴엔 wildcard 를 쓸 수 있다:
+ *   - `*` = **정확히 한 토큰**. `order.*` → `order.created`(O), `order.created.eu`(X).
+ *   - `>` = **한 토큰 이상(꼬리 전체)**, 맨 끝에만. `order.>` → `order.created`(O), `order.created.eu`(O), `order`(X).
+ *   nats-bus 는 NATS 가 native 로 매칭하고, cluster/memory-bus 는 {@link matchSubject} 로 자체 매칭한다.
+ *
+ * @module core/bus/contract
+ */
+import { MegaValidationError } from '../../errors/http-errors.js'
+
+/** request/reply 응답 대기 디폴트(ms). config `bus.requestTimeoutMs` 로 조정. */
+export const DEFAULT_REQUEST_TIMEOUT_MS = 5000
+
+/**
+ * @typedef {Object} BusEnvelope - wire/IPC 로 오가는 메시지 봉투(payload 와 meta 분리 — meta 는 traceId 등).
+ * @property {any} payload - 사용자 데이터.
+ * @property {Record<string, any>} [meta] - 부가 메타(전파용). 없으면 빈 객체로 취급.
+ */
+
+/**
+ * @typedef {Object} EmitOpts - emit 옵션.
+ * @property {Record<string, any>} [meta] - 이 메시지의 meta.
+ * @property {boolean} [persist] - true 면 영속 전달(JetStream — nats-bus 만; 그 외 driver 는 경고 후 비영속).
+ */
+
+/**
+ * @typedef {Object} OnOpts - on(구독) 옵션.
+ * @property {boolean} [persist] - true 면 영속 구독(JetStream consumer — nats-bus 만).
+ * @property {boolean} [ordered] - true 면 같은 subject 메시지를 순서대로 1건씩 직렬 처리(핸들러 await 직렬화).
+ */
+
+/**
+ * @typedef {(payload: any, meta: Record<string, any>, subject: string) => any} BusHandler - 사용자 핸들러.
+ *   3번째 인자 `subject` 는 메시지가 도착한 **구체** subject(prefix 제거됨) — wildcard 구독에서 어느 subject 가
+ *   매칭됐는지 안다. `meta.subject` 에도 같은 값이 담긴다(정본 위치). request 대상이면 **반환값이 reply**.
+ */
+
+/**
+ * @typedef {Object} Subscription - on/subscribe 가 돌려주는 구독 핸들.
+ * @property {() => Promise<void>} unsubscribe - 구독 해제.
+ */
+
+/**
+ * @typedef {(envelope: BusEnvelope) => void} ReplyFn - driver 가 핸들러에 주는 응답 함수(request 일 때만).
+ *
+ * @typedef {Object} BusDriver - driver 가 구현하는 저수준 인터페이스(manager 가 호출).
+ * @property {string} name - 'nats' | 'cluster' | 'memory'.
+ * @property {(subject: string, envelope: BusEnvelope, opts: { persist?: boolean }) => Promise<void>} publish -
+ *   fire-and-forget 발행(구독자 전원 fan-out).
+ * @property {(subject: string, handler: (envelope: BusEnvelope, reply?: ReplyFn, subject?: string) => any, opts: { persist?: boolean, ordered?: boolean }) => Promise<Subscription>} subscribe -
+ *   구독(subject 는 wildcard 가능). `reply` 는 request 로 들어온 메시지일 때만 제공. 핸들러의 3번째 인자는
+ *   매칭된 **구체** subject(driver 가 채워 manager 로 넘김 — wildcard 어디로 왔는지 안다).
+ * @property {(subject: string, envelope: BusEnvelope, opts: { timeout: number }) => Promise<BusEnvelope>} request -
+ *   req/reply — 첫 응답 envelope 반환. 응답자 없으면 `bus.no_responders`, 시한 초과면 `bus.request_timeout` throw.
+ * @property {() => Promise<{ driver: string, subscriptions: number }>} stats - 현재 구독 수.
+ * @property {() => Promise<void>} close - 구독·타이머·IPC·연결참조 정리.
+ */
+
+/**
+ * subject 정규화 — prefix 를 앞에 붙인다(네임스페이스 격리). prefix 가 빈 값이면 그대로.
+ * @param {string} subject @param {string} [prefix] - 예: 'app.'.
+ * @returns {string}
+ */
+export function normalizeSubject(subject, prefix) {
+  return prefix ? `${prefix}${subject}` : subject
+}
+
+/**
+ * subject 검증 — 비어있지 않고 공백/제어문자 없는 문자열. publish subject 는 wildcard 금지(구체적이어야 함).
+ * @param {string} subject @param {{ allowWildcard?: boolean }} [opts] - true 면 `*`/`>` 허용(구독용).
+ * @returns {void}
+ * @throws {MegaValidationError} `bus.invalid_subject`
+ */
+export function assertSubject(subject, { allowWildcard = false } = {}) {
+  if (typeof subject !== 'string' || subject.length === 0) {
+    throw new MegaValidationError('bus.invalid_subject', `bus subject must be a non-empty string. Got: ${typeof subject}.`, { details: { subject } })
+  }
+  if (/\s/.test(subject)) {
+    throw new MegaValidationError('bus.invalid_subject', `bus subject must not contain whitespace. Got: ${JSON.stringify(subject)}.`, { details: { subject } })
+  }
+  if (!allowWildcard && /[*>]/.test(subject)) {
+    throw new MegaValidationError('bus.invalid_subject', `bus publish subject must be concrete (no '*'/'>' wildcards). Got: ${JSON.stringify(subject)}.`, { details: { subject } })
+  }
+  if (allowWildcard) {
+    const tokens = subject.split('.')
+    const gtIdx = tokens.indexOf('>')
+    if (gtIdx !== -1 && gtIdx !== tokens.length - 1) {
+      throw new MegaValidationError('bus.invalid_subject', `bus '>' wildcard must be the last token. Got: ${JSON.stringify(subject)}.`, { details: { subject } })
+    }
+  }
+}
+
+/**
+ * NATS 식 wildcard 매칭 — cluster/memory-bus 의 자체 패턴 매칭(nats-bus 는 NATS native 사용).
+ *   `*` = 한 토큰, `>` = 한 토큰 이상(꼬리). 토큰 수가 정확히 맞아야 매칭(`>` 제외).
+ * @param {string} pattern - 구독 패턴(wildcard 가능). @param {string} subject - 구체 subject.
+ * @returns {boolean}
+ */
+export function matchSubject(pattern, subject) {
+  if (pattern === subject) return true
+  const p = pattern.split('.')
+  const s = subject.split('.')
+  for (let i = 0; i < p.length; i++) {
+    if (p[i] === '>') return s.length > i // 꼬리 전체(한 토큰 이상 남아야).
+    if (i >= s.length) return false
+    if (p[i] === '*') continue // 한 토큰 매치.
+    if (p[i] !== s[i]) return false
+  }
+  return p.length === s.length // wildcard 없는 잔여 — 토큰 수 일치해야.
+}

package/src/core/bus/index.js

@@ -0,0 +1,285 @@
+// @ts-check
+/**
+ * 메시지 버스 — BusManager(사용자 API) + 자동 폴백 factory + `ctx.bus` 부착 (ADR-227).
+ *
+ * # 두 층
+ *   - **driver**(nats/cluster/memory): 저수준 전달만(`publish/subscribe/request/stats/close`).
+ *     {@link import('./contract.js').BusDriver} 계약.
+ *   - **BusManager**: driver 위에 사용자 ergonomics — `emit`/`on`(핸들러 = payload,meta)/`off`/`request`/
+ *     `with`(meta 바인딩) + subject prefix + envelope 포장 + 핸들러 에러 격리(driver 로 reject 전파 안 함).
+ *
+ * # 자동 폴백 (`driver: 'auto'`, 기본)
+ *   bus(NATS) 어댑터 활성 → **nats**(진짜 분산). 없고 cluster 워커 → **cluster**(단일 노드, 경고). 둘 다 없음
+ *   → **memory**(분산 미보장, 경고). 명시 driver 는 전제 부재 시 **fail-fast**(P7).
+ *
+ * # `ctx.bus` 통합
+ *   `ctx.bus` 는 종전대로 `(alias) => MegaBusAdapter` 콜러블이고, {@link attachBusApi} 가
+ *   `.emit/.on/.off/.request/.with/.stats` 를 얹는다. `ctx.bus(alias)`(기존)와 `ctx.bus.emit(...)`(신규) 공존.
+ *
+ * @module core/bus
+ */
+import { MegaValidationError } from '../../errors/http-errors.js'
+import { assertSubject, normalizeSubject, DEFAULT_REQUEST_TIMEOUT_MS } from './contract.js'
+import { MemoryBusDriver } from './memory-bus.js'
+import { ClusterBusDriver } from './cluster-bus.js'
+import { NatsBusDriver } from './nats-bus.js'
+
+export { MemoryBusDriver, ClusterBusDriver, NatsBusDriver }
+
+/**
+ * 프로세스 전역 활성 manager — boot 가 설정하고 ctx-builder 가 `ctx.bus` 부착 시 읽는다(락과 동일 패턴).
+ * @type {BusManager | null}
+ */
+let activeManager = null
+
+/** 활성 버스 manager 설정(boot bus 스테이지). null 로 해제(셧다운/테스트). @param {BusManager | null} m @returns {void} */
+export function setBusManager(m) {
+  activeManager = m
+}
+
+/** 현재 활성 버스 manager(없으면 null). @returns {BusManager | null} */
+export function getBusManager() {
+  return activeManager
+}
+
+/**
+ * 사용자 메시지 버스 API. driver 한 개를 감싸 emit/on/off/request/with 를 제공한다.
+ */
+export class BusManager {
+  /** @type {import('./contract.js').BusDriver} */ #driver
+  /** @type {{ prefix: string, defaultPersist: boolean, requestTimeoutMs: number }} */ #defaults
+  /** @type {any} 로거(옵션). */ #logger
+  /** @type {Array<{ subject: string, handler: Function, subscription: import('./contract.js').Subscription }>} off() 추적. */ #regs = []
+  /** @type {boolean} persist 미지원 driver 경고 1회 가드. */ #persistWarned = false
+
+  /**
+   * @param {import('./contract.js').BusDriver} driver
+   * @param {{ defaults: { prefix: string, defaultPersist: boolean, requestTimeoutMs: number }, logger?: any }} opts
+   */
+  constructor(driver, { defaults, logger }) {
+    this.#driver = driver
+    this.#defaults = defaults
+    this.#logger = logger
+  }
+
+  /** @returns {string} 활성 driver 이름('nats'|'cluster'|'memory'). */
+  get driverName() {
+    return this.#driver.name
+  }
+
+  /**
+   * 메시지 발행(fire-and-forget fan-out).
+   * @param {string} subject - 구체 subject(wildcard 불가).
+   * @param {any} payload
+   * @param {import('./contract.js').EmitOpts} [opts] - meta / persist.
+   * @returns {Promise<void>}
+   */
+  async emit(subject, payload, opts = {}) {
+    assertSubject(subject)
+    const full = normalizeSubject(subject, this.#defaults.prefix)
+    const persist = this.#resolvePersist(opts.persist)
+    this.#logger?.debug?.({ subject: full, driver: this.#driver.name, persist }, 'bus.emit')
+    await this.#driver.publish(full, { payload, meta: opts.meta ?? {} }, { persist })
+  }
+
+  /**
+   * 구독. 핸들러는 `(payload, meta)`. request 대상이면 핸들러 **반환값이 reply**(undefined 면 응답 안 함).
+   * @param {string} subject - wildcard(`*`/`>`) 가능.
+   * @param {import('./contract.js').BusHandler} handler
+   * @param {import('./contract.js').OnOpts} [opts] - persist / ordered.
+   * @returns {Promise<import('./contract.js').Subscription>}
+   */
+  async on(subject, handler, opts = {}) {
+    assertSubject(subject, { allowWildcard: true })
+    if (typeof handler !== 'function') {
+      throw new MegaValidationError('bus.invalid_handler', `ctx.bus.on(subject, handler) requires a function. Got: ${typeof handler}.`, { details: { subject } })
+    }
+    const full = normalizeSubject(subject, this.#defaults.prefix)
+    const persist = this.#resolvePersist(opts.persist)
+    // driver 로 넘기는 wrapper — 사용자 핸들러 에러를 여기서 흡수(driver 는 reject 를 못 받는다). reply 처리도 여기.
+    // driver 가 넘긴 구체 subject 에서 prefix 를 떼어(사용자는 unprefixed 로 생각) 3번째 인자 + meta.subject 로 준다.
+    const wrapped = async (/** @type {import('./contract.js').BusEnvelope} */ env, /** @type {import('./contract.js').ReplyFn} */ reply, /** @type {string} */ subject) => {
+      const userSubject = this.#stripPrefix(subject)
+      const meta = userSubject === undefined ? (env.meta ?? {}) : { ...(env.meta ?? {}), subject: userSubject }
+      try {
+        const result = await handler(env.payload, meta, /** @type {any} */ (userSubject))
+        if (reply && result !== undefined) reply({ payload: result, meta: {} })
+      } catch (e) {
+        // 핸들러 실패는 비치명적(다른 구독자·다음 메시지에 영향 없게) — 로깅하고 흡수(P4: 무시 아님, 격리).
+        this.#logger?.error?.({ subject: full, driver: this.#driver.name, err: e }, 'bus.on handler threw')
+      }
+    }
+    const subscription = await this.#driver.subscribe(full, wrapped, { persist, ordered: opts.ordered === true })
+    this.#regs.push({ subject: full, handler, subscription })
+    this.#logger?.debug?.({ subject: full, driver: this.#driver.name, persist, ordered: opts.ordered === true }, 'bus.on subscribed')
+    return subscription
+  }
+
+  /**
+   * 구독 해제 — 같은 (subject, handler) 로 등록된 구독을 푼다.
+   * @param {string} subject @param {import('./contract.js').BusHandler} handler @returns {Promise<void>}
+   */
+  async off(subject, handler) {
+    const full = normalizeSubject(subject, this.#defaults.prefix)
+    const i = this.#regs.findIndex((r) => r.subject === full && r.handler === handler)
+    if (i < 0) return // 등록 안 됐거나 이미 해제 — idempotent.
+    const [reg] = this.#regs.splice(i, 1)
+    await reg.subscription.unsubscribe()
+  }
+
+  /**
+   * req/reply — 첫 응답 payload 반환. 응답자 없으면 `bus.no_responders`, 시한 초과면 `bus.request_timeout`.
+   * @param {string} subject @param {any} payload
+   * @param {{ timeout?: number, meta?: Record<string, any> }} [opts]
+   * @returns {Promise<any>}
+   */
+  async request(subject, payload, opts = {}) {
+    assertSubject(subject)
+    const full = normalizeSubject(subject, this.#defaults.prefix)
+    const timeout = opts.timeout ?? this.#defaults.requestTimeoutMs
+    this.#logger?.debug?.({ subject: full, driver: this.#driver.name, timeout }, 'bus.request')
+    const reply = await this.#driver.request(full, { payload, meta: opts.meta ?? {} }, { timeout })
+    return reply.payload
+  }
+
+  /**
+   * meta 를 바인딩한 스코프 버스 — 이후 emit/request 가 이 meta 를 자동 병합한다(요청 단위 traceId 등).
+   * @param {Record<string, any>} meta @returns {{ emit: Function, on: Function, off: Function, request: Function, with: Function }}
+   */
+  with(meta) {
+    const self = this
+    /** @param {Record<string, any>} [m] */
+    const merge = (m) => ({ ...meta, ...m })
+    return {
+      emit: (/** @type {string} */ s, /** @type {any} */ p, /** @type {import('./contract.js').EmitOpts} */ o = {}) => self.emit(s, p, { ...o, meta: merge(o.meta) }),
+      request: (/** @type {string} */ s, /** @type {any} */ p, /** @type {any} */ o = {}) => self.request(s, p, { ...o, meta: merge(o.meta) }),
+      on: (/** @type {string} */ s, /** @type {any} */ h, /** @type {any} */ o) => self.on(s, h, o),
+      off: (/** @type {string} */ s, /** @type {any} */ h) => self.off(s, h),
+      with: (/** @type {Record<string, any>} */ m) => self.with(merge(m)),
+    }
+  }
+
+  /** @returns {Promise<{ driver: string, subscriptions: number }>} */
+  async stats() {
+    return this.#driver.stats()
+  }
+
+  /** 정리 — 등록 구독 해제 + driver 정리. @returns {Promise<void>} */
+  async close() {
+    for (const reg of this.#regs.splice(0)) {
+      try {
+        await reg.subscription.unsubscribe()
+      } catch (e) {
+        this.#logger?.warn?.({ subject: reg.subject, err: e }, 'bus.close: unsubscribe failed (continuing)')
+      }
+    }
+    await this.#driver.close()
+  }
+
+  /**
+   * persist 요청을 driver 능력에 맞춰 해석 — nats 만 영속 지원. 그 외 driver 면 1회 경고 후 비영속.
+   * @param {boolean | undefined} requested @returns {boolean}
+   */
+  #resolvePersist(requested) {
+    const want = requested ?? this.#defaults.defaultPersist
+    if (want && this.#driver.name !== 'nats') {
+      if (!this.#persistWarned) {
+        this.#persistWarned = true
+        this.#logger?.warn?.({ driver: this.#driver.name }, `bus: persist:true requires the nats driver — '${this.#driver.name}' delivers non-persistently. Use NATS for durable messaging.`)
+      }
+      return false
+    }
+    return want
+  }
+
+  /**
+   * driver 가 넘긴 구체 subject 에서 config prefix 를 떼어 사용자 관점(unprefixed)으로 되돌린다.
+   * @param {string | undefined} subject @returns {string | undefined}
+   */
+  #stripPrefix(subject) {
+    if (subject === undefined) return undefined
+    const p = this.#defaults.prefix
+    return p && subject.startsWith(p) ? subject.slice(p.length) : subject
+  }
+}
+
+/**
+ * config 의 bus 섹션에서 manager 기본값을 뽑는다.
+ * @param {{ prefix?: string, defaultPersist?: boolean, requestTimeoutMs?: number }} busConfig
+ * @returns {{ prefix: string, defaultPersist: boolean, requestTimeoutMs: number }}
+ */
+function resolveDefaults(busConfig) {
+  return {
+    prefix: typeof busConfig.prefix === 'string' ? busConfig.prefix : '',
+    defaultPersist: busConfig.defaultPersist === true,
+    requestTimeoutMs: Number.isInteger(busConfig.requestTimeoutMs) ? /** @type {number} */ (busConfig.requestTimeoutMs) : DEFAULT_REQUEST_TIMEOUT_MS,
+  }
+}
+
+/**
+ * 요청 driver(또는 'auto')와 가용 자원으로 driver 를 고른다.
+ * @param {string} requested - 'auto'|'nats'|'cluster'|'memory'.
+ * @param {{ logger?: any, nc: any, isClusterWorker: boolean }} env
+ * @returns {import('./contract.js').BusDriver}
+ * @throws {MegaValidationError} 명시 driver 전제 부재 또는 알 수 없는 driver.
+ */
+function selectDriver(requested, { logger, nc, isClusterWorker }) {
+  switch (requested) {
+    case 'memory':
+      return new MemoryBusDriver()
+    case 'cluster':
+      if (!isClusterWorker) {
+        throw new MegaValidationError('bus.driver_unavailable', "bus.driver='cluster' requires running as a cluster worker (mega start --cluster=N). Use 'auto' or 'memory' for single-process.", { details: { requested } })
+      }
+      return new ClusterBusDriver()
+    case 'nats':
+      if (!nc) {
+        throw new MegaValidationError('bus.driver_unavailable', "bus.driver='nats' requires a NATS bus adapter — set config bus.nats to a buses alias.", { details: { requested } })
+      }
+      return new NatsBusDriver({ nc })
+    case 'auto': {
+      if (nc) {
+        logger?.debug?.({ driver: 'nats' }, 'bus: auto-selected nats driver')
+        return new NatsBusDriver({ nc })
+      }
+      if (isClusterWorker) {
+        logger?.warn?.('bus: auto-selected cluster driver (no NATS) — delivery is single-node only, NOT across nodes. Use NATS for true distributed messaging.')
+        return new ClusterBusDriver()
+      }
+      logger?.warn?.('bus: auto-selected memory driver (no NATS, no cluster) — single-process only, NOT distributed. Use NATS (or cluster) in production.')
+      return new MemoryBusDriver()
+    }
+    default:
+      throw new MegaValidationError('bus.invalid_driver', `unknown bus.driver '${requested}'. Use 'auto' | 'nats' | 'cluster' | 'memory'.`, { details: { requested } })
+  }
+}
+
+/**
+ * 메시지 버스 manager 를 만든다 — driver 자동 폴백 포함. boot 가 1회 호출해 `ctx.bus` 에 부착한다.
+ * @param {{ driver?: string, nats?: string, prefix?: string, defaultPersist?: boolean, requestTimeoutMs?: number }} [busConfig]
+ * @param {{ logger?: any, nc?: any, isClusterWorker?: boolean }} [deps] - `nc` boot 가 bus 어댑터에서 빌린 NatsConnection(없으면 null).
+ * @returns {BusManager}
+ */
+export function createBusManager(busConfig = {}, deps = {}) {
+  const { logger, nc = null, isClusterWorker = false } = deps
+  const requested = busConfig.driver ?? 'auto'
+  const driver = selectDriver(requested, { logger, nc, isClusterWorker })
+  const manager = new BusManager(driver, { defaults: resolveDefaults(busConfig), logger })
+  logger?.debug?.({ requested, selected: driver.name }, 'bus: manager created')
+  return manager
+}
+
+/**
+ * `ctx.bus` 콜러블에 사용자 API 메서드를 얹는다 — `ctx.bus(alias)`(기존)와 `ctx.bus.emit(...)`(신규) 공존.
+ * @param {Function & Record<string, any>} busAccessor - `(alias) => MegaBusAdapter` 콜러블(ctx-builder 산출).
+ * @param {BusManager} manager @returns {Function & Record<string, any>} 같은 accessor(체이닝).
+ */
+export function attachBusApi(busAccessor, manager) {
+  busAccessor.emit = manager.emit.bind(manager)
+  busAccessor.on = manager.on.bind(manager)
+  busAccessor.off = manager.off.bind(manager)
+  busAccessor.request = manager.request.bind(manager)
+  busAccessor.with = manager.with.bind(manager)
+  busAccessor.stats = manager.stats.bind(manager)
+  return busAccessor
+}