@gaonjs/cli 0.52.0 → 0.56.0

package/dist/index.js

@@ -27,7 +27,7 @@ import { runHubCommand } from "./hub.js";
 import { runWorkCommand } from "./work.js";
 import { runJobsCommand } from "./jobs.js";
 import { runDbCommand } from "./commands/db.js";
-import { runDoctorCommand, ALL_RULES } from "./doctor.js";
+import { runDoctorCommand, ALL_RULES, RULE_SUMMARIES } from "./doctor.js";
 import { runMcpCommand } from "./commands/mcp.js";
 export { startDev, resolveDevLayout, regenerateGaonOnce, } from "./dev.js";
 export { runDevCommand } from "./commands/dev.js";
@@ -109,13 +109,17 @@ function renderHelp(version = VERSION) {
         "    gaon gen           .gaon 타입 브리지 + api() 런타임 매니페스트만 재생성 (서버·검사 없이 · build 전제 · --json)",
         "    gaon build         멀티 앱 프론트 프로덕션 빌드 (gaon gen + apps/* 순회 · 앱별 dist/<앱>·base=/<앱>/ · --json)",
         "    gaon console       프로젝트 컨텍스트 REPL (--no-config)",
-        "    gaon test          테스트 러너 (테스트 DB <db>_test 자동 생성·마이그레이션 후 vitest · --scope unit|integration|all · -- vitest 인자)",
-        `    gaon doctor        정적 검사 (${ALL_RULES.length} 검사 · 응답 혼용·N+1·의존·커넥션·마이그·컴포저블 순수·자동 import·파일명/컬럼 관례·인증 배선·UI 킷 배선·라우트 등록·정적 충돌·_method·CSRF 배선·내부 앵커·pageProps 구조분해·비동기 오프로드·페이지 레이아웃 브레이크포인트·Link>Button 중첩·seal 클라 배선·보안 역전·§4.5 관계·import.meta.env·로케일 커버리지·render return 누락)`,
+        "    gaon test          테스트 러너 (테스트 DB <db>_test 자동 생성·마이그레이션 후 vitest · --scope unit|integration|all)",
+        "    gaon test -- <인자>       `--` 뒤는 vitest 로 그대로 전달 (gaon 이 안 가로챔 · 예: gaon test -- --json --reporter=json)",
+        // 열거는 RULE_SUMMARIES(doctor.ts) 를 단일 출처로 쓴다 — 손유지 산문이 뒤처져
+        // 새 검사가 help 에서 빠지던 표류 방지(타입이 전수 채움을 강제).
+        `    gaon doctor        정적 검사 (${ALL_RULES.length} 검사 · ${ALL_RULES.map((r) => RULE_SUMMARIES[r]).join("·")})`,
         "    gaon doctor --json                        자동화용 JSON 출력",
         "    gaon doctor --check=n-plus-one,connections  선택 검사만 실행",
         "    gaon doctor --fix                         기계 정정 가능한 위반 계획(dry-run · v0.16 §7.5.3)",
         "    gaon doctor --fix --yes                   실제 편집 적용(원본은 .bak-<타임스탬프> 로 자동 백업)",
-        "    gaon g auth        인증 스캐폴드 생성 (회원가입·로그인·세션·보호 라우트 · --jwt --app <api> = API 앱 토큰 변형)",
+        "    gaon g auth        인증 스캐폴드 생성 (회원가입·로그인·세션·보호 라우트 · --jwt --app <api> = API 앱 토큰 변형 · --public = 비-web 앱 공개 가입)",
+        "    gaon g ui-kit      UI 킷 스캐폴드 (Button·Input 등 원자 프리미티브 · --app <이름>)",
         "    gaon g controller <name>   컨트롤러 스캐폴드 (Rails 관례 · 페이지+JSON 액션)",
         "    gaon g model <Name>        모델 스캐폴드 (스키마+모델 · E-4 컬럼 예시)",
         "    gaon g page <Path/Name>    Vue 페이지 (Inertia SPA · pageProps 브리지)",
@@ -147,19 +151,34 @@ function renderHelp(version = VERSION) {
  * 지정 없음(undefined) = 5 검사 모두 실행. 알 수 없는 이름은 무시(안전).
  */
 export function parseDoctorChecks(argv) {
-    // 인정 집합은 doctor.ts 의 ALL_RULES(정본 28종)를 단일 출처로 쓴다 — 과거
+    // 인정 집합은 doctor.ts 의 ALL_RULES(정본 29종)를 단일 출처로 쓴다 — 과거
     // 손유지 9종 리스트가 뒤처져 --check=seal-security 같은 16종이 조용히 무시되고
     // 전체 검사로 되돌아가던 표류를 근본 차단한다(결정 168).
     const isKnown = (s) => ALL_RULES.includes(s);
     const out = [];
+    const unknown = [];
     for (const a of argv) {
         if (a.startsWith("--check=")) {
             for (const nm of a.slice("--check=".length).split(",")) {
-                if (isKnown(nm) && !out.includes(nm))
-                    out.push(nm);
+                if (isKnown(nm)) {
+                    if (!out.includes(nm))
+                        out.push(nm);
+                }
+                else if (nm !== "" && !unknown.includes(nm)) {
+                    unknown.push(nm);
+                }
             }
         }
     }
+    // 결정 411: 모르는 이름은 여전히 무시하되(안전 방향 — 전체 검사로 넓어짐) **조용히**
+    // 넘기지 않는다. 오타 하나가 "그 검사만 돌렸다" 는 착각으로 이어지고, 전부 오타면
+    // 29종 전체가 돌아가 선택 실행 의도가 통째로 사라진다.
+    if (unknown.length > 0) {
+        process.stderr.write(`  ! 알 수 없는 검사 이름 무시: ${unknown.join(", ")}\n` +
+            `    → 지원 이름은 gaon doctor --json 의 rule 값 또는 gaon help 참고` +
+            (out.length === 0 ? " (인정된 이름이 없어 전체 검사를 실행합니다)" : "") +
+            "\n");
+    }
     return out.length ? out : undefined;
 }
 /**
@@ -225,6 +244,20 @@ export function parseDbArgs(sub, argv) {
     const dbIdx = argv.indexOf("--db");
     const cfgIdx = argv.indexOf("--config");
     const valueFlags = new Set(["--db", "--config"]);
+    // 결정 404: 값 플래그의 **값 부재**도 fail-loud. `gaon db migrate --db`(값 없이 끝)는
+    // db=undefined 가 돼 "커넥션 하나만" 이던 의도가 조용히 **전 커넥션 적용**으로 확장됐다
+    // (결정 139 순회 기본값과 결합해 파괴 반경이 커진다). readPortFlag(결정 240)와 같은 규약.
+    for (const f of valueFlags) {
+        const i = argv.indexOf(f);
+        if (i < 0)
+            continue;
+        const v = argv[i + 1];
+        if (v === undefined || v.startsWith("-")) {
+            throw new Error(`gaon db ${sub}: ${f} 값이 없습니다.\n` +
+                `  → 예: gaon db ${sub} ${f} ${f === "--db" ? "main" : "gaon.config.ts"}\n` +
+                `  → 값 없이 두면 ${f === "--db" ? "전 커넥션에 적용" : "기본 설정 파일 사용"}으로 조용히 넓어져 멈춥니다.`);
+        }
+    }
     // 결정 358: db 는 파괴 방향 오동작이 가능한 명령군이라 미지 플래그를 조용히
     // 무시하지 않는다 — `--dryrun`(오타)이 무시되면 dry-run 의도가 **실제 마이그레이션
     // 적용**으로 반전된다(결정 267 down-위치 문제와 동형). 인정 집합 밖 `--*` 는 throw.
@@ -248,6 +281,19 @@ export function parseDbArgs(sub, argv) {
         }
         positionals.push(a);
     }
+    // 결정 404: 미지 **위치 인자**도 막는다. 종전엔 positionals 가 'down' 판정에만 쓰이고
+    // 나머지는 버려져서 `gaon db migrate donw`(오타)·`rollback`(타 프레임웍 관례)이 무경고로
+    // **정방향 migrate 실 적용**으로 반전됐다 — 결정 358 이 플래그에서 막은 것과 같은 파괴
+    // 방향인데 위치 인자만 뚫려 있었다.
+    const allowedPositionals = sub === "migrate" ? ["down"] : [];
+    const unknown = positionals.find((p) => !allowedPositionals.includes(p));
+    if (unknown !== undefined) {
+        throw new Error(`gaon db ${sub}: 알 수 없는 인자 '${unknown}'.\n` +
+            (sub === "migrate"
+                ? `  → 지원 인자: down(롤백) 하나뿐입니다. 예: gaon db migrate down\n`
+                : `  → gaon db ${sub} 는 위치 인자를 받지 않습니다.\n`) +
+            `  → 오타가 조용히 무시되면 의도와 반대로(예: 롤백 대신 정방향 적용) 실행될 수 있어 멈춥니다.`);
+    }
     return {
         json: argv.includes("--json"),
         db: dbIdx >= 0 ? argv[dbIdx + 1] : undefined,
@@ -372,9 +418,17 @@ export function runCli(argv, opts = {}) {
         const knownSteps = ["typecheck", "vue-tsc", "build", "doctor"];
         const onlyIdx = argv.indexOf("--only");
         const onlyRaw = onlyIdx >= 0 ? argv[onlyIdx + 1] : undefined;
-        const only = onlyRaw && knownSteps.includes(onlyRaw)
-            ? onlyRaw
-            : undefined;
+        // 결정 411: `--only` 오타를 조용히 전체 실행으로 폴백하지 않는다 — "typecheck 만
+        // 돌렸다" 는 착각으로 CI 시간이 늘거나(안전 방향이라 더 안 보인다), 반대로
+        // 단일 단계만 돌린 줄 알고 넘어간다. 값 부재도 같이 막는다(--port 규약 · 결정 240).
+        if (onlyIdx >= 0 && (onlyRaw === undefined || !knownSteps.includes(onlyRaw))) {
+            process.stderr.write(`  ✗ gaon check: --only 값이 ${onlyRaw === undefined ? "없습니다" : `잘못됐습니다('${onlyRaw}')`}.\n` +
+                `    → 지원 단계: ${knownSteps.join(" · ")}\n` +
+                `    → 예: gaon check --only typecheck\n`);
+            process.exitCode = 2;
+            return;
+        }
+        const only = onlyRaw !== undefined ? onlyRaw : undefined;
         void runCheckCommand({
             json: argv.includes("--json"),
             only,
@@ -418,7 +472,7 @@ export function runCli(argv, opts = {}) {
         });
         return;
     }
-    // `gaon doctor` — 정적 검사(M9-E · 28 검사 · ALL_RULES 단일 출처). --check=<이름>[,<이름>...] 로
+    // `gaon doctor` — 정적 검사(M9-E · 29 검사 · ALL_RULES 단일 출처). --check=<이름>[,<이름>...] 로
     // 선택 실행, --json 은 자동화 파싱용.
     // exit code (M9-E-Fix): fatal → 2(사용자 오류) / errors > 0 → 1 / 그 외 → 0.
     if (argv[0] === "doctor") {
@@ -437,9 +491,14 @@ export function runCli(argv, opts = {}) {
             // --fix (dry-run): errors > 0 이면 1 · errors 0 이어도 **계획이 있으면 1**
             //              (고칠 게 있다는 신호 — 이전엔 warning-only 계획이 0 으로 삼켜짐).
             // 기본: errors > 0 이면 1.
+            // 결정 410: `--fix --yes` 인데 **적용에 성공한 게 하나도 없으면** 비-0.
+            // 종전엔 잔여 errors 만 봐서, 위반이 warning 레벨이고 fixer 가 전부 실패하면
+            // (fixer 예외·대상 파일 선점 등) "고친 것 0" 인데 exit 0 이라 자동화가
+            // "고쳐졌다" 로 오판했다 — 시도했는데 아무것도 못 고친 건 성공이 아니다.
             const fix = result.fix;
             const dryPlans = fix !== undefined && !fix.applied && fix.outcomes.length > 0;
-            process.exitCode = result.errors.length > 0 || dryPlans ? 1 : 0;
+            const nothingApplied = fix !== undefined && fix.applied && fix.outcomes.length > 0 && !fix.outcomes.some((o) => o.applied);
+            process.exitCode = result.errors.length > 0 || dryPlans || nothingApplied ? 1 : 0;
         })
             .catch((err) => {
             const msg = err instanceof Error ? err.message : String(err);
@@ -505,21 +564,33 @@ export function runCli(argv, opts = {}) {
     if (argv[0] === "db") {
         const sub = argv[1];
         const known = ["diff", "migrate", "reset", "seed", "status"];
+        // 결정 411: --json 모드면 실패 사유도 **구조화**해서 낸다 — runDbCommand 는 이미
+        // JSON 에러를 방출하는데(commands/db.ts) 라우팅 단계 실패만 텍스트라 자동화가
+        // 사유를 못 받았다(비대칭).
+        const dbJson = argv.includes("--json");
+        const failDb = (message) => {
+            if (dbJson) {
+                process.stdout.write(JSON.stringify({ ok: false, kind: "usage", command: "db", message }) + "\n");
+            }
+            else {
+                process.stderr.write(`  ✗ ${message}\n`);
+            }
+            process.exitCode = 1;
+        };
         if (!sub || !known.includes(sub)) {
-            process.stderr.write(`  ✗ 알 수 없는 db 서브커맨드: ${sub ?? "(없음)"}\n` +
+            failDb(`알 수 없는 db 서브커맨드: ${sub ?? "(없음)"}\n` +
                 `  → 지원: gaon db diff | migrate | reset | seed | status\n` +
-                `  → 옵션: --json · --db <키>(생략 = 전 커넥션 순회) · --config <path> · --yes · --dry-run\n`);
-            process.exitCode = 1;
+                `  → 옵션: --json · --db <키>(생략 = 전 커넥션 순회) · --config <path> · --yes · --dry-run`);
             return;
         }
-        // 결정 358: 미지 플래그는 파싱 경계에서 fail-loud(오타 dry-run 이 실 적용되는 반전 방지).
+        // 결정 358·404: 미지 플래그·미지 위치 인자·값 부재는 파싱 경계에서 fail-loud
+        // (오타 dry-run 이 실 적용되는 반전 방지).
         let dbOpts;
         try {
             dbOpts = parseDbArgs(sub, argv);
         }
         catch (err) {
-            process.stderr.write(`  ✗ ${err instanceof Error ? err.message : String(err)}\n`);
-            process.exitCode = 1;
+            failDb(err instanceof Error ? err.message : String(err));
             return;
         }
         void runDbCommand(sub, dbOpts)
@@ -659,14 +730,27 @@ export function runCli(argv, opts = {}) {
     // `gaon test [--scope unit|integration|all] [-- vitest 인자]` — 테스트 러너(M9-G).
     if (argv[0] === "test") {
         const rest = argv.slice(1);
-        const scopeIdx = rest.indexOf("--scope");
-        const scopeRaw = scopeIdx >= 0 ? rest[scopeIdx + 1] : undefined;
-        const scope = scopeRaw === "unit" || scopeRaw === "integration" || scopeRaw === "all"
-            ? scopeRaw
-            : undefined;
+        // 결정 411: `--` 뒤는 **전부 vitest 몫**이다. 종전엔 gaon 이 위치와 무관하게
+        // --json·--scope 를 가로채 `gaon test -- --json`(vitest 자체 JSON 리포터)이
+        // 불가능했다 — 탈출구를 연다(help 에 적힌 계약과 코드를 일치시킨다).
+        const sepIdx = rest.indexOf("--");
+        const own = sepIdx >= 0 ? rest.slice(0, sepIdx) : rest;
+        const forwarded = sepIdx >= 0 ? rest.slice(sepIdx + 1) : [];
+        const scopeIdx = own.indexOf("--scope");
+        const scopeRaw = scopeIdx >= 0 ? own[scopeIdx + 1] : undefined;
+        // 결정 411: scope 오타를 조용히 전체 실행으로 폴백하지 않는다(--pm 오타를 막은
+        // 결정 167 과 대칭) — 통합만 돌리려던 CI 가 전체를 돌리며 실 인프라까지 띄운다.
+        if (scopeIdx >= 0 && scopeRaw !== "unit" && scopeRaw !== "integration" && scopeRaw !== "all") {
+            process.stderr.write(`  ✗ gaon test: --scope 값이 ${scopeRaw === undefined ? "없습니다" : `잘못됐습니다('${scopeRaw}')`}.\n` +
+                `    → 지원 값: unit · integration · all\n` +
+                `    → 예: gaon test --scope integration\n`);
+            process.exitCode = 2;
+            return;
+        }
+        const scope = scopeRaw !== undefined ? scopeRaw : undefined;
         const passthrough = [];
-        for (let i = 0; i < rest.length; i++) {
-            const a = rest[i];
+        for (let i = 0; i < own.length; i++) {
+            const a = own[i];
             if (a === "--scope") {
                 i++;
                 continue;
@@ -676,7 +760,8 @@ export function runCli(argv, opts = {}) {
             if (a !== undefined)
                 passthrough.push(a);
         }
-        void runTestCommand(passthrough, { json: argv.includes("--json"), scope })
+        passthrough.push(...forwarded);
+        void runTestCommand(passthrough, { json: own.includes("--json"), scope })
             .then((code) => {
             process.exitCode = code;
         })

package/dist/mcp/tools.js

@@ -603,6 +603,10 @@ export const TOOLS = [
                     description: '지정 시 그 검사 하나만 실행. 생략 시 전체.',
                 },
                 noDoctor: { type: 'boolean', description: 'true 면 doctor 를 제외(기본 false — doctor 는 기본 포함 · 결정 157).' },
+                // 결정 411: 폐기된 includeDoctor 를 스키마에 되살리지 **않는다**. 자리를 남기면
+                // strict 클라이언트의 구 호출이 "성공했는데 조용히 무시" 로 끝나 결정 362 가
+                // 없애려던 유령 파라미터 오도가 되살아난다 — 스키마 부재로 인한 검증 거부가
+                // 오히려 fail-loud(어느 파라미터를 쓰라는 신호)라 결정 362 계약을 유지한다.
             },
             additionalProperties: false,
         },

package/dist/messages-gen.js

@@ -4,7 +4,7 @@
 // 카탈로그의 키를 유니온 타입으로 물성화해, t('key') 의 존재하지 않는 키를 컴파일
 // 타임에 잡는다(현재는 GaonMessages 가 비어 있어 키가 string 으로 열림). 생성 파일은
 // 타입만 담는다(규칙 3). @gaonjs/i18n 의 공개 API(loadLocales·renderMessagesDts)만 쓴다.
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { loadLocales, renderMessagesDts } from '@gaonjs/i18n';
 /**
@@ -13,11 +13,19 @@ import { loadLocales, renderMessagesDts } from '@gaonjs/i18n';
  * 안 쓰는 프로젝트가 never 로 깨지지 않게). 생성 여부를 돌려준다.
  */
 export function generateMessagesDts(localesDir, out, baseLng) {
-    if (!existsSync(localesDir))
+    // 결정 414: 카탈로그가 사라졌으면 **옛 생성물을 지운다** — 남겨두면 없어진 키의
+    // 유니온이 그대로 살아 t('없어진키') 가 계속 컴파일된다(제거를 못 잡는 사각).
+    if (!existsSync(localesDir)) {
+        if (existsSync(out))
+            rmSync(out, { force: true });
         return false;
+    }
     const resources = loadLocales(localesDir);
-    if (Object.keys(resources).length === 0)
+    if (Object.keys(resources).length === 0) {
+        if (existsSync(out))
+            rmSync(out, { force: true });
         return false;
+    }
     mkdirSync(dirname(out), { recursive: true });
     // 결정 352: 기준 로케일 = config i18n.fallbackLng(호출자가 정적 분석으로 전달).
     // 이전엔 항상 알파벳순 첫 로케일이라 컴파일 보증이 fallback 체인과 다른 로케일에

package/dist/scaffold/controller.js

@@ -18,6 +18,8 @@
  * @param app 대상 앱 폴더(apps/<app>/).
  */
 export function controllerScaffold(names, app) {
+    // 라우트 키·api() 키는 **앱 접두**를 포함한다(결정 55 · 'app:controller#action') —
+    // 접두 없는 'posts#count' 는 멀티앱에서 해상되지 않아 주석 그대로 복사하면 컴파일이 깨진다.
     const { pascal, plural } = names;
     const lines = [
         `// ${plural} 컨트롤러 — gaon g controller (M9-B).`,
@@ -35,7 +37,7 @@ export function controllerScaffold(names, app) {
         `  },`,
         ``,
         `  // GET /${plural}/count.json — JSON 액션 (errata E-3).`,
-        `  // 반환값 = 응답. api('${plural}#count') 클라이언트가 Serialized<> 로 받는다.`,
+        `  // 반환값 = 응답. api('${app}:${plural}#count') 클라이언트가 Serialized<> 로 받는다.`,
         `  // this.params() 안전 규칙: 라우트 > body > query (errata E-3 §5.1).`,
         `  async count() {`,
         `    return { total: await ${pascal}.count() }`,

package/dist/scaffold/page.js

@@ -22,10 +22,12 @@ export function pageScaffold(pagePath, app) {
     const segments = trimmed.split('/').filter(Boolean);
     const last = segments[segments.length - 1];
     const parent = segments[segments.length - 2] ?? last;
-    // 라우트 키 기본값 — 앱 접두(결정 55) + 폴더=리소스명(복수·소문자) +
-    // 파일=액션명(소문자). 앱 네임스페이스가 있어야 멀티앱에서 전역 GaonRouteMap
-    // 충돌이 없다.
-    const routeKey = `${app}:${toCamel(parent).toLowerCase()}#${toCamel(last).toLowerCase()}`;
+    // 라우트 키 기본값 — 앱 접두(결정 55) + 폴더=리소스명(컨트롤러 파일명) +
+    // 파일=액션명. 앱 네임스페이스가 있어야 멀티앱에서 전역 GaonRouteMap 충돌이 없다.
+    // camelCase 를 **평탄화하지 않는다**: 컨트롤러 파일명·액션명 관례가 camelCase 라
+    // (`blogPosts.ts` · `editForm`) 소문자로 뭉개면 `blogposts#editform` 처럼 존재하지
+    // 않는 키가 나와 pageProps 가 해상되지 않는다(gaon g page BlogPosts/EditForm 실측).
+    const routeKey = `${app}:${toCamel(parent)}#${toCamel(last)}`;
     const filePath = `apps/${app}/pages/${trimmed}.vue`;
     const lines = [
         `<script setup lang="ts">`,

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

@@ -58,9 +58,11 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
 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/*`(내부 스코프)·
+2. **파사드 import 만.** 프레임웍 심볼은 `gaonjs` 와 그 하위 경로에서
+   import 한다 — 전체 목록: `gaonjs`·`gaonjs/data`·`gaonjs/web`·
+   `gaonjs/vue`·`gaonjs/async`·`gaonjs/config`·`gaonjs/service`·
+   `gaonjs/mail`·`gaonjs/storage`·`gaonjs/i18n`·`gaonjs/env`·
+   `gaonjs/log`·`gaonjs/testing`. `@gaonjs/*`(내부 스코프)·
    `@inertiajs/vue3`(어댑터 내부 의존)는 앱 코드에서 직접 import 금지.
    (설치명 `gaonjs` · CLI 명령 `gaon` — errata E-1.)
 3. **의존 방향 4규칙** (doctor 강제): ① 앱→`domain/` 허용 ②
@@ -111,7 +113,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
   컬럼명 · 스키마 파일 ↔ 테이블 ↔ `tables.d.ts` 키 변환 규칙)은
   `agents/data.md` "DB 네이밍" 표가 정본이다 — 먼저 읽는다.
 
-### 2.2 `gaon doctor` 검사 28종
+### 2.2 `gaon doctor` 검사 29종
 
 1. `response-mixing` — 한 액션 안 render/JSON/redirect 혼용 (E-3)
 2. `n-plus-one` — include 미사용 · loop 안 관계 호출 (E-4)
@@ -141,6 +143,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
 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`)
 28. `render-return` — 액션이 `this.render`/`this.redirect`/`this.json` 을 호출만 하고 `return` 하지 않음 = 응답이 버려져 조용히 204(백지) — `return this.render(...)` 로 고치라 (결정 340 · 경고)
+29. `channel-collision` — 두 앱이 **같은 이름의 채널**을 각각 정의 = **에러**. 채널 이름은 전역이다(브로드캐스트 subject `gaon.chan.<이름>`·프레즌스 키에 앱 프리픽스 없음) — 한 앱의 broadcast 가 다른 앱 연결로 팬아웃되고 접속자 목록이 병합되며, 두 정의의 `authorize` 가 갈리면 공개 쪽 규칙으로 메시지가 샌다. 앱마다 이름을 분리하거나(클라이언트 `useChannel` 인자도 함께), 일부러 공유하는 채널이면 정의를 `shared/channels/<이름>.ts` 하나에 두고 각 앱 채널 파일에서 재수출하라(재수출은 통과 · 정의 하나 = 인가 규칙 하나) — 잡·리스너의 동명 등록 throw(결정 271)와 같은 계열의 정적 검사 (`agents/realtime.md` §2)
 
 ## 3. 로직 배치 One Way 판단표
 
@@ -201,7 +204,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
 ```bash
 gaon check        # .gaon 재생성 → typecheck + vue-tsc + build + doctor (기본 포함 · --no-doctor 로 뺌 · 결정 157)
 gaon test         # vitest — DB·NATS 는 실 인프라 (agents/testing.md)
-gaon doctor       # 정적 검사 28종 (§2.2)
+gaon doctor       # 정적 검사 29종 (§2.2)
 ```
 
 ### 4.1 CLI 명령 (전 명령 `--json` 지원)
@@ -212,6 +215,7 @@ gaon doctor       # 정적 검사 28종 (§2.2)
 | `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` · `g auth --app <앱> --public` = 비-web 앱에 공개 회원가입(`/registration/new`)을 opt-in(기본: web=공개·비-web=역할 게이트 · 결정 155) |
+| `gaon g auth --jwt --app <앱>` | **API(JWT) 앱 변형** — 이 명령 **하나**가 앱 폴더째 만든다(토큰 컨트롤러 3종 + `strategy:'jwt'` app.config + `<APP>_JWT_SECRET` 시드 · 페이지·UI 킷·회원가입 없음). `gaon g app` 을 먼저 돌리지 않는다 — 이미 있는 app.config 는 자동 배선을 못 해 exit 1 이고, 쓰지 않는 Vue 프론트가 남는다. web 앱은 세션이 정본이라 `--jwt` 불가 (결정 337·338) |
 | `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` | 검증 루프 |

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

@@ -86,7 +86,7 @@ Gaon 프레임웍 문서: https://gaonjs.dev
 
 ```bash
 gaon check                        # .gaon 재생성 → 타입검사+build+doctor (CI 한 번에 · --no-doctor 로 doctor 뺌)
-gaon doctor                       # 정적 검사 28종 (상세 AGENTS §2.2)
+gaon doctor                       # 정적 검사 29종 (상세 AGENTS §2.2)
 npm test                          # Vitest · DB 테스트는 실 Docker 필수 (§9)
 ```
 

package/dist/templates/project/Dockerfile.tpl

@@ -18,12 +18,22 @@ RUN pnpm install --frozen-lockfile
 FROM base AS build
 COPY --from=deps /app/node_modules ./node_modules
 COPY . .
+# 결정 408: 브라우저에 실리는 공개 변수(VITE_*)는 **빌드 시점에 번들로 각인**된다 —
+# 런타임 env(compose.prod.yaml)로는 못 바꾼다. 값이 필요하면 빌드 인자로 넘긴다:
+#   docker build --build-arg VITE_API_BASE=https://api.example.com .
+# 넘기지 않으면 아래 .env.example 의 placeholder 가 그대로 각인되므로, 공개 변수를
+# 쓰는 앱은 반드시 build-arg 로 주거나 .env.example 에 **공개 가능한 실값**을 둔다.
+# (비밀은 VITE_ 로 만들지 말 것 — 번들은 누구나 읽는다.)
+ARG VITE_VARS=""
 # gaon build 는 .gaon/env.d.ts 생성에 .env 가 필수(결정 198)인데 .env 는 이미지에
 # 넣지 않는다(.dockerignore) — .env.example 을 임시 복제해 빌드하고 즉시 지운다.
 # 지우는 이유: example 의 placeholder(SESSION_SECRET 등)가 런타임에 남으면 compose
 # 가 env 를 안 넘겼을 때 fail-loud 검증을 조용히 통과시킨다(결정 313). 런타임 env
 # 는 compose.prod.yaml 의 environment 가 단일 소스다.
-RUN cp .env.example .env && pnpm build && rm -f .env
+RUN cp .env.example .env \
+  && for kv in $VITE_VARS; do printf '%s\n' "$kv" >> .env; done \
+  && pnpm build \
+  && rm -f .env
 
 # 3) 런타임 — 소스 + 번들 + 의존을 그대로 실행.
 FROM base AS runtime

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

@@ -39,6 +39,11 @@ await SendWelcomeMail.later(user.id)   // domain/jobs/sendWelcomeMail.ts (§1)
 
 ```ts
 // 파생 효과 — 커밋 뒤에만 나가야 하는 발행은 서비스 afterCommit (§4 아웃박스).
+// domain/services/registerUser.ts
+import { service, afterCommit } from 'gaonjs/service'   // service·afterCommit 는 같은 서브패스
+import { User } from '../models/User.js'
+import { ResizeAvatar } from '../jobs/resizeAvatar.js'
+
 export const RegisterUser = service(async (input: RegisterInput) => {
   const user = await User.create(input)
   afterCommit(() => ResizeAvatar.later(user.id))  // 커밋 성공 후에만 발행
@@ -89,18 +94,25 @@ await SendWelcomeMail.at(someDate, user.id) // 특정 시각 실행
   유추가 충돌한다. 이제 **등록 시 throw**(조용한 덮어쓰기 = 발행이 엉뚱한
   핸들러로 가던 무신호 버그 봉합) — 각각 `name` 을 다르게 주거나 파일을 나눈다.
   리스너(`on()`)도 동형 — 같은 파일에 여럿 두면 `id` 를 다르게 준다(durable 충돌).
-- **옵션** — `queue`(기본 `'default'`) · `retries`(기본 3) ·
-  `curve`(백오프 곡선 ms) · `jitter` · `concurrency`.
+- **옵션(`JobOptions` 전부)** — `name` · `queue`(기본 `'default'`) · `retries`(기본 3) ·
+  `concurrency`(기본 1) + 백오프(`curve` 곡선 ms · `jitter` 기본 0.2). 이 6개가 전부다 —
+  **`maxDeliver` 는 잡 옵션이 아니라 워커 옵션**이다(아래).
 - **실패** — 재시도를 소진하면 DLQ 로 간다. `gaon jobs list --failed` ·
   `gaon jobs retry <id>` 로 조회·재적재한다(조회는 전량 배치 스캔 — 옛 레코드도
   상한 없이 찾아 재적재할 수 있다 · 결정 351).
 - **네이티브 재전달 소진도 DLQ 로 간다(결정 347).** 크래시 루프·미등록 잡(워커에
-  `domain/jobs/` 파일이 배포되지 않음)이 재전달 상한(기본 25 · `maxDeliver`)을
+  `domain/jobs/` 파일이 배포되지 않음)이 재전달 상한(기본 25)을
   소진하면, 워커가 MAX_DELIVERIES advisory 를 받아 그 잡을 DLQ 로 이관한다 —
   이전엔 스트림에 무신호로 영구 잔류했다. 미등록 잡의 재전달 지연은 지수
   (1s→2s→…30s 포화)이고 잡 이름당 1회 경고를 남긴다(정상 롤링 배포 창은 통과).
   advisory 는 비영속이라 백스톱은 best-effort 다(소진 순간 워커가 전무하면 다음
   소진 때 회수).
+  - **`maxDeliver` 는 워커 옵션이다 — 잡별로 못 준다.** 재전달 상한은 `runWork()` 의
+    `maxDeliver`(= `runWorker()` 로 전달 · `packages/async/src/worker.ts`)이고 그 워커가
+    소비하는 **모든 큐에 공통**으로 걸린다. `job(handler, { maxDeliver: … })` 같은 표면은
+    없다(`JobOptions` 는 위 6개뿐 — 넘겨도 무시된다). 잡별로 조절 가능한 것은
+    `retries`(앱 레벨 재시도)뿐이고, `maxDeliver` 는 그 아래층인 **JetStream 네이티브
+    재전달**(크래시 복구·미등록 잡 백스톱)의 상한이라 축이 다르다.
 - **큐 동시성은 큐별로 정확히 적용된다(결정 348)** — 다른 큐의 긴 잡이 이 큐의
   처리량을 깎지 않는다(잡별 `concurrency` 선언 = 그 큐의 실제 동시 처리 수).
 - **워커 복원력(결정 258)** — 재시도 재적재나 DLQ 이관을 하는 도중 NATS 가
@@ -190,8 +202,12 @@ await OrderPlaced.emit({ orderId: 1n })
 
 - 실패하면 백오프(잡과 같은 곡선 `[1s, 5s, 30s, 5m, 1h]`)로 재전달되고, 최대
   재전달(기본 6 · 최초 포함) 소진 시 **영구 폐기**된다. 즉 계속 실패하는 이벤트는
-  약 **1시간 36분** 뒤 사라진다 — `gaon work` 가 `✗ 이벤트 폐기` 로 신호한다
-  (결정 308 · 이전엔 human 모드 무신호). 놓치면 안 되는 처리는 리스너에서 잡을
+  최초 실패로부터 **약 1시간 5분**(1s+5s+30s+5m+1h = **1h05m36s** · 지터 ±20% 별도)
+  뒤 사라진다 — `gaon work` 가 `✗ 이벤트 폐기` 로 신호한다
+  (결정 308 · 이전엔 human 모드 무신호). **크래시 루프**(핸들러 throw 가 아니라
+  프로세스가 ack 전에 반복 사망)로 소진돼도 MAX_DELIVERIES advisory 백스톱이
+  같은 `✗ 이벤트 폐기` 신호를 낸다(결정 398 · 잡의 결정 347 동형 · advisory 는
+  비영속이라 best-effort). 놓치면 안 되는 처리는 리스너에서 잡을
   발행해(`.later()`) 잡의 재시도·DLQ 배터리로 넘긴다.
 - **리스너별 순차 처리는 보장되지 않는다** — 재시도 대기 중 다음 이벤트가 먼저
   처리될 수 있고, 드물게 같은 리스너의 두 이벤트가 겹칠 수 있다. 순서·중복에
@@ -235,15 +251,20 @@ export const PlaceOrder = service(async (input: { name: string }) => {
   어떤 경로로도 삭제되지 않으므로 유실이 없다.
 - at-least-once — 발행 후 표시하므로 중복 가능성이 있고, dedup(msgID)이
   흡수한다(claim 리스 60s < dedupe 창 120s 라 "발행 후 표시 전 크래시"
-  재발행도 창 안에서 접힌다).
+  재발행도 창 안에서 접힌다). **"claim 리스 < dedupe 창" 은 부팅이 강제한다
+  (결정 396)** — `dedupeWindowMs` 를 claim 아래로 줄이는 오설정은 조용한 이중
+  배달이 되므로 `gaon work` 가 수리 안내와 함께 fail-loud 한다. claim 리스는
+  env `GAON_OUTBOX_CLAIM_TIMEOUT_MS`(또는 `runWork` 의 `outboxClaimTimeoutMs`)
+  로 조정한다.
 - 아웃박스 테이블(`_gaon_outbox`)은 코어 내장이며 `gaon serve`·`gaon work`
   기동 시 보장된다(결정 144 · nats 설정이 있을 때).
 - 발행 완료 행은 릴레이가 **자동 정리(purge)** 한다 — 기본 7일 보존 후 삭제
-  (결정 78). 수동 cleanup 코드를 쓰지 말 것. 보존 기간·간격·폴링 주기는 env
-  `GAON_OUTBOX_RETENTION_MS`·`GAON_OUTBOX_PURGE_INTERVAL_MS`·`GAON_OUTBOX_RELAY_POLL_MS`
+  (결정 78). 수동 cleanup 코드를 쓰지 말 것. 보존 기간·간격·폴링 주기·claim 리스는 env
+  `GAON_OUTBOX_RETENTION_MS`·`GAON_OUTBOX_PURGE_INTERVAL_MS`·`GAON_OUTBOX_RELAY_POLL_MS`·
+  `GAON_OUTBOX_CLAIM_TIMEOUT_MS`(결정 396)
   로 조정한다(결정 312 · `GAON_WORKER_*` 와 대칭 · `gaon work` 가 읽는다). 프로그래매틱
-  경로는 `runWork()` 의 `outboxRetentionMs`·`outboxPurgeIntervalMs`·`relayPollMs`.
-  미발행 행은 절대 삭제되지 않는다.
+  경로는 `runWork()` 의 `outboxRetentionMs`·`outboxPurgeIntervalMs`·`relayPollMs`·
+  `outboxClaimTimeoutMs`. 미발행 행은 절대 삭제되지 않는다.
 - **발행 실패는 행 단위로 격리된다(결정 306 · 346).** 한 행의 publish 가 실패해도
   (예: 페이로드가 NATS `max_payload` 1MiB 초과) 그 행만 claim 된 채 남아 리스
   만료(60s) 후 재시도되고, 뒤 행들은 정상 발행된다 — 한 행이 아웃박스 전체를
@@ -301,7 +322,8 @@ export default schedule((s) => {
   워커에 로드밸런싱된다. 발행은 1인, 처리는 N인.
 - **exactly-once(발행 기준)** — 한 스케줄 틱은 리더 1인이 한 번만 발행한다.
   리더 교체(페일오버) 순간 구·신 리더가 같은 틱을 겹쳐 발행해도, 결정론적
-  dedupe 키 + JetStream 중복 윈도우가 이를 1회로 수렴시킨다(결정 233).
+  dedupe 키 + JetStream 중복 윈도우가 이를 1회로 수렴시킨다 — cron 은 발화
+  분(minute) 키(결정 233), **every 는 위상 슬롯 키**(결정 394 · 아래)로 접힌다.
   잡 자체는 재시도(백오프)가 있으니 **핸들러는 멱등**하게 짠다(같은 잡이 두 번
   처리돼도 안전하게).
 - **`s.every` 위상은 리더 교체를 가로질러 보존된다(결정 349).** 마지막 발화
@@ -309,6 +331,13 @@ export default schedule((s) => {
   아니면 잔여 시간만 기다린다 — 재선출마다 타이머가 리셋돼 리스 플래핑이
   interval 보다 잦으면 every 잡이 영영 안 돌던 기아가 없다. 리스 갱신도 순단
   1~2회는 재시도 후에만 리더를 내려놓는다(불필요한 failover·리셋 억제).
+- **`s.every` 의 failover 이중발화도 접힌다(결정 394).** 구 리더가 발화 직후
+  위상 기록(KV put · best-effort)을 못 남기고 죽으면 신 리더가 같은 슬롯을
+  즉시 재발화하는데, every 발화가 위상 슬롯 기반 결정적 dedupe 키
+  (`enqueueScheduled`)를 쓰므로 같은 슬롯의 재발화는 JetStream 중복 윈도우
+  안에서 1건으로 수렴한다 — 결정 349 이후 every 만 랜덤 id(`later()`)라
+  안 접히던 창을 닫았다. 사임(stop) 시 리스 키 삭제도 CAS 라 stale 리더의
+  종료가 신 리더의 키를 지우지 않는다(결정 395).
 - **`gaon serve` 는 스케줄러를 돌리지 않는다** — 스케줄·리더 선출·아웃박스
   릴레이는 **`gaon work` 전용**이다. 웹 프로세스는 잡을 **발행**만 할 수 있고
   (`.later()`), 처리·스케줄은 워커가 한다. **운영에서** 스케줄이 안 도는 흔한
@@ -352,6 +381,9 @@ drain — 스케줄러 리더를 반납하고 진행 중인 잡을 완료한 뒤
 - **`gaon work`** — 신규 잡 pull 을 멈추고 **진행 중 잡을 완료**한 뒤 종료한다
   (`drainTimeoutMs` 상한 · 기본 30s). 스케줄러 리더는 즉시 반납해 다른 인스턴스가
   승계한다. drain 상한을 넘긴 잡은 ack 되지 않아 재전달(크래시 복구)된다.
+  상한은 **큐가 동시성 포화 상태로 긴 잡을 물고 있어도** 지켜진다(결정 397 —
+  종전엔 이 경우 소비 루프 종료 대기가 상한 밖이라 stop 이 잡 완료까지 무기한
+  붙들렸다).
 - **컨테이너 기본 워커 1** — `gaon serve` 클러스터(`--workers`)도 SIGTERM 에
   워커들을 graceful drain 후 종료한다(결정 84).
 
@@ -457,12 +489,16 @@ async create() {
 - **스케줄 대상은 항상 잡 · 무인자** — `s.every('10m', async () => ...)` 인라인
   함수 금지. 인자 필수 잡은 컴파일 에러로 거부된다(결정 310 · §5).
 - **계속 실패하는 리스너는 이벤트를 잃는다** — 리스너는 DLQ 가 없어 재전달
-  소진(기본 6회 · 약 1h36m) 후 영구 폐기된다(§3 계약 · `gaon work` 가 `✗ 이벤트
+  소진(기본 6회 · 약 1h05m36s) 후 영구 폐기된다(§3 계약 · `gaon work` 가 `✗ 이벤트
   폐기` 로 신호). 유실 불가 처리는 리스너에서 잡으로 넘긴다.
 - **커밋 전 발행 주의** — 트랜잭션 안에서 DB 확정 후에만 나가야 하는
   발행은 `afterCommit()` 또는 아웃박스로.
 - **테스트에서 NATS 목업 금지** (§9) — 실 JetStream 에 접속한다
   (`agents/testing.md`).
+- **MySQL 은 8.0+(`explicit_defaults_for_timestamp=ON`) 전제** (결정 400) —
+  구식 설정(OFF · 5.7 기본)에서는 아웃박스 테이블의 timestamp 컬럼이 NOT NULL
+  + zero-date 기본으로 생성돼 strict `NO_ZERO_DATE` 와 충돌할 수 있다. 관리형
+  MySQL 에서 해당 플래그가 OFF 면 ON 으로 바꿔라.
 - **동시 실행 방지에 로컬 뮤텍스·플래그 금지** (결정 147) — `let running = false`
   같은 프로세스 로컬 가드는 멀티 인스턴스에서 안 먹는다. `lock(key, fn)` 을
   쓴다. 운영에서 `redis` 미설정이면 `lock()` 이 수리 안내로 throw 하니 조용한
@@ -485,12 +521,18 @@ async create() {
 | 결정 211 | `gaon dev` all-in-one — serve·work·hub 자동 기동 · dev 워커 동시성 4(`GAON_WORKER_CONCURRENCY`) · `--no-work`/`--no-hub` (§6) |
 | 결정 258 | 워커 소비 루프 복원력(§1) — 재시도/DLQ 발행이 NATS 순단으로 실패해도 큐 소비가 멈추지 않음(nak 재전달 백스톱 · 잡 유실 방지 · 실패 로그) |
 | 결정 306 | 아웃박스 발행 실패 행 격리(§4) — poison 행(페이로드 상한 초과 등)이 배치 전체를 세우지 않음 · 실패 행은 미발행 유지(유실 없음·재시도) · `relay-error` 이벤트로 관측 |
-| 결정 308 | `gaon work` human 신호 확장(§3) — 리스너 폐기(`✗ 이벤트 폐기`)·워커 인프라 오류·재시도가 기본 모드에서 무신호이던 갭 봉합 + 리스너 재시도·폐기 계약(DLQ 없음·~1h36m) 명문화 |
+| 결정 308 | `gaon work` human 신호 확장(§3) — 리스너 폐기(`✗ 이벤트 폐기`)·워커 인프라 오류·재시도가 기본 모드에서 무신호이던 갭 봉합 + 리스너 재시도·폐기 계약(DLQ 없음 · 곡선 합 **1h05m36s** · 종전 "1h36m" 오기 정정) 명문화 |
 | 결정 310 | 스케줄 대상 잡 무인자 가드(§5) — 인자 필수 잡 등록을 컴파일 타임 거부(메서드 bivariance 로 통과해 `undefined` 인자 발화하던 구멍 차단) |
 | 결정 312 | 아웃박스 릴레이 env 튜닝(§4) — `GAON_OUTBOX_RETENTION_MS`·`GAON_OUTBOX_PURGE_INTERVAL_MS`·`GAON_OUTBOX_RELAY_POLL_MS`(`GAON_WORKER_*` 대칭) |
 | 결정 346 | 아웃박스 2단계 publish(§4) — claim(`claimed_at`+SKIP LOCKED 짧은 tx) → 커밋 → tx 밖 publish → 표시 · NATS 지연의 DB 락 전파 제거 · claim 리스 60s(< dedupe 창) · 유실 0 |
-| 결정 347 | max_deliver 소진 DLQ 백스톱(§1) — MAX_DELIVERIES advisory → DLQ 이관(무신호 영구 잔류 봉합) · 미등록 잡 지수 nak(1s→30s 포화)+이름당 1회 경고 · `maxDeliver` 옵션 |
+| 결정 347 | max_deliver 소진 DLQ 백스톱(§1) — MAX_DELIVERIES advisory → DLQ 이관(무신호 영구 잔류 봉합) · 미등록 잡 지수 nak(1s→30s 포화)+이름당 1회 경고 · 상한은 **워커 옵션** `runWork({ maxDeliver })`(기본 25 · 잡 옵션 아님 · 워커의 전 큐 공통) |
 | 결정 348 | 워커 큐별 동시성 게이트(§1) — 전역 inflight 비교가 낳던 교차 큐 간섭 제거(선언 `concurrency` = 실제 동시 처리) |
 | 결정 349 | 리스 갱신 순단 재시도 + every 위상 KV 보존(§5) — 키가 내 것이면 revision 동기화 재시도 후에만 revoke · `gaon_scheduler` KV 로 위상 이어받기(플래핑 기아 봉합) |
 | 결정 351 | DLQ 조회 배치 스캔(§1) — ordered 컨슈머 fetch 로 삭제 갭 서버 스킵 · findDlq 1000건 상한 제거(옛 레코드 retry 복원) |
+| 결정 394 | every failover 이중발화 dedupe(§5) — 위상 슬롯 기반 결정적 키(`enqueueScheduled`)로 구·신 리더의 같은 슬롯 재발화가 1건으로 수렴(결정 349 가 연 창 봉합 · cron 결정 233 동형) |
+| 결정 395 | 리스 사임 CAS 삭제(§5) — stop() 이 `previousSeq` 로 자기 revision 에서만 키 삭제 · stale 리더 종료가 신 리더 키를 지우던 재선출 순단 봉합(허브 endpoint 결정 259 동형) |
+| 결정 396 | 아웃박스 claim<dedupe 불변식 부팅 강제(§4) — 위반 시 fail-loud(조용한 이중 배달 봉합) · claim 리스 운영 표면 `GAON_OUTBOX_CLAIM_TIMEOUT_MS`/`outboxClaimTimeoutMs` 신설 |
+| 결정 397 | graceful drain 상한 유계화(§6) — 포화 큐의 긴 잡이 소비 루프 종료를 붙들어 `drainTimeoutMs` 가 무효이던 우회 봉합(closers 도 같은 deadline 공유 · 워커·리스너 공통) |
+| 결정 398 | 리스너 크래시 루프 소진 신호(§3) — EVENTS 스트림 MAX_DELIVERIES advisory 백스톱으로 `dropped` 신호(잡 결정 347 동형 · 공유 스트림이라 메시지 삭제는 안 함) |
+| 결정 400 | P3 청소 묶음 — 허브 KV 복원 오염 키 방어(try/continue) · 라인 디코더 완결 초과 라인도 onOverflow(무신호 명령 소실 금지) · MySQL timestamp 모드 함정 문서화 · listDlq 롤링 버퍼(O(limit) 메모리) · advisory dead 는 삭제 성공 워커만 신호 + 삭제 실패 잔류 관측 |
 | §7 | 비동기 배터리 원문 (백오프 기본값 = M7 벤치마크 확정) |