fable-eco

Fable Eco

get-fable 向けにキュレーションされた機能の配布と実行制御を行うサブシステムです。

目的

断片化した開発者ツールのインストールと、規律あるエージェント機能の有効化とのギャップを埋めます。fable-eco は「多くをインストールし、少数だけを有効化する」というアーキテクチャ原則を徹底します。コードグラフインデクサー、レビュー支援ツール、ブラウザーツール、テストランナーなど、キュレーションされた AI エンジニアリング機能を、変更不能な固定バージョンでトランザクション的にプロビジョニングします。また、明示的な最小権限ポリシーのもとで、ルーティングされた get-fable タスク向けにタスク範囲を限定した実行契約をコンパイルします。

使用する場面

• 副作用を伴わずに、ローカルマシンのランタイム、コンパイラー、パッケージマネージャー、コーディングホストの設定を検出するとき。
• キュレーションされたエコシステム機能の解決、計画、インストール、更新、ロールバックを行うとき。
• .fable/eco.json でプロジェクトの機能バインディングを管理し、必要な機能、プロファイル、最小契約バージョンを宣言するとき。
• 変更を加えない doctor チェックで、エコシステムの整合性、ロックファイル、ジャーナル、壊れたシンボリックリンクを診断または修復するとき。
• ライフサイクルのルーティング判断に基づいて、エージェントタスク向けの決定論的な機能実行契約をコンパイルするとき。

使用しない場面

• 上位レベルのライフサイクルタスクのルーティングや状態管理（get-fable を使用してください）。
• 外部機能を必要としない、内部で完結するコードの作成（fable-execute を使用してください）。
• テストファーストのレッド・グリーン・リファクタリングループの実行（fable-tdd を使用してください）。
• 繰り返し発生する実行失敗や壊れたテストハーネスの診断（fable-recover を使用してください）。

入力

• routing_decision：選択されたスキル、タスクの形状、意図を含む fable_core::RoutingDecision からの構造化ルーティング判断です。
• project_binding：.fable/eco.json で指定する任意のワークスペースバインディングです。有効なプロファイル、固定された機能、ポリシーのオーバーライドを宣言します。
• catalog_layers：公式配布、チームリポジトリ、ローカルディレクトリにまたがる、複数レイヤーの機能マニフェストです。
• machine_facts：検出されたシステムランタイム、OS プラットフォーム、パッケージマネージャー、ホスト設定の状態です。

期待される出力

• install_plan：ロールバック分類を含む、インストール操作のトポロジカル有向非巡回グラフ（DAG）です。
• lockfile：SHA-256 ダイジェストと来歴メタデータを含む、暗号学的ハッシュ付きの .fable/eco.lock です。
• execution_contract：認可されたツール、環境変数、実行制限のみを公開する、タスク範囲限定のマニフェストです。
• capability_receipt：ホスト設定の編集内容、インストールされたバージョン、有効な所有権を記録した構造化レコードです。

手順

1. 検出：変更を加えないプローブを実行し、マシンの情報、インストール済みランタイム、既存の機能バージョン、ホスト設定ファイルを検出します。
2. カタログの読み込みと検証：公式、チーム、ローカルの各カタログレイヤーから機能とプロファイルのマニフェストを取り込み、セマンティックなスキーマ検証を適用します。
3. 決定論的な解決：依存関係と競合のグラフを構築し、推移的な機能要件を解決して、互換性の問題や不足している前提条件を検出します。
4. 計画の生成：変更を適用する前に、すべてのファイルコピー、ダウンロードの展開、環境更新、ヘルスチェックを示す実行計画を作成します。
5. トランザクションによるプロビジョニング：ステージングサンドボックス内で、先行書き込みジャーナル（.fable/eco-journal.json）を使用して操作を実行し、チェックサムとアトミックなコミットを検証します。
6. 健全性の検証：インストールされた各機能に対してインストール後のヘルスプローブを実行し、運用準備が整っていることを確認します。
7. レシートとロックの確定：.fable/eco.lock を更新し、ホスト設定の所有権レシートを書き込みます。
8. 契約のコンパイル：ルーティングされたタスクでは、ルーティング判断とポリシールールに照らしてインストール済み機能を絞り込み、実行契約をコンパイルします。

決定ルール

• 変更前に計画する：実行前に検証済みの計画を立てずに、ファイルの変更、ダウンロード、設定の編集を行ってはなりません。
• 安定版チャンネルでの不変性：安定版の機能は、不変の Git コミットまたは暗号学的にハッシュ化されたリリースアーカイブに解決される必要があります（main または HEAD は拒否します）。
• 権限レイヤーの単調性：プロジェクトポリシーで機能を制限することはできますが、マシン全体に適用される拒否ルールを上書きすることはできません。
• 最小権限での機能有効化：現在のライフサイクルフェーズとタスクの形状に必要な特定の機能のみを公開します。
• 失敗時のロールバック：プロビジョニング中にヘルスチェックまたはインストール手順が失敗した場合、トランザクションジャーナルを使用して自動ロールバックを実行します。

ツールポリシー

• 高性能な Rust クレート fable-eco を介して、検出と解決をネイティブに実行します。
• 厳格なパストラバーサル防止（.. によるエスケープを禁止）のもとで、アトミックなファイルシステムのステージングとコピー操作を使用します。
• システムファイルや環境の状態を変更せずに、読み取り専用のプローブを実行します。
• 受信するすべてのマニフェストを、schemas/eco/ 内の正規の JSON Schema 定義に照らして検証します。

エビデンス要件

• 検出結果には、構造化されたマシン情報（OS、アーキテクチャ、ランタイム、パッケージマネージャー、ホスト）を含める必要があります。
• インストール計画には、明示的な id、kind、depends_on、rollback_class を含むすべての操作を記載する必要があります。
• 実行コントラクトには、正確な機能 ID、許可されるツール、ネットワークポリシー、適用グレードを指定する必要があります。
• 完了した操作では、ロックファイルを永続化する前に、インストール後のヘルスチェックに合格したエビデンスが必要です。

失敗処理

• トランザクションのステージングが失敗した場合、または予期しないクラッシュが発生した場合は、ジャーナルの状態（Clean、RecoverableRollback、RecoverableCommit、Corrupted）を分類して復旧します。
• 必須のランタイムまたは依存関係をホストマシンで利用できない場合は、機能を劣化または互換性なしとしてマークし、修正手順を報告します。
• 機能要件が競合する場合は、解決を停止し、競合する機能チェーンを出力します。

完了条件

• 選択したすべての機能が、未処理のエラーなく正常にステージング、検証、コミットされていること。
• 対象ホストの設定ファイルが、検証済みの所有者タグを付けて正しくパッチされていること。
• インストール後のヘルスチェックが、終了コード 0 と有効な出力で合格すること。
• 決定性のある .fable/eco.lock が生成され、ワークスペースの状態と同期されていること。