mega-framework 0.1.5 → 0.1.7

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

@@ -0,0 +1,47 @@
+export class MegaDbAdapter extends MegaAdapter {
+    /**
+     * 명시적 트랜잭션 경계 (ADR-010). 성공 시 commit, throw 시 rollback.
+     * driver 별 구현 (postgres `BEGIN/COMMIT/ROLLBACK`, MongoDB `session.withTransaction`).
+     * nested 호출은 driver 별 (postgres SAVEPOINT, MongoDB throw `adapter.nested_transaction_unsupported`).
+     *
+     * `opts.isolation`(ADR-190) — SQL 격리수준 옵트인. 미지정이면 driver 디폴트. driver 별 지원:
+     * postgres/maria 는 top-level 트랜잭션에 `SET TRANSACTION ISOLATION LEVEL` 로 반영(nested 엔 불가 —
+     * `adapter.nested_isolation_unsupported`), sqlite 는 항상 SERIALIZABLE 동작이라 'serializable' 만 수용,
+     * mongodb 는 SQL 격리수준 개념이 없어 지정 시 `adapter.invalid_option`.
+     *
+     * @template T
+     * @param {(db: any) => Promise<T>} _fn - 트랜잭션 컨텍스트의 `db` 를 받는 콜백.
+     * @param {{ isolation?: 'read uncommitted' | 'read committed' | 'repeatable read' | 'serializable' }} [_opts] - 트랜잭션 옵션(ADR-190).
+     * @returns {Promise<T>}
+     */
+    withTransaction<T>(_fn: (db: any) => Promise<T>, _opts?: {
+        isolation?: "read uncommitted" | "read committed" | "repeatable read" | "serializable";
+    }): Promise<T>;
+    /**
+     * 계측된 SQL 쿼리 실행 (ADR-138). `_instrument('query', …)` 로 감싸므로 자동 span(`<driver>.query`,
+     * `db.system.name`/`db.query.text`/`mega.rows_affected`)·stats·상태 검증이 한 번에 처리된다.
+     * `MegaModel.db.query`(native handle 직접 호출)와 달리 트레이싱/메트릭에 잡힌다.
+     *
+     * 진행 중 트랜잭션이 있으면 **같은 connection** 위에서 실행해 격리를 유지한다(구체 어댑터가
+     * 트랜잭션 컨텍스트를 인식) — 트랜잭션 밖이면 풀/단일 연결. 결과 형태는 driver native 를 그대로
+     * 돌려준다(ADR-009 — 어댑터별 차이 허용). SQL 어댑터(postgres/maria/sqlite) 만 구현하며,
+     * Document DB(mongo) 는 SQL `query` 개념이 없어 미구현(`adapter.not_implemented`).
+     *
+     * @param {string} _sql - 파라미터화된 SQL(placeholder `$1`/`?` 보존 — 값 인터폴레이션 금지).
+     * @param {any[]} [_params] - placeholder 바인딩 값.
+     * @returns {Promise<any>} driver native 쿼리 결과.
+     */
+    query(_sql: string, _params?: any[]): Promise<any>;
+    /**
+     * `query` span 시작 속성 — 파라미터화된 SQL 만 `statement` 로 싣는다(트레이서가 `db.query.text` 로
+     * 매핑). 문자열이 아니면(쿼리 빌더 객체 등) `mega.query_unparam:true` 로 폴백 — 원본 페이로드
+     * 노출·추측 정제를 피한다(ADR-138). placeholder(`$1`/`?`)는 보존되고 바인딩 값은 싣지 않으므로
+     * 시크릿 누출·라벨 카디널리티 폭증이 없다.
+     *
+     * @protected
+     * @param {unknown} sql
+     * @returns {object}
+     */
+    protected _queryStartAttrs(sql: unknown): object;
+}
+import { MegaAdapter } from './mega-adapter.js';

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

@@ -0,0 +1,62 @@
+export class MegaLockAdapter extends MegaAdapter {
+    /**
+     * 락 획득. `key` 에 대한 상호배제 락을 `opts.ttl`(ms) 동안 잡는다. 이미 다른 곳이 잡고 있으면
+     * retry 설정(opts)만큼 재시도하고, 그래도 못 잡으면 throw(경합은 정상 도메인 결과 — 호출부가 처리).
+     *
+     * @param {string} _key - 락 자원 키.
+     * @param {{ ttl?: number, retryCount?: number, retryDelay?: number, retryJitter?: number }} [_opts]
+     *   - `ttl`(ms, 필수에 준함) 보유 시간. `retryCount/retryDelay/retryJitter` 는 경합 시 재시도 정책(driver 별).
+     * @returns {Promise<any>} 락 핸들(release/extend 에 전달).
+     */
+    acquire(_key: string, _opts?: {
+        ttl?: number;
+        retryCount?: number;
+        retryDelay?: number;
+        retryJitter?: number;
+    }): Promise<any>;
+    /**
+     * 락 해제. 이미 만료/해제됐어도 비치명적(자동 만료가 안전망) — 구체 어댑터는 best-effort 로 처리.
+     * @param {any} _lock - {@link acquire} 가 돌려준 핸들.
+     * @returns {Promise<void>}
+     */
+    release(_lock: any): Promise<void>;
+    /**
+     * 락 TTL 연장. 임계구역이 길어질 때 만료 전에 보유 시간을 늘린다.
+     *
+     * **반환된 핸들을 이후 release/extend 에 써야 한다** — 구체 driver(redlock)가 연장 시 **새 핸들**을
+     * 만들 수 있어, 기존 핸들은 무효가 될 수 있다(ADR-113). 그래서 베이스 계약을 `Promise<void>` 가
+     * 아니라 연장된 핸들 반환으로 둔다.
+     *
+     * @param {any} _lock @param {number} _ttl - 추가 보유 시간(ms).
+     * @returns {Promise<any>} 연장된 락 핸들.
+     */
+    extend(_lock: any, _ttl: number): Promise<any>;
+    /**
+     * convenience — 락을 잡고 `fn` 을 실행한 뒤 **반드시 해제**한다(fn 이 throw 해도 release 보장).
+     *
+     * 구체 driver 가 자동 연장을 지원하면(redlock `using`) fn 실행 중 만료가 임박할 때 자동으로 TTL 을
+     * 늘리고, 연장 실패 시 fn 에 중단 신호(abort signal)를 전달한다 — 이 경우 fn 시그니처는 `(signal)`
+     * 이고, 자동 연장이 없는 단순 구현이면 `(lock)` 을 받는다(구체 어댑터 JSDoc 참조).
+     *
+     * @template T
+     * @param {string} _key @param {{ ttl?: number }} _opts @param {(arg: any) => Promise<T>} _fn
+     * @returns {Promise<T>}
+     */
+    withLock<T>(_key: string, _opts: {
+        ttl?: number;
+    }, _fn: (arg: any) => Promise<T>): Promise<T>;
+    /**
+     * 락 ttl 검증 헬퍼 (구체 어댑터의 acquire/extend/withLock 에서 사용). **밀리초** 양의 정수만 통과.
+     *
+     * cache 의 `_assertTtl`(초 단위, undefined=무한 허용)과 달리 락 ttl 은:
+     *   - **필수** — 무한 락은 데드락 위험이라 허용하지 않는다(undefined 거부).
+     *   - **밀리초** 양의 정수 — 0/음수/소수/비숫자 거부.
+     *
+     * @protected
+     * @param {number} [ttl] - 보유 시간(ms).
+     * @returns {void}
+     * @throws {MegaValidationError} `lock.invalid_ttl`
+     */
+    protected _assertLockTtl(ttl?: number): void;
+}
+import { MegaAdapter } from './mega-adapter.js';

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

@@ -0,0 +1,15 @@
+export class MegaLogSinkAdapter extends MegaAdapter {
+    /**
+     * 로그 레코드 기록 (동기). 비동기 IO 가 필요하면 내부 큐잉 + worker thread (구체별).
+     * @param {object} _record - pino 표준 record.
+     * @returns {void}
+     */
+    write(_record: object): void;
+    /**
+     * 큐 drain + flush 보장. shutdown 마지막 단계 (07-sequence-diagrams §6).
+     * 디폴트는 `disconnect()` 위임 — 구체가 큐 drain 으로 override.
+     * @returns {Promise<void>}
+     */
+    close(): Promise<void>;
+}
+import { MegaAdapter } from './mega-adapter.js';

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

@@ -0,0 +1,32 @@
+export class MegaSessionAdapter extends MegaAdapter {
+    /**
+     * @param {string} _sessionId
+     * @returns {Promise<object | null>} 세션 record — 없으면 `null`.
+     */
+    load(_sessionId: string): Promise<object | null>;
+    /**
+     * @param {string} _sessionId
+     * @param {object} _record
+     * @returns {Promise<void>}
+     */
+    save(_sessionId: string, _record: object): Promise<void>;
+    /**
+     * @param {string} _sessionId
+     * @returns {Promise<void>}
+     */
+    destroy(_sessionId: string): Promise<void>;
+    /**
+     * rolling TTL 갱신 (매 요청, ADR-046).
+     * @param {string} _sessionId
+     * @param {number} _ttlMs
+     * @returns {Promise<void>}
+     */
+    touch(_sessionId: string, _ttlMs: number): Promise<void>;
+    /**
+     * 만료 세션 정리. file 드라이버는 스캔 후 삭제, Redis 는 TTL 자동(no-op). `MegaSchedule` 로 자동 등록
+     * 가능(ADR-129/046).
+     * @returns {Promise<number>} 정리된(삭제된) 세션 수.
+     */
+    cleanup(): Promise<number>;
+}
+import { MegaAdapter } from './mega-adapter.js';

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

@@ -0,0 +1,139 @@
+/**
+ * @typedef {object} MongoTxContext - AsyncLocalStorage 에 담기는 트랜잭션 컨텍스트.
+ * @property {import('mongodb').ClientSession} session - 진행 중 트랜잭션을 소유한 세션.
+ */
+/**
+ * CMAP(Connection Monitoring and Pooling) 이벤트 누적 카운터. mongodb driver 는 풀 통계를
+ * 직접 노출하는 공개 API 가 없어(`topology` 는 비공개 내부), 표준 CMAP 이벤트(기본 발생)를
+ * 구독해 누적한다. open=created-closed, inUse=checkedOut-checkedIn 으로 파생.
+ * @typedef {object} PoolCounters
+ * @property {number} created @property {number} closed
+ * @property {number} checkedOut @property {number} checkedIn
+ */
+export class MegaMongoAdapter extends MegaDbAdapter {
+    /**
+     * @param {MongoConfig} [config] - services.databases.<key> 설정.
+     * @throws {MegaValidationError} `adapter.connection_required` - url·discrete 둘 다 없음.
+     * @throws {MegaValidationError} `adapter.connection_conflict` - url + discrete 동시 지정.
+     * @throws {MegaValidationError} `adapter.dbname_required` - dbName 누락 + url path 에도 없음.
+     * @throws {MegaValidationError} `adapter.invalid_option` - 옵션 타입/범위 오류.
+     */
+    constructor(config?: MongoConfig);
+    /** driver 식별자 — dialect 디스패치·CRUD 의 단일 출처(ADR-212). mongo 는 SQL CRUD 미지원(P3). @returns {'mongodb'} */
+    get driver(): "mongodb";
+    /**
+     * raw Db handle (ADR-009). `connect()` 후에만 베이스 `native` getter 가 호출한다.
+     * @protected
+     * @returns {import('mongodb').Db}
+     */
+    protected _native(): import("mongodb").Db;
+    /**
+     * 헬스 체크 — 실제 `ping` 으로 응답성 확인 (베이스 디폴트는 상태만 반영).
+     * 실패는 throw 없이 `ok:false` + 사유(베이스 계약). 비밀번호/connectionString 은 노출하지 않는다.
+     *
+     * @returns {Promise<{ ok: boolean, driver: 'mongodb', state: string, dbName?: string, error?: string }>}
+     */
+    healthCheck(): Promise<{
+        ok: boolean;
+        driver: "mongodb";
+        state: string;
+        dbName?: string;
+        error?: string;
+    }>;
+    /**
+     * 누적 통계 + mongo 특화(driver/dbName + CMAP 풀 카운터). 연결 전이면 카운터는 0.
+     * @returns {ReturnType<import('./mega-adapter.js').MegaAdapter['getStats']> & { driver: string, dbName: string, pool: { created: number, closed: number, checkedOut: number, checkedIn: number, open: number, inUse: number } }}
+     */
+    getStats(): ReturnType<import("./mega-adapter.js").MegaAdapter["getStats"]> & {
+        driver: string;
+        dbName: string;
+        pool: {
+            created: number;
+            closed: number;
+            checkedOut: number;
+            checkedIn: number;
+            open: number;
+            inUse: number;
+        };
+    };
+    /**
+     * 명시적 트랜잭션 경계 (ADR-010, ADR-108). `session.withTransaction` 에 위임한다 —
+     * driver 가 commit/abort + transient 에러 자동 retry 를 관리(모듈 docstring 참조).
+     *
+     * `fn` 은 `(db, session)` 을 받는다. 성공 시 driver 가 commit 후 `fn` 반환값을 그대로 돌려주고,
+     * throw 시 abort 후 원본 에러를 re-throw 한다. nested 호출은 ALS 로 감지해 거부(Sqlite 와 동일).
+     * `session.endSession()` 은 `finally` 에서 반드시 호출(leak 방지).
+     *
+     * `opts.isolation`(ADR-190) — MongoDB 트랜잭션에는 SQL 격리수준 개념이 없다(snapshot 의미는 driver/
+     * readConcern 관할). 지정 시 `adapter.invalid_option` 으로 명시 거부한다(조용히 무시 X — P4).
+     *
+     * hook(`onCallStart/onCallEnd`) + 상태 검증 + stats 누적은 `_instrument` 가 처리한다(ADR-077).
+     *
+     * @template T
+     * @param {(db: import('mongodb').Db, session: import('mongodb').ClientSession) => Promise<T> | T} fn
+     * @param {{ isolation?: never }} [opts] - 트랜잭션 옵션(ADR-190) — mongodb 는 isolation 미지원.
+     * @returns {Promise<T>}
+     * @throws {MegaInternalError} `adapter.nested_transaction_unsupported` - 이미 트랜잭션 진행 중.
+     * @throws {MegaValidationError} `adapter.invalid_option` - isolation 지정(미지원).
+     */
+    withTransaction<T>(fn: (db: import("mongodb").Db, session: import("mongodb").ClientSession) => Promise<T> | T, opts?: {
+        isolation?: never;
+    }): Promise<T>;
+    #private;
+}
+export type MongoConfig = {
+    /**
+     * - 'mongodb' (매니저가 사용 — 어댑터는 무시).
+     */
+    driver?: string;
+    /**
+     * - `mongodb://...` 연결 문자열 (discrete 와 배타).
+     */
+    url?: string;
+    /**
+     * - `url` 의 deprecated 별칭 (하위 호환).
+     */
+    connectionString?: string;
+    host?: string;
+    port?: number;
+    user?: string;
+    password?: string;
+    /**
+     * - 선택할 DB (url path 에서 추출 가능, 명시 우선).
+     */
+    dbName?: string;
+    /**
+     * - 공통 풀 인터페이스.
+     */
+    pool?: {
+        min?: number;
+        max?: number;
+        idleTimeoutMs?: number;
+        acquireTimeoutMs?: number;
+    };
+    /**
+     * - MongoClient passthrough (authSource, replicaSet, tls, readPreference, serverSelectionTimeoutMS, …).
+     */
+    options?: Record<string, any>;
+};
+/**
+ * - AsyncLocalStorage 에 담기는 트랜잭션 컨텍스트.
+ */
+export type MongoTxContext = {
+    /**
+     * - 진행 중 트랜잭션을 소유한 세션.
+     */
+    session: import("mongodb").ClientSession;
+};
+/**
+ * CMAP(Connection Monitoring and Pooling) 이벤트 누적 카운터. mongodb driver 는 풀 통계를
+ * 직접 노출하는 공개 API 가 없어(`topology` 는 비공개 내부), 표준 CMAP 이벤트(기본 발생)를
+ * 구독해 누적한다. open=created-closed, inUse=checkedOut-checkedIn 으로 파생.
+ */
+export type PoolCounters = {
+    created: number;
+    closed: number;
+    checkedOut: number;
+    checkedIn: number;
+};
+import { MegaDbAdapter } from './mega-db-adapter.js';

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

@@ -0,0 +1,108 @@
+/**
+ * @typedef {object} NatsConfig
+ * @property {string} [driver] - 'nats' (매니저가 사용 — 어댑터는 무시).
+ * @property {string} [url] - `nats://host:port` 연결 문자열 (discrete 와 배타).
+ * @property {string} [connectionString] - `url` 의 deprecated 별칭 (하위 호환).
+ * @property {string} [host] @property {number} [port] @property {string} [user] @property {string} [password]
+ * @property {string} [token] - 토큰 인증 (별도 축 — url/discrete 어느 쪽과도 조합 가능).
+ * @property {any} [pool] - 미지원 — 지정 시 `adapter.invalid_option` throw (NATS 는 단일 연결, ADR-112).
+ * @property {Record<string, any>} [options] - connect() passthrough (name, reconnect, maxReconnectAttempts, pingInterval, tls, jwt, nkey, …).
+ */
+export class MegaNatsAdapter extends MegaBusAdapter {
+    /**
+     * @param {NatsConfig} [config] - services.buses.<key> 설정.
+     * @throws {MegaValidationError} `adapter.connection_required` - url·discrete 둘 다 없음.
+     * @throws {MegaValidationError} `adapter.connection_conflict` - url + discrete 동시 지정.
+     * @throws {MegaValidationError} `adapter.invalid_option` - pool 지정/옵션 타입 오류.
+     */
+    constructor(config?: NatsConfig);
+    /**
+     * raw NatsConnection handle (ADR-009). `connect()` 후에만 베이스 `native` getter 가 호출한다.
+     * @protected
+     * @returns {import('nats').NatsConnection}
+     */
+    protected _native(): import("nats").NatsConnection;
+    /**
+     * 헬스 체크 — 실제 `rtt`(서버 왕복 ping)로 응답성 확인. 실패는 throw 없이 `ok:false` + 사유.
+     * @returns {Promise<{ ok: boolean, driver: 'nats', state: string, server?: string, rttMs?: number, error?: string }>}
+     */
+    healthCheck(): Promise<{
+        ok: boolean;
+        driver: "nats";
+        state: string;
+        server?: string;
+        rttMs?: number;
+        error?: string;
+    }>;
+    /**
+     * 누적 통계 + nats 특화(server + 연결 stats). 연결 전이면 server/stats 는 undefined.
+     * @returns {ReturnType<import('./mega-adapter.js').MegaAdapter['getStats']> & { driver: string, server: string | undefined, nats: import('nats').Stats | undefined }}
+     */
+    getStats(): ReturnType<import("./mega-adapter.js").MegaAdapter["getStats"]> & {
+        driver: string;
+        server: string | undefined;
+        nats: import("nats").Stats | undefined;
+    };
+    /**
+     * 잡 enqueue — 단순 publish (queue group 분배는 `process` 측 책임, ADR-112).
+     * @param {string} jobName
+     * @param {any} payload
+     * @returns {Promise<void>}
+     */
+    enqueue(jobName: string, payload: any): Promise<void>;
+    /**
+     * 잡 처리 등록 — **queue group** 구독(같은 queue 구독자끼리 load-balance). 기본 queue 이름은 jobName
+     * (같은 잡의 모든 워커가 한 그룹).
+     *
+     * ⚠️ **전달 보장 = at-most-once(비영속, H5)**: 이건 **core NATS** queue group 이라 메시지가 디스크에
+     * 남지 않는다 — 구독자가 없거나 처리 중 죽으면 그 메시지는 **유실**된다(재시도·DLQ 없음). 유실이
+     * 치명적이거나 영속 큐/재시도/DLQ 가 필요하면 **`MegaJobQueue`(JetStream, at-least-once, ADR-028/112)**
+     * 를 쓴다. `ctx.bus(x).process` 와 `mega worker`(JetStream) 는 **전달 보장이 다르므로 혼용 금지**.
+     *
+     * **subscription 핸들을 반환하지 않는 건 의도적**(L-2): worker 는 앱 수명 동안 상주하는 것이
+     * 정상이고(개별 잡 처리 등록을 런타임에 떼었다 붙였다 하는 패턴은 비표준), 정리는 disconnect 시
+     * `_disconnect()` 의 `nc.drain()` 이 **모든 구독을 일괄 비우며** 처리한다. 개별 unsubscribe 가
+     * 필요한 일시 구독은 `subscribe()`(핸들 반환)를 쓴다 — `process` 는 fire-and-forget `enqueue` 와
+     * 대칭인 상주 worker 용이다.
+     *
+     * @param {string} jobName
+     * @param {(payload: any) => any} handler
+     * @param {{ queue?: string }} [opts]
+     * @returns {Promise<void>}
+     */
+    process(jobName: string, handler: (payload: any) => any, { queue }?: {
+        queue?: string;
+    }): Promise<void>;
+    #private;
+}
+export type NatsConfig = {
+    /**
+     * - 'nats' (매니저가 사용 — 어댑터는 무시).
+     */
+    driver?: string;
+    /**
+     * - `nats://host:port` 연결 문자열 (discrete 와 배타).
+     */
+    url?: string;
+    /**
+     * - `url` 의 deprecated 별칭 (하위 호환).
+     */
+    connectionString?: string;
+    host?: string;
+    port?: number;
+    user?: string;
+    password?: string;
+    /**
+     * - 토큰 인증 (별도 축 — url/discrete 어느 쪽과도 조합 가능).
+     */
+    token?: string;
+    /**
+     * - 미지원 — 지정 시 `adapter.invalid_option` throw (NATS 는 단일 연결, ADR-112).
+     */
+    pool?: any;
+    /**
+     * - connect() passthrough (name, reconnect, maxReconnectAttempts, pingInterval, tls, jwt, nkey, …).
+     */
+    options?: Record<string, any>;
+};
+import { MegaBusAdapter } from './mega-bus-adapter.js';

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

@@ -0,0 +1,139 @@
+/**
+ * @typedef {object} PostgresConfig
+ * @property {string} [driver] - 'postgres' (매니저가 사용 — 어댑터는 무시).
+ * @property {string} [url] - `postgres://user:pw@host:port/db` (discrete 필드와 배타).
+ * @property {string} [connectionString] - `url` 의 deprecated 별칭 (하위 호환).
+ * @property {string} [host] @property {number} [port] @property {string} [user]
+ * @property {string} [password] @property {string} [database]
+ * @property {{ min?: number, max?: number, idleTimeoutMs?: number, acquireTimeoutMs?: number, maxLifetimeMs?: number }} [pool] - 공통 풀 인터페이스.
+ * @property {Record<string, any>} [options] - pg.Pool passthrough (ssl, statement_timeout, application_name, keepAlive, query_timeout, …).
+ */
+/**
+ * @typedef {object} PgTxContext - AsyncLocalStorage 에 담기는 트랜잭션 컨텍스트.
+ * @property {import('pg').PoolClient} client - 이 트랜잭션을 소유한 풀 클라이언트.
+ * @property {number} depth - nesting 깊이 (top-level=0, 첫 nested=1, ...).
+ */
+export class MegaPostgresAdapter extends MegaDbAdapter {
+    /**
+     * @param {PostgresConfig} [config] - services.databases.<key> 설정.
+     * @throws {import('../errors/http-errors.js').MegaValidationError} `adapter.connection_required` - url·discrete 둘 다 없음.
+     * @throws {import('../errors/http-errors.js').MegaValidationError} `adapter.connection_conflict` - url + discrete 동시 지정.
+     * @throws {import('../errors/http-errors.js').MegaValidationError} `adapter.invalid_option` - 옵션 타입/범위 오류.
+     */
+    constructor(config?: PostgresConfig);
+    /** driver 식별자 — dialect 디스패치(getDialect)·CRUD 의 단일 출처(ADR-212). @returns {'postgres'} */
+    get driver(): "postgres";
+    /**
+     * raw Pool handle (ADR-009). `connect()` 후에만 베이스 `native` getter 가 호출한다.
+     * @protected
+     * @returns {import('pg').Pool}
+     */
+    protected _native(): import("pg").Pool;
+    /**
+     * 헬스 체크 — 실제 `SELECT 1` 으로 응답성 확인 (베이스 디폴트는 상태만 반영).
+     * 실패는 throw 없이 `ok:false` + 사유(베이스 계약). 비밀번호/connectionString 은 노출하지 않는다.
+     *
+     * @returns {Promise<{ ok: boolean, driver: 'postgres', state: string, error?: string }>}
+     */
+    healthCheck(): Promise<{
+        ok: boolean;
+        driver: "postgres";
+        state: string;
+        error?: string;
+    }>;
+    /**
+     * 누적 통계 + 풀 통계(total/idle/waiting). 연결 전이면 풀 통계는 0.
+     * @returns {ReturnType<import('./mega-adapter.js').MegaAdapter['getStats']> & { driver: string, pool: { total: number, idle: number, waiting: number } }}
+     */
+    getStats(): ReturnType<import("./mega-adapter.js").MegaAdapter["getStats"]> & {
+        driver: string;
+        pool: {
+            total: number;
+            idle: number;
+            waiting: number;
+        };
+    };
+    /**
+     * 명시적 트랜잭션 경계 (ADR-010, ADR-106). top-level 은 풀 클라이언트 1개 위 manual
+     * `BEGIN/COMMIT/ROLLBACK`, nested 는 같은 클라이언트 위 `SAVEPOINT`(모듈 docstring 참조).
+     *
+     * `fn` 은 **트랜잭션 컨텍스트 클라이언트**(pg PoolClient)를 인자로 받는다. 성공 시 COMMIT(또는
+     * RELEASE SAVEPOINT) 후 `fn` 반환값을 그대로 돌려주고, throw 시 ROLLBACK(또는 ROLLBACK TO
+     * SAVEPOINT) 후 원본 에러를 re-throw 한다.
+     *
+     * `opts.isolation`(ADR-190) — top-level 이면 `BEGIN` 직후 `SET TRANSACTION ISOLATION LEVEL` 로
+     * 반영한다(PostgreSQL 은 트랜잭션 첫 쿼리 전이라 유효). 격리수준은 트랜잭션 시작 시 고정되므로
+     * nested(SAVEPOINT) 호출에 지정하면 `adapter.nested_isolation_unsupported` 로 거부한다.
+     *
+     * hook(`onCallStart/onCallEnd`) + 상태 검증 + stats 누적은 `_instrument` 가 처리한다(ADR-077).
+     *
+     * @template T
+     * @param {(client: import('pg').PoolClient) => 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: (client: import("pg").PoolClient) => Promise<T> | T, opts?: {
+        isolation?: "read uncommitted" | "read committed" | "repeatable read" | "serializable";
+    }): Promise<T>;
+    /**
+     * 계측된 SQL 쿼리 (ADR-138). 진행 중 트랜잭션이 있으면 그 컨텍스트의 클라이언트를, 없으면 풀을
+     * 통해 실행한다 — 트랜잭션 안에서 호출해도 같은 connection 을 써 격리가 유지된다(풀의 다른
+     * 커넥션을 잡아 트랜잭션 밖으로 새지 않음). `_instrument('query', …)` 가 자동 span(`postgres.query`,
+     * `db.system.name`/`db.query.text`/`mega.rows_affected`)·stats·상태 검증을 처리한다. 결과는 pg 의
+     * `QueryResult`(`{ rows, rowCount, … }`)를 그대로 돌려준다(ADR-009).
+     *
+     * @param {string} sql - 파라미터화된 SQL(placeholder `$1` 보존).
+     * @param {any[]} [params] - placeholder 바인딩 값.
+     * @returns {Promise<import('pg').QueryResult>}
+     */
+    query(sql: string, params?: any[]): Promise<import("pg").QueryResult>;
+    #private;
+}
+export type PostgresConfig = {
+    /**
+     * - 'postgres' (매니저가 사용 — 어댑터는 무시).
+     */
+    driver?: string;
+    /**
+     * - `postgres://user:pw@host:port/db` (discrete 필드와 배타).
+     */
+    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;
+        maxLifetimeMs?: number;
+    };
+    /**
+     * - pg.Pool passthrough (ssl, statement_timeout, application_name, keepAlive, query_timeout, …).
+     */
+    options?: Record<string, any>;
+};
+/**
+ * - AsyncLocalStorage 에 담기는 트랜잭션 컨텍스트.
+ */
+export type PgTxContext = {
+    /**
+     * - 이 트랜잭션을 소유한 풀 클라이언트.
+     */
+    client: import("pg").PoolClient;
+    /**
+     * - nesting 깊이 (top-level=0, 첫 nested=1, ...).
+     */
+    depth: number;
+};
+import { MegaDbAdapter } from './mega-db-adapter.js';

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

@@ -0,0 +1,70 @@
+export class MegaRedisAdapter extends MegaCacheAdapter {
+    /**
+     * @param {RedisConfig} [config] - services.caches.<key> 설정.
+     * @throws {MegaValidationError} `adapter.connection_required` - url·discrete 둘 다 없음.
+     * @throws {MegaValidationError} `adapter.connection_conflict` - url + discrete 동시 지정.
+     * @throws {MegaValidationError} `adapter.invalid_option` - pool 지정/옵션 타입 오류/db 범위 오류.
+     */
+    constructor(config?: RedisConfig);
+    /**
+     * raw ioredis handle (ADR-009). `connect()` 후에만 베이스 `native` getter 가 호출한다.
+     * @protected
+     * @returns {import('ioredis').Redis}
+     */
+    protected _native(): import("ioredis").Redis;
+    /**
+     * 헬스 체크 — 실제 `ping` 으로 응답성 확인 (베이스 디폴트는 상태만 반영).
+     * 실패는 throw 없이 `ok:false` + 사유(베이스 계약). 비밀번호/url 은 노출하지 않는다.
+     *
+     * @returns {Promise<{ ok: boolean, driver: 'redis', state: string, db?: number, error?: string }>}
+     */
+    healthCheck(): Promise<{
+        ok: boolean;
+        driver: "redis";
+        state: string;
+        db?: number;
+        error?: string;
+    }>;
+    /**
+     * 누적 통계 + redis 특화(driver/db/연결 status). 연결 status 는 ioredis 의 connection 상태 문자열
+     * ('wait'|'connecting'|'connect'|'ready'|'close'|'end' 등) — 풀이 없어 이걸 노출한다.
+     * @returns {ReturnType<import('./mega-adapter.js').MegaAdapter['getStats']> & { driver: string, db: number | undefined, status: string | undefined }}
+     */
+    getStats(): ReturnType<import("./mega-adapter.js").MegaAdapter["getStats"]> & {
+        driver: string;
+        db: number | undefined;
+        status: string | undefined;
+    };
+    #private;
+}
+export type RedisConfig = {
+    /**
+     * - 'redis' (매니저가 사용 — 어댑터는 무시).
+     */
+    driver?: string;
+    /**
+     * - `redis://[:pw@]host:port[/db]` 연결 문자열 (discrete 와 배타).
+     */
+    url?: string;
+    /**
+     * - `url` 의 deprecated 별칭 (하위 호환).
+     */
+    connectionString?: string;
+    host?: string;
+    port?: number;
+    user?: string;
+    password?: string;
+    /**
+     * - 논리 DB 번호 0~15 (connection 과 별개 축, url path 보다 우선).
+     */
+    db?: number;
+    /**
+     * - 미지원 — 지정 시 `adapter.invalid_option` throw (Redis 는 풀 모델 아님, ADR-110).
+     */
+    pool?: any;
+    /**
+     * - ioredis passthrough (keyPrefix, commandTimeout, tls, retryStrategy, keepAlive, …).
+     */
+    options?: Record<string, any>;
+};
+import { MegaCacheAdapter } from './mega-cache-adapter.js';