lmxopcua/docs/plans/2026-06-06-equipment-namespace-structure-milestone.md

Equipment-Namespace Structure Materialization — Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers-extended-cc:executing-plans to implement this plan task-by-task.

Goal: A deploy that includes an Equipment-kind namespace materialises its full Area / Line / Equipment / Signal browse tree into the live OPC UA address space on :4840, with friendly-Name browse names and BadWaitingForInitialData leaf values. (Live values are a separate later milestone and are explicitly out of scope here.)

Architecture: The live rebuild (OpcUaPublishActor.HandleRebuild) is sink-based — it drives Phase7Applier against an IOpcUaAddressSpaceSink, materialising the Area/Line/Equipment folder skeleton (MaterialiseHierarchy) and SystemPlatform/Galaxy variables (MaterialiseGalaxyTags). Today there is no equipment-signal pass: Equipment-bound Tag/VirtualTag/ScriptedAlarm rows never become variables. This plan adds that pass, mirroring MaterialiseGalaxyTags, fed by equipment data carried in the deployment composition. It also makes the UNS folders browse by their friendly Name.

Tech Stack: .NET 10, Akka.NET actors, EF Core (SQL Server), OPC UA SDK. Build/test from the repo root: dotnet build, dotnet test. Per-task tests live under tests/Server/… and tests/Core/….

Background (read first): docs/plans/2026-06-06-equipment-namespace-materialization-scope.md — this plan implements its WS-1, WS-2, WS-4 (+ tests). The reference implementation to mirror is the Galaxy path: Phase7Applier.MaterialiseGalaxyTags + OpcUaPublishActor.HandleRebuild.

---

Architecture decisions (resolve before/while implementing)

These are surfaced from the investigation; Task 0 records the chosen answers in the plan/code.

1. Reuse EquipmentNodeWalker vs add a sink pass. EquipmentNodeWalker.Walk is fully built + unit-tested but writes to an IAddressSpaceBuilder (the driver-discovery API), whereas the rebuild path writes to IOpcUaAddressSpaceSink. Two ways to bridge:

   • (A, recommended) Add Phase7Applier.MaterialiseEquipmentTags(composition) — sink-based, a near-copy of MaterialiseGalaxyTags, iterating equipment tags and calling _sink.EnsureFolder / _sink.EnsureVariable. Consistent with the rest of the rebuild; no adapter. Downside: re-expresses some grouping logic the walker already has.
   • (B) Adapt EquipmentNodeWalker via a sink-backed IAddressSpaceBuilder. Check for an existing capturing builder (GenericDriverNodeManager.CapturingBuilder, src/Core/…/Core/OpcUa/GenericDriverNodeManager.cs); if one cleanly wraps the sink, call EquipmentNodeWalker.Walk(capturingBuilder, content) and reuse the tested logic. Downside: couples the rebuild to the driver-builder API + that adapter. Recommendation: spend the first 20 min of Task 2 confirming whether a sink→builder adapter exists and is cheap. If yes → B (reuse the tested walker). If not → A. This plan is written for A (lower coupling, self-contained); swap the Task 2 body for B if the adapter is clean.

2. Where equipment data comes from at rebuild: artifact vs live DB. MaterialiseGalaxyTags uses the sealed-artifact composition. For consistency and snapshot-correctness, carry equipment data in the composition too (Task 1). A pragmatic alternative with precedent (the b1b3f3f SubscribeBulk pass queries the live DB) is to load EquipmentNamespaceContent directly from the DB in the rebuild — simpler, but live-DB-vs-sealed-artifact can diverge. This plan carries it in the composition (the correct, consistent choice).

3. Folder NodeId vs BrowseName. Keep the existing scheme: NodeId = logical Id (UnsAreaId/UnsLineId/EquipmentId) so browse-path resolution + ACLs are unaffected; set the BrowseName/DisplayName = friendly Name (Task 3). MaterialiseHierarchy already keys NodeId on the Id and displays DisplayName; the bug is that DisplayName is currently populated with the Id. The fix is in the composer (Task 3), not the applier.

4. No double-materialisation. MaterialiseHierarchy already creates the Area/Line/Equipment folders. The new equipment-tag pass must only add the variables under existing equipment folders (and any per-tag FolderPath sub-folders) — it must NOT re-create the equipment folders.

---

Task 0: Confirm signatures + record the architecture decisions

Classification: trivial Estimated implement time: ~3 min Parallelizable with: none (do first)

Files:

• Read: src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/Phase7Applier.cs (MaterialiseGalaxyTags, MaterialiseHierarchy, SafeEnsureFolder, the _sink API)
• Read: src/Core/ZB.MOM.WW.OtOpcUa.Core.Abstractions/IOpcUaAddressSpaceSink.cs (exact EnsureFolder/EnsureVariable signatures)
• Read: src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/Phase7Composer.cs (Phase7CompositionResult, Compose, how EquipmentNode.DisplayName + galaxy tags are built)
• Read: src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Drivers/DeploymentArtifact.cs (ParseComposition, BuildGalaxyTagPlans)
• Read: src/Core/ZB.MOM.WW.OtOpcUa.Core/OpcUa/EquipmentNodeWalker.cs (the tested logic to mirror: AddTagVariable, identifier properties)

Step 1: Decide A vs B (decision #1) — grep for CapturingBuilder / IAddressSpaceBuilder implementations that wrap IOpcUaAddressSpaceSink. If a clean adapter exists, note "Task 2 uses B". Step 2: Confirm the sink's EnsureVariable signature (NodeId, parent, displayName, DriverAttributeInfo incl. FullName + DataType) — MaterialiseGalaxyTags is the template. Step 3: Record the confirmed decisions as a comment block at the top of the new MaterialiseEquipmentTags (created in Task 2). No code/test change in this task.

---

Task 1: Carry equipment signals in the deployment composition + artifact

Classification: high-risk Estimated implement time: ~5 min Parallelizable with: none (Task 2 depends on it)

Files:

• Modify: src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/Phase7Composer.cs — add an EquipmentTagPlan list to Phase7CompositionResult; populate it in Compose from Tag rows where EquipmentId != null AND the tag's driver's namespace Kind == Equipment (the inverse of the galaxy filter). Set DisplayName = Name on Area/Line/Equipment records (decision #3 / Task 3 overlaps — do the field plumbing here).
• Modify: the artifact serializer that writes ArtifactBlob (find via grep -rn "ArtifactBlob\|RevisionHash\|Serialize" src/Server/ZB.MOM.WW.OtOpcUa.ControlPlane/AdminOperations/ConfigComposer.cs) — emit the equipment tags (with EquipmentId, FolderPath, Name, DataType, DriverInstanceId, TagConfig.FullName) into the Tags array (they are likely already there) and ensure Area/Line/Equipment friendly Names are serialised.
• Modify: src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Drivers/DeploymentArtifact.cs — add BuildEquipmentTagPlans(root, drivers): the mirror of BuildGalaxyTagPlans that KEEPS EquipmentId != null tags whose namespace Kind == Equipment, reading FullName from TagConfig. Wire it into ParseComposition.
• Test: tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests/Drivers/DeploymentArtifactTests.cs (or the existing composition test file).

Step 1 — failing test: add a test that round-trips an artifact containing one Equipment namespace + one equipment Tag and asserts ParseComposition(...).EquipmentTags contains it with the right EquipmentId, FullName, DataType. Run: dotnet test tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests --filter EquipmentTag → FAIL (member missing). Step 2 — implement the EquipmentTagPlan record + populate in composer + parse in artifact. Step 3 — run the test → PASS, plus the full Runtime.Tests + OpcUaServer.Tests suites green. Step 4 — commit: feat(opcua): carry Equipment-namespace tags through the deployment composition.

Design note: EquipmentNamespaceContent (the EquipmentNodeWalker input) uses full entity types. If Task 2 chooses option B, EquipmentTagPlan should carry enough to reconstruct the Tag/Equipment fields the walker reads (Name, FolderPath, EquipmentId, DataType, FullName). For option A, a flat EquipmentTagPlan(EquipmentId, DriverInstanceId, FolderPath, Name, DataType, FullName) is enough.

---

Task 2: Materialise equipment signals in the live rebuild

Classification: high-risk Estimated implement time: ~5 min Parallelizable with: none (depends on Task 1)

Files:

• Modify: src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/Phase7Applier.cs — add MaterialiseEquipmentTags(Phase7CompositionResult composition), a sink-based near-copy of MaterialiseGalaxyTags: for each EquipmentTagPlan, ensure its FolderPath sub-folder (if any) under the existing equipment folder (parentNodeId = EquipmentId or the sub-folder), then EnsureVariable(nodeId: FullName, parent, displayName: Name, attributeInfo: new DriverAttributeInfo(FullName, DataType, …)). Log equipment tags materialised (tags=N, equipment=M).
• Modify: src/Server/ZB.MOM.WW.OtOpcUa.Runtime/OpcUa/OpcUaPublishActor.cs:HandleRebuild — after MaterialiseGalaxyTags(composition), call _applier.MaterialiseEquipmentTags(composition).
• Test: tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests/Phase7ApplierHierarchyTests.cs (sibling to the existing hierarchy test, which mocks IOpcUaAddressSpaceSink).

Step 1 — failing test: with a fake sink, call MaterialiseEquipmentTags on a composition with one equipment tag and assert one EnsureVariable(nodeId == FullName, parent == EquipmentId, displayName == Name) call landed. Run filtered test → FAIL (method missing). Step 2 — implement MaterialiseEquipmentTags (mirror MaterialiseGalaxyTags; reuse SafeEnsureFolder; idempotent via the same dedupe the galaxy pass uses) and the HandleRebuild wire-up. Step 3 — run the new test + OpcUaServer.Tests + Runtime.Tests → PASS. Step 4 — commit: feat(opcua): materialise Equipment-namespace tags in the live rebuild.

If Task 0 chose option B: instead of a new method, build EquipmentNamespaceContent from the composition, obtain the sink-backed IAddressSpaceBuilder, and call EquipmentNodeWalker.Walk. Keep the same HandleRebuild call site + test assertions.

---

Task 3: Friendly browse names for UNS folders

Classification: small Estimated implement time: ~3 min Parallelizable with: none (verify after Task 1, which plumbs DisplayName)

Files:

• Modify: src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/Phase7Composer.cs — ensure the composition's Area/Line/Equipment records carry DisplayName = <row>.Name (not the logical Id). MaterialiseHierarchy already passes DisplayName to the sink as the folder browse name, so this is the only change needed.
• Test: tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests/Phase7ApplierHierarchyTests.cs — assert SafeEnsureFolder is called with displayName == "filling" (Name) while nodeId == "nw-area-filling" (Id).

Step 1 — failing test asserting DisplayName == Name, NodeId == Id. Run → FAIL (currently DisplayName == Id). Step 2 — implement the composer change. Step 3 — run → PASS. Step 4 — commit: fix(opcua): UNS folders browse by friendly Name, NodeId stays the logical Id.

---

Task 4: Idempotency + restart-safety

Classification: small Estimated implement time: ~3 min Parallelizable with: none (after Task 2)

Files:

• Read/verify: OpcUaPublishActor.HandleRebuild runs on both the apply path and the DriverHostActor.RestoreApplied bootstrap path (added in b1b3f3f) — so the new pass is already restart-covered. Confirm by inspection; no code change expected.
• Test: tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests/Phase7ApplierHierarchyTests.cs — call MaterialiseEquipmentTags twice with the same composition and assert no duplicate EnsureVariable (idempotent), matching the galaxy pass's dedupe behaviour.

Step 1 — failing test (double-apply → single variable). Step 2 — fix dedupe if needed. Step 3 — run → PASS. Step 4 — commit: test(opcua): equipment-tag materialisation is idempotent.

---

Task 5: docker-dev integration verification + tool support

Classification: standard Estimated implement time: ~5 min Parallelizable with: none (last; needs Tasks 1–3 deployed)

Files:

• Create: tests/Server/ZB.MOM.WW.OtOpcUa.Host.IntegrationTests/EquipmentNamespaceMaterializationTests.cs (model on the existing DriverReconnectE2eTests.cs / phase-7 smoke) — seed a 1-area/1-line/1-equipment/1-tag Equipment namespace + a Modbus FK driver, apply a deployment, browse …/filling/line-1/<eq>/<signal>, assert the variable exists with BadWaitingForInitialData (structure-only).
• Modify (in the scadaproj repo, not OtOpcUa): scadaproj/otopcua-uns-loader/otopcua_uns.py — add a verify branch that browses the Equipment tree (friendly names) and asserts the leaf count matches the loaded equipment tags. (Tracked here for completeness; commit in scadaproj.)

Step 1 — write the integration test (skip-guarded if it needs live infra, per the repo's other integration tests). Step 2 — run it against docker-dev (docs/v2/implementation/phase-7-e2e-smoke.md has the harness). Step 3 — manual confirm via the AdminUI Deploy at :9200 + an asyncua browse. Step 4 — commit: test(opcua): e2e Equipment-namespace structure materialisation.

---

Verification (whole milestone)

After all tasks: deploy an Equipment namespace via scadaproj/otopcua-uns-loader (extend it to emit Equipment rows) + the AdminUI Deploy, then browse :4840:

• OtOpcUa/filling/line-1/<equipment>/<signal> exists, folders browse-named filling / line-1 / …
• leaf variables read BadWaitingForInitialData (values are the next milestone).
• A node restart auto-restores the tree (via RestoreApplied) with no re-deploy.

Out of scope (explicit)

• Live values for equipment signals (driver subscribe / VirtualTag engine / OpcUaClient factory) — the next milestone (scope doc §5 WS-3).
• The Galaxy/SystemPlatform path (works).
• The AdminUI UNS editor.