mega-framework 0.1.9 → 0.1.11

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

package/src/core/config-validator.js

@@ -11,7 +11,7 @@
  * @module core/config-validator
  */
 import { MegaConfigError } from '../errors/config-error.js'
-import { GLOBAL_ONLY_KEYS, APP_ONLY_KEYS, SHARED_REFERENCE_KEYS } from './scope-registry.js'
+import { GLOBAL_ONLY_KEYS, APP_ONLY_KEYS, SHARED_REFERENCE_KEYS, DUAL_SCOPE_KEYS } from './scope-registry.js'
 import { checkCompressionConfig } from './ws-compression.js'
 
 /**
@@ -81,6 +81,16 @@ export function validateGlobalConfig(globalConfig) {
     validateWsClusterConfig(globalConfig.wsCluster, globalConfig.services?.buses)
   }
 
+  // 4c) lock 검증 (ADR-226) — 분산 락 driver 자동폴백 + 기본 옵션. 잘못된 설정은 부팅 시 fail-fast.
+  if (globalConfig.lock !== undefined) {
+    validateLockConfig(globalConfig.lock, globalConfig.services?.caches)
+  }
+
+  // 4d) bus 검증 (ADR-227) — 메시지 버스 driver 자동폴백 + 기본 옵션. 잘못된 설정은 부팅 시 fail-fast.
+  if (globalConfig.bus !== undefined) {
+    validateBusConfig(globalConfig.bus, globalConfig.services?.buses)
+  }
+
   // 5) jobs / schedules / workers 명시 등록 배열 검증 (M-2 + ADR-124 / 04-data-models §1.1).
   //    GLOBAL_ONLY_KEYS 에 키만 등록돼 있고 shape 검증이 없어, `jobs: SendEmailJob`(배열 잊음)이나
   //    원소가 클래스 아닌 값이면 흡수 로직이 silent drop 했다. 부팅 시 fail-fast 로 드러낸다.
@@ -212,6 +222,103 @@ function validateWsClusterConfig(wsCluster, buses) {
   }
 }
 
+/** lock.driver 허용값 (ADR-226). */
+const LOCK_DRIVERS = Object.freeze(['auto', 'redis', 'cluster', 'memory'])
+
+/**
+ * `lock` config 검증 (ADR-226). 분산 락 manager 자동배선의 트리거라 잘못된 설정을 부팅 시 fail-fast 한다.
+ *  (1) object 여야 한다.
+ *  (2) `driver` 가 있으면 'auto'|'redis'|'cluster'|'memory' 중 하나.
+ *  (3) `ttl`/`waitMs` 가 있으면 음 아닌 정수(ttl 은 양의 정수, waitMs 는 0 이상).
+ *  (4) `fifo` 가 있으면 boolean.
+ *  (5) `cache` 가 있으면 string + `services.caches` 에 선언된 키(redis driver 가 빌릴 cache alias).
+ *
+ * @param {any} lock - globalConfig.lock.
+ * @param {Record<string, any>|undefined} caches - globalConfig.services.caches.
+ * @throws {MegaConfigError} 위 위반 시.
+ */
+function validateLockConfig(lock, caches) {
+  if (typeof lock !== 'object' || lock === null || Array.isArray(lock)) {
+    throw new MegaConfigError('config.lock_invalid', 'lock must be an object ({ driver?, ttl?, waitMs?, fifo?, cache? }).', {
+      details: { type: Array.isArray(lock) ? 'array' : typeof lock },
+    })
+  }
+  if (lock.driver !== undefined && !LOCK_DRIVERS.includes(lock.driver)) {
+    throw new MegaConfigError('config.lock_driver_invalid', `lock.driver must be one of [${LOCK_DRIVERS.join(', ')}], got '${lock.driver}'.`, {
+      details: { driver: lock.driver },
+    })
+  }
+  if (lock.ttl !== undefined && (!Number.isInteger(lock.ttl) || lock.ttl <= 0)) {
+    throw new MegaConfigError('config.lock_ttl_invalid', 'lock.ttl must be a positive integer (ms).', { details: { ttl: lock.ttl } })
+  }
+  if (lock.waitMs !== undefined && (!Number.isInteger(lock.waitMs) || lock.waitMs < 0)) {
+    throw new MegaConfigError('config.lock_waitms_invalid', 'lock.waitMs must be an integer >= 0 (ms, 0 = no wait).', { details: { waitMs: lock.waitMs } })
+  }
+  if (lock.fifo !== undefined && typeof lock.fifo !== 'boolean') {
+    throw new MegaConfigError('config.lock_fifo_invalid', 'lock.fifo must be a boolean.', { details: { fifo: lock.fifo } })
+  }
+  if (lock.cache !== undefined) {
+    if (typeof lock.cache !== 'string' || lock.cache.length === 0) {
+      throw new MegaConfigError('config.lock_cache_invalid', 'lock.cache must be a non-empty string (a global services.caches key).', { details: { cache: lock.cache } })
+    }
+    if (!caches?.[lock.cache]) {
+      throw new MegaConfigError(
+        'config.lock_cache_not_found',
+        `lock.cache '${lock.cache}' is not defined in services.caches. Declared: [${Object.keys(caches ?? {}).join(', ') || '(none)'}].`,
+        { details: { cache: lock.cache, declared: Object.keys(caches ?? {}) } },
+      )
+    }
+  }
+}
+
+/** bus.driver 허용값 (ADR-227). */
+const BUS_DRIVERS = Object.freeze(['auto', 'nats', 'cluster', 'memory'])
+
+/**
+ * `bus` config 검증 (ADR-227). 메시지 버스 manager 자동배선의 트리거라 잘못된 설정을 부팅 시 fail-fast 한다.
+ *  (1) object 여야 한다.
+ *  (2) `driver` 가 있으면 'auto'|'nats'|'cluster'|'memory' 중 하나.
+ *  (3) `prefix` 가 있으면 string.
+ *  (4) `defaultPersist` 가 있으면 boolean.
+ *  (5) `requestTimeoutMs` 가 있으면 양의 정수.
+ *  (6) `nats` 가 있으면 string + `services.buses` 에 선언된 키(nats driver 가 빌릴 버스 alias).
+ *
+ * @param {any} bus - globalConfig.bus.
+ * @param {Record<string, any>|undefined} buses - globalConfig.services.buses.
+ * @throws {MegaConfigError} 위 위반 시.
+ */
+function validateBusConfig(bus, buses) {
+  if (typeof bus !== 'object' || bus === null || Array.isArray(bus)) {
+    throw new MegaConfigError('config.bus_invalid', 'bus must be an object ({ driver?, nats?, prefix?, defaultPersist?, requestTimeoutMs? }).', {
+      details: { type: Array.isArray(bus) ? 'array' : typeof bus },
+    })
+  }
+  if (bus.driver !== undefined && !BUS_DRIVERS.includes(bus.driver)) {
+    throw new MegaConfigError('config.bus_driver_invalid', `bus.driver must be one of [${BUS_DRIVERS.join(', ')}], got '${bus.driver}'.`, { details: { driver: bus.driver } })
+  }
+  if (bus.prefix !== undefined && typeof bus.prefix !== 'string') {
+    throw new MegaConfigError('config.bus_prefix_invalid', 'bus.prefix must be a string (subject namespace, e.g. "app.").', { details: { prefix: bus.prefix } })
+  }
+  if (bus.defaultPersist !== undefined && typeof bus.defaultPersist !== 'boolean') {
+    throw new MegaConfigError('config.bus_persist_invalid', 'bus.defaultPersist must be a boolean.', { details: { defaultPersist: bus.defaultPersist } })
+  }
+  if (bus.requestTimeoutMs !== undefined && (!Number.isInteger(bus.requestTimeoutMs) || bus.requestTimeoutMs <= 0)) {
+    throw new MegaConfigError('config.bus_timeout_invalid', 'bus.requestTimeoutMs must be a positive integer (ms).', { details: { requestTimeoutMs: bus.requestTimeoutMs } })
+  }
+  if (bus.nats !== undefined) {
+    if (typeof bus.nats !== 'string' || bus.nats.length === 0) {
+      throw new MegaConfigError('config.bus_nats_invalid', 'bus.nats must be a non-empty string (a global services.buses key).', { details: { nats: bus.nats } })
+    }
+    if (!buses?.[bus.nats]) {
+      throw new MegaConfigError(
+        'config.bus_nats_not_found',
+        `bus.nats '${bus.nats}' is not defined in services.buses. Declared: [${Object.keys(buses ?? {}).join(', ') || '(none)'}].`,
+        { details: { nats: bus.nats, declared: Object.keys(buses ?? {}) } },
+      )
+    }
+  }
+}
+
 /**
  * `jobs`/`schedules`/`workers` 같은 "클래스(함수) 배열" config 키를 검증한다 (M-2/ADR-124). 미정의면
  * 통과(선택 키). 정의됐으면 (1) 배열이어야 하고 (2) 모든 원소가 함수(클래스)여야 한다 — 위반 시 부팅 fail-fast.
@@ -260,6 +367,7 @@ export function validateAppConfig(appConfig, expectedFolderName, globalConfig) {
   // 1) 알 수 없는 키 + 잘못된 스코프
   for (const key of Object.keys(appConfig)) {
     if (APP_ONLY_KEYS.includes(key)) continue
+    if (DUAL_SCOPE_KEYS.includes(key)) continue // lock/bus 는 글로벌·앱 양쪽 허용(ADR-229) — 아래서 shape 검증.
     if (GLOBAL_ONLY_KEYS.includes(key)) {
       throw new MegaConfigError(
         'config.wrong_scope',
@@ -290,6 +398,15 @@ export function validateAppConfig(appConfig, expectedFolderName, globalConfig) {
     )
   }
 
+  // 2a) 앱별 lock/bus(ADR-229) — 글로벌과 같은 shape 규칙. cache/nats 는 **글로벌 services** 의 키를 참조한다
+  //     (services 는 글로벌 정의라 앱 lock.cache/bus.nats 도 globalConfig.services 를 본다).
+  if (appConfig.lock !== undefined) {
+    validateLockConfig(appConfig.lock, globalConfig?.services?.caches)
+  }
+  if (appConfig.bus !== undefined) {
+    validateBusConfig(appConfig.bus, globalConfig?.services?.buses)
+  }
+
   // 2b) bridgeHub(WS Hub 브릿지, ADR-065/176) 검증 + wsCluster 상호배타.
   //     클러스터 전송은 앱당 **하나**다 — bridgeHub(WS Hub) 와 global wsCluster(NATS) 를 동시에 쓰면
   //     app.broadcast 가 양쪽으로 나가 이중 전파된다. 부팅 시 fail-fast 로 막는다(boot 가 둘 중 하나만 배선).

package/src/core/ctx-builder.js

@@ -18,6 +18,8 @@
  */
 import { MegaConfigError } from '../errors/config-error.js'
 import * as AdapterManager from '../adapters/adapter-manager.js'
+import { getLockManager, attachLockApi } from './lock/index.js'
+import { getBusManager, attachBusApi } from './bus/index.js'
 import { contextProxy as workersContext, PROXY_PROTOCOL_KEYS } from './workers-manager.js'
 import { tracer as megaTracer } from '../lib/mega-tracing.js'
 
@@ -160,7 +162,18 @@ export function buildAdapterAccessors(aliasMaps = {}, appName = '(unknown)') {
       return AdapterManager.get(domain, globalKey) // 별명은 있으나 인스턴스 미등록이면 여기서 throw
     }
   }
-  return { db: make('db'), cache: make('cache'), bus: make('bus'), lock: make('lock') }
+  // lock accessor 는 종전대로 `(alias) => MegaLockAdapter` 콜러블이되, 분산 락 manager 가 설정돼 있으면
+  // 거기에 `.with/.acquire/.tryAcquire/...` 사용자 API 를 얹는다(ADR-226). `ctx.lock(alias)`(스케줄러 등
+  // 기존 사용처)와 `ctx.lock.with(...)`(신규)이 한 콜러블에 공존한다.
+  const lock = make('lock')
+  const manager = getLockManager()
+  if (manager) attachLockApi(/** @type {any} */ (lock), manager)
+  // bus accessor 도 동일 — `ctx.bus(alias)`(설정형 어댑터)에 `.emit/.on/.off/.request/.with` 메시지 버스
+  // 사용자 API 를 얹는다(ADR-227). 콜러블 공존(락 ADR-226 과 같은 패턴).
+  const bus = make('bus')
+  const busManager = getBusManager()
+  if (busManager) attachBusApi(/** @type {any} */ (bus), busManager)
+  return { db: make('db'), cache: make('cache'), bus, lock }
 }
 
 /**

package/src/core/index.js

@@ -9,6 +9,8 @@ export { MegaCluster } from './mega-cluster.js'
 export { loadRoutes } from './routes-loader.js'
 // 중앙 부팅 orchestrator (ADR-123)
 export { bootApp, buildBootContext } from './boot.js'
+// ctx 없는 영역(백그라운드·외부 콜백·테스트)의 booted MegaApp 접근점 (ADR-228)
+export { getApp, hasApp } from './app-registry.js'
 export { wrapEnvelope, errorEnvelope, synthesizeEnvelopeResponseSchema, ENVELOPE_MARK } from './envelope.js'
 // HTTP 라이프사이클 Pipeline — before/transform/after 합성 정본 (ADR-185)
 export { buildHttpPipeline, wrapPreHandler, composeTransform, composeAfter } from './pipeline.js'