mega-framework 0.1.5 → 0.1.7

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,80 @@
+/**
+ * @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>;
+/**
+ * - 앱의 `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;
+};

package/types/core/hub-link.d.ts

@@ -0,0 +1,264 @@
+export class MegaHubLink {
+    /**
+     * 링크 라이프사이클 이벤트 (wire 타입과 충돌하지 않도록 `link.*` reserved). {@link MegaHubLink#on}
+     * 으로 구독한다. **핸들러 인자는 이벤트마다 다르다**(L-2):
+     *   - `RECONNECTED`     → `{ hubId: string }` — 재연결 성공(새 등록 완료). hubId 는 새 hub 의 식별자.
+     *   - `DISCONNECTED`    → `{ code: number, reason: string, isDrain: boolean }` — 등록 후 절단.
+     *     `isDrain` 은 close code 가 4503(DRAIN)인지(다른 hub 로 회전 신호, ADR-098).
+     *   - `RECONNECT_FAILED`→ `{ error: Error }` — 재연결 재시도 소진(더 이상 자동 재시도 없음).
+     * @type {Readonly<{ RECONNECTED: string, DISCONNECTED: string, RECONNECT_FAILED: string }>}
+     */
+    static EVENTS: Readonly<{
+        RECONNECTED: string;
+        DISCONNECTED: string;
+        RECONNECT_FAILED: string;
+    }>;
+    /**
+     * @param {Object} [opts]
+     * @param {string} [opts.url] - hub URL (예: 'ws://hub1.internal:19991/_hub'). 누락 시 throw.
+     * @param {string} [opts.token] - Bearer 토큰 (wsHub.acceptedTokens 중 하나). 누락 시 throw.
+     * @param {string} [opts.bridgeId] - 운영 식별자 (예: 'main-1'). 누락 시 throw.
+     * @param {string} [opts.instanceId] - REGISTER instanceId. 기본 bridgeId.
+     * @param {string[]} [opts.capabilities] - 선언 capability 목록. 기본 [].
+     * @param {import('../lib/mega-retry.js').MegaRetryOptions} [opts.retry] - 지정 시 재연결 활성(ADR-098).
+     *   `{ retries, minTimeout, maxTimeout, factor, jitter }`. 미지정 → 재연결 끔(기본 동작).
+     * @param {number} [opts.connectTimeoutMs=10000] - register_ok 미수신 시 attempt reject 까지(M4).
+     * @param {import('./ws-compression.js').WsCompressionConfig} [opts.compression] - Bridge↔Hub link
+     *   per-message deflate 압축(ADR-078). Global `wsHub.compression` 블록과 동일
+     *   스키마 — hub 서버와 양쪽이 협상해야 활성(RFC 7692). 디폴트 OFF. 잘못된 값은 즉시 throw.
+     * @param {{ warn?: Function, debug?: Function, info?: Function, error?: Function }} [opts.logger]
+     * @param {typeof import('ws').WebSocket} [opts.WebSocketCtor] - 테스트 주입용 ws 생성자.
+     * @param {number} [opts.maxBufferedBytes=16777216] - 송신 버퍼(bufferedAmount) 상한(바이트). 초과 시
+     *   백프레셔로 보고 소켓을 닫고(1013) 송신을 명시 실패시킨다 — hub 가 느릴 때 bridge 힙이 무한
+     *   적재되는 것을 막는다. 재연결(retry) 설정 시 자동 회복.
+     */
+    constructor({ url, token, bridgeId, instanceId, capabilities, retry, connectTimeoutMs, compression, logger, WebSocketCtor, maxBufferedBytes }?: {
+        url?: string;
+        token?: string;
+        bridgeId?: string;
+        instanceId?: string;
+        capabilities?: string[];
+        retry?: import("../lib/mega-retry.js").MegaRetryOptions;
+        connectTimeoutMs?: number;
+        compression?: import("./ws-compression.js").WsCompressionConfig;
+        logger?: {
+            warn?: Function;
+            debug?: Function;
+            info?: Function;
+            error?: Function;
+        };
+        WebSocketCtor?: typeof import("ws").WebSocket;
+        maxBufferedBytes?: number;
+    });
+    _url: string;
+    _token: string;
+    _bridgeId: string;
+    _instanceId: string;
+    _capabilities: string[];
+    _log: {
+        warn?: Function;
+        debug?: Function;
+        info?: Function;
+        error?: Function;
+    };
+    _WS: typeof WebSocket;
+    /** 재연결 옵션 (없으면 재연결 비활성). @type {import('../lib/mega-retry.js').MegaRetryOptions | null} */
+    _retry: import("../lib/mega-retry.js").MegaRetryOptions | null;
+    /** 한 attempt 의 register_ok 대기 한도(M4). reconnect 에서도 동일 적용. @type {number} */
+    _connectTimeoutMs: number;
+    /** 송신 버퍼(bufferedAmount) 상한 — 초과 시 백프레셔로 소켓을 닫는다(기본 16 MiB). @type {number} */
+    _maxBufferedBytes: number;
+    /** @type {false | Object} ws 클라이언트 perMessageDeflate 로 전달(_connectOnce). */
+    _perMessageDeflate: false | Object;
+    /** @type {import('ws').WebSocket | null} */
+    _ws: import("ws").WebSocket | null;
+    /** @type {boolean} register_ok 수신 여부. */
+    _isRegistered: boolean;
+    /** @type {string | null} hub 가 부여한 hubId. */
+    _hubId: string | null;
+    /** @type {number} register_ok 의 heartbeatMs(0 이면 heartbeat 끔). */
+    _heartbeatMs: number;
+    /** @type {ReturnType<typeof setInterval> | null} */
+    _hbTimer: ReturnType<typeof setInterval> | null;
+    /** type(wire)/lifecycle event → 핸들러 집합. @type {Map<string, Set<Function>>} */
+    _handlers: Map<string, Set<Function>>;
+    /** close() 로 의도적으로 닫는 중인지 — true 면 자동 재연결하지 않는다. @type {boolean} */
+    _isClosing: boolean;
+    /** 재연결 진행 중 가드(중복 reconnect 방지). @type {boolean} */
+    _isReconnecting: boolean;
+    /** close() 가 진행 중인 재시도(백오프 대기)를 취소하기 위한 컨트롤러. @type {AbortController | null} */
+    _abort: AbortController | null;
+    /** register_ok 로 협상된 hub 프로토콜 버전(등록 전 null, 레거시 hub 면 1). @type {number | null} */
+    _negotiatedProtocolVersion: number | null;
+    /**
+     * 레거시 hub 모드 — REGISTER 의 `protocolVersion` 필드를 모르는 구버전 hub(strict 스키마가
+     * `hub.invalid_message` 로 거부)로 판정되면 true. 이후 register 는 필드 없이(v1) 보낸다.
+     * @type {boolean}
+     */
+    _isLegacyHub: boolean;
+    /** hub 가 부여한 hubId (register 전엔 null). */
+    get hubId(): string;
+    /** register_ok 를 받아 사용 가능한 상태인지. */
+    get isRegistered(): boolean;
+    /** 협상된 hub 프로토콜 버전 (register 전엔 null, 레거시 hub 면 1). */
+    get negotiatedProtocolVersion(): number;
+    /** 소켓이 OPEN(=1) 인지. */
+    get isOpen(): boolean;
+    /** 재연결이 활성(retry 옵션 지정)인지. */
+    get canReconnect(): boolean;
+    /**
+     * 수신 메시지/라이프사이클 핸들러 등록. 같은 type 에 여러 개 등록 가능(모두 호출).
+     * @param {string} wireType - {@link HUB_MESSAGE_TYPES} 의 값(`hub.broadcast` 등) 또는
+     *   {@link MegaHubLink.EVENTS} 의 라이프사이클 이벤트(`link.*`).
+     * @param {(msg: Object) => void} handler
+     * @returns {this}
+     */
+    on(wireType: string, handler: (msg: Object) => void): this;
+    /**
+     * hub 연결 + REGISTER 핸드셰이크. register_ok 수신 시 resolve.
+     *
+     * `retry` 옵션이 있으면 최초 연결도 지수 백오프로 재시도한다(ADR-098). 없으면 단발 시도.
+     *
+     * @param {Object} [opts]
+     * @param {number} [opts.connectTimeoutMs] - register_ok 대기 한도 override(M4). **이 값은 인스턴스에
+     *   저장되어(`this._connectTimeoutMs`) 이후 자동 재연결 attempt 에도 동일하게 적용된다** — 이 한 번의
+     *   connect() 에만 적용되는 것이 아니다(L-1). 재연결마다 같은 타임아웃을 쓰는 동작은 의도된 것이다.
+     * @returns {Promise<{ hubId: string, heartbeatMs: number }>}
+     * @throws register 전 에러/종료/타임아웃(재시도 소진 포함) 시 reject.
+     */
+    connect({ connectTimeoutMs }?: {
+        connectTimeoutMs?: number;
+    }): Promise<{
+        hubId: string;
+        heartbeatMs: number;
+    }>;
+    /**
+     * 단일 연결 시도 — ws open → REGISTER → register_ok. 한 attempt 의 Promise 를 돌려준다.
+     * 재시도/재연결은 호출부({@link MegaHubLink#connect}/{@link MegaHubLink#_reconnect})가 감싼다.
+     *
+     * @param {{ connectTimeoutMs: number }} args
+     * @returns {Promise<{ hubId: string, heartbeatMs: number }>}
+     * @private
+     */
+    private _connectOnce;
+    /**
+     * 등록 후 연결이 끊겼을 때 처리 — DISCONNECTED emit + (retry 활성·의도적 close 아님) 자동 재연결.
+     * @param {number} code - WS close code (4503=drain 등).
+     * @param {string} reason
+     * @private
+     */
+    private _handleEstablishedClose;
+    /**
+     * 자동 재연결 — 백오프로 _connectOnce 반복. 성공 시 RECONNECTED, 소진 시 RECONNECT_FAILED emit.
+     * @returns {Promise<void>}
+     * @private
+     */
+    private _reconnect;
+    /**
+     * 사용자 접속 알림 (JOIN). presence 등록.
+     * @param {{ userId: string, sessionId: string, channels: string[], metadata?: Object }} entry
+     * @returns {void}
+     */
+    join(entry: {
+        userId: string;
+        sessionId: string;
+        channels: string[];
+        metadata?: Object;
+    }): void;
+    /**
+     * 단일 세션 종료 (LEAVE).
+     * @param {string} sessionId
+     * @returns {void}
+     */
+    leave(sessionId: string): void;
+    /**
+     * 다수 세션 일괄 종료 (BULK_LEAVE) — 여러 세션의 presence LEAVE 를 한 프레임으로 보낸다.
+     *
+     * 공개 API 다(프레임워크 내부는 현재 hub 의 bridge-gone 자동 감지에 의존해 직접 호출하지 않음).
+     * 다음 같은 **대량 정리** 상황에서 애플리케이션이 직접 호출한다:
+     *   - 대량 logout(한 사용자의 여러 세션을 한 번에 종료),
+     *   - 클라이언트 풀/탭 정리(연결 다수를 묶어 종료),
+     *   - bridge 가 자체 drain 으로 보유 세션을 능동적으로 비울 때(소켓 close 를 기다리지 않고 선통지).
+     * 세션 1건이면 {@link MegaHubLink#leave} 를 쓰는 편이 단순하다.
+     *
+     * @param {string[]} sessionIds
+     * @returns {void}
+     */
+    bulkLeave(sessionIds: string[]): void;
+    /**
+     * 채널 전체 푸시 (BROADCAST). hub 가 가입 bridge 들에 fan-out.
+     * @param {{ ns: string, channel: string, message: Object, exceptSessionIds?: string[] }} payload
+     * @returns {void}
+     */
+    broadcast(payload: {
+        ns: string;
+        channel: string;
+        message: Object;
+        exceptSessionIds?: string[];
+    }): void;
+    /**
+     * 특정 사용자에게 직접 (DIRECT). hub 가 userId→sessionIds[] fan-out (ADR-035).
+     * @param {{ userId: string, message: Object }} payload
+     * @returns {void}
+     */
+    direct(payload: {
+        userId: string;
+        message: Object;
+    }): void;
+    /**
+     * 세션 메타데이터 갱신 (METADATA) — 명시 필드만(ADR-059).
+     * @param {{ sessionId: string, metadata: Object }} payload
+     * @returns {void}
+     */
+    updateMetadata(payload: {
+        sessionId: string;
+        metadata: Object;
+    }): void;
+    /**
+     * 바이너리 메타 프레임 (BINARY). raw bytes 후속 프레임 전송은 본 Step 미포함(envelope 한정).
+     * @param {{ ref: string, mimeType: string, bytes: number }} payload
+     * @returns {void}
+     */
+    binary(payload: {
+        ref: string;
+        mimeType: string;
+        bytes: number;
+    }): void;
+    /** 연결 종료 — 의도적 close 표시 + 진행 중 재연결 취소 + heartbeat 정리 후 소켓 close. */
+    close(): void;
+    /**
+     * 타입별 송신 — register_ok 이후에만 허용. register 전 호출은 fail-closed throw.
+     * @param {string} type - wire type(`hub.*`).
+     * @param {Object} payload
+     * @returns {void}
+     * @private
+     */
+    private _send;
+    /**
+     * envelope 직렬화 후 소켓 송신.
+     * @param {Object} envelope
+     * @returns {void}
+     * @private
+     */
+    private _sendEnvelope;
+    /**
+     * 수신 메시지를 등록된 핸들러에 디스패치. 핸들러 throw 는 격리(다른 핸들러 보호).
+     * @param {import('../lib/hub-protocol.js').HubEnvelope} msg
+     * @returns {void}
+     * @private
+     */
+    private _dispatch;
+    /**
+     * 라이프사이클 이벤트 emit (RECONNECTED 등). 디스패치와 같은 핸들러 맵을 쓰되 인자는 이벤트 데이터.
+     * @param {string} event - {@link MegaHubLink.EVENTS} 값.
+     * @param {Object} data
+     * @returns {void}
+     * @private
+     */
+    private _emit;
+    /** heartbeat 루프 시작 (heartbeatMs>0 일 때만). 프로세스 종료 막지 않게 unref. @private */
+    private _startHeartbeat;
+    /** heartbeat 루프 정지. @private */
+    private _stopHeartbeat;
+}
+import { WebSocket } from 'ws';