diff --git a/docs/discord_first_redesign.md b/docs/discord_first_redesign.md
new file mode 100644
index 0000000..0363975
--- /dev/null
+++ b/docs/discord_first_redesign.md
@@ -0,0 +1,611 @@
+# Lang2SQL — Discord-First 재설계 명세
+
+> **작성일**: 2026-05-18
+> **결정자**: ryan@brain-crew.com
+> **상태**: 골격 승인. §10 잔여 결정 항목 보완 후 Week 1 착수.
+> **범위**: 현 `lang2sql/` 트리를 비우고 본 문서대로 새로 채운다.
+
+---
+
+## 0. 제품 한 줄과 타이브레이커
+
+> **"Discord에서 쓰는 read-only · audit-by-default SQL 에이전트.
+> DB는 절대 변하지 않고, 모든 쿼리는 예산/시간/행 한도 안에서 돈다.
+> 대화 맥락은 끊겨도 영속된다."**
+
+설계 충돌 시 우선순위:
+
+1. **Discord UX가 단순한가?**
+2. **DB는 안 깨지는가?**
+3. **맥락은 보존되는가?**
+
+이 3가지에 부정으로 답하는 어떤 추상화도 도입하지 않는다.
+
+---
+
+## 1. 확정된 기술 결정
+
+| # | 항목 | 선택 | 근거 |
+|---|---|---|---|
+| 1 | Discord lib | **`discord.py` 2.x** | 가장 성숙·안정. 문서/예제 풍부. 비동기 native. |
+| 2 | DB 엔진 타깃 (V1) | **PostgreSQL** | EXPLAIN·statement_timeout·RO role·sslmode 등 모든 safety 기법이 정직하게 동작. MySQL/SQLite/BigQuery는 V2 이후. |
+| 3 | 세션 영속화 | **Hermes-style write-through** | 매 메시지·매 도구 호출/결과·매 pause·매 audit 항목을 즉시 디스크에 flush. 봇 재시작/배포/네트워크 단절 후 다시 붙어도 동일 맥락 복구. |
+| 4 | 세션 + 자격증명 스토어 | **AES-GCM 암호화된 SQLite 단일 파일** | 트라이얼 단계 무료·무의존. JSON1으로 conversation 저장. 외부 secret manager는 V2 옵션. |
+| 5 | LLM 백엔드 | **OpenAI + NVIDIA NIM 듀얼 어댑터** | NIM endpoint가 OpenAI 호환(`/v1/chat/completions`) → 어댑터 거의 그대로 재사용. 슬래시 명령 `/model` 로 유저 전환. |
+| 6 | Go TUI | **유지 (개발 도구)** | Discord 불가 환경 fallback. `serve.py` NDJSON 인터페이스 유지. |
+| 7 | 차트 출력 | **PNG 첨부 + 자동 페이지네이션** | matplotlib + Pillow. Discord 첨부 한도(무료 8MB/메시지, 임베드 10개)에 맞춰 잘라 보냄. |
+| 8 | 호스팅 (트라이얼) | **소형 VPS** | §1.1 참조. Cloudflare Workers 부적합. |
+
+### 1.1 호스팅 — "Cloudflare 5천원" 건에 대한 솔직한 답
+
+`discord.py` 는 Discord WebSocket gateway에 **계속 붙어 있어야 하는 장기 실행 Python 프로세스**입니다. Cloudflare Workers의 edge runtime은 짧은 HTTP 요청-응답 모델이라 봇 본체를 못 올립니다. (D1/KV/R2 같은 backing store로는 활용 가능하지만 V1 범위 밖.)
+
+**저렴·트라이얼 권장 옵션**
+
+| 옵션 | 비용 | 메모 |
+|---|---|---|
+| **Oracle Cloud Always Free** | $0 (무기한) | ARM Ampere 4코어/24GB. 가성비 최강. 가입 시 카드 검증. |
+| **fly.io shared-cpu-1x** | $0 ~ $5/월 | 256MB로 시작 가능. 한국에서 가까운 region(NRT/SIN). |
+| **Hetzner CX11** | €4.5/월 (~6,500원) | 안정·빠름. 유럽 region. |
+| **본인 PC + 24h on** | $0 | 데모 단계 충분. 동적 IP면 이주 권장. |
+
+**비추**: Cloudflare Workers(런타임 비호환), Heroku 무료(폐지), Render 무료(60s sleep으로 봇 끊김).
+
+### 1.2 "타깃 = 가짜연구소 디스코드?" 정리
+
+질문하신 *"이 타깃이 가짜연구소 디스코드?"* 에 대해: 문서에서 쓴 "타깃"은 **지원할 DB 엔진 종류**(PG vs MySQL vs BQ)를 의미한 것이고, **봇이 초대될 디스코드 커뮤니티**와는 별개입니다.
+
+- **DB 엔진 타깃**: PostgreSQL (확정)
+- **배포 커뮤니티**: 가짜연구소 디스코드라면 그쪽 길드에 봇을 초대하는 별개 결정. V1 코드는 어떤 길드에든 동작하도록 작성.
+
+### 1.3 "자격증명 저장 위치" 풀이
+
+`/connect` 로 입력받는 **DB 사용자명·비밀번호를 어디에 저장하느냐**의 질문입니다.
+
+| 옵션 | 비용 | 강도 | 추천 시점 |
+|---|---|---|---|
+| **로컬 AES-GCM SQLite** | $0 | 마스터키(env) + per-row IV | **V1 — 채택** |
+| AWS Secrets Manager | ~$0.40/secret/월 | 강함 | 다중 인스턴스·SOC2 |
+| GCP Secret Manager | ~$0.06/secret/월 | 강함 | GCP 환경일 때 |
+| HashiCorp Vault | self-host | 강함 | 사내 운영 |
+
+V1은 **로컬 암호화 SQLite**. 마스터키는 `LANG2SQL_MASTER_KEY` env로 주입. 키 분실 시 secrets만 무효화되고 conversation/audit은 그대로 (분리 저장).
+
+---
+
+## 2. 상위 아키텍처
+
+```
+                          ┌──────────────────────────────┐
+                          │      DISCORD GATEWAY         │
+                          │  - DM (private analytics)    │
+                          │  - Guild channel / thread    │
+                          │  - Slash commands / modals   │
+                          └───────────────┬──────────────┘
+                                          │ events
+                                          ▼
+┌──────────────────────────────────────────────────────────────────────┐
+│                       DISCORD ADAPTER  (1급)                          │
+│  ┌──────────────┐  ┌──────────────┐  ┌───────────────────────────┐  │
+│  │ Onboarding   │  │ SessionRouter│  │ Streaming Renderer        │  │
+│  │  /connect    │  │  key 결정    │  │  토큰 → message edits      │  │
+│  │  modal+test  │  │              │  │  rows  → PNG (페이지)      │  │
+│  └──────────────┘  └──────────────┘  └───────────────────────────┘  │
+│  ┌──────────────┐  ┌──────────────┐  ┌───────────────────────────┐  │
+│  │ Interactive  │  │ Permissions  │  │ DiscordRateLimit          │  │
+│  │  ask_user /  │  │ guild-admin/ │  │  message edit throttle    │  │
+│  │  show_plan   │  │ owner/user   │  │  per-user / per-guild     │  │
+│  │  → buttons   │  │              │  │                           │  │
+│  └──────────────┘  └──────────────┘  └───────────────────────────┘  │
+└───────────────────────────┬──────────────────────────────────────────┘
+                            │ ctx = ContextConcierge.build(session_key, principal)
+                            ▼
+┌──────────────────────────────────────────────────────────────────────┐
+│                        TENANCY LAYER                                  │
+│  ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────────┐ │
+│  │TenantRegistry│ │ExplorerCache │ │ EncryptedStore (AES-GCM)     │ │
+│  │key→DBSpec    │ │LRU engines   │ │ secrets + conversation +     │ │
+│  │              │ │              │ │ audit (단일 SQLite)           │ │
+│  └──────────────┘ └──────────────┘ └──────────────────────────────┘ │
+│  ┌──────────────────────────────────────────────────────────────┐   │
+│  │  ContextConcierge — session_key + principal → HarnessContext │   │
+│  └──────────────────────────────────────────────────────────────┘   │
+└───────────────────────────┬──────────────────────────────────────────┘
+                            ▼ ctx
+┌──────────────────────────────────────────────────────────────────────┐
+│                        HARNESS KERNEL                                 │
+│   agent_loop · system_prompt(per turn) · ToolRegistry(ctx 주입)       │
+│   Session(live layer + pending_call + write-through) · Hooks(pub/sub) │
+└──────┬─────────────────────┬──────────────────┬──────────────────────┘
+       │ ports               │                  │
+       ▼                     ▼                  ▼
+┌──────────────────────────────────────────────────────────────────────┐
+│                    SAFETY LAYER  (제품의 moat)                        │
+│  L0 connect (RO role, TLS)  →  L1 stmt gate (sqlglot AST)             │
+│  L2 cost gate (EXPLAIN)     →  L3 runtime (timeout/row/byte)          │
+│  L4 audit (append-only)     →  L5 rate limit (token bucket)           │
+└──────┬─────────────────────┬──────────────────┬──────────────────────┘
+       ▼                     ▼                  ▼
+┌──────────────────────────────────────────────────────────────────────┐
+│                     OUTBOUND ADAPTERS                                 │
+│  LLM (openai / nvidia-nim)  ·  DB (sqlalchemy-postgres)               │
+│  Secrets (encrypted-sqlite) ·  SessionStore (encrypted-sqlite)        │
+│  AuditSink (sqlite, file)                                             │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+규칙: 화살표는 **안쪽으로만**. Kernel/Safety는 어댑터를 import하지 않는다. 새 frontend·새 LLM·새 DB·새 session store는 어댑터 한 장 추가로 끝.
+
+---
+
+## 3. 세션 전략 — Hermes-style 영속화
+
+### 3.1 session_key 정책
+
+| Discord 컨텍스트 | session_key | DB credential 출처 | 멤버 가시성 | 용도 |
+|---|---|---|---|---|
+| **봇과의 DM** | `dm:{user_id}` | 유저 본인의 비밀저장소 항목 | 본인만 | **개인 분석 (기본 경로)** |
+| **길드 채널(메인)** | `chan:{guild_id}:{channel_id}` | 길드 어드민이 등록한 공용 DB | 채널 멤버 전원 | 팀 공용 대시보드 질의 |
+| **길드 스레드** | `thr:{guild_id}:{channel_id}:{thread_id}` | 상위 채널과 동일 | 스레드 참여자 | 병렬 조사 (1조사 = 1스레드) |
+
+**원칙**:
+- 민감 DB 자격증명은 **DM에서만 받음**. 채널 메시지는 영구히 history에 남고 다른 멤버에게 보임.
+- 위 3가지 외의 session_key는 사용 금지. 변형이 늘면 "누가 무엇을 보는지" 추적 불가.
+- **principal** (= 누가 보낸 메시지인가) 은 session_key와 별개로 매 요청 기록. 공용 채널에서도 audit log에 *"이 쿼리는 누가 시켰는지"* 가 남음.
+
+### 3.2 영속화 메커니즘 (write-through)
+
+```
+User msg ──▶ Discord adapter ──▶ session.append_message(msg)
+                                      │
+                                      ├─▶ in-memory state update
+                                      └─▶ store.write(session_id, msg)   ← 동기, 즉시
+                                              │
+                                              ▼
+                                  AES-GCM SQLite (append-only segment)
+
+Tool call/result ──▶ same path, immediate flush
+Pause(ask_user)   ──▶ pending_call snapshot, immediate flush
+LLM stream delta ──▶ buffered in-mem, flush at chunk boundary
+```
+
+**보장**: 봇 프로세스가 임의 시점에 죽어도 *디스크에 마지막으로 flush된 상태까지는* 안전. 재시작 시:
+
+1. `SessionStore.iter_active(since=now-30d)` 로 미완 세션 로드
+2. `pending_call` 이 있는 세션은 *사용자 답을 기다리는 상태*로 복원
+3. Discord 어댑터가 DM·채널·스레드별로 reattach
+4. 사용자가 다음 메시지를 보내면 **끊김 없이 이어짐** — 이게 Hermes-style 핵심
+
+**저장 모델** (SQLite 스키마):
+
+```sql
+-- 세션 메타
+CREATE TABLE sessions (
+  id            TEXT PRIMARY KEY,         -- session_key
+  principal     TEXT NOT NULL,            -- 마지막 발화 유저
+  kind          TEXT NOT NULL,            -- 'dm' | 'channel' | 'thread'
+  db_spec_id    TEXT,                     -- secrets.id 참조
+  created_at    TIMESTAMP NOT NULL,
+  updated_at    TIMESTAMP NOT NULL,
+  pending_call  TEXT,                     -- JSON | NULL
+  closed_at     TIMESTAMP                 -- NULL = active
+);
+
+-- 메시지 append-only 로그
+CREATE TABLE messages (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  session_id  TEXT REFERENCES sessions(id),
+  ts          TIMESTAMP NOT NULL,
+  role        TEXT NOT NULL,              -- system|user|assistant|tool_result
+  content     TEXT,                       -- JSON or text
+  tool_calls  TEXT,                       -- JSON | NULL
+  tool_call_id TEXT,
+  principal   TEXT
+);
+CREATE INDEX ON messages(session_id, id);
+
+-- 암호화 자격증명
+CREATE TABLE secrets (
+  id            TEXT PRIMARY KEY,         -- e.g. "user:123:default"
+  owner         TEXT NOT NULL,            -- discord user id
+  label         TEXT,                     -- "prod-pg" 같은 표시명
+  ciphertext    BLOB NOT NULL,            -- AES-GCM
+  iv            BLOB NOT NULL,
+  tag           BLOB NOT NULL,
+  created_at    TIMESTAMP NOT NULL,
+  last_used_at  TIMESTAMP
+);
+
+-- 감사 로그 (append-only)
+CREATE TABLE audit (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  ts          TIMESTAMP NOT NULL,
+  session_id  TEXT,
+  principal   TEXT,
+  kind        TEXT,                       -- 'sql' | 'tool' | 'pause' | 'safety_block'
+  payload     TEXT,                       -- JSON
+  duration_ms INTEGER,
+  status      TEXT                        -- 'ok' | 'error' | 'blocked'
+);
+```
+
+### 3.3 동시성
+
+```
+전역 concurrency       = 무제한 (asyncio)
+per-session            = FIFO 1 (같은 conversation에 동시 LLM 호출 금지)
+per-user rate limit    = token bucket  (LLM 20/min,  DB 60/min)
+per-guild rate limit   = token bucket  (DB 200/min)
+LLM stream             = 세션마다 독립 (한 사용자가 폭주해도 다른 사용자 영향 X)
+```
+
+이 모델이면 **사용자 1000명도 단일 프로세스 처리 가능**. 한 유저가 폭주해도 다른 유저는 영향 없음.
+
+---
+
+## 4. DB 연결 온보딩 (Discord-native)
+
+```
+사용자                  Bot (DM)                  Tenancy Layer
+  │                       │                             │
+  │── /connect ──────────▶│                             │
+  │                       │   Modal 출력:                │
+  │                       │   ┌──────────────────┐      │
+  │                       │   │ label: "prod-pg" │      │
+  │                       │   │ host:            │      │
+  │                       │   │ port: 5432       │      │
+  │                       │   │ database:        │      │
+  │                       │   │ user:            │      │
+  │                       │   │ password: [hide] │      │
+  │                       │   │ schema: (opt)    │      │
+  │                       │   │ sslmode: require │      │
+  │                       │   │ ☑ RO 계정인가요? │      │
+  │                       │   └──────────────────┘      │
+  │── submit ────────────▶│                             │
+  │                       │── build url ────────────────│
+  │                       │── encrypt (AES-GCM) ───────▶│ secrets.put
+  │                       │── test SELECT 1 ───────────▶│ Explorer 임시
+  │                       │── probe RO (BEGIN; CREATE TABLE __probe; ROLLBACK)
+  │                       │   - 실패하면 ✅ RO 확정      │
+  │                       │   - 성공하면 ⚠️ 경고 + 명시적 confirm
+  │                       │── SHOW TABLES ──────────────│
+  │                       │◀── ok, 17 tables ───────────│
+  │◀── ephemeral embed ───│                             │
+  │   ✅ Connected to     │                             │
+  │   "prod-pg" (17 tbls) │                             │
+  │   Try: "tables 보여줘"│                             │
+  │                       │                             │
+  │── "tables 보여줘" ───▶│                             │
+  │                       │── agent_loop(ctx) ─────────▶│ kernel
+```
+
+**핵심 결정**:
+- **Modal로만** 자격증명 입력 (슬래시 명령 인자로 URL 받지 않음) → 비밀번호가 채널 로그에 안 남음.
+- **자동 RO 검증**: `BEGIN; CREATE TABLE __probe(x int); ROLLBACK;` 시도 → 실패하면 RO 확정, 성공하면 경고.
+- **`db_url`은 절대 평문 저장 안 함**. AES-GCM 암호화 후 SQLite secrets 테이블에 저장.
+- **여러 DB 등록 가능**: `/connections` 로 목록, `/use <label>` 로 활성 DB 전환, `/disconnect <label>` 로 삭제.
+
+**관련 슬래시 명령**:
+
+| 명령 | 위치 | 동작 |
+|---|---|---|
+| `/connect` | DM | Modal로 새 DB 등록 + 검증 |
+| `/connections` | DM/Channel | 등록된 DB 목록 (label만) |
+| `/use <label>` | DM | 활성 DB 전환 |
+| `/disconnect <label>` | DM | 자격증명 삭제 |
+| `/test` | DM | 현재 활성 DB SELECT 1 |
+| `/safety` | Any | 현재 활성 보호 레이어 embed |
+| `/safety self-test` | Any | 7개 공격 자가 검증 + 결과 embed |
+| `/audit me` | Any | 본인 최근 50건 쿼리 |
+| `/audit export` | DM | CSV DM 첨부 |
+| `/model` | Any | OpenAI / NIM 모델 전환 |
+| `/reset` | DM/Channel | 현 세션 conversation 초기화 (audit는 보존) |
+
+---
+
+## 5. DB 강건성 — Safety Layer (제품의 moat)
+
+```
+요청 ─▶ ┌──────────────────────────────────────────────────────┐
+        │ L0 Connection                                         │
+        │  • RO role 권장/검증 (CREATE TABLE 시도 → 실패해야 함)│
+        │  • sslmode=require 강제 옵션                            │
+        │  • 헬스체크 + pool recycle 30분                         │
+        │  • dialect=postgres (V1 고정)                          │
+        └──────────────────────────────────────────────────────┘
+                              │
+                              ▼
+        ┌──────────────────────────────────────────────────────┐
+        │ L1 Statement Gate (sqlglot AST)                       │
+        │  • 화이트리스트: SELECT, WITH, EXPLAIN, SHOW           │
+        │  • 서브쿼리/CTE 내부도 검사 (regex 아님)               │
+        │  • 위반 시: ❌ embed "blocked: DROP not allowed"       │
+        │  • audit.kind = 'safety_block'                         │
+        └──────────────────────────────────────────────────────┘
+                              │
+                              ▼
+        ┌──────────────────────────────────────────────────────┐
+        │ L2 Cost Gate                                          │
+        │  • EXPLAIN 먼저 → 예상 rows 추출                      │
+        │  • 임계 초과(default: 1M rows) → show_plan            │
+        │  • 사용자가 ✅ 누르면 진행, ❌ 누르면 취소              │
+        │  • 본 단계는 *cost*만 검사, 권한은 L1 통과 후         │
+        └──────────────────────────────────────────────────────┘
+                              │
+                              ▼
+        ┌──────────────────────────────────────────────────────┐
+        │ L3 Runtime Caps                                       │
+        │  • statement_timeout = 30s (configurable)             │
+        │  • row_limit = 1000 (truncate + 사용자 알림)          │
+        │  • 위반 시: ⚠️ "timeout @ 30s, partial 0 rows"        │
+        └──────────────────────────────────────────────────────┘
+                              │
+                              ▼
+        ┌──────────────────────────────────────────────────────┐
+        │ L4 Audit (append-only)                                │
+        │  • {ts, principal, session_id, sql, rows, ms,         │
+        │     status, error?, safety_path}                      │
+        │  • SQLite, 일 단위 로그 회전, /audit export CSV        │
+        └──────────────────────────────────────────────────────┘
+                              │
+                              ▼
+        ┌──────────────────────────────────────────────────────┐
+        │ L5 Rate Limit (token bucket)                          │
+        │  • per-user:  LLM 20/min, DB 60/min                   │
+        │  • per-guild: DB 200/min                              │
+        │  • 위반 시: friendly "잠시 후 다시 시도, 남은 12s"      │
+        └──────────────────────────────────────────────────────┘
+                              │
+                              ▼
+                          실행 / 응답
+```
+
+### 5.1 어필 — 5가지 무기
+
+1. **`/safety` 슬래시 명령** — 현재 활성 보호 레이어를 embed로 보여줌. 마케팅 페이지가 봇 안에 있는 셈.
+2. **레드팀 자체 시연 GIF** — `DROP TABLE`, `; DELETE`, `pg_sleep(10000)`, `SELECT * FROM huge_table` 4가지를 시도하면 4가지 방식으로 막히는 30초 영상. README 첫 화면.
+3. **공개 audit log 샘플** — "이 쿼리는 이렇게 기록됩니다" JSON. SOC2/ISO27001 친화 메시지.
+4. **`/safety self-test`** — 봇이 자기 자신에게 7개 공격을 시도하고 결과를 embed로 출력. 운영자가 정기 실행 → "녹색 7/7" 스크린샷을 README에 박음.
+5. **벤치마크 페이지** — `lang2sql` vs *"그냥 LLM에 connection 던지기"*. 동일 적대적 10개 프롬프트 대결: 우리 10/10 차단, 비교군 N개 실행. 정량 비교가 가장 강한 어필.
+
+### 5.2 self-test 7개 공격 (Week 2 tests/safety/ 에 위치)
+
+| # | 입력 | 기대 결과 |
+|---|---|---|
+| 1 | `DROP TABLE users` | L1 block |
+| 2 | `; DELETE FROM users; --` (SQL injection in arg) | L1 block |
+| 3 | CTE 안에 INSERT (`WITH x AS (INSERT ...) SELECT...`) | L1 block |
+| 4 | `SELECT pg_sleep(10000)` | L3 timeout 30s |
+| 5 | `SELECT * FROM huge_table` (수십억 rows) | L2 cost gate confirm |
+| 6 | row 50,000개 반환 | L3 row_limit truncate |
+| 7 | 분당 100회 호출 | L5 rate limit |
+
+---
+
+## 6. 새 레포 레이아웃
+
+```
+lang2sql/
+├── README.md                      # Discord-first pitch + safety GIF
+├── pyproject.toml
+├── .env.example                   # LANG2SQL_MASTER_KEY, DISCORD_TOKEN, ...
+│
+├── src/lang2sql/
+│   │
+│   ├── core/                      # 순수 타입 + 포트
+│   │   ├── types.py               # Message/ToolCall/ToolResult/Event
+│   │   ├── identity.py            # Principal, GuildRole
+│   │   ├── safety_types.py        # SafetyVerdict, Budget, RateBucket
+│   │   └── ports/
+│   │       ├── llm.py
+│   │       ├── explorer.py        # capabilities() 추가
+│   │       ├── tool.py
+│   │       ├── secrets.py
+│   │       ├── session_store.py
+│   │       ├── audit.py
+│   │       └── hook.py
+│   │
+│   ├── harness/                   # kernel
+│   │   ├── context.py             # HarnessContext
+│   │   ├── session.py             # Session + pending_call + write-through
+│   │   ├── loop.py                # agent_loop (async gen)
+│   │   ├── system_prompt.py       # per-turn rebuild
+│   │   ├── tool_registry.py       # ctx 주입
+│   │   └── prompts/
+│   │
+│   ├── semantic/                  # 기존 자산 이식 (그대로)
+│   │
+│   ├── safety/                    # ★ moat
+│   │   ├── statement_gate.py      # sqlglot AST
+│   │   ├── cost_gate.py           # EXPLAIN → budget
+│   │   ├── runtime.py             # timeout / row / bytes
+│   │   ├── audit.py               # append-only logger
+│   │   ├── rate_limit.py          # token bucket
+│   │   ├── ro_probe.py            # RO 검증
+│   │   └── self_test.py           # /safety self-test 7개
+│   │
+│   ├── tools/                     # ctx-aware
+│   │   ├── explore_schema.py
+│   │   ├── run_sql.py             # → safety 통과 후 실행
+│   │   ├── write_sql.py
+│   │   ├── define_metric.py
+│   │   ├── define_dimension.py
+│   │   ├── define_relationship.py
+│   │   ├── search_semantic.py
+│   │   ├── ask_user.py
+│   │   ├── show_plan.py
+│   │   ├── visualize.py           # rows → PNG (페이지네이션 메타)
+│   │   ├── explain_query.py
+│   │   └── load_skill.py
+│   │
+│   ├── skills/                    # SkillRegistry (현재 자산 이식)
+│   │
+│   ├── tenancy/                   # 멀티유저
+│   │   ├── concierge.py           # ContextConcierge.build()
+│   │   ├── tenant_registry.py     # key → DBSpec
+│   │   ├── explorer_cache.py      # LRU SQLAlchemy engines
+│   │   ├── session_queue.py       # per-session FIFO
+│   │   └── encrypted_store.py     # AES-GCM SQLite
+│   │
+│   ├── discord/                   # ★ 1급 frontend
+│   │   ├── bot.py                 # discord.py 진입점
+│   │   ├── commands/
+│   │   │   ├── connect.py         # /connect Modal
+│   │   │   ├── connections.py     # /connections /use /disconnect
+│   │   │   ├── safety.py          # /safety, /safety self-test
+│   │   │   ├── audit.py           # /audit me /audit export
+│   │   │   ├── model.py           # /model (openai/nim)
+│   │   │   ├── reset.py           # /reset
+│   │   │   └── help.py
+│   │   ├── session_router.py      # msg → session_key
+│   │   ├── streaming.py           # 토큰 → message edit (throttle 1s)
+│   │   ├── interactive.py         # ask_user → Button view
+│   │   ├── render.py              # rows → PNG (페이지 분할)
+│   │   ├── permissions.py         # guild admin 검사
+│   │   └── recovery.py            # 부팅 시 active session reattach
+│   │
+│   ├── adapters/
+│   │   ├── llm/
+│   │   │   ├── openai_.py
+│   │   │   └── nvidia_nim.py      # OpenAI-호환 엔드포인트
+│   │   ├── db/
+│   │   │   └── postgres_explorer.py
+│   │   ├── secrets/
+│   │   │   └── encrypted_sqlite.py
+│   │   ├── session_store/
+│   │   │   └── encrypted_sqlite.py
+│   │   └── audit_sink/
+│   │       └── sqlite.py
+│   │
+│   └── frontends_dev/             # 부수 (개발 도구)
+│       ├── cli.py                 # 단발 질의 디버그
+│       └── serve.py               # NDJSON (tui-go 유지용)
+│
+├── tui-go/                        # 유지 — Discord 불가 시 fallback
+├── tests/
+│   ├── safety/                    # 7개 공격 회귀 (CI 차단 기준)
+│   ├── harness/
+│   ├── discord/                   # discord mock
+│   └── tenancy/
+└── docs/
+    ├── discord_first_redesign.md  # ← 본 문서
+    ├── DB_ROBUSTNESS.md           # ★ trust page
+    ├── DISCORD_ONBOARDING.md      # 사용자 가이드
+    └── DEPLOY.md
+```
+
+---
+
+## 7. 마이그레이션 — 5주 plan
+
+```
+Week 1 ─ Foundation                                         [PR-1]
+   • core/ports/* 정의
+   • HarnessContext + Session(pending_call) + Tool(ctx, **args)
+   • agent_loop + per-turn system prompt
+   • semantic/* 그대로 이식
+   • frontends_dev/cli.py 로 kernel 검증
+
+Week 2 ─ Safety Layer                                       [PR-2]
+   • statement_gate (sqlglot)
+   • runtime (timeout/row)
+   • audit (sqlite sink)
+   • ro_probe
+   • self_test 7개 + tests/safety/ (CI gate)
+
+Week 3 ─ Tenancy + Persistence (Hermes-style)               [PR-3]
+   • encrypted_sqlite (AES-GCM)  — secrets + sessions 통합
+   • SessionStore.write_through() + iter_active()
+   • tenant_registry + explorer_cache
+   • session_queue
+   • ContextConcierge
+
+Week 4 ─ Discord (product 본체)                              [PR-4]
+   • bot 진입 + /connect Modal + onboarding 전 플로우
+   • session_router (DM/channel/thread)
+   • recovery.py (부팅 reattach)
+   • streaming + interactive (Button view)
+   • render (PNG 페이지네이션)
+   • /safety, /audit, /connections, /use, /model
+
+Week 5 ─ Polish + Appeal                                    [PR-5]
+   • /safety self-test 자동 데모
+   • README GIF + benchmark
+   • DB_ROBUSTNESS.md trust page
+   • cost_gate (EXPLAIN) — 마지막
+   • DEPLOY.md (Oracle Cloud / fly.io)
+```
+
+각 PR은 별 브랜치(`feature/week{N}-*`)로 끊고, 직전 PR이 master에 머지된 후 다음 시작.
+
+---
+
+## 8. 차트 페이지네이션 (질문 #4 상세)
+
+요구: 행이 많을 때 한 메시지에 다 넣으면 Discord 한도(첨부 8MB, 이미지 1장 권장)에 걸림.
+
+```
+DataEvent (rows=N) ──▶ discord/render.py
+                          │
+                          ├─▶ row 수에 따라 분할:
+                          │     ≤ 50 rows   → 텍스트 embed 1개
+                          │     ≤ 500 rows  → PNG table 1장
+                          │     > 500 rows  → 50행씩 PNG 페이지 K장
+                          │
+                          ├─▶ K장이 ≤ 10이면: 한 메시지에 attachments=[png1..pngK]
+                          │
+                          └─▶ K > 10이면: View(buttons=[◀ Prev, Next ▶, ⇩ CSV])
+                                            └─ 누를 때마다 message.edit(file=...)
+                                            └─ CSV 버튼 = 전체 CSV를 DM 첨부
+
+차트(시각화) 도 동일 패턴:
+  - 단일 line/bar → 1장
+  - facet (예: 카테고리별 시계열) → 카테고리당 1장, 페이지 버튼
+```
+
+`tools/visualize.py` 가 `VizSpec` 을 반환하고, Discord 어댑터의 `render.py` 가 spec → PNG 변환·페이지 분할 책임을 짐. **렌더링은 discord 레이어에만 존재** → 다른 frontend(TUI 등)는 spec을 받아 자기 방식으로 렌더링.
+
+---
+
+## 9. LLM 멀티 백엔드 — OpenAI + NVIDIA NIM
+
+```
+adapters/llm/openai_.py        — 기존 자산 그대로
+adapters/llm/nvidia_nim.py     — base_url 만 https://integrate.api.nvidia.com/v1
+                                  api_key 만 NVIDIA_API_KEY
+                                  나머지는 OpenAI 클라이언트 그대로 재사용
+```
+
+**`/model` 명령** — Modal/Select로 모델 선택:
+
+| Provider | 노출 후보 (디폴트는 V1에서 1개씩 고정) |
+|---|---|
+| OpenAI | `gpt-4.1`, `gpt-4.1-mini`, `o4-mini` |
+| NVIDIA NIM | `meta/llama-3.1-70b-instruct`, `mistralai/mixtral-8x22b-instruct-v0.1`, `nvidia/llama-3.1-nemotron-70b-instruct` |
+
+선택은 **세션 스코프** (DM 세션마다 다른 모델 가능). audit log에 `model_id` 기록.
+
+비용 관점:
+- OpenAI: per-token, 디폴트는 `gpt-4.1-mini` (저렴) 추천
+- NIM: NVIDIA 계정 무료 크레딧 사용 → 떨어지면 자비. `/model` 로 OpenAI 폴백 유도.
+- 향후 글로벌 per-user 토큰 캡 추가 가능 (Week 5+).
+
+---
+
+## 10. 잔여 결정 (Week 1 착수 전 답이 있으면 좋음)
+
+1. **NIM 모델 디폴트** — 70B Llama vs Mixtral 8x22B? (Mixtral이 tool-calling 안정성↑)
+2. **첫 배포 길드** — 가짜연구소 디스코드인가, 본인 테스트 길드인가? 부팅 시 길드 화이트리스트 적용 여부.
+3. **세션 retention** — 비활성 세션을 며칠까지 보존? (현재 §3.2 가정: 30일 후 archive로 이동, 90일 후 삭제)
+4. **audit retention** — 동일 질문, 별도 정책 필요? (compliance 관점)
+5. **`/reset` 시 audit 보존 여부** — 기본 보존 권장(이미 기록된 건 지우면 안 됨), 사용자에게 명시.
+
+위 5개는 Week 1 코드에 직접 영향 없으므로 그동안 답변 받으면 됩니다.
+
+---
+
+## 11. 한 줄 요약
+
+> **kernel/safety 레이어를 hexagonal로 굳히고, Discord adapter와 SafetyLayer를 1급 영역으로 격상하고, Hermes-style write-through로 세션을 영속화한다. 그 외 모든 것은 어댑터 한 장.**
+
+— end —
diff --git a/docs/discord_first_redesign_v2.md b/docs/discord_first_redesign_v2.md
new file mode 100644
index 0000000..7d9acd7
--- /dev/null
+++ b/docs/discord_first_redesign_v2.md
@@ -0,0 +1,911 @@
+# Lang2SQL — Discord-First 재설계 명세 (v2)
+
+> **작성일**: 2026-05-18
+> **결정자**: ryan@brain-crew.com
+> **상태**: v1 → v2. Codex 독립 리뷰 + Agent Teams 다각도 audit (devils-advocate / discord-fact-checker / pg-safety-expert / codebase-reality) 결과 반영.
+> **선행 문서**: `docs/discord_first_redesign.md` (v1, 보존)
+> **범위**: 현 `lang2sql/` 트리를 **evolve in place** 로 점진 재구성 (v1의 "wipe and rebuild" 어조는 폐기. §6 참조.)
+
+---
+
+## v1 → v2 변경 요약
+
+| # | 영역 | v1 | v2 |
+|---|---|---|---|
+| 1 | **타이브레이커** | 3축 (UX·무결성·맥락) | **4축** — *의미적 정확성* 추가 |
+| 2 | **§3 세션** | DM/채널/스레드 모두 V1 | **V1은 DM-only**, 채널/스레드는 V2 (allowlist 이후) |
+| 3 | **§3.2 영속화** | 모든 토큰 delta 까지 flush | **6개 이벤트만 append-log**, stream chunk 복구 폐기 |
+| 4 | **§3.2 스키마** | sessions/messages/secrets/audit | **+ `persistent_views`** 추가 (Discord 재시작 복구 필수) |
+| 5 | **§4 `/connect`** | 7+필드 Modal + `password: [hide]` | **connection string 1필드 Modal** (Discord Modal은 5필드 한도·password style 미지원) |
+| 6 | **§4 RO probe** | `CREATE TABLE __probe; ROLLBACK` | **catalog 쿼리** (`information_schema.role_table_grants` + `pg_has_role`) |
+| 7 | **§4 writable 계정** | "경고 + confirm" | **거부 + 도우미 명령** `/grant-readonly` 가 role 생성 SQL 제공 |
+| 8 | **§5 L0 Connection** | "RO role 권장" | **dedicated `lang2sql_readonly` role + 5개 GUC SET (`temp_file_limit='1GB'` 단위 필수)** |
+| 9 | **§5 L1 Statement Gate** | sqlglot 화이트리스트만 | **catalog-driven function denylist (OID 매칭) + `EXPLAIN ANALYZE + DML` 거부 + `COPY` 전면 차단** |
+| 10 | **§5 L2 Cost Gate** | EXPLAIN row → 차단 | **EXPLAIN 다중 metric → 경고+사용자 confirm**. 실제 차단은 L3 runtime cap에 위임 |
+| 11 | **§5 L3 Runtime** | timeout/row만 명시 | **5개 GUC 모두 명시** (statement_timeout, lock_timeout, idle_in_transaction_session_timeout, temp_file_limit, search_path) + `row_security=on` |
+| 12 | **§5 L4 Audit** | hash chain 암시 | hash chain은 V2 로 명시 이전. V1은 append-only SQLite + 일 회전 |
+| 13 | **§7 일정** | 5주, Week 4 과적재 + cost_gate Week 5 모순 | **6 PR (PR-0 + 5주 + 0.5주 여유)**. Week 4 분할, cost_gate는 Week 2 (경고 모드)로 이동 |
+| 14 | **§6 레이아웃** | 신규 트리 (wipe) | **evolve in place**. 보존/포팅/삭제 표로 명시 |
+| 15 | **§9 NIM** | "OpenAI 호환 그대로 재사용" | **contract test 통과 후 experimental** 노출, OpenAI가 V1 디폴트 |
+| 16 | **§1.4 (신규)** | — | **Discord 플랫폼 제약** 단독 절: Modal 5필드, Interaction token 15분, autocomplete 3s, persistent view 요건 |
+| 17 | **§2 다이어그램** | sync 추정 | **async boundary 명시** — `create_async_engine(asyncpg)` |
+| 18 | **§ToolResult 규약 (신규 §3.4)** | `data: Any` | **canonical shape** (`{kind, payload, meta}`) — write-through 영속화 호환 |
+| 19 | **§11 (신규)** | — | Codex 지적 중 **거부한 항목**과 사유 (transparency) |
+| 20 | **§10 (개편)** | open questions | **V1 명시적 제외 = V2+** 항목 정리 |
+
+---
+
+## 0. 제품 한 줄과 타이브레이커
+
+> **"Discord에서 쓰는 read-only · audit-by-default SQL 에이전트.
+> DB는 절대 변하지 않고, 답은 의미적으로 검증 가능하며, 모든 쿼리는 예산/시간/행 한도 안에서 돈다.
+> 대화 맥락은 끊겨도 영속된다."**
+
+설계 충돌 시 우선순위 (위에서 아래 = 강함):
+
+1. **DB 무결성** — 쓰기·부작용·자원 hog가 발생하지 않는가
+2. **의미적 정확성** — 답이 문법적으로만이 아니라 *의미적으로* 맞는가
+3. **Discord UX 단순성** — 한 번의 입력으로 가능한 결과를 얻는가
+4. **맥락 보존** — 끊겨도 이어지는가
+
+`v1`은 "DB는 안 깨지는가?"만 다뤘다. NL→SQL 제품의 진짜 위험은 *"안전하게 실행되어 자신 있게 틀린 결론을 답하는 것"* — 정확성 축이 v2의 핵심 추가.
+
+타이브레이커는 **3축에서 4축으로**. (Codex의 5축 권고는 솔로 트라이얼에 과한 product framing이라 거부 — 4축이 적정 균형.)
+
+---
+
+## 1. 확정된 기술 결정
+
+| # | 항목 | 선택 | 근거 |
+|---|---|---|---|
+| 1 | Discord lib | **`discord.py` 2.x** | 가장 성숙. 단, Modal 5필드 한도·Interaction token 15분 만료 등 §1.4 제약 인지. |
+| 2 | DB 엔진 타깃 (V1) | **PostgreSQL** | EXPLAIN·`SET TRANSACTION READ ONLY`·dedicated role·`statement_timeout` 등 모든 safety 기법이 정직하게 동작. V2: MySQL/SQLite/BigQuery. |
+| 3 | 세션 영속화 | **Hermes-style write-through, 6 event types** | 매 발화·도구·일시정지를 즉시 flush. **스트림 청크 복구는 폐기** (idempotency 폭탄 위험). |
+| 4 | 세션 + 자격증명 스토어 | **AES-GCM 암호화 SQLite (per-row, secrets 테이블만)** | secrets만 행 단위 암호. sessions/messages/audit는 평문(검색 가능). 키 분실 시 secrets만 무효. |
+| 5 | LLM 백엔드 | **OpenAI 디폴트, NVIDIA NIM은 contract-test 통과 후 experimental** | NIM 어댑터는 `base_url` 차이만이라 30 LOC. 단, tool-calling/streaming/JSON schema 동치성은 contract test로 검증 후 `/model` 노출. |
+| 6 | DB 드라이버 | **`asyncpg` via `sqlalchemy.ext.asyncio.create_async_engine`** | discord.py는 100% asyncio. sync SQLAlchemy를 그대로 호출하면 event loop를 블록하여 gateway disconnect 위험. |
+| 7 | Go TUI | **freeze 유지 (개발 도구)** | NDJSON 인터페이스(`cli/commands/serve.py`) 호환 그대로. V1에선 신규 기능 0. |
+| 8 | Python TUI (`src/lang2sql/tui/`) | **삭제** | 스펙에 없고 Discord가 1급 frontend. 약 1,400 LOC 정리. |
+| 9 | 차트 출력 | **PNG 첨부 + Discord 한도 인지 페이지네이션** | 메시지 2000자 / embed description 4096자 / embed 총 6000자 / 첨부 8MB 한도. §8 참조. |
+| 10 | 호스팅 (트라이얼) | **소형 VPS** | §1.1 참조. Cloudflare Workers는 부적합. |
+
+### 1.1 호스팅 — Cloudflare Workers는 부적합
+
+`discord.py` 는 Discord WebSocket gateway에 **계속 붙어 있어야 하는 장기 실행 Python 프로세스**입니다. Cloudflare Workers의 edge runtime은 short-request 모델이라 불가.
+
+| 옵션 | 비용 | 메모 |
+|---|---|---|
+| **Oracle Cloud Always Free** | $0 무기한 | ARM Ampere 4코어/24GB. 카드 검증 필요. |
+| **fly.io shared-cpu-1x** | $0 ~ $5/월 | 256MB 시작. 한국 가까운 region. |
+| **Hetzner CX11** | €4.5/월 (~6,500원) | 안정·빠름. 유럽 region. |
+| **본인 PC 24h** | $0 | 데모 단계 충분. |
+
+### 1.2 "타깃 = 가짜연구소 디스코드?" 정리
+
+질문하신 *"이 타깃이 가짜연구소 디스코드?"* 에 대해: 문서의 "타깃"은 **지원할 DB 엔진**(PG vs MySQL vs BQ)을 의미. **배포 커뮤니티**(어느 길드에 봇을 초대하는가)와는 별개. V1 코드는 어떤 길드에든 동작.
+
+### 1.3 자격증명 저장 (모순 명확화)
+
+- 단일 SQLite 파일 `lang2sql.db` 안에 4개 테이블 (`secrets`, `sessions`, `messages`, `audit`, `persistent_views`).
+- **`secrets` 테이블만** AES-GCM per-row 암호화 (컬럼: `ciphertext`, `iv`, `tag`).
+- `sessions`/`messages`/`audit`/`persistent_views`는 평문. 검색 가능. (대화 텍스트 자체가 민감하다 판단되면 V2에서 전체 컬럼 암호로 확장.)
+- 마스터키: `LANG2SQL_MASTER_KEY` env. 분실 시 **secrets만 무효** — 사용자가 `/connect` 재등록. 대화/감사는 보존.
+- (v1 §1.3 vs §1#4의 "모순"은 Codex 오독. SQLCipher 형 파일 단위 암호가 아니라 per-row 컬럼 암호로 명확화.)
+
+### 1.4 Discord 플랫폼 제약 (신규)
+
+이 제약들이 §4 설계와 §3 영속화 스키마를 직접 좌우.
+
+| 제약 | 값 | 영향 |
+|---|---|---|
+| **Modal 최대 컴포넌트** | 5개 TextInput (각 ActionRow 1개) | §4 `/connect`는 single-field connection string 강제. |
+| **Modal password style** | **없음** (Short / Paragraph 2종만) | 비밀번호 평문 입력. 완화책: dedicated `lang2sql_readonly` role + 1회용 약한 비밀번호. |
+| **Interaction token** | 발급 후 **15분 만료** | 장기 쿼리 결과는 `interaction.edit_original_response()` 대신 `bot.message.edit(channel_id, message_id)` (bot token) 로. |
+| **Slash command 자동완성** | **3초 응답 데드라인** | DB 카탈로그 자동완성은 in-memory 캐시 필수 (실시간 조회 불가). |
+| **메시지 길이** | content 2000자 / embed description 4096자 / embed 총 6000자 | 결과는 PNG 또는 첨부파일로 강제. |
+| **메시지 첨부** | 8MB / 메시지 (무료 길드) | 차트 PNG 페이지 분할 필요. §8. |
+| **persistent View** | `View(timeout=None)` + 모든 항목에 `custom_id` ≤ 100자 + `setup_hook()`에서 `add_view()` 재등록 | §3.2 `persistent_views` 테이블 필수. |
+| **`custom_id`** | 100자 한도 | `query:{user_id}:{hash16}` 형태로 압축. |
+
+출처: https://docs.discord.com/developers/components/reference , https://discordpy.readthedocs.io/en/latest/
+
+---
+
+## 2. 상위 아키텍처 (async 경계 명시)
+
+```
+                          ┌──────────────────────────────┐
+                          │      DISCORD GATEWAY         │
+                          │  (WebSocket, asyncio)        │
+                          └───────────────┬──────────────┘
+                                          │
+                                          ▼
+┌──────────────────────────────────────────────────────────────────────┐
+│                       DISCORD ADAPTER  (1급, asyncio)                 │
+│  /connect Modal · SessionRouter · Streaming(throttled edit)           │
+│  Interactive(persistent View) · Render(PNG paginate) · Permissions    │
+│  Recovery(reattach via persistent_views table)                        │
+└───────────────────────────┬──────────────────────────────────────────┘
+                            │ async ctx = await Concierge.build(key, principal)
+                            ▼
+┌──────────────────────────────────────────────────────────────────────┐
+│                       TENANCY LAYER  (asyncio)                        │
+│  TenantRegistry · ExplorerCache(LRU async engines)                    │
+│  EncryptedStore · ContextConcierge · SessionQueue(per-session FIFO)   │
+└───────────────────────────┬──────────────────────────────────────────┘
+                            ▼ ctx
+┌──────────────────────────────────────────────────────────────────────┐
+│                       HARNESS KERNEL  (asyncio)                       │
+│  agent_loop · system_prompt(per turn) · ToolRegistry(ctx 주입)        │
+│  Session(write-through, 6 events) · Hooks(pub/sub)                    │
+└──────┬─────────────────────┬──────────────────┬──────────────────────┘
+       │ ports               │                  │
+       ▼                     ▼                  ▼
+┌──────────────────────────────────────────────────────────────────────┐
+│                   SAFETY LAYER  (제품의 moat)                         │
+│  L0 connect (dedicated readonly role + 5 GUC SET)                     │
+│  L1 stmt gate (sqlglot AST + catalog-driven function denylist by OID) │
+│  L2 cost gate (EXPLAIN multi-metric → user confirm)                   │
+│  L3 runtime caps (statement_timeout, lock_timeout, ...)               │
+│  L4 audit (append-only SQLite, 일 회전)                                │
+│  L5 rate limit (token bucket)                                         │
+└──────┬─────────────────────┬──────────────────┬──────────────────────┘
+       ▼                     ▼                  ▼
+┌──────────────────────────────────────────────────────────────────────┐
+│                     OUTBOUND ADAPTERS                                 │
+│  LLM (openai / nvidia-nim contract-tested)                            │
+│  DB (sqlalchemy.ext.asyncio + asyncpg)                                │
+│  Secrets·SessionStore·AuditSink·PersistentViewStore (encrypted-sqlite)│
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+규칙은 v1과 동일 — 화살표는 안쪽으로만. 변경점은 **모든 레이어 asyncio 명시**.
+
+---
+
+## 3. 세션 전략
+
+### 3.1 V1 = DM-only
+
+| Discord 컨텍스트 | session_key | V1 상태 |
+|---|---|---|
+| **봇과의 DM** | `dm:{user_id}` | ✅ **V1 디폴트 (유일한 진입로)** |
+| 길드 채널 | `chan:{guild_id}:{channel_id}` | ⏸ V2 (table/schema allowlist + admin 승인 절차 이후) |
+| 길드 스레드 | `thr:{guild_id}:{channel_id}:{thread_id}` | ⏸ V2 |
+
+**근거**:
+- 길드 채널은 *"채널 멤버 전원 가시"* — read-only여도 PII/민감 row가 노출되는 순간 **데이터 유출 제품**이 됨.
+- V1 트라이얼은 개인 분석이 핵심 use case. 채널/스레드는 V2에서 권한 모델(allowlist + per-user audit) 완성 후 개방.
+- (Codex + devils-advocate 합의: V1 공용 채널 활성화는 제품 정체성 ("read-only · audit-by-default")의 자기부정.)
+
+**Cross-session 격리**: 같은 user가 DM과 (V2의) 채널을 동시 사용해도 ExplorerCache·rate-limit·schema_cache 키는 **(session_key, principal)** 페어로 격리. 같은 principal이라도 다른 session_key면 메타데이터 누설 금지.
+
+### 3.2 영속화 — Hermes-style, 6 event types only
+
+스트림 청크 단위 복구는 폐기. **6개 이벤트만** append-log:
+
+```
+user_msg          — 사용자 발화 (1회/메시지)
+tool_started      — 도구 호출 시작
+tool_finished     — 도구 결과 (성공/실패)
+assistant_final   — 어시스턴트 최종 응답 (스트림 종료 시 1회)
+pending_prompt    — ask_user / show_plan으로 일시정지 진입
+run_interrupted   — 프로세스 종료/타임아웃으로 중단 (재시작 시 표시용)
+```
+
+```
+User msg ──▶ Discord adapter ──▶ session.append('user_msg', payload)
+                                        │
+                                        ├─▶ in-memory state update
+                                        └─▶ store.write_tx(...)   ← 동기 트랜잭션
+                                                │
+                                                ▼
+                                       SQLite (WAL, append-only)
+
+Tool start/end   ──▶ append('tool_started' / 'tool_finished')
+Pause(ask_user)  ──▶ append('pending_prompt') + flush
+LLM stream delta ──▶ buffered in-memory, NO persistence
+Crash mid-turn   ──▶ 다음 부팅 시 turn에 'run_interrupted' 표시
+                     사용자가 다음 메시지 보내면 새 turn으로 시작
+                     (자동 재시도 안 함 — idempotency 폭탄 방지)
+```
+
+**보장**: 마지막으로 flush된 event까지 안전. 재시작 시:
+1. `SessionStore.iter_active(since=now-30d)` 로 미완 세션 로드.
+2. 마지막 event가 `pending_prompt` 면 그대로 대기 상태 복원.
+3. 마지막 event가 `tool_started` 인데 `tool_finished` 없으면 `run_interrupted` 추가 + 사용자에게 "중단됨, `/retry` 로 재시도하세요" 표시.
+4. Discord adapter가 DM별로 reattach.
+5. **Persistent View** (cost confirm 버튼, paginate 버튼)는 `persistent_views` 테이블에서 message_id·channel_id 복원 후 `setup_hook()`에서 `add_view()`.
+
+(v1의 "끊김 없이 이어짐" 어조는 과장이었음 — v2는 *"중단 표시 후 명시 재시도"* 로 축소.)
+
+### 3.3 저장 스키마
+
+```sql
+-- 세션 메타
+CREATE TABLE sessions (
+  id            TEXT PRIMARY KEY,         -- session_key (V1: dm:USER_ID)
+  principal     TEXT NOT NULL,            -- 마지막 발화 user id
+  kind          TEXT NOT NULL,            -- V1: 'dm'
+  db_spec_id    TEXT REFERENCES secrets(id),
+  active_model  TEXT,                     -- 'openai:gpt-4.1-mini' 등
+  created_at    TIMESTAMP NOT NULL,
+  updated_at    TIMESTAMP NOT NULL,
+  closed_at     TIMESTAMP
+);
+
+-- 이벤트 append-only (6 종)
+CREATE TABLE events (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  session_id  TEXT REFERENCES sessions(id),
+  ts          TIMESTAMP NOT NULL,
+  kind        TEXT NOT NULL,              -- user_msg|tool_started|...|run_interrupted
+  payload     TEXT NOT NULL,              -- canonical JSON (§3.4)
+  principal   TEXT
+);
+CREATE INDEX events_by_session ON events(session_id, id);
+
+-- 암호화 자격증명
+CREATE TABLE secrets (
+  id            TEXT PRIMARY KEY,         -- e.g. "user:123:prod-pg"
+  owner         TEXT NOT NULL,
+  label         TEXT NOT NULL,
+  ciphertext    BLOB NOT NULL,            -- AES-GCM
+  iv            BLOB NOT NULL,
+  tag           BLOB NOT NULL,
+  created_at    TIMESTAMP NOT NULL,
+  last_used_at  TIMESTAMP
+);
+
+-- 감사 로그
+CREATE TABLE audit (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  ts          TIMESTAMP NOT NULL,
+  session_id  TEXT,
+  principal   TEXT,
+  kind        TEXT,                       -- 'sql'|'tool'|'safety_block'|'rate_block'
+  payload     TEXT,                       -- JSON
+  duration_ms INTEGER,
+  status      TEXT                        -- 'ok'|'error'|'blocked'
+);
+
+-- ★ Discord persistent view 복구용 (신규)
+CREATE TABLE persistent_views (
+  message_id   TEXT PRIMARY KEY,
+  channel_id   TEXT NOT NULL,
+  guild_id     TEXT,                      -- DM이면 NULL
+  view_kind    TEXT NOT NULL,             -- 'cost_confirm'|'paginate'|'ask_user'|'plan_approval'
+  state_json   TEXT NOT NULL,             -- view 생성자에게 넘길 인자
+  session_id   TEXT REFERENCES sessions(id),
+  expires_at   TIMESTAMP,                 -- NULL = persistent
+  created_at   TIMESTAMP NOT NULL
+);
+CREATE INDEX views_active ON persistent_views(expires_at) WHERE expires_at IS NULL;
+```
+
+### 3.4 ToolResult canonical shape (신규)
+
+`ToolResult.data` 가 `Any` 면 SQLite write-through 시 직렬화 불일치로 복구 불가능. canonical:
+
+```python
+{
+  "kind": "rows" | "ddl" | "list" | "viz_spec" | "scalar" | "none",
+  "payload": ...,           # kind에 따라:
+                            #   rows  → [{...}, ...]
+                            #   ddl   → "CREATE TABLE ..."
+                            #   list  → ["t1", "t2", ...]
+                            #   viz_spec → {chart_type, data, ...}
+                            #   scalar → number | string
+                            #   none  → null
+  "meta": {                 # 공통 메타
+    "truncated": bool,
+    "row_count": int,
+    "elapsed_ms": int,
+    "warnings": [str, ...]
+  }
+}
+```
+
+도구 12개 전부 이 shape에 맞춤 (대부분 이미 dict 반환 — 키 표준화만).
+
+**Provider-coupling 처리**: conversation은 internal canonical 형식 (`role` ∈ {system|user|assistant|tool_result}, `tool_calls`는 OpenAI-like)으로 저장. OpenAI 어댑터는 통과, Anthropic 어댑터는 양방향 변환. 모델을 *같은 provider family 내에서* 전환할 땐 conversation 유지. **provider family를 넘는 전환 (OpenAI↔Anthropic)** 시 사용자에게 "대화 초기화" 명시 confirm.
+
+### 3.5 동시성
+
+```
+전역 concurrency    = 무제한 (asyncio)
+per-session         = FIFO 1 (같은 conversation에 동시 LLM 호출 금지)
+per-user rate       = token bucket (LLM 20/min,  DB 60/min)
+per-guild rate      = token bucket (DB 200/min)        ← V2 채널 활성화 시
+LLM stream          = 세션마다 독립
+DB engines          = ExplorerCache LRU 50 (per db_url)
+```
+
+SQLite는 WAL 모드 + `busy_timeout=200ms`. V1 두 자릿수 동시 사용자에 충분. V2 본격 트래픽 시 Postgres 백엔드로 교체 (어댑터만 갈아끼움).
+
+---
+
+## 4. DB 연결 온보딩 (Discord-native, 재설계)
+
+**v1 → v2 결정적 변경**: Modal 5필드 한도 + password style 미지원에 맞춰 **connection string 단일 필드 모델**로 전환.
+
+### 4.1 `/connect` Modal (5필드)
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  /connect                                                │
+├─────────────────────────────────────────────────────────┤
+│  label              (Short, required)                   │
+│  └ 예: "prod-pg"                                         │
+│                                                          │
+│  connection_url     (Paragraph, required)               │
+│  └ postgresql://USER:PASS@HOST:5432/DB?sslmode=require  │
+│  └ ⚠️ 가급적 dedicated readonly role 사용                │
+│  └ /grant-readonly 로 role 생성 SQL 확인                 │
+│                                                          │
+│  default_schema     (Short, optional)                   │
+│  └ 비우면 'public'                                       │
+│                                                          │
+│  notes              (Paragraph, optional)               │
+│  └ 본인 메모                                              │
+│                                                          │
+│  acknowledgment     (Short, required)                   │
+│  └ "READ-ONLY" 라고 정확히 입력해야 제출 가능             │
+└─────────────────────────────────────────────────────────┘
+```
+
+5필드 정확히 사용. password masking은 Discord가 지원 안 함 — 평문이지만 Modal 자체가 interaction-scoped (메시지 history에 안 남음). 사용자에게 *"본인만 보이며 채팅 로그에 남지 않습니다. 그러나 화면 입력 중에는 노출되므로 dedicated readonly role + 1회용 비밀번호 사용을 강력 권장"* 안내.
+
+### 4.2 제출 직후 처리 (`on_modal_submit`)
+
+```
+1. Parse connection_url → host/port/user/pass/db/options 분해. parse 실패 시 ephemeral error.
+2. AES-GCM 즉시 암호화 → secrets 테이블 put. 메모리 평문 즉시 zeroize.
+3. Async engine 임시 생성 (asyncpg). pool_size=1, pool_recycle=30s.
+4. ★ RO Probe (catalog 쿼리, fail-closed):
+     SELECT
+       current_setting('transaction_read_only')::bool                 AS tx_ro,
+       (SELECT bool_or(pg_has_role(current_user, r, 'USAGE'))
+        FROM unnest(ARRAY['pg_write_all_data']) r)                    AS has_write_role,
+       EXISTS (
+         SELECT 1 FROM information_schema.role_table_grants
+         WHERE grantee = current_user
+           AND privilege_type IN ('INSERT','UPDATE','DELETE','TRUNCATE')
+           AND table_schema NOT IN ('pg_catalog','information_schema')
+       )                                                              AS has_write_grant;
+5. has_write_role = TRUE 또는 has_write_grant = TRUE 면:
+   ❌ REJECT. 사용자에게 안내:
+     "이 계정은 쓰기 권한을 가지고 있어 등록할 수 없습니다.
+      `/grant-readonly` 명령을 실행하면 read-only role 생성 SQL을 보내드립니다."
+   secrets 행 즉시 삭제.
+6. SELECT 1 검증 + `SELECT count(*) FROM information_schema.tables WHERE table_schema=...`
+7. 성공 ephemeral embed:
+   "✅ Connected to 'prod-pg'. N tables visible. Try: \"tables 보여줘\""
+```
+
+(v1의 `BEGIN; CREATE TABLE __probe; ROLLBACK` 은 fail-open이라 폐기. CREATE 권한 없음 ≠ UPDATE 권한 없음.)
+
+### 4.3 `/grant-readonly` 도우미 명령
+
+```
+사용자: /grant-readonly database=prod_db schema=public
+
+봇 DM:
+  다음 SQL을 PG superuser로 실행하세요. 비밀번호 부분만 교체:
+
+  CREATE ROLE lang2sql_ro_USER123 LOGIN PASSWORD '<DISPOSABLE>';
+  GRANT CONNECT ON DATABASE prod_db TO lang2sql_ro_USER123;
+  GRANT USAGE ON SCHEMA public TO lang2sql_ro_USER123;
+  GRANT SELECT ON ALL TABLES IN SCHEMA public TO lang2sql_ro_USER123;
+  ALTER DEFAULT PRIVILEGES IN SCHEMA public
+    GRANT SELECT ON TABLES TO lang2sql_ro_USER123;
+  ALTER ROLE lang2sql_ro_USER123 SET default_transaction_read_only = on;
+
+  완료되면 /connect 로 이 계정을 등록하세요.
+```
+
+writable confirm 옵션 폐기 — read-only가 제품 정체성인데 우회를 열어두는 건 약속 깨짐. 대신 사용자가 RO role을 만들기 쉽게 도와줌.
+
+### 4.4 슬래시 명령 (V1)
+
+| 명령 | 위치 | 동작 |
+|---|---|---|
+| `/connect` | DM | §4.1 Modal |
+| `/grant-readonly` | DM | §4.3 SQL 생성기 |
+| `/connections` | DM | 등록 DB 목록 (label만, 비밀번호 안 보임) |
+| `/use <label>` | DM | 활성 DB 전환 |
+| `/disconnect <label>` | DM | 자격증명 삭제 |
+| `/test` | DM | 현재 활성 DB `SELECT 1` + RO probe 재실행 |
+| `/safety` | DM | 현재 활성 보호 레이어 embed |
+| `/safety self-test` | DM | 7개 공격 자가 검증 |
+| `/audit me` | DM | 본인 최근 50건 쿼리 |
+| `/audit export` | DM | CSV 첨부 |
+| `/model` | DM | provider 내 model 전환 (provider 변경 시 confirm) |
+| `/reset` | DM | 현 세션 conversation 초기화 (audit 보존) |
+| `/retry` | DM | 마지막 `run_interrupted` 턴 재시도 |
+| `/help` | DM | 명령 목록 |
+
+---
+
+## 5. DB 강건성 — Safety Layer (v2 강화)
+
+```
+요청 ─▶ ┌──────────────────────────────────────────────────────┐
+        │ L0 Connection                                         │
+        │  • dedicated `lang2sql_readonly` role 강제 (§4.3)     │
+        │  • sslmode=require / verify-full 옵션                  │
+        │  • create_async_engine + asyncpg (event loop 비차단)  │
+        │  • pool_size=5, pool_recycle=30min, pool_pre_ping=on  │
+        │  • 매 connection 시작 시 GUC 일괄 SET:                  │
+        │      SET ROLE <readonly_role>;                        │
+        │      SET default_transaction_read_only = on;          │
+        │      SET transaction_read_only = on;                  │
+        │      SET statement_timeout = '30s';                   │
+        │      SET lock_timeout = '5s';                         │
+        │      SET idle_in_transaction_session_timeout = '60s'; │
+        │      SET temp_file_limit = '1GB';     ← 단위 필수!     │
+        │      SET search_path = pg_catalog, <user_schema>;     │
+        │      SET row_security = on;                           │
+        │  ※ SET TRANSACTION READ ONLY 단독은 부족함을 인지       │
+        │     (PG: "high-level, does not prevent all writes")   │
+        └──────────────────────────────────────────────────────┘
+                              │
+                              ▼
+        ┌──────────────────────────────────────────────────────┐
+        │ L1 Statement Gate (sqlglot AST + catalog denylist)    │
+        │                                                        │
+        │  (a) sqlglot AST 파싱, 화이트리스트:                    │
+        │      SELECT, WITH, EXPLAIN(*), DESCRIBE                │
+        │      *EXPLAIN ANALYZE + (Insert|Update|Delete|Merge)*  │
+        │       조합은 명시적 거부 (실제 실행됨)                   │
+        │  (b) 모든 CTE 내부도 walk:                              │
+        │      find_all(exp.Insert, exp.Update, exp.Delete,     │
+        │               exp.Merge) → 발견 시 차단                 │
+        │  (c) `COPY` 전면 차단 (FROM/TO PROGRAM/file 전부)       │
+        │  (d) parse error → fail-closed (block)                │
+        │  (e) multi-statement (";" 분할) → 첫 번째만 허용,       │
+        │       나머지가 있으면 거부                              │
+        │  (f) ★ Function denylist (catalog-driven, OID 매칭):    │
+        │       부팅 시 pg_proc에서 위험 함수 OID 수집,           │
+        │       AST의 모든 function call을 OID 매칭으로 차단     │
+        │       → schema-qualified bypass 방어                   │
+        │       (이름 매칭만 하면 public.pg_sleep 같은 alias에   │
+        │        취약)                                            │
+        │  • 위반 시: audit.kind='safety_block' + ❌ embed       │
+        └──────────────────────────────────────────────────────┘
+                              │
+                              ▼
+        ┌──────────────────────────────────────────────────────┐
+        │ L2 Cost Gate — *경고+confirm* 모드 (차단 아님)         │
+        │                                                        │
+        │  • EXPLAIN (FORMAT JSON) → JSON plan tree 재귀 walk    │
+        │  • 임계 (V1 디폴트):                                     │
+        │      Total Cost > 1,000,000                            │
+        │    OR Plan Rows × Plan Width > 100 MB (bytes)          │
+        │    OR Sort/Hash 노드 + 입력 > 1M rows                   │
+        │  • 임계 초과 시:                                         │
+        │      show_plan(plan=..., cost=..., est_rows=...,       │
+        │                est_bytes=...) → Discord button view   │
+        │      사용자 ✅ 누르면 진행, ❌ 누르면 취소               │
+        │  • EXPLAIN 추정은 stale stats 시 빗나감 → 차단 아님      │
+        │  • 실제 차단은 L3 runtime cap에 위임                    │
+        └──────────────────────────────────────────────────────┘
+                              │
+                              ▼
+        ┌──────────────────────────────────────────────────────┐
+        │ L3 Runtime Caps — GUC 기반                            │
+        │  • statement_timeout = 30s     (L0에서 SET)            │
+        │  • lock_timeout = 5s                                   │
+        │  • idle_in_transaction_session_timeout = 60s           │
+        │  • temp_file_limit = '1GB'                             │
+        │  • app-level row_limit = 1000 (truncate + 알림)        │
+        │  • 위반 시: ⚠️ "timeout/limit 적중, partial result"    │
+        └──────────────────────────────────────────────────────┘
+                              │
+                              ▼
+        ┌──────────────────────────────────────────────────────┐
+        │ L4 Audit (append-only SQLite)                         │
+        │  • events 외에 audit 테이블 별도 (§3.3)                 │
+        │  • 일 회전 + retention 90일                             │
+        │  • /audit me  → 본인 최근 50건                          │
+        │  • /audit export → CSV DM                              │
+        │  • hash chain / 외부 sink → V2 백로그                   │
+        └──────────────────────────────────────────────────────┘
+                              │
+                              ▼
+        ┌──────────────────────────────────────────────────────┐
+        │ L5 Rate Limit (token bucket)                          │
+        │  • per-user:  LLM 20/min, DB 60/min                   │
+        │  • per-guild: V2 (V1은 DM-only)                        │
+        │  • Discord API rate limit도 별도 어댑터 책임           │
+        └──────────────────────────────────────────────────────┘
+                              │
+                              ▼
+                          실행 / 응답
+```
+
+### 5.1 함수 denylist (V1, catalog 부팅 시 OID 수집)
+
+| 카테고리 | 항목 | 사유 |
+|---|---|---|
+| **DoS / sleep** | `pg_sleep`, `pg_sleep_for`, `pg_sleep_until` | RO 통과, lock hold |
+| **Advisory lock** | `pg_advisory_lock(_shared)?`, `pg_advisory_xact_lock(_shared)?`, `pg_try_advisory_*` | 자원 hog |
+| **Backend control** | `pg_terminate_backend`, `pg_cancel_backend` | operational |
+| **Logging / signal** | `pg_log_backend_memory_contexts`, `pg_reload_conf`, `pg_rotate_logfile` | 운영 부수효과 |
+| **WAL / replication** | `pg_create_*_replication_slot`, `pg_drop_replication_slot`, `pg_logical_emit_message`, `pg_switch_wal`, `pg_backup_start/stop`, `pg_create_restore_point`, `pg_promote`, `pg_wal_replay_pause/resume` | 상태 변경 |
+| **Server file / LO** | `pg_read_file`, `pg_read_binary_file`, `pg_ls_*`, `lo_import`, `lo_export`, `lo_create`, `lo_unlink`, `lo_truncate`, `lo_open`, `lo_from_bytea`, `lo_put`, `lowrite` | FS / large object bypass |
+| **Egress / FDW** | `dblink_exec`, `dblink`, `dblink_connect`, `postgres_fdw_disconnect*` | 외부 egress |
+| **Stats / maintenance** | `pg_restore_relation_stats`, `pg_clear_*_stats`, `brin_summarize_*`, `gin_clean_pending_list` | optimizer 조작 |
+| **Configuration** | `set_config('...', ..., false)` (session-wide), `pg_reload_conf` | session 설정 우회 |
+| **Misc** | `pg_export_snapshot`, `pg_log_standby_snapshot` | 자원 보유 |
+
+Extension 함수 (`PostGIS`, `pgcrypto`, `http`, `plpython`, `plperlu`) 는 환경별 inventory 후 추가.
+
+### 5.2 self-test 7개 공격 (회귀 — CI 차단 기준)
+
+| # | 입력 | 기대 결과 |
+|---|---|---|
+| 1 | `DROP TABLE users` | L1 block (DDL) |
+| 2 | `; DELETE FROM users; --` (multi-stmt) | L1 block (multi-statement) |
+| 3 | `WITH x AS (INSERT INTO t VALUES (1) RETURNING *) SELECT * FROM x` | L1 block (DML in CTE, sqlglot walk) |
+| 4 | `SELECT pg_sleep(10000)` | L1 block (function denylist, OID match) |
+| 5 | `EXPLAIN (FORMAT JSON) SELECT * FROM huge_table` → estimated >100M rows | L2 cost gate → user confirm |
+| 6 | `SELECT * FROM table_50k` (50,000 rows) | L3 row_limit 1000 → truncate |
+| 7 | 분당 100 호출 | L5 rate limit |
+
+추가 (V2 backlog):
+- `SELECT public.pg_sleep(60)` (schema-qualified bypass) → catalog-driven OID match으로 V1에서도 차단 가능. 회귀 추가 권장.
+- `COPY foo TO PROGRAM 'curl ...'` → L1 block (COPY 전면 차단)
+- writable role probe: `/connect` 로 writable account 등록 시도 → RO probe 거부.
+
+### 5.3 어필 — 5가지 무기 (v1과 동일, GIF 콘텐츠 업데이트)
+
+1. `/safety` 슬래시 명령 — 현재 보호 레이어 embed.
+2. 레드팀 GIF 30초 — 7개 공격 시도가 각각 다른 레이어에 막히는 영상.
+3. 공개 audit log JSON 샘플 — "이렇게 기록됩니다".
+4. `/safety self-test` — 본인이 본인에게 7개 공격 → "녹색 7/7" 스크린샷.
+5. 벤치마크 — `lang2sql` vs *"그냥 LLM에 connection 던지기"* 정량 비교.
+
+---
+
+## 6. 새 레포 레이아웃 — Evolve in place
+
+v1의 "wipe and rebuild" 어조는 폐기. 실제 작업은 **PR-0(정리) + 5개 PR(점진 추가)** 로 진행. (codebase-reality 결론.)
+
+### 6.1 보존 / 포팅 / 삭제
+
+| 분류 | 대상 | LOC | 메모 |
+|---|---|---|---|
+| **KEEP-AS-IS** | `src/lang2sql/semantic/*` | ~670 | 순수 in-memory. `dialect="postgres"` 기본값만 변경 (`sql_composer.py:19`). |
+| | `src/lang2sql/harness/types.py` | ~155 | `core/types.py` 로 이동(rename)만. |
+| | `src/lang2sql/skills/registry.py` | ~101 | 그대로. |
+| | `src/lang2sql/tools/{ask_user,show_plan}.py` | ~93 | harness intercept라 본문 더미. |
+| | `tests/test_semantic_layer.py`, `test_harness_core.py`, `test_skills_registry.py` | ~1,054 | 회귀 안전망. |
+| | `src/lang2sql/integrations/llm/openai_.py`, `anthropic_.py` | ~362 | 그대로. NIM은 wrapper. |
+| | `tui-go/*` | — | freeze. |
+| **PORT-WITH-MINOR-CHANGES** | `src/lang2sql/harness/{tool,loop,system_prompt}.py` | ~575 | ctx 인자 추가. 본체 70% 그대로. |
+| | `src/lang2sql/tools/{run_sql,explore_schema,profile_table,define_*,search_semantic,write_sql,visualize,load_skill}.py` | ~1,200 | ctx 사용 + run_sql만 safety 호출 추가. |
+| | `src/lang2sql/integrations/db/sqlalchemy_explorer.py` | ~128 | async 전환 (asyncpg) + GUC SET. |
+| | `src/lang2sql/core/ports.py` | ~101 | port 5개 추가 (secrets/session_store/audit/hook/persistent_view_store). |
+| | `cli/commands/serve.py` | ~393 | `frontends_dev/serve.py` 로 이동. NDJSON 그대로 (Go TUI 호환). |
+| | `cli/commands/agent.py` | ~111 | `frontends_dev/cli.py` 로 이동. |
+| **REWRITE** | `src/lang2sql/harness/session.py` | ~215 → ~250 | 6-event write-through로 교체. |
+| | `src/lang2sql/harness/builder.py` | ~88 → ~100 | `ContextConcierge` 로 승격. |
+| **NEW** | `src/lang2sql/safety/*` (statement_gate, cost_gate, runtime, audit, rate_limit, ro_probe, self_test) | ~900 | |
+| | `src/lang2sql/tenancy/*` (concierge, tenant_registry, explorer_cache, session_queue, encrypted_store, persistent_view_store) | ~700 | |
+| | `src/lang2sql/discord/*` (bot, commands/*, session_router, streaming, interactive, render, permissions, recovery) | ~1,500 | |
+| | `src/lang2sql/adapters/llm/nvidia_nim.py`, `adapters/db/postgres_explorer.py`, `adapters/secrets/encrypted_sqlite.py`, ... | ~600 | |
+| | `tests/{safety,discord,tenancy}/*` | ~1,200 | |
+| **DELETE** | `src/lang2sql/tui/*` (Python Textual + widgets) | ~1,400 | Discord가 1급. |
+| | `src/lang2sql/{components,flows,viz,interface,utils}/*`, `integrations/{embedding,vectorstore,loaders,chunking,catalog}/*` | ~5,000 | V1에 RAG/구 파이프라인 없음. |
+| | `src/lang2sql/integrations/llm/{gemma_,gemini_,bedrock_,azure_,huggingface_,ollama_}.py` | ~1,000 | gemma 등 백버너로 보관 또는 삭제. |
+| | `cli/commands/{tui,init,quary,run_streamlit}.py` | ~350 | |
+| | `tests/test_{components,flows,integrations}_*`, `test_tools_code_agent.py` | ~1,500 | 동반 삭제. |
+
+### 6.2 최종 트리 (PR-5 끝난 시점)
+
+```
+lang2sql/
+├── README.md
+├── pyproject.toml
+├── .env.example
+│
+├── src/lang2sql/
+│   │
+│   ├── core/                      # 순수 타입 + 포트
+│   │   ├── types.py               # 기존 harness/types.py 이동
+│   │   ├── identity.py            # Principal, GuildRole (신규)
+│   │   ├── safety_types.py        # SafetyVerdict, Budget, RateBucket (신규)
+│   │   └── ports/
+│   │       ├── llm.py             # 기존 일부
+│   │       ├── explorer.py        # async 전환
+│   │       ├── tool.py            # ctx
+│   │       ├── secrets.py         # 신규
+│   │       ├── session_store.py   # 신규
+│   │       ├── audit.py           # 신규
+│   │       ├── persistent_view_store.py  # 신규
+│   │       └── hook.py            # 기존
+│   │
+│   ├── harness/                   # kernel
+│   │   ├── context.py             # HarnessContext (신규)
+│   │   ├── session.py             # 6-event write-through (재작성)
+│   │   ├── loop.py                # 기존 70% 보존
+│   │   ├── system_prompt.py       # 기존, per-turn 유지
+│   │   ├── tool_registry.py       # ctx 주입 (개명)
+│   │   └── prompts/
+│   │
+│   ├── semantic/                  # 그대로 (dialect 기본값 변경)
+│   │
+│   ├── safety/                    # ★ 신규
+│   │   ├── statement_gate.py
+│   │   ├── cost_gate.py
+│   │   ├── runtime.py
+│   │   ├── audit.py
+│   │   ├── rate_limit.py
+│   │   ├── ro_probe.py
+│   │   └── self_test.py
+│   │
+│   ├── tools/                     # ctx-aware
+│   │   ├── explore_schema.py
+│   │   ├── run_sql.py             # safety 호출 추가
+│   │   ├── write_sql.py           # (compose만, 이름 유지 — devils-advocate 검증)
+│   │   ├── define_metric.py
+│   │   ├── define_dimension.py
+│   │   ├── define_relationship.py
+│   │   ├── search_semantic.py
+│   │   ├── profile_table.py
+│   │   ├── ask_user.py
+│   │   ├── show_plan.py
+│   │   ├── visualize.py
+│   │   ├── explain_query.py       # 보존, V1 메뉴에 노출
+│   │   └── load_skill.py
+│   │
+│   ├── skills/                    # 기존
+│   │
+│   ├── tenancy/                   # ★ 신규
+│   │   ├── concierge.py
+│   │   ├── tenant_registry.py
+│   │   ├── explorer_cache.py
+│   │   ├── session_queue.py
+│   │   ├── encrypted_store.py
+│   │   └── persistent_view_store.py
+│   │
+│   ├── discord/                   # ★ 1급 frontend (신규)
+│   │   ├── bot.py
+│   │   ├── commands/
+│   │   │   ├── connect.py
+│   │   │   ├── grant_readonly.py
+│   │   │   ├── connections.py
+│   │   │   ├── safety.py
+│   │   │   ├── audit.py
+│   │   │   ├── model.py
+│   │   │   ├── reset.py
+│   │   │   ├── retry.py
+│   │   │   └── help.py
+│   │   ├── session_router.py      # V1: DM-only
+│   │   ├── streaming.py           # throttled message edit
+│   │   ├── interactive.py         # persistent View
+│   │   ├── render.py              # PNG 페이지네이션
+│   │   ├── permissions.py
+│   │   └── recovery.py            # 부팅 시 persistent_views reattach
+│   │
+│   ├── adapters/                  # outbound
+│   │   ├── llm/
+│   │   │   ├── openai_.py         # 기존
+│   │   │   └── nvidia_nim.py      # 신규
+│   │   ├── db/
+│   │   │   └── postgres_explorer.py  # 기존 sqlalchemy_explorer 진화
+│   │   ├── secrets/
+│   │   │   └── encrypted_sqlite.py
+│   │   ├── session_store/
+│   │   │   └── encrypted_sqlite.py
+│   │   └── audit_sink/
+│   │       └── sqlite.py
+│   │
+│   └── frontends_dev/             # 부수
+│       ├── cli.py                 # 기존 agent.py 이동
+│       └── serve.py               # 기존 serve.py 이동 (Go TUI 호환)
+│
+├── tui-go/                        # freeze
+├── tests/
+│   ├── (보존) test_semantic_layer.py, test_harness_core.py, test_skills_registry.py
+│   ├── safety/                    # 7개 self-test + 회귀
+│   ├── discord/                   # mock 기반
+│   └── tenancy/
+└── docs/
+    ├── discord_first_redesign.md       # v1 보존
+    ├── discord_first_redesign_v2.md    # ← 본 문서
+    ├── DB_ROBUSTNESS.md                # ★ trust page
+    ├── DISCORD_ONBOARDING.md           # 사용자 가이드
+    └── DEPLOY.md
+```
+
+---
+
+## 7. 마이그레이션 — PR-0 + 5주 plan
+
+```
+PR-0 ─ 정리 (0.5주)                                       [-7,700 LOC]
+   • src/lang2sql/tui/*, components/, flows/, viz/,
+     interface/, utils/, 미사용 integrations/, 옛 cli/
+     명령들, 동반 tests/ 삭제
+   • python -c "import lang2sql" + pytest 통과 확인
+   • 잔존: semantic/, harness/, skills/, openai+anthropic 어댑터,
+           기존 sqlalchemy_explorer, tui-go/, 보존 tests 3종
+
+PR-1 ─ Kernel (Week 1)                                    [~400 LOC]
+   • core/ports/* 정의 (5개 신규 포트 시그니처)
+   • HarnessContext, ctx-aware Tool 시그니처
+   • harness/{tool_registry,loop,system_prompt} 시그니처 갈이
+   • Session 임시 in-memory (PR-3에서 영속화)
+   • ToolResult canonical shape 합의
+   • frontends_dev/cli.py 로 검증
+
+PR-2 ─ Safety (Week 2, 모두 *경고 모드* 포함)              [~900 LOC]
+   • statement_gate (sqlglot AST + function denylist OID)
+   • runtime (5개 GUC SET, temp_file_limit '1GB' 단위)
+   • cost_gate (EXPLAIN multi-metric, 경고+confirm 모드)
+   • audit (sqlite sink)
+   • ro_probe (catalog 쿼리)
+   • self_test 7개 + tests/safety/ (CI gate)
+   • run_sql 도구가 safety 통과시키도록 ~20 LOC 추가
+
+PR-3 ─ Async + Tenancy + Persistence (Week 3)             [~1,400 LOC]
+   • DBExplorerPort async 전환 + asyncpg 어댑터
+   • 모든 도구 async 호환 (대부분 자동, 일부 to_thread)
+   • encrypted_sqlite (AES-GCM secrets)
+   • SessionStore 6-event write-through + iter_active
+   • PersistentViewStore (신규)
+   • tenant_registry + explorer_cache(async LRU)
+   • session_queue (per-session FIFO)
+   • ContextConcierge
+
+PR-4a ─ Discord onboarding (Week 4 전반)                  [~700 LOC]
+   • bot 진입 + setup_hook (persistent View 재등록)
+   • /connect Modal (5필드 connection string) + 제출 처리
+   • /grant-readonly, /test, /connections, /use, /disconnect
+   • Principal/Policy 기본
+   • DM-only session_router
+   • recovery.py (events 마지막=tool_started → run_interrupted,
+                  persistent_views reattach)
+
+PR-4b ─ Discord product (Week 4 후반)                     [~800 LOC]
+   • streaming (토큰 → throttled message.edit 1s)
+   • interactive (ask_user/show_plan → persistent View buttons)
+   • render (PNG 페이지네이션, Discord 한도 인지)
+   • /safety, /audit, /model, /reset, /retry, /help
+   • cost_gate를 *차단 모드*로 승격 옵션 추가
+
+PR-5 ─ Polish + Appeal (Week 5)                           [~300 LOC]
+   • /safety self-test 자동 데모 GIF
+   • README 갱신
+   • DB_ROBUSTNESS.md (trust page)
+   • DEPLOY.md (Oracle Cloud / fly.io)
+   • benchmark (vs "naive LLM SQL")
+   • NIM contract test 통과 후 /model에 노출
+```
+
+총 ~4,500 LOC 신규 + ~600 LOC 수정, ~7,700 LOC 삭제. 5.5주 1인 풀타임. Week 4 분할로 v1의 과적재 해소.
+
+각 PR은 별 브랜치 (`feature/pr-{N}-*`), 직전 PR 머지 후 다음 시작.
+
+---
+
+## 8. 차트 페이지네이션 (Discord 한도 인지)
+
+```
+Result rows → discord/render.py
+                │
+                ├─ 50 rows 이하  → embed 텍스트 1개 (4096자 한도 체크)
+                ├─ 500 rows 이하 → matplotlib + Pillow → PNG 1장
+                ├─ > 500 rows    → 50 rows/페이지 PNG K장
+                │
+                ├─ K ≤ 5         → 단일 메시지에 첨부 K장 (8MB 한도 체크)
+                ├─ K > 5         → persistent View (◀ Prev / Next ▶ / ⇩ CSV)
+                │                   첫 페이지만 즉시 전송
+                │                   메시지 ID + 페이지 상태 →
+                │                     persistent_views 테이블 저장
+                │                   봇 재시작 후에도 버튼 작동
+                │
+                └─ CSV 버튼      → 전체 CSV를 DM 첨부 (8MB 초과 시 분할)
+```
+
+차트(visualize) 도 동일 패턴 — facet 차트는 카테고리당 1장.
+
+**한도 표** (v1엔 빠졌던 항목):
+- content 2000자 / embed description 4096자 / embed 총 6000자
+- 단일 메시지 첨부 8MB (무료 길드), 25MB (Nitro)
+- 메시지당 임베드 최대 10개, 컴포넌트 최대 5 ActionRow
+
+---
+
+## 9. LLM 멀티 백엔드 — OpenAI (V1) + NVIDIA NIM (contract-tested)
+
+```
+adapters/llm/openai_.py        — 그대로
+adapters/llm/nvidia_nim.py     — OpenAI(base_url=NIM_ENDPOINT, api_key=NIM_KEY)
+                                  ~30 LOC wrapper
+```
+
+**V1 디폴트**: OpenAI `gpt-4.1-mini`. `/model` 슬래시 명령으로 전환 가능.
+
+**NIM contract test (PR-2 또는 PR-5)**:
+```
+tests/llm_contract/test_nim_openai_parity.py
+  • tool_calling: 동일 schema → 동일 호출 시그니처
+  • streaming: text_delta chunk shape 호환
+  • finish_reason: 'stop'|'tool_calls'|'length' 매핑
+  • JSON mode: schema adherence
+  통과 시 /model 노출, 실패 시 마스크
+```
+
+선택 가능한 모델 (V1 후보):
+
+| Provider | 후보 |
+|---|---|
+| OpenAI | `gpt-4.1-mini` (디폴트), `gpt-4.1`, `o4-mini` |
+| NVIDIA NIM (contract-test 통과 후) | `meta/llama-3.1-70b-instruct`, `mistralai/mixtral-8x22b-instruct-v0.1` |
+
+비용 안내:
+- OpenAI: per-token. `/model` 에서 mini 디폴트.
+- NIM: NVIDIA 무료 크레딧 → 떨어지면 자비. `/model` 로 OpenAI 폴백 안내.
+- per-user 토큰 캡은 V2 백로그 (`/audit` 에 누적 비용 표시는 V1.5).
+
+**Provider family 전환** (OpenAI ↔ Anthropic): conversation 직렬화가 호환되지 않음. 사용자에게 *"대화 초기화 필요"* confirm 후 진행.
+
+---
+
+## 10. V1 명시적 제외 — V2+ 백로그
+
+| 항목 | 사유 |
+|---|---|
+| 길드 채널·스레드 세션 | 데이터 노출 위험. allowlist + admin 승인 모델이 V2. |
+| audit log hash chain / 외부 sink | V1 SOC2 친화 어조만 유지. 실제 hash chain은 V2. |
+| 외부 secret manager (AWS SM / GCP SM / Vault) | V1은 로컬 암호 SQLite로 충분. |
+| MySQL / SQLite / BigQuery 어댑터 | V1은 PostgreSQL 전용. |
+| RAG / 벡터스토어 / 임베딩 | 본 제품은 schema-grounded NL→SQL. RAG는 V2 옵션. |
+| Anthropic 어댑터 사용자 노출 | V1 디폴트는 OpenAI. 어댑터 코드는 보존만. |
+| 다중 인스턴스 / Redis 세션 스토어 | 트라이얼은 단일 프로세스. V2 스케일링 시. |
+| BQ cost gate (bytes_processed × $) | PG cost_gate가 먼저, BQ 어댑터 들어올 때 함께. |
+| Components V2 (Discord 2025) | 모달은 변경 없음. message 컴포넌트 V2 migration은 V1 이후. |
+
+---
+
+## 11. Codex 리뷰에서 거부한 항목 (transparency)
+
+본 v2는 Codex가 제기한 25개 지적 중 ~12개를 수용. 다음 항목은 **검증 후 거부**:
+
+| Codex 지적 | 거부 사유 |
+|---|---|
+| **§1#4 vs §1.3 "AES-GCM 모순"** | doc은 per-row 컬럼 암호 (secrets만), Codex는 SQLCipher 형 파일 단위 암호로 오독. v2 §1.3에서 추가 명확화. |
+| **`write_sql.py` → `draft_sql.py` 개명** | `write_sql.py` 본문은 SQLComposer로 *생성*만 함. 실행은 `run_sql.py`. Codex는 파일을 안 읽고 이름으로 추론. 이름 유지. |
+| **§0 5단 타이브레이커** (권한→정확성→무결성→UX→맥락) | 솔로 트라이얼에 과한 product framing. 4축 (DB 무결성·의미적 정확성·Discord UX·맥락)으로 절충. |
+| **Hermes-style write-through 통째 부정** | 사용자 명시 요구사항. 단, *"스트림 청크 복구"* 부분만 거부 — 6 event types로 단순화. |
+| **EXPLAIN cost gate가 row estimate만으론 부족 → 차단** | trial V1에 stale stats까지 잡으라는 건 과함. *차단이 아니라 경고+사용자 confirm* 으로 절충, 실제 차단은 L3 runtime cap에 위임. |
+| **NIM "OpenAI 호환" 검증 안 됨 → 사용 금지** | contract test 통과 후 experimental 노출로 절충. 전면 금지는 아님. |
+| **SQLite single-writer "1000 유저" 비현실적** | trial 트래픽은 두 자릿수. V2 스케일 시점 항목으로 명시. |
+| **wipe vs "semantic 이식" 모순** | "이식"은 트리 비우고 자산 복사라는 자연 해석. 그러나 v2에선 *evolve in place* 로 어조 자체를 변경 → 모순 자체 소멸. |
+
+---
+
+## 12. 잔여 결정 사항
+
+(Week 1 착수 전 답이 있으면 좋은 항목)
+
+1. **첫 배포 길드** — V1은 DM-only라 길드 선택은 봇 초대받을 수 있는 길드만 필요. 가짜연구소 디스코드 또는 본인 테스트 길드?
+2. **세션 retention** — 비활성 세션 보존 기간. v2 §3.2 가정: **30일 active, 30~90일 archive, 90일 후 삭제**. 변경 필요 시 알려주세요.
+3. **audit retention** — 90일 동일. compliance 관점에서 더 길게? 별도 보존?
+4. **NIM 디폴트 후보** — `llama-3.1-70b-instruct` vs `mixtral-8x22b-instruct-v0.1`. (Mixtral이 tool-calling 안정성 우위로 알려져 있음 — contract test로 결정.)
+5. **Cost gate 차단 모드 승격 시점** — V1은 경고만. PR-5에서 차단 옵션 추가? V2로?
+6. **`/audit export` 형식** — CSV만? JSON 옵션도?
+7. **`/reset` 시 audit 보존** — 기본 보존 권장. 사용자에게 명시.
+
+위 7개는 Week 1 코드에 직접 영향 없음.
+
+---
+
+## 13. 한 줄 요약
+
+> **Evolve in place. 4축 타이브레이커로 의미적 정확성을 1급화한다. Discord plataforma 한도(Modal 5필드, password style 없음, Interaction 15분, autocomplete 3s, persistent view)를 §1.4에 박는다. PostgreSQL safety는 `SET TRANSACTION READ ONLY` 단독을 신뢰하지 않고, dedicated readonly role + 5 GUC + catalog-driven function denylist(OID) 3중으로 막는다. 세션은 6 event types만 write-through, 스트림 청크 복구는 폐기. V1은 DM-only — 채널/스레드는 권한 모델 완성 후 V2.**
+
+— end —
diff --git a/docs/discord_first_redesign_v3_minimal.md b/docs/discord_first_redesign_v3_minimal.md
new file mode 100644
index 0000000..c2b2859
--- /dev/null
+++ b/docs/discord_first_redesign_v3_minimal.md
@@ -0,0 +1,578 @@
+# Lang2SQL — Discord-First 재설계 (v3, Walking Skeleton)
+
+> **작성일**: 2026-05-18
+> **결정자**: ryan@brain-crew.com
+> **상태**: v2 → v3. 5명 리뷰어(Codex + Agent Teams 4명) 라운드 2 audit 결과 반영.
+> **핵심 변경**: v2의 *"5.5주에 다 넣자"* → v3의 *"3주에 가장 작은 작동하는 제품 + 확장점"*.
+> **선행 문서**: `discord_first_redesign.md` (v1), `discord_first_redesign_v2.md` (v2, 확장 청사진으로 보존).
+
+---
+
+## 0. 한 줄과 타이브레이커
+
+> **"Discord DM에서 자연어로 PostgreSQL에 묻고, 안전하게 답을 받는다. DB는 변하지 않고, 결과는 audit에 남는다."**
+
+설계 충돌 시 우선순위:
+
+1. **데이터·DB 무결성 + 권한** — DB가 변하지 않는가, 사용자가 권한 있는 데이터만 보는가
+2. **의미적 정확성** — 답이 의미적으로 맞는가 (V1엔 audit + golden query set, validation loop는 V1.5+)
+3. **Discord UX 단순성** — 한 번의 입력으로 결과를 얻는가
+4. **맥락 보존** — 끊겨도 이어지는가 (V1은 *in-memory*, 영속화는 V1.6)
+
+(Codex가 v2 4축에 *"권한/data exposure를 최상위 축으로 올리지 않았다"* 고 STILL-INVALID 판정 → 축 #1을 *"무결성 + 권한"* 통합으로 명확화. devils-advocate의 "5축은 product framing overkill" 우려는 4축 유지로 절충.)
+
+---
+
+## 1. v3-minimal 범위
+
+### 1.1 V1에 *들어가는* 것
+
+| 영역 | V1 |
+|---|---|
+| 인터페이스 | Discord DM only. 슬래시 명령 3개: `/connect`, `/ask <질문>`, `/disconnect` |
+| LLM | OpenAI `gpt-4.1-mini` 단일 |
+| DB | PostgreSQL only (dedicated readonly role 강제) |
+| 응답 형식 | 텍스트 (≤50행) 또는 CSV 첨부 (>50행) — PNG·차트·페이지 버튼 V1 미포함 |
+| Safety | L0 (GUC pack) + L1 (statement gate) + L4 (audit) **3개만** |
+| 세션 | in-memory dict — 봇 재시작 시 손실. 사용자가 다시 `/ask` 호출 |
+| 영속화 | audit + secrets만 SQLite. conversation은 휘발 |
+| 도구 | `run_sql`, `explore_schema`, `ask_user` **3개만** |
+| 호스팅 | 본인 PC 또는 fly.io free / Oracle Cloud Always Free |
+
+### 1.2 V1에 *안* 들어가는 것 (V1.x로 미룸)
+
+| 항목 | 미루는 곳 | 이유 |
+|---|---|---|
+| `run_code` / `write_code` 도구 | **삭제** (V2도 보류) | Codex 최우선 지적: read-only 제품에서 Python subprocess는 모든 safety layer를 무력화 (token·secret·FS·network 노출). 부활 시 sandbox 필수. |
+| Cost gate (EXPLAIN-based) | V1.5 | L1 + L0 timeout으로 1차 충분. confirm UX는 persistent View 의존이라 V1.7에 자연스럽게 들어옴. |
+| Rate limit | V1.5 | 트라이얼은 1~2명. |
+| Self-test 7개 자동화 | V1.5 | V1엔 수동 회귀. CI YAML은 V1.5와 동반. |
+| Persistent View / streaming / PNG paginate | V1.7 | Discord SDK 깊은 영역. V1엔 ephemeral 한 번 응답으로 충분. |
+| Hermes write-through (영속 conversation) | V1.6 | in-memory로 시작. 사용자가 끊김 불편을 호소하면 SessionStore 어댑터 교체. |
+| `define_metric/dimension/relationship` 등 semantic CRUD 도구 | V1.5 | `write_sql` 컴포저는 비어 있는 layer로도 작동. semantic 구축은 trial 사용자가 명시 요청할 때. |
+| NVIDIA NIM | V1.5 (contract test 통과 후) | OpenAI 하나로 시작. |
+| Anthropic 노출 (`/model` 명령) | V2 | 코드는 보존, V1엔 미노출. |
+| 길드 채널 / 스레드 세션 | V2 | Codex가 "DM-only도 DM 덤프 위험"으로 추가 지적 — V2에 schema/table allowlist + per-user audit 완성 후. |
+| `/grant-readonly` 도우미 명령 | V1.5 | V1은 README의 SQL 가이드로 충분. |
+| Audit hash chain / 외부 sink | V2 | V1엔 append-only SQLite + `/audit me`. |
+| `visualize` 도구 | V1.7 | PNG render 함께. |
+| `load_skill` | V1.5 | skills/ 디렉토리는 보존, 도구만 미노출. |
+| Python Textual TUI | **삭제** | |
+| Go TUI | freeze (유지하되 V1에서 신규 작업 0) | |
+| RAG / 벡터스토어 / embedding | V2+ | V1은 schema-grounded NL→SQL. |
+
+### 1.3 기술 결정 (최소)
+
+| 항목 | 선택 |
+|---|---|
+| Discord lib | `discord.py` 2.x |
+| DB 드라이버 | `asyncpg` + `sqlalchemy.ext.asyncio.create_async_engine` (**AUTOCOMMIT isolation**) |
+| LLM | OpenAI `gpt-4.1-mini` |
+| Secret 저장 | AES-GCM per-row in SQLite (`secrets` 테이블만 암호화) |
+| 호스팅 | Oracle Cloud Always Free 또는 fly.io free (Cloudflare Workers 불가 — discord.py는 장기 실행) |
+
+---
+
+## 2. 상위 아키텍처 (V1)
+
+```
+                    ┌──────────────────────────┐
+                    │   DISCORD GATEWAY (DM)   │
+                    └──────────────┬───────────┘
+                                   │ asyncio
+                                   ▼
+┌──────────────────────────────────────────────────────────────┐
+│            DISCORD ADAPTER (단순)                              │
+│   /connect Modal · /ask handler · /disconnect                  │
+│   ephemeral response · CSV attach (>50 rows)                   │
+└──────────────┬───────────────────────────────────────────────┘
+               │ ctx = await Concierge.build(dm:user_id, principal)
+               ▼
+┌──────────────────────────────────────────────────────────────┐
+│            TENANCY (최소)                                      │
+│   ContextConcierge · EncryptedSecrets (AES-GCM SQLite)         │
+└──────────────┬───────────────────────────────────────────────┘
+               ▼ ctx
+┌──────────────────────────────────────────────────────────────┐
+│            HARNESS KERNEL                                      │
+│   agent_loop · Session(in-memory) · ToolRegistry(ctx)          │
+│   system_prompt(per-turn)                                      │
+└──────┬───────────────────────┬───────────────────────────────┘
+       │                       │
+       ▼                       ▼
+┌──────────────────────────────────────────────────────────────┐
+│            SAFETY (3 레이어)                                   │
+│   L0 connect (readonly role + GUC pack)                        │
+│   L1 statement gate (sqlglot AST + hardcoded fn denylist)      │
+│   L4 audit (SQLite append-only)                                │
+└──────┬───────────────────────┬───────────────────────────────┘
+       ▼                       ▼
+┌──────────────────────────────────────────────────────────────┐
+│            ADAPTERS                                            │
+│   LLM: openai_                                                 │
+│   DB:  postgres_explorer (asyncpg)                             │
+│   Secrets/Audit: encrypted_sqlite                              │
+└──────────────────────────────────────────────────────────────┘
+```
+
+규칙:
+- 포트는 5개만 정의 (`LLMPort`, `ExplorerPort`, `ToolPort`, `SecretsPort`, `AuditPort`). 나머지(`SessionStorePort`, `PersistentViewStorePort`, `HookPort`)는 V1.x에 추가.
+- 모든 어댑터는 async. event loop 블로킹 금지.
+- safety는 `run_sql` 한 곳에서만 통과. 다른 도구는 SQL을 실행 안 함.
+
+---
+
+## 3. DB 연결 — `/connect` (Modal 2필드)
+
+```
+사용자                       Bot DM                        Tenancy
+  │                            │                               │
+  │── /connect ───────────────▶│                               │
+  │                            │   Modal 출력:                  │
+  │                            │   ┌────────────────────────┐ │
+  │                            │   │ label    (Short)        │ │
+  │                            │   │ url      (Short)        │ │
+  │                            │   │  postgresql://USER:PASS │ │
+  │                            │   │   @HOST:5432/DB         │ │
+  │                            │   │   ?sslmode=require       │ │
+  │                            │   └────────────────────────┘ │
+  │── submit ─────────────────▶│                               │
+  │                            │                               │
+  │                            │   defer (ephemeral)            │
+  │                            │   ─ RO probe (catalog) ──────▶│
+  │                            │   ← OK/FAIL                   │
+  │                            │   if OK:                       │
+  │                            │     encrypt → secrets.put      │
+  │                            │   if FAIL:                     │
+  │                            │     embed: "read-only role 필요│
+  │                            │              README의 SQL 참조"│
+  │                            │                               │
+  │                            │   button view 동의:            │
+  │                            │   ┌────────────────────────┐ │
+  │                            │   │ READ-ONLY 정책 동의     │ │
+  │                            │   │  [✅ Agree] [❌ Cancel]│ │
+  │                            │   └────────────────────────┘ │
+  │── ✅ Agree ───────────────▶│                               │
+  │                            │   secrets 활성화 + ephemeral  │
+  │                            │   "✅ Connected to 'prod-pg'" │
+```
+
+**핵심 결정** (v2 → v3):
+- v2의 7필드 Modal → **2필드** (label + url). `acknowledgment="READ-ONLY"` 평문 입력 강제 폐기 → **별도 button view**로 동의 분리 (discord-fact-checker 권고).
+- `connection_url`은 **Short** 필드 (Paragraph는 줄바꿈 사고 유발). PG connection string은 ~200자라 Short 4000자 한도 안에 충분.
+- Modal 제출 후 **3초 안에 `interaction.response.defer(ephemeral=True)`** 필수 (Discord 한도). RO probe + secrets put은 defer 후 followup.
+- **RO probe가 먼저, secrets put은 후** (probe 실패 시 orphan 자격증명 방지).
+- writable 계정 등록은 **거부** (Codex/pg-safety-expert 합의 fail-closed). README에 readonly role 생성 SQL 가이드.
+
+### 3.1 RO probe (개선된 catalog 쿼리)
+
+```sql
+SELECT
+  current_setting('transaction_read_only')::bool                  AS tx_ro,
+  -- pg_write_all_data role 직접/간접 멤버십
+  pg_has_role(current_user, 'pg_write_all_data', 'USAGE')         AS has_write_role,
+  -- non-system table 쓰기 권한 (PUBLIC + role-chain + inherited 모두 포함)
+  EXISTS (
+    SELECT 1 FROM information_schema.tables t
+    WHERE t.table_schema NOT IN ('pg_catalog','information_schema')
+      AND (
+           has_table_privilege(current_user, t.table_schema||'.'||t.table_name, 'INSERT')
+        OR has_table_privilege(current_user, t.table_schema||'.'||t.table_name, 'UPDATE')
+        OR has_table_privilege(current_user, t.table_schema||'.'||t.table_name, 'DELETE')
+        OR has_table_privilege(current_user, t.table_schema||'.'||t.table_name, 'TRUNCATE')
+      )
+    LIMIT 1
+  )                                                                AS has_write_grant,
+  -- schema CREATE 권한
+  EXISTS (
+    SELECT 1 FROM information_schema.schemata s
+    WHERE s.schema_name NOT IN ('pg_catalog','information_schema')
+      AND has_schema_privilege(current_user, s.schema_name, 'CREATE')
+    LIMIT 1
+  )                                                                AS has_create;
+```
+
+**합격 조건**: `tx_ro = true AND has_write_role = false AND has_write_grant = false AND has_create = false`. 셋 중 하나라도 진실이면 거부.
+
+(pg-safety-expert + Codex가 v2의 `role_table_grants WHERE grantee=current_user` 가 PUBLIC·role-chain·inherited grant를 못 잡는다고 지적 → `has_table_privilege()` 기반으로 재작성.)
+
+---
+
+## 4. Safety Layer (3개)
+
+### 4.1 L0 Connection — readonly role + GUC pack
+
+```sql
+-- 매 connection 시작 (postgres_explorer.on_connect)
+SET ROLE lang2sql_readonly;             -- ← 반드시 dedicated role
+SET default_transaction_read_only = on;
+SET transaction_read_only = on;
+SET statement_timeout = '30s';
+SET lock_timeout = '5s';
+SET idle_in_transaction_session_timeout = '60s';
+SET temp_file_limit = '1GB';           -- 단위 명시 필수 (없으면 kB 해석)
+SET work_mem = '64MB';                  -- sort/hash spill을 temp_file_limit로 가두기
+SET jit = off;                          -- JIT 컴파일 비용 폭주 방지
+SET bytea_output = 'hex';
+SET client_min_messages = 'warning';
+SET application_name = 'lang2sql/v1';
+SET search_path = pg_catalog, public;
+SET row_security = on;
+```
+
+**Engine**: `create_async_engine(..., isolation_level='AUTOCOMMIT', pool_size=2, pool_recycle=1800, pool_pre_ping=True)`.
+**ExplorerCache**: LRU 30 (per db_url). 사용자당 등록 가능 DB는 V1에서 1개로 고정 (V1.5에 다중 지원).
+
+**제약**: V1 트라이얼 두 자릿수 사용자에서 PG `max_connections=100` 안에 머무름. 사용자 N × pool_size 2 = 2N connection.
+
+(`SET TRANSACTION READ ONLY`는 *"high-level, does not prevent all writes"* — dedicated role + GUC + L1이 3중 방어. pg-safety-expert 출처: https://www.postgresql.org/docs/current/sql-set-transaction.html)
+
+### 4.2 L1 Statement Gate — sqlglot AST
+
+```python
+# safety/statement_gate.py
+ALLOWED_TOP = {Select, With, Explain, Describe}
+BLOCKED_NODES = (Insert, Update, Delete, Merge, Create, Drop, Alter,
+                 Truncate, Grant, Revoke, Copy, Set)
+DENY_FUNCTIONS = {            # V1 hardcoded names (V1.5에 OID 매핑으로 승격)
+    'pg_sleep', 'pg_sleep_for', 'pg_sleep_until',
+    'pg_advisory_lock', 'pg_advisory_lock_shared',
+    'pg_advisory_xact_lock', 'pg_advisory_xact_lock_shared',
+    'pg_try_advisory_lock', 'pg_try_advisory_xact_lock',
+    'pg_terminate_backend', 'pg_cancel_backend',
+    'pg_read_file', 'pg_read_binary_file', 'pg_ls_dir',
+    'lo_import', 'lo_export', 'lo_create', 'lo_unlink',
+    'lo_truncate', 'lo_open', 'lo_from_bytea', 'lo_put', 'lowrite',
+    'dblink', 'dblink_exec', 'dblink_connect',
+    'pg_reload_conf', 'pg_rotate_logfile',
+    'pg_create_restore_point', 'pg_switch_wal',
+    'pg_logical_emit_message',
+    'pg_promote', 'pg_wal_replay_pause', 'pg_wal_replay_resume',
+    'pg_backup_start', 'pg_backup_stop',
+}
+
+def classify(sql: str) -> Verdict:
+    # 1. parse — 실패하면 fail-closed
+    try:
+        ast = sqlglot.parse(sql, dialect='postgres')
+    except ParseError:
+        return Verdict.block(reason='parse_error')
+    if len(ast) > 1:
+        return Verdict.block(reason='multi_statement')
+    root = ast[0]
+    # 2. 최상위 노드 화이트리스트
+    if type(root) not in ALLOWED_TOP:
+        return Verdict.block(reason='not_a_read_statement')
+    # 3. EXPLAIN ANALYZE + DML 거부
+    if isinstance(root, Explain) and root.args.get('analyze'):
+        if root.find(*BLOCKED_NODES[:4]):  # Insert/Update/Delete/Merge
+            return Verdict.block(reason='explain_analyze_dml')
+    # 4. 모든 서브트리에서 차단 노드 검사 (CTE 내부 INSERT 등)
+    for node in root.find_all(*BLOCKED_NODES):
+        return Verdict.block(reason=f'forbidden_{type(node).__name__.lower()}')
+    # 5. 함수 호출 검사 — schema-qualified bypass 포함
+    for func in root.find_all(exp.Func):
+        name = (func.name or '').lower()
+        # public.pg_sleep 같은 schema 접두사도 처리
+        if name in DENY_FUNCTIONS:
+            return Verdict.block(reason=f'forbidden_function_{name}')
+    return Verdict.allow()
+```
+
+V1.5 보강:
+- OID-based 매핑 (extension 동적 등록 대응).
+- TTL refresh (mid-session 새 함수 감지).
+- `DO $$ ... $$` 블록 차단 (PG 동적 SQL).
+
+### 4.3 L4 Audit — SQLite append-only
+
+```sql
+CREATE TABLE audit (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  ts          TIMESTAMP NOT NULL,
+  principal   TEXT NOT NULL,                 -- discord user_id
+  session_id  TEXT NOT NULL,                 -- 'dm:USER_ID'
+  kind        TEXT NOT NULL,                 -- 'sql' | 'safety_block' | 'connect' | 'disconnect'
+  sql         TEXT,                          -- 차단된 SQL 포함
+  row_count   INTEGER,
+  duration_ms INTEGER,
+  status      TEXT,                          -- 'ok' | 'error' | 'blocked'
+  error       TEXT                           -- 차단 사유 또는 PG error
+);
+CREATE INDEX audit_by_principal ON audit(principal, id);
+```
+
+V1 명령: `/audit me` → 최근 20건 ephemeral embed. CSV export·hash chain·외부 sink는 V2.
+
+---
+
+## 5. 영속화 스토어 (V1: secrets + audit만)
+
+```sql
+-- secrets: AES-GCM per-row
+CREATE TABLE secrets (
+  id           TEXT PRIMARY KEY,           -- f"user:{user_id}:default"
+  owner        TEXT NOT NULL,              -- discord user_id
+  label        TEXT NOT NULL,
+  ciphertext   BLOB NOT NULL,              -- AES-GCM(url, key, iv)
+  iv           BLOB NOT NULL,
+  tag          BLOB NOT NULL,
+  created_at   TIMESTAMP NOT NULL,
+  last_used_at TIMESTAMP
+);
+
+-- audit (위 §4.3)
+```
+
+**V1엔 `sessions`, `messages`, `events`, `persistent_views` 테이블 없음.** conversation은 `dict[user_id, list[Message]]` in-memory. 봇 재시작 시 conversation 손실 (사용자가 다시 `/ask`).
+
+마스터 키: `LANG2SQL_MASTER_KEY` env (32 bytes urlsafe base64). 분실 시 secrets만 무효.
+
+---
+
+## 6. 레포 레이아웃 (V1)
+
+```
+lang2sql/
+├── README.md                    # 30초 setup + readonly role SQL
+├── pyproject.toml
+├── .env.example                 # LANG2SQL_MASTER_KEY, DISCORD_TOKEN, OPENAI_API_KEY
+│
+├── src/lang2sql/
+│   ├── core/
+│   │   ├── types.py             # Message, ToolCall, ToolResult, Event
+│   │   ├── identity.py          # Principal (discord user_id)
+│   │   └── ports/
+│   │       ├── llm.py
+│   │       ├── explorer.py
+│   │       ├── tool.py
+│   │       ├── secrets.py
+│   │       └── audit.py
+│   │
+│   ├── harness/
+│   │   ├── context.py           # HarnessContext
+│   │   ├── session.py           # in-memory dict
+│   │   ├── loop.py              # agent_loop (기존 70% 보존)
+│   │   ├── system_prompt.py     # per-turn
+│   │   └── tool_registry.py
+│   │
+│   ├── semantic/                # ★ 기존 코드 그대로 (dialect="postgres")
+│   │
+│   ├── safety/
+│   │   ├── statement_gate.py    # sqlglot + hardcoded denylist
+│   │   ├── runtime.py           # L0 GUC SET (connect hook)
+│   │   └── audit.py             # append-only writer
+│   │
+│   ├── tools/                   # 3개만
+│   │   ├── run_sql.py           # statement_gate 통과 후 실행
+│   │   ├── explore_schema.py    # information_schema 기반
+│   │   └── ask_user.py
+│   │
+│   ├── tenancy/
+│   │   ├── concierge.py         # ContextConcierge
+│   │   └── encrypted_secrets.py # AES-GCM SQLite
+│   │
+│   ├── discord/
+│   │   ├── bot.py
+│   │   └── commands/
+│   │       ├── connect.py       # Modal 2필드 + button view 동의
+│   │       ├── ask.py           # 자연어 질문 → agent_loop → 응답
+│   │       ├── disconnect.py
+│   │       └── audit.py         # /audit me
+│   │
+│   └── adapters/
+│       ├── llm/openai_.py       # 기존 그대로
+│       └── db/postgres_explorer.py  # 기존 explorer를 async로 진화
+│
+├── tests/
+│   ├── test_semantic_layer.py   # 기존 보존
+│   ├── test_harness_core.py     # 기존 보존 (ctx 시그니처만 조정 ~50 LOC)
+│   ├── test_skills_registry.py  # 기존 보존
+│   └── safety/
+│       ├── test_statement_gate.py  # 회귀 12개 (V1 hard gate)
+│       └── test_ro_probe.py
+│
+└── docs/
+    ├── discord_first_redesign.md       # v1 보존
+    ├── discord_first_redesign_v2.md    # v2 보존 (확장 청사진)
+    ├── discord_first_redesign_v3_minimal.md  # ← 본 문서
+    ├── README_DEPLOY.md
+    └── README_READONLY_ROLE.md         # /connect 실패 시 가이드
+```
+
+**삭제** (PR-0):
+- `src/lang2sql/tui/` (Python Textual, ~1,400 LOC)
+- `src/lang2sql/components/`, `flows/`, `viz/`, `interface/`, `utils/`
+- `src/lang2sql/integrations/{embedding,vectorstore,loaders,chunking,catalog}/`
+- `src/lang2sql/integrations/llm/{gemma_, bedrock_, azure_, huggingface_, ollama_, gemini_}.py`
+- `src/lang2sql/tools/{run_code,write_code,define_*,search_semantic,write_sql,visualize,explain_query,profile_table,show_plan,load_skill}.py` (V1 미사용 — V1.5/V1.7에 복원)
+- `src/lang2sql/integrations/llm/anthropic_.py` 는 보존 (V2 노출용)
+- `cli/commands/{tui,init,quary,run_streamlit}.py`
+- `infra/observability/`, `infra/monitoring/`, `docker/pgvector/`, `pgvector.sh`
+- `interface/`, `prompt/`, `dev/e2e_traces/`, `test/`, `bench/` 일부, 옛 테스트 파일들
+
+**보존**:
+- `src/lang2sql/semantic/*` (~670 LOC, `dialect="postgres"` 기본값만 변경)
+- `src/lang2sql/harness/types.py` → `core/types.py`로 이동
+- `src/lang2sql/skills/registry.py` (V1.5 `load_skill` 도구 부활 시 사용)
+- `src/lang2sql/integrations/llm/{openai_, anthropic_}.py`
+- `src/lang2sql/integrations/db/sqlalchemy_explorer.py` → `adapters/db/postgres_explorer.py`로 async 진화
+- `cli/commands/{agent, serve}.py` → `frontends_dev/`로 이동 (V1엔 미노출, 디버그 보존)
+- `tui-go/` freeze
+- `bench/` (V1.5 마케팅 자료로 활용)
+- `docker/postgres/init/` (CI 시드)
+- 테스트 3개 (semantic, harness_core, skills_registry)
+
+---
+
+## 7. 마이그레이션 — 3주 walking skeleton
+
+```
+Week 0 (PR-0a + PR-0b, 합 1주)              [-7,700 LOC, +50 LOC]
+   PR-0a 안전 삭제 (3일):
+     • src/lang2sql/tui/, components/, flows/, viz/, 옛 cli
+     • 미사용 LLM 어댑터 (gemma 등)
+     • V1.x에서 부활할 tools/* 6개 (run_code/write_code 포함 — V2도 보류)
+     • python -c "import lang2sql" + 보존 tests 3개 통과 확인
+   PR-0b 의존 검증 후 삭제 (2일):
+     • grep -r "from lang2sql\." 로 cross-module import 그래프
+     • interface/, utils/, integrations/{embedding,vectorstore,...}
+     • harness/builder.py 의 build_explorer_from_url 사용처 확인 — utils/ 에 있다면 adapters/db/로 이동
+     • .github/workflows/v1_ci.yml 추가 (pytest 보존 3개)
+
+Week 1 (PR-1, kernel + ctx)                  [+450 LOC]
+   • core/ports/* 5개 (LLM, Explorer, Tool, Secrets, Audit)
+   • HarnessContext + Session(in-memory dict)
+   • Tool.execute(ctx, **args) 시그니처
+   • test_harness_core.py ctx 마이그레이션 (~50 LOC, 1시간)
+   • frontends_dev/cli.py로 kernel 검증 (PG sample db 로컬)
+
+Week 2 (PR-2, safety + 도구 3개)             [+550 LOC]
+   • safety/statement_gate.py (sqlglot + hardcoded denylist)
+   • safety/runtime.py (L0 GUC SET on connect)
+   • safety/audit.py + SQLite schema
+   • tools/run_sql.py — statement_gate 호출 후 execute
+   • tools/explore_schema.py — information_schema 기반
+   • adapters/db/postgres_explorer.py — async (asyncpg, AUTOCOMMIT)
+   • adapters/secrets/encrypted_sqlite.py (AES-GCM)
+   • tests/safety/ 회귀 12개 (CI gate)
+
+Week 3 (PR-3, discord + 출하)                [+700 LOC]
+   • discord/bot.py + setup_hook
+   • discord/commands/{connect, ask, disconnect, audit}
+   • Modal 2필드 + 동의 button view
+   • RO probe (§3.1 catalog 쿼리)
+   • tenancy/concierge.py
+   • ephemeral 응답 + CSV attach
+   • README_DEPLOY.md + README_READONLY_ROLE.md
+
+총: ~1,750 LOC 신규, ~7,700 LOC 삭제, 3주 솔로.
+```
+
+**회귀 12개** (V1 CI gate, Week 2에 완성):
+
+| # | 입력 | 기대 |
+|---|---|---|
+| 1 | `DROP TABLE users` | L1 block (Drop 노드) |
+| 2 | `; DELETE FROM t; --` | L1 block (multi_statement) |
+| 3 | `WITH x AS (INSERT INTO t VALUES (1) RETURNING *) SELECT * FROM x` | L1 block (CTE 내 Insert) |
+| 4 | `SELECT pg_sleep(60)` | L1 block (함수 denylist) |
+| 5 | `SELECT public.pg_sleep(60)` | L1 block (schema-qualified) |
+| 6 | `COPY foo TO PROGRAM 'curl ...'` | L1 block (Copy 노드) |
+| 7 | `EXPLAIN ANALYZE DELETE FROM t` | L1 block (analyze + DML) |
+| 8 | `DO $$ BEGIN INSERT INTO t VALUES(1); END $$` | L1 block (parse_error 또는 미허용 노드 — fail-closed) |
+| 9 | `SELECT * FROM big_table` (50,001 rows) | L0 timeout 30s 또는 row 한도 1000 truncate |
+| 10 | `SELECT pg_advisory_lock(1)` | L1 block |
+| 11 | `RESET ROLE; SELECT 1` | L1 block (multi_statement) |
+| 12 | `SELECT lo_export(1, '/tmp/x')` | L1 block (함수 denylist) |
+
+(pg-safety-expert가 라운드 1·2에서 권고한 회귀를 V1 CI로 승격. V2 backlog에 두는 게 아니라 V1 fail-closed의 정당성 자체이므로.)
+
+---
+
+## 8. 확장 로드맵 — 같은 포트에 어댑터 추가
+
+각 V1.x 는 **이전 V를 부수지 않고 어댑터/모듈만 추가**.
+
+```
+V1.5  (1주)  — Safety + 운영 보강
+   + safety/cost_gate.py (EXPLAIN warn+confirm — 단 V1.7 persistent View 전엔 텍스트 confirm만)
+   + safety/rate_limit.py (token bucket)
+   + safety/self_test.py (CI 자동 회귀, +5개 공격)
+   + tools/{define_metric, define_dimension, define_relationship, search_semantic, write_sql, load_skill}
+   + adapters/llm/nvidia_nim.py + contract test (통과 시 /model 노출)
+   + `/grant-readonly` 명령
+   + per-user 다중 DB (`/connections`, `/use`)
+
+V1.6  (1주)  — Hermes-lite 영속화
+   + adapters/session_store/encrypted_sqlite.py
+   + 11 event types: user_msg, tool_started, tool_finished,
+                    assistant_final, pending_prompt, run_interrupted,
+                    user_action, session_updated, safety_decision,
+                    cost_confirm, audit_marker
+     (Codex 권고로 6 → 11 확장)
+   + Session 어댑터를 in-memory → SQLite로 교체
+   + 부팅 시 active 세션 reattach + run_interrupted 표시
+
+V1.7  (1.5주)  — Discord 풍부함
+   + discord/streaming.py (throttled message edit)
+   + discord/interactive.py (persistent View)
+   + discord/render.py (PNG paginate, 25MB cap)
+   + tools/visualize.py 부활
+   + persistent_views 테이블 + recovery (setup_hook)
+   + cost_gate를 persistent View confirm으로 승격
+   + max_pages 200 + CSV 25MB 분할 정책
+
+V2  (별도 분기)  — 확장
+   + 길드 채널 / 스레드 세션 (schema/table allowlist + admin 승인)
+   + Anthropic provider family 노출 (family 전환 시 confirm)
+   + cost_gate hard-block tier (3-tier)
+   + audit hash chain + 외부 sink (S3/GCS)
+   + 의미적 정확성 implementation: golden query set, answer citation, validation loop
+   + MySQL / SQLite / BigQuery 어댑터
+   + 외부 secret manager (AWS SM / GCP SM)
+```
+
+**확장 시 절대 깨지지 않는 약속**:
+- 포트 5개의 시그니처 변경 금지 (확장은 *추가* 메서드만)
+- secrets / audit SQLite 스키마 변경은 마이그레이션 스크립트 동반
+- L0 + L1 + L4 는 모든 V에서 fail-closed
+
+---
+
+## 9. 핵심 거부·수용 사항 (transparency)
+
+5명 리뷰어 audit에서 **수용한 것**:
+- `run_code` / `write_code` 도구 V1 즉시 삭제 (Codex 최우선 지적)
+- Modal `acknowledgment` 평문 강제 폐기 → 별도 button view (discord-fact-checker)
+- RO probe를 `has_table_privilege()` 기반으로 (pg-safety-expert + Codex)
+- L0 GUC에 `work_mem`, `jit=off`, `bytea_output`, `application_name`, AUTOCOMMIT 추가 (pg-safety-expert)
+- `pool_size=5 → 2`, per-user db 1개 (max_connections 보호)
+- `connection_url`을 Paragraph → Short
+- 첨부 한도 8MB → **25MB** (현재 값, 2022 변경)
+- self-test 회귀를 V2 backlog → **V1 CI gate**로 승격 (12개)
+- 5.5주 → 3주 (walking skeleton + V1.x 단계로 분할)
+- 6 event types → V1엔 없음 (in-memory), V1.6에 11 event types로 확장 (Codex가 6→`user_action/session_updated/safety_decision` 추가 권고)
+
+**거부한 것** (사유 명시):
+- `write_sql` 코드 파일명 개명 — 코드 본문은 SQL 생성만, 실행은 `run_sql`. 파일명 유지. **단 LLM에 노출되는 tool name은 `compose_sql`로 변경** (codex의 PARTIALLY-JUSTIFIED 절충).
+- 5축 타이브레이커 — 4축 유지하되 축 #1을 "무결성 + 권한 + data exposure" 통합으로 명확화.
+- DM 데이터 유출 방지를 위한 V1 allowlist — V1엔 README 가이드로만, table allowlist는 V2 (사용자 trial 부담 최소화).
+- Hermes write-through full — V1엔 in-memory, V1.6에 영속화 단계 도입.
+
+---
+
+## 10. 잔여 결정 (V1 착수 전)
+
+1. **`compose_sql` vs `write_sql` LLM tool name** — 위 §9 절충안 적용? 그대로 `write_sql`?
+2. **첫 배포 길드 / 봇 application 생성** — Discord developer portal 어디 계정?
+3. **OpenAI 키 / NIM 키** — V1엔 OpenAI 하나면 충분.
+4. **`/audit me` 응답 — 최근 N건의 N 기본값** — 권고: 20건.
+
+---
+
+## 11. 한 줄
+
+> **V1은 "DM에서 `/connect` → `/ask` → 안전한 답"이 작동하는 walking skeleton. 3주에 출하. 확장은 모두 어댑터·모듈 추가로 V1.x 단위. V2 청사진은 `v2.md`에 보존.**
+
+— end —
diff --git a/docs/discord_first_redesign_v4.md b/docs/discord_first_redesign_v4.md
new file mode 100644
index 0000000..1cce05c
--- /dev/null
+++ b/docs/discord_first_redesign_v4.md
@@ -0,0 +1,639 @@
+# Lang2SQL v4 — 컨셉과 아키텍처
+
+> **작성일**: 2026-05-18
+> **결정자**: ryan@brain-crew.com
+> **상태**: 컨셉 확정 단계. v1/v2/v3는 보존 (역사 자료).
+> **전제**: 기존 레포 wipe 후 백지에서 다시 작성.
+
+---
+
+# Chap 1. 만들려는 것의 정체성
+
+## 1.1 기존 오픈소스의 공통 한계 — 어디를 비집고 들어갈까
+
+Vanna AI(~20k), Wren AI(~12k), SQLCoder(~3.8k) 같은 Text-to-SQL 오픈소스들은 *질문→SQL 파이프라인 자체* 는 이미 충분히 완성도 높음. 그러면 우리는 *그 위에 무엇을 더 얹을* 것인가가 정체성 결정.
+
+기존 오픈소스를 보면 공통적으로 **3가지 약점** 이 있음:
+
+| 약점 | 누구의 문제 | 기존 처리 |
+|---|---|---|
+| **DB 정보 완성도가 낮으면 성능 급락** | 사용자가 description·sample query 없이 등록 | Vanna: 학습 데이터 품질에 전적 의존 |
+| **이전 대화·정의를 기억 못함** | 매번 새 세션처럼 동작 | 대부분 stateless |
+| **비즈니스 맥락은 사람이 직접 정의해야 함** | metric 정의·용어집을 사용자가 일일이 입력 | Wren: MDL 수동 작성 |
+
+이 셋이 *실무에서는 매우 중요* 한데 *비즈니스마다 다르기 때문에 정량 평가가 어려운 영역*. 그래서 오픈소스가 잘 안 건드려옴. 우리는 **이 셋을 한 번에 다루는 방향** 으로 차별화.
+
+## 1.2 우리의 한 줄 컨셉
+
+> **"문서로 비즈니스 맥락을 학습하고, 당신의 DB에 대답하고, 모든 대화·정의를 기억하는 Discord 분석 에이전트."**
+
+기존 SQL 봇이 *"질문하면 SQL 만들어 줄게"* 였다면, 우리는 *"우리 회사 문서 넣어줘 → 학습할게 → 너희 팀이 같이 묻고 답을 받자 → 다 기억하고 다음에도 적용할게"*.
+
+## 1.3 4기둥 (Pillars)
+
+| 기둥 | 정체성 | 차별점 |
+|---|---|---|
+| **① Discord multi-mode** | DM(개인 분석) + 채널 멘션→thread(팀 협업) 양면 | 대부분 오픈소스는 Slack 또는 웹 UI 일면. Discord native + thread 패턴 |
+| **② Hermes-style 기억** | conversation + 학습된 facts + preferences 영속 | 대부분 stateless. *"우리 fiscal year는 7월 시작"* 한 번 가르치면 계속 적용 |
+| **③ 문서 → 시멘틱 레이어** | 사용자가 문서 업로드 → LLM이 metric/dim/rule 추출 → 사용자 confirm → 등록 | Wren의 MDL은 수동 작성. 우리는 *문서가 곧 진실의 출처* |
+| **④ DB 강건성 facade** | 사용자가 description 없이 등록해도 동작 | Vanna는 학습 데이터 품질 의존. 우리는 *불완전한 DB에서도 작동* 이 핵심 가치 |
+
+기둥 ④가 *우리 연구·제품 정체성의 가장 중요한 한 포인트*. *"사용자가 입력하는 DB 정보의 완성도가 낮아도 성능 하락을 최소화"* 가 차별화. V1엔 껍데기만, V1.x에서 깊이 채움.
+
+## 1.4 타이브레이커 (충돌 시 우선순위)
+
+설계가 충돌하면 위에서 아래로:
+
+1. **무결성 + 권한** — DB가 변하지 않고, 권한 있는 데이터만 본다
+2. **의미적 정확성** — 답이 *진짜로* 맞는다 (자신 있게 틀린 답이 가장 위험)
+3. **Discord UX** — 한 번에 결과 (멘션→thread)
+4. **맥락 보존** — 끊겨도 이어진다 (Hermes 영속화)
+
+(v2까지의 *"DB가 안 변하는가"* 한 축에서 *"+ 권한"* 까지 통합. Codex 외부 리뷰의 *"권한/data exposure를 별도 축으로"* 우려를 축 #1 안에 흡수.)
+
+---
+
+# Chap 2. 아키텍처 — ASCII로 보는 큰 그림
+
+## 2.1 전체 흐름
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                          USER (Discord)                              │
+│                                                                       │
+│   DM message     |     Channel @mention      |     Thread reply       │
+│   ─────────     |     ─────────────────     |     ─────────────       │
+│   (개인 분석)    |    (봇이 thread 생성)     |   (같은 thread 계속)    │
+└──────┬────────────────────┬────────────────────────┬─────────────────┘
+       │                    │                        │
+       └────────────────────┼────────────────────────┘
+                            ▼
+       ┌────────────────────────────────────────────────┐
+       │  DISCORD ADAPTER                                │
+       │   • 입력 분류 → session_key 결정                  │
+       │     - dm:USER_ID                                │
+       │     - thr:GUILD:CHANNEL:THREAD_ID                │
+       │   • 멘션 없는 채널 메시지 → 무시                  │
+       │   • 응답 렌더링 (텍스트 / CSV / PNG)              │
+       └────────────────────┬───────────────────────────┘
+                            ▼
+       ┌────────────────────────────────────────────────┐
+       │  MEMORY + CONCIERGE                             │
+       │                                                  │
+       │   MemoryService {                                │
+       │     FactStore        ◄─ "어디 저장하나"           │
+       │     RecallStrategy   ◄─ "무엇을 가져올지"          │
+       │     FactExtractor    ◄─ "어떻게 만들지"           │
+       │   }                                              │
+       │                                                  │
+       │   IngestionPipeline {                            │
+       │     DocumentSource[] ◄─ "어디서 가져올지"          │
+       │     DocumentExtractor[] ◄─ "어떻게 해석할지"       │
+       │   }                                              │
+       │                                                  │
+       │   ContextConcierge.build(session_key, principal) │
+       │     → ctx 조립                                    │
+       └────────────────────┬───────────────────────────┘
+                            ▼ ctx
+       ┌────────────────────────────────────────────────┐
+       │  ★ HARNESS (조립된 단위, 하나의 덩어리)            │
+       │                                                  │
+       │   HarnessContext {                               │
+       │     llm           — OpenAI port                  │
+       │     tools         — run_sql, ingest_doc, ...     │
+       │     semantic      — SemanticLayer (live ref)     │
+       │     session       — 영속 conversation + facts    │
+       │     safety        — SafetyPipeline               │
+       │     explorer      — DB (asyncpg)                 │
+       │     audit         — append-only                  │
+       │   }                                              │
+       │                                                  │
+       │   agent_loop(ctx, question):                     │
+       │     while turn < max:                            │
+       │        prompt = system_prompt(ctx)               │
+       │            ├─ semantic 주입                       │
+       │            ├─ recalled facts 주입                 │
+       │            └─ schema 주입                         │
+       │        resp = llm.invoke(prompt, tools)          │
+       │        if resp.tool_calls:                       │
+       │          for tc in resp.tool_calls:              │
+       │            result = tools.execute(ctx, tc)       │
+       │            session.append('tool_finished', ...)  │
+       │        else:                                     │
+       │          yield resp.content                      │
+       │          break                                   │
+       │                                                  │
+       │   run_sql tool 내부:                              │
+       │     ★ ctx.safety.evaluate(sql, ctx)              │
+       │        Layer 1 → 2 → 3 → ...                     │
+       └────────────────────┬───────────────────────────┘
+                            ▼
+       ┌────────────────────────────────────────────────┐
+       │  OUTBOUND ADAPTERS                              │
+       │   LLM:     openai_                              │
+       │   DB:      postgres_explorer (asyncpg)          │
+       │   Store:   encrypted_sqlite                     │
+       └────────────────────────────────────────────────┘
+                            ▼
+              사용자 PostgreSQL · OpenAI · 로컬 SQLite
+```
+
+핵심 정정:
+- **하네스는 tools·semantic·session·safety 를 *분리된 레이어로 위아래* 두지 않음.** 모두 `HarnessContext` 안에 *주입된 의존성* 으로 들어감. 하네스 = 조립된 한 덩어리.
+- DM/Channel 양분은 *session_key 결정 단계에서만 다름*. 그 아래로는 동일 흐름.
+- 도구 안에서 SafetyPipeline 호출 → 각 layer가 차례로 검증.
+
+## 2.2 디렉토리 구조
+
+```
+lang2sql/
+├── README.md
+├── pyproject.toml
+├── .env.example
+│
+├── src/lang2sql/
+│   ├── core/                      # 순수 타입 + 포트
+│   │   ├── types.py               # Message, ToolCall, ToolResult, Event
+│   │   ├── identity.py            # Principal
+│   │   └── ports/
+│   │       ├── llm.py
+│   │       ├── explorer.py
+│   │       ├── tool.py
+│   │       ├── secrets.py
+│   │       ├── audit.py
+│   │       ├── session_store.py
+│   │       ├── safety.py          ── SafetyLayer Protocol
+│   │       ├── memory.py          ── FactStorePort, RecallStrategy, FactExtractor
+│   │       └── ingestion.py       ── DocumentSource, DocumentExtractor
+│   │
+│   ├── harness/                   # 조립된 단위
+│   │   ├── context.py             # HarnessContext
+│   │   ├── session.py             # conversation + facts
+│   │   ├── loop.py                # agent_loop (async generator)
+│   │   ├── system_prompt.py       # per-turn rebuild
+│   │   └── tool_registry.py
+│   │
+│   ├── semantic/                  # 도메인 모델
+│   │   ├── types.py
+│   │   ├── layer.py
+│   │   ├── sql_composer.py
+│   │   └── store.py
+│   │
+│   ├── safety/                    # ★ SafetyPipeline chain
+│   │   ├── pipeline.py
+│   │   └── layers/
+│   │       ├── whitelist_gate.py
+│   │       └── timeout_setter.py
+│   │
+│   ├── memory/                    # ★ 3축 분리
+│   │   ├── service.py
+│   │   ├── stores/
+│   │   │   └── inmemory.py
+│   │   ├── recall/
+│   │   │   └── all_facts.py
+│   │   └── extractors/
+│   │       └── manual.py
+│   │
+│   ├── ingestion/                 # ★ Source × Extractor
+│   │   ├── pipeline.py
+│   │   ├── sources/
+│   │   │   └── file.py
+│   │   └── extractors/
+│   │       └── llm_extractor.py
+│   │
+│   ├── tools/                     # ctx-aware
+│   │   ├── run_sql.py
+│   │   ├── explore_schema.py
+│   │   ├── define_metric.py
+│   │   ├── ingest_doc.py
+│   │   ├── remember.py
+│   │   └── ask_user.py
+│   │
+│   ├── tenancy/                   # 멀티유저
+│   │   ├── concierge.py
+│   │   └── encrypted_secrets.py
+│   │
+│   ├── discord/                   # ★ 1급 frontend
+│   │   ├── bot.py
+│   │   ├── commands/
+│   │   │   ├── connect.py
+│   │   │   ├── ingest.py
+│   │   │   ├── remember.py
+│   │   │   └── audit.py
+│   │   ├── session_router.py      # DM / thread 분기
+│   │   └── render.py
+│   │
+│   └── adapters/                  # outbound
+│       ├── llm/openai_.py
+│       ├── db/postgres_explorer.py
+│       └── storage/encrypted_sqlite.py
+│
+├── tests/
+│   ├── unit/
+│   ├── safety/                    # 회귀 12개 (CI gate)
+│   └── e2e/
+└── docs/
+```
+
+`★` 3개가 **확장 핵심** — 다음 Chap 3에서 자세히.
+
+---
+
+# Chap 3. 확장성 — 3개의 chain/strategy 패턴
+
+## 3.1 왜 chain/strategy 패턴인가
+
+V1엔 *가장 단순한 1개씩* 만 구현, V1.5/V2에서 *어댑터를 추가* 하는 방식으로 확장.
+
+이게 *진짜* "확장 가능"의 의미. 단순히 *"미루는 것"* 이 아니라, *V1엔 단순 구현으로 동작하지만 추상은 박혀 있어서 V1.5에 새 구현을 끼울 때 기존 코드를 안 건드리는* 것.
+
+비유: 콘센트(포트)와 가전(어댑터)의 관계. V1엔 LED 전구 하나, V1.5엔 선풍기 추가, V2엔 스마트 조명 추가 — 콘센트는 그대로.
+
+## 3.2 ★ ① SafetyPipeline — DB 강건성의 모이는 곳
+
+### 패턴
+
+```python
+class SafetyLayer(Protocol):
+    name: str
+    async def check(self, sql: str, ctx: HarnessContext) -> Verdict: ...
+    # Verdict: allow | block(reason) | confirm(plan) | transform(sql')
+
+class SafetyPipeline:
+    def __init__(self, layers: list[SafetyLayer]):
+        self.layers = layers
+    
+    async def evaluate(self, sql, ctx) -> SafetyResult:
+        current = sql
+        for layer in self.layers:
+            v = await layer.check(current, ctx)
+            if v.kind == 'block':     return SafetyResult.blocked(...)
+            if v.kind == 'confirm':   await ctx.request_confirm(v.plan)
+            if v.kind == 'transform': current = v.transformed_sql
+        return SafetyResult.allowed(current)
+```
+
+### V1 → V2 진화
+
+| 버전 | layers (순서대로) | 비용 |
+|---|---|---|
+| **V1** (껍데기) | `WhitelistGate` (SELECT/WITH로 시작) + `TimeoutSetter` (statement_timeout) | ~200 LOC |
+| **V1.5** | + `SqlglotASTGate` (AST 기반 정밀 검증) + `FunctionDenylist` (pg_sleep 등 차단) + `LimitInjector` (SELECT에 LIMIT 자동 부착) + `GUCPackSetter` (5 GUC pack) + `RateLimit` (token bucket) | +500 LOC |
+| **V2** | + `CostGate` (EXPLAIN multi-metric) + per-engine pipeline (PG vs BQ) + `AuditHashChain` | +400 LOC |
+
+### 의미 — *DB 정보 완성도가 낮아도 동작*
+
+V1.5에 *"description 없는 컬럼은 자동 description 생성"* 같은 layer 추가 가능:
+
+```python
+class AutoDescribeLayer:
+    """description이 없는 컬럼을 LLM으로 생성해 시멘틱에 주입"""
+    async def check(self, sql, ctx):
+        missing = [c for c in ctx.referenced_columns(sql) if not c.description]
+        for col in missing:
+            desc = await self.llm.describe_column(col)
+            ctx.semantic.upsert_dimension(col.name, description=desc)
+        return Verdict.allow()
+```
+
+기존 컴포넌트 변경 0. 그냥 layer 1개 추가.
+
+V1.5엔 *"DB 강건성"* 차별화의 핵심 layer들이 들어옴 — *불완전한 메타데이터를 자동 보강* 하는 layer들. 그게 우리 제품의 한 포인트.
+
+---
+
+## 3.3 ★ ② MemoryService — Hermes 기억의 3축 분리
+
+### 패턴
+
+```python
+# 3축이 독립적으로 진화
+class FactStorePort(Protocol):
+    async def put(self, fact: Fact) -> str: ...
+    async def query(self, scope: Scope, filter: dict) -> list[Fact]: ...
+
+class RecallStrategy(Protocol):
+    async def recall(self, store, ctx, question: str) -> list[Fact]: ...
+
+class FactExtractor(Protocol):
+    async def extract(self, recent_events: list[Event]) -> list[Fact]: ...
+
+class MemoryService:
+    def __init__(self, store, recall, extractor): ...
+```
+
+### V1 → V2 진화
+
+| 버전 | Store | Recall | Extractor |
+|---|---|---|---|
+| **V1** | `InMemoryFactStore` | `AllFactsRecall` (전부 주입) | `ManualOnly` (`/remember` 명령만) |
+| **V1.5** | `SqliteFactStore` (영속) | `KeywordRecall` (질문 키워드 매칭) | `LLMExtractor` (대화에서 반복 패턴 추출) |
+| **V2** | `SqliteFactStore` | `EmbeddingRecall` (벡터 유사도) | + `ConflictResolver` (사용자가 X 했다가 not-X 했을 때) |
+| **V2.5** | `PostgresFactStore` (멀티 인스턴스) | `HybridRecall` (keyword + embedding + recency) | + 신뢰도 점수 |
+
+### 의미 — *진짜* Hermes-style
+
+V1엔 *"`/remember "우리 fiscal year는 7월 시작"` 명령으로만 fact 등록 + 모든 facts를 매번 전부 주입"* — 단순. 그러나 *facts가 영속화되고 모든 세션에서 적용* 됨.
+
+V1.5에 LLMExtractor 추가하면 *"사용자가 매번 'KST 기준'을 강조하니 자동으로 facts에 시간대=KST 저장"* 같은 자동 학습. V2에 EmbeddingRecall 추가하면 *"질문과 관련된 facts만 가져와 토큰 절약 + 신호 강화"*.
+
+핵심: V1.5/V2 변경 시 `harness/` 코드는 한 줄도 안 건드림. `memory/` 안에 새 클래스 추가.
+
+---
+
+## 3.4 ★ ③ IngestionPipeline — 문서 → 시멘틱 레이어
+
+### 패턴
+
+```python
+class DocumentSource(Protocol):
+    name: str
+    async def fetch(self, ref: str) -> Document: ...
+
+class DocumentExtractor(Protocol):
+    name: str
+    target_kinds: set[str]   # {'metric', 'dimension', 'business_rule'}
+    async def extract(self, doc, schema_summary) -> list[Candidate]: ...
+
+class IngestionPipeline:
+    def __init__(self, sources, extractors): ...
+    
+    async def ingest(self, source_kind, ref, ctx) -> list[Candidate]:
+        doc = await self.sources[source_kind].fetch(ref)
+        candidates = []
+        for ext in self.extractors:
+            candidates += await ext.extract(doc, ctx.schema_summary)
+        return candidates   # → 사용자 confirm UI로
+```
+
+### V1 → V2 진화
+
+| 버전 | Sources | Extractors |
+|---|---|---|
+| **V1** | `FileUpload` (MD/PDF/TXT) | `LLMExtractor` (단일 prompt) |
+| **V1.5** | + `URLFetch` (HTML/PDF) | + `DDLExtractor` (DB schema 파일 직접 파싱) |
+| **V2** | + `NotionMCP`, `ConfluenceMCP` | + `HybridExtractor` (LLM + rule-based) |
+| **V2.5** | + `GitHubMarkdown`, `GoogleDriveMCP` | + `ChunkedRAGExtractor` (긴 문서) |
+
+### 흐름 — V1 walking skeleton
+
+```
+사용자: /ingest <파일 첨부> metric_definitions.md
+   │
+   ▼
+FileUpload.fetch()
+   │ doc.text = "매출은 SUM(orders.amount) WHERE status != 'cancelled'..."
+   ▼
+LLMExtractor.extract(doc, current_schema)
+   │ LLM prompt:
+   │  "다음 문서에서 metric/dimension/business_rule을 찾아 JSON으로 반환:
+   │   - 현재 DB 스키마: {orders, order_items, products, customers}
+   │   - 문서: {doc.text}
+   │  ..."
+   │ → candidates = [
+   │     {kind: 'metric', name: 'total_revenue', 
+   │      expr: 'SUM(orders.amount)', source_doc: 'metric_definitions.md#L12'},
+   │     {kind: 'business_rule', name: 'exclude_cancelled',
+   │      sql: "status != 'cancelled'", applies_to: ['total_revenue']},
+   │   ]
+   ▼
+Discord embed (button view):
+   "이 문서에서 다음을 찾았어요:
+    📊 METRIC: total_revenue
+       SUM(orders.amount)
+       출처: metric_definitions.md L12
+    
+    📋 RULE: exclude_cancelled (적용: total_revenue)
+       status != 'cancelled'
+    
+    [✅ 모두 등록] [개별 선택] [❌ 취소]"
+   ▼
+사용자 ✅
+   ▼
+SemanticLayer.add(...) + source_doc reference 보존
+   ▼
+이후 /ask "이번 달 매출" 
+   ▼ LLM이 SemanticLayer에서 total_revenue 자동 매칭
+   ▼ SQLComposer가 exclude_cancelled rule을 WHERE에 자동 주입
+```
+
+V1.5에서 같은 문서 재업로드 시 *diff* 표시 → 사용자가 update/keep/remove 선택. 즉 *"문서가 곧 단일 진실 소스"* 패턴.
+
+### 의미 — *비즈니스 맥락을 잘 이해*
+
+기둥 ③의 진짜 의미. 사용자가 사내 정의를 *문서로* 가지고 있다면 그대로 업로드 → 자동 추출 → confirm → 적용. *Wren AI의 MDL 수동 작성* 대비 비교 우위.
+
+---
+
+## 3.5 V1엔 무엇을 박아두고 무엇을 미루는가
+
+```
+V1에 반드시 있어야 할 추상 (포트·인터페이스만, ~300 LOC 추가 비용):
+  core/ports/safety.py        — SafetyLayer Protocol
+  core/ports/memory.py        — FactStorePort, RecallStrategy, FactExtractor
+  core/ports/ingestion.py     — DocumentSource, DocumentExtractor
+  
+  safety/pipeline.py          — SafetyPipeline 클래스
+  memory/service.py           — MemoryService 클래스
+  ingestion/pipeline.py       — IngestionPipeline 클래스
+
+V1엔 각 추상의 단순 구현 1~2개씩만 (~700 LOC):
+  safety/layers/{whitelist_gate, timeout_setter}.py
+  memory/stores/inmemory.py + recall/all_facts.py + extractors/manual.py
+  ingestion/sources/file.py + extractors/llm_extractor.py
+```
+
+추상 비용: ~300 LOC.
+V1.5에서 절감하는 비용: ~500 LOC (chain 패턴이 없었다면 매번 코어 수정).
+V2에서 절감하는 비용: ~1,000 LOC.
+**초기 투자가 빠르게 회수**.
+
+---
+
+# Chap 4. V1 walking skeleton
+
+## 4.1 V1에 들어가는 것
+
+| 영역 | V1 |
+|---|---|
+| Discord 진입 | DM 메시지 / 채널 `@bot` 멘션 → 자동 thread / thread reply |
+| 명령 | `/connect`, `/ingest <파일>`, `/remember "..."`, `/audit me`, `/forget <id>` |
+| 자연어 | DM 또는 thread 안에서 그냥 묻기 |
+| LLM | OpenAI `gpt-4.1-mini` 단일 |
+| DB | PostgreSQL only |
+| 응답 | 텍스트 (≤50행) 또는 CSV 첨부 (>50행) |
+| Safety | SafetyPipeline + V1 layer 2개 (WhitelistGate + TimeoutSetter) |
+| Memory | MemoryService + V1 구현 (InMemory + AllFacts + Manual) |
+| Ingestion | IngestionPipeline + V1 (FileUpload + LLMExtractor) |
+| 영속화 | secrets/audit/sessions/facts → SQLite. conversation → 영속 |
+| 도구 | run_sql · explore_schema · ingest_doc · define_metric · remember · ask_user |
+| 호스팅 | Oracle Cloud Always Free 또는 fly.io free |
+
+## 4.2 V1에 *안* 들어가는 것
+
+| 항목 | 미루는 곳 | 이유 |
+|---|---|---|
+| `run_code` / `write_code` (Python 실행) | **영구 삭제** | read-only 약속을 무력화. 부활 시 sandbox 필수 |
+| Cost gate (EXPLAIN 기반) | V1.5 | L1 + L0 timeout으로 1차 충분 |
+| Function denylist | V1.5 | WhitelistGate가 1차 방어 |
+| Rate limit | V1.5 | 트라이얼 두 자릿수 |
+| Auto fact extraction | V1.5 (LLMExtractor 추가) | Manual `/remember` 로 시작 |
+| URL/Notion 문서 입력 | V1.5 / V2 | FileUpload 1개로 시작 |
+| Embedding recall | V2 | 토큰 절약 효과는 facts가 많아질 때 |
+| Persistent View / streaming / PNG paginate | V1.7 | Discord SDK 깊은 영역 |
+| Anthropic / NIM | V1.5 (contract test 후) | OpenAI 하나로 시작 |
+| 길드 channel 활성화 admin 게이트 | (멘션 패턴이 대체) | thread는 채널 권한 상속 |
+| Audit hash chain | V2 | 트라이얼은 SQLite append-only로 충분 |
+| `visualize` (PNG 차트) | V1.7 | V1엔 CSV 첨부로 충분 |
+
+## 4.3 V1 LOC 추정
+
+```
+core/                ~600 LOC  (ports + types + identity)
+harness/             ~700 LOC  (context, session, loop, system_prompt, tool_registry)
+semantic/            ~600 LOC  (types, layer, sql_composer, store)
+safety/              ~250 LOC  (pipeline + 2 layers)
+memory/              ~350 LOC  (service + 3 simple impls)
+ingestion/           ~300 LOC  (pipeline + 2 adapters)
+tools/               ~700 LOC  (6 tools × 평균 ~120 LOC)
+tenancy/             ~400 LOC  (concierge, encrypted_secrets, factstore)
+discord/             ~800 LOC  (bot, commands 5개, session_router, render)
+adapters/            ~500 LOC  (openai, postgres_async, encrypted_sqlite)
+tests/               ~900 LOC  (unit + safety 회귀 + e2e mock)
+
+총 V1: ~6,100 LOC 신규
+```
+
+## 4.4 일정 — 4.5~5주 솔로
+
+```
+Week 1 — core + harness
+   • core/ports/ (5 + safety/memory/ingestion 추상 3)
+   • HarnessContext, Session (in-memory + 영속 facts), agent_loop
+   • frontends_dev/cli.py 로 단위 검증
+
+Week 2 — semantic + safety + 첫 도구들
+   • semantic/* 도메인 모델 + SQLComposer
+   • safety/pipeline.py + layers/(whitelist, timeout)
+   • tools/{run_sql, explore_schema}
+   • adapters/{openai, postgres_async, encrypted_sqlite}
+   • tests/safety/ 회귀 12개 (CI gate)
+
+Week 3 — memory + ingestion + 나머지 도구
+   • memory/service + 3 impl
+   • ingestion/pipeline + 2 adapter
+   • tools/{ingest_doc, define_metric, remember, ask_user}
+   • tenancy/{concierge, encrypted_secrets, factstore}
+
+Week 4 — Discord
+   • bot.py + setup_hook
+   • commands/{connect, ingest, remember, audit, forget}
+   • session_router (DM / channel @mention → thread / thread reply)
+   • render (텍스트 / CSV 첨부)
+   • Modal + 동의 button view
+
+Week 5 — polish + e2e + 출하
+   • README + DEPLOY 가이드
+   • bench/ 데모 시나리오 1개
+   • CI YAML
+   • 첫 길드 배포
+
+총: 4.5~5주 솔로 풀타임.
+```
+
+3주는 *기존 코드 70% 활용* 가정이었음. wipe 기준엔 4.5~5주가 정직.
+
+## 4.5 회귀 12개 (V1 CI gate)
+
+| # | 입력 | 기대 |
+|---|---|---|
+| 1 | `DROP TABLE users` | WhitelistGate block (DDL) |
+| 2 | `; DELETE FROM t; --` | WhitelistGate block (multi-statement) |
+| 3 | `INSERT INTO t VALUES (1)` | WhitelistGate block |
+| 4 | `UPDATE t SET x=1` | WhitelistGate block |
+| 5 | `WITH x AS (INSERT INTO t VALUES (1)) SELECT * FROM x` | WhitelistGate block (CTE 안 INSERT — V1.5 SqlglotASTGate 이전엔 *최상위 노드만* 보지만, WITH+INSERT는 첫 키워드가 WITH라 통과될 수 있음 → V1엔 *INSERT 키워드 검색* 으로 fail-closed) |
+| 6 | `SELECT * FROM nonexistent` | PG error (gate 통과, 실행 단계 실패) |
+| 7 | `SELECT pg_sleep(60)` | (V1엔 timeout 30s에서 cut. V1.5 FunctionDenylist 추가 시 명시 block.) |
+| 8 | `SELECT * FROM huge_table` (50k rows) | row_limit 1000 truncate |
+| 9 | `SELECT 1` (정상) | allow |
+| 10 | `WITH a AS (SELECT 1) SELECT * FROM a` (정상 CTE) | allow |
+| 11 | `EXPLAIN SELECT 1` | allow |
+| 12 | `` (빈 문자열) | block (parse_error) |
+
+V1엔 단순한 회귀. V1.5에서 ASTGate 추가 시 회귀가 *훨씬 정밀해짐*. 그때 추가:
+- `SELECT public.pg_sleep(60)` (schema-qualified) → FunctionDenylist
+- `COPY foo TO PROGRAM 'curl ...'` → ASTGate
+- `EXPLAIN ANALYZE DELETE FROM t` → ASTGate
+
+---
+
+# Chap 5. 의견 정리
+
+## 5.1 왜 이 설계가 작동할 거라 보는가
+
+**(1) "오픈소스의 정체성"이 차별점에 부합**
+
+Vanna/Wren/SQLCoder가 *질문→SQL 파이프라인 자체* 는 완성도 높음. 우리가 또 *"GPT-4보다 더 좋은 SQL을 만든다"* 로 경쟁하면 *오픈소스 정체성* 이 약함 — 모델 fine-tuning은 데이터·GPU 싸움.
+
+대신 우리는 *"불완전한 DB에서도 잘 동작" + "문서로 비즈니스 맥락 학습" + "Discord에서 팀이 같이 묻고 답을 받음" + "모든 정의·대화를 기억"* — 이 4가지 조합은 기존 오픈소스에 *없음*. 그게 정체성.
+
+**(2) chain/strategy 패턴이 *체계화된 강건성 연구* 의 코드 토대**
+
+DB 강건성 차별화는 *"description 없으면 자동 생성"* 같은 *상황별 커스텀 전략* 의 모음. V1.5의 SafetyPipeline layer들이 그 전략을 *추가 가능한 형태* 로 받아들임. 새 전략 = 새 layer 1개.
+
+연구자 입장에선 *Hint Vector* 같은 *DB 구조에 대한 근본적 강건성* 도 한 layer로 들어올 수 있음. 즉 *연구→제품* 흐름이 자연스러움.
+
+**(3) 멘션+thread 패턴이 Discord native**
+
+DM vs Channel 양분이 사라지고, *thread* 가 *분석 노트* 가 됨. Discord 사용자 멘탈 모델과 일치. 가짜연구소 같은 use case도 자연스럽게 들어옴.
+
+**(4) Hermes 기억이 *실무 가치* 와 직결**
+
+*"우리 회사 매출 정의는 이거"* 한 번 가르치면 *모든 세션에서 적용*. 매번 prompt에 풀어 넣는 LLM과 차별. facts가 쌓일수록 *제품 가치가 누적* 됨 — 사용자 lock-in.
+
+## 5.2 한계와 trade-off (정직하게)
+
+| 한계 | 영향 | 대응 |
+|---|---|---|
+| 의미적 정확성의 정량 평가 부재 | "안전하게 틀린 답"이 가장 위험한데 V1엔 validation loop 없음 | V1.5에 golden query set + answer citation. 그러나 본질은 *비즈니스마다 다름* — 우리 측 한계 |
+| LLM 비용 노출 | 토큰 폭주 시 사용자 비용 증가 | V1.5에 rate limit + per-user 토큰 cap |
+| 첫 출하까지 4.5~5주 | 빠른 검증 어려움 | walking skeleton이지만 wipe라 4주 미만은 무리 |
+| chain/strategy 추상 비용 | V1 LOC +300 | V1.5/V2에서 절감되는 비용으로 회수 (계산상 흑자) |
+| Discord 플랫폼 락-인 | Discord 외 사용 시 어댑터 추가 필요 | 4기둥 중 Discord는 *frontend 어댑터* 일 뿐, 핵심은 변하지 않음. Slack 어댑터 추가 시 ~500 LOC |
+| 의미 추출 LLM 환각 | 문서에서 잘못된 metric 추출 가능 | 사용자 confirm 단계가 1차 방어. V1.5에 validator layer |
+| in-memory recall (V1) | facts 많아지면 토큰 폭증 | V1.5에 KeywordRecall, V2에 EmbeddingRecall |
+
+## 5.3 비교 — 기존 오픈소스 대비 위치
+
+| 영역 | Vanna AI | Wren AI | SQLCoder | **Lang2SQL (우리)** |
+|---|---|---|---|---|
+| 자연어 → SQL | ✅ RAG | ✅ MDL 기반 | ✅ fine-tuned LLM | ✅ RAG + 시멘틱 + harness |
+| DB 직접 연결 | ✅ | ✅ | ✅ | ✅ |
+| Semantic layer | ❌ | ✅ (수동 MDL) | ❌ | ✅ (**문서 자동 추출**) |
+| 대화 기억 | ❌ | ❌ | ❌ | ✅ (**Hermes**) |
+| 멀티유저 협업 | 2.0에서 추가 | enterprise BI | ❌ | ✅ (**Discord thread**) |
+| 불완전 DB 보강 | ❌ (학습 데이터 의존) | ❌ | ❌ | ✅ (**V1.5+ 자동 보강 layer**) |
+| 사용 UI | Web UI | Web UI | CLI | **Discord** |
+| 확장 모델 | 단일 architecture | enterprise platform | 단일 LLM | **chain/strategy 3개** |
+
+**위치 요약**: *Vanna의 자연어→SQL + Wren의 시멘틱 + 우리만의 (문서 자동 추출 + Discord 협업 + Hermes 기억 + DB 강건성 layer)*.
+
+## 5.4 한 줄
+
+> **"Discord 멘션으로 thread를 띄우고, 문서를 넣어 비즈니스 맥락을 학습시키고, DB가 불완전해도 견디고, 모든 대화·정의를 기억하는 오픈소스 분석 에이전트."**
+
+---
+
+# 결정 필요 사항
+
+V1 착수 전 답이 있으면 좋은 항목:
+
+1. **첫 배포 Discord 길드** — 본인 테스트 길드 / 가짜연구소 / 기타?
+2. **OpenAI API 키** — 본인 키 / 팀 키 / 무료 한도?
+3. **레포 새 이름 vs `lang2sql/` 유지** — 권고: 유지 + 새 브랜치 (`feature/v4-rebuild`)
+4. **첫 데모 시나리오 1개** — bench/ 에 들어갈 *완성된 use case*. 예: "이커머스 매출 분석 — 4 테이블, 3 metric, 1 문서, 5개 질문"
+5. **NIM 도입 시점** — V1.5에 contract test 후 / V2까지 보류?
+
+답해 주시면 v4-final 로 마무리하고 Week 1 PR-1 (core + harness) 부터 시작.
+
+— end —
diff --git a/docs/discord_first_redesign_v4_1.md b/docs/discord_first_redesign_v4_1.md
new file mode 100644
index 0000000..f588584
--- /dev/null
+++ b/docs/discord_first_redesign_v4_1.md
@@ -0,0 +1,610 @@
+# Lang2SQL v4.1 — 컨셉과 아키텍처
+
+> **작성일**: 2026-05-18
+> **결정자**: ryan@brain-crew.com
+> **상태**: v4 → v4.1. 두 가지 큰 정정 — (a) Discord 를 *기둥* 에서 *Phase 1 인터페이스* 로 격하, (b) **시멘틱 federation (git-like 분기)** 을 4번째 ★ 패턴으로 추가.
+> **전제**: 기존 레포 wipe 후 백지에서 다시 작성.
+
+---
+
+# Chap 1. 만들려는 것의 정체성
+
+## 1.1 기존 오픈소스의 공통 한계
+
+Vanna AI(~20k), Wren AI(~12k), SQLCoder(~3.8k) 같은 Text-to-SQL 오픈소스들은 *질문→SQL 파이프라인 자체* 는 이미 완성도가 높음. 우리는 *그 위에 무엇을 더 얹을* 것인가가 정체성 결정.
+
+기존 오픈소스의 **공통 약점**:
+
+| 약점 | 누구의 문제 | 기존 처리 |
+|---|---|---|
+| **DB 정보 완성도 낮으면 성능 급락** | 사용자가 description/sample 없이 등록 | Vanna: 학습 데이터 품질에 전적 의존 |
+| **이전 대화·정의 못 기억** | 매번 새 세션처럼 동작 | 대부분 stateless |
+| **비즈니스 맥락은 사람이 직접 정의** | metric·용어집을 일일이 입력 | Wren: MDL 수동 작성 |
+| **단일 진실 (single truth) 모델의 조직 충돌** | 같은 회사라도 팀별로 *"활성 사용자"* 정의가 다름. 한 팀이 바꾸면 다른 팀 깨짐 | Wren: 단일 MDL. Vanna: 학습 데이터 혼선 |
+
+이 네 가지가 *실무에서 매우 중요* 한데 *비즈니스마다 다르기 때문에 정량 평가가 어려운 영역*. 그래서 오픈소스가 잘 안 건드림. 우리는 **이 네 가지를 한 번에 다루는 방향** 으로 차별화.
+
+## 1.2 우리의 한 줄 컨셉
+
+> **"문서로 비즈니스 맥락을 학습하고, 팀별로 시멘틱이 분기되고, 불완전한 DB에서도 답하고, 모든 정의·대화를 기억하는 오픈소스 분석 에이전트."**
+
+기존 SQL 봇이 *"질문하면 SQL 만들어 줄게"* 였다면, 우리는 *"우리 회사 문서 넣어줘 → 학습할게 → 팀별로 다른 정의도 같이 들고 있을게 → 너희가 묻고 답을 받자 → 다 기억하고 다음에도 적용할게"*.
+
+**Discord 는 Phase 1 인터페이스**. Slack/Web/Teams 도 같은 코어 위에서 어댑터로 추가 가능. *Discord 자체* 는 정체성이 아니라 *멀티 인터페이스* 의 첫 구현.
+
+## 1.3 4기둥 (Pillars)
+
+| 기둥 | 정체성 | 차별점 |
+|---|---|---|
+| **① 비즈니스 맥락 학습** | 문서→시멘틱 자동 추출 + 사용자 confirm | Wren MDL 은 수동 작성. 우리는 *문서가 곧 진실의 출처* |
+| **② 강건성 (2축)** | (2a) **DB 강건성** — 불완전 메타데이터 자동 보강 (2b) **시멘틱 강건성** — 팀별 다른 정의 federation | 기존 오픈소스 *없는 영역*. 우리의 한 포인트 |
+| **③ Hermes 기억** | conversation + facts + preferences 영속 | 대부분 stateless |
+| **④ 멀티 인터페이스** | Phase 1: Discord, Phase 2: Slack, Phase 3: Web | Discord는 *어댑터 하나*, lock-in 없음 |
+
+기둥 ②가 *우리 제품·연구 정체성*. **두 종류의 강건성** 이 핵심:
+- **(2a) DB 강건성** — 사용자가 description/sample query 없이 등록해도 성능 하락 최소화
+- **(2b) 시멘틱 강건성** — 팀별 정의 차이를 *충돌 없이 공존* (git-like 브랜칭)
+
+V1엔 골격만, V1.5/V2에서 깊이 채움.
+
+## 1.4 타이브레이커 (충돌 시 우선순위)
+
+1. **무결성 + 권한** — DB가 변하지 않고, 권한 있는 데이터만 본다
+2. **의미적 정확성** — 답이 *진짜로* 맞는다
+3. **UX 단순성** — 한 번에 결과 (멘션→thread, 또는 다른 frontend 의 동치 패턴)
+4. **맥락 보존** — 끊겨도 이어진다 (Hermes 영속화)
+
+---
+
+# Chap 2. 아키텍처 — ASCII로 보는 큰 그림
+
+## 2.1 전체 흐름
+
+```
+   USER  (Phase 1: Discord. Phase 2+: Slack/Web/Teams)
+       │
+       ▼
+┌─────────────────────────────────────────────────────────┐
+│  ★ Frontend 어댑터  (인터페이스 분리)                       │
+│                                                           │
+│   discord/  ──┐                                           │
+│   slack/   ──┤   각 어댑터가 공통 인터페이스 구현            │
+│   web/     ──┘   - 입력 받기                               │
+│                  - 출력 보내기                              │
+│                  - 세션 키 결정                             │
+└──────────────────┬──────────────────────────────────────┘
+                   ▼
+┌─────────────────────────────────────────────────────────┐
+│  MEMORY + CONCIERGE                                      │
+│                                                           │
+│   기억 (Memory) — 3축 분리                                 │
+│     • 어디 저장하는가                                       │
+│     • 무엇을 가져올지                                       │
+│     • 어떻게 새로 만드는지                                  │
+│                                                           │
+│   문서 흡수 (Ingestion) — 출처 × 해석                       │
+│     • 어디서 문서를 받는가 (파일/URL/Notion ...)             │
+│     • 어떻게 metric/rule 을 뽑아낼지                         │
+│                                                           │
+│   시멘틱 federation — scope 결정                            │
+│     • 이 대화가 어느 scope 인가 (DM/채널/스레드)             │
+│     • 같은 용어 다른 정의 시 어느 게 우선인가                 │
+│                                                           │
+│   ContextConcierge — 위 셋을 묶어 ctx 조립                   │
+└──────────────────┬──────────────────────────────────────┘
+                   ▼ ctx
+┌─────────────────────────────────────────────────────────┐
+│  ★ HARNESS  (조립된 단위, 하나의 덩어리)                    │
+│                                                           │
+│   ctx 안에 있는 것:                                        │
+│     • LLM 클라이언트                                       │
+│     • 도구들 (run_sql, ingest_doc, ...)                    │
+│     • semantic (scope-aware)                              │
+│     • session (영속 conversation + facts)                  │
+│     • safety pipeline                                      │
+│     • DB explorer                                          │
+│     • audit logger                                         │
+│                                                           │
+│   agent_loop:                                              │
+│     1. system prompt 만들기                                 │
+│        - 현재 scope 의 effective semantic 주입               │
+│        - 관련 facts 주입                                    │
+│        - DB schema 주입                                     │
+│     2. LLM 호출                                            │
+│     3. 도구 호출 결과 모으기                                 │
+│     4. 다음 턴 또는 종료                                    │
+│                                                           │
+│   run_sql 도구 내부:                                        │
+│     ★ safety pipeline 통과 후 실행                          │
+│        layer 1 → 2 → 3 → ...                              │
+└──────────────────┬──────────────────────────────────────┘
+                   ▼
+┌─────────────────────────────────────────────────────────┐
+│  OUTBOUND ADAPTERS                                       │
+│   LLM · DB (asyncpg) · Storage (encrypted SQLite)         │
+└─────────────────────────────────────────────────────────┘
+```
+
+★ 4개가 **확장 핵심** — Chap 3에서 자세히.
+
+## 2.2 디렉토리 구조
+
+```
+lang2sql/
+├── README.md
+├── pyproject.toml
+│
+├── src/lang2sql/
+│   ├── core/                      # 순수 타입 + 포트(추상)
+│   │   ├── types.py
+│   │   ├── identity.py
+│   │   └── ports/
+│   │       ├── llm.py
+│   │       ├── explorer.py
+│   │       ├── tool.py
+│   │       ├── secrets.py
+│   │       ├── audit.py
+│   │       ├── session_store.py
+│   │       ├── frontend.py        ← NEW (Phase 분리)
+│   │       ├── safety.py          ← Safety layer
+│   │       ├── memory.py          ← Memory 3축
+│   │       ├── ingestion.py       ← Document source × extractor
+│   │       └── semantic_scope.py  ← NEW (Federation)
+│   │
+│   ├── harness/                   # 조립된 단위
+│   │   ├── context.py
+│   │   ├── session.py
+│   │   ├── loop.py
+│   │   ├── system_prompt.py
+│   │   └── tool_registry.py
+│   │
+│   ├── semantic/                  # 도메인 모델 + scope 지원
+│   │   ├── types.py               # Metric/Dimension/Relationship/Rule
+│   │   ├── layer.py
+│   │   ├── scoped_layer.py        ← NEW (git-like 분기)
+│   │   ├── sql_composer.py
+│   │   └── store.py
+│   │
+│   ├── safety/                    # ★ Safety pipeline (체인)
+│   │   ├── pipeline.py
+│   │   └── layers/
+│   │
+│   ├── memory/                    # ★ 3축 분리
+│   │   ├── service.py
+│   │   ├── stores/
+│   │   ├── recall/
+│   │   └── extractors/
+│   │
+│   ├── ingestion/                 # ★ 출처 × 해석 매트릭스
+│   │   ├── pipeline.py
+│   │   ├── sources/
+│   │   └── extractors/
+│   │
+│   ├── tools/                     # ctx-aware
+│   │   ├── run_sql.py
+│   │   ├── explore_schema.py
+│   │   ├── define_metric.py       # scope 인지
+│   │   ├── ingest_doc.py
+│   │   ├── remember.py
+│   │   └── ask_user.py
+│   │
+│   ├── tenancy/
+│   │   ├── concierge.py
+│   │   └── encrypted_secrets.py
+│   │
+│   ├── frontends/                 # ★ 인터페이스 분리
+│   │   ├── discord/               # Phase 1
+│   │   ├── slack/                 # Phase 2 (디렉토리만 비워둠)
+│   │   ├── web/                   # Phase 3
+│   │   └── cli/                   # 개발 도구
+│   │
+│   └── adapters/                  # outbound
+│       ├── llm/openai_.py
+│       ├── db/postgres_explorer.py
+│       └── storage/encrypted_sqlite.py
+│
+├── tests/
+└── docs/
+```
+
+---
+
+# Chap 3. 확장성 — 4개의 패턴
+
+## 3.1 왜 패턴인가
+
+V1엔 *가장 단순한 1개씩만* 구현, V1.5/V2에서 *어댑터를 추가* 하는 방식으로 확장. 핵심 가치: **V1엔 단순 구현으로 동작하지만 추상은 박혀 있어서 새 구현을 끼울 때 기존 코드 안 건드림**.
+
+비유로 풀면 — *콘센트와 가전제품*. V1엔 LED 전구 하나만 꽂혀 있어도, 콘센트 규격이 표준이라 V1.5에 선풍기·스마트조명 그냥 꽂으면 됨. 콘센트 자체를 다시 만들 일 없음.
+
+| ★ | 이름 | 역할 |
+|---|---|---|
+| ① | Safety pipeline | DB 강건성 — *검사 layer 줄* 에 SQL 을 통과시킴, layer 추가식 확장 |
+| ② | Memory service | Hermes 기억 — *어디 저장/무엇을 가져올지/어떻게 만들지* 3축 독립 진화 |
+| ③ | Ingestion pipeline | 문서 흡수 — *출처 × 해석* 매트릭스로 입력 다양화 |
+| ④ | **Semantic federation** | **시멘틱 강건성 — git-like 팀별 분기** |
+
+## 3.2 ★ ① Safety pipeline — DB 강건성의 모이는 곳
+
+### 개념
+
+SQL이 실행되기 전에 *검사 layer 들의 줄* 을 차례로 통과. 각 layer 는 통과/차단/사용자 확인 요청/SQL 수정 중 하나를 결정.
+
+비유 — *공항 보안 검색대*. 가방을 X-ray 통과 → 금속탐지 → 액체 검사 → 라벨 검사. 한 단계라도 막히면 통과 불가. 새 검사항목 (예: 화학물질 탐지) 추가는 *기존 단계 그대로 둔 채 검색대 줄에 한 칸 끼우기*.
+
+### 단계별 진화
+
+| 버전 | 줄에 있는 layer |
+|---|---|
+| **V1** (껍데기) | (1) Whitelist — SELECT/WITH 로 시작해야만 통과 (2) Timeout 설정 — 30초 |
+| **V1.5** | + AST 정밀 검증 (CTE 안 INSERT 도 잡음) + 위험 함수 차단 (pg_sleep 등) + LIMIT 자동 부착 + 5개 PG 설정 일괄 적용 + Rate limit + **메타데이터 자동 보강** (description 없는 컬럼 자동 생성) |
+| **V2** | + 비용 게이트 (EXPLAIN 으로 예상 비용 평가, 임계 초과 시 사용자 확인) + 엔진별 별도 pipeline (PG vs BigQuery) |
+
+V1.5 의 **메타데이터 자동 보강** layer 가 *DB 강건성 차별점의 핵심*. 사용자 DB에 description 빈 칸이면 LLM이 채워줌. 채워진 description 은 시멘틱 레이어로 흘러가 다음 질문에 활용. *Vanna 가 학습 데이터 품질에 의존* 하는 약점을 *자동 보강* 으로 메움.
+
+새 layer 추가는 *클래스 한 개 + 줄에 끼우기*. `run_sql` 도구 코드 변경 0.
+
+## 3.3 ★ ② Memory service — Hermes 기억의 3축 분리
+
+### 개념
+
+기억은 *하나의 큰 상자* 가 아니라 **세 가지 독립 기능의 조합**:
+
+| 축 | 역할 |
+|---|---|
+| **Store (저장소)** | facts 를 어디에 보관하는가 (메모리/SQLite/PostgreSQL/Redis ...) |
+| **Recall (불러오기 전략)** | 현재 질문에 어떤 facts 를 가져올지 (전부/키워드 매칭/벡터 유사도/하이브리드) |
+| **Extractor (새 fact 만들기)** | 새 facts 를 어떻게 생성할지 (사용자 명시 명령만 / LLM이 대화에서 자동 추출) |
+
+각 축이 독립적으로 진화. 예: Store 만 더 큰 DB로 교체 가능. Recall 만 더 똑똑하게 교체 가능.
+
+### 단계별 진화
+
+| 버전 | Store | Recall | Extractor |
+|---|---|---|---|
+| **V1** | 메모리 안 dict | 모든 facts 매번 주입 | `/remember` 명령만 |
+| **V1.5** | SQLite 영속 | 키워드 매칭으로 관련 facts 만 | LLM이 대화에서 반복 패턴 추출 |
+| **V2** | (같음) | 벡터 유사도 (embedding) | + 충돌 해결 (사용자가 X 했다가 not-X 시) |
+| **V2.5** | PostgreSQL (멀티 인스턴스) | 하이브리드 (키워드 + 벡터 + 최근성) | + 신뢰도 점수 |
+
+V1엔 가장 단순한 조합 (메모리 + 전부 주입 + 수동) 으로 시작하되 *3축 추상* 은 박혀 있음. V1.5에 Store 만 SQLite 로 교체하는 게 *어댑터 1개 추가* 로 끝.
+
+## 3.4 ★ ③ Ingestion pipeline — 문서 → 시멘틱 레이어
+
+### 개념
+
+문서가 들어오면 두 단계:
+
+| 단계 | 역할 |
+|---|---|
+| **Source (출처)** | 어디서 문서를 가져오는가 (파일 업로드/URL/Notion/Confluence/Google Drive) |
+| **Extractor (해석)** | 문서 텍스트에서 metric/dimension/rule 후보를 어떻게 뽑아내는가 (LLM/DDL 파싱/하이브리드) |
+
+Source 와 Extractor 가 *매트릭스* 라서 *Source 1개 추가 = N 개 Extractor 와 자동 결합*.
+
+### 사용자 흐름 (V1)
+
+1. 사용자가 Discord 에 `/ingest` 와 함께 매출 정의 문서를 첨부
+2. 봇이 파일 내용을 가져와서 LLM 에 *"이 문서에서 metric/dimension/rule 을 찾아줘"* 라고 요청
+3. LLM 이 후보들을 추출 (예: "total_revenue = SUM(orders.amount) WHERE status != 'cancelled'")
+4. 봇이 Discord embed 로 사용자에게 보여줌:
+   - 📊 METRIC: total_revenue → SUM(orders.amount)
+   - 📋 RULE: exclude_cancelled (total_revenue 에 적용) → status != 'cancelled'
+   - [✅ 모두 등록] [개별 선택] [❌ 취소]
+5. 사용자 ✅
+6. 시멘틱 레이어에 등록 (출처 문서 ID 같이 보존)
+7. 이후 *"이번 달 매출"* 질문 시 자동으로 위 정의가 적용됨
+
+### 단계별 진화
+
+| 버전 | Sources | Extractors |
+|---|---|---|
+| **V1** | 파일 업로드 (MD/PDF/TXT) | LLM 추출 |
+| **V1.5** | + URL 가져오기 | + DDL 파일 직접 파싱 (schema 파일에서 자동 추출) |
+| **V2** | + Notion / Confluence MCP | + 하이브리드 (LLM + 규칙) |
+| **V2.5** | + GitHub Markdown / Google Drive MCP | + 청크 기반 RAG (긴 문서) |
+
+V1.5엔 같은 문서를 다시 업로드하면 *변경된 부분 diff* 표시 → 사용자가 update/keep/remove 선택. 즉 **문서가 곧 단일 진실 소스** 패턴.
+
+## 3.5 ★ ④ Semantic federation — Git-like 시멘틱 분기
+
+### 왜 필요한가
+
+같은 회사라도 팀별로 *같은 용어, 다른 의미* 가 흔함:
+
+| 용어 | 마케팅 | 프로덕트 | 파이낸스 |
+|---|---|---|---|
+| 활성 사용자 | 30일 내 로그인 | 7일 내 핵심 액션 | 유료 구독자 |
+| 매출 | 광고 매출 | (관심 없음) | net (환불 차감) |
+| 유저 | 가입자 | 활성자 | 결제자 |
+
+기존 오픈소스는 *단일 진실 (single truth)* 모델:
+- Wren MDL: 회사 단일 정의, 수동 유지 → 한 팀이 바꾸면 다른 팀 깨짐
+- Vanna: 학습 데이터 혼선 → 의미 충돌이 RAG 결과에 섞임
+
+결국 *팀별로 자체 봇 운영* 으로 갈라지거나, *모든 팀이 같은 정의에 합의* 해야 함 (실현 불가).
+
+### 우리의 해결 — git 처럼 브랜치를 가져감
+
+```
+                          builtin (시스템 기본 = 비어 있음)
+                              │
+                              ▼
+                       ┌──────────────┐
+                       │  main 브랜치  │ ← 회사 공통 시멘틱 (canonical)
+                       │  (guild)      │   admin 이 등록
+                       └──────┬───────┘
+                              │ 상속
+              ┌───────────────┼───────────────┐
+              ▼               ▼               ▼
+       ┌──────────┐    ┌──────────┐    ┌──────────┐
+       │#marketing│    │ #product │    │ #finance │
+       │ 채널 브랜치│   │ 채널 브랜치│   │ 채널 브랜치│
+       │          │    │          │    │          │
+       │active_   │    │active_   │    │revenue=  │
+       │user=30d  │    │user=7d   │    │net       │
+       └──────────┘    └──────────┘    └──────────┘
+              │
+              │ 상속
+              ▼
+       ┌──────────────────┐
+       │ thread 브랜치     │ ← 일시적 정의 (분석 1건 동안만)
+       │                   │
+       │experiment_       │
+       │arm=treatment_b   │
+       └──────────────────┘
+```
+
+### 어떻게 동작하나 — 가장 구체적인 scope 가 이김
+
+사용자가 `#marketing` 채널에서 *"활성 사용자 수"* 라 물으면 봇은 시멘틱을 찾기 위해 *아래에서 위로* 순회:
+1. 현재 thread 안에 정의가 있는가? → 없음
+2. `#marketing` 채널에 정의가 있는가? → 있음 (*"30일 내 로그인"*) → **여기서 멈춤**
+
+같은 사용자가 `#product` 채널에서 같은 질문:
+1. thread → 없음
+2. `#product` 채널 → 있음 (*"7일 내 핵심 액션"*) → 여기서 멈춤
+
+두 채널 모두 자기 정의를 사용. **충돌 없음** — 각자 자기 scope 에서 산다.
+
+### 사용자 흐름
+
+`#marketing` 채널에서 새 정의 등록:
+- 사용자: `/define_metric active_user "30일 내 로그인"`
+- 봇: ✅ 채널 scope 에 등록 (기본 동작)
+- 효과: `#marketing` 에서만 적용. 다른 채널은 그대로.
+
+`#finance` 채널에서 다른 정의 등록:
+- 사용자: `/define_metric revenue "net (환불 제외)"`
+- 봇: ✅ 채널 scope
+
+admin 이 회사 공통 등록:
+- admin: `/define_metric --guild revenue "gross + tax included"`
+- 봇: ✅ main 브랜치 등록
+- 효과: 다른 채널엔 영향, finance 채널엔 자체 override 가 우선
+
+현재 scope 의 effective 시멘틱 조회:
+- 사용자: `/semantic show`
+- 봇: *"이 채널에서 사용 중인 정의들:*
+  - *active_user (채널 override): 30일 내 로그인*
+  - *revenue (회사 main): gross + tax*
+  - *..."*
+
+이 채널이 main 과 다른 점:
+- 사용자: `/semantic diff main` (V1.5 기능)
+- 봇: *"이 채널이 main 과 다른 정의 1개: active_user 만 override"*
+
+채널 정의를 main 으로 승격 제안:
+- 사용자: `/semantic promote active_user` (V1.5 기능)
+- 봇: *"admin 승인 요청 전송됨"*
+
+### 단계별 진화
+
+| 버전 | 기능 |
+|---|---|
+| **V1** | 3-scope (guild / channel / thread) 자동 resolution. `/define_metric` 은 현재 scope 기본. `/semantic show` 로 effective layer 조회 |
+| **V1.5** | `/semantic diff main`, `/semantic promote` (admin 승인 flow), 충돌 알림 (admin 이 main 바꾸면 override 채널에 통지) |
+| **V2** | 외부 git 저장소 동기화 (semantic-as-code: .yaml 로 export/import), cross-guild template 공유 |
+| **V2.5** | branch fork & merge UI, 충돌 해결 flow, scope 별 audit (누가 언제 정의 바꿨나) |
+
+### 의미 — *시멘틱 강건성* 이라는 새 축
+
+이건 **DB 강건성과는 다른 축의 강건성**:
+
+| 축 | 무엇에 견디는가 | 어떻게 |
+|---|---|---|
+| **(2a) DB 강건성** | *불완전한 메타데이터* | Safety pipeline 의 메타데이터 보강 layer + auto description |
+| **(2b) 시멘틱 강건성** | *조직별 다른 비즈니스 정의* | Git-like scope chain (federation) |
+
+둘 다 *"현실의 messy함에 강건"* 이라는 큰 우산. **둘 다 Vanna/Wren 이 못 하는 영역**:
+
+| | Vanna | Wren | **Lang2SQL** |
+|---|---|---|---|
+| DB 메타데이터 부족 시 동작 | ❌ 학습 데이터 의존 | ❌ MDL 사전 정의 필수 | ✅ 자동 보강 |
+| 팀별 다른 정의 공존 | ❌ RAG 혼선 | ❌ 단일 MDL | ✅ Scope chain |
+
+## 3.6 V1 에 박을 추상 (정리)
+
+V1엔 추상만 박고 단순 구현. 코어 변경 없이 V1.5에 어댑터 추가:
+
+- 추상 (port/interface) 들이 들어갈 위치: `core/ports/safety.py`, `memory.py`, `ingestion.py`, `semantic_scope.py`, `frontend.py`
+- 각 추상의 V1 단순 구현 1~2개씩만 (Safety: layer 2개, Memory: 단순 3축 조합, Ingestion: 파일+LLM, Federation: SQLite 기반 3-scope)
+
+추상 비용: 약 +400 LOC.
+V1.5/V2 절감: 약 1,500 LOC.
+*초기 투자가 빠르게 회수*.
+
+---
+
+# Chap 4. V1 walking skeleton
+
+## 4.1 V1 에 들어가는 것
+
+| 영역 | V1 |
+|---|---|
+| Frontend | Phase 1: Discord (DM + 채널 @bot 멘션→thread + thread reply) |
+| 명령 | `/connect`, `/ingest <파일>`, `/define_metric <name> "<def>"`, `/remember "..."`, `/semantic show`, `/audit me` |
+| LLM | OpenAI `gpt-4.1-mini` 단일 |
+| DB | PostgreSQL only |
+| 응답 | 텍스트 (≤50행) 또는 CSV 첨부 (>50행) |
+| Safety | Safety pipeline + V1 layer 2개 (Whitelist + Timeout) |
+| Memory | Memory service + V1 (메모리 + 전부 주입 + 수동) |
+| Ingestion | 파일 업로드 + LLM 추출 |
+| **Semantic federation** | **3-scope resolution (guild/channel/thread). `/define_metric` 현재 scope 기본. `/semantic show` 로 effective layer 조회.** |
+| 영속화 | secrets / audit / sessions / facts / semantic_entries → SQLite |
+| 도구 | run_sql · explore_schema · ingest_doc · define_metric (scope 인지) · remember · ask_user |
+| 호스팅 | Oracle Cloud Always Free 또는 fly.io free |
+
+## 4.2 V1 에 *안* 들어가는 것
+
+| 항목 | 미루는 곳 | 이유 |
+|---|---|---|
+| `run_code`/`write_code` (Python 실행) | **영구 삭제** | read-only 약속을 무력화 |
+| Discord-native 강조 패턴 (safety embed / metadata ask / reactions / #audit channel) | V1.5 | 사용자 워크플로우 다듬는 영역, 트라이얼 피드백 후 결정 |
+| 비용 게이트 (EXPLAIN) | V1.5 | L1 + L0 timeout 1차 충분 |
+| 위험 함수 차단 (pg_sleep 등) | V1.5 | Whitelist 가 1차 방어 |
+| 메타데이터 자동 보강 (auto description) | V1.5 | DB 강건성 핵심 layer — V1엔 추상만, 구현은 V1.5 |
+| Rate limit | V1.5 | 트라이얼 두 자릿수 |
+| 자동 fact 추출 | V1.5 | 수동 `/remember` 로 시작 |
+| `/semantic diff` / `/semantic promote` | V1.5 | 3-scope resolution 동작 검증 후 추가 |
+| URL/Notion 문서 입력 | V1.5 / V2 | 파일 업로드 하나로 시작 |
+| 벡터 유사도 recall | V2 | facts 적을 땐 효과 미미 |
+| Persistent View / streaming / PNG 분할 | V1.7 | Discord SDK 깊은 영역 |
+| Anthropic / NIM | V1.5 (검증 후) | OpenAI 하나로 시작 |
+| Slack / Web 어댑터 | Phase 2/3 | 추상은 V1에 박힘 |
+| Audit hash chain | V2 | append-only SQLite 1차 충분 |
+| `visualize` (PNG 차트) | V1.7 | CSV 첨부로 충분 |
+| Scope 별 audit (누가 언제 정의 바꿨나) | V2 | semantic_entries 에 created_by/created_at 만 V1 |
+
+## 4.3 V1 LOC 추정
+
+| 영역 | LOC |
+|---|---|
+| core | ~650 (ports + types + identity + semantic_scope/frontend port) |
+| harness | ~700 |
+| semantic | ~700 (types, layer, scoped_layer, sql_composer, store) |
+| safety | ~250 (pipeline + 2 layers) |
+| memory | ~350 (service + 3 simple impls) |
+| ingestion | ~300 |
+| tools | ~750 (6 tools — define_metric 가 scope 인지) |
+| tenancy | ~400 |
+| frontends/discord | ~800 (adapter, bot, commands 6개, session_router, render) |
+| adapters | ~500 |
+| tests | ~950 |
+| **총 V1** | **~6,350 LOC 신규** |
+
+## 4.4 일정 — 4.5~5주 솔로
+
+| 주차 | 작업 |
+|---|---|
+| **Week 1** | core 포트 정의 + HarnessContext, Session, agent_loop. cli 어댑터로 단위 검증 |
+| **Week 2** | semantic (scoped layer 포함) + safety pipeline + 첫 도구들 (run_sql, explore_schema, define_metric) + OpenAI/PG/SQLite 어댑터. safety 회귀 12개 |
+| **Week 3** | memory + ingestion + 나머지 도구 (ingest_doc, remember, ask_user) + tenancy (concierge, secrets, factstore, scope_resolver) |
+| **Week 4** | Discord 어댑터 (bot, 명령 6개, session_router, render). 동의 button view 등 |
+| **Week 5** | polish, e2e, README, DEPLOY 가이드, bench/ 데모 1개, CI YAML, 첫 길드 배포 |
+
+## 4.5 회귀 12개 (V1 CI gate)
+
+V1 의 Whitelist + Timeout 만으로 충분히 막혀야 하는 12개 회귀 케이스:
+
+| # | 입력 | 기대 |
+|---|---|---|
+| 1 | `DROP TABLE users` | 차단 |
+| 2 | `; DELETE FROM t; --` | 차단 (multi-stmt) |
+| 3 | `INSERT INTO t VALUES (1)` | 차단 |
+| 4 | `UPDATE t SET x=1` | 차단 |
+| 5 | `WITH x AS (INSERT INTO t ...) SELECT * FROM x` | 차단 (INSERT 키워드 fail-closed) |
+| 6 | `SELECT * FROM nonexistent` | PG error (gate 통과, 실행 단계 실패) |
+| 7 | `SELECT pg_sleep(60)` | 30초 timeout |
+| 8 | `SELECT * FROM huge_table` (50k rows) | row_limit 1000 으로 truncate |
+| 9 | `SELECT 1` | 통과 |
+| 10 | `WITH a AS (SELECT 1) SELECT * FROM a` | 통과 |
+| 11 | `EXPLAIN SELECT 1` | 통과 |
+| 12 | 빈 문자열 | 차단 (parse_error) |
+
+V1.5 에 AST 정밀 검증 + 함수 차단 + 메타데이터 보강이 들어오면 추가 회귀:
+- schema-qualified bypass (`public.pg_sleep`)
+- `COPY ... TO PROGRAM`
+- `EXPLAIN ANALYZE DELETE`
+
+---
+
+# Chap 5. 의견 정리
+
+## 5.1 왜 이 설계가 작동할 거라 보는가
+
+**(1) "오픈소스의 정체성" 이 차별점에 부합**
+
+Vanna/Wren/SQLCoder 가 *질문→SQL* 은 잘 풀고 있음. *"GPT-4 보다 더 좋은 SQL을 만든다"* 로 경쟁하면 모델 fine-tuning 싸움 — 우리 영역 아님.
+
+대신 우리는 **네 가지 조합** 으로 차별:
+- 문서로 비즈니스 맥락 학습
+- 팀별 시멘틱 federation (git-like)
+- 불완전 DB에서도 동작
+- 모든 정의·대화 기억
+
+이 조합은 기존 오픈소스에 *없음*.
+
+**(2) 강건성을 *두 축* 으로 분리한 게 깊이**
+
+기존엔 *"DB 강건성"* 만 봤는데, 라이브 사용해 보면 *"팀별 정의 충돌"* 이 더 자주 터지는 문제. *시멘틱 강건성* 을 별도 축으로 명시한 것 자체가 새로움.
+
+**(3) 4개 패턴이 *연구→제품* 토대**
+
+DB 강건성 차별화는 *"description 없으면 자동 생성"* 같은 *상황별 커스텀 전략* 의 모음. Safety pipeline 의 layer 로 들어옴.
+시멘틱 강건성은 *"팀별 다른 정의"* 의 federated 관리. Scoped semantic layer 로 들어옴.
+연구자가 *Hint Vector* 같은 *DB 구조 강건성* 을 추가하고 싶으면 layer 1개로 됨. *연구→제품* 흐름 자연스러움.
+
+**(4) Discord 는 *Phase 1 인터페이스* 일 뿐**
+
+정체성에 Discord 가 박혀 있으면 위험. v4.1 은 frontend 추상으로 분리. Phase 2 Slack 추가 시 코어 변경 0줄. *오픈소스* 정체성과도 부합 — *플랫폼 lock-in 없음*.
+
+## 5.2 한계와 trade-off (정직)
+
+| 한계 | 영향 | 대응 |
+|---|---|---|
+| 의미적 정확성 정량 평가 부재 | *"안전하게 틀린 답"* 위험 | V1.5 에 골든 query set + 답 출처 표시 |
+| LLM 비용 노출 | 토큰 폭주 시 사용자 비용 | V1.5 rate limit + per-user 토큰 cap |
+| 첫 출하까지 4.5~5주 | 빠른 검증 어려움 | walking skeleton, wipe 라 4주 미만 무리 |
+| 추상 비용 V1 LOC +400 | 일정 부담 | V1.5/V2 에서 ~1,500 LOC 절감 (흑자) |
+| 시멘틱 충돌 해결 UI 부재 (V1) | admin 이 main 바꿔도 channel override 우선 — 사용자 혼선 가능 | V1.5 `/semantic diff` + 알림 |
+| 의미 추출 LLM 환각 | 문서에서 잘못된 metric 추출 | 사용자 confirm 1차 방어, V1.5 검증 layer |
+| 메모리 안 recall (V1) | facts 많아지면 토큰 폭증 | V1.5 키워드 recall, V2 벡터 recall |
+| frontend 어댑터 추가 비용 | Slack/Web 각 ~1,000 LOC | Phase 2/3 단계 적용 |
+
+## 5.3 비교 — 기존 오픈소스 대비 위치
+
+| 영역 | Vanna AI | Wren AI | SQLCoder | **Lang2SQL (우리)** |
+|---|---|---|---|---|
+| 자연어 → SQL | ✅ RAG | ✅ MDL | ✅ fine-tuned | ✅ RAG + 시멘틱 + harness |
+| DB 직접 연결 | ✅ | ✅ | ✅ | ✅ |
+| Semantic layer | ❌ | ✅ (수동 MDL) | ❌ | ✅ (**문서 자동 추출**) |
+| **시멘틱 federation (팀별 분기)** | ❌ | ❌ | ❌ | ✅ (**git-like 3-scope**) |
+| **DB 메타데이터 자동 보강** | ❌ | ❌ | ❌ | ✅ (V1.5 보강 layer) |
+| 대화 기억 | ❌ | ❌ | ❌ | ✅ (Hermes) |
+| 멀티유저 협업 | 2.0 추가 | enterprise BI | ❌ | ✅ (Discord thread, frontend 추상) |
+| Frontend 종류 | Web UI | Web UI | CLI | **Discord/Slack/Web (어댑터)** |
+| 확장 모델 | 단일 아키텍처 | enterprise platform | 단일 LLM | **4가지 패턴 (chain/strategy/scope)** |
+
+**위치 요약**: *Vanna 의 자연어→SQL + Wren 의 시멘틱 + 우리만의 (문서 자동 추출 + git-like 팀 federation + DB/시멘틱 두 축 강건성 + Hermes 기억 + 멀티 인터페이스)*.
+
+## 5.4 한 줄
+
+> **"문서를 넣어 비즈니스 맥락을 학습시키고, 팀별로 시멘틱이 분기되고, DB가 불완전해도 견디고, 모든 정의·대화를 기억하는 오픈소스 분석 에이전트. Phase 1 은 Discord, 그 다음은 Slack·Web."**
+
+---
+
+# 결정 필요 사항
+
+V1 착수 전 답이 있으면 좋은 항목:
+
+1. **첫 배포 Discord 길드** — 본인 테스트 / 가짜연구소 / 기타?
+2. **OpenAI API 키** — 본인 / 팀?
+3. **레포 이름** — `lang2sql/` 유지 + 새 브랜치 (`feature/v4-rebuild`) 권고
+4. **첫 데모 시나리오** — bench/ 에 들어갈 *완성된 use case* 1개. 예: "이커머스 매출 분석 — 4 테이블, 3 metric, 1 문서, 5개 질문, 마케팅 채널 vs 파이낸스 채널에서 다른 정의로 같은 질문"
+5. **`/define_metric` 디폴트 scope** — channel (권고) vs DM 발생 시 personal vs admin 명시 강제?
+6. **NIM 도입 시점** — V1.5 contract test 후 / V2 보류?
+
+답해 주시면 v4.1-final 마무리하고 Week 1 부터 시작.
+
+— end —
diff --git a/docs/discord_first_redesign_v4_2.md b/docs/discord_first_redesign_v4_2.md
new file mode 100644
index 0000000..891e1b4
--- /dev/null
+++ b/docs/discord_first_redesign_v4_2.md
@@ -0,0 +1,284 @@
+# Lang2SQL v4.2 — 컨셉과 아키텍처
+
+> **작성일**: 2026-05-18
+> **결정자**: ryan@brain-crew.com
+> **상태**: 컨셉 확정 단계.
+
+---
+
+# Chap 1. 정체성
+
+## 1.1 기존 오픈소스의 공통 한계
+
+Vanna AI(~20k), Wren AI(~12k), SQLCoder(~3.8k) 같은 Text-to-SQL 오픈소스들은 *질문→SQL 파이프라인 자체* 는 이미 완성도 높음. 그러면 우리는 *그 위에 무엇을 더 얹을* 것인가가 정체성 결정.
+
+기존 오픈소스의 **공통 약점**:
+
+| 약점 | 기존 처리 |
+|---|---|
+| **DB 정보 완성도 낮으면 성능 급락** | Vanna: 학습 데이터 품질 의존 |
+| **이전 대화·정의 못 기억** | 대부분 stateless |
+| **비즈니스 맥락은 사람이 직접 정의** | Wren: MDL 수동 작성 |
+| **단일 진실 모델의 조직 충돌** | 팀별 정의 차이 → 혼선 |
+
+이 네 가지가 *실무에서 매우 중요* 한데 *비즈니스마다 다르기 때문에 정량 평가가 어려운 영역*. 그래서 오픈소스가 잘 안 건드림. 우리는 **이 네 가지를 한 번에 다루는 방향** 으로 차별화.
+
+## 1.2 우리의 한 줄 컨셉
+
+> **"문서로 비즈니스 맥락을 학습하고, 팀별로 시멘틱이 분기되고, 불완전한 DB에서도 답하고, 모든 정의·대화를 기억하는 오픈소스 분석 에이전트."**
+
+기존 SQL 봇이 *"질문하면 SQL 만들어 줄게"* 였다면, 우리는 *"우리 회사 문서 넣어줘 → 학습할게 → 팀별로 다른 정의도 같이 들고 있을게 → 너희가 묻고 답을 받자 → 다 기억하고 다음에도 적용할게"*.
+
+**Discord 는 Phase 1 인터페이스**. Slack/Teams/Web 도 같은 코어 위에서 어댑터로 추가 가능.
+
+## 1.3 4기둥 (Pillars)
+
+| 기둥 | 정체성 | 차별점 |
+|---|---|---|
+| **① 비즈니스 맥락 학습** | 문서→시멘틱 자동 추출 + 사용자 confirm | Wren MDL 은 수동. 우리는 *문서가 곧 진실의 출처* |
+| **② DB 강건성** | 불완전 메타데이터를 *자동 보강* (description 자동 생성, FK 추정, 샘플 profile 등) | Vanna 는 *학습 데이터 의존*. 우리는 *DB가 깨끗하지 않아도 동작* |
+| **③ Hermes 기억** | conversation + facts + preferences 영속 | 대부분 stateless |
+| **④ 멀티 인터페이스** | Phase 1: Discord, Phase 2: Slack, Phase 3: Teams, Phase 4: Web | Discord 는 *어댑터 하나*, lock-in 없음 |
+
+기둥 ② 가 **진짜 차별점**. *Vanna 의 한 포인트 한계 보완* 이 정체성. 부수적으로 **시멘틱 강건성 (팀별 다른 정의 federation)** 이 같이 들어옴.
+
+## 1.4 타이브레이커 (충돌 시 우선순위)
+
+1. **무결성 + 권한**
+2. **의미적 정확성**
+3. **UX 단순성**
+4. **맥락 보존**
+
+---
+
+# Chap 2. 아키텍처
+
+## 2.1 전체 흐름
+
+```
+   USER  (Phase 1: Discord)
+       │
+       ▼
+┌─────────────────────────────────────────────────────────┐
+│  Frontend 어댑터  (Phase 분리)                            │
+│   discord/  slack/  teams/  web/  cli/                    │
+└──────────────────┬──────────────────────────────────────┘
+                   ▼
+┌─────────────────────────────────────────────────────────┐
+│  MEMORY + CONCIERGE                                      │
+│                                                           │
+│   기억 (★②) — 어디 저장 / 무엇을 가져올지 / 어떻게 만들지   │
+│   문서 흡수 (★③) — 출처 × 해석                            │
+│   시멘틱 federation (★④) — scope 분기                     │
+│   DB 강건성 (★①) — 메타데이터 자동 보강                    │
+│                                                           │
+│   ContextConcierge — 위 넷을 묶어 ctx 조립                 │
+└──────────────────┬──────────────────────────────────────┘
+                   ▼ ctx
+┌─────────────────────────────────────────────────────────┐
+│  HARNESS  (조립된 단위, 하나의 덩어리)                     │
+│   • LLM 클라이언트                                         │
+│   • 도구들 (run_sql, ingest_doc, ...)                      │
+│   • semantic (scope-aware + 보강된 상태)                    │
+│   • session (영속 conversation + facts)                    │
+│   • DB explorer                                            │
+│   • audit logger                                           │
+│                                                           │
+│   agent_loop:                                              │
+│     prompt = system_prompt(ctx)                            │
+│       (effective semantic + facts + 보강된 schema 주입)     │
+│     LLM 호출 → 도구 호출 → 다음 턴 또는 종료                 │
+└──────────────────┬──────────────────────────────────────┘
+                   ▼
+┌─────────────────────────────────────────────────────────┐
+│  OUTBOUND ADAPTERS                                       │
+│   LLM · DB (asyncpg) · Storage (encrypted SQLite)         │
+└─────────────────────────────────────────────────────────┘
+```
+
+★ 4개가 **확장 핵심** — Chap 3 에서.
+
+## 2.2 디렉토리 구조
+
+```
+lang2sql/src/lang2sql/
+├── core/                  ports (추상)
+├── harness/               agent_loop, ctx
+├── semantic/              types, scoped_layer, sql_composer
+├── robustness/            ★① pipeline + enrichers/
+├── memory/                ★② service + stores/recall/extractors/
+├── ingestion/             ★③ pipeline + sources/extractors/
+├── tools/                 ctx-aware (run_sql, ingest_doc, ...)
+├── tenancy/               concierge, encrypted_secrets
+├── frontends/             ★ Phase 분리 (discord/slack/teams/web/cli)
+└── adapters/              llm, db, storage
+```
+
+---
+
+# Chap 3. 확장성 — 4개의 ★ 패턴
+
+V1엔 *가장 단순한 1개씩만* 구현, V1.5/V2 에서 *어댑터를 추가* 하는 방식. 비유 — *콘센트와 가전제품*. V1엔 LED 전구만 꽂혀 있어도, 콘센트 규격이 표준이라 V1.5에 선풍기·스마트조명 그냥 꽂으면 됨.
+
+★ 4 패턴 모두 **우리 차별점**:
+
+| ★ | 이름 | 역할 |
+|---|---|---|
+| ① | **Robustness 파이프라인** | DB 강건성 — 불완전 메타데이터 자동 보강 |
+| ② | Memory service | Hermes 기억 — 3축 분리 |
+| ③ | Ingestion pipeline | 문서 흡수 — 출처 × 해석 |
+| ④ | Semantic federation | 시멘틱 강건성 — git-like 팀별 분기 |
+
+## 3.1 ★ ① Robustness 파이프라인 — *우리의 진짜 차별점*
+
+사용자가 자기 DB 를 봇에 등록할 때, *현실은 메타데이터가 항상 불완전* — description 빈 컬럼, FK 누락, 의미 모호한 컬럼명, 샘플 데이터 부재.
+
+기존 오픈소스는 *이걸 사용자 숙제* 로 떠넘김 (Vanna: *"학습 데이터 잘 만드세요"*, Wren: *"MDL 잘 쓰세요"*).
+
+**우리의 접근 — 봇이 *능동적으로 보강***. DB 정보가 비어 있으면 봇이 채워 넣음. 비유로 *번역가가 누락된 원문을 문맥으로 추정해 채워 가는* 작업.
+
+확장 단위는 *enricher*. *description 자동 생성*, *FK 관계 추정*, *샘플 profile*, *컬럼명 패턴 → 쿼리 예시 우선순위*, *도메인 힌트 주입* 등을 *각각 enricher 한 종류* 로 추가.
+
+V1엔 추상만 박힘 (enricher 0 개). V1.5 부터 *DescriptionGenerator* 같은 첫 enricher 가 들어오며 실 가치 발생. 새 enricher 추가는 *클래스 1개 + 줄에 끼우기* 로 끝.
+
+**의미** — *Hint Vector* 같은 *DB 구조 강건성* 연구 결과를 그대로 enricher 로 plugin 가능. **연구실 코드가 곧 제품 layer**. *연구 친화* 아키텍처의 핵심.
+
+## 3.2 ★ ② Memory service — Hermes 기억의 3축 분리
+
+기억은 *하나의 큰 상자* 가 아니라 **세 가지 독립 기능의 조합**:
+
+| 축 | 역할 |
+|---|---|
+| **Store** | facts 를 어디에 보관 (메모리/SQLite/PostgreSQL/Redis ...) |
+| **Recall** | 현재 질문에 어떤 facts 를 가져올지 (전부/키워드/벡터/하이브리드) |
+| **Extractor** | 새 facts 를 어떻게 만들지 (사용자 명령만 / LLM 자동 추출) |
+
+각 축이 독립 진화. 예: V1.5 에 Store 만 SQLite 로 교체하는 게 *어댑터 1개 추가* 로 끝.
+
+진화:
+
+| 버전 | Store | Recall | Extractor |
+|---|---|---|---|
+| **V1** | 메모리 dict | 전부 주입 | `/remember` 명령만 |
+| **V1.5** | SQLite | 키워드 매칭 | LLM 자동 추출 |
+| **V2** | (같음) | 벡터 유사도 | + 충돌 해결 |
+| **V2.5** | PostgreSQL | 하이브리드 | + 신뢰도 점수 |
+
+## 3.3 ★ ③ Ingestion pipeline — 문서 → 시멘틱 레이어
+
+문서가 들어오면 두 단계:
+
+| 단계 | 역할 |
+|---|---|
+| **Source** | 어디서 문서를 가져오나 (파일/URL/Notion/Confluence/Google Drive) |
+| **Extractor** | 문서에서 metric/dimension/rule 후보를 어떻게 뽑는가 (LLM/DDL 파싱/하이브리드) |
+
+Source 와 Extractor 가 *매트릭스* 라서 *Source 1개 추가 = N 개 Extractor 와 자동 결합*.
+
+사용자 흐름 (V1):
+1. `/ingest` + 파일 첨부
+2. 봇이 LLM 에 *"metric/dimension/rule 찾아줘"* 요청
+3. Discord embed 로 후보 보여줌 + [✅ 모두 등록] [개별 선택] [❌ 취소]
+4. ✅ → 시멘틱 레이어에 등록 (출처 문서 ID 보존)
+5. 이후 *"이번 달 매출"* 질문 시 자동 적용
+
+진화:
+
+| 버전 | Sources | Extractors |
+|---|---|---|
+| **V1** | 파일 업로드 | LLM 추출 |
+| **V1.5** | + URL | + DDL 파일 직접 파싱 |
+| **V2** | + Notion / Confluence MCP | + 하이브리드 |
+| **V2.5** | + GitHub / Google Drive MCP | + 청크 RAG |
+
+## 3.4 ★ ④ Semantic federation — Git-like 시멘틱 분기
+
+같은 회사라도 팀별로 *같은 용어, 다른 의미*:
+
+| 용어 | 마케팅 | 프로덕트 | 파이낸스 |
+|---|---|---|---|
+| 활성 사용자 | 30일 내 로그인 | 7일 내 핵심 액션 | 유료 구독자 |
+| 매출 | 광고 매출 | (관심 없음) | net (환불 차감) |
+
+기존 *single truth* 모델은 *조직 현실과 충돌* — Wren 의 *"한 회사 한 MDL"* 은 팀별 합의 안 되면 깨짐.
+
+### 우리의 해결 — git 처럼 브랜치를 가져감
+
+```
+                       ┌──────────────┐
+                       │  main 브랜치  │ ← 회사 공통 (admin 정의)
+                       └──────┬───────┘
+                              │ 상속
+              ┌───────────────┼───────────────┐
+              ▼               ▼               ▼
+       ┌──────────┐    ┌──────────┐    ┌──────────┐
+       │#marketing│    │ #product │    │ #finance │
+       │active_   │    │active_   │    │revenue=  │
+       │user=30d  │    │user=7d   │    │net       │
+       └──────────┘    └──────────┘    └──────────┘
+              │
+              │ 상속
+              ▼
+       ┌──────────────────┐
+       │ thread 브랜치     │ ← 일시적 정의
+       └──────────────────┘
+```
+
+**동작**: 가장 구체적인 scope 가 이김. `#marketing` 에서 *"활성 사용자 수"* → 채널 정의(30일) 적용. `#product` 에서 같은 질문 → 채널 정의(7일) 적용. **충돌 없음** — 각자 자기 scope 에서 산다.
+
+사용자 흐름:
+
+```
+@user in #marketing:
+   /define_metric active_user "30일 내 로그인"   → 채널 scope
+
+admin:
+   /define_metric --guild revenue "gross + tax"  → main 브랜치
+   → finance 채널엔 자체 override 우선
+
+@user in #marketing:
+   /semantic show
+   → "이 채널: active_user (override) 30일, revenue (main) gross+tax"
+```
+
+진화:
+
+| 버전 | 기능 |
+|---|---|
+| **V1** | 3-scope (guild/channel/thread) 자동 resolution |
+| **V1.5** | `/semantic diff`, `/semantic promote` (admin 승인), 충돌 알림 |
+| **V2** | 외부 git 저장소 동기화 (semantic-as-code) |
+| **V2.5** | branch fork & merge UI |
+
+### 의미 — *시멘틱 강건성*
+
+기둥 ② DB 강건성 과 *짝* 인 개념:
+- **DB 강건성** (★①) — *불완전한 메타데이터* 에 견딤
+- **시멘틱 강건성** (★④) — *조직별 다른 정의* 에 견딤
+
+둘 다 *"현실의 messy함에 강건"*. **둘 다 Vanna/Wren 이 못 하는 영역**.
+
+---
+
+# Chap 4. 의견 정리
+
+## 4.1 비교 — 기존 오픈소스 대비 위치
+
+| 영역 | Vanna AI | Wren AI | SQLCoder | **Lang2SQL** |
+|---|---|---|---|---|
+| 자연어 → SQL | ✅ RAG | ✅ MDL | ✅ fine-tuned | ✅ RAG + 시멘틱 + harness |
+| DB 직접 연결 | ✅ | ✅ | ✅ | ✅ |
+| Semantic layer | ❌ | ✅ (수동 MDL) | ❌ | ✅ (**문서 자동 추출**) |
+| **시멘틱 federation** | ❌ | ❌ | ❌ | ✅ (**git-like 3-scope**) |
+| **DB 메타데이터 자동 보강** | ❌ | ❌ | ❌ | ✅ (**Robustness pipeline**) |
+| 대화 기억 | ❌ | ❌ | ❌ | ✅ (Hermes) |
+| Frontend 종류 | Web UI | Web UI | CLI | **Discord → Slack → Teams → Web** |
+| 확장 모델 | 단일 아키텍처 | enterprise platform | 단일 LLM | **★ 4 패턴** |
+
+**위치 요약**: *Vanna 의 자연어→SQL + Wren 의 시멘틱 + 우리만의 (문서 자동 추출 + git-like 팀 federation + DB 메타데이터 자동 보강 + Hermes 기억 + 멀티 인터페이스)*.
+
+## 4.2 한 줄
+
+> **"문서를 넣어 비즈니스 맥락을 학습시키고, 팀별로 시멘틱이 분기되고, *DB 메타데이터가 불완전해도 자동 보강* 하고, 모든 정의·대화를 기억하는 오픈소스 분석 에이전트."**
+
+— end —