mega-framework 0.1.6 → 0.1.8

package/types/lib/mega-worker.d.ts

@@ -0,0 +1,129 @@
+/**
+ * @typedef {object} WorkerHandle - 풀 안의 워커 1개 핸들.
+ * @property {number} id - 핸들 식별자(로그/디버그).
+ * @property {Worker | import('node:child_process').ChildProcess} native - 실제 thread/process.
+ * @property {number | null} current - 처리 중인 taskId(없으면 null).
+ * @property {boolean} down - 종료/크래시 처리됨(중복 처리 가드).
+ */
+/**
+ * @typedef {object} WorkerTask - 디스패치 대기/진행 중인 task 1건.
+ * @property {number} taskId
+ * @property {string} taskName
+ * @property {any} args
+ * @property {{ timeoutMs?: number }} opts
+ * @property {(value: any) => void} resolve
+ * @property {(err: Error) => void} reject
+ * @property {WorkerHandle | null} handle - 배정된 워커(미배정 null).
+ * @property {ReturnType<typeof setTimeout> | null} timer - 타임아웃 타이머.
+ * @property {boolean} isSettled
+ * @property {(() => void) | null} _notify - stop() 의 완료 대기 깨우기.
+ */
+/**
+ * CPU 워커 풀. 서브클래스가 `static name`/`static taskFile`/`static mode`/`static poolSize` 를 선언하고,
+ * 호출자는 `run(taskName, args, opts)` 로 task 를 디스패치한다.
+ */
+export class MegaWorker extends EventEmitter<any> {
+    /**
+     * @param {object} [args]
+     * @param {string} [args.projectRoot] - `static taskFile` 상대경로 해석 기준(디폴트 process.cwd()).
+     * @throws {MegaConfigError} static 설정(taskFile/mode/poolSize)이 잘못됐을 때 — 부팅 fail-fast.
+     */
+    constructor({ projectRoot }?: {
+        projectRoot?: string;
+    });
+    /** @returns {string} 등록 키(= `static name` 오버라이드 또는 클래스명). */
+    get name(): string;
+    /** @returns {'thread' | 'process'} 실행 모드(디폴트 'thread'). */
+    get mode(): "thread" | "process";
+    /** @returns {number} 풀 크기. */
+    get poolSize(): number;
+    /** @returns {number} 윈도우({@link MegaWorker#restartWindowMs}) 내 crash 교체 허용 횟수. */
+    get maxRestarts(): number;
+    /** @returns {number} crash 교체 판정 슬라이딩 윈도우(ms). `static restartWindowMs` 로 조정. */
+    get restartWindowMs(): number;
+    /** @returns {boolean} start() 후 stop() 전이면 true. */
+    get isStarted(): boolean;
+    /** @param {'dispatch'|'done'|'fail'|'crash'|'stopped'} event @param {(payload: any) => void} listener @returns {this} */
+    on(event: "dispatch" | "done" | "fail" | "crash" | "stopped", listener: (payload: any) => void): this;
+    /** @param {'dispatch'|'done'|'fail'|'crash'|'stopped'} event @param {(payload: any) => void} listener @returns {this} */
+    once(event: "dispatch" | "done" | "fail" | "crash" | "stopped", listener: (payload: any) => void): this;
+    /** @param {'dispatch'|'done'|'fail'|'crash'|'stopped'} event @param {(payload: any) => void} listener @returns {this} */
+    off(event: "dispatch" | "done" | "fail" | "crash" | "stopped", listener: (payload: any) => void): this;
+    /**
+     * 워커 풀을 띄운다(`poolSize` 개). 각 워커가 taskFile 을 로드해 `{ ready:true }` 를 보낼 때까지 대기한다
+     * (race 방지). 멱등 — 이미 start 됐으면 무시. taskFile 로드 실패는 spawn 핸드셰이크에서 fail-fast.
+     * @returns {Promise<this>}
+     * @throws {MegaError} 전원 spawn 실패 시 근본 원인(`worker.spawn_failed`)을 전파. 풀 **일부만** 떠도
+     *   성공분을 terminate 한 뒤 `worker.start_partial` 로 fail-fast(M-1 — 누수 방지).
+     */
+    start(): Promise<this>;
+    /**
+     * task 를 워커에 디스패치한다. 유휴 워커가 있으면 즉시, 없으면 큐 대기 후 가용 시 디스패치.
+     * @param {string} taskName - taskFile 이 export 한 함수명.
+     * @param {any} [args] - 함수 인자(structured clone/IPC 가능한 데이터만 — 함수·클래스 인스턴스 X). 직렬화
+     *   불가 인자는 디스패치 시점에 `worker.invalid_args` 로 reject 된다(fail-fast — H-1/M-2, ADR-124 보강).
+     * @param {{ timeoutMs?: number }} [opts] - timeoutMs 초과 시 `worker.task_timeout` reject + 워커 교체.
+     * @returns {Promise<any>} task 함수 반환값.
+     * @throws {MegaError} not_started / stopped / invalid_task / pool_exhausted (즉시 reject) /
+     *   invalid_args (직렬화 불가 인자 — 디스패치 시점 reject).
+     */
+    run(taskName: string, args?: any, opts?: {
+        timeoutMs?: number;
+    }): Promise<any>;
+    /**
+     * graceful shutdown — 새 run() 거부 + 큐 대기분 `worker.stopped` reject + in-flight 완료 대기 → terminate.
+     * `MegaShutdown` 정리 경로에서 호출된다(workers-manager 가 `register('workers:stop', ...)` 배선).
+     * @returns {Promise<this>}
+     */
+    stop(): Promise<this>;
+    #private;
+}
+/**
+ * - 풀 안의 워커 1개 핸들.
+ */
+export type WorkerHandle = {
+    /**
+     * - 핸들 식별자(로그/디버그).
+     */
+    id: number;
+    /**
+     * - 실제 thread/process.
+     */
+    native: Worker | import("node:child_process").ChildProcess;
+    /**
+     * - 처리 중인 taskId(없으면 null).
+     */
+    current: number | null;
+    /**
+     * - 종료/크래시 처리됨(중복 처리 가드).
+     */
+    down: boolean;
+};
+/**
+ * - 디스패치 대기/진행 중인 task 1건.
+ */
+export type WorkerTask = {
+    taskId: number;
+    taskName: string;
+    args: any;
+    opts: {
+        timeoutMs?: number;
+    };
+    resolve: (value: any) => void;
+    reject: (err: Error) => void;
+    /**
+     * - 배정된 워커(미배정 null).
+     */
+    handle: WorkerHandle | null;
+    /**
+     * - 타임아웃 타이머.
+     */
+    timer: ReturnType<typeof setTimeout> | null;
+    isSettled: boolean;
+    /**
+     * - stop() 의 완료 대기 깨우기.
+     */
+    _notify: (() => void) | null;
+};
+import { EventEmitter } from 'node:events';
+import { Worker } from 'node:worker_threads';

package/types/lib/otel-resource.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 공통 입력 → OTel Resource. 시크릿은 attributes 에 싣지 말 것(exporter 로 평문 전송됨).
+ *
+ * @param {object} opts
+ * @param {string} opts.serviceName - **필수**(호출부가 선검증). `service.name` 속성.
+ * @param {string} [opts.version] - `service.version`.
+ * @param {string} [opts.environment] - `deployment.environment.name`.
+ * @param {Record<string, any>} [opts.attributes] - 추가 resource 속성(머지).
+ * @returns {import('@opentelemetry/resources').Resource}
+ */
+export function buildOtelResource({ serviceName, version, environment, attributes }: {
+    serviceName: string;
+    version?: string;
+    environment?: string;
+    attributes?: Record<string, any>;
+}): import("@opentelemetry/resources").Resource;

package/types/lib/worker-runner/process-entry.d.ts

@@ -0,0 +1 @@
+export {};

package/types/lib/worker-runner/task-dispatch.d.ts

@@ -0,0 +1,28 @@
+/**
+ * taskFile 모듈을 동적 import 한다. 절대경로를 file:// URL 로 변환해 OS·ESM 호환성을 보장한다.
+ * @param {string} taskFile - 워커 진입 모듈 절대경로.
+ * @returns {Promise<Record<string, any>>} 모듈 네임스페이스(task 함수들).
+ */
+export function loadTaskModule(taskFile: string): Promise<Record<string, any>>;
+/**
+ * Error 를 스레드/프로세스 경계 너머로 보낼 수 있게 평탄화한다 (structuredClone/IPC 는 Error 인스턴스의
+ * name/message/stack 을 보존하지 않으므로 명시 직렬화). 부모가 이를 받아 다시 Error 로 복원한다.
+ * @param {unknown} err
+ * @returns {{ name: string, message: string, stack?: string, code?: string }}
+ */
+export function serializeError(err: unknown): {
+    name: string;
+    message: string;
+    stack?: string;
+    code?: string;
+};
+/**
+ * 부모가 보낸 task 디스패치 메시지 1건을 처리한다 — 모듈에서 `taskName` 함수를 찾아 실행하고 결과/에러를
+ * 부모로 돌려보낸다. 미존재 task·실행 실패를 묵살하지 않고 `{ ok:false, error }` 로 명시 보고.
+ *
+ * @param {Record<string, any>} mod - loadTaskModule 결과.
+ * @param {any} msg - 부모 메시지 `{ id, taskName, args }`.
+ * @param {(reply: any) => void} send - 부모로 회신하는 채널(`parentPort.postMessage` / `process.send`).
+ * @returns {Promise<void>}
+ */
+export function handleTaskMessage(mod: Record<string, any>, msg: any, send: (reply: any) => void): Promise<void>;

package/types/lib/worker-runner/thread-entry.d.ts

@@ -0,0 +1 @@
+export {};

package/types/lib/ws-hub.d.ts

@@ -0,0 +1,259 @@
+/**
+ * CLI 진입점 — env 로 설정 읽어 hub 기동 (bin/mega-ws-hub.js 에서 호출).
+ *
+ * env: MEGA_WSHUB_TOKENS (필수, 콤마구분 acceptedTokens), MEGA_WSHUB_PORT (기본 3100),
+ *      MEGA_WSHUB_HOST (기본 0.0.0.0), MEGA_WSHUB_HEARTBEAT_MS (선택), MEGA_WSHUB_MAX_PAYLOAD (선택, bytes),
+ *      MEGA_WSHUB_COMPRESSION ('true' 면 압축 ON, ADR-078 디폴트값으로),
+ *      MEGA_WSHUB_COMPRESSION_THRESHOLD (선택, bytes — 압축 ON 일 때만 적용).
+ * 향후 mega.config.js 의 wsHub 블록 로딩으로 대체 (ADR-068) — 그 시점에 6 필드 전체가
+ * config 로 전달된다. 지금 CLI 는 env 한정이라 enabled + threshold 만 노출(나머지는 ADR-078 디폴트).
+ *
+ * SIGTERM/SIGINT 시 MegaShutdown 이 hub.stop({ drain: true })(bridge 소켓 4503 + wss.close)을
+ * 실행한다(L2 + drain) — 독립 hub 종료는 "다른 인스턴스로 재연결" 신호(4503)가 맞다(ADR-098).
+ *
+ * @returns {Promise<MegaWsHub>}
+ */
+export function runWsHubCli(): Promise<MegaWsHub>;
+/** 기본 heartbeat 주기 (ms, 04-data-models MegaWsHubConfig.heartbeatMs 기본값). */
+export const DEFAULT_HEARTBEAT_MS: 25000;
+/** 기본 최대 프레임 크기 (bytes, L3). 1 MiB — 정상 envelope 은 수 KB 이므로 넉넉하다. */
+export const DEFAULT_MAX_PAYLOAD_BYTES: 1048576;
+/**
+ * bridge 별 송신 버퍼(bufferedAmount) 기본 상한(바이트) — 16 MiB. 초과 = 느린 bridge 가 fan-out 을 못
+ * 따라오는 것 → terminate(백프레셔). 클라↔bridge 종단(`ws-upgrade.js` DEFAULT_MAX_BUFFERED_BYTES)과 대칭.
+ */
+export const DEFAULT_MAX_BUFFERED_BYTES: number;
+export class MegaWsHub {
+    /**
+     * @param {Object} [opts]
+     * @param {string[]} [opts.acceptedTokens] - Bridge Bearer 토큰 화이트리스트 (비거나 누락 시 throw).
+     * @param {number} [opts.heartbeatMs=25000] - register_ok 로 알려줄 heartbeat 주기.
+     * @param {number} [opts.maxPayloadBytes=1048576] - WS 프레임 최대 크기(L3). 초과 시 ws 가 1009 close.
+     * @param {number} [opts.maxBufferedBytes=16777216] - bridge 별 송신 버퍼(bufferedAmount) 상한(바이트).
+     *   초과한 bridge 는 느린 소비자로 보고 terminate 한다 — fan-out 허브에서 bridge 1개가 느려도 모든
+     *   채널 메시지가 그 소켓 버퍼(힙)에 무한 적재돼 OOM 으로 가는 것을 막는다(백프레셔).
+     * @param {string} [opts.hubId] - hub 식별자. 기본 ULID 자동 생성.
+     * @param {import('../core/ws-compression.js').WsCompressionConfig} [opts.compression] - Bridge↔Hub
+     *   link per-message deflate 압축(ADR-078 / wsHub.compression). 디폴트 OFF.
+     *   bridge(MegaHubLink)와 양쪽이 협상해야 활성. 잘못된 threshold/windowBits 면 즉시 throw.
+     * @param {{ warn?: Function, debug?: Function, info?: Function, error?: Function }} [opts.logger]
+     */
+    constructor({ acceptedTokens, heartbeatMs, maxPayloadBytes, maxBufferedBytes, hubId, compression, logger }?: {
+        acceptedTokens?: string[];
+        heartbeatMs?: number;
+        maxPayloadBytes?: number;
+        maxBufferedBytes?: number;
+        hubId?: string;
+        compression?: import("../core/ws-compression.js").WsCompressionConfig;
+        logger?: {
+            warn?: Function;
+            debug?: Function;
+            info?: Function;
+            error?: Function;
+        };
+    });
+    _acceptedTokens: string[];
+    _heartbeatMs: number;
+    _maxPayloadBytes: number;
+    _maxBufferedBytes: number;
+    _hubId: string;
+    /** @type {false | Object} WebSocketServer perMessageDeflate 로 전달(start). */
+    _perMessageDeflate: false | Object;
+    _log: {
+        warn?: Function;
+        debug?: Function;
+        info?: Function;
+        error?: Function;
+    };
+    /** @type {WebSocketServer | null} */
+    _wss: WebSocketServer | null;
+    /** heartbeat liveness 체크 interval (M3). @type {ReturnType<typeof setInterval> | null} */
+    _livenessTimer: ReturnType<typeof setInterval> | null;
+    /** 등록된 bridge 연결. connId → { socket, lastSeen, protocolVersion, presenceFanout }. @type {Map<string, { socket: import('ws').WebSocket, lastSeen: number, protocolVersion?: number, presenceFanout?: boolean }>} */
+    _bridges: Map<string, {
+        socket: import("ws").WebSocket;
+        lastSeen: number;
+        protocolVersion?: number;
+        presenceFanout?: boolean;
+    }>;
+    /** presence. sessionId → { bridgeConnId, userId, channels:Set, metadata }. @type {Map<string, { bridgeConnId: string, userId: string, channels: Set<string>, metadata: Object }>} */
+    _sessions: Map<string, {
+        bridgeConnId: string;
+        userId: string;
+        channels: Set<string>;
+        metadata: Object;
+    }>;
+    /** channel → sessionId 집합. @type {Map<string, Set<string>>} */
+    _channelSessions: Map<string, Set<string>>;
+    /** userId → sessionId 집합 (DIRECT fan-out, ADR-035). @type {Map<string, Set<string>>} */
+    _userSessions: Map<string, Set<string>>;
+    /**
+     * 역인덱스: channel → (bridgeConnId → 그 bridge 의 채널 내 세션 수). BROADCAST 의 bridge 선정을
+     * 세션 수 무관 O(bridge 수)로 만든다 — 멤버 10k 채널에서 메시지당 수백 µs 가 µs 대로 떨어진다.
+     * `_addSession`/`_removeSession` 이 증분 유지(카운트 0 → 키 제거), 메모리는 채널×bridge 수준.
+     * @type {Map<string, Map<string, number>>}
+     */
+    _channelBridges: Map<string, Map<string, number>>;
+    /** hub 식별자. */
+    get hubId(): string;
+    /** 등록된 bridge 수 (테스트/관측용). */
+    get bridgeCount(): number;
+    /** 현재 presence 세션 수 (테스트/관측용). */
+    get sessionCount(): number;
+    /**
+     * hub 시작.
+     * @param {{ port?: number, host?: string }} [opts]
+     * @returns {Promise<{ port: number, host: string }>} 실제 바인딩 주소.
+     */
+    start({ port, host }?: {
+        port?: number;
+        host?: string;
+    }): Promise<{
+        port: number;
+        host: string;
+    }>;
+    /** 현재 바인딩 주소 (테스트용). */
+    address(): {
+        port: number;
+        host: string;
+    };
+    /**
+     * 연결 1건 처리. register 전엔 hub.register 만 허용. 인증 통과 시 presence 라우팅 활성.
+     * @param {import('ws').WebSocket} socket
+     * @param {import('node:http').IncomingMessage} _req
+     * @private
+     */
+    private _onConnection;
+    /**
+     * hub.register 처리 — Bearer 검증(timing-safe). 성공 시 bridge 등록 + register_ok.
+     * @param {string} connId
+     * @param {import('ws').WebSocket} socket
+     * @param {Object} msg - 검증된 hub.register envelope.
+     * @returns {boolean} 등록 성공 여부(연결의 isRegistered 갱신용).
+     * @private
+     */
+    private _handleRegister;
+    /**
+     * 등록된 bridge 의 수신 메시지 라우팅 (12-타입).
+     * @param {string} connId
+     * @param {import('ws').WebSocket} socket
+     * @param {Object} msg - 검증된 hub 메시지.
+     * @returns {void}
+     * @private
+     */
+    private _route;
+    /**
+     * presence 에 세션 추가.
+     *
+     * sessionId 가 이미 존재하면(같은 세션 재JOIN, 또는 채널 변경) 먼저 옛 매핑을 정리한 뒤 재삽입한다
+     * — 그러지 않으면 옛 채널 인덱스(`_channelSessions`)에 stale 엔트리가 남는다(채널이 바뀐 경우).
+     * 옛 매핑이 **다른 bridge** 소속이면 "sessionId 전역 유일" 계약(ADR-059) 위반이므로 warn 로그를 남기고
+     * last-writer 로 재배정한다 — silent 덮어쓰기 금지(L-3). 이렇게 하면 옛 bridge 의 채널 인덱스가
+     * 제거되어, 옛 bridge 의 `_handleBridgeGone` 이 재배정된 세션을 잘못 지우는 일도 없어진다.
+     *
+     * @param {string} connId
+     * @param {{ userId: string, sessionId: string, channels: string[], metadata?: Object }} entry
+     * @private
+     */
+    private _addSession;
+    /**
+     * channel→bridge 역인덱스 증분 갱신. 카운트가 0 이 되면 키를 지워 인덱스가 stale 하지 않게 한다.
+     * @param {string} channel @param {string} connId @param {1|-1} delta
+     * @private
+     */
+    private _bumpChannelBridge;
+    /**
+     * presence 에서 세션 제거. 빈 인덱스는 정리.
+     * @param {string} sessionId
+     * @returns {boolean} 실제 제거 여부.
+     * @private
+     */
+    private _removeSession;
+    /**
+     * bridge 연결 종료 시 — 그 bridge 의 모든 세션 제거 + 다른 bridge 에 bulk_leave 통지.
+     * @param {string} connId
+     * @private
+     */
+    private _handleBridgeGone;
+    /**
+     * origin 을 제외한 모든 등록 bridge 로 송신. envelope 는 1회만 직렬화(L5).
+     * BULK_LEAVE(bridge-gone 정리 통지)처럼 전 bridge 가 받아야 하는 통지에 쓴다.
+     * @param {string} exceptConnId
+     * @param {Object} envelope
+     * @private
+     */
+    private _fanOutToOthers;
+    /**
+     * presence(JOIN/LEAVE/METADATA) fan-out — `presence-fanout` capability 를 선언한 bridge 에만 송신.
+     * roster 가 redis 로 분리(ADR-177)된 뒤 표준 bridge 는 이 타입들을 no-op 으로 버리므로, 옵트인하지
+     * 않은 bridge 에는 보내지 않는다 — 세션 churn × bridge 수 만큼의 죽은 프레임을 제거한다.
+     * 구버전 bridge 호환: hub presence 를 실제로 쓰려는 bridge 는 capability 로 명시 선언한다.
+     * @param {string} exceptConnId
+     * @param {Object} envelope
+     * @private
+     */
+    private _fanOutPresence;
+    /**
+     * 한 채널의 세션을 가진 bridge 들로 fan-out (origin 제외, 중복 bridge 1회). 직렬화 1회(L5).
+     *
+     * `exceptSessionIds` 가 있으면 해당 세션은 bridge 선정에서 제외한다(ADR-098). 어떤 bridge 의
+     * 채널 세션이 **전부** 제외 대상이면 그 bridge 는 통째로 스킵된다(불필요한 전송 절약). 일부만 제외면
+     * bridge 는 받아서 로컬에서 해당 세션만 건너뛴다(envelope 의 payload.exceptSessionIds 가 그대로 전달됨).
+     *
+     * @param {string} channel
+     * @param {string} exceptConnId
+     * @param {Object} envelope
+     * @param {string[]} [exceptSessionIds] - fan-out 에서 뺄 세션 목록(BROADCAST payload).
+     * @private
+     */
+    private _fanOutChannel;
+    /**
+     * 한 user 의 세션을 가진 bridge 들로 fan-out (DIRECT, ADR-035). origin 제외(L7) — origin 은
+     * local 직접 전달하므로 hub 가 되돌리지 않는다(BROADCAST 와 동일 패턴). 직렬화 1회(L5).
+     * @param {string} userId
+     * @param {Object} envelope
+     * @param {string} [exceptConnId] - 제외할 origin bridge connId.
+     * @private
+     */
+    private _fanOutUser;
+    /**
+     * connId 로 직렬화된 프레임 송신 (등록된 bridge 한정).
+     * @param {string} connId
+     * @param {string} serialized - 이미 JSON.stringify 된 envelope.
+     * @private
+     */
+    private _sendTo;
+    /**
+     * 단일 envelope 송신 — 직렬화 후 위임 (register_ok/error/heartbeat 등 1:1 송신용).
+     * @param {import('ws').WebSocket} socket
+     * @param {Object} envelope
+     * @private
+     */
+    private _safeSend;
+    /**
+     * 직렬화된 프레임 소켓 송신 — 닫히는 중 등 실패는 비치명적(이유+로그).
+     * @param {import('ws').WebSocket} socket
+     * @param {string} serialized
+     * @private
+     */
+    private _sendSerialized;
+    /**
+     * heartbeat liveness 감시(M3) — heartbeatMs*2 이상 HEARTBEAT 미수신 bridge 를 정리 후 terminate.
+     * half-open 연결(TCP 는 살아있으나 상대가 죽음)이 presence 에 영구 잔존하는 것을 막는다.
+     * @private
+     */
+    private _checkLiveness;
+    /**
+     * hub 종료 — liveness 타이머 정리 + 모든 bridge 연결 닫고 서버 close.
+     *
+     * `drain: true` 면 bridge 소켓을 close code **4503**(DRAIN, ADR-098) 로 닫는다 — bridge 가 "다른 hub
+     * 인스턴스로 재연결하라" 로 해석한다(LB/mesh 회전). 기본(false)은 1001(GOING_AWAY) — 일반 종료.
+     *
+     * @param {{ drain?: boolean }} [opts]
+     * @returns {Promise<void>}
+     */
+    stop({ drain }?: {
+        drain?: boolean;
+    }): Promise<void>;
+}
+import { WebSocketServer } from 'ws';

package/types/models/crud-sql-builder.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @typedef {Object} CrudDialect - dialect 모듈의 DML facet(ADR-212) 일부.
+ * @property {(name: string) => string} quoteIdent
+ * @property {(i: number) => string} placeholder
+ */
+/** 컬럼이 schema 화이트리스트에 있는지 — 없으면 throw. @param {string} col @param {Set<string>} cols @param {string} model @param {string} where */
+export function assertColumn(col: string, cols: Set<string>, model: string, where: string): void;
+/** limit/offset 정수 검증 — 음수/비정수 throw, 통과하면 그 정수 반환. @param {unknown} v @param {string} name @param {string} model @returns {number} */
+export function assertNonNegInt(v: unknown, name: string, model: string): number;
+/**
+ * filter → WHERE 조각(접두 'WHERE' 없음) + params + 다음 placeholder 인덱스.
+ * 등호 AND + `IN`(배열) + `IS NULL`(null) 만(ADR-212 경계). `undefined` 값은 throw, 빈 배열은 `1=0`(매칭 0).
+ *
+ * @param {Record<string, any>} filter
+ * @param {Set<string>} cols - schema 컬럼 화이트리스트
+ * @param {CrudDialect} dialect
+ * @param {string} model - 에러 메시지용
+ * @param {number} [startIndex=1] - placeholder 시작 인덱스(SET 뒤 WHERE 처럼 이어붙일 때)
+ * @returns {{ clause: string, params: any[], nextIndex: number }}
+ */
+export function buildWhere(filter: Record<string, any>, cols: Set<string>, dialect: CrudDialect, model: string, startIndex?: number): {
+    clause: string;
+    params: any[];
+    nextIndex: number;
+};
+/**
+ * orderBy 옵션 → `ORDER BY ...` 조각(없으면 ''). 컬럼 화이트리스트 + dir enum.
+ * @param {string | Array<{ column: string, dir?: 'asc'|'desc' }> | undefined} orderBy
+ * @param {Set<string>} cols @param {CrudDialect} dialect @param {string} model
+ * @returns {string}
+ */
+export function buildOrderBy(orderBy: string | Array<{
+    column: string;
+    dir?: "asc" | "desc";
+}> | undefined, cols: Set<string>, dialect: CrudDialect, model: string): string;
+/**
+ * select 옵션 → 컬럼 목록 조각(`*` 또는 인용 컬럼). 화이트리스트 검증.
+ * @param {string[] | undefined} select @param {Set<string>} cols @param {CrudDialect} dialect @param {string} model
+ * @returns {string}
+ */
+export function buildSelectList(select: string[] | undefined, cols: Set<string>, dialect: CrudDialect, model: string): string;
+/**
+ * - dialect 모듈의 DML facet(ADR-212) 일부.
+ */
+export type CrudDialect = {
+    quoteIdent: (name: string) => string;
+    placeholder: (i: number) => string;
+};

package/types/models/index.d.ts

@@ -0,0 +1 @@
+export { MegaModel } from "./mega-model.js";

package/types/models/mega-model.d.ts

@@ -0,0 +1,138 @@
+export class MegaModel {
+    /**
+     * 어댑터 globalKey — `mega.config.js` 의 `services.databases.<key>` 와 정확히 일치 (ADR-061).
+     * 서브클래스가 박는다. 비어 있으면 db/withTransaction 접근 시 throw.
+     * @type {string}
+     */
+    static adapter: string;
+    /**
+     * 데이터 소스 식별자. SQL 의 table 또는 MongoDB 의 collection 모두 본 필드에 명시 (ADR-081).
+     * 어댑터별 native 호출 시 의미는 동일. 비어 있으면 db/withTransaction 접근 시 throw.
+     * @type {string}
+     */
+    static table: string;
+    /**
+     * 자동 lookup — `adapter` 키로 어댑터의 driver native handle 반환
+     * (pg Pool / MongoClient / mariadb Pool / better-sqlite3 Database, ADR-009).
+     *
+     * 어댑터가 아직 `connect()` 전이면 어댑터 베이스가 `adapter.not_connected` 를 throw 한다
+     * (08-class-specs §3.2 불변식 — native 는 연결 후에만 유효).
+     *
+     * @returns {any} driver native handle.
+     */
+    static get db(): any;
+    /**
+     * 명시적 트랜잭션 경계 (ADR-010). 어댑터의 `withTransaction` 에 위임한다 — 성공 시 commit,
+     * `fn` 이 throw 하면 driver native rollback 후 원본 에러 re-throw. **자동 request-scoped
+     * 트랜잭션은 만들지 않는다** (ADR-010).
+     *
+     * `fn` 이 받는 인자는 **트랜잭션 컨텍스트의 native handle**(예: pg client) 이다. 같은 모델의
+     * 다른 메서드(`this.db.query`)는 트랜잭션 **밖** 글로벌 handle 을 쓰므로, 트랜잭션 안에서는
+     * `fn` 인자를 명시적으로 써야 격리가 유지된다 (08-class-specs §3.1 — 사용자 책임).
+     *
+     * nested 트랜잭션 정책(postgres SAVEPOINT / Mongo throw)은 **구체 어댑터 책임**이다.
+     * 베이스는 위임만 한다.
+     *
+     * `fn` 인자 수는 어댑터별로 다르다 — SQL 어댑터는 `(client)` 1개, Mongo 어댑터는 `(db, session)`
+     * 2개를 넘긴다(ADR-108). 따라서 가변 인자로 타입을 둔다(어댑터가 인자 형태의 정본).
+     *
+     * `opts.isolation`(ADR-190) — SQL 격리수준 옵트인. driver 별 지원·제약은 어댑터가 정본
+     * (postgres/maria=top-level 만, sqlite='serializable' 만, mongodb=미지원 throw).
+     *
+     * @template T
+     * @param {(...args: any[]) => Promise<T>} fn - 트랜잭션 컨텍스트 native handle(들)을 받는 콜백.
+     * @param {{ isolation?: 'read uncommitted' | 'read committed' | 'repeatable read' | 'serializable' }} [opts] - 트랜잭션 옵션(ADR-190).
+     * @returns {Promise<T>}
+     */
+    static withTransaction<T>(fn: (...args: any[]) => Promise<T>, opts?: {
+        isolation?: "read uncommitted" | "read committed" | "repeatable read" | "serializable";
+    }): Promise<T>;
+    /**
+     * **계측된 쿼리** — `this.db.query`(native handle 직접 호출, 트레이싱 미통과)와 달리 어댑터의
+     * `query` 도메인 메서드에 위임해 자동 span(`<driver>.query`)·메트릭·stats 에 잡힌다(ADR-138).
+     * 진행 중 트랜잭션이 있으면 어댑터가 같은 connection 으로 실행하므로, `withTransaction(async (tx) => …)`
+     * 콜백 안에서 `Model.query(sql, params)` 를 부르면 격리가 유지되고 span 도 트랜잭션 span 의 자식이 된다
+     * (native `tx.query`는 계측 미통과 escape hatch). SQL 어댑터(postgres/maria/sqlite) 전용 — Document
+     * DB(mongo)는 `adapter.not_implemented`.
+     *
+     * @param {string} sql - 파라미터화된 SQL(placeholder 보존 — 값 인터폴레이션 금지).
+     * @param {any[]} [params] - placeholder 바인딩 값.
+     * @returns {Promise<any>} driver native 쿼리 결과(어댑터별 형태 — ADR-009).
+     */
+    static query(sql: string, params?: any[]): Promise<any>;
+    /** 단건 조회(없으면 null). filter 는 등호 AND + 배열 IN + null IS NULL. @param {Record<string, any>} filter @param {{ select?: string[] }} [opts] @returns {Promise<any|null>} */
+    static findOne(filter: Record<string, any>, opts?: {
+        select?: string[];
+    }): Promise<any | null>;
+    /** PK 단건 조회(단일 PK 필요, 없으면 model.no_primary_key). @param {any} id @param {{ select?: string[] }} [opts] @returns {Promise<any|null>} */
+    static findById(id: any, opts?: {
+        select?: string[];
+    }): Promise<any | null>;
+    /** 다건 조회(기본 limit 없음 — 명시할 때만, ADR-212 #2). @param {Record<string, any>} [filter] @param {{ select?: string[], orderBy?: string | Array<{ column: string, dir?: 'asc'|'desc' }>, limit?: number, offset?: number }} [opts] @returns {Promise<any[]>} */
+    static findMany(filter?: Record<string, any>, opts?: {
+        select?: string[];
+        orderBy?: string | Array<{
+            column: string;
+            dir?: "asc" | "desc";
+        }>;
+        limit?: number;
+        offset?: number;
+    }): Promise<any[]>;
+    /** 조건 매칭 행 수. @param {Record<string, any>} [filter] @returns {Promise<number>} */
+    static count(filter?: Record<string, any>): Promise<number>;
+    /** 조건 매칭 행 존재 여부. @param {Record<string, any>} filter @returns {Promise<boolean>} */
+    static exists(filter: Record<string, any>): Promise<boolean>;
+    /** 페이지 조회. total 은 `{ withTotal: true }` 일 때만 추가 count(ADR-212 #4). @param {Record<string, any>} filter @param {{ select?: string[], orderBy?: any, limit: number, offset?: number, withTotal?: boolean }} opts @returns {Promise<{ rows: any[], limit: number, offset: number, total?: number }>} */
+    static paginate(filter: Record<string, any>, opts: {
+        select?: string[];
+        orderBy?: any;
+        limit: number;
+        offset?: number;
+        withTotal?: boolean;
+    }): Promise<{
+        rows: any[];
+        limit: number;
+        offset: number;
+        total?: number;
+    }>;
+    /** 단건 삽입. 기본 새 id 반환, `{ returning: true }` 면 레코드(ADR-212 #1). @param {Record<string, any>} data @param {{ returning?: boolean }} [opts] @returns {Promise<any>} */
+    static insertOne(data: Record<string, any>, opts?: {
+        returning?: boolean;
+    }): Promise<any>;
+    /** 다건 삽입. 기본 `{ count }`, `{ returning: true }` 면 레코드 배열(maria 미지원→throw). @param {Record<string, any>[]} rows @param {{ returning?: boolean }} [opts] @returns {Promise<{ count: number } | any[]>} */
+    static insertMany(rows: Record<string, any>[], opts?: {
+        returning?: boolean;
+    }): Promise<{
+        count: number;
+    } | any[]>;
+    /** 정확히 한 행 갱신(>1 매칭→롤백 후 model.multiple_matches, ADR-212 #3). 변경 행 수 반환. @param {Record<string, any>} filter @param {Record<string, any>} patch @returns {Promise<number>} */
+    static updateOne(filter: Record<string, any>, patch: Record<string, any>): Promise<number>;
+    /** 다건 갱신. 빈 filter 는 차단 — 전체 갱신은 `{ all: true }`. @param {Record<string, any>} filter @param {Record<string, any>} patch @param {{ all?: boolean }} [opts] @returns {Promise<number>} */
+    static updateMany(filter: Record<string, any>, patch: Record<string, any>, opts?: {
+        all?: boolean;
+    }): Promise<number>;
+    /** 정확히 한 행 삭제(>1 매칭→롤백 후 model.multiple_matches). 삭제 행 수 반환. @param {Record<string, any>} filter @returns {Promise<number>} */
+    static deleteOne(filter: Record<string, any>): Promise<number>;
+    /** 다건 삭제. 빈 filter 는 차단 — 전체 삭제는 `{ all: true }`. @param {Record<string, any>} filter @param {{ all?: boolean }} [opts] @returns {Promise<number>} */
+    static deleteMany(filter: Record<string, any>, opts?: {
+        all?: boolean;
+    }): Promise<number>;
+    /** upsert(INSERT … ON CONFLICT/DUPLICATE KEY UPDATE). `opts.conflict` 는 PK/unique 컬럼 필수. @param {Record<string, any>} data @param {{ conflict: string[], update?: string[], returning?: boolean }} opts @returns {Promise<any>} */
+    static upsert(data: Record<string, any>, opts: {
+        conflict: string[];
+        update?: string[];
+        returning?: boolean;
+    }): Promise<any>;
+    /**
+     * `adapter`/`table` 정합성을 검증하고 글로벌 매니저에서 어댑터(MegaDbAdapter)를 잡아 반환한다.
+     *
+     * 정본은 "부팅 시 검증"(08-class-specs §3.1 라이프사이클, ADR-067)을 말하지만, 중앙 부팅
+     * 오케스트레이터(`mega serve` CLI)가 아직 미배선이라(ADR-102 미결 항목) **접근 시점 lazy 검증**
+     * 으로 둔다 — `ctx.db(alias)` 가 미등록 별명을 즉시 throw 하는 것과 같은 패턴(ADR-102).
+     * 오케스트레이터가 생기면 부팅 시 일괄 검증을 추가한다(ADR-104).
+     *
+     * @protected
+     * @returns {import('../adapters/mega-db-adapter.js').MegaDbAdapter}
+     */
+    protected static _resolveAdapter(): import("../adapters/mega-db-adapter.js").MegaDbAdapter;
+}