convex-self-heal

ゲート付き本番環境セルフヒーリングループ

Sentry／Datadog／Vercel は、エラーから調査、PR のドラフト作成まで進められますが、バックエンドを不透明なものとして扱い、未検証の差分を残して人間によるマージのゲートで止まります。Convex には、彼らにはできないことが可能です。エラー行がユーザー自身のデプロイ環境にあり、そのデプロイ環境のプレビューで修正をリハーサルできるため、誰かがレビューする前に、プラットフォームが実際の不変条件に照らして修正を検証します。この機能は、構成要素をつなぐ仕上げとなるもので、sentinel（捕捉）→ findings bus（診断）→ fixers（修復）→ migrate-rehearse／tsc／probe（検証）→ 人間による PR（判断）→ deploy-guard（昇格）を連携させます。マージボタンは人間が押します。修正が機能することの証明まで、すべてを機械が行います。

ワークフロー

1. GUARD：deploy-guard — このループは本番環境を読み取り、本番環境への変更を提案します。デプロイを分類して告知し、ループの対象範囲について事前に継続的な同意を得てください（自動で準備してよい修正の種類と、必ず保留すべき修正の種類を定めます）。自動マージは絶対に行いません。人間によるマージが、固定された境界です。
2. CAPTURE：sentinel が必要です（ユーザー自身のデプロイ環境で発生した本番エラーを、書き込み時に編集・秘匿します）。存在しない場合は、インストールを提案して停止してください。捕捉なしに修復できるものはありません。
3. 新規／再発エラーの TRIAGE：公式 MCP 経由で取得します（sentinel テーブルに対する data/run-once-query、またはモニターの prod_error イベント）。分類します。一時的なもの（再試行／無視。単発のネットワーク障害について PR を作成してはいけません）、設定（環境変数／シークレット。env に引き渡し、シークレットを推測しない）、またはコード／スキーマの不具合（続行）です。
4. findings bus で ROOT-CAUSE を特定：該当する関数に関連する監査を実行します。convex-insights（失敗したリクエストとスタック）、convex-advisor（読み取り制限／OCC が原因の場合）、convex-reviewer／convex-authz（ロジック／認可の不具合の場合）を使用します。証拠（スタックと再現用の入力）および fixCapability を含むバスの指摘事項を作成します。根本原因が不明確な場合は、停止して報告してください。誤った修正は、未解決のエラーよりも深刻です。
5. 修復：指摘事項の fixCapability（convex-authz、reviewer fixers、パフォーマンス向けの convex-expert）を使い、ブランチ上で修正します。本番環境に直接修正を加えてはいけません。
6. 提案する前に、バックエンド固有の不変条件に照らして検証します（ここが差別化要因です。該当する項目を省略してはいけません）。 (a) tsc --noEmit がクリーンであること。 (b) 修正がスキーマ／データに関わる場合は、本番スナップショットをシードしたプレビュー上で migrate-rehearse を実行します。スキーマ適合性ゲートは、実際に近い形のデータで合格する必要があります。 (c) 再現してから解消を確認します。エラーの引き金となった入力を修正後のコードに対して再生し（convex-test のケース、またはプレビュー上での MCP 実行）、失敗が再発しないことを確認します。 (d) リグレッションがないこと：指摘事項が解消され、変更対象の関数に新たなバスの指摘事項が追加されていないこと。 該当する検証のいずれかに失敗した修正は、提案してはいけません。失敗した内容とともに「試行したが検証できなかった」と報告します。
7. 提案のみとし、マージはしません。修正、検証の証拠（tsc の結果、リハーサルの結果、再現して解消したことの確認）、元のエラーと指摘事項、および可逆性に関する注記を含む PR（またはレビュー用の差分）を作成します。変更の分類ラベルを付けます。人間がレビューしてマージします。
8. マージ後、deploy-guard の本番環境への同意を得て PROMOTE します。デプロイ後、sentinel テーブルと logs（失敗）を再確認し、エラーのシグネチャが再発しなくなったことを確認します。この目的で insights を使ってはいけません。insights が追跡するのは OCC／読み取り制限に関するパフォーマンスイベントだけであり、任意のエラーシグネチャではありません。本番環境でエラーが再発しなくなったときにのみ、このループは完了します。再発した場合は、新しい証拠を添えて再度対応します。
9. 範囲を BOUND します。自動で準備するのは、ステップ 1 でユーザーが事前承認した種類に限ります（デフォルトで安全な種類：バリデーターの修正、インデックスの追加、所有権チェックの追加、非破壊的なバックフィル）。破壊的な変更、チェックの追加を超えるセキュリティ上重要な変更、または曖昧な変更は、必ず人間からの明示的な指示を待ちます。ループを監査できるよう、すべての操作を追記専用の記録に残します。

ルール

• マージボタンは人間が操作します。このループでは修正を準備して認定しますが、自動でマージしたり、本番環境へ自動デプロイしたりすることは決してありません（信頼できるシステムが、人の介入なしに本番環境へ自動マージしてリリースすることはない、という業界の原則に沿っています）。
• 提案する前に認定します。tsc ＋（本番スナップショットのプレビュー環境での schema→migrate-rehearse）＋障害を再現して解消を確認すること＋新たなバス上の検出事項がないこと。認定できていない修正は、完了したものとして提案せず、「認定できませんでした」と報告します。
• まずトリアージします。一時的な問題は再試行または無視し、設定エラーは環境側に回します（シークレットを推測してはいけません）。実際のコードやスキーマの不具合のみを修復ループに入れます。
• 修復はブランチまたはプレビュー環境で行い、本番環境へ直接変更を加えてはいけません。デプロイするのは、deploy-guardで本番環境への同意を改めて得た場合に限ります。
• 自動で準備するのは、事前に承認された修正クラスのみです（デフォルトで安全：バリデーター／インデックス／所有権／破壊的でないバックフィル）。破壊的、または判断が曖昧な変更は、必ず人間の判断に委ねます。
• 実際にループを完了させます。マージとデプロイの後、センチネルテーブルとログでエラーのシグネチャが再発しなくなったことを確認します（パフォーマンスイベントしか認識しないinsightsは使いません）。再発が続く場合は、再度対応します。
• すべての操作は、追記専用で監査可能な記録に記録します。データレジデンシーはユーザー自身のデプロイ環境内に保ちます（センチネルの原則）。
• 根本原因が不明な場合は、停止して報告します。不確かな修正は、未解決のまま可視化されているエラーよりも悪い結果を招きます。