多次元実験状態管理

多次元実験状態管理 は何をしますか？

長時間実行される多次元計算実験の「状態」に秩序をもたらす自己完結型のスキルです。 計算プラグインが計算を実行しますが、このスキルはその周辺の混乱（反復、スナップショット、 監査、ロールバック）を管理します。

このスキルは調整のみを行います。それ自体は結果を一切計算しません。 すべての数値はプラグインから得られます。

使用すべき場面

• ワークフローがパラメータ空間（次元の直積グリッド）上で多数のラウンドを実行し、各ラウンドの状態を記録する必要がある場合。
• 各ラウンドの前後で宣言された重要ファイルのスナップショットが必要な場合。
• すべてのラウンドに対して完全な監査証跡（パラメータ、ハッシュ、タイムスタンプ、ステータス）が必要な場合。
• ユーザーが任意の過去のラウンドに非破壊的にロールバックできる必要がある場合。
• 典型的な用途：縦断的研究、パラメータスキャン、外部ソルバー（Mathematica、GAP、SymPy、カスタムスクリプト）を呼び出す記号・数値スイープ。

必須ワークフロー

依存関係のブートストラップ（初回使用時）

初回実行前に、このスキルのランタイム依存関係を確認します。

• コア: 純粋な標準ライブラリのみ — インストール不要。
• オプション: PyYAML（設定がYAMLの場合のみ必要。JSON設定の場合は標準ライブラリのみで動作）。

PyYAML が不足しており、ユーザーの設定がYAMLの場合は、そのことを伝え、pip install pyyaml を実行するかどうかを確認してください。ユーザーの明示的な許可なしにグローバル環境にインストールしないでください。

ユーザーが多次元実験の実行、検査、または復元を要求した場合は、常に以下の手順を順に実行してください。

1. 設定の読み込み。実験設定 (config.example.yaml がテンプレート) を読み込みます。param_space.dimensions、critical_paths、および plugin.command が存在することを確認します。YAMLを使用する場合はPyYAMLがインストールされている必要があります。そうでない場合はJSONを使用します。
2. 空間の展開。すべての次元の直積を列挙します。実行前に、合計ラウンド数をユーザーに報告します。
3. ドライランを優先。python scripts/run.py dryrun --config <cfg> を実行し、ユーザーが副作用なしで完全な計画（すべてのパラメータの組み合わせ）を確認できるようにします。ユーザーの確認後にのみ実行に進みます。
4. スイープの実行。python scripts/run.py run --config <cfg> を実行します。各ラウンドについて、順に: 宣言された重要パスのスナップショットを事前に取得し、プラグインを呼び出し、事後にスナップショットを取得し、1つの監査レコードを追加します。
5. 失敗への正しい対応。ラウンドのプラグインが非ゼロで終了した場合、そのステータス（failed/error）を記録します。auto_rollback が有効な場合、最後の成功したラウンドの事後状態を作業ディレクトリに復元し、以降のラウンドがクリーンな状態で開始できるようにします。この復元自体も監査されます。単一の不良な組み合わせでスイープ全体を停止しないでください。
6. 要約。スイープ後、スキルは出力ディレクトリの下に results_summary.csv、results_summary.md、report_draft.md、および run_metadata.json を書き込みます。ユーザーにこれらのファイルを指示します。
7. リクエストに応じた復元。過去のラウンドを復元するには、python scripts/run.py rollback --config <cfg> --round <N> を実行します。デフォルトでは新しいディレクトリに復元します。ユーザーが明示的にライブ作業ディレクトリの上書きを希望する場合のみ --force を追加します。

ハード制約

• 自分で結果を計算しないこと。すべてのドメイン固有の計算はユーザープラグインに属します。スキルはそれを呼び出し、契約の結果を記録するだけです。
• 宣言された重要パスのみをスナップショットすること。作業ディレクトリ全体のコピーは決して行われません。コンテンツはハッシュでアドレス指定されて保存されるため、変更のないファイルは余分なコストがかかりません。
• ロールバックはデフォルトで非破壊的。--force がない限り、ライブ作業ディレクトリは変更されず、復元された状態は新しいディレクトリに配置されます。すべてのロールバック（手動または自動）は監査ログに書き込まれます。
• 決定性はユーザーの約束。スキルは オーケストレーション（同じパラメータ→同じ記録された計画、同じハッシュ）の再現性を保証します。非決定論的なプラグインを決定論的にすることはできません。「制限事項」を参照してください。

使用例

# 副作用なしで完全なラウンド計画を表示（常に最初にこれを行う）。
python scripts/run.py dryrun --config config.example.yaml

# スイープを実行。
python scripts/run.py run --config config.example.yaml

# 過去のラウンドを復元（--force がない限り新しいディレクトリに）。
python scripts/run.py rollback --config config.example.yaml --round 7

# 要約を再生成、または1つのラウンドの結果を検証。
python scripts/run.py summary --config config.example.yaml
python scripts/run.py verify --config config.example.yaml --round 7

プラグイン契約

マネージャーはラウンドごとに1つのシェルコマンドを起動します。

python your_plugin.py --params {PARAMS} --out {OUT}

• {PARAMS} - このラウンドのパラメータの組み合わせを含むJSONファイルへのパス。
• {OUT} - プラグインが結果のJSONを書き込まなければならないパス。
• 終了コード: 0 成功、1 アサーション失敗/チェック失敗、2 エラーまたはスキップ。

外部ソルバー（Mathematica、GAP、Python LMMスクリプト）は、この契約に従うようにラップされます。つまり、パラメータファイルを読み取り、結果ファイルを書き込みます。スキルは何が計算されるかに関心を持ちません。

障害処理

• プラグインが終了コード 1 で終了したラウンドは failed とマークされ、終了コード 2 は error とマークされます。どちらも監査ログに保持され、スイープは続行されます。
• config エラー（空間の欠落、不正なYAML、{OUT} の欠落）は、副作用の前に中断し、明確なメッセージを出力します（終了コード2）。
• 記録されていないラウンドや事後スナップショットがないラウンドへの rollback は、状態を破損させるのではなく、明確なエラーで失敗します。

制限事項

• 決定性はオーケストレーション層のみ。マネージャーはハッシュを記録し、同じパラメータに対して同じ計画を再生しますが、プラグインが決定論的であることを強制することはできません。プラグインがネットワークにアクセスしたり、ランダムシードを使用したり、壁時計を読み取ったりする場合、同じ入力でも異なる出力が生成される可能性があります。そのような非決定性は、プラグイン側で宣言してください。
• 重要パスは事前に宣言する必要があります。critical_paths にリストされていないファイルはスナップショットされず、したがってロールバックできません。
• Golden出力検証はv0.2。現在の検証器はプラグイン契約（終了コード0 + 結果ファイルの存在）のみをチェックします。既知の期待出力との比較は計画されていますが、まだ実装されていません。
• YAML設定にはPyYAMLが必要。JSON設定は標準ライブラリのみで動作します。