diff --git a/docs/plans/2026-06-10-script-log-and-scripted-alarm-runtime-design.md b/docs/plans/2026-06-10-script-log-and-scripted-alarm-runtime-design.md new file mode 100644 index 00000000..88911210 --- /dev/null +++ b/docs/plans/2026-06-10-script-log-and-scripted-alarm-runtime-design.md @@ -0,0 +1,229 @@ +# 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`. +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.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.