lmxopcua/docs/plans/2026-06-08-driverless-equipment-namespace-design.md

Driver-less Equipment Namespace — Design (2026-06-08)

Problem

In the OtOpcUa config model, Equipment.DriverInstanceId is a non-null logical FK — every equipment row must reference a DriverInstance. But the Northwind company overlay's equipment signals are VirtualTags (driverless — they link via EquipmentId + a Script, with no driver binding); their live values come from the galaxy mirror over the GalaxyMxGateway driver via the script return ctx.GetTag("TestMachine_NNN.Sig").Value;.

To satisfy the non-null FK and the validator rule that forbids a GalaxyMxGateway driver in an Equipment-kind namespace (DraftValidator.ValidateDriverNamespaceCompatibility: NamespaceKind.Equipment => DriverType != "GalaxyMxGateway"), the loader was cornered into inventing a placeholder Modbus driver (nw-uns-modbus, 0 tags bound) and pointing all 40 equipment rows at it.

That placeholder is misleading ("equipment tied to Modbus") and not inert — on every deploy the runtime tries to instantiate a real Modbus driver for it and fails:

WARNING  DriverHost: factory for Modbus threw on nw-uns-modbus; stubbing
Cause:   Modbus driver config for 'nw-uns-modbus' missing required Host
WARNING  DriverHost: no factory for driver type Modbus (instance nw-uns-modbus); falling back to stub
INFO     DriverHost: spawned Modbus driver nw-uns-modbus (stub=True)

The data path is correct (the MxGateway is the source, via the VirtualTag indirection — verify-equipment shows 396 Good), but the driver association is a lie and generates per-deploy exception/stub noise.

Decision

Option B — make equipment driver-less. VirtualTag-only equipment genuinely has no field driver, so it should reference none: make Equipment.DriverInstanceId nullable, delete the placeholder driver, and teach the one cluster-attribution site to tolerate a null driver. This keeps the VirtualTag route intact (so overlay-building, hierarchy reorganization, and value transforms all stay available — those are the route's strength), removes the misleading Modbus FK, and eliminates the stub/exception noise.

Chosen over: A (a no-op "Virtual" driver type — keeps a placeholder), and Option 4 (relax the validator so a GalaxyMxGateway driver can serve equipment directly as galaxy tags — rejected because a galaxy tag's subscribe ref is FolderPath.Name, i.e. tree placement is coupled to galaxy source, so a direct-tag overlay could not freely reorganize the company hierarchy without further driver re-architecture, and it would also drop transforms/ScriptedAlarms and blur the SystemPlatform/Equipment layering).

Impact map (investigated)

The change is small because almost nothing depends on Equipment.DriverInstanceId.

Schema / entity — the core change

• src/Core/ZB.MOM.WW.OtOpcUa.Configuration/Entities/Equipment.cs:23 — public required string DriverInstanceId → public string? DriverInstanceId.
• EF infers nullability from the C# type: OtOpcUaConfigDbContext.ConfigureEquipment has no .IsRequired() call, so only the property type changes. One EF migration emits a single AlterColumn(DriverInstanceId, nullable: true); the model snapshot loses its .IsRequired().
• No FK to drop. Equipment→DriverInstance is a logical FK only — no EF HasOne/WithMany, no DB FK_… constraint, no ON DELETE. Deleting the placeholder driver while equipment still references it is already schema-legal.
• IX_Equipment_Driver is a plain non-unique, non-filtered index — valid on a nullable column, kept as-is (no filtered-index change; YAGNI).

Validator / composer / applier / runtime — no change required

• DraftValidator (all 9 rules read): none dereference Equipment.DriverInstanceId; none require an Equipment namespace to have a driver. ValidateDriverNamespaceCompatibility iterates draft.DriverInstances — with the placeholder gone, that namespace simply has no driver row to check.
• DraftSnapshotFactory.FromConfigDbAsync loads the full Equipment entity → naturally carries null. No projection change.
• Phase7Composer — EquipmentNode uses EquipmentId/Name/UnsLineId; equipment Tags use Tag.DriverInstanceId (a separate field), not Equipment's; EquipmentVirtualTag uses EquipmentId/Name/ScriptId. Equipment.DriverInstanceId is never read.
• Phase7Applier — MaterialiseHierarchy / MaterialiseEquipmentVirtualTags build folders + variable nodes from projected fields only; never reads the driver.
• DriverHostActor — spawns one driver actor per DriverInstance in the artifact. Deleting the placeholder DriverInstance ⇒ no Modbus spec ⇒ no stub spawn, no missing required Host exception. The VirtualTag host is spawned unconditionally and streams regardless of driver children.
• VirtualTagHostActor — driver-agnostic; depends only on the dependency mux publishing the galaxy-mirror values (from the GalaxyMxGateway driver, untouched).

The one real code change — DeploymentArtifact.BuildClusterSets

src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Drivers/DeploymentArtifact.cs (~lines 271–297). Equipment carries no ClusterId; today it is cluster-attributed via its driver (equipmentIds.Add(id) when di is not null && driverIds.Contains(di)). With a null driver, equipment — and its VirtualTags — would be silently dropped in multi-cluster (ScopeTo) mode.

Fix using the UNS hierarchy, which already carries cluster identity (UnsArea.ClusterId exists, and Equipment → UnsLine.UnsAreaId → UnsArea):

• Build a UnsLineId → UnsAreaId map from the artifact's UnsLines array.
• Driver-bound equipment: unchanged (in-cluster when its driver is in-cluster).
• Driver-less equipment: in-cluster iff its line's area is in-cluster (areaIds.Contains(lineToArea[UnsLineId])).

This is more correct than the driver path: it anchors on the equipment's actual UNS placement, which is exactly the same-cluster invariant decision #122 already enforces (driver-cluster must equal line-cluster). The existing cross-cluster consistency warning (lines 237–244) is phrased "in cluster by its driver"; for driver-less equipment the attribution is by line, so it is consistent by construction and the warning won't fire. Single-cluster (ClusterFilterMode.None, the docker-dev topology) never calls BuildClusterSets, so this is a correctness fix for multi-cluster, not a dev-path requirement.

Loader — scadaproj/otopcua-uns-loader/otopcua_uns.py

In cmd_populate_equipment:

• Remove the placeholder DriverInstance INSERT ('Northwind UNS placeholder', 'Modbus', …) and its comment.
• Equipment INSERT: drop DriverInstanceId from the column list (→ NULL).
• Retire the EQ_DRIVER = "nw-uns-modbus" constant and the now-dead DELETE … Tag WHERE DriverInstanceId / DELETE … DriverInstance teardown lines (in both cmd_populate_equipment and cmd_clean) — they become no-ops; remove for clarity. Keep the Namespace INSERT/teardown.
• Fix the stale # … "an Equipment namespace has a driver" expectations comment.

AdminUI — two production derefs (found at build time, not by the grep sweep)

Making the column nullable surfaced two .razor sites the impact grep missed (caught by TreatWarningsAsErrors):

• Components/Pages/Clusters/TagEdit.razor:191 — db.Equipment.Where(e => driverIds.Contains(e.DriverInstanceId)) (CS8604). Behavior-preserving fix: guard e.DriverInstanceId != null && … (SQL already excludes NULL from an IN set, so this only satisfies the compiler).
• Components/Pages/Clusters/EquipmentEdit.razor — the equipment editor loads DriverInstanceId into a non-null FormModel (line 183, CS8601) and mandates a driver on save ("Pick a driver instance."). Decision: give it full driver-less support — FormModel.DriverInstanceId → string?, add a "(none / driver-less)" option to the driver dropdown, relax the mandatory-driver validation, and persist NULL when none is selected (normalize empty → null).

Noted, not changing (YAGNI)

• sp_ComputeGenerationDiff includes DriverInstanceId in a CHECKSUM(...). It is NULL-tolerant for this one-time transition and sits on the dormant generation-diff path (the active deploy gate is the C# DraftValidator + ConfigComposer.SnapshotAndFlattenAsync, not the SP). Flagged verify-only; if it is ever reactivated, wrap with ISNULL(DriverInstanceId, '') as a follow-on.

Testing & verification

1. Unit (Configuration tests): a DraftValidator test that a draft with driver-less equipment (Equipment.DriverInstanceId == null, Equipment namespace with zero drivers) validates clean.
2. Unit (Runtime tests): a BuildClusterSets / scoped-ParseComposition test proving a null-driver equipment is attributed to the cluster of its line's area in ScopeTo mode (and its VirtualTags are kept), while a wrong-cluster line excludes it.
3. Existing Configuration, OpcUaServer (Phase7), and Runtime (DeploymentArtifact) suites stay green.
4. Migration authored + applied to the docker-dev config DB.
5. Live docker-dev: re-run the loader (populate-equipment, now driver-less) → redeploy → confirm 396 Good still flow on :4840 (VERIFY-EQUIPMENT: PASS) and central-1 logs no longer contain spawned Modbus driver nw-uns-modbus or missing required Host.

Sequencing & risk

Step	Risk	Notes
Entity nullable + EF migration	medium — schema change	single AlterColumn; no FK/constraint to drop; reversible
BuildClusterSets null-driver attribution	low–medium — multi-cluster scoping	additive branch; single-cluster path unaffected; covered by a new test
Loader edits	low	drop placeholder + NULL the FK; teardown becomes no-ops
Live redeploy on docker-dev	low	recreate admin nodes only; sites untouched; the proof the wart is gone

Branches

• OtOpcUa: feat/driverless-equipment-namespace (off master 446a456).
• Loader: scadaproj (otopcua_uns.py).
• Migration authored in the Configuration project; applied to docker-dev. Merge/push only on the user's explicit go (the user manages this repo's integration).

Related context

• Investigation: this design is grounded in a three-front impact sweep (EF/schema, validator/artifact, runtime/loader) — see the per-layer findings folded into the Impact map above.
• Decision #122 (same-cluster invariant: equipment's driver-cluster must equal its UNS-line cluster) — the anchor that makes line-based attribution for driver-less equipment correct.
• DraftValidator.ValidateDriverNamespaceCompatibility — the rule that forbids GalaxyMxGateway in Equipment namespaces and forced the original placeholder.