mega-framework 0.1.9 → 0.1.11

package/src/adapters/nats-adapter.js

@@ -1,10 +1,14 @@
 // @ts-check
 /**
- * MegaNatsAdapter — NATS 메시지 버스 어댑터 (`nats` 공식 driver 래퍼, ADR-112).
+ * MegaNatsAdapter — NATS 메시지 버스 어댑터 (`@nats-io/*` v3 driver 래퍼, ADR-112/225).
  *
  * **첫 bus 도메인 어댑터**(`MegaBusAdapter` 첫 구체). DB/cache 와 달리 pub/sub·req/reply·
  * queue group 메시징 인터페이스를 구현한다.
  *
+ * # nats v3 (`@nats-io/*`) — v2 `nats` 단일 패키지에서 분리됨 (ADR-225)
+ *   core connect 는 `@nats-io/transport-node`, 타입은 `@nats-io/nats-core`. `JSONCodec()` 팩토리가
+ *   제거돼 본 어댑터는 {@link import('./nats-codec.js')} 의 공유 JSON 코덱을 쓴다.
+ *
  * # 표준 표면 (MegaBusAdapter 상속)
  *   - `_connect()`   — `connect({ servers, ...auth, ...options })` (driver 는 connect 시점 lazy import).
  *                      connect() 자체가 서버 응답까지 기다리므로 별도 ping 불필요(실패 시 throw=검증).
@@ -15,10 +19,10 @@
  *   - `getStats()`   — 베이스 stats + nats 특화(server/연결 stats: inMsgs/outMsgs/inBytes/outBytes).
  *   - `publish/subscribe/request` + `enqueue/process` — 아래 인터페이스.
  *
- * # 직렬화 = JSONCodec
- *   payload 는 NATS wire 에서 `Uint8Array` 다. 본 어댑터는 `JSONCodec` 로 인코드/디코드를 표준화해
- *   사용자는 JS 값을 그대로 publish/subscribe 한다(수신 측에서 같은 값으로 복원). `undefined` payload
- *   는 `null` 로 정규화(JSONCodec 가 undefined 를 인코드하지 못함).
+ * # 직렬화 = 공유 JSON 코덱 (ADR-225 — v3 JSONCodec 제거)
+ *   payload 는 NATS wire 에서 `Uint8Array` 다. 본 어댑터는 {@link import('./nats-codec.js')} 의
+ *   `encodeJson`/`decodeJson` 로 인코드/디코드를 표준화해 사용자는 JS 값을 그대로 publish/subscribe
+ *   한다(수신 측에서 같은 값으로 복원). `undefined` payload 는 `null` 로 정규화(JSON 이 undefined 미표현).
  *
  * # queue (job) 인터페이스 — 단순 publish + queue group (jetstream 미사용, ADR-112)
  *   `enqueue(job, msg)` = 해당 subject 로 **단순 publish**. `process(job, handler)` = **queue group**
@@ -59,6 +63,7 @@
 import { MegaValidationError, MegaInternalError } from '../errors/http-errors.js'
 import { MegaBusAdapter } from './mega-bus-adapter.js'
 import { resolveConnection, assertPlainObject } from './adapter-options.js'
+import { encodeJson, decodeJson } from './nats-codec.js'
 import * as Registry from './registry.js'
 
 /** NATS 기본 클라이언트 포트(discrete 모드에서 port 미지정 시). */
@@ -78,11 +83,9 @@ const DEFAULT_REQUEST_TIMEOUT_MS = 30000
  */
 
 export class MegaNatsAdapter extends MegaBusAdapter {
-  /** @type {import('nats').NatsConnection | null} 연결된 NatsConnection (connect 후에만). */
+  /** @type {import('@nats-io/nats-core').NatsConnection | null} 연결된 NatsConnection (connect 후에만). */
   #nc = null
-  /** @type {import('nats').Codec<any> | null} JSONCodec (connect 시 생성). */
-  #codec = null
-  /** @type {import('nats').ConnectionOptions} _connect 에서 `connect()` 에 넘길 옵션(생성자에서 고정). */
+  /** @type {import('@nats-io/nats-core').ConnectionOptions} _connect 에서 `connect()` 에 넘길 옵션(생성자에서 고정). */
   #connectOptions
 
   /**
@@ -107,7 +110,7 @@ export class MegaNatsAdapter extends MegaBusAdapter {
     const conn = resolveConnection(config, { driver: 'nats', dbConflictsWithUrl: false })
     assertPlainObject('options', config.options, { driver: 'nats' })
 
-    /** @type {import('nats').ConnectionOptions} */
+    /** @type {import('@nats-io/nats-core').ConnectionOptions} */
     const connectOptions = {}
     // options(passthrough) 먼저 — 아래 servers/auth 가 항상 이긴다(연결 필수값 보호).
     if (config.options !== undefined) Object.assign(connectOptions, config.options)
@@ -135,10 +138,9 @@ export class MegaNatsAdapter extends MegaBusAdapter {
    * @returns {Promise<void>}
    */
   async _connect() {
-    const { connect, JSONCodec } = await import('nats')
-    const nc = await connect(this.#connectOptions)
-    this.#nc = nc
-    this.#codec = JSONCodec()
+    // v3: core connect 는 `@nats-io/transport-node`(노드 전송) — v2 `nats` 단일 패키지 대체(ADR-225).
+    const { connect } = await import('@nats-io/transport-node')
+    this.#nc = await connect(this.#connectOptions)
   }
 
   /**
@@ -151,7 +153,6 @@ export class MegaNatsAdapter extends MegaBusAdapter {
     if (this.#nc !== null) {
       const nc = this.#nc
       this.#nc = null
-      this.#codec = null
       // 이미 닫혀 있으면(서버측 절단 등) drain 이 throw 할 수 있어 가드.
       if (!nc.isClosed()) await nc.drain()
     }
@@ -160,7 +161,7 @@ export class MegaNatsAdapter extends MegaBusAdapter {
   /**
    * raw NatsConnection handle (ADR-009). `connect()` 후에만 베이스 `native` getter 가 호출한다.
    * @protected
-   * @returns {import('nats').NatsConnection}
+   * @returns {import('@nats-io/nats-core').NatsConnection}
    */
   _native() {
     if (this.#nc === null) {
@@ -193,7 +194,7 @@ export class MegaNatsAdapter extends MegaBusAdapter {
 
   /**
    * 누적 통계 + nats 특화(server + 연결 stats). 연결 전이면 server/stats 는 undefined.
-   * @returns {ReturnType<import('./mega-adapter.js').MegaAdapter['getStats']> & { driver: string, server: string | undefined, nats: import('nats').Stats | undefined }}
+   * @returns {ReturnType<import('./mega-adapter.js').MegaAdapter['getStats']> & { driver: string, server: string | undefined, nats: import('@nats-io/nats-core').Stats | undefined }}
    */
   getStats() {
     const nc = this.#nc
@@ -211,15 +212,15 @@ export class MegaNatsAdapter extends MegaBusAdapter {
   // ──────────────────────────────────────────────────────────────────────
 
   /**
-   * fire-and-forget 발행 (ack X). payload 는 JSONCodec 로 인코드.
+   * fire-and-forget 발행 (ack X). payload 는 공유 JSON 코덱(encodeJson)으로 인코드.
    * @param {string} subject
    * @param {any} payload
    * @returns {Promise<void>}
    */
   async publish(subject, payload) {
     return this._instrument('publish', { subject }, async () => {
-      const nc = /** @type {import('nats').NatsConnection} */ (this.#nc)
-      nc.publish(subject, this.#encode(payload))
+      const nc = /** @type {import('@nats-io/nats-core').NatsConnection} */ (this.#nc)
+      nc.publish(subject, encodeJson(payload))
     })
   }
 
@@ -233,7 +234,7 @@ export class MegaNatsAdapter extends MegaBusAdapter {
    */
   async subscribe(subject, handler) {
     return this._instrument('subscribe', { subject }, async () => {
-      const nc = /** @type {import('nats').NatsConnection} */ (this.#nc)
+      const nc = /** @type {import('@nats-io/nats-core').NatsConnection} */ (this.#nc)
       const sub = nc.subscribe(subject, {
         callback: (err, msg) => this.#dispatch('subscribe', subject, handler, err, msg),
       })
@@ -254,20 +255,22 @@ export class MegaNatsAdapter extends MegaBusAdapter {
    */
   async request(subject, payload, { timeout = DEFAULT_REQUEST_TIMEOUT_MS } = {}) {
     return this._instrument('request', { subject, timeout }, async () => {
-      const nc = /** @type {import('nats').NatsConnection} */ (this.#nc)
+      const nc = /** @type {import('@nats-io/nats-core').NatsConnection} */ (this.#nc)
       try {
-        const reply = await nc.request(subject, this.#encode(payload), { timeout })
-        return /** @type {import('nats').Codec<any>} */ (this.#codec).decode(reply.data)
+        const reply = await nc.request(subject, encodeJson(payload), { timeout })
+        return decodeJson(reply.data)
       } catch (err) {
-        // NATS 타임아웃/무응답을 명시 에러 코드로 변환(silent 무시 X). 그 외 에러는 원본 전파.
-        const code = /** @type {any} */ (err)?.code
-        if (code === 'TIMEOUT') {
+        // v3(ADR-225): 타임아웃/무응답이 문자열 code('TIMEOUT'/'503')에서 **에러 클래스**로 바뀌었다.
+        // 클래스는 cold path 라 catch 에서 lazy import(모듈은 _connect 가 이미 로드 — 비용 0). 명시
+        // 에러 코드로 변환(silent 무시 X). RequestError 는 no-responders 를 isNoResponders() 로 알린다.
+        const { TimeoutError, NoRespondersError, RequestError } = await import('@nats-io/nats-core')
+        if (err instanceof TimeoutError) {
           throw new MegaInternalError('bus.request_timeout', `nats request("${subject}") timed out after ${timeout}ms.`, {
             details: { subject, timeout },
             cause: err,
           })
         }
-        if (code === '503') {
+        if (err instanceof NoRespondersError || (err instanceof RequestError && err.isNoResponders())) {
           throw new MegaInternalError('bus.no_responders', `nats request("${subject}"): no responders subscribed to the subject.`, {
             details: { subject },
             cause: err,
@@ -286,8 +289,8 @@ export class MegaNatsAdapter extends MegaBusAdapter {
    */
   async enqueue(jobName, payload) {
     return this._instrument('enqueue', { jobName }, async () => {
-      const nc = /** @type {import('nats').NatsConnection} */ (this.#nc)
-      nc.publish(jobName, this.#encode(payload))
+      const nc = /** @type {import('@nats-io/nats-core').NatsConnection} */ (this.#nc)
+      nc.publish(jobName, encodeJson(payload))
     })
   }
 
@@ -313,7 +316,7 @@ export class MegaNatsAdapter extends MegaBusAdapter {
    */
   async process(jobName, handler, { queue = jobName } = {}) {
     return this._instrument('process', { jobName, queue }, async () => {
-      const nc = /** @type {import('nats').NatsConnection} */ (this.#nc)
+      const nc = /** @type {import('@nats-io/nats-core').NatsConnection} */ (this.#nc)
       nc.subscribe(jobName, {
         queue,
         callback: (err, msg) => this.#dispatch('process', jobName, (m) => handler(m), err, msg),
@@ -321,23 +324,15 @@ export class MegaNatsAdapter extends MegaBusAdapter {
     })
   }
 
-  /**
-   * payload → Uint8Array (JSONCodec). undefined 는 null 로 정규화(JSONCodec 가 undefined 미지원).
-   * @param {any} payload @returns {Uint8Array}
-   */
-  #encode(payload) {
-    return /** @type {import('nats').Codec<any>} */ (this.#codec).encode(payload === undefined ? null : payload)
-  }
-
   /**
    * 구독/잡 콜백 공통 디스패처 — 에러·디코드·handler 호출을 표면화한다(silent 금지).
-   * 구독 에러(NatsError)·디코드 실패·handler throw 를 모두 `console.error` 로 드러낸다.
+   * 구독 에러·디코드 실패·handler throw 를 모두 `console.error` 로 드러낸다.
    *
    * @param {'subscribe' | 'process'} kind
    * @param {string} subject
    * @param {(msg: any, replyFn?: (payload: any) => void) => any} handler
-   * @param {import('nats').NatsError | null} err
-   * @param {import('nats').Msg} msg
+   * @param {Error | null} err
+   * @param {import('@nats-io/nats-core').Msg} msg
    * @returns {void}
    */
   #dispatch(kind, subject, handler, err, msg) {
@@ -348,14 +343,14 @@ export class MegaNatsAdapter extends MegaBusAdapter {
     }
     let decoded
     try {
-      decoded = /** @type {import('nats').Codec<any>} */ (this.#codec).decode(msg.data)
+      decoded = decodeJson(msg.data)
     } catch (decodeErr) {
       console.error(`[MegaNatsAdapter] ${kind}("${subject}") payload decode failed:`, decodeErr)
       return
     }
     // reply subject 가 있으면 replyFn 제공(request 응답용). subscribe 만 해당 — process 는 단방향.
     const replyFn =
-      kind === 'subscribe' && msg.reply ? /** @param {any} p */ (p) => msg.respond(this.#encode(p)) : undefined
+      kind === 'subscribe' && msg.reply ? /** @param {any} p */ (p) => msg.respond(encodeJson(p)) : undefined
     try {
       const out = handler(decoded, replyFn)
       // handler 가 async 면 reject 도 표면화(떠다니는 promise 가 silent 실패되지 않게).

package/src/adapters/nats-codec.js

@@ -0,0 +1,38 @@
+// @ts-check
+/**
+ * NATS JSON wire 코덱 — `@nats-io/*` v3 에서 제거된 `JSONCodec()` 대체 (ADR-225).
+ *
+ * v2 `nats` 패키지는 `JSONCodec()` 팩토리로 JS 값 ↔ `Uint8Array` 변환을 제공했으나, v3
+ * (`@nats-io/nats-core`)에서 코덱 팩토리가 제거되고 메시지에 `.json()`/`.string()` 편의 메서드만
+ * 남았다. 본 모듈은 어댑터·잡 큐가 wire 에 싣는 payload 의 JSON 직렬화를 **한 곳에서** 정의해
+ * (`MegaNatsAdapter` publish ↔ 소비자 decode 라운드트립 일관성), v2 `JSONCodec` 의 의미를 보존한다:
+ *   - encode: `undefined` 는 `null` 로 정규화(JSON 은 `undefined` 를 표현 못 함) 후 `JSON.stringify`.
+ *   - decode: 빈 payload(길이 0)는 `null` 로(빈 발행을 graceful 처리). 그 외는 `JSON.parse`.
+ *
+ * TextEncoder/TextDecoder 는 Node 전역(웹 표준)이라 신규 의존성 0.
+ *
+ * @module adapters/nats-codec
+ */
+
+const TE = new TextEncoder()
+const TD = new TextDecoder()
+
+/**
+ * JS 값 → NATS wire 바이트(JSON). `undefined` 는 `null` 로 정규화한다.
+ * @param {any} value
+ * @returns {Uint8Array}
+ */
+export function encodeJson(value) {
+  return TE.encode(JSON.stringify(value === undefined ? null : value))
+}
+
+/**
+ * NATS wire 바이트(JSON) → JS 값. 빈 payload(길이 0)는 `null`. 파싱 실패는 throw(호출부가 처리).
+ * @param {Uint8Array} data
+ * @returns {any}
+ * @throws {SyntaxError} JSON 파싱 실패 시(silent 금지 — poison 메시지 감지에 사용).
+ */
+export function decodeJson(data) {
+  if (!data || data.byteLength === 0) return null
+  return JSON.parse(TD.decode(data))
+}

package/src/cli/commands/scaffold.js

@@ -162,6 +162,7 @@ export function registerScaffoldCommands(program, { out, projectRoot, logger, re
           throw new Error(
             `Unknown generator '${kind}'. Supported: ${GENERATOR_KINDS.join(', ')}. ` +
               `(플러그인 generator 확인 실패: ${/** @type {any} */ (e).message ?? e})`,
+            { cause: e },
           )
         }
         if (def === undefined) {

package/src/cli/index.js

@@ -396,11 +396,13 @@ async function runStart(opts, { argv, out, projectRoot, logger, spawn, selfPath
     }
 
     // 런타임 그래프 lazy 로드 — 부팅 명령에서만 프레임워크 전체를 지불한다(모듈 상단 주석).
-    const [{ bootApp }, { MegaCluster }, { installPrimaryAggregator, installWorkerResponder }, { buildLogger }] =
+    const [{ bootApp }, { MegaCluster }, { installPrimaryAggregator, installWorkerResponder }, { installClusterLockMaster }, { installClusterBusMaster }, { buildLogger }] =
       await Promise.all([
         import('../core/boot.js'),
         import('../core/mega-cluster.js'),
         import('../core/cluster-metrics.js'),
+        import('../core/lock/cluster-lock.js'),
+        import('../core/bus/cluster-bus.js'),
         import('../lib/mega-logger.js'),
       ])
 
@@ -444,6 +446,12 @@ async function runStart(opts, { argv, out, projectRoot, logger, spawn, selfPath
     if (mega.isPrimary()) {
       // 마스터에 메트릭 집계기 설치(ADR-163) — 워커의 /metrics 요청을 받아 전 워커 합산해 회신.
       installPrimaryAggregator()
+      // 마스터에 분산 락 responder 설치(ADR-226) — cluster lock driver 워커들의 IPC 요청을 한 곳에서 직렬화.
+      // redis 없이 클러스터로만 돌 때 워커 간 상호배제를 마스터의 in-memory 락으로 제공한다(단일 노드 한정).
+      installClusterLockMaster()
+      // 마스터에 메시지 버스 라우터 설치(ADR-227) — cluster bus driver 워커들의 pub/sub IPC 를 fan-out.
+      // NATS 없이 클러스터로만 돌 때 워커 간 메시지 전달을 마스터 라우터로 제공한다(단일 노드 한정).
+      installClusterBusMaster()
       announce(masterLogger, `cluster master ${process.pid} forked ${workers} worker(s)`)
     }
     return 0
@@ -691,6 +699,39 @@ async function wireHostLogger(global, injectedLogger) {
   return appLogger
 }
 
+/**
+ * 잡 워커의 큐 길목 이벤트를 호스트 로거로 흘린다(ADR-223). `MegaJobWorker` 는 순수 런타임이라 logger 를
+ * 모르고 이벤트만 재방출하므로, 호스트가 구독하지 않으면 production 에서 잡 실패·DLQ 격리가 로그에 안 남는다.
+ * 레벨: `fail`=error(최종 실패), `dlq`=warn(격리됨), `retry`=warn(재시도), `start`/`done`=debug(prod silent).
+ * `dispatch`(enqueue)는 producer(웹) 측 이벤트라 워커 호스트에선 발화하지 않아 구독하지 않는다. 핵심 식별
+ * 필드만 박는다(전체 페이로드·결과 금지, P5). `log` 가 없으면(로거 미구성) 옵셔널 체이닝으로 no-op.
+ * @param {import('../lib/mega-job-worker.js').MegaJobWorker} worker
+ * @param {{ debug?: Function, warn?: Function, error?: Function }|null|undefined} log
+ * @returns {void}
+ */
+function subscribeJobLogging(worker, log) {
+  worker.on('fail', (e) => log?.error?.({ err: e?.error, subject: e?.subject, seq: e?.seq, phase: e?.phase }, 'job failed'))
+  worker.on('dlq', (e) => log?.warn?.({ subject: e?.subject, dlqSubject: e?.dlqSubject, seq: e?.seq }, 'job routed to DLQ'))
+  worker.on('retry', (e) => log?.warn?.({ err: e?.error, subject: e?.subject, seq: e?.seq, attempt: e?.attempt, retriesLeft: e?.retriesLeft }, 'job retry'))
+  worker.on('start', (e) => log?.debug?.({ subject: e?.subject, seq: e?.seq }, 'job start'))
+  worker.on('done', (e) => log?.debug?.({ subject: e?.subject, seq: e?.seq }, 'job done'))
+}
+
+/**
+ * 스케줄러의 길목 이벤트를 호스트 로거로 흘린다(ADR-223 — 잡 워커와 같은 갭). `MegaScheduler` 도 이벤트
+ * (run/skip/done/fail)만 노출하므로 호스트가 구독해 로그로 남긴다. 레벨: `fail`=error, 나머지는 debug
+ * (특히 `skip`=락 미획득은 클러스터 정상 동작이라 debug). `key`(락 키)는 클러스터 leader 추적에 유용.
+ * @param {import('../lib/mega-schedule.js').MegaScheduler} scheduler
+ * @param {{ debug?: Function, warn?: Function, error?: Function }|null|undefined} log
+ * @returns {void}
+ */
+function subscribeScheduleLogging(scheduler, log) {
+  scheduler.on('fail', (e) => log?.error?.({ err: e?.error, name: e?.name, key: e?.key, phase: e?.phase }, 'schedule failed'))
+  scheduler.on('skip', (e) => log?.debug?.({ name: e?.name, key: e?.key, reason: e?.reason }, 'schedule skipped'))
+  scheduler.on('run', (e) => log?.debug?.({ name: e?.name, key: e?.key }, 'schedule run'))
+  scheduler.on('done', (e) => log?.debug?.({ name: e?.name, key: e?.key }, 'schedule done'))
+}
+
 /**
  * `mega worker` 호스트 골격 — config + 어댑터 connect + ctx + `MegaJobWorker` 인스턴스 + graceful.
  * 등록 소스 = `config.jobs` + 플러그인 `mega.jobs.register` 분(`collectRegistrations`, ADR-123).
@@ -712,6 +753,11 @@ export async function runWorkerHost(projectRoot, logger) {
   // 옵트인 OFF 면 subscribeJobs 는 no-op() 을 반환한다. start 전에 구독해 enqueue(dispatch)부터 잡는다. 구독은
   // MegaMetrics.shutdown(boot 가 'mega-metrics' MegaShutdown hook 으로 등록)에서 일괄 해제되므로 별도 등록 불필요.
   MegaMetrics.subscribeJobs(worker)
+  // 잡 길목 로깅 (ADR-223) — MegaJobWorker 는 큐 이벤트를 재방출만 하고 logger 를 모른다(순수 런타임). 호스트가
+  // 구독해 로그로 남기지 않으면 production 에서 잡 영구 실패·DLQ 격리가 로그에 0 줄로 남아(메트릭/데모 페이지로만
+  // 보임) 운영자가 실패 신호를 못 받는다(mega-job-queue 설계: "fail/dlq 구독이 사실상 필수"). P5(에러 핸들러·
+  // async 경계 로그). 메트릭(subscribeJobs)과 독립적이라 둘 다 둔다. 페이로드 전체가 아닌 핵심 필드만 박는다(P5).
+  subscribeJobLogging(worker, log)
   // 등록 소스(ADR-123) = config.jobs(정적) + 플러그인 host.listJobs()(동적). register 가 subject/bus
   // 미선언·중복을 부팅 시 fail-fast.
   const jobs = collectRegistrations(global, host, 'jobs')
@@ -740,6 +786,9 @@ export async function runSchedulerHost(projectRoot, logger) {
   const { global, host, ctx } = await prepareRuntime(projectRoot, { ping: false, logger })
   const log = await wireHostLogger(global, logger)
   const scheduler = new MegaScheduler({ ctx })
+  // 스케줄 길목 로깅 (ADR-223) — 워커와 같은 갭: MegaScheduler 도 이벤트(run/skip/done/fail)를 노출만 하고
+  // logger 를 모른다. 호스트가 구독하지 않으면 production 에서 스케줄 실패가 로그에 안 남는다. P5.
+  subscribeScheduleLogging(scheduler, log)
   // 등록 소스(ADR-123) = config.schedules(정적) + 플러그인 host.listSchedules()(동적). register 가
   // cron 미선언·중복을 부팅 시 fail-fast.
   const schedules = collectRegistrations(global, host, 'schedules')

package/src/core/app-registry.js

@@ -0,0 +1,69 @@
+// @ts-check
+/**
+ * 부팅된 MegaApp 프로세스 레지스트리 — **ctx 없는 영역**(백그라운드 setInterval·외부 SDK 콜백·테스트 헬퍼)에서
+ * `getApp()` 으로 booted 앱에 접근해 `app.lock` / `app.bus` 등 process-level 표면을 쓴다 (ADR-228).
+ *
+ * # 왜 필요한가
+ *   `ctx.lock`/`ctx.bus` 는 요청 ctx 에만 있어, 요청 흐름 밖(타이머·외부 라이브러리 콜백)에선 잡을 수 없었다.
+ *   lock/bus manager 는 **process 싱글톤**(`setLockManager`/`setBusManager`)이라 요청과 무관하게 같은 인스턴스다.
+ *   `getApp()` 은 그 싱글톤을 들고 있는 MegaApp 을 돌려줘, ctx 가 있을 때와 **동일 표면**(app.lock/app.bus)을 제공한다.
+ *
+ * # ctx 와의 차이
+ *   `app.*` 는 **요청 무관** 자원만 — `lock`/`bus`(process manager) · `db(alias)`/`cache(alias)`(앱 별명 해석) ·
+ *   `log`/`name`. 요청-스코프(`req`/`user`/`session`/`reply`/요청 locale `t`)는 **없다** — 그건 ctx 전용이다.
+ *
+ * @module core/app-registry
+ */
+import { MegaError } from '../errors/mega-error.js'
+
+/** @type {Map<string, import('./mega-app.js').MegaApp>} name → booted MegaApp(등록 순서). */
+const apps = new Map()
+
+/**
+ * booted MegaApp 을 레지스트리에 등록한다(boot 의 apps 스테이지가 앱마다 1회 호출).
+ * @param {import('./mega-app.js').MegaApp} app
+ * @returns {void}
+ */
+export function setApp(app) {
+  apps.set(app.name, app)
+}
+
+/**
+ * booted MegaApp 을 가져온다 — ctx 없는 영역의 표준 접근점.
+ *   - `name` 지정: 그 이름의 앱(없으면 `app.not_found`).
+ *   - `name` 생략 + 앱 1개: 그 앱.
+ *   - `name` 생략 + 앱 0개: `app.not_initialized`(부팅 전 호출 — fail-fast).
+ *   - `name` 생략 + 앱 2개 이상: `app.ambiguous`(이름 필수).
+ *
+ * @param {string} [name] - 앱 이름(멀티앱 프로세스에서 지정).
+ * @returns {import('./mega-app.js').MegaApp}
+ * @throws {MegaError} `app.not_initialized` | `app.ambiguous` | `app.not_found`
+ */
+export function getApp(name) {
+  if (name !== undefined) {
+    const app = apps.get(name)
+    if (!app) {
+      throw new MegaError('app.not_found', `getApp('${name}') — no booted app named '${name}'. Booted: [${[...apps.keys()].join(', ') || '(none)'}].`, {
+        details: { name, booted: [...apps.keys()] },
+      })
+    }
+    return app
+  }
+  if (apps.size === 0) {
+    throw new MegaError('app.not_initialized', 'getApp() called before boot — no app is initialized. Call after bootApp() completes (e.g. afterBoot hook or post-listen background tasks).', { details: {} })
+  }
+  if (apps.size > 1) {
+    throw new MegaError('app.ambiguous', `getApp() is ambiguous — ${apps.size} apps booted ([${[...apps.keys()].join(', ')}]). Pass a name: getApp('<name>').`, { details: { booted: [...apps.keys()] } })
+  }
+  return /** @type {import('./mega-app.js').MegaApp} */ ([...apps.values()][0])
+}
+
+/** 등록된 앱이 있나(부팅 여부 가드 — `getApp` throw 없이 확인). @returns {boolean} */
+export function hasApp() {
+  return apps.size > 0
+}
+
+/** 테스트 격리/재부팅용 — 레지스트리 비움(shutdown 에서도 호출). @returns {void} */
+export function _resetApps() {
+  apps.clear()
+}

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())
     },
   },
   {