docs(config): v3 스키마 재편 설계 + 구현 계획

docs/superpowers/specs/2026-06-04-config-schema-reorg-design.md

@@ -0,0 +1,297 @@
+# config 스키마 재편 (v2 → v3): 미디어별 `[ingest]` 통합 + per-option 주석
+
+- 상태: 설계 확정 (brainstorming 완료)
+- 작성일: 2026-06-04
+- 선행: `docs/superpowers/specs/2026-05-31-config-migration-design.md` (마이그레이션 엔진), `#197`(엔진), `#198`(`kebab config migrate` surface)
+- 영향 crate: `kebab-config`(스키마+마이그레이션), `kebab-app`(call-site sweep + signature), `kebab-eval`(config_snapshot), `kebab-cli`(`config migrate`/`init` 출력)
+- contract_sections: design §6 (Config schema / XDG), §9 (versioning cascade — signature 불변 보장)
+
+## 1. 동기
+
+옵션이 누적되며 `config.toml`(13 섹션 / ~60 필드)이 다음 군더더기를 갖게 됨:
+
+1. **OCR 중복·비대칭** — `[image.ocr]` 와 `[pdf.ocr]` 가 `enabled/engine/model/endpoint/languages/max_pixels/request_timeout_secs` 를 거의 그대로 중복. 게다가 paddle-onnx 모델 경로(`det_model`/`rec_model`/`dict`/`score_thresh`/`unclip_ratio`/`max_boxes`)는 `[image.ocr]` 에만 존재하고 PDF paddle 경로가 거기를 참조(`kebab-app/src/lib.rs:3102` `ocr_engine_version_for_sig` 가 `config.image.ocr` 를 읽음) — "pdf 설정인데 image 밑을 봐야 하는" 숨은 비대칭.
+2. **미디어별 설정 산재** — 이미지 `[image]`, PDF `[pdf]`, 코드 `[ingest.code]`, 청킹 `[chunking]`. "형식 X 설정이 어디 있나"의 규칙이 없음.
+3. **`endpoint` 4중복** — `models.llm`/`models.embedding`/`image.ocr`/`pdf.ocr`. "비우면 `models.llm.endpoint` fallback" 규칙이 코드에만 있고 파일엔 안 보임. (단, **컴포넌트별 endpoint 는 실사용 중** — embedding 로컬 + llm 원격 — 이므로 통합 금지.)
+4. **`request_timeout_secs` 3중복** + 각각 "`0` 은 비활성화 아님" 함정.
+5. **`kebab init` 이 60+ 필드 일괄 방출** — 실제 사용자가 만지는 건 `workspace.root`/endpoint/모델명 정도.
+6. 사용자 실파일에서 추가 관찰: `score_gate = 0.30000001192092896`(f32→f64 직렬화 찌꺼기), `engine="paddle-onnx"` 인데 `model="gemma4:e4b"` 가 남는 죽은 필드.
+
+## 2. 목표 / 비목표
+
+**목표**
+
+- 미디어 형식 설정을 `[ingest.*]` 한 우산 아래로 일관 배치 (향후 새 형식 = `[ingest.<형식>]` 한 곳 추가).
+- OCR 비대칭 제거: image·pdf 가 **각자 OCR 전체(paddle 경로 포함)를 독립 보유**(완전 대칭).
+- **무손실 변환**: 기존 v2 파일의 모든 값·주석·순서·사용자 대안 주석 줄을 보존.
+- **per-option 주석**: 각 키 옆 한 줄 설명을 `kebab init` 출력과 신규 추가 키에 부착.
+- 업그레이드 시 **불필요한 재색인 0** (parser_version signature 불변).
+- env override 이름 **무파손**.
+
+**비목표 (YAGNI)**
+
+- config 값 의미 검증(범위 체크 등) — 별개.
+- 다운그레이드(v3→v2).
+- 노브 숨기기/축소 — 명시적으로 제외(사용자가 "온전한 변환" 선택). 전 옵션을 잘 문서화한 완전체 유지.
+- endpoint 통합 — 컴포넌트별 override 유지(실사용).
+- **load 시 파일 자동 쓰기** — 여전히 비목표(2026-05-31 spec 계승). 단 §5.3 의 *메모리 내* 변환은 쓰기가 아니므로 별개로 허용.
+
+## 3. 새 스키마 (v3)
+
+per-option 주석을 부착한 `kebab init` 출력 형태(값은 기본값):
+
+```toml
+# kebab config — `~/.config/kebab/config.toml`.
+# (헤더: workspace.root 경로 규칙 / 지원 형식 / KEBAB_* override — 기존 헤더 계승)
+schema_version = 3
+
+# 색인 대상 워크스페이스.
+[workspace]
+root = "~/KnowledgeBase"      # 색인 루트. 절대/~/${VAR}/상대(=이 파일 기준).
+exclude = [".git/**", "node_modules/**", ".obsidian/**"]  # denylist glob.
+
+# XDG 저장 경로(데이터/sqlite/벡터/에셋/모델).
+[storage]
+data_dir = "${XDG_DATA_HOME:-~/.local/share}/kebab"  # 모든 산출물 루트.
+sqlite = "{data_dir}/kebab.sqlite"   # 메타·FTS5 DB.
+vector_dir = "{data_dir}/lancedb"    # 임베딩 벡터 스토어.
+asset_dir = "{data_dir}/assets"      # 원본 사본(_external 등).
+artifact_dir = "{data_dir}/artifacts"
+model_dir = "{data_dir}/models"      # fastembed/candle/nli 모델 캐시.
+runs_dir = "{data_dir}/runs"         # eval run 산출.
+copy_threshold_mb = 100              # 이 크기 초과 파일은 사본 대신 참조.
+
+# 다국어 sentence embedding. dim 불일치 시 검색 0건.
+[models.embedding]
+provider = "fastembed"   # fastembed | candle | ollama | none.
+model = "multilingual-e5-large"
+version = "v1"           # 모델 정체성 일부(캐시 키). 모델 바꾸면 함께 갱신.
+dimensions = 1024        # 모델 출력 차원. 틀리면 검색 0건.
+batch_size = 64
+num_threads = 0          # candle 전용 CPU 스레드 cap(0=auto). NUMA 회피 레버.
+# endpoint = "..."       # ollama provider 시 HTTP. 비우면 models.llm.endpoint fallback.
+
+# Ollama host:port + 모델.
+[models.llm]
+provider = "ollama"
+model = "gemma4:e4b"
+context_tokens = 32768
+endpoint = "http://127.0.0.1:11434"
+temperature = 0.0
+seed = 0
+request_timeout_secs = 300   # 단일 HTTP 상한. 0=즉시실패(비활성화 아님). 대형모델 CPU면 ↑.
+
+# NLI(groundedness) 모델.
+[models.nli]
+model = "Xenova/mDeBERTa-v3-base-xnli-multilingual-nli-2mil7"
+provider = "onnx"
+
+# 색인 공통(병렬도 + 파일시스템 watch).   ← 기존 [indexing]
+[ingest]
+max_parallel_extractors = 2
+max_parallel_embeddings = 1
+watch_filesystem = false
+
+# 청크 크기·오버랩·heading 존중 (markdown/pdf/code/image 모든 형식 공통).  ← 기존 [chunking]
+[ingest.chunking]
+target_tokens = 500
+overlap_tokens = 80
+respect_markdown_headings = true
+chunker_version = "md-heading-v1"
+
+# code ingest skip 정책(.gitignore 자동 honor).
+[ingest.code]
+skip_generated_header = true
+max_file_bytes = 262144
+max_file_lines = 5000
+extra_skip_globs = []
+ast_chunk_max_lines = 200
+fallback_lines_per_chunk = 80
+fallback_lines_overlap = 20
+
+# 이미지 OCR(기본 off, asset 당 비용).   ← 기존 [image.ocr]
+[ingest.image.ocr]
+enabled = false
+engine = "ollama-vision"     # ollama-vision | paddle-onnx.
+model = "gemma4:e4b"         # ollama-vision 전용. paddle-onnx 는 번들 모델 사용(이 값 무시).
+languages = ["eng", "kor"]
+max_pixels = 1600
+request_timeout_secs = 300   # 0=즉시실패(비활성화 아님).
+# --- paddle-onnx 전용(engine=paddle-onnx 일 때만) ---
+# det_model = "..."          # 비우면 번들 ppocrv5_mobile_det.onnx.
+# rec_model = "..."          # 비우면 번들 korean rec.
+# dict = "..."               # 비우면 번들 korean_dict.txt.
+score_thresh = 0.3           # DBNet box 점수 하한.
+unclip_ratio = 1.5           # box 패딩 비율.
+max_boxes = 1000             # 이미지당 box cap(runaway guard).
+
+# 이미지 캡션(기본 off).   ← 기존 [image.caption]
+[ingest.image.caption]
+enabled = false
+max_pixels = 768
+prompt_template_version = "caption-v1"
+
+# scanned PDF page-단위 OCR(기본 off, page 당 비용).   ← 기존 [pdf.ocr]
+[ingest.pdf.ocr]
+enabled = false
+always_on = false            # true=모든 page vision 호출(vector PDF dual-text).
+engine = "ollama-vision"     # ollama-vision | paddle-onnx.
+model = "qwen2.5vl:3b"       # ollama-vision 전용. paddle-onnx 는 번들 모델 사용.
+languages = ["eng", "kor"]
+max_pixels = 2048
+request_timeout_secs = 180   # 0=즉시실패(비활성화 아님).
+valid_ratio_threshold = 0.5  # 유효문자 비율 < 이면 scanned 로 판정→OCR fallback.
+min_char_count = 20          # page 문자수 < 이면 auto-scanned.
+lang_hint = "kor"            # 단일 page lang hint(비우면 없음).
+# --- paddle-onnx 전용(대칭 신규) ---
+# det_model / rec_model / dict = "..."   # 비우면 번들.
+score_thresh = 0.3
+unclip_ratio = 1.5
+max_boxes = 1000
+
+# 검색 기본 k·stale 기준·fusion.
+[search]
+default_k = 10
+hybrid_fusion = "rrf"
+rrf_k = 60
+snippet_chars = 220
+cache_capacity = 256
+stale_threshold_days = 30
+
+# 답변 생성: prompt 템플릿·score gate·multi-hop·NLI.
+[rag]
+prompt_template_version = "rag-v3"
+score_gate = 0.3             # serialize_with 헬퍼로 직렬화 깔끔(기존 f32 찌꺼기 제거).
+explain_default = false
+max_context_tokens = 8000
+multi_hop_max_depth = 3
+multi_hop_max_sub_queries_per_iter = 5
+multi_hop_max_pool_chunks = 15
+nli_threshold = 0.0          # 0=NLI 게이트 off.
+
+# TUI 팔레트.
+[ui]
+theme = "dark"
+
+# ingest 로그(기본 on).
+[logging]
+ingest_log_enabled = true
+ingest_log_dir = "{state_dir}/logs"
+keep_recent_runs = 100
+retention_days = 30
+```
+
+## 4. 필드 매핑 (v2 → v3)
+
+| v2 위치 | v3 위치 | 비고 |
+|---------|---------|------|
+| `[workspace]` `[storage]` `[search]` `[rag]` `[ui]` `[logging]` `[models.*]` | 동일 | 변경 없음 |
+| `[indexing].*` (3키) | `[ingest].*` (bare 키) | `IndexingCfg` 해체 → `IngestCfg` 스칼라 |
+| `[chunking]` | `[ingest.chunking]` | 이름 의도적으로 `markdown` 아님(전 형식 공통) |
+| `[ingest.code]` | `[ingest.code]` | 이미 nested — 무이동 |
+| `[image.ocr]` | `[ingest.image.ocr]` | 키 동일 |
+| `[image.caption]` | `[ingest.image.caption]` | 키 동일 |
+| `[pdf.ocr]` | `[ingest.pdf.ocr]` | 키 동일 + **paddle 6키 대칭 신규** (`det_model`/`rec_model`/`dict`/`score_thresh`/`unclip_ratio`/`max_boxes`) |
+
+신규 키(pdf paddle 대칭)는 모두 `#[serde(default)]` + `Option`/기본값 → v2 파일에 없어도 무해.
+
+## 5. Rust 구조 변경 (`kebab-config/src/lib.rs`)
+
+### 5.1 구조체
+
+```rust
+pub struct Config {
+    pub schema_version: u32,
+    pub workspace: WorkspaceCfg,
+    pub storage: StorageCfg,
+    pub models: ModelsCfg,
+    pub ingest: IngestCfg,   // ← indexing/chunking/image/pdf 흡수
+    pub search: SearchCfg,
+    pub rag: RagCfg,
+    pub ui: UiCfg,
+    pub logging: LoggingCfg,
+    #[serde(skip)] source_dir: Option<PathBuf>,
+}
+
+pub struct IngestCfg {
+    // ← 기존 IndexingCfg (스칼라 먼저: toml 직렬화는 스칼라가 테이블보다 앞)
+    pub max_parallel_extractors: u32,
+    pub max_parallel_embeddings: u32,
+    pub watch_filesystem: bool,
+    // 하위 테이블
+    pub chunking: ChunkingCfg,
+    pub code: IngestCodeCfg,
+    pub image: ImageCfg,     // { ocr: OcrCfg, caption: CaptionCfg }
+    pub pdf: PdfCfg,         // { ocr: PdfOcrCfg }
+}
+```
+
+- `IndexingCfg` 구조체 삭제(스칼라로 흡수). `ChunkingCfg`/`ImageCfg`/`OcrCfg`/`CaptionCfg`/`PdfCfg`/`IngestCodeCfg` **내부 필드 불변**(부모 경로만 이동).
+- `PdfOcrCfg` 에 paddle 6키 대칭 추가.
+- 제거된 top-level 필드: `indexing`/`chunking`/`image`/`pdf`.
+- 스칼라-우선 필드 순서로 `defaults_are_serde_roundtrip_stable` 유지.
+
+### 5.2 call-site sweep (~65곳, 7 src 파일)
+
+기계적 치환: `config.chunking.X`→`config.ingest.chunking.X`, `config.image.ocr`→`config.ingest.image.ocr`, `config.pdf.ocr`→`config.ingest.pdf.ocr`, `config.indexing.X`→`config.ingest.X`. 대상: `kebab-app/src/{lib.rs,app.rs,schema.rs}`, `kebab-eval/src/runner.rs`. `kebab-parse-image` 는 leaf 구조체(`&OcrCfg` 등) 직접 수령 → 무영향(확인됨).
+
+### 5.3 load 시 메모리 내 자동 변환 (정합성 필수)
+
+v3 는 최초의 **non-additive rename** 이라, 미변환 v2 파일을 v3 struct 로 deserialize 하면 `[chunking]`/`[image]`/`[pdf]`/`[indexing]` 을 못 찾아 **사용자 설정이 조용히 기본값으로 유실**. (이전 마이그레이션은 전부 additive 라 serde default 로 load 호환됐음 — 이 가정이 v3 에서 처음 깨짐.)
+
+→ `Config::from_file` 변경: 텍스트의 `schema_version < CURRENT` (또는 legacy 테이블 탐지) 시 `migrate::migrate_document(text)` 를 **메모리에서** 적용한 `new_text` 를 deserialize. **디스크 쓰기 없음**(파일 갱신은 여전히 `kebab config migrate` 전용 — 2026-05-31 spec 의 "자동 쓰기 비목표" 계승; 메모리 변환은 쓰기가 아니므로 무충돌). 1회성 `tracing::warn!`: "config 가 schema vN 입니다 — 이번 실행은 메모리에서 v3 로 변환됨. 파일 갱신은 `kebab config migrate`."
+
+- parse 실패 시 `migrate_document` 는 입력 그대로 반환 → 기존 `ConfigInvalid` 경로 유지.
+- `source_dir` stamp 는 변환 후 동일하게 `path.parent()`.
+
+## 6. 마이그레이션 `step_2_to_3` (`kebab-config/src/migrate.rs`)
+
+`run_steps` 에 `if from < 3 { step_2_to_3(doc, changes) }` 추가. `step_2_to_3` 는 **테이블 relocation**(toml_edit, 값·키주석·순서 보존):
+
+1. `[indexing]` 의 3키 → `[ingest]` bare 키로 이동. 원 `[indexing]` 제거.
+2. `[chunking]` 테이블 → `[ingest.chunking]` 로 이동(통째). 원 제거.
+3. `[image.ocr]`→`[ingest.image.ocr]`, `[image.caption]`→`[ingest.image.caption]`. 원 `[image]` 제거.
+4. `[pdf.ocr]`→`[ingest.pdf.ocr]`. 원 `[pdf]` 제거.
+5. **pdf paddle 동작 보존(중요)** — v2 는 pdf 가 paddle 일 때 `image.ocr` 의 paddle 값(`det_model`/`rec_model`/`dict`/`score_thresh`/`unclip_ratio`/`max_boxes`)을 빌려 썼다(§1 비대칭). 따라서 이동 직후 **`[image.ocr]` 의 이 6키 실제 값을 `[ingest.pdf.ocr]` 의 대칭 키로 복사**한다(사용자가 image paddle 을 튜닝한 경우까지 동작 동일 보장). 사용자가 둘 다 기본이면 복사값=기본값이라 무차. 복사는 사용자가 `[pdf.ocr]` 에 해당 키를 이미 명시한 경우엔 덮어쓰지 않음.
+6. 기존 `[ingest.code]` 는 그대로(이미 올바른 위치). 단 `[ingest]` 가 새로 bare 키를 받으므로 직렬화 순서 정합 확인.
+
+이동은 **user item 의 decor(값 뒤 인라인 주석 + 사용자 대안 주석 줄)를 동반**해야 함 — toml_edit 에서 `Table::remove` 로 떼어낸 `Item` 을 새 부모에 `insert`. 멱등(이미 v3 형태면 no-op).
+
+이동 후 기존 `reconcile(annotated_default, doc)` 가:
+- 빠진 키(특히 pdf paddle 대칭 6키) 를 주석과 함께 추가.
+- `schema_version` stamp → 3.
+
+`CURRENT_SCHEMA_VERSION: u32 = 3` 으로 bump.
+
+## 7. per-option 주석 인프라
+
+- `key_comment(path: &str) -> Option<&'static str>` 신설 (`section_comment` 자매). dotted leaf 경로(`ingest.chunking.target_tokens` 등) → 한 줄.
+- `annotate_table` 확장: 스칼라 leaf 에도 `key_comment` 가 있으면 인라인/prefix 주석 부착.
+- **부착 범위**: `annotated_default_document`(=`kebab init` + reconcile 참조원) 의 모든 키. reconcile 가 **새로 추가하는** 키만 주석 동반(기존 사용자 키는 값 불가침 → 주석 미주입, 사용자 대안 주석 보존).
+- §3 의 모든 키 주석 텍스트를 `key_comment` 에 등재(구현 시 일괄).
+
+## 8. 불변식 / 회귀 가드
+
+1. **signature 불변** — `ingest_config_signature`(lib.rs:3129) 출력 문자열이 v2 바이너리와 **바이트 동일**. 값 기반이라 struct 경로 변경과 무관해야 함. `ocr_engine_version_for_sig` 가 읽는 paddle 경로 소스를 image signature 는 `config.ingest.image.ocr` 로, **pdf signature 는 `config.ingest.pdf.ocr` 의 신규 대칭 키**로 갱신. 동작 보존은 §6.5 의 값 복사(image paddle 값 → pdf 대칭 키)로 성립 — 마이그레이션된 파일에서 pdf 대칭 키 = v2 시절 image 값이므로 signature 동일. 골든 문자열 회귀 테스트 필수.
+2. **env 이름 보존** — `apply_env` whitelist 의 LHS(키 문자열) 전부 그대로, RHS(대입 대상)만 새 struct 경로. 신규 pdf paddle 키만 `KEBAB_PDF_OCR_{DET_MODEL,REC_MODEL,DICT,SCORE_THRESH,UNCLIP_RATIO,MAX_BOXES}` 추가. 기존 env 테스트 전부 green 유지.
+3. **무손실 골든** — 사용자 실제 v2 config(첨부본; `score_gate` 찌꺼기·주석 대안 줄 포함)를 fixture 로: `migrate_document` → (a) 모든 사용자 값 보존, (b) 사용자 주석/대안 줄 보존, (c) `[ingest.image.ocr]` 등 신 위치 존재, (d) 결과가 v3 `Config` 로 parse 되고 값이 원 의미와 동일, (e) 재실행 멱등.
+4. **load 자동변환** — v2 텍스트를 `Config::from_file` 로 읽으면(디스크 미변경) `config.ingest.chunking.target_tokens` 등이 사용자 값으로 채워짐(기본값 유실 없음) 테스트.
+5. **float 직렬화 정리** — `Config::defaults()` 직렬화에 `0.30000001192092896` 부재, `score_gate = 0.3`. 구현: f32 필드에 `#[serde(serialize_with = "ser_f32_clean")]`(f32 Display 의 shortest round-trip 을 f64 로 재파싱해 직렬화) — struct 타입·호출부 무변경, kebab-config 국소. 사용자 기존 파일의 찌꺼기 값은 toml_edit 보존(값 불가침)이라 그대로 — 재생성 시에만 정리됨(비목표 §2 정합).
+
+## 9. 버전 / 문서 cascade
+
+- **minor bump** (인터페이스 변경: config 섹션 rename + 신규 키). `Cargo.toml` workspace version.
+- **schema_version 2→3** (위).
+- **도그푸딩 필수**(CLAUDE.md Dogfood trigger: CLI/config surface) — `kebab config migrate` 를 실제 v2 파일(첨부본)에 돌려 무손실 + 자동변환 + 재색인 0 확인. evidence → HOTFIXES + release notes.
+- **문서 동기화(같은 PR)**: README Configuration 섹션 + `docs/SMOKE.md` config 예시 블록(새 레이아웃) + HOTFIXES dated entry + `2026-05-31-config-migration-design.md` 의 Risks/notes 에 v3 rename 교차링크.
+
+## 10. 리스크
+
+| 리스크 | 완화 |
+|--------|------|
+| 테이블 이동 시 주석 유실 | toml_edit `remove`→`insert` 로 `Item` 통째 이동, 골든 테스트(§8.3) |
+| signature 변동→전체 재색인 | 골든 문자열 회귀 테스트(§8.1), 값 포맷 보존 |
+| pdf paddle 대칭 추가가 기존 pdf paddle 동작 변경 | §6.5 마이그레이션이 image paddle 6키 실제 값을 pdf 대칭 키로 복사 → 동작·signature 동일(§8.1) |
+| call-site 누락 | 컴파일러가 강제(필드 제거→ 미수정 site 컴파일 에러), clippy gate |
+| 메모리 자동변환 매 load 비용 | toml_edit parse 1회/실행, 무시 가능 |
+```