エンジンおよびライブラリバージョンの固定 (Pinning engine and library versions)

このガイドは、プロジェクトを配布し、既知の正常動作するエンジンバージョンおよびライブラリバージョン群のもとで確実に実行させたい管理者を対象としています。バージョンを固定（Pinning）することでプロジェクトが真実のソース (source of truth) となります：ユーザーがプロジェクトをアクティベートすると、エンジンは互換性のないバージョンでの実行を拒否し、プロジェクトが宣言したバージョンに合わせて各固定ライブラリをプロビジョニングします。

どちらの固定情報も プロジェクト隣接設定 (project-adjacent config) — プロジェクトの griptape-nodes-project.yml の隣に配置された griptape_nodes_config.json に記述します。プロジェクト YAML 自体にはバージョンデータは含まれず、隣接設定がそれを担います。このファイルがユーザー設定の上にどのように重なるかについては、ワークスペースを参照してください。

/MyProject/
  griptape-nodes-project.yml      <- プロジェクトファイル (ここにバージョン固定は記述しない)
  griptape_nodes_config.json      <- エンジンとライブラリの固定情報をここに記述

両方のファイルを一緒に配布してください。隣接設定はユーザーのグローバル設定より上、かつワークスペース設定より下に重ねられるため、ユーザーのマシン全体の設定を汚すことなく、そのプロジェクトをアクティベートするすべてのユーザーに固定情報が適用されます。

エンジンバージョンの固定 (Pin the engine version)

requires_engine に PEP 440 バージョン指定子を設定します。プロジェクトがアクティベートされる際、実行中のエンジンのバージョンがこの指定子を満たしている必要があり、満たしていない場合はアクティベーションがブロックされます。

{
  "app_events": {
    "on_app_initialization_complete": {
      "requires_engine": ">=0.80,<1.0"
    }
  }
}

指定子は実行中のエンジンバージョンと照合されます。
不一致の場合は アクティベーションがブロックされます: プロジェクトは読み込まれず、必要なバージョンと現在実行中のバージョンがユーザーに通知されます。
キーを省略する（または null に設定する）と、エンジンチェックは完全にスキップされます。

下限のみの指定ではなく、範囲を区切った指定（>=0.80,<1.0）を使用することで、挙動が変更された可能性のある将来のメジャーエンジンリリース下でプロジェクトが意図せずアクティベートされるのを防ぐことができます。

ライブラリバージョンの固定 (Pin library versions)

libraries_to_download は、エンジンがプロジェクトに代わってプロビジョニングするライブラリを一覧化します。各エントリは、単純な git URL 文字列（従来の挙動 — バージョン強制なしでソースからクローン）か、バージョン固定を追加するオブジェクトのいずれかを指定できます：

{
  "app_events": {
    "on_app_initialization_complete": {
      "libraries_to_download": [
        {
          "name": "Griptape Nodes Library",
          "version": "==0.79.0",
          "git_url": "griptape-ai/griptape-nodes-library-standard@v0.79.0"
        }
      ]
    }
  }
}

フィールド	必須	意味
`git_url`	はい	`url@ref` 形式の Git ソース: 完全な URL または `user/repo` 略記、および任意の `@branch\\|tag\\|commit` サフィックス。`@ref` がない場合はリポジトリのデフォルトブランチが使用されます。
`version`	いいえ	インストールされたライブラリが満たすべき PEP 440 指定子（例: `==0.79.0`、`>=1.2,<2`）。ソースのみで固定する場合は省略します。
`name`	いいえ	ライブラリのマニフェスト `name`。設定されている場合、再ダウンロードが必要かどうかを判断するためにインストール済みのコピーが名前で照合されます。

クローンするソースと強制するバージョンが乖離しないように、git_url の ref と version の両方を同じリリース（例: @v0.79.0 と ==0.79.0）に固定してください。

ダウンロード対象のライブラリのみが上書きされる

libraries_to_download にリストされているライブラリは、固定条件を満たすためにエンジンが 上書き する唯一の対象です。単に登録されているだけ（パスによって libraries_to_register に記載されている）のライブラリは現状のまま読み込まれ、プロジェクトのアクティベーションによって上書きされることは 決してありません。プロジェクトにライブラリのバージョンを強制させたい場合は、登録リストだけでなくダウンロードリストにそのライブラリを含める必要があります。

ライブラリを libraries_to_register に重複して追加する必要はありません：ダウンロードが成功した後、エンジンは解決されたマニフェストパスを自動的に登録リストに追加するため、ダウンロードから読み込みまでの一連の流れが単独で完結します。

ダウンロードファイルの配置場所

libraries_to_download は何をどのバージョンでインストールするかを指定します；libraries_dir（プロジェクト YAML 内のフィールド）は、それらのライブラリをどこにインストール・解決するかを指定します。これら 2 つは連動します：固定された各ダウンロードは、プロジェクトの解決済みライブラリディレクトリ内にプロビジョニングされます。プロジェクトが libraries_dir を宣言しておらず親からも継承していない場合、ダウンロードはワークスペース相対の libraries ディレクトリに配置され、従来の挙動が維持されます。プロジェクトツリー全体で共有の libraries_dir を使用している場合、親によって一度ダウンロードされた固定ライブラリは再ダウンロードされることなくすべての子プロジェクトで再利用されます。

アクティベーション時の動作 (What happens on activation)

ユーザーがバージョン固定されたプロジェクトをアクティベートすると、エンジンは libraries_to_download の各エントリをインストール済みの状態と比較し、以下のいずれかのプランを策定します：

プラン	発生条件	効果
SKIP	インストール済みのバージョンがすでに固定条件を満たしている	何も変更されません。
INSTALL	ライブラリがまだインストールされていない	固定されたソースをクローンします。非破壊的です。
OVERWRITE	条件を満たさない異なるバージョンがインストールされている	ローカルのライブラリディレクトリを削除し、固定ソースを再クローンします。破壊的です。

破壊的な OVERWRITE が実行される前に、エディタは完全なプランの読み取り専用 プレビュー を表示し、ユーザーの承認を待ちます。拒否した場合は安全な何もしない状態（no-op）となります：直前のプロジェクトがアクティブなまま維持され、ライブラリファイルは一切変更されません。また、実行中のエンジンが固定条件を満たせない場合はプレビュー上でエンジンバージョンの不一致（requires_engine）が報告され、承認がブロックされます。

設定の実例 (Worked example)

エンジン >=0.80,<1.0 を要求し、標準ライブラリを 0.79.0 に固定するプロジェクトの例：

/MyProject/griptape-nodes-project.yml

project_template_schema_version: "1.0.0"
name: "my-pinned-project"
description: "Runs on engine 0.80-0.x with the standard library pinned to 0.79.0."

/MyProject/griptape_nodes_config.json

{
  "app_events": {
    "on_app_initialization_complete": {
      "requires_engine": ">=0.80,<1.0",
      "libraries_to_download": [
        {
          "name": "Griptape Nodes Library",
          "version": "==0.79.0",
          "git_url": "griptape-ai/griptape-nodes-library-standard@v0.79.0"
        }
      ]
    }
  }
}

アクティベーション時の挙動：

エンジンチェック — 実行中のエンジンが >=0.80,<1.0 の範囲外である場合、バージョン不一致メッセージとともにアクティベーションがブロックされます。
初回アクティベーション（クリーンなマシン） — 標準ライブラリが存在しないため、プランは INSTALL となり、v0.79.0 がクローンされて登録されます。
再アクティベーション（0.79.0 がすでに存在） — 固定条件を満たしているため、プランは SKIP となります。
異なるバージョンがインストールされている場合（例えば以前のプロジェクトが 0.78.0 を残していた場合） — 0.78.0 は ==0.79.0 を満たさないため、プランは破壊的な OVERWRITE となります：プレビューモーダルが表示され、承認されるとローカルのライブラリディレクトリが削除されて v0.79.0 が再クローンされます。

注意事項と留意点 (Notes and gotchas)

文字列のみの指定も引き続き機能します。 既存の "libraries_to_download": ["user/repo"] リストは、バージョン強制を行わずにソースからのクローンを継続します。オブジェクト形式のみが version を強制します。
ユーザーごとの上書きが優先されます。 ユーザーのワークスペース設定は、プロジェクト隣接設定の上に重ねられます（ワークスペースを参照）。ユーザーはローカルで固定設定を上書きできます；固定設定はプロジェクトと一緒に配布されるデフォルト値であり、変更不能なロックではありません。
CLI での代替手段。 ヘッドレスエンジンを自動化する管理者は、griptape-nodes libraries download <git_url> でライブラリをクローンし、griptape-nodes libraries sync で更新できます。ライブラリおよびコマンドラインインターフェースリファレンスを参照してください。上記で解説した宣言的設定は、同じ固定設定をプロジェクトと一緒に配布するための移植性の高い方法です。