Arcrun/.agents/specs/u6u-platform-evolution/design.md

Design Document: u6u Platform Evolution

Overview

u6u 平台演進的核心目標是將現有的「HTTP endpoint 零件 + 單一 Cloudflare 部署」架構，演進為「WASM 零件模型 + 三層物理部署 + 雙面翻轉畫布」的完整平台。

設計的最高原則是 Dogfooding：每一層都是下一層的第一個用戶。底層先建立最小可運行的能力，再用自己的方式往上蓋。這確保每個設計決策都被真實使用場景驗證，而非紙上談兵。

Bootstrap 順序（不可跳過）

Phase 0：最小 WASM 執行核心
  → Component Dispatcher 能在 CF Workers 執行一個 .wasm（stdin/stdout JSON）
  → validate_json.wasm 作為第一個真實零件（TinyGo，< 50KB，驗證整個 pipeline）
  → Component Registry API（/guide、/validate-contract、/components）

Phase 1：遷移現有零件
  → 將 u6u-builtins 的 20 個 HTTP endpoint 逐一遷移為 .wasm
  → 遷移期間 Component Dispatcher 雙模式並存（HTTP fallback）
  → 每個零件附帶 component.contract.yaml

Phase 2：Cypher 語意擴展 + Multi-Tier Dispatcher
  → 支援 IS_A、ON_SUCCESS、ON_FAIL、CALLS_SUBFLOW、ON_CLICK
  → Component Dispatcher 路由層（Tier 1 CF / Tier 2 workerd / Tier 3 Wazero）

Phase 3：前端畫布（用自己的 Web Components 開發）
  → 先建立 Web Components 零件庫（u6u-btn、u6u-card 等）
  → 畫布本身用這些 Web Components 組裝
  → 雙面翻轉介面

關鍵設計約束

• KBDB 不變量：永遠只有三張表（blocks / templates / slots），不新增表
• API-First 鐵律：所有跨服務通訊只透過 HTTP API，禁止相對路徑引用
• 零件 I/O 不變量：唯一合法的 I/O 模型是 stdin_stdout_json
• Tier 3 約束：無 V8、無 Node.js、無網路，所有零件必須在 Wazero 上跑

---

Architecture

系統全景圖

graph TB
    subgraph "Tier 1 — Cloudflare Workers（雲端）"
        CE[Cypher Executor<br/>GraphExecutor]
        CD[Component Dispatcher<br/>路由層]
        CR[Component Registry<br/>KBDB HTTP API]
        KBDB[(KBDB<br/>blocks/templates/slots<br/>+ Vectorize)]
        R2[(R2<br/>.wasm 二進位)]
        CE --> CD
        CD --> CR
        CR --> KBDB
        CR --> R2
    end

    subgraph "Tier 2 — workerd self-hosted（企業地端）"
        T2D[Tier 2 Dispatcher<br/>同 wasi-shim，不同部署]
        T2R[本地 Registry 快取]
        T2D --> T2R
    end

    subgraph "Tier 3 — 邊緣載具"
        T3E[Go 排程引擎]
        Wazero[Wazero Runtime]
        SQLite[(SQLite<br/>本地 KBDB)]
        DTN[DTN 佇列]
        T3E --> Wazero
        T3E --> SQLite
        T3E --> DTN
    end

    subgraph "前端"
        Canvas[雙面翻轉畫布<br/>React 19 + Web Components]
        WC[Web Components 零件庫<br/>u6u-btn / u6u-card / ...]
        Canvas --> WC
    end

    CD -->|WASM 執行| Tier1WASM[.wasm 執行]
    CD -->|Cypher binding| ExtSvc[外部服務<br/>MCP / n8n / 任意 URL]
    CD -->|HTTP| T2D
    T2D -->|Wazero IPC| Wazero
    DTN -->|Burst 傳輸| T2D
    Canvas -->|u6u:trigger event| CE

Cypher Binding 的正確定義

Cypher binding 是 u6u 的核心執行機制，指「用 Cypher 三元組語法把零件串接成工作流，串接關係儲存在 KBDB，不寫死在程式碼裡」。

這個概念相對於 Cloudflare Workers 原生的 Service Binding（需要 deploy、串接關係寫死在 wrangler.toml）。

cypher-executor 就是執行 Cypher binding 的引擎。

零件本身只有兩種 component_type：

component_type	說明	需要 deploy？
wasm	所有後端零件（內建或用戶自建），本地 WASM 執行	否
service_binding	多個零件預組合成單一高頻零件的效能最佳化（如 OAuth + GSheets 常用組合）	是

重要：cypher_binding 不是 component_type。 它是整個執行引擎的名字，描述「零件如何被串接」，而不是「零件如何被執行」。所有零件（不管是內建還是用戶自建、不管是打外部 API 還是純邏輯）都是 .wasm，透過 Cypher 三元組串接。

所有後端零件都是 .wasm。 需要呼叫外部 HTTP API 的零件（如 google-sheets、http-request），透過 WASI shim 注入的 host function 發出網路請求，不在 .wasm 內部直接呼叫網路 syscall。

Component Dispatcher 路由決策樹

flowchart TD
    A[Cypher Executor 呼叫零件 id] --> B{查 Component Registry<br/>取得合約}
    B --> C{component_type?}
    C -->|wasm| E{當前 Tier?}
    C -->|service_binding| SB{有 CF Service Binding?}
    SB -->|是| SBExec[CF Service Binding 執行<br/>需 deploy，效能最佳]
    SB -->|否| SBErr[回傳錯誤：binding 未宣告]
    E -->|Tier 1 / Tier 2| I[workerd WASM<br/>WebAssembly.instantiate<br/>+ WASI shim（兩者相同）]
    E -->|Tier 3| L[Wazero IPC<br/>stdin/stdout，完全離線]
    I --> RC{runtime_compat<br/>包含 cf-workers?}
    RC -->|否| J[回傳 RUNTIME_INCOMPATIBLE 錯誤]
    RC -->|是| Exec[執行 .wasm]

KBDB 資料模型（tpl-component）

erDiagram
    TEMPLATES {
        string template_id "tpl-component"
        string name
        string description
    }
    BLOCKS {
        string block_id "comp-{id}-{version}"
        string template_id
        string user_id
        string page_name
    }
    SLOTS {
        string slot_id
        string block_id
        string key
        string value
    }
    TEMPLATES ||--o{ BLOCKS : "defines"
    BLOCKS ||--o{ SLOTS : "has"

---

Components and Interfaces

1. Component Registry（u6u-core/registry/）

Component Registry 是 KBDB 的薄包裝層，透過 HTTP API 管理零件合約。

零件命名機制

零件有兩個名稱，職責完全不同：

欄位	由誰決定	用途	範例
display_name	建立者自由取	顯示用，不影響任何邏輯	宇宙無敵 GSheets 超級寫入器
canonical_id	Registry AI 正規化後確認	搜尋、版本控制、Cypher 引用的唯一鍵	gsheets_create_table

canonical_id 正規化流程：

提交者輸入 display_name
    ↓
Registry 用 Workers AI 建議 canonical_id
（格式：{service}_{verb}_{object}，全小寫底線）
    ↓
同時搜尋 Vectorize，若相似度 > 0.9 的 canonical_id 已存在
→ 提示「可能與 gsheets_create_table 重複，是否作為新版本提交？」
    ↓
提交者確認或修改 canonical_id
    ↓
上架，canonical_id 永久不變

零件分類機制

採用「強制 category + 自由 tags」雙層分類：

• category：強制填，有限集合，定義前後端邊界

  • logic：後端邏輯零件（.wasm，純計算/轉換）
  • api：後端 API 零件（.wasm + cypher_binding，呼叫外部服務）
  • ui：前端 UI 元件（Web Component，瀏覽器執行）
  • style：前端樣式零件（CSS tokens）
  • anim：前端動畫零件

• tags：自由增加，跨零件共享語意

  • 例：gsheets_create_table 有 ["google", "sheets", "spreadsheet", "storage", "write"]
  • 例：excel_write_row 有 ["microsoft", "excel", "spreadsheet", "storage", "write"]
  • 搜尋「外部存儲」時，兩個都能透過 Vectorize 語意搜尋找到

HTTP 端點：

GET  /components/guide                → 機器可讀開發指引（Markdown）
POST /components/validate-contract    → 驗證 component.contract.yaml 格式
POST /components                      → 提交零件（.wasm + contract）觸發沙盒驗收
GET  /components/:id                  → 取得零件合約（最優版本）
GET  /components/:id/versions         → 取得所有版本清單（含評分）
GET  /components/search?q=...         → 語意搜尋零件

KBDB 整合：

• 每個零件版本 = 一個 Block，block_id = comp-{id}-{version}
• Template = tpl-component（預先建立，不新增表）
• .wasm 二進位存 R2，KBDB slot 只存 wasm_r2_key
• description + tags 欄位寫入 Vectorize 索引，支援語意搜尋

Slot 欄位對應（tpl-component）：

Slot key	說明	範例值
canonical_id	正規化功能名稱（永久不變，搜尋/版本控制用）	gsheets_create_table
display_name	建立者自取的顯示名稱	宇宙無敵 GSheets 超級寫入器
category	零件分類（有限集合）	logic / api / ui / style / anim
version	實作版本	v1
wasi_target	WASM 目標	preview1
stability	穩定性標籤	floating
runtime_compat	相容 runtime（JSON 陣列）	["cf-workers","wazero"]
component_type	零件類型	wasm / service_binding
max_size_kb	體積上限	2048
max_cold_start_ms	冷啟動上限	50
no_network_syscall	禁止網路 syscall	true
input_schema	JSON Schema（JSON 字串）	{"type":"object",...}
output_schema	JSON Schema（JSON 字串）	{"type":"object",...}
gherkin_tests	測試案例（JSON 字串）	[{"scenario":"..."}]
wasm_r2_key	R2 物件鍵（wasm 模式）	components/validate_json/v1.wasm
service_binding_key	CF binding key（service_binding 模式）	CLINIC_GSHEETS
description	自然語言描述（寫入 Vectorize）	在 Google Sheets 建立新工作表
tags	自由標籤（JSON 陣列，跨零件共享語意）	["google","sheets","storage","write"]
success_rate	成功率（0-1）	0.98
avg_duration_ms	平均執行時間	12
call_count	被調用次數	1024
status	狀態	active / deprecated / tombstone
deprecated_at	棄用時間戳記	1700000000000

2. Component Dispatcher（cypher-executor/src/lib/component-loader.ts 擴展）

Component Dispatcher 是 createComponentLoader 的升級版，新增 WASM 執行路徑。

介面定義：

// 零件類型（只有兩種）
type ComponentType =
  | 'wasm'            // 所有後端零件，透過 Cypher binding 串接，本地 WASM 執行
  | 'service_binding'; // 效能最佳化：CF Service Binding，需 deploy，用於高頻預組合零件

// 新版 ComponentDescriptor
type ComponentDescriptor = {
  component_type: ComponentType;
  // WASM 模式
  wasm_r2_key?: string;
  runtime_compat?: string[];
  max_cold_start_ms?: number;
  // Service Binding 模式（CF Worker 間高效呼叫，需 deploy）
  binding?: string;      // wrangler.toml 中宣告的 binding key
  path?: string;
};

Tier 1 WASM 執行（CF Workers 原生）：

Cloudflare Workers 原生支援 WebAssembly.instantiate，但 WASI preview1 需要手動實作 WASI imports。設計採用輕量 WASI shim 方案：

// WASI preview1 shim（只實作 stdin/stdout/stderr，其餘 syscall 回傳 ENOSYS）
function createWasiImports(stdin: Uint8Array): {
  imports: WebAssembly.Imports;
  getStdout: () => Uint8Array;
} {
  const stdoutChunks: Uint8Array[] = [];
  let stdinOffset = 0;

  return {
    imports: {
      wasi_snapshot_preview1: {
        fd_write: (fd: number, iovs: number, iovs_len: number, nwritten: number) => { /* ... */ },
        fd_read: (fd: number, iovs: number, iovs_len: number, nread: number) => { /* ... */ },
        proc_exit: (code: number) => { throw new Error(`wasm exit: ${code}`); },
        // 其餘 syscall 回傳 ENOSYS（76）
        fd_seek: () => 76,
        fd_close: () => 0,
        environ_get: () => 0,
        environ_sizes_get: () => 0,
        args_get: () => 0,
        args_sizes_get: () => 0,
        clock_time_get: () => 0,
        random_get: (buf: number, buf_len: number) => { /* crypto.getRandomValues */ return 0; },
      },
    },
    getStdout: () => { /* 合併 stdoutChunks */ },
  };
}

設計決策：不使用 @cloudflare/workers-wasi（已停止維護）。改用自製輕量 WASI shim，只實作 fd_read/fd_write/proc_exit/random_get，其餘 syscall 回傳 ENOSYS。這足以支援 TinyGo/Rust/AssemblyScript 的 stdin/stdout 零件，且不引入外部依賴。

執行流程：

1. 從 R2 取得 .wasm 二進位（ArrayBuffer）
2. WebAssembly.compile(buffer) → WebAssembly.Module
3. 建立 WASI imports shim（注入 stdin = JSON.stringify(input)）
4. WebAssembly.instantiate(module, imports)
5. 呼叫 _start() 或 main()
6. 從 stdout buffer 讀取輸出
7. JSON.parse(stdout) → output

R2 快取策略：

• 第一次呼叫：從 R2 fetch .wasm，WebAssembly.compile 後快取 WebAssembly.Module（Worker 記憶體，跨請求共享）
• 後續呼叫：直接用快取的 Module，只重新 instantiate（避免重複編譯）

3. Cypher Triplet Parser 擴展（cypher-executor/src/actions/triplet-parser.ts）

現有 parser 只支援 PIPE / IF / FOREACH / CONTINUE。需擴展支援新語意關係。

新增 EdgeType：

export type EdgeType =
  | 'PIPE' | 'IF' | 'FOREACH' | 'CONTINUE'  // 現有
  | 'IS_A' | 'ON_SUCCESS' | 'ON_FAIL'        // 新增：執行語意
  | 'ON_CLICK' | 'CALLS_SUBFLOW'             // 新增：觸發語意
  | 'CONTAINS' | 'HAS_STYLE' | 'HAS_BEHAVIOR'; // 新增：結構語意

URI 協議解析：

// 節點 componentId 解析
function resolveComponentId(uri: string): {
  type: 'component' | 'workflow' | 'ui' | 'style';
  canonicalId: string;
  stability: 'floating' | 'stable' | 'pinned';
  pinnedVersion?: string;
} {
  // component://validate_json@stable → { type: 'component', canonicalId: 'validate_json', stability: 'stable' }
  // component://validate_json@pinned:v1 → { type: 'component', canonicalId: 'validate_json', stability: 'pinned', pinnedVersion: 'v1' }
  // workflow://wf_save_to_db → { type: 'workflow', canonicalId: 'wf_save_to_db', stability: 'floating' }
  // ui://u6u-btn → { type: 'ui', canonicalId: 'u6u-btn', stability: 'floating' }
}

ON_SUCCESS / ON_FAIL 執行語意：

GraphExecutor 需要區分「節點執行成功」vs「節點執行失敗」，而非依賴 context 欄位：

// 在 executeNode 中，捕捉 try/catch 後分別走 ON_SUCCESS / ON_FAIL 邊
case 'ON_SUCCESS':
  // 只在上游節點成功時執行
  if (!nodeError) {
    result = await this.executeNode(nextNode, ...);
  }
  break;
case 'ON_FAIL':
  // 只在上游節點失敗時執行（接收 error context）
  if (nodeError) {
    result = await this.executeNode(nextNode, graph, { ...context, error: nodeError }, ...);
  }
  break;

CALLS_SUBFLOW 執行語意：

case 'CALLS_SUBFLOW': {
  // 從 KBDB 載入子 Workflow 定義
  const subWorkflowId = nextNode.componentId!.replace('workflow://', '');
  const subGraph = await loadWorkflowFromKBDB(subWorkflowId, env);
  const subExecutor = new GraphExecutor(loader);
  const subResult = await subExecutor.execute(subGraph, result as Record<string, unknown>, kvNamespace);
  result = { ...(result as Record<string, unknown>), ...subResult.data as Record<string, unknown> };
  break;
}

4. Web Components 零件庫（u6u-core/web-components/）

Web Components 以原生 Custom Elements API 實作，不依賴任何框架。

<u6u-btn> 介面：

// HTML attributes
interface U6uBtnAttributes {
  label: string;       // 顯示文字
  color?: string;      // 主題色（CSS custom property）
  tooltip?: string;    // 滑鼠懸停提示（純靜態）
  workflow?: string;   // workflow://id
  disabled?: boolean;
}

// 發出的自訂事件
interface U6uTriggerEvent extends CustomEvent {
  detail: {
    workflowId: string;
    payload: Record<string, unknown>;
  };
}

<u6u-card> Smart Container 邏輯：

// u6u-card 攔截子元件的 u6u:trigger 事件
// 收集同容器內所有 u6u-text-input / u6u-text-field 的值
// 合併至 payload 後再向上冒泡
connectedCallback() {
  this.addEventListener('u6u:trigger', (e: Event) => {
    const trigger = e as CustomEvent;
    e.stopPropagation();
    
    const inputs = this.querySelectorAll('u6u-text-input, u6u-text-field');
    const collected: Record<string, unknown> = {};
    inputs.forEach(input => {
      const name = input.getAttribute('name');
      const value = (input as any).value;
      if (name) collected[name] = value;
    });
    
    this.dispatchEvent(new CustomEvent('u6u:trigger', {
      bubbles: true,
      composed: true,
      detail: {
        ...trigger.detail,
        payload: { ...trigger.detail.payload, ...collected },
      },
    }));
  });
}

5. 雙面翻轉畫布（inkstone-admin/frontend/web/）

畫布本身用 React 19 + Web Components 組裝，體現 dogfooding 原則。

翻轉狀態機：

stateDiagram-v2
    [*] --> UIView: 初始狀態
    UIView --> LogicView: 點擊翻面按鈕
    LogicView --> UIView: 點擊翻面按鈕
    LogicView --> Editing: 修改三元組
    Editing --> Saving: 確認儲存
    Saving --> LogicView: KBDB 寫入成功
    Saving --> LogicView: KBDB 寫入失敗（顯示錯誤）

---

Data Models

Component Contract YAML（完整規格）

canonical_id: "validate_json"       # 正規化功能名稱（永久不變，Registry AI 正規化後確認）
display_name: "JSON 格式驗證器"      # 建立者自取，顯示用
category: "logic"                    # logic | api | ui | style | anim
version: "v1"                        # 實作版本
wasi_target: "preview1"              # WASM 目標格式
stability: "floating"                # floating | stable | pinned

runtime_compat:
  - "cf-workers"
  - "workerd"
  - "wazero"

constraints:
  max_size_kb: 2048
  max_cold_start_ms: 50
  no_network_syscall: true
  no_filesystem_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
      description: "驗證失敗時的錯誤訊息"

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 格式"

零件開發語言決策

內建零件使用 TinyGo（純邏輯零件）和 TinyGo + json.RawMessage（需要任意 HTTP body 的零件）。不引入 Rust 作為內建零件語言。

用戶自建零件支援三種語言，按難度分層：

語言	目標用戶	JSON 能力	備註
AssemblyScript	一般用戶（TS 背景）	社群套件 assemblyscript-json，支援動態 JSON	語法最接近 TS，門檻最低；靜默錯誤風險，沙盒驗收必須通過
TinyGo	技術較強用戶（Go 背景）	靜態 struct 完整支援；json.RawMessage 處理任意 body	編譯期報錯，AI 生成安全性較高
Rust	進階用戶	serde_json::Value 完整動態 JSON	生態最成熟，體積最小；學習曲線陡

/components/guide 端點提供三份語言範例，用戶根據自身背景選擇。

內建零件 JSON 策略（TinyGo）：

// 固定 schema 零件（google-sheets、gmail 等）→ 靜態 struct
type Input struct {
    SpreadsheetId string `json:"spreadsheet_id"`
    Range         string `json:"range"`
    AccessToken   string `json:"access_token"`
}

// 任意 body 零件（http-request）→ json.RawMessage 傳遞 raw bytes，不解析
type Input struct {
    URL    string          `json:"url"`
    Method string          `json:"method"`
    Body   json.RawMessage `json:"body"` // 任意 JSON，不解析
}

Workflow Cypher 三元組（完整語法）

kind: Workflow
id: wf_submit_form

triplets:
  # 節點類型宣告
  - "btn_submit >> IS_A >> ui://u6u-btn"
  - "step_validate >> IS_A >> component://validate_json"
  - "step_save >> IS_A >> component://kbdb_write"

  # 前端觸發後端
  - "btn_submit >> ON_CLICK >> step_validate"

  # 成功/失敗分支
  - "step_validate >> ON_SUCCESS >> step_save"
  - "step_validate >> ON_FAIL >> step_notify_error"

  # 子流程呼叫
  - "step_save >> ON_SUCCESS >> CALLS_SUBFLOW >> workflow://wf_notify_user"

  # 容器結構
  - "card_main >> CONTAINS >> btn_submit"
  - "card_main >> CONTAINS >> input_name"

Evaluation Block（KBDB tpl-evaluation）

每次 Workflow 執行後，Evaluator Agent 寫入一個 Evaluation Block：

Slot key	說明
run_id	執行唯一 ID
workflow_id	Workflow ID
component_id	被評價的零件 ID
verdict	success / failed / timeout
duration_ms	執行時間
error_message	失敗訊息（可選）
evaluated_at	評價時間戳記

Pitfall Block（KBDB tpl-pitfall）

Slot key	說明
component_id	問題零件 ID
failure_pattern	失敗模式描述
first_seen_at	首次發現時間戳記
occurrence_count	發生次數

---

Correctness Properties

A property is a characteristic or behavior that should hold true across all valid executions of a system — essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.

Property Reflection（去重分析）

在寫出最終屬性前，先做冗餘分析：

• 1.1 + 1.2：都是合約欄位完整性驗證，合併為 Property 1「合約格式完整性」
• 2.1 + 2.2：驗收流程執行 + 失敗回報，合併為 Property 2「沙盒驗收流程正確性」
• 2.3 + 2.4：提交後可讀取 + 冪等提交，合併為 Property 3「零件提交冪等性與持久性」
• 3.1 + 3.5：WASM 執行 + 雙模式路由，合併為 Property 4「Component Dispatcher 路由正確性」
• 3.4 + 6.4：不相容 Tier 回傳錯誤 + 結構化錯誤，合併為 Property 5「Dispatcher 錯誤結構完整性」
• 4.1：URI 解析 round-trip，獨立為 Property 6
• 4.2 + 4.4：版本選擇算法（floating 最高分 + pinned 固定版本），合併為 Property 7「版本選擇策略正確性」
• 4.5：版本保留不變量，獨立為 Property 8
• 5.7：Confluence 屬性，獨立為 Property 9
• 8.3 + 8.4 + 8.5：Web Components 事件與渲染，合併為 Property 10「Web Components 事件與渲染冪等性」
• 10.6 + 12.5：評價冪等性 + 查詢冪等性，合併為 Property 11「系統操作冪等性」

最終保留 11 個屬性，每個提供獨立驗證價值。

---

Property 1: 合約格式完整性

For any component contract object，若缺少任何必填欄位（id、version、wasi_target、stability、runtime_compat、constraints.max_size_kb、constraints.max_cold_start_ms、constraints.no_network_syscall、constraints.io_model、input_schema、output_schema、gherkin_tests），合約驗證器 SHALL 拒絕該合約並回傳包含缺失欄位名稱的錯誤；反之，包含所有必填欄位的合約 SHALL 通過格式驗證。

Validates: Requirements 1.1, 1.2, 1.4

---

Property 2: 沙盒驗收流程正確性

For any 提交的零件（.wasm + contract），若零件在驗收步驟 N 失敗，Component_Registry 的回應 SHALL 包含步驟 N 的名稱與具體失敗原因，且不執行步驟 N+1 之後的步驟。

Validates: Requirements 2.1, 2.2

---

Property 3: 零件提交冪等性與持久性

For any 通過驗收的零件（id, version），提交後從 Component_Registry 讀取該零件的合約，所有欄位值 SHALL 與提交時的合約完全一致（序列化 round-trip）；對相同 (id, version) 重複提交 N 次，KBDB 中 SHALL 只存在一個對應的 Block。

Validates: Requirements 2.3, 2.4

---

Property 4: Component Dispatcher 路由正確性

For any 零件合約，若 io_model = "stdin_stdout_json"，Component_Dispatcher SHALL 使用 WASM 執行路徑，將 input JSON 寫入 stdin，從 stdout 讀取 output JSON；若 io_model = "http_endpoint"，SHALL 使用 HTTP 路徑。對任意合法 JSON input，WASM 執行路徑的輸出 SHALL 與 HTTP 執行路徑的輸出語意等效。

Validates: Requirements 3.1, 3.5, 3.6

---

Property 5: Dispatcher 錯誤結構完整性

For any (component_id, tier) 組合，若該零件的 runtime_compat 不包含當前 tier，Component_Dispatcher 的錯誤回應 SHALL 同時包含：零件 id、當前 tier 名稱、已嘗試的呼叫路徑清單，三個欄位缺一不可。

Validates: Requirements 3.4, 6.4

---

Property 6: 零件 URI 解析 Round-Trip

For any 合法的零件 URI 字串（格式為 component://id、component://id@stable、component://id@pinned:vN），解析後再重新序列化 SHALL 產生與原始 URI 語意等效的字串；解析出的 id、stability、pinnedVersion 欄位 SHALL 與原始 URI 中的對應部分完全一致。

Validates: Requirements 4.1

---

Property 7: 版本選擇策略正確性

For any 零件 id 下的版本集合（每個版本有 success_rate、avg_duration_ms、call_count 評分），當 stability = floating 時，Component_Dispatcher SHALL 選取「成功率 × 速度評分 × 被調用次數」最高的版本；當 stability = pinned:vN 時，無論版本集合中其他版本的評分如何，SHALL 永遠選取版本 vN。

Validates: Requirements 4.2, 4.4

---

Property 8: 歷史版本永久保留不變量

For any 已上架的零件版本（id, version），無論該版本後來被標記為 deprecated 或 tombstone，其 .wasm 二進位 SHALL 永遠可從 R2 讀取，且 pinned 引用 SHALL 永遠能透過 Component_Dispatcher 執行該版本。

Validates: Requirements 4.5, 10.5

---

Property 9: Cypher 三元組解析 Confluence（順序無關性）

For any 合法的 Cypher 三元組集合，無論三元組在輸入陣列中的排列順序如何，parseTriplets 產生的執行圖（節點集合、邊集合、拓撲結構）SHALL 語意等效——即相同的節點 id 集合、相同的 (from, to, type) 邊集合。

Validates: Requirements 5.7

---

Property 10: Web Components 事件與渲染冪等性

For any workflow URI 設定於 <u6u-btn> 的 workflow attribute，使用者點擊後發出的 u6u:trigger 事件 detail 中的 workflowId SHALL 與 URI 中的 id 完全一致；For any 一組具名 <u6u-text-input> 元件置於 <u6u-card> 內，觸發事件後收集到的 payload SHALL 包含所有輸入元件的 name-value 對；For any attribute 值，對同一 Web Component 設定相同 attribute 值 N 次，渲染結果 SHALL 與設定一次相同（冪等渲染）。

Validates: Requirements 8.3, 8.4, 8.5

---

Property 11: 系統操作冪等性

For any Workflow 執行日誌（run_id），Evaluator_Agent 對相同 run_id 處理 N 次，KBDB 中 SHALL 只存在一個對應的 Evaluation Block，不產生重複記錄；For any Component_Registry 讀取操作的查詢參數，在 KBDB 資料不變的前提下，對相同參數呼叫 N 次 SHALL 回傳完全相同的結果。

Validates: Requirements 10.6, 12.5

---

Error Handling

Component Dispatcher 錯誤分類

錯誤類型	觸發條件	回應格式
COMPONENT_NOT_FOUND	KBDB 中找不到零件	{ error: "COMPONENT_NOT_FOUND", component_id, tier }
RUNTIME_INCOMPATIBLE	runtime_compat 不含當前 Tier	{ error: "RUNTIME_INCOMPATIBLE", component_id, tier, attempted_paths: [] }
WASM_EXECUTION_TIMEOUT	超過 max_cold_start_ms	{ error: "WASM_EXECUTION_TIMEOUT", component_id, timeout_ms }
WASM_INVALID_OUTPUT	stdout 不是合法 JSON	{ error: "WASM_INVALID_OUTPUT", component_id, raw_output }
WASM_SYSCALL_VIOLATION	.wasm 嘗試網路/檔案 syscall	{ error: "WASM_SYSCALL_VIOLATION", component_id, syscall_name }
CONTRACT_VALIDATION_FAILED	合約格式不合規	{ error: "CONTRACT_VALIDATION_FAILED", missing_fields: [] }

沙盒驗收失敗回應格式

{
  "success": false,
  "failed_step": "syscall_scan",
  "reason": "發現禁止的 syscall：sock_connect",
  "guide_anchor": "#syscall-constraints",
  "component_id": "my_component",
  "version": "v1"
}

Tier 3 離線錯誤處理

Tier 3 在離線環境中，所有無法執行的操作都寫入 DTN 佇列，不拋出錯誤：

// Go 排程引擎的錯誤處理策略
type DTNEntry struct {
    Type      string          // "missing_component" | "sync_log" | "request_wasm"
    Payload   json.RawMessage
    CreatedAt time.Time
    RetryCount int
}

Web Components 錯誤邊界

<u6u-btn> 在 workflow attribute 未設定時，點擊不發出事件，僅在 console 輸出警告：

[u6u-btn] workflow attribute is not set, click event ignored

---

Testing Strategy

雙軌測試策略

本功能採用「單元測試 + 屬性測試」雙軌策略：

• 單元測試（Vitest）：驗證具體範例、邊界條件、錯誤情境
• 屬性測試（fast-check）：驗證上述 11 個 Correctness Properties，每個屬性最少執行 100 次迭代

屬性測試配置

使用 fast-check（已在 tech stack 中），每個屬性測試標記格式：

// Feature: u6u-platform-evolution, Property N: {property_text}
it.prop([fc.record({ id: fc.string(), version: fc.string(), ... })])(
  'Property 1: 合約格式完整性',
  (contract) => {
    // ...
  },
  { numRuns: 100 }
);

各 Phase 測試重點

Phase 0（WASM 執行核心）：

• Property 4：WASM 執行路徑 round-trip（validate_json.wasm 作為 ground truth）
• Property 1：合約格式驗證
• 單元測試：WASI shim 的 fd_read/fd_write 正確性

Phase 1（零件遷移）：

• Property 3：提交冪等性（20 個零件各提交兩次，驗證無重複）
• Property 2：沙盒驗收流程（各步驟失敗案例）
• Property 8：歷史版本保留（deprecate 後仍可讀取）

Phase 2（Cypher 擴展）：

• Property 9：Confluence（三元組順序無關性，fast-check shuffle）
• Property 6：URI 解析 round-trip
• Property 7：版本選擇策略（floating 最高分、pinned 固定版本）
• Property 5：錯誤結構完整性

Phase 3（前端畫布）：

• Property 10：Web Components 事件與渲染冪等性（@testing-library/react + fast-check）
• Property 11：評價冪等性（Evaluator Agent 重複處理）

整合測試

以下場景使用整合測試（1-3 個具體範例，不用 PBT）：

• Tier 1 CF Workers 環境中實際執行 validate_json.wasm（驗證 WASM 在 Workers 環境可運行）
• KBDB tpl-component Template 建立與 Slot 讀寫（驗證 KBDB 整合）
• R2 .wasm 上傳與讀取（驗證 R2 整合）
• Vectorize 語意搜尋（驗證「查詢 Google Sheets 資料」能找到 gsheets_get_entries）

單元測試重點（非 PBT）

• WASI shim：fd_read 正確讀取 stdin、fd_write 正確寫入 stdout
• evaluateCondition：現有條件評估函數的邊界案例
• resolveComponentId：URI 解析的邊界案例（空字串、特殊字元）
• <u6u-card> Smart Container：巢狀容器的事件冒泡行為