# HANDOFF: KBDB triplet/graph → 改名 **KBDB-graph**，作為 KBDB 插件獨立（2026-06-13）

來源：InkStoneCo 頂層 `.agents/specs/matrix-rearrange/` Phase 2（R2）。
**指針式考古**：相關歷史素材在 InkStoneCo `_archive/`，照路徑挖，不複製。

## 定位（leo 2026-06-13 澄清）

此目錄 `matrix/kbdb-graph-plugin`（原 matrix/kbdb，已改名）作為 **KBDB-graph**，是**原有 KBDB 的插件**獨立：
- **原有 KBDB（基本盤）** = `arcrun/kbdb`：D1 三表（blocks/templates/slots）的基本儲存讀寫，已併進 arcrun。
- **KBDB-graph（本目錄→獨立 repo）** = 掛在基本盤之上的 triplet 採集 + graph 查詢能力。**類比 Apache AGE 之於 Postgres**——插件掛在基本儲存上，不取代它。
- **為何獨立**：它比較龐大、不是基本存儲功能；且 leo 產權、較複雜。故獨立成 repo，不留在 arcrun。
- **由此目錄的 CC 自行 `git init` + 推 GitHub**（命名 `KBDB-graph`，帳號 leo 定/uncle6me-web）。

## ⚠️ 重大修正（leo 2026-06-14）：插件現狀違反 KBDB 鐵律，要改寫

**先讀總管決策 `InkStoneCo/.agents/specs/matrix-rearrange/DECISION-kbdb-v3-baseplane.md`。**

你之前的 design.md 把「現狀代碼直接 SQL 讀 entry_values/blocks」當成「AGE-on-Postgres 訊號」、跑去問「要不要共用 D1 直接 SQL」——**這是讀現狀推翻鐵律的錯**。你自己的 CLAUDE.md 第 83 行就寫了「禁止繞過 API 直接 D1 操作 — API-as-Wall」。現狀代碼是違規的歷史產物，不是設計依據。

### KBDB 鐵律（leo 拍板，最高原則）
1. **任何人都不准動表**（CREATE/ALTER/DROP）。只有基本盤維護者能改那 3 表，你不行。
2. 新資料類型=建 template，永不建表。triplet=`template='triplet'` 寫進 entry_values。
3. 插件**不准直接接觸表**（禁 SELECT/INSERT/JOIN），讀寫**全走基本盤 API**。
4. 插件層全程禁 SQL。

### 正確形態
- 基本盤=arcrun/kbdb（3 表 + CRUD API：templates/entries/records/search 端點，已存在），**不動**。它用 `entry_type='block'` 表達 block，無獨立 blocks 表。
- 你=`triplet` template 定義（`contracts/triplet.json`）+ graph 查詢函式。寫 triplet→調基本盤 records/entries API；查圖→調基本盤 search API 取 entry_values 在插件層組裝。**零建表、零 migration、零 SQL。**

## 待辦（由本目錄 CC 執行）

1. **改寫成走 API/薄殼**（核心）：`triplet-crud` 的 `INSERT INTO entry_values`、graph/entity 的 `SELECT FROM ...` → 改調基本盤 API（或 MCP/CLI 薄殼，與 AI/人同一條路）。寫 triplet=建 `template='triplet'` + 填 slot（調 `POST /templates`、`POST /records`）；查圖=調 search/records API 取回再組裝。**注意**：arcrun 的 MCP/CLI 目前還沒 KBDB tool（要 arcrun 端先補，見 arcrun HANDOFF §2），在那之前先直調基本盤 HTTP API。
2. **刪除違規 migrations**：`0001_init`/`0005_universal_table` 等含 `CREATE TABLE` 的全刪（插件不建表）。triplets VIEW 改用 API 查 + 插件層組裝。
3. **改名 `KBDB-graph` + `git init` + 推 GitHub**（帳號 leo 定）。由本 CC 自己推。
4. **裁剪 CLAUDE.md**：移除整套 KBDB v3 基本盤規範（那屬 arcrun/kbdb），只留 graph 插件相關 + 上面鐵律。
5. 部署繞開 GitHub（wrangler 直推），禁跨 repo 同步 Actions（[[github-flagged-risk]]）。

## 注意
- 本目錄現**無獨立 git**。改名後 `git init` + remote（帳號 leo 定），由本 CC 推。
- arcrun 端基本盤已正確（3 表 + API），不需升 v3、不需搬基本盤。對應交棒見 arcrun `docs/HANDOFF-matrix-rearrange.md` §2。