バインディング
バインディングはホスト環境にワークブック操作を公開し、計算はコアに残します。各言語で使いやすい型や操作方法に合わせて、C ABI を呼び出します。
用語: バインディング
ホスト側の型（Uint8Array / bytes / bytearray / バイト列のポインタと長さなど）をエンジン入力に、エンジン出力をホスト側の型に変換する薄い層です。バインディングは数式の意味論を実装せず、データの形を整え、リソースの寿命を管理します。
バインディングが行うのはホスト側の型と寿命の変換だけで、計算は常に C ABI の先にあるコアで行われます。
担当すること
- ホストのバッファを C ABI が受け取れるワークブックのバイト列に変換します。
- ワークブックハンドルとリソースの寿命（いつ解放するか）を管理します（WASM の
delete()、Python のコンテキストマネージャー、Native Node のdispose()と GC フォールバック、CLI のプロセス終了、MCP セッションの終了）。 - スプレッドシート値をホスト値に変換し、
ValueKindを保ちます（セルエラーが例外ではなく値であり続けるようにします）。 - 計算エラーと入出力エラーを公開します（スプレッドシートのエラー値を失わない形にします）。
- 各ホスト用の API を公開します。
ロケールの挙動はコアに置きます。C ABI と JS / Python バインディングは、完全な Excel プロファイル ID を渡してプロファイル選択、関数名の変換、数式のローカライズ、ロケール情報の取得を行います。人間向けの関数メタデータはホスト側の責務で、エンジンのカタログではロケールに依存しません。
担当しないこと
バインディングは次のことを しません。
- 数式の意味論を実装しません（パーサ / 評価器はコアが担当します）。
- ワークブックの読み込みを重複実装しません（OOXML / XLSB のリーダーはコアが担当します）。
- プロファイル固有の挙動を追加しません（プロファイルはワークブック状態であり、C ABI 経由で設定されます）。
- 独自の再計算が必要なセルの集合・依存関係グラフ・再計算スケジューラを導入しません（すべてコアが担当します）。
バインディングで Excel を再実装しないこと
関数結果の特別扱いや、コアと異なる値変換が必要なら、コア側を修正します。評価器にケースを追加し、Oracle ゴールデンデータを追加すれば、すべてのバインディングが同じ挙動を取り込めます。バインディングごとに修正するとずれが広がります。
npm の WASM バインディングは、単一スレッドの @libraz/formulon 入口と pthread の @libraz/formulon/threads 入口を公開します。どちらも C ABI、ワークブック API、TypeScript 宣言を共有し、ワーカーを使う並列再計算に対応するのは後者だけです。
実例
| バインディング | ホスト側で扱う型・操作 | 触らない領域 |
|---|---|---|
| WASM | Uint8Array、ステータス付きの戻り値、ValueKind 列挙型、非同期モジュールファクトリ、直列版／pthread 版の入口選択 | 関数の意味論・ファイルの読み込み・計算グラフ |
| Native Node | N-API Buffer、同期 API、dispose() / memoryUsage() | 関数の意味論・ファイルの読み込み・計算グラフ |
| Python | bytes、コンテキストマネージャー、FormulonError、Value.to_python() | 関数の意味論・ファイルの読み込み・計算グラフ |
| CLI | argv、stdin / stdout / stderr、終了コード | 関数の意味論・ファイルの読み込み・計算グラフ |
| MCP | JSON 入出力、セッションマップ、許可リストに基づく呼び出し | 関数の意味論・ファイルの読み込み・計算グラフ |