ガイド

フェデレーション

AI エージェントの支援による翻訳です。内容に相違がある場合は、英語版ページが優先されます。文章に問題を見つけた際は、Issueまたはプルリクエストをお願いします。

フェデレーションを使うと、個別に所有されるコンテキストレイヤーを、統合したり更新責任を移したりすることなく、チームでまとめて参照できます。

中央集約ではなく合成する理由

コンテキストレイヤーが最新に保たれるのは、所有者が仕事の中で読み、修正するからです。他チームの内容を中央に集約すると、内容と、それに責任を負う人たちが切り離されてしまいます。フェデレーションなら、リポジトリ、所有者、レビューの流れをそのまま維持できます。詳しい論拠は設計の理由にあります。

兄弟マウントとは

兄弟とは、ホスト側が federation.mountsで宣言する、別チームのコンテキストレイヤーです。この宣言では、ホストが参照する不変のコミットを完全な形でピン留めし、所有者と作業に応じた経路を記録します。ツールは、そのピンにある兄弟のマニフェストで定義されたレイヤーの投影を、git 管理外のキャッシュへ読み込みます。兄弟の内容がホストにコピーされることはありません。

投影とは、そのピンにある兄弟自身のマニフェストによって読み取り可能となる内容の総体です。leji.json、コンテキストルート、ブートプロファイル、カテゴリインデックスファイル、agentsのバインディングが名指しするプロファイル、エージェントプロファイルと決定記録のツリー、機械可読なインデックスと変更履歴、そして生成されたインデックスが列挙する統制対象のパスすべてが、どこにあっても含まれます。

兄弟レイヤーは多くの場合、より大きな製品リポジトリ内にあります。この境界があるため、コンテキストを読むためだけに、マウントが製品全体を取り込むことはありません。

マウントは参照であり、フォークでもアクセス権の付与でもありません。権限は兄弟側に残り、誰が読めるかは引き続き兄弟のバージョン管理システムが決定します。マウントは、すでにアクセス権を持つ人が、その関係と選択されたリビジョンを確認できるようにするだけです。

"federation": {
   "mounts": [
      {
         "name": "product-context",
         "source": "https://github.com/acme/product-context",
         "pin": "7d3f2a19c4e8b6a0d5f1c2e9b8a7f6d5c4b3a2e1", // 完全なコミット ID：記録上のバージョン
         "trackingRef": "refs/heads/main",                    // 古さはこれを基準に判断する
         "owner": { "name": "Product team", "contact": "product@acme.example" },
         "role": "product-side context, owned by the product team",
         // 経路の決定：このマウントが作業に関係する条件
         "categories": ["domain", "decisions"],
         "requiredWhen": ["a task changes how a plan or entitlement is represented"]
      }
   ]
}

ピンの更新は、leji.jsonに対する、レビュー済みの変更として行います。ホストは関係を宣言し、兄弟側は自身のリポジトリ、所有者、レビューのゲート、変更履歴、適合性の宣言を維持します。

マウントを扱う

leji mounts hydrate --fetch      # 各兄弟のレイヤー投影をそのピンで実体化する
leji mounts status               # 可用性、完全性、各ピンの遅れを確認する
leji mounts update-pin <name>    # ひとつのピンを観測済みのコミットまで進める
leji mounts locate <name>        # 読み手が兄弟を読む場所を示す

hydrate --fetch は、明示的にネットワークから取得し、各投影をそのピンで実体化します。status は、可用性、完全性、ピンの古さを調べます。locateは、読み手が兄弟レイヤーを開くための、リゾルバ管理下のパスを返します。

マウントを最新に保つには、この一連の操作を繰り返します。hydrate --fetchで出典を観測し、status で各ピンの遅れを確認します。次に update-pinで、リゾルバが実際に観測したコミットまでピンを進め、もう一度 hydrateを実行して、新しいピンで投影を実体化します。ピンの更新と実体化は別々の操作なので、手元の内容が変わる前に、書き換えをレビュー可能な差分として確認できます。

update-pinは既定ではオフラインで動作します。実行時に実際に観測された最後の証跡まで進めるだけで、最新であることを示唆せず、その旨を出力に明記します。実行中に宣言された出典を観測するには--fetchを付けます。接続先はその出典だけです。途中のどこかで失敗した場合、処理は中止され、leji.json は変更されません。ピンは前方にしか進みません。現在のピンの子孫でない対象は、--to <oid> で明示的に名指しし、さらに --allow-non-fast-forwardを付けないかぎり拒否されます。この組み合わせが必要になる理由として多いのは、上流ブランチが書き換えられた場合です。ただし、意図して以前のコミットへ巻き戻す場合にも必要になります。チェックしているのは履歴が書き換えられたかどうかではなく、祖先関係だからです。この組み合わせを使うたびに警告が表示され、JSON 出力にも記録されます。現在のピンから到達できないコミットへピンを移動するためです。マニフェストを変更せずに比較と変更内容を確認するには--dry-run を使います。--fetchと組み合わせた場合、そのフラグによるストア操作とネットワーク通信は実行されるため、取得したオブジェクトと参照は管理下のストアに残ります。

書き換えられるのはピン自体のバイト列だけです。そのため、フィールドの順序、書式、スキーマで定義されていないキーは、編集後もそのまま残ります。古いピンのキャッシュエントリもその場に残ります。内容アドレスで管理されているため、単に参照されなくなるだけです。整理用のコマンドはありません。容量を解放する場合は、.leji/mounts/ 配下の古いエントリを手動で削除してください。

ハイドレーションの途中で、不完全な投影が公開されることはありません。キャッシュは .leji/mounts/ 配下に置かれ、init がそれをルートの .gitignore に追加します。このパスは実装の詳細として扱ってください。locate を使うと、兄弟レイヤーの参照先が分かります。キャッシュのパスを直接記述すると、公開方法が変わった際に動作しなくなります。

ビューアーでは、端末を使わずに同じ状態を確認できます。leji viewerは、ホストと兄弟レイヤーを図示した Manifest ページを生成し、マウントごとに可用性、ずれ、所有者、ピン、出典を 1 行で表示します。ハイドレート後に再生成してください。

federated を宣言する

ハイドレートされていないマウントは警告の対象ですが、ビルドは失敗しません。CI では leji validate --federation=available|required を使って、可用性を必須にするか選択できます。通常の検証では取得を行わず、すべてのマウントを必須にも設定しません。

ローカルで利用できるだけでは、適合性を満たしません。ピンは sourceで提示された参照から到達可能でなければならず、その確認にはネットワーク接続が必要です。このチェックには leji conformance --federation=verify を実行してください。チェックが出典に到達できない場合は unknown と報告されます。unknown がレベルを与えることは決してありません。

検証は必要条件ですが、それだけでは十分ではありません。federatedはさらに、このコンテキストレイヤー自身が別のリポジトリからピン留めされたマウントとして利用されていること、古いピンの報告が用意されていること、そしてブートプロファイルと生成されたインデックスがすべての兄弟を示していることを要求します。

最初の 2 項目はプロセスに関する申告なので、verifiedLevelが利用者に代わって宣言することはありません。1 台のマシンで実体化したという事実は、適合性の入力にはなりません。

まず配布のパターンを選ぶ

ドキュメント専用の git サブモジュールは、多数のリポジトリでひとつのコンテキストレイヤーを共有するためのものです。フェデレーションは、すでに個別のレイヤーを所有している複数のチームをつなぐためのものです。解決する課題が異なるため、フェデレーションがサブモジュールに取って代わることはありません。サブモジュールの詳しい手順は導入ガイドにあります。

規範的な投影の閉包、失敗の境界、フェデレーションの完全な規則については、配布を参照してください。