Close scratch iteration 009 grouped policy and VEX audit repairs

docs/modules/vex-hub/architecture.md

@@ -19,7 +19,7 @@ Non-goals: policy decisioning (Policy Engine), consensus computation (VexLens),
 - **VexHub.Worker**: Background workers for ingestion schedules and validation pipelines.
 - **Normalization Pipeline**: Canonicalizes statements, deduplicates, and links provenance.
 - **Validation Pipeline**: Schema validation (OpenVEX/CycloneDX/CSAF) and signature checks.
-- **Storage**: PostgreSQL schema `vexhub` for normalized statements, provenance, conflicts, and export cursors.
+- **Storage**: PostgreSQL schema `vexhub` for sources, normalized statements, provenance, conflicts, ingestion jobs, and export cursors.
 
 ## 4) Data Model (Draft)
 - `vexhub.statement`
@@ -37,11 +37,25 @@ All tables must include `tenant_id`, UTC timestamps, and deterministic ordering
 - `GET /api/v1/vex/cve/{cve-id}`
 - `GET /api/v1/vex/package/{purl}`
 - `GET /api/v1/vex/source/{source-id}`
+- `GET /api/v1/vex/stats`
 - `GET /api/v1/vex/export` (bulk OpenVEX feed)
 - `GET /api/v1/vex/index` (vex-index.json)
 
 Responses are deterministic: stable ordering by `timestamp DESC`, then `source_id ASC`, then `statement_hash ASC`.
 
+`GET /api/v1/vex/stats` returns the dashboard contract consumed by the console VEX surfaces:
+- `totalStatements`
+- `verifiedStatements`
+- `flaggedStatements`
+- `byStatus`
+- `bySource`
+- `recentActivity`
+- `trends`
+- `generatedAt`
+
+The stats endpoint must keep working on fresh installs even when a committed EF compiled-model stub is empty; runtime model fallback is required until a real optimized model is generated.
+The service must also auto-apply embedded SQL migrations for schema `vexhub` on startup so wiped volumes converge without manual SQL bootstrap.
+
 ## 6) Determinism & Offline Posture
 - Ingestion runs against frozen snapshots where possible; all outputs include `snapshot_hash`.
 - Canonical JSON serialization with stable key ordering.
@@ -67,6 +81,7 @@ Responses are deterministic: stable ordering by `timestamp DESC`, then `source_i
 ## 10) Testing Strategy
 - Unit tests for normalization and validation pipelines.
 - Integration tests with Postgres for ingestion and API outputs.
+- Persistence registration and runtime-model tests that prove source/conflict/ingestion-job repositories and startup migrations are wired on the service path.
 - Determinism tests comparing repeated exports with identical inputs.
 
-*Last updated: 2025-12-22.*
+*Last updated: 2026-03-13.*