mega-framework 0.1.10 → 0.1.11

package/src/lib/mega-job-queue.js

@@ -38,13 +38,22 @@
  *   `fail`(최종 실패 — phase 로 단계 구분) · `dlq`(DLQ 라우팅). 소비자가 구독해 로그를 박는다.
  *   타이머·콜백 경로라 호출자가 없으므로 `fail`/`dlq` 구독이 사실상 필수다.
  *
+ * # nats v3 (`@nats-io/jetstream`) — JetStream API 위치 변경 (ADR-225)
+ *   v2 `nats` 단일 패키지에서 `@nats-io/*` 로 분리됐다. JetStream client/manager 는 `nc.jetstream()`/
+ *   `nc.jetstreamManager()` **메서드**에서 `jetstream(nc)`/`jetstreamManager(nc)` **함수**로 바뀌었고,
+ *   enum(RetentionPolicy/StorageType/AckPolicy)은 `@nats-io/jetstream`, `nanos`/codec 은
+ *   `@nats-io/nats-core` 로 이동, stream/consumer "not found" 가 문자열 code('404')에서 전용 에러
+ *   클래스(`StreamNotFoundError`/`ConsumerNotFoundError`)로 바뀌었다. 잡 미사용 앱에 nats 로드를
+ *   강제하지 않으려 ensureReady 가 `@nats-io/*` 를 lazy import 한다(어댑터 정합).
+ *
  * @module lib/mega-job-queue
- * @see ADR-119, ADR-028 (3종 분리), ADR-112 (NATS 어댑터), ADR-029 (래핑)
+ * @see ADR-119, ADR-028 (3종 분리), ADR-112 (NATS 어댑터), ADR-225 (nats v3 전환), ADR-029 (래핑)
  */
 import { EventEmitter } from 'node:events'
 import { MegaConfigError } from '../errors/config-error.js'
 import { MegaJob, resolveJobRetryConfig, resolveJobRunTimeoutMs } from './mega-job.js'
 import { withRetry } from './mega-retry.js'
+import { encodeJson, decodeJson } from '../adapters/nats-codec.js'
 
 /** 잡 큐가 노출하는 이벤트 화이트리스트(오타 차단 + 문서화 — 형제 클래스와 동일 정책). */
 const KNOWN_EVENTS = Object.freeze([
@@ -56,9 +65,6 @@ const KNOWN_EVENTS = Object.freeze([
   'dlq', // DLQ 라우팅 완료 — event.dlqSubject
 ])
 
-/** JetStream "stream/consumer not found" 에러 코드(실측 — nats 2.29, code '404'). */
-const NOT_FOUND_CODE = '404'
-
 /** DLQ 스트림 `max_age` 디폴트(ms) — 7일. 무한 적재 방지(ADR-134). `dlqMaxAgeMs: 0` 으로 끌 수 있다. */
 export const DEFAULT_DLQ_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000
 
@@ -86,7 +92,7 @@ function truncateStack(stack) {
 
 /**
  * @typedef {Object} MegaJobQueueOptions
- * @property {import('nats').NatsConnection} nc - **연결된** NatsConnection(`ctx.bus(alias).native`).
+ * @property {import('@nats-io/nats-core').NatsConnection} nc - **연결된** NatsConnection(`ctx.bus(alias).native`).
  * @property {number} [ackWaitMs=30000] - consumer ack 대기(ms). 초과 시 JetStream 재전달. `working()`
  *   하트비트가 이 값의 절반마다 lease 를 갱신한다.
  * @property {number} [maxDeliver=5] - JetStream 최대 전달 횟수(워커 크래시 재전달 backstop).
@@ -112,6 +118,18 @@ function truncateStack(stack) {
  * @property {Error} [error] - 실패 사유(실패 시).
  */
 
+/**
+ * ensureReady 가 lazy import 로 채우는 v3 nats 심볼 묶음(ADR-225). enum·nanos·not-found 에러 클래스만
+ * 추려 보관해 잡 미사용 앱에 nats 전체 로드를 강제하지 않는다.
+ * @typedef {Object} MegaJobQueueNatsBundle
+ * @property {typeof import('@nats-io/jetstream').RetentionPolicy} RetentionPolicy
+ * @property {typeof import('@nats-io/jetstream').AckPolicy} AckPolicy
+ * @property {typeof import('@nats-io/jetstream').StorageType} StorageType
+ * @property {typeof import('@nats-io/nats-core').nanos} nanos
+ * @property {typeof import('@nats-io/jetstream').JetStreamApiError} JetStreamApiError
+ * @property {typeof import('@nats-io/jetstream').JetStreamApiCodes} JetStreamApiCodes
+ */
+
 /**
  * JetStream 잡 큐 런타임. {@link MegaJob} 클래스를 받아 enqueue/consume·재시도·DLQ 를 처리한다.
  *
@@ -124,7 +142,7 @@ function truncateStack(stack) {
  * await sub.stop()
  */
 export class MegaJobQueue extends EventEmitter {
-  /** @type {import('nats').NatsConnection} */ #nc
+  /** @type {import('@nats-io/nats-core').NatsConnection} */ #nc
   /** @type {number} */ #ackWaitMs
   /** @type {number} */ #maxDeliver
   /** @type {number} */ #heartbeatMs
@@ -132,10 +150,9 @@ export class MegaJobQueue extends EventEmitter {
   /** @type {number} DLQ max_age(ms). 0 = 무제한. */ #dlqMaxAgeMs
   /** @type {number|undefined} DLQ max_bytes. undefined = 무제한. */ #dlqMaxBytes
   /** @type {number} run 전체 실행 상한 디폴트(ms). 0 = 무제한. 잡별 static timeoutMs 가 우선. */ #runTimeoutMs
-  /** @type {typeof import('nats')|null} 지연 로드된 nats 모듈(enum/codec/nanos). */ #nats = null
-  /** @type {import('nats').Codec<any>|null} */ #codec = null
-  /** @type {import('nats').JetStreamClient|null} */ #js = null
-  /** @type {import('nats').JetStreamManager|null} */ #jsm = null
+  /** @type {MegaJobQueueNatsBundle|null} 지연 로드된 v3 nats 심볼 묶음. ensureReady 가 채운다. */ #nats = null
+  /** @type {import('@nats-io/jetstream').JetStreamClient|null} */ #js = null
+  /** @type {import('@nats-io/jetstream').JetStreamManager|null} */ #jsm = null
   /** @type {Promise<void>|null} ensureReady 멱등 가드. */ #readyPromise = null
   /**
    * subject 별 ensureStream 멱등 캐시(#readyPromise 와 동일 패턴). 없으면 enqueue 가 매 호출
@@ -151,9 +168,11 @@ export class MegaJobQueue extends EventEmitter {
    */
   constructor({ nc, ackWaitMs = 30_000, maxDeliver = 5, heartbeatMs, streamPrefix = 'MEGA_JOBS', dlqMaxAgeMs = DEFAULT_DLQ_MAX_AGE_MS, dlqMaxBytes, runTimeoutMs = DEFAULT_RUN_TIMEOUT_MS } = /** @type {any} */ ({})) {
     super()
-    if (!nc || typeof nc.jetstream !== 'function' || typeof nc.jetstreamManager !== 'function') {
+    // v3(ADR-225): jetstream()/jetstreamManager() 는 더 이상 nc 메서드가 아니라 standalone 함수다.
+    // nc 는 core NatsConnection 이면 충분(publish/subscribe 계약) — jetstream(nc)/jetstreamManager(nc) 에 넘긴다.
+    if (!nc || typeof nc.publish !== 'function' || typeof nc.subscribe !== 'function') {
       throw new TypeError(
-        'MegaJobQueue({ nc }) — nc must be a connected NatsConnection (jetstream()/jetstreamManager()).',
+        'MegaJobQueue({ nc }) — nc must be a connected NatsConnection (publish()/subscribe()).',
       )
     }
     if (typeof ackWaitMs !== 'number' || ackWaitMs <= 0) {
@@ -255,11 +274,21 @@ export class MegaJobQueue extends EventEmitter {
   async ensureReady() {
     if (this.#readyPromise) return this.#readyPromise
     this.#readyPromise = (async () => {
-      const nats = await import('nats')
-      this.#nats = nats
-      this.#codec = nats.JSONCodec()
-      this.#js = this.#nc.jetstream()
-      this.#jsm = await this.#nc.jetstreamManager()
+      // v3(ADR-225): JetStream client/manager 는 standalone 함수(`jetstream(nc)`/`jetstreamManager(nc)`),
+      // enum 은 @nats-io/jetstream, nanos 는 @nats-io/nats-core. 둘을 병렬 lazy import(잡 미사용 앱 보호).
+      const [js, core] = await Promise.all([import('@nats-io/jetstream'), import('@nats-io/nats-core')])
+      // not-found 는 전용 서브클래스가 top-level export 가 아니라(jserrors 내부), base JetStreamApiError +
+      // JetStreamApiCodes(StreamNotFound=10059/ConsumerNotFound=10014)로 판별한다(실측 — v3 런타임 export 표면).
+      this.#nats = {
+        RetentionPolicy: js.RetentionPolicy,
+        AckPolicy: js.AckPolicy,
+        StorageType: js.StorageType,
+        nanos: core.nanos,
+        JetStreamApiError: js.JetStreamApiError,
+        JetStreamApiCodes: js.JetStreamApiCodes,
+      }
+      this.#js = js.jetstream(this.#nc)
+      this.#jsm = await js.jetstreamManager(this.#nc)
     })()
     return this.#readyPromise
   }
@@ -356,7 +385,7 @@ export class MegaJobQueue extends EventEmitter {
     if (cached) return cached
     const ensured = (async () => {
       await this.ensureReady()
-      const nats = /** @type {typeof import('nats')} */ (this.#nats)
+      const nats = /** @type {MegaJobQueueNatsBundle} */ (this.#nats)
       await this.#ensureStreamExists(this.#workStreamName(subject), [subject], nats.RetentionPolicy.Workqueue)
       // DLQ 스트림에 한도를 건다(무한 적재 방지, ADR-134). dlqMaxAgeMs=0 이면 max_age 미지정(무제한),
       // dlqMaxBytes 미지정이면 max_bytes 미지정.
@@ -380,20 +409,22 @@ export class MegaJobQueue extends EventEmitter {
    * 단일 스트림 멱등 생성 — info 로 존재 확인 후 없으면 add. not-found 외 에러는 전파. `limits` 가
    * 주어지면 생성 시 `max_age`/`max_bytes` 를 함께 설정한다(DLQ 한도, ADR-134). 이미 존재하는 스트림은
    * 갱신하지 않는다(멱등 — 설정 변경은 운영 책임).
-   * @param {string} name @param {string[]} subjects @param {import('nats').RetentionPolicy} retention
+   * @param {string} name @param {string[]} subjects @param {import('@nats-io/jetstream').RetentionPolicy} retention
    * @param {{ maxAgeMs?: number, maxBytes?: number }} [limits]
    * @returns {Promise<void>}
    */
   async #ensureStreamExists(name, subjects, retention, limits) {
-    const jsm = /** @type {import('nats').JetStreamManager} */ (this.#jsm)
-    const nats = /** @type {typeof import('nats')} */ (this.#nats)
+    const jsm = /** @type {import('@nats-io/jetstream').JetStreamManager} */ (this.#jsm)
+    const nats = /** @type {MegaJobQueueNatsBundle} */ (this.#nats)
     try {
       await jsm.streams.info(name)
       return // 이미 존재.
     } catch (e) {
-      if (/** @type {any} */ (e)?.code !== NOT_FOUND_CODE) throw e // 진짜 장애는 묻지 않는다.
+      // v3(ADR-225): not-found 가 문자열 code('404')에서 JetStreamApiError(code=StreamNotFound)로 바뀜. 그 외 전파.
+      if (!(e instanceof nats.JetStreamApiError && e.code === nats.JetStreamApiCodes.StreamNotFound)) throw e
     }
-    /** @type {Record<string, any>} */
+    // v3 StreamConfig 는 `name` 필수(WithRequired) — name 을 가진 partial StreamConfig 로 타입 고정.
+    /** @type {import('@nats-io/nats-core').WithRequired<Partial<import('@nats-io/jetstream').StreamConfig>, 'name'>} */
     const config = { name, subjects, retention, storage: nats.StorageType.File }
     if (limits) {
       // max_age 는 nanos(ms→ns). 0 은 NATS 에서 "무제한" 이므로 양수일 때만 설정(미지정=무제한과 동일).
@@ -408,13 +439,14 @@ export class MegaJobQueue extends EventEmitter {
    * @param {string} stream @param {string} durable @param {string} subject @param {number} concurrency @returns {Promise<void>}
    */
   async #ensureConsumer(stream, durable, subject, concurrency) {
-    const jsm = /** @type {import('nats').JetStreamManager} */ (this.#jsm)
-    const nats = /** @type {typeof import('nats')} */ (this.#nats)
+    const jsm = /** @type {import('@nats-io/jetstream').JetStreamManager} */ (this.#jsm)
+    const nats = /** @type {MegaJobQueueNatsBundle} */ (this.#nats)
     try {
       await jsm.consumers.info(stream, durable)
       return
     } catch (e) {
-      if (/** @type {any} */ (e)?.code !== NOT_FOUND_CODE) throw e
+      // v3(ADR-225): consumer not-found = JetStreamApiError(code=ConsumerNotFound). 그 외 에러는 전파.
+      if (!(e instanceof nats.JetStreamApiError && e.code === nats.JetStreamApiCodes.ConsumerNotFound)) throw e
     }
     await jsm.consumers.add(stream, {
       durable_name: durable,
@@ -442,11 +474,11 @@ export class MegaJobQueue extends EventEmitter {
     }
     await this.ensureStream(JobClass)
     const subject = /** @type {string} */ (JobClass.subject)
-    const js = /** @type {import('nats').JetStreamClient} */ (this.#js)
+    const js = /** @type {import('@nats-io/jetstream').JetStreamClient} */ (this.#js)
     // msgID(옵트인) = JetStream `Nats-Msg-Id` dedup — 스트림 duplicate window(NATS 기본 2분) 안의
     // 같은 msgID 재발행은 적재되지 않고 ack.duplicate=true 로 돌아온다(producer 중복: 재시도 enqueue·
     // 이중 클릭 방어). 미지정 시 dedup 없음(기존 동작, 비용 0) — duplicate 는 그때 항상 false.
-    const ack = await js.publish(subject, this.#encode(payload), msgID !== undefined ? { msgID } : undefined)
+    const ack = await js.publish(subject, encodeJson(payload), msgID !== undefined ? { msgID } : undefined)
     // dispatch 는 publish(부작용) 완료 후 발화 — 리스너 throw 가 반환값/흐름을 오염시키지 않게 safeEmit(L-3).
     this.#safeEmit('dispatch', { subject, seq: ack.seq, stream: ack.stream })
     return { seq: ack.seq, stream: ack.stream, duplicate: ack.duplicate }
@@ -478,7 +510,7 @@ export class MegaJobQueue extends EventEmitter {
     const runTimeoutMs = resolveJobRunTimeoutMs(JobClass, this.#runTimeoutMs) // 행 잡 영구 점유 backstop.
     await this.#ensureConsumer(stream, durable, subject, concurrency)
 
-    const js = /** @type {import('nats').JetStreamClient} */ (this.#js)
+    const js = /** @type {import('@nats-io/jetstream').JetStreamClient} */ (this.#js)
     const consumer = await js.consumers.get(stream, durable)
     const messages = await consumer.consume({ max_messages: concurrency })
 
@@ -506,8 +538,8 @@ export class MegaJobQueue extends EventEmitter {
 
     return {
       stop: async () => {
-        // ConsumerMessages.close() 는 Promise<void|Error> 를 반환(nats 2.29 consumer.d.ts) — drain 중
-        // 오류면 Error 인스턴스를 resolve 한다(reject 아님). 묵히지 않고 stderr 로 표면화한다(L-3).
+        // ConsumerMessages.close() 는 Promise<void|Error> 를 반환(@nats-io/jetstream v3 동일 계약) — drain
+        // 중 오류면 Error 인스턴스를 resolve 한다(reject 아님). 묵히지 않고 stderr 로 표면화한다(L-3).
         const closeResult = await messages.close()
         if (closeResult instanceof Error) {
           console.error(`[mega-job-queue] consumer close reported an error on '${subject}':`, closeResult)
@@ -522,7 +554,7 @@ export class MegaJobQueue extends EventEmitter {
    * in-flight Promise 가 reject 되지 않게 — MegaScheduler #fire 와 동일 불변식). 내부/테스트용 seam 이라
    * `_` 접두사(어댑터 `_connect` 컨벤션).
    *
-   * @param {MegaJob} instance @param {Record<string, any>} ctx @param {import('nats').JsMsg} msg
+   * @param {MegaJob} instance @param {Record<string, any>} ctx @param {import('@nats-io/jetstream').JsMsg} msg
    * @param {ReturnType<typeof resolveJobRetryConfig>} retryConfig @param {string} subject
    * @param {number} [runTimeoutMs] - run 전체(재시도 포함) 상한(ms). 미지정 시 큐 디폴트, 0 = 무제한.
    * @returns {Promise<MegaJobHandleResult>}
@@ -545,7 +577,7 @@ export class MegaJobQueue extends EventEmitter {
       this.#safeEmit('fail', { subject, seq, error, phase: 'max-deliver' })
       let exhaustedPayload
       try {
-        exhaustedPayload = this.#decode(msg.data)
+        exhaustedPayload = decodeJson(msg.data)
       } catch {
         // 디코드까지 실패한 poison 이면 raw 바이트를 봉투에 보관(무시 아님, DLQ 로 보존).
         exhaustedPayload = { decodeError: true, rawBase64: this.#toBase64(msg.data) }
@@ -556,7 +588,7 @@ export class MegaJobQueue extends EventEmitter {
 
     let payload
     try {
-      payload = this.#decode(msg.data)
+      payload = decodeJson(msg.data)
     } catch (decodeErr) {
       // 디코드 불가 = poison 메시지. 재시도 무의미 → 곧장 DLQ(원본 바이트 base64 보관).
       const error = decodeErr instanceof Error ? decodeErr : new Error(String(decodeErr))
@@ -657,11 +689,11 @@ export class MegaJobQueue extends EventEmitter {
    * (at-least-once — 즉시 재전달 핫 루프 방지). 단 이번 전달이 `max_deliver` 의 **마지막 전달**이면 nak 해도
    * 재전달이 없어 메시지가 워크 스트림에 orphan 으로 남는다 — 이때는 un-ack 보존 + `fail(dlq-orphan)` 으로
    * 운영자 개입을 명시 표면화한다(ack/term 으로 잡을 지우면 유실이라 하지 않는다). 본 메서드도 throw 하지 않는다.
-   * @param {string} subject @param {any} payload @param {Error} error @param {import('nats').JsMsg} msg @param {number} seq @returns {Promise<void>}
+   * @param {string} subject @param {any} payload @param {Error} error @param {import('@nats-io/jetstream').JsMsg} msg @param {number} seq @returns {Promise<void>}
    */
   async #routeToDlq(subject, payload, error, msg, seq) {
     const dlqSubject = `${subject}.dlq`
-    const js = /** @type {import('nats').JetStreamClient} */ (this.#js)
+    const js = /** @type {import('@nats-io/jetstream').JetStreamClient} */ (this.#js)
     try {
       // DLQ publish 자체를 짧게 재시도(추가 2회, 250ms→1s) — 일시적 NATS 응답 지연/재연결 틈을 흡수해
       // nak 재전달(전체 인프로세스 재시도 사이클 반복)보다 훨씬 싸게 orphan 확률을 줄인다.
@@ -669,7 +701,7 @@ export class MegaJobQueue extends EventEmitter {
         () =>
           js.publish(
             dlqSubject,
-            this.#encode({
+            encodeJson({
               originalSubject: subject,
               failedAt: new Date().toISOString(),
               deliveryCount: msg.info.deliveryCount,
@@ -700,16 +732,8 @@ export class MegaJobQueue extends EventEmitter {
   }
 
   // ── 헬퍼 ────────────────────────────────────────────────────────────────
-
-  /** @param {any} value @returns {Uint8Array} JSONCodec 인코드(undefined→null). */
-  #encode(value) {
-    return /** @type {import('nats').Codec<any>} */ (this.#codec).encode(value === undefined ? null : value)
-  }
-
-  /** @param {Uint8Array} data @returns {any} JSONCodec 디코드. */
-  #decode(data) {
-    return /** @type {import('nats').Codec<any>} */ (this.#codec).decode(data)
-  }
+  // JSON 인코드/디코드는 공유 코덱(adapters/nats-codec.js)의 encodeJson/decodeJson 을 직접 쓴다
+  // (v3 에서 JSONCodec 팩토리 제거 — ADR-225). undefined→null 정규화·빈 payload→null 은 코덱이 담당.
 
   /** @param {Uint8Array} data @returns {string} base64(원본 바이트 보존용). */
   #toBase64(data) {

package/types/adapters/mega-adapter.d.ts

@@ -21,7 +21,7 @@ export class MegaAdapter {
      * 토큰이 없으면(옵트인 OFF) 아예 쓰이지 않아 0 비용.
      * @type {AsyncLocalStorage<any>}
      */
-    static "__#private@#callScope": AsyncLocalStorage<any>;
+    static #callScope: AsyncLocalStorage<any>;
     /**
      * @param {object} [config] - driver 별 설정 (url / pool / file 등).
      */

package/types/adapters/nats-adapter.d.ts

@@ -19,9 +19,9 @@ 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}
      */
-    protected _native(): import("nats").NatsConnection;
+    protected _native(): import("@nats-io/nats-core").NatsConnection;
     /**
      * 헬스 체크 — 실제 `rtt`(서버 왕복 ping)로 응답성 확인. 실패는 throw 없이 `ok:false` + 사유.
      * @returns {Promise<{ ok: boolean, driver: 'nats', state: string, server?: string, rttMs?: number, error?: string }>}
@@ -36,12 +36,12 @@ 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(): ReturnType<import("./mega-adapter.js").MegaAdapter["getStats"]> & {
         driver: string;
         server: string | undefined;
-        nats: import("nats").Stats | undefined;
+        nats: import("@nats-io/nats-core").Stats | undefined;
     };
     /**
      * 잡 enqueue — 단순 publish (queue group 분배는 `process` 측 책임, ADR-112).

package/types/adapters/nats-codec.d.ts

@@ -0,0 +1,13 @@
+/**
+ * JS 값 → NATS wire 바이트(JSON). `undefined` 는 `null` 로 정규화한다.
+ * @param {any} value
+ * @returns {Uint8Array}
+ */
+export function encodeJson(value: any): Uint8Array;
+/**
+ * NATS wire 바이트(JSON) → JS 값. 빈 payload(길이 0)는 `null`. 파싱 실패는 throw(호출부가 처리).
+ * @param {Uint8Array} data
+ * @returns {any}
+ * @throws {SyntaxError} JSON 파싱 실패 시(silent 금지 — poison 메시지 감지에 사용).
+ */
+export function decodeJson(data: Uint8Array): any;

package/types/adapters/redlock-adapter.d.ts

@@ -10,7 +10,7 @@ export class MegaRedlockAdapter extends MegaLockAdapter {
      * 보고 거부, 숫자 4종은 음 아닌 정수, driftFactor 는 [0,1) 유한수.
      * @param {unknown} options @returns {Partial<RedlockSettings>}
      */
-    static "__#private@#normalizeSettings"(options: unknown): Partial<RedlockSettings>;
+    static #normalizeSettings(options: unknown): Partial<RedlockSettings>;
     /**
      * @param {RedlockConfig} [config] - services.locks.<key> 설정.
      * @throws {MegaValidationError} `lock.redis_required` - `redis` 키 누락/비문자열.

package/types/core/app-registry.d.ts

@@ -0,0 +1,22 @@
+/**
+ * booted MegaApp 을 레지스트리에 등록한다(boot 의 apps 스테이지가 앱마다 1회 호출).
+ * @param {import('./mega-app.js').MegaApp} app
+ * @returns {void}
+ */
+export function setApp(app: import("./mega-app.js").MegaApp): void;
+/**
+ * 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?: string): import("./mega-app.js").MegaApp;
+/** 등록된 앱이 있나(부팅 여부 가드 — `getApp` throw 없이 확인). @returns {boolean} */
+export function hasApp(): boolean;
+/** 테스트 격리/재부팅용 — 레지스트리 비움(shutdown 에서도 호출). @returns {void} */
+export function _resetApps(): void;

package/types/core/bus/cluster-bus.d.ts

@@ -0,0 +1,45 @@
+/**
+ * master 프로세스에 버스 라우터를 설치한다(멱등). 워커들의 구독을 모아 발행 시 fan-out 한다.
+ * `mega start` 클러스터 분기에서 master 가 1회 호출한다.
+ * @param {import('node:cluster').Cluster} [cluster] - 테스트 주입용(기본 node:cluster).
+ * @returns {{ subscriptions: () => number } | null} 관측용 핸들(테스트). 이미 설치됐으면 null.
+ */
+export function installClusterBusMaster(cluster?: import("node:cluster").Cluster): {
+    subscriptions: () => number;
+} | null;
+/** 테스트 격리용 — master 설치 플래그 초기화. @returns {void} */
+export function _resetClusterBusMaster(): void;
+/**
+ * 워커 측 cluster 버스 driver — master 에 IPC 위임 + master 의 deliver 를 로컬 핸들러로 디스패치.
+ */
+export class ClusterBusDriver {
+    /**
+     * @param {{ proc?: NodeJS.Process }} [opts] - `proc` 테스트 주입용(기본 process). cluster 워커여야 send 존재.
+     * @throws {Error} proc.send 가 없으면(cluster 워커 아님).
+     */
+    constructor({ proc }?: {
+        proc?: NodeJS.Process;
+    });
+    /** @type {'cluster'} */
+    get name(): "cluster";
+    /** cluster 는 persist 무시(opts 는 계약 정합용). @param {string} subject @param {import('./contract.js').BusEnvelope} envelope @param {{ persist?: boolean }} [_opts] @returns {Promise<void>} */
+    publish(subject: string, envelope: import("./contract.js").BusEnvelope, _opts?: {
+        persist?: boolean;
+    }): Promise<void>;
+    /** @param {string} pattern @param {Function} handler @param {{ ordered?: boolean }} opts @returns {Promise<import('./contract.js').Subscription>} */
+    subscribe(pattern: string, handler: Function, { ordered }?: {
+        ordered?: boolean;
+    }): Promise<import("./contract.js").Subscription>;
+    /** @param {string} subject @param {import('./contract.js').BusEnvelope} envelope @param {{ timeout: number }} opts @returns {Promise<import('./contract.js').BusEnvelope>} */
+    request(subject: string, envelope: import("./contract.js").BusEnvelope, { timeout }: {
+        timeout: number;
+    }): Promise<import("./contract.js").BusEnvelope>;
+    /** @returns {Promise<{ driver: string, subscriptions: number }>} */
+    stats(): Promise<{
+        driver: string;
+        subscriptions: number;
+    }>;
+    /** 정리 — IPC 리스너 제거 + 대기 요청 reject + 핸들러 비움. @returns {Promise<void>} */
+    close(): Promise<void>;
+    #private;
+}

package/types/core/bus/contract.d.ts

@@ -0,0 +1,164 @@
+/**
+ * @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: string, prefix?: string): string;
+/**
+ * subject 검증 — 비어있지 않고 공백/제어문자 없는 문자열. publish subject 는 wildcard 금지(구체적이어야 함).
+ * @param {string} subject @param {{ allowWildcard?: boolean }} [opts] - true 면 `*`/`>` 허용(구독용).
+ * @returns {void}
+ * @throws {MegaValidationError} `bus.invalid_subject`
+ */
+export function assertSubject(subject: string, { allowWildcard }?: {
+    allowWildcard?: boolean;
+}): void;
+/**
+ * NATS 식 wildcard 매칭 — cluster/memory-bus 의 자체 패턴 매칭(nats-bus 는 NATS native 사용).
+ *   `*` = 한 토큰, `>` = 한 토큰 이상(꼬리). 토큰 수가 정확히 맞아야 매칭(`>` 제외).
+ * @param {string} pattern - 구독 패턴(wildcard 가능). @param {string} subject - 구체 subject.
+ * @returns {boolean}
+ */
+export function matchSubject(pattern: string, subject: string): boolean;
+/** request/reply 응답 대기 디폴트(ms). config `bus.requestTimeoutMs` 로 조정. */
+export const DEFAULT_REQUEST_TIMEOUT_MS: 5000;
+/**
+ * - wire/IPC 로 오가는 메시지 봉투(payload 와 meta 분리 — meta 는 traceId 등).
+ */
+export type BusEnvelope = {
+    /**
+     * - 사용자 데이터.
+     */
+    payload: any;
+    /**
+     * - 부가 메타(전파용). 없으면 빈 객체로 취급.
+     */
+    meta?: Record<string, any>;
+};
+/**
+ * - emit 옵션.
+ */
+export type EmitOpts = {
+    /**
+     * - 이 메시지의 meta.
+     */
+    meta?: Record<string, any>;
+    /**
+     * - true 면 영속 전달(JetStream — nats-bus 만; 그 외 driver 는 경고 후 비영속).
+     */
+    persist?: boolean;
+};
+/**
+ * - on(구독) 옵션.
+ */
+export type OnOpts = {
+    /**
+     * - true 면 영속 구독(JetStream consumer — nats-bus 만).
+     */
+    persist?: boolean;
+    /**
+     * - true 면 같은 subject 메시지를 순서대로 1건씩 직렬 처리(핸들러 await 직렬화).
+     */
+    ordered?: boolean;
+};
+/**
+ * - 사용자 핸들러.
+ *   3번째 인자 `subject` 는 메시지가 도착한 **구체** subject(prefix 제거됨) — wildcard 구독에서 어느 subject 가
+ *   매칭됐는지 안다. `meta.subject` 에도 같은 값이 담긴다(정본 위치). request 대상이면 **반환값이 reply**.
+ */
+export type BusHandler = (payload: any, meta: Record<string, any>, subject: string) => any;
+/**
+ * - on/subscribe 가 돌려주는 구독 핸들.
+ */
+export type Subscription = {
+    /**
+     * - 구독 해제.
+     */
+    unsubscribe: () => Promise<void>;
+};
+/**
+ * - driver 가 핸들러에 주는 응답 함수(request 일 때만).
+ */
+export type ReplyFn = (envelope: BusEnvelope) => void;
+/**
+ * - driver 가 구현하는 저수준 인터페이스(manager 가 호출).
+ */
+export type BusDriver = {
+    /**
+     * - 'nats' | 'cluster' | 'memory'.
+     */
+    name: string;
+    /**
+     * -
+     * fire-and-forget 발행(구독자 전원 fan-out).
+     */
+    publish: (subject: string, envelope: BusEnvelope, opts: {
+        persist?: boolean;
+    }) => Promise<void>;
+    /**
+     * -
+     * 구독(subject 는 wildcard 가능). `reply` 는 request 로 들어온 메시지일 때만 제공. 핸들러의 3번째 인자는
+     * 매칭된 **구체** subject(driver 가 채워 manager 로 넘김 — wildcard 어디로 왔는지 안다).
+     */
+    subscribe: (subject: string, handler: (envelope: BusEnvelope, reply?: ReplyFn, subject?: string) => any, opts: {
+        persist?: boolean;
+        ordered?: boolean;
+    }) => Promise<Subscription>;
+    /**
+     * -
+     * req/reply — 첫 응답 envelope 반환. 응답자 없으면 `bus.no_responders`, 시한 초과면 `bus.request_timeout` throw.
+     */
+    request: (subject: string, envelope: BusEnvelope, opts: {
+        timeout: number;
+    }) => Promise<BusEnvelope>;
+    /**
+     * - 현재 구독 수.
+     */
+    stats: () => Promise<{
+        driver: string;
+        subscriptions: number;
+    }>;
+    /**
+     * - 구독·타이머·IPC·연결참조 정리.
+     */
+    close: () => Promise<void>;
+};