mega-framework 0.1.10 → 0.1.11

package/types/core/bus/index.d.ts

@@ -0,0 +1,100 @@
+/** 활성 버스 manager 설정(boot bus 스테이지). null 로 해제(셧다운/테스트). @param {BusManager | null} m @returns {void} */
+export function setBusManager(m: BusManager | null): void;
+/** 현재 활성 버스 manager(없으면 null). @returns {BusManager | null} */
+export function getBusManager(): BusManager | null;
+/**
+ * 메시지 버스 manager 를 만든다 — driver 자동 폴백 포함. boot 가 1회 호출해 `ctx.bus` 에 부착한다.
+ * @param {{ driver?: string, nats?: string, prefix?: string, defaultPersist?: boolean, requestTimeoutMs?: number }} [busConfig]
+ * @param {{ logger?: any, nc?: any, isClusterWorker?: boolean }} [deps] - `nc` boot 가 bus 어댑터에서 빌린 NatsConnection(없으면 null).
+ * @returns {BusManager}
+ */
+export function createBusManager(busConfig?: {
+    driver?: string;
+    nats?: string;
+    prefix?: string;
+    defaultPersist?: boolean;
+    requestTimeoutMs?: number;
+}, deps?: {
+    logger?: any;
+    nc?: any;
+    isClusterWorker?: boolean;
+}): BusManager;
+/**
+ * `ctx.bus` 콜러블에 사용자 API 메서드를 얹는다 — `ctx.bus(alias)`(기존)와 `ctx.bus.emit(...)`(신규) 공존.
+ * @param {Function & Record<string, any>} busAccessor - `(alias) => MegaBusAdapter` 콜러블(ctx-builder 산출).
+ * @param {BusManager} manager @returns {Function & Record<string, any>} 같은 accessor(체이닝).
+ */
+export function attachBusApi(busAccessor: Function & Record<string, any>, manager: BusManager): Function & Record<string, any>;
+/**
+ * 사용자 메시지 버스 API. driver 한 개를 감싸 emit/on/off/request/with 를 제공한다.
+ */
+export class BusManager {
+    /**
+     * @param {import('./contract.js').BusDriver} driver
+     * @param {{ defaults: { prefix: string, defaultPersist: boolean, requestTimeoutMs: number }, logger?: any }} opts
+     */
+    constructor(driver: import("./contract.js").BusDriver, { defaults, logger }: {
+        defaults: {
+            prefix: string;
+            defaultPersist: boolean;
+            requestTimeoutMs: number;
+        };
+        logger?: any;
+    });
+    /** @returns {string} 활성 driver 이름('nats'|'cluster'|'memory'). */
+    get driverName(): string;
+    /**
+     * 메시지 발행(fire-and-forget fan-out).
+     * @param {string} subject - 구체 subject(wildcard 불가).
+     * @param {any} payload
+     * @param {import('./contract.js').EmitOpts} [opts] - meta / persist.
+     * @returns {Promise<void>}
+     */
+    emit(subject: string, payload: any, opts?: import("./contract.js").EmitOpts): Promise<void>;
+    /**
+     * 구독. 핸들러는 `(payload, meta)`. request 대상이면 핸들러 **반환값이 reply**(undefined 면 응답 안 함).
+     * @param {string} subject - wildcard(`*`/`>`) 가능.
+     * @param {import('./contract.js').BusHandler} handler
+     * @param {import('./contract.js').OnOpts} [opts] - persist / ordered.
+     * @returns {Promise<import('./contract.js').Subscription>}
+     */
+    on(subject: string, handler: import("./contract.js").BusHandler, opts?: import("./contract.js").OnOpts): Promise<import("./contract.js").Subscription>;
+    /**
+     * 구독 해제 — 같은 (subject, handler) 로 등록된 구독을 푼다.
+     * @param {string} subject @param {import('./contract.js').BusHandler} handler @returns {Promise<void>}
+     */
+    off(subject: string, handler: import("./contract.js").BusHandler): Promise<void>;
+    /**
+     * req/reply — 첫 응답 payload 반환. 응답자 없으면 `bus.no_responders`, 시한 초과면 `bus.request_timeout`.
+     * @param {string} subject @param {any} payload
+     * @param {{ timeout?: number, meta?: Record<string, any> }} [opts]
+     * @returns {Promise<any>}
+     */
+    request(subject: string, payload: any, opts?: {
+        timeout?: number;
+        meta?: Record<string, any>;
+    }): Promise<any>;
+    /**
+     * meta 를 바인딩한 스코프 버스 — 이후 emit/request 가 이 meta 를 자동 병합한다(요청 단위 traceId 등).
+     * @param {Record<string, any>} meta @returns {{ emit: Function, on: Function, off: Function, request: Function, with: Function }}
+     */
+    with(meta: Record<string, any>): {
+        emit: Function;
+        on: Function;
+        off: Function;
+        request: Function;
+        with: Function;
+    };
+    /** @returns {Promise<{ driver: string, subscriptions: number }>} */
+    stats(): Promise<{
+        driver: string;
+        subscriptions: number;
+    }>;
+    /** 정리 — 등록 구독 해제 + driver 정리. @returns {Promise<void>} */
+    close(): Promise<void>;
+    #private;
+}
+import { MemoryBusDriver } from './memory-bus.js';
+import { ClusterBusDriver } from './cluster-bus.js';
+import { NatsBusDriver } from './nats-bus.js';
+export { MemoryBusDriver, ClusterBusDriver, NatsBusDriver };

package/types/core/bus/memory-bus.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @typedef {Object} MemorySub - 구독 레코드.
+ * @property {string} pattern @property {(envelope: import('./contract.js').BusEnvelope, reply?: import('./contract.js').ReplyFn, subject?: string) => any} handler
+ * @property {boolean} ordered @property {Promise<void>} tail - ordered 직렬화용 꼬리 프라미스.
+ */
+export class MemoryBusDriver {
+    /** @type {'memory'} */
+    get name(): "memory";
+    /** 매칭 구독에 fan-out. memory 는 persist 무시(opts 는 계약 정합용). @param {string} subject @param {import('./contract.js').BusEnvelope} envelope @param {{ persist?: boolean }} [_opts] @returns {Promise<void>} */
+    publish(subject: string, envelope: import("./contract.js").BusEnvelope, _opts?: {
+        persist?: boolean;
+    }): Promise<void>;
+    /** 구독 등록. @param {string} pattern @param {MemorySub['handler']} handler @param {{ ordered?: boolean }} opts @returns {Promise<import('./contract.js').Subscription>} */
+    subscribe(pattern: string, handler: MemorySub["handler"], { ordered }?: {
+        ordered?: boolean;
+    }): Promise<import("./contract.js").Subscription>;
+    /**
+     * req/reply — 매칭 핸들러에 replyFn 을 주고 첫 응답을 반환. 응답자 없으면 no_responders, 시한 초과면 timeout.
+     * @param {string} subject @param {import('./contract.js').BusEnvelope} envelope @param {{ timeout: number }} opts
+     * @returns {Promise<import('./contract.js').BusEnvelope>}
+     */
+    request(subject: string, envelope: import("./contract.js").BusEnvelope, { timeout }: {
+        timeout: number;
+    }): Promise<import("./contract.js").BusEnvelope>;
+    /** @returns {Promise<{ driver: string, subscriptions: number }>} */
+    stats(): Promise<{
+        driver: string;
+        subscriptions: number;
+    }>;
+    /** 정리 — 구독 비움. @returns {Promise<void>} */
+    close(): Promise<void>;
+    #private;
+}
+/**
+ * - 구독 레코드.
+ */
+export type MemorySub = {
+    pattern: string;
+    handler: (envelope: import("./contract.js").BusEnvelope, reply?: import("./contract.js").ReplyFn, subject?: string) => any;
+    ordered: boolean;
+    /**
+     * - ordered 직렬화용 꼬리 프라미스.
+     */
+    tail: Promise<void>;
+};

package/types/core/bus/nats-bus.d.ts

@@ -0,0 +1,41 @@
+export class NatsBusDriver {
+    /** @param {{ nc: any }} opts - `nc` 빌린 NatsConnection(`busAdapter.native`). */
+    constructor({ nc }: {
+        nc: any;
+    });
+    /** @type {'nats'} */
+    get name(): "nats";
+    /**
+     * 발행 — persist 면 JetStream(영속), 아니면 core pub/sub(비영속).
+     * @param {string} subject @param {import('./contract.js').BusEnvelope} envelope @param {{ persist?: boolean }} opts
+     * @returns {Promise<void>}
+     */
+    publish(subject: string, envelope: import("./contract.js").BusEnvelope, { persist }?: {
+        persist?: boolean;
+    }): Promise<void>;
+    /**
+     * 구독 — persist 면 JetStream ephemeral consumer, 아니면 core 구독. core 는 wildcard·reply 를 native 지원.
+     * @param {string} pattern @param {(envelope: import('./contract.js').BusEnvelope, reply?: import('./contract.js').ReplyFn, subject?: string) => any} handler
+     * @param {{ persist?: boolean, ordered?: boolean }} opts @returns {Promise<import('./contract.js').Subscription>}
+     */
+    subscribe(pattern: string, handler: (envelope: import("./contract.js").BusEnvelope, reply?: import("./contract.js").ReplyFn, subject?: string) => any, { persist, ordered }?: {
+        persist?: boolean;
+        ordered?: boolean;
+    }): Promise<import("./contract.js").Subscription>;
+    /**
+     * req/reply — NATS native request. 첫 응답 envelope 반환. v3 에러 클래스로 timeout/no-responders 판별.
+     * @param {string} subject @param {import('./contract.js').BusEnvelope} envelope @param {{ timeout: number }} opts
+     * @returns {Promise<import('./contract.js').BusEnvelope>}
+     */
+    request(subject: string, envelope: import("./contract.js").BusEnvelope, { timeout }: {
+        timeout: number;
+    }): Promise<import("./contract.js").BusEnvelope>;
+    /** @returns {Promise<{ driver: string, subscriptions: number }>} 영속 구독 수(core 구독은 NATS 측 관리라 미집계). */
+    stats(): Promise<{
+        driver: string;
+        subscriptions: number;
+    }>;
+    /** 정리 — 영속 consumer 정지. nc 는 어댑터 소유라 닫지 않는다. @returns {Promise<void>} */
+    close(): Promise<void>;
+    #private;
+}

package/types/core/index.d.ts

@@ -11,6 +11,7 @@ export { MegaHubLink } from "./hub-link.js";
 export { createSessionCleanupSchedule } from "./session-cleanup-schedule.js";
 export { Router, MegaRouteError } from "./router.js";
 export { bootApp, buildBootContext } from "./boot.js";
+export { getApp, hasApp } from "./app-registry.js";
 export { wrapEnvelope, errorEnvelope, synthesizeEnvelopeResponseSchema, ENVELOPE_MARK } from "./envelope.js";
 export { buildHttpPipeline, wrapPreHandler, composeTransform, composeAfter } from "./pipeline.js";
 export { ajvErrorToValidationError, MAX_VALIDATION_DETAILS } from "./ajv-mapper.js";

package/types/core/lock/cluster-lock.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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?: import("node:cluster").Cluster): MemoryLockDriver | null;
+/** 테스트 격리용 — master responder 설치 플래그 초기화. @returns {void} */
+export function _resetClusterLockMaster(): void;
+/**
+ * 워커 측 cluster 락 driver — master 에 IPC 위임하는 얇은 RPC 클라이언트.
+ * driver 계약은 {@link import('./contract.js').LockDriver} 를 따른다(typedef — 런타임 implements 아님).
+ */
+export class ClusterLockDriver {
+    /**
+     * @param {{ proc?: NodeJS.Process }} [opts] - `proc` 테스트 주입용(기본 전역 process). cluster 워커면
+     *   `process.send` 로 master 에 닿는다.
+     * @throws {Error} proc.send 가 없으면(=cluster 워커가 아님) — factory 가 cluster 워커일 때만 생성한다.
+     */
+    constructor({ proc }?: {
+        proc?: NodeJS.Process;
+    });
+    /** @type {'cluster'} */
+    get name(): "cluster";
+    /** @param {string} key @param {import('./contract.js').NormalizedLockOpts} opts @returns {Promise<import('./contract.js').DriverLock | null>} */
+    acquire(key: string, opts: import("./contract.js").NormalizedLockOpts): Promise<import("./contract.js").DriverLock | null>;
+    /** @param {string} key @param {string} token @returns {Promise<boolean>} */
+    release(key: string, token: string): Promise<boolean>;
+    /** @param {string} key @param {string} token @param {number} ttl @returns {Promise<boolean>} */
+    extend(key: string, token: string, ttl: number): Promise<boolean>;
+    /** @param {string} key @returns {Promise<void>} */
+    forceRelease(key: string): Promise<void>;
+    /** @returns {Promise<{ driver: string, active: number, waiting: number }>} */
+    stats(): Promise<{
+        driver: string;
+        active: number;
+        waiting: number;
+    }>;
+    /** 정리 — IPC 리스너 제거 + 대기 요청에 null 응답(누수 방지). @returns {Promise<void>} */
+    close(): Promise<void>;
+    #private;
+}
+import { MemoryLockDriver } from './memory-lock.js';

package/types/core/lock/contract.d.ts

@@ -0,0 +1,181 @@
+/**
+ * @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(): string;
+/**
+ * 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: {
+    ttl: number;
+    waitMs: number;
+    fifo: boolean;
+}, opts?: LockOpts): NormalizedLockOpts;
+/**
+ * 락 key 검증 — 비어있지 않은 문자열. 저장소 키/redis subject 로 쓰이므로 제어문자·공백을 막는다.
+ * @param {string} key
+ * @returns {void}
+ * @throws {MegaValidationError} `lock.invalid_key`
+ */
+export function assertLockKey(key: string): void;
+/** 락 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;
+/**
+ * - acquire/with/tryAcquire 옵션(정규화 전).
+ */
+export type LockOpts = {
+    /**
+     * - 락 보유 시간(ms, 양의 정수). 미지정 시 manager 디폴트.
+     */
+    ttl?: number;
+    /**
+     * - 획득 대기 상한(ms, 0 이상). 0 = 즉시(tryAcquire 와 동일). 미지정 시 디폴트.
+     */
+    waitMs?: number;
+    /**
+     * - true 면 대기자를 도착 순서대로 깨운다(기아 방지). driver 가 지원해야 함.
+     */
+    fifo?: boolean;
+    /**
+     * - true 면 단조 증가 fence 토큰을 함께 반환(외부 시스템의 stale-writer 차단용).
+     */
+    fence?: boolean;
+    /**
+     * - true 면 manager 가 watchdog 으로 ttl 절반마다 자동 연장(긴 임계구역).
+     */
+    extendable?: boolean;
+};
+/**
+ * - 검증·기본값 적용된 옵션.
+ */
+export type NormalizedLockOpts = {
+    ttl: number;
+    waitMs: number;
+    fifo: boolean;
+    fence: boolean;
+    extendable: boolean;
+};
+/**
+ * - driver.acquire 성공 결과(저수준 — manager 가 LockHandle 로 감싼다).
+ */
+export type DriverLock = {
+    /**
+     * - 이 보유를 식별하는 랜덤 토큰(release/extend 가 소유 검증에 쓴다).
+     */
+    token: string;
+    /**
+     * - fence 토큰(단조 증가). `fence:true` 일 때만.
+     */
+    fence?: number;
+};
+/**
+ * - 사용자에게 반환되는 락 핸들(manager 구성).
+ */
+export type LockHandle = {
+    /**
+     * - 잠근 자원 키.
+     */
+    key: string;
+    /**
+     * - 보유 토큰.
+     */
+    token: string;
+    /**
+     * - fence 토큰(`fence:true` 일 때만).
+     */
+    fence?: number;
+    /**
+     * - 락 해제(idempotent — 이미 풀렸어도 안전). watchdog 도 멈춘다.
+     */
+    release: () => Promise<void>;
+    /**
+     * - TTL 연장. 아직 보유 중이면 true, 잃었으면 false.
+     */
+    extend: (ttl?: number) => Promise<boolean>;
+};
+/**
+ * - driver 가 구현하는 저수준 인터페이스(manager 가 호출).
+ */
+export type LockDriver = {
+    /**
+     * - 'redis' | 'cluster' | 'memory'.
+     */
+    name: string;
+    /**
+     * -
+     * waitMs 안에 획득하면 `{token, fence?}`, 못 잡으면 `null`(throw 아님 — 경합은 정상 결과).
+     */
+    acquire: (key: string, opts: NormalizedLockOpts) => Promise<DriverLock | null>;
+    /**
+     * - 토큰이 현재 보유자면 풀고 true,
+     * 아니면(이미 만료/타인 보유) false. 절대 throw 안 함.
+     */
+    release: (key: string, token: string) => Promise<boolean>;
+    /**
+     * - 토큰이 보유자면 ttl
+     * 갱신 후 true, 아니면 false.
+     */
+    extend: (key: string, token: string, ttl: number) => Promise<boolean>;
+    /**
+     * - 관리용 강제 해제(토큰 무관). 대기자 깨움 포함.
+     */
+    forceRelease: (key: string) => Promise<void>;
+    /**
+     * - 현재 보유/대기 수.
+     */
+    stats: () => Promise<{
+        driver: string;
+        active: number;
+        waiting: number;
+    }>;
+    /**
+     * - 타이머·구독·연결참조 정리(graceful shutdown).
+     */
+    close: () => Promise<void>;
+};

package/types/core/lock/fifo-waitlist.d.ts

@@ -0,0 +1,38 @@
+export class FifoWaitlist {
+    /**
+     * @param {RedisLike} client - ioredis 호환 클라이언트(명령용, redis-lock 과 공유).
+     * @param {{ zkey: (key: string) => string, seqKey: string }} opts -
+     *   `zkey` 락 key → zset 키 매퍼, `seqKey` 전역 시퀀스 카운터 키(네임스페이스 일원화).
+     */
+    constructor(client: RedisLike, { zkey, seqKey }: {
+        zkey: (key: string) => string;
+        seqKey: string;
+    });
+    /**
+     * 대기열에 합류 — 전역 INCR 시퀀스를 점수로 부여해 도착 순서를 확정한다.
+     * @param {string} key @param {string} token @param {number} deadlineMs - 이 대기자의 시한(now+waitMs); reaping 판정용.
+     * @returns {Promise<string>} 등록된 member 문자열(leave 에 그대로 넘겨 정확히 제거).
+     */
+    join(key: string, token: string, deadlineMs: number): Promise<string>;
+    /**
+     * 내가 큐의 head 인지 — 시한 지난(버려진) head 를 청소한 뒤 맨 앞 token 과 비교.
+     * @param {string} key @param {string} token @param {number} nowMs - 현재 시각(Date.now()).
+     * @returns {Promise<boolean>}
+     */
+    isHead(key: string, token: string, nowMs: number): Promise<boolean>;
+    /** 대기열에서 이탈(획득 성공/타임아웃/취소 시). @param {string} key @param {string} member - join 이 돌려준 값. @returns {Promise<void>} */
+    leave(key: string, member: string): Promise<void>;
+    /** 현재 대기자 수. @param {string} key @returns {Promise<number>} */
+    size(key: string): Promise<number>;
+    #private;
+}
+/**
+ * - 이 헬퍼가 쓰는 ioredis 메서드 부분집합(테스트 fake 도 충족).
+ */
+export type RedisLike = {
+    incr: (key: string) => Promise<number>;
+    zadd: (key: string, score: number, member: string) => Promise<any>;
+    zrem: (key: string, member: string) => Promise<any>;
+    zrange: (key: string, start: number, stop: number) => Promise<string[]>;
+    zcard: (key: string) => Promise<number>;
+};

package/types/core/lock/index.d.ts

@@ -0,0 +1,96 @@
+/** 활성 락 manager 설정(boot lock 스테이지). null 로 해제(셧다운/테스트). @param {LockManager | null} manager @returns {void} */
+export function setLockManager(manager: LockManager | null): void;
+/** 현재 활성 락 manager(없으면 null — `ctx.lock.with` 미부착). @returns {LockManager | null} */
+export function getLockManager(): LockManager | null;
+/**
+ * 분산 락 manager 를 만든다 — driver 자동 폴백 포함. boot 가 1회 호출해 `ctx.lock` 에 부착한다.
+ *
+ * @param {{ driver?: string, ttl?: number, waitMs?: number, fifo?: boolean, cache?: string }} [lockConfig] -
+ *   config 의 `lock` 섹션. `cache` 는 redis driver 가 빌릴 cache 어댑터 alias(redis/auto 일 때 의미).
+ * @param {{ logger?: any, redisClient?: any, isClusterWorker?: boolean }} [deps] -
+ *   - `redisClient` boot 가 cache 어댑터에서 빌려 넘긴 ioredis 클라이언트(없으면 null).
+ *   - `isClusterWorker` 현재 프로세스가 cluster 워커인지(`cluster.isWorker`).
+ * @returns {LockManager}
+ */
+export function createLockManager(lockConfig?: {
+    driver?: string;
+    ttl?: number;
+    waitMs?: number;
+    fifo?: boolean;
+    cache?: string;
+}, deps?: {
+    logger?: any;
+    redisClient?: any;
+    isClusterWorker?: boolean;
+}): LockManager;
+/**
+ * `ctx.lock` 콜러블에 사용자 API 메서드를 얹는다 — `ctx.lock(alias)`(기존)와 `ctx.lock.with(...)`(신규) 공존.
+ * boot 가 manager 생성 후 각 앱의 lock accessor 에 1회 호출한다.
+ *
+ * @param {Function & Record<string, any>} lockAccessor - `(alias) => MegaLockAdapter` 콜러블(ctx-builder 산출).
+ * @param {LockManager} manager
+ * @returns {Function & Record<string, any>} 같은 accessor(체이닝용).
+ */
+export function attachLockApi(lockAccessor: Function & Record<string, any>, manager: LockManager): Function & Record<string, any>;
+/**
+ * 사용자 분산 락 API. driver 한 개를 감싸 `with/acquire/tryAcquire/forceRelease/stats` 를 제공한다.
+ */
+export class LockManager {
+    /**
+     * @param {import('./contract.js').LockDriver} driver - 선택된 저수준 driver.
+     * @param {{ defaults: { ttl: number, waitMs: number, fifo: boolean }, logger?: any }} opts
+     */
+    constructor(driver: import("./contract.js").LockDriver, { defaults, logger }: {
+        defaults: {
+            ttl: number;
+            waitMs: number;
+            fifo: boolean;
+        };
+        logger?: any;
+    });
+    /** @returns {string} 활성 driver 이름('redis'|'cluster'|'memory'). */
+    get driverName(): string;
+    /**
+     * 락 획득(대기 후 실패 시 throw) — `try/finally` 로 직접 release 하는 용도.
+     * @param {string} key - 자원 키(비어있지 않은 공백 없는 문자열).
+     * @param {import('./contract.js').LockOpts} [opts] - ttl/waitMs/fifo/fence/extendable.
+     * @returns {Promise<import('./contract.js').LockHandle>}
+     * @throws {MegaConflictError} `lock.not_acquired` - waitMs 안에 못 잡음(자원이 잠겨있음 — 409).
+     * @throws {MegaValidationError} key/opts 부적합.
+     */
+    acquire(key: string, opts?: import("./contract.js").LockOpts): Promise<import("./contract.js").LockHandle>;
+    /**
+     * 락을 즉시 1회만 시도(대기 없음) — 못 잡으면 null(throw 아님).
+     * @param {string} key @param {import('./contract.js').LockOpts} [opts]
+     * @returns {Promise<import('./contract.js').LockHandle | null>}
+     */
+    tryAcquire(key: string, opts?: import("./contract.js").LockOpts): Promise<import("./contract.js").LockHandle | null>;
+    /**
+     * 락 보호 임계구역 실행 — 획득 → fn 실행 → **반드시 해제**(성공/예외 무관). 가장 권장되는 사용법.
+     * @template T
+     * @param {string} key
+     * @param {import('./contract.js').LockOpts | ((lock: import('./contract.js').LockHandle) => Promise<T> | T)} optsOrFn -
+     *   옵션, 또는 옵션을 생략하고 바로 fn(2-인자 형태 `with(key, fn)`).
+     * @param {(lock: import('./contract.js').LockHandle) => Promise<T> | T} [maybeFn] - 3-인자 형태의 fn.
+     * @returns {Promise<T>} fn 의 반환값.
+     */
+    with<T>(key: string, optsOrFn: import("./contract.js").LockOpts | ((lock: import("./contract.js").LockHandle) => Promise<T> | T), maybeFn?: (lock: import("./contract.js").LockHandle) => Promise<T> | T): Promise<T>;
+    /**
+     * 관리용 강제 해제(토큰 무관) — 운영 개입(고아 락 정리)용. 주의: 정상 보유자의 임계구역을 깰 수 있다.
+     * @param {string} key @returns {Promise<void>}
+     */
+    forceRelease(key: string): Promise<void>;
+    /** @returns {Promise<{ driver: string, active: number, waiting: number }>} 현재 보유/대기 수. */
+    stats(): Promise<{
+        driver: string;
+        active: number;
+        waiting: number;
+    }>;
+    /** 정리 — driver 자원(타이머·구독·IPC) 해제. graceful shutdown 에서 호출. @returns {Promise<void>} */
+    close(): Promise<void>;
+    #private;
+}
+import { MemoryLockDriver } from './memory-lock.js';
+import { ClusterLockDriver } from './cluster-lock.js';
+import { RedisLockDriver } from './redis-lock.js';
+export { MemoryLockDriver, ClusterLockDriver, RedisLockDriver };

package/types/core/lock/memory-lock.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @typedef {Object} HeldLock - 보유 중 락 레코드.
+ * @property {string} token @property {number} expiresAt @property {ReturnType<typeof setTimeout>} timer @property {number} [fence]
+ */
+/**
+ * @typedef {Object} Waiter - 대기 큐 항목.
+ * @property {number} ttl @property {boolean} fence @property {(lock: import('./contract.js').DriverLock | null) => void} resolve
+ * @property {ReturnType<typeof setTimeout> | null} timer
+ */
+export class MemoryLockDriver {
+    /** @type {'memory'} */
+    get name(): "memory";
+    /**
+     * 락 획득 — 즉시 가능하면 grant, 아니면 waitMs 안에서 FIFO 큐 대기.
+     * @param {string} key @param {import('./contract.js').NormalizedLockOpts} opts
+     * @returns {Promise<import('./contract.js').DriverLock | null>}
+     */
+    acquire(key: string, { ttl, waitMs, fence }: import("./contract.js").NormalizedLockOpts): Promise<import("./contract.js").DriverLock | null>;
+    /**
+     * 락 해제 — 토큰이 현재 보유자일 때만. 해제 후 다음 대기자 승계.
+     * @param {string} key @param {string} token @returns {Promise<boolean>}
+     */
+    release(key: string, token: string): Promise<boolean>;
+    /**
+     * TTL 연장 — 토큰이 보유자일 때만 만료 타이머 재설정.
+     * @param {string} key @param {string} token @param {number} ttl @returns {Promise<boolean>}
+     */
+    extend(key: string, token: string, ttl: number): Promise<boolean>;
+    /** 강제 해제(관리용, 토큰 무관) — 보유 비우고 다음 대기자 승계. @param {string} key @returns {Promise<void>} */
+    forceRelease(key: string): Promise<void>;
+    /** @returns {Promise<{ driver: string, active: number, waiting: number }>} 보유/대기 수. */
+    stats(): Promise<{
+        driver: string;
+        active: number;
+        waiting: number;
+    }>;
+    /** 정리 — 모든 만료 타이머 해제 + 대기자에 null 응답(graceful shutdown). @returns {Promise<void>} */
+    close(): Promise<void>;
+    #private;
+}
+/**
+ * - 보유 중 락 레코드.
+ */
+export type HeldLock = {
+    token: string;
+    expiresAt: number;
+    timer: ReturnType<typeof setTimeout>;
+    fence?: number;
+};
+/**
+ * - 대기 큐 항목.
+ */
+export type Waiter = {
+    ttl: number;
+    fence: boolean;
+    resolve: (lock: import("./contract.js").DriverLock | null) => void;
+    timer: ReturnType<typeof setTimeout> | null;
+};

package/types/core/lock/redis-lock.d.ts

@@ -0,0 +1,43 @@
+export class RedisLockDriver {
+    /**
+     * @param {{ client: any, createSubscriber?: () => any }} opts
+     *   - `client` ioredis 호환 클라이언트(`set`/`eval`/`incr`/`zadd`… 보유). cache 어댑터의 `.native`.
+     *   - `createSubscriber` Pub/Sub 구독 연결 생성자(기본 `client.duplicate()`). 테스트 주입용.
+     */
+    constructor({ client, createSubscriber }: {
+        client: any;
+        createSubscriber?: () => any;
+    });
+    /** @type {'redis'} */
+    get name(): "redis";
+    /**
+     * 락 획득 — fifo 면 대기열 head 일 때만, 아니면 즉시 SET 후 경합 시 Pub/Sub 대기.
+     * @param {string} key @param {import('./contract.js').NormalizedLockOpts} opts
+     * @returns {Promise<import('./contract.js').DriverLock | null>}
+     */
+    acquire(key: string, { ttl, waitMs, fifo, fence }: import("./contract.js").NormalizedLockOpts): Promise<import("./contract.js").DriverLock | null>;
+    /**
+     * 해제 — 소유 토큰일 때만 DEL + 해제 알림(Lua 원자).
+     * @param {string} key @param {string} token @returns {Promise<boolean>}
+     */
+    release(key: string, token: string): Promise<boolean>;
+    /**
+     * 연장 — 소유 토큰일 때만 PEXPIRE(Lua 원자).
+     * @param {string} key @param {string} token @param {number} ttl @returns {Promise<boolean>}
+     */
+    extend(key: string, token: string, ttl: number): Promise<boolean>;
+    /** 강제 해제(관리용, 토큰 무관) — DEL + 해제 알림(대기자 깨움). @param {string} key @returns {Promise<void>} */
+    forceRelease(key: string): Promise<void>;
+    /**
+     * 통계(best-effort) — `…:v:*`/`…:w:*` 키를 SCAN 으로 센다. O(키 수) 라 운영 관측용(고빈도 호출 비권장).
+     * @returns {Promise<{ driver: string, active: number, waiting: number }>}
+     */
+    stats(): Promise<{
+        driver: string;
+        active: number;
+        waiting: number;
+    }>;
+    /** 정리 — 구독 연결만 quit(명령 클라이언트는 cache 소유라 건드리지 않음). @returns {Promise<void>} */
+    close(): Promise<void>;
+    #private;
+}