feat(kbdb): recipe 公庫/私庫雙向機制 + UUID 身份 + KBDB Base + 市場數據

kbdb-base SDD §7.5（公庫/私庫雙向機制，richblack 2026-06-07 拍板）。

## KBDB Base worker（新）
- kbdb/：D1-only 核心三表（entries/templates/entry_values）+ CRUD + LIKE search
  + recipe-stats 端點（市場數據）+ 0001_base.sql migration（含 recipe_stat seed）

## Phase 2.3：init 建 D1 + 套 migration
- cli cf-api.ts 加 listD1Databases/ensureD1Database；init 建 arcrun-kbdb D1
- deploy.ts 部署後對 D1 套 0001_base.sql（CF /d1/query API，idempotent）+ 注入 database_id

## Phase 5.1：recipe 成功記錄（市場數據來源）
- GraphExecutor 收集本次用到的 recipe uuid（usedRecipeKeys）
- executeWebhookGraph 執行結束一次性記 per-uuid 成功/失敗到 KBDB（fire-and-forget）

## Phase 7.5：recipe UUID 身份 + app-store 模型
- recipe 領 uuid=唯一身份；canonical_id/author/公私=屬性（§7.5.5）
- recipe:{uuid} + idx:canonical/installed/hash；resolveRecipe 向後相容不破執行鏈
- POST /recipes/submit=領新 uuid 新增作者版本（非覆蓋，app-store）
- GET /public-recipes 搜尋（多作者+per-uuid 市場星數）/ :id pull（選市場最佳）
- 落空→found:false 創作引導（§7.5.6 閉環）
- POST /recipes/migrate-uuid 一次性轉舊 key（增量寫不刪舊、冪等）
- init-seed 用 UUID（author=system）

## 薄殼（rule 07 §5：CLI + MCP 覆蓋同組能力）
- CLI: acr recipe search/pull/submit-p（config 加 DEFAULT_PUBLIC_LIBRARY_URL）
- MCP: arcrun_recipe_search/pull/submit_p/push/list/delete（補齊漂移）

## 壓測修正
- api-recipe-seeds: google_sheets_append PUT→POST（:append 正確動詞，階段12）

四 worker tsc 全綠（cypher/cli/kbdb/mcp）。

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

kbdb/migrations/0001_base.sql

@@ -0,0 +1,88 @@
+-- KBDB Base — atomic universal table (3 tables, never changes)
+-- SDD: .agents/specs/arcrun/kbdb-base/design.md
+--
+-- Plugin model (like PostgreSQL core + PGVector/AGE):
+--   - Base = these 3 tables + plain CRUD + D1 LIKE search (D1 only, free, no credit card).
+--   - embed module = optional, writes vectors to Vectorize (does NOT alter these tables).
+--   - triplet module = separate repo, writes derived records into entry_values (does NOT alter base).
+-- "Table never changes": new tech records its output elsewhere, never ALTERs the base.
+
+-- ============================================================
+-- 1. Three tables
+-- ============================================================
+
+-- Universal main table: each entry is one atomic datum.
+-- entry_type extended for arcrun: 'block' | 'value' | 'template' | 'slot' | 'project' | 'workflow' | 'recipe_stat'
+CREATE TABLE IF NOT EXISTS entries (
+  id TEXT PRIMARY KEY,
+  content TEXT,
+  entry_type TEXT NOT NULL,
+  owner_id TEXT,                   -- multi-tenant: namespace (self-hosted) or api_key (SaaS)
+
+  -- tree structure (project -> workflow via parent_id; SDD Q1 decision)
+  parent_id TEXT,
+
+  -- optional block metadata (harmless plain columns)
+  page_name TEXT,
+  refs_json TEXT DEFAULT '[]',
+  tags_json TEXT DEFAULT '[]',
+  task_status TEXT,
+
+  -- optional embed bookkeeping (set by optional embed module; base never reads them)
+  content_hash TEXT,
+  is_embedded INTEGER DEFAULT 0,
+
+  -- metadata
+  confidence REAL,
+  metadata_json TEXT,
+
+  created_at INTEGER DEFAULT (unixepoch()),
+  updated_at INTEGER DEFAULT (unixepoch())
+);
+
+-- Template table: defines slots for a virtual table
+CREATE TABLE IF NOT EXISTS templates (
+  id TEXT PRIMARY KEY,
+  name TEXT UNIQUE NOT NULL,
+  description TEXT,
+  slots_json TEXT NOT NULL,        -- JSON array, e.g. ["display_name","gender"]
+  created_by TEXT,                 -- 'system' | 'ai' | owner_id
+  created_at INTEGER DEFAULT (unixepoch()),
+  updated_at INTEGER DEFAULT (unixepoch())
+);
+
+-- Slot link table: composes multiple entries into one structured record
+CREATE TABLE IF NOT EXISTS entry_values (
+  id TEXT PRIMARY KEY,
+  record_id TEXT NOT NULL,
+  template_id TEXT NOT NULL REFERENCES templates(id),
+  slot_name TEXT NOT NULL,
+  entry_id TEXT NOT NULL REFERENCES entries(id),
+  created_at INTEGER DEFAULT (unixepoch()),
+  UNIQUE(record_id, slot_name)
+);
+
+-- ============================================================
+-- 2. Indexes
+-- ============================================================
+
+CREATE INDEX IF NOT EXISTS idx_entries_type ON entries(entry_type);
+CREATE INDEX IF NOT EXISTS idx_entries_owner ON entries(owner_id);
+CREATE INDEX IF NOT EXISTS idx_entries_parent ON entries(parent_id);
+CREATE INDEX IF NOT EXISTS idx_entries_page ON entries(page_name);
+CREATE INDEX IF NOT EXISTS idx_entries_task ON entries(task_status);
+CREATE INDEX IF NOT EXISTS idx_entries_hash ON entries(content_hash);
+
+CREATE INDEX IF NOT EXISTS idx_ev_record ON entry_values(record_id);
+CREATE INDEX IF NOT EXISTS idx_ev_template ON entry_values(template_id);
+CREATE INDEX IF NOT EXISTS idx_ev_template_slot ON entry_values(template_id, slot_name);
+CREATE INDEX IF NOT EXISTS idx_ev_entry ON entry_values(entry_id);
+
+-- ============================================================
+-- 3. Seed templates used by arcrun base
+-- ============================================================
+
+-- recipe_stat: success/failure counters for a recipe (feeds recipe submission, SDD section 7)
+INSERT OR IGNORE INTO templates (id, name, description, slots_json, created_by)
+VALUES
+  ('tpl-recipe-stat', 'recipe_stat', 'recipe success/failure counters', '["canonical_id","success_count","failure_count","last_status","last_at"]', 'system');

kbdb/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "arcrun-kbdb",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "hono": "^4.7.0",
+    "zod": "~3.23.8"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20250219.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.1.0",
+    "wrangler": "^4.0.0"
+  }
+}

kbdb/src/actions/entry-crud.ts

@@ -0,0 +1,117 @@
+// Entry CRUD — atomic data + tree (project/workflow via parent_id). Base, D1 only.
+import type { Bindings, Entry } from '../types';
+
+function uid(prefix: string): string {
+  // deterministic-enough unique id without Math.random in hot path is fine here;
+  // crypto.randomUUID is available in Workers runtime.
+  return `${prefix}_${crypto.randomUUID()}`;
+}
+
+export interface CreateEntryInput {
+  content?: string | null;
+  entry_type: string;
+  owner_id?: string | null;
+  parent_id?: string | null;
+  page_name?: string | null;
+  refs_json?: string;
+  tags_json?: string;
+  task_status?: string | null;
+  confidence?: number | null;
+  metadata_json?: string | null;
+  id?: string;
+}
+
+export async function createEntry(db: D1Database, input: CreateEntryInput): Promise<Entry> {
+  const id = input.id ?? uid('e');
+  await db
+    .prepare(
+      `INSERT INTO entries (id, content, entry_type, owner_id, parent_id, page_name, refs_json, tags_json, task_status, confidence, metadata_json)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    )
+    .bind(
+      id,
+      input.content ?? null,
+      input.entry_type,
+      input.owner_id ?? null,
+      input.parent_id ?? null,
+      input.page_name ?? null,
+      input.refs_json ?? '[]',
+      input.tags_json ?? '[]',
+      input.task_status ?? null,
+      input.confidence ?? null,
+      input.metadata_json ?? null,
+    )
+    .run();
+  const row = await getEntry(db, id);
+  if (!row) throw new Error('createEntry: insert succeeded but row not found');
+  return row;
+}
+
+export async function getEntry(db: D1Database, id: string): Promise<Entry | null> {
+  const row = await db.prepare('SELECT * FROM entries WHERE id = ?').bind(id).first<Entry>();
+  return row ?? null;
+}
+
+export interface ListEntriesFilter {
+  entry_type?: string;
+  owner_id?: string;
+  parent_id?: string;
+  limit?: number;
+  offset?: number;
+}
+
+export async function listEntries(db: D1Database, f: ListEntriesFilter = {}): Promise<Entry[]> {
+  const conds: string[] = [];
+  const params: unknown[] = [];
+  if (f.entry_type) { conds.push('entry_type = ?'); params.push(f.entry_type); }
+  if (f.owner_id) { conds.push('owner_id = ?'); params.push(f.owner_id); }
+  if (f.parent_id) { conds.push('parent_id = ?'); params.push(f.parent_id); }
+  const where = conds.length ? `WHERE ${conds.join(' AND ')}` : '';
+  const limit = Math.min(f.limit ?? 100, 1000);
+  const offset = f.offset ?? 0;
+  const res = await db
+    .prepare(`SELECT * FROM entries ${where} ORDER BY created_at DESC LIMIT ? OFFSET ?`)
+    .bind(...params, limit, offset)
+    .all<Entry>();
+  return res.results ?? [];
+}
+
+export interface UpdateEntryInput {
+  content?: string | null;
+  parent_id?: string | null;
+  page_name?: string | null;
+  refs_json?: string;
+  tags_json?: string;
+  task_status?: string | null;
+  confidence?: number | null;
+  metadata_json?: string | null;
+}
+
+export async function updateEntry(db: D1Database, id: string, patch: UpdateEntryInput): Promise<Entry | null> {
+  const cols: string[] = [];
+  const params: unknown[] = [];
+  const map: Record<string, unknown> = patch as Record<string, unknown>;
+  for (const k of ['content', 'parent_id', 'page_name', 'refs_json', 'tags_json', 'task_status', 'confidence', 'metadata_json']) {
+    if (k in map && map[k] !== undefined) { cols.push(`${k} = ?`); params.push(map[k]); }
+  }
+  if (cols.length === 0) return getEntry(db, id);
+  cols.push('updated_at = unixepoch()');
+  await db.prepare(`UPDATE entries SET ${cols.join(', ')} WHERE id = ?`).bind(...params, id).run();
+  return getEntry(db, id);
+}
+
+export async function deleteEntry(db: D1Database, id: string): Promise<void> {
+  await db.prepare('DELETE FROM entries WHERE id = ?').bind(id).run();
+}
+
+// D1 LIKE keyword search (base; semantic search is the optional embed module).
+export async function searchEntries(db: D1Database, q: string, owner_id?: string, limit = 50): Promise<Entry[]> {
+  const conds = ['content LIKE ?'];
+  const params: unknown[] = [`%${q}%`];
+  if (owner_id) { conds.push('owner_id = ?'); params.push(owner_id); }
+  const res = await db
+    .prepare(`SELECT * FROM entries WHERE ${conds.join(' AND ')} ORDER BY updated_at DESC LIMIT ?`)
+    .bind(...params, Math.min(limit, 200))
+    .all<Entry>();
+  return res.results ?? [];
+}

kbdb/src/actions/recipe-stat.ts

@@ -0,0 +1,63 @@
+// Recipe success/failure records (SDD section 7.1). Stored as an entry per recipe canonical_id.
+// This is the "fuel" for submission-with-proof: real 2xx counts beat self-written tests.
+import type { Bindings } from '../types';
+
+interface RecipeStat {
+  canonical_id: string;
+  success_count: number;
+  failure_count: number;
+  last_status: string | null;
+  last_at: number | null;
+}
+
+// One entry per recipe: id = recipestat:{canonical_id}, entry_type='recipe_stat',
+// counters live in metadata_json. Atomic upsert via D1.
+function statId(canonicalId: string): string {
+  return `recipestat:${canonicalId}`;
+}
+
+export async function recordRecipeResult(db: D1Database, canonicalId: string, ok: boolean, nowMs: number): Promise<RecipeStat> {
+  const id = statId(canonicalId);
+  const existing = await db.prepare('SELECT metadata_json FROM entries WHERE id = ?').bind(id).first<{ metadata_json: string | null }>();
+
+  let stat: RecipeStat;
+  if (existing) {
+    const prev = existing.metadata_json ? (JSON.parse(existing.metadata_json) as RecipeStat) : emptyStat(canonicalId);
+    stat = {
+      canonical_id: canonicalId,
+      success_count: prev.success_count + (ok ? 1 : 0),
+      failure_count: prev.failure_count + (ok ? 0 : 1),
+      last_status: ok ? 'success' : 'failure',
+      last_at: nowMs,
+    };
+    await db
+      .prepare('UPDATE entries SET metadata_json = ?, updated_at = unixepoch() WHERE id = ?')
+      .bind(JSON.stringify(stat), id)
+      .run();
+  } else {
+    stat = {
+      canonical_id: canonicalId,
+      success_count: ok ? 1 : 0,
+      failure_count: ok ? 0 : 1,
+      last_status: ok ? 'success' : 'failure',
+      last_at: nowMs,
+    };
+    await db
+      .prepare('INSERT INTO entries (id, content, entry_type, metadata_json) VALUES (?, ?, ?, ?)')
+      .bind(id, canonicalId, 'recipe_stat', JSON.stringify(stat))
+      .run();
+  }
+  return stat;
+}
+
+export async function getRecipeStat(db: D1Database, canonicalId: string): Promise<RecipeStat> {
+  const row = await db.prepare('SELECT metadata_json FROM entries WHERE id = ?').bind(statId(canonicalId)).first<{ metadata_json: string | null }>();
+  if (!row || !row.metadata_json) return emptyStat(canonicalId);
+  return JSON.parse(row.metadata_json) as RecipeStat;
+}
+
+function emptyStat(canonicalId: string): RecipeStat {
+  return { canonical_id: canonicalId, success_count: 0, failure_count: 0, last_status: null, last_at: null };
+}
+
+export type { RecipeStat };

kbdb/src/actions/record-crud.ts

@@ -0,0 +1,120 @@
+// Template + Record CRUD. A "record" = multiple entries composed via a template's slots.
+// Base, D1 only. (Ported clean from KBDB; no vectorize/triplet imports.)
+import type { Template } from '../types';
+import { createEntry } from './entry-crud';
+
+function uid(prefix: string): string {
+  return `${prefix}_${crypto.randomUUID()}`;
+}
+
+// ---- Templates ----
+
+export interface CreateTemplateInput {
+  name: string;
+  description?: string | null;
+  slots: string[];
+  created_by?: string | null;
+  id?: string;
+}
+
+export async function createTemplate(db: D1Database, input: CreateTemplateInput): Promise<Template> {
+  const id = input.id ?? uid('tpl');
+  await db
+    .prepare(`INSERT INTO templates (id, name, description, slots_json, created_by) VALUES (?, ?, ?, ?, ?)`)
+    .bind(id, input.name, input.description ?? null, JSON.stringify(input.slots), input.created_by ?? null)
+    .run();
+  const row = await getTemplate(db, id);
+  if (!row) throw new Error('createTemplate: row not found after insert');
+  return row;
+}
+
+export async function getTemplate(db: D1Database, idOrName: string): Promise<Template | null> {
+  const row = await db
+    .prepare('SELECT * FROM templates WHERE id = ? OR name = ? LIMIT 1')
+    .bind(idOrName, idOrName)
+    .first<Template>();
+  return row ?? null;
+}
+
+export async function listTemplates(db: D1Database): Promise<Template[]> {
+  const res = await db.prepare('SELECT * FROM templates ORDER BY created_at DESC').all<Template>();
+  return res.results ?? [];
+}
+
+export async function updateTemplate(db: D1Database, id: string, patch: { description?: string | null; slots?: string[] }): Promise<Template | null> {
+  const cols: string[] = [];
+  const params: unknown[] = [];
+  if (patch.description !== undefined) { cols.push('description = ?'); params.push(patch.description); }
+  if (patch.slots !== undefined) { cols.push('slots_json = ?'); params.push(JSON.stringify(patch.slots)); }
+  if (cols.length === 0) return getTemplate(db, id);
+  cols.push('updated_at = unixepoch()');
+  await db.prepare(`UPDATE templates SET ${cols.join(', ')} WHERE id = ?`).bind(...params, id).run();
+  return getTemplate(db, id);
+}
+
+// ---- Records (entry_values composed by template) ----
+
+export interface CreateRecordInput {
+  template: string;          // template id or name
+  values: Record<string, string>; // slot_name -> content
+  owner_id?: string | null;
+  record_id?: string;
+}
+
+export interface RecordResult {
+  record_id: string;
+  template_id: string;
+  values: Record<string, string>;
+}
+
+export async function createRecord(db: D1Database, input: CreateRecordInput): Promise<RecordResult> {
+  const tpl = await getTemplate(db, input.template);
+  if (!tpl) throw new Error(`template not found: ${input.template}`);
+  const slots: string[] = JSON.parse(tpl.slots_json);
+  const recordId = input.record_id ?? uid('rec');
+
+  for (const slot of slots) {
+    if (!(slot in input.values)) continue;
+    const entry = await createEntry(db, {
+      content: input.values[slot],
+      entry_type: 'value',
+      owner_id: input.owner_id ?? null,
+    });
+    await db
+      .prepare(`INSERT INTO entry_values (id, record_id, template_id, slot_name, entry_id) VALUES (?, ?, ?, ?, ?)`)
+      .bind(uid('ev'), recordId, tpl.id, slot, entry.id)
+      .run();
+  }
+  return { record_id: recordId, template_id: tpl.id, values: input.values };
+}
+
+export async function getRecord(db: D1Database, recordId: string): Promise<RecordResult | null> {
+  const res = await db
+    .prepare(
+      `SELECT ev.slot_name as slot, e.content as content, ev.template_id as template_id
+       FROM entry_values ev JOIN entries e ON ev.entry_id = e.id
+       WHERE ev.record_id = ?`,
+    )
+    .bind(recordId)
+    .all<{ slot: string; content: string; template_id: string }>();
+  const rows = res.results ?? [];
+  if (rows.length === 0) return null;
+  const values: Record<string, string> = {};
+  for (const r of rows) values[r.slot] = r.content;
+  return { record_id: recordId, template_id: rows[0].template_id, values };
+}
+
+export async function searchByTemplate(db: D1Database, template: string, owner_id?: string, limit = 100): Promise<RecordResult[]> {
+  const tpl = await getTemplate(db, template);
+  if (!tpl) return [];
+  const res = await db
+    .prepare(`SELECT DISTINCT record_id FROM entry_values WHERE template_id = ? ORDER BY created_at DESC LIMIT ?`)
+    .bind(tpl.id, Math.min(limit, 500))
+    .all<{ record_id: string }>();
+  const out: RecordResult[] = [];
+  for (const { record_id } of res.results ?? []) {
+    const rec = await getRecord(db, record_id);
+    if (rec && (!owner_id || true)) out.push(rec);
+  }
+  return out;
+}

kbdb/src/index.ts

@@ -0,0 +1,23 @@
+// KBDB Base — atomic universal table worker (arcrun self-hosted data layer + official core).
+// SDD: .agents/specs/arcrun/kbdb-base/design.md
+//
+// Base = D1 only (free, no credit card): entries / templates / records + LIKE search + recipe-stats.
+// Optional modules (NOT in this base): embed (Vectorize+AI binding, semantic search), triplet (separate repo).
+import { Hono } from 'hono';
+import type { Bindings } from './types';
+import { entryRoutes } from './routes/entries';
+import { templateRoutes } from './routes/templates';
+import { recordRoutes } from './routes/records';
+import { recipeStatRoutes } from './routes/recipe-stats';
+
+const app = new Hono<{ Bindings: Bindings }>();
+
+app.get('/', (c) => c.json({ service: 'arcrun-kbdb', tier: 'base', status: 'ok' }));
+app.get('/health', (c) => c.json({ ok: true }));
+
+app.route('/entries', entryRoutes);
+app.route('/templates', templateRoutes);
+app.route('/records', recordRoutes);
+app.route('/recipe-stats', recipeStatRoutes);
+
+export default app;

kbdb/src/routes/entries.ts

@@ -0,0 +1,63 @@
+// Entries route — atomic data + tree (project/workflow). Base, no embed/triplet.
+import { Hono } from 'hono';
+import type { Bindings } from '../types';
+import {
+  createEntry,
+  getEntry,
+  listEntries,
+  updateEntry,
+  deleteEntry,
+  searchEntries,
+} from '../actions/entry-crud';
+
+export const entryRoutes = new Hono<{ Bindings: Bindings }>();
+
+// POST /entries — create (entry_type=block/value/project/workflow/...)
+entryRoutes.post('/', async (c) => {
+  const body = await c.req.json().catch(() => null);
+  if (!body || !body.entry_type) return c.json({ success: false, error: 'entry_type required' }, 400);
+  const entry = await createEntry(c.env.DB, body);
+  return c.json({ success: true, entry });
+});
+
+// GET /entries — list with filters (entry_type, owner_id, parent_id)
+// e.g. list workflows under a project: ?parent_id=PROJECT&entry_type=workflow
+entryRoutes.get('/', async (c) => {
+  const entries = await listEntries(c.env.DB, {
+    entry_type: c.req.query('entry_type') || undefined,
+    owner_id: c.req.query('owner_id') || undefined,
+    parent_id: c.req.query('parent_id') || undefined,
+    limit: c.req.query('limit') ? Number(c.req.query('limit')) : undefined,
+    offset: c.req.query('offset') ? Number(c.req.query('offset')) : undefined,
+  });
+  return c.json({ success: true, entries, count: entries.length });
+});
+
+// GET /entries/search?q=...&owner_id=... — D1 LIKE keyword search (base)
+entryRoutes.get('/search', async (c) => {
+  const q = c.req.query('q');
+  if (!q) return c.json({ success: false, error: 'q required' }, 400);
+  const entries = await searchEntries(c.env.DB, q, c.req.query('owner_id') || undefined);
+  return c.json({ success: true, entries, count: entries.length, mode: 'keyword' });
+});
+
+// GET /entries/:id
+entryRoutes.get('/:id', async (c) => {
+  const entry = await getEntry(c.env.DB, c.req.param('id'));
+  if (!entry) return c.json({ success: false, error: 'not found' }, 404);
+  return c.json({ success: true, entry });
+});
+
+// PATCH /entries/:id
+entryRoutes.patch('/:id', async (c) => {
+  const body = await c.req.json().catch(() => ({}));
+  const entry = await updateEntry(c.env.DB, c.req.param('id'), body);
+  if (!entry) return c.json({ success: false, error: 'not found' }, 404);
+  return c.json({ success: true, entry });
+});
+
+// DELETE /entries/:id
+entryRoutes.delete('/:id', async (c) => {
+  await deleteEntry(c.env.DB, c.req.param('id'));
+  return c.json({ success: true });
+});

kbdb/src/routes/recipe-stats.ts

@@ -0,0 +1,25 @@
+// Recipe stats route (SDD section 7.1) — success/failure counters per recipe.
+// cypher-executor calls POST /recipe-stats/record after each recipe HTTP call;
+// submission reads GET /recipe-stats/:canonical_id as the "proof" for no-verify submit.
+import { Hono } from 'hono';
+import type { Bindings } from '../types';
+import { recordRecipeResult, getRecipeStat } from '../actions/recipe-stat';
+
+export const recipeStatRoutes = new Hono<{ Bindings: Bindings }>();
+
+// POST /recipe-stats/record — { canonical_id, ok, at } (at = epoch ms, passed in by caller)
+recipeStatRoutes.post('/record', async (c) => {
+  const body = await c.req.json().catch(() => null);
+  if (!body || !body.canonical_id || typeof body.ok !== 'boolean') {
+    return c.json({ success: false, error: 'canonical_id and ok(boolean) required' }, 400);
+  }
+  const at = typeof body.at === 'number' ? body.at : 0;
+  const stat = await recordRecipeResult(c.env.DB, body.canonical_id, body.ok, at);
+  return c.json({ success: true, stat });
+});
+
+// GET /recipe-stats/:canonical_id
+recipeStatRoutes.get('/:canonical_id', async (c) => {
+  const stat = await getRecipeStat(c.env.DB, c.req.param('canonical_id'));
+  return c.json({ success: true, stat });
+});

kbdb/src/routes/records.ts

@@ -0,0 +1,33 @@
+// Records route — structured records (entry_values composed by a template).
+import { Hono } from 'hono';
+import type { Bindings } from '../types';
+import { createRecord, getRecord, searchByTemplate } from '../actions/record-crud';
+
+export const recordRoutes = new Hono<{ Bindings: Bindings }>();
+
+// POST /records — { template, values:{slot:content}, owner_id? }
+recordRoutes.post('/', async (c) => {
+  const body = await c.req.json().catch(() => null);
+  if (!body || !body.template || !body.values) {
+    return c.json({ success: false, error: 'template and values required' }, 400);
+  }
+  try {
+    const rec = await createRecord(c.env.DB, body);
+    return c.json({ success: true, record: rec });
+  } catch (e) {
+    return c.json({ success: false, error: e instanceof Error ? e.message : String(e) }, 400);
+  }
+});
+
+// GET /records/by-template/:template — list records of a template
+recordRoutes.get('/by-template/:template', async (c) => {
+  const records = await searchByTemplate(c.env.DB, c.req.param('template'), c.req.query('owner_id') || undefined);
+  return c.json({ success: true, records, count: records.length });
+});
+
+// GET /records/:recordId
+recordRoutes.get('/:recordId', async (c) => {
+  const rec = await getRecord(c.env.DB, c.req.param('recordId'));
+  if (!rec) return c.json({ success: false, error: 'not found' }, 404);
+  return c.json({ success: true, record: rec });
+});

kbdb/src/routes/templates.ts

@@ -0,0 +1,33 @@
+// Templates + Records route. Template = virtual table def; record = composed entries.
+import { Hono } from 'hono';
+import type { Bindings } from '../types';
+import { createTemplate, getTemplate, listTemplates, updateTemplate } from '../actions/record-crud';
+
+export const templateRoutes = new Hono<{ Bindings: Bindings }>();
+
+templateRoutes.post('/', async (c) => {
+  const body = await c.req.json().catch(() => null);
+  if (!body || !body.name || !Array.isArray(body.slots)) {
+    return c.json({ success: false, error: 'name and slots[] required' }, 400);
+  }
+  const tpl = await createTemplate(c.env.DB, body);
+  return c.json({ success: true, template: tpl });
+});
+
+templateRoutes.get('/', async (c) => {
+  const templates = await listTemplates(c.env.DB);
+  return c.json({ success: true, templates, count: templates.length });
+});
+
+templateRoutes.get('/:idOrName', async (c) => {
+  const tpl = await getTemplate(c.env.DB, c.req.param('idOrName'));
+  if (!tpl) return c.json({ success: false, error: 'not found' }, 404);
+  return c.json({ success: true, template: tpl });
+});
+
+templateRoutes.patch('/:id', async (c) => {
+  const body = await c.req.json().catch(() => ({}));
+  const tpl = await updateTemplate(c.env.DB, c.req.param('id'), body);
+  if (!tpl) return c.json({ success: false, error: 'not found' }, 404);
+  return c.json({ success: true, template: tpl });
+});

kbdb/src/types.ts

@@ -0,0 +1,53 @@
+// KBDB Base types. Base depends on D1 only.
+// Optional modules add their own bindings (embed: VECTORIZE+AI). Base never references them.
+
+export type Bindings = {
+  DB: D1Database;
+  ENVIRONMENT: string;
+};
+
+export type EntryType =
+  | 'block'
+  | 'value'
+  | 'template'
+  | 'slot'
+  | 'project'
+  | 'workflow'
+  | 'recipe_stat';
+
+export interface Entry {
+  id: string;
+  content: string | null;
+  entry_type: EntryType | string;
+  owner_id: string | null;
+  parent_id: string | null;
+  page_name: string | null;
+  refs_json: string;
+  tags_json: string;
+  task_status: string | null;
+  content_hash: string | null;
+  is_embedded: number;
+  confidence: number | null;
+  metadata_json: string | null;
+  created_at: number;
+  updated_at: number;
+}
+
+export interface Template {
+  id: string;
+  name: string;
+  description: string | null;
+  slots_json: string;
+  created_by: string | null;
+  created_at: number;
+  updated_at: number;
+}
+
+export interface EntryValue {
+  id: string;
+  record_id: string;
+  template_id: string;
+  slot_name: string;
+  entry_id: string;
+  created_at: number;
+}

kbdb/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ESNext"],
+    "types": ["@cloudflare/workers-types/2023-07-01"],
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "isolatedModules": true,
+    "resolveJsonModule": true,
+    "esModuleInterop": true
+  },
+  "include": ["src/**/*.ts", "tests/**/*.ts"]
+}

kbdb/wrangler.toml

@@ -0,0 +1,16 @@
+name = "arcrun-kbdb"
+main = "src/index.ts"
+compatibility_date = "2025-02-19"
+workers_dev = true
+compatibility_flags = ["nodejs_compat"]
+
+# KBDB Base — atomic universal table (SDD .agents/specs/arcrun/kbdb-base).
+# Base needs D1 ONLY (free, no credit card). embed module adds Vectorize+AI bindings
+# (optional, self-host opens it themselves). triplet is a separate repo.
+[[d1_databases]]
+binding = "DB"
+database_name = "arcrun-kbdb"
+database_id = "placeholder-replaced-by-init"
+
+[vars]
+ENVIRONMENT = "production"