From risk numbers to alerts

We've built the graph, maintained it, and computed risk on it. But none of that is the product. The product is: a customer says "alert me if an admin can drain more than $5M of my token," and the system watches for exactly that, forever. The rule engine (pkg/rules) is where the risk graph finally becomes an alert. This is what it was all for.

1 · A rule, anatomised

A customer rule (pkg/rules/types.go Rule) is a small declarative spec:

Read it as a sentence: "for [scope], when [field] [operator] [value], fire." The four rule types map to four questions:

Source: pkg/rules/types.go (Rule, Condition, Scope, RuleType), threshold.go/aggregate.go/balance.go.

2 · Fields: the contract with the risk engine

The field path in a condition is the hinge between this lesson and Lesson 6. The risk engine writes risk values onto nodes; the rule engine reads them by path. The catalog of evaluable fields is a real schema (docs/rule-fields.json, fields.gen.go), and every field declares where it comes from:

Source: docs/rule-fields.json (path · kind · unit · cadence · rule_types · scopes · source). A lint (scripts/lint-schema-coverage.sh) keeps the schema endpoint in sync with the code.

3 · Scope: which nodes does the rule touch?

Before evaluating, the engine resolves the rule's scope into a concrete list of node IDs (pkg/rules/scope.go ScopeResolver.Resolve):

4 · The evaluation loop (two cadences)

The Engine (engine.go) runs two things concurrently:

• runHTTP — a CRUD + dry-run API: customers create/edit rules, and can test a rule against the current graph without firing (handleDryRun).
• runPeriodicEval → evalCycle — the heartbeat: on each cycle, for each rule, resolve scope → read the field for each node → check the condition → run the firing state machine.

Two cadences again mirror the system's push-based philosophy (L1): periodic for the 2-hourly risk fields, event-driven for live fields (a balance_changed or lending_dirty signal evaluates the relevant rules immediately).

5 · Firing: a state machine, not a trigger ⭐

Here's the non-obvious depth. A rule does not fire an alert every time the condition is true — that would spam a customer with thousands of identical alerts while a threshold stays breached. Instead, each (rule, node) pair runs through a firing state machine (firing.go):

• CLEAR → ACTIVE: condition first met → emit one alert.
• ACTIVE (re-emit): still breached + cooldown elapsed → emit a reminder (not a flood).
• ACTIVE → COOLDOWN: condition clears → a resolve grace period (so a value flickering across the threshold doesn't thrash).
• COOLDOWN → CLEAR: grace expires while clear → reset. COOLDOWN → ACTIVE: re-breached during grace → alert again.

6 · Where alerts go

An emitted AlertEvent is published (publisher.go) and stored in OpenSearch (opensearch.go, opensearchstore.go) — note this is the system's one use of OpenSearch, separate from Memgraph/Redis; alerts are documents you search/filter, not graph nodes. Downstream, the alert-processor (cmd/alert-processor, pkg/alertprocessor) consumes and delivers them. The loop is finally closed:

Check yourself

What you can now do

• Anatomise a rule: type + condition (field/operator/value) + scope + trigger.
• Explain fields as the contract with the risk engine — and how a field's source + cadence set its meaning and latency.
• Describe scope resolution as anchored graph queries (L2 in production), and the periodic vs on_event eval cadences.
• Explain the firing state machine and why alerting is stateful (debounce, hysteresis, resolve lifecycle).
• Trace the complete product loop: on-chain event → graph → risk field → rule → alert.