---
title: kebab v0.20.1 release notes (draft)
created: 2026-05-28
status: draft
release_trigger:
  - 사용자 도그푸딩 필요 (Bug #8 — 한국어 2자 query 0-hit 해소)
  - frozen design contract 변경 (design §5.5 chunks_fts: trigram → unicode61 + 형태소 column)
---

# kebab v0.20.1 — 한국어 형태소 검색 + 영어 substring 회귀

v0.20.0 (sub-item 1 scanned PDF OCR via qwen2.5vl:3b, 2026-05-27) 후속의 patch release. v0.20.x 라인의 두 누적 enhancement (logging round 2 + 한국어 morphological tokenizer) 를 하나로 묶어 cut.

## 핵심 변경

### 1. 한국어 2자 query 지원 — Bug #8 해소

이전 V007 (v0.17.0+) 의 trigram FTS5 tokenizer 는 3-character gram 최소 인덱싱이라 `'한국'` / `'서울'` / `'지하철'` 같은 1-3자 한국어 단어 query 가 종종 0-hit 였습니다. 사용자 도그푸딩 round 3/4 의 가장 큰 search experience surface.

**v0.20.1 의 해결책** — `chunks_fts` tokenizer 를 `unicode61` 로 환원 + lindera ko-dic 형태소 분석기로 한국어 chunk text 를 분해해 별 column `tokenized_korean_text` 에 pre-fill. FTS5 trigger 의 CASE expression 이 raw text 앞에 prepend 해 단일 query 로 두 column 모두 매칭.

```bash
# v0.17.0 (V007 trigram): 0 hit
# v0.20.1 (V009 morphological): hit (chunk 의 ko-dic 분해 결과에 '한국' morpheme 가 존재)
kebab search '한국'
kebab search '서울'
```

**Dogfood evidence** (`tasks/HOTFIXES.md` 2026-05-28 entry + `docs/DOGFOOD.md` §2.1bis 의 reference fixture 14 scenario):

| Query | v0.17.0 (V007 trigram) | v0.20.1 (V009) |
|---|---|---|
| `'한국'` 2자 | 0 hit | hit |
| `'서울'` 2자 | 0 hit | hit |
| `'지하철'` 3자 | substring (제한적) | morpheme + raw token 모두 매칭 |
| `'서울특별시'` compound | substring | ko-dic 분해 `[서울, 특별시]` |

**Known limitation**: ko-dic 가 compound noun (예: `한국정부`) 을 단일 token 으로 저장하는 경우 그 chunk 의 `'한국'` 단독 query 는 hit X. KB 가 영어/code 위주면 한국어 token 자체 부재로 lexical 0-hit 자연. N-gram supplement (sub-token 추가 emit) 는 v0.21.x P9 follow-up.

### 2. 영어 substring 매칭 회귀 (V002 동작 환원)

V007 trigram 의 ad-hoc 부산물이었던 영어 substring 매칭 (`'token'` query 가 `'tokenizer'` chunk 도 hit) 은 V009 의 unicode61 transition 으로 **사라집니다**. V002 (pre-v0.17.0) 의 whole-token 매칭으로 환원.

```bash
# v0.17.0: 'token' query → 'tokenizer' chunk hit (substring recall ↑, 단어 경계 정밀도 ↓)
# v0.20.1: 'token' query → 'token' 토큰만 hit, 'tokenizer' 는 다른 token
kebab search --mode lexical 'token'      # 다른 결과 가능
kebab search --mode lexical 'tokenizer'  # 정확한 token 매칭
```

substring recall 이 필요한 시나리오는 **vector** 또는 **hybrid** mode 권장 (RRF 가 lexical + semantic 결합). spec §3 Non-Goals Path A 의 설계 결정 — lexical 의 단어 경계 정밀도 vs substring recall trade-off 에서 후자 포기.

### 3. V007 → V009 자동 backfill (재-ingest 불필요)

기존 V007 KB 를 v0.20.1 binary 로 첫 부팅할 때 `App::open_with_config` 의 first-boot hook 이 자동 실행:

1. V009 migration apply (schema 변경: `tokenized_korean_text TEXT` column ADD + chunks_fts re-create with unicode61 + CASE expression triggers).
2. `backfill_tokenized_korean_text` API 호출 — chunks 의 NULL `tokenized_korean_text` row 를 lindera 로 분해 후 UPDATE. 1000-row batch transaction + progress callback.
3. chunks_au trigger 가 chunks_fts 를 자동 재-index.

KB 크기 비례 latency:
- 1만 chunk → ~30-60초 (lindera tokenize + UPDATE + trigger overhead).
- 10만 chunk → ~5-10분.
- stderr 의 `tracing::info!` progress log (`korean tokenizer backfill: 500/10000`) 발화. 사용자 hang 인지 방지.
- 부분 완료 (Ctrl-C) 후 재실행 시 IS NULL filter 로 idempotent 이어 처리.

backfill 실패 시 (예: lindera dict load fail) `App::open_with_config` 은 success 반환 + warn log. vector/hybrid mode 정상 사용 가능.

### 4. Ingest 성능 영향

새 chunk ingest 시 chunker (`kebab-chunk::md_heading_v1`, `code_*_ast_v1`, `pdf_page_v1`, `tier2_shared`) 가 chunk emit 직전에 `tokenize_korean_morphological(text)` 호출. OnceLock 캐시로 dictionary load 가 process-lifetime 동안 1회 — amortized cost 낮음.

도그푸딩 측정 (1781 markdown / 9050 chunk):
- v0.20.0 ingest baseline: ~700초.
- v0.20.1 ingest: ~671초 (실측 — overhead 거의 무의미, chunk text 길이 비례 +5-10% 예상).

`kebab.sqlite` 파일 크기 영향:
- `tokenized_korean_text` column 추가 (한국어 chunk 비례 +20-30% column data).
- chunks_fts shadow 의 indexed text 가 raw + tokenized 합 (Korean-heavy KB 에서 ~2배 chunks_fts 크기).
- 영어/code 위주 KB 에서는 `tokenized_korean_text` 가 NULL 또는 short → 영향 minimal.

binary 크기:
- v0.20.0: ~270 MB (release).
- v0.20.1: ~390 MB (lindera-ko-dic embedded dict 의 ~120 MB 추가).

## Migration cascade

| Version field | v0.20.0 | v0.20.1 |
|---|---|---|
| `lexical_index_version` | `lex:{chunker}` | `lex:{chunker}:fts5-v009-korean-morphological` |
| `corpus_revision` | V004 seed = 0 | V009 migration tail 의 +1 (post-migration baseline = 1) |
| `chunker_version` | unchanged | unchanged |
| `parser_version` | unchanged | unchanged |
| `embedding_version` | unchanged | unchanged |
| Wire schema (`search_response.v1`, `answer.v1`) | shape unchanged | shape unchanged (hit ordering / snippet content 만 변화) |

eval runner 의 `config_snapshot_json` 가 자동으로 `lexical_index_version` 의 V009 suffix 를 picks up — `crates/kebab-eval/tests/fixtures/eval/run-1.json` 의 V009 baseline 으로 regenerate 됨.

## API + dependency 변경

신규 workspace dependencies:
- `lindera = "3"` (MIT/Apache-2.0)
- `lindera-ko-dic = "3"` (Apache-2.0, MeCab-ko-dic upstream)

신규 facade-level API (`kebab-app` 의 `*_with_config` 패턴 따라):
- `kebab_chunk::tokenize_korean_morphological(text: &str) -> Option<String>`
- `kebab_store_sqlite::SqliteStore::backfill_tokenized_korean_text<F, T>(progress, tokenize) -> Result<u64>`

retired:
- `kebab_app::short_query_hint()` helper — V007 시절 advisory. V009 의 2-char Korean query hit 으로 obsolete. `SearchResponse.hint` struct field + wire schema `hint` field 는 forward-compat 차원에서 보존 (항상 None).

## Logging round 2 (v0.20.x sub-item 1 후속, PR #190 머지)

- PDF OCR raster image dimension capture (PR #189 의 round 1 null 결함 fix).
- V008 SQLite mirror — historical OCR query table.
- CLI `kebab inspect ocr-stats` + `kebab inspect ocr-failures`.
- Log retention policy — `keep_recent_runs` + `retention_days`.

자세한 내용 = HANDOFF.md "v0.20.x ingest log r2" entry + spec `docs/superpowers/specs/2026-05-28-v0.20.x-logging-r2-spec.md`.

## Breaking changes / 사용자 영향

- **영어 lexical 의 substring 매칭이 사라짐** — 사용자가 `'token'` query 로 `'tokenizer'` 도 찾는 패턴 의존 시 vector/hybrid mode 로 mode-switch 권장. release notes 만 보고 mode 변경 안 한 사용자는 자기 KB 의 검색 결과 변화 인지.
- **첫 부팅 latency** — 큰 KB 의 사용자는 v0.20.1 binary 의 첫 호출이 30초~10분 hang. stderr progress log 확인.
- **DB / binary 크기 증가** — `kebab.sqlite` +20-30% (Korean-heavy), binary +120MB (lindera ko-dic embedded). `/build/cache/tmp` 또는 별 디스크에 KB 둔 사용자는 영향 minimal.

## Upgrade 절차

```bash
# 1. binary 교체 (release tag v0.20.1)
git fetch && git checkout v0.20.1 && cargo build --release -p kebab-cli

# 2. 첫 호출 — V009 migration + eager backfill 자동
kebab search '한국'   # stderr 의 backfill progress log 확인

# 3. 새 검색 패턴 확인
kebab search '서울'   # 2자 query hit
kebab search 'tokenizer'   # whole-token (substring recall 회귀)
```

회귀 발견 시 `tasks/HOTFIXES.md` 또는 GitHub issue 보고.

## References

- Spec: [`docs/superpowers/specs/2026-05-28-v0.20.x-korean-morphological-tokenizer-spec.md`](../superpowers/specs/2026-05-28-v0.20.x-korean-morphological-tokenizer-spec.md)
- Plan: [`docs/superpowers/plans/2026-05-28-v0.20.x-korean-morphological-tokenizer-plan.md`](../superpowers/plans/2026-05-28-v0.20.x-korean-morphological-tokenizer-plan.md)
- HOTFIXES entry: [`tasks/HOTFIXES.md`](../../tasks/HOTFIXES.md) 2026-05-28
- DOGFOOD scenarios: [`docs/DOGFOOD.md`](../DOGFOOD.md) §2.1 + §2.1bis
- Design contract: [`docs/superpowers/specs/2026-04-27-kebab-final-form-design.md`](../superpowers/specs/2026-04-27-kebab-final-form-design.md) §5.5 + §9
- V009 migration: [`migrations/V009__fts_korean_morphological.sql`](../../migrations/V009__fts_korean_morphological.sql)
- lindera: https://github.com/lindera-morphology/lindera (MIT/Apache-2.0)
- lindera-ko-dic: https://github.com/lindera-morphology/lindera-dictionary (Apache-2.0)