mega-framework 0.1.6 → 0.1.7

package/types/lib/logger/telegram-core.d.ts

@@ -0,0 +1,104 @@
+/**
+ * 슬라이딩 윈도우 throttle — 최근 `windowMs` 안에 `max` 건까지만 허용(폭주 시 텔레그램 rate limit 직격 방지).
+ *
+ * @param {number} max - 윈도우당 최대 전송 건수(디폴트 5).
+ * @param {number} windowMs - 윈도우 길이 ms(디폴트 60_000 = 1분).
+ * @returns {{ tryAcquire(now: number): boolean, size(): number }}
+ */
+export function createThrottle(max?: number, windowMs?: number): {
+    tryAcquire(now: number): boolean;
+    size(): number;
+};
+/**
+ * pino 레코드를 텔레그램 메시지 텍스트로 포맷한다. redact 는 메인 스레드 pino 가 이미 적용했으므로
+ * 레코드에는 시크릿이 없다(transport 는 마스킹된 NDJSON 만 받음). 핵심 필드만 추린다(전체 payload X, P5).
+ *
+ * @param {Record<string, any>} record - pino 표준 레코드(JSON 파싱됨).
+ * @param {string} [serviceName]
+ * @returns {string} 텔레그램 sendMessage 용 텍스트.
+ */
+export function formatMessage(record: Record<string, any>, serviceName?: string): string;
+/**
+ * 텔레그램 Bot API `sendMessage` 호출. https 호출은 주입 가능(`httpsRequest`)이라 단위 테스트에서 모킹한다.
+ *
+ * @param {object} args
+ * @param {string} args.botToken
+ * @param {string} args.chatId
+ * @param {string} args.text
+ * @param {(url: string, body: string) => Promise<{ statusCode: number }>} args.httpsRequest - 주입 HTTP.
+ * @returns {Promise<boolean>} 전송 성공(2xx) 여부.
+ * @throws 호출 자체가 throw 하면 호출자(transport)가 retry queue 로 보낸다.
+ */
+export function sendTelegram({ botToken, chatId, text, httpsRequest }: {
+    botToken: string;
+    chatId: string;
+    text: string;
+    httpsRequest: (url: string, body: string) => Promise<{
+        statusCode: number;
+    }>;
+}): Promise<boolean>;
+/**
+ * disk-backed retry queue — 전송 실패한 텍스트를 파일(JSONL)에 쌓고, 다음 기회에 재시도한다(전송 실패해도
+ * 메시지를 잃지 않음, ADR-023).
+ *
+ * # in-process 직렬화 락 (ADR-023)
+ *   단일 스레드라도 `append`(open→write→close)와 `drain`(rename→read→rm)은 각 await 사이에서 **이벤트루프
+ *   인터리브**된다. 인터리브되면 append 의 `open` 이 drain 의 `rename` 보다 먼저 일어날 때, write 가 이미
+ *   rename·rm 된 inode 로 가서 항목이 **유실**된다(rename-claim 의 "유실 0" 이 깨지는 좁은 창). 그래서 큐
+ *   연산을 promise 체인 mutex 로 **직렬화**해 인터리브를 원천 차단한다. 큐 연산은 드물어(전송 실패 시
+ *   append + 주기 drain) 직렬화 비용은 무시 가능. rename-claim 은 cross-process 안전용으로 그대로 둔다.
+ *
+ * # 상한(cap) — 무한 증가 방지 (H4, 최적화 리포트)
+ *   텔레그램이 장기 장애(토큰 만료·차단·네트워크 단절)면 실패분이 무한 적재되고, drain 이 파일 전체를
+ *   메모리로 읽어 재시도→또 실패→전량 재append 한다. 그래서 `drain` 이 **maxAge 만료 + maxEntries 상한**을
+ *   적용해(오래된 것부터 드롭, 드롭 수는 `onDrop` 으로 관측) 디스크·드레인 메모리를 함께 bound 한다.
+ *   write 경로 append rate 는 transport throttle 로 이미 제한되므로 drain 시점 cap 으로 충분하다.
+ */
+export class RetryQueue {
+    /**
+     * @param {string} filePath - JSONL 큐 파일 경로(없으면 비어 있음).
+     * @param {{ maxEntries?: number, maxAgeMs?: number, onDrop?: (count: number) => void }} [opts]
+     *   maxEntries: 보관 최대 항목 수(기본 5000, 0=무제한). maxAgeMs: 항목 최대 보존 ms(기본 24h, 0=무제한).
+     *   onDrop: cap 으로 드롭된 수 통지(관측용).
+     */
+    constructor(filePath: string, { maxEntries, maxAgeMs, onDrop }?: {
+        maxEntries?: number;
+        maxAgeMs?: number;
+        onDrop?: (count: number) => void;
+    });
+    /** @type {string} */
+    _file: string;
+    /** @type {Promise<unknown>} 직렬화 락의 꼬리 — append/drain/clear 를 이 체인에 줄세운다. */
+    _tail: Promise<unknown>;
+    /** @type {number} 보관 최대 항목 수(0=무제한). */
+    _maxEntries: number;
+    /** @type {number} 항목 최대 보존 ms(0=무제한). */
+    _maxAgeMs: number;
+    /** @type {((count: number) => void) | null} cap 드롭 수 통지. */
+    _onDrop: ((count: number) => void) | null;
+    /**
+     * 큐 연산을 직렬화 — 앞 연산이 끝난 뒤(성패 무관) `fn` 을 실행한다. 한 연산의 실패가 다음 연산을 막지
+     * 않도록 락 체인은 에러를 삼키되, 호출자에겐 결과/에러를 그대로 전파한다.
+     * @template T @param {() => Promise<T>} fn @returns {Promise<T>} @private
+     */
+    private _serialize;
+    /**
+     * 실패 메시지를 큐에 append (직렬화됨).
+     * @param {string} text
+     * @returns {Promise<void>}
+     */
+    append(text: string): Promise<void>;
+    /**
+     * 큐 전체를 가로채(claim) 비우고, 각 항목 텍스트 배열을 반환한다. 호출자가 재전송 시도 후, 다시
+     * 실패한 것만 `append` 로 되돌린다.
+     *
+     * read-then-`writeFile('')` 는 두 await 사이에 끼어든 `append` 를 통째로 지운다(producer=write 경로의
+     * 재시도 append, consumer=drain). 그래서 `rename` 으로 **단일 syscall** 가로채기를 쓴다: 가로챈 뒤 들어오는
+     * append 는 새 파일(`this._file`)에 쌓이므로 유실되지 않는다(유실 0, ADR-023/141). 동시 drain 이 한 번 더
+     * 들어오면 파일이 이미 옮겨져 `ENOENT` → 빈 배열(중복 처리 없음).
+     * @returns {Promise<string[]>}
+     */
+    drain(): Promise<string[]>;
+    /** 큐 파일 제거(테스트·정리용, 직렬화됨). @returns {Promise<void>} */
+    clear(): Promise<void>;
+}

package/types/lib/logger/telegram-transport.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 실제 https POST — telegram-core 의 주입 시그니처에 맞춘 thin 래퍼.
+ *
+ * @param {string} url
+ * @param {string} body
+ * @param {{ request?: typeof httpsRequestRaw, timeoutMs?: number }} [deps] - request 는 테스트 주입용(기본=node:https).
+ * @returns {Promise<{ statusCode: number }>}
+ */
+export function httpsPost(url: string, body: string, { request, timeoutMs }?: {
+    request?: typeof httpsRequestRaw;
+    timeoutMs?: number;
+}): Promise<{
+    statusCode: number;
+}>;
+/**
+ * pino transport 진입점 — `{ target: <this>, options }` 로 등록되면 worker 가 이 default export 를 호출한다.
+ *
+ * @param {object} opts
+ * @param {string} opts.botToken
+ * @param {string} opts.chatId
+ * @param {number} [opts.throttleMax] - 윈도우당 최대 전송(디폴트 5).
+ * @param {number} [opts.throttleWindowMs] - 윈도우 ms(디폴트 60_000).
+ * @param {string} [opts.retryDir] - retry queue 디렉터리(디폴트 './logs/telegram-retry').
+ * @param {string} [opts.serviceName]
+ * @param {number} [opts.retryDrainMs] - retry 드레인 주기(디폴트 30_000).
+ * @param {number} [opts.retryMaxEntries] - retry 큐 보관 최대 항목 수(디폴트 5000, 0=무제한, H4 cap).
+ * @param {number} [opts.retryMaxAgeMs] - retry 항목 최대 보존 ms(디폴트 24h, 0=무제한, H4 cap).
+ * @param {(url: string, body: string) => Promise<{ statusCode: number }>} [opts.httpsRequest] - HTTP 주입(기본=httpsPost). 단위 테스트용 seam(ADR-165 동일 패턴) — pino worker 는 미전달.
+ * @returns {import('node:stream').Writable}
+ */
+export default function telegramTransport(opts: {
+    botToken: string;
+    chatId: string;
+    throttleMax?: number;
+    throttleWindowMs?: number;
+    retryDir?: string;
+    serviceName?: string;
+    retryDrainMs?: number;
+    retryMaxEntries?: number;
+    retryMaxAgeMs?: number;
+    httpsRequest?: (url: string, body: string) => Promise<{
+        statusCode: number;
+    }>;
+}): import("node:stream").Writable;
+import { request as httpsRequestRaw } from 'node:https';

package/types/lib/mega-brute-force.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @typedef {object} BruteForceResult - check/fail 반환 형태 (03-api-spec §786).
+ * @property {boolean} locked - 현재 잠김 여부.
+ * @property {boolean} isLocked - `locked` 별칭(Boolean 컨벤션 — 둘 다 노출).
+ * @property {number} attemptsLeft - 잠기기까지 남은 실패 허용 횟수(잠겼으면 0).
+ * @property {number} retryAfterMs - 잠금 해제까지 남은 ms(안 잠겼으면 0).
+ */
+export class MegaBruteForce {
+    /**
+     * @param {object} opts
+     * @param {import('../adapters/mega-cache-adapter.js').MegaCacheAdapter} opts.cache - 연결된 redis 캐시 어댑터(`.native`=ioredis).
+     * @param {string} opts.key - 네임스페이스(도메인 구분). 03-api-spec 의 생성자 `key`.
+     * @param {number} [opts.maxAttempts=5] - 잠금까지 허용 실패 횟수.
+     * @param {number} [opts.windowMs=900000] - 시도 카운트 윈도우(ms). 첫 실패부터 이 시간 뒤 카운터 소멸.
+     * @param {number} [opts.lockMs=900000] - 잠금 지속 시간(ms).
+     * @throws {MegaValidationError} `bruteforce.invalid_option` - cache/key 누락 또는 수치 옵션 비-양의정수.
+     */
+    constructor(opts?: {
+        cache: import("../adapters/mega-cache-adapter.js").MegaCacheAdapter;
+        key: string;
+        maxAttempts?: number;
+        windowMs?: number;
+        lockMs?: number;
+    });
+    /**
+     * 시도 **전** 현재 상태 조회(부수효과 없음). 잠겨 있으면 호출부가 즉시 거부할 수 있다.
+     * @param {string} subject - 대상 식별자(이메일·IP 등).
+     * @returns {Promise<BruteForceResult>}
+     */
+    check(subject: string): Promise<BruteForceResult>;
+    /**
+     * 실패 1건 기록. 카운터를 원자적으로 +1 하고, `maxAttempts` 도달 시 잠금을 건다.
+     * 이미 잠긴 상태면 카운터를 더 늘리지 않고 잠금 정보를 그대로 반환한다.
+     * @param {string} subject - 대상 식별자.
+     * @returns {Promise<BruteForceResult>}
+     */
+    fail(subject: string): Promise<BruteForceResult>;
+    /**
+     * 카운터·잠금 즉시 제거(로그인 성공 등 정상 시도 후).
+     * @param {string} subject - 대상 식별자.
+     * @returns {Promise<void>}
+     */
+    reset(subject: string): Promise<void>;
+    #private;
+}
+/**
+ * - check/fail 반환 형태 (03-api-spec §786).
+ */
+export type BruteForceResult = {
+    /**
+     * - 현재 잠김 여부.
+     */
+    locked: boolean;
+    /**
+     * - `locked` 별칭(Boolean 컨벤션 — 둘 다 노출).
+     */
+    isLocked: boolean;
+    /**
+     * - 잠기기까지 남은 실패 허용 횟수(잠겼으면 0).
+     */
+    attemptsLeft: number;
+    /**
+     * - 잠금 해제까지 남은 ms(안 잠겼으면 0).
+     */
+    retryAfterMs: number;
+};

package/types/lib/mega-circuit-breaker.d.ts

@@ -0,0 +1,241 @@
+/**
+ * 외부 호출을 서킷 브레이커로 감싸 **재사용 가능한** 브레이커를 만든다(보호 함수 1개당 1 브레이커).
+ * `new MegaCircuitBreaker(fn, opts)` 의 함수형 별칭 — 다른 Mega* 유틸(`withRetry`)과 호출 모양 일관.
+ *
+ * @param {(...args: any[]) => Promise<any>} fn - 보호할 비동기 함수.
+ * @param {MegaCircuitBreakerOptions} [options] - 브레이커 옵션.
+ * @returns {MegaCircuitBreaker} 장수(long-lived) 브레이커. 이후 `.fire(...args)` 로 호출.
+ */
+export function wrap(fn: (...args: any[]) => Promise<any>, options?: MegaCircuitBreakerOptions): MegaCircuitBreaker;
+/**
+ * 회로가 **열려** 호출이 거부됐을 때 `fire()` 가 reject 하는 에러의 `code`. 호출부가
+ * `err.code === OPEN_CIRCUIT_ERROR_CODE` 로 "지금은 차단 중" 을 분기 판별할 때 쓴다. (opossum 정본.)
+ * @type {'EOPENBREAKER'}
+ */
+export const OPEN_CIRCUIT_ERROR_CODE: "EOPENBREAKER";
+/**
+ * 호출이 `timeout` ms 를 넘겨 실패 처리된 에러의 `code`. (opossum 정본.)
+ * @type {'ETIMEDOUT'}
+ */
+export const TIMEOUT_ERROR_CODE: "ETIMEDOUT";
+/**
+ * 동시 호출이 `capacity` 한도를 넘어 거부된 에러의 `code`. (opossum 정본.)
+ * @type {'ESEMLOCKED'}
+ */
+export const CAPACITY_ERROR_CODE: "ESEMLOCKED";
+/**
+ * 외부 호출을 서킷 브레이커로 감싸는 래퍼. opossum `CircuitBreaker` 인스턴스 1개를 보유하고, 우리
+ * 컨벤션(Boolean `is*` 게터·`getStats()`·이벤트 화이트리스트)으로 표면을 정리한다.
+ *
+ * @example
+ * const breaker = new MegaCircuitBreaker(callPaymentApi, { timeout: 3000, errorThresholdPercentage: 50 })
+ * breaker.on('open', () => log.warn('payment circuit open'))
+ * try {
+ *   const res = await breaker.fire(orderId)
+ * } catch (e) {
+ *   if (e.code === OPEN_CIRCUIT_ERROR_CODE) return useCachedQuote() // 명시적 폴백
+ *   throw e
+ * }
+ */
+export class MegaCircuitBreaker {
+    /**
+     * @param {(...args: any[]) => Promise<any>} fn - 보호할 비동기 함수(외부 호출).
+     * @param {MegaCircuitBreakerOptions} [options] - 브레이커 옵션.
+     * @throws {TypeError} `fn` 이 함수가 아니면.
+     */
+    constructor(fn: (...args: any[]) => Promise<any>, options?: MegaCircuitBreakerOptions);
+    /**
+     * 보호된 함수를 호출한다. 회로가 closed/halfOpen 이면 원함수를 실행하고, open 이면 원함수를 건너뛰고
+     * 즉시 `EOPENBREAKER` 로 reject 한다(빠른 실패). 결과/에러는 **그대로 전파**(삼키지 않음).
+     *
+     * @param {...any} args - 원함수에 그대로 전달할 인자.
+     * @returns {Promise<any>} 원함수의 반환값. 거부/타임아웃/실패 시 reject(에러 `code` 로 분기).
+     */
+    fire(...args: any[]): Promise<any>;
+    /**
+     * 회로가 열려 있거나 호출이 실패할 때 대신 실행할 폴백을 등록한다. 폴백이 있으면 `fire()` 는 에러로
+     * reject 하지 않고 폴백 반환값으로 resolve 한다(`fallback` 이벤트 발화).
+     *
+     * @param {(...args: any[]) => any} fn - 폴백 함수(동기/비동기 모두 허용). 원호출 인자를 그대로 받는다.
+     * @returns {this} 체이닝용.
+     */
+    fallback(fn: (...args: any[]) => any): this;
+    /**
+     * 브레이커 이벤트를 구독한다(소비자가 분기점에 로그를 박는 지점). 알 수 없는 이벤트명은 오타로
+     * 보고 throw 한다(조용히 무시 금지).
+     *
+     * @param {'fire'|'success'|'failure'|'timeout'|'reject'|'open'|'halfOpen'|'close'|'fallback'|'semaphoreLocked'|'healthCheckFailed'|'shutdown'} event
+     * @param {(...args: any[]) => void} listener
+     * @returns {this} 체이닝용.
+     * @throws {RangeError} 알 수 없는 이벤트명일 때.
+     */
+    on(event: "fire" | "success" | "failure" | "timeout" | "reject" | "open" | "halfOpen" | "close" | "fallback" | "semaphoreLocked" | "healthCheckFailed" | "shutdown", listener: (...args: any[]) => void): this;
+    /**
+     * {@link MegaCircuitBreaker#on} 으로 등록한 리스너를 해제한다. 알 수 없는 이벤트명은 오타로 보고
+     * throw 한다 — `on()` 과 동일한 화이트리스트. 검증 없이 위임하면 오타 이벤트명이 조용히 매칭
+     * 실패해 "해제했다고 믿지만 리스너가 그대로 살아있는" 디버깅 지옥을 만든다. (`removeListener` 별칭도 보호.)
+     *
+     * @param {'fire'|'success'|'failure'|'timeout'|'reject'|'open'|'halfOpen'|'close'|'fallback'|'semaphoreLocked'|'healthCheckFailed'|'shutdown'} event
+     * @param {(...args: any[]) => void} listener
+     * @returns {this} 체이닝용.
+     * @throws {RangeError} 알 수 없는 이벤트명일 때.
+     */
+    off(event: "fire" | "success" | "failure" | "timeout" | "reject" | "open" | "halfOpen" | "close" | "fallback" | "semaphoreLocked" | "healthCheckFailed" | "shutdown", listener: (...args: any[]) => void): this;
+    /**
+     * 1회성 구독(EventEmitter `once`). on() 과 동일 화이트리스트(L-1).
+     * @param {'fire'|'success'|'failure'|'timeout'|'reject'|'open'|'halfOpen'|'close'|'fallback'|'semaphoreLocked'|'healthCheckFailed'|'shutdown'} event
+     * @param {(...args: any[]) => void} listener @returns {this}
+     * @throws {RangeError} 알 수 없는 이벤트명일 때.
+     */
+    once(event: "fire" | "success" | "failure" | "timeout" | "reject" | "open" | "halfOpen" | "close" | "fallback" | "semaphoreLocked" | "healthCheckFailed" | "shutdown", listener: (...args: any[]) => void): this;
+    /**
+     * `on` 의 EventEmitter 별칭. 우회로 화이트리스트를 비껴가지 않도록 동일 검증(L-1).
+     * @param {'fire'|'success'|'failure'|'timeout'|'reject'|'open'|'halfOpen'|'close'|'fallback'|'semaphoreLocked'|'healthCheckFailed'|'shutdown'} event
+     * @param {(...args: any[]) => void} listener @returns {this}
+     * @throws {RangeError} 알 수 없는 이벤트명일 때.
+     */
+    addListener(event: "fire" | "success" | "failure" | "timeout" | "reject" | "open" | "halfOpen" | "close" | "fallback" | "semaphoreLocked" | "healthCheckFailed" | "shutdown", listener: (...args: any[]) => void): this;
+    /**
+     * `off` 의 EventEmitter 별칭. 동일 화이트리스트 검증(L-1).
+     * @param {'fire'|'success'|'failure'|'timeout'|'reject'|'open'|'halfOpen'|'close'|'fallback'|'semaphoreLocked'|'healthCheckFailed'|'shutdown'} event
+     * @param {(...args: any[]) => void} listener @returns {this}
+     * @throws {RangeError} 알 수 없는 이벤트명일 때.
+     */
+    removeListener(event: "fire" | "success" | "failure" | "timeout" | "reject" | "open" | "halfOpen" | "close" | "fallback" | "semaphoreLocked" | "healthCheckFailed" | "shutdown", listener: (...args: any[]) => void): this;
+    /**
+     * 리스너를 큐 앞에 추가(EventEmitter `prependListener`). 동일 화이트리스트 검증(L-1).
+     * @param {'fire'|'success'|'failure'|'timeout'|'reject'|'open'|'halfOpen'|'close'|'fallback'|'semaphoreLocked'|'healthCheckFailed'|'shutdown'} event
+     * @param {(...args: any[]) => void} listener @returns {this}
+     * @throws {RangeError} 알 수 없는 이벤트명일 때.
+     */
+    prependListener(event: "fire" | "success" | "failure" | "timeout" | "reject" | "open" | "halfOpen" | "close" | "fallback" | "semaphoreLocked" | "healthCheckFailed" | "shutdown", listener: (...args: any[]) => void): this;
+    /**
+     * 1회성 리스너를 큐 앞에 추가(EventEmitter `prependOnceListener`). 동일 화이트리스트 검증(L-1).
+     * @param {'fire'|'success'|'failure'|'timeout'|'reject'|'open'|'halfOpen'|'close'|'fallback'|'semaphoreLocked'|'healthCheckFailed'|'shutdown'} event
+     * @param {(...args: any[]) => void} listener @returns {this}
+     * @throws {RangeError} 알 수 없는 이벤트명일 때.
+     */
+    prependOnceListener(event: "fire" | "success" | "failure" | "timeout" | "reject" | "open" | "halfOpen" | "close" | "fallback" | "semaphoreLocked" | "healthCheckFailed" | "shutdown", listener: (...args: any[]) => void): this;
+    /** 회로를 강제로 연다(차단). 테스트/운영 수동 개입용. */
+    open(): void;
+    /** 회로를 강제로 닫는다(정상 복귀). 카운터를 비우고 호출을 다시 흘려보낸다. */
+    close(): void;
+    /** 브레이커를 비활성화한다 — 회로 로직을 우회하고 원함수를 항상 그대로 호출. */
+    disable(): void;
+    /** {@link MegaCircuitBreaker#disable} 를 되돌려 회로 로직을 다시 활성화한다. */
+    enable(): void;
+    /**
+     * 브레이커를 영구 종료한다 — 내부 롤링 윈도우 타이머를 정리한다. **테스트/graceful shutdown 시 필수**
+     * (호출 안 하면 setInterval 타이머가 남아 프로세스/테스트 종료를 막는다).
+     */
+    shutdown(): void;
+    /** @returns {boolean} 회로가 열려(차단) 있으면 true. */
+    get isOpen(): boolean;
+    /** @returns {boolean} 회로가 닫혀(정상) 있으면 true. */
+    get isClosed(): boolean;
+    /** @returns {boolean} 복구 프로빙(half-open) 중이면 true. */
+    get isHalfOpen(): boolean;
+    /** @returns {boolean} 브레이커가 활성(enable) 상태면 true. */
+    get isEnabled(): boolean;
+    /** @returns {boolean} 브레이커가 종료(shutdown)됐으면 true. */
+    get isShutdown(): boolean;
+    /** @returns {string} 브레이커 이름. */
+    get name(): string;
+    /**
+     * 통계 스냅샷을 평탄화해 반환한다(핵심 카운터만). 모니터링/디버그 로그용.
+     * @returns {MegaCircuitBreakerStats}
+     */
+    getStats(): MegaCircuitBreakerStats;
+    /**
+     * 내부 opossum 브레이커 raw 핸들(escape hatch). 여기서 노출하지 않은 opossum 고급 기능(캐시·
+     * coalesce·healthCheck·snapshot 등)이 필요할 때만 직접 접근한다. 어댑터의 `.native` 와 같은 취지.
+     * @returns {import('opossum')<any[], any>}
+     */
+    get raw(): import("opossum")<any[], any>;
+    #private;
+}
+/**
+ * 브레이커 생성 옵션. opossum 옵션 중 **서킷 브레이커 본질에 해당하는 것만** 추려 노출한다(캐시·
+ * coalesce 등 부가 기능은 escape hatch {@link MegaCircuitBreaker#raw} 로 직접 접근). 디폴트는
+ * opossum 정본값을 **명시적으로** 다시 박는다 — opossum 버전 드리프트와 무관하게 동작을 고정.
+ */
+export type MegaCircuitBreakerOptions = {
+    /**
+     * - 단일 호출 제한 시간(ms). 초과 시 `ETIMEDOUT` 으로 실패 처리.
+     * `false`(또는 0)면 타임아웃 끔.
+     */
+    timeout?: number;
+    /**
+     * - 롤링 윈도우 실패율(%)이 이 값을 넘으면 회로 open.
+     */
+    errorThresholdPercentage?: number;
+    /**
+     * - open 상태 유지 시간(ms). 경과 후 halfOpen 으로 1회 프로빙.
+     */
+    resetTimeout?: number;
+    /**
+     * - 실패율 집계 롤링 윈도우 길이(ms).
+     */
+    rollingCountTimeout?: number;
+    /**
+     * - 롤링 윈도우를 나누는 버킷 수.
+     */
+    rollingCountBuckets?: number;
+    /**
+     * - 이 횟수만큼 호출이 쌓이기 전엔 실패율이 높아도 open 안 함
+     * (표본 부족으로 인한 조기 trip 방지). 0=비활성.
+     */
+    volumeThreshold?: number;
+    /**
+     * - 동시 진행(in-flight) 호출 상한. 초과분은 `ESEMLOCKED` 로 즉시 거부.
+     * 미지정=무제한.
+     */
+    capacity?: number;
+    /**
+     * - `true` 반환 시 그 에러는 **실패로 집계하지 않음**
+     * (예: 4xx 같은 "정상적 거절"). 회로 trip 대상에서 제외.
+     */
+    errorFilter?: (err: any, ...args: any[]) => boolean;
+    /**
+     * - 브레이커 이름(이벤트·stats 식별용). 미지정 시 `fn.name || 'anonymous'`.
+     */
+    name?: string;
+};
+/**
+ * 브레이커 통계 스냅샷({@link MegaCircuitBreaker#getStats} 반환). opossum `status.stats` 의 핵심
+ * 카운터만 추려 평탄화한다(핵심 필드만, 페이로드·시크릿 없음).
+ */
+export type MegaCircuitBreakerStats = {
+    /**
+     * - 브레이커 이름.
+     */
+    name: string;
+    /**
+     * - 현재 상태. shutdown 후엔 `'shutdown'`.
+     */
+    state: "closed" | "open" | "halfOpen" | "shutdown";
+    /**
+     * - 누적 호출 시도 수.
+     */
+    fires: number;
+    /**
+     * - 성공 수.
+     */
+    successes: number;
+    /**
+     * - 실패 수.
+     */
+    failures: number;
+    /**
+     * - 타임아웃 수.
+     */
+    timeouts: number;
+    /**
+     * - 회로 open 으로 거부된 수.
+     */
+    rejects: number;
+    /**
+     * - 폴백이 실행된 수.
+     */
+    fallbacks: number;
+};

package/types/lib/mega-cron.d.ts

@@ -0,0 +1,66 @@
+/**
+ * cron 표현식 정적 유틸. 모든 메서드는 상태가 없다(인스턴스화 불필요).
+ *
+ * @example
+ * MegaCron.isValid('0 3 * * *')                 // true
+ * MegaCron.validate('nope')                     // throws Error
+ * MegaCron.next('0 3 * * *', new Date(), { timezone: 'Asia/Seoul' })  // 다음 새벽 3시(KST)
+ */
+export class MegaCron {
+    /**
+     * 표현식을 파싱 검증한다. 유효하면 아무것도 반환하지 않고, 무효면 throw 한다(삼키지 않음).
+     * @param {string} expr - cron 표현식.
+     * @param {MegaCronOptions} [opts] - timezone 등(타임존도 함께 검증).
+     * @returns {void}
+     * @throws {TypeError} expr 이 비문자열/빈 문자열일 때.
+     * @throws {Error} 표현식/타임존 파싱 실패 시(원본은 `.cause`).
+     */
+    static validate(expr: string, opts?: MegaCronOptions): void;
+    /**
+     * 표현식 유효 여부를 throw 없이 boolean 으로 돌려준다. 사용자 입력 검증 UI 등에 쓴다.
+     * @param {string} expr - cron 표현식.
+     * @param {MegaCronOptions} [opts] - timezone 등.
+     * @returns {boolean} 유효하면 true.
+     */
+    static isValid(expr: string, opts?: MegaCronOptions): boolean;
+    /**
+     * `from`(기본=현재) **이후** 첫 발생 시각을 계산한다.
+     * @param {string} expr - cron 표현식.
+     * @param {Date} [from] - 기준 시각(이 시각 이후의 다음 발생). 미지정 시 현재.
+     * @param {MegaCronOptions} [opts] - timezone 등.
+     * @returns {Date} 다음 발생 시각.
+     * @throws {Error} 표현식 무효 시, 또는 이후 발생이 없을 때(예: 일회성 과거 시각).
+     */
+    static next(expr: string, from?: Date, opts?: MegaCronOptions): Date;
+    /**
+     * `from`(기본=현재) 이후 **n개**의 발생 시각을 계산한다. 모니터링/미리보기용.
+     * @param {string} expr - cron 표현식.
+     * @param {number} n - 개수(양의 정수).
+     * @param {Date} [from] - 기준 시각. 미지정 시 현재.
+     * @param {MegaCronOptions} [opts] - timezone 등.
+     * @returns {Date[]} 발생 시각 배열(시간 오름차순). 더 없으면 길이가 n 보다 짧을 수 있다.
+     * @throws {TypeError} n 이 양의 정수가 아닐 때.
+     * @throws {Error} 표현식 무효 시.
+     */
+    static nextRuns(expr: string, n: number, from?: Date, opts?: MegaCronOptions): Date[];
+    /**
+     * `from`(기본=현재) **이전** 가장 가까운 발생 시각을 계산한다(역산). croner `previousRuns(1, ref)` 위임.
+     * @param {string} expr - cron 표현식.
+     * @param {Date} [from] - 기준 시각(이 시각 이전의 가장 최근 발생). 미지정 시 현재.
+     * @param {MegaCronOptions} [opts] - timezone 등.
+     * @returns {Date} 이전 발생 시각.
+     * @throws {Error} 표현식 무효 시, 또는 이전 발생이 없을 때.
+     */
+    static prev(expr: string, from?: Date, opts?: MegaCronOptions): Date;
+}
+/**
+ * cron 계산 옵션. timezone 은 발생 시각 계산에 영향을 준다(예: `0 3 * * *` 를 `Asia/Seoul` 로 보면
+ * 한국 새벽 3시 = UTC 18:00).
+ */
+export type MegaCronOptions = {
+    /**
+     * - IANA 타임존(예: `'Asia/Seoul'`, `'Europe/Stockholm'`). 미지정 시
+     * 호스트 로컬 타임존. 잘못된 타임존은 throw.
+     */
+    timezone?: string;
+};

package/types/lib/mega-hash.d.ts

@@ -0,0 +1,32 @@
+/**
+ * MegaHash — 비밀번호 해싱 진입점. 03-api-spec §765 의 `static password = { hash, verify }` 표면.
+ */
+export class MegaHash {
+    static password: {
+        /**
+         * 비밀번호를 scrypt 로 해시한다. 매 호출 새 random salt → 같은 비밀번호도 매번 다른 해시.
+         *
+         * @param {string} plain - 평문 비밀번호.
+         * @param {{ N?: number, r?: number, p?: number, keylen?: number, saltBytes?: number }} [opts]
+         *   - scrypt 파라미터 오버라이드(미지정 시 ADR-130 디폴트). 강한 보호가 필요할 때만 사용.
+         * @returns {Promise<string>} `$scrypt$N=..,r=..,p=..$<salt>$<hash>` 포맷 문자열.
+         * @throws {MegaValidationError} `hash.invalid_password` - plain 이 비-문자열/빈 문자열.
+         */
+        hash(plain: string, opts?: {
+            N?: number;
+            r?: number;
+            p?: number;
+            keylen?: number;
+            saltBytes?: number;
+        }): Promise<string>;
+        /**
+         * 평문이 저장된 해시와 일치하는지 검증한다(상수 시간 비교). 03-api-spec §765 — verify 는 검증 액션
+         * 자체라 `is*` 접두사 룰의 예외로 동사형 그대로 둔다.
+         *
+         * @param {string} plain - 평문 비밀번호.
+         * @param {string} stored - {@link MegaHash.password.hash} 가 만든 해시 문자열.
+         * @returns {Promise<boolean>} 일치하면 true. 포맷 손상/비-scrypt/불일치는 모두 false(fail-closed).
+         */
+        verify(plain: string, stored: string): Promise<boolean>;
+    };
+}

package/types/lib/mega-health.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 헬스 체크 등록.
+ * @param {string} name
+ * @param {() => Promise<{ ok: boolean, [key: string]: any }> | { ok: boolean }} fn
+ * @param {{ timeoutMs?: number }} [opts] - 체크별 타임아웃(양의 정수 ms, 기본 {@link DEFAULT_CHECK_TIMEOUT_MS}).
+ */
+export function register(name: string, fn: () => Promise<{
+    ok: boolean;
+    [key: string]: any;
+}> | {
+    ok: boolean;
+}, opts?: {
+    timeoutMs?: number;
+}): void;
+/**
+ * 모든 체크 실행 (병렬). 하나라도 false 면 전체 ok=false.
+ * @returns {Promise<{ ok: boolean, checks: Record<string, { ok: boolean, error?: string, [key: string]: any }> }>}
+ */
+export function checkAll(): Promise<{
+    ok: boolean;
+    checks: Record<string, {
+        ok: boolean;
+        error?: string;
+        [key: string]: any;
+    }>;
+}>;
+/**
+ * @returns {Promise<boolean>}
+ */
+export function isReady(): Promise<boolean>;
+/**
+ * 디버그·테스트용.
+ * @returns {number}
+ */
+export function registeredCount(): number;
+/**
+ * 테스트용 reset.
+ */
+export function _reset(): void;
+/** 체크 1개의 기본 타임아웃(ms) — hung 체크가 readiness 응답을 무기한 막지 않게 한다. */
+export const DEFAULT_CHECK_TIMEOUT_MS: 5000;