altair823-org/kebab
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 40 Wiki Activity

refactor(app): doc-side expansion(별칭) 기능 제거 #202

Merged
altair823 merged 9 commits from refactor/remove-doc-expansion into main 2026-06-03 00:39:30 +00:00
Conversation 1 Commits 9 Files Changed 50 +165 -1295
altair823 commented 2026-06-02 21:43:41 +00:00
Owner
Copy Link

요약

doc-side expansion(별칭) 기능을 완전히 제거한다. 측정·딥리서치(docs/superpowers/research/2026-06-03-expansion-cost-rethink-research.md)에서 별칭의 ROI 가 음수로 확인됐다: cross-lingual(한↔영)·동의어·약어 recall@10 은 e5-large 단독으로 이미 완벽하고(en 18/18, ko 18/18, syn 11/11, abbr 7/7), 별칭의 실효는 설명형 paraphrase +2 그룹(14→16)뿐인데 그 대가가 청크당 색인-시 LLM 호출(살아있는 KB 에서 지속 불가능, 정답 18문서만 2.5시간)이었다. 학계(arXiv 2309.08541 "강한 검색기엔 expansion 이 해롭다")와도 정합. 별칭은 이미 default-off 라 일반 사용자 체감은 0이며, 본 PR 은 코드·스키마·wire 표면을 정리해 유지보수 부담을 없앤다.

설계: docs/superpowers/specs/2026-06-03-remove-doc-expansion-spec.md
계획: docs/superpowers/plans/2026-06-03-remove-doc-expansion-plan.md

제거 / 유지 경계

제거: Chunk.aliases, kebab-app/src/expansion.rs + ingest 별칭 생성·캐시·sentinel 벡터 루프, IngestExpansionCfg/[ingest.expansion], kebab-search 의 run_alias_query/merge_body_alias/alias lexical arm, IngestEvent::ExpansionProgress + CLI/TUI 렌더 + wire expansion_progress kind, 별칭 전용 테스트.

유지(의도적): Metadata.aliases(문서 메타데이터, 무관), AssetChunked/AssetTimings(+ expansion_ms 필드는 wire 호환 위해 값 0 유지), derivation_cache embedding kind(V012 임베딩 캐시), chunks_fts(본문 FTS), 그리고 ALIAS_SUFFIX/strip_alias_suffix(ids.rs) — 기존 KB 의 잔존 alias sentinel 벡터를 검색 시 본문 chunk 로 graceful 매핑하는 read-side 하위호환(제거 시 옛 KB 결과 깨짐 방지).

마이그레이션 / 버전

  • 신규 migrations/V013__drop_chunk_aliases.sql — forward-only 로 chunk_aliases_fts(+ 트리거) + chunks.aliases DROP. V010 은 freeze 규칙대로 무수정, V013 이 덮어 제거. corpus_revision cascade 불필요(본문·임베딩 불변).
  • workspace version 0.24.0 → 0.25.0.
  • [ingest.expansion] 가 남아있는 기존 config.toml 은 serde forward-compat 로 무해하게 무시됨(확인).

검증

  • cargo clippy --workspace --all-targets -j 4 -- -D warnings → exit 0 (리더 독립 재실행으로 재확인, 1m59s).
  • cargo test --workspace --no-fail-fast -j 1 → 1452 tests passed, 실패 0 (195 그룹 ok).
  • acceptance grep 잔존 0: expansion::|ExpansionCfg|chunk_aliases|run_alias_query|merge_body_alias|ExpansionProgress|embed_aliases|is_nav_boilerplate, Chunk.aliases 0.
  • fresh KB 스모크: kebab ingest 정상 종료, .schema 에 chunk_aliases_fts/chunks.aliases 부재 확인, expand phase 미출력.
  • 기존 [ingest.expansion] config 무해 무시 확인.

시험 항목 (Test Plan)

  • V013 적용된 fresh KB 에 chunk_aliases_fts/aliases 컬럼 부재
  • 별칭 sentinel 벡터가 남은 구 KB 도 search/ask 정상(read-side graceful 매핑)
  • AssetChunked/AssetTimings 진행 표시 유지, expansion_progress 미출력

Assisted-by: Claude Code

## 요약 doc-side expansion(별칭) 기능을 완전히 제거한다. 측정·딥리서치(`docs/superpowers/research/2026-06-03-expansion-cost-rethink-research.md`)에서 별칭의 ROI 가 음수로 확인됐다: cross-lingual(한↔영)·동의어·약어 recall@10 은 e5-large 단독으로 이미 완벽하고(en 18/18, ko 18/18, syn 11/11, abbr 7/7), 별칭의 실효는 설명형 paraphrase +2 그룹(14→16)뿐인데 그 대가가 **청크당 색인-시 LLM 호출**(살아있는 KB 에서 지속 불가능, 정답 18문서만 2.5시간)이었다. 학계(arXiv 2309.08541 "강한 검색기엔 expansion 이 해롭다")와도 정합. 별칭은 이미 default-off 라 일반 사용자 체감은 0이며, 본 PR 은 코드·스키마·wire 표면을 정리해 유지보수 부담을 없앤다. 설계: docs/superpowers/specs/2026-06-03-remove-doc-expansion-spec.md 계획: docs/superpowers/plans/2026-06-03-remove-doc-expansion-plan.md ## 제거 / 유지 경계 **제거**: `Chunk.aliases`, `kebab-app/src/expansion.rs` + ingest 별칭 생성·캐시·sentinel 벡터 루프, `IngestExpansionCfg`/`[ingest.expansion]`, `kebab-search` 의 `run_alias_query`/`merge_body_alias`/alias lexical arm, `IngestEvent::ExpansionProgress` + CLI/TUI 렌더 + wire `expansion_progress` kind, 별칭 전용 테스트. **유지(의도적)**: `Metadata.aliases`(문서 메타데이터, 무관), `AssetChunked`/`AssetTimings`(+ `expansion_ms` 필드는 wire 호환 위해 값 0 유지), derivation_cache `embedding` kind(V012 임베딩 캐시), `chunks_fts`(본문 FTS), 그리고 `ALIAS_SUFFIX`/`strip_alias_suffix`(ids.rs) — **기존 KB 의 잔존 alias sentinel 벡터를 검색 시 본문 chunk 로 graceful 매핑하는 read-side 하위호환**(제거 시 옛 KB 결과 깨짐 방지). ## 마이그레이션 / 버전 - 신규 `migrations/V013__drop_chunk_aliases.sql` — forward-only 로 `chunk_aliases_fts`(+ 트리거) + `chunks.aliases` DROP. V010 은 freeze 규칙대로 무수정, V013 이 덮어 제거. corpus_revision cascade 불필요(본문·임베딩 불변). - workspace version `0.24.0 → 0.25.0`. - `[ingest.expansion]` 가 남아있는 기존 config.toml 은 serde forward-compat 로 무해하게 무시됨(확인). ## 검증 - `cargo clippy --workspace --all-targets -j 4 -- -D warnings` → exit 0 (리더 독립 재실행으로 재확인, 1m59s). - `cargo test --workspace --no-fail-fast -j 1` → 1452 tests passed, 실패 0 (195 그룹 ok). - acceptance grep 잔존 0: `expansion::|ExpansionCfg|chunk_aliases|run_alias_query|merge_body_alias|ExpansionProgress|embed_aliases|is_nav_boilerplate`, `Chunk.aliases` 0. - fresh KB 스모크: `kebab ingest` 정상 종료, `.schema` 에 `chunk_aliases_fts`/`chunks.aliases` 부재 확인, expand phase 미출력. - 기존 `[ingest.expansion]` config 무해 무시 확인. ## 시험 항목 (Test Plan) - [ ] V013 적용된 fresh KB 에 chunk_aliases_fts/aliases 컬럼 부재 - [ ] 별칭 sentinel 벡터가 남은 구 KB 도 search/ask 정상(read-side graceful 매핑) - [ ] AssetChunked/AssetTimings 진행 표시 유지, expansion_progress 미출력 Assisted-by: Claude Code
altair823 added 9 commits 2026-06-02 21:43:42 +00:00
refactor(core): Chunk.aliases 필드 제거 b1c5feb3f3 
doc-side expansion(별칭) 제거 — Chunk 의 aliases: Option<String> 필드와
serde default 테스트 제거. Metadata.aliases(Vec, 문서 메타)는 유지.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
refactor(chunk): Chunk 생성부의 aliases 리터럴 + store 컬럼 제거 ecaf224381 
kebab-chunk/* AST·md·tier2·pdf chunker 의 aliases: None 리터럴 삭제,
store-sqlite documents.rs chunks INSERT 컬럼/바인딩 + get_chunk 매핑에서
aliases 제거.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
refactor(config): ExpansionCfg + [ingest.expansion] 제거 ec96648956 
IngestExpansionCfg struct + IngestCfg.expansion 필드 + Default +
KEBAB_INGEST_EXPANSION_* env 파싱 + 테스트 제거. migrate.rs 의
ingest.expansion 섹션 주석 제거 — config migrate 테스트는 ingest.code 앵커로
정정(forward-compat: 기존 [ingest.expansion] 섹션은 serde 가 무시).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
refactor(search): alias lexical arm 제거 a64c31ee94 
run_alias_query / merge_body_alias 제거, 검색을 body_rows 직접 사용으로
단순화. build_match_string_for_column 의 column 매개변수 인라인(text 고정).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
refactor(app): ingest 별칭 생성·캐시·sentinel 벡터 루프 제거 21e02d8a93 
ingest_one_asset 의 청크당 별칭 LLM 생성·derivation_cache 조회/저장·
embed_aliases sentinel 벡터(`{orig}#alias#N`) upsert 루프 제거.
expansion_ms 는 wire 호환 위해 0 고정. alias_sentinel_ids_to_delete 와
orphan purge 3개 호출부를 본문 chunk_id 직접 삭제로 단순화.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
refactor(wire): ExpansionProgress 이벤트 + 렌더 제거 a48c405826 
IngestEvent::ExpansionProgress variant + 직렬화 테스트 제거(AssetChunked/
AssetTimings 유지). CLI/TUI 의 expansion 렌더 제거, AssetTimings 한 줄에서
expand 세그먼트 제거. ingest_progress.v1 schema 의 expansion_progress kind
제거, expansion_ms 설명을 "값 0 유지"로 갱신.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
feat(store): V013 마이그레이션 — chunk_aliases_fts + chunks.aliases DROP 16aadea222 
forward-only 마이그레이션으로 V010 이 만든 chunk_aliases_fts(+트리거)와
chunks.aliases 컬럼 제거. 과거 V010 은 freeze 무수정. 순수 구조 변경 —
corpus_revision bump 안 함(spec §결정: 본문/임베딩 불변, in-process LRU 는
프로세스별·query 이전 실행이라 bump 무의미).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
test: 별칭 전용 테스트 삭제 + 영향 테스트/fixture 갱신 e03d03cb26 
kebab-search/tests/lexical.rs 의 alias 채널 테스트 + insert_chunk_with_aliases
헬퍼 제거(body 회수 회귀 테스트로 대체). Chunk 리터럴 aliases: None 제거
(embedding_records_fk/idempotency/inspect). chunk 스냅샷 fixture 의 aliases
키 제거. config_migrate 는 ingest.code 앵커로, corpus_revision/search_lexical
주석은 V013 비-bump 명시로 갱신.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
docs: 별칭 제거 문서 동기화 + version 0.25.0 fc5103642e 
HOTFIXES 2026-06-03 dated entry, 2026-05-30 design spec 제거 banner,
HANDOFF 1줄, README(별칭 섹션/config/명령표 정리), ARCHITECTURE(결정 표 +
디렉토리 트리), SMOKE/DOGFOOD config-migrate 예시 정정. workspace version
0.24.0 → 0.25.0 (+ Cargo.lock).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
claude-reviewer-01 approved these changes 2026-06-02 21:46:22 +00:00
claude-reviewer-01 left a comment
Member
Copy Link

회차 1 — 별칭 제거. 독립 검증 후 actionable 결함 0, 머지 동의(APPROVE).

독립 검증한 것

  • cargo clippy --workspace --all-targets -j 4 -- -D warnings → exit 0 (리뷰어가 worktree 에서 재실행, 1m59s).
  • acceptance grep 잔존 0(expansion::|ExpansionCfg|chunk_aliases|run_alias_query|merge_body_alias|ExpansionProgress|embed_aliases|is_nav_boilerplate, Chunk.aliases).
  • migrations/V013__drop_chunk_aliases.sql 실재·정확: trigger → FTS 테이블 → 컬럼 DROP 순서, V010 무수정(freeze 준수), forward-only.

핵심 로직 diff 검토 (회귀 위험 영역)

  • kebab-search/lexical.rs: 별칭 채널(run_alias_query/merge_body_alias/alias 분기) 제거 후 raw_rows = run_query(...) 직결 = pre-V010 body-only 동작 복원. build_match_string_for_column→build_match_string(text 고정) 원복. 깔끔.
  • kebab-app/lib.rs: expansion 루프·캐시·sentinel 벡터 임베딩 전부 제거, expansion_ms = 0(주석으로 wire 호환 명시). purge_vector_orphans 본문 경로 유지.
  • wire ingest_progress.v1: expansion_progress kind + 이제 고아가 된 done 프로퍼티까지 정합 제거. expansion_ms 는 값 0 으로 유지(additive-compat). AssetChunked/AssetTimings 보존·정상 emit(3곳).

좋았던 판단

  • Metadata.aliases(문서 메타) vs Chunk.aliases(expansion) 경계 정확히 지킴.
  • read-side ALIAS_SUFFIX/strip_alias_suffix(ids/filters/vector.rs) 를 손대지 않아 기존 KB 의 잔존 sentinel 벡터가 검색 시 본문 chunk 로 graceful 매핑됨 — 옛 데이터 회귀 방지.
  • 9개 커밋이 crate 경계로 atomic 하게 분리돼 리뷰가 쉬움.

전체 테스트 1452 pass(작성자 보고) + 위 독립 검증으로 회귀 위험 낮음. 사용자 머지 권장.

회차 1 — 별칭 제거. 독립 검증 후 actionable 결함 0, 머지 동의(APPROVE). **독립 검증한 것** - `cargo clippy --workspace --all-targets -j 4 -- -D warnings` → exit 0 (리뷰어가 worktree 에서 재실행, 1m59s). - acceptance grep 잔존 0(`expansion::|ExpansionCfg|chunk_aliases|run_alias_query|merge_body_alias|ExpansionProgress|embed_aliases|is_nav_boilerplate`, `Chunk.aliases`). - `migrations/V013__drop_chunk_aliases.sql` 실재·정확: trigger → FTS 테이블 → 컬럼 DROP 순서, V010 무수정(freeze 준수), forward-only. **핵심 로직 diff 검토 (회귀 위험 영역)** - `kebab-search/lexical.rs`: 별칭 채널(`run_alias_query`/`merge_body_alias`/alias 분기) 제거 후 `raw_rows = run_query(...)` 직결 = pre-V010 body-only 동작 복원. `build_match_string_for_column`→`build_match_string`(`text` 고정) 원복. 깔끔. - `kebab-app/lib.rs`: expansion 루프·캐시·sentinel 벡터 임베딩 전부 제거, `expansion_ms = 0`(주석으로 wire 호환 명시). purge_vector_orphans 본문 경로 유지. - wire `ingest_progress.v1`: `expansion_progress` kind + 이제 고아가 된 `done` 프로퍼티까지 정합 제거. `expansion_ms` 는 값 0 으로 유지(additive-compat). `AssetChunked`/`AssetTimings` 보존·정상 emit(3곳). **좋았던 판단** - `Metadata.aliases`(문서 메타) vs `Chunk.aliases`(expansion) 경계 정확히 지킴. - read-side `ALIAS_SUFFIX`/`strip_alias_suffix`(ids/filters/vector.rs) 를 손대지 않아 기존 KB 의 잔존 sentinel 벡터가 검색 시 본문 chunk 로 graceful 매핑됨 — 옛 데이터 회귀 방지. - 9개 커밋이 crate 경계로 atomic 하게 분리돼 리뷰가 쉬움. 전체 테스트 1452 pass(작성자 보고) + 위 독립 검증으로 회귀 위험 낮음. 사용자 머지 권장.
altair823 merged commit 1dfab6dfc5 into main 2026-06-03 00:39:30 +00:00
altair823 deleted branch refactor/remove-doc-expansion 2026-06-03 00:39:32 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
claude-reviewer-01
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
altair823 claude-reviewer-01
No Assignees
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: altair823-org/kebab#202
Delete Branch "refactor/remove-doc-expansion"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?