feat(arcrun): implement arcrun MVP — open-source AI workflow engine

Phase 1-5 complete per .agents/specs/u6u-core-mvp/: **Phase 1 — Cherry-pick & cleanup** - Create arcrun/ from cypher-executor, credentials, builtins, registry - Remove 9 InkStone Service Bindings (KBDB, REGISTRY, CLINIC_*, AICEO, MINI_ME) - Rewrite component-loader: 3-layer (builtin → WASM_BUCKET R2 → error) - Remove autoPublishMissing.ts, proxy.ts (AICEO), execution-logger.ts (KBDB) - Clean all KV namespace IDs and InkStone internal URLs from config files **Phase 2 — contract.yaml completeness** - Add credentials_required to gmail, google_sheets, telegram, line_notify - Add config_example to all 21 components with annotated field descriptions **Phase 3 — Credential injection** - Add credential-injector.ts: AES-GCM decrypt from CREDENTIALS_KV - Integrate into GraphExecutor before WASM execution - Structured errors with repair instructions when credential missing **Phase 4 — CLI (acr)** - cli/package.json: arcrun package, bin: acr, deps: commander/js-yaml/chalk/ora - 8 commands: init, creds push, push, run, validate, parts, list, logs - Standard mode: writes directly to user's CF KV via CF REST API - acr init: interactive setup with arcrun.dev API Key registration **Phase 5 — Open source release prep** - README.md: 5-minute quickstart, component table, workflow YAML syntax - CONTRIBUTING.md: TinyGo dev env, component scaffolding, submission flow - Security audit: no InkStone internal URLs/IDs in committed files - .gitignore: exclude credentials.yaml, .wrangler, *.wasm https://claude.ai/code/session_01BnCdSLVH8tUed9VrrPavgT
2026-04-16 04:06:25 +00:00
commit 2707fca32b
155 changed files with 17413 additions and 0 deletions
@@ -0,0 +1,66 @@
+// 確保 KBDB 中存在 tpl-component Template Block
+// Requirements: 12.1
+
+import type { Bindings } from '../types';
+
+const TEMPLATE_ID = 'tpl-component';
+
+const SLOT_KEYS = [
+  'canonical_id',
+  'display_name',
+  'category',
+  'version',
+  'wasi_target',
+  'stability',
+  'runtime_compat',
+  'component_type',
+  'max_size_kb',
+  'max_cold_start_ms',
+  'no_network_syscall',
+  'input_schema',
+  'output_schema',
+  'gherkin_tests',
+  'wasm_r2_key',
+  'cypher_binding_url',
+  'service_binding_key',
+  'description',
+  'tags',
+  'success_rate',
+  'avg_duration_ms',
+  'call_count',
+  'status',
+  'deprecated_at',
+];
+
+export async function ensureTemplate(env: Bindings): Promise<{ created: boolean; template_id: string }> {
+  const kbdbUrl = env.KBDB_URL || 'https://kbdb.finally.click';
+  const headers = {
+    'Content-Type': 'application/json',
+    'Authorization': `Bearer ${env.KBDB_INTERNAL_TOKEN}`,
+  };
+
+  // 先嘗試取得現有 template
+  const getRes = await fetch(`${kbdbUrl}/templates/${TEMPLATE_ID}`, { headers });
+  if (getRes.ok) {
+    return { created: false, template_id: TEMPLATE_ID };
+  }
+
+  // 不存在則建立
+  const createRes = await fetch(`${kbdbUrl}/templates`, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify({
+      template_id: TEMPLATE_ID,
+      name: 'Component',
+      description: 'u6u 零件合約 Template，每個零件版本對應一個 Block',
+      slot_keys: SLOT_KEYS,
+    }),
+  });
+
+  if (!createRes.ok) {
+    const errText = await createRes.text();
+    throw new Error(`建立 tpl-component 失敗（${createRes.status}）：${errText.slice(0, 200)}`);
+  }
+
+  return { created: true, template_id: TEMPLATE_ID };
+}
@@ -0,0 +1,236 @@
+// 回傳 Markdown 格式開發指引
+// Requirements: 11.1, 11.2, 11.3
+
+export function getGuide(): string {
+  return `# u6u Component Authoring Guide
+
+## 概覽
+
+u6u 零件是以 WASI preview1 格式編譯的 WebAssembly 模組，唯一合法的 I/O 模型是 **stdin/stdout JSON**。
+
+---
+
+## TinyGo 白名單 {#tinygo-whitelist}
+
+第一波內部零件使用 TinyGo 開發。**只允許**以下 import：
+
+\`\`\`go
+import (
+    "os"             // 只用 os.Stdin / os.Stdout / os.Stderr
+    "io"             // io.ReadAll(os.Stdin)
+    "encoding/json"  // json.Unmarshal / json.Marshal
+)
+\`\`\`
+
+### 允許的操作
+
+- \`io.ReadAll(os.Stdin)\` 讀取 input JSON
+- \`json.Unmarshal\` 解析 input
+- \`json.Marshal\` + \`os.Stdout.Write\` 輸出 output JSON
+- 基本型別操作（string、int64、float64、bool、[]byte、map[string]interface{}）
+- 錯誤用 stdout 輸出：\`{"error": "說明"}\`，不要 panic
+
+---
+
+## 禁止行為 {#forbidden-behaviors}
+
+以下行為會導致沙盒驗收失敗：
+
+- **網路 syscall**：\`net/*\`、\`sock_connect\`、\`sock_accept\` 等
+- **檔案系統 syscall**：\`os.Open\`、\`os.Create\`、\`path_open\` 等
+- **goroutine / channel**：WASM 環境不支援
+- **syscall.*\`**：任何直接 syscall
+- **第三方 module**：只用標準庫
+- **打包 runtime**：不得打包 QuickJS、Node.js 等
+- **超過 2MB**：體積上限 2048KB
+- **混合前後端邏輯**：一個零件只做一件事
+
+---
+
+## I/O 模型 {#io-model}
+
+唯一合法的 I/O 模型：\`stdin_stdout_json\`
+
+\`\`\`
+stdin  → JSON.stringify(input)  → 零件讀取
+stdout ← JSON.stringify(output) ← 零件輸出
+\`\`\`
+
+---
+
+## TinyGo 最小可運行範例 {#tinygo-example}
+
+\`\`\`go
+package main
+
+import (
+    "encoding/json"
+    "io"
+    "os"
+)
+
+type Input struct {
+    JsonString string \`json:"json_string"\`
+}
+
+type Output struct {
+    Valid bool   \`json:"valid"\`
+    Error string \`json:"error,omitempty"\`
+}
+
+func main() {
+    data, err := io.ReadAll(os.Stdin)
+    if err != nil {
+        writeError("讀取 stdin 失敗: " + err.Error())
+        return
+    }
+
+    var input Input
+    if err := json.Unmarshal(data, &input); err != nil {
+        writeError("解析 input JSON 失敗: " + err.Error())
+        return
+    }
+
+    var result interface{}
+    valid := json.Unmarshal([]byte(input.JsonString), &result) == nil
+
+    out := Output{Valid: valid}
+    if !valid {
+        out.Error = "不合法的 JSON 格式"
+    }
+
+    outBytes, _ := json.Marshal(out)
+    os.Stdout.Write(outBytes)
+}
+
+func writeError(msg string) {
+    out, _ := json.Marshal(map[string]string{"error": msg})
+    os.Stdout.Write(out)
+}
+\`\`\`
+
+---
+
+## component.contract.yaml 完整範例 {#contract-example}
+
+\`\`\`yaml
+canonical_id: "validate_json"
+display_name: "JSON 格式驗證器"
+category: "logic"
+version: "v1"
+wasi_target: "preview1"
+stability: "floating"
+
+runtime_compat:
+  - "cf-workers"
+  - "workerd"
+  - "wazero"
+
+constraints:
+  max_size_kb: 2048
+  max_cold_start_ms: 50
+  no_network_syscall: true
+  io_model: "stdin_stdout_json"
+
+input_schema:
+  type: object
+  required: ["json_string"]
+  properties:
+    json_string:
+      type: string
+      description: "待驗證的 JSON 字串"
+
+output_schema:
+  type: object
+  properties:
+    valid:
+      type: boolean
+    error:
+      type: string
+
+gherkin_tests:
+  - scenario: "合法 JSON 通過驗證"
+    given: '{"json_string":"{\\"key\\":\\"value\\"}"}'
+    then_contains: '{"valid":true}'
+  - scenario: "非法 JSON 回傳錯誤"
+    given: '{"json_string":"not-json"}'
+    then_contains: '{"valid":false,"error":'
+
+tags: ["validation", "json", "utility"]
+description: "驗證輸入字串是否為合法 JSON 格式"
+\`\`\`
+
+---
+
+## 本地測試指令 {#local-testing}
+
+使用 \`wasmtime\` 在本地測試零件：
+
+\`\`\`bash
+# 編譯（TinyGo）
+tinygo build -o validate_json.wasm -target wasi ./main.go
+
+# 測試 happy path
+echo '{"json_string":"{}"}' | wasmtime validate_json.wasm
+# 預期輸出：{"valid":true}
+
+# 測試 error path
+echo '{"json_string":"not-json"}' | wasmtime validate_json.wasm
+# 預期輸出：{"valid":false,"error":"..."}
+\`\`\`
+
+---
+
+## syscall 限制 {#syscall-constraints}
+
+沙盒驗收會掃描 .wasm binary 中的 import，以下 syscall 一律拒絕：
+
+- \`sock_connect\`、\`sock_accept\`、\`sock_recv\`、\`sock_send\`、\`sock_shutdown\`
+- \`fd_open\`、\`path_open\`、\`path_create_directory\`、\`path_remove_directory\`
+- \`path_rename\`、\`path_unlink_file\`、\`path_filestat_get\`
+
+---
+
+## 常見錯誤與解法 {#common-errors}
+
+| 錯誤 | 原因 | 解法 |
+|---|---|---|
+| \`size_check 失敗\` | .wasm 超過 2048KB | 移除不必要的依賴，使用 TinyGo 而非 Go |
+| \`syscall_scan 失敗\` | 含有網路/檔案 syscall | 移除 \`net/*\`、\`os.Open\` 等 import |
+| \`gherkin_tests 失敗\` | 輸出不符合預期 | 確認 stdout 輸出為合法 JSON |
+| \`contract 驗證失敗\` | 缺少必填欄位 | 參考上方 contract 範例補齊欄位 |
+
+---
+
+## contract.yaml JSON Schema {#contract-schema}
+
+\`\`\`json
+{
+  "type": "object",
+  "required": ["canonical_id", "display_name", "category", "version", "wasi_target", "stability", "runtime_compat", "constraints", "input_schema", "output_schema", "gherkin_tests"],
+  "properties": {
+    "canonical_id": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" },
+    "display_name": { "type": "string" },
+    "category": { "type": "string", "enum": ["logic", "api", "ui", "style", "anim"] },
+    "version": { "type": "string", "pattern": "^v\\\\d+$" },
+    "wasi_target": { "type": "string", "enum": ["preview1"] },
+    "stability": { "type": "string", "enum": ["floating", "stable", "pinned"] },
+    "runtime_compat": { "type": "array", "items": { "type": "string", "enum": ["cf-workers", "workerd", "wazero"] }, "minItems": 1 },
+    "constraints": {
+      "type": "object",
+      "required": ["max_size_kb", "max_cold_start_ms", "no_network_syscall", "io_model"],
+      "properties": {
+        "max_size_kb": { "type": "number", "maximum": 2048 },
+        "max_cold_start_ms": { "type": "number", "maximum": 50 },
+        "no_network_syscall": { "type": "boolean" },
+        "io_model": { "type": "string", "enum": ["stdin_stdout_json"] }
+      }
+    },
+    "input_schema": { "type": "object" },
+    "output_schema": { "type": "object" },
+    "gherkin_tests": { "type": "array", "minItems": 2 }
+  }
+}
+\`\`\`
+`;
+}
@@ -0,0 +1,162 @@
+// queryComponents — 查詢零件合約與語意搜尋
+// Requirements: 12.2, 12.3
+
+import type { Bindings } from '../types';
+
+export interface ComponentVersion {
+  canonical_id: string;
+  display_name: string;
+  version: string;
+  category: string;
+  stability: string;
+  status: string;
+  description: string;
+  tags: string[];
+  success_rate: number;
+  avg_duration_ms: number;
+  call_count: number;
+  wasm_r2_key?: string;
+  cypher_binding_url?: string;
+  score: number;
+}
+
+/** 從 KBDB 取得零件的最優版本合約 */
+export async function getComponent(
+  canonicalId: string,
+  env: Bindings,
+): Promise<ComponentVersion | null> {
+  const kbdbUrl = env.KBDB_URL || 'https://kbdb.finally.click';
+  const headers = {
+    'Content-Type': 'application/json',
+    'Authorization': `Bearer ${env.KBDB_INTERNAL_TOKEN}`,
+  };
+
+  // 搜尋所有版本（block_id 前綴 comp-{id}-）
+  const res = await fetch(
+    `${kbdbUrl}/records/search?template_id=tpl-component&canonical_id=${encodeURIComponent(canonicalId)}&limit=20`,
+    { headers },
+  );
+
+  if (!res.ok) return null;
+
+  const data = await res.json() as { records?: Array<{ record_id: string; values: Record<string, string> }> };
+  const records = (data.records ?? []).filter(r =>
+    r.values.canonical_id === canonicalId && r.values.status !== 'tombstone'
+  );
+
+  if (records.length === 0) return null;
+
+  // 選取評分最高的版本（floating 策略）
+  const scored = records.map(r => ({
+    ...r.values,
+    score: computeScore(r.values),
+  }));
+  scored.sort((a, b) => b.score - a.score);
+  const best = scored[0];
+
+  return toComponentVersion(best);
+}
+
+/** 取得零件所有版本清單（含評分排序） */
+export async function getComponentVersions(
+  canonicalId: string,
+  env: Bindings,
+): Promise<ComponentVersion[]> {
+  const kbdbUrl = env.KBDB_URL || 'https://kbdb.finally.click';
+  const headers = {
+    'Content-Type': 'application/json',
+    'Authorization': `Bearer ${env.KBDB_INTERNAL_TOKEN}`,
+  };
+
+  const res = await fetch(
+    `${kbdbUrl}/records/search?template_id=tpl-component&canonical_id=${encodeURIComponent(canonicalId)}&limit=20`,
+    { headers },
+  );
+
+  if (!res.ok) return [];
+
+  const data = await res.json() as { records?: Array<{ record_id: string; values: Record<string, string> }> };
+  const records = (data.records ?? []).filter(r =>
+    r.values.canonical_id === canonicalId && r.values.status !== 'tombstone'
+  );
+
+  return records
+    .map(r => ({ ...r.values, score: computeScore(r.values) }))
+    .sort((a, b) => b.score - a.score)
+    .slice(0, 10)
+    .map(toComponentVersion);
+}
+
+/** 語意搜尋零件（透過 KBDB Vectorize） */
+export async function searchComponents(
+  query: string,
+  env: Bindings,
+): Promise<ComponentVersion[]> {
+  const kbdbUrl = env.KBDB_URL || 'https://kbdb.finally.click';
+  const headers = {
+    'Content-Type': 'application/json',
+    'Authorization': `Bearer ${env.KBDB_INTERNAL_TOKEN}`,
+  };
+
+  // 透過 KBDB 語意搜尋（Vectorize）
+  const res = await fetch(`${kbdbUrl}/search`, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify({
+      query,
+      type: 'suggest',
+      topK: 10,
+      filter: { template_id: 'tpl-component' },
+    }),
+  });
+
+  if (!res.ok) return [];
+
+  const data = await res.json() as { matches?: Array<{ block_id: string; score: number; metadata?: Record<string, string> }> };
+  const matches = data.matches ?? [];
+
+  // 取得每個匹配的完整合約
+  const results: ComponentVersion[] = [];
+  for (const match of matches.slice(0, 10)) {
+    const blockRes = await fetch(`${kbdbUrl}/records/${match.block_id}`, { headers });
+    if (!blockRes.ok) continue;
+    const block = await blockRes.json() as { values: Record<string, string> };
+    if (block.values.status === 'tombstone') continue;
+    results.push(toComponentVersion({ ...block.values, score: match.score }));
+  }
+
+  return results;
+}
+
+// ── 內部工具函數 ──────────────────────────────────────────────────────────────
+
+/** 計算零件評分：成功率 × 速度評分 × log(被調用次數 + 1) */
+function computeScore(v: Record<string, string>): number {
+  const successRate = parseFloat(v.success_rate ?? '1');
+  const avgDuration = parseFloat(v.avg_duration_ms ?? '10');
+  const callCount = parseInt(v.call_count ?? '0', 10);
+  // 速度評分：越快越高，50ms 為基準
+  const speedScore = Math.max(0, 1 - avgDuration / 1000);
+  return successRate * speedScore * Math.log(callCount + 2);
+}
+
+function toComponentVersion(v: Record<string, string | number>): ComponentVersion {
+  return {
+    canonical_id: String(v.canonical_id ?? ''),
+    display_name: String(v.display_name ?? ''),
+    version: String(v.version ?? 'v1'),
+    category: String(v.category ?? 'logic'),
+    stability: String(v.stability ?? 'floating'),
+    status: String(v.status ?? 'active'),
+    description: String(v.description ?? ''),
+    tags: (() => {
+      try { return JSON.parse(String(v.tags ?? '[]')); } catch { return []; }
+    })(),
+    success_rate: parseFloat(String(v.success_rate ?? '1')),
+    avg_duration_ms: parseFloat(String(v.avg_duration_ms ?? '0')),
+    call_count: parseInt(String(v.call_count ?? '0'), 10),
+    wasm_r2_key: v.wasm_r2_key ? String(v.wasm_r2_key) : undefined,
+    cypher_binding_url: v.cypher_binding_url ? String(v.cypher_binding_url) : undefined,
+    score: typeof v.score === 'number' ? v.score : parseFloat(String(v.score ?? '0')),
+  };
+}
@@ -0,0 +1,96 @@
+// 沙盒驗收流程：五個步驟依序執行
+// Requirements: 2.1, 2.2, 2.3
+
+import { FORBIDDEN_SYSCALLS } from '../types';
+import type { ComponentContract, SandboxResult, SandboxStep } from '../types';
+
+// ── 步驟 (a)：體積檢查 ────────────────────────────────────────────────────────
+
+function checkSize(wasmBytes: Uint8Array, contract: ComponentContract): string | null {
+  const maxSizeKb = contract.constraints.max_size_kb;
+  const actualKb = wasmBytes.byteLength / 1024;
+  if (actualKb > maxSizeKb) {
+    return `體積 ${actualKb.toFixed(1)}KB 超過上限 ${maxSizeKb}KB`;
+  }
+  return null;
+}
+
+// ── 步驟 (b)：冷啟動時間（Phase 0 mock 0ms）────────────────────────────────────
+
+function checkColdStart(_wasmBytes: Uint8Array, _contract: ComponentContract): string | null {
+  // Phase 0：mock 通過，記錄 0ms
+  // Phase 2 再實作真實測量
+  return null;
+}
+
+// ── 步驟 (c)：syscall 掃描 ────────────────────────────────────────────────────
+
+function scanSyscalls(wasmBytes: Uint8Array): string | null {
+  // 將 .wasm binary 轉為文字，搜尋禁止的 import 字串
+  // WASM binary 中 import section 的函數名稱以 UTF-8 字串形式存在
+  const text = new TextDecoder('utf-8', { fatal: false }).decode(wasmBytes);
+
+  for (const syscall of FORBIDDEN_SYSCALLS) {
+    if (text.includes(syscall)) {
+      return `發現禁止的 syscall：${syscall}`;
+    }
+  }
+  return null;
+}
+
+// ── 步驟 (d)：Gherkin 測試（Phase 0 mock 通過）────────────────────────────────
+
+function runGherkinTests(_wasmBytes: Uint8Array, _contract: ComponentContract): string | null {
+  // Phase 0：mock 通過
+  // Phase 1 再實作真實 Gherkin 執行
+  return null;
+}
+
+// ── 步驟 (e)：runtime 相容測試（Phase 0 mock 通過）────────────────────────────
+
+function checkRuntimeCompat(_wasmBytes: Uint8Array, _contract: ComponentContract): string | null {
+  // Phase 0：mock 通過
+  // Phase 2 再實作真實多 runtime 測試
+  return null;
+}
+
+// ── 主流程 ────────────────────────────────────────────────────────────────────
+
+interface StepDef {
+  name: SandboxStep;
+  run: (wasmBytes: Uint8Array, contract: ComponentContract) => string | null;
+  guideAnchor: string;
+}
+
+const STEPS: StepDef[] = [
+  { name: 'size_check',     run: checkSize,           guideAnchor: '#common-errors' },
+  { name: 'cold_start',     run: checkColdStart,      guideAnchor: '#common-errors' },
+  { name: 'syscall_scan',   run: scanSyscalls,        guideAnchor: '#syscall-constraints' },
+  { name: 'gherkin_tests',  run: runGherkinTests,     guideAnchor: '#local-testing' },
+  { name: 'runtime_compat', run: checkRuntimeCompat,  guideAnchor: '#contract-example' },
+];
+
+export function runSandboxAcceptance(
+  wasmBytes: Uint8Array,
+  contract: ComponentContract,
+): SandboxResult {
+  for (const step of STEPS) {
+    const error = step.run(wasmBytes, contract);
+    if (error !== null) {
+      return {
+        success: false,
+        failed_step: step.name,
+        reason: error,
+        guide_anchor: step.guideAnchor,
+        component_id: contract.canonical_id,
+        version: contract.version,
+      };
+    }
+  }
+
+  return {
+    success: true,
+    component_id: contract.canonical_id,
+    version: contract.version,
+  };
+}
@@ -0,0 +1,90 @@
+// 零件提交：沙盒驗收 → 寫入 KBDB Block → 上傳 R2
+// Requirements: 2.1, 2.2, 2.3
+
+import { runSandboxAcceptance } from './sandboxAcceptance';
+import type { ComponentContract, SandboxResult, Bindings } from '../types';
+
+export async function submitComponent(
+  wasmBytes: Uint8Array,
+  contract: ComponentContract,
+  env: Bindings,
+): Promise<SandboxResult & { wasm_r2_key?: string }> {
+  // 1. 沙盒驗收
+  const sandboxResult = runSandboxAcceptance(wasmBytes, contract);
+  if (!sandboxResult.success) {
+    return sandboxResult;
+  }
+
+  const blockId = `comp-${contract.canonical_id}-${contract.version}`;
+  const r2Key = `components/${contract.canonical_id}/${contract.version}.wasm`;
+
+  // 2. 上傳 .wasm 至 R2
+  await env.WASM_BUCKET.put(r2Key, wasmBytes, {
+    httpMetadata: { contentType: 'application/wasm' },
+  });
+
+  // 3. 寫入 KBDB Block（冪等：先嘗試取得，存在則更新，不存在則建立）
+  const kbdbUrl = env.KBDB_URL || 'https://kbdb.finally.click';
+  const headers = {
+    'Content-Type': 'application/json',
+    'Authorization': `Bearer ${env.KBDB_INTERNAL_TOKEN}`,
+  };
+
+  const slots: Record<string, string> = {
+    canonical_id: contract.canonical_id,
+    display_name: contract.display_name,
+    category: contract.category,
+    version: contract.version,
+    wasi_target: contract.wasi_target,
+    stability: contract.stability,
+    runtime_compat: JSON.stringify(contract.runtime_compat),
+    component_type: contract.component_type ?? 'wasm',
+    max_size_kb: String(contract.constraints.max_size_kb),
+    max_cold_start_ms: String(contract.constraints.max_cold_start_ms),
+    no_network_syscall: String(contract.constraints.no_network_syscall),
+    input_schema: JSON.stringify(contract.input_schema),
+    output_schema: JSON.stringify(contract.output_schema),
+    gherkin_tests: JSON.stringify(contract.gherkin_tests),
+    wasm_r2_key: r2Key,
+    description: contract.description ?? '',
+    tags: JSON.stringify(contract.tags ?? []),
+    success_rate: '1',
+    avg_duration_ms: '0',
+    call_count: '0',
+    status: 'active',
+    deprecated_at: '',
+  };
+
+  if (contract.cypher_binding_url) slots.cypher_binding_url = contract.cypher_binding_url;
+  if (contract.service_binding_key) slots.service_binding_key = contract.service_binding_key;
+
+  // 冪等：先查是否存在
+  const existRes = await fetch(`${kbdbUrl}/records/${blockId}`, { headers });
+
+  if (existRes.ok) {
+    // 已存在：更新 slots
+    await fetch(`${kbdbUrl}/records/${blockId}`, {
+      method: 'PUT',
+      headers,
+      body: JSON.stringify({ values: slots }),
+    });
+  } else {
+    // 不存在：建立新 Block
+    await fetch(`${kbdbUrl}/records`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({
+        record_id: blockId,
+        template_id: 'tpl-component',
+        values: slots,
+      }),
+    });
+  }
+
+  return {
+    success: true,
+    component_id: contract.canonical_id,
+    version: contract.version,
+    wasm_r2_key: r2Key,
+  };
+}
@@ -0,0 +1,34 @@
+// 驗證 component.contract.yaml 所有必填欄位
+// Requirements: 1.1, 1.2, 11.5
+
+import { ComponentContractSchema } from '../types';
+import type { ComponentContract } from '../types';
+
+export interface ValidateContractResult {
+  valid: boolean;
+  missing_fields: string[];
+  errors: string[];
+  contract?: ComponentContract;
+}
+
+export function validateContract(raw: unknown): ValidateContractResult {
+  const result = ComponentContractSchema.safeParse(raw);
+
+  if (result.success) {
+    return { valid: true, missing_fields: [], errors: [], contract: result.data };
+  }
+
+  const missing_fields: string[] = [];
+  const errors: string[] = [];
+
+  for (const issue of result.error.issues) {
+    const path = issue.path.join('.');
+    if (issue.code === 'invalid_type' && issue.received === 'undefined') {
+      missing_fields.push(path || issue.message);
+    } else {
+      errors.push(path ? `${path}: ${issue.message}` : issue.message);
+    }
+  }
+
+  return { valid: false, missing_fields, errors };
+}