tomoaki/hakorune
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
dda65b94b7c45d97e2317a5e116b4b288214fb52
hakorune/docs/development/philosophy/box-first-manifesto.md
Moe Charm de99b40bee Phase 12 TypeBox統合ABI設計完了: C ABI + Nyash ABI革命的統合 
主な成果:
- TypeBox（型情報をBoxとして扱う）による統合ABI設計
- C ABI + Nyash ABIの完全統合仕様書作成
- 3大AI専門家（Gemini/Codex/ChatGPT5）による検証済み
- ChatGPT5の10個の安全性改善提案を反映
- README.mdのドキュメント更新（全起点から到達可能）

MapBox拡張:
- string型キーサポート（従来のi64に加えて）
- remove/clear/getOr/keysStr/valuesStr/toJson実装
- keys()/values()のランタイムシムサポート（TypeBox待ち）

その他の改善:
- Phase 11.9（文法統一化）ドキュメント追加
- Phase 16（FoldLang）ドキュメント追加
- 非同期タイムアウトテスト追加
- 各種ビルド警告（未使用import等）は次のリファクタリングで対応予定

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-09-02 09:26:09 +09:00

3.4 KiB
Raw Blame History

🧱 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の管理

この順序と原則で、壊さず、早く、何度でもやり直せる。