mega-framework 0.1.6 → 0.1.7

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

@@ -0,0 +1,176 @@
+/** DLQ 스트림 `max_age` 디폴트(ms) — 7일. 무한 적재 방지(ADR-134). `dlqMaxAgeMs: 0` 으로 끌 수 있다. */
+export const DEFAULT_DLQ_MAX_AGE_MS: number;
+/**
+ * run 전체(재시도 포함) 실행 상한 디폴트(ms) — 30분. 행(hang)된 run 이 `working()` lease 를 영원히
+ * 갱신하며 메시지를 영구 점유하는 것을 막는 backstop. 잡별 `static timeoutMs` 로 override, `0` = 무제한.
+ */
+export const DEFAULT_RUN_TIMEOUT_MS: number;
+/**
+ * @typedef {Object} MegaJobQueueOptions
+ * @property {import('nats').NatsConnection} nc - **연결된** NatsConnection(`ctx.bus(alias).native`).
+ * @property {number} [ackWaitMs=30000] - consumer ack 대기(ms). 초과 시 JetStream 재전달. `working()`
+ *   하트비트가 이 값의 절반마다 lease 를 갱신한다.
+ * @property {number} [maxDeliver=5] - JetStream 최대 전달 횟수(워커 크래시 재전달 backstop).
+ * @property {number} [heartbeatMs] - `working()` 전송 주기(ms). 기본 `max(1000, ackWaitMs/2)`.
+ * @property {string} [streamPrefix='MEGA_JOBS'] - 스트림 이름 접두사.
+ * @property {number} [dlqMaxAgeMs=604800000] - DLQ 스트림 메시지 보존 기한(ms, 디폴트 7일). 초과한 실패
+ *   잡은 NATS 가 자동 만료시킨다(무한 적재 방지, ADR-134). `0` 이면 무제한(끔 — 영구 보존). **신규 DLQ
+ *   스트림 생성 시에만** 적용(멱등 — 기존 스트림은 운영자가 NATS CLI 로 갱신).
+ * @property {number} [dlqMaxBytes] - DLQ 스트림 최대 크기(bytes). 미지정이면 byte 상한 없음(`max_age` 가
+ *   주 가드). 디스크 상한이 필요한 운영 환경에서만 지정.
+ * @property {number} [runTimeoutMs=1800000] - run 전체(재시도 포함) 실행 상한 디폴트(ms, 기본 30분).
+ *   초과 시 잡을 실패로 판정해 DLQ 라우팅 — 행 잡이 `working()` lease 를 영구 갱신하며 메시지를 점유하는
+ *   것을 막는다. 잡별 `static timeoutMs` 가 우선, `0` = 무제한. ⚠️ 타임아웃돼도 진행 중 run 은 중단되지
+ *   않는다(백그라운드 계속 — run 멱등 설계 필요). 나중 실패는 fail(abandoned-run) 으로 표면화.
+ */
+/**
+ * @typedef {Object} MegaJobHandleResult - {@link MegaJobQueue#_handleMessage} 결과(내부/테스트용).
+ * @property {boolean} ok - run 이 성공해 ack 됐는지.
+ * @property {any} [result] - run 반환값(성공 시).
+ * @property {Error} [error] - 실패 사유(실패 시).
+ */
+/**
+ * JetStream 잡 큐 런타임. {@link MegaJob} 클래스를 받아 enqueue/consume·재시도·DLQ 를 처리한다.
+ *
+ * @example
+ * const queue = new MegaJobQueue({ nc: ctx.bus('jobs').native })
+ * queue.on('dlq', (e) => log.error(e, 'job moved to DLQ'))
+ * await queue.enqueue(SendEmailJob, { to: 'a@b.c' })
+ * const sub = await queue.consume(SendEmailJob, new SendEmailJob(), ctx)
+ * // graceful shutdown
+ * await sub.stop()
+ */
+export class MegaJobQueue extends EventEmitter<any> {
+    /**
+     * @param {MegaJobQueueOptions} options
+     * @throws {TypeError} nc 가 JetStream 가능한 NatsConnection 이 아니면(fail-fast).
+     */
+    constructor({ nc, ackWaitMs, maxDeliver, heartbeatMs, streamPrefix, dlqMaxAgeMs, dlqMaxBytes, runTimeoutMs }?: MegaJobQueueOptions);
+    /** @param {'dispatch'|'start'|'done'|'retry'|'fail'|'dlq'} event @param {(payload: any) => void} listener @returns {this} */
+    on(event: "dispatch" | "start" | "done" | "retry" | "fail" | "dlq", listener: (payload: any) => void): this;
+    /** @param {'dispatch'|'start'|'done'|'retry'|'fail'|'dlq'} event @param {(payload: any) => void} listener @returns {this} */
+    off(event: "dispatch" | "start" | "done" | "retry" | "fail" | "dlq", listener: (payload: any) => void): this;
+    /** @param {'dispatch'|'start'|'done'|'retry'|'fail'|'dlq'} event @param {(payload: any) => void} listener @returns {this} */
+    once(event: "dispatch" | "start" | "done" | "retry" | "fail" | "dlq", listener: (payload: any) => void): this;
+    /** @param {'dispatch'|'start'|'done'|'retry'|'fail'|'dlq'} event @param {(payload: any) => void} listener @returns {this} */
+    addListener(event: "dispatch" | "start" | "done" | "retry" | "fail" | "dlq", listener: (payload: any) => void): this;
+    /** @param {'dispatch'|'start'|'done'|'retry'|'fail'|'dlq'} event @param {(payload: any) => void} listener @returns {this} */
+    removeListener(event: "dispatch" | "start" | "done" | "retry" | "fail" | "dlq", listener: (payload: any) => void): this;
+    /** @param {'dispatch'|'start'|'done'|'retry'|'fail'|'dlq'} event @param {(payload: any) => void} listener @returns {this} */
+    prependListener(event: "dispatch" | "start" | "done" | "retry" | "fail" | "dlq", listener: (payload: any) => void): this;
+    /** @param {'dispatch'|'start'|'done'|'retry'|'fail'|'dlq'} event @param {(payload: any) => void} listener @returns {this} */
+    prependOnceListener(event: "dispatch" | "start" | "done" | "retry" | "fail" | "dlq", listener: (payload: any) => void): this;
+    /**
+     * JetStream client/manager·codec 을 지연 초기화한다(멱등 — 동시 호출도 1회만). nats 드라이버는
+     * 여기서 lazy import(어댑터 정합 — 잡 미사용 앱에 nats 로드 강제 안 함).
+     * @returns {Promise<void>}
+     */
+    ensureReady(): Promise<void>;
+    /**
+     * 잡 스트림(workqueue)과 DLQ 스트림(limits)을 멱등 생성한다. 이미 있으면 그대로 둔다(설정 변경은
+     * 운영 책임 — 자동 update 안 함). enqueue/consume 가 자동 호출하므로 보통 직접 부를 필요 없다.
+     * @param {typeof MegaJob} JobClass @returns {Promise<void>}
+     */
+    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<{
+        seq: number;
+        stream: string;
+        duplicate: boolean;
+    }>;
+    /**
+     * 잡 처리를 시작한다 — durable consumer 를 만들고 메시지를 받아 `run(payload, ctx)` 를 재시도와 함께
+     * 실행한다. `static concurrency` 만큼 동시 처리한다. 반환 핸들의 `stop()` 으로 graceful 중단.
+     *
+     * (소비 워커 라이프사이클·bus 별명 배선은 `MegaJobWorker` 영역 — 본 메서드는 "처리 베이스".
+     * 정본 `MegaWorker` = CPU `worker_threads` 풀로 별개 추상(ADR-120/ADR-121).)
+     *
+     * ⚠️ **head-of-line blocking 운영 주의(Med)**: in-flight 상한은 `concurrency`(= `max_ack_pending`)다.
+     * 일시 장애로 **모든 in-flight 가 동시에 긴 백오프**(`static backoff.max` 큼 + `retries` 많음)에 들어가면
+     * 그 subject 처리량이 0 에 수렴하고 정상 메시지도 뒤에서 대기한다(메모리는 안전 — 무한 증가 X). 큰
+     * backoff 를 쓰면 `concurrency` 를 충분히 키우고, 재시도 적체를 메트릭(`job:start`/`fail` 이벤트)으로 관측하라.
+     *
+     * @param {typeof MegaJob} JobClass @param {MegaJob} instance - `run` 호출 대상(서브클래스 인스턴스).
+     * @param {Record<string, any>} ctx - run 에 넘길 컨텍스트.
+     * @returns {Promise<{ stop: () => Promise<void> }>}
+     */
+    consume(JobClass: typeof MegaJob, instance: MegaJob, ctx: Record<string, any>): Promise<{
+        stop: () => Promise<void>;
+    }>;
+    /**
+     * 메시지 1건 처리 — decode → run(재시도) → ack | DLQ. **절대 throw 하지 않는다**(consume 루프의
+     * in-flight Promise 가 reject 되지 않게 — MegaScheduler #fire 와 동일 불변식). 내부/테스트용 seam 이라
+     * `_` 접두사(어댑터 `_connect` 컨벤션).
+     *
+     * @param {MegaJob} instance @param {Record<string, any>} ctx @param {import('nats').JsMsg} msg
+     * @param {ReturnType<typeof resolveJobRetryConfig>} retryConfig @param {string} subject
+     * @param {number} [runTimeoutMs] - run 전체(재시도 포함) 상한(ms). 미지정 시 큐 디폴트, 0 = 무제한.
+     * @returns {Promise<MegaJobHandleResult>}
+     */
+    _handleMessage(instance: MegaJob, ctx: Record<string, any>, msg: import("nats").JsMsg, retryConfig: ReturnType<typeof resolveJobRetryConfig>, subject: string, runTimeoutMs?: number): Promise<MegaJobHandleResult>;
+    #private;
+}
+export type MegaJobQueueOptions = {
+    /**
+     * - **연결된** NatsConnection(`ctx.bus(alias).native`).
+     */
+    nc: import("nats").NatsConnection;
+    /**
+     * - consumer ack 대기(ms). 초과 시 JetStream 재전달. `working()`
+     * 하트비트가 이 값의 절반마다 lease 를 갱신한다.
+     */
+    ackWaitMs?: number;
+    /**
+     * - JetStream 최대 전달 횟수(워커 크래시 재전달 backstop).
+     */
+    maxDeliver?: number;
+    /**
+     * - `working()` 전송 주기(ms). 기본 `max(1000, ackWaitMs/2)`.
+     */
+    heartbeatMs?: number;
+    /**
+     * - 스트림 이름 접두사.
+     */
+    streamPrefix?: string;
+    /**
+     * - DLQ 스트림 메시지 보존 기한(ms, 디폴트 7일). 초과한 실패
+     * 잡은 NATS 가 자동 만료시킨다(무한 적재 방지, ADR-134). `0` 이면 무제한(끔 — 영구 보존). **신규 DLQ
+     * 스트림 생성 시에만** 적용(멱등 — 기존 스트림은 운영자가 NATS CLI 로 갱신).
+     */
+    dlqMaxAgeMs?: number;
+    /**
+     * - DLQ 스트림 최대 크기(bytes). 미지정이면 byte 상한 없음(`max_age` 가
+     * 주 가드). 디스크 상한이 필요한 운영 환경에서만 지정.
+     */
+    dlqMaxBytes?: number;
+    /**
+     * - run 전체(재시도 포함) 실행 상한 디폴트(ms, 기본 30분).
+     * 초과 시 잡을 실패로 판정해 DLQ 라우팅 — 행 잡이 `working()` lease 를 영구 갱신하며 메시지를 점유하는
+     * 것을 막는다. 잡별 `static timeoutMs` 가 우선, `0` = 무제한. ⚠️ 타임아웃돼도 진행 중 run 은 중단되지
+     * 않는다(백그라운드 계속 — run 멱등 설계 필요). 나중 실패는 fail(abandoned-run) 으로 표면화.
+     */
+    runTimeoutMs?: number;
+};
+/**
+ * - {@link MegaJobQueue#_handleMessage} 결과(내부/테스트용).
+ */
+export type MegaJobHandleResult = {
+    /**
+     * - run 이 성공해 ack 됐는지.
+     */
+    ok: boolean;
+    /**
+     * - run 반환값(성공 시).
+     */
+    result?: any;
+    /**
+     * - 실패 사유(실패 시).
+     */
+    error?: Error;
+};
+import { EventEmitter } from 'node:events';
+import { MegaJob } from './mega-job.js';
+import { resolveJobRetryConfig } from './mega-job.js';

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

@@ -0,0 +1,130 @@
+/**
+ * @typedef {Object} JobEntry - 등록된 잡 1건의 내부 메타데이터.
+ * @property {string} name - 잡 클래스명(= 등록 키).
+ * @property {typeof MegaJob} JobClass - 등록된 잡 클래스.
+ * @property {MegaJob} instance - run 호출 대상 인스턴스.
+ * @property {string} subject - NATS subject.
+ * @property {string} busAlias - bus 별명(`ctx.bus(alias)`).
+ * @property {{ stop: () => Promise<void> }|null} handle - start() 가 만든 consume 핸들(미 start 면 null).
+ */
+/**
+ * MegaJob 소비 워커 런타임. 잡 클래스를 등록하고 `start()` 로 소비를 시작, `stop()` 으로 graceful 중단한다.
+ *
+ * @example
+ * const worker = new MegaJobWorker({ ctx })   // ctx.bus(alias).native 로 nc 해석
+ * worker.on('dlq', (e) => log.error(e, 'job moved to DLQ'))
+ * worker.register(SendEmailJob).register(ResizeImageJob)
+ * await worker.start()
+ * MegaShutdown.register('worker', async () => { await worker.stop() })   // graceful shutdown 통합
+ */
+export class MegaJobWorker extends EventEmitter<any> {
+    /**
+     * @param {object} args
+     * @param {Record<string, any>} args.ctx - 실행 컨텍스트. **반드시 `ctx.bus(alias)`(함수)** 가 있어야
+     *   하며(잡 bus 별명 해석), run(payload, ctx) 에도 그대로 전달된다.
+     * @param {Partial<Omit<import('./mega-job-queue.js').MegaJobQueueOptions, 'nc'>>} [args.queueOptions]
+     *   - MegaJobQueue 옵션(`ackWaitMs`/`maxDeliver`/`heartbeatMs`/`streamPrefix`/`dlqMaxAgeMs`/`dlqMaxBytes`).
+     *   `nc` 는 워커가 배선하므로 제외. DLQ 한도(`dlqMaxAgeMs` 디폴트 7일)는 그대로 큐로 전달된다(ADR-134).
+     * @throws {TypeError} ctx 또는 ctx.bus 가 없을 때(fail-fast — bus 해석 불가).
+     */
+    constructor({ ctx, queueOptions }?: {
+        ctx: Record<string, any>;
+        queueOptions?: Partial<Omit<import("./mega-job-queue.js").MegaJobQueueOptions, "nc">>;
+    });
+    /** @param {'dispatch'|'start'|'done'|'retry'|'fail'|'dlq'} event @param {(payload: any) => void} listener @returns {this} */
+    on(event: "dispatch" | "start" | "done" | "retry" | "fail" | "dlq", listener: (payload: any) => void): this;
+    /** @param {'dispatch'|'start'|'done'|'retry'|'fail'|'dlq'} event @param {(payload: any) => void} listener @returns {this} */
+    off(event: "dispatch" | "start" | "done" | "retry" | "fail" | "dlq", listener: (payload: any) => void): this;
+    /** @param {'dispatch'|'start'|'done'|'retry'|'fail'|'dlq'} event @param {(payload: any) => void} listener @returns {this} */
+    once(event: "dispatch" | "start" | "done" | "retry" | "fail" | "dlq", listener: (payload: any) => void): this;
+    /** @param {'dispatch'|'start'|'done'|'retry'|'fail'|'dlq'} event @param {(payload: any) => void} listener @returns {this} */
+    addListener(event: "dispatch" | "start" | "done" | "retry" | "fail" | "dlq", listener: (payload: any) => void): this;
+    /** @param {'dispatch'|'start'|'done'|'retry'|'fail'|'dlq'} event @param {(payload: any) => void} listener @returns {this} */
+    removeListener(event: "dispatch" | "start" | "done" | "retry" | "fail" | "dlq", listener: (payload: any) => void): this;
+    /** @param {'dispatch'|'start'|'done'|'retry'|'fail'|'dlq'} event @param {(payload: any) => void} listener @returns {this} */
+    prependListener(event: "dispatch" | "start" | "done" | "retry" | "fail" | "dlq", listener: (payload: any) => void): this;
+    /** @param {'dispatch'|'start'|'done'|'retry'|'fail'|'dlq'} event @param {(payload: any) => void} listener @returns {this} */
+    prependOnceListener(event: "dispatch" | "start" | "done" | "retry" | "fail" | "dlq", listener: (payload: any) => void): this;
+    /**
+     * 잡 클래스를 등록한다(아직 소비 안 함 — {@link MegaJobWorker#start} 가 consume 을 건다). subject·bus 를
+     * 즉시 검증해 잘못된 등록을 부팅 시점에 드러낸다(fail-fast — MegaScheduler.register 패턴).
+     *
+     * @param {typeof MegaJob} JobClass - `MegaJob` 를 상속한 클래스.
+     * @returns {this} 체이닝용.
+     * @throws {TypeError} MegaJob 서브클래스가 아니거나 subject 가 비었을 때.
+     * @throws {Error} 이름 중복일 때.
+     * @throws {MegaConfigError} `static bus` 가 비었거나 미선언 별명일 때.
+     */
+    register(JobClass: typeof MegaJob): this;
+    /**
+     * 등록된 모든 잡의 소비를 시작한다(각 잡의 bus 큐로 `consume`). 이미 start 된 잡은 건너뛴다. 멱등.
+     * @returns {Promise<this>}
+     */
+    start(): Promise<this>;
+    /**
+     * 모든 잡 소비를 graceful 중단한다(consume 핸들 stop — 진행 중 처리는 마무리까지 대기). graceful
+     * shutdown 필수(`MegaShutdown.register('worker', () => worker.stop())`). 한 잡의 stop 실패가 나머지
+     * 정리를 막지 않도록 allSettled 로 모은다(방어). 단, 하부 `MegaJobQueue` 의 consume 핸들 `stop()` 은
+     * `ConsumerMessages.close()` 가 reject 하지 않는 설계라(nats 2.29: drain 오류를 `Promise<void|Error>` 로
+     * resolve) close 에러를 **큐 이벤트가 아니라 console(stderr)로 표면화**한다(L-3). 즉 allSettled 의
+     * rejected 슬롯은 정상 경로에선 비고, 방어적 안전망으로만 둔다.
+     * @returns {Promise<this>}
+     */
+    stop(): Promise<this>;
+    /**
+     * 잡을 큐에 넣는다(편의 위임 — producer 측). 워커가 해당 bus 큐를 통해 enqueue 한다.
+     * @param {typeof MegaJob} JobClass @param {any} payload
+     * @returns {Promise<{ seq: number, stream: string, duplicate: boolean }>}
+     */
+    enqueue(JobClass: typeof MegaJob, payload: any): Promise<{
+        seq: number;
+        stream: string;
+        duplicate: boolean;
+    }>;
+    /**
+     * 등록된 잡 메타데이터 목록. 모니터링/CLI 용.
+     * @returns {Array<{ name: string, subject: string, bus: string, consuming: boolean }>}
+     */
+    list(): Array<{
+        name: string;
+        subject: string;
+        bus: string;
+        consuming: boolean;
+    }>;
+    /** @returns {boolean} start() 된 상태면 true. */
+    get isStarted(): boolean;
+    #private;
+}
+/**
+ * - 등록된 잡 1건의 내부 메타데이터.
+ */
+export type JobEntry = {
+    /**
+     * - 잡 클래스명(= 등록 키).
+     */
+    name: string;
+    /**
+     * - 등록된 잡 클래스.
+     */
+    JobClass: typeof MegaJob;
+    /**
+     * - run 호출 대상 인스턴스.
+     */
+    instance: MegaJob;
+    /**
+     * - NATS subject.
+     */
+    subject: string;
+    /**
+     * - bus 별명(`ctx.bus(alias)`).
+     */
+    busAlias: string;
+    /**
+     * - start() 가 만든 consume 핸들(미 start 면 null).
+     */
+    handle: {
+        stop: () => Promise<void>;
+    } | null;
+};
+import { EventEmitter } from 'node:events';
+import { MegaJob } from './mega-job.js';

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

@@ -0,0 +1,138 @@
+/**
+ * 잡 클래스의 `static retries`/`static backoff` 를 {@link import('./mega-retry.js').MegaRetryOptions}
+ * 형식으로 매핑한다(03-api-spec 필드 → p-retry 옵션). 미지정 필드는 OQ-012 디폴트로 채운다.
+ *
+ * @param {typeof MegaJob} JobClass - 잡 클래스.
+ * @returns {{ retries: number, minTimeout: number, maxTimeout: number, factor: number, jitter: boolean }}
+ * @throws {TypeError} retries 가 음수/비정수이거나 backoff 형식이 무효일 때(fail-fast).
+ */
+export function resolveJobRetryConfig(JobClass: typeof MegaJob): {
+    retries: number;
+    minTimeout: number;
+    maxTimeout: number;
+    factor: number;
+    jitter: boolean;
+};
+/**
+ * 잡 클래스의 `static timeoutMs` 를 검증해 반환한다. 미지정(undefined/null)이면 `defaultMs`(큐 디폴트),
+ * `0` = 무제한. 음수/비정수는 운영 실수라 fail-fast(silent 보정 금지).
+ *
+ * @param {typeof MegaJob} JobClass - 잡 클래스.
+ * @param {number} defaultMs - 큐 레벨 디폴트(ms, 0 = 무제한).
+ * @returns {number} 적용할 타임아웃(ms). 0 = 무제한.
+ * @throws {TypeError} timeoutMs 가 0 이상 정수가 아닐 때.
+ */
+export function resolveJobRunTimeoutMs(JobClass: typeof MegaJob, defaultMs: number): number;
+/**
+ * MegaJob — NATS JetStream 기반 영속 잡 베이스 클래스 (ADR-119).
+ *
+ * 03-api-spec §6 의 "클래스 + static 설정" 패턴(MegaSchedule/MegaWorker 와 동형). 서브클래스가
+ * static 설정과 `async run(payload, ctx)` 를 정의하면, 실행 런타임 {@link MegaJobQueue}(JetStream
+ * wrapper)가 enqueue/consume·재시도·DLQ 를 담당한다.
+ *
+ * # 왜 JetStream 인가 (중학생용)
+ *   보통 메시지(core NATS)는 받을 사람이 그 순간 없으면 사라진다(at-most-once). 잡은 "꼭 한 번은
+ *   처리돼야" 하므로, 서버에 **저장(persist)** 해두고 워커가 가져가 처리한 뒤 "처리 완료(ack)" 를
+ *   보내야 지워지는 큐가 필요하다 — 그게 JetStream 의 **workqueue** 스트림이다. 여러 워커가 같은 큐를
+ *   봐도 메시지 1건은 **딱 한 워커**에게만 간다(분산 중복방지 = OQ-012 의 leader election 을 큐가 대신).
+ *
+ * # 재시도 → DLQ (MegaRetry 재사용)
+ *   `run()` 이 실패하면 {@link MegaJobQueue} 가 `MegaRetry`(p-retry)로 `static retries`·
+ *   `static backoff` 설정만큼 **인프로세스 지수 백오프 재시도**한다. 그래도 모두 실패하면 메시지를
+ *   **DLQ(Dead Letter Queue) subject `<subject>.dlq`** 로 보내 따로 보관한다(원인 분석·재처리용).
+ *
+ * # 설정 필드 (03-api-spec §6 정본)
+ *   - `static subject`     : 잡 NATS subject(필수). 워크 스트림이 이 subject 를 저장한다.
+ *   - `static bus`         : bus 별명(`ctx.bus(alias)` → MegaNatsAdapter). 워커 배선이 사용.
+ *   - `static concurrency` : 동시에 처리할 메시지 수(consumer `max_ack_pending`). 기본 1(순차·안전).
+ *   - `static retries`     : run 실패 시 **추가** 재시도 횟수(첫 시도 제외). 기본 3.
+ *   - `static backoff`     : `{ type:'exponential', initial, max }`. p-retry 로 매핑(factor=2, jitter=on).
+ *   - `static timeoutMs`   : run 전체(재시도 포함) 상한(ms). 미지정 시 큐 디폴트, `0` = 무제한.
+ *
+ * @module lib/mega-job
+ * @see ADR-119, ADR-028 (잡·스케줄러·워커 3종 분리), ADR-029 (라이브러리 래핑)
+ */
+/**
+ * 잡 백오프 설정. 03-api-spec §6 의 `static backoff` 형식. `type` 은 현재 `'exponential'` 만 지원한다
+ * (미지원 type 은 {@link resolveJobRetryConfig} 에서 throw — 추측 진행 금지).
+ *
+ * @typedef {Object} MegaJobBackoff
+ * @property {string} type - 백오프 종류. **현재 `'exponential'` 만 지원**(미지원 type 은
+ *   {@link resolveJobRetryConfig} 가 런타임 throw — 타입은 서브클래스 리터럴 오버라이드 편의를 위해
+ *   넓게 두고 검증은 런타임이 담당).
+ * @property {number} initial - 첫 재시도 지연(ms) = p-retry `minTimeout`.
+ * @property {number} max - 재시도 지연 상한(ms) = p-retry `maxTimeout`.
+ */
+/**
+ * 잡 큐 실패·재시도·DLQ 기본값(OQ-012 결정, ADR-119). p-retry(MegaRetry) 정합 디폴트:
+ * 추가 재시도 3회, 지수 factor 2, 첫 지연 1s, 상한 30s, jitter on(thundering herd 완화).
+ * @type {{ retries: 3, backoff: MegaJobBackoff }}
+ */
+export const JOB_RETRY_DEFAULTS: {
+    retries: 3;
+    backoff: MegaJobBackoff;
+};
+/**
+ * NATS JetStream 기반 영속 잡 베이스 클래스. 서브클래스가 static 설정과 `run(payload, ctx)` 를 정의한다.
+ *
+ * @example
+ * export class SendEmailJob extends MegaJob {
+ *   static subject = 'send-email'
+ *   static bus = 'jobs'
+ *   static concurrency = 5
+ *   static retries = 3
+ *   static backoff = { type: 'exponential', initial: 1000, max: 30_000 }
+ *   async run(payload, ctx) {
+ *     await ctx.cache('main').set(`sent:${payload.id}`, '1')
+ *   }
+ * }
+ */
+export class MegaJob {
+    /** @type {string|undefined} 잡 NATS subject(필수 — 미정의 시 큐 등록에서 throw). */
+    static subject: string | undefined;
+    /** @type {string|undefined} bus 별명(`ctx.bus(alias)`). 워커 배선이 nc 해석에 사용. */
+    static bus: string | undefined;
+    /** @type {number} 동시 처리 메시지 수(consumer max_ack_pending). 기본 1(순차·안전). */
+    static concurrency: number;
+    /** @type {number} run 실패 시 **추가** 재시도 횟수(첫 시도 제외). 기본 3(OQ-012). */
+    static retries: number;
+    /** @type {MegaJobBackoff} 지수 백오프 설정. 기본 { exponential, 1s, 30s }(OQ-012). */
+    static backoff: MegaJobBackoff;
+    /**
+     * @type {number|undefined} run 전체(재시도 포함) 실행 상한(ms). 초과 시 큐가 잡을 실패로 판정해 DLQ 로
+     *   보낸다 — 행(hang)된 run 이 `working()` lease 를 영원히 갱신하며 메시지를 영구 점유하는 것을 막는다.
+     *   미지정 시 {@link import('./mega-job-queue.js').MegaJobQueue} 의 `runTimeoutMs`(기본 30분), `0` = 무제한.
+     *   ⚠️ 타임아웃돼도 진행 중이던 run 은 JS 특성상 중단되지 않는다(백그라운드 계속) — run 은 멱등하게
+     *   설계해야 한다(at-least-once, 모듈 docstring).
+     */
+    static timeoutMs: number | undefined;
+    /**
+     * 메시지 1건마다 실행되는 본문. 서브클래스가 **반드시** 구현한다. throw 하면 {@link MegaJobQueue}
+     * 가 재시도하고, 재시도 소진 시 DLQ 로 보낸다 — 그러므로 비치명/일시 오류는 그냥 throw 하면 된다.
+     * @param {any} _payload - enqueue 된 잡 페이로드(JSON 디코드된 값).
+     * @param {Record<string, any>} _ctx - 실행 컨텍스트(`db/cache/bus/lock` 접근자 등).
+     * @returns {Promise<any>}
+     * @throws {Error} 서브클래스가 구현하지 않으면.
+     */
+    run(_payload: any, _ctx: Record<string, any>): Promise<any>;
+}
+/**
+ * 잡 백오프 설정. 03-api-spec §6 의 `static backoff` 형식. `type` 은 현재 `'exponential'` 만 지원한다
+ * (미지원 type 은 {@link resolveJobRetryConfig} 에서 throw — 추측 진행 금지).
+ */
+export type MegaJobBackoff = {
+    /**
+     * - 백오프 종류. **현재 `'exponential'` 만 지원**(미지원 type 은
+     * {@link resolveJobRetryConfig} 가 런타임 throw — 타입은 서브클래스 리터럴 오버라이드 편의를 위해
+     * 넓게 두고 검증은 런타임이 담당).
+     */
+    type: string;
+    /**
+     * - 첫 재시도 지연(ms) = p-retry `minTimeout`.
+     */
+    initial: number;
+    /**
+     * - 재시도 지연 상한(ms) = p-retry `maxTimeout`.
+     */
+    max: number;
+};

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

@@ -0,0 +1,45 @@
+/**
+ * `logger` config 의 sink 배열을 pino transport target 배열로 변환한다(순수 — 테스트 가능).
+ *
+ * @param {Array<Record<string, any>>} sinks - `[{ type:'console'|'file'|'telegram', ... }]`.
+ * @param {string} level - 전역 레벨(sink 가 자기 level 미지정 시 사용).
+ * @returns {Array<{ target: string, level: string, options: Record<string, any> }>}
+ */
+export function buildTargets(sinks: Array<Record<string, any>>, level: string): Array<{
+    target: string;
+    level: string;
+    options: Record<string, any>;
+}>;
+/**
+ * `logger` config → pino 옵션(또는 비활성 시 `null`). Fastify `logger` 또는 `pino()` 에 그대로 전달 가능.
+ *
+ * @param {unknown} config - `MegaLoggerConfig`(`{ level, sinks, redact? }`).
+ * @returns {{ level: string, mixin: Function, redact: { paths: string[] }, transport: { targets: any[] } } | null}
+ */
+export function buildLoggerOptions(config: unknown): {
+    level: string;
+    mixin: Function;
+    redact: {
+        paths: string[];
+    };
+    transport: {
+        targets: any[];
+    };
+} | null;
+/**
+ * `logger` config 로 pino 인스턴스를 만든다(비활성이면 `null`). bootApp 이 한 번 만들어 모든 앱이 공유한다
+ * (worker thread·파일 핸들 1벌). Fastify 는 인스턴스를 받으면 요청별 child(reqId 바인딩)를 만든다.
+ *
+ * @param {unknown} config - `MegaLoggerConfig`.
+ * @returns {import('pino').Logger | null}
+ */
+export function buildLogger(config: unknown): import("pino").Logger | null;
+/** sink 디폴트 — 텔레그램은 warn 이상(ADR-023). */
+export const TELEGRAM_DEFAULT_LEVEL: "warn";
+/**
+ * 기본 시크릿 redact 경로(ADR-023, H2 보안). 사용자가 `logger.redact` 를 지정하지 않아도 **항상** 적용해
+ * 토큰·비밀번호·인증 헤더가 stdout/파일/텔레그램(외부 sink)으로 평문 유출되는 것을 막는다(CLAUDE.md P5).
+ * pino(fast-redact) 경로 문법으로 부팅 시 1회 검증됨(leading wildcard `*.x` 포함). 사용자 redact 는 병합된다.
+ * @type {ReadonlyArray<string>}
+ */
+export const DEFAULT_REDACT_PATHS: ReadonlyArray<string>;