OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

はじめに

パス 3 のライブ SQLite E2E ハーネス

Path 3 のライブ SQLite E2E ハーネスは、従来の JSONL ファイルが移行入力またはアーカイブ資料として残る一方で、Gateway が SQLite を正規のセッションおよびトランスクリプトストアとして使用していることを証明します。これはメンテナー向けの証明ハーネスであり、通常のユーザー診断ではありません。

Gateway が移行後のトラフィックを処理した後は、従来の JSONL との同等性は、もはや有効なランタイム健全性シグナルではありません。新しいターンでは SQLite のみが更新されるため、正常に移行された Gateway では、SQLite のトランスクリプト行数が従来の JSONL の件数と異なる場合があります。したがって、ライブハーネスは各ステップで Gateway の動作、SQLite 行の変化、従来ファイルの静止状態、およびログの健全性を測定する必要があります。

コマンド形式

想定されるライブコマンドは次のとおりです。

bash
node scripts/path3-live-sqlite-e2e.mjs \  --url http://127.0.0.1:18789 \  --agent main \  --session-key agent:main:path3-live-e2e:<timestamp> \  --json

このコマンドは、すでに実行中の Gateway に接続します。後から明示的な移行モードが追加されない限り、移行の開始、停止、インポート、再実行は行いません。CI または分離されたローカル環境向けのバリアントでは test/helpers/openclaw-test-instance.ts を使用できますが、ライブ証明パスでは、実際のオペレーター Gateway と、その実際のエージェント別 SQLite データベースを検査する必要があります。

分離されたビルド済み CLI の証明

ビルド済み CLI の証明ランナーは、分離された従来のセッションストアにシードデータを投入し、再ビルドした Gateway を起動して、ランタイム読み取りの開始前に、起動時処理によって使用頻度の高い従来セッションが SQLite にインポートされることを証明します。最初の Gateway 起動前に openclaw doctor --fix を実行してはなりません。実行すると、切り替え後の初回起動時にユーザーが利用するアップグレードパスではなく、手動移行パスを証明することになるためです。

起動時インポートの後、分離された証明では、診断証拠として openclaw doctor --session-sqlite inspect および openclaw doctor --session-sqlite validate を実行できます。これらの doctor コマンドは、起動時アップグレード証明の移行ドライバーではありません。個別の doctor インポートシナリオでは、従来のトランスクリプトファイルと trajectory サイドカーにシードデータを投入し、SQLite が正規ストアのままで、それらの成果物を doctor がアーカイブすることを検証する必要があります。

事前確認

事前確認ではベースラインを収集し、Gateway が使用可能でない場合は、証明用ターンを送信する前に失敗します。

  • GET /health と Gateway の詳細ステータスは、Gateway が実行中で到達可能であることを報告する必要があります。
  • CLI と Gateway のバージョンは、テスト対象のブランチと一致する必要があります。
  • ハーネスは、アクティブな Gateway ファイルログのログカーソルを記録します。
  • ハーネスは、sessions、session_entries、transcript_events、transcript_event_identities、および session_routes について、エージェント別の SQLite テーブル行数を記録します。
  • ハーネスは、従来の sessions.json、参照される JSONL ファイル、および証明用セッションの候補 JSONL パスについて、mtime、size、および存在状況を記録します。
  • lsof -p <gateway-pid> は SQLite DB/WAL/SHM ハンドルを示し、使用中の .jsonl または sessions.json ハンドルがないことを示す必要があります。

ライブモードでは、openclaw doctor --session-sqlite validate は情報提供のみを目的とします。切り替え後のトラフィックの後では、従来ファイルに対する想定内の差異が報告される場合があります。ハーネスは、doctor の出力を分類と移行インベントリに使用する必要がありますが、ランタイムの合否判定基準として使用してはなりません。

エージェント駆動シナリオ

ライブシナリオでは専用の証明用セッションキーを使用し、可能な限り公開 RPC パスを通じて Gateway を操作します。通常の永続化を実行するにはエージェントのターン 1 回で十分ですが、完全な証明では、以前は個別のライブ確認が必要だった 3.1b の接合部を網羅する必要があります。

  • 通常のチャットターン: 証明用セッションを作成または再利用し、実際のエージェントプロンプトを送信して、最終的なアシスタント結果を待ち、chat.history または同等の Gateway プロジェクションを検証します。
  • トランスクリプトの同一性: 同じマーカーが Gateway の履歴と SQLite のトランスクリプト行に現れることを検証します。安定したイベント ID の行が存在する場合は、それも対象に含めます。
  • セッションメタデータアクセサー: Gateway/セッションアクセサーを通じて証明用セッションと選択した既存のライブセッションを読み取り、SQLite の行と比較します。
  • セッションパッチのプロジェクション: 証明用セッションに対して元に戻せるモデル/セッションメタデータの変更を適用し、その後、プロジェクションされた行と Gateway の応答が一致することを検証します。
  • Compaction チェックポイントのライフサイクル: 証明用セッション、またはハーネスが作成した合成フィクスチャセッションに限り、チェックポイントを一覧表示、分岐、および復元します。
  • 再起動からの復旧: 制御された証明用セッションまたは分離されたテストインスタンスに対して、安全な復旧マーカーパスを実行します。ライブモードでこのステップを実行できるのは、対象セッションセットが明示されており、元に戻せる場合に限ります。
  • クリーンアップのライフサイクル: 証明用セッションを削除またはリセットし、その後、SQLite のライフサイクル行とアーカイブ済みトランスクリプトの状態を検証します。

WhatsApp や音声通話の入力など、実際のオペレーター Gateway で安全に実行できないトランスポート固有の接合部については、偽の外部トランスポートではなく、同じ SQLite 契約に対するオーナーレベルのランタイムプローブを使用する必要があります。

ステップごとのアサーション

各ステップでは、前後の状態のスナップショットを取得し、構造化されたアサーション記録を書き込みます。

  • SQLite の行数は、想定された箇所でのみ増加します。
  • ランタイムイベントを記録する、マーカーで裏付けられた証明用セッションでは、trajectory のランタイム行が増加します。
  • 証明用セッション行には、想定される session_id、ステータス、タイムスタンプ、メタデータ、およびルート行が含まれます。
  • Gateway の履歴/セッションプロジェクションは、SQLite のトランスクリプト末尾と一致します。
  • 証明用セッションの JSONL ファイルは作成も変更もされません。
  • 証明用セッションの .trajectory.jsonl、.trajectory-path.json、またはマーカーから派生した trajectory/<session>.jsonl サイドカーは作成されません。
  • 既存の従来 JSONL ファイルと sessions.json は、ステップが明示的なオフライン移行またはアーカイブ操作でない限り、変更されません。
  • Gateway プロセスは、.jsonl または sessions.json のハンドルを開きません。
  • 前回のカーソル以降のログには、シナリオで明示的に許可リストへ追加されていない限り、ERROR、FATAL、SQLITE_、no such column、セッションストア利用不可、再起動復旧失敗、またはトランスクリプト照合警告が含まれません。

ログスキャンは合否契約の一部です。ヘルスチェックに応答しても、SQLite スキーマエラーまたはトランスクリプト照合の失敗を繰り返し出力する Gateway は、Path 3 では正常と判定されません。

証拠成果物

ハーネスは .artifacts/path3-live-e2e/<timestamp>/ 配下に証拠を書き込み、git の管理対象外にする必要があります。

  • summary.json: コマンド引数、Gateway のバージョン、結果、失敗したアサーション、および成果物のパス。
  • sqlite-before.json および sqlite-after.json: 行数と、選択された証明用の行。
  • legacy-files.json: 従来ファイルの存在状況、mtime、サイズ、および各ファイルが変更されたかどうか。
  • gateway-log-scan.json: カーソル範囲、一致したログ行、および許可リストの判定。
  • events.jsonl: PR の証明コメントに適した、順序付きのステップ別観測結果。

PR の証明では、トランスクリプト全体や非公開メッセージの内容を貼り付けるのではなく、これらの成果物を要約する必要があります。

安全規則

  • ライブモードでは、Gateway の実行中に従来の JSONL を再インポートしてはなりません。
  • ライブモードでは、明示的に選択され、元に戻せる修復プローブを除き、証明用以外のセッションを変更してはなりません。
  • 破壊的または広範な移行ステップを実行するには、影響を受ける SQLite DB と従来のセッションディレクトリの新しいバックアップが必要です。
  • バックアップの範囲は、変更対象のエージェント DB/セッションディレクトリに限定し、ディスク使用量が際限なく増加することを避けるため、1 回の証明実行中は再利用する必要があります。
  • 呼び出し元が --keep-artifacts を渡さない限り、クリーンアップステップの完了後に、証明用セッション、証明用 JSONL、または変更された従来ファイルが残っていてはなりません。

合格結果

ライブ実行の合格は、Gateway が実際のエージェント駆動セッションフローを受け入れ、観測されたすべての正規状態が SQLite に存在し、従来のランタイムファイルが静止状態を保ち、測定期間中のログの健全性が維持されたことを意味します。ライブトラフィックの後も従来の JSONL との同等性が維持されるという意味ではありません。SQLite が正規ストアになると、ライブ環境で差異が生じることは想定内です。

Was this useful?
On this page

On this page