@gaonjs/cli 0.5.0 → 0.10.1

package/dist/templates/project/agents/data.md.tpl

@@ -0,0 +1,556 @@
+# agents/data.md — 데이터 레이어 (스키마 · 모델 · 관계 · 쿼리 · 서비스 · 마이그레이션)
+
+> 골격: **정본 규칙 → 정본 예시 → 알려진 함정 → 관련 결정 번호** (결정 40 · 2층 구조).
+> 루트 `AGENTS.md` 는 코어 요약만 담는다 — 시그니처·표·예시의 정본은 이 파일이다.
+> 대상 패키지: `@gaonjs/data` (파사드 import 는 `gaonjs/data` · `gaonjs/service`).
+
+## 정본 규칙
+
+### 1. 스키마 정의 (v0.15 §4.2)
+
+```ts
+// domain/schema/posts.ts — 스키마 파일명 = 테이블명 (루트 §네이밍)
+import { table, t } from 'gaonjs/data'
+
+export const posts = table('posts', {
+  id: t.id(),                          // bigint PK, 자동
+  title: t.string().max(200),
+  body: t.text(),
+  published: t.boolean().default(false),
+  authorId: t.belongsTo('users'),      // FK + 관계를 한 줄로
+  ...t.timestamps(),                   // createdAt, updatedAt
+})
+```
+
+**컬럼 정의가 곧 DB 타입 + TS 타입 + 검증 규칙의 단일 원천**이다
+(v0.15 §4.2 line 388 원문). 세 곳에 따로 쓰지 않는다.
+
+### 1.1 관계 선언 (M2D · 결정 33)
+
+관계는 **두 자리**에 나뉘어 산다 — FK 컬럼을 **가진 쪽**은 컬럼으로,
+**갖지 않는 쪽**(역방향)은 `table()` 3번째 인자의 `relations` 로 쓴다.
+역방향은 자기 테이블에 컬럼을 만들지 않으므로 컬럼 자리에 둘 수 없다.
+
+```ts
+// domain/schema/posts.ts
+import { table, t, hasMany, hasOne, belongsToMany } from 'gaonjs/data'
+
+export const posts = table('posts', {
+  id: t.id(),
+  title: t.string().max(200),
+  authorId: t.belongsTo('users'),          // 정방향(FK 보유) = 컬럼
+  ...t.timestamps(),
+}, {
+  relations: {
+    comments: hasMany('comments'),         // 1:N  → comments.postId
+    cover: hasOne('covers'),               // 1:1  → covers.postId
+    tags: belongsToMany('tags'),           // N:M  → posts_tags(postId, tagId)
+  },
+})
+```
+
+**대상은 언제나 문자열 테이블명**이다 — 모델을 넘기지 않는다. 모델끼리
+import 하면 순환 참조가 생기므로, 실제 연결은 부팅 시 프레임웍이 한다
+(정본 §4.4 "관계는 지연 정의").
+
+| 선언 | 시그니처 | 레코드 접근 | 반환 |
+|---|---|---|---|
+| `t.belongsTo(table)` | `(table)` — **컬럼** | `await post.author()` | `Row` (단건) |
+| `hasMany(target, opts?)` | `(target, { foreignKey? })` | `await post.comments()` | `Row[]` |
+| `hasOne(target, opts?)` | `(target, { foreignKey? })` | `await post.cover()` | `Row \| undefined` |
+| `belongsToMany(target, opts?)` | `(target, { through?, foreignKey?, otherKey? })` | `await post.tags()` | `Row[]` |
+
+**기본값 관례** (생략 시 · 명시 지정이 항상 이긴다):
+
+| 옵션 | 기본값 | 예 |
+|---|---|---|
+| `foreignKey` | 단수형(**자기** 테이블) + `Id` | `posts` → `postId` |
+| `otherKey` | 단수형(**대상** 테이블) + `Id` | `tags` → `tagId` |
+| `through` | 두 테이블명을 **사전순**으로 결합 | `posts`+`tags` → `posts_tags` |
+
+- 관례에 맞지 않으면 **명시한다** — 예: `posts.authorId` 를 가리키는
+  `users` 쪽 선언은 `hasMany('posts', { foreignKey: 'authorId' })`.
+- 조인 테이블은 **평범한 테이블**로 따로 정의한다
+  (`table('posts_tags', { id: t.id(), postId: t.belongsTo('posts'), tagId: t.belongsTo('tags') })`).
+  `belongsToMany` 가 테이블을 만들어 주지는 않는다.
+- doctor 가 **대상·조인 테이블의 존재**와 **커넥션 경계**(§7)를
+  검사한다 (`unknown-relation-target` · `cross-connection-relation`).
+
+### 1.2 DB 네이밍 (결정 43)
+
+테이블명·컬럼명·파일명 사이의 표기와 변환은 아래가 전부다 — 추측하지 않는다.
+
+| 대상 | 표기 | 예시 |
+|---|---|---|
+| 테이블명 (`table('...')` 문자열) | 소문자 · **복수** · 다단어 `snake_case` | `posts` · `posts_tags` |
+| 컬럼명 (스키마 키 · Row 타입) | **camelCase** | `title` · `authorId` · `createdAt` |
+| FK 컬럼 | 단수 테이블 + `Id` | `posts` → `postId` · `tags` → `tagId` |
+| 타임스탬프 | `createdAt` · `updatedAt` (`...t.timestamps()`) | — |
+| 스키마 파일명 | 테이블명을 **camelCase** 로 | `posts.ts` · `posts_tags` → `postsTags.ts` |
+| export 심볼 | 파일명과 같은 camelCase | `export const postsTags = table('posts_tags', …)` |
+| 모델 파일·심볼 | **PascalCase 단수** | `domain/models/Post.ts` · `export const Post` |
+| `tables.d.ts` 키 · DB 실 테이블 | **테이블명 그대로**(snake_case) | `posts_tags: RowOf<typeof postsTags>` |
+
+**변환 규칙은 하나** — 다단어 테이블 `posts_tags` 는:
+
+- 스키마 **파일명**·**export 심볼** = camelCase `postsTags`,
+- `table()` 문자열 · `tables.d.ts` 키 · DB 테이블 = snake_case `posts_tags`.
+
+컬럼은 어느 경우에도 camelCase 다(스네이크 컬럼 리터럴 금지 · `createdAt`
+이지 `created_at` 아님). 파일명 casing 은 doctor `schema-filename` 이
+강제한다(단수/복수는 대상 밖 · 결정 38).
+
+### 2. 컬럼 타입 전체 (실 구현 · `packages/data/src/schema.ts:394-445`)
+
+| 빌더 | SQL 타입 | TS 타입 | 비고 |
+|---|---|---|---|
+| `t.id()` | `bigserial` | `bigint` | PK · insert 선택적 |
+| `t.string()` | `varchar` | `string` | `.max(n)` 로 길이 |
+| `t.text()` | `text` | `string` | 긴 문자열 |
+| `t.boolean()` | `boolean` | `boolean` | |
+| `t.bigint()` | `bigint` | `bigint` | |
+| `t.datetime()` | `timestamptz` | `Date` | 타임존 포함 |
+| `t.belongsTo('users')` | `bigint` | `bigint` | FK + 관계 자동 파생 |
+| `t.timestamps()` | `timestamptz × 2` | — | createdAt·updatedAt |
+| `t.decimal(p, s)` | `numeric(p,s)` | `string` | 정확성 우선 (E-4 (b)) |
+| `t.enum([...] as const)` | `text + CHECK` | union type | E-4 (a) |
+| `t.uuid()` | `uuid` | `string` | |
+| `t.uuidPk()` | `uuid` | `string` | PK · `gen_random_uuid()` (E-4 (d)) |
+| `t.json<T>()` / `t.jsonb<T>()` | `jsonb` | `T` (제네릭) | Postgres 권장 = jsonb |
+| `t.int()` | `integer` | `number` | 4바이트 정수 |
+| `t.smallint()` | `smallint` | `number` | 2바이트 정수 |
+| `t.float()` | `real` | `number` | 4바이트 부동소수 |
+| `t.double()` | `double precision` | `number` | 8바이트 부동소수 |
+| `t.date()` | `date` | `string` (ISO 8601) | E-4 (c) |
+| `t.time()` | `time` | `string` (`HH:MM:SS`) | E-4 (c) |
+| `t.bytea()` | `bytea` | `Uint8Array` | 인라인 바이너리 |
+
+### 3. 컬럼 수식어
+
+모든 타입에 적용되는 수식어(빌더가 지원하는 조합만):
+
+- `.nullable()` — NULL 허용. Row 타입이 `T | null` 이 되며 insert 에서
+  선택적.
+- `.default(v)` — DDL 기본값 (모든 타입에 확장 · E-4 §4.1). `t.id()` /
+  `t.timestamps()` / `.default()` 가 붙은 컬럼은 `create()` 입력에서
+  선택적이다 (v0.15 §4.2 line 392–395).
+- `.hidden()` — 직렬화 경계(`Serialized<>` · `SerializedOf<>`)에서
+  **타입 레벨로** 제외 (모든 타입에 확장). 페이지 props 에서 접근하면
+  컴파일 에러 — 유출이 타입 시스템에서 막힌다 (v0.15 §4.2 line
+  396–399 원문). 비밀번호 다이제스트가 대표: `passwordDigest: t.string().hidden()`.
+- `.unique()` — 컬럼 레벨 UNIQUE 제약 (E-4).
+- `.index()` — 컬럼 레벨 인덱스 (E-4).
+- `.check(expr)` — 컬럼 레벨 CHECK 제약 (E-4).
+
+**테이블 레벨 복합 제약** (E-4 §4.2):
+
+```ts
+export const posts = table('posts', {
+  slug: t.string().max(100),
+  ownerId: t.belongsTo('users'),
+  ...t.timestamps(),
+}, {
+  db: 'main',                              // 커넥션 키 (§7)
+  unique: [['ownerId', 'slug']],           // 복합 unique
+  index: [['ownerId', 'createdAt']],       // 복합 index
+  check: [['positive_age', 'age > 0']],    // [name, expr]
+})
+```
+
+### 4. 체이닝 전체 (`packages/data/src/model.ts:136-338`)
+
+체이닝 표면은 아래 표가 **전부**다. 표에 없는 메서드
+(`destroy`·`findBy`·`paginate`·`order`·해시 인자
+`where({...})` 같은 다른 ORM 관습)를 추측해서 쓰지 말 것 — 표
+바깥의 쿼리는 §5 `Post.query()` 탈출구로 내려간다.
+
+**where op 12종** (`model.ts:61-71`):
+
+| 분류 | op | val 인자 |
+|---|---|---|
+| 비교 (`WhereOp`) | `=` `!=` `>` `<` `>=` `<=` `like` `ilike` | `Row[col]` 1개 |
+| 컬렉션 (`WhereOpIn`) | `in` `not in` | `ReadonlyArray<Row[col]>` |
+| Null (`WhereOpNull`) | `is null` `is not null` | **없음** — 2-인자 호출 `where('deletedAt', 'is null')` |
+
+**체이닝 메서드 전체** (`Chain` · `model.ts:79-109`):
+
+| 메서드 | 시그니처 | 반환 | 비고 |
+|---|---|---|---|
+| `where` | `(col, op, val?)` | `Chain` | op 에 따라 val 형태 강제 (위 표) |
+| `whereIn` | `(col, vals)` | `Chain` | `where(col, 'in', vals)` 축약 |
+| `orWhere` | `(col, op, val?)` | `Chain` | op 12종 전부 (M2C) · 결합은 `(a AND b) OR c` (Rails 관습 · `model.ts:245-262`) |
+| `orderBy` | `(col, dir?)` | `Chain` | dir 기본 `'asc'` · 호출마다 누적 (다중 정렬) |
+| `reorder` | `(col, dir?)` | `Chain` | 기존 정렬 전부 버리고 재지정 |
+| `latest` | `()` | `Chain` | `orderBy('createdAt', 'desc')` 고정 축약 |
+| `limit` | `(n)` | `Chain` | |
+| `offset` | `(n)` | `Chain` | 페이지네이션 = `orderBy·offset·limit` 조합 |
+| `first` | `()` | `Promise<Rec \| undefined>` | 자동 `limit 1` |
+| `all` | `()` | `Promise<Rec[]>` | |
+| `count` | `()` | `Promise<bigint>` | driver 별 반환을 **bigint 로 통일** (E-4 (g) · `model.ts:390`) |
+| `exists` | `()` | `Promise<boolean>` | |
+| `sum` · `avg` | `(col)` | `Promise<string \| null>` | numeric 정확성 · 대상 행 없으면 null |
+| `min` · `max` | `(col)` | `Promise<Row[col] \| null>` | 컬럼 타입 그대로 |
+| `pluck` | `(col)` | `Promise<Row[col][]>` | 단일 컬럼 배열 · 정렬·limit·offset 반영 |
+| `select` | `(['a', 'b'])` | `SelectChain<Row, K>` | 부분 컬럼 — `first`/`all` 이 `Pick<Row, K>` **plain 행** 반환 (메서드·관계·update 없음) |
+| `include` | `(...rels)` | `IncludedChain` | 관계 eager 로드 — **4종 전부**(belongsTo·hasMany·hasOne·belongsToMany, §1.1). **N+1 방지**: 관계당 쿼리 1회 (belongsToMany 는 피벗 `inner join` 1회) · 행 수와 무관. doctor 의 **n-plus-one** 검사가 include 미사용 · loop 안 관계 호출을 감지한다 |
+| `updateAll` | `(patch)` | `Promise<bigint>` | **벌크 갱신** (M2C) — where 조건만 반영 · 영향 행 수 반환. limit·offset·orderBy 가 걸려 있으면 **throw** (Postgres `UPDATE ... LIMIT` 미지원 — 행을 좁히려면 `pluck('id')` → `whereIn('id', ids)`) |
+| `deleteAll` | `()` | `Promise<bigint>` | **벌크 삭제** (M2C) — 규칙은 updateAll 과 동일. 빈 where = 전체 삭제 (이름이 위험을 드러냄) |
+
+**집계·조인 그룹** (`Chain` · M2E · 결정 34):
+
+| 메서드 | 시그니처 | 반환 | 비고 |
+|---|---|---|---|
+| `groupBy` | `(col \| col[])` | `GroupChain` | 그룹 집계로 **분기** — 종단은 집계 함수 하나(`count`/`sum`/`avg`/`min`/`max`)이고 결과는 `Rec[]` 이 아니라 **`그룹 키 + 집계값` 행 배열**(`GroupRow[]`). `Post.groupBy('authorId').count()` → `{ authorId, count: bigint }[]` |
+| `having` | `('count', op, val)` · `('sum'\|'avg'\|'min'\|'max', col, op, val)` | `GroupChain` | groupBy 뒤 **집계값** 필터 (그룹 키 필터는 `where`). `.having('count', '>', 2)` · `.having('sum', 'price', '>=', 1000)` |
+| `distinct` | `()` · `(col \| col[])` | `Chain` · `SelectChain` | 인자 없으면 `SELECT DISTINCT` 전체 행(집계·벌크 쓰기 이어짐), 컬럼을 주면 그 컬럼만 뽑는 `SelectChain`. `distinct().count()` 는 `count(distinct id)` |
+| `withCount` | `(...rels)` | `IncludedChain` | 관계별 개수를 **상관 서브쿼리**로 얹는다 — `withCount('comments')` → 각 Rec 에 `commentsCount: bigint`. 조인이 아니라 행이 안 늘어 `limit` 과 함께 써도 개수가 정확. **hasMany·hasOne·belongsToMany 만**(belongsTo 는 항상 0/1 이라 throw). `include` 와 같은 체인에 실린다(`include('author').withCount('comments')`) |
+| `join` | `(table, 'table.col', 'self.col')` | `JoinChain` | INNER JOIN — **필터·정렬 수단**이고 반환은 **자기 테이블의 Rec**(조인 테이블 컬럼은 안 실림 → 뽑아야 하면 §5 `Post.query()`). 조인 테이블 조건은 한정 이름(`where('users.name', '=', ...)`), 1:N 부풀림은 `distinct()` 로 접는다. `join`/`leftJoin`·`where`·`orderBy`·`distinct`·`select`·`pluck`·`count`·`exists`·`first`·`all` 이어짐 |
+| `leftJoin` | `(table, 'table.col', 'self.col')` | `JoinChain` | LEFT OUTER JOIN — 짝 없는 자기 행도 남는다. "짝 없는 것만" = `.where('posts.id', 'is null')` |
+
+> 조인 노출은 정본 결정 28 게이트 (f)(원안 = 기각·`Post.query()` 로만)를
+> **재결정**한 결과다 (결정 34 · 2026-07-24 PM 승인). `withCount` 가 관계명
+> 기반이라 조인 없이 조인 파워를 주고, `join`/`leftJoin` 은 반환을 자기
+> 테이블 Rec 으로 좁혀 "정답이 하나" 원칙을 지킨다 — 조인 테이블 컬럼까지
+> 필요한 SELECT 는 여전히 `Post.query()` 탈출구다.
+
+**루트 전용** (`ModelApi` · `model.ts:148-171`) — 체인 중간에서는 못 쓴다:
+
+| 메서드 | 시그니처 | 반환 | 비고 |
+|---|---|---|---|
+| `create` | `(data)` | `Promise<Rec>` | `t.id()`·`t.timestamps()`·`.default()` 컬럼은 입력에서 선택적 (`InsertOf`) |
+| `batchInsert` | `(rows)` | `Promise<Rec[]>` | **벌크 삽입** (M2F · 결정 35) — 여러 row 를 **단일 INSERT 문**(원자적)으로 · 넣은 순서대로 Rec 반환. 빈 배열은 DB 무접촉 `[]`. beforeCreate 훅은 각 row 에 적용 |
+| `insertOrIgnore` | `(row \| rows)` | `Promise<Rec[]>` | **멱등 삽입** (M2F) — `ON CONFLICT DO NOTHING` · UNIQUE/PK 충돌 행은 건너뛰고 **실제로 삽입된 Rec 만** 반환. 충돌 대상 인자 없음(어떤 UNIQUE/PK 든 충돌 시 건너뜀) |
+| `upsert` | `(row \| rows, { onConflict?, update? })` | `Promise<Rec[]>` | **있으면 갱신 없으면 삽입** (M2F) — `ON CONFLICT DO UPDATE`. `onConflict` 생략 = 기본 키(`id`) 자동(없으면 throw) · `update` 생략(`'exclude'`) = 입력 컬럼에서 충돌 기준·`id` 뺀 나머지를 `excluded` 로 덮음 · 갱신 대상 없으면 DO NOTHING |
+| `find` | `(id)` | `Promise<Rec>` | 없으면 **throw** — undefined 를 허용하려면 `where('id', '=', id).first()` |
+| `query` | `()` | Kysely `SelectQueryBuilder` | §5 탈출구 |
+
+> 벌크 삽입 3종(`batchInsert`·`insertOrIgnore`·`upsert`)은 **RETURNING 을
+> 지원하는 커넥션(Postgres)** 에서만 된다 — 삽입/무시/갱신된 행 집합을
+> 정확히 복원할 수 있는 방언이 RETURNING 뿐이라, 비 RETURNING 커넥션에서는
+> 어림하지 않고 수리 안내와 함께 **throw** 한다(결정 35 · §7.5.3). 삽입 계열은
+> `create` 처럼 루트 전용 — `where` 필터와 무관하므로 체인 종단이 아니다.
+
+**레코드(`Rec`) 내장** (`model.ts:47-52`):
+
+- `rec.update(patch)` — `Partial<Row>` 부분 갱신, 갱신된 Rec 반환.
+- `rec.delete()` — id 기준 단건 삭제, `Promise<void>` (M2C). 벌크는
+  체인 `deleteAll()`. `destroy()` 아님 — TS 생태계 관례(Prisma
+  `delete`·Kysely `deleteFrom`) 정합 (결정 31).
+- 관계 메서드 — 선언(§1.1)에서 자동 파생, lazy 1회 조회:
+  `authorId: t.belongsTo('users')` → `await post.author()` /
+  `comments: hasMany('comments')` → `await post.comments()`.
+  **`include()` 로 로드하면 같은 이름이 값이 된다** — `post.comments`
+  (배열). 함수가 아니라 값이라 페이지 props 로 그대로 직렬화된다
+  (§6 `Serialized<T>` 는 함수 값을 떨군다).
+- 사용자 메서드 (§8 `methods`) — `this` = Rec 으로 바인딩.
+
+**체인 상태 전이 주의** (`model.ts:112-146`):
+
+- `select()`·`include()` 이후에도 빌더 메서드(`where`·`orWhere`·
+  `whereIn`·`orderBy`·`reorder`·`latest`·`limit`·`offset`)는 전부
+  이어진다 (M2C 패리티) — `Post.include('author').latest().all()` 도 됨.
+- 단 **스칼라 집계(count 등)·pluck·벌크 쓰기(updateAll/deleteAll)·
+  스코프·`groupBy`·`join`/`leftJoin` 은 `Chain` 전용** — select·include
+  **앞**에서 끝낸다. `withCount` 는 예외로 `include` 와 같은 자리에 실린다.
+- `groupBy` 이후는 `GroupChain` — 결과가 그룹 행이라 `first`/`all` 대신
+  집계 함수가 종단이고, 레코드가 아니라 `include`·`select` 도 없다.
+- `join`/`leftJoin` 이후는 `JoinChain` — 반환은 자기 Rec 이라
+  `include`·집계 그룹은 없고 스칼라 집계·`select`(자기 컬럼)·`pluck` 만.
+- `select()` 이후엔 `include` 도 없다 (부분 행에 관계를 붙이지 않는다).
+- 스코프(§8)는 `Chain` 의 어느 지점에서든 재호출 가능
+  (`Post.where(...).published()` 도 됨).
+
+### 5. `Post.query()` = Kysely 원본 (탈출구)
+
+**정본 §4.4 line 448–449 원문:**
+> "…내부 구현은 Kysely 위에 얹으므로, 복잡한 쿼리는 언제든
+> `Post.query()`로 내려가 순수 쿼리 빌더를 쓸 수 있다(탈출구)."
+
+실 구현 (E-4 (h) 정정 · `model.ts:165, 590-593`):
+
+```ts
+// 조인·집계·CTE 등 복잡 쿼리
+const rows = await Post.query()
+  .innerJoin('users', 'users.id', 'posts.authorId')
+  .select(['posts.title', 'users.email'])
+  .execute()
+```
+
+반환 타입 = Kysely `SelectQueryBuilder<any, any, {}>` (원본). Chain
+좁게 유지 + 조인 등 복잡 쿼리는 여기서 처리 (E-4 (f) 결정).
+
+### 6. `Serialized<T>` (vue) vs `SerializedOf<Defs>` (data) — **별개 타입**
+
+두 타입은 이름이 비슷하지만 **별개**다 (E-4 §7).
+
+- `packages/vue/src/serialize.ts:28` — **`Serialized<T>`**: 임의 값의
+  JSON-safe 매핑 (Date → string, bigint → string, Hidden 브랜드 제외).
+  `api()` 반환 타입 · `pageProps<'ctrl#action'>()` 결과 타입이 이것.
+- `packages/data/src/schema.ts:544` — **`SerializedOf<Defs>`**: 테이블
+  스키마 defs 의 SerializedOf — hidden 컬럼 키 제외한 Row.
+
+혼동 유발이라 이름 분리를 유지한다 (E-4 (i) 결정).
+
+### 7. 멀티 DB 커넥션 (v0.15 §4.5)
+
+- **키 생략 = main** — 기본 경로는 단일 DB 프로젝트와 완전히 같다.
+- **커넥션을 가로지르는 `belongsTo` 는 금지** — doctor 의
+  **connections** 검사가 잡는다.
+- **`service()` 트랜잭션은 단일 커넥션에서만 원자적** — 다중 커넥션
+  접근 시 doctor 경고.
+- 마이그레이션은 커넥션별: `gaon db diff --db legacy`.
+
+### 8. 모델 정의 (`model()`) (`packages/data/src/model.ts:601-622`)
+
+`model()` 은 스키마(§1)를 Kysely 위의 실행 가능한 API 로 감싼다 —
+scope·인스턴스 메서드를 함께 선언하고, 나머지 체이닝(§4)·CRUD 는
+런타임이 자동 생성한다.
+
+```ts
+// domain/models/Post.ts
+import { model } from 'gaonjs/data'
+import { posts } from '../schema/posts.js'
+
+export const Post = model(posts, {
+  scopes: {
+    published: (q) => q.where('published', '=', true),
+    recent: (q) => q.latest().limit(10),
+    // 파라미터 스코프 (M2C) — q 뒤 인자가 호출 시그니처가 된다
+    byAuthor: (q, authorId: bigint) => q.where('authorId', '=', authorId),
+  },
+  methods: {
+    // 인스턴스 메서드 — this 는 레코드(Rec) 타입으로 추론된다
+    async publish() {
+      return await this.update({ published: true })
+    },
+  },
+  hooks: {
+    beforeCreate(data) {
+      // insert 직전 데이터 보정 (정규화·파생값 등)
+      data.title = data.title?.trim()
+    },
+  },
+})
+```
+
+```ts
+// 사용 — scope·체이닝·CRUD 가 그대로 이어진다
+const items = await Post.published().latest().limit(20).all()
+const both = await Post.published().recent().all()      // 스코프 조합
+const mine = await Post.byAuthor(user.id).count()       // 파라미터 스코프
+const post = await Post.create({ title: '제목', body: '...', authorId: user.id })
+await post.publish()                                    // 인스턴스 메서드
+```
+
+- **두 번째 인자** = `{ scopes?, methods?, hooks? }`. `scopes` 값은
+  `(q) => q.where(...)` 형태로 쿼리를 좁히는 함수, `methods` 는 인스턴스
+  메서드(`this` 로 레코드 필드·관계에 접근), `hooks` 는 `beforeCreate`
+  하나 (`model.ts:610`).
+- **스코프는 반드시 `scopes: {}` 객체 안에** 선언한다 (NAMESPACED) —
+  model() 밖 별도 함수·프로퍼티로 흉내내지 않는다.
+- **파라미터 스코프** (M2C · 결정 31) — 첫 인자 `q` 는 고정, 그 뒤
+  인자는 자유이며 **타입을 명시**한다 (`(q, authorId: bigint) => ...`).
+  q 뒤 인자가 그대로 호출 시그니처가 된다: `Post.byAuthor(1n)`.
+  무인자 스코프를 `Post.published(true)` 처럼 인자 호출하면 타입 에러.
+- **`Post.query()`** 로 언제든 Kysely 원본으로 내려갈 수 있다 (§5).
+- **관계는 `model()` 이 아니라 스키마에 선언한다** (§1.1) — `model()`
+  두 번째 인자에 `relations` 자리는 없다. 선언한 관계는 scope·method 와
+  자유롭게 조합된다: scope 는 관계 로드 **전에** 체인을 좁히고
+  (`Post.published().include('comments')`), method 의 `this` 에서는
+  관계를 그대로 호출한다.
+
+```ts
+export const Post = model(posts, {
+  scopes: {
+    // 스코프는 컬럼만 다룬다 — 관계 조건이 필요하면 Post.query() 탈출구(§5)
+    published: (q) => q.where('published', '=', true),
+  },
+  methods: {
+    // this = Rec — 스키마에 선언한 관계가 그대로 붙어 있다
+    async commentCount() {
+      return (await this.comments()).length
+    },
+  },
+})
+```
+
+### 9. 서비스 (`service()`) — 트랜잭션 작업 흐름 (정본 §5.3 · `packages/data/src/service.ts`)
+
+로직 배치의 One Way 규칙은 루트 `AGENTS.md` 판단표가 정본이다 (정본 §5.3):
+한 모델 안 로직 → 모델 메서드 · 여러 모델/외부 API/트랜잭션 → `domain/services/` ·
+컨트롤러는 HTTP 번역만.
+
+```ts
+// domain/services/publishPost.ts — 파일명 camelCase (루트 §네이밍)
+import { service, afterCommit } from 'gaonjs/service'
+import { Post } from '../models/Post.js'
+
+export const PublishPost = service(async (postId: bigint) => {
+  const post = await Post.find(postId)
+  const published = await post.update({ published: true })
+  afterCommit(async () => { /* 커밋 성공 뒤에만 — 이벤트·잡 발행 지점 */ })
+  return published
+})
+
+// 컨트롤러에서:
+// const post = await PublishPost.call(this.params('id'))
+```
+
+- **시그니처** — `service(handler, options?)` → `{ call(...args) }`.
+  `call()` 의 인자·반환 타입은 핸들러 정의에서 그대로 추론된다
+  (제네릭 인자를 직접 붙이지 않는다).
+- **트랜잭션** — 본문 전체가 하나의 DB 트랜잭션. 중간 실패 시 전부
+  롤백. 본문 안의 모델 호출은 코드 변경 없이 트랜잭션에 합류한다
+  (AsyncLocalStorage 전파). `{ transaction: false }` 로 해제.
+- **커넥션** — `{ db: '키' }` (생략 = main). 트랜잭션은 **단일
+  커넥션에서만 원자적** (§7) — 다른 키의 조회는 트랜잭션 밖에서
+  돌고, doctor 의 **connections** 검사가 다중 커넥션 접근을 경고한다.
+- **중첩** — 같은 커넥션 키의 서비스가 서비스를 부르면 바깥
+  트랜잭션에 합류한다 (중첩 BEGIN 없음 — 전체가 한 단위).
+- **`afterCommit(fn)`** — 커밋 성공 뒤에만 실행 (롤백 시 실행 안 됨).
+  잡·이벤트 발행처럼 "DB 확정 후에만 나가야 하는" 부수효과를 여기 둔다.
+  service() 본문 밖에서 부르면 에러.
+- **파사드는 `gaonjs/service`** — `@gaonjs/data` (스코프) 로 import
+  하지 않는다.
+
+### 10. 마이그레이션 — 파일 리플레이 + 스키마 diff (합성형 · 결정 39)
+
+```bash
+gaon db diff          # 스키마(domain/schema/*.ts) ↔ 실제 DB 차이 미리보기 (적용 X)
+gaon db migrate       # db/migrations/*.ts replay → 스키마 diff 적용 + _gaon_migrations 이력
+gaon db migrate down  # 가장 최근 이력 1건 롤백
+gaon db status        # 마이그레이션 파일 적용/대기 + 스키마 drift
+gaon db reset --yes   # 초기화 (dev · production 거부)
+gaon db seed          # domain/seed.ts 실행
+```
+
+**기본은 스키마 우선이다.** `domain/schema/*.ts` 를 고치고 `gaon db migrate`
+하면 diff 가 차이를 계산해 반영한다. 여기에 **손작성 마이그레이션 파일**이
+1급으로 합쳐진다(결정 39 · 합성형): `migrate` 는 ① `db/migrations/*.ts` 를
+**파일명 순으로 실제 실행**(replay)하고, ② 그 뒤 스키마 diff 로 나머지를
+적용한다.
+
+- **손작성 마이그는 `db/migrations/<파일명>.ts`** 에 두고 `up(db)`·`down(db)`
+  (Kysely) 를 export 한다. **파일명이 곧 버전 키** — `0001_add_posts.ts`
+  시퀀스든 `20260724_add_posts.ts` 타임스탬프든 사전순 정렬이 안정적이면 된다
+  (naming = `timestamp_action`). `down()` 은 롤백(`migrate down`)용 —
+  없으면 그 파일은 롤백할 수 없다(migrate down 이 §7.5.3 안내로 알림).
+  ```ts
+  import type { Kysely } from 'kysely'
+  export async function up(db: Kysely<any>): Promise<void> {
+    await db.schema.alterTable('posts').addColumn('pinned', 'boolean', (c) => c.notNull().defaultTo(false)).execute()
+  }
+  export async function down(db: Kysely<any>): Promise<void> {
+    await db.schema.alterTable('posts').dropColumn('pinned').execute()
+  }
+  ```
+- **데이터 이전(백필)·복잡한 수동 DDL** 처럼 스키마 diff 로 표현할 수 없는
+  변경은 이 손작성 파일로 둔다 — 이제 migrate 가 **실제로 실행**한다(재현·
+  리뷰 가능). 이력(`_gaon_migrations`)에 파일별 한 행이 남아 재실행 시
+  건너뛴다(중복 방지).
+- **migrate 는 스키마에 없는 테이블을 자동 DROP 하지 않는다**(replay·외부
+  테이블 보호 · 자동 apply 의 데이터 손실 배제). 테이블 제거는 손작성 마이그의
+  `down`(또는 명시적 마이그)으로 한다. `gaon db diff` 는 dropTable 을 계속
+  미리 보여주고, migrate 는 건너뛴 테이블을 크게 알린다(조용한 무시 방지).
+- 마이그레이션은 커넥션별로 돈다(§7 · `--db <키>`).
+
+## 정본 예시
+
+```ts
+// 목록 + 필터 + 정렬 — 대표 패턴
+const posts = await Post
+  .where('published', '=', true)
+  .where('authorId', 'in', [1n, 2n, 3n])
+  .orderBy('createdAt', 'desc')
+  .limit(20)
+  .all()
+
+// 페이지네이션 (2페이지 · 20개씩)
+const page2 = await Post.latest().offset(20).limit(20).all()
+
+// 부분 문자열 검색 · OR 조합
+const found = await Post.where('title', 'like', '%gaon%').first()
+const mine = await Post.where('published', '=', true).orWhere('authorId', '=', me.id).all()
+
+// 집계
+const total = await Post.where('published', '=', true).count()   // bigint
+const hasAny = await Post.where('authorId', '=', me.id).exists() // boolean
+const views = await Post.sum('viewCount')                        // string | null (숫자 컬럼)
+
+// eager load — include 는 체인 마지막에 (N+1 방지) · 관계 4종 모두
+const withAuthor = await Post.published().latest().limit(20).include('author').all()
+withAuthor[0].author            // 로드된 행 (include 시 함수가 아니라 값)
+
+// 역방향도 같은 자리 — 여러 관계를 한 번에, 관계당 쿼리 1회
+const feed = await Post.published().include('author', 'comments', 'tags').limit(20).all()
+feed[0].comments[0].body        // hasMany → 배열
+feed[0].tags.map((t) => t.name) // belongsToMany → 배열 (피벗 조인 1회)
+
+// 관계 개수 — withCount 는 조인이 아니라 서브쿼리라 limit 과 함께 정확
+const list = await Post.include('author').withCount('comments').latest().limit(20).all()
+list[0].commentsCount           // bigint · list[0].author 와 한 체인에
+
+// 그룹 집계 — 결과는 Rec 이 아니라 `그룹 키 + 집계값` 행
+const byAuthor = await Post.groupBy('authorId').orderBy('count', 'desc').count()
+byAuthor[0]                     // { authorId: bigint, count: bigint }
+const active = await Post.groupBy('authorId').having('count', '>', 5).count()
+
+// 조인 — 필터·정렬 수단, 반환은 자기(posts) Rec (users 컬럼은 안 실림)
+const teamPosts = await Post
+  .join('users', 'users.id', 'posts.authorId')
+  .where('users.name', '=', 'alice')
+  .distinct()
+  .all()
+// users.email 까지 뽑아야 하면 → §5 Post.query() 탈출구
+
+// 지연 호출 — 한 건만 필요할 때 (loop 안에서 쓰면 N+1 · doctor 가 잡는다)
+const post = await Post.find(id)
+const comments = await post.comments()   // Row[]
+const cover = await post.cover()         // Row | undefined (hasOne)
+
+// 부분 컬럼
+const titles = await Post.pluck('title')               // string[]
+const slim = await Post.select(['id', 'title']).all()  // Pick<Row, 'id' | 'title'>[]
+
+// 삭제 — 단건은 레코드, 벌크는 deleteAll (M2C)
+const post = await Post.find(id)
+await post.delete()
+const removed = await Post.where('published', '=', false).deleteAll()   // bigint
+const touched = await Post.where('authorId', '=', me.id).updateAll({ published: true })
+
+// 벌크 삽입·UPSERT — 루트 전용 (M2F · 결정 35)
+const seeded = await Post.batchInsert(rows)          // 단일 INSERT 문 · Rec[] (순서 보존)
+const fresh = await Post.insertOrIgnore(rows)         // 충돌 건너뜀 · 실 삽입만
+await Post.upsert(rows, { onConflict: 'slug', update: ['title', 'body'] })
+await Post.upsert({ id, title, body })                // onConflict 생략 = 기본 키(id)
+```
+
+## 알려진 함정
+
+- **체이닝 표 밖 메서드 추측 금지** — `destroy`·`findBy`·`paginate`·
+  `order`·해시 인자 `where({...})` 는 없다. 단건 삭제는 `rec.delete()`,
+  벌크는 `deleteAll()` (결정 31).
+- **`find(id)` 는 없으면 throw** — undefined 를 원하면
+  `where('id', '=', id).first()`.
+- **관계 대상은 문자열 테이블명** — 모델 객체를 넘기면 순환 참조.
+- **불규칙 복수**(`people`·`media` 등)는 단수화 관례가 못 잡는다 —
+  `foreignKey`/`otherKey` 를 명시한다.
+- **`updateAll`/`deleteAll` 에 limit·offset·orderBy 가 걸려 있으면 throw** —
+  행을 좁히려면 `pluck('id')` → `whereIn('id', ids)`.
+- **loop 안 관계 lazy 호출 = N+1** — doctor **n-plus-one** 검사가 잡는다.
+  목록은 `include()` 로.
+- **스키마 파일명은 camelCase** — 테이블 `posts_tags` → 파일 `postsTags.ts`
+  (파일 안 `table('posts_tags', …)` 문자열은 스네이크 그대로).
+- **잡·이벤트 발행을 트랜잭션과 정합시키려면** `afterCommit()`(service 안)
+  또는 아웃박스(`agents/async.md`) — 커밋 전 발행은 롤백 시 유령 부수효과.
+
+## 관련 결정 번호
+
+| 결정 | 내용 |
+|---|---|
+| 결정 31 | `rec.delete()` 명명(destroy 아님) · 파라미터 스코프 (M2C) |
+| 결정 33 | 관계 선언 위치(컬럼 + relations) · 문자열 테이블명 (M2D) |
+| 결정 34 | 집계·조인 그룹(groupBy·having·distinct·withCount·join) (M2E) |
+| 결정 35 | 벌크 삽입 3종(batchInsert·insertOrIgnore·upsert) (M2F) |
+| 결정 39 | 마이그레이션 합성형(파일 replay → 스키마 diff · no-auto-drop) |
+| E-4 | 컬럼 타입·수식어·체이닝 확장 · `Post.query()` 정정 · Serialized 명명 |