hakorune/apps/README.md

# Nyash Applications Showcase

このディレクトリには、Nyashの実力を示す実用的なアプリケーションが含まれています。

開発・貢献に関する全体ガイドはリポジトリルートの`AGENTS.md`（Repository Guidelines）を参照してください。プロジェクト構成、ビルド/テスト、PR要件の要点を簡潔にまとめています。

## 🚀 実装済みアプリケーション

### 🎮 ゲーム・エミュレータ

#### CHIP-8エミュレータ
**場所**: `chip8_nyash/chip8_emulator.hako`  
**特徴**: 完全なゲーム機エミュレータ、グラフィック表示対応
```bash
./target/release/hakorune apps/chip8_nyash/chip8_emulator.hako
```

### 📝 エディタ・開発ツール

#### Enhanced Kilo Editor
**場所**: `kilo_nyash/enhanced_kilo_editor.hako`  
**特徴**: テキストエディタ（kilo改良版）、実用的なファイル編集機能
```bash
./target/release/hakorune apps/kilo_nyash/enhanced_kilo_editor.hako
```

### 🌐 ネットワークアプリ

#### TinyProxy
**場所**: `tinyproxy_nyash/proxy_server.hako`  
**特徴**: HTTPプロキシサーバー、Netプラグイン活用
```bash
./target/release/hakorune apps/tinyproxy_nyash/proxy_server.hako
```

### 🛠️ ユーティリティ・ベンチマーク

#### ny-echo - 最小CLI実装
**場所**: `ny-echo/main.hako`
標準入力を読み取り、オプションに応じて変換して出力する基本的なCLIツール。

```bash
# 基本使用
echo "Hello World" | nyash apps/ny-echo/main.hako

# 大文字変換
echo "hello" | nyash apps/ny-echo/main.hako --upper

# 小文字変換
echo "HELLO" | nyash apps/ny-echo/main.hako --lower
```

**特徴**:
- ConsoleBoxによるI/O処理
- StringBoxの変換メソッド活用
- VM/AOTで同一動作（JIT実行は現在封印）

### 2. ny-array-bench - 性能ベンチマーク
ArrayBoxの各種操作をベンチマークし、VM/JIT/AOTの性能比較を行うツール。

```bash
# ベンチマーク実行
nyash apps/ny-array-bench/main.hako

# 出力例（JSON形式）
{
  "create_1000": 1.23,
  "map_1000": 2.45,
  "reduce_1000": 0.98,
  "relative_performance": {"vm": 1.0, "aot": 5.0}
}
```

**特徴**:
- カスタムStatsBoxによる計測
- JSON形式でCI連携可能
- 性能改善の定量的測定

### 3. ny-jsonlint（開発中）
PyRuntimeBoxを使用してPythonのjsonモジュールでJSON検証を行うツール。

### 4. ny-filegrep（開発中）
ファイルシステムを検索し、パターンマッチングを行う実用的なツール。

### 5. ny-http-hello（開発中）
HTTPサーバーを実装し、Web対応を実証するデモアプリケーション。

## 🔧 ビルドと実行

### 実行方法
```bash
# インタープリター実行
nyash apps/APP_NAME/main.hako

# VM実行（高速）
nyash --backend vm apps/APP_NAME/main.hako

# JIT実行（封印中）
# 現在は無効です。Interpreter/VM か AOT(EXE) を使用してください。
```

### テスト実行
各アプリケーションにはtest.shが含まれています：

```bash
cd apps/ny-echo
./test.sh
```

## 🎯 予定アプリケーション（論文・ベンチマーク用）

### 📊 CLBG標準ベンチマーク
AI先生たちの推奨により、論文説得力向上のため以下を実装予定：

#### 1. binary-trees - メモリ・GC性能測定
**目的**: GC性能、メモリ割り当て速度測定
**期待性能**: Interpreter(1x) → VM(8x) → LLVM(20x)
```nyash
// 二分木大量生成・破棄でGC性能測定
box TreeNode {
    init { left, right, value }
    birth(depth, value) { ... }
}
```

#### 2. n-body - 数値計算の王道
**目的**: 浮動小数点演算、ループ最適化効果測定
**期待性能**: Interpreter(1x) → VM(10x) → LLVM(50x)
```nyash
// 太陽系シミュレーション、重力計算
// MathBoxを活用した数値計算ベンチマーク
```

#### 3. mandelbrot - 計算+画像出力
**目的**: 純粋計算性能、ファイル出力確認
**期待性能**: Interpreter(1x) → VM(15x) → LLVM(80x)
```nyash
// フラクタル計算、PPM/PNGファイル出力
// 視覚的にJIT/LLVM効果を確認可能
```

### 🌟 Nyash特色ベンチマーク

#### 4. JSON Stream Aggregator
**目的**: プラグイン統一性、「Everything is Box」実証
**特徴**: File/Netプラグインから同じコードで処理
```nyash
// FileBoxとNetBoxから同じAPIでJSONを読み取り
// 同一コードでローカルファイルとHTTP APIに対応
```

## 📊 性能指標（現在の実測値）

| アプリ | Interpreter | VM | LLVM(予定) | 用途 |
|--------|-------------|----|-----------| -----|
| ny-echo | 1.0x | 13.5x | 50x | I/O性能 |
| ny-array-bench | 1.0x | 13.5x | 40x | 計算性能 |
| chip8_emulator | 1.0x | 13.5x | 60x | ゲーム性能 |
| enhanced_kilo_editor | 1.0x | 13.5x | 45x | エディタ性能 |
| tinyproxy | 1.0x | 13.5x | 35x | ネットワーク性能 |

## 🎯 実装ロードマップ

### ✅ 完了済み
- [x] ny-echo（基本I/O検証）
- [x] ny-array-bench（性能基準）
- [x] chip8_emulator（ゲーム・グラフィック）
- [x] enhanced_kilo_editor（実用ツール）
- [x] tinyproxy（ネットワーク）

### 🚧 実装予定（論文・ベンチマーク用）
- [ ] binary-trees（GC性能測定）
- [ ] n-body（数値計算）
- [ ] mandelbrot（視覚的ベンチマーク）
- [ ] JSON Stream Aggregator（プラグイン統一）

### 🔮 将来候補
- [ ] レイトレーサー（CPU集約的）
- [ ] Lispインタープリター（言語実装）
- [ ] 静的サイトジェネレータ（実用性）

## 🚀 Nyashメモリ管理の真価を示す革新的アプリケーション

### AI先生たちの提案（2025-08-31）

Gemini先生とChatGPT5先生から、Nyashの決定論的メモリ管理（スコープベース解放、finiシステム、weak自動nil化）がもたらす新しいプログラミングパラダイムについて革新的な提案を受けました。

### 🌟 最優先実装候補

#### 1. **分散ホットスワップ・パイプライン**
**概要**: NyaMesh上でセンサ→前処理→推論→配信の各段をプラグイン化し、無停止で更新可能なMLパイプライン

**Nyashならではの特徴**:
- 🔄 **無停止プラグイン更新**: finiシステムにより論理的に終了しても物理的に参照可能
- 🧹 **決定的メモリ管理**: スコープ解放と逆順カスケードで予測可能な解放
- ⚡ **性能維持**: p99レイテンシ悪化<5%、スループット維持

**他言語では困難な理由**:
- Rust/C++: 手動メモリ管理で複雑、ホットスワップ時にUAFリスク
- Python/Ruby: GILにより真の並行性が得られない

#### 2. **BoxTorrent - 内容アドレス化P2P配布基盤**
**概要**: 大容量データや中間生成物を「Box=DAGノード」として配布し、変換プラグインで処理

**Nyashならではの特徴**:
- 📦 **ゼロコピー共有**: Arc<Mutex>で安全にBoxを共有
- 🔍 **内容ハッシュ重複排除**: 同一内容のBoxを自動的に再利用
- 🗑️ **自然なキャッシュ管理**: 参照カウントで不要データを自動削除

#### 3. **Live Shared Heap - メッシュ越し共有ヒープ**
**概要**: 論理的に単一のShared HeapにBoxを配置し、P2Pネットワーク上で共有

**Nyashならではの特徴**:
- 🌐 **分散ロックの単純化**: 全Boxがスレッドセーフ前提
- 🔌 **プラグイン透過性**: ヒープ上の同一Boxをそのまま扱える
- 🔧 **ノード障害耐性**: 参照カウントで自然復旧

### 📊 実装による測定可能な優位性

| 指標 | 期待される優位性 |
|------|-----------------|
| **安全性** | UAF/データ競合/クラッシュ発生率 0% |
| **可用性** | ホットスワップ中断時間 0秒 |
| **効率性** | ゼロコピー率 90%以上 |
| **拡張性** | ピア数に対して線形スケール |
| **回復性** | ノード喪失下での自動復旧 |

### 🎯 実装ロードマップ（Nyash特化）

#### Phase 1: ミニマムPoC（1週間）
- [ ] **BoxTorrentミニ版**: 内容アドレスBox + 参照カウント連携
- [ ] **測定基盤**: 参照グラフ可視化、メモリリーク監視

#### Phase 2: 分散デモ（2週間）
- [ ] **2段パイプライン**: センサ→処理のホットスワップ実証
- [ ] **性能計測**: p99レイテンシ、スループット監視

#### Phase 3: 論文向け完全版（3週間）
- [ ] **完全なMLパイプライン**: 4段以上の処理段
- [ ] **大規模ベンチマーク**: 100ノード規模での性能実証

### 💡 Nyashだからこそ可能な革新

**「他言語では危険だがNyashなら安全」な例**:
1. **ゼロコピー共有バッファの多段パイプ**: 大容量Box<ByteBuf>を複数プラグインが並列処理
2. **共有メモリマップファイルの安全クローズ**: 最後の参照が落ちた瞬間のみクローズ
3. **マルチプロデューサ・マルチコンシューマなリングバッファ**: 言語レベルでunsafe不要

これらの実装により、Nyashの「Everything is Box」哲学とArc<Mutex>統一アーキテクチャが、単なる理論ではなく実用的な価値を持つことを証明します。

### 🔮 将来候補
- [ ] レイトレーサー（CPU集約的）
- [ ] Lispインタープリター（言語実装）
- [ ] 静的サイトジェネレータ（実用性）

## 🤝 貢献方法

新しいアプリケーションのアイデアや改善提案は大歓迎です！

1. 新しいアプリディレクトリを作成
2. main.hakoとtest.shを実装
3. このREADMEに追加
4. PRを送信

すべてのアプリケーションは「Everything is Box」哲学に従い、プラグインシステムを活用することを推奨します。