mega-framework 0.1.7 → 0.1.9

package/types/cli/index.d.ts

@@ -96,29 +96,16 @@ export function resolveDb(setting: string | boolean | undefined | null): string
  */
 export function shouldReexecForWatch(flags: Record<string, string | boolean>, env: Record<string, string | undefined>): boolean;
 /**
- * `mega start --watch` → `node --watch … <self> start … --cluster 1` 재실행 명령을 빌드한다 (ADR-182).
+ * `mega start --watch` supervisor 의 **자식 인자**를 빌드한다 (ADR-220, ADR-182 개정).
  *
- * - `--watch` 인자는 **node 플래그**로 옮기고 mega 인자에선 제거한다.
+ * - `--watch`/`--watch-ignore`(값 포함)는 부모(supervisor) 전용 — 자식 인자에서 제거한다
+ *   (가드 env 와 이중 안전으로 무한재귀 방지).
  * - **단일 프로세스 강제**(`--cluster 1`) — 멀티워커 watch 카오스 방지(기존 `--cluster` 값은 무시).
- * - watchPaths 가 있으면 `--watch-path=…`(이게 모듈 그래프 watch 를 **대체**하므로 앱 소스·전역설정 경로를
- *   명시해야 한다 — 실측 확인). 없으면 plain `--watch`(모듈 그래프 폴백).
- *
- * @param {Object} o
- * @param {string[]} o.argv - 원본 mega argv(예: `['start','--watch','--port','3000']`).
- * @param {string[]} o.watchPaths - 감시할 절대경로(존재하는 것만).
- * @param {string} o.selfPath - mega 진입 스크립트(`process.argv[1]`).
- * @param {string} o.execPath - node 바이너리(`process.execPath`).
- * @returns {{ command: string, args: string[] }}
- */
-export function buildWatchCommand({ argv, watchPaths, selfPath, execPath }: {
-    argv: string[];
-    watchPaths: string[];
-    selfPath: string;
-    execPath: string;
-}): {
-    command: string;
-    args: string[];
-};
+ *
+ * @param {string[]} argv - 원본 mega argv(예: `['start','--watch','--port','3000']`).
+ * @returns {string[]} 자식 `mega` 인자(예: `['start','--port','3000','--cluster','1']`).
+ */
+export function buildWatchChildArgs(argv: string[]): string[];
 /**
  * `mega` CLI 진입점. 파싱 → 명령 분기. **이 함수는 process.exit 를 호출하지 않는다**(테스트 가능) —
  * exit code 를 반환하고, bin 래퍼가 `process.exitCode` 로 반영한다.
@@ -178,24 +165,24 @@ export function collectRegistrations(global: Object, host: import("../lib/mega-p
  * 등록 소스 = `config.jobs` + 플러그인 `mega.jobs.register` 분(`collectRegistrations`, ADR-123).
  * @param {string} projectRoot
  * @param {{ debug?: Function, info?: Function, warn?: Function }} [logger]
- * @returns {Promise<MegaJobWorker>}
+ * @returns {Promise<import('../lib/mega-job-worker.js').MegaJobWorker>}
  */
 export function runWorkerHost(projectRoot: string, logger?: {
     debug?: Function;
     info?: Function;
     warn?: Function;
-}): Promise<MegaJobWorker>;
+}): Promise<import("../lib/mega-job-worker.js").MegaJobWorker>;
 /**
  * `mega scheduler` 호스트 골격 — config + 어댑터 connect + ctx + `MegaScheduler` 인스턴스 + graceful.
  * @param {string} projectRoot
  * @param {{ debug?: Function, info?: Function, warn?: Function }} [logger]
- * @returns {Promise<MegaScheduler>}
+ * @returns {Promise<import('../lib/mega-schedule.js').MegaScheduler>}
  */
 export function runSchedulerHost(projectRoot: string, logger?: {
     debug?: Function;
     info?: Function;
     warn?: Function;
-}): Promise<MegaScheduler>;
+}): Promise<import("../lib/mega-schedule.js").MegaScheduler>;
 /**
  * 마이그레이션 대상 DB 어댑터 해석 — `services.databases` 의 globalKey 로 조회한다. `--db <key>` 미지정
  * 시 유일 선언 db, 그게 아니면 `primary`, 둘 다 아니면(다중·미선언) fail-fast 로 명시를 요구한다.
@@ -245,5 +232,3 @@ export const BUILTIN_COMMANDS: Set<string>;
 /** CLI 사용법 텍스트 — commander 자동 생성(ADR-195) + 플러그인 명령 안내. 명령·옵션 정의가 곧 도움말의
  * 단일 정본이라 수기 USAGE 와의 드리프트가 없다. */
 export const USAGE: string;
-import { MegaJobWorker } from '../lib/mega-job-worker.js';
-import { MegaScheduler } from '../lib/mega-schedule.js';

package/types/cli/watch.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 미니 glob → RegExp. 지원: 더블스타+슬래시(0개 이상의 디렉토리), 더블스타(경로 전체), `*`(세그먼트
+ * 내), `?`(1글자). 그 외 문자는 리터럴(정규식 특수문자 escape). 매칭 대상은 루트 상대 POSIX 경로
+ * 전체(^…$). 패턴 예시는 스캐폴드 `.env` 의 `WATCH_IGNORE` 참조 — JS 블록 주석 안에는
+ * 더블스타+슬래시 시퀀스를 쓸 수 없어(주석 조기 종료) 여기 직접 못 적는다.
+ *
+ * @param {string} pattern - glob 패턴(예 `.env.*`).
+ * @returns {RegExp}
+ */
+export function globToRegExp(pattern: string): RegExp;
+/**
+ * ignore 패턴 합성 — config(`watch.ignore`) + CLI(`--watch-ignore a,b`). 숨은 디폴트 없음(모듈
+ * docstring 참조). 잘못된 모양은 fail-fast(silent 무시 금지).
+ *
+ * @param {{ ignore?: unknown }} [watchConfig] - mega.config.js 의 `watch`.
+ * @param {string | undefined} [cliIgnore] - `--watch-ignore` 값(콤마 구분).
+ * @returns {string[]}
+ * @throws {TypeError} config `watch.ignore` 가 문자열 배열이 아닐 때.
+ */
+export function mergeWatchIgnore(watchConfig?: {
+    ignore?: unknown;
+}, cliIgnore?: string | undefined): string[];
+/**
+ * 루트 상대 경로가 ignore 에 걸리는지 (Boolean — `is*`).
+ * @param {string} rel - 루트 상대 POSIX 경로(예 `apps/main/locales/ko.json`).
+ * @param {RegExp[]} regexps - {@link globToRegExp} 컴파일 결과.
+ * @returns {boolean}
+ */
+export function isIgnoredPath(rel: string, regexps: RegExp[]): boolean;
+/**
+ * watch supervisor — 감시 경로의 변경(ignore 통과분)을 debounce 후 자식(`mega start`)을
+ * SIGTERM → respawn 한다. 자식이 스스로 죽으면(crash) 재시작하지 않고 다음 변경을 기다린다
+ * (crash-loop 방지 — nodemon 의 "app crashed - waiting for file changes" 와 동형).
+ *
+ * @param {object} o
+ * @param {string} o.projectRoot
+ * @param {string[]} o.watchPaths - 감시할 절대경로(존재하는 것만 — 호출측이 필터).
+ * @param {string[]} o.ignore - glob 패턴 목록.
+ * @param {() => import('node:child_process').ChildProcess} o.spawnChild - 자식 기동 팩토리(주입 — 테스트).
+ * @param {(msg: string) => void} o.out
+ * @param {number} [o.debounceMs=500] - 연속 변경 디바운스.
+ * @param {(dir: string, opts: object, cb: (event: string, filename: string | Buffer | null) => void) => { close(): void }} [o.watchFn] -
+ *   fs.watch 주입(테스트). 기본 node:fs watch.
+ * @returns {Promise<number>} 부모(supervisor)의 exit code — SIGINT/SIGTERM 수신 시 자식 정리 후 0.
+ */
+export function startWatchSupervisor({ projectRoot, watchPaths, ignore, spawnChild, out, debounceMs, watchFn }: {
+    projectRoot: string;
+    watchPaths: string[];
+    ignore: string[];
+    spawnChild: () => import("node:child_process").ChildProcess;
+    out: (msg: string) => void;
+    debounceMs?: number;
+    watchFn?: (dir: string, opts: object, cb: (event: string, filename: string | Buffer | null) => void) => {
+        close(): void;
+    };
+}): Promise<number>;
+/** {@link startWatchSupervisor} 의 watchPaths 기본 집합 — 존재하는 것만.
+ * @param {string} projectRoot @returns {string[]} */
+export function defaultWatchPaths(projectRoot: string): string[];

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

@@ -63,6 +63,29 @@ export function getHttpCtx({ app, req, reply }: {
     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).
  */

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

@@ -117,7 +117,9 @@ export class MegaHubLink {
     /**
      * hub 연결 + REGISTER 핸드셰이크. register_ok 수신 시 resolve.
      *
-     * `retry` 옵션이 있으면 최초 연결도 지수 백오프로 재시도한다(ADR-098). 없으면 단발 시도.
+     * 초기 연결은 retry 유무와 무관하게 **단 1회** 시도한다. `retry` 옵션이 있으면 실패 시 백그라운드
+     * 재연결(지수 백오프)로 전환하고 reject 한다 — 성공 시 RECONNECTED, 소진 시 RECONNECT_FAILED emit.
+     * 호출부(boot)는 reject 를 warn 으로 받고 부팅을 계속한다(허브 다운이 부팅을 막지 않는 계약).
      *
      * @param {Object} [opts]
      * @param {number} [opts.connectTimeoutMs] - register_ok 대기 한도 override(M4). **이 값은 인스턴스에

package/types/core/index.d.ts

@@ -14,7 +14,7 @@ export { bootApp, buildBootContext } from "./boot.js";
 export { wrapEnvelope, errorEnvelope, synthesizeEnvelopeResponseSchema, ENVELOPE_MARK } from "./envelope.js";
 export { buildHttpPipeline, wrapPreHandler, composeTransform, composeAfter } from "./pipeline.js";
 export { ajvErrorToValidationError, MAX_VALIDATION_DETAILS } from "./ajv-mapper.js";
-export { buildHttpCtx, getHttpCtx, buildAdapterAccessors } from "./ctx-builder.js";
+export { buildHttpCtx, getHttpCtx, getLazyHttpCtx, buildAdapterAccessors } from "./ctx-builder.js";
 export { createWsMessage, validateWsMessage, parseWsMessage, generateMessageId, WS_MESSAGE_SCHEMA, WS_PROTOCOL_VERSION, WS_TYPE_PATTERN } from "./ws-message.js";
 export { MegaWsConnection, driveWsConnection, createPlainCodec, createAspCodec, rejectUpgrade, CLOSE_CODE_DECRYPT_FAILED, CLOSE_CODE_INTERNAL_ERROR } from "./ws-upgrade.js";
 export { buildPerMessageDeflate, checkCompressionConfig, COMPRESSION_DEFAULTS } from "./ws-compression.js";

package/types/core/mega-app.d.ts

@@ -35,7 +35,7 @@ export class MegaApp {
      * @param {Object|false} [opts.helmet] - fastify-helmet 옵션 (보안 헤더). false=미등록, undefined=디폴트 ON
      *   (ADR-047/127). 라우트 옵션 오버라이드는 완전 교체(ADR-073).
      * @param {Object|false} [opts.cors] - fastify-cors 옵션. false=미등록, undefined=origin:false(교차출처 거부, 안전 디폴트).
-     * @param {Object|false} [opts.rateLimit] - fastify-rate-limit 옵션. false=미등록, undefined=디폴트(IP당 100/min, ADR-048).
+     * @param {Object|false} [opts.rateLimit] - fastify-rate-limit 옵션. false=미등록, undefined=디폴트(IP당 1000/min, ADR-048/197).
      *   멀티 인스턴스 분산 카운팅은 `caches.rate` 별명(Redis), 미선언 시 in-memory 폴백.
      * @param {Object|false} [opts.csrf] - fastify-csrf-protection 옵션. false=미등록, undefined=디폴트 ON.
      *   ADR-051: JSON 요청은 토큰 면제+Origin 검증, 폼 요청만 토큰 검증.

package/types/core/pipeline.d.ts

@@ -1,7 +1,8 @@
 /**
  * 미들웨어를 Fastify 가 async preHandler 로 인식하는 arity-2 래퍼로 감싸고, canonical ctx 를
  * 3번째 인자로 주입한다 — 핸들러·글로벌 미들웨어와 동일한 `(req, reply, ctx)` 계약(ADR-134/184).
- * getHttpCtx 는 요청당 캐싱이라 같은 요청의 모든 미들웨어·핸들러가 동일 ctx 객체를 공유한다.
+ * ctx 는 **lazy 프록시**(ADR-214) — 미들웨어가 실제로 속성을 만질 때만 빌드되고, 요청당 캐싱이라
+ * 같은 요청의 모든 미들웨어·핸들러가 동일 ctx 객체를 공유한다.
  *
  * @param {Function} fn - `(req, reply, ctx?)` 미들웨어 (arity-2 도 하위 호환 — 3번째 인자 무시).
  * @param {import('./mega-app.js').MegaApp | null} [app] - ctx 의 어댑터·서비스 접근자 출처(없으면 null).

package/types/core/security.d.ts

@@ -21,7 +21,7 @@
  * @param {string[]} [opts.hosts] - 앱 도메인 목록(CSRF Origin 검증 allowlist, ADR-051).
  * @param {Object|false} [opts.helmet] - fastify-helmet 옵션. false=미등록, undefined=디폴트 ON.
  * @param {Object|false} [opts.cors] - fastify-cors 옵션. false=미등록, undefined=origin:false(교차출처 거부).
- * @param {Object|false} [opts.rateLimit] - fastify-rate-limit 옵션. false=미등록, undefined=디폴트(100/min).
+ * @param {Object|false} [opts.rateLimit] - fastify-rate-limit 옵션. false=미등록, undefined=디폴트(1000/min, ADR-214).
  * @param {Object|false} [opts.csrf] - fastify-csrf-protection 옵션. false=미등록, undefined=디폴트 ON.
  * @param {{ masterSecret?: string, http?: { enabledPaths?: string[], driftMs?: number, headerSignal?: string, timestampHeader?: string, nonceCache?: any } }} [opts.asp] -
  *   ASP 설정. `masterSecret` + `http.enabledPaths`(비어있지 않음)가 둘 다 있을 때만 HTTP ASP 등록.
@@ -53,9 +53,9 @@ export function registerSecurityPlugins(fastify: import("fastify").FastifyInstan
         warn?: Function;
     };
 }): SecuritySummary;
-/** rate-limit 기본값 (ADR-048: IP 당 100 req/min). 사용자 config 로 완전 교체(ADR-073). */
+/** rate-limit 기본값 (IP 당 1000 req/min — ADR-048 의 100/min 은 평상 트래픽도 429 를 만드는 운영 함정이라 상향, ADR-214). 사용자 config 로 완전 교체(ADR-073). */
 export const DEFAULT_RATE_LIMIT: Readonly<{
-    max: 100;
+    max: 1000;
     timeWindow: "1 minute";
 }>;
 /**

package/types/core/session-store.d.ts

@@ -14,5 +14,12 @@ export function createSessionStore(storeConfig: {
 }, defaults?: {
     ttlMs?: number;
 }): import("../adapters/mega-session-adapter.js").MegaSessionAdapter;
+/**
+ * file driver 만료 스캔 cleanup 기본 주기(1시간, ms) — ADR-046 의 "file 모드 cleanup 자동" 약속 구현(ADR-215).
+ * 어댑터 자체 디폴트는 0(off)이라, 팩토리 경유 생성(=프레임워크 부팅 경로)에서만 기본 주기를 주입한다.
+ * 만료 파일의 lazy 삭제는 같은 sid 재접근 시에만 일어나므로, 주기 스캔이 없으면 미접근 만료 세션이
+ * 디스크에 무한 누적된다(G5 audit M-3). `cleanupIntervalMs: 0` 명시로 옵트아웃(외부 cron/scheduler 운용 시).
+ */
+export const DEFAULT_FILE_CLEANUP_INTERVAL_MS: 3600000;
 /** 지원 세션 driver 목록(테스트·문서용). */
 export const SESSION_STORE_DRIVERS: readonly string[];

package/types/core/ws-roster.d.ts

@@ -57,6 +57,15 @@ export class MegaWsRedisRoster {
      * @param {string} channel @param {string} sessionId @param {RosterMember} member @returns {Promise<void>}
      */
     add(channel: string, sessionId: string, member: RosterMember): Promise<void>;
+    /**
+     * ioredis pipeline.exec() 결과(`[err, res][]`)에서 첫 명령 오류를 throw 한다 — pipeline 은 명령별
+     * 오류를 reject 가 아니라 결과 배열에 싣기 때문에, 묵히면 호출부의 기존 실패 처리(catch+warn)가
+     * 더는 동작하지 않는다(직렬 await 시절의 throw 계약 유지).
+     * @param {Array<[Error | null, any]> | null} results
+     * @returns {void}
+     * @private
+     */
+    private _throwFirstPipelineError;
     /**
      * 채널 roster 에서 멤버 제거(disconnect).
      * @param {string} channel @param {string} sessionId @returns {Promise<void>}
@@ -78,7 +87,10 @@ export class MegaWsRedisRoster {
      */
     startHeartbeat(): void;
     /**
-     * 로컬 멤버 전체를 다시 add(=expiresAt 갱신). @returns {Promise<void>} @private
+     * 로컬 멤버 전체의 `expiresAt` 을 한 pipeline 으로 일괄 갱신. 직렬 add 루프(멤버당 2 RT)는 멤버
+     * 1,000 에 주기당 수백 ms — 갱신 지연이 TTL 윈도를 침식해 살아있는 세션이 lazy 만료될 수 있었다.
+     * pipeline 이면 단일 왕복 수준(실측 ~200×). 채널 키 PEXPIRE 는 채널당 1회만 싣는다.
+     * @returns {Promise<void>} @private
      */
     private _refreshLocal;
     /**

package/types/core/ws-upgrade.d.ts

@@ -1,3 +1,23 @@
+/**
+ * 프로세스 합산 send budget 을 조정한다(ADR-215). 부팅/운영 튜닝 진입점.
+ * @param {{ maxTotalBufferedBytes?: number }} [opts] - 바이트 budget. `0` = 무제한(옵트아웃).
+ * @returns {{ maxTotalBufferedBytes: number }} 적용된 현재 값.
+ * @throws {TypeError} 음수/비숫자 — 설정 실수 fail-fast.
+ */
+export function configureWsSendBudget({ maxTotalBufferedBytes: max }?: {
+    maxTotalBufferedBytes?: number;
+}): {
+    maxTotalBufferedBytes: number;
+};
+/**
+ * 테스트 격리용 — budget 상태 초기화(추적 Set·스로틀·budget 디폴트 복원).
+ * @returns {void}
+ */
+export function _resetWsSendBudget(): void;
+/** 테스트용 — 연결을 budget 추적에 등록. @param {MegaWsConnection} conn @returns {void} */
+export function _trackWsSendBudget(conn: MegaWsConnection): void;
+/** 테스트용 — 스로틀 우회 가능한 스윕 직접 호출. @param {number} [now] @returns {void} */
+export function _sweepWsSendBudget(now?: number): void;
 /**
  * 라우트 opts 의 `heartbeatMs` 를 검증해 반환한다. 미지정 → 기본 30초, `0` = liveness 끔.
  * 무효값(음수/비정수/비숫자)은 운영 실수 — 조용히 보정하지 않고 warn 로그 후 기본값을 쓴다
@@ -116,6 +136,15 @@ export const CLOSE_CODE_SLOW_CONSUMER: 1013;
 export const CLOSE_CODE_REQUEUE: 4503;
 /** send 버퍼(bufferedAmount) 기본 상한(바이트). 초과 = 소비자가 ack 를 못 따라옴 → 연결 종료(서버 OOM 방지). */
 export const DEFAULT_MAX_BUFFERED_BYTES: number;
+/**
+ * 프로세스 **합산** send 버퍼 기본 budget(바이트, ADR-215 — G5 audit M-6).
+ *
+ * per-conn 상한(위 16MiB)은 연결 1개의 OOM 방어일 뿐이라, 느린 소비자 N 개가 각자 cap 직전까지
+ * 쌓으면 합산은 무제한이었다(이론상 1,000개 × 16MiB = 16GB). 합산이 본 budget 을 넘으면 **가장 큰
+ * 송신 큐를 보유한 연결부터** 1013(slow consumer)으로 종료해 budget 아래로 회수한다.
+ * `configureWsSendBudget({ maxTotalBufferedBytes: 0 })` 으로 무제한 옵트아웃.
+ */
+export const DEFAULT_MAX_TOTAL_BUFFERED_BYTES: number;
 /**
  * 클라↔bridge ping/pong liveness 기본 주기(ms) — 30초. 주기마다 ping 을 보내고 직전 주기의 pong 이
  * 없으면 half-open(상대 사망·네트워크 단절) 으로 보고 terminate 한다 — 좀비 연결이 OS TCP 타임아웃까지

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

@@ -182,8 +182,10 @@ export type MegaCircuitBreakerOptions = {
      */
     rollingCountBuckets?: number;
     /**
-     * - 이 횟수만큼 호출이 쌓이기 전엔 실패율이 높아도 open 안 함
-     * (표본 부족으로 인한 조기 trip 방지). 0=비활성.
+     * - 롤링 윈도우에 이 횟수만큼 호출이 쌓이기 전엔 실패율이
+     * 높아도 open 안 함(표본 부족 조기 trip 방지). 0=비활성. ⚠️ opossum 정본값(0)과 다른 프레임워크
+     * 디폴트 — 0 이면 부팅 직후/저빈도 호출에서 **첫 실패 1건**이 실패율 100% 가 돼 즉시 30s 차단되는
+     * 풋건이라 5 로 올렸다. opossum 원 동작이 필요하면 명시적으로 0 을 지정.
      */
     volumeThreshold?: number;
     /**

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

@@ -12,6 +12,13 @@ export function register(name: string, fn: () => Promise<{
 }, opts?: {
     timeoutMs?: number;
 }): void;
+/**
+ * 등록된 체크 제거(이름 기준). 닫힌 자원(예: hub link)의 체크가 stale 클로저로 남지 않게
+ * 소유자가 register 와 짝맞춰 부른다.
+ * @param {string} name
+ * @returns {boolean} 제거됐으면 true(미등록 이름이면 false).
+ */
+export function unregister(name: string): boolean;
 /**
  * 모든 체크 실행 (병렬). 하나라도 false 면 전체 ok=false.
  * @returns {Promise<{ ok: boolean, checks: Record<string, { ok: boolean, error?: string, [key: string]: any }> }>}

package/types/lib/mega-job-queue.d.ts

@@ -12,6 +12,8 @@ export const DEFAULT_RUN_TIMEOUT_MS: number;
  *   하트비트가 이 값의 절반마다 lease 를 갱신한다.
  * @property {number} [maxDeliver=5] - JetStream 최대 전달 횟수(워커 크래시 재전달 backstop).
  * @property {number} [heartbeatMs] - `working()` 전송 주기(ms). 기본 `max(1000, ackWaitMs/2)`.
+ *   양의 정수 + `< ackWaitMs` 필수(생성자 fail-fast) — 이상이면 lease 갱신이 늦어 정상 처리 중
+ *   중복 재전달, 0 이하면 working() 플러딩.
  * @property {string} [streamPrefix='MEGA_JOBS'] - 스트림 이름 접두사.
  * @property {number} [dlqMaxAgeMs=604800000] - DLQ 스트림 메시지 보존 기한(ms, 디폴트 7일). 초과한 실패
  *   잡은 NATS 가 자동 만료시킨다(무한 적재 방지, ADR-134). `0` 이면 무제한(끔 — 영구 보존). **신규 DLQ
@@ -73,10 +75,18 @@ export class MegaJobQueue extends EventEmitter<any> {
      */
     ensureStream(JobClass: typeof MegaJob): Promise<void>;
     /**
-     * 잡을 큐에 넣는다(JetStream publish — 서버에 영속 저장). 스트림이 없으면 만든다.
-     * @param {typeof MegaJob} JobClass @param {any} payload @returns {Promise<{ seq: number, stream: string, duplicate: boolean }>}
-     */
-    enqueue(JobClass: typeof MegaJob, payload: any): Promise<{
+     * 잡을 큐에 넣는다(JetStream publish — 서버에 영속 저장). 스트림이 없으면 만든다(subject 별 1회 확인 후 캐시).
+     *
+     * @param {typeof MegaJob} JobClass @param {any} payload
+     * @param {{ msgID?: string }} [opts] - `msgID` = JetStream `Nats-Msg-Id` dedup 키(옵트인). 스트림
+     *   duplicate window(NATS 기본 2분 — 운영자가 NATS CLI 로 스트림별 조정) 안의 같은 msgID 재발행은
+     *   적재되지 않고 `duplicate: true` 로 반환된다. 비즈니스 멱등키(주문 ID 등)를 권장. 미지정 시
+     *   dedup 없음 — `duplicate` 는 항상 false.
+     * @returns {Promise<{ seq: number, stream: string, duplicate: boolean }>}
+     */
+    enqueue(JobClass: typeof MegaJob, payload: any, { msgID }?: {
+        msgID?: string;
+    }): Promise<{
         seq: number;
         stream: string;
         duplicate: boolean;
@@ -129,6 +139,8 @@ export type MegaJobQueueOptions = {
     maxDeliver?: number;
     /**
      * - `working()` 전송 주기(ms). 기본 `max(1000, ackWaitMs/2)`.
+     * 양의 정수 + `< ackWaitMs` 필수(생성자 fail-fast) — 이상이면 lease 갱신이 늦어 정상 처리 중
+     * 중복 재전달, 0 이하면 working() 플러딩.
      */
     heartbeatMs?: number;
     /**

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

@@ -92,7 +92,14 @@ export class MegaJob {
     static subject: string | undefined;
     /** @type {string|undefined} bus 별명(`ctx.bus(alias)`). 워커 배선이 nc 해석에 사용. */
     static bus: string | undefined;
-    /** @type {number} 동시 처리 메시지 수(consumer max_ack_pending). 기본 1(순차·안전). */
+    /**
+     * @type {number} 동시 처리 메시지 수. 기본 1(순차·안전).
+     *
+     * ⚠️ 이 값은 durable consumer 의 `max_ack_pending` 으로 들어가므로 **워커 그룹(같은 subject 를
+     * 소비하는 모든 인스턴스) 전체의 합산 in-flight 상한**이다 — `mega worker` 인스턴스를 늘려도
+     * 합산 동시 처리는 이 값을 넘지 못한다. 처리량을 늘리려면 인스턴스 증설과 **함께** concurrency 를
+     * 키워야 한다(실측: c=1→c=32 에서 처리량 ~10배).
+     */
     static concurrency: number;
     /** @type {number} run 실패 시 **추가** 재시도 횟수(첫 시도 제외). 기본 3(OQ-012). */
     static retries: number;

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

@@ -53,7 +53,7 @@ export const CORE_API_VERSION: string;
  * @property {Array<{ path: string, template: string }>} files
  * @property {string} [description] - `mega help` 가 병기하는 한 줄 설명(선택).
  */
-/** 빌트인 generator 13종 이름 — 플러그인 scaffold 가 점유 금지(빌트인이 우선이라 silent shadow 가 됨).
+/** 빌트인 generator 이름 — 플러그인 scaffold 가 점유 금지(빌트인이 우선이라 silent shadow 가 됨).
  * cli/generators 의 `GENERATOR_KINDS` 와 동일해야 한다(레이어 역전 회피를 위해 미러 — 동기화는
  * mega-plugin 단위 테스트가 GENERATOR_KINDS 와 집합 비교로 강제한다). */
 export const RESERVED_GENERATOR_NAMES: Set<string>;

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

@@ -37,8 +37,10 @@ export class MegaWorker extends EventEmitter<any> {
     get mode(): "thread" | "process";
     /** @returns {number} 풀 크기. */
     get poolSize(): number;
-    /** @returns {number} crash 교체 허용 총량. */
+    /** @returns {number} 윈도우({@link MegaWorker#restartWindowMs}) 내 crash 교체 허용 횟수. */
     get maxRestarts(): number;
+    /** @returns {number} crash 교체 판정 슬라이딩 윈도우(ms). `static restartWindowMs` 로 조정. */
+    get restartWindowMs(): number;
     /** @returns {boolean} start() 후 stop() 전이면 true. */
     get isStarted(): boolean;
     /** @param {'dispatch'|'done'|'fail'|'crash'|'stopped'} event @param {(payload: any) => void} listener @returns {this} */

package/types/lib/ws-hub.d.ts

@@ -69,11 +69,12 @@ export class MegaWsHub {
     _wss: WebSocketServer | null;
     /** heartbeat liveness 체크 interval (M3). @type {ReturnType<typeof setInterval> | null} */
     _livenessTimer: ReturnType<typeof setInterval> | null;
-    /** 등록된 bridge 연결. connId → { socket, lastSeen, protocolVersion }. @type {Map<string, { socket: import('ws').WebSocket, lastSeen: number, protocolVersion?: number }>} */
+    /** 등록된 bridge 연결. connId → { socket, lastSeen, protocolVersion, presenceFanout }. @type {Map<string, { socket: import('ws').WebSocket, lastSeen: number, protocolVersion?: number, presenceFanout?: boolean }>} */
     _bridges: Map<string, {
         socket: import("ws").WebSocket;
         lastSeen: number;
         protocolVersion?: number;
+        presenceFanout?: boolean;
     }>;
     /** presence. sessionId → { bridgeConnId, userId, channels:Set, metadata }. @type {Map<string, { bridgeConnId: string, userId: string, channels: Set<string>, metadata: Object }>} */
     _sessions: Map<string, {
@@ -86,6 +87,13 @@ export class MegaWsHub {
     _channelSessions: Map<string, Set<string>>;
     /** userId → sessionId 집합 (DIRECT fan-out, ADR-035). @type {Map<string, Set<string>>} */
     _userSessions: Map<string, Set<string>>;
+    /**
+     * 역인덱스: channel → (bridgeConnId → 그 bridge 의 채널 내 세션 수). BROADCAST 의 bridge 선정을
+     * 세션 수 무관 O(bridge 수)로 만든다 — 멤버 10k 채널에서 메시지당 수백 µs 가 µs 대로 떨어진다.
+     * `_addSession`/`_removeSession` 이 증분 유지(카운트 0 → 키 제거), 메모리는 채널×bridge 수준.
+     * @type {Map<string, Map<string, number>>}
+     */
+    _channelBridges: Map<string, Map<string, number>>;
     /** hub 식별자. */
     get hubId(): string;
     /** 등록된 bridge 수 (테스트/관측용). */
@@ -148,6 +156,12 @@ export class MegaWsHub {
      * @private
      */
     private _addSession;
+    /**
+     * channel→bridge 역인덱스 증분 갱신. 카운트가 0 이 되면 키를 지워 인덱스가 stale 하지 않게 한다.
+     * @param {string} channel @param {string} connId @param {1|-1} delta
+     * @private
+     */
+    private _bumpChannelBridge;
     /**
      * presence 에서 세션 제거. 빈 인덱스는 정리.
      * @param {string} sessionId
@@ -162,12 +176,23 @@ export class MegaWsHub {
      */
     private _handleBridgeGone;
     /**
-     * origin 을 제외한 모든 등록 bridge 로 송신 (presence 공유용). envelope 는 1회만 직렬화(L5).
+     * origin 을 제외한 모든 등록 bridge 로 송신. envelope 는 1회만 직렬화(L5).
+     * BULK_LEAVE(bridge-gone 정리 통지)처럼 전 bridge 가 받아야 하는 통지에 쓴다.
      * @param {string} exceptConnId
      * @param {Object} envelope
      * @private
      */
     private _fanOutToOthers;
+    /**
+     * presence(JOIN/LEAVE/METADATA) fan-out — `presence-fanout` capability 를 선언한 bridge 에만 송신.
+     * roster 가 redis 로 분리(ADR-177)된 뒤 표준 bridge 는 이 타입들을 no-op 으로 버리므로, 옵트인하지
+     * 않은 bridge 에는 보내지 않는다 — 세션 churn × bridge 수 만큼의 죽은 프레임을 제거한다.
+     * 구버전 bridge 호환: hub presence 를 실제로 쓰려는 bridge 는 capability 로 명시 선언한다.
+     * @param {string} exceptConnId
+     * @param {Object} envelope
+     * @private
+     */
+    private _fanOutPresence;
     /**
      * 한 채널의 세션을 가진 bridge 들로 fan-out (origin 제외, 중복 bridge 1회). 직렬화 1회(L5).
      *