@gaonjs/cli 0.5.0 → 0.10.1

package/dist/scaffold/index.d.ts

@@ -2,7 +2,8 @@ export type { ScaffoldFile } from './controller.js';
 export { controllerScaffold } from './controller.js';
 export { modelScaffold, modelScaffoldFiles, schemaScaffold } from './model.js';
 export { pageScaffold } from './page.js';
-export { jobScaffold } from './job.js';
+export { jobScaffold, jobTestScaffold } from './job.js';
+export { appScaffoldFiles, validateAppName } from './app.js';
 export { inflectModel, toCamel, toPascal, singularize, pluralize, type ModelNames, } from './inflect.js';
 import type { ScaffoldFile } from './controller.js';
 export interface WriteResult {

package/dist/scaffold/index.js

@@ -8,7 +8,8 @@ import { dirname, join, resolve } from 'node:path';
 export { controllerScaffold } from './controller.js';
 export { modelScaffold, modelScaffoldFiles, schemaScaffold } from './model.js';
 export { pageScaffold } from './page.js';
-export { jobScaffold } from './job.js';
+export { jobScaffold, jobTestScaffold } from './job.js';
+export { appScaffoldFiles, validateAppName } from './app.js';
 export { inflectModel, toCamel, toPascal, singularize, pluralize, } from './inflect.js';
 /**
  * 파일 계획을 실제로 쓴다. 기본은 기존 파일 skip(멱등 · 사고 방지).

package/dist/scaffold/job.d.ts

@@ -1,3 +1,8 @@
 import type { ScaffoldFile } from './controller.js';
 /** 잡 이름(파스칼) → 파일·잡명 파생. */
 export declare function jobScaffold(pascalName: string): ScaffoldFile;
+/**
+ * 잡 통합 테스트 골격 (결정 42) — 발행→실 처리 검증을 `expectJobProcessed`
+ * 한 호출로. 실 NATS 필수(§9 · 목업 금지) — `docker compose up -d nats`.
+ */
+export declare function jobTestScaffold(pascalName: string): ScaffoldFile;

package/dist/scaffold/job.js

@@ -44,3 +44,38 @@ export function jobScaffold(pascalName) {
     ];
     return { path: `domain/jobs/${camel}.ts`, contents: lines.join('\n') };
 }
+/**
+ * 잡 통합 테스트 골격 (결정 42) — 발행→실 처리 검증을 `expectJobProcessed`
+ * 한 호출로. 실 NATS 필수(§9 · 목업 금지) — `docker compose up -d nats`.
+ */
+export function jobTestScaffold(pascalName) {
+    const trimmed = pascalName.trim();
+    if (!trimmed) {
+        throw new Error(`[gaon g job] 잡 이름이 비어 있습니다. 예: gaon g job SendEmail`);
+    }
+    const pascal = trimmed
+        .split(/[_\-\s]+/)
+        .map((w) => (w ? w.charAt(0).toUpperCase() + w.slice(1) : ''))
+        .join('');
+    const camel = pascal.charAt(0).toLowerCase() + pascal.slice(1);
+    const lines = [
+        `// ${pascal} 잡 통합 테스트 — gaon g job (결정 42).`,
+        `// 실 NATS JetStream 필수(§9 · 목업 금지): docker compose up -d nats`,
+        `import { describe, it } from 'vitest'`,
+        `import { connectNats, expectJobProcessed } from 'gaonjs/testing'`,
+        `import ${camel} from '../../domain/jobs/${camel}.js'`,
+        ``,
+        `describe('${pascal} (실 NATS JetStream)', () => {`,
+        `  it('발행한 잡이 워커에서 처리된다', async () => {`,
+        `    const nats = await connectNats(process.env.NATS_URL ?? 'nats://localhost:4222')`,
+        `    try {`,
+        `      await expectJobProcessed(${camel}, () => ${camel}.later({ id: 'test' }), { nats })`,
+        `    } finally {`,
+        `      await nats.close()`,
+        `    }`,
+        `  })`,
+        `})`,
+        ``,
+    ];
+    return { path: `test/integration/${camel}.integration.test.ts`, contents: lines.join('\n') };
+}

package/dist/scaffold/model.js

@@ -4,13 +4,13 @@
 // 스키마는 errata E-4 신규 컬럼 타입(decimal · enum · uuid)과 수식어(unique ·
 // nullable · default) 예시를 담아 새 개발자가 바로 참고할 수 있게 한다.
 //
-// 파일 위치 (CLAUDE.md §2 · rule 5):
-//  · 스키마 → domain/schema/<name>.ts (테이블 정의 · tables.d.ts 원천)
-//  · 모델   → domain/models/<name>.ts (Active Record · scopes/methods)
+// 파일 위치 (CLAUDE.md §2 · rule 5 · 파일 네이밍 표 v0.16 §3.4):
+//  · 스키마 → domain/schema/<posts>.ts (파일명 = 테이블명 · camelCase 복수)
+//  · 모델   → domain/models/<Post>.ts  (파일명 = 모델명 · PascalCase 단수)
 // 앱→도메인 import 만 허용되므로 이 위치가 유일한 정답이다.
 /** 스키마 스캐폴드 — E-4 컬럼 타입 예시를 함께 담는다. */
 export function schemaScaffold(names) {
-    const { pascal, camel, plural } = names;
+    const { pascal, plural } = names;
     const lines = [
         `// ${pascal} 스키마 — gaon g model (M9-B).`,
         `// errata E-4 예시: unique · default · enum · nullable. 컬럼은 자유롭게 추가/삭제한다.`,
@@ -34,19 +34,19 @@ export function schemaScaffold(names) {
         ``,
     ];
     return {
-        path: `domain/schema/${camel}.ts`,
+        path: `domain/schema/${plural}.ts`,
         contents: lines.join('\n'),
     };
 }
 /** 모델 스캐폴드 — scopes 예시를 담는다(체이닝 진입점 도우미). */
 export function modelScaffold(names) {
-    const { pascal, camel, plural } = names;
+    const { pascal, plural } = names;
     const lines = [
         `// ${pascal} 모델 — gaon g model (M9-B).`,
         `// scopes 는 체인 어느 지점에서든 호출 가능하다(§4.4). E-4 체이닝 예시:`,
         `//   ${pascal}.published().orderBy('createdAt', 'desc').limit(20).all()`,
         `import { model } from 'gaonjs/data'`,
-        `import { ${plural} } from '../schema/${camel}.js'`,
+        `import { ${plural} } from '../schema/${plural}.js'`,
         ``,
         `export const ${pascal} = model(${plural}, {`,
         `  scopes: {`,
@@ -56,7 +56,7 @@ export function modelScaffold(names) {
         ``,
     ];
     return {
-        path: `domain/models/${camel}.ts`,
+        path: `domain/models/${pascal}.ts`,
         contents: lines.join('\n'),
     };
 }

package/dist/templates/auth/auth.wiring.ts.tpl

@@ -1,6 +1,6 @@
 // 인증 배선 — gaon g auth 스캐폴드.
 import type { AuthOptions } from 'gaonjs/web'
-import { User } from '../../domain/models/user.js'
+import { User } from '../../domain/models/User.js'
 
 // 세션에 심긴 userId 로 사용자를 로드한다(§7). web 은 도메인을 loadUser 로 받는다.
 export const loadUser: AuthOptions['loadUser'] = async (id) =>

package/dist/templates/auth/registration.controller.ts.tpl

@@ -1,6 +1,6 @@
 // 회원가입 컨트롤러 — gaon g auth 스캐폴드.
 import { controller, hashPassword } from 'gaonjs/web'
-import { User } from '../../../domain/models/user.js'
+import { User } from '../../../domain/models/User.js'
 
 export default controller({
   // GET /registration/new — 회원가입 폼

package/dist/templates/auth/session.controller.ts.tpl

@@ -1,6 +1,6 @@
 // 세션 컨트롤러(로그인/로그아웃) — gaon g auth 스캐폴드.
 import { controller, verifyPassword } from 'gaonjs/web'
-import { User } from '../../../domain/models/user.js'
+import { User } from '../../../domain/models/User.js'
 
 export default controller({
   // GET /session/new — 로그인 폼

package/dist/templates/auth/user.model.ts.tpl

@@ -1,5 +1,5 @@
 // 사용자 모델 — gaon g auth 스캐폴드.
 import { model } from 'gaonjs/data'
-import { users } from '../schema/user.js'
+import { users } from '../schema/users.js'
 
 export const User = model(users, {})

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

@@ -0,0 +1,214 @@
+# AGENTS.md — Gaon 프로젝트 AI 개발자 지침 (코어)
+
+이 문서는 **AI 코딩 에이전트**(Claude · Codex · Cursor · Copilot 등)와
+사람 개발자가 Gaon 프로젝트에서 작업할 때 참조하는 관례의 진입점이다.
+정본은 설계 문서(v0.15 동결 + errata E-1~E-5, v0.16 편입)이며, 관례
+문서는 **2층 구조**다 (결정 40):
+
+- **이 파일 (코어)** — 절대 규칙 · 로직 배치 판단표 · 검증 루프 ·
+  카테고리 색인. 여기엔 요약만 있다.
+- **`agents/*.md` (카테고리)** — 시그니처·체이닝 표·정본 예시·함정의
+  정본. **해당 영역 파일을 만지기 전에 반드시 그 카테고리 문서를 읽는다.**
+
+**대상 프로젝트 = Gaon 프레임웍으로 만든 사용자 프로젝트**(`gaonjs`
+설치 후 `gaon new` 로 생성한 앱).
+
+## 0. 카테고리 색인 — 작업 전에 반드시 읽어라
+
+작업이 아래 영역에 걸치면, 코드를 만지기 **전에** 해당 파일을 읽는다.
+코어에는 요약만 있다 — 메서드 시그니처·표·정본 예시는 전부 카테고리
+파일에 있고, 표에 없는 API 를 추측하면 실패한다.
+
+| 작업 영역 | 먼저 읽을 파일 |
+|---|---|
+| 스키마 · 모델 · 관계 · 쿼리/체이닝 · 서비스 · 마이그레이션 | `agents/data.md` |
+| 라우트 · 컨트롤러 · params · JSON 액션 · 인증/비밀번호 | `agents/web.md` |
+| 페이지 · 컴포넌트 · 컴포저블 · 레이아웃 · `api()` · bigint key | `agents/frontend.md` |
+| 잡 · 이벤트 · 리스너 · 아웃박스 · 스케줄 | `agents/async.md` |
+| 채널 · 프레즌스 · 허브 | `agents/realtime.md` |
+| 테스트 작성·실행 (실 인프라 · `expectJobProcessed`) | `agents/testing.md` |
+| 보안 기본값 · 탈출구(v-html · raw SQL) 사용 | `agents/security.md` |
+
+예: 회원가입 세로 조각(스키마+서비스+잡+컨트롤러+테스트)이면
+`data · web · async · testing` 네 파일을 먼저 읽는다.
+
+## 1. The One Way 원칙
+
+Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍"** 이다
+(v0.15 §1.2). 우선순위는 **AI 첫 시도 성공률 > 개발자 편의 > 구현
+편의** — 선택지가 생기면 정답이 하나가 되는 쪽을 고른다.
+
+1. **The One Way** — 모든 문제에 공식 답이 하나. 선택지는 탈출구
+   (escape hatch)로만 남긴다.
+2. **관례가 곧 문서** — 파일 위치·이름이 곧 동작. 설정은 관례를
+   벗어날 때만 쓴다.
+3. **마법은 타입 추론으로** — 데코레이터·DI 컨테이너 없음. 스키마 →
+   모델 → 컨트롤러 → Vue 까지 **타입 추론만**으로 흐른다 (`.gaon/`
+   생성 파일만 예외 · 프레임웍이 관리).
+
+**파일 하나 = 한 개념 · 명시적 import**. Nuxt식 자동 import 는 넣지
+않는다 (errata E-5 §2.4).
+
+## 2. 절대 규칙
+
+1. **TypeScript 전용 · 함수/객체 스타일.** JS 파일 추가 금지, 클래스형·
+   데코레이터 금지 — `model()`·`controller()`·`job()`·`service()`·
+   `channel()` 함수형 API 만.
+2. **파사드 import 만.** 프레임웍 심볼은 `gaonjs/*` (`gaonjs/web`·
+   `gaonjs/data`·`gaonjs/vue`·`gaonjs/async`·`gaonjs/service`·
+   `gaonjs/testing`)에서 import 한다. `@gaonjs/*`(내부 스코프)·
+   `@inertiajs/vue3`(어댑터 내부 의존)는 앱 코드에서 직접 import 금지.
+   (설치명 `gaonjs` · CLI 명령 `gaon` — errata E-1.)
+3. **의존 방향 4규칙** (doctor 강제): ① 앱→`domain/` 허용 ②
+   `domain/`→앱 금지 ③ 앱→앱 금지 ④ 앱→`shared/` 허용 — `shared/` 는
+   앱 import 금지, `domain/` 은 **타입 import 만** (공용 컴포넌트는
+   props 로만 받는 순수 UI).
+4. **보안 기본값(CORS·rate limit·CSRF)은 기본 켬.** 끄는 것은 명시적
+   설정으로만 (`agents/security.md`).
+5. **테스트는 Docker 실인프라 필수** — DB·NATS 목업·인메모리 대체 절대
+   금지 (§9 · `agents/testing.md`).
+6. **인증·폼은 Inertia SPA 방식** (SSR 아님). 폼은 `Inertia.post()` →
+   서버 redirect. REST + `fetch()` 는 **API 앱(JWT) 전용**.
+7. **한 액션은 한 종류 응답만** (render 또는 JSON 또는 redirect —
+   혼용 금지 · doctor response-mixing).
+8. **`.gaon/` 자동 생성 파일 편집 금지** — `routes.d.ts`·`tables.d.ts`
+   는 `gaon check`/`gaon dev` 가 재생성한다.
+
+### 2.1 파일 네이밍 표 (2026-07-24 승인 · 벤치마크 R1 실측 고정)
+
+"Pascal 인가 camel 인가" 를 추측하지 않는다 — 아래 표가 전부다.
+
+| 대상 | 파일명 | 예시 |
+|---|---|---|
+| 모델 | **PascalCase** | `domain/models/Post.ts` |
+| 스키마 | **camelCase** (테이블명) | `domain/schema/posts.ts` · `posts_tags`→`postsTags.ts` |
+| 서비스 | **camelCase** | `domain/services/registerUser.ts` |
+| 잡 | **camelCase** | `domain/jobs/sendWelcomeMail.ts` |
+| 이벤트 | **camelCase** | `domain/events/orderPlaced.ts` |
+| 리스너 | **camelCase** | `domain/listeners/notifyAdmin.ts` |
+| 메일 | **camelCase** | `domain/mails/welcome.ts` |
+| 컨트롤러 | **camelCase** (액션 단위) | `apps/web/controllers/posts.ts` |
+| Vue 페이지 | **PascalCase** (Route 이름) | `apps/web/pages/Posts/Index.vue` |
+| Vue 컴포넌트 | **PascalCase** | `apps/web/components/PostCard.vue` |
+| 컴포저블 | **use** + PascalCase | `apps/web/composables/usePostSearch.ts` |
+| 레이아웃 | **PascalCase** | `apps/web/layouts/Default.vue` |
+| 채널 | **camelCase** | `apps/web/channels/chatMessages.ts` |
+| 마이그레이션 | **timestamp_action** | `db/migrations/20260724_add_posts.ts` |
+
+- 다단어 테이블의 스키마 **파일명**은 camelCase (`posts_tags` →
+  `postsTags.ts`) — 파일 **안**의 `table('posts_tags', …)` 문자열은
+  스네이크 그대로.
+- **식별자** (결정 43): 함수·변수·메서드 = camelCase · 타입·Vue 컴포넌트 =
+  PascalCase · 상수·환경 변수 = UPPER_SNAKE. **DB 네이밍**(테이블명 ·
+  컬럼명 · 스키마 파일 ↔ 테이블 ↔ `tables.d.ts` 키 변환 규칙)은
+  `agents/data.md` "DB 네이밍" 표가 정본이다 — 먼저 읽는다.
+
+### 2.2 `gaon doctor` 검사 9종
+
+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)
+5. `migration-diff` — 스키마 vs DB 상태 불일치
+6. `shared-composable-purity` — shared 안 `api`/`pageProps` import (결정 25)
+7. `no-auto-import` — 자동 import 설정 (E-5 §2.4)
+8. `schema-filename` — 스키마 파일명 camelCase 관례 (결정 38 · `--fix` 지원)
+9. `agents-doc-index` — 이 문서 색인(§0) ↔ `agents/` 실 파일 불일치 (결정 40)
+
+## 3. 로직 배치 One Way 판단표
+
+### 3.1 서버 로직 (정본 §5.3 원문)
+
+> 1. 한 모델 안에서 끝나는 로직 → **모델 메서드**
+> 2. 여러 모델·외부 API·트랜잭션이 얽히는 작업 흐름 → **`domain/services/`**
+> 3. 컨트롤러에는 비즈니스 로직을 두지 않는다 — HTTP와의 **번역만**
+
+### 3.2 프론트 로직 (errata E-5 §2.1 원문 · 결정 25)
+
+> 1. 컴포저블에는 **프론트 전용 로직만** — UI 상태, 브라우저 API,
+>    `api()` 호출 래핑, 채널 구독 래핑.
+> 2. 비즈니스 로직(도메인 규칙·계산·트랜잭션)은 컴포저블에 두지 않는다
+>    — 서버의 `domain/`(모델 메서드·서비스)에만.
+> 3. 한 컴포넌트 안에서만 쓰는 상태는 컴포저블로 뽑지 않는다 — 그냥
+>    `<script setup>` 에. 컴포저블은 **재사용될 때만**.
+
+### 3.3 데이터 경로 4종 (errata E-3 §2 원문)
+
+| 상황 | 경로 | 근거 |
+|---|---|---|
+| 지금 페이지의 데이터를 다시 받기 (필터 변경·새로고침·무한 스크롤) | **Inertia partial reload** — 같은 액션 재호출, 필요한 props만 | §6.1 |
+| 서버가 먼저 밀어주는 데이터 (알림·채팅·접속자) | **채널/프레즌스** (`agents/realtime.md`) | §7 |
+| 페이지와 무관한 데이터 요청 (자동완성·옵션 조회 등 앱 내부용) | **JSON 액션 + `api()` 클라이언트** (`agents/web.md`·`agents/frontend.md`) | E-3 |
+| 외부에 공개하는 API (모바일 앱·서드파티) | **별도 API 앱 + JWT 옵션** | §3, §7 |
+
+### 3.4 잡 발행 위치 (결정 32)
+
+잡 `.later(...)` 은 **컨트롤러 · 서비스 · 리스너 어디서든** 발행 가능 —
+위치를 강제하지 않는다 (`agents/async.md` §2). DB 커밋 정합이 필요하면
+서비스 `afterCommit()` 또는 아웃박스.
+
+## 4. 검증 루프
+
+작업마다 실행한다:
+
+```bash
+gaon check        # .gaon 재생성 → typecheck + vue-tsc + build (+doctor)
+gaon test         # vitest — DB·NATS 는 실 인프라 (agents/testing.md)
+gaon doctor       # 정적 검사 9종 (§2.2)
+```
+
+### 4.1 CLI 명령 (전 명령 `--json` 지원)
+
+| 명령 | 역할 |
+|---|---|
+| `gaon new <name>` | 프로젝트 스캐폴드 |
+| `gaon dev` | 통합 개발 오케스트레이션 (Docker·`.gaon` 재생성·워처) |
+| `gaon serve` / `work` / `hub` | 운영 프로세스 3종 (웹 · 워커 · 실시간 허브) |
+| `gaon g <type> <name>` | 스캐폴드: `auth`·`controller`·`model`·`page`·`job` |
+| `gaon db <sub>` | `diff`·`migrate`(`down`)·`status`·`reset`·`seed` (`agents/data.md` §10) |
+| `gaon check` / `test` / `doctor` | 검증 루프 |
+| `gaon console` | 프로젝트 컨텍스트 REPL |
+| `gaon jobs` | DLQ 조회·재적재 |
+| `gaon mcp` | 내장 MCP 서버 — 도구: `list_routes`·`get_schema`·`run_migration`·`run_tests`·`read_agent_doc` |
+
+`gaon mcp` 는 프레임웍이 자신을 AI 도구로 노출한다 (§7.5.3) — grep
+으로 더듬는 대신 프레임웍에게 직접 묻는다. `read_agent_doc` 은 §0
+카테고리 문서를 조회한다 (결정 40).
+
+## 5. npm 배포본 (2026-07-23 실측 · `npm view <pkg> version`)
+
+| 패키지 | 버전 | 역할 |
+|---|---|---|
+| `gaonjs` | 0.6.0 | 파사드(설치 단위) · CLI `gaon` |
+| `@gaonjs/cli` | 0.5.0 | 제너레이터·스캐폴딩·명령 라우팅 |
+| `@gaonjs/data` | 0.3.0 | 스키마 DSL · 모델 · 마이그레이션 |
+| `@gaonjs/config` | 0.1.0 | `gaon.config.ts`·`app.config.ts` |
+| `@gaonjs/web` | 0.3.0 | Fastify 웹 레이어 · 인증 · JSON 액션 |
+| `@gaonjs/vue` | 0.2.0 | Vue 어댑터 · pageProps · 타입드 `api()` |
+| `@gaonjs/async` | 0.2.2 | 채널 · 프레즌스 · 허브 · 잡 · 스케줄 |
+| `@gaonjs/core` | 0.1.4 | 메타데이터 · 직렬화 프리미티브(Hidden) |
+| `@gaonjs/mail` / `storage` / `i18n` | 0.1.0 | 메일 · 파일 스토리지 · 다국어 |
+
+## 6. 원칙 · 엄수
+
+- **추론 금지 · 사실에 입각.** 확인 안 된 것은 실행·측정으로 검증
+  하거나 사용자에게 묻는다. 표에 없는 API 를 추측해서 쓰지 않는다 —
+  카테고리 문서(§0)를 먼저 읽는다.
+- **무조건 긍정 금지.** 문제가 있으면 문제라고 말하고, 비용·제약이
+  있으면 반영 전에 명시한다.
+- **에러 메시지는 수리 안내서.** "무엇이 잘못됐다" 가 아니라 → "어느
+  파일에 무엇을 추가/수정하고 어떤 명령을 실행하라" 까지 (v0.15 §7.5.3).
+- **관례가 곧 문서** — 관례를 어길 때만 설정을 쓴다.
+- **정본·정오표 원문 우선.** 이 문서·카테고리 문서와 정본이 충돌하면
+  정본·최신 정오표를 따른다.
+
+## 7. 참고 문서
+
+- 설계 정본: `docs/gaondesignv0.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).
+- 프레임웍 구현 저장소의 AI 지침은 `CLAUDE.md` — 이 문서와 대상이
+  다르다 (CLAUDE = 프레임웍 구현자용, AGENTS = 프레임웍 사용자용).

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

@@ -0,0 +1,218 @@
+# agents/async.md — 비동기 (잡 · 이벤트 · 리스너 · 아웃박스 · 스케줄러)
+
+> 골격: **정본 규칙 → 정본 예시 → 알려진 함정 → 관련 결정 번호** (결정 40 · 2층 구조).
+> 루트 `AGENTS.md` 는 코어 요약만 담는다 — 시그니처·표·예시의 정본은 이 파일이다.
+> 대상 패키지: `@gaonjs/async` (파사드 import 는 `gaonjs/async`). 백본 = NATS JetStream ·
+> 실행은 워커 프로세스(`gaon work`).
+
+## 정본 규칙
+
+### 1. 잡 (`job()`) (`packages/async/src/jobs.ts:146-185`)
+
+잡은 도메인 소속이다 — `domain/jobs/*.ts` 에 파일을 놓으면 등록이고,
+어느 앱에서 큐잉하든 같은 워커(`gaon work`)가 처리한다. 모델·서비스와
+같은 함수/객체 스타일(데코레이터 금지).
+
+```ts
+// domain/jobs/sendWelcomeMail.ts — 파일명 camelCase (루트 §네이밍)
+import { job } from 'gaonjs/async'
+
+export const SendWelcomeMail = job(async (userId: bigint) => {
+  // 실 발송 로직 (예: gaonjs/mail 사용)
+}, { retries: 3 })
+```
+
+```ts
+await SendWelcomeMail.later(user.id)        // 즉시 큐잉(인자 타입 그대로 추론)
+await SendWelcomeMail.in('10m', user.id)    // 지연 실행
+await SendWelcomeMail.at(someDate, user.id) // 특정 시각 실행
+```
+
+- **시그니처** — `job(handler, options?)`. 첫 인자는 평범한 async
+  함수(`(...args) => Promise<void> | void`) — `defineJob` 이나
+  `{ perform }` 객체 형태가 아니다.
+- **이름** — `options.name` 으로 명시하거나, 생략하면 `domain/jobs/`
+  파일 로더가 **파일명**으로 채운다(`assignName`). 이름을 얻기 전까지
+  `.later()` 등을 호출하면 에러 — 파일로 두거나 `name` 을 직접 준다.
+- **옵션** — `queue`(기본 `'default'`) · `retries`(기본 3) ·
+  `curve`(백오프 곡선 ms) · `jitter` · `concurrency`.
+- **실패** — 재시도를 소진하면 DLQ 로 간다. `gaon jobs list --failed` ·
+  `gaon jobs retry <id>` 로 조회·재적재한다.
+- 기본 백오프 곡선은 `[1s, 5s, 30s, 5m, 1h]` + 지터 0.2, 재시도 3
+  (총 4시도) — §7 · 벤치마크로 확정된 값.
+
+### 2. 잡 발행 위치 (결정 32 · 2026-07-24 종결)
+
+잡(`.later(...)`)은 **컨트롤러 · 서비스 · 리스너 어디서든 발행
+가능**하다. The One Way 로 발행 위치를 강제하지 않는다 — 사용 맥락에
+따라 선택한다 (v0.16 §12 결정 32).
+
+- **컨트롤러** — 요청 응답 시 즉시 발행 (예: 회원가입 응답 후 환영
+  메일 잡):
+
+  ```ts
+  async create() {
+    const user = await User.create(this.params(User.registerForm))
+    await SendWelcomeMail.later(user.id)      // 컨트롤러에서 발행
+    return this.redirect('/dashboard')
+  }
+  ```
+
+- **서비스** — 여러 컨트롤러 재사용 · 트랜잭션 · 복잡 로직:
+
+  ```ts
+  // domain/services/registerUser.ts — service() 상세는 agents/data.md §9
+  import { service } from 'gaonjs/service'
+
+  export const RegisterUser = service(async (input: RegisterInput) => {
+    const user = await User.create(input)
+    await SendWelcomeMail.later(user.id)      // 서비스에서 발행
+    return user
+  })
+  // 컨트롤러에서: const user = await RegisterUser.call(input)
+  ```
+
+- **리스너** — 이벤트 반응 (예: OrderPlaced 이벤트 → EmailReceipt 잡).
+
+**어디서 발행하든 정합이다.** 컨트롤러 발행 = 즉시성 · 서비스 발행 =
+재사용성 · 리스너 발행 = 이벤트 기반. DB 커밋과 정합이 필요하면
+서비스 `afterCommit()`(`agents/data.md` §9) 또는 아웃박스(§4)를 쓴다.
+
+### 3. 이벤트와 리스너
+
+이벤트는 페이로드 shape 에서 타입이 **구조적으로** 추론된다. 리스너는
+`domain/listeners/*.ts` 의 default export 이고, durable 컨슈머 id 는
+**파일명**에서 채워진다(재시작해도 같은 컨슈머).
+
+```ts
+// domain/events/orderPlaced.ts
+import { event } from 'gaonjs/async'
+import { t } from 'gaonjs/data'
+
+export const OrderPlaced = event('order.placed', {
+  orderId: t.bigint(),
+})
+```
+
+```ts
+// domain/listeners/notifyAdmin.ts
+import { on } from 'gaonjs/async'
+import { OrderPlaced } from '../events/orderPlaced.js'
+
+export default on(OrderPlaced, ({ orderId }) => {
+  // orderId 는 bigint 로 추론됨
+})
+```
+
+이벤트 발행:
+
+```ts
+await OrderPlaced.emit({ orderId: 1n })
+```
+
+여러 리스너가 같은 이벤트를 durable 컨슈머로 구독하며, 각자 재시도된다.
+
+### 4. 아웃박스 (트랜잭션 정합)
+
+이벤트를 DB 트랜잭션과 **원자적으로** 발행하려면 아웃박스를 쓴다.
+`runInTransaction` 안에서 발행한 이벤트는 같은 트랜잭션의 아웃박스
+테이블에 스테이징되고, 트랜잭션이 커밋돼야 릴레이가 실제로 NATS 에
+발행한다. 트랜잭션이 롤백되면 이벤트도 사라진다.
+
+```ts
+import { runInTransaction } from 'gaonjs/async'
+
+await runInTransaction(async () => {
+  await Order.create({ /* … */ })
+  await OrderPlaced.emit({ orderId })   // 커밋돼야 실제 발행됨
+})
+```
+
+- 트랜잭션 안의 `emit` 은 `AsyncLocalStorage` 로 투명하게 감지돼
+  아웃박스에 스테이징된다(별도 API 호출 불필요).
+- 릴레이(`gaon work` 내장)가 `SKIP LOCKED` 로 아웃박스를 폴링해 발행
+  한다 (기본 폴 1000ms · 배치 100).
+- at-least-once — 발행 후 표시하므로 중복 가능성이 있고, dedup(msgID)이
+  흡수한다.
+- 아웃박스 테이블(`_gaon_outbox`)은 코어 내장이며 워커 기동 시 보장된다.
+
+### 5. 스케줄러
+
+`domain/schedule.ts` 에서 반복 작업을 선언한다. 실행 대상은 **항상 잡**
+이다(인라인 함수 금지). 여러 워커가 떠 있어도 **리더로 선출된 하나**만
+발행하므로 중복 실행이 없다.
+
+```ts
+// domain/schedule.ts
+import { schedule } from 'gaonjs/async'
+import { CleanupExpiredSessions } from './jobs/cleanupExpiredSessions.js'
+import { SendDailyDigest } from './jobs/sendDailyDigest.js'
+import { SendWeeklyReport } from './jobs/sendWeeklyReport.js'
+
+export default schedule((s) => {
+  s.every('10m', CleanupExpiredSessions)     // 주기 실행
+  s.daily.at('04:00', SendDailyDigest)       // 매일 특정 시각
+  s.cron('0 9 * * 1', SendWeeklyReport)      // 크론 표현식 (5필드)
+})
+```
+
+| 빌더 | 설명 |
+| --- | --- |
+| `s.every(interval, Job)` | `'10m'`·`'700ms'` 등 주기 또는 ms |
+| `s.daily.at('HH:MM', Job)` | 매일 지정 시각 |
+| `s.cron('분 시 일 월 요일', Job)` | 5필드 크론 표현식 |
+
+### 6. 워커 프로세스 (`gaon work`)
+
+잡·리스너·스케줄러·아웃박스 릴레이를 한 프로세스로 조립한다. 운영
+프로세스 3종(serve·work·hub) 중 하나. SIGTERM/SIGINT 에 graceful
+drain — 스케줄러 리더를 반납하고 진행 중인 잡을 완료한 뒤 종료한다.
+
+## 정본 예시
+
+회원 가입 → 환영 메일 비동기 발송 세로 조각 (§7 원문 예시):
+
+```ts
+// domain/jobs/sendWelcomeMail.ts
+import { job } from 'gaonjs/async'
+
+export const SendWelcomeMail = job(async (userId: bigint) => {
+  // 실 발송 (stub 도 OK — 파일 관례가 관건)
+}, { retries: 3 })
+```
+
+```ts
+// apps/web/controllers/registration.ts — 컨트롤러는 잡 발행만 (직접 발송 금지)
+async create() {
+  const user = await RegisterUser.call(this.params(RegisterUser.form))
+  await SendWelcomeMail.later(user.id)
+  return this.redirect('/dashboard')
+}
+```
+
+발행·처리를 검증하는 실 NATS 테스트는 `agents/testing.md` (결정 42 ·
+`expectJobProcessed`) 를 따른다.
+
+## 알려진 함정
+
+- **컨트롤러에서 메일·외부 발송 직접 호출 = 함정** — 컨트롤러는 잡
+  발행만. nodemailer·resend·@sendgrid/mail 직접 import 금지.
+- **클래스형 잡·데코레이터(`@Job`·`@Processor`) 금지** — `job()` 함수형만.
+- **잡 파일 위치는 `domain/jobs/`** — 앱 폴더가 아니다 (잡은 도메인
+  소속 · 어느 앱에서든 큐잉).
+- **`export const <Pascal> = job(...)`** — export 없이 정의만 하면
+  컨트롤러가 import 해 `.later()` 를 부를 수 없다.
+- **스케줄 대상은 항상 잡** — `s.every('10m', async () => ...)` 인라인
+  함수 금지.
+- **커밋 전 발행 주의** — 트랜잭션 안에서 DB 확정 후에만 나가야 하는
+  발행은 `afterCommit()` 또는 아웃박스로.
+- **테스트에서 NATS 목업 금지** (§9) — 실 JetStream 에 접속한다
+  (`agents/testing.md`).
+
+## 관련 결정 번호
+
+| 결정 | 내용 |
+|---|---|
+| 결정 32 | 잡 발행 위치 자유 (컨트롤러·서비스·리스너 모두 정합) |
+| 결정 42 | 비동기 테스트 헬퍼 `expectJobProcessed` (`agents/testing.md`) |
+| §7 | 비동기 배터리 원문 (백오프 기본값 = M7 벤치마크 확정) |