lmxopcua/docs/v2/implementation/exit-gate-phase-7.md

Phase 7 Exit Gate — Scripting, Virtual Tags, Scripted Alarms, Historian Sink

Status: FULLY CLOSED 2026-04-23 audit — the three original follow-ups (#239 / #240 / #241) were all shipped under later branches but this exit-gate doc wasn't updated at the time. All three verified against the repo + tests green.

Compliance script: scripts/compliance/phase-7-compliance.ps1 Plan doc: docs/v2/implementation/phase-7-scripting-and-alarming.md

What shipped

Stream	PR	Summary
A	#177–#179	Core.Scripting — Roslyn sandbox + DependencyExtractor + ForbiddenTypeAnalyzer + per-script Serilog sink + 63 tests
B	#180	Core.VirtualTags — dep graph (iterative Tarjan) + engine + timer scheduler + VirtualTagSource + 36 tests
C	#181	Core.ScriptedAlarms — Part 9 state machine + predicate engine + message template + ScriptedAlarmSource + 47 tests
D	#182	Core.AlarmHistorian — SQLite store-and-forward + backoff ladder + dead-letter retention + Galaxy.Host IPC contracts + 14 tests
E	#183	Config DB schema — Script / VirtualTag / ScriptedAlarm / ScriptedAlarmState entities + migration + 12 tests
F	#185	Admin UI — ScriptService / VirtualTagService / ScriptedAlarmService / ScriptTestHarnessService / HistorianDiagnosticsService + Monaco editor + /alarms/historian page + 13 tests
G	#184	Walker emits Virtual + ScriptedAlarm variables with NodeSourceKind discriminator + 5 tests
G follow-up	#186	DriverNodeManager dispatch routes by NodeSourceKind + writes rejected for non-Driver sources + 7 tests

Phase 7 totals: ~197 new tests across 7 projects. Plan decisions #1–#22 all realised in code.

Compliance Checks (run at exit gate)

Covered by scripts/compliance/phase-7-compliance.ps1:

• Roslyn sandbox anchored on ScriptContext assembly with ForbiddenTypeAnalyzer defense-in-depth (plan #6)
• DependencyExtractor rejects non-literal tag paths with source spans (plan #7)
• Per-script rolling Serilog sink + companion-forwarding Error+ to main log (plan #12)
• VirtualTag dep graph uses iterative SCC — no stack overflow on 10 000-deep chains
• VirtualTagSource implements IReadable + ISubscribable per ADR-002
• Part 9 state machine covers every transition (Apply/Ack/Confirm/Shelve/Unshelve/Enable/Disable/Comment/ShelvingCheck)
• AlarmPredicateContext rejects SetVirtualTag at runtime (predicates must be pure)
• MessageTemplate substitutes {TagPath} tokens at event emission (plan #13); missing/bad → {?}
• SQLite sink backoff ladder 1s → 2s → 5s → 15s → 60s cap (plan #16)
• Default 1M-row capacity + 30-day dead-letter retention (plan #21)
• Per-event outcomes Ack/RetryPlease/PermanentFail on the wire
• Galaxy.Host IPC contracts (HistorianAlarmEventRequest / Response / ConnectivityStatusNotification)
• Config DB check constraints: trigger-required, timer-min, severity-range, alarm-type-enum, JSON comments
• ScriptedAlarmState keyed on ScriptedAlarmId (not generation-scoped) per plan #14
• Admin services: SourceHash preserves compile-cache hit on rename; Update recomputes on source change
• ScriptTestHarnessService enforces declared-inputs-only contract (plan #22)
• Monaco editor via CDN + textarea fallback (plan #18)
• /alarms/historian page with Retry-dead-lettered operator action
• Walker emits NodeSourceKind.Virtual + NodeSourceKind.ScriptedAlarm variables
• DriverNodeManager dispatch routes Reads by source; Writes to non-Driver rejected with BadUserAccessDenied (plan #6)

Deferred to Post-Gate Follow-ups (all closed as of 2026-04-23 audit)

Originally kept out of the capstone so the gate could close cleanly. Each landed as a targeted follow-up PR; audit this session verified them against the repo:

• SealedBootstrap composition root (task #239) — CLOSED. src/Server/ZB.MOM.WW.OtOpcUa.Server/Phase7/Phase7Composer.cs instantiates VirtualTagEngine + ScriptedAlarmEngine via Phase7EngineComposer.Compose, and SqliteStoreAndForwardSink in ResolveHistorianSink when a registered driver provides IAlarmHistorianWriter (today: GalaxyProxyDriver). OpcUaServerService.ExecuteAsync calls Phase7Composer.PrepareAsync then OpcUaApplicationHost.SetPhase7Sources before applicationHost.StartAsync so OtOpcUaServer + DriverNodeManager capture the VirtualReadable / ScriptedAlarmReadable at construction. 38 tests green under tests/Server/ZB.MOM.WW.OtOpcUa.Server.Tests/Phase7/ + SealedBootstrapIntegrationTests. The work landed under the label "Phase 7 follow-up #246" and was never re-labelled against #239.
• Live OPC UA end-to-end smoke (task #240) — CLOSED. scripts/e2e/test-phase7-virtualtags.ps1 drives a full Client.CLI read of a driver-sourced input, reads the VirtualTag computed off it, triggers a scripted alarm by writing the trigger value, and subscribes to the alarm condition — all through a running OtOpcUa server. Covered in scripts/e2e/test-all.ps1 + scripts/e2e/README.md matrix.
• sp_ComputeGenerationDiff extension (task #241) — CLOSED. Migration 20260420232000_ExtendComputeGenerationDiffWithPhase7.cs extends the stored proc to emit Script / VirtualTag / ScriptedAlarm sections alongside the existing NodeAcl / Tag / Equipment / DriverInstance / Namespace output. Admin DiffViewer picks them up through its existing section-plugin architecture (Phase 6.4 Stream C).

Completion Checklist

• Stream A shipped + merged
• Stream B shipped + merged
• Stream C shipped + merged
• Stream D shipped + merged
• Stream E shipped + merged
• Stream F shipped + merged
• Stream G shipped + merged
• Stream G follow-up (dispatch) shipped + merged
• phase-7-compliance.ps1 present and passes
• Full solution dotnet test passes (no new failures beyond pre-existing tolerated CLI flake)
• Exit-gate doc checked in
• SealedBootstrap composition follow-up shipped (#239 / Phase 7 follow-up #246)
• Live end-to-end smoke follow-up shipped (#240 — scripts/e2e/test-phase7-virtualtags.ps1)
• sp_ComputeGenerationDiff extension follow-up shipped (#241 — migration ExtendComputeGenerationDiffWithPhase7)

How to run

pwsh ./scripts/compliance/phase-7-compliance.ps1

Exit code 0 = all pass; non-zero = failures listed in the preceding [FAIL] lines.