setup

このリポジトリを一度だけ Veris に接続します。再実行時は、すでに完了している作業をスキップします。 セットアップでは、トランスポートの選択と設定を行います。選択したパスの準備、実行、証拠、クリーンアップの手順を実行方法に記録し、build と fix がトランスポートを再選択せずに再利用できるようにします。

セットアップでは、アプリケーションの実証済みの実行と、build と fix が利用する引き継ぎ情報の両方を用意します：.veris/twin.yaml、.veris/NOTES.md、.veris/setup.json（検証済みのプラグインセッションでは、twin.yaml の代わりにセッションメタデータを使用します）。Ledger ヘルパーは任意です。引き継ぎには、保存済みのコマンドそのものを正常に実行した結果を再利用してください。終了時に同じコマンドを繰り返さないでください。Git がない場合も同じファイルを作成し、コミットは省略します。

常に守る3つのルール：

• アプリケーションコードを変更してはいけません。また、アプリケーションをサンドボックスに向けてはいけません。唯一の例外はステップ3のダイレクトティアです。この場合、アプリは各ベンダーの URL を環境変数から読み込み、本番環境でも同じ変数が設定されています。それ以外では、コンテナーまたはホスト型ティアによってプロセスの外部からアプリのトラフィックをリダイレクトし、コードには本番環境のホスト名と認証情報を維持します。
• API キーを表示してはいけません。ログイン／ステータスの出力ではプラットフォームキーがマスクされますが、データの読み取りではベンダーの認証情報が完全な状態で返されることがあります。認証情報を含むデータは保護されたファイルにリダイレクトし、値をコマンド、レポート、ターミナル出力に含めないでください。
• 環境の作成、何かのインストール、またはサンドボックスの昇格を行う前に、許可を求めてください。

主な CLI は veris です。ホスト型ランナーには、それぞれ専用のプロバイダーコマンドがあります。veris <command> --help でフラグを確認できます。ターミナルなしで実行するため、返答として行うすべての操作はフラグで指定する必要があります。--yes は確認に使用します。 通常なら停止して確認を求めるコマンドは、代わりに実行を拒否し、必要なフラグを示します。 すべての get と list では --json を指定します。env get と env use ではテーブルに表示される短縮 ID を使用できます。--from には完全な ID が必要で、これは --json で表示されます。

認証情報を含むテーブルでは、最初に読み取る前に保存先を用意します： umask 077; CREDS_DIR=$(mktemp -d) を実行してから、データコマンドの出力を "$CREDS_DIR" 内のファイルにリダイレクトします。フィールド名は、生の行ではなく jq 'map(keys)' で確認します。値は表示せず、アプリケーションの認証情報ファイルまたは環境に直接抽出します。引き継ぎには変数名と抽出コマンドを記載し、抽出した値は記載しないでください。JSON セレクターのエラーには、拒否された値が引用される場合があります。そのため、パーサーの標準エラー出力も保護されたディレクトリにリダイレクトします。値を表示した後で保護されたファイルに移しても、情報漏えいを取り消すことはできません。

0. 現在のセッションを確認する

ローカル CLI、ログイン、Docker を確認する前に、利用可能なプラグインツールとランタイムコンテキストを確認します。これらから、このセッションがすでにプラグイン管理のサンドボックス内で実行されていると分かった場合は、../veris-reference/session.md を読み、実際に検証して、そのセットアップ手順に従います。そこで以下のプロビジョニング／実行／クリーンアップ手順を置き換えた後、共通のノートとメタデータの手順に合流します。ツインが関連付けられていないプラグインには、満たされていないプロバイダー前提条件があります。代替の環境をプロビジョニングしないでください。Docker または API キーがないことだけでは、このパスを選択しません。

1. マシンを確認する

git rev-parse --verify HEAD と git remote -v も確認します。Git の コミットがなくても、セットアップ、build、fix は実行できます。任意のソース記録ヘルパーで 比較対象のベースを固定する場合に限り、コミットが必要です。 PR 用のリモートがない場合は、変更内容をローカルに記録します。エンジニアから頼まれない限り、 Git を初期化したり、リモートを追加したりしないでください。以下のコミットに関する手順は、Git がある場合に適用します。

veris doctor を実行します。次の順番で、チェックごとに 1 行ずつ表示されます。バイナリのバージョン、 ログイン状態、コントロールプレーン、ゲートウェイモード、プレーンが提供するベンダーのホスト名、Docker、 トンネル用バイナリ（cloudflared）、証明書ファイル、プロジェクトファイル、環境、サンドボックスです。

該当する場合にのみ表示される行もあります。ゲートウェイモードとベンダーのホスト名を確認するには、 ログイン済みで、プレーンが応答している必要があります。そのため、新しいマシンでは表示されません。 環境の行は、プロジェクトファイルがある場合に必要です。稼働中のサンドボックスがある場合は、 その時計とコールバックの登録情報が追加されます。シェルの VERIS_API_KEY がプロファイル独自のキーを 上書きしている場合は、ログイン行の直後に警告が追加されます。

✓ は成功、! は確認事項、✗ は実行に失敗することを示します。Doctor 自体は何も変更しません。 → の行には、変更を加えるコマンドが示されます。チェックに失敗したものがあると、終了コード 1 で終了します。 --json を指定すると、同じチェック結果が標準出力に表示されます。

• command not found：veris がインストールされていません。この手順の他の項目ではインストールできません。 エンジニアに確認してから、そのマシンに該当する行を実行します。macOS と Linux：

  curl -LsSf https://raw.githubusercontent.com/veris-ai/veris-cli/main/scripts/install.sh | sh
  

  Windows：

  powershell -c "irm https://raw.githubusercontent.com/veris-ai/veris-cli/main/scripts/install.ps1 | iex"
  

  root 権限もパッケージマネージャーも必要ありません。macOS と Linux では、バイナリは ~/.local/bin に配置されます。そのため、再度 command not found が表示された場合は、 このディレクトリが PATH に含まれていません。その旨を伝えて、そこで作業を止めます。 veris doctor にバージョン行が表示されたら完了です。バージョンは 0.19.0 以降である必要があります。 それより古い CLI は、twin のコントロール URL が現在要求するキーを送信できず（その場合、 veris sandbox コマンドは 401 invalid or missing API key で失敗します）、または twin ごとの reset と services operations の動詞がありません。インストール行を再実行してアップグレードします。

• ✗ Not logged in：veris login を実行します。ペアリングコードとコンソールへのリンクが表示されます。 両方をエンジニアに提示し、ブラウザーでペアリングを承認するよう伝えます。その後は待ちます。 ペアリングが承認されるとコマンドは自動的に終了し、キーがプロファイルに保存されます。 --no-browser を指定すると、ブラウザーを開かずにリンクが表示されます。別のコントロールプレーンを使う場合： veris login --profile dev --api-base <url>。CI ではペアリングを承認できないため、 veris login --key-stdin を実行して、既存のキーを標準入力から読み込みます。 veris whoami では、コマンドが使用するキー、組織、プレーンを確認できます。

• Docker に関する !：ステップ 3 のコンテナ層には、稼働中のデーモンが必要です。 エンジニアがホスト型実行を依頼した場合は、代わりにその層のゲートウェイとプロバイダーの前提条件を確認します。 それ以外の場合は、Docker を起動するよう依頼します。このマシンでデーモンを実行できない場合は、 ステップ 3 のホスト型層を利用します。テスト対象のコードに対して、--image なしで実行する方法に 決してフォールバックしないでください。ホスト型層のゲートウェイ確認については、 ../veris-reference/hosted.md を参照してください。

• コントロールプレーンの no such host を示す ✗、またはエンジニアが両方とも動作すると言っているマシンでの docker.sock に対する permission denied を示す !：サンドボックス内で実行されています。 ../veris-reference/troubleshooting.md の エージェントがサンドボックス内で実行されている場合を参照してください。そこで作業を止めます。

• 新しいリポジトリでプロジェクトファイルまたはサンドボックスがないことを示す ! は、想定どおりの状態であり、 問題ではありません。

• それ以外の ✗：該当する行と修正方法を伝えて、そこで作業を止めます。

2. コードが呼び出すものを確認します

README ではなく、コードを読んでください。SDK のインポート、ホスト名、ベース URL の設定を確認します。テスト対象の経路にあるベンダーのホスト名をすべて列挙してください。

veris services はカタログです。各ツインについて、ツインの名前、何を代替するのか、その URL がアプリに渡される際に使われる変数、プロキシがそのツイン用にインターセプトするベンダーのホスト名を 1 行ずつ表示します。--services に指定するのは名前です。

name (+issuer) と表示されるツインは、ファミリーのイシュアーを経由してサインインします。コントロールプレーンは、そのツインを保持する各サンドボックスにイシュアーをデプロイします。たとえば、google-calendar と一緒に google-identity が配置されます。--services に指定するのは基本名であり、イシュアーも指定しても何も変わりません。そのため、環境で指定していないツインがサンドボックスに含まれることがあり、veris status ではそれぞれに + が付きます。ツインもこのマークも、修正が必要なエラーではありません。

ホスト名がないツインは、2 つの理由のいずれかでインターセプトされません。データプレーンである可能性があります。この場合、ホスト名のリダイレクトではなく、実行時にアプリに渡される URL を使って、アプリが直接接続します。データベースがよくある例です。あるいは、このコントロールプレーンがまだそのツイン用のホスト名を提供していない可能性もあります。veris doctor の vendor-hostnames の行には、この状態にあるツインがすべて表示されます。該当するのは postgres と yente だけです。アプリ自体が必要とするデータプレーン（独自のデータベースやセルフホストのサービスなど）も列挙してください。これらがないと、必要とするテストスイートは失敗します。

ベンダーではなく、ホスト名を照合してください。ベンダーが複数のホストを使うこともあれば、ツインがその一部しかカバーしないこともあります。Stripe のツインが応答するのは api.stripe.com であり、files と meter-events のホストはカバーされません。同じホスト名に複数のツインが応答することもあります。たとえば、3 つの Google ツインはすべて www.googleapis.com を列挙しています。サンドボックスはパスに基づいて振り分けるため、コードが呼び出すパスをカバーするツインをすべて含めてください。

対応するツインがないホスト名は制約事項です。ステップ 7 に記録し、モックしないでください。

このコマンドで指定した名前は、開始時のリストです。最終リストをエンジニアに示し、作成する前に確認を求めてください。

3. ティアを選び、イメージをビルドする

テストの実行方法は3つあり、それぞれをティアと呼びます。何かをビルドする前に決めてください。リモートで実行する明示的な依頼があれば、Docker が動作する場合でも、以下のホステッドティアの説明に従います。それ以外の場合は、コードに基づくダイレクトティアの判定基準を適用し、その後 veris doctor を使ってコンテナ実行とホステッド実行のどちらにするかを選びます。

テスト対象の経路上にあるすべてのベンダー呼び出しを確認してください。それぞれの URL が、アプリがすでに読み込んでいる環境変数から構成され、本番環境で同じ変数に実際のホスト名がデフォルト値として設定されている場合、それらの変数を設定する方法が、すでに用意されているコードパスです。プロキシは不要です。これがダイレクトティアです。

ダイレクトティアの場合は、 ../veris-reference/direct.md に進み、そこに記載された判定基準と設定方法に従ってから、手順7でここに戻ってください。この手順の残りと手順5、6はスキップします。イメージも、動作確認の実行も必要ありません。手順4の環境ルールは、その設定によって用意される環境にも適用されます。まず veris env list --json を読み、すべてのサービスがすでにそろっているものを再利用してください。手順4のプロキシフラグは適用されません。

アプリ内、またはアプリが呼び出す SDK 内にハードコードされたベンダーホスト名が1つでもあれば、コンテナティアまたはホステッドティアを使ってリダイレクトする必要があります。アプリが登録するベンダーのベース URL についても、対応するツインが環境変数のヒントを公開していない場合は同様です。ただし、テスト対象の経路からそのベース URL に到達しない場合は除きます。ダイレクトティアでは、そのようなベース URL は実際のベンダーへの通信を続け、捕捉されません。veris services を使うとすべてのツインのヒント変数がわかります。また、サンドボックスは不要なので、実行を始める前にヒントが欠けていないか確認してください。

コンテナティアは veris run --image を使い、プロキシとともにコンテナ内でテストを実行します。Docker が利用でき、リダイレクトが必要なコードでは、これがデフォルトです。すべてのランタイムに対応し、SDK にバンドルされた証明書にもパッチを適用できます。

ホステッドティアでは、送信トラフィックのプロキシとしてツインのゲートウェイを使うリモートボックスでテストを実行します。エンジニアがリモート実行を依頼した場合、またはリダイレクトが必要なコードで veris doctor が Docker を利用できず、この環境では起動できないと報告した場合に選んでください。ホステッド実行の明示的な依頼がない場合は、まず上記のダイレクトティアの判定基準を適用します。この場合は ../veris-reference/hosted.md に進み、判定基準を確認して、選んだプロバイダーの「必要なもの」に関する手順に従ってください。その後、イメージなしで手順4に戻ります。--image は指定せず、proxy.image が未設定のままになるようにしてください。手順5は変更ありません。手順6ではプロバイダーの実行手順とホステッド実行のレシートルールに従います。この手順の残りはスキップしてください。

テストを実行できるイメージならどれでも使えます。リポジトリ独自のテスト用イメージや Dockerfile のステージ、またはリポジトリをマウントした標準的なツールチェーンイメージを使えます。今すぐビルドしてください。手順4でそのタグを記録します。Veris 固有のものをイメージに入れてはいけません。キー、証明書、プロキシ設定は含めないでください。イメージの派生に実作業が必要だった場合は、ルートに Dockerfile.veris として保存し、ビルドタグを示すコメントを付けてください。コンテナ内でテストをまったく実行できない場合は、作業を中止してエンジニアに伝えてください。完了条件は docker image inspect <tag> が成功することです。

手順6の動作確認で、アプリがベンダーに到達する前に失敗した場合（インタープリターがモジュールを見つけられない、インポートを解決できない、バイナリが PATH にないなど）は、イメージを修正して再ビルドしてください。実行コマンドに -e PYTHONPATH=… を加えたり、イメージ内のファイルをマウントで上書きしたりして、実行コマンド側で修正してはいけません。.veris/NOTES.md には、ビルド済みのイメージに対して動作するコマンドが記録され、以降のすべての実行でその回避策が引き継がれるためです。よくある原因は、ソースをイメージに入れる前にプロジェクトをインストールしていることです。uv を使う場合：

FROM ghcr.io/astral-sh/uv:0.9-python3.12-bookworm-slim
WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-install-project
COPY src ./src
COPY tests ./tests
RUN uv sync --frozen

依存関係を先にインストールしてキャッシュできるようにし、ソースがそろってから最後にプロジェクトをインストールします。

4. 環境を作成する

veris env create <project-name> --services stripe,asana --ttl 60 \
  --command '<the smallest test command that calls a vendor>' \
  --image <tag> --require-service stripe --default

不明なサービス名は拒否され、カタログが表示されます。名前は veris services から指定してください。

上記の --ttl 60 は選択肢であり、必須ではありません。--ttl を省略すると記録されず、コントロールプレーン独自のデフォルトが適用されます。サーバーが許可する範囲外の数値は拒否され、拒否時には有効範囲が示されます。イメージのプル、ビルド、読み戻しにかかる時間を見込んでください。veris up の前にワークロードイメージをプルしてください。実行中のサンドボックスの有効期間は延長できません。期限切れやティアダウンの前に証拠を保存してください。

--boot、--snapshot、--data、--command も同様です。指定したものだけが記録され、省略したものは何も書き込まれません。そのため、サンドボックスはバンドルを起動し、データをシードせず、veris run は -- の後にあるコマンドを受け取ります。ターミナルを使わずに指定が必要なのは名前と --services（または --from）だけです。したがって、フラグは質問に答えるためではなく、記録させたいものがある場合に指定してください。唯一の組み合わせは --boot snapshot で、--snapshot ID|NAME がなければ拒否されます。

環境を作成する前に、veris env list --json を実行し、サーバー上にすでにあるすべての環境の名前とサービスを確認してください。環境を採用するのは、それがこのプロジェクトのものである場合に限ります。サービスがあなたのリストと完全に一致するか、サーバー名がプロジェクト名である必要があります。 その場合は、同じ残りのフラグを指定して veris env create <project-name> --from <full id> を実行します。それ以外の場合は、既存の環境に必要なサービスがすべて含まれていても、プロジェクト名で新しい環境を作成してください。スーパーセットの環境では、コードから呼び出されないサービスも起動され、料金が発生します。また、別のプロジェクトの環境はそのプロジェクトと共有されているため、どちらかが実行した env delete --server や baseline promote は両方に反映されます。採用する場合は、作成前に確認する質問で、サーバー上の環境名と ID を示し、共有環境であることを伝えてください。--from と --services は併用できないため、採用した環境はサーバーのサービスリストを引き継ぎ、この操作では拡張できません。サーバー上で名前は一意ではないため、使用した ID を明記してください。

環境を作成する前に、すべてのエントリーポイントに必要なサービスの全体を確認してください。サービスが不足している場合は、新しい環境が必要です。ローカルのデフォルトを変更しても、サービスは追加されません。

名前とサービスはサーバーに送られます。それ以外はすべて、環境の設定として .veris/twin.yaml に書き込まれます。そこには、指定した場合の TTL、起動元、データファイル、run.command としてのテストコマンド、およびプロキシフラグから作成される proxy: ブロックが含まれます。

environments:
  <project-name>:
    proxy:
      image: <tag>
      require_service: [stripe]

.veris/twin.yaml をコミットしてください。veris run は両方の設定をそこから読み込むため、日常的に実行するコマンドにどちらのフラグも必要ありません。--require-callback、--expose <port>、--strict も同じブロックに記録されます。

複数のエントリーポイントがある場合は、デフォルトを1つにし、各フローの完全なコマンドを、各フローの --require-service とコールバック関連フラグも含めて NOTES に記録してください。 require_service はリストであり、明示的な --require-service フラグを指定すると、その実行ではリストが置き換えられます。-- の後に別のコマンドを指定しても、要件は置き換わりません。 Webhook フローと受信先のないフローのようにデフォルトが両立しない場合は、各フロー固有のフラグを指定して veris env create <flow> --from <full-id> を実行し、名前を付けてローカルエントリーを個別に記録します。veris run --env <flow> でいずれかを選択してください。 veris env get <flow> で設定を読み戻してください。 採用すると、新しいサーバー環境を作成せずにローカルのデフォルトが書き込まれます。 デフォルトが成功したからといって、別のエントリーポイントも検証済みだと主張しないでください。

マウント、-e 変数、--patch-bundled-cas、--cap-add はファイル内に対応するキーがありません。 これらは手順7で .veris/NOTES.md に記録する veris run のコマンド行に指定します。--data で指定しない限り、データファイルはありません。また、このコマンドは .gitignore に .veris/twin.local.yaml も追加します。このファイルはマシンごとに異なるため、コミットしません。veris env get に各設定、その設定元、サーバー上の記録が表示されれば完了です。

5. サンドボックスを起動する

veris up を実行します。環境のサンドボックスを作成し、そのフォルダー用に ID をすぐに記録します。その後、コントロールプレーンがサンドボックスの準備完了を報告し、すべてのツインが応答するまで待ちます。環境のデータファイルを追加し、各ツインの URL と、その URL がアプリに渡される変数を表示します。環境で名前が指定されていないツインは、プラットフォームが追加したサインイン発行者（ステップ 2）です。そのヒントの横の行に、その旨が表示されます。

終了コード 0 で終了し、ツインが一覧表示されたら完了です。veris status を実行すると、いつでもサンドボックスの状態、起動元、期限、および各ツインのステータス、環境変数のヒント、URL、テーブル件数を確認できます。サンドボックスは TTL の期間存続し、その後消滅します。

失敗した場合は、終了コードを確認してください。サンドボックスの起動に失敗した場合は、理由とともに終了コード 1 になります。待機時間が尽きた時点でサンドボックスのプロビジョニングが続いている場合は、終了コード 4 になります。デフォルトの待機時間は 5 分です。--timeout 10m を指定すると、より長く待機できます。終了コード 4 の場合、サンドボックスは保持され、その後起動する可能性があるため、後で veris status を確認してください。ツインが拒否したデータファイルがある場合は、サンドボックスを保持したまま終了コード 1 になります。ファイルを修正してから、veris sandbox data add <file> で追加してください。

6. 動作を確認する

veris run --patch-bundled-cas -- <the smallest test that calls the vendor>

docker run の場合と同様に、コマンドに必要なものを追加します。

ホステッドティアでは veris run はありません。プロビジョニング済みのボックスでテストコマンドを実行するには、プロバイダーの手順を使用してください。そのレシートは、ウォーターマーク以降に読み取られたツインのトレースです。../veris-reference/hosted.md の プロバイダーの手順 と レシート を参照してください。完了条件もそこに記載されています。このステップの残りはコンテナティア向けです。ステップ 7 から再開してください。

• イメージにコードが含まれていない場合は、イメージがコードを想定している場所にリポジトリをマウントするために -v を指定します。docker image inspect <tag> でイメージの WORKDIR を確認できます。
• アプリが読み込む認証情報ディレクトリには、-v <dir>:/run/keys:ro -e KEYS_DIR=/run/keys を指定します。入力する前に、ツインの Credentials セクションを確認してください。必要に応じて、公開されている合成認証情報または発行者が提供するトークンを使用します。許容モードでも、でっち上げたトークンが有効になるわけではありません。受け渡し方法については、以下の認証ガイダンスを参照してください。
• テストで必要な変数には -e を指定します。

マウントするのは、リポジトリ、依存関係キャッシュ、認証情報ディレクトリだけにしてください。

--patch-bundled-cas は、プロキシの証明書を認識対象の SDK 同梱 CA ファイルすべてに追加します。対象は certifi、botocore、stripe、httplib2 です。Stripe、botocore、httplib2 では必要です。イメージにそのようなファイルが含まれていない場合、追加のコストはかかりません。--receipt <file> を指定すると、レシートを JSON としてそのファイルに書き込み、標準出力には出力しません。

実行すると、ツインごとに 2 つの件数が表示されます。

veris: the sandbox received 6 request(s):          ← what the proxy saw leave the app
  stripe   6
veris: the sandbox recorded 6 request(s) since the watermark:   ← what the twin logged
  stripe   6
veris: ✓ required stripe ≥1: saw 6   ✓ ledgers agree (6 = 6)

この 2 つの件数は、実行における 2 つの台帳です。件数と、その下に表示される判定行が実行のレシートです。

サンドボックスの合計は、プロキシの合計を上回ることがあります。プロダクトツインが、サンドボックス内で兄弟にあたる発行者を使ってトークンを検証する場合があるためです。同時に発生したトラフィックが加算される場合もあります。不一致を診断する前に、ツインごとのトレースを比較してください。一致しているだけではアプリケーションの成功を証明できません。また、差異がある場合はトレースから説明できる必要があります。

実行が終了コード 0 で終了し、要件を満たし、レシートと読み戻し結果から意図したアプリケーションのフローによるトラフィックを確認できたら完了です。 データプレーンがサンドボックスの台帳にのみ現れる場合があります。内部の発行者との通信だけでは、アプリが実行された証明にはなりません。 カウントが 0 より大きいだけでは不十分です。両方のカウントが 0 より大きくても実行が失敗した場合は、アプリケーションエラーと未達の要件を確認してください。ベンダーによる拒否、コールバックの欠落、後続のアプリケーションアサーションは、いずれもトラフィック到着後に失敗することがあります。veris sandbox data get <twin> auth で twin の認証モードを確認してください。認証情報の検証が許容的でも、サービス提供元ファミリーの発行元が求めるトークンの来歴要件はなくなりません。Google Calendar などの製品 twin では、引き続き発行元が発行したトークンが必要です。 enforced の twin は、認証情報を既知の状態と照合します。 veris sandbox services manual <twin> --raw で、その twin の Credentials セクションを確認してください。公開された認証情報の保存先が記載されています。テーブル表示では長いセルが切り詰められるため、veris sandbox data get <twin> <table> --json を使用してください。その JSON を、リポジトリ外の所有者のみがアクセスできる一時ディレクトリ（umask 077 を設定したうえで mktemp -d を使用）に新しいファイルとしてリダイレクトし、アプリに必要なフィールドだけを環境変数または読み取り専用の認証情報ファイルに抽出してください。値を表示したり、証跡に保存したりしないでください。また、実行後に一時的な認証情報ファイルを削除してください。ツールが認証情報へのアクセスを拒否した場合は、その権限の問題を解決してください。拒否を回避するために別の経路を使ってはいけません。 次に、twin が受け入れる認証情報をアプリに渡すか、認証情報を持っている twin を使って配線を証明してください。いずれの場合も、手順 7 の 認証情報とバージョン に記録します。

その後、完全なコマンドを手順 7 の .veris/NOTES.md に記録してください。twin.yaml に記載するのは、イメージ、必須の twin、そして -- の後に続くコマンドだけです。実行方法 に記載できるのは、レシートが生成されたマウントだけです。そのため、後続のタスクで必要になるマウント（イメージに焼き込まれたコピーの代わりに使うリポジトリ、フィクスチャツリーなど）をこの実行で使っていない場合は、そのマウントもここで証明してください。

最終的に成功したコマンドと必須の twin は、手順 4 に記録したものと異なる場合があります。異なる場合は、veris env create <name> --from <full id> --force で再記録してください。エントリにすでにあるフラグはすべて引き継いでください。修正した --command と --require-service に加え、同じ --image と --default、またエントリに記録されている場合は同じ --ttl、--boot、--data も指定します。エントリはマージされず置き換えられるため、指定しなかったフラグは削除されます。--require-service を省略すると、その後の実行では twin のアサーションが行われず、空のレシートで成功してしまいます。--from を付けないと、サーバー上に 2 つ目の環境も作成されます。その後、veris env get を再実行し、手順 4 の完了条件をもう一度確認してください。

自分で実行した veris sandbox の読み取りは、実行の合計には含まれません。実行開始時にウォーターマークが設定され、sandbox がその後に記録した内容だけがカウントされます。実行中に行った /veris/* の読み取りは、別の control-plane (/veris/*) の行に表示され、カウント対象外と示されます。

どちらかのカウントが条件を満たせばチェックは合格です。片方だけで ✓ と判定された場合、その行に (engine; …) または (sandbox ledger; …) のどちらで判定したかが示されます。終了コード 4 は、どちらのカウントでもチェックを確定できず、結果が不明であることを意味します。再実行してください。同じ結果が繰り返される場合は、veris status を確認して報告してください。

インバウンドフローでは、--require-service に加えて --expose <port> と --require-callback <path> を使用してください。登録、署名、配信の読み戻しについては、../veris-reference/webhooks.md に従ってください。受信側独自のアサーションを証明してください。決済が成功しても、Webhook の受信が証明されたことにはなりません。

終了コード 3 は、要件が満たされなかったことを意味します。コールバックが示されている場合は、アウトバウンドの配線を変更する前に Webhook のリファレンスに従ってください。サービス要件が満たされていない場合は、次を確認してください。

1. テストがベンダーを呼び出していません。インプロセスモックがまだ有効か、フィルターによって呼び出しがスキップされています。ベンダーを呼び出すテストを選んでください。
2. ベンダーのホスト名が、環境内のツインが応答するホスト名に含まれていません。コード内のホスト名を veris services および veris env get の結果と照合してください。
3. SDK が証明書を拒否しました。CERTIFICATE_VERIFY_FAILED、SSLError、またはベンダーホストへの接続エラーが発生しています。あるホストがすべてのハンドシェイクを拒否した場合、実行時にホスト名と Next: の手順を示す行が出力されます。その手順に従ってください。 --patch-bundled-cas はバンドルされた CA ファイルを修正します。コンテナーでの実行（--image）では、JVM トラストストアが自動的に注入されます。--java-truststore はホストティアでのみ使用でき、--image とは併用できません。証明書をピン留めする SDK は修正できません。停止して報告してください。詳細な手順は ../veris-reference/troubleshooting.md の SDK がプロキシの証明書を拒否する場合を参照してください。
4. ツインが、データベースや Yente のようなセルフホスト型サービスなど、ホスト名を持たないデータプレーンです。これらはプロキシされません。実行時に、veris up が表示する変数を使ってツインの URL をアプリに渡し、その旨を表示します。 veris: yente: not proxied; handed YENTE_API_BASE=…。アプリはこの変数を読み取る必要があり、同じ変数を指定する独自の -e がある場合はそちらが優先されます。データプレーンへのトラフィックはサンドボックスのカウントにのみ表示され、プロキシのカウントには表示されません。また、判定には (sandbox ledger; not proxied) と表示されます。これは想定どおりです。
5. 通常のベンダーツインの場合、コントロールプレーンがベンダーホスト名を提供していません。この場合、実行時に、項目 4 と同じ方法でツインの URL をアプリに渡し、同じ not proxied の行を表示します。ただし、ここではこの行は想定外です。veris doctor のベンダーホスト名の行には、プレーンがホスト名を提供していないツインがすべて表示されます。このリストにベンダーツインがあることが原因です。完了条件： doctor に表示されるのが postgres と yente のデータプレーンのみであること、または実行時に --route <twin>=<host> でホスト名が指定されていること。
6. アプリが、実行によって起動されていないプロセス（compose のサイドカー）からベンダーにアクセスしています：../veris-reference/troubleshooting.md。

exit 3 を解消するために、テストのベンダー呼び出しやベース URL を変更しないでください。

7. 測定した内容を記録する

.veris/NOTES.mdを作成してコミットします。buildとfixは最初にこのファイルを読むため、後続のタスクで再度調べることになる内容はここに記録します。実施した内容をもとに記入してください。マニュアル、認証モード、検証実行です。マニュアルは veris sandbox services manual <twin> --rawです。--rawを指定するとMarkdownが標準出力に出力され、指定しない場合はマニュアルが標準エラーに表示されます。認証モードは veris sandbox data get <twin> authです。

以下の見出しを使います。それぞれの見出しの下に、測定済みまたは未測定と記入してください。空の見出しも、それ自体が調査結果です。IDと照合およびエラーと重複排除キーは例外です。正常系を1回実行しても何も集約されず、マニュアルにもレコードの識別方法は記載されていないため、セットアップ時にはどちらも未測定と記入するのが想定されています。初回利用時にbuildまたはfixが、../veris-reference/twin.mdに記載された読み取りによってこれらを埋めます。

• 実行方法。 選択した実行方法について、動作確認済みの準備、起動、再接続の手順、必要なサービス、ソースのビルドコマンド、アプリケーションのテストコマンドを記録します。影響を受けるテストの選択方法も含めてください。有効期限の確認方法と、必要に応じて現在のサンドボックスバインディング、URL、認証情報を更新する方法も記録します。セットアップ時の古いIDは観測結果です。実行時のレシートまたはトレースの収集方法も、選択した方法で必要な場合は実行前後の読み取りを含めて記録します。ライフサイクルの管理者と、そのクリーンアップまたは変更引き継ぎの手順を明記します。レシート、終了コード、接続エラーの解釈方法について、その実行方法のリファレンスへのリンクを記載します。 コンテナで実行する場合は、レシートファイル、マウント、変数を含む、検証済みの完全なveris run行を記録します。実際のパスを使ってください。外部マウントを使う場合は、その内容と作成方法を説明します。同じキャッシュマウントを使い、空のディレクトリから依存関係キャッシュを準備できることを検証します。オフラインビルドでは空のキャッシュを作成できません。イメージとビルドコマンド、秘密情報を保存せずにアプリケーションへ認証情報を渡す方法を記録します。 直接実行する場合は、変数の初期化とアプリケーションのコマンドに加えて、サービスごとのウォーターマークと実行後のトレース読み取りをdirect.mdに記載されたとおりに記録します。 ホスト型で実行する場合は、hosted.mdに記載された、プロバイダーの準備、実行、終了のコマンドと証拠の手順を記録します。 プラグイン管理のセッションを使う場合は、session.mdに記載された、アプリケーションのコマンド、プロバイダーのツール、証拠と引き継ぎの手順を記録します。 この手順を確立した既存の証拠をそのまま残してください。記録のためにアプリケーションを追加で実行する必要はありません。
• ツインで表現できないもの。 ツインのないホスト名、データプレーンツイン、スモークテストで実行できなかったもの。
• IDと照合。 ベンダーが同一レコードとして扱うフィールドと、その過程で行われる正規化、切り詰め、結合。
• エラーと重複排除キー。 どの失敗が冪等性キーに紐づいて再利用時に再生され、どの失敗ではキーが解放されたままになるか。リトライを行う修正は、この答えを前提とします。
• 認証情報とバージョン。 各ツインが受け付けるキーの形式、固定されたAPIバージョン、仮の値で通用するもの。
• リポジトリ独自のテストがベンダーに到達しない箇所。 インプロセスでモックするスイートは、レシートが空でも成功します。ほとんどのリポジトリではベンダー向けテストがレシートを生成できないため、それらのテストについて段落を書くより、レシートを生成できる唯一のテストを挙げる方が価値があります。
• ツインが誤っていた点。

8. ファイル（アプリがファイルを扱う場合のみ）

アプリがファイルをアップロードまたは読み込む場合に限り、この手順を行います。Drive、Dropbox、添付ファイルなどが該当します。 行だけの状態はタスクごとに簡単にシードできるため、ベースラインは不要であることを明記します。

アプリがファイルを扱う場合でも、シードするものがないことがあります。フィクスチャがない場合や、ファイル対応のツインが受け付ける認証情報がない場合です。その場合は ツインで表現できないこと にその旨を記載して、先に進みます。中途半端にシードしたベースラインは、ないよりも悪いものです。

それ以外の場合は、ファイルを一度シードし、以降のすべてのサンドボックスで使えるようにします。手順は ../veris-reference/state.md の ファイル にあります。ファイルを読み戻し、各行の SHA-256 がローカルファイルと一致することを確認します。エンジニアに確認してから、veris baseline promote を実行します。このコマンドは、このフォルダーのサンドボックスをキャプチャしてスナップショットとして保存し、そのスナップショットを環境のデフォルトに設定したあと、元のサンドボックスを削除します。--keep-source を指定すると、そのサンドボックスは凍結され、サニタイズされた状態で保持されます。promote は、そのサンドボックスに対して行う最後の操作です。veris baseline get にピンが表示されれば完了です。以降の veris up はすべてその状態から開始し、セットアップで promote を行うのはここだけです。サンドボックスの内容を .veris/NOTES.md に記録します。所有者、パス、ハッシュを記載してください。

9. ビルド情報と成果物の設定を保存する

.veris/setup.json をリポジトリのビルド定義と同期させます。有効な既存情報は再利用し、ビルドや作業コマンドが変わった場合は更新します。

{"source_roots": ["api/app"], "build_command": "make build", "build_outputs": ["dist"]}

source_roots は、本番用ソースコードの場所です。build_command と build_outputs には、リポジトリ独自のビルドコマンドと、そのビルドが出力するディレクトリを指定します。これらがないと、後続のタスクで新しいビルドと古いビルドを判別できず、推測する代わりにその旨を示すことになります。アプリケーションがテスト用イメージに組み込まれている場合は、build_command でそのイメージをビルドし、build_outputs は [] にします。イメージタグは .veris/NOTES.md に記載してください。標準のツールチェーンイメージでマウントしたソースをコンパイルする場合は、ソースとキャッシュのマウントを含むコンパイルコマンドと、リポジトリに書き戻される出力ディレクトリ（例：Maven の target）を記録します。実際に検証したコマンドをそのまま使ってください。インタープリター型言語ではビルドディレクトリが出力されないことも多く、その場合は [] が正しい値です。テスト対象のコードと関係のないビルドを指定しないでください。

既存の artifact_policy と、エンジニアが選択した無視・保持の設定は維持してください。設定が記録されていない場合は pr-body を使用します。タスクごとに再確認する必要はありません。

• pr-body：変更の説明に、簡潔な検証サマリーと、選択した機密情報を削除済みの証拠を含めます。タスクの成果物はローカルに保存されます。
• local：成果物はディスク上に保持されます。リモートセッションでは、サンドボックスの有効期限後も保持するために、明示的なエクスポートが必要です。
• commit：選択した機密情報を削除済みのタスク成果物・証拠を Git に含めます。

pr-body または local を使う新しいセットアップでは、不足している以下の無視エントリーを追加します。既存のセットアップでは、意図的な選択を維持してください。.veris/ 全体を無視しないでください。twin.yaml と NOTES.md も隠れてしまいます。

.veris/bin/
.veris/tasks/
.veris/evidence/

commit の場合は .veris/bin/ を無視したままにし、選択したタスク・証拠のパスを追跡可能にします。無視されていないという理由だけで、タスク成果物をコミットしないでください。

監査用のオプションヘルパー

エンジニアから監査を依頼された場合、または調査で記録・台帳ヘルパーが必要な場合を除き、ステージングは省略します。このインストール環境の veris-reference/scripts/ から、必要な record.sh／ledger.sh を .veris/bin/ にコピーします。このスキルを基にパスを特定してください。OpenCode では、verisSkill を使ってインストール済みスクリプトを読み込み、ステージング後に SHA-256 を検証します。ホスト側の apply_patch ではなく、プロバイダーのリモート書き込みツールか リモート bash の代替手段を使用してください。アップグレード後にステージング済みヘルパーを使用する前に、その内容を検証するか更新します。通常のセットアップ・ビルド・修正は、コピーがなくても実行できます。

10. 完了

CLI 管理のセットアップでは、インストール済みプラグインの veris-reference/scripts/check-setup.py を、絶対パスを指定して Python 3 で実行し、--project でこのリポジトリを指定します。このスクリプトは、プロジェクトのコードを実行せずに、引き継ぎファイルとビルドメタデータを確認します。報告された不足があれば修正します。Python 3 が利用できない場合は、ステップ 7 と 9 の同じファイルとメタデータを手動で確認してください。この確認だけのためにランタイムをインストールしないでください。これは構造上の確認であり、ステップ 6 のアプリケーション検証の代わりにはなりません。保存済みの How to run コマンドを正確に実行して成功していれば、その要件を満たします。veris env get <flow> --json で読み戻したフロー設定も再利用してください。保存済みのレシピが変更された場合、または未テストの必須セットアップ条件が残っている場合にのみ、再実行してください。たとえば、ウォームキャッシュでの実行では、コールドキャッシュを前提とするレシピを検証したことにはなりません。未テストのレシピや、読み戻しが不足している箇所は、正確に記載してください。プラグインセッションでは、session.md に記載されている同等のセッションメタデータと引き継ぎを使用します。CLI 設定ファイルやローカルチェッカーの実行は不要です。

How to run は新しいセッションとして確認してください。一時的な認証情報ファイルと外部キャッシュを再作成するコマンドを含め、認証情報の値や未定義のシェル変数は含めないでください。依頼された場合は、RUN.md と COVERAGE.md を引き継ぎに添付します。これらは .veris/NOTES.md や .veris/setup.json の代わりにはなりません。

クリーンアップの前に、失敗した検証実行の後も含め、機密情報を除去した証拠を保存してください。veris down --yes は、このフォルダーのサンドボックスを削除します。ステップ 8 で promote を実行した後は、削除するものは残っていません。ホスト型ティアでは、まずプロバイダーのティアダウンコマンドを使ってホスト型ボックスを削除してください（../veris-reference/hosted.md）。コミットすべきファイルとして、.veris/twin.yaml、.veris/NOTES.md、.veris/setup.json、作成した場合は Dockerfile.veris をエンジニアに伝えてください。ステップ 6 のレシート行を報告してください。ダイレクトティアとホスト型ティアでは、代わりにその役割を果たしたトレースエントリーを報告してください。以降の作業は build または fix が引き継ぎます。新たな場所へリポジトリのコードを送信する前に、許可を求めてください。