mega-framework 0.1.10 → 0.1.13

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

@@ -0,0 +1,164 @@
+/**
+ * @typedef {Object} BusEnvelope - wire/IPC 로 오가는 메시지 봉투(payload 와 meta 분리 — meta 는 traceId 등).
+ * @property {any} payload - 사용자 데이터.
+ * @property {Record<string, any>} [meta] - 부가 메타(전파용). 없으면 빈 객체로 취급.
+ */
+/**
+ * @typedef {Object} EmitOpts - emit 옵션.
+ * @property {Record<string, any>} [meta] - 이 메시지의 meta.
+ * @property {boolean} [persist] - true 면 영속 전달(JetStream — nats-bus 만; 그 외 driver 는 경고 후 비영속).
+ */
+/**
+ * @typedef {Object} OnOpts - on(구독) 옵션.
+ * @property {boolean} [persist] - true 면 영속 구독(JetStream consumer — nats-bus 만).
+ * @property {boolean} [ordered] - true 면 같은 subject 메시지를 순서대로 1건씩 직렬 처리(핸들러 await 직렬화).
+ */
+/**
+ * @typedef {(payload: any, meta: Record<string, any>, subject: string) => any} BusHandler - 사용자 핸들러.
+ *   3번째 인자 `subject` 는 메시지가 도착한 **구체** subject(prefix 제거됨) — wildcard 구독에서 어느 subject 가
+ *   매칭됐는지 안다. `meta.subject` 에도 같은 값이 담긴다(정본 위치). request 대상이면 **반환값이 reply**.
+ */
+/**
+ * @typedef {Object} Subscription - on/subscribe 가 돌려주는 구독 핸들.
+ * @property {() => Promise<void>} unsubscribe - 구독 해제.
+ */
+/**
+ * @typedef {(envelope: BusEnvelope) => void} ReplyFn - driver 가 핸들러에 주는 응답 함수(request 일 때만).
+ *
+ * @typedef {Object} BusDriver - driver 가 구현하는 저수준 인터페이스(manager 가 호출).
+ * @property {string} name - 'nats' | 'cluster' | 'memory'.
+ * @property {(subject: string, envelope: BusEnvelope, opts: { persist?: boolean }) => Promise<void>} publish -
+ *   fire-and-forget 발행(구독자 전원 fan-out).
+ * @property {(subject: string, handler: (envelope: BusEnvelope, reply?: ReplyFn, subject?: string) => any, opts: { persist?: boolean, ordered?: boolean }) => Promise<Subscription>} subscribe -
+ *   구독(subject 는 wildcard 가능). `reply` 는 request 로 들어온 메시지일 때만 제공. 핸들러의 3번째 인자는
+ *   매칭된 **구체** subject(driver 가 채워 manager 로 넘김 — wildcard 어디로 왔는지 안다).
+ * @property {(subject: string, envelope: BusEnvelope, opts: { timeout: number }) => Promise<BusEnvelope>} request -
+ *   req/reply — 첫 응답 envelope 반환. 응답자 없으면 `bus.no_responders`, 시한 초과면 `bus.request_timeout` throw.
+ * @property {() => Promise<{ driver: string, subscriptions: number }>} stats - 현재 구독 수.
+ * @property {() => Promise<void>} close - 구독·타이머·IPC·연결참조 정리.
+ */
+/**
+ * subject 정규화 — prefix 를 앞에 붙인다(네임스페이스 격리). prefix 가 빈 값이면 그대로.
+ * @param {string} subject @param {string} [prefix] - 예: 'app.'.
+ * @returns {string}
+ */
+export function normalizeSubject(subject: string, prefix?: string): string;
+/**
+ * subject 검증 — 비어있지 않고 공백/제어문자 없는 문자열. publish subject 는 wildcard 금지(구체적이어야 함).
+ * @param {string} subject @param {{ allowWildcard?: boolean }} [opts] - true 면 `*`/`>` 허용(구독용).
+ * @returns {void}
+ * @throws {MegaValidationError} `bus.invalid_subject`
+ */
+export function assertSubject(subject: string, { allowWildcard }?: {
+    allowWildcard?: boolean;
+}): void;
+/**
+ * NATS 식 wildcard 매칭 — cluster/memory-bus 의 자체 패턴 매칭(nats-bus 는 NATS native 사용).
+ *   `*` = 한 토큰, `>` = 한 토큰 이상(꼬리). 토큰 수가 정확히 맞아야 매칭(`>` 제외).
+ * @param {string} pattern - 구독 패턴(wildcard 가능). @param {string} subject - 구체 subject.
+ * @returns {boolean}
+ */
+export function matchSubject(pattern: string, subject: string): boolean;
+/** request/reply 응답 대기 디폴트(ms). config `bus.requestTimeoutMs` 로 조정. */
+export const DEFAULT_REQUEST_TIMEOUT_MS: 5000;
+/**
+ * - wire/IPC 로 오가는 메시지 봉투(payload 와 meta 분리 — meta 는 traceId 등).
+ */
+export type BusEnvelope = {
+    /**
+     * - 사용자 데이터.
+     */
+    payload: any;
+    /**
+     * - 부가 메타(전파용). 없으면 빈 객체로 취급.
+     */
+    meta?: Record<string, any>;
+};
+/**
+ * - emit 옵션.
+ */
+export type EmitOpts = {
+    /**
+     * - 이 메시지의 meta.
+     */
+    meta?: Record<string, any>;
+    /**
+     * - true 면 영속 전달(JetStream — nats-bus 만; 그 외 driver 는 경고 후 비영속).
+     */
+    persist?: boolean;
+};
+/**
+ * - on(구독) 옵션.
+ */
+export type OnOpts = {
+    /**
+     * - true 면 영속 구독(JetStream consumer — nats-bus 만).
+     */
+    persist?: boolean;
+    /**
+     * - true 면 같은 subject 메시지를 순서대로 1건씩 직렬 처리(핸들러 await 직렬화).
+     */
+    ordered?: boolean;
+};
+/**
+ * - 사용자 핸들러.
+ *   3번째 인자 `subject` 는 메시지가 도착한 **구체** subject(prefix 제거됨) — wildcard 구독에서 어느 subject 가
+ *   매칭됐는지 안다. `meta.subject` 에도 같은 값이 담긴다(정본 위치). request 대상이면 **반환값이 reply**.
+ */
+export type BusHandler = (payload: any, meta: Record<string, any>, subject: string) => any;
+/**
+ * - on/subscribe 가 돌려주는 구독 핸들.
+ */
+export type Subscription = {
+    /**
+     * - 구독 해제.
+     */
+    unsubscribe: () => Promise<void>;
+};
+/**
+ * - driver 가 핸들러에 주는 응답 함수(request 일 때만).
+ */
+export type ReplyFn = (envelope: BusEnvelope) => void;
+/**
+ * - driver 가 구현하는 저수준 인터페이스(manager 가 호출).
+ */
+export type BusDriver = {
+    /**
+     * - 'nats' | 'cluster' | 'memory'.
+     */
+    name: string;
+    /**
+     * -
+     * fire-and-forget 발행(구독자 전원 fan-out).
+     */
+    publish: (subject: string, envelope: BusEnvelope, opts: {
+        persist?: boolean;
+    }) => Promise<void>;
+    /**
+     * -
+     * 구독(subject 는 wildcard 가능). `reply` 는 request 로 들어온 메시지일 때만 제공. 핸들러의 3번째 인자는
+     * 매칭된 **구체** subject(driver 가 채워 manager 로 넘김 — wildcard 어디로 왔는지 안다).
+     */
+    subscribe: (subject: string, handler: (envelope: BusEnvelope, reply?: ReplyFn, subject?: string) => any, opts: {
+        persist?: boolean;
+        ordered?: boolean;
+    }) => Promise<Subscription>;
+    /**
+     * -
+     * req/reply — 첫 응답 envelope 반환. 응답자 없으면 `bus.no_responders`, 시한 초과면 `bus.request_timeout` throw.
+     */
+    request: (subject: string, envelope: BusEnvelope, opts: {
+        timeout: number;
+    }) => Promise<BusEnvelope>;
+    /**
+     * - 현재 구독 수.
+     */
+    stats: () => Promise<{
+        driver: string;
+        subscriptions: number;
+    }>;
+    /**
+     * - 구독·타이머·IPC·연결참조 정리.
+     */
+    close: () => Promise<void>;
+};

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>;
+};