fix(db): add FK constraint on usage_snapshots.agent_id [#1244]

internal/upgrade/version.go

@@ -2,4 +2,4 @@ package upgrade
 
 // RequiredSchemaVersion is the schema migration version this binary requires.
 // Bump this whenever adding a new SQL migration file.
-const RequiredSchemaVersion uint = 86
+const RequiredSchemaVersion uint = 87

migrations/000087_usage_snapshots_agent_fk.down.sql

@@ -0,0 +1,2 @@
+-- Rollback migration 087
+ALTER TABLE usage_snapshots DROP CONSTRAINT IF EXISTS fk_usage_snapshots_agent_id;

migrations/000087_usage_snapshots_agent_fk.up.sql

@@ -0,0 +1,17 @@
+-- Migration 087: FK constraint for usage_snapshots.agent_id
+--
+-- Pre-check audit (should return 0 violations on a clean DB):
+--   SELECT COUNT(*) FROM usage_snapshots
+--   WHERE agent_id IS NOT NULL
+--     AND agent_id NOT IN (SELECT id FROM agents);
+--
+-- Orphan cleanup (idempotent guard):
+DELETE FROM usage_snapshots
+WHERE agent_id IS NOT NULL
+  AND agent_id NOT IN (SELECT id FROM agents);
+
+-- Add FK constraint: usage_snapshots.agent_id → agents(id) ON DELETE SET NULL
+-- agent_id is nullable — rows with NULL remain for aggregate/rollup totals.
+ALTER TABLE usage_snapshots
+    ADD CONSTRAINT fk_usage_snapshots_agent_id
+    FOREIGN KEY (agent_id) REFERENCES agents(id) ON DELETE SET NULL;