@gaonjs/cli 0.42.2 → 0.43.0

package/dist/commands/test.js

@@ -2,14 +2,14 @@
  * @gaonjs/cli · `gaon test` — vitest wrapper (M9-G · v0.15 §13.5)
  *
  * The One Way — 하나의 명령이 vitest 를 얇게 감싼다. 사용자는
- * `gaon test` 로 전체를, `gaon test posts` 로 필터를, `gaon test --unit`
+ * `gaon test` 로 전체를, `gaon test posts` 로 필터를, `gaon test --scope unit`
  * 으로 단위만 실행한다. 나머지는 전부 vitest 에 그대로 위임 — 우리가
  * 관례를 재발명하지 않는다.
  *
- * 스코프 필터(§9 실 인프라 관례):
- *   --unit         *.test.ts (통합 제외)
- *   --integration  *.integration.test.ts 만
- *   (기본)         둘 다 실행
+ * 스코프 필터(§9 실 인프라 관례 · `--scope <값>`):
+ *   --scope unit         *.test.ts (통합 제외)
+ *   --scope integration  *.integration.test.ts 만
+ *   --scope all / (기본)  둘 다 실행
  *
  * 실행 경로 우선순위:
  *   1) 사용자 package.json 의 `test` 스크립트가 있으면 `<pm> run test`(결정 170 ·

package/dist/db/reset.js

@@ -10,7 +10,7 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { sql } from 'kysely';
-import { snapshotFromDb, MIGRATIONS_TABLE } from '@gaonjs/data';
+import { snapshotFromDb, orderTableDropsByFk, MIGRATIONS_TABLE } from '@gaonjs/data';
 import { resolveDbTarget } from './resolve.js';
 import { runDbMigrate } from './migrate.js';
 import { runDbSeedCommand } from '../db.js';
@@ -71,7 +71,8 @@ export async function runDbReset(opts) {
         // 현재 DB 스냅샷 — 지울 테이블 목록. dialect.introspect 는 이미
         // _gaon_migrations 를 제외하지만, reset 은 이력도 지워야 하므로 별도 처리.
         const snapshot = await snapshotFromDb(target.db, target.dialect);
-        const userTables = Object.keys(snapshot).sort();
+        // FK 역순(자식 먼저)으로 정렬해 mysql(CASCADE 없음) 다중 drop 이 FK 위반 없이 돌게 한다(F4 · 결정 275).
+        const userTables = orderTableDropsByFk(snapshot, Object.keys(snapshot).sort());
         // dry-run: 무엇을 지울지·만들지를 계산해 출력. 실제 파괴는 안 함.
         if (opts.dryRun) {
             const dropSqls = userTables.map((t) => target.dialect.dropTable(t));
@@ -93,15 +94,24 @@ export async function runDbReset(opts) {
             };
         }
         else {
-            // DROP ALL — 이력 테이블도 함께. 순서: 외래키 참조 대상이 나중에 지워지도록
-            // dialect.dropTable 이 CASCADE 를 붙인다(postgres). mysql 은 SET FOREIGN_KEY_CHECKS
-            // 우회가 필요하지만, 스키마 대상 테이블만 다루므로 대체로 안전.
-            for (const t of userTables) {
-                await sql.raw(target.dialect.dropTable(t)).execute(target.db);
-                droppedTables.push(t);
+            // DROP ALL — 이력 테이블도 함께. pg 는 dropTable 이 CASCADE, mysql 은 CASCADE 가 없어
+            // FK 역순 정렬(위 orderTableDropsByFk)로 안전하게 지운다. 순환 FK 방어로 mysql 은
+            // FOREIGN_KEY_CHECKS 를 잠시 끈다(F4 · 결정 275).
+            const isMysql = target.dialect.name === 'mysql';
+            if (isMysql)
+                await sql.raw('set foreign_key_checks = 0').execute(target.db);
+            try {
+                for (const t of userTables) {
+                    await sql.raw(target.dialect.dropTable(t)).execute(target.db);
+                    droppedTables.push(t);
+                }
+                // 이력 테이블 삭제 — 존재하지 않아도 에러 없게.
+                await sql.raw(`drop table if exists ${MIGRATIONS_TABLE}`).execute(target.db);
+            }
+            finally {
+                if (isMysql)
+                    await sql.raw('set foreign_key_checks = 1').execute(target.db);
             }
-            // 이력 테이블 삭제 — 존재하지 않아도 에러 없게.
-            await sql.raw(`drop table if exists ${MIGRATIONS_TABLE}`).execute(target.db);
         }
     }
     finally {

package/dist/db/resolve.js

@@ -128,6 +128,13 @@ export async function resolveDbTarget(opts) {
             `  등록된 키: ${known.length ? known.join(', ') : '(없음)'}\n` +
             `  → gaon.config.ts 의 db.${dbKey} 를 선언하고 다시 실행하세요.`);
     }
+    // 결정 279(§7.4): 문서형(mongodb) 커넥션은 마이그레이션이 없다 — SQL 전용 경로(diff/migrate/
+    // introspect)로 흘리지 않고 명확히 안내한다. 몽고 인덱스는 Mongoose 스키마 선언으로 관리한다.
+    if (connCfg.adapter === 'mongodb') {
+        throw new Error(`[gaon db] 커넥션 '${dbKey}' 은 문서형(mongodb)입니다 — 문서형은 마이그레이션이 없습니다(§7.4).\n` +
+            `  → 몽고 인덱스는 Mongoose 스키마 선언(index:true / schema.index())으로 관리합니다(dev 자동 ensureIndexes).\n` +
+            `  → gaon db diff/migrate 는 SQL 커넥션(postgres·mysql)에만 실행하세요.`);
+    }
     const db = createDb(connCfg);
     registerConnection(dbKey, db, connCfg.adapter);
     const dialect = dialectFor(connCfg.adapter);

package/dist/doctor/schema-relations.js

@@ -13,12 +13,16 @@
 // belongsTo 를 검출할 수 있다(resolve.ts scanTables 는 단일 dbKey 로 거르므로 부적합).
 import { existsSync } from 'node:fs';
 import { join, relative } from 'node:path';
-import { scanSchemaDir, checkCrossConnectionRelations, checkRelationTargets, } from '@gaonjs/data';
+import { scanSchemaDir, checkCrossConnectionRelations, checkRelationTargets, checkPartitions, } from '@gaonjs/data';
 import { registerTsResolve } from '../tsResolve.js';
 /** TableDef 판별 — scanSchemaDir 이 준 모듈 네임스페이스에서 table() 산출만 고른다. */
 function isTableDef(v) {
     return (typeof v === 'object' &&
         v !== null &&
+        // 결정 279(§4.3·§6.2): 문서형 collection() 산출(__gaonKind)은 크로스커넥션 관계 로드에서
+        // 제외한다 — SQL↔문서형 belongsTo/hasMany 는 애초에 관계 그래프에 오르지 않는다(추가 코드
+        // 없이 격리 · generator.ts isTableDef 와 동일 판별).
+        !('__gaonKind' in v) &&
         'name' in v &&
         'defs' in v &&
         'db' in v &&
@@ -108,6 +112,7 @@ export async function checkSchemaRelations(cwd) {
     const diags = [
         ...checkCrossConnectionRelations(tables),
         ...checkRelationTargets(tables),
+        ...checkPartitions(tables), // 결정 277 — 파티션 키 컬럼 존재 검사
     ];
     const issues = diags.map((d) => toCheck(d, fileOf, ownerOf(d.message)));
     return { rule: 'schema-relations', issues };

package/dist/mcp/tools.js

@@ -201,6 +201,7 @@ export async function getSchemaTool(args, cwd) {
             index: t.constraints.index,
             check: t.constraints.check,
         },
+        partitionBy: t.partitionBy ? { strategy: t.partitionBy.strategy, columns: [...t.partitionBy.columns] } : undefined,
     }));
     const lines = [];
     if (tables.length === 0) {
@@ -231,10 +232,23 @@ export async function getSchemaTool(args, cwd) {
             const chk = t.constraints.check ?? [];
             if (uniq.length > 0)
                 lines.push(`  unique: ${uniq.map((u) => `[${u.join(', ')}]`).join(', ')}`);
+            // 인덱스 원소는 문자열 배열(btree) 또는 method/partial/표현식 객체(결정 273).
             if (idx.length > 0)
-                lines.push(`  index:  ${idx.map((u) => `[${u.join(', ')}]`).join(', ')}`);
+                lines.push(`  index:  ${idx
+                    .map((u) => {
+                    if (Array.isArray(u))
+                        return `[${u.join(', ')}]`;
+                    const o = u;
+                    const target = o.expr ?? `[${(o.cols ?? []).join(', ')}]`;
+                    const usingSfx = o.using ? ` using ${o.using}` : '';
+                    const whereSfx = o.where ? ` where ${o.where}` : '';
+                    return `${target}${usingSfx}${whereSfx}`;
+                })
+                    .join(', ')}`);
             if (chk.length > 0)
                 lines.push(`  check:  ${chk.map(([n]) => n).join(', ')}`);
+            if (t.partitionBy)
+                lines.push(`  partition: ${t.partitionBy.strategy} (${t.partitionBy.columns.join(', ')})`);
         }
         lines.push('');
         lines.push(`총 ${tables.length}개 테이블`);

package/dist/templates/project/AGENTS.md.tpl

@@ -115,7 +115,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
 
 1. `response-mixing` — 한 액션 안 render/JSON/redirect 혼용 (E-3)
 2. `n-plus-one` — include 미사용 · loop 안 관계 호출 (E-4)
-3. `dependency-direction` — 의존 방향 4규칙 위반
+3. `dependency-direction` — 의존 방향 4규칙 위반 (domain→shared 를 값으로 import 한 경우만 `--fix` 지원 = `import`→`import type` AST 삽입 · 나머지 방향(domain→app·app→app·shared→app)은 파일 위치 판단이 필요해 수동 · `doctor/fixers/dependency-direction`)
 4. `connections` — 스키마·`getConnection` 이 쓰는 커넥션 키가 `gaon.config.ts` 에 등록됐는지 · db 설정 정적 분석(삼항·`??` 지원 · 못 읽으면 안내) (§4.5 · 결정 135)
 5. `migration-diff` — 스키마 vs DB 상태 불일치
 6. `shared-purity` — shared/ 전체(.ts·.vue)가 `api`/`pageProps`·domain 값을 import (컴포저블·컴포넌트 통일 · 결정 25·217)
@@ -137,7 +137,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
 22. `page-layout-breakpoint` — 페이지 파일이 레이아웃 브레이크포인트(`sm:flex-row`·`md:grid-cols-2` 등)를 직접 사용(반응형은 UI 킷 블록이 책임 · `PageShell` 등으로 감싸라 · 킷에 없는 표현이면 그대로 둬도 됨 · 표시/타이포/여백 반응형은 오탐 방지로 제외) (결정 107 · 안내 경고)
 23. `link-button-nesting` — `<Link><Button>…</Button></Link>` 이중 감싸기(`<a><button>` 중첩 · HTML 비준수·접근성 결함 · 버튼 모양 링크는 `<Button href="…">` 한 표면을 쓰라 · Link 직계 자식 Button 만 검출) (결정 113 · 경고)
 24. `seal-security` — `@gaonjs/seal` 을 켠 앱에서 (a) `gaon.config.ts` 가 진짜 방어층(rate limit·보안 헤더·CORS)을 **명시적으로 껐을** 때 = 봉인을 켜고 방어를 끄는 역전 **경고**, (b) `main.ts` 가 seal 클라이언트를 배선(`@gaonjs/seal/client` 정적 import + `createGaonApp` sealClient)하지 않았을 때 = 봉인 문서를 브라우저가 못 열어 blank 가 되는 **에러**(`gaon doctor --fix --yes` 의 `seal-client-wiring` fixer 가 자동 배선). seal 은 서버 검증을 대체하지 않는다 (결정 121·124 · `agents/seal.md`)
-25. `schema-relations` — 커넥션을 가로지르는 belongsTo·역방향 관계(SQL 조인이 커넥션을 못 넘음)와 존재하지 않는 관계 대상 = **에러**(§4.5). data 패키지 검사(`checkCrossConnectionRelations`·`checkRelationTargets`)를 CLI 러너가 배선 — 배포 후 raw postgres 에러 대신 doctor 가 잡는다 (결정 134 · `agents/data.md`)
+25. `schema-relations` — 커넥션을 가로지르는 belongsTo·역방향 관계(SQL 조인이 커넥션을 못 넘음)와 존재하지 않는 관계 대상 = **에러**(§4.5). **파티션 키 컬럼이 실제 컬럼인지도 검사**(결정 277 · `checkPartitions` — 오타·유령 컬럼). data 패키지 검사(`checkCrossConnectionRelations`·`checkRelationTargets`·`checkPartitions`)를 CLI 러너가 배선 — 배포 후 raw postgres 에러 대신 doctor 가 잡는다 (결정 134·277 · `agents/data.md`)
 26. `no-import-meta-env` — `.vue`(SFC) `<script>` 에서 `import.meta.env` 직접 사용 = **에러**. SFC 는 nodenext 아래 CommonJS 출력으로 분류돼 vue-tsc 가 TS1470 로 거부한다(`gaon check` red). 클라 공개 환경변수는 `import { env } from 'gaonjs/vue'` 로 읽으라(VITE_* 접두 제거·타입드 · `.gaon/env.d.ts` 는 `.env` 스캔 생성) — 템플릿 프로즈·주석의 언급은 오탐 제외 (결정 198 · `agents/frontend.md` §9)
 27. `locale-parity` — `locales/` 의 로케일 간 키 부분 누락 = **경고**. 어떤 키가 특정 로케일에만 빠지면 `messages.d.ts`(기준 로케일 기준)는 컴파일을 통과하고, 런타임에 그 로케일 사용자는 fallback(대개 다른 언어) 번역을 조용히 본다. 검사가 로케일 간 키 diff 를 계산해 빠진 파일·키를 짚는다(`--json` 은 `detail.missing` 으로 구조화). 로케일이 0·1개면 무소음 (결정 216 · `agents/i18n.md`)
 
@@ -210,7 +210,7 @@ gaon doctor       # 정적 검사 27종 (§2.2)
 | `gaon new <name>` | 프로젝트 스캐폴드 |
 | `gaon dev` | 통합 개발 오케스트레이션 (Docker·`.gaon` 재생성·**serve·work·hub 자동 기동**·**코드 변경 감시·재시작** · 결정 211) |
 | `gaon serve` / `work` / `hub` | 운영 프로세스 3종 (웹 · 워커 · 실시간 허브) — **감시 없음** · 배포 배치용(`gaon dev` 가 개발 중엔 셋을 내장 기동) · 웹은 `PORT`, 허브는 `GAON_HUB_PORT` |
-| `gaon g <type> <name>` | 스캐폴드: `auth`·`ui-kit`·`controller`·`model`·`page`·`job`·`app` |
+| `gaon g <type> <name>` | 스캐폴드: `auth`·`ui-kit`·`controller`·`model`·`page`·`job`·`app` · `g auth --app <앱> --public` = 비-web 앱에 공개 회원가입(`/registration/new`)을 opt-in(기본: web=공개·비-web=역할 게이트 · 결정 155) |
 | `gaon gen` / `build` | `gen` = `.gaon` 타입 브리지 + api() 런타임 매니페스트만 재생성(서버·검사 없이) · `build` = 멀티 앱 프론트 프로덕션 빌드(`gaon gen` + `apps/*` 순회 · 앱별 `dist/<앱>`·base=`/<앱>/`) · 결정 127·146 |
 | `gaon db <sub>` | `diff`·`migrate`(`down`)·`status`·`reset`·`seed` (`agents/data.md` §10) |
 | `gaon check` / `test` / `doctor` | 검증 루프 |
@@ -242,6 +242,7 @@ gaon doctor       # 정적 검사 27종 (§2.2)
 | 패키지 | 역할 |
 |---|---|
 | `gaonjs` | 파사드(설치 단위) · CLI `gaon` |
+| `create-gaon` | `npm create gaon <name>` 진입점 · `gaon new` 에 위임 |
 | `@gaonjs/cli` | 제너레이터·스캐폴딩·명령 라우팅 |
 | `@gaonjs/data` | 스키마 DSL · 모델 · 마이그레이션 |
 | `@gaonjs/config` | `gaon.config.ts`·`app.config.ts` |

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

@@ -79,9 +79,12 @@ await SendWelcomeMail.at(someDate, user.id) // 특정 시각 실행
 - **시그니처** — `job(handler, options?)`. 첫 인자는 평범한 async
   함수(`(...args) => Promise<void> | void`) — `defineJob` 이나
   `{ perform }` 객체 형태가 아니다.
-- **이름** — `options.name` 으로 명시하거나, 생략하면 `domain/jobs/`
-  파일 로더가 **파일명**으로 채운다(`assignName`). 이름을 얻기 전까지
-  `.later()` 등을 호출하면 에러 — 파일로 두거나 `name` 을 직접 준다.
+- **이름** — `job()` 이 **정의 시점에 스스로** 이름을 잡는다: `options.name` 이
+  있으면 그것, 없으면 자신을 정의한 **파일의 파일명**을 스택에서 유추한다
+  (`inferNameFromCaller`). 그래서 `domain/jobs/` 파일에 두기만 하면 로더를 기다리지
+  않고 곧바로 `.later()` 를 호출할 수 있다. `domain/jobs/` 파일 로더의 `assignName`
+  은 폴백일 뿐(이미 이름이 있으면 멱등). 스택에서 파일명을 못 얻는 특수 환경에서만
+  `options.name` 을 명시한다(이름을 못 얻은 채 발행하면 에러).
 - **파일당 잡 하나(결정 271)** — 같은 파일에 `job()` 을 둘 이상 두면 파일명
   유추가 충돌한다. 이제 **등록 시 throw**(조용한 덮어쓰기 = 발행이 엉뚱한
   핸들러로 가던 무신호 버그 봉합) — 각각 `name` 을 다르게 주거나 파일을 나눈다.

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

@@ -147,24 +147,71 @@ import 하면 순환 참조가 생기므로, 실제 연결은 부팅 시 프레
   — 단 레코드를 손으로 재구성하거나 JSON 왕복하면 마커가 사라지니 그럴 땐 hidden
   컬럼을 직접 넣지 않는다.
 - `.unique()` — 컬럼 레벨 UNIQUE 제약 (E-4).
-- `.index()` — 컬럼 레벨 인덱스 (E-4).
+- `.index()` — 컬럼 레벨 인덱스 (E-4). 옵션 객체로 method·partial 지정 (결정 273):
+  - `.index()` — 기본 인덱스. **jsonb 컬럼은 자동 gin**(유연 검색 `@>`·`?` 용 · The One Way), 그 외는 btree.
+  - `.index({ using: 'brin' })` — 시계열 정렬 컬럼(예: `createdAt`)에 관례로 BRIN.
+  - `.index({ where: "status = 'active'" })` — partial(부분) 인덱스.
+  - method 집합 = `btree | gin | brin | gist`. **jsonb→gin 자동은 컬럼 `.index()` 한 곳뿐** —
+    brin/gist 는 명시(과유도가 perpetual-diff 를 늘림). **`t.jsonb()` 도 `.index()` 를 가진다**(결정 273 신설).
 - `.check(expr)` — 컬럼 레벨 CHECK 제약 (E-4).
 
-**테이블 레벨 복합 제약** (E-4 §4.2):
+**테이블 레벨 복합 제약** (E-4 §4.2 · 인덱스 객체 확장 결정 273):
 
 ```ts
-export const posts = table('posts', {
-  slug: t.string().max(100),
-  ownerId: t.belongsTo('users'),
+export const logs = table('logs', {
+  userId: t.belongsTo('users'),
+  status: t.enum(['active', 'archived'] as const),
+  createdAt: t.datetime(),
+  meta: t.jsonb<Record<string, unknown>>().index(),   // 자동 gin
   ...t.timestamps(),
 }, {
-  db: 'main',                              // 커넥션 키 (§7)
-  unique: [['ownerId', 'slug']],           // 복합 unique
-  index: [['ownerId', 'createdAt']],       // 복합 index
-  check: [['positive_age', 'age > 0']],    // [name, expr]
+  db: 'main',                                          // 커넥션 키 (§7)
+  unique: [['userId', 'status']],                      // 복합 unique
+  index: [
+    ['userId', 'createdAt'],                           // 복합 btree(문자열 배열 = 기존과 동일)
+    { cols: ['meta'], using: 'gin' },                  // jsonb GIN
+    { cols: ['createdAt'], using: 'brin' },            // 시계열 BRIN
+    { cols: ['status'], where: "status = 'active'" },  // partial
+    { expr: "(meta->>'tenant')" },                     // 표현식 인덱스(이름 자동 · 해시)
+  ],
+  check: [['positive_age', 'age > 0']],                // [name, expr]
+})
+```
+
+- 인덱스 원소가 **문자열 배열**이면 기존과 100% 동일(btree). **객체**면 `cols`·`expr`·`using`·`where`·`name`.
+- 프레임웍이 만든 인덱스는 **`idx_` 접두**만 관리한다 — raw(수동 튜닝) 인덱스는 diff 가 건드리지
+  않으니(drop 계획 안 함), 손수 만든 특수 인덱스는 `idx_` 아닌 이름으로 둔다.
+- **MySQL/MariaDB(legacy §4.5) 커넥션은 gin/brin/gist·partial·표현식 인덱스가 없다** — 선언하면
+  `gaon db migrate` 가 **명확히 실패**한다(조용히 btree 로 떨구지 않음). 이런 인덱스는 main(postgres)에.
+
+**선언적 파티셔닝** (결정 277 · PostgreSQL · 대용량 로그/이벤트/감사):
+
+```ts
+export const logs = table('logs', {
+  id: t.id(),
+  createdAt: t.datetime(),
+  meta: t.jsonb<Record<string, unknown>>().index(),      // 자동 gin
+}, {
+  partitionBy: { strategy: 'range', columns: ['createdAt'] },  // 부모만 선언
 })
 ```
 
+- 전략은 `range | list | hash`. **부모 테이블만 선언**한다 — 파티션 키는 PK 에 자동 편입된다
+  (복합 PK `(id, createdAt)`). 개별 **자식 파티션은 스키마 밖**(시간에 따라 증식)이라 헬퍼로 관리한다:
+  ```ts
+  // domain/schedule.ts — 크론 잡으로 명시 실행(자동 마법 없음)
+  import { rollMonthlyPartitions } from 'gaonjs/data'
+  await rollMonthlyPartitions(db, { table: 'logs', ahead: 1, keep: 6 })
+  // ahead=다가올 개월 미리 생성 · keep=6 이면 6개월 지난 파티션 파기(keep 없으면 파기 안 함)
+  ```
+  저수준 헬퍼: `createRangePartition`·`createListPartition`·`createHashPartition`·`createDefaultPartition`·
+  `dropPartition`·`listPartitions`. **retention(오래된 파티션 파기)은 절대 자동으로 하지 않는다** —
+  `keep` 을 명시하고 그 잡을 실행할 때만 지운다(결정 39 자동 DROP 금지 정신).
+- MySQL/MariaDB 커넥션은 선언적 파티셔닝을 지원하지 않는다(migrate 시 fail-loud).
+
+**`t.timestamps()` 와 `update()`** (결정 276): `update()` 는 `updatedAt` 을 **자동으로 현재 시각으로
+갱신**한다(patch 에 `updatedAt` 을 직접 주면 그 값을 존중). 값 변경 없이 시각만 올리려면 `touch()`.
+
 ### 4. 체이닝 전체 (`packages/data/src/model.ts`)
 
 체이닝 표면은 아래 표가 **전부**다. 표에 없는 메서드
@@ -185,7 +232,7 @@ export const posts = table('posts', {
 | 메서드 | 시그니처 | 반환 | 비고 |
 |---|---|---|---|
 | `where` | `(col, op, val?)` | `Chain` | op 에 따라 val 형태 강제 (위 표) |
-| `whereIn` | `(col, vals)` | `Chain` | `where(col, 'in', vals)` 축약 |
+| `whereIn` | `(col, vals)` | `Chain` | `where(col, 'in', vals)` 축약. **빈 배열(`[]`)은 단락**(결정 99) — 단독이면 DB 무접촉으로 빈 결과(`count`=0·`exists`=false), 다른 조건과 `or` 로 섞이면 `1 = 0` 으로 상수 폴딩(`in ()` 문법 오류 방지) |
 | `whereAny` | `(cols, op, val?)` | `Chain` | **여러 컬럼에 같은 조건을 OR 로 묶어 괄호로 감쌈** = `(c1 op v OR c2 op v)` · 앞선 where 와 **AND 로 안전 결합**(결정 118). 다중 컬럼 검색의 정본 — `orWhere` 로 흩뜨리면 앞 조건이 샌다(아래 함정) |
 | `orWhere` | `(col, op, val?)` | `Chain` | op 12종 전부 (M2C) · 결합은 `(a AND b) OR c` (Rails 관습). **다중 컬럼 검색엔 쓰지 말 것** — `whereAny` 를 쓴다(결정 118) |
 | `orderBy` | `(col, dir?)` | `Chain` | dir 기본 `'asc'` · 호출마다 누적 (다중 정렬) · 정렬 뒤 PK 타이브레이커 자동 부가(결정 110) |
@@ -203,9 +250,9 @@ export const posts = table('posts', {
 | `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<number>` | **벌크 갱신** (M2C) — where 조건만 반영 · 영향 행 수(number · 결정 90). limit·offset·orderBy 가 걸려 있으면 **throw** (Postgres `UPDATE ... LIMIT` 미지원 — 행을 좁히려면 `pluck('id')` → `whereIn('id', ids)`) |
+| `updateAll` | `(patch)` | `Promise<number>` | **벌크 갱신** (M2C) — where 조건만 반영 · 영향 행 수(number · 결정 90). limit·offset·orderBy·**distinct** 가 걸려 있으면 **throw** (Postgres `UPDATE ... LIMIT` 미지원 — 행을 좁히려면 `pluck('id')` → `whereIn('id', ids)`) |
 | `deleteAll` | `()` | `Promise<number>` | **벌크 삭제** (M2C) — 규칙은 updateAll 과 동일. 빈 where = 전체 삭제 (이름이 위험을 드러냄) |
-| `incrementAll` | `(field, by?=1)` | `Promise<number>` | **원자 벌크 증가**(결정 115) — `SET col = col + by` 한 문장 · 수치 컬럼 · 영향 행 수(number). 벌크 계약(limit/offset/orderBy 있으면 throw)은 updateAll 과 동일 |
+| `incrementAll` | `(field, by?=1)` | `Promise<number>` | **원자 벌크 증가**(결정 115) — `SET col = col + by` 한 문장 · 수치 컬럼 · 영향 행 수(number). 벌크 계약(limit/offset/orderBy/distinct 있으면 throw)은 updateAll 과 동일 |
 | `decrementAll` | `(field, by?=1)` | `Promise<number>` | **원자 벌크 감소**(결정 115) — `SET col = col - by`. incrementAll 의 대칭 |
 
 **집계·조인 그룹** (`Chain` · M2E · 결정 34):
@@ -214,7 +261,7 @@ export const posts = table('posts', {
 |---|---|---|---|
 | `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)` |
+| `distinct` | `()` · `(col \| col[])` | `Chain` · `SelectChain` | 인자 없으면 `SELECT DISTINCT` 전체 행(읽기 집계 이어짐), 컬럼을 주면 그 컬럼만 뽑는 `SelectChain`. `distinct().count()` 는 `count(distinct id)`. **벌크 쓰기로는 이어지지 않는다** — distinct 걸린 체인의 `updateAll`/`deleteAll` 등은 throw(위 벌크 계약) |
 | `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()`). **자기 테이블 컬럼은 한정 없이 그대로** 쓴다 — `t.timestamps()`·`t.id()` 로 양 테이블이 `createdAt`·`id` 를 공유해도 조인 시 자기 테이블로 자동 한정돼 `where('createdAt', ..)` 가 안전하다(ambiguous column 방지). **조인 테이블** 조건만 한정 이름(`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')` |
@@ -304,7 +351,8 @@ methods: {
 - `groupBy` 이후는 `GroupChain` — 결과가 그룹 행이라 `first`/`all` 대신
   집계 함수가 종단이고, 레코드가 아니라 `include`·`select` 도 없다.
 - `join`/`leftJoin` 이후는 `JoinChain` — 반환은 자기 Rec 이라 `include`·집계 그룹은
-  없지만 `where`/`whereAny`/`orWhere`/`orderBy`/`distinct`/`limit`/`offset`·스칼라 집계·
+  없지만 `where`/`whereAny`/`orWhere`/`orderBy`/`distinct`/`limit`/`offset`·스칼라 집계는
+  **`count`·`exists` 두 종만**(sum/avg/min/max 는 JoinChain 에 없다 — 필요하면 §5 `Post.query()`)·
   `select`(자기 컬럼)·`pluck`·`first`/`all`/**`paginate`** 는 이어진다. 그래서 **텍스트
   검색(whereAny)+관계 필터(join)+페이지네이션을 한 체인으로** 조립할 수 있다(읽기 조합).
 - `select()` 이후엔 `include` 도 없다 (부분 행에 관계를 붙이지 않는다).
@@ -397,6 +445,73 @@ export const PlaceOrder = service(async (input: { userId: string; total: number
 - **왜 `afterCommit`** — main 이 롤백되면 analytics 기록도 일어나지 않아야 한다.
   `afterCommit` 은 커밋이 성공한 경우에만 콜백을 돈다(§9 · `agents/async.md`).
 
+### 7.1 문서형 컬렉션 — `collection()` (v1.1 · `@gaonjs/adapter-mongo` · 결정 278~282)
+
+SQL `model()`(Kysely) 옆에 문서형 동사 `collection()` 을 **Mongoose** 위에 둔다.
+로그·이벤트·감사·분석처럼 **문서·유연 스키마·대량 append** 용도다. **`model()` 은
+SQL 전용 · `collection()` 은 문서형** — 한 동사가 두 세계를 처리하지 않는다(The One Way).
+
+문서형은 **opt-in 설치**다(SQL 전용 프로젝트는 mongoose 를 받지 않는다):
+
+```bash
+npm i @gaonjs/adapter-mongo mongoose
+```
+
+```ts
+// domain/schema/auditLog.ts — mongoSchema() 는 진짜 Mongoose Schema 를 반환한다.
+import { collection, mongoSchema } from 'gaonjs/data'
+
+const auditLogSchema = mongoSchema({
+  actorId: { type: String, required: true, index: true },
+  action:  { type: String, required: true },
+  ip:      { type: String, hidden: true },   // 직렬화 경계 제외 (SQL .hidden() 과 동일 의미)
+}, { timestamps: true })
+
+// 순수 Mongoose 관례 — Gaon 이 메서드 DSL 을 재발명하지 않는다.
+auditLogSchema.statics.recent = function (limit: number) {
+  return this.find().sort({ createdAt: -1 }).limit(limit).lean()
+}
+
+// db: 'logs' — 몽고 커넥션 바인딩 (SQL 의 { db: 'legacy' } 와 대칭)
+export const AuditLog = collection('audit_logs', auditLogSchema, { db: 'logs' })
+```
+
+```ts
+// gaon.config.ts — 문서형 커넥션은 adapter: 'mongodb' 로 SQL 과 나란히 선언한다.
+export default defineConfig({
+  db: {
+    main: { adapter: 'postgres', url: env('DATABASE_URL') },
+    logs: { adapter: 'mongodb',  url: env('MONGO_URL') },
+  },
+})
+```
+
+**정본 규칙**:
+- **`hidden` 은 SQL 과 같은 의미** — "서버는 읽고 직렬화만 제외". `select:false` 를
+  쓰지 않는다. render props 로 흘릴 땐 **`.lean()`** 을 쓴다(정본 경로) — `_id`(ObjectId)는
+  응답 경계에서 자동으로 string 이 된다(결정 282 · 결정 37 문서형 대응).
+- **몽고 쓰기를 SQL `service()` tx 안에서 하지 말 것** — 몽고는 v1 에서 트랜잭션이
+  없어, tx 안 몽고 쓰기는 `MongoCrossConnectionWriteError` 로 **막힌다**(조용한 부분
+  커밋 방지 · 결정 281). "커밋 후 로그" 는 `afterCommit` 으로 잇는다(§7 크로스커넥션과 동일 규율):
+  ```ts
+  export const SignUp = service(async (input) => {
+    const user = await Users.create(input)                 // main(SQL) 트랜잭션
+    afterCommit(() => AuditLog.create({ actorId: String(user.id), action: 'signup' })) // 커밋 뒤 몽고 쓰기
+    return user
+  })
+  ```
+- **SQL ↔ 문서형 관계 금지** — `belongsTo`/`hasMany` 는 SQL 전용이다. 몽고 컬렉션끼리의
+  참조는 Mongoose `ref`/`populate` 로 사용자가 직접 한다(Gaon doctor 가 강제하지 않음).
+- **인덱스 = Mongoose 스키마 선언**(`index: true` / `schema.index()`) — dev 는 자동
+  `ensureIndexes`. 몽고는 마이그레이션이 없다(`gaon db diff/migrate` 는 mongo 를 건너뛴다).
+
+**알려진 함정**:
+- `aggregate` 결과는 임의 projection(그룹·계산)이라 `hidden` 마커를 심지 **않는다** —
+  SQL `Post.query()`(Kysely 원본) raw 탈출구가 hidden 을 우회하는 것과 동형. 문서를
+  안전하게 렌더에 흘리려면 `find()/findOne().lean()` 을 쓴다.
+- 인스턴스 `document.save()` 는 크로스커넥션 가드 밖이다 — 정본 쓰기는 static
+  `create/update/delete`(가드 대상). tx 안에서 쓸 일이면 `afterCommit` 으로 미룬다.
+
 ### 8. 모델 정의 (`model()`) (`packages/data/src/model.ts`)
 
 `model()` 은 스키마(§1)를 Kysely 위의 실행 가능한 API 로 감싼다 —
@@ -800,8 +915,8 @@ 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 doomed = await Post.find(id)
+await doomed.delete()
 const removed = await Post.where('published', '=', false).deleteAll()   // number
 const touched = await Post.where('authorId', '=', me.id).updateAll({ published: true })
 
@@ -820,10 +935,15 @@ await Post.upsert({ id, title, body })                // onConflict 생략 = 기
   · 결정 119). 단건 삭제는 `rec.delete()`, 벌크는 `deleteAll()` (결정 31).
 - **`find(id)` 는 없으면 throw** — undefined 를 원하면
   `where('id', '=', id).first()`.
+- **`find` 과 `where('id', …)` 의 id 타입은 비대칭** — `find(id)` 는
+  `bigint | string` 을 받는다(문자열은 그대로 드라이버에 넘긴다 · 별도 코드에서
+  `BigInt()` 강제 안 함). 반면 `where('id', '=', v)` 는 컬럼 타입 `Row['id']`(=bigint)를
+  요구해 **문자열을 넘기면 컴파일 에러**다. 라우트 파라미터(문자열)로 조회할 땐
+  `find(this.params.id)` 를 쓰거나, `where` 로는 `BigInt(this.params.id)` 로 감싼다.
 - **관계 대상은 문자열 테이블명** — 모델 객체를 넘기면 순환 참조.
 - **불규칙 복수**(`people`·`media` 등)는 단수화 관례가 못 잡는다 —
   `foreignKey`/`otherKey` 를 명시한다.
-- **`updateAll`/`deleteAll` 에 limit·offset·orderBy 가 걸려 있으면 throw** —
+- **`updateAll`/`deleteAll` 에 limit·offset·orderBy·distinct 가 걸려 있으면 throw** —
   행을 좁히려면 `pluck('id')` → `whereIn('id', ids)`.
 - **벌크 3종은 행이 아니라 `{ count }` 를 준다** (결정 90) — 반환을 `Rec[]` 처럼
   다루지 말 것. 삽입된 행이 필요하면 소량은 `create()`, 대량은 유니크 키 재조회.
@@ -885,4 +1005,12 @@ await Post.upsert({ id, title, body })                // onConflict 생략 = 기
 | 결정 119 | `paginate(page, perPage)` — 체인 종단 `{rows,total,page,pageCount,perPage}` · 클램프·개수 number 내장 · UI 킷 Pagination 정합 · 손 조립(쿼리 2회·count 캐스팅·페이지 수학)은 반정본 · GroupChain 미탑재(행 목록 전용) |
 | 결정 148 | 캐시 헬퍼 `cache.remember`/`forget`·쿼리 `.withCache(ttl)` — 명시 TTL 만 · **자동 무효화 없음**(쓰기 자동 퍼지 기각 · 조용한 stale 방지) · Redis 기본·메모리 폴백(§8.2) |
 | 결정 153 | `Model.form` 컬럼 제약(`.max`·enum) 쓰기 전 서버측 검증 → 422(폼 에러) · DB 제약 위반 raw 500 방지(§8.1 · `this.params`) |
+| 결정 220 | 마이그레이션 diff 확장 — 기존 컬럼의 `.unique()`·`.index()`·`.default()`·`.check()` 추가/제거를 diff 로 잡음(§10) |
+| 결정 221 | 크로스 커넥션 트랜잭션 런타임 가드 — tx 안 다른 커넥션 **쓰기**(INSERT/UPDATE/DELETE) throw · **읽기는 예외** · 중첩 서비스/afterCommit/tx:false 는 자기 경계로 통과(§5 · 규칙 9) |
+| 결정 253 | hidden 마커를 **열거 가능한 심볼**로 부여 — `{ ...row }` spread·`Object.assign` 을 넘어 보존돼 우회 유출(S1) 봉합(§1) |
+| 결정 265 | 조인 시 자기 테이블 컬럼 자동 한정 — `where`/`whereAny`/`orderBy` 가 자기 테이블로 한정돼 ambiguous column 방지(§4 join) |
+| 결정 278 | 문서형 동사 `collection()`(Mongoose) — SQL `model()` 과 분리 · `mongoSchema()` 얇은 래퍼(판별 태그+hidden 전개) · `@gaonjs/adapter-mongo`(mongoose optional peer)(§7.1) |
+| 결정 279 | 문서형 커넥션 `adapter: 'mongodb'`(config `db` 맵) · `isTableDef` 가 collection 제외(tables.d.ts·doctor) · `gaon db` mongo 마이그 fail-loud(§7.1) |
+| 결정 281 | 몽고 쓰기를 SQL `service()` tx 안에서 하면 `MongoCrossConnectionWriteError` 로 막힘 — "커밋 후 로그" 는 `afterCommit`(§7.1 · 결정 221 동형) |
+| 결정 282 | ObjectId(`_id` 포함) → string 직렬화 정규화(응답 경계 · 결정 37 문서형 대응 · `.lean()` 권장)(§7.1) |
 | E-4 | 컬럼 타입·수식어·체이닝 확장 · `Post.query()` 정정 · Serialized 명명 |

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

@@ -55,6 +55,11 @@ const props = pageProps<'web:posts#index'>()
   로 서버가 번역해 흘려보낸다(`agents/i18n.md` §5 · 결정 213).
   `pageProps<K>()` 반환에도 교차되어 `props.csrf` 로도 읽히지만, 라우트 키가 필요 없는
   `useShared()` 가 정본 표면이다(임의 라우트 키를 빌려 currentUser 를 읽던 우회 트릭을 없앤다).
+  - **구조분해 금지 — `pageProps` 와 같은 함정** (`packages/vue/src/shared.ts`). `useShared()`
+    는 매 접근마다 `usePage().props` 를 다시 읽는 **Proxy** 를 돌려준다. `const { csrf } =
+    useShared()` 처럼 구조분해하면 그 순간 값을 한 번 스냅샷해 **반응성이 끊긴다**(리다이렉트·
+    partial reload 후 flash·currentUser 갱신이 안 보인다). 항상 `const shared = useShared()`
+    로 받아 `shared.csrf`·`shared.flash` 로 접근한다.
 - **파사드는 `gaonjs/vue`** — `@gaonjs/vue` (스코프)·`@inertiajs/vue3` (내부 의존)
   로 import 하지 않는다.
 - **Gaon 은 `vue-router` 를 쓰지 않는다** — 라우팅은 **Inertia = SPA + 서버
@@ -71,9 +76,19 @@ const props = pageProps<'web:posts#index'>()
   `router.visit(url)`. **외부 URL(`https://…`)·`target="_blank"` 만 `<a>`** 를
   유지한다. 내부 경로 일반 앵커는 doctor **internal-anchor** 가 잡는다(결정 96).
 - **페이지 제목 = `Head`(결정 271)** — 문서 `<title>` 은 `gaonjs/vue` 의 `Head` 로
-  설정한다: `<Head title="글 목록" />`. `createGaonApp({ title })` 조합자가 이 값을
-  받아 `글 목록 · 사이트명` 처럼 꾸민다. `document.title` 수동 조작·`@inertiajs`
-  직접 import 금지(결정 64) — 정본 표면은 `Head` 뿐이다.
+  설정한다. `createGaonApp({ title })` 조합자가 이 값을 받아 `글 목록 · 사이트명` 처럼
+  꾸민다. `document.title` 수동 조작·`@inertiajs` 직접 import 금지(결정 64) — 정본
+  표면은 `Head`(`gaonjs/vue` 재수출) 뿐이다. 페이지 `<template>` 최상단에 둔다:
+  ```vue
+  <script setup lang="ts">
+  import { Head, pageProps } from 'gaonjs/vue'
+  const props = pageProps<'web:posts#index'>()
+  </script>
+  <template>
+    <Head title="글 목록" />
+    <!-- 이하 페이지 본문 -->
+  </template>
+  ```
 - **`shared/` 밖에서만 사용** — `shared/` 안 `pageProps` 사용은 §4 대칭 표에서
   금지 (라우트를 모른다는 순수 규칙).
 

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

@@ -31,8 +31,9 @@ t('nav.home')                     // 중첩은 점 표기
 |---|---|---|
 | 번역 | `t(key, params?)` | 키는 카탈로그에서 타입 검사(아래 §4) · params 는 `{{name}}` 보간 |
 | 현재 언어 | `currentLanguage(): string` | 요청 로케일 |
-| 지원 언어 | `languages(): string[]` | 설정된 supportedLngs |
+| 지원 언어 | `languages(): readonly string[]` | 설정된 supportedLngs(읽기 전용) |
 | 고정 번역 | `runWithLanguage(lng, fn)` | fn 안의 t() 가 그 언어(메일·비요청 경로 · §mail) |
+| 고정 번역기 | `translator(lng)` | 언어를 고정한 번역 함수 `(key, params?) => string` 를 돌려준다(테스트·비요청 경로) |
 
 ### 1.5 복수형 — `count` 로 자동 선택 (i18next 규약 · 결정 181)
 
@@ -142,6 +143,7 @@ nav 라벨·레이아웃 문구처럼 앱의 **모든** 페이지가 쓰는 chro
 
 ```ts
 // apps/web/app.config.ts
+import { defineAppConfig } from 'gaonjs/config'
 import { t } from 'gaonjs/i18n'
 export default defineAppConfig({
   sharedProps: () => ({

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

@@ -10,7 +10,9 @@
 
 메일은 `domain/mails/<이름>.ts` 에 `mail()` 로 정의한다(모델·잡과 같은 함수/객체
 스타일 · 데코레이터 금지). 파일을 두면 등록이고 파일명이 곧 이름이다. build 함수는
-데이터를 받아 메시지(`to`·`subject`·`html`/`text`·`from?`)를 만든다.
+데이터를 받아 메시지(`to`·`subject`·`html`/`text`·`from?`·`cc?`·`bcc?`·`replyTo?`)를
+만든다. `to`·`cc`·`bcc` 는 `string | readonly string[]`(여러 수신자), `replyTo` 는 단일
+`string` 이다. build 함수는 동기·비동기(`async`) 둘 다 된다(`MailMessage | Promise<MailMessage>`).
 
 ```ts
 // domain/mails/welcome.ts
@@ -26,9 +28,9 @@ export const WelcomeMail = mail<{ name: string; email: string }>((u) => ({
 
 | 표면 | 시그니처 | 비고 |
 |---|---|---|
-| 정의 | `mail<T>((data) => MailMessage)` | 파일명 = 이름 |
-| 발송 | `def.deliver(data, { locale?, to? })` | 설정된 SMTP 로 보냄 |
-| 미리보기 | `def.render(data, { locale?, to? })` | 발송 없이 메시지만(테스트·미리보기) · `to` 는 `deliver` 와 대칭 |
+| 정의 | `mail<T>((data) => MailMessage \| Promise<MailMessage>)` | 파일명 = 이름 · build 는 async 가능 |
+| 발송 | `def.deliver(data, { locale?, to? }): Promise<SentInfo>` | 설정된 SMTP 로 보냄(`await`) |
+| 미리보기 | `def.render(data, { locale?, to? }): Promise<MailMessage>` | 발송 없이 메시지만(테스트·미리보기 · `await`) · `to` 는 `deliver` 와 대칭 |
 
 ### 2. 로케일 메일 — `deliver(data, { locale })` (결정 160)
 

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

@@ -60,7 +60,7 @@ export default channel({
 
 | 훅 | 시점 | 반환 |
 | --- | --- | --- |
-| `authorize(ctx)` | 소켓 attach 전 | `boolean` — false 면 연결 거부 |
+| `authorize(ctx)` | 소켓 attach 전 | `boolean \| Promise<boolean>` — false 면 연결 거부(4401 close) · async 가능 |
 | `presenceInfo(ctx)` | attach 전 | 접속자 목록에 실을 공개 메타 |
 | `onJoin(ctx)` | 연결·프레즌스 등록 후 | — |
 | `onMessage(ctx, data)` | 클라이언트 메시지 | — |
@@ -80,11 +80,15 @@ export default channel({
 
 멤버 식별자는 로그인 사용자면 `user:<id>`, 익명이면 `conn:<uuid>` 다.
 
-**핸들러가 throw 하면 그 연결만 닫힌다(결정 257).** `onMessage`/`onLeave` 안에서
-예외(코드 결함·DB 순단)가 나도 **서버는 죽지 않는다** — HTTP 액션이 500 으로
-마감되는 것과 대칭으로, 그 연결에 에러 프레임을 보내고 닫는다(다른 연결·서버는
-그대로 산다). 즉 `onMessage` 예외는 전역 장애가 아니라 연결 단위 장애다. 재시도가
-필요한 로직은 핸들러 안에서 try/catch 로 감싸 직접 통제한다.
+**핸들러가 throw 해도 서버는 죽지 않는다(결정 257).** `onMessage`/`onLeave` 안에서
+예외(코드 결함·DB 순단)가 나도 그 예외는 **연결 단위로 격리**된다 — HTTP 액션이 500
+으로 마감되는 것과 대칭이다(다른 연결·서버는 그대로 산다). 단 **두 훅의 마감이 다르다**:
+- `onMessage` throw → 그 연결에 **에러 프레임(`{ t:'error' }`)을 보내고 `1011` 로 종료**한다
+  (요청 실패지만 서버는 생존 = HTTP 500 대칭).
+- `onLeave` throw → 연결이 **이미 닫히는 중**이라 통지할 곳이 없다. **로그만 남기고 정리(프레즌스
+  해제 등)를 계속**한다(추가 종료·에러 프레임 없음).
+
+재시도가 필요한 로직은 핸들러 안에서 try/catch 로 감싸 직접 통제한다.
 
 ### 2.5 서버 개시 broadcast (결정 126)
 
@@ -332,7 +336,7 @@ export default channel({
 | 결정 207 | 허브 fail-fast(§5) — 리스는 얻고 TCP 포트 bind 실패 시 좀비 리더 대신 리스 사임 + `process.exit(1)`(F-13 fix · `onFatal` 훅으로 주입 가능) |
 | 결정 225 | 프레즌스 연결 축 refcount(§3) — 같은 멤버의 멀티탭·멀티서버 연결을 refcount 해 마지막 연결에서만 이탈 · cleanupServer 는 그 서버 연결만 회수(타서버 불간섭) |
 | 결정 227 | 특정/다중 유저 타겟 발송(§2.6) — `sendToUsers(name, userIds, data)` · `broadcast` 와 대칭 · 대상 연결에만 전달(멀티서버·멀티탭) · 도달 유저 수 반환(오프라인=0) · 수정 1 연결 추적 위에 얹음 |
-| 결정 257 | 채널 `onMessage`/`onLeave` throw 는 그 연결만 마감(§2.4) — 사용자 핸들러 예외가 unhandledRejection 으로 serve 를 죽이지 않는다(HTTP 500 대칭 · 에러 프레임 + 연결 종료) |
+| 결정 257 | 채널 `onMessage`/`onLeave` throw 는 연결 단위로 격리(§2) — 사용자 핸들러 예외가 unhandledRejection 으로 serve 를 죽이지 않는다(HTTP 500 대칭) · `onMessage` = 에러 프레임 + `1011` 종료 · `onLeave` = 이미 닫히는 중이라 로그만·정리 계속 |
 | 결정 259 | 허브 디스커버리 endpoint 는 소유 리더만 삭제(§5) — addr 일치 + revision CAS · standby 종료·리더 교대가 활성 endpoint 를 지우지 않음(재접속 서버 허브 발견 보존) |
 | 결정 260 | 리스 TTL 역할별 독립(§5) — 허브·스케줄러가 `gaon_lease_<역할>` 별도 버킷 · 공유 버킷 MaxAge 플래핑 제거 |
 | 결정 272 | `useChannel` 접속자 명단 조립(§4) — `onPresence(members)` 가 스냅샷+join+leave 를 하나의 전체 명단으로 반영 · 반응형 `members` Ref 추가(`messages` 대칭) · id 키 멱등 · 종전엔 스냅샷만 `onPresence`(`data`=undefined)·델타는 `onFrame` 으로만 흘러 문서대로 짠 접속자 목록이 조용히 빈 채 남던 결함 |

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

@@ -59,7 +59,11 @@ seal 은 이들 중 어느 것의 이유도 되지 못한다:
 | CSRF · 무차별 요청(DoS) | ❌ | 세션 CSRF · rate limit |
 | 작정한 공격자의 봉인 위조 | ❌(클라에 규약 있음) | 위 서버 검증 전부 |
 
-## 1. 켜는 법 — The One Way (결정 121·124)
+## 정본 규칙
+
+(§0 은 포지셔닝 프리앰블 — 켜기 전에 반드시 읽는다. 아래 §1~§5 가 실제 정본 규칙이다.)
+
+### 1. 켜는 법 — The One Way (결정 121·124)
 
 ```bash
 1) npm i @gaonjs/seal            # 선택 플러그인 · 기본 스캐폴드 미포함
@@ -88,7 +92,7 @@ void createGaonApp({ pages, layouts, /* ... */ sealClient })
 - 미설치로 `seal: true` 를 켜면 **부팅 에러**(수리 안내). `masterSecret` 설정 표면은 없다 — 미끼 literal
   이라 설정할 이유가 없다(비밀 착시·랜덤화 사고 방지).
 
-## 2. 무엇이 봉인되나
+### 2. 무엇이 봉인되나
 
 - **요청/응답 JSON**: 클라 `installClientSeal()` 이 Inertia XHR 인터셉터(`XMLHttpRequest.prototype`) +
   `api()`/`fetch` 봉인을 설치한다. 서버는 Fastify **4-stage 훅**(`plugin.ts` · onRequest 분류/fail-closed →
@@ -112,17 +116,18 @@ void createGaonApp({ pages, layouts, /* ... */ sealClient })
 - **자동 제외 / 옵트아웃**: 정적 자산·헬스체크·multipart 업로드 body·비대상(JSON 도 Inertia 도 아닌 HTML
   직접 로드·네이티브 form)은 **자동 제외**(사람 판단 없이 헤더 기계 판별 · 결정 125). 외부(웹훅 등)가 봉인을
   모르는 경로는 `seal: { except: ['/webhooks/*'] }`.
-- **fail-closed (403 · 결정 121)**: 봉인 강제 경로에 시그널 헤더 없이 온 요청, drift/replay/키 실패는
-  **403 SealError** — 평문 통과 절대 없음. WS 개봉 실패는 **서버·클라 모두 소켓 4500 종료**(결정 222 · silent
+- **fail-closed (403·413 · 결정 121)**: 봉인 강제 경로에 시그널 헤더 없이 온 요청, drift/replay/키 실패는
+  **403 SealError** — 평문 통과 절대 없음. **과대 요청 본문(상한 초과 · `PAYLOAD_TOO_LARGE`)만 예외로 413**
+  (`readStream` OOM 방어 · `errors.ts`). WS 개봉 실패는 **서버·클라 모두 소켓 4500 종료**(결정 222 · silent
   fallback 없음). 클라(`useChannel`)는 4500 이후 재연결하지 않는다(개봉 실패 = transient 아님 · 종단).
 
-## 3. CSP (결정 124)
+### 3. CSP (결정 124)
 
 seal 앱 응답에만 `script-src` 에 `'wasm-unsafe-eval'` 을 **자동 주입**한다(wasm 컴파일만 허용 ·
 `'unsafe-eval'` 보다 좁음). **전역 완화 금지** — 비-seal 앱은 strict CSP(`script-src 'self'`) 그대로다.
 요청 단위 판별(seal 스코프가 요청을 표시 · 보안 헤더 훅이 그 응답에만 보정).
 
-## 4. 아키텍처 경계 (AI 가 넘지 말 것)
+### 4. 아키텍처 경계 (AI 가 넘지 말 것)
 
 - **`@gaonjs/vue` 는 seal 무지 유지 · 비-seal 앱 번들에 wasm 0.** 두 번째 http/ws 클라이언트를 이식하지
   않는다 — 봉인/개봉은 기존 전송 경로(Inertia·`api()`·`useChannel`) **경계 인터셉터**가 한다.
@@ -152,7 +157,7 @@ seal 앱 응답에만 `script-src` 에 `'wasm-unsafe-eval'` 을 **자동 주입*
 - **허브(`gaon hub`)는 손대지 않는다** — 봉인/개봉은 각 웹서버의 소켓 경계에서만. 타 서버 접속자의
   UA·ts 컨텍스트가 없어 허브가 프레임을 복호할 수 없는 것은 구조적 필연(설계상) · 허브·NATS 내부는 평문.
 
-## 5. 게이트 — seal 검증은 **실 브라우저가 blocking** (결정 124)
+### 5. 게이트 — seal 검증은 **실 브라우저가 blocking** (결정 124)
 
 - 정본 게이트는 **실 vite 프로덕션 빌드 + 실 chromium + 실 wasm** e2e 다:
   `test/integration/seal-browser-e2e.integration.test.ts`(마운트·data-page 개봉·useForm POST·api()·WS `E:` 왕복·
@@ -168,6 +173,29 @@ seal 앱 응답에만 `script-src` 에 `'wasm-unsafe-eval'` 을 **자동 주입*
   (Playwright `page.waitForResponse(...).text()`·`page.on('response')` · 외부 `curl`)로 **시그널 헤더 + 암호문**을
   직접 봐야 드러난다. 정본 게이트 ⑨(결정 125)가 이 방식으로 네비게이션 wire 봉인을 정면 단언한다.
 
+## 정본 예시
+
+봉인은 **켜는 것**이 전부다 — 컨트롤러·`this.params`·`api()`·페이지 코드는 한 줄도 안 바뀐다(§2 wire 봉인은 훅/인터셉터가 담당).
+
+```ts
+// apps/web/app.config.ts — 앱 wire 전체 봉인.
+export default defineAppConfig({ seal: true })
+```
+```ts
+// apps/web/main.ts — seal 클라이언트 정적 import 를 createGaonApp 에 주입(결정 124 · doctor 가 강제·fixer 자동 배선).
+import { createGaonApp } from 'gaonjs/vue'
+import * as sealClient from '@gaonjs/seal/client'
+void createGaonApp({ pages, layouts, /* ... */ sealClient })
+```
+```ts
+// 컨트롤러는 그대로 — seal 을 전혀 모른다(요청/응답 JSON·최초 문서 data-page·WS 프레임이 자동 봉인).
+export default controller({
+  async index() {
+    return this.render('Posts/Index', { posts: await Post.latest().all() })
+  },
+})
+```
+
 ## 알려진 함정
 
 1. **main.ts 배선 누락** → 봉인 문서를 브라우저가 못 열어 화면 blank. → `gaon check`(`seal-security`)가 잡고 `gaon doctor --fix --yes` 가 배선. 런타임도 수리 안내 throw.

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

@@ -94,6 +94,11 @@
   한다 — 폼(POST)을 추가하는 순간 CSRF 가 이미 켜져 있다. 앱에 비-GET
   라우트가 있는데 `app.config.ts` 에 session 이 없으면 `gaon doctor` 의
   `csrf-wiring` 이 경고한다(JWT/API 앱은 토큰 인증이라 CSRF 대상 제외).
+- **CSRF 를 끄는 유일한 스위치는 `session: { csrf: false }` (결정 271 · 규칙 8).**
+  `app.config.ts` 의 `session` 에 `csrf: false` 를 명시할 때만 그 앱의 CSRF 검증이
+  꺼진다 — 생략·`undefined` 는 켬(보안 기본값). 커스텀 헤더 인증 등 세션 앱이면서
+  CSRF 를 꺼야 하는 특수 경로용 탈출구이고, 끄면 상태 변경 요청이 무방비가 되므로
+  이유를 남긴다. wire 가 이 값을 `SessionOptions.csrf` 로 그대로 전달한다.
 - **CSRF/세션 실패는 코어가 Inertia-네이티브로 마감한다 (결정 165).** 세션 만료·
   secret 로테이션·장시간 탭으로 CSRF 가 실패하면, Inertia 요청은 raw JSON 403 이 아니라
   **409 + `X-Inertia-Location` 풀 리로드**(새 세션 쿠키+새 토큰) + `flash.error` 안내로
@@ -241,3 +246,6 @@ const rows = await Post.query()
 | 결정 145 | 인가 프리미티브 `this.authorize(cond)` — 거짓 → 403(존재 은닉 시 404) · 인증(401)과 별개 축 · 저수준 탈출구 |
 | 결정 149 | 인가 정책 객체 `policy()` + `this.can` — 재사용 규칙을 리소스별 액션→조건으로 묶음 · 값 객체(레지스트리 아님) · 가드는 `authorize(can(...))` 로 수렴 · authorize(cond) 무회귀(§2) |
 | 결정 155 | `gaon g auth --app <비-web>` 시큐어 기본 — 공개 회원가입 미생성 + 역할 게이트(authorize) 예시 · web=공개가입 · `--public` opt-in(§2) |
+| 결정 165 | 세션/CSRF 실패·415 를 코어가 Inertia-네이티브(409 풀 리로드+flash / 415 수리 안내)로 마감 — raw JSON 403 무 · 비-Inertia 는 JSON 유지(§2.3) |
+| 결정 254 | 로그인 시 세션 ID 재생성(fixation 방어) · 로그아웃 시 세션 파기(§2.3 · `this.auth`) |
+| 결정 271 | CSRF 를 끄는 유일 스위치 = `session: { csrf: false }` — 생략은 켬(보안 기본값) · wire 가 `SessionOptions.csrf` 로 전달(§2.3) |

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

@@ -19,13 +19,16 @@
 | 조회 | `Storage.get(key): Promise<Buffer \| null>` | 없으면 null |
 | 삭제 | `Storage.delete(key)` | 멱등 |
 | 존재 | `Storage.exists(key): Promise<boolean>` | |
-| URL | `Storage.url(key, { expiresIn? }): Promise<string>` | 공개 버킷/CDN = 공개 URL · 아니면 presigned |
+| URL | `Storage.url(key, { expiresIn? }): Promise<string>` | 드라이버별로 다름(아래) — 로컬=공개 경로 · s3=공개 URL 또는 presigned |
 | 디스크 선택 | `Storage.disk('s3').put(...)` | 기본 디스크 외 다른 디스크로 |
 
-- **URL 은 `Storage.url()` 한 곳**이다 — `publicUrl`(공개 버킷·CDN·R2 public)이
-  있으면 `${publicUrl}/${key}`, 없으면 만료 있는 **presigned URL** 을 만든다.
-  `expiresIn`(초)로 만료를 조절한다. 존재하지 않는 `Attachment.urlFor` 같은
-  헬퍼를 만들지 말 것 — 표면은 `Storage.url()` 뿐이다.
+- **URL 은 `Storage.url()` 한 곳**이지만 **드라이버로 갈린다**:
+  - **로컬 디스크**: 항상 `${baseUrl}/${key}` **공개 경로**를 만든다(서명 없음 · `expiresIn` 무시).
+    `baseUrl` 기본값은 `/storage`(웹이 그 경로를 정적 서빙·라우트로 노출) — presigned 개념이 없다.
+  - **s3 디스크**: `publicUrl`(공개 버킷·CDN·R2 public)이 있으면 `${publicUrl}/${key}`,
+    없으면 만료 있는 **presigned URL**(`getSignedUrl` · `expiresIn` 초 · 기본 3600)을 만든다.
+  존재하지 않는 `Attachment.urlFor`·`Storage.signedUrl` 같은 헬퍼를 만들지 말 것 —
+  표면은 `Storage.url()` 뿐이다.
 - **키는 경로**다(`avatars/${user.id}.png`). 앞 슬래시는 정규화된다.
 - **`contentType` 은 어댑터별로 다르게 반영된다**(결정 236): `s3` 는 객체
   메타데이터로 저장해 다운로드·presign 시 그대로 나가고, **로컬**은 저장하지
@@ -55,7 +58,8 @@ storage: process.env.STORAGE_ENDPOINT
 
 - dev 는 compose 의 `createbuckets` 가 버킷을 만들어 **첫 업로드부터 동작**한다
   (결정 132 · zero-config). `cp .env.example .env && gaon dev` → 우회 0.
-- 로컬 디스크: `{ driver: 'local', root: 'storage', publicUrl?: '/uploads' }`.
+- 로컬 디스크: `{ driver: 'local', root: 'storage', baseUrl?: '/storage' }` — `url(key)`
+  = `baseUrl + '/' + key`(공개 경로 · `baseUrl` 생략 시 `/storage`).
 - 운영(R2/S3)은 인프라에서 버킷을 사전 생성한다(앱 밖 관심사) — endpoint·creds
   만 env 로 바꾼다.
 
@@ -99,6 +103,19 @@ export default controller({
   `<bucket>-test`, 로컬 root 는 `<root>-test` 로 격리된다(`<db>_test` 대칭 ·
   `agents/testing.md`). 스토리지 잡 테스트는 스캐폴드 `test/setup.ts` 그대로 통과한다.
 
+## 정본 예시
+
+```ts
+// 저장 → 공개/서명 URL 얻기(드라이버 무관 · 같은 코드). url() 은 async.
+const key = `avatars/${user.id}.png`
+await Storage.put(key, buffer, { contentType: 'image/png' })
+const src = await Storage.url(key)            // 로컬=`/storage/avatars/<id>.png` · s3=공개 URL 또는 presigned
+// 만료 있는 서명 URL(s3 · 로컬은 expiresIn 무시):
+const tempLink = await Storage.url(key, { expiresIn: 600 })
+```
+
+업로드(멀티파트) 수신·저장의 정본은 §3(`this.file('avatar')` → `Storage.put`).
+
 ## 알려진 함정
 
 - **존재하지 않는 API 를 상상하지 말 것** — 파일 URL 은 `Storage.url()`,

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

@@ -25,8 +25,9 @@
 - `gaon test` 가 잡·이벤트 NATS 스트림도 **자동 격리**한다(결정 130) —
   테스트 프로세스에 `GAON_STREAM_PREFIX` 를 주입해 스트림·subject 가
   `GAON_TEST_JOBS`·`test.gaon.jobs.>` 로 갈린다. 같은 접두가 **NATS KV 버킷**
-  (스케줄러 리스 `gaon_lease`·프레즌스·허브)에도 적용돼(결정 203) `test_gaon_lease`
-  처럼 격리된다 — 스트림뿐 아니라 KV 도 개발·운영 스택과 안 겹친다. 그래서
+  (프레즌스·허브·역할별 리스)에도 적용돼(결정 203) 격리된다 — 리스 버킷은 결정 260 으로
+  역할마다 분리돼 `gaon_lease_<역할>`(예 `gaon_lease_hub_leader`) 이고, 테스트에선
+  `test_gaon_lease_hub_leader` 처럼 접두가 붙는다. 스트림뿐 아니라 KV 도 개발·운영 스택과 안 겹친다. 그래서
   개발용 `gaon work` 가 떠 있어도 테스트 잡을 훔치지 않고 스케줄러 리더 경합도
   안 생기며, 테스트가 남긴 잡을 개발 워커가 처리하지도 않는다 — **테스트 전에
   워커를 내릴 필요가 없다.** (직접 `vitest` 로 돌리면 이 격리가 없어 개발 스택과
@@ -42,6 +43,14 @@
 - 통합 테스트는 `test/integration/<이름>.integration.test.ts` — 러너는
   vitest (`gaon test --scope integration`).
 - 단위 테스트는 소스 옆 `<이름>.test.ts` (`--scope unit`).
+- **필터·인자 전달** — `gaon test <필터>`(예 `gaon test posts`)는 `posts` 를 vitest
+  파일명 필터로 그대로 넘긴다. `gaon test -- <vitest 인자>`(예 `gaon test -- --reporter=dot`)
+  로 vitest 플래그를 통과시킨다 — `--scope`/`--json` 만 gaon 이 소비하고 나머지는 전부
+  vitest 에 그대로 전달된다.
+- **MCP `run_tests` 도 같은 하네스를 탄다(결정 270)** — 내장 MCP 서버의 `run_tests` 도구는
+  vitest 를 직접 spawn 하지 않고 `gaon test`(`runTestCommand`)에 위임한다. 그래서 AI 가
+  MCP 로 돌려도 테스트 DB 프로비저닝·`GAON_STREAM_PREFIX` 격리·사용자 `test` 스크립트
+  우선이 그대로 적용된다(필터·`--scope` 인자도 동일).
 - `vi.mock('gaonjs/async')` · `vi.mock('nats')` · `vi.mock('@nats-io/…')`
   같은 프레임웍·전송 목업은 금지다 (§9) — 실 접속으로 검증한다.
 

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

@@ -168,9 +168,11 @@ export default controller({
 `this.file()` 업로드(멀티파트)의 CSRF 토큰은 **`x-csrf-token` 헤더**로 보낸다.
 멀티파트는 `parts()` 스트리밍이라 CSRF 검사(preHandler) 시점에 **바디가 아직
 파싱되지 않아** 폼 필드 `_csrf` 가 검사에 잡히지 않는다(구조적 한계 · 디스패처가
-handler 안에서 파싱). 일반 폼(JSON/urlencoded)의 `_csrf` 바디 폴백은 멀티파트엔
+handler 안에서 파싱). 일반 JSON 폼의 `_csrf` 바디 폴백은 멀티파트엔
 통하지 않는다. 파일이 있으면 `useForm` 이 자동으로 multipart 로 보내므로, 업로드
-제출은 **반드시 헤더**로 토큰을 실어야 한다.
+제출은 **반드시 헤더**로 토큰을 실어야 한다. (참고: 지원 Content-Type 은
+`application/json` · `multipart/form-data` 뿐이라 `x-www-form-urlencoded` 로 폼을
+보내면 `_csrf` 폴백에 닿기 전에 415 로 거부된다 · `inertia.ts` · §아래 415.)
 
 ```vue
 <script setup lang="ts">
@@ -576,10 +578,16 @@ export default controller({
 | 결정 119 | 목록 액션 페이지네이션 = `chain.paginate(page, perPage)` 종단(§4.3 · `agents/data.md`) · 손 조립 반정본 · result 통째로 render props 안전 |
 | 결정 120 | 클라이언트 IP = `this.request.ip`(별도 표면 없음) · `web.clientIp` direct/proxy/header 로 rate limit·로깅과 같은 산출 배선(§4.4 · `agents/security.md`) |
 | 결정 133 | 멀티파트 업로드(`this.file()`) CSRF 는 `x-csrf-token` 헤더로만 — 바디 `_csrf` 는 스트리밍 파싱이라 검사 시점에 없다(§3 · 헤더 부재 시 403 + 수리 안내) |
+| 결정 64 | 폼 API 는 `gaonjs/vue` 의 `useForm`·`router` 뿐 — 로그아웃 등 DELETE 는 `router.delete()`(`@inertiajs/vue3` 직접 import 금지 · `Inertia.post()` 유령 API 아님) |
+| 결정 122 | 관계·hidden 값이 render 경계 `serializeProps` 를 넘어 새지 않는다 — hidden 컬럼 제외 유지(§4.2) |
+| 결정 165 | 세션/CSRF 실패·415(지원 안 되는 Content-Type)를 코어가 Inertia-네이티브(409 풀 리로드+flash / 415 수리 안내)로 마감 — raw JSON 403 으로 앱을 깨지 않는다(§4.1 · 지원 타입 `application/json`·`multipart/form-data`) |
+| 결정 183 | 검증 사유 로케일화 — 안정 코드 + 예약 namespace `validation.<code>` 로 요청 로케일 번역(미제공 시 내장 fallback · §4.1) |
+| 결정 253 | hidden 마커 = 열거 가능한 심볼 → `render(page, { ...user })` spread 우회로도 hidden 값이 안 샌다(§4.2) |
+| 결정 254 | 로그인 시 세션 ID 재생성(fixation 방어) · 로그아웃 시 세션 파기(§4.4 auth) |
 | E-1 | 파사드 = `gaonjs` · CLI = `gaon` |
 
 ## `@gaonjs/seal` 켠 앱
 
 `app.config seal: true` 면 그 앱의 wire(요청/응답 JSON + 최초 문서 data-page)가 봉인된다 — 컨트롤러·라우트·
 `this.params`·`api()` 코드는 한 줄도 안 바뀐다. **정본은 `agents/seal.md`**(켜는 법·main.ts 배선·`except`·
-자동 제외·fail-closed 403).
+자동 제외·fail-closed = 평문 통과 금지 · 기본 403 · 과대 페이로드는 413).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaonjs/cli",
-  "version": "0.42.2",
+  "version": "0.43.0",
   "description": "Gaon CLI — 스캐폴딩·제너레이터·마이그레이션·dev/serve/work/hub·doctor·check (bin: gaon)",
   "type": "module",
   "license": "MIT",
@@ -28,12 +28,12 @@
     "typescript": "^5.9.0",
     "vite": "^7.0.0",
     "@gaonjs/async": "0.15.3",
-    "@gaonjs/config": "0.18.0",
+    "@gaonjs/config": "0.19.0",
+    "@gaonjs/data": "0.21.0",
     "@gaonjs/core": "0.2.4",
     "@gaonjs/i18n": "0.2.4",
-    "@gaonjs/data": "0.17.3",
-    "@gaonjs/mail": "0.3.3",
-    "@gaonjs/web": "0.20.4"
+    "@gaonjs/web": "0.21.0",
+    "@gaonjs/mail": "0.3.3"
   },
   "scripts": {
     "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json && node -e \"require('fs').cpSync('src/templates','dist/templates',{recursive:true})\""

package/dist/doctor/shared-composable-purity.d.ts

@@ -1,8 +0,0 @@
-import type { DoctorCheck, RuleReport } from './types.js';
-/**
- * 단일 shared 컴포저블 소스를 검사해 순수성 위반 목록을 낸다
- * (단위 테스트 진입점).
- */
-export declare function inspectSharedComposable(file: string, source: string, cwd: string): DoctorCheck[];
-/** shared/composables/ 를 훑어 순수성 위반을 모두 낸다. */
-export declare function checkSharedComposablePurity(cwd: string): Promise<RuleReport>;

package/dist/doctor/shared-composable-purity.js

@@ -1,164 +0,0 @@
-// @gaonjs/cli · doctor · shared 컴포저블 순수성 검사 (M9-E 확장 · errata E-5 §2.2)
-//
-// shared/composables/ 는 shared 컴포넌트의 "props 로만" 규칙과 정확히
-// 같은 구도를 따른다. 라우트를 몰라야 하고(api·pageProps 금지) · domain
-// 은 타입으로만 참조해야 한다. 필요한 데이터·호출 함수는 인자로 받는다.
-// 정본 근거: errata E-5 §2.2 (컴포저블·레이아웃 관례 · 결정 25).
-//
-// 검사 대상:
-//  1) 프레임웍 모듈(gaonjs · gaonjs/vue · @gaonjs/vue · @gaonjs/web) 에서
-//     'api' · 'pageProps' 를 value import 하면 error.
-//     - type-only 는 무해(구조 참조뿐 · 라우트 지식 필요 없음).
-//  2) domain 을 value import 하면 error.
-//     - type-only 는 허용(모델 Row 타입 등 · 순수 타입 참조).
-//
-// 방법: shared/composables/*.ts 를 TS AST 로 파싱해 import 선언만 훑는다.
-// 상대 import 는 실 파일까지 해석하지 않고 경로 접두사(domain/) 로 판정 —
-// 이 검사는 순수성 게이트라 정확도보다 재현성이 우선(false positive 는
-// 오히려 안전).
-import { readdir, readFile } from 'node:fs/promises';
-import { join, relative, resolve, dirname } from 'node:path';
-import ts from 'typescript';
-/** 라우트 지식을 담은 심볼 — shared 는 참조할 수 없다. */
-const FORBIDDEN_FRAMEWORK_NAMES = new Set(['api', 'pageProps']);
-/**
- * 프레임웍 모듈 패턴. 문서 표기(gaon/vue)는 실 패키지 이름의 짧은
- * 별칭이며, 실 배포본은 gaonjs 파사드 subpath 와 @gaonjs 스코프를 쓴다.
- * 하나만 잡으면 우회가 쉬우므로 알려진 표기 3종을 모두 매치한다.
- */
-const FRAMEWORK_MODULE_PATTERNS = [
-    /^gaonjs$/,
-    /^gaonjs\/vue$/,
-    /^@gaonjs\/vue$/,
-    /^@gaonjs\/web$/,
-];
-/** import 선언에서 이름과 type-only 플래그를 추출한다. */
-function collectImportedNames(node) {
-    const out = [];
-    const clause = node.importClause;
-    if (!clause)
-        return out;
-    const clauseTypeOnly = clause.isTypeOnly;
-    if (clause.name)
-        out.push({ name: clause.name.text, typeOnly: clauseTypeOnly });
-    const bindings = clause.namedBindings;
-    if (bindings) {
-        if (ts.isNamespaceImport(bindings)) {
-            out.push({ name: bindings.name.text, typeOnly: clauseTypeOnly });
-        }
-        else if (ts.isNamedImports(bindings)) {
-            for (const el of bindings.elements) {
-                out.push({ name: el.name.text, typeOnly: clauseTypeOnly || el.isTypeOnly });
-            }
-        }
-    }
-    return out;
-}
-function isRelativeSpecifier(s) {
-    return s.startsWith('./') || s.startsWith('../');
-}
-function matchesFrameworkModule(spec) {
-    return FRAMEWORK_MODULE_PATTERNS.some((re) => re.test(spec));
-}
-/**
- * 단일 shared 컴포저블 소스를 검사해 순수성 위반 목록을 낸다
- * (단위 테스트 진입점).
- */
-export function inspectSharedComposable(file, source, cwd) {
-    const issues = [];
-    const rel = relative(cwd, file);
-    const sf = ts.createSourceFile(file, source, ts.ScriptTarget.ES2022, true);
-    const baseDir = dirname(file);
-    const visit = (node) => {
-        if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)) {
-            const spec = node.moduleSpecifier.text;
-            const { line } = sf.getLineAndCharacterOfPosition(node.getStart(sf));
-            const names = collectImportedNames(node);
-            // 1) 프레임웍의 api/pageProps 를 value import → error
-            if (matchesFrameworkModule(spec)) {
-                for (const n of names) {
-                    if (n.typeOnly)
-                        continue; // type-only 는 라우트 실행 지식이 아님
-                    if (!FORBIDDEN_FRAMEWORK_NAMES.has(n.name))
-                        continue;
-                    issues.push({
-                        rule: 'shared-composable-purity',
-                        level: 'error',
-                        file: rel,
-                        line: line + 1,
-                        message: `${rel} (line ${line + 1})\n` +
-                            `  '${spec}' 의 '${n.name}' import 발견 · shared 는 라우트를 몰라야 함\n` +
-                            `→ 옵션: apps/<앱>/composables/ 로 옮기거나 · ${n.name} 호출을 인자로 받도록 바꾸라`,
-                        detail: {
-                            kind: 'framework-api',
-                            module: spec,
-                            name: n.name,
-                        },
-                    });
-                }
-            }
-            // 2) domain value import → error (type-only 는 허용)
-            if (isRelativeSpecifier(spec)) {
-                const abs = resolve(baseDir, spec);
-                const parts = relative(cwd, abs).split(/[\\/]/).filter(Boolean);
-                if (parts[0] === 'domain') {
-                    const valueNames = names.filter((n) => !n.typeOnly);
-                    if (valueNames.length > 0) {
-                        issues.push({
-                            rule: 'shared-composable-purity',
-                            level: 'error',
-                            file: rel,
-                            line: line + 1,
-                            message: `${rel} (line ${line + 1})\n` +
-                                `  domain 값 import 발견 · shared 컴포저블은 domain 을 타입으로만 참조해야 함\n` +
-                                `→ 'import type { ... } from ...' 형태로 바꾸거나 · 필요한 값은 인자로 받도록 바꾸라`,
-                            detail: {
-                                kind: 'domain-value',
-                                module: spec,
-                                names: valueNames.map((n) => n.name),
-                            },
-                        });
-                    }
-                }
-            }
-        }
-        ts.forEachChild(node, visit);
-    };
-    visit(sf);
-    return issues;
-}
-/** shared/composables/ 를 훑어 순수성 위반을 모두 낸다. */
-export async function checkSharedComposablePurity(cwd) {
-    const composablesDir = join(cwd, 'shared', 'composables');
-    const files = [];
-    await collectTsFiles(composablesDir, files);
-    const issues = [];
-    for (const file of files) {
-        const src = await readFile(file, 'utf8');
-        issues.push(...inspectSharedComposable(file, src, cwd));
-    }
-    return { rule: 'shared-composable-purity', issues };
-}
-async function collectTsFiles(root, out) {
-    let entries;
-    try {
-        entries = (await readdir(root, { withFileTypes: true }));
-    }
-    catch {
-        return;
-    }
-    for (const e of entries) {
-        const name = e.name;
-        if (name === 'node_modules' || name === 'dist' || name === '.gaon')
-            continue;
-        const full = join(root, name);
-        if (e.isDirectory())
-            await collectTsFiles(full, out);
-        else if (e.isFile() &&
-            name.endsWith('.ts') &&
-            !name.endsWith('.d.ts') &&
-            !name.endsWith('.test.ts')) {
-            out.push(full);
-        }
-    }
-}