scadalink-design/docs/plans/2026-05-16-expression-trigger-design.md

# Expression Trigger for Template Scripts and Alarms — Design

**Date:** 2026-05-16
**Status:** Approved (brainstorming) — implementation plan to follow

## Context

Template scripts and template alarms can only be triggered by single-attribute
conditions. Scripts support `Interval`, `ValueChange`, `Conditional`
(`{attributeName, operator, threshold}` — one attribute, numeric compare),
and `Call`. Alarms support `ValueMatch`, `RangeViolation`, `RateOfChange`, and
`HiLo` — all single-attribute. There is no way to trigger on a relationship
between *multiple* attributes (e.g. "speed is high *and* mode is Run").

This design adds an **Expression trigger**: a user-supplied read-only boolean
C# expression, evaluated whenever an instance attribute updates, that fires the
script / activates the alarm when it returns true. It generalizes the existing
single-attribute `Conditional` trigger.

### Decisions taken during brainstorming

- The trigger is a **read-only boolean expression** — no `External`/`Database`/
  `Notify`/`CallScript` side effects. It must be cheap and safe to run on every
  attribute update.
- **Scripts fire edge-triggered** — once per `false→true` transition.
- **Alarms are level-based** — active while the expression is true, clear when
  false (consistent with all existing alarm trigger types).
- **Evaluation approach B** — compile against a *restricted read-only globals
  type*, so read-only is enforced, not merely conventional. Reuses the existing
  Roslyn compilation pipeline.

## Design

### 1. Trigger model & storage

- **Scripts:** `TemplateScript.TriggerType` (`string?`) gains the value
  `"Expression"`. `TriggerConfiguration` JSON is `{ "expression": "<C#>" }`.
- **Alarms:** `AlarmTriggerType` enum gains a member `Expression`.
  `TriggerConfiguration` JSON is the same `{ "expression": "<C#>" }`.
- The expression is a bare C# boolean expression (no `return` keyword — Roslyn
  scripting returns the trailing expression's value), e.g.
  `Attributes["Speed"] > 1000 && (string)Attributes["Mode"] == "Run"`.
- Entity types unchanged: both `TriggerConfiguration` fields stay `string?`.

Adding the `AlarmTriggerType` member touches three switch sites:
`AlarmActor.ParseEvalConfig`, `AlarmActor.HandleAttributeValueChanged`,
`AlarmTriggerConfigCodec`.

### 2. Runtime evaluation

- **`TriggerExpressionGlobals`** (new, `ScadaLink.SiteRuntime`) — a read-only
  globals type exposing only `Attributes["X"]`, `Children["C"].Attributes["X"]`,
  and `Parent.Attributes["X"]`, backed by an in-memory snapshot dictionary. No
  side-effecting APIs. A missing attribute reads as `null` (never throws).
- The expression is compiled once via the existing Roslyn pipeline (same
  forbidden-API trust checks) against `TriggerExpressionGlobals`; the compiled
  delegate is cached on the actor.
- **Attribute snapshot:** `ScriptActor` and `AlarmActor` already receive every
  `AttributeValueChanged`. Each keeps a local `Dictionary<string,object?>`
  snapshot — seeded from the instance's initial attribute set at startup, then
  updated on each change. The expression evaluates against the snapshot — no
  `Ask` back to the `InstanceActor`; cheap and re-entrancy-free.
- **On each `AttributeValueChanged`:** update snapshot → run cached expression
  → `bool`.
  - **Script (edge):** track the previous result; on `false→true`, run the
    script (spawn `ScriptExecutionActor`, as the other triggers do).
  - **Alarm (level):** the `bool` feeds the existing binary Normal↔Active state
    machine — raise on `→Active`, clear on `→Normal`.
- Cost per attribute update: one cached-delegate call + one bool compare.

### 3. Editors & analysis

- **`ScriptTriggerEditor`:** add `Expression` to `ScriptTriggerKind` and
  `ScriptTriggerConfigCodec` (round-trips `{ expression }`).
- **`AlarmTriggerEditor`:** add an `Expression` case to its trigger `@switch`.
- Both render the same **expression panel**: a compact `MonacoEditor`
  (~120 px) with C# syntax, `Attributes["..."]` completion driven by the
  template's attribute metadata (self / children / parent), and live compile
  diagnostics. A one-line hint summarizes what fires.
- **Analysis:** reuse the existing `Template` analysis kind — completion and
  diagnostics work with no new analyzer code. Editor completion is slightly
  permissive (also shows `Instance`/`External`), but the runtime's restricted
  `TriggerExpressionGlobals` is what enforces read-only. A dedicated strict
  analysis kind is a possible later refinement, out of scope here.

### 4. Error handling & validation

- **Pre-deployment:** extend `ValidationService` to compile-check expression
  triggers (against `TriggerExpressionGlobals`); compile errors block
  deployment and surface like other validation errors. Unknown
  `Attributes["..."]` keys are flagged as the existing trigger-reference
  validation does.
- **Runtime — expression throws:** caught; treated as `false` for that update;
  a script-error event is written to the site event log. The actor never
  crashes.
- **Non-bool result:** treated as `false` and logged.
- **Missing attribute:** reads as `null` (handled in `TriggerExpressionGlobals`).
- **Blank expression:** the trigger is inert; validation emits a warning.

### 5. Testing & verification

- **Unit:** codec round-trip for script and alarm `{ expression }`; expression
  compile (valid + invalid).
- **Runtime:** deploy an instance with an expression-triggered script and
  alarm; drive attribute updates (bound Test Run / CLI); confirm the script
  fires only on `false→true` and the alarm raises/clears with the expression.
- **UI:** the expression panel in both editors; save → reopen round-trip.

## Implementation tasks

- #25 — Implement expression trigger model + codecs
- #26 — Implement runtime expression evaluation (blocked by #25)
- #27 — Add expression panel to the trigger editors (blocked by #25)
- #28 — Validate expression triggers pre-deployment (blocked by #25, #26)