mega-framework 0.1.5 → 0.1.7

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

@@ -0,0 +1,476 @@
+// @ts-check
+/**
+ * SQLite dialect (ADR-207) — `dialects/README.md` contract 구현.
+ *
+ * postgres 와의 핵심 차이:
+ *   - **type affinity** — varchar/char/uuid/timestamp 류는 전부 TEXT, 정수 계열은 INTEGER(64bit),
+ *     serial 류는 인라인 PK 일 때만 `INTEGER PRIMARY KEY AUTOINCREMENT`.
+ *   - **`dependsOnRebuild: true`** — 컬럼 drop/타입 변경/제약 변경 등은 sqlite ALTER 가 표현하지
+ *     못해 differ 가 그 테이블의 모든 변경을 `rebuildTable` 1개로 수렴하고, 본 dialect 가
+ *     공식 12-step 재생성 절차를 렌더한다(데이터는 컬럼 매핑 INSERT…SELECT 로 보존).
+ *     재생성 대상 테이블의 트리거/뷰는 generate 가 DB 파일을 직접 읽어 검사한다
+ *     (`inspectRebuildHazards`) — 뷰 충돌은 fail-fast, 트리거는 파일 헤더·콘솔 경고로 이름 명시
+ *     (재생성 SQL 은 사용자가 추가).
+ *   - **FK 는 인라인 정의**(`supportsAlterAddFk: false`) — sqlite 는 ALTER 로 FK 를 추가/삭제할 수
+ *     없다. CREATE TABLE 에 named 테이블 제약으로 싣고(스키마는 forward reference 허용), FK 변경은
+ *     rebuild 경로. RENAME COLUMN 은 스키마 내 참조를 자동 갱신하므로 FK 이름 동기화 자체가 불필요.
+ *   - UNIQUE 는 제약이 아니라 **UNIQUE INDEX** 로 렌더 — 후행 추가/삭제가 rebuild 없이 가능하고
+ *     명명 표준(uniq_*)이 그대로 diff 식별자가 된다.
+ *   - 컬럼 코멘트 미지원 — setComment 는 SQL 주석 한 줄로 대체(명시 안내, silent 누락 아님).
+ *   - `PRAGMA foreign_keys` 는 트랜잭션 안에서 변경 불가 — rebuild 마이그레이션은
+ *     `export const transaction = false`(generate 가 자동 설정) + 내부 BEGIN/COMMIT 으로 진행한다.
+ *
+ * @module core/migration/dialects/sqlite
+ */
+import { MegaConfigError } from '../../../errors/config-error.js'
+
+// ── dialect 표준 인터페이스 속성 ─────────────────────────────────────────────
+/** sqlite 는 식별자 길이 제한이 사실상 없다. */
+export const identifierMaxBytes = Infinity
+/** CONCURRENTLY 동등물 없음 — --concurrent 는 generate 가 명시 거부. */
+export const supportsConcurrentIndex = false
+/** enum 표현 전략 — TEXT + CHECK(col IN (...)). */
+export const enumStrategy = 'check'
+/** RENAME COLUMN(3.25+)은 트랜잭션 내 정상 동작. */
+export const supportsRenameInTx = true
+/** 단순 DROP COLUMN(3.35+)도 트랜잭션 대상 — 단 본 dialect 는 호환 위해 rebuild 로 처리. */
+export const canDropColumnInTx = true
+/** 핵심 — 다수 ALTER 미지원이라 테이블 재생성(12-step) 패턴 사용. */
+export const dependsOnRebuild = true
+/** RENAME CONSTRAINT 없음. (FK 는 인라인이라 이름 동기화 자체가 불필요.) */
+export const supportsRenameConstraint = false
+/** ALTER 로 FK 추가/삭제 불가 — CREATE TABLE 인라인 + 변경은 rebuild. */
+export const supportsAlterAddFk = false
+/** 컬럼/FK 변경은 rebuild 로 수렴 — dropFk 선행 발행 자체가 없다. */
+export const requiresDropFkBeforeDropColumn = false
+/** SQL DDL 렌더 dialect — 생성 파일이 `db.query(sql)` 계약을 쓴다(mongo 와 분기, ADR-209). */
+export const usesSqlDdl = true
+
+/** bare 허용 식별자 — 그 외는 따옴표. */
+const BARE_IDENT_RE = /^[a-z_][a-z0-9_]*$/
+
+/**
+ * SQL 식별자 인용 — postgres 와 동일한 더블쿼트(필요 시만).
+ * @param {string} name @returns {string}
+ */
+export function quoteIdent(name) {
+  if (BARE_IDENT_RE.test(name)) return name
+  return `"${name.replaceAll('"', '""')}"`
+}
+
+/**
+ * 값 literal 인용 — '' 이스케이프(sqlite 는 백슬래시 escape 없음). boolean 은 INTEGER 0/1.
+ * @param {unknown} value @returns {string}
+ */
+export function quoteLiteral(value) {
+  if (value === null) return 'NULL'
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) {
+      throw new MegaConfigError('migration.schema_invalid', `default 값이 유한한 수가 아닙니다: ${value}`, { details: { value: String(value) } })
+    }
+    return String(value)
+  }
+  if (typeof value === 'boolean') return value ? '1' : '0' // boolean → INTEGER affinity 정합
+  if (typeof value === 'object' && value !== null && typeof (/** @type {any} */ (value).raw) === 'string') {
+    return /** @type {any} */ (value).raw
+  }
+  return `'${String(value).replaceAll("'", "''")}'`
+}
+
+/**
+ * 컬럼 타입 → sqlite 타입(affinity).
+ * @param {Record<string, any>} def @returns {string}
+ */
+export function typeSql(def) {
+  switch (def.type) {
+    case 'serial':
+    case 'bigSerial':
+    case 'integer':
+    case 'bigInteger':
+    case 'smallInteger':
+    case 'boolean': // 0/1 — INTEGER affinity
+      return 'INTEGER'
+    case 'real':
+    case 'doublePrecision':
+      return 'REAL'
+    case 'decimal':
+      return `NUMERIC(${def.precision}, ${def.scale})`
+    case 'varchar':
+    case 'text':
+    case 'char':
+    case 'uuid':
+    case 'timestamp':
+    case 'timestamptz': // ISO8601 TEXT 저장 규약(ADR-207)
+    case 'date':
+    case 'time':
+    case 'json':
+    case 'jsonb':
+    case 'enum':
+      return 'TEXT'
+    case 'bytea':
+      return 'BLOB'
+    default:
+      throw new MegaConfigError('migration.schema_invalid', `sqlite dialect: 알 수 없는 타입 '${def.type}'.`, { details: { type: def.type } })
+  }
+}
+
+// ── 명명 표준 — postgres 와 동일 규칙 ────────────────────────────────────────
+/** @param {string} table @param {string[]} cols @param {boolean} [unique] @returns {string} */
+export function indexName(table, cols, unique = false) {
+  return `${unique ? 'uniq' : 'idx'}_${table}_${cols.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.schema_invalid', `표현식 인덱스는 name 이 필수입니다 (table '${table}').`, { details: { table } })
+  }
+  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}`
+}
+/** @param {string} table @returns {string} */
+export function pkName(table) {
+  return `pk_${table}`
+}
+/** sqlite 인라인 PK 는 별도 제약 이름이 없다 — diff 정규화용 합성 명칭. @param {string} table @returns {string} */
+export function inlinePkName(table) {
+  return `pk_${table}`
+}
+
+/**
+ * enum 의 CHECK 식 — 유일한 enum 렌더 지점(differ 는 values 만 전달).
+ * @param {string} col @param {string[]} values @returns {string}
+ */
+export function enumCheckExpr(col, values) {
+  return `${quoteIdent(col)} IN (${values.map((v) => quoteLiteral(v)).join(', ')})`
+}
+
+/**
+ * 컬럼 정의 절. serial 류 + 인라인 PK 는 `INTEGER PRIMARY KEY AUTOINCREMENT`(rowid alias).
+ * enum/명시 CHECK 는 컬럼 절이 아니라 테이블 제약(named)으로 — 호출부가 별도 합성.
+ * @param {string} name @param {Record<string, any>} def @param {{ inlinePrimary?: boolean }} [opts]
+ * @returns {string}
+ */
+function columnClause(name, def, { inlinePrimary = true } = {}) {
+  const isSerial = def.type === 'serial' || def.type === 'bigSerial'
+  let sql = `${quoteIdent(name)} ${typeSql(def)}`
+  if (inlinePrimary && def.primary === true) {
+    sql += isSerial ? ' PRIMARY KEY AUTOINCREMENT' : ' PRIMARY KEY'
+  }
+  if (def.notNull === true) sql += ' NOT NULL'
+  if (def.default !== undefined) sql += ` DEFAULT ${quoteLiteral(def.default)}`
+  return sql
+}
+
+/**
+ * 컬럼의 CHECK 테이블 제약 절(enum + 명시 check) — CREATE TABLE 본문용.
+ * @param {string} table @param {string} col @param {Record<string, any>} def @returns {string[]}
+ */
+function checkConstraintClauses(table, col, def) {
+  /** @type {string[]} */
+  const out = []
+  if (def.type === 'enum') {
+    out.push(`CONSTRAINT ${quoteIdent(def.enumName ?? checkName(table, col))} CHECK (${enumCheckExpr(col, def.values)})`)
+  }
+  if (def.check !== undefined) {
+    out.push(`CONSTRAINT ${quoteIdent(def.check.name ?? checkName(table, col))} CHECK (${def.check.expr})`)
+  }
+  return out
+}
+
+/** FK 테이블 제약 절. @param {string} table @param {string} col @param {Record<string, any>} ref @returns {string} */
+function fkConstraintClause(table, col, ref) {
+  const name = ref.name ?? fkName(table, col, ref.table)
+  let sql = `CONSTRAINT ${quoteIdent(name)} FOREIGN KEY (${quoteIdent(col)}) REFERENCES ${quoteIdent(ref.table)} (${quoteIdent(ref.column)})`
+  if (ref.onDelete !== undefined) sql += ` ON DELETE ${ref.onDelete.toUpperCase()}`
+  if (ref.onUpdate !== undefined) sql += ` ON UPDATE ${ref.onUpdate.toUpperCase()}`
+  return sql
+}
+
+/**
+ * UNIQUE 인덱스 생성 문 — sqlite 는 UNIQUE 를 제약이 아니라 인덱스로 렌더(후행 추가/삭제가
+ * rebuild 없이 가능, 명명 표준 유지).
+ * @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 [`CREATE UNIQUE INDEX ${quoteIdent(name)} ON ${quoteIdent(table)} (${quoteIdent(col)})`]
+}
+
+/**
+ * 인덱스 생성 문 — 부분(WHERE)·표현식 인덱스 지원(sqlite ✓). USING 은 미지원(거부).
+ * @param {string} table @param {Record<string, any>} ix @returns {string}
+ */
+function indexCreateStatement(table, ix) {
+  if (ix.using !== undefined) {
+    throw new MegaConfigError('migration.dialect_feature_unsupported', `sqlite 는 인덱스 USING 절을 지원하지 않습니다 (table '${table}').`, {
+      details: { table, using: ix.using },
+    })
+  }
+  const name = resolveIndexName(table, ix)
+  const target = ix.expression !== undefined ? `(${ix.expression})` : `(${ix.columns.map(quoteIdent).join(', ')})`
+  let sql = `CREATE ${ix.unique === true ? 'UNIQUE ' : ''}INDEX ${quoteIdent(name)} ON ${quoteIdent(table)} ${target}`
+  if (ix.where !== undefined) sql += ` WHERE ${ix.where}`
+  return sql
+}
+
+/**
+ * CREATE TABLE 문(+UNIQUE 인덱스) — FK·CHECK 는 named 테이블 제약으로 본문 인라인.
+ * @param {Record<string, any>} record @param {{ tableNameOverride?: string }} [opts] - rebuild 의 임시 테이블명.
+ * @returns {string[]}
+ */
+function createTableStatements(record, { tableNameOverride } = {}) {
+  const table = tableNameOverride ?? record.table
+  /** @type {string[]} */
+  const lines = []
+  for (const [name, def] of Object.entries(record.columns)) {
+    lines.push('  ' + columnClause(name, def))
+  }
+  if (record.primaryKey !== undefined) {
+    lines.push(`  CONSTRAINT ${quoteIdent(pkName(record.table))} PRIMARY KEY (${record.primaryKey.map(quoteIdent).join(', ')})`)
+  }
+  for (const [name, def] of Object.entries(record.columns)) {
+    for (const c of checkConstraintClauses(record.table, name, def)) lines.push('  ' + c)
+    if (def.references !== undefined) lines.push('  ' + fkConstraintClause(record.table, name, def.references))
+  }
+  /** @type {string[]} */
+  const out = [`CREATE TABLE ${quoteIdent(table)} (\n${lines.join(',\n')}\n)`]
+  if (tableNameOverride === undefined) {
+    for (const [name, def] of Object.entries(record.columns)) out.push(...uniqueIndexStatements(record.table, name, def))
+  }
+  return out
+}
+
+/**
+ * 12-step 테이블 재생성 — 공식 절차(PRAGMA OFF → tx → 새 테이블 → 데이터 이주 → 교체 → 인덱스 →
+ * fk check → COMMIT → PRAGMA ON). 트리거/뷰 재생성은 범위 밖(모듈 docstring·생성 파일 헤더 명시).
+ * @param {Record<string, any>} from @param {Record<string, any>} to
+ * @param {Record<string, string>} renames - from→to 컬럼 매핑.
+ * @returns {string[]}
+ */
+function rebuildStatements(from, to, renames) {
+  const table = to.table
+  const tmp = `_new_${table}`
+  // BEGIN IMMEDIATE — 시작 시점에 쓰기 락을 선점해 동시 러너의 rebuild 가 절차 중간에 끼어들지
+  // 못하게 한다(deferred BEGIN 은 첫 쓰기까지 락이 없어 read-check-apply 경합 창이 넓다).
+  /** @type {string[]} */
+  const out = ['PRAGMA foreign_keys=OFF', 'BEGIN IMMEDIATE']
+  out.push(...createTableStatements(to, { tableNameOverride: tmp }))
+  // 데이터 이주 — to 컬럼별 출처: rename 매핑 → 동명 컬럼 → (없으면 제외 = DEFAULT/NULL).
+  /** @type {string[]} */
+  const targetCols = []
+  /** @type {string[]} */
+  const sourceCols = []
+  for (const colName of Object.keys(to.columns)) {
+    const renamedFrom = Object.entries(renames).find(([, n]) => n === colName)?.[0]
+    const source = renamedFrom ?? (from.columns[colName] !== undefined ? colName : undefined)
+    if (source !== undefined) {
+      targetCols.push(quoteIdent(colName))
+      sourceCols.push(quoteIdent(source))
+    }
+  }
+  if (targetCols.length > 0) {
+    out.push(`INSERT INTO ${quoteIdent(tmp)} (${targetCols.join(', ')}) SELECT ${sourceCols.join(', ')} FROM ${quoteIdent(table)}`)
+  }
+  out.push(`DROP TABLE ${quoteIdent(table)}`)
+  out.push(`ALTER TABLE ${quoteIdent(tmp)} RENAME TO ${quoteIdent(table)}`)
+  for (const [name, def] of Object.entries(to.columns)) out.push(...uniqueIndexStatements(table, name, def))
+  for (const ix of to.indexes ?? []) out.push(indexCreateStatement(table, ix))
+  out.push('PRAGMA foreign_key_check') // 위반 행을 반환(throw 아님) — 결과 검토는 운영자 몫(헤더 안내)
+  out.push('COMMIT')
+  out.push('PRAGMA foreign_keys=ON')
+  return out
+}
+
+/** renames(from→to)를 to→from 으로 뒤집는다. @param {Record<string, string>} renames @returns {Record<string, string>} */
+function invertRenames(renames) {
+  return Object.fromEntries(Object.entries(renames).map(([a, b]) => [b, a]))
+}
+
+/**
+ * rebuild 위험 요소 검사(best-effort) — 대상 DB 파일이 있으면 읽기 전용으로 열어 sqlite_master 에서
+ * 재생성 테이블의 **트리거**(DROP TABLE 과 함께 소실 — 사용자 재생성 필요)와 테이블을 참조하는
+ * **뷰**(3.25+ 가 RENAME 시점에 뷰를 재파싱해 rebuild 가 통째 실패)를 찾는다. generate 는 원래
+ * DB 무연결 설계지만 sqlite 는 "서버" 가 아니라 파일이라 이 검사가 유일한 사전 방어선이다.
+ * 파일 부재(첫 generate 등)·열기 실패는 빈 결과 — 헤더의 일반 경고가 잔여 방어선.
+ *
+ * @param {string} filename - sqlite DB 파일 경로(':memory:' 면 검사 불가).
+ * @param {string[]} tables - rebuild 대상 테이블들.
+ * @returns {Promise<{ triggers: string[], conflictViews: string[] }>}
+ */
+export async function inspectRebuildHazards(filename, tables) {
+  /** @type {{ triggers: string[], conflictViews: string[] }} */
+  const empty = { triggers: [], conflictViews: [] }
+  if (typeof filename !== 'string' || filename === ':memory:') return empty
+  let db
+  try {
+    const { default: Database } = await import('better-sqlite3')
+    db = new Database(filename, { readonly: true, fileMustExist: true })
+  } catch {
+    // 파일 부재/열기 실패 — 첫 generate(아직 DB 없음) 등 정상 경로. 헤더 일반 경고로 폴백.
+    return empty
+  }
+  try {
+    const rows = /** @type {Array<{ type: string, name: string, tbl_name: string, sql: string | null }>} */ (
+      db.prepare("SELECT type, name, tbl_name, sql FROM sqlite_master WHERE type IN ('trigger', 'view')").all()
+    )
+    const triggers = rows.filter((r) => r.type === 'trigger' && tables.includes(r.tbl_name)).map((r) => r.name)
+    // 뷰는 SQL 본문이 대상 테이블을 단어 경계로 언급하면 충돌 후보(보수적 — 과탐지는 안전 방향).
+    const conflictViews = rows
+      .filter((r) => r.type === 'view' && typeof r.sql === 'string' && tables.some((t) => new RegExp(`\\b${t}\\b`, 'i').test(/** @type {string} */ (r.sql))))
+      .map((r) => r.name)
+    return { triggers, conflictViews }
+  } finally {
+    db.close()
+  }
+}
+
+/**
+ * 변경 연산(op) 1개 → `{ up: string[], down: string[] }`.
+ * setNotNull/setDefault/addCheck/addFk/… 류는 differ 가 rebuildTable 로 수렴하므로 도달하지 않는다
+ * (도달 시 명시 에러 — silent 누락 금지).
+ * @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: createTableStatements(op.record), down: [`DROP TABLE IF EXISTS ${quoteIdent(table)}`] }
+    case 'dropTable': {
+      const down = createTableStatements(op.record)
+      for (const ix of op.record.indexes ?? []) down.push(indexCreateStatement(table, ix))
+      return {
+        up: [
+          // FK 로 얽힌 테이블 동시 제거 — sqlite 는 dropFk 가 불가하므로 트랜잭션 한정 지연 검사로 순서 무관화.
+          'PRAGMA defer_foreign_keys=ON',
+          `-- 경고: 테이블과 모든 데이터가 영구 삭제됩니다 — down 으로 구조(제약·인덱스 포함)는 복원되지만 데이터는 복원되지 않습니다.\nDROP TABLE IF EXISTS ${quoteIdent(table)}`,
+        ],
+        down,
+      }
+    }
+    case 'addColumn': {
+      if (op.def.primary === true) {
+        throw new MegaConfigError('migration.unsupported_change', `sqlite: 기존 테이블에 PRIMARY KEY 컬럼 추가는 재생성이 필요합니다 — 다른 변경과 함께 적용하거나 raw 마이그레이션으로 작성하세요 (table '${table}').`, {
+          details: { table, column: op.column },
+        })
+      }
+      /** @type {string[]} */
+      const up = []
+      // ADD COLUMN 은 컬럼 제약만 허용 — named CHECK·인라인 REFERENCES 를 컬럼 절에 직렬로 붙인다.
+      let clause = columnClause(op.column, op.def, { inlinePrimary: false })
+      for (const c of checkConstraintClauses(table, op.column, op.def)) clause += ` ${c}`
+      const ref = op.def.references
+      if (ref !== undefined) {
+        // 인라인 REFERENCES — sqlite 허용(컬럼이 NULL 허용일 때). NOT NULL FK 추가는 rebuild 경로.
+        clause += ` REFERENCES ${quoteIdent(ref.table)} (${quoteIdent(ref.column)})`
+        if (ref.onDelete !== undefined) clause += ` ON DELETE ${ref.onDelete.toUpperCase()}`
+        if (ref.onUpdate !== undefined) clause += ` ON UPDATE ${ref.onUpdate.toUpperCase()}`
+      }
+      let add = `ALTER TABLE ${quoteIdent(table)} ADD COLUMN ${clause}`
+      if (op.def.notNull === true && op.def.default === undefined) {
+        add = `-- 경고: sqlite 는 기존 행이 있으면 DEFAULT 없는 NOT NULL 컬럼 추가가 실패합니다.\n${add}`
+      }
+      up.push(add)
+      up.push(...uniqueIndexStatements(table, op.column, op.def))
+      return {
+        up,
+        down: [`-- 경고: 컬럼 데이터가 영구 삭제됩니다.\nALTER TABLE ${quoteIdent(table)} DROP COLUMN ${quoteIdent(op.column)}`],
+      }
+    }
+    case 'renameColumn':
+      return {
+        up: [`ALTER TABLE ${quoteIdent(table)} RENAME COLUMN ${quoteIdent(op.from)} TO ${quoteIdent(op.to)}`],
+        down: [`ALTER TABLE ${quoteIdent(table)} RENAME COLUMN ${quoteIdent(op.to)} TO ${quoteIdent(op.from)}`],
+      }
+    case 'addUnique':
+      return {
+        up: [`CREATE UNIQUE INDEX ${quoteIdent(op.name)} ON ${quoteIdent(table)} (${quoteIdent(op.column)})`],
+        down: [`DROP INDEX IF EXISTS ${quoteIdent(op.name)}`],
+      }
+    case 'dropUnique':
+      return {
+        up: [`DROP INDEX IF EXISTS ${quoteIdent(op.name)}`],
+        down: [`CREATE UNIQUE INDEX ${quoteIdent(op.name)} ON ${quoteIdent(table)} (${quoteIdent(op.column)})`],
+      }
+    case 'addIndex':
+      return {
+        up: [indexCreateStatement(table, op.index)],
+        down: [`DROP INDEX IF EXISTS ${quoteIdent(resolveIndexName(table, op.index))}`],
+      }
+    case 'dropIndex':
+      return {
+        up: [`DROP INDEX IF EXISTS ${quoteIdent(resolveIndexName(table, op.index))}`],
+        down: [indexCreateStatement(table, op.index)],
+      }
+    case 'setComment':
+      // sqlite 는 컬럼 코멘트가 없다 — 누락을 숨기지 않고 SQL 주석으로 명시(실행 무해).
+      return {
+        up: [`-- sqlite: 컬럼 코멘트 미지원 — '${table}.${op.column}' 의 코멘트 변경은 적용되지 않습니다.`],
+        down: [`-- sqlite: 컬럼 코멘트 미지원 — '${table}.${op.column}' 의 코멘트 변경은 적용되지 않습니다.`],
+      }
+    case 'rebuildTable':
+      return {
+        up: rebuildStatements(op.from, op.to, op.renames ?? {}),
+        down: rebuildStatements(op.to, op.from, invertRenames(op.renames ?? {})),
+      }
+    default:
+      // setNotNull/alterType/addFk 류는 differ 가 rebuildTable 로 수렴 — 도달은 differ 결함.
+      throw new MegaConfigError('migration.schema_invalid', `sqlite dialect: '${op.kind}' 는 직접 렌더 대상이 아닙니다(rebuildTable 로 수렴돼야 함).`, {
+        details: { kind: op.kind },
+      })
+  }
+}
+
+/**
+ * 연산 목록 → `{ 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() }
+}
+
+// ── DML facet (ADR-212) — CRUD(model-crud)용 DML 보조. better-sqlite3 RETURNING 지원(실측). ──
+export const paramStyle = 'positional'
+/** sqlite 는 위치식 `?`(인덱스 무시). @returns {string} */
+export function placeholder() {
+  return '?'
+}
+export const supportsReturning = true
+export const supportsBulkReturning = true
+/** SELECT native(stmt.all 배열) → record[]. @param {any} res @returns {any[]} */
+export function parseReadResult(res) {
+  return Array.isArray(res) ? res : []
+}
+/** write native → 정규화. RETURNING 이면 stmt.all 배열, 아니면 `{ changes, lastInsertRowid }`. @param {any} res */
+export function parseWriteResult(res) {
+  if (Array.isArray(res)) return { count: res.length, rows: res }
+  return { count: Number(res?.changes ?? 0), lastInsertRowid: res?.lastInsertRowid }
+}
+/** upsert 절 — `ON CONFLICT (...) DO UPDATE SET col = excluded.col`. @param {{ conflictCols: string[], updateCols: string[] }} o */
+export function upsertClause({ conflictCols, updateCols }) {
+  const set = updateCols.map((c) => `${quoteIdent(c)} = excluded.${quoteIdent(c)}`).join(', ')
+  return `ON CONFLICT (${conflictCols.map(quoteIdent).join(', ')}) DO UPDATE SET ${set}`
+}