mega-framework 0.1.10 → 0.1.13

package/src/core/boot.js

@@ -46,6 +46,9 @@ import { MegaShutdown } from '../lib/mega-shutdown.js'
 import { buildLogger } from '../lib/mega-logger.js'
 import { buildFromGlobalConfig, connectAll, get as getAdapter, entries as adapterEntries } from '../adapters/adapter-manager.js'
 import { buildWorkers, startAll as startWorkers, contextProxy as workersContext } from './workers-manager.js'
+import { createLockManager, setLockManager, attachLockApi } from './lock/index.js'
+import { createBusManager, setBusManager, attachBusApi } from './bus/index.js'
+import { setApp, _resetApps } from './app-registry.js'
 import { MegaWsCluster } from './ws-cluster.js'
 import { MegaWsRedisRoster } from './ws-roster.js'
 import * as MegaMetrics from '../lib/mega-metrics.js'
@@ -95,6 +98,33 @@ function composeAspConfig(globalAsp, appAsp) {
   return { ...appAsp, ...(masterSecret ? { masterSecret } : {}) }
 }
 
+/**
+ * lock redis driver 가 빌릴 raw ioredis 를 cache 어댑터에서 빌린다(eval/duplicate 보유 검증). 글로벌·앱별 lock
+ * 스테이지가 공유한다. 없거나 raw redis 가 아니면 null(auto 면 폴백, 명시 redis 면 factory 가 fail-fast).
+ * @param {string | undefined} cacheKey - lock.cache(글로벌 services.caches 키). @param {any} [logger]
+ * @returns {any | null}
+ */
+function borrowLockRedis(cacheKey, logger) {
+  if (!cacheKey) return null
+  const native = /** @type {any} */ (getAdapter('cache', cacheKey))?.native
+  if (native && typeof native.eval === 'function' && typeof native.duplicate === 'function') return native
+  logger?.warn?.({ cache: cacheKey }, 'boot.lock: configured cache adapter has no raw ioredis (eval/duplicate) — redis lock driver unavailable')
+  return null
+}
+
+/**
+ * bus nats driver 가 빌릴 raw NatsConnection 을 bus 어댑터에서 빌린다(publish/subscribe/request 보유 검증).
+ * @param {string | undefined} natsKey - bus.nats(글로벌 services.buses 키). @param {any} [logger]
+ * @returns {any | null}
+ */
+function borrowBusNc(natsKey, logger) {
+  if (!natsKey) return null
+  const native = /** @type {any} */ (getAdapter('bus', natsKey))?.native
+  if (native && typeof native.publish === 'function' && typeof native.subscribe === 'function' && typeof native.request === 'function') return native
+  logger?.warn?.({ nats: natsKey }, 'boot.bus: configured bus adapter has no NATS native (publish/subscribe/request) — nats bus driver unavailable')
+  return null
+}
+
 /**
  * boot/CLI 컨텍스트 — `db/cache/bus/lock` 을 글로벌 키로 직접 조회하고, `workers` 는 `static name` 으로
  * lookup 한다(앱 별명 변환 없음 — 둘 다 글로벌 자원). worker/scheduler CLI 도 같은 형태를 재사용한다
@@ -222,6 +252,50 @@ const PREPARE_STEPS = [
       st.logger?.debug?.('boot.adapters connected')
     },
   },
+  {
+    name: 'lock',
+    needs: ['global', 'host'],
+    run: (st) => {
+      // 분산 락 manager 자동배선 (ADR-226) — `ctx.lock.with/.acquire/...` 사용자 API. driver 자동 폴백:
+      //   redis cache 어댑터(config `lock.cache`) → redis(진짜 분산) / cluster 워커 → cluster(단일 노드) /
+      //   둘 다 없음 → memory(분산 미보장, 경고). 명시 driver 의 전제 부재는 factory 가 fail-fast(P7).
+      // adapters 스테이지 이후라 cache 의 raw ioredis(`.native`)가 connect 된 상태다. setLockManager 싱글톤을
+      // ctx-builder 가 읽어 모든 ctx(HTTP·worker·scheduler)의 lock accessor 에 API 를 얹는다.
+      // 글로벌 lock manager — 앱별 lock 설정이 없는 앱의 fallback + worker/scheduler boot ctx(MegaApp 없음)용.
+      // 앱별 분리(ADR-229)는 apps 스테이지가 app.config.lock 이 있을 때만 별도 manager 를 만들어 덮어쓴다.
+      const lockCfg = /** @type {any} */ (st.global).lock ?? {}
+      const manager = createLockManager(lockCfg, { logger: st.logger, redisClient: borrowLockRedis(lockCfg.cache, st.logger), isClusterWorker: nodeCluster.isWorker })
+      setLockManager(manager)
+      // 'app' stage — 어댑터 disconnect 보다 먼저 정리(redis 구독 연결 quit·타이머 해제가 cache 끊기기 전에).
+      MegaShutdown.register('mega-lock', async () => {
+        await manager.close()
+        setLockManager(null)
+      })
+      st.logger?.debug?.({ driver: manager.driverName, configured: lockCfg.driver ?? 'auto' }, 'boot.lock manager ready (ADR-226)')
+    },
+  },
+  {
+    name: 'bus',
+    needs: ['global', 'host'],
+    run: (st) => {
+      // 메시지 버스 manager 자동배선 (ADR-227) — `ctx.bus.emit/.on/.request/...` 사용자 API. driver 자동 폴백:
+      //   NATS bus 어댑터(config `bus.nats`) → nats(진짜 분산) / cluster 워커 → cluster(단일 노드) /
+      //   둘 다 없음 → memory(분산 미보장, 경고). 명시 driver 의 전제 부재는 factory 가 fail-fast(P7).
+      // adapters 스테이지 이후라 NATS 어댑터의 raw NatsConnection(`.native`)이 connect 된 상태다. 새 연결을 만들지
+      // 않고 빌려 쓰므로 클러스터 broadcast(ADR-176)·잡 큐(ADR-119)와 같은 nc 를 공유한다.
+      // 글로벌 bus manager — 앱별 bus 설정이 없는 앱의 fallback + worker/scheduler boot ctx 용. 앱별 분리(ADR-229)는
+      // apps 스테이지가 app.config.bus 가 있을 때만 별도 manager 로 덮어쓴다.
+      const busCfg = /** @type {any} */ (st.global).bus ?? {}
+      const manager = createBusManager(busCfg, { logger: st.logger, nc: borrowBusNc(busCfg.nats, st.logger), isClusterWorker: nodeCluster.isWorker })
+      setBusManager(manager)
+      // 'app' stage — 어댑터 disconnect 보다 먼저 정리(영속 consumer·구독이 nc 끊기기 전에).
+      MegaShutdown.register('mega-bus', async () => {
+        await manager.close()
+        setBusManager(null)
+      })
+      st.logger?.debug?.({ driver: manager.driverName, configured: busCfg.driver ?? 'auto' }, 'boot.bus manager ready (ADR-227)')
+    },
+  },
   {
     name: 'health-auto-checks',
     needs: ['global'],
@@ -492,8 +566,33 @@ const BOOT_STEPS = [
         st.logger?.debug?.({ app: name, filesLoaded }, 'boot.routes loaded')
         st.server.mount(app)
         megaApps.push(app)
+        // ctx 없는 영역의 getApp() 접근점에 등록(ADR-228).
+        setApp(app)
+
+        // 앱별 lock/bus 분리(ADR-229) — app.config.lock/bus 가 있으면 그 앱 전용 manager 를 만들어 이 앱의
+        // adapterAccessors 에 덮어쓴다(ctx.<app>·getApp(name) 둘 다 앱 manager 를 본다). 미지정 앱은 생성자가
+        // 이미 붙인 글로벌 manager 를 그대로 쓴다(중복 연결 없음). 앱 설정은 글로벌과 shallow merge(앱 키 우선).
+        const isWorker = nodeCluster.isWorker
+        const appLockCfg = /** @type {any} */ (config).lock
+        if (appLockCfg) {
+          const merged = { .../** @type {any} */ (st.global).lock, ...appLockCfg }
+          const lockMgr = createLockManager(merged, { logger: st.logger, redisClient: borrowLockRedis(merged.cache, st.logger), isClusterWorker: isWorker })
+          attachLockApi(/** @type {any} */ (app.adapterAccessors.lock), lockMgr)
+          MegaShutdown.register(`mega-lock:${name}`, async () => lockMgr.close())
+          st.logger?.debug?.({ app: name, driver: lockMgr.driverName }, 'boot.lock app-scoped manager (ADR-229)')
+        }
+        const appBusCfg = /** @type {any} */ (config).bus
+        if (appBusCfg) {
+          const merged = { .../** @type {any} */ (st.global).bus, ...appBusCfg }
+          const busMgr = createBusManager(merged, { logger: st.logger, nc: borrowBusNc(merged.nats, st.logger), isClusterWorker: isWorker })
+          attachBusApi(/** @type {any} */ (app.adapterAccessors.bus), busMgr)
+          MegaShutdown.register(`mega-bus:${name}`, async () => busMgr.close())
+          st.logger?.debug?.({ app: name, driver: busMgr.driverName }, 'boot.bus app-scoped manager (ADR-229)')
+        }
       }
       st.megaApps = megaApps
+      // 재부팅/테스트 격리 — 'app' stage 에서 레지스트리 비움(어댑터 disconnect 와 같은 시점, getApp 가 stale 앱 X).
+      MegaShutdown.register('mega-app-registry', () => _resetApps())
     },
   },
   {

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 없는 잔여 — 토큰 수 일치해야.
+}