mega-framework 0.1.5 → 0.1.7

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

@@ -0,0 +1,94 @@
+/**
+ * @typedef {object} FileConfig
+ * @property {string} [driver] - 'file' (매니저가 사용 — 어댑터는 무시).
+ * @property {string} [basePath] - 캐시 파일 저장 디렉토리 (필수).
+ * @property {string} [dir] - `basePath` 의 별칭 (ADR-082 정합, 하위 호환).
+ * @property {{ serializer?: 'json' | 'raw', extension?: string }} [options]
+ */
+/**
+ * @typedef {object} CacheEnvelope - 디스크에 저장되는 단일 파일 포맷.
+ * @property {number} v - 스키마 버전.
+ * @property {string} key - 원본 캐시 key (디버깅용 — 파일명은 해시라 역추적 불가).
+ * @property {any} value - 저장 값(serializer='raw' 면 문자열).
+ * @property {number | null} expiresAt - 만료 epoch ms (무한이면 null).
+ */
+export class MegaFileAdapter extends MegaCacheAdapter {
+    /**
+     * @param {FileConfig} [config] - services.caches.<key> 설정.
+     * @throws {MegaValidationError} `adapter.basepath_required` - basePath/dir 누락.
+     * @throws {MegaValidationError} `adapter.invalid_option` - 옵션 타입/미지원 키 오류.
+     */
+    constructor(config?: FileConfig);
+    /**
+     * raw "디렉토리 핸들" (ADR-009). 파일 어댑터는 native driver 가 없어 basePath 정보를 노출한다.
+     * @protected
+     * @returns {{ basePath: string }}
+     */
+    protected _native(): {
+        basePath: string;
+    };
+    /**
+     * 헬스 체크 — basePath 에 probe 파일을 write→read→unlink 해 실제 읽기/쓰기 가능 확인
+     * (베이스 디폴트는 상태만 반영). 실패는 throw 없이 `ok:false` + 사유(베이스 계약).
+     *
+     * @returns {Promise<{ ok: boolean, driver: 'file', state: string, basePath?: string, error?: string }>}
+     */
+    healthCheck(): Promise<{
+        ok: boolean;
+        driver: "file";
+        state: string;
+        basePath?: string;
+        error?: string;
+    }>;
+    /**
+     * 누적 통계 + file 특화(basePath/serializer/extension).
+     * @returns {ReturnType<import('./mega-adapter.js').MegaAdapter['getStats']> & { driver: string, basePath: string, serializer: string, extension: string }}
+     */
+    getStats(): ReturnType<import("./mega-adapter.js").MegaAdapter["getStats"]> & {
+        driver: string;
+        basePath: string;
+        serializer: string;
+        extension: string;
+    };
+    #private;
+}
+export type FileConfig = {
+    /**
+     * - 'file' (매니저가 사용 — 어댑터는 무시).
+     */
+    driver?: string;
+    /**
+     * - 캐시 파일 저장 디렉토리 (필수).
+     */
+    basePath?: string;
+    /**
+     * - `basePath` 의 별칭 (ADR-082 정합, 하위 호환).
+     */
+    dir?: string;
+    options?: {
+        serializer?: "json" | "raw";
+        extension?: string;
+    };
+};
+/**
+ * - 디스크에 저장되는 단일 파일 포맷.
+ */
+export type CacheEnvelope = {
+    /**
+     * - 스키마 버전.
+     */
+    v: number;
+    /**
+     * - 원본 캐시 key (디버깅용 — 파일명은 해시라 역추적 불가).
+     */
+    key: string;
+    /**
+     * - 저장 값(serializer='raw' 면 문자열).
+     */
+    value: any;
+    /**
+     * - 만료 epoch ms (무한이면 null).
+     */
+    expiresAt: number | null;
+};
+import { MegaCacheAdapter } from './mega-cache-adapter.js';

package/types/adapters/file-session-adapter.d.ts

@@ -0,0 +1,101 @@
+/**
+ * @typedef {object} FileSessionConfig
+ * @property {string} [driver] - 'file' (팩토리가 사용 — 어댑터는 무시).
+ * @property {string} [basePath] - 세션 파일 저장 디렉토리 (필수).
+ * @property {string} [dir] - `basePath` 의 별칭 (하위 호환).
+ * @property {number} [ttlMs] - save() 가 적용할 기본 TTL(ms). 미지정 시 24시간.
+ * @property {number} [cleanupIntervalMs] - 내부 cleanup 타이머 주기(ms). 미지정/0 이면 타이머 없음(단일 dev 편의).
+ * @property {string} [extension] - 파일 확장자 (기본 '.json').
+ */
+/**
+ * @typedef {object} SessionEnvelope - 디스크에 저장되는 단일 파일 포맷.
+ * @property {number} v - 스키마 버전.
+ * @property {string} sid - 원본 세션 id(ULID — 파일명은 해시라 역추적 불가).
+ * @property {object} data - 세션 레코드.
+ * @property {number | null} expiresAt - 만료 epoch ms (무한이면 null).
+ */
+export class MegaFileSessionAdapter extends MegaSessionAdapter {
+    /**
+     * @param {FileSessionConfig} [config]
+     * @throws {MegaValidationError} `session.basepath_required` - basePath/dir 누락.
+     * @throws {MegaValidationError} `session.invalid_option` - 옵션 타입 오류.
+     */
+    constructor(config?: FileSessionConfig);
+    /**
+     * raw "디렉토리 핸들" (ADR-009).
+     * @protected
+     * @returns {{ basePath: string }}
+     */
+    protected _native(): {
+        basePath: string;
+    };
+    /**
+     * 헬스 체크 — basePath 에 probe write→read→unlink 로 실제 읽기/쓰기 가능 확인.
+     * @returns {Promise<{ ok: boolean, driver: 'file', state: string, basePath?: string, error?: string }>}
+     */
+    healthCheck(): Promise<{
+        ok: boolean;
+        driver: "file";
+        state: string;
+        basePath?: string;
+        error?: string;
+    }>;
+    /**
+     * 누적 통계 + file 세션 특화.
+     * @returns {ReturnType<import('./mega-adapter.js').MegaAdapter['getStats']> & { driver: string, basePath: string, ttlMs: number }}
+     */
+    getStats(): ReturnType<import("./mega-adapter.js").MegaAdapter["getStats"]> & {
+        driver: string;
+        basePath: string;
+        ttlMs: number;
+    };
+    #private;
+}
+export type FileSessionConfig = {
+    /**
+     * - 'file' (팩토리가 사용 — 어댑터는 무시).
+     */
+    driver?: string;
+    /**
+     * - 세션 파일 저장 디렉토리 (필수).
+     */
+    basePath?: string;
+    /**
+     * - `basePath` 의 별칭 (하위 호환).
+     */
+    dir?: string;
+    /**
+     * - save() 가 적용할 기본 TTL(ms). 미지정 시 24시간.
+     */
+    ttlMs?: number;
+    /**
+     * - 내부 cleanup 타이머 주기(ms). 미지정/0 이면 타이머 없음(단일 dev 편의).
+     */
+    cleanupIntervalMs?: number;
+    /**
+     * - 파일 확장자 (기본 '.json').
+     */
+    extension?: string;
+};
+/**
+ * - 디스크에 저장되는 단일 파일 포맷.
+ */
+export type SessionEnvelope = {
+    /**
+     * - 스키마 버전.
+     */
+    v: number;
+    /**
+     * - 원본 세션 id(ULID — 파일명은 해시라 역추적 불가).
+     */
+    sid: string;
+    /**
+     * - 세션 레코드.
+     */
+    data: object;
+    /**
+     * - 만료 epoch ms (무한이면 null).
+     */
+    expiresAt: number | null;
+};
+import { MegaSessionAdapter } from './mega-session-adapter.js';

package/types/adapters/index.d.ts

@@ -0,0 +1,20 @@
+export { MegaAdapter } from "./mega-adapter.js";
+export { MegaDbAdapter } from "./mega-db-adapter.js";
+export { MegaCacheAdapter } from "./mega-cache-adapter.js";
+export { MegaBusAdapter } from "./mega-bus-adapter.js";
+export { MegaLockAdapter } from "./mega-lock-adapter.js";
+export { MegaLogSinkAdapter } from "./mega-log-sink-adapter.js";
+export { MegaSessionAdapter } from "./mega-session-adapter.js";
+export { MegaSqliteAdapter } from "./sqlite-adapter.js";
+export { MegaPostgresAdapter } from "./postgres-adapter.js";
+export { MegaMariaAdapter } from "./maria-adapter.js";
+export { MegaMongoAdapter } from "./mongo-adapter.js";
+export { MegaRedisAdapter } from "./redis-adapter.js";
+export { MegaFileAdapter } from "./file-adapter.js";
+export { MegaNatsAdapter } from "./nats-adapter.js";
+export { MegaRedlockAdapter } from "./redlock-adapter.js";
+export { MegaFileSessionAdapter } from "./file-session-adapter.js";
+export { MegaRedisSessionAdapter } from "./redis-session-adapter.js";
+export * as MegaAdapterRegistry from "./registry.js";
+export { BUILTIN_DRIVERS } from "./registry.js";
+export * as MegaAdapterManager from "./adapter-manager.js";

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

@@ -0,0 +1,115 @@
+export class MegaMariaAdapter extends MegaDbAdapter {
+    /**
+     * @param {MariaConfig} [config] - services.databases.<key> 설정.
+     * @throws {MegaValidationError} `adapter.connection_required` - url·discrete 둘 다 없음.
+     * @throws {MegaValidationError} `adapter.connection_conflict` - url + discrete 동시 지정.
+     * @throws {MegaValidationError} `adapter.invalid_option` - 옵션 타입/범위 오류(bigIntStrategy 포함).
+     */
+    constructor(config?: MariaConfig);
+    /** driver 식별자 — dialect 디스패치(getDialect)·CRUD 의 단일 출처(ADR-212). @returns {'mariadb'} */
+    get driver(): "mariadb";
+    /**
+     * raw Pool handle (ADR-009). `connect()` 후에만 베이스 `native` getter 가 호출한다.
+     * @protected
+     * @returns {import('mariadb').Pool}
+     */
+    protected _native(): import("mariadb").Pool;
+    /**
+     * 헬스 체크 — 실제 `SELECT 1` 으로 응답성 확인. 실패는 throw 없이 `ok:false` + 사유(베이스 계약).
+     * 비밀번호/connectionString 은 노출하지 않는다.
+     *
+     * @returns {Promise<{ ok: boolean, driver: 'mariadb', state: string, error?: string }>}
+     */
+    healthCheck(): Promise<{
+        ok: boolean;
+        driver: "mariadb";
+        state: string;
+        error?: string;
+    }>;
+    /**
+     * 누적 통계 + 풀 통계(total/idle/active/queue). 연결 전이면 풀 통계는 0.
+     * @returns {ReturnType<import('./mega-adapter.js').MegaAdapter['getStats']> & { driver: string, pool: { total: number, idle: number, active: number, queue: number } }}
+     */
+    getStats(): ReturnType<import("./mega-adapter.js").MegaAdapter["getStats"]> & {
+        driver: string;
+        pool: {
+            total: number;
+            idle: number;
+            active: number;
+            queue: number;
+        };
+    };
+    /**
+     * 명시적 트랜잭션 경계 (ADR-010, ADR-107). top-level 은 풀 연결 1개 위
+     * `beginTransaction/commit/rollback`, nested 는 같은 연결 위 `SAVEPOINT`(모듈 docstring 참조).
+     *
+     * `fn` 은 **트랜잭션 컨텍스트 연결**(mariadb PoolConnection)을 인자로 받는다. 성공 시 commit(또는
+     * RELEASE SAVEPOINT) 후 반환값을 그대로 돌려주고, throw 시 rollback(또는 ROLLBACK TO SAVEPOINT)
+     * 후 원본 에러 re-throw.
+     *
+     * `opts.isolation`(ADR-190) — top-level 이면 `beginTransaction()` **직전에** 같은 연결에서
+     * `SET TRANSACTION ISOLATION LEVEL` 을 실행한다(MariaDB 의 `SET TRANSACTION` 은 같은 세션의
+     * **다음** 트랜잭션 1회에만 적용 — 공식 문서). 격리수준은 트랜잭션 시작 시 고정되므로
+     * nested(SAVEPOINT) 호출에 지정하면 `adapter.nested_isolation_unsupported` 로 거부한다.
+     *
+     * hook(`onCallStart/onCallEnd`) + 상태 검증 + stats 누적은 `_instrument` 가 처리한다(ADR-077).
+     *
+     * @template T
+     * @param {(conn: import('mariadb').PoolConnection) => Promise<T> | T} fn
+     * @param {{ isolation?: 'read uncommitted' | 'read committed' | 'repeatable read' | 'serializable' }} [opts] - 트랜잭션 옵션(ADR-190).
+     * @returns {Promise<T>}
+     * @throws {MegaInternalError} `adapter.nested_isolation_unsupported` - nested 호출에 isolation 지정.
+     */
+    withTransaction<T>(fn: (conn: import("mariadb").PoolConnection) => Promise<T> | T, opts?: {
+        isolation?: "read uncommitted" | "read committed" | "repeatable read" | "serializable";
+    }): Promise<T>;
+    #private;
+}
+export type MariaConfig = {
+    /**
+     * - 'mariadb' (매니저가 사용 — 어댑터는 무시).
+     */
+    driver?: string;
+    /**
+     * - `mariadb://user:pw@host:port/db` (discrete 필드와 배타, query string 미지원).
+     */
+    url?: string;
+    /**
+     * - `url` 의 deprecated 별칭 (하위 호환).
+     */
+    connectionString?: string;
+    host?: string;
+    port?: number;
+    user?: string;
+    password?: string;
+    database?: string;
+    /**
+     * - 공통 풀 인터페이스.
+     */
+    pool?: {
+        min?: number;
+        max?: number;
+        idleTimeoutMs?: number;
+        acquireTimeoutMs?: number;
+    };
+    /**
+     * - mariadb passthrough + bigIntStrategy.
+     */
+    options?: Record<string, any> & {
+        bigIntStrategy?: "number" | "bigint" | "string";
+    };
+};
+/**
+ * - AsyncLocalStorage 에 담기는 트랜잭션 컨텍스트.
+ */
+export type MariaTxContext = {
+    /**
+     * - 이 트랜잭션을 소유한 풀 연결.
+     */
+    conn: import("mariadb").PoolConnection;
+    /**
+     * - nesting 깊이 (top-level=0, 첫 nested=1, ...).
+     */
+    depth: number;
+};
+import { MegaDbAdapter } from './mega-db-adapter.js';

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

@@ -0,0 +1,215 @@
+/**
+ * 어댑터 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 "__#private@#callScope": AsyncLocalStorage<any>;
+    /**
+     * @param {object} [config] - driver 별 설정 (url / pool / file 등).
+     */
+    constructor(config?: object);
+    /**
+     * 현재 lifecycle 상태 (읽기 전용). 테스트·헬스체크용.
+     * @returns {AdapterState}
+     */
+    get state(): AdapterState;
+    /**
+     * driver 설정 (서브클래스 전용 — `_` 접두사 = framework-internal).
+     * @protected
+     * @returns {object}
+     */
+    protected get _config(): object;
+    /**
+     * 연결 수립. 부팅 시퀀스 6번째 단계에서 호출 (Fastify 인스턴스 생성 직전, ADR-045).
+     * 이미 connected 면 idempotent no-op. disconnecting 중이면 throw.
+     * `_connect()` 가 throw 하면 상태 `failed` 로 두고 원본 에러 전파 (부팅 abort).
+     *
+     * 동시에 두 번 호출되면(아직 첫 호출이 resolve 되기 전) 첫 호출만 `_connect()` 를 실행하고
+     * 나머지는 같은 promise 를 await 한다 — 이중 연결/이중 pool 생성을 막는다(L1).
+     *
+     * @returns {Promise<void>}
+     */
+    connect(): Promise<void>;
+    /**
+     * 연결 해제. graceful shutdown 시 등록 역순으로 호출 (07-sequence-diagrams §6).
+     * 아직 연결 안 했거나 이미 끊긴 상태면 idempotent no-op. disconnecting 중 재호출은 throw.
+     * `_disconnect()` 가 throw 하면 상태 `failed` 로 두고 원본 에러 전파(L4) — 정리 실패를
+     * `disconnected`(정상)로 덮지 않는다.
+     *
+     * @returns {Promise<void>}
+     */
+    disconnect(): Promise<void>;
+    /**
+     * 헬스 체크. 디폴트는 연결 상태 반영 — 구체 어댑터가 실제 ping 으로 override 권장.
+     * @returns {Promise<{ ok: boolean, [k: string]: any }>}
+     */
+    healthCheck(): Promise<{
+        ok: boolean;
+        [k: string]: any;
+    }>;
+    /**
+     * 누적 통계 스냅샷 (동기). Prometheus `/metrics` 가 수집 (옵트인, 후속 Phase).
+     * @returns {{ state: AdapterState, requests: number, errors: number, totalLatencyMs: number, avgLatencyMs: number }}
+     */
+    getStats(): {
+        state: AdapterState;
+        requests: number;
+        errors: number;
+        totalLatencyMs: number;
+        avgLatencyMs: number;
+    };
+    /**
+     * driver native handle (pg Pool / MongoClient / ioredis Client / NATS Connection 등, ADR-009).
+     * `connect()` 후에만 유효 — 그 외엔 throw (08-class-specs §3.2 불변식).
+     * @returns {any}
+     */
+    get native(): any;
+    /**
+     * 현재 호출 스코프 토큰(부모) — 트레이서(`MegaTracing`)가 `onCallStart` 에서 읽어 새 span 의 parent
+     * 로 삼는다. 진행 중인 바깥 도메인 호출이 없으면 `undefined`(= 루트). {@link _instrument} 가 `run()`
+     * 으로 설정. `_` 접두사 = framework-internal(외부 트레이서 lib 가 읽어야 해 OOP protected 는 아님).
+     * @returns {any}
+     */
+    get _currentCallScope(): any;
+    /**
+     * 도메인 메서드 호출 시작 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: string, attrs?: object): any;
+    /**
+     * 도메인 메서드 호출 종료 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: string, attrs?: object, err?: Error, scope?: any): void;
+    /**
+     * 관찰성 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: "onCallStart" | "onCallEnd", listener: HookListener): () => void;
+    /**
+     * 관찰성 hook 리스너 해제. 마지막 리스너가 빠지면 Set 을 `null` 로 되돌려 0 비용 fast path 복구.
+     *
+     * @param {'onCallStart' | 'onCallEnd'} hookName
+     * @param {HookListener} listener
+     * @returns {boolean} 실제로 제거됐으면 true (없던 리스너면 false).
+     */
+    removeHookListener(hookName: "onCallStart" | "onCallEnd", listener: HookListener): boolean;
+    /**
+     * 해당 hook 에 리스너가 1개 이상 붙어 있는지 (Boolean — `has*`, ADR-036).
+     * @param {'onCallStart' | 'onCallEnd'} hookName
+     * @returns {boolean}
+     */
+    hasHookListeners(hookName: "onCallStart" | "onCallEnd"): boolean;
+    /**
+     * 실제 연결 수립. 디폴트 no-op (예: 로그 sink 는 연결 개념 없음).
+     * DB/cache/bus 구체 어댑터는 driver 연결 로직으로 override.
+     * @protected
+     * @returns {Promise<void>}
+     */
+    protected _connect(): Promise<void>;
+    /**
+     * 실제 연결 해제. 디폴트 no-op. 구체 어댑터가 driver close 로 override.
+     * @protected
+     * @returns {Promise<void>}
+     */
+    protected _disconnect(): Promise<void>;
+    /**
+     * native handle 반환. 디폴트는 미구현 throw — 구체 어댑터가 override.
+     * @protected
+     * @returns {any}
+     */
+    protected _native(): any;
+    /**
+     * 도메인 메서드를 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>}
+     */
+    protected _instrument<T>(callName: string, attrs: object, fn: () => Promise<T>, extractEndAttrs?: (result: T) => object): Promise<T>;
+    /**
+     * 도메인 메서드가 connect 전 호출됐는지 검증. 아니면 `adapter.not_connected` throw.
+     * @protected
+     * @param {string} callName
+     * @returns {void}
+     */
+    protected _assertConnected(callName: string): void;
+    /**
+     * 미구현 도메인 메서드 stub 용 — 명확한 `adapter.not_implemented` throw.
+     * @protected
+     * @param {string} method
+     * @returns {never}
+     */
+    protected _notImplemented(method: string): never;
+    #private;
+}
+/**
+ * 어댑터 lifecycle 상태.
+ */
+export type AdapterState = "created" | "connected" | "disconnecting" | "disconnected" | "failed";
+/**
+ * 관찰성 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.
+ */
+export type HookListener = (callName: string, attrs?: object, err?: Error, scope?: any) => any;
+import { AsyncLocalStorage } from 'node:async_hooks';

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

@@ -0,0 +1,45 @@
+export class MegaBusAdapter extends MegaAdapter {
+    /**
+     * fire-and-forget 발행 (ack X).
+     * @param {string} _subject
+     * @param {any} _payload
+     * @returns {Promise<void>}
+     */
+    publish(_subject: string, _payload: any): Promise<void>;
+    /**
+     * 구독. handler 는 `async (msg, replyFn) => void`. 반환된 핸들로 cleanup.
+     * @param {string} _subject
+     * @param {(msg: any, replyFn?: (payload: any) => void) => any} _handler
+     * @returns {Promise<{ unsubscribe: () => Promise<void> }>}
+     */
+    subscribe(_subject: string, _handler: (msg: any, replyFn?: (payload: any) => void) => any): Promise<{
+        unsubscribe: () => Promise<void>;
+    }>;
+    /**
+     * req/reply 패턴. timeout 초과 시 `bus.request_timeout` throw.
+     * @param {string} _subject
+     * @param {any} _payload
+     * @param {{ timeout?: number }} [_opts]
+     * @returns {Promise<any>} reply.
+     */
+    request(_subject: string, _payload: any, _opts?: {
+        timeout?: number;
+    }): Promise<any>;
+    /**
+     * 잡 enqueue (MegaJob 백엔드, ADR-028).
+     * @param {string} _jobName
+     * @param {any} _payload
+     * @param {object} [_opts]
+     * @returns {Promise<void>}
+     */
+    enqueue(_jobName: string, _payload: any, _opts?: object): Promise<void>;
+    /**
+     * 잡 처리 등록 (MegaJob 백엔드, ADR-028).
+     * @param {string} _jobName
+     * @param {(payload: any) => any} _handler
+     * @param {object} [_opts]
+     * @returns {Promise<void>}
+     */
+    process(_jobName: string, _handler: (payload: any) => any, _opts?: object): Promise<void>;
+}
+import { MegaAdapter } from './mega-adapter.js';

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

@@ -0,0 +1,47 @@
+export class MegaCacheAdapter extends MegaAdapter {
+    /**
+     * @param {string} _key
+     * @returns {Promise<any>} 값 — 없으면 `null` (throw X).
+     */
+    get(_key: string): Promise<any>;
+    /**
+     * @param {string} _key
+     * @param {any} _value
+     * @param {{ ttl?: number }} [_opts] - `ttl` 미지정 시 무한 (초 단위).
+     * @returns {Promise<void>}
+     */
+    set(_key: string, _value: any, _opts?: {
+        ttl?: number;
+    }): Promise<void>;
+    /**
+     * @param {string} _key
+     * @returns {Promise<void>}
+     */
+    del(_key: string): Promise<void>;
+    /**
+     * 키 존재 여부 (Boolean — `has*` 접두사, ADR-036). `get` 과 race 가능 — 보장 X.
+     * @param {string} _key
+     * @returns {Promise<boolean>}
+     */
+    has(_key: string): Promise<boolean>;
+    /**
+     * 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}
+     */
+    protected _assertTtl(ttl?: number, { allowZero, allowInfinity }?: {
+        allowZero?: boolean;
+        allowInfinity?: boolean;
+    }): void;
+}
+import { MegaAdapter } from './mega-adapter.js';