mega-framework 0.1.0

package/src/adapters/mega-adapter.js

@@ -0,0 +1,511 @@
+// @ts-check
+/**
+ * MegaAdapter — 모든 어댑터의 추상 베이스 (ADR-027, ADR-045, ADR-077).
+ *
+ * 표준 lifecycle 5종 + 관찰성 hook 2종을 강제해서 코어가 부팅·종료·헬스체크·트레이싱을
+ * **균일하게** 처리하도록 한다. 도메인 베이스(`MegaDbAdapter` 등)와 구체 어댑터
+ * (`MegaPostgresAdapter` 등)가 이 베이스를 상속한다.
+ *
+ * # 표준 표면 (08-class-specs §3.2)
+ *   - `connect()` / `disconnect()` — lifecycle. 상태 머신은 베이스가 관리.
+ *   - `healthCheck()` — `/health/ready` 가 모든 어댑터의 `ok` 를 AND.
+ *   - `getStats()` — 동기. 호출 횟수·에러·latency 누적 스냅샷.
+ *   - `get native` — driver native handle (pg Pool / MongoClient 등). connect 후에만 유효.
+ *   - `onCallStart(callName, attrs)` / `onCallEnd(callName, attrs, err, scope)` — 관찰성 hook.
+ *     디폴트는 `addHookListener` 로 등록된 리스너에 디스패치(없으면 no-op·0 비용).
+ *     트레이싱(`MegaTracing`)이 `addHookListener` 로 구독해 자동 span 으로 변환 (ADR-077).
+ *     `onCallStart` 이 스코프 토큰을 반환하면 `_instrument` 가 `fn` 을 그 토큰으로 `run()` 안에서
+ *     실행해 span 중첩(트랜잭션 안의 query)을 정확히 만든다 — ADR-077 의 유일한 _instrument seam.
+ *
+ * # 구체 어댑터가 구현할 것 (override)
+ *   - `_connect()` / `_disconnect()` — 실제 연결/해제 (디폴트 no-op).
+ *   - `_native()` — native handle 반환 (디폴트 throw `adapter.not_implemented`).
+ *   - 도메인 메서드(`query` / `get` / `publish` 등) — 도메인 베이스에서 stub 제공, 구체가 override.
+ *   - 도메인 메서드 내부에서 {@link MegaAdapter#_instrument} 로 감싸면 hook + 상태 검증 + stats
+ *     누적이 한 번에 처리된다 (roadmap "boilerplate 패턴"). 직접 `onCallStart/onCallEnd` 호출도 가능.
+ *
+ * # 상태 머신
+ *   created → connected ⇄ disconnected,  실패 시 → failed,  종료 진행 중 → disconnecting.
+ *
+ * @module adapters/mega-adapter
+ */
+import { performance } from 'node:perf_hooks'
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { MegaInternalError } from '../errors/http-errors.js'
+
+/**
+ * 어댑터 lifecycle 상태.
+ * @typedef {'created' | 'connected' | 'disconnecting' | 'disconnected' | 'failed'} AdapterState
+ */
+
+/**
+ * 관찰성 hook 리스너 (ADR-077 보강 + span 중첩 seam).
+ *   - `onCallStart(callName, attrs)` — **스코프 토큰을 반환할 수 있다**(예: 트레이서의 OTel span
+ *     context). 반환하면 베이스가 도메인 `fn` 을 그 토큰으로 `run()` 안에서 실행해, 중첩 호출이
+ *     토큰을 부모로 보게 한다(span 계층 정확). 반환 안 하면(`undefined`) 래핑 없이 실행(0 비용).
+ *   - `onCallEnd(callName, attrs, err?, scope?)` — `scope` 는 짝이 되는 `onCallStart` 의 반환 토큰.
+ * 계약: **throw 금지**(베이스가 격리하지만 리스너 측도 자체 보호 권장). 도메인 결과·통계 영향 X.
+ * @typedef {(callName: string, attrs?: object, err?: Error, scope?: any) => any} HookListener
+ */
+
+export class MegaAdapter {
+  /**
+   * 도메인 호출 스코프 토큰 저장소 (ADR-077 보강, span 중첩 seam). `onCallStart` 이 반환한
+   * 토큰을 도메인 `fn` 실행 동안 전파해, 중첩 호출(트랜잭션 안의 query)이 부모 토큰을 보게 한다.
+   * `AsyncLocalStorage.run()` 격리라 동시 top-level 호출도 서로 섞이지 않는다(`enterWith` 누수 회피).
+   * **전 어댑터 공유**(static) — "현재 호출 컨텍스트"는 async 실행 흐름 전역이라, 어댑터 A 의
+   * 트랜잭션 안에서 어댑터 B 를 호출하면 B 의 span 이 A 의 span 밑으로 정확히 묶인다.
+   * 토큰이 없으면(옵트인 OFF) 아예 쓰이지 않아 0 비용.
+   * @type {AsyncLocalStorage<any>}
+   */
+  static #callScope = new AsyncLocalStorage()
+
+  /** @type {object} driver 별 옵션 (생성자 인자). */
+  #config
+  /** @type {AdapterState} */
+  #state = 'created'
+  /** @type {{ requests: number, errors: number, totalLatencyMs: number }} */
+  #stats = { requests: 0, errors: 0, totalLatencyMs: 0 }
+  /** @type {Promise<void> | null} 진행 중 connect — 동시 connect race 가드(L1). */
+  #connectPromise = null
+  /**
+   * 관찰성 hook 리스너 (ADR-077 보강). 외부 트레이서(`MegaTracing`)가 코어/어댑터
+   * 코드 변경 없이 `onCallStart`/`onCallEnd` 를 구독하는 채널이다. 디폴트 `null` — 리스너가 없으면
+   * 디스패치가 즉시 빠져나가 옵트인 OFF 시 0 비용을 보장한다(첫 `addHookListener` 때만 Set 할당).
+   * @type {{ onCallStart: Set<HookListener> | null, onCallEnd: Set<HookListener> | null }}
+   */
+  #hookListeners = { onCallStart: null, onCallEnd: null }
+
+  /**
+   * @param {object} [config] - driver 별 설정 (url / pool / file 등).
+   */
+  constructor(config = {}) {
+    // 추상 클래스 — 직접 인스턴스화 금지 (08-class-specs §3.2 불변식).
+    if (new.target === MegaAdapter) {
+      throw new MegaInternalError(
+        'adapter.abstract_instantiation',
+        'MegaAdapter is abstract — instantiate a concrete adapter (e.g. MegaPostgresAdapter), not the base class.',
+        { details: { class: 'MegaAdapter' } },
+      )
+    }
+    this.#config = config ?? {}
+  }
+
+  /**
+   * 현재 lifecycle 상태 (읽기 전용). 테스트·헬스체크용.
+   * @returns {AdapterState}
+   */
+  get state() {
+    return this.#state
+  }
+
+  /**
+   * driver 설정 (서브클래스 전용 — `_` 접두사 = framework-internal).
+   * @protected
+   * @returns {object}
+   */
+  get _config() {
+    return this.#config
+  }
+
+  // ──────────────────────────────────────────────────────────────────────
+  // lifecycle (베이스가 상태 머신 관리, 실제 연결은 _connect/_disconnect 위임)
+  // ──────────────────────────────────────────────────────────────────────
+
+  /**
+   * 연결 수립. 부팅 시퀀스 6번째 단계에서 호출 (Fastify 인스턴스 생성 직전, ADR-045).
+   * 이미 connected 면 idempotent no-op. disconnecting 중이면 throw.
+   * `_connect()` 가 throw 하면 상태 `failed` 로 두고 원본 에러 전파 (부팅 abort).
+   *
+   * 동시에 두 번 호출되면(아직 첫 호출이 resolve 되기 전) 첫 호출만 `_connect()` 를 실행하고
+   * 나머지는 같은 promise 를 await 한다 — 이중 연결/이중 pool 생성을 막는다(L1).
+   *
+   * @returns {Promise<void>}
+   */
+  async connect() {
+    if (this.#state === 'connected') return // idempotent (connect 두 번)
+    this.#assertNotDisconnecting('connect')
+    // L1: 동시 connect race 가드. 정본 §3.2 상태 집합에 'connecting' 이 없으므로 공개 상태는
+    // 추가하지 않고, 진행 중 promise 를 공유해 _connect() 가 정확히 1회만 실행되게 한다.
+    if (this.#connectPromise) return this.#connectPromise
+    this.#connectPromise = (async () => {
+      try {
+        await this._connect()
+        this.#state = 'connected'
+      } catch (err) {
+        this.#state = 'failed'
+        throw err
+      } finally {
+        this.#connectPromise = null
+      }
+    })()
+    return this.#connectPromise
+  }
+
+  /**
+   * 연결 해제. graceful shutdown 시 등록 역순으로 호출 (07-sequence-diagrams §6).
+   * 아직 연결 안 했거나 이미 끊긴 상태면 idempotent no-op. disconnecting 중 재호출은 throw.
+   * `_disconnect()` 가 throw 하면 상태 `failed` 로 두고 원본 에러 전파(L4) — 정리 실패를
+   * `disconnected`(정상)로 덮지 않는다.
+   *
+   * @returns {Promise<void>}
+   */
+  async disconnect() {
+    if (this.#state === 'created' || this.#state === 'disconnected') return // idempotent
+    this.#assertNotDisconnecting('disconnect')
+    this.#state = 'disconnecting'
+    try {
+      await this._disconnect()
+      this.#state = 'disconnected'
+    } catch (err) {
+      // L4: _disconnect() 실패는 'failed' 로 남긴다(정본 상태 집합의 failed, §3.2). 'disconnected'
+      // 로 덮으면 정리 실패가 silent 정상처럼 보임. 원본 에러는 그대로 전파 — shutdown 측이 로깅.
+      this.#state = 'failed'
+      throw err
+    }
+  }
+
+  /**
+   * 헬스 체크. 디폴트는 연결 상태 반영 — 구체 어댑터가 실제 ping 으로 override 권장.
+   * @returns {Promise<{ ok: boolean, [k: string]: any }>}
+   */
+  async healthCheck() {
+    return { ok: this.#state === 'connected', state: this.#state }
+  }
+
+  /**
+   * 누적 통계 스냅샷 (동기). Prometheus `/metrics` 가 수집 (옵트인, 후속 Phase).
+   * @returns {{ state: AdapterState, requests: number, errors: number, totalLatencyMs: number, avgLatencyMs: number }}
+   */
+  getStats() {
+    const { requests, errors, totalLatencyMs } = this.#stats
+    return {
+      state: this.#state,
+      requests,
+      errors,
+      totalLatencyMs,
+      avgLatencyMs: requests > 0 ? totalLatencyMs / requests : 0,
+    }
+  }
+
+  /**
+   * driver native handle (pg Pool / MongoClient / ioredis Client / NATS Connection 등, ADR-009).
+   * `connect()` 후에만 유효 — 그 외엔 throw (08-class-specs §3.2 불변식).
+   * @returns {any}
+   */
+  get native() {
+    if (this.#state !== 'connected') {
+      throw new MegaInternalError(
+        'adapter.not_connected',
+        `native handle of "${this.constructor.name}" is only available after connect() (state=${this.#state}).`,
+        { details: { adapter: this.constructor.name, state: this.#state } },
+      )
+    }
+    return this._native()
+  }
+
+  // ──────────────────────────────────────────────────────────────────────
+  // 관찰성 hook (ADR-077) — 디폴트 no-op. 트레이싱이 구독.
+  // ──────────────────────────────────────────────────────────────────────
+
+  /**
+   * 현재 호출 스코프 토큰(부모) — 트레이서(`MegaTracing`)가 `onCallStart` 에서 읽어 새 span 의 parent
+   * 로 삼는다. 진행 중인 바깥 도메인 호출이 없으면 `undefined`(= 루트). {@link _instrument} 가 `run()`
+   * 으로 설정. `_` 접두사 = framework-internal(외부 트레이서 lib 가 읽어야 해 OOP protected 는 아님).
+   * @returns {any}
+   */
+  get _currentCallScope() {
+    return MegaAdapter.#callScope.getStore()
+  }
+
+  /**
+   * 도메인 메서드 호출 시작 hook. 디폴트 동작 = 등록된 hook 리스너(ADR-077 보강)로 디스패치.
+   * 구체 어댑터의 도메인 메서드(`query`/`publish`/`get` 등) before 에서 호출됨(또는 `_instrument`).
+   * 리스너가 없으면(옵트인 OFF) 즉시 빠져나간다(0 비용). 트레이싱(`MegaTracing`)이
+   * `addHookListener('onCallStart', fn)` 으로 구독해 span 시작으로 변환 (ADR-077).
+   *
+   * **스코프 토큰**: 리스너가 값을 반환하면 그 중 **첫 정의된 반환**을 스코프 토큰으로 돌려준다.
+   * `_instrument` 는 이 토큰으로 도메인 `fn` 을 `run()` 안에서 실행해 span 중첩을 정확히 만든다.
+   *
+   * @param {string} callName - 'query' | 'publish' | 'get' | ...
+   * @param {object} [attrs] - span 속성. 예: `{ key, statement, args }`.
+   * @returns {any} 스코프 토큰(트레이서의 span context) 또는 `undefined`(중첩 래핑 없음).
+   */
+  onCallStart(callName, attrs) {
+    const set = this.#hookListeners.onCallStart
+    if (set === null) return undefined // 옵트인 OFF — 0 비용 fast path.
+    let scope
+    for (const fn of set) {
+      const r = fn(callName, attrs)
+      if (scope === undefined && r !== undefined) scope = r // 첫 정의된 반환 = 스코프 토큰.
+    }
+    return scope
+  }
+
+  /**
+   * 도메인 메서드 호출 종료 hook. 디폴트 동작 = 등록된 hook 리스너로 디스패치(`onCallStart` 대칭).
+   *
+   * @param {string} callName
+   * @param {object} [attrs] - 결과 속성. 예: `{ rowCount, latencyMs, hit }`.
+   * @param {Error} [err] - 있으면 호출 실패 — span status = ERROR.
+   * @param {any} [scope] - 짝이 되는 `onCallStart` 가 반환한 스코프 토큰(트레이서가 span 종료에 사용).
+   * @returns {void}
+   */
+  onCallEnd(callName, attrs, err, scope) {
+    const set = this.#hookListeners.onCallEnd
+    if (set === null) return // 옵트인 OFF — 0 비용 fast path.
+    for (const fn of set) fn(callName, attrs, err, scope)
+  }
+
+  // ──────────────────────────────────────────────────────────────────────
+  // hook 리스너 API (ADR-077 보강) — 외부 트레이서가 코어 변경 없이 구독.
+  // ──────────────────────────────────────────────────────────────────────
+
+  /**
+   * 관찰성 hook 리스너 등록 (옵션 B — `_instrument` 무변경, 베이스에 구독 채널만 추가).
+   *
+   * `MegaTracing` 같은 외부 트레이서가 어댑터 코드를 건드리지 않고 `onCallStart`/`onCallEnd`
+   * 발화를 구독한다. 같은 리스너 함수의 중복 등록은 `Set` 이라 1회로 합쳐진다.
+   *
+   * @param {'onCallStart' | 'onCallEnd'} hookName
+   * @param {HookListener} listener
+   * @returns {() => void} 등록 해제 함수 (구독 취소 시 호출).
+   * @throws {MegaInternalError} `adapter.invalid_hook` - hookName/listener 가 잘못된 타입.
+   */
+  addHookListener(hookName, listener) {
+    if (hookName !== 'onCallStart' && hookName !== 'onCallEnd') {
+      throw new MegaInternalError(
+        'adapter.invalid_hook',
+        `addHookListener: hookName must be 'onCallStart' or 'onCallEnd' (got '${hookName}').`,
+        { details: { hookName } },
+      )
+    }
+    if (typeof listener !== 'function') {
+      throw new MegaInternalError(
+        'adapter.invalid_hook',
+        `addHookListener('${hookName}'): listener must be a function (got ${typeof listener}).`,
+        { details: { hookName, type: typeof listener } },
+      )
+    }
+    if (this.#hookListeners[hookName] === null) this.#hookListeners[hookName] = new Set()
+    this.#hookListeners[hookName].add(listener)
+    return () => this.removeHookListener(hookName, listener)
+  }
+
+  /**
+   * 관찰성 hook 리스너 해제. 마지막 리스너가 빠지면 Set 을 `null` 로 되돌려 0 비용 fast path 복구.
+   *
+   * @param {'onCallStart' | 'onCallEnd'} hookName
+   * @param {HookListener} listener
+   * @returns {boolean} 실제로 제거됐으면 true (없던 리스너면 false).
+   */
+  removeHookListener(hookName, listener) {
+    const set = hookName === 'onCallStart' || hookName === 'onCallEnd' ? this.#hookListeners[hookName] : null
+    if (set === null || set === undefined) return false
+    const removed = set.delete(listener)
+    if (set.size === 0) this.#hookListeners[hookName] = null // fast path 복구
+    return removed
+  }
+
+  /**
+   * 해당 hook 에 리스너가 1개 이상 붙어 있는지 (Boolean — `has*`, ADR-036).
+   * @param {'onCallStart' | 'onCallEnd'} hookName
+   * @returns {boolean}
+   */
+  hasHookListeners(hookName) {
+    return (hookName === 'onCallStart' || hookName === 'onCallEnd') && this.#hookListeners[hookName] !== null
+  }
+
+  // ──────────────────────────────────────────────────────────────────────
+  // 서브클래스 헬퍼 (protected, `_` 접두사) — 구체 어댑터 구현 지원
+  // ──────────────────────────────────────────────────────────────────────
+
+  /**
+   * 실제 연결 수립. 디폴트 no-op (예: 로그 sink 는 연결 개념 없음).
+   * DB/cache/bus 구체 어댑터는 driver 연결 로직으로 override.
+   * @protected
+   * @returns {Promise<void>}
+   */
+  async _connect() {}
+
+  /**
+   * 실제 연결 해제. 디폴트 no-op. 구체 어댑터가 driver close 로 override.
+   * @protected
+   * @returns {Promise<void>}
+   */
+  async _disconnect() {}
+
+  /**
+   * native handle 반환. 디폴트는 미구현 throw — 구체 어댑터가 override.
+   * @protected
+   * @returns {any}
+   */
+  _native() {
+    return this._notImplemented('native')
+  }
+
+  /**
+   * 도메인 메서드를 hook + 상태 검증 + stats 누적으로 감싸는 표준 보일러플레이트 (roadmap, ADR-077).
+   *
+   * connect 전 호출이면 `adapter.not_connected` throw. 성공/실패 모두 `onCallEnd` 호출 후
+   * 결과 반환 / 원본 에러 re-throw (08-class-specs §3.2 "도메인 메서드 throw → onCallEnd(.., err) 후 re-throw").
+   *
+   * **hook 격리(M1)**: `onCallStart`/`onCallEnd` 는 관찰성 hook 일 뿐 도메인 결과·통계에
+   * 영향을 주면 안 된다. hook 은 **throw 금지**가 계약이지만, 위반(트레이서 버그 등) 시에도
+   * 도메인 호출이 깨지지 않도록 hook 호출을 별도 try/catch 로 격리해 `console.warn` 후 무시한다.
+   * 통계(requests/errors/latency)는 항상 fn 본체의 성공/실패 기준으로만 누적된다.
+   *
+   * **결과 기반 종료 속성**(`extractEndAttrs`): 도메인 호출 결과에서 span 종료 속성을 뽑아야 하는
+   * 경우(예: `query` 의 `rows_affected`)에 쓴다. 성공 시 `extractEndAttrs(result)` 의 반환 객체를
+   * 종료 attrs 에 머지한다. 결과 의존 attr 이 없으면 생략 — 기존 호출부(`withTransaction` 등)는
+   * 4번째 인자 없이 그대로 동작한다(0 변경). 추출기 throw 는 도메인 결과를 깨지 않도록 격리(M1 정합).
+   *
+   * @protected
+   * @template T
+   * @param {string} callName - 도메인 호출 이름 (span 이름 기반).
+   * @param {object} attrs - 시작 span 속성 (`{ key, statement, ... }`).
+   * @param {() => Promise<T>} fn - 실제 driver 호출.
+   * @param {(result: T) => object} [extractEndAttrs] - 결과에서 종료 span 속성 추출(선택). 성공 시만 호출.
+   * @returns {Promise<T>}
+   */
+  async _instrument(callName, attrs, fn, extractEndAttrs) {
+    this._assertConnected(callName)
+    // onCallStart 가 "스코프 토큰"(트레이서의 span context)을 반환하면, 도메인 fn 을 그 토큰으로
+    // `#callScope.run` 안에서 실행한다 — 중첩 호출(트랜잭션 안의 query)이 토큰을 부모로 보게 해
+    // span 계층이 정확해진다(ADR-077 보강). 토큰이 없으면(옵트인 OFF) fn 을 그대로 실행
+    // — run 래퍼가 없어 0 비용. **이 한 줄(run 위임)이 ADR-077 의 _instrument 에 추가된 유일한 seam.**
+    const scope = this.#safeHookStart(callName, attrs)
+    this.#stats.requests += 1
+    const start = performance.now()
+    const exec = scope === undefined ? fn : () => MegaAdapter.#callScope.run(scope, fn)
+    let result
+    try {
+      result = await exec()
+    } catch (err) {
+      // 실패 경로: 통계는 fn 본체 기준으로만(에러 1회), hook 은 격리 호출.
+      const latencyMs = performance.now() - start
+      this.#stats.totalLatencyMs += latencyMs
+      this.#stats.errors += 1
+      this.#safeHookEnd(callName, { ...attrs, latencyMs }, /** @type {Error} */ (err), scope)
+      throw err
+    }
+    // 성공 경로: onCallEnd 가 throw 해도 #safeHookEnd 가 흡수 → 성공이 에러로 오기록되지 않는다(M1).
+    const latencyMs = performance.now() - start
+    this.#stats.totalLatencyMs += latencyMs
+    const endAttrs = { ...attrs, latencyMs }
+    if (typeof extractEndAttrs === 'function') {
+      Object.assign(endAttrs, this.#safeExtractEnd(callName, extractEndAttrs, result))
+    }
+    this.#safeHookEnd(callName, endAttrs, undefined, scope)
+    return result
+  }
+
+  /**
+   * `extractEndAttrs` 격리 호출 — 추출기가 throw 해도 도메인 결과·통계를 보호한다(M1 정합).
+   * throw 시 빈 객체를 돌려 종료 attr 보강 없이 진행. 로거 미주입 베이스라 `console.warn`.
+   *
+   * @param {string} callName
+   * @param {(result: any) => object} extractEndAttrs
+   * @param {any} result
+   * @returns {object}
+   */
+  #safeExtractEnd(callName, extractEndAttrs, result) {
+    try {
+      const out = extractEndAttrs(result)
+      return out && typeof out === 'object' ? out : {}
+    } catch (extractErr) {
+      console.warn(
+        `[MegaAdapter] ${this.constructor.name} extractEndAttrs('${callName}') threw and was ignored — must not throw.`,
+        extractErr,
+      )
+      return {}
+    }
+  }
+
+  /**
+   * `onCallStart` 격리 호출 — hook 이 throw 해도 도메인 호출·통계를 보호하고(M1) 스코프 토큰을 돌려준다.
+   * throw 시 토큰 없이(`undefined`) 진행해 도메인 fn 은 래핑 없이 실행된다. hook throw 는 `console.warn`.
+   *
+   * 로거 미주입 베이스라 `console.warn` 사용 — MegaServer 의 raw 소켓 가드와 동일 패턴(   * 비치명적, 이유 주석 + 로그).
+   *
+   * @param {string} callName
+   * @param {object} [attrs]
+   * @returns {any} 스코프 토큰 또는 `undefined`.
+   */
+  #safeHookStart(callName, attrs) {
+    try {
+      return this.onCallStart(callName, attrs)
+    } catch (hookErr) {
+      console.warn(
+        `[MegaAdapter] ${this.constructor.name}.onCallStart('${callName}') threw and was ignored — observability hooks must not throw.`,
+        hookErr,
+      )
+      return undefined
+    }
+  }
+
+  /**
+   * `onCallEnd` 격리 호출 — `#safeHookStart` 대칭. hook throw 는 흡수 후 `console.warn`(M1 보호).
+   *
+   * @param {string} callName
+   * @param {object} [attrs]
+   * @param {Error} [err]
+   * @param {any} [scope] - 짝이 되는 `onCallStart` 가 반환한 스코프 토큰.
+   * @returns {void}
+   */
+  #safeHookEnd(callName, attrs, err, scope) {
+    try {
+      this.onCallEnd(callName, attrs, err, scope)
+    } catch (hookErr) {
+      console.warn(
+        `[MegaAdapter] ${this.constructor.name}.onCallEnd('${callName}') threw and was ignored — observability hooks must not throw.`,
+        hookErr,
+      )
+    }
+  }
+
+  /**
+   * 도메인 메서드가 connect 전 호출됐는지 검증. 아니면 `adapter.not_connected` throw.
+   * @protected
+   * @param {string} callName
+   * @returns {void}
+   */
+  _assertConnected(callName) {
+    if (this.#state !== 'connected') {
+      throw new MegaInternalError(
+        'adapter.not_connected',
+        `Adapter "${this.constructor.name}" method "${callName}" called before connect() (state=${this.#state}).`,
+        { details: { adapter: this.constructor.name, call: callName, state: this.#state } },
+      )
+    }
+  }
+
+  /**
+   * 미구현 도메인 메서드 stub 용 — 명확한 `adapter.not_implemented` throw.
+   * @protected
+   * @param {string} method
+   * @returns {never}
+   */
+  _notImplemented(method) {
+    throw new MegaInternalError(
+      'adapter.not_implemented',
+      `${this.constructor.name}.${method}() is not implemented.`,
+      { details: { adapter: this.constructor.name, method } },
+    )
+  }
+
+  /**
+   * disconnecting 진행 중 재호출 가드.
+   * @param {string} call
+   * @returns {void}
+   */
+  #assertNotDisconnecting(call) {
+    if (this.#state === 'disconnecting') {
+      throw new MegaInternalError(
+        'adapter.disconnecting',
+        `Adapter "${this.constructor.name}" is disconnecting — "${call}" rejected.`,
+        { details: { adapter: this.constructor.name, call } },
+      )
+    }
+  }
+}

package/src/adapters/mega-bus-adapter.js

@@ -0,0 +1,81 @@
+// @ts-check
+/**
+ * MegaBusAdapter — publish / subscribe / request / job queue 표준 인터페이스 (추상, 08-class-specs §3.5).
+ *
+ * `ctx.bus(key)` 가 본 베이스 인스턴스를 반환. 구체: `MegaNatsAdapter`
+ *. subject prefix `mega.<appName>.<event>` 자동 (옵션, ADR-064).
+ * `enqueue / process` 는 `MegaJob` 백엔드 (ADR-028).
+ *
+ * @module adapters/mega-bus-adapter
+ */
+import { MegaInternalError } from '../errors/http-errors.js'
+import { MegaAdapter } from './mega-adapter.js'
+
+export class MegaBusAdapter extends MegaAdapter {
+  /**
+   * @param {object} [config]
+   */
+  constructor(config) {
+    super(config)
+    if (new.target === MegaBusAdapter) {
+      throw new MegaInternalError(
+        'adapter.abstract_instantiation',
+        'MegaBusAdapter is abstract — use a concrete bus adapter (MegaNatsAdapter).',
+        { details: { class: 'MegaBusAdapter' } },
+      )
+    }
+  }
+
+  /**
+   * fire-and-forget 발행 (ack X).
+   * @param {string} _subject
+   * @param {any} _payload
+   * @returns {Promise<void>}
+   */
+  async publish(_subject, _payload) {
+    return this._notImplemented('publish')
+  }
+
+  /**
+   * 구독. handler 는 `async (msg, replyFn) => void`. 반환된 핸들로 cleanup.
+   * @param {string} _subject
+   * @param {(msg: any, replyFn?: (payload: any) => void) => any} _handler
+   * @returns {Promise<{ unsubscribe: () => Promise<void> }>}
+   */
+  async subscribe(_subject, _handler) {
+    return this._notImplemented('subscribe')
+  }
+
+  /**
+   * req/reply 패턴. timeout 초과 시 `bus.request_timeout` throw.
+   * @param {string} _subject
+   * @param {any} _payload
+   * @param {{ timeout?: number }} [_opts]
+   * @returns {Promise<any>} reply.
+   */
+  async request(_subject, _payload, _opts = {}) {
+    return this._notImplemented('request')
+  }
+
+  /**
+   * 잡 enqueue (MegaJob 백엔드, ADR-028).
+   * @param {string} _jobName
+   * @param {any} _payload
+   * @param {object} [_opts]
+   * @returns {Promise<void>}
+   */
+  async enqueue(_jobName, _payload, _opts = {}) {
+    return this._notImplemented('enqueue')
+  }
+
+  /**
+   * 잡 처리 등록 (MegaJob 백엔드, ADR-028).
+   * @param {string} _jobName
+   * @param {(payload: any) => any} _handler
+   * @param {object} [_opts]
+   * @returns {Promise<void>}
+   */
+  async process(_jobName, _handler, _opts = {}) {
+    return this._notImplemented('process')
+  }
+}

package/src/adapters/mega-cache-adapter.js

@@ -0,0 +1,94 @@
+// @ts-check
+/**
+ * MegaCacheAdapter — key-value 캐시 표준 인터페이스 (추상, 08-class-specs §3.4).
+ *
+ * `ctx.cache(key)` 가 본 베이스 인스턴스를 반환. 구체: `MegaRedisAdapter` /
+ * `MegaFileAdapter` (ADR-082). 사용자 `key` 에 자동 prefix
+ * `mega:cache:<appName>:<key>` 가 코어에서 부착됨 (ADR-064).
+ *
+ * @module adapters/mega-cache-adapter
+ */
+import { MegaInternalError, MegaValidationError } from '../errors/http-errors.js'
+import { MegaAdapter } from './mega-adapter.js'
+
+export class MegaCacheAdapter extends MegaAdapter {
+  /**
+   * @param {object} [config]
+   */
+  constructor(config) {
+    super(config)
+    if (new.target === MegaCacheAdapter) {
+      throw new MegaInternalError(
+        'adapter.abstract_instantiation',
+        'MegaCacheAdapter is abstract — use a concrete cache adapter (MegaRedisAdapter, MegaFileAdapter).',
+        { details: { class: 'MegaCacheAdapter' } },
+      )
+    }
+  }
+
+  /**
+   * @param {string} _key
+   * @returns {Promise<any>} 값 — 없으면 `null` (throw X).
+   */
+  async get(_key) {
+    return this._notImplemented('get')
+  }
+
+  /**
+   * @param {string} _key
+   * @param {any} _value
+   * @param {{ ttl?: number }} [_opts] - `ttl` 미지정 시 무한 (초 단위).
+   * @returns {Promise<void>}
+   */
+  async set(_key, _value, _opts = {}) {
+    return this._notImplemented('set')
+  }
+
+  /**
+   * @param {string} _key
+   * @returns {Promise<void>}
+   */
+  async del(_key) {
+    return this._notImplemented('del')
+  }
+
+  /**
+   * 키 존재 여부 (Boolean — `has*` 접두사, ADR-036). `get` 과 race 가능 — 보장 X.
+   * @param {string} _key
+   * @returns {Promise<boolean>}
+   */
+  async has(_key) {
+    return this._notImplemented('has')
+  }
+
+  /**
+   * ttl 값 검증 헬퍼 (구체 어댑터 `set` 에서 사용). 초 단위 양의 정수만 통과(L3).
+   *
+   * `undefined` = 무한(검증 통과, no-expiry). 그 외엔 다음을 거부하고 `cache.invalid_ttl` throw:
+   *   - 숫자 아님 / `NaN`
+   *   - `Infinity`(무한은 `undefined` 로 표현 — 옵션 `allowInfinity` 로 driver override 가능)
+   *   - 정수 아님(소수 초 — Redis `EX` 등 대부분 정수 초만 허용)
+   *   - 음수
+   *   - `0`(즉시 만료 의미가 driver 마다 달라 모호 — 옵션 `allowZero` 로 override 가능)
+   *
+   * @protected
+   * @param {number} [ttl] - 초 단위 TTL.
+   * @param {{ allowZero?: boolean, allowInfinity?: boolean }} [opts] - driver 별 완화 옵션.
+   * @returns {void}
+   */
+  _assertTtl(ttl, { allowZero = false, allowInfinity = false } = {}) {
+    if (ttl === undefined) return // 무한(no-expiry)
+    /** @param {string} why */
+    const reject = (why) => {
+      throw new MegaValidationError('cache.invalid_ttl', `Invalid cache ttl (${why}): ${ttl}`, {
+        details: { ttl },
+      })
+    }
+    if (typeof ttl !== 'number' || Number.isNaN(ttl)) reject('not a number')
+    else if (ttl === Infinity) {
+      if (!allowInfinity) reject('Infinity — use undefined for no-expiry')
+    } else if (!Number.isInteger(ttl)) reject('not an integer number of seconds')
+    else if (ttl < 0) reject('negative')
+    else if (ttl === 0 && !allowZero) reject('zero')
+  }
+}