kebab/tasks/p9/p9-fb-39b-embedding-upgrade.md

phase, component, task_id, title, status, target_version, depends_on, unblocks, contract_source, contract_sections, source_feedback

phase	component	task_id	title	status	target_version	depends_on	unblocks	contract_source	contract_sections	source_feedback
P9	kebab-embed-local + kebab-config + kebab-store-vector + docs	p9-fb-39b	Embedding model upgrade (multilingual-e5-large)	completed	0.6.0	p9-fb-39		../../docs/superpowers/specs/2026-04-27-kebab-final-form-design.md	§4 search §5 storage §9 versioning cascade	사용자 도그푸딩 2026-05-06 — Claude Code 가 kebab CLI 사용 후 "rank 5+ 노이즈 섞임" 지적 (fb-39 의 lever 적용 측면).

p9-fb-39b — Embedding model upgrade

✅ 구현 완료. fb-39 의 lever 후보 4개 중 embedding model 업그레이드 lever 적용. P@k metric (fb-39) 으로 small vs large 비교 가능.

• Design update: docs/superpowers/specs/2026-04-27-kebab-final-form-design.md §5 / §9
• Plan: docs/superpowers/plans/2026-05-10-p9-fb-39b-embedding-upgrade.md

요약

• multilingual-e5-small (384 dim) → multilingual-e5-large (1024 dim) default flip.
• 기존 user TOML 이 small 명시 시 그대로 유지 (backwards-compat).
• fb-23 incremental ingest 가 embedding_version mismatch 감지 → 자동 re-embed.
• 0.5 → 0.6 minor bump 트리거 (design §9 cascade rule, current Cargo.toml = 0.5.0).

구현 항목

1. config defaults flip — [models.embedding] model = "multilingual-e5-large", dimensions = 1024.
2. fastembed e5-large resolution — kebab-embed-local 의 resolve_model() 에 e5-large arm 추가.
3. fixture sweep — 모든 unit/integration 테스트의 default embedding 모델 확인. Config 에서 명시하지 않으면 새 default 따름 (provider = "none" 테스트 제외).
4. design contract update — design §5 (storage example) + §9 (versioning table) 의 embedding_model.id + dimensions 갱신.
5. HOTFIXES entry — 사용자 재 ingest 절차 + backwards-compat 동작 명시.
6. README update — [models.embedding] 섹션의 기본값 + dimensions 필드 설명 갱신.
7. SMOKE.md append — 스모크 테스트 중 embedding 업그레이드 검증 절차 (reset → config 갱신 → ingest → eval).
8. tasks/INDEX.md append — p9-fb-39b row 추가 (p9-fb-39 sibling).

Allowed dependencies

• kebab-embed-local — fastembed crate + kebab-core
• kebab-config — toml crate
• kebab-store-vector — lancedb crate (table naming 로직만 영향)
• kebab-app — 와이어링만 (API 변경 없음)

Forbidden dependencies

• parse-* crate (parser 무관)
• llm-* crate (embedding 과 무관)
• search crate (검색 로직은 adapter pattern 으로 이미 generic)

Test

• cargo test -p kebab-embed-local -- e5_large (새 arm 테스트)
• cargo test -p kebab-config -- embedding_defaults (config defaults)
• cargo test --workspace --no-fail-fast -j 1 (full regression)
• Smoke: kebab --config /tmp/smoke.toml doctor | grep embedding → multilingual-e5-large (1024d)
• Smoke: kebab --config /tmp/smoke.toml ingest → embedding 진행 표시 + dimension check
• P@k eval: kebab eval run (fb-39 의 golden set) small vs large 비교

Backward compat notes

• Pre-fb-39b user 가 config 에서 명시하지 않은 embedding → new default (large) 자동 적용. TOML 에 model = "multilingual-e5-small" 명시하면 유지.
• kebab-config 의 EmbeddingCfg.model 은 String 필드 — TOML 에 명시한 값이 default 를 override (serde 기본 동작).
• Orphan LanceDB table (chunk_embeddings_multilingual-e5-small_384) 은 다음 kebab ingest 실행 후 stale 취급 — 사용자가 수동 kebab reset --vector-only 로 정리 가능.

Binary version bump

• 0.5.0 → 0.6.0 (current Cargo.toml = 0.5.0; embedding_version cascade triggers minor bump per design §9).
• Release notes: embedding default: multilingual-e5-small (384d) → multilingual-e5-large (1024d), P@k metric ↑.

Post-merge deviation

• embedding_dim_mismatch ErrorV1 dropped: design spec §Migration policy 가 LanceVectorStore::open 안 dim mismatch 감지 + 신규 error.v1.code = "embedding_dim_mismatch" 를 명시했으나 구현에서 제외. 이유: LanceDB tables 가 (model, dim) namespaced (crates/kebab-store-vector/src/paths.rs:21) — 신규 model 변경 시 새 table 자동 생성, 옛 table orphan. dim mismatch 가 hard error 되지 않고 검색 결과 0건 (silent precision loss) 으로 surface. HOTFIXES 항목이 documentation source. 명시 error 가 의미 있으려면 별도 startup health check 필요 — fb-39c 후보 또는 v0.7.0 의 doctor 확장.
• 영향: 사용자가 model 변경 후 kebab ingest 안 하면 검색 결과 0건. README + SMOKE walkthrough 가 reset --vector-only && ingest 시퀀스 안내.