mega-framework 0.1.6 → 0.1.8

package/types/core/mega-server.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Host 헤더에서 hostname 만 추출한다 (소문자 정규화). IPv6 리터럴(`[::1]:3000`)은 hostname 자체가
+ * 콜론을 포함하므로 단순 `split(':')` 으로는 `'['` 가 나와 vhost 매칭이 전부 깨진다 — 대괄호 형식이면
+ * 괄호 안(`::1`)을, 아니면 첫 콜론 앞(포트 제거)을 취한다.
+ * @param {unknown} hostHeader - `req.headers.host` 원본.
+ * @returns {string}
+ */
+export function hostnameOf(hostHeader: unknown): string;
+/**
+ * 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, logger?: { debug?: Function, warn?: Function } }} [opts] -
+     *   listen 기본값 (listen() 인자로 override 가능). `logger` 는 pino 호환 로거(선택) — 미매핑 host
+     *   404·upgrade 소켓 에러 같은 비치명 이벤트를 구조적으로 남긴다(미주입 시 console 폴백).
+     */
+    constructor(opts?: {
+        port?: number;
+        host?: string;
+        logger?: {
+            debug?: Function;
+            warn?: Function;
+        };
+    });
+    /** @type {Map<string, import('./mega-app.js').MegaApp>} */
+    _hostMap: Map<string, import("./mega-app.js").MegaApp>;
+    /** @type {import('./mega-app.js').MegaApp[]} */
+    _apps: import("./mega-app.js").MegaApp[];
+    /** @type {import('node:http').Server | null} */
+    _httpServer: import("node:http").Server | null;
+    /** @type {{ debug?: Function, warn?: Function } | null} */
+    _log: {
+        debug?: Function;
+        warn?: Function;
+    } | null;
+    _opts: {
+        port?: number;
+        host?: string;
+        logger?: {
+            debug?: Function;
+            warn?: Function;
+        };
+    };
+    /**
+     * 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: import("./mega-app.js").MegaApp): void;
+    /**
+     * @returns {boolean}
+     */
+    isListening(): boolean;
+    /**
+     * 모든 마운트된 MegaApp 의 Fastify 인스턴스 ready + HTTP 서버 listen.
+     * @param {{ port?: number, host?: string }} [opts]
+     */
+    listen(opts?: {
+        port?: number;
+        host?: string;
+    }): Promise<void>;
+    /**
+     * 모든 마운트된 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 순으로 닫아 일관성을 맞춘다.
+     */
+    close(): Promise<void>;
+    /** 등록된 호스트 목록 (디버그·테스트용). */
+    get hosts(): string[];
+}

package/types/core/mega-service.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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: Record<string, any>, opts?: {
+        app?: Object;
+    });
+    /** @type {Record<string, any>} */
+    ctx: Record<string, any>;
+    /** @type {Object | null} */
+    app: Object | null;
+    /** 요청·인스턴스 로거. ctx.log 가 없으면 console fallback. */
+    get log(): any;
+    /** 다른 서비스 호출용. ctx.services 가 없으면 빈 객체. */
+    get services(): any;
+}

package/types/core/migration/dialect-registry.d.ts

@@ -0,0 +1,22 @@
+/**
+ * dialect 의 contract 충족 검증 — 미구현 멤버 목록을 모아 한 번에 보고.
+ * @param {string} driver @param {Record<string, any>} dialect
+ * @throws {MegaConfigError} `migration.dialect_contract`
+ */
+export function assertDialectContract(driver: string, dialect: Record<string, any>): void;
+/**
+ * driver 의 dialect 조회(+contract 검증).
+ * @param {string} driver - services.databases.<key>.driver 값.
+ * @returns {Record<string, any>}
+ * @throws {MegaConfigError} `migration.dialect_unsupported` | `migration.dialect_contract`
+ */
+export function getDialect(driver: string): Record<string, any>;
+/**
+ * dialect 가 DML facet 을 충족하는지 — **누락 멤버 배열**(빈 배열=충족)을 반환한다(throw 아님 — 호출부
+ * model-crud 가 `model.*` 에러로 표면화). mongo 등 DML facet 미구현 dialect 는 비어있지 않은 배열을 돌려준다.
+ * @param {Record<string, any>} dialect
+ * @returns {string[]}
+ */
+export function dmlFacetMissing(dialect: Record<string, any>): string[];
+/** 자동 생성을 지원하는 driver 목록. */
+export const SUPPORTED_DRIVERS: string[];

package/types/core/migration/dialects/maria.d.ts

@@ -0,0 +1,99 @@
+/**
+ * SQL 식별자 인용 — 백틱. 한도 초과는 fail-fast(절단 충돌 방지 — postgres 와 동일 정책).
+ * @param {string} name @returns {string}
+ * @throws {MegaConfigError} `migration.identifier_too_long`
+ */
+export function quoteIdent(name: string): string;
+/**
+ * 값 literal 인용 — MariaDB 는 기본 sql_mode 에서 백슬래시가 escape 문자라 `\` 도 이스케이프한다
+ * (postgres 의 standard_conforming_strings 와 다른 지점).
+ * @param {unknown} value @returns {string}
+ */
+export function quoteLiteral(value: unknown): string;
+/**
+ * 컬럼 타입 → MariaDB SQL 타입.
+ * @param {Record<string, any>} def @returns {string}
+ */
+export function typeSql(def: Record<string, any>): string;
+/** @param {string} table @param {string[]} cols @param {boolean} [unique] @returns {string} */
+export function indexName(table: string, cols: string[], unique?: boolean): string;
+/** @param {string} table @param {Record<string, any>} ix @returns {string} */
+export function resolveIndexName(table: string, ix: Record<string, any>): string;
+/** @param {string} table @param {string} col @returns {string} */
+export function uniqueName(table: string, col: string): string;
+/** @param {string} table @param {string} col @param {string} refTable @returns {string} */
+export function fkName(table: string, col: string, refTable: string): string;
+/** @param {string} table @param {string} col @returns {string} */
+export function checkName(table: string, col: string): string;
+/** MariaDB 의 PRIMARY KEY 이름은 항상 'PRIMARY' — 명시 이름을 줘도 서버가 무시한다. @returns {string} */
+export function pkName(): string;
+/** @returns {string} */
+export function inlinePkName(): string;
+/**
+ * enum 의 CHECK 식 — contract 필수 멤버. maria 는 enum-type 전략이라 diff 경로에서는 쓰이지
+ * 않지만, 명시 .check() 렌더와 동형 표면을 유지한다.
+ * @param {string} col @param {string[]} values @returns {string}
+ */
+export function enumCheckExpr(col: string, values: string[]): string;
+/**
+ * 같은 타입의 길이/정밀도/enum 값 **축소** — 위배 데이터가 있으면 적용 실패·잘림 위험(경고 주석).
+ * enum 값 제거는 enum-type 전략에서 alterType 으로 오므로 여기서 함께 잡는다.
+ * @param {Record<string, any>} from @param {Record<string, any>} to @returns {boolean}
+ */
+export function isNarrowing(from: Record<string, any>, to: Record<string, any>): boolean;
+/**
+ * 변경 연산(op) 1개 → `{ up: string[], down: string[] }`. op 종류·필드는 differ 가 정본.
+ * @param {Record<string, any>} op
+ * @returns {{ up: string[], down: string[] }}
+ */
+export function renderOp(op: Record<string, any>): {
+    up: string[];
+    down: string[];
+};
+/**
+ * 연산 목록 → `{ up, down }` (down 은 역순). DDL 암묵 COMMIT 특성상 다단 변경의 중간 실패는
+ * 부분 적용으로 남는다 — 러너 락(ADR-190)·생성 파일 헤더가 그 한계를 명시한다.
+ * @param {Array<Record<string, any>>} ops
+ * @returns {{ up: string[], down: string[] }}
+ */
+export function renderOps(ops: Array<Record<string, any>>): {
+    up: string[];
+    down: string[];
+};
+/** maria 는 위치식 `?`(인덱스 무시). @returns {string} */
+export function placeholder(): string;
+/** SELECT native(rows 배열) → record[]. @param {any} res @returns {any[]} */
+export function parseReadResult(res: any): any[];
+/** write native(`{ affectedRows, insertId }`) → 정규화. @param {any} res */
+export function parseWriteResult(res: any): {
+    count: any;
+    insertId: any;
+};
+/** upsert 절 — `ON DUPLICATE KEY UPDATE col = VALUES(col)`. maria 는 conflict target 미사용(자동 unique 매칭). @param {{ updateCols: string[] }} o */
+export function upsertClause({ updateCols }: {
+    updateCols: string[];
+}): string;
+/** MariaDB 식별자 한도 — **64자**(chars, utf8 멀티바이트 식별자도 자수 기준). contract 멤버명은
+ * 역사적으로 *MaxBytes 지만 maria 검증은 자수로 한다(비ASCII 과잉 거부 방지 — ADR-208 L-3). */
+export const identifierMaxBytes: 64;
+/** 온라인 인덱스 추가 — `ALGORITHM=INPLACE, LOCK=NONE` (--concurrent 옵트인). */
+export const supportsConcurrentIndex: true;
+/** enum 표현 전략 — native ENUM 타입(값 변경 = MODIFY COLUMN). */
+export const enumStrategy: "enum-type";
+/** RENAME COLUMN 자체는 지원(10.5+)하나 DDL 암묵 COMMIT 이라 트랜잭션 내 원자성은 없다. */
+export const supportsRenameInTx: false;
+/** DDL 암묵 COMMIT — DROP COLUMN 을 트랜잭션으로 롤백할 수 없다(ADR-190 기존 인지). */
+export const canDropColumnInTx: false;
+/** ALTER 가 대부분의 변경을 표현 — 테이블 재생성 불요. */
+export const dependsOnRebuild: false;
+/** `ALTER TABLE … RENAME CONSTRAINT` 미지원 — MariaDB 11.8 실측(구문 에러). DROP+ADD 로 대체. */
+export const supportsRenameConstraint: false;
+/** ALTER 로 FK 추가/삭제 가능(`ADD CONSTRAINT … FOREIGN KEY` / `DROP CONSTRAINT` — 11.8 실측). */
+export const supportsAlterAddFk: true;
+/** InnoDB 는 FK 가 걸린 컬럼의 DROP 을 거부(1553 — FK 인덱스 요구, 11.8 실측) — dropFk 선행 필수. */
+export const requiresDropFkBeforeDropColumn: true;
+/** SQL DDL 렌더 dialect — 생성 파일이 `db.query(sql)` 계약을 쓴다(mongo 와 분기, ADR-209). */
+export const usesSqlDdl: true;
+export const paramStyle: "positional";
+export const supportsReturning: false;
+export const supportsBulkReturning: false;

package/types/core/migration/dialects/mongo.d.ts

@@ -0,0 +1,89 @@
+/**
+ * collection/필드 이름 검증 — mongo 는 SQL 인용이 없어서 quoteIdent 는 검증 깔때기 + 원형 반환.
+ * `$` 시작(연산자 충돌), `.`(경로 구분자), `system.` prefix(예약), 빈 문자열, NUL 을 거부한다.
+ * @param {string} name @returns {string}
+ */
+export function quoteIdent(name: string): string;
+/** JS 코드에 박는 값 literal — JSON 직렬화(따옴표·escape 안전). @param {unknown} value @returns {string} */
+export function quoteLiteral(value: unknown): string;
+/**
+ * contract 형식 충족용 — mongo 에는 CHECK 가 없다. enum 은 `$jsonSchema` 의 enum 키워드로
+ * 렌더되므로 이 함수가 정상 흐름에서 호출되면 통합 결함이다(silent 우회 금지).
+ * @param {string} col @param {string[]} values @returns {string}
+ */
+export function enumCheckExpr(col: string, values: string[]): string;
+/** @param {string} table @param {string[]} cols @param {boolean} [unique] @returns {string} */
+export function indexName(table: string, cols: string[], unique?: boolean): string;
+/** @param {string} table @param {Record<string, any>} ix @returns {string} */
+export function resolveIndexName(table: string, ix: Record<string, any>): string;
+/** @param {string} table @param {string} col @returns {string} */
+export function uniqueName(table: string, col: string): string;
+/** @param {string} table @param {string} col @param {string} refTable @returns {string} */
+export function fkName(table: string, col: string, refTable: string): string;
+/** @param {string} table @param {string} col @returns {string} */
+export function checkName(table: string, col: string): string;
+/** mongo PK 는 _id 단일 — diff 정규화용 합성 명칭. @param {string} table @returns {string} */
+export function pkName(table: string): string;
+/** @param {string} table @returns {string} */
+export function inlinePkName(table: string): string;
+/**
+ * record → collection `$jsonSchema`. `additionalProperties: false`(strict) 라 `_id` 를 항상
+ * properties 에 포함한다(_id 는 모든 도큐먼트에 존재 — 누락 시 insert 전부 거부되는 함정).
+ * @param {Record<string, any>} record
+ * @returns {Record<string, any>}
+ */
+export function jsonSchemaOf(record: Record<string, any>): Record<string, any>;
+/**
+ * 인덱스 컬럼 항목 파싱 — `'field'`(asc) | `'field:desc'`. 필드 존재 검증은 schema-validator 가
+ * suffix 제거 후 수행한다.
+ * @param {string} entry @returns {{ field: string, dir: 1 | -1 }}
+ */
+export function parseIndexColumn(entry: string): {
+    field: string;
+    dir: 1 | -1;
+};
+/**
+ * 변경 연산(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: Record<string, any>): {
+    up: string[];
+    down: string[];
+};
+/**
+ * ops 배열 → { up, down } (down 은 역순 — 적용의 정확한 역).
+ * @param {Array<Record<string, any>>} ops
+ * @returns {{ up: string[], down: string[] }}
+ */
+export function renderOps(ops: Array<Record<string, any>>): {
+    up: string[];
+    down: string[];
+};
+/** 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: Set<string>;

package/types/core/migration/dialects/postgres.d.ts

@@ -0,0 +1,117 @@
+/**
+ * SQL 식별자 인용 — 필요할 때만 `"..."`. **모든 식별자가 지나는 단일 깔때기**라 여기서
+ * 63byte 초과를 fail-fast 한다 — postgres 는 NOTICE 와 함께 조용히 절단해 이름 충돌·
+ * `migrate:status` 표기 불일치를 만들기 때문(자동 축약 없이 거부, 정책 2).
+ *
+ * @param {string} name @returns {string}
+ * @throws {MegaConfigError} `migration.identifier_too_long` - 63byte 초과(합성 이름 포함).
+ */
+export function quoteIdent(name: string): string;
+/**
+ * DEFAULT/CHECK 용 literal 렌더 — 문자열은 단일따옴표 escape, `{ raw }` 는 검증된 식 그대로.
+ * @param {unknown} value @returns {string}
+ */
+export function renderLiteral(value: unknown): string;
+/**
+ * 컬럼 타입 → postgres SQL 타입.
+ * @param {Record<string, any>} def @param {{ forAlter?: boolean }} [opts] - forAlter: ALTER TYPE 대상
+ *   (SERIAL 은 타입이 아니라 시퀀스 단축문법이라 INTEGER/BIGINT 로 강등).
+ * @returns {string}
+ */
+export function typeSql(def: Record<string, any>, { forAlter }?: {
+    forAlter?: boolean;
+}): string;
+/** @param {string} table @param {string[]} cols @param {boolean} [unique] @returns {string} */
+export function indexName(table: string, cols: string[], unique?: boolean): string;
+/** @param {string} table @param {Record<string, any>} ix @returns {string} 인덱스 정의의 유효 이름. */
+export function resolveIndexName(table: string, ix: Record<string, any>): string;
+/** @param {string} table @param {string} col @returns {string} */
+export function uniqueName(table: string, col: string): string;
+/** @param {string} table @param {string} col @param {string} refTable @returns {string} */
+export function fkName(table: string, col: string, refTable: string): string;
+/** @param {string} table @param {string} col @returns {string} */
+export function checkName(table: string, col: string): string;
+/** @param {string} table @returns {string} */
+export function pkName(table: string): string;
+/** CREATE TABLE 인라인 단일 PK 의 서버 자동 명명. @param {string} table @returns {string} */
+export function inlinePkName(table: string): string;
+/**
+ * enum 컬럼의 CHECK 식 — **유일한 enum CHECK 렌더 지점**(differ 는 values 만 전달, ADR-205 H-1).
+ * @param {string} col @param {string[]} values @returns {string}
+ */
+export function enumCheckExpr(col: string, values: string[]): string;
+/**
+ * ALTER TYPE 시 implicit cast 가 보장되지 않아 USING 식 검토가 필요한지. 안전 목록(정수 확장·
+ * varchar↔text·decimal 정밀도·timestamp↔timestamptz·길이 변경) 밖이면 true.
+ * @param {Record<string, any>} from @param {Record<string, any>} to @returns {boolean}
+ */
+export function isRiskyCast(from: Record<string, any>, to: Record<string, any>): boolean;
+/**
+ * 같은 타입의 길이/정밀도 **축소** 인지 — varchar(200→50)·decimal(12,2→8,2) 등. implicit cast 는
+ * 존재해 isRiskyCast 로는 안 잡히지만, 기존 데이터가 한도를 넘으면 적용이 실패하거나(varchar)
+ * 반올림·잘림이 생긴다 — 경고 주석 대상.
+ * @param {Record<string, any>} from @param {Record<string, any>} to @returns {boolean}
+ */
+export function isNarrowing(from: Record<string, any>, to: Record<string, any>): boolean;
+/**
+ * 변경 연산(op) 1개 → `{ up: string[], down: string[] }`.
+ * op 종류·필드는 {@link module:core/migration/differ} 가 정본.
+ *
+ * @param {Record<string, any>} op
+ * @returns {{ up: string[], down: string[] }}
+ */
+export function renderOp(op: Record<string, any>): {
+    up: string[];
+    down: string[];
+};
+/**
+ * 연산 목록 → `{ up: string[], down: string[] }`. down 은 **역순**(가장 마지막 변경부터 되돌림).
+ * @param {Array<Record<string, any>>} ops
+ * @returns {{ up: string[], down: string[] }}
+ */
+export function renderOps(ops: Array<Record<string, any>>): {
+    up: string[];
+    down: string[];
+};
+/** @param {number} i - 1-base placeholder 인덱스. @returns {string} */
+export function placeholder(i: number): string;
+/** SELECT native 결과(pg `{ rows }`) → record[]. @param {any} res @returns {any[]} */
+export function parseReadResult(res: any): any[];
+/** write native 결과(pg `{ rowCount, rows }`) → 정규화. @param {any} res @returns {{ count: number, rows?: any[] }} */
+export function parseWriteResult(res: any): {
+    count: number;
+    rows?: any[];
+};
+/** upsert 절 — `ON CONFLICT (...) DO UPDATE SET ...`. @param {{ conflictCols: string[], updateCols: string[] }} o @returns {string} */
+export function upsertClause({ conflictCols, updateCols }: {
+    conflictCols: string[];
+    updateCols: string[];
+}): string;
+/** 식별자 최대 길이(byte) — postgres NAMEDATALEN-1. 초과는 절단·충돌 위험이라 fail-fast(정책 2). */
+export const identifierMaxBytes: 63;
+/** CREATE INDEX CONCURRENTLY 지원(트랜잭션 밖 실행 필요 — generate --concurrent 옵트인). */
+export const supportsConcurrentIndex: true;
+/** enum 표현 전략 — 'check' = TEXT + CHECK(col IN (...)). (maria 는 'enum-type' 예정.) */
+export const enumStrategy: "check";
+/** RENAME COLUMN 의 트랜잭션 내 실행 지원. */
+export const supportsRenameInTx: true;
+/** DROP COLUMN 의 트랜잭션 내 롤백 가능(maria 는 DDL 암묵 commit 으로 false 예정). */
+export const canDropColumnInTx: true;
+/** 일부 ALTER 가 테이블 재생성을 요구하는지(sqlite true 예정). */
+export const dependsOnRebuild: false;
+/** ALTER TABLE ... RENAME CONSTRAINT 지원(postgres 9.2+). 미지원 dialect 는 DROP+ADD 로 대체. */
+export const supportsRenameConstraint: true;
+/** ALTER 로 FK 추가/삭제 가능 — false(sqlite)면 FK 는 CREATE TABLE 인라인 + 변경은 rebuild. */
+export const supportsAlterAddFk: true;
+/** FK 걸린 컬럼 DROP 전 dropFk 선행 필요 여부 — postgres 는 의존 객체 cascade 라 불필요. */
+export const requiresDropFkBeforeDropColumn: false;
+/** SQL DDL 렌더 dialect — 생성 파일이 `db.query(sql)` 계약을 쓴다(mongo 와 분기, ADR-209). */
+export const usesSqlDdl: true;
+/** dialect 표준 인터페이스 별칭 — 값 인용(SQL injection 방지 깔때기). @type {typeof renderLiteral} */
+export const quoteLiteral: typeof renderLiteral;
+/** placeholder 스타일 — postgres 는 번호식 `$1`. */
+export const paramStyle: "numbered";
+/** RETURNING 지원(insert/upsert 레코드 반환). */
+export const supportsReturning: true;
+/** insertMany RETURNING 지원. */
+export const supportsBulkReturning: true;

package/types/core/migration/dialects/sqlite.d.ts

@@ -0,0 +1,111 @@
+/**
+ * SQL 식별자 인용 — postgres 와 동일한 더블쿼트(필요 시만).
+ * @param {string} name @returns {string}
+ */
+export function quoteIdent(name: string): string;
+/**
+ * 값 literal 인용 — '' 이스케이프(sqlite 는 백슬래시 escape 없음). boolean 은 INTEGER 0/1.
+ * @param {unknown} value @returns {string}
+ */
+export function quoteLiteral(value: unknown): string;
+/**
+ * 컬럼 타입 → sqlite 타입(affinity).
+ * @param {Record<string, any>} def @returns {string}
+ */
+export function typeSql(def: Record<string, any>): string;
+/** @param {string} table @param {string[]} cols @param {boolean} [unique] @returns {string} */
+export function indexName(table: string, cols: string[], unique?: boolean): string;
+/** @param {string} table @param {Record<string, any>} ix @returns {string} */
+export function resolveIndexName(table: string, ix: Record<string, any>): string;
+/** @param {string} table @param {string} col @returns {string} */
+export function uniqueName(table: string, col: string): string;
+/** @param {string} table @param {string} col @param {string} refTable @returns {string} */
+export function fkName(table: string, col: string, refTable: string): string;
+/** @param {string} table @param {string} col @returns {string} */
+export function checkName(table: string, col: string): string;
+/** @param {string} table @returns {string} */
+export function pkName(table: string): string;
+/** sqlite 인라인 PK 는 별도 제약 이름이 없다 — diff 정규화용 합성 명칭. @param {string} table @returns {string} */
+export function inlinePkName(table: string): string;
+/**
+ * enum 의 CHECK 식 — 유일한 enum 렌더 지점(differ 는 values 만 전달).
+ * @param {string} col @param {string[]} values @returns {string}
+ */
+export function enumCheckExpr(col: string, values: string[]): string;
+/**
+ * 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 function inspectRebuildHazards(filename: string, tables: string[]): Promise<{
+    triggers: string[];
+    conflictViews: string[];
+}>;
+/**
+ * 변경 연산(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: Record<string, any>): {
+    up: string[];
+    down: string[];
+};
+/**
+ * 연산 목록 → `{ up, down }` (down 은 역순).
+ * @param {Array<Record<string, any>>} ops
+ * @returns {{ up: string[], down: string[] }}
+ */
+export function renderOps(ops: Array<Record<string, any>>): {
+    up: string[];
+    down: string[];
+};
+/** sqlite 는 위치식 `?`(인덱스 무시). @returns {string} */
+export function placeholder(): string;
+/** SELECT native(stmt.all 배열) → record[]. @param {any} res @returns {any[]} */
+export function parseReadResult(res: any): any[];
+/** write native → 정규화. RETURNING 이면 stmt.all 배열, 아니면 `{ changes, lastInsertRowid }`. @param {any} res */
+export function parseWriteResult(res: any): {
+    count: number;
+    rows: any[];
+    lastInsertRowid?: undefined;
+} | {
+    count: number;
+    lastInsertRowid: any;
+    rows?: undefined;
+};
+/** upsert 절 — `ON CONFLICT (...) DO UPDATE SET col = excluded.col`. @param {{ conflictCols: string[], updateCols: string[] }} o */
+export function upsertClause({ conflictCols, updateCols }: {
+    conflictCols: string[];
+    updateCols: string[];
+}): string;
+/** sqlite 는 식별자 길이 제한이 사실상 없다. */
+export const identifierMaxBytes: number;
+/** 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;
+export const paramStyle: "positional";
+export const supportsReturning: true;
+export const supportsBulkReturning: true;

package/types/core/migration/differ.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 한 adapter 그룹의 모델 목록 diff.
+ *
+ * @param {Array<{ name: string, table: string, record: any }>} prevModels - 직전 snapshot 의 모델.
+ * @param {Array<{ name: string, table: string, record: any }>} currModels - 현재 스캔 모델.
+ * @param {{ renames?: Record<string, Record<string, string>>, dialect?: Record<string, any> }} [opts]
+ *   - renames: `{ [table]: { old: new } }` 확정 rename 매핑(미지정 시 drop+add 로 두고 후보만 보고).
+ *   - dialect: 명명·능력 contract(기본 postgres — 호출자는 driver 별 dialect 를 주입).
+ * @returns {{ ops: Array<Record<string, any>>, renameCandidates: Array<{ table: string, dropped: string[], added: string[] }> }}
+ */
+export function diffModels(prevModels: Array<{
+    name: string;
+    table: string;
+    record: any;
+}>, currModels: Array<{
+    name: string;
+    table: string;
+    record: any;
+}>, { renames, dialect }?: {
+    renames?: Record<string, Record<string, string>>;
+    dialect?: Record<string, any>;
+}): {
+    ops: Array<Record<string, any>>;
+    renameCandidates: Array<{
+        table: string;
+        dropped: string[];
+        added: string[];
+    }>;
+};
+/**
+ * `--renames "old:new,old2:new2"` 문자열을 테이블별 매핑으로 펼친다 — 후보 테이블의 dropped/added
+ * 에 해당 쌍이 있을 때만 그 테이블에 적용(테이블 간 동명 컬럼 오적용 방지).
+ *
+ * **어떤 후보와도 매치되지 않는 쌍은 fail-fast** 한다(`migration.rename_unmatched`) — 오타를
+ * 조용히 버리면 사용자는 rename 을 명시했다고 믿는 채 무경고 DROP COLUMN(데이터 손실) 마이그레이션이
+ * 생성된다(P1 보호의 입구).
+ *
+ * @param {string} spec - `old:new[,old:new...]`.
+ * @param {Array<{ table: string, dropped: string[], added: string[] }>} candidates
+ * @returns {Record<string, Record<string, string>>}
+ * @throws {MegaConfigError} `migration.rename_invalid` - 형식 오류. `migration.rename_unmatched` - 후보 불일치.
+ */
+export function parseRenamesSpec(spec: string, candidates: Array<{
+    table: string;
+    dropped: string[];
+    added: string[];
+}>): Record<string, Record<string, string>>;