mega-framework 0.1.0

package/src/adapters/redis-session-adapter.js

@@ -0,0 +1,261 @@
+// @ts-check
+/**
+ * MegaRedisSessionAdapter — Redis 세션 스토어 (`ioredis` 래퍼, ADR-129).
+ *
+ * `MegaSessionAdapter`(ADR-046/027) 의 두 번째 구체(file 다음). **분산/클러스터 환경 권장 스토어**
+ * (ADR-046 — "cluster 모드는 Redis 권장"). 세션 레코드를 Redis 키로 보관하고 TTL 을 Redis 가
+ * 자동 만료시켜 cleanup 이 거의 불필요하다.
+ *
+ * # 연결 처리 — `MegaRedisAdapter`(cache)와 동일 전략 재사용
+ *   `resolveConnection`(url XOR discrete) + lazy ioredis import(미사용 환경 비강제) + connect+ping
+ *   검증. cache 어댑터와 같은 패턴이라 운영 일관성이 있다(같은 url/host 옵션 표면).
+ *
+ * # 키 네임스페이스
+ *   `<keyPrefix><sid>` (기본 prefix `mega:sess:`). cache 키(ADR-064 `mega:cache:…`)와 분리돼
+ *   같은 Redis 인스턴스를 캐시·세션이 공유해도 충돌하지 않는다.
+ *
+ * # TTL / cleanup
+ *   `save()` 는 `SET key json PX ttlMs`(원자적 저장+만료). `touch()` 는 `PEXPIRE key ttlMs`(rolling).
+ *   `cleanup()` 은 **no-op(0 반환)** — Redis 가 TTL 만료를 자동 처리하므로 스캔이 불필요하다
+ *   (file 스토어와 분기. ADR-046 "Redis 는 TTL 자동").
+ *
+ * # 설정
+ *   ```js
+ *   session: {
+ *     store: { driver: 'redis', url: 'redis://:pw@host:6379/0', keyPrefix: 'mega:sess:' },
+ *     ttlMs: 86400000,   // save() 가 적용할 기본 TTL (미들웨어가 store 생성 시 주입)
+ *   }
+ *   ```
+ *   비밀번호/url 은 healthCheck/getStats/에러 details 에 절대 노출하지 않는다.
+ *
+ * @module adapters/redis-session-adapter
+ */
+import { MegaValidationError } from '../errors/http-errors.js'
+import { MegaSessionAdapter } from './mega-session-adapter.js'
+import { resolveConnection, assertPlainObject } from './adapter-options.js'
+
+/** save() 가 store 기본 TTL 미설정 시 적용할 폴백 (24시간, ms). */
+const DEFAULT_TTL_MS = 86_400_000
+
+/** 기본 키 prefix — cache 키(mega:cache:)와 분리. */
+const DEFAULT_KEY_PREFIX = 'mega:sess:'
+
+/**
+ * @typedef {object} RedisSessionConfig
+ * @property {string} [driver] - 'redis' (팩토리가 사용 — 어댑터는 무시).
+ * @property {string} [url] - `redis://[:pw@]host:port[/db]` (discrete 와 배타).
+ * @property {string} [connectionString] - `url` 의 deprecated 별칭.
+ * @property {string} [host] @property {number} [port] @property {string} [user] @property {string} [password]
+ * @property {number} [db] - 논리 DB 번호 0~15.
+ * @property {string} [keyPrefix] - 세션 키 prefix(기본 'mega:sess:').
+ * @property {number} [ttlMs] - save() 가 적용할 기본 TTL(ms). 미지정 시 24시간.
+ * @property {Record<string, any>} [options] - ioredis passthrough.
+ */
+
+export class MegaRedisSessionAdapter extends MegaSessionAdapter {
+  /** @type {import('ioredis').Redis | null} */
+  #client = null
+  /** @type {string | undefined} 연결 URL(시크릿 포함 — 외부 노출 금지). */
+  #url
+  /** @type {import('ioredis').RedisOptions} */
+  #clientOptions
+  /** @type {string} 세션 키 prefix. */
+  #keyPrefix
+  /** @type {number} save() 기본 TTL(ms). */
+  #ttlMs
+  /** @type {number | undefined} 논리 DB(getStats 용). */
+  #db
+
+  /**
+   * @param {RedisSessionConfig} [config]
+   * @throws {MegaValidationError} `adapter.connection_required` / `adapter.connection_conflict` / `session.invalid_option`
+   */
+  constructor(config = /** @type {any} */ ({})) {
+    super(config)
+
+    // db 는 connection 과 별개 축이라 url 과 충돌하지 않음(MegaRedisAdapter 와 동일).
+    const conn = resolveConnection(config, { driver: 'redis', dbConflictsWithUrl: false })
+
+    if (config.db !== undefined) {
+      if (!Number.isInteger(config.db) || config.db < 0 || config.db > 15) {
+        throw new MegaValidationError('session.invalid_option', 'redis session "db" must be an integer between 0 and 15.', {
+          details: { driver: 'redis', option: 'db', value: config.db },
+        })
+      }
+      this.#db = config.db
+    }
+
+    this.#keyPrefix = config.keyPrefix ?? DEFAULT_KEY_PREFIX
+    if (typeof this.#keyPrefix !== 'string') {
+      throw new MegaValidationError('session.invalid_option', 'redis session "keyPrefix" must be a string.', {
+        details: { driver: 'redis', option: 'keyPrefix', type: typeof this.#keyPrefix },
+      })
+    }
+
+    if (config.ttlMs !== undefined && (!Number.isInteger(config.ttlMs) || config.ttlMs <= 0)) {
+      throw new MegaValidationError('session.invalid_option', `redis session "ttlMs" must be a positive integer (ms). Got: ${config.ttlMs}.`, {
+        details: { driver: 'redis', option: 'ttlMs', value: config.ttlMs },
+      })
+    }
+    this.#ttlMs = config.ttlMs ?? DEFAULT_TTL_MS
+
+    assertPlainObject('options', config.options, { driver: 'redis' })
+
+    /** @type {import('ioredis').RedisOptions} */
+    const clientOptions = {}
+    if (config.options !== undefined) Object.assign(clientOptions, config.options)
+    // 라이프사이클은 베이스 상태머신이 관리 — ioredis 자동 연결 끄고 _connect 에서 명시 연결.
+    clientOptions.lazyConnect = true
+    if (conn.url === undefined) {
+      if (conn.host !== undefined) clientOptions.host = conn.host
+      if (conn.port !== undefined) clientOptions.port = conn.port
+      if (conn.user !== undefined) clientOptions.username = conn.user
+      if (conn.password !== undefined) clientOptions.password = conn.password
+    }
+    if (this.#db !== undefined) clientOptions.db = this.#db
+    this.#url = conn.url
+    this.#clientOptions = clientOptions
+  }
+
+  /**
+   * ioredis 클라이언트 생성 + connect + ping (driver 는 connect 시점 lazy import — 미사용 환경 비강제).
+   * @protected
+   * @returns {Promise<void>}
+   */
+  async _connect() {
+    const { Redis } = await import('ioredis')
+    const client = this.#url !== undefined ? new Redis(this.#url, this.#clientOptions) : new Redis(this.#clientOptions)
+    try {
+      await client.connect()
+      const pong = await client.ping()
+      if (pong !== 'PONG') {
+        throw new MegaValidationError('adapter.health_failed', `redis session ping returned unexpected reply: ${pong}`, {
+          details: { driver: 'redis', reply: pong },
+        })
+      }
+      this.#client = client
+    } catch (err) {
+      try {
+        client.disconnect()
+      } catch (closeErr) {
+        // 검증 실패 후 정리 실패는 비치명적 — 원본 연결 에러가 진짜 원인.
+        console.warn('[MegaRedisSessionAdapter] client.disconnect() failed after connect validation error (original error wins):', closeErr)
+      }
+      throw err
+    }
+  }
+
+  /**
+   * ioredis graceful 종료(`quit`).
+   * @protected
+   * @returns {Promise<void>}
+   */
+  async _disconnect() {
+    if (this.#client !== null) {
+      const client = this.#client
+      this.#client = null
+      await client.quit()
+    }
+  }
+
+  /**
+   * raw ioredis handle (ADR-009).
+   * @protected
+   * @returns {import('ioredis').Redis}
+   */
+  _native() {
+    if (this.#client === null) return this._notImplemented('native')
+    return this.#client
+  }
+
+  /**
+   * 헬스 체크 — 실제 ping. 비밀번호/url 은 노출하지 않는다.
+   * @returns {Promise<{ ok: boolean, driver: 'redis', state: string, db?: number, error?: string }>}
+   */
+  async healthCheck() {
+    if (this.state !== 'connected' || this.#client === null) {
+      return { ok: false, driver: 'redis', state: this.state }
+    }
+    try {
+      const pong = await this.#client.ping()
+      return { ok: pong === 'PONG', driver: 'redis', state: this.state, db: this.#db }
+    } catch (err) {
+      return { ok: false, driver: 'redis', state: this.state, db: this.#db, error: err instanceof Error ? err.message : String(err) }
+    }
+  }
+
+  /**
+   * 누적 통계 + redis 세션 특화.
+   * @returns {ReturnType<import('./mega-adapter.js').MegaAdapter['getStats']> & { driver: string, db: number | undefined, keyPrefix: string, ttlMs: number, status: string | undefined }}
+   */
+  getStats() {
+    return { ...super.getStats(), driver: 'redis', db: this.#db, keyPrefix: this.#keyPrefix, ttlMs: this.#ttlMs, status: this.#client?.status }
+  }
+
+  /**
+   * sid → Redis 키.
+   * @param {string} sid @returns {string}
+   */
+  #keyFor(sid) {
+    return this.#keyPrefix + sid
+  }
+
+  /**
+   * 세션 조회. 없으면 `null`(Redis 가 만료 키를 자동 제거하므로 별도 만료 검사 불필요).
+   * @param {string} sid
+   * @returns {Promise<object | null>}
+   */
+  async load(sid) {
+    return this._instrument('load', { sid }, async () => {
+      const raw = await /** @type {import('ioredis').Redis} */ (this.#client).get(this.#keyFor(sid))
+      if (raw === null) return null
+      return JSON.parse(raw)
+    })
+  }
+
+  /**
+   * 세션 저장 — `SET key json PX ttlMs`(원자적 저장+만료).
+   * @param {string} sid
+   * @param {object} record
+   * @returns {Promise<void>}
+   */
+  async save(sid, record) {
+    return this._instrument('save', { sid }, async () => {
+      const raw = JSON.stringify(record ?? {})
+      await /** @type {import('ioredis').Redis} */ (this.#client).set(this.#keyFor(sid), raw, 'PX', this.#ttlMs)
+    })
+  }
+
+  /**
+   * 세션 삭제(idempotent — DEL 은 없는 키도 0 반환).
+   * @param {string} sid
+   * @returns {Promise<void>}
+   */
+  async destroy(sid) {
+    return this._instrument('destroy', { sid }, async () => {
+      await /** @type {import('ioredis').Redis} */ (this.#client).del(this.#keyFor(sid))
+    })
+  }
+
+  /**
+   * rolling TTL 갱신(ADR-046) — `PEXPIRE key ttlMs`. 키가 없으면 PEXPIRE 가 0 을 반환하고 no-op
+   * (없는/만료된 세션을 되살리지 않음 — file 스토어와 동일 의미).
+   * @param {string} sid
+   * @param {number} ttlMs
+   * @returns {Promise<void>}
+   */
+  async touch(sid, ttlMs) {
+    return this._instrument('touch', { sid, ttlMs }, async () => {
+      await /** @type {import('ioredis').Redis} */ (this.#client).pexpire(this.#keyFor(sid), ttlMs)
+    })
+  }
+
+  /**
+   * no-op(0 반환) — Redis 가 TTL 만료를 자동 처리하므로 스캔 cleanup 이 불필요하다(ADR-046).
+   * 인터페이스 정합을 위해 존재하며, `mega scheduler` 가 호출해도 안전하다.
+   * @returns {Promise<number>} 항상 0.
+   */
+  async cleanup() {
+    return this._instrument('cleanup', {}, async () => 0)
+  }
+}

package/src/adapters/redlock-adapter.js

@@ -0,0 +1,385 @@
+// @ts-check
+/**
+ * MegaRedlockAdapter — 분산 락 어댑터 (`redlock` 래퍼, ADR-113).
+ *
+ * **첫 lock 도메인 어댑터**(`MegaLockAdapter` 첫 구체). Redis 기반 Redlock 알고리즘으로
+ * 여러 프로세스·인스턴스 간 상호배제 락을 제공한다. cluster 미지원(단일 노드, ADR-110 정합) — 단일
+ * Redis 인스턴스 위 단일 클라이언트로 동작한다.
+ *
+ * # 표준 표면 (MegaLockAdapter 상속)
+ *   - `_connect()`   — 참조한 Redis 캐시 어댑터의 native client 를 빌려 `new Redlock([client], settings)`.
+ *   - `_disconnect()`— redlock 의 'error' 리스너 제거 + 참조 해제. **`redlock.quit()` 은 호출하지 않는다**
+ *                      (아래 "공유 client lifecycle" 참조).
+ *   - `_native()`    — redlock 인스턴스(raw handle, ADR-009).
+ *   - `healthCheck()`— 참조 Redis 어댑터의 healthCheck 에 위임(락 가용성 == Redis 가용성).
+ *   - `getStats()`   — 베이스 stats + redlock 특화(driver/redis 키/settings).
+ *   - `acquire/release/extend/withLock` — redlock acquire/release/extend/using 위임.
+ *
+ * # 공유 Redis client 참조 (중요 — ADR-102 글로벌 공유 확장)
+ *   redlock 은 자체 연결을 열지 않고, `config.redis` 가 가리키는 **이미 등록된 Redis 캐시 어댑터**
+ *   (`services.caches.<key>`)의 native client 를 빌려 쓴다. `_connect` 에서 매니저로 그 어댑터를 찾아
+ *   `await adapter.connect()`(멱등·race-guard 라 부팅 병렬 connect 와 순서 무관) 후 `.native` 를 잡는다.
+ *
+ *   **공유 client lifecycle**: 빌려온 ioredis client 의 소유권은 Redis 어댑터에 있다. 따라서
+ *   `_disconnect` 에서 `redlock.quit()`(=모든 client 에 `.quit()`)을 호출하면 **Redis 어댑터가 소유한
+ *   공유 연결을 끊어버리는** 사고가 난다. 종료는 매니저 LIFO 로 lock(나중 등록) → cache(먼저 등록)
+ *   순서라, lock 이 먼저 끊긴 뒤 Redis 어댑터가 자기 client 를 quit 한다. 그래서 본 어댑터의
+ *   `_disconnect` 는 리스너 정리만 하고 client 는 건드리지 않는다(소유권 경계 명시).
+ *
+ * # redlock 'error' 이벤트 (Node EventEmitter 주의)
+ *   `Redlock extends EventEmitter` 이고 백그라운드 오류(예: `using` 자동 연장 실패, 만료된 락 release
+ *   실패)를 'error' 로 emit 한다. **리스너가 없으면 Node 가 프로세스를 죽인다**(unhandled 'error').
+ *   `_connect` 에서 리스너를 부착해 비치명적 오류를 표면화(console.warn)한다 — 삼키지 않되 치명으로
+ *   격상하지도 않는다(락은 TTL 로 자동 만료되는 안전망이 있음).
+ *
+ * # 설정 (services.locks.<key>) — ADR-113
+ *   ```js
+ *   services: {
+ *     caches: { sess: { driver: 'redis', url: 'redis://localhost:6379/0' } },
+ *     locks: {
+ *       main: {
+ *         driver: 'redlock',
+ *         redis: 'sess',          // services.caches 의 Redis 어댑터 key 참조(필수)
+ *         options: {              // redlock Settings passthrough(선택)
+ *           driftFactor: 0.01,
+ *           retryCount: 10,
+ *           retryDelay: 200,      // ms
+ *           retryJitter: 200,     // ms
+ *           automaticExtensionThreshold: 500,  // ms (using 자동 연장 임계)
+ *         },
+ *       },
+ *     },
+ *   }
+ *   ```
+ *
+ * @module adapters/redlock-adapter
+ */
+import { MegaValidationError } from '../errors/http-errors.js'
+import { MegaLockAdapter } from './mega-lock-adapter.js'
+import { assertPlainObject, assertNonNegativeInt } from './adapter-options.js'
+import * as AdapterManager from './adapter-manager.js'
+import * as Registry from './registry.js'
+
+/**
+ * redlock Settings 부분집합. redlock 패키지의 `Settings` interface 는 **type-only export** 라 패키지
+ * `exports` 맵(→ .d.ts 없는 esm .js)을 통과하면 TS 에 안 보인다(런타임 값 있는 class 만 보임). 그래서
+ * 같은 shape 를 로컬 typedef 로 둔다(redlock 정의와 1:1, dist/index.d.ts 확인).
+ * @typedef {object} RedlockSettings
+ * @property {number} [driftFactor] - 시계 드리프트 보정 계수 [0,1).
+ * @property {number} [retryCount] - 경합 시 재시도 횟수.
+ * @property {number} [retryDelay] - 재시도 간 지연(ms).
+ * @property {number} [retryJitter] - 재시도 지연 지터(ms).
+ * @property {number} [automaticExtensionThreshold] - `using` 자동 연장 임계(ms).
+ */
+
+/**
+ * redlock `using` routine 이 받는 중단 신호 (redlock 의 `RedlockAbortSignal` 과 동일 shape — 위와 같은
+ * type-only export 사유로 로컬 정의). `aborted` 가 true 면 자동 연장 실패로 배타성 상실, `error` 에 사유.
+ * @typedef {AbortSignal & { error?: Error }} RedlockAbortSignal
+ */
+
+/**
+ * redlock Settings 의 알려진 키 (5종). 그 외 키는 오타로 보고 거부한다(fail-fast).
+ * @type {ReadonlySet<string>}
+ */
+const KNOWN_SETTINGS = new Set(['driftFactor', 'retryCount', 'retryDelay', 'retryJitter', 'automaticExtensionThreshold'])
+
+/**
+ * @typedef {object} RedlockConfig
+ * @property {string} [driver] - 'redlock' (매니저가 사용 — 어댑터는 무시).
+ * @property {string} redis - 참조할 Redis 캐시 어댑터 key (services.caches.<key>). 필수.
+ * @property {Partial<RedlockSettings>} [options] - redlock Settings passthrough(driftFactor/retryCount/retryDelay/retryJitter/automaticExtensionThreshold).
+ */
+
+export class MegaRedlockAdapter extends MegaLockAdapter {
+  /** @type {import('redlock').default | null} 연결된 redlock 인스턴스 (connect 후에만). */
+  #redlock = null
+  /** @type {string} 참조 Redis 캐시 어댑터 key (services.caches.<key>). */
+  #redisKey
+  /** @type {Partial<RedlockSettings>} 생성자에서 검증·고정한 redlock Settings. */
+  #settings
+  /** @type {(err: Error) => void} redlock 'error' 리스너(off 로 정확히 제거하려고 1개 보관). */
+  #onRedlockError
+
+  /**
+   * @param {RedlockConfig} [config] - services.locks.<key> 설정.
+   * @throws {MegaValidationError} `lock.redis_required` - `redis` 키 누락/비문자열.
+   * @throws {MegaValidationError} `adapter.invalid_option` - options 타입/알 수 없는 settings 키/음수.
+   */
+  constructor(config = /** @type {any} */ ({})) {
+    super(config)
+
+    const redisKey = config.redis
+    if (typeof redisKey !== 'string' || redisKey.length === 0) {
+      throw new MegaValidationError(
+        'lock.redis_required',
+        'redlock: "redis" is required — it must be the key of a Redis cache adapter declared in services.caches.',
+        { details: { driver: 'redlock' } },
+      )
+    }
+    this.#redisKey = redisKey
+    this.#settings = MegaRedlockAdapter.#normalizeSettings(config.options)
+
+    // 'error' 리스너를 한 번만 만들어 보관 — _disconnect 에서 off 로 정확히 같은 참조를 제거하기 위함.
+    this.#onRedlockError = (err) => {
+      // redlock 은 EventEmitter 라 백그라운드 오류를 'error' 로 emit 한다(리스너 없으면 프로세스 사망).
+      //
+      // `ResourceLockedError`(자원이 이미 잠김/quorum 미달)는 **정상적인 경합 결과**다 — acquire 는 이걸
+      // 호출자에게 throw 로, `using` 은 abort signal 로 이미 전달한다. 따라서 'error' 채널의 중복 emit 만
+      // 흘려보낸다(삼키는 게 아니라 호출자가 다른 경로로 이미 받음). 만약 매 경합마다
+      // warn 하면 락 경합이 잦은 프로덕션 로그가 범람한다(우회 아닌, 문서화된 의도적 필터).
+      if (err && /** @type {any} */ (err).name === 'ResourceLockedError') return
+      // 그 외(네트워크·Redis 다운·스크립트 오류 등)는 진짜 예상 밖 백그라운드 오류 — 표면화하되
+      // 치명 격상은 안 함(락은 TTL 자동 만료 안전망).
+      console.warn(`[MegaRedlockAdapter] redlock background error (non-fatal — locks auto-expire via TTL):`, err)
+    }
+  }
+
+  /**
+   * redlock Settings 검증·정규화. options 없으면 빈 객체(=redlock 디폴트 사용). 알 수 없는 키는 오타로
+   * 보고 거부, 숫자 4종은 음 아닌 정수, driftFactor 는 [0,1) 유한수.
+   * @param {unknown} options @returns {Partial<RedlockSettings>}
+   */
+  static #normalizeSettings(options) {
+    if (options === undefined) return {}
+    assertPlainObject('options', options, { driver: 'redlock' })
+    const opts = /** @type {Record<string, unknown>} */ (options)
+    for (const key of Object.keys(opts)) {
+      if (!KNOWN_SETTINGS.has(key)) {
+        throw new MegaValidationError(
+          'adapter.invalid_option',
+          `redlock: unknown option "${key}". Known: ${[...KNOWN_SETTINGS].join(', ')}.`,
+          { details: { driver: 'redlock', option: key } },
+        )
+      }
+    }
+    // retryCount/retryDelay/retryJitter/automaticExtensionThreshold 는 음 아닌 정수(ms 또는 횟수).
+    for (const key of ['retryCount', 'retryDelay', 'retryJitter', 'automaticExtensionThreshold']) {
+      assertNonNegativeInt(key, opts[key], { driver: 'redlock' })
+    }
+    // driftFactor 는 시계 드리프트 보정 계수 — [0,1) 유한수.
+    if (opts.driftFactor !== undefined) {
+      const df = opts.driftFactor
+      if (typeof df !== 'number' || !Number.isFinite(df) || df < 0 || df >= 1) {
+        throw new MegaValidationError('adapter.invalid_option', `redlock "driftFactor" must be a finite number in [0, 1) (got: ${df}).`, {
+          details: { driver: 'redlock', option: 'driftFactor', value: df },
+        })
+      }
+    }
+    return /** @type {Partial<RedlockSettings>} */ ({ ...opts })
+  }
+
+  /**
+   * 참조 Redis 어댑터의 native client 를 빌려 redlock 인스턴스를 만든다.
+   *
+   * driver(`redlock`)는 **connect 시점에 lazy import** — 모듈 import(배럴 자기등록)만으로는 redlock 을
+   * 로드하지 않아 미사용 환경이 설치를 강제받지 않는다(다른 어댑터 정합).
+   *
+   * @protected
+   * @returns {Promise<void>}
+   * @throws {MegaConfigError} `adapter.not_registered` - 참조 Redis 어댑터 미등록(매니저).
+   * @throws {MegaValidationError} `lock.redis_client_required` - 참조 어댑터의 native 가 Redis client 가 아님.
+   */
+  async _connect() {
+    // 참조한 Redis 캐시 어댑터를 매니저에서 찾는다(미등록이면 adapter.not_registered throw). 그 다음
+    // connect 를 보장한다 — connect 는 멱등·race-guard 라, connectAll 의 병렬 connect 와 섞여도
+    // 정확히 1회만 실연결되고 본 await 는 같은 promise 를 공유한다(부팅 순서 의존 제거).
+    const cacheAdapter = AdapterManager.get('cache', this.#redisKey)
+    await cacheAdapter.connect()
+    const client = cacheAdapter.native // ioredis Redis client (connect 후에만 유효)
+
+    // 빌려온 client 가 redlock 이 요구하는 Redis 인터페이스(lua eval)인지 부팅 시 검증 — 비-Redis
+    // 캐시(예: file 어댑터)를 redis 로 지정한 사고를 첫 acquire 가 아니라 부팅에서 잡는다(fail-fast).
+    if (typeof client?.eval !== 'function' || typeof client?.evalsha !== 'function') {
+      throw new MegaValidationError(
+        'lock.redis_client_required',
+        `redlock: cache adapter "${this.#redisKey}" did not provide a Redis client (its native handle has no eval/evalsha). "redis" must reference a Redis cache adapter.`,
+        { details: { driver: 'redlock', redis: this.#redisKey } },
+      )
+    }
+
+    const { default: Redlock } = await import('redlock')
+    const redlock = new Redlock([client], this.#settings)
+    // EventEmitter — 리스너 없으면 'error' emit 시 프로세스가 죽는다. 반드시 부착(위 클래스 docstring).
+    redlock.on('error', this.#onRedlockError)
+    this.#redlock = redlock
+  }
+
+  /**
+   * redlock 정리 — 'error' 리스너 제거 + 참조 해제. **빌려온 공유 client 는 건드리지 않는다**
+   * (소유권은 Redis 어댑터, 매니저 LIFO 로 별도 disconnect — 위 클래스 docstring "공유 client lifecycle").
+   * @protected
+   * @returns {Promise<void>}
+   */
+  async _disconnect() {
+    if (this.#redlock !== null) {
+      const redlock = this.#redlock
+      this.#redlock = null
+      redlock.off('error', this.#onRedlockError)
+      // redlock.quit() 은 의도적으로 호출하지 않음 — 공유 ioredis client 는 Redis 어댑터가 소유·종료.
+    }
+  }
+
+  /**
+   * raw redlock handle (ADR-009). 베이스 `native` getter 가 connected 상태에서만 호출한다.
+   * @protected
+   * @returns {import('redlock').default}
+   */
+  _native() {
+    if (this.#redlock === null) {
+      // 베이스 native getter 가 state 검증을 먼저 하므로 정상 경로에선 도달 안 함 — 방어.
+      return this._notImplemented('native')
+    }
+    return this.#redlock
+  }
+
+  /**
+   * 헬스 체크 — 락 가용성은 곧 참조 Redis 의 가용성이라 그 어댑터의 healthCheck 에 위임한다.
+   * 실패는 throw 없이 `ok:false` + 사유(베이스 계약).
+   * @returns {Promise<{ ok: boolean, driver: 'redlock', state: string, redis: string, redisOk?: boolean, error?: string }>}
+   */
+  async healthCheck() {
+    if (this.state !== 'connected' || this.#redlock === null) {
+      return { ok: false, driver: 'redlock', state: this.state, redis: this.#redisKey }
+    }
+    try {
+      const cacheAdapter = AdapterManager.get('cache', this.#redisKey)
+      const health = await cacheAdapter.healthCheck()
+      return { ok: !!health?.ok, driver: 'redlock', state: this.state, redis: this.#redisKey, redisOk: !!health?.ok }
+    } catch (err) {
+      return { ok: false, driver: 'redlock', state: this.state, redis: this.#redisKey, error: err instanceof Error ? err.message : String(err) }
+    }
+  }
+
+  /**
+   * 누적 통계 + redlock 특화(driver/redis 키/settings). settings 는 숫자 계수뿐이라 시크릿 없음.
+   * @returns {ReturnType<import('./mega-adapter.js').MegaAdapter['getStats']> & { driver: string, redis: string, settings: Partial<RedlockSettings> }}
+   */
+  getStats() {
+    return {
+      ...super.getStats(),
+      driver: 'redlock',
+      redis: this.#redisKey,
+      settings: { ...this.#settings },
+    }
+  }
+
+  // ──────────────────────────────────────────────────────────────────────
+  // MegaLockAdapter 인터페이스 — acquire / release / extend / withLock
+  // hook + 상태검증 + stats 는 `_instrument` 가 처리(ADR-077).
+  // ──────────────────────────────────────────────────────────────────────
+
+  /**
+   * 락 획득 — `redlock.acquire([key], ttl, settings)`. 경합 시 retry(opts) 소진 후 실패하면 redlock 이
+   * `ExecutionError` 를 throw(정상 도메인 결과 — 호출부가 처리).
+   *
+   * @param {string} key - 락 자원 키.
+   * @param {{ ttl?: number, retryCount?: number, retryDelay?: number, retryJitter?: number }} [opts]
+   *   - `ttl`(ms, 양의 정수 필수). retry 3종은 이번 호출 한정 override(미지정 시 생성자 settings 사용).
+   * @returns {Promise<import('redlock').Lock>} redlock Lock 핸들.
+   */
+  async acquire(key, opts = {}) {
+    // ttl·retry 검증은 _instrument 밖 — 잘못된 인자는 네트워크 I/O·hook·stats 누적 전에 fail-fast
+    // (인자 오류는 어댑터 "호출"이 아니라 프로그래밍 오류, redis-adapter set 과 동일 패턴).
+    this._assertLockTtl(opts.ttl)
+    const settings = this.#perCallSettings(opts)
+    return this._instrument('acquire', { key, ttl: opts.ttl }, async () => {
+      const redlock = /** @type {import('redlock').default} */ (this.#redlock)
+      return redlock.acquire([key], /** @type {number} */ (opts.ttl), settings)
+    })
+  }
+
+  /**
+   * 락 해제 — `lock.release()`. 이미 만료/탈취된 락 release 는 redlock 이 'error' 로 표면화하거나
+   * throw 할 수 있다(비치명 — 락은 어차피 만료됨). 본 메서드는 정상 해제 경로를 instrument 한다.
+   *
+   * @param {import('redlock').Lock} lock - {@link acquire}/{@link extend} 가 돌려준 핸들.
+   * @returns {Promise<void>}
+   */
+  async release(lock) {
+    this.#assertLock(lock, 'release')
+    return this._instrument('release', { resources: lock.resources }, async () => {
+      await lock.release()
+    })
+  }
+
+  /**
+   * 락 TTL 연장 — `redlock.extend(lock, ttl)`. **새 Lock 핸들을 반환**한다(redlock 이 연장 시 새 핸들을
+   * 만듦) — 이후 release/extend 는 반환된 핸들을 써야 한다(기존 핸들 무효, ADR-113).
+   *
+   * @param {import('redlock').Lock} lock @param {number} ttl - 추가 보유 시간(ms, 양의 정수).
+   * @returns {Promise<import('redlock').Lock>} 연장된 새 Lock 핸들.
+   */
+  async extend(lock, ttl) {
+    this.#assertLock(lock, 'extend')
+    this._assertLockTtl(ttl)
+    return this._instrument('extend', { resources: lock.resources, ttl }, async () => {
+      const redlock = /** @type {import('redlock').default} */ (this.#redlock)
+      return redlock.extend(lock, ttl)
+    })
+  }
+
+  /**
+   * convenience — `redlock.using([key], ttl, settings, routine)`. 락 획득 + **자동 연장**
+   * (automaticExtensionThreshold 임박 시 자동 extend) + 종료 시 자동 release(routine 이 throw 해도 보장).
+   *
+   * routine 은 `(signal)` 을 받는다 — `signal.aborted` 가 true 면 자동 연장이 실패해 더는 배타성을
+   * 보장할 수 없는 상태다(`signal.error` 에 사유). routine 은 이때 즉시 중단하고 예외 상황으로 처리해야
+   * 한다(베이스 `withLock` 의 `(lock)` 시그니처와 다름 — auto-extension 모델 차이, ADR-113).
+   *
+   * @template T
+   * @param {string} key
+   * @param {{ ttl?: number, retryCount?: number, retryDelay?: number, retryJitter?: number }} opts - `ttl`(ms) 필수.
+   * @param {(signal: RedlockAbortSignal) => Promise<T>} fn - 임계구역 routine.
+   * @returns {Promise<T>} routine 반환값.
+   */
+  async withLock(key, opts, fn) {
+    this._assertLockTtl(opts?.ttl)
+    if (typeof fn !== 'function') {
+      throw new MegaValidationError('lock.invalid_routine', `redlock withLock("${key}"): routine (3rd arg) must be a function.`, {
+        details: { driver: 'redlock', key, type: typeof fn },
+      })
+    }
+    const settings = this.#perCallSettings(opts)
+    return this._instrument('withLock', { key, ttl: opts.ttl }, async () => {
+      const redlock = /** @type {import('redlock').default} */ (this.#redlock)
+      return redlock.using([key], /** @type {number} */ (opts.ttl), settings, fn)
+    })
+  }
+
+  /**
+   * acquire/withLock 의 이번-호출 한정 retry override 를 redlock Settings 부분객체로 만든다. 비어 있으면
+   * redlock 이 생성자 settings(또는 라이브러리 디폴트)를 쓴다. 음수 등은 acquire 진입 전 검증.
+   * @param {{ retryCount?: number, retryDelay?: number, retryJitter?: number }} opts
+   * @returns {Partial<RedlockSettings>}
+   */
+  #perCallSettings(opts) {
+    /** @type {Record<string, number>} */
+    const s = {}
+    for (const key of ['retryCount', 'retryDelay', 'retryJitter']) {
+      const v = /** @type {any} */ (opts)[key]
+      if (v !== undefined) {
+        assertNonNegativeInt(key, v, { driver: 'redlock' })
+        s[key] = v
+      }
+    }
+    return s
+  }
+
+  /**
+   * lock 핸들 형태 가드 — redlock Lock 은 `resources` 배열을 갖는다. 잘못된 인자를 네트워크 호출 전에
+   * 명확한 에러로 거부(추측으로 driver 에 넘기지 않음).
+   * @param {any} lock @param {string} method @returns {void}
+   */
+  #assertLock(lock, method) {
+    if (lock === null || typeof lock !== 'object' || !Array.isArray(lock.resources)) {
+      throw new MegaValidationError('lock.invalid_lock', `redlock ${method}(): expected a Lock handle from acquire()/extend().`, {
+        details: { driver: 'redlock', method },
+      })
+    }
+  }
+}
+
+// 빌트인 driver 자기등록 (ADR-044) — 배럴(`adapters/index.js`)이 본 모듈을 import 하면 트리거된다.
+// redlock 은 _connect() 의 lazy import 까지 로드되지 않으므로 등록은 안전(미사용 환경 비강제).
+Registry.register('redlock', MegaRedlockAdapter)