mega-framework 0.1.6 → 0.1.8

package/src/{cli → lib}/ws-hub.js

@@ -23,7 +23,7 @@
  *   ADR-094 의 ASP echo 데모 hub 를 본 12-타입 hub 로 교체(ADR-097). 클라↔bridge ASP
  *   round-trip 검증은 embedded 종단(`core/ws-upgrade.js`, ws-upgrade.integration)으로 이전됨.
  *
- * @module cli/ws-hub
+ * @module lib/ws-hub
  */
 import { createHash, timingSafeEqual } from 'node:crypto'
 import { WebSocketServer } from 'ws'
@@ -32,8 +32,10 @@ import { buildPerMessageDeflate, COMPRESSION_DEFAULTS } from '../core/ws-compres
 import {
   HUB_MESSAGE_TYPES,
   HUB_CLOSE_CODES,
+  HUB_PROTOCOL_VERSION,
   createHubMessage,
   validateHubMessage,
+  negotiateHubProtocolVersion,
 } from '../lib/hub-protocol.js'
 import { MegaShutdown } from '../lib/mega-shutdown.js'
 
@@ -45,6 +47,12 @@ export const DEFAULT_HEARTBEAT_MS = 25_000
 /** 기본 최대 프레임 크기 (bytes, L3). 1 MiB — 정상 envelope 은 수 KB 이므로 넉넉하다. */
 export const DEFAULT_MAX_PAYLOAD_BYTES = 1_048_576
 
+/**
+ * bridge 별 송신 버퍼(bufferedAmount) 기본 상한(바이트) — 16 MiB. 초과 = 느린 bridge 가 fan-out 을 못
+ * 따라오는 것 → terminate(백프레셔). 클라↔bridge 종단(`ws-upgrade.js` DEFAULT_MAX_BUFFERED_BYTES)과 대칭.
+ */
+export const DEFAULT_MAX_BUFFERED_BYTES = 16 * 1024 * 1024
+
 /**
  * 토큰 timing-safe 비교 — sha256 으로 길이 정규화 후 `timingSafeEqual`. 후보 전체를 순회하여
  * 조기 반환 timing 누출도 줄인다(early-return 안 함).
@@ -68,19 +76,23 @@ export class MegaWsHub {
    * @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 = DEFAULT_HEARTBEAT_MS, maxPayloadBytes = DEFAULT_MAX_PAYLOAD_BYTES, hubId, compression, logger } = {}) {
+  constructor({ acceptedTokens, heartbeatMs = DEFAULT_HEARTBEAT_MS, maxPayloadBytes = DEFAULT_MAX_PAYLOAD_BYTES, maxBufferedBytes = DEFAULT_MAX_BUFFERED_BYTES, hubId, compression, logger } = {}) {
     if (!Array.isArray(acceptedTokens) || acceptedTokens.length === 0) {
       throw new Error('MegaWsHub: acceptedTokens must be a non-empty array (ADR-059).')
     }
     this._acceptedTokens = [...acceptedTokens]
     this._heartbeatMs = Number.isInteger(heartbeatMs) && heartbeatMs > 0 ? heartbeatMs : DEFAULT_HEARTBEAT_MS
     this._maxPayloadBytes = Number.isInteger(maxPayloadBytes) && maxPayloadBytes > 0 ? maxPayloadBytes : DEFAULT_MAX_PAYLOAD_BYTES
+    this._maxBufferedBytes = Number.isInteger(maxBufferedBytes) && maxBufferedBytes > 0 ? maxBufferedBytes : DEFAULT_MAX_BUFFERED_BYTES
     this._hubId = typeof hubId === 'string' && hubId.length > 0 ? hubId : `hub-${generateMessageId()}`
     // Bridge↔Hub link 압축(ADR-078). enabled=false → false. 잘못된 값은 생성자에서 즉시 throw.
     /** @type {false | Object} WebSocketServer perMessageDeflate 로 전달(start). */
@@ -91,7 +103,7 @@ export class MegaWsHub {
     this._wss = null
     /** heartbeat liveness 체크 interval (M3). @type {ReturnType<typeof setInterval> | null} */
     this._livenessTimer = null
-    /** 등록된 bridge 연결. connId → { socket, lastSeen }. @type {Map<string, { socket: import('ws').WebSocket, lastSeen: number }>} */
+    /** 등록된 bridge 연결. connId → { socket, lastSeen, protocolVersion, presenceFanout }. @type {Map<string, { socket: import('ws').WebSocket, lastSeen: number, protocolVersion?: number, presenceFanout?: boolean }>} */
     this._bridges = new Map()
     /** presence. sessionId → { bridgeConnId, userId, channels:Set, metadata }. @type {Map<string, { bridgeConnId: string, userId: string, channels: Set<string>, metadata: Object }>} */
     this._sessions = new Map()
@@ -99,6 +111,13 @@ export class MegaWsHub {
     this._channelSessions = new Map()
     /** userId → sessionId 집합 (DIRECT fan-out, ADR-035). @type {Map<string, Set<string>>} */
     this._userSessions = new Map()
+    /**
+     * 역인덱스: channel → (bridgeConnId → 그 bridge 의 채널 내 세션 수). BROADCAST 의 bridge 선정을
+     * 세션 수 무관 O(bridge 수)로 만든다 — 멤버 10k 채널에서 메시지당 수백 µs 가 µs 대로 떨어진다.
+     * `_addSession`/`_removeSession` 이 증분 유지(카운트 0 → 키 제거), 메모리는 채널×bridge 수준.
+     * @type {Map<string, Map<string, number>>}
+     */
+    this._channelBridges = new Map()
   }
 
   /** hub 식별자. */
@@ -158,6 +177,20 @@ export class MegaWsHub {
     let isRegistered = false
     this._log?.debug?.({ connId }, 'ws-hub connection (awaiting register)')
 
+    // 미등록 연결 register 타임아웃 — liveness(_checkLiveness)는 등록된 bridge 만 스캔하므로,
+    // REGISTER 를 안 보내는 연결(오설정 bridge·포트 스캐너·half-open)은 이 타이머가 없으면
+    // fd/메모리로 영구 잔존한다. heartbeatMs 안에 등록 못 하면 1008 로 닫는다(fail-closed).
+    const registerTimer = setTimeout(() => {
+      if (isRegistered) return
+      this._log?.warn?.({ connId, timeoutMs: this._heartbeatMs }, 'ws-hub register timeout — closing unregistered connection (1008)')
+      try {
+        socket.close(1008, 'register timeout')
+      } catch (err) {
+        this._log?.debug?.({ err, connId }, 'ws-hub register-timeout close failed (already closing)')
+      }
+    }, this._heartbeatMs)
+    registerTimer.unref?.()
+
     socket.on('message', (raw) => {
       const frame = Array.isArray(raw) ? Buffer.concat(raw).toString('utf8') : raw.toString('utf8')
       let msg
@@ -184,12 +217,14 @@ export class MegaWsHub {
           return
         }
         isRegistered = this._handleRegister(connId, socket, msg)
+        if (isRegistered) clearTimeout(registerTimer)
         return
       }
       this._route(connId, socket, msg)
     })
 
     socket.on('close', () => {
+      clearTimeout(registerTimer) // 미등록 타임아웃 정리(등록 전 절단·정상 종료 공통).
       if (isRegistered) this._handleBridgeGone(connId)
       this._log?.debug?.({ connId }, 'ws-hub connection closed')
     })
@@ -209,16 +244,33 @@ export class MegaWsHub {
    * @private
    */
   _handleRegister(connId, socket, msg) {
-    const payload = /** @type {{ instanceId: string, token: string, capabilities: string[] }} */ (/** @type {any} */ (msg).payload)
+    const payload = /** @type {{ instanceId: string, token: string, capabilities: string[], protocolVersion?: number }} */ (/** @type {any} */ (msg).payload)
     if (!isTokenAccepted(payload.token, this._acceptedTokens)) {
       this._log?.warn?.({ connId, instanceId: payload.instanceId }, 'ws-hub register denied — bad token (ADR-059)')
       this._safeSend(socket, createHubMessage({ type: T.ERROR, error: { code: 'hub.unauthorized', message: 'invalid bridge token' }, ref: /** @type {any} */ (msg).id }))
       socket.close(1008, 'unauthorized') // RFC 6455 1008 = policy violation
       return false
     }
-    this._bridges.set(connId, { socket, lastSeen: Date.now() })
-    this._log?.info?.({ connId, instanceId: payload.instanceId, hubId: this._hubId }, 'ws-hub bridge registered')
-    this._safeSend(socket, createHubMessage({ type: T.REGISTER_OK, payload: { hubId: this._hubId, acceptedAt: Date.now(), heartbeatMs: this._heartbeatMs } }))
+    // 프로토콜 버전 협상 — bridge 가 최대 지원 버전을 실으면 상호 최고 버전(min)을 채택해 회신한다.
+    // 부재 = 레거시 bridge → v1 고정 + register_ok 에 필드 미포함(strict 스키마 bridge 가 안 깨지게).
+    const hasVersionRequest = payload.protocolVersion !== undefined
+    const protocolVersion = hasVersionRequest
+      ? negotiateHubProtocolVersion(payload.protocolVersion)
+      : HUB_PROTOCOL_VERSION
+    // presence fan-out 은 옵트인 — roster 가 redis 로 분리(ADR-177)된 뒤 bridge 는 JOIN/LEAVE/METADATA
+    // 를 no-op 으로 버리므로, `presence-fanout` capability 를 선언한 bridge 에만 보낸다(죽은 트래픽 제거).
+    const presenceFanout = Array.isArray(payload.capabilities) && payload.capabilities.includes('presence-fanout')
+    this._bridges.set(connId, { socket, lastSeen: Date.now(), protocolVersion, presenceFanout })
+    this._log?.info?.({ connId, instanceId: payload.instanceId, hubId: this._hubId, protocolVersion }, 'ws-hub bridge registered')
+    this._safeSend(socket, createHubMessage({
+      type: T.REGISTER_OK,
+      payload: {
+        hubId: this._hubId,
+        acceptedAt: Date.now(),
+        heartbeatMs: this._heartbeatMs,
+        ...(hasVersionRequest ? { protocolVersion } : {}),
+      },
+    }))
     return true
   }
 
@@ -236,12 +288,12 @@ export class MegaWsHub {
     switch (type) {
       case T.JOIN:
         this._addSession(connId, payload)
-        // 클러스터 presence 공유 — 다른 모든 bridge 에 같은 JOIN fan-out (07 §2).
-        this._fanOutToOthers(connId, msg)
+        // 클러스터 presence 공유 — `presence-fanout` 선언 bridge 에만 (07 §2 + ADR-177 후 죽은 트래픽 제거).
+        this._fanOutPresence(connId, msg)
         break
       case T.LEAVE: {
         const removed = this._removeSession(payload.sessionId)
-        if (removed) this._fanOutToOthers(connId, msg)
+        if (removed) this._fanOutPresence(connId, msg)
         break
       }
       case T.BULK_LEAVE: {
@@ -263,7 +315,7 @@ export class MegaWsHub {
         const session = this._sessions.get(payload.sessionId)
         if (session) {
           session.metadata = payload.metadata
-          this._fanOutToOthers(connId, msg) // presence 메타 동기화
+          this._fanOutPresence(connId, msg) // presence 메타 동기화 — 옵트인 bridge 만.
         }
         break
       }
@@ -334,6 +386,7 @@ export class MegaWsHub {
         this._channelSessions.set(ch, set)
       }
       set.add(entry.sessionId)
+      this._bumpChannelBridge(ch, connId, +1)
     }
     let uset = this._userSessions.get(entry.userId)
     if (!uset) {
@@ -343,6 +396,27 @@ export class MegaWsHub {
     uset.add(entry.sessionId)
   }
 
+  /**
+   * channel→bridge 역인덱스 증분 갱신. 카운트가 0 이 되면 키를 지워 인덱스가 stale 하지 않게 한다.
+   * @param {string} channel @param {string} connId @param {1|-1} delta
+   * @private
+   */
+  _bumpChannelBridge(channel, connId, delta) {
+    let counts = this._channelBridges.get(channel)
+    if (!counts) {
+      if (delta < 0) return // 제거인데 인덱스 없음 — 정합상 없을 일이지만 방어.
+      counts = new Map()
+      this._channelBridges.set(channel, counts)
+    }
+    const next = (counts.get(connId) ?? 0) + delta
+    if (next > 0) {
+      counts.set(connId, next)
+    } else {
+      counts.delete(connId)
+      if (counts.size === 0) this._channelBridges.delete(channel)
+    }
+  }
+
   /**
    * presence 에서 세션 제거. 빈 인덱스는 정리.
    * @param {string} sessionId
@@ -359,6 +433,7 @@ export class MegaWsHub {
         set.delete(sessionId)
         if (set.size === 0) this._channelSessions.delete(ch)
       }
+      this._bumpChannelBridge(ch, session.bridgeConnId, -1)
     }
     const uset = this._userSessions.get(session.userId)
     if (uset) {
@@ -389,7 +464,8 @@ export class MegaWsHub {
   }
 
   /**
-   * origin 을 제외한 모든 등록 bridge 로 송신 (presence 공유용). envelope 는 1회만 직렬화(L5).
+   * origin 을 제외한 모든 등록 bridge 로 송신. envelope 는 1회만 직렬화(L5).
+   * BULK_LEAVE(bridge-gone 정리 통지)처럼 전 bridge 가 받아야 하는 통지에 쓴다.
    * @param {string} exceptConnId
    * @param {Object} envelope
    * @private
@@ -401,6 +477,25 @@ export class MegaWsHub {
     }
   }
 
+  /**
+   * 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
+   */
+  _fanOutPresence(exceptConnId, envelope) {
+    /** @type {string | null} 첫 대상에서 1회 직렬화(L5) — 대상 0 이면 직렬화도 안 함. */
+    let data = null
+    for (const [connId, bridge] of this._bridges) {
+      if (connId === exceptConnId || !(/** @type {any} */ (bridge).presenceFanout)) continue
+      if (data === null) data = JSON.stringify(envelope)
+      this._sendSerialized(bridge.socket, data)
+    }
+  }
+
   /**
    * 한 채널의 세션을 가진 bridge 들로 fan-out (origin 제외, 중복 bridge 1회). 직렬화 1회(L5).
    *
@@ -415,12 +510,24 @@ export class MegaWsHub {
    * @private
    */
   _fanOutChannel(channel, exceptConnId, envelope, exceptSessionIds) {
+    const except = Array.isArray(exceptSessionIds) && exceptSessionIds.length > 0 ? new Set(exceptSessionIds) : null
+    if (!except) {
+      // 일반 경로(대부분의 메시지): channel→bridge 역인덱스로 선정이 O(bridge 수) — 세션 수 무관.
+      const counts = this._channelBridges.get(channel)
+      if (!counts || counts.size === 0) return
+      const data = JSON.stringify(envelope)
+      for (const connId of counts.keys()) {
+        if (connId !== exceptConnId) this._sendTo(connId, data)
+      }
+      return
+    }
+    // exceptSessionIds 경로(드묾): "제외 세션만 가진 bridge 통째 스킵" 판정에 세션 단위 정보가
+    // 필요하므로 기존 멤버 순회를 유지한다.
     const sids = this._channelSessions.get(channel)
     if (!sids) return
-    const except = Array.isArray(exceptSessionIds) && exceptSessionIds.length > 0 ? new Set(exceptSessionIds) : null
     const targets = new Set()
     for (const sid of sids) {
-      if (except && except.has(sid)) continue // 제외 세션은 bridge 선정에 기여하지 않음
+      if (except.has(sid)) continue // 제외 세션은 bridge 선정에 기여하지 않음
       const session = this._sessions.get(sid)
       if (session && session.bridgeConnId !== exceptConnId) targets.add(session.bridgeConnId)
     }
@@ -478,6 +585,22 @@ export class MegaWsHub {
    * @private
    */
   _sendSerialized(socket, serialized) {
+    // 느린 bridge 백프레셔 가드: 송신 버퍼가 상한을 넘으면 더 쌓지 않고 연결을 끊는다 — fan-out 허브는
+    // bridge 1개만 느려도 모든 채널 메시지가 그 소켓 버퍼(힙)에 적재돼 OOM 으로 가는 최악 지점이다.
+    // terminate 후 'close' 이벤트가 `_handleBridgeGone` 을 불러 presence 정리 + BULK_LEAVE fan-out 이
+    // 따라온다(재연결은 bridge 의 retry 책임, ADR-098).
+    if (socket.bufferedAmount > this._maxBufferedBytes) {
+      this._log?.warn?.(
+        { bufferedAmount: socket.bufferedAmount, max: this._maxBufferedBytes },
+        'ws-hub slow bridge — terminating (backpressure)',
+      )
+      try {
+        socket.terminate()
+      } catch (err) {
+        this._log?.debug?.({ err }, 'ws-hub backpressure terminate failed (already closing)')
+      }
+      return
+    }
     try {
       socket.send(serialized)
     } catch (err) {
@@ -575,7 +698,8 @@ export async function runWsHubCli() {
   const hub = new MegaWsHub({ acceptedTokens, heartbeatMs, maxPayloadBytes, compression, logger: console })
   const addr = await hub.start({ port, host })
   // 독립 hub 프로세스 graceful shutdown(L2 + drain) — SIGTERM/SIGINT → hub.stop({ drain: true }).
-  MegaShutdown.register('mega-ws-hub', async () => hub.stop({ drain: true }))
+  // 'server' stage — hub 도 수용 종단이라 가장 먼저 drain 종료한다.
+  MegaShutdown.register('mega-ws-hub', async () => hub.stop({ drain: true }), { stage: 'server' })
   MegaShutdown.setupSignals()
   console.log(`[mega:ws-hub] listening on ${addr.host}:${addr.port} (hubId=${hub.hubId})`)
   return hub

package/src/models/crud-sql-builder.js

@@ -0,0 +1,133 @@
+// @ts-check
+/**
+ * CRUD SQL 조각 빌더 (ADR-212) — **순수 함수**(DB·어댑터 불요, 단위 테스트 용이).
+ *
+ * 모든 식별자(컬럼·테이블)는 `static schema` 화이트리스트에서만 도출하고 `dialect.quoteIdent` 로 인용한다.
+ * 값은 100% 파라미터 바인딩(`dialect.placeholder(i)` + params). **문자열 인터폴레이션 0**(ADR-009 안전 경계).
+ *
+ * @module models/crud-sql-builder
+ */
+import { MegaInternalError } from '../errors/http-errors.js'
+
+/**
+ * @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, cols, model, where) {
+  if (!cols.has(col)) {
+    throw new MegaInternalError(
+      'model.unknown_column',
+      `${model}: '${col}' 은 static schema 컬럼이 아닙니다(${where}). 선언된 컬럼만 CRUD 에 쓸 수 있습니다 — 임의 SQL 은 this.query 사용.`,
+      { details: { model, column: col, where } },
+    )
+  }
+}
+
+/** limit/offset 정수 검증 — 음수/비정수 throw, 통과하면 그 정수 반환. @param {unknown} v @param {string} name @param {string} model @returns {number} */
+export function assertNonNegInt(v, name, model) {
+  if (!Number.isInteger(v) || /** @type {number} */ (v) < 0) {
+    throw new MegaInternalError(
+      'model.invalid_pagination',
+      `${model}: ${name} 은 0 이상의 정수여야 합니다(got ${JSON.stringify(v)}).`,
+      {
+        details: { model, [name]: v },
+      },
+    )
+  }
+  return /** @type {number} */ (v)
+}
+
+/**
+ * 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, cols, dialect, model, startIndex = 1) {
+  /** @type {string[]} */
+  const parts = []
+  /** @type {any[]} */
+  const params = []
+  let i = startIndex
+  for (const key of Object.keys(filter)) {
+    assertColumn(key, cols, model, 'filter')
+    const v = filter[key]
+    const id = dialect.quoteIdent(key)
+    if (v === undefined) {
+      throw new MegaInternalError(
+        'model.invalid_filter',
+        `${model}: filter['${key}'] 가 undefined 입니다(null 과 구분 — 의도 모호).`,
+        {
+          details: { model, column: key },
+        },
+      )
+    }
+    if (v === null) {
+      parts.push(`${id} IS NULL`)
+      continue
+    }
+    if (Array.isArray(v)) {
+      if (v.length === 0) {
+        parts.push('1=0') // 빈 IN → 매칭 0(안전).
+        continue
+      }
+      const phs = v.map(() => dialect.placeholder(i++))
+      parts.push(`${id} IN (${phs.join(', ')})`)
+      params.push(...v)
+      continue
+    }
+    parts.push(`${id} = ${dialect.placeholder(i++)}`)
+    params.push(v)
+  }
+  return { clause: parts.join(' AND '), params, nextIndex: i }
+}
+
+/**
+ * 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, cols, dialect, model) {
+  if (orderBy === undefined) return ''
+  const list = typeof orderBy === 'string' ? [{ column: orderBy }] : orderBy
+  if (!Array.isArray(list) || list.length === 0) return ''
+  const items = list.map((o) => {
+    const col = typeof o === 'string' ? o : o.column
+    assertColumn(col, cols, model, 'orderBy')
+    const dir = typeof o === 'string' ? 'asc' : (o.dir ?? 'asc')
+    if (dir !== 'asc' && dir !== 'desc') {
+      throw new MegaInternalError(
+        'model.invalid_pagination',
+        `${model}: orderBy dir 은 'asc'|'desc' 만 — got '${dir}'.`,
+        { details: { model, dir } },
+      )
+    }
+    return `${dialect.quoteIdent(col)} ${dir.toUpperCase()}`
+  })
+  return ` ORDER BY ${items.join(', ')}`
+}
+
+/**
+ * select 옵션 → 컬럼 목록 조각(`*` 또는 인용 컬럼). 화이트리스트 검증.
+ * @param {string[] | undefined} select @param {Set<string>} cols @param {CrudDialect} dialect @param {string} model
+ * @returns {string}
+ */
+export function buildSelectList(select, cols, dialect, model) {
+  if (select === undefined) return '*'
+  if (!Array.isArray(select) || select.length === 0) return '*'
+  return select
+    .map((c) => {
+      assertColumn(c, cols, model, 'select')
+      return dialect.quoteIdent(c)
+    })
+    .join(', ')
+}

package/src/models/mega-model.js

@@ -41,6 +41,7 @@
  */
 import { MegaInternalError } from '../errors/http-errors.js'
 import * as MegaAdapterManager from '../adapters/adapter-manager.js'
+import * as crud from './model-crud.js'
 
 export class MegaModel {
   /**
@@ -85,12 +86,16 @@ export class MegaModel {
    * `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 async withTransaction(fn) {
-    return this._resolveAdapter().withTransaction(fn)
+  static async withTransaction(fn, opts) {
+    return this._resolveAdapter().withTransaction(fn, opts)
   }
 
   /**
@@ -109,6 +114,81 @@ export class MegaModel {
     return this._resolveAdapter().query(sql, params)
   }
 
+  // ── 공통 CRUD (ADR-212) ────────────────────────────────────────────────
+  //
+  // `static schema`(ADR-204)를 선언한 모델에 한해, 컬럼·PK 메타에서 도출된 **bounded** CRUD 를
+  // 제공한다. 모든 식별자는 schema 화이트리스트 + `quoteIdent`, 값은 100% 파라미터 바인딩이라
+  // SQL 인젝션 표면이 없다(crud-sql-builder). raw 트랙(`this.query`/`this.db`)은 그대로 살아있다 —
+  // CRUD 는 추가 표면일 뿐 ADR-009 native 형태를 바꾸지 않는다. driver→dialect(DML facet) 디스패치는
+  // 단일 base(MegaModel)에서 런타임에 결정한다(A안). mongo 는 미지원(P3) — 호출 시 명시 throw.
+  //
+  // 본문·정규화·에러는 model-crud 에 위임하고 여기서는 `this`(Model 클래스)만 넘긴다.
+
+  /** 단건 조회(없으면 null). filter 는 등호 AND + 배열 IN + null IS NULL. @param {Record<string, any>} filter @param {{ select?: string[] }} [opts] @returns {Promise<any|null>} */
+  static async findOne(filter, opts) {
+    return crud.findOne(this, filter, opts)
+  }
+
+  /** PK 단건 조회(단일 PK 필요, 없으면 model.no_primary_key). @param {any} id @param {{ select?: string[] }} [opts] @returns {Promise<any|null>} */
+  static async findById(id, opts) {
+    return crud.findById(this, id, opts)
+  }
+
+  /** 다건 조회(기본 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 async findMany(filter, opts) {
+    return crud.findMany(this, filter ?? {}, opts)
+  }
+
+  /** 조건 매칭 행 수. @param {Record<string, any>} [filter] @returns {Promise<number>} */
+  static async count(filter) {
+    return crud.count(this, filter)
+  }
+
+  /** 조건 매칭 행 존재 여부. @param {Record<string, any>} filter @returns {Promise<boolean>} */
+  static async exists(filter) {
+    return crud.exists(this, filter)
+  }
+
+  /** 페이지 조회. 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 async paginate(filter, opts) {
+    return crud.paginate(this, filter ?? {}, opts)
+  }
+
+  /** 단건 삽입. 기본 새 id 반환, `{ returning: true }` 면 레코드(ADR-212 #1). @param {Record<string, any>} data @param {{ returning?: boolean }} [opts] @returns {Promise<any>} */
+  static async insertOne(data, opts) {
+    return crud.insertOne(this, data, opts)
+  }
+
+  /** 다건 삽입. 기본 `{ count }`, `{ returning: true }` 면 레코드 배열(maria 미지원→throw). @param {Record<string, any>[]} rows @param {{ returning?: boolean }} [opts] @returns {Promise<{ count: number } | any[]>} */
+  static async insertMany(rows, opts) {
+    return crud.insertMany(this, rows, opts)
+  }
+
+  /** 정확히 한 행 갱신(>1 매칭→롤백 후 model.multiple_matches, ADR-212 #3). 변경 행 수 반환. @param {Record<string, any>} filter @param {Record<string, any>} patch @returns {Promise<number>} */
+  static async updateOne(filter, patch) {
+    return crud.updateOne(this, filter, patch)
+  }
+
+  /** 다건 갱신. 빈 filter 는 차단 — 전체 갱신은 `{ all: true }`. @param {Record<string, any>} filter @param {Record<string, any>} patch @param {{ all?: boolean }} [opts] @returns {Promise<number>} */
+  static async updateMany(filter, patch, opts) {
+    return crud.updateMany(this, filter, patch, opts)
+  }
+
+  /** 정확히 한 행 삭제(>1 매칭→롤백 후 model.multiple_matches). 삭제 행 수 반환. @param {Record<string, any>} filter @returns {Promise<number>} */
+  static async deleteOne(filter) {
+    return crud.deleteOne(this, filter)
+  }
+
+  /** 다건 삭제. 빈 filter 는 차단 — 전체 삭제는 `{ all: true }`. @param {Record<string, any>} filter @param {{ all?: boolean }} [opts] @returns {Promise<number>} */
+  static async deleteMany(filter, opts) {
+    return crud.deleteMany(this, filter, opts)
+  }
+
+  /** 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 async upsert(data, opts) {
+    return crud.upsert(this, data, opts)
+  }
+
   /**
    * `adapter`/`table` 정합성을 검증하고 글로벌 매니저에서 어댑터(MegaDbAdapter)를 잡아 반환한다.
    *