mega-framework 0.1.0

package/src/lib/mega-retry.js

@@ -0,0 +1,95 @@
+// @ts-check
+/**
+ * MegaRetry — exponential backoff 재시도 유틸 (ADR-029/ADR-098).
+ *
+ * 검증된 공개 라이브러리 `p-retry`(v8) 를 우리 컨벤션으로 얇게 래핑한다(ADR-029: "내부 구현은
+ * 검증된 공개 npm 라이브러리를 래핑한다 — MegaRetry=p-retry"). 직접 백오프 타이머를 굴리지 않는
+ * 이유: 지터·취소(AbortSignal)·시도별 콜백 같은 경계 케이스를 직접 짜면 추론 최소화 원칙 위반이
+ * 되기 쉽다. p-retry 는 이를 검증된 형태로 제공한다.
+ *
+ * # 백오프 공식 (p-retry)
+ *   delay(attempt) = min(maxTimeout, random * minTimeout * factor^(attempt-1))
+ *   - `jitter: true` → random ∈ [1, 2) 곱(p-retry `randomize`). thundering herd 완화.
+ *   - `jitter: false` → 정확히 minTimeout * factor^(attempt-1) (테스트 결정성).
+ *
+ * # 첫 시도는 즉시
+ *   attempt 1 은 지연 없이 실행된다. `retries: N` 이면 최대 N 회 **추가** 재시도(총 N+1 시도).
+ *
+ * # 재시도 중단 (AbortError)
+ *   {@link RetryAbortError} 를 throw 하면 즉시 중단되고 그 안에 감싼 원본 에러가 다시 던져진다.
+ *   "이 에러는 재시도해도 소용없다"(예: 인증 실패) 를 표현할 때 쓴다.
+ *
+ * # 에러 처리 정합
+ *   본 모듈은 에러를 묵지 않는다 — 최종 실패 시 마지막 에러를 그대로 throw 한다. 호출부가
+ *   try/catch 로 명시 처리 하도록 한다.
+ *
+ * @module lib/mega-retry
+ */
+import pRetry, { AbortError } from 'p-retry'
+
+/**
+ * 재시도를 즉시 중단시키는 에러 래퍼 (p-retry `AbortError`). `throw new RetryAbortError(원본에러)`
+ * 하면 더 이상 재시도하지 않고 원본 에러가 호출부로 전파된다.
+ * @type {typeof AbortError}
+ */
+export const RetryAbortError = AbortError
+
+/**
+ * @typedef {Object} MegaRetryOptions
+ * @property {number} [retries=10] - 최대 **추가** 재시도 횟수(첫 시도 제외). Infinity 허용.
+ * @property {number} [minTimeout=1000] - 첫 백오프 지연(ms).
+ * @property {number} [maxTimeout=30000] - 백오프 지연 상한(ms).
+ * @property {number} [factor=2] - 지수 증가율.
+ * @property {boolean} [jitter=true] - 지연에 random[1,2) 곱(thundering herd 완화). false 면 결정적.
+ * @property {(ctx: { error: Error, attemptNumber: number, retriesLeft: number, retryDelay: number }) => void|Promise<void>} [onFailedAttempt]
+ *   - 매 시도 실패 직후 호출(다음 지연 전). 로그/관측용. throw 하면 재시도 중단.
+ * @property {(ctx: { error: Error, attemptNumber: number, retriesLeft: number }) => boolean|Promise<boolean>} [shouldRetry]
+ *   - false 반환 시 재시도 중단(마지막 에러 throw). 특정 에러만 재시도할 때.
+ * @property {AbortSignal} [signal] - abort 시 대기/재시도 즉시 취소.
+ * @property {boolean} [unref=true] - 백오프 타이머 unref(프로세스 종료를 막지 않음). 기본 true.
+ */
+
+/**
+ * `fn` 을 지수 백오프로 재시도한다. 성공 시 그 반환값을, 모두 실패하면 마지막 에러를 throw.
+ *
+ * @template T
+ * @param {(attemptNumber: number) => Promise<T>|T} fn - 실행할 작업. attemptNumber(1-based) 를 받는다.
+ * @param {MegaRetryOptions} [options]
+ * @returns {Promise<T>}
+ * @throws {Error} 모든 시도 실패 시 마지막 에러(또는 RetryAbortError 의 원본 에러).
+ * @example
+ *   await withRetry(() => connectToHub(), { retries: 5, minTimeout: 500, maxTimeout: 10_000 })
+ */
+export function withRetry(fn, options = {}) {
+  const {
+    retries = 10,
+    minTimeout = 1000,
+    maxTimeout = 30_000,
+    factor = 2,
+    jitter = true,
+    onFailedAttempt,
+    shouldRetry,
+    signal,
+    unref = true,
+  } = options
+
+  // jitter → p-retry `randomize`. 나머지는 1:1 매핑. 콜백/signal 은 있을 때만 실어 p-retry 기본 유지.
+  // p-retry 의 Options 타입은 readonly 라 한 번에 리터럴로 구성한다(이후 변형 X).
+  /** @type {import('p-retry').Options} */
+  const pOpts = {
+    retries,
+    minTimeout,
+    maxTimeout,
+    factor,
+    randomize: jitter,
+    unref,
+    ...(typeof onFailedAttempt === 'function' ? { onFailedAttempt } : {}),
+    ...(typeof shouldRetry === 'function' ? { shouldRetry } : {}),
+    ...(signal ? { signal } : {}),
+  }
+
+  return pRetry(fn, pOpts)
+}
+
+/** 네임스페이스 형태 접근(다른 Mega* 유틸과 일관). `MegaRetry.withRetry(...)`. */
+export const MegaRetry = Object.freeze({ withRetry, RetryAbortError })

package/src/lib/mega-schedule.js

@@ -0,0 +1,507 @@
+// @ts-check
+/**
+ * MegaSchedule / MegaScheduler — cron 기반 작업 스케줄러 + 분산 중복 실행 방지 (ADR-118).
+ *
+ * 두 가지를 제공한다:
+ *   - {@link MegaSchedule}  — 스케줄 작업 **베이스 클래스**(static 설정 + `run(ctx)`). 03-api-spec §6 의
+ *     "클래스 + static 설정" 패턴(MegaJob/MegaWorker 와 동형).
+ *   - {@link MegaScheduler} — 등록된 스케줄들을 실제 cron 시각에 **실행**하는 런타임. 시각 계산·타이머는
+ *     `croner`(v10) 에 위임하고(MegaCron 과 동일 라이브러리), **분산 중복방지**는
+ *     `MegaLockAdapter`(redlock, `ctx.lock(alias)`)에 위임한다.
+ *
+ * # 분산 중복 실행 방지 (왜 필요한가 — 중학생용)
+ *   같은 앱을 서버 2대(또는 2 프로세스)에 띄우면, "매일 새벽 3시 정리" 같은 스케줄이 **양쪽에서 동시에**
+ *   돈다 → 정리가 2번 실행돼 데이터가 꼬일 수 있다. 그래서 실행 직전에 **분산 락**을 딱 1개만 잡게 한다:
+ *   먼저 잡은 1대만 실행하고, 못 잡은 나머지는 **조용히 건너뛴다**(skip). 락은 `ttl`(ms) 뒤 자동 만료돼
+ *   다음 주기엔 다시 경쟁한다.
+ *
+ *   구현: `lock.acquire(key, { ttl, retryCount: 0 })` — **단 한 번** 시도하고 실패하면(이미 누가 잡음)
+ *   즉시 skip 한다(retry 안 함 — retry+throw 는 "중복방지"가 아니라 "대기"라서 의미가 다름). 성공하면
+ *   `run(ctx)` 실행 후 **반드시 release**(finally).
+ *
+ * # ⚠️ acquire 실패 = skip 의 한계 (ADR-118 기록)
+ *   `acquire` 는 (a) 경합(다른 인스턴스가 보유)과 (b) 락 backend 장애(Redis 다운)를 **둘 다** throw 로
+ *   알린다 — 현재 lock 어댑터 계약상 둘을 typed-error 로 구분하지 못한다. 그래서 본 스케줄러는 acquire
+ *   실패를 모두 skip 으로 보되, **에러를 `skip` 이벤트에 실어** 관측 가능하게 한다(소비자가 로그로
+ *   인프라 장애를 알아챌 수 있게). 부팅 시 `connectAll({ ping: true })` 가 backend 가용성을 1차 검증한다.
+ *   런타임 장애 구분(skip vs fail)을 위한 lock 어댑터 typed-error 는 후속 과제(ADR-118 재평가 조건).
+ *
+ * # 순수 유틸이라 logger 미주입, 이벤트로 노출
+ *   MegaCircuitBreaker 와 동일하게 본 스케줄러는 logger 를 모른다. 대신 흐름 길목(job 시작/종료)을
+ *   이벤트로 노출한다: `run`(실행 시작)·`done`(성공)·`skip`(락 미획득→건너뜀)·`fail`(실행/해제 실패).
+ *   소비자(앱·CLI)가 이 이벤트를 구독해 `logger.debug/warn` 을 박는다. **타이머로 자동 실행되는 경로는
+ *   호출자가 없으므로, 실패를 놓치지 않으려면 `fail`/`skip` 구독이 사실상 필수다.**
+ *
+ * @module lib/mega-schedule
+ * @see ADR-118, ADR-113 (MegaLock/redlock), ADR-029 (라이브러리 래핑)
+ */
+import { Cron } from 'croner'
+import { EventEmitter } from 'node:events'
+import { MegaConfigError } from '../errors/config-error.js'
+import { MegaCron } from './mega-cron.js'
+
+/**
+ * 스케줄 분산 락 설정. **lock 도메인은 cache 와 별개**(ADR-113) — `ctx.lock(alias)`.
+ *
+ * @typedef {Object} MegaScheduleLock
+ * @property {string} lock - lock 어댑터 별명(`ctx.lock(alias)` 로 해석). 03-api-spec 의 옛 `cache` 필드를
+ *   대체한다(lock 이 독립 도메인이 된 뒤 정합 — ADR-118).
+ * @property {number} ttl - 락 보유 시간(**밀리초**, 양의 정수). **작업 예상 소요보다 넉넉히** 잡아야
+ *   한다 — 작업이 ttl 을 넘기면 락이 자동 만료돼 다른 인스턴스가 중복 실행할 수 있다(자동 연장 미사용).
+ * @property {string} [key] - 락 자원 키. 미지정 시 `mega:schedule:<클래스명>`.
+ */
+
+/**
+ * 스케줄 작업 베이스 클래스. 서브클래스가 static 설정과 `run(ctx)` 를 정의한다.
+ *
+ * @example
+ * export class DailyCleanup extends MegaSchedule {
+ *   static cron = '0 3 * * *'
+ *   static timezone = 'Asia/Seoul'
+ *   static lock = { lock: 'main', ttl: 60_000 }   // 분산 중복방지 (ms!)
+ *   async run(ctx) {
+ *     await ctx.db('main').native.query('DELETE FROM tmp WHERE ...')
+ *   }
+ * }
+ */
+export class MegaSchedule {
+  /** @type {string|undefined} cron 표현식(필수 — 미정의 시 register 에서 throw). */
+  static cron = undefined
+
+  /** @type {string|undefined} IANA 타임존(예: 'Asia/Seoul'). 미지정 시 호스트 로컬. */
+  static timezone = undefined
+
+  /** @type {MegaScheduleLock|undefined} 분산 중복방지 락 설정. 미지정 시 중복방지 없이 실행. */
+  static lock = undefined
+
+  /**
+   * 스케줄 시각마다 실행되는 본문. 서브클래스가 **반드시** 구현한다.
+   * @param {Record<string, any>} _ctx - 실행 컨텍스트(`db/cache/bus/lock` 접근자 등, ctx-builder 참조).
+   * @returns {Promise<any>}
+   * @throws {Error} 서브클래스가 구현하지 않으면.
+   */
+  async run(_ctx) {
+    throw new Error(
+      `${this.constructor.name}: MegaSchedule subclass must implement async run(ctx).`,
+    )
+  }
+}
+
+/** 스케줄러가 노출하는 이벤트 화이트리스트(오타 차단 + 문서화 — MegaCircuitBreaker 와 동일 정책). */
+const KNOWN_EVENTS = Object.freeze([
+  'run', // 작업 실행 시작(락 획득 후, 또는 락 미사용)
+  'skip', // 락 미획득(다른 인스턴스가 보유 등)으로 건너뜀 — event.error 에 사유
+  'done', // 작업 성공 완료
+  'fail', // 작업 run() 실패 또는 락 release 실패 — event.error / event.phase
+])
+
+/**
+ * @typedef {Object} MegaScheduleFireResult - {@link MegaScheduler#runNow} / 내부 fire 의 결과.
+ * @property {string} name - 스케줄 클래스명.
+ * @property {boolean} ran - 실제로 run(ctx) 가 호출됐는지(skip 이면 false).
+ * @property {boolean} skipped - 락 미획득으로 건너뛰었는지.
+ * @property {boolean} ok - run(ctx) 가 에러 없이 끝났는지(skip 이면 false).
+ * @property {any} [result] - run(ctx) 반환값(성공 시).
+ * @property {Error} [error] - 실패/skip 사유.
+ */
+
+/**
+ * @typedef {Object} ScheduleEntry - 등록된 스케줄 1건의 내부 메타데이터.
+ * @property {string} name - 스케줄 클래스명(= 등록 키).
+ * @property {typeof MegaSchedule} ScheduleClass - 등록된 클래스.
+ * @property {MegaSchedule} instance - 인스턴스(run 호출 대상).
+ * @property {string} cron - cron 표현식.
+ * @property {string|undefined} timezone - IANA 타임존.
+ * @property {MegaScheduleLock|undefined} lock - 분산 락 설정.
+ * @property {Cron|null} job - start() 가 만든 croner 핸들(미 start 면 null).
+ */
+
+/**
+ * 등록된 스케줄들을 cron 시각에 실행하는 런타임. 시각/타이머는 croner, 분산 중복방지는 lock 어댑터에 위임.
+ *
+ * @example
+ * const scheduler = new MegaScheduler({ ctx })   // ctx 는 lock 사용 시 ctx.lock(alias) 필요
+ * scheduler.on('skip', (e) => log.debug(e, 'schedule skipped'))
+ * scheduler.on('fail', (e) => log.error(e, 'schedule failed'))
+ * scheduler.register(DailyCleanup).start()
+ * // graceful shutdown
+ * scheduler.stop()
+ */
+export class MegaScheduler extends EventEmitter {
+  /** @type {Record<string, any>|null} run(ctx) 에 넘길 컨텍스트(+ lock 해석용). */
+  #ctx
+  /** @type {Map<string, ScheduleEntry>} 등록된 스케줄(이름 → 메타 + croner 핸들). */
+  #jobs = new Map()
+  /** @type {boolean} start() 호출 후 stop() 전까지 true. */
+  #started = false
+
+  /**
+   * @param {object} [args]
+   * @param {Record<string, any>} [args.ctx] - 실행 컨텍스트. 스케줄이 `static lock` 을 쓰면 `ctx.lock`
+   *   (함수)이 있어야 한다(없으면 fire 시 throw). lock 미사용이면 생략 가능.
+   */
+  constructor({ ctx } = {}) {
+    super()
+    this.#ctx = ctx ?? null
+  }
+
+  /**
+   * 이벤트명 화이트리스트 검증. 모든 구독/해제 오버라이드가 공유한다 — 오타 이벤트명을 조용히
+   * 무시하지 않고 즉시 RangeError 로 드러낸다(L-1: on/off 뿐 아니라 once/addListener/prepend* 도 동일 보호).
+   * @param {string} method - 호출된 메서드명(에러 메시지용).
+   * @param {string} event - 검증할 이벤트명.
+   * @returns {void}
+   * @throws {RangeError} 알 수 없는 이벤트명일 때.
+   */
+  #assertKnownEvent(method, event) {
+    if (!KNOWN_EVENTS.includes(event)) {
+      throw new RangeError(
+        `MegaScheduler.${method}('${event}', ...) — unknown event. Known: ${KNOWN_EVENTS.join(', ')}.`,
+      )
+    }
+  }
+
+  /**
+   * 이벤트 구독. 알 수 없는 이벤트명은 오타로 보고 throw(MegaCircuitBreaker 와 동일).
+   * @param {'run'|'skip'|'done'|'fail'} event @param {(payload: any) => void} listener @returns {this}
+   * @throws {RangeError} 알 수 없는 이벤트명일 때.
+   */
+  on(event, listener) {
+    this.#assertKnownEvent('on', event)
+    return super.on(event, listener)
+  }
+
+  /**
+   * {@link MegaScheduler#on} 으로 등록한 리스너 해제. 동일 화이트리스트 검증. (`removeListener` 별칭도 보호.)
+   * @param {'run'|'skip'|'done'|'fail'} event @param {(payload: any) => void} listener @returns {this}
+   * @throws {RangeError} 알 수 없는 이벤트명일 때.
+   */
+  off(event, listener) {
+    this.#assertKnownEvent('off', event)
+    return super.off(event, listener)
+  }
+
+  /**
+   * 1회성 구독(EventEmitter `once`). on() 과 동일 화이트리스트(L-1).
+   * @param {'run'|'skip'|'done'|'fail'} event @param {(payload: any) => void} listener @returns {this}
+   * @throws {RangeError} 알 수 없는 이벤트명일 때.
+   */
+  once(event, listener) {
+    this.#assertKnownEvent('once', event)
+    return super.once(event, listener)
+  }
+
+  /**
+   * `on` 의 EventEmitter 별칭. 우회로 화이트리스트를 비껴가지 않도록 동일 검증(L-1).
+   * @param {'run'|'skip'|'done'|'fail'} event @param {(payload: any) => void} listener @returns {this}
+   * @throws {RangeError} 알 수 없는 이벤트명일 때.
+   */
+  addListener(event, listener) {
+    this.#assertKnownEvent('addListener', event)
+    return super.addListener(event, listener)
+  }
+
+  /**
+   * `off` 의 EventEmitter 별칭. 동일 화이트리스트 검증(L-1).
+   * @param {'run'|'skip'|'done'|'fail'} event @param {(payload: any) => void} listener @returns {this}
+   * @throws {RangeError} 알 수 없는 이벤트명일 때.
+   */
+  removeListener(event, listener) {
+    this.#assertKnownEvent('removeListener', event)
+    return super.removeListener(event, listener)
+  }
+
+  /**
+   * 리스너를 큐 앞에 추가(EventEmitter `prependListener`). 동일 화이트리스트 검증(L-1).
+   * @param {'run'|'skip'|'done'|'fail'} event @param {(payload: any) => void} listener @returns {this}
+   * @throws {RangeError} 알 수 없는 이벤트명일 때.
+   */
+  prependListener(event, listener) {
+    this.#assertKnownEvent('prependListener', event)
+    return super.prependListener(event, listener)
+  }
+
+  /**
+   * 1회성 리스너를 큐 앞에 추가(EventEmitter `prependOnceListener`). 동일 화이트리스트 검증(L-1).
+   * @param {'run'|'skip'|'done'|'fail'} event @param {(payload: any) => void} listener @returns {this}
+   * @throws {RangeError} 알 수 없는 이벤트명일 때.
+   */
+  prependOnceListener(event, listener) {
+    this.#assertKnownEvent('prependOnceListener', event)
+    return super.prependOnceListener(event, listener)
+  }
+
+  /**
+   * 스케줄 클래스를 등록한다(아직 실행 안 함 — {@link MegaScheduler#start} 가 타이머를 건다).
+   * cron 표현식·lock 설정을 즉시 검증해 잘못된 등록은 부팅 시점에 드러낸다(추측 진행 금지).
+   *
+   * @param {typeof MegaSchedule} ScheduleClass - `MegaSchedule` 를 상속한 클래스.
+   * @returns {this} 체이닝용.
+   * @throws {TypeError} MegaSchedule 서브클래스가 아니거나 cron 이 비었을 때.
+   * @throws {Error} cron 표현식 무효, 이름 중복, lock 설정 형식 오류 시.
+   */
+  register(ScheduleClass) {
+    if (typeof ScheduleClass !== 'function' || !(ScheduleClass.prototype instanceof MegaSchedule)) {
+      throw new TypeError('MegaScheduler.register(C) — C must be a subclass of MegaSchedule.')
+    }
+    const name = ScheduleClass.name
+    if (typeof name !== 'string' || name.length === 0) {
+      throw new TypeError('MegaScheduler.register(C) — schedule class must have a non-empty name.')
+    }
+    if (this.#jobs.has(name)) {
+      throw new Error(`MegaScheduler.register: schedule '${name}' is already registered.`)
+    }
+    const cron = ScheduleClass.cron
+    if (typeof cron !== 'string' || cron.trim() === '') {
+      throw new TypeError(
+        `MegaScheduler.register('${name}') — static cron must be a non-empty string.`,
+      )
+    }
+    const timezone = ScheduleClass.timezone
+    // cron + timezone 정합을 즉시 검증(무효면 throw).
+    MegaCron.validate(cron, { timezone })
+    // timezone 미지정/빈 문자열 → 호스트 로컬 시각 폴백(환경 의존). 부팅 시 1회 경고(L-3).
+    if (typeof timezone !== 'string' || timezone.trim() === '') {
+      console.warn(
+        `[mega-schedule] '${name}' has no static timezone — falling back to host local time. ` +
+          `Set 'static timezone = "Asia/Seoul"' (IANA) to avoid environment-dependent behavior.`,
+      )
+    }
+
+    const lock = ScheduleClass.lock
+    if (lock !== undefined) {
+      this.#assertLockConfig(name, lock)
+      // lock 별명을 부팅 시점에 해석해 미선언 별명을 fail-fast(M-1). ctx.lock 미주입이면 이 시점엔
+      // 검증 불가 — fire 시 fail(lock-setup) 로 표면화(기존 계약 유지).
+      this.#assertLockAliasDeclared(name, lock.lock)
+    }
+
+    const instance = new ScheduleClass()
+    this.#jobs.set(name, { name, ScheduleClass, instance, cron, timezone, lock, job: null })
+    return this
+  }
+
+  /**
+   * lock 설정 형식 검증(fail-fast). lock 도메인 ttl 은 **밀리초 양의 정수**(어댑터 `_assertLockTtl` 정합).
+   * @param {string} name @param {any} lock @returns {void}
+   */
+  #assertLockConfig(name, lock) {
+    if (lock === null || typeof lock !== 'object') {
+      throw new Error(
+        `MegaScheduler.register('${name}') — static lock must be an object { lock, ttl, key? }.`,
+      )
+    }
+    if (typeof lock.lock !== 'string' || lock.lock.length === 0) {
+      throw new Error(
+        `MegaScheduler.register('${name}') — lock.lock must be a non-empty string (the ctx.lock(alias) name).`,
+      )
+    }
+    if (typeof lock.ttl !== 'number' || !Number.isInteger(lock.ttl) || lock.ttl <= 0) {
+      throw new Error(
+        `MegaScheduler.register('${name}') — lock.ttl must be a positive integer (milliseconds). Got: ${lock.ttl}.`,
+      )
+    }
+    if (lock.key !== undefined && (typeof lock.key !== 'string' || lock.key.length === 0)) {
+      throw new Error(
+        `MegaScheduler.register('${name}') — lock.key, if set, must be a non-empty string.`,
+      )
+    }
+  }
+
+  /**
+   * lock 별명이 ctx 에 선언돼 있는지 부팅 시점에 검증한다(M-1 fail-fast). `ctx.lock(alias)` 를 1회
+   * 호출해 미선언 별명이면 즉시 throw — 잘못된 별명 오타가 **첫 cron 트리거 때(타이머·호출자 없음)** 까지
+   * 숨지 않게 한다. ctx.lock 이 미주입(스케줄러가 lock 없이 생성)이면 이 시점엔 검증할 수 없으므로
+   * 건너뛴다 — 그 경우는 fire 시 `fail(lock-setup)` 으로 표면화된다(`#fire` 의 동일 가드).
+   * @param {string} name @param {string} alias @returns {void}
+   * @throws {MegaConfigError} ctx.lock 이 있는데 별명이 미선언일 때.
+   */
+  #assertLockAliasDeclared(name, alias) {
+    const ctx = this.#ctx
+    if (!ctx || typeof ctx.lock !== 'function') return // 미주입 — fire 시 fail(lock-setup) 로 처리.
+    try {
+      ctx.lock(alias) // 미선언 별명이면 ctx-builder 가 throw(MegaConfigError) — 부팅에서 잡는다.
+    } catch (e) {
+      const cause = e instanceof Error ? e : new Error(String(e))
+      throw new MegaConfigError(
+        'schedule.unknown_lock_alias',
+        `MegaScheduler.register('${name}') — lock alias '${alias}' is not a declared lock adapter. ` +
+          `Declare it in the app's locks config (ctx.lock('${alias}') failed: ${cause.message}).`,
+        { details: { schedule: name, alias }, cause },
+      )
+    }
+  }
+
+  /**
+   * 등록된 모든 스케줄에 croner 타이머를 걸어 cron 시각마다 자동 실행한다. 이미 start 된 스케줄은 건너뛴다.
+   *
+   * croner 옵션: `protect`(같은 인스턴스에서 이전 실행이 안 끝났으면 새 트리거 차단 — 단일 프로세스 overrun
+   * 방지), `unref`(타이머가 프로세스 종료를 막지 않음 — graceful/테스트), `catch`(타이머 콜백의 미처리
+   * 에러를 `fail` 이벤트로 라우팅 — unhandled rejection 방지).
+   *
+   * @returns {this} 체이닝용.
+   */
+  start() {
+    for (const job of this.#jobs.values()) {
+      if (job.job !== null) continue // 이미 스케줄됨.
+      job.job = new Cron(
+        job.cron,
+        {
+          name: job.name,
+          timezone: job.timezone,
+          protect: true,
+          unref: true,
+          catch: (/** @type {unknown} */ e) => {
+            const error = e instanceof Error ? e : new Error(String(e))
+            this.emit('fail', { name: job.name, error, phase: 'timer' })
+          },
+        },
+        // croner 콜백은 void|Promise<void> 계약 — #fire 결과는 버리고(이벤트로 이미 노출) await 만 한다.
+        async () => {
+          await this.#fire(job.name)
+        },
+      )
+    }
+    this.#started = true
+    return this
+  }
+
+  /**
+   * 모든 스케줄 타이머를 영구 중단한다(graceful shutdown 필수 — 안 부르면 타이머가 프로세스 종료를
+   * 늦출 수 있다). croner `stop()` 후엔 같은 인스턴스를 resume 할 수 없어, job 핸들을 비우고 재 start 시
+   * 새로 만든다. 진행 중인 run(ctx) 은 중단하지 않는다(완료까지 대기는 호출부 책임).
+   * @returns {this} 체이닝용.
+   */
+  stop() {
+    for (const job of this.#jobs.values()) {
+      if (job.job !== null) {
+        job.job.stop()
+        job.job = null
+      }
+    }
+    this.#started = false
+    return this
+  }
+
+  /**
+   * 스케줄을 **지금 즉시** 한 번 실행한다(cron 시각 무시). 분산 중복방지 로직은 그대로 적용된다 —
+   * 테스트·운영 수동 트리거·CLI 용.
+   *
+   * ⚠️ overlap: lock 미사용 스케줄은 `runNow` 호출 시 croner 의 자동 트리거와 **동일 프로세스 내에서
+   * overlap** 할 수 있다(croner `protect` 는 타이머 트리거끼리만 막고 수동 `runNow` 는 막지 않는다).
+   * 분산/동일프로세스 중복방지가 필요한 작업은 `static lock` 을 선언하라(L-2).
+   * @param {string} name - 등록된 스케줄 클래스명.
+   * @returns {Promise<MegaScheduleFireResult>}
+   * @throws {Error} 등록되지 않은 name 일 때.
+   */
+  async runNow(name) {
+    if (!this.#jobs.has(name)) {
+      throw new Error(
+        `MegaScheduler.runNow('${name}') — not registered. Registered: [${
+          this.list()
+            .map((j) => j.name)
+            .join(', ') || '(none)'
+        }].`,
+      )
+    }
+    return this.#fire(name)
+  }
+
+  /**
+   * 등록된 스케줄 메타데이터 목록. 모니터링/CLI 용.
+   * @returns {Array<{ name: string, cron: string, timezone: string|undefined, hasLock: boolean, nextRun: Date }>}
+   */
+  list() {
+    return [...this.#jobs.values()].map((j) => ({
+      name: j.name,
+      cron: j.cron,
+      timezone: j.timezone,
+      hasLock: j.lock !== undefined,
+      nextRun: MegaCron.next(j.cron, undefined, { timezone: j.timezone }),
+    }))
+  }
+
+  /** @returns {boolean} start() 된 상태면 true. */
+  get isStarted() {
+    return this.#started
+  }
+
+  /**
+   * 스케줄 1회 실행(락 중복방지 포함). 절대 throw 하지 않는다 — 결과/실패를 이벤트 + 반환 객체로 알린다
+   * (타이머 콜백에서 호출되므로 unhandled rejection 을 만들지 않기 위함).
+   * @param {string} name @returns {Promise<MegaScheduleFireResult>}
+   */
+  async #fire(name) {
+    const job = /** @type {ScheduleEntry} */ (this.#jobs.get(name))
+    const { instance, lock } = job
+    const ctx = this.#ctx
+
+    if (!lock) {
+      return this.#runBody(name, instance, ctx, undefined)
+    }
+
+    // 분산 중복방지 — lock 어댑터 해석.
+    if (!ctx || typeof ctx.lock !== 'function') {
+      // 설정 오류(lock 선언했는데 ctx.lock 없음)는 묵히지 않고 fail 로 표면화.
+      const error = new Error(
+        `MegaScheduler: schedule '${name}' declares static lock but ctx.lock(alias) is unavailable. Pass { ctx } with a lock accessor.`,
+      )
+      this.emit('fail', { name, error, phase: 'lock-setup' })
+      return { name, ran: false, skipped: false, ok: false, error }
+    }
+
+    // register 가 부팅 시 별명을 이미 검증하므로 정상 경로에선 throw 안 함. 그래도 #fire 의 불변식
+    // ("절대 throw 안 함")을 지키기 위해 방어적으로 감싼다 — 형제 케이스(ctx.lock 미주입)와 동일하게
+    // fail(lock-setup) 로 표면화한다(M-1: line 354 가 try/catch 밖이라 throw 가 새던 문제 해소).
+    let adapter
+    try {
+      adapter = ctx.lock(lock.lock)
+    } catch (e) {
+      const error = e instanceof Error ? e : new Error(String(e))
+      this.emit('fail', { name, error, phase: 'lock-setup' })
+      return { name, ran: false, skipped: false, ok: false, error }
+    }
+    const key = lock.key ?? `mega:schedule:${name}`
+
+    let held
+    try {
+      // 단 한 번 시도(retryCount: 0). 실패=이미 누가 보유(또는 backend 장애) → skip.
+      held = await adapter.acquire(key, { ttl: lock.ttl, retryCount: 0 })
+    } 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' })
+      }
+    }
+  }
+
+  /**
+   * run(ctx) 실행 본문 — run/done/fail 이벤트 발화 + 결과 객체 구성. throw 하지 않는다.
+   * @param {string} name @param {MegaSchedule} instance @param {Record<string, any>|null} ctx
+   * @param {string|undefined} key @returns {Promise<MegaScheduleFireResult>}
+   */
+  async #runBody(name, instance, ctx, key) {
+    this.emit('run', { name, key })
+    try {
+      const result = await instance.run(ctx ?? {})
+      this.emit('done', { name, key })
+      return { name, ran: true, skipped: false, ok: true, result }
+    } catch (e) {
+      const error = e instanceof Error ? e : new Error(String(e))
+      this.emit('fail', { name, key, error, phase: 'run' })
+      return { name, ran: true, skipped: false, ok: false, error }
+    }
+  }
+}