db-referential-integrity

db-referential-integrity (M3)

外部キーは、参照先が実在することをデータベースが保証する仕組みです。孤児データを防ぐための、最も低コストで長期間有効な保証です。外部キーがないと整合性の担保がアプリケーションコードに移り、気づかないうちに劣化していきます。このモジュールは両方の軸に対応します。設計面では整合性を、パフォーマンス面では結合と実行計画の動作を確認します。外部キーをサポートするリレーショナルエンジンのみが対象です。ドキュメント型／KV プロファイルでは対象外とし、誤った減点を避けます。

チェック項目

• 外部キーの欠落：別テーブルの主キーに一致する参照として名前や型が定義された列（*_id）に、FOREIGN KEY 制約がありません。財務関連テーブルや認証関連テーブル（orders、payments、sessions、memberships）で、孤児データを可能にする外部キーの欠落がある場合は、重大度 5 の上限ケースです。
• ON DELETE / ON UPDATE アクション：リレーションシップに対してデフォルト（NO ACTION／RESTRICT）が適切でないにもかかわらず、明示的な参照アクションが指定されていない外部キー、または大量削除につながる危険な CASCADE（例：ユーザーの削除により請求書もカスケード削除される）を確認します。各アクションは意図的に指定する必要があります。
• 参照サイクル：順序どおりの挿入／削除を妨げ、マイグレーションを複雑にする外部キーの循環（A→B→C→A）です。重大度は 4 です。
• 複合外部キーの不一致：複数列の外部キーの列セット／順序が、参照先の一意キーと一致しない、または複合参照が一部のみである場合です。
• 未検証／NOT VALID の外部キー：バックフィル後も未検証のまま残されている外部キー（Postgres の NOT VALID）です。

軸と重大度

• 財務／認証関連の行を孤児化させる外部キーの欠落：重大度 5、fail、軸 both、信頼度 established（上限）。
• 外部キーの循環：重大度 4、warn、軸 both。
• ON DELETE の欠落／過剰（暗黙の RESTRICT による阻止、または意図しない CASCADE）：重大度 3～4、warn、軸 design。
• 複合外部キーの順序の不一致：重大度 3、warn。
• 注：外部キー列に対応するインデックスがない場合は、ここではなく M11（インデックス作成）の対象です。相互参照し、二重計上しないでください。

Tier-0 静的チェック

scripts/parse-schema.mjs で DDL を解析します。*_id 形式の各列について、一致する FOREIGN KEY／REFERENCES 句が存在するか確認します。宣言された外部キーを列挙し、明示的な ON DELETE／ON UPDATE アクションがないものを検出します。外部キーグラフを作成し、循環を検出します。方向性のある ORM ソースの解析では、重大度 5 の孤児データ上限は適用されません。

Tier-1 検証クエリ

外部キー制約とアクションを一覧表示します（欠落または危険なアクションを確認）：

-- $DATABASE_URL, read-only
SELECT conrelid::regclass AS child, confrelid::regclass AS parent,
       confdeltype AS on_delete, confupdtype AS on_update, convalidated AS validated
FROM pg_constraint WHERE contype = 'f';

外部キーの欠落が疑われる場合に、実際の孤児データが存在するか確認します：

SELECT count(*) AS orphans FROM child c
LEFT JOIN parent p ON c.parent_id = p.id WHERE p.id IS NULL AND c.parent_id IS NOT NULL;

稼働中の DB がない場合、孤児データ数は needs_api とし、決して暗黙に問題なしとしないでください。

検出結果

schema/finding.schema.json に従って出力します。例：

• M3.payments.user_id_no_fk — user_id がテーブルを参照していないため、孤児の支払いデータが発生する可能性があります（重大度 5、fail、軸 both、信頼度 established）。
• M3.invoices.fk_cascade_deletes_financial — users からの ON DELETE CASCADE によって invoices が大量削除されます（重大度 4、warn、軸 design、fixable: proposed）。
• M3.graph.fk_cycle_a_b_c — 参照サイクルによって順序どおりの読み込みが妨げられます（重大度 4、warn、軸 both）。 各検出結果では、evidence.observed に外部キー／列の DDL またはカタログ行をそのまま引用します。verification.reproduce には上記の実行可能なクエリを指定します（method: ddl_parse／constraint_check／query_stat）。expected_impact は段階と信頼度タグを付けます。

正確性

• 外部キーの欠落が上限に達するのは、孤児データのリスクが実在する場合（財務／認証の整合性）に限ります。重要度の低いルックアップテーブルでの外部キー欠落は、最大でも warn です。
• アプリケーションレベルの整合性担保（検証、ソフト外部キー）は緩和策であり、代替策ではありません。その存在は記載しますが、データベースレベルの保証がないことに変わりはありません。アプリケーションコードで「修正」されると主張しないでください。
• Tier-1 の件数確認なしに、孤児行が存在すると断定しないでください。静的解析では directional です。