v0.31.0 — 척추 단순화 + 캐시 전면화 (spine simplification + cache everywhere)

v0.30.1 이후 누적된 세 PR(#214 척추 재작성 · #216 임베딩 캐시 전면화 · #217 OCR/caption 캐시)을 묶은 릴리스. breaking 변경(세션 제거 V015 마이그레이션 + config v4→v5)이 포함되어 minor bump. 실 데이터 도그푸딩 evidence는 tasks/HOTFIXES.md 2026-06-25 항목.

1. 척추 재작성 / 단순화 (#214) — breaking

기능 추가로 산만해진 표면·동작·내부를 강하게 정리. 능력은 (거의) 유지하되 조작 표면과 코드 구조를 단순화.

제거된 기능 (crate 24→22): kebab tui 서브커맨드 + kebab-tui crate, multi-turn 세션(ask --session·chat_sessions/chat_turns), legacy RAG 템플릿 rag-v1/v2(rag-v3/v4만 유지), search LRU 캐시, candle 임베더 provider(kebab-embed-candle).
config v4→v5 무손실 자동 마이그레이션: OCR 엔진 설정 중복을 공유 [ingest.ocr] 블록으로 통합. kebab config migrate 또는 로드 시 자동 — 사용자 개입 불필요(.bak 백업). env arm 75→22, 노출 키 정리.
V015 마이그레이션: 기존 KB 의 chat_sessions/chat_turns 테이블을 첫 store open 시 자동 드롭.
trade-off: 구 v0.30.1 바이너리는 v5 config([ingest.ocr] 슬림화로 missing field engine)를 못 읽음 — downgrade 는 마이그레이션 전 config 백업(.bak) 복원 필요. multi-turn 세션·tui 를 쓰던 워크플로는 제거됨.
upgrade: 새 바이너리로 아무 명령이나 실행하면 config v3/v4→v5 + DB V14/V15 가 자동 적용. 별도 조치 불필요. (실 v3 KB 도그푸딩: 마이그레이션 후 lexical search 정상.)

2. 임베딩 캐시 전면화 (#216) — patch (출력 불변)

markdown 만 타던 임베딩 derivation 캐시를 image/pdf/code 핸들러 전부에 배선. 재인덱싱 시 청크 텍스트가 동일하면(force-reingest 또는 chunker 외 버전 유지) 임베딩을 재계산하지 않고 캐시 재사용.

trade-off: 없음 — 출력 byte-identical(fresh-dir=전부 미스=기존과 동일, 재인덱싱=캐시 히트로 동일 LE-f32 벡터). 미디어 무관 version_key 라 같은 텍스트는 미디어 교차로 한 엔트리 공유.
mitigation: 4 미디어 전부 cache hit/miss 를 tracing::info! 로 노출 — warm 재인덱싱이 embed 0회인지 확인 가능.
upgrade: 자동. 새 바이너리부터 image/pdf/code 재인덱싱이 임베딩 캐시를 탐.

3. OCR/caption derivation 캐시 (#217) — patch (출력 불변)

이미지 OCR·이미지 caption·PDF 페이지 OCR 결과를 소스 바이트 + OCR/caption 버전키로 캐싱. 재인덱싱이나 chunker/embedding 버전 bump 시 비싼 비전 엔진(paddle ONNX / ollama-vision)을 재실행하지 않고 캐시된 텍스트 재사용 — 비전 작업을 버전-캐스케이드에서 분리.

변경 사실: 새 ocr/caption derivation_cache 네임스페이스(마이그레이션 불필요 — 스키마 namespace-agnostic). 결과는 full-struct serde 로 캐싱돼 block 레벨까지 byte-identical 재구성.
trade-off: 없음 — 출력 불변. 캐시 히트 시 provenance 이벤트는 재현 안 함(wire 스키마/게이트에 없어 무영향). ollama-vision 의 잔여 비결정성은 첫 결과를 박제해 재현성 오히려 향상.
mitigation: 엔진/모델/paddle 출력 파라미터(score_thresh/unclip_ratio/max_boxes) 변경 시 version key 변경→캐시 미스→재계산(stale 방지). PDF 경로 캐시 GET 에러는 debug 로그 후 미스로 degrade(per-page 회복력).
upgrade: 자동. 실 도그푸딩(17개 jira 스크린샷, paddle OCR): 재인덱싱이 OCR 캐시 히트(created_at 17/17 고정) → 7.0× 빠름(8.5s→1.2s), 16/17 실 OCR 텍스트.

버전

0.30.1 → 0.31.0 (minor — 세션 제거 V015 + config v5 breaking 변경이 트리거). 새 CLI flag·wire breaking 변경은 없으나(캐시는 자동·표면 무변경), 척추의 마이그레이션·인터페이스 제거가 minor 를 강제.

도그푸딩 (실엔진 종단 검증)

OCR 캐시 (b1): 17 실 jira PNG, paddle-onnx(CPU) → 재인덱싱 캐시 HIT, 7.0× 빠름, created_at 17/17 고정, 16/17 실 OCR 텍스트.
caption 캐시 (b2): 4 실 jira PNG, ollama-vision(gemma3:4b, GPU 스왑) → 재인덱싱 캐시 HIT, 22× 빠름, 비결정적 LLM 캡션 verbatim 재현(비결정성 박제 확증), 캡션 품질 양호. lemonade 복구 확인.
마이그레이션: 실 v3 KB → config v5 + V14/V15 자동 적용(chat_sessions 드롭), 검색 정상.

알려진 한계 / 후속

caption 캐시(b2)의 영구 CI 가드용 mock-LLM 결정적 테스트는 후속 패치(실엔진 도그푸딩으로 검증 완료, mock 테스트는 GPU 없는 CI 회귀 가드용).
paddle 결정적 게이트 코퍼스(텍스트-bearing fixture)는 미커밋 — 현재 paddle_e2e.rs 는 fixture 부재 시 skip. 캐시 정확성 게이트는 mock(ocr_caption_cache.rs) + 실엔진(paddle_image_cache.rs)이 담당.

5.1 KiB Raw Permalink Blame History Unescape Escape