NEPLg2.1 標準ライブラリ設計

1.1 値中心・式指向

• if / match / block が値を返す言語仕様に合わせ、ライブラリ API も「値を返す関数」を標準形とする。
• パイプ |> で自然に読めるよう、変換対象は原則第 1 引数に置く。

1.2 安全 API 優先

• 公開 API の戻り値は Option / Result / Outcome を用途に応じて使い分ける。
• _raw / _safe のような実装都合の命名は公開面から排除する。
• 低レベル API は内部実装または隔離層に閉じ込め、利用者に直接露出しない。

1.3 bare 名の統一

• API 名には prefix/suffix を付けない（get_opt・get_safe・read_i32 のような命名は採用しない）。
• read / write / flush / close / get / push / pop のような bare 名を正とする。
• 型ごとの差異は引数型・戻り値型・trait 制約・オーバーロード解決で表し、命名規則で補わない。

1.4 能力は trait で表す

• Copy / Clone / Eq / Ord / Hash / Stringify などの能力は trait で表す。
• どの型がどの能力を持つかは .nepl ソース上の宣言を唯一の根拠とし、compiler 内部に型ごとの固定表を持たない。

1.5 層構造と依存方向

• core → alloc → runtimes → std → features の順に、動作条件は増え、互換性は狭くなる。
• より下位互換な層へ置ける機能を、より上位依存な層へ不用意に押し上げない。

2.1 core

• 純粋で target 非依存な基本機能だけを置く。
• heap を必要としないものを置く。
• OS / device / syscall / allocator 詳細に依存しない。
• 基本型・演算・基本 trait・Result / Option などの最小集合を担当する。
• math.nepl のように、ほぼすべての runtime で共通に提供されるべき計算ライブラリはここに置く。
• 乱数（rand）は非決定的でありプラットフォーム依存のため core には置かない。features/ に配置する。

2.2 alloc

• core の上で、heap 依存だが target 非依存の汎用機能を提供する。
• allocator / 領域管理 / 診断補助 / encoding / hash をここへ置く。
• MemPtr .T / RegionToken は compiler/runtime 境界モジュールとして alloc 配下に置くが、safe user code からは抽象型（OwnedBuf .T, Slice .T など）だけが見える。

2.3 runtimes

• target ごとの syscall / ABI / descriptor 差分を吸収する adapter 層。
• 利用者は原則としてこれらを直接使わず、std や std/streamio を通して利用する。
• wasm / wasi / llvm の差分もここに含めて扱う。

2.4 std

• 各個別 target を束ね、device / OS 依存 API を標準的に扱えるようにする facade 層。
• runtimes / std/streamio を適切に包み、利用者向けに安定した標準 API 面を提供する。
• std は stdlib 全体そのものではなく、stdlib の中で target 依存 API を標準化して見せる役割だけを担う。

2.5 features

• 外部 API / FFI / デバイス接続などの公式追加機能群。
• GUI / HTTP / TUI / 音声再生など、外界と接続する機能を置く。
• 一方で、regex や audio buffer など純計算・データ処理は core または alloc に置く。

alloc と features の境界判断基準:

判断に迷う場合の原則: 「入出力なしに動作するか」が alloc、「外界と通信しなければ動作しないか」が features。

2.6 kp（暫定・競技プログラミング層）

• 競技プログラミング向けの先行ライブラリを置く暫定層。
• 成熟し責務が一般化できた機能は std / alloc/collections / alloc/text 等へ昇格させる。

2.7 nm・neplg2（独立ライブラリ層）

• nm: 拡張 markdown・doc comment・HTML 変換など周辺ツールチェーン用。
• neplg2: セルフホスト compiler 用ライブラリ。

4.1 alloc/collections

• Vec / Map / Set / Queue / Stack など一般用途のデータ構造。
• device や OS に依存しないため std には入れない。
• allocator と trait 能力に基づき、move / effect / memory 規則と整合する API を提供する。

4.2 alloc/text

• str / String / Unicode / format / parse / 文字列表現変換を担当する。
• bool/i32/i64/i128/... と文字列の相互変換はここに置く。
• 標準入出力そのものは text の責務ではなく、std/stdio や std/streamio が利用する側。

4.3 alloc/io

• Reader / Writer / Seekable / Buffered など I/O の低水準抽象。
• syscall や descriptor などの具体実装は持たない。
• 「何が読めるか / 書けるか」の能力を trait として表現する。

4.4 std/streamio

• alloc/io の抽象を束ね、read / write / flush / close の高水準 API を提供する。
• stdio・fs・将来の socket / timer / process event / UI event などを、同じ stream 能力モデルで扱えるようにする。

5.1 使い分け基準

• Option: 値が存在しないことが想定内で、診断や失敗理由を伴わない分岐。
• Result: 単純な成功/失敗制御で十分。診断は不要か呼び出し側が不要と判断できる。
• Outcome: warning/info/log を失わずに返したい API。compiler・parser・json 変換など。