併 bge-m3 換代（#59）＋補上分支漏做的另一半：Vectorize index 也換

leo 2026-08-05：「換 embed model 當然要合併，當然要換 vectorize，**原本的根本不能用**」
——我把已拍板的事當成待裁決，錯了。

## 為什麼非換不可（08-03 leo 拍板，5 組中文測資實證）
  @cf/baai/bge-base-en-v1.5   768   排序正確 2/5   margin -0.0413   1660ms  ← 舊
  @cf/baai/bge-m3            1024        5/5        +0.1410    959ms  ← 新
舊英文模型嵌中文：分數全擠在 0.65-0.81，區辨力接近沒有＝**根本不能用**。

## 🔴 分支只做了一半，另一半我補上
feat/embed-model-m3-t59 只改 kbdb（embed.ts / types.ts / 測試），**完全沒動 deploy.ts**
⇒ 就算合併，安裝器仍會建 **768 維的舊 index**，新向量根本收不進去。
（git show f3af5d3 --stat 實查：只有 3 個檔，全在 kbdb/）

本次補上安裝器那半：
· KBDB_VECTORIZE_INDEX: arcrun-kbdb-embed → **arcrun-kbdb-embed-m3**（換名字，非只換維度）
· ensureVectorizeIndex: dimensions 768 → **1024**
· kbdb/wrangler.toml 說明與 metadata-index 指令同步改新名（照抄不會建錯 index）
· embed.ts docstring「768 維向量」→ 1024（分支漏改，會誤導）

## 為什麼要換「名字」不是只改維度
① 維度 768→1024，舊 index 收不進新向量
② 就算維度相同也不能沿用——不同模型的向量混在同一 index 比對出來是垃圾，
   而 #58（Vectorize vector delete 未接）代表舊向量刪不掉
   ⇒ **開新名字反而順手繞開 #58**，且新舊並存可回滾。

## 查證（歷史警察 Q0-Q3，非假設）
· git log --all -S"arcrun-kbdb-embed-m3" / -S"dimensions: 1024" 皆空 ⇒ 無分支改過，非重造輪子
· **metadata index 用同一個常數**（deploy.ts:426 ensureVectorizeMetadataIndexes）
  ⇒ t36 的四個 metadata index（owner_id/entry_type/source/library，Arcrun#11 根因修復）
  會自動建在新 index 上，**不會因改名而遺失**——這點特地查過，不是假設。

## 驗
· kbdb 測試 87/87 綠（含新增 4 項 embed-model-config）
· cli tsc --noEmit **零錯誤**
· 三處一致性機械確認：embed.ts=bge-m3／deploy.ts=dimensions 1024／index=arcrun-kbdb-embed-m3
· 踩到並記錄：註解寫 `**dimensions=1024**​/metric` 會因 `*/` 提早關掉 block comment（TS1127）

## 既有實例遷移（尚未執行，需對實例操作）
建新 index → 重部署 kbdb（binding 指新 index）
→ POST /embed/backfill {"reindex":true} 到 remaining=0 → 舊 index 可刪。

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

cli/src/lib/deploy.ts

@@ -163,8 +163,27 @@ export interface DeployContext {
   kbdbEmbed?: boolean;
 }
 
-/** Vectorize index 名（kbdb embed 模組用）。bge-base-en-v1.5 = 768 維、cosine。 */
-export const KBDB_VECTORIZE_INDEX = 'arcrun-kbdb-embed';
+/**
+ * Vectorize index 名（kbdb embed 模組用）。**bge-m3 = 1024 維、cosine。**
+ *
+ * 🔴 2026-08-03 換代（leo 拍板；5 組中文測資實證：舊 `bge-base-en-v1.5` 排序 2/5、
+ *   margin −0.0413＝**中文根本不能用**；`bge-m3` 5/5、+0.1410、959ms）。
+ *   leo 08-05：「換 embed model 當然要合併，當然要換 vectorize，原本的根本不能用」。
+ *
+ * **換模型必須換 index，且必須換「名字」**：
+ *   ① 維度 768→1024，舊 index 收不進新向量
+ *   ② 就算維度相同也不能沿用——不同模型的向量混在同一 index，比對出來是垃圾；
+ *      而 #58（Vectorize vector delete 未接）代表舊向量刪不掉
+ *      ⇒ **開新名字的 index 反而順手繞開 #58**，且新舊並存可回滾。
+ *
+ * ⚠️ 這個常數同時被 `ensureVectorizeMetadataIndexes()` 使用（deploy.ts:426）
+ *   ⇒ t36 的四個 metadata index（owner_id/entry_type/source/library，Arcrun#11 根因修復）
+ *   會自動建在新 index 上，**不會因為改名而遺失**（已查證，非假設）。
+ *
+ * 既有實例遷移：部署後 `POST /embed/backfill {"reindex":true}` 重嵌到 remaining=0，
+ * 確認語意查詢正常後，舊的 `arcrun-kbdb-embed` 可自行刪除。
+ */
+export const KBDB_VECTORIZE_INDEX = 'arcrun-kbdb-embed-m3';
 
 export interface DeployResult {
   implemented: boolean;
@@ -388,7 +407,9 @@ async function applyD1Migration(ctx: DeployContext, sql: string): Promise<void>
 
 /**
  * 確保 KBDB embed 用的 Vectorize index 存在（issue #7 / T2.4）。
- * REST `POST /accounts/{id}/vectorize/v2/indexes`（dimensions=768/metric=cosine，對齊 bge-base-en-v1.5）。
+ * REST `POST /accounts/{id}/vectorize/v2/indexes`（dimensions=1024 / metric=cosine，對齊 bge-m3）。
+ * ⚠️ 這行別寫成 `**dimensions=1024**​/metric`——`*` 緊接 `/` 會提早關掉 block comment（實撞 TS1127）。
+ * 維度必須與 `kbdb/src/embed.ts` 的 `DEFAULT_EMBED_MODEL` 一致——不一致時 upsert 直接被 CF 拒絕。
  * 冪等：已存在（CF 回「already exists」類錯）視為成功，不報錯。用 init 已驗的 apiToken+accountId。
  */
 async function ensureVectorizeIndex(ctx: DeployContext): Promise<void> {
@@ -398,8 +419,8 @@ async function ensureVectorizeIndex(ctx: DeployContext): Promise<void> {
     headers: { Authorization: `Bearer ${ctx.apiToken}`, 'Content-Type': 'application/json' },
     body: JSON.stringify({
       name: KBDB_VECTORIZE_INDEX,
-      config: { dimensions: 768, metric: 'cosine' },
-      description: 'arcrun KBDB optional embed module (issue #7)',
+      config: { dimensions: 1024, metric: 'cosine' },
+      description: 'arcrun KBDB embed module — bge-m3 1024d (issue #7 / #59)',
     }),
     signal: AbortSignal.timeout(60_000),
   });