run-cherries-experiments

Cherries の実験を実行する

Cherries の実験や保存済みレコードには、このスキルを使用します。コマンドを利用する前に、Cherries のチェックアウトにある docs/README.md を読んでください。インストール済みバージョンには、ドキュメントに記載された機能がすべて含まれているとは限りません。

リポジトリの境界

たとえば、独立した実験用スーパープロジェクトで作業してください。

phace-exp/
  cherries.toml  pyproject.toml  uv.lock
  libs/apple/  libs/melon/       # Git submodules
  exp/YYYY/mm/dd/study/
    src/  configs/  fixtures/  docs/  analysis/

作成した研究ソース、設定、レポート、厳選したフィクスチャ、サブモジュールの gitlink は Git で管理します。LFS は、厳選されレビュー可能なアセットにのみ使用します。生成された入力、出力、ログ、メッシュ、チェックポイントは Cherries ストアに保存し、Apple や Melon のリポジトリには置かず、広範な LFS パターンにも含めないでください。

/tmp ではなく、設定済みのローカルデータボリュームを使用してください。

# cherries.local.toml (normally Git ignored)
[collection]
storage = "/data/cherries/phace-exp"

新しいコレクションは明示的に初期化してください。

cherries --project-dir . --storage /data/cherries/phace-exp init \
  --collection-id "<collection-uuid>"

プロジェクトの設定を読み、ローカルストレージとアーカイブ先を確認してください。マシン固有のパスや公開済みの実験 Git ref を前提にしないでください。ローカルストレージを上書きするには --storage を使用します。--remote main によるリモートアーカイブ／同期には、archive.main.path が明示的に設定されている必要があります。現在、ローカルレコーダーが対応しているのは Linux と Python 3.12 以降です。

封印される日次実験

通常の Python または uv run python を実行します。ブートストラップ、再起動、デーモン、手動保存、自動 Git コミットは行われません。

from liblaf import cherries


class Config(cherries.BaseConfig):
    mesh: str = "sha256:<full-digest>"  # raw source declaration
    steps: int = 200


def main(cfg: Config) -> None:
    mesh = cherries.input(cfg.mesh, name="mesh.vtu")
    result = cherries.output("solution.txt")
    cherries.temp("solver-cache")
    result.write_text(f"{mesh.name}: {cfg.steps}\n")
    cherries.log_metric("steps", cfg.steps)


if __name__ == "__main__":
    cherries.main(main)

モジュールスコープでは副作用を発生させないでください。main の外で、データの読み込み、ソルバー／GPU コンテキストのインスタンス化、実験状態のランダム生成、実行中の入力の解析、Cherries のアセット、メトリック、パラメーター、ステップのヘルパーの呼び出しを行わないでください。設定のデフォルト値は生の文字列またはパスにしてください。ヘルパーの使用にはアクティブな実行が必要です。通常の Python として元の引数を保持して呼び出してください。

uv run python exp/2026/10/05/mouthopen/src/10-run.py --steps 200

BaseConfig はケバブケースのフラグを受け付けます。ヘルプの表示と設定の無効判定は、記録の開始前に終了します。CHERRIES_COMET=1 を設定するのは、Comet の可観測性を意図して利用する場合だけにしてください。デフォルトでは無効であり、それ以外の場合は SDK が読み込まれません。

main が戻る前に、非同期のネイティブ操作を完了し、作業フォルダーへの書き込みをすべて終えてください。Cherries は、デーモンスレッドを含む、新たに作成された Python 管理下のスレッドの終了を待ちますが、外部のネイティブスレッドに対しては終了待機も追跡もできません。ネイティブの後処理スレッドは封印を妨げません。ネイティブライブラリや GPU の処理は、明示的に同期してください。

input() は、ローカルパス、完全な sha256: ファイル ID、sha256-tree: バンドル ID、または run:<record-id>/<logical-path> を受け付けます。独立したコピーを検証して inputs/ にステージングし、選択した生成元を記録してから、系譜を登録します。ダイジェストの来歴を制限するには source_run=<record-id> を渡してください。output() は outputs/ 以下の必須パスを宣言します。log_output() は既存の外部出力をそこにコピーします。temp() は破棄可能な scratch/ のパスを返します。

main の実行中にステージング済みの入力を変更しないでください。変更が検出された場合、不完全な作業が残り、封印せずにエラーが発生します。有限でない科学計算のメトリック値は、確認用に NaN、Infinity、-Infinity の文字列として保持されます。

Cherries は、エントリーソース、HEAD、バイナリ差分、選択された未追跡ソース、実行時の証拠、パラメーター、入力バインディング、ログ、メトリック、宣言された出力を取得します。取得は通常のインポート後、main の境界で行われます。そのため、レコードのソースの安定性は記録しても、replay_verified を主張しないでください。参照される Git ベースは利用可能な状態に保ってください。実行が成功すると、正規化された SHA-256 オブジェクトと小さな不変レコードが封印されます。宣言された出力が見つからない場合や記録エラーが発生した場合、作業ステージは保持されます。実行に失敗すると診断情報が記録され、依存関係や保持指定のない未封印のローカルペイロードに限り、破棄されることがあります。

実験記録の継続的な更新

実験セッション中、実験の記録を自動的に維持します。これは継続的なワークフローの依頼です。「ドキュメントを書いて」という別の指示を待たないでください。セッションの開始時に、作業を提案する前に、研究の RUN.md と関連する実行メモを読んでください。決定事項、うまくいかなかった方法、不確実な点、および現在の計画に至った理由を引き継いでください。

実行を確定する前に、その問い、プロトコル、議論を研究の RUN.md に記録しておいてください。保存済みの実行については、exp/YYYY/mm/dd/study/docs/runs/<RUN-ID>.md に編集可能な Markdown ドキュメントを 1 つ維持してください。phace-exp では、templates/run-memory.md をもとに作成してください。テンプレートのプロンプトは実際の証拠に置き換えてください。正確な実行 ID、コマンド／構成、入力と出力の参照先、観察事項、現在の解釈、決定事項、未解決の問い、次のステップ、および重要な変更の簡潔な日付入り履歴を記載してください。該当するセクションだけを使ってください。

実質的な議論、新しい結果、決定、訂正、または方針変更の後、さらに最終回答やセッションの引き継ぎの前に、メモを更新してください。測定された事実は保持してください。結論が変わった場合は、以前の解釈が置き換えられたことを説明して明記してください。チャットをそのままコピーするのではなく、役立つ推論を要約してください。実行に失敗し、保存済みの実行がない場合は、診断情報を研究メモに記録してください。

変更したドキュメントの各バージョンを、保存済みの実行にローカルで添付してください。

uv run cherries note <RUN-ID> --file exp/YYYY/mm/dd/study/docs/runs/<RUN-ID>.md
uv run cherries --json show <RUN-ID>

Markdown 全文は追記専用の注釈として保持されます。show には projection.notes が含まれます。value が # Run memory: で始まる最新のエントリが保存済みメモで、それ以前のバージョンも引き続き利用できます。ローカルのドキュメントがなくなった場合は、そこから復元してください。並行するセッションによって異なるバージョンが残っている場合は、両方を読んで、証拠と未解決の問いを統合した新しい改訂版を作成してください。note を呼び出す前に最後に保存されたメモと比較し、ドキュメントに変更がなければ呼び出しを省略してください。CLI は呼び出しのたびに改訂版を追記し、重複を抑止しません。

このような通常のメモは、依存する記録も保持ロックも作成しないため、メモを取っても手動で破棄できる状態は維持されます。元の確定済み RUN.md とレシートはそのまま保持してください。明示的な比較、図、または会議の成果物には、以下の分析ワークフローを使用し、元となる実行を保護してください。ドキュメントを維持する権限があるからといって、Git コミットやリモート公開が自動的に行われると推測しないでください。

レコードの検査とアーカイブ

グローバルオプションはコマンドの前に指定します。出力をスクリプトの入力として使う場合は、 --json を使用してください。

cherries --storage /data/cherries/phace-exp --json browse --quality unreviewed
cherries --storage /data/cherries/phace-exp browse --failed
cherries --storage /data/cherries/phace-exp browse --label mouthopen
cherries --storage /data/cherries/phace-exp browse --asset sha256:<digest>
cherries --storage /data/cherries/phace-exp browse --search mouthopen
cherries --storage /data/cherries/phace-exp browse --used-in weekly/2026-10-05
cherries --storage /data/cherries/phace-exp show <record-id>
cherries --storage /data/cherries/phace-exp read <record-id> RUN.md
cherries --storage /data/cherries/phace-exp path <record-id> outputs/solution.txt
cherries --storage /data/cherries/phace-exp --json path <record-id> legacy/data/example.vtu
cherries --storage /data/cherries/phace-exp path --release <lease-id>
cherries --storage /data/cherries/phace-exp archive <record-id> --remote /archive/cherries --evict
cherries --storage /data/cherries/phace-exp restore <record-id> --remote /archive/cherries

browse は最新のレビュー品質を使用します。--used-in を指定すると、名前を指定した分析と、その直接のソース親が含まれます。--search は名前、種類、旧来の由来、移行済みの旧来のソースに一致します。 path は、宣言されたファイルまたはディレクトリと、必要な .series の付属ファイルを実体化し、永続的な読み取りリースを作成します。sha256-tree は選択したレコードで宣言されている必要があります。宣言された空のディレクトリを含め、完全なトポロジーを復元します。restore は一時的な復元ホールド中にレコード全体を検証し、その後、ローカルに復元された常駐ビューを作成します。

付属ファイルを含むバンドルのプライマリパスは、付属ファイルを隣に配置した状態でファイルを返します。 ツリー入力では、宣言された空のフォルダーも含め、記録されたステージング済みパスが使用されます。

JSON の path 結果にはリース ID が含まれます。検査が終了したら、その ID を指定して解放してください。これは legacy/data/example.vtu のような移行済みの生パスにも同様に適用されます。

Python で後続の作業を行う場合は、クローズ可能なリーダーホールドを使用してください。

with cherries.open_run("<record-id>") as saved:
    result = saved.path("outputs/solution.txt")

workspace=Path("analysis/compare") を渡すと、ソースが既存の分析ワークスペースホールドに関連付けられます。どちらの方法でも、アクセサーをクローズするか、コンテキストマネージャーを使用してください。一時的なリーダーホールドが、ワークスペースがクローズされた場合でも進行中の読み取りを保護します。ワークスペース自身のホールドは、cherries analysis close を実行するまで維持されます。

cherries rerun <id> --prepare-only --workspace replay/<id> は、保存された Git HEAD、バイナリ差分、選択された未追跡ソース、取得されたエントリーポイント、入力マッピングから、新しいワークスペースを再構築します。ローカルに取得済みの Git ベースと、ソースが安定した実験レシートが必要です。--prepare-only を指定しない場合は、そのワークスペースを uv run で実行します（uv.lock が存在する場合は --locked を付けます）。新しい試行が作成されます。科学的なチェックで確認されるまで、replay_verified は false のままです。準備済みのワークスペースを閉じるには、cherries rerun --close <workspace> を実行してください。

アーカイブはフォアグラウンドでのみ実行されます。各ローカルオブジェクトを検証し、完全なクロージャーを公開して、読み戻したバイト列を検証した後、最後にリモートの commit.json を公開します。ローカルディレクトリのリモートには、アトミックなファイルシステム境界があります。汎用の rclone リモートには --coordinated が必要です。これは、コレクションのパブリッシャーを外部で実際に直列化することを宣言します。マーカーファイルによるロックや、古い所有者のロックの奪取は使用しないでください。追記専用のメタデータを転送するには、cherries sync --remote REMOTE [--coordinated] を使用します。Sync は SHA に紐付けられた制御メタデータ、イベント、ペイロードを含まないチェックポイントマーカーを最後に書き込みます。チェックポイントのインポートでは、選択したレシートのメタデータと、必要な祖先グラフのみがマージされます。リモートのペイロードが利用可能であることを証明するものではありません。選択した復元とインポートでは、その系譜のイベントのみがインストールされ、すでにローカルにある祖先への更新も含まれます。インストール前に、チェックポイントに紐付けられたすべてのイベント証明が引き続き検証されます。グローバルなメタデータ同期は、コレクション全体を対象とする範囲を維持します。browse --failed の失敗した試行はローカル診断情報であり、公開もインポートもされません。

--evict は、検証後に、適格な実体化済みローカルビューのみを解放します。他の常駐レコード、進行中の作業、リーダー／分析ホールド、--keep-local が解放を妨げます。--important はローカルビューではなく、論理的な保持を保護します。共有ツリーオブジェクトは、いずれかの常駐ローカルレコードがそのツリーを必要とする限り、メンバー全体のクロージャーを保持します。

後続のソースローカル注釈に失敗した場合でも、アーカイブはコミット済みになることがあります。この場合、archive は検証済みの場所と warnings エントリーを返し、終了ステータスは成功になります。--evict はそのレコードをスキップし、eviction_skipped を報告します。返されたコミット証拠とローカルバイト列を保持してください。リモート公開エラーが発生した場合は、コマンドは失敗します。ローカル注釈の失敗から公開結果を推測してはいけません。

レビューと軽量な分析

実行が成功すると、unreviewed で開始されます。レビューは主観的なものであり、実行や科学的な検証とは別です。ラベルとレビューはメタデータイベントを追記しますが、不変のレシートや CAS オブジェクトは変更しません。また、bad によって成功した実行が自動的に破棄されることはありません。

cherries review <id> --quality good --note "Useful comparison"
cherries label add <id> mouthopen promising
cherries label remove <id> promising
cherries mark <id> --important
cherries mark <id> --keep-local
cherries note <id> --file findings.md
cherries link <id> --git <commit>
cherries analysis new analysis/compare --source <id>
cherries analysis save analysis/compare --output out/figure.png --used-in weekly/2026-10-05
cherries analysis close analysis/compare

フォローアップ作業には、最新の開発環境、ParaView、またはその他の対話型ツールを使用してください。選択したソースを分析に追加します。分析を開いている間は、そのワークスペースにソースが保持されます。RUN.md、analysis.json、src/、および明示的に指定した out/... の出力のみを保存してください。封印された記録では、RUN.md と analysis.json は名前が維持され、ワークスペースの src/... は source/... として保存され、選択した out/... ファイルは outputs/... として保存されます。既存の分析記録を含め、取得にはこれらの保存済みパスを使用してください。たとえば、cherries read <analysis-id> source/compare.py や cherries path <analysis-id> outputs/figure.png のようにします。 必要に応じて、ParaView の設定と表示中のアセットへの参照を保存してください。保存済みの分析は軽量な依存記録であり、すべてのソースを保護しますが、厳密なソルバーの再実行を保証するものではありません。メモと Git リンクは追記専用のイベントであり、他のメタデータと同期されます。

レガシーのインポートは、来歴が不完全な追加専用の不変レコードです。レガシーのソース名は検索可能ですが、ソースが安定した実験でも、再実行可能な記録でも、保守の許可でもありません。

ローカルの単一マシンで保守を行うには、一時停止レシートと保存済みプランが必要です。

cherries maintenance pause
cherries discard <id> --plan
cherries discard --apply <plan-path>
cherries prune --plan
cherries prune --apply <plan-path>
cherries maintenance resume <pause-token>

一時停止により参照の作成が凍結され、アクティブまたは保留中の作業、レガシーの来歴、あるいは外部参加者がある場合はフェイルクローズします。プランはローカルの一時停止レシートとインベントリに紐づけられます。これはリモートまたは分散環境での削除を許可するものではありません。rclone によるクリーンアップで代用したり、依存関係のあるレコードを削除したりしないでください。廃止された子レコードも、親レコードをブロックし続けます。共有ツリーオブジェクトの退避では、常駐するローカルレコードのいずれかが必要とする間、その完全な依存関係の範囲が保護されます。

エビデンスとレポート

実際のレコード ID、コマンド、レコード／マニフェストのエビデンス、生成されたアセットのパス、および観測されたメトリクスを報告してください。実行レシート、検証結果、主観的なレビュー、再実行に関する主張を区別してください。封印が成功するまでは、作業フォルダーを保存済みレコードと呼ばないでください。また、検証済みのレシートと移行担当者の確認なしに、移行が完了したと説明しないでください。