lmxopcua/docs/plans/2026-06-10-script-log-and-scripted-alarm-runtime-design.md

# Script-log Engine Emit + Scripted-Alarm Runtime — Design

> **Status:** approved 2026-06-10 (brainstorming). Next: implementation plan
> (`writing-plans`). Companion gap analysis: `pending.md` (repo root, verified
> against `master @ ac1e1dfd`).

## Goal

Make the Script-log page show real script output, and stand up scripted alarms
end-to-end — including real OPC UA Part 9 condition nodes and client-initiated
acknowledge/shelve. Delivered in three sequenced layers.

## Problem / current state (verified)

- The Script-log page (`ScriptLog.razor`) + transport (`IInProcessBroadcaster` →
  `ScriptLogSignalRBridge` → `script-logs` DPS topic) are fully built, but a healthy
  script's `ctx.Logger.*` output never reaches them — the Roslyn evaluators inject a
  **static** `SerilogLog.ForContext<…>()` into the script context. Only eval
  *failures* publish a `ScriptLogEntry` (from `VirtualTagActor`). Hence the page note
  *"No script-log entries yet. Engine emit (F8/F9) is pending."*
- `ScriptLoggerFactory` / `ScriptLogCompanionSink` / the `scripts-*.log` sink exist
  but are **not wired into the Host** — the evaluators bypass them.
- **Scripted alarms do not run at all.** The Part-9-complete `ScriptedAlarmEngine` +
  `ScriptedAlarmSource` are orphaned (never constructed); `DriverHostActor` wires only
  the virtual-tag host. The new runtime materialises a placeholder `[active,
  acknowledged]` variable per alarm; real Part 9 nodes are the unstarted **F14b /
  #85** workstream.
- `phase-7-status.md` marks the alarm runtime "Done", but it describes a **superseded
  architecture** (`OpcUaApplicationHost` / `Phase7EngineComposer` etc., all 0 hits
  today). Trust the code, not that doc. Full detail + audit table in `pending.md`.

## Decisions (from brainstorming)

| # | Decision |
|---|---|
| D1 | **Full scope: all three layers** (shared emit · F9 engine runtime · F14b real Part 9 + client ack). |
| D2 | Build F9 on the **heavyweight `ScriptedAlarmEngine`** (Part-9-complete, tested), **not** the lightweight `ScriptedAlarmActor`. Retire `ScriptedAlarmActor` + `RoslynScriptedAlarmEvaluator`. |
| D3 | A **root script logger** (file + companion + new topic sink) is the **shared emit seam** for F8 *and* F9. Build once at Host startup, inject into both evaluators and the engine's `ScriptLoggerFactory`. |
| D4 | `ScriptLogTopicSink` gates at a **configurable minimum level, default `Information`** (Debug/Trace stay in the file, off the wire). |
| D5 | Composition carries the alarm predicate **source + dependency refs** via a new `EquipmentScriptedAlarmPlan` (parallel to `EquipmentVirtualTagPlan`), built byte-parity in **both** compose seams (`Phase7Composer` + `DeploymentArtifact`). |
| D6 | **Ack plumbing is grouped into Layer 2** — AdminUI ack/shelve and OPC-UA-client ack both route to the same `engine.AcknowledgeAsync(...)`. Layer 1 stays "alarms run + persist + historize + emit". |

**No Configuration entity / EF migration change** is required: the `ScriptedAlarmState`
table already exists; the EF store reads/writes it, and the composition enrichment is
in-memory plan types only.

## Architecture

The unifying seam is the **root script logger**:

```
root script logger ─┬→ scripts-*.log (rolling, all levels)
                    ├→ ScriptLogCompanionSink (Error+ → main opcua-*.log)
                    └→ ScriptLogTopicSink (≥ min level) → IScriptLogPublisher
                          → DPS "script-logs" → ScriptLogSignalRBridge
                          → IInProcessBroadcaster → ScriptLog.razor
```

Inject it into both Roslyn evaluators (F8) and the `ScriptedAlarmEngine`'s
`ScriptLoggerFactory` (F9); every layer's script logging lights up the page for free.

```
Layer 0  Shared emit          ScriptLogTopicSink + root logger + per-script ForContext   [foundation]
Layer 1  F9 engine runtime    ScriptedAlarmHostActor wraps ScriptedAlarmEngine            [the payoff]
Layer 2  F14b real Part 9     real AlarmConditionState nodes + events + inbound ack        [SDK epic]
```

---

## Layer 0 — Shared script-log emit + F8 live

**Outcome:** a healthy virtual-tag script's `ctx.Logger.Information(...)` shows on the
page in ~½s.

**New:**
- `ScriptLogTopicSink : Serilog.Core.ILogEventSink` (`Core.Scripting`) — reads
  `ScriptId`/`VirtualTagId`/`AlarmId`/`EquipmentId` off the `LogEvent`, builds a
  `ScriptLogEntry`, hands it to an injected `IScriptLogPublisher`. Min-level gate (D4).
- `IScriptLogPublisher` (`Core.Scripting`) — `void Publish(ScriptLogEntry entry)`.
  Keeps Akka out of Core.
- `DpsScriptLogPublisher : IScriptLogPublisher` (Runtime/Host) — holds the
  `ActorSystem` mediator; `Publish` → `Mediator.Tell(new Publish("script-logs", entry))`.

**Changed:**
- Host startup builds the **root script logger** (file + companion + topic sink),
  registers it in DI.
- `RoslynVirtualTagEvaluator` + `RoslynScriptedAlarmEvaluator` take the root logger
  instead of the static field; per evaluation `ForContext` the identity
  (`ScriptId`/`VirtualTagId`/`EquipmentId`) and inject into the script context.
  Requires threading `scriptId`+`equipmentId` to the evaluator per call (small
  extension; `VirtualTagId` already present — in the live path `scriptId ==
  virtualTagId` today).
- `ScriptLoggerFactory` gains a binding for the standard property set (so the engine's
  per-alarm logger carries `AlarmId`/`EquipmentId` the topic sink understands).

**No regression:** `VirtualTagActor`'s existing failure `PublishLog` stays (catches
compile errors/timeouts the script can't log) — distinct messages, no double-emit.

**Tests (xUnit+Shouldly):** sink props→entry mapping + min-level gate + null props;
root-logger fan-out (Error→all three sinks, Debug→file only); evaluator emits via a
fake `IScriptLogPublisher` when a script logs. Live-verify: author a logging vtag in
docker-dev.

---

## Layer 1 — F9 engine runtime

**Outcome:** scripted alarms run — predicates evaluate against live tags, state
persists, transitions drive the alarm node + historian + Alerts page, predicate logs
hit the page (via Layer 0).

**Host:** `ScriptedAlarmHostActor` (new, Runtime) — child of `DriverHostActor`, spawned
where `VirtualTagHostActor` is. Owns one `ScriptedAlarmEngine`; on `ApplyScriptedAlarms`
calls `engine.LoadAsync(defs)`; disposes engine on stop.

**Supporting pieces:**
1. `DependencyMuxTagUpstreamSource : ITagUpstreamSource` (new) — host registers
   interest with `DependencyMuxActor` for the union of alarm dep refs; each
   `DependencyValueChanged` pushes into the adapter cache and fires the engine's
   `SubscribeTag` observers. `ReadTag` = cache lookup (Bad if absent). Values wrapped
   as `DataValueSnapshot` (Good) like the vtag path.
2. `EfAlarmConditionStateStore : IAlarmStateStore` (new) — persists `AlarmConditionState`
   ↔ the existing `ScriptedAlarmState` table (enabled/acked/confirmed/shelving +
   `ShelvingExpiresUtc` + LastAck*/LastConfirm*/CommentsJson; **ActiveState re-derived,
   not stored**). Mirrors `EfAlarmActorStateStore`; uses `IDbContextFactory<OtOpcUaConfigDbContext>`.
3. **Composition enrichment** (D5) — new `EquipmentScriptedAlarmPlan(ScriptedAlarmId,
   EquipmentId, Name, AlarmType, Severity, MessageTemplate, PredicateScriptId,
   PredicateSource, DependencyRefs, HistorizeToAveva, Retain, Enabled)`. `PredicateSource`
   resolved `PredicateScriptId → Script.SourceCode`; `DependencyRefs` =
   `DependencyExtractor.Extract(source).Reads` ∪ message-template token paths. Built in
   `Phase7Composer.Compose` (live DB) and `DeploymentArtifact` (artifact encode/decode),
   byte-parity. `DriverHostActor` → `ApplyScriptedAlarms(composition.EquipmentScriptedAlarms)`.
4. **Engine→outputs bridge** (host `engine.OnEvent` handler): map `Condition` →
   `(active, acknowledged)` → `OpcUaPublishActor.WriteAlarmState(AlarmId, …)`; if
   `HistorizeToAveva` → `HistorianAdapterActor`; publish `AlarmTransitionEvent` on the
   `alerts` topic. **Script-log emit is automatic** — the host passes Layer 0's root
   logger into the engine's `ScriptLoggerFactory` (the Layer 0↔1 join).

**Retire:** `ScriptedAlarmActor`, `RoslynScriptedAlarmEvaluator`, the F9b DI
registration in `Program.cs`.

```
deploy → EquipmentScriptedAlarmPlan(source+deps) → ScriptedAlarmHostActor.LoadAsync
tag change → DependencyMux → adapter → engine predicate eval → Part9StateMachine
   engine.OnEvent ─┬→ WriteAlarmState (active/ack node)
                   ├→ HistorianAdapterActor (if Historize)
                   ├→ alerts topic (Alerts page)
                   └→ per-alarm logger → [Layer 0] → Script-log page
```

**Tests:** EF store round-trip (in-memory EF); upstream adapter push→observer;
composition enrichment + `Phase7Composer`↔`DeploymentArtifact` parity (same discipline
as `{{equip}}`); host actor TestKit (apply → tag change → asserts WriteAlarmState /
historian / alerts emitted). Engine internals already tested. Live-verify: author an
alarm, drive its tag, watch the node flip + historian queue + predicate logs.

---

## Layer 2 — F14b real Part 9 + client ack

**Outcome:** alarms become real Part 9 conditions — clients see them in event
subscriptions and can Acknowledge/Shelve/Confirm; the placeholder variable is retired.

**SDK-heavy epic (issue #85).** All SDK address-space work funnels through
`OpcUaPublishActor` on the pinned dispatcher. **SDK specifics (creating
`AlarmConditionState`, the event model, method-handler wiring) confirmed via the
DeepWiki MCP (`OPCFoundation/UA-.NETStandard`) during planning**, not assumed here.

**Components:**
1. **Real condition nodes** — materialise a proper `AlarmConditionState` (or the
   subtype per `AlarmType`: Limit/OffNormal/Discrete) under the equipment node with the
   standard sub-properties (ActiveState/AckedState/ConfirmedState/EnabledState/
   ShelvingState/Severity/Retain/Comment). Replaces `WriteAlarmState`'s flat variable.
2. **State → condition** — the Layer 1 bridge now carries the full `AlarmConditionState`
   and sets it on the real node.
3. **Event firing** — `condition.ReportEvent(...)` on each transition so subscribers get
   the alarm (AlarmsAndConditions).
4. **Inbound method dispatch + ack plumbing (D6)** — wire
   `Acknowledge`/`Confirm`/`AddComment`/`OneShotShelve`/`TimedShelve`/`Unshelve` →
   `engine.<Op>Async(conditionId, principal, comment, ct)` with the **authenticated
   session principal**. Both the OPC UA client path and `ScriptedAlarms.razor` route to
   the same engine methods; engine transition → persist → emit → node update + event.
5. **Permission gating** — method calls gate at the `AlarmAck` tier (LDAP-group → OPC-UA
   permission map); Confirm/Shelve/AddComment equivalently.

```
OPC UA client ─┐                          ┌→ engine updates AlarmConditionState
AdminUI page ──┴→ engine.AcknowledgeAsync  ┤   → OpcUaPublishActor → real condition node
                  (principal, AlarmAck gate)└→ condition.ReportEvent → client event stream
```

**Tests:** engine-state→condition-state mapping; method→engine routing (fake engine) +
permission gating; SDK node/event behaviour proven by **Client.CLI** alarm subscribe +
ack round-trip in docker-dev. Highest-risk layer; most live-verification dependent.

---

## Cross-cutting

**Hard rules (carry into the plan):**
- Stage by explicit path — never `git add .`. Never stage `sql_login.txt` or
  `src/Server/ZB.MOM.WW.OtOpcUa.Host/pki/`. Never echo the gateway API key into a new
  tracked file. No force-push, no `--no-verify`.
- **No Configuration entity / EF migration change** (the `ScriptedAlarmState` table
  already exists).
- Agent must **not** sign in to the AdminUI for live verification — the user signs in.
- Razor/JS proven only by live docker-dev `/run`; everything else unit-tested
  (xUnit + Shouldly, in-memory EF, Akka TestKit). No bUnit.
- Build on a feature branch off `master`; planning docs (this design + the plan +
  `.tasks.json`) committed to `master` per established pattern.

**Touched code (indicative — plan nails exact files):**
- Layer 0: `Core.Scripting/` (new sink + publisher iface + factory binding),
  `Host/Program.cs` (root logger wiring + retire static loggers), `Host/Engines/Roslyn*Evaluator.cs`,
  `Runtime` (DPS publisher).
- Layer 1: `Runtime/ScriptedAlarms/` (host actor, upstream adapter, EF store),
  `OpcUaServer/Phase7Composer.cs` + `Runtime/Drivers/DeploymentArtifact.cs` (enriched plan),
  `Runtime/Drivers/DriverHostActor.cs` (spawn + apply), retire `ScriptedAlarmActor` +
  `RoslynScriptedAlarmEvaluator`.
- Layer 2: `OpcUaServer/OtOpcUaNodeManager.cs` (real condition nodes + methods),
  `Runtime/OpcUa/OpcUaPublishActor.cs` (richer alarm message), security gate,
  `AdminUI/Components/Pages/ScriptedAlarms.razor` (ack/shelve control).

**Out of scope:** virtual-tag historization production sink (Gap 5 / B.6 — separate);
Phase-7 Playwright E2E (F.7).

**Sequencing:** Layer 0 is the low-risk foundation and independently shippable. Layer 1
is the self-contained "alarms work" payoff. Layer 2 is the SDK epic — largest, highest
risk, most live-verification dependent.