mega-framework 0.1.0

package/src/lib/mega-worker.js

@@ -0,0 +1,653 @@
+// @ts-check
+/**
+ * MegaWorker — CPU-heavy 계산을 격리 실행하는 **워커 풀** (정본, ADR-121/124).
+ *
+ * # ⚠️ `MegaJobWorker`(잡 소비 런타임)와 전혀 다른 추상 (ADR-120/121)
+ *   {@link import('./mega-job-worker.js').MegaJobWorker} 는 NATS 잡을 **자동 소비**하는 IO-bound 런타임이고,
+ *   본 `MegaWorker` 는 CPU-bound 작업을 스레드/프로세스 풀로 **격리**해 `ctx.workers.<name>.run(task)` 로
+ *   **명시 호출**한다. 이름이 비슷할 뿐 역할이 정반대다(잡 소비 vs CPU 격리). 03-api-spec §6 정본.
+ *
+ * # 설계 결정 (ADR-124 — 사용자 확정: 추천안 + thread/process 양쪽)
+ *   - **작업 로직 = `static taskFile`** 의 별도 모듈에 **named export 한 async 함수**(Piscina/workerpool
+ *     업계 표준). worker_threads/child_process 는 별도 파일을 실행하고 함수/클로저를 경계 너머로 넘길 수
+ *     없어(structured clone/IPC 는 데이터만), 서브클래스 메서드 인라인 대신 파일 경로가 불가피하다.
+ *     정본 §6 의 `async run(task)` 인라인 스케치는 본 패턴으로 갱신(ADR-124).
+ *   - **`static mode = 'thread' | 'process'`** — 둘 다 구현. thread=`worker_threads`(가벼움, 같은
+ *     프로세스 메모리 격리), process=`child_process.fork`(완전 격리, 더 무거움). 둘 다 node 빌트인(의존성 0).
+ *   - **풀 정책** — `static poolSize`(디폴트 `os.cpus().length - 1`, 최소 1). 작업 큐 + 가용 워커에 디스패치.
+ *   - **crash 자동 재시작** — 워커가 예기치 않게 죽으면 in-flight task 를 `worker.crashed` 로 reject 하고
+ *     `static maxRestarts`(디폴트 5)까지 교체 워커를 띄운다(MegaJobWorker M-1 패턴 정합).
+ *   - **graceful shutdown** — `stop()`: 새 `run()` 거부 + 큐 대기분 `worker.stopped` reject + in-flight 완료
+ *     대기(allSettled) → 워커 terminate. `MegaShutdown` 통합은 workers-manager 가 배선.
+ *
+ * @example
+ * // workers/image-tasks.js (= static taskFile) — named export 한 async 함수.
+ * export async function resize({ src, dst, width }) { ...CPU... ; return out }
+ *
+ * class ImageProcessor extends MegaWorker {
+ *   static name = 'image-processor'
+ *   static taskFile = './workers/image-tasks.js'
+ *   static mode = 'thread'
+ *   static poolSize = 4
+ * }
+ * // 부팅 시 ctx.workers['image-processor'] 자동 배선(workers-manager).
+ * const out = await ctx.workers['image-processor'].run('resize', { src, dst, width })
+ *
+ * @module lib/mega-worker
+ * @see ADR-124, ADR-121, 03-api-spec §6
+ */
+import { EventEmitter } from 'node:events'
+import os from 'node:os'
+import { Worker } from 'node:worker_threads'
+import { fork } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { isAbsolute, resolve as resolvePath } from 'node:path'
+import { MegaError } from '../errors/mega-error.js'
+import { MegaConfigError } from '../errors/config-error.js'
+
+/** 워커가 방출하는 이벤트 화이트리스트(형제 MegaJobWorker 정책). */
+const KNOWN_EVENTS = Object.freeze(['dispatch', 'done', 'fail', 'crash', 'stopped'])
+
+/** mode 별 워커 진입점(번들된 generic 러너 — 사용자 taskFile 을 로드해 메시지 루프 구동). */
+const THREAD_ENTRY = new URL('./worker-runner/thread-entry.js', import.meta.url)
+const PROCESS_ENTRY = fileURLToPath(new URL('./worker-runner/process-entry.js', import.meta.url))
+
+/** poolSize 디폴트 — 코어 수 - 1(메인 스레드 여유), 최소 1. */
+const DEFAULT_POOL_SIZE = Math.max(1, os.cpus().length - 1)
+/** crash 시 풀 전체에서 허용하는 교체 워커 재시작 총량 디폴트. */
+const DEFAULT_MAX_RESTARTS = 5
+
+/**
+ * @typedef {object} WorkerHandle - 풀 안의 워커 1개 핸들.
+ * @property {number} id - 핸들 식별자(로그/디버그).
+ * @property {Worker | import('node:child_process').ChildProcess} native - 실제 thread/process.
+ * @property {number | null} current - 처리 중인 taskId(없으면 null).
+ * @property {boolean} down - 종료/크래시 처리됨(중복 처리 가드).
+ */
+
+/**
+ * @typedef {object} WorkerTask - 디스패치 대기/진행 중인 task 1건.
+ * @property {number} taskId
+ * @property {string} taskName
+ * @property {any} args
+ * @property {{ timeoutMs?: number }} opts
+ * @property {(value: any) => void} resolve
+ * @property {(err: Error) => void} reject
+ * @property {WorkerHandle | null} handle - 배정된 워커(미배정 null).
+ * @property {ReturnType<typeof setTimeout> | null} timer - 타임아웃 타이머.
+ * @property {boolean} isSettled
+ * @property {(() => void) | null} _notify - stop() 의 완료 대기 깨우기.
+ */
+
+/**
+ * CPU 워커 풀. 서브클래스가 `static name`/`static taskFile`/`static mode`/`static poolSize` 를 선언하고,
+ * 호출자는 `run(taskName, args, opts)` 로 task 를 디스패치한다.
+ */
+export class MegaWorker extends EventEmitter {
+  /** @type {string} taskFile 상대경로 해석 기준. */ #projectRoot
+  /** @type {string} 해석된 taskFile 절대경로. */ #taskFile
+  /** @type {WorkerHandle[]} 전체 워커. */ #pool = []
+  /** @type {WorkerHandle[]} 유휴 워커(디스패치 가능). */ #idle = []
+  /** @type {WorkerTask[]} 디스패치 대기 큐. */ #queue = []
+  /** @type {Map<number, WorkerTask>} taskId → 진행 중 task. */ #inflight = new Map()
+  /** @type {boolean} */ #started = false
+  /** @type {boolean} */ #stopping = false
+  /** @type {number} */ #nextTaskId = 1
+  /** @type {number} */ #nextHandleId = 1
+  /** @type {number} crash 교체 누적. */ #restarts = 0
+  /** @type {number} 진행 중인 교체 spawn 수(일시적 풀 0 상태에서 run 을 큐잉할지 판단). */ #pendingRespawns = 0
+
+  /**
+   * @param {object} [args]
+   * @param {string} [args.projectRoot] - `static taskFile` 상대경로 해석 기준(디폴트 process.cwd()).
+   * @throws {MegaConfigError} static 설정(taskFile/mode/poolSize)이 잘못됐을 때 — 부팅 fail-fast.
+   */
+  constructor({ projectRoot } = {}) {
+    super()
+    this.#projectRoot = projectRoot ?? process.cwd()
+    // 잘못된 static 설정은 생성(=부팅) 시점에 즉시 드러낸다(fail-fast — 형제 register 패턴).
+    this.#taskFile = this.#resolveTaskFile()
+    this.#assertMode()
+    this.#assertPoolSize()
+    this.#assertMaxRestarts()
+  }
+
+  // ── static 설정 접근자 ─────────────────────────────────────────────────────
+
+  /** @returns {string} 등록 키(= `static name` 오버라이드 또는 클래스명). */
+  get name() {
+    return /** @type {any} */ (this.constructor).name
+  }
+
+  /** @returns {'thread' | 'process'} 실행 모드(디폴트 'thread'). */
+  get mode() {
+    return /** @type {any} */ (this.constructor).mode ?? 'thread'
+  }
+
+  /** @returns {number} 풀 크기. */
+  get poolSize() {
+    const p = /** @type {any} */ (this.constructor).poolSize
+    return typeof p === 'number' ? p : DEFAULT_POOL_SIZE
+  }
+
+  /** @returns {number} crash 교체 허용 총량. */
+  get maxRestarts() {
+    const r = /** @type {any} */ (this.constructor).maxRestarts
+    return Number.isInteger(r) && r >= 0 ? r : DEFAULT_MAX_RESTARTS
+  }
+
+  /** @returns {boolean} start() 후 stop() 전이면 true. */
+  get isStarted() {
+    return this.#started
+  }
+
+  // ── static 설정 검증(생성 시점 fail-fast) ──────────────────────────────────
+
+  /** @returns {string} 해석된 taskFile 절대경로. @throws {MegaConfigError} */
+  #resolveTaskFile() {
+    const tf = /** @type {any} */ (this.constructor).taskFile
+    if (typeof tf !== 'string' || tf.trim() === '') {
+      throw new MegaConfigError(
+        'worker.missing_task_file',
+        `MegaWorker '${this.name}' — static taskFile must be a non-empty string (the worker entry module that named-exports task functions).`,
+        { details: { worker: this.name } },
+      )
+    }
+    return isAbsolute(tf) ? tf : resolvePath(this.#projectRoot, tf)
+  }
+
+  /** @throws {MegaConfigError} mode 가 'thread'/'process' 가 아닐 때. */
+  #assertMode() {
+    const m = this.mode
+    if (m !== 'thread' && m !== 'process') {
+      throw new MegaConfigError(
+        'worker.invalid_mode',
+        `MegaWorker '${this.name}' — static mode must be 'thread' or 'process', got '${m}'.`,
+        { details: { worker: this.name, mode: m } },
+      )
+    }
+  }
+
+  /** @throws {MegaConfigError} poolSize 가 양의 정수가 아닐 때. */
+  #assertPoolSize() {
+    const p = /** @type {any} */ (this.constructor).poolSize
+    if (p !== undefined && (!Number.isInteger(p) || p < 1)) {
+      throw new MegaConfigError(
+        'worker.invalid_pool_size',
+        `MegaWorker '${this.name}' — static poolSize must be a positive integer, got ${p}.`,
+        { details: { worker: this.name, poolSize: p } },
+      )
+    }
+  }
+
+  /** @throws {MegaConfigError} maxRestarts 가 음이 아닌 정수가 아닐 때. */
+  #assertMaxRestarts() {
+    const r = /** @type {any} */ (this.constructor).maxRestarts
+    if (r !== undefined && (!Number.isInteger(r) || r < 0)) {
+      throw new MegaConfigError(
+        'worker.invalid_max_restarts',
+        `MegaWorker '${this.name}' — static maxRestarts must be a non-negative integer, got ${r}.`,
+        { details: { worker: this.name, maxRestarts: r } },
+      )
+    }
+  }
+
+  // ── 이벤트 화이트리스트(형제 MegaJobWorker 정책) ──────────────────────
+
+  /** @param {string} method @param {string} event @throws {RangeError} */
+  #assertKnownEvent(method, event) {
+    if (!KNOWN_EVENTS.includes(event)) {
+      throw new RangeError(
+        `MegaWorker.${method}('${event}', ...) — unknown event. Known: ${KNOWN_EVENTS.join(', ')}.`,
+      )
+    }
+  }
+
+  /** @param {'dispatch'|'done'|'fail'|'crash'|'stopped'} event @param {(payload: any) => void} listener @returns {this} */
+  on(event, listener) {
+    this.#assertKnownEvent('on', event)
+    return super.on(event, listener)
+  }
+
+  /** @param {'dispatch'|'done'|'fail'|'crash'|'stopped'} event @param {(payload: any) => void} listener @returns {this} */
+  once(event, listener) {
+    this.#assertKnownEvent('once', event)
+    return super.once(event, listener)
+  }
+
+  /** @param {'dispatch'|'done'|'fail'|'crash'|'stopped'} event @param {(payload: any) => void} listener @returns {this} */
+  off(event, listener) {
+    this.#assertKnownEvent('off', event)
+    return super.off(event, listener)
+  }
+
+  // ── 라이프사이클 ───────────────────────────────────────────────────────────
+
+  /**
+   * 워커 풀을 띄운다(`poolSize` 개). 각 워커가 taskFile 을 로드해 `{ ready:true }` 를 보낼 때까지 대기한다
+   * (race 방지). 멱등 — 이미 start 됐으면 무시. taskFile 로드 실패는 spawn 핸드셰이크에서 fail-fast.
+   * @returns {Promise<this>}
+   * @throws {MegaError} 전원 spawn 실패 시 근본 원인(`worker.spawn_failed`)을 전파. 풀 **일부만** 떠도
+   *   성공분을 terminate 한 뒤 `worker.start_partial` 로 fail-fast(M-1 — 누수 방지).
+   */
+  async start() {
+    if (this.#started) return this
+    // M-1: Promise.all 은 첫 reject 시 즉시 끝나 **이미 spawn 된 다른 워커가 누수**(terminate 안 됨)된다.
+    //   allSettled 로 전부 기다린 뒤, 하나라도 실패하면 성공분을 정리(terminate)하고 fail-fast 한다.
+    const results = await Promise.allSettled(
+      Array.from({ length: this.poolSize }, () => this.#spawn()),
+    )
+    /** @type {WorkerHandle[]} */
+    const handles = []
+    /** @type {unknown[]} */
+    const errors = []
+    for (const r of results) {
+      if (r.status === 'fulfilled') handles.push(r.value)
+      else errors.push(r.reason)
+    }
+    if (handles.length < this.poolSize) {
+      // 성공분을 terminate 해 누수 막는다(M-1 핵심 — 일부만 떴을 때만 실제 누수가 생긴다).
+      await Promise.allSettled(handles.map((h) => this.#terminate(h)))
+      if (handles.length === 0) {
+        // 전원 실패는 "부분(partial)" 이 아니다 — 근본 원인(spawn 에러)을 그대로 전파한다(정확성).
+        //   #spawn 은 항상 MegaError('worker.spawn_failed') 로 reject 하므로 그 코드가 보존된다.
+        throw errors[0]
+      }
+      // 일부만 떴음 → 풀 불완전(genuine partial). fail-fast.
+      throw new MegaError(
+        'worker.start_partial',
+        `MegaWorker '${this.name}' — worker pool spawn partial failure (${handles.length}/${this.poolSize}).`,
+        {
+          details: { worker: this.name, spawned: handles.length, poolSize: this.poolSize },
+          cause: errors[0],
+        },
+      )
+    }
+    for (const h of handles) {
+      this.#pool.push(h)
+      this.#idle.push(h)
+    }
+    this.#started = true
+    return this
+  }
+
+  /**
+   * task 를 워커에 디스패치한다. 유휴 워커가 있으면 즉시, 없으면 큐 대기 후 가용 시 디스패치.
+   * @param {string} taskName - taskFile 이 export 한 함수명.
+   * @param {any} [args] - 함수 인자(structured clone/IPC 가능한 데이터만 — 함수·클래스 인스턴스 X). 직렬화
+   *   불가 인자는 디스패치 시점에 `worker.invalid_args` 로 reject 된다(fail-fast — H-1/M-2, ADR-124 보강).
+   * @param {{ timeoutMs?: number }} [opts] - timeoutMs 초과 시 `worker.task_timeout` reject + 워커 교체.
+   * @returns {Promise<any>} task 함수 반환값.
+   * @throws {MegaError} not_started / stopped / invalid_task / pool_exhausted (즉시 reject) /
+   *   invalid_args (직렬화 불가 인자 — 디스패치 시점 reject).
+   */
+  run(taskName, args, opts = {}) {
+    // stopping 을 not_started 보다 먼저 본다 — stop() 이 #started=false 로 만들지만, 중단된 워커의 run 은
+    // "not started" 가 아니라 "stopped" 가 의미상 맞다(#stopping 은 stop 후 계속 true).
+    if (this.#stopping) {
+      return Promise.reject(
+        new MegaError('worker.stopped', `MegaWorker '${this.name}' — run() after stop().`, {
+          details: { worker: this.name },
+        }),
+      )
+    }
+    if (!this.#started) {
+      return Promise.reject(
+        new MegaError('worker.not_started', `MegaWorker '${this.name}' — run() before start().`, {
+          details: { worker: this.name },
+        }),
+      )
+    }
+    if (typeof taskName !== 'string' || taskName.trim() === '') {
+      return Promise.reject(
+        new MegaError('worker.invalid_task', `MegaWorker '${this.name}' — taskName must be a non-empty string.`, {
+          details: { worker: this.name },
+        }),
+      )
+    }
+    if (this.#pool.length === 0 && this.#pendingRespawns === 0) {
+      // 모든 워커가 죽고 교체도 진행 중이 아님(한도 소진) → 더는 처리 불가. 교체가 진행 중이면(아래)
+      // 큐잉만 하고 respawn 이 완료되면 pump 가 집어간다(일시적 풀 0 race 를 pool_exhausted 로 오인하지 않음).
+      return Promise.reject(
+        new MegaError('worker.pool_exhausted', `MegaWorker '${this.name}' — no live workers (pool exhausted).`, {
+          details: { worker: this.name },
+        }),
+      )
+    }
+    return new Promise((resolve, reject) => {
+      /** @type {WorkerTask} */
+      const task = {
+        taskId: this.#nextTaskId++,
+        taskName,
+        args,
+        opts: opts ?? {},
+        resolve: (v) => {
+          task.isSettled = true
+          resolve(v)
+          task._notify?.()
+        },
+        reject: (e) => {
+          task.isSettled = true
+          reject(e)
+          task._notify?.()
+        },
+        handle: null,
+        timer: null,
+        isSettled: false,
+        _notify: null,
+      }
+      this.#queue.push(task)
+      this.#pump()
+    })
+  }
+
+  /**
+   * graceful shutdown — 새 run() 거부 + 큐 대기분 `worker.stopped` reject + in-flight 완료 대기 → terminate.
+   * `MegaShutdown` 정리 경로에서 호출된다(workers-manager 가 `register('workers:stop', ...)` 배선).
+   * @returns {Promise<this>}
+   */
+  async stop() {
+    this.#stopping = true
+    // 1) 아직 시작 안 한 큐 대기분은 즉시 reject(in-flight 만 완료 대기 — stop 시간 bound).
+    for (const task of this.#queue.splice(0)) {
+      task.reject(
+        new MegaError('worker.stopped', `MegaWorker '${this.name}' stopped before task '${task.taskName}' started.`, {
+          details: { worker: this.name, taskName: task.taskName },
+        }),
+      )
+    }
+    // 2) in-flight 완료 대기 — 각 task settle 시 _notify 로 깨운다.
+    const waits = [...this.#inflight.values()].map(
+      (t) =>
+        new Promise((res) => {
+          t._notify = /** @type {() => void} */ (res)
+          if (t.isSettled) res(undefined)
+        }),
+    )
+    await Promise.allSettled(waits)
+    // 3) 워커 terminate(중복 down 가드 후).
+    await Promise.allSettled(this.#pool.map((h) => this.#terminate(h)))
+    this.#pool = []
+    this.#idle = []
+    this.#started = false
+    this.emit('stopped', { worker: this.name })
+    return this
+  }
+
+  // ── 내부: 디스패치 / 풀 관리 ───────────────────────────────────────────────
+
+  /** 큐와 유휴 워커가 둘 다 있으면 배정한다. */
+  #pump() {
+    while (this.#queue.length > 0 && this.#idle.length > 0) {
+      const task = /** @type {WorkerTask} */ (this.#queue.shift())
+      const handle = /** @type {WorkerHandle} */ (this.#idle.shift())
+      this.#assign(handle, task)
+    }
+  }
+
+  /** @param {WorkerHandle} handle @param {WorkerTask} task */
+  #assign(handle, task) {
+    handle.current = task.taskId
+    task.handle = handle
+    this.#inflight.set(task.taskId, task)
+    if (typeof task.opts.timeoutMs === 'number' && task.opts.timeoutMs > 0) {
+      const timer = setTimeout(() => this.#onTimeout(handle, task), task.opts.timeoutMs)
+      timer.unref()
+      task.timer = timer
+    }
+    try {
+      // ⚠️ H-1/M-2: 직렬화 불가 인자(함수·클래스 인스턴스 등)는 #send 가 **동기 throw** 한다
+      //   (thread=structured clone DataCloneError, process=advanced serialization Error — 둘 다 실측 확인).
+      //   롤백 없이 두면 좀비 task 가 #inflight 에 영원히 남아 stop() 이 in-flight 대기에서 영구 hang(H-1).
+      //   → in-flight·timer·핸들을 원복하고 task 를 worker.invalid_args 로 명시 reject(fail-fast).
+      //   워커 자체는 멀쩡하므로 유휴로 되돌려 다음 큐를 계속 처리한다.
+      this.#send(handle, { id: task.taskId, taskName: task.taskName, args: task.args })
+    } catch (sendErr) {
+      this.#inflight.delete(task.taskId)
+      if (task.timer) {
+        clearTimeout(task.timer)
+        task.timer = null
+      }
+      handle.current = null
+      task.handle = null
+      // 핸들은 살아있으니 유휴 복귀(stop 중이면 복귀 안 함 — #release 와 동일 정책). 복귀하면 #pump 의
+      // while 가 다음 반복에서 이 핸들을 다시 집어 큐를 진행한다(여기서 재귀 #pump 호출은 불필요).
+      if (!this.#stopping) this.#idle.push(handle)
+      const reason = sendErr instanceof Error ? sendErr.message : String(sendErr)
+      task.reject(
+        new MegaError('worker.invalid_args', `MegaWorker '${this.name}' task '${task.taskName}' — arguments are not serializable: ${reason}`, {
+          details: { worker: this.name, taskName: task.taskName },
+          cause: sendErr,
+        }),
+      )
+      return
+    }
+    this.emit('dispatch', { worker: this.name, taskId: task.taskId, taskName: task.taskName })
+  }
+
+  /** 워커를 유휴로 되돌리고 다음 큐를 펌프한다. @param {WorkerHandle} handle */
+  #release(handle) {
+    handle.current = null
+    if (!this.#stopping) this.#idle.push(handle)
+    this.#pump()
+  }
+
+  /**
+   * 워커가 보낸 task 결과 메시지 처리. @param {WorkerHandle} handle @param {any} m `{ id, ok, result, error }`.
+   */
+  #onMessage(handle, m) {
+    if (!m || typeof m.id !== 'number') return // ready 등 비-task 메시지 무시.
+    const task = this.#inflight.get(m.id)
+    if (task === undefined) return
+    this.#inflight.delete(m.id)
+    if (task.timer) clearTimeout(task.timer)
+    this.#release(handle)
+    if (m.ok) {
+      this.emit('done', { worker: this.name, taskId: m.id, taskName: task.taskName })
+      task.resolve(m.result)
+    } else {
+      this.emit('fail', { worker: this.name, taskId: m.id, taskName: task.taskName, error: m.error })
+      task.reject(this.#rebuildError('worker.task_failed', task, m.error))
+    }
+  }
+
+  /**
+   * 워커가 예기치 않게 죽음(error/비정상 exit). in-flight reject + crash 이벤트 + 교체 재시작.
+   * @param {WorkerHandle} handle @param {Error} err
+   */
+  #onWorkerDown(handle, err) {
+    if (handle.down) return // error→exit 이중 발화 가드.
+    handle.down = true
+    this.#removeHandle(handle)
+    if (handle.current !== null) {
+      const task = this.#inflight.get(handle.current)
+      if (task) {
+        this.#inflight.delete(handle.current)
+        if (task.timer) clearTimeout(task.timer)
+        task.reject(
+          new MegaError('worker.crashed', `MegaWorker '${this.name}' worker crashed: ${err.message}`, {
+            details: { worker: this.name, taskName: task.taskName },
+            cause: err,
+          }),
+        )
+      }
+    }
+    this.emit('crash', { worker: this.name, error: err.message })
+    this.#scheduleRespawn()
+    this.#drainIfDead()
+  }
+
+  /** 비정상 exit 처리(정상 종료 code 0 는 stop 경로에서만 기대). @param {WorkerHandle} handle @param {number|null} code */
+  #onExit(handle, code) {
+    if (this.#stopping || handle.down) return // 종료 중 terminate 로 인한 exit 은 정상.
+    this.#onWorkerDown(handle, new Error(`worker exited unexpectedly (code ${code})`))
+  }
+
+  /** 타임아웃 — task reject + 멈춘 워커 교체. @param {WorkerHandle} handle @param {WorkerTask} task */
+  #onTimeout(handle, task) {
+    if (task.isSettled || !this.#inflight.has(task.taskId)) return
+    this.#inflight.delete(task.taskId)
+    task.reject(
+      new MegaError('worker.task_timeout', `MegaWorker '${this.name}' task '${task.taskName}' timed out after ${task.opts.timeoutMs}ms.`, {
+        details: { worker: this.name, taskName: task.taskName, timeoutMs: task.opts.timeoutMs },
+      }),
+    )
+    // 멈춘 워커는 회수 불가 — 교체로 처리(down 처리 + 재시작).
+    handle.down = true
+    this.#removeHandle(handle)
+    void this.#terminate(handle)
+    this.emit('crash', { worker: this.name, error: `task '${task.taskName}' timeout — worker recycled` })
+    this.#scheduleRespawn()
+    this.#drainIfDead()
+  }
+
+  /**
+   * crash/timeout 으로 죽은 워커를 교체한다 — 종료 중이 아니고 재시작 한도(`maxRestarts`) 내일 때만(
+   * M-1 패턴). spawn 은 비동기라 완료 시 풀에 넣고 pump. spawn 실패도 묵살하지 않는다(fail 이벤트).
+   * @returns {void}
+   */
+  #scheduleRespawn() {
+    if (this.#stopping || this.#restarts >= this.maxRestarts) return
+    this.#restarts++
+    this.#pendingRespawns++
+    this.#spawn()
+      .then((h) => {
+        this.#pendingRespawns--
+        if (this.#stopping) {
+          void this.#terminate(h)
+          return
+        }
+        this.#pool.push(h)
+        this.#release(h)
+      })
+      .catch((e) => {
+        this.#pendingRespawns--
+        this.emit('fail', { worker: this.name, error: `respawn failed: ${e?.message ?? e}` })
+        this.#drainIfDead()
+      })
+  }
+
+  /**
+   * 풀이 완전히 비고 교체 spawn 도 더 없으면(한도 소진/실패) 큐 대기 task 들을 `pool_exhausted` 로
+   * 비운다 — 영영 디스패치 안 될 task 가 hang 하지 않게(silent stall 금지).
+   * @returns {void}
+   */
+  #drainIfDead() {
+    if (this.#stopping) return
+    if (this.#pool.length === 0 && this.#pendingRespawns === 0) {
+      for (const task of this.#queue.splice(0)) {
+        task.reject(
+          new MegaError('worker.pool_exhausted', `MegaWorker '${this.name}' — pool exhausted (all workers died, no respawn left).`, {
+            details: { worker: this.name, taskName: task.taskName },
+          }),
+        )
+      }
+    }
+  }
+
+  /** @param {WorkerHandle} handle 풀·유휴 목록에서 제거. */
+  #removeHandle(handle) {
+    const pi = this.#pool.indexOf(handle)
+    if (pi !== -1) this.#pool.splice(pi, 1)
+    const ii = this.#idle.indexOf(handle)
+    if (ii !== -1) this.#idle.splice(ii, 1)
+  }
+
+  // ── 내부: thread/process 추상화 ────────────────────────────────────────────
+
+  /**
+   * 워커 1개를 띄우고 `{ ready:true }` 핸드셰이크까지 기다린다. 영속 리스너는 ready 후 부착.
+   * @returns {Promise<WorkerHandle>} @throws {MegaError} ready 전 죽으면 `worker.spawn_failed`.
+   */
+  async #spawn() {
+    /** @type {WorkerHandle} */
+    const handle = { id: this.#nextHandleId++, native: /** @type {any} */ (null), current: null, down: false }
+    const native =
+      this.mode === 'thread'
+        ? new Worker(THREAD_ENTRY, { workerData: { taskFile: this.#taskFile } })
+        : // serialization:'advanced' → IPC 가 V8 직렬화기를 써서 (1) thread 의 structured clone 과 동일하게
+          //   Date/Map/Set/BigInt 등을 보존하고, (2) 함수 등 직렬화 불가 인자에 process.send 가 **동기 throw**
+          //   한다(기본 json 은 함수를 silent drop → M-2 의 silent-wrong). 둘 다 #assign 의 try/catch 가 잡아
+          //   worker.invalid_args 로 fail-fast. 자식 채널 모드는 fork 시 자동 전파(NODE_CHANNEL_SERIALIZATION_MODE).
+          fork(PROCESS_ENTRY, [this.#taskFile], {
+            stdio: ['ignore', 'inherit', 'inherit', 'ipc'],
+            serialization: 'advanced',
+          })
+    handle.native = native
+
+    await new Promise((resolve, reject) => {
+      const onMsg = (/** @type {any} */ m) => {
+        if (m && m.ready) {
+          cleanup()
+          resolve(undefined)
+        }
+      }
+      const onErr = (/** @type {any} */ e) => {
+        cleanup()
+        reject(
+          new MegaError('worker.spawn_failed', `MegaWorker '${this.name}' worker failed to start: ${e?.message ?? e}`, {
+            details: { worker: this.name, taskFile: this.#taskFile },
+            cause: e instanceof Error ? e : new Error(String(e)),
+          }),
+        )
+      }
+      const onExit = (/** @type {any} */ code) => {
+        cleanup()
+        reject(
+          new MegaError('worker.spawn_failed', `MegaWorker '${this.name}' worker exited before ready (code ${code}).`, {
+            details: { worker: this.name, taskFile: this.#taskFile, code },
+          }),
+        )
+      }
+      const cleanup = () => {
+        native.removeListener('message', onMsg)
+        native.removeListener('error', onErr)
+        native.removeListener('exit', onExit)
+      }
+      native.on('message', onMsg)
+      native.on('error', onErr)
+      native.on('exit', onExit)
+    })
+
+    // 정상 가동 — 영속 리스너 부착.
+    native.on('message', (/** @type {any} */ m) => this.#onMessage(handle, m))
+    native.on('error', (/** @type {any} */ e) => this.#onWorkerDown(handle, e instanceof Error ? e : new Error(String(e))))
+    native.on('exit', (/** @type {any} */ code) => this.#onExit(handle, /** @type {number|null} */ (code)))
+    return handle
+  }
+
+  /** @param {WorkerHandle} handle @param {any} msg 부모→워커 메시지 전송(채널 추상화). */
+  #send(handle, msg) {
+    if (this.mode === 'thread') {
+      /** @type {Worker} */ (handle.native).postMessage(msg)
+    } else {
+      /** @type {import('node:child_process').ChildProcess} */ (handle.native).send(msg)
+    }
+  }
+
+  /** @param {WorkerHandle} handle 워커 종료(thread terminate / process kill). @returns {Promise<void>} */
+  async #terminate(handle) {
+    handle.down = true // terminate 로 인한 exit 을 crash 로 오인하지 않게.
+    if (this.mode === 'thread') {
+      await /** @type {Worker} */ (handle.native).terminate()
+    } else {
+      /** @type {import('node:child_process').ChildProcess} */ (handle.native).kill()
+    }
+  }
+
+  /**
+   * 워커가 직렬화해 보낸 error 를 MegaError 로 복원한다(name/message/stack/code 보존을 cause 로).
+   * @param {string} code @param {WorkerTask} task @param {{ name?: string, message?: string, stack?: string, code?: string }} [serialized]
+   * @returns {MegaError}
+   */
+  #rebuildError(code, task, serialized) {
+    const cause = new Error(serialized?.message ?? 'worker task failed')
+    if (serialized?.name) cause.name = serialized.name
+    if (serialized?.stack) cause.stack = serialized.stack
+    if (serialized?.code) /** @type {any} */ (cause).code = serialized.code
+    return new MegaError(code, `MegaWorker '${this.name}' task '${task.taskName}' failed: ${serialized?.message ?? 'unknown error'}`, {
+      details: { worker: this.name, taskName: task.taskName },
+      cause,
+    })
+  }
+}

package/src/lib/worker-runner/process-entry.js

@@ -0,0 +1,30 @@
+// @ts-check
+/**
+ * `child_process` 진입점 (mode:'process') — `MegaWorker` 가 `fork(process-entry, [taskFile], { ipc })` 로
+ * 띄운다 (ADR-124). thread-entry 와 동형이나 채널이 IPC(`process.send`/`process.on`)이고
+ * taskFile 을 `process.argv[2]` 로 받는다. 메모리·V8 완전 격리가 필요할 때 mode:'process' 를 쓴다(스레드보다
+ * 무겁지만 한 task 가 프로세스를 죽여도 나머지 격리).
+ *
+ * IPC 채널은 부모가 `serialization:'advanced'`(V8 직렬화기)로 fork 하므로 thread 의 structured clone 과
+ * 동일하게 Date/Map/Set/BigInt 등을 보존한다(자식 채널 모드는 `NODE_CHANNEL_SERIALIZATION_MODE` 로 자동
+ * 전파). 함수·심볼 등 직렬화 불가 값은 송신 시 동기 throw → 부모가 worker.invalid_args 로 fail-fast(ADR-124 보강).
+ *
+ * @module lib/worker-runner/process-entry
+ */
+import { loadTaskModule, handleTaskMessage } from './task-dispatch.js'
+
+const taskFile = process.argv[2]
+if (typeof taskFile !== 'string' || taskFile.length === 0) {
+  throw new Error('process-entry.js requires a taskFile path as argv[2].')
+}
+if (typeof process.send !== 'function') {
+  throw new Error('process-entry.js must be forked with an IPC channel (process.send is undefined).')
+}
+
+const send = process.send.bind(process)
+const mod = await loadTaskModule(taskFile)
+process.on('message', (msg) => {
+  void handleTaskMessage(mod, msg, send)
+})
+// 로드 완료 신호 — 부모는 이 메시지를 받고서야 task 를 디스패치한다(race 방지).
+send({ ready: true })