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>

registry/src/actions/detectFakeComponent.ts

@@ -0,0 +1,92 @@
+// G1 假零件偵測（component-gatekeeping SDD，R2）
+//
+// 判準（DECISIONS §1）：零件若滿足任一，是假零件，該降級成 recipe / 工作流：
+//   (a) contract 或 wasm binary 出現具體外部服務 URL / domain
+//   (b) 宣告能力是 http_request 子集（打某固定 endpoint）
+//
+// Q2 決議（richblack 2026-05-29）：兩者都「硬擋」（不是只 warn）。
+//   理由：零件不該連外，連外即 recipe。這兩個 pattern 都是「該是 recipe 的東西偽裝成零件」。
+//
+// 排除：auth_* primitive（credential 後端，DECISIONS §3b 不適用假零件判準）、http_request 自己。
+
+import type { ComponentContract } from '../types';
+
+// auth primitive 與 http_request 不適用假零件判準
+const EXEMPT_IDS = new Set([
+  'http_request',
+  'auth_static_key',
+  'auth_oauth2',
+  'auth_service_account',
+  'auth_mtls',
+]);
+
+// 外部 URL / domain pattern。
+// - 明確的 scheme://host
+// - 裸 domain（api.foo.com / foo.googleapis.com 之類）
+const URL_SCHEME_RE = /\bhttps?:\/\/[^\s"'`)]+/i;
+// 裸 domain：至少 host.tld，排除過於通用的誤判（如 stdin.json）——要求含常見 TLD 或 .xxx.yyy 多段
+const BARE_DOMAIN_RE = /\b[a-z0-9][a-z0-9-]*(\.[a-z0-9-]+)*\.(com|org|net|dev|io|me|click|app|co|googleapis\.com|telegram\.org)\b/i;
+
+/**
+ * 把 contract 的文字欄位攤平成一個字串，供 URL 掃描。
+ * 掃 description / display_name / input_schema / output_schema / tags / aliases。
+ */
+function flattenContractText(contract: ComponentContract): string {
+  const parts: string[] = [
+    contract.display_name ?? '',
+    contract.description ?? '',
+    JSON.stringify(contract.input_schema ?? {}),
+    JSON.stringify(contract.output_schema ?? {}),
+    (contract.tags ?? []).join(' '),
+    (contract.aliases ?? []).join(' '),
+  ];
+  return parts.join('\n');
+}
+
+/**
+ * 偵測投稿零件是否為假零件。
+ * 回 null = 通過；回字串 = 退稿原因（已含指回正路的訊息）。
+ */
+export function detectFakeComponent(
+  contract: ComponentContract,
+  wasmBytes: Uint8Array,
+): string | null {
+  if (EXEMPT_IDS.has(contract.canonical_id)) {
+    return null;
+  }
+
+  const pointToRecipe =
+    '。這該是 API recipe（http_request + 固定設定）或工作流，不是零件。' +
+    '零件 = 封閉邏輯（流程控制 / 資料處理），不連外部服務。見 DECISIONS §1。';
+
+  // (a) contract 文字含外部 URL / domain
+  const contractText = flattenContractText(contract);
+  const schemeHit = contractText.match(URL_SCHEME_RE);
+  if (schemeHit) {
+    return `偵測到 contract 含外部 URL：${schemeHit[0].slice(0, 80)}${pointToRecipe}`;
+  }
+  const domainHit = contractText.match(BARE_DOMAIN_RE);
+  if (domainHit) {
+    return `偵測到 contract 含外部 domain：${domainHit[0]}${pointToRecipe}`;
+  }
+
+  // (a') wasm binary 文字含外部 URL / domain（零件原碼把 endpoint 編進去）
+  // 只掃可印 ASCII 區段以降低誤判；wasm 字串以 UTF-8 存放。
+  const wasmText = new TextDecoder('utf-8').decode(wasmBytes);
+  const wasmSchemeHit = wasmText.match(URL_SCHEME_RE);
+  if (wasmSchemeHit) {
+    return `偵測到 wasm 內嵌外部 URL：${wasmSchemeHit[0].slice(0, 80)}${pointToRecipe}`;
+  }
+
+  // (b) http_request 子集：零件宣告自己只是「打某 API/endpoint」
+  // heuristic：description 描述「打/呼叫 ... API/endpoint」+ input 有 url-like 欄位
+  const desc = (contract.description ?? '') + ' ' + contract.display_name;
+  const inputKeys = Object.keys(contract.input_schema ?? {}).join(' ').toLowerCase();
+  const hasUrlField = /\b(url|endpoint|api_url|base_url|host)\b/.test(inputKeys);
+  const describesHttpCall = /(打|呼叫|call|fetch|request|POST|GET|PUT|DELETE)\s*.*(api|endpoint|url|https?)/i.test(desc);
+  if (hasUrlField && describesHttpCall) {
+    return `偵測到疑似 http_request 子集（input 有 url 欄位 + 描述為打 API）${pointToRecipe}`;
+  }
+
+  return null;
+}

registry/src/actions/ensureTemplate.ts

@@ -0,0 +1,21 @@
+// ensureTemplate — 確保 SUBMISSIONS_KV 可正常存取（健康檢查用）
+// Requirements: 12.1
+//
+// 原本此模組負責在 KBDB 建立 tpl-component Template Block。
+// 已改為 SUBMISSIONS_KV 模式後，不再需要預建 Template。
+// 此函式改為驗證 KV binding 是否正常，供 /init 端點呼叫。
+
+import type { Bindings } from '../types';
+
+export async function ensureTemplate(env: Bindings): Promise<{ created: boolean; template_id: string }> {
+  // 寫入並讀取一個測試 key，確認 KV binding 正常
+  const testKey = '_init_health_check';
+  await env.SUBMISSIONS_KV.put(testKey, '1', { expirationTtl: 60 });
+  const val = await env.SUBMISSIONS_KV.get(testKey);
+
+  if (val !== '1') {
+    throw new Error('SUBMISSIONS_KV binding 異常：寫入後無法讀取');
+  }
+
+  return { created: true, template_id: 'submissions_kv' };
+}

registry/src/actions/getGuide.ts

@@ -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 }
+  }
+}
+\`\`\`
+`;
+}

registry/src/actions/indexOnlyComponent.ts

@@ -0,0 +1,85 @@
+// 零件 metadata-only 索引：只寫 KV，不沙盒、不上 R2
+// 用途：backfill 既有已部署但未索引的零件（cypher-executor 不從 R2 讀 wasm，零件用獨立 Worker URL）
+// SDD: matrix/arcrun/.agents/specs/component-registry-canon/design.md Phase 1
+//
+// 跟 submitComponent 對照：
+//   submitComponent  → 跑沙盒 + 寫 R2 + 寫 KV
+//   indexOnlyComponent → 只寫 KV（hash_id 規則一致：cmp_ + sha256(canonical_id)[:8]）
+//
+// 冪等：相同 canonical_id + version 不重複寫
+
+import type { ComponentContract, Bindings } from '../types';
+
+async function deriveHashId(canonicalId: string): Promise<string> {
+  const encoder = new TextEncoder();
+  const data = encoder.encode(canonicalId);
+  const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  const hex = hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
+  return 'cmp_' + hex.slice(0, 8);
+}
+
+export interface IndexOnlyResult {
+  success: boolean;
+  component_hash_id: string;
+  canonical_id: string;
+  version: string;
+  already_indexed: boolean;
+}
+
+export async function indexOnlyComponent(
+  contract: ComponentContract,
+  env: Bindings,
+): Promise<IndexOnlyResult> {
+  const hashId = await deriveHashId(contract.canonical_id);
+  const kvKey = `comp:${hashId}:${contract.version}`;
+
+  const existing = await env.SUBMISSIONS_KV.get(kvKey);
+  if (existing) {
+    return {
+      success: true,
+      component_hash_id: hashId,
+      canonical_id: contract.canonical_id,
+      version: contract.version,
+      already_indexed: true,
+    };
+  }
+
+  const record = {
+    component_hash_id: hashId,
+    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: contract.runtime_compat,
+    component_type: contract.component_type ?? 'wasm',
+    constraints: contract.constraints,
+    input_schema: contract.input_schema,
+    output_schema: contract.output_schema,
+    gherkin_tests: contract.gherkin_tests,
+    description: contract.description ?? '',
+    aliases: contract.aliases ?? [],
+    tags: contract.tags ?? [],
+    success_rate: 1,
+    avg_duration_ms: 0,
+    call_count: 0,
+    visibility: 'public' as const,
+    status: 'active' as const,
+    submitted_at: new Date().toISOString(),
+    deprecated_at: null,
+    indexed_only: true,
+  };
+
+  await env.SUBMISSIONS_KV.put(kvKey, JSON.stringify(record));
+  await env.SUBMISSIONS_KV.put(`idx:${contract.canonical_id}`, hashId);
+
+  return {
+    success: true,
+    component_hash_id: hashId,
+    canonical_id: contract.canonical_id,
+    version: contract.version,
+    already_indexed: false,
+  };
+}

registry/src/actions/queryComponents.ts

@@ -0,0 +1,162 @@
+// queryComponents — 查詢零件合約
+// 支援兩種查詢 id：
+//   component_hash_id（cmp_xxxxxxxx）— 永久穩定，workflow 引用用
+//   canonical_id（小寫底線）         — 可讀名稱，透過 idx: 反查索引解析
+// Requirements: 12.2, 12.3
+
+import type { Bindings } from '../types';
+
+export interface ComponentRecord {
+  component_hash_id: string;
+  canonical_id: string;
+  display_name: string;
+  version: string;
+  category: string;
+  stability: string;
+  status: string;
+  description: string;
+  aliases: string[];
+  tags: string[];
+  success_rate: number;
+  avg_duration_ms: number;
+  call_count: number;
+  wasm_r2_key?: string;
+  score: number;
+}
+
+// ── id 解析：支援 hash_id 和 canonical_id 兩種格式 ──────────────────────────
+
+async function resolveHashId(id: string, env: Bindings): Promise<string | null> {
+  // 已經是 hash_id 格式
+  if (id.startsWith('cmp_')) return id;
+  // canonical_id → 透過 idx: 反查索引
+  const hashId = await env.SUBMISSIONS_KV.get(`idx:${id}`);
+  return hashId;
+}
+
+// ── 取得零件的所有版本 ────────────────────────────────────────────────────────
+
+async function listVersions(hashId: string, env: Bindings): Promise<ComponentRecord[]> {
+  const prefix = `comp:${hashId}:`;
+  const list = await env.SUBMISSIONS_KV.list({ prefix });
+
+  const records: ComponentRecord[] = [];
+  for (const key of list.keys) {
+    const raw = await env.SUBMISSIONS_KV.get(key.name);
+    if (!raw) continue;
+    try {
+      const v = JSON.parse(raw);
+      if (v.status === 'tombstone') continue;
+      records.push(toComponentRecord(v));
+    } catch {
+      continue;
+    }
+  }
+  return records;
+}
+
+// ── 公開 API ──────────────────────────────────────────────────────────────────
+
+/** 取得零件最優版本（floating 策略：成功率 × 速度 × log(使用次數)） */
+export async function getComponent(
+  id: string,
+  env: Bindings,
+): Promise<ComponentRecord | null> {
+  const hashId = await resolveHashId(id, env);
+  if (!hashId) return null;
+
+  const versions = await listVersions(hashId, env);
+  if (versions.length === 0) return null;
+
+  versions.sort((a, b) => b.score - a.score);
+  return versions[0];
+}
+
+/** 取得零件所有版本清單（含評分排序） */
+export async function getComponentVersions(
+  id: string,
+  env: Bindings,
+): Promise<ComponentRecord[]> {
+  const hashId = await resolveHashId(id, env);
+  if (!hashId) return [];
+
+  const versions = await listVersions(hashId, env);
+  versions.sort((a, b) => b.score - a.score);
+  return versions.slice(0, 10);
+}
+
+/** 關鍵字搜尋（掃描 KV prefix comp:，比對 canonical_id / display_name / description / aliases）
+ *
+ * 注意：這是 Phase 0 的純文字比對版本。
+ * Phase 2 接入 Cloudflare Vectorize 後改為語意搜尋，API 介面不變。
+ */
+export async function searchComponents(
+  query: string,
+  env: Bindings,
+): Promise<ComponentRecord[]> {
+  const q = query.toLowerCase();
+
+  // 列出所有 comp: 前綴的 key（只取最新一頁，最多 1000 個）
+  const list = await env.SUBMISSIONS_KV.list({ prefix: 'comp:' });
+
+  const seen = new Set<string>(); // 每個 hash_id 只取最優版本
+  const candidates: ComponentRecord[] = [];
+
+  for (const key of list.keys) {
+    const raw = await env.SUBMISSIONS_KV.get(key.name);
+    if (!raw) continue;
+    let v: Record<string, unknown>;
+    try { v = JSON.parse(raw); } catch { continue; }
+
+    if (v.status === 'tombstone' || v.visibility !== 'public') continue;
+
+    // 比對：canonical_id / display_name / description / aliases
+    const searchable = [
+      String(v.canonical_id ?? ''),
+      String(v.display_name ?? ''),
+      String(v.description ?? ''),
+      ...(Array.isArray(v.aliases) ? v.aliases.map(String) : []),
+      ...(Array.isArray(v.tags) ? v.tags.map(String) : []),
+    ].join(' ').toLowerCase();
+
+    if (!searchable.includes(q)) continue;
+
+    const hashId = String(v.component_hash_id ?? '');
+    if (seen.has(`${hashId}:${v.version}`)) continue;
+    seen.add(`${hashId}:${v.version}`);
+    candidates.push(toComponentRecord(v));
+  }
+
+  candidates.sort((a, b) => b.score - a.score);
+  return candidates.slice(0, 10);
+}
+
+// ── 內部工具函數 ──────────────────────────────────────────────────────────────
+
+function computeScore(v: Record<string, unknown>): number {
+  const successRate = parseFloat(String(v.success_rate ?? '1'));
+  const avgDuration = parseFloat(String(v.avg_duration_ms ?? '10'));
+  const callCount = parseInt(String(v.call_count ?? '0'), 10);
+  const speedScore = Math.max(0, 1 - avgDuration / 1000);
+  return successRate * speedScore * Math.log(callCount + 2);
+}
+
+function toComponentRecord(v: Record<string, unknown>): ComponentRecord {
+  return {
+    component_hash_id: String(v.component_hash_id ?? ''),
+    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 ?? ''),
+    aliases: Array.isArray(v.aliases) ? v.aliases.map(String) : [],
+    tags: Array.isArray(v.tags) ? v.tags.map(String) : [],
+    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,
+    score: computeScore(v),
+  };
+}

registry/src/actions/sandboxAcceptance.ts

@@ -0,0 +1,145 @@
+// 沙盒驗收流程：五個步驟依序執行
+// Requirements: 2.1, 2.2, 2.3
+
+import { FORBIDDEN_SYSCALLS } from '../types';
+import type { ComponentContract, SandboxResult, SandboxStep } from '../types';
+import { detectFakeComponent } from './detectFakeComponent';
+import { checkPureWasi } from './wasmImports';
+// 註：G4 Gherkin 不在 registry 跑（CF Worker 禁止 runtime 編譯 wasm）。
+// Gherkin 在投稿者本地（CLI/Node）跑，registry 只驗 gherkin_evidence 一致性。
+// 見 .agents/specs/component-gatekeeping/design.md §4 修訂。
+
+// ── 步驟 (G1)：假零件偵測（最先擋，component-gatekeeping SDD R2）─────────────────
+
+function checkFakeComponent(wasmBytes: Uint8Array, contract: ComponentContract): string | null {
+  return detectFakeComponent(contract, wasmBytes);
+}
+
+// ── 步驟 (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）────────────────────────────────────
+
+
+// ── 步驟 (c)：syscall 掃描 ────────────────────────────────────────────────────
+
+function scanSyscalls(wasmBytes: Uint8Array): string | null {
+  // G3（R3）：import module 白名單 — 只准 wasi_snapshot_preview1 + u6u（避免 runtime 鎖定）。
+  const pureWasiError = checkPureWasi(wasmBytes);
+  if (pureWasiError !== null) {
+    return pureWasiError;
+  }
+
+  // 次要：禁止 syscall 黑名單（網路/檔案系統 import 名）。
+  // WASM binary 中 import section 的函數名稱以 UTF-8 字串形式存在。
+  const text = new TextDecoder('utf-8').decode(wasmBytes);
+  for (const syscall of FORBIDDEN_SYSCALLS) {
+    if (text.includes(syscall)) {
+      return `發現禁止的 syscall：${syscall}`;
+    }
+  }
+  return null;
+}
+
+// 註：cold_start / runtime_compat 未實作（列 UNIMPLEMENTED_STEPS，不假綠）。
+// Gherkin 執行不在 registry（CF 跑不了 wasm），在投稿者本地；registry 只驗 evidence。
+
+// ── 主流程 ────────────────────────────────────────────────────────────────────
+
+interface StepDef {
+  name: SandboxStep;
+  run: (wasmBytes: Uint8Array, contract: ComponentContract) => string | null;
+  guideAnchor: string;
+}
+
+// registry 端把關步驟（全靜態，CF Worker 可跑；不執行 wasm）。
+// G4 Gherkin 的「執行」在投稿者本地（CLI/Node），registry 只驗 evidence 一致性。
+const STEPS: StepDef[] = [
+  { name: 'fake_component_scan', run: checkFakeComponent, guideAnchor: '#fake-component' },
+  { name: 'size_check',     run: checkSize,           guideAnchor: '#common-errors' },
+  { name: 'syscall_scan',   run: scanSyscalls,        guideAnchor: '#syscall-constraints' },
+];
+
+// 未真正實作 / 未在 registry 端執行的步驟（誠實標記，§3c/§7 禁假綠）：
+//   gherkin_tests：在投稿者本地跑，registry 只驗 evidence（不重跑）→ 第一期 evidence 可造假
+//   cold_start / runtime_compat：mock，未實作
+const UNIMPLEMENTED_STEPS: SandboxStep[] = ['gherkin_tests', 'cold_start', 'runtime_compat'];
+
+/** 投稿者本地跑 Gherkin 的結果證據（CLI 上傳；registry 存證可審） */
+export interface GherkinEvidence {
+  scenario: string;
+  given: string;
+  actual_stdout: string;
+  passed: boolean;
+}
+
+function fail(step: SandboxStep, reason: string, guideAnchor: string, contract: ComponentContract): SandboxResult {
+  return {
+    success: false,
+    failed_step: step,
+    reason,
+    guide_anchor: guideAnchor,
+    component_hash_id: '',
+    canonical_id: contract.canonical_id,
+    version: contract.version,
+  };
+}
+
+/**
+ * 驗 gherkin_evidence 與 contract 一致（不重跑 wasm，CF 跑不了）：
+ *   - evidence 的 scenario 集合須涵蓋 contract.gherkin_tests 的每個 scenario
+ *   - 每個 evidence.passed 須為 true
+ * 回 null = 通過；回字串 = 退稿原因。
+ * evidence 缺省（backfill / 舊投稿）→ 不擋（回 null），但 gherkin_tests 仍列 unimplemented（未驗證）。
+ */
+function checkGherkinEvidence(contract: ComponentContract, evidence?: GherkinEvidence[]): string | null {
+  if (!evidence || evidence.length === 0) return null;
+  const evidenceScenarios = new Set(evidence.map(e => e.scenario));
+  for (const test of contract.gherkin_tests) {
+    if (!evidenceScenarios.has(test.scenario)) {
+      return `gherkin_evidence 缺少 scenario「${test.scenario}」的本地測試結果`;
+    }
+  }
+  for (const e of evidence) {
+    if (!e.passed) {
+      return `gherkin_evidence scenario「${e.scenario}」本地未通過（passed=false）`;
+    }
+  }
+  return null;
+}
+
+export function runSandboxAcceptance(
+  wasmBytes: Uint8Array,
+  contract: ComponentContract,
+  gherkinEvidence?: GherkinEvidence[],
+): SandboxResult {
+  // 1. 靜態步驟（假零件 / 體積 / 純WASI；不執行 wasm）
+  for (const step of STEPS) {
+    const error = step.run(wasmBytes, contract);
+    if (error !== null) {
+      return fail(step.name, error, step.guideAnchor, contract);
+    }
+  }
+
+  // 2. Gherkin evidence 一致性（投稿者本地已跑；registry 不重跑）
+  const evidenceError = checkGherkinEvidence(contract, gherkinEvidence);
+  if (evidenceError !== null) {
+    return fail('gherkin_tests', evidenceError, '#local-testing', contract);
+  }
+
+  return {
+    success: true,
+    unimplemented_steps: UNIMPLEMENTED_STEPS,  // gherkin(本地跑,registry未重跑) / cold_start / runtime_compat
+    component_hash_id: '',  // 由 submitComponent 在驗收通過後填入
+    canonical_id: contract.canonical_id,
+    version: contract.version,
+  };
+}

registry/src/actions/submitComponent.ts

@@ -0,0 +1,153 @@
+// 零件提交：沙盒驗收 → 派發 hash id → 寫入 SUBMISSIONS_KV
+// Requirements: 2.1, 2.2, 2.3
+// SDD: matrix/arcrun/.agents/specs/component-registry-canon/design.md Phase 1.5
+//
+// 2026-05-07：移除 R2 寫入。cypher-executor 已不從 R2 動態載 wasm（每個零件 = 獨立 Worker）。
+// R2 是 dead storage，移除避免誤導 AI 以為零件部署需要 wasm bytes。
+//
+// KV key 設計：
+//   comp:{hash_id}:{version}  → 零件元數據 JSON
+//   idx:{canonical_id}        → hash_id 反查索引（canonical_id → hash_id）
+//
+// hash_id 派發規則：
+//   hash_id = 'cmp_' + sha256(canonical_id).slice(0, 8)
+//   相同 canonical_id 永遠得到相同 hash_id（冪等）
+
+import { runSandboxAcceptance } from './sandboxAcceptance';
+import type { GherkinEvidence } from './sandboxAcceptance';
+import type { ComponentContract, SandboxResult, Bindings } from '../types';
+
+// ── G0 人類閘門（component-gatekeeping SDD R4）─────────────────────────────────
+//
+// 建零件不是 AI 能自己決定的事。submit 預設拒絕，除非帶人類確認 + 舉證。
+// 把關點在「建立零件的 API」本身（此處）→ CLI/MCP/Python/JS 四路全收斂到這關。
+// 誠實限制：AI 技術上能偽造 confirmed_by_human:true。靠 reason 留記錄（軌跡可審）+
+// mindset 明示「絕不代替人類確認建零件」+ 純 WASI 沙箱框死能力，讓偽造成明確越界。
+
+export interface HumanConfirmation {
+  confirmed_by_human: true;          // 必須為 literal true
+  reason_why_not_workflow: string;   // 非空：AI 舉證「為何工作流做不到」
+  confirmed_at: string;              // ISO timestamp
+}
+
+export interface SubmitOptions {
+  /** backfill 既有零件用：跳過人類閘門 + 沙盒（這些是已驗、已部署的存量） */
+  skip_acceptance?: boolean;
+  /** 人類確認 + 舉證（新投稿必填，除非 skip_acceptance） */
+  human_confirmation?: HumanConfirmation;
+  /** 投稿者本地跑 Gherkin 的結果（CLI 上傳，registry 存證可審） */
+  gherkin_evidence?: GherkinEvidence[];
+}
+
+function gateError(contract: ComponentContract, reason: string): SandboxResult {
+  return {
+    success: false,
+    failed_step: 'fake_component_scan',  // 復用最前步驟欄位語意：未過閘門
+    reason,
+    guide_anchor: '#human-gate',
+    component_hash_id: '',
+    canonical_id: contract.canonical_id,
+    version: contract.version,
+  };
+}
+
+// ── hash id 生成 ─────────────────────────────────────────────────────────────
+
+async function deriveHashId(canonicalId: string): Promise<string> {
+  const encoder = new TextEncoder();
+  const data = encoder.encode(canonicalId);
+  const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  const hex = hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
+  return 'cmp_' + hex.slice(0, 8);
+}
+
+// ── 主流程 ────────────────────────────────────────────────────────────────────
+
+export async function submitComponent(
+  wasmBytes: Uint8Array,
+  contract: ComponentContract,
+  env: Bindings,
+  options: SubmitOptions = {},
+): Promise<SandboxResult> {
+  const { skip_acceptance, human_confirmation, gherkin_evidence } = options;
+
+  // 0. G0 人類閘門（新投稿必經；backfill 既有存量 skip）
+  if (!skip_acceptance) {
+    if (
+      !human_confirmation ||
+      human_confirmation.confirmed_by_human !== true ||
+      !human_confirmation.reason_why_not_workflow ||
+      human_confirmation.reason_why_not_workflow.trim() === ''
+    ) {
+      return gateError(
+        contract,
+        '建零件需人類確認。請用 `acr component create`（會互動式問你），' +
+          '並說明「為何這件事無法用工作流達成」。預設假設工作流 / recipe 能做——先試工作流。',
+      );
+    }
+  }
+
+  // 1. 沙盒驗收（靜態把關 + gherkin_evidence 一致性；backfill 仍可選擇性跳過 wasm 驗收）
+  if (!skip_acceptance) {
+    const sandboxResult = runSandboxAcceptance(wasmBytes, contract, gherkin_evidence);
+    if (!sandboxResult.success) {
+      return sandboxResult;
+    }
+  }
+
+  // 2. 派發 hash id
+  const hashId = await deriveHashId(contract.canonical_id);
+  const kvKey = `comp:${hashId}:${contract.version}`;
+
+  // 3. 冪等
+  const existing = await env.SUBMISSIONS_KV.get(kvKey);
+  if (existing) {
+    return {
+      success: true,
+      component_hash_id: hashId,
+      canonical_id: contract.canonical_id,
+      version: contract.version,
+    };
+  }
+
+  // 4. 寫入 metadata
+  const record = {
+    component_hash_id: hashId,
+    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: contract.runtime_compat,
+    component_type: contract.component_type ?? 'wasm',
+    constraints: contract.constraints,
+    input_schema: contract.input_schema,
+    output_schema: contract.output_schema,
+    gherkin_tests: contract.gherkin_tests,
+    description: contract.description ?? '',
+    aliases: contract.aliases ?? [],
+    tags: contract.tags ?? [],
+    success_rate: 1,
+    avg_duration_ms: 0,
+    call_count: 0,
+    visibility: 'public' as const,
+    status: 'active' as const,
+    submitted_at: new Date().toISOString(),
+    deprecated_at: null,
+    // G0 軌跡可審：人類為何建此零件（舉證）+ 投稿者本地 Gherkin 結果證據
+    human_confirmation: human_confirmation ?? null,
+    gherkin_evidence: gherkin_evidence ?? null,
+  };
+
+  await env.SUBMISSIONS_KV.put(kvKey, JSON.stringify(record));
+  await env.SUBMISSIONS_KV.put(`idx:${contract.canonical_id}`, hashId);
+
+  return {
+    success: true,
+    component_hash_id: hashId,
+    canonical_id: contract.canonical_id,
+    version: contract.version,
+  };
+}

registry/src/actions/validateContract.ts

@@ -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 };
+}

registry/src/actions/wasmImports.ts

@@ -0,0 +1,128 @@
+// G3 純 WASI 把關（component-gatekeeping SDD，R3）
+//
+// 解析 WASM import section，取出所有 import 的 module name。
+// 把關：只准 wasi_snapshot_preview1 + u6u（host functions）。
+// 其他 module → runtime 鎖定風險，退稿（DECISIONS §4：避免 runtime 鎖定債）。
+//
+// WASM binary 結構（preview1）：
+//   magic(4) + version(4) + 一串 section
+//   section: id(1 byte) + size(LEB128) + payload
+//   import section id = 2。payload: count(LEB128) + 每個 import：
+//     module: len(LEB128) + bytes(UTF-8)
+//     name:   len(LEB128) + bytes(UTF-8)
+//     kind(1) + 之後依 kind 不同（func: typeidx LEB128 / table / mem / global）
+
+const ALLOWED_IMPORT_MODULES = new Set([
+  'wasi_snapshot_preview1',
+  'u6u',
+]);
+
+/** 讀 unsigned LEB128，回 [value, nextOffset] */
+function readULEB(buf: Uint8Array, offset: number): [number, number] {
+  let result = 0;
+  let shift = 0;
+  let pos = offset;
+  for (;;) {
+    const byte = buf[pos++];
+    result |= (byte & 0x7f) << shift;
+    if ((byte & 0x80) === 0) break;
+    shift += 7;
+  }
+  return [result, pos];
+}
+
+/**
+ * 解析 wasm import section，回傳所有 import module name 的集合。
+ * 解析失敗（非合法 wasm）回 null。
+ */
+export function parseWasmImportModules(wasmBytes: Uint8Array): Set<string> | null {
+  // magic + version
+  if (wasmBytes.length < 8) return null;
+  if (wasmBytes[0] !== 0x00 || wasmBytes[1] !== 0x61 || wasmBytes[2] !== 0x73 || wasmBytes[3] !== 0x6d) {
+    return null; // 不是 \0asm
+  }
+
+  const decoder = new TextDecoder('utf-8');
+  const modules = new Set<string>();
+  let offset = 8;
+
+  try {
+    while (offset < wasmBytes.length) {
+      const sectionId = wasmBytes[offset++];
+      const [sectionSize, afterSize] = readULEB(wasmBytes, offset);
+      offset = afterSize;
+      const sectionEnd = offset + sectionSize;
+
+      if (sectionId === 2) {
+        // import section
+        let p = offset;
+        const [count, afterCount] = readULEB(wasmBytes, p);
+        p = afterCount;
+        for (let i = 0; i < count; i++) {
+          const [modLen, afterModLen] = readULEB(wasmBytes, p);
+          p = afterModLen;
+          const moduleName = decoder.decode(wasmBytes.subarray(p, p + modLen));
+          p += modLen;
+          modules.add(moduleName);
+
+          const [nameLen, afterNameLen] = readULEB(wasmBytes, p);
+          p = afterNameLen;
+          p += nameLen; // skip import name
+
+          const kind = wasmBytes[p++];
+          // 依 kind skip descriptor
+          if (kind === 0x00) {
+            // func: typeidx (ULEB)
+            const [, afterType] = readULEB(wasmBytes, p);
+            p = afterType;
+          } else if (kind === 0x01) {
+            // table: reftype(1) + limits
+            p += 1;
+            const [flags, afterFlags] = readULEB(wasmBytes, p);
+            p = afterFlags;
+            const [, afterMin] = readULEB(wasmBytes, p);
+            p = afterMin;
+            if (flags === 0x01) { const [, afterMax] = readULEB(wasmBytes, p); p = afterMax; }
+          } else if (kind === 0x02) {
+            // mem: limits
+            const [flags, afterFlags] = readULEB(wasmBytes, p);
+            p = afterFlags;
+            const [, afterMin] = readULEB(wasmBytes, p);
+            p = afterMin;
+            if (flags === 0x01) { const [, afterMax] = readULEB(wasmBytes, p); p = afterMax; }
+          } else if (kind === 0x03) {
+            // global: valtype(1) + mut(1)
+            p += 2;
+          } else {
+            // 未知 kind，無法安全 skip → 中止解析
+            return modules.size > 0 ? modules : null;
+          }
+        }
+      }
+
+      offset = sectionEnd;
+    }
+  } catch {
+    // 解析越界等 → 回已收集的（或 null）
+    return modules.size > 0 ? modules : null;
+  }
+
+  return modules;
+}
+
+/**
+ * G3 把關：確認 wasm 只 import 白名單 module。
+ * 回 null = 通過；回字串 = 退稿原因。
+ */
+export function checkPureWasi(wasmBytes: Uint8Array): string | null {
+  const modules = parseWasmImportModules(wasmBytes);
+  if (modules === null) {
+    return 'WASM import section 無法解析（非合法 WASI preview1 wasm？）';
+  }
+  for (const mod of modules) {
+    if (!ALLOWED_IMPORT_MODULES.has(mod)) {
+      return `偵測到非白名單 import module：「${mod}」。零件只准依賴 wasi_snapshot_preview1 + u6u host functions（避免 runtime 鎖定，見 DECISIONS §4）`;
+    }
+  }
+  return null;
+}