fix(embed-candle): address round-1 review

- commit track-spec + meta-spec/plan into branch (HIGH: dangling `amends:` ref)
- inline parity evidence (cosine 1.0, max_abs_diff 2.01e-7) into HOTFIXES +
  release notes; drop refs to deleted IMPL_REPORT/SPIKE_REPORT (MEDIUM)
- model guard: reject non-e5-large `model` before the 2GB download so
  model_id() can't mislabel vectors (MEDIUM) + unit test
- parity test now covers BOTH query: and passage: prefixes (MEDIUM)
- guard encodings.first() index; document zero-attention/pooling invariant;
  clarify embed_batch prefixing doc (LOW)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

crates/kebab-embed-candle/src/lib.rs

@@ -46,6 +46,11 @@ const CANDLE_CACHE_SUBDIR: &str = "candle";
 /// onnxruntime path uses, just the safetensors variant candle can read.
 const HF_MODEL: &str = "intfloat/multilingual-e5-large";
 
+/// The only `config.models.embedding.model` value the candle adapter accepts
+/// (the e5-large weights `HF_MODEL` resolves to). Guards against silently
+/// downloading e5-large while `model_id()` reports a different name.
+const SUPPORTED_MODEL: &str = "multilingual-e5-large";
+
 /// Token truncation length (e5 was trained at 512).
 const MAX_LEN: usize = 512;
 
@@ -99,6 +104,22 @@ impl CandleEmbedder {
             }
         }
 
+        // 1b. Model guard. `HF_MODEL` is hard-coded (candle currently only wires
+        //     e5-large), so if the operator configured a *different* model name
+        //     we must NOT silently download e5-large and then label its vectors
+        //     with the configured name via `model_id()` — that would mislabel
+        //     `embedding_version` and corrupt a mixed index. Fail fast, before
+        //     the ~2GB download.
+        let want = config.models.embedding.model.as_str();
+        if want != SUPPORTED_MODEL && want != HF_MODEL {
+            anyhow::bail!(
+                "candle provider currently supports only '{SUPPORTED_MODEL}' (or \
+                 the HF id '{HF_MODEL}'), but config.models.embedding.model = \
+                 '{want}'. Use provider=fastembed for other models, or set \
+                 model = \"{SUPPORTED_MODEL}\"."
+            );
+        }
+
         // 2. Resolve `{data_dir}/models/candle/` exactly like the fastembed
         //    adapter resolves its own subdir.
         let data_dir = expand_path(&config.storage.data_dir, "");
@@ -177,8 +198,9 @@ impl CandleEmbedder {
         })
     }
 
-    /// Embed one batch (already prefixed) through the candle pipeline:
-    /// tokenize → forward → masked mean pool → L2 normalize.
+    /// Embed one batch of **already-prefixed** strings (the e5 `query:`/
+    /// `passage:` prefix is applied by the caller [`CandleEmbedder::embed`])
+    /// through the candle pipeline: tokenize → forward → masked mean pool → L2.
     fn embed_batch(&self, prefixed: &[String]) -> Result<Vec<Vec<f32>>> {
         let encodings = self
             .tokenizer
@@ -186,7 +208,13 @@ impl CandleEmbedder {
             .map_err(|e| anyhow::anyhow!("kb-embed-candle: encode_batch: {e}"))?;
 
         let bsz = encodings.len();
-        let seq = encodings[0].get_ids().len();
+        // `embed` already returns early on empty input and `.chunks()` never
+        // yields an empty slice, so this is currently unreachable — but guard
+        // the index so a future refactor can't turn it into a panic.
+        let Some(first) = encodings.first() else {
+            return Ok(Vec::new());
+        };
+        let seq = first.get_ids().len();
 
         let mut ids = Vec::with_capacity(bsz * seq);
         let mut mask = Vec::with_capacity(bsz * seq);
@@ -212,6 +240,9 @@ impl CandleEmbedder {
         // attention-mask-weighted mean pooling
         let mask3 = attn_f32.unsqueeze(2)?; // (b, seq, 1)
         let summed = hidden.broadcast_mul(&mask3)?.sum(1)?; // (b, hidden)
+        // counts ≥ 1 always: every input is e5-prefixed AND special tokens are
+        // added (encode_batch(_, true)), so no row has an all-zero mask. If that
+        // invariant ever breaks, broadcast_div would emit NaN vectors.
         let counts = mask3.sum(1)?; // (b, 1)
         let mean = summed.broadcast_div(&counts)?;
 
@@ -360,4 +391,26 @@ mod tests {
             "error must mention both dims, got: {msg}"
         );
     }
+
+    // ── model guard ──────────────────────────────────────────────────
+    // A non-e5-large model name must fail fast (BEFORE the ~2GB download),
+    // so we never download e5-large yet label its vectors with another name
+    // via model_id() — which would mislabel embedding_version.
+
+    #[test]
+    fn new_rejects_unsupported_model() {
+        let mut config = kebab_config::Config::defaults();
+        config.models.embedding.model = "multilingual-e5-small".to_string();
+        // num_threads defaults to 0, so no global rayon side effect here.
+        // `.err()` (not `expect_err`) avoids requiring `CandleEmbedder: Debug`
+        // — it holds a Mutex/Tokenizer and intentionally derives no Debug.
+        let err = CandleEmbedder::new(&config)
+            .err()
+            .expect("unsupported model must error");
+        let msg = format!("{err:#}");
+        assert!(
+            msg.contains("candle provider currently supports only"),
+            "expected model-guard error, got: {msg}"
+        );
+    }
 }

crates/kebab-embed-candle/tests/parity.rs

@@ -49,11 +49,14 @@ fn candle_matches_fastembed() {
     let candle = CandleEmbedder::new(&config).expect("build CandleEmbedder");
     let fastembed = FastembedEmbedder::new(&config).expect("build FastembedEmbedder");
 
+    // Cover BOTH prefix paths (`passage:` for Document, `query:` for Query) so
+    // a query-side prefix/pooling divergence can't slip through (reviewer note).
     let inputs: Vec<EmbeddingInput> = SENTENCES
         .iter()
-        .map(|s| EmbeddingInput {
-            text: s,
-            kind: EmbeddingKind::Document,
+        .flat_map(|s| {
+            [EmbeddingKind::Document, EmbeddingKind::Query]
+                .into_iter()
+                .map(move |kind| EmbeddingInput { text: s, kind })
         })
         .collect();
 
@@ -61,11 +64,12 @@ fn candle_matches_fastembed() {
     let fv = fastembed.embed(&inputs).expect("fastembed embed");
 
     assert_eq!(cv.len(), fv.len(), "embedding counts must match");
+    assert_eq!(cv.len(), inputs.len(), "one vector per input");
     assert_eq!(candle.dimensions(), 1024);
 
     let mut min_cos = f32::INFINITY;
     let mut max_abs_diff = 0f32;
-    for (i, s) in SENTENCES.iter().enumerate() {
+    for (i, inp) in inputs.iter().enumerate() {
         assert_eq!(cv[i].len(), 1024, "candle dim");
         assert_eq!(fv[i].len(), 1024, "fastembed dim");
         let c = cosine(&cv[i], &fv[i]);
@@ -76,8 +80,12 @@ fn candle_matches_fastembed() {
             .map(|(a, b)| (a - b).abs())
             .fold(0f32, f32::max);
         max_abs_diff = max_abs_diff.max(diff);
-        let preview: String = s.chars().take(40).collect();
-        println!("[{i:>2}] cos={c:.6} max_abs_diff={diff:.6e}  {preview}");
+        let kind = match inp.kind {
+            EmbeddingKind::Document => "doc",
+            EmbeddingKind::Query => "qry",
+        };
+        let preview: String = inp.text.chars().take(36).collect();
+        println!("[{i:>2}] {kind} cos={c:.6} max_abs_diff={diff:.6e}  {preview}");
     }
 
     println!("PARITY_SUMMARY cosine_min={min_cos:.6} max_abs_diff={max_abs_diff:.6e}");

docs/release-notes/v0.22.0-draft.md

@@ -69,4 +69,6 @@ double-free 경로를 원천 차단한다. NUMA 노드 바인딩이 더 필요
 
 듀얼소켓 NUMA 서버에서 `provider=candle` 로 5150-doc ingest 가 double-free
 없이 EXIT=0 완주하는지가 본 release 의 최종 인수 게이트다 (meta-spec §4.3).
-패리티 max abs diff 수치는 `IMPL_REPORT.md` 참조.
+패리티(candle vs onnxruntime): cosine_min = 1.000000, 차원별 max 절대오차 =
+2.01e-7 — 벡터가 사실상 동일하므로 `embedding_version` 유지(재색인 0). 재현은
+`crates/kebab-embed-candle/tests/parity.rs` (`--ignored`).

docs/superpowers/specs/2026-06-01-embed-candle-track-spec.md

@@ -0,0 +1,78 @@
+# Track 1 Spec — candle e5-large 임베딩 provider (NUMA-안전)
+
+- 날짜: 2026-06-01
+- 우산: [meta-spec](./2026-06-01-embedding-numa-backends-meta-spec.md) / [meta-plan](./2026-06-01-embedding-numa-backends-meta-plan.md)
+- 선행: Phase 0 스파이크 PASS+독립검증 (cosine 1.000000, 스레드 캡 가능, latency ~4×). 커밋 76841af.
+- 브랜치: `feat/embed-candle`
+
+## 1. 목표
+
+fastembed(onnxruntime) 의 "intra-op 스레드 48 하드코딩 → NUMA 힙 손상" 을 회피하기 위해, 동일 모델 `multilingual-e5-large` 를 **candle(순수 Rust)** 로 돌리는 임베딩 provider 를 추가한다. opt-in, 품질 중립, NUMA 스레드 캡 가능.
+
+## 2. 확정 결정 (사용자 승인 2026-06-01)
+
+- **D-reindex**: `embedding_version` **유지(재색인 0)** 를 목표. 구현 중 candle vs onnxruntime 벡터의 **차원별 max 절대오차**를 측정해 사실상 동일(예: max abs diff < 1e-5)함을 확인하고, 골든 스위트로 회귀 0 을 실측해 확정. 유의미한 차이가 나오면만 version bump + 재색인.
+- **D-default**: 글로벌 default provider 는 **onnxruntime 유지**, candle 은 **opt-in** (`models.embedding.provider = "candle"`).
+- **조기 종료**: candle 이 골든 baseline 충족 시 ollama/A2 트랙 생략 (A1 stopgap 문서만 별도).
+
+## 3. 아키텍처
+
+- **신규 crate `kebab-embed-candle`** — `kebab_core::Embedder` 구현. candle 의 큰 의존성 트리를 이 crate 에 격리.
+  - 허용 deps: `candle-core`/`candle-nn`/`candle-transformers` (0.10.x), `tokenizers`, `hf-hub`, `kebab-core`, `kebab-config`, `anyhow`, `tracing`. **다른 `kebab-*` 의존 금지**(core/config 외) — design §8 경계.
+- **주입 분기**: `kebab-app/src/app.rs` 의 `embedder()` (현 :829-837, `FastembedEmbedder::new` 무조건 생성) 를 `config.models.embedding.provider` 로 분기:
+  - `"fastembed"` | `"onnx"` | (빈값/기존) → `FastembedEmbedder` (default, 기존 동작 유지).
+  - `"candle"` → `CandleEmbedder`.
+  - 알 수 없는 값 → 명확한 에러.
+- **facade 규칙 준수**: UI crate 는 `kebab-app` 만. `kebab-app` 이 `kebab-embed-candle` 의존 추가.
+
+## 4. CandleEmbedder 동작 (스파이크에서 검증된 파이프라인)
+
+- 모델: `intfloat/multilingual-e5-large` 의 `model.safetensors` + `config.json` + `tokenizer.json` 을 `hf-hub` 으로 `{model_dir}/candle/` (config `storage.model_dir`) 아래에 캐시.
+- `candle_transformers::models::xlm_roberta::{Config, XLMRobertaModel}` 로 로드 (CPU `Device::Cpu`).
+- `embed()`: e5 프리픽스(`query: `/`passage: `, `EmbeddingInput` kind 기준 — `kebab-embed-local` 의 `prefix_input` 규약과 동일) → 토크나이즈(max_len 512, batch-longest 패딩, special tokens) → forward → **attention-mask 가중 mean pooling** → **L2 정규화**.
+- `dimensions()` = 1024, `model_id`/`model_version` = config 값(기존과 동일 식별자 유지).
+- **스레드 캡**: config 신규 필드 `models.embedding.num_threads`(u32, 0=auto) + env `KEBAB_EMBED_THREADS`. `CandleEmbedder::new` 에서 `rayon::ThreadPoolBuilder::new().num_threads(n).build_global()` 1회 적용(이미 초기화 시 무시). 0/auto 면 미설정(rayon 기본). NUMA 노드 바인딩은 `numactl`(A1) 과 조합 — 문서화.
+- `Mutex<XLMRobertaModel>` 또는 forward 가 `&self` 면 불필요 — candle forward 는 `&self` 가능, 단 내부 가변 없으면 `Send+Sync` 보장 확인.
+
+## 5. config 변경
+
+- `EmbeddingModelCfg` 에 `num_threads: u32`(default 0) 추가. env `KEBAB_EMBED_THREADS`.
+- `provider` 허용값 문서화: `fastembed`(default)/`candle`.
+- default toml + `Config::default()` 갱신, 기존 테스트 영향 확인.
+
+## 6. 버전/캐스케이드
+
+- D-reindex 에 따라 `embedding_version` 유지 (벡터 동일). cascade(design §9) 트리거 안 함 — 기존 색인 재사용. (max abs diff 확인 실패 시에만 bump.)
+- wire schema 변경 없음.
+
+## 7. 테스트 (산출물)
+
+- **단위**(`kebab-embed-candle`): `dimensions()==1024`; `embed()` 출력 L2≈1; 빈 입력 빈 출력; 프리픽스 적용 확인.
+- **패리티 테스트**(`#[ignore]`, 모델 2GB+네트워크 필요): candle vs `FastembedEmbedder` 동일 문장 cosine ≥ 0.9999 + max abs diff 보고. CI 기본 제외, 수동/도그푸딩에서 실행.
+- **통합**(`kebab-cli` 또는 `kebab-app`): `provider="candle"` 로 소량 fixture ingest → 청크/임베딩 카운트 > 0, 검색 1건 성공. (모델 필요 → `#[ignore]` 또는 feature.)
+- **스레드 캡**: `num_threads=4` 설정 시 `rayon::current_num_threads()==4` 확인.
+- **회귀**: 기존 fastembed 경로 default 동작 불변(provider 미지정 시).
+- clippy `-D warnings`, 빌드 직렬 `-j 4`.
+
+## 8. 품질 게이트 (머지 전)
+
+- `kebab-eval` 골든 스위트(`/build/dogfood/golden_queries.yaml`) 를 provider=candle 로 실행 → MRR/hit@k ≥ 현 baseline (회귀 0). [[feedback_search_quality_dogfood]]
+- 패러프레이즈 robustness(#195/#196) 스폿 확인.
+
+## 9. 문서/릴리스 (머지 시 동일 PR)
+
+- README: Configuration 에 `provider=candle` + `num_threads`/`KEBAB_EMBED_THREADS` 추가. SMOKE config 예시 동기화. [[feedback_readme_sync_rule]]
+- ARCHITECTURE: crate 그래프 + 디렉터리에 `kebab-embed-candle` 추가.
+- HANDOFF: 머지 후 한 줄(임베딩 백엔드 다변화).
+- HOTFIXES: 본 날짜 dated entry (NUMA double-free 진단 + candle provider 도입 + 스파이크 패리티 증거).
+- 버전 bump: 신규 config surface(provider=candle, num_threads) = pre-1.0 minor bump (0.21.1 → 0.22.0), release notes.
+
+## 10. 범위 밖 / 후속
+
+- candle crate feature-gate 로 빌드 비용 격리 (후속).
+- NUMA 노드 자동 바인딩(현재는 numactl 외부 조합).
+- ollama/A2/A1 트랙 (candle 게이트 통과 시 생략).
+
+## 11. 잔여 게이트 (사용자 실행, Claude 불가)
+
+- 그 듀얼소켓 NUMA 서버에서 `provider=candle` 로 5150-doc ingest **double-free 없이 EXIT=0 완주**. PR 머지 전/후 검증 예약. (meta-spec §4.3)

docs/superpowers/specs/2026-06-01-embedding-numa-backends-meta-plan.md

@@ -0,0 +1,77 @@
+# Meta-Plan — NUMA-안전 임베딩 백엔드 실행 계획
+
+- 날짜: 2026-06-01
+- 우산 스펙: [2026-06-01-embedding-numa-backends-meta-spec.md](./2026-06-01-embedding-numa-backends-meta-spec.md)
+- 실행 모델: 트랙별 worktree 격리 + omc teammate (omc-teams, sequential single-team). 트랙 내 단계는 spec → plan → 구현 → 테스트 → PR.
+
+## 0. 즉시 (본 계획과 병행, 무코드)
+
+- **A1 stopgap 문서화 + 사용자 제공**: `numactl --cpunodebind=0 --membind=0 kebab ingest` (또는 `taskset -c 0-11`). 현재 불통 해소용. 이건 트랙 4의 산출물 일부지만 지금 바로 안내.
+- 사용자 NUMA 서버에서 A1 로 5150-doc 완주되는지 1회 확인 → "스레드/NUMA 가 원인" 인과 확정(메타스펙 §1 보강).
+
+## 1. 트랙 실행 순서 & 게이트
+
+`candle → ollama → A2 → A1(정식 문서화)`. 한 트랙의 PR open + NUMA 검증 예약 전까지 다음 트랙 미착수.
+
+**조기 종료 (D1 확정)**: candle 또는 ollama 가 허용 품질(골든 ≥ baseline 무회귀) + NUMA 안전을 만족하면 **거기서 종료**, 이후 트랙 미진행. 둘 다 품질 미달 시에만 A2 → A1 진행. candle 은 동일 e5-large 라 패리티 통과 시 종착 유력.
+
+### 트랙 1 — candle (`feat/embed-candle`)
+
+- **Phase 0 — 타당성 스파이크 (게이트, 최우선)**
+  - worktree 에서 candle + candle-transformers 의존성 추가, `xlm_roberta::XLMRobertaModel` 로 `intfloat/multilingual-e5-large` safetensors 로드 (CPU).
+  - 몇 개 문장 임베딩 → (a) onnxruntime e5-large 벡터와 cosine 패리티, (b) CPU latency, (c) `RAYON_NUM_THREADS` 로 스레드 캡 동작, (d) padding_idx 위치 임베딩 정확성.
+  - 산출: 스파이크 리포트(패리티 수치 + latency + 스레드 제어 확인). **통과해야 Phase 1 진행.**
+- **Phase 1 — spec**: 트랙 spec 작성 (Embedder 구현, config provider="candle", embedding_version, 재색인 절차, 테스트 매트릭스).
+- **Phase 2 — plan**: 구현 plan.
+- **Phase 3 — 구현**: `kebab-embed-candle`(신규 crate) 또는 `kebab-embed-local` 내 provider 분기. Embedder 구현 + app.rs 주입 분기 + config.
+- **Phase 4 — 테스트**: 단위/통합 + 패리티 + 골든. 빌드는 직렬 `-j 4`.
+- **Phase 5 — PR + 검증**: gitea PR. 사용자 NUMA 서버 5150-doc 완주 + 골든 baseline 확인.
+
+### 트랙 2 — ollama (`feat/embed-ollama`)
+
+- spec → plan → 구현(`OllamaEmbedder`: `/api/embed` 호출, provider="ollama", 모델 선택[e5 GGUF 또는 bge-m3]) → 테스트(패리티/골든, 프로세스 격리로 double-free 부재) → PR + NUMA 검증.
+
+### 트랙 3 — A2 (`feat/embed-ort-direct`)
+
+- spec → plan → 구현(fastembed 우회, `ort` 세션 직접 + `with_intra_threads(N)` + NUMA affinity, 토크나이즈/mean-pool/L2 재현, provider="onnx" 기본 유지) → 테스트(기존 e5 벡터와 cosine≈1.0, 재색인 0) → PR + NUMA 검증.
+- **품질-중립 안전망**: 재색인 없이 즉시 default 가능.
+
+### 트랙 4 — A1 정식화 (`docs/embed-numa-affinity`)
+
+- 런처 래핑/문서 + (선택) config 노브로 affinity 힌트. README/SMOKE/HOTFIXES 동기화.
+
+## 2. omc teammate 운용 (메모리 규약 준수)
+
+- spawn: omc-teams tmux pane + brief 파일. **sequential single-team** (multi-team 동시 spawn 금지).
+- 모델 라우팅: executor + initial draft + round-1 review = **opus**; closure verify / micro-patch round = **sonnet**. (`OMC_TEAM_ROLE_OVERRIDES` env)
+- worker spawn 직후 completion polling shell `run_in_background=true` (phase=completed/failed 감지 → main session 자동 알림).
+- 빌드/테스트 직렬, `-j 4` 기본. `CARGO_TARGET_DIR=/build` 사용 (routinely clean 금지).
+
+## 3. 워크트리 / 브랜치
+
+| 트랙 | 브랜치 | worktree |
+|---|---|---|
+| 1 candle | `feat/embed-candle` | 신규 |
+| 2 ollama | `feat/embed-ollama` | 신규 |
+| 3 A2 | `feat/embed-ort-direct` | 신규 |
+| 4 A1 | `docs/embed-numa-affinity` | 신규 |
+
+각 트랙 머지 후 다음 트랙 rebase. 트랙 간 공유 상태 없음(독립 provider).
+
+## 4. 리스크 레지스터
+
+- candle Phase 0 패리티 실패 → 트랙 1 강등, ollama 우선.
+- candle CPU latency 가 onnxruntime 대비 과도 → opt-in provider 로만.
+- ollama 모델이 e5 아님 → 골든 회귀 가능 → default 승격 보류.
+- NUMA 검증이 사용자 가용성에 의존 → 각 PR 은 검증 전까지 "merge-pending".
+- ort rc.9 자체 버그가 A2 에서도 재현 가능성 → A2 스레드 캡으로도 안 죽는지 NUMA 검증 필수.
+
+## 5. 진행 상태 (라이브)
+
+- [x] candle 타당성 desk-research (xlm_roberta 모듈 존재 + cembedd 선례) — 2026-06-01
+- [ ] A1 stopgap 사용자 NUMA 서버 확인
+- [x] 트랙 1 Phase 0 스파이크 — **VERDICT=PASS** (2026-06-01). cosine min=mean=1.000000(onnxruntime 동일), RAYON 스레드 캡 가능, latency ~4×(67.5 vs 16.8 ms/문장, 4 vs 12 스레드). 커밋 76841af. → **조기 종료 유력**: candle 이 품질 baseline 자동 충족 → ollama/A2/A1 불필요 전망. 잔여 게이트=골든 실측 + NUMA 서버 5150-doc 완주.
+- [ ] 트랙 1 spec/plan/impl/test/PR (진행)
+- [ ] 트랙 2 …
+- [ ] 트랙 3 …
+- [ ] 트랙 4 …

docs/superpowers/specs/2026-06-01-embedding-numa-backends-meta-spec.md

@@ -0,0 +1,102 @@
+# Meta-Spec — NUMA-안전 임베딩 백엔드 (다중 트랙)
+
+- 날짜: 2026-06-01
+- 상태: DRAFT (umbrella)
+- 범위: `kebab-embed-local` 및 임베더 주입 경로. 4개 트랙의 우산 스펙.
+- 하위 산출물: 각 트랙은 본 메타스펙을 참조하는 자체 spec(`tasks/` 또는 `docs/superpowers/specs/`)과 plan을 가진다.
+
+## 1. 문제
+
+CPU-only Ollama 서버(Intel Xeon Silver 4214 ×2 소켓 = 48 logical, NUMA 2노드)에서 `kebab ingest` 가 매 실행 힙 손상으로 죽는다:
+
+```
+ingest [>     ] 3/5150  double free or corruption (!prev)
+중지됨 (core dumped)
+```
+
+근본 원인(코드로 확정): fastembed 4.9.1 (`text_embedding/impl.rs:52,80`) 이 ONNX intra-op 스레드를 `available_parallelism()`(=48) 로 **하드코딩**하고 `InitOptions` 에 이를 덮어쓸 API 가 없다. 듀얼소켓 NUMA 에서 onnxruntime(`ort 2.0.0-rc.9`) 스레드풀이 힙을 손상시킨다. 진단 근거: `tasks/HOTFIXES.md` 의 본 날짜 entry + 대화 로그.
+
+- 모델/디스크/AVX/데이터 문제 아님 (모델 2.08GB 정상, AVX-512 완비). 순수 스레드/NUMA × 네이티브 런타임 버그.
+- onnxruntime 공식 문서도 듀얼소켓 NUMA 는 intra-op 스레드를 한 노드로 묶으라고 권고.
+
+## 2. 목표 / 비목표
+
+목표:
+- 그 NUMA 서버에서 5150-doc 코퍼스를 **double-free 없이 완주**하는 임베딩 경로 확보.
+- 검색 품질을 골든 스위트(MRR/hit@k) baseline 이상으로 유지.
+- `models.embedding.provider` 로 선택 가능한 백엔드들로 구현 (기존 provider 필드 활용).
+
+비목표:
+- 랭킹 자동 조정 (별도 보류 결정, `[[project_ranking_deferred]]`).
+- 임베딩 모델 품질 개선 자체 (NUMA 안정성이 본 과제의 초점).
+- GPU 경로.
+
+## 3. 공유 아키텍처
+
+- 교체 지점은 **단일**: `crates/kebab-app/src/app.rs:836` 의 `FastembedEmbedder::new(&config)`.
+- 트레이트 표면이 작다: `kebab_core::Embedder` (`traits.rs:127`) — `model_id / model_version / dimensions / embed`. 새 백엔드는 이 4개만 구현.
+- 설정: `models.embedding.provider` (이미 존재), `model`, `version`, `dimensions`, `batch_size`. 신규로 트랙별 스레드/affinity 노브 추가 가능.
+
+## 4. 횡단 정책 (모든 트랙 공통)
+
+### 4.1 embedding_version & 재색인
+- 벡터가 바뀌면(=candle, ollama) **`embedding_version` bump → 전체 재색인** (design §9 cascade). A2/A1 은 동일 onnxruntime e5-large 라 벡터 불변 → 재색인 불필요.
+- 재색인 비용/절차를 각 트랙 spec 에 명시.
+
+### 4.2 품질 검증 (필수 게이트)
+- 벡터가 바뀌는 트랙은 머지 전 `kebab-eval` 골든 스위트(`/build/dogfood/golden_queries.yaml`) 로 MRR/hit@k 측정, **baseline 이상**이어야 default 승격. baseline 미달이면 opt-in provider 로만 유지.
+- 패러프레이즈 robustness(#195/#196) 회귀 확인.
+
+### 4.3 NUMA 서버 검증 (필수 게이트, 사용자 실행)
+- **결정적 증거는 그 서버에서만 난다 (Claude 접근 불가).** 각 트랙은 사용자가 그 서버에서 5150-doc 코퍼스 ingest 를 **double-free 없이 완주(EXIT=0)** 함을 확인해야 "검증 완료".
+- 각 트랙 spec 에 사용자-실행 검증 절차(명령 + 기대 출력)를 문서화.
+
+### 4.4 스레드/NUMA 제어
+- 각 백엔드가 intra-op/worker 스레드를 캡하고 한 NUMA 노드로 묶을 수 있어야 함. 캡 못 하면 트랙 실패.
+
+## 5. 트랙
+
+선호/구현 순서: **candle → ollama → A2 → A1**. (단 A1 은 무코드 stopgap 이라 즉시 문서화해 당장의 불통을 해소; 구현 순서와 별개.)
+
+| # | 트랙 | 백엔드 | 벡터 변경(재색인) | 핵심 리스크 | 격리 브랜치 |
+|---|------|--------|----|------|------|
+| 1 | candle | 순수 Rust (candle `xlm_roberta`) | 예 | XLM-R padding_idx/패리티/CPU 성능 | `feat/embed-candle` |
+| 2 | ollama | 별 프로세스 (Ollama `/api/embed`) | 예 | 모델이 e5 아님→품질, ingest 가 Ollama 의존 | `feat/embed-ollama` |
+| 3 | A2 | onnxruntime 직접(`ort` 세션) | 아니오 | fastembed 우회 후 토크나이즈/풀링 재현 정확도 | `feat/embed-ort-direct` |
+| 4 | A1 | onnxruntime + 실행 래핑(taskset/numactl) | 아니오 | 코드 변경 거의 없음, 문서/런처만 | `docs/embed-numa-affinity` |
+
+### 5.1 트랙별 테스트 매트릭스 (각 트랙 spec 에서 구체화)
+
+모든 트랙:
+- 단위: `embed()` 가 올바른 dim/정규화(L2≈1) 벡터 반환.
+- 통합: `kebab ingest` 소량 fixture → 청크/임베딩 카운트.
+- **NUMA 서버 검증**(§4.3): 5150-doc 완주.
+
+벡터-변경 트랙(candle/ollama) 추가:
+- 패리티: onnxruntime e5-large 대비 동일 입력 cosine 유사도(가능 시) 또는 골든 스위트 동등성.
+- 골든: MRR/hit@k ≥ baseline (§4.2).
+- 재색인 절차 검증.
+
+벡터-불변 트랙(A2/A1) 추가:
+- 회귀: 기존 e5-large 벡터와 cosine ≈ 1.0 (A2 는 같은 런타임이라 사실상 동일해야).
+
+## 6. 결정사항 (확정 2026-06-01)
+
+- **D1 조기 종료 (사용자 확정)**: 트랙을 선호 순서로 진행하되, candle 또는 ollama 가 **허용 품질 기준 + NUMA 안전**을 만족하면 **거기서 멈춘다** (이후 트랙 미진행). 둘 다 품질이 너무 낮으면 A2 → A1 까지 계속.
+  - **허용 품질 기준**: 골든 스위트 MRR/hit@k 가 현 e5-large(onnxruntime) baseline 대비 유의미한 회귀 없음. candle 은 동일 e5-large 가중치라 패리티 통과 시 이 기준을 거의 자동 충족 → candle 이 종착 가능성 높음. ollama 는 모델이 달라 경계선이면 사용자 판단.
+  - A2/A1 은 candle·ollama 둘 다 실패 시의 **fallback** (A2 는 재색인 0 품질-중립).
+- **D2 즉시 완화**: A1(taskset/numactl) 은 무코드라 본 작업과 무관하게 지금 바로 사용자에게 워크어라운드로 제공.
+- **D3 메타 산출물 위치**: 본 메타스펙 + 메타플랜은 `docs/superpowers/specs/`. 트랙별 spec 은 도달 시 작성.
+- **D4 frozen design 영향**: 임베딩 백엔드 다변화는 design §(임베딩) 갱신 가능 — 트랙 머지 시 동기화.
+
+## 7. 성공 기준
+
+- 그 NUMA 서버에서 최소 1개 트랙이 5150-doc 완주(EXIT=0).
+- default 로 승격되는 백엔드는 골든 baseline 이상.
+- 각 트랙이 자체 브랜치/워크트리 + 문서화된 테스트로 독립 검증.
+
+## 8. 시퀀싱 게이트
+
+1. candle **스파이크**(Phase 0) 가 패리티+CPU 성능+스레드 제어를 입증해야 candle 본 구현 진행. 실패 시 candle 트랙 강등/스킵 후 ollama 로.
+2. 각 트랙은 PR open + NUMA 서버 검증 예약 후 다음 트랙 시작 (omc-teams sequential single-team 제약).
+3. 벡터-변경 트랙은 골든 게이트 통과 전 default 승격 금지.

tasks/HOTFIXES.md

@@ -27,9 +27,9 @@ config 로 줄일 surface 가 없었고, fastembed 4.9 의 ORT 바인딩은 이
 provider 를 추가하기로 결정. candle 의 CPU 백엔드는 글로벌 rayon 풀 크기로
 스레드를 정하므로, 한 번의 `rayon::ThreadPoolBuilder::build_global` 캡으로
 스레드를 NUMA-안전한 수로 묶을 수 있다. **재색인 0 목표**(`embedding_version`
-유지) — Phase 0 스파이크(`SPIKE_REPORT.md`, 커밋 76841af)가 candle vs
-onnxruntime **코사인 1.000000** 패리티를 입증했고, 본 Track 1 구현의 패리티
-테스트로 차원별 max 절대오차를 재실측해 확정.
+유지) — Phase 0 스파이크(커밋 76841af)가 candle vs onnxruntime **코사인
+1.000000** 패리티를 입증했고, 본 Track 1 구현의 패리티 테스트로 차원별 max
+절대오차를 재실측해 확정.
 
 **무엇을 건드렸나.**
 - 신규 crate `crates/kebab-embed-candle` — `kebab_core::Embedder` 구현
@@ -46,9 +46,12 @@ onnxruntime **코사인 1.000000** 패리티를 입증했고, 본 Track 1 구현
 - 스파이크 crate `crates/spike-embed-candle` 제거(학습은 production 으로 흡수됨).
 - 버전 0.21.1 → **0.22.0** (신규 config surface — pre-1.0 minor bump).
 
-**패리티 증거.** Phase 0 스파이크 cosine 1.000000 (10문장 한/영 혼합). 본
-Track 1 의 `#[ignore]` 패리티 테스트 결과(max abs diff)는
-`/build/out/kebab-worktrees/embed-candle/IMPL_REPORT.md` 에 기록.
+**패리티 증거.** candle vs `FastembedEmbedder`(onnxruntime), 동일 10문장
+(한/영 혼합, e5 `passage:`/`query:` prefix): **cosine_min = 1.000000,
+차원별 max 절대오차 = 2.01e-7** (f32 커널 반올림 수준 — 랭킹 영향 임계보다
+약 50배 작음). 재현: `cargo test -p kebab-embed-candle --release -- --ignored
+--nocapture` (`crates/kebab-embed-candle/tests/parity.rs`, 모델 ~2GB 필요라
+CI 기본 제외). 이 수치가 `embedding_version` 유지(재색인 0) 결정의 근거.
 
 **호환성.** fastembed default 경로의 동작/벡터 불변. `embedding_version`
 유지 → 기존 색인 재사용(재색인 0). wire schema 변경 없음. 옛 config.toml 은