feat(storage): 工作流與 recipe 的家搬到 KBDB，KV 降成可丟棄的快取（Arcrun#16＋#17）

leo 08-12：「我要的是寫進 KBDB，不是 KV，他的 Recipes、Cypher 是一段話，文字，
數據，一個 entry」「如果零件和工作流的 recipe 不見了，是很可怕的事情」。
同日實害：一次例行更新讓九支工作流在畫面上全部消失。#97 已修掉直接原因
（別再照名字猜使用者的資源、別再擅自新建一顆空的綁上去）；這裡修更下面那一句——
**資產本來就不該只存在於一個會被換掉的暫存層裡**。

做法（換 binding，不改四十幾處呼叫端）：
- lib/asset-keys.ts    哪些 KV key 是資產、對應 KBDB 哪一列。**唯一**要人看懂的那張表。
- lib/durable-store.ts 讀＝KV 先行、miss 回源 KBDB 並補快取；寫＝先 KBDB 再 KV，
                       KBDB 失敗就拋錯（禁假綠）；**列舉一律回源**——空 KV 列出來是
                       「零筆」而不是「查不到」，那正是東西消失的形狀。
- index.ts             入口把 WEBHOOKS/RECIPES 換成上面那層。逐處改寫一定會漏，
                       而漏掉的那一處就是下一次「東西不見了」的入口。
- routes/storage.ts    /storage/audit（搬前搬後各數一次）＋ /storage/migrate-to-kbdb
                       （只增不刪、冪等、逐筆回報成敗）。
- kbdb                 migration 0005 seed 四列 template（零 schema 異動，手法同 0003/0004）
                       ＋ PUT /entries/:id 指定 id 的整列 upsert（通用原語，不是為誰開特例）。
- 衍生資料（idx:*、cron-idx:_all）不進 KBDB，讀不到就從資產重算。

⚠️ 狀態＝◐ 半通，**別因為程式碼看起來完整就先合併**。
已實測：5 份 migration 在本機 D1 全數套用（含 0005）；兩顆 worker 都能以改動後的
程式碼在本機開起來；tsc 錯誤數 7→7（既有，未新增）。
**沒跑到**：「砍掉 KV、資產還在」那一次端到端驗證——本次施工環境的權限閘不放行
執行 vitest/node/curl。那一次已寫成 scripts/verify-kv-retirement.sh，
在能執行的機器上跑一次就是證據。建議順序：先跑腳本、綠了再合併。

規格層依 D35 走 pending-changes.md「P-KV」提案，等 leo confirm（現行 active SDD
是 workflow-discovery，本案不在它的 tasks 內，故不自建 SDD、不改 rules 那張儲存表）。

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

system-dev/docs/3-specs/pending-changes.md

@@ -8,6 +8,75 @@
 
 ## 待裁決
 
+### P-KV｜KV 退休：工作流與 recipe 的家搬到 KBDB（Leo/Arcrun#16 + #17）— 2026-08-12
+
+**觸發**：leo 2026-08-12 原話——
+> 「我要的是寫進 KBDB，不是 KV，他的 Recipes、Cypher 是一段話，文字，數據，一個 entry」
+> 「因為對 KV 的使用有禁令，但卻會把資產放在這裡，這不是違法嗎？」
+> 「現在是我幫他寫工作流，未來是他的 AI 自己寫工作流，
+>   **如果零件和工作流的 recipe 不見了，是很可怕的事情**」
+
+同日實害：一次例行更新讓使用者的九支工作流在畫面上全部消失（Arcrun#97）。
+#97 已修掉直接原因（`cli/src/lib/resource-resolver.ts`：不再照名字猜使用者的資源、
+不再擅自新建一顆空的綁上去）。**本案修的是更下面那一句**：使用者的資產本來就不該
+只存在於一個會被換掉的暫存層裡——#97 修的是「別再換錯」，這裡修的是「換了也不會怎樣」。
+
+**為什麼要走規格層（D35）**：`.claude/rules/01-tech-stack.md`「資料儲存」那張表把
+workflow 定義寫在 `WEBHOOKS` KV、recipe 寫在 `RECIPES` KV。改掉真相來源＝改規格。
+現行 active SDD 是 `workflow-discovery`，本案不在它的 tasks 內，故依 D35 第 3 條
+寫 proposal 停下等 leo confirm。**#16 已被多份 SDD 引用為前提**
+（`arcrun/artifact-sharing/` design K2「KBDB 是唯一公庫後端」、requirements Out of Scope、
+tasks 1.5／5.2 都寫明「遷移本體由 #16 負責」），所以這不是新方向，是那些卷等的那一塊落地。
+
+**提議的規格（三句）**
+1. **資產的真相來源＝KBDB**（D1 `entries` 一列一份資產）。KV 降級為可丟棄的快取。
+2. **零 SQL、永不加表**（D38）：新增四個 `entry_type`
+   （`workflow_def` / `api_recipe` / `auth_recipe` / `prompt_recipe`），
+   各在 `templates` 表 seed 一列定義（`kbdb/migrations/0005_arcrun_asset_templates.sql`，
+   手法同 0003／0004）。定義本體打包進 `metadata_json`，比照 `execution_log`／`recipe_stat` 既有先例。
+3. **衍生資料不進 KBDB**：`idx:*`（recipe 反查）、`cron-idx:_all` 算得回來，
+   留在 KV，讀不到就從 KBDB 重算（不讓 KBDB 長出垃圾列）。
+
+**實作形狀（已寫在 `feat/kv-retire-recipes-16-17` 分支，未合併）**
+- 換 binding 而不是改呼叫端：`src/index.ts` 入口把 `WEBHOOKS`／`RECIPES`
+  換成 KBDB 撐腰的包裝（`src/lib/durable-store.ts`），四十幾處呼叫端一行不動。
+  理由：逐處改寫一定會漏，**漏掉的那一處就是下一次「東西不見了」的入口**。
+- 「哪些 key 是資產」集中成一張表（`src/lib/asset-keys.ts`），是唯一需要人看懂的東西。
+- 讀＝KV 先行、miss 回源 KBDB 並補快取；寫＝先 KBDB 再 KV，KBDB 失敗就拋錯（禁假綠）；
+  **列舉一律走 KBDB**——空 KV 列出來是「零筆」而不是「查不到」，那正是消失的形狀。
+- 搬遷與盤點：`GET /storage/audit`、`POST /storage/migrate-to-kbdb`（只增不刪、冪等、逐筆回報）。
+- KBDB 端只加一個通用原語：`PUT /entries/:id`（指定 id 的整列 upsert），零 schema 異動。
+
+**影響分析**
+- 現行 active SDD `workflow-discovery`：**不受影響**。它的 `entry_type='workflow'`
+  搜尋 entry 照舊雙寫，本案刻意用另一個型別 `workflow_def` 存定義本體、且不標 `embed`，
+  以免同一支工作流嵌兩份向量。search／backfill 兩支端點一行未動。
+- `artifact-sharing`：本案就是它 K2 等的 #16。落地後可拆 tasks 1.5 的 KV 過渡轉接（5.2）。
+- credential：**不碰**。憑證走 CF Workers Secrets ＋ D1 目錄（rule 01），不在本案範圍。
+- 匿名 webhook（`webhooks.ts` 的 `put(token, record)`）：**目前沒搬**，仍是 KV-only。
+  它也是使用者建出來的東西，但不在 #16/#17 的字面範圍內——在此列出，請 leo 裁要不要納入。
+- 效能：資產讀取多一層快取判斷；快取命中時與現況相同，miss 時多一次 KBDB 往返。
+  `list` 一律回源，但會順手把整批補進快取，所以「列出來再逐筆讀」總共只多一次往返。
+
+**尚未完成／誠實限制（決定要不要 confirm 前請先看這段）**
+- **端到端證據沒跑**。實作環境（雲端工人沙箱）不放行執行測試與 HTTP
+  （`vitest`／`node`／`curl` 皆被權限閘擋下），所以「砍掉 KV、資產還在」這一次
+  **我沒有真的做出來給你看**。已跑到的只有：5 份 migration 在本機 D1 全部套用成功、
+  兩顆 worker 都能以改動後的程式碼在本機開起來、`tsc` 錯誤數與改動前一致（7 個既有錯，未新增）。
+- 那一次驗證已經寫成可執行的腳本 `scripts/verify-kv-retirement.sh`
+  （開空實例 → 放 9 支工作流＋3 份 recipe → 數一次 → **砍掉整個 KV 層重建** → 再數一次
+  → 真的觸發一支確認跑得動），**在能執行的機器上跑一次就是那個證據**。
+- 因此本案的狀態是 **◐ 半通**：程式碼與遷移路徑齊備，證據缺一份。
+  **建議 confirm 的順序是「先跑那支腳本、綠了再合併」**，不要因為程式碼看起來完整就先併——
+  這件事的整個重點就是不要再有「看起來好好的，其實東西不見了」。
+
+**⏸ 停在這裡等 leo 裁**：
+① 方向 confirm 嗎（資產真相來源改 KBDB、KV 降快取）？
+② 匿名 webhook 要不要一起納入？
+③ KV 舊資料要不要清（本案只增不刪，清是另一個決定）？
+
+---
+
 ### P2｜fan-out 並行執行（一個節點的多條出邊目前是循序跑）— 2026-08-03
 
 **觸發**：leo 08-03 原話——「這是在測試中的計畫，**希望體驗很好**，我發現用 gemma4 的反應非常慢。」