mega-framework 0.1.10 → 0.1.13

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/templates/model/code-mongo.tpl

@@ -17,19 +17,11 @@ export class {{Name}} extends MegaModel {
   static table = '{{table}}'
 
   // 자동 마이그레이션 스키마(ADR-209) — 빌더 API 는 docs/guide/03-service-model-db.md §5 참조.
-  static schema = (t) => ({
+  static schema = /** @param {any} t */ (t) => ({
     name: t.varchar(100).notNull(),
     createdAt: t.timestamptz().notNull(), // 생성 시 앱에서 new Date() 로 채운다(mongo 는 default 미지원)
   })
 
   // 인덱스(선택): static indexes = (t) => [t.index(['name'], { unique: true })]
 
-  /**
-   * _id 로 1건 조회 — `this.db` 는 native mongodb `Db`(ADR-009), 도큐먼트 API 직접 사용.
-   * @param {import('mongodb').ObjectId} id
-   * @returns {Promise<object|null>}
-   */
-  static async findById(id) {
-    return this.db.collection(this.table).findOne({ _id: id })
-  }
 }

package/templates/model/code.tpl

@@ -15,7 +15,7 @@ export class {{Name}} extends MegaModel {
   static table = '{{table}}'
 
   // 자동 마이그레이션 스키마(ADR-204) — 빌더 API 는 docs/guide/03-service-model-db.md §5 참조.
-  static schema = (t) => ({
+  static schema = /** @param {any} t */ (t) => ({
     id: t.serial().primary(),
     name: t.varchar(100).notNull(),
     createdAt: t.timestamptz().defaultNow(),
@@ -23,13 +23,4 @@ export class {{Name}} extends MegaModel {
 
   // 인덱스(선택): static indexes = (t) => [t.index(['name'], { unique: true })]
 
-  /**
-   * id 로 1건 조회. `this.query` 는 계측된 어댑터 query 위임(ADR-138).
-   * @param {string|number} id
-   * @returns {Promise<object|null>}
-   */
-  static async findById(id) {
-    const { rows } = await this.query('select * from {{table}} where id = $1', [id])
-    return rows[0] ?? null
-  }
 }

package/templates/model/test-mongo.tpl

@@ -12,27 +12,5 @@ describe('{{Name}} model (mongodb)', () => {
 
   test('schema 빌더 선언 — 자동 마이그레이션 트랙 옵트인(ADR-209)', () => {
     expect(typeof {{Name}}.schema).toBe('function')
-  })
-
-  test('findById — native Db 의 도큐먼트 API 에 위임', async () => {
-    /** @type {any[]} */
-    const calls = []
-    const fakeDb = {
-      collection: (/** @type {string} */ name) => ({
-        findOne: async (/** @type {any} */ filter) => {
-          calls.push({ name, filter })
-          return { _id: filter._id }
-        },
-      }),
-    }
-    // MegaModel.db 는 getter 라 서브클래스 own property 로 가린다(테스트 한정).
-    Object.defineProperty({{Name}}, 'db', { value: fakeDb, configurable: true })
-    try {
-      const doc = await {{Name}}.findById(/** @type {any} */ ('id-1'))
-      expect(doc).toEqual({ _id: 'id-1' })
-      expect(calls[0].name).toBe('{{table}}')
-    } finally {
-      delete /** @type {any} */ ({{Name}}).db
-    }
-  })
+  })  
 })

package/templates/model/test.tpl

@@ -13,21 +13,4 @@ describe('{{Name}} model', () => {
   test('schema 빌더 선언 — 자동 마이그레이션 트랙 옵트인(ADR-204)', () => {
     expect(typeof {{Name}}.schema).toBe('function')
   })
-
-  test('findById — 어댑터 query 에 위임', async () => {
-    const orig = {{Name}}.query
-    /** @type {any[]} */
-    const calls = []
-    {{Name}}.query = async (/** @type {string} */ sql, /** @type {any[]} */ params) => {
-      calls.push({ sql, params })
-      return { rows: [{ id: params[0] }] }
-    }
-    try {
-      const row = await {{Name}}.findById(7)
-      expect(row).toEqual({ id: 7 })
-      expect(calls[0].params).toEqual([7])
-    } finally {
-      {{Name}}.query = orig
-    }
-  })
 })

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