mega-framework 0.1.10 → 0.1.11

package/src/core/config-validator.js

@@ -11,7 +11,7 @@
  * @module core/config-validator
  */
 import { MegaConfigError } from '../errors/config-error.js'
-import { GLOBAL_ONLY_KEYS, APP_ONLY_KEYS, SHARED_REFERENCE_KEYS } from './scope-registry.js'
+import { GLOBAL_ONLY_KEYS, APP_ONLY_KEYS, SHARED_REFERENCE_KEYS, DUAL_SCOPE_KEYS } from './scope-registry.js'
 import { checkCompressionConfig } from './ws-compression.js'
 
 /**
@@ -81,6 +81,16 @@ export function validateGlobalConfig(globalConfig) {
     validateWsClusterConfig(globalConfig.wsCluster, globalConfig.services?.buses)
   }
 
+  // 4c) lock 검증 (ADR-226) — 분산 락 driver 자동폴백 + 기본 옵션. 잘못된 설정은 부팅 시 fail-fast.
+  if (globalConfig.lock !== undefined) {
+    validateLockConfig(globalConfig.lock, globalConfig.services?.caches)
+  }
+
+  // 4d) bus 검증 (ADR-227) — 메시지 버스 driver 자동폴백 + 기본 옵션. 잘못된 설정은 부팅 시 fail-fast.
+  if (globalConfig.bus !== undefined) {
+    validateBusConfig(globalConfig.bus, globalConfig.services?.buses)
+  }
+
   // 5) jobs / schedules / workers 명시 등록 배열 검증 (M-2 + ADR-124 / 04-data-models §1.1).
   //    GLOBAL_ONLY_KEYS 에 키만 등록돼 있고 shape 검증이 없어, `jobs: SendEmailJob`(배열 잊음)이나
   //    원소가 클래스 아닌 값이면 흡수 로직이 silent drop 했다. 부팅 시 fail-fast 로 드러낸다.
@@ -212,6 +222,103 @@ function validateWsClusterConfig(wsCluster, buses) {
   }
 }
 
+/** lock.driver 허용값 (ADR-226). */
+const LOCK_DRIVERS = Object.freeze(['auto', 'redis', 'cluster', 'memory'])
+
+/**
+ * `lock` config 검증 (ADR-226). 분산 락 manager 자동배선의 트리거라 잘못된 설정을 부팅 시 fail-fast 한다.
+ *  (1) object 여야 한다.
+ *  (2) `driver` 가 있으면 'auto'|'redis'|'cluster'|'memory' 중 하나.
+ *  (3) `ttl`/`waitMs` 가 있으면 음 아닌 정수(ttl 은 양의 정수, waitMs 는 0 이상).
+ *  (4) `fifo` 가 있으면 boolean.
+ *  (5) `cache` 가 있으면 string + `services.caches` 에 선언된 키(redis driver 가 빌릴 cache alias).
+ *
+ * @param {any} lock - globalConfig.lock.
+ * @param {Record<string, any>|undefined} caches - globalConfig.services.caches.
+ * @throws {MegaConfigError} 위 위반 시.
+ */
+function validateLockConfig(lock, caches) {
+  if (typeof lock !== 'object' || lock === null || Array.isArray(lock)) {
+    throw new MegaConfigError('config.lock_invalid', 'lock must be an object ({ driver?, ttl?, waitMs?, fifo?, cache? }).', {
+      details: { type: Array.isArray(lock) ? 'array' : typeof lock },
+    })
+  }
+  if (lock.driver !== undefined && !LOCK_DRIVERS.includes(lock.driver)) {
+    throw new MegaConfigError('config.lock_driver_invalid', `lock.driver must be one of [${LOCK_DRIVERS.join(', ')}], got '${lock.driver}'.`, {
+      details: { driver: lock.driver },
+    })
+  }
+  if (lock.ttl !== undefined && (!Number.isInteger(lock.ttl) || lock.ttl <= 0)) {
+    throw new MegaConfigError('config.lock_ttl_invalid', 'lock.ttl must be a positive integer (ms).', { details: { ttl: lock.ttl } })
+  }
+  if (lock.waitMs !== undefined && (!Number.isInteger(lock.waitMs) || lock.waitMs < 0)) {
+    throw new MegaConfigError('config.lock_waitms_invalid', 'lock.waitMs must be an integer >= 0 (ms, 0 = no wait).', { details: { waitMs: lock.waitMs } })
+  }
+  if (lock.fifo !== undefined && typeof lock.fifo !== 'boolean') {
+    throw new MegaConfigError('config.lock_fifo_invalid', 'lock.fifo must be a boolean.', { details: { fifo: lock.fifo } })
+  }
+  if (lock.cache !== undefined) {
+    if (typeof lock.cache !== 'string' || lock.cache.length === 0) {
+      throw new MegaConfigError('config.lock_cache_invalid', 'lock.cache must be a non-empty string (a global services.caches key).', { details: { cache: lock.cache } })
+    }
+    if (!caches?.[lock.cache]) {
+      throw new MegaConfigError(
+        'config.lock_cache_not_found',
+        `lock.cache '${lock.cache}' is not defined in services.caches. Declared: [${Object.keys(caches ?? {}).join(', ') || '(none)'}].`,
+        { details: { cache: lock.cache, declared: Object.keys(caches ?? {}) } },
+      )
+    }
+  }
+}
+
+/** bus.driver 허용값 (ADR-227). */
+const BUS_DRIVERS = Object.freeze(['auto', 'nats', 'cluster', 'memory'])
+
+/**
+ * `bus` config 검증 (ADR-227). 메시지 버스 manager 자동배선의 트리거라 잘못된 설정을 부팅 시 fail-fast 한다.
+ *  (1) object 여야 한다.
+ *  (2) `driver` 가 있으면 'auto'|'nats'|'cluster'|'memory' 중 하나.
+ *  (3) `prefix` 가 있으면 string.
+ *  (4) `defaultPersist` 가 있으면 boolean.
+ *  (5) `requestTimeoutMs` 가 있으면 양의 정수.
+ *  (6) `nats` 가 있으면 string + `services.buses` 에 선언된 키(nats driver 가 빌릴 버스 alias).
+ *
+ * @param {any} bus - globalConfig.bus.
+ * @param {Record<string, any>|undefined} buses - globalConfig.services.buses.
+ * @throws {MegaConfigError} 위 위반 시.
+ */
+function validateBusConfig(bus, buses) {
+  if (typeof bus !== 'object' || bus === null || Array.isArray(bus)) {
+    throw new MegaConfigError('config.bus_invalid', 'bus must be an object ({ driver?, nats?, prefix?, defaultPersist?, requestTimeoutMs? }).', {
+      details: { type: Array.isArray(bus) ? 'array' : typeof bus },
+    })
+  }
+  if (bus.driver !== undefined && !BUS_DRIVERS.includes(bus.driver)) {
+    throw new MegaConfigError('config.bus_driver_invalid', `bus.driver must be one of [${BUS_DRIVERS.join(', ')}], got '${bus.driver}'.`, { details: { driver: bus.driver } })
+  }
+  if (bus.prefix !== undefined && typeof bus.prefix !== 'string') {
+    throw new MegaConfigError('config.bus_prefix_invalid', 'bus.prefix must be a string (subject namespace, e.g. "app.").', { details: { prefix: bus.prefix } })
+  }
+  if (bus.defaultPersist !== undefined && typeof bus.defaultPersist !== 'boolean') {
+    throw new MegaConfigError('config.bus_persist_invalid', 'bus.defaultPersist must be a boolean.', { details: { defaultPersist: bus.defaultPersist } })
+  }
+  if (bus.requestTimeoutMs !== undefined && (!Number.isInteger(bus.requestTimeoutMs) || bus.requestTimeoutMs <= 0)) {
+    throw new MegaConfigError('config.bus_timeout_invalid', 'bus.requestTimeoutMs must be a positive integer (ms).', { details: { requestTimeoutMs: bus.requestTimeoutMs } })
+  }
+  if (bus.nats !== undefined) {
+    if (typeof bus.nats !== 'string' || bus.nats.length === 0) {
+      throw new MegaConfigError('config.bus_nats_invalid', 'bus.nats must be a non-empty string (a global services.buses key).', { details: { nats: bus.nats } })
+    }
+    if (!buses?.[bus.nats]) {
+      throw new MegaConfigError(
+        'config.bus_nats_not_found',
+        `bus.nats '${bus.nats}' is not defined in services.buses. Declared: [${Object.keys(buses ?? {}).join(', ') || '(none)'}].`,
+        { details: { nats: bus.nats, declared: Object.keys(buses ?? {}) } },
+      )
+    }
+  }
+}
+
 /**
  * `jobs`/`schedules`/`workers` 같은 "클래스(함수) 배열" config 키를 검증한다 (M-2/ADR-124). 미정의면
  * 통과(선택 키). 정의됐으면 (1) 배열이어야 하고 (2) 모든 원소가 함수(클래스)여야 한다 — 위반 시 부팅 fail-fast.
@@ -260,6 +367,7 @@ export function validateAppConfig(appConfig, expectedFolderName, globalConfig) {
   // 1) 알 수 없는 키 + 잘못된 스코프
   for (const key of Object.keys(appConfig)) {
     if (APP_ONLY_KEYS.includes(key)) continue
+    if (DUAL_SCOPE_KEYS.includes(key)) continue // lock/bus 는 글로벌·앱 양쪽 허용(ADR-229) — 아래서 shape 검증.
     if (GLOBAL_ONLY_KEYS.includes(key)) {
       throw new MegaConfigError(
         'config.wrong_scope',
@@ -290,6 +398,15 @@ export function validateAppConfig(appConfig, expectedFolderName, globalConfig) {
     )
   }
 
+  // 2a) 앱별 lock/bus(ADR-229) — 글로벌과 같은 shape 규칙. cache/nats 는 **글로벌 services** 의 키를 참조한다
+  //     (services 는 글로벌 정의라 앱 lock.cache/bus.nats 도 globalConfig.services 를 본다).
+  if (appConfig.lock !== undefined) {
+    validateLockConfig(appConfig.lock, globalConfig?.services?.caches)
+  }
+  if (appConfig.bus !== undefined) {
+    validateBusConfig(appConfig.bus, globalConfig?.services?.buses)
+  }
+
   // 2b) bridgeHub(WS Hub 브릿지, ADR-065/176) 검증 + wsCluster 상호배타.
   //     클러스터 전송은 앱당 **하나**다 — bridgeHub(WS Hub) 와 global wsCluster(NATS) 를 동시에 쓰면
   //     app.broadcast 가 양쪽으로 나가 이중 전파된다. 부팅 시 fail-fast 로 막는다(boot 가 둘 중 하나만 배선).

package/src/core/ctx-builder.js

@@ -18,6 +18,8 @@
  */
 import { MegaConfigError } from '../errors/config-error.js'
 import * as AdapterManager from '../adapters/adapter-manager.js'
+import { getLockManager, attachLockApi } from './lock/index.js'
+import { getBusManager, attachBusApi } from './bus/index.js'
 import { contextProxy as workersContext, PROXY_PROTOCOL_KEYS } from './workers-manager.js'
 import { tracer as megaTracer } from '../lib/mega-tracing.js'
 
@@ -160,7 +162,18 @@ export function buildAdapterAccessors(aliasMaps = {}, appName = '(unknown)') {
       return AdapterManager.get(domain, globalKey) // 별명은 있으나 인스턴스 미등록이면 여기서 throw
     }
   }
-  return { db: make('db'), cache: make('cache'), bus: make('bus'), lock: make('lock') }
+  // lock accessor 는 종전대로 `(alias) => MegaLockAdapter` 콜러블이되, 분산 락 manager 가 설정돼 있으면
+  // 거기에 `.with/.acquire/.tryAcquire/...` 사용자 API 를 얹는다(ADR-226). `ctx.lock(alias)`(스케줄러 등
+  // 기존 사용처)와 `ctx.lock.with(...)`(신규)이 한 콜러블에 공존한다.
+  const lock = make('lock')
+  const manager = getLockManager()
+  if (manager) attachLockApi(/** @type {any} */ (lock), manager)
+  // bus accessor 도 동일 — `ctx.bus(alias)`(설정형 어댑터)에 `.emit/.on/.off/.request/.with` 메시지 버스
+  // 사용자 API 를 얹는다(ADR-227). 콜러블 공존(락 ADR-226 과 같은 패턴).
+  const bus = make('bus')
+  const busManager = getBusManager()
+  if (busManager) attachBusApi(/** @type {any} */ (bus), busManager)
+  return { db: make('db'), cache: make('cache'), bus, lock }
 }
 
 /**

package/src/core/index.js

@@ -9,6 +9,8 @@ export { MegaCluster } from './mega-cluster.js'
 export { loadRoutes } from './routes-loader.js'
 // 중앙 부팅 orchestrator (ADR-123)
 export { bootApp, buildBootContext } from './boot.js'
+// ctx 없는 영역(백그라운드·외부 콜백·테스트)의 booted MegaApp 접근점 (ADR-228)
+export { getApp, hasApp } from './app-registry.js'
 export { wrapEnvelope, errorEnvelope, synthesizeEnvelopeResponseSchema, ENVELOPE_MARK } from './envelope.js'
 // HTTP 라이프사이클 Pipeline — before/transform/after 합성 정본 (ADR-185)
 export { buildHttpPipeline, wrapPreHandler, composeTransform, composeAfter } from './pipeline.js'

package/src/core/lock/cluster-lock.js

@@ -0,0 +1,174 @@
+// @ts-check
+/**
+ * ClusterLockDriver — Node `cluster` IPC 기반 분산 락 driver (ADR-226).
+ *
+ * redis 가 없지만 **클러스터**(`mega start --cluster=N`)로 도는 환경용. 같은 노드의 워커들이 **master
+ * 프로세스에 위임**해 직렬화한다 — 워커가 IPC 로 master 에 acquire/release 를 요청하고, master 는
+ * {@link import('./memory-lock.js').MemoryLockDriver} 한 개로 실제 상호배제를 관리한 뒤 응답한다.
+ *
+ * # ⚠️ 멀티 노드 미보장
+ *   cluster IPC 는 **한 노드(master + 그 워커들)** 안에서만 닿는다. 노드가 여러 대면 master 도 여러 개라
+ *   서로의 락을 모른다 — **노드 간 상호배제는 보장하지 못한다**. 진짜 분산 락은 redis driver 를 쓴다.
+ *   factory 가 cluster driver 를 고를 때 이 한계를 부팅 경고로 알린다.
+ *
+ * # 구성
+ *   - **master 측**: {@link installClusterLockMaster} 를 master 프로세스에서 1회 호출 — 워커 메시지를
+ *     받아 MemoryLockDriver 로 처리하고 회신한다(`mega start` 클러스터 분기, metrics aggregator 옆).
+ *   - **worker 측**: {@link ClusterLockDriver} 가 `process.send` 로 요청하고 correlation id 로 응답을 매칭한다.
+ *     acquire 의 waitMs 대기·FIFO 큐·TTL 만료는 전부 master 의 MemoryLockDriver 가 처리하므로 worker 는
+ *     얇은 RPC 클라이언트다.
+ *
+ * # 워커 crash
+ *   워커가 락 보유 중 죽으면 master 의 메모리 락은 **TTL 만료**로 풀린다(안전망). 즉시 정리는 안 함 —
+ *   TTL 을 임계구역 예상보다 넉넉히 잡는 것이 운영 권고(memory/redis 와 동일).
+ *
+ * @module core/lock/cluster-lock
+ */
+import nodeCluster from 'node:cluster'
+import { MemoryLockDriver } from './memory-lock.js'
+
+/** IPC 메시지 마커 — 다른 cluster 메시지(metrics 등)와 섞이지 않게 한다. */
+const LOCK_MSG = 'mega:lock'
+
+/** master 에 responder 가 이미 설치됐는지(멱등 가드). @type {boolean} */
+let masterInstalled = false
+
+/**
+ * master 프로세스에 락 responder 를 설치한다(멱등). 워커들의 IPC 요청을 한 MemoryLockDriver 로 직렬화한다.
+ * `mega start` 클러스터 분기에서 master 가 1회 호출한다.
+ *
+ * @param {import('node:cluster').Cluster} [cluster] - 테스트 주입용(기본 node:cluster).
+ * @returns {MemoryLockDriver | null} 설치된 master driver(테스트/관측용). 이미 설치됐으면 null.
+ */
+export function installClusterLockMaster(cluster = nodeCluster) {
+  if (masterInstalled) return null
+  masterInstalled = true
+  const driver = new MemoryLockDriver()
+  cluster.on('message', (worker, msg) => {
+    void handleMasterMessage(driver, worker, msg)
+  })
+  return driver
+}
+
+/**
+ * master 측 메시지 1건 처리 — op 를 MemoryLockDriver 로 위임하고 결과를 워커에 회신. 절대 throw 안 함
+ * (worker 에러 응답으로 표면화). acquire 의 waitMs 대기는 driver 가 hold 하므로 응답이 그만큼 늦게 간다.
+ * @param {MemoryLockDriver} driver @param {import('node:cluster').Worker} worker @param {any} msg
+ * @returns {Promise<void>}
+ */
+async function handleMasterMessage(driver, worker, msg) {
+  if (!msg || msg.t !== LOCK_MSG || msg.id === undefined) return
+  const { id, op, key, token, ttl, opts } = msg
+  try {
+    /** @type {any} */
+    let result
+    if (op === 'acquire') result = await driver.acquire(key, opts)
+    else if (op === 'release') result = await driver.release(key, token)
+    else if (op === 'extend') result = await driver.extend(key, token, ttl)
+    else if (op === 'forceRelease') {
+      await driver.forceRelease(key)
+      result = null
+    } else if (op === 'stats') result = await driver.stats()
+    else {
+      worker.send?.({ t: LOCK_MSG, id, error: `unknown lock op: ${op}` })
+      return
+    }
+    worker.send?.({ t: LOCK_MSG, id, result })
+  } catch (e) {
+    // master 측 처리 실패 — 워커에 에러로 전달(silent 금지). 워커의 #request 가 reject 한다.
+    worker.send?.({ t: LOCK_MSG, id, error: e instanceof Error ? e.message : String(e) })
+  }
+}
+
+/** 테스트 격리용 — master responder 설치 플래그 초기화. @returns {void} */
+export function _resetClusterLockMaster() {
+  masterInstalled = false
+}
+
+/**
+ * 워커 측 cluster 락 driver — master 에 IPC 위임하는 얇은 RPC 클라이언트.
+ * driver 계약은 {@link import('./contract.js').LockDriver} 를 따른다(typedef — 런타임 implements 아님).
+ */
+export class ClusterLockDriver {
+  /** @type {Map<string, { resolve: (v: any) => void, reject: (e: any) => void }>} id → 대기 응답. */ #pending = new Map()
+  /** @type {number} 요청 시퀀스(pid 와 합쳐 전역 유일 id). */ #seq = 0
+  /** @type {NodeJS.Process} master 와의 IPC 채널(cluster 워커면 process). */ #proc
+  /** @type {(msg: any) => void} 'message' 리스너 참조(close 에서 제거). */ #onMessage
+
+  /**
+   * @param {{ proc?: NodeJS.Process }} [opts] - `proc` 테스트 주입용(기본 전역 process). cluster 워커면
+   *   `process.send` 로 master 에 닿는다.
+   * @throws {Error} proc.send 가 없으면(=cluster 워커가 아님) — factory 가 cluster 워커일 때만 생성한다.
+   */
+  constructor({ proc = process } = {}) {
+    if (typeof proc.send !== 'function') {
+      throw new Error('ClusterLockDriver requires an IPC channel (process.send) — only valid in a cluster worker.')
+    }
+    this.#proc = proc
+    this.#onMessage = (msg) => {
+      if (!msg || msg.t !== LOCK_MSG || msg.id === undefined) return
+      const p = this.#pending.get(msg.id)
+      if (!p) return
+      this.#pending.delete(msg.id)
+      if (msg.error !== undefined) p.reject(new Error(`cluster lock master error: ${msg.error}`))
+      else p.resolve(msg.result)
+    }
+    proc.on('message', this.#onMessage)
+  }
+
+  /** @type {'cluster'} */
+  get name() {
+    return 'cluster'
+  }
+
+  /**
+   * master 에 op 를 보내고 응답을 correlation id 로 기다린다.
+   * @param {string} op @param {Record<string, any>} payload @returns {Promise<any>}
+   */
+  #request(op, payload) {
+    return new Promise((resolve, reject) => {
+      const id = `${process.pid}:${++this.#seq}`
+      this.#pending.set(id, { resolve, reject })
+      try {
+        this.#proc.send?.({ t: LOCK_MSG, id, op, ...payload })
+      } catch (e) {
+        // IPC 채널 단절 등 — 즉시 reject(대기 누수 방지).
+        this.#pending.delete(id)
+        reject(e instanceof Error ? e : new Error(String(e)))
+      }
+    })
+  }
+
+  /** @param {string} key @param {import('./contract.js').NormalizedLockOpts} opts @returns {Promise<import('./contract.js').DriverLock | null>} */
+  async acquire(key, opts) {
+    return this.#request('acquire', { key, opts })
+  }
+
+  /** @param {string} key @param {string} token @returns {Promise<boolean>} */
+  async release(key, token) {
+    return this.#request('release', { key, token })
+  }
+
+  /** @param {string} key @param {string} token @param {number} ttl @returns {Promise<boolean>} */
+  async extend(key, token, ttl) {
+    return this.#request('extend', { key, token, ttl })
+  }
+
+  /** @param {string} key @returns {Promise<void>} */
+  async forceRelease(key) {
+    await this.#request('forceRelease', { key })
+  }
+
+  /** @returns {Promise<{ driver: string, active: number, waiting: number }>} */
+  async stats() {
+    const s = await this.#request('stats', {})
+    return { driver: 'cluster', active: s.active, waiting: s.waiting }
+  }
+
+  /** 정리 — IPC 리스너 제거 + 대기 요청에 null 응답(누수 방지). @returns {Promise<void>} */
+  async close() {
+    this.#proc.off?.('message', this.#onMessage)
+    for (const p of this.#pending.values()) p.resolve(null)
+    this.#pending.clear()
+  }
+}

package/src/core/lock/contract.js

@@ -0,0 +1,123 @@
+// @ts-check
+/**
+ * 분산 락 공통 contract — driver 인터페이스 + Lock 핸들 shape + opts 검증 + 토큰 생성 (ADR-226).
+ *
+ * `ctx.lock.with/.acquire/.tryAcquire` 사용자 API 는 {@link import('./index.js').LockManager} 가 제공하고,
+ * 실제 상호배제는 **driver**(redis/cluster/memory)가 담당한다. driver 는 저장/조정만 하고(아래 LockDriver),
+ * watchdog 자동 연장·Lock 핸들 구성·tryAcquire(=waitMs 0) 같은 사용자 ergonomics 는 manager 가 driver
+ * 위에 얹는다. 그래서 FIFO·fence 처럼 저장소-특화 동작만 driver 가 구현하고, 나머지는 한 곳(manager)에서
+ * 모든 driver 에 공통 적용된다.
+ *
+ * # 기존 `ctx.lock(alias)` 와의 관계 (ADR-113 ↔ ADR-226)
+ *   `ctx.lock` 은 **callable object** 다 — `ctx.lock(alias)` 는 종전대로 설정된 `MegaLockAdapter`(redlock)를
+ *   반환하고(스케줄러·기존 사용처 무변경), 거기에 `.with/.acquire/...` 메서드가 붙어 사용자 분산 락 API 가
+ *   된다. 둘은 별개 하위시스템이다(전자=설정형 alias 어댑터, 후자=자동폴백 driver).
+ *
+ * @module core/lock/contract
+ */
+import { randomBytes } from 'node:crypto'
+import { MegaValidationError } from '../../errors/http-errors.js'
+
+/** 락 TTL 디폴트(ms) — 임계구역 보호 시간. config `lock.ttl` 로 조정. */
+export const DEFAULT_TTL_MS = 5000
+/** 획득 대기 디폴트(ms) — 경합 시 이만큼 기다린다(0=즉시 실패). config `lock.waitMs` 로 조정. */
+export const DEFAULT_WAIT_MS = 1000
+/** watchdog 자동 연장 주기 = ttl × 이 비율. 만료 전에 넉넉히 갱신(절반). */
+export const WATCHDOG_RATIO = 0.5
+
+/**
+ * @typedef {Object} LockOpts - acquire/with/tryAcquire 옵션(정규화 전).
+ * @property {number} [ttl] - 락 보유 시간(ms, 양의 정수). 미지정 시 manager 디폴트.
+ * @property {number} [waitMs] - 획득 대기 상한(ms, 0 이상). 0 = 즉시(tryAcquire 와 동일). 미지정 시 디폴트.
+ * @property {boolean} [fifo] - true 면 대기자를 도착 순서대로 깨운다(기아 방지). driver 가 지원해야 함.
+ * @property {boolean} [fence] - true 면 단조 증가 fence 토큰을 함께 반환(외부 시스템의 stale-writer 차단용).
+ * @property {boolean} [extendable] - true 면 manager 가 watchdog 으로 ttl 절반마다 자동 연장(긴 임계구역).
+ */
+
+/**
+ * @typedef {Object} NormalizedLockOpts - 검증·기본값 적용된 옵션.
+ * @property {number} ttl @property {number} waitMs @property {boolean} fifo @property {boolean} fence @property {boolean} extendable
+ */
+
+/**
+ * @typedef {Object} DriverLock - driver.acquire 성공 결과(저수준 — manager 가 LockHandle 로 감싼다).
+ * @property {string} token - 이 보유를 식별하는 랜덤 토큰(release/extend 가 소유 검증에 쓴다).
+ * @property {number} [fence] - fence 토큰(단조 증가). `fence:true` 일 때만.
+ */
+
+/**
+ * @typedef {Object} LockHandle - 사용자에게 반환되는 락 핸들(manager 구성).
+ * @property {string} key - 잠근 자원 키.
+ * @property {string} token - 보유 토큰.
+ * @property {number} [fence] - fence 토큰(`fence:true` 일 때만).
+ * @property {() => Promise<void>} release - 락 해제(idempotent — 이미 풀렸어도 안전). watchdog 도 멈춘다.
+ * @property {(ttl?: number) => Promise<boolean>} extend - TTL 연장. 아직 보유 중이면 true, 잃었으면 false.
+ */
+
+/**
+ * @typedef {Object} LockDriver - driver 가 구현하는 저수준 인터페이스(manager 가 호출).
+ * @property {string} name - 'redis' | 'cluster' | 'memory'.
+ * @property {(key: string, opts: NormalizedLockOpts) => Promise<DriverLock | null>} acquire -
+ *   waitMs 안에 획득하면 `{token, fence?}`, 못 잡으면 `null`(throw 아님 — 경합은 정상 결과).
+ * @property {(key: string, token: string) => Promise<boolean>} release - 토큰이 현재 보유자면 풀고 true,
+ *   아니면(이미 만료/타인 보유) false. 절대 throw 안 함.
+ * @property {(key: string, token: string, ttl: number) => Promise<boolean>} extend - 토큰이 보유자면 ttl
+ *   갱신 후 true, 아니면 false.
+ * @property {(key: string) => Promise<void>} forceRelease - 관리용 강제 해제(토큰 무관). 대기자 깨움 포함.
+ * @property {() => Promise<{ driver: string, active: number, waiting: number }>} stats - 현재 보유/대기 수.
+ * @property {() => Promise<void>} close - 타이머·구독·연결참조 정리(graceful shutdown).
+ */
+
+/**
+ * 락 보유 토큰 생성 — 충돌 사실상 불가한 랜덤 24-hex. release/extend 가 소유권 검증에 쓴다.
+ * @returns {string}
+ */
+export function generateToken() {
+  return randomBytes(12).toString('hex')
+}
+
+/**
+ * acquire/with/tryAcquire 옵션을 검증·정규화한다(fail-fast — 잘못된 입력은 락 시도 전에 throw).
+ * @param {{ ttl: number, waitMs: number, fifo: boolean }} defaults - manager 디폴트(config 유래).
+ * @param {LockOpts} [opts] - 사용자 옵션.
+ * @returns {NormalizedLockOpts}
+ * @throws {MegaValidationError} `lock.invalid_opts` - ttl/waitMs 가 정수 범위를 벗어나거나 boolean 아닌 플래그.
+ */
+export function normalizeLockOpts(defaults, opts = {}) {
+  const ttl = opts.ttl ?? defaults.ttl
+  if (!Number.isInteger(ttl) || ttl <= 0) {
+    throw new MegaValidationError('lock.invalid_opts', `lock ttl must be a positive integer (ms). Got: ${ttl}.`, { details: { ttl } })
+  }
+  const waitMs = opts.waitMs ?? defaults.waitMs
+  if (!Number.isInteger(waitMs) || waitMs < 0) {
+    throw new MegaValidationError('lock.invalid_opts', `lock waitMs must be an integer >= 0 (ms, 0 = no wait). Got: ${waitMs}.`, { details: { waitMs } })
+  }
+  for (const flag of /** @type {const} */ (['fifo', 'fence', 'extendable'])) {
+    if (opts[flag] !== undefined && typeof opts[flag] !== 'boolean') {
+      throw new MegaValidationError('lock.invalid_opts', `lock '${flag}' must be a boolean. Got: ${typeof opts[flag]}.`, { details: { flag, value: opts[flag] } })
+    }
+  }
+  return {
+    ttl,
+    waitMs,
+    fifo: opts.fifo ?? defaults.fifo,
+    fence: opts.fence === true,
+    extendable: opts.extendable === true,
+  }
+}
+
+/**
+ * 락 key 검증 — 비어있지 않은 문자열. 저장소 키/redis subject 로 쓰이므로 제어문자·공백을 막는다.
+ * @param {string} key
+ * @returns {void}
+ * @throws {MegaValidationError} `lock.invalid_key`
+ */
+export function assertLockKey(key) {
+  if (typeof key !== 'string' || key.length === 0) {
+    throw new MegaValidationError('lock.invalid_key', `lock key must be a non-empty string. Got: ${typeof key}.`, { details: { key } })
+  }
+  if (/\s/.test(key)) {
+    // 공백·제어문자만 금지(redis 키/pub-sub 채널 안전). ':' '.' '-' 같은 일반 키 구분자는 허용.
+    throw new MegaValidationError('lock.invalid_key', `lock key must not contain whitespace or control characters. Got: ${JSON.stringify(key)}.`, { details: { key } })
+  }
+}

package/src/core/lock/fifo-waitlist.js

@@ -0,0 +1,93 @@
+// @ts-check
+/**
+ * FifoWaitlist — redis Sorted Set 기반 FIFO 대기열 (ADR-226, redis-lock driver 전용).
+ *
+ * `fifo:true` 락은 경합 시 **도착 순서**대로 깨워야 한다(기아 방지). redis 에는 프로세스 경계를 넘는
+ * 공유 큐가 필요하므로 **Sorted Set** 으로 순서를 매기고, 대기자는 자신이 **큐의 맨 앞(head)** 이 됐을
+ * 때만 락 `SET NX` 를 시도한다. 해제 알림은 redis Pub/Sub 가 깨운다(redis-lock.js).
+ *
+ * # 점수 = 전역 INCR 시퀀스 (ms 타임스탬프 아님)
+ *   타임스탬프(ms)를 점수로 쓰면 같은 ms 에 합류한 대기자들의 순서가 비결정적(점수 동률 → member 사전순)이
+ *   되어 FIFO 가 깨진다. 그래서 점수는 redis `INCR <seqKey>` 의 **전역 단조 시퀀스**를 쓴다 — 모든
+ *   프로세스가 한 카운터를 공유하므로 합류 순서가 곧 전역 총순서다(진짜 분산 FIFO).
+ *
+ * # stale 항목 reaping (member 에 deadline 인코딩)
+ *   대기자 프로세스가 `leave` 전에 죽으면 그 항목이 head 에 남아 뒤를 막는다. 시퀀스 점수로는 "오래됨"을
+ *   판단할 수 없으므로, member 를 `"<token>:<deadlineMs>"` 로 인코딩한다. head 의 deadline 이 현재보다
+ *   과거면(대기 시한 초과 — 정상 대기자라면 스스로 떠났을 것) 버려진 것으로 보고 `ZREM` 후 다음 head 를 본다.
+ *
+ * @module core/lock/fifo-waitlist
+ */
+
+/**
+ * @typedef {Object} RedisLike - 이 헬퍼가 쓰는 ioredis 메서드 부분집합(테스트 fake 도 충족).
+ * @property {(key: string) => Promise<number>} incr
+ * @property {(key: string, score: number, member: string) => Promise<any>} zadd
+ * @property {(key: string, member: string) => Promise<any>} zrem
+ * @property {(key: string, start: number, stop: number) => Promise<string[]>} zrange
+ * @property {(key: string) => Promise<number>} zcard
+ */
+
+/** reaping 무한루프 방지 상한(연속 stale head 청소 횟수). */
+const MAX_REAP_PER_CHECK = 16
+
+export class FifoWaitlist {
+  /** @type {RedisLike} */ #client
+  /** @type {(key: string) => string} key → waitlist zset 키. */ #zkey
+  /** @type {string} 전역 시퀀스 카운터 키(INCR). */ #seqKey
+
+  /**
+   * @param {RedisLike} client - ioredis 호환 클라이언트(명령용, redis-lock 과 공유).
+   * @param {{ zkey: (key: string) => string, seqKey: string }} opts -
+   *   `zkey` 락 key → zset 키 매퍼, `seqKey` 전역 시퀀스 카운터 키(네임스페이스 일원화).
+   */
+  constructor(client, { zkey, seqKey }) {
+    this.#client = client
+    this.#zkey = zkey
+    this.#seqKey = seqKey
+  }
+
+  /**
+   * 대기열에 합류 — 전역 INCR 시퀀스를 점수로 부여해 도착 순서를 확정한다.
+   * @param {string} key @param {string} token @param {number} deadlineMs - 이 대기자의 시한(now+waitMs); reaping 판정용.
+   * @returns {Promise<string>} 등록된 member 문자열(leave 에 그대로 넘겨 정확히 제거).
+   */
+  async join(key, token, deadlineMs) {
+    const seq = Number(await this.#client.incr(this.#seqKey))
+    const member = `${token}:${deadlineMs}`
+    await this.#client.zadd(this.#zkey(key), seq, member)
+    return member
+  }
+
+  /**
+   * 내가 큐의 head 인지 — 시한 지난(버려진) head 를 청소한 뒤 맨 앞 token 과 비교.
+   * @param {string} key @param {string} token @param {number} nowMs - 현재 시각(Date.now()).
+   * @returns {Promise<boolean>}
+   */
+  async isHead(key, token, nowMs) {
+    for (let i = 0; i < MAX_REAP_PER_CHECK; i++) {
+      const head = await this.#client.zrange(this.#zkey(key), 0, 0)
+      if (head.length === 0) return false
+      const member = head[0]
+      const sep = member.lastIndexOf(':')
+      const deadline = Number(member.slice(sep + 1))
+      if (deadline && deadline < nowMs) {
+        // 시한 초과 head = 떠나지 못하고 죽은 대기자 → 청소하고 다음 head 확인.
+        await this.#client.zrem(this.#zkey(key), member)
+        continue
+      }
+      return member.slice(0, sep) === token
+    }
+    return false
+  }
+
+  /** 대기열에서 이탈(획득 성공/타임아웃/취소 시). @param {string} key @param {string} member - join 이 돌려준 값. @returns {Promise<void>} */
+  async leave(key, member) {
+    await this.#client.zrem(this.#zkey(key), member)
+  }
+
+  /** 현재 대기자 수. @param {string} key @returns {Promise<number>} */
+  async size(key) {
+    return this.#client.zcard(this.#zkey(key))
+  }
+}