Pasta ソウルドキュメント

# Pasta ソウルドキュメント

_Memories of pasta twine together—now and then a knot, yet always a delight._

このドキュメントは、pastaプロジェクトの「憲法」です。すべての設計判断、実装方針、開発活動の根拠となる「あるべき姿」を定義します。

### ドキュメントヒエラルキー

pastaプロジェクトのドキュメントは、以下の優先順位と役割を持ちます：

#### Level 0: Entry Point
- **[README.md](README.md)** - プロジェクト概要（導入・アーキテクチャ）

#### Level 1: Constitution
- **[SOUL.md](SOUL.md)** - プロジェクトの憲法（Why: ビジョン、コアバリュー、あるべき姿）
- **[GRAMMAR.md](GRAMMAR.md)** - 利用者向けクイックリファレンス（例文豊富な学習用資料）
- **[AGENTS.md](AGENTS.md)** - AI開発支援（Kiro workflow、ステアリング）

#### Level 2: Implementation Layer
実装層ドキュメント。技術的詳細と品質管理を担当。

**クレートREADME**:
- [pasta_dsl/README.md](crates/pasta_dsl/README.md) - DSLパーサーAPI
- [pasta_core/README.md](crates/pasta_core/README.md) - レジストリAPI
- [pasta_lua/README.md](crates/pasta_lua/README.md) - Luaトランスパイラ・ランタイム
- [pasta-lua-coding skill](.agents/skills/pasta-lua-coding/SKILL.md) - Lua APIリファレンス（references/に詳細）
- [pasta_lsp/README.md](crates/pasta_lsp/README.md) - Language Server Protocol実装
- [pasta_shiori/README.md](crates/pasta_shiori/README.md) - SHIORI DLLインターフェース
- [pasta_sample_ghost/README.md](crates/pasta_sample_ghost/README.md) - サンプルゴースト

**品質管理ドキュメント**:
- [TEST_COVERAGE.md](TEST_COVERAGE.md) - テストカバレッジマップ
- [OPTIMIZATION.md](OPTIMIZATION.md) - トランスパイラ最適化リファレンス
- [SCENE_TABLE_REVIEW.md](SCENE_TABLE_REVIEW.md) - シーンテーブル設計レビュー

#### Level 3: Steering (AI向け)
- [.kiro/steering/](/.kiro/steering/) - AI向けプロジェクトルール（完全性優先）
- [doc/spec/](doc/spec/) - 言語仕様書（章別分割、AI向け必要な章のみ参照）

**ルール**: 仕様の衝突時は doc/spec/ を優先し、GRAMMAR.md・README.md を修正する

---

## 1. ビジョン

### プロジェクトの存在意義

**pasta**は、「伺か」のようなデスクトップマスコットや、シナリオ型ゲームを実現するための対話スクリプトエンジンです。

### コア概念：「パスタのように絡み合う会話」

会話の記録というのは、長い長い一本の糸です。この糸は時に絡み合い、時に結び目を作りながら、パスタのように複雑に織りなされていきます。

この絡み合いこそが、会話の**意外性**と**面白さ**を生み出します。前方一致によるランダムジャンプを主軸にすることで、スクリプト作者が意図した範囲内での自然な会話の揺らぎを実現します。

### ミッション

1. **ゴースト会話の記述基盤**: デスクトップマスコットの掛け合い会話を直感的に記述できるスクリプト言語を提供する
2. **シナリオエンジンとしての汎用性**: ゲームエンジンとしても流用可能なデータ構造とランタイムを提供する
3. **エコシステムとの統合**: SHIORI.DLLインターフェースによる従来資産の活用と、arekaへの統合による次世代基盤の確立

---

## 2. コアバリュー

pastaの設計を貫く4つの柱：

### 2.1 日本語フレンドリー

**原則**: 日本語話者が直感的に使えること

- **全角キーワード対応**: `＊`、`・`、`＠`、`＄`、`＞`など、全角文字で記述可能
- **タイプ量削減**: 全角文字なら1文字で済むマーカーを採用
- **読みやすさ**: 日本語の文章の中に自然に溶け込む文法設計

**例**:
```pasta
＊会話
  ぱすた：おはよう！
  ラザニア：ごきげんよう、今日も良い天気ですわね
```

### 2.2 UNICODE識別子

**原則**: グローバルな多言語対応

- **日本語シーン名**: `＊挨拶`、`＊自己紹介`など
- **日本語変数名**: `＄カウンター`、`＄ユーザー名`など
- **Unicode Identifier仕様**: XID_START / XID_CONTINUE準拠
- **文化的柔軟性**: 各言語圏のユーザーが母語で記述可能

### 2.3 yield型エンジン

**原則**: 継続可能な出力ストリーム

- **Generator/yieldパターン**: イベント出力を逐次yield
- **チェイントーク対応**: 連続した会話の中断・再開が可能
- **UI独立性**: 出力ペース制御をエンジン外（areka層）に委譲

**設計意図**: スクリプトエンジンは純粋なロジック層として動作し、UI表現とのカップリングを排除

### 2.4 宣言的フロー

**原則**: if/while/forのない、シンプルな制御構造

- **Call/Jump制御**: シーンへのジャンプ・呼び出しで会話を制御
- **属性フィルタリング**: 条件判定は属性マッチングで表現
- **複雑ロジック**: 必要ならLuaブロックで実装

**設計意図**: スクリプト作者が会話フローに集中できる、読みやすく保守しやすい文法

---

## 3. 設計原則

### 3.1 行指向文法

**原則**: 行頭の数文字で行属性が確定する

- 行の種類は冒頭インデント＋キーワードで判定
- 改行が行の区切り（明確な終端）
- 例外はLuaコードブロックのみ（複数行）

**利点**:
- パーサー実装がシンプル
- スクリプト作者が直感的に理解可能
- エラーメッセージが行単位で明確

### 3.2 前方一致によるランダム選択

**原則**: 意外性と再生可能性の両立

#### シーン検索
- `＞挨拶` → 「挨拶」で始まるすべてのシーンが候補
- 候補からランダムに1つを選択
- 同名シーンの重複定義が意図的にサポートされる

#### 単語選択
- `＠greeting` → 登録された単語値リストからランダム抽出
- 前方一致により、関連語彙を柔軟にグルーピング可能

**設計意図**:
- 会話に自然な揺らぎを持たせる
- スクリプト作者が意図した範囲内での変化を実現
- 繰り返し実行時の単調さを回避

### 3.3 UI独立性の原則

**原則**: Wait/Syncはマーカーのみ、制御はUI層が実装

- スクリプトエンジンは `Wait`, `Sync` などのイベントを**マーカーとして出力するのみ**
- 実際の待機処理、同期処理はareka層（UI層）が実装
- エンジンは純粋なロジック層として独立

**利点**:
- エンジンのテスタビリティ向上
- UI実装の自由度確保
- プラットフォーム非依存性

---

## 4. 辞書アーキテクチャ

pastaの核となるデータ構造は「シーン辞書」と「単語辞書」です。

### 4.1 シーン辞書（Label Table）

シーンは会話の単位であり、前方一致検索とランダム選択の対象です。

#### グローバルシーン

**定義**: `＊シーン名`

- ファイル全体からアクセス可能
- 前方一致検索の基本単位
- 同名シーンの重複定義が可能（ランダム選択）

**用途**:
- 会話のエントリーポイント
- 独立したイベントハンドラ
- 再利用可能な会話パターン

**例**:
```pasta
＊挨拶
  ぱすた：おはよう！

＊挨拶
  ぱすた：こんにちは！

＊挨拶_朝
  ぱすた：おはようございます！
```

→ `＞挨拶` は3つすべてが候補となりランダム選択

#### ローカルシーン

**定義**: `・シーン名`（親シーン内でインデント）

- 親グローバルシーン内でのみアクセス可能
- スコープが限定された、サブルーチン的な扱い
- 名前空間の汚染を防ぐ

**用途**:
- 選択肢の実装
- 親シーン固有のサブフロー
- 一時的な会話分岐

**例**:
```pasta
＊メニュー
  ぱすた：何をする？
  ＞選択肢
  
  ・選択肢1
    ぱすた：選択肢1が選ばれました
  
  ・選択肢2
    ぱすた：選択肢2が選ばれました
```

### 4.2 単語辞書（Word Dictionary）

単語は文字列のリストであり、ランダム選択により会話に揺らぎを与えます。

#### グローバル単語

**定義**: `＠単語名：値1、値2、値3`（ファイルレベル、インデントなし）

- ファイル全体からアクセス可能
- プロジェクト共通の語彙として機能

**用途**:
- 共通の挨拶表現
- 汎用的な相槌
- 複数箇所で使い回す定型句

**例**:
```pasta
＠挨拶：おはよう、こんにちは、こんばんは
＠相槌：うん、そうだね、なるほど
```

#### シーン単語

**定義**: `＠単語名：値1、値2`（グローバルシーン内、インデント）

- 親グローバルシーン内でのみアクセス可能
- シーン固有の語彙として機能

**用途**:
- そのシーンでのみ使う専門用語
- 文脈依存の表現バリエーション

**例**:
```pasta
＊料理の会話
  ＠食材：トマト、玉ねぎ、じゃがいも
  ぱすた：今日は＠食材　を使って料理するよ
```

#### アクター単語

**定義**: `＠単語名：値`（アクタースコープ内）

- 特定アクター固有の表現・表情として機能
- さくらスクリプトの`\s[表情ID]`などを格納

**用途**:
- アクター固有の表情定義
- キャラクター特有の口癖バリエーション

**例**:
```pasta
％ぱすた
  ＠通常：\s[0]
  ＠照れ：\s[1]
  ＠驚き：\s[2]

＊会話
  ぱすた：＠驚き　えっ、本当！？
```

---

## 5. シーン実行アーキテクチャ

pastaの核心は、静的な「辞書」（シーン辞書・単語辞書）だけでなく、それらが実行時にどのように動作するかにあります。本章では、シーン関数のLua実行モデルを**映画撮影**のメタファーで説明します。

### 5.1 映画撮影のメタファー

pastaは「台本DSL」として設計されており、実行モデルは映画撮影に喩えることができます。

| 要素           | メタファー   | Lua実体                                 | 役割                          |
| -------------- | ------------ | --------------------------------------- | ----------------------------- |
| **シーン**     | 台本（脚本） | `function SCENE.__シーン名__(act, ...)` | 会話の台本、Lua関数として定義 |
| **アクター**   | 役者         | `act.アクター`                          | 発話者、表情変更の主体        |
| **アクション** | 演技         | `talk()`, `word()`                      | 実際の発話・動作              |
| **act**        | カメラ       | `act` オブジェクト                      | 撮影装置、出力の受け皿        |

**映画撮影の流れ**:

1. **台本準備**: シーン（Lua関数）が定義される
2. **撮影開始**: 監督の「アクション！」でシーン関数が呼び出される
3. **演技**: アクター（役者）がact（カメラ）に向かって発話・動作する
4. **記録**: actオブジェクトがすべての出力を記録（撮影）する
5. **カット**: シーン関数が終了または次のシーンへ遷移

この4要素の関係性が、pastaの実行モデルの本質です。

### 5.2 シーン関数の構造

Pasta DSLで定義されたシーンは、トランスパイラによりLua関数に変換されます。

#### 関数シグネチャ

```lua
function SCENE.__シーン名__(act, ...)
    local args = { ... }
    local save, var = act:init_scene(SCENE)
    -- シーンの本体
end
```

**各要素の役割**:

- **`act`**: カメラオブジェクト。すべての出力の受け皿
- **`...`**: シーン呼び出し時に渡された引数
- **`save`**: グローバル変数（`＄＊変数名`）へのアクセス
- **`var`**: ローカル変数（`＄変数名`）へのアクセス

#### coroutine/yieldパターン

pastaはLuaのコルーチンとyieldを活用し、**継続可能な出力ストリーム**を実現します。

- シーン実行中、発話やイベントは逐次yieldされる
- UI層（areka）が出力ペースを制御
- チェイントーク（連続会話）の中断・再開が可能

これにより、スクリプトエンジンは純粋なロジック層として動作し、UI表現とのカップリングを排除しています。

### 5.3 アクター発話の実行モデル

アクターの発話は、actオブジェクト（カメラ）への「撮影」として記録されます。

#### 発話の記録

```lua
act.ぱすた:talk(act.ぱすた:word("通常"))
act.ぱすた:talk("こんにちは！")
```

**発話シーケンス**:

1. **アクター選択**: `act.ぱすた` でアクターオブジェクトを取得
2. **表情変更**: `word("通常")` で表情コード（`\s[0]`等）を解決
3. **テキスト出力**: `talk(...)` でactに発話を記録

#### 単語展開による動的テキスト

`＠単語名` の参照は、実行時に `act:word("単語名")` として解決されます。

**スコープ解決順序**:

1. **アクタースコープ**: 現在発話中のアクターの単語辞書
2. **シーンスコープ**: 現在実行中のシーンの単語辞書
3. **グローバルスコープ**: ファイルレベルの単語辞書

同名の単語が複数スコープに存在する場合、より狭いスコープが優先されます。

### 5.4 シーン呼び出しと制御フロー

シーン間の遷移は、Call文（`＞シーン名`）によって実現されます。

#### Callによるサブルーチン呼び出し

```lua
act:call(SCENE.__global_name__, "ローカルシーン", {})
```

- 指定シーンを呼び出し、**実行後に復帰**
- 実行スタックにコンテキストが積まれる
- 選択肢実装やサブフロー分岐に使用

#### 末尾呼び出し（Jump相当）

```lua
return act:call(SCENE.__global_name__, "次のシーン", {})
```

- `return` を付けることで**末尾呼び出し最適化**が適用
- スタックを消費せずにシーン遷移
- 長時間シナリオでのスタックオーバーフローを防止

**設計意図**: Luaの末尾呼び出し最適化（Tail Call Optimization）を活用し、if/while/forのない宣言的フローを維持しながら、無限に続くシナリオを安全に実行できます。

---

## 6. Phase 0: あるべき基盤（完了）

Phase 0（一次設計の再構築）は完了しました。以下は各要素の「あるべき姿」とその達成状況です。

### 5.1 DSL文法の理想形

**あるべき姿**: 曖昧性のない、一貫した文法仕様

- すべてのマーカーが明確に定義されている
- 全角/半角の対応が完全
- パーサーが一意に解釈可能な文法
- エラーメッセージが具体的で理解しやすい

**現状の課題**:
- 一部文法の曖昧性・不完全性
- エッジケースでの解釈の不一致

### 5.2 トランスパイル品質基準

**あるべき姿**: 期待されるLuaコードを確実に生成

- パスタスクリプトの意図が正確にLuaコードに変換される
- 最適化されたコード生成（不要な中間変数なし）
- デバッグ可能なコード（行番号対応、コメント保持）
- 統合テストでの完全一致検証（`comprehensive_control_flow.pasta`）

**現状の課題**:
- トランスパイル結果の品質問題
- 一部機能で期待される出力との乖離

### 5.3 シーンテーブル設計

**あるべき姿**: 前方一致検索を効率的に実現

- Radix Trie等の高効率データ構造
- O(log n)以下の検索時間
- メモリ効率の最適化

**現状の課題**:
- シーンテーブル設計の不備
- 検索アルゴリズムの最適化不足

### 5.4 宣言的制御フロー

**あるべき姿**: Callによる明快な制御

- Call: サブルーチン呼び出し、実行後復帰
- 末尾Call（旧Jump）: トランスパイラが自動判定し最適化
- 属性フィルタリングによる条件分岐
- ネストした制御フローの明確な実装

**現状の課題**:
- Call文の実装品質
- 戻り値の扱いの不整合

### 5.5 過去完了仕様31件からの知見

**教訓**:
1. **要件と実装の一致**: 仕様書と実装の乖離を継続的に検証
2. **テストファースト**: 新機能は必ずテストを先に書く
3. **段階的な進化**: 大規模な変更は小さなステップに分割
4. **回帰防止**: リグレッションテストの徹底

### 5.6 Phase 0完了基準（Definition of Done）

以下すべてを満たした時点でPhase 0完了とする：

#### 文法・パーサー
- [x] SPECIFICATION.md 全マーカー定義完了
- [x] 全角/半角対応表の完全性
- [x] `cargo test` pasta_core 100%パス（94テスト）
- [x] `cargo test` pasta_lua 100%パス（249テスト）
- [x] `cargo test` pasta_shiori 100%パス（28テスト）

#### トランスパイル品質
- [x] comprehensive_control_flow.pasta の期待出力検証（Lua版Golden Test）
  - 8つのスナップショットテスト実装済み
  - comprehensive_control_flow.pastaは旧文法のためスキップ（TODO: 更新予定）
- [x] スナップショットテスト整備（insta crate使用）
- [x] 最適化レベルの文書化（OPTIMIZATION.md）

#### ドキュメント整合性
- [x] SOUL.md ⇔ SPECIFICATION.md 一貫性検証（完全）
- [x] Gap Analysis完了
- [x] ドキュメントヒエラルキー明文化
- [x] TEST_COVERAGE.md 更新済み

#### テストカバレッジ
- [x] TEST_COVERAGE.md 作成（機能⇔テストマッピング）
- [x] 未テスト領域の特定と受容判断
- [x] Runtime E2E テスト整備（16テスト）

#### 設計品質
- [x] シーンテーブル設計レビュー完了（SCENE_TABLE_REVIEW.md）
- [x] Call文の実装（末尾Call自動判定含む）
- [x] リグレッションテスト整備（483テスト）

---

## 7. 開発哲学

### 7.1 テストファースト

**原則**: 実装よりもテストを先に書く

- 新機能は必ずテストケースから始める
- リグレッションテストで品質を保証
- `cargo test --workspace` が常にパスする状態を維持

### 7.2 段階的な進化

**原則**: 大きな変更は小さなステップで

- Phase単位での機能追加
- 各Phaseでの品質ゲート通過
- MVP禁止：中途半端な完成は認めない

### 7.3 仕様と実装の一致

**原則**: ドキュメントとコードは常に同期

- SPECIFICATION.mdが権威的ソース
- 実装変更時は必ず仕様書を更新
- Gap Analysisによる定期的な整合性検証

### 7.4 UI独立性の徹底

**原則**: エンジンは純粋なロジック層

- Wait/Syncはマーカー出力のみ
- UI制御はareka層に委譲
- ユニットテスト可能性を最優先

---

## 8. ターゲットユーザー

1. **デスクトップマスコット作者**: 伺か互換環境での会話スクリプト記述
2. **ゲーム開発者**: シナリオ型ゲームの対話エンジンとして活用
3. **LLM統合開発者**: MCP連携による動的対話システムの構築

---

## 9. ロードマップ

### 現在地: Phase 2（コア機能実装）

Phase 0, Phase 1は完了し、現在はPhase 2（コア機能実装）を進行中です。

### Phase 1: 基盤確立（完了）

- 安定したDSL文法
- 信頼性の高いトランスパイラ
- 効率的なシーン検索

### Phase 2: コア機能実装（進行中）

- シーン継続チェーン
- インライン多段解決
- Luaランタイム拡充

### Phase 3: 高度機能

- イベントハンドリング拡充
- 永続化機能
- デバッグツール

### Phase 4: エコシステム統合

- SHIORI.DLL完全対応
- areka統合
- MCP/LLM連携

---

**最終更新**: 2026-03-07
**ステータス**: Phase 2進行中 - コア機能実装フェーズ