Arcrun/docs/HANDOFF-matrix-rearrange.md

HANDOFF: Matrix 重整交棒給 arcrun（2026-06-13）

來源：InkStoneCo 頂層 .agents/specs/matrix-rearrange/。本檔是該重整交給 arcrun 的待辦清單。 指針式考古：整合素材真身在 InkStoneCo _archive/，照路徑去挖，不複製進此檔。

---

1. cypher-executor 整合進 arcrun 後關掉（leo 2026-06-13：整合後只剩 arcrun）

matrix/cypher-executor 是 diverged 副本，整合進 arcrun/cypher-executor 後就關掉/封存，之後 cypher 只有 arcrun 一份。

如何整合（勘查 2026-06-13）

A. matrix 版獨有、arcrun 缺的 5 檔 → 補進 arcrun（皆非 SaaS 遺留，是 self-hosted 核心）：

• src/actions/version-selector.ts：零件版本選擇策略 floating/stable/pinned
• src/actions/autoPublishMissing.ts：missing 零件用 Workers AI 自動生成上架
• src/lib/component-dispatcher.ts：雙模式路由 wasm/cypher_binding/service_binding
• src/lib/wasm-executor.ts：WASM 執行
• src/routes/proxy.ts：proxy 路由

B. 兩邊都有但內容不同的 10 檔 → 逐檔比對合併（取較完整/正確的一邊，保留 arcrun 較新的 auth 演進）： cypher-handlers / execution-evaluator / execution-logger / graph-builder / search-nodes / triplet-parser / webhook-graph-resolver / webhook-handlers / graph-executor / index

C. 保留 arcrun 獨有的（不要被舊版覆蓋）：credential-injector / auth-dispatcher / auth-recipe-seeds / api-recipe-seeds（arcrun 較新的 Auth Recipe 演進）。

素材真身：matrix/cypher-executor/（降級後仍在原地）。整合完成、驗證通過後，封存 matrix/cypher-executor 進 _archive/，cypher 之後只有 arcrun 一份。先讀對應 SDD 再動。

2. KBDB 插件化 + 補 CLI/MCP 薄殼（arcrun 端只留基本盤 + 暴露能力）

arcrun/kbdb 留 3 表基本盤 + API（已完整：templates/entries/records/search）。它是刻意設計的基本盤（0001_base.sql 註釋 plugin model），不升 v3、不加 blocks 表。triplet/graph 由 matrix/kbdb-graph-plugin 抽成獨立 repo KBDB-graph。

KBDB 鐵律（leo 2026-06-14）：任何人不准動表；新類型=建 template（走 API）；插件/AI/人全走 API，禁 SQL；基本盤不提供建表 API。詳見頂層 DECISION-kbdb-v3-baseplane.md。

arcrun 端待辦（核實：CLI/MCP 現在完全沒 KBDB 能力）：

• 補 MCP 薄殼（AI 用，含插件）：kbdb_create_template(name+slots)、kbdb_create_record(填 slot)、kbdb_query/kbdb_search 等，調基本盤現有 API。不提供建表 tool，只給 template/slot——類 Supabase 萬用表，AI 想建表時只有 template/slot 可用。
• 補 CLI 薄殼（人用，後補）：對應命令。
• 能力真身在基本盤 API（已有），CLI/MCP 只薄殼暴露（arcrun 薄殼原則）。

對方交棒見 matrix/kbdb-graph-plugin/docs/HANDOFF-kbdb-plugin.md。

3. leo21c self-hosted 部署（Mira dogfood 用）

leo 用 leo21c CF 帳號部署 self-hosted arcrun（MULTI_TENANT=false），Mira 改 dogfood 這套。 依現有 scripts/local-deploy.sh + docs/3-specs/arcrun/sdk-and-website/self-hosted-init.md。namespace 明碼非 api key。

3b. ⚠️ MCP self-hosted 認證失敗（mira CC 2026-06-14 回報，跨專案問題）

一句話：MCP worker 還走舊 partner-key 認證（mcp/src/middleware/partner-auth.ts，每個端點都掛 partnerAuthMiddleware），但 self-hosted 認證是 namespace 明碼。導致 Claude Code 連 self-hosted MCP 一律 401。CLI 全通（走 cypher-executor，已支援 MULTI_TENANT=false）。

根因：MCP 的 partner-auth.ts 沒跟上 cypher-executor 的 self-hosted 認證改版。這是 07-thin-shell.md §4 已記的「MCP 帳號來源違反」的具體症狀（SDD proposal 已存在：docs/3-specs/arcrun/sdk-and-website/mcp-account-source.md）。

診斷證據（curl arcrun-mcp.leo21c.workers.dev/mcp，mira CC 實測）：

• GET /mcp → 200（worker 活）；MCP initialize 無 auth → 401；Bearer ak_（舊 uncle6 key）→ 401 Invalid partner key；Bearer leo（namespace 明碼）→ 401；X-Namespace header → 401
• cypher-executor / → 200（CLI 走這條，通）
• acr mcp-setup 生成的 .mcp.json 是裸的（無 headers），就算有 key 也沒地方帶

修法（三選一，arcrun 端決策）：

1. MCP worker 加 self-hosted 認證：接受 namespace 明碼（與 cypher-executor 一致），或 self-hosted 模式 MCP 免 partner key。
2. acr mcp-setup 把有效認證寫進 .mcp.json headers（前提：self-hosted 有可用 key 機制）。
3. 對齊完成前，官方文件明說 self-hosted MCP 暫不可用、請用 CLI（避免使用者困惑）。

影響範圍：任何 self-hosted dogfood（mira、未來 product）都踩，非 mira 獨有。屬 arcrun 框架側待修，走 SDD 協議（對應 mcp-account-source.md，動工前宣告）。 mira 現況：全靠 acr CLI 即可推進，不卡。.mcp.json 留著等上游修好自動能連。

---

3b-2. ⚠️ 第一次端到端實測：修補 code 對，但 MULTI_TENANT 沒注入 MCP worker（2026-06-14 晚，mira 推 leo21c + 總管核實）

mira 把 release@main 推上 leo21c（deployment 14:31，version 7de919d6），仍 401 Invalid or expired partner key。總管核實了真因（不是 code bug，是部署機制 bug）：

• ✅ 修補 code 在且正確：mcp/src/middleware/partner-auth.ts:19 if (c.env.MULTI_TENANT === 'false') 確實擋在 partner-key 查詢之前。
• ☠️ 真因：mcp/wrangler.toml 的 MULTI_TENANT = "false" 是注釋掉的（第 13-14 行 # [vars] / # MULTI_TENANT）。部署後 worker 的 c.env.MULTI_TENANT === undefined ≠ 'false' → if 不成立 → 走 partner-key 查詢 → 401。
• 🔍 更深層：self-hosted 部署（acr init/acr update）沒把 MULTI_TENANT=false 注入 MCP worker 的 vars。cli/src/ grep MULTI_TENANT 只有 config 定義 + 註釋，無「部署時注入 worker env」的 code。對照：cypher-executor 通是因它把 key 當不驗證 opaque（不依賴 MULTI_TENANT）；MCP 依賴此 env 才走 namespace 分支，故漏注入就斷。
• 類比：self-hosted-init.md 注入了 WORKER_SUBDOMAIN，但漏注入 MULTI_TENANT（同一類部署注入機制的缺口）。

修法（arcrun 端，二選一或都做）：

1. acr init/update 部署 MCP（及需要的 worker）時，依 config multi_tenant: false 注入 MULTI_TENANT=false 到 worker vars（與注入 WORKER_SUBDOMAIN 同套機制，self-hosted-init.md）。
2. 短期：文件指引 self-hosted 用戶手動 wrangler secret put MULTI_TENANT（或取消 mcp/wrangler.toml 那兩行註釋）——但這違反「用戶零填寫」，①才是正解。

驗收：leo21c MCP worker 設好 MULTI_TENANT=false 後，curl -H "Authorization: Bearer leo" .../mcp initialize → 200（非 401）。

4. arcrun-gui 併入 + arcrun.dev 降官網

arcrun-gui 不再獨立，GUI 併入 arcrun repo（用戶下載即有）。arcrun.dev 降級為框架官網，移除 /mira/ 寄居（Mira 搬 mira.uncle6.me）。

5. arcrun-mcp → 已整進 arcrun/mcp，直接關掉（leo 2026-06-13）

勘查確認（2026-06-13）：arcrun/mcp 已是真身，比 matrix/arcrun-mcp 多 arcrun_recipe.ts + arcrun_whoami.ts，且 matrix/arcrun-mcp 無任何 arcrun/mcp 缺的東西（Only in arcrun-mcp 為空）= 已全部整進去。 動作：matrix/arcrun-mcp 直接關掉——封存進 _archive/ 即可，不遷帳號（舊 repo richblack/arcrun-mcp 留歷史）。無需整合，arcrun/mcp 就是現役。

6. KBDB 資料層遷移：3 個框架缺口（mira CC 2026-06-14 回報 + 總管核實，擋 mira 遷移）

mira 實測 leo21c self-hosted KBDB：好消息 entries 表 block-compatible（content/entry_type/parent_id/page_name/refs_json/tags_json/task_status/metadata_json = mira block 模型），河道/wiki/triplet 可直接落 entries，不必改資料模型。但卡 3 個 arcrun 缺口：

① 主缺口（擋遷移）：cypher proxy 漏 /kbdb/entries — 核實屬實。

• cypher-executor/src/routes/kbdb-proxy.ts 只實作 /kbdb/templates + /kbdb/records（注釋自稱含 entries，實際沒有）。基本盤 arcrun/kbdb 有 /entries（index.ts:18），proxy 沒轉發。
• 結果 mira 三者湊不齊：直連 kbdb worker /entries=有 block CRUD 但裸開無隔離；cypher /kbdb/*=有認證+owner_id 隔離但無 /entries。
• 修法：比照 /kbdb/records 的 owner_id 注入模式，補 /kbdb/entries（POST/GET filters/GET :id/PATCH/DELETE）。守鐵律（只轉發 API，不開 SQL/建表）。補好 mira _kbdb_client.py 改走 cypher.leo21c/kbdb/entries + X-Arcrun-API-Key namespace 隔離 → 完成解耦。

② MCP 的 KBDB service binding 壞 — 核實屬實。

• mcp/wrangler.toml 有 { binding="KBDB", service="arcrun-kbdb" }，kbdb-client 用 env.KBDB.fetch，但 mira 報 Cannot read properties of undefined (reading 'fetch') = env.KBDB undefined（self-hosted 部署時 binding 沒正確建/worker 名對不上 leo21c 的 kbdb）。
• 連帶：官方回報管道 arcrun_report_feedback（MCP tool）也因此送不出 → 這份回報只能靠總管轉。修這個才恢復 self-hosted 的 MCP 回報能力。
• 修法：self-hosted 部署確保 KBDB service binding 正確指向 leo21c kbdb worker（或改 HTTP fetch via KBDB_BASE_URL，與插件同模式，避免 self-hosted service binding 名稱耦合）。

③（非阻擋）mcp-setup namespace 不一致 — 核實屬實。

• cli/src/commands/mcp-setup.ts:53 用 config.api_key。self-hosted 若 api_key 存的是舊 ak_（非 namespace），則 MCP 與 CLI 讀寫不同分區。
• 修法：self-hosted 下 mcp-setup 優先用 NAMESPACE（config.namespace），與 CLI 同一分區。

對應 SDD：mira 端記在 mira SDD 14-A（標 🚧 待對端）；arcrun 端走協議（kbdb-proxy 屬既有 SDD 範圍）。

---

6b. ⚠️ 部署斷層：code 已補但 leo21c 未重部署（總管本地模擬核實 2026-06-15）

總管不靠 Hetzner、從本機直接 curl leo21c 端點驗證，發現 ①② 的 code 已 commit 進 arcrun repo，但對應 worker 沒部署到 leo21c CF：

證據（本機 curl leo21c，namespace=leo）	結果	判讀
GET cypher/kbdb/templates	200	cypher-executor 活著（舊版）
GET cypher/kbdb/entries	404	新 route 未上線（b1e302b 的 /kbdb/entries 沒部署）
GET cypher/kbdb/records	404	連既有 records proxy 都 404 → leo21c 上的 cypher 版本落後
直連 kbdb.leo21c/entries（裸開）	200	kbdb worker 本體活著，entries 表在
arcrun repo kbdb-proxy.ts	含完整 /kbdb/entries CRUD（行 144-184）	source 正確，純粹是沒 deploy

結論：缺口①②的 code 修正屬實（commit b1e302b /kbdb/entries + 1af7655 KBDB service binding），但卡在「部署到 leo21c」這一步。在 leo21c cypher-executor 重新部署前，mira _kbdb_client.py 即使改好也 smoke 必 404。

交棒 task（arcrun CC，依協議走既有 SDD + 鐵律「部署繞開 GitHub、wrangler 直推 CF」）：

1. 確認 leo21c 帳號（CLOUDFLARE_API_TOKEN 指 leo21c 51a01bfa…）下 cypher-executor 是哪個版本、為何落後（acr update 漏部署 cypher？還是只部署了部分 worker？）。
2. 重新部署 cypher-executor（+ 確認 mcp worker 的 KBDB service binding 一併上線，缺口②）到 leo21c。
3. 自驗：curl -H 'X-Arcrun-API-Key: leo' https://arcrun-cypher-executor.leo21c.workers.dev/kbdb/entries?limit=1 應回 200（非 404）。回 200 才算缺口①真正清空，mira 14-A 才解鎖。

接力鏈：arcrun 部署 cypher（6b）→ 端點 200 → mira 改 _kbdb_client.py（14A.1）→ smoke 讀寫 leo21c → 解耦完成。

6b-解決（arcrun CC 2026-06-15，已部署 + 自驗 200）

根因不是 GitHub lag（origin/main == 本地 4d6e77f，含 /kbdb/entries route）。兩層真因：

1. acr update 的 content-hash manifest 跳過機制（cli/src/lib/deploy.ts:198-225）把 cypher 當「未變動」跳過 → 落後。解：acr update --force 清空 manifest 強制全部重部。
2. .env line 3 的 CLOUDFLARE_ACCOUNT_ID=58309bb9…（官方帳號）被 CLI 載入並覆蓋 config.yaml 的 leo21c 51a01bfa…（env > 全域 config，config.ts:174）→ leo21c token 對官方帳號認證 → KV 解析「Authentication error」→ update 中止。解：部署時 CLOUDFLARE_ACCOUNT_ID=51a01bfa… node cli/dist/index.js update --force 強制 account 對齊 leo21c token。
   • ⚠️ 遺留陷阱：repo .env 是「官方帳號」部署脈絡用的；對 leo21c self-hosted 部署必須覆蓋 CLOUDFLARE_ACCOUNT_ID，否則 leo21c token vs 官方 account 不匹配。見記憶 cf-account-official-vs-loadtest。

部署結果：23/23 worker 全部 ✓（含 cypher-executor / kbdb / mcp），seed ✓（10 API + 23 auth recipe），cron index migrate ✓。用本地 build CLI 1.3.12（全域 acr 仍 1.3.11，未 npm publish）。

自驗（本機 curl leo21c，namespace=leo）：

• GET /kbdb/entries?limit=1 → 200 {"success":true,"entries":[],"count":0}（真轉發 kbdb worker，非假綠）✅ ← 缺口①清空，mira 14-A 解鎖
• GET /kbdb/templates → 200 ✅
• GET /kbdb/records?limit=1 → 404（非回歸，by design）：proxy 只有 POST /records、GET /records/by-template/:t、GET /records/:id，本就無 bare list route。HANDOFF 原以 records 404 當「cypher 舊版」訊號，但該路由從未存在。
• 缺口②：MCP initialize（Bearer leo）→ 200（非 401，MULTI_TENANT=false 已注入，KBDB binding 隨 mcp worker 上線）✅

---

每項動工前依 .claude/rules/00-sdd-protocol.md 宣告已讀 SDD。本 HANDOFF 是「有哪些事」，不是「繞過 SDD 的捷徑」。