@gaonjs/cli 0.31.0 → 0.32.0

package/dist/commands/db.d.ts

@@ -4,7 +4,11 @@ export interface DbCommandOptions {
     readonly cwd?: string;
     /** 자동화 출력. 기본 false(사람 텍스트). */
     readonly json?: boolean;
-    /** 커넥션 키(§4.5). 기본 'main'. */
+    /**
+     * 커넥션 키(§4.5). 결정 139: diff/migrate/status/seed 는 생략(또는 'all') 시
+     * 등록된 **전 커넥션**을 순회 적용한다 · `--db <키>` 는 단일 좁힘. reset(파괴적)은
+     * 항상 단일이며 생략 시 'main'.
+     */
     readonly db?: string;
     /** --config <path> 오버라이드. 없으면 cwd/gaon.config.ts 관례. */
     readonly config?: string;

package/dist/commands/db.js

@@ -11,7 +11,12 @@ import { runDbDiff } from '../db/diff.js';
 import { runDbMigrate } from '../db/migrate.js';
 import { runDbReset } from '../db/reset.js';
 import { runDbStatus } from '../db/status.js';
+import { listConnectionKeys } from '../db/resolve.js';
 import { runDbSeedCommand } from '../db.js';
+/** 전 커넥션 순회 대상 서브커맨드(결정 139 · reset 은 파괴적이라 제외 · 단일 유지). */
+const MULTI_CONN_SUBS = new Set(['diff', 'migrate', 'status', 'seed']);
+/** 알려진 서브커맨드. dispatcher 방어(모르는 값이 오면 seed 로 새지 않게). */
+const KNOWN_SUBS = new Set(['diff', 'migrate', 'reset', 'seed', 'status']);
 /**
  * `gaon db <sub>` 진입점. 사람/JSON 출력을 자체 처리하고 exitCode 를
  * 돌려준다. seed 는 기존 M8 runDbSeedCommand 로 위임(신규 서명에 정합).
@@ -19,7 +24,6 @@ import { runDbSeedCommand } from '../db.js';
 export async function runDbCommand(subcommand, opts = {}) {
     const cwd = opts.cwd ?? process.cwd();
     const json = opts.json ?? false;
-    const dbKey = opts.db ?? 'main';
     const configPath = opts.config;
     const dryRun = opts.dryRun ?? false;
     const emit = (text, jsonValue) => {
@@ -28,45 +32,55 @@ export async function runDbCommand(subcommand, opts = {}) {
         else
             process.stdout.write(text + '\n');
     };
-    try {
-        if (subcommand === 'diff') {
-            const r = await runDbDiff({ cwd, dbKey, json, configPath });
-            emit(r.text, r.json);
-            return r.exitCode;
-        }
-        if (subcommand === 'migrate') {
-            const r = await runDbMigrate({ cwd, dbKey, json, dryRun, down: opts.down ?? false, configPath });
-            emit(r.text, r.json);
-            return r.exitCode;
-        }
-        if (subcommand === 'status') {
-            const r = await runDbStatus({ cwd, dbKey, json, configPath });
-            emit(r.text, r.json);
-            return r.exitCode;
-        }
-        if (subcommand === 'reset') {
-            const r = await runDbReset({
-                cwd,
-                dbKey,
-                json,
-                yes: opts.yes ?? false,
-                dryRun,
-                configPath,
-            });
-            emit(r.text, r.json);
-            return r.exitCode;
-        }
-        if (subcommand === 'seed') {
-            // 결정 101: seed 도 diff/migrate 와 같은 설정 해석 경로(config → env)를 쓴다.
-            const r = await runDbSeedCommand({ root: cwd, json, configPath, dbKey });
-            emit(r.text, r.json);
-            return r.exitCode;
-        }
-        // 방어 — dispatcher 라 도달할 수 없지만 컴파일러 만족용.
+    // 한 커넥션에 대해 서브커맨드를 실행한다(순회 루프의 단위).
+    const runOne = async (subKey) => {
+        if (subcommand === 'diff')
+            return runDbDiff({ cwd, dbKey: subKey, json, configPath });
+        if (subcommand === 'migrate')
+            return runDbMigrate({ cwd, dbKey: subKey, json, dryRun, down: opts.down ?? false, configPath });
+        if (subcommand === 'status')
+            return runDbStatus({ cwd, dbKey: subKey, json, configPath });
+        if (subcommand === 'reset')
+            return runDbReset({ cwd, dbKey: subKey, json, yes: opts.yes ?? false, dryRun, configPath });
+        // seed (결정 101: diff/migrate 와 같은 설정 해석 경로 config → env).
+        return runDbSeedCommand({ root: cwd, json, configPath, dbKey: subKey });
+    };
+    // 방어 — dispatcher 라 도달할 수 없지만, 모르는 서브커맨드가 seed 로 새지 않게.
+    if (!KNOWN_SUBS.has(subcommand)) {
         process.stderr.write(`  ✗ 알 수 없는 db 서브커맨드: ${String(subcommand)}\n` +
             `  → 지원: diff | migrate | reset | seed | status\n`);
         return 1;
     }
+    try {
+        // 결정 139: diff/migrate/status/seed 는 --db 생략(또는 'all') 시 등록된 전
+        // 커넥션을 순회 적용한다(One Way — 커넥션 하나를 잊어 빈 채 배포하는 사고 방지).
+        // `--db <키>` 는 단일 좁힘. reset(파괴적)은 항상 단일(main 폴백).
+        const wantsAll = subcommand !== 'reset' && (opts.db === undefined || opts.db === 'all');
+        if (wantsAll && MULTI_CONN_SUBS.has(subcommand)) {
+            const keys = await listConnectionKeys(cwd, configPath);
+            // 단일 커넥션이면 종전 출력과 100% 동일(하위 호환).
+            if (keys.length === 1) {
+                const r = await runOne(keys[0]);
+                emit(r.text, r.json);
+                return r.exitCode;
+            }
+            return runAcrossConnections(subcommand, keys, runOne, emit, json);
+        }
+        // 단일 커넥션 경로(--db <키> · reset · env-only 폴백) — 종전 동작 그대로.
+        if (subcommand === 'reset' && opts.db === 'all') {
+            // reset 은 전 커넥션 순회를 하지 않는다(파괴적). 명시적으로 거부한다.
+            const msg = `reset 은 전 커넥션 순회를 지원하지 않습니다(파괴적).\n` +
+                `→ 커넥션을 하나씩 지정하세요: 'gaon db reset --db main --yes'.`;
+            if (json)
+                process.stdout.write(JSON.stringify({ command: 'reset', ok: false, error: msg }) + '\n');
+            else
+                process.stderr.write(`  ✗ ${msg}\n`);
+            return 1;
+        }
+        const r = await runOne(opts.db ?? 'main');
+        emit(r.text, r.json);
+        return r.exitCode;
+    }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         if (json) {
@@ -78,3 +92,45 @@ export async function runDbCommand(subcommand, opts = {}) {
         return 1;
     }
 }
+/**
+ * 전 커넥션 순회 실행(결정 139). 각 커넥션을 등록 순서대로 돌리고, 한 커넥션이
+ * 실패해도 나머지를 계속한다(부분 적용 방지가 아니라 부분 진행 후 전체 보고 — 어느
+ * 커넥션이 성공/실패했는지가 사용자에게 필요). exitCode = 하나라도 실패면 1.
+ */
+async function runAcrossConnections(subcommand, keys, runOne, emit, json) {
+    const results = [];
+    for (const key of keys) {
+        try {
+            const r = await runOne(key);
+            results.push({ db: key, ok: r.exitCode === 0, exitCode: r.exitCode, text: r.text, json: r.json });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            results.push({
+                db: key,
+                ok: false,
+                exitCode: 1,
+                text: `  ✗ [${key}] gaon db ${subcommand} 실패: ${msg}`,
+                json: { command: subcommand, db: key, ok: false, error: msg },
+            });
+        }
+    }
+    const failed = results.filter((r) => !r.ok);
+    const exitCode = failed.length > 0 ? 1 : 0;
+    if (json) {
+        emit('', {
+            command: subcommand,
+            connections: keys,
+            ok: failed.length === 0,
+            results: results.map((r) => ({ db: r.db, ok: r.ok, ...r.json })),
+        });
+        return exitCode;
+    }
+    const header = `  gaon db ${subcommand} · 커넥션 ${keys.length}개 순회: ${keys.join(', ')}`;
+    const sections = results.map((r) => `  ── [${r.db}] ${'─'.repeat(Math.max(0, 40 - r.db.length))}\n${r.text}`);
+    const footer = failed.length === 0
+        ? `  ✓ 전 커넥션 완료(${keys.length}개).`
+        : `  ✗ ${failed.length}/${keys.length} 커넥션 실패: ${failed.map((r) => r.db).join(', ')}`;
+    emit([header, ...sections, footer].join('\n'), null);
+    return exitCode;
+}

package/dist/db/resolve.d.ts

@@ -28,11 +28,9 @@ export interface ResolvedDbTarget {
     close(): Promise<void>;
 }
 /**
- * gaon.config.ts 를 로드해 target db 커넥션을 등록하고 스키마 테이블을 모아 온다.
- *
- * 커넥션 결정 순서:
- *  1) config.db[dbKey] 가 있으면 그 어댑터·URL 사용
- *  2) dbKey='main' 이고 GAON_DATABASE_URL 이 있으면 그 URL 로 main 을 세움
- *  3) 그 외 → 수리 안내 에러
+ * 프로젝트의 커넥션 키 목록을 돌려준다(결정 139 · `gaon db <sub>` 전 커넥션 순회용).
+ * config.db 에 선언된 키 순서 그대로. 선언이 없으면(env-only 프로젝트) `['main']`
+ * 폴백(GAON_DATABASE_URL 관례) — 단일 커넥션 프로젝트의 종전 동작과 정합.
  */
+export declare function listConnectionKeys(cwd: string, configPath?: string): Promise<string[]>;
 export declare function resolveDbTarget(opts: ResolveDbOptions): Promise<ResolvedDbTarget>;

package/dist/db/resolve.js

@@ -65,15 +65,15 @@ function isTableDef(v) {
  *  2) dbKey='main' 이고 GAON_DATABASE_URL 이 있으면 그 URL 로 main 을 세움
  *  3) 그 외 → 수리 안내 에러
  */
-export async function resolveDbTarget(opts) {
-    const cwd = resolvePath(opts.cwd);
+/**
+ * gaon.config 를 로드해 config 값과 실 경로를 돌려준다. --config <path> 가 있으면
+ * 그 파일의 default export 를, 없으면 cwd 관례(gaon.config.ts)를 쓴다.
+ * resolveDbTarget·listConnectionKeys 가 공유한다(결정 139).
+ */
+async function loadDbConfig(cwd, configPathOpt) {
     registerTsResolve();
-    // 사용자가 --config <path> 를 준 경우 그 경로에서 default export 를 로드한다.
-    // 없으면 cwd 관례.
-    let configPath;
-    let config;
-    if (opts.configPath) {
-        configPath = resolvePath(opts.configPath);
+    if (configPathOpt) {
+        const configPath = resolvePath(configPathOpt);
         if (!existsSync(configPath)) {
             throw new Error(`[gaon db] --config 로 지정한 파일이 없습니다: ${configPath}\n` +
                 `→ 경로를 확인하거나 --config 없이 실행해 cwd/gaon.config.ts 를 쓰세요.`);
@@ -83,12 +83,25 @@ export async function resolveDbTarget(opts) {
             throw new Error(`[gaon db] --config 파일의 default export 가 객체가 아닙니다: ${configPath}\n` +
                 `→ export default defineConfig({ db: { main: { adapter: 'postgres', url: '...' } } }) 형태로 두세요.`);
         }
-        config = mod.default;
-    }
-    else {
-        configPath = findConfigPath(cwd);
-        config = await loadGaonConfig(cwd);
+        return { config: mod.default, configPath };
     }
+    return { config: await loadGaonConfig(cwd), configPath: findConfigPath(cwd) };
+}
+/**
+ * 프로젝트의 커넥션 키 목록을 돌려준다(결정 139 · `gaon db <sub>` 전 커넥션 순회용).
+ * config.db 에 선언된 키 순서 그대로. 선언이 없으면(env-only 프로젝트) `['main']`
+ * 폴백(GAON_DATABASE_URL 관례) — 단일 커넥션 프로젝트의 종전 동작과 정합.
+ */
+export async function listConnectionKeys(cwd, configPath) {
+    const { config } = await loadDbConfig(resolvePath(cwd), configPath);
+    const keys = Object.keys(config.db ?? {});
+    return keys.length ? keys : ['main'];
+}
+export async function resolveDbTarget(opts) {
+    const cwd = resolvePath(opts.cwd);
+    // 사용자가 --config <path> 를 준 경우 그 경로에서 default export 를 로드한다.
+    // 없으면 cwd 관례.
+    const { config, configPath } = await loadDbConfig(cwd, opts.configPath);
     const dbKey = opts.dbKey;
     const cfg = config.db?.[dbKey];
     let connCfg;

package/dist/doctor/connections.d.ts

@@ -5,7 +5,29 @@ interface KeyUse {
     readonly line: number;
     readonly kind: 'table' | 'getConnection';
 }
-/** gaon.config.ts 를 정적 AST 로 파싱해 db 커넥션 키 목록을 뽑는다. */
+/** gaon.config.ts 정적 분석 결과(결정 135). keys = 뽑아낸 커넥션 키, dbDeclared =
+ * db 프로퍼티 존재 여부, unanalyzable = db 초기화식에 정적으로 못 읽는 부분(식별자
+ * 참조·함수 호출 등)이 섞여 있었는지. unanalyzable 이면 커넥션 검사가 커버리지를
+ * 보장할 수 없어 doctor 가 안내를 낸다(W2). */
+export interface ConfigDbAnalysis {
+    readonly keys: string[];
+    readonly dbDeclared: boolean;
+    readonly unanalyzable: boolean;
+}
+/**
+ * gaon.config.ts 를 정적 AST 로 파싱해 db 커넥션 키를 분석한다(결정 135 · W2).
+ *
+ * 객체 리터럴뿐 아니라 스캐폴드·실사용에서 흔한 형태를 모두 훑는다:
+ *  - `db: { main: {...} }`                         → ['main']
+ *  - `db: process.env.X ? { main:{...} } : undefined` → 삼항 양 분기(결정 135)
+ *  - `db: cfg ?? { main:{...} }` · `a && { ... }`   → ?? · && · || 양변
+ *  - `db: ({ main:{...} })`                          → 괄호 벗김
+ *  - `db: { main, legacy }`(shorthand)              → ['main','legacy']
+ * 못 읽는 형태(식별자 참조·함수 호출·스프레드)는 unanalyzable=true 로 표시한다 —
+ * "키 0" 로 조용히 통과시키던(main 폴백) 스캐폴드 삼항 사각(W2 근본)을 없앤다.
+ */
+export declare function analyzeConfigDb(source: string): ConfigDbAnalysis;
+/** 하위 호환 — db 커넥션 키만 돌려준다(analyzeConfigDb 위임). */
 export declare function extractConfigDbKeys(source: string): string[];
 /** 소스에서 table(name, defs, { db: 'X' }) 와 getConnection('X') 호출을 추출한다. */
 export declare function extractKeyUses(cwd: string, file: string, source: string): KeyUse[];

package/dist/doctor/connections.js

@@ -13,26 +13,77 @@ import { existsSync } from 'node:fs';
 import { readdir, readFile } from 'node:fs/promises';
 import { join, relative } from 'node:path';
 import ts from 'typescript';
-/** gaon.config.ts 를 정적 AST 로 파싱해 db 커넥션 키 목록을 뽑는다. */
-export function extractConfigDbKeys(source) {
+/**
+ * gaon.config.ts 를 정적 AST 로 파싱해 db 커넥션 키를 분석한다(결정 135 · W2).
+ *
+ * 객체 리터럴뿐 아니라 스캐폴드·실사용에서 흔한 형태를 모두 훑는다:
+ *  - `db: { main: {...} }`                         → ['main']
+ *  - `db: process.env.X ? { main:{...} } : undefined` → 삼항 양 분기(결정 135)
+ *  - `db: cfg ?? { main:{...} }` · `a && { ... }`   → ?? · && · || 양변
+ *  - `db: ({ main:{...} })`                          → 괄호 벗김
+ *  - `db: { main, legacy }`(shorthand)              → ['main','legacy']
+ * 못 읽는 형태(식별자 참조·함수 호출·스프레드)는 unanalyzable=true 로 표시한다 —
+ * "키 0" 로 조용히 통과시키던(main 폴백) 스캐폴드 삼항 사각(W2 근본)을 없앤다.
+ */
+export function analyzeConfigDb(source) {
     const sf = ts.createSourceFile('gaon.config.ts', source, ts.ScriptTarget.ES2022, true);
     const keys = [];
+    let dbDeclared = false;
+    let unanalyzable = false;
+    const collect = (node) => {
+        if (ts.isParenthesizedExpression(node))
+            return collect(node.expression);
+        if (ts.isObjectLiteralExpression(node)) {
+            for (const dp of node.properties) {
+                if (ts.isPropertyAssignment(dp)) {
+                    const n = propNameText(dp.name);
+                    if (n)
+                        keys.push(n);
+                    else
+                        unanalyzable = true; // 계산된 키 등
+                }
+                else if (ts.isShorthandPropertyAssignment(dp)) {
+                    keys.push(dp.name.text);
+                }
+                else {
+                    unanalyzable = true; // 스프레드·메서드 등
+                }
+            }
+            return;
+        }
+        if (ts.isConditionalExpression(node)) {
+            collect(node.whenTrue);
+            collect(node.whenFalse);
+            return;
+        }
+        if (ts.isBinaryExpression(node)) {
+            const op = node.operatorToken.kind;
+            if (op === ts.SyntaxKind.QuestionQuestionToken ||
+                op === ts.SyntaxKind.BarBarToken ||
+                op === ts.SyntaxKind.AmpersandAmpersandToken) {
+                collect(node.left);
+                collect(node.right);
+                return;
+            }
+            unanalyzable = true;
+            return;
+        }
+        // `undefined` · `null` 분기 = 커넥션 없음(분석 가능 · 키 기여 0).
+        if (node.kind === ts.SyntaxKind.NullKeyword)
+            return;
+        if (ts.isIdentifier(node) && node.text === 'undefined')
+            return;
+        // 그 외(식별자 참조·함수 호출 등) = 정적으로 못 읽음.
+        unanalyzable = true;
+    };
     const visit = (node) => {
-        // defineConfig({ db: { main: {...}, legacy: {...} } })
         if (ts.isCallExpression(node) && isDefineConfig(node.expression)) {
             const arg = node.arguments[0];
             if (arg && ts.isObjectLiteralExpression(arg)) {
                 for (const p of arg.properties) {
                     if (ts.isPropertyAssignment(p) && propNameText(p.name) === 'db') {
-                        if (ts.isObjectLiteralExpression(p.initializer)) {
-                            for (const dp of p.initializer.properties) {
-                                if (ts.isPropertyAssignment(dp)) {
-                                    const n = propNameText(dp.name);
-                                    if (n)
-                                        keys.push(n);
-                                }
-                            }
-                        }
+                        dbDeclared = true;
+                        collect(p.initializer);
                     }
                 }
             }
@@ -40,7 +91,11 @@ export function extractConfigDbKeys(source) {
         ts.forEachChild(node, visit);
     };
     visit(sf);
-    return keys;
+    return { keys, dbDeclared, unanalyzable };
+}
+/** 하위 호환 — db 커넥션 키만 돌려준다(analyzeConfigDb 위임). */
+export function extractConfigDbKeys(source) {
+    return analyzeConfigDb(source).keys;
 }
 function isDefineConfig(e) {
     if (ts.isIdentifier(e) && e.text === 'defineConfig')
@@ -107,8 +162,24 @@ export async function checkConnections(cwd) {
     const configPath = findConfigPath(cwd);
     if (configPath) {
         const src = await readFile(configPath, 'utf8');
-        for (const k of extractConfigDbKeys(src))
+        const analysis = analyzeConfigDb(src);
+        for (const k of analysis.keys)
             registered.add(k);
+        // W2(결정 135): db 가 선언됐는데 정적으로 못 읽는 형태면 커넥션 검사가
+        // 등록 키를 놓쳐 오탐/사각이 생긴다 — "main 만 허용" 으로 조용히 통과하지 말고
+        // 안내한다(에러 = 수리 안내서 · §7.5.3).
+        if (analysis.dbDeclared && analysis.unanalyzable) {
+            issues.push({
+                rule: 'connections',
+                level: 'warning',
+                file: relative(cwd, configPath),
+                message: `gaon.config.ts 의 db 설정을 정적으로 읽지 못했습니다 — 커넥션 키 검사가 불완전할 수 있습니다.\n` +
+                    `읽어낸 키: ${analysis.keys.length ? analysis.keys.join(', ') : '(없음)'}\n` +
+                    `→ db 를 리터럴 객체로 두세요(키는 리터럴 · 값만 env). 예:\n` +
+                    `    db: { main: { adapter: 'postgres', url: process.env.DATABASE_URL ?? '' } }`,
+                detail: { kind: 'unanalyzable-db', keys: analysis.keys },
+            });
+        }
     }
     const files = [];
     await collectTsFiles(join(cwd, 'domain'), files);

package/dist/doctor/schema-relations.d.ts

@@ -0,0 +1,7 @@
+import type { RuleReport } from './types.js';
+/**
+ * 프로젝트 전체의 §4.5 관계 제약을 검사한다. domain/schema 가 없으면 통과.
+ * 스키마 로드 실패(문법 오류 등)는 이 검사만 warning 으로 강등하고 안내한다 —
+ * connections(static)·gaon check(typecheck)가 별도로 원인을 짚는다.
+ */
+export declare function checkSchemaRelations(cwd: string): Promise<RuleReport>;

package/dist/doctor/schema-relations.js

@@ -0,0 +1,114 @@
+// @gaonjs/cli · doctor · 스키마 관계 검사 배선 (§4.5 · 결정 134)
+//
+// @gaonjs/data 의 checkCrossConnectionRelations·checkRelationTargets 를 `gaon
+// doctor` 러너에 배선한다. 이 검사들은 이미 data 패키지에 구현+테스트가 완비돼
+// 있었으나 CLI 러너가 호출하지 않아 커넥션을 가로지르는 belongsTo 가 doctor 로
+// 잡히지 않고 배포 후 raw postgres 에러로만 드러났다 — "미구현"이 아니라
+// "배선 안 됨"(§13.9 "단위 green ≠ 개발자 도달" 4번째 사례 · 결정 134).
+//
+// connections 검사(static AST)와 달리 관계 그래프는 TableDef 값(참조 컬럼·db
+// 키·역방향 관계)이 필요하다. 그래서 domain/schema/*.ts 를 실제 로드해 TableDef[]
+// 를 모은다 — `gaon db diff`·`migrate` 와 같은 스키마 로드 경로(scanSchemaDir).
+// 커넥션으로 걸러내지 않고 **전 커넥션 테이블을 함께** 봐야 커넥션을 가로지르는
+// belongsTo 를 검출할 수 있다(resolve.ts scanTables 는 단일 dbKey 로 거르므로 부적합).
+import { existsSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { scanSchemaDir, checkCrossConnectionRelations, checkRelationTargets, } from '@gaonjs/data';
+import { registerTsResolve } from '../tsResolve.js';
+/** TableDef 판별 — scanSchemaDir 이 준 모듈 네임스페이스에서 table() 산출만 고른다. */
+function isTableDef(v) {
+    return (typeof v === 'object' &&
+        v !== null &&
+        'name' in v &&
+        'defs' in v &&
+        'db' in v &&
+        typeof v.name === 'string');
+}
+/**
+ * domain/schema/ 의 모든 TableDef 를 커넥션 구분 없이 로드하고, 각 테이블이
+ * 어느 소스 파일에서 왔는지 함께 기록한다(진단에 파일 위치를 붙이기 위함).
+ */
+async function loadAllTables(cwd, schemaDir) {
+    registerTsResolve();
+    // outDir 은 import 지정자 계산에만 쓰이고 파일을 쓰지 않는다(resolve.ts 관례).
+    const outDir = join(cwd, '.gaon');
+    const modules = await scanSchemaDir(schemaDir, outDir);
+    const tables = [];
+    const fileOf = new Map();
+    for (const mod of modules) {
+        // importPath 는 .gaon 기준 상대(./../domain/schema/x.js) — 사람이 읽을 프로젝트
+        // 상대 경로로 정규화한다(진단 file 필드는 cwd 상대 관례).
+        const relFile = importPathToProjectRel(cwd, outDir, mod.importPath);
+        for (const [, value] of Object.entries(mod.ns)) {
+            if (isTableDef(value)) {
+                tables.push(value);
+                if (!fileOf.has(value.name))
+                    fileOf.set(value.name, relFile);
+            }
+        }
+    }
+    tables.sort((a, b) => a.name.localeCompare(b.name));
+    return { tables, fileOf };
+}
+/** scanSchemaDir 의 importPath(.gaon 기준, .js)를 cwd 상대 .ts 경로로 되돌린다. */
+function importPathToProjectRel(cwd, outDir, importPath) {
+    const abs = join(outDir, importPath).replace(/\.js$/, '.ts');
+    return relative(cwd, abs).replace(/\\/g, '/');
+}
+/** data 의 Diagnostic 를 doctor 의 DoctorCheck 로 변환한다(§4.5 → RuleReport 정합). */
+function toCheck(d, fileOf, owner) {
+    const file = fileOf.get(owner);
+    return {
+        rule: 'schema-relations',
+        level: d.level === 'warning' ? 'warning' : 'error',
+        message: d.message,
+        ...(file ? { file } : {}),
+        detail: { code: d.code, table: owner },
+    };
+}
+/**
+ * 관계 진단이 어느 테이블 소유인지를 message 앞머리(`<table>.<...>`)에서 뽑아
+ * 파일을 붙인다. 관계·컬럼 검사 모두 "테이블명.멤버 …" 로 시작한다.
+ */
+function ownerOf(message) {
+    const m = message.match(/^([A-Za-z0-9_]+)\./);
+    return m ? m[1] : '';
+}
+/**
+ * 프로젝트 전체의 §4.5 관계 제약을 검사한다. domain/schema 가 없으면 통과.
+ * 스키마 로드 실패(문법 오류 등)는 이 검사만 warning 으로 강등하고 안내한다 —
+ * connections(static)·gaon check(typecheck)가 별도로 원인을 짚는다.
+ */
+export async function checkSchemaRelations(cwd) {
+    const schemaDir = join(cwd, 'domain', 'schema');
+    if (!existsSync(schemaDir))
+        return { rule: 'schema-relations', issues: [] };
+    let tables;
+    let fileOf;
+    try {
+        ;
+        ({ tables, fileOf } = await loadAllTables(cwd, schemaDir));
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            rule: 'schema-relations',
+            issues: [
+                {
+                    rule: 'schema-relations',
+                    level: 'warning',
+                    message: `스키마 관계 검사를 건너뜁니다 — domain/schema 로드 실패: ${msg}\n` +
+                        `→ 'gaon check' 로 타입 오류를 먼저 확인하세요(스키마가 컴파일되면 이 검사가 활성화됩니다).`,
+                    detail: { skipped: true },
+                },
+            ],
+        };
+    }
+    // data 패키지 구현을 그대로 호출한다(재구현 금지 · 결정 134).
+    const diags = [
+        ...checkCrossConnectionRelations(tables),
+        ...checkRelationTargets(tables),
+    ];
+    const issues = diags.map((d) => toCheck(d, fileOf, ownerOf(d.message)));
+    return { rule: 'schema-relations', issues };
+}

package/dist/doctor/types.d.ts

@@ -1,4 +1,4 @@
-export type DoctorRule = 'response-mixing' | 'n-plus-one' | 'dependency-direction' | 'connections' | 'migration-diff' | 'shared-composable-purity' | 'no-auto-import' | 'schema-filename' | 'agents-doc-index' | 'column-casing' | 'model-filename' | 'page-filename' | 'auth-wiring' | 'ui-kit-wiring' | 'route-registration' | 'static-collision' | 'method-override' | 'csrf-wiring' | 'internal-anchor' | 'pageprops-destructure' | 'async-offload' | 'page-layout-breakpoint' | 'link-button-nesting' | 'seal-security';
+export type DoctorRule = 'response-mixing' | 'n-plus-one' | 'dependency-direction' | 'connections' | 'migration-diff' | 'shared-composable-purity' | 'no-auto-import' | 'schema-filename' | 'agents-doc-index' | 'column-casing' | 'model-filename' | 'page-filename' | 'auth-wiring' | 'ui-kit-wiring' | 'route-registration' | 'static-collision' | 'method-override' | 'csrf-wiring' | 'internal-anchor' | 'pageprops-destructure' | 'async-offload' | 'page-layout-breakpoint' | 'link-button-nesting' | 'seal-security' | 'schema-relations';
 export type DoctorLevel = 'passed' | 'warning' | 'error';
 export interface DoctorCheck {
     readonly rule: DoctorRule;

package/dist/doctor/types.js

@@ -1,6 +1,6 @@
 // @gaonjs/cli · doctor 공용 타입 (M9-E · M9-E-Fix · M9-E 확장 · E-5)
 //
-// 21 검사(전체 목록은 AGENTS §2.2 · doctor.ts `ALL_RULES`)가 모두 이 DoctorCheck
+// 25 검사(전체 목록은 AGENTS §2.2 · doctor.ts `ALL_RULES`)가 모두 이 DoctorCheck
 // 를 낸다. 상위(runDoctorCommand)는 level 로 passed/
 // warnings/errors 로 갈라 담는다. 자동화(CI)는 JSON 을 파싱해
 // errors.length > 0 이면 fail 로 판단한다.

package/dist/doctor.d.ts

@@ -4,7 +4,8 @@ export type { ResponseKind, ActionUsage } from './doctor/response-mixing.js';
 export { inspectControllerSource, checkResponseMixing } from './doctor/response-mixing.js';
 export { inspectControllerForNPlusOne, checkNPlusOne } from './doctor/n-plus-one.js';
 export { extractRelativeImports, checkDependencyDirection } from './doctor/dependency-direction.js';
-export { extractConfigDbKeys, extractKeyUses, checkConnections } from './doctor/connections.js';
+export { extractConfigDbKeys, analyzeConfigDb, extractKeyUses, checkConnections, } from './doctor/connections.js';
+export { checkSchemaRelations } from './doctor/schema-relations.js';
 export { scanSchema, checkMigrationDiff } from './doctor/migration-diff.js';
 export { inspectSharedComposable, checkSharedComposablePurity, } from './doctor/shared-composable-purity.js';
 export { inspectConfigForAutoImport, inspectPackageJson, checkNoAutoImport, } from './doctor/no-auto-import.js';

package/dist/doctor.js

@@ -1,7 +1,7 @@
 /**
  * @gaonjs/cli · `gaon doctor` — 정적 검사 (M9-E · CLI DX 완성 · E-5 확장)
  *
- * 23 검사를 조립한다:
+ * 25 검사를 조립한다:
  *  1) response-mixing (errata E-3 §C · 라이브)
  *  2) n-plus-one (errata E-4 (e))
  *  3) dependency-direction (CLAUDE.md §5 · 4 규칙)
@@ -25,6 +25,8 @@
  * 21) async-offload (결정 102·103 · 컨트롤러 인라인 메일·이미지·외부 HTTP = 응답 지연 경고)
  * 22) page-layout-breakpoint (결정 107 · 페이지 레이아웃 브레이크포인트 직접 사용 = 안내 경고)
  * 23) link-button-nesting (결정 113 · Link 로 Button 감싸기 = <a><button> 중첩 경고)
+ * 24) seal-security (결정 121 · seal 클라 배선 · 보안 역전)
+ * 25) schema-relations (§4.5 · 결정 134 · 커넥션 가로지르는 belongsTo·관계 · 대상 부재 error)
  *
  * 각 검사는 순수 함수(cwd → RuleReport). 상위 runDoctorCommand 가 조립해
  * DoctorResult 로 낸다. --json 은 자동화(CI)를 위해 반드시 파싱 가능한
@@ -41,6 +43,7 @@ import { checkResponseMixing } from './doctor/response-mixing.js';
 import { checkNPlusOne } from './doctor/n-plus-one.js';
 import { checkDependencyDirection } from './doctor/dependency-direction.js';
 import { checkConnections } from './doctor/connections.js';
+import { checkSchemaRelations } from './doctor/schema-relations.js';
 import { checkMigrationDiff } from './doctor/migration-diff.js';
 import { checkSharedComposablePurity } from './doctor/shared-composable-purity.js';
 import { checkNoAutoImport } from './doctor/no-auto-import.js';
@@ -68,7 +71,8 @@ import { FIXERS, FIXER_CAPABILITIES } from './doctor/fixers/index.js';
 export { inspectControllerSource, checkResponseMixing } from './doctor/response-mixing.js';
 export { inspectControllerForNPlusOne, checkNPlusOne } from './doctor/n-plus-one.js';
 export { extractRelativeImports, checkDependencyDirection } from './doctor/dependency-direction.js';
-export { extractConfigDbKeys, extractKeyUses, checkConnections } from './doctor/connections.js';
+export { extractConfigDbKeys, analyzeConfigDb, extractKeyUses, checkConnections, } from './doctor/connections.js';
+export { checkSchemaRelations } from './doctor/schema-relations.js';
 export { scanSchema, checkMigrationDiff } from './doctor/migration-diff.js';
 export { inspectSharedComposable, checkSharedComposablePurity, } from './doctor/shared-composable-purity.js';
 export { inspectConfigForAutoImport, inspectPackageJson, checkNoAutoImport, } from './doctor/no-auto-import.js';
@@ -115,6 +119,7 @@ const ALL_RULES = [
     'page-layout-breakpoint',
     'link-button-nesting',
     'seal-security',
+    'schema-relations',
 ];
 const CHECKERS = {
     'response-mixing': checkResponseMixing,
@@ -141,6 +146,7 @@ const CHECKERS = {
     'page-layout-breakpoint': checkPageLayoutBreakpoint,
     'link-button-nesting': checkLinkButtonNesting,
     'seal-security': checkSealSecurity,
+    'schema-relations': checkSchemaRelations,
 };
 /**
  * 규칙을 순서대로 실행해 RuleReport[] 를 낸다. 규칙 하나가 크래시해도 나머지는

package/dist/index.js

@@ -104,7 +104,7 @@ function renderHelp(version = VERSION) {
         "    gaon gen           .gaon 타입 브리지 + api() 런타임 매니페스트만 재생성 (서버·검사 없이 · build 전제 · --json)",
         "    gaon console       프로젝트 컨텍스트 REPL (--no-config)",
         "    gaon test          테스트 러너 (테스트 DB <db>_test 자동 생성·마이그레이션 후 vitest · --scope unit|integration|all · -- vitest 인자)",
-        "    gaon doctor        정적 검사 (24 검사 · 응답 혼용·N+1·의존·커넥션·마이그·컴포저블 순수·자동 import·파일명/컬럼 관례·인증 배선·UI 킷 배선·라우트 등록·정적 충돌·_method·CSRF 배선·내부 앵커·pageProps 구조분해·비동기 오프로드·페이지 레이아웃 브레이크포인트·Link>Button 중첩·seal 클라 배선·보안 역전)",
+        "    gaon doctor        정적 검사 (25 검사 · 응답 혼용·N+1·의존·커넥션·마이그·컴포저블 순수·자동 import·파일명/컬럼 관례·인증 배선·UI 킷 배선·라우트 등록·정적 충돌·_method·CSRF 배선·내부 앵커·pageProps 구조분해·비동기 오프로드·페이지 레이아웃 브레이크포인트·Link>Button 중첩·seal 클라 배선·보안 역전·§4.5 관계)",
         "    gaon doctor --json                        자동화용 JSON 출력",
         "    gaon doctor --check=n-plus-one,connections  선택 검사만 실행",
         "    gaon doctor --fix                         기계 정정 가능한 위반 계획(dry-run · v0.16 §7.5.3)",
@@ -121,8 +121,8 @@ function renderHelp(version = VERSION) {
         "    gaon work          워커 프로세스 (잡·리스너·스케줄·아웃박스 · graceful drain)",
         "    gaon jobs list --failed   DLQ(실패 잡) 목록",
         "    gaon jobs retry <id>      DLQ 잡 재적재",
-        "    gaon db diff              스키마 ↔ DB 차이 미리보기 (적용 X · --json · --db <키>)",
-        "    gaon db migrate           db/migrations/*.ts replay + 스키마 diff 적용 + 이력",
+        "    gaon db diff              스키마 ↔ DB 차이 미리보기 (적용 X · 전 커넥션 순회 · --db <키> 로 단일)",
+        "    gaon db migrate           db/migrations/*.ts replay + 스키마 diff 적용 + 이력 (전 커넥션 순회 · --db <키> 로 단일)",
         "    gaon db migrate down      가장 최근 이력 한 건 롤백",
         "    gaon db migrate --dry-run 적용 없이 실행 예정 파일 + up SQL 만 출력",
         "    gaon db status            마이그레이션 파일 적용/대기 + 스키마 drift",
@@ -344,7 +344,7 @@ export function runCli(argv, opts = {}) {
         if (!sub || !known.includes(sub)) {
             process.stderr.write(`  ✗ 알 수 없는 db 서브커맨드: ${sub ?? "(없음)"}\n` +
                 `  → 지원: gaon db diff | migrate | reset | seed | status\n` +
-                `  → 옵션: --json · --db <키> · --config <path> · --yes · --dry-run\n`);
+                `  → 옵션: --json · --db <키>(생략 = 전 커넥션 순회) · --config <path> · --yes · --dry-run\n`);
             process.exitCode = 1;
             return;
         }

package/dist/templates/project/.env.example.tpl

@@ -10,6 +10,14 @@ REDIS_URL=redis://127.0.0.1:6379
 # NATS — 실시간·비동기 백본(§7).
 NATS_URL=nats://127.0.0.1:4222
 
+# 파일 스토리지(§7 · M8) — docker-compose.yaml 의 minio 서비스와 정합.
+# STORAGE_BUCKET 은 compose 의 createbuckets 가 만드는 dev 버킷명과 같아야 한다.
+# 운영은 R2/S3 endpoint·자격증명으로 교체하고, 버킷은 인프라에서 사전 생성한다.
+STORAGE_ENDPOINT=http://127.0.0.1:9000
+STORAGE_BUCKET={{PROJECT_NAME}}
+STORAGE_ACCESS_KEY={{PROJECT_NAME}}
+STORAGE_SECRET_KEY={{PROJECT_NAME}}_secret
+
 # 세션 · 쿠키 서명 비밀 (32자 이상, 운영은 반드시 교체).
 SESSION_SECRET=change-me-to-a-32-char-random-secret!!
 COOKIE_SECRET=change-me-too-32-char-random-secret!!

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

@@ -26,6 +26,7 @@ v0.15+errata→v0.16→v0.17 · 결정 31~89)이며, 관례 문서는 **2층 구
 | 페이지 · 컴포넌트 · 컴포저블 · 레이아웃 · `api()` · bigint key | `agents/frontend.md` |
 | 잡 · 이벤트 · 리스너 · 아웃박스 · 스케줄 | `agents/async.md` |
 | 채널 · 프레즌스 · 허브 | `agents/realtime.md` |
+| 파일 스토리지 (`Storage.put/url` · s3Disk · presigned · CSP 자동 배선) | `agents/storage.md` |
 | 테스트 작성·실행 (실 인프라 · `expectJobProcessed`) | `agents/testing.md` |
 | 보안 기본값 · 탈출구(v-html · raw SQL) 사용 | `agents/security.md` |
 | 페이로드 봉인 (`@gaonjs/seal` · wire/문서/WS 암호화 · 선택 플러그인) | `agents/seal.md` |
@@ -105,12 +106,12 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
   컬럼명 · 스키마 파일 ↔ 테이블 ↔ `tables.d.ts` 키 변환 규칙)은
   `agents/data.md` "DB 네이밍" 표가 정본이다 — 먼저 읽는다.
 
-### 2.2 `gaon doctor` 검사 24종
+### 2.2 `gaon doctor` 검사 25종
 
 1. `response-mixing` — 한 액션 안 render/JSON/redirect 혼용 (E-3)
 2. `n-plus-one` — include 미사용 · loop 안 관계 호출 (E-4)
 3. `dependency-direction` — 의존 방향 4규칙 위반
-4. `connections` — 커넥션 간 belongsTo · service 트랜잭션 (§4.5)
+4. `connections` — 스키마·`getConnection` 이 쓰는 커넥션 키가 `gaon.config.ts` 에 등록됐는지 · db 설정 정적 분석(삼항·`??` 지원 · 못 읽으면 안내) (§4.5 · 결정 135)
 5. `migration-diff` — 스키마 vs DB 상태 불일치
 6. `shared-composable-purity` — shared 안 `api`/`pageProps` import (결정 25)
 7. `no-auto-import` — 자동 import 설정 (E-5 §2.4)
@@ -131,6 +132,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 check --fix` 의 `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`)
 
 ## 3. 로직 배치 One Way 판단표
 
@@ -219,7 +221,10 @@ gaon doctor       # 정적 검사 24종 (§2.2)
 
 **스케일링 구분** — `serve --workers N`(한 포트 · node:cluster 수직) vs 웹 인스턴스
 여러 대(각각 다른 `PORT` · 허브 뒤 수평) vs `work`(포트 없음 · 프로세스만)는 서로
-다르다. 로컬 멀티 인스턴스 레시피·구분표는 `docs/guides/operations.md` "스케일링" 절 참고.
+다르다. 워커 다중화 시 스케줄 발행=단일 리더 · 소비=워커 분산 계약은
+`agents/async.md` §5 "리더 선출 계약" 이 정본이다(exactly-once 발행 · `gaon serve`
+는 스케줄러 미실행). 로컬 멀티 인스턴스 레시피·구분표는 프레임웍 문서
+`gaonjs.dev` 의 operations 가이드(`docs/guides/operations.md`)를 참고한다.
 
 ## 5. npm 배포본 — 패키지 → 역할
 
@@ -258,8 +263,9 @@ gaon doctor       # 정적 검사 24종 (§2.2)
   이력 동결 = `gaondesignv0.16.md`·`v0.15.md` + errata E-1~E-5
   (E-1 파사드명 · E-2 실시간 TCP · E-3 JSON 액션/params · E-4 컬럼·
   체이닝 · E-5 컴포저블·레이아웃).
-- 가이드: `docs/guides/*.md` (getting-started · data · data-flow ·
-  serialization · authentication · realtime · async · pipeline ·
-  operations · configuration).
+- 가이드(프레임웍 문서 · `gaonjs.dev` · 사용자 프로젝트엔 동봉 안 됨):
+  getting-started · data · data-flow · serialization · authentication ·
+  realtime · async · pipeline · operations · configuration. 작업별 정본은
+  위 §0 표의 `agents/*.md`(스캐폴드에 동봉) 를 먼저 읽는다.
 - 프레임웍 구현 저장소의 AI 지침은 `CLAUDE.md` — 이 문서와 대상이
   다르다 (CLAUDE = 프레임웍 구현자용, AGENTS = 프레임웍 사용자용).

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

@@ -226,6 +226,23 @@ export default schedule((s) => {
 | `s.daily.at('HH:MM', Job)` | 매일 지정 시각 |
 | `s.cron('분 시 일 월 요일', Job)` | 5필드 크론 표현식 |
 
+#### 리더 선출 계약 (정본)
+
+여러 `gaon work` 인스턴스를 HA 로 띄워도 스케줄이 중복 발행되지 않는 이유:
+
+- **스케줄 발행 = 단일 리더** — 워커들이 NATS KV 리스(lease)로 리더 하나를
+  선출하고, 그 리더만 `s.every`·`s.cron` 시각에 잡을 **발행**한다. 리더가
+  죽으면 리스가 만료돼 다른 워커가 승계한다(active-standby).
+- **소비 = 워커 전체 분산** — 발행된 잡은 NATS JetStream 큐 그룹으로 **모든**
+  워커에 로드밸런싱된다. 발행은 1인, 처리는 N인.
+- **exactly-once(발행 기준)** — 한 스케줄 틱은 리더 1인이 한 번만 발행한다.
+  잡 자체는 재시도(백오프)가 있으니 **핸들러는 멱등**하게 짠다(같은 잡이 두 번
+  처리돼도 안전하게).
+- **`gaon serve` 는 스케줄러를 돌리지 않는다** — 스케줄·리더 선출·아웃박스
+  릴레이는 **`gaon work` 전용**이다. 웹 프로세스는 잡을 **발행**만 할 수 있고
+  (`.later()`), 처리·스케줄은 워커가 한다. 스케줄이 안 도는 흔한 원인은
+  `gaon work` 를 안 띄운 것이다.
+
 ### 6. 워커 프로세스 (`gaon work`)
 
 잡·리스너·스케줄러·아웃박스 릴레이를 한 프로세스로 조립한다. 운영

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

@@ -340,11 +340,50 @@ const rows = await Post.query()
 ### 7. 멀티 DB 커넥션 (v0.15 §4.5)
 
 - **키 생략 = main** — 기본 경로는 단일 DB 프로젝트와 완전히 같다.
-- **커넥션을 가로지르는 `belongsTo` 는 금지** — doctor 의
-  **connections** 검사가 잡는다.
-- **`service()` 트랜잭션은 단일 커넥션에서만 원자적** — 다중 커넥션
-  접근 시 doctor 경고.
-- 마이그레이션은 커넥션별: `gaon db diff --db legacy`.
+- **커넥션을 가로지르는 `belongsTo`·역방향 관계는 금지** — SQL 조인은
+  커넥션을 못 넘는다. doctor 의 **schema-relations** 검사(결정 134)가
+  `cross-connection-belongsTo`·`cross-connection-relation`·존재하지 않는 관계
+  대상을 **에러**로 잡는다(배포 후 raw postgres 에러 대신 `gaon doctor` 에서).
+  커넥션 키 등록 정합은 **connections** 검사가 본다.
+- **`service()` 트랜잭션은 단일 커넥션에서만 원자적** — Gaon 은 분산
+  트랜잭션을 흉내 내지 않는다(§9 정본).
+- **마이그레이션은 전 커넥션에 걸린다** — `gaon db migrate`(인자 없음)는 등록된
+  **모든** 커넥션을 순회 적용한다(결정 139 · One Way — 커넥션 하나를 잊어 빈 채
+  배포하는 사고 방지). 한 커넥션만 좁히려면 `gaon db migrate --db legacy`.
+  diff·status·seed 도 같은 정책(생략=전 커넥션 · `--db <키>`=단일). reset(파괴적)만
+  항상 단일이다.
+
+#### 두 DB 에 걸친 쓰기 — `afterCommit` 로 잇는다 (정본)
+
+커넥션을 가로지르는 쓰기(예: main 에 주문 저장 → analytics 에 집계 기록)는
+**한 트랜잭션으로 묶을 수 없다**. main 커넥션 트랜잭션을 **먼저 커밋**하고,
+성공한 뒤에만 `afterCommit` 에서 보조 커넥션에 쓴다 — 실패해도 main 은 이미
+안전하고, 재시도·보정은 잡/아웃박스로 다룬다.
+
+```ts
+// domain/services/PlaceOrder.ts — main 커밋 성공 뒤에만 analytics 기록
+import { service, afterCommit } from 'gaonjs/service'
+import { getConnection } from 'gaonjs/data'
+
+export const placeOrder = service(async (input: { userId: string; total: number }) => {
+  const order = await Order.create({ userId: input.userId, total: input.total }) // main 트랜잭션
+
+  // 커넥션을 가로지르는 쓰기는 트랜잭션 밖 — 커밋 성공 뒤에만.
+  afterCommit(async () => {
+    await getConnection('analytics')
+      .insertInto('order_stats')
+      .values({ orderId: order.id, total: input.total })
+      .execute()
+  })
+  return order
+})
+```
+
+- **왜 트랜잭션에 안 넣나** — 두 커넥션에 걸친 원자성은 불가능하다. main 을
+  진실의 원천으로 커밋하고 analytics 는 파생으로 뒤따르게 한다(정합이 중요하면
+  아웃박스/보상 트랜잭션으로 격상).
+- **왜 `afterCommit`** — main 이 롤백되면 analytics 기록도 일어나지 않아야 한다.
+  `afterCommit` 은 커밋이 성공한 경우에만 콜백을 돈다(§9 · `agents/async.md`).
 
 ### 8. 모델 정의 (`model()`) (`packages/data/src/model.ts:601-622`)
 
@@ -504,8 +543,9 @@ export const PublishPost = service(async (postId: bigint) => {
   롤백. 본문 안의 모델 호출은 코드 변경 없이 트랜잭션에 합류한다
   (AsyncLocalStorage 전파). `{ transaction: false }` 로 해제.
 - **커넥션** — `{ db: '키' }` (생략 = main). 트랜잭션은 **단일
-  커넥션에서만 원자적** (§7) — 다른 키의 조회는 트랜잭션 밖에서
-  돌고, doctor 의 **connections** 검사가 다중 커넥션 접근을 경고한다.
+  커넥션에서만 원자적** (§7) — 다른 키에 걸친 쓰기는 트랜잭션 밖에서
+  `afterCommit` 으로 잇는다(§7 "두 DB 에 걸친 쓰기"). 커넥션 키 등록
+  정합은 doctor **connections**, 관계 경계는 **schema-relations** 가 본다.
 - **중첩** — 같은 커넥션 키의 서비스가 서비스를 부르면 바깥
   트랜잭션에 합류한다 (중첩 BEGIN 없음 — 전체가 한 단위).
 - **`afterCommit(fn)`** — 커밋 성공 뒤에만 실행 (롤백 시 실행 안 됨).
@@ -517,14 +557,18 @@ export const PublishPost = service(async (postId: bigint) => {
 ### 10. 마이그레이션 — 파일 리플레이 + 스키마 diff (합성형 · 결정 39)
 
 ```bash
-gaon db diff          # 스키마(domain/schema/*.ts) ↔ 실제 DB 차이 미리보기 (적용 X)
-gaon db migrate       # db/migrations/*.ts replay → 스키마 diff 적용 + _gaon_migrations 이력
+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 실행
+gaon db migrate --db analytics  # 한 커넥션만 좁혀 적용
+gaon db status        # 마이그레이션 파일 적용/대기 + 스키마 drift (전 커넥션)
+gaon db reset --yes   # 초기화 (dev · production 거부 · 항상 단일 커넥션 --db)
+gaon db seed          # domain/seed.ts 실행 (전 커넥션)
 ```
 
+diff/migrate/status/seed 는 `--db` 를 생략하면 **등록된 전 커넥션을 순회**한다
+(결정 139). `gaon db diff`(내부 `_gaon_*` 테이블은 계획에서 제외 · 결정 138).
+
 **기본은 스키마 우선이다.** `domain/schema/*.ts` 를 고치고 `gaon db migrate`
 하면 diff 가 차이를 계산해 반영한다. 여기에 **손작성 마이그레이션 파일**이
 1급으로 합쳐진다(결정 39 · 합성형): `migrate` 는 ① `db/migrations/*.ts` 를

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

@@ -32,6 +32,13 @@
   realtime 허용). 끄거나 조정은 `createApp({ security: { securityHeaders: … } })`
   — `false` 로 전부 끔, `{ contentSecurityPolicy: '…' | false, hsts: false }` 로 조정.
   `helmet` 등 라이브러리를 따로 깔지 말 것(코어 내장 · 라이브러리 미의존).
+- **스토리지 오리진 CSP 자동 배선 (결정 131)** — `gaon.config.ts` 의 storage(S3/R2/MinIO)
+  설정이 있으면 코어가 그 오리진을 CSP 의 **img-src**(스토리지 이미지 `<img>` 표시)·
+  **connect-src**(브라우저 직접 presigned 업로드/다운로드)에 자동으로 더한다(seal→
+  `wasm-unsafe-eval`(결정 124)과 동형). 그래서 스토리지 이미지·직접 업로드를 쓰겠다고
+  **CSP 를 손으로 넓히거나 `contentSecurityPolicy: false` 로 끄지 말 것** — 오리진은
+  storage 설정에서 파생돼 자동으로 허용된다. 오리진은 `endpoint`·`publicUrl` 의
+  scheme+host(+port)만 뽑는다(비절대 URL 이면 부팅 에러 + 수리 안내).
 
 ### 2. 세션·CSRF·JWT
 

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

@@ -0,0 +1,110 @@
+# agents/storage.md — 파일 스토리지 (`Storage` · 디스크 · presigned)
+
+> 골격: **정본 규칙 → 정본 예시 → 알려진 함정 → 관련 결정 번호** (결정 40 · 2층 구조).
+> 루트 `AGENTS.md` 는 코어 요약만 담는다 — 시그니처·표·예시의 정본은 이 파일이다.
+> 대상 패키지: `@gaonjs/storage` (파사드 import 는 `gaonjs/storage`).
+
+## 정본 규칙
+
+### 1. 하나의 API, 여러 디스크
+
+파일은 `Storage` 파사드로 저장·조회한다 — 로컬(`storage/`)이든 S3 호환
+(Cloudflare R2·MinIO·AWS S3)이든 **같은 코드**가 돈다. 디스크는
+`gaon.config.ts` 의 `storage` 로 선언하고, endpoint 만 바꾸면 dev(MinIO) →
+운영(R2/S3) 로 옮겨간다.
+
+| 표면 | 시그니처 | 비고 |
+|---|---|---|
+| 저장 | `Storage.put(key, body, { contentType? })` | body = Buffer·string·Uint8Array |
+| 조회 | `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 |
+| 디스크 선택 | `Storage.disk('s3').put(...)` | 기본 디스크 외 다른 디스크로 |
+
+- **URL 은 `Storage.url()` 한 곳**이다 — `publicUrl`(공개 버킷·CDN·R2 public)이
+  있으면 `${publicUrl}/${key}`, 없으면 만료 있는 **presigned URL** 을 만든다.
+  `expiresIn`(초)로 만료를 조절한다. 존재하지 않는 `Attachment.urlFor` 같은
+  헬퍼를 만들지 말 것 — 표면은 `Storage.url()` 뿐이다.
+- **키는 경로**다(`avatars/${user.id}.png`). 앞 슬래시는 정규화된다.
+
+### 2. 설정 (`gaon.config.ts`)
+
+```ts
+storage: process.env.STORAGE_ENDPOINT
+  ? {
+      default: 'main',
+      disks: {
+        main: {
+          driver: 's3',                              // 's3' | 'local'
+          bucket: process.env.STORAGE_BUCKET ?? 'myapp',
+          endpoint: process.env.STORAGE_ENDPOINT,    // MinIO/R2 = 필수 · AWS S3 = 생략
+          accessKeyId: process.env.STORAGE_ACCESS_KEY,
+          secretAccessKey: process.env.STORAGE_SECRET_KEY,
+          // publicUrl: 'https://cdn.example.com',    // 있으면 url()이 공개 URL
+        },
+      },
+    }
+  : undefined,
+```
+
+- dev 는 compose 의 `createbuckets` 가 버킷을 만들어 **첫 업로드부터 동작**한다
+  (결정 132 · zero-config). `cp .env.example .env && gaon dev` → 우회 0.
+- 로컬 디스크: `{ driver: 'local', root: 'storage', publicUrl?: '/uploads' }`.
+- 운영(R2/S3)은 인프라에서 버킷을 사전 생성한다(앱 밖 관심사) — endpoint·creds
+  만 env 로 바꾼다.
+
+### 3. 업로드 (multipart)
+
+컨트롤러에서 `this.file('필드명')` 으로 업로드 파일을 받아 그대로 저장한다:
+
+```ts
+// apps/web/controllers/profile.ts
+export default controller({
+  async updateAvatar() {
+    const f = this.file('avatar')                     // UploadedFile | undefined
+    if (!f) return this.back().withErrors({ avatar: '파일이 필요합니다.' })
+    const key = `avatars/${this.auth.user!.id}.png`
+    await Storage.put(key, f.buffer, { contentType: f.mimetype })
+    return this.redirect('/profile')
+  },
+})
+```
+
+- **멀티파트 폼의 CSRF 는 `x-csrf-token` 헤더 전용**이다(결정 133 · 구조적).
+  `useForm(...).post(url, { headers: { 'x-csrf-token': shared.csrf } })` 로 보낸다 —
+  바디 `_csrf` 는 멀티파트에서 안 걸린다(상세는 `agents/web.md` §3).
+
+### 4. 스토리지 오리진 CSP 자동 배선 (결정 131)
+
+`storage` 에 s3 디스크가 있으면 프레임웍이 그 오리진을 **CSP 에 자동 배선**한다 —
+`endpoint` 는 `connect-src`(브라우저 직접 presigned PUT/GET)와 `img-src` 에,
+`publicUrl` 은 `img-src` 에 붙는다. 이미지 표시·직접 업로드가 CSP 로 막히지
+않으므로 **CSP 를 손으로 넓히지 말 것**. 오리진은 scheme+host+port 만 잡는다.
+
+### 5. 스토리지를 쓰는 잡·테스트
+
+- 무거운 처리(썸네일·외부 업로드)는 컨트롤러 인라인 대신 `domain/jobs/` 잡으로
+  뺀다(`agents/async.md` 판단표 · doctor `async-offload` 경고). 잡·워커(`gaon work`)도
+  `wireDomain` 으로 스토리지가 배선돼 있어 `Storage.*` 가 그대로 돈다(결정 129).
+- 테스트에서도 `gaon test` 하네스가 스토리지를 배선한다(결정 136) — s3 버킷은
+  `<bucket>-test`, 로컬 root 는 `<root>-test` 로 격리된다(`<db>_test` 대칭 ·
+  `agents/testing.md`). 스토리지 잡 테스트는 스캐폴드 `test/setup.ts` 그대로 통과한다.
+
+## 알려진 함정
+
+- **존재하지 않는 API 를 상상하지 말 것** — 파일 URL 은 `Storage.url()`,
+  저장은 `Storage.put()` 뿐이다. `Attachment.urlFor`·`Storage.signedUrl` 등은 없다.
+- **`Storage.url()` 은 async** 다 — `await` 를 빠뜨리면 `[object Promise]` 가 렌더된다.
+- **버킷 미준비 = `NoSuchBucket`** — dev 는 compose `createbuckets` 가, 운영은
+  인프라가 버킷을 만든다. 프레임웍은 런타임에 버킷을 만들지 않는다(결정 132).
+- **멀티파트 업로드를 일반 폼처럼 `_csrf` 바디 필드로 보내면 403** — 헤더로
+  옮긴다(결정 133).
+
+## 관련 결정 번호
+
+- 결정 131 — 스토리지 오리진 CSP 자동 배선(img-src·connect-src).
+- 결정 132 — dev 버킷 zero-config(compose `createbuckets` · 런타임 버킷 생성 안 함).
+- 결정 133 — 멀티파트 CSRF = `x-csrf-token` 헤더 전용(구조적).
+- 결정 129 — `gaon work` 도 `wireDomain` 으로 스토리지·메일 배선(운영 워커).
+- 결정 136 — `gaon test` 하네스가 스토리지·메일을 테스트 격리 값으로 배선.

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

@@ -92,22 +92,36 @@ describe('SendWelcomeMail (실 NATS JetStream)', () => {
 DB 테스트는 손으로 커넥션을 배선하지 않는다 — `gaon test` 와 스캐폴드
 `test/setup.ts` 가 The One Way 를 제공한다:
 
-- `gaon test` 가 테스트 전용 DB(`<db>_test`)를 만들고 마이그레이션한다.
-- `test/setup.ts` 가 그 DB 에 붙고(`connectTestDatabase`) 매 테스트 뒤
-  전 테이블을 비운다(`truncateAll`) — 새 테스트는 항상 빈 DB 에서 시작한다.
+- `gaon test` 가 각 커넥션의 테스트 전용 DB(`<db>_test`)를 만들고 마이그레이션한다.
+- `test/setup.ts` 가 그 DB 들에 붙고(`connectTestDatabase`) 매 테스트 뒤
+  **등록된 모든 커넥션**의 테이블을 비운다(`truncateAllConnections`) — 새 테스트는
+  항상 빈 DB 에서 시작한다.
+- `connectTestDatabase` 는 DB 뿐 아니라 **스토리지·메일·i18n 도 배선**한다(결정 136)
+  — serve·work 와 같은 경로(`wireDomain`)라, 스토리지·메일을 쓰는 잡·서비스가
+  테스트에서도 그대로 돈다. 스토리지 s3 버킷은 `<bucket>-test`, 로컬 root 는
+  `<root>-test` 로 격리되고(compose `createbuckets` 가 `<PROJECT>-test` 버킷을 만든다),
+  메일은 MailPit(캡처 sink) 그대로다.
 
 스캐폴드가 심어 주는 `test/setup.ts`(수정 불필요):
 
 ```ts
 import { afterAll, afterEach, beforeAll } from 'vitest'
-import { connectTestDatabase, truncateAll, type TestDbHandle } from 'gaonjs/testing'
+import { connectTestDatabase, truncateAllConnections, type TestDbHandle } from 'gaonjs/testing'
 
 let handle: TestDbHandle
 beforeAll(async () => { handle = await connectTestDatabase() })
-afterEach(async () => { await truncateAll() })
+afterEach(async () => { await truncateAllConnections() }) // 보조 커넥션(§4.5)까지 전부 격리
 afterAll(async () => { await handle?.close() })
 ```
 
+- **`truncateAllConnections()` vs `truncateAll('키')`** — 전자는 등록된 **모든**
+  커넥션을 순회한다(멀티 커넥션 격리 · 결정 137). 특정 커넥션만 비우려면
+  `truncateAll('analytics')` 로 좁힌다. `truncateAll()`(인자 생략)은 main 만 비우므로
+  보조 커넥션이 있는 프로젝트는 `truncateAllConnections()` 를 쓴다.
+- **타임아웃** — 실 인프라 왕복(DB·NATS·스토리지)이 기본 전제라 스캐폴드
+  `vitest.config.ts` 는 `testTimeout: 15000`(hookTimeout 포함)으로 둔다 — vitest 기본
+  5s 는 `expectJobProcessed`(10s 대기) 같은 e2e 를 그대로 타임아웃 낸다(결정 137).
+
 그러면 테스트는 격리 코드 없이 모델·서비스를 그대로 부른다:
 
 ```ts

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

@@ -152,6 +152,34 @@ export default controller({
   ①이 검증까지 주므로 **모델이 있으면 ①을 먼저 고른다**. ②는 로그인 폼처럼
   전용 테이블이 없는 입력의 탈출구다.
 
+**멀티파트 업로드 + CSRF — 토큰은 `x-csrf-token` 헤더로만 (결정 133):**
+
+`this.file()` 업로드(멀티파트)의 CSRF 토큰은 **`x-csrf-token` 헤더**로 보낸다.
+멀티파트는 `parts()` 스트리밍이라 CSRF 검사(preHandler) 시점에 **바디가 아직
+파싱되지 않아** 폼 필드 `_csrf` 가 검사에 잡히지 않는다(구조적 한계 · 디스패처가
+handler 안에서 파싱). 일반 폼(JSON/urlencoded)의 `_csrf` 바디 폴백은 멀티파트엔
+통하지 않는다. 파일이 있으면 `useForm` 이 자동으로 multipart 로 보내므로, 업로드
+제출은 **반드시 헤더**로 토큰을 실어야 한다.
+
+```vue
+<script setup lang="ts">
+import { useForm, useShared } from 'gaonjs/vue'
+const shared = useShared()               // csrf 는 자동 주입 공유 prop (결정 116)
+const form = useForm({ avatar: null as File | null })
+
+function submit() {
+  // 파일이 있으면 multipart — csrf 는 x-csrf-token 헤더로(바디 _csrf 는 안 걸림).
+  form.post('/uploads', { headers: { 'x-csrf-token': shared.csrf } })
+}
+</script>
+```
+
+- **알려진 함정:** 업로드 폼을 일반 폼처럼 `useForm({ avatar, _csrf: shared.csrf })`
+  로 짜면 `_csrf` 가 멀티파트 필드로 들어가 **검사 시점에 없어 403** 이 난다. 서버는
+  이 경우 "→ x-csrf-token 헤더로 보내라" 는 수리 안내와 함께 403 을 돌려준다.
+- 비멀티파트 폼은 지금처럼 `_csrf: shared.csrf` 바디 필드로 그대로 보낸다(§4 로그인
+  예시). 멀티파트일 때만 헤더가 유일 경로다.
+
 ### 4. 데이터 경로 판단 — 루트 판단표가 정본
 
 데이터가 필요할 때는 루트 `AGENTS.md` 의 데이터 경로 4종 판단표를 따른다
@@ -440,6 +468,7 @@ export default controller({
 | 결정 117 | render props 에 예약 공유 키 = 컴파일 에러 + 런타임 방어(자동 주입값 조용한 덮어쓰기 금지 · §4.2) |
 | 결정 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 + 수리 안내) |
 | E-1 | 파사드 = `gaonjs` · CLI = `gaon` |
 
 ## `@gaonjs/seal` 켠 앱

package/dist/templates/project/docker-compose.yaml.tpl

@@ -77,3 +77,23 @@ services:
       interval: 2s
       timeout: 3s
       retries: 30
+
+  # 개발 버킷 생성 — this.file() → Storage.put() 이 첫 업로드부터 돌게 한다.
+  # MinIO 서버만 띄우면 버킷이 없어 첫 업로드가 NoSuchBucket 으로 실패한다 —
+  # minio 헬스 후 내장 mc 로 dev 버킷(.env 의 STORAGE_BUCKET = 기본 {{PROJECT_NAME}})과
+  # 테스트 버킷({{PROJECT_NAME}}-test)을 만들고 종료한다(`--ignore-existing` 라 재기동에
+  # 멱등). 테스트 버킷은 `gaon test` 하네스가 스토리지를 `<bucket>-test` 로 격리할 때
+  # 쓴다(결정 136 · <db>_test 대칭). minio 서버 이미지에 mc 가 이미 들어 있어 별도
+  # 이미지(minio/mc)를 받지 않는다(첫 gaon dev 가 더 빠름). 운영(R2/S3)은 인프라에서
+  # 버킷을 사전 생성한다(앱 밖 관심사) — 이 컨테이너는 dev·테스트 전용.
+  createbuckets:
+    image: minio/minio:latest
+    depends_on:
+      minio:
+        condition: service_healthy
+    entrypoint: >
+      /bin/sh -c "
+      mc alias set local http://minio:9000 {{PROJECT_NAME}} {{PROJECT_NAME}}_secret &&
+      mc mb --ignore-existing local/{{PROJECT_NAME}} local/{{PROJECT_NAME}}-test
+      "
+    restart: "no"

package/dist/templates/project/gaon.config.ts.tpl

@@ -4,6 +4,10 @@ import { defineConfig } from 'gaonjs/config'
 
 export default defineConfig({
   // DB — main 커넥션. 스키마에서 { db: '키' } 로 다른 커넥션에 붙일 수 있다(§4.5).
+  // env 미설정이면 배터리를 배선하지 않는다(redis·nats·storage 와 동형). 삼항이어도
+  // doctor 의 커넥션·관계 검사가 참 분기의 키(main)를 정적으로 읽어 §4.5 가드레일이
+  // 작동한다(결정 135). 커넥션을 늘리려면 참 분기에 키를 더 추가한다:
+  //   analytics: { adapter: 'postgres', url: process.env.ANALYTICS_URL ?? '' }.
   db: process.env.DATABASE_URL
     ? {
         main: {
@@ -19,6 +23,23 @@ export default defineConfig({
   // NATS — 실시간·비동기 백본(§7). broadcast 전용(errata E-2).
   nats: process.env.NATS_URL ? { url: process.env.NATS_URL } : undefined,
 
+  // 파일 스토리지(§7 · M8). S3 호환(dev = MinIO · 운영 = R2/S3) — endpoint 만 바꾸면
+  // 같은 코드가 돈다. dev 버킷은 compose 의 createbuckets 가 만든다(첫 업로드부터 동작).
+  storage: process.env.STORAGE_ENDPOINT
+    ? {
+        default: 'main',
+        disks: {
+          main: {
+            driver: 's3',
+            bucket: process.env.STORAGE_BUCKET ?? '{{PROJECT_NAME}}',
+            endpoint: process.env.STORAGE_ENDPOINT,
+            accessKeyId: process.env.STORAGE_ACCESS_KEY,
+            secretAccessKey: process.env.STORAGE_SECRET_KEY,
+          },
+        },
+      }
+    : undefined,
+
   // 웹 서버 리슨 옵션. --port · env PORT 로 덮을 수 있다.
   web: {
     port: process.env.PORT ? Number(process.env.PORT) : 3000,

package/dist/templates/project/test/setup.ts.tpl

@@ -1,13 +1,16 @@
-// test/setup.ts — 테스트 격리 부트스트랩 (§9 실 인프라 · 결정 111).
+// test/setup.ts — 테스트 격리 부트스트랩 (§9 실 인프라 · 결정 111·137).
 //
-// `gaon test` 가 테스트 전용 DB(<db>_test)를 만들고 마이그레이션한 뒤 vitest 를
-// 돌린다. 이 파일이 그 DB 에 붙고(connectTestDatabase), 매 테스트 뒤 전 테이블을
-// 비운다(truncateAll). 트랜잭션 롤백이 아니라 truncate 인 이유: service() 는 실제
-// COMMIT 을 해서 바깥 트랜잭션으로 되돌릴 수 없다(결정 111 · agents/testing.md).
+// `gaon test` 가 각 커넥션의 테스트 전용 DB(<db>_test)를 만들고 마이그레이션한 뒤
+// vitest 를 돌린다. 이 파일이 그 DB 들에 붙고(connectTestDatabase — 스토리지·메일도
+// 테스트 격리 값으로 배선), 매 테스트 뒤 등록된 **모든** 커넥션의 테이블을 비운다
+// (truncateAllConnections). 트랜잭션 롤백이 아니라 truncate 인 이유: service() 는
+// 실제 COMMIT 을 해서 바깥 트랜잭션으로 되돌릴 수 없다(결정 111 · agents/testing.md).
+// truncateAll(main 만)이 아니라 truncateAllConnections 인 이유: 보조 커넥션(§4.5)이
+// 비워지지 않으면 상태가 다음 테스트로 새어 조용한 거짓 실패가 난다(결정 137).
 //
 // 목업·인메모리 금지(§9) — 실 DB 로만 검증한다.
 import { afterAll, afterEach, beforeAll } from 'vitest'
-import { connectTestDatabase, truncateAll, type TestDbHandle } from 'gaonjs/testing'
+import { connectTestDatabase, truncateAllConnections, type TestDbHandle } from 'gaonjs/testing'
 
 let handle: TestDbHandle
 
@@ -16,7 +19,7 @@ beforeAll(async () => {
 })
 
 afterEach(async () => {
-  await truncateAll()
+  await truncateAllConnections()
 })
 
 afterAll(async () => {

package/dist/templates/project/vitest.config.ts.tpl

@@ -19,5 +19,10 @@ export default defineConfig({
     ],
     // 실 DB 를 공유하는 통합 테스트 격리 — 파일 병렬 금지(§9 · 결정 111).
     fileParallelism: false,
+    // 실 인프라(DB·NATS·스토리지) 왕복이 기본 전제라 vitest 기본 5s 는 너무 짧다 —
+    // 잡 발행→워커 처리(expectJobProcessed 10s 대기) 같은 e2e 가 그대로 타임아웃 난다.
+    // 15s 로 넉넉히 둔다(결정 137 · One Way — 실 인프라 왕복에 맞춘 기본값).
+    testTimeout: 15000,
+    hookTimeout: 15000,
   },
 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaonjs/cli",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "Gaon CLI 구현: 제너레이터·스캐폴딩·로드맵 출력 (M1 스텁)",
   "type": "module",
   "license": "MIT",
@@ -28,11 +28,11 @@
     "typescript": "^5.9.0",
     "vite": "^7.0.0",
     "@gaonjs/async": "0.8.0",
-    "@gaonjs/config": "0.10.0",
-    "@gaonjs/data": "0.13.1",
     "@gaonjs/core": "0.2.1",
+    "@gaonjs/config": "0.12.0",
+    "@gaonjs/web": "0.14.0",
     "@gaonjs/mail": "0.1.3",
-    "@gaonjs/web": "0.13.1"
+    "@gaonjs/data": "0.14.0"
   },
   "scripts": {
     "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json && node -e \"require('fs').cpSync('src/templates','dist/templates',{recursive:true})\""