mega-framework 0.1.5 → 0.1.7

package/src/core/migration/model-scan.js

@@ -0,0 +1,84 @@
+// @ts-check
+/**
+ * 스키마 모델 file-scan (ADR-204) — `apps/<app>/models/**` 를 재귀 스캔해 `static schema` 를
+ * 선언한 모델을 수집한다(별도 register 단계 없음 — services-loader/ADR-148 의 자동 스캔 패턴 정합).
+ *
+ * 식별은 **duck-typing**: export 값이 `schema` 함수 + `table`/`adapter` 문자열을 가지면 모델로
+ * 본다(클래스 identity 비의존 — 프레임워크 패키지 사본이 달라도 동작). `static schema` 가 없는
+ * 모델(레거시 raw SQL 운용)은 **정상적으로 건너뛴다** — 자동 생성은 옵트인.
+ *
+ * 제외 규칙: `_` 로 시작하는 파일/디렉토리, `*.test.js`, `static skip = true` 옵트아웃.
+ *
+ * @module core/migration/model-scan
+ */
+import { existsSync, readdirSync, statSync } from 'node:fs'
+import { join, resolve as pathResolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { MegaConfigError } from '../../errors/config-error.js'
+
+/**
+ * @typedef {{ name: string, table: string, adapter: string, app: string, file: string, Model: any }} ScannedModel
+ */
+
+/**
+ * models 디렉토리 재귀 수집 — `_` prefix·테스트 파일 제외, 결정적 순서(이름순).
+ * @param {string} dir @returns {string[]} 절대 경로 목록.
+ */
+function collectModelFiles(dir) {
+  /** @type {string[]} */
+  const out = []
+  const entries = readdirSync(dir, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+  for (const e of entries) {
+    if (e.name.startsWith('_')) continue
+    const abs = join(dir, e.name)
+    if (e.isDirectory()) {
+      out.push(...collectModelFiles(abs))
+      continue
+    }
+    if (!e.name.endsWith('.js') || e.name.endsWith('.test.js')) continue
+    out.push(pathResolve(abs))
+  }
+  return out
+}
+
+/**
+ * 모든 앱의 models 폴더를 스캔해 schema 모델을 수집한다.
+ *
+ * @param {{ projectRoot: string, appNames: string[] }} opts
+ * @returns {Promise<ScannedModel[]>}
+ * @throws {MegaConfigError} `migration.model_load_failed` - 모델 파일 import 실패(문법 오류 등).
+ */
+export async function scanSchemaModels({ projectRoot, appNames }) {
+  /** @type {ScannedModel[]} */
+  const out = []
+  for (const app of appNames) {
+    const dir = join(projectRoot, 'apps', app, 'models')
+    if (!existsSync(dir)) continue // 모델 폴더 부재는 정상(마이그레이션 폴더와 동일 규칙)
+    for (const file of collectModelFiles(dir)) {
+      let mod
+      try {
+        // mtime 쿼리로 ESM 모듈 캐시를 우회 — 같은 프로세스에서 모델 수정 후 재스캔(연속 generate·
+        // 테스트) 시 옛 모듈이 잡히면 diff 가 변경을 못 본다.
+        mod = await import(`${pathToFileURL(file).href}?mtime=${statSync(file).mtimeMs}`)
+      } catch (err) {
+        // ESM dynamic import 의 SyntaxError stack 은 V8 내부 프레임뿐(위치 정보 없음 — 실측)이라
+        // stack 병기는 노이즈만 더한다. 파일 경로 + 원문 메시지를 정확히 — 위치는 사용자가
+        // `node <file>` 직접 실행으로 확인 가능(cause 에 원본 보존).
+        throw new MegaConfigError(
+          'migration.model_load_failed',
+          `모델 파일 로드 실패: ${file} — ${/** @type {any} */ (err).message}`,
+          { cause: err, details: { file, app } },
+        )
+      }
+      for (const exported of Object.values(mod)) {
+        const Model = /** @type {any} */ (exported)
+        if (typeof Model !== 'function') continue
+        if (typeof Model.schema !== 'function') continue // schema 미선언(레거시 raw SQL 모델) — 옵트인 제외
+        if (Model.skip === true) continue // 명시 옵트아웃
+        if (typeof Model.table !== 'string' || typeof Model.adapter !== 'string') continue
+        out.push({ name: Model.name, table: Model.table, adapter: Model.adapter, app, file, Model })
+      }
+    }
+  }
+  return out
+}

package/src/core/migration/mongo-migration-db.js

@@ -0,0 +1,97 @@
+// @ts-check
+/**
+ * mongo 마이그레이션 db 셈(shim) (ADR-209) — 러너({@link module:core/migration-runner})는 이력
+ * 부기(`mega_migrations`)를 **framework-controlled SQL 상수**로 수행한다(ADR-149 — name 은
+ * 파일명 규약 검증, applied_at 은 ISO, checksum 은 sha-256 hex 라 인라인 안전). mongo 는 SQL 이
+ * 없으므로, native `Db` 를 감싼 Proxy 가 그 닫힌 SQL 집합만 collection 연산으로 번역한다 —
+ * 러너는 한 줄도 바뀌지 않는다(SQL dialect 경로 영향 0).
+ *
+ * 마이그레이션 파일(`up(db)/down(db)`)이 받는 `db` 도 이 Proxy 다 — `query` 외 모든 속성은
+ * native `Db` 로 위임되므로 생성 파일의 `db.createCollection(...)`/`db.collection(...)`/
+ * `db.command(...)` 가 그대로 동작한다. 임의 SQL(`db.query('SELECT …')`)은 명시 거부 —
+ * mongo 마이그레이션 본문은 도큐먼트 API 를 쓴다.
+ *
+ * 이력 도큐먼트: `{ _id: <name>, name, applied_at, checksum }` — `_id` 가 곧 PK 라 동시 적용
+ * 경합은 중복 키(E11000)로 차단되고, 러너의 실패 후 이력 재확인(ADR-208 M-2)이 패자를 skip 으로
+ * 흡수한다(SQL 경로와 동일 거동).
+ *
+ * @module core/migration/mongo-migration-db
+ */
+import { MegaConfigError } from '../../errors/config-error.js'
+import { MIGRATIONS_TABLE } from '../migration-runner.js'
+
+/** 러너 부기 SQL → 번역기. 패턴은 migration-runner.js 의 상수 문장과 1:1 (회귀 테스트로 고정). */
+const SQL_HANDLERS = [
+  {
+    // ensureTable — 이력 컬렉션은 첫 insert 시 자동 생성되므로 no-op (name=_id 가 PK).
+    re: new RegExp(`^CREATE TABLE IF NOT EXISTS ${MIGRATIONS_TABLE} `),
+    run: async () => ({ rows: /** @type {any[]} */ ([]), rowCount: 0 }),
+  },
+  {
+    // checksum 컬럼 존재 검사 — 도큐먼트 모델엔 컬럼 개념이 없어 항상 "존재"(보강 ALTER 불요).
+    re: new RegExp(`^SELECT checksum FROM ${MIGRATIONS_TABLE} LIMIT 1$`),
+    run: async () => ({ rows: /** @type {any[]} */ ([]), rowCount: 0 }),
+  },
+  {
+    re: new RegExp(`^SELECT name, checksum FROM ${MIGRATIONS_TABLE}$`),
+    /** @param {import('mongodb').Db} db */
+    run: async (db) => {
+      const rows = await db.collection(MIGRATIONS_TABLE).find({}, { projection: { _id: 0, name: 1, checksum: 1 } }).toArray()
+      return { rows, rowCount: rows.length }
+    },
+  },
+  {
+    re: new RegExp(`^SELECT name FROM ${MIGRATIONS_TABLE} WHERE name = '([^']+)'$`),
+    /** @param {import('mongodb').Db} db @param {RegExpMatchArray} m */
+    run: async (db, m) => {
+      const doc = await db.collection(MIGRATIONS_TABLE).findOne({ name: m[1] }, { projection: { _id: 0, name: 1 } })
+      return { rows: doc === null ? [] : [doc], rowCount: doc === null ? 0 : 1 }
+    },
+  },
+  {
+    re: new RegExp(`^INSERT INTO ${MIGRATIONS_TABLE} \\(name, applied_at, checksum\\) VALUES \\('([^']+)', '([^']+)', '([^']+)'\\)$`),
+    /** @param {import('mongodb').Db} db @param {RegExpMatchArray} m */
+    run: async (db, m) => {
+      await db.collection(MIGRATIONS_TABLE).insertOne({ _id: /** @type {any} */ (m[1]), name: m[1], applied_at: m[2], checksum: m[3] })
+      return { rowCount: 1 }
+    },
+  },
+  {
+    re: new RegExp(`^DELETE FROM ${MIGRATIONS_TABLE} WHERE name = '([^']+)'$`),
+    /** @param {import('mongodb').Db} db @param {RegExpMatchArray} m */
+    run: async (db, m) => {
+      const r = await db.collection(MIGRATIONS_TABLE).deleteOne({ name: m[1] })
+      return { rowCount: r.deletedCount }
+    },
+  },
+]
+
+/**
+ * native `Db` → 러너/마이그레이션 파일 공용 db 셈.
+ *
+ * @param {import('mongodb').Db} nativeDb - 연결된 mongodb `Db` (adapter.native).
+ * @returns {any} Proxy — `query(sql)` 은 부기 SQL 번역, 그 외는 native `Db` 위임.
+ */
+export function createMongoMigrationDb(nativeDb) {
+  /** @param {string} sql @returns {Promise<any>} */
+  const query = async (sql) => {
+    for (const h of SQL_HANDLERS) {
+      const m = sql.match(h.re)
+      if (m !== null) return h.run(nativeDb, m)
+    }
+    throw new MegaConfigError(
+      'migration.mongo_sql_unsupported',
+      `mongo 마이그레이션에서 SQL 을 실행할 수 없습니다 — 본문은 도큐먼트 API(db.collection(...)/db.command(...))를 사용하세요. ` +
+        `(받은 SQL 머리: ${sql.slice(0, 80)})`,
+      { details: { sql: sql.slice(0, 200) } },
+    )
+  }
+  return new Proxy(nativeDb, {
+    get(target, prop) {
+      if (prop === 'query') return query
+      const value = Reflect.get(target, prop, target) // receiver=proxy 면 Db 내부 private 접근이 깨질 수 있다
+      // Db 의 메서드는 내부 this 바인딩이 필요하다(collection/command/createCollection …).
+      return typeof value === 'function' ? value.bind(target) : value
+    },
+  })
+}

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

@@ -0,0 +1,400 @@
+// @ts-check
+/**
+ * 스키마 빌더 (ADR-204) — 모델의 `static schema = (t) => ({ ... })` 선언을 **직렬화 가능한 record**
+ * 로 변환한다. record 가 journal snapshot(`.mega/journal/`)·diff·SQL 렌더의 단일 정본이다.
+ *
+ * 빌더는 마이그레이션 **생성 전용**이다 — 런타임 쿼리·CRUD 헬퍼는 만들지 않는다(ADR-009 ORM 부재
+ * 결정 준수). 모델은 여전히 native handle(`this.db`)·계측 쿼리(`this.query`)로 도메인 메서드를
+ * 직접 작성한다.
+ *
+ * # 사용 예
+ *   ```js
+ *   export class User extends MegaModel {
+ *     static adapter = 'primary'
+ *     static table = 'users'
+ *     static schema = (t) => ({
+ *       id: t.serial().primary(),
+ *       email: t.varchar(200).notNull().unique(),
+ *       role: t.enum(['admin', 'user']).default('user'),
+ *       orgId: t.integer().references('Organization', 'id', { onDelete: 'cascade' }),
+ *       createdAt: t.timestamptz().defaultNow(),
+ *     })
+ *     static indexes = (t) => [t.index(['role', 'createdAt'])]
+ *   }
+ *   ```
+ *
+ * # record 구조 (journal 직렬화 정본)
+ *   `{ table, adapter, columns: { <name>: ColumnDef }, primaryKey?: string[], indexes: IndexDef[], validation? }`
+ *   - ColumnDef: `{ type, length?, precision?, scale?, values?, primary?, notNull?, unique?,
+ *     default?, check?, references?, comment? }` — 설정된 필드만 존재(미설정 키 부재 = 결정적 직렬화).
+ *   - references: `{ model, column, table?, onDelete?, onUpdate?, name? }` — `table` 은 스냅샷 구성
+ *     시점에 모델 스캔 결과로 해석돼 채워진다(스냅샷 자기완결 — 과거 스냅샷 diff 에 모델 재스캔 불요).
+ *
+ * @module core/migration/schema-builder
+ */
+import { MegaConfigError } from '../../errors/config-error.js'
+
+/** FK onDelete/onUpdate 허용 동작 (PostgreSQL 참조 동작 5종). */
+export const FK_ACTIONS = ['cascade', 'set null', 'set default', 'restrict', 'no action']
+
+/**
+ * 컬럼 정의 체인 빌더 — 타입 메서드(`t.<type>()`)가 만들고, 제약 메서드를 체인한다.
+ * 최종 직렬화는 {@link ColumnBuilder#build} 가 수행한다(플레인 객체 반환).
+ */
+export class ColumnBuilder {
+  /** @type {Record<string, any>} 누적 컬럼 정의. */
+  #def
+
+  /** @param {Record<string, any>} def - 타입 메서드가 만든 초기 정의(`{ type, ... }`). */
+  constructor(def) {
+    this.#def = def
+  }
+
+  /** PRIMARY KEY 지정(단일 컬럼). 복합 PK 는 `t.primary([cols])` 사용. @returns {this} */
+  primary() {
+    this.#def.primary = true
+    return this
+  }
+
+  /** NOT NULL 지정. @returns {this} */
+  notNull() {
+    this.#def.notNull = true
+    return this
+  }
+
+  /**
+   * 명시 null 허용(ADR-210) — SQL 에선 nullable 이 기본이라 no-op(선언적 표시)이고, mongo 에선
+   * `bsonType: ['<type>', 'null']` 유니온으로 렌더된다(미선언 시 mongo 는 필드 **생략만** 허용 —
+   * 명시 null 은 121 거부, 실측). `.notNull()` 과 동시 사용 불가.
+   * @returns {this}
+   */
+  nullable() {
+    this.#def.nullable = true
+    return this
+  }
+
+  /**
+   * UNIQUE 제약. 이름 미지정 시 dialect 명명 표준(`uniq_<table>_<col>`)을 따른다.
+   * @param {{ name?: string }} [opts]
+   * @returns {this}
+   */
+  unique(opts) {
+    this.#def.unique = opts?.name !== undefined ? { name: opts.name } : true
+    return this
+  }
+
+  /**
+   * DEFAULT 값. literal(string/number/boolean/null) 또는 `{ raw: 'expr' }`(raw SQL 식).
+   * @param {string | number | boolean | null | { raw: string }} value
+   * @returns {this}
+   */
+  default(value) {
+    this.#def.default = value
+    return this
+  }
+
+  /** `DEFAULT CURRENT_TIMESTAMP` 단축. @returns {this} */
+  defaultNow() {
+    this.#def.default = { raw: 'CURRENT_TIMESTAMP' }
+    return this
+  }
+
+  /**
+   * CHECK 제약. 이름 미지정 시 `chk_<table>_<col>`.
+   * @param {string} expr - CHECK 식(raw SQL).
+   * @param {{ name?: string }} [opts]
+   * @returns {this}
+   */
+  check(expr, opts) {
+    this.#def.check = opts?.name !== undefined ? { expr, name: opts.name } : { expr }
+    return this
+  }
+
+  /**
+   * FK 참조. 대상은 **모델 이름**(file-scan 결과의 클래스 이름)과 그 컬럼 — 실제 테이블명은
+   * 스냅샷 구성 시 해석된다.
+   * @param {string} modelName - 대상 모델 이름(예: 'Organization').
+   * @param {string} columnName - 대상 컬럼 이름(예: 'id').
+   * @param {{ onDelete?: string, onUpdate?: string, name?: string }} [opts]
+   * @returns {this}
+   */
+  references(modelName, columnName, opts = {}) {
+    /** @type {Record<string, any>} */
+    const ref = { model: modelName, column: columnName }
+    if (opts.onDelete !== undefined) ref.onDelete = opts.onDelete
+    if (opts.onUpdate !== undefined) ref.onUpdate = opts.onUpdate
+    if (opts.name !== undefined) ref.name = opts.name
+    this.#def.references = ref
+    return this
+  }
+
+  /** 컬럼 코멘트(`COMMENT ON COLUMN`). @param {string} text @returns {this} */
+  comment(text) {
+    this.#def.comment = text
+    return this
+  }
+
+  /** 직렬화 — 누적 정의의 플레인 사본 반환. @returns {Record<string, any>} */
+  build() {
+    return { ...this.#def }
+  }
+}
+
+/**
+ * 테이블 스키마 빌더 — `schema(t)`/`indexes(t)` 콜백이 받는 `t`.
+ * 타입 메서드는 {@link ColumnBuilder} 를, `index()` 는 IndexDef 를 반환한다.
+ * `primary([cols])` 는 복합 PK 를 빌더 내부 상태에 기록한다.
+ */
+export class SchemaBuilder {
+  /** @type {string[] | undefined} 복합 PRIMARY KEY 컬럼 목록 (`t.primary([...])`). */
+  compositePrimaryKey = undefined
+
+  /** @param {Record<string, any>} def @returns {ColumnBuilder} */
+  #col(def) {
+    return new ColumnBuilder(def)
+  }
+
+  // ── 정수 ──────────────────────────────────────────────────────────────────
+  /** 자동증가 INT (postgres SERIAL). @returns {ColumnBuilder} */
+  serial() {
+    return this.#col({ type: 'serial' })
+  }
+  /** 자동증가 BIGINT (postgres BIGSERIAL). @returns {ColumnBuilder} */
+  bigSerial() {
+    return this.#col({ type: 'bigSerial' })
+  }
+  /** @returns {ColumnBuilder} */
+  integer() {
+    return this.#col({ type: 'integer' })
+  }
+  /** @returns {ColumnBuilder} */
+  bigInteger() {
+    return this.#col({ type: 'bigInteger' })
+  }
+  /** @returns {ColumnBuilder} */
+  smallInteger() {
+    return this.#col({ type: 'smallInteger' })
+  }
+
+  // ── 부동소수/정밀수 ──────────────────────────────────────────────────────
+  /** @returns {ColumnBuilder} */
+  real() {
+    return this.#col({ type: 'real' })
+  }
+  /** @returns {ColumnBuilder} */
+  doublePrecision() {
+    return this.#col({ type: 'doublePrecision' })
+  }
+  /**
+   * 고정 정밀 십진수 (postgres NUMERIC).
+   * @param {number} precision @param {number} scale @returns {ColumnBuilder}
+   */
+  decimal(precision, scale) {
+    return this.#col({ type: 'decimal', precision, scale })
+  }
+
+  // ── 문자열 ────────────────────────────────────────────────────────────────
+  /** @param {number} maxLength @returns {ColumnBuilder} */
+  varchar(maxLength) {
+    return this.#col({ type: 'varchar', length: maxLength })
+  }
+  /** @returns {ColumnBuilder} */
+  text() {
+    return this.#col({ type: 'text' })
+  }
+  /** @param {number} length @returns {ColumnBuilder} */
+  char(length) {
+    return this.#col({ type: 'char', length })
+  }
+
+  // ── 논리/시간/기타 ────────────────────────────────────────────────────────
+  /** @returns {ColumnBuilder} */
+  boolean() {
+    return this.#col({ type: 'boolean' })
+  }
+  /** @returns {ColumnBuilder} */
+  timestamp() {
+    return this.#col({ type: 'timestamp' })
+  }
+  /** @returns {ColumnBuilder} */
+  timestamptz() {
+    return this.#col({ type: 'timestamptz' })
+  }
+  /** @returns {ColumnBuilder} */
+  date() {
+    return this.#col({ type: 'date' })
+  }
+  /** @returns {ColumnBuilder} */
+  time() {
+    return this.#col({ type: 'time' })
+  }
+  /** @returns {ColumnBuilder} */
+  uuid() {
+    return this.#col({ type: 'uuid' })
+  }
+  /** @returns {ColumnBuilder} */
+  json() {
+    return this.#col({ type: 'json' })
+  }
+  /** @returns {ColumnBuilder} */
+  jsonb() {
+    return this.#col({ type: 'jsonb' })
+  }
+  /** @returns {ColumnBuilder} */
+  bytea() {
+    return this.#col({ type: 'bytea' })
+  }
+  /**
+   * MongoDB ObjectId (mongo 전용 — SQL dialect 는 렌더 시점에 거부). `_id` 는 생략해도 자동이며,
+   * 명시 선언은 `_id: t.objectId().primary()` 형태만 허용된다(ADR-209).
+   * @returns {ColumnBuilder}
+   */
+  objectId() {
+    return this.#col({ type: 'objectId' })
+  }
+
+  /**
+   * 중첩 도큐먼트(embedded object — mongo 전용). shape 미지정 시 자유형 object.
+   * 중첩 필드의 제약은 타입·길이·enum·notNull(→required)만 — unique/primary/references/check 는
+   * 최상위 전용이다(mongo dialect 가 렌더 시점에 거부).
+   * @param {Record<string, ColumnBuilder>} [shape] - { 필드명: t.<type>()… }.
+   * @returns {ColumnBuilder}
+   * @throws {MegaConfigError} shape 값이 빌더가 아닐 때.
+   */
+  object(shape) {
+    if (shape === undefined) return this.#col({ type: 'object' })
+    /** @type {Record<string, any>} */
+    const built = {}
+    for (const [key, builder] of Object.entries(shape)) {
+      if (!(builder instanceof ColumnBuilder)) {
+        throw new MegaConfigError('migration.schema_invalid', `t.object: 필드 '${key}' 가 빌더(t.<type>()…)가 아닙니다.`, { details: { field: key } })
+      }
+      built[key] = builder.build()
+    }
+    return this.#col({ type: 'object', shape: built })
+  }
+
+  /**
+   * 배열(mongo 전용). items 미지정 시 자유형 배열.
+   * @param {ColumnBuilder} [items] - 요소 타입(t.<type>()…).
+   * @param {{ uniqueItems?: boolean }} [opts]
+   * @returns {ColumnBuilder}
+   * @throws {MegaConfigError} items 가 빌더가 아닐 때.
+   */
+  array(items, opts = {}) {
+    /** @type {Record<string, any>} */
+    const def = { type: 'array' }
+    if (items !== undefined) {
+      if (!(items instanceof ColumnBuilder)) {
+        throw new MegaConfigError('migration.schema_invalid', `t.array: items 는 빌더(t.<type>()…)여야 합니다.`, { details: {} })
+      }
+      def.items = items.build()
+    }
+    if (opts.uniqueItems === true) def.uniqueItems = true
+    return this.#col(def)
+  }
+
+  /**
+   * 열거형 — postgres 렌더는 `TEXT` + `CHECK (col IN (...))` (native enum 타입 미사용 —
+   * 값 추가/삭제가 제약 교체로 단순해짐).
+   * @param {string[]} values @param {{ name?: string }} [opts] - name: CHECK 제약 이름 override.
+   * @returns {ColumnBuilder}
+   */
+  enum(values, opts) {
+    /** @type {Record<string, any>} */
+    const def = { type: 'enum', values: Array.isArray(values) ? [...values] : values }
+    if (opts?.name !== undefined) def.enumName = opts.name
+    return this.#col(def)
+  }
+
+  /**
+   * 복합 PRIMARY KEY 선언 — schema 콜백 안에서 `t.primary(['a','b'])` 로 호출(반환값 없음,
+   * 컬럼 맵에는 넣지 않는다). 단일 PK 는 컬럼 체인 `.primary()` 사용.
+   * @param {string[]} columns
+   * @returns {void}
+   */
+  primary(columns) {
+    this.compositePrimaryKey = Array.isArray(columns) ? [...columns] : columns
+  }
+
+  /**
+   * 인덱스 정의 — `static indexes = (t) => [t.index(...)]` 에서 사용.
+   * @param {string | string[] | { expression: string }} columnsOrExpr - 컬럼(들) 또는 표현식 인덱스.
+   * @param {{ name?: string, unique?: boolean, where?: string, using?: string }} [opts]
+   * @returns {Record<string, any>} IndexDef.
+   */
+  index(columnsOrExpr, opts = {}) {
+    /** @type {Record<string, any>} */
+    const def = {}
+    if (typeof columnsOrExpr === 'object' && !Array.isArray(columnsOrExpr) && columnsOrExpr !== null) {
+      def.expression = columnsOrExpr.expression
+    } else {
+      def.columns = Array.isArray(columnsOrExpr) ? [...columnsOrExpr] : [columnsOrExpr]
+    }
+    if (opts.name !== undefined) def.name = opts.name
+    if (opts.unique === true) def.unique = true
+    if (opts.where !== undefined) def.where = opts.where
+    if (opts.using !== undefined) def.using = opts.using
+    return def
+  }
+}
+
+/**
+ * 모델 클래스(또는 동형 객체)의 `static schema`/`static indexes` 를 실행해 record 를 만든다.
+ * 모델 식별은 duck-typing — `schema` 함수 + `table`/`adapter` 문자열(클래스 identity 비의존,
+ * 패키지 사본이 달라도 동작). 검증은 {@link module:core/migration/schema-validator} 가 별도 수행.
+ *
+ * @param {{ name?: string, table?: string, adapter?: string, schema?: Function, indexes?: Function }} Model
+ * @returns {{ table: string, adapter: string, columns: Record<string, any>, primaryKey?: string[], indexes: any[], validation?: any }}
+ * @throws {MegaConfigError} `migration.schema_invalid` - table/adapter 누락, schema 반환 형태 오류.
+ */
+export function buildModelRecord(Model) {
+  const modelName = Model?.name || '(anonymous)'
+  if (typeof Model?.table !== 'string' || Model.table.length === 0) {
+    throw new MegaConfigError('migration.schema_invalid', `model '${modelName}': static table 이 비어 있습니다 — schema 모델은 table 필수.`, {
+      details: { model: modelName },
+    })
+  }
+  if (typeof Model?.adapter !== 'string' || Model.adapter.length === 0) {
+    throw new MegaConfigError('migration.schema_invalid', `model '${modelName}': static adapter 가 비어 있습니다 — schema 모델은 adapter 필수.`, {
+      details: { model: modelName },
+    })
+  }
+  const t = new SchemaBuilder()
+  const cols = /** @type {Function} */ (Model.schema)(t)
+  if (cols === null || typeof cols !== 'object' || Array.isArray(cols)) {
+    throw new MegaConfigError(
+      'migration.schema_invalid',
+      `model '${modelName}': static schema 는 { 컬럼명: t.<type>()… } 플레인 객체를 반환해야 합니다.`,
+      { details: { model: modelName, returned: Array.isArray(cols) ? 'array' : typeof cols } },
+    )
+  }
+  /** @type {Record<string, any>} */
+  const columns = {}
+  for (const [name, builder] of Object.entries(cols)) {
+    if (!(builder instanceof ColumnBuilder)) {
+      throw new MegaConfigError(
+        'migration.schema_invalid',
+        `model '${modelName}': 컬럼 '${name}' 이 빌더(t.<type>()…)가 아닙니다 — schema 콜백의 t 메서드로 정의하세요.`,
+        { details: { model: modelName, column: name } },
+      )
+    }
+    columns[name] = builder.build()
+  }
+  /** @type {{ table: string, adapter: string, columns: Record<string, any>, primaryKey?: string[], indexes: any[], validation?: any }} */
+  const record = { table: Model.table, adapter: Model.adapter, columns, indexes: [] }
+  if (t.compositePrimaryKey !== undefined) record.primaryKey = t.compositePrimaryKey
+  // mongo 전용 — collection validator 옵션(static validation = { level, action }). 값 검증은
+  // mongo dialect 렌더가 수행하고, SQL dialect 는 record 의 이 필드를 읽지 않는다(ADR-209).
+  if (/** @type {any} */ (Model).validation !== undefined) record.validation = /** @type {any} */ (Model).validation
+  if (typeof Model.indexes === 'function') {
+    const defs = Model.indexes(t)
+    if (!Array.isArray(defs)) {
+      throw new MegaConfigError('migration.schema_invalid', `model '${modelName}': static indexes 는 [t.index(...)] 배열을 반환해야 합니다.`, {
+        details: { model: modelName, returned: typeof defs },
+      })
+    }
+    record.indexes = defs
+  }
+  return record
+}