mega-framework 0.1.0

package/src/core/mega-cluster.js

@@ -0,0 +1,232 @@
+// @ts-check
+import cluster from 'node:cluster'
+import os from 'node:os'
+
+/**
+ * MegaCluster — Node cluster 모듈 래퍼.
+ *
+ * 사용:
+ *   const cluster = new MegaCluster({ instances: 'max' })
+ *   await cluster.start(async () => {
+ *     // 워커 프로세스 안에서 실행되는 코드 — MegaApp/Server 부팅
+ *     await server.listen({ port: 3000 })
+ *   })
+ *
+ * 마스터 프로세스: 워커 N개 fork + IPC + SIGTERM/SIGINT → 워커들에 'shutdown'.
+ * 워커 프로세스: 사용자 함수 실행. 마스터로부터 'shutdown' 받으면 graceful close.
+ *
+ * ADR-030 (cluster 직접). graceful shutdown 시퀀스 강화는 MegaShutdown 영역.
+ */
+
+const SHUTDOWN_MSG = 'mega-shutdown'
+
+/**
+ * 코어가 워커에 부착하는 비표준 프로퍼티(`_megaBirthAt`, 수명 측정용)를 포함한 Worker.
+ * @typedef {import('node:cluster').Worker & { _megaBirthAt?: number }} MegaWorker
+ */
+// NOTE: 워커 ready 협응(부팅 완료 신호)은 현재 미사용. 필요해지면 후속 Phase 에서
+//       마스터 수신부까지 양방향(send + receive)으로 한 번에 배선한다.
+
+export class MegaCluster {
+  /**
+   * @param {Object} [opts]
+   * @param {number | 'max'} [opts.instances] - 워커 수. 'max' 면 CPU 코어 수.
+   * @param {boolean} [opts.respawn=true] - 워커 crash 시 자동 재시작
+   * @param {number} [opts.gracePeriodMs=30000] - SIGTERM 후 강제 kill 까지 대기
+   * @param {import('node:cluster').Cluster} [opts._cluster] - 테스트용 cluster 주입(기본 node:cluster). per ADR-165
+   * @param {NodeJS.Process} [opts._proc] - 테스트용 process 주입(기본 전역 process). per ADR-165
+   */
+  constructor(opts = {}) {
+    this._instances = resolveInstances(opts.instances)
+    this._respawn = opts.respawn !== false
+    this._gracePeriodMs = opts.gracePeriodMs ?? 30_000
+    this._shuttingDown = false
+    // fork/IPC/시그널 경로는 자식 프로세스 안에서만 실행돼 부모 v8 커버리지로 측정 불가다.
+    // cluster/process 를 주입 seam 으로 분리해 fake 로 in-process 단위 검증한다. per ADR-165
+    this._cluster = opts._cluster ?? cluster
+    this._proc = opts._proc ?? process
+    /** @type {Set<MegaWorker>} */
+    this._workers = new Set()
+    /** @type {(() => Promise<void>) | null} */
+    this._workerFn = null
+
+    // M1 — respawn backoff (crash-loop 보호)
+    this._respawnTooFast = 0          // 빠른 연속 crash 카운터
+    this._maxRapidRespawn = 5         // 5번 연속 너무 빨리 crash 하면 중단
+    this._minRespawnIntervalMs = 1000 // 1초 이내 crash 는 "너무 빠름"
+  }
+
+  /**
+   * 마스터 / 워커 둘 다 호출. 마스터면 fork, 워커면 사용자 함수 실행.
+   * @param {() => Promise<void>} workerFn - 워커 프로세스에서 실행할 부팅 함수.
+   * @returns {Promise<void>}
+   */
+  async start(workerFn) {
+    if (typeof workerFn !== 'function') {
+      throw new Error('MegaCluster.start: workerFn must be a function')
+    }
+    if (this._cluster.isPrimary) {
+      return this._startPrimary(workerFn)
+    }
+    return this._startWorker(workerFn)
+  }
+
+  /** boolean 네이밍 (ADR-036). */
+  isShuttingDown() {
+    return this._shuttingDown
+  }
+
+  /** boolean — primary 프로세스인지. */
+  isPrimary() {
+    return this._cluster.isPrimary
+  }
+
+  /** boolean — worker 프로세스인지. */
+  isWorker() {
+    return !this._cluster.isPrimary
+  }
+
+  /**
+   * @private 마스터 프로세스 부팅 시퀀스.
+   * @param {() => Promise<void>} workerFn
+   */
+  async _startPrimary(workerFn) {
+    this._workerFn = workerFn
+    // workerFn 은 마스터에서 사용 안 함 (정보 전달용 placeholder)
+    for (let i = 0; i < this._instances; i++) {
+      this._forkWorker()
+    }
+
+    // SIGTERM/SIGINT → graceful shutdown 협응
+    const onSignal = (/** @type {string} */ sig) => {
+      if (this._shuttingDown) return
+      this._shuttingDown = true
+      console.log(`[mega-cluster] received ${sig}, broadcasting shutdown to ${this._workers.size} workers (grace ${this._gracePeriodMs}ms)`)
+      this._broadcastShutdown()
+      // grace 초과 시 강제 kill
+      setTimeout(() => {
+        for (const w of this._workers) {
+          try { w.kill('SIGKILL') } catch (err) { console.warn('[mega-cluster] SIGKILL failed:', err.message) }
+        }
+        this._proc.exit(1)
+      }, this._gracePeriodMs).unref()
+    }
+    this._proc.on('SIGTERM', () => onSignal('SIGTERM'))
+    this._proc.on('SIGINT', () => onSignal('SIGINT'))
+  }
+
+  /** @private 워커 fork + 라이프사이클 wiring. */
+  _forkWorker() {
+    const worker = /** @type {MegaWorker} */ (this._cluster.fork())
+    worker._megaBirthAt = Date.now()   // 수명 측정용 (M1 respawn backoff)
+    this._workers.add(worker)
+    worker.on('exit', (code, signal) => {
+      this._workers.delete(worker)
+      if (this._shuttingDown) {
+        if (this._workers.size === 0) {
+          console.log('[mega-cluster] all workers exited, primary exiting 0')
+          this._proc.exit(0)
+        }
+        return
+      }
+      if (this._respawn) {
+        // M1 — respawn backoff: 너무 빨리 연속 crash 하면 crash-loop 으로 보고 respawn 중단.
+        const now = Date.now()
+        const lastBirth = worker._megaBirthAt ?? now
+        const lifetimeMs = now - lastBirth
+        if (lifetimeMs < this._minRespawnIntervalMs) {
+          this._respawnTooFast += 1
+          if (this._respawnTooFast >= this._maxRapidRespawn) {
+            // H-1 — crash-loop 포기 시 그냥 return 하면 이벤트루프가 비어 exit 0(성공)으로
+            //   보인다 → systemd/k8s 가 "정상 종료" 로 판단해 재시작 안 함.
+            //   명시적 exit 1 로 "비정상 종료" 를 외부 supervisor 에 알려 재시작을 유도한다.
+            console.error(
+              `[mega-cluster] rapid crash-loop detected (${this._respawnTooFast} restarts within ${this._minRespawnIntervalMs}ms), giving up — exiting 1. Last exit: code=${code}, signal=${signal}.`,
+            )
+            this._proc.exit(1)
+            return   // 실 process.exit 은 즉시 종료하나, 주입된 fake 는 계속 실행되므로 명시적 중단
+          }
+        } else {
+          this._respawnTooFast = 0   // 정상 lifetime 이면 카운터 reset
+        }
+        console.warn(
+          `[mega-cluster] worker ${worker.process.pid} died (code=${code}, signal=${signal}, lifetime=${lifetimeMs}ms), respawning (rapid-crash-count=${this._respawnTooFast}/${this._maxRapidRespawn})`,
+        )
+        this._forkWorker()
+      } else {
+        console.warn(`[mega-cluster] worker ${worker.process.pid} died (code=${code}, signal=${signal}), respawn disabled`)
+      }
+    })
+  }
+
+  /** @private 모든 워커에 shutdown 메시지 송신. */
+  _broadcastShutdown() {
+    for (const w of this._workers) {
+      try {
+        w.send({ type: SHUTDOWN_MSG })
+      } catch (err) {
+        // 워커가 이미 disconnected — 무시 + 로그 (silent 금지)
+        console.warn(`[mega-cluster] failed to send shutdown to worker ${w.process.pid}:`, err.message)
+      }
+    }
+  }
+
+  /**
+   * @private 워커 프로세스 시작 — 사용자 함수 실행 + 마스터 메시지 수신.
+   * @param {() => Promise<void>} workerFn
+   */
+  async _startWorker(workerFn) {
+    // NOTE: 워커 graceful 종료는 사용자 SIGTERM 핸들러(또는 MegaShutdown.setupSignals)에 위임.
+    // 무핸들러 감지 + warn 로그 + respawn backoff(crash-loop 보호).
+    // 워커 ready 협응 양방향 배선은 후속 Phase (필요 시) 에서 박을 예정.
+    // 마스터로부터 shutdown 메시지 수신 → 워커 graceful close
+    this._proc.on('message', (msg) => {
+      // IPC 메시지는 Serializable 타입 — shutdown 협응 형태로 좁혀 읽는다.
+      const data = /** @type {{ type?: string }} */ (msg)
+      if (data?.type === SHUTDOWN_MSG && !this._shuttingDown) {
+        this._shuttingDown = true
+        // M2 — process.emit 의 반환값으로 SIGTERM 핸들러 등록 여부 감지.
+        //   핸들러가 있었으면 true, 없으면 false → 무핸들러 경고.
+        const hadListener = this._proc.emit('SIGTERM')
+        if (!hadListener) {
+          console.warn(
+            `[mega-cluster] worker ${this._proc.pid} has no SIGTERM handler registered. Will be force-killed by master after grace period. ` +
+              `Register a SIGTERM handler (or use MegaShutdown.setupSignals) to enable graceful shutdown.`,
+          )
+        }
+      }
+    })
+
+    // 사용자 함수 실행 (MegaApp/Server 부팅)
+    try {
+      await workerFn()
+    } catch (err) {
+      console.error(`[mega-cluster] worker ${this._proc.pid} workerFn failed:`, err)
+      this._proc.exit(1)
+    }
+  }
+
+  /** 외부에서 강제 종료 트리거 (테스트용). */
+  async shutdown() {
+    if (this._shuttingDown) return
+    this._shuttingDown = true
+    if (this._cluster.isPrimary) {
+      this._broadcastShutdown()
+    }
+  }
+}
+
+/**
+ * @private
+ * @param {number | 'max' | undefined} input
+ * @returns {number}
+ */
+function resolveInstances(input) {
+  if (input === 'max' || input === undefined) {
+    return Math.max(1, os.availableParallelism?.() ?? os.cpus().length)
+  }
+  if (typeof input === 'number' && Number.isFinite(input) && input >= 1) {
+    return Math.floor(input)
+  }
+  throw new Error(`MegaCluster: instances must be a positive number or 'max'. Got: ${input}`)
+}

package/src/core/mega-server.js

@@ -0,0 +1,176 @@
+// @ts-check
+import { createServer as createHttpServer } from 'node:http'
+import { MegaConfigError } from '../errors/config-error.js'
+
+/**
+ * MegaServer — 여러 MegaApp 을 하나의 HTTP 서버에서 호스트네임 기반으로 라우팅.
+ *
+ * 단일 HTTP 서버 + Host 헤더 분기. ADR-003 (도메인 기반 멀티앱).
+ * WS hub·cluster master 의 토대.
+ *
+ * 동작:
+ *   1. mount(app) 으로 MegaApp 등록 (hosts 배열의 각 host 가 등록됨)
+ *   2. listen() → Node http.Server 생성, 매 요청마다 hostname 확인 → 해당 MegaApp 의
+ *      Fastify routing 함수에 위임
+ *
+ * vhost 매칭은 ADR-003 + ADR-067 (호스트 충돌 부팅 검증) 이미 처리됨.
+ */
+export class MegaServer {
+  /**
+   * @param {{ port?: number, host?: string }} [opts] - listen 기본값 (listen() 인자로 override 가능)
+   */
+  constructor(opts = {}) {
+    /** @type {Map<string, import('./mega-app.js').MegaApp>} */
+    this._hostMap = new Map()
+    /** @type {import('./mega-app.js').MegaApp[]} */
+    this._apps = []
+    /** @type {import('node:http').Server | null} */
+    this._httpServer = null
+    this._opts = opts
+  }
+
+  /**
+   * MegaApp 마운트. 같은 host 가 두 앱에 매핑되면 throw (ADR-067 정합).
+   *
+   * WHY 2-pass: 충돌 검사를 **전체 host 에 대해 먼저 끝낸 뒤** `#hostMap` 을 변경한다. 한 번에 섞으면
+   * `hosts=['y','x']` 에서 'y' 를 등록한 직후 'x' 충돌로 throw 했을 때, 'y'→app 만 남고 app 은
+   * `_apps` 에 미등록되는 **부분 상태**가 생긴다(`#hostMap`↔`_apps` 불변식 깨짐 → 'y' 요청이 ready 안
+   * 된 Fastify 로 라우팅). 사전검증으로 mutate 전에 전부 막아 throw 시 상태를 원자적으로 보존한다.
+   *
+   * @param {import('./mega-app.js').MegaApp} app
+   */
+  mount(app) {
+    if (this._apps.includes(app)) return
+    // ① 전체 host 충돌 사전검증 — 어떤 host 든 충돌하면 #hostMap 을 손대기 전에 throw.
+    for (const host of app.hosts) {
+      const existing = this._hostMap.get(host)
+      if (existing && existing !== app) {
+        throw new MegaConfigError(
+          'config.host_collision',
+          `Host '${host}' is claimed by both '${existing.name}' and '${app.name}'.`,
+        )
+      }
+    }
+    // ② 충돌 없음 확정 후에만 등록 — throw 가능 경로가 끝나 상태가 원자적으로 일관된다.
+    for (const host of app.hosts) {
+      this._hostMap.set(host, app)
+    }
+    this._apps.push(app)
+  }
+
+  /**
+   * @returns {boolean}
+   */
+  isListening() {
+    return this._httpServer?.listening === true
+  }
+
+  /**
+   * 모든 마운트된 MegaApp 의 Fastify 인스턴스 ready + HTTP 서버 listen.
+   * @param {{ port?: number, host?: string }} [opts]
+   */
+  async listen(opts = {}) {
+    if (this._apps.length === 0) {
+      throw new Error('MegaServer.listen: no MegaApps mounted')
+    }
+
+    // 모든 Fastify 인스턴스 ready (라우트 등록 완료 보장)
+    for (const app of this._apps) {
+      await app.fastify.ready()
+    }
+
+    this._httpServer = createHttpServer((req, res) => {
+      const hostHeader = String(req.headers.host || '')
+      const hostname = hostHeader.split(':')[0].toLowerCase()
+      const app = this._hostMap.get(hostname)
+      if (!app) {
+        res.statusCode = 404
+        res.setHeader('content-type', 'application/json')
+        res.end(
+          JSON.stringify({
+            ok: false,
+            error: {
+              code: 'host.not_mounted',
+              message: `No app mounted for host '${hostname}'. Known hosts: ${[...this._hostMap.keys()].join(', ')}`,
+            },
+          }),
+        )
+        return
+      }
+      // Fastify v5: `fastify.routing` 은 요청 디스패처 함수(preRouting) 자체다.
+      // 검증: node_modules/fastify/fastify.js — `routing: httpHandler`, 내부에서도
+      // `httpHandler(req, res)` 로 직접 호출. 따라서 routing(req, res) 로 호출한다.
+      app.fastify.routing(req, res)
+    })
+
+    // WS HTTP Upgrade 핸들오프 — 호스트 분기 후 해당 MegaApp 에 위임.
+    // Fastify 는 (websocket 플러그인 없으면) 'upgrade' 를 듣지 않으므로 여기서 직접 배선한다.
+    this._httpServer.on('upgrade', (req, socket, head) => {
+      const hostHeader = String(req.headers.host || '')
+      const hostname = hostHeader.split(':')[0].toLowerCase()
+      const app = this._hostMap.get(hostname)
+      if (!app) {
+        // 매핑 안 된 host 의 upgrade 는 거부 (소켓 파괴). HTTP 404 와 동일 정책.
+        // L4: destroy 전 error 가드. listener 없는 raw 소켓이 ECONNRESET 등으로 uncaught
+        // exception → 프로세스 크래시 하는 것을 막는다 (H1 과 동일 패턴). MegaServer 는
+        // 아직 pino 미통합이라 비치명적 소켓 에러는 console.warn 으로 명시 로그.
+        socket.on('error', (err) => {
+          console.warn('[MegaServer] raw socket error on unmapped-host upgrade:', err?.message ?? err)
+        })
+        socket.destroy()
+        return
+      }
+      app.handleUpgrade(req, socket, head)
+    })
+
+    const port = opts.port ?? this._opts.port ?? 3000
+    const host = opts.host ?? this._opts.host ?? '0.0.0.0'
+    const httpServer = this._httpServer
+    await new Promise((resolve, reject) => {
+      // WHY 이벤트 배선: node http.Server.listen 의 콜백은 err 인자를 받지 않는다
+      // (() => void). 바인딩 실패(EADDRINUSE 등)는 'error' 이벤트로만 발생하므로,
+      // 'error' 리스너가 없으면 unhandled error 로 프로세스가 크래시/행 한다.
+      // 따라서 'listening'/'error' 를 once() 로 배선하고, 어느 한쪽이 발생하면
+      // 다른 쪽 리스너를 제거해 누수를 막는다.
+      const onError = (/** @type {Error} */ err) => {
+        httpServer.removeListener('listening', onListening)
+        reject(err)
+      }
+      const onListening = () => {
+        httpServer.removeListener('error', onError)
+        resolve(undefined)
+      }
+      httpServer.once('error', onError)
+      httpServer.once('listening', onListening)
+      httpServer.listen({ port, host })
+    })
+  }
+
+  /**
+   * 모든 마운트된 MegaApp close (역순 — 마지막 mount 부터) → HTTP 서버 종료.
+   * graceful 처리는 MegaCluster + MegaShutdown 에서 강화.
+   *
+   * # 종료 순서 (M1)
+   *   각 app 의 WS 클라이언트를 **먼저** close(1001) 한 뒤 httpServer 를 닫는다. Node 의
+   *   `http.Server.close` 콜백은 업그레이드된 WS 소켓을 포함한 모든 연결이 닫혀야 발생하므로,
+   *   httpServer 를 먼저 await 하면 활성 WS 연결이 있을 때 영원히 끝나지 않는다(hang). single
+   *   모드(MegaApp.close)와 동일하게 WS → HTTP 순으로 닫아 일관성을 맞춘다.
+   */
+  async close() {
+    // ① 각 app close — 내부에서 활성 WS 클라이언트 close(1001) + Fastify close (역순 LIFO).
+    for (const app of [...this._apps].reverse()) {
+      await app.close()
+    }
+    // ② 그 다음 HTTP 서버 종료 — WS 소켓이 모두 닫혔으므로 콜백이 즉시 발생한다.
+    if (this._httpServer && this._httpServer.listening) {
+      await new Promise((resolve, reject) => {
+        this._httpServer.close((err) => (err ? reject(err) : resolve(undefined)))
+      })
+    }
+  }
+
+  /** 등록된 호스트 목록 (디버그·테스트용). */
+  get hosts() {
+    return [...this._hostMap.keys()]
+  }
+}

package/src/core/mega-service.js

@@ -0,0 +1,41 @@
+// @ts-check
+
+/**
+ * MegaService — 도메인 비즈니스 로직 베이스.
+ *
+ * 라우트 핸들러(인라인 함수 또는 정적 메서드 ref)는 직접 모델을 호출하지 않고 항상 서비스를 거쳐야
+ * 한다(ADR-022). ESLint custom rule `mega/no-direct-model-import`(`mega-framework/eslint-plugin`,
+ * eslint.config.js 에 배선)가 lint 시점에 routes/controllers → models 직접 import 를 차단한다.
+ *
+ * 서비스는 요청 컨텍스트 ctx 와 함께 인스턴스화되며, this.ctx / this.app / this.log /
+ * this.services 로 접근. 다른 서비스 호출은 this.services.<name> 으로 합성.
+ *
+ * 자동 DI(ADR-148): `apps/<app>/services/<name>-service.js` 를 부팅 시 로드해 두면 핸들러·다른 서비스가
+ * `ctx.services.<name>` / `this.services.<name>` 로 요청별 인스턴스를 받는다(첫 접근 시 lazy 생성·요청 내 캐시).
+ */
+export class MegaService {
+  /**
+   * @param {Record<string, any>} ctx - 요청 컨텍스트 (req·log·services·db·cache·bus 등)
+   * @param {Object} [opts]
+   * @param {Object} [opts.app] - MegaApp 인스턴스 (옵션)
+   */
+  constructor(ctx, opts = {}) {
+    if (ctx == null || typeof ctx !== 'object') {
+      throw new Error('MegaService: ctx is required')
+    }
+    /** @type {Record<string, any>} */
+    this.ctx = ctx
+    /** @type {Object | null} */
+    this.app = opts.app ?? null
+  }
+
+  /** 요청·인스턴스 로거. ctx.log 가 없으면 console fallback. */
+  get log() {
+    return this.ctx?.log ?? console
+  }
+
+  /** 다른 서비스 호출용. ctx.services 가 없으면 빈 객체. */
+  get services() {
+    return this.ctx?.services ?? {}
+  }
+}

package/src/core/migration-runner.js

@@ -0,0 +1,196 @@
+// @ts-check
+/**
+ * 마이그레이션 러너 (ADR-149) — `apps/<app>/migrations/<ts>-<name>.js` 의 up/down 을
+ * 대상 DB 에 적용·롤백하고, 적용 이력을 대상 DB 의 `mega_migrations` 테이블로 추적한다.
+ *
+ * 러너는 **어댑터에 비의존적**이다 — 호출자(`runMigrateHost`)가 연결된 DB 어댑터(`{ query, withTransaction }`)를
+ * `db` 로 넘긴다. 마이그레이션 파일의 `up(db)/down(db)` 는 이 어댑터를 받아 SQL 을 실행한다. 어댑터가
+ * `withTransaction` 을 지원하면 각 마이그레이션을 트랜잭션으로 감싸 부분 실패를 롤백한다(postgres DDL-in-tx).
+ *
+ * 부기 SQL(테이블 생성·SELECT·INSERT·DELETE)은 표준 SQL 만 쓰고, 값(마이그레이션 name·applied_at)은
+ * **framework-controlled 라 따옴표가 불가능**(name 은 {@link MIGRATION_FILE_RE} 검증, applied_at 은 ISO)하므로
+ * placeholder(`$1` vs `?`) dialect 분기 없이 인라인해도 인젝션-안전하다.
+ *
+ * @module core/migration-runner
+ */
+import { readdirSync } from 'node:fs'
+import { join, resolve as pathResolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { MegaConfigError } from '../errors/config-error.js'
+
+/** 적용 이력 테이블 이름. */
+export const MIGRATIONS_TABLE = 'mega_migrations'
+
+/** 마이그레이션 파일명 형식 — `<YYYYMMDDHHmmss>-<kebab>.js`. generator(ADR-012)가 이 prefix 를 생성. */
+export const MIGRATION_FILE_RE = /^\d{14}-[a-z0-9][a-z0-9-]*\.js$/
+
+/**
+ * @typedef {{ query: (sql: string, params?: any[]) => Promise<any>, withTransaction?: (fn: () => Promise<any>) => Promise<any> }} MigrationDb
+ */
+
+/**
+ * @typedef {{ name: string, file: string, app: string, absPath: string }} MigrationFile
+ */
+
+/**
+ * 모든 앱의 `migrations/` 폴더를 스캔해 마이그레이션 파일 목록을 **타임스탬프(파일명 prefix) 오름차순**으로
+ * 반환한다. 형식(`MIGRATION_FILE_RE`)에 맞지 않는 파일·`*.test.js` 는 건너뛴다. 폴더 부재는 정상.
+ *
+ * @param {{ projectRoot: string, appNames: string[] }} opts
+ * @returns {MigrationFile[]}
+ */
+export function collectMigrationFiles({ projectRoot, appNames }) {
+  /** @type {MigrationFile[]} */
+  const out = []
+  for (const app of appNames) {
+    const dir = join(projectRoot, 'apps', app, 'migrations')
+    let files
+    try {
+      files = readdirSync(dir)
+    } catch (err) {
+      if (/** @type {any} */ (err).code === 'ENOENT') continue
+      throw err
+    }
+    for (const file of files) {
+      if (!MIGRATION_FILE_RE.test(file)) continue // ts-prefix 형식만(.test.js 등 자동 제외)
+      out.push({ name: file.replace(/\.js$/, ''), file, app, absPath: pathResolve(join(dir, file)) })
+    }
+  }
+  // 전역 타임스탬프 정렬 — name = `<ts>-<kebab>` 라 사전식 = 시간순.
+  out.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+  return out
+}
+
+/**
+ * 마이그레이션 모듈 로드 + up/down 검증.
+ * @param {string} absPath
+ * @returns {Promise<{ up: Function, down: Function }>}
+ * @throws {MegaConfigError} import 실패 / up·down 누락.
+ */
+export async function loadMigration(absPath) {
+  let mod
+  try {
+    mod = await import(pathToFileURL(absPath).href)
+  } catch (err) {
+    throw new MegaConfigError('migration.file_load_failed', `Failed to load migration '${absPath}': ${/** @type {any} */ (err).message}`, { cause: err })
+  }
+  if (typeof mod.up !== 'function' || typeof mod.down !== 'function') {
+    throw new MegaConfigError('migration.invalid', `Migration '${absPath}' must export async function up(db) and down(db).`)
+  }
+  return { up: mod.up, down: mod.down }
+}
+
+/**
+ * 이력 테이블 보장(idempotent). 표준 SQL — postgres/maria/sqlite 공통.
+ * @param {MigrationDb} db
+ * @returns {Promise<void>}
+ */
+async function ensureTable(db) {
+  await db.query(`CREATE TABLE IF NOT EXISTS ${MIGRATIONS_TABLE} (name VARCHAR(255) PRIMARY KEY, applied_at VARCHAR(64) NOT NULL)`)
+}
+
+/**
+ * 적용된 마이그레이션 name 집합.
+ * @param {MigrationDb} db
+ * @returns {Promise<Set<string>>}
+ */
+async function appliedSet(db) {
+  const res = await db.query(`SELECT name FROM ${MIGRATIONS_TABLE}`)
+  const rows = res?.rows ?? (Array.isArray(res) ? res : [])
+  return new Set(rows.map((/** @type {any} */ r) => r.name))
+}
+
+/**
+ * 적용 기록 INSERT. name(검증된 [\d a-z -])·iso(ISO)는 따옴표 불가라 인라인 안전(placeholder dialect 회피).
+ * @param {MigrationDb} db @param {string} name @param {string} appliedAtIso
+ */
+async function recordApplied(db, name, appliedAtIso) {
+  await db.query(`INSERT INTO ${MIGRATIONS_TABLE} (name, applied_at) VALUES ('${name}', '${appliedAtIso}')`)
+}
+
+/**
+ * 적용 기록 DELETE(롤백 시).
+ * @param {MigrationDb} db @param {string} name
+ */
+async function removeApplied(db, name) {
+  await db.query(`DELETE FROM ${MIGRATIONS_TABLE} WHERE name = '${name}'`)
+}
+
+/**
+ * 어댑터가 트랜잭션을 지원하면 fn 을 트랜잭션으로 감싸 실행한다. postgres 는 AsyncLocalStorage 로 tx
+ * 컨텍스트를 추적하므로 fn 안의 `db.query` 가 같은 트랜잭션 클라이언트로 라우팅된다(ADR-106).
+ * @param {MigrationDb} db @param {() => Promise<void>} fn
+ */
+async function runInTransaction(db, fn) {
+  if (typeof db.withTransaction === 'function') {
+    await db.withTransaction(async () => {
+      await fn()
+    })
+  } else {
+    await fn()
+  }
+}
+
+/**
+ * 미적용(pending) 마이그레이션을 타임스탬프 순으로 모두 적용한다. 각 마이그레이션의 up + 이력 기록을
+ * 한 트랜잭션으로 묶어 원자적으로 처리한다.
+ *
+ * @param {{ db: MigrationDb, projectRoot: string, appNames: string[], now?: () => string, log?: { info?: Function } }} opts
+ *   - now: 적용 시각 ISO 문자열 공급자(테스트 주입용, 기본 `new Date().toISOString()`).
+ * @returns {Promise<{ applied: string[] }>}
+ */
+export async function migrateUp({ db, projectRoot, appNames, now = () => new Date().toISOString(), log }) {
+  await ensureTable(db)
+  const applied = await appliedSet(db)
+  const pending = collectMigrationFiles({ projectRoot, appNames }).filter((m) => !applied.has(m.name))
+  /** @type {string[]} */
+  const done = []
+  for (const m of pending) {
+    const { up } = await loadMigration(m.absPath)
+    const appliedAt = now()
+    await runInTransaction(db, async () => {
+      await up(db)
+      await recordApplied(db, m.name, appliedAt)
+    })
+    log?.info?.({ migration: m.name }, 'migrate.up applied')
+    done.push(m.name)
+  }
+  return { applied: done }
+}
+
+/**
+ * 가장 최근 적용된 마이그레이션 1개를 롤백한다(down + 이력 삭제, 한 트랜잭션). 적용분이 없으면 no-op.
+ * 적용 이력에 있으나 파일이 사라진 항목은 down 을 실행할 수 없어 건너뛴다.
+ *
+ * @param {{ db: MigrationDb, projectRoot: string, appNames: string[], log?: { info?: Function } }} opts
+ * @returns {Promise<{ rolledBack: string | null }>}
+ */
+export async function migrateDown({ db, projectRoot, appNames, log }) {
+  await ensureTable(db)
+  const applied = await appliedSet(db)
+  const appliedFiles = collectMigrationFiles({ projectRoot, appNames }).filter((m) => applied.has(m.name))
+  const last = appliedFiles[appliedFiles.length - 1]
+  if (!last) return { rolledBack: null }
+  const { down } = await loadMigration(last.absPath)
+  await runInTransaction(db, async () => {
+    await down(db)
+    await removeApplied(db, last.name)
+  })
+  log?.info?.({ migration: last.name }, 'migrate.down rolled back')
+  return { rolledBack: last.name }
+}
+
+/**
+ * 적용/미적용 마이그레이션 목록(타임스탬프 순).
+ * @param {{ db: MigrationDb, projectRoot: string, appNames: string[] }} opts
+ * @returns {Promise<{ applied: string[], pending: string[] }>}
+ */
+export async function migrateStatus({ db, projectRoot, appNames }) {
+  await ensureTable(db)
+  const applied = await appliedSet(db)
+  const all = collectMigrationFiles({ projectRoot, appNames })
+  return {
+    applied: all.filter((m) => applied.has(m.name)).map((m) => m.name),
+    pending: all.filter((m) => !applied.has(m.name)).map((m) => m.name),
+  }
+}