mega-framework 0.1.6 → 0.1.8

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

@@ -43,7 +43,7 @@
  */
 import { EventEmitter } from 'node:events'
 import { MegaConfigError } from '../errors/config-error.js'
-import { MegaJob, resolveJobRetryConfig } from './mega-job.js'
+import { MegaJob, resolveJobRetryConfig, resolveJobRunTimeoutMs } from './mega-job.js'
 import { withRetry } from './mega-retry.js'
 
 /** 잡 큐가 노출하는 이벤트 화이트리스트(오타 차단 + 문서화 — 형제 클래스와 동일 정책). */
@@ -52,7 +52,7 @@ const KNOWN_EVENTS = Object.freeze([
   'start', // 메시지 처리 시작
   'done', // 처리 성공 + ack — event.result
   'retry', // 재시도 1회 실패(다음 시도 전) — event.attempt/retriesLeft/error
-  'fail', // 최종 실패 — event.phase('run'|'decode'|'dlq-publish'|'max-deliver'|'consume-loop')/error
+  'fail', // 최종 실패 — event.phase('run'|'decode'|'dlq-publish'|'dlq-orphan'|'max-deliver'|'consume-loop'|'abandoned-run')/error
   'dlq', // DLQ 라우팅 완료 — event.dlqSubject
 ])
 
@@ -62,6 +62,15 @@ 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
 
+/**
+ * run 전체(재시도 포함) 실행 상한 디폴트(ms) — 30분. 행(hang)된 run 이 `working()` lease 를 영원히
+ * 갱신하며 메시지를 영구 점유하는 것을 막는 backstop. 잡별 `static timeoutMs` 로 override, `0` = 무제한.
+ */
+export const DEFAULT_RUN_TIMEOUT_MS = 30 * 60 * 1000
+
+/** DLQ publish 실패 nak 재전달 지연 상한(ms) — 즉시 재전달 핫 루프 방지(점증 지연의 cap). */
+const NAK_DELAY_MAX_MS = 30_000
+
 /** DLQ 봉투에 싣는 error.stack 최대 길이(자) — poison 잡 폭주 시 DLQ 비대 방지(Med). */
 const DLQ_MAX_STACK_LEN = 4000
 
@@ -82,12 +91,18 @@ function truncateStack(stack) {
  *   하트비트가 이 값의 절반마다 lease 를 갱신한다.
  * @property {number} [maxDeliver=5] - JetStream 최대 전달 횟수(워커 크래시 재전달 backstop).
  * @property {number} [heartbeatMs] - `working()` 전송 주기(ms). 기본 `max(1000, ackWaitMs/2)`.
+ *   양의 정수 + `< ackWaitMs` 필수(생성자 fail-fast) — 이상이면 lease 갱신이 늦어 정상 처리 중
+ *   중복 재전달, 0 이하면 working() 플러딩.
  * @property {string} [streamPrefix='MEGA_JOBS'] - 스트림 이름 접두사.
  * @property {number} [dlqMaxAgeMs=604800000] - DLQ 스트림 메시지 보존 기한(ms, 디폴트 7일). 초과한 실패
  *   잡은 NATS 가 자동 만료시킨다(무한 적재 방지, ADR-134). `0` 이면 무제한(끔 — 영구 보존). **신규 DLQ
  *   스트림 생성 시에만** 적용(멱등 — 기존 스트림은 운영자가 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) 으로 표면화.
  */
 
 /**
@@ -116,17 +131,25 @@ export class MegaJobQueue extends EventEmitter {
   /** @type {string} */ #streamPrefix
   /** @type {number} DLQ max_age(ms). 0 = 무제한. */ #dlqMaxAgeMs
   /** @type {number|undefined} DLQ max_bytes. undefined = 무제한. */ #dlqMaxBytes
+  /** @type {number} run 전체 실행 상한 디폴트(ms). 0 = 무제한. 잡별 static timeoutMs 가 우선. */ #runTimeoutMs
   /** @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
+  /**
+   * subject 별 ensureStream 멱등 캐시(#readyPromise 와 동일 패턴). 없으면 enqueue 가 매 호출
+   * `jsm.streams.info` RPC ×2(워크+DLQ)를 반복해 enqueue 비용의 2/3 가 존재 재확인에 낭비된다.
+   * 실패한 Promise 는 캐시에서 비워 다음 호출이 재시도하게 한다.
+   * @type {Map<string, Promise<void>>}
+   */
+  #ensuredStreams = new Map()
 
   /**
    * @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} */ ({})) {
+  constructor({ nc, ackWaitMs = 30_000, maxDeliver = 5, heartbeatMs, streamPrefix = 'MEGA_JOBS', dlqMaxAgeMs = DEFAULT_DLQ_MAX_AGE_MS, dlqMaxBytes, runTimeoutMs = DEFAULT_RUN_TIMEOUT_MS } = /** @type {any} */ ({})) {
     super()
     if (!nc || typeof nc.jetstream !== 'function' || typeof nc.jetstreamManager !== 'function') {
       throw new TypeError(
@@ -146,6 +169,15 @@ export class MegaJobQueue extends EventEmitter {
     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}.`)
     }
+    // runTimeoutMs: 0 = 무제한(끔). 음수/비정수는 운영 실수라 fail-fast(silent 보정 X).
+    if (typeof runTimeoutMs !== 'number' || !Number.isInteger(runTimeoutMs) || runTimeoutMs < 0) {
+      throw new TypeError(`MegaJobQueue: runTimeoutMs must be an integer >= 0 (0 = unlimited). Got: ${runTimeoutMs}.`)
+    }
+    // heartbeatMs: working() lease 갱신 주기. ackWaitMs 이상이면 갱신이 늦어 정상 처리 중 lease 가
+    // 만료돼 중복 재전달(at-least-once 폭증)되고, 0 이하면 setInterval 1ms 클램프로 working() 플러딩.
+    if (heartbeatMs !== undefined && (typeof heartbeatMs !== 'number' || !Number.isInteger(heartbeatMs) || heartbeatMs < 1 || heartbeatMs >= ackWaitMs)) {
+      throw new TypeError(`MegaJobQueue: heartbeatMs must be a positive integer < ackWaitMs (${ackWaitMs}). Got: ${heartbeatMs}.`)
+    }
     this.#nc = nc
     this.#ackWaitMs = ackWaitMs
     this.#maxDeliver = maxDeliver
@@ -153,6 +185,7 @@ export class MegaJobQueue extends EventEmitter {
     this.#streamPrefix = streamPrefix
     this.#dlqMaxAgeMs = dlqMaxAgeMs
     this.#dlqMaxBytes = dlqMaxBytes
+    this.#runTimeoutMs = runTimeoutMs
   }
 
   // ── 이벤트 화이트리스트(L-1 정책 — 형제 클래스와 동일) ────────────────────
@@ -317,16 +350,30 @@ export class MegaJobQueue extends EventEmitter {
    * @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,
-    })
+    // subject 별 1회만 실제 확인(RPC ×2) — 이후 호출은 캐시된 Promise 를 기다린다(동시 호출도 1회).
+    const cached = this.#ensuredStreams.get(subject)
+    if (cached) return cached
+    const ensured = (async () => {
+      await this.ensureReady()
+      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,
+      })
+    })()
+    this.#ensuredStreams.set(subject, ensured)
+    try {
+      await ensured
+    } catch (err) {
+      // 실패는 캐시하지 않는다 — NATS 일시 장애 후 다음 enqueue/consume 이 재시도할 수 있게.
+      this.#ensuredStreams.delete(subject)
+      throw err
+    }
+    return ensured
   }
 
   /**
@@ -380,14 +427,26 @@ export class MegaJobQueue extends EventEmitter {
   }
 
   /**
-   * 잡을 큐에 넣는다(JetStream publish — 서버에 영속 저장). 스트림이 없으면 만든다.
-   * @param {typeof MegaJob} JobClass @param {any} payload @returns {Promise<{ seq: number, stream: string, duplicate: boolean }>}
+   * 잡을 큐에 넣는다(JetStream publish — 서버에 영속 저장). 스트림이 없으면 만든다(subject 별 1회 확인 후 캐시).
+   *
+   * @param {typeof MegaJob} JobClass @param {any} payload
+   * @param {{ msgID?: string }} [opts] - `msgID` = JetStream `Nats-Msg-Id` dedup 키(옵트인). 스트림
+   *   duplicate window(NATS 기본 2분 — 운영자가 NATS CLI 로 스트림별 조정) 안의 같은 msgID 재발행은
+   *   적재되지 않고 `duplicate: true` 로 반환된다. 비즈니스 멱등키(주문 ID 등)를 권장. 미지정 시
+   *   dedup 없음 — `duplicate` 는 항상 false.
+   * @returns {Promise<{ seq: number, stream: string, duplicate: boolean }>}
    */
-  async enqueue(JobClass, payload) {
+  async enqueue(JobClass, payload, { msgID } = /** @type {{ msgID?: string }} */ ({})) {
+    if (msgID !== undefined && (typeof msgID !== 'string' || msgID.length === 0)) {
+      throw new TypeError(`MegaJobQueue.enqueue: msgID, if set, must be a non-empty string. Got: ${msgID}.`)
+    }
     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))
+    // msgID(옵트인) = JetStream `Nats-Msg-Id` dedup — 스트림 duplicate window(NATS 기본 2분) 안의
+    // 같은 msgID 재발행은 적재되지 않고 ack.duplicate=true 로 돌아온다(producer 중복: 재시도 enqueue·
+    // 이중 클릭 방어). 미지정 시 dedup 없음(기존 동작, 비용 0) — duplicate 는 그때 항상 false.
+    const ack = await js.publish(subject, this.#encode(payload), msgID !== undefined ? { msgID } : undefined)
     // 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 }
@@ -416,6 +475,7 @@ export class MegaJobQueue extends EventEmitter {
     const durable = this.#durableName(subject)
     const concurrency = this.#resolveConcurrency(JobClass) // L-1: 양의 정수 fail-fast(max_ack_pending=0 풋건 차단).
     const retryConfig = resolveJobRetryConfig(JobClass)
+    const runTimeoutMs = resolveJobRunTimeoutMs(JobClass, this.#runTimeoutMs) // 행 잡 영구 점유 backstop.
     await this.#ensureConsumer(stream, durable, subject, concurrency)
 
     const js = /** @type {import('nats').JetStreamClient} */ (this.#js)
@@ -426,7 +486,7 @@ export class MegaJobQueue extends EventEmitter {
     const inFlight = new Set()
     const loop = (async () => {
       for await (const msg of messages) {
-        const p = this._handleMessage(instance, ctx, msg, retryConfig, subject).finally(() =>
+        const p = this._handleMessage(instance, ctx, msg, retryConfig, subject, runTimeoutMs).finally(() =>
           inFlight.delete(p),
         )
         inFlight.add(p)
@@ -464,9 +524,10 @@ export class MegaJobQueue extends EventEmitter {
    *
    * @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>}
    */
-  async _handleMessage(instance, ctx, msg, retryConfig, subject) {
+  async _handleMessage(instance, ctx, msg, retryConfig, subject, runTimeoutMs = this.#runTimeoutMs) {
     const seq = msg.seq
 
     // M-1(ADR-119 hardening): 이번 전달이 max_deliver 에 도달했고(deliveryCount >= maxDeliver)
@@ -520,8 +581,14 @@ export class MegaJobQueue extends EventEmitter {
     let runResult
     /** @type {Error|null} run 최종 실패 사유(성공이면 null). */
     let runError = null
+    /** @type {NodeJS.Timeout|undefined} run 타임아웃 타이머(있으면 finally 에서 정리). */
+    let timeoutHandle
+    /** @type {boolean} 타임아웃이 race 를 이겼는지(버려진 run 의 잔여 실패 표면화 분기용). */
+    let timedOut = false
+    /** @type {Promise<any>|undefined} run(재시도) Promise — 타임아웃 시 잔여 실패 관찰에 필요. */
+    let runPromise
     try {
-      runResult = await withRetry(() => instance.run(payload, ctx), {
+      runPromise = withRetry(() => instance.run(payload, ctx), {
         ...retryConfig,
         onFailedAttempt: (info) => {
           this.#safeEmit('retry', {
@@ -533,11 +600,44 @@ export class MegaJobQueue extends EventEmitter {
           })
         },
       })
+      if (runTimeoutMs > 0) {
+        // 행(hang) 잡 backstop: run 전체(재시도 포함)에 상한을 건다. 상한 초과 = 실패 판정 → DLQ.
+        // 없으면 working() 하트비트가 lease 를 영원히 갱신해 메시지가 재전달도 DLQ 도 못 가는
+        // 영구 점유가 된다(프로세스 사망 시에만 해소).
+        runResult = await Promise.race([
+          runPromise,
+          new Promise((_resolve, reject) => {
+            timeoutHandle = setTimeout(() => {
+              timedOut = true
+              reject(new Error(
+                `MegaJobQueue: job on '${subject}' exceeded run timeout (${runTimeoutMs}ms) — treating as ` +
+                  `failed (run continues in background; design run to be idempotent).`,
+              ))
+            }, runTimeoutMs)
+            if (typeof timeoutHandle.unref === 'function') timeoutHandle.unref()
+          }),
+        ])
+      } else {
+        runResult = await runPromise
+      }
     } catch (err) {
       runError = err instanceof Error ? err : new Error(String(err))
+      if (timedOut && runPromise) {
+        // 버려진(타임아웃 패배) run 의 나중 실패를 묵히지 않고 표면화한다 — 잡은 이미 실패 판정·DLQ
+        // 라우팅됐으므로 처리 흐름엔 영향 없다(reject 자체는 race 가 구독해 unhandledRejection 아님).
+        runPromise.catch((lateErr) => {
+          this.#safeEmit('fail', {
+            subject,
+            seq,
+            error: lateErr instanceof Error ? lateErr : new Error(String(lateErr)),
+            phase: 'abandoned-run',
+          })
+        })
+      }
     } finally {
       settled = true
       clearInterval(heartbeat)
+      if (timeoutHandle !== undefined) clearTimeout(timeoutHandle)
     }
 
     if (runError === null) {
@@ -552,30 +652,47 @@ export class MegaJobQueue extends EventEmitter {
   }
 
   /**
-   * DLQ 라우팅 — 실패 페이로드+에러 메타를 `<subject>.dlq` 로 발행하고 원본을 ack. 발행 실패 시 ack 하지
-   * 않고 nak 해 잡을 보존한다(at-least-once). 본 메서드도 throw 하지 않는다.
+   * DLQ 라우팅 — 실패 페이로드+에러 메타를 `<subject>.dlq` 로 발행하고 원본을 ack. 발행은 인프로세스로
+   * 짧게 재시도(일시 장애 흡수)하고, 그래도 실패하면 ack 하지 않고 **점증 지연 nak** 해 잡을 보존한다
+   * (at-least-once — 즉시 재전달 핫 루프 방지). 단 이번 전달이 `max_deliver` 의 **마지막 전달**이면 nak 해도
+   * 재전달이 없어 메시지가 워크 스트림에 orphan 으로 남는다 — 이때는 un-ack 보존 + `fail(dlq-orphan)` 으로
+   * 운영자 개입을 명시 표면화한다(ack/term 으로 잡을 지우면 유실이라 하지 않는다). 본 메서드도 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,
-          // stack 전체를 봉투에 담으면 poison 잡 폭주 시 DLQ 직렬화 비용·디스크가 급증한다 → 상한으로 truncate(Med).
-          error: { name: error.name, message: error.message, stack: truncateStack(error.stack) },
-          payload,
-        }),
+      // DLQ publish 자체를 짧게 재시도(추가 2회, 250ms→1s) — 일시적 NATS 응답 지연/재연결 틈을 흡수해
+      // nak 재전달(전체 인프로세스 재시도 사이클 반복)보다 훨씬 싸게 orphan 확률을 줄인다.
+      await withRetry(
+        () =>
+          js.publish(
+            dlqSubject,
+            this.#encode({
+              originalSubject: subject,
+              failedAt: new Date().toISOString(),
+              deliveryCount: msg.info.deliveryCount,
+              // stack 전체를 봉투에 담으면 poison 잡 폭주 시 DLQ 직렬화 비용·디스크가 급증한다 → 상한으로 truncate(Med).
+              error: { name: error.name, message: error.message, stack: truncateStack(error.stack) },
+              payload,
+            }),
+          ),
+        { retries: 2, minTimeout: 250, maxTimeout: 1000, factor: 2, jitter: true },
       )
     } 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' })
+      if (msg.info.deliveryCount >= this.#maxDeliver) {
+        // 마지막 전달 — nak 해도 JetStream 이 더는 재전달하지 않는다. ack/term 하면 잡이 사라지므로
+        // un-ack 로 워크 스트림에 보존하고(운영자가 NATS CLI 로 수습 가능), orphan 을 크게 표면화한다.
+        this.#safeEmit('fail', { subject, seq, error: e, phase: 'dlq-orphan' })
+        return
+      }
+      // DLQ 발행 실패 → ack 안 함(보존). 점증 지연 nak — 즉시 재전달이면 DLQ 백엔드 장애 동안
+      // 재전달→재시도 사이클 전체가 타이트하게 도는 핫 루프가 된다(deliveryCount 기반 지수 지연).
+      const nakDelayMs = Math.min(NAK_DELAY_MAX_MS, 1000 * 2 ** (msg.info.deliveryCount - 1))
+      msg.nak(nakDelayMs) // 부작용(nak) 먼저 확정 — emit 보다 앞선다(M-3: 리스너 throw 가 보존 결정을 막지 않게).
+      this.#safeEmit('fail', { subject, seq, error: e, phase: 'dlq-publish', nakDelayMs })
       return
     }
     msg.ack() // DLQ 에 안전히 보관됨 → 워크 메시지 제거(emit 보다 먼저 확정).

package/src/lib/mega-job.js

@@ -23,6 +23,7 @@
  *   - `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 (라이브러리 래핑)
@@ -72,7 +73,14 @@ export class MegaJob {
   /** @type {string|undefined} bus 별명(`ctx.bus(alias)`). 워커 배선이 nc 해석에 사용. */
   static bus = undefined
 
-  /** @type {number} 동시 처리 메시지 수(consumer max_ack_pending). 기본 1(순차·안전). */
+  /**
+   * @type {number} 동시 처리 메시지 수. 기본 1(순차·안전).
+   *
+   * ⚠️ 이 값은 durable consumer 의 `max_ack_pending` 으로 들어가므로 **워커 그룹(같은 subject 를
+   * 소비하는 모든 인스턴스) 전체의 합산 in-flight 상한**이다 — `mega worker` 인스턴스를 늘려도
+   * 합산 동시 처리는 이 값을 넘지 못한다. 처리량을 늘리려면 인스턴스 증설과 **함께** concurrency 를
+   * 키워야 한다(실측: c=1→c=32 에서 처리량 ~10배).
+   */
   static concurrency = 1
 
   /** @type {number} run 실패 시 **추가** 재시도 횟수(첫 시도 제외). 기본 3(OQ-012). */
@@ -81,6 +89,15 @@ export class MegaJob {
   /** @type {MegaJobBackoff} 지수 백오프 설정. 기본 { exponential, 1s, 30s }(OQ-012). */
   static backoff = JOB_RETRY_DEFAULTS.backoff
 
+  /**
+   * @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 = undefined
+
   /**
    * 메시지 1건마다 실행되는 본문. 서브클래스가 **반드시** 구현한다. throw 하면 {@link MegaJobQueue}
    * 가 재시도하고, 재시도 소진 시 DLQ 로 보낸다 — 그러므로 비치명/일시 오류는 그냥 throw 하면 된다.
@@ -138,3 +155,22 @@ export function resolveJobRetryConfig(JobClass) {
   // factor=2(exponential), jitter=on — OQ-012 정합. MegaRetry 가 첫 시도 즉시 + 이후 지수 백오프.
   return { retries, minTimeout: initial, maxTimeout: max, factor: 2, jitter: true }
 }
+
+/**
+ * 잡 클래스의 `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, defaultMs) {
+  const timeoutMs = JobClass.timeoutMs ?? defaultMs
+  if (typeof timeoutMs !== 'number' || !Number.isInteger(timeoutMs) || timeoutMs < 0) {
+    throw new TypeError(
+      `MegaJob '${JobClass.name}': static timeoutMs must be an integer >= 0 (0 = unlimited). Got: ${timeoutMs}.`,
+    )
+  }
+  return timeoutMs
+}

package/src/lib/mega-metrics.js

@@ -36,14 +36,10 @@
  * @see https://opentelemetry.io/docs/specs/otel/metrics/ (OTel metrics)
  * @see https://prometheus.io/docs/instrumenting/exposition_formats/ (Prometheus 텍스트 포맷)
  */
+import { getHeapStatistics } from 'node:v8'
 import { MeterProvider } from '@opentelemetry/sdk-metrics'
 import { PrometheusExporter, PrometheusSerializer } from '@opentelemetry/exporter-prometheus'
-import { resourceFromAttributes } from '@opentelemetry/resources'
-import {
-  ATTR_SERVICE_NAME,
-  ATTR_SERVICE_VERSION,
-  ATTR_DEPLOYMENT_ENVIRONMENT_NAME,
-} from '@opentelemetry/semantic-conventions'
+import { buildOtelResource } from './otel-resource.js'
 import { MegaConfigError } from '../errors/config-error.js'
 
 /** meter 이름 (instrumentation scope) — OTel 컨벤션상 패키지명. */
@@ -147,12 +143,8 @@ export function init(opts = /** @type {any} */ ({})) {
     )
   }
 
-  const resource = resourceFromAttributes({
-    [ATTR_SERVICE_NAME]: serviceName,
-    ...(typeof opts.version === 'string' ? { [ATTR_SERVICE_VERSION]: opts.version } : {}),
-    ...(typeof opts.environment === 'string' ? { [ATTR_DEPLOYMENT_ENVIRONMENT_NAME]: opts.environment } : {}),
-    ...(opts.attributes && typeof opts.attributes === 'object' ? opts.attributes : {}),
-  })
+  // resource 조립은 트레이싱과 공유하는 단일 출처(otel-resource.js, ADR-193) — 두 SDK 간 드리프트 방지.
+  const resource = buildOtelResource({ serviceName, version: opts.version, environment: opts.environment, attributes: opts.attributes })
 
   // preventServerStart — 자체 :9464 서버를 띄우지 않고 우리가 collect() 로 직접 긁는다(메인 포트 서빙).
   const reader = new PrometheusExporter({ preventServerStart: true })
@@ -556,7 +548,7 @@ function buildInstruments(meter) {
  */
 function registerSystemGauges(meter) {
   const memory = meter.createObservableGauge('mega_process_memory_bytes', {
-    description: '프로세스 메모리 사용량(바이트) — kind=rss|heap_used|heap_total|external 라벨.',
+    description: '프로세스 메모리 사용량(바이트) — kind=rss|heap_used|heap_total|external|array_buffers 라벨.',
     unit: 'By',
   })
   memory.addCallback((result) => {
@@ -565,6 +557,32 @@ function registerSystemGauges(meter) {
     result.observe(mu.heapUsed, { kind: 'heap_used' })
     result.observe(mu.heapTotal, { kind: 'heap_total' })
     result.observe(mu.external, { kind: 'external' })
+    // arrayBuffers 분리 노출(ADR-215, G5 M-5) — mongo driver 등 ArrayBuffer 상주분을 heap 과 구분해
+    // "RSS 만 보는" 관측 함정(burst 후 V8 페이지 미반환 = 정상 평형)을 운영자가 분해해 읽을 수 있게.
+    result.observe(mu.arrayBuffers ?? 0, { kind: 'array_buffers' })
+  })
+
+  // V8 힙 통계(ADR-215, G5 M-5) — heap_size_limit(OOM 한계)·total_available_size(여유)·physical 등
+  // process.memoryUsage 가 못 보여주는 V8 내부 수위. kind 는 고정 enum 이라 카디널리티 안전.
+  const V8_HEAP_KINDS = Object.freeze([
+    'total_heap_size',
+    'total_physical_size',
+    'total_available_size',
+    'used_heap_size',
+    'heap_size_limit',
+    'malloced_memory',
+    'peak_malloced_memory',
+    'external_memory',
+  ])
+  const v8Heap = meter.createObservableGauge('mega_v8_heap_bytes', {
+    description: `V8 힙 통계(바이트, v8.getHeapStatistics) — kind=${V8_HEAP_KINDS.join('|')} 라벨.`,
+    unit: 'By',
+  })
+  v8Heap.addCallback((result) => {
+    const hs = /** @type {Record<string, number>} */ (/** @type {unknown} */ (getHeapStatistics()))
+    for (const kind of V8_HEAP_KINDS) {
+      if (typeof hs[kind] === 'number') result.observe(hs[kind], { kind })
+    }
   })
 
   const uptime = meter.createObservableGauge('mega_process_uptime_seconds', {

package/src/lib/mega-plugin.js

@@ -53,11 +53,23 @@ const LIFECYCLE_EVENTS = /** @type {const} */ (['beforeBoot', 'afterBoot', 'befo
  */
 
 /**
+ * 플러그인 scaffold generator manifest(03-api-spec §11) — `mega g <name>` 이 소비한다(ADR-187/199).
+ * `dir` 는 프로젝트 루트 상대 출력 기준, `files[].path`/`files[].template` 의 `{{token}}` 은
+ * cli/generators 의 `SCAFFOLD_TOKENS` 계약(Name/name/camelName/snake/app)으로 치환된다.
  * @typedef {Object} MegaScaffoldDef
  * @property {string} dir
  * @property {Array<{ path: string, template: string }>} files
+ * @property {string} [description] - `mega help` 가 병기하는 한 줄 설명(선택).
  */
 
+/** 빌트인 generator 이름 — 플러그인 scaffold 가 점유 금지(빌트인이 우선이라 silent shadow 가 됨).
+ * cli/generators 의 `GENERATOR_KINDS` 와 동일해야 한다(레이어 역전 회피를 위해 미러 — 동기화는
+ * mega-plugin 단위 테스트가 GENERATOR_KINDS 와 집합 비교로 강제한다). */
+export const RESERVED_GENERATOR_NAMES = new Set([
+  'app', 'controller', 'channel', 'service', 'model', 'middleware', 'route',
+  'schedule', 'job', 'worker', 'locale', 'adapter', 'migration', 'adr',
+])
+
 /**
  * @typedef {Object} LoadedPluginMeta
  * @property {string} name
@@ -230,7 +242,8 @@ export class MegaPluginHost {
   }
 
   /**
-   * 스캐폴드 generator 등록. 같은 이름 재등록은 fail-fast.
+   * 스캐폴드 generator manifest 등록(ADR-199). 같은 이름 재등록·빌트인 13종 점유·파일 항목 모양 위반은
+   * **install 시점 fail-fast** — 첫 `mega g` 사용 때까지 잘못된 manifest 가 잠복하지 않게 한다.
    * @param {string} name
    * @param {MegaScaffoldDef} def
    * @returns {void}
@@ -239,15 +252,33 @@ export class MegaPluginHost {
     if (typeof name !== 'string' || name.length === 0) {
       throw new TypeError('mega.scaffold.register: name must be a non-empty string.')
     }
-    if (!def || typeof def.dir !== 'string' || !Array.isArray(def.files)) {
+    if (RESERVED_GENERATOR_NAMES.has(name)) {
+      // 빌트인 kind 는 `mega g` 디스패치에서 항상 우선이라, 등록을 허용하면 도달 불가(silent shadow)다.
+      throw new MegaConfigError('plugin.builtin_generator_conflict', `Plugin cannot register builtin generator "${name}" (reserved).`, {
+        details: { name },
+      })
+    }
+    if (!def || typeof def.dir !== 'string' || def.dir.length === 0 || !Array.isArray(def.files)) {
       throw new TypeError(`mega.scaffold.register('${name}'): def must be { dir: string, files: array }.`)
     }
+    for (const f of def.files) {
+      if (!f || typeof f.path !== 'string' || f.path.length === 0 || typeof f.template !== 'string') {
+        throw new TypeError(`mega.scaffold.register('${name}'): files entries must be { path: string, template: string }. Got ${JSON.stringify(f)}.`)
+      }
+    }
+    if (def.description !== undefined && typeof def.description !== 'string') {
+      throw new TypeError(`mega.scaffold.register('${name}'): description must be a string when given.`)
+    }
     if (this.#generators.has(name)) {
       throw new MegaConfigError('plugin.duplicate_generator', `Scaffold generator '${name}' is already registered.`, {
         details: { name },
       })
     }
-    this.#generators.set(name, { dir: def.dir, files: [...def.files] })
+    this.#generators.set(name, {
+      dir: def.dir,
+      files: def.files.map((f) => ({ path: f.path, template: f.template })),
+      ...(typeof def.description === 'string' ? { description: def.description } : {}),
+    })
   }
 
   /**

package/src/lib/mega-schedule.js

@@ -15,9 +15,10 @@
  *   먼저 잡은 1대만 실행하고, 못 잡은 나머지는 **조용히 건너뛴다**(skip). 락은 `ttl`(ms) 뒤 자동 만료돼
  *   다음 주기엔 다시 경쟁한다.
  *
- *   구현: `lock.acquire(key, { ttl, retryCount: 0 })` — **단 한 번** 시도하고 실패하면(이미 누가 잡음)
- *   즉시 skip 한다(retry 안 함 — retry+throw 는 "중복방지"가 아니라 "대기"라서 의미가 다름). 성공하면
- *   `run(ctx)` 실행 후 **반드시 release**(finally).
+ *   구현: `lock.withLock(key, { ttl, retryCount: 0 }, run)` — **단 한 번** 시도하고 실패하면(이미 누가
+ *   잡음) 즉시 skip 한다(retry 안 함 — retry+throw 는 "중복방지"가 아니라 "대기"라서 의미가 다름).
+ *   성공하면 임계구역 동안 락이 **자동 연장**되고(redlock `using`), 종료 시 자동 release 된다 —
+ *   run 이 ttl 을 넘겨도 락이 만료돼 다른 인스턴스가 끼어드는 중복 실행이 없다.
  *
  * # ⚠️ acquire 실패 = skip 의 한계 (ADR-118 기록)
  *   `acquire` 는 (a) 경합(다른 인스턴스가 보유)과 (b) 락 backend 장애(Redis 다운)를 **둘 다** throw 로
@@ -46,8 +47,10 @@ import { MegaCron } from './mega-cron.js'
  * @typedef {Object} MegaScheduleLock
  * @property {string} lock - lock 어댑터 별명(`ctx.lock(alias)` 로 해석). 03-api-spec 의 옛 `cache` 필드를
  *   대체한다(lock 이 독립 도메인이 된 뒤 정합 — ADR-118).
- * @property {number} ttl - 락 보유 시간(**밀리초**, 양의 정수). **작업 예상 소요보다 넉넉히** 잡아야
- *   한다 — 작업이 ttl 을 넘기면 락이 자동 만료돼 다른 인스턴스가 중복 실행할 수 있다(자동 연장 미사용).
+ * @property {number} ttl - 락 보유 시간(**밀리초**, 양의 정수). 임계구역 동안 **자동 연장**되므로
+ *   (redlock `using`) 작업이 ttl 을 넘겨도 중복 실행되지 않는다 — ttl 은 "연장 1회분 윈도우"다.
+ *   ⚠️ redlock 은 `ttl ≥ automaticExtensionThreshold(기본 500ms) + 100ms` 를 요구한다(기본 설정 기준
+ *   **600ms 이상**) — 미달이면 fire 시 skip(error 동봉)으로 표면화된다.
  * @property {string} [key] - 락 자원 키. 미지정 시 `mega:schedule:<클래스명>`.
  */
 
@@ -463,28 +466,43 @@ export class MegaScheduler extends EventEmitter {
     }
     const key = lock.key ?? `mega:schedule:${name}`
 
-    let held
+    // withLock(= redlock `using`, ADR-113) — 단 한 번 시도(retryCount: 0) + **자동 연장** + 자동 release.
+    // run 이 ttl 을 넘겨도 redlock 이 임계구역 동안 락을 연장해 다른 인스턴스의 중복 실행을 막는다
+    // (기존 acquire/release 는 "ttl 을 넉넉히" 라는 운영자 추측에 의존 — ADR-118 재평가 조건 충족으로 전환).
+    // 경합/backend 장애는 routine 진입 **전에** throw 되므로 acquired 플래그로 skip(미획득)과
+    // release 실패(획득 후)를 구분한다. run(ctx) 계약은 무변경 — 연장 실패(signal.aborted)는
+    // 스케줄러가 관찰해 fail(lock-extend) 로 표면화한다.
+    let acquired = false
+    /** @type {MegaScheduleFireResult|undefined} */
+    let outcome
     try {
-      // 단 한 번 시도(retryCount: 0). 실패=이미 누가 보유(또는 backend 장애) → skip.
-      held = await adapter.acquire(key, { ttl: lock.ttl, retryCount: 0 })
+      await adapter.withLock(key, { ttl: lock.ttl, retryCount: 0 }, async (/** @type {any} */ signal) => {
+        acquired = true
+        outcome = await this.#runBody(name, instance, ctx, key)
+        // 자동 연장 실패 = 임계구역 도중 배타성 상실(드묾 — lock backend 장애). run 결과와 별개로 표면화.
+        if (signal?.aborted) {
+          const cause = signal.error instanceof Error ? signal.error : undefined
+          const error = new Error(
+            `lock auto-extension failed for '${key}' — exclusivity may have been lost during run`,
+            cause ? { cause } : undefined,
+          )
+          this.emit('fail', { name, key, error, phase: 'lock-extend' })
+        }
+      })
     } catch (e) {
       const error = e instanceof Error ? e : new Error(String(e))
-      // 에러를 실어 관측 가능하게 — 인프라 장애도 여기로 오므로 소비자가 구분/경보(상단 docstring).
-      this.emit('skip', { name, key, reason: 'lock-not-acquired', error })
-      return { name, ran: false, skipped: true, ok: false, error }
-    }
-
-    try {
-      return await this.#runBody(name, instance, ctx, key)
-    } finally {
-      try {
-        await adapter.release(held)
-      } catch (e) {
-        // 락 해제 실패는 비치명적(ttl 로 자동 만료) — 다음 주기 재경쟁. 묵히지 않고 fail 로 표면화.
-        const error = e instanceof Error ? e : new Error(String(e))
-        this.emit('fail', { name, key, error, phase: 'release' })
+      if (!acquired) {
+        // 획득 실패 = 경합(다른 인스턴스 보유) 또는 backend 장애 — 구분 불가(상단 docstring).
+        // 에러를 실어 관측 가능하게 → 소비자가 로그/경보로 인프라 장애를 알아챈다.
+        this.emit('skip', { name, key, reason: 'lock-not-acquired', error })
+        return { name, ran: false, skipped: true, ok: false, error }
       }
+      // routine 진입 후 throw = release 경로 실패(#runBody 는 throw 안 함) — 비치명적(ttl 만료로
+      // 자동 해제, 다음 주기 재경쟁). run 결과는 보존해 반환한다.
+      this.emit('fail', { name, key, error, phase: 'release' })
+      return outcome ?? { name, ran: true, skipped: false, ok: false, error }
     }
+    return /** @type {MegaScheduleFireResult} */ (outcome)
   }
 
   /**