mega-framework 0.1.0

package/src/lib/mega-job-worker.js

@@ -0,0 +1,295 @@
+// @ts-check
+/**
+ * MegaJobWorker — MegaJob 들을 NATS JetStream 에서 **소비**하는 잡 워커 런타임 (ADR-120).
+ *
+ * {@link MegaScheduler} 가 {@link import('./mega-schedule.js').MegaSchedule} 의 런타임이듯,
+ * `MegaJobWorker` 는 {@link import('./mega-job.js').MegaJob} 의 **소비 런타임**이다. 등록된 잡 클래스마다
+ * bus 별명을 풀어 {@link MegaJobQueue} 로 `consume()` 을 구동하고, 프로세스 graceful shutdown 시 모든
+ * 소비를 멈춘다(`stop()`).
+ *
+ * # ⚠️ 정본 `MegaWorker`(CPU worker_threads 풀)와 다른 추상 (ADR-120)
+ *   03-api-spec §6 의 `class MegaWorker` 는 **CPU-heavy 계산 격리용 worker_threads 풀**
+ *   (`ctx.workers.<name>.run(task)`, 명시 호출)이다. 본 클래스는 그것과 **별개**로, NATS 잡을 소비하는
+ *   워커 프로세스 런타임이다(02-architecture §5-2 의 `mega worker` 명령이 "NATS subscribe → MegaJob 실행"
+ *   이라 한 그 역할). 두 개념을 같은 이름에 욱여넣지 않으려고 `MegaJobWorker` 로 분리했다(ADR-120).
+ *
+ * # concurrency 모델 — Promise concurrency (worker_threads 아님, ADR-120)
+ *   잡은 대부분 IO-bound(DB/HTTP/큐)이고, 동시 처리 상한은 이미 두 겹으로 걸린다: (1) NATS workqueue
+ *   consumer 의 `max_ack_pending = static concurrency`(서버측 in-flight 제한), (2) `MegaJobQueue.consume`
+ *   의 인프로세스 Promise 동시성 상한. 따라서 별도 thread/process 풀 없이 **같은 이벤트루프의 Promise
+ *   동시성**으로 충분하다. CPU-bound 잡이 생기면 정본 `MegaWorker`(worker_threads) 후속 Step 으로 분리한다.
+ *
+ * # bus 배선 — 별명 → NatsConnection
+ *   `MegaJobQueue` 는 연결된 `NatsConnection` 을 직접 받는다(별명 해석 안 함). 그 별명→nc
+ *   배선이 바로 본 런타임의 역할이다: `static bus` 별명을 `ctx.bus(alias).native` 로 풀어 nc 를 얻고, 같은
+ *   bus 의 여러 잡은 **하나의 MegaJobQueue 인스턴스를 공유**한다(bus 별명당 1개).
+ *
+ * # logger 미주입, 이벤트로 노출 (형제 클래스와 동일)
+ *   순수 런타임이라 logger 를 모른다. 하부 {@link MegaJobQueue} 의 이벤트(`dispatch`/`start`/`done`/
+ *   `retry`/`fail`/`dlq`)를 **그대로 재방출(forward)** 해, 소비자가 워커 1곳만 구독하면 모든 잡 큐의 길목을
+ *   관측할 수 있다. 타이머·콜백 경로라 `fail`/`dlq` 구독이 사실상 필수다.
+ *
+ * @module lib/mega-job-worker
+ * @see ADR-120, ADR-119 (MegaJob/MegaJobQueue), ADR-028 (3종 분리), ADR-117 (Step 분할)
+ */
+import { EventEmitter } from 'node:events'
+import { MegaConfigError } from '../errors/config-error.js'
+import { MegaJob } from './mega-job.js'
+import { MegaJobQueue } from './mega-job-queue.js'
+
+/** 워커가 재방출하는 큐 이벤트 화이트리스트(MegaJobQueue 와 동일 — 오타 차단). */
+const KNOWN_EVENTS = Object.freeze(['dispatch', 'start', 'done', 'retry', 'fail', 'dlq'])
+
+/**
+ * @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 {
+  /** @type {Record<string, any>} bus 별명 해석용 컨텍스트(+ run 에 전달). */ #ctx
+  /** @type {Partial<Omit<import('./mega-job-queue.js').MegaJobQueueOptions, 'nc'>>} 큐 옵션(nc 제외). */ #queueOptions
+  /** @type {Map<string, JobEntry>} 등록 잡(이름 → 메타 + consume 핸들). */ #jobs = new Map()
+  /** @type {Map<string, MegaJobQueue>} bus 별명 → 공유 MegaJobQueue 인스턴스. */ #queues = new Map()
+  /** @type {boolean} start() 후 stop() 전까지 true. */ #started = false
+
+  /**
+   * @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 = {} } = /** @type {any} */ ({})) {
+    super()
+    if (!ctx || typeof ctx.bus !== 'function') {
+      throw new TypeError('MegaJobWorker({ ctx }) — ctx with a bus(alias) accessor is required (to resolve job bus → NatsConnection).')
+    }
+    this.#ctx = ctx
+    this.#queueOptions = queueOptions
+  }
+
+  // ── 이벤트 화이트리스트(형제 클래스와 동일 정책) ──────────────────────
+
+  /**
+   * 이벤트명 화이트리스트 검증. 모든 구독/해제 오버라이드가 공유.
+   * @param {string} method @param {string} event @returns {void}
+   * @throws {RangeError} 알 수 없는 이벤트명일 때.
+   */
+  #assertKnownEvent(method, event) {
+    if (!KNOWN_EVENTS.includes(event)) {
+      throw new RangeError(
+        `MegaJobWorker.${method}('${event}', ...) — unknown event. Known: ${KNOWN_EVENTS.join(', ')}.`,
+      )
+    }
+  }
+
+  /** @param {'dispatch'|'start'|'done'|'retry'|'fail'|'dlq'} event @param {(payload: any) => void} listener @returns {this} */
+  on(event, listener) {
+    this.#assertKnownEvent('on', event)
+    return super.on(event, listener)
+  }
+
+  /** @param {'dispatch'|'start'|'done'|'retry'|'fail'|'dlq'} event @param {(payload: any) => void} listener @returns {this} */
+  off(event, listener) {
+    this.#assertKnownEvent('off', event)
+    return super.off(event, listener)
+  }
+
+  /** @param {'dispatch'|'start'|'done'|'retry'|'fail'|'dlq'} event @param {(payload: any) => void} listener @returns {this} */
+  once(event, listener) {
+    this.#assertKnownEvent('once', event)
+    return super.once(event, listener)
+  }
+
+  /** @param {'dispatch'|'start'|'done'|'retry'|'fail'|'dlq'} event @param {(payload: any) => void} listener @returns {this} */
+  addListener(event, listener) {
+    this.#assertKnownEvent('addListener', event)
+    return super.addListener(event, listener)
+  }
+
+  /** @param {'dispatch'|'start'|'done'|'retry'|'fail'|'dlq'} event @param {(payload: any) => void} listener @returns {this} */
+  removeListener(event, listener) {
+    this.#assertKnownEvent('removeListener', event)
+    return super.removeListener(event, listener)
+  }
+
+  /** @param {'dispatch'|'start'|'done'|'retry'|'fail'|'dlq'} event @param {(payload: any) => void} listener @returns {this} */
+  prependListener(event, listener) {
+    this.#assertKnownEvent('prependListener', event)
+    return super.prependListener(event, listener)
+  }
+
+  /** @param {'dispatch'|'start'|'done'|'retry'|'fail'|'dlq'} event @param {(payload: any) => void} listener @returns {this} */
+  prependOnceListener(event, listener) {
+    this.#assertKnownEvent('prependOnceListener', event)
+    return super.prependOnceListener(event, listener)
+  }
+
+  // ── 등록 / 라이프사이클 ────────────────────────────────────────────────────
+
+  /**
+   * 잡 클래스를 등록한다(아직 소비 안 함 — {@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) {
+    if (typeof JobClass !== 'function' || !(JobClass.prototype instanceof MegaJob)) {
+      throw new TypeError('MegaJobWorker.register(C) — C must be a subclass of MegaJob.')
+    }
+    const name = JobClass.name
+    if (this.#jobs.has(name)) {
+      throw new Error(`MegaJobWorker.register: job '${name}' is already registered.`)
+    }
+    // subject 검증은 MegaJobQueue 가 enqueue/consume 시 #assertJobSubject 로 하지만, 등록 시점에 한 번 더
+    // 당겨 부팅 fail-fast. 비어있지 않은 문자열만 여기서 보고, 형식 상세는 큐가 책임진다.
+    const subject = JobClass.subject
+    if (typeof subject !== 'string' || subject.trim() === '') {
+      throw new TypeError(`MegaJobWorker.register('${name}') — static subject must be a non-empty string.`)
+    }
+    // bus 별명 — 미지정 시 잡 nc 를 풀 수 없으므로 fail-fast. 별명이 ctx 에 선언됐는지도 즉시 검증.
+    const busAlias = JobClass.bus
+    if (typeof busAlias !== 'string' || busAlias.trim() === '') {
+      throw new MegaConfigError(
+        'job.missing_bus',
+        `MegaJobWorker.register('${name}') — static bus must be a non-empty string (the ctx.bus(alias) name).`,
+        { details: { job: name } },
+      )
+    }
+    this.#assertBusAliasDeclared(name, busAlias)
+
+    const instance = new JobClass()
+    this.#jobs.set(name, { name, JobClass, instance, subject, busAlias, handle: null })
+    return this
+  }
+
+  /**
+   * bus 별명이 ctx 에 선언돼 있는지 부팅 시점에 검증한다(fail-fast — MegaScheduler.#assertLockAliasDeclared
+   * 패턴). `ctx.bus(alias)` 를 1회 호출해 미선언 별명이면 즉시 throw — 오타가 첫 소비 시점까지 숨지 않게.
+   * @param {string} name @param {string} alias @returns {void}
+   * @throws {MegaConfigError} 별명이 미선언일 때.
+   */
+  #assertBusAliasDeclared(name, alias) {
+    try {
+      this.#ctx.bus(alias) // 미선언 별명이면 ctx-builder 가 MegaConfigError throw — 부팅에서 잡는다.
+    } catch (e) {
+      const cause = e instanceof Error ? e : new Error(String(e))
+      throw new MegaConfigError(
+        'job.unknown_bus_alias',
+        `MegaJobWorker.register('${name}') — bus alias '${alias}' is not a declared bus adapter ` +
+          `(ctx.bus('${alias}') failed: ${cause.message}).`,
+        { details: { job: name, alias }, cause },
+      )
+    }
+  }
+
+  /**
+   * bus 별명에 대한 공유 {@link MegaJobQueue} 를 멱등 생성한다 — 같은 bus 의 여러 잡이 한 nc·한 큐를 공유.
+   * 큐 이벤트를 워커로 재방출(forward)해 소비자가 워커 1곳만 구독하면 되게 한다.
+   * @param {string} busAlias @returns {MegaJobQueue}
+   */
+  #queueFor(busAlias) {
+    const existing = this.#queues.get(busAlias)
+    if (existing) return existing
+    const adapter = this.#ctx.bus(busAlias) // register 에서 이미 검증 — 정상 경로에선 throw 안 함.
+    const nc = adapter.native // MegaBusAdapter.native = 연결된 NatsConnection(ADR-009).
+    const queue = new MegaJobQueue({ nc, ...this.#queueOptions })
+    // 큐 길목 이벤트를 워커로 그대로 재방출 — 소비자는 worker.on(...) 한 곳만 구독.
+    for (const event of KNOWN_EVENTS) {
+      queue.on(/** @type {any} */ (event), (payload) => this.emit(event, payload))
+    }
+    this.#queues.set(busAlias, queue)
+    return queue
+  }
+
+  /**
+   * 등록된 모든 잡의 소비를 시작한다(각 잡의 bus 큐로 `consume`). 이미 start 된 잡은 건너뛴다. 멱등.
+   * @returns {Promise<this>}
+   */
+  async start() {
+    for (const job of this.#jobs.values()) {
+      if (job.handle !== null) continue // 이미 소비 중.
+      const queue = this.#queueFor(job.busAlias)
+      job.handle = await queue.consume(job.JobClass, job.instance, this.#ctx)
+    }
+    this.#started = true
+    return 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>}
+   */
+  async stop() {
+    const stops = []
+    for (const job of this.#jobs.values()) {
+      if (job.handle === null) continue
+      stops.push(job.handle.stop())
+      job.handle = null
+    }
+    await Promise.allSettled(stops)
+    this.#started = false
+    return this
+  }
+
+  /**
+   * 잡을 큐에 넣는다(편의 위임 — producer 측). 워커가 해당 bus 큐를 통해 enqueue 한다.
+   * @param {typeof MegaJob} JobClass @param {any} payload
+   * @returns {Promise<{ seq: number, stream: string, duplicate: boolean }>}
+   */
+  async enqueue(JobClass, payload) {
+    const busAlias = JobClass.bus
+    if (typeof busAlias !== 'string' || busAlias.trim() === '') {
+      throw new MegaConfigError(
+        'job.missing_bus',
+        `MegaJobWorker.enqueue('${JobClass?.name}') — static bus must be a non-empty string.`,
+        { details: { job: JobClass?.name } },
+      )
+    }
+    return this.#queueFor(busAlias).enqueue(JobClass, payload)
+  }
+
+  /**
+   * 등록된 잡 메타데이터 목록. 모니터링/CLI 용.
+   * @returns {Array<{ name: string, subject: string, bus: string, consuming: boolean }>}
+   */
+  list() {
+    return [...this.#jobs.values()].map((j) => ({
+      name: j.name,
+      subject: j.subject,
+      bus: j.busAlias,
+      consuming: j.handle !== null,
+    }))
+  }
+
+  /** @returns {boolean} start() 된 상태면 true. */
+  get isStarted() {
+    return this.#started
+  }
+}

package/src/lib/mega-job.js

@@ -0,0 +1,140 @@
+// @ts-check
+/**
+ * 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).
+ *
+ * @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 = Object.freeze({
+  retries: 3,
+  backoff: Object.freeze({ type: 'exponential', initial: 1000, max: 30_000 }),
+})
+
+/**
+ * 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 = undefined
+
+  /** @type {string|undefined} bus 별명(`ctx.bus(alias)`). 워커 배선이 nc 해석에 사용. */
+  static bus = undefined
+
+  /** @type {number} 동시 처리 메시지 수(consumer max_ack_pending). 기본 1(순차·안전). */
+  static concurrency = 1
+
+  /** @type {number} run 실패 시 **추가** 재시도 횟수(첫 시도 제외). 기본 3(OQ-012). */
+  static retries = JOB_RETRY_DEFAULTS.retries
+
+  /** @type {MegaJobBackoff} 지수 백오프 설정. 기본 { exponential, 1s, 30s }(OQ-012). */
+  static backoff = JOB_RETRY_DEFAULTS.backoff
+
+  /**
+   * 메시지 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} 서브클래스가 구현하지 않으면.
+   */
+  async run(_payload, _ctx) {
+    throw new Error(
+      `${this.constructor.name}: MegaJob subclass must implement async run(payload, ctx).`,
+    )
+  }
+}
+
+/**
+ * 잡 클래스의 `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) {
+  const retries = JobClass.retries ?? JOB_RETRY_DEFAULTS.retries
+  if (typeof retries !== 'number' || !Number.isInteger(retries) || retries < 0) {
+    throw new TypeError(
+      `MegaJob '${JobClass.name}': static retries must be a non-negative integer. Got: ${retries}.`,
+    )
+  }
+  // null/undefined 는 디폴트로 대체(?? ) — 이후 backoff 는 항상 값이 있다. 비-객체(문자열·숫자 등)만 거른다.
+  const backoff = JobClass.backoff ?? JOB_RETRY_DEFAULTS.backoff
+  if (typeof backoff !== 'object') {
+    throw new TypeError(
+      `MegaJob '${JobClass.name}': static backoff must be an object { type, initial, max }.`,
+    )
+  }
+  // 현재 exponential 만 지원 — 미지원 type 을 조용히 다른 백오프로 해석하지 않는다.
+  if (backoff.type !== 'exponential') {
+    throw new TypeError(
+      `MegaJob '${JobClass.name}': static backoff.type '${backoff.type}' is not supported (only 'exponential').`,
+    )
+  }
+  const { initial, max } = backoff
+  if (typeof initial !== 'number' || initial <= 0) {
+    throw new TypeError(
+      `MegaJob '${JobClass.name}': static backoff.initial must be a positive number (ms). Got: ${initial}.`,
+    )
+  }
+  if (typeof max !== 'number' || max < initial) {
+    throw new TypeError(
+      `MegaJob '${JobClass.name}': static backoff.max must be a number >= initial (${initial}). Got: ${max}.`,
+    )
+  }
+  // factor=2(exponential), jitter=on — OQ-012 정합. MegaRetry 가 첫 시도 즉시 + 이후 지수 백오프.
+  return { retries, minTimeout: initial, maxTimeout: max, factor: 2, jitter: true }
+}

package/src/lib/mega-logger.js

@@ -0,0 +1,128 @@
+// @ts-check
+/**
+ * MegaLogger — pino + multi-sink 통합 (ADR-023/141).
+ *
+ * # 무엇인가 (중학생용 설명)
+ *   서버가 무슨 일을 했는지 기록(로그)을 남기는 장치다. 검증된 라이브러리 `pino`(아주 빠른 JSON 로거) 위에,
+ *   `mega.config.js` 의 `logger` 설정대로 **여러 출력처(sink)** 를 동시에 연결한다:
+ *     - console (dev 는 보기 좋은 pretty, prod 는 JSON 한 줄)
+ *     - file (날짜별 로테이션 + 오래된 파일 N개만 보관)
+ *     - telegram (warn 이상만, worker thread 로 비동기 전송 + 실패 시 재시도 — 메인 루프 안 막음)
+ *
+ * # 핵심 (ADR-023)
+ *   - **request_id 주입**: Fastify 가 `req.log` 에 `reqId` 를 자동 바인딩한다(요청별 상관).
+ *   - **trace_id 주입**: pino `mixin` = `MegaTracing.logMixin` → 활성 span 의 `trace_id`/`span_id` 자동 첨부(ADR-116).
+ *   - **시크릿 redact**: pino `redact` 로 `*.password`/`*.token`/`authorization` 등 마스킹(메인 스레드에서 적용 →
+ *     transport 가 받는 NDJSON 엔 이미 시크릿 없음).
+ *   - **worker thread 격리**: pino transport 는 worker thread 에서 돈다 — 무거운 IO(파일·텔레그램)가 이벤트루프 보호.
+ *
+ * # sink 확장 (ADR-027)
+ *   새 sink 는 `MegaLogSinkAdapter`(추상, src/adapters) 계약을 따르는 pino transport 모듈을 추가하면 된다
+ *   (텔레그램 sink 가 그 예 — `logger/telegram-transport.js`).
+ *
+ * @module lib/mega-logger
+ * @see ADR-023
+ * @see ADR-141
+ */
+import { fileURLToPath } from 'node:url'
+import pino from 'pino'
+import * as MegaTracing from './mega-tracing.js'
+
+/** 텔레그램 transport 모듈 절대경로(pino worker 가 path 로 로드). */
+const TELEGRAM_TRANSPORT = fileURLToPath(new URL('./logger/telegram-transport.js', import.meta.url))
+
+/** sink 디폴트 — 텔레그램은 warn 이상(ADR-023). */
+export const TELEGRAM_DEFAULT_LEVEL = 'warn'
+
+/**
+ * `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, level) {
+  /** @type {Array<{ target: string, level: string, options: Record<string, any> }>} */
+  const targets = []
+  for (const sink of sinks) {
+    if (!sink || typeof sink !== 'object') continue
+    const sinkLevel = typeof sink.level === 'string' ? sink.level : level
+    if (sink.type === 'console') {
+      if (sink.pretty) {
+        // dev pretty — pino-pretty 가 NDJSON 을 사람이 읽기 좋게. 시크릿은 이미 redact 됨.
+        targets.push({
+          target: 'pino-pretty',
+          level: sinkLevel,
+          options: { colorize: true, translateTime: 'SYS:standard', ignore: 'pid,hostname' },
+        })
+      } else {
+        // prod — stdout 으로 JSON 한 줄(destination 1 = stdout).
+        targets.push({ target: 'pino/file', level: sinkLevel, options: { destination: 1 } })
+      }
+    } else if (sink.type === 'file') {
+      // 날짜별 로테이션 + keep N — pino-roll(pino 팀 공식). frequency 'daily', limit.count = keep.
+      targets.push({
+        target: 'pino-roll',
+        level: sinkLevel,
+        options: {
+          file: sink.path,
+          frequency: sink.rotation === 'daily' || sink.rotation === undefined ? 'daily' : sink.rotation,
+          mkdir: true,
+          ...(Number.isInteger(sink.keep) && sink.keep > 0 ? { limit: { count: sink.keep } } : {}),
+        },
+      })
+    } else if (sink.type === 'telegram') {
+      // warn 이상만(디폴트) — worker thread + throttle + disk retry(telegram-transport.js).
+      targets.push({
+        target: TELEGRAM_TRANSPORT,
+        level: typeof sink.level === 'string' ? sink.level : TELEGRAM_DEFAULT_LEVEL,
+        options: {
+          botToken: sink.botToken,
+          chatId: sink.chatId,
+          ...(Number.isInteger(sink.throttleMax) ? { throttleMax: sink.throttleMax } : {}),
+          ...(Number.isInteger(sink.throttleWindowMs) ? { throttleWindowMs: sink.throttleWindowMs } : {}),
+          ...(typeof sink.retryDir === 'string' ? { retryDir: sink.retryDir } : {}),
+          ...(typeof sink.serviceName === 'string' ? { serviceName: sink.serviceName } : {}),
+        },
+      })
+    }
+    // 알 수 없는 type 은 조용히 무시하지 않고 — config-validator 가 부팅 시 막는 게 정석이나, 여기선
+    // 빌더라 미지원 type 을 건너뛴다(검증은 별도). 빈 결과면 buildLoggerOptions 가 null 반환.
+  }
+  return targets
+}
+
+/**
+ * `logger` config → pino 옵션(또는 비활성 시 `null`). Fastify `logger` 또는 `pino()` 에 그대로 전달 가능.
+ *
+ * @param {unknown} config - `MegaLoggerConfig`(`{ level, sinks, redact?, includeRequestId? }`).
+ * @returns {{ level: string, mixin: Function, redact?: string[], transport: { targets: any[] } } | null}
+ */
+export function buildLoggerOptions(config) {
+  if (!config || typeof config !== 'object') return null
+  const c = /** @type {Record<string, any>} */ (config)
+  if (!Array.isArray(c.sinks) || c.sinks.length === 0) return null
+  const level = typeof c.level === 'string' ? c.level : 'info'
+  const targets = buildTargets(c.sinks, level)
+  if (targets.length === 0) return null
+  return {
+    level,
+    // trace_id/span_id 자동 주입(ADR-116) — 활성 span 없으면 빈 객체(0 비용).
+    mixin: MegaTracing.logMixin,
+    ...(Array.isArray(c.redact) && c.redact.length > 0 ? { redact: c.redact } : {}),
+    transport: { targets },
+  }
+}
+
+/**
+ * `logger` config 로 pino 인스턴스를 만든다(비활성이면 `null`). bootApp 이 한 번 만들어 모든 앱이 공유한다
+ * (worker thread·파일 핸들 1벌). Fastify 는 인스턴스를 받으면 요청별 child(reqId 바인딩)를 만든다.
+ *
+ * @param {unknown} config - `MegaLoggerConfig`.
+ * @returns {import('pino').Logger | null}
+ */
+export function buildLogger(config) {
+  const options = buildLoggerOptions(config)
+  if (options === null) return null
+  return pino(/** @type {any} */ (options))
+}