Project Bourne

Project Bourne

Project Bourne は、再現可能な科学・工学ワークロードのための、オープンソースの実行・来歴管理インフラストラクチャです。

次の問いに答えます。この科学的な結果は、具体的にどのようにして得られたのでしょうか？

AIをクラスターから遠ざける

Researcher's workstation
  Linux / macOS
        │
  AI / Agent (optional)
        │ local stdio MCP
        ▼
  Bourne Control Plane
        │
        ├─ freezes immutable ExecutionPlan
        ├─ builds/stages versioned Bourne workers
        └─ uses existing VPN / OpenSSH
        ▼

HPC login / access node
  one-shot Bourne Remote Worker
        │
        ├─ validates the plan
        ├─ verifies staged file digests
        ├─ stages the execution bundle
        └─ submits with sbatch / qsub / bsub
        ▼

Slurm / PBS / IBM LSF
        │
        │ allocates resources
        ▼

Compute allocation
  execution-scoped Bourne Compute Worker
        │
        ├─ reads immutable ExecutionPlan
        ├─ observes actual allocation
        ├─ reproduces selected environment
        ├─ performs compute-side preflight
        ├─ executes exact scientific argv
        └─ writes durable result evidence
        ▼

Scientific workload

Later:

Researcher's workstation
        │
        │ existing SSH
        ▼
Remote Worker: reconcile
        │
        ├─ exact Bourne-owned scheduler job state
        └─ bounded result evidence
        ▼
Local Bourne provenance database

Remote Worker と Compute Worker はエージェントでも永続サービスでもなく、どちらも短期間だけ稼働する、バージョン管理された Bourne ワーカーです。Bourne は計算ノードに直接 SSH 接続しません。Slurm／PBS／LSF は Compute Worker を割り当て内に配置し、ジョブの投入を受け付けた後のジョブのライフサイクルを管理します。研究者のワークステーション／コントロールプレーンは切断しても、後で同じ実行を再調整できます。

HPC の利用経路では、クラスター上で AI、MCP サーバー、AI 認証情報、受信ポート、root アクセス、永続デーモン、パブリックインターネット接続は不要です。研究者が既に利用している OpenSSH の設定とスケジューラーへのアクセスを使用します。エージェントに渡されるのは、制限のないリモートシェルではなく、型付きの Bourne 操作です。

Bourne のコントロールプレーンは、Linux と macOS でサポートされ、テスト済みです。ネイティブ Windows はまだ検証もサポートもされていません。

Bourne はエージェントネイティブであり、エージェント依存ではありません。CLI と Python サービスは、エージェントや MCP がなくても動作します。

クイックスタート

人間

Project Bourne v0.8.1 を PyPI からインストールします。

python -m pip install "bourneprov==0.8.1"

bourne run python examples/demo.py
bourne list
bourne show @1

# Or execute an ExecutionRequest v2 document:
bourne execute --request bourne.json

インストール済みの CLI を使って、サイトに対応した SSH ワークフローを設定します。

bourne site add imperial \
  --ssh login.example.edu \
  --scheduler slurm \
  --local-root "$PWD" \
  --remote-root /work/$USER/project

bourne discover --site imperial
bourne plan --site imperial --request bourne.json --provider constraints.json

最初のプラン呼び出しでは、範囲を限定した候補が表示されます。その後、人間またはエージェントが明示的に選好を決定します。

bourne plan --site imperial --request bourne.json \
  --provider constraints.json \
  --trust-provider-classifications \
  --candidate sha256:...

bourne execute --plan <plan-id>
bourne execution wait <execution-id>

信頼フラグは、この宣言型プロバイダーにおける意味的分類に対する明示的なレビュー判断です。プロバイダー自身がその権限を付与することはできません。より限定的なユーザー判断には、--approve-variant-change PARAMETER または --declare-execution-only PARAMETER を使用します。選択した候補によってプロバイダーに紐づく JSON 入力が変更される場合、Bourne は元の入力を保持し、別途ハッシュ化した WorkloadVariant をプランに自動的に紐づけます。

投入が受け付けられた後、ジョブは Slurm／PBS／LSF が管理します。研究者のワークステーション／コントロールプレーン、VPN、SSH 接続、MCP ホスト、エージェントは切断してもかまいません。Bourne は後で再接続し、正確な実行内容を照合します。接続が切断され、状況が不明な場合でも、確認なしに再投入することはありません。

エージェント／MCP

v0.8.1 のエージェントおよび MCP エントリーポイントは、引き続きローカルの stdio を使用します。

python -m pip install "bourneprov[mcp]==0.8.1"
bourne mcp

# Or use the public transparent launcher:
npx -y @project-bourne/[email protected]

開発

Project Bourne では、開発、依存関係のロック、テスト、ビルドのフロントエンドとして uv を使用します。uv をインストールした後、コミット済みのロックファイルを同期し、次のコマンドでテストスイートを実行します。

uv sync --locked --all-extras --dev
uv run --frozen --no-sync python -W error::ResourceWarning -m unittest discover -s tests -v
uv build --no-sources

CI では、これらのコマンドのロック／フリーズ版を使用するため、古くなった uv.lock があれば、依存関係が意図せず変化するのではなく、失敗として検出されます。uv は開発ツール専用です。bourneprov の実行時依存関係ではなく、pip install にも不要です。npm ランチャーでも使われず、HPC のログインノードや計算ノードでも必要ありません。貢献者向けワークフローの全容については、CONTRIBUTING.md を参照してください。

Bourne を選ぶ理由

Bourne は、科学プログラムを変更することなく、任意の実行ファイルをラップします。ローカルファーストで、フレームワークに依存しません。Python、コンパイル済みソルバー、Julia、MPI プログラム、その他のコマンドが、同じ永続的な実験モデルを使用します。

bourne run bash -c "echo hello"
bourne run ./solver case.yaml
bourne run julia simulation.jl
bourne run mpirun -np 64 ./solver

プログラムの標準出力と標準エラー出力は、実行中も表示され、実験記録に保存されます。

v0.8 におけるランタイムの実態

v0.8 では、計画の実態、スケジューラーの実態、ランタイムの実態、実験の実態、検証、科学的妥当性を別々に扱います。実行スコープの Compute Worker は、バージョン管理されたプロセス、割り当て、CPU、メモリ、I/O、GPU、環境のエビデンスを、observed、partially_observed、unavailable、unsupported、unknown のいずれかの明示的なカバレッジとともに記録します。テレメトリーが欠落していても、有効なワークロードは失敗せず、捏造されたゼロ値に置き換えられることもありません。

IBM LSF が Slurm、PBS に加わり、範囲を限定したキュー検出、bsub、特定のジョブを対象にした実行中の bjobs、最近終了したジョブを対象にした bjobs -a、永続的な bhist による照合、bkill に対応します。既存の Apptainer/Singularity イメージは、選択したサイトに対応するプランに固定できます。Bourne はコンピュート側で既存のランタイム／イメージを検証し、科学的コマンドを正確な argv として渡します。イメージのビルド、プル、インストール、管理は行いません。v0.8 では、マルチノードのコンテナ起動のオーケストレーション、MPI ランチャーとコンテナの実行順序の決定、MPI ランチャーの挿入には対応しません。ランタイムのエビデンスとスケジューラーの対応状況を参照してください。

コアアーキテクチャ

Bourne Core は、決定論的な実行、エビデンス、計画、ストレージ、来歴を担います。CLI、SDK、MCP は、同じサービスを利用するアダプターです。

             Project Bourne Core
                    │
       ┌────────────┼────────────┐
       │            │            │
      CLI          SDK          MCP
    humans                     agents

リモートワーカーは、単発で実行されるユーザー空間の非 AI・非デーモンです。検出、プランの検証、ステージング、スケジューラーへの送信、照合のための、バージョン管理された操作のみを受け付けます。科学的コマンドは不変のプラン内で正確な argv として保持され、科学的 argv がリモートシェルのテキストに展開されることはありません。リモートワーカープロトコルは v1 のままです。v0.8 では、ワーカー結果プロトコル v3 とステージング済みプランプロトコル v4 が追加される一方、リリース済みのワーカー結果 v1/v2 およびステージング済みプラン v1/v2/v3 のペイロードを読み取る機能も維持されます。

エージェントと MCP の統合

標準のローカル stdio サーバーは bourne mcp です。安定版の公式 MCP Registry ID は io.github.KozakHou/project-bourne で、ポータブルな Agent Skill は skills/project-bourne にあります。v0.8.1 の npm パッケージと、それに対応する Registry メタデータには、同じリリース ID が使用されています。

MCP 互換のエージェントは、「このシミュレーションを 4 つの GPU で実行し、来歴を保持してください」のような明示的なリクエストを ExecutionRequest v2 に変換し、Bourne にプランの作成を依頼して、決定論的な解決結果を表示できます。その後、実行の意図が確立された段階で、不変のプランを実行できます。Bourne 自体は、制約のない自然言語を解釈せず、別のモデルを呼び出すこともありません。

エージェントの処理は、意図的に次の 2 段階に分かれています。

agent intent → ExecutionRequest v2 → bourne_plan → inspect → bourne_execute_plan

計画の作成では、ワークロードを実行したり、インフラストラクチャを暗黙に検出したりすることはありません。対象が曖昧な場合や事実が不明な場合は、未解決のままにします。MCP のアノテーションはホストの UX 向けのヒントです。Bourne Core は引き続き、不変のプラン、正確な argv、スケジューラージョブの所有権、アーティファクトのセマンティクス、来歴を強制します。MCP の統合とエージェント向けガイダンスを参照してください。

実行リクエスト

実行内容を、制約付きのバージョン管理された JSON リクエストとして一度だけ記述できるようになりました。

{
  "kind": "bourne.execution-request",
  "version": 2,
  "command": ["python", "train.py", "--case", "case1"],
  "artifacts": {
    "inputs": ["config.yaml"],
    "outputs": ["result.h5"]
  },
  "resources": {"cpus": 8, "gpus": 1, "walltime": "2h"},
  "execution": {"backend": "direct"},
  "verification": {
    "checks": [
      {"type": "output_exists", "path": "result.h5"},
      {"type": "output_min_bytes", "path": "result.h5", "min_bytes": 1024}
    ]
  }
}

bourne.json として保存し、同じ意図を計画または実行に使用します。

bourne request validate bourne.json
bourne request show bourne.json

bourne discover
bourne plan --request bourne.json
bourne execute --request bourne.json

実行も検出も行わずに、最小限のリクエストを作成します。

bourne request init --output bourne.json -- python train.py
bourne request schema > execution-request-v2.schema.json

既存のフラグベースのコマンドも引き続きサポートされます。並行する別の実装ではなく、同じ ExecutionRequest → WorkloadSpec → ExecutionPlan パイプラインにコンパイルされます。

bourne execute --backend direct --cpus 2 --output result.txt -- python script.py

リクエストファイルでは、相対パスの working_directory はリクエストファイルのディレクトリを基準に解決されます。その後、宣言されたアーティファクトは、その科学的作業ディレクトリを基準に解決されます。Bourne は、作業ディレクトリの字句上の値と解決済みの値の両方を保持します。また、解析や計画の際に $HOME を展開したり、シェル構文を評価したり、プロジェクトコードをインポートしたり、何かを実行したりすることはありません。

親参照にも、意図を保持する同じルールが適用されます。リクエストでは latest、@N、一意なプレフィックス、または完全な ULID を使用できます。Bourne は、リクエストされた値を保持するとともに、コンパイル済みワークロードで使用される正規の親 ULID を別に記録します。

サマリーのテレメトリーはデフォルトで有効で、すでに取得済みの事実を使用します。壁時計時間、UTF-8 の stdout／stderr のバイト数、判明しているアーティファクトの合計バイト数、リクエストされたリソース、観測された割り当て、およびタイムスタンプから確定できる場合のスケジューラーのキュー時間です。"telemetry": {"mode": "off"} を指定すると、サマリーは無効になります。取得できないメトリクスは利用不可として扱われ、ゼロにはなりません。

最初の決定論的な検証チェックは、output_exists、output_min_bytes、output_sha256 です。これらのチェックでは、取得済みの宣言された出力 Artifact レコードのみを評価します。検証結果はプロセスのステータスとは別に永続化されるため、実験のステータスが completed でも、検証結果は failed または unknown となることがあります。これらのチェックで確認できるのはアーティファクトに関する事実であり、科学的妥当性全般ではありません。正確な仕様と安全上の制限については、実行リクエスト、テレメトリー、検証を参照してください。

計画と実行

Project Bourne v0.4.0 では、v0.3 のインベントリを基盤とする永続的な計画レイヤーが追加されました。

bourne discover

bourne plan --backend direct -- python examples/demo.py
bourne execute --backend direct -- python examples/demo.py

bourne execution list
bourne execution show @1

bourne plan は、科学コマンドを実行せず、検出も行いません。フレームワークに依存しない WorkloadSpec を作成し、その明示的な要件と推定された要件を既存のインベントリと照合して、候補ごとに説明を示します。選択が曖昧でない場合に限り、不変の ExecutionPlan を永続化します。必要に応じて、リソースと配置の制約を明示してください。

bourne plan \
  --backend slurm \
  --target gpu \
  --cpus 16 \
  --gpus 4 \
  --nodes 1 \
  --memory 64G \
  --walltime 2h \
  -- ./solver case.yaml

選択した Slurm プランを実行し、結果の実行試行を調査または待機します。

bourne execute --plan @1
bourne execution show @1
bourne execution wait @1

記録済みのジョブがまだアクティブな間は、bourne execution cancel @1 により、Bourne が管理するそのジョブのキャンセルを要求できます。同じ計画およびライフサイクルモデルは、--backend pbs と --backend lsf にも対応します。

直接実行では、Bourne の既存のライブ出力、プロセスグループ、アーティファクト、系譜、および実験プロベナンスの仕組みが再利用されます。Slurm、PBS、LSF のプランでは、プランとともにステージングされる自己完結型の Bourne ワーカーが使用されます。ワーカーは事前チェックを行い、実際に割り当てられたホストと科学実験を記録します。アクセス側のコントローラーは、その上限付き JSON 結果をトランザクションでインポートします。計算ノードへの SSH 接続や、bourneprov パッケージの事前インストールは不要ですが、計算割り当て環境から Python 3 を使用でき、ステージングディレクトリと作業ディレクトリが見える必要があります。

ジョブの送信は実験ではなく、スケジューラーの完了は科学的成功を意味せず、リクエストされたリソースと割り当てられたリソースは同じではありません。Bourne は、これらを個別の永続的な事実として記録します。キャンセルで指定するのは任意のスケジューラージョブ ID ではなく、Bourne の実行参照であり、送信者の ID が確認されます。正確なモデル、安全境界、および現時点での制限については、ワークロードの計画とスケジューラー実行を参照してください。

計算サイトの検出（v0.3.0）

Bourne は、現在の ID に表示される実行環境の不変なローカルスナップショットを取得できます。

bourne discover
bourne inventory
bourne inventory --find python
bourne inventory --json

検出対象には、現在の ID とアクセス先、許可リストに登録されたユーザー関連のストレージパス、直接実行コンテキスト、汎用の PATH 実行ファイル、オプションの Conda／virtualenv／コンテナー／モジュールコンテキスト、安全なシステム機能、Bourne の履歴、および利用可能な場合は読み取り専用の Slurm／PBS／LSF ターゲットクラスの概要が含まれます。不明な実行ファイルは実行せず、汎用的な情報として記録されます。ラップトップ、デスクトップおよび GPU ワークステーション、DGX クラスの個人用マシン、共有の研究室システム、スケジューラー対応の HPC サイトは、いずれも有効な計算サイトです。スケジューラーのないマシンも、それ自体で完結した環境です。

検出は観察のみを行います。実行ファイルが見えても、ワークロードとの互換性が検証されたことにはならず、スケジューラーパーティションが見えても、ジョブの送信が許可されている証拠にはなりません。また、ストレージの役割に関するヒントは、保持ポリシーやバックアップポリシーを示すものではありません。インベントリはローカルに保持されます。プロバイダーは、他のユーザーのホームディレクトリをたどったり、共有ストレージをクロールしたり、SSH 認証情報やコンテナーシークレットを調べたり、任意の環境変数をダンプしたり、計算ノードに SSH 接続したり、スケジューラージョブを送信またはキャンセルしたり、環境を変更したりしません。正確なトポロジー、証拠、制限事項、セキュリティ上の仕様については、計算サイトの検出を参照してください。

来歴、アーティファクト、リネージ

Project Bourne v0.2 では、入力／出力のフィンガープリント、最小限の derived_from 関係、安全な実行コンテキストの観測、アーティファクトのトレース機能が追加されています。分離されたディレクトリから、決定論的な例を実行してください。

cp -R examples/provenance /tmp/bourne-provenance-demo
cd /tmp/bourne-provenance-demo
export BOURNE_DB="$PWD/bourne.sqlite3"

bourne run \
  --input config_A.json \
  --output result_A.csv \
  -- python demo_simulation.py config_A.json result_A.csv

bourne run \
  --derived-from @1 \
  --input config_B.json \
  --input result_A.csv \
  --output result_B.csv \
  -- python demo_simulation.py config_B.json result_B.csv

bourne show @2
bourne show @1
bourne trace result_B.csv

入力は実行前にフィンガープリントが取得されます。出力は実行後にフィンガープリントが取得され、失敗または中断された実行後に見つからない期待出力も対象に含まれます。SHA-256 の読み取りはチャンク単位でストリーミングされます。Bourne は、宣言されたファイルをコピーまたはアップロードしません。

パスはアーティファクトの ID ではありません。各キャプチャには安定した ULID が割り当てられ、SHA-256 によってコンテンツのバージョンが区別されます。過去のパスが複数のバージョンを示す可能性があり、現在のファイル内容から特定できない場合、bourne trace は候補を一覧表示し、推測を拒否します。

正確なキャプチャ、トレース、移行、セキュリティ上の仕様については、アーティファクト、リネージ、実行コンテキストを参照してください。

人間にわかりやすい実験参照

正規の実験 ID は、引き続き 26 文字の ULID です。実験を受け付けるコマンドでは、次の形式も使用できます。

01M02GDJEW...   case-insensitive unique ULID prefix
latest          most recent experiment
@1              most recent experiment
@2              second-most-recent experiment
@3              third-most-recent experiment

例：

bourne show latest
bourne show 01M02GDJEW
bourne compare @2 @1
bourne run --derived-from @1 -- ./solver case_B.yaml

Bourne は、プレフィックスが曖昧な場合に推測することはありません。bourne list はデフォルトで 10 文字のプレフィックスを表示し、bourne list --full-id は正規 ID を表示します。

シェル補完

補完候補には、正規の実験 ID、latest、最近の @N 参照が含まれます。現在のシェルセッションで補完を有効にするには、次を実行してください。

# Bash
source <(bourne completion bash)

# Zsh
source <(bourne completion zsh)

# Fish
bourne completion fish | source

bourne show と bourne compare の補完では、BOURNE_DB を含む、現在設定されているデータベースが照会されます。

Bourne が記録する内容

各実験で、次の内容を記録します。

• 実行ステータス（完了、失敗、中断）、正確な引数ベクトル、 作業ディレクトリ、UTC タイムスタンプ、実行時間、終了コード；
• 実行中および取得した stdout/stderr；
• Git リポジトリのルート、コミット、ブランチ、変更状態（取得可能な場合）；
• オペレーティングシステム、アーキテクチャ、ホスト名、CPU、任意の NVIDIA ランタイム メタデータ；
• 要求された実行可能ファイルのパスと解決された実行可能ファイルのパスに加え、厳密に許可リストに登録された virtualenv/Conda コンテキストのヒント；
• 明示的に宣言された入出力アーティファクトのバージョンと直接の系譜。

コレクターは、利用できない情報があっても適切に動作を継続します。Git、NVIDIA ツール、GPU、環境の ヒント、または実行可能ファイルの解決に失敗しても、ワークロードは停止しません。任意の 環境変数は保存されないため、認証情報やトークンはデフォルトでは取得されません。

失敗したコマンドや中断されたコマンドは、bourne がプロセスのセマンティクスを返す前に保存されます。

bourne run --output expected.csv -- python -c "raise RuntimeError('boom')"
bourne show @1

POSIX システムでは、Bourne は専用のプロセスグループを使用するため、通常、Ctrl+C によって無関係な プロセスを対象にせず、子孫プロセスを終了できます。

実行の成功は検証を意味するものではなく、決定論的なアーティファクト検証も科学的妥当性全般を保証するものではありません。Bourne はこれらの状態を個別に記録します。

ローカルストレージと移行

デフォルトの SQLite パスは次のとおりです。

~/.local/share/bourne/experiments.sqlite3

プロジェクト固有のデータベースを使用するには、次のようにします。

export BOURNE_DB=/path/to/experiments.sqlite3

リリース済みの v0.1.1 から v0.7.0 までのデータベースを含め、古い Bourne データベースを v0.8.0 で開くと、スキーマ 7 まで決定論的なトランザクション移行が実行されます。 既存の実験、アーティファクト、系譜、インベントリ、ワークロード、プラン、 実行、スケジューラージョブ、割り当て、イベント、実験リンクは引き続き読み取り可能です。 移行では、v0.4 の記録に ExecutionRequest の履歴を新たに作成することはありません。 不明または新しいスキーマバージョンの場合は明示的にエラーとなり、Bourne が 既存のデータベースをリセットすることはありません。新しいディスカバリーのたびに、個別の不変スナップショットが作成されます。

ライセンス

Project Bourne v0.5.0 以降は Apache License 2.0 のもとで配布されます。v0.4.0 までのリリースには、リリース時に適用されていた MIT License の条項が引き続き適用されます。詳細は ライセンスの履歴をご覧ください。

リリース検証

リリースバージョンは 0.8.1 です。ベースランタイムにはサードパーティー依存関係がなく、MCP サポートは引き続き明示的なオプションの追加機能です。

ソースツリーのテストを実行するには、次のコマンドを使用します。

uv sync --locked --all-extras --dev
uv run --frozen --no-sync python -W error::ResourceWarning -m unittest discover -s tests -v
uv build --no-sources

コンピュートワーカーの stdout と stderr は実行中も出力され、結果バンドル内では取得した各ストリームにつき 8 MiB までに制限されます。切り詰められたことは、ランタイムの証拠として明示されます。 通常のローカル bourne run では、既存の取得動作が維持されます。ディスクにスプールするログ、自動アーティファクト検出／アーカイブ、科学計算用依存関係の インストールまたはソースビルド、汎用データ同期、制限のない リモートシェル、スケジューラーを使わない切断耐性のあるリモート監視、割り当て全体にわたる分散 テレメトリー、キュー／パフォーマンス予測、任意の検証スクリプト、 ホスト型 HTTP MCP、組み込み LLM、広範な科学的妥当性の推論は、引き続き v0.8 の対象外です。ランタイムの証拠とスケジューラーのカバレッジ、 サイト対応アーキテクチャ、VISIONをご覧ください。

LSF の実稼働環境での検証と Apptainer の実稼働環境での検証は、まだ実施されていません。ランタイムの サンプリングは実行単位で行われ、複数ノードの割り当て全体にわたって自動的に集約されることはありません。Bourne は MPI ランチャーを注入せず、コンテナーと MPI の実行順序を自動的に 選択することもありません。移植可能な LSF のメモリー／GPU リソース構文は、引き続きサイトごとに異なり、未解決です。