# CAX Design Specification (ChatGPT Analysis)

**Generated by**: ChatGPT  
**Date**: 2025-09-21  
**Context**: 30分集中設計セッション  

## 🎯 Core Vision

**Nyash C-ABI Explorer (CAX)** - GUIでC ABI境界を「ぽいっと付け外し」「視覚化」「録って再生」「スクリプトで自動化」

## 🏗️ Architecture Design

### Core + GUI 分離アーキテクチャ
```
Core (Rust/Nyash): 既存cabi-debuggerフック + IPCサーバ
  ↕ JSON-RPC/WebSocket
GUI (Tauri/Electron): Svelte/React/TypeScript フロントエンド
```

### データフロー
```
PluginHost.Invoke → CABIDebugger → IPC → GUI Timeline
C ABI Calls → Real-time Logs → JSON Stream → 可視化
```

## 🎨 UX Design

### 画面レイアウト (5パネル構成)
```
┌─────────────┬─────────────────┬─────────────┐
│   Explorer  │   Live Timeline │   Inspector │
│ (attach/detach) │ (call flow)   │ (call details)│
├─────────────┴─────────────────┴─────────────┤
│          Record/Replay Controls            │
├─────────────────────────────────────────────┤
│        Console & Macros (Scripts)         │
└─────────────────────────────────────────────┘
```

### 操作体験
1. **1クリック Attach**: `map.so` の行をクリック→即時ログ流れる
2. **色分け表示**: 緑=Ok、黄=by-name、赤=Err/timeout、紫=ownership警告
3. **録画/再生**: ワンボタンでJSONL/TLV保存→プラグイン無しで再現
4. **ホットスワップ**: `disable→quiesce→reload` をGUIウィザードで

## 🔧 Technical Features

### 1. Real-time Monitoring
- **Live Timeline**: Swimlane（プラグイン別/スレッド別）
- **Call Inspector**: 引数/戻り値/実行時間/ソース位置
- **Filter System**: `outcome:warn plugin:map` 形式

### 2. Record/Replay System
```json
// ログ1行例
{
  "ts": 1737153845.123456,
  "plugin": "map.so", 
  "type_id": 17,
  "method": "get/1",
  "args": [{"str":"key"}],
  "ret": {"str":"value"},
  "outcome": "Ok",
  "elapsed_us": 87,
  "by_name": false,
  "site": {"file":"apps/x.nyash","line":42}
}
```

### 3. Hot-Swap Management
```
安全手順: disable → wait(0 inflight) → fini → dlclose → dlopen → init → re-enable
GUI支援: 進捗表示 + state snapshot/restore（任意）
```

### 4. Macro Automation
```nyash
// CAX API例
cax.filter({outcome:'warn'})
cax.attach("map.so") 
cax.replay("trace.tlv")
cax.hotswap("map.so", "/tmp/map_new.so")
```

## 📋 Implementation Roadmap

### Week 1 (MVP Core)
- ✅ IPCサーバ（subscribe/attach/detach）
- ✅ Explorer + Timeline（基本表示）
- ✅ Inspector（引数/戻り値表示）
- ✅ 記録（JSONL形式）

### Week 2 (Advanced Features)  
- ✅ Signature Checker（extern宣言 vs 実装差分）
- ✅ Record/Replay（ファイル形式）
- ✅ 簡易マクロ（フィルタ・基本操作）
- ✅ Hot-swap wizard（dry-run）

## 🎨 GUI Implementation

### Technology Stack
- **Frontend**: Tauri + Svelte/React + TypeScript
- **IPC**: JSON-RPC over WebSocket
- **Styling**: TailwindCSS + 可視化ライブラリ

### Key Components
```typescript
// IPC API例
interface CaxApi {
  subscribe(params: {plugins: string[], level: string}): void
  attach(params: {plugin: string}): void
  hotswap(params: {plugin: string, path: string}): void
  record: {
    start(params: {file: string}): void
    stop(): void
  }
  replay(params: {file: string, mode: string}): void
}
```

## 🚧 Risk Mitigation

### Performance
- **オーバーヘッド**: 既定軽量（log sampling、構造化は遅延ダンプ）
- **再入防止**: スレッドローカルで抑止

### Safety  
- **クラッシュ隔離**: detach≠dlclose（最初は"ロード専用"）
- **権限管理**: プロセス境界越えはエージェント方式

## 💡 Competitive Advantages

### vs 既存デバッガ
- **境界特化**: C↔Nyash境界に最適化された可視化
- **型安全**: TypeBox境界での実時間検証
- **構造化**: ライフサイクル・所有権の一元観測

### Innovation Points
- **Record/Replay**: ABIコール完全再現（回帰テスト革命）
- **GUI Integration**: コマンドライン→GUI操作の体験革新
- **Hot-Swap**: 無停止デバッグ・プラグイン更新

---

**Note**: この設計は、C ABI動的呼び出しからの1分発想を30分で具体化したもの。実装の現実性と革新性を両立した世界初級ツールの仕様です。