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

Get started

パス 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 に接続します。明示的な移行モードが後から追加されない限り、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 プロジェクションを検証します。
  • トランスクリプト ID: 同じマーカーが 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