53 lines
3.4 KiB
Markdown
53 lines
3.4 KiB
Markdown
|
# 🧱 Nyash開発哲学: 「箱を作って下に積む」
|
|||
|
|
|
|||
|
|
作成日: 2025-09-02
|
|||
|
|
ステータス: 運用指針（安定）
|
|||
|
|
|
|||
|
|
## 目的
|
|||
|
|
機能を最短で安全に通しつつ、後戻り可能性と可観測性を最大化するための実践原則。Nyashは「Everything is Box」。開発も同様に、まず箱（境界・足場）を作り、下に積んでいく。
|
|||
|
|
|
|||
|
|
## 中核原則（Box-First）
|
|||
|
|
- 境界一本化: 変換・正規化は境界箱（Boundary/Registry/Semantics）1箇所に集約。
|
|||
|
|
- 下に積む: 上位機能の前に、受け皿となる下位の箱（ABI/Registry/Hostcall/Semantics）を先に用意。
|
|||
|
|
- 小さい箱: API面は最小・明確に。用途が広がれば能力(capability)を後置きで追加。
|
|||
|
|
- いつでも戻せる: env/feature/Box設定で切替可能。フォールバック経路を常設し破壊的変更を避ける。
|
|||
|
|
- 可観測性先行: JSON/DOT/タグ付きログなどの観測を同時に追加し、振る舞いを記録・比較可能にする。
|
|||
|
|
- 明示性優先: 暗黙の魔法を排除（by-id固定、explicit override/from、strictトグル）。
|
|||
|
|
|
|||
|
|
## 積む順序（5ステップ）
|
|||
|
|
1) 境界箱を置く: Semantics/ABI/HandleRegistry/Hostcall/Config のいずれかに着地点を用意。
|
|||
|
|
2) no-op足場: 失敗しない実装（no-op/同期get/仮戻り値0）でまず通す。
|
|||
|
|
3) 小さく通す: ゴールデン3件（成功/失敗/境界）で tri-backend を最小通過。
|
|||
|
|
4) 観測を入れる: Result行・stats.jsonl・CFG DOT・TRACE env を追加（デフォルト静か、必要時のみON）。
|
|||
|
|
5) 厳密化: 型/戻り/エラーを段階で厳密化、フォールバックを削り strict を既定へ寄せる。
|
|||
|
|
|
|||
|
|
## 具体適用（現行ライン）
|
|||
|
|
- Semantics層: 加算/比較/文字列化の正規化をVM/JIT/Interpreterで共有。
|
|||
|
|
- 単一出口: returnは必ずretブロックに集約。PHIはローカルへ実体化しReturnはlocal load。
|
|||
|
|
- Handle-First + by-id: PluginInvokeは常に a0=handle / method_id 固定。TLVでプリミティブ化。
|
|||
|
|
- Await/Future: まず同期解決で安全着地→Cancellation/Timeout/Err統一を段階導入。
|
|||
|
|
- Safepoint: checkpointはglobal_hooks経由でGC/スケジューラ連携（no-op→実装）。
|
|||
|
|
|
|||
|
|
## アンチパターン（避けること）
|
|||
|
|
- バックエンド横串: VM/JIT/LLVMが互いを直接知る配線。
|
|||
|
|
- 境界分散: 値変換やポリシーが複数箇所に散らばる。
|
|||
|
|
- 先に最適化: 観測や足場なしで高速化のみを入れる。
|
|||
|
|
- 暗黙フォールバック: 失敗を隠して通す（原因が観測できない）。
|
|||
|
|
- 仕様の局所実装: 便宜的な特例 if/else を増やす（規約化せずに拡散）。
|
|||
|
|
|
|||
|
|
## 成功判定（DoD）
|
|||
|
|
- tri-backend一致: Script/VM/JIT（必要に応じAOT）でResult系の一致。
|
|||
|
|
- 観測可: stats/TRACE/DOTが残り、回帰比較が可能。
|
|||
|
|
- リバータブル: env/feature/Box設定で旧経路へ即時切替可能。
|
|||
|
|
- 文書化: 追加箱/APIの概要と使用例をdocsへ追補（最小）。
|
|||
|
|
|
|||
|
|
## 付録: 代表Box一覧（足場）
|
|||
|
|
- SemanticsBox: coerce/compare/arith/concat の正規化
|
|||
|
|
- HandleRegistry: ハンドル↔実体の一元管理
|
|||
|
|
- InvokeHost: by-id呼び出し（固定長/可変長、TLV）
|
|||
|
|
- JitConfigBox: 環境設定の集約窓口
|
|||
|
|
- ObservabilityBox: stats.jsonl/CFG DOT/traceの管理
|
|||
|
|
|
|||
|
|
この順序と原則で、壊さず、早く、何度でもやり直せる。
|
|||
|
|
|