mega-framework 0.1.6 → 0.1.8

package/types/core/boot.d.ts

@@ -0,0 +1,233 @@
+/**
+ * boot/CLI 컨텍스트 — `db/cache/bus/lock` 을 글로벌 키로 직접 조회하고, `workers` 는 `static name` 으로
+ * lookup 한다(앱 별명 변환 없음 — 둘 다 글로벌 자원). worker/scheduler CLI 도 같은 형태를 재사용한다
+ * (잡/스케줄의 `static bus`/`static lock` = 글로벌 키; 잡이 CPU 작업을 `ctx.workers` 로 오프로드 가능).
+ * @param {Object} global - global config.
+ * @param {{ debug?: Function, info?: Function, warn?: Function }} [logger]
+ * @returns {BootContext}
+ */
+export function buildBootContext(global: Object, logger?: {
+    debug?: Function;
+    info?: Function;
+    warn?: Function;
+}): BootContext;
+/**
+ * 공유 어댑터 전수의 `healthCheck()` 를 `MegaHealth` 에 `<domain>:<globalKey>` 이름으로 등록한다.
+ * `/health/ready` 가 어댑터 생사를 실제로 반영하게 하는 배선 — `prepareRuntime` 이 connect 직후
+ * 호출한다(`health.autoChecks:false` 옵트아웃). 등록은 이름 기준 덮어쓰기라 재부팅(테스트)에도 멱등.
+ *
+ * @param {Array<{ domain: string, key: string, adapter: { healthCheck: () => Promise<{ ok: boolean }> } }>} [entries] -
+ *   대상 어댑터 엔트리(기본: 어댑터 매니저의 전체 등록분). 테스트 주입용.
+ * @returns {string[]} 등록한 체크 이름 목록.
+ */
+export function registerAdapterHealthChecks(entries?: Array<{
+    domain: string;
+    key: string;
+    adapter: {
+        healthCheck: () => Promise<{
+            ok: boolean;
+        }>;
+    };
+}>): string[];
+/**
+ * 부트 step 정의 — 부팅 시퀀스의 한 단계.
+ * @typedef {Object} BootStep
+ * @property {string} name - step 이름(로그·prerequisite 에러 식별자).
+ * @property {string[]} [needs] - 선행 step 이 state 에 만들어 둬야 하는 키(prerequisite). 누락 시
+ *   `boot.step_prerequisite` throw — step 순서 변경·누락 같은 배선 실수를 즉시 드러낸다.
+ * @property {'abort'|'warn'} [onFail] - 실패 정책. `'abort'`(기본) = fail-fast throw(M-1 정리 경로),
+ *   `'warn'` = best-effort(warn 로그 후 다음 step 계속 — 부팅을 막으면 안 되는 부가 단계용).
+ * @property {(state: Record<string, any>) => Promise<void>|void} run - 단계 본체. 산출물은 state 에 쓴다.
+ */
+/**
+ * step 배열 실행기 — 각 step 의 prerequisite 검증 → 실행 → 길목 debug 로그(start/done/tookMs).
+ * 실패는 step 의 `onFail` 정책을 따른다(기본 abort — 현재 부트 시퀀스 전 단계가 fail-fast).
+ *
+ * @param {BootStep[]} steps - 실행할 step 정의(순서 = 시퀀스 정본).
+ * @param {Record<string, any>} state - step 간 공유 상태(산출물 버스).
+ * @param {{ debug?: Function, warn?: Function }} [logger]
+ * @returns {Promise<void>}
+ * @throws {MegaConfigError} prerequisite 누락(`boot.step_prerequisite`) — 배선 오류는 즉시 abort.
+ */
+export function runBootSteps(steps: BootStep[], state: Record<string, any>, logger?: {
+    debug?: Function;
+    warn?: Function;
+}): Promise<void>;
+/**
+ * 런타임 공통 준비 — {@link PREPARE_STEPS}(config → plugins → adapters → health-auto-checks →
+ * metrics → tracing → workers → ws-hub → boot-context)를 {@link runBootSteps} 로 실행한다.
+ * `bootApp`(서버)·`mega worker`/`mega scheduler`(CLI 호스트)가 **같은 순서**를 공유한다.
+ *
+ * @param {string} projectRoot
+ * @param {{ ping?: boolean, logger?: { debug?: Function, info?: Function, warn?: Function } }} [opts]
+ * @returns {Promise<{ global: Object, apps: Array<{ name: string, config: Object }>, host: MegaPluginHost, ctx: BootContext, wsHub: (MegaWsHub | null) }>}
+ */
+export function prepareRuntime(projectRoot: string, { ping, logger }?: {
+    ping?: boolean;
+    logger?: {
+        debug?: Function;
+        info?: Function;
+        warn?: Function;
+    };
+}): Promise<{
+    global: Object;
+    apps: Array<{
+        name: string;
+        config: Object;
+    }>;
+    host: MegaPluginHost;
+    ctx: BootContext;
+    wsHub: (MegaWsHub | null);
+}>;
+/**
+ * `global.server` 의 운영 옵션을 각 앱 Fastify 인스턴스 옵션으로 매핑한다(ADR-181, 04-data-models
+ * §MegaServerConfig). 미지정 키는 생략해 Fastify 기본값을 따른다. boot 가 모든 MegaApp 에 동일 주입한다
+ * (port/host 는 MegaServer.listen 이, 아래 런타임 옵션은 Fastify 인스턴스가 소비).
+ *   - trustProxy / trustedProxies → Fastify `trustProxy`(프록시/LB 뒤 req.ip·X-Forwarded-* 신뢰).
+ *     trustedProxies(목록)가 있으면 그것을, 없으면 trustProxy(boolean/number/string)를 그대로 넘긴다.
+ *   - timeouts.requestMs → Fastify `requestTimeout`(요청 수신 제한, slow-loris 보호).
+ *   - keepAliveMs       → Fastify `keepAliveTimeout`(keep-alive 소켓 idle 제한, ALB 정합).
+ *
+ * 프로덕션(`NODE_ENV==='production'`)에서 trustProxy/trustedProxies 미설정이면 **부팅 warn 1회**(ADR-186).
+ * 프록시/LB 뒤에서 미설정 시 `req.protocol`/`req.ip` 가 프록시 기준으로 잡혀 secure 쿠키 누락·rate-limit
+ * 키 왜곡·CSRF Origin 오판으로 번진다 — 직접 listen 배포면 무시해도 되는 안내성 경고다.
+ *
+ * @param {any} server - `global.server` config(없으면 빈 객체).
+ * @param {{ logger?: { warn?: Function }, env?: Record<string, string|undefined> }} [opts] - warn 출력용
+ *   logger 와 환경(테스트 주입용, 기본 `process.env`).
+ * @returns {{ trustProxy?: any, requestTimeout?: number, keepAliveTimeout?: number }}
+ */
+export function serverFastifyOptions(server: any, { logger, env }?: {
+    logger?: {
+        warn?: Function;
+    };
+    env?: Record<string, string | undefined>;
+}): {
+    trustProxy?: any;
+    requestTimeout?: number;
+    keepAliveTimeout?: number;
+};
+/**
+ * 프로젝트를 부팅한다 — {@link BOOT_STEPS}(runtime → before-boot-hook → logger → server → apps →
+ * cluster-transport → listen → after-boot-hook → shutdown-bridge)를 {@link runBootSteps} 로 실행한다.
+ *
+ * 어느 step 이든 실패하면 그대로 throw(fail-fast, 전 step onFail='abort'). 어댑터 connect 실패는
+ * 매니저가 LIFO cleanup 하고, 그 외 단계 실패(예: server.listen EADDRINUSE, beforeBoot hook throw)는
+ * 어댑터가 이미 connect 돼 `'adapters:disconnect'` MegaShutdown hook 이 등록된 상태라, 호출자가
+ * `MegaShutdown.now` 로 그 hook 을 실행해 정리해야 한다 — `bin/mega.js` 의 catch 가 이 정리 경로를
+ * 배선한다(M-1). 그러지 않으면 연결된 어댑터가 이벤트루프를 살려 프로세스가 hang 한다.
+ *
+ * @param {string} projectRoot - 프로젝트 루트 절대 경로(mega.config.js 가 있는 곳).
+ * @param {Object} [opts]
+ * @param {boolean} [opts.listen=true] - false 면 mount 까지만(테스트·검증용).
+ * @param {number} [opts.port] - listen 포트(미지정 시 server/global 기본).
+ * @param {string} [opts.host] - listen 호스트.
+ * @param {boolean} [opts.ping=false] - connectAll 시 healthCheck 까지 검증.
+ * @param {{ debug?: Function, info?: Function, warn?: Function }} [opts.logger] - 길목 debug 로그(선택).
+ * @returns {Promise<BootResult>}
+ */
+export function bootApp(projectRoot: string, { listen, port, host: listenHost, ping, logger }?: {
+    listen?: boolean;
+    port?: number;
+    host?: string;
+    ping?: boolean;
+    logger?: {
+        debug?: Function;
+        info?: Function;
+        warn?: Function;
+    };
+}): Promise<BootResult>;
+/** prepareRuntime step 이름 시퀀스(정본) — introspection·테스트용. */
+export const PREPARE_STEP_NAMES: readonly string[];
+/** bootApp step 이름 시퀀스(정본) — introspection·테스트용. */
+export const BOOT_STEP_NAMES: readonly string[];
+/**
+ * 부팅 결과 핸들.
+ */
+export type BootResult = {
+    /**
+     * - mount 된 MegaServer(listen=false 면 미-listen 상태).
+     */
+    server: MegaServer;
+    /**
+     * - 플러그인 호스트(install 완료, queryable).
+     */
+    host: MegaPluginHost;
+    /**
+     * - mega.config.js default export(global).
+     */
+    config: Object;
+    /**
+     * - 로드된 앱 config 목록.
+     */
+    apps: Array<{
+        name: string;
+        config: Object;
+    }>;
+    /**
+     * - 생성된 MegaApp 인스턴스(등록 순서).
+     */
+    megaApps: MegaApp[];
+    /**
+     * - lifecycle hook 에 넘긴 boot context.
+     */
+    ctx: BootContext;
+    /**
+     * - embedded wsHub(ADR-137, `wsHub.enabled` OFF 면 null).
+     */
+    wsHub: import("../lib/ws-hub.js").MegaWsHub | null;
+    /**
+     * - 공유 pino 로거(ADR-141, logger 비활성이면 null). CLI 시작 메시지 등에 재사용.
+     */
+    appLogger: import("pino").Logger | null;
+};
+/**
+ * lifecycle hook(beforeBoot/afterBoot/beforeShutdown)이 받는 boot context (L-2/ADR-123).
+ * `db/cache/bus/lock` 은 **글로벌 키 직접 lookup**(앱 별명 변환 없음 — boot 레벨은 별명 스코프 밖).
+ */
+export type BootContext = {
+    /**
+     * - global config.
+     */
+    config: Object;
+    log?: {
+        debug?: Function;
+        info?: Function;
+        warn?: Function;
+    };
+    db: (globalKey: string) => import("../adapters/mega-adapter.js").MegaAdapter;
+    cache: (globalKey: string) => import("../adapters/mega-adapter.js").MegaAdapter;
+    bus: (globalKey: string) => import("../adapters/mega-adapter.js").MegaAdapter;
+    lock: (globalKey: string) => import("../adapters/mega-adapter.js").MegaAdapter;
+    /**
+     * - `ctx.workers.<name>.run(task)` (ADR-124).
+     */
+    workers: Record<string, import("../lib/mega-worker.js").MegaWorker>;
+};
+/**
+ * 부트 step 정의 — 부팅 시퀀스의 한 단계.
+ */
+export type BootStep = {
+    /**
+     * - step 이름(로그·prerequisite 에러 식별자).
+     */
+    name: string;
+    /**
+     * - 선행 step 이 state 에 만들어 둬야 하는 키(prerequisite). 누락 시
+     * `boot.step_prerequisite` throw — step 순서 변경·누락 같은 배선 실수를 즉시 드러낸다.
+     */
+    needs?: string[];
+    /**
+     * - 실패 정책. `'abort'`(기본) = fail-fast throw(M-1 정리 경로),
+     * `'warn'` = best-effort(warn 로그 후 다음 step 계속 — 부팅을 막으면 안 되는 부가 단계용).
+     */
+    onFail?: "abort" | "warn";
+    /**
+     * - 단계 본체. 산출물은 state 에 쓴다.
+     */
+    run: (state: Record<string, any>) => Promise<void> | void;
+};
+import { MegaPluginHost } from '../lib/mega-plugin.js';
+import { MegaWsHub } from '../lib/ws-hub.js';
+import { MegaServer } from './mega-server.js';
+import { MegaApp } from './mega-app.js';

package/types/core/cluster-metrics.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 여러 워커의 Prometheus exposition 텍스트를 하나로 합산한다(순수 — 테스트 가능).
+ *
+ * - **counter / histogram(_bucket/_sum/_count)**: 동일 `name{labels}` 끼리 값 **합산**(클러스터 누적).
+ * - **gauge**: 합산(메모리·CPU 는 클러스터 합이 유의미). 단 프로세스별 gauge(uptime 등)는 합이 N배가 되는
+ *   문서화된 한계 — prom-client 기본도 gauge=sum. `_info`/`target_info` 메타는 합산 대신 **첫 값 유지**(=1).
+ * - `# HELP`/`# TYPE` 는 패밀리별 1줄로 dedupe 하고, 패밀리(TYPE 이름) 단위로 묶어 재출력한다.
+ *
+ * @param {string[]} texts - 각 워커 `collect()` 결과(빈 문자열 허용).
+ * @returns {string} 합산된 exposition 텍스트(끝 개행 포함). 입력이 모두 비면 빈 문자열.
+ */
+export function mergeExposition(texts: string[]): string;
+/**
+ * 워커 프로세스에 collect 응답기를 설치한다 — 마스터의 `collect` 요청에 자기 `MegaMetrics.collect()` 로 회신.
+ * 클러스터 워커가 아니면 no-op. `process.on('message')` 다중 리스너라 MegaCluster shutdown 핸들러와 공존한다.
+ *
+ * IPC 경로는 fork 워커 안에서만 실행돼 부모 v8 커버리지로 측정 불가다. cluster/process 를 주입 seam 으로
+ * 분리해 fake 로 in-process 단위 검증한다(per ADR-165 — `MegaCluster` 와 동일 패턴). 프로덕션 호출부는
+ * 인자를 안 넘겨 실 전역을 쓴다.
+ * @param {{ _cluster?: import('node:cluster').Cluster, _proc?: NodeJS.Process }} [opts]
+ * @returns {void}
+ */
+export function installWorkerResponder({ _cluster, _proc }?: {
+    _cluster?: import("node:cluster").Cluster;
+    _proc?: NodeJS.Process;
+}): void;
+/**
+ * 마스터 프로세스에 집계기를 설치한다 — 워커의 `request` 를 받아 전 워커에 fan-out, 회신을 모아 합산해 회신.
+ * 마스터가 아니면 no-op. `cluster.on('message')` 로 모든 워커 메시지를 한 핸들러로 받는다.
+ *
+ * IPC 경로는 마스터 안에서만 실행돼 부모 v8 커버리지로 측정 불가다 — cluster 를 주입 seam 으로 분리해
+ * fake 로 in-process 단위 검증한다(per ADR-165).
+ * @param {{ timeoutMs?: number, _cluster?: import('node:cluster').Cluster }} [opts] - 라운드 수집 timeout(전원 미응답 시 부분 합산). 기본 2000ms.
+ * @returns {void}
+ */
+export function installPrimaryAggregator({ timeoutMs, _cluster }?: {
+    timeoutMs?: number;
+    _cluster?: import("node:cluster").Cluster;
+}): void;
+/**
+ * 현재 프로세스 기준 메트릭을 수집한다 — 클러스터 워커면 마스터를 통해 **전 워커 합산**, 단일 프로세스면 로컬.
+ * `/metrics` 라우트와 `/demo/metrics` 가 쓴다. timeout/마스터 부재 시 로컬 `collect()` 로 폴백(스크레이프가 안
+ * 멈추도록).
+ * cluster/process 는 주입 seam(테스트용 — per ADR-165). 프로덕션 호출부는 인자를 안 넘겨 실 전역을 쓴다.
+ * @param {{ timeoutMs?: number, _cluster?: import('node:cluster').Cluster, _proc?: NodeJS.Process }} [opts] - 응답 대기 timeout(라운드 timeout 보다 넉넉히). 기본 2500ms.
+ * @returns {Promise<string>} Prometheus exposition 텍스트.
+ */
+export function collectCluster({ timeoutMs, _cluster, _proc }?: {
+    timeoutMs?: number;
+    _cluster?: import("node:cluster").Cluster;
+    _proc?: NodeJS.Process;
+}): Promise<string>;

package/types/core/config-loader.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 프로젝트 루트에서 mega.config.js + 활성 앱 config 들 로드 + 검증.
+ * @param {string} projectRoot - 프로젝트 루트 절대 경로
+ * @returns {Promise<{global: Object, apps: Array<{name: string, config: Object}>}>}
+ * @throws {MegaConfigError}
+ */
+export function loadAndValidateConfig(projectRoot: string): Promise<{
+    global: Object;
+    apps: Array<{
+        name: string;
+        config: Object;
+    }>;
+}>;

package/types/core/config-validator.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 메인 config 검증.
+ * @param {Record<string, any>} globalConfig - mega.config.js export 객체
+ * @throws {MegaConfigError}
+ */
+export function validateGlobalConfig(globalConfig: Record<string, any>): void;
+/**
+ * 앱 config 검증.
+ * @param {Record<string, any>} appConfig - apps/<name>/app.config.js export 객체
+ * @param {string} expectedFolderName - 폴더명 (apps/<name>)
+ * @param {Record<string, any>} globalConfig - 메인 (Shared-Reference 키 cross-check 용)
+ * @throws {MegaConfigError}
+ */
+export function validateAppConfig(appConfig: Record<string, any>, expectedFolderName: string, globalConfig: Record<string, any>): void;
+/**
+ * 모든 앱 cross-validate: 호스트 충돌 감지 (ADR-067).
+ * @param {Array<{ name: string, config: Record<string, any> }>} apps
+ * @throws {MegaConfigError}
+ */
+export function validateHostCollisions(apps: Array<{
+    name: string;
+    config: Record<string, any>;
+}>): void;
+/**
+ * 가까운 키 추천 (Levenshtein 거리 기반).
+ * @param {string} input
+ * @param {readonly string[]} known
+ * @returns {string | undefined}
+ */
+export function suggestKey(input: string, known: readonly string[]): string | undefined;

package/types/core/ctx-builder.d.ts

@@ -0,0 +1,103 @@
+/**
+ * @typedef {object} AdapterAliasMaps - 앱의 `app.config.js` 별명 선언 (alias → globalKey).
+ * @property {Record<string, string>} [databases]
+ * @property {Record<string, string>} [caches]
+ * @property {Record<string, string>} [buses]
+ * @property {Record<string, string>} [locks]
+ */
+/**
+ * @typedef {object} AdapterAccessors
+ * @property {(alias: string) => import('../adapters/mega-adapter.js').MegaAdapter} db
+ * @property {(alias: string) => import('../adapters/mega-adapter.js').MegaAdapter} cache
+ * @property {(alias: string) => import('../adapters/mega-adapter.js').MegaAdapter} bus
+ * @property {(alias: string) => import('../adapters/mega-adapter.js').MegaAdapter} lock
+ */
+/**
+ * 앱의 별명 맵으로 `db/cache/bus/lock` 접근자 4종을 만든다. 접근자는 요청과 무관하게 안정적이므로
+ * **앱당 한 번** 만들어 재사용한다(MegaApp 생성자). 각 접근자는 호출 시 별명→globalKey→공유
+ * 인스턴스로 해석하고, 미선언 별명이면 throw.
+ *
+ * @param {AdapterAliasMaps} [aliasMaps] - 앱 별명 선언. 없으면 모든 접근자가 미선언 throw.
+ * @param {string} [appName] - 에러 메시지용 앱 이름.
+ * @returns {AdapterAccessors}
+ */
+export function buildAdapterAccessors(aliasMaps?: AdapterAliasMaps, appName?: string): AdapterAccessors;
+/**
+ * HTTP 요청 단위 ctx 를 만든다 (canonical handler 시그니처 `(req, res, ctx)`, ADR-074/docs/03).
+ *
+ * canonical ctx 표면: `app / log / requestId / req / reply` + `db/cache/bus` 접근자 +
+ * `workers`(CPU 워커 풀, ADR-124) + `tracer`(사용자 직접 span — `ctx.tracer.span`,
+ * ADR-126). (i18n `t`, `session` 객체, `services` 자동 DI 등 나머지 canonical 필드도 같은 방식으로 추가된다.)
+ *
+ * `app` 이 null(standalone Router — 앱에 바인딩 안 된 테스트 경로)이면 `db/cache/bus` 접근자는
+ * 생략된다(해당 ctx 로는 어댑터 lookup 불가). `workers` 는 글로벌 자원이라 app 무관하게 항상 노출한다
+ * (미등록 이름 접근 시 worker.not_registered fail-fast — 워커 0개면 접근 자체가 없어 무해).
+ *
+ * @param {object} args
+ * @param {import('./mega-app.js').MegaApp | null} args.app
+ * @param {import('fastify').FastifyRequest} args.req
+ * @param {import('fastify').FastifyReply} args.reply
+ * @returns {Record<string, any>}
+ */
+export function buildHttpCtx({ app, req, reply }: {
+    app: import("./mega-app.js").MegaApp | null;
+    req: import("fastify").FastifyRequest;
+    reply: import("fastify").FastifyReply;
+}): Record<string, any>;
+/**
+ * 요청당 ctx 를 **한 번만** 만들고 `req` 에 캐싱해 재사용한다(ADR-134). 글로벌 미들웨어(preHandler)와
+ * 라우트 핸들러가 같은 요청에서 호출하면 **동일 ctx 객체**를 받으므로, 미들웨어가 ctx 에 심은 값
+ * (예: `ctx.user`)을 핸들러가 그대로 본다. 첫 호출이 build, 이후 호출은 캐시 반환.
+ *
+ * 캐시 키는 비열거 Symbol 이라 `{...ctx}`/`Object.keys(req)` 에 노출되지 않는다. `req` 는 Fastify 가
+ * 요청마다 새로 만드는 객체라 요청 스코프로 자연히 격리된다(요청 종료 시 GC).
+ *
+ * @param {object} args
+ * @param {import('./mega-app.js').MegaApp | null} args.app
+ * @param {import('fastify').FastifyRequest} args.req
+ * @param {import('fastify').FastifyReply} args.reply
+ * @returns {Record<string, any>}
+ */
+export function getHttpCtx({ app, req, reply }: {
+    app: import("./mega-app.js").MegaApp | null;
+    req: import("fastify").FastifyRequest;
+    reply: import("fastify").FastifyReply;
+}): Record<string, any>;
+/**
+ * **lazy** HTTP ctx — 실제 ctx 빌드를 첫 속성 접근 시점까지 미루는 요청당 프록시 (G1 H-1, ADR-214).
+ *
+ * hot path 단일 최대 프레임워크 비용이 "핸들러가 ctx 를 안 써도 매 요청 무조건 buildHttpCtx"
+ * (1,615 B + ≈0.7 µs/req, CPU 2.3% — audit-G1 실측)였다. 이 프록시는 생성 비용이 객체 1개 수준이고,
+ * 핸들러·미들웨어가 ctx 의 속성을 **처음 만질 때만** {@link getHttpCtx} 로 실 ctx 를 만든다(이후 캐시).
+ *
+ * 호환성: canonical 시그니처 `(req, reply, ctx)` 는 그대로 — 모든 핸들러가 여전히 3번째 인자를 받고,
+ * 참조하는 순간부터는 기존과 동일한 실 ctx 표면(ADR-134 요청당 공유 포함)이다. 프록시 자체도 요청당
+ * 1개로 캐시되어 미들웨어와 핸들러가 **동일 객체**(`===`)를 받는다. 모든 트랩이 실 ctx 로 위임되므로
+ * `in`/spread/`Object.keys`/getter·setter(`ctx.user=`) 동작이 보존된다.
+ *
+ * @param {object} args
+ * @param {import('./mega-app.js').MegaApp | null} args.app
+ * @param {import('fastify').FastifyRequest} args.req
+ * @param {import('fastify').FastifyReply} args.reply
+ * @returns {Record<string, any>}
+ */
+export function getLazyHttpCtx({ app, req, reply }: {
+    app: import("./mega-app.js").MegaApp | null;
+    req: import("fastify").FastifyRequest;
+    reply: import("fastify").FastifyReply;
+}): Record<string, any>;
+/**
+ * - 앱의 `app.config.js` 별명 선언 (alias → globalKey).
+ */
+export type AdapterAliasMaps = {
+    databases?: Record<string, string>;
+    caches?: Record<string, string>;
+    buses?: Record<string, string>;
+    locks?: Record<string, string>;
+};
+export type AdapterAccessors = {
+    db: (alias: string) => import("../adapters/mega-adapter.js").MegaAdapter;
+    cache: (alias: string) => import("../adapters/mega-adapter.js").MegaAdapter;
+    bus: (alias: string) => import("../adapters/mega-adapter.js").MegaAdapter;
+    lock: (alias: string) => import("../adapters/mega-adapter.js").MegaAdapter;
+};

package/types/core/envelope.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 자동 envelope (ADR-018). preSerialization 훅의 마지막 단계에서 호출되어
+ * raw data → `{ ok:true, data, meta }`.
+ *
+ * transform 미들웨어(ADR-091)가 먼저 raw data 를 변환했으면, 그 변환 결과 위에 envelope 만 감쌈
+ * (실행 순서: transform → wrap, ADR-076 / ADR-091).
+ *
+ * 이미 envelope 형태로 보낸 경우(`{ ok:false, error: ... }` 등 명시) 는 그대로 통과 —
+ * 글로벌 에러 핸들러가 만든 error envelope 의 이중 wrap 을 방지.
+ *
+ * @param {Record<string, any>} req - Fastify request
+ * @param {Record<string | symbol, any>} reply - Fastify reply
+ * @param {any} payload - 핸들러/transform 이 만든 raw data 또는 이미 만들어진 envelope
+ * @returns {Object | any} envelope 또는 (이미 envelope 면) 원본 payload
+ */
+export function wrapEnvelope(req: Record<string, any>, reply: Record<string | symbol, any>, payload: any): Object | any;
+/**
+ * 에러 envelope (ADR-014). 글로벌 에러 핸들러가 사용.
+ * @param {Record<string, any>} req
+ * @param {Record<string | symbol, any>} reply
+ * @param {{ code: string, message?: string, details?: any }} error
+ * @returns {{ ok: false, error: { code: string, message: string, details?: any }, meta: Object }}
+ */
+export function errorEnvelope(req: Record<string, any>, reply: Record<string | symbol, any>, error: {
+    code: string;
+    message?: string;
+    details?: any;
+}): {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+        details?: any;
+    };
+    meta: Object;
+};
+/**
+ * 라우트 `schema.response` 를 envelope 모양으로 합성한다.
+ *
+ * 배경: 자동 envelope(ADR-018)는 preSerialization 마지막에 raw data 를 `{ ok, data, meta }` 로
+ * 감싸는데, 사용자가 raw data 모양의 response schema 를 선언하면 Fastify 직렬화기가 **envelope 를
+ * 그 raw 스키마로 직렬화해 ok/data/meta 가 통째로 제거**된다(silent 데이터 소실). 그래서 등록
+ * 시점(onRoute)에 각 상태코드 스키마를 `{ ok, data: <사용자 스키마>, error, meta }` 로 재작성한다 —
+ * 사용자는 계속 raw data 모양만 선언하고(ADR-091), strict 직렬화(ADR-020: 선언 외 필드 제거)는
+ * data 안에서 그대로 동작하며, OpenAPI 명세(@fastify/swagger 가 schema 수집)도 실제 와이어 모양과
+ * 일치하게 된다.
+ *
+ * 합성 제외(원본 유지) 3종:
+ *   - `type: 'string'` 스키마 — 문자열 payload 는 Fastify 가 preSerialization(envelope wrap) 자체를
+ *     건너뛰므로(raw 전송, 예: /metrics) envelope 모양으로 바꾸면 오히려 직렬화가 깨진다.
+ *   - 이미 envelope 모양(`properties.ok` 보유) — 사용자가 envelope 전체를 직접 선언한 경우.
+ *   - 스키마가 object 가 아닌 항목 — 알 수 없는 형식은 건드리지 않는다(fail-safe).
+ *
+ * Fastify v5 의 media-type 형식(`{ content: { 'application/json': { schema } } }`)은 내부 schema
+ * 에 같은 규칙을 적용한다.
+ *
+ * @param {Record<string, any>} response - 라우트 `schema.response` (상태코드/패턴 → JSON Schema).
+ * @returns {Record<string, any>} envelope 모양으로 합성된 새 response 객체 (원본 불변).
+ */
+export function synthesizeEnvelopeResponseSchema(response: Record<string, any>): Record<string, any>;
+/**
+ * 응답 envelope 헬퍼 (ADR-014, ADR-018).
+ *
+ * 모든 HTTP 응답은 `{ ok, data|error, meta }` 형태로 통일된다.
+ * wrapEnvelope 는 preSerialization 의 마지막 단계에서 raw data 를 감싸고,
+ * errorEnvelope 는 글로벌 에러 핸들러에서 에러를 감싼다.
+ *
+ * @module core/envelope
+ */
+/** request 시작 시간 기록용 symbol (meta.took_ms 계산). reply 객체에 부착. */
+export const REPLY_START_SYMBOL: unique symbol;
+/**
+ * 프레임워크가 만든 envelope 임을 표시하는 비열거 마킹 symbol.
+ *
+ * 이중 wrap 방지 판별을 키 모양 추측(duck-typing)이 아니라 이 마킹으로 한다 — 핸들러가 우연히
+ * `{ ok, data }` 모양의 도메인 데이터(예: 외부 API 프록시 응답)를 반환해도 정상적으로 data 로
+ * 감싸진다. 비열거라 JSON 직렬화·spread 에는 나타나지 않는다.
+ */
+export const ENVELOPE_MARK: unique symbol;

package/types/core/error-mapper.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Fastify setErrorHandler 에 등록할 핸들러 빌더.
+ *
+ * 우선순위:
+ *   1) AJV validation 에러 → MegaValidationError 변환 (ADR-090)
+ *   2) MegaHttpError → 그대로 envelope (status/code/message/details 보존)
+ *   3) MegaError → 500 + code/message 보존 (도메인 에러지만 HTTP status 없음)
+ *   4) 그 외 일반 Error → MegaInternalError (스택·메시지는 로그만, envelope 엔 마스킹)
+ *
+ * @param {{ exposeInternalDetails?: boolean }} [opts]
+ *   - exposeInternalDetails: true 면 일반 Error 의 message 를 envelope 에 노출.
+ *     기본 false (보안 — 내부 구현 누출 방지).
+ * @returns {(error: Error, req: any, reply: any) => any}
+ */
+export function buildErrorHandler({ exposeInternalDetails }?: {
+    exposeInternalDetails?: boolean;
+}): (error: Error, req: any, reply: any) => any;

package/types/core/formbody.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 폼 바디 파서 자동 등록 결과 요약(디버그·테스트용).
+ * @typedef {Object} FormbodySummary
+ * @property {boolean} enabled - 등록 여부.
+ */
+/**
+ * views 설정이 서버사이드 렌더를 켰는지 (Boolean — `has*`). `views.dir` 가 비지 않은 문자열일 때만 true.
+ * registerTemplate 의 옵트인 판정과 같은 기준이라 폼 파싱이 뷰 등록과 정확히 짝을 이룬다.
+ * @param {unknown} views
+ * @returns {boolean}
+ */
+export function hasServerViews(views: unknown): boolean;
+/**
+ * Fastify 인스턴스에 `@fastify/formbody` 를 등록한다 — 서버사이드 뷰를 켠 앱에 한해 옵트인.
+ *
+ * `views` 가 없으면 **미등록**(JSON·text 만 파싱, 기존 동작 유지). 호출 시점은 라우트 등록 이전이어야
+ * 한다(content-type 파서는 글로벌이라 등록 후 도착하는 모든 요청에 적용) — MegaApp 생성자가 그 지점이다.
+ *
+ * @param {import('fastify').FastifyInstance} fastify - 대상 앱 Fastify 인스턴스.
+ * @param {Object} opts
+ * @param {unknown} opts.views - `MegaViewsConfig`(dir/layoutDir/...). 서버 뷰 옵트인 판정에 쓴다.
+ * @param {string} [opts.appName] - 앱 이름(로그용).
+ * @param {{ debug?: Function }} [opts.logger] - 흐름 길목 debug 로그(선택).
+ * @returns {FormbodySummary}
+ */
+export function registerFormbody(fastify: import("fastify").FastifyInstance, { views, appName, logger }?: {
+    views: unknown;
+    appName?: string;
+    logger?: {
+        debug?: Function;
+    };
+}): FormbodySummary;
+/**
+ * 폼 바디 파서 자동 등록 결과 요약(디버그·테스트용).
+ */
+export type FormbodySummary = {
+    /**
+     * - 등록 여부.
+     */
+    enabled: boolean;
+};