mega-framework 0.1.6 → 0.1.7

package/src/core/migration/dialects/mongo.js

@@ -0,0 +1,824 @@
+// @ts-check
+/**
+ * mongodb dialect (ADR-209) — 빌더 record 를 SQL 이 아니라 **mongo command JS 문**으로 렌더한다
+ * (`usesSqlDdl: false` — 생성 파일의 `db` 는 mongodb `Db` 인스턴스).
+ *
+ * SQL dialect 와의 핵심 차이:
+ *   - **스키마 = collection validator(`$jsonSchema`)** — 컬럼 단위 ALTER 가 없고 validator 를
+ *     통째로 교체한다(`collMod`). 그래서 컬럼 수준 변경은 differ 가 `rebuildTable` op 1개로
+ *     수렴하고(`dependsOnRebuild` + `rebuildTriggerKinds` 확장 — 테이블 재생성이 아니라 validator
+ *     교체로 렌더), 인덱스/UNIQUE 변경만 개별 op 로 남는다.
+ *   - **validator 는 기존 도큐먼트를 변환하지 않는다** — 엄격해진 스키마는 이후 insert/update
+ *     시점에 거부될 뿐이다. backfill(`updateMany`)은 자동 생성 범위 밖(사용자 raw 편집 — 생성
+ *     파일에 경고 주석 동반).
+ *   - **rename 은 `$rename` updateMany 동반** — validator 의 속성명만 바꾸면 기존 도큐먼트는 옛
+ *     필드명으로 남아 strict 검증과 어긋난다. rename 은 사용자가 명시 확정한 의도이므로 데이터
+ *     이동까지 생성한다(SQL dialect 의 RENAME COLUMN 데이터 보존 의미 정합). 순서는 **collMod
+ *     먼저, $rename 다음** — strict 검증은 update 결과를 "현재" validator 로 평가하므로 교체 전
+ *     $rename 은 옛 스키마의 additionalProperties: false 에 걸린다(실측).
+ *   - **idempotent 렌더(ADR-210)** — no-tx 다단의 부분 실패 후 **같은 파일 재실행이 1차 복구
+ *     수단**(ADR-208 M-1 원칙)이다: dropIndex/dropCollection 은 not-found(27/26) 무해 통과,
+ *     createCollection 은 exists(48) 시 validator collMod 수렴, createIndex 는 동일 스펙 재실행이
+ *     서버 자연 멱등(스펙 충돌 85/86 은 진짜 결함이라 그대로 실패), collMod/$rename 은 자연 멱등.
+ *   - **트랜잭션 없음** — `collMod`/`create`/`drop`/인덱스 DDL 은 multi-document 트랜잭션 안에서
+ *     실행할 수 없고(공식 문서 — 트랜잭션은 CRUD 중심, 4.4+ 의 create 예외도 제한적), standalone
+ *     은 트랜잭션 자체가 없다. 생성 파일은 항상 `export const transaction = false`.
+ *   - **명시 거부(escape hatch 안내)**: `.references()`(FK 개념 없음), `.check()`(cross-field 는
+ *     `$jsonSchema` 범위 밖 — raw 에서 `$expr` validator), `.default()`(`$jsonSchema` 는 default
+ *     미지원 — 앱 레벨), serial/bigSerial(`_id: ObjectId` 사용), `_id` 외 `.primary()`/복합 PK,
+ *     SQL `where` 인덱스(JSON partialFilterExpression 문자열만 허용), 표현식 인덱스.
+ *
+ * bsonType 매핑 한계(정직 명시): smallInteger→int(구분 없음), time→string(native 없음),
+ * uuid→string(`crypto.randomUUID()` 정합 — binData(subtype 4) UUID 는 raw 마이그레이션),
+ * timestamp/timestamptz/date→date(시간대 개념 없음 — UTC Date 단일), json/jsonb→object.
+ *
+ * @module core/migration/dialects/mongo
+ */
+import { MegaConfigError } from '../../../errors/config-error.js'
+
+// ── 능력/한계 속성 (dialects/README.md contract) ────────────────────────────
+/** mongo namespace 한도(db 포함 120byte)에서 db 명을 제외한 보수적 collection/필드 한도. */
+export const identifierMaxBytes = 64
+/** mongo 4.2+ 인덱스 빌드는 항상 online(hybrid build) — --concurrent 는 의미 변화 없이 허용. */
+export const supportsConcurrentIndex = true
+/** enum 은 `$jsonSchema` 의 enum 키워드 — CHECK 도 native enum 타입도 아니다. */
+export const enumStrategy = 'jsonschema-enum'
+/** renameCollection 은 트랜잭션 안에서 불가(공식 문서). */
+export const supportsRenameInTx = false
+/** validator 교체(collMod)는 즉시 적용 — 단 본 dialect 는 트랜잭션 자체를 쓰지 않는다. */
+export const canDropColumnInTx = false
+/** 컬럼 수준 변경을 rebuildTable(=validator 교체) 1 op 로 수렴한다. */
+export const dependsOnRebuild = true
+/** constraint 개념이 없다. */
+export const supportsRenameConstraint = false
+/** FK 자체가 없다 — differ 의 FK 분리/동기화 경로 전부 비활성. */
+export const supportsAlterAddFk = false
+/** FK 가 없으니 해당 없음. */
+export const requiresDropFkBeforeDropColumn = false
+/** SQL 이 아니라 mongo command JS 문을 렌더한다 — generate 가 파일 템플릿을 분기한다. */
+export const usesSqlDdl = false
+
+/**
+ * differ 의 수렴 트리거 확장 — mongo 는 validator 가 통짜라 **모든 컬럼 수준 변경**이 수렴 대상이다
+ * (sqlite 기본 집합 + addColumn/renameColumn/setComment). 인덱스/UNIQUE 변경은 collMod 와 무관한
+ * 개별 op 로 남는다.
+ */
+export const rebuildTriggerKinds = new Set([
+  'alterType', 'setNotNull', 'dropNotNull', 'setDefault', 'dropDefault',
+  'addCheck', 'dropCheck', 'addFk', 'dropFk', 'renameFk', 'addPk', 'dropPk', 'changePk',
+  'dropColumn', 'addColumn', 'renameColumn', 'setComment',
+])
+
+/**
+ * collection/필드 이름 검증 — mongo 는 SQL 인용이 없어서 quoteIdent 는 검증 깔때기 + 원형 반환.
+ * `$` 시작(연산자 충돌), `.`(경로 구분자), `system.` prefix(예약), 빈 문자열, NUL 을 거부한다.
+ * @param {string} name @returns {string}
+ */
+export function quoteIdent(name) {
+  if (typeof name !== 'string' || name.length === 0) {
+    throw new MegaConfigError('migration.schema_invalid', `mongo dialect: 빈 식별자는 사용할 수 없습니다.`, { details: { identifier: name } })
+  }
+  if (Buffer.byteLength(name, 'utf8') > identifierMaxBytes) {
+    throw new MegaConfigError(
+      'migration.identifier_too_long',
+      `식별자 '${name}' 가 mongo 권장 한도(${identifierMaxBytes}byte)를 초과합니다 — 이름을 줄이세요.`,
+      { details: { identifier: name, bytes: Buffer.byteLength(name, 'utf8'), max: identifierMaxBytes } },
+    )
+  }
+  if (name.startsWith('$') || name.includes('.') || name.includes('\0') || name.startsWith('system.')) {
+    throw new MegaConfigError(
+      'migration.schema_invalid',
+      `mongo dialect: 식별자 '${name}' 는 사용할 수 없습니다 — '$' 시작·'.' 포함·NUL·'system.' prefix 는 mongo 네임스페이스 규칙 위반입니다.`,
+      { details: { identifier: name } },
+    )
+  }
+  return name
+}
+
+/** JS 코드에 박는 값 literal — JSON 직렬화(따옴표·escape 안전). @param {unknown} value @returns {string} */
+export function quoteLiteral(value) {
+  return JSON.stringify(value)
+}
+
+/**
+ * contract 형식 충족용 — mongo 에는 CHECK 가 없다. enum 은 `$jsonSchema` 의 enum 키워드로
+ * 렌더되므로 이 함수가 정상 흐름에서 호출되면 통합 결함이다(silent 우회 금지).
+ * @param {string} col @param {string[]} values @returns {string}
+ */
+export function enumCheckExpr(col, values) {
+  throw new MegaConfigError(
+    'migration.dialect_feature_unsupported',
+    `mongo dialect: CHECK 식이 없습니다 — enum 은 $jsonSchema 의 enum 으로 렌더됩니다 (col '${col}').`,
+    { details: { col, values } },
+  )
+}
+
+// ── 명명 표준 (SQL dialect 와 동일 규칙 — diff 식별자 안정성) ────────────────
+/** @param {string} table @param {string[]} cols @param {boolean} [unique] @returns {string} */
+export function indexName(table, cols, unique = false) {
+  // dot-path(중첩 필드) 인덱스는 이름 합성 시 '.' 를 '_' 로 — 인덱스 이름의 네임스페이스 혼동 방지.
+  return `${unique ? 'uniq' : 'idx'}_${table}_${cols.map((c) => parseIndexColumn(c).field.replaceAll('.', '_')).join('_')}`
+}
+/** @param {string} table @param {Record<string, any>} ix @returns {string} */
+export function resolveIndexName(table, ix) {
+  if (ix.name !== undefined) return ix.name
+  if (ix.expression !== undefined) {
+    throw new MegaConfigError(
+      'migration.dialect_feature_unsupported',
+      `mongo dialect: 표현식 인덱스를 지원하지 않습니다 (table '${table}') — wildcard/계산 필드 인덱스는 raw 마이그레이션(createIndex)으로 작성하세요.`,
+      { details: { table, expression: ix.expression } },
+    )
+  }
+  return indexName(table, ix.columns, ix.unique === true)
+}
+/** @param {string} table @param {string} col @returns {string} */
+export function uniqueName(table, col) {
+  return `uniq_${table}_${col}`
+}
+/** @param {string} table @param {string} col @param {string} refTable @returns {string} */
+export function fkName(table, col, refTable) {
+  return `fk_${table}_${col}_${refTable}`
+}
+/** @param {string} table @param {string} col @returns {string} */
+export function checkName(table, col) {
+  return `chk_${table}_${col}`
+}
+/** mongo PK 는 _id 단일 — diff 정규화용 합성 명칭. @param {string} table @returns {string} */
+export function pkName(table) {
+  return `pk_${table}`
+}
+/** @param {string} table @returns {string} */
+export function inlinePkName(table) {
+  return `pk_${table}`
+}
+
+// ── $jsonSchema 합성 ─────────────────────────────────────────────────────────
+
+/**
+ * mongo 에서 표현 불가한 def 속성의 명시 거부 — silent 누락으로 "선언했는데 반영 안 됨" 을 막는다.
+ * @param {string} table @param {string} col @param {Record<string, any>} def
+ */
+function assertSupportedDef(table, col, def) {
+  const where = { table, column: col }
+  if (def.type === 'serial' || def.type === 'bigSerial') {
+    throw new MegaConfigError(
+      'migration.dialect_feature_unsupported',
+      `mongo dialect: table '${table}' 컬럼 '${col}' — mongo 는 SERIAL(자동증가) 대신 ObjectId 를 사용합니다. ` +
+        `'_id: t.objectId().primary()'(생략 가능 — _id 는 자동) 로 선언하거나 필드를 제거하세요.`,
+      { details: { ...where, type: def.type } },
+    )
+  }
+  if (def.references !== undefined) {
+    throw new MegaConfigError(
+      'migration.fk_not_supported',
+      `mongo dialect: table '${table}' 컬럼 '${col}' 의 .references() — mongo 에는 FK/참조 무결성이 없습니다. ` +
+        '참조 검증이 필요하면 앱 레벨(서비스 코드)에서 처리하고 schema 에서는 제거하세요.',
+      { details: where },
+    )
+  }
+  if (def.check !== undefined) {
+    throw new MegaConfigError(
+      'migration.dialect_feature_unsupported',
+      `mongo dialect: table '${table}' 컬럼 '${col}' 의 .check() — cross-field/임의 식 검증은 $jsonSchema 범위 밖입니다. ` +
+        `생성 파일을 raw 편집해 collMod validator 에 $expr 를 추가하세요(예: { $and: [{ $jsonSchema: {…} }, { $expr: {…} }] }).`,
+      { details: { ...where, expr: def.check.expr } },
+    )
+  }
+  if (def.default !== undefined) {
+    throw new MegaConfigError(
+      'migration.dialect_feature_unsupported',
+      `mongo dialect: table '${table}' 컬럼 '${col}' 의 .default() — $jsonSchema 는 default 를 지원하지 않습니다(검증 전용). ` +
+        '기본값은 도큐먼트 생성 시 앱 레벨에서 채우세요.',
+      { details: { ...where, default: def.default } },
+    )
+  }
+  if (def.notNull === true && def.nullable === true) {
+    throw new MegaConfigError(
+      'migration.schema_invalid',
+      `mongo dialect: table '${table}' 컬럼 '${col}' — .notNull() 과 .nullable() 은 동시에 쓸 수 없습니다(모순).`,
+      { details: where },
+    )
+  }
+  if (def.primary === true && col !== '_id') {
+    throw new MegaConfigError(
+      'migration.dialect_feature_unsupported',
+      `mongo dialect: table '${table}' 컬럼 '${col}' 의 .primary() — mongo PK 는 '_id' 뿐입니다. ` +
+        `'_id: t.objectId().primary()' 로 선언하거나(생략 시 자동 ObjectId), 고유성이 목적이면 .unique() 를 사용하세요.`,
+      { details: where },
+    )
+  }
+}
+
+/**
+ * 컬럼 def → `$jsonSchema` 속성 스키마. 중첩(object shape / array items)은 재귀.
+ * @param {string} table @param {string} col @param {Record<string, any>} def
+ * @returns {Record<string, any>}
+ */
+function propertySchema(table, col, def) {
+  assertSupportedDef(table, col, def)
+  /** @type {Record<string, any>} */
+  const s = {}
+  switch (def.type) {
+    case 'objectId':
+      s.bsonType = 'objectId'
+      break
+    case 'integer':
+    case 'smallInteger': // mongo 는 int32 단일 — small 구분 없음(모듈 docstring 한계 명시)
+      s.bsonType = 'int'
+      break
+    case 'bigInteger':
+      s.bsonType = 'long'
+      break
+    case 'real':
+    case 'doublePrecision':
+      s.bsonType = 'double'
+      break
+    case 'decimal':
+      s.bsonType = 'decimal' // Decimal128 — precision/scale 은 $jsonSchema 로 표현 불가(검증 밖)
+      break
+    case 'varchar':
+      s.bsonType = 'string'
+      s.maxLength = def.length
+      break
+    case 'char':
+      s.bsonType = 'string'
+      s.minLength = def.length
+      s.maxLength = def.length
+      break
+    case 'text':
+      s.bsonType = 'string'
+      break
+    case 'boolean':
+      s.bsonType = 'bool'
+      break
+    case 'timestamp':
+    case 'timestamptz':
+    case 'date':
+      s.bsonType = 'date'
+      break
+    case 'time':
+      s.bsonType = 'string' // mongo 에 time-of-day native 없음 — ISO 'HH:mm:ss' 문자열 규약
+      break
+    case 'uuid':
+      s.bsonType = 'string' // crypto.randomUUID() 문자열 정합 — binData(subtype 4)는 raw 마이그레이션
+      break
+    case 'json':
+    case 'jsonb':
+      s.bsonType = 'object'
+      break
+    case 'bytea':
+      s.bsonType = 'binData'
+      break
+    case 'enum':
+      s.enum = [...def.values]
+      break
+    case 'object': {
+      s.bsonType = 'object'
+      if (def.shape !== undefined) {
+        const nested = nestedObjectSchema(table, col, def.shape)
+        if (Object.keys(nested.properties).length > 0) s.properties = nested.properties
+        if (nested.required.length > 0) s.required = nested.required
+        s.additionalProperties = false
+      }
+      break
+    }
+    case 'array': {
+      s.bsonType = 'array'
+      if (def.items !== undefined) s.items = propertySchema(table, `${col}[]`, def.items)
+      if (def.uniqueItems === true) s.uniqueItems = true
+      break
+    }
+    default:
+      throw new MegaConfigError('migration.schema_invalid', `mongo dialect: 알 수 없는 타입 '${def.type}'.`, { details: { table, column: col, type: def.type } })
+  }
+  if (typeof def.comment === 'string') s.description = def.comment
+  // .nullable() — SQL 의 "NULL 저장 가능" 의미를 mongo 로 번역: 필드 생략뿐 아니라 **명시 null** 도
+  // 허용한다(bsonType 유니온 / enum 에 null 추가). 미선언 시 mongo 는 필드 생략만 허용(실측 121).
+  if (def.nullable === true) {
+    if (s.bsonType !== undefined) s.bsonType = [s.bsonType, 'null']
+    if (s.enum !== undefined) s.enum = [...s.enum, null]
+  }
+  return s
+}
+
+/**
+ * 중첩 object shape → { properties, required }. 중첩 단계에서는 notNull → required 만 제약으로
+ * 인정한다(unique/primary/references/check 는 최상위 전용 — assertSupportedDef 가 거부).
+ * @param {string} table @param {string} parentCol @param {Record<string, any>} shape
+ * @returns {{ properties: Record<string, any>, required: string[] }}
+ */
+function nestedObjectSchema(table, parentCol, shape) {
+  /** @type {Record<string, any>} */
+  const properties = {}
+  /** @type {string[]} */
+  const required = []
+  for (const [key, def] of Object.entries(shape)) {
+    quoteIdent(key)
+    properties[key] = propertySchema(table, `${parentCol}.${key}`, def)
+    if (def.notNull === true) required.push(key)
+  }
+  return { properties, required }
+}
+
+/**
+ * record → collection `$jsonSchema`. `additionalProperties: false`(strict) 라 `_id` 를 항상
+ * properties 에 포함한다(_id 는 모든 도큐먼트에 존재 — 누락 시 insert 전부 거부되는 함정).
+ * @param {Record<string, any>} record
+ * @returns {Record<string, any>}
+ */
+export function jsonSchemaOf(record) {
+  const table = record.table
+  if (record.primaryKey !== undefined) {
+    throw new MegaConfigError(
+      'migration.dialect_feature_unsupported',
+      `mongo dialect: table '${table}' 의 t.primary([...]) — mongo 는 복합 PK 를 지원하지 않습니다(_id 단일). ` +
+        '복합 고유성이 목적이면 t.index([...], { unique: true }) 를 사용하세요.',
+      { details: { table, primaryKey: record.primaryKey } },
+    )
+  }
+  /** @type {Record<string, any>} */
+  const properties = {}
+  /** @type {string[]} */
+  const required = []
+  if (record.columns._id === undefined) properties._id = { bsonType: 'objectId' }
+  for (const [col, def] of Object.entries(record.columns)) {
+    quoteIdent(col)
+    properties[col] = propertySchema(table, col, /** @type {any} */ (def))
+    if (/** @type {any} */ (def).notNull === true) required.push(col)
+  }
+  /** @type {Record<string, any>} */
+  const schema = { bsonType: 'object' }
+  if (required.length > 0) schema.required = required
+  schema.properties = properties
+  schema.additionalProperties = false
+  return schema
+}
+
+/** record 의 validation 옵션(모델 static validation) 정규화 — 미지정 시 strict/error. */
+const VALIDATION_LEVELS = ['strict', 'moderate']
+const VALIDATION_ACTIONS = ['error', 'warn']
+
+/**
+ * @param {Record<string, any>} record
+ * @returns {{ validationLevel: string, validationAction: string }}
+ */
+function validationOptionsOf(record) {
+  const v = record.validation ?? {}
+  const level = v.level ?? 'strict'
+  const action = v.action ?? 'error'
+  if (!VALIDATION_LEVELS.includes(level) || !VALIDATION_ACTIONS.includes(action)) {
+    throw new MegaConfigError(
+      'migration.schema_invalid',
+      `mongo dialect: table '${record.table}' 의 static validation — level 은 [${VALIDATION_LEVELS.join('|')}], action 은 [${VALIDATION_ACTIONS.join('|')}] 만 허용됩니다.`,
+      { details: { table: record.table, validation: v } },
+    )
+  }
+  return { validationLevel: level, validationAction: action }
+}
+
+// ── JS 문 렌더 ───────────────────────────────────────────────────────────────
+
+/**
+ * 값 → JS 코드 객체 literal (2-space, 키 순서 = 삽입 순서 보존). JSON.stringify 기반이라
+ * 결정적 출력 — 생성 파일 diff 노이즈 없음.
+ * @param {unknown} obj @param {string} indent - 후속 행 들여쓰기.
+ * @returns {string}
+ */
+function js(obj, indent) {
+  return JSON.stringify(obj, null, 2).split('\n').join(`\n${indent}`)
+}
+
+/** @param {string} table @returns {string} `db.collection('t')` 접근 코드. */
+function coll(table) {
+  return `db.collection(${quoteLiteral(quoteIdent(table))})`
+}
+
+/**
+ * 인덱스 컬럼 항목 파싱 — `'field'`(asc) | `'field:desc'`. 필드 존재 검증은 schema-validator 가
+ * suffix 제거 후 수행한다.
+ * @param {string} entry @returns {{ field: string, dir: 1 | -1 }}
+ */
+export function parseIndexColumn(entry) {
+  if (entry.endsWith(':desc')) return { field: entry.slice(0, -5), dir: -1 }
+  if (entry.endsWith(':asc')) return { field: entry.slice(0, -4), dir: 1 }
+  return { field: entry, dir: 1 }
+}
+
+/** mongo 인덱스 타입으로 허용하는 using 값 (그 외 SQL 의 USING 은 미지원 거부). */
+const INDEX_USING = ['text', '2dsphere', 'hashed']
+
+/**
+ * partialFilterExpression 이 허용하는 연산자(공식 문서의 닫힌 목록 — MongoDB 6.0+ 에서 $in/$or 포함).
+ * 그 외($ne/$nin/$not/$regex/$expr …)는 서버가 createIndex 시점에 거부한다 — generate 가 미리 막지
+ * 않으면 직전 dropIndex 가 이미 실행돼 기존 인덱스 유실 + 부분 적용으로 증폭된다(audit M-3 실측).
+ */
+const PARTIAL_FILTER_OPS = new Set(['$eq', '$gt', '$gte', '$lt', '$lte', '$in', '$exists', '$type', '$and', '$or'])
+
+/**
+ * partialFilterExpression 재귀 검증 — 화이트리스트 밖 연산자·$exists:false 를 generate 시점에 거부.
+ * @param {string} table @param {unknown} expr @param {string} [path]
+ */
+function assertPartialFilter(table, expr, path = 'partialFilterExpression') {
+  if (expr === null || typeof expr !== 'object' || Array.isArray(expr)) {
+    throw new MegaConfigError(
+      'migration.dialect_feature_unsupported',
+      `mongo dialect: 부분 인덱스 식 '${path}' 는 객체여야 합니다 (table '${table}').`,
+      { details: { table, path } },
+    )
+  }
+  for (const [key, value] of Object.entries(expr)) {
+    if (key.startsWith('$')) {
+      if (!PARTIAL_FILTER_OPS.has(key)) {
+        throw new MegaConfigError(
+          'migration.dialect_feature_unsupported',
+          `mongo dialect: partialFilterExpression 의 '${key}' 는 mongo 가 부분 인덱스에서 지원하지 않습니다 — ` +
+            `허용: [${[...PARTIAL_FILTER_OPS].join(', ')}] (공식 문서의 닫힌 목록, table '${table}', 위치: ${path}). ` +
+            '다른 조건이 필요하면 raw 마이그레이션 대신 조건을 지원 연산자로 재표현하세요(예: $ne → $in 의 여집합 불가 — 설계 재고).',
+          { details: { table, operator: key, path } },
+        )
+      }
+      if (key === '$and' || key === '$or') {
+        if (!Array.isArray(value)) {
+          throw new MegaConfigError('migration.dialect_feature_unsupported', `mongo dialect: '${key}' 는 배열이어야 합니다 (table '${table}', 위치: ${path}).`, { details: { table, path } })
+        }
+        for (let i = 0; i < value.length; i++) assertPartialFilter(table, value[i], `${path}.${key}[${i}]`)
+      } else if (key === '$exists' && value !== true) {
+        throw new MegaConfigError(
+          'migration.dialect_feature_unsupported',
+          `mongo dialect: partialFilterExpression 의 $exists 는 true 만 지원됩니다(공식 문서) (table '${table}', 위치: ${path}).`,
+          { details: { table, path } },
+        )
+      }
+      continue
+    }
+    // 필드 조건 — 값이 객체면 연산자 객체로 보고 재귀, 스칼라/배열이면 equality(허용).
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+      assertPartialFilter(table, value, `${path}.${key}`)
+    }
+  }
+}
+
+/**
+ * 인덱스 생성 문 — createIndex(spec, options). `where` 는 mongo 에선 **JSON 문자열**
+ * (partialFilterExpression)로 해석한다 — SQL 식은 번역 불가라 명시 거부.
+ * @param {string} table @param {Record<string, any>} ix @returns {string}
+ */
+function indexCreateStatement(table, ix) {
+  const name = resolveIndexName(table, ix)
+  quoteIdent(name)
+  if (ix.using !== undefined && !INDEX_USING.includes(ix.using)) {
+    throw new MegaConfigError(
+      'migration.dialect_feature_unsupported',
+      `mongo dialect: 인덱스 using '${ix.using}' 미지원 — 허용: [${INDEX_USING.join(', ')}] (table '${table}').`,
+      { details: { table, using: ix.using } },
+    )
+  }
+  /** @type {Record<string, any>} */
+  const spec = {}
+  for (const entry of ix.columns) {
+    const { field, dir } = parseIndexColumn(entry)
+    // dot-path(중첩 필드 인덱스 — mongo 핵심 패턴) 허용: 세그먼트별로 이름 규칙 검증.
+    for (const seg of field.split('.')) quoteIdent(seg)
+    spec[field] = ix.using !== undefined ? ix.using : dir
+  }
+  /** @type {Record<string, any>} */
+  const options = { name }
+  if (ix.unique === true) options.unique = true
+  if (ix.where !== undefined) {
+    let parsed
+    try {
+      parsed = JSON.parse(ix.where)
+    } catch (err) {
+      throw new MegaConfigError(
+        'migration.dialect_feature_unsupported',
+        `mongo dialect: 부분 인덱스의 where 는 JSON(partialFilterExpression) 문자열이어야 합니다 — SQL 식은 번역되지 않습니다. ` +
+          `예: t.index(['qty'], { where: '{"qty": {"$gt": 0}}' }) (table '${table}', where: ${JSON.stringify(ix.where)}).`,
+        { cause: err, details: { table, where: ix.where } },
+      )
+    }
+    assertPartialFilter(table, parsed)
+    options.partialFilterExpression = parsed
+  }
+  return `await ${coll(table)}.createIndex(${js(spec, '')}, ${js(options, '')})`
+}
+
+/**
+ * 인덱스 삭제 문 — idempotent: 부분 실패 후 재실행이 1차 복구 수단(ADR-208 M-1 원칙)이라
+ * 이미 없는 인덱스(IndexNotFound, code 27)는 무해 통과시킨다. 그 외 에러는 전파.
+ * @param {string} table @param {string} name @returns {string}
+ */
+function dropIndexStatement(table, name) {
+  return (
+    `await ${coll(table)}.dropIndex(${quoteLiteral(name)}).catch((err) => {
+` +
+    `  // 재실행 복구: 이미 없는 인덱스는 무해(IndexNotFound) — 그 외 에러는 전파.
+` +
+    `  if (err.codeName !== 'IndexNotFound' && err.code !== 27) throw err
+` +
+    `})`
+  )
+}
+
+/** 인덱스 삭제 문. @param {string} table @param {Record<string, any>} ix @returns {string} */
+function indexDropStatement(table, ix) {
+  return dropIndexStatement(table, resolveIndexName(table, ix))
+}
+
+/** 컬렉션 삭제 문 — idempotent(NamespaceNotFound, code 26 무해 통과). @param {string} table @returns {string} */
+function dropCollectionStatement(table) {
+  return (
+    `await db.dropCollection(${quoteLiteral(quoteIdent(table))}).catch((err) => {
+` +
+    `  // 재실행 복구: 이미 없는 컬렉션은 무해(NamespaceNotFound) — 그 외 에러는 전파.
+` +
+    `  if (err.codeName !== 'NamespaceNotFound' && err.code !== 26) throw err
+` +
+    `})`
+  )
+}
+
+/** 컬럼 .unique() → UNIQUE 인덱스 생성 문 목록(sqlite 패턴 — 후행 토글이 validator 와 무관). */
+/** @param {string} table @param {string} col @param {Record<string, any>} def @returns {string[]} */
+function uniqueIndexStatements(table, col, def) {
+  if (def.unique === undefined) return []
+  const name = def.unique === true ? uniqueName(table, col) : def.unique.name
+  return [`await ${coll(table)}.createIndex(${js({ [col]: 1 }, '')}, ${js({ name, unique: true }, '')})`]
+}
+
+/**
+ * createCollection 문(+UNIQUE 인덱스) — validator/validationLevel/validationAction 동반.
+ * @param {Record<string, any>} record @returns {string[]}
+ */
+function createCollectionStatements(record) {
+  const table = quoteIdent(record.table)
+  const schema = jsonSchemaOf(record)
+  const { validationLevel, validationAction } = validationOptionsOf(record)
+  /** @type {string[]} */
+  const out = []
+  // strict + required 신설 컬렉션은 안전(빈 컬렉션) — 주석 불필요. 기존 도큐먼트 경고는 collMod 측.
+  // idempotent: 부분 실패 후 재실행에서 이미 존재(NamespaceExists, code 48)하면 validator 를
+  // 목표 상태로 collMod 동기화한다(수렴 — 외부 선생성 컬렉션도 같은 경로로 합류).
+  out.push(
+    `{\n` +
+      `  const validator = { $jsonSchema: ${js(schema, '  ')} }\n` +
+      `  await db.createCollection(${quoteLiteral(table)}, { validator, validationLevel: ${quoteLiteral(validationLevel)}, validationAction: ${quoteLiteral(validationAction)} }).catch(async (err) => {\n` +
+      `    // 재실행 복구: 이미 존재(NamespaceExists)하면 validator 만 목표 상태로 동기화 — 그 외 에러는 전파.\n` +
+      `    if (err.codeName !== 'NamespaceExists' && err.code !== 48) throw err\n` +
+      `    await db.command({ collMod: ${quoteLiteral(table)}, validator, validationLevel: ${quoteLiteral(validationLevel)}, validationAction: ${quoteLiteral(validationAction)} })\n` +
+      `  })\n` +
+      `}`,
+  )
+  for (const [col, def] of Object.entries(record.columns)) out.push(...uniqueIndexStatements(table, col, /** @type {any} */ (def)))
+  return out
+}
+
+/**
+ * collMod 가 "엄격해지는" 변경의 경고 주석 산출 — mongo collMod 는 기존 위배 행이 있어도 항상
+ * 성공하고 도큐먼트 단위로 **늦게**(update 시점 121) 터진다. SQL 은 적용 시점에 실패해 즉시
+ * 드러나므로(maria 1265 실측 — ADR-206 M-3 축소 경고와 동급 보호), mongo 는 경고 필요성이 더
+ * 높다(audit M-1). up/down 모두 같은 산출기를 쓴다(방향 대칭).
+ *
+ * @param {Record<string, any>} record - 교체 목표 record.
+ * @param {Record<string, any>} prevRecord - 직전 record.
+ * @param {{ renamedInto?: Set<string>, renamedAway?: Set<string> }} [renameSets]
+ *   - renamedInto: record 쪽에서 rename 으로 생긴 필드($rename 이 데이터를 옮김 — backfill 불요).
+ *   - renamedAway: prevRecord 쪽에서 rename 으로 떠나는 필드(잔존 아님 — $unset 불요).
+ * @returns {string[]} 경고 주석 행 목록(없으면 빈 배열).
+ */
+function collModWarnings(record, prevRecord, { renamedInto = new Set(), renamedAway = new Set() } = {}) {
+  const table = record.table
+  /** @type {string[]} */
+  const warnings = []
+
+  // ① required 신설 — 해당 필드 없는 기존 도큐먼트의 update 가 121.
+  const prevRequired = new Set(Object.entries(prevRecord.columns).filter(([, d]) => /** @type {any} */ (d).notNull === true).map(([c]) => c))
+  const newRequired = Object.entries(record.columns)
+    .filter(([c, d]) => /** @type {any} */ (d).notNull === true && !prevRequired.has(c) && !renamedInto.has(c))
+    .map(([c]) => c)
+  if (newRequired.length > 0) {
+    warnings.push(
+      `// 경고: [${newRequired.join(', ')}] 가 새로 required 입니다 — 해당 필드가 없는 기존 도큐먼트는 이후`,
+      `//   update/replace 가 검증에 걸립니다. 필요 시 본 문장 앞에 backfill 을 직접 추가하세요.`,
+      `//   예: await ${coll(table)}.updateMany({ ${newRequired[0]}: { $exists: false } }, { $set: { ${newRequired[0]}: /* 기본값 */ } })`,
+    )
+  }
+
+  // ② 필드 제거 — mongo 의 "제거" 는 validator 변경일 뿐 데이터가 지워지지 않고,
+  //    additionalProperties: false 라 잔존 필드 보유 도큐먼트의 모든 update 가 121 이 된다.
+  const removed = Object.keys(prevRecord.columns).filter((c) => record.columns[c] === undefined && !renamedAway.has(c))
+  if (removed.length > 0) {
+    warnings.push(
+      `// 경고: [${removed.join(', ')}] 필드가 스키마에서 제거됩니다 — 데이터는 지워지지 않으며, 잔존 필드를`,
+      `//   가진 도큐먼트는 이후 모든 update 가 검증(additionalProperties)에 걸립니다. 본 문장 뒤에 정리를 권장합니다.`,
+      `//   예: await ${coll(table)}.updateMany({ ${removed[0]}: { $exists: true } }, { $unset: { ${removed[0]}: '' } }, { bypassDocumentValidation: true })`,
+    )
+  }
+
+  // ③ 같은 이름 필드의 축소/타입 변경 — 기존 위배 행은 collMod 시점엔 조용히 통과하고 update 에서 121.
+  for (const [c, d] of Object.entries(record.columns)) {
+    const pd = /** @type {any} */ (prevRecord.columns[c])
+    if (pd === undefined) continue
+    const cd = /** @type {any} */ (d)
+    if (pd.type === 'enum' && cd.type === 'enum') {
+      const removedValues = (pd.values ?? []).filter((/** @type {string} */ v) => !(cd.values ?? []).includes(v))
+      if (removedValues.length > 0) {
+        warnings.push(
+          `// 경고: '${c}' 의 enum 값 [${removedValues.join(', ')}] 이 제거됩니다 — 그 값을 가진 기존 도큐먼트는`,
+          `//   이후 update 가 검증에 걸립니다. 적용 전 backfill(값 치환)을 권장합니다.`,
+        )
+      }
+    } else if ((pd.type === 'varchar' || pd.type === 'char') && (cd.type === 'varchar' || cd.type === 'char') && typeof pd.length === 'number' && typeof cd.length === 'number' && cd.length < pd.length) {
+      warnings.push(
+        `// 경고: '${c}' 의 최대 길이가 ${pd.length} → ${cd.length} 로 축소됩니다 — 초과 길이 기존 도큐먼트는 이후 update 가 검증에 걸립니다.`,
+      )
+    } else if (pd.type !== cd.type) {
+      warnings.push(
+        `// 경고: '${c}' 타입이 ${pd.type} → ${cd.type} 로 바뀝니다 — 기존 도큐먼트는 변환되지 않으며, 옛 타입 잔존 행은 이후 update 가 검증에 걸립니다.`,
+      )
+    }
+  }
+  return warnings
+}
+
+/**
+ * collMod(validator 교체) 문 — 엄격해지는 변경 4종(required 신설·필드 제거·enum/길이 축소·타입
+ * 변경)의 경고 주석 동반. collMod 자체는 같은 값 재설정에 에러가 없어 자연 멱등이다.
+ * @param {Record<string, any>} record - 교체 목표 record.
+ * @param {Record<string, any> | null} prevRecord - 직전 record (경고 산출용 — null 이면 경고 생략).
+ * @param {{ renamedInto?: Set<string>, renamedAway?: Set<string> }} [renameSets]
+ * @returns {string}
+ */
+function collModStatement(record, prevRecord, renameSets = {}) {
+  const schema = jsonSchemaOf(record)
+  const { validationLevel, validationAction } = validationOptionsOf(record)
+  const warnings = prevRecord === null ? [] : collModWarnings(record, prevRecord, renameSets)
+  const stmt =
+    `await db.command({\n` +
+    `  collMod: ${quoteLiteral(quoteIdent(record.table))},\n` +
+    `  validator: { $jsonSchema: ${js(schema, '  ')} },\n` +
+    `  validationLevel: ${quoteLiteral(validationLevel)},\n` +
+    `  validationAction: ${quoteLiteral(validationAction)},\n` +
+    `})`
+  return warnings.length > 0 ? `${warnings.join('\n')}\n${stmt}` : stmt
+}
+
+/**
+ * rebuildTable(=validator 교체) 렌더 — collMod + (differ 수렴이 삼킨) 인덱스/UNIQUE 변경 재계산 +
+ * rename 의 `$rename` 데이터 이동. **컬렉션 재생성이 아니다** — 도큐먼트는 그대로 둔다.
+ * @param {Record<string, any>} from @param {Record<string, any>} to
+ * @param {Record<string, string>} renames - from→to 필드 매핑(사용자 확정).
+ * @returns {{ up: string[], down: string[] }}
+ */
+function renderValidatorRebuild(from, to, renames) {
+  const table = to.table
+  /** @type {string[]} */
+  const up = []
+  /** @type {string[]} */
+  const down = []
+
+  // 1) validator 교체를 **먼저** — strict 검증은 update 의 "결과 도큐먼트" 를 새 validator 로
+  //    평가하므로, $rename 을 교체 전에 돌리면 옛 validator(additionalProperties: false)가 새
+  //    필드명을 거부해 적용이 실패한다(실측 — Document failed validation). 교체 후 $rename 의
+  //    결과는 새 스키마에 부합해 통과한다. down 도 동일 원리(from 으로 교체 후 역 $rename).
+  //    경고는 up/down 모두 산출(방향 대칭 — audit M-1). rename 으로 생기는/떠나는 필드는
+  //    $rename 이 데이터를 옮기므로 backfill/$unset 경고에서 제외.
+  const oldNames = new Set(Object.keys(renames))
+  const newNames = new Set(Object.values(renames))
+  up.push(collModStatement(to, from, { renamedInto: newNames, renamedAway: oldNames }))
+  down.push(collModStatement(from, to, { renamedInto: oldNames, renamedAway: newNames }))
+
+  // 2) rename — 데이터 이동(updateMany $rename). down 은 역방향. bypassDocumentValidation:
+  //    검증은 update "결과 도큐먼트 전체" 를 평가하므로, rename 과 무관한 필드의 기존 드리프트
+  //    (예: 직전 타입 변경의 미변환 데이터)가 있으면 $rename 자체가 거부된다(실측 — down 경로).
+  //    SQL 의 RENAME COLUMN 도 행 데이터를 검증하지 않는다 — 동일 의미로 우회한다(이동만 수행).
+  for (const [oldName, newName] of Object.entries(renames)) {
+    quoteIdent(oldName)
+    quoteIdent(newName)
+    up.push(`await ${coll(table)}.updateMany({}, { $rename: { ${quoteLiteral(oldName)}: ${quoteLiteral(newName)} } }, { bypassDocumentValidation: true })`)
+    down.push(`await ${coll(table)}.updateMany({}, { $rename: { ${quoteLiteral(newName)}: ${quoteLiteral(oldName)} } }, { bypassDocumentValidation: true })`)
+  }
+
+  // 3) 수렴이 삼킨 인덱스/UNIQUE 변경 재계산 — 이름 기준 식별(differ 의 인덱스 diff 와 동일 규칙).
+  /** @type {Map<string, { create: string, drop: string, def: any }>} */
+  const fromIx = new Map()
+  /** @type {Map<string, { create: string, drop: string, def: any }>} */
+  const toIx = new Map()
+  const collect = (/** @type {Record<string, any>} */ record, /** @type {Map<string, any>} */ map) => {
+    for (const ix of record.indexes ?? []) {
+      map.set(resolveIndexName(record.table, ix), { create: indexCreateStatement(record.table, ix), drop: indexDropStatement(record.table, ix), def: ix })
+    }
+    for (const [col, def] of Object.entries(record.columns)) {
+      const d = /** @type {any} */ (def)
+      if (d.unique === undefined) continue
+      const name = d.unique === true ? uniqueName(record.table, col) : d.unique.name
+      map.set(name, {
+        create: uniqueIndexStatements(record.table, col, d)[0],
+        drop: dropIndexStatement(record.table, name),
+        def: { unique: true, columns: [col] },
+      })
+    }
+  }
+  collect(from, fromIx)
+  collect(to, toIx)
+  for (const [name, f] of fromIx) {
+    const t = toIx.get(name)
+    if (t === undefined || !isEqualJson(f.def, t.def)) {
+      up.push(f.drop)
+      down.push(f.create)
+    }
+  }
+  for (const [name, t] of toIx) {
+    const f = fromIx.get(name)
+    if (f === undefined || !isEqualJson(f.def, t.def)) {
+      up.push(t.create)
+      down.push(t.drop)
+    }
+  }
+
+  // down 은 이미 의미 순서(validator 원복 → 역 $rename → 인덱스 역계산) — 추가 역순 불요.
+  return { up, down }
+}
+
+/** @param {unknown} a @param {unknown} b @returns {boolean} */
+function isEqualJson(a, b) {
+  return JSON.stringify(a ?? null) === JSON.stringify(b ?? null)
+}
+
+/**
+ * 변경 연산(op) 1개 → `{ up: string[], down: string[] }` (mongo command JS 문).
+ * 컬럼 수준 op 는 differ 가 rebuildTable 로 수렴하므로 도달하지 않는다(도달 시 명시 에러).
+ * @param {Record<string, any>} op
+ * @returns {{ up: string[], down: string[] }}
+ */
+export function renderOp(op) {
+  const table = op.table
+  switch (op.kind) {
+    case 'createTable':
+      return {
+        up: createCollectionStatements(op.record),
+        down: [`// 경고: 컬렉션과 모든 도큐먼트가 영구 삭제됩니다.\n${dropCollectionStatement(table)}`],
+      }
+    case 'dropTable': {
+      // 테이블(모델) 제거 또는 collection 이름 변경의 drop 측 — mongo 의 이름 변경은
+      // db.renameCollection (트랜잭션 불가)이 있으나 differ 는 모델 단위 drop+create 로 본다
+      // (SQL dialect 와 동일 — 데이터 이전은 자동화 범위 밖). 이름만 바꾸는 의도라면 이 파일을
+      // raw 편집해 `await db.renameCollection('old', 'new')` 1문으로 대체하세요.
+      const down = createCollectionStatements(op.record)
+      for (const ix of op.record.indexes ?? []) down.push(indexCreateStatement(table, ix))
+      return {
+        up: [
+          `// 경고: 컬렉션과 모든 도큐먼트가 영구 삭제됩니다. 이름 변경 의도라면 본 문장을\n` +
+            `//   await db.renameCollection(${quoteLiteral(table)}, '<새이름>') 으로 직접 교체하세요(도큐먼트 보존).\n` +
+            dropCollectionStatement(table),
+        ],
+        down,
+      }
+    }
+    case 'rebuildTable':
+      return renderValidatorRebuild(op.from, op.to, op.renames ?? {})
+    case 'addIndex': {
+      const stmt = indexCreateStatement(table, op.index)
+      // mongo 4.2+ 인덱스 빌드는 항상 online(hybrid) — --concurrent 는 동작 차이가 없다(명시 주석).
+      return {
+        up: [op.concurrent === true ? `// mongo 4.2+ 인덱스 빌드는 항상 online — --concurrent 는 표기일 뿐 동작 차이 없음.\n${stmt}` : stmt],
+        down: [indexDropStatement(table, op.index)],
+      }
+    }
+    case 'dropIndex':
+      return { up: [indexDropStatement(table, op.index)], down: [indexCreateStatement(table, op.index)] }
+    case 'addUnique':
+      return {
+        up: [`await ${coll(table)}.createIndex(${js({ [op.column]: 1 }, '')}, ${js({ name: op.name, unique: true }, '')})`],
+        down: [dropIndexStatement(table, op.name)],
+      }
+    case 'dropUnique':
+      return {
+        up: [dropIndexStatement(table, op.name)],
+        down: [`await ${coll(table)}.createIndex(${js({ [op.column]: 1 }, '')}, ${js({ name: op.name, unique: true }, '')})`],
+      }
+    default:
+      throw new MegaConfigError(
+        'migration.schema_invalid',
+        `mongo dialect: 알 수 없는 변경 연산 '${op.kind}' — 컬럼 수준 변경은 rebuildTriggerKinds 수렴으로 도달하지 않아야 합니다(통합 결함).`,
+        { details: { kind: op.kind } },
+      )
+  }
+}
+
+/**
+ * ops 배열 → { up, down } (down 은 역순 — 적용의 정확한 역).
+ * @param {Array<Record<string, any>>} ops
+ * @returns {{ up: string[], down: string[] }}
+ */
+export function renderOps(ops) {
+  /** @type {string[]} */
+  const up = []
+  /** @type {string[][]} */
+  const downs = []
+  for (const op of ops) {
+    const r = renderOp(op)
+    up.push(...r.up)
+    downs.push(r.down)
+  }
+  return { up, down: downs.reverse().flat() }
+}