mega-framework 0.1.0

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

@@ -0,0 +1,600 @@
+// @ts-check
+/**
+ * MegaJobQueue — NATS JetStream 기반 잡 큐 런타임 (ADR-119).
+ *
+ * {@link import('./mega-job.js').MegaJob} 정의를 받아 **영속 큐(enqueue)** · **처리(consume)** · **재시도** ·
+ * **DLQ 라우팅**을 담당한다. 시각/타이머가 croner 였던 MegaScheduler 처럼, 본 런타임은 **영속성·전달
+ * 보장·분산 중복방지를 NATS JetStream 에 위임**하고(ADR-029: 검증된 라이브러리 래핑), 재시도 백오프는
+ * `MegaRetry`(p-retry)를 재사용한다.
+ *
+ * # 분산 중복방지 = workqueue 스트림 (OQ-012 leader election 대체)
+ *   잡 subject 당 **retention=workqueue** 스트림을 만든다. workqueue 는 메시지 1건이 **딱 하나의
+ *   consumer** 에게만 전달되고 ack 시 삭제된다 — 여러 워커가 같은 durable consumer(같은 이름)를
+ *   공유하면 자동 load-balance 되고, 한 메시지를 두 워커가 동시에 처리하는 일이 없다. 즉 별도 leader
+ *   election 없이 큐 자체가 분산 중복방지를 보장한다(ADR-119, OQ-012 결정).
+ *
+ * # 재시도 → DLQ (인프로세스 MegaRetry + working() lease 유지)
+ *   메시지를 받으면 `MegaRetry.withRetry` 로 `run(payload, ctx)` 를 `static retries`·`static backoff`
+ *   만큼 **인프로세스 지수 백오프 재시도**한다. 재시도 동안 메시지를 계속 점유하므로, `ack_wait` 가
+ *   만료돼 JetStream 이 **중복 재전달**하지 않도록 주기적으로 `msg.working()`(ack 타이머 리셋)을 보낸다.
+ *   모든 재시도 소진 시 페이로드를 **DLQ subject `<subject>.dlq`**(별도 limits 스트림)로 발행하고 원본
+ *   메시지를 ack 한다. DLQ 발행이 실패하면 ack 하지 않고 `nak` 해 **잡을 잃지 않는다**(at-least-once).
+ *
+ * # DLQ 스트림 한도 (ADR-134 — 무한 적재 방지)
+ *   DLQ 는 `Limits` retention 스트림이라 NATS 디폴트로는 무한 적재된다(디스크 소진 위험). 그래서 DLQ
+ *   스트림에 **`max_age` 디폴트 7일**(`dlqMaxAgeMs`)을 걸어 오래된 실패 잡을 자동 만료시킨다. `dlqMaxBytes`
+ *   로 디스크 상한도 걸 수 있다. 스트림 생성은 멱등(이미 있으면 그대로 — 운영자가 NATS CLI 로 갱신)이라
+ *   **신규 스트림에만** 한도가 적용된다. 영구 보존이 필요하면 `dlqMaxAgeMs: 0`(=무제한)으로 끈다. 운영
+ *   가이드는 docs/INFRA.md §6.
+ *
+ * # ⚠️ ack_wait vs 인프로세스 재시도 (기록)
+ *   `static backoff.max` 가 크고 `retries` 가 많으면 한 메시지를 오래 점유한다. `working()` 하트비트가
+ *   lease 를 갱신하지만, **워커가 재시도 도중 죽으면** ack_wait 만료 후 다른 워커로 재전달된다(at-least-once
+ *   — run 은 멱등하게 설계해야 함). `max_deliver`(기본 5)는 워커 크래시 재전달의 backstop 이다.
+ *
+ * # 흐름 길목을 이벤트로 노출 (MegaScheduler/MegaCircuitBreaker 와 동일 정책)
+ *   순수 런타임이라 logger 를 모른다. 대신 길목을 이벤트로 노출한다:
+ *   `dispatch`(enqueue) · `start`(처리 시작) · `done`(성공 ack) · `retry`(재시도 1회 실패) ·
+ *   `fail`(최종 실패 — phase 로 단계 구분) · `dlq`(DLQ 라우팅). 소비자가 구독해 로그를 박는다.
+ *   타이머·콜백 경로라 호출자가 없으므로 `fail`/`dlq` 구독이 사실상 필수다.
+ *
+ * @module lib/mega-job-queue
+ * @see ADR-119, ADR-028 (3종 분리), ADR-112 (NATS 어댑터), ADR-029 (래핑)
+ */
+import { EventEmitter } from 'node:events'
+import { MegaConfigError } from '../errors/config-error.js'
+import { MegaJob, resolveJobRetryConfig } from './mega-job.js'
+import { withRetry } from './mega-retry.js'
+
+/** 잡 큐가 노출하는 이벤트 화이트리스트(오타 차단 + 문서화 — 형제 클래스와 동일 정책). */
+const KNOWN_EVENTS = Object.freeze([
+  'dispatch', // enqueue(잡 발행) — event.seq/stream
+  'start', // 메시지 처리 시작
+  'done', // 처리 성공 + ack — event.result
+  'retry', // 재시도 1회 실패(다음 시도 전) — event.attempt/retriesLeft/error
+  'fail', // 최종 실패 — event.phase('run'|'decode'|'dlq-publish'|'max-deliver'|'consume-loop')/error
+  'dlq', // DLQ 라우팅 완료 — event.dlqSubject
+])
+
+/** JetStream "stream/consumer not found" 에러 코드(실측 — nats 2.29, code '404'). */
+const NOT_FOUND_CODE = '404'
+
+/** DLQ 스트림 `max_age` 디폴트(ms) — 7일. 무한 적재 방지(ADR-134). `dlqMaxAgeMs: 0` 으로 끌 수 있다. */
+export const DEFAULT_DLQ_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000
+
+/**
+ * @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` 가
+ *   주 가드). 디스크 상한이 필요한 운영 환경에서만 지정.
+ */
+
+/**
+ * @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 {
+  /** @type {import('nats').NatsConnection} */ #nc
+  /** @type {number} */ #ackWaitMs
+  /** @type {number} */ #maxDeliver
+  /** @type {number} */ #heartbeatMs
+  /** @type {string} */ #streamPrefix
+  /** @type {number} DLQ max_age(ms). 0 = 무제한. */ #dlqMaxAgeMs
+  /** @type {number|undefined} DLQ max_bytes. undefined = 무제한. */ #dlqMaxBytes
+  /** @type {typeof import('nats')|null} 지연 로드된 nats 모듈(enum/codec/nanos). */ #nats = null
+  /** @type {import('nats').Codec<any>|null} */ #codec = null
+  /** @type {import('nats').JetStreamClient|null} */ #js = null
+  /** @type {import('nats').JetStreamManager|null} */ #jsm = null
+  /** @type {Promise<void>|null} ensureReady 멱등 가드. */ #readyPromise = null
+
+  /**
+   * @param {MegaJobQueueOptions} options
+   * @throws {TypeError} nc 가 JetStream 가능한 NatsConnection 이 아니면(fail-fast).
+   */
+  constructor({ nc, ackWaitMs = 30_000, maxDeliver = 5, heartbeatMs, streamPrefix = 'MEGA_JOBS', dlqMaxAgeMs = DEFAULT_DLQ_MAX_AGE_MS, dlqMaxBytes } = /** @type {any} */ ({})) {
+    super()
+    if (!nc || typeof nc.jetstream !== 'function' || typeof nc.jetstreamManager !== 'function') {
+      throw new TypeError(
+        'MegaJobQueue({ nc }) — nc must be a connected NatsConnection (jetstream()/jetstreamManager()).',
+      )
+    }
+    if (typeof ackWaitMs !== 'number' || ackWaitMs <= 0) {
+      throw new TypeError(`MegaJobQueue: ackWaitMs must be a positive number (ms). Got: ${ackWaitMs}.`)
+    }
+    if (typeof maxDeliver !== 'number' || !Number.isInteger(maxDeliver) || maxDeliver < 1) {
+      throw new TypeError(`MegaJobQueue: maxDeliver must be an integer >= 1. Got: ${maxDeliver}.`)
+    }
+    // dlqMaxAgeMs: 0 = 무제한(끔). 음수/비정수는 운영 실수라 fail-fast(silent 보정 X).
+    if (typeof dlqMaxAgeMs !== 'number' || !Number.isInteger(dlqMaxAgeMs) || dlqMaxAgeMs < 0) {
+      throw new TypeError(`MegaJobQueue: dlqMaxAgeMs must be an integer >= 0 (0 = unlimited). Got: ${dlqMaxAgeMs}.`)
+    }
+    if (dlqMaxBytes !== undefined && (typeof dlqMaxBytes !== 'number' || !Number.isInteger(dlqMaxBytes) || dlqMaxBytes < 1)) {
+      throw new TypeError(`MegaJobQueue: dlqMaxBytes must be an integer >= 1 when set. Got: ${dlqMaxBytes}.`)
+    }
+    this.#nc = nc
+    this.#ackWaitMs = ackWaitMs
+    this.#maxDeliver = maxDeliver
+    this.#heartbeatMs = heartbeatMs ?? Math.max(1000, Math.floor(ackWaitMs / 2))
+    this.#streamPrefix = streamPrefix
+    this.#dlqMaxAgeMs = dlqMaxAgeMs
+    this.#dlqMaxBytes = dlqMaxBytes
+  }
+
+  // ── 이벤트 화이트리스트(L-1 정책 — 형제 클래스와 동일) ────────────────────
+
+  /**
+   * 이벤트명 화이트리스트 검증. 모든 구독/해제 오버라이드가 공유.
+   * @param {string} method @param {string} event @returns {void}
+   * @throws {RangeError} 알 수 없는 이벤트명일 때.
+   */
+  #assertKnownEvent(method, event) {
+    if (!KNOWN_EVENTS.includes(event)) {
+      throw new RangeError(
+        `MegaJobQueue.${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)
+  }
+
+  // ── 초기화 ──────────────────────────────────────────────────────────────
+
+  /**
+   * JetStream client/manager·codec 을 지연 초기화한다(멱등 — 동시 호출도 1회만). nats 드라이버는
+   * 여기서 lazy import(어댑터 정합 — 잡 미사용 앱에 nats 로드 강제 안 함).
+   * @returns {Promise<void>}
+   */
+  async ensureReady() {
+    if (this.#readyPromise) return this.#readyPromise
+    this.#readyPromise = (async () => {
+      const nats = await import('nats')
+      this.#nats = nats
+      this.#codec = nats.JSONCodec()
+      this.#js = this.#nc.jetstream()
+      this.#jsm = await this.#nc.jetstreamManager()
+    })()
+    return this.#readyPromise
+  }
+
+  /**
+   * 잡 클래스 검증 — MegaJob 서브클래스 + 유효한 static subject(fail-fast).
+   *
+   * subject 는 단순 "비어있지 않은 문자열" 이 아니라 **NATS subject 규칙**을 따라야 한다(L-2): 와일드카드
+   * (`*`·`>`)·공백·빈 토큰을 허용하면 workqueue 필터가 다른 잡의 메시지까지 빨아들이거나 `<subject>.dlq`
+   * 와 overlap 해 **무한 재처리/유실** 풋건이 된다. 또 `<subject>.dlq` 를 DLQ 로 쓰므로 subject 가 이미
+   * `.dlq` 로 끝나면 다른 잡의 DLQ 와 충돌한다 — 모두 등록 시점에 막는다.
+   *
+   * @param {typeof MegaJob} JobClass @returns {string} subject.
+   * @throws {TypeError} 서브클래스가 아니거나 subject 가 무효(빈 값·와일드카드·공백·빈 토큰·`.dlq` 말미)일 때.
+   */
+  #assertJobSubject(JobClass) {
+    if (typeof JobClass !== 'function' || !(JobClass.prototype instanceof MegaJob)) {
+      throw new TypeError('MegaJobQueue: JobClass must be a subclass of MegaJob.')
+    }
+    const subject = JobClass.subject
+    if (typeof subject !== 'string' || subject.trim() === '') {
+      throw new TypeError(`MegaJobQueue: '${JobClass.name}' static subject must be a non-empty string.`)
+    }
+    // 토큰 문자셋만 허용 — 와일드카드(`*`·`>`)·공백·기타 특수문자 차단(L-2).
+    if (!/^[A-Za-z0-9._-]+$/.test(subject)) {
+      throw new TypeError(
+        `MegaJobQueue: '${JobClass.name}' static subject '${subject}' contains invalid characters ` +
+          `(only letters, digits, '.', '_', '-' allowed — no wildcards '*'/'>' or whitespace).`,
+      )
+    }
+    // 빈 토큰(선두/말미 점·연속 점)은 NATS 가 거부 — 우리도 동일하게 막는다.
+    if (subject.split('.').some((token) => token.length === 0)) {
+      throw new TypeError(
+        `MegaJobQueue: '${JobClass.name}' static subject '${subject}' has an empty token (no leading/trailing/double dots).`,
+      )
+    }
+    // `<subject>.dlq` 가 DLQ subject 라, subject 자체가 '.dlq' 로 끝나면 다른 잡의 DLQ 와 충돌한다.
+    if (subject.endsWith('.dlq')) {
+      throw new TypeError(
+        `MegaJobQueue: '${JobClass.name}' static subject '${subject}' must not end with '.dlq' (reserved for DLQ routing).`,
+      )
+    }
+    return subject
+  }
+
+  /**
+   * `static concurrency` 를 검증해 반환한다(fail-fast). **NATS 는 `max_ack_pending=0` 을 무제한으로
+   * 해석**하므로(consumer 설정 `max_ack_pending: concurrency`), concurrency=0/음수/비정수면 의도치 않은
+   * 무제한 in-flight(서버측 동시성 제한 무력화) 풋건이 된다 — 그 전에 막는다.
+   * @param {typeof MegaJob} JobClass @returns {number} 양의 정수 concurrency.
+   * @throws {MegaConfigError} concurrency 가 양의 정수가 아닐 때.
+   */
+  #resolveConcurrency(JobClass) {
+    const concurrency = JobClass.concurrency ?? 1
+    if (!Number.isInteger(concurrency) || concurrency < 1) {
+      throw new MegaConfigError(
+        'job.invalid_concurrency',
+        `MegaJobQueue: '${JobClass.name}' static concurrency must be a positive integer (got: ${concurrency}). ` +
+          `NATS treats max_ack_pending=0 as unlimited, so 0/negative/non-integer values are rejected.`,
+        { details: { job: JobClass.name, concurrency } },
+      )
+    }
+    return concurrency
+  }
+
+  /**
+   * 이벤트를 안전하게 발화한다 — 리스너(소비자 코드)가 throw 해도 잡 처리 흐름(ack/nak/DLQ)을 오염시키지
+   * 않도록 격리한다. `_handleMessage`/`#routeToDlq` 의 **"절대 throw 안 함" 불변식**을 지키는 핵심(M-3·L-3:
+   * 형제 MegaScheduler `#fire` 와 동일 정책). 리스너 예외는 묵히지 않고 stderr 로 표면화한다(   * logger 미주입이라 console). `fail` 리스너 예외를 다시 `fail` 로 emit 하면 무한 재귀라 console 로만 알린다.
+   * @param {'dispatch'|'start'|'done'|'retry'|'fail'|'dlq'} event @param {any} payload @returns {void}
+   */
+  #safeEmit(event, payload) {
+    try {
+      this.emit(event, payload)
+    } catch (e) {
+      // 리스너 throw 는 비치명 — ack/nak(부작용)은 emit 보다 먼저 확정되므로 잡 처리에 영향 없다.
+      // 묵히지 않고 stderr 로 알린다(logger 미주입이라 console).
+      console.error(
+        `[mega-job-queue] '${event}' event listener threw (ignored — does not affect job processing):`,
+        e,
+      )
+    }
+  }
+
+  /**
+   * 잡 스트림(workqueue)과 DLQ 스트림(limits)을 멱등 생성한다. 이미 있으면 그대로 둔다(설정 변경은
+   * 운영 책임 — 자동 update 안 함). enqueue/consume 가 자동 호출하므로 보통 직접 부를 필요 없다.
+   * @param {typeof MegaJob} JobClass @returns {Promise<void>}
+   */
+  async ensureStream(JobClass) {
+    await this.ensureReady()
+    const subject = this.#assertJobSubject(JobClass)
+    const nats = /** @type {typeof import('nats')} */ (this.#nats)
+    await this.#ensureStreamExists(this.#workStreamName(subject), [subject], nats.RetentionPolicy.Workqueue)
+    // DLQ 스트림에 한도를 건다(무한 적재 방지, ADR-134). dlqMaxAgeMs=0 이면 max_age 미지정(무제한),
+    // dlqMaxBytes 미지정이면 max_bytes 미지정.
+    await this.#ensureStreamExists(this.#dlqStreamName(subject), [`${subject}.dlq`], nats.RetentionPolicy.Limits, {
+      maxAgeMs: this.#dlqMaxAgeMs,
+      maxBytes: this.#dlqMaxBytes,
+    })
+  }
+
+  /**
+   * 단일 스트림 멱등 생성 — info 로 존재 확인 후 없으면 add. not-found 외 에러는 전파. `limits` 가
+   * 주어지면 생성 시 `max_age`/`max_bytes` 를 함께 설정한다(DLQ 한도, ADR-134). 이미 존재하는 스트림은
+   * 갱신하지 않는다(멱등 — 설정 변경은 운영 책임).
+   * @param {string} name @param {string[]} subjects @param {import('nats').RetentionPolicy} retention
+   * @param {{ maxAgeMs?: number, maxBytes?: number }} [limits]
+   * @returns {Promise<void>}
+   */
+  async #ensureStreamExists(name, subjects, retention, limits) {
+    const jsm = /** @type {import('nats').JetStreamManager} */ (this.#jsm)
+    const nats = /** @type {typeof import('nats')} */ (this.#nats)
+    try {
+      await jsm.streams.info(name)
+      return // 이미 존재.
+    } catch (e) {
+      if (/** @type {any} */ (e)?.code !== NOT_FOUND_CODE) throw e // 진짜 장애는 묻지 않는다.
+    }
+    /** @type {Record<string, any>} */
+    const config = { name, subjects, retention, storage: nats.StorageType.File }
+    if (limits) {
+      // max_age 는 nanos(ms→ns). 0 은 NATS 에서 "무제한" 이므로 양수일 때만 설정(미지정=무제한과 동일).
+      if (typeof limits.maxAgeMs === 'number' && limits.maxAgeMs > 0) config.max_age = nats.nanos(limits.maxAgeMs)
+      if (typeof limits.maxBytes === 'number' && limits.maxBytes > 0) config.max_bytes = limits.maxBytes
+    }
+    await jsm.streams.add(config)
+  }
+
+  /**
+   * durable consumer 를 멱등 생성한다(같은 durable_name = 워커 그룹 → load-balance + 중복방지).
+   * @param {string} stream @param {string} durable @param {string} subject @param {number} concurrency @returns {Promise<void>}
+   */
+  async #ensureConsumer(stream, durable, subject, concurrency) {
+    const jsm = /** @type {import('nats').JetStreamManager} */ (this.#jsm)
+    const nats = /** @type {typeof import('nats')} */ (this.#nats)
+    try {
+      await jsm.consumers.info(stream, durable)
+      return
+    } catch (e) {
+      if (/** @type {any} */ (e)?.code !== NOT_FOUND_CODE) throw e
+    }
+    await jsm.consumers.add(stream, {
+      durable_name: durable,
+      ack_policy: nats.AckPolicy.Explicit, // 각 메시지를 명시 ack — 재시도/DLQ 제어의 전제.
+      ack_wait: nats.nanos(this.#ackWaitMs), // ms → ns(nanos). working() 하트비트가 갱신.
+      max_deliver: this.#maxDeliver, // 워커 크래시 재전달 backstop.
+      max_ack_pending: concurrency, // 동시 미ack 상한 = concurrency(서버측 in-flight 제한).
+      filter_subject: subject,
+    })
+  }
+
+  /**
+   * 잡을 큐에 넣는다(JetStream publish — 서버에 영속 저장). 스트림이 없으면 만든다.
+   * @param {typeof MegaJob} JobClass @param {any} payload @returns {Promise<{ seq: number, stream: string, duplicate: boolean }>}
+   */
+  async enqueue(JobClass, payload) {
+    await this.ensureStream(JobClass)
+    const subject = /** @type {string} */ (JobClass.subject)
+    const js = /** @type {import('nats').JetStreamClient} */ (this.#js)
+    const ack = await js.publish(subject, this.#encode(payload))
+    // dispatch 는 publish(부작용) 완료 후 발화 — 리스너 throw 가 반환값/흐름을 오염시키지 않게 safeEmit(L-3).
+    this.#safeEmit('dispatch', { subject, seq: ack.seq, stream: ack.stream })
+    return { seq: ack.seq, stream: ack.stream, duplicate: ack.duplicate }
+  }
+
+  /**
+   * 잡 처리를 시작한다 — durable consumer 를 만들고 메시지를 받아 `run(payload, ctx)` 를 재시도와 함께
+   * 실행한다. `static concurrency` 만큼 동시 처리한다. 반환 핸들의 `stop()` 으로 graceful 중단.
+   *
+   * (소비 워커 라이프사이클·bus 별명 배선은 `MegaJobWorker` 영역 — 본 메서드는 "처리 베이스".
+   * 정본 `MegaWorker` = CPU `worker_threads` 풀로 별개 추상(ADR-120/ADR-121).)
+   *
+   * @param {typeof MegaJob} JobClass @param {MegaJob} instance - `run` 호출 대상(서브클래스 인스턴스).
+   * @param {Record<string, any>} ctx - run 에 넘길 컨텍스트.
+   * @returns {Promise<{ stop: () => Promise<void> }>}
+   */
+  async consume(JobClass, instance, ctx) {
+    await this.ensureStream(JobClass)
+    const subject = /** @type {string} */ (JobClass.subject)
+    const stream = this.#workStreamName(subject)
+    const durable = this.#durableName(subject)
+    const concurrency = this.#resolveConcurrency(JobClass) // L-1: 양의 정수 fail-fast(max_ack_pending=0 풋건 차단).
+    const retryConfig = resolveJobRetryConfig(JobClass)
+    await this.#ensureConsumer(stream, durable, subject, concurrency)
+
+    const js = /** @type {import('nats').JetStreamClient} */ (this.#js)
+    const consumer = await js.consumers.get(stream, durable)
+    const messages = await consumer.consume({ max_messages: concurrency })
+
+    /** @type {Set<Promise<any>>} 진행 중 처리(동시성 상한). */
+    const inFlight = new Set()
+    const loop = (async () => {
+      for await (const msg of messages) {
+        const p = this._handleMessage(instance, ctx, msg, retryConfig, subject).finally(() =>
+          inFlight.delete(p),
+        )
+        inFlight.add(p)
+        // 동시성 상한 도달 시 하나라도 끝날 때까지 대기(과도 in-flight 방지).
+        if (inFlight.size >= concurrency) await Promise.race(inFlight)
+      }
+      await Promise.allSettled(inFlight) // close 후 남은 처리 마무리.
+    })()
+    // 루프 자체 에러(iterator 깨짐 등)는 묵지 않고 fail 로 표면화. _handleMessage 는 throw 안 함.
+    loop.catch((e) =>
+      this.#safeEmit('fail', {
+        subject,
+        error: e instanceof Error ? e : new Error(String(e)),
+        phase: 'consume-loop',
+      }),
+    )
+
+    return {
+      stop: async () => {
+        // ConsumerMessages.close() 는 Promise<void|Error> 를 반환(nats 2.29 consumer.d.ts) — drain 중
+        // 오류면 Error 인스턴스를 resolve 한다(reject 아님). 묵히지 않고 stderr 로 표면화한다(L-3).
+        const closeResult = await messages.close()
+        if (closeResult instanceof Error) {
+          console.error(`[mega-job-queue] consumer close reported an error on '${subject}':`, closeResult)
+        }
+        await loop.catch(() => {}) // 남은 처리 완료까지 대기(에러는 위 loop.catch 에서 이미 표면화).
+      },
+    }
+  }
+
+  /**
+   * 메시지 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
+   * @returns {Promise<MegaJobHandleResult>}
+   */
+  async _handleMessage(instance, ctx, msg, retryConfig, subject) {
+    const seq = msg.seq
+
+    // M-1(ADR-119 hardening): 이번 전달이 max_deliver 에 도달했고(deliveryCount >= maxDeliver)
+    // **이전에 최소 1번 재전달이 있었다면**(deliveryCount > 1), 이전 전달들이 워커 크래시(ack 못 하고
+    // 죽음 → ack_wait 만료 → 재전달)로 소진된 것이다. 이번이 JetStream 의 **마지막 전달**이라, 여기서
+    // run 을 또 시도해 같은 크래시가 나면 메시지가 워크 스트림에 orphan 으로 남는다(더는 재전달 안 됨,
+    // DLQ 로도 못 감). 따라서 run 없이 곧장 DLQ 로 라우팅한다(phase: 'max-deliver').
+    //   ⚠️ `deliveryCount > 1` 가드: maxDeliver=1(재전달 없음)이면 첫 전달도 deliveryCount=1 이라, 가드가
+    //   없으면 **정상 잡이 한 번도 실행되지 않고** DLQ 로 빠지는 풋건이 된다. 첫 전달은 항상 정상 처리한다.
+    if (msg.info.deliveryCount > 1 && msg.info.deliveryCount >= this.#maxDeliver) {
+      const error = new Error(
+        `MegaJobQueue: job on '${subject}' exhausted max_deliver (${this.#maxDeliver}) at delivery ` +
+          `${msg.info.deliveryCount} — routing to DLQ (likely worker crash loop).`,
+      )
+      this.#safeEmit('fail', { subject, seq, error, phase: 'max-deliver' })
+      let exhaustedPayload
+      try {
+        exhaustedPayload = this.#decode(msg.data)
+      } catch {
+        // 디코드까지 실패한 poison 이면 raw 바이트를 봉투에 보관(무시 아님, DLQ 로 보존).
+        exhaustedPayload = { decodeError: true, rawBase64: this.#toBase64(msg.data) }
+      }
+      await this.#routeToDlq(subject, exhaustedPayload, error, msg, seq)
+      return { ok: false, error }
+    }
+
+    let payload
+    try {
+      payload = this.#decode(msg.data)
+    } catch (decodeErr) {
+      // 디코드 불가 = poison 메시지. 재시도 무의미 → 곧장 DLQ(원본 바이트 base64 보관).
+      const error = decodeErr instanceof Error ? decodeErr : new Error(String(decodeErr))
+      this.#safeEmit('fail', { subject, seq, error, phase: 'decode' })
+      await this.#routeToDlq(subject, { decodeError: true, rawBase64: this.#toBase64(msg.data) }, error, msg, seq)
+      return { ok: false, error }
+    }
+
+    this.#safeEmit('start', { subject, seq })
+    let settled = false
+    // 재시도 동안 메시지를 점유하므로 ack_wait 만료(→중복 재전달)를 막기 위해 working() 으로 lease 갱신.
+    const heartbeat = setInterval(() => {
+      if (!settled) msg.working()
+    }, this.#heartbeatMs)
+
+    // run(재시도) 결과를 변수에 담는다 — ack/DLQ(부작용) + emit 은 try/catch **밖**에서 처리한다(M-3·L-3).
+    // 이유: emit('done')/emit('fail') 리스너가 throw 했을 때 run 의 catch 가 잡으면 성공 잡이 spurious
+    // DLQ·double-ack 로 오염된다. 결과 판정과 부작용을 분리해 "절대 throw 안 함" 불변식을 지킨다.
+    /** @type {any} run 성공 시 반환값(runError===null 일 때만 유효). */
+    let runResult
+    /** @type {Error|null} run 최종 실패 사유(성공이면 null). */
+    let runError = null
+    try {
+      runResult = await withRetry(() => instance.run(payload, ctx), {
+        ...retryConfig,
+        onFailedAttempt: (info) => {
+          this.#safeEmit('retry', {
+            subject,
+            seq,
+            attempt: info.attemptNumber,
+            retriesLeft: info.retriesLeft,
+            error: info.error,
+          })
+        },
+      })
+    } catch (err) {
+      runError = err instanceof Error ? err : new Error(String(err))
+    } finally {
+      settled = true
+      clearInterval(heartbeat)
+    }
+
+    if (runError === null) {
+      msg.ack() // 부작용(ack) 먼저 — emit 보다 앞서 확정한다.
+      this.#safeEmit('done', { subject, seq, result: runResult })
+      return { ok: true, result: runResult }
+    }
+    // run 소진 → DLQ 라우팅. emit('fail') 은 safeEmit 이라 리스너 throw 가 DLQ 흐름을 막지 않는다.
+    this.#safeEmit('fail', { subject, seq, error: runError, phase: 'run' })
+    await this.#routeToDlq(subject, payload, runError, msg, seq)
+    return { ok: false, error: runError }
+  }
+
+  /**
+   * DLQ 라우팅 — 실패 페이로드+에러 메타를 `<subject>.dlq` 로 발행하고 원본을 ack. 발행 실패 시 ack 하지
+   * 않고 nak 해 잡을 보존한다(at-least-once). 본 메서드도 throw 하지 않는다.
+   * @param {string} subject @param {any} payload @param {Error} error @param {import('nats').JsMsg} msg @param {number} seq @returns {Promise<void>}
+   */
+  async #routeToDlq(subject, payload, error, msg, seq) {
+    const dlqSubject = `${subject}.dlq`
+    const js = /** @type {import('nats').JetStreamClient} */ (this.#js)
+    try {
+      await js.publish(
+        dlqSubject,
+        this.#encode({
+          originalSubject: subject,
+          failedAt: new Date().toISOString(),
+          deliveryCount: msg.info.deliveryCount,
+          error: { name: error.name, message: error.message, stack: error.stack },
+          payload,
+        }),
+      )
+    } catch (pubErr) {
+      // DLQ 발행 실패 → ack 안 함(보존). nak 으로 재전달 요청 → DLQ 백엔드 회복 후 재시도(안 묻음).
+      const e = pubErr instanceof Error ? pubErr : new Error(String(pubErr))
+      msg.nak() // 부작용(nak) 먼저 확정 — emit 보다 앞선다(M-3: 리스너 throw 가 보존 결정을 막지 않게).
+      this.#safeEmit('fail', { subject, seq, error: e, phase: 'dlq-publish' })
+      return
+    }
+    msg.ack() // DLQ 에 안전히 보관됨 → 워크 메시지 제거(emit 보다 먼저 확정).
+    this.#safeEmit('dlq', { subject, dlqSubject, seq, error })
+  }
+
+  // ── 헬퍼 ────────────────────────────────────────────────────────────────
+
+  /** @param {any} value @returns {Uint8Array} JSONCodec 인코드(undefined→null). */
+  #encode(value) {
+    return /** @type {import('nats').Codec<any>} */ (this.#codec).encode(value === undefined ? null : value)
+  }
+
+  /** @param {Uint8Array} data @returns {any} JSONCodec 디코드. */
+  #decode(data) {
+    return /** @type {import('nats').Codec<any>} */ (this.#codec).decode(data)
+  }
+
+  /** @param {Uint8Array} data @returns {string} base64(원본 바이트 보존용). */
+  #toBase64(data) {
+    return Buffer.from(data).toString('base64')
+  }
+
+  /** @param {string} subject @returns {string} 스트림 이름 안전화(영숫자·_·- 외 → _). */
+  #sanitize(subject) {
+    return subject.replace(/[^A-Za-z0-9_-]/g, '_')
+  }
+
+  /** @param {string} subject @returns {string} 워크 스트림 이름. */
+  #workStreamName(subject) {
+    return `${this.#streamPrefix}_${this.#sanitize(subject)}`
+  }
+
+  /** @param {string} subject @returns {string} DLQ 스트림 이름. */
+  #dlqStreamName(subject) {
+    return `${this.#streamPrefix}_${this.#sanitize(subject)}_DLQ`
+  }
+
+  /** @param {string} subject @returns {string} durable consumer 이름(워커 그룹 키). */
+  #durableName(subject) {
+    return `${this.#sanitize(subject)}_workers`
+  }
+}