SITREP Signal System
Structured event emission, provenance chains, and build phases for the per-fund intelligence system.Hugo emits structured events to the fund_events table for every SITREP-relevant mutation. The event stream is the foundation for a per-fund intelligence system.
Event groups
| Group | Examples | Source |
|---|---|---|
| Mutations | commitment_created, mfn_general_rule_created, clause_assigned, side_letter_status_changed, lp_task_created |
User actions via withImpact |
| Derived | mfn_eligibility_changed |
Automatic diff in withImpact |
| Absence | lp_silent_threshold_exceeded, election_window_closing_soon (reserved) |
Scheduled cron sweep (phase 6) |
| System | parser_execution_failed (reserved) |
Pipeline signals (phase 6) |
For the complete event taxonomy with payload schemas and trigger details, see the Events catalog.
Provenance
Root events (user actions, sweeps) have caused_by = NULL and depth = 0. Derived events point at the root that caused them via the caused_by FK.
This allows provenance walks: "this LP gained eligibility for clause X because user Y created general rule Z."
fund_events schema
| Column | Type | Description |
|---|---|---|
id | TEXT PK | UUID |
fund_id | TEXT FK | Fund this event belongs to |
event_type | TEXT | Closed enum value (29 types) |
payload_json | TEXT | Structured JSON payload per event type |
caused_by | TEXT FK | Root event ID (NULL for root events) |
depth | INTEGER | 0 for root, 1+ for derived |
created_at | TEXT | ISO timestamp |
Build phases
| Phase | Description | Status |
|---|---|---|
| 1–2 | fund_events table, withImpact helper, closed event enum (29 types), 10 handler migrations |
Shipped |
| 3 | Queue-driven synthesis trigger with 30s debounce | Planned |
| 4 | fund_sitrep_state table + queue consumer |
Planned |
| 5 | fund_sitrep_cache + synthesis function |
Planned |
| 6 | Re-enable cron with absence sweeps | Planned |
| 7 | SITREP card UI on fund-detail overview | Planned |
Synthesis trigger design
The synthesizer fires on events, not on a clock tick. Every write to fund_events sends a message to hugo-sitrep-queue via waitUntil. The consumer debounces: if events are still arriving for a fund, it extends debounce_until by 30 seconds. Once quiet, it runs synthesis and writes fund_sitrep_cache.