Skip to content

Alerts

Purpose

What a client of the platform (the TUI, the web app app) collects as alerts: what went wrong, or needs a look, on any of its contexts, in one list instead of notices that vanish. The spec is client-neutral: it fixes the sources, what each event says and how repeats merge, and shared conformance vectors make every client decide alike; how a client shows the list and which keys it uses belong to its own spec (Terminal UI).

Related specs: - Terminal UI — the TUI's Alerts pane, its keys and the count in the context row. - Behaviour — the trading halt. - Pub/Sub Topics — the names of the topics followed, built by the naming library.

Requirements

Requirement: Alert Sources

A client SHALL collect, for each context it is bound to while bound, and for itself:

  • a P&L worker's limit breach (sc.<S>.risk.limit.breach, named by the portfolio devkit), for every scenario of the registry; the pub/sub matches topics exactly, so the client SHALL follow the registry and subscribe the breach topic of each scenario it has;
  • a worker lifecycle event (sys.workmanager.worker.lifecycle) that is a failure (failed, load-failed), a status report of a part-working or disconnected worker (status with degraded or disconnected; not reconnecting, the way back), or a gap in a worker's input (gap);
  • a trading halt set or lifted after the client read the halts once; the halts found when it binds a context are not alerts (the client shows them as halts);
  • a context's api going down after it answered, and answering again after that; a context never reached is not an alert;
  • every action of the client that failed, with the reason it shows the user.

Scenario: A scenario added

  • WHEN a scenario is added to the registry of the bound context
  • THEN the client SHALL follow that scenario's limit breaches too, without a restart

Requirement: What an Event Says

An event that is an alert SHALL become one alert with a key, a severity (error, warning, info), a source (risk, worker, halt, context, or the client's own), a subject and a text: a failure is an error with the failure's type and message, a degraded or disconnected status report or an input gap a warning, a breach the severity it carries (warning without one) with the limit, the actual and the limit value, a halt an error with its reason and a lifted halt info. Anything else SHALL be no alert.

Scenario: Two clients, one answer

  • WHEN the TUI and the web app are given the same lifecycle payload, breach payload or halt change
  • THEN they SHALL find the same alert or none, as in the shared vectors (conformance/alerts/classify.yaml, in the TUI repository until the vectors move to a shared home)

Requirement: Repeats, Read and Bound

An alert with the context and key of one already in the list SHALL update that one (its text, the time it last came, how often it came) and bring it back to the top as unread, not add another. Alerts SHALL be listed newest first, a client SHALL say how many are unread and SHALL mark them read when the user looks at the list; the user SHALL be able to dismiss one and to clear the list. The list is the client's own: kept in memory, bounded (the oldest go first), not saved.

Scenario: A failing worker

  • WHEN a worker fails three times
  • THEN the list SHALL show one alert for it, counted three times, unread