docs: enterprise refactor plan with ralph specs

.ralph/specs/legacy/database.md

@@ -0,0 +1,99 @@
+# ABE — Database Specification (SQLite)
+
+## Rationale
+File-based storage loses all data on container restart.
+SQLite requires zero extra services and is perfect for self-hosted deployment.
+
+## Library
+Use `better-sqlite3` (synchronous, faster than async alternatives for this use case).
+
+## Location
+Database file: `data/abe.db` (persisted via Docker volume)
+
+## Schema
+
+### Table: sessions
+```sql
+CREATE TABLE IF NOT EXISTS sessions (
+  id TEXT PRIMARY KEY,
+  url TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'running',
+  seed INTEGER NOT NULL,
+  max_states INTEGER NOT NULL DEFAULT 50,
+  states_visited INTEGER NOT NULL DEFAULT 0,
+  anomalies_found INTEGER NOT NULL DEFAULT 0,
+  started_at INTEGER NOT NULL,
+  finished_at INTEGER,
+  config_json TEXT NOT NULL DEFAULT '{}'
+);
+```
+
+### Table: states
+```sql
+CREATE TABLE IF NOT EXISTS states (
+  id TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL REFERENCES sessions(id),
+  url TEXT NOT NULL,
+  title TEXT NOT NULL,
+  dom_snapshot_path TEXT,
+  visit_count INTEGER NOT NULL DEFAULT 0,
+  discovered_at INTEGER NOT NULL
+);
+```
+
+### Table: actions
+```sql
+CREATE TABLE IF NOT EXISTS actions (
+  id TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL REFERENCES sessions(id),
+  state_id TEXT NOT NULL REFERENCES states(id),
+  type TEXT NOT NULL,
+  selector TEXT,
+  value TEXT,
+  url TEXT,
+  seed INTEGER NOT NULL,
+  executed_at INTEGER NOT NULL,
+  sequence_order INTEGER NOT NULL
+);
+```
+
+### Table: anomalies
+```sql
+CREATE TABLE IF NOT EXISTS anomalies (
+  id TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL REFERENCES sessions(id),
+  type TEXT NOT NULL,
+  severity TEXT NOT NULL,
+  description TEXT NOT NULL,
+  action_trace_json TEXT NOT NULL,
+  evidence_json TEXT NOT NULL,
+  screenshot_path TEXT,
+  dom_snapshot_path TEXT,
+  detected_at INTEGER NOT NULL
+);
+```
+
+### Table: notifications
+```sql
+CREATE TABLE IF NOT EXISTS notifications (
+  id TEXT PRIMARY KEY,
+  anomaly_id TEXT NOT NULL REFERENCES anomalies(id),
+  channel TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'pending',
+  sent_at INTEGER,
+  error TEXT
+);
+```
+
+## Repository Pattern
+
+Create `src/db/` with:
+- `src/db/connection.ts` — singleton SQLite connection, runs migrations on startup
+- `src/db/SessionRepository.ts` — CRUD for sessions
+- `src/db/AnomalyRepository.ts` — CRUD for anomalies, includes filter by session/severity
+- `src/db/migrations.ts` — runs all CREATE TABLE IF NOT EXISTS on startup
+
+## Rules
+- All DB operations are synchronous (better-sqlite3 is sync)
+- Repositories are injected into the API server, never imported directly by core engine
+- The engine emits events → the API server listens and persists to DB