arcrun — AI workflow execution engine (clean history)

Self-hosted 開源：WASM 零件 + recipe + cypher-executor，跑在你自己的 Cloudflare。

此為重建的乾淨歷史起點（移除曾誤 commit 的 GCP SA 金鑰，舊歷史保留在
richblack/arcrun 與本地 backup 分支）。含：
- acr init --self-hosted installer（建 KV/R2 + codeload 拉預編譯 wasm + wrangler deploy + seed recipe）
- recipe push 把關（資料外流提醒 + 打通檢查）
- 19 個正當零件預編譯 wasm（claude_api/km_writer/kbdb_upsert_block 排除：違反 DECISIONS §1）
- CLI / cypher-executor / registry / 完整 SDD

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.agents/specs/component-registry-canon/design.md

@@ -0,0 +1,162 @@
+# SDD: arcrun Component Registry 正典化（Component Registry Canon）
+
+> 2026-05-07 建立。狗糧發現的根本問題：registry 活著但 index 空的，AI 找不到零件就會繞回 Python。
+> 範圍：**讓 registry 成為零件 metadata 的 SSOT**，含 u6u → arcrun rebrand。
+
+---
+
+## 1. 問題
+
+### 1.1 表象
+- `registry.arcrun.dev/components/search?q=*` 永遠回 0 結果
+- MCP `u6u_search_components` 找不到任何零件
+- `acr parts list` 同樣空
+
+### 1.2 根因
+`matrix/arcrun/registry/components/` 下 30+ 個零件已經部署成獨立 Worker（kbdb_ingest, claude_api, kbdb_create_block, kbdb_patch_block, http_request, string_ops, ⋯），但**它們的 contract.yaml 沒有透過 `POST /components/submit` 進 registry index**。
+
+部署路徑：
+```
+registry/components/{name}/main.go     ← TinyGo 寫的零件
+       ↓ tinygo build
+.component-builds/{name}/component.wasm
+       ↓ wrangler deploy
+{name}.arcrun.dev (Worker)              ← 零件可被 HTTP 呼叫了
+
+registry index?                         ← 這步從來沒做
+```
+
+### 1.3 影響（吃狗糧的觀察）
+- 新 AI（Claude / Gemini / Codex）進來不知道有什麼零件 → 自己寫 Python 直打 API
+- arcrun 想推「AI-first 自服務」整個破功
+- 文件寫得再好都救不了 — 因為 README 只能寫概念，零件清單必須是 API 動態查
+
+---
+
+## 2. 目標
+
+**Registry 是零件 metadata 的 SSOT**：
+
+- 零件 Worker 在跑 ⇔ registry 有對應 entry（雙向綁定）
+- AI 透過 MCP `search_components` 永遠找得到所有現役零件
+- README 不寫死數量，動態 badge 即時反映
+- 第三方裝完 MCP 30 秒內能找到第一個可用零件
+
+---
+
+## 3. 三層設計
+
+### Layer 1: 一次性 backfill（Phase 1）
+
+掃 `matrix/arcrun/registry/components/*/component.contract.yaml`，把每個 contract POST 進 registry index。
+
+工具：`matrix/arcrun/registry/scripts/backfill-index.ts`
+- 讀檔 → 解析 YAML → 呼叫 registry submit endpoint
+- idempotent：已存在不重複寫（registry 端要支援 upsert）
+- 跳過沙盒驗收（這些零件已驗過、已部署，不用重跑 gherkin tests）
+
+### Layer 2: 部署即註冊（Phase 2）
+
+改 `.github/workflows/deploy.yml`：
+- 通用掃描掃到 `.component-builds/{name}/wrangler.toml` 部署成功後
+- post-deploy step 自動呼叫 registry submit（contract 從 `registry/components/{name}/component.contract.yaml` 讀）
+
+零件 Worker 部署 ⇒ registry 自動更新。沒有「零件部署了但 registry 不知道」的可能。
+
+### Layer 3: Discoverability（Phase 3）
+
+- README 移除「21 個零件」這種寫死數字，改「跑 search 看當前清單」
+- 加 badge endpoint `registry.arcrun.dev/badge/components.svg` 即時顯示數量
+- MCP `get_component_guide` 開頭加鐵律：「動工前必須先 search，不是猜」
+- onboarding kit GitHub template：CLAUDE.md / .cursor/rules / AGENTS.md 三件套，all 強制 search 優先
+
+### Layer 4: u6u → arcrun Rebrand（Phase 4）
+
+把 `matrix/u6u-mcp/` 跟所有 `u6u_*` tool 名搬到 arcrun 命名空間。
+
+理由：
+- u6u 是申請 arcrun.dev 之前的暫名，現在已過時
+- 命名混亂阻礙推廣（「為什麼 arcrun 文件叫 u6u_*?」）
+- 第三方看到 u6u 不知道是同一個產品
+
+範圍：
+1. 目錄：`matrix/u6u-mcp/` → `matrix/arcrun-mcp/`
+2. Worker name：`u6u-mcp` → `arcrun-mcp`
+3. Tool 前綴：`u6u_search_components` → `arcrun_search_components`（14 個 tool）
+4. Hostname：`mcp.finally.click` → `mcp.arcrun.dev`（finally.click 保留 redirect 到 arcrun.dev 過渡期）
+5. Repo / Worker 內部 ID：u6u-mcp-server → arcrun-mcp-server
+6. README 全文：u6u → arcrun
+7. user memory（CLAUDE.md / MEMORY.md）相關提及一併更新
+8. inkstone-component-registry（舊 worker）廢止 → arcrun-registry 為唯一現役
+
+**Rebrand 原則：**
+- 用戶端 config（claude_desktop_config.json 等）給過渡期：兩個 URL 都活，舊的回 deprecation header 提示換新
+- Tool 前綴 `u6u_*` → `arcrun_*` 沒有過渡期（一刀切，因為前綴是 AI 看的，不是用戶記憶肌肉）
+- 文件 / repo 內所有 reference 立即改
+
+---
+
+## 4. 範圍邊界
+
+**在本 SDD 範圍內：**
+- ✅ Phase 1: backfill index
+- ✅ Phase 2: 部署即註冊 hook
+- ✅ Phase 3: README + badge + onboarding kit
+- ✅ Phase 4: u6u → arcrun rebrand（含目錄 / worker / hostname / tool 前綴 / 文件）
+
+**不在範圍內：**
+- 新零件開發（這是 polaris 業務範圍）
+- registry KV schema 改動（用既有結構）
+- u6u-gui 的 rebrand（u6u-mcp 同 monorepo 但獨立 SDD）
+- Phase 5（用戶自製零件 R2 上傳）— 等 Phase 4 完成後另開 SDD
+
+**前置依賴（已完成）：**
+- ✅ u6u-mcp Zod 4 → Zod 3 修復（2026-05-07）
+- ✅ u6u-mcp service binding 改指 arcrun-registry（2026-05-07）
+- ✅ arcrun-registry Worker 部署在 registry.arcrun.dev
+
+---
+
+## 5. 驗收標準
+
+### Phase 1 驗收
+- `u6u_search_components("kbdb")` 回非空結果，含 `kbdb_ingest` / `kbdb_create_block` / `kbdb_patch_block`
+- `acr parts list` CLI 端對端能列出
+- registry KV 內至少 30 entries
+
+### Phase 2 驗收
+- 部署任一既有零件後，registry 30 秒內 reflect 更新
+- 部署一個全新零件，無需手動 publish，registry 自動有
+- CI workflow 不會因 registry 寫入失敗就擋部署（degraded mode：寫入失敗 log warning 但不 fail）
+
+### Phase 3 驗收
+- README 沒有「21 個零件」「30 個零件」這種寫死數字
+- badge SVG 渲染正確、數字跟 KV 一致
+- onboarding kit clone 下來，照 README 跑能 30 秒內 list 到零件
+
+### Phase 4 驗收
+- `mcp.arcrun.dev/mcp/mcp` 通，回的 tool 名都是 `arcrun_*`
+- 舊 `mcp.finally.click/mcp/mcp` 仍可用但回 deprecation header
+- README / docs / GUIDE 全部 u6u 字樣消除
+- `matrix/u6u-mcp/` 目錄不存在，改為 `matrix/arcrun-mcp/`
+- 用戶記憶（`~/.claude/.../MEMORY.md`）arcrun MCP 設定範例已更新
+
+---
+
+## 6. 風險與緩解
+
+| 風險 | 緩解 |
+|---|---|
+| backfill 把 contract 灌進去後，沙盒驗收覆蓋既有資料 | registry submit 加 `skip_acceptance=true` flag，僅 backfill 用 |
+| 部署 hook 寫入失敗擋掉部署 | hook degraded mode：失敗只 warning，不 fail 部署 |
+| Rebrand 把現役 client 弄壞 | 過渡期：舊 hostname 跟 worker 並存 1 個月 |
+| Tool 前綴改名 AI 適應期 | 不過渡，一刀切（前綴是 system instruction 範圍，AI 一個 prompt 就學會）|
+| 既有用戶 config 寫死 finally.click | 提前公告 + 過渡期 + 舊 endpoint 自動 redirect / proxy |
+
+---
+
+## 7. 變更紀錄
+
+| 版本 | 日期 | 內容 |
+|---|---|---|
+| v1.0 | 2026-05-07 | 初版。吃狗糧發現 registry 空的，三層設計（backfill / auto-register / discoverability）+ u6u → arcrun rebrand 一併納入。 |