mega-framework 0.1.6 → 0.1.8

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

@@ -0,0 +1,285 @@
+/**
+ * 활성 여부 (Boolean — `is*`). `init` 후 `shutdown` 전이면 true.
+ * @returns {boolean}
+ */
+export function isEnabled(): boolean;
+/**
+ * OTel 메트릭 초기화. 옵트인 — 본 함수를 부르지 않으면 모든 `record*` 가 0 비용 no-op.
+ *
+ * @param {object} opts
+ * @param {string} opts.serviceName - **필수**. `service.name` resource 속성.
+ * @param {string} [opts.version] - `service.version`.
+ * @param {string} [opts.environment] - `deployment.environment.name`.
+ * @param {Record<string, any>} [opts.attributes] - 추가 resource 속성(머지). 시크릿 금지.
+ * @returns {void}
+ * @throws {MegaConfigError} `metrics.already_initialized` / `metrics.service_name_required`.
+ */
+export function init(opts?: {
+    serviceName: string;
+    version?: string;
+    environment?: string;
+    attributes?: Record<string, any>;
+}): void;
+/**
+ * `MEGA_METRICS_*` / `METRICS_ENABLED` 환경변수로 옵트인 초기화 (12-factor). 비활성이면 **no-op**.
+ * `/metrics` 자체는 `health.exposeMetrics` config 로 켜지지만(ADR-072), SDK 초기화는 env 로도 가능하게
+ * 트레이싱(`MegaTracing.fromEnv`)과 대칭으로 둔다. 둘 중 하나라도 켜지면 활성.
+ *
+ * 매핑:
+ *   - `METRICS_ENABLED` 또는 `MEGA_METRICS_ENABLED` (true 면 활성)
+ *   - `MEGA_METRICS_SERVICE_NAME` → serviceName (없으면 `MEGA_OTEL_SERVICE_NAME` 폴백)
+ *   - `MEGA_METRICS_VERSION` / `MEGA_METRICS_ENVIRONMENT` → resource 속성
+ *
+ * @param {Record<string, string|undefined>} [env=process.env]
+ * @returns {boolean} 활성화돼 init 했으면 true, 옵트인 OFF 면 false.
+ * @throws {MegaConfigError} 활성인데 serviceName 누락 시 `metrics.service_name_required`.
+ */
+export function fromEnv(env?: Record<string, string | undefined>): boolean;
+/**
+ * 현재 누적된 메트릭을 Prometheus 텍스트(exposition format)로 직렬화한다. `/metrics` 라우트와 테스트가
+ * **같은 경로**로 사용한다. 옵트인 OFF 면 빈 문자열.
+ * @returns {Promise<string>}
+ */
+export function collect(): Promise<string>;
+/**
+ * 트레이싱 종료 대칭 — provider 종료(+ 구독 해제). init 전이면 no-op.
+ * @returns {Promise<void>}
+ */
+export function shutdown(): Promise<void>;
+/**
+ * HTTP 요청 1건 기록 — 카운터 +1 + latency 히스토그램. mega-app `onResponse` hook 이 호출.
+ * @param {object} info
+ * @param {string} info.method - HTTP 메서드(대문자).
+ * @param {string} [info.route] - **매칭된 라우트 패턴**(`/users/:id`). 없으면 `__unmatched__`(M-A).
+ * @param {number} info.statusCode - 응답 상태코드.
+ * @param {number} info.durationMs - 처리 시간(ms).
+ * @param {string} info.app - 앱 이름.
+ * @returns {void}
+ */
+export function recordHttp({ method, route, statusCode, durationMs, app }: {
+    method: string;
+    route?: string;
+    statusCode: number;
+    durationMs: number;
+    app: string;
+}): void;
+/**
+ * WebSocket 메시지 1건 기록. ws 수신 배선이 호출.
+ * @param {object} info
+ * @param {string} info.type - 메시지 타입(라우트 키처럼 bounded 한 값만 — raw payload X).
+ * @param {string} [info.ns] - 네임스페이스.
+ * @param {number} [info.durationMs] - 처리 시간(ms). 있으면 히스토그램 기록.
+ * @param {string} [info.app] - 앱 이름.
+ * @returns {void}
+ */
+export function recordWs({ type, ns, durationMs, app }: {
+    type: string;
+    ns?: string;
+    durationMs?: number;
+    app?: string;
+}): void;
+/**
+ * 어댑터 호출 1건 기록 — 도메인/드라이버/콜별 카운터 + latency. 보통 `subscribe`(onCallEnd)가 호출.
+ * @param {object} info
+ * @param {string} info.domain - db|cache|bus|lock.
+ * @param {string} info.driver - 드라이버명(postgres|redis|nats|…).
+ * @param {string} info.call - 도메인 콜명(query|get|publish|acquire|…).
+ * @param {number} info.durationMs - latency(ms).
+ * @param {boolean} info.isError - 실패 여부.
+ * @returns {void}
+ */
+export function recordAdapterCall({ domain, driver, call, durationMs, isError }: {
+    domain: string;
+    driver: string;
+    call: string;
+    durationMs: number;
+    isError: boolean;
+}): void;
+/**
+ * 잡 큐 이벤트 1건 기록(enqueued|processed|retried|dlq). MegaJobQueue/Worker 가 호출.
+ * @param {object} info
+ * @param {string} info.queue - 큐 이름.
+ * @param {'enqueued'|'processed'|'retried'|'dlq'} info.event
+ * @returns {void}
+ */
+export function recordJob({ queue, event }: {
+    queue: string;
+    event: "enqueued" | "processed" | "retried" | "dlq";
+}): void;
+/**
+ * 세션 이벤트 1건 기록(created|destroyed). 세션 미들웨어가 호출.
+ * @param {object} info
+ * @param {string} [info.driver] - file|redis.
+ * @param {'created'|'destroyed'} info.event
+ * @returns {void}
+ */
+export function recordSession({ driver, event }: {
+    driver?: string;
+    event: "created" | "destroyed";
+}): void;
+/**
+ * 브루트포스 이벤트 1건 기록(check|fail|lockout|reset). MegaBruteForce 가 호출.
+ * subject(이메일·IP)는 **라벨에 절대 안 넣는다** — 카디널리티 폭증 + PII. namespace 만 라벨.
+ * @param {object} info
+ * @param {string} info.namespace - 도메인 네임스페이스(login|password-reset|…).
+ * @param {'check'|'fail'|'lockout'|'reset'} info.event
+ * @returns {void}
+ */
+export function recordBruteForce({ namespace, event }: {
+    namespace: string;
+    event: "check" | "fail" | "lockout" | "reset";
+}): void;
+/**
+ * 파일 업로드 결과 1건 기록. multipart 통합(`src/core/multipart.js`)이 호출.
+ *
+ * - 카운터 `mega_upload_files_total{app,result}` +1 — result 는 **bounded enum** 만:
+ *   `accepted`(MIME 화이트리스트 통과) / `rejected_mime`(비허용 MIME) / `saved`(디스크 저장 완료).
+ *   파일명·MIME 문자열은 라벨에 **안 넣는다** — 카디널리티 폭증·PII 방지. 크기 초과(413)·개수
+ *   초과(413)는 @fastify/multipart 가 네이티브로 throw 하므로 `mega_http_requests_total{status_code="413"}`
+ *   로 이미 관측된다(중복 집계 안 함).
+ * - `bytes` 가 주어지면 히스토그램 `mega_upload_file_bytes{app}` 에 분포 기록(저장 완료 시점).
+ *
+ * @param {object} info
+ * @param {string} [info.app] - 앱 이름.
+ * @param {'accepted'|'rejected_mime'|'saved'} info.result - 업로드 결과(bounded enum).
+ * @param {number} [info.bytes] - 파일 크기(바이트). 있으면 히스토그램 기록.
+ * @returns {void}
+ */
+export function recordUpload({ app, result, bytes }: {
+    app?: string;
+    result: "accepted" | "rejected_mime" | "saved";
+    bytes?: number;
+}): void;
+/**
+ * i18n 이벤트 1건 집계(ADR-135). init 전이면 no-op.
+ *
+ * - `event='request'`: 요청별 결정 언어 분포(앱·언어 라벨). onRequest 1회.
+ * - `event='missing'`: 누락 키(dev saveMissing 신호 — 앱·언어·scope 라벨). 키 자체는 라벨 미노출(카디널리티).
+ *
+ * lang/scope 는 `available`·{server,client} 로 bounded 라 카디널리티 안전.
+ *
+ * @param {object} info
+ * @param {string} [info.app] - 앱 이름.
+ * @param {string} info.lang - 결정/요청 언어.
+ * @param {string} [info.scope] - namespace scope(missing 시 server|client). request 면 생략.
+ * @param {'request'|'missing'} info.event
+ * @returns {void}
+ */
+export function recordI18n({ app, lang, scope, event }: {
+    app?: string;
+    lang: string;
+    scope?: string;
+    event: "request" | "missing";
+}): void;
+/**
+ * 템플릿 렌더 1건 기록(ADR-136). init 전이면 no-op. 템플릿 통합(`src/core/template.js`)이 호출.
+ *
+ * - 카운터 `mega_template_renders_total{app,result}` +1 — result 는 **bounded enum** 만:
+ *   `rendered`(성공) / `error`(렌더 실패 — 문법 오류·파일 없음·참조 throw). view 이름·경로는 라벨에
+ *   **안 넣는다** — 카디널리티 폭증·경로 노출 방지(upload/i18n 패턴 정합).
+ * - `durationMs` 가 주어지면 히스토그램 `mega_template_render_duration_seconds{app}` 에 분포 기록.
+ * - `bytes` 는 span 속성으로만 남기고 메트릭 라벨엔 안 쓴다(렌더 시간이 운영 신호 — 크기는 응답 메트릭과 중복).
+ *
+ * @param {object} info
+ * @param {string} [info.app] - 앱 이름.
+ * @param {'rendered'|'error'} info.result - 렌더 결과(bounded enum).
+ * @param {number} [info.durationMs] - 렌더 소요(ms). 있으면 히스토그램 기록(초 단위 변환).
+ * @param {number} [info.bytes] - 렌더 바이트(현재 메트릭 미사용 — 시그니처 호환·향후 확장용).
+ * @returns {void}
+ */
+export function recordTemplate({ app, result, durationMs }: {
+    app?: string;
+    result: "rendered" | "error";
+    durationMs?: number;
+    bytes?: number;
+}): void;
+/**
+ * 단일 어댑터의 `onCallEnd` 를 구독해 호출 메트릭으로 변환한다. init 전이면 no-op. 중복 구독 방지.
+ * @param {import('../adapters/mega-adapter.js').MegaAdapter} adapter
+ * @param {{ domain?: string, driver?: string, key?: string }} [meta]
+ * @returns {() => void} 구독 해제 함수.
+ */
+export function subscribe(adapter: import("../adapters/mega-adapter.js").MegaAdapter, meta?: {
+    domain?: string;
+    driver?: string;
+    key?: string;
+}): () => void;
+/**
+ * 부팅된 전역 어댑터 매니저의 모든 공유 어댑터에 onCallEnd 리스너를 일괄 구독한다(트레이싱 attachToManager 대칭).
+ * @param {{ entries: () => Array<{ domain: string, key: string, driver: string, adapter: import('../adapters/mega-adapter.js').MegaAdapter }> }} manager
+ * @returns {number} 구독한 어댑터 수.
+ */
+export function attachToManager(manager: {
+    entries: () => Array<{
+        domain: string;
+        key: string;
+        driver: string;
+        adapter: import("../adapters/mega-adapter.js").MegaAdapter;
+    }>;
+}): number;
+/**
+ * 잡 워커(또는 큐)의 이벤트를 구독해 잡 메트릭(`mega_jobs_total`)으로 변환한다(어댑터 {@link subscribe} 대칭).
+ * `init` 전이면 **no-op**(0 비용 — 빈 해제 함수 반환). 같은 emitter 를 다시 구독하면 기존 해제 함수를 반환해
+ * **중복 부착을 방지**한다(어댑터 subscribe 와 동일 정책).
+ *
+ * `MegaJobWorker` 는 하부 `MegaJobQueue` 의 이벤트를 그대로 재방출(forward)하므로, **워커 1곳만 구독하면**
+ * 그 워커가 든 모든 bus 큐의 잡이 집계된다. `MegaJobQueue` 를 직접 구독해도 동일하게 동작한다(둘 다 같은
+ * 이벤트명을 방출). queue 라벨 = 이벤트 payload 의 `subject`.
+ *
+ * 리스너가 던질 일은 없지만(`recordJob` 은 카운터 add 뿐), 만에 하나 던져도 큐의 `#safeEmit`/워커 forward
+ * 가 격리하므로 잡 처리 흐름(ack/nak/DLQ)에는 영향이 없다(M-3 불변식 정합).
+ *
+ * @param {import('node:events').EventEmitter} emitter - `dispatch/done/retry/dlq` 를 방출하는 MegaJobWorker/MegaJobQueue.
+ * @returns {() => void} 구독 해제 함수.
+ */
+export function subscribeJobs(emitter: import("node:events").EventEmitter): () => void;
+/**
+ * 클라이언트 IP 가 allowList 에 허용되는지 (Boolean — `is*`). `/metrics` 엔드포인트 접근 제어용(ADR-072
+ * 면제 위에 추가 인증). allowList 항목은 **정확한 IP**(IPv4/IPv6) 또는 **IPv4 CIDR**(`10.0.0.0/8`).
+ * 빈 list/미지정이면 **모두 허용**(메인 포트 노출 — 사이드카/내부망 전제, 운영자 결정).
+ *
+ * IPv6 CIDR 는 미지원(정확 매치만) — 필요 시 후속 확장. 잘못된 CIDR 항목은 매치 실패로 간주(조용히
+ * 통과시키지 않음 = fail-closed 방향).
+ *
+ * @param {string} ip - 클라이언트 IP(Fastify `req.ip`). IPv4-mapped IPv6(`::ffff:1.2.3.4`)는 IPv4 로 정규화.
+ * @param {string[]} [allowList] - 허용 IP/CIDR 목록.
+ * @returns {boolean}
+ */
+export function isIpAllowed(ip: string, allowList?: string[]): boolean;
+/**
+ * 테스트 격리용 reset — 동기 강제 정리(provider flush 없이 상태만 비움). 정상 종료는 `shutdown`.
+ * @returns {void}
+ */
+export function _reset(): void;
+/** Prometheus 텍스트 노출 포맷 content-type (exposition format 0.0.4). */
+export const PROM_CONTENT_TYPE: "text/plain; version=0.0.4; charset=utf-8";
+export type MetricsState = {
+    provider: import("@opentelemetry/sdk-metrics").MeterProvider;
+    /**
+     * - MetricReader(=PrometheusExporter, preventServerStart).
+     */
+    reader: PrometheusExporter;
+    serializer: PrometheusSerializer;
+    /**
+     * - 생성된 인스트루먼트 묶음.
+     */
+    m: Instruments;
+};
+export type Instruments = {
+    httpRequests: import("@opentelemetry/api").Counter;
+    httpDuration: import("@opentelemetry/api").Histogram;
+    wsMessages: import("@opentelemetry/api").Counter;
+    wsDuration: import("@opentelemetry/api").Histogram;
+    adapterCalls: import("@opentelemetry/api").Counter;
+    adapterDuration: import("@opentelemetry/api").Histogram;
+    jobs: import("@opentelemetry/api").Counter;
+    sessions: import("@opentelemetry/api").Counter;
+    bruteforce: import("@opentelemetry/api").Counter;
+    uploadFiles: import("@opentelemetry/api").Counter;
+    uploadBytes: import("@opentelemetry/api").Histogram;
+    i18n: import("@opentelemetry/api").Counter;
+    templateRenders: import("@opentelemetry/api").Counter;
+    templateDuration: import("@opentelemetry/api").Histogram;
+};
+import { PrometheusExporter } from '@opentelemetry/exporter-prometheus';
+import { PrometheusSerializer } from '@opentelemetry/exporter-prometheus';

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

@@ -0,0 +1,245 @@
+/**
+ * `plugins` 배열을 순서대로 로딩한다 — resolve → shape 검증 → apiVersion 체크 → `install(mega, options)`.
+ *
+ * 02-architecture §14 부팅 시퀀스 4·5단계. 배열에 **명시된 것만** 로딩(auto-discovery X) → 배열에 없는
+ * 패키지는 `node_modules` 에 있어도 `install` 이 호출되지 않는다(ADR-079). 어느 단계든 실패하면
+ * `MegaConfigError` 로 fail-fast(부팅 중단, silent skip 금지).
+ *
+ * @param {MegaPluginsConfig | null | undefined} plugins -
+ *   `Array<string | { name, options }>`. 테스트·프로그램 편의로 **인라인 플러그인 객체**(`install` 함수
+ *   보유)도 원소로 허용한다.
+ * @param {MegaPluginHost} host - 코어가 만든 hook 컨텍스트.
+ * @param {{ projectRoot?: string, importer?: (spec: string) => Promise<MegaPlugin>, logger?: { debug?: Function } }} [opts] -
+ *   `projectRoot` 는 로컬 경로(`./...`) 해석 기준. `importer` 주입 시 모듈 해석을 가로채(테스트). `logger`
+ *   는 길목 debug 로그.
+ * @returns {Promise<LoadedPluginMeta[]>} 로딩된 플러그인 메타 목록(등록 순서).
+ * @throws {MegaConfigError} 잘못된 config/entry/shape/apiVersion/로드 실패/중복 플러그인(plugin.duplicate_plugin).
+ * @throws {TypeError} host 가 MegaPluginHost 인스턴스가 아님.
+ */
+export function loadPlugins(plugins: MegaPluginsConfig | null | undefined, host: MegaPluginHost, { projectRoot, importer, logger }?: {
+    projectRoot?: string;
+    importer?: (spec: string) => Promise<MegaPlugin>;
+    logger?: {
+        debug?: Function;
+    };
+}): Promise<LoadedPluginMeta[]>;
+/**
+ * 코어 플러그인 API 계약 메이저 버전 (ADR-122). npm 패키지 버전(`package.json`, 현재 pre-1.0 `0.x`)과
+ * **분리**한다 — 패키지 0.x 는 자주 바뀌어 거기 묶으면 0.x bump 마다 모든 플러그인이 깨진다. 플러그인은
+ * 코어 *내부 구조*가 아니라 *공개 hook 계약*에 의존하므로, 계약이 바뀔 때만 올리는 독립 버전이 맞다.
+ * 03-api-spec/02-architecture 의 예시(`apiVersion: '1'`)와도 정합.
+ * @type {string}
+ */
+export const CORE_API_VERSION: string;
+/**
+ * @typedef {Object} MegaPlugin
+ * @property {string} name        - npm 패키지명 또는 식별자.
+ * @property {string} version     - semver (예: '1.0.0').
+ * @property {string} apiVersion  - 코어 API 계약 메이저 버전. mismatch 시 부팅 throw.
+ * @property {(mega: MegaPluginHost, options?: object) => void | Promise<void>} install
+ */
+/**
+ * @typedef {Object} MegaCliCommandDef
+ * @property {string} description
+ * @property {(args: object) => unknown} handler - 03-api-spec 은 `Promise<void>|void` 로 적었으나,
+ *   핸들러가 결과(예: exit code·출력)를 반환할 수 있게 `unknown` 으로 넓힘(CLI 가 소비).
+ */
+/**
+ * 플러그인 scaffold generator manifest(03-api-spec §11) — `mega g <name>` 이 소비한다(ADR-187/199).
+ * `dir` 는 프로젝트 루트 상대 출력 기준, `files[].path`/`files[].template` 의 `{{token}}` 은
+ * cli/generators 의 `SCAFFOLD_TOKENS` 계약(Name/name/camelName/snake/app)으로 치환된다.
+ * @typedef {Object} MegaScaffoldDef
+ * @property {string} dir
+ * @property {Array<{ path: string, template: string }>} files
+ * @property {string} [description] - `mega help` 가 병기하는 한 줄 설명(선택).
+ */
+/** 빌트인 generator 이름 — 플러그인 scaffold 가 점유 금지(빌트인이 우선이라 silent shadow 가 됨).
+ * cli/generators 의 `GENERATOR_KINDS` 와 동일해야 한다(레이어 역전 회피를 위해 미러 — 동기화는
+ * mega-plugin 단위 테스트가 GENERATOR_KINDS 와 집합 비교로 강제한다). */
+export const RESERVED_GENERATOR_NAMES: Set<string>;
+/**
+ * @typedef {Object} LoadedPluginMeta
+ * @property {string} name
+ * @property {string} version
+ * @property {string} apiVersion
+ */
+/**
+ * `mega.config.js` 의 `plugins` 배열 (04-data-models §1.1 MegaPluginsConfig).
+ * @typedef {Array<string | { name: string, options?: object }>} MegaPluginsConfig
+ */
+/**
+ * `MegaPluginContext` — `install(mega)` 가 받는 `mega` 인자(03-api-spec §11).
+ *
+ * 코어 hook 의 등록 표면을 dot-notation(`mega.adapters.register(...)`)으로 노출하고, 등록 결과를
+ * 내부 레지스트리에 수집한다. 수집물은 getter/list 메서드로 queryable 하다(후속 Step 이 소비).
+ */
+export class MegaPluginHost {
+    /**
+     * @param {{ logger?: { debug?: Function } }} [opts] - 길목 debug 로그용(선택). 순수 등록 유틸이라
+     *   미주입이 기본 — 미주입 시 no-op.
+     */
+    constructor({ logger }?: {
+        logger?: {
+            debug?: Function;
+        };
+    });
+    /** 3rd party 어댑터 등록 (ADR-044) — 실 드라이버 레지스트리에 즉시 위임. */
+    adapters: {
+        /** @param {string} driver @param {Function} AdapterClass */
+        register: (driver: string, AdapterClass: Function) => void;
+    };
+    /** CLI 명령 등록 — `mega <name>`(소비는 CLI). */
+    cli: {
+        /** @param {string} name @param {MegaCliCommandDef} opts */
+        command: (name: string, opts: MegaCliCommandDef) => void;
+    };
+    /** Fastify 플러그인을 모든 앱에 등록(소비는 부팅 orchestrator). */
+    app: {
+        /** @param {Function} fastifyPlugin @param {object} [opts] */
+        use: (fastifyPlugin: Function, opts?: object) => void;
+    };
+    /** 글로벌 미들웨어 등록(소비는 라우트 파이프라인). */
+    middlewares: {
+        /** @param {Function} mw */
+        global: (mw: Function) => void;
+    };
+    /** 스캐폴드 generator 등록 — `mega g <name>`(소비는 CLI). */
+    scaffold: {
+        /** @param {string} name @param {MegaScaffoldDef} def */
+        register: (name: string, def: MegaScaffoldDef) => void;
+    };
+    /** 코어 lib 노출 — `ctx.lib.<name>`(소비는 ctx 빌더). */
+    lib: {
+        /** @param {string} name @param {Function} Class */
+        register: (name: string, Class: Function) => void;
+    };
+    /** 잡 등록 — `mega worker` 가 `config.jobs` 정적 등록분과 함께 흡수(ADR-123). */
+    jobs: {
+        /** @param {Function} JobClass - MegaJob 서브클래스. */
+        register: (JobClass: Function) => void;
+    };
+    /** 스케줄 등록 — `mega scheduler` 가 `config.schedules` 정적 등록분과 함께 흡수(ADR-123). */
+    schedules: {
+        /** @param {Function} TaskClass - MegaSchedule 서브클래스. */
+        register: (TaskClass: Function) => void;
+    };
+    /** 워커 등록 — `buildWorkers` 가 `config.workers` 정적 등록분과 함께 흡수(ADR-134). */
+    workers: {
+        /** @param {Function} WorkerClass - MegaWorker 서브클래스. */
+        register: (WorkerClass: Function) => void;
+    };
+    /**
+     * 라이프사이클 이벤트 구독. 미지정 이벤트는 `RangeError`(오타 차단 — 형제 MegaScheduler `on` 정책).
+     * hook 은 부팅 orchestrator 가 넘기는 boot context 를 선택적으로 받는다(L-2/ADR-123, `(ctx?) => ...`).
+     * @param {'beforeBoot' | 'afterBoot' | 'beforeShutdown'} event
+     * @param {(ctx?: object) => Promise<void> | void} fn
+     * @returns {this}
+     */
+    on(event: "beforeBoot" | "afterBoot" | "beforeShutdown", fn: (ctx?: object) => Promise<void> | void): this;
+    /**
+     * 한 lifecycle 단계의 구독 hook 을 **등록 순서대로** 실행한다(부팅 orchestrator 가 호출).
+     * beforeBoot/afterBoot 는 fail-fast(에러 전파)로 부팅을 멈춘다. beforeShutdown 은 graceful
+     * shutdown 경로에서 보통 `MegaShutdown.register`(per-hook catch)로 브리지된다(ADR-122).
+     *
+     * **L-2(ADR-123)**: 부팅 orchestrator 가 boot context(`{ config, log, db/cache/bus/lock }`)를
+     * 인자로 넘기면 각 hook 이 `fn(ctx)` 로 받는다. ctx 미주입 시 `undefined` 전달(03-api-spec 의
+     * `() => void` 시그니처와 하위 호환 — 인자 안 받는 hook 은 그대로 동작).
+     * @param {'beforeBoot' | 'afterBoot' | 'beforeShutdown'} event
+     * @param {object} [ctx] - boot context(L-2). orchestrator 가 주입, 미주입 시 undefined.
+     * @returns {Promise<void>}
+     */
+    runLifecycle(event: "beforeBoot" | "afterBoot" | "beforeShutdown", ctx?: object): Promise<void>;
+    /**
+     * loadPlugins 가 install 성공 후 메타를 기록한다(framework-internal).
+     * @param {LoadedPluginMeta} meta
+     * @returns {void}
+     */
+    _recordLoaded(meta: LoadedPluginMeta): void;
+    /** 등록 순서대로 install 된 플러그인 메타 목록. @returns {LoadedPluginMeta[]} */
+    get loadedPlugins(): LoadedPluginMeta[];
+    /** 등록된 CLI 명령 이름 목록. @returns {string[]} */
+    listCommands(): string[];
+    /** CLI 명령 정의 조회(없으면 undefined). @param {string} name @returns {MegaCliCommandDef | undefined} */
+    getCommand(name: string): MegaCliCommandDef | undefined;
+    /** CLI 명령 존재 여부. @param {string} name @returns {boolean} */
+    hasCommand(name: string): boolean;
+    /** 등록된 스캐폴드 generator 이름 목록. @returns {string[]} */
+    listGenerators(): string[];
+    /** 스캐폴드 generator 정의 조회. @param {string} name @returns {MegaScaffoldDef | undefined} */
+    getGenerator(name: string): MegaScaffoldDef | undefined;
+    /** 등록된 lib 이름 목록. @returns {string[]} */
+    listLibs(): string[];
+    /** lib 클래스 조회. @param {string} name @returns {Function | undefined} */
+    getLib(name: string): Function | undefined;
+    /** 플러그인이 등록한 잡 클래스 목록(복사본 — `mega worker` 가 소비). @returns {Function[]} */
+    listJobs(): Function[];
+    /** 플러그인이 등록한 스케줄 클래스 목록(복사본 — `mega scheduler` 가 소비). @returns {Function[]} */
+    listSchedules(): Function[];
+    /** 플러그인이 등록한 워커 클래스 목록(복사본 — `buildWorkers` 가 소비). @returns {Function[]} */
+    listWorkers(): Function[];
+    /** 등록된 Fastify 플러그인 목록(복사본). @returns {Array<{ plugin: Function, opts: object | undefined }>} */
+    get fastifyPlugins(): Array<{
+        plugin: Function;
+        opts: object | undefined;
+    }>;
+    /** 등록된 글로벌 미들웨어 목록(복사본). @returns {Function[]} */
+    get globalMiddlewares(): Function[];
+    /**
+     * 한 lifecycle 단계의 구독 hook 목록(복사본).
+     * @param {'beforeBoot' | 'afterBoot' | 'beforeShutdown'} event
+     * @returns {Function[]}
+     */
+    lifecycleHooks(event: "beforeBoot" | "afterBoot" | "beforeShutdown"): Function[];
+    #private;
+}
+export type MegaPlugin = {
+    /**
+     * - npm 패키지명 또는 식별자.
+     */
+    name: string;
+    /**
+     * - semver (예: '1.0.0').
+     */
+    version: string;
+    /**
+     * - 코어 API 계약 메이저 버전. mismatch 시 부팅 throw.
+     */
+    apiVersion: string;
+    install: (mega: MegaPluginHost, options?: object) => void | Promise<void>;
+};
+export type MegaCliCommandDef = {
+    description: string;
+    /**
+     * - 03-api-spec 은 `Promise<void>|void` 로 적었으나,
+     * 핸들러가 결과(예: exit code·출력)를 반환할 수 있게 `unknown` 으로 넓힘(CLI 가 소비).
+     */
+    handler: (args: object) => unknown;
+};
+/**
+ * 플러그인 scaffold generator manifest(03-api-spec §11) — `mega g <name>` 이 소비한다(ADR-187/199).
+ * `dir` 는 프로젝트 루트 상대 출력 기준, `files[].path`/`files[].template` 의 `{{token}}` 은
+ * cli/generators 의 `SCAFFOLD_TOKENS` 계약(Name/name/camelName/snake/app)으로 치환된다.
+ */
+export type MegaScaffoldDef = {
+    dir: string;
+    files: Array<{
+        path: string;
+        template: string;
+    }>;
+    /**
+     * - `mega help` 가 병기하는 한 줄 설명(선택).
+     */
+    description?: string;
+};
+export type LoadedPluginMeta = {
+    name: string;
+    version: string;
+    apiVersion: string;
+};
+/**
+ * `mega.config.js` 의 `plugins` 배열 (04-data-models §1.1 MegaPluginsConfig).
+ */
+export type MegaPluginsConfig = Array<string | {
+    name: string;
+    options?: object;
+}>;

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

@@ -0,0 +1,85 @@
+/**
+ * @typedef {Object} MegaRetryOptions
+ * @property {number} [retries=10] - 최대 **추가** 재시도 횟수(첫 시도 제외). Infinity 허용.
+ * @property {number} [minTimeout=1000] - 첫 백오프 지연(ms).
+ * @property {number} [maxTimeout=30000] - 백오프 지연 상한(ms).
+ * @property {number} [factor=2] - 지수 증가율.
+ * @property {boolean} [jitter=true] - 지연에 random[1,2) 곱(thundering herd 완화). false 면 결정적.
+ * @property {(ctx: { error: Error, attemptNumber: number, retriesLeft: number, retryDelay: number }) => void|Promise<void>} [onFailedAttempt]
+ *   - 매 시도 실패 직후 호출(다음 지연 전). 로그/관측용. throw 하면 재시도 중단.
+ * @property {(ctx: { error: Error, attemptNumber: number, retriesLeft: number }) => boolean|Promise<boolean>} [shouldRetry]
+ *   - false 반환 시 재시도 중단(마지막 에러 throw). 특정 에러만 재시도할 때.
+ * @property {AbortSignal} [signal] - abort 시 대기/재시도 즉시 취소.
+ * @property {boolean} [unref=true] - 백오프 타이머 unref(프로세스 종료를 막지 않음). 기본 true.
+ */
+/**
+ * `fn` 을 지수 백오프로 재시도한다. 성공 시 그 반환값을, 모두 실패하면 마지막 에러를 throw.
+ *
+ * @template T
+ * @param {(attemptNumber: number) => Promise<T>|T} fn - 실행할 작업. attemptNumber(1-based) 를 받는다.
+ * @param {MegaRetryOptions} [options]
+ * @returns {Promise<T>}
+ * @throws {Error} 모든 시도 실패 시 마지막 에러(또는 RetryAbortError 의 원본 에러).
+ * @example
+ *   await withRetry(() => connectToHub(), { retries: 5, minTimeout: 500, maxTimeout: 10_000 })
+ */
+export function withRetry<T>(fn: (attemptNumber: number) => Promise<T> | T, options?: MegaRetryOptions): Promise<T>;
+/**
+ * 재시도를 즉시 중단시키는 에러 래퍼 (p-retry `AbortError`). `throw new RetryAbortError(원본에러)`
+ * 하면 더 이상 재시도하지 않고 원본 에러가 호출부로 전파된다.
+ * @type {typeof AbortError}
+ */
+export const RetryAbortError: typeof AbortError;
+/** 네임스페이스 형태 접근(다른 Mega* 유틸과 일관). `MegaRetry.withRetry(...)`. */
+export const MegaRetry: Readonly<{
+    withRetry: typeof withRetry;
+    RetryAbortError: typeof AbortError;
+}>;
+export type MegaRetryOptions = {
+    /**
+     * - 최대 **추가** 재시도 횟수(첫 시도 제외). Infinity 허용.
+     */
+    retries?: number;
+    /**
+     * - 첫 백오프 지연(ms).
+     */
+    minTimeout?: number;
+    /**
+     * - 백오프 지연 상한(ms).
+     */
+    maxTimeout?: number;
+    /**
+     * - 지수 증가율.
+     */
+    factor?: number;
+    /**
+     * - 지연에 random[1,2) 곱(thundering herd 완화). false 면 결정적.
+     */
+    jitter?: boolean;
+    /**
+     * - 매 시도 실패 직후 호출(다음 지연 전). 로그/관측용. throw 하면 재시도 중단.
+     */
+    onFailedAttempt?: (ctx: {
+        error: Error;
+        attemptNumber: number;
+        retriesLeft: number;
+        retryDelay: number;
+    }) => void | Promise<void>;
+    /**
+     * - false 반환 시 재시도 중단(마지막 에러 throw). 특정 에러만 재시도할 때.
+     */
+    shouldRetry?: (ctx: {
+        error: Error;
+        attemptNumber: number;
+        retriesLeft: number;
+    }) => boolean | Promise<boolean>;
+    /**
+     * - abort 시 대기/재시도 즉시 취소.
+     */
+    signal?: AbortSignal;
+    /**
+     * - 백오프 타이머 unref(프로세스 종료를 막지 않음). 기본 true.
+     */
+    unref?: boolean;
+};
+import { AbortError } from 'p-retry';