mega-framework 0.1.6 → 0.1.7

package/src/core/migration/schema-validator.js

@@ -0,0 +1,315 @@
+// @ts-check
+/**
+ * 스키마 record 검증기 (ADR-204) — 모델 스캔·빌더 실행 결과(record 집합)를 SQL 생성 전에 일괄
+ * 검증한다. 실패는 전부 `migration.schema_invalid` 로 fail-fast(P7 — 잘못된 스키마로 SQL 을 만들어
+ * 적용 단계에서 cryptic 하게 죽는 것을 차단).
+ *
+ * 검증과 동시에 FK `references` 의 대상 모델명을 실제 테이블명으로 해석해 record 에
+ * `references.table` 을 채운다(스냅샷 자기완결 — 과거 스냅샷만으로 diff 가능).
+ *
+ * @module core/migration/schema-validator
+ */
+import { MegaConfigError } from '../../errors/config-error.js'
+import { FK_ACTIONS } from './schema-builder.js'
+
+/** SQL 식별자(컬럼·테이블 이름) 형식 — 소문자 시작 snake/camel 허용, 공백·따옴표 불가. */
+const IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/
+
+/** 빌더가 만들 수 있는 타입 집합 (postgres PoC 기준 — dialect 가 별도 매핑). */
+const KNOWN_TYPES = new Set([
+  'serial', 'bigSerial', 'integer', 'bigInteger', 'smallInteger',
+  'real', 'doublePrecision', 'decimal',
+  'varchar', 'text', 'char',
+  'boolean', 'timestamp', 'timestamptz', 'date', 'time',
+  'uuid', 'json', 'jsonb', 'enum', 'bytea',
+  // mongo 전용(ADR-209) — SQL dialect 는 렌더 시점(typeSql)에 명시 거부한다.
+  'objectId', 'object', 'array',
+])
+
+/** 중첩 def(object shape / array items)에서 허용하지 않는 최상위 전용 제약. */
+const NESTED_FORBIDDEN = ['primary', 'unique', 'references', 'check', 'default']
+
+/**
+ * 중첩 def 재귀 검증 — 타입·길이·enum 규칙은 최상위와 동일, 최상위 전용 제약은 거부.
+ * @param {string} model @param {string} path @param {Record<string, any>} def
+ */
+function validateNestedDef(model, path, def) {
+  const where = { model, column: path }
+  if (!KNOWN_TYPES.has(def.type)) {
+    throw invalid(`model '${model}.${path}': 알 수 없는 타입 '${def.type}'.`, where)
+  }
+  for (const key of NESTED_FORBIDDEN) {
+    if (def[key] !== undefined) {
+      throw invalid(
+        `model '${model}.${path}': 중첩 필드에는 .${key}() 를 쓸 수 없습니다 — 중첩 단계의 제약은 타입·길이·enum·notNull 만 지원됩니다(ADR-209).`,
+        { ...where, constraint: key },
+      )
+    }
+  }
+  if ((def.type === 'varchar' || def.type === 'char') && (!Number.isInteger(def.length) || def.length <= 0)) {
+    throw invalid(`model '${model}.${path}': ${def.type} 길이는 양의 정수여야 합니다.`, where)
+  }
+  if (def.type === 'enum' && (!Array.isArray(def.values) || def.values.length === 0)) {
+    throw invalid(`model '${model}.${path}': enum values 는 비어 있지 않은 문자열 배열이어야 합니다.`, where)
+  }
+  validateNestedStructure(model, path, def)
+}
+
+/**
+ * object shape / array items 의 재귀 진입점 (최상위·중첩 공용).
+ * @param {string} model @param {string} path @param {Record<string, any>} def
+ */
+function validateNestedStructure(model, path, def) {
+  if (def.type === 'object' && def.shape !== undefined) {
+    for (const [key, sub] of Object.entries(def.shape)) {
+      if (!IDENT_RE.test(key)) {
+        throw invalid(`model '${model}.${path}': 중첩 필드명 '${key}' 이 유효한 식별자가 아닙니다.`, { model, column: `${path}.${key}` })
+      }
+      validateNestedDef(model, `${path}.${key}`, sub)
+    }
+  }
+  if (def.type === 'array' && def.items !== undefined) {
+    validateNestedDef(model, `${path}[]`, def.items)
+  }
+}
+
+/**
+ * @param {string} message @param {Record<string, unknown>} details
+ * @returns {MegaConfigError}
+ */
+function invalid(message, details) {
+  return new MegaConfigError('migration.schema_invalid', message, { details })
+}
+
+/**
+ * record 의 t.object shape 들이 제공하는 중첩 dot-path 전부 수집(에러 안내용).
+ * @param {Record<string, any>} columns @param {string} [prefix]
+ * @returns {string[]}
+ */
+function collectNestedPaths(columns, prefix = '') {
+  /** @type {string[]} */
+  const out = []
+  for (const [colName, def] of Object.entries(columns)) {
+    if (def.type === 'object' && def.shape !== undefined) {
+      for (const [key, sub] of Object.entries(def.shape)) {
+        const path = `${prefix}${colName}.${key}`
+        out.push(path)
+        if (sub.type === 'object' && sub.shape !== undefined) {
+          out.push(...collectNestedPaths({ [key]: sub }, `${prefix}${colName}.`).map((nestedPath) => nestedPath))
+        }
+      }
+    }
+  }
+  return out
+}
+
+/**
+ * 인덱스 필드 존재 검증 — 평면 필드는 columns 직접, dot-path(중첩 필드 인덱스 — mongo 핵심 패턴,
+ * ADR-210 M-5)는 `t.object` shape 를 따라 해석한다. 실패 메시지는 사용 가능 path 를 동반한다.
+ * @param {string} model @param {Record<string, any>} record @param {string} field
+ * @param {Record<string, unknown>} where
+ */
+function assertIndexFieldExists(model, record, field, where) {
+  if (!field.includes('.')) {
+    if (record.columns[field] === undefined) {
+      throw invalid(`model '${model}': 인덱스 컬럼 '${field}' 가 schema 에 없습니다.`, { ...where, column: field })
+    }
+    return
+  }
+  const segments = field.split('.')
+  /** @type {any} */
+  let def = record.columns[segments[0]]
+  let ok = def !== undefined
+  for (let i = 1; ok && i < segments.length; i++) {
+    if (def.type !== 'object' || def.shape === undefined || def.shape[segments[i]] === undefined) {
+      ok = false
+      break
+    }
+    def = def.shape[segments[i]]
+  }
+  if (!ok) {
+    const available = collectNestedPaths(record.columns)
+    throw invalid(
+      `model '${model}': 중첩 필드 '${field}' 가 t.object shape 에 선언되어 있지 않습니다 ` +
+        `(사용 가능 path: ${available.length > 0 ? available.join(', ') : '(선언된 중첩 path 없음)'}).`,
+      { ...where, column: field, available },
+    )
+  }
+}
+
+/**
+ * 스캔된 모델 record 집합을 검증하고 FK 대상 테이블을 해석(in-place)한다.
+ *
+ * @param {Array<{ name: string, table: string, adapter: string, record: any, file?: string }>} models - 스캔 결과
+ *   (name = 모델 이름, file = 출처 파일 경로 — 충돌 메시지에 동반, record =
+ *   {@link module:core/migration/schema-builder.buildModelRecord} 산출).
+ * @param {{ identifierMaxBytesOf?: (adapter: string) => number }} [opts] - adapter 별 식별자 byte 한도
+ *   공급자(dialect.identifierMaxBytes — 합성 이름은 dialect 의 quoteIdent 깔때기가 추가 검증).
+ * @returns {void}
+ * @throws {MegaConfigError} `migration.schema_invalid` | `migration.identifier_too_long`
+ */
+export function validateModels(models, { identifierMaxBytesOf = () => Infinity } = {}) {
+  /** @type {Map<string, { table: string, record: any, file?: string }>} 모델명 → 대상 (FK 해석용). */
+  const byName = new Map()
+  for (const m of models) {
+    const dup = byName.get(m.name)
+    if (dup !== undefined) {
+      throw invalid(
+        `모델 이름 '${m.name}' 이 중복됩니다 — file-scan 범위 안에서 모델 이름은 유일해야 합니다(FK 대상 식별자). ` +
+          `파일: ${dup.file ?? '(unknown)'} ↔ ${m.file ?? '(unknown)'}`,
+        { model: m.name, files: [dup.file ?? null, m.file ?? null] },
+      )
+    }
+    byName.set(m.name, { table: m.table, record: m.record, file: m.file })
+  }
+  /** @type {Map<string, { model: string, file?: string }>} `${adapter}:${table}` → 출처 (테이블 중복 검출). */
+  const tables = new Map()
+
+  for (const m of models) {
+    const { name, record } = m
+    const where = { model: name, table: record.table }
+    const maxBytes = identifierMaxBytesOf(record.adapter)
+
+    if (!IDENT_RE.test(record.table)) {
+      throw invalid(`model '${name}': table '${record.table}' 이 유효한 식별자가 아닙니다.`, where)
+    }
+    // dialect 식별자 한도 — 절단(서버측 truncate)은 이름 충돌·표기 불일치를 만들므로 거부.
+    // 합성 이름(idx_/fk_ 등)은 dialect quoteIdent 깔때기가 렌더 시점에 추가 검증한다.
+    if (Buffer.byteLength(record.table, 'utf8') > maxBytes) {
+      throw new MegaConfigError(
+        'migration.identifier_too_long',
+        `model '${name}': table '${record.table}' 이 dialect 식별자 한도(${maxBytes}byte)를 초과합니다 — 이름을 줄이세요.`,
+        { details: { ...where, bytes: Buffer.byteLength(record.table, 'utf8'), max: maxBytes } },
+      )
+    }
+    const tableKey = `${record.adapter}:${record.table}`
+    const dupTable = tables.get(tableKey)
+    if (dupTable !== undefined) {
+      throw invalid(
+        `model '${name}': table '${record.table}' (adapter '${record.adapter}') 이 model '${dupTable.model}' 과 중복됩니다. ` +
+          `파일: ${dupTable.file ?? '(unknown)'} ↔ ${m.file ?? '(unknown)'}`,
+        { ...where, dupModel: dupTable.model, files: [dupTable.file ?? null, m.file ?? null] },
+      )
+    }
+    tables.set(tableKey, { model: name, file: m.file })
+
+    const colNames = Object.keys(record.columns)
+    if (colNames.length === 0) {
+      throw invalid(`model '${name}': 컬럼이 없습니다 — schema 는 최소 1개 컬럼을 정의해야 합니다.`, where)
+    }
+
+    // PK 규칙 — 컬럼 레벨 .primary() 는 최대 1개, 복합 PK(t.primary)와 동시 사용 불가.
+    const primaryCols = colNames.filter((c) => record.columns[c].primary === true)
+    if (primaryCols.length > 1) {
+      throw invalid(
+        `model '${name}': .primary() 컬럼이 ${primaryCols.length}개(${primaryCols.join(', ')}) — 복합 PK 는 t.primary(['a','b']) 로 선언하세요.`,
+        { ...where, columns: primaryCols },
+      )
+    }
+    if (record.primaryKey !== undefined) {
+      if (primaryCols.length > 0) {
+        throw invalid(`model '${name}': 컬럼 .primary() 와 t.primary([...]) 를 동시에 쓸 수 없습니다.`, { ...where, columns: primaryCols })
+      }
+      if (!Array.isArray(record.primaryKey) || record.primaryKey.length === 0) {
+        throw invalid(`model '${name}': t.primary([...]) 는 비어 있지 않은 컬럼 배열이어야 합니다.`, where)
+      }
+      for (const c of record.primaryKey) {
+        if (record.columns[c] === undefined) {
+          throw invalid(`model '${name}': t.primary 의 '${c}' 가 schema 컬럼에 없습니다.`, { ...where, column: c })
+        }
+      }
+    }
+
+    for (const [colName, def] of Object.entries(record.columns)) {
+      const colWhere = { ...where, column: colName }
+      if (!IDENT_RE.test(colName)) {
+        throw invalid(`model '${name}': 컬럼명 '${colName}' 이 유효한 식별자가 아닙니다.`, colWhere)
+      }
+      if (Buffer.byteLength(colName, 'utf8') > maxBytes) {
+        throw new MegaConfigError(
+          'migration.identifier_too_long',
+          `model '${name}': 컬럼명 '${colName}' 이 dialect 식별자 한도(${maxBytes}byte)를 초과합니다 — 이름을 줄이세요.`,
+          { details: { ...colWhere, bytes: Buffer.byteLength(colName, 'utf8'), max: maxBytes } },
+        )
+      }
+      if (!KNOWN_TYPES.has(def.type)) {
+        throw invalid(`model '${name}.${colName}': 알 수 없는 타입 '${def.type}'.`, colWhere)
+      }
+      if (def.notNull === true && def.nullable === true) {
+        throw invalid(`model '${name}.${colName}': .notNull() 과 .nullable() 은 동시에 쓸 수 없습니다(모순).`, colWhere)
+      }
+      if ((def.type === 'varchar' || def.type === 'char') && (!Number.isInteger(def.length) || def.length <= 0)) {
+        throw invalid(`model '${name}.${colName}': ${def.type} 길이는 양의 정수여야 합니다. Got ${JSON.stringify(def.length)}.`, colWhere)
+      }
+      if (def.type === 'decimal' && (!Number.isInteger(def.precision) || def.precision <= 0 || !Number.isInteger(def.scale) || def.scale < 0)) {
+        throw invalid(`model '${name}.${colName}': decimal(precision, scale) 은 양의 정수 precision 과 0 이상 정수 scale 이 필요합니다.`, colWhere)
+      }
+      if (def.type === 'enum') {
+        if (!Array.isArray(def.values) || def.values.length === 0 || def.values.some((/** @type {any} */ v) => typeof v !== 'string' || v.length === 0)) {
+          throw invalid(`model '${name}.${colName}': enum values 는 비어 있지 않은 문자열 배열이어야 합니다.`, colWhere)
+        }
+      }
+      // mongo 중첩 구조(object shape / array items) — 재귀 검증.
+      validateNestedStructure(name, colName, def)
+      if (def.check !== undefined && (typeof def.check.expr !== 'string' || def.check.expr.length === 0)) {
+        throw invalid(`model '${name}.${colName}': check 식이 비어 있습니다.`, colWhere)
+      }
+      if (def.default !== undefined && def.default !== null && typeof def.default === 'object') {
+        if (typeof def.default.raw !== 'string' || def.default.raw.length === 0) {
+          throw invalid(`model '${name}.${colName}': default 객체는 { raw: '<SQL 식>' } 형태여야 합니다.`, colWhere)
+        }
+      }
+
+      const ref = def.references
+      if (ref !== undefined) {
+        const target = byName.get(ref.model)
+        if (target === undefined) {
+          throw invalid(
+            `model '${name}.${colName}': references 대상 모델 '${ref.model}' 이 file-scan 결과에 없습니다 — schema 를 가진 모델만 FK 대상이 될 수 있습니다.`,
+            { ...colWhere, refModel: ref.model },
+          )
+        }
+        if (target.record.adapter !== record.adapter) {
+          throw invalid(
+            `model '${name}.${colName}': FK 대상 '${ref.model}' 의 adapter('${target.record.adapter}')가 다릅니다 — cross-adapter FK 는 불가능합니다.`,
+            { ...colWhere, refModel: ref.model },
+          )
+        }
+        if (target.record.columns[ref.column] === undefined) {
+          throw invalid(`model '${name}.${colName}': references 대상 컬럼 '${ref.model}.${ref.column}' 이 없습니다.`, {
+            ...colWhere,
+            refModel: ref.model,
+            refColumn: ref.column,
+          })
+        }
+        if (ref.onDelete !== undefined && !FK_ACTIONS.includes(ref.onDelete)) {
+          throw invalid(`model '${name}.${colName}': onDelete '${ref.onDelete}' — 허용: ${FK_ACTIONS.join(' | ')}.`, colWhere)
+        }
+        if (ref.onUpdate !== undefined && !FK_ACTIONS.includes(ref.onUpdate)) {
+          throw invalid(`model '${name}.${colName}': onUpdate '${ref.onUpdate}' — 허용: ${FK_ACTIONS.join(' | ')}.`, colWhere)
+        }
+        // FK 대상 테이블 해석 — 스냅샷 자기완결(과거 스냅샷 diff 에 모델 재스캔 불요).
+        ref.table = target.table
+      }
+    }
+
+    // 인덱스 — 컬럼 존재 + 표현식/컬럼 상호배타.
+    for (const ix of record.indexes ?? []) {
+      if (ix.expression !== undefined) {
+        if (typeof ix.expression !== 'string' || ix.expression.length === 0) {
+          throw invalid(`model '${name}': 표현식 인덱스의 expression 이 비어 있습니다.`, where)
+        }
+        continue
+      }
+      if (!Array.isArray(ix.columns) || ix.columns.length === 0) {
+        throw invalid(`model '${name}': 인덱스는 columns 또는 { expression } 이 필요합니다.`, where)
+      }
+      for (const c of ix.columns) {
+        // mongo 정렬 방향 suffix(':desc'/':asc')는 필드명이 아니다 — 제거 후 존재 검증
+        // (SQL dialect 에선 suffix 포함 이름이 quoteIdent 깔때기에서 거부된다).
+        const field = c.endsWith(':desc') ? c.slice(0, -5) : c.endsWith(':asc') ? c.slice(0, -4) : c
+        assertIndexFieldExists(name, record, field, where)
+      }
+    }
+  }
+}

package/src/core/migration-lock.js

@@ -0,0 +1,205 @@
+// @ts-check
+/**
+ * 마이그레이션 락 (ADR-190) — 동시 `mega migrate` 실행(멀티 인스턴스 배포 훅 등)의 중복 적용을 막는다.
+ *
+ * 러너({@link module:core/migration-runner})는 어댑터 비의존을 유지하고, 락은 **호스트(`runMigrateHost`)
+ * 레벨**에서 driver 별 표준 메커니즘으로 건다:
+ *   - postgres : `pg_advisory_lock(key)` — 세션 귀속 락이라 풀에서 연결 1개를 고정(pin)해 잡고,
+ *                같은 연결에서 unlock 한다(풀 경유 query 는 매번 다른 연결을 탈 수 있어 부적합).
+ *                선점돼 있으면 해제까지 대기한다(PostgreSQL 공식 문서 — advisory lock 은 세션 종료 시 자동 해제).
+ *   - mariadb  : `GET_LOCK(name, timeout)` — 동일하게 연결 고정, timeout 초과 시 fail-fast.
+ *                추가로 MariaDB 는 DDL 이 암묵 COMMIT 을 유발해(공식 문서 "Statements That Cause an
+ *                Implicit Commit") 러너의 트랜잭션 래핑이 DDL 원자성을 보장하지 못함을 경고로 명시한다.
+ *   - sqlite   : 별도 락 없음 — connection-per-Database 단일 파일 DB 는 자체 파일 락 + 트랜잭션 DDL
+ *                (busy timeout 직렬화)로 충분하다(ADR-105). 잔존 경합은 러너의 2중 이력 재확인이
+ *                흡수한다(ADR-208 M-2).
+ *   - mongodb  : `mega_migrations_lock` 컬렉션의 `_id:'lock'` 도큐먼트 선점(insertOne — _id 유일성이
+ *                원자적 선점). 선점돼 있으면 폴링 대기, 한도 초과 시 fail-fast(보유자 정보 동반).
+ *                해제는 deleteOne — crash 로 남은 stale lock 은 에러 안내의 수동 정리 절차를 따른다(ADR-209).
+ *   - 그 외    : 락 미지원 driver 는 **명시 경고 후** 락 없이 진행한다(silent skip 금지, P4).
+ *
+ * @module core/migration-lock
+ */
+import { MegaConfigError } from '../errors/config-error.js'
+
+/** postgres advisory lock 키 — 'mega' ASCII(0x6d656761). 프레임워크 고정값(임의 64-bit 앱 키). */
+export const PG_ADVISORY_LOCK_KEY = 0x6d656761
+
+/** mariadb GET_LOCK 이름. */
+export const MARIA_LOCK_NAME = 'mega_migrations'
+
+/** mariadb GET_LOCK 대기 한도(초) — 초과 시 `migrate.lock_timeout` fail-fast. */
+export const MARIA_LOCK_TIMEOUT_SEC = 60
+
+/** mongodb 락 컬렉션 이름. */
+export const MONGO_LOCK_COLLECTION = 'mega_migrations_lock'
+
+/** mongodb 락 대기 한도(ms)·폴링 간격(ms) — 한도 초과 시 `migrate.lock_timeout` fail-fast. */
+export const MONGO_LOCK_TIMEOUT_MS = 60_000
+export const MONGO_LOCK_POLL_MS = 500
+
+/**
+ * @typedef {{ debug?: Function, info?: Function, warn?: Function }} LockLogger
+ */
+
+/**
+ * driver 별 마이그레이션 락 안에서 `fn` 을 실행한다. 락 획득/해제는 같은 고정 연결에서 수행하고,
+ * 해제 실패는 원본 결과/에러를 가리지 않는다(세션 락은 연결 반납·종료 시 서버가 자동 해제).
+ *
+ * @template T
+ * @param {import('../adapters/mega-adapter.js').MegaAdapter} adapter - 연결된 대상 DB 어댑터.
+ * @param {() => Promise<T>} fn - 락 보유 중 실행할 작업(마이그레이션 up/down).
+ * @param {{ logger?: LockLogger }} [opts]
+ * @returns {Promise<T>}
+ * @throws {MegaConfigError} `migrate.lock_timeout` - mariadb GET_LOCK 대기 한도 초과.
+ */
+export async function withMigrationLock(adapter, fn, { logger } = {}) {
+  const driver = /** @type {any} */ (adapter)?.getStats?.().driver
+  if (driver === 'postgres') return withPgAdvisoryLock(adapter, fn, logger)
+  if (driver === 'mariadb') return withMariaLock(adapter, fn, logger)
+  if (driver === 'mongodb') return withMongoLock(adapter, fn, logger)
+  if (driver === 'sqlite') {
+    // 단일 파일 DB — 파일 락 + 트랜잭션 DDL 이 곧 직렬화 장치라 별도 락이 불필요(ADR-105/184).
+    logger?.debug?.({ driver }, 'migrate.lock skipped (sqlite file lock + transactional DDL)')
+    return fn()
+  }
+  // 3rd-party driver 등 락 전략 미정의 — 락 없이 진행하되 반드시 명시 경고(P4: silent skip 금지).
+  logger?.warn?.({ driver: driver ?? null }, 'migrate.lock unsupported for this driver — proceeding without a migration lock')
+  return fn()
+}
+
+/**
+ * postgres — 풀에서 연결 1개를 고정해 `pg_advisory_lock` 으로 직렬화한다. 락은 세션(연결) 귀속이라
+ * 같은 클라이언트에서 잡고 풀어야 하며, 마이그레이션 본문은 평소처럼 어댑터(풀)로 실행돼도 무방하다.
+ *
+ * @template T
+ * @param {any} adapter @param {() => Promise<T>} fn @param {LockLogger} [logger]
+ * @returns {Promise<T>}
+ */
+async function withPgAdvisoryLock(adapter, fn, logger) {
+  const pool = adapter.native
+  const client = await pool.connect()
+  try {
+    logger?.debug?.({ key: PG_ADVISORY_LOCK_KEY }, 'migrate.lock acquiring (pg_advisory_lock)')
+    // 선점 시 해제까지 대기 — 동시 배포의 늦은 쪽은 앞선 쪽이 끝난 뒤 pending 0 으로 무해 통과한다.
+    await client.query('SELECT pg_advisory_lock($1)', [PG_ADVISORY_LOCK_KEY])
+    logger?.debug?.({ key: PG_ADVISORY_LOCK_KEY }, 'migrate.lock acquired')
+    try {
+      return await fn()
+    } finally {
+      try {
+        await client.query('SELECT pg_advisory_unlock($1)', [PG_ADVISORY_LOCK_KEY])
+      } catch (err) {
+        // unlock 실패는 비치명적 — 아래 release/세션 종료 시 서버가 자동 해제한다. 원본 결과 우선.
+        logger?.warn?.({ err }, 'migrate.lock pg_advisory_unlock failed (lock auto-releases with the session)')
+      }
+    }
+  } finally {
+    client.release()
+  }
+}
+
+/**
+ * mariadb — 연결 1개를 고정해 `GET_LOCK` 으로 직렬화한다. DDL 암묵 COMMIT 경고를 함께 남긴다.
+ *
+ * @template T
+ * @param {any} adapter @param {() => Promise<T>} fn @param {LockLogger} [logger]
+ * @returns {Promise<T>}
+ */
+async function withMariaLock(adapter, fn, logger) {
+  // MariaDB 는 CREATE/ALTER/DROP 등 DDL 이 암묵 COMMIT 을 유발 — 러너의 트랜잭션 래핑이 DDL 을
+  // 롤백하지 못한다. 락으로 동시 실행은 막지만, 중간 실패 시 부분 적용이 남을 수 있음을 명시(ADR-190).
+  logger?.warn?.('migrate: MariaDB DDL causes an implicit COMMIT — a failed migration may leave partially applied DDL (no rollback).')
+  const pool = adapter.native
+  const conn = await pool.getConnection()
+  try {
+    logger?.debug?.({ name: MARIA_LOCK_NAME }, 'migrate.lock acquiring (GET_LOCK)')
+    const rows = await conn.query(`SELECT GET_LOCK('${MARIA_LOCK_NAME}', ${MARIA_LOCK_TIMEOUT_SEC}) AS l`)
+    // GET_LOCK: 1=획득, 0=timeout, NULL=에러. bigIntStrategy 에 따라 BigInt 일 수 있어 Number 정규화.
+    const raw = rows?.[0]?.l
+    const got = raw == null ? null : Number(raw)
+    if (got !== 1) {
+      throw new MegaConfigError(
+        'migrate.lock_timeout',
+        `another migration appears to be running — GET_LOCK('${MARIA_LOCK_NAME}') not acquired within ${MARIA_LOCK_TIMEOUT_SEC}s.`,
+        { details: { result: got } },
+      )
+    }
+    logger?.debug?.({ name: MARIA_LOCK_NAME }, 'migrate.lock acquired')
+    try {
+      return await fn()
+    } finally {
+      try {
+        await conn.query(`SELECT RELEASE_LOCK('${MARIA_LOCK_NAME}')`)
+      } catch (err) {
+        // 해제 실패는 비치명적 — 연결 반납·세션 종료 시 서버가 자동 해제한다. 원본 결과 우선.
+        logger?.warn?.({ err }, 'migrate.lock RELEASE_LOCK failed (lock auto-releases with the session)')
+      }
+    }
+  } finally {
+    await conn.release()
+  }
+}
+
+/**
+ * mongodb — `mega_migrations_lock` 의 `_id:'lock'` 도큐먼트를 insertOne 으로 선점한다(_id 유일성이
+ * 원자적 선점 장치 — 트랜잭션/replica-set 불요라 standalone 에서도 동작). 선점돼 있으면 폴링으로
+ * 대기하고, 한도 초과 시 보유자 정보(pid/host/at)와 수동 정리 절차를 담아 fail-fast 한다.
+ * mongo DDL 은 트랜잭션 밖이라(공식 문서 — collMod 등은 multi-document 트랜잭션 불가) 중간 실패는
+ * 부분 적용으로 남을 수 있음을 경고로 명시한다(maria 패턴 정합, ADR-190/209).
+ *
+ * @template T
+ * @param {any} adapter @param {() => Promise<T>} fn @param {LockLogger} [logger]
+ * @returns {Promise<T>}
+ */
+async function withMongoLock(adapter, fn, logger) {
+  logger?.warn?.('migrate: MongoDB DDL runs outside transactions — a failed migration may leave partially applied changes (no rollback).')
+  /** @type {import('mongodb').Db} */
+  const db = adapter.native
+  const coll = db.collection(MONGO_LOCK_COLLECTION)
+  const me = { _id: /** @type {any} */ ('lock'), pid: process.pid, host: process.env.HOSTNAME ?? 'unknown', at: new Date().toISOString() }
+  logger?.debug?.({ collection: MONGO_LOCK_COLLECTION }, 'migrate.lock acquiring (mongo lock document)')
+  const deadline = Date.now() + MONGO_LOCK_TIMEOUT_MS
+  for (;;) {
+    try {
+      await coll.insertOne(me)
+      break
+    } catch (err) {
+      // E11000(중복 키) = 다른 러너 보유 — 폴링 대기. 그 외 에러는 즉시 전파(연결 단절 등).
+      if (/** @type {any} */ (err).code !== 11000) throw err
+      if (Date.now() >= deadline) {
+        /** @type {any} */
+        let holder = null
+        try {
+          holder = await coll.findOne({ _id: /** @type {any} */ ('lock') })
+        } catch (readErr) {
+          // 보유자 조회 실패는 안내 품질 문제일 뿐 — timeout 이 정본 에러다.
+          logger?.debug?.({ err: readErr }, 'migrate.lock holder lookup failed')
+        }
+        throw new MegaConfigError(
+          'migrate.lock_timeout',
+          `another migration appears to be running — mongo lock not acquired within ${MONGO_LOCK_TIMEOUT_MS / 1000}s ` +
+            `(holder: ${holder ? `pid ${holder.pid}@${holder.host} since ${holder.at}` : '(unknown)'}). ` +
+            `진행 중인 프로세스가 없는데도 반복되면 crash 로 남은 stale lock 입니다 — ` +
+            `db.${MONGO_LOCK_COLLECTION}.deleteOne({ _id: 'lock' }) 로 정리 후 재시도하세요.`,
+          { details: { collection: MONGO_LOCK_COLLECTION, holder } },
+        )
+      }
+      await new Promise((resolve) => setTimeout(resolve, MONGO_LOCK_POLL_MS))
+    }
+  }
+  logger?.debug?.({ collection: MONGO_LOCK_COLLECTION }, 'migrate.lock acquired')
+  try {
+    return await fn()
+  } finally {
+    try {
+      await coll.deleteOne({ _id: /** @type {any} */ ('lock'), pid: process.pid })
+    } catch (err) {
+      // 해제 실패는 비치명적이지 않다(mongo 락은 세션 자동 해제가 없다) — stale lock 안내를 경고로 남긴다.
+      logger?.warn?.(
+        { err },
+        `migrate.lock release failed — stale lock 이 남으면 db.${MONGO_LOCK_COLLECTION}.deleteOne({ _id: 'lock' }) 로 정리하세요`,
+      )
+    }
+  }
+}