トラブルシューティング

AWRの何かが期待通りに動いていません。このガイドは症状から修正へと進みます。まずヘルスチェック、次に データベースの問題、そしてソースファイルへの中断された変更です。各セクションで、実行すべき正確なコマンドと 出力の読み方を示します。日常的なコマンドについては日常ワークフローと CLIリファレンスを参照してください。

ステップ1: ヘルスチェックを実行する

AWRにはDoctorという組み込みの診断コマンドがあり、2つのレベルで実行できます:

awr --json doctor --database-only
awr --json doctor

• --database-onlyはSQLiteデータベース自体をチェックします。整合性、外部キー、スキーマバージョン、 マイグレーションの識別情報、AWR所有のスキーマオブジェクト。
• 完全なdoctorはさらに、選択したソースファイルと、ランタイムレコードとディスク上のファイルとの バインディングを検査します。

Doctorはデータベースを読み取り専用で開きます。スキーマのマイグレーション、ソースの再インデックス、 保留中の変更の適用、クレームの失効、孤立ファイルの削除は行いません —— そのため、破損したプロジェクト でも常に安全に実行できます。

Doctorの所見の読み方

Doctorは推測ではなく、明示的な所見として問題を報告します:

• schema_issues —— AWR所有のテーブル、カラム、インデックス、トリガーの欠落または変更。同梱の マイグレーションと照合してチェックされます。余分なオブジェクトは共存できます。Doctorは定義を修復 したり、そのSQLを出力したりしません。
• foreign_key_check_error —— 不正な参照のためにSQLiteが外部キーチェック自体を実行できませんでした。 このフィールドが見えたら、データベースは不健全です。報告された違反数ゼロは「すべて正常」ではなく 「カウントできなかった」を意味します。
• アクティブなセッション —— 情報提供のみ。古いレコードがプロセスの停止を証明するわけではありません。
• 欠落した依存関係、ダングリングエッジ、利用不能なソース、中断された保存、破損または未登録の成果物は、 それぞれ所見として報告されます。読み取り不能なページや外部の（非AWR）データベースは、誤解を招く ステータスではなく明示的なエラーになります。

症状: 「AWRがソースファイルを拒否した」

YAMLソースファイルに構文エラーや型の違うフィールドがある場合、AWRはエラーコードInvalidInputと構造化 された詳細で失敗します:

{
  "location": {
    "locator": "file:///project/work.yaml",
    "pointer": "/work_items/0/title",
    "line": 3,
    "column": 10
  },
  "rule": "ledger.string",
  "repair": "Use a quoted string or a YAML block scalar (|) for multiline text."
}

読み方: pointerはソースファイル自身の語彙（設定された中国語フィールド名を含む）で問題のフィールドを 示します。lineとcolumnは1始まりです。純粋な構文エラーはパーサーの座標のみを持つことがあり、一部の ルックアップ（YAMLエイリアスなど）は座標がnullのポインターを保持します —— それは他が有効なファイルを 拒否するものではありません。ruleは失敗した期待を示し、repairは期待される構造を説明します。ファイルを 編集したり、拒否された値をエコーし返したりすることは決してありません。

よくあるケース: title: [Draft, Review]と書くと、YAMLはリストとしてパースしますが、そのフィールドは 文字列を要求します。カンマを文字どおりに意図していた場合:

title: "Draft, Review"

複数行の説明にはYAMLブロックスカラー（|）を使います。有効な中国語テキストやスペースを含むパスは完全に サポートされています。

症状: 「変更がクエリに反映されない」

ソースファイルを編集したのにAWRが古い事実を表示し続けています。再インデックスを実行してください:

awr source reindex

その後、レポートの両方の部分を確認してください。操作の成功とプロジェクションの完全性です。スキャンは 成功してもプロジェクションが不完全なままのことがあります。スキャンはソースを観察しますが、変更された事実を インポートしないからです。同じレポートは--jsonでJSONとしても、MCPのawr_source_reindex経由でも得られ ます。同等の開始スナップショットからの出力を比較してください。再インデックス自体がソース状態を更新します。

作業アイテムの証跡がおかしく見える場合、work show（またはMCPのawr_work_get）はフラットなevidence リストの隣にevidence_groupsを報告します。各グループは1つの正確なロケーターを持ちます。同じパスの ソース参照と検証済みレポートは区別されたままで、グルーピングがレコード間で検証を移譲することは決して ありません。

症状: 「データベースが破損または喪失した」

ソースファイルはプロジェクトの事実について権威がありますが、SQLiteデータベース（.awr/state.db）には それらのファイルが含まない状態も保持されています。セッション、クレーム、チェックポイント、ランタイム イベント、成果物の登録、変更の試行です。再インデックスはソースからプロジェクションを更新しますが、その ランタイム履歴を再構築することはできません —— 同じソースから新しいデータベースを初期化しても同様です。

適切なバックアップ

リカバリー可能なスナップショットのためには、以下のすべてを一緒に保持し、組み立てている間はプロジェクトの 書き込みを停止してください（SQLiteのバックアップAPIは一貫したデータベースイメージを提供しますが、周囲の ファイルはスナップショットしません）:

• SQLiteのバックアップAPIまたは同等のツールで作成した、.awr/state.dbの一貫したバックアップ —— 書き込み中にファイルをコピーすると、ライトアヘッドログに残っているコミット済みレコードを逃すことが あります。
• 対応するソースファイル、Gitリビジョン、.awr/project.toml、許可ルート設定、明示的に許可された外部 ソース。
• 管理対象の成果物ファイル、管理ディレクトリ外の登録済みローカル成果物、保留中の操作が参照する .awr/mutationsのリカバリージャーナルとスナップショット。

リストア

1. プロジェクトを停止します。
2. 記録された正規ルートでリストアします。退避した状態は削除せずに保持してください。
3. awr --json doctor --database-onlyを実行し、次に完全なawr --json doctorを実行します。

リストアは、ファイルがまだ欠けている間に成果物の登録を回復することがあります —— ファイルをリストアするか、 その所見を未解決のままにしてください。awr source reindexはランタイムのリストアでもデータベースの移動 ツールでもありません。

Doctorは名前付きの修復を実行できますが、現在のプロジェクトリビジョン、選択されたオブジェクト、理由が 揃った場合に限ります。修復はソースと無関係なランタイム状態を保持します。データベースの整合性が壊れている 場合、提案されるランタイム修復は無効になります —— 自動再構築はありません。

症状: 「変更が書き込み途中で中断された」

AWRは承認された提案を耐久性ガード付きでソースファイルに適用します。試行が記録される前に不変の 変更前/変更後スナップショットが保存され、成功には意図したソースバイト、再構築されたプロジェクション、 最終的な適用イベントが必要です。プロセスが書き込み途中で停止した場合、その試行は開いたままリカバリー 可能です。

write_outcome: pending_recoveryを伴うMutationIncompleteが返ったら、まず検査します:

awr --json doctor
awr --json proposal show PROPOSAL_ID

出力から現在のproject_revisionを読み、提案を再開します:

awr --json proposal recover PROPOSAL_ID \
  --actor reviewer \
  --reason "Resume the interrupted report review" \
  --expected-revision CURRENT_REVISION

リカバリーが何をするかは、試行がどこまで進んだかによります:

成功した再試行はrecoveredを報告し、元の試行を指名し、そのresolved_event_idを最終イベントに 紐付けます。

してはいけない2つのこと:

• 結果を強制するためにスナップショットを編集しないでください。 現在のソースがどちらのスナップ ショットとも一致しない場合は、ソースのコンフリクトを解決し、新しい提案を準備してください。
• 再試行がファイルを書いたと思い込まないでください。 source_write_performedは現在の呼び出しに ついてのみ記述します —— リカバリーが最初に再検証するのはそのためです。

並行性: AWRの書き込みは、ソースごとのOSロックとトランザクショナルなexpected_revisionチェックで調整 されます。別々のソースは独立に進行しますが、介在するプロジェクトリビジョンが明示的なリカバリー再試行を 必要とすることがあります。外部エディターはロックに参加しません。フィンガープリントチェックがその変更を 検出します。

立ち止まって助けを求めるべきとき

以下の場合は、即興で対処せず立ち止まってエスカレーションしてください:

• Doctorがデータベース整合性の破損を報告した（foreign_key_check_error、読み取り不能なページ） —— ランタイム修復は無効で、自動再構築はありません。
• 変更のリカバリーがソース/スナップショットのコンフリクトを報告した —— サポートされる経路は新しい 提案であり、スナップショットやジャーナルの手編集ではありません。
• マシンの電源喪失、分散書き込み、他のオペレーティングシステムを含むシナリオ —— リカバリー保証は ローカルプロセスの中断をカバーします。それを超えるものは確立されていません。

助けを求めたりissueを提出したりする前に、状態が新鮮なうちに記録してください:

awr --json doctor --database-only
awr --json doctor
awr --json proposal show PROPOSAL_ID   # if a mutation is involved

退避したデータベース、.awr/mutationsのジャーナル、関連するソースファイルを手つかずのまま保持して ください —— それらがレポートを実行可能なものにし、修正が失敗したときのフォールバックにもなります。