mega-framework 0.1.10 → 0.1.13

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
+}

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

@@ -0,0 +1,103 @@
+// @ts-check
+/**
+ * MemoryBusDriver — 단일 프로세스 in-memory 메시지 버스 driver (ADR-227).
+ *
+ * Node 이벤트루프 위의 구독 목록 fan-out. **단일 프로세스 안에서만** 전달하므로 멀티 프로세스·멀티 노드에는
+ * 닿지 않는다 — factory 가 memory 를 고를 때 부팅 경고를 낸다(`src/core/bus/index.js`). 개발/테스트, 또는
+ * 분산이 불필요한 단일 인스턴스용. wildcard 는 {@link matchSubject} 로 자체 매칭한다.
+ *
+ * driver 계약은 {@link import('./contract.js').BusDriver} 를 따른다(typedef — 런타임 implements 아님).
+ * 핸들러 호출은 manager 가 넘긴 wrapper 라 **절대 reject 하지 않는다**(사용자 에러는 manager 가 잡아 로깅) —
+ * 그래서 driver 는 `void handler(...)` 로 안전하게 던지고 fan-out 을 막지 않는다.
+ *
+ * @module core/bus/memory-bus
+ */
+import { matchSubject } from './contract.js'
+import { MegaInternalError } from '../../errors/http-errors.js'
+
+/**
+ * @typedef {Object} MemorySub - 구독 레코드.
+ * @property {string} pattern @property {(envelope: import('./contract.js').BusEnvelope, reply?: import('./contract.js').ReplyFn, subject?: string) => any} handler
+ * @property {boolean} ordered @property {Promise<void>} tail - ordered 직렬화용 꼬리 프라미스.
+ */
+
+export class MemoryBusDriver {
+  /** @type {Map<number, MemorySub>} 구독 id → 레코드. */ #subs = new Map()
+  /** @type {number} 구독 id 시퀀스. */ #seq = 0
+
+  /** @type {'memory'} */
+  get name() {
+    return 'memory'
+  }
+
+  /** 매칭 구독에 fan-out. memory 는 persist 무시(opts 는 계약 정합용). @param {string} subject @param {import('./contract.js').BusEnvelope} envelope @param {{ persist?: boolean }} [_opts] @returns {Promise<void>} */
+  async publish(subject, envelope, _opts = {}) {
+    for (const sub of this.#subs.values()) {
+      if (matchSubject(sub.pattern, subject)) this.#deliver(sub, envelope, subject)
+    }
+  }
+
+  /** 구독 등록. @param {string} pattern @param {MemorySub['handler']} handler @param {{ ordered?: boolean }} opts @returns {Promise<import('./contract.js').Subscription>} */
+  async subscribe(pattern, handler, { ordered = false } = {}) {
+    const id = ++this.#seq
+    this.#subs.set(id, { pattern, handler, ordered, tail: Promise.resolve() })
+    return {
+      unsubscribe: async () => {
+        this.#subs.delete(id)
+      },
+    }
+  }
+
+  /**
+   * req/reply — 매칭 핸들러에 replyFn 을 주고 첫 응답을 반환. 응답자 없으면 no_responders, 시한 초과면 timeout.
+   * @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 matches = [...this.#subs.values()].filter((s) => matchSubject(s.pattern, subject))
+    if (matches.length === 0) {
+      throw new MegaInternalError('bus.no_responders', `bus request("${subject}"): no subscriber matches the subject.`, { details: { subject } })
+    }
+    return new Promise((resolve, reject) => {
+      let settled = false
+      const timer = setTimeout(() => {
+        if (settled) return
+        settled = true
+        reject(new MegaInternalError('bus.request_timeout', `bus request("${subject}") timed out after ${timeout}ms.`, { details: { subject, timeout } }))
+      }, timeout)
+      timer.unref?.()
+      /** @type {import('./contract.js').ReplyFn} */
+      const reply = (replyEnv) => {
+        if (settled) return // 첫 응답만 채택(NATS request 의미).
+        settled = true
+        clearTimeout(timer)
+        resolve(replyEnv)
+      }
+      for (const sub of matches) this.#deliver(sub, envelope, subject, reply)
+    })
+  }
+
+  /** @returns {Promise<{ driver: string, subscriptions: number }>} */
+  async stats() {
+    return { driver: 'memory', subscriptions: this.#subs.size }
+  }
+
+  /** 정리 — 구독 비움. @returns {Promise<void>} */
+  async close() {
+    this.#subs.clear()
+  }
+
+  /**
+   * 한 구독에 전달 — ordered 면 꼬리 프라미스에 직렬 연결, 아니면 즉시 호출. handler 는 reject 안 하므로 안전.
+   * `subject` 는 매칭된 **구체** subject(wildcard 가 아닌 실제 발행 subject) — 핸들러가 어디로 왔는지 안다.
+   * @param {MemorySub} sub @param {import('./contract.js').BusEnvelope} envelope @param {string} subject @param {import('./contract.js').ReplyFn} [reply]
+   * @returns {void}
+   */
+  #deliver(sub, envelope, subject, reply) {
+    if (sub.ordered) {
+      sub.tail = sub.tail.then(() => sub.handler(envelope, reply, subject))
+    } else {
+      void sub.handler(envelope, reply, subject)
+    }
+  }
+}

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

@@ -0,0 +1,203 @@
+// @ts-check
+/**
+ * NatsBusDriver — NATS 기반 **분산** 메시지 버스 driver (ADR-227).
+ *
+ * 멀티 프로세스·멀티 노드에 닿는 디폴트 driver. NATS core pub/sub(실시간 fan-out·비영속) 위에서 동작하고,
+ * `persist:true` 옵션이면 JetStream(영속 저장 + 재시작 후 재전달)으로 전환한다. NATS 가 wildcard·request/reply 를
+ * native 로 지원하므로 그대로 위임한다(매처 자체 구현 불필요). nats v3(`@nats-io/*`, ADR-225) 위에서 돈다.
+ *
+ * NATS 연결은 **bus 어댑터가 소유한 것을 빌린다**(`config.bus.nats` = 버스 어댑터 alias). 별도 연결을 만들지
+ * 않으므로 클러스터 broadcast(ADR-176)·잡 큐(ADR-119)와 **같은 NatsConnection** 을 공유한다 — close 에서 nc 를
+ * 닫지 않는다(생애주기는 어댑터 소유).
+ *
+ * # 영속(persist) — 비영속과 subject 공간 분리
+ *   JetStream 스트림은 설정된 subject 로 **들어오는 모든 메시지**를 저장하므로, core(비영속) 메시지까지 스트림에
+ *   잡히면 이중 저장된다. 이를 막으려 영속 메시지는 내부 prefix `_mbusp.` 를 붙인 별도 subject 로 보낸다 —
+ *   영속 emit↔on 은 이 공간에서 만나고, core 와 섞이지 않는다. 스트림 1개(`MEGABUS_PERSIST`)가 `_mbusp.>` 를
+ *   잡고, 영속 구독은 그 위에 ephemeral consumer(filter_subject=패턴)를 만든다.
+ *
+ * driver 계약은 {@link import('./contract.js').BusDriver} 를 따른다(typedef — 런타임 implements 아님).
+ * @module core/bus/nats-bus
+ */
+import { encodeJson, decodeJson } from '../../adapters/nats-codec.js'
+import { MegaInternalError } from '../../errors/http-errors.js'
+
+/** 영속 메시지 subject 내부 prefix(core 와 분리). */
+const PERSIST_PREFIX = '_mbusp.'
+/** 영속 스트림 이름(공유 — subject prefix 로 앱 격리). */
+const PERSIST_STREAM = 'MEGABUS_PERSIST'
+
+export class NatsBusDriver {
+  /** @type {any} 빌린 NatsConnection(bus 어댑터 소유). */ #nc
+  /** @type {any} @nats-io/jetstream 모듈(lazy). */ #js = null
+  /** @type {(ms: number) => number} nanos(ms→ns) — @nats-io/nats-core(lazy). */ #nanos = (ms) => ms
+  /** @type {any} JetStreamClient(lazy). */ #jsc = null
+  /** @type {any} JetStreamManager(lazy). */ #jsm = null
+  /** @type {Promise<void> | null} JetStream 초기화 직렬화. */ #jsInit = null
+  /** @type {boolean} 영속 스트림 보장 완료. */ #streamEnsured = false
+  /** @type {Set<{ stop: () => void }>} 활성 영속 consumer(close 에서 정리). */ #persistSubs = new Set()
+
+  /** @param {{ nc: any }} opts - `nc` 빌린 NatsConnection(`busAdapter.native`). */
+  constructor({ nc }) {
+    this.#nc = nc
+  }
+
+  /** @type {'nats'} */
+  get name() {
+    return 'nats'
+  }
+
+  /**
+   * 발행 — persist 면 JetStream(영속), 아니면 core pub/sub(비영속).
+   * @param {string} subject @param {import('./contract.js').BusEnvelope} envelope @param {{ persist?: boolean }} opts
+   * @returns {Promise<void>}
+   */
+  async publish(subject, envelope, { persist = false } = {}) {
+    if (!persist) {
+      this.#nc.publish(subject, encodeJson(envelope))
+      return
+    }
+    await this.#ensureJetStream()
+    await this.#jsc.publish(`${PERSIST_PREFIX}${subject}`, encodeJson(envelope))
+  }
+
+  /**
+   * 구독 — persist 면 JetStream ephemeral consumer, 아니면 core 구독. core 는 wildcard·reply 를 native 지원.
+   * @param {string} pattern @param {(envelope: import('./contract.js').BusEnvelope, reply?: import('./contract.js').ReplyFn, subject?: string) => any} handler
+   * @param {{ persist?: boolean, ordered?: boolean }} opts @returns {Promise<import('./contract.js').Subscription>}
+   */
+  async subscribe(pattern, handler, { persist = false, ordered = false } = {}) {
+    if (persist) return this.#subscribePersistent(pattern, handler, ordered)
+    let tail = Promise.resolve()
+    const sub = this.#nc.subscribe(pattern, {
+      callback: (/** @type {any} */ err, /** @type {any} */ msg) => {
+        if (err) return // 구독 에러(드물게)는 NATS 가 별도 보고 — 콜백 인자로 온 err 는 무시 가능(P4: 비치명적).
+        const envelope = decodeJson(msg.data)
+        // request 로 온 메시지면(reply subject 존재) replyFn 제공. msg.subject = 매칭된 구체 subject(NATS native).
+        const reply = msg.reply ? (/** @type {any} */ env) => this.#nc.publish(msg.reply, encodeJson(env)) : undefined
+        if (ordered) tail = tail.then(() => handler(envelope, reply, msg.subject))
+        else void handler(envelope, reply, msg.subject)
+      },
+    })
+    return {
+      unsubscribe: async () => {
+        sub.unsubscribe()
+      },
+    }
+  }
+
+  /**
+   * req/reply — NATS native request. 첫 응답 envelope 반환. v3 에러 클래스로 timeout/no-responders 판별.
+   * @param {string} subject @param {import('./contract.js').BusEnvelope} envelope @param {{ timeout: number }} opts
+   * @returns {Promise<import('./contract.js').BusEnvelope>}
+   */
+  async request(subject, envelope, { timeout }) {
+    try {
+      const reply = await this.#nc.request(subject, encodeJson(envelope), { timeout })
+      return decodeJson(reply.data)
+    } catch (err) {
+      // v3(ADR-225): timeout/무응답이 에러 클래스. cold path 라 catch 에서 lazy import(모듈은 이미 로드 — 비용 0).
+      const { TimeoutError, NoRespondersError, RequestError } = await import('@nats-io/nats-core')
+      if (err instanceof TimeoutError) {
+        throw new MegaInternalError('bus.request_timeout', `bus request("${subject}") timed out after ${timeout}ms.`, { details: { subject, timeout }, cause: err })
+      }
+      if (err instanceof NoRespondersError || (err instanceof RequestError && err.isNoResponders())) {
+        throw new MegaInternalError('bus.no_responders', `bus request("${subject}"): no responders subscribed.`, { details: { subject }, cause: err })
+      }
+      throw err
+    }
+  }
+
+  /** @returns {Promise<{ driver: string, subscriptions: number }>} 영속 구독 수(core 구독은 NATS 측 관리라 미집계). */
+  async stats() {
+    return { driver: 'nats', subscriptions: this.#persistSubs.size }
+  }
+
+  /** 정리 — 영속 consumer 정지. nc 는 어댑터 소유라 닫지 않는다. @returns {Promise<void>} */
+  async close() {
+    for (const sub of this.#persistSubs) sub.stop()
+    this.#persistSubs.clear()
+  }
+
+  /**
+   * 영속 구독 — 영속 스트림 위에 ephemeral consumer 를 만들고 consume 루프로 배달 + ack.
+   * @param {string} pattern @param {Function} handler @param {boolean} ordered
+   * @returns {Promise<import('./contract.js').Subscription>}
+   */
+  async #subscribePersistent(pattern, handler, ordered) {
+    await this.#ensureJetStream()
+    const filter = `${PERSIST_PREFIX}${pattern}`
+    // ephemeral consumer(durable_name 없음 — inactive 시 서버가 자동 삭제). filter 로 패턴 한정.
+    const ci = await this.#jsm.consumers.add(PERSIST_STREAM, {
+      ack_policy: this.#js.AckPolicy.Explicit,
+      filter_subject: filter,
+      inactive_threshold: this.#nanos(30_000), // 끊긴 consumer 30s 후 서버 정리.
+    })
+    const consumer = await this.#jsc.consumers.get(PERSIST_STREAM, ci.name)
+    const messages = await consumer.consume()
+    let stopped = false
+    let tail = Promise.resolve()
+    // 배달 루프 — 별도 비동기. envelope 디코드 → 핸들러 → ack. 영속은 request/reply 미지원(reply 없음).
+    ;(async () => {
+      for await (const msg of messages) {
+        if (stopped) break
+        const envelope = decodeJson(msg.data)
+        // 저장 subject 는 내부 persist prefix 가 붙어 있으니 떼고 넘긴다 → manager 는 user prefix 만 안다.
+        const subject = msg.subject.startsWith(PERSIST_PREFIX) ? msg.subject.slice(PERSIST_PREFIX.length) : msg.subject
+        if (ordered) tail = tail.then(() => handler(envelope, undefined, subject))
+        else void handler(envelope, undefined, subject)
+        msg.ack()
+      }
+    })().catch(() => {
+      // consume 루프 종료(stop/연결단절)는 정상 흐름 — unsubscribe/close 가 stop 한다. 비치명적.
+    })
+    const entry = {
+      stop: () => {
+        stopped = true
+        messages.stop()
+      },
+    }
+    this.#persistSubs.add(entry)
+    return {
+      unsubscribe: async () => {
+        entry.stop()
+        this.#persistSubs.delete(entry)
+        try {
+          await this.#jsm.consumers.delete(PERSIST_STREAM, ci.name)
+        } catch (e) {
+          // 이미 자동 삭제(inactive_threshold)됐을 수 있음 — not-found 는 무해. 그 외는 전파.
+          if (!(e instanceof this.#js.JetStreamApiError && e.code === this.#js.JetStreamApiCodes.ConsumerNotFound)) throw e
+        }
+      },
+    }
+  }
+
+  /** JetStream client/manager lazy 초기화 + 영속 스트림 멱등 보장(최초 persist 사용 시 1회). @returns {Promise<void>} */
+  async #ensureJetStream() {
+    if (this.#streamEnsured) return
+    if (this.#jsInit) return this.#jsInit
+    this.#jsInit = (async () => {
+      // nanos 는 @nats-io/nats-core, JetStream client/manager·enum 은 @nats-io/jetstream(ADR-225). 병렬 lazy import.
+      const [js, core] = await Promise.all([import('@nats-io/jetstream'), import('@nats-io/nats-core')])
+      this.#js = js
+      this.#nanos = core.nanos
+      this.#jsc = js.jetstream(this.#nc)
+      this.#jsm = await js.jetstreamManager(this.#nc)
+      try {
+        await this.#jsm.streams.info(PERSIST_STREAM)
+      } catch (e) {
+        if (e instanceof js.JetStreamApiError && e.code === js.JetStreamApiCodes.StreamNotFound) {
+          await this.#jsm.streams.add({ name: PERSIST_STREAM, subjects: [`${PERSIST_PREFIX}>`], retention: js.RetentionPolicy.Limits, storage: js.StorageType.File })
+        } else {
+          throw e
+        }
+      }
+      this.#streamEnsured = true
+    })()
+    try {
+      await this.#jsInit
+    } finally {
+      this.#jsInit = null
+    }
+  }
+}