Phase 7 Stream B — Core.VirtualTags project (engine + dep graph + timer + source)

Ships the evaluation engine that consumes compiled scripts from Stream A, subscribes to upstream driver tags, runs on change + on timer, cascades evaluations through dependent virtual tags in topological order, and emits changes through a driver-capability-shaped adapter the DriverNodeManager can dispatch to per ADR-002.

DependencyGraph owns the directed dep-graph where nodes are tag paths (driver tags implicit leaves, virtual tags registered internal nodes) and edges run from a virtual tag to each tag it reads. Kahn algorithm produces the topological sort. Tarjan iterative SCC detects every cycle in one pass so publish-time rejection surfaces all offending cycles together. Both iterative so 10k-deep chains do not StackOverflow. Re-adding a node overwrites prior dependency set cleanly (supports config-publish reloads).

VirtualTagDefinition is the operator-authored config row (Path, DataType, ScriptSource, ChangeTriggered, TimerInterval, Historize). Stream E config DB materializes these on publish.

ITagUpstreamSource is the abstraction the engine pulls driver tag values from. Stream G bridges this to IReadable + ISubscribable on live drivers; tests use FakeUpstream that tracks subscription count for leak-test assertions.

IHistoryWriter is the per-tag Historize sink. NullHistoryWriter default when caller does not pass one.

VirtualTagContext is the per-evaluation ScriptContext. Reads from engine last-known-value cache, writes route through SetVirtualTag callback so cross-tag side effects participate in change cascades. Injectable Now clock for deterministic tests.

VirtualTagEngine orchestrates. Load compiles every script via ScriptSandbox, builds the dep graph via DependencyExtractor, checks for cycles, reports every compile failure in one error, subscribes to each referenced upstream path, seeds the value cache. EvaluateAllAsync runs topological order. EvaluateOneAsync is timer path. Read returns cached value. Subscribe registers observer. OnUpstreamChange updates cache, fans out, schedules transitive dependents (change-driven=false tags skipped). EvaluateInternalAsync holds a SemaphoreSlim so cascades do not interleave. Script exceptions and timeouts map per-tag to BadInternalError. Coercion from script double to config Int32 uses Convert.ToInt32.

TimerTriggerScheduler groups tags by interval into shared Timers. Tags without TimerInterval not scheduled.

VirtualTagSource implements IReadable + ISubscribable per ADR-002. ReadAsync returns cache. SubscribeAsync fires initial-data callback per OPC UA convention. IWritable deliberately not implemented — OPC UA writes to virtual tags rejected in DriverNodeManager per Phase 7 decision 6.

36 unit tests across 4 files: DependencyGraphTests 12, VirtualTagEngineTests 13, VirtualTagSourceTests 6, TimerTriggerSchedulerTests 4. Coverage includes cycle detection (self-loop, 2-node, 3-node, multiple disjoint), 2-level change cascade, per-tag error isolation (one tag throws, others keep working), timeout isolation, Historize toggle, ChangeTriggered=false ignore, reload cleans subscriptions, Dispose releases resources, SetVirtualTag fires observers, type coercion, 10k deep graph no stack overflow, initial-data callback, Unsubscribe stops events.

Fixed two bugs during implementation. Monitor.Enter/Exit cannot be held across await (Monitor ownership is thread-local and lost across suspension) — switched to SemaphoreSlim. Kahn edge-direction was inverted — for dependency ordering (X depends on Y means Y comes before X) in-degree should be count of a node own deps, not count of nodes pointing to it; was incrementing inDegree[dep] instead of inDegree[nodeId], causing false cycle detection on valid DAGs.

Full Phase 7 test count after Stream B: 99 green (63 Scripting + 36 VirtualTags). Streams C and G will plug engine + source into live OPC UA dispatch path.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

CLAUDE.md

@@ -87,13 +87,14 @@ The server supports non-transparent warm/hot redundancy via the `Redundancy` sec
 
 ## LDAP Authentication
 
-The server uses LDAP-based user authentication via the `Authentication.Ldap` section in `appsettings.json`. When enabled, credentials are validated by LDAP bind against a GLAuth server (installed at `C:\publish\glauth\`), and LDAP group membership maps to OPC UA permissions: `ReadOnly` (browse/read), `WriteOperate` (write FreeAccess/Operate attributes), `WriteTune` (write Tune attributes), `WriteConfigure` (write Configure attributes), `AlarmAck` (alarm acknowledgment). `LdapAuthenticationProvider` implements both `IUserAuthenticationProvider` and `IRoleProvider`. See `docs/Security.md` for the full guide and `C:\publish\glauth\auth.md` for LDAP user/group reference.
+The server uses LDAP-based user authentication via the `Authentication.Ldap` section in `appsettings.json`. When enabled, credentials are validated by LDAP bind against a GLAuth server (installed at `C:\publish\glauth\`), and LDAP group membership maps to OPC UA permissions: `ReadOnly` (browse/read), `WriteOperate` (write FreeAccess/Operate attributes), `WriteTune` (write Tune attributes), `WriteConfigure` (write Configure attributes), `AlarmAck` (alarm acknowledgment). `LdapUserAuthenticator` (`src/ZB.MOM.WW.OtOpcUa.Server/Security/LdapUserAuthenticator.cs`) implements `IUserAuthenticator`. See `docs/Security.md` for the full guide and `C:\publish\glauth\auth.md` for LDAP user/group reference.
 
 ## Library Preferences
 
 - **Logging**: Serilog with rolling daily file sink
 - **Unit tests**: xUnit + Shouldly for assertions
-- **Service hosting**: TopShelf (Windows service install/uninstall/run as console)
+- **Service hosting (Server, Admin)**: .NET generic host with `AddWindowsService` (decision #30 — replaced TopShelf in v2; see `src/ZB.MOM.WW.OtOpcUa.Server/OpcUaServerService.cs`)
+- **Service hosting (Galaxy.Host)**: plain console app wrapped by NSSM (`.NET Framework 4.8 x86` — required by MXAccess COM bitness)
 - **OPC UA**: OPC Foundation UA .NET Standard stack (https://github.com/opcfoundation/ua-.netstandard) — NuGet: `OPCFoundation.NetStandard.Opc.Ua.Server`
 
 ## OPC UA .NET Standard Documentation

ZB.MOM.WW.OtOpcUa.slnx

@@ -3,6 +3,8 @@
         <Project Path="src/ZB.MOM.WW.OtOpcUa.Core.Abstractions/ZB.MOM.WW.OtOpcUa.Core.Abstractions.csproj"/>
         <Project Path="src/ZB.MOM.WW.OtOpcUa.Configuration/ZB.MOM.WW.OtOpcUa.Configuration.csproj"/>
         <Project Path="src/ZB.MOM.WW.OtOpcUa.Core/ZB.MOM.WW.OtOpcUa.Core.csproj"/>
+        <Project Path="src/ZB.MOM.WW.OtOpcUa.Core.Scripting/ZB.MOM.WW.OtOpcUa.Core.Scripting.csproj"/>
+        <Project Path="src/ZB.MOM.WW.OtOpcUa.Core.VirtualTags/ZB.MOM.WW.OtOpcUa.Core.VirtualTags.csproj"/>
         <Project Path="src/ZB.MOM.WW.OtOpcUa.Server/ZB.MOM.WW.OtOpcUa.Server.csproj"/>
         <Project Path="src/ZB.MOM.WW.OtOpcUa.Admin/ZB.MOM.WW.OtOpcUa.Admin.csproj"/>
         <Project Path="src/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Shared/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Shared.csproj"/>
@@ -14,6 +16,8 @@
         <Project Path="src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.csproj"/>
         <Project Path="src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.csproj"/>
         <Project Path="src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.csproj"/>
+        <Project Path="src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared.csproj"/>
+        <Project Path="src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Host/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Host.csproj"/>
         <Project Path="src/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.csproj"/>
         <Project Path="src/ZB.MOM.WW.OtOpcUa.Client.Shared/ZB.MOM.WW.OtOpcUa.Client.Shared.csproj"/>
         <Project Path="src/ZB.MOM.WW.OtOpcUa.Client.CLI/ZB.MOM.WW.OtOpcUa.Client.CLI.csproj"/>
@@ -24,6 +28,8 @@
         <Project Path="tests/ZB.MOM.WW.OtOpcUa.Core.Abstractions.Tests/ZB.MOM.WW.OtOpcUa.Core.Abstractions.Tests.csproj"/>
         <Project Path="tests/ZB.MOM.WW.OtOpcUa.Configuration.Tests/ZB.MOM.WW.OtOpcUa.Configuration.Tests.csproj"/>
         <Project Path="tests/ZB.MOM.WW.OtOpcUa.Core.Tests/ZB.MOM.WW.OtOpcUa.Core.Tests.csproj"/>
+        <Project Path="tests/ZB.MOM.WW.OtOpcUa.Core.Scripting.Tests/ZB.MOM.WW.OtOpcUa.Core.Scripting.Tests.csproj"/>
+        <Project Path="tests/ZB.MOM.WW.OtOpcUa.Core.VirtualTags.Tests/ZB.MOM.WW.OtOpcUa.Core.VirtualTags.Tests.csproj"/>
         <Project Path="tests/ZB.MOM.WW.OtOpcUa.Server.Tests/ZB.MOM.WW.OtOpcUa.Server.Tests.csproj"/>
         <Project Path="tests/ZB.MOM.WW.OtOpcUa.Admin.Tests/ZB.MOM.WW.OtOpcUa.Admin.Tests.csproj"/>
         <Project Path="tests/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Shared.Tests/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Shared.Tests.csproj"/>
@@ -34,12 +40,18 @@
         <Project Path="tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.Tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.Tests.csproj"/>
         <Project Path="tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests.csproj"/>
         <Project Path="tests/ZB.MOM.WW.OtOpcUa.Driver.S7.Tests/ZB.MOM.WW.OtOpcUa.Driver.S7.Tests.csproj"/>
+        <Project Path="tests/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests.csproj"/>
         <Project Path="tests/ZB.MOM.WW.OtOpcUa.Driver.AbCip.Tests/ZB.MOM.WW.OtOpcUa.Driver.AbCip.Tests.csproj"/>
         <Project Path="tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.Tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.Tests.csproj"/>
+        <Project Path="tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests.csproj"/>
         <Project Path="tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Tests.csproj"/>
+        <Project Path="tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests.csproj"/>
         <Project Path="tests/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Tests/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Tests.csproj"/>
+        <Project Path="tests/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared.Tests/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared.Tests.csproj"/>
+        <Project Path="tests/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Host.Tests/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Host.Tests.csproj"/>
         <Project Path="tests/ZB.MOM.WW.OtOpcUa.Driver.AbCip.IntegrationTests/ZB.MOM.WW.OtOpcUa.Driver.AbCip.IntegrationTests.csproj"/>
         <Project Path="tests/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Tests/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Tests.csproj"/>
+        <Project Path="tests/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.IntegrationTests/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.IntegrationTests.csproj"/>
         <Project Path="tests/ZB.MOM.WW.OtOpcUa.Client.Shared.Tests/ZB.MOM.WW.OtOpcUa.Client.Shared.Tests.csproj"/>
         <Project Path="tests/ZB.MOM.WW.OtOpcUa.Client.CLI.Tests/ZB.MOM.WW.OtOpcUa.Client.CLI.Tests.csproj"/>
         <Project Path="tests/ZB.MOM.WW.OtOpcUa.Client.UI.Tests/ZB.MOM.WW.OtOpcUa.Client.UI.Tests.csproj"/>

docs/Client.CLI.md

@@ -14,7 +14,7 @@ dotnet build
 dotnet run -- <command> [options]
 ```
 
-The executable name is still `lmxopcua-cli` — a residual from the pre-v2 rename (`Program.cs:SetExecutableName`). Scripts + operator muscle memory depend on the name; flipping it to `otopcua-cli` is a follow-up that also needs to move the client-side PKI store folder (<code>{LocalAppData}/LmxOpcUaClient/pki/</code> — used by the shared client for its application certificate) so trust relationships survive the rename.
+The executable name is `otopcua-cli`. Dev boxes carrying a pre-task-#208 install may still have the legacy `{LocalAppData}/LmxOpcUaClient/` folder on disk; on first launch of any post-#208 CLI or UI build, `ClientStoragePaths` (`src/ZB.MOM.WW.OtOpcUa.Client.Shared/ClientStoragePaths.cs`) migrates it to `{LocalAppData}/OtOpcUaClient/` automatically so trusted certificates + saved settings survive the rename.
 
 ## Architecture
 
@@ -46,7 +46,7 @@ All commands accept these options:
 When `-U` and `-P` are provided, the shared service passes a `UserIdentity(username, password)` to the OPC UA session. Without credentials, anonymous identity is used.
 
 ```bash
-lmxopcua-cli write -u opc.tcp://localhost:4840 -n "ns=2;s=MyNode" -v 42 -U operator -P op123
+otopcua-cli write -u opc.tcp://localhost:4840 -n "ns=2;s=MyNode" -v 42 -U operator -P op123
 ```
 
 ### Failover
@@ -54,20 +54,20 @@ lmxopcua-cli write -u opc.tcp://localhost:4840 -n "ns=2;s=MyNode" -v 42 -U opera
 When `-F` is provided, the shared service tries the primary URL first, then each failover URL in order. For long-running commands (`subscribe`, `alarms`), the service monitors the session via keep-alive and automatically reconnects to the next available server on failure.
 
 ```bash
-lmxopcua-cli connect -u opc.tcp://localhost:4840/OtOpcUa -F opc.tcp://localhost:4841/OtOpcUa
+otopcua-cli connect -u opc.tcp://localhost:4840/OtOpcUa -F opc.tcp://localhost:4841/OtOpcUa
 ```
 
 ### Transport Security
 
 When `sign` or `encrypt` is specified, the shared service:
 
-1. Ensures a client application certificate exists under `{LocalAppData}/LmxOpcUaClient/pki/` (auto-created if missing)
+1. Ensures a client application certificate exists under `{LocalAppData}/OtOpcUaClient/pki/` (auto-created if missing; pre-rename `LmxOpcUaClient/` is migrated in place on first launch)
 2. Discovers server endpoints and selects one matching the requested security mode
 3. Prefers `Basic256Sha256` when multiple matching endpoints exist
 4. Fails with a clear error if no matching endpoint is found
 
 ```bash
-lmxopcua-cli browse -u opc.tcp://localhost:4840/OtOpcUa -S encrypt -U admin -P secret -r -d 2
+otopcua-cli browse -u opc.tcp://localhost:4840/OtOpcUa -S encrypt -U admin -P secret -r -d 2
 ```
 
 ### Verbose Logging
@@ -81,7 +81,7 @@ The `--verbose` flag switches Serilog output from `Warning` to `Debug` level, sh
 Tests connectivity to an OPC UA server. Creates a session, prints connection metadata, and disconnects.
 
 ```bash
-lmxopcua-cli connect -u opc.tcp://localhost:4840/OtOpcUa -U admin -P admin123
+otopcua-cli connect -u opc.tcp://localhost:4840/OtOpcUa -U admin -P admin123
 ```
 
 Output:
@@ -99,7 +99,7 @@ Connection successful.
 Reads the current value of a single node and prints the value, status code, and timestamps.
 
 ```bash
-lmxopcua-cli read -u opc.tcp://localhost:4840/OtOpcUa -n "ns=3;s=DEV.ScanState" -U admin -P admin123
+otopcua-cli read -u opc.tcp://localhost:4840/OtOpcUa -n "ns=3;s=DEV.ScanState" -U admin -P admin123
 ```
 
 | Flag | Description |
@@ -121,7 +121,7 @@ Server Time: 2026-03-30T19:58:38.0971257Z
 Writes a value to a node. The shared service reads the current value first to determine the target data type, then converts the supplied string value using `ValueConverter.ConvertValue()`.
 
 ```bash
-lmxopcua-cli write -u opc.tcp://localhost:4840 -n "ns=2;s=MyNode" -v 42
+otopcua-cli write -u opc.tcp://localhost:4840 -n "ns=2;s=MyNode" -v 42
 ```
 
 | Flag | Description |
@@ -135,10 +135,10 @@ Browses the OPC UA address space starting from the Objects folder or a specified
 
 ```bash
 # Browse top-level Objects folder
-lmxopcua-cli browse -u opc.tcp://localhost:4840/OtOpcUa -U admin -P admin123
+otopcua-cli browse -u opc.tcp://localhost:4840/OtOpcUa -U admin -P admin123
 
 # Browse a specific node recursively to depth 3
-lmxopcua-cli browse -u opc.tcp://localhost:4840/OtOpcUa -U admin -P admin123 -r -d 3 -n "ns=3;s=ZB"
+otopcua-cli browse -u opc.tcp://localhost:4840/OtOpcUa -U admin -P admin123 -r -d 3 -n "ns=3;s=ZB"
 ```
 
 | Flag | Description |
@@ -152,7 +152,7 @@ lmxopcua-cli browse -u opc.tcp://localhost:4840/OtOpcUa -U admin -P admin123 -r
 Monitors a node for value changes using OPC UA subscriptions. Prints each data change notification with timestamp, value, and status code. Runs until Ctrl+C, then unsubscribes and disconnects cleanly.
 
 ```bash
-lmxopcua-cli subscribe -u opc.tcp://localhost:4840 -n "ns=2;s=MyNode" -i 500
+otopcua-cli subscribe -u opc.tcp://localhost:4840 -n "ns=2;s=MyNode" -i 500
 ```
 
 | Flag | Description |
@@ -166,12 +166,12 @@ Reads historical data from a node. Supports raw history reads and aggregate (pro
 
 ```bash
 # Raw history
-lmxopcua-cli historyread -u opc.tcp://localhost:4840/OtOpcUa \
+otopcua-cli historyread -u opc.tcp://localhost:4840/OtOpcUa \
   -n "ns=1;s=TestMachine_001.TestHistoryValue" \
   --start "2026-03-25" --end "2026-03-30"
 
 # Aggregate: 1-hour average
-lmxopcua-cli historyread -u opc.tcp://localhost:4840/OtOpcUa \
+otopcua-cli historyread -u opc.tcp://localhost:4840/OtOpcUa \
   -n "ns=1;s=TestMachine_001.TestHistoryValue" \
   --start "2026-03-25" --end "2026-03-30" \
   --aggregate Average --interval 3600000
@@ -203,10 +203,10 @@ Subscribes to alarm events on a node. Prints structured alarm output including s
 
 ```bash
 # Subscribe to alarm events on the Server node
-lmxopcua-cli alarms -u opc.tcp://localhost:4840/OtOpcUa
+otopcua-cli alarms -u opc.tcp://localhost:4840/OtOpcUa
 
 # Subscribe to a specific source node with condition refresh
-lmxopcua-cli alarms -u opc.tcp://localhost:4840/OtOpcUa \
+otopcua-cli alarms -u opc.tcp://localhost:4840/OtOpcUa \
   -n "ns=1;s=TestMachine_001" --refresh
 ```
 
@@ -221,7 +221,7 @@ lmxopcua-cli alarms -u opc.tcp://localhost:4840/OtOpcUa \
 Reads the OPC UA redundancy state from a server: redundancy mode, service level, server URIs, and application URI.
 
 ```bash
-lmxopcua-cli redundancy -u opc.tcp://localhost:4840/OtOpcUa -U admin -P admin123
+otopcua-cli redundancy -u opc.tcp://localhost:4840/OtOpcUa -U admin -P admin123
 ```
 
 Example output:

docs/Client.UI.md

@@ -65,7 +65,7 @@ The top bar provides the endpoint URL, Connect, and Disconnect buttons. The **Co
 
 ### Settings Persistence
 
-Connection settings are saved to `{LocalAppData}/LmxOpcUaClient/settings.json` after each successful connection and on window close. The folder name is a residual from the pre-v2 rename (the `Client.Shared` session factory still calls itself `LmxOpcUaClient` at `OpcUaClientService.cs:428`); renaming to `OtOpcUaClient` is a follow-up that needs a migration shim so existing users don't lose their settings on upgrade. The settings are reloaded on next launch, including:
+Connection settings are saved to `{LocalAppData}/OtOpcUaClient/settings.json` after each successful connection and on window close. Dev boxes upgrading from a pre-task-#208 build still have the legacy `LmxOpcUaClient/` folder on disk; `ClientStoragePaths` in `Client.Shared` moves it to the canonical path on first launch so existing trusted certs + saved settings persist without operator action. The settings are reloaded on next launch, including:
 
 - All connection parameters
 - Active subscription node IDs (restored after reconnection)

docs/drivers/AbLegacy-Test-Fixture.md

@@ -0,0 +1,125 @@
+# AB Legacy test fixture
+
+Coverage map + gap inventory for the AB Legacy (PCCC) driver — SLC 500 /
+MicroLogix / PLC-5 / LogixPccc-mode.
+
+**TL;DR:** Docker integration-test scaffolding lives at
+`tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests/` (task #224),
+reusing the AB CIP `ab_server` image in PCCC mode with per-family
+compose profiles (`slc500` / `micrologix` / `plc5`). Scaffold passes
+the skip-when-absent contract cleanly. **Wire-level round-trip against
+`ab_server` PCCC mode currently fails** with `BadCommunicationError`
+on read/write (verified 2026-04-20) — ab_server's PCCC server-side
+coverage is narrower than libplctag's PCCC client expects. The smoke
+tests target the correct shape for real hardware + should pass when
+`AB_LEGACY_ENDPOINT` points at a real SLC 5/05 / MicroLogix. Unit tests
+via `FakeAbLegacyTag` still carry the contract coverage.
+
+## What the fixture is
+
+**Integration layer** (task #224, scaffolded with a known ab_server
+gap):
+`tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests/` with
+`AbLegacyServerFixture` (TCP-probes `localhost:44818`) + three smoke
+tests (parametric read across families, SLC500 write-then-read). Reuses
+the AB CIP `otopcua-ab-server:libplctag-release` image via a relative
+`build:` context in `Docker/docker-compose.yml` — one image, different
+`--plc` flags. See `Docker/README.md` §Known limitations for the
+ab_server PCCC round-trip gap + resolution paths.
+
+**Unit layer**: `tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.Tests/` is
+still the primary coverage. All tests tagged `[Trait("Category", "Unit")]`.
+The driver accepts `IAbLegacyTagFactory` via ctor DI; every test
+supplies a `FakeAbLegacyTag`.
+
+## What it actually covers (unit only)
+
+- `AbLegacyAddressTests` — PCCC address parsing for SLC / MicroLogix / PLC-5
+  / LogixPccc-mode (`N7:0`, `F8:12`, `B3:0/5`, etc.)
+- `AbLegacyCapabilityTests` — data type mapping, read-only enforcement
+- `AbLegacyReadWriteTests` — read + write happy + error paths against the fake
+- `AbLegacyBitRmwTests` — bit-within-DINT read-modify-write serialization via
+  per-parent `SemaphoreSlim` (mirrors the AB CIP + FOCAS PMC-bit pattern from #181)
+- `AbLegacyHostAndStatusTests` — probe + host-status transitions driven by
+  fake-returned statuses
+- `AbLegacyDriverTests` — `IDriver` lifecycle
+
+Capability surfaces whose contract is verified: `IDriver`, `IReadable`,
+`IWritable`, `ITagDiscovery`, `ISubscribable`, `IHostConnectivityProbe`,
+`IPerCallHostResolver`.
+
+## What it does NOT cover
+
+### 1. Wire-level PCCC
+
+No PCCC frame is sent by the test suite. libplctag's PCCC subset (DF1,
+ControlNet-over-EtherNet, PLC-5 native EtherNet) is untested here;
+driver-side correctness depends on libplctag being correct.
+
+### 2. Family-specific behavior
+
+- SLC 500 timeout + retry thresholds (SLC's comm module has known slow-response
+  edges) — unit fakes don't simulate timing.
+- MicroLogix 1100 / 1400 max-connection-count limits — not stressed.
+- PLC-5 native EtherNet connection setup (PCCC-encapsulated-in-CIP vs raw
+  CSPv4) — routing covered at parse level only.
+
+### 3. Multi-device routing
+
+`IPerCallHostResolver` contract is verified; real PCCC wire routing across
+multiple gateways is not.
+
+### 4. Alarms / history
+
+PCCC has no alarm object + no history object. Driver doesn't implement
+`IAlarmSource` or `IHistoryProvider` — no test coverage is the correct shape.
+
+### 5. File-type coverage
+
+PCCC has many file types (N, F, B, T, C, R, S, ST, A) — the parser tests
+cover the common ones but uncommon ones (`R` counters, `S` status files,
+`A` ASCII strings) have thin coverage.
+
+## When to trust AB Legacy tests, when to reach for a rig
+
+| Question | Unit tests | Real PLC |
+| --- | --- | --- |
+| "Does `N7:0/5` parse correctly?" | yes | - |
+| "Does bit-in-word RMW serialize concurrent writers?" | yes | yes |
+| "Does the driver lifecycle hang / crash?" | yes | yes |
+| "Does a real read against an SLC 500 return correct bytes?" | no | yes (required) |
+| "Does MicroLogix 1100 respect its connection-count cap?" | no | yes (required) |
+| "Do PLC-5 ST-files round-trip correctly?" | no | yes (required) |
+
+## Follow-up candidates
+
+1. **Fix ab_server PCCC coverage upstream** — the scaffold lands the
+   Docker infrastructure; the wire-level round-trip gap is in ab_server
+   itself. Filing a patch to `libplctag/libplctag` to expand PCCC
+   server-side opcode coverage would make the scaffolded smoke tests
+   pass without a golden-box tier.
+2. **Rockwell RSEmulate 500 golden-box tier** — Rockwell's real emulator
+   for SLC/MicroLogix/PLC-5. Would close UDT-equivalent (integer-file
+   indirection), timer/counter decomposition, and real ladder execution
+   gaps. Costs: RSLinx OEM license, Windows-only, Hyper-V conflict
+   matching TwinCAT XAR + Logix Emulate, no clean PR-diffable project
+   format (SLC/ML save as binary `.RSS`). Scaffold like the Logix
+   Emulate tier when operationally worth it.
+3. **Lab rig** — used SLC 5/05 or MicroLogix 1100 on a dedicated
+   network; parts are end-of-life but still available. PLC-5 +
+   LogixPccc-mode behaviour + DF1 serial need specific controllers.
+
+## Key fixture / config files
+
+- `tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests/AbLegacyServerFixture.cs`
+  — TCP probe + skip attributes + env-var parsing
+- `tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests/AbLegacyReadSmokeTests.cs`
+  — three wire-level smoke tests (currently blocked by ab_server PCCC gap)
+- `tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests/Docker/docker-compose.yml`
+  — compose profiles reusing AB CIP Dockerfile
+- `tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests/Docker/README.md`
+  — known-limitations write-up + resolution paths
+- `tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.Tests/FakeAbLegacyTag.cs` —
+  in-process fake + factory
+- `src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/AbLegacyDriver.cs` — scope remarks
+  at the top of the file

docs/drivers/AbServer-Test-Fixture.md

@@ -0,0 +1,216 @@
+# ab_server test fixture
+
+Coverage map + gap inventory for the AB CIP integration fixture backed by
+libplctag's `ab_server` simulator.
+
+**TL;DR:** `ab_server` is a connectivity + atomic-read smoke harness for the AB
+CIP driver. It does **not** benchmark UDTs, alarms, or any family-specific
+quirk. UDT / alarm / quirk behavior is verified only by unit tests with
+`FakeAbCipTagRuntime`.
+
+## What the fixture is
+
+- **Binary**: `ab_server` — a C program in libplctag's
+  `src/tools/ab_server/` ([libplctag/libplctag](https://github.com/libplctag/libplctag),
+  MIT).
+- **Launcher**: Docker (only supported path). `Docker/Dockerfile`
+  multi-stage-builds `ab_server` from source against a pinned libplctag
+  tag + copies the binary into a slim runtime image.
+  `Docker/docker-compose.yml` has per-family services (`controllogix`
+  / `compactlogix` / `micro800` / `guardlogix`); all bind `:44818`.
+- **Lifecycle**: `AbServerFixture` TCP-probes `127.0.0.1:44818` at
+  collection init + records a skip reason when unreachable. Tests skip
+  via `[AbServerFact]` / `[AbServerTheory]` which check the same probe.
+- **Profiles**: `KnownProfiles.{ControlLogix, CompactLogix, Micro800, GuardLogix}`
+  in `AbServerProfile.cs` — thin Family + ComposeProfile + Notes records;
+  the compose file is the canonical source of truth for which tags get
+  seeded + which `--plc` mode the simulator boots in.
+- **Tests**: one smoke, `AbCipReadSmokeTests.Driver_reads_seeded_DInt_from_ab_server`,
+  parametrized over all four profiles via `[AbServerTheory]` + `[MemberData]`.
+- **Endpoint override**: `AB_SERVER_ENDPOINT=host:port` points the
+  fixture at a real PLC instead of the local container.
+
+## What it actually covers
+
+- Read path: driver → libplctag → CIP-over-EtherNet/IP → simulator → back.
+- Atomic Logix types per seed: `DINT`, `REAL`, `BOOL`, `SINT`, `STRING`.
+- One `DINT[16]` array tag (ControlLogix profile only).
+- `--plc controllogix` and `--plc compactlogix` mode dispatch.
+- The skip-on-missing-binary behavior (`AbServerFactAttribute`) so a fresh
+  clone without the simulator stays green.
+
+## What it does NOT cover
+
+Each gap below is either stated explicitly in the profile's `Notes` field or
+inferable from the seed-tag set + smoke-test surface.
+
+### 1. UDTs / CIP Template Object (class 0x6C)
+
+ControlLogix profile `Notes`: *"ab_server lacks full UDT emulation."*
+
+Unverified against `ab_server`:
+
+- PR 6 structured read/write (`AbCipStructureMember` fan-out)
+- #179 Template Object shape reader (`CipTemplateObjectDecoder` + `FetchUdtShapeAsync`)
+- #194 whole-UDT read optimization (`AbCipUdtReadPlanner` +
+  `AbCipUdtMemberLayout` + the `ReadGroupAsync` path in `AbCipDriver`)
+
+Unit coverage: `AbCipFetchUdtShapeTests`, `CipTemplateObjectDecoderTests`,
+`AbCipUdtMemberLayoutTests`, `AbCipUdtReadPlannerTests`,
+`AbCipDriverWholeUdtReadTests` — all with golden Template-Object byte buffers
++ offset-keyed `FakeAbCipTag` values.
+
+### 2. ALMD / ALMA alarm projection (#177)
+
+Depends on the ALMD UDT shape, which `ab_server` cannot emulate. The
+`OnAlarmEvent` raise/clear path + ack-write semantics are not exercised
+end-to-end.
+
+Unit coverage: `AbCipAlarmProjectionTests` — fakes feed `InFaulted` /
+`Severity` via `ValuesByOffset` + assert the emitted `AlarmEventArgs`.
+
+### 3. Micro800 unconnected-only path
+
+Micro800 profile `Notes`: *"ab_server has no --plc micro800 — falls back to
+controllogix emulation."*
+
+The empty routing path + unconnected-session requirement (PR 11) is unit-tested
+but never challenged at the CIP wire level. Real Micro800 (2080-series) on a
+lab rig would be the authoritative benchmark.
+
+### 4. GuardLogix safety subsystem
+
+GuardLogix profile `Notes`: *"ab_server doesn't emulate the safety
+subsystem."*
+
+Only the `_S`-suffix naming classifier (PR 12, `SecurityClassification.ViewOnly`
+forced on safety tags) runs. Actual safety-partition write rejection — what
+happens when a non-safety write lands on a real `1756-L8xS` — is not exercised.
+
+### 5. CompactLogix narrow ConnectionSize cap
+
+CompactLogix profile `Notes`: *"ab_server lacks the narrower limit itself."*
+
+Driver-side `AbCipPlcFamilyProfile` caps `ConnectionSize` at the CompactLogix
+value per PR 10, but `ab_server` accepts whatever the client asks for — the
+cap's correctness is trusted from its unit test, never stressed against a
+simulator that rejects oversized requests.
+
+### 6. BOOL-within-DINT read-modify-write (#181)
+
+The `AbCipDriver.WriteBitInDIntAsync` RMW path + its per-parent `SemaphoreSlim`
+serialization is unit-tested only (`AbCipBoolInDIntRmwTests`). `ab_server`
+seeds a plain `TestBOOL` tag; the `.N` bit-within-DINT syntax that triggers
+the RMW path is not exercised end-to-end.
+
+### 7. Capability surfaces beyond read
+
+No smoke test for:
+
+- `IWritable.WriteAsync`
+- `ITagDiscovery.DiscoverAsync` (`@tags` walker)
+- `ISubscribable.SubscribeAsync` (poll-group engine)
+- `IHostConnectivityProbe` state transitions under wire failure
+- `IPerCallHostResolver` multi-device routing
+
+The driver implements all of these + they have unit coverage, but the only
+end-to-end path `ab_server` validates today is atomic `ReadAsync`.
+
+## Logix Emulate golden-box tier
+
+Rockwell Studio 5000 Logix Emulate sits **above** ab_server in fidelity +
+**below** real hardware. When an operator has Emulate running on a
+reachable Windows box + sets two env vars, the suite promotes several
+behaviours from unit-only to end-to-end wire-level coverage:
+
+```powershell
+$env:AB_SERVER_PROFILE  = 'emulate'
+$env:AB_SERVER_ENDPOINT = '<emulate-pc-ip>:44818'
+dotnet test tests\ZB.MOM.WW.OtOpcUa.Driver.AbCip.IntegrationTests
+```
+
+With `AB_SERVER_PROFILE` unset or `abserver`, the Emulate-tier classes
+skip cleanly + the ab_server Docker fixture runs as usual.
+
+| Gap this fixture doc calls out | ab_server | Logix Emulate | Real hardware |
+|---|---|---|---|
+| UDT / CIP Template Object (task #194) | no | **yes** | yes |
+| ALMD alarm projection (task #177) | no | **yes** | yes |
+| `@tags` Symbol Object walk with `Program:` scope | partial | **yes** | yes |
+| Add-On Instructions | no | **yes** | yes |
+| GuardLogix safety-partition write rejection | no | **yes** (Emulate 5580) | yes |
+| CompactLogix narrow ConnectionSize enforcement | no | **yes** (5370 firmware) | yes |
+| EtherNet/IP embedded-switch behaviour | no | no | yes |
+| Redundant chassis failover (1756-RM) | no | no | yes |
+| Motion control timing | no | no | yes |
+
+**Tests that promote to Emulate** (gated on `AB_SERVER_PROFILE=emulate`
+via `AbServerProfileGate.SkipUnless`):
+
+- `AbCipEmulateUdtReadTests.WholeUdt_read_decodes_each_member_at_its_Template_Object_offset`
+  — #194 whole-UDT optimization, verified against real Template Object
+  bytes
+- `AbCipEmulateAlmdTests.Real_ALMD_raise_fires_OnAlarmEvent_through_the_driver_projection`
+  — #177 ALMD projection, verified against the real ALMD instruction
+
+**Required Studio 5000 project state** is documented in
+[`tests/…/AbCip.IntegrationTests/LogixProject/README.md`](../../tests/ZB.MOM.WW.OtOpcUa.Driver.AbCip.IntegrationTests/LogixProject/README.md);
+the `.L5X` export lands there once the Emulate PC is on-site + the
+project is authored.
+
+**Costs to accept**:
+
+- **Rockwell TechConnect or per-seat license** — not redistributable;
+  not CI-runnable. Each operator licenses their own Emulate install.
+- **Windows-only + Hyper-V conflict** — Emulate can't coexist with
+  Docker Desktop's WSL 2 backend on the same OS, same way TwinCAT XAR
+  can't (see `docs/v2/dev-environment.md` §Integration host).
+- **Manual lifecycle** — no `docker compose up` equivalent; operator
+  opens Emulate, loads the L5X, clicks Run. The L5X in the repo keeps
+  project state reproducible, runtime-start is human.
+
+## When to trust ab_server, when to reach for a rig
+
+| Question | ab_server | Unit tests | Logix Emulate | Lab rig |
+| --- | --- | --- | --- | --- |
+| "Does the driver talk CIP at all?" | yes | - | yes | - |
+| "Is my atomic read path wired correctly?" | yes | yes | yes | yes |
+| "Does whole-UDT grouping work?" | no | yes | **yes** | yes |
+| "Do ALMD alarms raise + clear?" | no | yes | **yes** | yes |
+| "Is Micro800 unconnected-only enforced wire-side?" | no (emulated as CLX) | partial | yes | yes (required) |
+| "Does GuardLogix reject non-safety writes on safety tags?" | no | no | yes (Emulate 5580) | yes |
+| "Does CompactLogix refuse oversized ConnectionSize?" | no | partial | yes (5370 firmware) | yes |
+| "Does BOOL-in-DINT RMW race against concurrent writers?" | no | yes | partial | yes (stress) |
+| "Does EtherNet/IP embedded-switch behave correctly?" | no | no | no | yes (required) |
+| "Does redundant-chassis failover work?" | no | no | no | yes (required) |
+
+## Follow-up candidates
+
+If integration-level UDT / alarm / quirk proof becomes a shipping gate, the
+options are roughly:
+
+1. **Logix Emulate golden-box tier** (scaffolded; see the section above) —
+   highest-fidelity path short of real hardware. Closes UDT / ALMD / AOI /
+   optimized-DB gaps in one license + one Windows PC.
+2. **Extend `ab_server`** upstream — the project accepts PRs + already
+   carries a CIP framing layer that UDT emulation could plug into.
+3. **Stand up a lab rig** — physical `1756-L7x` / `5069-L3x` / `2080-LC30`
+   / `1756-L8xS` controllers. The only path that covers safety partitions
+   across nodes, redundant chassis, embedded-switch behaviour, and motion
+   timing.
+
+See also:
+
+- `tests/ZB.MOM.WW.OtOpcUa.Driver.AbCip.IntegrationTests/AbServerFixture.cs`
+- `tests/ZB.MOM.WW.OtOpcUa.Driver.AbCip.IntegrationTests/AbServerProfile.cs`
+- `tests/ZB.MOM.WW.OtOpcUa.Driver.AbCip.IntegrationTests/AbServerProfileGate.cs`
+  — `AB_SERVER_PROFILE` tier gate
+- `tests/ZB.MOM.WW.OtOpcUa.Driver.AbCip.IntegrationTests/AbCipReadSmokeTests.cs`
+- `tests/ZB.MOM.WW.OtOpcUa.Driver.AbCip.IntegrationTests/Docker/` — ab_server
+  image + compose
+- `tests/ZB.MOM.WW.OtOpcUa.Driver.AbCip.IntegrationTests/Emulate/` — Logix
+  Emulate tier tests
+- `tests/ZB.MOM.WW.OtOpcUa.Driver.AbCip.IntegrationTests/LogixProject/README.md`
+  — L5X project state the Emulate tier expects
+- `docs/v2/test-data-sources.md` §2 — the broader test-data-source picking
+  rationale this fixture slots into

docs/drivers/FOCAS-Test-Fixture.md

@@ -0,0 +1,133 @@
+# FOCAS test fixture
+
+Coverage map + gap inventory for the FANUC FOCAS2 CNC driver.
+
+**TL;DR: there is no integration fixture.** Every test uses a
+`FakeFocasClient` injected via `IFocasClientFactory`. Fanuc's FOCAS library
+(`Fwlib32.dll`) is closed-source proprietary with no public simulator;
+CNC-side behavior is trusted from field deployments.
+
+## What the fixture is
+
+Nothing at the integration layer.
+`tests/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Tests/` is unit-only. The driver ships
+as Tier C (process-isolated) per `docs/v2/driver-stability.md` because the
+FANUC DLL has known crash modes; tests can't replicate those in-process.
+
+## What it actually covers (unit only)
+
+- `FocasCapabilityTests` — data-type mapping (PMC bit / word / float,
+  macro variable types, parameter types)
+- `FocasCapabilityMatrixTests` — per-CNC-series range validation (macro
+  / parameter / PMC letter + number) across 16i / 0i-D / 0i-F /
+  30i / PowerMotion. See [`docs/v2/focas-version-matrix.md`](../v2/focas-version-matrix.md)
+  for the authoritative matrix. 46 theory cases lock every documented
+  range boundary — widening a range without updating the doc fails a
+  test.
+- `FocasReadWriteTests` — read + write against the fake, FOCAS native status
+  → OPC UA StatusCode mapping
+- `FocasScaffoldingTests` — `IDriver` lifecycle + multi-device routing
+- `FocasPmcBitRmwTests` — PMC bit read-modify-write synchronization (per-byte
+  `SemaphoreSlim`, mirrors the AB / Modbus pattern from #181)
+- `FwlibNativeHelperTests` — `Focas32.dll` → `Fwlib32.dll` bridge validation
+  + P/Invoke signature validation
+
+Capability surfaces whose contract is verified: `IDriver`, `IReadable`,
+`IWritable`, `ITagDiscovery`, `ISubscribable`, `IHostConnectivityProbe`,
+`IPerCallHostResolver`.
+
+Pre-flight validation runs in `FocasDriver.InitializeAsync` — configs
+referencing out-of-range addresses fail at load time with a diagnostic
+message naming the CNC series + documented limit. This closes the
+cheap half of the hardware-free stability gap; Tier-C process
+isolation (task #220) closes the expensive half — see
+[`docs/v2/implementation/focas-isolation-plan.md`](../v2/implementation/focas-isolation-plan.md).
+
+## What it does NOT cover
+
+### 1. FOCAS wire traffic
+
+No FOCAS TCP frame is sent. `Fwlib32.dll`'s TCP-to-FANUC-gateway exchange is
+closed-source; the driver trusts the P/Invoke layer per #193. Real CNC
+correctness is trusted from field deployments.
+
+### 2. Alarm / parameter-change callbacks
+
+FOCAS has no push model — the driver polls via the shared `PollGroupEngine`.
+There are no CNC-initiated callbacks to test; the absence is by design.
+
+### 3. Macro / ladder variable types
+
+FANUC has CNC-specific extensions (macro variables `#100-#999`, system
+variables `#1000-#5000`, PMC timers / counters / keep-relays) whose
+per-address semantics differ across 0i-F / 30i / 31i / 32i Series. Driver
+covers the common address shapes; per-model quirks are not stressed.
+
+### 4. Model-specific behavior
+
+- Alarm retention across power cycles (model-specific CNC behavior)
+- Parameter range enforcement (CNC rejects out-of-range writes)
+- MTB (machine tool builder) custom screens that expose non-standard data
+
+### 5. Tier-C process isolation — architecture shipped, Fwlib32 integration hardware-gated
+
+The Tier-C architecture is now in place as of PRs #169–#173 (FOCAS
+PR A–E, task #220):
+
+- `Driver.FOCAS.Shared` carries MessagePack IPC contracts
+- `Driver.FOCAS.Host` (.NET 4.8 x86 Windows service via NSSM) accepts
+  a connection on a strictly-ACL'd named pipe + dispatches frames to
+  an `IFocasBackend`
+- `Driver.FOCAS.Ipc.IpcFocasClient` implements the `IFocasClient` DI
+  seam by forwarding over IPC — swap the DI registration and the
+  driver runs Tier-C with zero other changes
+- `Driver.FOCAS.Supervisor.FocasHostSupervisor` owns the spawn +
+  heartbeat + respawn + 3-in-5min crash-loop breaker + sticky alert
+- `Driver.FOCAS.Host.Stability.PostMortemMmf` ↔
+  `Driver.FOCAS.Supervisor.PostMortemReader` — ring-buffer of the
+  last ~1000 IPC operations survives a Host crash
+
+The one remaining gap is the production `FwlibHostedBackend`: an
+`IFocasBackend` implementation that wraps the licensed
+`Fwlib32.dll` P/Invoke. That's hardware-gated on task #222 — we
+need a CNC on the bench (or the licensed FANUC developer kit DLL
+with a test harness) to validate it. Until then, the Host ships
+`FakeFocasBackend` + `UnconfiguredFocasBackend`. Setting
+`OTOPCUA_FOCAS_BACKEND=fake` lets operators smoke-test the whole
+Tier-C pipeline end-to-end without any CNC.
+
+## When to trust FOCAS tests, when to reach for a rig
+
+| Question | Unit tests | Real CNC |
+| --- | --- | --- |
+| "Does PMC address `R100.3` route to the right bit?" | yes | yes |
+| "Does the FANUC status → OPC UA StatusCode map cover every documented code?" | yes (contract) | yes |
+| "Does a real read against a 30i Series return correct bytes?" | no | yes (required) |
+| "Does `Fwlib32.dll` crash on concurrent reads?" | no | yes (stress) |
+| "Do macro variables round-trip across power cycles?" | no | yes (required) |
+
+## Follow-up candidates
+
+1. **Nothing public** — Fanuc's FOCAS Developer Kit ships an emulator DLL
+   but it's under NDA + tied to licensed dev-kit installations; can't
+   redistribute for CI.
+2. **Lab rig** — used FANUC 0i-F simulator controller (or a retired machine
+   tool) on a dedicated network; only path that covers real CNC behavior.
+3. **Process isolation first** — before trusting FOCAS in production at
+   scale, shipping the Tier-C out-of-process Host architecture (similar to
+   Galaxy) is higher value than a CI simulator.
+
+## Key fixture / config files
+
+- `tests/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Tests/FakeFocasClient.cs` —
+  in-process fake implementing `IFocasClient`
+- `tests/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Tests/FocasCapabilityMatrixTests.cs`
+  — parameterized theories locking the per-series matrix
+- `src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/FocasDriver.cs` — ctor takes
+  `IFocasClientFactory`
+- `src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/FocasCapabilityMatrix.cs` —
+  per-CNC-series range validator (the matrix the doc describes)
+- `docs/v2/focas-version-matrix.md` — authoritative range reference
+- `docs/v2/implementation/focas-isolation-plan.md` — Tier-C isolation
+  plan (task #220)
+- `docs/v2/driver-stability.md` — Tier C scope + process-isolation rationale

docs/drivers/Galaxy-Test-Fixture.md

@@ -0,0 +1,164 @@
+# Galaxy test fixture
+
+Coverage map + gap inventory for the Galaxy driver — out-of-process Host
+(net48 x86 MXAccess COM) + Proxy (net10) + Shared protocol.
+
+**TL;DR: Galaxy has the richest test harness in the fleet** — real Host
+subprocess spawn, real ZB SQL queries, IPC parity checks against the v1
+LmxProxy reference, + live-smoke tests when MXAccess runtime is actually
+installed. Gaps are live-plant + failover-shaped: the E2E suite covers the
+representative ~50-tag deployment but not large-site discovery stress, real
+Rockwell/Siemens PLC enumeration through MXAccess, or ZB SQL Always-On
+replica failover.
+
+## What the fixture is
+
+Multi-project test topology:
+
+- **E2E parity** —
+  `tests/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.E2E/ParityFixture.cs` spawns the
+  production `OtOpcUa.Driver.Galaxy.Host.exe` as a subprocess, opens the
+  named-pipe IPC, connects `GalaxyProxyDriver` + runs hierarchy / stability
+  parity tests against both.
+- **Host.Tests** —
+  `tests/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host.Tests/` — direct Host process
+  testing (18+ test classes covering alarm discovery, AVEVA prerequisite
+  checks, IPC dispatcher, alarm tracker, probe manager, historian
+  cluster/quality/wiring, history read, OPC UA attribute mapping,
+  subscription lifecycle, reconnect, multi-host proxy, ADS address routing,
+  expression evaluation) + `GalaxyRepositoryLiveSmokeTests` that hit real
+  ZB SQL.
+- **Proxy.Tests** — `GalaxyProxyDriver` client contract tests.
+- **Shared.Tests** — shared protocol + address model.
+- **TestSupport** — test helpers reused across the above.
+
+## How tests skip
+
+- **E2E parity**: `ParityFixture.SkipIfUnavailable()` runs at class init and
+  checks Windows-only, non-admin user, ZB SQL reachable on
+  `localhost:1433`, Host EXE built in the expected `bin/` folder. Any miss
+  → tests skip.
+- **Live-smoke** (`GalaxyRepositoryLiveSmokeTests`): `Assert.Skip` when ZB
+  unreachable. A `per project_galaxy_host_installed` memory on this repo's
+  dev box notes the MXAccess runtime is installed + pipe ACL denies Admins,
+  so live tests must run from a non-elevated shell.
+- **Unit** tests (Shared, Proxy contract, most Host.Tests) have no skip —
+  they run anywhere.
+
+## What it actually covers
+
+### E2E parity suite
+
+- `HierarchyParityTests` — Host address-space hierarchy vs v1 LmxProxy
+  reference (same ZB, same Galaxy, same shape)
+- `StabilityFindingsRegressionTests` — probe subscription failure
+  handling + host-status mutation guard from the v1 stability findings
+  backlog
+
+### Host.Tests (representative)
+
+- Alarm discovery → subsystem setup
+- AVEVA prerequisite checks (runtime installed, platform deployed, etc.)
+- IPC dispatcher — request/response routing over the named pipe
+- Alarm tracker state machine
+- Probe manager — per-runtime probe subscription + reconnect
+- Historian cluster / quality / wiring — Aveva Historian integration
+- OPC UA attribute mapping
+- Subscription lifecycle + reconnect
+- Multi-host proxy routing
+- ADS address routing + expression evaluation (Galaxy's legacy expression
+  language)
+
+### Live-smoke
+
+- `GalaxyRepositoryLiveSmokeTests` — real SQL against ZB database, verifies
+  the ZB schema + `LocalPlatform` scope filter + change-detection query
+  shape match production.
+
+### Capability surfaces hit
+
+All of them: `IDriver`, `IReadable`, `IWritable`, `ITagDiscovery`,
+`ISubscribable`, `IHostConnectivityProbe`, `IPerCallHostResolver`,
+`IAlarmSource`, `IHistoryProvider`. Galaxy is the only driver where every
+interface sees both contract + real-integration coverage.
+
+## What it does NOT cover
+
+### 1. MXAccess COM by default
+
+The E2E parity suite backs subscriptions via the DB-only path; MXAccess COM
+integration opts in via a separate live-smoke. So "does the MXAccess STA
+pump correctly handle real Wonderware runtime events" is exercised only
+when the operator runs live smoke on a machine with MXAccess installed.
+
+### 2. Real Rockwell / Siemens PLC enumeration
+
+Galaxy runtime talks to PLCs through MXAccess (Device Integration Objects).
+The CI parity suite uses a representative ~50-tag deployment; large sites
+(1000+ tag hierarchies, multi-Galaxy replication, deeply-nested templates)
+are not stressed.
+
+### 3. ZB SQL Always-On failover
+
+Live-smoke hits a single SQL instance. Real production ZB often runs on
+Always-On availability groups; replica failover behavior is not tested.
+
+### 4. Galaxy replication / backup-restore
+
+Galaxy supports backup + partial replication across platforms — these
+rewrite the ZB schema in ways that change the contained_name vs tag_name
+mapping. Not exercised.
+
+### 5. Historian failover
+
+Aveva Historian can be clustered. `historian cluster / quality` tests
+verify the cluster-config query; they don't exercise actual failover
+(primary dies → secondary takes over mid-HistoryRead).
+
+### 6. AVEVA runtime version matrix
+
+MXAccess COM contract varies subtly across System Platform 2017 / 2020 /
+2023. The live-smoke runs against whatever version is installed on the dev
+box; CI has no AVEVA installed at all (licensing + footprint).
+
+## When to trust the Galaxy suite, when to reach for a live plant
+
+| Question | E2E parity | Live-smoke | Real plant |
+| --- | --- | --- | --- |
+| "Does Host spawn + IPC round-trip work?" | yes | yes | yes |
+| "Does the ZB schema query match production shape?" | partial | yes | yes |
+| "Does MXAccess COM handle runtime reconnect correctly?" | no | yes | yes |
+| "Does the driver scale to 1000+ tags on one Galaxy?" | no | partial | yes (required) |
+| "Does historian failover mid-read return a clean error?" | no | no | yes (required) |
+| "Does System Platform 2023's MXAccess differ from 2020?" | no | partial | yes (required) |
+| "Does ZB Always-On replica failover preserve generation?" | no | no | yes (required) |
+
+## Follow-up candidates
+
+1. **System Platform 2023 live-smoke matrix** — set up a second dev box
+   running SP2023; run the same live-smoke against both to catch COM-contract
+   drift early.
+2. **Synthetic large-site fixture** — script a ZB populator that creates a
+   1000-Equipment / 20000-tag hierarchy, run the parity suite against it.
+   Catches O(N) → O(N²) discovery regressions.
+3. **Historian failover scripted test** — with a two-node AVEVA Historian
+   cluster, tear down primary mid-HistoryRead + verify the driver's failover
+   behavior + error surface.
+4. **ZB Always-On CI** — SQL Server 2022 on Linux supports Always-On;
+   could stand up a two-replica group for replica-failover coverage.
+
+This is already the best-tested driver; the remaining work is site-scale
++ production-topology coverage, not capability coverage.
+
+## Key fixture / config files
+
+- `tests/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.E2E/ParityFixture.cs` — E2E fixture
+  that spawns Host + connects Proxy
+- `tests/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host.Tests/GalaxyRepositoryLiveSmokeTests.cs`
+  — live ZB smoke with `Assert.Skip` gate
+- `tests/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.TestSupport/` — shared helpers
+- `docs/drivers/Galaxy.md` — COM bridge + STA pump + IPC architecture
+- `docs/drivers/Galaxy-Repository.md` — ZB SQL reader + `LocalPlatform`
+  scope filter + change detection
+- `docs/v2/aveva-system-platform-io-research.md` — MXAccess + Wonderware
+  background

docs/drivers/Modbus-Test-Fixture.md

@@ -0,0 +1,123 @@
+# Modbus test fixture
+
+Coverage map + gap inventory for the Modbus TCP driver's integration-test
+harness backed by `pymodbus` simulator profiles per PLC family.
+
+**TL;DR:** Modbus is the best-covered driver — a real `pymodbus` server on
+localhost with per-family seed-register profiles, plus a skip-gate when the
+simulator port isn't reachable. Covers DL205 / Mitsubishi MELSEC / Siemens
+S7-1500 family quirks end-to-end. Gaps are mostly error-path + alarm/history
+shaped (neither is a Modbus-side concept).
+
+## What the fixture is
+
+- **Simulator**: `pymodbus` (Python, BSD) launched as a pinned Docker
+  container at
+  `tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests/Docker/`.
+  Docker is the only supported launch path.
+- **Lifecycle**: `ModbusSimulatorFixture` (collection-scoped) TCP-probes
+  `localhost:5020` on first use. `MODBUS_SIM_ENDPOINT` env var overrides the
+  endpoint so the same suite can target a real PLC.
+- **Profiles**: `DL205Profile`, `MitsubishiProfile`, `S7_1500Profile` —
+  each composes device-specific register-format + quirk-seed JSON for pymodbus.
+  Profile JSONs live under `Docker/profiles/` and are baked into the image.
+- **Compose services**: one per profile (`standard` / `dl205` /
+  `mitsubishi` / `s7_1500`); only one binds `:5020` at a time.
+- **Tests skip** via `Assert.Skip(sim.SkipReason)` when the probe fails; no
+  custom FactAttribute needed because `ModbusSimulatorCollection` carries the
+  skip reason.
+
+## What it actually covers
+
+### DL205 (Automation Direct)
+
+- `DL205SmokeTests` — FC16 write → FC03 read round-trip on holding register
+- `DL205CoilMappingTests` — Y-output / C-relay / X-input address mapping
+  (octal → Modbus offset)
+- `DL205ExceptionCodeTests` — Modbus exception 0x02 → OPC UA `BadOutOfRange` against the dl205 profile (natural out-of-range path)
+- `ExceptionInjectionTests` — every other exception code in the mapping table (0x01 / 0x03 / 0x04 / 0x05 / 0x06 / 0x0A / 0x0B) against the `exception_injection` profile on both read + write paths
+- `DL205FloatCdabQuirkTests` — CDAB word-swap float encoding
+- `DL205StringQuirkTests` — packed-string V-memory layout
+- `DL205VMemoryQuirkTests` — V-memory octal addressing
+- `DL205XInputTests` — X-register read-only enforcement
+
+### Mitsubishi MELSEC
+
+- `MitsubishiSmokeTests` — read + write round-trip
+- `MitsubishiQuirkTests` — word-order, device-code mapping (D/M/X/Y ranges)
+
+### Siemens S7-1500 (Modbus gateway flavor)
+
+- `S7_1500SmokeTests` — read + write round-trip
+- `S7_ByteOrderTests` — ABCD/DCBA/BADC/CDAB byte-order matrix
+
+### Capability surfaces hit
+
+- `IReadable` + `IWritable` — full round-trip
+- `ISubscribable` — via the shared `PollGroupEngine` (polled subscription)
+- `IHostConnectivityProbe` — TCP-reach transitions
+
+## What it does NOT cover
+
+### 1. No `ITagDiscovery`
+
+Modbus has no symbol table — the driver requires a static tag map from
+`DriverConfig`. There is no discovery path to test + none in the fixture.
+
+### 2. Error-path fuzzing
+
+`pymodbus` serves the seeded values happily; the fixture can't easily inject
+exception responses (code 0x01–0x0B) or malformed PDUs. The
+`AbCipStatusMapper`-equivalent for exception codes is unit-tested via
+`DL205ExceptionCodeTests` but the simulator itself never refuses a read.
+
+### 3. Variant-specific quirks beyond the three profiles
+
+- FX5U / QJ71MT91 Mitsubishi variants — profile scaffolds exist, no tests yet
+- Non-S7-1500 Siemens (S7-1200 / ET200SP) — byte-order covered but
+  connection-pool + fragmentation quirks untested
+- DL205-family cousins (DL06, DL260) — no dedicated profile
+
+### 4. Subscription stress
+
+`PollGroupEngine` is unit-tested standalone but the simulator doesn't exercise
+it under multi-register packing stress (FC03 with 125-register batches,
+boundary splits, etc.).
+
+### 5. Alarms / history
+
+Not a Modbus concept. Driver doesn't implement `IAlarmSource` or
+`IHistoryProvider`; no test coverage is the correct shape.
+
+## When to trust the Modbus fixture, when to reach for a rig
+
+| Question | Fixture | Unit tests | Real PLC |
+| --- | --- | --- | --- |
+| "Does FC03/FC06/FC16 work end-to-end?" | yes | - | yes |
+| "Does DL205 octal addressing map correctly?" | yes | yes | yes |
+| "Does float CDAB word-swap round-trip?" | yes | yes | yes |
+| "Does the driver handle exception responses?" | no | yes | yes (required) |
+| "Does packing 125 regs into one FC03 work?" | no | no | yes (required) |
+| "Does FX5U behave like Q-series?" | no | no | yes (required) |
+
+## Follow-up candidates
+
+1. Add `MODBUS_SIM_ENDPOINT` override documentation to
+   `docs/v2/test-data-sources.md` so operators can point the suite at a lab rig.
+2. ~~Extend `pymodbus` profiles to inject exception responses~~ — **shipped**
+   via the `exception_injection` compose profile + standalone
+   `exception_injector.py` server. Rules in
+   `Docker/profiles/exception_injection.json` map `(fc, address)` to an
+   exception code; `ExceptionInjectionTests` exercises every code in
+   `MapModbusExceptionToStatus` (0x01 / 0x02 / 0x03 / 0x04 / 0x05 / 0x06 /
+   0x0A / 0x0B) end-to-end on both read (FC03) and write (FC06) paths.
+3. Add an FX5U profile once a lab rig is available; the scaffolding is in place.
+
+## Key fixture / config files
+
+- `tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests/ModbusSimulatorFixture.cs`
+- `tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests/DL205/DL205Profile.cs`
+- `tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests/Mitsubishi/MitsubishiProfile.cs`
+- `tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests/S7/S7_1500Profile.cs`
+- `tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests/Docker/` —
+  Dockerfile + compose + per-family JSON profiles

docs/drivers/OpcUaClient-Test-Fixture.md

@@ -0,0 +1,170 @@
+# OPC UA Client test fixture
+
+Coverage map + gap inventory for the OPC UA Client (gateway / aggregation)
+driver.
+
+**TL;DR:** Wire-level coverage now exists via
+[opc-plc](https://github.com/Azure-Samples/iot-edge-opc-plc) — Microsoft
+Industrial IoT's OPC UA PLC simulator running in Docker (task #215). Real
+Secure Channel, real Session, real MonitoredItem exchange against an
+independent server implementation. Unit tests still carry the exhaustive
+capability matrix (cert auth / security policies / reconnect / failover /
+attribute mapping). Gaps remaining: upstream-server-specific quirks
+(historian aggregates, typed ConditionType events, SDK-publish-queue edge
+behavior under load) — opc-plc uses the same OPCFoundation stack internally
+so fully-independent-stack coverage needs `open62541/open62541` as a second
+image (follow-up).
+
+## What the fixture is
+
+**Integration layer** (task #215):
+`tests/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.IntegrationTests/` stands up
+`mcr.microsoft.com/iotedge/opc-plc:2.14.10` via `Docker/docker-compose.yml`
+on `opc.tcp://localhost:50000`. `OpcPlcFixture` probes the port at
+collection init + skips tests with a clear message when the container's
+not running (matches the Modbus/pymodbus + S7/python-snap7 skip pattern).
+Docker is the launcher — no PowerShell wrapper needed because opc-plc
+ships pre-containerized. Compose-file flags: `--ut` (unsecured transport
+advertised), `--aa` (auto-accept client certs — opc-plc's cert trust store
+resets on each spin-up), `--alm` (alarm simulation for IAlarmSource
+follow-up coverage), `--pn=50000` (port).
+
+**Unit layer**:
+`tests/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Tests/` is still the primary
+coverage. Tests inject fakes through the driver's construction path; the
+OPCFoundation.NetStandard `Session` surface is wrapped behind an interface
+the tests mock.
+
+## What it actually covers
+
+### Integration (opc-plc Docker, task #215)
+
+- `OpcUaClientSmokeTests.Client_connects_and_reads_StepUp_node_through_real_OPC_UA_stack` —
+  full Secure Channel + Session + `ns=3;s=StepUp` Read round-trip
+- `OpcUaClientSmokeTests.Client_reads_batch_of_varied_types_from_live_simulator` —
+  batch Read of UInt32 / Int32 / Boolean; asserts `bool`-specific Variant
+  decoding to catch a common attribute-mapping regression
+- `OpcUaClientSmokeTests.Client_subscribe_receives_StepUp_data_changes_from_live_server` —
+  real `MonitoredItem` subscription against `ns=3;s=FastUInt1` (ticks every
+  100 ms); asserts `OnDataChange` fires within 3 s of subscribe
+
+Wire-level surfaces verified: `IDriver` + `IReadable` + `ISubscribable` +
+`IHostConnectivityProbe` (via the Secure Channel exchange).
+
+### Unit
+
+The surface is broad because `OpcUaClientDriver` is the richest-capability
+driver in the fleet (it's a gateway for another OPC UA server, so it
+mirrors the full capability matrix):
+
+- `OpcUaClientDriverScaffoldTests` — `IDriver` lifecycle
+- `OpcUaClientReadWriteTests` — read + write lifecycle
+- `OpcUaClientSubscribeAndProbeTests` — monitored-item subscription + probe
+  state transitions
+- `OpcUaClientDiscoveryTests` — `GetEndpoints` + endpoint selection
+- `OpcUaClientAttributeMappingTests` — OPC UA node attribute → driver value
+  mapping
+- `OpcUaClientSecurityPolicyTests` — `SignAndEncrypt` / `Sign` / `None`
+  policy negotiation contract
+- `OpcUaClientCertAuthTests` — cert store paths, revocation-list config
+- `OpcUaClientReconnectTests` — SDK reconnect hook + `TransferSubscriptions`
+  across the disconnect boundary
+- `OpcUaClientFailoverTests` — primary → secondary session fallback per
+  driver config
+- `OpcUaClientAlarmTests` — A&E severity bucket (1–1000 → Low / Medium /
+  High / Critical), subscribe / unsubscribe / ack contract
+- `OpcUaClientHistoryTests` — historical data read + interpolation contract
+
+Capability surfaces whose contract is verified: `IDriver`, `ITagDiscovery`,
+`IReadable`, `IWritable`, `ISubscribable`, `IHostConnectivityProbe`,
+`IAlarmSource`, `IHistoryProvider`.
+
+## What it does NOT cover
+
+### 1. Real stack exchange
+
+No UA Secure Channel is ever opened. Every test mocks `Session.ReadAsync`,
+`Session.CreateSubscription`, `Session.AddItem`, etc. — the SDK itself is
+trusted. Certificate validation, signing, nonce handling, chunk assembly,
+keep-alive cadence — all SDK-internal and untested here.
+
+### 2. Subscription transfer across reconnect
+
+Contract test: "after a simulated reconnect, `TransferSubscriptions` is
+called with the right handles." Real behavior: SDK re-publishes against the
+new channel and some events can be lost depending on publish-queue state.
+The lossy window is not characterized.
+
+### 3. Large-scale subscription stress
+
+100+ monitored items with heterogeneous publish intervals under a single
+session — the shape that breaks publish-queue-size tuning in the wild — is
+not exercised.
+
+### 4. Real historian mappings
+
+`IHistoryProvider.ReadRawAsync` + `ReadProcessedAsync` +
+`ReadAtTimeAsync` + `ReadEventsAsync` are contract-mocked. Against a real
+historian (AVEVA Historian, Prosys historian, Kepware LocalHistorian) each
+has specific interpolation + bad-quality-handling quirks the contract test
+doesn't see.
+
+### 5. Real A&E events
+
+Alarm subscription is mocked via filtered monitored items; the actual
+`EventFilter` select-clause behavior against a server that exposes typed
+ConditionType events (non-base `BaseEventType`) is not verified.
+
+### 6. Authentication variants
+
+- Anonymous, UserName/Password, X509 cert tokens — each is contract-tested
+  but not exchanged against a server that actually enforces each.
+- LDAP-backed `UserName` (matching this repo's server-side
+  `LdapUserAuthenticator`) requires a live LDAP round-trip; not tested.
+
+## When to trust OpcUaClient tests, when to reach for a server
+
+| Question | Unit tests | Real upstream server |
+| --- | --- | --- |
+| "Does severity 750 bucket as High?" | yes | yes |
+| "Does the driver call `TransferSubscriptions` after reconnect?" | yes | yes |
+| "Does a real OPC UA read/write round-trip work?" | no | yes (required) |
+| "Does event-filter-based alarm subscription return ConditionType events?" | no | yes (required) |
+| "Does history read from AVEVA Historian return correct aggregates?" | no | yes (required) |
+| "Does the SDK's publish queue lose notifications under load?" | no | yes (stress) |
+
+## Follow-up candidates
+
+The easiest win here is to **wire the client driver tests against this
+repo's own server**. The integration test project
+`tests/ZB.MOM.WW.OtOpcUa.Server.Tests/OpcUaServerIntegrationTests.cs`
+already stands up a real OPC UA server on a non-default port with a seeded
+FakeDriver. An `OpcUaClientLiveLoopbackTests` that connects the client
+driver to that server would give:
+
+- Real Secure Channel negotiation
+- Real Session / Subscription / MonitoredItem exchange
+- Real read/write round-trip
+- Real certificate validation (the integration test already sets up PKI)
+
+It wouldn't cover upstream-server-specific quirks (AVEVA Historian, Kepware,
+Prosys), but it would cover 80% of the SDK surface the driver sits on top
+of.
+
+Beyond that:
+
+1. **Prosys OPC UA Simulation Server** — free, Windows-available, scriptable.
+2. **UaExpert Server-Side Simulator** — Unified Automation's sample server;
+   good coverage of typed ConditionType events.
+3. **Dedicated historian integration lab** — only path for
+   historian-specific coverage.
+
+## Key fixture / config files
+
+- `tests/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Tests/` — unit tests with
+  mocked `Session`
+- `src/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient/OpcUaClientDriver.cs` — ctor +
+  session-factory seam tests mock through
+- `tests/ZB.MOM.WW.OtOpcUa.Server.Tests/OpcUaServerIntegrationTests.cs` —
+  the server-side integration harness a future loopback client test could
+  piggyback on

docs/drivers/README.md

@@ -37,6 +37,19 @@ Driver type metadata is registered at startup in `DriverTypeRegistry` (`src/ZB.M
 
 - **All other drivers** share a single per-driver specification in [docs/v2/driver-specs.md](../v2/driver-specs.md) — addressing, data-type maps, connection settings, and quirks live there. That file is the authoritative per-driver reference; this index points at it rather than duplicating.
 
+## Test-fixture coverage maps
+
+Each driver has a dedicated fixture doc that lays out what the integration / unit harness actually covers vs. what's trusted from field deployments. Read the relevant one before claiming "green suite = production-ready" for a driver.
+
+- [AB CIP](AbServer-Test-Fixture.md) — Dockerized `ab_server` (multi-stage build from libplctag source); atomic-read smoke across 4 families; UDT / ALMD / family quirks unit-only
+- [Modbus](Modbus-Test-Fixture.md) — Dockerized `pymodbus` + per-family JSON profiles (4 compose profiles); best-covered driver, gaps are error-path-shaped
+- [Siemens S7](S7-Test-Fixture.md) — Dockerized `python-snap7` server; DB/MB read + write round-trip verified end-to-end on `:1102`
+- [AB Legacy](AbLegacy-Test-Fixture.md) — Docker scaffold via `ab_server` PCCC mode (task #224); wire-level round-trip currently blocked by ab_server's PCCC coverage gap, docs call out RSEmulate 500 + lab-rig resolution paths
+- [TwinCAT](TwinCAT-Test-Fixture.md) — XAR-VM integration scaffolding (task #221); three smoke tests skip when VM unreachable. Unit via `FakeTwinCATClient` with native-notification harness
+- [FOCAS](FOCAS-Test-Fixture.md) — no integration fixture, unit-only via `FakeFocasClient`; Tier C out-of-process isolation scoped but not shipped
+- [OPC UA Client](OpcUaClient-Test-Fixture.md) — no integration fixture, unit-only via mocked `Session`; loopback against this repo's own server is the obvious next step
+- [Galaxy](Galaxy-Test-Fixture.md) — richest harness: E2E Host subprocess + ZB SQL live-smoke + MXAccess opt-in
+
 ## Related cross-driver docs
 
 - [HistoricalDataAccess.md](../HistoricalDataAccess.md) — `IHistoryProvider` dispatch, aggregate mapping, continuation points. The Galaxy driver's Aveva Historian implementation is the first; OPC UA Client forwards to the upstream server; other drivers do not implement the interface and return `BadHistoryOperationUnsupported`.

docs/drivers/S7-Test-Fixture.md

@@ -0,0 +1,121 @@
+# Siemens S7 test fixture
+
+Coverage map + gap inventory for the S7 driver.
+
+**TL;DR:** S7 now has a wire-level integration fixture backed by
+[python-snap7](https://github.com/gijzelaerr/python-snap7)'s `Server` class
+(task #216). Atomic reads (u16 / i16 / i32 / f32 / bool-with-bit) + DB
+write-then-read round-trip are exercised end-to-end through S7netplus +
+real ISO-on-TCP on `localhost:1102`. Unit tests still carry everything
+else (address parsing, error-branch handling, probe-loop contract). Gaps
+remaining are variant-quirk-shaped: Optimized-DB symbolic access, PG/OP
+session types, PUT/GET-disabled enforcement — all need real hardware.
+
+## What the fixture is
+
+**Integration layer** (task #216):
+`tests/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/` stands up a
+python-snap7 `Server` via `Docker/docker-compose.yml --profile s7_1500`
+on `localhost:1102` (pinned `python:3.12-slim-bookworm` base +
+`python-snap7>=2.0`). Docker is the only supported launch path.
+`Snap7ServerFixture` probes the port at collection init + skips with a
+clear message when unreachable (matches the pymodbus pattern).
+`server.py` (baked into the image under `Docker/`) reads a JSON profile
++ seeds DB/MB bytes at declared offsets; seeds are typed (`u16` / `i16`
+/ `i32` / `f32` / `bool` / `ascii` for S7 STRING).
+
+**Unit layer**: `tests/ZB.MOM.WW.OtOpcUa.Driver.S7.Tests/` covers
+everything the wire-level suite doesn't — address parsing, error
+branches, probe-loop contract. All tests tagged
+`[Trait("Category", "Unit")]`.
+
+The driver ctor change that made this possible:
+`Plc(CpuType, host, port, rack, slot)` — S7netplus 0.20's 5-arg overload
+— wires `S7DriverOptions.Port` through so the simulator can bind 1102
+(non-privileged) instead of 102 (root / Firewall-prompt territory).
+
+## What it actually covers
+
+### Integration (python-snap7, task #216)
+
+- `S7_1500SmokeTests.Driver_reads_seeded_u16_through_real_S7comm` — DB1.DBW0
+  read via real S7netplus over TCP + simulator; proves handshake + read path
+- `S7_1500SmokeTests.Driver_reads_seeded_typed_batch` — i16, i32, f32,
+  bool-with-bit in one batch call; proves typed decode per S7DataType
+- `S7_1500SmokeTests.Driver_write_then_read_round_trip_on_scratch_word` —
+  `DB1.DBW100` write → read-back; proves write path + buffer visibility
+
+### Unit
+
+- `S7AddressParserTests` — S7 address syntax (`DB1.DBD0`, `M10.3`, `IW4`, etc.)
+- `S7DriverScaffoldTests` — `IDriver` lifecycle (init / reinit / shutdown / health)
+- `S7DriverReadWriteTests` — error paths (uninitialized read/write, bad
+  addresses, transport exceptions)
+- `S7DiscoveryAndSubscribeTests` — `ITagDiscovery.DiscoverAsync` + polled
+  `ISubscribable` contract with the shared `PollGroupEngine`
+
+Capability surfaces whose contract is verified: `IDriver`, `ITagDiscovery`,
+`IReadable`, `IWritable`, `ISubscribable`, `IHostConnectivityProbe`.
+Wire-level surfaces verified: `IReadable`, `IWritable`.
+
+## What it does NOT cover
+
+### 1. Wire-level anything
+
+No ISO-on-TCP frame is ever sent during the test suite. S7netplus is the only
+wire-path abstraction and it has no in-process fake mode; the shipping choice
+was to contract-test via `IS7Client` rather than patch into S7netplus
+internals.
+
+### 2. Read/write happy path
+
+Every `S7DriverReadWriteTests` case exercises error branches. A successful
+read returning real PLC data is not tested end-to-end — the return value is
+whatever the fake says it is.
+
+### 3. Mailbox serialization under concurrent reads
+
+The driver's `SemaphoreSlim` serializes S7netplus calls because the S7 CPU's
+comm mailbox is scanned at most once per cycle. Contention behavior under
+real PLC latency is not exercised.
+
+### 4. Variant quirks
+
+S7-1200 vs S7-1500 vs S7-300/400 connection semantics (PG vs OP vs S7-Basic)
+not differentiated at test time.
+
+### 5. Data types beyond the scalars
+
+UDT fan-out, `STRING` with length-prefix quirks, `DTL` / `DATE_AND_TIME`,
+arrays of structs — not covered.
+
+## When to trust the S7 tests, when to reach for a rig
+
+| Question | Unit tests | Real PLC |
+| --- | --- | --- |
+| "Does the address parser accept X syntax?" | yes | - |
+| "Does the driver lifecycle hang / crash?" | yes | yes |
+| "Does a real read against an S7-1500 return correct bytes?" | no | yes (required) |
+| "Does mailbox serialization actually prevent PG timeouts?" | no | yes (required) |
+| "Does a UDT fan-out produce usable member variables?" | no | yes (required) |
+
+## Follow-up candidates
+
+1. **Snap7 server** — [Snap7](https://snap7.sourceforge.net/) ships a
+   C-library-based S7 server that could run in-CI on Linux. A pinned build +
+   a fixture shape similar to `ab_server` would give S7 parity with Modbus /
+   AB CIP coverage.
+2. **Plcsim Advanced** — Siemens' paid emulator. Licensed per-seat; fits a
+   lab rig but not CI.
+3. **Real S7 lab rig** — cheapest physical PLC (CPU 1212C) on a dedicated
+   network port, wired via self-hosted runner.
+
+Without any of these, S7 driver correctness against real hardware is trusted
+from field deployments, not from the test suite.
+
+## Key fixture / config files
+
+- `tests/ZB.MOM.WW.OtOpcUa.Driver.S7.Tests/` — unit tests only, no harness
+- `src/ZB.MOM.WW.OtOpcUa.Driver.S7/S7Driver.cs` — ctor takes
+  `IS7ClientFactory` which tests fake; docstring lines 8-20 note the deferred
+  integration fixture

docs/drivers/TwinCAT-Test-Fixture.md

@@ -0,0 +1,158 @@
+# TwinCAT test fixture
+
+Coverage map + gap inventory for the Beckhoff TwinCAT ADS driver.
+
+**TL;DR:** Integration-test scaffolding lives at
+`tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/` (task #221).
+`TwinCATXarFixture` probes TCP 48898 on an operator-supplied VM; three
+smoke tests (read / write / native notification) run end-to-end through
+the real ADS stack when the VM is reachable, skip cleanly otherwise.
+**Remaining operational work**: stand up a TwinCAT 3 XAR runtime in a
+Hyper-V VM, author the `.tsproj` project documented at
+`TwinCatProject/README.md`, rotate the 7-day trial license (or buy a
+paid runtime). Unit tests via `FakeTwinCATClient` still carry the
+exhaustive contract coverage.
+
+TwinCAT is the only driver outside Galaxy that uses **native
+notifications** (no polling) for `ISubscribable`, and the fake exposes a
+fire-event harness so notification routing is contract-tested rigorously
+at the unit layer.
+
+## What the fixture is
+
+**Integration layer** (task #221, scaffolded):
+`tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/` —
+`TwinCATXarFixture` TCP-probes ADS port 48898 on the host specified by
+`TWINCAT_TARGET_HOST` + requires `TWINCAT_TARGET_NETID` (AmsNetId of the
+VM). No fixture-owned lifecycle — XAR can't run in Docker because it
+bypasses the Windows kernel scheduler, so the VM stays
+operator-managed. `TwinCatProject/README.md` documents the required
+`.tsproj` project state; the file itself lands once the XAR VM is up +
+the project is authored. Three smoke tests:
+`Driver_reads_seeded_DINT_through_real_ADS`,
+`Driver_write_then_read_round_trip_on_scratch_REAL`, and
+`Driver_subscribe_receives_native_ADS_notifications_on_counter_changes`
+— all skip cleanly via `[TwinCATFact]` when the runtime isn't
+reachable.
+
+**Unit layer**: `tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Tests/` is
+still the primary coverage. `FakeTwinCATClient` also fakes the
+`AddDeviceNotification` flow so tests can trigger callbacks without a
+running runtime.
+
+## What it actually covers
+
+### Integration (XAR VM, task #221 — code scaffolded, needs VM + project)
+
+- `TwinCAT3SmokeTests.Driver_reads_seeded_DINT_through_real_ADS` — real AMS
+  handshake + ADS read of `GVL_Fixture.nCounter` (seeded at 1234, MAIN
+  increments each cycle)
+- `TwinCAT3SmokeTests.Driver_write_then_read_round_trip_on_scratch_REAL` —
+  real ADS write + read on `GVL_Fixture.rSetpoint`
+- `TwinCAT3SmokeTests.Driver_subscribe_receives_native_ADS_notifications_on_counter_changes`
+  — real `AddDeviceNotification` against the cycle-incrementing counter;
+  observes `OnDataChange` firing within 3 s of subscribe
+
+All three gated on `TWINCAT_TARGET_HOST` + `TWINCAT_TARGET_NETID` env
+vars; skip cleanly via `[TwinCATFact]` when the VM isn't reachable or
+vars are unset.
+
+### Unit
+
+- `TwinCATAmsAddressTests` — `ads://<netId>:<port>` parsing + routing
+- `TwinCATCapabilityTests` — data-type mapping (primitives + declared UDTs),
+  read-only classification
+- `TwinCATReadWriteTests` — read + write through the fake, status mapping
+- `TwinCATSymbolPathTests` — symbol-path routing for nested struct members
+- `TwinCATSymbolBrowserTests` — `ITagDiscovery.DiscoverAsync` via
+  `ReadSymbolsAsync` (#188) + system-symbol filtering
+- `TwinCATNativeNotificationTests` — `AddDeviceNotification` (#189)
+  registration, callback-delivery-to-`OnDataChange` wiring, unregister on
+  unsubscribe
+- `TwinCATDriverTests` — `IDriver` lifecycle
+
+Capability surfaces whose contract is verified: `IDriver`, `IReadable`,
+`IWritable`, `ITagDiscovery`, `ISubscribable`, `IHostConnectivityProbe`,
+`IPerCallHostResolver`.
+
+## What it does NOT cover
+
+### 1. AMS / ADS wire traffic
+
+No real AMS router frame is exchanged. Beckhoff's `TwinCAT.Ads` NuGet (their
+own .NET SDK, not libplctag-style OSS) has no in-process fake; tests stub
+the `ITwinCATClient` abstraction above it.
+
+### 2. Multi-route AMS
+
+ADS supports chained routes (`<localNetId> → <routerNetId> → <targetNetId>`)
+for PLCs behind an EC master / IPC gateway. Parse coverage exists; wire-path
+coverage doesn't.
+
+### 3. Notification reliability under jitter
+
+`AddDeviceNotification` delivers at the runtime's cycle boundary; under high
+CPU load or network jitter real notifications can coalesce. The fake fires
+one callback per test invocation — real callback-coalescing behavior is
+untested.
+
+### 4. TC2 vs TC3 variant handling
+
+TwinCAT 2 (ADS v1) and TwinCAT 3 (ADS v2) have subtly different
+`GetSymbolInfoByName` semantics + symbol-table layouts. Driver targets TC3;
+TC2 compatibility is not exercised.
+
+### 5. Cycle-time alignment for `ISubscribable`
+
+Native ADS notifications fire on the PLC cycle boundary. The fake test
+harness assumes notifications fire on a timer the test controls;
+cycle-aligned firing under real PLC control is not verified.
+
+### 6. Alarms / history
+
+Driver doesn't implement `IAlarmSource` or `IHistoryProvider` — not in
+scope for this driver family. TwinCAT 3's TcEventLogger could theoretically
+back an `IAlarmSource`, but shipping that is a separate feature.
+
+## When to trust TwinCAT tests, when to reach for a rig
+
+| Question | Unit tests | Real TwinCAT runtime |
+| --- | --- | --- |
+| "Does the AMS address parser accept X?" | yes | - |
+| "Does notification → `OnDataChange` wire correctly?" | yes (contract) | yes |
+| "Does symbol browsing filter TwinCAT internals?" | yes | yes |
+| "Does a real ADS read return correct bytes?" | no | yes (required) |
+| "Do notifications coalesce under load?" | no | yes (required) |
+| "Does a TC2 PLC work the same as TC3?" | no | yes (required) |
+
+## Follow-up candidates
+
+1. **XAR VM live-population** — scaffolding is in place (this PR); the
+   remaining work is operational: stand up the Hyper-V VM, install XAR,
+   author the `.tsproj` per `TwinCatProject/README.md`, configure the
+   bilateral ADS route, set `TWINCAT_TARGET_HOST` + `TWINCAT_TARGET_NETID`
+   on the dev box. Then the three smoke tests transition skip → pass.
+   Tracked as #221.
+2. **License-rotation automation** — XAR's 7-day trial expires on
+   schedule. Either automate `TcActivate.exe /reactivate` via a
+   scheduled task on the VM (not officially supported; reportedly works
+   for some TC3 builds), or buy a paid runtime license (~$1k one-time
+   per runtime per CPU) to kill the rotation. The doc at
+   `TwinCatProject/README.md` §License rotation walks through both.
+3. **Lab rig** — cheapest IPC (CX7000 / CX9020) on a dedicated network;
+   the only route that covers TC2 + real EtherCAT I/O timing + cycle
+   jitter under CPU load.
+
+## Key fixture / config files
+
+- `tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCATXarFixture.cs`
+  — TCP probe + skip-attributes + env-var parsing
+- `tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCAT3SmokeTests.cs`
+  — three wire-level smoke tests
+- `tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCatProject/README.md`
+  — project spec + VM setup + license-rotation notes
+- `tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Tests/FakeTwinCATClient.cs` —
+  in-process fake with the notification-fire harness used by
+  `TwinCATNativeNotificationTests`
+- `src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATDriver.cs` — ctor takes
+  `ITwinCATClientFactory`

docs/v2/dev-environment.md

@@ -143,15 +143,49 @@ Dev credentials in this inventory are convenience defaults, not secrets. Change
 
 | Resource | Purpose | Type | Default port | Default credentials | Owner |
 |----------|---------|------|--------------|---------------------|-------|
-| **Docker Desktop for Windows** | Host for containerized simulators | Install | (Hyper-V required; not compatible with TwinCAT runtime — see TwinCAT row below for the workaround) | n/a | Integration host admin |
-| **`oitc/modbus-server`** | Modbus TCP simulator (per `test-data-sources.md` §1) | Docker container | 502 (Modbus TCP) | n/a (no auth in protocol) | Integration host admin |
-| **`ab_server`** (libplctag binary) | AB CIP + AB Legacy simulator (per `test-data-sources.md` §2 + §3) | Native binary built from libplctag source; runs in a separate VM or host since it conflicts with Docker Desktop's Hyper-V if run on bare metal | 44818 (CIP) | n/a | Integration host admin |
-| **Snap7 Server** | S7 simulator (per `test-data-sources.md` §4) | Native binary; runs in a separate VM or in WSL2 to avoid Hyper-V conflict | 102 (ISO-TCP) | n/a | Integration host admin |
+| **Docker Desktop for Windows** | Host for every driver test-fixture simulator (Modbus / AB CIP / S7 / OpcUaClient) + SQL Server | Install | (Hyper-V required; not compatible with TwinCAT runtime — see TwinCAT row below for the workaround) | n/a | Integration host admin |
+| **Modbus fixture — `otopcua-pymodbus:3.13.0`** | Modbus driver integration tests | Docker image (local build, see `tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests/Docker/`); 4 compose profiles: `standard` / `dl205` / `mitsubishi` / `s7_1500` | 5020 (non-privileged) | n/a (no auth in protocol) | Developer (per machine) |
+| **AB CIP fixture — `otopcua-ab-server:libplctag-release`** | AB CIP driver integration tests | Docker image (multi-stage build of libplctag's `ab_server` from source, pinned to the `release` tag; see `tests/ZB.MOM.WW.OtOpcUa.Driver.AbCip.IntegrationTests/Docker/`); 4 compose profiles: `controllogix` / `compactlogix` / `micro800` / `guardlogix` | 44818 (CIP / EtherNet/IP) | n/a | Developer (per machine) |
+| **S7 fixture — `otopcua-python-snap7:1.0`** | S7 driver integration tests | Docker image (local build, `python-snap7>=2.0`; see `tests/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/Docker/`); 1 compose profile: `s7_1500` | 1102 (non-privileged; driver honours `S7DriverOptions.Port`) | n/a | Developer (per machine) |
+| **OPC UA Client fixture — `mcr.microsoft.com/iotedge/opc-plc:2.14.10`** | OpcUaClient driver integration tests | Docker image (Microsoft-maintained, pinned; see `tests/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.IntegrationTests/Docker/`) | 50000 (OPC UA) | Anonymous (`--daa` off); auto-accept certs (`--aa`) | Developer (per machine) |
 | **TwinCAT XAR runtime VM** | TwinCAT ADS testing (per `test-data-sources.md` §5; Beckhoff XAR cannot coexist with Hyper-V on the same OS) | Hyper-V VM with Windows + TwinCAT XAR installed under 7-day renewable trial | 48898 (ADS over TCP) | TwinCAT default route credentials configured per Beckhoff docs | Integration host admin |
-| **OPC Foundation reference server** | OPC UA Client driver test source (per `test-data-sources.md` §"OPC UA Client") | Built from `OPCFoundation/UA-.NETStandard` `ConsoleReferenceServer` project | 62541 (default for the reference server) | Anonymous + Username (`user1` / `password1`) per the reference server's built-in user list | Integration host admin |
+| **Rockwell Studio 5000 Logix Emulate** | AB CIP golden-box tier — closes UDT / ALMD / AOI / GuardLogix-safety / CompactLogix-ConnectionSize gaps the ab_server simulator can't cover. Loads the L5X project documented at `tests/.../AbCip.IntegrationTests/LogixProject/README.md`. Tests gated on `AB_SERVER_PROFILE=emulate` + `AB_SERVER_ENDPOINT=<ip>:44818`; see `docs/drivers/AbServer-Test-Fixture.md` §Logix Emulate golden-box tier | Windows-only install; **Hyper-V conflict** — can't coexist with Docker Desktop's WSL 2 backend on the same OS, same story as TwinCAT XAR. Runs on a dedicated Windows PC reachable on the LAN | 44818 (CIP / EtherNet/IP) | None required at the CIP layer; Studio 5000 project credentials per Rockwell install | Integration host admin (license + install); Developer (per session — open Emulate, load L5X, click Run) |
 | **FOCAS TCP stub** (`Driver.Focas.TestStub`) | FOCAS functional testing (per `test-data-sources.md` §6) | Local .NET 10 console app from this repo | 8193 (FOCAS) | n/a | Developer / integration host (run on demand) |
 | **FOCAS FaultShim** (`Driver.Focas.FaultShim`) | FOCAS native-fault injection (per `test-data-sources.md` §6) | Test-only native DLL named `Fwlib64.dll`, loaded via DLL search path in the test fixture | n/a (in-process) | n/a | Developer / integration host (test-only) |
 
+### Docker fixtures — quick reference
+
+Every driver's integration-test simulator ships as a Docker image (or pulls
+one from MCR). Start the one you need, run `dotnet test`, stop it.
+Container lifecycle is always manual — fixtures TCP-probe at collection
+init + skip cleanly when nothing's running.
+
+| Driver | Fixture image | Compose file | Bring up |
+|---|---|---|---|
+| Modbus | local-build `otopcua-pymodbus:3.13.0` | `tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests/Docker/docker-compose.yml` | `docker compose -f <compose> --profile <standard\|dl205\|mitsubishi\|s7_1500> up -d` |
+| AB CIP | local-build `otopcua-ab-server:libplctag-release` | `tests/ZB.MOM.WW.OtOpcUa.Driver.AbCip.IntegrationTests/Docker/docker-compose.yml` | `docker compose -f <compose> --profile <controllogix\|compactlogix\|micro800\|guardlogix> up -d` |
+| S7 | local-build `otopcua-python-snap7:1.0` | `tests/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/Docker/docker-compose.yml` | `docker compose -f <compose> --profile s7_1500 up -d` |
+| OpcUaClient | `mcr.microsoft.com/iotedge/opc-plc:2.14.10` (pinned) | `tests/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.IntegrationTests/Docker/docker-compose.yml` | `docker compose -f <compose> up -d` |
+
+First build of a local-build image takes 1–5 minutes; subsequent runs use
+layer cache. `ab_server` is the slowest (multi-stage build clones
+libplctag + compiles C). Stop with `docker compose -f <compose> --profile <…> down`.
+
+**Endpoint overrides** — every fixture respects an env var to point at a
+real PLC instead of the simulator:
+
+- `MODBUS_SIM_ENDPOINT` (default `localhost:5020`)
+- `AB_SERVER_ENDPOINT` (no default; overrides the local container endpoint)
+- `S7_SIM_ENDPOINT` (default `localhost:1102`)
+- `OPCUA_SIM_ENDPOINT` (default `opc.tcp://localhost:50000`)
+
+No native launchers — Docker is the only supported path for these
+fixtures. A fresh clone needs Docker Desktop and nothing else; fixture
+TCP probes skip tests cleanly when the container isn't running.
+
+See each driver's `docs/drivers/*-Test-Fixture.md` for the full coverage
+map + gap inventory.
+
 ### D. Cloud / external services
 
 | Resource | Purpose | Type | Access | Owner |

docs/v2/focas-version-matrix.md

@@ -0,0 +1,145 @@
+# FOCAS version / capability matrix
+
+Authoritative source for the per-CNC-series ranges that
+[`FocasCapabilityMatrix`](../../src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/FocasCapabilityMatrix.cs)
+enforces at driver init time. Every row cites the Fanuc FOCAS Developer
+Kit function whose documented input range determines the ceiling.
+
+**Why this exists** — we have no FOCAS hardware on the bench and no
+working simulator. Fwlib32 returns `EW_NUMBER` / `EW_PARAM` when you
+hand it an address outside the controller's supported range; the
+driver would map that to a per-read `BadOutOfRange` at steady state.
+Catching at `InitializeAsync` with this matrix surfaces operator
+typos + mismatched series declarations as config errors before any
+session is opened, which is the only feedback loop available without
+a live CNC to read against.
+
+**Who declares the series** — `FocasDeviceOptions.Series` in
+`appsettings.json`. Defaults to `Unknown`, which is permissive — every
+address passes validation. Pre-matrix configs don't break on upgrade.
+
+---
+
+## Series covered
+
+| Enum value | Controller family | Typical era |
+| --- | --- | --- |
+| `Unknown` | (legacy / not declared) | permissive fallback |
+| `Sixteen_i` | 16i / 18i / 21i | 1997-2008 |
+| `Zero_i_D` | 0i-D | 2008-2013 |
+| `Zero_i_F` | 0i-F | 2013-present, general-purpose |
+| `Zero_i_MF` | 0i-MF | 0i-F lathe variant |
+| `Zero_i_TF` | 0i-TF | 0i-F turning variant |
+| `Thirty_i` | 30i-A / 30i-B | 2007-present, high-end |
+| `ThirtyOne_i` | 31i-A / 31i-B | 30i simpler variant |
+| `ThirtyTwo_i` | 32i-A / 32i-B | 30i compact |
+| `PowerMotion_i` | Power Motion i-A / i-MODEL A | motion-only controller |
+
+## Macro variable range (`cnc_rdmacro` / `cnc_wrmacro`)
+
+Common macros `1-33` + `100-199` + `500-999` are universal across all
+series. Extended macros (`#10000+`) exist only on higher-end series.
+The numbers below reflect the extended ceiling per series per the
+DevKit range tables.
+
+| Series | Min | Max | Notes |
+| --- | ---: | ---: | --- |
+| `Sixteen_i` | 0 | 999 | legacy ceiling — no extended |
+| `Zero_i_D` | 0 | 999 | 0i-D still at legacy ceiling |
+| `Zero_i_F` / `Zero_i_MF` / `Zero_i_TF` | 0 | 9999 | extended added on 0i-F |
+| `Thirty_i` / `ThirtyOne_i` / `ThirtyTwo_i` | 0 | 99999 | full extended set |
+| `PowerMotion_i` | 0 | 999 | atypical — limited macro coverage |
+
+## Parameter range (`cnc_rdparam` / `cnc_wrparam`)
+
+| Series | Min | Max |
+| --- | ---: | ---: |
+| `Sixteen_i` | 0 | 9999 |
+| `Zero_i_D` / `Zero_i_F` / `Zero_i_MF` / `Zero_i_TF` | 0 | 14999 |
+| `Thirty_i` / `ThirtyOne_i` / `ThirtyTwo_i` | 0 | 29999 |
+| `PowerMotion_i` | 0 | 29999 |
+
+## PMC letters (`pmc_rdpmcrng` / `pmc_wrpmcrng`)
+
+Addresses are letter + number (e.g. `R100`, `F50.3`). Legacy
+controllers omit the `F`/`G` signal groups that 30i-family ladder
+programs use, and only the 30i-family exposes `K` (keep-relay) +
+`T` (timer).
+
+| Letter | 16i | 0i-D | 0i-F family | 30i family | Power Motion-i |
+| --- | :-: | :-: | :-: | :-: | :-: |
+| `X` | yes | yes | yes | yes | yes |
+| `Y` | yes | yes | yes | yes | yes |
+| `R` | yes | yes | yes | yes | yes |
+| `D` | yes | yes | yes | yes | yes |
+| `E` | — | yes | yes | yes | — |
+| `A` | — | yes | yes | yes | — |
+| `F` | — | — | yes | yes | — |
+| `G` | — | — | yes | yes | — |
+| `M` | — | — | yes | yes | — |
+| `C` | — | — | yes | yes | — |
+| `K` | — | — | — | yes | — |
+| `T` | — | — | — | yes | — |
+
+Letter match is case-insensitive. `FocasAddress.PmcLetter` is carried
+as a string (not char) so the matrix can do ordinal-ignore-case
+comparison.
+
+## PMC address-number ceiling
+
+PMC addresses are byte-addressed on read + bit-addressed on write;
+`FocasAddress` carries the bit index separately, so these are byte
+ceilings.
+
+| Series | Max byte | Notes |
+| --- | ---: | --- |
+| `Sixteen_i` | 999 | legacy |
+| `Zero_i_D` | 1999 | doubled since 16i |
+| `Zero_i_F` family | 9999 | |
+| `Thirty_i` family | 59999 | highest density |
+| `PowerMotion_i` | 1999 | |
+
+## Error surface
+
+When a tag fails validation, `FocasDriver.InitializeAsync` throws
+`InvalidOperationException` with a message of the form:
+
+```
+FOCAS tag '<name>' (<address>) rejected by capability matrix: <reason>
+```
+
+`<reason>` is the verbatim string from `FocasCapabilityMatrix.Validate`
+and always names the series + the documented limit so the operator
+can either raise the limit (if wrong) or correct the CNC series they
+declared (if mismatched). Sample:
+
+```
+FOCAS tag 'X_axis_macro_ext' (MACRO:50000) rejected by capability
+matrix: Macro variable #50000 is outside the documented range
+[0, 9999] for Zero_i_F.
+```
+
+## How this matrix stays honest
+
+- Every row is covered by a parameterized test in
+  [`FocasCapabilityMatrixTests.cs`](../../tests/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Tests/FocasCapabilityMatrixTests.cs)
+  — 46 cases across macro / parameter / PMC-letter / PMC-number
+  boundaries + unknown-series permissiveness + rejection-message
+  content + case-insensitivity.
+- Widening or narrowing a range in the matrix without updating this
+  doc will fail a test, because the theories cite the specific row
+  they reflect in their `InlineData`.
+- The matrix is not comprehensive — it encodes only the subset of
+  FOCAS surface the driver currently exposes (Macro / Parameter /
+  PMC). When the driver gains a new capability (e.g. tool management,
+  alarm history), add its series-specific range tables here + matching
+  tests at the same time.
+
+## Follow-up
+
+This validation closes the cheap half of the FOCAS hardware-free
+stability gap — config errors now fail at load instead of per-read.
+The expensive half is Tier-C process isolation so that a crashing
+`Fwlib32.dll` doesn't take the main OPC UA server down with it. See
+[`docs/v2/implementation/focas-isolation-plan.md`](implementation/focas-isolation-plan.md)
+for that plan (task #220).

docs/v2/implementation/adr-001-equipment-node-walker.md

@@ -0,0 +1,248 @@
+# ADR-001 — Equipment node walker: how driver tags bind to the UNS address space
+
+**Status:** Accepted 2026-04-20 — Option A (Config-primary); Option D deferred to v2.1
+
+**Related tasks:** [#195 IdentificationFolderBuilder wire-in](../../../) (blocked on this)
+
+**Related decisions in `plan.md`:** #110 (Tag belongs to Equipment via FK in Equipment ns),
+#116 / #117 / #121 (five identifiers as properties, `Equipment.Name` as path segment),
+#120 (UNS hierarchy mandatory in Equipment ns; SystemPlatform ns exempt).
+
+## Context
+
+Today the `DriverNodeManager` builds its address space by calling
+`ITagDiscovery.DiscoverAsync` on each registered driver. Every driver returns whatever
+browse shape its wire protocol produces — Galaxy returns gobjects with attributes, Modbus
+returns whatever tag configs the operator authored, AB CIP returns controller-walk output,
+etc. The result is a per-driver subtree, rooted under the driver's own namespace, with no
+UNS levels.
+
+The Config DB meanwhile carries the authoritative UNS model for every Equipment-kind
+namespace:
+
+```
+ConfigGeneration
+ └─ ServerCluster
+    └─ Namespace (Kind=Equipment)
+       └─ UnsArea
+          └─ UnsLine
+             └─ Equipment (carries 9 OPC 40010 Identification fields + 5 identifiers)
+                └─ Tag (EquipmentId FK when Kind=Equipment; DriverInstanceId + FolderPath when Kind=SystemPlatform)
+```
+
+Decision #110 already binds `Tag → Equipment` by foreign key. Decision #120 requires the
+Equipment-namespace browse tree to conform to `Enterprise/Site/Area/Line/Equipment/TagName`.
+The building blocks exist:
+
+- `IdentificationFolderBuilder.Build(equipmentBuilder, row)` — pure function that hangs
+  nine OPC 40010 properties under an Equipment node. Shipped, untested in integration.
+- `Equipment` table rows with `UnsLineId` FK + the 9 identification columns + the 5
+  identifier columns.
+- `Tag` table rows with nullable `EquipmentId` + a `TagConfig` JSON column carrying the
+  wire-level address.
+- `NodeScopeResolver` — Phase-1 stub that returns a cluster-level scope only, with an
+  explicit "future resolver will join against the Configuration DB" note.
+
+What's missing is the **walker**: server-side code that reads the UNS + Equipment + Tag
+rows for the current published generation, traverses them in UNS order, materializes each
+level as an OPC UA folder, and wires `IdentificationFolderBuilder.Build` + the 5-identifier
+properties under each Equipment node.
+
+The walker isn't pure bookkeeping — it has to decide **how driver-discovered tags bind to
+UNS Equipment nodes**. That's the decision this ADR resolves.
+
+## Open question
+
+> For an Equipment-kind driver, is the published OPC UA surface driven by (a) the Config
+> DB's `Tag` rows, (b) the driver's `ITagDiscovery.DiscoverAsync` output, or (c) some
+> combination?
+
+SystemPlatform-kind drivers (Galaxy only, today) are unambiguous: decision #120 exempts
+them from UNS + they keep their v1 native hierarchy. The walker does not touch
+SystemPlatform namespaces beyond the existing driver-discovery path. This ADR only decides
+Equipment-kind composition.
+
+## Options
+
+### Option A — Config-primary
+
+The `Tag` table is the sole source of truth for what gets published. `ITagDiscovery`
+becomes a validation + enrichment surface, not a discovery surface.
+
+**Walker flow:**
+
+1. Read `UnsArea` / `UnsLine` / `Equipment` / `Tag` for the published generation.
+2. Walk Area → Line → Equipment, materializing each level as an OPC UA folder.
+3. Under each Equipment node:
+   - Add the 5 identifier properties (`EquipmentId`, `EquipmentUuid`, `MachineCode`,
+     `ZTag`, `SAPID`) as OPC UA properties per decision #121.
+   - Call `IdentificationFolderBuilder.Build` to add the `Identification` sub-folder with
+     the 9 OPC 40010 fields.
+   - For each `Tag` row bound to this Equipment: ask the driver's `IReadable` /
+     `IWritable` surface whether it can address `Tag.TagConfig.address`; if yes, create a
+     variable node. If no, create a `BadNotFound` placeholder with a diagnostic so
+     operators see the mismatch instead of a silent drop.
+4. `ITagDiscovery.DiscoverAsync` is re-purposed to **enrich** — driver may return schema
+   hints (data type, bounds, description) that operators missed when authoring the Tag
+   row. The Admin UI surfaces them as "driver suggests" hints for next-draft edits.
+
+**Trade-offs:**
+
+- ✅ Matches decision #110's framing cleanly. `Tag` rows carry the contract; nothing gets
+  published that's not explicitly authored.
+- ✅ Same model for every Equipment-kind driver. Modbus / S7 / AB CIP / AB Legacy /
+  TwinCAT / FOCAS / OpcUaClient all compose identically.
+- ✅ UNS hierarchy is always exactly as-authored. No race between "driver added a tag at
+  runtime" and "operator hasn't approved it yet."
+- ✅ Aligns with the Config-DB-first operator story the Admin UI already tells.
+- ❌ Drivers with large native schemas (TwinCAT PLCs with thousands of symbols, AB CIP
+  controllers with full @tags walkers) can't "just publish everything" — operators must
+  author Tag rows. This is a pure workflow cost, not a correctness cost.
+- ❌ A Tag row whose driver can't address it produces a placeholder node at runtime
+  (BadNotFound), not a publish-time validation failure. Mitigation: `sp_ValidateDraft`
+  already validates per-driver references at publish — extend it to call each driver's
+  existence check, or keep it as runtime-visible with an Admin UI indicator.
+
+### Option B — Discovery-primary
+
+`ITagDiscovery.DiscoverAsync` is the source of truth for what gets published. The walker
+joins discovered tags against Config-DB Equipment rows to assemble the UNS tree.
+
+**Walker flow:**
+
+1. Driver runs `ITagDiscovery.DiscoverAsync` — returns its native tag graph.
+2. Walker reads `Equipment` + `Tag` rows; uses `Tag.TagConfig.address` to match against
+   discovered references.
+3. For each match: materialize the UNS path + attach the discovered variable under the
+   bound Equipment node.
+4. Discovered tags with no matching `Tag` row: silently dropped (or surfaced under a
+   `Unmapped/` diagnostic folder).
+5. `Tag` rows with no discovered match: hidden (or surfaced as `BadNotFound` placeholder
+   same as Option A).
+
+**Trade-offs:**
+
+- ✅ Lets drivers with rich discovery (TwinCAT `SymbolLoaderFactory`, AB CIP `@tags`)
+  publish live controller state without operator-authored Tag rows for every symbol.
+- ✅ Driver-native metadata (real OPC UA data types, real bounds) is authoritative.
+- ❌ Conflicts with the Config-DB-first publish workflow. Operators publish a generation
+  + discover a different set at runtime + the two don't necessarily match. Diff tooling
+  becomes harder.
+- ❌ Galaxy's SystemPlatform-namespace path still uses Option-B-like discovery — so the
+  codebase would host two compositions regardless. But adding a second
+  discovery-primary composition for Equipment-kind would double the surface operators
+  have to reason about.
+- ❌ Requires each driver to emit tag identifiers that stably match `Tag.TagConfig.address`
+  shape across re-discovery. Works for Galaxy (attribute full refs are stable); harder for
+  AB CIP where the @tags walker may return tags operators haven't declared.
+- ❌ Operator-visible symptom of "my tag didn't publish" splits between two places: the
+  Tag row exists (Config DB) + the driver can't find it (runtime discovery). Option A
+  surfaces the same gap as a single `BadNotFound` placeholder; B multiplies it.
+
+### Option C — Parallel namespaces
+
+Driver tags are always published under a driver-native folder hierarchy (discovery-driven,
+same as today). A secondary UNS "view" namespace is overlaid, containing Equipment nodes
+with Identification sub-folders + `Organizes` references pointing at the driver-native tag
+nodes.
+
+**Walker flow:**
+
+1. Driver's native discovery publishes `ns=2;s={DriverInstanceId}/{...driver shape}` as
+   today.
+2. Walker reads UNS + Equipment + Tag rows.
+3. For each Equipment, creates a node under the UNS namespace (`ns=3;s=UNS/Site/Area/Line/Equipment`)
+   + adds Identification properties + creates `Organizes` references from the Equipment
+   node to the matching driver-native variable nodes.
+
+**Trade-offs:**
+
+- ✅ Preserves the discovery-first driver shape — no change to what Modbus / S7 / AB CIP
+  publish natively; those projects keep working identically.
+- ✅ UNS tree becomes an overlay that operators can opt into or out of. External consumers
+  that want UNS addressing browse via the UNS namespace; consumers that want driver-native
+  addressing keep using the driver namespace.
+- ❌ Doubles the OPC UA node count for every Equipment-kind tag (one node in driver ns,
+  one reference in UNS ns). OPC UA clients handle it but it inflates browse-result sizes.
+- ❌ Contradicts decision #120: "Equipment namespace browse paths must conform to the
+  canonical 5-level Unified Namespace structure." Option C makes the driver namespace
+  browse path NOT conform; the UNS namespace is a second view. An external client that
+  reads the Equipment namespace in driver-native shape doesn't see UNS at all.
+- ❌ Identification ACL semantics get complicated — the sub-folder lives in the UNS ns,
+  but the tag data lives in the driver ns. Two different scope ids; two grants to author.
+
+### Option D — Config-primary with driver-discovery-assist
+
+Same as Option A, but `ITagDiscovery.DiscoverAsync` is called during *draft authoring*
+(not at server runtime) to populate an Admin UI "discovered tags available" panel that
+operators can one-click-add to the draft Tag table. At publish time the Tag rows drive
+the server as in Option A — discovery runs only as an offline helper.
+
+**Trade-offs:**
+
+- ✅ Keeps Option A's runtime semantics — Config DB is the sole publish-time truth.
+- ✅ Closes Option A's only real workflow weakness (authoring Tag rows for large
+  controllers) by letting operators import discovered tags with a click.
+- ✅ Draws a clean line between author-time discovery (optional, offline) and publish-time
+  resolution (strict, Config-DB-driven).
+- ❌ Adds work that isn't on the Phase 6.4 checklist — Admin UI needs a "pull discovered
+  tags from this driver" flow, which means the Admin host needs to proxy a DiscoverAsync
+  call through the Server process (or directly into the driver — more complex deployment
+  topology). v2.1 work, not v2.
+
+## Recommendation
+
+**Pick Option A.** Ship the walker as Config-primary immediately; defer Option D's
+Admin-UI discovery-assist to v2.1 once the walker is proven.
+
+Reasons:
+
+1. **Decision #110 already points here.** `Tag.EquipmentId` + `Tag.TagConfig` are the
+   published contract. Option A is the straight-line implementation of that contract.
+2. **Identical composition across seven drivers.** Every Equipment-kind driver uses the
+   same walker code path. New drivers (e.g. a future OPC UA Client gateway mode) plug in
+   without touching the walker.
+3. **Phase 6.4 Admin UI already authors Tag rows.** CSV import, UnsTab drag/drop, draft
+   diff — all operate on Tag rows. The walker being Tag-row-driven means the Admin UI
+   and the server see the same surface.
+4. **BadNotFound is a clean failure mode.** An operator publishes a Tag row whose
+   address the driver can't reach → client sees a `BadNotFound` variable with a
+   diagnostic, operator fixes the Tag row + republishes. This is legible + easy to
+   debug. Options B and C smear the failure across multiple namespaces.
+5. **Option D is additive, not alternative.** Nothing in A blocks adding D later; the
+   walker contract stays the same, Admin UI just gets a discovery-assist panel.
+
+The walker implementation lands under two tasks this ADR spawns (if accepted):
+
+- **Task A** — Build `EquipmentNodeWalker` in `Core.OpcUa` that drives the
+  `ClusterNode → Namespace → UnsArea → UnsLine → Equipment → Tag` traversal, calls
+  `IdentificationFolderBuilder.Build` per Equipment, materializes the 5 identifier
+  properties, and creates variable nodes for each bound Tag row. Writes integration
+  tests covering the happy path + BadNotFound placeholder.
+- **Task B** — Extend `NodeScopeResolver` to join against Config DB + populate the
+  full `NodeScope` path (UnsAreaId / UnsLineId / EquipmentId / TagId). Unblocks the
+  Phase 6.2 finer-grained ACL (per-Equipment, per-UnsLine grants). Add ACL integration
+  test per task #195 — browse `Equipment/Identification` as unauthorized user,
+  assert `BadUserAccessDenied`.
+
+Task #195 closes on Task B's landing.
+
+## Consequences if we don't decide
+
+- Task #195 stays blocked. The `IdentificationFolderBuilder` exists but is dead code
+  reachable only from its unit tests.
+- `NodeScopeResolver` stays at cluster-level scope. Per-Equipment / per-UnsLine ACL
+  grants work at the Admin UI authoring layer + the data-plane evaluator, but the
+  runtime scope resolution never populates anything below `ClusterId + TagId` — so
+  finer grants are effectively cluster-wide at dispatch. Phase 6.2's rollout plan calls
+  this out as a rollout limitation; it's not a correctness bug but it's a feature gap.
+- Equipment metadata (the 9 OPC 40010 fields, the 5 identifiers) ships in the Config DB
+  + the Admin UI editor but never surfaces on the OPC UA endpoint. External consumers
+  (ERP, SAP PM) can't resolve equipment via OPC UA properties as decision #121 promises.
+
+## Next step
+
+Accept this ADR + spawn Task A + Task B.
+
+If the recommendation is rejected, the alternative options (B / C / D) are ranked by
+implementation cost in the Trade-offs sections above. My strong preference is A + defer D.

docs/v2/implementation/adr-002-driver-vs-virtual-dispatch.md

@@ -0,0 +1,136 @@
+# ADR-002 — Driver-vs-virtual dispatch: how `DriverNodeManager` routes reads, writes, and subscriptions across driver tags and virtual (scripted) tags
+
+**Status:** Accepted 2026-04-20 — Option B (single NodeManager + NodeSource tag on the resolver output); Options A and C explicitly rejected.
+
+**Related phase:** [Phase 7 — Scripting Runtime + Scripted Alarms](phase-7-scripting-and-alarming.md) Stream G.
+
+**Related tasks:** #237 Phase 7 Stream G — Address-space integration.
+
+**Related ADRs:** [ADR-001 — Equipment node walker](adr-001-equipment-node-walker.md) (this ADR extends the walker + resolver it established).
+
+## Context
+
+Phase 7 introduces **virtual tags** — OPC UA variables whose values are computed by user-authored C# scripts against other tags (driver or virtual). Per design decision #2 in the Phase 7 plan, virtual tags **live in the Equipment tree alongside driver tags** (not a separate `/Virtual/...` namespace). An operator browsing `Enterprise/Site/Area/Line/Equipment/` sees a flat list of children that includes both driver-sourced variables (e.g. `SpeedSetpoint` coming from a Modbus tag) and virtual variables (e.g. `LineRate` computed from `SpeedSetpoint × 0.95`).
+
+From the operator's perspective there is no difference. From the server's perspective there is a big one: a read / write / subscribe on a driver node must dispatch to a driver's `IReadable` / `IWritable` / `ISubscribable` implementation; the same operation on a virtual node must dispatch to the `VirtualTagEngine`. The existing `DriverNodeManager` (shipped in Phase 1, extended by ADR-001) only knows about the driver case today.
+
+The question is how the dispatch should branch. Three options considered.
+
+## Options
+
+### Option A — A separate `VirtualTagNodeManager` sibling to `DriverNodeManager`
+
+Register a second `INodeManager` with the OPC UA stack dedicated to virtual-tag nodes. Each tag landed under an Equipment folder would be owned by whichever NodeManager materialized it; mixed folders would have children belonging to two different managers.
+
+**Pros:**
+- Clean separation — virtual-tag code never touches driver code paths.
+- Independent lifecycle: restart the virtual-tag engine without touching drivers.
+
+**Cons:**
+- ADR-001's `EquipmentNodeWalker` was designed as a single walker producing a single tree under one NodeManager. Forking into two walkers (one per source) risks the UNS / Equipment folders existing twice (once per manager) with different child sets, and the OPC UA stack treating them as distinct nodes.
+- Mixed equipment folders: when a Line has 3 driver tags + 2 virtual tags, a client browsing the Line folder expects to see 5 children. Two NodeManagers each claiming ownership of the same folder adds the browse-merge problem the stack doesn't do cleanly.
+- ACL binding (Phase 6.2 trie): one scope per Equipment folder, resolved by `NodeScopeResolver`. Two NodeManagers means two resolution paths or shared resolution logic — cross-manager coupling that defeats the separation.
+- Audit pathways (Phase 6.2 `IAuditLogger`) and resilience wrappers (Phase 6.1 `CapabilityInvoker`) are wired into the existing `DriverNodeManager`. Duplicating them into a second manager doubles the surface that the Roslyn analyzer from Phase 6.1 Stream A follow-up must keep honest.
+
+**Rejected** because the sharing of folders (Equipment nodes owning both kinds of children) is the common case, not the exception. Two NodeManagers would fight for ownership on every Equipment node.
+
+### Option B — Single `DriverNodeManager`, `NodeScopeResolver` returns a `NodeSource` tag, dispatch branches on source
+
+`NodeScopeResolver` (established in ADR-001) already joins nodes against the config DB to produce a `ScopeId` for ACL enforcement. Extend it to **also return a `NodeSource` enum** (`Driver` or `Virtual`). `DriverNodeManager` dispatch methods check the source and route:
+
+```csharp
+internal sealed class DriverNodeManager : CustomNodeManager2
+{
+    private readonly IReadOnlyDictionary<string, IDriver> _drivers;
+    private readonly IVirtualTagEngine _virtualTagEngine;
+    private readonly NodeScopeResolver _resolver;
+
+    protected override async Task ReadValueAsync(NodeId nodeId, ...)
+    {
+        var scope = _resolver.Resolve(nodeId);
+        // ... ACL check via Phase 6.2 trie (unchanged)
+        return scope.Source switch
+        {
+            NodeSource.Driver  => await _drivers[scope.DriverInstanceId].ReadAsync(...),
+            NodeSource.Virtual => await _virtualTagEngine.ReadAsync(scope.VirtualTagId, ...),
+        };
+    }
+}
+```
+
+**Pros:**
+- Single address-space tree. `EquipmentNodeWalker` emits one folder per Equipment node and hangs both driver and virtual children under it. Browse / subscribe fan-out / ACL resolution all happen in one NodeManager with one mental model.
+- ACL binding works identically for both kinds. A user with `ReadEquipment` on `Line1/Pump_7` can read every child, driver-sourced or virtual.
+- Phase 6.1 resilience wrapping + Phase 6.2 audit logging apply uniformly. The `CapabilityInvoker` analyzer stays correct without new exemptions.
+- Adding future source kinds (e.g. a "derived tag" that's neither a driver read nor a script evaluation) is a single-enum-case addition — no new NodeManager.
+
+**Cons:**
+- `NodeScopeResolver` becomes slightly chunkier — it now carries dispatch metadata in addition to ACL scope. We own that complexity; the payoff is one tree, one lifecycle.
+- A bug in the dispatch branch could leak a driver call into the virtual path or vice versa. Mitigated by an xUnit theory in Stream G.4 that mixes both kinds in one Equipment folder and asserts each routes correctly.
+
+**Accepted.**
+
+### Option C — Virtual tag engine registers as a synthetic `IDriver`
+
+Implement a `VirtualTagDriverAdapter` that wraps `VirtualTagEngine` and registers it alongside real drivers through the existing `DriverTypeRegistry`. Then `DriverNodeManager` dispatches everything through driver plumbing — virtual tags are just "a driver with no wire."
+
+**Pros:**
+- Reuses every existing `IDriver` pathway without modification.
+- Dispatch branch is trivial because there's no branch — everything routes through driver plumbing.
+
+**Cons:**
+- `DriverInstance` is the wrong shape for virtual-tag config: no `DriverType`, no `HostAddress`, no connectivity probe, no lifecycle-initialization parameters, no NSSM wrapper. Forcing it to fit means adding null columns / sentinel values everywhere.
+- `IDriver.InitializeAsync` / `IRediscoverable` semantics don't match a scripting engine — the engine doesn't "discover" tags against a wire, it compiles scripts against a config snapshot.
+- The resilience Polly wrappers are calibrated for network-bound calls (timeout / retry / circuit breaker). Applying them to a script evaluation is either a pointless passthrough or wrong tuning.
+- The Admin UI would need special-casing in every driver-config screen to hide fields that don't apply. The shape mismatch leaks everywhere.
+
+**Rejected** because the fit is worse than Option B's lightweight dispatch branch. The pretense of uniformity would cost more than the branch it avoids.
+
+## Decision
+
+**Option B is accepted.**
+
+`NodeScopeResolver.Resolve(nodeId)` returns a `NodeScope` record with:
+
+```csharp
+public sealed record NodeScope(
+    string ScopeId,            // ACL scope ID — unchanged from ADR-001
+    NodeSource Source,         // NEW: Driver or Virtual
+    string? DriverInstanceId,  // populated when Source=Driver
+    string? VirtualTagId);     // populated when Source=Virtual
+
+public enum NodeSource
+{
+    Driver,
+    Virtual,
+}
+```
+
+`DriverNodeManager` holds a single reference to `IVirtualTagEngine` alongside its driver dictionary. Read / Write / Subscribe dispatch pattern-matches on `scope.Source` and routes accordingly. Writes to a virtual node from an OPC UA client return `BadUserAccessDenied` because per Phase 7 decision #6, virtual tags are writable **only** from scripts via `ctx.SetVirtualTag`. That check lives in `DriverNodeManager` before the dispatch branch — a dedicated ACL rule rather than a capability of the engine.
+
+Dispatch tests (Phase 7 Stream G.4) must cover at minimum:
+- Mixed Equipment folder (driver + virtual children) browses with all children visible
+- Read routes to the correct backend for each source kind
+- Subscribe delivers changes from both kinds on the same subscription
+- OPC UA client write to a virtual node returns `BadUserAccessDenied` without invoking the engine
+- Script-driven write to a virtual node (via `ctx.SetVirtualTag`) updates the value + fires subscription notifications
+
+## Consequences
+
+- `EquipmentNodeWalker` (ADR-001) gains an extra input channel: the config DB's `VirtualTag` table alongside the existing `Tag` table. Walker emits both kinds of children under each Equipment folder with the `NodeSource` tag set per row.
+- `NodeScopeResolver` gains a `NodeSource` return value. The change is additive (ADR-001's `ScopeId` field is unchanged), so Phase 6.2's ACL trie keeps working without modification.
+- `DriverNodeManager` gains a dispatch branch but the shape of every `I*` call into drivers is unchanged. Phase 6.1's resilience wrapping applies identically to the driver branch; the virtual branch wraps separately (virtual tag evaluation errors map to `BadInternalError` per Phase 7 decision #11, not through the Polly pipeline).
+- Adding a future source kind (e.g. an alias tag, a cross-cluster federation tag) is one enum case + one dispatch arm + the equivalent walker extension. The architecture is extensible without rewrite.
+
+## Not Decided (revisitable)
+
+- **Whether `IVirtualTagEngine` should live alongside `IDriver` in `Core.Abstractions` or stay in the Phase 7 project.** Plan currently keeps it in Phase 7's `Core.VirtualTags` project because it's not a driver capability. If Phase 7 Stream G discovers significant shared surface, promote later — not blocking.
+- **Whether server-side method calls from OPC UA clients (e.g. a future "force-recompute-this-virtual-tag" admin method) should route through the same dispatch.** Out of scope — virtual tags have no method nodes today; scripted alarm method calls (`OneShotShelve` etc.) route through their own `ScriptedAlarmEngine` path per Phase 7 Stream C.6.
+
+## References
+
+- [Phase 7 — Scripting Runtime + Scripted Alarms](phase-7-scripting-and-alarming.md) Stream G
+- [ADR-001 — Equipment node walker](adr-001-equipment-node-walker.md)
+- [`docs/v2/plan.md`](../plan.md) decision #110 (Tag-to-Equipment binding)
+- [`docs/v2/plan.md`](../plan.md) decision #120 (UNS hierarchy requirements)
+- Phase 6.2 `NodeScopeResolver` ACL join

docs/v2/implementation/exit-gate-phase-2-closed.md

@@ -0,0 +1,108 @@
+# Phase 2 Close-Out (2026-04-20)
+
+> Supersedes `exit-gate-phase-2-final.md` (2026-04-18) which captured the state at PR 2
+> merge. Between that doc and today, PR 4 closed all open high + medium findings, PR 13
+> shipped the probe manager, PR 14 shipped the alarm subsystem, and PR 61 closed the v1
+> archive deletion. Phase 2 is closed.
+
+## Status: **CLOSED**
+
+Every stream in Phase 2 is complete. Every finding from the 2026-04-18 adversarial review
+is resolved. The v1 archive is deleted. The Galaxy driver runs the full
+`Shared` / `Host` / `Proxy` topology against live MXAccess on the dev box with all 9
+capability interfaces wired end-to-end.
+
+## Stream-by-stream
+
+| Stream | Plan §reference | Status | Close commit |
+|---|---|---|---|
+| A — Driver.Galaxy.Shared | §A.1–A.3 | ✅ Complete | PR 1 |
+| B — Driver.Galaxy.Host | §B.1–B.10 | ✅ Complete — real Win32 pump, Tier C protections, all 3 IGalaxyBackend impls (Stub / DbBacked / MxAccess), probe manager, alarm tracker, Historian wire-up | PR 1 + PR 4 + PR 12 + PR 13 + PR 14 |
+| C — Driver.Galaxy.Proxy | §C.1–C.4 | ✅ Complete — all 9 capability interfaces, supervisor (Backoff + CircuitBreaker + HeartbeatMonitor), subscription push frames | PR 1 + PR 4 |
+| D — Retire legacy Host | §D.1–D.3 | ✅ Complete — archive markings landed in PR 2, source tree deletion in Phase 3 PR 18, status doc closed in PR 61 | PR 2 → Phase 3 PR 18 → PR 61 |
+| E — Parity validation | §E.1–E.4 | ✅ Complete — E2E suite + 4 stability-finding regression tests + `HostSubprocessParityTests` cross-FX integration | PR 2 |
+
+## 2026-04-18 adversarial findings — resolved
+
+All four `High` + `Medium` items flagged as OPEN at the 2026-04-18 exit gate closed in PR 4
+(`caa9cb8 Phase 2 PR 4 — close the 4 open high/medium MXAccess findings from
+exit-gate-phase-2-final.md`):
+
+| ID | Finding | Resolution |
+|----|---------|------------|
+| High 1 | MxAccess Read subscription-leak on cancellation | One-shot read now wraps subscribe → first `OnDataChange` → unsubscribe in try/finally. Per-tag callback always detached. If the read installed the underlying subscription (prior `_addressToHandle` key was absent) it tears it down on the way out — no leaked probe item handles on caller cancel or timeout. |
+| High 2 | No MXAccess reconnect loop, only supervisor-driven recycle | `MxAccessClient` gains `MxAccessClientOptions { AutoReconnect, MonitorInterval=5s, StaleThreshold=60s }` + a background `MonitorLoopAsync` started on first `ConnectAsync`. Checks `_lastObservedActivityUtc` each interval (bumped by every `OnDataChange` callback); if stale, probes the proxy with a no-op COM `AddItem("$Heartbeat")` on the StaPump; on probe failure does reconnect-with-replay — Unregister (best-effort), Register, snapshot `_addressToHandle.Keys`, clear, re-AddItem every previously-active subscription. `ConnectionStateChanged` fires on the false→true transition; `ReconnectCount` bumps. |
+| Medium 3 | `SubscribeAsync` doesn't push `OnDataChange` frames yet | `IGalaxyBackend` gains `OnDataChange` / `OnAlarmEvent` / `OnHostStatusChanged` events. New `IFrameHandler.AttachConnection(FrameWriter)` called per-connection by `PipeServer` after Hello. `GalaxyFrameHandler.ConnectionSink` subscribes the events for the connection lifetime, fire-and-forgets pushes as `MessageKind.OnDataChangeNotification` / `AlarmEvent` / `RuntimeStatusChange` frames through the writer, swallows `ObjectDisposedException` for dispose race, unsubscribes on Dispose. `MxAccessGalaxyBackend.SubscribeAsync` wires `OnTagValueChanged` that fans values out per-tag to every subscription listening (one MXAccess subscription, multi-fan-out via `_refToSubs` reverse map). `UnsubscribeAsync` only calls `mx.UnsubscribeAsync` when the last sub for a tag drops. |
+| Medium 4 | `WriteValuesAsync` doesn't await `OnWriteComplete` | `MxAccessClient.WriteAsync` rewritten to return `Task<bool>` via the v1-style TCS-keyed-by-item-handle pattern in `_pendingWrites`. TCS added before the `Write` call, awaited with configurable timeout (default 5s), removed in finally. Returns true only when `OnWriteComplete` reported success. `MxAccessGalaxyBackend.WriteValuesAsync` reports per-tag `Bad_InternalError` ("MXAccess runtime reported write failure") when the bool returns false. |
+
+## Cross-cutting deferrals — resolved
+
+| Deferral | Resolution |
+|----------|------------|
+| Deletion of v1 archive | Phase 3 PR 18 deleted the source trees; PR 61 closed `V1_ARCHIVE_STATUS.md` |
+| Wonderware Historian SDK plugin port | `Driver.Galaxy.Host/Backend/Historian/` ports the 10 source files (`HistorianDataSource`, `HistorianClusterEndpointPicker`, `HistorianHealthSnapshot`, etc.). `MxAccessGalaxyBackend` implements `HistoryReadAsync` / `HistoryReadProcessedAsync` / `HistoryReadAtTimeAsync` / `HistoryReadEventsAsync`. `GalaxyProxyDriver.MapAggregateToColumn` translates `HistoryAggregateType` → `AnalogSummaryQuery` column names on the proxy side so Host stays OPC-UA-free. |
+| MxAccess subscription push frames | Closed under Medium 3 above |
+| Wonderware Historian-backed HistoryRead | Closed under the Historian port row |
+| Alarm subsystem wire-up | PR 14. `GalaxyAlarmTracker` in `Backend/Alarms/` advises the four Galaxy alarm-state attributes per `IsAlarm=true` attribute (`.InAlarm`, `.Priority`, `.DescAttrName`, `.Acked`), runs the OPC UA Part 9 lifecycle simplified for the Galaxy AlarmExtension model, raises `AlarmTransition` events (Active / Acknowledged / Inactive) forwarded through the existing `OnAlarmEvent` IPC frame. `AcknowledgeAlarmAsync` writes operator comment to `<tag>.AckMsg` through the PR 4 TCS-by-handle write path. |
+| Reconnect-without-recycle in MxAccessClient | Closed under High 2 (reconnect-with-replay loop is the "without-recycle" path — supervisor recycle remains the fallback). |
+| Real downstream-consumer cutover | Out of scope for this repo; phased Year-3 rollout per `docs/v2/plan.md` §Rollout — not a Phase 2 deliverable. |
+
+## 2026-04-20 test baseline
+
+Full-solution `dotnet test ZB.MOM.WW.OtOpcUa.slnx` on `v2` tip:
+
+| Project | Pass | Skip | Target |
+|---|---:|---:|---|
+| Core.Abstractions.Tests | 37 | 0 | net10 |
+| Client.Shared.Tests | 136 | 0 | net10 |
+| Client.CLI.Tests | 52 | 0 | net10 |
+| Client.UI.Tests | 98 | 0 | net10 |
+| Driver.S7.Tests | 58 | 0 | net10 |
+| Driver.Modbus.Tests | 182 | 0 | net10 |
+| Driver.Modbus.IntegrationTests | 2 | 21 | net10 (Docker-gated) |
+| Driver.AbLegacy.Tests | 96 | 0 | net10 |
+| Driver.AbCip.Tests | 211 | 0 | net10 |
+| Driver.AbCip.IntegrationTests | 11 | 1 | net10 (ab_server-gated) |
+| Driver.TwinCAT.Tests | 110 | 0 | net10 |
+| Driver.OpcUaClient.Tests | 78 | 0 | net10 |
+| Driver.FOCAS.Tests | 119 | 0 | net10 |
+| Driver.Galaxy.Shared.Tests | 6 | 0 | net10 |
+| Driver.Galaxy.Proxy.Tests | 18 | 7 | net10 (live-Galaxy-gated) |
+| **Driver.Galaxy.Host.Tests** | **107** | **0** | **net48 x86** |
+| Analyzers.Tests | 5 | 0 | net10 |
+| Core.Tests | 182 | 0 | net10 |
+| Configuration.Tests | 71 | 0 | net10 |
+| Admin.Tests | 92 | 0 | net10 |
+| Server.Tests | 173 | 0 | net10 |
+| **Total** | **1844** | **29** | |
+
+**Observed flake**: one Configuration.Tests failure on the first full-solution run turned
+green on re-run. Not a stable regression; logged as a known flake until it reproduces.
+
+**Skips are all infra-gated**:
+- Modbus 21 skips — oitc/modbus-server Docker container not started.
+- AbCip 1 skip — libplctag `ab_server` binary not on PATH.
+- Galaxy.Proxy 7 skips — live Galaxy stack not reachable from the current shell (admin-token pipe ACL).
+
+## What "Phase 2 closed" means for Phase 3 and later
+
+- Galaxy runs as first-class v2 driver, same capability-interface contract as Modbus / S7 /
+  AbCip / AbLegacy / TwinCAT / FOCAS / OpcUaClient.
+- No v1 code path remains. Anything invoking the `ZB.MOM.WW.LmxOpcUa.*` namespaces is
+  historical; any future work routes through `Driver.Galaxy.Proxy` + the named-pipe IPC.
+- The 2026-04-13 stability findings live on as named regression tests under
+  `tests/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.E2E/StabilityFindingsRegressionTests.cs` — a
+  future refactor that reintroduces any of those four defects trips the test.
+- Aveva Historian integration is wired end-to-end; new driver families don't need
+  Historian-specific plumbing in the IPC — they just implement `IHistoryProvider`.
+
+## Outstanding — not Phase 2 blockers
+
+- **AB CIP whole-UDT read optimization** (task #194) — niche performance win for large UDT
+  reads; current per-member fan-out works correctly.
+- **AB CIP `IAlarmSource` via tag-projected ALMA/ALMD** (task #177) — AB CIP driver doesn't
+  currently expose alarms; feature-flagged follow-up.
+- **IdentificationFolderBuilder wire-in** (task #195) — blocked on Equipment node walker.
+- **UnsTab Playwright E2E** (task #199) — infra setup PR.
+
+None of these are Phase 2 scope; all are tracked independently.

docs/v2/implementation/exit-gate-phase-2-final.md

@@ -1,5 +1,11 @@
 # Phase 2 Final Exit Gate (2026-04-18)
 
+> **⚠️ Superseded by [`exit-gate-phase-2-closed.md`](exit-gate-phase-2-closed.md) (2026-04-20).**
+> This doc captures the snapshot at PR 2 merge — when the four `High` + `Medium` findings
+> in the adversarial review were still OPEN and Historian port + alarm subsystem were still
+> deferred. All of those closed subsequently (PR 4 + PR 12 + PR 13 + PR 14 + PR 61). Kept
+> as historical evidence; consult the close-out doc for current Phase 2 status.
+
 > Supersedes `phase-2-partial-exit-evidence.md` and `exit-gate-phase-2.md`. Captures the
 > as-built state at the close of Phase 2 work delivered across two PRs.
 

docs/v2/implementation/focas-isolation-plan.md

@@ -0,0 +1,173 @@
+# FOCAS Tier-C isolation — plan for task #220
+
+> **Status**: PRs A–E shipped. Architecture is in place; the only
+> remaining FOCAS work is the hardware-dependent production
+> integration of `Fwlib32.dll` into a real `IFocasBackend`
+> (`FwlibHostedBackend`), which needs an actual CNC on the bench
+> and is tracked as a follow-up on #220.
+>
+> **Pre-reqs shipped**: version matrix + pre-flight validation
+> (PR #168 — the cheap half of the hardware-free stability gap).
+
+## Why isolate
+
+`Fwlib32.dll` is a proprietary Fanuc library with no source, no
+symbols, and a documented habit of crashing the hosting process on
+network errors, malformed responses, and during handle recycling.
+Today the FOCAS driver runs in-process with the OPC UA server —
+a crash inside the Fanuc DLL takes every driver down with it,
+including ones that have nothing to do with FOCAS. Galaxy has the
+same class of problem and solved it with the Tier-C pattern (host
+service + proxy driver + named-pipe IPC); FOCAS should follow that
+playbook.
+
+## Topology (target)
+
+```
++-------------------------------------+         +--------------------------+
+|  OtOpcUa.Server (.NET 10 x64)       |         | OtOpcUaFocasHost         |
+|                                     |  pipe   | (.NET 4.8 x86 Windows    |
+|  ZB.MOM.WW.OtOpcUa.Driver.FOCAS     | <-----> |  service)                |
+|    - FocasProxyDriver (in-proc)     |         |                          |
+|    - supervisor / respawn / BackPr  |         |  Fwlib32.dll + session   |
+|                                     |         |  handles + STA thread    |
++-------------------------------------+         +--------------------------+
+```
+
+Why .NET 4.8 x86 for the host: `Fwlib32.dll` ships as 32-bit only.
+The Galaxy.Host is already .NET 4.8 x86 for the same reason
+(MXAccess COM bitness), so the NSSM wrapper pattern transfers
+directly.
+
+## Three new projects
+
+| Project | TFM | Role |
+| --- | --- | --- |
+| `ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared` | `netstandard2.0` | MessagePack DTOs — `FocasReadRequest`, `FocasReadResponse`, `FocasSubscribeRequest`, `FocasPmcBitWriteRequest`, etc. Same assembly referenced by .NET 10 + .NET 4.8 so the wire format stays identical. |
+| `ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Host` | `net48` x86 | Windows service. Owns the Fwlib32 session handles + STA thread + handle-recycling loop. Pipe server + per-call auth (same ACL + caller SID + shared secret pattern as Galaxy.Host). |
+| `ZB.MOM.WW.OtOpcUa.Driver.FOCAS` (existing) | `net10.0` | Collapses to a proxy that forwards each `IReadable` / `IWritable` / `ISubscribable` call over the pipe. `FocasCapabilityMatrix` + `FocasAddress` stay here — pre-flight runs before any IPC. |
+
+## Supervisor responsibilities (in the Proxy)
+
+Mirrors Galaxy.Proxy 1:1:
+
+1. Start the Host process on first `InitializeAsync` (NSSM-wrapped
+   service in production, direct spawn in dev) + heartbeat every
+   5s.
+2. If heartbeat misses 3× in a row, fan out `BadCommunicationError`
+   to every subscription and respawn with exponential backoff
+   (1s / 2s / 4s / max 30s).
+3. Crash-loop circuit breaker: 5 respawns in 60s → drop to
+   `BadDeviceFailure` steady state until operator resets.
+4. Post-mortem MMF: on Host exit, Host writes its last-N operations
+   + session state to an MMF the Proxy reads to log context.
+
+## IPC surface (approximate)
+
+Every `FocasDriver` method that today calls into Fwlib32 directly
+becomes an `ExecuteAsync` call with a typed request:
+
+| Today (in-process) | Tier-C (IPC) |
+| --- | --- |
+| `FocasTagReader.Read(tag)` | `client.Execute(new FocasReadRequest(session, address))` |
+| `FocasTagWriter.Write(tag, value)` | `client.Execute(new FocasWriteRequest(...))` |
+| `FocasPmcBitRmw.Write(tag, bit, value)` | `client.Execute(new FocasPmcBitWriteRequest(...))` — RMW happens in Host so the critical section stays on one process |
+| `FocasConnectivityProbe.ProbeAsync` | `client.Execute(new FocasProbeRequest())` |
+| `FocasSubscriber.Subscribe(tags)` | `client.Execute(new FocasSubscribeRequest(tags))` — Host owns the poll loop + streams changes back as `FocasDataChangedNotification` over the pipe |
+
+Subscription streaming is the non-obvious piece: the Host polls on
+its own timer + pushes change notifications so the Proxy doesn't
+round-trip per poll. Matches `Driver.Galaxy.Host` subscription
+forwarding.
+
+## PR sequence — shipped
+
+1. **PR A (#169) — shared contracts** ✅
+   `Driver.FOCAS.Shared` netstandard2.0 with MessagePack DTOs for every
+   IPC surface (Hello/Heartbeat/OpenSession/Read/Write/PmcBitWrite/
+   Subscribe/Probe/RuntimeStatus/Recycle/ErrorResponse) + FrameReader/
+   FrameWriter + 24 round-trip tests.
+2. **PR B (#170) — Host project skeleton** ✅
+   `Driver.FOCAS.Host` net48 x86 Windows Service entry point,
+   `PipeAcl` + `PipeServer` + `IFrameHandler` + `StubFrameHandler`.
+   ACL denies LocalSystem/Administrators; Hello verifies
+   shared-secret + protocol major. 3 handshake tests.
+3. **PR C (#171) — IPC path end-to-end** ✅
+   Proxy `Ipc/FocasIpcClient` + `Ipc/IpcFocasClient` (implements
+   IFocasClient via IPC). Host `Backend/IFocasBackend` +
+   `FakeFocasBackend` + `UnconfiguredFocasBackend` +
+   `Ipc/FwlibFrameHandler` replacing the stub. 13 new round-trip
+   tests via in-memory loopback.
+4. **PR D (#172) — Supervisor + respawn** ✅
+   `Supervisor/Backoff` (5s→15s→60s) + `CircuitBreaker` (3-in-5min →
+   1h→4h→manual) + `HeartbeatMonitor` + `IHostProcessLauncher` +
+   `FocasHostSupervisor`. 14 tests.
+5. **PR E — Ops glue** ✅ (this PR)
+   `ProcessHostLauncher` (real Process.Start + FocasIpcClient
+   connect), `Host/Stability/PostMortemMmf` (magic 'OFPC') +
+   Proxy `Supervisor/PostMortemReader`, `scripts/install/
+   Install-FocasHost.ps1` + `Uninstall-FocasHost.ps1` NSSM wrappers.
+   7 tests (4 MMF round-trip + 3 reader format compatibility).
+
+**Post-shipment totals: 189 FOCAS driver tests + 24 Shared tests + 13 Host tests = 226 FOCAS-family tests green.**
+
+What remains is hardware-dependent: wiring `Fwlib32.dll` P/Invoke
+into a real `FwlibHostedBackend` implementation of `IFocasBackend`
++ validating against a live CNC. The architecture is all the
+plumbing that work needs.
+
+## Testing without hardware
+
+Same constraint as today: no CNC, no simulator. The isolation work
+itself is verifiable without Fwlib32 actually being called:
+
+- **Pipe contract**: PR A's MessagePack round-trip tests cover every
+  DTO.
+- **Supervisor**: PR D uses a `FakeFocasHost` stub that can be told
+  to crash, hang, or miss heartbeats. The supervisor's respawn +
+  circuit-breaker behaviour is fully testable against the stub.
+- **IPC ACL + auth**: reuse the Galaxy.Host's existing test harness
+  pattern — negative tests attempt to connect as the wrong user and
+  assert rejection.
+- **Fwlib32 integration itself**: still untestable without hardware.
+  When a real CNC becomes available, the smoke tests already
+  scaffolded in `tests/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.IntegrationTests/`
+  run against it via `FOCAS_ENDPOINT`.
+
+## Decisions to confirm before starting
+
+- **Sharing transport code with Galaxy.Host** — should the pipe
+  server + ACL + shared-secret + MMF plumbing go into a common
+  `Core.Hosting.Tier-C` project both hosts reference? Probably yes;
+  deferred until PR B is drafted because the right abstraction only
+  becomes visible after two uses.
+- **Handle-recycling cadence** — Fwlib32 session handles leak
+  memory over weeks per the Fanuc-published defect list. Galaxy
+  recycles MXAccess handles on a 24h timer; FOCAS should mirror but
+  the trigger point (idle vs scheduled) needs operator input.
+- **Per-CNC Host process vs one Host serving N CNCs** — one-per-CNC
+  isolates blast radius but scales poorly past ~20 machines; shared
+  Host scales but one bad CNC can wedge the lot. Start with shared
+  Host + document the blast-radius trade; revisit if operators hit
+  it.
+
+## Non-goals
+
+- Simulator work. `open_focas` + other OSS FOCAS simulators are
+  untested + not maintained; not worth chasing vs. waiting for real
+  hardware.
+- Changing the public `FocasDriverOptions` shape beyond what
+  already shipped (the `Series` knob). Operator config continues to
+  look the same after the split — the Tier-C topology is invisible
+  from `appsettings.json`.
+- Historian / long-term history integration. FOCAS driver doesn't
+  implement `IHistoryProvider` + there's no plan to add it.
+
+## References
+
+- [`docs/v2/implementation/phase-2-galaxy-out-of-process.md`](phase-2-galaxy-out-of-process.md)
+  — the working Tier-C template this plan follows.
+- [`docs/drivers/FOCAS-Test-Fixture.md`](../../drivers/FOCAS-Test-Fixture.md)
+  — what's covered today + what stays blocked on hardware.
+- [`docs/v2/focas-version-matrix.md`](../focas-version-matrix.md) —
+  the capability matrix that pre-flights configs before IPC runs.

docs/v2/implementation/phase-7-scripting-and-alarming.md

@@ -0,0 +1,190 @@
+# Phase 7 — Scripting Runtime, Virtual Tags, and Scripted Alarms
+
+> **Status**: DRAFT — planning output from the 2026-04-20 interactive planning session. Pending review before work begins. Task #230 tracks the draft; #231–#238 are the stream placeholders.
+>
+> **Branch**: `v2/phase-7-scripting-and-alarming`
+> **Estimated duration**: 10–12 weeks (scope-comparable to Phase 6; largest single phase outside Phase 2 Galaxy split)
+> **Predecessor**: Phase 6.4 (Admin UI completion) — reuses the tab-plugin pattern + draft/publish flow
+> **Successor**: v2 release-readiness capstone
+
+## Phase Objective
+
+Add two **additive** runtime capabilities on top of the existing driver + Equipment address-space foundation:
+
+1. **Virtual (calculated) tags** — OPC UA variables whose values are computed by user-authored C# scripts against other tags (driver or virtual), evaluated on change and/or timer. They live in the existing Equipment/UNS tree alongside driver tags and behave identically to clients (browse, subscribe, historize).
+2. **Scripted alarms** — OPC UA Part 9 alarms whose condition is a user-authored C# predicate. Full state machine (EnabledState / ActiveState / AckedState / ConfirmedState / ShelvingState) with persistent operator-supplied state across restarts. Complement the existing Galaxy-native and AB CIP ALMD alarm sources — they do not replace them.
+
+Tie-in capability — **historian alarm sink**:
+
+3. **Aveva Historian as alarm system of record** — every qualifying alarm transition (activation, ack, confirm, clear, shelve, disable, comment) from **any `IAlarmSource`** (scripted + Galaxy + ALMD) routes through a new local SQLite store-and-forward queue to Galaxy.Host, which uses its already-loaded `aahClientManaged` DLLs to write to the Historian's alarm schema. Per-alarm `HistorizeToAveva` toggle gates which sources flow (default off for Galaxy-native since Galaxy itself already historizes them). Plant operators query one uniform historical alarm timeline.
+
+**Why it's additive, not a rewrite**: every `IAlarmSource` implementation shipped in Phase 6.x stays unchanged; scripted alarms register as an additional source in the existing fan-out. The Equipment node walker built in ADR-001 gains a "virtual" source kind alongside "driver" without removing anything. Operator-facing semantics for existing driver tags and alarms are unchanged.
+
+## Design Decisions (locked in the 2026-04-20 planning session)
+
+| # | Decision | Rationale |
+|---|---------|-----------|
+| 1 | Script language = **C# via Roslyn scripting** | Developer audience, strong typing, AST walkable for dependency inference, existing .NET 10 runtime in main server. |
+| 2 | Virtual tags live in the **Equipment tree** alongside driver tags (not a separate `/Virtual/...` namespace) | Operator mental model stays unified; calculated `LineRate` shows up under the Line1 folder next to the driver-sourced `SpeedSetpoint` it's derived from. |
+| 3 | Evaluation trigger = **change-driven + timer-driven**; operator chooses per-tag | Change-driven is cheap at steady state; timer is the escape hatch for polling derivations that don't have a discrete "input changed" signal. |
+| 4 | Script shape = **Shape A — one script per virtual tag/alarm**; `return` produces the value (or `bool` for alarm condition) | Minimal surface; no predicate/action split. Alarm side-effects (severity, message) configured out-of-band, not in the script. |
+| 5 | Alarm fidelity = **full OPC UA Part 9** | Uniform with Galaxy + ALMD on the wire; client-side tooling (HMIs, historians, event pipelines) gets one shape. |
+| 6 | Sandbox = **read-only context**; scripts can only read any tag + write to virtual tags | Strict Roslyn `ScriptOptions` allow-list. No HttpClient / File / Process / reflection. |
+| 7 | Dependency declaration = **AST inference**; operator doesn't maintain a separate dependency list | `CSharpSyntaxWalker` extracts `ctx.GetTag("path")` string-literal calls at compile time; dynamic paths rejected at publish. |
+| 8 | Config storage = **config DB with generation-sealed cache** (same as driver instances) | Virtual tags + alarms publish atomically in the same generation as the driver instance config they may depend on. |
+| 9 | Script return value shape (`ctx.GetTag`) = **`DataValue { Value, StatusCode, Timestamp }`** | Scripts branch on quality naturally without separate `ctx.GetQuality(...)` calls. |
+| 10 | Historize virtual tags = **per-tag checkbox** | Writes flow through the same history-write path as driver tags. Consumed by existing `IHistoryProvider`. |
+| 11 | Per-tag error isolation — a throwing script sets that tag's quality to `BadInternalError`; engine keeps running for every other tag | Mirrors Phase 6.1 Stream B's per-surface error handling. |
+| 12 | Dedicated Serilog sink = `scripts-*.log` rolling file; structured-property `ScriptName` for filtering | Keeps noisy script logs out of the main `opcua-*.log`. `ctx.Logger.Info/Warning/Error/Debug` bound in the script context. |
+| 13 | Alarm message = **template with substitution** (`"Reactor temp {Reactor/Temp} exceeded {Limit}"`) | Middle ground between static and separate message-script; engine resolves `{path}` tokens at event emission. |
+| 14 | Alarm state persistence — `ActiveState` recomputed from tag values on startup; `EnabledState / AckedState / ConfirmedState / ShelvingState` + audit trail persist to config DB | Operators don't re-ack after restart; ack history survives for compliance (GxP / 21 CFR Part 11). |
+| 15 | Historian sink scope = **all `IAlarmSource` implementations**, not just scripted; per-alarm `HistorizeToAveva` toggle | Plant gets one consolidated alarm timeline; Galaxy-native alarms default off to avoid duplication. |
+| 16 | Historian failure mode = **SQLite store-and-forward queue on the node**; config DB is source of truth, Historian is best-effort projection | Operators never blocked by Historian downtime; failed writes queue + retry when Historian recovers. |
+| 17 | Historian ingestion path = **IPC to Galaxy.Host**, which calls the already-loaded `aahClientManaged` DLLs | Reuses existing bitness / licensing / Tier-C isolation. No new 32-bit DLL load in the main server. |
+| 18 | Admin UI code editor = **Monaco** via the Admin project's asset pipeline | Industry default for C# editing in a browser; ~3 MB bundle acceptable given Admin is operator-facing only, not public. Revisitable if bundle size becomes a deployment constraint. |
+| 19 | Cascade evaluation order = **serial** for v1; parallel promoted to a Phase 7 follow-up | Deterministic, easier to reason about, simplifies cycle + ordering bugs in the rollout. Parallel becomes a tuning knob when real 1000+ virtual-tag deployments measure contention. |
+| 20 | Shelving UX = **OPC UA method calls only** (`OneShotShelve` / `TimedShelve` / `Unshelve` on the `AlarmConditionType` node); **no Admin UI shelve controls** | Plant HMIs + OPC UA clients already speak these methods by spec; reinventing the UI adds surface without operator value. Admin still renders current shelve state + audit trail read-only on the alarm detail page. |
+| 21 | Dead-lettered historian events retained for **30 days** in the SQLite queue; Admin `/alarms/historian` exposes a "Retry dead-lettered" button | Long enough for a Historian outage or licensing glitch to be resolved + operator to investigate; short enough that the SQLite file doesn't grow unbounded. Configurable via `AlarmHistorian:DeadLetterRetentionDays` for deployments with stricter compliance windows. |
+| 22 | Test harness synthetic inputs = **declared inputs only** (from the AST walker's extracted dependency set) | Enforces the dependency declaration — if a path can't be supplied to the harness, the AST walker didn't see it and the script can't reference it at runtime. Catches dependency-inference drift at test time, not publish time. |
+
+## Scope — What Changes
+
+| Concern | Change |
+|---------|--------|
+| **New project `OtOpcUa.Core.Scripting`** (.NET 10) | Roslyn-based script engine. Compiles user C# scripts with a sandboxed `ScriptOptions` allow-list (numeric / string / datetime / `ScriptContext` API only — no reflection / File / Process / HttpClient). `DependencyExtractor` uses `CSharpSyntaxWalker` to enumerate `ctx.GetTag("...")` literal-string calls; rejects non-literal paths at publish time. Per-script compile cache keyed by source hash. Per-evaluation timeout. Exception in script → tag goes `BadInternalError`; engine unaffected for other tags. `ctx.Logger` is a Serilog `ILogger` bound to the `scripts-*.log` rolling sink with structured property `ScriptName`. |
+| **New project `OtOpcUa.Core.VirtualTags`** (.NET 10) | `VirtualTagEngine` consumes the `DependencyExtractor` output, builds a topological dependency graph spanning driver tags + other virtual tags (cycle detection at publish time), schedules re-evaluation on change + on timer, propagates results through an `IVirtualTagSource` that implements `IReadable` + `ISubscribable` so `DriverNodeManager` routes reads / subscriptions uniformly. Per-tag `Historize` flag routes to the same history-write path driver tags use. |
+| **New project `OtOpcUa.Core.ScriptedAlarms`** (.NET 10) | `ScriptedAlarmEngine` materializes each configured alarm as an OPC UA `AlarmConditionType` (or `LimitAlarmType` / `OffNormalAlarmType`). On startup, re-evaluates every predicate against current tag values to rebuild `ActiveState` — no persistence needed for the active flag. Persistent state: `EnabledState`, `AckedState`, `ConfirmedState`, `ShelvingState`, branch stack, ack audit (user/time/comment). Template message substitution resolves `{TagPath}` tokens at event emission. Ack / Confirm / Shelve method nodes bound to the engine; transitions audit-logged via the existing `IAuditLogger` (Phase 6.2). Registers as an additional `IAlarmSource` — no change to the existing fan-out. |
+| **New project `OtOpcUa.Core.AlarmHistorian`** (.NET 10) | `IAlarmHistorianSink` abstraction + `SqliteStoreAndForwardSink` default implementation. Every qualifying `IAlarmSource` emission (per-alarm `HistorizeToAveva` toggle) persists to a local SQLite queue (`%ProgramData%\OtOpcUa\alarm-historian-queue.db`). Background drain worker reads unsent rows + forwards over IPC to Galaxy.Host. Failed writes keep the row pending with exponential backoff. Queue capacity bounded (default 1M events, oldest-dropped with a structured warning log). |
+| **`Driver.Galaxy.Shared`** — new IPC contracts | `HistorianAlarmEventRequest` (activation / ack / confirm / clear / shelve / disable / comment payloads matching the Aveva Historian alarm schema) + `HistorianAlarmEventResponse` (ack / retry-please / permanent-fail). `HistorianConnectivityStatusNotification` so the main server can surface "Historian disconnected" on the Admin `/hosts` page. |
+| **`Driver.Galaxy.Host`** — new frame handler for alarm writes | Reuses the already-loaded `aahClientManaged.dll` + `aahClientCommon.dll`. Maps the IPC request DTOs to the historian SDK's alarm-event API (exact method TBD during Stream D.2 — needs a live-historian smoke to confirm the right SDK entry point). Errors map to structured response codes so the main server's backoff logic can distinguish "transient" from "permanent". |
+| **Config DB schema** — new tables | `VirtualTag (Id, EquipmentPath, Name, DataType, IntervalMs?, ChangeTriggerEnabled, Historize, ScriptId)`; `Script (Id, SourceCode, CompiledHash, Language='CSharp')`; `ScriptedAlarm (Id, EquipmentPath, Name, AlarmType, Severity, MessageTemplate, HistorizeToAveva, PredicateScriptId)`; `ScriptedAlarmState (AlarmId, EnabledState, AckedState, ConfirmedState, ShelvingState, ShelvingExpiresUtc?, LastAckUser, LastAckComment, LastAckUtc, BranchStack_JSON)`. Every write goes through `sp_PublishGeneration` + `IAuditLogger`. |
+| **Address-space build** — Phase 6 `EquipmentNodeWalker` extension | Emits virtual-tag nodes alongside driver-sourced nodes under the same Equipment folder. `NodeScopeResolver` gains a `Virtual` source kind alongside `Driver`. `DriverNodeManager` dispatch routes reads / writes / subscriptions to the `VirtualTagEngine` when the source is virtual. |
+| **Admin UI** — new tabs | `/virtual-tags` and `/scripted-alarms` tabs under the existing draft/publish flow. Monaco-based C# code editor (syntax highlighting, IntelliSense against a hand-written type stub for `ScriptContext`). Dependency preview panel shows the inferred input list from the AST walker. Test-harness lets operator supply synthetic `DataValue` inputs + see script output + logger emissions without publishing. Per-alarm controls: `AlarmType`, `Severity`, `MessageTemplate`, `HistorizeToAveva`. New `/alarms/historian` diagnostics view: queue depth, drain rate, last-successful-write, per-alarm "last routed to historian" timestamp. |
+| **`DriverTypeRegistry`** — no change | Scripting is not a driver — it doesn't register as a `DriverType`. The engine hangs off the same `SealedBootstrap` as drivers but through a different composition root. |
+
+## Scope — What Does NOT Change
+
+| Item | Reason |
+|------|--------|
+| Existing `IAlarmSource` implementations (Galaxy, AB CIP ALMD) | Scripted alarms register as an *additional* source; existing sources pass through unchanged. Default `HistorizeToAveva=false` for Galaxy alarms avoids duplicating records the Galaxy historian wiring already captures. |
+| Driver capability surface (`IReadable` / `IWritable` / `ISubscribable` / etc.) | Virtual tags implement the same interfaces — drivers and virtual tags are interchangeable from the node manager's perspective. No new capability. |
+| Config DB publication flow (`sp_PublishGeneration` + sealed cache) | Virtual tag + alarm tables plug in as additional rows. Atomic publish semantics unchanged. |
+| Authorization trie (Phase 6.2) | Virtual-tag nodes inherit the Equipment scope's grants — same treatment as the Phase 6.4 Identification sub-folder. No new scope level. |
+| Tier-C isolation topology | Scripting engine runs in the main .NET 10 server process. Roslyn scripts are already sandboxed via `ScriptOptions`; no need for process isolation because they have no unmanaged reach. Galaxy.Host's existing Tier-C boundary already owns the historian SDK writes. |
+| Galaxy alarm ingestion path into the historian | Galaxy writes alarms directly via `aahClientManaged` today; Phase 7 Stream D gives it a *second* path (via the new sink) when a Galaxy alarm has `HistorizeToAveva=true`, but the direct path stays for the default case. |
+| OPC UA wire protocol / AddressSpace schema | Clients see new nodes under existing folders + new alarm conditions. No new namespaces, no new ObjectTypes beyond what Part 9 already defines. |
+
+## Entry Gate Checklist
+
+- [ ] All Phase 6.x exit gates cleared (#133, #142, #151, #158)
+- [ ] Equipment node walker wired into `DriverNodeManager` (task #212 — done)
+- [ ] `IAuditLogger` surface live (Phase 6.2 Stream A)
+- [ ] `sp_PublishGeneration` + sealed-cache flow verified on the existing driver-config tables
+- [ ] Dev Aveva Historian reachable from the dev box (for Stream D.2 smoke)
+- [ ] `v2` branch clean + baseline tests green
+- [ ] Blazor editor component library picked (Monaco confirmed vs alternatives — see decision to log)
+- [ ] Review this plan — decisions #1–#17 signed off, no open questions
+
+## Task Breakdown
+
+### Stream A — `Core.Scripting` (Roslyn engine + sandbox + AST inference + logger) — **2 weeks**
+
+1. **A.1** Project scaffold + NuGet `Microsoft.CodeAnalysis.CSharp.Scripting`. `ScriptOptions` allow-list (`typeof(object).Assembly`, `typeof(Enumerable).Assembly`, the Core.Scripting assembly itself — nothing else). Hand-written `ScriptContext` base class with `GetTag(string)` / `SetVirtualTag(string, object)` / `Logger` / `Now` / `Deadband(double, double, double)` helpers.
+2. **A.2** `DependencyExtractor : CSharpSyntaxWalker`. Visits every `InvocationExpressionSyntax` targeting `ctx.GetTag` / `ctx.SetVirtualTag`; accepts only a `LiteralExpressionSyntax` argument. Non-literal arguments (concat, variable, method call) → publish-time rejection with an actionable error pointing the operator at the exact span. Outputs `IReadOnlySet<string> Inputs` + `IReadOnlySet<string> Outputs`.
+3. **A.3** Compile cache. `(source_hash) → compiled Script<T>`. Recompile only when source changes. Warm on `SealedBootstrap`.
+4. **A.4** Per-evaluation timeout wrapper (default 250ms; configurable per tag). Timeout = tag quality `BadInternalError` + structured warning log. Keeps a single runaway script from starving the engine.
+5. **A.5** Serilog sink wiring. New `scripts-*.log` rolling file enricher; `ctx.Logger` returns an `ILogger` with `ForContext("ScriptName", ...)`. Main `opcua-*.log` gets a companion entry at WARN level if a script logs ERROR, so the operator sees it in the primary log.
+6. **A.6** Tests: AST extraction unit tests (30+ cases covering literal / concat / variable / null / method-returned paths); sandbox escape tests (attempt `typeof`, `Assembly.Load`, `File.OpenRead` — all must fail at compile); exception isolation (throwing script doesn't kill the engine); timeout behavior; logger structured-property binding.
+
+### Stream B — Virtual tag engine (dependency graph + change/timer schedulers + historize) — **1.5 weeks**
+
+1. **B.1** `VirtualTagEngine`. Ingests the set of compiled scripts + their inputs/outputs; builds a directed dependency graph (driver tag ID → virtual tag ID → virtual tag ID). Cycle detection at publish-time via Tarjan; publish rejects with a clear error message listing the cycle.
+2. **B.2** `ChangeTriggerDispatcher`. Subscribes to every referenced driver tag via the existing `ISubscribable` fan-out. On a `DataValueSnapshot` delta (value / status / timestamp — any of the three), enqueues affected virtual tags for re-evaluation in topological order.
+3. **B.3** `TimerTriggerDispatcher`. Per-tag `IntervalMs` scheduled via a shared timer-wheel. Independent of change triggers — a tag can have both, either, or neither.
+4. **B.4** `EvaluationPipeline`. Serial evaluation per cascade (parallel promoted to a follow-up — avoids cross-tag ordering bugs on first rollout). Exception handling per A.4; propagates results via `IVirtualTagSource`.
+5. **B.5** `IVirtualTagSource` implementation. Implements `IReadable` + `ISubscribable`. Reads return the most recent evaluated value; subscriptions receive `OnDataChange` events on each re-evaluation.
+6. **B.6** History routing. Per-tag `Historize` flag emits the value + timestamp to the existing history-write path used by drivers.
+7. **B.7** Tests: dependency graph (happy + cycle); change cascade through two levels of virtual tags; timer-only tag ignores input changes; change + timer both configured; error propagation; historize on/off.
+
+### Stream C — Scripted alarm engine + Part 9 state machine + template messages — **2.5 weeks**
+
+1. **C.1** Alarm config model + `ScriptedAlarmEngine` skeleton. Alarms materialize as `AlarmConditionType` (or subtype — `LimitAlarm`, `OffNormal`) nodes under their configured Equipment path. Severity loaded from config.
+2. **C.2** `Part9StateMachine`. Tracks `EnabledState`, `ActiveState`, `AckedState`, `ConfirmedState`, `ShelvingState` per condition ID. Shelving has `OneShotShelving` + `TimedShelving` variants + an `UnshelveTime` timer.
+3. **C.3** Predicate evaluation. On any input change (same trigger mechanism as Stream B), run the `bool` predicate. On `false → true` transition, activate (increment branch stack if prior Ack-but-not-Confirmed state exists). On `true → false`, clear (but keep condition visible if retain flag set).
+4. **C.4** Startup recovery. For every configured alarm, run the predicate against current tag values to rebuild `ActiveState` *only*. Load `EnabledState` / `AckedState` / `ConfirmedState` / `ShelvingState` + audit from the `ScriptedAlarmState` table. No re-acknowledgment required for conditions that were acked before restart.
+5. **C.5** Template substitution. Engine resolves `{TagPath}` tokens in `MessageTemplate` at event emission time using current tag values. Unresolvable tokens (bad path, missing tag) emit a structured error log + substitute `{?}` so the event still fires.
+6. **C.6** OPC UA method binding. `Acknowledge`, `Confirm`, `AddComment`, `OneShotShelve`, `TimedShelve`, `Unshelve` methods on each condition node route to the engine + persist via audit-logged writes to `ScriptedAlarmState`.
+7. **C.7** `IAlarmSource` implementation. Emits Part 9-shaped events through the existing fan-out the `AlarmTracker` composes.
+8. **C.8** Tests: every transition (all 32 state combinations the state machine can produce); startup recovery (seed table with varied ack/confirm/shelve state, restart, verify correct recovery); template substitution (literal path, nested path, bad path); shelving timer expiry; OPC UA method calls via Client.CLI.
+
+### Stream D — Historian alarm sink (SQLite store-and-forward + Galaxy.Host IPC) — **2 weeks**
+
+1. **D.1** `Core.AlarmHistorian` project. `IAlarmHistorianSink` interface; `SqliteStoreAndForwardSink` default implementation using Microsoft.Data.Sqlite. Schema: `Queue (RowId, AlarmId, EventType, PayloadJson, EnqueuedUtc, LastAttemptUtc?, AttemptCount, DeadLettered)`. Queue capacity bounded; oldest-dropped on overflow with structured warning.
+2. **D.2** **Live-historian smoke** against the dev box's Aveva Historian. Identify the exact `aahClientManaged` alarm-write API entry point (likely `IAlarmsDatabase.WriteAlarmEvent` or equivalent — verify with a throwaway Galaxy.Host test hook). Document in a short `docs/v2/historian-alarm-api.md` artifact.
+3. **D.3** `Driver.Galaxy.Shared` contract additions. `HistorianAlarmEventRequest` / `HistorianAlarmEventResponse` / `HistorianConnectivityStatusNotification`. Round-trip tests in `Driver.Galaxy.Shared.Tests`.
+4. **D.4** `Driver.Galaxy.Host` handler. Translates incoming `HistorianAlarmEventRequest` to the SDK call identified in D.2. Returns structured response (Ack / RetryPlease / PermanentFail). Connectivity notifications sent proactively when the SDK's session drops.
+5. **D.5** Drain worker in the main server. Polls the SQLite queue; batches up to 100 events per IPC round-trip; exponential backoff on `RetryPlease` (1s → 2s → 5s → 15s → 60s cap); `PermanentFail` dead-letters the row + structured error log.
+6. **D.6** Per-alarm toggle wired through: `HistorizeToAveva` column on both `ScriptedAlarm` + a new `AlarmHistorizationPolicy` projection the Galaxy / ALMD alarm sources consult (default `false` for Galaxy, `true` for scripted, operator-adjustable per-alarm).
+7. **D.7** `/alarms/historian` diagnostics view in Admin. Queue depth, drain rate, last-successful-write, last-error, per-alarm last-routed timestamp.
+8. **D.8** Tests: SQLite queue round-trip; drain worker with fake IPC (success / retry / perm-fail); overflow eviction; Galaxy.Host handler against a stub historian API; end-to-end with the live historian on the dev box (non-CI — operator-invoked).
+
+### Stream E — Config DB schema + generation-sealed cache extensions — **1 week**
+
+1. **E.1** EF migration for new tables. Foreign keys from `VirtualTag.ScriptId` / `ScriptedAlarm.PredicateScriptId` to `Script.Id`.
+2. **E.2** `sp_PublishGeneration` extension. Sealed-cache snapshot includes virtual tags + scripted alarms + their scripts. Atomic publish guarantees the address-space build sees a consistent view.
+3. **E.3** CRUD services. `VirtualTagService`, `ScriptedAlarmService`, `ScriptService`. Each audit-logged; Ack / Confirm / Shelve persist through `ScriptedAlarmStateService` with full audit trail (who / when / comment / previous state).
+4. **E.4** Tests: migration up / down; publish atomicity (concurrent writes to different alarm rows don't leak into an in-flight publish); audit trail on every mutation.
+
+### Stream F — Admin UI scripting tab — **2 weeks**
+
+1. **F.1** Monaco editor Razor component. CSS-isolated; loads Monaco via NPM + the Admin project's existing asset pipeline. C# syntax highlighting (Monaco ships it). IntelliSense via a hand-written `ScriptContext.cs` type stub delivered with the editor (not the compiled Core.Scripting DLL — keeps the browser bundle small).
+2. **F.2** `/virtual-tags` tab. List view (Equipment path / Name / DataType / inputs-summary / Historize / actions). Edit pane splits: Monaco editor left, dependency preview panel right (live-updates from a debounced `/api/scripting/analyze` endpoint that runs the `DependencyExtractor`). Publish button gated by Phase 6.2 `WriteConfigure` permission.
+3. **F.3** `/scripted-alarms` tab. Same editor shape + extra controls: AlarmType dropdown, Severity slider, MessageTemplate textbox with live-preview showing `{path}` token resolution against latest tag values, `HistorizeToAveva` checkbox. **Alarm detail page displays current `ShelvingState` + `LastAckUser / LastAckUtc / LastAckComment` read-only** — no shelve/unshelve / ack / confirm buttons per decision #20. Operators drive state transitions via OPC UA method calls from plant HMIs or the Client.CLI.
+4. **F.4** Test harness. Modal that lets the operator supply synthetic `DataValue` inputs for the dependency set + see script output + logger emissions (rendered in a virtual terminal). Enables testing without publishing.
+5. **F.5** Script log viewer. SignalR stream of the `scripts-*.log` sink filtered by the script under edit (using the structured `ScriptName` property). Tail-last-200 + "load more".
+6. **F.6** `/alarms/historian` diagnostics view per Stream D.7.
+7. **F.7** Playwright smoke. Author a calc tag, publish, verify it appears in the equipment tree via a probe OPC UA read. Author an alarm, verify it appears in `AlarmsAndConditions`.
+
+### Stream G — Address-space integration — **1 week**
+
+1. **G.1** `EquipmentNodeWalker` extension. Current walker iterates driver tags per equipment; extend to also iterate virtual tags + alarms. `NodeScopeResolver` returns `NodeSource.Virtual` for virtual nodes and `NodeSource.Driver` for existing.
+2. **G.2** `DriverNodeManager` dispatch. Read / Write / Subscribe operations check the resolved source and route to `VirtualTagEngine` or the driver as appropriate. Writes to virtual tags allowed only from scripts (per decision #6) — OPC UA client writes to a virtual node return `BadUserAccessDenied`.
+3. **G.3** `AlarmTracker` composition. The `ScriptedAlarmEngine` registers as an additional `IAlarmSource` — no new composition code, the existing fan-out already accepts multiple sources.
+4. **G.4** Tests: mixed equipment folder (driver tag + virtual tag + driver-native alarm + scripted alarm) browsable via Client.CLI; read / subscribe round-trip for the virtual tag; scripted alarm transitions visible in the alarm event stream.
+
+### Stream H — Exit gate — **1 week**
+
+1. **H.1** Compliance script real-checks: schema migrations applied; new tables populated from a draft→publish cycle; sealed-generation snapshot includes virtual tags + alarms; SQLite alarm queue initialized; `scripts-*.log` sink emitting; `AlarmConditionType` nodes materialize in the address space; per-alarm `HistorizeToAveva` toggle enforced end-to-end.
+2. **H.2** Full-solution `dotnet test` baseline. Target: Phase 6 baseline + ~300 new tests across Streams A–G.
+3. **H.3** `docs/v2/plan.md` Migration Strategy §6 update — add Phase 7.
+4. **H.4** Phase-status memory update.
+5. **H.5** Merge `v2/phase-7-scripting-and-alarming` → `v2`.
+
+## Compliance Checks (run at exit gate)
+
+- [ ] **Sandbox escape**: attempts to reference `System.IO.File`, `System.Net.Http.HttpClient`, `System.Diagnostics.Process`, or `typeof(X).Assembly.Load` fail at script compile with an actionable error.
+- [ ] **Dependency inference**: `ctx.GetTag(myStringVar)` (non-literal path) is rejected at publish with a span-pointed error; `ctx.GetTag("Line1/Speed")` is accepted + appears in the inferred input set.
+- [ ] **Change cascade**: tag A → virtual tag B → virtual tag C. When A changes, B recomputes, then C recomputes. Single change event triggers the full cascade in topological order within one evaluation pass.
+- [ ] **Cycle rejection**: publish a config where virtual tag B depends on A and A depends on B. Publish fails pre-commit with a clear cycle message.
+- [ ] **Startup recovery**: seed `ScriptedAlarmState` with one acked+confirmed alarm + one shelved alarm + one clean alarm, restart, verify operator does NOT see ack prompts for the first two, shelving remains in effect, clean alarm is clear.
+- [ ] **Ack audit**: acknowledge an alarm; `IAuditLogger` captures user / timestamp / comment / prior state; row persists through restart.
+- [ ] **Historian queue durability**: take Galaxy.Host offline, fire 10 alarm transitions, bring Galaxy.Host back; queue drains all 10 in order.
+- [ ] **Per-alarm historian toggle**: Galaxy-native alarm with `HistorizeToAveva=false` does NOT enqueue; scripted alarm with `HistorizeToAveva=true` DOES enqueue.
+- [ ] **Script timeout**: infinite-loop script times out at 250ms; tag quality `BadInternalError`; other tags unaffected.
+- [ ] **Log isolation**: `ctx.Logger.Error("test")` lands in `scripts-*.log` with structured property `ScriptName=<name>`; main `opcua-*.log` gets a WARN companion entry.
+- [ ] **ACL binding**: virtual tag under an Equipment scope inherits the Equipment's grants. User without the Equipment grant reads the virtual tag and gets `BadUserAccessDenied`.
+
+## Decisions Resolved in Plan Review
+
+Every open question from the initial draft was resolved in the 2026-04-20 plan review — see decisions #18–#22 in the decisions table above. No pending questions block Stream A.
+
+## References
+
+- [`docs/v2/plan.md`](../plan.md) §6 Migration Strategy — add Phase 7 as the final additive phase before v2 release readiness.
+- [`docs/v2/implementation/overview.md`](overview.md) — phase gate conventions.
+- [`docs/v2/implementation/phase-6-2-authorization-runtime.md`](phase-6-2-authorization-runtime.md) — `IAuditLogger` surface reused for Ack/Confirm/Shelve + script edits.
+- [`docs/v2/implementation/phase-6-4-admin-ui-completion.md`](phase-6-4-admin-ui-completion.md) — draft/publish flow, diff viewer, tab-plugin pattern reused.
+- [`docs/v2/implementation/phase-2-galaxy-out-of-process.md`](phase-2-galaxy-out-of-process.md) — Galaxy.Host IPC shape + shared-contract conventions reused for Stream D.
+- [`docs/v2/driver-specs.md`](../driver-specs.md) §Alarm semantics — Part 9 fidelity requirements.
+- [`docs/v2/driver-stability.md`](../driver-stability.md) — per-surface error handling, crash-loop breaker patterns Stream A.4 mirrors.
+- [`docs/v2/config-db-schema.md`](../config-db-schema.md) — add a Phase 7 §§ for `VirtualTag`, `Script`, `ScriptedAlarm`, `ScriptedAlarmState`.

docs/v2/modbus-test-plan.md

@@ -13,9 +13,9 @@ confirmed DL205 quirk lands in a follow-up PR as a named test in that project.
 
 ## Harness
 
-**Chosen simulator: pymodbus 3.13.0** (`pip install 'pymodbus[simulator]==3.13.0'`).
-Replaced ModbusPal in PR 43 — see `tests/.../Pymodbus/README.md` for the
-trade-off rationale. Headline reasons:
+**Chosen simulator: pymodbus 3.13.0** packaged as a pinned Docker image
+under `tests/.../Modbus.IntegrationTests/Docker/`. See that folder's
+`README.md` for image-build notes + compose profiles. Headline reasons:
 
 - **Headless** pure-Python CLI; no Java GUI, runs cleanly on a CI runner.
 - **Maintained** — current stable 3.13.0; ModbusPal 1.6b is abandoned.
@@ -26,17 +26,18 @@ trade-off rationale. Headline reasons:
 - **Per-register raw uint16 seeding** — encoding the DL205 string-byte-order
   / BCD / CDAB-float quirks stays explicit (the quirk math lives in the
   `_quirk` JSON-comment fields next to each register).
-- Pip-installable on Windows; sidesteps the privileged-port admin
-  requirement by defaulting to TCP **5020** instead of 502.
+- **Dockerized** — pinned image means the CI simulator surface is
+  reproducible + no `pip install` step on the dev box.
+- Defaults to TCP **5020** (matches the compose port-map + the fixture
+  default endpoint; sidesteps the Windows Firewall prompt on 502).
 
 **Setup pattern**:
-1. `pip install "pymodbus[simulator]==3.13.0"`.
-2. Start the simulator with one of the in-repo profiles:
-   `tests\.../Pymodbus\serve.ps1 -Profile standard` (or `-Profile dl205`).
-3. `dotnet test tests\ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests` —
+1. `docker compose -f tests\...\Modbus.IntegrationTests\Docker\docker-compose.yml --profile <standard|dl205|mitsubishi|s7_1500> up -d`.
+2. `dotnet test tests\ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests` —
    tests auto-skip when the endpoint is unreachable. Default endpoint is
    `localhost:5020`; override via `MODBUS_SIM_ENDPOINT` for a real PLC on its
    native port 502.
+3. `docker compose -f ... --profile <…> down` when finished.
 
 ## Per-device quirk catalog
 
@@ -113,9 +114,11 @@ vendors get promoted into driver defaults or opt-in options:
 - **PR 42 — ModbusPal `.xmpp` profiles** — **SUPERSEDED by PR 43**. Replaced
   with pymodbus JSON because ModbusPal 1.6b is abandoned, GUI-only, and only
   exposes 2 of the 4 standard tables.
-- **PR 43 — pymodbus JSON profiles** — **DONE**. `Pymodbus/standard.json` +
-  `Pymodbus/dl205.json` + `Pymodbus/serve.ps1` runner. Both bind TCP 5020.
+- **PR 43 — pymodbus JSON profiles** — **DONE**. Dockerized under
+  `Docker/profiles/` (standard.json, dl205.json, mitsubishi.json,
+  s7_1500.json); compose file launches each via a named profile.
+  All bind TCP 5020.
 - **PR 44+**: one PR per confirmed DL205 quirk, landing the named test + any
   driver-side adjustment (string byte order, BCD decoder, V-memory address
   helper, FC16 cap-per-device-family) needed to pass it. Each quirk's value
-  is already pre-encoded in `Pymodbus/dl205.json`.
+  is already pre-encoded in `Docker/profiles/dl205.json`.

docs/v2/plan.md

@@ -736,7 +736,7 @@ Each step leaves the system runnable. The generic extraction is effectively free
 6. **Wire `Server`** — bootstrap from Configuration using an instance-bound credential (cert/gMSA/SQL login), fail fast if the credential is rejected, register drivers, start Core.
 7. **Scaffold `Admin`** — Blazor Server app with: instance + credential management, draft/publish/rollback generation workflow (diff viewer, "publish to fleet", per-instance override), and core CRUD for drivers/devices/tags. Driver-specific config screens deferred to later phases.
 
-**Phase 2 — Galaxy driver (prove the refactor)**
+**Phase 2 — Galaxy driver (prove the refactor) — ✅ CLOSED 2026-04-20** (see [`implementation/exit-gate-phase-2-closed.md`](implementation/exit-gate-phase-2-closed.md))
 8. **Build `Galaxy.Shared`** — .NET Standard 2.0 IPC message contracts
 9. **Build `Galaxy.Host`** — .NET 4.8 x86 process hosting MxAccessBridge, GalaxyRepository, alarms, HDA with IPC server
 10. **Build `Galaxy.Proxy`** — .NET 10 in-process proxy implementing IDriver interfaces, forwarding over IPC

docs/v2/test-data-sources.md

@@ -191,40 +191,30 @@ Modbus has no native String, DateTime, or Int64 — those rows are skipped on th
 
 ### CI fixture (task #180)
 
-The integration harness at `tests/ZB.MOM.WW.OtOpcUa.Driver.AbCip.IntegrationTests/` exposes two test-time contracts:
+The integration harness at `tests/ZB.MOM.WW.OtOpcUa.Driver.AbCip.IntegrationTests/` is Docker-only — `ab_server` is a source-only tool under libplctag's `src/tools/ab_server/`, and the fixture's multi-stage `Docker/Dockerfile` is the only supported reproducible build path.
 
-- **`AbServerFixture(AbServerProfile)`** — starts the simulator with the CLI args composed from the profile's `--plc` family + seed-tag set. One fixture instance per family, one simulator process per test case (smoke tier). For larger suites that can share a simulator across several reads/writes, use a `IClassFixture<AbServerFixture>` wrapper per family.
-- **`KnownProfiles.{ControlLogix, CompactLogix, Micro800, GuardLogix}`** — the four per-family profiles. Drives the simulator's `--plc` mode + the preseed `--tag name:type[:size]` set. Micro800 + GuardLogix fall back to `controllogix` under the hood because ab_server has no dedicated mode for them — the driver-side family profile still enforces the narrower connection shape / safety classification separately.
+- **`AbServerFixture(AbServerProfile)`** — thin TCP probe against `127.0.0.1:44818` (or `AB_SERVER_ENDPOINT` override). Does not spawn the simulator; the operator brings up the compose service for whichever family the test class targets (`controllogix` / `compactlogix` / `micro800` / `guardlogix`).
+- **`KnownProfiles.{ControlLogix, CompactLogix, Micro800, GuardLogix}`** — thin `(Family, ComposeProfile, Notes)` records. The compose file (`Docker/docker-compose.yml`) is the canonical source of truth for which tags each family seeds + which `--plc` mode the simulator boots in. `Micro800` uses the dedicated `--plc=Micro800` mode; `GuardLogix` uses `ControlLogix` emulation because ab_server has no safety subsystem (the `_S`-suffixed seed tag triggers driver-side ViewOnly classification only).
 
-**Pinned version** (recorded in `ci/ab-server.lock.json` so drift is one-file visible):
-
-- `libplctag` **v2.6.16** (published 2026-03-29) — `ab_server.exe` ships inside the `_tools.zip` asset alongside `plctag.dll` + two `list_tags_*` helpers.
-- Windows x64: `libplctag_2.6.16_windows_x64_tools.zip` — SHA256 `9b78a3dee73d9cd28ca348c090f453dbe3ad9d07ad6bf42865a9dc3a79bc2232`
-- Windows x86: `libplctag_2.6.16_windows_x86_tools.zip` — SHA256 `fdfefd58b266c5da9a1ded1a430985e609289c9e67be2544da7513b668761edf`
-- Windows ARM64: `libplctag_2.6.16_windows_arm64_tools.zip` — SHA256 `d747728e4c4958bb63b4ac23e1c820c4452e4778dfd7d58f8a0aecd5402d4944`
+**Pinned version**: the `Docker/Dockerfile` clones libplctag at a pinned tag (currently the `release` branch) via its `LIBPLCTAG_TAG` build-arg and compiles `ab_server` from source. Bump deliberately alongside a driver-side change that needs the newer simulator.
 
 **CI step:**
 
 ```yaml
 # GitHub Actions step placed before `dotnet test`:
-- name: Fetch ab_server (libplctag v2.6.16)
+- name: Start ab_server Docker container
   shell: pwsh
   run: |
-    $pin = Get-Content ci/ab-server.lock.json | ConvertFrom-Json
-    $asset = $pin.assets.'windows-x64'       # swap to windows-x86 / windows-arm64 on non-x64 runners
-    $url = "https://github.com/libplctag/libplctag/releases/download/$($pin.tag)/$($asset.file)"
-    $zip = Join-Path $env:RUNNER_TEMP 'libplctag-tools.zip'
-    Invoke-WebRequest $url -OutFile $zip
-    $actual = (Get-FileHash -Algorithm SHA256 $zip).Hash.ToLower()
-    if ($actual -ne $asset.sha256) { throw "libplctag tools SHA256 mismatch: expected $($asset.sha256), got $actual" }
-    $dest = Join-Path $env:RUNNER_TEMP 'libplctag-tools'
-    Expand-Archive $zip -DestinationPath $dest
-    Add-Content $env:GITHUB_PATH $dest
+    docker compose -f tests/ZB.MOM.WW.OtOpcUa.Driver.AbCip.IntegrationTests/Docker/docker-compose.yml `
+      --profile controllogix up -d --build
+    # Wait for :44818 to accept connections (compose healthcheck-equivalent)
+    for ($i = 0; $i -lt 30; $i++) {
+      if ((Test-NetConnection -ComputerName localhost -Port 44818 -WarningAction SilentlyContinue).TcpTestSucceeded) { break }
+      Start-Sleep -Seconds 1
+    }
 ```
 
-The fixture's `LocateBinary()` picks the binary up off PATH so the C# harness doesn't own the download — CI YAML is the right place for version pinning + hash verification. Developer workstations install the binary once from source (`cmake + make ab_server` under a libplctag clone) and the same fixture works identically.
-
-Tests without ab_server on PATH are marked `Skip` via `AbServerFactAttribute` / `AbServerTheoryAttribute`, so fresh-clone runs without the simulator still pass all unit suites in this project.
+Tests skip via `AbServerFactAttribute` / `AbServerTheoryAttribute` when the probe fails, so fresh-clone runs without Docker still pass all unit suites in this project.
 
 ---
 

scripts/install/Install-FocasHost.ps1

@@ -0,0 +1,108 @@
+<#
+.SYNOPSIS
+    Registers the OtOpcUaFocasHost Windows service. Optional companion to
+    Install-Services.ps1 — only run this on nodes where FOCAS driver instances will run
+    with Tier-C process isolation enabled.
+
+.DESCRIPTION
+    FOCAS PR #220 / Tier-C isolation plan. Wraps OtOpcUa.Driver.FOCAS.Host.exe (net48 x86)
+    as a Windows service using NSSM, running under the same service account as the main
+    OtOpcUa service so the named-pipe ACL works. Passes the per-process shared secret via
+    environment variable at service-start time so it never hits disk.
+
+.PARAMETER InstallRoot
+    Where the FOCAS Host binaries live (typically
+    C:\Program Files\OtOpcUa\Driver.FOCAS.Host).
+
+.PARAMETER ServiceAccount
+    Service account SID or DOMAIN\name. Must match the main OtOpcUa server account so the
+    PipeAcl match succeeds.
+
+.PARAMETER FocasSharedSecret
+    Per-process secret passed via env var. Generated freshly per install if not supplied.
+
+.PARAMETER FocasBackend
+    Backend selector for the Host process. One of:
+      fwlib32      (default — real Fanuc Fwlib32.dll integration; requires licensed DLL on PATH)
+      fake         (in-memory; smoke-test mode)
+      unconfigured (safe default returning structured errors; use until hardware is wired)
+
+.PARAMETER FocasPipeName
+    Pipe name the Host listens on. Default: OtOpcUaFocas.
+
+.EXAMPLE
+    .\Install-FocasHost.ps1 -InstallRoot 'C:\Program Files\OtOpcUa\Driver.FOCAS.Host' `
+        -ServiceAccount 'OTOPCUA\svc-otopcua' -FocasBackend fwlib32
+#>
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory)] [string]$InstallRoot,
+    [Parameter(Mandatory)] [string]$ServiceAccount,
+    [string]$FocasSharedSecret,
+    [ValidateSet('fwlib32','fake','unconfigured')] [string]$FocasBackend = 'unconfigured',
+    [string]$FocasPipeName = 'OtOpcUaFocas',
+    [string]$ServiceName = 'OtOpcUaFocasHost',
+    [string]$NssmPath = 'C:\Program Files\nssm\nssm.exe'
+)
+
+$ErrorActionPreference = 'Stop'
+
+function Resolve-Sid {
+    param([string]$Account)
+    if ($Account -match '^S-\d-\d+') { return $Account }
+    try {
+        $nt = New-Object System.Security.Principal.NTAccount($Account)
+        return $nt.Translate([System.Security.Principal.SecurityIdentifier]).Value
+    } catch {
+        throw "Could not resolve '$Account' to a SID. Pass an explicit SID or check the account name."
+    }
+}
+
+if (-not (Test-Path $NssmPath)) {
+    throw "nssm.exe not found at '$NssmPath'. Install NSSM or pass -NssmPath."
+}
+
+$hostExe = Join-Path $InstallRoot 'OtOpcUa.Driver.FOCAS.Host.exe'
+if (-not (Test-Path $hostExe)) {
+    throw "FOCAS Host binary not found at '$hostExe'. Publish the Driver.FOCAS.Host project first."
+}
+
+if (-not $FocasSharedSecret) {
+    $FocasSharedSecret = [System.Guid]::NewGuid().ToString('N')
+    Write-Host "Generated FocasSharedSecret — store it alongside the OtOpcUa service config."
+}
+
+$allowedSid = Resolve-Sid $ServiceAccount
+
+# Idempotent install — remove + re-create if present.
+$existing = Get-Service -Name $ServiceName -ErrorAction SilentlyContinue
+if ($existing) {
+    Write-Host "Removing existing '$ServiceName' service..."
+    & $NssmPath stop $ServiceName confirm | Out-Null
+    & $NssmPath remove $ServiceName confirm | Out-Null
+}
+
+& $NssmPath install $ServiceName $hostExe | Out-Null
+& $NssmPath set $ServiceName DisplayName 'OT-OPC-UA FOCAS Host (Tier-C isolated Fwlib32)' | Out-Null
+& $NssmPath set $ServiceName Description 'Out-of-process Fwlib32.dll host for OtOpcUa FOCAS driver. Crash-isolated from the main OPC UA server.' | Out-Null
+& $NssmPath set $ServiceName ObjectName  $ServiceAccount | Out-Null
+& $NssmPath set $ServiceName Start SERVICE_AUTO_START | Out-Null
+& $NssmPath set $ServiceName AppStdout (Join-Path $env:ProgramData 'OtOpcUa\focas-host-stdout.log') | Out-Null
+& $NssmPath set $ServiceName AppStderr (Join-Path $env:ProgramData 'OtOpcUa\focas-host-stderr.log') | Out-Null
+& $NssmPath set $ServiceName AppRotateFiles 1 | Out-Null
+& $NssmPath set $ServiceName AppRotateBytes 10485760 | Out-Null
+
+& $NssmPath set $ServiceName AppEnvironmentExtra `
+    "OTOPCUA_FOCAS_PIPE=$FocasPipeName" `
+    "OTOPCUA_ALLOWED_SID=$allowedSid" `
+    "OTOPCUA_FOCAS_SECRET=$FocasSharedSecret" `
+    "OTOPCUA_FOCAS_BACKEND=$FocasBackend" | Out-Null
+
+& $NssmPath set $ServiceName DependOnService OtOpcUa | Out-Null
+
+Write-Host "Installed '$ServiceName' under '$ServiceAccount' (SID=$allowedSid)."
+Write-Host "Pipe: \\.\pipe\$FocasPipeName    Backend: $FocasBackend"
+Write-Host "Start the service with: Start-Service $ServiceName"
+Write-Host ""
+Write-Host "NOTE: the Fwlib32 backend requires the licensed Fwlib32.dll on PATH"
+Write-Host "alongside the Host exe. See docs/v2/focas-deployment.md."

scripts/install/Uninstall-FocasHost.ps1

@@ -0,0 +1,27 @@
+<#
+.SYNOPSIS
+    Removes the OtOpcUaFocasHost Windows service.
+
+.DESCRIPTION
+    Companion to Install-FocasHost.ps1. Stops + unregisters the service via NSSM.
+    Idempotent — succeeds silently if the service doesn't exist.
+
+.EXAMPLE
+    .\Uninstall-FocasHost.ps1
+#>
+[CmdletBinding()]
+param(
+    [string]$ServiceName = 'OtOpcUaFocasHost',
+    [string]$NssmPath = 'C:\Program Files\nssm\nssm.exe'
+)
+
+$ErrorActionPreference = 'Stop'
+
+$svc = Get-Service -Name $ServiceName -ErrorAction SilentlyContinue
+if (-not $svc) { Write-Host "Service '$ServiceName' not present — nothing to do."; return }
+
+if (-not (Test-Path $NssmPath)) { throw "nssm.exe not found at '$NssmPath'." }
+
+& $NssmPath stop   $ServiceName confirm | Out-Null
+& $NssmPath remove $ServiceName confirm | Out-Null
+Write-Host "Removed '$ServiceName'."

src/ZB.MOM.WW.OtOpcUa.Client.CLI/Program.cs

@@ -9,7 +9,7 @@ return await new CliApplicationBuilder()
         if (type.IsSubclassOf(typeof(CommandBase))) return Activator.CreateInstance(type, CommandBase.DefaultFactory)!;
         return Activator.CreateInstance(type)!;
     })
-    .SetExecutableName("lmxopcua-cli")
-    .SetDescription("LmxOpcUa CLI - command-line client for the LmxOpcUa OPC UA server")
+    .SetExecutableName("otopcua-cli")
+    .SetDescription("OtOpcUa CLI - command-line client for the OtOpcUa OPC UA server")
     .Build()
     .RunAsync(args);

src/ZB.MOM.WW.OtOpcUa.Client.Shared/Adapters/DefaultApplicationConfigurationFactory.cs

@@ -18,8 +18,8 @@ internal sealed class DefaultApplicationConfigurationFactory : IApplicationConfi
 
         var config = new ApplicationConfiguration
         {
-            ApplicationName = "LmxOpcUaClient",
-            ApplicationUri = "urn:localhost:LmxOpcUaClient",
+            ApplicationName = "OtOpcUaClient",
+            ApplicationUri = "urn:localhost:OtOpcUaClient",
             ApplicationType = ApplicationType.Client,
             SecurityConfiguration = new SecurityConfiguration
             {
@@ -60,7 +60,7 @@ internal sealed class DefaultApplicationConfigurationFactory : IApplicationConfi
         {
             var app = new ApplicationInstance
             {
-                ApplicationName = "LmxOpcUaClient",
+                ApplicationName = "OtOpcUaClient",
                 ApplicationType = ApplicationType.Client,
                 ApplicationConfiguration = config
             };

src/ZB.MOM.WW.OtOpcUa.Client.Shared/ClientStoragePaths.cs

@@ -0,0 +1,90 @@
+namespace ZB.MOM.WW.OtOpcUa.Client.Shared;
+
+/// <summary>
+///     Resolves the canonical under-LocalAppData folder for the shared OPC UA client's PKI
+///     store + persisted settings. Renamed from <c>LmxOpcUaClient</c> to <c>OtOpcUaClient</c>
+///     in task #208; a one-shot migration shim moves a pre-rename folder in place on first
+///     resolution so existing developer boxes keep their trusted server certs + saved
+///     connection settings on upgrade.
+/// </summary>
+/// <remarks>
+///     Thread-safe: the rename uses <see cref="Directory.Move"/> which is atomic on NTFS
+///     within the same volume. The lock guarantees the migration runs at most once per
+///     process even under concurrent first-touch from CLI + UI.
+/// </remarks>
+public static class ClientStoragePaths
+{
+    /// <summary>Canonical client folder name. Post-#208.</summary>
+    public const string CanonicalFolderName = "OtOpcUaClient";
+
+    /// <summary>Pre-#208 folder name. Used only by the migration shim.</summary>
+    public const string LegacyFolderName = "LmxOpcUaClient";
+
+    private static readonly Lock _migrationLock = new();
+    private static bool _migrationChecked;
+
+    /// <summary>
+    ///     Absolute path to the client's top-level folder under LocalApplicationData. Runs the
+    ///     one-shot legacy-folder migration before returning so callers that depend on this
+    ///     path (PKI store, settings file) find their existing state at the canonical name.
+    /// </summary>
+    public static string GetRoot()
+    {
+        var localAppData = Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData);
+        var canonical = Path.Combine(localAppData, CanonicalFolderName);
+        MigrateLegacyFolderIfNeeded(localAppData, canonical);
+        return canonical;
+    }
+
+    /// <summary>Subfolder for the application's PKI store — used by both CLI + UI.</summary>
+    public static string GetPkiPath() => Path.Combine(GetRoot(), "pki");
+
+    /// <summary>
+    ///     Expose the migration probe for tests + for callers that want to check whether the
+    ///     legacy folder still exists without forcing the rename. Returns true when a legacy
+    ///     folder existed + was moved to canonical, false when no migration was needed or
+    ///     canonical was already present.
+    /// </summary>
+    public static bool TryRunLegacyMigration()
+    {
+        var localAppData = Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData);
+        var canonical = Path.Combine(localAppData, CanonicalFolderName);
+        return MigrateLegacyFolderIfNeeded(localAppData, canonical);
+    }
+
+    private static bool MigrateLegacyFolderIfNeeded(string localAppData, string canonical)
+    {
+        // Fast-path out of the lock when the migration has already been attempted this process
+        // — saves the IO on every subsequent call, + the migration is idempotent within the
+        // same process anyway.
+        if (_migrationChecked) return false;
+
+        lock (_migrationLock)
+        {
+            if (_migrationChecked) return false;
+            _migrationChecked = true;
+
+            var legacy = Path.Combine(localAppData, LegacyFolderName);
+
+            // Only migrate when the legacy folder is present + canonical isn't. Either of the
+            // other three combinations (neither / only-canonical / both) means migration
+            // should NOT run: no-op fresh install, already-migrated, or manual state the
+            // developer has set up — don't clobber.
+            if (!Directory.Exists(legacy)) return false;
+            if (Directory.Exists(canonical)) return false;
+
+            try
+            {
+                Directory.Move(legacy, canonical);
+                return true;
+            }
+            catch (IOException)
+            {
+                // Concurrent another-process-moved-it or volume-boundary or permissions — leave
+                // the legacy folder alone; callers that need it can either re-run migration
+                // manually or point CertificateStorePath explicitly.
+                return false;
+            }
+        }
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Client.Shared/Models/ConnectionSettings.cs

@@ -41,11 +41,11 @@ public sealed class ConnectionSettings
     public bool AutoAcceptCertificates { get; set; } = true;
 
     /// <summary>
-    ///     Path to the certificate store. Defaults to a subdirectory under LocalApplicationData.
+    ///     Path to the certificate store. Defaults to a subdirectory under LocalApplicationData
+    ///     resolved via <see cref="ClientStoragePaths"/> so the one-shot legacy-folder migration
+    ///     runs before the path is returned.
     /// </summary>
-    public string CertificateStorePath { get; set; } = Path.Combine(
-        Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
-        "LmxOpcUaClient", "pki");
+    public string CertificateStorePath { get; set; } = ClientStoragePaths.GetPkiPath();
 
     /// <summary>
     ///     Validates the settings and throws if any required values are missing or invalid.

src/ZB.MOM.WW.OtOpcUa.Client.Shared/OpcUaClientService.cs

@@ -425,7 +425,7 @@ public sealed class OpcUaClientService : IOpcUaClientService
             : new UserIdentity();
 
         var sessionTimeoutMs = (uint)(settings.SessionTimeoutSeconds * 1000);
-        return await _sessionFactory.CreateSessionAsync(config, endpoint, "LmxOpcUaClient", sessionTimeoutMs, identity,
+        return await _sessionFactory.CreateSessionAsync(config, endpoint, "OtOpcUaClient", sessionTimeoutMs, identity,
             ct);
     }
 

src/ZB.MOM.WW.OtOpcUa.Client.UI/Services/JsonSettingsService.cs

@@ -1,4 +1,5 @@
 using System.Text.Json;
+using ZB.MOM.WW.OtOpcUa.Client.Shared;
 
 namespace ZB.MOM.WW.OtOpcUa.Client.UI.Services;
 
@@ -7,9 +8,9 @@ namespace ZB.MOM.WW.OtOpcUa.Client.UI.Services;
 /// </summary>
 public sealed class JsonSettingsService : ISettingsService
 {
-    private static readonly string SettingsDir = Path.Combine(
-        Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
-        "LmxOpcUaClient");
+    // ClientStoragePaths.GetRoot runs the one-shot legacy-folder migration so pre-#208
+    // developer boxes pick up their existing settings.json on first launch post-rename.
+    private static readonly string SettingsDir = ClientStoragePaths.GetRoot();
 
     private static readonly string SettingsPath = Path.Combine(SettingsDir, "settings.json");
 

src/ZB.MOM.WW.OtOpcUa.Client.UI/ViewModels/MainWindowViewModel.cs

@@ -21,9 +21,7 @@ public partial class MainWindowViewModel : ObservableObject
 
     [ObservableProperty] private bool _autoAcceptCertificates = true;
 
-    [ObservableProperty] private string _certificateStorePath = Path.Combine(
-        Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
-        "LmxOpcUaClient", "pki");
+    [ObservableProperty] private string _certificateStorePath = ClientStoragePaths.GetPkiPath();
 
     [ObservableProperty]
     [NotifyCanExecuteChangedFor(nameof(ConnectCommand))]

src/ZB.MOM.WW.OtOpcUa.Core.Scripting/CompiledScriptCache.cs

@@ -0,0 +1,83 @@
+using System.Collections.Concurrent;
+using System.Security.Cryptography;
+using System.Text;
+
+namespace ZB.MOM.WW.OtOpcUa.Core.Scripting;
+
+/// <summary>
+///     Source-hash-keyed compile cache for user scripts. Roslyn compilation is the most
+///     expensive step in the evaluator pipeline (5-20ms per script depending on size);
+///     re-compiling on every value-change event would starve the virtual-tag engine.
+///     The cache is generic on the <see cref="ScriptContext"/> subclass + result type so
+///     different engines (virtual-tag / alarm-predicate / future alarm-action) each get
+///     their own cache instance — there's no cross-type pollution.
+/// </summary>
+/// <remarks>
+///     <para>
+///         Concurrent-safe: <see cref="ConcurrentDictionary{TKey, TValue}"/> of
+///         <see cref="Lazy{T}"/> means a miss on two threads compiles exactly once.
+///         <see cref="LazyThreadSafetyMode.ExecutionAndPublication"/> guarantees other
+///         threads block on the in-flight compile rather than racing to duplicate work.
+///     </para>
+///     <para>
+///         Cache is keyed on SHA-256 of the UTF-8 bytes of the source — collision-free in
+///         practice. Whitespace changes therefore miss the cache on purpose; operators
+///         see re-compile time on their first evaluation after a format-only edit which
+///         is rare and benign.
+///     </para>
+///     <para>
+///         No capacity bound. Virtual-tag + alarm scripts are operator-authored and
+///         bounded by config DB (typically low thousands). If that changes in v3, add an
+///         LRU eviction policy — the API stays the same.
+///     </para>
+/// </remarks>
+public sealed class CompiledScriptCache<TContext, TResult>
+    where TContext : ScriptContext
+{
+    private readonly ConcurrentDictionary<string, Lazy<ScriptEvaluator<TContext, TResult>>> _cache = new();
+
+    /// <summary>
+    ///     Return the compiled evaluator for <paramref name="scriptSource"/>, compiling
+    ///     on first sight + reusing thereafter. If the source fails to compile, the
+    ///     original Roslyn / sandbox exception propagates; the cache entry is removed so
+    ///     the next call retries (useful during Admin UI authoring when the operator is
+    ///     still fixing syntax).
+    /// </summary>
+    public ScriptEvaluator<TContext, TResult> GetOrCompile(string scriptSource)
+    {
+        if (scriptSource is null) throw new ArgumentNullException(nameof(scriptSource));
+
+        var key = HashSource(scriptSource);
+        var lazy = _cache.GetOrAdd(key, _ => new Lazy<ScriptEvaluator<TContext, TResult>>(
+            () => ScriptEvaluator<TContext, TResult>.Compile(scriptSource),
+            LazyThreadSafetyMode.ExecutionAndPublication));
+
+        try
+        {
+            return lazy.Value;
+        }
+        catch
+        {
+            // Failed compile — evict so a retry with corrected source can succeed.
+            _cache.TryRemove(key, out _);
+            throw;
+        }
+    }
+
+    /// <summary>Current entry count. Exposed for Admin UI diagnostics / tests.</summary>
+    public int Count => _cache.Count;
+
+    /// <summary>Drop every cached compile. Used on config generation publish + tests.</summary>
+    public void Clear() => _cache.Clear();
+
+    /// <summary>True when the exact source has been compiled at least once + is still cached.</summary>
+    public bool Contains(string scriptSource)
+        => _cache.ContainsKey(HashSource(scriptSource));
+
+    private static string HashSource(string source)
+    {
+        var bytes = Encoding.UTF8.GetBytes(source);
+        var hash = SHA256.HashData(bytes);
+        return Convert.ToHexString(hash);
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Core.Scripting/DependencyExtractor.cs

@@ -0,0 +1,137 @@
+using Microsoft.CodeAnalysis;
+using Microsoft.CodeAnalysis.CSharp;
+using Microsoft.CodeAnalysis.CSharp.Syntax;
+using Microsoft.CodeAnalysis.Text;
+
+namespace ZB.MOM.WW.OtOpcUa.Core.Scripting;
+
+/// <summary>
+///     Parses a script's source text + extracts every <c>ctx.GetTag("literal")</c> and
+///     <c>ctx.SetVirtualTag("literal", ...)</c> call. Outputs the static dependency set
+///     the virtual-tag engine uses to build its change-trigger subscription graph (Phase
+///     7 plan decision #7 — AST inference, operator doesn't maintain a separate list).
+/// </summary>
+/// <remarks>
+///     <para>
+///         The tag-path argument MUST be a literal string expression. Variables,
+///         concatenation, interpolation, and method-returned strings are rejected because
+///         the extractor can't statically know what tag they'll resolve to at evaluation
+///         time — the dependency graph needs to know every possible input up front.
+///         Rejections carry the exact source span so the Admin UI can point at the offending
+///         token.
+///     </para>
+///     <para>
+///         Identifier matching is by spelling: the extractor looks for
+///         <c>ctx.GetTag(...)</c> / <c>ctx.SetVirtualTag(...)</c> literally. A deliberately
+///         misspelled method call (<c>ctx.GetTagz</c>) is not picked up but will also fail
+///         to compile against <see cref="ScriptContext"/>, so there's no way to smuggle a
+///         dependency past the extractor while still having a working script.
+///     </para>
+/// </remarks>
+public static class DependencyExtractor
+{
+    /// <summary>
+    ///     Parse <paramref name="scriptSource"/> + return the inferred read + write tag
+    ///     paths, or a list of rejection messages if non-literal paths were used.
+    /// </summary>
+    public static DependencyExtractionResult Extract(string scriptSource)
+    {
+        if (string.IsNullOrWhiteSpace(scriptSource))
+            return new DependencyExtractionResult(
+                Reads: new HashSet<string>(StringComparer.Ordinal),
+                Writes: new HashSet<string>(StringComparer.Ordinal),
+                Rejections: []);
+
+        var tree = CSharpSyntaxTree.ParseText(scriptSource, options:
+            new CSharpParseOptions(kind: SourceCodeKind.Script));
+        var root = tree.GetRoot();
+
+        var walker = new Walker();
+        walker.Visit(root);
+
+        return new DependencyExtractionResult(
+            Reads: walker.Reads,
+            Writes: walker.Writes,
+            Rejections: walker.Rejections);
+    }
+
+    private sealed class Walker : CSharpSyntaxWalker
+    {
+        private readonly HashSet<string> _reads = new(StringComparer.Ordinal);
+        private readonly HashSet<string> _writes = new(StringComparer.Ordinal);
+        private readonly List<DependencyRejection> _rejections = [];
+
+        public IReadOnlySet<string> Reads => _reads;
+        public IReadOnlySet<string> Writes => _writes;
+        public IReadOnlyList<DependencyRejection> Rejections => _rejections;
+
+        public override void VisitInvocationExpression(InvocationExpressionSyntax node)
+        {
+            // Only interested in member-access form: ctx.GetTag(...) / ctx.SetVirtualTag(...).
+            // Anything else (free functions, chained calls, static calls) is ignored — but
+            // still visit children in case a ctx.GetTag call is nested inside.
+            if (node.Expression is MemberAccessExpressionSyntax member)
+            {
+                var methodName = member.Name.Identifier.ValueText;
+                if (methodName is nameof(ScriptContext.GetTag) or nameof(ScriptContext.SetVirtualTag))
+                {
+                    HandleTagCall(node, methodName);
+                }
+            }
+            base.VisitInvocationExpression(node);
+        }
+
+        private void HandleTagCall(InvocationExpressionSyntax node, string methodName)
+        {
+            var args = node.ArgumentList.Arguments;
+            if (args.Count == 0)
+            {
+                _rejections.Add(new DependencyRejection(
+                    Span: node.Span,
+                    Message: $"Call to ctx.{methodName} has no arguments. " +
+                             "The tag path must be the first argument."));
+                return;
+            }
+
+            var pathArg = args[0].Expression;
+            if (pathArg is not LiteralExpressionSyntax literal
+                || !literal.Token.IsKind(SyntaxKind.StringLiteralToken))
+            {
+                _rejections.Add(new DependencyRejection(
+                    Span: pathArg.Span,
+                    Message: $"Tag path passed to ctx.{methodName} must be a string literal. " +
+                             $"Dynamic paths (variables, concatenation, interpolation, method " +
+                             $"calls) are rejected at publish so the dependency graph can be " +
+                             $"built statically. Got: {pathArg.Kind()} ({pathArg})"));
+                return;
+            }
+
+            var path = (string?)literal.Token.Value ?? string.Empty;
+            if (string.IsNullOrWhiteSpace(path))
+            {
+                _rejections.Add(new DependencyRejection(
+                    Span: literal.Span,
+                    Message: $"Tag path passed to ctx.{methodName} is empty or whitespace."));
+                return;
+            }
+
+            if (methodName == nameof(ScriptContext.GetTag))
+                _reads.Add(path);
+            else
+                _writes.Add(path);
+        }
+    }
+}
+
+/// <summary>Output of <see cref="DependencyExtractor.Extract"/>.</summary>
+public sealed record DependencyExtractionResult(
+    IReadOnlySet<string> Reads,
+    IReadOnlySet<string> Writes,
+    IReadOnlyList<DependencyRejection> Rejections)
+{
+    /// <summary>True when no rejections were recorded — safe to publish.</summary>
+    public bool IsValid => Rejections.Count == 0;
+}
+
+/// <summary>A single non-literal-path rejection with the exact source span for UI pointing.</summary>
+public sealed record DependencyRejection(TextSpan Span, string Message);

src/ZB.MOM.WW.OtOpcUa.Core.Scripting/ForbiddenTypeAnalyzer.cs

@@ -0,0 +1,152 @@
+using Microsoft.CodeAnalysis;
+using Microsoft.CodeAnalysis.CSharp;
+using Microsoft.CodeAnalysis.CSharp.Syntax;
+using Microsoft.CodeAnalysis.Text;
+
+namespace ZB.MOM.WW.OtOpcUa.Core.Scripting;
+
+/// <summary>
+///     Post-compile sandbox guard. <c>ScriptOptions</c> alone can't reliably
+///     constrain the type surface a script can reach because .NET 10's type-forwarding
+///     system resolves many BCL types through multiple assemblies — restricting the
+///     reference list doesn't stop <c>System.Net.Http.HttpClient</c> from being found if
+///     any transitive reference forwards to <c>System.Net.Http</c>. This analyzer walks
+///     the script's syntax tree after compile, uses the <see cref="SemanticModel"/> to
+///     resolve every type / member reference, and rejects any whose containing namespace
+///     matches a deny-list pattern.
+/// </summary>
+/// <remarks>
+///     <para>
+///         Deny-list is the authoritative Phase 7 plan decision #6 set:
+///         <c>System.IO</c>, <c>System.Net</c>, <c>System.Diagnostics.Process</c>,
+///         <c>System.Reflection</c>, <c>System.Threading.Thread</c>,
+///         <c>System.Runtime.InteropServices</c>. <c>System.Environment</c> (for process
+///         env-var read) is explicitly left allowed — it's read-only process state, doesn't
+///         persist outside, and the test file pins this compromise so tightening later is
+///         a deliberate plan decision.
+///     </para>
+///     <para>
+///         Deny-list prefix match. <c>System.Net</c> catches <c>System.Net.Http</c>,
+///         <c>System.Net.Sockets</c>, <c>System.Net.NetworkInformation</c>, etc. — every
+///         subnamespace. If a script needs something under a denied prefix, Phase 7's
+///         operator audience authors it through a helper the plan team adds as part of
+///         the <see cref="ScriptContext"/> surface, not by unlocking the namespace.
+///     </para>
+/// </remarks>
+public static class ForbiddenTypeAnalyzer
+{
+    /// <summary>
+    ///     Namespace prefixes scripts are NOT allowed to reference. Each string is
+    ///     matched as a prefix against the resolved symbol's namespace name (dot-
+    ///     delimited), so <c>System.IO</c> catches <c>System.IO.File</c>,
+    ///     <c>System.IO.Pipes</c>, and any future subnamespace without needing explicit
+    ///     enumeration.
+    /// </summary>
+    public static readonly IReadOnlyList<string> ForbiddenNamespacePrefixes =
+    [
+        "System.IO",
+        "System.Net",
+        "System.Diagnostics",       // catches Process, ProcessStartInfo, EventLog, Trace/Debug file sinks
+        "System.Reflection",
+        "System.Threading.Thread",  // raw Thread — Tasks stay allowed (different namespace)
+        "System.Runtime.InteropServices",
+        "Microsoft.Win32",          // registry
+    ];
+
+    /// <summary>
+    ///     Scan the <paramref name="compilation"/> for references to forbidden types.
+    ///     Returns empty list when the script is clean; non-empty list means the script
+    ///     must be rejected at publish with the rejections surfaced to the operator.
+    /// </summary>
+    public static IReadOnlyList<ForbiddenTypeRejection> Analyze(Compilation compilation)
+    {
+        if (compilation is null) throw new ArgumentNullException(nameof(compilation));
+
+        var rejections = new List<ForbiddenTypeRejection>();
+        foreach (var tree in compilation.SyntaxTrees)
+        {
+            var semantic = compilation.GetSemanticModel(tree);
+            var root = tree.GetRoot();
+            foreach (var node in root.DescendantNodes())
+            {
+                switch (node)
+                {
+                    case ObjectCreationExpressionSyntax obj:
+                        CheckSymbol(semantic.GetSymbolInfo(obj.Type).Symbol, obj.Type.Span, rejections);
+                        break;
+                    case InvocationExpressionSyntax inv when inv.Expression is MemberAccessExpressionSyntax memberAcc:
+                        CheckSymbol(semantic.GetSymbolInfo(memberAcc.Expression).Symbol, memberAcc.Expression.Span, rejections);
+                        CheckSymbol(semantic.GetSymbolInfo(inv).Symbol, inv.Span, rejections);
+                        break;
+                    case MemberAccessExpressionSyntax mem:
+                        // Catches static calls like System.IO.File.ReadAllText(...) — the
+                        // MemberAccess "System.IO.File" resolves to the File type symbol
+                        // whose containing namespace is System.IO, triggering a rejection.
+                        CheckSymbol(semantic.GetSymbolInfo(mem.Expression).Symbol, mem.Expression.Span, rejections);
+                        break;
+                    case IdentifierNameSyntax id when node.Parent is not MemberAccessExpressionSyntax:
+                        CheckSymbol(semantic.GetSymbolInfo(id).Symbol, id.Span, rejections);
+                        break;
+                }
+            }
+        }
+        return rejections;
+    }
+
+    private static void CheckSymbol(ISymbol? symbol, TextSpan span, List<ForbiddenTypeRejection> rejections)
+    {
+        if (symbol is null) return;
+
+        var typeSymbol = symbol switch
+        {
+            ITypeSymbol t => t,
+            IMethodSymbol m => m.ContainingType,
+            IPropertySymbol p => p.ContainingType,
+            IFieldSymbol f => f.ContainingType,
+            _ => null,
+        };
+        if (typeSymbol is null) return;
+
+        var ns = typeSymbol.ContainingNamespace?.ToDisplayString() ?? string.Empty;
+        foreach (var forbidden in ForbiddenNamespacePrefixes)
+        {
+            if (ns == forbidden || ns.StartsWith(forbidden + ".", StringComparison.Ordinal))
+            {
+                rejections.Add(new ForbiddenTypeRejection(
+                    Span: span,
+                    TypeName: typeSymbol.ToDisplayString(),
+                    Namespace: ns,
+                    Message: $"Type '{typeSymbol.ToDisplayString()}' is in the forbidden namespace '{ns}'. " +
+                             $"Scripts cannot reach {forbidden}* per Phase 7 sandbox rules."));
+                return;
+            }
+        }
+    }
+}
+
+/// <summary>A single forbidden-type reference in a user script.</summary>
+public sealed record ForbiddenTypeRejection(
+    TextSpan Span,
+    string TypeName,
+    string Namespace,
+    string Message);
+
+/// <summary>Thrown from <see cref="ScriptEvaluator{TContext, TResult}.Compile"/> when the
+/// post-compile forbidden-type analyzer finds references to denied namespaces.</summary>
+public sealed class ScriptSandboxViolationException : Exception
+{
+    public IReadOnlyList<ForbiddenTypeRejection> Rejections { get; }
+
+    public ScriptSandboxViolationException(IReadOnlyList<ForbiddenTypeRejection> rejections)
+        : base(BuildMessage(rejections))
+    {
+        Rejections = rejections;
+    }
+
+    private static string BuildMessage(IReadOnlyList<ForbiddenTypeRejection> rejections)
+    {
+        var lines = rejections.Select(r => $"  - {r.Message}");
+        return "Script references types outside the Phase 7 sandbox allow-list:\n"
+               + string.Join("\n", lines);
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Core.Scripting/ScriptContext.cs

@@ -0,0 +1,80 @@
+using Serilog;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+
+namespace ZB.MOM.WW.OtOpcUa.Core.Scripting;
+
+/// <summary>
+///     The API user scripts see as the global <c>ctx</c>. Abstract — concrete subclasses
+///     (e.g. <c>VirtualTagScriptContext</c>, <c>AlarmScriptContext</c>) plug in the
+///     actual tag-backend + logger + virtual-tag writer for each evaluation. Phase 7 plan
+///     decision #6: scripts can read any tag, write only to virtual tags, and have no
+///     other .NET reach — no HttpClient, no File, no Process, no reflection.
+/// </summary>
+/// <remarks>
+///     <para>
+///         Every member on this type MUST be serializable in the narrow sense that
+///         <see cref="DependencyExtractor"/> can recognize tag-access call sites from the
+///         script AST. Method names used from scripts are locked — renaming
+///         <see cref="GetTag"/> or <see cref="SetVirtualTag"/> is a breaking change for every
+///         authored script and the dependency extractor must update in lockstep.
+///     </para>
+///     <para>
+///         New helpers (<see cref="Now"/>, <see cref="Deadband"/>) are additive: adding a
+///         method doesn't invalidate existing scripts. Do not remove or rename without a
+///         plan-level decision + migration for authored scripts.
+///     </para>
+/// </remarks>
+public abstract class ScriptContext
+{
+    /// <summary>
+    ///     Read a tag's current value + quality + source timestamp. Path syntax is
+    ///     <c>Enterprise/Site/Area/Line/Equipment/TagName</c> (forward-slash delimited,
+    ///     matching the Equipment-namespace browse tree). Returns a
+    ///     <see cref="DataValueSnapshot"/> so scripts branch on quality without a second
+    ///     call.
+    /// </summary>
+    /// <remarks>
+    ///     <paramref name="path"/> MUST be a string literal in the script source — dynamic
+    ///     paths (variables, concatenation, method-returned strings) are rejected at
+    ///     publish by <see cref="DependencyExtractor"/>. This is intentional: the static
+    ///     dependency set is required for the change-driven scheduler to subscribe to the
+    ///     right upstream tags at load time.
+    /// </remarks>
+    public abstract DataValueSnapshot GetTag(string path);
+
+    /// <summary>
+    ///     Write a value to a virtual tag. Operator scripts cannot write to driver-sourced
+    ///     tags — the OPC UA dispatch in <c>DriverNodeManager</c> rejects that separately
+    ///     per ADR-002 with <c>BadUserAccessDenied</c>. This method is the only write path
+    ///     virtual tags have.
+    /// </summary>
+    /// <remarks>
+    ///     Path rules identical to <see cref="GetTag"/> — literal only, dependency
+    ///     extractor tracks the write targets so the engine knows what downstream
+    ///     subscribers to notify.
+    /// </remarks>
+    public abstract void SetVirtualTag(string path, object? value);
+
+    /// <summary>
+    ///     Current UTC timestamp. Prefer this over <see cref="DateTime.UtcNow"/> in
+    ///     scripts so the harness can supply a deterministic clock for tests.
+    /// </summary>
+    public abstract DateTime Now { get; }
+
+    /// <summary>
+    ///     Per-script Serilog logger. Output lands in the dedicated <c>scripts-*.log</c>
+    ///     sink with structured property <c>ScriptName</c> = the script's configured name.
+    ///     Use at error level to surface problems; main <c>opcua-*.log</c> receives a
+    ///     companion WARN entry so operators see script errors in the primary log.
+    /// </summary>
+    public abstract ILogger Logger { get; }
+
+    /// <summary>
+    ///     Deadband helper — returns <c>true</c> when <paramref name="current"/> differs
+    ///     from <paramref name="previous"/> by more than <paramref name="tolerance"/>.
+    ///     Useful for alarm predicates that shouldn't flicker on small noise. Pure
+    ///     function; no side effects.
+    /// </summary>
+    public static bool Deadband(double current, double previous, double tolerance)
+        => Math.Abs(current - previous) > tolerance;
+}

src/ZB.MOM.WW.OtOpcUa.Core.Scripting/ScriptEvaluator.cs

@@ -0,0 +1,75 @@
+using Microsoft.CodeAnalysis.CSharp.Scripting;
+using Microsoft.CodeAnalysis.Scripting;
+
+namespace ZB.MOM.WW.OtOpcUa.Core.Scripting;
+
+/// <summary>
+///     Compiles + runs user scripts against a <see cref="ScriptContext"/> subclass. Core
+///     evaluator — no caching, no timeout, no logging side-effects yet (those land in
+///     Stream A.3, A.4, A.5 respectively). Stream B + C wrap this with the dependency
+///     scheduler + alarm state machine.
+/// </summary>
+/// <remarks>
+///     <para>
+///         Scripts are compiled against <see cref="ScriptGlobals{TContext}"/> so the
+///         context member is named <c>ctx</c> in the script, matching the
+///         <see cref="DependencyExtractor"/>'s walker and the Admin UI type stub.
+///     </para>
+///     <para>
+///         Compile pipeline is a three-step gate: (1) Roslyn compile — catches syntax
+///         errors + type-resolution failures, throws <see cref="CompilationErrorException"/>;
+///         (2) <see cref="ForbiddenTypeAnalyzer"/> runs against the semantic model —
+///         catches sandbox escapes that slipped past reference restrictions due to .NET's
+///         type forwarding, throws <see cref="ScriptSandboxViolationException"/>; (3)
+///         delegate creation — throws at this layer only for internal Roslyn bugs, not
+///         user error.
+///     </para>
+///     <para>
+///         Runtime exceptions thrown from user code propagate unwrapped. The virtual-tag
+///         engine (Stream B) catches them per-tag + maps to <c>BadInternalError</c>
+///         quality per Phase 7 decision #11 — this layer doesn't swallow anything so
+///         tests can assert on the original exception type.
+///     </para>
+/// </remarks>
+public sealed class ScriptEvaluator<TContext, TResult>
+    where TContext : ScriptContext
+{
+    private readonly ScriptRunner<TResult> _runner;
+
+    private ScriptEvaluator(ScriptRunner<TResult> runner)
+    {
+        _runner = runner;
+    }
+
+    public static ScriptEvaluator<TContext, TResult> Compile(string scriptSource)
+    {
+        if (scriptSource is null) throw new ArgumentNullException(nameof(scriptSource));
+
+        var options = ScriptSandbox.Build(typeof(TContext));
+        var script = CSharpScript.Create<TResult>(
+            code: scriptSource,
+            options: options,
+            globalsType: typeof(ScriptGlobals<TContext>));
+
+        // Step 1 — Roslyn compile. Throws CompilationErrorException on syntax / type errors.
+        var diagnostics = script.Compile();
+
+        // Step 2 — forbidden-type semantic analysis. Defense-in-depth against reference-list
+        // leaks due to type forwarding.
+        var rejections = ForbiddenTypeAnalyzer.Analyze(script.GetCompilation());
+        if (rejections.Count > 0)
+            throw new ScriptSandboxViolationException(rejections);
+
+        // Step 3 — materialize the callable delegate.
+        var runner = script.CreateDelegate();
+        return new ScriptEvaluator<TContext, TResult>(runner);
+    }
+
+    /// <summary>Run against an already-constructed context.</summary>
+    public Task<TResult> RunAsync(TContext context, CancellationToken ct = default)
+    {
+        if (context is null) throw new ArgumentNullException(nameof(context));
+        var globals = new ScriptGlobals<TContext> { ctx = context };
+        return _runner(globals, ct);
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Core.Scripting/ScriptGlobals.cs

@@ -0,0 +1,19 @@
+namespace ZB.MOM.WW.OtOpcUa.Core.Scripting;
+
+/// <summary>
+///     Wraps a <see cref="ScriptContext"/> as a named field so user scripts see
+///     <c>ctx.GetTag(...)</c> instead of the bare <c>GetTag(...)</c> that Roslyn's
+///     globalsType convention would produce. Keeps the script ergonomics operators
+///     author against consistent with the dependency extractor (which looks for the
+///     <c>ctx.</c> prefix) and with the Admin UI hand-written type stub.
+/// </summary>
+/// <remarks>
+///     Generic on <typeparamref name="TContext"/> so alarm predicates can use a richer
+///     context (e.g. with an <c>Alarm</c> property carrying the owning condition's
+///     metadata) without affecting virtual-tag contexts.
+/// </remarks>
+public class ScriptGlobals<TContext>
+    where TContext : ScriptContext
+{
+    public TContext ctx { get; set; } = default!;
+}

src/ZB.MOM.WW.OtOpcUa.Core.Scripting/ScriptLogCompanionSink.cs

@@ -0,0 +1,65 @@
+using Serilog;
+using Serilog.Core;
+using Serilog.Events;
+
+namespace ZB.MOM.WW.OtOpcUa.Core.Scripting;
+
+/// <summary>
+///     Serilog sink that mirrors script log events at <see cref="LogEventLevel.Error"/>
+///     or higher to a companion logger (typically the main <c>opcua-*.log</c>) at
+///     <see cref="LogEventLevel.Warning"/>. Lets operators see script errors in the
+///     primary server log without drowning it in Debug/Info/Warning noise from scripts.
+/// </summary>
+/// <remarks>
+///     <para>
+///         Registered alongside the dedicated <c>scripts-*.log</c> rolling file sink in
+///         the root script-logger configuration — events below Error land only in the
+///         scripts file; Error/Fatal events land in both the scripts file (at original
+///         level) and the main log (downgraded to Warning since the main log's audience
+///         is server operators, not script authors).
+///     </para>
+///     <para>
+///         The forwarded message preserves the <c>ScriptName</c> property so operators
+///         reading the main log can tell which script raised the error at a glance.
+///         Original exception (if any) is attached so the main log's diagnostics keep
+///         the full stack trace.
+///     </para>
+/// </remarks>
+public sealed class ScriptLogCompanionSink : ILogEventSink
+{
+    private readonly ILogger _mainLogger;
+    private readonly LogEventLevel _minMirrorLevel;
+
+    public ScriptLogCompanionSink(ILogger mainLogger, LogEventLevel minMirrorLevel = LogEventLevel.Error)
+    {
+        _mainLogger = mainLogger ?? throw new ArgumentNullException(nameof(mainLogger));
+        _minMirrorLevel = minMirrorLevel;
+    }
+
+    public void Emit(LogEvent logEvent)
+    {
+        if (logEvent is null) return;
+        if (logEvent.Level < _minMirrorLevel) return;
+
+        var scriptName = "unknown";
+        if (logEvent.Properties.TryGetValue(ScriptLoggerFactory.ScriptNameProperty, out var prop)
+            && prop is ScalarValue sv && sv.Value is string s)
+        {
+            scriptName = s;
+        }
+
+        var rendered = logEvent.RenderMessage();
+        if (logEvent.Exception is not null)
+        {
+            _mainLogger.Warning(logEvent.Exception,
+                "[Script] {ScriptName} emitted {OriginalLevel}: {ScriptMessage}",
+                scriptName, logEvent.Level, rendered);
+        }
+        else
+        {
+            _mainLogger.Warning(
+                "[Script] {ScriptName} emitted {OriginalLevel}: {ScriptMessage}",
+                scriptName, logEvent.Level, rendered);
+        }
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Core.Scripting/ScriptLoggerFactory.cs

@@ -0,0 +1,48 @@
+using Serilog;
+
+namespace ZB.MOM.WW.OtOpcUa.Core.Scripting;
+
+/// <summary>
+///     Creates per-script Serilog <see cref="ILogger"/> instances with the
+///     <c>ScriptName</c> structured property pre-bound. Every log call from a user
+///     script carries the owning virtual-tag or alarm name so operators can filter the
+///     dedicated <c>scripts-*.log</c> sink by script in the Admin UI.
+/// </summary>
+/// <remarks>
+///     <para>
+///         Factory-based — the engine (Stream B / C) constructs exactly one instance
+///         from the root script-logger pipeline at startup, then derives a per-script
+///         logger for each <see cref="ScriptContext"/> it builds. No per-evaluation
+///         allocation in the hot path.
+///     </para>
+///     <para>
+///         The wrapped root logger is responsible for output wiring — typically a
+///         rolling file sink to <c>scripts-*.log</c> plus a
+///         <see cref="ScriptLogCompanionSink"/> that forwards Error-or-higher events
+///         to the main server log at Warning level so operators see script errors
+///         in the primary log without drowning it in Info noise.
+///     </para>
+/// </remarks>
+public sealed class ScriptLoggerFactory
+{
+    /// <summary>Structured property name the enricher binds. Stable for log filtering.</summary>
+    public const string ScriptNameProperty = "ScriptName";
+
+    private readonly ILogger _rootLogger;
+
+    public ScriptLoggerFactory(ILogger rootLogger)
+    {
+        _rootLogger = rootLogger ?? throw new ArgumentNullException(nameof(rootLogger));
+    }
+
+    /// <summary>
+    ///     Create a per-script logger. Every event it emits carries
+    ///     <c>ScriptName=<paramref name="scriptName"/></c> as a structured property.
+    /// </summary>
+    public ILogger Create(string scriptName)
+    {
+        if (string.IsNullOrWhiteSpace(scriptName))
+            throw new ArgumentException("Script name is required.", nameof(scriptName));
+        return _rootLogger.ForContext(ScriptNameProperty, scriptName);
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Core.Scripting/ScriptSandbox.cs

@@ -0,0 +1,87 @@
+using Microsoft.CodeAnalysis.CSharp.Scripting;
+using Microsoft.CodeAnalysis.Scripting;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+
+namespace ZB.MOM.WW.OtOpcUa.Core.Scripting;
+
+/// <summary>
+///     Factory for the <see cref="ScriptOptions"/> every user script is compiled against.
+///     Implements Phase 7 plan decision #6 (read-only sandbox) by whitelisting only the
+///     assemblies + namespaces the script API needs; no <c>System.IO</c>, no
+///     <c>System.Net</c>, no <c>System.Diagnostics.Process</c>, no
+///     <c>System.Reflection</c>. Attempts to reference those types in a script fail at
+///     compile with a compiler error that points at the exact span — the operator sees
+///     the rejection before publish, not at evaluation.
+/// </summary>
+/// <remarks>
+///     <para>
+///         Roslyn's default <see cref="ScriptOptions"/> references <c>mscorlib</c> /
+///         <c>System.Runtime</c> transitively which pulls in every type in the BCL — this
+///         class overrides that with an explicit minimal allow-list.
+///     </para>
+///     <para>
+///         Namespaces pre-imported so scripts don't have to write <c>using</c> clauses:
+///         <c>System</c>, <c>System.Math</c>-style statics are reachable via
+///         <see cref="Math"/>, and <c>ZB.MOM.WW.OtOpcUa.Core.Abstractions</c> so scripts
+///         can name <see cref="DataValueSnapshot"/> directly.
+///     </para>
+///     <para>
+///         The sandbox cannot prevent a script from allocating unbounded memory or
+///         spinning in a tight loop — those are budget concerns, handled by the
+///         per-evaluation timeout (Stream A.4) + the test-harness (Stream F.4) that lets
+///         operators preview output before publishing.
+///     </para>
+/// </remarks>
+public static class ScriptSandbox
+{
+    /// <summary>
+    ///     Build the <see cref="ScriptOptions"/> used for every virtual-tag / alarm
+    ///     script. <paramref name="contextType"/> is the concrete
+    ///     <see cref="ScriptContext"/> subclass the globals will be of — the compiler
+    ///     uses its type to resolve <c>ctx.GetTag(...)</c> calls.
+    /// </summary>
+    public static ScriptOptions Build(Type contextType)
+    {
+        if (contextType is null) throw new ArgumentNullException(nameof(contextType));
+        if (!typeof(ScriptContext).IsAssignableFrom(contextType))
+            throw new ArgumentException(
+                $"Script context type must derive from {nameof(ScriptContext)}", nameof(contextType));
+
+        // Allow-listed assemblies — each explicitly chosen. Adding here is a
+        // plan-level decision; do not expand casually. HashSet so adding the
+        // contextType's assembly is idempotent when it happens to be Core.Scripting
+        // already.
+        var allowedAssemblies = new HashSet<System.Reflection.Assembly>
+        {
+            // System.Private.CoreLib — primitives (int, double, bool, string, DateTime,
+            // TimeSpan, Math, Convert, nullable<T>). Can't practically script without it.
+            typeof(object).Assembly,
+            // System.Linq — IEnumerable extensions (Where / Select / Sum / Average / etc.).
+            typeof(System.Linq.Enumerable).Assembly,
+            // Core.Abstractions — DataValueSnapshot + DriverDataType so scripts can name
+            // the types they receive from ctx.GetTag.
+            typeof(DataValueSnapshot).Assembly,
+            // Core.Scripting itself — ScriptContext base class + Deadband static.
+            typeof(ScriptContext).Assembly,
+            // Serilog.ILogger — script-side logger type.
+            typeof(Serilog.ILogger).Assembly,
+            // Concrete context type's assembly — production contexts subclass
+            // ScriptContext in Core.VirtualTags / Core.ScriptedAlarms; tests use their
+            // own subclass. The globals wrapper is generic on this type so Roslyn must
+            // be able to resolve it during compilation.
+            contextType.Assembly,
+        };
+
+        var allowedImports = new[]
+        {
+            "System",
+            "System.Linq",
+            "ZB.MOM.WW.OtOpcUa.Core.Abstractions",
+            "ZB.MOM.WW.OtOpcUa.Core.Scripting",
+        };
+
+        return ScriptOptions.Default
+            .WithReferences(allowedAssemblies)
+            .WithImports(allowedImports);
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Core.Scripting/TimedScriptEvaluator.cs

@@ -0,0 +1,102 @@
+namespace ZB.MOM.WW.OtOpcUa.Core.Scripting;
+
+/// <summary>
+///     Wraps a <see cref="ScriptEvaluator{TContext, TResult}"/> with a per-evaluation
+///     wall-clock timeout. Default is 250ms per Phase 7 plan Stream A.4; configurable
+///     per tag so deployments with slower backends can widen it.
+/// </summary>
+/// <remarks>
+///     <para>
+///         Implemented with <see cref="Task.WaitAsync(TimeSpan, CancellationToken)"/>
+///         rather than a cancellation-token-only approach because Roslyn-compiled
+///         scripts don't internally poll the cancellation token unless the user code
+///         does async work. A CPU-bound infinite loop in a script won't honor a
+///         cooperative cancel — <c>WaitAsync</c> returns control when the timeout fires
+///         regardless of whether the inner task completes.
+///     </para>
+///     <para>
+///         <b>Known limitation:</b> when a script times out, the underlying ScriptRunner
+///         task continues running on a thread-pool thread until the Roslyn runtime
+///         returns. In the CPU-bound-infinite-loop case that's effectively "leaked" —
+///         the thread is tied up until the runtime decides to return, which it may
+///         never do. Phase 7 plan Stream A.4 accepts this as a known trade-off; tighter
+///         CPU budgeting would require an out-of-process script runner, which is a v3
+///         concern. In practice, the timeout + structured warning log surfaces the
+///         offending script so the operator can fix it; the orphan thread is rare.
+///     </para>
+///     <para>
+///         Caller-supplied <see cref="CancellationToken"/> is honored — if the caller
+///         cancels before the timeout fires, the caller's cancel wins and the
+///         <see cref="OperationCanceledException"/> propagates (not wrapped as
+///         <see cref="ScriptTimeoutException"/>). That distinction matters: the
+///         virtual-tag engine's shutdown path cancels scripts on dispose; it shouldn't
+///         see those as timeouts.
+///     </para>
+/// </remarks>
+public sealed class TimedScriptEvaluator<TContext, TResult>
+    where TContext : ScriptContext
+{
+    /// <summary>Default timeout per Phase 7 plan Stream A.4 — 250ms.</summary>
+    public static readonly TimeSpan DefaultTimeout = TimeSpan.FromMilliseconds(250);
+
+    private readonly ScriptEvaluator<TContext, TResult> _inner;
+
+    /// <summary>Wall-clock budget per evaluation. Script exceeding this throws <see cref="ScriptTimeoutException"/>.</summary>
+    public TimeSpan Timeout { get; }
+
+    public TimedScriptEvaluator(ScriptEvaluator<TContext, TResult> inner)
+        : this(inner, DefaultTimeout)
+    {
+    }
+
+    public TimedScriptEvaluator(ScriptEvaluator<TContext, TResult> inner, TimeSpan timeout)
+    {
+        _inner = inner ?? throw new ArgumentNullException(nameof(inner));
+        if (timeout <= TimeSpan.Zero)
+            throw new ArgumentOutOfRangeException(nameof(timeout), "Timeout must be positive.");
+        Timeout = timeout;
+    }
+
+    public async Task<TResult> RunAsync(TContext context, CancellationToken ct = default)
+    {
+        if (context is null) throw new ArgumentNullException(nameof(context));
+
+        // Push evaluation to a thread-pool thread so a CPU-bound script (e.g. a tight
+        // loop with no async work) doesn't hog the caller's thread before WaitAsync
+        // gets to register its timeout. Without this, Roslyn's ScriptRunner executes
+        // synchronously on the calling thread and returns an already-completed Task,
+        // so WaitAsync sees a completed task and never fires the timeout.
+        var runTask = Task.Run(() => _inner.RunAsync(context, ct), ct);
+        try
+        {
+            return await runTask.WaitAsync(Timeout, ct).ConfigureAwait(false);
+        }
+        catch (TimeoutException)
+        {
+            // WaitAsync's synthesized timeout — the inner task may still be running
+            // on its thread-pool thread (known leak documented in the class summary).
+            // Wrap so callers can distinguish from user-written timeout logic.
+            throw new ScriptTimeoutException(Timeout);
+        }
+    }
+}
+
+/// <summary>
+///     Thrown when a script evaluation exceeds its configured timeout. The virtual-tag
+///     engine (Stream B) catches this + maps the owning tag's quality to
+///     <c>BadInternalError</c> per Phase 7 plan decision #11, logging a structured
+///     warning with the offending script name so operators can locate + fix it.
+/// </summary>
+public sealed class ScriptTimeoutException : Exception
+{
+    public TimeSpan Timeout { get; }
+
+    public ScriptTimeoutException(TimeSpan timeout)
+        : base($"Script evaluation exceeded the configured timeout of {timeout.TotalMilliseconds:F1} ms. " +
+               "The script was either CPU-bound or blocked on a slow operation; check ctx.Logger output " +
+               "around the timeout and consider widening the timeout per tag, simplifying the script, or " +
+               "moving heavy work out of the evaluation path.")
+    {
+        Timeout = timeout;
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Core.Scripting/ZB.MOM.WW.OtOpcUa.Core.Scripting.csproj

@@ -0,0 +1,35 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+    <PropertyGroup>
+        <TargetFramework>net10.0</TargetFramework>
+        <Nullable>enable</Nullable>
+        <ImplicitUsings>enable</ImplicitUsings>
+        <LangVersion>latest</LangVersion>
+        <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+        <GenerateDocumentationFile>true</GenerateDocumentationFile>
+        <NoWarn>$(NoWarn);CS1591</NoWarn>
+        <RootNamespace>ZB.MOM.WW.OtOpcUa.Core.Scripting</RootNamespace>
+    </PropertyGroup>
+
+    <ItemGroup>
+        <!-- Roslyn scripting API — compiles user C# snippets with a constrained ScriptOptions
+             allow-list so scripts can't reach Process/File/HttpClient/reflection. Per Phase 7
+             plan decisions #1 + #6. -->
+        <PackageReference Include="Microsoft.CodeAnalysis.CSharp.Scripting" Version="4.12.0"/>
+        <PackageReference Include="Serilog" Version="4.2.0"/>
+    </ItemGroup>
+
+    <ItemGroup>
+        <ProjectReference Include="..\ZB.MOM.WW.OtOpcUa.Core.Abstractions\ZB.MOM.WW.OtOpcUa.Core.Abstractions.csproj"/>
+    </ItemGroup>
+
+    <ItemGroup>
+        <InternalsVisibleTo Include="ZB.MOM.WW.OtOpcUa.Core.Scripting.Tests"/>
+    </ItemGroup>
+
+    <ItemGroup>
+        <NuGetAuditSuppress Include="https://github.com/advisories/GHSA-37gx-xxp4-5rgx"/>
+        <NuGetAuditSuppress Include="https://github.com/advisories/GHSA-w3x6-4m5h-cxqf"/>
+    </ItemGroup>
+
+</Project>

src/ZB.MOM.WW.OtOpcUa.Core.VirtualTags/DependencyGraph.cs

@@ -0,0 +1,271 @@
+namespace ZB.MOM.WW.OtOpcUa.Core.VirtualTags;
+
+/// <summary>
+///     Directed dependency graph over tag paths. Nodes are tag paths (either driver
+///     tags — leaves — or virtual tags — internal nodes). Edges run from a virtual tag
+///     to each tag it reads via <c>ctx.GetTag(...)</c>. Supports cycle detection at
+///     publish time and topological sort for evaluation ordering.
+/// </summary>
+/// <remarks>
+///     <para>
+///         Cycle detection uses Tarjan's strongly-connected-components algorithm,
+///         iterative implementation (no recursion) so deeply-nested graphs can't blow
+///         the stack. A cycle of length > 1 (or a self-loop) is a publish-time error;
+///         the engine refuses to load such a config.
+///     </para>
+///     <para>
+///         Topological sort uses Kahn's algorithm. The output order guarantees that when
+///         tag X depends on tag Y, Y appears before X — so a change cascade starting at
+///         Y can evaluate the full downstream closure in one serial pass without needing
+///         a second iteration.
+///     </para>
+///     <para>
+///         Missing leaf dependencies (a virtual tag reads a driver tag that doesn't
+///         exist in the live config) are NOT rejected here — the graph treats any
+///         unregistered path as an implicit leaf. Leaf validity is a separate concern
+///         handled at engine-load time against the authoritative tag catalog.
+///     </para>
+/// </remarks>
+public sealed class DependencyGraph
+{
+    private readonly Dictionary<string, HashSet<string>> _dependsOn = new(StringComparer.Ordinal);
+    private readonly Dictionary<string, HashSet<string>> _dependents = new(StringComparer.Ordinal);
+
+    /// <summary>
+    ///     Register a node and the set of tags it depends on. Idempotent — re-adding
+    ///     the same node overwrites the prior dependency set, so re-publishing an edited
+    ///     script works without a separate "remove" call.
+    /// </summary>
+    public void Add(string nodeId, IReadOnlySet<string> dependsOn)
+    {
+        if (string.IsNullOrWhiteSpace(nodeId)) throw new ArgumentException("Node id required.", nameof(nodeId));
+        if (dependsOn is null) throw new ArgumentNullException(nameof(dependsOn));
+
+        // Remove any prior dependents pointing at the previous version of this node.
+        if (_dependsOn.TryGetValue(nodeId, out var previous))
+        {
+            foreach (var dep in previous)
+            {
+                if (_dependents.TryGetValue(dep, out var set))
+                    set.Remove(nodeId);
+            }
+        }
+
+        _dependsOn[nodeId] = new HashSet<string>(dependsOn, StringComparer.Ordinal);
+        foreach (var dep in dependsOn)
+        {
+            if (!_dependents.TryGetValue(dep, out var set))
+                _dependents[dep] = set = new HashSet<string>(StringComparer.Ordinal);
+            set.Add(nodeId);
+        }
+    }
+
+    /// <summary>Tag paths <paramref name="nodeId"/> directly reads.</summary>
+    public IReadOnlySet<string> DirectDependencies(string nodeId) =>
+        _dependsOn.TryGetValue(nodeId, out var set) ? set : (IReadOnlySet<string>)new HashSet<string>();
+
+    /// <summary>
+    ///     Tags whose evaluation depends on <paramref name="nodeId"/> — i.e. when
+    ///     <paramref name="nodeId"/> changes, these need to re-evaluate. Direct only;
+    ///     transitive propagation falls out of the topological sort.
+    /// </summary>
+    public IReadOnlySet<string> DirectDependents(string nodeId) =>
+        _dependents.TryGetValue(nodeId, out var set) ? set : (IReadOnlySet<string>)new HashSet<string>();
+
+    /// <summary>
+    ///     Full transitive dependent closure of <paramref name="nodeId"/> in topological
+    ///     order (direct dependents first, then their dependents, and so on). Used by the
+    ///     change-trigger dispatcher to schedule the right sequence of re-evaluations
+    ///     when a single upstream value changes.
+    /// </summary>
+    public IReadOnlyList<string> TransitiveDependentsInOrder(string nodeId)
+    {
+        if (string.IsNullOrWhiteSpace(nodeId)) return [];
+
+        var result = new List<string>();
+        var visited = new HashSet<string>(StringComparer.Ordinal);
+        var order = TopologicalSort();
+        var rank = new Dictionary<string, int>(StringComparer.Ordinal);
+        for (var i = 0; i < order.Count; i++) rank[order[i]] = i;
+
+        // DFS from the changed node collecting every reachable dependent.
+        var stack = new Stack<string>();
+        stack.Push(nodeId);
+        while (stack.Count > 0)
+        {
+            var cur = stack.Pop();
+            foreach (var dep in DirectDependents(cur))
+            {
+                if (visited.Add(dep))
+                {
+                    result.Add(dep);
+                    stack.Push(dep);
+                }
+            }
+        }
+
+        // Sort by topological rank so when re-evaluation runs serial, earlier entries
+        // are computed before later entries that might depend on them.
+        result.Sort((a, b) =>
+        {
+            var ra = rank.TryGetValue(a, out var va) ? va : int.MaxValue;
+            var rb = rank.TryGetValue(b, out var vb) ? vb : int.MaxValue;
+            return ra.CompareTo(rb);
+        });
+        return result;
+    }
+
+    /// <summary>Iterable of every registered node id (inputs-only tags excluded).</summary>
+    public IReadOnlyCollection<string> RegisteredNodes => _dependsOn.Keys;
+
+    /// <summary>
+    ///     Produce an evaluation order where every node appears after all its
+    ///     dependencies. Throws <see cref="DependencyCycleException"/> if any cycle
+    ///     exists. Implemented via Kahn's algorithm.
+    /// </summary>
+    public IReadOnlyList<string> TopologicalSort()
+    {
+        // Kahn's framing: edge u -> v means "u must come before v". For dependencies,
+        // if X depends on Y, Y must come before X, so the edge runs Y -> X and X has
+        // an incoming edge from Y. inDegree[X] = count of X's registered (virtual) deps
+        // — leaf driver-tag deps don't contribute to ordering since they're never emitted.
+        var inDegree = new Dictionary<string, int>(StringComparer.Ordinal);
+        foreach (var node in _dependsOn.Keys) inDegree[node] = 0;
+        foreach (var kv in _dependsOn)
+        {
+            var nodeId = kv.Key;
+            foreach (var dep in kv.Value)
+            {
+                if (_dependsOn.ContainsKey(dep))
+                    inDegree[nodeId]++;
+            }
+        }
+
+        var ready = new Queue<string>(inDegree.Where(kv => kv.Value == 0).Select(kv => kv.Key));
+        var result = new List<string>();
+        while (ready.Count > 0)
+        {
+            var n = ready.Dequeue();
+            result.Add(n);
+            // In our edge direction (node -> deps), removing n means decrementing in-degree
+            // of every node that DEPENDS on n.
+            foreach (var dependent in DirectDependents(n))
+            {
+                if (inDegree.TryGetValue(dependent, out var d))
+                {
+                    inDegree[dependent] = d - 1;
+                    if (inDegree[dependent] == 0) ready.Enqueue(dependent);
+                }
+            }
+        }
+
+        if (result.Count != inDegree.Count)
+        {
+            var cycles = DetectCycles();
+            throw new DependencyCycleException(cycles);
+        }
+        return result;
+    }
+
+    /// <summary>
+    ///     Returns every strongly-connected component of size &gt; 1 + every self-loop.
+    ///     Empty list means the graph is a DAG. Useful for surfacing every cycle in one
+    ///     rejection pass so operators see all of them, not just one at a time.
+    /// </summary>
+    public IReadOnlyList<IReadOnlyList<string>> DetectCycles()
+    {
+        // Iterative Tarjan's SCC. Avoids recursion so deep graphs don't StackOverflow.
+        var index = 0;
+        var indexOf = new Dictionary<string, int>(StringComparer.Ordinal);
+        var lowlinkOf = new Dictionary<string, int>(StringComparer.Ordinal);
+        var onStack = new HashSet<string>(StringComparer.Ordinal);
+        var sccStack = new Stack<string>();
+        var cycles = new List<IReadOnlyList<string>>();
+
+        foreach (var root in _dependsOn.Keys)
+        {
+            if (indexOf.ContainsKey(root)) continue;
+
+            var work = new Stack<(string node, IEnumerator<string> iter)>();
+            indexOf[root] = index;
+            lowlinkOf[root] = index;
+            index++;
+            onStack.Add(root);
+            sccStack.Push(root);
+            work.Push((root, _dependsOn[root].GetEnumerator()));
+
+            while (work.Count > 0)
+            {
+                var (v, iter) = work.Peek();
+                if (iter.MoveNext())
+                {
+                    var w = iter.Current;
+                    if (!_dependsOn.ContainsKey(w))
+                        continue; // leaf — not part of any cycle with us
+                    if (!indexOf.ContainsKey(w))
+                    {
+                        indexOf[w] = index;
+                        lowlinkOf[w] = index;
+                        index++;
+                        onStack.Add(w);
+                        sccStack.Push(w);
+                        work.Push((w, _dependsOn[w].GetEnumerator()));
+                    }
+                    else if (onStack.Contains(w))
+                    {
+                        lowlinkOf[v] = Math.Min(lowlinkOf[v], indexOf[w]);
+                    }
+                }
+                else
+                {
+                    // v fully explored — unwind
+                    work.Pop();
+                    if (lowlinkOf[v] == indexOf[v])
+                    {
+                        var component = new List<string>();
+                        string w;
+                        do
+                        {
+                            w = sccStack.Pop();
+                            onStack.Remove(w);
+                            component.Add(w);
+                        } while (w != v);
+
+                        if (component.Count > 1 || _dependsOn[v].Contains(v))
+                            cycles.Add(component);
+                    }
+                    else if (work.Count > 0)
+                    {
+                        var parent = work.Peek().node;
+                        lowlinkOf[parent] = Math.Min(lowlinkOf[parent], lowlinkOf[v]);
+                    }
+                }
+            }
+        }
+        return cycles;
+    }
+
+    public void Clear()
+    {
+        _dependsOn.Clear();
+        _dependents.Clear();
+    }
+}
+
+/// <summary>Thrown when <see cref="DependencyGraph.TopologicalSort"/> finds one or more cycles.</summary>
+public sealed class DependencyCycleException : Exception
+{
+    public IReadOnlyList<IReadOnlyList<string>> Cycles { get; }
+
+    public DependencyCycleException(IReadOnlyList<IReadOnlyList<string>> cycles)
+        : base(BuildMessage(cycles))
+    {
+        Cycles = cycles;
+    }
+
+    private static string BuildMessage(IReadOnlyList<IReadOnlyList<string>> cycles)
+    {
+        var lines = cycles.Select(c => "  - " + string.Join(" -> ", c) + " -> " + c[0]);
+        return "Virtual-tag dependency graph contains cycle(s):\n" + string.Join("\n", lines);
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Core.VirtualTags/IHistoryWriter.cs

@@ -0,0 +1,25 @@
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+
+namespace ZB.MOM.WW.OtOpcUa.Core.VirtualTags;
+
+/// <summary>
+///     Sink for virtual-tag evaluation results that the operator marked
+///     <c>Historize = true</c>. Stream G wires this to the existing history-write path
+///     drivers use; tests inject a fake recorder.
+/// </summary>
+/// <remarks>
+///     Emission is fire-and-forget from the evaluation pipeline — a slow historian must
+///     not block script evaluations. Implementations queue internally and drain on their
+///     own cadence.
+/// </remarks>
+public interface IHistoryWriter
+{
+    void Record(string path, DataValueSnapshot value);
+}
+
+/// <summary>No-op default used when no historian is configured.</summary>
+public sealed class NullHistoryWriter : IHistoryWriter
+{
+    public static readonly NullHistoryWriter Instance = new();
+    public void Record(string path, DataValueSnapshot value) { }
+}

src/ZB.MOM.WW.OtOpcUa.Core.VirtualTags/ITagUpstreamSource.cs

@@ -0,0 +1,40 @@
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+
+namespace ZB.MOM.WW.OtOpcUa.Core.VirtualTags;
+
+/// <summary>
+///     What the virtual-tag engine pulls driver-tag values from. Implementations
+///     shipped in Stream G bridge this to <see cref="IReadable"/> + <see cref="ISubscribable"/>
+///     on the live driver instances; tests use an in-memory fake.
+/// </summary>
+/// <remarks>
+///     <para>
+///         The read path is synchronous because user scripts call
+///         <c>ctx.GetTag(path)</c> inline — blocking on a driver wire call per-script
+///         evaluation would kill throughput. Implementations are expected to serve
+///         from a last-known-value cache populated by the subscription callbacks.
+///     </para>
+///     <para>
+///         The subscription path feeds the engine's <c>ChangeTriggerDispatcher</c> so
+///         change-driven virtual tags re-evaluate on any upstream delta (value, status,
+///         or timestamp). One subscription per distinct upstream tag path; the engine
+///         tracks the mapping itself.
+///     </para>
+/// </remarks>
+public interface ITagUpstreamSource
+{
+    /// <summary>
+    ///     Synchronous read returning the last-known value + quality for
+    ///     <paramref name="path"/>. Returns a <c>BadNodeIdUnknown</c>-quality snapshot
+    ///     when the path isn't configured.
+    /// </summary>
+    DataValueSnapshot ReadTag(string path);
+
+    /// <summary>
+    ///     Register an observer that fires every time the upstream value at
+    ///     <paramref name="path"/> changes. Returns an <see cref="IDisposable"/> the
+    ///     engine disposes when the virtual-tag config is reloaded or the engine shuts
+    ///     down, so source-side subscriptions don't leak.
+    /// </summary>
+    IDisposable SubscribeTag(string path, Action<string, DataValueSnapshot> observer);
+}

src/ZB.MOM.WW.OtOpcUa.Core.VirtualTags/TimerTriggerScheduler.cs

@@ -0,0 +1,83 @@
+using Serilog;
+
+namespace ZB.MOM.WW.OtOpcUa.Core.VirtualTags;
+
+/// <summary>
+///     Periodic re-evaluation scheduler for tags with a non-null
+///     <see cref="VirtualTagDefinition.TimerInterval"/>. Independent of the
+///     change-trigger path — a tag can be timer-only, change-only, or both. One
+///     <see cref="System.Threading.Timer"/> per interval-group keeps the wire count
+///     low regardless of tag count.
+/// </summary>
+public sealed class TimerTriggerScheduler : IDisposable
+{
+    private readonly VirtualTagEngine _engine;
+    private readonly ILogger _logger;
+    private readonly List<Timer> _timers = [];
+    private readonly CancellationTokenSource _cts = new();
+    private bool _disposed;
+
+    public TimerTriggerScheduler(VirtualTagEngine engine, ILogger logger)
+    {
+        _engine = engine ?? throw new ArgumentNullException(nameof(engine));
+        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
+    }
+
+    /// <summary>
+    ///     Stand up one <see cref="Timer"/> per unique interval. All tags with
+    ///     matching interval share a timer; each tick triggers re-evaluation of the
+    ///     group in topological order so cascades are consistent with change-triggered
+    ///     behavior.
+    /// </summary>
+    public void Start(IReadOnlyList<VirtualTagDefinition> definitions)
+    {
+        if (_disposed) throw new ObjectDisposedException(nameof(TimerTriggerScheduler));
+
+        var byInterval = definitions
+            .Where(d => d.TimerInterval.HasValue && d.TimerInterval.Value > TimeSpan.Zero)
+            .GroupBy(d => d.TimerInterval!.Value);
+
+        foreach (var group in byInterval)
+        {
+            var paths = group.Select(d => d.Path).ToArray();
+            var interval = group.Key;
+            var timer = new Timer(_ => Tick(paths), null, interval, interval);
+            _timers.Add(timer);
+            _logger.Information("TimerTriggerScheduler: {TagCount} tag(s) on {Interval} cadence",
+                paths.Length, interval);
+        }
+    }
+
+    private void Tick(IReadOnlyList<string> paths)
+    {
+        if (_cts.IsCancellationRequested) return;
+        foreach (var p in paths)
+        {
+            try
+            {
+                _engine.EvaluateOneAsync(p, _cts.Token).GetAwaiter().GetResult();
+            }
+            catch (OperationCanceledException)
+            {
+                return;
+            }
+            catch (Exception ex)
+            {
+                _logger.Error(ex, "TimerTriggerScheduler evaluate failed for {Path}", p);
+            }
+        }
+    }
+
+    public void Dispose()
+    {
+        if (_disposed) return;
+        _disposed = true;
+        _cts.Cancel();
+        foreach (var t in _timers)
+        {
+            try { t.Dispose(); } catch { }
+        }
+        _timers.Clear();
+        _cts.Dispose();
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Core.VirtualTags/VirtualTagContext.cs

@@ -0,0 +1,64 @@
+using Serilog;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+using ZB.MOM.WW.OtOpcUa.Core.Scripting;
+
+namespace ZB.MOM.WW.OtOpcUa.Core.VirtualTags;
+
+/// <summary>
+///     Per-evaluation <see cref="ScriptContext"/> for a virtual-tag script. Reads come
+///     out of the engine's last-known-value cache (driver tags updated via the
+///     <see cref="ITagUpstreamSource"/> subscription, virtual tags updated by prior
+///     evaluations). Writes route through the engine's <c>SetVirtualTag</c> callback so
+///     cross-tag write side effects still participate in change-trigger cascades.
+/// </summary>
+/// <remarks>
+///     <para>
+///         Context instances are evaluation-scoped, not tag-scoped. The engine
+///         constructs a fresh context for every run — cheap because the constructor
+///         just captures references — so scripts can't cache mutable state across runs
+///         via <c>ctx</c>. Mutable state across runs is a future decision (e.g. a
+///         dedicated <c>ctx.Memory</c> dictionary); not in scope for Phase 7.
+///     </para>
+///     <para>
+///         The <see cref="Now"/> clock is injectable so tests can pin time
+///         deterministically. Production wires to <see cref="DateTime.UtcNow"/>.
+///     </para>
+/// </remarks>
+public sealed class VirtualTagContext : ScriptContext
+{
+    private readonly IReadOnlyDictionary<string, DataValueSnapshot> _readCache;
+    private readonly Action<string, object?> _setVirtualTag;
+    private readonly Func<DateTime> _clock;
+
+    public VirtualTagContext(
+        IReadOnlyDictionary<string, DataValueSnapshot> readCache,
+        Action<string, object?> setVirtualTag,
+        ILogger logger,
+        Func<DateTime>? clock = null)
+    {
+        _readCache = readCache ?? throw new ArgumentNullException(nameof(readCache));
+        _setVirtualTag = setVirtualTag ?? throw new ArgumentNullException(nameof(setVirtualTag));
+        Logger = logger ?? throw new ArgumentNullException(nameof(logger));
+        _clock = clock ?? (() => DateTime.UtcNow);
+    }
+
+    public override DataValueSnapshot GetTag(string path)
+    {
+        if (string.IsNullOrWhiteSpace(path))
+            return new DataValueSnapshot(null, 0x80340000u /* BadNodeIdUnknown */, null, _clock());
+        return _readCache.TryGetValue(path, out var v)
+            ? v
+            : new DataValueSnapshot(null, 0x80340000u /* BadNodeIdUnknown */, null, _clock());
+    }
+
+    public override void SetVirtualTag(string path, object? value)
+    {
+        if (string.IsNullOrWhiteSpace(path))
+            throw new ArgumentException("Virtual tag path required.", nameof(path));
+        _setVirtualTag(path, value);
+    }
+
+    public override DateTime Now => _clock();
+
+    public override ILogger Logger { get; }
+}

src/ZB.MOM.WW.OtOpcUa.Core.VirtualTags/VirtualTagDefinition.cs

@@ -0,0 +1,41 @@
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+
+namespace ZB.MOM.WW.OtOpcUa.Core.VirtualTags;
+
+/// <summary>
+///     Operator-authored virtual-tag configuration row. Phase 7 Stream E (config DB
+///     schema) materializes these from the <c>VirtualTag</c> + <c>Script</c> tables on
+///     publish; the engine ingests a list of them at load time.
+/// </summary>
+/// <param name="Path">
+///     UNS tag path — <c>Enterprise/Site/Area/Line/Equipment/TagName</c>. Used both as
+///     the engine's internal id and the OPC UA browse path.
+/// </param>
+/// <param name="DataType">
+///     Expected return type. The evaluator coerces the script's return value to this
+///     type before publishing; mismatch surfaces as <c>BadTypeMismatch</c> quality on
+///     the tag.
+/// </param>
+/// <param name="ScriptSource">Roslyn C# script source. Must compile under <c>ScriptSandbox</c>.</param>
+/// <param name="ChangeTriggered">
+///     True if any input tag's change (value / status / timestamp delta) should trigger
+///     re-evaluation. Operator picks per tag — usually true for inputs that change at
+///     protocol rates.
+/// </param>
+/// <param name="TimerInterval">
+///     Optional periodic re-evaluation cadence. Null = timer-driven disabled. Both can
+///     be enabled simultaneously; independent scheduling paths both feed
+///     <c>EvaluationPipeline</c>.
+/// </param>
+/// <param name="Historize">
+///     When true, every evaluation result is forwarded to the configured
+///     <see cref="IHistoryWriter"/>. Operator-set per tag; the Admin UI exposes as a
+///     checkbox.
+/// </param>
+public sealed record VirtualTagDefinition(
+    string Path,
+    DriverDataType DataType,
+    string ScriptSource,
+    bool ChangeTriggered = true,
+    TimeSpan? TimerInterval = null,
+    bool Historize = false);

src/ZB.MOM.WW.OtOpcUa.Core.VirtualTags/VirtualTagEngine.cs

@@ -0,0 +1,385 @@
+using System.Collections.Concurrent;
+using Serilog;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+using ZB.MOM.WW.OtOpcUa.Core.Scripting;
+
+namespace ZB.MOM.WW.OtOpcUa.Core.VirtualTags;
+
+/// <summary>
+///     The Phase 7 virtual-tag evaluation engine. Ingests a set of
+///     <see cref="VirtualTagDefinition"/>s at load time, compiles each script against
+///     <see cref="ScriptSandbox"/>, builds the dependency graph, subscribes to every
+///     referenced upstream tag, and schedules re-evaluations on change + on timer.
+/// </summary>
+/// <remarks>
+///     <para>
+///         Evaluation order is topological per ADR-001 / Phase 7 plan decision #19 —
+///         serial for the v1 rollout, parallel promoted to a follow-up. When upstream
+///         tag X changes, the engine computes the transitive dependent closure of X in
+///         topological rank and evaluates each in turn, so a cascade through multiple
+///         levels of virtual tags settles within one change-trigger pass.
+///     </para>
+///     <para>
+///         Per-tag error isolation per Phase 7 plan decision #11 — a script exception
+///         (or timeout) fails that tag's latest value with <c>BadInternalError</c> or
+///         <c>BadTypeMismatch</c> quality and logs a structured error; every other tag
+///         keeps evaluating. The engine itself never faults from a user script.
+///     </para>
+/// </remarks>
+public sealed class VirtualTagEngine : IDisposable
+{
+    private readonly ITagUpstreamSource _upstream;
+    private readonly IHistoryWriter _history;
+    private readonly ScriptLoggerFactory _loggerFactory;
+    private readonly ILogger _engineLogger;
+    private readonly Func<DateTime> _clock;
+    private readonly TimeSpan _scriptTimeout;
+
+    private readonly DependencyGraph _graph = new();
+    private readonly Dictionary<string, VirtualTagState> _tags = new(StringComparer.Ordinal);
+    private readonly ConcurrentDictionary<string, DataValueSnapshot> _valueCache = new(StringComparer.Ordinal);
+    private readonly ConcurrentDictionary<string, List<Action<string, DataValueSnapshot>>> _observers
+        = new(StringComparer.Ordinal);
+    private readonly List<IDisposable> _upstreamSubscriptions = [];
+    private readonly SemaphoreSlim _evalGate = new(1, 1);
+    private bool _loaded;
+    private bool _disposed;
+
+    public VirtualTagEngine(
+        ITagUpstreamSource upstream,
+        ScriptLoggerFactory loggerFactory,
+        ILogger engineLogger,
+        IHistoryWriter? historyWriter = null,
+        Func<DateTime>? clock = null,
+        TimeSpan? scriptTimeout = null)
+    {
+        _upstream = upstream ?? throw new ArgumentNullException(nameof(upstream));
+        _loggerFactory = loggerFactory ?? throw new ArgumentNullException(nameof(loggerFactory));
+        _engineLogger = engineLogger ?? throw new ArgumentNullException(nameof(engineLogger));
+        _history = historyWriter ?? NullHistoryWriter.Instance;
+        _clock = clock ?? (() => DateTime.UtcNow);
+        _scriptTimeout = scriptTimeout ?? TimedScriptEvaluator<VirtualTagContext, object?>.DefaultTimeout;
+    }
+
+    /// <summary>Registered tag paths, in topological order. Empty before <see cref="Load"/>.</summary>
+    public IReadOnlyCollection<string> LoadedTagPaths => _tags.Keys;
+
+    /// <summary>Compile + register every tag in <paramref name="definitions"/>. Throws on cycle or any compile failure.</summary>
+    public void Load(IReadOnlyList<VirtualTagDefinition> definitions)
+    {
+        if (_disposed) throw new ObjectDisposedException(nameof(VirtualTagEngine));
+        if (definitions is null) throw new ArgumentNullException(nameof(definitions));
+
+        // Start from a clean slate — supports config-publish reloads.
+        UnsubscribeFromUpstream();
+        _tags.Clear();
+        _graph.Clear();
+
+        var compileFailures = new List<string>();
+        foreach (var def in definitions)
+        {
+            try
+            {
+                var extraction = DependencyExtractor.Extract(def.ScriptSource);
+                if (!extraction.IsValid)
+                {
+                    var msgs = string.Join("; ", extraction.Rejections.Select(r => r.Message));
+                    compileFailures.Add($"{def.Path}: dependency extraction rejected — {msgs}");
+                    continue;
+                }
+
+                var evaluator = ScriptEvaluator<VirtualTagContext, object?>.Compile(def.ScriptSource);
+                var timed = new TimedScriptEvaluator<VirtualTagContext, object?>(evaluator, _scriptTimeout);
+                var scriptLogger = _loggerFactory.Create(def.Path);
+
+                _tags[def.Path] = new VirtualTagState(def, timed, extraction.Reads, extraction.Writes, scriptLogger);
+                _graph.Add(def.Path, extraction.Reads);
+            }
+            catch (Exception ex)
+            {
+                compileFailures.Add($"{def.Path}: {ex.Message}");
+            }
+        }
+
+        if (compileFailures.Count > 0)
+        {
+            var joined = string.Join("\n  ", compileFailures);
+            throw new InvalidOperationException(
+                $"Virtual-tag engine load failed. {compileFailures.Count} script(s) did not compile:\n  {joined}");
+        }
+
+        // Cycle check — throws DependencyCycleException on offense.
+        _ = _graph.TopologicalSort();
+
+        // Subscribe to every referenced upstream path (driver tags only — virtual tags
+        // cascade internally). Seed the cache with current upstream values so first
+        // evaluations see something real.
+        var upstreamPaths = definitions
+            .SelectMany(d => _tags[d.Path].Reads)
+            .Where(p => !_tags.ContainsKey(p))
+            .Distinct(StringComparer.Ordinal);
+        foreach (var path in upstreamPaths)
+        {
+            _valueCache[path] = _upstream.ReadTag(path);
+            _upstreamSubscriptions.Add(_upstream.SubscribeTag(path, OnUpstreamChange));
+        }
+
+        _loaded = true;
+        _engineLogger.Information(
+            "VirtualTagEngine loaded {TagCount} tag(s), {UpstreamCount} upstream subscription(s)",
+            _tags.Count, _upstreamSubscriptions.Count);
+    }
+
+    /// <summary>
+    ///     Evaluate every registered tag once in topological order — used at startup so
+    ///     virtual tags have a defined initial value rather than inheriting the cache
+    ///     default. Also called after a config reload.
+    /// </summary>
+    public async Task EvaluateAllAsync(CancellationToken ct = default)
+    {
+        EnsureLoaded();
+        var order = _graph.TopologicalSort();
+        foreach (var path in order)
+        {
+            if (_tags.ContainsKey(path))
+                await EvaluateOneAsync(path, ct).ConfigureAwait(false);
+        }
+    }
+
+    /// <summary>Evaluate a single tag — used by the timer trigger + test hooks.</summary>
+    public Task EvaluateOneAsync(string path, CancellationToken ct = default)
+    {
+        EnsureLoaded();
+        if (!_tags.ContainsKey(path))
+            throw new ArgumentException($"Not a registered virtual tag: {path}", nameof(path));
+        return EvaluateInternalAsync(path, ct);
+    }
+
+    /// <summary>
+    ///     Read the most recently evaluated value for <paramref name="path"/>. Driver
+    ///     tags return the last-known upstream value; virtual tags return their last
+    ///     evaluation result.
+    /// </summary>
+    public DataValueSnapshot Read(string path)
+    {
+        if (string.IsNullOrWhiteSpace(path))
+            return new DataValueSnapshot(null, 0x80340000u, null, _clock());
+        return _valueCache.TryGetValue(path, out var v)
+            ? v
+            : new DataValueSnapshot(null, 0x80340000u /* BadNodeIdUnknown */, null, _clock());
+    }
+
+    /// <summary>
+    ///     Register an observer that fires on every evaluation of the given tag.
+    ///     Returns an <see cref="IDisposable"/> to unsubscribe. Does NOT fire a seed
+    ///     value — subscribers call <see cref="Read"/> for the current value if needed.
+    /// </summary>
+    public IDisposable Subscribe(string path, Action<string, DataValueSnapshot> observer)
+    {
+        var list = _observers.GetOrAdd(path, _ => []);
+        lock (list) { list.Add(observer); }
+        return new Unsub(this, path, observer);
+    }
+
+    /// <summary>
+    ///     Change-trigger entry point — called by the upstream subscription callback.
+    ///     Updates the cache, fans out to observers (so OPC UA clients see the upstream
+    ///     change too if they subscribed via the engine), and schedules every
+    ///     change-triggered dependent for re-evaluation in topological order.
+    /// </summary>
+    internal void OnUpstreamChange(string path, DataValueSnapshot value)
+    {
+        _valueCache[path] = value;
+        NotifyObservers(path, value);
+
+        // Fire-and-forget — the upstream subscription callback must not block the
+        // driver's dispatcher. Exceptions during cascade are handled per-tag inside
+        // EvaluateInternalAsync.
+        _ = CascadeAsync(path, CancellationToken.None);
+    }
+
+    private async Task CascadeAsync(string upstreamPath, CancellationToken ct)
+    {
+        try
+        {
+            var dependents = _graph.TransitiveDependentsInOrder(upstreamPath);
+            foreach (var dep in dependents)
+            {
+                if (_tags.TryGetValue(dep, out var state) && state.Definition.ChangeTriggered)
+                    await EvaluateInternalAsync(dep, ct).ConfigureAwait(false);
+            }
+        }
+        catch (Exception ex)
+        {
+            _engineLogger.Error(ex, "VirtualTagEngine cascade failed for upstream {Path}", upstreamPath);
+        }
+    }
+
+    private async Task EvaluateInternalAsync(string path, CancellationToken ct)
+    {
+        if (!_tags.TryGetValue(path, out var state)) return;
+
+        // Serial evaluation across all tags. Phase 7 plan decision #19 — parallel is a
+        // follow-up. The semaphore bounds the evaluation graph so two cascades don't
+        // interleave, which would break the "earlier nodes computed first" invariant.
+        // SemaphoreSlim.WaitAsync is async-safe where Monitor.Enter is not (Monitor
+        // ownership is thread-local and lost across await).
+        await _evalGate.WaitAsync(ct).ConfigureAwait(false);
+        try
+        {
+            var ctxCache = BuildReadCache(state.Reads);
+            var context = new VirtualTagContext(
+                ctxCache,
+                (p, v) => OnScriptSetVirtualTag(p, v),
+                state.Logger,
+                _clock);
+
+            DataValueSnapshot result;
+            try
+            {
+                var raw = await state.Evaluator.RunAsync(context, ct).ConfigureAwait(false);
+                var coerced = CoerceResult(raw, state.Definition.DataType);
+                result = new DataValueSnapshot(coerced, 0u, _clock(), _clock());
+            }
+            catch (ScriptTimeoutException tex)
+            {
+                state.Logger.Warning("Script timed out after {Timeout}", tex.Timeout);
+                result = new DataValueSnapshot(null, 0x80020000u /* BadInternalError */, null, _clock());
+            }
+            catch (OperationCanceledException)
+            {
+                throw; // shutdown path — don't misclassify
+            }
+            catch (Exception ex)
+            {
+                state.Logger.Error(ex, "Virtual-tag script threw");
+                result = new DataValueSnapshot(null, 0x80020000u /* BadInternalError */, null, _clock());
+            }
+
+            _valueCache[path] = result;
+            NotifyObservers(path, result);
+            if (state.Definition.Historize) _history.Record(path, result);
+        }
+        finally
+        {
+            _evalGate.Release();
+        }
+    }
+
+    private IReadOnlyDictionary<string, DataValueSnapshot> BuildReadCache(IReadOnlySet<string> reads)
+    {
+        var map = new Dictionary<string, DataValueSnapshot>(StringComparer.Ordinal);
+        foreach (var r in reads)
+        {
+            map[r] = _valueCache.TryGetValue(r, out var v)
+                ? v
+                : _upstream.ReadTag(r);
+        }
+        return map;
+    }
+
+    private void OnScriptSetVirtualTag(string path, object? value)
+    {
+        if (!_tags.ContainsKey(path))
+        {
+            _engineLogger.Warning(
+                "Script attempted ctx.SetVirtualTag on non-virtual or non-registered path {Path}", path);
+            return;
+        }
+        var snap = new DataValueSnapshot(value, 0u, _clock(), _clock());
+        _valueCache[path] = snap;
+        NotifyObservers(path, snap);
+        if (_tags[path].Definition.Historize) _history.Record(path, snap);
+    }
+
+    private void NotifyObservers(string path, DataValueSnapshot value)
+    {
+        if (!_observers.TryGetValue(path, out var list)) return;
+        Action<string, DataValueSnapshot>[] snapshot;
+        lock (list) { snapshot = list.ToArray(); }
+        foreach (var obs in snapshot)
+        {
+            try { obs(path, value); }
+            catch (Exception ex)
+            {
+                _engineLogger.Warning(ex, "Virtual-tag observer for {Path} threw", path);
+            }
+        }
+    }
+
+    private static object? CoerceResult(object? raw, DriverDataType target)
+    {
+        if (raw is null) return null;
+        try
+        {
+            return target switch
+            {
+                DriverDataType.Boolean => Convert.ToBoolean(raw),
+                DriverDataType.Int32 => Convert.ToInt32(raw),
+                DriverDataType.Int64 => Convert.ToInt64(raw),
+                DriverDataType.Float32 => Convert.ToSingle(raw),
+                DriverDataType.Float64 => Convert.ToDouble(raw),
+                DriverDataType.String => Convert.ToString(raw) ?? string.Empty,
+                DriverDataType.DateTime => raw is DateTime dt ? dt : Convert.ToDateTime(raw),
+                _ => raw,
+            };
+        }
+        catch
+        {
+            // Caller logs + maps to BadTypeMismatch — we let null propagate so the
+            // outer evaluation path sets the Bad quality.
+            return null;
+        }
+    }
+
+    private void UnsubscribeFromUpstream()
+    {
+        foreach (var s in _upstreamSubscriptions)
+        {
+            try { s.Dispose(); } catch { /* best effort */ }
+        }
+        _upstreamSubscriptions.Clear();
+    }
+
+    private void EnsureLoaded()
+    {
+        if (!_loaded) throw new InvalidOperationException(
+            "VirtualTagEngine not loaded. Call Load(definitions) first.");
+    }
+
+    public void Dispose()
+    {
+        if (_disposed) return;
+        _disposed = true;
+        UnsubscribeFromUpstream();
+        _tags.Clear();
+        _graph.Clear();
+    }
+
+    internal DependencyGraph GraphForTesting => _graph;
+
+    private sealed class Unsub : IDisposable
+    {
+        private readonly VirtualTagEngine _engine;
+        private readonly string _path;
+        private readonly Action<string, DataValueSnapshot> _observer;
+        public Unsub(VirtualTagEngine e, string path, Action<string, DataValueSnapshot> observer)
+        {
+            _engine = e; _path = path; _observer = observer;
+        }
+        public void Dispose()
+        {
+            if (_engine._observers.TryGetValue(_path, out var list))
+            {
+                lock (list) { list.Remove(_observer); }
+            }
+        }
+    }
+
+    internal sealed record VirtualTagState(
+        VirtualTagDefinition Definition,
+        TimedScriptEvaluator<VirtualTagContext, object?> Evaluator,
+        IReadOnlySet<string> Reads,
+        IReadOnlySet<string> Writes,
+        ILogger Logger);
+}

src/ZB.MOM.WW.OtOpcUa.Core.VirtualTags/VirtualTagSource.cs

@@ -0,0 +1,89 @@
+using System.Collections.Concurrent;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+
+namespace ZB.MOM.WW.OtOpcUa.Core.VirtualTags;
+
+/// <summary>
+///     Implements the driver-agnostic capability surface the
+///     <c>DriverNodeManager</c> dispatches to when a node resolves to
+///     <c>NodeSource.Virtual</c> per ADR-002. Reads return the engine's last-known
+///     evaluation result; subscriptions forward engine-emitted change events as
+///     <see cref="ISubscribable.OnDataChange"/> events.
+/// </summary>
+/// <remarks>
+///     <para>
+///         <see cref="IWritable"/> is deliberately not implemented — OPC UA client
+///         writes to virtual tags are rejected in <c>DriverNodeManager</c> before they
+///         reach here per Phase 7 decision #6. Scripts are the only write path, routed
+///         through <c>ctx.SetVirtualTag</c>.
+///     </para>
+/// </remarks>
+public sealed class VirtualTagSource : IReadable, ISubscribable
+{
+    private readonly VirtualTagEngine _engine;
+    private readonly ConcurrentDictionary<string, Subscription> _subs = new(StringComparer.Ordinal);
+
+    public VirtualTagSource(VirtualTagEngine engine)
+    {
+        _engine = engine ?? throw new ArgumentNullException(nameof(engine));
+    }
+
+    public event EventHandler<DataChangeEventArgs>? OnDataChange;
+
+    public Task<IReadOnlyList<DataValueSnapshot>> ReadAsync(
+        IReadOnlyList<string> fullReferences, CancellationToken cancellationToken)
+    {
+        if (fullReferences is null) throw new ArgumentNullException(nameof(fullReferences));
+        var results = new DataValueSnapshot[fullReferences.Count];
+        for (var i = 0; i < fullReferences.Count; i++)
+            results[i] = _engine.Read(fullReferences[i]);
+        return Task.FromResult<IReadOnlyList<DataValueSnapshot>>(results);
+    }
+
+    public Task<ISubscriptionHandle> SubscribeAsync(
+        IReadOnlyList<string> fullReferences,
+        TimeSpan publishingInterval,
+        CancellationToken cancellationToken)
+    {
+        if (fullReferences is null) throw new ArgumentNullException(nameof(fullReferences));
+
+        var handle = new SubscriptionHandle(Guid.NewGuid().ToString("N"));
+        var observers = new List<IDisposable>(fullReferences.Count);
+        foreach (var path in fullReferences)
+        {
+            observers.Add(_engine.Subscribe(path, (p, snap) =>
+                OnDataChange?.Invoke(this, new DataChangeEventArgs(handle, p, snap))));
+        }
+        _subs[handle.DiagnosticId] = new Subscription(handle, observers);
+
+        // OPC UA convention: emit initial-data callback for each path with the current value.
+        foreach (var path in fullReferences)
+        {
+            var snap = _engine.Read(path);
+            OnDataChange?.Invoke(this, new DataChangeEventArgs(handle, path, snap));
+        }
+
+        return Task.FromResult<ISubscriptionHandle>(handle);
+    }
+
+    public Task UnsubscribeAsync(ISubscriptionHandle handle, CancellationToken cancellationToken)
+    {
+        if (handle is null) throw new ArgumentNullException(nameof(handle));
+        if (_subs.TryRemove(handle.DiagnosticId, out var sub))
+        {
+            foreach (var d in sub.Observers)
+            {
+                try { d.Dispose(); } catch { }
+            }
+        }
+        return Task.CompletedTask;
+    }
+
+    private sealed class SubscriptionHandle : ISubscriptionHandle
+    {
+        public SubscriptionHandle(string id) { DiagnosticId = id; }
+        public string DiagnosticId { get; }
+    }
+
+    private sealed record Subscription(SubscriptionHandle Handle, IReadOnlyList<IDisposable> Observers);
+}

src/ZB.MOM.WW.OtOpcUa.Core.VirtualTags/ZB.MOM.WW.OtOpcUa.Core.VirtualTags.csproj

@@ -0,0 +1,32 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+    <PropertyGroup>
+        <TargetFramework>net10.0</TargetFramework>
+        <Nullable>enable</Nullable>
+        <ImplicitUsings>enable</ImplicitUsings>
+        <LangVersion>latest</LangVersion>
+        <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+        <GenerateDocumentationFile>true</GenerateDocumentationFile>
+        <NoWarn>$(NoWarn);CS1591</NoWarn>
+        <RootNamespace>ZB.MOM.WW.OtOpcUa.Core.VirtualTags</RootNamespace>
+    </PropertyGroup>
+
+    <ItemGroup>
+        <PackageReference Include="Serilog" Version="4.2.0"/>
+    </ItemGroup>
+
+    <ItemGroup>
+        <ProjectReference Include="..\ZB.MOM.WW.OtOpcUa.Core.Abstractions\ZB.MOM.WW.OtOpcUa.Core.Abstractions.csproj"/>
+        <ProjectReference Include="..\ZB.MOM.WW.OtOpcUa.Core.Scripting\ZB.MOM.WW.OtOpcUa.Core.Scripting.csproj"/>
+    </ItemGroup>
+
+    <ItemGroup>
+        <InternalsVisibleTo Include="ZB.MOM.WW.OtOpcUa.Core.VirtualTags.Tests"/>
+    </ItemGroup>
+
+    <ItemGroup>
+        <NuGetAuditSuppress Include="https://github.com/advisories/GHSA-37gx-xxp4-5rgx"/>
+        <NuGetAuditSuppress Include="https://github.com/advisories/GHSA-w3x6-4m5h-cxqf"/>
+    </ItemGroup>
+
+</Project>

src/ZB.MOM.WW.OtOpcUa.Core/OpcUa/EquipmentNodeWalker.cs

@@ -0,0 +1,173 @@
+using ZB.MOM.WW.OtOpcUa.Configuration.Entities;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+
+namespace ZB.MOM.WW.OtOpcUa.Core.OpcUa;
+
+/// <summary>
+///     Materializes the canonical Unified Namespace browse tree for an Equipment-kind
+///     <see cref="Configuration.Entities.Namespace"/> from the Config DB's
+///     <c>UnsArea</c> / <c>UnsLine</c> / <c>Equipment</c> / <c>Tag</c> rows. Runs during
+///     address-space build per <see cref="IDriver"/> whose
+///     <c>Namespace.Kind = Equipment</c>; SystemPlatform-kind namespaces (Galaxy) are
+///     exempt per decision #120 and reach this walker only indirectly through
+///     <see cref="ITagDiscovery.DiscoverAsync"/>.
+/// </summary>
+/// <remarks>
+///     <para>
+///         <b>Composition strategy.</b> ADR-001 (2026-04-20) accepted Option A — Config
+///         primary. The walker treats the supplied <see cref="EquipmentNamespaceContent"/>
+///         snapshot as the authoritative published surface. Every Equipment row becomes a
+///         folder node at the UNS level-5 segment; every <see cref="Tag"/> bound to an
+///         Equipment (non-null <see cref="Tag.EquipmentId"/>) becomes a variable node under
+///         it. Driver-discovered tags that have no Config-DB row are not added by this
+///         walker — the ITagDiscovery path continues to exist for the SystemPlatform case +
+///         for enrichment, but Equipment-kind composition is fully Tag-row-driven.
+///     </para>
+///
+///     <para>
+///         <b>Under each Equipment node.</b> Five identifier properties per decision #121
+///         (<c>EquipmentId</c>, <c>EquipmentUuid</c>, <c>MachineCode</c>, <c>ZTag</c>,
+///         <c>SAPID</c>) are added as OPC UA properties — external systems (ERP, SAP PM)
+///         resolve equipment by whichever identifier they natively use without a sidecar.
+///         <see cref="IdentificationFolderBuilder.Build"/> materializes the OPC 40010
+///         Identification sub-folder with the nine decision-#139 fields when at least one
+///         is non-null; when all nine are null the sub-folder is omitted rather than
+///         appearing empty.
+///     </para>
+///
+///     <para>
+///         <b>Address resolution.</b> Variable nodes carry the driver-side full reference
+///         in <see cref="DriverAttributeInfo.FullName"/> copied from <c>Tag.TagConfig</c>
+///         (the wire-level address JSON blob whose interpretation is driver-specific). At
+///         runtime the dispatch layer routes Read/Write calls through the configured
+///         capability invoker; an unreachable address surfaces as an OPC UA Bad status via
+///         the natural driver-read failure path, NOT as a build-time reject. The ADR calls
+///         this "BadNotFound placeholder" behavior — legible to operators via their Admin
+///         UI + OPC UA client inspection of node status.
+///     </para>
+///
+///     <para>
+///         <b>Pure function.</b> This class has no dependency on the OPC UA SDK, no
+///         Config-DB access, no state. It consumes pre-loaded EF Core rows + streams calls
+///         into the supplied <see cref="IAddressSpaceBuilder"/>. The server-side wiring
+///         (load snapshot → invoke walker → per-tag capability probe) lives in the Task B
+///         PR alongside <c>NodeScopeResolver</c>'s Config-DB join.
+///     </para>
+/// </remarks>
+public static class EquipmentNodeWalker
+{
+    /// <summary>
+    ///     Walk <paramref name="content"/> into <paramref name="namespaceBuilder"/>.
+    ///     The builder is scoped to the Equipment-kind namespace root; the walker emits
+    ///     Area → Line → Equipment folders under it, then identifier properties + the
+    ///     Identification sub-folder + variable nodes per bound Tag under each Equipment.
+    /// </summary>
+    /// <param name="namespaceBuilder">
+    ///     The builder scoped to the Equipment-kind namespace root. Caller is responsible for
+    ///     creating this (e.g. <c>rootBuilder.Folder(namespace.NamespaceId, namespace.NamespaceUri)</c>).
+    /// </param>
+    /// <param name="content">Pre-loaded + pre-filtered rows for a single published generation.</param>
+    public static void Walk(IAddressSpaceBuilder namespaceBuilder, EquipmentNamespaceContent content)
+    {
+        ArgumentNullException.ThrowIfNull(namespaceBuilder);
+        ArgumentNullException.ThrowIfNull(content);
+
+        // Group lines by area + equipment by line + tags by equipment up-front. Avoids an
+        // O(N·M) re-scan at each UNS level on large fleets.
+        var linesByArea = content.Lines
+            .GroupBy(l => l.UnsAreaId, StringComparer.OrdinalIgnoreCase)
+            .ToDictionary(g => g.Key, g => g.OrderBy(l => l.Name, StringComparer.Ordinal).ToList(), StringComparer.OrdinalIgnoreCase);
+
+        var equipmentByLine = content.Equipment
+            .GroupBy(e => e.UnsLineId, StringComparer.OrdinalIgnoreCase)
+            .ToDictionary(g => g.Key, g => g.OrderBy(e => e.Name, StringComparer.Ordinal).ToList(), StringComparer.OrdinalIgnoreCase);
+
+        var tagsByEquipment = content.Tags
+            .Where(t => !string.IsNullOrEmpty(t.EquipmentId))
+            .GroupBy(t => t.EquipmentId!, StringComparer.OrdinalIgnoreCase)
+            .ToDictionary(g => g.Key, g => g.OrderBy(t => t.Name, StringComparer.Ordinal).ToList(), StringComparer.OrdinalIgnoreCase);
+
+        foreach (var area in content.Areas.OrderBy(a => a.Name, StringComparer.Ordinal))
+        {
+            var areaBuilder = namespaceBuilder.Folder(area.Name, area.Name);
+            if (!linesByArea.TryGetValue(area.UnsAreaId, out var areaLines)) continue;
+
+            foreach (var line in areaLines)
+            {
+                var lineBuilder = areaBuilder.Folder(line.Name, line.Name);
+                if (!equipmentByLine.TryGetValue(line.UnsLineId, out var lineEquipment)) continue;
+
+                foreach (var equipment in lineEquipment)
+                {
+                    var equipmentBuilder = lineBuilder.Folder(equipment.Name, equipment.Name);
+                    AddIdentifierProperties(equipmentBuilder, equipment);
+                    IdentificationFolderBuilder.Build(equipmentBuilder, equipment);
+
+                    if (!tagsByEquipment.TryGetValue(equipment.EquipmentId, out var equipmentTags)) continue;
+                    foreach (var tag in equipmentTags)
+                        AddTagVariable(equipmentBuilder, tag);
+                }
+            }
+        }
+    }
+
+    /// <summary>
+    ///     Adds the five operator-facing identifiers from decision #121 as OPC UA properties
+    ///     on the Equipment node. EquipmentId + EquipmentUuid are always populated;
+    ///     MachineCode is required per <see cref="Equipment"/>; ZTag + SAPID are nullable in
+    ///     the data model so they're skipped when null to avoid empty-string noise in the
+    ///     browse tree.
+    /// </summary>
+    private static void AddIdentifierProperties(IAddressSpaceBuilder equipmentBuilder, Equipment equipment)
+    {
+        equipmentBuilder.AddProperty("EquipmentId", DriverDataType.String, equipment.EquipmentId);
+        equipmentBuilder.AddProperty("EquipmentUuid", DriverDataType.String, equipment.EquipmentUuid.ToString());
+        equipmentBuilder.AddProperty("MachineCode", DriverDataType.String, equipment.MachineCode);
+        if (!string.IsNullOrEmpty(equipment.ZTag))
+            equipmentBuilder.AddProperty("ZTag", DriverDataType.String, equipment.ZTag);
+        if (!string.IsNullOrEmpty(equipment.SAPID))
+            equipmentBuilder.AddProperty("SAPID", DriverDataType.String, equipment.SAPID);
+    }
+
+    /// <summary>
+    ///     Emit a single Tag row as an <see cref="IAddressSpaceBuilder.Variable"/>. The driver
+    ///     full reference lives in <c>Tag.TagConfig</c> (wire-level address, driver-specific
+    ///     JSON blob); the variable node's data type derives from <c>Tag.DataType</c>.
+    ///     Unreachable-address behavior per ADR-001 Option A: the variable is created; the
+    ///     driver's natural Read failure surfaces an OPC UA Bad status at runtime.
+    /// </summary>
+    private static void AddTagVariable(IAddressSpaceBuilder equipmentBuilder, Tag tag)
+    {
+        var attr = new DriverAttributeInfo(
+            FullName: tag.TagConfig,
+            DriverDataType: ParseDriverDataType(tag.DataType),
+            IsArray: false,
+            ArrayDim: null,
+            SecurityClass: SecurityClassification.FreeAccess,
+            IsHistorized: false);
+        equipmentBuilder.Variable(tag.Name, tag.Name, attr);
+    }
+
+    /// <summary>
+    ///     Parse <see cref="Tag.DataType"/> (stored as the <see cref="DriverDataType"/> enum
+    ///     name string, decision #138) into the enum value. Unknown names fall back to
+    ///     <see cref="DriverDataType.String"/> so a one-off driver-specific type doesn't
+    ///     abort the whole walk; the underlying driver still sees the original TagConfig
+    ///     address + can surface its own typed value via the OPC UA variant at read time.
+    /// </summary>
+    private static DriverDataType ParseDriverDataType(string raw) =>
+        Enum.TryParse<DriverDataType>(raw, ignoreCase: true, out var parsed) ? parsed : DriverDataType.String;
+}
+
+/// <summary>
+///     Pre-loaded + pre-filtered snapshot of one Equipment-kind namespace's worth of Config
+///     DB rows. All four collections are scoped to the same
+///     <see cref="Configuration.Entities.ConfigGeneration"/> + the same
+///     <see cref="Configuration.Entities.Namespace"/> row. The walker assumes this filter
+///     was applied by the caller + does no cross-generation or cross-namespace validation.
+/// </summary>
+public sealed record EquipmentNamespaceContent(
+    IReadOnlyList<UnsArea> Areas,
+    IReadOnlyList<UnsLine> Lines,
+    IReadOnlyList<Equipment> Equipment,
+    IReadOnlyList<Tag> Tags);

src/ZB.MOM.WW.OtOpcUa.Driver.AbCip/AbCipAlarmProjection.cs

@@ -0,0 +1,232 @@
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.AbCip;
+
+/// <summary>
+///     Task #177 — projects AB Logix ALMD alarm instructions onto the OPC UA alarm surface by
+///     polling the ALMD UDT's <c>InFaulted</c> / <c>Acked</c> / <c>Severity</c> members at a
+///     configurable interval + translating state transitions into <c>OnAlarmEvent</c>
+///     callbacks on the owning <see cref="AbCipDriver"/>. Feature-flagged off by default via
+///     <see cref="AbCipDriverOptions.EnableAlarmProjection"/>; callers that leave the flag off
+///     get a no-op subscribe path so capability negotiation still works.
+/// </summary>
+/// <remarks>
+///     <para>ALMD-only in this pass. ALMA (analog alarm) projection is a follow-up because
+///     its threshold + limit semantics need more design — ALMD's "is the alarm active + has
+///     the operator acked" shape maps cleanly onto the driver-agnostic
+///     <see cref="IAlarmSource"/> contract without concessions.</para>
+///
+///     <para>Polling reuses <see cref="AbCipDriver.ReadAsync"/>, so ALMD reads get the #194
+///     whole-UDT optimization for free when the ALMD is declared with its standard members.
+///     One poll loop per subscription call; the loop batches every
+///     member read across the full source-node set into a single ReadAsync per tick.</para>
+///
+///     <para>ALMD <c>Acked</c> write semantics on Logix are rising-edge sensitive at the
+///     instruction level — writing <c>Acked=1</c> directly is honored by FT View + the
+///     standard HMI templates, but some PLC programs read <c>AckCmd</c> + look for the edge
+///     themselves. We pick the simpler <c>Acked</c> write for first pass; operators whose
+///     ladder watches <c>AckCmd</c> can wire a follow-up "AckCmd 0→1→0" pulse on the client
+///     side until a driver-level knob lands.</para>
+/// </remarks>
+internal sealed class AbCipAlarmProjection : IAsyncDisposable
+{
+    private readonly AbCipDriver _driver;
+    private readonly TimeSpan _pollInterval;
+    private readonly Dictionary<long, Subscription> _subs = new();
+    private readonly Lock _subsLock = new();
+    private long _nextId;
+
+    public AbCipAlarmProjection(AbCipDriver driver, TimeSpan pollInterval)
+    {
+        _driver = driver;
+        _pollInterval = pollInterval;
+    }
+
+    public async Task<IAlarmSubscriptionHandle> SubscribeAsync(
+        IReadOnlyList<string> sourceNodeIds, CancellationToken cancellationToken)
+    {
+        var id = Interlocked.Increment(ref _nextId);
+        var handle = new AbCipAlarmSubscriptionHandle(id);
+        var cts = new CancellationTokenSource();
+        var sub = new Subscription(handle, [..sourceNodeIds], cts);
+
+        lock (_subsLock) _subs[id] = sub;
+
+        sub.Loop = Task.Run(() => RunPollLoopAsync(sub, cts.Token), cts.Token);
+        await Task.CompletedTask;
+        return handle;
+    }
+
+    public async Task UnsubscribeAsync(IAlarmSubscriptionHandle handle, CancellationToken cancellationToken)
+    {
+        if (handle is not AbCipAlarmSubscriptionHandle h) return;
+        Subscription? sub;
+        lock (_subsLock)
+        {
+            if (!_subs.Remove(h.Id, out sub)) return;
+        }
+        try { sub.Cts.Cancel(); } catch { }
+        try { await sub.Loop.ConfigureAwait(false); } catch { }
+        sub.Cts.Dispose();
+    }
+
+    public async Task AcknowledgeAsync(
+        IReadOnlyList<AlarmAcknowledgeRequest> acknowledgements, CancellationToken cancellationToken)
+    {
+        if (acknowledgements.Count == 0) return;
+
+        // Write Acked=1 per request. IWritable isn't on AbCipAlarmProjection so route through
+        // the driver's public interface — delegating instead of re-implementing the write path
+        // keeps the bit-in-DINT + idempotency + per-call-host-resolve knobs intact.
+        var requests = acknowledgements
+            .Select(a => new WriteRequest($"{a.SourceNodeId}.Acked", true))
+            .ToArray();
+        // Best-effort — the driver's WriteAsync returns per-item status; individual ack
+        // failures don't poison the batch. Swallow the return so a single faulted ack
+        // doesn't bubble out of the caller's batch expectation.
+        _ = await _driver.WriteAsync(requests, cancellationToken).ConfigureAwait(false);
+    }
+
+    public async ValueTask DisposeAsync()
+    {
+        List<Subscription> snap;
+        lock (_subsLock) { snap = _subs.Values.ToList(); _subs.Clear(); }
+        foreach (var sub in snap)
+        {
+            try { sub.Cts.Cancel(); } catch { }
+            try { await sub.Loop.ConfigureAwait(false); } catch { }
+            sub.Cts.Dispose();
+        }
+    }
+
+    /// <summary>
+    ///     Poll-tick body — reads <c>InFaulted</c> + <c>Severity</c> for every source node id
+    ///     in the subscription, diffs each against last-seen state, fires raise/clear events.
+    ///     Extracted so tests can drive one tick without standing up the Task.Run loop.
+    /// </summary>
+    internal void Tick(Subscription sub, IReadOnlyList<DataValueSnapshot> results)
+    {
+        // results index layout: for each sourceNode, [InFaulted, Severity] in order.
+        for (var i = 0; i < sub.SourceNodeIds.Count; i++)
+        {
+            var nodeId = sub.SourceNodeIds[i];
+            var inFaultedDv = results[i * 2];
+            var severityDv = results[i * 2 + 1];
+            if (inFaultedDv.StatusCode != AbCipStatusMapper.Good) continue;
+
+            var nowFaulted = ToBool(inFaultedDv.Value);
+            var severity = ToInt(severityDv.Value);
+
+            var wasFaulted = sub.LastInFaulted.GetValueOrDefault(nodeId, false);
+            sub.LastInFaulted[nodeId] = nowFaulted;
+
+            if (!wasFaulted && nowFaulted)
+            {
+                _driver.InvokeAlarmEvent(new AlarmEventArgs(
+                    sub.Handle, nodeId, ConditionId: $"{nodeId}#active",
+                    AlarmType: "ALMD",
+                    Message: $"ALMD {nodeId} raised",
+                    Severity: MapSeverity(severity),
+                    SourceTimestampUtc: DateTime.UtcNow));
+            }
+            else if (wasFaulted && !nowFaulted)
+            {
+                _driver.InvokeAlarmEvent(new AlarmEventArgs(
+                    sub.Handle, nodeId, ConditionId: $"{nodeId}#active",
+                    AlarmType: "ALMD",
+                    Message: $"ALMD {nodeId} cleared",
+                    Severity: MapSeverity(severity),
+                    SourceTimestampUtc: DateTime.UtcNow));
+            }
+        }
+    }
+
+    private async Task RunPollLoopAsync(Subscription sub, CancellationToken ct)
+    {
+        var refs = new List<string>(sub.SourceNodeIds.Count * 2);
+        foreach (var nodeId in sub.SourceNodeIds)
+        {
+            refs.Add($"{nodeId}.InFaulted");
+            refs.Add($"{nodeId}.Severity");
+        }
+
+        while (!ct.IsCancellationRequested)
+        {
+            try
+            {
+                var results = await _driver.ReadAsync(refs, ct).ConfigureAwait(false);
+                Tick(sub, results);
+            }
+            catch (OperationCanceledException) when (ct.IsCancellationRequested) { break; }
+            catch { /* per-tick failures are non-fatal; next tick retries */ }
+
+            try { await Task.Delay(_pollInterval, ct).ConfigureAwait(false); }
+            catch (OperationCanceledException) { break; }
+        }
+    }
+
+    internal static AlarmSeverity MapSeverity(int raw) => raw switch
+    {
+        <= 250 => AlarmSeverity.Low,
+        <= 500 => AlarmSeverity.Medium,
+        <= 750 => AlarmSeverity.High,
+        _ => AlarmSeverity.Critical,
+    };
+
+    private static bool ToBool(object? v) => v switch
+    {
+        bool b => b,
+        int i => i != 0,
+        long l => l != 0,
+        _ => false,
+    };
+
+    private static int ToInt(object? v) => v switch
+    {
+        int i => i,
+        long l => (int)l,
+        short s => s,
+        byte b => b,
+        _ => 0,
+    };
+
+    internal sealed class Subscription
+    {
+        public Subscription(AbCipAlarmSubscriptionHandle handle, IReadOnlyList<string> sourceNodeIds, CancellationTokenSource cts)
+        {
+            Handle = handle; SourceNodeIds = sourceNodeIds; Cts = cts;
+        }
+        public AbCipAlarmSubscriptionHandle Handle { get; }
+        public IReadOnlyList<string> SourceNodeIds { get; }
+        public CancellationTokenSource Cts { get; }
+        public Task Loop { get; set; } = Task.CompletedTask;
+        public Dictionary<string, bool> LastInFaulted { get; } = new(StringComparer.Ordinal);
+    }
+}
+
+/// <summary>Handle returned by <see cref="AbCipAlarmProjection.SubscribeAsync"/>.</summary>
+public sealed record AbCipAlarmSubscriptionHandle(long Id) : IAlarmSubscriptionHandle
+{
+    public string DiagnosticId => $"abcip-alarm-sub-{Id}";
+}
+
+/// <summary>
+///     Detects the ALMD / ALMA signature in an <see cref="AbCipTagDefinition"/>'s declared
+///     members. Used by both discovery (to stamp <c>IsAlarm=true</c> on the emitted
+///     variable) + initial driver setup (to decide which tags the alarm projection owns).
+/// </summary>
+public static class AbCipAlarmDetector
+{
+    /// <summary>
+    ///     <c>true</c> when <paramref name="tag"/> is a Structure whose declared members match
+    ///     the ALMD signature (<c>InFaulted</c> + <c>Acked</c> present). ALMA detection
+    ///     (analog alarms with <c>HHLimit</c>/<c>HLimit</c>/<c>LLimit</c>/<c>LLLimit</c>)
+    ///     ships as a follow-up.
+    /// </summary>
+    public static bool IsAlmd(AbCipTagDefinition tag)
+    {
+        if (tag.DataType != AbCipDataType.Structure || tag.Members is null) return false;
+        var names = tag.Members.Select(m => m.Name).ToHashSet(StringComparer.OrdinalIgnoreCase);
+        return names.Contains("InFaulted") && names.Contains("Acked");
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Driver.AbCip/AbCipDriver.cs

@@ -21,7 +21,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.AbCip;
 ///     <see cref="PlcTagHandle"/> and reconnects each device.</para>
 /// </remarks>
 public sealed class AbCipDriver : IDriver, IReadable, IWritable, ITagDiscovery, ISubscribable,
-    IHostConnectivityProbe, IPerCallHostResolver, IDisposable, IAsyncDisposable
+    IHostConnectivityProbe, IPerCallHostResolver, IAlarmSource, IDisposable, IAsyncDisposable
 {
     private readonly AbCipDriverOptions _options;
     private readonly string _driverInstanceId;
@@ -32,10 +32,15 @@ public sealed class AbCipDriver : IDriver, IReadable, IWritable, ITagDiscovery,
     private readonly PollGroupEngine _poll;
     private readonly Dictionary<string, DeviceState> _devices = new(StringComparer.OrdinalIgnoreCase);
     private readonly Dictionary<string, AbCipTagDefinition> _tagsByName = new(StringComparer.OrdinalIgnoreCase);
+    private readonly AbCipAlarmProjection _alarmProjection;
     private DriverHealth _health = new(DriverState.Unknown, null, null);
 
     public event EventHandler<DataChangeEventArgs>? OnDataChange;
     public event EventHandler<HostStatusChangedEventArgs>? OnHostStatusChanged;
+    public event EventHandler<AlarmEventArgs>? OnAlarmEvent;
+
+    /// <summary>Internal seam for the alarm projection to raise events through the driver.</summary>
+    internal void InvokeAlarmEvent(AlarmEventArgs args) => OnAlarmEvent?.Invoke(this, args);
 
     public AbCipDriver(AbCipDriverOptions options, string driverInstanceId,
         IAbCipTagFactory? tagFactory = null,
@@ -52,6 +57,7 @@ public sealed class AbCipDriver : IDriver, IReadable, IWritable, ITagDiscovery,
             reader: ReadAsync,
             onChange: (handle, tagRef, snapshot) =>
                 OnDataChange?.Invoke(this, new DataChangeEventArgs(handle, tagRef, snapshot)));
+        _alarmProjection = new AbCipAlarmProjection(this, _options.AlarmPollInterval);
     }
 
     /// <summary>
@@ -162,6 +168,7 @@ public sealed class AbCipDriver : IDriver, IReadable, IWritable, ITagDiscovery,
 
     public async Task ShutdownAsync(CancellationToken cancellationToken)
     {
+        await _alarmProjection.DisposeAsync().ConfigureAwait(false);
         await _poll.DisposeAsync().ConfigureAwait(false);
         foreach (var state in _devices.Values)
         {
@@ -187,6 +194,39 @@ public sealed class AbCipDriver : IDriver, IReadable, IWritable, ITagDiscovery,
         return Task.CompletedTask;
     }
 
+    // ---- IAlarmSource (ALMD projection, #177) ----
+
+    /// <summary>
+    ///     Subscribe to ALMD alarm transitions on <paramref name="sourceNodeIds"/>. Each id
+    ///     names a declared ALMD UDT tag; the projection polls the tag's <c>InFaulted</c> +
+    ///     <c>Severity</c> members at <see cref="AbCipDriverOptions.AlarmPollInterval"/> and
+    ///     fires <see cref="OnAlarmEvent"/> on 0→1 (raise) + 1→0 (clear) transitions.
+    ///     Feature-gated — when <see cref="AbCipDriverOptions.EnableAlarmProjection"/> is
+    ///     <c>false</c> (the default), returns a handle wrapping a no-op subscription so
+    ///     capability negotiation still works; <see cref="OnAlarmEvent"/> never fires.
+    /// </summary>
+    public Task<IAlarmSubscriptionHandle> SubscribeAlarmsAsync(
+        IReadOnlyList<string> sourceNodeIds, CancellationToken cancellationToken)
+    {
+        if (!_options.EnableAlarmProjection)
+        {
+            var disabled = new AbCipAlarmSubscriptionHandle(0);
+            return Task.FromResult<IAlarmSubscriptionHandle>(disabled);
+        }
+        return _alarmProjection.SubscribeAsync(sourceNodeIds, cancellationToken);
+    }
+
+    public Task UnsubscribeAlarmsAsync(IAlarmSubscriptionHandle handle, CancellationToken cancellationToken) =>
+        _options.EnableAlarmProjection
+            ? _alarmProjection.UnsubscribeAsync(handle, cancellationToken)
+            : Task.CompletedTask;
+
+    public Task AcknowledgeAsync(
+        IReadOnlyList<AlarmAcknowledgeRequest> acknowledgements, CancellationToken cancellationToken) =>
+        _options.EnableAlarmProjection
+            ? _alarmProjection.AcknowledgeAsync(acknowledgements, cancellationToken)
+            : Task.CompletedTask;
+
     // ---- IHostConnectivityProbe ----
 
     public IReadOnlyList<HostConnectivityStatus> GetHostStatuses() =>
@@ -287,56 +327,127 @@ public sealed class AbCipDriver : IDriver, IReadable, IWritable, ITagDiscovery,
         var now = DateTime.UtcNow;
         var results = new DataValueSnapshot[fullReferences.Count];
 
-        for (var i = 0; i < fullReferences.Count; i++)
-        {
-            var reference = fullReferences[i];
-            if (!_tagsByName.TryGetValue(reference, out var def))
-            {
-                results[i] = new DataValueSnapshot(null, AbCipStatusMapper.BadNodeIdUnknown, null, now);
-                continue;
-            }
-            if (!_devices.TryGetValue(def.DeviceHostAddress, out var device))
-            {
-                results[i] = new DataValueSnapshot(null, AbCipStatusMapper.BadNodeIdUnknown, null, now);
-                continue;
-            }
+        // Task #194 — plan the batch: members of the same parent UDT get collapsed into one
+        // whole-UDT read + in-memory member decode; every other reference falls back to the
+        // per-tag path that's been here since PR 3. Planner is a pure function over the
+        // current tag map; BOOL/String/Structure members stay on the fallback path because
+        // declaration-only offsets can't place them under Logix alignment rules.
+        var plan = AbCipUdtReadPlanner.Build(fullReferences, _tagsByName);
 
-            try
-            {
-                var runtime = await EnsureTagRuntimeAsync(device, def, cancellationToken).ConfigureAwait(false);
-                await runtime.ReadAsync(cancellationToken).ConfigureAwait(false);
+        foreach (var group in plan.Groups)
+            await ReadGroupAsync(group, results, now, cancellationToken).ConfigureAwait(false);
 
-                var status = runtime.GetStatus();
-                if (status != 0)
-                {
-                    results[i] = new DataValueSnapshot(null,
-                        AbCipStatusMapper.MapLibplctagStatus(status), null, now);
-                    _health = new DriverHealth(DriverState.Degraded, _health.LastSuccessfulRead,
-                        $"libplctag status {status} reading {reference}");
-                    continue;
-                }
-
-                var tagPath = AbCipTagPath.TryParse(def.TagPath);
-                var bitIndex = tagPath?.BitIndex;
-                var value = runtime.DecodeValue(def.DataType, bitIndex);
-                results[i] = new DataValueSnapshot(value, AbCipStatusMapper.Good, now, now);
-                _health = new DriverHealth(DriverState.Healthy, now, null);
-            }
-            catch (OperationCanceledException)
-            {
-                throw;
-            }
-            catch (Exception ex)
-            {
-                results[i] = new DataValueSnapshot(null,
-                    AbCipStatusMapper.BadCommunicationError, null, now);
-                _health = new DriverHealth(DriverState.Degraded, _health.LastSuccessfulRead, ex.Message);
-            }
-        }
+        foreach (var fb in plan.Fallbacks)
+            await ReadSingleAsync(fb, fullReferences[fb.OriginalIndex], results, now, cancellationToken).ConfigureAwait(false);
 
         return results;
     }
 
+    private async Task ReadSingleAsync(
+        AbCipUdtReadFallback fb, string reference, DataValueSnapshot[] results, DateTime now, CancellationToken ct)
+    {
+        if (!_tagsByName.TryGetValue(reference, out var def))
+        {
+            results[fb.OriginalIndex] = new DataValueSnapshot(null, AbCipStatusMapper.BadNodeIdUnknown, null, now);
+            return;
+        }
+        if (!_devices.TryGetValue(def.DeviceHostAddress, out var device))
+        {
+            results[fb.OriginalIndex] = new DataValueSnapshot(null, AbCipStatusMapper.BadNodeIdUnknown, null, now);
+            return;
+        }
+
+        try
+        {
+            var runtime = await EnsureTagRuntimeAsync(device, def, ct).ConfigureAwait(false);
+            await runtime.ReadAsync(ct).ConfigureAwait(false);
+
+            var status = runtime.GetStatus();
+            if (status != 0)
+            {
+                results[fb.OriginalIndex] = new DataValueSnapshot(null,
+                    AbCipStatusMapper.MapLibplctagStatus(status), null, now);
+                _health = new DriverHealth(DriverState.Degraded, _health.LastSuccessfulRead,
+                    $"libplctag status {status} reading {reference}");
+                return;
+            }
+
+            var tagPath = AbCipTagPath.TryParse(def.TagPath);
+            var bitIndex = tagPath?.BitIndex;
+            var value = runtime.DecodeValue(def.DataType, bitIndex);
+            results[fb.OriginalIndex] = new DataValueSnapshot(value, AbCipStatusMapper.Good, now, now);
+            _health = new DriverHealth(DriverState.Healthy, now, null);
+        }
+        catch (OperationCanceledException)
+        {
+            throw;
+        }
+        catch (Exception ex)
+        {
+            results[fb.OriginalIndex] = new DataValueSnapshot(null,
+                AbCipStatusMapper.BadCommunicationError, null, now);
+            _health = new DriverHealth(DriverState.Degraded, _health.LastSuccessfulRead, ex.Message);
+        }
+    }
+
+    /// <summary>
+    ///     Task #194 — perform one whole-UDT read on the parent tag, then decode each
+    ///     grouped member from the runtime's buffer at its computed byte offset. A per-group
+    ///     failure (parent read raised, non-zero libplctag status, or missing device) stamps
+    ///     the mapped fault across every grouped member only — sibling groups + the
+    ///     per-tag fallback list are unaffected.
+    /// </summary>
+    private async Task ReadGroupAsync(
+        AbCipUdtReadGroup group, DataValueSnapshot[] results, DateTime now, CancellationToken ct)
+    {
+        var parent = group.ParentDefinition;
+
+        if (!_devices.TryGetValue(parent.DeviceHostAddress, out var device))
+        {
+            StampGroupStatus(group, results, now, AbCipStatusMapper.BadNodeIdUnknown);
+            return;
+        }
+
+        try
+        {
+            var runtime = await EnsureTagRuntimeAsync(device, parent, ct).ConfigureAwait(false);
+            await runtime.ReadAsync(ct).ConfigureAwait(false);
+
+            var status = runtime.GetStatus();
+            if (status != 0)
+            {
+                var mapped = AbCipStatusMapper.MapLibplctagStatus(status);
+                StampGroupStatus(group, results, now, mapped);
+                _health = new DriverHealth(DriverState.Degraded, _health.LastSuccessfulRead,
+                    $"libplctag status {status} reading UDT {group.ParentName}");
+                return;
+            }
+
+            foreach (var member in group.Members)
+            {
+                var value = runtime.DecodeValueAt(member.Definition.DataType, member.Offset, bitIndex: null);
+                results[member.OriginalIndex] = new DataValueSnapshot(value, AbCipStatusMapper.Good, now, now);
+            }
+            _health = new DriverHealth(DriverState.Healthy, now, null);
+        }
+        catch (OperationCanceledException)
+        {
+            throw;
+        }
+        catch (Exception ex)
+        {
+            StampGroupStatus(group, results, now, AbCipStatusMapper.BadCommunicationError);
+            _health = new DriverHealth(DriverState.Degraded, _health.LastSuccessfulRead, ex.Message);
+        }
+    }
+
+    private static void StampGroupStatus(
+        AbCipUdtReadGroup group, DataValueSnapshot[] results, DateTime now, uint statusCode)
+    {
+        foreach (var member in group.Members)
+            results[member.OriginalIndex] = new DataValueSnapshot(null, statusCode, null, now);
+    }
+
     // ---- IWritable ----
 
     /// <summary>

src/ZB.MOM.WW.OtOpcUa.Driver.AbCip/AbCipDriverOptions.cs

@@ -38,6 +38,24 @@ public sealed class AbCipDriverOptions
     ///     should appear in the address space.
     /// </summary>
     public bool EnableControllerBrowse { get; init; }
+
+    /// <summary>
+    ///     Task #177 — when <c>true</c>, declared ALMD tags are surfaced as alarm conditions
+    ///     via <see cref="Core.Abstractions.IAlarmSource"/>; the driver polls each subscribed
+    ///     alarm's <c>InFaulted</c> + <c>Severity</c> members + fires <c>OnAlarmEvent</c> on
+    ///     state transitions. Default <c>false</c> — operators explicitly opt in because
+    ///     projection semantics don't exactly mirror Rockwell FT Alarm &amp; Events; shops
+    ///     running FT Live should keep this off + take alarms through the native route.
+    /// </summary>
+    public bool EnableAlarmProjection { get; init; }
+
+    /// <summary>
+    ///     Poll interval for the ALMD projection loop. Shorter intervals catch faster edges
+    ///     at the cost of PLC round-trips; edges shorter than this interval are invisible to
+    ///     the projection (a 0→1→0 transition within one tick collapses to no event). Default
+    ///     1 second — matches typical SCADA alarm-refresh conventions.
+    /// </summary>
+    public TimeSpan AlarmPollInterval { get; init; } = TimeSpan.FromSeconds(1);
 }
 
 /// <summary>

src/ZB.MOM.WW.OtOpcUa.Driver.AbCip/AbCipUdtMemberLayout.cs

@@ -0,0 +1,78 @@
+namespace ZB.MOM.WW.OtOpcUa.Driver.AbCip;
+
+/// <summary>
+///     Computes byte offsets for declared UDT members under Logix natural-alignment rules so
+///     a single whole-UDT read (task #194) can decode each member from one buffer without
+///     re-reading per member. Declaration-driven — the caller supplies
+///     <see cref="AbCipStructureMember"/> rows; this helper produces the offset each member
+///     sits at in the parent tag's read buffer.
+/// </summary>
+/// <remarks>
+///     <para>Alignment rules applied per Rockwell "Logix 5000 Data Access" manual + the
+///     libplctag test fixtures: each member aligns to its natural boundary (SInt 1, Int 2,
+///     DInt/Real/Dt 4, LInt/ULInt/LReal 8), padding inserted before the member as needed.
+///     The total size is padded to the alignment of the largest member so arrays-of-UDT also
+///     work at element stride — though this helper is used only on single instances today.</para>
+///
+///     <para><see cref="TryBuild"/> returns <c>null</c> on unsupported member types
+///     (<see cref="AbCipDataType.Bool"/>, <see cref="AbCipDataType.String"/>,
+///     <see cref="AbCipDataType.Structure"/>). Whole-UDT grouping opts out of those groups
+///     and falls back to the per-tag read path — BOOL members are packed into a hidden host
+///     byte at the top of the UDT under Logix, so their offset can't be computed from
+///     declared-member order alone. The CIP Template Object reader produces a
+///     <see cref="AbCipUdtShape"/> that carries real offsets for BOOL + nested structs; when
+///     that shape is cached the driver can take the richer path instead.</para>
+/// </remarks>
+public static class AbCipUdtMemberLayout
+{
+    /// <summary>
+    ///     Try to compute member offsets for the supplied declared members. Returns <c>null</c>
+    ///     if any member type is unsupported for declaration-only layout.
+    /// </summary>
+    public static IReadOnlyDictionary<string, int>? TryBuild(
+        IReadOnlyList<AbCipStructureMember> members)
+    {
+        ArgumentNullException.ThrowIfNull(members);
+        if (members.Count == 0) return null;
+
+        var offsets = new Dictionary<string, int>(members.Count, StringComparer.OrdinalIgnoreCase);
+        var cursor = 0;
+
+        foreach (var member in members)
+        {
+            if (!TryGetSizeAlign(member.DataType, out var size, out var align))
+                return null;
+
+            if (cursor % align != 0)
+                cursor += align - (cursor % align);
+
+            offsets[member.Name] = cursor;
+            cursor += size;
+        }
+
+        return offsets;
+    }
+
+    /// <summary>
+    ///     Natural size + alignment for a Logix atomic type. <c>false</c> for types excluded
+    ///     from declaration-only grouping (Bool / String / Structure).
+    /// </summary>
+    private static bool TryGetSizeAlign(AbCipDataType type, out int size, out int align)
+    {
+        switch (type)
+        {
+            case AbCipDataType.SInt: case AbCipDataType.USInt:
+                size = 1; align = 1; return true;
+            case AbCipDataType.Int: case AbCipDataType.UInt:
+                size = 2; align = 2; return true;
+            case AbCipDataType.DInt: case AbCipDataType.UDInt:
+            case AbCipDataType.Real: case AbCipDataType.Dt:
+                size = 4; align = 4; return true;
+            case AbCipDataType.LInt: case AbCipDataType.ULInt:
+            case AbCipDataType.LReal:
+                size = 8; align = 8; return true;
+            default:
+                size = 0; align = 0; return false;
+        }
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Driver.AbCip/AbCipUdtReadPlanner.cs

@@ -0,0 +1,109 @@
+namespace ZB.MOM.WW.OtOpcUa.Driver.AbCip;
+
+/// <summary>
+///     Task #194 — groups a ReadAsync batch of full-references into whole-UDT reads where
+///     possible. A group is emitted for every parent UDT tag whose declared
+///     <see cref="AbCipStructureMember"/>s produced a valid offset map AND at least two of
+///     its members appear in the batch; every other reference stays in the per-tag fallback
+///     list that <see cref="AbCipDriver.ReadAsync"/> runs through its existing read path.
+///     Pure function — the planner never touches the runtime + never reads the PLC.
+/// </summary>
+public static class AbCipUdtReadPlanner
+{
+    /// <summary>
+    ///     Split <paramref name="requests"/> into whole-UDT groups + per-tag leftovers.
+    ///     <paramref name="tagsByName"/> is the driver's <c>_tagsByName</c> map — both parent
+    ///     UDT rows and their fanned-out member rows live there. Lookup is OrdinalIgnoreCase
+    ///     to match the driver's dictionary semantics.
+    /// </summary>
+    public static AbCipUdtReadPlan Build(
+        IReadOnlyList<string> requests,
+        IReadOnlyDictionary<string, AbCipTagDefinition> tagsByName)
+    {
+        ArgumentNullException.ThrowIfNull(requests);
+        ArgumentNullException.ThrowIfNull(tagsByName);
+
+        var fallback = new List<AbCipUdtReadFallback>(requests.Count);
+        var byParent = new Dictionary<string, List<AbCipUdtReadMember>>(StringComparer.OrdinalIgnoreCase);
+
+        for (var i = 0; i < requests.Count; i++)
+        {
+            var name = requests[i];
+            if (!tagsByName.TryGetValue(name, out var def))
+            {
+                fallback.Add(new AbCipUdtReadFallback(i, name));
+                continue;
+            }
+
+            var (parentName, memberName) = SplitParentMember(name);
+            if (parentName is null || memberName is null
+                || !tagsByName.TryGetValue(parentName, out var parent)
+                || parent.DataType != AbCipDataType.Structure
+                || parent.Members is not { Count: > 0 })
+            {
+                fallback.Add(new AbCipUdtReadFallback(i, name));
+                continue;
+            }
+
+            var offsets = AbCipUdtMemberLayout.TryBuild(parent.Members);
+            if (offsets is null || !offsets.TryGetValue(memberName, out var offset))
+            {
+                fallback.Add(new AbCipUdtReadFallback(i, name));
+                continue;
+            }
+
+            if (!byParent.TryGetValue(parentName, out var members))
+            {
+                members = new List<AbCipUdtReadMember>();
+                byParent[parentName] = members;
+            }
+            members.Add(new AbCipUdtReadMember(i, def, offset));
+        }
+
+        // A single-member group saves nothing (one whole-UDT read replaces one per-member read)
+        // — demote to fallback to avoid paying the cost of reading the full UDT buffer only to
+        // pull one field out.
+        var groups = new List<AbCipUdtReadGroup>(byParent.Count);
+        foreach (var (parentName, members) in byParent)
+        {
+            if (members.Count < 2)
+            {
+                foreach (var m in members)
+                    fallback.Add(new AbCipUdtReadFallback(m.OriginalIndex, m.Definition.Name));
+                continue;
+            }
+            groups.Add(new AbCipUdtReadGroup(parentName, tagsByName[parentName], members));
+        }
+
+        return new AbCipUdtReadPlan(groups, fallback);
+    }
+
+    private static (string? Parent, string? Member) SplitParentMember(string reference)
+    {
+        var dot = reference.IndexOf('.');
+        if (dot <= 0 || dot == reference.Length - 1) return (null, null);
+        return (reference[..dot], reference[(dot + 1)..]);
+    }
+}
+
+/// <summary>A planner output: grouped UDT reads + per-tag fallbacks.</summary>
+public sealed record AbCipUdtReadPlan(
+    IReadOnlyList<AbCipUdtReadGroup> Groups,
+    IReadOnlyList<AbCipUdtReadFallback> Fallbacks);
+
+/// <summary>One UDT parent whose members were batched into a single read.</summary>
+public sealed record AbCipUdtReadGroup(
+    string ParentName,
+    AbCipTagDefinition ParentDefinition,
+    IReadOnlyList<AbCipUdtReadMember> Members);
+
+/// <summary>
+///     One member inside an <see cref="AbCipUdtReadGroup"/>. <c>OriginalIndex</c> is the
+///     slot in the caller's request list so the decoded value lands at the correct output
+///     offset. <c>Definition</c> is the fanned-out member-level tag definition. <c>Offset</c>
+///     is the byte offset within the parent UDT buffer where this member lives.
+/// </summary>
+public sealed record AbCipUdtReadMember(int OriginalIndex, AbCipTagDefinition Definition, int Offset);
+
+/// <summary>A reference that falls back to the per-tag read path.</summary>
+public sealed record AbCipUdtReadFallback(int OriginalIndex, string Reference);

src/ZB.MOM.WW.OtOpcUa.Driver.AbCip/IAbCipTagRuntime.cs

@@ -31,6 +31,17 @@ public interface IAbCipTagRuntime : IDisposable
     /// </summary>
     object? DecodeValue(AbCipDataType type, int? bitIndex);
 
+    /// <summary>
+    ///     Decode a value at an arbitrary byte offset in the local buffer. Task #194 —
+    ///     whole-UDT reads perform one <see cref="ReadAsync"/> on the parent UDT tag then
+    ///     call this per declared member with its computed offset, avoiding one libplctag
+    ///     round-trip per member. Implementations that do not support offset-aware decoding
+    ///     may fall back to <see cref="DecodeValue"/> when <paramref name="offset"/> is zero;
+    ///     offsets greater than zero against an unsupporting runtime should return <c>null</c>
+    ///     so the planner can skip grouping.
+    /// </summary>
+    object? DecodeValueAt(AbCipDataType type, int offset, int? bitIndex);
+
     /// <summary>
     ///     Encode <paramref name="value"/> into the local buffer per the tag's type. Callers
     ///     pair this with <see cref="WriteAsync"/>.

src/ZB.MOM.WW.OtOpcUa.Driver.AbCip/LibplctagTagRuntime.cs

@@ -32,24 +32,26 @@ internal sealed class LibplctagTagRuntime : IAbCipTagRuntime
 
     public int GetStatus() => (int)_tag.GetStatus();
 
-    public object? DecodeValue(AbCipDataType type, int? bitIndex) => type switch
+    public object? DecodeValue(AbCipDataType type, int? bitIndex) => DecodeValueAt(type, 0, bitIndex);
+
+    public object? DecodeValueAt(AbCipDataType type, int offset, int? bitIndex) => type switch
     {
         AbCipDataType.Bool => bitIndex is int bit
             ? _tag.GetBit(bit)
-            : _tag.GetInt8(0) != 0,
-        AbCipDataType.SInt => (int)(sbyte)_tag.GetInt8(0),
-        AbCipDataType.USInt => (int)_tag.GetUInt8(0),
-        AbCipDataType.Int => (int)_tag.GetInt16(0),
-        AbCipDataType.UInt => (int)_tag.GetUInt16(0),
-        AbCipDataType.DInt => _tag.GetInt32(0),
-        AbCipDataType.UDInt => (int)_tag.GetUInt32(0),
-        AbCipDataType.LInt => _tag.GetInt64(0),
-        AbCipDataType.ULInt => (long)_tag.GetUInt64(0),
-        AbCipDataType.Real => _tag.GetFloat32(0),
-        AbCipDataType.LReal => _tag.GetFloat64(0),
-        AbCipDataType.String => _tag.GetString(0),
-        AbCipDataType.Dt => _tag.GetInt32(0), // seconds-since-epoch DINT; consumer widens as needed
-        AbCipDataType.Structure => null,       // UDT whole-tag decode lands in PR 6
+            : _tag.GetInt8(offset) != 0,
+        AbCipDataType.SInt => (int)(sbyte)_tag.GetInt8(offset),
+        AbCipDataType.USInt => (int)_tag.GetUInt8(offset),
+        AbCipDataType.Int => (int)_tag.GetInt16(offset),
+        AbCipDataType.UInt => (int)_tag.GetUInt16(offset),
+        AbCipDataType.DInt => _tag.GetInt32(offset),
+        AbCipDataType.UDInt => (int)_tag.GetUInt32(offset),
+        AbCipDataType.LInt => _tag.GetInt64(offset),
+        AbCipDataType.ULInt => (long)_tag.GetUInt64(offset),
+        AbCipDataType.Real => _tag.GetFloat32(offset),
+        AbCipDataType.LReal => _tag.GetFloat64(offset),
+        AbCipDataType.String => _tag.GetString(offset),
+        AbCipDataType.Dt => _tag.GetInt32(offset),
+        AbCipDataType.Structure => null,
         _ => null,
     };
 

src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Host/Backend/FakeFocasBackend.cs

@@ -0,0 +1,122 @@
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+using MessagePack;
+using ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared.Contracts;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Host.Backend;
+
+/// <summary>
+///     In-memory <see cref="IFocasBackend"/> for tests + an operational stub mode when
+///     <c>OTOPCUA_FOCAS_BACKEND=fake</c>. Keeps per-address values keyed by a canonical
+///     string; RMW semantics honor PMC bit-writes against the containing byte so the
+///     <c>PmcBitWriteRequest</c> path can be exercised end-to-end without hardware.
+/// </summary>
+public sealed class FakeFocasBackend : IFocasBackend
+{
+    private readonly object _gate = new();
+    private long _nextSessionId;
+    private readonly HashSet<long> _openSessions = [];
+    private readonly Dictionary<string, byte[]> _pmcValues = [];
+    private readonly Dictionary<string, byte[]> _paramValues = [];
+    private readonly Dictionary<string, byte[]> _macroValues = [];
+
+    public Task<OpenSessionResponse> OpenSessionAsync(OpenSessionRequest request, CancellationToken ct)
+    {
+        lock (_gate)
+        {
+            var id = ++_nextSessionId;
+            _openSessions.Add(id);
+            return Task.FromResult(new OpenSessionResponse { Success = true, SessionId = id });
+        }
+    }
+
+    public Task CloseSessionAsync(CloseSessionRequest request, CancellationToken ct)
+    {
+        lock (_gate) { _openSessions.Remove(request.SessionId); }
+        return Task.CompletedTask;
+    }
+
+    public Task<ReadResponse> ReadAsync(ReadRequest request, CancellationToken ct)
+    {
+        lock (_gate)
+        {
+            if (!_openSessions.Contains(request.SessionId))
+                return Task.FromResult(new ReadResponse { Success = false, StatusCode = 0x80020000u, Error = "session-not-open" });
+
+            var store = StoreFor(request.Address.Kind);
+            var key = CanonicalKey(request.Address);
+            store.TryGetValue(key, out var value);
+            return Task.FromResult(new ReadResponse
+            {
+                Success = true,
+                StatusCode = 0,
+                ValueBytes = value ?? MessagePackSerializer.Serialize((int)0),
+                ValueTypeCode = request.DataType,
+                SourceTimestampUtcUnixMs = System.DateTimeOffset.UtcNow.ToUnixTimeMilliseconds(),
+            });
+        }
+    }
+
+    public Task<WriteResponse> WriteAsync(WriteRequest request, CancellationToken ct)
+    {
+        lock (_gate)
+        {
+            if (!_openSessions.Contains(request.SessionId))
+                return Task.FromResult(new WriteResponse { Success = false, StatusCode = 0x80020000u, Error = "session-not-open" });
+
+            var store = StoreFor(request.Address.Kind);
+            store[CanonicalKey(request.Address)] = request.ValueBytes ?? [];
+            return Task.FromResult(new WriteResponse { Success = true, StatusCode = 0 });
+        }
+    }
+
+    public Task<PmcBitWriteResponse> PmcBitWriteAsync(PmcBitWriteRequest request, CancellationToken ct)
+    {
+        lock (_gate)
+        {
+            if (!_openSessions.Contains(request.SessionId))
+                return Task.FromResult(new PmcBitWriteResponse { Success = false, StatusCode = 0x80020000u, Error = "session-not-open" });
+            if (request.BitIndex is < 0 or > 7)
+                return Task.FromResult(new PmcBitWriteResponse { Success = false, StatusCode = 0x803C0000u, Error = "bit-out-of-range" });
+
+            var key = CanonicalKey(request.Address);
+            _pmcValues.TryGetValue(key, out var current);
+            current ??= MessagePackSerializer.Serialize((byte)0);
+            var b = MessagePackSerializer.Deserialize<byte>(current);
+            var mask = (byte)(1 << request.BitIndex);
+            b = request.Value ? (byte)(b | mask) : (byte)(b & ~mask);
+            _pmcValues[key] = MessagePackSerializer.Serialize(b);
+            return Task.FromResult(new PmcBitWriteResponse { Success = true, StatusCode = 0 });
+        }
+    }
+
+    public Task<ProbeResponse> ProbeAsync(ProbeRequest request, CancellationToken ct)
+    {
+        lock (_gate)
+        {
+            return Task.FromResult(new ProbeResponse
+            {
+                Healthy = _openSessions.Contains(request.SessionId),
+                ObservedAtUtcUnixMs = System.DateTimeOffset.UtcNow.ToUnixTimeMilliseconds(),
+            });
+        }
+    }
+
+    private Dictionary<string, byte[]> StoreFor(int kind) => kind switch
+    {
+        0 => _pmcValues,
+        1 => _paramValues,
+        2 => _macroValues,
+        _ => _pmcValues,
+    };
+
+    private static string CanonicalKey(FocasAddressDto addr) =>
+        addr.Kind switch
+        {
+            0 => $"{addr.PmcLetter}{addr.Number}",
+            1 => $"P{addr.Number}",
+            2 => $"M{addr.Number}",
+            _ => $"?{addr.Number}",
+        };
+}

src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Host/Backend/IFocasBackend.cs

@@ -0,0 +1,24 @@
+using System.Threading;
+using System.Threading.Tasks;
+using ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared.Contracts;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Host.Backend;
+
+/// <summary>
+///     The Host's view of a FOCAS session. One implementation wraps the real
+///     <c>Fwlib32.dll</c> via P/Invoke (lands with the real Fwlib32 integration follow-up,
+///     since no hardware is available today); a second implementation —
+///     <see cref="FakeFocasBackend"/> — is used by tests.
+///     Both live on .NET 4.8 x86 so the Host can be deployed in either mode without
+///     changing the pipe server.
+///     Invoked via <c>FwlibFrameHandler</c> in the Ipc namespace.
+/// </summary>
+public interface IFocasBackend
+{
+    Task<OpenSessionResponse> OpenSessionAsync(OpenSessionRequest request, CancellationToken ct);
+    Task CloseSessionAsync(CloseSessionRequest request, CancellationToken ct);
+    Task<ReadResponse> ReadAsync(ReadRequest request, CancellationToken ct);
+    Task<WriteResponse> WriteAsync(WriteRequest request, CancellationToken ct);
+    Task<PmcBitWriteResponse> PmcBitWriteAsync(PmcBitWriteRequest request, CancellationToken ct);
+    Task<ProbeResponse> ProbeAsync(ProbeRequest request, CancellationToken ct);
+}

src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Host/Backend/UnconfiguredFocasBackend.cs

@@ -0,0 +1,37 @@
+using System.Threading;
+using System.Threading.Tasks;
+using ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared.Contracts;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Host.Backend;
+
+/// <summary>
+///     Safe default when the deployment hasn't configured a real Fwlib32 backend.
+///     Returns structured failure responses instead of throwing so the Proxy can map the
+///     error to <c>BadDeviceFailure</c> and surface a clear operator message pointing at
+///     <c>docs/v2/focas-deployment.md</c>. Used when <c>OTOPCUA_FOCAS_BACKEND</c> is unset
+///     or set to <c>unconfigured</c>.
+/// </summary>
+public sealed class UnconfiguredFocasBackend : IFocasBackend
+{
+    private const uint BadDeviceFailure = 0x80550000u;
+    private const string Reason =
+        "FOCAS Host is running without a real Fwlib32 backend. Set OTOPCUA_FOCAS_BACKEND=fwlib32 " +
+        "and ensure Fwlib32.dll is on PATH — see docs/v2/focas-deployment.md.";
+
+    public Task<OpenSessionResponse> OpenSessionAsync(OpenSessionRequest request, CancellationToken ct) =>
+        Task.FromResult(new OpenSessionResponse { Success = false, Error = Reason, ErrorCode = "NoFwlibBackend" });
+
+    public Task CloseSessionAsync(CloseSessionRequest request, CancellationToken ct) => Task.CompletedTask;
+
+    public Task<ReadResponse> ReadAsync(ReadRequest request, CancellationToken ct) =>
+        Task.FromResult(new ReadResponse { Success = false, StatusCode = BadDeviceFailure, Error = Reason });
+
+    public Task<WriteResponse> WriteAsync(WriteRequest request, CancellationToken ct) =>
+        Task.FromResult(new WriteResponse { Success = false, StatusCode = BadDeviceFailure, Error = Reason });
+
+    public Task<PmcBitWriteResponse> PmcBitWriteAsync(PmcBitWriteRequest request, CancellationToken ct) =>
+        Task.FromResult(new PmcBitWriteResponse { Success = false, StatusCode = BadDeviceFailure, Error = Reason });
+
+    public Task<ProbeResponse> ProbeAsync(ProbeRequest request, CancellationToken ct) =>
+        Task.FromResult(new ProbeResponse { Healthy = false, Error = Reason, ObservedAtUtcUnixMs = System.DateTimeOffset.UtcNow.ToUnixTimeMilliseconds() });
+}

src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Host/Ipc/FwlibFrameHandler.cs

@@ -0,0 +1,111 @@
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+using MessagePack;
+using Serilog;
+using ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Host.Backend;
+using ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared;
+using ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared.Contracts;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Host.Ipc;
+
+/// <summary>
+///     Real FOCAS frame handler. Deserializes each request DTO, delegates to
+///     <see cref="IFocasBackend"/>, re-serializes the response. The backend owns the
+///     Fwlib32 handle + STA thread — the handler is pure dispatch.
+/// </summary>
+public sealed class FwlibFrameHandler : IFrameHandler
+{
+    private readonly IFocasBackend _backend;
+    private readonly ILogger _logger;
+
+    public FwlibFrameHandler(IFocasBackend backend, ILogger logger)
+    {
+        _backend = backend ?? throw new ArgumentNullException(nameof(backend));
+        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
+    }
+
+    public async Task HandleAsync(FocasMessageKind kind, byte[] body, FrameWriter writer, CancellationToken ct)
+    {
+        try
+        {
+            switch (kind)
+            {
+                case FocasMessageKind.Heartbeat:
+                {
+                    var hb = MessagePackSerializer.Deserialize<Heartbeat>(body);
+                    await writer.WriteAsync(FocasMessageKind.HeartbeatAck,
+                        new HeartbeatAck
+                        {
+                            MonotonicTicks = hb.MonotonicTicks,
+                            HostUtcUnixMs = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds(),
+                        }, ct).ConfigureAwait(false);
+                    return;
+                }
+
+                case FocasMessageKind.OpenSessionRequest:
+                {
+                    var req = MessagePackSerializer.Deserialize<OpenSessionRequest>(body);
+                    var resp = await _backend.OpenSessionAsync(req, ct).ConfigureAwait(false);
+                    await writer.WriteAsync(FocasMessageKind.OpenSessionResponse, resp, ct).ConfigureAwait(false);
+                    return;
+                }
+
+                case FocasMessageKind.CloseSessionRequest:
+                {
+                    var req = MessagePackSerializer.Deserialize<CloseSessionRequest>(body);
+                    await _backend.CloseSessionAsync(req, ct).ConfigureAwait(false);
+                    return;
+                }
+
+                case FocasMessageKind.ReadRequest:
+                {
+                    var req = MessagePackSerializer.Deserialize<ReadRequest>(body);
+                    var resp = await _backend.ReadAsync(req, ct).ConfigureAwait(false);
+                    await writer.WriteAsync(FocasMessageKind.ReadResponse, resp, ct).ConfigureAwait(false);
+                    return;
+                }
+
+                case FocasMessageKind.WriteRequest:
+                {
+                    var req = MessagePackSerializer.Deserialize<WriteRequest>(body);
+                    var resp = await _backend.WriteAsync(req, ct).ConfigureAwait(false);
+                    await writer.WriteAsync(FocasMessageKind.WriteResponse, resp, ct).ConfigureAwait(false);
+                    return;
+                }
+
+                case FocasMessageKind.PmcBitWriteRequest:
+                {
+                    var req = MessagePackSerializer.Deserialize<PmcBitWriteRequest>(body);
+                    var resp = await _backend.PmcBitWriteAsync(req, ct).ConfigureAwait(false);
+                    await writer.WriteAsync(FocasMessageKind.PmcBitWriteResponse, resp, ct).ConfigureAwait(false);
+                    return;
+                }
+
+                case FocasMessageKind.ProbeRequest:
+                {
+                    var req = MessagePackSerializer.Deserialize<ProbeRequest>(body);
+                    var resp = await _backend.ProbeAsync(req, ct).ConfigureAwait(false);
+                    await writer.WriteAsync(FocasMessageKind.ProbeResponse, resp, ct).ConfigureAwait(false);
+                    return;
+                }
+
+                default:
+                    await writer.WriteAsync(FocasMessageKind.ErrorResponse,
+                        new ErrorResponse { Code = "unknown-kind", Message = $"Kind {kind} is not handled by the Host" },
+                        ct).ConfigureAwait(false);
+                    return;
+            }
+        }
+        catch (OperationCanceledException) { throw; }
+        catch (Exception ex)
+        {
+            _logger.Error(ex, "FwlibFrameHandler error processing {Kind}", kind);
+            await writer.WriteAsync(FocasMessageKind.ErrorResponse,
+                new ErrorResponse { Code = "backend-exception", Message = ex.Message },
+                ct).ConfigureAwait(false);
+        }
+    }
+
+    public IDisposable AttachConnection(FrameWriter writer) => IFrameHandler.NoopAttachment.Instance;
+}

src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Host/Ipc/IFrameHandler.cs

@@ -0,0 +1,31 @@
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+using ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared;
+using ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared.Contracts;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Host.Ipc;
+
+/// <summary>
+///     Dispatches a single IPC frame to the backend. Implementations own the FOCAS session
+///     state and translate request DTOs into Fwlib32 calls.
+/// </summary>
+public interface IFrameHandler
+{
+    Task HandleAsync(FocasMessageKind kind, byte[] body, FrameWriter writer, CancellationToken ct);
+
+    /// <summary>
+    ///     Called once per accepted connection after the Hello handshake. Lets the handler
+    ///     attach server-pushed event sinks (data-change notifications, runtime-status
+    ///     changes) to the connection's <paramref name="writer"/>. Returns an
+    ///     <see cref="IDisposable"/> the pipe server disposes when the connection closes —
+    ///     backends use it to unsubscribe from their push sources.
+    /// </summary>
+    IDisposable AttachConnection(FrameWriter writer);
+
+    public sealed class NoopAttachment : IDisposable
+    {
+        public static readonly NoopAttachment Instance = new();
+        public void Dispose() { }
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Host/Ipc/PipeAcl.cs

@@ -0,0 +1,39 @@
+using System;
+using System.IO.Pipes;
+using System.Security.AccessControl;
+using System.Security.Principal;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Host.Ipc;
+
+/// <summary>
+///     Builds the <see cref="PipeSecurity"/> for the FOCAS Host pipe. Same pattern as
+///     Galaxy.Host: only the configured OtOpcUa server principal SID gets
+///     <c>ReadWrite | Synchronize</c>; LocalSystem + Administrators are explicitly denied
+///     so a compromised service account on the same host can't escalate via the pipe.
+/// </summary>
+public static class PipeAcl
+{
+    public static PipeSecurity Create(SecurityIdentifier allowedSid)
+    {
+        if (allowedSid is null) throw new ArgumentNullException(nameof(allowedSid));
+
+        var security = new PipeSecurity();
+
+        security.AddAccessRule(new PipeAccessRule(
+            allowedSid,
+            PipeAccessRights.ReadWrite | PipeAccessRights.Synchronize,
+            AccessControlType.Allow));
+
+        var localSystem = new SecurityIdentifier(WellKnownSidType.LocalSystemSid, null);
+        var admins      = new SecurityIdentifier(WellKnownSidType.BuiltinAdministratorsSid, null);
+
+        if (allowedSid != localSystem)
+            security.AddAccessRule(new PipeAccessRule(localSystem, PipeAccessRights.FullControl, AccessControlType.Deny));
+        if (allowedSid != admins)
+            security.AddAccessRule(new PipeAccessRule(admins,      PipeAccessRights.FullControl, AccessControlType.Deny));
+
+        security.SetOwner(allowedSid);
+
+        return security;
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Host/Ipc/PipeServer.cs

@@ -0,0 +1,152 @@
+using System;
+using System.IO.Pipes;
+using System.Security.Principal;
+using System.Threading;
+using System.Threading.Tasks;
+using MessagePack;
+using Serilog;
+using ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared;
+using ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared.Contracts;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Host.Ipc;
+
+/// <summary>
+///     Accepts one client connection at a time on the FOCAS Host's named pipe with the
+///     strict ACL from <see cref="PipeAcl"/>. Verifies the peer SID + per-process shared
+///     secret before any RPC frame is accepted. Mirrors the Galaxy.Host pipe server byte for
+///     byte — different MessageKind enum, same negotiation semantics.
+/// </summary>
+public sealed class PipeServer : IDisposable
+{
+    private readonly string _pipeName;
+    private readonly SecurityIdentifier _allowedSid;
+    private readonly string _sharedSecret;
+    private readonly ILogger _logger;
+    private readonly CancellationTokenSource _cts = new();
+    private NamedPipeServerStream? _current;
+
+    public PipeServer(string pipeName, SecurityIdentifier allowedSid, string sharedSecret, ILogger logger)
+    {
+        _pipeName = pipeName ?? throw new ArgumentNullException(nameof(pipeName));
+        _allowedSid = allowedSid ?? throw new ArgumentNullException(nameof(allowedSid));
+        _sharedSecret = sharedSecret ?? throw new ArgumentNullException(nameof(sharedSecret));
+        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
+    }
+
+    public async Task RunOneConnectionAsync(IFrameHandler handler, CancellationToken ct)
+    {
+        using var linked = CancellationTokenSource.CreateLinkedTokenSource(_cts.Token, ct);
+        var acl = PipeAcl.Create(_allowedSid);
+
+        _current = new NamedPipeServerStream(
+            _pipeName,
+            PipeDirection.InOut,
+            maxNumberOfServerInstances: 1,
+            PipeTransmissionMode.Byte,
+            PipeOptions.Asynchronous,
+            inBufferSize: 64 * 1024,
+            outBufferSize: 64 * 1024,
+            pipeSecurity: acl);
+
+        try
+        {
+            await _current.WaitForConnectionAsync(linked.Token).ConfigureAwait(false);
+
+            if (!VerifyCaller(_current, out var reason))
+            {
+                _logger.Warning("FOCAS IPC caller rejected: {Reason}", reason);
+                _current.Disconnect();
+                return;
+            }
+
+            using var reader = new FrameReader(_current, leaveOpen: true);
+            using var writer = new FrameWriter(_current, leaveOpen: true);
+
+            var first = await reader.ReadFrameAsync(linked.Token).ConfigureAwait(false);
+            if (first is null || first.Value.Kind != FocasMessageKind.Hello)
+            {
+                _logger.Warning("FOCAS IPC first frame was not Hello; dropping");
+                return;
+            }
+
+            var hello = MessagePackSerializer.Deserialize<Hello>(first.Value.Body);
+            if (!string.Equals(hello.SharedSecret, _sharedSecret, StringComparison.Ordinal))
+            {
+                await writer.WriteAsync(FocasMessageKind.HelloAck,
+                    new HelloAck { Accepted = false, RejectReason = "shared-secret-mismatch" },
+                    linked.Token).ConfigureAwait(false);
+                _logger.Warning("FOCAS IPC Hello rejected: shared-secret-mismatch");
+                return;
+            }
+
+            if (hello.ProtocolMajor != Hello.CurrentMajor)
+            {
+                await writer.WriteAsync(FocasMessageKind.HelloAck,
+                    new HelloAck
+                    {
+                        Accepted = false,
+                        RejectReason = $"major-version-mismatch-peer={hello.ProtocolMajor}-server={Hello.CurrentMajor}",
+                    },
+                    linked.Token).ConfigureAwait(false);
+                _logger.Warning("FOCAS IPC Hello rejected: major mismatch peer={Peer} server={Server}",
+                    hello.ProtocolMajor, Hello.CurrentMajor);
+                return;
+            }
+
+            await writer.WriteAsync(FocasMessageKind.HelloAck,
+                new HelloAck { Accepted = true, HostName = Environment.MachineName },
+                linked.Token).ConfigureAwait(false);
+
+            using var attachment = handler.AttachConnection(writer);
+
+            while (!linked.Token.IsCancellationRequested)
+            {
+                var frame = await reader.ReadFrameAsync(linked.Token).ConfigureAwait(false);
+                if (frame is null) break;
+
+                await handler.HandleAsync(frame.Value.Kind, frame.Value.Body, writer, linked.Token).ConfigureAwait(false);
+            }
+        }
+        finally
+        {
+            _current.Dispose();
+            _current = null;
+        }
+    }
+
+    public async Task RunAsync(IFrameHandler handler, CancellationToken ct)
+    {
+        while (!ct.IsCancellationRequested)
+        {
+            try { await RunOneConnectionAsync(handler, ct).ConfigureAwait(false); }
+            catch (OperationCanceledException) { break; }
+            catch (Exception ex) { _logger.Error(ex, "FOCAS IPC connection loop error — accepting next"); }
+        }
+    }
+
+    private bool VerifyCaller(NamedPipeServerStream pipe, out string reason)
+    {
+        try
+        {
+            pipe.RunAsClient(() =>
+            {
+                using var wi = WindowsIdentity.GetCurrent();
+                if (wi.User is null)
+                    throw new InvalidOperationException("GetCurrent().User is null — cannot verify caller");
+                if (wi.User != _allowedSid)
+                    throw new UnauthorizedAccessException(
+                        $"caller SID {wi.User.Value} does not match allowed {_allowedSid.Value}");
+            });
+            reason = string.Empty;
+            return true;
+        }
+        catch (Exception ex) { reason = ex.Message; return false; }
+    }
+
+    public void Dispose()
+    {
+        _cts.Cancel();
+        _current?.Dispose();
+        _cts.Dispose();
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Host/Ipc/StubFrameHandler.cs

@@ -0,0 +1,41 @@
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+using MessagePack;
+using ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared;
+using ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared.Contracts;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Host.Ipc;
+
+/// <summary>
+///     Placeholder handler that returns <c>ErrorResponse{Code=not-implemented}</c> for every
+///     FOCAS data-plane request. Exists so PR B can ship the pipe server + ACL + handshake
+///     plumbing before PR C moves the Fwlib32 calls. Heartbeats are handled fully so the
+///     supervisor's liveness detector stays happy.
+/// </summary>
+public sealed class StubFrameHandler : IFrameHandler
+{
+    public Task HandleAsync(FocasMessageKind kind, byte[] body, FrameWriter writer, CancellationToken ct)
+    {
+        if (kind == FocasMessageKind.Heartbeat)
+        {
+            var hb = MessagePackSerializer.Deserialize<Heartbeat>(body);
+            return writer.WriteAsync(FocasMessageKind.HeartbeatAck,
+                new HeartbeatAck
+                {
+                    MonotonicTicks = hb.MonotonicTicks,
+                    HostUtcUnixMs = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds(),
+                }, ct);
+        }
+
+        return writer.WriteAsync(FocasMessageKind.ErrorResponse,
+            new ErrorResponse
+            {
+                Code = "not-implemented",
+                Message = $"Kind {kind} is stubbed — Fwlib32 lift lands in PR C",
+            },
+            ct);
+    }
+
+    public IDisposable AttachConnection(FrameWriter writer) => IFrameHandler.NoopAttachment.Instance;
+}

src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Host/Program.cs

@@ -0,0 +1,72 @@
+using System;
+using System.Security.Principal;
+using System.Threading;
+using Serilog;
+using ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Host.Backend;
+using ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Host.Ipc;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Host;
+
+/// <summary>
+///     Entry point for the <c>OtOpcUaFocasHost</c> Windows service / console host. The
+///     supervisor (Proxy-side) spawns this process per FOCAS driver instance and passes the
+///     pipe name, allowed-SID, and per-process shared secret as environment variables. In
+///     PR B the backend is <see cref="StubFrameHandler"/> — PR C swaps in the real
+///     Fwlib32-backed handler once the session state + STA thread move out of the .NET 10
+///     driver.
+/// </summary>
+public static class Program
+{
+    public static int Main(string[] args)
+    {
+        Log.Logger = new LoggerConfiguration()
+            .MinimumLevel.Information()
+            .WriteTo.File(
+                @"%ProgramData%\OtOpcUa\focas-host-.log".Replace("%ProgramData%", Environment.GetFolderPath(Environment.SpecialFolder.CommonApplicationData)),
+                rollingInterval: RollingInterval.Day)
+            .CreateLogger();
+
+        try
+        {
+            var pipeName = Environment.GetEnvironmentVariable("OTOPCUA_FOCAS_PIPE") ?? "OtOpcUaFocas";
+            var allowedSidValue = Environment.GetEnvironmentVariable("OTOPCUA_ALLOWED_SID")
+                ?? throw new InvalidOperationException(
+                    "OTOPCUA_ALLOWED_SID not set — the FOCAS Proxy supervisor must pass the server principal SID");
+            var sharedSecret = Environment.GetEnvironmentVariable("OTOPCUA_FOCAS_SECRET")
+                ?? throw new InvalidOperationException(
+                    "OTOPCUA_FOCAS_SECRET not set — the FOCAS Proxy supervisor must pass the per-process secret at spawn time");
+
+            var allowedSid = new SecurityIdentifier(allowedSidValue);
+
+            using var server = new PipeServer(pipeName, allowedSid, sharedSecret, Log.Logger);
+            using var cts = new CancellationTokenSource();
+            Console.CancelKeyPress += (_, e) => { e.Cancel = true; cts.Cancel(); };
+
+            Log.Information("OtOpcUaFocasHost starting — pipe={Pipe} allowedSid={Sid}",
+                pipeName, allowedSidValue);
+
+            var backendKind = (Environment.GetEnvironmentVariable("OTOPCUA_FOCAS_BACKEND") ?? "unconfigured")
+                .ToLowerInvariant();
+            IFocasBackend backend = backendKind switch
+            {
+                "fake"         => new FakeFocasBackend(),
+                "unconfigured" => new UnconfiguredFocasBackend(),
+                "fwlib32"      => new UnconfiguredFocasBackend(), // real Fwlib32 backend lands with hardware integration follow-up
+                _              => new UnconfiguredFocasBackend(),
+            };
+            Log.Information("OtOpcUaFocasHost backend={Backend}", backendKind);
+
+            var handler = new FwlibFrameHandler(backend, Log.Logger);
+            server.RunAsync(handler, cts.Token).GetAwaiter().GetResult();
+
+            Log.Information("OtOpcUaFocasHost stopped cleanly");
+            return 0;
+        }
+        catch (Exception ex)
+        {
+            Log.Fatal(ex, "OtOpcUaFocasHost fatal");
+            return 2;
+        }
+        finally { Log.CloseAndFlush(); }
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Host/Stability/PostMortemMmf.cs

@@ -0,0 +1,133 @@
+using System;
+using System.IO;
+using System.IO.MemoryMappedFiles;
+using System.Text;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Host.Stability;
+
+/// <summary>
+///     Ring-buffer of the last N IPC operations, written into a memory-mapped file. On a
+///     hard crash the Proxy-side supervisor reads the MMF after the corpse is gone to see
+///     what was in flight at the moment the Host died. Single-writer (the Host), multi-reader
+///     (the supervisor) — the file format is identical to the Galaxy Tier-C
+///     <c>PostMortemMmf</c> so a single reader tool can work both.
+/// </summary>
+/// <remarks>
+///     File layout:
+///     <code>
+///     [16-byte header: magic(4) | version(4) | capacity(4) | writeIndex(4)]
+///     [capacity × 256-byte entries: each is [8-byte utcUnixMs | 8-byte opKind | 240-byte UTF-8 message]]
+///     </code>
+///     Magic is 'OFPC' (0x4F46_5043) to distinguish a FOCAS file from the Galaxy MMF.
+/// </remarks>
+public sealed class PostMortemMmf : IDisposable
+{
+    private const int Magic = 0x4F465043; // 'OFPC'
+    private const int Version = 1;
+    private const int HeaderBytes = 16;
+    public const int EntryBytes = 256;
+    private const int MessageOffset = 16;
+    private const int MessageCapacity = EntryBytes - MessageOffset;
+
+    public int Capacity { get; }
+    public string Path { get; }
+
+    private readonly MemoryMappedFile _mmf;
+    private readonly MemoryMappedViewAccessor _accessor;
+    private readonly object _writeGate = new();
+
+    public PostMortemMmf(string path, int capacity = 1000)
+    {
+        if (capacity <= 0) throw new ArgumentOutOfRangeException(nameof(capacity));
+        Capacity = capacity;
+        Path = path;
+
+        var fileBytes = HeaderBytes + capacity * EntryBytes;
+        Directory.CreateDirectory(System.IO.Path.GetDirectoryName(path)!);
+
+        var fs = new FileStream(path, FileMode.OpenOrCreate, FileAccess.ReadWrite, FileShare.Read);
+        fs.SetLength(fileBytes);
+        _mmf = MemoryMappedFile.CreateFromFile(fs, null, fileBytes,
+            MemoryMappedFileAccess.ReadWrite, HandleInheritability.None, leaveOpen: false);
+        _accessor = _mmf.CreateViewAccessor(0, fileBytes, MemoryMappedFileAccess.ReadWrite);
+
+        if (_accessor.ReadInt32(0) != Magic)
+        {
+            _accessor.Write(0, Magic);
+            _accessor.Write(4, Version);
+            _accessor.Write(8, capacity);
+            _accessor.Write(12, 0);
+        }
+    }
+
+    public void Write(long opKind, string message)
+    {
+        lock (_writeGate)
+        {
+            var idx = _accessor.ReadInt32(12);
+            var offset = HeaderBytes + idx * EntryBytes;
+
+            _accessor.Write(offset + 0, DateTimeOffset.UtcNow.ToUnixTimeMilliseconds());
+            _accessor.Write(offset + 8, opKind);
+
+            var msgBytes = Encoding.UTF8.GetBytes(message ?? string.Empty);
+            var copy = Math.Min(msgBytes.Length, MessageCapacity - 1);
+            _accessor.WriteArray(offset + MessageOffset, msgBytes, 0, copy);
+            _accessor.Write(offset + MessageOffset + copy, (byte)0);
+
+            var next = (idx + 1) % Capacity;
+            _accessor.Write(12, next);
+        }
+    }
+
+    public PostMortemEntry[] ReadAll()
+    {
+        var magic = _accessor.ReadInt32(0);
+        if (magic != Magic) return new PostMortemEntry[0];
+
+        var capacity = _accessor.ReadInt32(8);
+        var writeIndex = _accessor.ReadInt32(12);
+
+        var entries = new PostMortemEntry[capacity];
+        var count = 0;
+        for (var i = 0; i < capacity; i++)
+        {
+            var slot = (writeIndex + i) % capacity;
+            var offset = HeaderBytes + slot * EntryBytes;
+
+            var ts = _accessor.ReadInt64(offset + 0);
+            if (ts == 0) continue;
+
+            var op = _accessor.ReadInt64(offset + 8);
+            var msgBuf = new byte[MessageCapacity];
+            _accessor.ReadArray(offset + MessageOffset, msgBuf, 0, MessageCapacity);
+            var nulTerm = Array.IndexOf<byte>(msgBuf, 0);
+            var msg = Encoding.UTF8.GetString(msgBuf, 0, nulTerm < 0 ? MessageCapacity : nulTerm);
+
+            entries[count++] = new PostMortemEntry(ts, op, msg);
+        }
+
+        Array.Resize(ref entries, count);
+        return entries;
+    }
+
+    public void Dispose()
+    {
+        _accessor.Dispose();
+        _mmf.Dispose();
+    }
+}
+
+public readonly struct PostMortemEntry
+{
+    public long UtcUnixMs { get; }
+    public long OpKind { get; }
+    public string Message { get; }
+
+    public PostMortemEntry(long utcUnixMs, long opKind, string message)
+    {
+        UtcUnixMs = utcUnixMs;
+        OpKind = opKind;
+        Message = message;
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Host/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Host.csproj

@@ -0,0 +1,40 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+    <PropertyGroup>
+        <OutputType>Exe</OutputType>
+        <TargetFramework>net48</TargetFramework>
+        <!-- Fwlib32.dll is 32-bit only — x86 target is mandatory. Matches the Galaxy.Host
+             bitness constraint but for a different native library. -->
+        <PlatformTarget>x86</PlatformTarget>
+        <Prefer32Bit>true</Prefer32Bit>
+        <Nullable>enable</Nullable>
+        <LangVersion>latest</LangVersion>
+        <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+        <GenerateDocumentationFile>true</GenerateDocumentationFile>
+        <NoWarn>$(NoWarn);CS1591</NoWarn>
+        <RootNamespace>ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Host</RootNamespace>
+        <AssemblyName>OtOpcUa.Driver.FOCAS.Host</AssemblyName>
+    </PropertyGroup>
+
+    <ItemGroup>
+        <PackageReference Include="System.IO.Pipes.AccessControl" Version="5.0.0"/>
+        <PackageReference Include="System.Memory" Version="4.5.5"/>
+        <PackageReference Include="System.Threading.Tasks.Extensions" Version="4.5.4"/>
+        <PackageReference Include="Serilog" Version="4.2.0"/>
+        <PackageReference Include="Serilog.Sinks.File" Version="7.0.0"/>
+    </ItemGroup>
+
+    <ItemGroup>
+        <ProjectReference Include="..\ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared\ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared.csproj"/>
+    </ItemGroup>
+
+    <ItemGroup>
+        <InternalsVisibleTo Include="ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Host.Tests"/>
+    </ItemGroup>
+
+    <ItemGroup>
+        <NuGetAuditSuppress Include="https://github.com/advisories/GHSA-37gx-xxp4-5rgx"/>
+        <NuGetAuditSuppress Include="https://github.com/advisories/GHSA-w3x6-4m5h-cxqf"/>
+    </ItemGroup>
+
+</Project>

src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared/Contracts/Addresses.cs

@@ -0,0 +1,39 @@
+using MessagePack;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared.Contracts;
+
+/// <summary>
+///     Wire shape for a parsed FOCAS address. Mirrors <c>FocasAddress</c> in the driver
+///     package but lives in Shared so the Host (.NET 4.8) can decode without taking a
+///     reference to the .NET 10 driver assembly. The Proxy serializes from its own
+///     <c>FocasAddress</c>; the Host maps back to its local equivalent.
+/// </summary>
+[MessagePackObject]
+public sealed class FocasAddressDto
+{
+    /// <summary>0 = Pmc, 1 = Parameter, 2 = Macro. Matches <c>FocasAreaKind</c> enum order.</summary>
+    [Key(0)] public int Kind { get; set; }
+
+    /// <summary>PMC letter — null for Parameter / Macro.</summary>
+    [Key(1)] public string? PmcLetter { get; set; }
+
+    [Key(2)] public int Number { get; set; }
+
+    /// <summary>Optional bit index (0-7 for PMC, 0-31 for Parameter).</summary>
+    [Key(3)] public int? BitIndex { get; set; }
+}
+
+/// <summary>
+///     0 = Bit, 1 = Byte, 2 = Int16, 3 = Int32, 4 = Float32, 5 = Float64, 6 = String.
+///     Matches <c>FocasDataType</c> enum order so both sides can cast <c>(int)</c>.
+/// </summary>
+public static class FocasDataTypeCode
+{
+    public const int Bit = 0;
+    public const int Byte = 1;
+    public const int Int16 = 2;
+    public const int Int32 = 3;
+    public const int Float32 = 4;
+    public const int Float64 = 5;
+    public const int String = 6;
+}

src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared/Contracts/Framing.cs

@@ -0,0 +1,57 @@
+namespace ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared.Contracts;
+
+/// <summary>
+///     Length-prefixed framing. Each IPC frame is:
+///     <c>[4-byte big-endian length][1-byte message kind][MessagePack body]</c>.
+///     Length is the body size only; the kind byte is not part of the prefixed length.
+///     Mirrors the Galaxy Tier-C framing so operators see one wire format across hosts.
+/// </summary>
+public static class Framing
+{
+    public const int LengthPrefixSize = 4;
+    public const int KindByteSize = 1;
+
+    /// <summary>
+    ///     Maximum permitted body length (16 MiB). Protects the receiver from a hostile or
+    ///     misbehaving peer sending an oversized length prefix.
+    /// </summary>
+    public const int MaxFrameBodyBytes = 16 * 1024 * 1024;
+}
+
+/// <summary>
+///     Wire identifier for each contract. Values are stable — new contracts append, never
+///     reuse. Ranges kept aligned with Galaxy so an operator reading a hex dump doesn't have
+///     to context-switch between drivers.
+/// </summary>
+public enum FocasMessageKind : byte
+{
+    Hello                    = 0x01,
+    HelloAck                 = 0x02,
+    Heartbeat                = 0x03,
+    HeartbeatAck             = 0x04,
+
+    OpenSessionRequest       = 0x10,
+    OpenSessionResponse      = 0x11,
+    CloseSessionRequest      = 0x12,
+
+    ReadRequest              = 0x30,
+    ReadResponse             = 0x31,
+    WriteRequest             = 0x32,
+    WriteResponse            = 0x33,
+    PmcBitWriteRequest       = 0x34,
+    PmcBitWriteResponse      = 0x35,
+
+    SubscribeRequest         = 0x40,
+    SubscribeResponse        = 0x41,
+    UnsubscribeRequest       = 0x42,
+    OnDataChangeNotification = 0x43,
+
+    ProbeRequest             = 0x70,
+    ProbeResponse            = 0x71,
+    RuntimeStatusChange      = 0x72,
+
+    RecycleHostRequest       = 0xF0,
+    RecycleStatusResponse    = 0xF1,
+
+    ErrorResponse            = 0xFE,
+}

src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared/Contracts/Hello.cs

@@ -0,0 +1,63 @@
+using MessagePack;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared.Contracts;
+
+/// <summary>
+///     First frame of every FOCAS Proxy -> Host connection. Advertises protocol major/minor
+///     and the per-process shared secret the Proxy passed to the Host at spawn time. Major
+///     mismatch is fatal; minor is advisory.
+/// </summary>
+[MessagePackObject]
+public sealed class Hello
+{
+    public const int CurrentMajor = 1;
+    public const int CurrentMinor = 0;
+
+    [Key(0)] public int ProtocolMajor { get; set; } = CurrentMajor;
+    [Key(1)] public int ProtocolMinor { get; set; } = CurrentMinor;
+    [Key(2)] public string PeerName { get; set; } = string.Empty;
+
+    /// <summary>
+    ///     Per-process shared secret verified on the Host side against the value passed by the
+    ///     supervisor at spawn time. Protects against a local attacker connecting to the pipe
+    ///     after authenticating via the pipe ACL.
+    /// </summary>
+    [Key(3)] public string SharedSecret { get; set; } = string.Empty;
+
+    [Key(4)] public string[] Features { get; set; } = System.Array.Empty<string>();
+}
+
+[MessagePackObject]
+public sealed class HelloAck
+{
+    [Key(0)] public int ProtocolMajor { get; set; } = Hello.CurrentMajor;
+    [Key(1)] public int ProtocolMinor { get; set; } = Hello.CurrentMinor;
+
+    /// <summary>True if the Host accepted the hello; false + <see cref="RejectReason"/> filled if not.</summary>
+    [Key(2)] public bool Accepted { get; set; }
+    [Key(3)] public string? RejectReason { get; set; }
+
+    [Key(4)] public string HostName { get; set; } = string.Empty;
+}
+
+[MessagePackObject]
+public sealed class Heartbeat
+{
+    [Key(0)] public long MonotonicTicks { get; set; }
+}
+
+[MessagePackObject]
+public sealed class HeartbeatAck
+{
+    [Key(0)] public long MonotonicTicks { get; set; }
+    [Key(1)] public long HostUtcUnixMs { get; set; }
+}
+
+[MessagePackObject]
+public sealed class ErrorResponse
+{
+    /// <summary>Stable symbolic code — e.g. <c>InvalidAddress</c>, <c>SessionNotFound</c>, <c>Fwlib32Crashed</c>.</summary>
+    [Key(0)] public string Code { get; set; } = string.Empty;
+
+    [Key(1)] public string Message { get; set; } = string.Empty;
+}

src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared/Contracts/Probe.cs

@@ -0,0 +1,47 @@
+using MessagePack;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared.Contracts;
+
+/// <summary>Lightweight connectivity probe — maps to <c>cnc_rdcncstat</c> on the Host.</summary>
+[MessagePackObject]
+public sealed class ProbeRequest
+{
+    [Key(0)] public long SessionId { get; set; }
+    [Key(1)] public int TimeoutMs { get; set; } = 2000;
+}
+
+[MessagePackObject]
+public sealed class ProbeResponse
+{
+    [Key(0)] public bool Healthy { get; set; }
+    [Key(1)] public string? Error { get; set; }
+    [Key(2)] public long ObservedAtUtcUnixMs { get; set; }
+}
+
+/// <summary>Per-host runtime status — fan-out target when the Host observes the CNC going unreachable without the Proxy asking.</summary>
+[MessagePackObject]
+public sealed class RuntimeStatusChangeNotification
+{
+    [Key(0)] public long SessionId { get; set; }
+
+    /// <summary>Running | Stopped | Unknown.</summary>
+    [Key(1)] public string RuntimeStatus { get; set; } = string.Empty;
+
+    [Key(2)] public long ObservedAtUtcUnixMs { get; set; }
+}
+
+[MessagePackObject]
+public sealed class RecycleHostRequest
+{
+    /// <summary>Soft | Hard. Soft drains subscriptions first; Hard kills immediately.</summary>
+    [Key(0)] public string Kind { get; set; } = "Soft";
+    [Key(1)] public string Reason { get; set; } = string.Empty;
+}
+
+[MessagePackObject]
+public sealed class RecycleStatusResponse
+{
+    [Key(0)] public bool Accepted { get; set; }
+    [Key(1)] public int GraceSeconds { get; set; } = 15;
+    [Key(2)] public string? Error { get; set; }
+}

src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared/Contracts/ReadWrite.cs

@@ -0,0 +1,85 @@
+using MessagePack;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared.Contracts;
+
+/// <summary>
+///     Read one FOCAS address. Multi-read is the Proxy's responsibility — it batches
+///     per-tag reads into parallel <see cref="ReadRequest"/> frames the Host services on its
+///     STA thread. Keeping the IPC read single-address keeps the Host side trivial; FOCAS
+///     itself has no multi-read primitive that spans area kinds.
+/// </summary>
+[MessagePackObject]
+public sealed class ReadRequest
+{
+    [Key(0)] public long SessionId { get; set; }
+    [Key(1)] public FocasAddressDto Address { get; set; } = new();
+    [Key(2)] public int DataType { get; set; }
+    [Key(3)] public int TimeoutMs { get; set; } = 2000;
+}
+
+[MessagePackObject]
+public sealed class ReadResponse
+{
+    [Key(0)] public bool Success { get; set; }
+    [Key(1)] public string? Error { get; set; }
+
+    /// <summary>OPC UA status code mapped by the Host via <c>FocasStatusMapper</c> — 0 = Good.</summary>
+    [Key(2)] public uint StatusCode { get; set; }
+
+    /// <summary>MessagePack-serialized boxed value. <c>null</c> when <see cref="Success"/> is false.</summary>
+    [Key(3)] public byte[]? ValueBytes { get; set; }
+
+    /// <summary>Matches <see cref="FocasDataTypeCode"/> so the Proxy knows how to deserialize.</summary>
+    [Key(4)] public int ValueTypeCode { get; set; }
+
+    [Key(5)] public long SourceTimestampUtcUnixMs { get; set; }
+}
+
+[MessagePackObject]
+public sealed class WriteRequest
+{
+    [Key(0)] public long SessionId { get; set; }
+    [Key(1)] public FocasAddressDto Address { get; set; } = new();
+    [Key(2)] public int DataType { get; set; }
+    [Key(3)] public byte[]? ValueBytes { get; set; }
+    [Key(4)] public int ValueTypeCode { get; set; }
+    [Key(5)] public int TimeoutMs { get; set; } = 2000;
+}
+
+[MessagePackObject]
+public sealed class WriteResponse
+{
+    [Key(0)] public bool Success { get; set; }
+    [Key(1)] public string? Error { get; set; }
+
+    /// <summary>OPC UA status code — 0 = Good.</summary>
+    [Key(2)] public uint StatusCode { get; set; }
+}
+
+/// <summary>
+///     PMC bit read-modify-write. Handled as a first-class operation (not two separate
+///     read+write round-trips) so the critical section stays on the Host — serializing
+///     concurrent bit writers to the same parent byte is Host-side via
+///     <c>SemaphoreSlim</c> keyed on <c>(PmcLetter, Number)</c>. Mirrors the in-process
+///     pattern from <c>FocasPmcBitRmw</c>.
+/// </summary>
+[MessagePackObject]
+public sealed class PmcBitWriteRequest
+{
+    [Key(0)] public long SessionId { get; set; }
+    [Key(1)] public FocasAddressDto Address { get; set; } = new();
+
+    /// <summary>The bit index to set/clear. 0-7.</summary>
+    [Key(2)] public int BitIndex { get; set; }
+
+    [Key(3)] public bool Value { get; set; }
+    [Key(4)] public int TimeoutMs { get; set; } = 2000;
+}
+
+[MessagePackObject]
+public sealed class PmcBitWriteResponse
+{
+    [Key(0)] public bool Success { get; set; }
+    [Key(1)] public string? Error { get; set; }
+    [Key(2)] public uint StatusCode { get; set; }
+}

src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared/Contracts/Session.cs

@@ -0,0 +1,31 @@
+using MessagePack;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared.Contracts;
+
+/// <summary>
+///     Open a FOCAS session against the CNC at <see cref="HostAddress"/>. One session per
+///     configured device. The Host owns the Fwlib32 handle; the Proxy tracks only the
+///     opaque <see cref="OpenSessionResponse.SessionId"/> returned on success.
+/// </summary>
+[MessagePackObject]
+public sealed class OpenSessionRequest
+{
+    [Key(0)] public string HostAddress { get; set; } = string.Empty;
+    [Key(1)] public int TimeoutMs { get; set; } = 2000;
+    [Key(2)] public int CncSeries { get; set; }
+}
+
+[MessagePackObject]
+public sealed class OpenSessionResponse
+{
+    [Key(0)] public bool Success { get; set; }
+    [Key(1)] public long SessionId { get; set; }
+    [Key(2)] public string? Error { get; set; }
+    [Key(3)] public string? ErrorCode { get; set; }
+}
+
+[MessagePackObject]
+public sealed class CloseSessionRequest
+{
+    [Key(0)] public long SessionId { get; set; }
+}

src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared/Contracts/Subscriptions.cs

@@ -0,0 +1,61 @@
+using MessagePack;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared.Contracts;
+
+/// <summary>
+///     Subscribe the Host to polling a set of tags on behalf of the Proxy. FOCAS is
+///     poll-only — there are no CNC-initiated callbacks — so the Host runs the poll loop and
+///     pushes <see cref="OnDataChangeNotification"/> frames whenever a value differs from
+///     the last observation. Delta-only + per-group interval keeps the wire quiet.
+/// </summary>
+[MessagePackObject]
+public sealed class SubscribeRequest
+{
+    [Key(0)] public long SessionId { get; set; }
+    [Key(1)] public long SubscriptionId { get; set; }
+    [Key(2)] public int IntervalMs { get; set; } = 1000;
+    [Key(3)] public SubscribeItem[] Items { get; set; } = System.Array.Empty<SubscribeItem>();
+}
+
+[MessagePackObject]
+public sealed class SubscribeItem
+{
+    /// <summary>Opaque correlation id the Proxy uses to route notifications back to the right OPC UA MonitoredItem.</summary>
+    [Key(0)] public long MonitoredItemId { get; set; }
+
+    [Key(1)] public FocasAddressDto Address { get; set; } = new();
+    [Key(2)] public int DataType { get; set; }
+}
+
+[MessagePackObject]
+public sealed class SubscribeResponse
+{
+    [Key(0)] public bool Success { get; set; }
+    [Key(1)] public string? Error { get; set; }
+
+    /// <summary>Items the Host refused (address mismatch, unsupported type). Empty on full success.</summary>
+    [Key(2)] public long[] RejectedMonitoredItemIds { get; set; } = System.Array.Empty<long>();
+}
+
+[MessagePackObject]
+public sealed class UnsubscribeRequest
+{
+    [Key(0)] public long SubscriptionId { get; set; }
+}
+
+[MessagePackObject]
+public sealed class OnDataChangeNotification
+{
+    [Key(0)] public long SubscriptionId { get; set; }
+    [Key(1)] public DataChange[] Changes { get; set; } = System.Array.Empty<DataChange>();
+}
+
+[MessagePackObject]
+public sealed class DataChange
+{
+    [Key(0)] public long MonitoredItemId { get; set; }
+    [Key(1)] public uint StatusCode { get; set; }
+    [Key(2)] public byte[]? ValueBytes { get; set; }
+    [Key(3)] public int ValueTypeCode { get; set; }
+    [Key(4)] public long SourceTimestampUtcUnixMs { get; set; }
+}

src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared/FrameReader.cs

@@ -0,0 +1,67 @@
+using System;
+using System.IO;
+using System.Threading;
+using System.Threading.Tasks;
+using MessagePack;
+using ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared.Contracts;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared;
+
+/// <summary>
+///     Reads length-prefixed, kind-tagged frames from a stream. Single-consumer — do not call
+///     <see cref="ReadFrameAsync"/> from multiple threads against the same instance.
+/// </summary>
+public sealed class FrameReader : IDisposable
+{
+    private readonly Stream _stream;
+    private readonly bool _leaveOpen;
+
+    public FrameReader(Stream stream, bool leaveOpen = false)
+    {
+        _stream = stream ?? throw new ArgumentNullException(nameof(stream));
+        _leaveOpen = leaveOpen;
+    }
+
+    public async Task<(FocasMessageKind Kind, byte[] Body)?> ReadFrameAsync(CancellationToken ct)
+    {
+        var lengthPrefix = new byte[Framing.LengthPrefixSize];
+        if (!await ReadExactAsync(lengthPrefix, ct).ConfigureAwait(false))
+            return null;
+
+        var length = (lengthPrefix[0] << 24) | (lengthPrefix[1] << 16) | (lengthPrefix[2] << 8) | lengthPrefix[3];
+        if (length < 0 || length > Framing.MaxFrameBodyBytes)
+            throw new InvalidDataException($"IPC frame length {length} out of range.");
+
+        var kindByte = _stream.ReadByte();
+        if (kindByte < 0) throw new EndOfStreamException("EOF after length prefix, before kind byte.");
+
+        var body = new byte[length];
+        if (!await ReadExactAsync(body, ct).ConfigureAwait(false))
+            throw new EndOfStreamException("EOF mid-frame.");
+
+        return ((FocasMessageKind)(byte)kindByte, body);
+    }
+
+    public static T Deserialize<T>(byte[] body) => MessagePackSerializer.Deserialize<T>(body);
+
+    private async Task<bool> ReadExactAsync(byte[] buffer, CancellationToken ct)
+    {
+        var offset = 0;
+        while (offset < buffer.Length)
+        {
+            var read = await _stream.ReadAsync(buffer, offset, buffer.Length - offset, ct).ConfigureAwait(false);
+            if (read == 0)
+            {
+                if (offset == 0) return false;
+                throw new EndOfStreamException($"Stream ended after reading {offset} of {buffer.Length} bytes.");
+            }
+            offset += read;
+        }
+        return true;
+    }
+
+    public void Dispose()
+    {
+        if (!_leaveOpen) _stream.Dispose();
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared/FrameWriter.cs

@@ -0,0 +1,56 @@
+using System;
+using System.IO;
+using System.Threading;
+using System.Threading.Tasks;
+using MessagePack;
+using ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared.Contracts;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared;
+
+/// <summary>
+///     Writes length-prefixed, kind-tagged MessagePack frames to a stream. Thread-safe via
+///     <see cref="SemaphoreSlim"/> — multiple producers (e.g. heartbeat + data-plane sharing a
+///     stream) get serialized writes.
+/// </summary>
+public sealed class FrameWriter : IDisposable
+{
+    private readonly Stream _stream;
+    private readonly SemaphoreSlim _gate = new(1, 1);
+    private readonly bool _leaveOpen;
+
+    public FrameWriter(Stream stream, bool leaveOpen = false)
+    {
+        _stream = stream ?? throw new ArgumentNullException(nameof(stream));
+        _leaveOpen = leaveOpen;
+    }
+
+    public async Task WriteAsync<T>(FocasMessageKind kind, T message, CancellationToken ct)
+    {
+        var body = MessagePackSerializer.Serialize(message, cancellationToken: ct);
+        if (body.Length > Framing.MaxFrameBodyBytes)
+            throw new InvalidOperationException(
+                $"IPC frame body {body.Length} exceeds {Framing.MaxFrameBodyBytes} byte cap.");
+
+        var lengthPrefix = new byte[Framing.LengthPrefixSize];
+        lengthPrefix[0] = (byte)((body.Length >> 24) & 0xFF);
+        lengthPrefix[1] = (byte)((body.Length >> 16) & 0xFF);
+        lengthPrefix[2] = (byte)((body.Length >> 8)  & 0xFF);
+        lengthPrefix[3] = (byte)( body.Length        & 0xFF);
+
+        await _gate.WaitAsync(ct).ConfigureAwait(false);
+        try
+        {
+            await _stream.WriteAsync(lengthPrefix, 0, lengthPrefix.Length, ct).ConfigureAwait(false);
+            _stream.WriteByte((byte)kind);
+            await _stream.WriteAsync(body, 0, body.Length, ct).ConfigureAwait(false);
+            await _stream.FlushAsync(ct).ConfigureAwait(false);
+        }
+        finally { _gate.Release(); }
+    }
+
+    public void Dispose()
+    {
+        _gate.Dispose();
+        if (!_leaveOpen) _stream.Dispose();
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared.csproj

@@ -0,0 +1,23 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+    <PropertyGroup>
+        <TargetFramework>netstandard2.0</TargetFramework>
+        <Nullable>enable</Nullable>
+        <LangVersion>latest</LangVersion>
+        <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+        <GenerateDocumentationFile>true</GenerateDocumentationFile>
+        <NoWarn>$(NoWarn);CS1591</NoWarn>
+        <RootNamespace>ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared</RootNamespace>
+    </PropertyGroup>
+
+    <ItemGroup>
+        <!-- MessagePack for IPC. Netstandard 2.0 consumable by both .NET 10 (Proxy) + .NET 4.8 (Host). -->
+        <PackageReference Include="MessagePack" Version="2.5.187"/>
+    </ItemGroup>
+
+    <ItemGroup>
+        <NuGetAuditSuppress Include="https://github.com/advisories/GHSA-37gx-xxp4-5rgx"/>
+        <NuGetAuditSuppress Include="https://github.com/advisories/GHSA-w3x6-4m5h-cxqf"/>
+    </ItemGroup>
+
+</Project>

src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/FocasCapabilityMatrix.cs

@@ -0,0 +1,139 @@
+namespace ZB.MOM.WW.OtOpcUa.Driver.FOCAS;
+
+/// <summary>
+///     Documented-API capability matrix — per CNC series, what ranges each
+///     <see cref="FocasAreaKind"/> supports. Authoritative source for the driver's
+///     pre-flight validation in <see cref="FocasDriver.InitializeAsync"/>.
+/// </summary>
+/// <remarks>
+///     <para>Ranges come from the Fanuc FOCAS Developer Kit documentation matrix
+///     (see <c>docs/v2/focas-version-matrix.md</c> for the authoritative copy with
+///     per-function citations). Numbers chosen to match what the FOCAS library
+///     accepts — a read against an address outside the documented range returns
+///     <c>EW_NUMBER</c> or <c>EW_PARAM</c> at the wire, which this driver maps to
+///     BadOutOfRange. Catching at init time surfaces the mismatch as a config
+///     error before any session is opened.</para>
+///     <para><see cref="FocasCncSeries.Unknown"/> is treated permissively: every
+///     address passes validation. Pre-matrix configs don't break on upgrade; new
+///     deployments are encouraged to declare a series in the device options.</para>
+/// </remarks>
+public static class FocasCapabilityMatrix
+{
+    /// <summary>
+    ///     Check whether <paramref name="address"/> is accepted by a CNC of
+    ///     <paramref name="series"/>. Returns <c>null</c> on pass + a failure reason
+    ///     on reject — the driver surfaces the reason string verbatim when failing
+    ///     <c>InitializeAsync</c> so operators see the specific out-of-range without
+    ///     guessing.
+    /// </summary>
+    public static string? Validate(FocasCncSeries series, FocasAddress address)
+    {
+        if (series == FocasCncSeries.Unknown) return null;
+
+        return address.Kind switch
+        {
+            FocasAreaKind.Macro     => ValidateMacro(series, address.Number),
+            FocasAreaKind.Parameter => ValidateParameter(series, address.Number),
+            FocasAreaKind.Pmc       => ValidatePmc(series, address.PmcLetter, address.Number),
+            _ => null,
+        };
+    }
+
+    /// <summary>Macro variable number accepted by a CNC series. Cites
+    /// <c>cnc_rdmacro</c>/<c>cnc_wrmacro</c> in the Developer Kit.</summary>
+    internal static (int min, int max) MacroRange(FocasCncSeries series) => series switch
+    {
+        // Common macros 1-33 + 100-199 + 500-999 universally; extended 10000+ only on
+        // higher-end series. Using the extended ceiling per series per DevKit notes.
+        FocasCncSeries.Sixteen_i    => (0, 999),
+        FocasCncSeries.Zero_i_D     => (0, 999),
+        FocasCncSeries.Zero_i_F or
+        FocasCncSeries.Zero_i_MF or
+        FocasCncSeries.Zero_i_TF    => (0, 9999),
+        FocasCncSeries.Thirty_i or
+        FocasCncSeries.ThirtyOne_i or
+        FocasCncSeries.ThirtyTwo_i  => (0, 99999),
+        FocasCncSeries.PowerMotion_i => (0, 999),
+        _ => (0, int.MaxValue),
+    };
+
+    /// <summary>Parameter number accepted; from <c>cnc_rdparam</c>/<c>cnc_wrparam</c>.
+    /// Ranges reflect the highest-numbered parameter documented per series.</summary>
+    internal static (int min, int max) ParameterRange(FocasCncSeries series) => series switch
+    {
+        FocasCncSeries.Sixteen_i    => (0, 9999),
+        FocasCncSeries.Zero_i_D or
+        FocasCncSeries.Zero_i_F or
+        FocasCncSeries.Zero_i_MF or
+        FocasCncSeries.Zero_i_TF    => (0, 14999),
+        FocasCncSeries.Thirty_i or
+        FocasCncSeries.ThirtyOne_i or
+        FocasCncSeries.ThirtyTwo_i  => (0, 29999),
+        FocasCncSeries.PowerMotion_i => (0, 29999),
+        _ => (0, int.MaxValue),
+    };
+
+    /// <summary>PMC letters accepted per series. Legacy controllers omit F/M/C
+    /// signal groups that 30i-family ladder programs use.</summary>
+    internal static IReadOnlySet<string> PmcLetters(FocasCncSeries series) => series switch
+    {
+        FocasCncSeries.Sixteen_i     => new HashSet<string>(StringComparer.OrdinalIgnoreCase) { "X", "Y", "R", "D" },
+        FocasCncSeries.Zero_i_D      => new HashSet<string>(StringComparer.OrdinalIgnoreCase) { "X", "Y", "R", "D", "E", "A" },
+        FocasCncSeries.Zero_i_F or
+        FocasCncSeries.Zero_i_MF or
+        FocasCncSeries.Zero_i_TF     => new HashSet<string>(StringComparer.OrdinalIgnoreCase) { "X", "Y", "F", "G", "R", "D", "E", "A", "M", "C" },
+        FocasCncSeries.Thirty_i or
+        FocasCncSeries.ThirtyOne_i or
+        FocasCncSeries.ThirtyTwo_i   => new HashSet<string>(StringComparer.OrdinalIgnoreCase) { "X", "Y", "F", "G", "R", "D", "E", "A", "M", "C", "K", "T" },
+        FocasCncSeries.PowerMotion_i => new HashSet<string>(StringComparer.OrdinalIgnoreCase) { "X", "Y", "R", "D" },
+        _ => new HashSet<string>(StringComparer.OrdinalIgnoreCase),
+    };
+
+    /// <summary>PMC address-number ceiling per series. Multiplied by 8 to get bit
+    /// count since PMC addresses are byte-addressed on read + bit-addressed on
+    /// write — FocasAddress carries the bit separately.</summary>
+    internal static int PmcMaxNumber(FocasCncSeries series) => series switch
+    {
+        FocasCncSeries.Sixteen_i    => 999,
+        FocasCncSeries.Zero_i_D     => 1999,
+        FocasCncSeries.Zero_i_F or
+        FocasCncSeries.Zero_i_MF or
+        FocasCncSeries.Zero_i_TF    => 9999,
+        FocasCncSeries.Thirty_i or
+        FocasCncSeries.ThirtyOne_i or
+        FocasCncSeries.ThirtyTwo_i  => 59999,
+        FocasCncSeries.PowerMotion_i => 1999,
+        _ => int.MaxValue,
+    };
+
+    private static string? ValidateMacro(FocasCncSeries series, int number)
+    {
+        var (min, max) = MacroRange(series);
+        return (number < min || number > max)
+            ? $"Macro variable #{number} is outside the documented range [{min}, {max}] for {series}."
+            : null;
+    }
+
+    private static string? ValidateParameter(FocasCncSeries series, int number)
+    {
+        var (min, max) = ParameterRange(series);
+        return (number < min || number > max)
+            ? $"Parameter #{number} is outside the documented range [{min}, {max}] for {series}."
+            : null;
+    }
+
+    private static string? ValidatePmc(FocasCncSeries series, string? letter, int number)
+    {
+        if (string.IsNullOrEmpty(letter)) return "PMC address is missing its letter prefix.";
+        var letters = PmcLetters(series);
+        if (!letters.Contains(letter))
+        {
+            var letterList = string.Join(", ", letters);
+            return $"PMC letter '{letter}' is not supported on {series}. Accepted: {{{letterList}}}.";
+        }
+        var max = PmcMaxNumber(series);
+        return number > max
+            ? $"PMC address {letter}{number} is outside the documented range [0, {max}] for {series}."
+            : null;
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/FocasCncSeries.cs

@@ -0,0 +1,47 @@
+namespace ZB.MOM.WW.OtOpcUa.Driver.FOCAS;
+
+/// <summary>
+///     Fanuc CNC controller series. Used by <see cref="FocasCapabilityMatrix"/> to
+///     gate which FOCAS addresses + value ranges the driver accepts against a given
+///     CNC — the FOCAS API surface varies meaningfully between series (macro ranges,
+///     PMC address letters, parameter numbers). A tag reference that's valid on a
+///     30i might be out-of-range on an 0i-MF; validating at driver
+///     <c>InitializeAsync</c> time surfaces the mismatch as a fast config error
+///     instead of a runtime read failure after the server's already running.
+/// </summary>
+/// <remarks>
+///     <para>Values chosen from the Fanuc FOCAS Developer Kit documented series
+///     matrix. Add a new entry + a row to <see cref="FocasCapabilityMatrix"/> when
+///     a new controller is targeted — the driver will refuse the device until both
+///     sides of the enum are filled in.</para>
+///     <para>Defaults to <see cref="Unknown"/> when the operator doesn't specify;
+///     the capability matrix treats Unknown as permissive (no range validation,
+///     same as pre-matrix behaviour) so old configs don't break on upgrade.</para>
+/// </remarks>
+public enum FocasCncSeries
+{
+    /// <summary>No series declared; capability matrix is permissive (legacy behaviour).</summary>
+    Unknown = 0,
+
+    /// <summary>Series 0i-D — compact CNC, narrow macro + PMC ranges.</summary>
+    Zero_i_D,
+    /// <summary>Series 0i-F — successor to 0i-D; widened macro range, added Plus variant.</summary>
+    Zero_i_F,
+    /// <summary>Series 0i-MF / 0i-MF Plus — machining-centre variants of 0i-F.</summary>
+    Zero_i_MF,
+    /// <summary>Series 0i-TF / 0i-TF Plus — turning-centre variants of 0i-F.</summary>
+    Zero_i_TF,
+
+    /// <summary>Series 16i / 18i / 21i — mid-range legacy; narrow ranges, limited PMC letters.</summary>
+    Sixteen_i,
+
+    /// <summary>Series 30i — high-end; widest macro / PMC / parameter ranges.</summary>
+    Thirty_i,
+    /// <summary>Series 31i — subset of 30i (fewer axes, same FOCAS surface).</summary>
+    ThirtyOne_i,
+    /// <summary>Series 32i — compact 30i variant.</summary>
+    ThirtyTwo_i,
+
+    /// <summary>Power Motion i — motion-control variant; atypical macro coverage.</summary>
+    PowerMotion_i,
+}

src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/FocasDriver.cs

@@ -57,7 +57,24 @@ public sealed class FocasDriver : IDriver, IReadable, IWritable, ITagDiscovery,
                         $"FOCAS device has invalid HostAddress '{device.HostAddress}' — expected 'focas://{{ip}}[:{{port}}]'.");
                 _devices[device.HostAddress] = new DeviceState(addr, device);
             }
-            foreach (var tag in _options.Tags) _tagsByName[tag.Name] = tag;
+            // Pre-flight: validate every tag's address against the declared CNC
+            // series so misconfigured addresses fail at init (clear config error)
+            // instead of producing BadOutOfRange on every read at runtime.
+            // Series=Unknown short-circuits the matrix; pre-matrix configs stay permissive.
+            foreach (var tag in _options.Tags)
+            {
+                var parsed = FocasAddress.TryParse(tag.Address)
+                    ?? throw new InvalidOperationException(
+                        $"FOCAS tag '{tag.Name}' has invalid Address '{tag.Address}'. " +
+                        $"Expected forms: R100, R100.3, PARAM:1815/0, MACRO:500.");
+                if (_devices.TryGetValue(tag.DeviceHostAddress, out var device)
+                    && FocasCapabilityMatrix.Validate(device.Options.Series, parsed) is { } reason)
+                {
+                    throw new InvalidOperationException(
+                        $"FOCAS tag '{tag.Name}' ({tag.Address}) rejected by capability matrix: {reason}");
+                }
+                _tagsByName[tag.Name] = tag;
+            }
 
             if (_options.Probe.Enabled)
             {

src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/FocasDriverOptions.cs

@@ -13,9 +13,15 @@ public sealed class FocasDriverOptions
     public TimeSpan Timeout { get; init; } = TimeSpan.FromSeconds(2);
 }
 
+/// <summary>
+///     One CNC the driver talks to. <paramref name="Series"/> enables per-series
+///     address validation at <see cref="FocasDriver.InitializeAsync"/>; leave as
+///     <see cref="FocasCncSeries.Unknown"/> to skip validation (legacy behaviour).
+/// </summary>
 public sealed record FocasDeviceOptions(
     string HostAddress,
-    string? DeviceName = null);
+    string? DeviceName = null,
+    FocasCncSeries Series = FocasCncSeries.Unknown);
 
 /// <summary>
 ///     One FOCAS-backed OPC UA variable. <paramref name="Address"/> is the canonical FOCAS

src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/Ipc/FocasIpcClient.cs

@@ -0,0 +1,120 @@
+using System.IO;
+using System.IO.Pipes;
+using MessagePack;
+using ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared;
+using ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared.Contracts;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Ipc;
+
+/// <summary>
+///     Proxy-side IPC channel to a running <c>Driver.FOCAS.Host</c>. Owns the pipe connection
+///     and serializes request/response round-trips through a single call gate so
+///     concurrent callers don't interleave frames. One instance per FOCAS Host session.
+/// </summary>
+public sealed class FocasIpcClient : IAsyncDisposable
+{
+    private readonly Stream _stream;
+    private readonly FrameReader _reader;
+    private readonly FrameWriter _writer;
+    private readonly SemaphoreSlim _callGate = new(1, 1);
+
+    private FocasIpcClient(Stream stream)
+    {
+        _stream = stream;
+        _reader = new FrameReader(stream, leaveOpen: true);
+        _writer = new FrameWriter(stream, leaveOpen: true);
+    }
+
+    /// <summary>Named-pipe factory: connects, sends Hello, awaits HelloAck.</summary>
+    public static async Task<FocasIpcClient> ConnectAsync(
+        string pipeName, string sharedSecret, TimeSpan connectTimeout, CancellationToken ct)
+    {
+        var stream = new NamedPipeClientStream(
+            serverName: ".",
+            pipeName: pipeName,
+            direction: PipeDirection.InOut,
+            options: PipeOptions.Asynchronous);
+
+        await stream.ConnectAsync((int)connectTimeout.TotalMilliseconds, ct);
+        return await HandshakeAsync(stream, sharedSecret, ct).ConfigureAwait(false);
+    }
+
+    /// <summary>
+    ///     Stream factory — used by tests that wire the Proxy against an in-memory stream
+    ///     pair instead of a real pipe. <paramref name="stream"/> is owned by the caller
+    ///     until <see cref="DisposeAsync"/>.
+    /// </summary>
+    public static Task<FocasIpcClient> ConnectAsync(Stream stream, string sharedSecret, CancellationToken ct)
+        => HandshakeAsync(stream, sharedSecret, ct);
+
+    private static async Task<FocasIpcClient> HandshakeAsync(Stream stream, string sharedSecret, CancellationToken ct)
+    {
+        var client = new FocasIpcClient(stream);
+        try
+        {
+            await client._writer.WriteAsync(FocasMessageKind.Hello,
+                new Hello { PeerName = "FOCAS.Proxy", SharedSecret = sharedSecret }, ct).ConfigureAwait(false);
+
+            var ack = await client._reader.ReadFrameAsync(ct).ConfigureAwait(false);
+            if (ack is null || ack.Value.Kind != FocasMessageKind.HelloAck)
+                throw new InvalidOperationException("Did not receive HelloAck from FOCAS.Host");
+
+            var ackMsg = FrameReader.Deserialize<HelloAck>(ack.Value.Body);
+            if (!ackMsg.Accepted)
+                throw new UnauthorizedAccessException($"FOCAS.Host rejected Hello: {ackMsg.RejectReason}");
+
+            return client;
+        }
+        catch
+        {
+            await client.DisposeAsync().ConfigureAwait(false);
+            throw;
+        }
+    }
+
+    public async Task<TResp> CallAsync<TReq, TResp>(
+        FocasMessageKind requestKind, TReq request, FocasMessageKind expectedResponseKind, CancellationToken ct)
+    {
+        await _callGate.WaitAsync(ct).ConfigureAwait(false);
+        try
+        {
+            await _writer.WriteAsync(requestKind, request, ct).ConfigureAwait(false);
+
+            var frame = await _reader.ReadFrameAsync(ct).ConfigureAwait(false);
+            if (frame is null) throw new EndOfStreamException("FOCAS IPC peer closed before response");
+
+            if (frame.Value.Kind == FocasMessageKind.ErrorResponse)
+            {
+                var err = MessagePackSerializer.Deserialize<ErrorResponse>(frame.Value.Body);
+                throw new FocasIpcException(err.Code, err.Message);
+            }
+
+            if (frame.Value.Kind != expectedResponseKind)
+                throw new InvalidOperationException(
+                    $"Expected {expectedResponseKind}, got {frame.Value.Kind}");
+
+            return MessagePackSerializer.Deserialize<TResp>(frame.Value.Body);
+        }
+        finally { _callGate.Release(); }
+    }
+
+    public async Task SendOneWayAsync<TReq>(FocasMessageKind requestKind, TReq request, CancellationToken ct)
+    {
+        await _callGate.WaitAsync(ct).ConfigureAwait(false);
+        try { await _writer.WriteAsync(requestKind, request, ct).ConfigureAwait(false); }
+        finally { _callGate.Release(); }
+    }
+
+    public async ValueTask DisposeAsync()
+    {
+        _callGate.Dispose();
+        _reader.Dispose();
+        _writer.Dispose();
+        await _stream.DisposeAsync().ConfigureAwait(false);
+    }
+}
+
+public sealed class FocasIpcException(string code, string message) : Exception($"[{code}] {message}")
+{
+    public string Code { get; } = code;
+}

src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/Ipc/IpcFocasClient.cs

@@ -0,0 +1,199 @@
+using MessagePack;
+using ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared.Contracts;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Ipc;
+
+/// <summary>
+///     <see cref="IFocasClient"/> implementation that forwards every operation over a
+///     <see cref="FocasIpcClient"/> to a <c>Driver.FOCAS.Host</c> process. Keeps the
+///     <c>Fwlib32.dll</c> P/Invoke out of the main server process so a native crash
+///     blast-radius stops at the Host boundary.
+/// </summary>
+/// <remarks>
+///     Session lifecycle: <see cref="ConnectAsync"/> sends <c>OpenSessionRequest</c> and
+///     caches the returned <c>SessionId</c>. Subsequent <see cref="ReadAsync"/> /
+///     <see cref="WriteAsync"/> / <see cref="ProbeAsync"/> calls thread that session id
+///     onto each request DTO. <see cref="Dispose"/> sends <c>CloseSessionRequest</c> +
+///     disposes the underlying pipe.
+/// </remarks>
+public sealed class IpcFocasClient : IFocasClient
+{
+    private readonly FocasIpcClient _ipc;
+    private readonly FocasCncSeries _series;
+    private long _sessionId;
+    private bool _connected;
+
+    public IpcFocasClient(FocasIpcClient ipc, FocasCncSeries series = FocasCncSeries.Unknown)
+    {
+        _ipc = ipc ?? throw new ArgumentNullException(nameof(ipc));
+        _series = series;
+    }
+
+    public bool IsConnected => _connected;
+
+    public async Task ConnectAsync(FocasHostAddress address, TimeSpan timeout, CancellationToken cancellationToken)
+    {
+        if (_connected) return;
+
+        var resp = await _ipc.CallAsync<OpenSessionRequest, OpenSessionResponse>(
+            FocasMessageKind.OpenSessionRequest,
+            new OpenSessionRequest
+            {
+                HostAddress = $"{address.Host}:{address.Port}",
+                TimeoutMs = (int)Math.Max(1, timeout.TotalMilliseconds),
+                CncSeries = (int)_series,
+            },
+            FocasMessageKind.OpenSessionResponse,
+            cancellationToken).ConfigureAwait(false);
+
+        if (!resp.Success)
+            throw new InvalidOperationException(
+                $"FOCAS Host rejected OpenSession for {address}: {resp.ErrorCode ?? "?"} — {resp.Error}");
+
+        _sessionId = resp.SessionId;
+        _connected = true;
+    }
+
+    public async Task<(object? value, uint status)> ReadAsync(
+        FocasAddress address, FocasDataType type, CancellationToken cancellationToken)
+    {
+        if (!_connected) return (null, FocasStatusMapper.BadCommunicationError);
+
+        var resp = await _ipc.CallAsync<ReadRequest, ReadResponse>(
+            FocasMessageKind.ReadRequest,
+            new ReadRequest
+            {
+                SessionId = _sessionId,
+                Address = ToDto(address),
+                DataType = (int)type,
+            },
+            FocasMessageKind.ReadResponse,
+            cancellationToken).ConfigureAwait(false);
+
+        if (!resp.Success) return (null, resp.StatusCode);
+
+        var value = DecodeValue(resp.ValueBytes, resp.ValueTypeCode);
+        return (value, resp.StatusCode);
+    }
+
+    public async Task<uint> WriteAsync(
+        FocasAddress address, FocasDataType type, object? value, CancellationToken cancellationToken)
+    {
+        if (!_connected) return FocasStatusMapper.BadCommunicationError;
+
+        // PMC bit writes get the first-class RMW frame so the critical section stays on the Host.
+        if (address.Kind == FocasAreaKind.Pmc && type == FocasDataType.Bit && address.BitIndex is int bit)
+        {
+            var bitResp = await _ipc.CallAsync<PmcBitWriteRequest, PmcBitWriteResponse>(
+                FocasMessageKind.PmcBitWriteRequest,
+                new PmcBitWriteRequest
+                {
+                    SessionId = _sessionId,
+                    Address = ToDto(address),
+                    BitIndex = bit,
+                    Value = Convert.ToBoolean(value),
+                },
+                FocasMessageKind.PmcBitWriteResponse,
+                cancellationToken).ConfigureAwait(false);
+            return bitResp.StatusCode;
+        }
+
+        var resp = await _ipc.CallAsync<WriteRequest, WriteResponse>(
+            FocasMessageKind.WriteRequest,
+            new WriteRequest
+            {
+                SessionId = _sessionId,
+                Address = ToDto(address),
+                DataType = (int)type,
+                ValueTypeCode = (int)type,
+                ValueBytes = EncodeValue(value, type),
+            },
+            FocasMessageKind.WriteResponse,
+            cancellationToken).ConfigureAwait(false);
+
+        return resp.StatusCode;
+    }
+
+    public async Task<bool> ProbeAsync(CancellationToken cancellationToken)
+    {
+        if (!_connected) return false;
+        try
+        {
+            var resp = await _ipc.CallAsync<ProbeRequest, ProbeResponse>(
+                FocasMessageKind.ProbeRequest,
+                new ProbeRequest { SessionId = _sessionId },
+                FocasMessageKind.ProbeResponse,
+                cancellationToken).ConfigureAwait(false);
+            return resp.Healthy;
+        }
+        catch { return false; }
+    }
+
+    public void Dispose()
+    {
+        if (_connected)
+        {
+            try
+            {
+                _ipc.SendOneWayAsync(FocasMessageKind.CloseSessionRequest,
+                    new CloseSessionRequest { SessionId = _sessionId }, CancellationToken.None)
+                    .GetAwaiter().GetResult();
+            }
+            catch { /* best effort */ }
+            _connected = false;
+        }
+        _ipc.DisposeAsync().AsTask().GetAwaiter().GetResult();
+    }
+
+    private static FocasAddressDto ToDto(FocasAddress addr) => new()
+    {
+        Kind = (int)addr.Kind,
+        PmcLetter = addr.PmcLetter,
+        Number = addr.Number,
+        BitIndex = addr.BitIndex,
+    };
+
+    private static byte[]? EncodeValue(object? value, FocasDataType type)
+    {
+        if (value is null) return null;
+        return type switch
+        {
+            FocasDataType.Bit     => MessagePackSerializer.Serialize(Convert.ToBoolean(value)),
+            FocasDataType.Byte    => MessagePackSerializer.Serialize(Convert.ToByte(value)),
+            FocasDataType.Int16   => MessagePackSerializer.Serialize(Convert.ToInt16(value)),
+            FocasDataType.Int32   => MessagePackSerializer.Serialize(Convert.ToInt32(value)),
+            FocasDataType.Float32 => MessagePackSerializer.Serialize(Convert.ToSingle(value)),
+            FocasDataType.Float64 => MessagePackSerializer.Serialize(Convert.ToDouble(value)),
+            FocasDataType.String  => MessagePackSerializer.Serialize(Convert.ToString(value) ?? string.Empty),
+            _ => MessagePackSerializer.Serialize(Convert.ToInt32(value)),
+        };
+    }
+
+    private static object? DecodeValue(byte[]? bytes, int typeCode)
+    {
+        if (bytes is null) return null;
+        return typeCode switch
+        {
+            FocasDataTypeCode.Bit     => MessagePackSerializer.Deserialize<bool>(bytes),
+            FocasDataTypeCode.Byte    => MessagePackSerializer.Deserialize<byte>(bytes),
+            FocasDataTypeCode.Int16   => MessagePackSerializer.Deserialize<short>(bytes),
+            FocasDataTypeCode.Int32   => MessagePackSerializer.Deserialize<int>(bytes),
+            FocasDataTypeCode.Float32 => MessagePackSerializer.Deserialize<float>(bytes),
+            FocasDataTypeCode.Float64 => MessagePackSerializer.Deserialize<double>(bytes),
+            FocasDataTypeCode.String  => MessagePackSerializer.Deserialize<string>(bytes),
+            _ => MessagePackSerializer.Deserialize<int>(bytes),
+        };
+    }
+}
+
+/// <summary>
+///     Factory producing <see cref="IpcFocasClient"/>s. One pipe connection per
+///     <c>IFocasClient</c> — matches the driver's one-client-per-device invariant. The
+///     deployment wires this into the DI container in place of
+///     <see cref="UnimplementedFocasClientFactory"/>.
+/// </summary>
+public sealed class IpcFocasClientFactory(Func<FocasIpcClient> ipcClientFactory, FocasCncSeries series = FocasCncSeries.Unknown)
+    : IFocasClientFactory
+{
+    public IFocasClient Create() => new IpcFocasClient(ipcClientFactory(), series);
+}

src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/Supervisor/Backoff.cs

@@ -0,0 +1,30 @@
+namespace ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Supervisor;
+
+/// <summary>
+///     Respawn-with-backoff schedule for the FOCAS Host process. Matches Galaxy Tier-C:
+///     5s → 15s → 60s cap. A sustained stable run (default 2 min) resets the index so a
+///     one-off crash after hours of steady-state doesn't start from the top of the ladder.
+/// </summary>
+public sealed class Backoff
+{
+    public static TimeSpan[] DefaultSequence { get; } =
+        [TimeSpan.FromSeconds(5), TimeSpan.FromSeconds(15), TimeSpan.FromSeconds(60)];
+
+    public TimeSpan StableRunThreshold { get; init; } = TimeSpan.FromMinutes(2);
+
+    private readonly TimeSpan[] _sequence;
+    private int _index;
+
+    public Backoff(TimeSpan[]? sequence = null) => _sequence = sequence ?? DefaultSequence;
+
+    public TimeSpan Next()
+    {
+        var delay = _sequence[Math.Min(_index, _sequence.Length - 1)];
+        _index++;
+        return delay;
+    }
+
+    public void RecordStableRun() => _index = 0;
+
+    public int AttemptIndex => _index;
+}

src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/Supervisor/CircuitBreaker.cs

@@ -0,0 +1,69 @@
+namespace ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Supervisor;
+
+/// <summary>
+///     Crash-loop circuit breaker for the FOCAS Host. Matches Galaxy Tier-C defaults:
+///     3 crashes within 5 minutes opens the breaker; cooldown escalates 1h → 4h → manual
+///     reset. A sticky alert stays live until the operator explicitly clears it so
+///     recurring crashes can't silently burn through the cooldown ladder overnight.
+/// </summary>
+public sealed class CircuitBreaker
+{
+    public int CrashesAllowedPerWindow { get; init; } = 3;
+    public TimeSpan Window { get; init; } = TimeSpan.FromMinutes(5);
+
+    public TimeSpan[] CooldownEscalation { get; init; } =
+        [TimeSpan.FromHours(1), TimeSpan.FromHours(4), TimeSpan.MaxValue];
+
+    private readonly List<DateTime> _crashesUtc = [];
+    private DateTime? _openSinceUtc;
+    private int _escalationLevel;
+    public bool StickyAlertActive { get; private set; }
+
+    /// <summary>
+    ///     Records a crash + returns <c>true</c> if the supervisor may respawn. On
+    ///     <c>false</c>, <paramref name="cooldownRemaining"/> is how long to wait before
+    ///     trying again (<c>TimeSpan.MaxValue</c> means manual reset required).
+    /// </summary>
+    public bool TryRecordCrash(DateTime utcNow, out TimeSpan cooldownRemaining)
+    {
+        if (_openSinceUtc is { } openedAt)
+        {
+            var cooldown = CooldownEscalation[Math.Min(_escalationLevel, CooldownEscalation.Length - 1)];
+            if (cooldown == TimeSpan.MaxValue)
+            {
+                cooldownRemaining = TimeSpan.MaxValue;
+                return false;
+            }
+            if (utcNow - openedAt < cooldown)
+            {
+                cooldownRemaining = cooldown - (utcNow - openedAt);
+                return false;
+            }
+
+            _openSinceUtc = null;
+            _escalationLevel++;
+        }
+
+        _crashesUtc.RemoveAll(t => utcNow - t > Window);
+        _crashesUtc.Add(utcNow);
+
+        if (_crashesUtc.Count > CrashesAllowedPerWindow)
+        {
+            _openSinceUtc = utcNow;
+            StickyAlertActive = true;
+            cooldownRemaining = CooldownEscalation[Math.Min(_escalationLevel, CooldownEscalation.Length - 1)];
+            return false;
+        }
+
+        cooldownRemaining = TimeSpan.Zero;
+        return true;
+    }
+
+    public void ManualReset()
+    {
+        _crashesUtc.Clear();
+        _openSinceUtc = null;
+        _escalationLevel = 0;
+        StickyAlertActive = false;
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/Supervisor/FocasHostSupervisor.cs

@@ -0,0 +1,159 @@
+namespace ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Supervisor;
+
+/// <summary>
+///     Ties <see cref="IHostProcessLauncher"/> + <see cref="Backoff"/> +
+///     <see cref="CircuitBreaker"/> + <see cref="HeartbeatMonitor"/> into one object the
+///     driver asks for <c>IFocasClient</c>s. On a detected crash (process exit or
+///     heartbeat loss) the supervisor fans out <c>BadCommunicationError</c> to all
+///     subscribers via the <see cref="OnUnavailable"/> callback, then respawns with
+///     backoff unless the breaker is open.
+/// </summary>
+/// <remarks>
+///     The supervisor itself is I/O-free — it doesn't know how to spawn processes, probe
+///     pipes, or send heartbeats. Production wires the concrete
+///     <see cref="IHostProcessLauncher"/> over <c>FocasIpcClient</c> + <c>Process</c>;
+///     tests drive the same state machine with a deterministic launcher stub.
+/// </remarks>
+public sealed class FocasHostSupervisor : IDisposable
+{
+    private readonly IHostProcessLauncher _launcher;
+    private readonly Backoff _backoff;
+    private readonly CircuitBreaker _breaker;
+    private readonly Func<DateTime> _clock;
+    private IFocasClient? _current;
+    private DateTime _currentStartedUtc;
+    private bool _disposed;
+
+    public FocasHostSupervisor(
+        IHostProcessLauncher launcher,
+        Backoff? backoff = null,
+        CircuitBreaker? breaker = null,
+        Func<DateTime>? clock = null)
+    {
+        _launcher = launcher ?? throw new ArgumentNullException(nameof(launcher));
+        _backoff = backoff ?? new Backoff();
+        _breaker = breaker ?? new CircuitBreaker();
+        _clock = clock ?? (() => DateTime.UtcNow);
+    }
+
+    /// <summary>Raised with a short reason string whenever the Host goes unavailable (crash / heartbeat loss / breaker-open).</summary>
+    public event Action<string>? OnUnavailable;
+
+    /// <summary>Crash count observed in the current process lifetime. Exposed for /hosts Admin telemetry.</summary>
+    public int ObservedCrashes { get; private set; }
+
+    /// <summary><c>true</c> if the crash-loop breaker has latched a sticky alert that needs operator reset.</summary>
+    public bool StickyAlertActive => _breaker.StickyAlertActive;
+
+    public int BackoffAttempt => _backoff.AttemptIndex;
+
+    /// <summary>
+    ///     Returns the current live client. If none, tries to launch — applying the
+    ///     backoff schedule between attempts and stopping once the breaker opens.
+    /// </summary>
+    public async Task<IFocasClient> GetOrLaunchAsync(CancellationToken ct)
+    {
+        ThrowIfDisposed();
+        if (_current is not null && _launcher.IsProcessAlive) return _current;
+
+        return await LaunchWithBackoffAsync(ct).ConfigureAwait(false);
+    }
+
+    /// <summary>
+    ///     Called by the heartbeat task each time a miss threshold is crossed.
+    ///     Treated as a crash: fan out Bad status + attempt respawn.
+    /// </summary>
+    public async Task NotifyHostDeadAsync(string reason, CancellationToken ct)
+    {
+        ThrowIfDisposed();
+        OnUnavailable?.Invoke(reason);
+        ObservedCrashes++;
+        try { await _launcher.TerminateAsync(ct).ConfigureAwait(false); }
+        catch { /* best effort */ }
+        _current?.Dispose();
+        _current = null;
+
+        if (!_breaker.TryRecordCrash(_clock(), out var cooldown))
+        {
+            OnUnavailable?.Invoke(cooldown == TimeSpan.MaxValue
+                ? "circuit-breaker-open-manual-reset-required"
+                : $"circuit-breaker-open-cooldown-{cooldown:g}");
+            return;
+        }
+        // Successful crash recording — do not respawn synchronously; GetOrLaunchAsync will
+        // pick up the attempt on the next call. Keeps the fan-out fast.
+    }
+
+    /// <summary>Operator action — clear the sticky alert + reset the breaker.</summary>
+    public void AcknowledgeAndReset()
+    {
+        _breaker.ManualReset();
+        _backoff.RecordStableRun();
+    }
+
+    private async Task<IFocasClient> LaunchWithBackoffAsync(CancellationToken ct)
+    {
+        while (true)
+        {
+            if (_breaker.StickyAlertActive)
+            {
+                if (!_breaker.TryRecordCrash(_clock(), out var cooldown) && cooldown == TimeSpan.MaxValue)
+                    throw new InvalidOperationException(
+                        "FOCAS Host circuit breaker is open and awaiting manual reset. " +
+                        "See Admin /hosts; call AcknowledgeAndReset after investigating the Host log.");
+            }
+
+            try
+            {
+                _current = await _launcher.LaunchAsync(ct).ConfigureAwait(false);
+                _currentStartedUtc = _clock();
+
+                // If the launch sequence itself takes long enough to count as a stable run,
+                // reset the backoff ladder immediately.
+                if (_clock() - _currentStartedUtc >= _backoff.StableRunThreshold)
+                    _backoff.RecordStableRun();
+
+                return _current;
+            }
+            catch (Exception ex) when (ex is not OperationCanceledException)
+            {
+                OnUnavailable?.Invoke($"launch-failed: {ex.Message}");
+                ObservedCrashes++;
+                if (!_breaker.TryRecordCrash(_clock(), out var cooldown))
+                {
+                    var hint = cooldown == TimeSpan.MaxValue
+                        ? "manual reset required"
+                        : $"cooldown {cooldown:g}";
+                    throw new InvalidOperationException(
+                        $"FOCAS Host circuit breaker opened after {ObservedCrashes} crashes — {hint}.", ex);
+                }
+
+                var delay = _backoff.Next();
+                await Task.Delay(delay, ct).ConfigureAwait(false);
+            }
+        }
+    }
+
+    /// <summary>Called from the heartbeat loop after a successful ack run — relaxes the backoff ladder.</summary>
+    public void NotifyStableRun()
+    {
+        if (_current is null) return;
+        if (_clock() - _currentStartedUtc >= _backoff.StableRunThreshold)
+            _backoff.RecordStableRun();
+    }
+
+    public void Dispose()
+    {
+        if (_disposed) return;
+        _disposed = true;
+        try { _launcher.TerminateAsync(CancellationToken.None).GetAwaiter().GetResult(); }
+        catch { /* best effort */ }
+        _current?.Dispose();
+        _current = null;
+    }
+
+    private void ThrowIfDisposed()
+    {
+        if (_disposed) throw new ObjectDisposedException(nameof(FocasHostSupervisor));
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/Supervisor/HeartbeatMonitor.cs

@@ -0,0 +1,29 @@
+namespace ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Supervisor;
+
+/// <summary>
+///     Tracks missed heartbeats from the FOCAS Host. 2s cadence + 3 consecutive misses =
+///     host declared dead (~6s detection). Same defaults as Galaxy Tier-C so operators
+///     see the same cadence across hosts on the /hosts Admin page.
+/// </summary>
+public sealed class HeartbeatMonitor
+{
+    public int MissesUntilDead { get; init; } = 3;
+
+    public TimeSpan Cadence { get; init; } = TimeSpan.FromSeconds(2);
+
+    public int ConsecutiveMisses { get; private set; }
+    public DateTime? LastAckUtc { get; private set; }
+
+    public void RecordAck(DateTime utcNow)
+    {
+        ConsecutiveMisses = 0;
+        LastAckUtc = utcNow;
+    }
+
+    /// <summary>Records a missed heartbeat; returns <c>true</c> when the death threshold is crossed.</summary>
+    public bool RecordMiss()
+    {
+        ConsecutiveMisses++;
+        return ConsecutiveMisses >= MissesUntilDead;
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/Supervisor/IHostProcessLauncher.cs

@@ -0,0 +1,32 @@
+namespace ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Supervisor;
+
+/// <summary>
+///     Abstraction over the act of spawning a FOCAS Host process and obtaining an
+///     <see cref="IFocasClient"/> connected to it. Production wires this to a real
+///     <c>Process.Start</c> + <c>FocasIpcClient.ConnectAsync</c>; tests use a fake that
+///     exposes deterministic failure modes so the supervisor logic can be stressed
+///     without spawning actual exes.
+/// </summary>
+public interface IHostProcessLauncher
+{
+    /// <summary>
+    ///     Spawn a new Host process (if one isn't already running) and return a live
+    ///     client session. Throws on unrecoverable errors; transient errors (e.g. Host
+    ///     not ready yet) should throw <see cref="TimeoutException"/> so the supervisor
+    ///     applies the backoff ladder.
+    /// </summary>
+    Task<IFocasClient> LaunchAsync(CancellationToken ct);
+
+    /// <summary>
+    ///     Terminate the Host process if one is running. Called on Dispose and after a
+    ///     heartbeat loss is detected.
+    /// </summary>
+    Task TerminateAsync(CancellationToken ct);
+
+    /// <summary>
+    ///     <c>true</c> when the most recently spawned Host process is still alive.
+    ///     Supervisor polls this at heartbeat cadence; going <c>false</c> without a
+    ///     clean shutdown counts as a crash.
+    /// </summary>
+    bool IsProcessAlive { get; }
+}

src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/Supervisor/PostMortemReader.cs

@@ -0,0 +1,57 @@
+using System.IO.MemoryMappedFiles;
+using System.Text;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Supervisor;
+
+/// <summary>
+///     Proxy-side reader for the Host's post-mortem MMF. After a Host crash the supervisor
+///     opens the file (which persists beyond the process lifetime) and enumerates the last
+///     few thousand IPC operations that were in flight. Format matches
+///     <c>Driver.FOCAS.Host.Stability.PostMortemMmf</c> — magic 'OFPC' / 256-byte entries.
+/// </summary>
+public sealed class PostMortemReader
+{
+    private const int Magic = 0x4F465043; // 'OFPC'
+    private const int HeaderBytes = 16;
+    private const int EntryBytes = 256;
+    private const int MessageOffset = 16;
+    private const int MessageCapacity = EntryBytes - MessageOffset;
+
+    public string Path { get; }
+
+    public PostMortemReader(string path) => Path = path;
+
+    public PostMortemEntry[] ReadAll()
+    {
+        if (!File.Exists(Path)) return [];
+
+        using var mmf = MemoryMappedFile.CreateFromFile(Path, FileMode.Open, null, 0, MemoryMappedFileAccess.Read);
+        using var accessor = mmf.CreateViewAccessor(0, 0, MemoryMappedFileAccess.Read);
+
+        if (accessor.ReadInt32(0) != Magic) return [];
+
+        var capacity = accessor.ReadInt32(8);
+        var writeIndex = accessor.ReadInt32(12);
+        var entries = new PostMortemEntry[capacity];
+        var count = 0;
+
+        for (var i = 0; i < capacity; i++)
+        {
+            var slot = (writeIndex + i) % capacity;
+            var offset = HeaderBytes + slot * EntryBytes;
+            var ts = accessor.ReadInt64(offset + 0);
+            if (ts == 0) continue;
+            var op = accessor.ReadInt64(offset + 8);
+            var msgBuf = new byte[MessageCapacity];
+            accessor.ReadArray(offset + MessageOffset, msgBuf, 0, MessageCapacity);
+            var nulTerm = Array.IndexOf<byte>(msgBuf, 0);
+            var msg = Encoding.UTF8.GetString(msgBuf, 0, nulTerm < 0 ? MessageCapacity : nulTerm);
+            entries[count++] = new PostMortemEntry(ts, op, msg);
+        }
+
+        Array.Resize(ref entries, count);
+        return entries;
+    }
+}
+
+public readonly record struct PostMortemEntry(long UtcUnixMs, long OpKind, string Message);

src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/Supervisor/ProcessHostLauncher.cs

@@ -0,0 +1,113 @@
+using System.Diagnostics;
+using ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Ipc;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Supervisor;
+
+/// <summary>
+///     Production <see cref="IHostProcessLauncher"/>. Spawns <c>OtOpcUa.Driver.FOCAS.Host.exe</c>
+///     with the pipe name / allowed-SID / per-spawn shared secret in the environment, waits for
+///     the pipe to come up, then connects a <see cref="FocasIpcClient"/> and wraps it in an
+///     <see cref="IpcFocasClient"/>. On <see cref="TerminateAsync"/> best-effort kills the
+///     process and closes the IPC stream.
+/// </summary>
+public sealed class ProcessHostLauncher : IHostProcessLauncher
+{
+    private readonly ProcessHostLauncherOptions _options;
+    private Process? _process;
+    private FocasIpcClient? _ipc;
+
+    public ProcessHostLauncher(ProcessHostLauncherOptions options)
+    {
+        _options = options ?? throw new ArgumentNullException(nameof(options));
+    }
+
+    public bool IsProcessAlive => _process is { HasExited: false };
+
+    public async Task<IFocasClient> LaunchAsync(CancellationToken ct)
+    {
+        await TerminateAsync(ct).ConfigureAwait(false);
+
+        var secret = _options.SharedSecret ?? Guid.NewGuid().ToString("N");
+
+        var psi = new ProcessStartInfo
+        {
+            FileName = _options.HostExePath,
+            Arguments = _options.Arguments ?? string.Empty,
+            UseShellExecute = false,
+            CreateNoWindow = true,
+        };
+        psi.Environment["OTOPCUA_FOCAS_PIPE"] = _options.PipeName;
+        psi.Environment["OTOPCUA_ALLOWED_SID"] = _options.AllowedSid;
+        psi.Environment["OTOPCUA_FOCAS_SECRET"] = secret;
+        psi.Environment["OTOPCUA_FOCAS_BACKEND"] = _options.Backend;
+
+        _process = Process.Start(psi)
+            ?? throw new InvalidOperationException($"Failed to start {_options.HostExePath}");
+
+        // Poll for pipe readiness up to the configured connect timeout.
+        var deadline = DateTime.UtcNow + _options.ConnectTimeout;
+        while (true)
+        {
+            ct.ThrowIfCancellationRequested();
+            if (_process.HasExited)
+                throw new InvalidOperationException(
+                    $"FOCAS Host exited before pipe was ready (ExitCode={_process.ExitCode}).");
+
+            try
+            {
+                _ipc = await FocasIpcClient.ConnectAsync(
+                    _options.PipeName, secret, TimeSpan.FromSeconds(1), ct).ConfigureAwait(false);
+                break;
+            }
+            catch (TimeoutException)
+            {
+                if (DateTime.UtcNow >= deadline)
+                    throw new TimeoutException(
+                        $"FOCAS Host pipe {_options.PipeName} did not come up within {_options.ConnectTimeout:g}.");
+                await Task.Delay(TimeSpan.FromMilliseconds(250), ct).ConfigureAwait(false);
+            }
+        }
+
+        return new IpcFocasClient(_ipc, _options.Series);
+    }
+
+    public async Task TerminateAsync(CancellationToken ct)
+    {
+        if (_ipc is not null)
+        {
+            try { await _ipc.DisposeAsync().ConfigureAwait(false); }
+            catch { /* best effort */ }
+            _ipc = null;
+        }
+
+        if (_process is not null)
+        {
+            try
+            {
+                if (!_process.HasExited)
+                {
+                    _process.Kill(entireProcessTree: true);
+                    await _process.WaitForExitAsync(ct).ConfigureAwait(false);
+                }
+            }
+            catch { /* best effort */ }
+            finally
+            {
+                _process.Dispose();
+                _process = null;
+            }
+        }
+    }
+}
+
+public sealed record ProcessHostLauncherOptions(
+    string HostExePath,
+    string PipeName,
+    string AllowedSid)
+{
+    public string? SharedSecret { get; init; }
+    public string? Arguments { get; init; }
+    public string Backend { get; init; } = "fwlib32";
+    public TimeSpan ConnectTimeout { get; init; } = TimeSpan.FromSeconds(15);
+    public FocasCncSeries Series { get; init; } = FocasCncSeries.Unknown;
+}

src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.csproj

@@ -14,6 +14,7 @@
 
     <ItemGroup>
         <ProjectReference Include="..\ZB.MOM.WW.OtOpcUa.Core.Abstractions\ZB.MOM.WW.OtOpcUa.Core.Abstractions.csproj"/>
+        <ProjectReference Include="..\ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared\ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared.csproj"/>
     </ItemGroup>
 
     <!--

src/ZB.MOM.WW.OtOpcUa.Driver.S7/S7Driver.cs

@@ -84,7 +84,7 @@ public sealed class S7Driver(S7DriverOptions options, string driverInstanceId)
         _health = new DriverHealth(DriverState.Initializing, null, null);
         try
         {
-            var plc = new Plc(_options.CpuType, _options.Host, _options.Rack, _options.Slot);
+            var plc = new Plc(_options.CpuType, _options.Host, _options.Port, _options.Rack, _options.Slot);
             // S7netplus writes timeouts into the underlying TcpClient via Plc.WriteTimeout /
             // Plc.ReadTimeout (milliseconds). Set before OpenAsync so the handshake itself
             // honours the bound.

src/ZB.MOM.WW.OtOpcUa.Server/OpcUa/DriverEquipmentContentRegistry.cs

@@ -0,0 +1,47 @@
+using ZB.MOM.WW.OtOpcUa.Core.OpcUa;
+
+namespace ZB.MOM.WW.OtOpcUa.Server.OpcUa;
+
+/// <summary>
+///     Holds pre-loaded <see cref="EquipmentNamespaceContent"/> snapshots keyed by
+///     <c>DriverInstanceId</c>. Populated once during <see cref="OpcUaServerService"/> startup
+///     (after <see cref="NodeBootstrap"/> resolves the generation) so the synchronous lookup
+///     delegate on <see cref="OpcUaApplicationHost"/> can serve the walker from memory without
+///     blocking on async DB I/O mid-dispatch.
+/// </summary>
+/// <remarks>
+///     <para>The registry is intentionally a shared mutable singleton with set-once-per-bootstrap
+///     semantics rather than an immutable map passed by value — the composition in Program.cs
+///     builds <see cref="OpcUaApplicationHost"/> before <see cref="NodeBootstrap"/> runs, so the
+///     registry must exist at DI-compose time but be empty until the generation is known. A
+///     driver registered after the initial populate pass simply returns null from
+///     <see cref="Get"/> + the wire-in falls back to the "no UNS content, let DiscoverAsync own
+///     it" path that PR #155 established.</para>
+/// </remarks>
+public sealed class DriverEquipmentContentRegistry
+{
+    private readonly Dictionary<string, EquipmentNamespaceContent> _content =
+        new(StringComparer.OrdinalIgnoreCase);
+    private readonly Lock _lock = new();
+
+    public EquipmentNamespaceContent? Get(string driverInstanceId)
+    {
+        lock (_lock)
+        {
+            return _content.TryGetValue(driverInstanceId, out var c) ? c : null;
+        }
+    }
+
+    public void Set(string driverInstanceId, EquipmentNamespaceContent content)
+    {
+        lock (_lock)
+        {
+            _content[driverInstanceId] = content;
+        }
+    }
+
+    public int Count
+    {
+        get { lock (_lock) { return _content.Count; } }
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Server/OpcUa/EquipmentNamespaceContentLoader.cs

@@ -0,0 +1,86 @@
+using Microsoft.EntityFrameworkCore;
+using ZB.MOM.WW.OtOpcUa.Configuration;
+using ZB.MOM.WW.OtOpcUa.Configuration.Entities;
+using ZB.MOM.WW.OtOpcUa.Core.OpcUa;
+
+namespace ZB.MOM.WW.OtOpcUa.Server.OpcUa;
+
+/// <summary>
+///     Loads the <see cref="EquipmentNamespaceContent"/> snapshot the
+///     <see cref="EquipmentNodeWalker"/> consumes, scoped to a single
+///     (driverInstanceId, generationId) pair. Joins the four row sets the walker expects:
+///     UnsAreas for the driver's cluster, UnsLines under those areas, Equipment bound to
+///     this driver + its lines, and Tags bound to this driver + its equipment — all at the
+///     supplied generation.
+/// </summary>
+/// <remarks>
+///     <para>The walker is driver-instance-scoped (decisions #116–#121 put the UNS in the
+///     Equipment-kind namespace owned by one driver instance at a time), so this loader is
+///     too — a single call returns one driver's worth of rows, never the whole fleet.</para>
+///
+///     <para>Returns <c>null</c> when the driver instance has no Equipment rows at the
+///     supplied generation. The wire-in in <see cref="OpcUaApplicationHost"/> treats null as
+///     "this driver has no UNS content, skip the walker and let DiscoverAsync own the whole
+///     address space" — the backward-compat path for drivers whose namespace kind is not
+///     Equipment (Modbus / AB CIP / TwinCAT / FOCAS).</para>
+/// </remarks>
+public sealed class EquipmentNamespaceContentLoader
+{
+    private readonly OtOpcUaConfigDbContext _db;
+
+    public EquipmentNamespaceContentLoader(OtOpcUaConfigDbContext db)
+    {
+        _db = db;
+    }
+
+    /// <summary>
+    ///     Load the walker-shaped snapshot for <paramref name="driverInstanceId"/> at
+    ///     <paramref name="generationId"/>. Returns <c>null</c> when the driver has no
+    ///     Equipment rows at that generation.
+    /// </summary>
+    public async Task<EquipmentNamespaceContent?> LoadAsync(
+        string driverInstanceId, long generationId, CancellationToken ct)
+    {
+        var equipment = await _db.Equipment
+            .AsNoTracking()
+            .Where(e => e.DriverInstanceId == driverInstanceId && e.GenerationId == generationId && e.Enabled)
+            .ToListAsync(ct).ConfigureAwait(false);
+
+        if (equipment.Count == 0)
+            return null;
+
+        // Filter UNS tree to only the lines + areas that host at least one Equipment bound to
+        // this driver — skips loading unrelated UNS branches from the cluster. LinesByArea
+        // grouping is driven off the Equipment rows so an empty line (no equipment) doesn't
+        // pull a pointless folder into the walker output.
+        var lineIds = equipment.Select(e => e.UnsLineId).Distinct(StringComparer.OrdinalIgnoreCase).ToArray();
+
+        var lines = await _db.UnsLines
+            .AsNoTracking()
+            .Where(l => l.GenerationId == generationId && lineIds.Contains(l.UnsLineId))
+            .ToListAsync(ct).ConfigureAwait(false);
+
+        var areaIds = lines.Select(l => l.UnsAreaId).Distinct(StringComparer.OrdinalIgnoreCase).ToArray();
+
+        var areas = await _db.UnsAreas
+            .AsNoTracking()
+            .Where(a => a.GenerationId == generationId && areaIds.Contains(a.UnsAreaId))
+            .ToListAsync(ct).ConfigureAwait(false);
+
+        // Tags belonging to this driver at this generation. Walker skips Tags with null
+        // EquipmentId (those are SystemPlatform-kind Galaxy tags per decision #120) but we
+        // load them anyway so the same rowset can drive future non-Equipment-kind walks
+        // without re-hitting the DB. Filtering here is a future optimization; today the
+        // per-tag cost is bounded by driver scope.
+        var tags = await _db.Tags
+            .AsNoTracking()
+            .Where(t => t.DriverInstanceId == driverInstanceId && t.GenerationId == generationId)
+            .ToListAsync(ct).ConfigureAwait(false);
+
+        return new EquipmentNamespaceContent(
+            Areas: areas,
+            Lines: lines,
+            Equipment: equipment,
+            Tags: tags);
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Server/OpcUa/OpcUaApplicationHost.cs

@@ -29,6 +29,7 @@ public sealed class OpcUaApplicationHost : IAsyncDisposable
     private readonly StaleConfigFlag? _staleConfigFlag;
     private readonly Func<string, ZB.MOM.WW.OtOpcUa.Core.Abstractions.DriverTier>? _tierLookup;
     private readonly Func<string, string?>? _resilienceConfigLookup;
+    private readonly Func<string, ZB.MOM.WW.OtOpcUa.Core.OpcUa.EquipmentNamespaceContent?>? _equipmentContentLookup;
     private readonly ILoggerFactory _loggerFactory;
     private readonly ILogger<OpcUaApplicationHost> _logger;
     private ApplicationInstance? _application;
@@ -43,7 +44,8 @@ public sealed class OpcUaApplicationHost : IAsyncDisposable
         NodeScopeResolver? scopeResolver = null,
         StaleConfigFlag? staleConfigFlag = null,
         Func<string, ZB.MOM.WW.OtOpcUa.Core.Abstractions.DriverTier>? tierLookup = null,
-        Func<string, string?>? resilienceConfigLookup = null)
+        Func<string, string?>? resilienceConfigLookup = null,
+        Func<string, ZB.MOM.WW.OtOpcUa.Core.OpcUa.EquipmentNamespaceContent?>? equipmentContentLookup = null)
     {
         _options = options;
         _driverHost = driverHost;
@@ -54,6 +56,7 @@ public sealed class OpcUaApplicationHost : IAsyncDisposable
         _staleConfigFlag = staleConfigFlag;
         _tierLookup = tierLookup;
         _resilienceConfigLookup = resilienceConfigLookup;
+        _equipmentContentLookup = equipmentContentLookup;
         _loggerFactory = loggerFactory;
         _logger = logger;
     }
@@ -103,11 +106,31 @@ public sealed class OpcUaApplicationHost : IAsyncDisposable
         // Drive each driver's discovery through its node manager. The node manager IS the
         // IAddressSpaceBuilder; GenericDriverNodeManager captures alarm-condition sinks into
         // its internal map and wires OnAlarmEvent → sink routing.
+        //
+        // ADR-001 Option A — when an EquipmentNamespaceContent is supplied for an
+        // Equipment-kind driver, run the EquipmentNodeWalker BEFORE the driver's DiscoverAsync
+        // so the UNS folder skeleton (Area/Line/Equipment) + Identification sub-folders +
+        // the five identifier properties (decision #121) are in place. DiscoverAsync then
+        // streams the driver's native shape on top; Tag rows bound to Equipment already
+        // materialized via the walker don't get duplicated because the driver's DiscoverAsync
+        // output is authoritative for its own native references only.
         foreach (var nodeManager in _server.DriverNodeManagers)
         {
             var driverId = nodeManager.Driver.DriverInstanceId;
             try
             {
+                if (_equipmentContentLookup is not null)
+                {
+                    var content = _equipmentContentLookup(driverId);
+                    if (content is not null)
+                    {
+                        ZB.MOM.WW.OtOpcUa.Core.OpcUa.EquipmentNodeWalker.Walk(nodeManager, content);
+                        _logger.LogInformation(
+                            "UNS walker populated {Areas} area(s), {Lines} line(s), {Equipment} equipment, {Tags} tag(s) for driver {Driver}",
+                            content.Areas.Count, content.Lines.Count, content.Equipment.Count, content.Tags.Count, driverId);
+                    }
+                }
+
                 var generic = new GenericDriverNodeManager(nodeManager.Driver);
                 await generic.BuildAddressSpaceAsync(nodeManager, ct).ConfigureAwait(false);
                 _logger.LogInformation("Address space populated for driver {Driver}", driverId);