Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

id: ADR-012 title: ライブ設定適用は、ジェネレーションスコープのパブリケーションと結果を使用する date: 2026-07-19 status: proposed relates-to:

  • https://github.com/zeroclaw-labs/zeroclaw/issues/7897
  • docs/book/src/architecture/config-lifecycle.md
  • crates/zeroclaw-config/src/schema.rs
  • crates/zeroclaw-gateway/src/api_config.rs
  • crates/zeroclaw-channels/src/orchestrator/mod.rs

ADR-012: ライブ設定の適用は世代スコープの発行と結果を使用する

コンテキスト

ZeroClaw は CLI、RPC、TUI、Quickstart、およびゲートウェイサーフェスを通じて設定を保存できます。保存が成功しても、すべての長期稼働サブシステムが新しい値を採用したとは限りません。ゲートウェイで可視の状態はすぐに変更される場合がありますが、デーモンが所有するチャンネル、セッション、プロバイダー、およびその他のコンポーネントは、/admin/reload がサブシステムグラフを再構築するまで、以前のランタイム状態を使用し続けます。

受理された RFC #7897 は、限定的な改善を対象としています。選択されたセキュリティポリシーおよびチャネルの変更は、デーモンの完全な再読み込みなしで適用でき、一方でオペレーターは、各サブシステムが実際に処理した世代に対する、対象固有の結果を受け取ります。受理されたアーキテクチャでは、1 つの正規の公開済み設定、世代固有の結果、限定的なセキュリティオーバーレイ、そして実証済みのチャネル遷移モードのみが必要です。

このレコードは、そのターゲットと実装ゲートを定義します。ライブ適用がすでに存在すると主張するものではありません。これらのゲートがリリースされるまでは、Config lifecycle で説明されている現在の保存済み対適用済みの挙動と /admin/reload フォールバックが、引き続き正とされます。

決定

正規の設定を1つ生成して公開する

プロセスには、正規の公開済み設定リビジョンが 1 つあります。プロセス内のライターは、リーダーとは別に直列化されます。ライターは現在のリビジョンをクローンし、変更を適用して検証し、直列化された書き込みトランザクション内で結果の設定を永続化し、その後初めて次の世代をアトミックに公開します。config.toml を編集する独立したプロセス間の調整は、この決定の範囲外です。

読み取り側の設定ロックは、非同期ディスク I/O の実行中も保持されません。公開によって、長期間保持される 2 つ目の設定キャッシュが作成されたり、汎用的なロールバック用に以前の設定スナップショットが保持されたりすることはありません。

Apply イベントは、公開された世代と変更されたパスを識別します。これらは、別の完全な設定コピーや以前の設定値を保持しません。各ターゲットは現在の正規リビジョンを読み取り、その世代がイベントの世代と一致する場合にのみ適用します。無効になったイベントはスキップされ、新しい世代の結果を上書きすることはできません。

実際に適用された生成の結果を記録する

すべての適用対象は、それぞれの世代固有の結果を記録します:

  • AppliedLive は、対象がデーモンを再読み込みせずに、特定された世代を適用したことを意味します。
  • QueuedForReload は、変更は保存されたものの、その対象では /admin/reload が必要であることを意味します。結果には具体的な理由が含まれます。
  • Rejected は、ターゲットがその世代のライブ適用を拒否したことを意味します。結果には具体的な理由が含まれます。

古い世代のターゲット完了によって、新しい世代のステータスが上書きされることはありません。Config status の表示では、変更パスのプレフィックスから 1 つのグローバルな適用済み状態を推測するのではなく、ターゲットの結果を報告します。

承認済みのセキュリティオーバーレイの適用範囲を限定する

承認済みセキュリティのライブ適用境界は、allowed_commands と forbidden_paths のみを対象とします。これらのフィールドが変更された場合でも、ポリシーを再構築するのではなく、既存の SecurityPolicy とそのレート制限トラッカーを保持します。

実行は、適用対象の世代向けの型付きオーバーレイを受け取ります。オーバーレイは、生成されたタスクおよび JoinSet の処理に明示的に伝播されます。タスクローカル状態は利便性のために使用できますが、唯一のセキュリティ権限源ではありません。実行スコープがない場合や世代が一致しない場合は、古いポリシーにフォールバックせず、フェイルクローズします。

より広範なリスクプロファイルの再割り当てやその他のセキュリティポリシーの変更は、後のアーキテクチャ上の決定により安全なライブ境界が確認されない限り、リロード待ちのキューに残ります。

チャンネルの変更を、実績のある移行モードに制限する

承認済みチャンネルのライブ適用境界は、InPlace または Handover 境界が証明された変更のみをサポートします。インプレース変更は、使用時に実行中のアダプターによって解決されます。ハンドオーバーは、既存のチャンネルインスタンスをデタッチする前に、置き換えを構築して証明します。

どちらの境界も証明できない変更は、具体的な理由を伴って QueuedForReload のままになります。この決定では、汎用的な停止・起動ロールバック機構は追加されません。それには以前の設定状態を保持するか、ハンドオーバー契約が回避することを意図している中断を受け入れる必要があるためです。

フォールバックとしてフルリロードを維持する

/admin/reload は、実証済みのライブ適用範囲外にあるすべての設定変更に対して、サポート対象のフォールバックのままです。この決定により、reload の認証、認可、または standalone-gateway の動作が変更されることはありません。

受け入れゲート

この ADR は、以下の条件をすべて満たすまで提案中のままです：

  • 正規化された構成の発行と世代スコープの適用済み状態台帳は、新しいライブ適用の動作を有効にせずに提供されます。
  • すべてのターゲット結果は処理した世代を名前に含めており、古い完了が新しいステータスを上書きすることはできません。
  • allowed_commands と forbidden_paths は、既存のレート制限トラッカーを保持し、スコープの欠落や世代の不一致がある場合にはフェイルクローズする、型付きで明示的に伝播される実行オーバーレイを使用します;
  • 実証されたチャネルのインプレースおよびハンドオーバーパスは、置換の準備が整うまで既存のサービスを維持し、サポートされていない変更は具体的なリロード理由を報告します。さらに
  • 設定 API と運用者向けドキュメントは、ターゲットごとのライブ、キュー、拒否の結果を具体的な理由とともに報告し、フォールバックとして /admin/reload を保持します。

正規公開と結果台帳は、セキュリティおよびチャネルのコンシューマーを有効化する前に、新たな本番動作を伴わずにリリースする必要があります。セキュリティの本番適用は、チャネルの本番適用に先行します。

結果

肯定的な結果:

  • 設定の状態では、保存された内容と各サブシステムが実際に適用した内容を区別できます。
  • 同一プロセス内の並行書き込みが、古い開始リビジョンから暗黙的に公開されることはありません。
  • 古い適用試行の完了が遅れても、新しい世代が適用済みと見なされることはありません。
  • 承認済みのセキュリティコンシューマーおよびチャネルコンシューマーには、限定的でテスト可能な安全境界があります。
  • サポート対象外の変更でも、明確で使い慣れたフルリロードの手段が維持されます。

否定的な結果:

  • Publication には、リーダー向けの設定ハンドルに加えて、ライターのシリアライズと世代の追跡が必要です。
  • 各ライブアプライターゲットは、結果ハンドラーと世代を考慮したテストを備えている必要があります。
  • 実行スコープのセキュリティ状態は、非同期タスクの境界を越えて明示的に伝播させる必要があります。
  • 多くの設定パスでは引き続きリロードが必要です。ライブ適用は一般的な保証ではなく、検証済みの動作の許可リストです。

参照