mega-framework 0.1.6 → 0.1.8

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

@@ -0,0 +1,260 @@
+/**
+ * 스케줄 분산 락 설정. **lock 도메인은 cache 와 별개**(ADR-113) — `ctx.lock(alias)`.
+ *
+ * @typedef {Object} MegaScheduleLock
+ * @property {string} lock - lock 어댑터 별명(`ctx.lock(alias)` 로 해석). 03-api-spec 의 옛 `cache` 필드를
+ *   대체한다(lock 이 독립 도메인이 된 뒤 정합 — ADR-118).
+ * @property {number} ttl - 락 보유 시간(**밀리초**, 양의 정수). 임계구역 동안 **자동 연장**되므로
+ *   (redlock `using`) 작업이 ttl 을 넘겨도 중복 실행되지 않는다 — ttl 은 "연장 1회분 윈도우"다.
+ *   ⚠️ redlock 은 `ttl ≥ automaticExtensionThreshold(기본 500ms) + 100ms` 를 요구한다(기본 설정 기준
+ *   **600ms 이상**) — 미달이면 fire 시 skip(error 동봉)으로 표면화된다.
+ * @property {string} [key] - 락 자원 키. 미지정 시 `mega:schedule:<클래스명>`.
+ */
+/**
+ * 스케줄 작업 베이스 클래스. 서브클래스가 static 설정과 `run(ctx)` 를 정의한다.
+ *
+ * @example
+ * export class DailyCleanup extends MegaSchedule {
+ *   static cron = '0 3 * * *'
+ *   static timezone = 'Asia/Seoul'
+ *   static lock = { lock: 'main', ttl: 60_000 }   // 분산 중복방지 (ms!)
+ *   async run(ctx) {
+ *     await ctx.db('main').native.query('DELETE FROM tmp WHERE ...')
+ *   }
+ * }
+ */
+export class MegaSchedule {
+    /** @type {string|undefined} cron 표현식(필수 — 미정의 시 register 에서 throw). */
+    static cron: string | undefined;
+    /** @type {string|undefined} IANA 타임존(예: 'Asia/Seoul'). 미지정 시 호스트 로컬. */
+    static timezone: string | undefined;
+    /** @type {MegaScheduleLock|undefined} 분산 중복방지 락 설정. 미지정 시 중복방지 없이 실행. */
+    static lock: MegaScheduleLock | undefined;
+    /**
+     * 스케줄 시각마다 실행되는 본문. 서브클래스가 **반드시** 구현한다.
+     * @param {Record<string, any>} _ctx - 실행 컨텍스트(`db/cache/bus/lock` 접근자 등, ctx-builder 참조).
+     * @returns {Promise<any>}
+     * @throws {Error} 서브클래스가 구현하지 않으면.
+     */
+    run(_ctx: Record<string, any>): Promise<any>;
+}
+/**
+ * @typedef {Object} MegaScheduleFireResult - {@link MegaScheduler#runNow} / 내부 fire 의 결과.
+ * @property {string} name - 스케줄 클래스명.
+ * @property {boolean} ran - 실제로 run(ctx) 가 호출됐는지(skip 이면 false).
+ * @property {boolean} skipped - 락 미획득으로 건너뛰었는지.
+ * @property {boolean} ok - run(ctx) 가 에러 없이 끝났는지(skip 이면 false).
+ * @property {any} [result] - run(ctx) 반환값(성공 시).
+ * @property {Error} [error] - 실패/skip 사유.
+ */
+/**
+ * @typedef {Object} ScheduleEntry - 등록된 스케줄 1건의 내부 메타데이터.
+ * @property {string} name - 스케줄 클래스명(= 등록 키).
+ * @property {typeof MegaSchedule} ScheduleClass - 등록된 클래스.
+ * @property {MegaSchedule} instance - 인스턴스(run 호출 대상).
+ * @property {string} cron - cron 표현식.
+ * @property {string|undefined} timezone - IANA 타임존.
+ * @property {MegaScheduleLock|undefined} lock - 분산 락 설정.
+ * @property {Cron|null} job - start() 가 만든 croner 핸들(미 start 면 null).
+ */
+/**
+ * 등록된 스케줄들을 cron 시각에 실행하는 런타임. 시각/타이머는 croner, 분산 중복방지는 lock 어댑터에 위임.
+ *
+ * @example
+ * const scheduler = new MegaScheduler({ ctx })   // ctx 는 lock 사용 시 ctx.lock(alias) 필요
+ * scheduler.on('skip', (e) => log.debug(e, 'schedule skipped'))
+ * scheduler.on('fail', (e) => log.error(e, 'schedule failed'))
+ * scheduler.register(DailyCleanup).start()
+ * // graceful shutdown
+ * scheduler.stop()
+ */
+export class MegaScheduler extends EventEmitter<any> {
+    /**
+     * @param {object} [args]
+     * @param {Record<string, any>} [args.ctx] - 실행 컨텍스트. 스케줄이 `static lock` 을 쓰면 `ctx.lock`
+     *   (함수)이 있어야 한다(없으면 fire 시 throw). lock 미사용이면 생략 가능.
+     */
+    constructor({ ctx }?: {
+        ctx?: Record<string, any>;
+    });
+    /**
+     * 이벤트 구독. 알 수 없는 이벤트명은 오타로 보고 throw(MegaCircuitBreaker 와 동일).
+     * @param {'run'|'skip'|'done'|'fail'} event @param {(payload: any) => void} listener @returns {this}
+     * @throws {RangeError} 알 수 없는 이벤트명일 때.
+     */
+    on(event: "run" | "skip" | "done" | "fail", listener: (payload: any) => void): this;
+    /**
+     * {@link MegaScheduler#on} 으로 등록한 리스너 해제. 동일 화이트리스트 검증. (`removeListener` 별칭도 보호.)
+     * @param {'run'|'skip'|'done'|'fail'} event @param {(payload: any) => void} listener @returns {this}
+     * @throws {RangeError} 알 수 없는 이벤트명일 때.
+     */
+    off(event: "run" | "skip" | "done" | "fail", listener: (payload: any) => void): this;
+    /**
+     * 1회성 구독(EventEmitter `once`). on() 과 동일 화이트리스트(L-1).
+     * @param {'run'|'skip'|'done'|'fail'} event @param {(payload: any) => void} listener @returns {this}
+     * @throws {RangeError} 알 수 없는 이벤트명일 때.
+     */
+    once(event: "run" | "skip" | "done" | "fail", listener: (payload: any) => void): this;
+    /**
+     * `on` 의 EventEmitter 별칭. 우회로 화이트리스트를 비껴가지 않도록 동일 검증(L-1).
+     * @param {'run'|'skip'|'done'|'fail'} event @param {(payload: any) => void} listener @returns {this}
+     * @throws {RangeError} 알 수 없는 이벤트명일 때.
+     */
+    addListener(event: "run" | "skip" | "done" | "fail", listener: (payload: any) => void): this;
+    /**
+     * `off` 의 EventEmitter 별칭. 동일 화이트리스트 검증(L-1).
+     * @param {'run'|'skip'|'done'|'fail'} event @param {(payload: any) => void} listener @returns {this}
+     * @throws {RangeError} 알 수 없는 이벤트명일 때.
+     */
+    removeListener(event: "run" | "skip" | "done" | "fail", listener: (payload: any) => void): this;
+    /**
+     * 리스너를 큐 앞에 추가(EventEmitter `prependListener`). 동일 화이트리스트 검증(L-1).
+     * @param {'run'|'skip'|'done'|'fail'} event @param {(payload: any) => void} listener @returns {this}
+     * @throws {RangeError} 알 수 없는 이벤트명일 때.
+     */
+    prependListener(event: "run" | "skip" | "done" | "fail", listener: (payload: any) => void): this;
+    /**
+     * 1회성 리스너를 큐 앞에 추가(EventEmitter `prependOnceListener`). 동일 화이트리스트 검증(L-1).
+     * @param {'run'|'skip'|'done'|'fail'} event @param {(payload: any) => void} listener @returns {this}
+     * @throws {RangeError} 알 수 없는 이벤트명일 때.
+     */
+    prependOnceListener(event: "run" | "skip" | "done" | "fail", listener: (payload: any) => void): this;
+    /**
+     * 스케줄 클래스를 등록한다(아직 실행 안 함 — {@link MegaScheduler#start} 가 타이머를 건다).
+     * cron 표현식·lock 설정을 즉시 검증해 잘못된 등록은 부팅 시점에 드러낸다(추측 진행 금지).
+     *
+     * @param {typeof MegaSchedule} ScheduleClass - `MegaSchedule` 를 상속한 클래스.
+     * @returns {this} 체이닝용.
+     * @throws {TypeError} MegaSchedule 서브클래스가 아니거나 cron 이 비었을 때.
+     * @throws {Error} cron 표현식 무효, 이름 중복, lock 설정 형식 오류 시.
+     */
+    register(ScheduleClass: typeof MegaSchedule): this;
+    /**
+     * 등록된 모든 스케줄에 croner 타이머를 걸어 cron 시각마다 자동 실행한다. 이미 start 된 스케줄은 건너뛴다.
+     *
+     * croner 옵션: `protect`(같은 인스턴스에서 이전 실행이 안 끝났으면 새 트리거 차단 — 단일 프로세스 overrun
+     * 방지), `unref`(타이머가 프로세스 종료를 막지 않음 — graceful/테스트), `catch`(타이머 콜백의 미처리
+     * 에러를 `fail` 이벤트로 라우팅 — unhandled rejection 방지).
+     *
+     * @returns {this} 체이닝용.
+     */
+    start(): this;
+    /**
+     * 모든 스케줄 타이머를 영구 중단한다(graceful shutdown 필수 — 안 부르면 타이머가 프로세스 종료를
+     * 늦출 수 있다). croner `stop()` 후엔 같은 인스턴스를 resume 할 수 없어, job 핸들을 비우고 재 start 시
+     * 새로 만든다. 진행 중인 run(ctx) 은 중단하지 않는다(완료까지 대기는 호출부 책임).
+     * @returns {this} 체이닝용.
+     */
+    stop(): this;
+    /**
+     * 스케줄을 **지금 즉시** 한 번 실행한다(cron 시각 무시). 분산 중복방지 로직은 그대로 적용된다 —
+     * 테스트·운영 수동 트리거·CLI 용.
+     *
+     * ⚠️ overlap: lock 미사용 스케줄은 `runNow` 호출 시 croner 의 자동 트리거와 **동일 프로세스 내에서
+     * overlap** 할 수 있다(croner `protect` 는 타이머 트리거끼리만 막고 수동 `runNow` 는 막지 않는다).
+     * 분산/동일프로세스 중복방지가 필요한 작업은 `static lock` 을 선언하라(L-2).
+     * @param {string} name - 등록된 스케줄 클래스명.
+     * @returns {Promise<MegaScheduleFireResult>}
+     * @throws {Error} 등록되지 않은 name 일 때.
+     */
+    runNow(name: string): Promise<MegaScheduleFireResult>;
+    /**
+     * 등록된 스케줄 메타데이터 목록. 모니터링/CLI 용.
+     * @returns {Array<{ name: string, cron: string, timezone: string|undefined, hasLock: boolean, nextRun: Date }>}
+     */
+    list(): Array<{
+        name: string;
+        cron: string;
+        timezone: string | undefined;
+        hasLock: boolean;
+        nextRun: Date;
+    }>;
+    /** @returns {boolean} start() 된 상태면 true. */
+    get isStarted(): boolean;
+    #private;
+}
+/**
+ * 스케줄 분산 락 설정. **lock 도메인은 cache 와 별개**(ADR-113) — `ctx.lock(alias)`.
+ */
+export type MegaScheduleLock = {
+    /**
+     * - lock 어댑터 별명(`ctx.lock(alias)` 로 해석). 03-api-spec 의 옛 `cache` 필드를
+     * 대체한다(lock 이 독립 도메인이 된 뒤 정합 — ADR-118).
+     */
+    lock: string;
+    /**
+     * - 락 보유 시간(**밀리초**, 양의 정수). 임계구역 동안 **자동 연장**되므로
+     * (redlock `using`) 작업이 ttl 을 넘겨도 중복 실행되지 않는다 — ttl 은 "연장 1회분 윈도우"다.
+     * ⚠️ redlock 은 `ttl ≥ automaticExtensionThreshold(기본 500ms) + 100ms` 를 요구한다(기본 설정 기준
+     * **600ms 이상**) — 미달이면 fire 시 skip(error 동봉)으로 표면화된다.
+     */
+    ttl: number;
+    /**
+     * - 락 자원 키. 미지정 시 `mega:schedule:<클래스명>`.
+     */
+    key?: string;
+};
+/**
+ * - {@link MegaScheduler#runNow} / 내부 fire 의 결과.
+ */
+export type MegaScheduleFireResult = {
+    /**
+     * - 스케줄 클래스명.
+     */
+    name: string;
+    /**
+     * - 실제로 run(ctx) 가 호출됐는지(skip 이면 false).
+     */
+    ran: boolean;
+    /**
+     * - 락 미획득으로 건너뛰었는지.
+     */
+    skipped: boolean;
+    /**
+     * - run(ctx) 가 에러 없이 끝났는지(skip 이면 false).
+     */
+    ok: boolean;
+    /**
+     * - run(ctx) 반환값(성공 시).
+     */
+    result?: any;
+    /**
+     * - 실패/skip 사유.
+     */
+    error?: Error;
+};
+/**
+ * - 등록된 스케줄 1건의 내부 메타데이터.
+ */
+export type ScheduleEntry = {
+    /**
+     * - 스케줄 클래스명(= 등록 키).
+     */
+    name: string;
+    /**
+     * - 등록된 클래스.
+     */
+    ScheduleClass: typeof MegaSchedule;
+    /**
+     * - 인스턴스(run 호출 대상).
+     */
+    instance: MegaSchedule;
+    /**
+     * - cron 표현식.
+     */
+    cron: string;
+    /**
+     * - IANA 타임존.
+     */
+    timezone: string | undefined;
+    /**
+     * - 분산 락 설정.
+     */
+    lock: MegaScheduleLock | undefined;
+    /**
+     * - start() 가 만든 croner 핸들(미 start 면 null).
+     */
+    job: Cron | null;
+};
+import { EventEmitter } from 'node:events';
+import { Cron } from 'croner';

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

@@ -0,0 +1,135 @@
+/**
+ * MegaShutdown — graceful shutdown 시퀀스 + 사용자 cleanup hook 묶음.
+ *
+ * 시퀀스 (docs/10 §3) — 명시 stage 로 코드화({@link SHUTDOWN_STAGES}):
+ *   Running → [server → jobs → app → workers → adapters → telemetry → logs] → Exited (process.exit)
+ *
+ * SIGTERM/SIGINT 캐치 + stage 순서 실행(stage 안은 등록 역순 LIFO) + hook 별 grace + hardKill 데드라인.
+ * readiness 503 전환(DrainingReady)은 isShuttingDown() 을 MegaHealth.checkAll 이 읽어 즉시 반영된다.
+ *
+ * API 는 docs/10·07 시퀀스에 맞춰 `MegaShutdown` 객체로 통일 (ADR — M-4).
+ *
+ * 사용 예:
+ *   MegaShutdown.register('my-queue', async () => consumer.stop())             // 기본 stage 'app'
+ *   MegaShutdown.register('db', async () => pool.end(), { stage: 'adapters' }) // 명시 stage
+ *   MegaShutdown.setupSignals({ gracePeriodMs: 30_000, hardKillMs: 60_000 })
+ *   await MegaShutdown.now()   // 수동 트리거
+ */
+/**
+ * 종료 stage 정본 순서 (docs/10 §3 의 단계를 코드로 명시) — `register(name, fn, { stage })` 가 이 중
+ * 하나를 지정하고, `now()` 는 이 배열 순서대로 stage 를 실행한다(stage 안에서는 등록 역순 LIFO).
+ *
+ *   server    — HTTP/WS 수용 종료(서버 close, 진행 중 요청 drain). ClosingHttp/ClosingWs.
+ *   jobs      — 잡 컨슈머·스케줄러 정지(새 잡 수신 중단, 진행 중 잡 완료). ClosingJobs/ClosingScheduler.
+ *   app       — 앱 레벨 정리(플러그인 beforeShutdown·세션 store·WS cluster/roster 등 어댑터를 **쓰는** 정리).
+ *               `stage` 미지정 기본값 — 사용자 cleanup 은 어댑터가 살아 있는 이 단계에서 돈다.
+ *   workers   — CPU 워커 풀·embedded wsHub 등 백그라운드 실행기 정지.
+ *   adapters  — 공유 어댑터 disconnect(DisconnectingAdapters, stage 안 LIFO = connect 역순).
+ *   telemetry — 메트릭·트레이싱 SDK flush/shutdown. 어댑터 **뒤** — disconnect 까지의 span/메트릭을 내보낸다.
+ *   logs      — 로거 flush(FlushingLogs). 항상 마지막 — 종료 시퀀스 자체의 로그가 유실되지 않게.
+ */
+export const SHUTDOWN_STAGES: readonly string[];
+/** hook 1개당 grace 기본값(ms) — 30초. `setupSignals({ gracePeriodMs })` 로 조정. */
+export const DEFAULT_GRACE_PERIOD_MS: 30000;
+/**
+ * graceful shutdown 전체 상한 기본값(ms) — 60초. 초과 시 hardKill(exit 1). 워커 프로세스의 종료 예산
+ * 상한이므로, 클러스터 마스터의 grace(`MegaCluster.gracePeriodMs`)는 **이 값 + 마진 이상**이어야
+ * 워커가 drain 을 끝내기 전에 마스터가 SIGKILL 하는 예산 역전이 없다(CLI 가 이 상수로 위계화).
+ */
+export const DEFAULT_HARD_KILL_MS: 60000;
+export namespace MegaShutdown {
+    export { SHUTDOWN_STAGES as STAGES };
+    export { register };
+    export { unregister };
+    export { isShuttingDown };
+    export { setupSignals };
+    export { setupGlobalErrorHandlers };
+    export { setLogger };
+    export { now };
+    export { registeredCount };
+    export { _reset };
+}
+/**
+ * 전역 에러 핸들러가 fatal 로그에 쓸 로거. boot 이 pino 공유 인스턴스(appLogger)를 주입한다(setLogger).
+ * 미설정(부팅 전 조기 크래시·로거 비활성 프로세스)이면 console.error 로 폴백한다. process 레벨 핸들러는
+ * bootApp 의 DI 그래프 밖이라 모듈 스코프 변수로 받아 둔다(전역 오염 회피, ADR-178).
+ */
+export type ShutdownLogger = {
+    info?: (...args: any[]) => void;
+    warn?: (...args: any[]) => void;
+    error?: (...args: any[]) => void;
+    fatal?: (...args: any[]) => void;
+};
+/**
+ * cleanup hook 등록. 실행 순서 = {@link SHUTDOWN_STAGES} 순서 → 같은 stage 안에서는 등록 역순(LIFO).
+ * `stage` 미지정이면 `'app'`(어댑터 종료 전, 사용자 cleanup 표준 위치) — 기존 2-인자 호출과 호환.
+ * @param {string} name - 식별자 (로그·unregister 용)
+ * @param {() => Promise<void> | void} fn
+ * @param {{ stage?: string }} [opts] - 종료 stage({@link SHUTDOWN_STAGES} 중 하나).
+ */
+declare function register(name: string, fn: () => Promise<void> | void, opts?: {
+    stage?: string;
+}): void;
+/**
+ * 등록된 cleanup hook 제거 (같은 name 전부). 런타임 중 동적으로 붙였다 떼는 hook(예: hub link)
+ * 의 누수를 막는다(L1). shutdown 진행 중에는 실행 추적(exitedHandlers)과 충돌하므로 무시한다.
+ * @param {string} name - register 시 쓴 식별자.
+ * @returns {number} 제거된 hook 수.
+ */
+declare function unregister(name: string): number;
+/**
+ * 현재 shutdown 진행 중인지.
+ * @returns {boolean}
+ */
+declare function isShuttingDown(): boolean;
+/**
+ * SIGTERM/SIGINT 시그널 등록 (한 번만 등록됨). 전역 에러 핸들러(unhandledRejection/uncaughtException)도
+ * 기본 등록한다 — `globalErrorHandlers: false` 로 끌 수 있다(REPL 등).
+ * @param {{ gracePeriodMs?: number, hardKillMs?: number, signals?: string[], globalErrorHandlers?: boolean }} [opts]
+ */
+declare function setupSignals(opts?: {
+    gracePeriodMs?: number;
+    hardKillMs?: number;
+    signals?: string[];
+    globalErrorHandlers?: boolean;
+}): void;
+/**
+ * 전역 `unhandledRejection`/`uncaughtException` 핸들러 등록 (ADR-178, 멱등). floating promise reject 나
+ * 미처리 예외로 프로세스가 **graceful 없이 즉사**(어댑터 disconnect·드레인 미실행 → 커넥션/락 누수, 진행 중
+ * 잡 유실)하는 것을 막는다. 둘 다 fatal 로깅 후 graceful shutdown(exit 1)을 트리거한다 — uncaughtException
+ * 이후의 프로세스 상태는 신뢰 불가라 복구하지 않고 정리 후 종료가 표준.
+ * @param {{ exitCode?: number }} [opts]
+ * @returns {void}
+ */
+declare function setupGlobalErrorHandlers({ exitCode }?: {
+    exitCode?: number;
+}): void;
+/**
+ * 전역 에러 핸들러(unhandledRejection/uncaughtException)가 fatal 로그에 쓸 로거를 주입한다(ADR-178).
+ * boot 이 pino 공유 인스턴스(appLogger)를 만들 때 호출한다. 미호출이면 핸들러는 console.error 로 폴백한다.
+ * @param {ShutdownLogger | null | undefined} logger - pino 호환 로거(info/warn/error/fatal 사용) 또는 null.
+ * @returns {void}
+ */
+declare function setLogger(logger: ShutdownLogger | null | undefined): void;
+/**
+ * 즉시 graceful shutdown 트리거.
+ *
+ * 두 번째 호출(이미 shutdown 진행 중)은 "사용자가 빨리 죽이고 싶다" 는 신호로 보고
+ * 즉시 강제 종료한다 (docs/10 §3 Invariant — M-3).
+ *
+ * @param {{ signal?: string, exitCode?: number }} [opts]
+ */
+declare function now({ signal, exitCode }?: {
+    signal?: string;
+    exitCode?: number;
+}): Promise<void>;
+/**
+ * 테스트용 — 등록된 hook 수 (디버그).
+ * @returns {number}
+ */
+declare function registeredCount(): number;
+/**
+ * 테스트용 — 내부 상태 reset (단위 테스트에서만 호출). 프로덕션 코드는 사용 X.
+ */
+declare function _reset(): void;
+export {};

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

@@ -0,0 +1,224 @@
+/**
+ * inbound 헤더의 `traceparent`(/`tracestate`)를 부모 OTel Context 로 복원한다(ADR-196, W3C trace context).
+ *
+ * 게이트웨이/업스트림이 보낸 trace 에 HTTP 루트 span 을 잇는 입구다 — {@link enterHttpSpan} 의 `headers`
+ * 옵션이 이 함수를 거친다. 헤더가 없거나 형식이 무효면 `undefined`(호출부가 새 루트로 시작 — fail-safe,
+ * 잘못된 외부 입력이 추적을 깨지 않게). 옵트인 OFF 면 `undefined`(0 비용).
+ *
+ * 비율 샘플링(`traceidratio`)은 `ParentBasedSampler` 라 복원된 원격 부모의 sampled flag 를 따른다 —
+ * 업스트림이 샘플한 trace 는 여기서도 기록되고, 버린 trace 는 여기서도 버려져 trace 가 반토막 나지 않는다.
+ *
+ * @param {Record<string, string | string[] | undefined>} headers - `req.headers`(대소문자 무관 키).
+ * @returns {import('@opentelemetry/api').Context | undefined} 유효한 원격 부모 컨텍스트, 없으면 undefined.
+ */
+export function extractRemoteContext(headers: Record<string, string | string[] | undefined>): import("@opentelemetry/api").Context | undefined;
+/**
+ * 현재 활성 span 을 outbound 헤더(`traceparent`/`tracestate`)로 직렬화해 carrier 에 채운다(ADR-196).
+ *
+ * 하류 HTTP 호출에 trace 를 잇는 출구다 — `fetch(url, { headers: ctx.tracer.propagationHeaders() })`.
+ * 활성 span 이 없거나 옵트인 OFF 면 carrier 를 그대로 반환(주입 없음 — 헤더 오염 없음).
+ *
+ * @param {Record<string, string>} [carrier={}] - 채울 헤더 객체(기존 키 보존, traceparent/tracestate 만 추가).
+ * @returns {Record<string, string>} carrier(체이닝용 동일 객체).
+ * @example
+ *   const res = await fetch(downstreamUrl, { headers: MegaTracing.propagationHeaders({ accept: 'application/json' }) })
+ */
+export function propagationHeaders(carrier?: Record<string, string>): Record<string, string>;
+/**
+ * 활성 여부 (Boolean — `is*`, ADR-036). `init` 후 `shutdown` 전이면 true.
+ * @returns {boolean}
+ */
+export function isEnabled(): boolean;
+/**
+ * OTel 트레이싱 초기화. 옵트인 — 본 함수를 부르지 않으면 어떤 어댑터에도 리스너가 안 붙어 0 비용.
+ *
+ * @param {object} opts
+ * @param {string} opts.serviceName - **필수**. `service.name` resource 속성.
+ * @param {string} [opts.endpoint] - OTLP HTTP traces endpoint (예: `http://localhost:4318/v1/traces`).
+ *   지정 + `exporter` 미지정 시 자동으로 `'otlp'` exporter 선택.
+ * @param {'always_on'|'always_off'|`traceidratio:${number}`|number} [opts.sampling='always_on'] -
+ *   샘플러. 비율은 `'traceidratio:0.1'` 또는 숫자 `0.1`(0~1). 비율 샘플러는 `ParentBased` 로 감싼다.
+ * @param {'console'|'otlp'|'zipkin'|'inmemory'|import('@opentelemetry/sdk-trace-base').SpanExporter} [opts.exporter] -
+ *   exporter 종류 문자열 또는 인스턴스 직접 주입(테스트는 `InMemorySpanExporter` 인스턴스). 미지정 시
+ *   `endpoint` 있으면 `'otlp'`, 없으면 `'console'`. `'zipkin'` 은 Zipkin v2 JSON(ADR-126 보강).
+ * @param {'simple'|'batch'} [opts.processor] - span processor. 미지정 시 otlp=`'batch'`, 그 외=`'simple'`.
+ * @param {string} [opts.version] - `service.version` resource 속성.
+ * @param {string} [opts.environment] - `deployment.environment.name` resource 속성.
+ * @param {Record<string, any>} [opts.attributes] - 추가 resource 속성(머지). 시크릿 금지.
+ * @returns {void}
+ * @throws {MegaConfigError} `tracing.already_initialized` / `tracing.service_name_required` / `tracing.invalid_sampling` / `tracing.invalid_exporter`.
+ */
+export function init(opts?: {
+    serviceName: string;
+    endpoint?: string;
+    sampling?: "always_on" | "always_off" | `traceidratio:${number}` | number;
+    exporter?: "console" | "otlp" | "zipkin" | "inmemory" | import("@opentelemetry/sdk-trace-base").SpanExporter;
+    processor?: "simple" | "batch";
+    version?: string;
+    environment?: string;
+    attributes?: Record<string, any>;
+}): void;
+/**
+ * `MEGA_OTEL_*` 환경변수로 옵트인 초기화 (12-factor). `MEGA_OTEL_ENABLED!=='true'` 면 **no-op**
+ * (init 미호출 → 0 비용). 활성 시 `MEGA_OTEL_SERVICE_NAME` 필수.
+ *
+ * 매핑:
+ *   - `MEGA_OTEL_ENABLED` (true|false, 디폴트 false)
+ *   - `MEGA_OTEL_SERVICE_NAME` → serviceName (필수)
+ *   - `MEGA_OTEL_ENDPOINT` → endpoint (OTLP)
+ *   - `MEGA_OTEL_SAMPLING_RATIO` → sampling (숫자 비율; `always_on`/`always_off` 문자열도 허용)
+ *   - `MEGA_OTEL_EXPORTER` → exporter (otlp|console|inmemory)
+ *   - `MEGA_OTEL_VERSION` / `MEGA_OTEL_ENVIRONMENT` → resource 속성
+ *
+ * @param {Record<string, string|undefined>} [env=process.env]
+ * @returns {boolean} 활성화돼 init 했으면 true, 옵트인 OFF 면 false.
+ * @throws {MegaConfigError} 활성인데 serviceName 누락 시 `tracing.service_name_required`.
+ */
+export function fromEnv(env?: Record<string, string | undefined>): boolean;
+/**
+ * 단일 어댑터의 `onCallStart`/`onCallEnd` 를 구독해 span 으로 변환한다. init 전이면 no-op(리스너 미부착).
+ * 이미 구독된 어댑터를 다시 부르면 기존 구독을 유지(중복 부착 방지).
+ *
+ * @param {import('../adapters/mega-adapter.js').MegaAdapter} adapter
+ * @param {{ domain?: string, driver?: string, key?: string }} [meta] - span 속성 보강용 메타.
+ * @returns {() => void} 구독 해제 함수.
+ */
+export function subscribe(adapter: import("../adapters/mega-adapter.js").MegaAdapter, meta?: {
+    domain?: string;
+    driver?: string;
+    key?: string;
+}): () => void;
+/**
+ * 부팅된 전역 어댑터 매니저의 **모든 공유 어댑터**에 hook 리스너를 일괄 구독한다(ADR-102 글로벌 공유).
+ * `connectAll` 이후 호출 권장(연결 안 된 어댑터도 구독은 안전 — 첫 호출 때 span 발화).
+ *
+ * @param {{ entries: () => Array<{ domain: string, key: string, driver: string, adapter: import('../adapters/mega-adapter.js').MegaAdapter }> }} manager -
+ *   `MegaAdapterManager` (entries() 노출). 테스트 더블도 같은 형태면 됨.
+ * @returns {number} 구독한 어댑터 수.
+ */
+export function attachToManager(manager: {
+    entries: () => Array<{
+        domain: string;
+        key: string;
+        driver: string;
+        adapter: import("../adapters/mega-adapter.js").MegaAdapter;
+    }>;
+}): number;
+/**
+ * 트레이싱 종료 — 모든 구독 해제 + 남은 span flush + provider 종료. init 전이면 no-op.
+ * @returns {Promise<void>}
+ */
+export function shutdown(): Promise<void>;
+/**
+ * 현재 exporter 반환(테스트·디버그용). `InMemorySpanExporter` 면 `.getFinishedSpans()` 로 span 검사.
+ * @returns {import('@opentelemetry/sdk-trace-base').SpanExporter | null}
+ */
+export function getExporter(): import("@opentelemetry/sdk-trace-base").SpanExporter | null;
+/**
+ * 강제 flush — `BatchSpanProcessor` 사용 시 테스트에서 span 발화를 기다릴 때.
+ * @returns {Promise<void>}
+ */
+export function forceFlush(): Promise<void>;
+/**
+ * **사용자 직접 span** — `name` span 을 현재 활성 span(없으면 루트)의 자식으로 열고 `fn(span)` 을 그
+ * span 컨텍스트 안에서 실행한다(`run()` 격리). `fn` 이 Promise 면 resolve/reject 까지 기다려 span 을
+ * 닫는다. 옵트인 OFF 면 0 비용 — span 없이 `fn(NOOP_SPAN)` 만 호출한다. `ctx.tracer.span` 의 구현부.
+ *
+ * @template T
+ * @param {string} name - span 이름(예: `'charge.process'`).
+ * @param {(span: import('@opentelemetry/api').Span) => T} fn - span 안에서 실행할 함수(span 인자 받음).
+ * @param {{ attributes?: Record<string, any>, kind?: import('@opentelemetry/api').SpanKind }} [opts]
+ * @returns {T} `fn` 의 반환값(그대로 — 동기/Promise 모두).
+ * @throws {*} `fn` 이 throw/reject 하면 span 에 기록(ERROR)하고 그대로 재전파(silent 금지).
+ */
+export function span<T>(name: string, fn: (span: import("@opentelemetry/api").Span) => T, opts?: {
+    attributes?: Record<string, any>;
+    kind?: import("@opentelemetry/api").SpanKind;
+}): T;
+/**
+ * **시작/종료 분리형 span** — HTTP `onRequest`/`onResponse` 처럼 시작과 종료가 다른 콜백인 경우에 쓴다.
+ * span 을 열고 `enterWith` 로 현재 비동기 흐름의 활성 컨텍스트를 이 span 으로 만든 뒤, `end(err)` 를
+ * 가진 핸들을 돌려준다(핸들은 보통 `req` 에 보관했다가 응답 시 닫는다). 옵트인 OFF 면 no-op 핸들.
+ *
+ * ⚠️ `enterWith` 는 **요청별로 격리된 비동기 흐름**에서만 호출해야 한다(HTTP 요청·WS 메시지 콜백은 각각
+ *   독립 async context 라 안전 — 실측 확인). 공유 동기 스코프에서 부르면 sibling 오염(ADR-114) 위험.
+ *
+ * @param {string} name
+ * @param {{ attributes?: Record<string, any>, kind?: import('@opentelemetry/api').SpanKind, parent?: import('@opentelemetry/api').Context }} [opts]
+ * @returns {{ span: import('@opentelemetry/api').Span, end: (err?: unknown, endAttributes?: Record<string, any>) => void }}
+ */
+export function enterSpan(name: string, opts?: {
+    attributes?: Record<string, any>;
+    kind?: import("@opentelemetry/api").SpanKind;
+    parent?: import("@opentelemetry/api").Context;
+}): {
+    span: import("@opentelemetry/api").Span;
+    end: (err?: unknown, endAttributes?: Record<string, any>) => void;
+};
+/**
+ * **HTTP 루트 span** 전용 헬퍼 — `onRequest` 에서 열고(`enterWith` 로 활성화), `onError` 에서 예외를
+ * 기록(`setError`), `onResponse` 에서 상태코드와 함께 닫는다(`finish`). HTTP 시맨틱(5xx=ERROR)을 한곳에
+ * 모아 배선 코드(mega-app)가 OTel enum 을 안 만지게 한다. 옵트인 OFF 면 no-op 핸들.
+ *
+ * `headers` 를 주면 inbound `traceparent` 를 부모로 복원해({@link extractRemoteContext}, ADR-196) 루트
+ * span 이 업스트림 trace 에 이어진다 — 무효/부재면 종전대로 새 루트.
+ *
+ * @param {{ method: string, route: string, path: string, host?: string, app: string, headers?: Record<string, string | string[] | undefined> }} info
+ * @returns {{ span: import('@opentelemetry/api').Span, setError: (err: unknown) => void, finish: (statusCode: number) => void }}
+ */
+export function enterHttpSpan({ method, route, path, host, app, headers }: {
+    method: string;
+    route: string;
+    path: string;
+    host?: string;
+    app: string;
+    headers?: Record<string, string | string[] | undefined>;
+}): {
+    span: import("@opentelemetry/api").Span;
+    setError: (err: unknown) => void;
+    finish: (statusCode: number) => void;
+};
+/**
+ * 현재 활성 span 의 trace/span id (로그 상관관계용). 활성 span 없거나 옵트인 OFF 면 null.
+ * @returns {{ traceId: string, spanId: string } | null}
+ */
+export function currentTraceIds(): {
+    traceId: string;
+    spanId: string;
+} | null;
+/**
+ * **pino mixin** — 활성 span 이 있으면 모든 로그 라인에 `{ trace_id, span_id }` 를 주입한다(ADR-116 (d)).
+ * 로거가 켜진 앱에서 `logger: { mixin: MegaTracing.logMixin }` 로 배선하면 요청 로그가 trace 와 상관된다.
+ * 활성 span 없으면 빈 객체(주입 없음). 옵트인 OFF 면 항상 빈 객체 → 0 비용.
+ * @returns {{ trace_id?: string, span_id?: string }}
+ */
+export function logMixin(): {
+    trace_id?: string;
+    span_id?: string;
+};
+/**
+ * 테스트 격리용 reset — 동기 강제 정리(provider flush 없이 상태만 비움). 비동기 정상 종료는 `shutdown`.
+ * @returns {void}
+ */
+export function _reset(): void;
+export { SpanKind } from "@opentelemetry/api";
+/**
+ * `ctx.tracer` 로 노출하는 트레이서 표면(ADR-077/116 canonical `ctx.tracer.span`). 모듈 싱글톤 — 활성
+ * 컨텍스트는 ALS 가 요청별로 들고 있으므로 객체 1개를 모든 요청이 공유해도 안전(getter 가 ALS 를 읽음).
+ */
+export const tracer: Readonly<{
+    span: typeof span;
+    /** outbound 헤더에 traceparent/tracestate 주입(ADR-196) — `fetch(url, { headers: ctx.tracer.propagationHeaders() })`. */
+    propagationHeaders: typeof propagationHeaders;
+    /** @returns {import('@opentelemetry/api').Span | undefined} 현재 활성 span(없으면 undefined — 03-api-spec §10). */
+    activeSpan(): import("@opentelemetry/api").Span | undefined;
+    /** @returns {string|null} 현재 활성 trace id(없으면 null). */
+    readonly traceId: string | null;
+    /** @returns {string|null} 현재 활성 span id(없으면 null). */
+    readonly spanId: string | null;
+}>;
+export type TracingState = {
+    provider: import("@opentelemetry/sdk-trace-base").BasicTracerProvider;
+    tracer: import("@opentelemetry/api").Tracer;
+    exporter: import("@opentelemetry/sdk-trace-base").SpanExporter;
+};