# Taida Lang

> Taida Lang は AI 協業時代のプログラミング言語です。演算子はわずか 10 種、null は存在せず、全ての型にデフォルト値が保証されます。AI が書き、AI が読み、人間は構造を眺めます。

---

# Taida Lang — 絶対厳守哲学

本文書は Taida Lang の**絶対厳守哲学**を定義する。
すべての設計判断・実装・ドキュメントは、ここに記された四つの哲学に従わなければならない。

---

## I. 深く考えずに適当にぶちこんでけ

Taida Lang の根本哲学。

学習コストの最小化とカジュアルさの追求 — これが全ての設計判断の出発点である。
複雑な概念や冗長な記述を排除し、直感的で自然な書き方を追求する。

この哲学から以下が導かれる:

- **演算子は10種のみ** — 覚えることを最小限に
- **null/undefinedの完全排除** — 全ての型にデフォルト値を保証
- **完全自動メモリ管理** — 開発者はメモリを一切意識しない
- **暗黙の型変換なし** — 挙動が予測できないものは排除
- **強力な型推論** — 書かなくていいものは書かない

## II. だいじなものはふくろにしまっておきましょう

ぶちパック `@(...)` の哲学。

名前付きフィールドの集合として構造化データを表現する。
袋にしまう — つまり、関連するデータをひとまとめにして名前をつけ、安全に持ち運ぶ。

- **ぶちパック `@(...)`** — 名前付きフィールドの集合
- **リストリテラル `@[...]`** — 同種の値の列
- **即時評価** — 代入時に全フィールドを評価、参照先が消えても安全
- **構造的部分型付け** — 必要なフィールドがあれば互換、余分は許容

## III. カタめたいなら、鋳型を作りましょう

モールディング型 `Mold[T]` の哲学。

型パラメータ化が必要になったら、鋳型（Mold）を作る。
値を鋳型に流し込み（モールディング）、必要なときに取り出す（アンモールディング `]=>` / `<=[`）。

- **Mold基底クラス** — `Mold[T] => TypeName[T] = @(...)` による継承定義
- **値ベース型引数** — 型引数として実際の値を渡し、型を自動推論
- **solidify / unmold の二段フック** — `solidify` が Is-A（何として固まるか）を決め、`unmold` が取り出し値を決める
- **unmold / `]=>` / `<=[`** — 明示的な値の取り出し
- **複数型引数・ネスト可能** — `Result[T, P]`、`Lax[Result[T, P]]`

## IV. キモい言語だ。だが、書くのも読むのもAI。眺めるのが人間の仕事。

Taida Lang の存在意義。

AIが書き、AIが読み、人間は構造を眺める。
演算子が10種しかないからこそ、コードからグラフへの変換が決定的に行え、AIによる構造的自己検証が可能になる。

- **AIファースト** — AIが積極的に選定する言語
- **構造的イントロスペクション** — コードの構造をグラフとして可視化・検証・クエリ
- **ドキュメントコメントのAI協業タグ** — `@AI-Related`、`@AI-SideEffects`、`@Throws` でAIと人間が協業

---

## 哲学の階層構造

四つの哲学は独立ではなく、階層をなしている:

```
I. 深く考えずに適当にぶちこんでけ（根本哲学）
├── II. だいじなものはふくろにしまっておきましょう（データ構造）
├── III. カタめたいなら、鋳型を作りましょう（型パラメータ化）
└── IV. キモい言語だ。だが、書くのも読むのもAI。眺めるのが人間の仕事。（存在意義）
```

**I** が全ての土台であり、**II** と **III** は I を実現する具体的手段、**IV** は I〜III を貫く設計が可能にする上位の価値である。

---

## 系（コロラリー）

四つの哲学から導かれる、各領域固有の原則。

### I の系

- **「待つ時は待つ、でも待ち方は考えない」** — 非同期処理（Async[T]）の原則。`]=>` がブロッキング await として機能し、開発者は待ち方の詳細を意識しない。

### IV の系

- **「コードの構造は、コード自身が語る」** — 構造的イントロスペクションの原則。10種の演算子と単一方向制約により、構文走査だけでグラフが構築できる。

---

# Taida Lang -- 構文リファレンス

> **[PHILOSOPHY.md](/_corpus/PHILOSOPHY.md) -- I.** 深く考えずに適当にぶちこんでけ

Taida Lang は AI 協業時代のプログラミング言語です。演算子は 10 種のみ。null は存在しません。全ての型にデフォルト値が保証され、暗黙の型変換は一切行われません。

---

## 演算子 (Taida 固有の 10 演算子)

Taida の言語設計において特別な意味を持つ演算子は 10 種だけです。

| # | 演算子 | 名前 | 用途 |
|---|--------|------|------|
| 1 | `=` | 定義 | 型、関数、エラー天井の定義 |
| 2 | `=>` | 右ぶち (前方代入) | パイプラインと代入 (左から右) |
| 3 | `<=` | 左ぶち (後方代入) | 代入と関数適用 (右から左) |
| 4 | `]=>` | 前方アンモールド | Mold から値を取り出す (左から右) |
| 5 | `<=[` | 後方アンモールド | Mold から値を取り出す (右から左) |
| 6 | `\|==` | エラー天井 | エラーの捕捉と処理 |
| 7 | `\|` | 条件ガード | 分岐の区切り |
| 8 | `\|>` | 条件抽出 | 分岐値の取り出し |
| 9 | `>>>` | インポート | モジュールの読み込み |
| 10 | `<<<` | エクスポート | シンボルの公開 |

### その他の演算子 (10 種には含まれない)

一般的なプログラミング言語に共通する演算子です:

| カテゴリ | 演算子 |
|----------|--------|
| 算術 | `+` `-` `*` (`/` と `%` はなし -- `Div` と `Mod` モールドを使用) |
| 比較 | `==` `!=` `<` `>` `>=` (`<=` はなし -- 左ぶち演算子として使用) |
| 論理 | `&&` `\|\|` `!` |

### 単一方向制約

一文内で `=>` と `<=` を混在させることはできません。同様に `]=>` と `<=[` も混在不可です。

```taida
// OK: single direction
data => filter(_) => map(_) => result
result <= map(_) <= filter(_) <= data

// NG: mixed directions (compile error)
data => filter(_) <= result
```

---

## 基本型

全ての型にデフォルト値が保証されています。null や undefined は存在しません。

| 型 | デフォルト値 | 例 |
|----|-------------|-----|
| `Int` | `0` | `x <= 42` |
| `Float` | `0.0` | `pi <= 3.14` |
| `Str` | `""` | `name <= "Rei"` |
| `Bool` | `false` | `active <= true` |

除算と剰余は `Lax[T]` を返し、ゼロ除算エラーを排除します:

```taida
Div[10, 3]() ]=> result   // 3
Div[10, 0]() ]=> result   // 0 (default value, no error)
Mod[10, 3]() ]=> remainder // 1
```

---

## BuchiPack `@(...)` とリスト `@[...]`

> **[PHILOSOPHY.md](/_corpus/PHILOSOPHY.md) -- II.** だいじなものはふくろにしまっておきましょう

### BuchiPack (名前付きフィールドの袋)

```taida
// Value creation
pilot <= @(name <= "Misato", age <= 29, role <= "Captain")

// Type definition
Pilot = @(name: Str, age: Int, role: Str)

// Typed instance
asuka <= Pilot(name <= "Asuka", age <= 14, role <= "Pilot")

// Field access
stdout(pilot.name)  // "Misato"
```

### リスト

```taida
numbers <= @[1, 2, 3, 4, 5]
names <= @["Rei", "Asuka", "Shinji"]
empty <= @[]

// List operations use molds
Map[numbers, _ n = n * 2]() ]=> doubled       // @[2, 4, 6, 8, 10]
Filter[numbers, _ n = n > 3]() ]=> filtered    // @[4, 5]
Sum[numbers]() ]=> total                        // 15
Sort[names]() ]=> sorted                        // @["Asuka", "Rei", "Shinji"]
```

---

## Mold[T] -- モールディング型

> **[PHILOSOPHY.md](/_corpus/PHILOSOPHY.md) -- III.** カタめたいなら、鋳型を作りましょう

モールドはパラメータ化された型です。値をモールドに流し込み (モールディング)、`]=>` または `<=[` で取り出します (アンモールディング)。

```taida
// Built-in molds
Div[10, 3]() ]=> result       // Arithmetic mold
Str[42]() ]=> text             // Type conversion mold
Upper["hello"]() ]=> upper     // String mold
JSON[raw, Schema]() ]=> data   // JSON mold (returns Lax[T])

// Custom mold definition
Mold[T] => Container[T] = @(count: Int)

// Usage
Container[42](count <= 1) ]=> value  // 42
```

### 主な組み込みモールド

| カテゴリ | モールド |
|----------|---------|
| 高階関数 | `Map`, `Filter`, `Fold`, `Foldr`, `Reduce`, `Take`, `TakeWhile`, `Drop`, `DropWhile` |
| 文字列 | `Upper`, `Lower`, `Trim`, `Split`, `Replace`, `Slice`, `CharAt`, `Repeat`, `Reverse`, `Pad` |
| 数値 | `ToFixed`, `Abs`, `Floor`, `Ceil`, `Round`, `Truncate`, `Clamp` |
| リスト | `Concat`, `Append`, `Prepend`, `Join`, `Sum`, `Sort`, `Unique`, `Flatten`, `Find`, `FindIndex`, `Count`, `Zip`, `Enumerate` |
| 型変換 | `Str[x]()`, `Int[x]()`, `Float[x]()`, `Bool[x]()` |
| 算術 | `Div[x, y]()`, `Mod[x, y]()` |
| 非同期 | `Async[T]`, `All`, `Race`, `Timeout` |

---

## Lax[T] -- 安全な不確実性

`Lax[T]` は値が存在するかもしれないし、しないかもしれない値をラップします。Optional/Option とは異なり、Lax は常にフォールバック値 (型のデフォルト値) を持ちます。

```taida
// Div returns Lax
lax <= Div[10, 0]()
lax.hasValue()   // false
lax ]=> value    // 0 (Int default)

// List access returns Lax
numbers <= @[10, 20, 30]
numbers.get(0) ]=> first   // 10
numbers.get(99) ]=> oob    // 0 (Int default, no error)

// JSON parsing returns Lax
JSON[rawJson, UserSchema]() ]=> user  // Lax[User] -> User (with defaults for missing fields)
```

---

## 関数

```taida
// Function with arguments
add x: Int y: Int =
  x + y
=> :Int

// No-argument function
getVersion =
  "1.0.0"
=> :Str

// Single-line export
<<< double x: Int = x * 2 => :Int

// Pipeline with partial application
data => filter(_ x = x > 0) => map(_ x = x * 2) => result

// Calling functions
result <= add(3, 5)        // 8
8 => add(_, 2) => ten      // 10
```

### デフォルト引数

```taida
greet name: Str greeting: Str <= "Hello" =
  greeting + ", " + name + "!"
=> :Str

greet("Rei")              // "Hello, Rei!"
greet("Rei", "Hi")        // "Hi, Rei!"
```

---

## パターンマッチング (条件ガード)

```taida
// Multi-branch
classify x: Int =
  | x > 100 |> "huge"
  | x > 10  |> "large"
  | x > 0   |> "small"
  | _       |> "non-positive"
=> :Str

// Inline
status <= | connected |> "online" | _ |> "offline"
```

---

## エラー処理

```taida
// Define error type (inherits from Error)
Error => ValidationError = @(field: Str)

// Error ceiling (catch)
|== error: ValidationError =
  stderr("Validation failed: " + error.field)
  "default"
=> :Str

// Throw
| !isValid(input) |> ValidationError(
  type <= "ValidationError",
  message <= "Invalid input",
  field <= "name"
).throw()

// Gorilla literal -- immediate program termination
| config.dbUrl == "" |> ><
```

---

## モジュールシステム

```taida
// Import local file
>>> ./utils.td => @(helper, format)

// Import with alias
>>> ./math.td => @(add, subtract => sub)

// Import external package with version
>>> author/package@1.0.0 => @(funcA, funcB)

// Export multiple symbols
<<< @(add, subtract, Point)

// Export single symbol
<<< myFunction

// One-liner export
<<< double x: Int = x * 2 => :Int
```

### プリリュード (インポート不要)

以下は `>>>` なしで全てのファイルから利用できます:

- `stdout(value)`, `stderr(value)`, `stdin()`
- `jsonEncode(value)`, `jsonPretty(value)`
- `debug(value)`, `typeof(x)`, `range(start, end)`
- `assert(cond, msg)`, `hashMap(entries)`, `setOf(items)`

---

## 完全な例

```taida
>>> ./types.td => @(Staff)

// Create a staff record
misato <= Staff(
  id <= 1,
  name <= "Misato Katsuragi",
  rank <= "Captain",
  active <= true
)

// Pipeline: process staff name
misato.name
  => Split[_, " "]()
  ]=> parts
  => map(_ p = Upper[p]())
  => Join[_, " "]()
  ]=> displayName

stdout(displayName)  // "MISATO KATSURAGI"

// Safe division
Div[100, misato.id]() ]=> ratio
stdout(Str[ratio]() ]=> _)  // "100"

// Conditional
status <= | misato.active |> "Active" | _ |> "Inactive"
stdout(status)  // "Active"
```

---

## 関連ドキュメント

- [言語ガイド全章](/_corpus/guide/) -- 概要からイントロスペクションまで 13 章
- [演算子リファレンス](/_corpus/reference/operators.md)
- [モールド型リファレンス](/_corpus/reference/mold_types.md)
- [標準メソッドリファレンス](/_corpus/reference/standard_methods.md)
- [哲学](/_corpus/PHILOSOPHY.md)

---

# Taida パッケージ

> **[PHILOSOPHY.md](/_corpus/PHILOSOPHY.md) -- I.** 深く考えずに適当にぶちこんでけ

Taida のパッケージシステムは `packages.tdm` マニフェストと `>>>` / `<<<` 演算子で構成されます。バージョン管理、依存解決、ロックファイルを備えた完全なパッケージマネージャです。

---

## packages.tdm マニフェスト

プロジェクトルートに `packages.tdm` を配置します。`taida init` で雛形を生成できます。

```taida
// packages.tdm

// Dependencies with version pins
>>> author/some-lib@a.3
>>> another/tool@b.12

// Exports (what this package provides)
<<<@a.1 @(myFunction, MyType, helper)
```

### マニフェスト構造

| セクション | 構文 | 用途 |
|------------|------|------|
| 依存関係 | `>>> author/pkg@gen.num[.label]` | バージョン付きパッケージ依存の宣言 |
| エクスポート | `<<<@gen.num[.label] @(symbols)` | パッケージバージョンと公開 API の宣言 |

### バージョン形式: `@gen.num[.label]`

Taida は SemVer を使いません。`@gen.num` 形式を採用しています:

```taida
>>> author/package@a.3         // exact: 世代 a の publish #3
>>> author/package@b           // 世代指定: 世代 b の最新を lockfile が解決
>>> author/package@a.4.alpha   // ラベル付き: プレリリース版
```

| フィールド | 意味 | 例 |
|-----------|------|-----|
| **gen** | 世代。破壊的変更時に `taida verify` が自動インクリメント | `a`, `b`, `aa` |
| **num** | パッケージの通算 publish 回数（リセットなし） | `1`, `47`, `128` |
| **label** | 任意のラベル（省略可）。プレリリースやリリース候補の識別 | `alpha`, `rc-1`, `beta2` |

`@c.47` を見れば:
- 破壊的変更が **2 回** あった（世代 c）
- 通算 **47 回目** の publish

### ラベル

ラベルはバージョンの末尾に `.label` として付与します。`taida publish --label <LABEL>` で指定します。

```taida
<<<@a.4.alpha @(run, Config)    // プレリリース版
<<<@a.5.rc-1 @(run, Config)     // リリース候補
<<<@a.6 @(run, Config)          // 正式リリース
```

ラベルの命名規則: `[a-z0-9][a-z0-9-]*`（小文字英数字で始まり、末尾ハイフン不可）

### 世代

世代の進行: `a → b → c → ... → z → aa → ab → ...`

世代は `taida publish` 時に verify が自動判定します。開発者が手動で指定することはありません。

---

## インポート / エクスポート

### パッケージからのインポート

```taida
// External package (version resolved from packages.tdm or inline)
>>> author/package@a.3 => @(funcA, funcB)

// Local file
>>> ./utils.td => @(helper, format)

// With alias
>>> ./math.td => @(add, subtract => sub)
```

### シンボルのエクスポート

```taida
// Multiple symbols
<<< @(add, subtract, Point)

// Single symbol
<<< myFunction

// One-liner export
<<< double x: Int = x * 2 => :Int
```

---

## taida-community レジストリ

Taida パッケージは [taida-community](https://github.com/taida-community) GitHub organization でホストされます。Fork ベースのレジストリです。

### 仕組み

1. **初回公開**: `taida publish` が `taida-community/proposals` に Issue を自動作成し、審査を受ける
2. **審査**: 自動 CI + ゲートキーパーレビュー
3. **承認**: `taida-community/{package-name}` に Fork リポジトリが作成される
4. **更新**: 以降のバージョンは Fork リポジトリへの PR として自動作成される

### パッケージ命名規則

```
author/package-name
```

- `author`: GitHub ユーザー名または org 名
- `package-name`: 小文字、ハイフン区切り

---

## CLI コマンド

### `taida init`

`packages.tdm` テンプレート付きの新規プロジェクトを生成します:

```bash
taida init
```

生成されるファイル:

```
my-project/
  packages.tdm
  main.td
  .taida/
    taida.lock
```

### `taida install`

`packages.tdm` に宣言された全ての依存パッケージをインストールします:

```bash
taida install
```

- 依存ツリーを解決
- taida-community からパッケージをダウンロード
- `.taida/taida.lock` を生成

### `taida deps`

厳密な依存解決と検証を行います:

```bash
taida deps
```

- 全ての依存関係を解決
- 不足パッケージをインストール
- ロックファイルを更新
- ダイヤモンド依存の衝突を検出

### `taida update`

世代内の最新バージョンに依存パッケージを更新します:

```bash
taida update
```

- taida-community で新しいバージョンを確認
- lockfile を再生成

### `taida publish`

パッケージを taida-community に公開します:

```bash
taida publish [--label LABEL] [--dry-run]
```

- `taida auth login` 済みであること
- verify が破壊的変更を自動検知し、世代を決定
- git commit + tag + push 方式で公開
- 初回は `taida-community/proposals` に Issue を自動作成

---

## ロックファイル

ロックファイルは `.taida/taida.lock` に保存されます。全ての依存関係の正確な解決済みバージョンを記録します。

- バージョン管理にコミットする
- 再現可能なビルドを保証する
- `taida install`、`taida deps`、`taida update` で再生成される
- 世代指定（`@a`）を exact バージョン（`@a.47`）に解決・記録する

---

## 依存解決

### ダイヤモンド依存

2 つのパッケージが同じパッケージの異なるバージョンに依存している場合、両方がインストールされます。各パッケージは自分の packages.tdm に書いたものだけが見えます。

### プロバイダ

依存関係はプロバイダの連鎖を通じて解決されます:

| 優先度 | プロバイダ | ソース |
|--------|-----------|--------|
| 1 | ワークスペース | ローカルの `packages.tdm` |
| 2 | コアバンドル | Taida に同梱されたパッケージ |
| 3 | ストア | taida-community GitHub org |

---

## プロジェクト例

```taida
// packages.tdm
>>> utils/string-helpers@a.3
>>> data/json-tools@b.7

<<<@a.1 @(processData, DataResult)
```

```taida
// main.td
>>> utils/string-helpers@a.3 => @(capitalize, slugify)
>>> ./types.td => @(Article)

article <= Article(
  title <= capitalize("hello world"),
  slug <= slugify("hello world")
)

stdout(jsonEncode(article))
```

---

## 関連ドキュメント

- [モジュールガイド](/_corpus/guide/10_modules.md)
- [CLI リファレンス](/_corpus/reference/cli.md)
- [コミュニティガイド](/community.md)

---

# Taida Lang -- 概要

> **PHILOSOPHY.md -- I.** 深く考えずに適当にぶちこんでけ

---

## Taida とは何か

Taida Lang は AI 協業時代のために設計されたプログラミング言語です。

演算子は10種のみに限定されており、null や undefined は存在しません。全ての型にデフォルト値が保証され、暗黙の型変換は一切行われません。操作はモールド（鋳型）で行い、メソッドは状態チェックと toString だけが残っています。

> **PHILOSOPHY.md -- IV.** キモい言語だ。だが、書くのも読むのもAI。眺めるのが人間の仕事。

AI が積極的に選定し、AI が書き、AI が読みます。人間は構造を眺めるだけで構いません。それが Taida の基本姿勢です。

---

## 技術的な特徴

Taida は3本の柱で成り立っています。

### 1. `><` -- ゴリラ哲学

`><` 怒りの表情がそのままリテラルになりました。プログラムにゴリラが出現する、すなわちコードが終了するということです。

```taida
| data.isEmpty() |> ><  // ゴリラが出現。プログラムは終了します。
```

他の言語では `sys.exit(1)` に11文字、`process.exit(1)` に15文字を要しますが、Taida では2文字で済みます。import も不要です。

また、カスタムエラーの throw をキャッチし忘れた場合は、暗黙のゴリラ天井がプログラムを停止させます。ゼロ除算や範囲外アクセスは Lax で安全に処理され、プログラムは止まりません。

詳しくは [エラー処理](08_error_handling.md) を参照してください。

### 2. 型のガチガチさ -- 厳格な型システム

Taida の型システムは柔軟さよりも厳格さを重視しています。

```taida
// これはエラーになります
"Count: " + 42              // コンパイルエラー。暗黙変換は行いません。

// 明示的に変換してください
"Count: " + Str[42]() ]=> _  // Str モールドで変換します
"Count: " + 42.toString()    // toString メソッドでも OK です
```

全ての型にデフォルト値があり、null は存在しません。外部データ（JSON）は溶鉄として扱われ、スキーマ（鋳型）を通さなければ Taida の型安全な世界に入れません。

詳しくは [型システム](01_types.md) と [型のガチガチさ](02_strict_typing.md) を参照してください。

### 3. 構造 -- ぶちパック、モールディング、グラフ

データは「ふくろ」にしまい、型が必要なら「鋳型」を作ります。そしてコードの構造はグラフとして抽出されます。

```taida
// ふくろ（ぶちパック）
pilot <= @(name <= "Rei", syncRate <= 78)

// 鋳型（モールディング型）
Mold[T] => Result[T, P <= :T => :Bool] = @(throw: Error)

// グラフ -- 10種の演算子だからこそ、決定的に抽出できます
data => Filter[_, _ x = x > 0]() => Map[_, _ x = x * 2]() => result
```

---

## なぜ AI は Taida を選ぶのか

### 固有演算子が10種しかない

覚えることが少ないというのは、AI にとっても同じです。生成するパターンが限定されるほど、正確なコードを書くことができます。

| 演算子 | 用途 |
|--------|------|
| `=` | 定義 |
| `=>` `<=` | ぶちこみ（データフロー） |
| `]=>` `<=[` | アンモールディング（値の取り出し） |
| `\|==` | エラー天井 |
| `\|` `\|>` | 条件分岐 |
| `>>>` `<<<` | モジュール（インポート/エクスポート） |

### グラフが決定的に抽出できる

演算子が少なく意味が一意であるため、構文を走査するだけでデータフローグラフを構築できます。推論も近似も不要です。AI が生成したコードの構造を、AI 自身が即座に検証できます。

### null がない

AI がコード生成する際に最も厄介なのは、「この変数は null かもしれない」という不確実性です。Taida では全ての型にデフォルト値が保証されているため、null チェックは不要です。

### 終端が明確

ゴリラリテラル `><` がある分岐は到達不能コードであり、`|==` がなければゴリラ天井が控えています。制御フローの終端が常に明確であるため、AI は安全なコードを生成しやすくなります。

---

## Hello World

```taida
greet name: Str =
  "Hello, " + name + "!"
=> :Str

message <= greet("World")
stdout(message)  // "Hello, World!"
```

`stdout` はプレリュードに含まれるビルトイン関数です。import は不要です。

---

## 基本的な構文

### 変数と代入

```taida
x <= 42
name <= "Asuka"
active <= true
```

### 型定義

```taida
Pilot = @(
  name: Str
  age: Int
  active: Bool
)

asuka <= Pilot(name <= "Asuka", age <= 14, active <= true)
```

### 関数定義

```taida
add x: Int y: Int =
  x + y
=> :Int

result <= add(3, 5)  // 8
```

### 条件分岐

```taida
grade <=
  | score >= 90 |> "A"
  | score >= 80 |> "B"
  | score >= 70 |> "C"
  | _ |> "D"
```

### パイプライン

```taida
// パイプライン: => で流す
data => Filter[_, _ x = x > 0]() => Map[_, _ x = x * 2]() => result
```

### エラー天井

```taida
|== error: Error =
  "Error: " + error.message
=> :Str

// この下でエラーが throw される可能性がある処理
riskyOperation()
```

### モジュール

```taida
>>> ./utils.td => @(helper, format)

result <= helper(data)

<<< @(myFunction, MyType)
```

---

## デフォルト値

全ての型にデフォルト値があります。null は存在しません。

| 型 | デフォルト値 |
|----|-------------|
| Int | `0` |
| Float | `0.0` |
| Str | `""` |
| Bool | `false` |
| @[T] (リスト) | `@[]` |
| @(...) (ぶちパック) | 各フィールドのデフォルト値 |
| JSON | `{}` (空オブジェクト) |
| Lax[T] | T のデフォルト値 |

```taida
// 型を定義すれば、省略されたフィールドはデフォルト値になります
NervStaff = @(name: Str, callSign: Str, age: Int)
ritchan <= NervStaff(name <= "Ritsuko")  // callSign = "", age = 0
```

---

## 他言語との比較

| 特徴 | Taida | TypeScript | Rust | Python |
|------|-------|------------|------|--------|
| 型安全性 | 厳格 | 中 | 極高 | 低 |
| null 安全 | 完全排除 | partial | Option | なし |
| メモリ管理 | 完全自動 | GC | 所有権 | GC |
| 学習コスト | 低 | 中 | 高 | 低 |
| AI 親和性 | 極高 | 中 | 低 | 中 |
| グラフ抽出 | 決定的 | 非決定的 | 非決定的 | 非決定的 |
| 操作の表現 | モールド | メソッド | メソッド | メソッド/関数 |
| 除算安全性 | Lax (常に値を返す) | Infinity | パニック (int) | ZeroDivisionError |

---

## ドキュメント構成

### ガイド

| # | ドキュメント | 内容 |
|---|------------|------|
| 00 | [概要](00_overview.md) | 本ドキュメント |
| 01 | [型システム](01_types.md) | プリミティブ型、Enum型、コレクション型、モールディング型、デフォルト値 |
| 02 | [型のガチガチさ](02_strict_typing.md) | 暗黙変換禁止、Lax による安全な操作、JSON エアロック |
| 03 | [JSON 溶鉄](03_json.md) | JSON の不透明プリミティブ化、スキーマ必須の型変換 |
| 04 | [ぶちパック](04_buchi_pack.md) | ぶちパック構文 |
| 05 | [モールディング](05_molding.md) | モールディング型（操作モールド全種） |
| 06 | [リスト操作](06_lists.md) | リスト操作（モールド + 状態チェックメソッド） |
| 07 | [制御フロー](07_control_flow.md) | 条件分岐、パターンマッチ |
| 08 | [エラー処理](08_error_handling.md) | Lax + throw/\|== + ゴリラ天井 |
| 09 | [関数](09_functions.md) | 関数定義、パイプライン、末尾再帰 |
| 10 | [モジュール](10_modules.md) | モジュールシステム（プリリュード、インポート/エクスポート） |
| 11 | [非同期処理](11_async.md) | Async[T]、]=> await |
| 12 | [イントロスペクション](12_introspection.md) | 構造的イントロスペクション |
| 13 | [アドオン作成](13_creating_addons.md) | Rust アドオンの作成とプレビルド配布 |

### リファレンス

| ドキュメント | 内容 |
|------------|------|
| [演算子リファレンス](../reference/operators.md) | 10種の演算子 + 算術・比較・論理 |
| [モールディング型リファレンス](../reference/mold_types.md) | 全モールドの型シグネチャ |
| [命名規則](../reference/naming_conventions.md) | 識別子の命名規則 |
| [CLI リファレンス](../reference/cli.md) | 実装準拠のコマンド一覧とオプション |
| [グラフモデル](../reference/graph_model.md) | 5つのグラフビュー |
| [ドキュメントコメント](../reference/documentation_comments.md) | AI 協業タグ |
| [末尾再帰最適化](../reference/tail_recursion.md) | TCO の判定ルール |
| [スコープルール](../reference/scope_rules.md) | スコープベース自動管理 |
| [アドオンマニフェスト](../reference/addon_manifest.md) | addon.toml の仕様 |
| [診断コード](../reference/diagnostic_codes.md) | コンパイラ診断コード一覧 |
| [標準ライブラリ](../reference/standard_library.md) | プリリュードとビルトイン型 |
| [標準メソッド](../reference/standard_methods.md) | 状態チェック・モナディックメソッド |

### 設計ドキュメント

| ドキュメント | 内容 |
|------------|------|
| [メソッド→モールド リファクタリング](../design/method_to_mold_refactoring.md) | 操作モールド設計 |
| [JSON 溶鉄化](../design/json_molten_iron.md) | JSON の不透明プリミティブ化設計 |
| [CLI ドキュメント運用設計](../design/cli_documentation.md) | CLI 文書の同期ルールと更新規約 |
| [Graph/Human 収益化設計](../design/graph_human_monetization.md) | 無料 `taida` と有料 `taida-human` の責務分離 |

---

# 型システム

> **PHILOSOPHY.md -- I.** 深く考えずに適当にぶちこんでけ

Taida の型システムは、開発者が型を意識しなくて済むように設計されています。強力な型推論があり、全ての型にデフォルト値が保証され、暗黙の型変換は行われません。書くときは何も考えなくて構いません。裏では型チェッカーがガチガチに守っています。

---

## プリミティブ型

### Int -- 整数

```taida
count <= 42
negative <= -10
```

**デフォルト値**: `0`

### Float -- 浮動小数点数

IEEE 754 double precision です。

```taida
pi <= 3.14159
rate <= 0.5
```

**デフォルト値**: `0.0`

### Str -- 文字列

```taida
name <= "Rei"
greeting <= 'Hello'
template <= `Hello, ${name}!`
```

**デフォルト値**: `""` (空文字列)

エスケープシーケンス:

| シーケンス | 文字 |
|-----------|------|
| `\n` | 改行 |
| `\t` | タブ |
| `\r` | 復帰 |
| `\\` | バックスラッシュ |
| `\'` | シングルクォート |
| `\"` | ダブルクォート |
| `\0` | null文字 |
| `\xHH` | 16進エスケープ (2桁) |
| `\u{HHHH}` | Unicodeエスケープ (1〜6桁) |

操作はモールドまたはメソッドで行います:

```taida
// モールドで操作
Upper["hello"]()                         // "HELLO"
Trim["  hello  "]()                      // "hello"
Split["a,b,c", ","]()                    // @["a", "b", "c"]
Replace["hello world", "world", "taida"]()  // "hello taida"

// メソッドで操作
"hello world".replace("world", "taida")  // "hello taida" (最初の一致のみ)
"aaa".replaceAll("a", "b")              // "bbb" (全置換)
"a,b,c".split(",")                       // @["a", "b", "c"]

// 状態チェックメソッド
"hello".length()                         // 5
"hello".contains("ell")                  // true
"hello".startsWith("he")                 // true
"hello".toString()                       // "hello"
```

### Bool -- 真偽値

```taida
active <= true
deleted <= false
```

**デフォルト値**: `false`

### Bytes -- バイト列（0..255）

バイナリ境界で使う組み込み型です。`Bytes` は `@[Int]` と違い、`0..255` の連続領域を表す用途に固定されています。

```taida
raw <= Bytes["ping"]()
raw ]=> bytes
bytes.length()                 // 4
bytes.get(0) ]=> b0            // 112
```

**デフォルト値**: `Bytes[@[]]`（空バイト列）

`Bytes` は不変です。更新は `ByteSet[...]()` が新しい値を返します。  
また、`Utf8Encode` / `Utf8Decode` で文字列との変換を行えます。

### Error -- エラー型

全てのエラーの基底型です。

```taida
Error = @(
  type: Str
  message: Str
)
```

カスタムエラーは Error を継承して定義します:

```taida
Error => ValidationError = @(
  field: Str
  code: Int
)
```

### Molten -- 溶鉄（不透明プリミティブ）

外部から入ってくる不定形データを表す型です。Molten は**溶鉄**です。形がなく、触れません。そのままでは何もできません。型安全な世界に持ち込むには、必ず Cage 経由で鋳型を通す必要があります。

Molten には型パラメータがありません。Molten は Molten でしかありません。メソッドも持たず、直接操作は一切できません。

`Bytes` と `Molten` は役割が異なります。

- `Bytes`: 3バックエンド共通のバイナリデータ型
- `Molten`: JS外部世界由来の不透明値（JS専用連携境界）

`UnsafePointer` はコア言語に導入しません。危険な低レベル境界は `Molten` などの不透明ハンドル + 専用APIで隔離します。

**デフォルト値**: `Molten`（Molten 型のデフォルト値は Molten 自身です。空の溶鉄です）

### JSON -- Molten の特殊ケース

JSON は Molten の特殊ケースです。外部から入ってくる JSON データを表します。JSON は溶鉄であり、形がなく、触れません。使うにはスキーマ（鋳型）を通す必要があります。

```taida
Pilot = @(name: Str, age: Int)

// スキーマを指定して鋳造します
JSON[rawStr, Pilot]() ]=> pilot
pilot.name   // 型安全にアクセスできます
```

JSON にはメソッドがありません。`json.at("name")` のような直接操作はできません。必ず `JSON[raw, Schema]()` でスキーマを通してください。戻り値は `Lax` です。

JSON は `Molten` の一種ですが、専用のモールド `JSON[raw, Schema]()` を持つ点が特殊です。他の Molten 値は `Cage` 経由で操作します。

**デフォルト値**: `{}` (空オブジェクト)

---

## コレクション型

### リスト `@[T]`

同種の値の列です。

```taida
numbers <= @[1, 2, 3, 4, 5]
names <= @["Asuka", "Rei"]
empty: @[Int] <= @[]
```

**デフォルト値**: `@[]` (空リスト)

操作はモールドで行います:

```taida
// モールドで操作します
Sort[@[3, 1, 2]]()                       // @[1, 2, 3]
Filter[@[1, 2, 3, 4], _ x = x > 2]()    // @[3, 4]
Map[@[1, 2, 3], _ x = x * 2]()          // @[2, 4, 6]
Concat[@[1, 2], @[3, 4]]()              // @[1, 2, 3, 4]
Join[@["a", "b", "c"], ","]()            // "a,b,c"

// パイプラインで連鎖します
numbers => Filter[_, _ x = x > 2]() => Map[_, _ x = x * 10]() => result

// メソッドは状態チェックと Lax 返しのみです
@[1, 2, 3].length()                      // 3
@[1, 2, 3].isEmpty()                     // false
@[1, 2, 3].contains(2)                   // true
@[1, 2, 3].get(0) ]=> val                // 1 (Lax を返します)
@[1, 2, 3].first() ]=> val               // 1 (Lax を返します)
empty: @[Int] <= @[]
empty.first() ]=> val                    // 0 (空リスト: デフォルト値)
```

### ぶちパック `@(...)`

> **PHILOSOPHY.md -- II.** だいじなものはふくろにしまっておきましょう

名前付きフィールドの集合です。

```taida
pilot <= @(name <= "Shinji", age <= 14)

// 型定義
Pilot = @(
  name: Str
  age: Int
  active: Bool
)

asuka <= Pilot(name <= "Asuka", age <= 14, active <= true)
```

**デフォルト値**: 各フィールドのデフォルト値

---

## モールディング型 `Mold[T]`

> **PHILOSOPHY.md -- III.** カタめたいなら、鋳型を作りましょう

型パラメータ化を実現する仕組みです。値を鋳型に流し込み（モールディング）、必要なときに取り出します（アンモールディング `]=>` / `<=[`）。

```taida
// 鋳型の定義
Mold[T] => Result[T, P <= :T => :Bool] = @(throw: Error)  // 述語付き操作モールド
Mold[T] => Lax[T] = @(hasValue: Bool)   // 安全モールド
```

### Result[T, P]

述語 P（`:T => :Bool`）で成功/失敗を判定する操作モールドです。`]=>` で述語を評価し、真なら値 T、偽なら throw が発動します。

```taida
Error => NotFound = @(message: Str)

// _ = true / _ = false は常に真/偽を返す無名関数
ok <= Result[42, _ = true]()
err <= Result[0, _ = false](throw <= NotFound(type <= "NotFound", message <= "fail"))

// => と ]=> の違い
ok ]=> value                  // 42（述語 true → 成功）
err ]=> value                 // throw 発動（エラー天井で捕捉可能）
err => r                      // r: Result[Int, _]（述語は未評価）

// ラムダ述語によるバリデーション
Result[age, _ x = x >= 18](throw <= err) ]=> validAge
```

### Lax[T] -- 必ず値を返すモールド型

「操作が失敗しても必ず値を返す」ことを保証するモールド型です。失敗時は型 T のデフォルト値にフォールバックします。

```taida
// 除算: ゼロ除算でも必ず値を返します
Div[10, 3]() ]=> result   // 3
Div[10, 0]() ]=> result   // 0 (Int のデフォルト値)

// リストアクセス: 範囲外でも必ず値を返します
items <= @[10, 20, 30]
items.get(1) ]=> val       // 20
items.get(100) ]=> val     // 0 (Int のデフォルト値)

// 型変換: 変換失敗でも必ず値を返します
Int["42"]() ]=> num        // 42
Int["abc"]() ]=> num       // 0 (変換失敗: デフォルト値)
```

`hasValue` フィールドで成功/失敗を判別できます:

```taida
lax <= Div[10, 0]()
lax.hasValue               // false (ゼロ除算は失敗)

lax2 <= Div[10, 3]()
lax2.hasValue              // true (正常に割れた)
```

**デフォルト値**: 内包する型 T のデフォルト値

### Gorillax[T] -- 覚悟のモールド型

「操作が失敗したらゴリラがプログラムを止める」モールド型です。Lax のようなデフォルト値へのフォールバックはありません。外部パッケージ（npm 等）の Molten 値への操作で使います。

```taida
// Cage で Molten（溶鉄）に操作を実行 → Gorillax で包まれます
Cage[lodash, _ lo = lo.sum(items)] => rilax  // rilax: Gorillax[Int]
rilax ]=> total              // 成功 → 値, 失敗 → ゴリラ（プログラム終了）

// .relax() で RelaxedGorillax に変換（|== でキャッチ可能に）
rilax.relax() => relaxed     // relaxed: RelaxedGorillax[Int]
```

**デフォルト値**: なし（unmold 失敗時はゴリラまたは throw）

### Async[T]

非同期処理を表現します。`]=>` がブロッキング await として機能します。

```taida
fetchData url: Str =
  httpGet(url)
=> :Async[@(body: Str)]

data <= fetchData("https://api.nerv.jp/pilots")
data ]=> response          // 完了まで待ちます
```

---

## 特殊型: Molten -- 溶鉄

Molten は他の型とは根本的に異なります。溶鉄です。形がなく、メソッドを持たず、直接操作はできません。JSON は Molten の特殊ケースであり、npm パッケージ等から得られる値も Molten です。

### 溶鉄の鋳造

```taida
// スキーマ（鋳型）を定義します
Pilot = @(
  name: Str
  age: Int
  syncRate: Int
)

// JSON を鋳型に流し込みます
raw <= '{"name": "Asuka", "age": 14, "syncRate": 78}'
JSON[raw, Pilot]() ]=> pilot

pilot.name      // "Asuka"
pilot.age       // 14
pilot.syncRate  // 78
```

### スキーマ照合のルール

| ルール | 動作 |
|--------|------|
| フィールド一致 | スキーマに定義されたフィールドのみ抽出。余分は無視 |
| フィールド欠損 | 型のデフォルト値を使用 |
| 型不一致 | 型のデフォルト値を使用 |
| null | 型のデフォルト値に変換（null 排除） |
| ネスト | 再帰的にスキーマ照合 |
| リスト | 各要素にスキーマを適用 |

```taida
// フィールド欠損 → デフォルト値
raw <= '{"name": "Rei"}'
JSON[raw, Pilot]() ]=> pilot
// pilot = @(name <= "Rei", age <= 0, syncRate <= 0)

// null → デフォルト値
raw <= '{"name": null, "age": null}'
JSON[raw, Pilot]() ]=> pilot
// pilot = @(name <= "", age <= 0, syncRate <= 0)
```

### 出力方向は安全

Taida の値を JSON 文字列にする方向は型安全です。プリリュード関数を使います:

```taida
pilot <= Pilot(name <= "Asuka", age <= 14, syncRate <= 78)
jsonEncode(pilot)   // '{"name":"Asuka","age":14,"syncRate":78}'
jsonPretty(pilot)   // 整形された JSON 文字列
```

---

## デフォルト値の完全保証

全ての型にデフォルト値があります。null も undefined も存在しません。

| 型 | デフォルト値 |
|----|-------------|
| Int | `0` |
| Float | `0.0` |
| Str | `""` |
| Bool | `false` |
| @[T] (リスト) | `@[]` |
| @(...) (ぶちパック) | 各フィールドのデフォルト値 |
| Molten | `Molten`（空の溶鉄） |
| JSON | `{}` (Molten の特殊ケース) |
| Lax[T] | T のデフォルト値 |

```taida
// 型を定義すれば、省略されたフィールドはデフォルト値になります
Pilot = @(name: Str, callSign: Str, age: Int)
rei <= Pilot(name <= "Rei")  // callSign = "", age = 0
```

---

## 型変換 -- モールドで明示的に

Taida では暗黙の型変換は一切行われません。型変換はモールドで明示的に行います。全ての型変換モールドは Lax を返します。

```taida
// Str → Int
Int["123"]() ]=> num         // 123
Int["abc"]() ]=> num         // 0 (変換失敗: デフォルト値)

// Str → Int（基数指定）
Int["ff", 16]() ]=> hex      // 255
Int["1010", 2]() ]=> bin     // 10

// Str → Float
Float["3.14"]() ]=> val      // 3.14
Float["abc"]() ]=> val       // 0.0 (変換失敗: デフォルト値)

// Int → Str
Str[42]() ]=> text           // "42"

// 値 → Bool
Bool[1]() ]=> flag           // true
Bool[0]() ]=> flag           // false
```

`toString()` メソッドも使えます。ただし型変換モールドと違い、Lax ではなく Str を直接返します:

```taida
42.toString()                // "42"
3.14.toString()              // "3.14"
true.toString()              // "true"
"hello".toString()           // "hello" (identity)
@[1, 2, 3].toString()        // "@[1, 2, 3]"
@(a <= 1, b <= 2).toString() // "@(a <= 1, b <= 2)"
```

`.toString()` は **全ての値型で利用できる共通メソッド** です（C12.rc3 で
3 バックエンド全てに正式採用）。Int / Float / Bool / Str / List / ぶちパック /
Lax / Result / HashMap / Set など、どの型に対しても呼び出せて、必ず `:Str`
を返します。文字列連結 (`+`) と組み合わせて使うのが標準的な使い方です:

```taida
status <= 404
msg <= "HTTP Error " + status.toString()
stdout(msg)                  // "HTTP Error 404"
```

引数は受け取りません。`n.toString(16)` のように base / precision を渡そう
とすると、`taida check` が `[E1508] Method 'toString' takes 0 argument(s)`
で拒否します。基数指定が必要な場合は `ToRadix[n, base]()` モールド
（`docs/reference/mold_types.md` 参照）を使います。`ToRadix` は
`Lax[Str]` を返すので、通常は `getOrDefault` で unwrap します:

```taida
ToRadix[255, 16]().getOrDefault("") ]=> hex   // "ff"
ToRadix[26, 2]().getOrDefault("") ]=> bin     // "11010"
```

精度指定など `ToRadix` でカバーできないフォーマットは専用の関数を別途
定義します（哲学 I: 暗黙の型変換なし）。

### 型変換モールド一覧

| モールド | 入力 | 出力 | 説明 |
|---------|------|------|------|
| `Int[x]()` | Str, Float, Bool | Lax[Int] | 整数に変換 |
| `Int[str, base]()` | Str, Int (2..36) | Lax[Int] | 指定基数で文字列を整数に変換 |
| `Float[x]()` | Str, Int | Lax[Float] | 浮動小数点に変換 |
| `Str[x]()` | Int, Float, Bool | Lax[Str] | 文字列に変換 |
| `Bool[x]()` | Int, Str | Lax[Bool] | 真偽値に変換 |

`Int[str]()` は文字列から整数への変換の正規経路です。`"+5"` や `"-7"` のような符号付き文字列も受理します。空文字列、数字以外の文字を含む文字列、小数点を含む文字列は変換失敗（`hasValue=false`）になります。

---

## 型アノテーション

型推論があるので、ほとんどの場合は型アノテーションを書く必要がありません。書きたいときだけ書けば十分です。

```taida
// 型推論に任せます（ほとんどの場合はこれで十分です）
x <= 42
name <= "Asuka"
pilots <= @[Pilot(name <= "Ritsuko")]

// 明示的に型を指定します
x: Int <= 42
name: Str <= "Rei"
pilots: @[Pilot] <= @[Pilot(name <= "Ritsuko")]
```

### 関数の型指定

```taida
add x: Int y: Int =
  x + y
=> :Int

createPilot name: Str age: Int =
  @(name <= name, age <= age, active <= true)
=> :@(name: Str, age: Int, active: Bool)
```

### 関数型シグネチャ

```taida
// 関数型は `:引数型 => :戻り型` の形式です
:Int => :Str      // Int から Str への関数
:Int :Int => :Int  // Int, Int から Int への関数
```

---

## 型推論

Hindley-Milner ベースの型推論により、大部分の場合で型アノテーションは不要です。

```taida
// リテラルからの推論
num <= 42              // Int
text <= "hello"        // Str
flag <= true           // Bool
list <= @[1, 2, 3]     // @[Int]

// 演算結果からの推論
sum <= 1 + 2           // Int
concat <= "a" + "b"    // Str

// ぶちパックからの推論
pilot <= @(name <= "Rei", age <= 14)
// pilot: @(name: Str, age: Int)

// モールドの結果からの推論
upper <= Upper["hello"]()    // Str
divided <= Div[10, 3]()      // Lax[Int]
```

---

## 構造的部分型付け

Taida は構造的部分型付けを採用しています。必要なフィールドを持っていれば、余分なフィールドがあっても互換性があります。

```taida
Pilot = @(
  name: Str
  age: Int
)

NervStaff = @(
  name: Str
  age: Int
  department: Str
  rank: Int
)

greet pilot: Pilot =
  "Hello, " + pilot.name
=> :Str

staff <= NervStaff(name <= "Ritsuko", age <= 30, department <= "Science", rank <= 2)
message <= greet(staff)  // OK: NervStaff は Pilot の部分型です
```

---

## 型エイリアス

型に別名をつけることができます。

```taida
PilotId = Int
PilotName = Str
PilotList = @[Pilot]

id: PilotId <= 2
name: PilotName <= "Asuka"
```

---

## Enum 型

列挙型です。有限個のバリアントから1つを選ぶ値を定義します。

### 定義

```taida
Enum => Status = :Ok :Fail :Retry
```

`Enum =>` でenum定義を開始し、バリアントを `:名前` で列挙します。

### 使用

```taida
Enum => Status = :Ok :Fail :Retry

myStatus <= Status:Retry()
stdout(myStatus)              // 2（ordinal値、0-indexed）
stdout(myStatus == Status:Retry())  // true
```

enum値は ordinal（0始まりの Int）として評価されます。`Status:Ok()` は `0`、`Status:Fail()` は `1`、`Status:Retry()` は `2` です。

### ビルトイン enum: HttpProtocol

`taida-lang/net` パッケージは `HttpProtocol` enum をエクスポートします:

```taida
>>> taida-lang/net => @(httpServe, HttpProtocol)

// HttpProtocol:H1() → 0 (wire: "h1.1")
// HttpProtocol:H2() → 1 (wire: "h2")
// HttpProtocol:H3() → 2 (wire: "h3")
httpServe(8080, handler, 1, 1000, 128, @(protocol <= HttpProtocol:H1()))
```

**デフォルト値**: 最初のバリアント（ordinal 0）

---

## まとめ

| 分類 | 型 | デフォルト値 |
|------|-----|-------------|
| プリミティブ | Int | `0` |
| プリミティブ | Float | `0.0` |
| プリミティブ | Str | `""` |
| プリミティブ | Bool | `false` |
| プリミティブ | Molten | `Molten`（空の溶鉄、メソッドなし） |
| プリミティブ | JSON | `{}` (Molten の特殊ケース、メソッドなし) |
| コレクション | @[T] (リスト) | `@[]` |
| コレクション | @(...) (ぶちパック) | 各フィールドのデフォルト値 |
| モールディング | Result[T, P] | T のデフォルト値 |
| モールディング | Lax[T] | T のデフォルト値 |
| モールディング | Async[T] | T のデフォルト値 |
| 列挙型 | Enum | 最初のバリアント (ordinal 0) |

操作はモールドで行います。メソッドは状態チェック + toString + モナディック操作のみです。型変換もモールドで明示的に行います。null はありません。

---

# 型のガチガチさ

> **PHILOSOPHY.md -- I.** 深く考えずに適当にぶちこんでけ

---

## Taida は柔軟ではありません

他の言語は柔軟さを売りにすることが多いですが、Taida は**ガチガチな厳格さ**を売りにしています。

柔軟さは「何が起こるかわからない」の別名であり、暗黙変換は「予想外の挙動」の温床です。Taida の型システムは、開発者が考えなくていいように全てを決めています。デフォルト値があり、暗黙変換はなく、失敗は Lax で安全に処理されます。曖昧さはありません。

Taida の「ガチガチ」は、エラーで止めるのではなく、**Lax で安全に値を返す**ことでガチガチさと安全性を両立しています。

---

## 暗黙の型変換は存在しません

```taida
// 他の言語ならこう書けます。Taida ではコンパイルエラーになります。
"Count: " + 42        // コンパイルエラー: Str と Int の加算はできません

// これが正解です。明示的に変換してください。
"Count: " + 42.toString()  // "Count: 42"
"Count: " + Str[42]() ]=> _  // Str モールドでも OK です
```

JavaScript は `"Count: " + 42` を `"Count: 42"` にしてくれます。便利ですが、`"5" - 3` は `2` になり、`"5" + 3` は `"53"` になります。便利の裏に予想外の挙動が潜んでいます。

Python は `"Count: " + 42` で `TypeError` を出します。正しい判断ですが、それは実行時エラーであり、プログラムを走らせるまでわかりません。

Taida は**コンパイル時**にエラーにします。走る前に止めます。

```taida
// 全て明示的に行います
num <= 42
str <= num.toString()           // "42"
Int["42"]() ]=> back            // 42
ToFixed[num, 2]() ]=> formatted // "42.00"
```

---

## ゼロ除算は Lax で安全に処理します

Taida に `/` 演算子と `%` 演算子はありません。除算と剰余は `Div[x, y]()` と `Mod[x, y]()` モールドで行います。ゼロ除算は Lax を返し、プログラムを停止させません。

```taida
Div[10, 3]() ]=> result  // 3
Div[10, 0]() ]=> result  // 0 (ゼロ除算: Lax のデフォルト値)
```

### 他の言語との比較

| 言語 | `10 / 0` の結果 | 問題 |
|------|-----------------|------|
| JavaScript | `Infinity` | 壊れたまま走り続けます |
| Python | `ZeroDivisionError` | 実行時エラー |
| Java | `ArithmeticException` (int), `Infinity` (double) | 型によって挙動が異なります |
| Rust | パニック (int), `Infinity` (float) | 型によって挙動が異なります |
| **Taida** | **Lax (デフォルト値)** | **常に値を返します。hasValue で判別できます** |

Taida はゼロ除算で壊れません。`Div[x, y]()` は Lax を返し、成功時は計算結果が、失敗時は型のデフォルト値がアンモールディングで取り出されます。

成功/失敗を判別する必要がある場合は `hasValue` を参照してください:

```taida
lax <= Div[10, 0]()
lax.hasValue  // false (ゼロ除算は失敗)

lax2 <= Div[10, 3]()
lax2.hasValue  // true (正常に割れた)
```

剰余も同様です:

```taida
Mod[10, 3]() ]=> result   // 1
Mod[10, 0]() ]=> result   // 0 (ゼロ除算: デフォルト値)
Mod[10, 0]().hasValue      // false
```

---

## 範囲外アクセスは Lax で安全に処理します

リストの要素アクセスは `.get()` メソッドで行います。範囲外の場合は Lax を返し、プログラムを停止させません。

```taida
items <= @[10, 20, 30]
items.get(1) ]=> val    // 20
items.get(100) ]=> val  // 0 (範囲外: Lax のデフォルト値)
```

### 他の言語との比較

| 言語 | `array[100]` の結果 | 問題 |
|------|---------------------|------|
| JavaScript | `undefined` | 黙って壊れます |
| Python | `IndexError` | 実行時エラー |
| Java | `ArrayIndexOutOfBoundsException` | 実行時エラー |
| Rust | パニック | |
| **Taida** | **Lax (デフォルト値)** | **常に値を返します。hasValue で判別できます** |

`first()`、`last()`、`max()`、`min()` も同様に Lax を返します:

```taida
@[1, 2, 3].first() ]=> val  // 1
empty: @[Int] <= @[]
empty.first() ]=> val        // 0 (空リスト: Lax のデフォルト値)

@[1, 2, 3].last() ]=> val   // 3
empty.last() ]=> val         // 0 (空リスト: Lax のデフォルト値)

@[1, 3, 2].max() ]=> val    // 3
empty.max() ]=> val          // 0 (空リスト: Lax のデフォルト値)
```

成功/失敗を判別したい場合:

```taida
empty: @[Int] <= @[]
lax <= empty.first()
lax.hasValue  // false (空リスト)
```

---

## JSON はエアロック（溶鉄）

外部から入ってくる JSON データは、Taida の型安全な世界にそのまま入れることはできません。JSON は**溶鉄**です。形がなく、メソッドを持たず、スキーマ（鋳型）を通さなければ使えません。

```
外部世界 (JSON)           鋳型（スキーマ）         Taida の型安全な世界
                      +-----------+
  {"name": "Asuka"}  |           |    name: Str <= "Asuka"
  {"age": null}   --> | JSON[x,T] | --> age: Int <= 0 (デフォルト値)
  {"x": ???}          |           |    (余分なフィールドは無視)
                      +-----------+
```

### JSON 構文

```taida
// スキーマを定義します
Pilot = @(name: Str, age: Int, syncRate: Int)

// JSON[生データ, スキーマ]() で鋳造します
raw <= '{"name": "Shinji", "age": 14, "syncRate": 78}'
JSON[raw, Pilot]() ]=> pilot

pilot.name      // "Shinji"
pilot.age       // 14
pilot.syncRate  // 78
```

### スキーマなしはエラーです

```taida
// NG: スキーマなし
JSON[raw]()               // コンパイルエラー: JSON requires a schema type argument

// NG: JSON にメソッドはありません
data <= JSON[raw, Pilot]()
data.at("name")           // コンパイルエラー: JSON has no methods

// OK: スキーマを通して鋳造します
JSON[raw, Pilot]() ]=> pilot
pilot.name                // "Shinji" (型安全)
```

### null は排除されます

```taida
Pilot = @(name: Str, age: Int)

// JSON の null はデフォルト値に変換されます
raw <= '{"name": null, "age": null}'
JSON[raw, Pilot]() ]=> pilot
// pilot = @(name <= "", age <= 0)
```

### 出力方向は安全です

Taida の値を JSON 文字列にする方向は型安全なので、自由に使えます:

```taida
jsonEncode(pilot)   // JSON 文字列に変換
jsonPretty(pilot)   // 整形された JSON 文字列に変換
```

---

## デフォルト値保証

> **PHILOSOPHY.md -- I.** 深く考えずに適当にぶちこんでけ

「安全に処理する」と「デフォルト値がある」は一貫しています。

- `Div[10, 0]()` は Lax を返します -- これは**よくある失敗**なので Lax でデフォルト値にフォールバックします
- `Pilot(name <= "Rei")` で `age` は `0` -- これは**省略されたフィールド**なのでデフォルト値を使います
- `JSON[raw, Pilot]()` でフィールド欠損 → デフォルト値 -- 外部データの不備はデフォルトで吸収します

よくある失敗には Lax で安全に処理し、省略された値にはデフォルトを与えます。全ての操作で「値が存在する」ことを保証するのが Taida の型システムの核心です。

| 型 | デフォルト値 |
|----|-------------|
| Int | `0` |
| Float | `0.0` |
| Str | `""` |
| Bool | `false` |
| @[T] | `@[]` |
| JSON | `{}` |

null はありません。undefined もありません。全ての変数には値があります。

---

## 型のガチガチさ = 安全 + 明示的

Taida の型のガチガチさは2つの意味を持っています。

### 1. 全てが明示的であること

```taida
// 暗黙変換はありません
"Count: " + 42                 // コンパイルエラー
"Count: " + 42.toString()      // OK: 明示的な変換

// 操作はモールドで明示的に行います
Upper["hello"]()               // "HELLO"（モールドで操作）
Div[10, 3]()                   // 除算もモールドで

// JSON はスキーマ必須です
JSON[raw, Pilot]()             // OK: スキーマ指定
JSON[raw]()                    // NG: スキーマなし
```

### 2. 全ての操作が安全であること

```taida
// ゼロ除算 → Lax で安全に
Div[10, 0]() ]=> result        // 0 (プログラムは止まりません)

// 範囲外アクセス → Lax で安全に
@[1, 2].get(100) ]=> val      // 0 (プログラムは止まりません)

// 型変換失敗 → Lax で安全に
Int["abc"]() ]=> num           // 0 (プログラムは止まりません)

// JSON のフィールド欠損 → デフォルト値
JSON['{}', Pilot]() ]=> pilot  // 全フィールドがデフォルト値
```

### 型チェッカーが守るもの

```taida
// 存在しないフィールドへのアクセス
pilot <= @(name <= "Asuka")
callSign <= pilot.callSign  // コンパイルエラー: フィールド 'callSign' は存在しません

// 型不一致
add x: Int y: Int = x + y => :Int
result <= add("hello", 5)  // コンパイルエラー: 第1引数で Str 型を Int 型に適用できません

// 単一方向制約
data => Filter[_, _ x = x > 0]() <= result  // コンパイルエラー: 単一方向制約違反
```

---

## ガチガチの何がいいのか

1. **バグが実行前にわかります** -- コンパイル時に型エラーを検出します
2. **よくある失敗で止まりません** -- Lax がデフォルト値で安全に処理します
3. **AI が安全なコードを生成できます** -- 暗黙の挙動がないため、AI の出力が予測可能です
4. **人間は眺めるだけで構いません** -- 型が合っていれば、コードの構造が正しいことが保証されます

> **PHILOSOPHY.md -- IV.** キモい言語だ。だが、書くのも読むのもAI。眺めるのが人間の仕事。

ガチガチだからこそ、安心してぶちこめるのです。

---

## まとめ

| 原則 | Taida の対応 |
|------|-------------|
| 暗黙変換 | 存在しません。コンパイルエラーです |
| ゼロ除算 | `Div[x, y]()` が Lax を返します。hasValue で判別できます |
| 範囲外アクセス | `.get()` が Lax を返します。hasValue で判別できます |
| 型変換 | モールドで明示的に。`Int[x]()`, `Str[x]()` 等。全て Lax を返します |
| JSON | 溶鉄。`JSON[raw, Schema]()` でスキーマ必須。メソッドなし |
| null | 存在しません。全ての型にデフォルト値があります |
| カスタムエラー | throw + ゴリラ天井。Lax とは別の仕組みです |

---

# JSON 溶鉄

> **PHILOSOPHY.md -- III.** カタめたいなら、鋳型を作りましょう

---

## JSON は溶鉄です

Taida の内部は型安全な世界です。全ての変数に型があり、デフォルト値があり、null はありません。

しかし外部の世界 -- API レスポンス、設定ファイル、ユーザー入力 -- はそうとは限りません。JSON には `null` が含まれるかもしれませんし、フィールドが欠けているかもしれません。型が間違っている可能性もあります。

Taida は JSON を**溶鉄**（molten iron）として扱います。溶鉄は熱く、形がなく、そのままでは触れません。型安全な世界に持ち込むには、必ず**鋳型**（スキーマ）を通す必要があります。

```
溶鉄（JSON）         鋳型（スキーマ）         製品（型付きぶちパック）
                    +-----------+
  raw string        |           |
  API response  --> | JSON[x,T] | -->  型安全な Taida 値
  config file       |           |
                    +-----------+
```

- **溶鉄** = 生の JSON データ。形がありません。触れません。そのままでは何もできません。
- **鋳型** = ぶちパックの型定義（TypeDef）。JSON の形を決めます。
- **鋳造** = `JSON[raw, Schema]()` で溶鉄を鋳型に流し込みます。
- **製品** = 型付きぶちパック。Taida の型安全な世界の住人です。

### JSON は不透明なプリミティブ型です

JSON 型はメソッドを一切持ちません。JSON はただの不透明な塊であり、中身を覗くことも、直接操作することもできません。

```taida
// これらは全てエラーになります
data.at("name")       // エラー: JSON has no methods
data.toStr()           // エラー: JSON has no methods
data.keys()            // エラー: JSON has no methods
data ]=> x             // エラー: JSON direct unmold is not allowed
```

JSON を使うには、スキーマを指定して型変換するしかありません。

---

## JSON[raw, Schema]() の基本

`JSON[raw, Schema]()` モールドが、溶鉄を型安全な値に鋳造する唯一の方法です。

### 引数の順序: `[何を, 何で]` 原則

```taida
JSON[raw, User]()
      |     |
     何を  何で（どの型に鋳造するか）
```

他のモールドと同じく、対象（何を）が先、ツール/パラメータ（何で）が後です。`Filter[list, fn]()`, `Split[str, delim]()` と一貫しています。

### 基本の使い方

```taida
// 1. スキーマを定義します
Pilot = @(name: Str, age: Int, active: Bool)

// 2. JSON 文字列を用意します
raw <= '{"name": "Asuka", "age": 14, "active": true}'

// 3. JSON モールドでスキーマを通して鋳造します
JSON[raw, Pilot]() ]=> pilot
// pilot: @(name <= "Asuka", age <= 14, active <= true)
```

### 2 引数は必須です

`JSON` モールドは常に 2 引数（生データ + スキーマ）を要求します。1 引数はコンパイルエラーです。

```taida
JSON[raw, User]()    // OK: スキーマあり
JSON[raw]()          // エラー: JSON requires a schema type argument
```

---

## スキーマの書き方

スキーマは Taida の TypeDef（ぶちパックの型定義）をそのまま使います。特別な構文は必要ありません。

### 基本スキーマ

```taida
Pilot = @(
  name: Str
  age: Int
  active: Bool
)

raw <= '{"name": "Rei", "age": 14, "active": true}'
JSON[raw, Pilot]() ]=> pilot
```

### ネストしたスキーマ

```taida
Address = @(
  city: Str
  zip: Str
)

Pilot = @(
  name: Str
  age: Int
  address: Address
)

raw <= '{"name": "Asuka", "age": 14, "address": {"city": "Tokyo-3", "zip": "999-0003"}}'
JSON[raw, Pilot]() ]=> pilot
pilot.address.city    // "Tokyo-3"
```

### リスト型のスキーマ

配列の JSON は `@[TypeDef]` をスキーマとして渡します。

```taida
Pilot = @(name: Str, syncRate: Int)

raw <= '[{"name": "Asuka", "syncRate": 95}, {"name": "Shinji", "syncRate": 41}]'
JSON[raw, @[Pilot]]() ]=> pilots
// pilots: @[@(name <= "Asuka", syncRate <= 95), @(name <= "Shinji", syncRate <= 41)]
```

### プリミティブ型への直接変換

```taida
JSON['"42"', Int]() ]=> num        // 42
JSON['[1, 2, 3]', @[Int]]() ]=> nums  // @[1, 2, 3]
```

---

## パース結果は Lax で返ります

JSON パースは失敗する可能性があります。`JSON[raw, Schema]()` の戻り値は `Lax[T]` です。

```taida
Pilot = @(name: Str, age: Int, active: Bool)

// パース成功
raw <= '{"name": "Rei", "age": 14, "active": true}'
JSON[raw, Pilot]() ]=> pilot
// pilot: @(name <= "Rei", age <= 14, active <= true)

// パース失敗（不正な JSON）
JSON["invalid json", Pilot]().hasValue    // false
JSON["invalid json", Pilot]() ]=> pilot2
// pilot2: @(name <= "", age <= 0, active <= false)  // 全てデフォルト値
```

### hasValue で成功判定

```taida
result <= JSON[raw, Pilot]()
result.hasValue    // true ならパース成功、false なら失敗
```

### getOrDefault でフォールバック

```taida
fallback <= Pilot(name <= "Unknown", age <= 0, active <= false)
JSON[raw, Pilot]().getOrDefault(fallback)
```

---

## スキーママッチングの 6 つのルール

JSON データをスキーマに照合する際の動作を、6 つのルールで説明します。

### ルール 1: フィールド一致

スキーマに定義されたフィールドのみが抽出されます。余分なフィールドは無視されます。

```taida
Pilot = @(name: Str, age: Int)

raw <= '{"name": "Asuka", "age": 14, "extra": "ignored"}'
JSON[raw, Pilot]() ]=> pilot
// pilot: @(name <= "Asuka", age <= 14)
// "extra" は無視されます
```

### ルール 2: フィールド欠落はデフォルト値

スキーマに定義されているが JSON にないフィールドは、型のデフォルト値になります。

```taida
Pilot = @(name: Str, age: Int, active: Bool)

raw <= '{"name": "Rei"}'
JSON[raw, Pilot]() ]=> pilot
// pilot: @(name <= "Rei", age <= 0, active <= false)
```

### ルール 3: 型不一致はデフォルト値

JSON フィールドの型がスキーマと合わない場合、デフォルト値になります。

```taida
Pilot = @(name: Str, age: Int)

raw <= '{"name": "Asuka", "age": "not a number"}'
JSON[raw, Pilot]() ]=> pilot
// pilot: @(name <= "Asuka", age <= 0)
```

### ルール 4: null はデフォルト値

JSON の `null` は対応する型のデフォルト値に変換されます。Taida に null はありません。

```taida
Pilot = @(name: Str, age: Int, active: Bool)

raw <= '{"name": "Rei", "age": null, "active": null}'
JSON[raw, Pilot]() ]=> pilot
// pilot: @(name <= "Rei", age <= 0, active <= false)
```

### ルール 5: ネストは再帰的にマッチング

ネストしたオブジェクトは、再帰的にスキーママッチングが適用されます。

```taida
Address = @(city: Str, zip: Str)
Pilot = @(name: Str, address: Address)

raw <= '{"name": "Asuka", "address": {"city": "Tokyo-3"}}'
JSON[raw, Pilot]() ]=> pilot
// pilot.address.city: "Tokyo-3"
// pilot.address.zip: ""（欠落 → デフォルト値）
```

### ルール 6: リストは各要素にスキーマを適用

配列の場合、各要素に個別にスキーママッチングが適用されます。

```taida
Pilot = @(name: Str, syncRate: Int)

raw <= '[{"name": "Rei", "syncRate": 95}, {"name": "Shinji"}]'
JSON[raw, @[Pilot]]() ]=> pilots
// pilots: @[
//   @(name <= "Rei", syncRate <= 95),
//   @(name <= "Shinji", syncRate <= 0)  // syncRate 欠落 → デフォルト値
// ]
```

---

## 出力方向: jsonEncode / jsonPretty

Taida の値を JSON 文字列に変換するには、プリリュード関数 `jsonEncode` と `jsonPretty` を使います。

出力方向（Taida → 外部）は型安全なので、スキーマは不要です。

```taida
pilot <= @(name <= "Asuka", age <= 14, active <= true)

// コンパクトな JSON 文字列
jsonStr <= jsonEncode(pilot)
// '{"name":"Asuka","age":14,"active":true}'

// 整形された JSON 文字列
prettyStr <= jsonPretty(pilot)
// '{
//   "name": "Asuka",
//   "age": 14,
//   "active": true
// }'
```

---

## 実用パターン

### API レスポンスの処理

```taida
Pilot = @(name: Str, age: Int)

fetchPilot id: Int =
  |== error: Error =
    Pilot(name <= "", age <= 0)
  => :Pilot

  response <= httpGet("https://api.nerv.jp/pilots/" + Str[id]() ]=> _)
  response ]=> res
  JSON[res.body, Pilot]() ]=> pilot
  pilot
=> :Pilot
```

### 設定ファイルの読み込み

```taida
Config = @(host: Str, port: Int)

loadConfig path: Str =
  |== error: Error =
    Config(host <= "localhost", port <= 8080)
  => :Config

  contents <= readFile(path)
  contents ]=> text
  JSON[text, Config]() ]=> config
  config
=> :Config
```

### 同じ JSON から複数の側面を抽出

同じ生データから、異なるスキーマで必要な情報だけを取り出せます。

```taida
UserInfo = @(name: Str, email: Str)
BillingInfo = @(plan: Str, amount: Int)

raw <= fetchJson("/api/account/123")

JSON[raw, UserInfo]() ]=> user
JSON[raw, BillingInfo]() ]=> billing

// 同じ JSON から必要な側面だけを抽出します
stdout(user.name + " is on " + billing.plan + " plan")
```

### パース結果の安全な処理

```taida
Pilot = @(name: Str, age: Int)

processPilotData raw: Str =
  result <= JSON[raw, Pilot]()
  | result.hasValue |> stdout("Pilot: " + result.__value.name)
  | _ |> stderr("Failed to parse pilot data")
=> :Void
```

---

## なぜ溶鉄なのか

### 1. null の完全排除

JSON の `null` は Taida に存在しません。スキーママッチングが `null` を自動的にデフォルト値に変換するため、型安全な世界に `null` が侵入することはありません。

### 2. 型の保証

JSON のフィールドの型は実行時まで不明です。`"age"` が文字列かもしれませんし、オブジェクトかもしれません。スキーマを通して鋳造することで、型が保証されます。

### 3. AI にとっての明確さ

AI がコードを生成する際、「この変数は JSON から来たのか、型安全な値なのか」が常に明確です。JSON 型のまま操作できないため、必ずスキーマを経由した型付き値として扱われます。

### 4. IO 型汚染問題への回答

Haskell は「一度 IO に触れたら IO が伝播する」内から外への汚染伝播型です。Taida は「内部に入るには必ず鋳型を通る」外から内への関所型です。方向が逆であり、外部データの侵入を水際で止めます。

---

## まとめ

JSON 溶鉄の原則:

1. **JSON は不透明なプリミティブ型です** -- メソッドなし、直接操作不可、直接 unmold 不可です
2. **`JSON[raw, Schema]()` がただ一つの入口です** -- スキーマ（鋳型）を通さなければ中身に触れません
3. **戻り値は Lax です** -- パース失敗時は `hasValue = false` で、unmold するとデフォルト値が返ります
4. **スキーママッチングの 6 ルールが動作します** -- フィールド一致、欠落はデフォルト値、型不一致はデフォルト値、null はデフォルト値、ネストは再帰、リストは各要素に適用
5. **出力方向は jsonEncode / jsonPretty** -- Taida の型安全な値から JSON 文字列への変換です
6. **JSON パースは `JSON[raw, Schema]()` のみです** -- 他の手段はありません

型安全な世界と外部世界の境界を、溶鉄と鋳型のメタファーで厳格に守ります。

---

# ぶちパック構文

> **PHILOSOPHY.md -- II.** だいじなものはふくろにしまっておきましょう

---

## ぶちパックとは

名前付きフィールドの集合を表現する構造化データ記法です。関連するデータをひとまとめにして名前をつけ、安全に持ち運びます。ふくろにしまう、ということです。

```taida
pilot <= @(name <= "Asuka", age <= 14, active <= true)
```

---

## 基本構文

### 値の作成

```taida
pack <= @(name <= "Asuka", age <= 14, active <= true)
```

### クラスライク/型定義

型を定義するときは `=` を使います:

```taida
Pilot = @(
  name: Str
  age: Int
  active: Bool
)

// インスタンス化
rei <= Pilot(name <= "Rei", age <= 14, active <= true)
```

### フィールドアクセス

```taida
pilot <= @(name <= "Shinji", age <= 14, callSign <= "Ikari")

pilotName <= pilot.name      // "Shinji"
pilotAge <= pilot.age        // 14
pilotCall <= pilot.callSign  // "Ikari"
```

### 存在しないフィールド

存在しないフィールドにアクセスするとコンパイルエラーになります:

```taida
pilot <= @(name <= "Rei")
syncRate <= pilot.syncRate  // コンパイルエラー: フィールド 'syncRate' は存在しません
```

型で定義されたフィールドはデフォルト値を持ちます:

```taida
Pilot = @(name: Str, callSign: Str, age: Int)
rei <= Pilot(name <= "Rei")  // callSign = "", age = 0
```

---

## 即時評価

ぶちパックのフィールドは代入時に即座に評価されます。

```taida
data <= @(
  timestamp <= getCurrentTime(),    // 代入時に即座に評価されます
  computed <= heavyCalculation()    // 代入時に即座に評価されます
)

// この時点で全フィールドは評価済みです
ts <= data.timestamp  // キャッシュされた値を取得します
```

これはスコープベース管理と組み合わさって安全性を保証します。参照先が解放されても、値はコピーされているため問題ありません。

---

## スコープベース管理

全てのぶちパック変数は、定義されたスコープで自動管理されます:

```taida
config <= @(host <= "localhost", port <= 8080)  // モジュールスコープ

processData items =
  temp <= @(processed <= items.length(), timestamp <= now())
  result <= @(count <= temp.processed, time <= temp.timestamp)
  result  // 戻り値として返されます
=> :@(count: Int, time: Str)
// temp は関数終了時に自動解放されます
```

---

## 型の継承（InheritanceDef）

`=>` 演算子で型の継承を表現します:

```taida
Pilot = @(
  name: Str
  age: Int
)

// Pilot を継承します
Pilot => NervStaff = @(
  department: Str
  rank: Int
)

staff <= NervStaff(
  name <= "Ritsuko",
  age <= 30,
  department <= "Science",
  rank <= 2
)

// 親フィールドにもアクセスできます
staff.name        // "Ritsuko"
staff.department  // "Science"
```

### メソッド内でのフィールドアクセス

メソッド内では、親フィールドも子フィールドも区別なく直接アクセスできます。`self` や `super` は不要です:

```taida
Pilot = @(
  name: Str
  age: Int
)

Pilot => NervOfficer = @(
  rank: Int
  intro =
    `I'm ${name}, rank ${Str[rank]() ]=> _}, age ${Str[age]() ]=> _}.`
  => :Str
)

ritsuko <= NervOfficer(name <= "Ritsuko", age <= 30, rank <= 2)
greeting <= ritsuko.intro()  // "I'm Ritsuko, rank 2, age 30."
```

---

## 構造的部分型付け

Taida は構造的部分型付けを採用しています。必要なフィールドがあれば互換と見なされ、余分なフィールドは許容されます。

```taida
// HasName 型は name フィールドだけを要求します
HasName = @(name: Str)

greet person: HasName =
  stdout("Hello, " + person.name)
=> :Void

// Pilot は name フィールドを持つので、HasName として渡せます
pilot <= @(name <= "Asuka", age <= 14, department <= "Unit-02")
greet(pilot)  // "Hello, Asuka"
```

---

## ネスト構造

ぶちパックは直接ネストできます:

```taida
pilot <= @(
  name <= "Rei",
  contact <= @(
    email <= "rei@nerv.jp",
    phone <= "NERV-001"
  )
)

email <= pilot.contact.email  // "rei@nerv.jp"
```

### 型定義でのネスト

```taida
Pilot = @(
  name: Str
  age: Int
  base: @(
    city: Str
    zip: Str
    org: @(
      code: Str
      name: Str
    )
  )
)

pilot <= Pilot(
  name <= "Shinji"
  age <= 14
  base <= @(
    city <= "Tokyo-3"
    zip <= "999-0003"
    org <= @(code <= "NERV", name <= "NERV HQ")
  )
)

orgCode <= pilot.base.org.code  // "NERV"
```

---

## 関数を含むぶちパック

ぶちパック内に関数を定義できます:

```taida
mathUtils <= @(
  add x: Int y: Int = x + y => :Int,
  subtract x: Int y: Int = x - y => :Int,
  PI <= 3.14159
)

result <= mathUtils.add(3, 5)  // 8
pi <= mathUtils.PI             // 3.14159
```

---

## 関数への名前付き引数

```taida
connect host: Str port: Int timeout: Int =
  // 接続処理
=> :Connection

options <= @(host <= "localhost", port <= 8080, timeout <= 5000)
conn <= connect(options)  // パラメータが自動展開されます
```

---

## モールディング型との統合

ぶちパック内にモールディング型を格納できます:

```taida
pilotData <= @(
  name <= "Asuka",
  syncRate <= Div[780, 10]()
)

// ]=> でアンモールディング
pilotData.syncRate ]=> rateValue  // 78
```

モールディング型の詳細は [モールディング型](05_molding.md) を参照してください。

---

## リストリテラル `@[...]`

リストは `@[...]` で表現します:

```taida
numbers <= @[1, 2, 3, 4, 5]
names <= @["Asuka", "Shinji", "Rei"]
empty: @[Int] <= @[]

// 型付きリスト
pilots: @[Pilot] <= @[
  Pilot(name <= "Asuka", age <= 14),
  Pilot(name <= "Shinji", age <= 14)
]
```

---

## JSON からの変換

外部の JSON データをぶちパックに変換するには、`JSON[raw, Schema]()` モールドを使います。詳細は [JSON 溶鉄](03_json.md) を参照してください。

```taida
Pilot = @(name: Str, age: Int)

raw <= '{"name": "Ritsuko", "age": 30}'
JSON[raw, Pilot]() ]=> pilot
// pilot: @(name <= "Ritsuko", age <= 30)
```

---

## まとめ

| 概念 | 構文 |
|------|------|
| 値の作成 | `@(field <= value, ...)` |
| 型定義（TypeDef） | `TypeName = @(field: Type, ...)` |
| インスタンス化 | `TypeName(field <= value, ...)` |
| フィールドアクセス | `pack.fieldName` |
| 型の継承（InheritanceDef） | `Parent => Child = @(...)` |
| ネスト | `@(inner <= @(field <= value))` |
| リストリテラル | `@[elem1, elem2, ...]` |
| JSON 変換 | `JSON[raw, TypeName]() ]=> val` |

---

# モールディング型

> **PHILOSOPHY.md -- III.** カタめたいなら、鋳型を作りましょう

---

## モールディング型とは

型パラメータ化が必要になったら、鋳型（Mold）を作ります。値を鋳型に流し込み（モールディング）、必要なときに取り出します（アンモールディング）。

操作はモールドで、状態チェックはメソッドで -- これが Taida の原則です。

```taida
// 鋳型の定義
Mold[T] => Result[T, P <= :T => :Bool] = @(throw: Error)
// P は述語 :T => :Bool（成功条件を定義）

// 値を流し込みます（_ = true は常に真を返す無名関数）
boxed <= Result[42, _ = true]()

// 取り出します（述語を評価 → 真なので値が返る）
boxed ]=> value  // 42
```

---

## Mold 基底クラス

すべてのモールディング型は `Mold[...]` を継承して定義します。

```taida
// 基本形式
Mold[T] => MyMold[T] = @(
  filling: T // [T]に代入された値が格納される
  solidify _ => :V  // Is-A（何として固まるか）を決める
  unmold _ => :U    // 取り出し値（]=> / <=[ / .unmold()）を決める

  // 追加フィールドを定義（プロパティ、メソッド）
)

// 例
Mold[T] => Result[T, P <= :T => :Bool] = @(throw: Error)
Mold[T] => Lax[T] = @(hasValue: Bool)
```

header 記法:

- `T` = 型変数
- `:Int` = concrete type
- `T <= :Int` = concrete type 制約付き型変数
- `Mold[...]` は親ヘッダー、`Name[...]` は子ヘッダー
- `Mold[...]` の親側は常に 1 slot のまま保つ
- 追加 slot は `Name[...]` または `Parent[...] => Child[...]` の子側にだけ書く
- 子ヘッダーは親ヘッダーを exact prefix として保持し、末尾にだけ slot を追加できる

ヘッダースロットの意味:

- 1つ目のスロットは常に `filling` に対応します
- 2つ目以降のスロットは、`@(...)` 内の「デフォルト値なしフィールド」に宣言順で対応します
- この対応は `T` だけでなく `:Int` のような具象型スロットでも同じです
- つまり、具象型スロットを途中に置いた場合も、そのスロットは1つの束縛先フィールドを消費します

```taida
Mold[:Int] => IntBox = @()
ok_box <= IntBox[1]()
// IntBox["x"]() はコンパイルエラー: 1つ目のスロットは具象型 Int

Mold[:Int] => IntPair[:Int, T] = @(
  second: T
)
pair <= IntPair[1, "x"]()

Mold[:Int] => Broken[:Int, T] = @()
// コンパイルエラー: 2つ目のヘッダースロットに対応するフィールドが無い
```

### solidify / unmold フック

`Mold` は 2 つのフックで挙動が決まります。

| フック | デフォルト | 意味 |
|---|---|---|
| `solidify` | `self` を返す | モールドが何の型として固まるか（Is-A） |
| `unmold` | `filling` を返す | 固まった値から何を取り出すか |

`Name[args]()` の評価は次の順序です。

1. `[]` を `filling` とデフォルト値なしフィールドへ順に束縛
2. `()` をデフォルト値ありフィールドへ束縛
3. `solidify` を評価して値 `V` を得る
4. `Name[args]()` の式型は `V`

演算子の意味:

- `Name[args]() => x`: `solidify` の結果を `x` に代入
- `Name[args]() ]=> x`: `solidify` 結果に対して `unmold` を実行して `x` に代入

### `filling` と引数バインド規則

`filling` は常に 1 つ目の `[]` 位置引数です。2つ目以降は `@(...)` のフィールド定義から自動的に割り当てられます。

| フィールド種別 | 入力 | 省略 |
|---|---|---|
| `filling` | 1つ目の `[]` | 不可 |
| デフォルト値なしフィールド（`filling` 以外） | 2つ目以降の `[]`（宣言順） | 不可 |
| デフォルト値ありフィールド | `()` 名前付き設定 | 可 |

規則違反はコンパイルエラーです（不足・過多・`[]`/`()` の取り違え・未定義オプション）。
また、カスタムモールド定義時に追加型引数の束縛先が無い場合もコンパイルエラーです。
さらに、通常フィールドは `field: Type` または `field <= value` のどちらかが必要です（`field` 単独は不可）。

```taida
Mold[T] => Div[T, U] = @(
  divisor: U
  solidify _ =
    | divisor == 0 |> Lax[T](hasValue <= false)
    | _ |> Lax[T](hasValue <= true)
  => :Lax[T]
)

Div[10, 3]()  // filling=10, divisor=3
Div[10]()     // コンパイルエラー: divisor が不足

Mold[T] => Broken[T, U] = @(
  solidify _ = filling
  => :T
)
// コンパイルエラー: U の束縛先が無い

Mold[:Int] => AlsoBroken[:Int, U] = @()
// コンパイルエラー: 具象型スロットもフィールドスロットを消費するため、U の束縛先が無い

Mold[T] => BrokenField[T] = @(
  count
)
// コンパイルエラー: count は型注釈かデフォルト値が必要
```

### インスタンス化

実際の値を型引数として渡すと、型が自動推論されます:

```taida
pilot <= @(name <= "Kaoru", age <= 14)
pilotBox <= Lax[pilot]()
// pilotBox: Lax[@(name: Str, age: Int)]

number <= 42
numberBox <= Lax[number]()
// numberBox: Lax[Int]
```

### 明示的な型指定

```taida
explicitBox: Lax[Str] <= Lax["test"]()
emptyLax: Lax[Int] <= Div[10, 0]()
```

---

## `[]` と `()` の役割分担

モールドは、`[]` と `()` で引数の役割を明確に分けています。

| | `[]` 位置引数 | `()` 名前付き設定 |
|---|---|---|
| **役割** | 必須引数（何を / 何で） | オプション設定（どうやって） |
| **名前** | なし（位置で区別） | あり（名前で区別） |
| **省略** | 不可 | 可（デフォルト値あり） |
| **順序** | 固定（`[何を, 何で]`） | 任意 |

```taida
// [] = 必須引数: str と old と new がなければ置換不可能
// () = オプション: all のデフォルトは false（最初の1つだけ）
Replace["hello world", "world", "taida"](all <= true)

// [] = 必須引数: list がなければソート不可能
// () = オプション: reverse と by にはデフォルトがある
Sort[@[3, 1, 2]](reverse <= true)
```

---

## 文字列モールド

文字列の変換・加工はモールドで行います。状態チェック（`length()`, `contains()`, `startsWith()` 等）はメソッドとして存在します。

| モールド | `[]` 必須 | `()` オプション | 戻り値 | 説明 |
|---------|----------|----------------|--------|------|
| `Upper[str]()` | str | - | Str | 大文字変換 |
| `Lower[str]()` | str | - | Str | 小文字変換 |
| `Trim[str]()` | str | start, end | Str | 空白除去 |
| `Split[str, delim]()` | str, delim | - | @[Str] | 分割 |
| `Replace[str, old, new]()` | str, old, new | all | Str | 置換 |
| `Slice[str]()` | str | start, end | Str | 範囲抽出 |
| `CharAt[str, idx]()` | str, idx | - | Lax[Str] | 指定位置の文字 |
| `Repeat[str, n]()` | str, n | - | Str | 繰り返し |
| `Reverse[str]()` | str | - | Str | 逆順 |
| `Pad[str, len]()` | str, len | side, char | Str | パディング |

### 使用例

```taida
Upper["hello"]()                              // "HELLO"
Lower["HELLO"]()                              // "hello"
Trim["  hello  "]()                           // "hello"
Trim["  hello  "](end <= false)               // "hello  "（先頭のみ）
Split["a,b,c", ","]()                         // @["a", "b", "c"]
Replace["hello world", "o", "0"]()            // "hell0 world"（最初の1つ）
Replace["hello world", "o", "0"](all <= true) // "hell0 w0rld"（全部）
Slice["hello"](start <= 1, end <= 3)          // "el"
CharAt["hello", 0]() ]=> ch                   // ch: "h" (Lax[Str]を返す)
Repeat["ha", 3]()                             // "hahaha"
Reverse["hello"]()                            // "olleh"
Pad["42", 5](side <= "start", char <= "0")    // "00042"
```

---

## 数値モールド

数値の変換・加工はモールドで行います。状態チェック（`isNaN()`, `isZero()`, `isPositive()` 等）はメソッドとして存在します。

| モールド | `[]` 必須 | `()` オプション | 戻り値 | 説明 |
|---------|----------|----------------|--------|------|
| `ToFixed[num, digits]()` | num, digits | - | Str | 小数点固定文字列 |
| `Abs[num]()` | num | - | Num | 絶対値 |
| `Floor[num]()` | num | - | Int | 切り捨て |
| `Ceil[num]()` | num | - | Int | 切り上げ |
| `Round[num]()` | num | - | Int | 四捨五入 |
| `Truncate[num]()` | num | - | Int | 0方向切り捨て |
| `Clamp[num, min, max]()` | num, min, max | - | Num | 範囲制限 |
| `BitAnd[a, b]()` | a, b | - | Int | ビットAND |
| `BitOr[a, b]()` | a, b | - | Int | ビットOR |
| `BitXor[a, b]()` | a, b | - | Int | ビットXOR |
| `BitNot[x]()` | x | - | Int | ビットNOT |
| `ShiftL[x, n]()` | x, n | - | Lax[Int] | 左シフト（`n` が 0..63 のとき成功） |
| `ShiftR[x, n]()` | x, n | - | Lax[Int] | 算術右シフト（`n` が 0..63 のとき成功） |
| `ShiftRU[x, n]()` | x, n | - | Lax[Int] | 論理右シフト（`n` が 0..63 のとき成功） |
| `ToRadix[int, base]()` | int, base | - | Lax[Str] | 基数変換（`base` は 2..36） |
| `Int[str, base]()` | str, base | - | Lax[Int] | 指定基数で文字列を整数化（`base` は 2..36） |

### 使用例

```taida
ToFixed[3.14159, 2]()         // "3.14"
Abs[-5]()                     // 5
Floor[3.7]()                  // 3
Ceil[3.2]()                   // 4
Round[3.5]()                  // 4
Truncate[-3.7]()              // -3
Clamp[15, 0, 10]()            // 10
```

> ビット演算用の新しい演算子は追加しません。`Bit*` / `Shift*` / `ToRadix` / `Int[str, base]` をモールドで使います。

### バイト列・Unicode 変換モールド

| モールド | `[]` 必須 | `()` オプション | 戻り値 | 説明 |
|---------|----------|----------------|--------|------|
| `UInt8[x]()` | x | - | Lax[Int] | `0..255` への範囲制約付き変換 |
| `Bytes[x]()` | x | `fill <= Int` | Lax[Bytes] | `Int/Str/@[Int]/Bytes` から Bytes へ変換 |
| `ByteSet[bytes, idx, value]()` | bytes, idx, value | - | Lax[Bytes] | 指定位置を更新した新しい Bytes を返す |
| `BytesToList[bytes]()` | bytes | - | @[Int] | Bytes を整数リストへ展開 |
| `Char[x]()` | x | - | Lax[Str] | `Int` または `Str` から1文字へ変換 |
| `CodePoint[str]()` | str | - | Lax[Int] | 1文字 `Str` からコードポイント取得 |
| `Utf8Encode[str]()` | str | - | Lax[Bytes] | UTF-8 バイト列へ変換 |
| `Utf8Decode[bytes]()` | bytes | - | Lax[Str] | UTF-8 バイト列を文字列へ復元（不正列は failure） |

```taida
Bytes[4](fill <= 65) ]=> b        // Bytes[@[65, 65, 65, 65]]
ByteSet[b, 1, 66]() ]=> b2        // Bytes[@[65, 66, 65, 65]]
BytesToList[b2]()                  // @[65, 66, 65, 65]

Char[65]() ]=> c                   // "A"
CodePoint["A"]() ]=> cp            // 65

Utf8Encode["pong"]() ]=> raw       // Bytes[@[112,111,110,103]]
Utf8Decode[raw]() ]=> text         // "pong"
```

---

## リストモールド

リストの操作はモールドで行います。状態チェック（`length()`, `isEmpty()`, `contains()`, `any()`, `all()`, `none()` 等）と安全アクセス（`get()`, `first()`, `last()`, `max()`, `min()`）はメソッドとして存在します。

| モールド | `[]` 必須 | `()` オプション | 戻り値 | 説明 |
|---------|----------|----------------|--------|------|
| `Reverse[list]()` | list | - | @[T] | 逆順 |
| `Concat[list, other]()` | list, other | - | @[T] | 結合 |
| `Append[list, val]()` | list, val | - | @[T] | 末尾追加 |
| `Prepend[list, val]()` | list, val | - | @[T] | 先頭追加 |
| `Join[list, sep]()` | list, sep | - | Str | 文字列結合 |
| `Sum[list]()` | list | - | Num | 合計 |
| `Sort[list]()` | list | reverse, by | @[T] | ソート |
| `Unique[list]()` | list | by | @[T] | 重複除去 |
| `Flatten[list]()` | list | - | @[U] | フラット化 |
| `Find[list, fn]()` | list, fn | - | Lax[T] | 条件検索 |
| `FindIndex[list, fn]()` | list, fn | - | Int | 条件位置検索 |
| `Count[list, fn]()` | list, fn | - | Int | 条件カウント |
| `Take[list, n]()` | list, n | - | @[T] | 先頭n個 |
| `Drop[list, n]()` | list, n | - | @[T] | 先頭n個スキップ |
| `TakeWhile[list, fn]()` | list, fn | - | @[T] | 条件満たす間取得 |
| `DropWhile[list, fn]()` | list, fn | - | @[T] | 条件満たす間スキップ |
| `Zip[list, other]()` | list, other | - | @[BuchiPack] | ペア化 |
| `Enumerate[list]()` | list | - | @[BuchiPack] | インデックス付与 |

### 高階関数モールド（HOF）

| モールド | `[]` 必須 | `()` オプション | 戻り値 | 説明 |
|---------|----------|----------------|--------|------|
| `Filter[list, fn]()` | list, fn | - | @[T] | 条件フィルタ |
| `Map[list, fn]()` | list, fn | - | @[U] | 変換 |
| `Fold[list, init, fn]()` | list, init, fn | - | A | 左畳み込み |
| `Foldr[list, init, fn]()` | list, init, fn | - | A | 右畳み込み |

### 統合モールドの使い方

Sort と Unique はオプション設定で挙動を制御できます:

```taida
// Sort: デフォルトは昇順
Sort[@[3, 1, 2]]()                                // @[1, 2, 3]
Sort[@[3, 1, 2]](reverse <= true)                 // @[3, 2, 1]
Sort[pilots](by <= _ p = p.syncRate)               // キー関数ソート
Sort[pilots](by <= _ p = p.name, reverse <= true)  // キー関数降順

// Unique: デフォルトは値の等価比較
Unique[@[1, 2, 2, 3, 3]]()                        // @[1, 2, 3]
Unique[items](by <= _ x = x.id)                    // idフィールドで重複判定
```

### 使用例

```taida
// パイロットデータの処理
pilots <= @[
  @(name <= "Shinji", syncRate <= 95, active <= true),
  @(name <= "Asuka", syncRate <= 41, active <= true),
  @(name <= "Rei", syncRate <= 65, active <= false)
]

// フィルタ → マップ
pilots => Filter[_, _ p = p.active]() => Map[_, _ p = p.name]() => activeNames
// activeNames: @["Shinji", "Asuka"]

// 集約
Fold[orders, 0, _ total order = total + (order.quantity * order.price)]() ]=> totalRevenue

// ソートとフィルタの組み合わせ
pilots => Filter[_, _ p = p.active]() => Sort[_](by <= _ p = p.syncRate, reverse <= true) => topPilots
```

---

## 演算モールド: Div / Mod

除算と剰余は Div / Mod モールドで行います。`/` と `%` 演算子は Taida にはありません。結果は Lax で返ります。

```taida
// 除算
Div[10, 3]() ]=> quotient    // 3
Div[10, 0]() ]=> quotient    // 0（ゼロ除算: デフォルト値）
Div[10, 0]().hasValue         // false

// 剰余
Mod[10, 3]() ]=> remainder   // 1
Mod[10, 0]() ]=> remainder   // 0（ゼロ除算: デフォルト値）
Mod[10, 0]().hasValue         // false
```

ゼロ除算はエラーではなく、`Lax(hasValue=false)` が返ります。unmold するとデフォルト値（Int なら 0、Float なら 0.0）が返ります。

---

## 条件モールド: If

`If[condition, then_value, else_value]()` は 2 分岐の条件式をモールドとして表現します。

```taida
// 基本的な条件分岐
stdout(If[x > 0, "positive", "negative"]())

// パイプラインでの使用（clamp パターン）
150 => If[_ > 100, 100, _]() => clamped   // 100
50 => If[_ > 100, 100, _]() => clamped    // 50
```

特徴:

- **Short-circuit**: 非選択 branch は評価しません。`If[true, "ok", throw "error"]()` でエラーは発生しません
- **パイプライン対応**: `_` で前段の値を参照できます（`_ > 3` のようにネストした `_` も可能）
- **ネスト可能**: `If[cond, If[cond2, a, b](), c]()` のように入れ子にできます
- **`| |>` との使い分け**: `If` は 2 分岐向き、`| |>` は複数分岐向き

```taida
// ネスト
stdout(If[true, If[false, 1, 2](), 3]())   // 2

// パイプラインで比較
5 => If[_ > 3, "big", "small"]() => result  // "big"
```

---

## 型比較モールド: TypeIs / TypeExtends

型の比較をモールドで行います。

### TypeIs -- 実行時の型チェック

`TypeIs[value, :TypeName]()` は値の実行時の型が指定した型と一致するかを返します。

```taida
stdout(TypeIs[42, :Int]())        // true
stdout(TypeIs["hello", :Int]())   // false
stdout(TypeIs["hello", :Str]())   // true
stdout(TypeIs[true, :Bool]())     // true
stdout(TypeIs[3.14, :Float]())    // true
stdout(TypeIs[42, :Num]())        // true（Int は Num の一種）
```

Enum variant の判定もできます:

```taida
Enum => Status = :Ok :Fail :Retry
x <= Status:Ok()
stdout(TypeIs[x, Status:Ok]())    // true
stdout(TypeIs[x, Status:Fail]())  // false
```

### TypeExtends -- 型の継承関係チェック

`TypeExtends[:TypeA, :TypeB]()` は TypeA が TypeB と同じか、TypeB のサブタイプかを返します。

```taida
stdout(TypeExtends[:Int, :Num]())     // true（Int は Num のサブタイプ）
stdout(TypeExtends[:Str, :Int]())     // false（Str は Int と無関係）

Animal = @(name: Str)
Animal => Dog = @(breed: Str)
stdout(TypeExtends[:Dog, :Animal]())  // true（Dog は Animal を継承）
stdout(TypeExtends[:Animal, :Dog]())  // false（逆方向は不可）
```

対応する型リテラル（B11 スコープ）:

- プリミティブ: `:Int`, `:Float`, `:Num`, `:Bool`, `:Str`, `:Bytes`, `:Error`
- ユーザー定義型: `:TypeName`
- Enum variant: `EnumName:Variant`（TypeIs のみ）

B11 スコープ外: inline BuchiPack 型リテラル、関数型リテラル、汎用 generic literal

---

## 型変換モールド

値の型変換は型変換モールドで行います。結果は Lax で返ります。
これは `solidify` オーバーライドで表現される仕様であり、型変換モールド専用のコンパイラ特別扱いは不要です。

| モールド | 説明 | 成功例 | 失敗例 |
|---------|------|--------|--------|
| `Int[x]()` | 整数に変換 | `Int["123"]()` → 123 | `Int["abc"]()` → 0 |
| `Int[str, base]()` | 指定基数で整数に変換 | `Int["ff", 16]()` → 255 | `Int["gg", 16]()` → 0 |
| `Float[x]()` | 浮動小数点に変換 | `Float["3.14"]()` → 3.14 | `Float["abc"]()` → 0.0 |
| `Str[x]()` | 文字列に変換 | `Str[42]()` → "42" | - |
| `Bool[x]()` | 真偽値に変換 | `Bool[1]()` → true | `Bool[0]()` → false |

```taida
// 文字列 → 整数
Int["123"]() ]=> num     // 123
Int["abc"]() ]=> num     // 0（変換失敗: デフォルト値）
Int["+5"]() ]=> num      // 5（符号付き文字列も受理）

// 文字列 → 整数（基数指定）
Int["ff", 16]() ]=> hex  // 255
Int["1010", 2]() ]=> bin // 10

// 文字列 → 浮動小数点
Float["3.14"]() ]=> val  // 3.14
Float["abc"]() ]=> val   // 0.0（変換失敗: デフォルト値）

// 数値 → 文字列
Str[42]() ]=> text       // "42"

// 値 → 真偽値
Bool[1]() ]=> flag       // true
Bool[0]() ]=> flag       // false
```

---

## Lax[T] -- 必ず値を返すモールド型

> **PHILOSOPHY.md -- I.** 深く考えずに適当にぶちこんでけ

Lax[T] は「操作が失敗しても必ず値を返す」モールド型です。失敗時は型 T のデフォルト値にフォールバックします。

### 概念

```taida
Mold[T] => Lax[T] = @(hasValue: Bool)

// 成功: hasValue = true, unmold で値が取り出せます
// 失敗: hasValue = false, unmold でデフォルト値が返ります
```

### IS-A Lax のモールド

| 操作 | 説明 |
|------|------|
| `Div[x, y]()` | 除算（ゼロ除算で hasValue=false） |
| `Mod[x, y]()` | 剰余（ゼロ除算で hasValue=false） |
| `Int[x]()` / `Float[x]()` / `Str[x]()` / `Bool[x]()` | 型変換（変換失敗で hasValue=false） |
| `JSON[raw, Schema]()` | JSON パース（パース失敗で hasValue=false） |
| `.get(idx)` | インデックスアクセス（範囲外で hasValue=false） |
| `.first()` / `.last()` | 先頭/末尾アクセス（空リストで hasValue=false） |
| `.max()` / `.min()` | 最大/最小値（空リストで hasValue=false） |
| `Find[list, fn]()` | 条件検索（見つからないとき hasValue=false） |

### Lax メソッド

| メソッド | 説明 | 戻り値 |
|---------|------|--------|
| `hasValue` | 値を持つかどうか（フィールドアクセス） | Bool |
| `isEmpty()` | 値を持たないかどうか | Bool |
| `getOrDefault(default)` | 値があれば値を、なければ指定したデフォルト値を返します | T |
| `map(fn)` | 値があれば fn を適用した新しい Lax を返します | Lax[U] |
| `flatMap(fn)` | 値があれば fn を適用し、fn が返す Lax をそのまま返します | Lax[U] |
| `toString()` | 文字列表現を返します | Str |
| `unmold()` | 値を取り出します（失敗時はデフォルト値） | T |

```taida
lax <= Div[10, 3]()
lax.hasValue              // true
lax.isEmpty()             // false
lax.getOrDefault(99)      // 3
lax.map(_ x = x * 2) ]=> doubled  // 6
lax.toString()            // "Lax(3)"

empty <= Div[10, 0]()
empty.hasValue            // false
empty.isEmpty()           // true
empty.getOrDefault(99)    // 99
empty.map(_ x = x * 2) ]=> doubled  // 0（空のまま）
empty.toString()          // "Lax(default: 0)"
```

---

## Result[T, P] -- 述語付き操作モールド

成功/失敗を**述語（P: :T => :Bool）**で判定するモールド型です。`]=>` でアンモールディングすると述語が評価され、成功なら値 T を返し、失敗なら throw が発動します。

```taida
Mold[T] => Result[T, P <= :T => :Bool] = @(throw: Error)
// P は :T => :Bool（成功条件を定義する述語）

// 使用例
Error => ValidationError = @(field: Str)

// true = 常に真の述語（常に成功）
ok <= Result[42, _ = true]()
ok ]=> value  // 42（述語 true → 成功）

// false = 常に偽の述語（常に失敗）
err <= Result[0, _ = false](throw <= ValidationError(type <= "ValidationError", message <= "fail", field <= "age"))
err ]=> value  // throw が発動（エラー天井で捕捉可能）

// ラムダ述語によるバリデーション
age <= 15
checked <= Result[age, _ x = x >= 18](throw <= ValidationError(type <= "ValidationError", message <= "Must be 18+", field <= "age"))
checked ]=> value  // age=15 → 述語が false → throw 発動
```

### => と ]=> の違い

```taida
Result[x, pred](throw <= err) => r   // r: Result[T, P]（default solidify = self）
Result[x, pred](throw <= err) ]=> r  // r: T（unmold 時に述語を評価 → 真なら値、偽なら throw）
```

### 関数の戻り値として

```taida
validateAge age: Int =
  Result[age, _ x = x >= 18](throw <= ValidationError(type <= "ValidationError", message <= "Must be 18+", field <= "age"))
=> :Result[Int, _]  // _ = 述語の型を推論
```

### モナディック操作はメソッドで

Result, Lax の `map`, `flatMap`, `mapError` はメソッドとして残っています。これらはモナディック操作であり、型ごとに固有の振る舞いを持つためです。

---

## Gorillax[T] -- 覚悟のモールド型

Lax[T] が「失敗してもデフォルト値で続行」なのに対し、Gorillax[T] は「失敗したらゴリラがプログラムを止める」モールド型です。安全を保証しない外部操作（npm パッケージの利用など）に使います。

```taida
Mold[T] => Gorillax[T] = @(hasValue: Bool)

// Lax: 失敗 → デフォルト値（プログラム続行）
// Gorillax: 失敗 → ゴリラ（プログラム終了）
```

### 直接生成

```taida
Gorillax[42]() => g         // g: Gorillax[Int], hasValue = true
g ]=> value                  // 42（成功: 値が取り出せます）
```

### Cage[T, F] -- Molten 専用の操作檻

Cage は Molten（溶鉄）に対して操作を実行し、結果を Gorillax で包むモールドです。Cage 内でのみ溶鉄への操作が許可されます。

**Cage は Molten 専用です。** 第一引数は Molten 型の値のみ受け付けます。Taida の型安全な値を Cage に渡すことはできません。

```taida
Cage[molten, function]() => gorillax  // gorillax: Gorillax[U]
// molten: Molten（溶鉄のみ）
// function: :Molten => :U（溶鉄に対する操作）
```

### 使用例

```taida
>>> npm:lodash => @(lodash)  // lodash: Molten（溶鉄状態、直接使用不可）

items: @[Int] <= @[1, 2, 3, 4, 5]

// Cage 内でのみ Molten への操作が許可されます
Cage[lodash, _ lo = lo.sum(items)] => rilax  // rilax: Gorillax[Int]

// 成功時: 値が取り出せます
rilax ]=> total              // total = 15

// 失敗時: ゴリラがプログラムを停止させます
// rilax ]=> total           // ><（ゴリラ出現）

// Taida の値は Cage に渡せません
// Cage[42, _ x = x + 1]()  // コンパイルエラー: Cage requires Molten type
```

### JSON と Molten の関係

JSON は概念的に Molten の一種です。どちらも外部由来の不透明な値であり、型安全な世界に持ち込むには鋳型を通す必要があります。

ただし JSON には専用のモールド `JSON[raw, Schema]()` があり、通常はこちらを使います。JSON を Cage に渡すことも可能ですが、Cage では JavaScript のメソッド呼び出しが行われるため、JSON の処理には適していません。

| 状況 | 使うべきもの |
|------|------------|
| JSON 文字列を型付き値に変換 | `JSON[raw, Schema]()` |
| npm パッケージの Molten を操作 | `Cage[molten, fn]()` |
| JSON を Cage に渡す | 可能だが非推奨（`JSON[raw, Schema]()` を使うこと） |

### .relax() -- RelaxedGorillax[T]

`.relax()` を呼ぶと、ゴリラが `RelaxedGorillaEscaped` エラーに変わります。このエラーは `|==` エラー天井で捕捉可能です。

```taida
rilax.relax() => relaxed     // relaxed: RelaxedGorillax[Int]

|== error: RelaxedGorillaEscaped =
  | _ |> 0
=> :Int

relaxed ]=> value            // 失敗時: throw（|== で捕捉）
```

### Gorillax メソッド

| メソッド | 説明 | 戻り値 |
|---------|------|--------|
| `hasValue` | 値を持つかどうか（フィールドアクセス） | Bool |
| `isEmpty()` | 値を持たないかどうか | Bool |
| `relax()` | RelaxedGorillax に変換（throwable にする） | RelaxedGorillax[T] |
| `toString()` | 文字列表現を返します | Str |

### RelaxedGorillax メソッド

| メソッド | 説明 | 戻り値 |
|---------|------|--------|
| `hasValue` | 値を持つかどうか（フィールドアクセス） | Bool |
| `isEmpty()` | 値を持たないかどうか | Bool |
| `toString()` | 文字列表現を返します | Str |

### 使い分け: Lax vs Gorillax

| 状況 | 使うべきもの |
|------|------------|
| ゼロ除算、範囲外アクセス、型変換 | Lax（デフォルト値で安全に続行） |
| 外部パッケージの Molten 操作（npm 等） | Cage → Gorillax（失敗は致命的） |
| 外部操作の失敗をキャッチしたい | `.relax()` → RelaxedGorillax |

---

## JS 補助モールド（JS バックエンド専用）

npm パッケージから得られる Molten 値に対して、JavaScript 固有の操作を行うモールドです。これらは全て **Molten を受け取り Molten を返します**（溶鉄から溶鉄）。最終的に Taida の型世界に持ち込むには Cage を経由します。

**重要: これらのモールドは JS トランスパイラでのみ動作します。** インタプリタおよび Native バックエンドでは「JS バックエンド専用です」コンパイルエラーになります。ポータブルなコード（複数バックエンドで動作させるコード）では使わないでください。

**3バックエンド・パリティの対象外です。** JSNew, JSSet, JSBind, JSSpread は JS interop 層であり、JS トランスパイラ固有の機能です。インタプリタや Native バックエンドに同等の実装は提供されません。

### JSNew[constructor, args] -- コンストラクタ呼び出し

JavaScript の `new` キーワードに相当する操作です。Molten のコンストラクタを呼び出し、新しい Molten インスタンスを返します。

```taida
>>> npm:express => @(express)

// new express.Router() に相当
JSNew[express.Router, @()]() => router  // router: Molten
```

| `[]` 必須 | 説明 |
|----------|------|
| `constructor` | Molten のコンストラクタ関数 |
| `args` | コンストラクタ引数（ぶちパック） |

**戻り値**: `Molten`

### JSSet[obj, key, value] -- プロパティ設定

Molten オブジェクトのプロパティに値を設定します。JavaScript の `obj[key] = value` に相当する破壊的操作です。**同一の Molten 参照を返します**（JavaScript の破壊的代入のセマンティクスがそのまま適用されます）。

```taida
>>> npm:express => @(express)

// Cage 内で Molten の関数を呼び出し、JS 補助モールドで操作します
Cage[express, _ e = e()]() ]=> app    // app: Molten（express() の結果）
JSSet[app, "port", 3000]() => app2    // app2: Molten（app と同一参照）
```

| `[]` 必須 | 説明 |
|----------|------|
| `obj` | 対象の Molten オブジェクト |
| `key` | プロパティ名（Str） |
| `value` | 設定する値（Any） |

**戻り値**: `Molten`（同一参照。JavaScript の破壊的代入に相当）

### JSBind[obj, method] -- this バインド

Molten オブジェクトのメソッドに `this` をバインドします。JavaScript の `obj.method.bind(obj)` に相当します。

```taida
>>> npm:someLib => @(lib)

handler <= JSBind[lib, "handleRequest"]() // handler: Molten
```

| `[]` 必須 | 説明 |
|----------|------|
| `obj` | 対象の Molten オブジェクト |
| `method` | メソッド名（Str） |

**戻り値**: `Molten`

### JSSpread[target, source] -- スプレッド展開

Molten オブジェクトにスプレッド展開でプロパティをマージします。JavaScript の `{...target, ...source}` に相当します。

```taida
>>> npm:config => @(defaults)

overrides <= @(port <= 8080, debug <= true)
merged <= JSSpread[defaults, overrides]()  // merged: Molten
```

| `[]` 必須 | 説明 |
|----------|------|
| `target` | マージ先の Molten オブジェクト |
| `source` | マージ元の値（Any） |

**戻り値**: `Molten`

### 型の流れ: npm から値の取り出しまで

npm パッケージを使う際の典型的な型の流れは以下の通りです:

```
npm import (Molten) → JSNew 等 (Molten→Molten) → Cage (Molten→Gorillax) → ]=> (値)
```

```taida
>>> npm:express => @(express)           // express: Molten

// Cage 内で Molten の関数を呼び出します
Cage[express, _ e = e()]() ]=> app       // app: Molten（express() の結果）
JSNew[express.Router, @()]() => router   // router: Molten（new 呼び出し）

// Cage で Molten の操作を実行し、Gorillax で受け取ります
Cage[app, _ a = a.get("/")]() => result  // result: Gorillax[Molten]
result ]=> handler                       // handler: Molten（またはゴリラ）
```

Molten への直接的な関数呼び出しは Cage 内でのみ許可されます。JS 補助モールド（JSNew, JSSet, JSBind, JSSpread）は Taida のモールド構文なので Cage 外でも使用可能ですが、Molten のメソッド呼び出しや関数呼び出しは必ず Cage を経由してください。

---

## アンモールディング

モールディング型から値を取り出すには3つの方法があります。
`Name[args]()` に対する `]=>` / `<=[` / `.unmold()` は、`solidify` 済みの値に対して実行されます。

### `]=>` 演算子

```taida
lax <= Div[10, 3]()
lax ]=> value  // value = 3
```

### `<=[` 演算子（逆向き）

```taida
value <=[ lax  // value = 3
```

### `.unmold()` メソッド

```taida
value <= lax.unmold()  // value = 3
```

### 使い分け

```taida
// 代入したい場合は演算子を使います
lax ]=> value

// 式の中で使いたい場合はメソッドを使います
result <= lax.unmold() + 10
```

---

## パイプラインでのモールド使用

パイプライン `=>` の中では、`_` が前ステップの値を受け取ります。モールドの `[]` 内でも使用可能です。

### 正方向パイプライン

```taida
"  Hello, World!  " => Trim[_]() => Upper[_]() => Replace[_, ",", ""]() => Split[_, " "]() => result
```

> **注意**: `<=` のチェーンによる逆方向パイプラインは現在サポートされていません。順方向パイプライン `=>` または中間変数を使用してください。

### リストのパイプライン

```taida
numbers => Filter[_, _ x = Mod[x, 2]() ]=> r; r == 0]() => Map[_, _ x = x * 2]() => result
```

### 直接呼び出し

```taida
Filter[list, isEven]() ]=> result
```

### 数値のパイプライン

```taida
value => Abs[_]() => Clamp[_, 0, 100]() => Round[_]() => result
```

---

## ユーザー定義モールド

`Mold[T]` を継承して独自のモールディング型を定義できます。

```taida
Mold[:@(x: Int, y: Int)] => Container = @(
  count: Int
  name: Str
  unmold _ =
    filling
  => @(x: Int, y: Int) // unmoldのカスタム定義（_ = :T）
)

data <= @(x <= 1, y <= 2)
box <= Container[data, 1, "my-container"]()
box ]=> extracted  // @(x <= 1, y <= 2)
box.count          // 1
box.name           // "my-container"
```

### solidify オーバーライド（自型以外に固める）

`solidify` をオーバーライドすると、カスタムモールドでも自型以外を返せます。

```taida
Mold[T] => TryInt[T] = @(
  solidify _ =
    Int[filling]()
  => :Lax[Int]
)

TryInt["123"]() => boxed   // boxed: Lax[Int]
TryInt["123"]() ]=> value  // value: Int
```

### メソッドの定義

モールディング型内にメソッドを定義できます:

```taida
Mold[T] => Container[T] = @(
  label: Str <= ""

  describe =
    `Container(${label}): ${unmold().toString()}`
  => :Str

  mapValue fn: T => :U =
    Container[fn(unmold())](label <= label)
  => :Container[U]
)
```

---

## まとめ

| 概念 | 構文 |
|------|------|
| 定義 | `Mold[T] => TypeName[T] = @(...)` |
| 中身 | `filling: T` |
| Is-A 決定 | `solidify _ => :V`（省略時: self） |
| 取り出し定義 | `unmold _ => :U`（省略時: filling） |
| インスタンス化 | `Name[a, b, ...](opt <= ...)`（`a` は filling、`b...` はデフォルト値なしフィールド宣言順） |
| アンモールディング | `]=>`, `<=[`, `.unmold()` |
| `[]` 位置引数 | 必須引数（何を / 何で） |
| `()` 名前付き設定 | オプション設定（どうやって） |
| 文字列モールド | Upper, Lower, Trim, Split, Replace, Slice, CharAt, Repeat, Reverse, Pad |
| 数値モールド | ToFixed, Abs, Floor, Ceil, Round, Truncate, Clamp |
| リストモールド | Reverse, Concat, Append, Prepend, Join, Sum, Sort, Unique, Flatten, Find, FindIndex, Count, Take, Drop, TakeWhile, DropWhile, Zip, Enumerate |
| HOF モールド | Filter, Map, Fold, Foldr |
| 演算モールド | Div[x, y]() → Lax, Mod[x, y]() → Lax |
| 型変換モールド | Int[x]() → Lax, Float[x]() → Lax, Str[x]() → Lax, Bool[x]() → Lax |
| Lax[T] | 必ず値を返すモールド型。Div/Mod/get/first/last/JSON の戻り値 |
| Result[T, P] | 述語付き操作モールド（P: :T => :Bool で成功/失敗を判定） |
| Gorillax[T] | 覚悟のモールド型。unmold 失敗時はゴリラ（プログラム終了） |
| RelaxedGorillax[T] | `.relax()` で生成。unmold 失敗時は RelaxedGorillaEscaped を throw |
| Cage[T, F] | Molten 専用の操作檻。`F(Molten)` を実行し Gorillax[U] を返す |
| JSNew[constructor, args] | JS の `new` 呼び出し。Molten→Molten（JS バックエンド専用） |
| JSSet[obj, key, value] | JS プロパティ設定。Molten→Molten（JS バックエンド専用） |
| JSBind[obj, method] | JS の `this` バインド。Molten→Molten（JS バックエンド専用） |
| JSSpread[target, source] | JS スプレッド展開。Molten→Molten（JS バックエンド専用） |
| パイプライン | `=>` / `<=` の中で `_` が前ステップの値を受け取る |

---

# リスト操作

> **PHILOSOPHY.md -- I.** 深く考えずに適当にぶちこんでけ

Taida のリスト `@[...]` は、同じ型の値を並べたシンプルなデータ構造です。状態の確認はメソッドで、値の操作はモールドで行います。

---

## リストリテラル `@[...]`

リストは `@[...]` で作成します。

```taida
numbers <= @[1, 2, 3, 4, 5]
names <= @["Asuka", "Rei", "Shinji"]
empty: @[Int] <= @[]
nested <= @[@[1, 2], @[3, 4]]
```

リストの要素はすべて同じ型でなければなりません。型はリテラルから自動推論されます。

```taida
// OK: 全て Int
@[1, 2, 3]

// OK: 全て Str
@["hello", "world"]

// NG: 混在はコンパイルエラーになります
// @[1, "hello"]
```

---

## 状態チェックメソッド

リストの状態を問い合わせるメソッドです。リスト自体は変更しません。

### length

要素数を返します。

```taida
@[1, 2, 3].length()           // 3
empty: @[Int] <= @[]
empty.length()                 // 0
```

### isEmpty

リストが空かどうかを返します。

```taida
empty: @[Int] <= @[]
empty.isEmpty()                // true
@[1, 2].isEmpty()              // false
```

### contains

指定した要素がリストに含まれているかを返します。

```taida
@[1, 2, 3].contains(2)   // true
@[1, 2, 3].contains(99)  // false
```

### indexOf

指定した要素の最初の出現位置を返します。見つからない場合は -1 を返します。

```taida
@[10, 20, 30, 20].indexOf(20)   // 1
@[10, 20, 30].indexOf(99)       // -1
```

### lastIndexOf

指定した要素の最後の出現位置を返します。見つからない場合は -1 を返します。

```taida
@[1, 2, 1, 2].lastIndexOf(1)   // 2
@[1, 2, 3].lastIndexOf(99)     // -1
```

---

## 安全アクセス -- Lax を返すメソッド

`first()`、`last()`、`get()`、`max()`、`min()` はすべて Lax を返します。値が存在しない場合でもプログラムは停止せず、デフォルト値にフォールバックします。

> **PHILOSOPHY.md -- I.** 深く考えずに適当にぶちこんでけ

### first / last

```taida
@[10, 20, 30].first() ]=> val   // 10
@[10, 20, 30].last() ]=> val    // 30

// 空リストでも安全です
empty: @[Int] <= @[]
empty.first() ]=> val            // 0 (Int のデフォルト値)
empty.last() ]=> val             // 0
```

### get

インデックスを指定して要素にアクセスします。

```taida
items <= @[10, 20, 30]
items.get(0) ]=> val    // 10
items.get(1) ]=> val    // 20
items.get(100) ]=> val  // 0 (範囲外: デフォルト値)
```

### max / min

最大値・最小値を返します。

```taida
@[3, 1, 4, 1, 5].max() ]=> val   // 5
@[3, 1, 4, 1, 5].min() ]=> val   // 1

// 空リストでも安全です
empty: @[Int] <= @[]
empty.max() ]=> val                // 0
empty.min() ]=> val                // 0
```

### hasValue で成功/失敗を判別する

Lax の `hasValue` フィールドを使うと、値が実際に存在するかどうかを判別できます。

```taida
scores <= @[85, 92, 78]

scores.get(0).hasValue    // true
scores.get(100).hasValue  // false

empty: @[Int] <= @[]
empty.first().hasValue         // false
@[1, 2].first().hasValue       // true
```

### getOrDefault でカスタムデフォルト値を指定する

```taida
@[10, 20, 30].get(100).getOrDefault(99)  // 99
empty: @[Int] <= @[]
empty.max().getOrDefault(-1)             // -1
```

---

## 述語メソッド -- any, all, none

リスト全体に対する条件判定です。Bool を返します。

### any

いずれかの要素が条件を満たすかを返します。

```taida
@[1, 2, 3, 4, 5].any(_ x = x > 3)    // true
@[1, 2, 3].any(_ x = x > 10)          // false
```

### all

すべての要素が条件を満たすかを返します。

```taida
@[2, 4, 6].all(_ x = Mod[x, 2]() ]=> r; r == 0)  // true
@[1, 2, 3].all(_ x = x > 0)                        // true
@[1, 2, 3].all(_ x = x > 2)                        // false
```

### none

すべての要素が条件を満たさないかを返します。

```taida
@[1, 2, 3].none(_ x = x > 10)   // true
@[1, 2, 3].none(_ x = x > 2)    // false
```

---

## 操作モールド

> **PHILOSOPHY.md -- III.** カタめたいなら、鋳型を作りましょう

リストの操作はすべてモールドで行います。結果は `]=>` で取り出すか、パイプラインで次の処理に渡します。

### 変換: Map, Filter

#### Map[list, fn]()

各要素に関数を適用して新しいリストを返します。

```taida
Map[@[1, 2, 3], _ x = x * 2]() ]=> doubled
// doubled: @[2, 4, 6]

// 条件付き変換
Map[@[1, 2, 3, 4, 5], _ x =
  | x > 3 |> x * 10
  | _ |> x
]() ]=> processed
// processed: @[1, 2, 3, 40, 50]
```

#### Filter[list, fn]()

条件を満たす要素だけを抽出します。

```taida
scores <= @[85, 92, 78, 95, 88]

Filter[scores, _ x = x >= 90]() ]=> highScores
// highScores: @[92, 95]

// 名前付き関数も使えます
isEven x =
  Mod[x, 2]() ]=> r
  r == 0
=> :Bool
Filter[@[1, 2, 3, 4, 5, 6], isEven]() ]=> evens
// evens: @[2, 4, 6]
```

### 畳み込み: Fold, Foldr

#### Fold[list, init, fn]()

左から畳み込みます。`init` が初期値、`fn` がアキュムレータ関数です。

```taida
// 合計
Fold[@[1, 2, 3, 4, 5], 0, _ acc x = acc + x]() ]=> total
// total: 15

// 文字列の結合
names <= @["Asuka", "Rei", "Shinji"]
Fold[names, "", _ acc name =
  | acc == "" |> name
  | _ |> acc + ", " + name
]() ]=> joined
// joined: "Asuka, Rei, Shinji"
```

#### Foldr[list, init, fn]()

右から畳み込みます。

```taida
Foldr[@["a", "b", "c"], "", _ acc x = x + acc]() ]=> concat
// concat: "abc"
```

### 取得: Take, Drop, TakeWhile, DropWhile

#### Take[list, n]() / Drop[list, n]()

先頭から n 個取得、または先頭 n 個をスキップします。

```taida
numbers <= @[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

Take[numbers, 3]() ]=> first3    // @[1, 2, 3]
Drop[numbers, 3]() ]=> rest      // @[4, 5, 6, 7, 8, 9, 10]
```

#### TakeWhile[list, fn]() / DropWhile[list, fn]()

条件を満たす間だけ取得、またはスキップします。

```taida
numbers <= @[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

TakeWhile[numbers, _ x = x < 5]() ]=> underFive  // @[1, 2, 3, 4]
DropWhile[numbers, _ x = x < 5]() ]=> fromFive   // @[5, 6, 7, 8, 9, 10]
```

### 追加: Append, Prepend, Concat

```taida
Append[@[1, 2], 3]() ]=> appended         // @[1, 2, 3]
Prepend[@[2, 3], 1]() ]=> prepended       // @[1, 2, 3]
Concat[@[1, 2], @[3, 4]]() ]=> combined   // @[1, 2, 3, 4]
```

### 整形: Sort, Reverse, Unique, Flatten

#### Sort[list]()

要素をソートします。オプションで降順やキー関数を指定できます。

```taida
Sort[@[3, 1, 4, 1, 5]]() ]=> sorted
// sorted: @[1, 1, 3, 4, 5]

// 降順
Sort[@[3, 1, 4, 1, 5]](reverse <= true) ]=> desc
// desc: @[5, 4, 3, 1, 1]

// キー関数でソート
pilots <= @[
  @(name <= "Asuka", age <= 14),
  @(name <= "Shinji", age <= 14),
  @(name <= "Rei", age <= 14)
]
Sort[pilots](by <= _ p = p.age) ]=> byAge
```

| オプション | デフォルト | 説明 |
|-----------|----------|------|
| `reverse` | `false` | `true` で降順 |
| `by` | なし（自然順） | キー抽出関数 |

#### Reverse[list]()

```taida
Reverse[@[1, 2, 3]]() ]=> reversed  // @[3, 2, 1]
```

#### Unique[list]()

重複を除去します。

```taida
Unique[@[1, 2, 2, 3, 3, 1]]() ]=> uniq  // @[1, 2, 3]

// キー関数で重複判定
Unique[items](by <= _ x = x.id) ]=> uniqueById
```

#### Flatten[list]()

ネストしたリストを1段階フラット化します。

```taida
Flatten[@[@[1, 2], @[3, 4]]]() ]=> flat  // @[1, 2, 3, 4]
```

### 結合: Join, Sum

#### Join[list, sep]()

要素を区切り文字で結合して文字列にします。

```taida
Join[@["a", "b", "c"], ","]() ]=> csv  // "a,b,c"
Join[@[1, 2, 3], "-"]() ]=> dashed     // "1-2-3"
```

#### Sum[list]()

数値リストの合計を返します。

```taida
Sum[@[1, 2, 3, 4, 5]]() ]=> total  // 15
empty: @[Int] <= @[]
Sum[empty]() ]=> zero               // 0
```

### 検索: Find, FindIndex, Count

#### Find[list, fn]()

条件を満たす最初の要素を Lax で返します。

```taida
Find[@[1, 2, 3, 4, 5], _ x = x > 3]() ]=> found
// found: 4

Find[@[1, 2, 3], _ x = x > 10]().hasValue  // false
```

#### FindIndex[list, fn]()

条件を満たす最初の要素の位置を返します。見つからない場合は -1。

```taida
FindIndex[@[10, 20, 30, 40], _ x = x > 25]()  // 2
```

#### Count[list, fn]()

条件を満たす要素の数を返します。

```taida
Count[@[1, 2, 3, 4, 5], _ x = x > 2]()  // 3
```

### ペア: Zip, Enumerate

#### Zip[list, other]()

2つのリストを要素ごとにペアにします。短い方に合わせます。

```taida
Zip[@[1, 2, 3], @["a", "b", "c"]]() ]=> pairs
// pairs: @[@(first <= 1, second <= "a"), @(first <= 2, second <= "b"), @(first <= 3, second <= "c")]
```

#### Enumerate[list]()

各要素にインデックスを付与します。

```taida
Enumerate[@["Asuka", "Rei", "Shinji"]]() ]=> indexed
// indexed: @[@(index <= 0, value <= "Asuka"), @(index <= 1, value <= "Rei"), @(index <= 2, value <= "Shinji")]
```

---

## パイプラインでのリスト操作

パイプライン `=>` / `<=` の中で `_` が前ステップの値を受け取ります。リスト操作を連鎖させることができます。

### 正方向パイプライン

```taida
scores <= @[85, 92, 78, 95, 88]

// フィルタ → マップ → 結合
scores => Filter[_, _ x = x >= 90]() => Map[_, _ x = x * 2]() => highDoubled
// highDoubled: @[184, 190]

// フィルタ → ソート → 先頭3件
@[5, 2, 8, 1, 9, 3, 7] => Filter[_, _ x = x > 3]() => Sort[_]() => Take[_, 3]() => result
// result: @[5, 7, 8]
```

### 中間変数による逆順処理

```taida
// 順方向パイプラインで同じ結果を得られます
@[5, 2, 8, 1, 9, 3, 7] => Filter[_, _ x = x > 3]() => Sort[_]() => Take[_, 3]() => result
```

> **注意**: `<=` のチェーンによる逆方向パイプライン（`result <= f() <= g() <= data`）は仕様上有効ですが、現在のパーサーでは単一の `<=` 代入のみサポートしています。順方向パイプライン `=>` または中間変数を使用してください。

### 直接呼び出し（unmold）

パイプラインを使わず、中間変数に結果を保持する方法もあります。

```taida
numbers <= @[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

isEven x =
  Mod[x, 2]() ]=> r
  r == 0
=> :Bool

Filter[numbers, isEven]() ]=> evens
Map[evens, _ x = x * 2]() ]=> doubled
Fold[doubled, 0, _ acc x = acc + x]() ]=> sum
// sum: 60
```

---

## パターン: データ処理パイプライン

### NERV スタッフデータの処理

```taida
staff <= @[
  @(name <= "Asuka", age <= 14, role <= "pilot", active <= true),
  @(name <= "Shinji", age <= 14, role <= "pilot", active <= true),
  @(name <= "Rei", age <= 14, role <= "pilot", active <= false),
  @(name <= "Ritsuko", age <= 30, role <= "scientist", active <= true)
]

// アクティブなスタッフの名前を取得します
staff => Filter[_, _ s = s.active]() => Map[_, _ s = s.name]() => activeNames
// activeNames: @["Asuka", "Shinji", "Ritsuko"]

// 平均年齢を計算します
staff => Map[_, _ s = s.age]() => ages
Fold[ages, 0, _ acc a = acc + a]() ]=> totalAge
Div[totalAge, ages.length()]() ]=> avgAge
// avgAge: 18
```

### 売上データの集計

```taida
orders <= @[
  @(product <= "A", quantity <= 5, price <= 100),
  @(product <= "B", quantity <= 3, price <= 200),
  @(product <= "A", quantity <= 2, price <= 100)
]

// 各注文の小計を計算し、合計します
orders => Map[_, _ o = o.quantity * o.price]() => subtotals
Sum[subtotals]() ]=> totalRevenue
// totalRevenue: 1300

// 商品Aだけの合計
orders => Filter[_, _ o = o.product == "A"]() => Map[_, _ o = o.quantity * o.price]() => aSubtotals
Sum[aSubtotals]() ]=> aRevenue
// aRevenue: 700
```

---

## 型シグネチャ一覧

| モールド | `[]` 必須引数 | `()` オプション | 戻り値 |
|---------|-------------|----------------|--------|
| `Map[list, fn]()` | list, fn | - | @[U] |
| `Filter[list, fn]()` | list, fn | - | @[T] |
| `Fold[list, init, fn]()` | list, init, fn | - | A |
| `Foldr[list, init, fn]()` | list, init, fn | - | A |
| `Take[list, n]()` | list, n | - | @[T] |
| `Drop[list, n]()` | list, n | - | @[T] |
| `TakeWhile[list, fn]()` | list, fn | - | @[T] |
| `DropWhile[list, fn]()` | list, fn | - | @[T] |
| `Append[list, val]()` | list, val | - | @[T] |
| `Prepend[list, val]()` | list, val | - | @[T] |
| `Concat[list, other]()` | list, other | - | @[T] |
| `Sort[list]()` | list | reverse, by | @[T] |
| `Reverse[list]()` | list | - | @[T] |
| `Unique[list]()` | list | by | @[T] |
| `Flatten[list]()` | list | - | @[U] |
| `Join[list, sep]()` | list, sep | - | Str |
| `Sum[list]()` | list | - | Num |
| `Find[list, fn]()` | list, fn | - | Lax[T] |
| `FindIndex[list, fn]()` | list, fn | - | Int |
| `Count[list, fn]()` | list, fn | - | Int |
| `Zip[list, other]()` | list, other | - | @[BuchiPack] |
| `Enumerate[list]()` | list | - | @[BuchiPack] |

---

## まとめ

| 分類 | API | 返す値 |
|------|-----|--------|
| **状態チェック** | `length()`, `isEmpty()`, `contains()`, `indexOf()`, `lastIndexOf()` | Int / Bool |
| **安全アクセス** | `first()`, `last()`, `get()`, `max()`, `min()` | Lax[T] |
| **述語** | `any()`, `all()`, `none()` | Bool |
| **操作** | `Map`, `Filter`, `Fold`, `Sort`, `Reverse`, etc. | モールド |

メソッドは「聞くだけ」、モールドは「作り変える」。ゴリラリテラルは終了。この使い分けが Taida のリスト操作の基本です。

詳しいモールドの仕様は [モールディング型リファレンス](../reference/mold_types.md) を、メソッドの仕様は [標準メソッドリファレンス](../reference/standard_methods.md) を参照してください。

---

# 制御フロー

> **PHILOSOPHY.md -- I.** 深く考えずに適当にぶちこんでけ

Taida には if/else も switch も三項演算子もありません。あるのは `|` と `|>` だけです。

---

## 条件分岐 `|` `|>`

### 基本構文

```taida
| 条件1 |> 値1
| 条件2 |> 値2
| _ |> デフォルト値
```

`_` はプレースホルダで、「それ以外の全て」を意味します。

### 変数への代入

条件分岐は式なので、結果を直接変数に代入できます。

```taida
score <= 85

grade <=
  | score >= 90 |> "A"
  | score >= 80 |> "B"
  | score >= 70 |> "C"
  | score >= 60 |> "D"
  | _ |> "F"
// grade: "B"
```

### 1行で書く

```taida
sign <= | x >= 0 |> "positive" | _ |> "negative"
```

### 複合条件

`&&` や `||` で条件を組み合わせることができます。

```taida
canDrive <=
  | age >= 18 && hasLicense |> true
  | _ |> false
```

---

## パターンマッチング的な条件分岐

### 値のパターンマッチ

```taida
status <= "success"

message <=
  | status == "success" |> "Operation completed"
  | status == "error" |> "Operation failed"
  | status == "pending" |> "Operation in progress"
  | _ |> "Unknown status"
```

### ぶちパックのフィールドによるマッチ

```taida
response <= @(code <= 200, data <= "OK")

result <=
  | response.code == 200 |> "Success: " + response.data
  | response.code == 404 |> "Not found"
  | response.code >= 500 |> "Server error"
  | _ |> "Unknown response"
```

### ネストした条件

条件分岐はネストできます。

```taida
staff <= @(age <= 29, role <= "commander", active <= true)

accessLevel <=
  | staff.role == "commander" |>
    | staff.active |> "full"
    | _ |> "readonly"
  | staff.role == "operator" |>
    | staff.age >= 18 |> "standard"
    | _ |> "limited"
  | _ |> "none"
// accessLevel: "full"
```

---

## ゴリラリテラル `><` との組み合わせ

条件分岐の先に `><` を置くと、プログラムは即座に終了します。

`><` はゴリラの顔文字です。日本語の顔文字で「ムキーッ」を意味する怒りの表情が、そのまま即時終了リテラルになりました。実行中にゴリラが出現すれば、プログラムは終了します。

```taida
processOrder order =
  | order.total < 0 |> ><      // 負の金額にゴリラが出現します。プログラムは終了します。
  | order.items.isEmpty() |> ><  // 商品なしにもゴリラが出現します。
  | _ |> submitOrder(order)
=> :OrderResult
```

条件分岐の中でゴリラが現れるということは、「ここに来たらもう終わりです」というプログラマの意思表明です。

### exit() との対比

| | `exit()` | `><` |
|--|----------|------|
| **性質** | 手続き（関数呼び出し） | 宣言（リテラル） |
| **戻り値の型** | Never / void / ! | ゴリラに型はありません |
| **エラーコード** | 0? 1? 42? 選ぶ必要があります | ゴリラにコードはありません |
| **クリーンアップ** | atexit? defer? finally? | ゴリラは片付けません |
| **import** | 必要です | 不要です。`><` は言語そのものです |
| **文字数** | 11~22文字 | **2文字** |

### なぜ `><` は見間違えないのか

`>` と `<` は比較演算子です。これを**逆向きにぶつける**と `><` になります。二つの矢印が正面衝突しています。クラッシュです。概念がそのまま記号になっています。`>` でもなく `<` でもない `><` だけが「終わり」を意味するため、他のどの演算子とも混同しません。

### AI との相性

AST 上で `><` は `Expr::Gorilla` として表現されます。AI にとっては以下のような利点があります。

- `><` がある分岐は「到達不能コード」として即座に判定できます
- 「ここは来てはいけない」を `><` の1トークンで表現できます
- 構造的イントロスペクションにおいて、終端ノードとして明確にマーキングされます

```taida
// AI が生成するコード例
validateInput input =
  | input.type != "expected" |> ><  // 不正な入力にはゴリラが出現します
  | input.value < 0 |> ><          // 負の値にもゴリラが出現します
  | _ |> processInput(input)
=> :Output
```

AI が `><` を使うとき、そこには曖昧さがありません。「この分岐に入ったらプログラムは終わる」ということ以上でもそれ以下でもありません。

---

## ガード節パターン

関数内での早期リターンとして条件分岐を使えます。異常系を先に弾き、正常系を最後に書くパターンです。

```taida
processStaff staff =
  | !staff.active |> @(success <= false, message <= "Inactive staff")
  | staff.age < 18 |> @(success <= false, message <= "Under age")
  | _ |>
    deployed <= assignMission(staff)
    @(success <= true, message <= "Assigned: " + deployed.name)
=> :@(success: Bool, message: Str)
```

`><` と組み合わせると、致命的な前提条件の違反を表現できます。

```taida
launchEva pilot eva =
  | !pilot.active |> ><           // 非アクティブパイロットは起動不可です
  | eva.power < 0 |> ><           // 電力不正は致命的です
  | pilot.syncRate < 10 |>
    @(success <= false, reason <= "Sync rate too low")
  | _ |>
    result <= activateEva(pilot, eva)
    @(success <= true, reason <= "")
=> :@(success: Bool, reason: Str)
```

---

## 再帰ループ

Taida には for や while のようなループ構文がありません。繰り返し処理は再帰で表現可能です。末尾再帰は自動的に最適化されるため、スタックオーバーフローを心配する必要はありません。

### 基本パターン: アキュムレータ

```taida
// 1 から n までの合計を計算します
sumTo n: Int =
  sumToTail(n, 0)
=> :Int

sumToTail n: Int acc: Int =
  | n < 1 |> acc
  | _ |> sumToTail(n - 1, acc + n)  // 末尾位置: 最適化されます
=> :Int

result <= sumTo(1000000)  // スタックオーバーフローしません
```

### 階乗

```taida
factorial n: Int =
  factorialTail n 1
=> :Int

factorialTail n: Int acc: Int =
  | n < 2 |> acc
  | _ |> factorialTail(n - 1, acc * n)
=> :Int
```

### フィボナッチ数列

```taida
fibonacci n: Int =
  fibTail n 0 1
=> :Int

fibTail n: Int a: Int b: Int =
  | n == 0 |> a
  | n == 1 |> b
  | _ |> fibTail(n - 1, b, a + b)
=> :Int
```

### リスト処理での再帰

多くのリスト処理はモールドで十分ですが、複雑なロジックには再帰が適しています。

```taida
// リストから条件を満たす最初の要素を見つけ、加工して返します
findAndProcess items: @[Item] =
  | items.isEmpty() |> @(found <= false, result <= "")
  | _ |>
    items.first() ]=> current
    | current.priority > 5 |>
      processed <= transform(current)
      @(found <= true, result <= processed.name)
    | _ |>
      Drop[items, 1]() ]=> rest
      findAndProcess(rest)  // 末尾再帰
=> :@(found: Bool, result: Str)
```

末尾再帰最適化の詳細は [末尾再帰最適化リファレンス](../reference/tail_recursion.md) を参照してください。

---

## 純粋式の原則（`| |>` アーム本体の構文境界）

> **PHILOSOPHY.md -- I.** 深く考えずに適当にぶちこんでけ

`| cond |> ...` のアーム本体は **純粋な式** です。副作用文（結果を捨てる関数呼び出しや `=> _var` パイプライン）をアームの途中に埋め込むことはできません。

### アーム本体に書ける要素

アーム本体は「**任意個の let バインディング** → **最終結果**」の形を取ります。

許可される非終端文（let バインディング）:

- `name <= expr` — 値バインディング
- `expr => name` — 単一方向パイプラインの末尾に書かれた値バインディング
- `expr ]=> name` — 前方アンモールド（Lax / Option 解凍）
- `name <=[ expr` — 後方アンモールド

**最終行** は C13-1 以降、次のいずれでも構いません:

- **値を生む式**（従来形） — そのまま式の値がアームの結果になる
- **let バインディング** — 束縛された値がそのままアームの結果として返る

```taida
// OK: let バインディング → 最終式（従来形）
classify n =
  | n > 0 |>
    doubled <= n * 2
    doubled + 1      // 最終式
  | _ |>
    zeroed <= 0
    zeroed - 1       // 最終式
=> :Int

// OK: 末尾バインディングがアームの結果を兼ねる（C13-1）
classify n =
  | n > 0 |>
    doubled <= n * 2
    result <= doubled + 1   // 末尾バインド — アームの値は `result` (= doubled + 1)
  | _ |> 0
=> :Int
```

同じ規則が **関数本体** と **`|==` エラー天井本体** にも適用されます:

```taida
sumAndShift x: Int y: Int =
  total <= x + y
  shifted <= total + 1    // 関数本体の末尾バインド — 戻り値は `shifted`
=> :Int

handle =
  |== err: Error =
    fallback <= "default"  // ハンドラ本体の末尾バインド — 結果は `fallback`
  => :Str
  "ok"
=> :Str
```

### アーム本体に書けない要素

以下はいずれも `[E1616]` でコンパイルエラーになります。副作用文の混入を禁止する境界です。

- 非終端位置の裸の関数呼び出し文（`stdout("x")` のみが 1 行として置かれる）
- `expr => _var` パターンでの値の捨て（哲学 I「暗黙の排除」に反するため） — C13-1 でも末尾の `_var` は同じく破棄扱いで禁止
- アーム本体内での関数定義 / 型定義 / モールド定義 / `|==` エラー天井 / `>>>` import / `<<<` export

```taida
// NG: FB-17 の再現ケース — アーム内に副作用文が紛れ込む
validateProjectRoot =
  | Exists["./"]() == false |>
    fail("error: current directory does not exist")
    writeFile(".hk_write_check", "test") => _wr   // [E1616]: discard 破棄パターンは禁止
    RemoveFile[".hk_write_check"]() => _rm
  | _ |>
    "ok"
=> :Str
```

### 単一方向パイプラインの中間命名 (`=> name`)

純粋な `=>` 単一方向パイプラインでは、中間の `=> name` を **bind-and-forward** として書けます。束縛された値は同じ値のまま次段へ流れ、`name` は **その pipeline 文の残り区間** から参照可能です。

```taida
add x: Int y: Int = x + y => :Int

1 => add(3, _) => addResult => stdout(addResult.toString())
```

`addResult` のスコープはこの 1 文の残り区間だけです。次の文では見えません。
方向混在（`=>` と `<=` の混在）および `expr => _tmp` 形の破棄は引き続き禁止です。

### Migration: 従来コードの書き換え

副作用を伴う前処理が必要な場合は **アーム本体の外に出す** か、ヘルパ関数 / `If` モールドを使います（C13 以前と同じ）:

```taida
// Before (NG): アーム内で副作用を起こしていた
run =
  | needsInit |>
    setup() => _s
    runApp()
  | _ |> runApp()
=> :Int

// After (OK): 副作用は関数として切り出し、アーム本体は純粋式に
run =
  setup_if_needed() => _
  runApp()
=> :Int

setup_if_needed =
  | needsInit |> setup()
  | _ |> 0
=> :Int
```

C13-1 で追加された末尾バインド形は、従来「最終行に同名の識別子をもう 1 行置く」ための冗長さを解消します:

```taida
// Before (C12 以前): 末尾識別子を再掲する冗長な書き方
f x =
  | x > 0 |>
    doubled <= x * 2
    result <= doubled + 1
    result                 // 末尾に同じ名前をもう 1 行
  | _ |> 0
=> :Int

// After (C13-1): 末尾バインドで完結
f x =
  | x > 0 |>
    doubled <= x * 2
    result <= doubled + 1  // 最終行の束縛値がそのままアームの値
  | _ |> 0
=> :Int
```

短い 2 分岐なら `If` モールドが簡潔です。

```taida
result <= If[cond, doSomething(), 0]()
```

### なぜこの制約なのか

Taida では `| cond |> value` は **式** なので、分岐の途中に状態遷移を許すと「式」ではなくなり、プログラムの構造的な意味が揺らぎます（哲学 IV「書くのも読むのも AI、眺めるのが人間」の前提が崩れます）。純粋式の原則により、条件分岐は常にグラフ上で単一ノードとして扱え、構造的イントロスペクションが確定的に働きます。

C13-1 の末尾バインド緩和は純粋式の原則と矛盾しません: 末尾バインドは構文上 let に見えますが、セマンティクスは「束縛＋その値を返す」という単一の純粋式と等価です。副作用文の混入禁止は引き続き維持されます。

---

## 式ベース

すべての条件分岐は値を返します。文ではなく式です。

```taida
// 条件分岐の結果を直接使えます
message <= "Status: " + (| active |> "ON" | _ |> "OFF")
```

すべての分岐は同じ型を返す必要があります。型チェッカーがこれを保証します。

---

## エラー処理との組み合わせ

条件分岐は [エラー処理](08_error_handling.md) の `|==` エラー天井や `throw` と組み合わせて使えます。

```taida
Error => RequestError = @(detail: Str)

processRequest request =
  |== error: RequestError =
    @(success <= false, error <= error.message)
  => :@(success: Bool, error: Str)

  | request.body == "" |> RequestError(type <= "RequestError", message <= "Empty body", detail <= "body").throw()
  | request.method != "POST" |> RequestError(type <= "RequestError", message <= "Invalid method", detail <= request.method).throw()
  | _ |>
    result <= process(request.body)
    @(success <= true, error <= "")
=> :@(success: Bool, error: Str)
```

---

## If モールド -- 2 分岐の条件式

2 分岐だけの条件分岐には `If[condition, then, else]()` モールドが使えます。`| |>` の簡潔な代替です。

```taida
// If モールド（2 分岐向き）
result <= If[x > 0, "positive", "negative"]()

// | |> 構文（複数分岐向き）
grade <=
  | score >= 90 |> "A"
  | score >= 80 |> "B"
  | _ |> "C"
```

パイプラインで `_` を使って前段の値を参照できます。

```taida
// clamp: 100 を超えたら 100 に制限
150 => If[_ > 100, 100, _]() => clamped   // 100

// 分類
5 => If[_ > 3, "big", "small"]() => label  // "big"
```

非選択 branch は評価されません（short-circuit）。

---

## 型比較モールド -- TypeIs / TypeExtends

型の判定にもモールドを使います。

```taida
// 実行時の型チェック
TypeIs[42, :Int]()           // true
TypeIs["hello", :Str]()     // true

// Enum variant 判定
Enum => Status = :Ok :Fail
TypeIs[x, Status:Ok]()      // true（x が Status:Ok の場合）

// 型の継承関係チェック
TypeExtends[:Int, :Num]()   // true
TypeExtends[:Dog, :Animal]()   // true（Dog が Animal を継承している場合）
```

詳細は「モールディング型」ガイドの型比較モールドセクションを参照してください。

---

## まとめ

| 構文 | 用途 |
|------|------|
| `\| cond \|> val` | 条件分岐（複数分岐向き） |
| `\| _ \|> val` | デフォルトケース |
| `\| cond \|> ><` | ゴリラが出現し、プログラムは即時終了します |
| `If[cond, then, else]()` | 2 分岐の条件式 |
| `TypeIs[val, :Type]()` | 実行時の型チェック |
| `TypeExtends[:A, :B]()` | 型の継承関係チェック |
| ネスト | 複雑な条件 |
| 1行 | 三項演算子の代替 |
| ガード節 | 異常系を先に弾くパターン |
| 再帰 | ループの代替（末尾再帰は自動最適化） |

---

# エラー処理

> **PHILOSOPHY.md -- I.** 深く考えずに適当にぶちこんでけ

Taida には try-catch がありません。エラー処理は2つの仕組みで成り立っています。

1. **Lax による安全な操作** -- よくある失敗（ゼロ除算、範囲外アクセスなど）はプログラムを止めず、デフォルト値にフォールバックします
2. **throw と |== によるカスタムエラー** -- ビジネスロジック上の致命的なエラーは明示的に投げ、明示的にキャッチします

キャッチされなかったエラーは**ゴリラ天井**が最後に止めます。

---

## Taida のエラーモデル

従来の言語では、ゼロ除算も範囲外アクセスもビジネスエラーも、すべてが例外として同じ仕組みで処理されていました。Taida はこれを2つの層に分離しています。

| 層 | 失敗の種類 | 処理方法 | プログラムは止まるか |
|---|-----------|----------|-------------------|
| **Lax 層** | ゼロ除算、範囲外アクセス、型変換失敗 | デフォルト値にフォールバック | 止まりません |
| **throw 層** | カスタムエラー（ビジネスロジック） | `\|==` でキャッチ、またはゴリラ天井 | キャッチしなければ止まります |
| **Gorillax 層** | 外部操作の失敗（npm 等） | ゴリラ（即終了）、または `.relax()` で throw に変換 | 止まります（relax すればキャッチ可能） |

---

## Lax による安全な操作

Lax[T] は「操作が失敗しても必ず値を返す」モールド型です。`hasValue` フィールドで成功/失敗を判別でき、失敗時は型 T のデフォルト値にフォールバックします。

### 除算と剰余

Taida に `/` 演算子と `%` 演算子はありません。除算と剰余は `Div[x, y]()` と `Mod[x, y]()` モールドで行います。これらは Lax を返すため、ゼロ除算でもプログラムは停止しません。

```taida
// 正常な除算
Div[10, 3]() ]=> result   // 3
Mod[10, 3]() ]=> result   // 1

// ゼロ除算 -- プログラムは停止しません
Div[10, 0]() ]=> result   // 0 (Int のデフォルト値)
Mod[10, 0]() ]=> result   // 0

// hasValue で判別できます
Div[10, 3]().hasValue   // true
Div[10, 0]().hasValue   // false
```

### リストの安全アクセス

`get()`、`first()`、`last()`、`max()`、`min()` はすべて Lax を返します。空リストや範囲外アクセスでもプログラムは停止しません。

```taida
items <= @[10, 20, 30]

// 正常なアクセス
items.get(1) ]=> val      // 20
items.first() ]=> val     // 10
items.last() ]=> val      // 30
items.max() ]=> val       // 30
items.min() ]=> val       // 10

// 範囲外・空リスト -- プログラムは停止しません
items.get(100) ]=> val    // 0 (デフォルト値)
empty: @[Int] <= @[]
empty.first() ]=> val     // 0
empty.max() ]=> val       // 0
```

### 型変換

型変換モールド `Int[x]()`、`Float[x]()`、`Str[x]()`、`Bool[x]()` も Lax を返します。

```taida
// 正常な変換
Int["123"]() ]=> num     // 123
Float["3.14"]() ]=> val  // 3.14

// 変換失敗 -- プログラムは停止しません
Int["abc"]() ]=> num     // 0 (デフォルト値)
Int["abc"]().hasValue    // false
```

### Lax の活用パターン

#### hasValue による分岐

```taida
userInput <= "42"
Int[userInput]() => parsed

| parsed.hasValue |>
  stdout("Parsed: " + parsed.unmold().toString())
| _ |>
  stdout("Invalid input")
```

#### getOrDefault でカスタムデフォルト値

```taida
empty: @[Int] <= @[]
Div[total, count]().getOrDefault(0)       // ゼロ除算時は 0
empty.first().getOrDefault(99)            // 空リスト時は 99
Int["abc"]().getOrDefault(-1)             // 変換失敗時は -1
```

#### map による変換チェーン

```taida
// 成功時のみ変換を適用します。失敗時はそのまま空の Lax が伝播します
Div[100, count]()
  .map(_ x = x * taxRate)
  .map(_ x = Round[x]().unmold())
  ]=> taxAmount
```

Lax の詳細は [リスト操作](06_lists.md) および [モールディング型リファレンス](../reference/mold_types.md) を参照してください。

---

## Error 基底型

カスタムエラーはすべて `Error` 基底型を継承して定義します。`throw()` メソッドは Error 型を継承した型のインスタンスのみが持ちます。

```taida
// Error 基底型（組み込み）
Error = @(
  type: Str
  message: Str
)

// カスタムエラーの定義
Error => ValidationError = @(
  field: Str
  code: Int
)

Error => ApiError = @(
  status: Int
  endpoint: Str
)
```

### throw は Error 継承型のみ

```taida
// OK: Error を継承しています
ValidationError(type <= "ValidationError", message <= "Invalid", field <= "email", code <= 400).throw()

// NG: 通常のぶちパックは throw できません
@(name <= "Asuka").throw()  // コンパイルエラー
```

---

## throw と |== エラー天井

### 基本構文

`|==` は、その下で発生する `throw` をキャッチするエラー天井です。式ではなく**スコープ宣言**です — `|==` の下にある全てのコードが保護領域となり、throw が発生するとハンドラが実行されます。

```taida
|== error: ErrorType =
  | 条件1 |> 処理1
  | 条件2 |> 処理2
  | _ |> デフォルト処理
=> :ReturnType

// ここから下が保護領域（throw が発生する可能性のある処理）
```

ハンドラの戻り値型（`=> :ReturnType`）は、保護領域の戻り値型と一致しなければなりません。型が合わない場合はコンパイルエラーになります。

> **C13-1 の末尾バインド短縮形**: `|==` ハンドラ本体の末尾が `name <= expr` / `expr => name` / `expr ]=> name` / `name <=[ expr` であるとき、束縛された値がそのままハンドラの結果になります。例:
>
> ```taida
> |== error: Error =
>   fallback <= "default"   // 末尾バインド — ハンドラ結果は "default"
> => :Str
> ```
>
> 関数本体や `| |>` アーム本体と同じ規則が適用されます。詳細は `docs/guide/07_control_flow.md` を参照してください。

### 基本的な使用例

```taida
Error => ValidationError = @(field: Str)

processInput text: Str =
  |== error: Error =
    | error.type == "ValidationError" |> "Invalid: empty"
    | _ |> "Unknown error: " + error.message
  => :Str

  | text == "" |> ValidationError(type <= "ValidationError", message <= "Empty input", field <= "text").throw()
  | _ |> "Processed: " + text
=> :Str
```

### エラーの伝播

`throw` は最も近い `|==` に到達するまで、呼び出しスタックを遡って伝播します。

- 同一スコープに `|==` がある → そのハンドラでキャッチされます
- 同一スコープに `|==` がない → 呼び出し元のスコープに伝播します
- HOF（Map、Filter 等）のコールバック内で `throw` が発生した場合も同様に伝播します
- どこにも `|==` がなければ → ゴリラ天井に到達し、プログラムは終了します

```taida
Error => NegativeValueError = @(value: Int)

innerFunction value: Int =
  | value < 0 |> NegativeValueError(type <= "NegativeValueError", message <= "Must be positive", value <= value).throw()
  | _ |> value * 2
=> :Int

outerFunction x: Int =
  |== error: Error =
    | error.type == "NegativeValueError" |> 0
    | _ |> -1
  => :Int

  result <= innerFunction(x)  // ここで throw が発生する可能性があります
  result + 10
=> :Int

result <= outerFunction(-5)  // 0 (エラーがキャッチされました)
result <= outerFunction(5)   // 20 (正常処理)
```

### 複数エラーの処理

```taida
Error => NegativeError = @(value: Int)
Error => TooLargeError = @(value: Int, limit: Int)

processValue value: Int =
  |== error: Error =
    | error.type == "NegativeError" |> @(success <= false, result <= 0, error <= "Negative")
    | error.type == "TooLargeError" |> @(success <= false, result <= 0, error <= "Too large")
    | _ |> @(success <= false, result <= 0, error <= "Unknown")
  => :@(success: Bool, result: Int, error: Str)

  | value < 0 |> NegativeError(type <= "NegativeError", message <= "Negative", value <= value).throw()
  | value > 1000 |> TooLargeError(type <= "TooLargeError", message <= "Over limit", value <= value, limit <= 1000).throw()
  | _ |> @(success <= true, result <= value * 2, error <= "")
=> :@(success: Bool, result: Int, error: Str)
```

---

## ゴリラ天井（Gorilla Ceiling）

明示的な `|==` がない場合、プログラムのトップレベルには暗黙の**ゴリラ天井**が存在します。

```
あなたのプログラム
|-- 関数A
|   +-- 関数B（ここでエラーが投げられます）
|       ! |== がありません
|-- ゴリラ天井
|   +-- 誰もキャッチしなかったので、ゴリラがプログラムを停止させます
+-- プログラム終了
```

ゴリラ天井は最後の番人です。すべてのエラーは最終的にゴリラ天井に到達し、プログラムは終了します。エラーが野放しになることを許しません。

```taida
// この関数にはエラー天井がありません
riskyFunction x: Int =
  | x < 0 |> Error(type <= "RuntimeError", message <= "Negative value").throw()
  | _ |> x * 2
=> :Int

// throw が発生すると、ゴリラ天井がキャッチしてプログラムは終了します
result <= riskyFunction(-1)  // ゴリラ天井に到達 => プログラム終了
```

### なぜゴリラ天井が必要なのか

他の言語ではエラーが黙殺されることがあります。Python の `None` が伝播して、全然関係ないところで `AttributeError` が出ます。JavaScript の未処理 Promise は静かに失敗します。

Taida ではカスタムエラーの throw はゴリラ天井が確実にキャッチし、プログラムを停止させます。一方、ゼロ除算や範囲外アクセスなどの「よくある失敗」は Lax で安全に処理され、プログラムは止まりません。

```taida
// 致命的なエラー: ゴリラ天井が停止させます
Error => FatalError = @(reason: Str)
FatalError(type <= "FatalError", message <= "Critical failure", reason <= "disk full").throw()
// ゴリラ天井に到達 => プログラム終了

// よくある失敗: Lax で安全に処理されます
Div[10, 0]() ]=> result  // 0 (プログラムは止まりません)
```

エラーを握り潰したい場合は、明示的に `|==` を書く必要があります。何もしなければ、ゴリラがプログラムを停止させます。

---

## Result[T, P] -- 述語付き操作モールド

Result は「成功条件を述語で定義する」モールド型です。`]=>` でアンモールディングすると述語 P が評価され、真なら値 T を返し、偽なら throw が発動します。

```taida
Mold[T] => Result[T, P <= :T => :Bool] = @(throw: Error)
// P: :T => :Bool（成功条件を定義する述語）
```

### 基本的な使用

```taida
// _ = true は常に真を返す無名関数（常に成功）
ok <= Result[42, _ = true]()
ok ]=> value  // 42

// _ = false は常に偽を返す無名関数（常に失敗）
Error => MyError = @(reason: Str)
err <= Result[0, _ = false](throw <= MyError(type <= "MyError", message <= "fail", reason <= "invalid"))
err ]=> value  // throw が発動（エラー天井で捕捉可能）
```

### => と ]=> の違い

`=>` は Result をそのまま代入します。`]=>` は述語を評価して値を取り出します。

```taida
Result[x, pred](throw <= err) => r   // r: Result[T, P]（述語は未評価）
Result[x, pred](throw <= err) ]=> r  // r: T（述語を評価 → 真なら値、偽なら throw）
```

### 述語によるバリデーション

述語にラムダを渡すことで、値のバリデーションを表現できます。

```taida
Error => ValidationError = @(field: Str)

// 年齢バリデーション: 18歳以上なら成功
age <= 25
Result[age, _ x = x >= 18]() ]=> validAge  // 25 >= 18 → true → validAge = 25

age <= 15
Result[age, _ x = x >= 18](throw <= ValidationError(type <= "ValidationError", message <= "Must be 18+", field <= "age")) ]=> validAge
// 15 >= 18 → false → throw 発動
```

### 関数の戻り値として

推論可能である場合、戻り値の型注釈では `:Result[T, _]` と書くことができます。`_` は述語の型を推論させるプレースホルダです。

```taida
Error => ValidationError = @(field: Str)

validateAge age: Int =
  Result[age, _ x = x >= 18](throw <= ValidationError(type <= "ValidationError", message <= "Must be 18+", field <= "age"))
=> :Result[Int, _]

// 呼び出し側
validateAge(25) ]=> validAge   // 25（成功）
validateAge(15) ]=> validAge   // throw 発動（エラー天井で捕捉可能）

// Result として受け取る（述語未評価）
validateAge(15) => result      // result: Result[Int, _]（まだ throw しない）
result ]=> validAge            // ここで述語が評価されて throw
```

### map / flatMap によるチェーン

Result はモナディック操作をサポートしています。

```taida
result <= Result[42, _ = true]()

// 成功時のみ変換します
doubled <= result.map(_ x = x * 2)

// 失敗時はそのまま伝播します
failed <= Result[0, _ = false](throw <= Error(type <= "Error", message <= "oops"))
failed.map(_ x = x * 2)  // throw がセットされたまま伝播
```

### getOrDefault / getOrThrow

```taida
result <= Result[42, _ = true]()

result.getOrDefault(0)   // 42
result.getOrThrow()      // 42

failed <= Result[0, _ = false](throw <= Error(type <= "Error", message <= "oops"))

failed.getOrDefault(0)   // 0
failed.getOrThrow()      // throw が発動します
```

---

## Gorillax -- 覚悟のエラーモデル

外部パッケージ（npm 等）の Molten（溶鉄）操作は安全が保証されません。Cage モールドで Molten への操作を実行し、結果を Gorillax で受け取ります。Cage は Molten 専用です。

### 基本: Cage → Gorillax → unmold

```taida
>>> npm:lodash => @(lodash)  // lodash: Molten

items: @[Int] <= @[1, 2, 3]
Cage[lodash, _ lo = lo.sum(items)] => rilax  // rilax: Gorillax[Int]
rilax ]=> total  // 成功 → total = 6, 失敗 → ゴリラ（プログラム終了）
```

Gorillax の unmold 失敗はゴリラと同じ -- `|==` ではキャッチできません。

### relax: キャッチ可能にする

`.relax()` を呼ぶと `RelaxedGorillax[T]` に変換されます。この型は unmold 失敗時に `RelaxedGorillaEscaped` エラーを throw します。`|==` でキャッチ可能です。

```taida
rilax.relax() => relaxed  // relaxed: RelaxedGorillax[Int]

|== error: RelaxedGorillaEscaped =
  | _ |> 0  // フォールバック値
=> :Int

relaxed ]=> total  // 失敗時: RelaxedGorillaEscaped が throw → |== でキャッチ
```

### エラーモデルの全体像

```
Lax 層:        失敗 → デフォルト値（プログラム続行）
throw 層:      失敗 → |== でキャッチ、またはゴリラ天井
Gorillax 層:   失敗 → ゴリラ（プログラム即終了）
  └ .relax():  失敗 → RelaxedGorillaEscaped（|== でキャッチ可能）
```

---

## パターン: エラーハンドリングのベストプラクティス

### 1. よくある失敗は Lax に任せる

ゼロ除算や範囲外アクセスのために throw/|== を書く必要はありません。Lax がすべて安全に処理します。

```taida
// 良い例: Lax に任せます
calculateAverage scores: @[Int] =
  Sum[scores]() ]=> total
  Div[total, scores.length()]() ]=> avg
  avg
=> :Int

// 不要: ゼロ除算のためにエラー処理を書く必要はありません
// | scores.isEmpty() |> Error(...).throw()  // これは過剰です
```

### 2. ビジネスロジックのエラーは throw で

ビジネスルールの違反など、処理を続行すべきでない場合は throw を使います。

```taida
Error => AuthError = @(userId: Str)
Error => PermissionError = @(action: Str)

deleteUser userId: Str requesterId: Str =
  |== error: Error =
    | error.type == "AuthError" |> @(success <= false, message <= "Authentication failed")
    | error.type == "PermissionError" |> @(success <= false, message <= "Permission denied")
    | _ |> @(success <= false, message <= "Unknown error")
  => :@(success: Bool, message: Str)

  | requesterId == "" |> AuthError(type <= "AuthError", message <= "Not authenticated", userId <= requesterId).throw()
  | requesterId != "admin" |> PermissionError(type <= "PermissionError", message <= "Admin only", action <= "delete").throw()
  | _ |>
    performDelete(userId)
    @(success <= true, message <= "Deleted")
=> :@(success: Bool, message: Str)
```

### 3. ガード節 + ゴリラで致命的な前提条件を守る

回復不能な前提条件の違反には `><` を使います。

```taida
initializeSystem config =
  | config.dbUrl == "" |> ><             // DB接続先なしは致命的です
  | config.port < 0 |> ><               // 不正なポートも致命的です
  | config.port > 65535 |> ><           // ポート範囲外も致命的です
  | _ |>
    db <= connectDatabase(config.dbUrl)
    startServer(config.port, db)
=> :Server
```

### 4. バリデーションチェーン

```taida
Error => ValidationError = @(field: Str)

validateAndProcess input =
  |== error: Error =
    @(success <= false, errors <= @[error.message])
  => :@(success: Bool, errors: @[Str])

  | input.name == "" |> ValidationError(type <= "ValidationError", message <= "Name required", field <= "name").throw()
  | input.email == "" |> ValidationError(type <= "ValidationError", message <= "Email required", field <= "email").throw()
  | input.age < 18 |> ValidationError(type <= "ValidationError", message <= "Must be 18+", field <= "age").throw()
  | _ |>
    result <= process(input)
    @(success <= true, errors <= @[])
=> :@(success: Bool, errors: @[Str])
```

---

## まとめ

| 概念 | 構文 | 説明 |
|------|------|------|
| **Lax** | `Div[x, y]()`, `get()` 等 | よくある失敗を安全に処理します。デフォルト値にフォールバックします |
| **Error 定義** | `Error => MyError = @(...)` | カスタムエラー型を定義します |
| **throw** | `.throw()` | Error 継承型のインスタンスでエラーを発生させます |
| **エラー天井** | `\|==` | throw されたエラーをキャッチして処理します |
| **ゴリラ天井** | 暗黙 | `\|==` がない場合の最後の番人です。ゴリラがプログラムを停止させます |
| **Result** | `Result[T, P]` | 述語 P で成功/失敗を判定する操作モールド型です |
| **ゴリラ** | `><` | 即時終了リテラルです。条件分岐と組み合わせて使います |
| **Gorillax** | `Gorillax[T]` | 覚悟のモールド型。unmold 失敗でゴリラ（プログラム終了） |
| **Cage** | `Cage[Molten, F]` | Molten 専用の操作檻。F(Molten) を実行し Gorillax[U] を返します |
| **RelaxedGorillax** | `.relax()` | Gorillax を throw 可能に変換。`\|==` でキャッチ可能になります |

### 使い分けの指針

| 状況 | 使うべきもの |
|------|------------|
| ゼロ除算、範囲外アクセス | Lax（自動的に安全） |
| 型変換の失敗 | Lax（`Int[x]()` 等が Lax を返す） |
| ビジネスルールの違反 | `throw` + `\|==` |
| 回復不能な前提条件の違反 | `><` ゴリラリテラル |
| 関数の戻り値としてのエラー表現 | `Result[T, P]`（`:Result[T, _]` で型推論） |
| 外部パッケージの Molten 操作 | `Cage` → `Gorillax`（失敗は致命的） |
| 外部操作の失敗をキャッチしたい | `.relax()` → `RelaxedGorillax` + `\|==` |
| エラーを握り潰さず確実に止めたい | ゴリラ天井（何もしなければ自動） |

---

# 関数

> **PHILOSOPHY.md — I.** 深く考えずに適当にぶちこんでけ

関数は Taida Lang の基本構成要素です。定義も呼び出しもシンプルに、深く考えずに書けます。

---

## 関数定義の基本

### 引数ありの関数

```taida
// 単一引数
double x: Int =
  x * 2
=> :Int

// 複数引数
add x: Int y: Int =
  x + y
=> :Int
```

関数本体は `=` の後に記述し、戻り型は `=> :Type` で指定します。`=> :Type` のインデントは関数定義と同じレベルです。

### 複数行の処理

```taida
processData data: Str =
  cleaned <= Trim[data]()
  upper <= Upper[cleaned]()
  upper
=> :Str
```

Taida では、文字列や数値の操作はメソッドではなくモールドで行います。トリムは `Trim[str]()` に、大文字変換は `Upper[str]()` です。

> **C13-1 の末尾バインド短縮形**: 関数本体の末尾が `name <= expr` / `expr => name` / `expr ]=> name` / `name <=[ expr` であるとき、束縛された値がそのまま関数の戻り値になります。上の例は以下のように書けます:
>
> ```taida
> processData data: Str =
>   cleaned <= Trim[data]()
>   upper <= Upper[cleaned]()   // 末尾バインド — 戻り値は `upper`
> => :Str
> ```
>
> 末尾の冗長な `upper` 行は不要です。詳細は `docs/guide/07_control_flow.md` を参照してください。

### 引数なし関数

引数のない関数は `= ... => :Type` の形式で定義します。

```taida
getVersion =
  "1.0.0"
=> :Str

getDefaultPilot =
  @(name <= "Rei", age <= 14, role <= "Pilot")
=> :@(name: Str, age: Int, role: Str)
```

### generic function

generic function は「計算手続きの抽象化」に限定します。`Mold` がデータ/solidify/unmold の抽象化を担うのに対し、generic function は inference-first で関数本体の型を共有するための仕組みです。

```taida
id[T] x: T =
  x
=> :T

first[T] xs: @[T] =
  xs.get(0)
=> :Lax[T]

mapValue[T, U] value: T fn: T => :U =
  fn(value)
=> :U

id(1)                              // Int
first(@["a", "b"]).unmold()        // "a"
mapValue(1, _ x = x.toString())    // "1"
```

制約が必要な場合は `T <= :Num` のように書きます。

```taida
clampMin[T <= :Num] x: T min: T =
  | x < min |> min
  | _ |> x
=> :T
```

ジェネリック関数の現在の制約:

- 呼び出しは推論のみです。`id(1)` は使えますが、呼び出し側での明示的な型引数 `id[Int](1)` は未対応です
- 各型変数は、少なくとも1つの引数の型注釈に現れる必要があります
- 型変数名に組み込み型名や既存の具象型名（`Int`, `User`, `Box` など）は使えません
- 制約は `T <= :Num` のようにヘッダー側で宣言します

```taida
id[T] x: T =
  x
=> :T

// NG: T が引数の型注釈に現れないので推論不能
// make[T] =
//   1
// => :T

// NG: Int は具象型名なので型変数名に使えない
// id[Int] x: Int =
//   x
// => :Int
```

---

## 型注釈

### 引数の型注釈

引数には必ず型を指定します。

```taida
greet name: Str =
  "Hello, " + name + "!"
=> :Str

calculate x: Int y: Float =
  Float[x]() + y
=> :Float
```

### 戻り型（省略不可）

戻り型は `=> :Type` で指定します。**戻り型の省略はできません。**すべての関数は戻り型を明示する必要があります。

```taida
add x: Int y: Int =
  x + y
=> :Int

// NG: 戻り型がないとコンパイルエラーになります
// add x: Int y: Int =
//   x + y
```

### 複雑な戻り型

ぶちパック型やモールディング型も戻り型に使えます。

```taida
createProfile name: Str age: Int =
  @(name <= name, age <= age, active <= true)
=> :@(name: Str, age: Int, active: Bool)

safeDivide x: Int y: Int =
  Div[x, y]()
=> :Lax[Int]
```

### 引数のデフォルト値

関数引数のデフォルト値仕様は `docs/design/function_default_args.md` で固定されています。

要点:

1. 引数は `name: Type`（型注釈必須）
2. `name: Type <= expr` で明示デフォルトを指定可能
3. 明示指定がない引数は、型のデフォルト値を使う
4. 呼び出し時に省略できるのは末尾引数のみ
5. 引数過多はコンパイルエラー

```taida
sum3 a: Int b: Int <= 10 c: Int <= 20 =
  a + b + c
=> :Int

sum3(1, 2, 3)  // 6
sum3(1, 2)     // 23
sum3(1)        // 31
sum3()         // 30
```


### 関数型シグネチャ

関数型は `:引数型 => :戻り型` の形式です。

```taida
:Int => :Str        // Int から Str への関数
:Int :Int => :Int   // Int, Int から Int への関数
```

---

## ラムダ関数

関数名の位置に `_` を使うと無名関数（ラムダ）になります。

```taida
// 基本形
_ x = x * 2

// 複数引数
_ x y = x + y

// 無名引数無し
x <= 12
_ = x
```

### ラムダは単一式

ラムダの本体は**単一の式**でなければなりません。`=>`、`<=`、`]=>`、`<=[` のいずれかが本体に現れた時点で、名前付き関数を使う必要があります。

```taida
// OK: 単一式
_ x = x * 2
_ x y = x + y
_ = 42

// NG: 演算子が現れたら名前付き関数にすること
// _ x =
//   result <= x * 2
//   result
```

単一式であるため、戻り型は式の型から推論されます。名前付き関数のような `=> :Type` は不要であり、書くこともできません。

### リスト操作での使用

ラムダはリスト操作のモールドと組み合わせて使います。

```taida
numbers <= @[1, 2, 3, 4, 5]

// Map: 各要素を変換します
Map[numbers, _ x = x * 2]() ]=> doubled       // @[2, 4, 6, 8, 10]

// Filter: 条件に合う要素を抽出します
Filter[numbers, _ x = x > 3]() ]=> filtered   // @[4, 5]

// Fold: 畳み込みで集約します
Fold[numbers, 0, _ acc x = acc + x]() ]=> total  // 15
```

---

## パイプライン

### 順方向パイプライン `=>`

`=>` でデータを左から右へ流します。`_` が前のステップの結果を受け取ります。

```taida
// データが左から右へ流れます
"  hello world  " => Trim[_]() => Upper[_]() => result
// result: "HELLO WORLD"

// 数値の変換
5 => add(3, _) => multiply(2, _) => result  // 16
```

### `<=` による代入

`<=` は右の値を左の変数に代入します。

```taida
result <= Upper["hello"]()
// result: "HELLO"
```

> **注意**: `<=` のチェーンによる逆方向パイプライン（`result <= f() <= g() <= data`）は現在サポートされていません。順方向パイプライン `=>` を使用してください。

### パイプラインでのモールド使用

操作がモールドなので、パイプラインとの組み合わせが自然です。

```taida
// 文字列処理パイプライン
"  Asuka Langley  " => Trim[_]() => Upper[_]() => Split[_, " "]() => result
// result: @["ASUKA", "LANGLEY"]

// 数値処理パイプライン
@[3, 1, 4, 1, 5, 9, 2, 6] => Sort[_]() => Unique[_]() => Filter[_, _ x = x > 3]() => result
// result: @[4, 5, 6, 9]
```

### 単一方向制約

一つの文で `=>` と `<=` を混在させることはできません。

```taida
// OK: => のみ
data => Filter[_, _ x = x > 0]() => Map[_, _ x = x * 2]() => result

// OK（仕様上有効だが、現在のパーサーは <= チェーン未対応。将来対応予定）:
// result <= Map[_, _ x = x * 2]() <= Filter[_, _ x = x > 0]() <= data

// NG: 混在はコンパイルエラーになります
data => Filter[_, _ x = x > 0]() <= result  // コンパイルエラー
```

---

## 部分適用（空スロット）

関数呼び出しの引数位置を空にすると、その位置が「穴」になり、部分適用された関数が返ります。

```taida
// 第2引数を空にします（穴）
add5 <= add(5, )
result <= add5(3)  // 8

// 第1引数を空にします
doubleIt <= multiply(, 2)
result <= doubleIt(5)  // 10

// 複数の穴
both <= add(, )
result <= both(3, 5)  // 8
```

穴の有無で通常呼び出しと部分適用が区別されます。

```taida
add(5, 3)   // 通常呼び出し → 8
add(5, )    // 部分適用 → :Int => :Int の関数
add(5)      // 通常呼び出し（第2引数はデフォルト値）
```

> 注: 部分適用は通常の関数呼び出しのみに適用されます。TypeDef やモールドのインスタンス化には使用できません。

> 注: 引数に `_` を渡す構文 `add(5, _)` は使えません。空スロット `add(5, )` を使用してください。`taida check` で `[E1502]` として拒否されます。

> 注: 関数オーバーロード（同じ名前の関数を異なる引数パターンで複数定義すること）は Taida Lang では禁止されています。`taida check` で `[E1501]` として拒否されます。

---

## 末尾再帰最適化

Taida は末尾再帰を自動検出し、トランポリン方式で最適化します。アノテーションは不要です。スタックオーバーフローを気にせずに再帰が書けます。

### 基本パターン: アキュムレータ

```taida
factorial n: Int acc: Int =
  | n < 2 |> acc
  | _ |> factorial(n - 1, acc * n)
=> :Int

result <= factorial(10000, 1)  // スタックオーバーフローしません
```

### フィボナッチ数列

```taida
fibonacci n: Int a: Int b: Int =
  | n == 0 |> a
  | _ |> fibonacci(n - 1, b, a + b)
=> :Int

fib10 <= fibonacci(10, 0, 1)  // 55
```

### エラー天井内の末尾位置

エラー天井 `|==` 内での末尾再帰も最適化されます。

```taida
retryLoop maxRetries: Int attempt: Int =
  |== error: Error =
    | attempt < maxRetries |> retryLoop(maxRetries, attempt + 1)
    | _ |> "Failed after retries"
  => :Str

  riskyOperation()
=> :Str
```

### 末尾位置の判定

以下の位置にある再帰呼び出しが末尾再帰として最適化されます。

- 関数本体の最後の式
- 条件分岐 `| ... |>` の各分岐の最後
- エラー天井 `|==` 内の最後

再帰呼び出しの後に演算がある場合は末尾位置ではありません。

```taida
// OK: 末尾位置（最適化されます）
| _ |> factorial(n - 1, acc * n)

// NG: 末尾位置ではない（乗算が後続するため最適化されません）
| _ |> n * factorial(n - 1)
```

### 相互再帰

2つ以上の関数が互いを末尾位置で呼び出す相互再帰も、自動的に最適化されます。

```taida
isEven n: Int =
  | n == 0 |> 1
  | _ |> isOdd(n - 1)
=> :Int

isOdd n: Int =
  | n == 0 |> 0
  | _ |> isEven(n - 1)
=> :Int

stdout(isEven(100000))  // スタックオーバーフローしません
```

詳しくは [末尾再帰最適化リファレンス](../reference/tail_recursion.md) を参照してください。

---

## まとめ

| 概念 | 構文 |
|------|------|
| 関数定義 | `name args: Type = body => :ReturnType` |
| 引数なし関数 | `name = body => :ReturnType` |
| ラムダ | `_ x = expr` |
| 順方向パイプライン | `data => f(_) => g(_) => result` |
| 逆方向パイプライン | `result <= g(_) <= f(_) <= data` **(将来対応予定)** |
| 部分適用 | `add(5, )` 空スロットで穴を指定 |
| 末尾再帰 | アキュムレータパターンで自動最適化 |

次のガイド: [モジュールシステム](10_modules.md)

---

# モジュールシステム

> **PHILOSOPHY.md — I.** 深く考えずに適当にぶちこんでけ

モジュール管理は2つの演算子だけです。`>>>` がインポート、`<<<` がエクスポートです。よく使う関数はプリリュードとして最初から使えます。

---

## プリリュード

インポート不要で、どのファイルからでも使える機能です。2つの層があります。

### 言語組込み（Layer 0）

演算子や構文と同じレベルで組み込まれています。モールドとして提供されます。

| カテゴリ | 例 |
|---------|-----|
| HOF モールド | `Map`, `Filter`, `Fold`, `Foldr`, `Reduce`, `Take`, `TakeWhile`, `Drop`, `DropWhile` |
| 文字列モールド | `Upper`, `Lower`, `Trim`, `Split`, `Replace`, `Slice`, `CharAt`, `Repeat`, `Reverse`, `Pad` |
| 数値モールド | `ToFixed`, `Abs`, `Floor`, `Ceil`, `Round`, `Truncate`, `Clamp` |
| リストモールド | `Concat`, `Append`, `Prepend`, `Join`, `Sum`, `Sort`, `Unique`, `Flatten`, `Find`, `FindIndex`, `Count`, `Zip`, `Enumerate` |
| 型変換モールド | `Str[x]()`, `Int[x]()`, `Float[x]()`, `Bool[x]()` |
| 演算モールド | `Div[x, y]()`, `Mod[x, y]()` |
| JSON モールド | `JSON[raw, Schema]()` |
| 非同期モールド | `Async[T]`, `All`, `Race`, `Timeout` |
| モールディング型 | `Result[T, P]`, `Lax[T]`, `Gorillax[T]`, `Cage[Molten, F]` |
| JS 補助モールド | `JSNew`, `JSSet`, `JSBind`, `JSSpread`（JS バックエンド専用） |

詳細は [モールディング型](05_molding.md) を参照してください。

### プリリュード関数（Layer 1）

| 関数 | 説明 |
|------|------|
| `stdout(value)` | 標準出力に出力します |
| `stderr(value)` | 標準エラー出力に出力します |
| `stdin()` | 標準入力から1行読み取ります |
| `jsonEncode(value)` | 値を JSON 文字列に変換します |
| `jsonPretty(value)` | 値を整形された JSON 文字列に変換します |
| `debug(value)` | 値をそのまま出力します。`debug(value, "label")` でラベル付き出力 |
| `typeof(x)` | 型名を文字列で返します |
| `range(start, end)` | 整数リストを生成します |
| `enumerate(list)` | インデックス付きリストを返します |
| `zip(a, b)` | 2つのリストを組み合わせます |
| `assert(cond, msg)` | 条件が false なら throw します |
| `hashMap(entries)` | HashMap を生成します |
| `setOf(items)` | Set を生成します |

```taida
// import は不要です
stdout("Hello, World!")
stderr("Error occurred")

input <= stdin()
stdout("You typed: " + input)

pilot <= @(name <= "Rei", age <= 14)
json <= jsonEncode(pilot)
stdout(json)  // {"name":"Rei","age":14}

debug(pilot, "check")  // [check] BuchiPack: @(name <= "Rei", age <= 14)
typeof(42)              // "Int"
```

---

## インポート `>>>`

### ローカルモジュール

`>>> ./path.td => @(symbols)` でローカルファイルからシンボルをインポートします。

```taida
// 同じディレクトリのファイルから
>>> ./utils.td => @(helper, format)

// 親ディレクトリのファイルから
>>> ../shared/common.td => @(constants)
```

### シンボル指定の省略

`=> @(symbols)` を省略すると、対象モジュールがエクスポートした全シンボルをインポートします。

```taida
>>> ./utils.td                    // utils.td の全エクスポートを取り込む
>>> ./utils.td => @(helper)       // helper だけを取り込む
```

明示的にシンボルを指定することを推奨します。省略すると名前衝突のリスクがあります。

### エイリアス

インポート時にシンボルの名前を変更できます。

```taida
>>> ./math.td => @(add, subtract => sub)
// subtract を sub として使用できます
result <= sub(10, 3)  // 7
```

### npm パッケージ（JS バックエンドのみ）

`>>> npm:package => @(symbols)` で npm パッケージをインポートします。JS バックエンドでのみ動作します。

npm からインポートされた値は **Molten** 型です。Molten は外部由来の不透明値であり、直接操作はできません。型安全な値を取り出すには Cage 経由で操作します。

```taida
>>> npm:express => @(express)  // express: Molten

// Cage 内で Molten の関数を呼び出します（直接呼び出しは不可）
Cage[express, _ e = e()]() ]=> app       // app: Molten（express() の結果）

// JS 補助モールドは Cage 外でも使えます（Taida のモールド構文）
JSNew[express.Router, @()]() => router   // router: Molten

// Cage で Molten から Taida の型世界に値を持ち込みます
Cage[app, _ a = a.listen(3000)]() => result  // result: Gorillax
result ]=> server                            // server: 値（またはゴリラ）
```

**型の流れ:**

```
npm import (Molten) → JSNew 等 (Molten→Molten) → Cage (Molten→Gorillax) → ]=> (値)
```

インタプリタおよび Native バックエンドで `npm:` インポートを使用するとコンパイルエラーになります。JS 補助モールド（JSNew, JSSet, JSBind, JSSpread）も同様です。

### 外部パッケージ

```taida
>>> author/package => @(funcA, funcB)
```

### 使用例

```taida
>>> ./utils.td => @(helper, double)

result <= double(8)       // 16
processed <= helper(data)
stdout(result)
```

---

## エクスポート `<<<`

### 複数シンボル

```taida
add x: Int y: Int = x + y => :Int
subtract x: Int y: Int = x - y => :Int
Point = @(x: Int, y: Int)

<<< @(add, subtract, Point)
```

### 複数行エクスポート

通常の `.td` ファイルでは `<<<` を複数行に分けて書くことができます。

```taida
<<< @(add, subtract)
<<< @(Point)
```

これは1行にまとめた場合と同じ効果です。ただし packages.tdm では `<<<` は1行のみ許可されます。

### 単一シンボル

```taida
<<< add
```

### ワンライナー

```taida
<<< double x: Int = x * 2 => :Int
```

### 構造化エクスポート

```taida
mathUtils <= @(
  add x: Int y: Int = x + y => :Int,
  subtract x: Int y: Int = x - y => :Int,
  PI <= 3.14159
)

<<< mathUtils
```

---

## モジュールの構成パターン

### ユーティリティモジュール（utils.td）

```taida
capitalize text: Str =
  | text == "" |> ""
  | _ |>
    first <= CharAt[text, 0]()
    rest <= Slice[text](start <= 1)
    Upper[first]() + rest
=> :Str

clamp value: Int min: Int max: Int =
  | value < min |> min
  | value > max |> max
  | _ |> value
=> :Int

<<< @(capitalize, clamp)
```

### 型定義モジュール（types.td）

```taida
Staff = @(
  id: Int
  name: Str
  rank: Str
  active: Bool
)

<<< @(Staff)
```

### メインモジュール（main.td）

```taida
>>> ./utils.td => @(capitalize, clamp)
>>> ./types.td => @(Staff)

asuka <= Staff(
  id <= 1,
  name <= "asuka",
  rank <= "Pilot",
  active <= true
)
displayName <= capitalize(asuka.name)
stdout(displayName)  // "Asuka"
```

---

## 実行モデル

### プログラムの実行

```bash
$ taida ./main.td
```

指定されたファイルのトップレベルコードが上から順に実行されます。

### ライブラリ vs 実行可能ファイル

ファイル自体に区別はありません。呼び出し方で決まります。

| 呼び出し方 | 動作 |
|------------|------|
| `$ taida ./file.td` | エントリーポイントとして実行されます |
| `>>> ./file.td => @(...)` | ライブラリとしてインポートされます |

### 二重実行の防止

同じファイルが複数回インポートされても、トップレベルコードは1回のみ実行されます。

### 循環参照の検出

循環参照は自動検出され、コンパイルエラーになります。

```taida
// a.td
>>> ./b.td => @(funcB)
<<< funcA

// b.td
>>> ./a.td => @(funcA)  // コンパイルエラー: 循環参照
<<< funcB
```

解決策は共通モジュールに抽出することです。

---

## packages.tdm（パッケージマニフェスト）

`packages.tdm` はパッケージの静的マニフェストです。依存宣言とパッケージの公開 API を1ファイルに集約します。

**packages.tdm は実行されません。** `>>>` と `<<<` のみが許可され、式・代入・関数定義は書けません。

```taida
// packages.tdm の例
>>> taida-lang/os@a.1
>>> ./main.td => @(hello, greet)

<<<@a.3 @(hello, greet)
```

### packages.tdm と通常の .td の違い

| | packages.tdm | 通常の .td |
|---|---|---|
| 実行 | されない（静的解釈のみ） | される |
| `>>>` のバージョン指定 | 可能（`@a.1` 等） | 不可 |
| `<<<` のバージョン指定 | 可能（`@a.3` 等、publish が管理） | 不可 |
| `<<<` の行数 | 1行のみ | 複数行可 |
| 式・代入・関数定義 | 禁止 | 可 |

### 役割の使い分け

| 用途 | エントリーポイント | packages.tdm の役割 |
|------|-------------------|-------------------|
| アプリ（`taida run`） | `main.td` | 依存宣言のみ |
| ライブラリ（`>>> author/pkg@a.1`） | packages.tdm が指す実コード | 依存 + 公開 API 宣言 |

---

## まとめ

| 構文 | 用途 |
|------|------|
| `stdout(value)` | 標準出力（プリリュード、import不要） |
| `>>> ./ファイル.td => @(シンボル)` | ローカルインポート |
| `>>> ./ファイル.td` | ローカルインポート（全エクスポートを取り込む） |
| `>>> npm:パッケージ => @(シンボル)` | npm パッケージインポート（JSのみ、Molten 型で取得） |
| `>>> パッケージ@ver => @(シンボル)` | バージョン指定インポート（packages.tdm のみ） |
| `<<< @(シンボル1, シンボル2)` | エクスポート（複数行可） |
| `<<< シンボル` | 単一エクスポート |

前のガイド: [関数](09_functions.md) | 次のガイド: [非同期処理](11_async.md)

---

# 非同期処理

> **PHILOSOPHY.md — I.** 深く考えずに適当にぶちこんでけ
>
> 系: 「待つ時は待つ、でも待ち方は考えない」

---

## Async[T] とは

`Async[T]` は非同期操作を表現するモールディング型です。I/O 操作やネットワーク通信など、完了までに時間がかかる処理を型安全に扱います。

`Async[T]` はビルトインのモールディング型です。インポートは不要です。

---

## `]=>` による暗黙的 await

`]=>` でアンモールディングすると、暗黙的に await として機能します。待ち方を考える必要はありません。

```taida
// 非同期操作の結果を取得します
result <= someAsyncOp()
result ]=> data  // ここでブロックして解決を待ちます
stdout(data)
```

`async/await` のようなキーワードは存在しません。`]=>` が唯一の待機手段です。

---

## 即時解決 / 即時拒否

テストやモック用に、即座に解決・拒否する Async を作成できます。

```taida
// 即座に解決します
resolved <= Async[42]()

// 即座に拒否します（AsyncReject モールドを使用）
rejected <= AsyncReject["timeout error"]()
```

---

## 非同期操作の連鎖

複数の非同期操作を順番に実行するには、`]=>` で一つずつ結果を取り出します。

```taida
// ユーザーを取得して、そのユーザーの投稿を取得します
userAsync <= fetchUser(1)
userAsync ]=> user
postsAsync <= fetchPosts(user.id)
postsAsync ]=> posts
stdout(posts)
```

関数にまとめることもできます。

```taida
fetchUserPosts userId: Int =
  |== error: Error =
    @[]
  => :@[Post]

  userAsync <= fetchUser(userId)
  userAsync ]=> user
  postsAsync <= fetchPosts(user.id)
  postsAsync ]=> posts
  posts
=> :@[Post]
```

---

## map による同期的変換

`map` メソッドで、非同期値を同期的に変換できます。非同期操作自体は増えません。

```taida
nameAsync <= fetchUser(1)
  .map(_ user = Upper[user.name]())
// nameAsync: Async[Str]

nameAsync ]=> name
stdout(name)  // 大文字に変換されたユーザー名
```

---

## 非ブロッキング取得

`getOrDefault` を使うと、解決を待たずにデフォルト値を返すことができます。

```taida
result <= someAsyncOp()
data <= result.getOrDefault(@(items <= @[]))
// pending や rejected の場合はデフォルト値を返します
```

---

## エラーハンドリング

エラー天井 `|==` を使って非同期操作のエラーを処理します。`]=>` でアンモールディングした際にエラーが発生すると、エラー天井にジャンプします。

```taida
fetchData id: Int =
  |== error: Error =
    @(found <= false, data <= "")
  => :@(found: Bool, data: Str)

  result <= someAsyncOp(id)
  result ]=> data  // 拒否された場合、ここでエラー天井へジャンプします

  @(found <= true, data <= data)
=> :@(found: Bool, data: Str)
```

エラー天井 `|==` がない場合は、ゴリラ天井がキャッチしてプログラムを停止させます。

### リトライパターン

末尾再帰と組み合わせたリトライパターンです。

```taida
retryLoop maxRetries: Int attempt: Int =
  |== error: Error =
    | attempt < maxRetries |> retryLoop(maxRetries, attempt + 1)
    | _ |> @(success <= false, data <= "")
  => :@(success: Bool, data: Str)

  result <= riskyAsyncOp()
  result ]=> data
  @(success <= true, data <= data)
=> :@(success: Bool, data: Str)

// 最大3回リトライ
outcome <= retryLoop(3, 0)
```

---

## Async[T] メソッド一覧

| メソッド | シグネチャ | 説明 |
|---------|-----------|------|
| `isPending()` | `=> :Bool` | 未解決かどうかを返します |
| `isFulfilled()` | `=> :Bool` | 解決済みかどうかを返します |
| `isRejected()` | `=> :Bool` | 拒否されたかどうかを返します |
| `map(fn)` | `:T => :U => :Async[U]` | 値の同期変換を行います |
| `getOrDefault(default)` | `T => :T` | デフォルト値付きの非ブロッキング取得です |
| `unmold()` | `=> :T` | 値を取り出します（ブロッキング await） |
| `toString()` | `=> :Str` | 文字列表現を返します |

---

## 並列実行とタイムアウト

`All`、`Race`、`Timeout` の各モールドに加えて、時間系 Prelude 最小カーネル `nowMs` / `sleep` が利用できます。

```taida
// All: 全ての非同期操作の完了を待ちます
asyncOps <= @[Async[1](), Async[2](), Async[3]()]
allResult <= All[asyncOps]()
allResult ]=> results  // @[1, 2, 3]

// Race: 最初に完了した結果を返します
raceResult <= Race[asyncOps]()
raceResult ]=> winner  // 最初の要素が返されます

// Timeout: タイムアウト付きで結果を待ちます
timeoutResult <= Timeout[someAsync, 5000]()
timeoutResult ]=> data  // タイムアウト前に完了すれば値を返します

// nowMs/sleep: 最小時間プリミティブ
start <= nowMs()
wait <= sleep(20)
wait ]=> _done
end <= nowMs()
stdout((end - start).toString())
```

`sleep(ms)` は `Async[Unit]` を返します。`ms` は `Int` かつ `0..=2_147_483_647` の範囲です。範囲外は rejected `Async` になります。

`nowMs()` は wall-clock（epoch ミリ秒）であり、単調時計ではありません。厳密な経過時間測定には差分と許容誤差を併用してください。

---

## まとめ

| 概念 | 構文 |
|------|------|
| Async の await | `asyncValue ]=> result` |
| エラーハンドリング | `\|== error: Error = ...` |
| 同期的変換 | `.map(_ x = ...)` |
| 非ブロッキング取得 | `.getOrDefault(value)` |
| 即時解決 | `Async[value]()` |
| 即時拒否 | `AsyncReject[error]()` |

前のガイド: [モジュールシステム](10_modules.md) | 次のガイド: [構造的イントロスペクション](12_introspection.md)

---

# 構造的イントロスペクション

> **PHILOSOPHY.md — IV.** キモい言語だ。だが、書くのも読むのもAI。眺めるのが人間の仕事。
>
> 系: 「コードの構造は、コード自身が語る」

---

## 構造的イントロスペクションとは

Taida は10種の演算子で全てを表現します。各演算子の意味は一意で、重複しません。そのため、**構文を走査するだけでコードの構造をグラフとして構築できます**。型推論や制御フロー解析は不要です。

他の言語では同じ処理を複数の構文で書けます（`return`, `yield`, `.then()`, コールバックなど）。Taida ではデータフローは `=>` か `<=` のどちらかだけです。この制約により、グラフが一意に確定します。

| 演算子 | グラフ上の意味 |
|--------|---------------|
| `=` | ノード生成 |
| `=>` | 順方向エッジ |
| `<=` | 逆方向エッジ |
| `]=>` | アンモールドエッジ（順方向） |
| `<=[` | アンモールドエッジ（逆方向） |
| `\|==` | エラー境界ノード |
| `\|` `\|>` | 条件エッジ |
| `>>>` | 依存エッジ（入） |
| `<<<` | 依存エッジ（出） |

---

## 5つのグラフビュー

### 1. データフローグラフ

`=>` / `<=` / `]=>` / `<=[` を追跡して、値がどこからどこへ流れるかを可視化します。

```taida
input <= "  asuka langley  "
input => Trim[_]() => Upper[_]() => result
```

```
[input: "  asuka langley  "] --(PipeForward)--> [Trim[_]()]
  --(PipeForward)--> [Upper[_]()]
  --(PipeForward)--> [result]
```

### 2. モジュール依存グラフ

`>>>` / `<<<` を追跡して、ファイル間の依存関係を可視化します。

```taida
>>> ./utils.td => @(helper, format)
>>> ./types.td => @(Staff, Config)
<<< @(main)
```

```
[main.td] --(Imports)--> [./utils.td] {helper, format}
[main.td] --(Imports)--> [./types.td] {Staff, Config}
[main.td] --(Exports)--> {main}
```

### 3. 型階層グラフ

`Mold[T] =>` や `Error =>` による継承関係を追跡します。

```
Staff
  +-- Commander
  +-- Operator

Mold[T]
  +-- Result[T, P]
  +-- Lax[T]
  +-- Async[T]

Error
  +-- ValidationError
  +-- NetworkError
```

### 4. エラー境界グラフ

`|==` と `.throw()` サイトの関係を追跡します。

```
[processData]
  +-- ErrorCeiling(Error)
        +-- Catches <-- ThrowSite(InputError) at line 8
        +-- Catches <-- (any Error thrown by transform())
```

ゴリラ天井は暗黙のエラー境界として、キャッチされなかったエラーを最終的に受け止めます。

### 5. コールグラフ

関数呼び出しの関係を追跡します。

```
processAll
  +-- Calls --> double
  |               +-- Calls --> add
  +-- Calls --> Map[...]
  +-- Calls --> Filter[...]
  +-- Calls --> add
```

---

## verify（構造的自己検証）

`taida verify` コマンドで、コードの構造的な健全性を検証できます。  
最新のCLIオプションは [CLI リファレンス](../reference/cli.md) を参照してください。

### CLI コマンド

```bash
# 全検証を実行します
taida verify ./src

# 特定の検証のみ
taida verify --check direction-constraint ./src
taida verify --check error-coverage ./src
taida verify --check no-circular-deps ./src
taida verify --check dead-code ./src

# JSON / SARIF 出力
taida verify --format json ./src
taida verify --format sarif ./src
```

### 出力例

```
$ taida verify ./src
[PASS] direction-constraint: 全ファイルが単一方向制約を満たしています
[PASS] error-coverage: 全ての throw サイトがエラー天井でカバーされています
[WARN] dead-code: 2つの未使用関数が検出されました
  - src/utils.td:15 deprecatedHelper
  - src/utils.td:42 oldFormat
[PASS] no-circular-deps: 循環依存はありません
[PASS] type-consistency: 型階層に不整合はありません

結果: 4 passed, 1 warning, 0 errors
```

### グラフの抽出・可視化

```bash
# データフローグラフ
taida graph --type dataflow ./src/main.td

# モジュール依存グラフ
taida graph --type module ./src/main.td

# 型階層グラフ
taida graph --type type-hierarchy ./src/main.td

# エラー境界グラフ
taida graph --type error ./src/main.td

# コールグラフ
taida graph --type call ./src/main.td

# 出力形式の指定
taida graph --type dataflow --format mermaid ./src/main.td
taida graph --type module --format dot ./src/main.td
taida graph --type call --format json ./src/main.td

# 構造サマリの生成
taida graph summary ./src/main.td
```

### 構造クエリ

グラフに対して構造的なクエリを発行できます。

```bash
# パス存在性
taida graph query --type dataflow --query "path_exists(input, result)" ./src/main.td
# => true: input -> Trim -> Upper -> result

# 循環検出
taida graph query --type module --query "find_cycles()" ./src/main.td
# => No cycles found.

# 到達可能性
taida graph query --type dataflow --query "reachable(input)" ./src/main.td
# => [Trim, Upper, result]

# エラーカバレッジ
taida graph query --type error --query "uncovered_throws()" ./src/main.td
# => All throw sites are covered.

# デッドコード検出
taida graph query --type call --query "unreachable_functions()" ./src/main.td
# => [unusedHelper, deprecatedFunc]
```

---

## AI 協業タグ

ドキュメントコメントにタグをつけることで、AI との協業を促進します。

### `@AI-Related`

関連するシンボルを明示します。AI がコードを変更する際に、影響範囲を把握するために使います。

```taida
///@ AI-Related: validateStaff, saveStaff, Staff
createStaff name: Str rank: Str =
  validated <= validateStaff(name, rank)
  saveStaff(validated)
=> :Staff
```

`@AI-Related` タグは現状 `taida verify` の個別チェック対象ではありません。  
`taida doc generate` で抽出されるドキュメント情報として活用します。

### `@AI-SideEffects`

副作用を持つ関数であることを明示します。

```taida
///@ AI-SideEffects: writes to database
saveRecord record: Record =
  ...
=> :Result[Record, _]
```

### `@Throws`

関数がスローする可能性のあるエラー型を明示します。

```taida
///@ Throws:
///@   - ValidationError: 入力が不正な場合
///@   - NetworkError: 接続エラー
fetchStaff id: Int =
  ...
=> :Staff
```

`@Throws` タグも同様に、現状はドキュメント用途で扱います。

---

## 構造サマリ

AI が消費するための機械可読フォーマットです。

```bash
taida graph summary ./src/main.td
```

```json
{
  "version": "1.0",
  "project": "nerv-ops",
  "stats": {
    "files": 12,
    "functions": 45,
    "types": 18,
    "mold_types": 6,
    "error_types": 4
  },
  "dataflow": {
    "total_pipes": 128,
    "forward_pipes": 95,
    "backward_pipes": 33,
    "unmold_operations": 22
  },
  "modules": {
    "total_imports": 34,
    "total_exports": 28,
    "has_cycles": false
  },
  "errors": {
    "total_ceilings": 15,
    "total_throw_sites": 23,
    "uncovered_throws": 0
  }
}
```

---

## 他言語との比較

| 特性 | Taida | TypeScript | Rust | Python |
|------|-------|------------|------|--------|
| 演算子数 | 10 | 50+ | 60+ | 30+ |
| データフロー方向の確定性 | 決定的 | 非決定的 | 非決定的 | 非決定的 |
| グラフ抽出に必要な解析 | 構文走査のみ | 型推論 + 制御フロー解析 | 所有権解析 | 動的解析が必要 |
| 単一方向制約 | あり | なし | なし | なし |

Taida の強みは、構文走査だけでグラフが構築でき、AI が生成したコードの構造を即座に検証できる点にあります。

---

## まとめ

| 概念 | 内容 |
|------|------|
| グラフ抽出 | 演算子の意味が一意なので構文走査だけで構築できます |
| 5つのビュー | DataFlow, Module, TypeHierarchy, Error, CallGraph |
| verify | 構造的な健全性を自動検証します |
| AI 協業タグ | `@AI-Related`, `@AI-SideEffects`, `@Throws` |
| 構造サマリ | AI が消費する JSON フォーマットで出力できます |

前のガイド: [非同期処理](11_async.md)

---

# Creating Addons (RC1.5)

> **PHILOSOPHY.md — IV.** キモい言語だ。だが、書くのも読むのもAI。眺めるのが人間の仕事。

Addons extend Taida Lang with Rust-backed functions that the main
binary loads at runtime. An addon is a Rust `cdylib` plus a
`native/addon.toml` manifest that pins the ABI, the package name, the
function table, and (optionally) prebuild distribution metadata so
users can `taida install` without needing a Rust toolchain.

This guide is aimed at addon *authors*. See `docs/reference/addon_manifest.md`
(RC15B-106/107) for the manifest reference and forward-compat policy.

---

## 1. Directory layout

A minimal addon crate sits alongside (or inside) your package:

```
my-addon/
  packages.tdm                  # Taida package manifest
  Cargo.toml                    # cdylib crate
  src/lib.rs                    # addon entry point
  native/
    addon.toml                  # RC1.5 install-time manifest
```

`Cargo.toml` must declare the crate as a `cdylib`:

```toml
[lib]
crate-type = ["cdylib"]
```

and depend on the in-tree `taida-addon` crate for the ABI types.

---

## 2. The addon.toml manifest

A minimal manifest without prebuild distribution (RC1 mode — users must
place the `.so` themselves) looks like:

```toml
abi = 1
entry = "taida_addon_get_v1"
package = "my-org/my-addon"
library = "my_addon"

[functions]
greet = 1
```

To ship a prebuild that `taida install` can fetch, add a
`[library.prebuild]` section (RC1.5):

```toml
[library.prebuild]
url = "https://github.com/my-org/my-addon/releases/download/v{version}/lib{name}-{target}.{ext}"

[library.prebuild.targets]
"x86_64-unknown-linux-gnu"  = "sha256:<64 lowercase hex chars>"
"aarch64-unknown-linux-gnu" = "sha256:..."
"x86_64-apple-darwin"       = "sha256:..."
"aarch64-apple-darwin"      = "sha256:..."
"x86_64-pc-windows-msvc"    = "sha256:..."
```

### URL template variables

| Variable    | Expands to |
|-------------|------------|
| `{version}` | The exact version resolved by `taida install` |
| `{target}`  | The host target triple (e.g. `x86_64-unknown-linux-gnu`) |
| `{ext}`     | Platform cdylib extension (`so`, `dylib`, `dll`) |
| `{name}`    | The `[library] name` value |

Unknown variables, unbalanced braces, and `{{` / `}}` escapes are
rejected at manifest parse time — there is no tolerance for typos.

### Supported host targets

| Triple | Status |
|--------|--------|
| `x86_64-unknown-linux-gnu`  | Baseline (RC1.5 v1) |
| `aarch64-unknown-linux-gnu` | Baseline (RC1.5 v1) |
| `x86_64-apple-darwin`       | Baseline (RC1.5 v1) |
| `aarch64-apple-darwin`      | Baseline (RC1.5 v1) |
| `x86_64-pc-windows-msvc`    | Baseline (RC1.5 v1) |
| `x86_64-unknown-linux-musl`  | Extension (RC15B-003) |
| `aarch64-unknown-linux-musl` | Extension (RC15B-003) |
| `i686-unknown-linux-gnu`     | Extension (RC15B-003) |
| `riscv64gc-unknown-linux-gnu`| Extension (RC15B-003) |
| `x86_64-unknown-freebsd`     | Extension (RC15B-003) |

You do not have to ship binaries for every target — only the ones you
have tested. Users on unlisted targets will get a deterministic
`addon is not available for your platform` error at install time,
which lists the targets your manifest does declare.

### SHA-256 integrity

The `targets` values are always lowercase `sha256:` + 64 hex chars.
Uppercase hex is rejected for canonical form. `taida install`
streams the downloaded bytes through SHA-256 and aborts with a
structured error on mismatch — there is no silent fallback.

### Reserved: `[library.prebuild.signatures]`

RC15B-005 reserves a `signatures` sub-table for future GPG / detached
signature verification:

```toml
[library.prebuild.signatures]
"x86_64-unknown-linux-gnu" = "gpg:<opaque-identifier>"
```

Values must start with `gpg:` and carry a non-empty printable-ASCII
payload. Taida currently **parses and stores** these values but does
not verify them. Adding them now is safe — older taidas that don't
understand the section will reject the manifest, which is the
intended forward-compat policy (see
`docs/reference/addon_manifest.md`).

---

## 3. Releasing prebuilds

The `.github/workflows/addon-prebuild-template.yml` template
(RC15B-004) automates the build-and-upload pipeline for the 5
baseline targets:

1. Copy the template into your addon repository.
2. Adjust `ADDON_NAME` and `CRATE_DIR` at the top of the file.
3. Uncomment the `push: tags:` trigger.
4. Push a `vX.Y.Z` tag.
5. The workflow builds for each target in the matrix, computes
   SHA-256 hashes, uploads the binaries to the matching GitHub
   Release, and also attaches a `prebuild-targets.toml.txt`
   fragment you can paste directly into your
   `[library.prebuild.targets]` block.

RC15B-003 extension targets (musl, i686, riscv64, FreeBSD) are
commented out in the template. Enable them one at a time after
verifying your crate builds cleanly on each — they typically need
`cross` on GitHub-hosted runners.

---

## 4. How `taida install` fetches prebuilds

When a package has a `native/addon.toml` with a `[library.prebuild]`
section, `taida install`:

1. Detects the host target (`HostTarget::detect_host_target`).
2. Looks the host triple up in `[library.prebuild.targets]`.
   Unknown host → deterministic error listing every target the
   manifest declares.
3. Expands `{version}`, `{target}`, `{ext}`, `{name}` in the URL
   template.
4. Downloads the binary over HTTPS (up to 10 redirects, see
   RC15B-106) or reads a `file://` URL (relative paths only; see
   `docs/reference/addon_manifest.md` for the security model).
5. Streams the bytes through SHA-256 and rejects any mismatch.
6. Caches the verified binary under
   `~/.taida/addon-cache/<org>/<name>/<version>/<target>/lib<name>.<ext>`
   and places a working copy at
   `.taida/deps/<pkg>/native/lib<name>.<ext>`.
7. Writes the target+hash pair into `taida.lock` as a
   `[[package.addon]]` sub-table so reproducible installs can
   verify the chain without re-downloading.

Downloads larger than ~256 KiB show a byte-count progress indicator
on stderr (RC15B-002). Users can force a re-download with
`taida install --force-refresh`, or prune the cache entirely with
`taida cache clean --addons` (RC15B-001).

---

## 5. Testing locally with `file://`

During development you do not need to publish to GitHub. Point the
URL template at a relative `file://` path:

```toml
[library.prebuild]
url = "file://target/release/libmy_addon.so"

[library.prebuild.targets]
"x86_64-unknown-linux-gnu" = "sha256:<compute this after each build>"
```

Constraints:

- Only **relative** paths are accepted under `file://`. Absolute
  paths and `..` components are rejected before any filesystem
  access (RC15B-101).
- The path is resolved relative to the project root containing
  `packages.tdm`.
- The SHA-256 must be updated every time you rebuild, because the
  integrity check still runs.

This is how the in-tree `taida-addon-terminal-sample` crate is
exercised in `tests/addon_terminal_install_e2e.rs`.

---

## 6. Checklist before releasing

- [ ] `cargo build --release --target <triple>` succeeds for every
      target in `[library.prebuild.targets]`
- [ ] SHA-256s in the manifest match the uploaded artefacts
- [ ] `taida install` completes end-to-end against a local
      `file://` URL before you tag the release
- [ ] The `[functions]` table lists every symbol your `cdylib`
      exports through `declare_addon!`
- [ ] Your README tells users the **minimum supported taida
      version** (older taidas will reject unknown manifest keys by
      design; see `docs/reference/addon_manifest.md`)

---

# Addon Manifest Reference (`native/addon.toml`)

> **PHILOSOPHY.md — IV.** キモい言語だ。だが、書くのも読むのもAI。眺めるのが人間の仕事。

This reference documents the `native/addon.toml` schema accepted by
the Rust addon foundation introduced in RC1 and extended by the
install-time pipeline in RC1.5. For a walkthrough of how to write
and ship an addon, see `docs/guide/13_creating_addons.md`.

The parser is intentionally a **hand-written strict subset of TOML**
implemented in `src/addon/manifest.rs`. It is not the upstream `toml`
crate, and it only accepts the sections and keys listed in this
document.

---

## Required top-level keys

```toml
abi     = 1                              # integer — must equal TAIDA_ADDON_ABI_VERSION
entry   = "taida_addon_get_v1"           # string — must equal TAIDA_ADDON_ENTRY_SYMBOL
package = "my-org/my-addon"              # string — "<org>/<name>", matched against packages.tdm
library = "my_addon"                     # string — cdylib filename stem (no lib prefix, no ext)
```

`abi`, `entry`, `package`, and `library` are all required. Any
mismatch with the frozen ABI v1 constants is a parse error, not a
load-time warning.

## `[functions]`

```toml
[functions]
greet = 1
noop  = 0
```

At least one function entry is required. Keys are the function name
as it appears in Taida source; values are the declared arity as a
non-negative integer. Non-integer arities and duplicate keys are
rejected at parse time.

## `[library.prebuild]` (RC1.5, optional)

```toml
[library.prebuild]
url = "https://example.com/releases/{version}/lib{name}-{target}.{ext}"
```

Declares where `taida install` should fetch the prebuild cdylib. If
this section is absent, the addon is in RC1-style "developer
places the `.so` manually" mode. If this section is present:

- `url` is required and must be a string.
- Template variables are `{version}`, `{target}`, `{ext}`, `{name}`.
- Unknown variables, unbalanced braces, and `{{` / `}}` escapes are
  rejected at parse time.

### `[library.prebuild.targets]` (RC1.5, required when `[library.prebuild]` is present)

```toml
[library.prebuild.targets]
"x86_64-unknown-linux-gnu"  = "sha256:abcdef0123...64 chars total"
"aarch64-apple-darwin"      = "sha256:..."
```

- Keys must be canonical target triples accepted by
  `HostTarget::from_triple` (the 5 RC1.5 v1 baseline targets plus
  the RC15B-003 extensions listed in
  `docs/guide/13_creating_addons.md`).
- Values must be `sha256:` + exactly 64 **lowercase** hex characters.
  Uppercase hex is rejected to enforce canonical form across
  platforms.
- Unknown / non-canonical target triples are rejected at parse time
  with `PrebuildUnknownTarget` — this prevents cache-directory
  traversal attacks by stopping attacker-controlled keys long
  before they reach `path.join()`.

### `[library.prebuild.signatures]` (RC15B-005, reserved)

```toml
[library.prebuild.signatures]
"x86_64-unknown-linux-gnu" = "gpg:<opaque-identifier>"
```

- Reserved for future GPG / detached signature verification.
- Keys must be canonical target triples (same rule as
  `[library.prebuild.targets]`).
- Values must start with `gpg:` followed by a non-empty
  printable-ASCII payload (no whitespace, no control characters).
  Other prefixes (`sigstore:`, …) are rejected so the reserved
  namespace stays clean for a future verifier.
- Taida currently **parses and stores** these entries but does not
  verify them. Adding them today is safe: when the verifier lands
  it will read from this exact field.

---

## RC15B-106: HTTPS download limits

When `taida install` downloads a prebuild over HTTPS it configures
the HTTP client with the following explicit policies:

| Policy           | Value                  | Notes |
|------------------|------------------------|-------|
| Request timeout  | 120 seconds            | End-to-end — applies to the whole request |
| Max redirects    | **10**                 | `reqwest::redirect::Policy::limited(10)` (constant `HTTPS_MAX_REDIRECTS` in `src/addon/prebuild_fetcher.rs`) |
| Max payload      | 100 MB                 | `Content-Length` is rejected before download starts when over the limit; streaming bodies are aborted at 100 MB |
| HTTP downgrade   | **rejected**           | `reqwest`'s default redirect policy blocks `https → http` transitions; we do not relax it |
| Scheme whitelist | `https://`, `file://`  | Everything else (including `http://`) is rejected before any network call |

Redirect chains longer than 10 hops result in a deterministic
`DownloadFailed` error rather than a silent infinite loop. The
limit is intentionally high enough for common CDN redirects
(GitHub → CDN → object store) but low enough to catch redirect
loops quickly.

For `file://` URLs, the fetcher rejects:

- Absolute paths (e.g. `file:///etc/passwd`)
- Any path containing `..` components (RC15B-101)
- Any URL scheme other than `file://` or `https://`

These checks run **before** any filesystem access or network I/O.

---

## RC15B-107: Unknown-key forward-compatibility policy

The manifest parser is **strict**: any section header or top-level
key not listed in this document is a parse error. This is a
deliberate ABI-drift guard:

- Unknown sections (e.g. `[library.experimental]`) are rejected.
- Unknown top-level keys (e.g. `maintainer = "..."`) are rejected.
- Unknown keys inside known sections are rejected.
- Duplicate keys (including in `[functions]`) are rejected.

Forward-compat rules for **manifest authors**:

1. **Adding a new section** to this reference is equivalent to an
   ABI bump. Wait for a taida release that understands the section
   before using it, and document the minimum supported
   `taida` version in your addon's README.
2. **Adding a new optional key** inside an existing reserved
   section (for example, adding `signatures` to
   `[library.prebuild]` in RC15B-005) is also an ABI bump —
   authors must update the parser in lock-step, and older taidas
   will refuse to load manifests that carry the new key.
3. **Writing a manifest with a future key** on an older taida is
   expected to fail. This is a feature, not a bug: silent
   tolerance would mean that a key which becomes load-bearing in a
   later version silently breaks anyone still on the older taida.

Forward-compat rules for **host tool implementers**:

1. New variants of `AddonManifestError` go at the end of the
   `#[non_exhaustive]` enum. Display format of existing variants
   must not change (the resolver pins on the `addon manifest
   error:` prefix).
2. New sections must be added to every branch of
   `parse_minimal_toml`'s section dispatcher, plus a validator in
   `parse_addon_manifest_str`, plus tests that cover both the
   happy path and at least one failure case.
3. The hand-written `is_valid_key` / target-keyed section
   detection must be updated consistently — see the
   `[library.prebuild.signatures]` addition in RC15B-005 for the
   pattern.

---

## Error taxonomy

Every error produced while parsing or validating `native/addon.toml`
is an `AddonManifestError` variant. Display format is deterministic
and starts with `addon manifest error:`. The variants currently in
use:

| Variant                                | When |
|----------------------------------------|------|
| `ReadFailed`                           | `fs::read_to_string` failed |
| `Syntax`                               | Line outside the accepted subset |
| `MissingKey`                           | Required top-level key absent |
| `AbiUnsupported`                       | `abi` did not equal `TAIDA_ADDON_ABI_VERSION` |
| `EntryMismatch`                        | `entry` did not equal `TAIDA_ADDON_ENTRY_SYMBOL` |
| `MissingPackageId` / `MissingLibrary`  | Empty required string |
| `NoFunctions`                          | `[functions]` absent or empty |
| `InvalidArity`                         | Function arity not a non-negative integer |
| `TypeMismatch`                         | Key value had wrong type |
| `PrebuildMissingUrl`                   | `[library.prebuild]` present without `url` |
| `PrebuildInvalidSha256`                | `targets.*` not `sha256:` + 64 lowercase hex |
| `PrebuildUnknownUrlVariable`           | `{foo}` not in `{version|target|ext|name}` |
| `PrebuildUnbalancedBrace`              | Lone `{` or `}` in URL template |
| `PrebuildDuplicateTarget`              | Same target listed twice under `targets` |
| `PrebuildUnknownTarget` (RC15B-103)    | Target key not in `HostTarget::from_triple` |
| `PrebuildInvalidSignatureFormat` (RC15B-005) | Signature value not `gpg:<opaque>` |
| `PrebuildSignatureUnknownTarget` (RC15B-005) | Signature key not a canonical triple |
| `PrebuildDuplicateSignatureTarget` (RC15B-005) | Same target listed twice under `signatures` |

---

# Taida CLI リファレンス

> 更新日: 2026-04-10  
> 実装正本: `src/main.rs`

このページは Taida CLI の単一リファレンスです。  
コマンド仕様は実装 (`src/main.rs`) に合わせています。

---

## 実行モード

### 1. REPL

```bash
taida
taida --no-check
```

- 引数なしで REPL を起動します。
- `--no-check` を付けると REPL 内の型チェックをスキップします。

### 2. ファイル実行（Interpreter）

```bash
taida <FILE>
taida --no-check <FILE>
```

- サブコマンド以外の第1引数はファイルパスとして扱われます。
- `--no-check` で型チェックをスキップできます。

### 3. 共通フラグ

`--no-check` はグローバルに受理され、サブコマンド振り分け前に除去されます。

- 実際に効果がある: `taida <FILE>`, `taida` (REPL), `taida build`, `taida transpile`
- 現状効果がない: `graph`, `verify`, `inspect`, `init`, `deps`, `install`, `update`, `doc`, `todo`, `lsp`
- `--help` / `-h` はトップレベルヘルプを表示します。
- `--version` / `-V` はバージョンを表示します。

### 4. トップレベルヘルプ

```bash
taida --help
taida -h
taida help
```

挙動:
- 使用方法、主要サブコマンド、グローバルフラグを表示します。
- exit code は `0` です。
- `taida <COMMAND> --help` のようなサブコマンド個別ヘルプへの導線を含みます。

---

## コマンド一覧

| コマンド | 用途 |
|---|---|
| `build` | 成果物生成の主コマンド（`--target native|js|wasm-*`） |
| `transpile` | `build --target js` のエイリアス |
| `todo` | `TODO[...]` 抽出と集計 |
| `check` | parse/type/verify(error-coverage) の静的診断 |
| `graph` | グラフ抽出 / summary / query |
| `verify` | 構造検証 |
| `inspect` | summary + graph統計 + verify 一括表示 |
| `init` | プロジェクト雛形生成 |
| `deps` | 依存解決 + install + lockfile（strict） |
| `install` | 依存インストール + lockfile生成 |
| `update` | リモート優先で依存更新 + lockfile更新 |
| `publish` | package publish の準備と push |
| `doc generate` | doc comments から Markdown 生成 |
| `lsp` | LSP サーバー起動（stdio） |
| `auth` | 認証状態の管理 |
| `community` | community API へのアクセス |
| `upgrade` | taida 自身のセルフアップデート |

補足:
- 表のサブコマンドは `--help` / `-h` を受理し、各節の usage を stdout に出して exit code `0` で終了します。
- `auth` / `community` の下位 verb も `taida auth login --help`, `taida community posts --help` のように個別 help を受理します。
- 実行モードは `taida <FILE>` であり、独立した `taida run` subcommand は現状ありません。

---

## `taida build`

```bash
taida build [--target native|js|wasm-min|wasm-wasi|wasm-edge|wasm-full] [--release] [--diag-format text|jsonl] [-o OUTPUT] [--entry ENTRY] <PATH>
```

| オプション | 短縮 | 説明 |
|---|---|---|
| `--target <native\|js\|wasm-min\|wasm-wasi\|wasm-edge\|wasm-full>` | - | 生成ターゲット（既定: `native`） |
| `--output <PATH>` / `--outdir <DIR>` | `-o` | 出力先（file入力時はファイル、dir入力時はディレクトリ） |
| `--entry <PATH>` | - | Native + dir入力時のエントリ上書き（既定: `main.td`） |
| `--release` | `-r` | TODO/Stub 残存時に失敗 |
| `--diag-format <text\|jsonl>` | - | 診断出力形式（既定: `text`） |

挙動:
- `<PATH>` は file/dir を受理します。
- `--target` 省略時は `native` がデフォルトです。
- `--target native`（デフォルト）:
  - file入力: そのファイルをエントリに Native バイナリ生成（既定 `src/foo.td -> src/foo`）
  - dir入力: 既定エントリ `<PATH>/main.td`、`--entry` で上書き可能
- `--target js`:
  - file入力: 単一 `.mjs` を生成（既定 `src/foo.td -> src/foo.mjs`）
  - dir入力: `.td` を再帰収集して `.mjs` を出力（既定出力は `<PATH>` 親の `dist/`）
  - dir入力で `package.json` が無ければ `{ "type": "module" }` を生成します。
- `--target wasm-*`:
  - `.wasm` 成果物を生成します。
  - 対応ターゲットは `wasm-min`, `wasm-wasi`, `wasm-edge`, `wasm-full` です。
- 既定では parse + type check を実行します（`--no-check` で type check をスキップ）。
- `--release` では `TODO` / `Stub` を検出すると終了します（file入力時は import 依存も再帰走査）。
- `--diag-format jsonl` では compile 診断を `taida.diagnostic.v1` JSONL で出力します（parse/type/verify/codegen/io）。

---

## `taida transpile`

```bash
taida transpile [--release] [--diag-format text|jsonl] [-o OUTPUT] <PATH>
```

`taida build --target js` のエイリアスです。引数はそのまま `build` に転送されます。

---

## `taida todo`

```bash
taida todo [--format text|json] [PATH]
```

| オプション | 短縮 | 説明 |
|---|---|---|
| `--format <FORMAT>` | `-f` | `text` (既定) / `json` |

挙動:
- `PATH` 省略時は `.` を対象にします。
- ディレクトリ指定時は `.td` を再帰収集します。
- JSON 出力は `total`, `todos`, `byId`, `byFile` を返します。

---

## `taida check`

```bash
taida check [--json] <PATH>
```

| オプション | 短縮 | 説明 |
|---|---|---|
| `--json` | - | 機械可読 JSON (`schema: taida.check.v1`) で出力 |

挙動:
- `<PATH>` はファイルまたはディレクトリ指定に対応します（ディレクトリ時は `.td` を再帰収集）。
- parse/type/verify(`error-coverage`) を実行し、`summary.total/errors/warnings/info/files` を出力します。
- `errors > 0` の場合は exit code `1`、それ以外は `0` です。

### Front Gate（仕様の正門）としての役割

`taida check` は単なる型検査器ではなく、**仕様の正門（front gate）** として機能します。

- **未実装機能の reject 口**: 言語仕様として確定しているが未実装の機能、または明示的に廃止された機能は、`taida check` が backend（Interpreter / JS / Native）に到達する前に拒否します。これにより backend ごとに別々の壊れ方をすることを防ぎます。
- **確定済み意味論の強制**: 関数オーバーロード禁止（`[E1501]`）、旧 `_` 部分適用禁止（`[E1502]`）、TypeDef 部分適用禁止（`[E1503]`）、パイプライン外 `Mold[_]()` 直接束縛禁止（`[E1504]`）など、確定済みの意味論制約を checker が強制します。
- **`--no-check` との関係**: `--no-check` で型チェックをスキップしても、parser error（`E01xx` / `E02xx`）は回避できません。checker が拒否する構文（`E13xx` / `E14xx` / `E15xx`）は `--no-check` でバイパスされますが、その場合 backend での挙動は未定義です。
- **診断コード**: `taida check` が発行する全ての診断コードは `docs/reference/diagnostic_codes.md` に定義されています。AI ツールはコードを安定識別子として利用できます。

---

## `taida graph`

```bash
taida graph [--type TYPE] [--format FORMAT] <PATH>
taida graph summary [--type TYPE] [--format FORMAT] <PATH>
taida graph query --type TYPE --query EXPR <PATH>
taida graph --help
```

| オプション | 短縮 | 説明 |
|---|---|---|
| `--type <TYPE>` | `-t` | `dataflow` / `module` / `type-hierarchy` / `error` / `call` |
| `--format <FORMAT>` | `-f` | `text` / `json` / `mermaid` / `dot` |
| `--query <EXPR>` | - | `query` サブコマンド用 |

挙動:
- 現状の `<PATH>` は単一ファイル入力です。
- 無効な `--type` / `--format` はエラー終了します。
- `summary` は構造サマリ(JSON文字列)を出力します。
- `--help` / `-h` は graph 専用の usage / type / format 一覧を表示し、exit code `0` で終了します。

---

## `taida verify`

```bash
taida verify [--check CHECK] [--format FORMAT] <PATH>
```

| オプション | 短縮 | 説明 |
|---|---|---|
| `--check <CHECK>` | `-c` | 実行チェック（複数指定可） |
| `--format <FORMAT>` | `-f` | `text` (既定) / `json` / `jsonl` / `sarif` |

`<PATH>` はファイルまたはディレクトリ指定に対応します。  
ディレクトリ指定時は `.td` を再帰走査します。

### `--check` の値

| チェック | 重要度 | 概要 |
|---|---|---|
| `error-coverage` | error | throw サイトのカバレッジ検証 |
| `no-circular-deps` | error | モジュール循環依存検出 |
| `dead-code` | warning | 到達不能関数検出 |
| `type-consistency` | error | 型階層の循環検出 |
| `unchecked-division` | warning | 除算安全性チェック枠（現行構文では通常 finding なし） |
| `direction-constraint` | error | 単一方向制約（`=>`/`<=`, `]=>`/`<=[`） |
| `unchecked-lax` | warning | Lax 未検査利用検出 |
| `naming-convention` | warning | 命名規約違反検出 |

注:
- 不明な check 名は `Unknown check` の warning として出力されます。
- `--severity` は現状未実装です。
- `--format jsonl` では finding 行 + summary 行を出力し、`ERROR` finding がある場合は exit code `1` になります。

---

## `taida inspect`

```bash
taida inspect [--format text|json|sarif] <PATH>
```

| オプション | 短縮 | 説明 |
|---|---|---|
| `--format <FORMAT>` | `-f` | `text` (既定) / `json` / `sarif` |

挙動:
- 現状の `<PATH>` は単一ファイル入力です。
- `text`: summary + 各グラフ統計 + verify結果を表示します。
- `json`: `summary` と `verification`（SARIF）を1つの JSON にまとめて出力します。
- `sarif`: verify 結果のみを SARIF で出力します。

---

## `taida init`

```bash
taida init [--target rust-addon] [DIR]
```

| オプション | 短縮 | 説明 |
|---|---|---|
| `--target rust-addon` | - | Rust アドオンプロジェクトをスキャフォールドします |

挙動:
- `DIR` 省略時はカレントディレクトリに初期化します。
- `packages.tdm` が既にある場合は失敗します。
- 通常モード: `packages.tdm`, `main.td`（未存在時）, `.taida/` を作成します。
- `--target rust-addon`: `Cargo.toml`, `src/lib.rs`, `native/addon.toml`, `taida/<name>.td`, `README.md` を含む Rust アドオンプロジェクトをスキャフォールドします。

---

## `taida deps`

```bash
taida deps
```

挙動:
- `packages.tdm` をカレントから親方向に探索します。
- 依存解決エラーが1件でもある場合、install/lockfile更新を行わず失敗します（strict fail-fast）。
- 成功時は `.taida/deps` と `.taida/taida.lock` を更新します。

---

## `taida install`

```bash
taida install [--force-refresh] [--allow-local-addon-build]
```

| オプション | 短縮 | 説明 |
|---|---|---|
| `--force-refresh` | - | アドオンキャッシュを無視して再ダウンロードします |
| `--allow-local-addon-build` | - | プレビルド不在時にローカルの `cargo build` にフォールバックします |

挙動:
- `packages.tdm` をカレントから親方向に探索します。
- 解決できた依存を install し、`.taida/taida.lock` を生成/更新します。
- アドオン依存は `native/addon.toml` の `[library.prebuild]` に従い、SHA-256検証付きでプレビルドをダウンロードします。
- ダウンロードは `~/.taida/addon-cache/` にキャッシュされます（`taida cache clean --addons` で削除）。
- 一部依存が解決不能でも lockfile 生成は試行し、最後に終了コード1を返します。

---

## `taida update`

```bash
taida update [--allow-local-addon-build]
```

| オプション | 短縮 | 説明 |
|---|---|---|
| `--allow-local-addon-build` | - | プレビルド不在時にローカルの `cargo build` にフォールバックします |

挙動:
- `install` と同様ですが、世代解決時にリモート優先モードで更新確認します。
- 解決できた依存を再 install し、`.taida/taida.lock` を更新します。

---

## `taida publish`

```bash
taida publish [--label LABEL] [--dry-run[=MODE]] [--target rust-addon]
```

| オプション | 短縮 | 説明 |
|---|---|---|
| `--label <LABEL>` | - | publish version の末尾にラベルを付与します（例: `@a.4.rc`） |
| `--dry-run` | - | 実際の変更を行わず、計画だけ表示します（`--dry-run=plan` と同等） |
| `--dry-run=plan` | - | 計画を表示して終了します |
| `--dry-run=build` | - | cargo build + lockfile まで実行し、git/release はスキップします |
| `--target rust-addon` | - | Rust cdylib アドオンとしてビルド・リリースします |

挙動:
- `taida auth login` 済みであることを要求します（author 名の解決に使用）。
- working tree が clean であることを要求します（未コミットの変更がある場合はエラー）。
- `packages.tdm` と git tag (`<version>`) から次の publish version を決定します。
- `packages.tdm` の `<<<@version owner/name` 行から package identity を解決します。`owner/name` が省略された場合はディレクトリ名にフォールバックします。
- `packages.tdm` の `<<<@...` を決定した exact version に更新します。
- git commit + tag (`<version>`) + push origin を実行します。
- 成功後、`taida-community/proposals` への登録用 URL を表示します。package identity がある場合はそのまま使用し、二重 prefix は発生しません。

`packages.tdm` の canonical surface (@b.11.rc3 以降):

```taida
>>> ./main.td
<<<@a.1 owner/name @(hello, greet)
```

- `>>> ./main.td` はエントリポイントのみを宣言します。
- `<<<@version owner/name @(symbols)` はバージョン、パッケージ ID、公開 API を一括で宣言します。
- package root import 時は `packages.tdm` の export surface が正として使われます。

以下の旧 surface は @b.11.rc3 で廃止されました:
- `<<<@version owner/name => @(symbols)` (arrow 形式)
- `>>> ./main.td => @(symbols)` を facade 宣言として使う split surface
- `<<<@version @(symbols)` (symbols-only、パッケージ ID なし)

---

## `taida cache`

```bash
taida cache clean [--addons]
```

| オプション | 短縮 | 説明 |
|---|---|---|
| `--addons` | - | アドオンプレビルドのキャッシュ (`~/.taida/addon-cache/`) を削除します |

挙動:
- `taida cache clean` はキャッシュを削除します。
- `--addons` でアドオンキャッシュのみを対象にします。

---

## `taida doc generate`

```bash
taida doc generate [-o OUTPUT] <PATH>
```

| オプション | 短縮 | 説明 |
|---|---|---|
| `--output <PATH>` | `-o` | 出力先（省略時は標準出力） |

挙動:
- `<PATH>` はファイルまたはディレクトリ指定に対応します。
- ディレクトリ指定時は `.td` を再帰収集し、doc comments から Markdown を連結生成します。
- 現状は Markdown 出力のみです。

---

## `taida lsp`

```bash
taida lsp
```

挙動:
- Tokio runtime 上で LSP サーバーを起動します（stdio transport）。

---

## `taida auth`

```bash
taida auth <login|logout|status>
taida auth <login|logout|status> --help
```

挙動:
- `login`, `logout`, `status` を提供します。
- `taida auth login --help` などの nested help は stdout に usage を表示し、exit code `0` で終了します。
- `login` は GitHub Device Authorization Flow を開始し、成功した token を保存します。
- `logout` は保存済み token を削除します。
- `status` は現在の認証状態を表示します。

---

## `taida community`

```bash
taida community <posts|post|messages|message|author>
taida community <posts|post|messages|message|author> --help
```

挙動:
- `posts`, `post`, `messages`, `message`, `author` を提供します。
- `taida community posts --help` などの nested help は stdout に usage を表示し、exit code `0` で終了します。
- `posts` は公開投稿を一覧表示します。
- `post` は認証済みユーザーとして公開投稿を作成します。本文に `--help` のような literal flag を含めたい場合は `--` 以降を本文として扱います。
- `messages` は自分宛の公開メッセージ一覧を取得します。
- `message` は `--to <user>` を使って公開メッセージを送信します。本文に `--help` のような literal flag を含めたい場合は `--` 以降を本文として扱います。
- `author` は著者プロフィールを表示します。引数省略時は認証済みユーザー自身を表示します。

---

## `taida upgrade`

```bash
taida upgrade [--check] [--gen GEN] [--label LABEL] [--version VERSION]
```

| オプション | 短縮 | 説明 |
|---|---|---|
| `--check` | - | 更新有無の確認のみ（インストールしない） |
| `--gen <GEN>` | - | 特定の世代（generation）でフィルタ（例: `b`） |
| `--label <LABEL>` | - | 特定のラベルでフィルタ（例: `rc2`） |
| `--version <VERSION>` | - | 特定バージョンに固定（例: `@b.10.rc2`） |

挙動:
- GitHub Releases API から全リリースタグを取得し、バージョン解決を行います。
- デフォルトでは最新の stable バージョン（ラベルなし、または `stable` ラベル）に更新します。
- `--gen` と `--label` は組み合わせ可能です。`--version` は `--gen`/`--label` と排他です。
- 同じ `@gen.num` に stable が複数ある場合、ラベルなしを優先します（例: `@b.11` > `@b.11.stable`）。
- 更新時はプラットフォームに応じたアーカイブ（`.tar.gz`）をダウンロードし、リリースの `SHA256SUMS` ファイルで整合性を検証してからバイナリを展開・自己置換します。`SHA256SUMS` が見つからない場合は警告を表示し、検証をスキップします。
- `--check` 指定時は更新有無を表示するのみで、exit code は常に `0` です。

制限:
- **Windows**: `--check`（更新有無の確認）のみ対応。自己置換（`.zip` 展開 + バイナリ置換）は未実装です。
- `update`（依存パッケージ更新）と `upgrade`（taida 自身の更新）は別のコマンドです。

---

# 診断コード体系 — `E####`

## 番号帯

| 帯域 | カテゴリ | フェーズ | 例 |
|------|---------|---------|-----|
| `E01xx` | 字句解析エラー | Lexer | 不正なトークン、未閉じ文字列 |
| `E02xx` | 構文解析エラー | Parser | 予期しないトークン、構文不正 |
| `E03xx` | 制約違反 | Parser / Verify | 単一方向制約、演算子混在禁止 |
| `E04xx` | 型エラー | TypeChecker | 型不一致、空リスト型推論不能 |
| `E05xx` | モジュールエラー | Module resolution | モジュール未発見、循環インポート |
| `E06xx` | ランタイムエラー | Interpreter | 未定義変数、ゼロ除算（Lax化済み） |
| `E07xx` | コード生成エラー | JS / Native | トランスパイル不能、未対応構文 |
| `E08xx` | パッケージエラー | Package manager | バージョン解決失敗、依存衝突 |
| `E09xx` | グラフエラー | Graph model | verify 失敗、構造不整合 |
| `E13xx` | 関数呼び出しエラー | TypeChecker | 引数過多、arity 不一致 |
| `E14xx` | モールド束縛エラー | TypeChecker | 必須引数不足、重複オプション、未定義フィールド |
| `E15xx` | 定義・意味論エラー | TypeChecker | 重複定義、禁止構文の明示拒否 |

## 現在の割り当て

### 制約違反 (`E03xx`)

| コード | メッセージ | フェーズ |
|--------|-----------|---------|
| `E0301` | 単一方向制約違反 — `=>` と `<=` の混在禁止 | Parser / Verify |
| `E0302` | 単一方向制約違反 — `]=>` と `<=[` の混在禁止 | Parser / Verify |

### 型エラー (`E04xx`)

| コード | メッセージ | フェーズ |
|--------|-----------|---------|
| `E0401` | リスト要素の型が不一致: 先頭要素は {T1} ですが、位置 {N} の要素は {T2} です | TypeChecker |

### 関数呼び出しエラー (`E13xx`)

| コード | メッセージ | フェーズ |
|--------|-----------|---------|
| `E1301` | 関数の引数が宣言されたパラメータ数を超過している | TypeChecker |
| `E1302` | デフォルト値式が自身または後続パラメータを参照している | TypeChecker |
| `E1303` | デフォルト値の型がパラメータの型注釈と不一致 | TypeChecker |

### モールド束縛エラー (`E14xx`)

| コード | メッセージ | フェーズ |
|--------|-----------|---------|
| `E1400` | TypeDef/Mold/Inheritance フィールドに型注釈または default がない | TypeChecker |
| `E1401` | MoldDef の追加 header 引数に束縛先がない | TypeChecker |
| `E1402` | MoldInst の `[]` 必須引数が不足 | TypeChecker |
| `E1403` | MoldInst の `[]` 引数が宣言数を超過 | TypeChecker |
| `E1404` | MoldInst の `()` オプションに同一名が重複 | TypeChecker |
| `E1405` | 必須フィールドが `()` オプション側に渡されている | TypeChecker |
| `E1406` | MoldInst の `()` に未定義のオプションが渡されている | TypeChecker |
| `E1407` | Mold / Inheritance header の arity・prefix・重複・親種別が不正 | TypeChecker |
| `E1408` | MoldInst の `[]` 引数が concrete header 型に一致しない | TypeChecker |
| `E1409` | MoldInst の `[]` 引数が constrained header 型に一致しない | TypeChecker |

### 定義・意味論エラー (`E15xx`)

| コード | メッセージ | フェーズ | 関連 |
|--------|-----------|---------|------|
| `E1501` | 同一スコープでの名前の再定義・関数オーバーロード禁止 | TypeChecker | QF-45, QF-46 |
| `E1502` | 旧 `_` 部分適用構文の使用禁止 — 空スロット `f(5, )` を使うこと | TypeChecker | QF-42 |
| `E1503` | TypeDef/BuchiPack インスタンス化での部分適用禁止 | TypeChecker | QF-43 |
| `E1504` | パイプライン外での `Mold[_]()` 直接束縛禁止 | TypeChecker | QF-44 |
| `E1505` | 部分適用のスロット数が arity と不一致 | TypeChecker | — |
| `E1506` | 関数引数の型が宣言されたパラメータ型と不一致 | TypeChecker | — |
| `E1507` | ビルトイン関数の引数個数が arity 範囲外 | TypeChecker | — |
| `E1508` | メソッド呼び出しの引数個数または型が不一致 | TypeChecker | — |
| `E1509` | generic function の型変数が declared constraint を満たさない | TypeChecker | — |
| `E1510` | inference-only generic function の型変数が parameter annotation / call から束縛・推論できない、または concrete type 名と衝突する | TypeChecker | — |

## 帯域ルール

### 帯域の分類と境界

診断コードは発生フェーズに基づいて3つの層に分かれる。

#### 1. 前段ゲート（`taida check` で検出、backend に到達しない）

| 帯域 | フェーズ | 責務 |
|------|---------|------|
| `E01xx` | Lexer | 字句解析。不正なトークン、未閉じ文字列 |
| `E02xx` | Parser | 構文解析。予期しないトークン、構文不正 |
| `E03xx` | Parser / Verify | 構造的制約。単一方向制約違反 |
| `E04xx` | TypeChecker | 型不一致、型推論不能 |
| `E05xx` | Module resolution | モジュール未発見、循環インポート |
| `E13xx` | TypeChecker | 関数呼び出し意味論。arity 不一致、デフォルト値制約 |
| `E14xx` | TypeChecker | モールド束縛意味論。フィールド重複、引数不足 |
| `E15xx` | TypeChecker | 定義・意味論。重複定義、禁止構文の明示拒否 |

#### 2. Backend 層（コード生成時に検出）

| 帯域 | フェーズ | 責務 |
|------|---------|------|
| `E07xx` | JS / Native codegen | トランスパイル不能、未対応構文 |

#### 3. 実行時層

| 帯域 | フェーズ | 責務 |
|------|---------|------|
| `E06xx` | Interpreter | ランタイムエラー（未定義変数等。Lax化により縮小傾向） |

#### 4. 周辺ツール層

| 帯域 | フェーズ | 責務 |
|------|---------|------|
| `E08xx` | Package manager | バージョン解決失敗、依存衝突 |
| `E09xx` | Graph model | verify 失敗、構造不整合 |

### 帯域重複の排除

- **前段ゲート内の重複なし**: `E01xx`-`E05xx` は入力処理の順序に沿った連番。`E13xx`-`E15xx` は TypeChecker 内の意味分類。両者は帯域が重複しない
- **`E03xx` の Parser / Verify 共有**: `E0301`/`E0302` は Parser と Verify の両方で検出される。これは同一の制約違反を2箇所で検出するための意図的な共有であり、帯域重複ではない
- **`E10xx`-`E12xx` は予約**: 将来の TypeChecker 拡張用に確保。現在は未使用

### フォーマットの統一

現在、エラーメッセージ内のコード表記に2つの形式が混在している:

| 形式 | 使用箇所 | 例 |
|------|---------|-----|
| `E0301:` (コロン区切り) | Parser / Verify | `E0301: 単一方向制約違反 — ...` |
| `[E1301]` (ブラケット囲み) | TypeChecker | `[E1301] Function '...' takes at most ...` |

**正規形式**: `[E####]`（ブラケット囲み）を正規とする。`E03xx` のコロン形式は後方互換のため維持するが、新規コードは必ずブラケット形式を使用すること。`split_diag_code_and_hint` 関数は両形式を解析できる。

## 命名規約

1. **形式**: `E` + 4桁ゼロ埋め数字（`E0001` 〜 `E9999`）
2. **帯域内の番号**: 先頭2桁がカテゴリ、末尾2桁が連番（`01` から開始）
3. **新規追加**: 各帯域の末尾に追番する。欠番を埋めない
4. **メッセージ言語**: エラーメッセージ本文は日本語（`--diag-format jsonl` 出力時も同様）
5. **コード表記**: 新規コードは `[E####]` ブラケット形式を使用する

## 後方互換ポリシー

### 不変

- **コードの意味は変更しない**: 一度割り当てた `E####` の意味（どの種類のエラーか）は変更しない
- **コードの再利用禁止**: 廃止したコードを別の意味で再利用しない

### 許容

- **メッセージ文面の改善**: 同一コードのエラーメッセージ文面は改善のため変更できる
- **コードの廃止**: 言語仕様の変更により不要になったコードは廃止できる（帯域は欠番になる）
- **severity の変更**: error → warning、warning → error の変更は可能（ただしリリースノートに明記）

### AI 連携

- `taida check --json` / `--diag-format jsonl` の出力に `E####` コードが含まれる
- AI ツールはコードを安定識別子として利用できる（文面に依存しない）
- 新規コード追加時はこのドキュメントを更新する

---

# ドキュメントコメント仕様

## 概要

ドキュメントコメントは、コードの説明や API ドキュメント生成、AI/LLM との協業を支援するための構造化されたコメントです。

## 設計原則

- **AI協業ファースト**: AI/LLM が理解しやすい構造化メタデータを提供
- **シンプルな構文**: `///@` プレフィックスで統一
- **豊富なメタデータ**: 目的、例、制約など多角的な情報を記述可能
- **ドキュメント生成対応**: 自動的に API ドキュメントを生成可能

---

## 基本構文

### 単一行コメント

```taida
///@ Purpose: この関数の目的を簡潔に説明
```

### 複数行コメント

```taida
///@
///@ 複数行にわたる説明を
///@ 記述できます。
///@
```

### タグ形式

タグは `@タグ名:` の形式で始まり、値が続きます。

```taida
///@ Purpose: パイロットを作成する
///@ Returns: 作成されたパイロットオブジェクト
```

---

## 標準タグ

### @Purpose

関数・型の目的を簡潔に説明します。

```taida
///@ Purpose: 指定されたIDのパイロットを取得する
getPilot id: Int =
  // 実装
=> :Pilot
```

### @Params

パラメータを説明します。

```taida
///@ Params:
///@   - id: パイロットの一意識別子
///@   - includeDeleted: 削除済みパイロットも含めるか
getPilot id: Int includeDeleted: Bool =
  // 実装
=> :Pilot
```

### @Returns

戻り値を説明します。

```taida
///@ Returns: 見つかったパイロット、見つからない場合はデフォルト値
```

### @Throws

発生しうるエラーを説明します。

```taida
///@ Throws:
///@   - ValidationError: IDが負の場合
///@   - NetworkError: サーバーに接続できない場合
```

### @Example

使用例を示します。

```taida
///@ Example:
///@   pilot <= getPilot(123)
///@   stdout(pilot.name)  // "Misato"
```

### @Since

導入バージョンを示します。

```taida
///@ Since: 1.2.0
```

### @Deprecated

非推奨であることを示します。

```taida
///@ Deprecated: 代わりに getPilotById を使用してください
```

### @See

関連する関数・型への参照を示します。

```taida
///@ See: updatePilot, deletePilot
```

---

## AI協業タグ

AI/LLM がコードを理解し、適切に利用するための特別なタグです。

### @AI-Context

AI がこの関数を使用すべき状況を説明します。

```taida
///@ AI-Context:
///@   この関数はパイロット登録フローで使用される。
///@   フォーム入力の検証後、データベースにパイロットを保存する前に呼び出す。
///@   認証が必要なコンテキストでは使用しない。
createPilot name: Str email: Str =
  // 実装
=> :Pilot
```

### @AI-Examples

AI が学習するための複数の使用例を提供します。

```taida
///@ AI-Examples:
///@   // 基本的な使用
///@   pilot <= createPilot("Misato", "asuka@nerv.jp")
///@
///@   // エラーハンドリング付き
///@   result <= createPilot(name, email)
///@     |== error: Error =
///@       stdout("Failed: " + error.message)
///@       Pilot()
///@
///@   // 検証後に使用
///@   | isValidEmail(email) |> createPilot(name, email)
///@   | _ |> Pilot()
```

### @AI-Constraints

AI がこの関数で行ってはいけないことを説明します。

```taida
///@ AI-Constraints:
///@   - 未検証の入力を直接渡さない
///@   - 空文字列のnameを渡さない
///@   - この関数を認証なしで公開APIから呼び出さない
///@   - 戻り値をnullチェックなしで使用しない
```

### @AI-Related

関連する関数・型を示し、AI が文脈を理解するのを助けます。

```taida
///@ AI-Related:
///@   - updatePilot: パイロット情報の更新
///@   - deletePilot: パイロットの削除
///@   - validateEmail: メールアドレスの検証
///@   - Pilot: パイロット型の定義
```

### @AI-Category

機能のカテゴリを示します。

```taida
///@ AI-Category: pilot-management, crud, database
```

使用可能なカテゴリ例:
- `utility`: ユーティリティ関数
- `validation`: 検証関数
- `transformation`: データ変換
- `crud`: CRUD操作
- `authentication`: 認証関連
- `networking`: ネットワーク操作
- `file-io`: ファイル操作
- `math`: 数学関数
- `string`: 文字列操作
- `collection`: コレクション操作

### @AI-Complexity

処理の計算量や複雑さを示します。

```taida
///@ AI-Complexity:
///@   - Time: O(n log n)
///@   - Space: O(n)
///@   - Network: 1 HTTP request
```

### @AI-SideEffects

副作用を明示します。

```taida
///@ AI-SideEffects:
///@   - Database: Creates new pilot record
///@   - Email: Sends welcome email
///@   - Logging: Logs pilot creation event
```

---

## 型のドキュメント

### 型定義のドキュメント

```taida
///@ Purpose: アプリケーションパイロットを表す
///@ AI-Context: 認証・認可で使用される基本的なパイロット情報
///@ AI-Related: Session, Permission, Role
Pilot = @(
  ///@ パイロットの一意識別子
  id: Int

  ///@ パイロットの表示名
  name: Str

  ///@ メールアドレス（ログインに使用）
  email: Str

  ///@ アカウントの有効状態
  active: Bool
)
```

### モールディング型のドキュメント

```taida
///@ Purpose: 非同期でデータを取得した結果をラップする
///@ AI-Context: API呼び出しの結果を安全に扱うために使用
///@ AI-Examples:
///@   result <= fetchPilot(id)
///@   | result.success |> result ]=> pilot; stdout(pilot.name)
///@   | _ |> stdout("Error: " + result.error.message)
Mold[T] => ApiResult[T] = @(
  success: Bool
  error: ApiError
  timestamp: Int
)
```

---

## 完全な例

### 関数のフルドキュメント

```taida
///@ Purpose: 指定された条件でパイロットを検索する
///@
///@ Params:
///@   - query: 検索クエリ（名前またはメールの部分一致）
///@   - limit: 最大取得件数（デフォルト: 10）
///@   - includeInactive: 非アクティブパイロットを含めるか
///@
///@ Returns: 条件に一致するパイロットのリスト
///@
///@ Throws:
///@   - ValidationError: queryが空の場合
///@   - DatabaseError: データベース接続エラー
///@
///@ Example:
///@   pilots <= searchPilots("asuka", 5, false)
///@   Map[pilots, _ u = stdout(u.name)]()
///@
///@ AI-Context:
///@   管理画面のパイロット検索機能で使用される。
///@   大量のデータを扱う可能性があるため、limitを適切に設定すること。
///@   パフォーマンスを考慮し、queryは最低3文字以上を推奨。
///@
///@ AI-Examples:
///@   // 基本的な検索
///@   pilots <= searchPilots("rei", 10, false)
///@
///@   // 非アクティブパイロットも含めて検索
///@   allPilots <= searchPilots("test", 100, true)
///@
///@   // エラーハンドリング付き
///@   result <= searchPilots(query, limit, false)
///@     |== error: ValidationError =
///@       @[]
///@
///@ AI-Constraints:
///@   - 空のqueryを渡さない
///@   - limitに極端に大きな値（1000以上）を設定しない
///@   - 認証なしのコンテキストで呼び出さない
///@
///@ AI-Related: getPilot, createPilot, updatePilot, Pilot
///@ AI-Category: pilot-management, search, database
///@ AI-Complexity:
///@   - Time: O(n) where n is the number of pilots
///@   - Space: O(limit)
///@   - Database: 1 query
///@
///@ Since: 1.0.0
searchPilots query: Str limit: Int includeInactive: Bool =
  |== error: Error =
    @[]
  => :@[Pilot]

  | query.length() < 1 |>
    ValidationError(message <= "Query cannot be empty").throw()
  | _ |>
    // データベースクエリの実行
    results <= db.query(
      "SELECT * FROM pilots WHERE name LIKE ? OR email LIKE ?",
      @["%" + query + "%", "%" + query + "%"]
    )
    results ]=> pilots

    filtered <=
      | includeInactive |> pilots
      | _ |> Filter[pilots, _ u = u.active]() ]=> active; active

    Take[filtered, limit]() ]=> limited
    limited
=> :@[Pilot]
```

---

## ドキュメント生成

ドキュメントコメントから API ドキュメントを自動生成できます。

### 生成コマンド

```bash
taida doc generate ./src --output ./docs/api
```

### 出力形式

- **HTML**: ブラウザで閲覧可能なドキュメント
- **Markdown**: GitHub 等で表示可能な形式
- **JSON**: プログラムから利用可能な形式

### 生成例

```markdown
## searchPilots

指定された条件でパイロットを検索する

### Parameters

| Name | Type | Description |
|------|------|-------------|
| query | Str | 検索クエリ（名前またはメールの部分一致） |
| limit | Int | 最大取得件数（デフォルト: 10） |
| includeInactive | Bool | 非アクティブパイロットを含めるか |

### Returns

`@[Pilot]` - 条件に一致するパイロットのリスト

### Example

```taida
pilots <= searchPilots("asuka", 5, false)
Map[pilots, _ u = stdout(u.name)]()
```

### Related

- `getPilot` - 単一パイロットの取得
- `createPilot` - パイロットの作成
- `updatePilot` - パイロットの更新
```

---

## ベストプラクティス

### 1. 公開APIには必ずドキュメントを付ける

```taida
// 良い例
///@ Purpose: パイロットを作成する
///@ Params:
///@   - name: パイロット名
///@ Returns: 作成されたパイロット
createPilot name: Str =
  // 実装
=> :Pilot

// 悪い例（ドキュメントなし）
createPilot name: Str =
  // 実装
=> :Pilot
```

### 2. AI-Contextは具体的に書く

```taida
// 良い例
///@ AI-Context:
///@   パイロット登録フォームの送信時に呼び出される。
///@   メールアドレスの形式検証は事前に行われている前提。
///@   重複チェックはこの関数内で行われる。

// 悪い例（曖昧）
///@ AI-Context: パイロット作成に使う
```

### 3. 例は実際に動作するコードで書く

```taida
// 良い例
///@ Example:
///@   config <= loadConfig("app.json")
///@   config ]=> cfg
///@   stdout("Port: " + cfg.port.toString())

// 悪い例（擬似コード）
///@ Example:
///@   cfg = loadConfig(path)
///@   print cfg.port
```

### 4. 制約は具体的な値で示す

```taida
// 良い例
///@ AI-Constraints:
///@   - nameは1文字以上100文字以下
///@   - emailは有効なメールアドレス形式
///@   - ageは0以上150以下

// 悪い例（曖昧）
///@ AI-Constraints:
///@   - 適切な値を渡すこと
```

---

## タグ一覧

### 標準タグ

| タグ | 説明 |
|------|------|
| `@Purpose` | 目的の説明 |
| `@Params` | パラメータの説明 |
| `@Returns` | 戻り値の説明 |
| `@Throws` | 発生しうるエラー |
| `@Example` | 使用例 |
| `@Since` | 導入バージョン |
| `@Deprecated` | 非推奨の説明 |
| `@See` | 関連項目 |

### AI協業タグ

| タグ | 説明 |
|------|------|
| `@AI-Context` | 使用すべき状況 |
| `@AI-Examples` | 複数の使用例 |
| `@AI-Constraints` | 制約・禁止事項 |
| `@AI-Related` | 関連する関数・型 |
| `@AI-Category` | 機能カテゴリ |
| `@AI-Complexity` | 計算量・複雑さ |
| `@AI-SideEffects` | 副作用 |

---

# グラフモデル リファレンス

## 共通定義

### GraphNode

全グラフビューに共通するノード型。

```taida
GraphNode = @(
  id: Str
  kind: Str
  label: Str
  location: @(
    file: Str
    line: Int
    column: Int
  )
  metadata: @()
)
```

| フィールド | 型 | 説明 |
|-----------|-----|------|
| `id` | `Str` | ノードの一意識別子（`file:line:col:kind` 形式） |
| `kind` | `Str` | ノード種別（ビューごとに定義） |
| `label` | `Str` | 表示用ラベル |
| `location` | `@(file, line, column)` | ソースコード上の位置 |
| `metadata` | `@()` | ビュー固有の追加情報 |

### GraphEdge

全グラフビューに共通するエッジ型。

```taida
GraphEdge = @(
  source: Str
  target: Str
  kind: Str
  label: Str
  metadata: @()
)
```

| フィールド | 型 | 説明 |
|-----------|-----|------|
| `source` | `Str` | 始点ノードのID |
| `target` | `Str` | 終点ノードのID |
| `kind` | `Str` | エッジ種別（ビューごとに定義） |
| `label` | `Str` | 表示用ラベル |
| `metadata` | `@()` | ビュー固有の追加情報 |

### Graph

グラフ全体を表現する型。

```taida
Graph = @(
  view: Str
  nodes: @[GraphNode]
  edges: @[GraphEdge]
  metadata: @(
    source_files: @[Str]
    generated_at: Str
    taida_version: Str
  )
)
```

---

## データフローグラフ

### ノード種別

| `kind` | 説明 | 抽出元 |
|--------|------|--------|
| `Variable` | 変数 | `x <= ...` / `... => x` |
| `FunctionCall` | 関数呼び出し | `func(...)` |
| `Literal` | リテラル値 | `42`, `"hello"`, `@[...]` |
| `BuchiPack` | ぶちパック | `@(...)` |
| `Unmold` | アンモールディング操作 | `]=>` / `<=[` / `.unmold()` |
| `Placeholder` | プレースホルダ | `_` |
| `Condition` | 条件分岐 | `\| cond \|>` |

### エッジ種別

| `kind` | 説明 | 抽出元演算子 |
|--------|------|------------|
| `PipeForward` | 順方向パイプ | `=>` |
| `PipeBackward` | 逆方向パイプ | `<=` |
| `UnmoldForward` | 順方向アンモールド | `]=>` |
| `UnmoldBackward` | 逆方向アンモールド | `<=[` |
| `Argument` | 関数引数 | `func(arg)` |
| `Return` | 戻り値 | `=> :Type` |
| `ConditionTrue` | 条件真 | `\| cond \|> value` |
| `ConditionFalse` | 条件偽 / デフォルト | `\| _ \|> value` |

### 抽出規則

| 構文パターン | 生成されるノード | 生成されるエッジ |
|-------------|----------------|----------------|
| `a => b` | `a`: Variable, `b`: Variable | `a -> b`: PipeForward |
| `a => func(_) => b` | `a`: Variable, `func(_)`: FunctionCall, `b`: Variable | `a -> func(_)`: PipeForward, `func(_) -> b`: PipeForward |
| `b <= a` | `a`: Variable, `b`: Variable | `a -> b`: PipeBackward |
| `mold ]=> x` | `mold`: Variable, `x`: Variable | `mold -> x`: UnmoldForward |
| `x <=[ mold` | `mold`: Variable, `x`: Variable | `mold -> x`: UnmoldBackward |
| `func(a, b)` | `func(a, b)`: FunctionCall, `a`: *, `b`: * | `a -> func`: Argument, `b -> func`: Argument |

> **注意**: 単一方向制約により、一つの文内で `PipeForward` と `PipeBackward` が同時に出現することはありません。同様に `UnmoldForward` と `UnmoldBackward` も同時に出現しません。

---

## モジュール依存グラフ

### ノード種別

| `kind` | 説明 | 抽出元 |
|--------|------|--------|
| `Module` | ローカルモジュール | `.td` ファイル |
| `ExternalPackage` | 外部パッケージ | `>>> package => ...` |
| `Symbol` | インポート/エクスポートされたシンボル | `@(sym1, sym2)` |

### エッジ種別

| `kind` | 説明 | 抽出元演算子 |
|--------|------|------------|
| `Imports` | モジュールのインポート | `>>>` |
| `Exports` | シンボルのエクスポート | `<<<` |
| `SymbolRef` | シンボルの使用 | インポートしたシンボルの参照 |

### 抽出規則

| 構文パターン | 生成されるノード | 生成されるエッジ |
|-------------|----------------|----------------|
| `>>> ./file.td => @(a, b)` | 現ファイル: Module, `./file.td`: Module, `a`, `b`: Symbol | 現ファイル -> `./file.td`: Imports |
| `>>> pkg@1.0 => @(func)` | 現ファイル: Module, `pkg`: ExternalPackage, `func`: Symbol | 現ファイル -> `pkg`: Imports |
| `<<< @(a, b)` | `a`, `b`: Symbol | 現ファイル -> `a`: Exports, 現ファイル -> `b`: Exports |

---

## 型階層グラフ

### ノード種別

| `kind` | 説明 | 抽出元 |
|--------|------|--------|
| `PrimitiveType` | プリミティブ型 | `Int`, `Str`, `Bool`, `Float` |
| `BuchiPackType` | ぶちパック型 | `TypeName = @(...)` |
| `MoldType` | モールディング型 | `Mold[T] => TypeName[T] = @(...)` |
| `ErrorType` | エラー型 | `Error => ErrorName = @(...)` |

### エッジ種別

| `kind` | 説明 | 抽出元 |
|--------|------|--------|
| `MoldInheritance` | Mold基底クラスからの継承 | `Mold[T] => ...` |
| `ErrorInheritance` | Error基底型からの継承 | `Error => ...` |
| `StructuralSubtype` | 構造的サブタイプ | `ParentType => ChildType = @(...)` |

### 抽出規則

| 構文パターン | 生成されるノード | 生成されるエッジ |
|-------------|----------------|----------------|
| `Name = @(...)` | `Name`: BuchiPackType | なし |
| `Mold[T] => Name[T] = @(...)` | `Name`: MoldType | `Mold[T] -> Name`: MoldInheritance |
| `Error => Name = @(...)` | `Name`: ErrorType | `Error -> Name`: ErrorInheritance |
| `Parent => Child = @(...)` | `Child`: BuchiPackType | `Parent -> Child`: StructuralSubtype |

---

## エラー境界グラフ

### ノード種別

| `kind` | 説明 | 抽出元 |
|--------|------|--------|
| `ErrorCeiling` | エラー天井 | `\|== error: Type = ...` |
| `ThrowSite` | throwの発生位置 | `ErrorType(...).throw()` |
| `Function` | エラー天井を含む関数 | 関数定義 |
| `GorillaCeiling` | ゴリラ天井（暗黙） | トップレベル（明示的なエラー天井がない場合） |

### エッジ種別

| `kind` | 説明 | 抽出元 |
|--------|------|--------|
| `Catches` | エラー天井がthrowをキャッチ | `\|==` と `.throw()` の関係 |
| `ThrowsTo` | throwからエラー天井への伝播 | `.throw()` の伝播先 |
| `Propagates` | エラーの関数間伝播 | 内部関数のthrowが外部関数のエラー天井に到達 |

### 抽出規則

| 構文パターン | 生成されるノード | 生成されるエッジ |
|-------------|----------------|----------------|
| `\|== error: T = ...` | ErrorCeiling(T) | なし |
| `ErrorType(...).throw()` | ThrowSite(ErrorType) | ThrowSite -> 最近のErrorCeiling: ThrowsTo |
| 関数内のエラー天井 | Function | Function内のErrorCeiling: Contains |
| エラー天井なしのthrow | ThrowSite | ThrowSite -> 呼び出し元のErrorCeiling: Propagates |

---

## コールグラフ

### ノード種別

| `kind` | 説明 | 抽出元 |
|--------|------|--------|
| `Function` | 名前付き関数 | `funcName args = ...` |
| `AnonymousFn` | 無名関数 | `_ x = x * 2` |
| `Method` | メソッド | ぶちパック/モールディング型内の関数 |
| `Entrypoint` | エントリーポイント | `taida` コマンドで実行されるファイル |

### エッジ種別

| `kind` | 説明 | 抽出元 |
|--------|------|--------|
| `Calls` | 関数呼び出し | `func(args)` |
| `TailCalls` | 末尾呼び出し | 末尾位置での `func(args)` |
| `CallsLambda` | 無名関数の呼び出し | `Map[..., _ x = ...]()` |

### 抽出規則

| 構文パターン | 生成されるエッジ |
|-------------|----------------|
| 関数A内の `funcB(args)` | `A -> funcB`: Calls |
| 関数A内の末尾位置の `funcB(args)` | `A -> funcB`: TailCalls |
| 関数A内の `Map[data, _ x = ...]()` | `A -> _lambda_N`: CallsLambda |

---

## クエリ言語

### クエリ構文

```
query_expr := query_name "(" args ")"
args       := arg ("," arg)*
arg        := node_id | "*" | query_expr
node_id    := IDENTIFIER
```

### クエリ一覧

| クエリ | 入力 | 出力 | 説明 |
|--------|------|------|------|
| `path_exists(a, b)` | ノードID × 2 | `Bool` | `a` から `b` へのパスが存在するか |
| `shortest_path(a, b)` | ノードID × 2 | `@[GraphNode]` | `a` から `b` への最短パス |
| `reachable(a)` | ノードID | `@[GraphNode]` | `a` から到達可能な全ノード |
| `find_cycles()` | なし | `@[@[GraphNode]]` | グラフ内の全循環 |
| `uncovered_throws()` | なし | `@[GraphNode]` | エラー天井でカバーされていないthrowサイト |
| `unreachable_functions()` | なし | `@[GraphNode]` | エントリーポイントから到達不能な関数 |
| `dependents(a)` | ノードID | `@[GraphNode]` | `a` に依存する全ノード |
| `dependencies(a)` | ノードID | `@[GraphNode]` | `a` が依存する全ノード |
| `fan_in(a)` | ノードID | `Int` | `a` に入るエッジ数 |
| `fan_out(a)` | ノードID | `Int` | `a` から出るエッジ数 |

### クエリの使用例

```bash
# データフローグラフに対するクエリ
taida graph query --type dataflow --query "path_exists(input, result)" ./src/main.td

# モジュール依存グラフの循環検出
taida graph query --type module --query "find_cycles()" ./src

# エラーカバレッジの検証
taida graph query --type error --query "uncovered_throws()" ./src

# 特定関数の呼び出し元を列挙
taida graph query --type call --query "dependents(processData)" ./src
```

---

## 出力形式

### JSON

```bash
taida graph --type dataflow --format json ./src/main.td
```

```json
{
  "view": "dataflow",
  "nodes": [
    {
      "id": "main.td:1:1:Variable",
      "kind": "Variable",
      "label": "input",
      "location": { "file": "main.td", "line": 1, "column": 1 },
      "metadata": {}
    },
    {
      "id": "main.td:2:10:FunctionCall",
      "kind": "FunctionCall",
      "label": "trim(_)",
      "location": { "file": "main.td", "line": 2, "column": 10 },
      "metadata": {}
    }
  ],
  "edges": [
    {
      "source": "main.td:1:1:Variable",
      "target": "main.td:2:10:FunctionCall",
      "kind": "PipeForward",
      "label": "=>",
      "metadata": {}
    }
  ],
  "metadata": {
    "source_files": ["main.td"],
    "generated_at": "2026-02-26T10:00:00Z",
    "taida_version": "0.1.0"
  }
}
```

### Mermaid

```bash
taida graph --type dataflow --format mermaid ./src/main.td
```

```mermaid
graph LR
    input["input: 'hello world'"]
    trim["trim(_)"]
    toUpperCase["toUpperCase(_)"]
    result["result"]

    input -->|"=>"| trim
    trim -->|"=>"| toUpperCase
    toUpperCase -->|"=>"| result
```

### Graphviz (DOT)

```bash
taida graph --type module --format dot ./src
```

```dot
digraph module_dependency {
    rankdir=LR;
    node [shape=box];

    "main.td" -> "utils.td" [label="imports: helper, format"];
    "main.td" -> "types.td" [label="imports: Pilot, Config"];
    "main.td" -> "express"  [label="imports: App", style=dashed];
}
```

---

## 構造サマリスキーマ

### StructuralSummary

```taida
StructuralSummary = @(
  version: Str
  project: Str
  timestamp: Str
  stats: ProjectStats
  dataflow: DataflowStats
  modules: ModuleStats
  errors: ErrorStats
  type_hierarchy: TypeHierarchyStats
)

ProjectStats = @(
  files: Int
  functions: Int
  types: Int
  mold_types: Int
  error_types: Int
  modules: Int
)

DataflowStats = @(
  total_pipes: Int
  forward_pipes: Int
  backward_pipes: Int
  unmold_operations: Int
)

ModuleStats = @(
  total_imports: Int
  total_exports: Int
  external_packages: Int
  has_cycles: Bool
  cycle_details: @[@[Str]]
)

ErrorStats = @(
  total_ceilings: Int
  total_throw_sites: Int
  uncovered_throws: Int
  error_types_used: @[Str]
  gorilla_ceiling_count: Int
)

TypeHierarchyStats = @(
  max_depth: Int
  mold_types: @[Str]
  error_types: @[Str]
  structural_subtypes: @[@(parent: Str, child: Str)]
)
```

### FileStructure

個別ファイルの構造情報。

```taida
FileStructure = @(
  file: Str
  functions: @[FunctionInfo]
  types: @[TypeInfo]
  imports: @[ImportInfo]
  exports: @[ExportInfo]
  error_ceilings: @[ErrorCeilingInfo]
)

FunctionInfo = @(
  name: Str
  line: Int
  params: @[@(name: Str, type: Str)]
  return_type: Str
  calls: @[Str]
  is_exported: Bool
)

TypeInfo = @(
  name: Str
  line: Int
  kind: Str
  parent: Str
  fields: @[@(name: Str, type: Str)]
)

ImportInfo = @(
  source: Str
  symbols: @[Str]
  line: Int
)

ExportInfo = @(
  symbols: @[Str]
  line: Int
)

ErrorCeilingInfo = @(
  error_type: Str
  line: Int
  handles: @[Str]
)
```

---

## CLIリファレンス

CLI 全体の仕様は [CLI リファレンス](./cli.md) を参照してください。  
このページでは `graph` / `verify` に関係する最小情報のみ記載します。

### `taida graph`

```
taida graph [--type TYPE] [--format FORMAT] <PATH>
taida graph summary [--type TYPE] [--format FORMAT] <PATH>
taida graph query --type TYPE --query EXPR <PATH>
```

| オプション | 短縮 | 説明 |
|---|---|---|
| `--type <TYPE>` | `-t` | `dataflow` / `module` / `type-hierarchy` / `error` / `call` |
| `--format <FORMAT>` | `-f` | `text` / `json` / `mermaid` / `dot` |
| `--query <EXPR>` | - | `query` サブコマンド用 |

注:
- 現状 `<PATH>` は単一ファイル入力です。
- `summary` は構造サマリを出力します。

### `taida verify`

```
taida verify [--check CHECK] [--format FORMAT] <PATH>
```

| オプション | 短縮 | 説明 |
|---|---|---|
| `--check <CHECK>` | `-c` | 実行チェック（複数指定可） |
| `--format <FORMAT>` | `-f` | `text` / `json` / `sarif` |

### 検証チェック一覧

| チェック名 | 重要度 | 説明 |
|---|---|---|
| `error-coverage` | error | throw サイトのカバレッジ検証 |
| `no-circular-deps` | error | モジュール循環依存検出 |
| `dead-code` | warning | 到達不能関数検出 |
| `type-consistency` | error | 型階層の循環検出 |
| `unchecked-division` | warning | 除算安全性チェック枠（現行構文では通常 finding なし） |
| `direction-constraint` | error | 単一方向制約の検証 |
| `unchecked-lax` | warning | Lax 未検査利用検出 |
| `naming-convention` | warning | 命名規約違反検出 |

---

# モールディング型リファレンス

## 概要

モールディング型の定義方法と、全モールディング型のリファレンスです。
概念的な説明は `../guide/05_molding.md` を参照してください。

> **PHILOSOPHY.md — III.** カタめたいなら、鋳型を作りましょう

---

## 設計原則: `[]` と `()` の役割分担

```rust
// AST 定義
MoldInst(String, Vec<Expr>, Vec<BuchiField>, Span)
//       名前    [位置引数]   (名前付き設定)
```

| | `[]` 位置引数 | `()` 名前付き設定 |
|---|---|---|
| **役割** | 必須引数（何を / 何で） | オプション設定（どうやって） |
| **名前** | なし（位置で区別） | あり（名前で区別） |
| **省略** | 不可 | 可（デフォルト値あり） |
| **順序** | 固定（`[何を, 何で]`） | 任意 |

---

## Mold基底クラス

すべてのモールディング型は `Mold[...]` を継承して定義します。

```taida
// 基本形式
Mold[T] => MyMold[T] = @(
  filling: T
  solidify _ => :V
  unmold _ => :U
  // 追加フィールド
)

// 例
Mold[T] => Result[T, P <= :T => :Bool] = @(throw: Error)  // 述語付き操作モールド
```

header 記法:

- `T` = 型変数
- `:Int` = concrete type
- `T <= :Int` = concrete type 制約付き型変数
- `Mold[...]` は親ヘッダー、`Name[...]` は子ヘッダー
- `Mold[...]` の親側は常に 1 slot のまま保つ
- 追加 slot は子ヘッダー側にだけ書く
- 子ヘッダーは親ヘッダーを exact prefix として保持し、末尾にだけ slot を追加できる

ヘッダースロット束縛規則:

1. `Mold[...]` の1つ目は常に `filling`
2. 2つ目以降は、`@(...)` の「デフォルト値なしフィールド」に宣言順で対応
3. `T` だけでなく `:Int` のような具象型スロットも1つのフィールドスロットを消費する
4. どれか1つでも束縛先が足りないと `E1401`
5. `Name[...]` を明示する場合は、`Mold[...]` を exact prefix に保ったまま、同数またはそれ以上の slot 数でなければ `E1407`

例:

```taida
Mold[:Int] => IntBox = @()
IntBox[1]()       // OK
IntBox["x"]()     // E1408: 具象型ヘッダー型不一致

Mold[:Int] => IntPair[:Int, T] = @(
  second: T
)
IntPair[1, "x"]() // OK

Mold[:Int] => Broken[:Int, T] = @()
// E1401: 2つ目のヘッダースロットに対応するフィールドが無い
```

### solidify / unmold（正式仕様）

| フック | デフォルト | 役割 |
|---|---|---|
| `solidify` | `self` を返す | `Name[args]()` が何の型として固まるか（Is-A）を決定 |
| `unmold` | `filling` を返す | `]=>` / `<=[` / `.unmold()` で取り出す値を決定 |

`[]` / `()` 束縛規則:

1. 1つ目の `[]` は常に `filling`
2. 2つ目以降の `[]` はデフォルト値なしフィールドへ宣言順に束縛
3. `()` はデフォルト値ありフィールドのみ指定可能
4. 規則違反はコンパイルエラー（不足/過多/取り違え/未定義オプション）
5. カスタムモールド定義時、追加型引数に対応する束縛先（デフォルト値なしフィールド）が無ければコンパイルエラー
6. 通常フィールドは `field: Type` または `field <= value` のどちらかが必須（`field` 単独はコンパイルエラー）

`Name[args]()` の評価順序:

1. `[]` を `filling` とデフォルト値なしフィールドへ順に束縛
2. `()` をデフォルト値ありフィールドへ束縛
3. `solidify` を評価
4. 式 `Name[args]()` の型は `solidify` の戻り値型

演算子の意味:

- `Name[args]() => x`: `solidify` の結果を代入
- `Name[args]() ]=> x`: `solidify` 結果に `unmold` を適用して代入

例:

```taida
Lax[42]() => boxed      // boxed: Lax[Int]（default solidify）
Lax[42]() ]=> value     // value: Int

Int["123"]() => parsed  // parsed: Lax[Int]（solidify override）
Int["123"]() ]=> num    // num: Int
```

---

## 文字列モールド

### Upper[str]

すべての文字を大文字に変換します。

```taida
Upper["hello"]()              // "HELLO"
str => Upper[_]() => result
```

### Lower[str]

すべての文字を小文字に変換します。

```taida
Lower["HELLO"]()              // "hello"
str => Lower[_]() => result
```

### Trim[str]

空白を除去します。オプションで除去方向を制御できます。

```taida
Trim["  hello  "]()                    // "hello"（両端）
Trim["  hello  "](end <= false)        // "hello  "（先頭のみ）
Trim["  hello  "](start <= false)      // "  hello"（末尾のみ）
```

| オプション | デフォルト | 説明 |
|-----------|----------|------|
| `start` | `true` | 先頭の空白を除去 |
| `end` | `true` | 末尾の空白を除去 |

### Split[str, delim]

区切り文字で分割してリストを返します。

```taida
Split["a,b,c", ","]()         // @["a", "b", "c"]
str => Split[_, ","]() => parts
```

### Replace[str, old, new]

部分文字列を置換します。オプションで全置換を制御できます。

```taida
Replace["hello world", "o", "0"]()              // "hell0 world"（最初の1つ）
Replace["hello world", "o", "0"](all <= true)   // "hell0 w0rld"（全部）
```

| オプション | デフォルト | 説明 |
|-----------|----------|------|
| `all` | `false` | `true` で全一致を置換 |

### Slice[str]

指定範囲の部分文字列を返します。

```taida
Slice["hello"](start <= 1, end <= 3)   // "el"
Slice["hello"](start <= 2)             // "llo"
Slice["hello"](end <= 3)               // "hel"
```

| オプション | デフォルト | 説明 |
|-----------|----------|------|
| `start` | `0` | 開始位置 |
| `end` | 文字列長 | 終了位置 |

### CharAt[str, idx]

指定位置の文字を返します。Lax[Str] を返し、範囲外の場合は hasValue=false（デフォルト値 ""）。

```taida
CharAt["hello", 0]() ]=> ch   // "h"
CharAt["hello", 4]() ]=> ch   // "o"
```

### Repeat[str, n]

文字列を指定回数繰り返します。

```taida
Repeat["ha", 3]()             // "hahaha"
Repeat["x", 0]()              // ""
```

### Reverse[str]

文字列を逆順にします（リストにも使用可能）。

```taida
Reverse["hello"]()            // "olleh"
```

### Pad[str, len]

指定長になるようパディングします。

```taida
Pad["42", 5](side <= "start")                 // "   42"
Pad["42", 5](side <= "end")                   // "42   "
Pad["42", 5](side <= "start", char <= "0")    // "00042"
```

| オプション | デフォルト | 説明 |
|-----------|----------|------|
| `side` | `"start"` | `"start"` または `"end"` |
| `char` | `" "` | パディング文字 |

---

## 数値モールド

### ToFixed[num, digits]

指定した小数点以下の桁数で文字列に変換します。

```taida
ToFixed[3.14159, 2]()         // "3.14"
ToFixed[42, 2]()              // "42.00"
```

### Abs[num]

絶対値を返します。

```taida
Abs[-5]()                     // 5
Abs[3.14]()                   // 3.14
```

### Floor[num]

小数点以下を切り捨てた整数を返します。

```taida
Floor[3.7]()                  // 3
Floor[-3.7]()                 // -4
```

### Ceil[num]

小数点以下を切り上げた整数を返します。

```taida
Ceil[3.2]()                   // 4
Ceil[-3.2]()                  // -3
```

### Round[num]

四捨五入した整数を返します。

```taida
Round[3.4]()                  // 3
Round[3.5]()                  // 4
```

### Truncate[num]

0方向に切り捨てた整数を返します。

```taida
Truncate[3.7]()               // 3
Truncate[-3.7]()              // -3
```

### Clamp[num, min, max]

指定範囲に収めた値を返します。

```taida
Clamp[5, 0, 10]()             // 5
Clamp[-5, 0, 10]()            // 0
Clamp[15, 0, 10]()            // 10
```

### BitAnd / BitOr / BitXor / BitNot

ビット演算をモールドとして提供します（演算子は追加しません）。

```taida
BitAnd[6, 3]()                 // 2
BitOr[6, 3]()                  // 7
BitXor[6, 3]()                 // 5
BitNot[0]()                    // -1
```

### ShiftL / ShiftR / ShiftRU

`n`（シフト量）が `0..63` のとき成功し、`Lax[Int]` を返します。範囲外は `hasValue = false` です。

```taida
ShiftL[1, 40]() ]=> x          // 1099511627776
ShiftRU[-1, 1]() ]=> y         // 9223372036854775807
ShiftL[1, 64]().hasValue       // false
```

### ToRadix[int, base]

整数を指定基数（`2..36`）の文字列へ変換します。

```taida
ToRadix[255, 16]() ]=> s       // "ff"
ToRadix[10, 1]().hasValue      // false
```

### Int[str, base]

指定基数（`2..36`）で文字列を整数に変換します。基数が範囲外の場合は変換失敗になります。符号は先頭 `+` または `-` で表現します。

```taida
Int["ff", 16]() ]=> n          // 255
Int["FF", 16]() ]=> n          // 255 (大文字も受理)
Int["+ff", 16]() ]=> n         // 255 (+ prefix も受理)
Int["1010", 2]() ]=> n         // 10
Int["77", 8]() ]=> n           // 63
Int["-ff", 16]() ]=> n         // -255
Int["2", 2]().hasValue         // false (基数2で "2" は無効)
Int["5", 1]().hasValue         // false (基数1は範囲外)
```

### UInt8 / Bytes / ByteSet / BytesToList

バイト列境界のモールド群です。`Bytes` は不変で、更新は新しい値を返します。

```taida
Bytes[4](fill <= 65) ]=> b      // Bytes[@[65, 65, 65, 65]]
ByteSet[b, 1, 66]() ]=> b2      // Bytes[@[65, 66, 65, 65]]
BytesToList[b2]()                // @[65, 66, 65, 65]
UInt8[255]() ]=> v               // 255
```

### Char / CodePoint / Utf8Encode / Utf8Decode

Unicode scalar value と UTF-8 の相互変換です。`CodePoint` は「1文字の Str」のみ成功します。

```taida
Char[65]() ]=> c                 // "A"
CodePoint["A"]() ]=> cp          // 65
Utf8Encode["pong"]() ]=> raw     // Bytes[@[112, 111, 110, 103]]
Utf8Decode[raw]() ]=> text       // "pong"
bad <= Bytes[@[255]]()
bad ]=> badBytes
Utf8Decode[badBytes]().hasValue   // false
```

---

## リストモールド

### Reverse[list]

リストを逆順にします（文字列にも使用可能）。

```taida
Reverse[@[1, 2, 3]]()        // @[3, 2, 1]
```

### Concat[list, other]

2つのリストを結合します。

```taida
Concat[@[1, 2], @[3, 4]]()   // @[1, 2, 3, 4]
```

### Append[list, val]

末尾に要素を追加した新しいリストを返します。

```taida
Append[@[1, 2], 3]()         // @[1, 2, 3]
```

### Prepend[list, val]

先頭に要素を追加した新しいリストを返します。

```taida
Prepend[@[2, 3], 1]()        // @[1, 2, 3]
```

### Join[list, sep]

要素を区切り文字で結合して文字列にします。

```taida
Join[@["a", "b", "c"], ","]()  // "a,b,c"
Join[@[1, 2, 3], "-"]()        // "1-2-3"
```

### Sum[list]

数値リストの合計を返します。

```taida
Sum[@[1, 2, 3]]()            // 6
Sum[@[]]()                    // 0
```

### Sort[list]（統合モールド）

要素をソートします。オプションで降順・キー関数を制御できます。

```taida
Sort[@[3, 1, 2]]()                              // @[1, 2, 3]
Sort[@[3, 1, 2]](reverse <= true)               // @[3, 2, 1]
Sort[pilots](by <= _ p = p.syncRate)             // キー関数ソート
Sort[pilots](by <= _ p = p.name, reverse <= true)  // キー関数降順
```

| オプション | デフォルト | 説明 |
|-----------|----------|------|
| `reverse` | `false` | `true` で降順 |
| `by` | なし（自然順） | キー抽出関数 |

### Unique[list]（統合モールド）

重複を除去したリストを返します。

```taida
Unique[@[1, 2, 2, 3, 3]]()                      // @[1, 2, 3]
Unique[items](by <= _ x = x.id)                  // キーで重複判定
```

| オプション | デフォルト | 説明 |
|-----------|----------|------|
| `by` | なし（値の等価比較） | キー抽出関数 |

### Flatten[list]

ネストしたリストを1段階フラット化します。

```taida
Flatten[@[@[1, 2], @[3, 4]]]()  // @[1, 2, 3, 4]
```

### Find[list, fn]

条件を満たす最初の要素を Lax で返します。

```taida
Find[@[1, 2, 3, 4], _ x = x > 2]() ]=> val  // 3
Find[@[1, 2], _ x = x > 10]().hasValue       // false
```

### FindIndex[list, fn]

条件を満たす最初の要素の位置を返します。見つからない場合は -1。

```taida
FindIndex[@[1, 2, 3, 4], _ x = x > 2]()  // 2
```

### Count[list, fn]

条件を満たす要素数を返します。

```taida
Count[@[1, 2, 3, 4, 5], _ x = x > 2]()  // 3
```

### Take[list, n] / Drop[list, n]

先頭からn個取得/スキップします。

```taida
Take[@[1, 2, 3, 4, 5], 3]()  // @[1, 2, 3]
Drop[@[1, 2, 3, 4, 5], 2]()  // @[3, 4, 5]
```

### TakeWhile[list, fn] / DropWhile[list, fn]

条件を満たす間取得/スキップします。

```taida
TakeWhile[@[1, 2, 3, 4, 5], _ x = x < 4]()  // @[1, 2, 3]
DropWhile[@[1, 2, 3, 4, 5], _ x = x < 3]()  // @[3, 4, 5]
```

### Zip[list, other]

2つのリストをペアにします。短い方に合わせます。

```taida
Zip[@[1, 2, 3], @["a", "b", "c"]]() ]=> pairs
// pairs: @[@(first <= 1, second <= "a"), @(first <= 2, second <= "b"), ...]
```

### Enumerate[list]

インデックスを付与したリストを返します。

```taida
Enumerate[@["a", "b", "c"]]() ]=> indexed
// indexed: @[@(index <= 0, value <= "a"), @(index <= 1, value <= "b"), ...]
```

### Filter[list, fn]

条件を満たす要素を抽出します。

```taida
isEven x =
  Mod[x, 2]() ]=> r
  r == 0
=> :Bool
Filter[@[1, 2, 3, 4], isEven]() ]=> evens  // @[2, 4]
```

### Map[list, fn]

各要素に関数を適用します。

```taida
Map[@[1, 2, 3], _ x = x * 2]() ]=> doubled  // @[2, 4, 6]
```

### Fold[list, init, fn]

左から畳み込みます。

```taida
Fold[@[1, 2, 3], 0, _ acc x = acc + x]() ]=> sum  // 6
```

### Foldr[list, init, fn]

右から畳み込みます。

```taida
Foldr[@["a", "b", "c"], "", _ acc x = x + acc]() ]=> concat  // "abc"
```

---

## 演算モールディング型

### Div[x, y]

除算を行い、Lax を返します。ゼロ除算の場合は `hasValue = false`。

```taida
Div[10, 3]() ]=> result   // 3
Div[10, 0]() ]=> result   // 0 (ゼロ除算: デフォルト値)
Div[10, 0]().hasValue      // false
```

### Mod[x, y]

剰余を計算し、Lax を返します。ゼロ除算の場合は `hasValue = false`。

```taida
Mod[10, 3]() ]=> result   // 1
Mod[10, 0]().hasValue      // false
```

---

## 条件モールディング型

### If[cond, then, else]

```taida
If[condition, then_value, else_value]() => T
```

2 分岐の条件式。`condition` を評価し、truthy なら `then_value`、falsy なら `else_value` を返します。

- 非選択 branch は評価しません（short-circuit）
- パイプラインで `_` を使って前段の値を参照できます
- ネスト可能: `If[cond, If[cond2, a, b](), c]()`

```taida
If[x > 0, "positive", "negative"]()
150 => If[_ > 100, 100, _]()   // clamp: 100
If[true, If[false, 1, 2](), 3]()   // 2
```

---

## 型比較モールディング型

### TypeIs[value, :TypeName]

```taida
TypeIs[value, :TypeName]() => Bool
```

値の実行時の型が指定した型名と一致するかを判定します。

対応する型リテラル: `:Int`, `:Float`, `:Num`, `:Bool`, `:Str`, `:Bytes`, `:Error`, `:NamedType`

Enum variant の判定: `TypeIs[value, EnumName:Variant]()` で特定の variant かを判定します。

```taida
TypeIs[42, :Int]()                // true
TypeIs["hello", :Str]()          // true
TypeIs[42, :Num]()               // true
TypeIs[Status:Ok(), Status:Ok]() // true
```

### TypeExtends[:TypeA, :TypeB]

```taida
TypeExtends[:TypeA, :TypeB]() => Bool
```

TypeA が TypeB と同じ型か、TypeB のサブタイプかを判定します。コンパイル時に解決可能です。

```taida
TypeExtends[:Int, :Num]()        // true
TypeExtends[:Dog, :Animal]()     // true（Dog が Animal を継承している場合）
TypeExtends[:Str, :Int]()        // false
```

---

## 型変換モールディング型

型変換モールドが `Lax[...]` を返す挙動は、`solidify` オーバーライドで定義される言語仕様です（専用のコンパイラ特別扱いではない）。

### Int[x]

値を整数に変換し、Lax を返します。文字列から整数への変換（Str → Int）の正規経路です。

```taida
Int["123"]() ]=> num   // 123
Int["abc"]() ]=> num   // 0 (変換失敗: デフォルト値)
Int[3.14]() ]=> num    // 3
Int["+5"]() ]=> num    // 5 (符号付き文字列も受理)
```

受理される文字列: 先頭に `+` または `-` を含むオプションの符号、続いて1桁以上の数字（`0-9`）。空文字列、小数点を含む文字列、先頭/末尾の空白、数字以外の文字を含む文字列は変換失敗になります。

`Int[str, base]()` で基数を指定した変換も可能です（詳細は [数値モールド](#intstr-base) を参照）。

### Float[x]

値を浮動小数点数に変換し、Lax を返します。

```taida
Float["3.14"]() ]=> val  // 3.14
Float[42]() ]=> val      // 42.0
```

### Str[x]

値を文字列に変換し、Lax を返します。

```taida
Str[42]() ]=> text       // "42"
Str[3.14]() ]=> text     // "3.14"
```

### Bool[x]

値を真偽値に変換し、Lax を返します。

```taida
Bool[1]() ]=> flag       // true
Bool[0]() ]=> flag       // false
```

---

## Lax モールディング型

### Lax[x]

値を Lax で包みます。

```taida
Lax[42]() ]=> val     // 42
Lax[42]().hasValue     // true
```

---

## Result

### Result[value, predicate]() / Result[value, predicate](throw <= error)

述語付き操作モールドです。`]=>` で述語 P を評価し、真なら値 T を返し、偽なら throw が発動します。

```taida
Mold[T] => Result[T, P <= :T => :Bool] = @(throw: Error)
// P: :T => :Bool（成功条件を定義する述語）

Result[42, _ = true]()                                          // 成功（_ = true は常に真）
Result[0, _ = false](throw <= NotFound(message <= "not found")) // 失敗（_ = false は常に偽）
Result[age, _ x = x >= 18](throw <= err)                        // バリデーション

// => と ]=> の違い
Result[x, pred](throw <= err) => r   // r: Result[T, P]（default solidify = self）
Result[x, pred](throw <= err) ]=> r  // r: T（unmold 時に述語を評価 → 真なら値、偽なら throw）

// 戻り値型注釈: _ で述語を推論
=> :Result[Int, _]
```

---

## Gorillax モールディング型

### Gorillax[x]

値を Gorillax で包みます。unmold 失敗時はゴリラ（プログラム即終了）。Lax とは異なりデフォルト値へのフォールバックはありません。

```taida
Gorillax[42]() ]=> val     // 42
Gorillax[42]().hasValue     // true
```

### Cage[molten, function]

Molten（溶鉄）に対して関数を実行し、結果を Gorillax で返します。関数の実行が失敗した場合は `hasValue = false` の Gorillax が返ります。

**Cage は Molten 専用です。** 第一引数は Molten 型の値のみ受け付けます。

```taida
Cage[molten, _ x = x.someMethod()] => result  // result: Gorillax[U]
// molten: Molten（溶鉄のみ）
// 成功: Gorillax(hasValue=true, __value=結果)
// 失敗: Gorillax(hasValue=false, __error=エラー)
```

### RelaxedGorillax[T]

`Gorillax.relax()` で生成。unmold 失敗時に `RelaxedGorillaEscaped` エラーを throw します（`|==` で捕捉可能）。

```taida
gorillax.relax() => relaxed  // relaxed: RelaxedGorillax[T]

|== error: RelaxedGorillaEscaped =
  | _ |> defaultValue
=> :T

relaxed ]=> val  // 失敗時: throw（キャッチ可能）
```

### unmold の挙動比較

| 型 | unmold 成功 | unmold 失敗 |
|---|-----------|-----------|
| `Lax[T]` | 値 T を返す | デフォルト値を返す |
| `Gorillax[T]` | 値 T を返す | ゴリラ（プログラム終了） |
| `RelaxedGorillax[T]` | 値 T を返す | `RelaxedGorillaEscaped` を throw |

---

## JS 補助モールド（JS バックエンド専用）

npm パッケージから得られる Molten 値に対して JavaScript 固有の操作を行うモールドです。全て Molten を受け取り Molten を返します。

**インタプリタおよび Native バックエンドでは「JS バックエンド専用です」コンパイルエラーになります。**

**3バックエンド・パリティの対象外です。** これらは JS interop 層であり、ポータブルなコードでは使いません。インタプリタや Native バックエンドに同等の実装は提供されません。

### JSNew[constructor, args]

JavaScript の `new` 演算子に相当するコンストラクタ呼び出しです。

```taida
>>> npm:express => @(express)

JSNew[express.Router, @()]() => router  // router: Molten
JSNew[express.Router, @(strict <= true)]() => strictRouter  // strictRouter: Molten
```

| `[]` 必須 | 型 | 説明 |
|----------|-----|------|
| `constructor` | Molten | コンストラクタ関数 |
| `args` | BuchiPack | コンストラクタ引数 |

**戻り値**: `Molten`

### JSSet[obj, key, value]

Molten オブジェクトのプロパティに値を破壊的に設定します。JavaScript の `obj[key] = value` に相当します。**同一の Molten 参照を返します** -- Molten の世界では JavaScript の破壊的代入のセマンティクスがそのまま適用されます。

```taida
JSSet[app, "port", 3000]() => app2    // app2: Molten（app と同一参照）
JSSet[config, "debug", true]() => c2  // c2: Molten（config と同一参照）
```

| `[]` 必須 | 型 | 説明 |
|----------|-----|------|
| `obj` | Molten | 対象オブジェクト |
| `key` | Str | プロパティ名 |
| `value` | Any | 設定する値 |

**戻り値**: `Molten`（同一参照。JavaScript の破壊的代入に相当）

### JSBind[obj, method]

Molten オブジェクトのメソッドに `this` をバインドします。JavaScript の `obj.method.bind(obj)` に相当します。

```taida
handler <= JSBind[server, "handleRequest"]()  // handler: Molten
callback <= JSBind[emitter, "emit"]()         // callback: Molten
```

| `[]` 必須 | 型 | 説明 |
|----------|-----|------|
| `obj` | Molten | 対象オブジェクト |
| `method` | Str | メソッド名 |

**戻り値**: `Molten`

### JSSpread[target, source]

Molten オブジェクトにプロパティをスプレッド展開でマージします。JavaScript の `{...target, ...source}` に相当します。

```taida
overrides <= @(port <= 8080, debug <= true)
merged <= JSSpread[defaults, overrides]()  // merged: Molten
```

| `[]` 必須 | 型 | 説明 |
|----------|-----|------|
| `target` | Molten | マージ先オブジェクト |
| `source` | Any | マージ元の値 |

**戻り値**: `Molten`

---

## パイプラインでの使用

`_` プレースホルダは `[]` 内でも使用可能です。

```taida
// 正方向パイプライン
list => Filter[_, isEven]() => Map[_, _ x = x * 2]() => result

// 逆方向パイプライン（仕様上有効だが、現在のパーサーは <= チェーン未対応。将来対応予定）
// result <= Map[_, _ x = x * 2]() <= Filter[_, isEven]() <= list

// 直接呼び出し（unmold）
Filter[list, isEven]() ]=> result

// 文字列パイプライン
"  Hello!  " => Trim[_]() => Upper[_]() => Split[_, " "]() => result
```

---

## 型シグネチャ一覧

### 文字列モールド

| モールド | `[]` 必須 | `()` オプション | 戻り値 |
|---------|----------|----------------|--------|
| `Upper[str]()` | str | - | Str |
| `Lower[str]()` | str | - | Str |
| `Trim[str]()` | str | start, end | Str |
| `Split[str, delim]()` | str, delim | - | @[Str] |
| `Replace[str, old, new]()` | str, old, new | all | Str |
| `Slice[str]()` | str | start, end | Str |
| `CharAt[str, idx]()` | str, idx | - | Lax[Str] |
| `Repeat[str, n]()` | str, n | - | Str |
| `Reverse[str]()` | str | - | Str |
| `Pad[str, len]()` | str, len | side, char | Str |

### 数値モールド

| モールド | `[]` 必須 | `()` オプション | 戻り値 |
|---------|----------|----------------|--------|
| `ToFixed[num, digits]()` | num, digits | - | Str |
| `Abs[num]()` | num | - | Num |
| `Floor[num]()` | num | - | Int |
| `Ceil[num]()` | num | - | Int |
| `Round[num]()` | num | - | Int |
| `Truncate[num]()` | num | - | Int |
| `Clamp[num, min, max]()` | num, min, max | - | Num |
| `BitAnd[a, b]()` | a, b | - | Int |
| `BitOr[a, b]()` | a, b | - | Int |
| `BitXor[a, b]()` | a, b | - | Int |
| `BitNot[x]()` | x | - | Int |
| `ShiftL[x, n]()` | x, n | - | Lax[Int] |
| `ShiftR[x, n]()` | x, n | - | Lax[Int] |
| `ShiftRU[x, n]()` | x, n | - | Lax[Int] |
| `ToRadix[int, base]()` | int, base | - | Lax[Str] |
| `Int[str, base]()` | str, base | - | Lax[Int] |

### リストモールド

| モールド | `[]` 必須 | `()` オプション | 戻り値 |
|---------|----------|----------------|--------|
| `Reverse[list]()` | list | - | @[T] |
| `Concat[list, other]()` | list, other | - | @[T] / Bytes |
| `Append[list, val]()` | list, val | - | @[T] |
| `Prepend[list, val]()` | list, val | - | @[T] |
| `Join[list, sep]()` | list, sep | - | Str |
| `Sum[list]()` | list | - | Num |
| `Sort[list]()` | list | reverse, by | @[T] |
| `Unique[list]()` | list | by | @[T] |
| `Flatten[list]()` | list | - | @[U] |
| `Find[list, fn]()` | list, fn | - | Lax[T] |
| `FindIndex[list, fn]()` | list, fn | - | Int |
| `Count[list, fn]()` | list, fn | - | Int |
| `Take[list, n]()` | list, n | - | @[T] |
| `Drop[list, n]()` | list, n | - | @[T] |
| `TakeWhile[list, fn]()` | list, fn | - | @[T] |
| `DropWhile[list, fn]()` | list, fn | - | @[T] |
| `Zip[list, other]()` | list, other | - | @[BuchiPack] |
| `Enumerate[list]()` | list | - | @[BuchiPack] |
| `Filter[list, fn]()` | list, fn | - | @[T] |
| `Map[list, fn]()` | list, fn | - | @[U] |
| `Fold[list, init, fn]()` | list, init, fn | - | A |
| `Foldr[list, init, fn]()` | list, init, fn | - | A |

### 条件モールド

| モールド | `[]` 必須 | `()` オプション | 戻り値 |
|---------|----------|----------------|--------|
| `If[cond, then, else]()` | cond, then, else | - | T (then の型) |

### 型比較モールド

| モールド | `[]` 必須 | `()` オプション | 戻り値 |
|---------|----------|----------------|--------|
| `TypeIs[value, :TypeName]()` | value, :TypeName | - | Bool |
| `TypeIs[value, EnumName:Variant]()` | value, EnumName:Variant | - | Bool |
| `TypeExtends[:TypeA, :TypeB]()` | :TypeA, :TypeB | - | Bool |

### 演算・型変換モールド

| モールド | `[]` 必須 | `()` オプション | 戻り値 |
|---------|----------|----------------|--------|
| `Div[x, y]()` | x, y | default | Lax[Num] |
| `Mod[x, y]()` | x, y | - | Lax[Num] |
| `Int[x]()` | x | - | Lax[Int] |
| `Float[x]()` | x | - | Lax[Float] |
| `Str[x]()` | x | - | Lax[Str] |
| `Bool[x]()` | x | - | Lax[Bool] |
| `UInt8[x]()` | x | - | Lax[Int] |
| `Bytes[x]()` | x | fill | Lax[Bytes] |
| `ByteSet[bytes, idx, value]()` | bytes, idx, value | - | Lax[Bytes] |
| `BytesToList[bytes]()` | bytes | - | @[Int] |
| `Char[x]()` | x | - | Lax[Str] |
| `CodePoint[str]()` | str | - | Lax[Int] |
| `Utf8Encode[str]()` | str | - | Lax[Bytes] |
| `Utf8Decode[bytes]()` | bytes | - | Lax[Str] |
| `Lax[x]()` | x | - | Lax[T] |
| `Gorillax[x]()` | x | - | Gorillax[T] |
| `Cage[molten, fn]()` | molten: Molten, fn | - | Gorillax[U] |

### JS 補助モールド（JS バックエンド専用）

| モールド | `[]` 必須 | `()` オプション | 戻り値 |
|---------|----------|----------------|--------|
| `JSNew[constructor, args]()` | constructor: Molten, args: BuchiPack | - | Molten |
| `JSSet[obj, key, value]()` | obj: Molten, key: Str, value: Any | - | Molten |
| `JSBind[obj, method]()` | obj: Molten, method: Str | - | Molten |
| `JSSpread[target, source]()` | target: Molten, source: Any | - | Molten |

---

# 命名規則

## 概要

Taida Langでは、コードの可読性と一貫性を保つために以下の命名規則を採用しています。

## 命名規則一覧

| 対象 | 規則 | 例 |
|------|------|-----|
| 型 | PascalCase | `Pilot`, `HttpRequest`, `ValidationError` |
| 変数 | snake_case | `pilot_name`, `total_count`, `is_valid` |
| 関数 | camelCase | `getPilotName`, `calculateTotal`, `isValid` |
| 定数 | UPPER_SNAKE_CASE | `MAX_SIZE`, `DEFAULT_TIMEOUT`, `PI` |
| モジュール | small-kebab-case | `http-client`, `pilot-service`, `json-parser` |
| ファイル | small-kebab-case.td | `http-client.td`, `pilot-service.td` |

---

## 型（PascalCase）

型定義には PascalCase を使用します。

```taida
// 基本的な型定義
Pilot = @(
  name: Str
  age: Int
)

// モールディング型
Mold[T] => Result[T, P <= :T => :Bool] = @(throw: Error)

// エラー型（Errorを継承）
Error => ValidationError = @(field: Str)
Error => HttpError = @(status_code: Int)
```

---

## 変数（snake_case）

変数名には snake_case を使用します。

```taida
// 基本的な変数
pilot_name <= "Misato"
total_count <= 42
is_active <= true

// ぶちパックのフィールド
pilot <= @(
  first_name <= "Misato",
  last_name <= "Katsuragi",
  call_sign <= "Ops-01"
)

// モールディング型のインスタンス
result_pilot <= Result[pilot, _ = true]()
```

---

## 関数（camelCase）

関数名には camelCase を使用します。

```taida
// 基本的な関数
getPilotName pilot: Pilot =
  pilot.first_name + " " + pilot.last_name
=> :Str

// 複数単語の関数名
calculateTotalPrice items: @[Item] =
  Fold[0, items, _ acc item = acc + item.price]() ]=> total
  total
=> :Int

// 真偽値を返す関数（is/has/can プレフィックス）
isValidEmail email: Str =
  // 検証ロジック
=> :Bool

hasPermission pilot: Pilot permission: Str =
  // 権限チェック
=> :Bool
```

---

## 定数（UPPER_SNAKE_CASE）

定数には UPPER_SNAKE_CASE を使用します。

```taida
// 数値定数
MAX_RETRY_COUNT <= 3
DEFAULT_TIMEOUT <= 5000
PI <= 3.14159

// 文字列定数
API_BASE_URL <= "https://api.example.com"
DEFAULT_LOCALE <= "ja-JP"

// 定数のエクスポート
<<< @(MAX_RETRY_COUNT, DEFAULT_TIMEOUT, API_BASE_URL)
```

---

## モジュール・ファイル（small-kebab-case）

モジュール名とファイル名には small-kebab-case を使用します。

```taida
// ファイル: pilot-service.td
>>> ./http-client.td => @(httpGet, httpPost)
>>> ./json-parser.td => @(parseJson)

PilotService = @(
  getPilot id: Int =
    // 実装
  => :Pilot
)

<<< @(PilotService)
```

### ファイル構成例

```
my-project/
  packages.tdm
  main.td
  lib/
    http-client.td
    json-parser.td
    pilot-service.td
  types/
    pilot-types.td
    error-types.td
```

---

## パッケージバージョニング

パッケージバージョンは `@世代.番号.ラベル` 形式を採用しています。

```
@世代.番号.ラベル

世代:   a〜z（単一小文字、破壊的変更で進む）
番号:   1〜（連番、publish ごとにインクリメント）
ラベル: [a-z0-9][a-z0-9-]*（省略可、人間/AI 向けの意味付け）
```

最新判定は `@世代.番号` の比較で完結します。ラベルは順序に影響しません。

```taida
// インポートでのバージョン指定
>>> alice/http@a.5.beta => @(get, post)
>>> bob/utils@b.1 => @(parse)

// エクスポートでのバージョン宣言
<<<@a.1.alpha @(MyApp, Config)
```

例:
- `@a.1` — 最初の公開（ラベルなし）
- `@a.1.alpha` — 初期アルファ
- `@a.5.beta` — ベータ段階
- `@a.12.rc` — リリース候補
- `@b.1.breaking` — 破壊的変更の新世代
- `@x.34.gen-2-stable` — 長いラベルも可

---

## 識別子に使用可能な文字

- 英字（a-z, A-Z）
- 数字（0-9）※先頭以外
- アンダースコア（_）
- Unicode文字（対応予定）

```taida
// OK
pilot_name <= "Misato"
pilot2 <= getPilot(2)
_private <= "internal"

// NG（数字で始まる）
// 2nd_pilot <= ...  // コンパイルエラー
```

---

## 予約語

Taida Langには予約語がありません。`unmold`、`throw` なども関数として扱われます。

```taida
// これらは予約語ではなく、関数/メソッドとして動作
opt.unmold()
error.throw()
```

---

## 推奨事項

### 意味のある名前を使う

```taida
// Good
pilot_count <= pilots.length
active_pilots <= Filter[pilots, _ p = p.is_active]()

// Bad
n <= pilots.length
x <= Filter[pilots, _ p = p.is_active]()
```

### 略語は避ける

```taida
// Good
getPilotById id: Int = ...
calculateTotalPrice items: @[Item] = ...

// Bad
getPltById id: Int = ...
calcTotPrc items: @[Item] = ...
```

### 真偽値には is/has/can プレフィックス

```taida
is_valid <= validateInput(data)
has_permission <= checkPermission(pilot)
can_proceed <= is_valid && has_permission
```

---

# 演算子リファレンス

## 概要

> **PHILOSOPHY.md -- I.** 深く考えずに適当にぶちこんでけ

Taida Langの演算子は**2つのカテゴリ**に分類されます。

### Taida固有演算子（10種）

Taidaの言語設計において特別な意味を持つ演算子です。「演算子は10種のみ」という哲学に基づき、これらは覚えるべき最小限のセットです。

| # | 演算子 | 名称 | 用途 |
|---|--------|------|------|
| 1 | `=` | 定義 | 型・関数・エラー天井の定義 |
| 2 | `=>` | 右ぶちこみ | パイプライン・代入（左から右へ） |
| 3 | `<=` | 左ぶちこみ | 代入・関数適用（右から左へ） |
| 4 | `]=>` | 前方アンモールディング | `solidify` 後の値から `unmold` で取り出す（左から右） |
| 5 | `<=[` | 後方アンモールディング | `solidify` 後の値から `unmold` で取り出す（右から左） |
| 6 | `\|==` | エラー天井 | エラーをキャッチして処理 |
| 7 | `\|` | 条件ガード | 条件分岐の区切り |
| 8 | `\|>` | 条件抽出 | 条件分岐の値取り出し |
| 9 | `>>>` | インポート | モジュールの読み込み |
| 10 | `<<<` | エクスポート | シンボルの公開 |

### その他の演算子

Taida固有演算子とは別カテゴリの、一般的なプログラミング言語にも存在する演算子です。これらは「10種の演算子」のカウントには含まれません。

| 種類 | 演算子 | 用途 |
|------|--------|------|
| 算術 | `+` `-` `*` | 数値演算（単項 `-` を含む） |
| 比較 | `==` `!=` `<` `>` `>=` | 比較（真偽値を返す） |
| 論理 | `&&` `\|\|` `!` | 論理演算（短絡評価） |

> **注意**: Taida に除算 (`/`) と剰余 (`%`) 演算子はありません。`Div[x, y]()` と `Mod[x, y]()` モールドを使用してください。

> **注意**: 比較演算子に `<=`（以下）は存在しません。`<=` は左ぶちこみ演算子として使用されるためです。「以下」を表現するには `!(x > n)` または `x < n \|\| x == n` を使用してください。

### 全演算子の一覧表

| カテゴリ | 種類 | 演算子 | 個数 |
|---------|------|--------|------|
| Taida固有 | ぶちこみ | `=` `=>` `<=` | 3 |
| Taida固有 | アンモールディング | `]=>` `<=[` | 2 |
| Taida固有 | 制御 | `\|==` `\|` `\|>` | 3 |
| Taida固有 | モジュール | `>>>` `<<<` | 2 |
| その他 | 算術 | `+` `-` `*` | 3 |
| その他 | 比較 | `==` `!=` `<` `>` `>=` | 5 |
| その他 | 論理 | `&&` `\|\|` `!` | 3 |

---

## 算術演算子

数値に対する基本的な演算を行います。優先順位はRustに準拠します。

| 演算子 | 説明 | 例 |
|--------|------|-----|
| `+` | 加算 | `3 + 5` → `8` |
| `-` | 減算 | `10 - 3` → `7` |
| `*` | 乗算 | `4 * 5` → `20` |
| `-` | 単項マイナス | `-5` |

### 除算と剰余

除算と剰余は `Div[x, y]()` と `Mod[x, y]()` モールドで行います。結果は Lax で返されます。

```taida
Div[10, 3]() ]=> result   // 3
Div[10, 0]() ]=> result   // 0 (ゼロ除算: Lax のデフォルト値)

Mod[10, 3]() ]=> result   // 1
Mod[10, 0]() ]=> result   // 0 (ゼロ除算: Lax のデフォルト値)
```

> `/` 演算子と `%` 演算子は Taida には存在しません。`Div[x, y]()` と `Mod[x, y]()` モールドで行います。

---

## 比較演算子

2つの値を比較し、`Bool` を返します。

| 演算子 | 説明 | 例 |
|--------|------|-----|
| `==` | 等価 | `x == y` |
| `!=` | 非等価 | `x != y` |
| `<` | 小なり | `x < y` |
| `>` | 大なり | `x > y` |
| `>=` | 以上 | `x >= y` |

> **注意**: `<=`（以下）は左ぶちこみ演算子と重複するため、比較演算子としては存在しません。「以下」を表現するには `<` と `==` を組み合わせてください。

```taida
// 「以下」の表現
is_small <= x < 10 || x == 10

// または否定を使う
is_small <= !(x > 10)
```

---

## 論理演算子

真偽値に対する論理演算を行います。短絡評価を行います（JS準拠）。

| 演算子 | 説明 | 短絡評価 |
|--------|------|----------|
| `&&` | 論理AND | 左がfalseなら右を評価しない |
| `\|\|` | 論理OR | 左がtrueなら右を評価しない |
| `!` | 論理NOT | - |

```taida
// AND: 両方trueの場合のみtrue
result <= x > 0 && y > 0

// OR: どちらかがtrueならtrue
result <= x == 0 || y == 0

// NOT: 真偽値を反転
result <= !is_valid

// 短絡評価の活用
safe <= x > 0 && x + y > 10
```

---

## ぶちこみ演算子

### `=>` 右ぶちこみ

左の値を右に渡します。

```taida
// 関数への適用
5 => add(3, _) => result  // result: 8

// 変数への代入
processData(input) => output

// パイプライン
data => filter(_) => map(_) => result
```

### `<=` 左ぶちこみ

右の値を左に渡します。変数への代入に使います。

```taida
// 変数への代入
x <= 42
name <= "Misato"

// 型のインスタンス化
pilot <= Pilot(name <= "Rei", age <= 14)

// 関数適用の結果を代入
result <= add(10, x)
```

> **注意**: `<=` は変数への単一代入のみに使用できます。`result <= f() <= g() <= data` のような `<=` のチェーン（逆方向パイプライン）は現在サポートされていません。逆方向のデータフローが必要な場合は、`=>` の順方向パイプラインまたは中間変数を使用してください。

### 単一方向制約（ぶちこみ演算子）

一つの文（statement）内で、`=>` と `<=` を混在させることは禁止されています。

**形式定義：**
- 文 S 内に出現するぶちこみ演算子の集合を `Ops(S)` とする
- `{=>} ⊆ Ops(S)` かつ `{<=} ⊆ Ops(S)` のとき、文 S はコンパイルエラーとなる
- ただし `=`（定義演算子）はこの制約の対象外である

```taida
// OK: 単一方向
data => filter(_) => map(_) => result

// OK（仕様上有効だが、現在のパーサーは <= チェーン未対応。将来対応予定）:
// result <= map(_) <= filter(_) <= data

// NG: 方向混在（コンパイルエラー）
data => filter(_) <= result
// エラー E0301: 単一方向制約違反
//   一つの文内で => と <= を混在させることはできません
//   ヒント: data => filter(_) => result に書き換えてください
```

> **注意**: `<=` のチェーン（`result <= f() <= g() <= data` のような2段以上の連鎖）は仕様上有効ですが、現在のパーサーでは単一の `<=` 代入のみサポートしています。逆方向のデータフローが必要な場合は `=>` の順方向パイプラインまたは中間変数を使用してください。

### `=` 定義

型、関数、エラー天井などを定義します。

```taida
// 型定義
Pilot = @(name: Str, age: Int)

// 関数定義
add x: Int y: Int =
  x + y
=> :Int

// モールディング型定義（Mold基底クラスから継承）
Mold[T] => Result[T, P <= :T => :Bool] = @(throw: Error)

// エラー天井定義
|== error: MyError =
  "Error: " + error.message
=> :Str
```

---

## 制御演算子

### `|==` エラー天井

エラーをキャッチして処理します。

```taida
|== error: ErrorType =
  | error.type == "NotFound" |> defaultValue
  | _ |> handleError(error)
=> :ReturnType

// この下でthrowが発生する可能性のある処理
riskyOperation()
```

### `|` `|>` 条件分岐

条件に基づいて値を選択します。

```taida
// 基本形（_ はプレースホルダ）
| condition |> valueIfTrue | _ |> valueIfFalse

// 複数条件
| x > 10 |> "large"
| x > 5 |> "medium"
| _ |> "small"

// パターンマッチ
| status == "success" |> handleSuccess()
| status == "error" |> handleError()
| _ |> handleUnknown()
```

### throw

エラーを発生させます。`throw()` メソッドは Error型を継承した型のインスタンスのみが持ちます。

```taida
// エラー型の定義（Errorを継承）
Error => ValidationError = @(field: Str)

// 条件付きthrow
| condition |> ValidationError(type <= "ValidationError", message <= "Something wrong", field <= "input").throw()

// 変数に入れてthrow
err <= ValidationError(type <= "ValidationError", message <= "Invalid input", field <= "data")
err.throw()
```

---

## モジュール演算子

### `>>>` インポート

モジュールをインポートします。

```taida
// ローカルファイル（シンボル指定）
>>> ./utils.td => @(helper)

// シンボル省略（全エクスポートを取り込む）
>>> ./utils.td

// バージョン指定（packages.tdm のみ）
>>> author/package@a.3 => @(funcA)

// エイリアス
>>> ./other.td => @(add, subtract => sub)
```

`=> @(symbols)` を省略すると、対象モジュールの全エクスポートを取り込みます。名前衝突を避けるため、明示的なシンボル指定を推奨します。

バージョン付きインポート（`@a.3` 等）は packages.tdm でのみ使用可能です。

### `<<<` エクスポート

シンボルをエクスポートします。通常の `.td` ファイルでは複数行の `<<<` が許可されます。

```taida
// 複数シンボル
<<< @(add, subtract, Point)

// 複数行に分割（通常の .td のみ、packages.tdm では1行のみ）
<<< @(add, subtract)
<<< @(Point)

// 単一シンボル
<<< add

// ワンライナー
<<< double x: Int = x * 2 => :Int
```

packages.tdm ではバージョン付き `<<<` が使用され、1行のみ許可されます: `<<<@a.3 @(hello, greet)`

---

## 特殊記号

### `_` プレースホルダ

3つの用途があります。

```taida
// 1. パターンマッチのワイルドカード（「それ以外の全て」）
| _ |> defaultValue

// 2. ラムダ関数の宣言
_ x = x * 2

// 3. パイプラインでの前ステップの値
data => Trim[_]() => output
```

### 空スロット部分適用

関数呼び出しの引数を空にすると部分適用になります。

```taida
add5 <= add(5, )     // 第2引数が穴
double <= multiply(, 2)  // 第1引数が穴
```

### `@(...)` ぶちパック

構造化データを表現します。

```taida
// 値の作成
pilot <= @(name <= "Misato", age <= 29)

// 型定義
Pilot = @(name: Str, age: Int)
```

### 確定済み意味論

以下は `taida check` が前段ゲートとして強制する確定済み意味論です。

#### `_` の3用途（これ以外は禁止）

`_` は以下の3つの文脈でのみ使用できます。

1. **パターンマッチのワイルドカード**: `| _ |> defaultValue` — 「それ以外の全て」
2. **ラムダ関数の宣言**: `_ x = x * 2` — 無名関数の名前位置
3. **パイプラインでの前ステップの値**: `data => Trim[_]() => output` — パイプライン内の前ステップ結果

**禁止**: 関数呼び出しの引数に `_` を渡して部分適用する旧構文 `add(5, _)` は `[E1502]` で拒否されます。空スロット `add(5, )` を使用してください。

#### 空スロット部分適用

関数呼び出しの引数位置を空にすると部分適用になります。

- `add(5, )` — 第2引数が穴。通常の関数呼び出しのみに適用
- TypeDef やモールドのインスタンス化には使用できません（`[E1503]` / `[E1504]` で拒否）

#### 関数オーバーロード禁止

同じ名前の関数を異なる引数パターンで複数定義すること（オーバーロード）は禁止です。`[E1501]` で拒否されます。

#### 同一スコープ重複定義禁止

同一スコープ内で同じ名前の変数・関数・型を再定義することは禁止です。`[E1501]` で拒否されます。異なるスコープでのシャドーイングは許可されます。詳細は `docs/reference/scope_rules.md` を参照してください。

### `@[...]` リスト

リストを表現します。

```taida
numbers <= @[1, 2, 3, 4, 5]
names <= @["Misato", "Rei"]
empty <= @[]
```

### `><` ゴリラリテラル

プログラムを即時終了させます。回復不能な前提条件の違反に使います。`|==` エラー天井ではキャッチできません。

```taida
| config.dbUrl == "" |> ><   // DB接続先なしは致命的
| config.port < 0 |> ><     // 不正なポートも致命的
```

Gorillax モールドの unmold 失敗時も同様にゴリラが発動し、プログラムが即時終了します。

### `unmold()` アンモールディング（メソッド形式）

`solidify` 後の値に対して `unmold` を実行し、取り出し値を返します。

```taida
lax <= Div[10, 3]()

// unmold()で値を取得（メソッド形式）
x <= lax.unmold()  // 3

result <=
  | x > 10 |> "large"
  | _ |> "small"
```

---

## アンモールディング演算子

### `]=>` 左アンモールディング

`solidify` 後の値に `unmold` を適用し、右側の変数に代入します。

```taida
lax <= Div[10, 3]()

// ]=> で値を取得して代入
lax ]=> x  // x に 3 が代入される

// リスト操作モールディング型との組み合わせ
Map[numbers, _ n = n * 2]() ]=> doubled
Filter[items, _ x = x > 10]() ]=> filtered

// チェーン
Filter[numbers, _ x = x > 2]() ]=> filtered
Map[filtered, _ x = x * 2]() ]=> result
```

### `<=[` 右アンモールディング

`]=>` の逆向き。`solidify` 後の値に `unmold` を適用し、左側の変数に代入します。

```taida
lax <= Div[10, 3]()

// <=[ で値を取得して代入
x <=[ lax  // x に 3 が代入される

// リスト操作との組み合わせ
doubled <=[ Map[numbers, _ n = n * 2]()
filtered <=[ Filter[items, _ x = x > 10]()
```

### 単一方向制約（アンモールディング演算子）

一つの文（statement）内で、`]=>` と `<=[` を混在させることは禁止されています。

**形式定義：**
- 文 S 内に出現するアンモールディング演算子の集合を `UnmoldOps(S)` とする
- `{]=>} ⊆ UnmoldOps(S)` かつ `{<=[} ⊆ UnmoldOps(S)` のとき、文 S はコンパイルエラーとなる

```taida
// OK: 単一方向
mold ]=> value
value <=[ mold

// NG: 方向混在（コンパイルエラー）
mold ]=> x <=[ other
// エラー E0302: 単一方向制約違反
//   一つの文内で ]=> と <=[ を混在させることはできません
```

> **注意**: ぶちこみ演算子（`=>` / `<=`）の単一方向制約とは独立して適用されます。つまり `=>` と `<=[` の共存、`<=` と `]=>` の共存は制約対象外です（これらは異なるカテゴリの演算子です）。

### `unmold()` と `]=>`/`<=[` の使い分け

```taida
// メソッド形式（式の中で使いたい場合）
result <= lax.unmold() + 10

// 演算子形式（代入したい場合）
lax ]=> value
result <= value + 10
```

---

## 演算子の優先順位

優先順位はRustに準拠します（高い順）。

| 優先度 | 演算子 | 結合性 |
|--------|--------|--------|
| 1 | `()` 関数呼び出し、`.` フィールドアクセス | 左から右 |
| 2 | `!` `-`（単項） | 右から左 |
| 3 | `*` | 左から右 |
| 4 | `+` `-` | 左から右 |
| 5 | `<` `>` `>=` | 左から右 |
| 6 | `==` `!=` | 左から右 |
| 7 | `&&` | 左から右 |
| 8 | `\|\|` | 左から右 |
| 9 | `\|` `\|>` 条件分岐 | 左から右 |
| 10 | `]=>` `<=[` アンモールディング | 左から右 |
| 11 | `=>` `<=` ぶちこみ | 左から右 |
| 12 | `\|==` エラー天井 | - |
| 13 | `>>>` `<<<` モジュール | - |

```taida
// 例：優先順位の適用
result <= 1 + 2 * 3      // => 7 (乗算が先)
result <= (1 + 2) * 3    // => 9 (括弧で優先)
result <= x > 0 && y > 0 // 比較が先、その後 &&
```

---

## 一般的なパターン

### 変数定義と関数適用

```taida
// 変数定義
x <= 42

// 関数適用（右ぶちこみ）
x => add(10, _) => result

// 関数適用（左ぶちこみ）
result <= add(x, 10)
```

### 関数呼び出しの引数補完（仕様）

関数引数デフォルトの正式仕様は `docs/design/function_default_args.md` を参照。

要点:

1. 省略された末尾引数は実効デフォルトで補完される
2. 実効デフォルトは `param: Type <= expr` があれば `expr`、なければ型デフォルト
3. 引数過多はコンパイルエラー

```taida
sum3 a: Int b: Int <= 10 c: Int <= 20 =
  a + b + c
=> :Int

sum3(1)  // 31
sum3()   // 30
```

### 条件付き処理

```taida
value <=
  | condition1 |> result1
  | condition2 |> result2
  | _ |> defaultResult
```

### エラー処理

```taida
// エラー型の定義
Error => InvalidInputError = @(input: Str)

processData input =
  |== error: Error =
    handleError(error)
  => :ResultType

  | !isValid(input) |> InvalidInputError(type <= "InvalidInputError", message <= "Bad input", input <= input).throw()
  | _ |> doProcess(input)
=> :ResultType
```

### モジュール構成

```taida
// インポート
>>> ./utils.td => @(helper)

// 処理
result <= helper(data)
// result: 処理結果

// エクスポート
<<< @(myFunction, MyType)
```

---

# スコープ規則

## 概要

Taida Langには2種類のスコープがあります。

| スコープ | 説明 |
|----------|------|
| モジュールスコープ | ファイルのトップレベルで定義されたシンボル |
| 関数スコープ | 関数内で定義されたシンボル |

---

## モジュールスコープ

ファイルのトップレベルで定義された型、関数、変数はモジュールスコープに属します。

```taida
// モジュールスコープの定義
Pilot = @(name: Str, age: Int)  // 型定義

MAX_SYNC_RATE <= 100  // 定数

getPilot id: Int =
  // 関数定義
=> :Pilot

// モジュール内のどこからでもアクセス可能
pilot <= Pilot(name <= "Misato", age <= MAX_SYNC_RATE)
```

### モジュールスコープの特徴

- ファイル内のどこからでもアクセス可能
- `<<<` でエクスポートすると他のモジュールからもアクセス可能
- インポートしたシンボルもモジュールスコープで利用可能

```taida
>>> ./utils.td => @(helper)  // helperがモジュールスコープに追加される

result <= helper(data)  // どこからでも使用可能

processData input: Str =
  helper(input)  // 関数内でも使用可能
=> :Str
```

---

## 関数スコープ

関数内で定義された変数、内部関数はその関数内でのみ有効です。

```taida
processPilot pilot: Pilot =
  // 引数 pilot は関数スコープ
  name <= pilot.name  // name は関数スコープ

  // 内部関数も関数スコープ
  formatName =
    name + " さん"
  => :Str

  formatted <= formatName()
  formatted
=> :Str

// NG: 関数外からはアクセス不可
// name  // コンパイルエラー
// formatName  // コンパイルエラー
```

### 関数スコープのネスト

内部関数は外側のスコープにアクセスできます（レキシカルスコープ）。

```taida
outer x: Int =
  y <= 10  // outer の関数スコープ

  inner z: Int =
    // x, y, z すべてにアクセス可能
    x + y + z
  => :Int

  inner(5)
=> :Int

result <= outer(3)  // 18 (3 + 10 + 5)
```

---

## 条件分岐内のスコープ

条件分岐 `|` `|>` 内で定義された変数は、その分岐内でのみ有効です。

```taida
processValue value: Int =
  result <=
    | value > 100 |>
      message <= "large"  // この分岐内でのみ有効
      message
    | value > 50 |>
      message <= "medium"  // 別の分岐、同名でも別変数
      message
    | _ |>
      "small"

  // message はここからアクセス不可
  result
=> :Str
```

### 分岐外で値を使いたい場合

分岐の戻り値として受け取ります。

```taida
processValue value: Int =
  // 分岐全体の結果を result に代入
  result <=
    | value > 100 |>
      message <= "large: " + value
      @(category <= "large", display <= message)
    | _ |>
      @(category <= "small", display <= "small value")

  // result を通じてアクセス
  result.category  // OK
  result.display   // OK
=> :@(category: Str, display: Str)
```

---

## エラー天井内のスコープ

エラー天井 `|==` 内で定義された変数は、そのエラー天井内でのみ有効です。

```taida
processData data: Data =
  |== error: Error =
    // error はこのブロック内でのみ有効
    message <= "Error: " + error.message
    @(success <= false, error_message <= message)
  => :@(success: Bool, error_message: Str)

  // error, message はここからアクセス不可
  processed <= doProcess(data)
  @(success <= true, error_message <= "")
=> :@(success: Bool, error_message: Str)
```

---

## シャドウイング

同一スコープ内での同名変数の再定義（シャドウイング）は禁止されています。

```taida
// NG: 同一スコープでの再定義
x <= 10
x <= 20  // コンパイルエラー: 'x' は既に定義されています

// NG: 関数内での再定義
processData data =
  temp <= data.value
  temp <= temp * 2  // コンパイルエラー
=> :Int
```

### 異なるスコープでは許可

```taida
x <= 10  // モジュールスコープ

process =
  x <= 20  // 関数スコープ、これは許可される（ただし外側のxを隠す）
  x
=> :Int

// 外側の x は変更されていない
result <= x  // 10
```

> **注意**: 異なるスコープでのシャドウイングは許可されますが、混乱を避けるため推奨されません。

---

## 再代入の禁止

Taida Langではすべての変数はイミュータブルです。一度定義した変数に再代入することはできません。

```taida
// NG: 再代入
counter <= 0
counter <= counter + 1  // コンパイルエラー

// OK: 新しい変数を定義
counter_initial <= 0
counter_updated <= counter_initial + 1
```

### イミュータブルな更新パターン

```taida
// リストの「更新」
original <= @[1, 2, 3]
// 新しいリストを生成
Map[original, _ x = x * 2]() ]=> updated
// original: @[1, 2, 3] (変更されない)
// updated: @[2, 4, 6]

// ぶちパックの「更新」
pilot <= @(name <= "Misato", age <= 14)
// 新しいぶちパックを生成
updated_pilot <= @(name <= pilot.name, age <= pilot.age + 1)
```

---

## スコープのまとめ

```taida
// === モジュールスコープ ===
Config = @(timeout: Int)  // 型定義
DEFAULT_TIMEOUT <= 5000   // 定数
config <= Config(timeout <= DEFAULT_TIMEOUT)  // 変数

processRequest request: Request =
  // === 関数スコープ ===
  // request は引数（関数スコープ）
  timeout <= config.timeout  // 外側のconfigにアクセス可能

  helper =
    // === ネストした関数スコープ ===
    // timeout, request にアクセス可能
    request.data
  => :Data

  result <=
    | request.valid |>
      // === 分岐スコープ ===
      data <= helper()
      processData(data)
    | _ |>
      // === 別の分岐スコープ ===
      @(error <= "invalid")

  result
=> :Result

// モジュールスコープからは Config, DEFAULT_TIMEOUT, config, processRequest にアクセス可能
// timeout, helper, result などにはアクセス不可
```

---

# 標準ライブラリリファレンス

## 概要

Taida は**プリリュード**と**ビルトイン型**で構成されています。全てインポート不要で使用できます。

> **PHILOSOPHY.md — I.** 深く考えずに適当にぶちこんでけ

操作系の処理はモールドとして提供されます。詳細は `reference/mold_types.md` を参照してください。
メソッドは状態チェックとモナディック操作に限定されています。詳細は `reference/standard_methods.md` を参照してください。
Prelude の追加可否基準は `docs/design/prelude_boundary.md` を参照してください。

---

## プリリュード関数

インポート不要で使用できる関数です。

### 入出力

| 関数 | 説明 | 例 |
|------|------|-----|
| `stdout(msg)` | 標準出力に出力し、書き込んだ UTF-8 バイト数を返す（`Int`） | `bytes <= stdout("作戦開始")` |
| `stderr(msg)` | 標準エラー出力に出力し、書き込んだ UTF-8 バイト数を返す（`Int`） | `bytes <= stderr("警告: 残弾なし")` |
| `stdin(prompt)` | プロンプトを表示して入力を受け取る（`Str`） | `name <= stdin("名前: ")` |
| `nowMs()` | 現在時刻（epoch ミリ秒）を取得（`Int`） | `start <= nowMs()` |
| `sleep(ms)` | 指定ミリ秒待機する（`Async[Unit]`） | `sleep(10) ]=> _done` |

```taida
// Misato の日常業務
stdout("NERV 作戦部、葛城ミサトです")
stderr("警告: エヴァ初号機の同期率が低下しています")
name <= stdin("オペレーター名を入力: ")
stdout("了解、" + name + "。作戦を開始します")

start <= nowMs()
wait <= sleep(10)
wait ]=> _done
end <= nowMs()
stdout((end - start).toString())
```

#### `stdout` / `stderr` 戻り値（C12 以降）

`stdout(...)` と `stderr(...)` は書き込んだペイロードの UTF-8 バイト数を
`Int` で返します（末尾の改行は含まない）。

```taida
// 書き込みバイト数を受け取る
bytes <= stdout("hello")   // bytes = 5
stdout(bytes)              // "5"

// 従来どおり、文として使う場合は値は自然に破棄される
stdout("そのまま動く")     // 値を受け取らない書き方も互換
```

`Value::Unit` は Taida プログラムからは観測できません。これは
PHILOSOPHY I（「null/undefined の完全排除」）に沿った設計です
— 副作用関数もデフォルト値を持つ `Int` を返し、常に何かを返す
という不変条件を保ちます。

### JSON シリアライズ

| 関数 | 説明 | 例 |
|------|------|-----|
| `jsonEncode(value)` | ぶちパックを JSON 文字列に変換 | `jsonEncode(data)` |
| `jsonPretty(value)` | ぶちパックを整形 JSON 文字列に変換 | `jsonPretty(data)` |

```taida
pilot <= @(name <= "Misato", age <= 29, role <= "Operations Director")
jsonEncode(pilot)   // `{"name":"Misato","age":29,"role":"Operations Director"}`
jsonPretty(pilot)
// {
//   "name": "Misato",
//   "age": 29,
//   "role": "Operations Director"
// }
```

> **注意**: JSON のパース（外部データ → Taida 値）には `JSON[raw, Schema]()` モールドを使用します。詳細は `docs/design/json_molten_iron.md` を参照してください。

### ユーティリティ

| 関数 | 説明 | 例 |
|------|------|-----|
| `typeof(x)` | 型名を文字列で返す | `typeof(42)` → `"Int"` |
| `range(start, end)` | 整数リスト生成 | `range(0, 5)` → `@[0, 1, 2, 3, 4]` |
| `debug(x)` | デバッグ出力して値をそのまま返す | `5 => debug => result` |

```taida
// debug はパイプラインの途中に挿入できます
scores <= @[95, 82, 78, 91]
scores => Filter[_, _ x = x > 80]() => debug => Map[_, _ x = x * 2]() => result
// debug で中間結果が stderr に出力されます

>>> taida-lang/crypto@a.1 => @(sha256)
token <= sha256("abc")
stdout(token)  // ba7816bf8f01cfea...f20015ad
```

`taida-lang/crypto` の拡張契約（HMAC/KDF/安全乱数/署名検証）は `docs/design/crypto_package_contract.md` を参照してください。

---

## Core Builtins（数値・バイト列）

インポート不要の組み込み型/モールドです。`Bytes` は Prelude 関数ではなく Core Builtin です。

### 型

| 型 | デフォルト値 | 用途 |
|---|---|---|
| `Int` | `0` | 64bit 整数 |
| `Float` | `0.0` | 浮動小数点 |
| `Bytes` | `Bytes[@[]]` | 0..255 のバイト列 |

### 数値拡張モールド

| モールド | 戻り値 | 説明 |
|---|---|---|
| `BitAnd[a, b]()` / `BitOr[a, b]()` / `BitXor[a, b]()` / `BitNot[x]()` | `Int` | ビット演算 |
| `ShiftL[x, n]()` / `ShiftR[x, n]()` / `ShiftRU[x, n]()` | `Lax[Int]` | シフト（`n` は 0..63 で成功） |
| `ToRadix[int, base]()` | `Lax[Str]` | `base`（2..36）への基数変換 |
| `Int[str, base]()` | `Lax[Int]` | 指定基数の文字列を整数化 |

> ビット演算子は追加しません。上記モールドを使用します。

### バイト列・Unicode モールド

| モールド | 戻り値 | 説明 |
|---|---|---|
| `UInt8[x]()` | `Lax[Int]` | `0..255` 制約付き変換 |
| `Bytes[x](fill <= n)` | `Lax[Bytes]` | `Int/Str/@[Int]/Bytes` から Bytes へ変換 |
| `ByteSet[bytes, idx, value]()` | `Lax[Bytes]` | 指定位置更新（不変） |
| `BytesToList[bytes]()` | `@[Int]` | Bytes を整数リストへ変換 |
| `BytesCursor[bytes](offset <= n)` | `@(bytes: Bytes, offset: Int, length: Int)` | Bytes の順次読み取りカーソルを生成 |
| `BytesCursorRemaining[cursor]()` | `Int` | 残り読み取り可能バイト数を返す |
| `BytesCursorTake[cursor, size]()` | `Lax[@(value: Bytes, cursor: @(...))]` | `size` バイト読み取り + カーソル前進 |
| `BytesCursorU8[cursor]()` | `Lax[@(value: Int, cursor: @(...))]` | 1バイト読み取り（`0..255`）+ カーソル前進 |
| `U16BE[x]()` / `U16LE[x]()` | `Lax[Bytes]` | 16bit 符号なし整数を endian 指定で2バイトへパック |
| `U32BE[x]()` / `U32LE[x]()` | `Lax[Bytes]` | 32bit 符号なし整数を endian 指定で4バイトへパック |
| `U16BEDecode[bytes]()` / `U16LEDecode[bytes]()` | `Lax[Int]` | 2バイトを endian 指定で 16bit 整数へデコード |
| `U32BEDecode[bytes]()` / `U32LEDecode[bytes]()` | `Lax[Int]` | 4バイトを endian 指定で 32bit 整数へデコード |
| `Char[x]()` | `Lax[Str]` | 1文字への変換 |
| `CodePoint[str]()` | `Lax[Int]` | 1文字のコードポイント取得 |
| `Utf8Encode[str]()` | `Lax[Bytes]` | UTF-8 エンコード |
| `Utf8Decode[bytes]()` | `Lax[Str]` | UTF-8 デコード（不正列は failure） |

`UnsafePointer` はコア言語に導入しません。必要な低レベル連携は不透明ハンドル（`Molten`）+ 専用APIで隔離します。

---

## プリリュード型コンストラクタ

インポート不要で使用できる型コンストラクタです。

### Result

述語付き操作モールドです。述語 P（`:T => :Bool`）で成功/失敗を判定します。`]=>` で述語を評価し、真なら値 T、偽なら throw が発動します。

| 構文 | 説明 | 例 |
|------|------|-----|
| `Result[value, _ = true]()` | 常に成功の Result | `Result[42, _ = true]()` |
| `Result[value, _ = false](throw <= error)` | 常に失敗の Result | `Result[0, _ = false](throw <= err)` |
| `Result[value, pred](throw <= error)` | 述語で判定する Result | `Result[age, _ x = x >= 18](throw <= err)` |

```taida
Error => ValidationError = @(message: Str)

validateAge age: Int =
  Result[age, _ x = x > 0](throw <= ValidationError(type <= "ValidationError", message <= "年齢は正の値でなければなりません"))
=> :Result[Int, _]
```


### Gorillax / Cage

覚悟のモールド型です。unmold 失敗時にデフォルト値ではなくゴリラ（プログラム即終了）が発動します。

| 構文 | 説明 | 例 |
|------|------|-----|
| `Gorillax[value]()` | 値を Gorillax で包む | `Gorillax[42]()` |
| `Cage[molten, fn]()` | Molten 専用。fn(molten) を実行し Gorillax で包む | `Cage[lodash, _ lo = lo.sum(items)]()` |

```taida
// Cage で溶鉄に操作 → Gorillax で受け取る
Cage[externalLib, _ lib = lib.process(data)] => result
result ]=> value         // 成功 → 値, 失敗 → ゴリラ

// .relax() で |== キャッチ可能に変換
result.relax() => relaxed  // relaxed: RelaxedGorillax[T]
```

### コレクション

| コンストラクタ | 説明 | 例 |
|--------------|------|-----|
| `hashMap()` | 空の HashMap を生成 | `hashMap()` |
| `setOf(list)` | リストから Set を生成 | `setOf(@[1, 2, 3])` |

---

## HashMap メソッド

HashMap はイミュータブルです。変更操作は新しい HashMap を返します。

```taida
pilots <= hashMap()
  .set("Misato", @(age <= 29, role <= "Operations Director"))
  .set("Ritsuko", @(age <= 30, role <= "Chief Scientist"))
```

| メソッド | 戻り値 | 説明 |
|---------|--------|------|
| `.get(key)` | `Lax[V]` | キーに対応する値を取得 |
| `.set(key, value)` | `HashMap[K, V]` | キーと値を追加した新しい HashMap |
| `.remove(key)` | `HashMap[K, V]` | キーを削除した新しい HashMap |
| `.has(key)` | `Bool` | キーが存在するか |
| `.keys()` | `@[K]` | キーのリスト |
| `.values()` | `@[V]` | 値のリスト |
| `.entries()` | `@[@(key, value)]` | キーと値のペアのリスト |
| `.size()` | `Int` | エントリ数 |
| `.merge(other)` | `HashMap[K, V]` | 2つの HashMap を結合した新しい HashMap |
| `.isEmpty()` | `Bool` | 空かどうか |
| `.toString()` | `Str` | 文字列表現 |

```taida
// get は Lax を返します
pilots.get("Misato").hasValue  // true
pilots.get("Gendo").hasValue   // false

// イミュータブルなので元の HashMap は変化しません
updated <= pilots.set("Shinji", @(age <= 14, role <= "Pilot"))
pilots.has("Shinji")   // false
updated.has("Shinji")  // true

// merge で結合
staff <= pilots.merge(updated)
```

---

## Set メソッド

Set もイミュータブルです。変更操作は新しい Set を返します。

```taida
pilotNames <= setOf(@["Misato", "Ritsuko", "Shinji"])
```

| メソッド | 戻り値 | 説明 |
|---------|--------|------|
| `.add(item)` | `Set[T]` | 要素を追加した新しい Set |
| `.remove(item)` | `Set[T]` | 要素を削除した新しい Set |
| `.has(item)` | `Bool` | 要素が含まれているか |
| `.union(other)` | `Set[T]` | 和集合 |
| `.intersect(other)` | `Set[T]` | 積集合 |
| `.diff(other)` | `Set[T]` | 差集合 |
| `.toList()` | `@[T]` | リストに変換 |
| `.size()` | `Int` | 要素数 |
| `.isEmpty()` | `Bool` | 空かどうか |
| `.toString()` | `Str` | 文字列表現 |

```taida
bridge <= setOf(@["Misato", "Ritsuko", "Maya"])
pilots <= setOf(@["Shinji", "Rei", "Asuka"])

// 集合演算
all <= bridge.union(pilots)
all.size()  // 6

bridge.has("Misato")  // true
bridge.has("Shinji")  // false

// 差集合で「パイロットでないスタッフ」を取得
staff <= all.diff(pilots)
```


---

# 標準メソッドリファレンス

## 概要

プリミティブ型およびリスト型で使用できる標準メソッドのリファレンスです。

メソッドは**状態チェック**（内部状態を問い合わせる）と**表示用**（toString）に限定されています。
操作系の処理はモールドとして提供されます。詳細は `reference/mold_types.md` を参照してください。

## 設計原則

- **状態チェックメソッド**: 対象の内部状態を Bool/Int で返す。変換は行わない
- **モナディック操作メソッド**: Result/Lax/Async 固有の map/flatMap/mapError
- **toString メソッド**: デバッグ・表示用の文字列変換
- **操作はモールドで**: 値の変換・加工はモールドを使用する

> **PHILOSOPHY.md — III.** カタめたいなら、鋳型を作りましょう

---

## `.toString()` — 全型共通の表示メソッド

全ての値は `.toString()` を呼び出せます。戻り値は常に `:Str` で、
インタプリタ / JS / Native の 3 バックエンドで同一の文字列が得られます。

```taida
42.toString()             // "42"
3.14.toString()           // "3.14"
true.toString()           // "true"
"hello".toString()        // "hello"
@[1, 2, 3].toString()     // "@[1, 2, 3]"
@(a <= 1, b <= 2).toString()  // "@(a <= 1, b <= 2)"
```

- 引数なしで呼び出すこと。`n.toString(16)` のように base や precision を
  渡そうとすると、チェッカーが `[E1508] Method 'toString' takes 0 argument(s)`
  で拒否します（哲学 I: 暗黙の型変換なし）。
- 基数指定で整数を文字列化したい場合は `ToRadix[n, base]()` モールド
  （`reference/mold_types.md §ToRadix`）を使います。戻り値は `Lax[Str]`
  なので `.getOrDefault("")` で unwrap します。
- 数値を Lax にラップして扱いたい場合は `Str[value]()` モールドを使います。
  `.toString()` は直接 `Str` を返すため、`+` 演算子で文字列連結する場合に
  便利です。

---

## Str — 文字列メソッド

### 状態チェック

#### length

文字列の長さを返します。

```taida
"hello".length()  // 5
"".length()       // 0
"日本語".length()   // 3 (文字数)
```

**シグネチャ**: `=> :Int`

#### contains

部分文字列が含まれているかを返します。

```taida
"hello world".contains("world")  // true
"hello".contains("xyz")  // false
```

**シグネチャ**: `substr: Str => :Bool`

#### startsWith

指定した文字列で始まるかを返します。

```taida
"hello world".startsWith("hello")  // true
"hello".startsWith("world")  // false
```

**シグネチャ**: `prefix: Str => :Bool`

#### endsWith

指定した文字列で終わるかを返します。

```taida
"hello world".endsWith("world")  // true
"hello".endsWith("xyz")  // false
```

**シグネチャ**: `suffix: Str => :Bool`

#### indexOf

部分文字列の位置を返します。見つからない場合は -1。

```taida
"hello world".indexOf("world")  // 6
"hello".indexOf("xyz")  // -1
```

**シグネチャ**: `substr: Str => :Int`

#### lastIndexOf

部分文字列の最後の出現位置を返します。見つからない場合は -1。

```taida
"hello hello".lastIndexOf("hello")  // 6
"hello".lastIndexOf("xyz")  // -1
```

**シグネチャ**: `substr: Str => :Int`

### 安全アクセス

#### get

指定インデックスの文字を Lax で返します。範囲外の場合は `hasValue = false`。

```taida
"hello".get(0) ]=> ch    // "h"
"hello".get(10) ]=> ch   // "" (デフォルト値)
"hello".get(10).hasValue  // false
```

**シグネチャ**: `index: Int => :Lax[Str]`

### 文字列変換

#### toString

文字列をそのまま返します（他の型との一貫性のため）。

```taida
"hello".toString()  // "hello"
```

**シグネチャ**: `=> :Str`

### 文字列操作

#### replace

最初に一致した部分文字列を置換します。引数が `:Str` の場合は固定文字列
マッチ、`:Regex` の場合は正規表現マッチになります。

```taida
"hello world".replace("world", "taida")  // "hello taida"
"aaa".replace("a", "b")  // "baa" (最初の一致のみ)

// C12 Phase 6 (FB-5): Regex overload
"hello".replace(Regex("[aeiou]"), "*")  // "h*llo"
```

**シグネチャ**:

- `target: Str, replacement: Str => :Str`
- `pattern: Regex, replacement: Str => :Str`

空ターゲット文字列の場合は元の文字列を返します（no-op）。Regex 置換で
は JS の `$&` / `$1` 系メタ構文は無効化され、置換文字列はリテラルとして
挿入されます。

#### replaceAll

すべての一致する部分文字列を置換します。

```taida
"hello world hello".replaceAll("hello", "hi")  // "hi world hi"
"aaa".replaceAll("a", "b")  // "bbb"

// C12 Phase 6 (FB-5): Regex overload
"hello".replaceAll(Regex("[aeiou]"), "*")  // "h*ll*"
"a1b2c3".replaceAll(Regex("\\d"), "#")     // "a#b#c#"
```

**シグネチャ**:

- `target: Str, replacement: Str => :Str`
- `pattern: Regex, replacement: Str => :Str`

空ターゲット文字列の場合は元の文字列を返します（no-op）。

#### split

文字列をセパレータで分割し、リストを返します。

```taida
"a,b,c".split(",")  // @["a", "b", "c"]
"hello".split(",")  // @["hello"] (一致なし → 単一要素)
"abc".split("")     // @["a", "b", "c"] (文字ごとに分割)

// C12 Phase 6 (FB-5): Regex overload
"one,two;three.four".split(Regex("[,;.]"))  // @["one", "two", "three", "four"]
```

**シグネチャ**:

- `separator: Str => :List[Str]`
- `pattern: Regex => :List[Str]`

空セパレータの場合は各文字に分割します（`Chars[]` モールドと同等）。

#### match

正規表現で最初の一致を取り出します。結果は `:RegexMatch` ぶちパックで、
`hasValue`, `full`, `groups`, `start` フィールドを持ちます。

```taida
m <= "id: 12-34".match(Regex("(\\d+)-(\\d+)"))
stdout(m.hasValue)  // true
stdout(m.full)       // "12-34"
stdout(m.groups)     // @["12", "34"]
stdout(m.start)      // 4  (char index, not byte index)
```

**シグネチャ**: `pattern: Regex => :RegexMatch`

一致なしの場合 `hasValue <= false`, `full <= ""`, `groups <= @[]`,
`start <= -1` のぶちパックを返します（null / undefined は返さない —
哲学 I）。

#### search

正規表現で最初の一致が見つかった位置（char index）を返します。一致が
ない場合は `-1` を返します。

```taida
stdout("abc123".search(Regex("\\d+")))  // 3
stdout("nothing".search(Regex("\\d+"))) // -1
```

**シグネチャ**: `pattern: Regex => :Int`

文字列内での固定文字列検索には `.indexOf(...)` を使用してください。
`search` は必ず `Regex` 引数を要求します。

#### Regex コンストラクタ

`Regex(pattern, flags?)` で正規表現オブジェクトを作成します（C12 Phase 6）。

```taida
r <= Regex("[aeiou]")          // flags なし
ri <= Regex("hello", "i")      // case-insensitive
```

**シグネチャ**: `pattern: Str, flags: Str => :Regex`

サポートされるフラグ:

| フラグ | 意味 |
|--------|------|
| `i` | 大文字小文字を無視 |
| `m` | 複数行モード（`^` / `$` が各行にマッチ） |
| `s` | dotall — `.` が改行にマッチ（Interpreter / JS のみ。Native の POSIX ERE はサポート外）|

サポートされるエスケープ:

| エスケープ | 意味 | 3 backend 対応 |
|-----------|------|----------------|
| `\d` / `\D` | 数字 / 数字以外 | 全 backend |
| `\w` / `\W` | 単語文字（英数字 + `_`）/ それ以外 | 全 backend |
| `\s` / `\S` | 空白文字 / 空白以外 | 全 backend |
| `\xHH` / `\x{HH…}` | 16 進コードポイント（1 バイト）| 全 backend |
| `\uHHHH` / `\u{HH…}` | Unicode コードポイント（UTF-8 エンコード）| 全 backend |
| `\\` | リテラルな `\` | 全 backend |
| `\b` / `\B` | 単語境界 / 単語境界以外 | Interpreter / JS のみ |

Native POSIX ERE は `\b` / `\B` に対応する概念を持ちません。単語境界が
必要な場合は Interpreter / JS ターゲットに限定するか、
`(^|[^A-Za-z0-9_])` などで明示的に囲むパターンに書き換えてください。

上記の表にない `\_` / `\/` のような意味を持たない「identity escape」は、
Interpreter（Rust `regex`）と Native（POSIX ERE）が lenient に受け付ける
ため、JS backend でも同じ挙動になるようコンパイル時に JS の `/u` 厳格
モードを無効化しています（C12B-040）。

`\x{HH…}` / `\u{HH…}` の bracket 形式は JS の `/u` モードでしか native に
解釈されませんが、同じ理由で `/u` を使えないため、JS ランタイムは
bracket 形式を `\uHHHH` あるいは UTF-16 サロゲートペアへ事前 rewrite
してから `RegExp` へ渡します。結果として **construct 時の検証と
first-use 時の実行が同じ文法**で動作し、`Regex("\x{41}")` のような
パターンが構築だけ成功して初回使用時に throw するといった asymmetric
な失敗モードは発生しません（C12B-040）。

不正なフラグや不正なパターンは **3 backend 全て** で構築時に
`:Error`（`ValueError`）が投げられます（C12B-029）。JavaScript の
`$&` / `$1` 等の置換メタ構文は無効化されており、置換文字列はリテラルと
して挿入されます。

### 操作はモールドでも可能

以下の操作はモールドとしても提供されます:

| 操作 | モールド | 例 |
|------|---------|-----|
| 大文字変換 | `Upper[str]()` | `Upper["hello"]()` → `"HELLO"` |
| 小文字変換 | `Lower[str]()` | `Lower["HELLO"]()` → `"hello"` |
| 空白除去 | `Trim[str]()` | `Trim["  hi  "]()` → `"hi"` |
| 分割 | `Split[str, delim]()` | `Split["a,b", ","]()` → `@["a", "b"]` |
| 置換 | `Replace[str, old, new]()` | `Replace["ab", "a", "x"]()` → `"xb"` |
| 範囲抽出 | `Slice[str]()` | `Slice["hello"](end <= 3)` → `"hel"` |
| 文字取得 | `CharAt[str, idx]()` | `CharAt["hello", 0]() ]=> ch` → `"h"` (Lax[Str]) |
| 繰り返し | `Repeat[str, n]()` | `Repeat["ha", 3]()` → `"hahaha"` |
| 逆順 | `Reverse[str]()` | `Reverse["hello"]()` → `"olleh"` |
| パディング | `Pad[str, len]()` | `Pad["42", 5](side <= "start", char <= "0")` → `"00042"` |
| 型変換 | `Int[str]()` / `Int[str, base]()` / `Float[str]()` | `Int["42"]() ]=> num` → `42`, `Int["ff", 16]() ]=> hex` → `255` |

---

## Bytes — バイト列メソッド

`Bytes` は 0..255 の連続領域です。バイナリ境界で使います。

### 状態チェック

#### length

バイト数を返します。

```taida
Bytes["ping"]() ]=> b
b.length()  // 4
```

**シグネチャ**: `=> :Int`

### 安全アクセス

#### get

指定インデックスのバイト値を `Lax[Int]` で返します。範囲外は `hasValue = false`。

```taida
Bytes[@[65, 66]]() ]=> b
b.get(0) ]=> v    // 65
b.get(99).hasValue  // false
```

**シグネチャ**: `index: Int => :Lax[Int]`

### 文字列変換

#### toString

表示用の `Bytes[@[...]]` 形式へ変換します。

```taida
Bytes[@[65, 66]]() ]=> b
b.toString()  // "Bytes[@[65, 66]]"
```

**シグネチャ**: `=> :Str`

### 操作はモールドで

```taida
ByteSet[b, 1, 67]() ]=> b2
Slice[b](start <= 0, end <= 1)      // Bytes
Concat[b, b2]()                      // Bytes
BytesToList[b2]()                    // @[Int]
Utf8Decode[b2]()                     // Lax[Str]
```

---

## Molten -- 溶鉄（メソッドなし）

`Molten` 型はメソッドを一切持ちません。Molten は外部由来の不透明値であり、直接操作はできません。型パラメータはありません -- Molten は Molten でしかありません。

```taida
>>> npm:lodash => @(lodash)  // lodash: Molten

// これらは全てエラーになります
lodash.sum()          // エラー: Molten has no methods
lodash.toString()     // エラー: Molten has no methods
lodash.length()       // エラー: Molten has no methods
```

Molten 値を操作するには Cage を使います。JS バックエンドでは JSNew, JSSet, JSBind, JSSpread モールドも利用可能です。

JSON は Molten の特殊ケースです。JSON もメソッドを持ちません（詳細は下記の JSON セクションを参照）。

---

## JSON -- 溶鉄（メソッドなし）

`JSON` 型はメソッドを一切持ちません。JSON は Molten の特殊ケースであり、外部由来の不透明値です。

```taida
// これらは全てエラーになります
data.at("name")       // エラー: JSON has no methods
data.toStr()           // エラー: JSON has no methods
data.keys()            // エラー: JSON has no methods
data ]=> x             // エラー: JSON direct unmold is not allowed
```

JSON を使うには `JSON[raw, Schema]()` でスキーマを指定してください。詳細は [JSON 溶鉄](../guide/03_json.md) を参照してください。

---

## Num — 数値メソッド (Int / Float)

### 状態チェック

#### isNaN

NaN (非数) かどうかを返します。

```taida
42.isNaN()     // false
0.0.isNaN()    // false
```

**シグネチャ**: `=> :Bool`

> **注意**: Taida に `/` 演算子はなく、`Div[x, y]()` モールドが Lax を返すため、通常の計算で NaN が生成されることはありません。外部データ（JSON など）から受け取った値の検査に使用します。

#### isInfinite

無限大かどうかを返します。

```taida
42.isInfinite()  // false
```

**シグネチャ**: `=> :Bool`

#### isFinite

有限数かどうかを返します。

```taida
42.isFinite()   // true
3.14.isFinite() // true
```

**シグネチャ**: `=> :Bool`

#### isPositive

正の数かどうかを返します。

```taida
5.isPositive()  // true
(-5).isPositive()  // false
0.isPositive()  // false
```

**シグネチャ**: `=> :Bool`

#### isNegative

負の数かどうかを返します。

```taida
(-5).isNegative()  // true
5.isNegative()  // false
```

**シグネチャ**: `=> :Bool`

#### isZero

ゼロかどうかを返します。

```taida
0.isZero()  // true
0.0.isZero()  // true
1.isZero()  // false
```

**シグネチャ**: `=> :Bool`

### 文字列変換

#### toString

数値を文字列に変換します。

```taida
42.toString()  // "42"
3.14.toString()  // "3.14"
```

**シグネチャ**: `=> :Str`

### 操作はモールドで

以下の操作はモールドとして提供されます:

| 操作 | モールド | 例 |
|------|---------|-----|
| 小数点固定 | `ToFixed[num, digits]()` | `ToFixed[3.14159, 2]()` → `"3.14"` |
| 絶対値 | `Abs[num]()` | `Abs[-5]()` → `5` |
| 切り捨て | `Floor[num]()` | `Floor[3.7]()` → `3` |
| 切り上げ | `Ceil[num]()` | `Ceil[3.2]()` → `4` |
| 四捨五入 | `Round[num]()` | `Round[3.5]()` → `4` |
| 0方向切り捨て | `Truncate[num]()` | `Truncate[3.7]()` → `3` |
| 範囲制限 | `Clamp[num, min, max]()` | `Clamp[15, 0, 10]()` → `10` |

---

## List — リストメソッド

### 状態チェック

#### length

リストの要素数を返します。

```taida
@[1, 2, 3].length()  // 3
@[].length()  // 0
```

**シグネチャ**: `=> :Int`

#### isEmpty

リストが空かどうかを返します。

```taida
@[].isEmpty()  // true
@[1].isEmpty()  // false
```

**シグネチャ**: `=> :Bool`

#### contains

要素が含まれているかを返します。

```taida
@[1, 2, 3].contains(2)  // true
@[1, 2, 3].contains(5)  // false
```

**シグネチャ**: `item: T => :Bool`

#### indexOf

要素の位置を返します。見つからない場合は -1。

```taida
@[10, 20, 30].indexOf(20)  // 1
@[10, 20, 30].indexOf(50)  // -1
```

**シグネチャ**: `item: T => :Int`

#### lastIndexOf

要素の最後の出現位置を返します。見つからない場合は -1。

```taida
@[1, 2, 1, 2].lastIndexOf(1)  // 2
```

**シグネチャ**: `item: T => :Int`

### 安全アクセス（Lax 返し）

#### first

最初の要素を Lax で返します。空リストの場合は `hasValue = false`。

```taida
@[1, 2, 3].first() ]=> val  // 1
@[].first().hasValue         // false
```

**シグネチャ**: `=> :Lax[T]`

#### last

最後の要素を Lax で返します。空リストの場合は `hasValue = false`。

```taida
@[1, 2, 3].last() ]=> val  // 3
@[].last().hasValue         // false
```

**シグネチャ**: `=> :Lax[T]`

#### get

指定インデックスの要素を Lax で返します。範囲外の場合は `hasValue = false`。

```taida
@[10, 20, 30].get(1) ]=> val    // 20
@[10, 20, 30].get(10).hasValue  // false
```

**シグネチャ**: `index: Int => :Lax[T]`

#### max

最大値を Lax で返します。空リストの場合は `hasValue = false`。

```taida
@[1, 3, 2].max() ]=> val  // 3
@[].max().hasValue         // false
```

**シグネチャ**: `=> :Lax[T]`

#### min

最小値を Lax で返します。空リストの場合は `hasValue = false`。

```taida
@[1, 3, 2].min() ]=> val  // 1
@[].min().hasValue         // false
```

**シグネチャ**: `=> :Lax[T]`

### 述語（状態チェック）

#### any

いずれかの要素が条件を満たすかを返します。

```taida
@[1, 2, 3].any(_ x = x > 2)  // true
@[1, 2, 3].any(_ x = x > 10)  // false
```

**シグネチャ**: `pred: :T => :Bool => :Bool`

#### all

すべての要素が条件を満たすかを返します。

```taida
@[2, 4, 6].all(_ x = Mod[x, 2]().unmold() == 0)  // true
@[1, 2, 3].all(_ x = x > 2)  // false
```

**シグネチャ**: `pred: :T => :Bool => :Bool`

#### none

すべての要素が条件を満たさないかを返します。

```taida
@[1, 2, 3].none(_ x = x > 10)  // true
@[1, 2, 3].none(_ x = x > 2)  // false
```

**シグネチャ**: `pred: :T => :Bool => :Bool`

### 操作はモールドで

以下の操作はモールドとして提供されます:

| 操作 | モールド | 例 |
|------|---------|-----|
| 逆順 | `Reverse[list]()` | `Reverse[@[1,2,3]]()` → `@[3,2,1]` |
| 結合 | `Concat[list, other]()` | `Concat[@[1,2], @[3,4]]()` → `@[1,2,3,4]` |
| 末尾追加 | `Append[list, val]()` | `Append[@[1,2], 3]()` → `@[1,2,3]` |
| 先頭追加 | `Prepend[list, val]()` | `Prepend[@[2,3], 1]()` → `@[1,2,3]` |
| 文字列結合 | `Join[list, sep]()` | `Join[@["a","b"], ","]()` → `"a,b"` |
| 合計 | `Sum[list]()` | `Sum[@[1,2,3]]()` → `6` |
| ソート | `Sort[list]()` | `Sort[@[3,1,2]]()` → `@[1,2,3]` |
| 重複除去 | `Unique[list]()` | `Unique[@[1,2,2,3]]()` → `@[1,2,3]` |
| フラット化 | `Flatten[list]()` | `Flatten[@[@[1],@[2]]]()` → `@[1,2]` |
| 条件検索 | `Find[list, fn]()` | `Find[@[1,2,3], _ x = x > 1]()` → `Lax(2)` |
| 位置検索 | `FindIndex[list, fn]()` | `FindIndex[@[1,2,3], _ x = x > 1]()` → `1` |
| 条件カウント | `Count[list, fn]()` | `Count[@[1,2,3], _ x = x > 1]()` → `2` |
| 先頭n個 | `Take[list, n]()` | `Take[@[1,2,3], 2]()` → `@[1,2]` |
| スキップ | `Drop[list, n]()` | `Drop[@[1,2,3], 1]()` → `@[2,3]` |
| ペア化 | `Zip[list, other]()` | `Zip[@[1,2], @["a","b"]]()` |
| インデックス付与 | `Enumerate[list]()` | `Enumerate[@["a","b"]]()` |
| フィルタ | `Filter[list, fn]()` | `Filter[@[1,2,3], _ x = x > 1]()` → `@[2,3]` |
| 変換 | `Map[list, fn]()` | `Map[@[1,2,3], _ x = x * 2]()` → `@[2,4,6]` |
| 左畳み込み | `Fold[list, init, fn]()` | `Fold[@[1,2,3], 0, _ a x = a + x]()` → `6` |
| 右畳み込み | `Foldr[list, init, fn]()` | `Foldr[@[1,2,3], 0, _ a x = a + x]()` → `6` |

---

## Bool — ブールメソッド

### 文字列変換

#### toString

真偽値を文字列に変換します。

```taida
true.toString()  // "true"
false.toString()  // "false"
```

**シグネチャ**: `=> :Str`

### 型変換はモールドで

`Int[bool]()` を使用してください。

```taida
Int[true]() ]=> num   // 1
Int[false]() ]=> num  // 0
```

---

## Lax — Lax メソッド

`Lax[T]` 型に対して使用できるメソッドです。Lax は `Div[x, y]()`、`Mod[x, y]()`、`get()`、`first()`、`last()`、`max()`、`min()` などの戻り値として得られます。

### フィールド

#### hasValue

値を持つかどうかを示すブールフィールドです。

```taida
Div[10, 3]().hasValue   // true
Div[10, 0]().hasValue   // false
```

**型**: `Bool`

### 検査

#### isEmpty

値を持たないかどうかを返します。`!hasValue` と同じです。

```taida
Div[10, 0]().isEmpty()  // true
Div[10, 3]().isEmpty()  // false
```

**シグネチャ**: `=> :Bool`

### 値の取得

#### getOrDefault

値があればその値を、なければ指定したデフォルト値を返します。

```taida
Div[10, 3]().getOrDefault(99)  // 3
Div[10, 0]().getOrDefault(99)  // 99
```

**シグネチャ**: `default: T => :T`

#### unmold

値を取り出します。`hasValue = false` の場合は型 T のデフォルト値を返します。

```taida
Div[10, 3]().unmold()  // 3
Div[10, 0]().unmold()  // 0 (Int のデフォルト値)
```

**シグネチャ**: `=> :T`

### モナディック操作

#### map

値がある場合に関数を適用し、新しい Lax を返します。

```taida
Div[10, 2]().map(_ x = x * 3) ]=> result  // 15
Div[10, 0]().map(_ x = x * 3) ]=> result  // 0 (空のまま)
```

**シグネチャ**: `fn: :T => :U => :Lax[U]`

#### flatMap

値がある場合に関数を適用し、関数が返す Lax をそのまま返します。

```taida
Div[10, 2]().flatMap(_ x = Div[x, 3]()) ]=> result  // 1
```

**シグネチャ**: `fn: :T => :Lax[U] => :Lax[U]`

### 文字列変換

#### toString

Lax の文字列表現を返します。

```taida
Div[10, 3]().toString()  // "Lax(3)"
Div[10, 0]().toString()  // "Lax(default: 0)"
```

**シグネチャ**: `=> :Str`

---

## Gorillax — 覚悟のモールドメソッド

`Gorillax[T]` 型に対して使用できるメソッドです。Gorillax は `Cage[value, fn]()` や `Gorillax[value]()` で生成されます。

### フィールド

#### hasValue

値を持つかどうかを示すブールフィールドです。

```taida
Gorillax[42]().hasValue  // true
```

**型**: `Bool`

### 検査

#### isEmpty

値を持たないかどうかを返します。

```taida
Gorillax[42]().isEmpty()  // false
```

**シグネチャ**: `=> :Bool`

### 変換

#### relax

Gorillax を RelaxedGorillax に変換します。unmold 失敗時のゴリラ（即終了）が `RelaxedGorillaEscaped` エラーの throw に変わり、`|==` でキャッチ可能になります。

```taida
Gorillax[42]().relax()  // RelaxedGorillax(42)
```

**シグネチャ**: `=> :RelaxedGorillax[T]`

### 文字列変換

#### toString

Gorillax の文字列表現を返します。

```taida
Gorillax[42]().toString()  // "Gorillax(42)"
```

**シグネチャ**: `=> :Str`

---

## RelaxedGorillax — リラックスしたゴリラメソッド

`RelaxedGorillax[T]` 型に対して使用できるメソッドです。`Gorillax.relax()` で生成されます。

### フィールド

#### hasValue

値を持つかどうかを示すブールフィールドです。

**型**: `Bool`

### 検査

#### isEmpty

値を持たないかどうかを返します。

**シグネチャ**: `=> :Bool`

### 文字列変換

#### toString

RelaxedGorillax の文字列表現を返します。

```taida
gorillax.relax().toString()  // "RelaxedGorillax(42)"
```

**シグネチャ**: `=> :Str`

---

## Result — モナディック型メソッド

`Result[T, P]` は `Mold[T] => Result[T, P <= :T => :Bool] = @(throw: Error)` として定義されます。述語 P が真を返す場合は成功、偽を返す場合は失敗（throw 発動）を表します。

### Result

| メソッド | シグネチャ | 説明 |
|---------|-----------|------|
| `throw` | `Error` | エラー値（フィールド） |
| `isSuccess()` | `=> :Bool` | 成功か（述語 P が真） |
| `isError()` | `=> :Bool` | エラーか（述語 P が偽） |
| `getOrDefault(default)` | `T => :T` | 安全な値取得 |
| `getOrThrow()` | `=> :T` | 値取得（失敗時エラーを throw） |
| `map(fn)` | `:T => :U => :Result[U, _]` | モナディック変換 |
| `flatMap(fn)` | `:T => :Result[U, _] => :Result[U, _]` | モナディック連鎖 |
| `mapError(fn)` | `:Error => :Error => :Result[T, P]` | throw フィールドのエラーを変換 |
| `toString()` | `=> :Str` | 文字列表現 |
| `unmold()` | `=> :T` | アンモールディング |

---

## Async — 非同期メソッド

| メソッド | シグネチャ | 説明 |
|---------|-----------|------|
| `isPending()` | `=> :Bool` | 実行中か |
| `isFulfilled()` | `=> :Bool` | 完了したか |
| `isRejected()` | `=> :Bool` | 失敗したか |
| `getOrDefault(default)` | `T => :T` | 安全な値取得 |
| `map(fn)` | `:T => :U => :Async[U]` | モナディック変換 |
| `toString()` | `=> :Str` | 文字列表現 |
| `unmold()` | `=> :T` | アンモールディング |

---

# 末尾再帰最適化 (Tail Recursion Optimization)

## 概要

末尾再帰最適化（TCO: Tail Call Optimization）は、関数の最後の操作が自分自身の呼び出しである場合に、スタックを消費せずに実行する最適化です。

## 設計原則

- **自動検出**: アノテーション不要（PHILOSOPHY.md — I.）
- **保証された最適化**: 末尾位置にある再帰呼び出しは必ず最適化される
- **エラーなし**: 末尾再帰でない場合もコンパイルエラーにはならない

---

## 末尾位置とは

「末尾位置」とは、その式の評価結果がそのまま関数の戻り値になる位置のことです。

### 末尾位置である例

```taida
// 関数の最後の式
factorial n: Int acc: Int =
  | n < 1 |> acc
  | _ |> factorial(n - 1, acc * n)  // ← 末尾位置
=> :Int
```

### 末尾位置でない例

```taida
// 再帰呼び出しの後に演算がある
factorial n: Int =
  | n < 1 |> 1
  | _ |> n * factorial(n - 1)  // ← 末尾位置ではない（乗算が後に続く）
=> :Int
```

---

## 末尾位置の判定ルール

### 1. 関数本体の最後の式

```taida
// 末尾位置
foo x: Int =
  bar(x)  // ← 関数本体の最後 = 末尾位置
=> :Int
```

### 2. 条件分岐の各分岐の最後

```taida
// 両方の分岐が末尾位置
factorial n: Int acc: Int =
  | n < 1 |> acc               // ← 末尾位置
  | _ |> factorial(n - 1, acc * n)  // ← 末尾位置
=> :Int
```

### 3. ネストした条件分岐の最後

```taida
classify x: Int =
  | x < 0 |>
    | x < -100 |> handleVeryNegative(x)  // ← 末尾位置
    | _ |> handleNegative(x)             // ← 末尾位置
  | x == 0 |> handleZero(x)              // ← 末尾位置
  | _ |>
    | x > 100 |> handleVeryPositive(x)   // ← 末尾位置
    | _ |> handlePositive(x)             // ← 末尾位置
=> :Int
```

### 4. エラーシーリング内の最後

```taida
process x: Int =
  |== error: Error =
    defaultValue  // ← 末尾位置（エラー分岐）
  => :Int

  calculate(x)    // ← 末尾位置（正常分岐）
=> :Int
```

---

## 末尾位置でないパターン

### 1. 演算子の引数

```taida
// NOT 末尾位置: 乗算の引数
badFactorial n: Int =
  | n < 1 |> 1
  | _ |> n * badFactorial(n - 1)  // × 乗算が後続
=> :Int
```

### 2. 関数呼び出しの引数

```taida
// NOT 末尾位置: wrapの引数
foo x: Int =
  wrap(foo(x - 1))  // × wrapの呼び出しが後続
=> :Int
```

### 3. 変数束縛の右辺

```taida
// NOT 末尾位置: 後続の式がある
foo x: Int =
  result <= bar(x)  // × 後に result の返却がある
  result
=> :Int
```

### 4. unmold/]=>の右辺

```taida
// NOT 末尾位置
foo x: Int =
  asyncOp(x) ]=> result  // × 後続処理がある
  result
=> :Int
```

---

## アキュムレータパターン

末尾再帰を実現する典型的なパターンは「アキュムレータ」を使う方法です。

### Before: 末尾再帰でない

```taida
// スタックが n 回積まれる
factorial n: Int =
  | n < 1 |> 1
  | _ |> n * factorial(n - 1)
=> :Int
```

### After: 末尾再帰

```taida
// スタックは1回のみ（最適化される）
factorial n: Int =
  factorialTail n 1
=> :Int

factorialTail n: Int acc: Int =
  | n < 1 |> acc
  | _ |> factorialTail(n - 1, acc * n)  // 末尾位置
=> :Int
```

---

## 実用例

### リストの合計

```taida
// 末尾再帰版
sum list: @[Int] =
  sumTail list 0
=> :Int

sumTail list: @[Int] acc: Int =
  | list.isEmpty() |> acc
  | _ |>
    list.first() ]=> head
    Drop[list, 1]() ]=> rest
    sumTail(rest, acc + head)
=> :Int
```

### リストの反転

```taida
// 末尾再帰版
reverse list: @[Int] =
  reverseTail list @[]
=> :@[Int]

reverseTail list: @[Int] acc: @[Int] =
  | list.isEmpty() |> acc
  | _ |>
    list.first() ]=> head
    Drop[list, 1]() ]=> rest
    Prepend[acc, head]() ]=> newAcc
    reverseTail(rest, newAcc)
=> :@[Int]
```

### フィボナッチ数列

```taida
// 末尾再帰版
fibonacci n: Int =
  fibTail n 0 1
=> :Int

fibTail n: Int a: Int b: Int =
  | n == 0 |> a
  | n == 1 |> b
  | _ |> fibTail(n - 1, b, a + b)
=> :Int
```

### 二分探索

```taida
binarySearch list: @[Int] target: Int =
  searchTail list target 0 (list.length() - 1)
=> :Int

searchTail list: @[Int] target: Int low: Int high: Int =
  | low > high |> 0 - 1
  | _ |>
    Div[low + high, 2]() ]=> mid
    list.get(mid) ]=> value
    | value == target |> mid
    | value < target |> searchTail(list, target, mid + 1, high)
    | _ |> searchTail(list, target, low, mid - 1)
=> :Int
```

### 文字列の繰り返し

```taida
repeat str: Str n: Int =
  repeatTail str n ""
=> :Str

repeatTail str: Str n: Int acc: Str =
  | n < 1 |> acc
  | _ |> repeatTail(str, n - 1, acc + str)
=> :Str
```

---

## 相互再帰

相互再帰（2つ以上の関数が互いを末尾位置で呼び出す）も末尾呼び出し最適化の対象です。コンパイラが関数間の呼び出しグラフを解析し、相互再帰グループを自動検出します。

```taida
// isEven と isOdd が互いを末尾位置で呼び出す → TCO が適用される
isEven n: Int =
  | n == 0 |> 1
  | _ |> isOdd(n - 1)
=> :Int

isOdd n: Int =
  | n == 0 |> 0
  | _ |> isEven(n - 1)
=> :Int

// 100,000 回の相互再帰でもスタックオーバーフローしない
stdout(isEven(100000))
```

### 相互再帰の条件

相互再帰が最適化されるための条件は、直接再帰と同じです:

1. **末尾位置**: 相手関数の呼び出しが末尾位置にあること
2. **自動検出**: アノテーション不要。コンパイラが呼び出しグラフから相互再帰グループを検出する
3. **3つ以上の関数**: 2関数に限らず、A->B->C->A のような3つ以上の関数の循環も最適化される

### バックエンド対応状況

| バックエンド | 直接再帰 TCO | 相互再帰 TCO |
|-------------|:-----------:|:-----------:|
| Interpreter | OK | OK |
| JS          | OK | OK |
| Native      | OK | 通常呼び出し |

Native バックエンドでは、相互再帰は通常の関数呼び出しとして実行されます。深い相互再帰ではスタックオーバーフローの可能性があるため、Interpreter または JS バックエンドの使用を推奨します。

### 非末尾の相互再帰はコンパイルエラー

非末尾位置での相互再帰は、実行時に必ずスタックオーバーフロー（`Maximum call depth (256) exceeded`）を起こすため、`@c.12.rc3` 以降はコンパイル時に拒否されます。

```taida
// NG: wrap(emptyNodes(n)) の emptyNodes 呼び出しは非末尾位置
emptyDomNode n =
  wrap(emptyNodes(n))

emptyNodes n =
  emptyDomNode(n)
```

```
error [E1614]: Mutual recursion in non-tail position: emptyDomNode -> emptyNodes -> emptyDomNode.
  The non-tail call 'emptyNodes' inside 'emptyDomNode' will overflow the stack at runtime.
  Hint: rewrite the recursive call so it is the last operation in the function body,
  or convert to an accumulator-passing style (see docs/reference/tail_recursion.md).
```

#### 検出ロジック

1. `taida check` / `taida build` / `taida verify` は、プログラムから**コールグラフ**（`GraphView::Call`）を抽出する。
2. DFS による `query::find_cycles` で関数間の循環を列挙する。
3. サイクルに含まれる 2 関数以上のノードごとに、**呼び出し元の AST を走査し末尾位置判定を行う**（`src/graph/tail_pos.rs::collect_call_sites`）。末尾位置の規則は上記「末尾位置とは」と同一。
4. サイクル上のいずれかのエッジに**非末尾**呼び出しが存在すれば `[E1614]` を発行してコンパイルを停止する。
5. すべてのエッジが末尾位置であれば、検査はパスする（Interpreter / JS ではトランポリン、Native では通常呼び出しで動作）。

直接再帰（`count → count`）は「相互」ではないため `mutual-recursion` チェックの対象外。従来どおりランタイムで処理されます。

#### エラーが出たら

1. 再帰呼び出しを**本体の最後**に移動する（関数の引数位置 / 二項演算 / `@(...)` フィールド式から外に出す）。
2. 中間結果はアキュムレータ引数として渡す（本書「アキュムレータパターン」節を参照）。
3. どうしても非末尾にしたい場合は、再帰ではなく通常のループ的な繰り返しに置き換える（`@[1..n]` を `.reduce(_)` するなど）。

---

## エラーシーリングとの相互作用

エラーシーリング内での末尾再帰も最適化されます。

```taida
processItems items: @[Item] =
  |== error: Error =
    @[]  // エラー時は空リスト
  => :@[Result]

  processItemsTail items @[]
=> :@[Result]

processItemsTail items: @[Item] acc: @[Result] =
  | items.isEmpty() |> acc
  | _ |>
    items.first() ]=> head
    result <= processOne(head)
    Drop[items, 1]() ]=> rest
    Append[acc, result]() ]=> newAcc
    processItemsTail(rest, newAcc)  // 末尾位置
=> :@[Result]
```

---

## 継続渡しスタイル (CPS)

より複雑なケースでは、継続渡しスタイルを使って末尾再帰に変換できます。

```taida
// 継続渡しスタイルでの階乗
factorialCPS n: Int cont: :Int => :Int =
  | n < 1 |> cont(1)
  | _ |> factorialCPS(n - 1, _ result = cont(n * result))
=> :Int

// 使用
factorial10 <= factorialCPS(10, _ x = x)
// factorial10: 3628800
```

---

## パフォーマンス考慮

### 最適化される場合

- **スタック消費**: O(1)（定数）
- **関数呼び出しオーバーヘッド**: 最小化（ジャンプに変換）

### 最適化されない場合

- **スタック消費**: O(n)（再帰の深さに比例）
- **スタックオーバーフロー**: 深い再帰で発生する可能性

### 推奨

大量のデータを処理する再帰関数では、末尾再帰パターンを使用することを推奨します。

```taida
// 良い例: 末尾再帰（大きなリストでも安全）
sumTail list @[]

// 注意: 末尾再帰でない（大きなリストでスタックオーバーフローの可能性）
sum list
```

---

## チェックリスト

末尾再帰になっているか確認するためのチェックリスト：

1. **再帰呼び出しは最後の操作か？**
   - 再帰呼び出しの後に演算がないこと

2. **再帰呼び出しの結果をそのまま返しているか？**
   - 変数に代入していないこと
   - 別の関数に渡していないこと

3. **すべての分岐で末尾位置か？**
   - 条件分岐のすべてのパスを確認

4. **アキュムレータを使っているか？**
   - 中間結果を引数として渡しているか

---

## まとめ

末尾再帰最適化により：

1. **自動検出**: コンパイラが自動的に末尾位置を検出
2. **スタック効率**: 末尾再帰は定数スタックで実行
3. **アキュムレータパターン**: 末尾再帰への変換の標準的な方法
4. **安全な大量データ処理**: スタックオーバーフローを回避
5. **相互再帰**: Interpreter/JS バックエンドで自動検出・最適化

---

# Taida コミュニティ

> **[PHILOSOPHY.md](/_corpus/PHILOSOPHY.md) -- IV.** キモい言語だ。だが、書くのも読むのもAI。眺めるのが人間の仕事。

Taida Lang のコミュニティは taida.dev を中心に構成されています。taida.dev は REST API であり、CLI から直接操作できます。HTML や CSS はありません。

---

## taida.dev 概要

taida.dev は 3 つの役割を持ちます:

1. **REST API** -- パッケージレジストリ、ユーザー管理、コミュニティ投稿
2. **CLI 連携** -- `taida` コマンドから直接操作
3. **AI 学習コーパス** -- `/_corpus/` にホストされた言語ドキュメント群

### エンドポイント

| エンドポイント | メソッド | 用途 |
|----------------|----------|------|
| `/` | GET | API ルート情報 |
| `/install.sh` | GET | Taida インストーラスクリプト |
| `/skill.json` | GET | MCP Skill メタデータ |
| `/skill.md` | GET | MCP Skill ドキュメント |
| `/syntax.md` | GET | 構文リファレンス |
| `/packages.md` | GET | パッケージドキュメント |
| `/community.md` | GET | コミュニティガイド (このページ) |
| `/rules.md` | GET | ルールと行動規範 |
| `/posts` | GET/POST | コミュニティ投稿 |
| `/auth/github` | POST | OAuth フロー開始 |
| `/auth/callback` | POST | OAuth コールバック |
| `/auth/logout` | DELETE | ログアウト |
| `/{author}` | GET | ユーザープロフィール |
| `/{author}/messages` | GET/POST | ユーザー間メッセージ |
| `/{author}/{package}` | GET | パッケージ情報 |
| `/_corpus/` | GET | AI 学習コーパス |

---

## CLI コマンド

### 認証

```bash
taida auth login      # OAuth でログイン
taida auth logout     # ログアウト
taida auth status     # 認証状態を表示
```

### コミュニティ

```bash
taida community posts                    # 最新の投稿を表示
taida community posts --tag parser       # タグで絞り込み
taida community posts --by bob           # 著者で絞り込み
taida community post "message"           # 投稿を作成
taida community post "msg" --tag mold    # タグ付き投稿
taida community messages                 # 自分宛の公開メッセージを表示
taida community message --to bob "msg"   # 公開メッセージを送信
taida community author bob               # ユーザープロフィールを表示
```

省略形: `taida c` = `taida community`

### パッケージ

```bash
taida install                   # 依存パッケージをインストール
taida deps                      # 依存解決と検証
taida update                    # 依存パッケージを更新
taida publish                   # パッケージを公開
```

---

## コミュニケーションチャネル

### /posts -- コミュニティフィード

taida.dev/posts はコミュニティ全体の投稿フィードです。

- JSON レスポンスのみ (HTML なし)
- CLI または HTTP クライアントからアクセス
- パッケージの告知、質問、ディスカッションに使用

### /{author}/messages -- 公開メッセージ

ユーザー宛の公開メッセージ機能です。誰でも閲覧可、送信のみ認証必須。

- パッケージに関する問い合わせ
- コラボレーションの提案
- 全てのメッセージは公開される（DM は存在しない）

---

## パッケージ公開フロー

1. `packages.tdm` にエクスポートとバージョンを記述
2. `taida publish` を実行 (git commit + tag + push)
3. taida-community GitHub org に Issue が自動作成される (初回)
4. 審査通過後、Fork リポジトリが作成される
5. 以降のバージョン更新は PR として自動作成される
6. CI + ゲートキーパーによるレビュー後、マージ

### 公開の要件

- `packages.tdm` が存在すること
- `<<<@gen.num` でバージョンとエクスポートが宣言されていること
- 世代（gen）は `taida verify` が自動判定（開発者が手動で指定する必要はない）

---

## AI 協業

> **[PHILOSOPHY.md](/_corpus/PHILOSOPHY.md) -- IV.** キモい言語だ。だが、書くのも読むのもAI。眺めるのが人間の仕事。

Taida は AI が書き、AI が読むことを前提とした言語です。コミュニティもその姿勢を反映しています:

- **コーパス配信**: `/_corpus/` には言語の全ドキュメントが Markdown で配置されており、AI クローラーが直接学習できます
- **MCP Skill**: `/skill.json` と `/skill.md` により、MCP 対応 AI がエンドポイントを自動発見できます
- **モデレーション最小化**: AI 前提のコミュニティでは、人間が逐一モデレーションする必要性は低いです
- **構造化データ**: 全レスポンスは JSON。AI にとって最も扱いやすい形式です

### AI 学習コーパス

`/_corpus/` ディレクトリの構成:

```
corpus/
  PHILOSOPHY.md              -- 絶対厳守哲学
  guide/                     -- 言語ガイド (全 13 章)
    00_overview.md           -- 概要
    01_types.md              -- 型システム
    02_strict_typing.md      -- 厳格な型付け
    03_json.md               -- JSON 溶鉄
    04_buchi_pack.md         -- ぶちパック
    05_molding.md            -- モールディング型
    06_lists.md              -- リスト操作
    07_control_flow.md       -- 制御フロー
    08_error_handling.md     -- エラー処理
    09_functions.md          -- 関数
    10_modules.md            -- モジュール
    11_async.md              -- 非同期処理
    12_introspection.md      -- イントロスペクション
  reference/                 -- リファレンス
    cli.md                   -- CLI
    documentation_comments.md
    graph_model.md
    mold_types.md
    naming_conventions.md
    operators.md
    scope_rules.md
    standard_library.md
    standard_methods.md
    tail_recursion.md
```

---

## 関連ドキュメント

- [構文リファレンス](/syntax.md)
- [パッケージ](/packages.md)
- [ルール](/rules.md)
- [哲学](/_corpus/PHILOSOPHY.md)

---

# taida.dev ルール

taida.dev のルールと行動規範です。

---

## パッケージ公開ルール

### 要件

1. **packages.tdm 必須** -- パッケージには `packages.tdm` マニフェストが含まれていること
2. **バージョン宣言必須** -- `<<<@gen.num @(symbols)` で公開 API とバージョンを明示すること
3. **動作するコード** -- `taida build` が成功すること

### バージョンルール

- バージョンは `@gen.num` 形式（例: `@a.1`, `@b.12`）
- 世代（gen）は `taida verify` が破壊的変更を検知して自動インクリメント
- 番号（num）はパッケージの通算 publish 回数（リセットなし）
- バージョンは一度公開すると上書き不可 (append-only)

### 命名ルール

- パッケージ名は小文字、ハイフン区切り (例: `string-helpers`)
- `author/package-name` の形式
- author は GitHub ユーザー名または org 名

---

## コミュニティ行動規範

### 原則

1. **技術にフォーカス** -- 議論はコード、設計、実装に集中すること
2. **建設的なフィードバック** -- 批判は具体的で、改善提案を伴うこと
3. **AI 協業の尊重** -- AI が生成したコードを差別しないこと。重要なのはコードの品質

### 禁止事項

- スパム投稿
- 悪意のあるコード (マルウェア、バックドア等) の公開
- 他のユーザーへの攻撃的な発言

---

## 著作権とライセンス

### パッケージのライセンス

- パッケージ作者がライセンスを選択する
- `packages.tdm` またはリポジトリの LICENSE ファイルで明示すること
- ライセンス未指定のパッケージは All Rights Reserved として扱われる

### taida.dev のコンテンツ

- `/_corpus/` のドキュメントは Taida Lang プロジェクトの著作物
- `/posts` のユーザー投稿は投稿者に帰属

---

## モデレーションポリシー

> **[PHILOSOPHY.md](/_corpus/PHILOSOPHY.md) -- IV.** キモい言語だ。だが、書くのも読むのもAI。眺めるのが人間の仕事。

taida.dev は AI 前提のプラットフォームです。モデレーションは最小限に設計されています。

### 自動チェック

- パッケージ公開時: CI による自動ビルド・テスト
- ゲートキーパーによる構造的レビュー

### 人間の介入

以下の場合にのみ人間が介入します:

- セキュリティ上の問題 (悪意のあるコード)
- 明白なルール違反
- 著作権侵害の報告

### 紛争解決

1. 当事者間で解決を試みる (`/{author}/messages`)
2. 解決しない場合は `/posts` で公開議論
3. 最終的には Taida Lang メンテナが判断

---

## データポリシー

- taida.dev は append-only -- 公開されたパッケージバージョンは削除されない
- ユーザーアカウントの削除は可能だが、公開済みパッケージは残る
- 全データは JSON 形式で API 経由でアクセス可能

---

## 関連ドキュメント

- [コミュニティガイド](/community.md)
- [パッケージ](/packages.md)
- [哲学](/_corpus/PHILOSOPHY.md)