18 Commits

Author	SHA1	Message	Date
Joseph Doherty	662f3f9f5c	refactor(driver-pages): address Phase 6/8 deep-review findings ... - Topic-name drift fix: DriverHealthChanged.TopicName and DriverControlTopic.Name now live on the message contracts in Commons. AkkaDriverHealthPublisher, DriverStatusSignalRBridge, DriverHostActor, and AdminOperationsActor all delegate to the single constant so a rename can't silently desynchronise publisher and subscriber. - DriverStatusPanel._opResultClearTimer switched from System.Timers.Timer to System.Threading.Timer + awaited DisposeAsync. Prevents an in-flight 8s clear-callback from invoking StateHasChanged on a component whose hub has already been released. - PublishHealthSnapshot deduplicates against the last published (state, lastSuccess, lastError, errorCount) fingerprint. The 30s heartbeat no longer floods the SignalR layer with identical Healthy snapshots — newly-joined clients still warm up via the snapshot store on JoinDriver.	2026-05-28 11:52:20 -04:00
Joseph Doherty	dcd2509548	refactor(driver-pages): address post-review follow-ups ... - DriverInstanceSpec carries ClusterId from the deployment artifact; DriverHostActor threads the real cluster identity into DriverInstanceActor instead of the local NodeId. Old pre-PR artifacts without a ClusterId field fall back to the NodeId so in-flight deployments keep working. - DriverHostActor.ChildEntry holds the full DriverInstanceSpec (was only carrying DriverType + LastConfigJson). Restart respawns preserve RowId, Name, Enabled, ClusterId — no placeholder values. - Drop the unnecessary _faultLock on DriverInstanceActor — every read/write site runs inside an Akka message handler which is single-threaded per actor instance. - DriverStatusPanel.DisposeAsync awaits Timer.DisposeAsync so an in-flight 5s tick can't invoke StateHasChanged on a component whose hub has already been torn down.	2026-05-28 11:41:46 -04:00
Joseph Doherty	ffcc8d1065	feat(adminui): Reconnect/Restart on DriverStatusPanel (DriverOperator-gated) ... - RestartDriver / ReconnectDriver messages + AdminOperationsActor handlers (broadcast via driver-control DPS topic; audited via ConfigEdits). - DriverHostActor subscribes to driver-control; locates the matching child DriverInstanceActor and stops+respawns it (Restart) or sends it a ForceReconnect internal message (Reconnect — re-enters Reconnecting state without full stop). DriverInstanceSpec constructor call uses named args to handle the full 6-parameter signature. - New DriverOperator authorization policy mapped to DriverOperator or FleetAdmin role; documented in docs/security.md. Map LDAP group via GroupToRole (e.g. "ot-driver-operator": "DriverOperator"). - DriverStatusPanel renders Reconnect + Restart buttons when the user holds the DriverOperator policy (hidden otherwise). Restart requires an in-page Razor confirm block (no JS confirm, keeps SignalR event loop unblocked). Both buttons show a spinner and are disabled during in-flight; result chip auto-clears after 8s. Username sourced from AuthenticationStateProvider. Reconnect resolves to "ForceReconnect" (re-enter Reconnecting, not full stop+respawn) — transport drops and retries while actor and in-memory state are preserved. All DriverInstanceActor states handle ForceReconnect safely (no-op when already in transition).	2026-05-28 11:14:04 -04:00
Joseph Doherty	4203b84d51	feat(runtime): publish DriverHealthChanged via DriverInstanceActor ... - IDriverHealthPublisher in Core.Abstractions + NullDriverHealthPublisher no-op for tests/dev-stub paths. - AkkaDriverHealthPublisher in Runtime forwards to the cluster-wide `driver-health` DPS topic. - DriverInstanceActor instrumented to publish snapshots on every observable state change + a periodic 30s heartbeat so the AdminUI snapshot store warms up for newly-joined SignalR clients. - Sliding 5-minute Faulted-count tracked per actor via Queue<DateTime>. - DriverHostActor.SpawnChild threads clusterId (_localNode.Value) and the health publisher down to every DriverInstanceActor child. - ServiceCollectionExtensions.AddOtOpcUaRuntime registers AkkaDriverHealthPublisher as IDriverHealthPublisher singleton.	2026-05-28 10:22:44 -04:00
Joseph Doherty	64e3fbe035	docs: backfill XML documentation across 756 files ... Adds <summary>, <param>, <typeparam>, and <inheritdoc/> tags to public members surfaced by commentchecker — resolves 5,847 of 5,869 issues (99.6%) across three /fixdocs passes.	2026-05-28 08:10:17 -04:00
Joseph Doherty	7dfbca6469	feat(opcua): materialise SystemPlatform tags (Galaxy) as OPC UA variables ... Closes the gap where Tag rows with EquipmentId=NULL + Namespace.Kind=SystemPlatform (Galaxy hierarchy) existed in ConfigDb but were never surfaced in the OPC UA address space. Now they materialise as Variable nodes under a folder named for their FolderPath, browseable through any OPC UA client. Layers touched: - IOpcUaAddressSpaceSink: new EnsureVariable(nodeId, parentFolderId, displayName, dataType) signature on the sink interface, NullSink, DeferredSink, SdkSink. - OtOpcUaNodeManager.EnsureVariable: creates a BaseDataVariableState parented under the named folder (or root), initial Value=null + StatusCode=BadWaitingForInitialData; resolves Tag.DataType strings to the matching OPC UA built-in NodeId. Idempotent. - Phase7CompositionResult: new GalaxyTags collection of GalaxyTagPlan records carrying (TagId, DriverInstanceId, FolderPath, DisplayName, DataType, MxAccessRef). Constructor overloads keep existing call sites compiling. - Phase7Composer.Compose: now takes Tag + Namespace inputs, filters for SystemPlatform-namespace tags with EquipmentId=NULL, emits GalaxyTagPlan rows with MXAccess ref "FolderPath.Name". - Phase7Plan: new AddedGalaxyTags / RemovedGalaxyTags / ChangedGalaxyTags collections + GalaxyTagDelta record; IsEmpty + needsRebuild updated. - Phase7Planner.Compute: diffs GalaxyTags by TagId via existing DiffById helper. - DeploymentArtifact.ParseComposition: reads the Tags + Namespaces + DriverInstances arrays the ConfigComposer already emits, applies the same SystemPlatform filter, returns the same GalaxyTagPlan list as the composer so artifact-side and compose-side plans agree. - Phase7Applier: new MaterialiseGalaxyTags pass that ensures one folder per distinct FolderPath then one Variable per tag. NodeId for the variable is "<FolderPath>.<Name>" matching the MXAccess ref so the future Galaxy SubscribeBulk wiring can address them directly. - OpcUaPublishActor.RebuildAddressSpace: invokes MaterialiseGalaxyTags after MaterialiseHierarchy. _lastApplied initialiser updated for the new ctor. - seed-clusters.sql: pre-existing TestMachine_001.TestAlarm001..003 rows needed no change — the composer/applier now picks them up automatically. Verified end-to-end via docker-dev: deploy click → driver-a logs "Phase7Applier: Galaxy tags materialised (tags=3, folders=1)" → OPC UA Client CLI browses the three Variable nodes under TestMachine_001 folder. Reads return BadWaitingForInitialData status (expected — Galaxy driver's SubscribeBulk wiring to push values into the nodes is the remaining follow-up).	2026-05-26 15:43:22 -04:00
Joseph Doherty	60beb9128e	feat(deploy,runtime): wire mxaccessgw connection — endpoint, key, seed row ... User confirmed the mxaccessgw client (Galaxy driver) doesn't need Windows — only the gateway worker has that constraint. This wires the Galaxy driver into the docker-dev fleet: - docker-compose.yml: GALAXY_MXGW_API_KEY env var on every host service (admin nodes harmlessly ignore it; driver-role nodes pick it up when the seeded DriverInstance resolves ApiKeySecretRef=env:GALAXY_MXGW_API_KEY). Default value matches the key the operator provided; override via shell env (GALAXY_MXGW_API_KEY=... docker compose up -d) to rotate without editing compose. - seed-clusters.sql: now creates a SystemPlatform Namespace (MAIN-galaxy, urn:zb:docker-dev:galaxy) plus a GalaxyMxGateway DriverInstance (MAIN-galaxy-mxgw) in the MAIN cluster pointing at http://10.100.0.48:5120 with UseTls=false. Idempotent via IF NOT EXISTS. - DriverInstanceActor.ShouldStub: clarified the doc comment — only the legacy "Galaxy" type name and "Historian.Wonderware" are Windows-only; the v2 "GalaxyMxGateway" driver is .NET 10 cross-platform (gRPC to an external gateway) and is NOT stubbed. - README: documents the final operator step — sign in, click "Deploy current configuration" on /deployments to materialise the seeded Galaxy driver into a running gRPC connection. Raw DriverInstance rows don't spawn drivers on their own; the v2 lifecycle requires a sealed Deployment first.	2026-05-26 14:58:02 -04:00
Joseph Doherty	607dc51dec	feat(opcua): #85 UNS Area/Line/Equipment folder hierarchy in SDK ... Phase7Composer now carries UnsAreaProjection + UnsLineProjection lists so the applier can materialise the full UNS topology in the OPC UA address space. New IOpcUaAddressSpaceSink.EnsureFolder(folderNodeId, parentNodeId, displayName) seam (no-op default, recorded in tests, forwarded by DeferredAddressSpaceSink, implemented by SdkAddressSpaceSink). The SDK- side OtOpcUaNodeManager gains an EnsureFolder API that creates FolderState nodes with proper parent linkage; RebuildAddressSpace now clears folders too so re-applies don't accumulate stale topology. Phase7Applier.MaterialiseHierarchy walks composition.UnsAreas → composition.UnsLines → composition.EquipmentNodes, calling EnsureFolder with the correct parent at each level. Idempotent — calling twice with the same composition is a no-op. OpcUaPublishActor.HandleRebuild invokes it after Phase7Applier.Apply so OPC UA clients browsing the server now see Area/Line/Equipment as proper folders rather than flat tag ids. DeploymentArtifact.ParseComposition reads UnsAreas + UnsLines from the JSON snapshot the ControlPlane emits, populating the new fields when present. Phase7Composer.Compose now accepts UnsAreas + UnsLines; a 3-arg overload preserves the old signature for legacy callers + existing tests. The Phase7CompositionResult convenience ctor likewise keeps the planner tests working without UNS data. 3 new hierarchy tests (pure unit + boot-verify against a real OtOpcUaSdkServer); OpcUaServer suite is 48/48 green (was 45, +3), Runtime 74/74 unchanged. Closes #85.	2026-05-26 10:48:56 -04:00
Joseph Doherty	52997ee164	feat(observability): F13d Prometheus + OpenTelemetry instrumentation ... OtOpcUaTelemetry (Commons/Observability) centralizes the project's Meter + ActivitySource so all instrumentation points emit through a single named surface. Counters cover the hot paths: otopcua.deploy.applied (outcome=ack|reject) otopcua.deploy.apply.duration (s, histogram) otopcua.driver.lifecycle (event=spawn|spawn_stub|stop|fault) otopcua.virtualtag.eval (outcome=ok|fail|skip) otopcua.scriptedalarm.transition (state=activated|acknowledged|cleared) otopcua.opcua.sink.write (kind=value|alarm|rebuild) otopcua.redundancy.service_level_change (level=byte) Plus two ActivitySource spans: otopcua.deploy.apply wraps DriverHostActor.ApplyAndAck otopcua.opcua.address_space_rebuild wraps OpcUaPublishActor.HandleRebuild Instruments are no-op until a listener attaches, so tests + dev hosts pay nothing for unread telemetry. Host Program.cs gains AddOtOpcUaObservability() (binds the OtOpcUa Meter + ActivitySource to OpenTelemetry, attaches a Prometheus exporter) and MapOtOpcUaMetrics() (mounts /metrics scrape endpoint). Driver-side internals + ASP.NET request metrics deliberately stay off — the scrape payload is scoped to OtOpcUa signals only. Tests use MeterListener + ActivityListener to verify VirtualTagActor.eval, OpcUaPublishActor.AttributeValueUpdate, and RebuildAddressSpace actually emit on the central instruments. Runtime suite is 72 / 72 green (+3). Closes #105. Path A (F13b/c/d) complete; next batch options: #85 UNS folder hierarchy in SDK, or F8b/F9b production engine bindings.	2026-05-26 10:29:40 -04:00
Joseph Doherty	7e22e2250c	feat(runtime): #109 OpcUaPublishActor — load artifact, compose, plan-diff, apply ... Closes the loop between F10b (SDK NodeManager) and F14 (Phase7Plan + Phase7Applier). DriverHostActor's successful apply now triggers a RebuildAddressSpace on the publish actor, which loads the latest deployment artifact + walks composer → planner → applier through the sink. The OPC UA address space tracks the deployed composition. DeploymentArtifact: - New ParseComposition(blob) → Phase7CompositionResult that decodes Equipment + DriverInstance + ScriptedAlarm arrays into the projection records Phase7Planner consumes. Pascal-case property names mirror ConfigComposer.SnapshotAndFlattenAsync's output. - Each entity reader is tolerant: missing-id rows are dropped, natural-key sort matches Phase7Composer's contract. OpcUaPublishActor: - New Props params: dbFactory + applier. When wired, RebuildAddressSpace does: 1. LoadLatestArtifact (most recent Sealed Deployment.ArtifactBlob) 2. ParseComposition → Phase7CompositionResult 3. Phase7Planner.Compute(lastApplied, next) → Phase7Plan 4. Empty plan ⇒ no-op (deploy of unchanged composition is benign) 5. applier.Apply(plan) drives sink.RebuildAddressSpace + WriteAlarmState for removed nodes 6. lastApplied = next so the next rebuild diffs forward - Without dbFactory/applier wiring, falls back to raw sink.RebuildAddressSpace — the dev/Mac path before #108 binds prod. DriverHostActor: - New Props param opcUaPublishActor (IActorRef?). After successful ApplyAndAck (status Applied, ACK sent), tells the publish actor RebuildAddressSpace with the same correlation id so the audit trail threads through. Null publish actor ⇒ no trigger (admin-only nodes). Tests: Runtime 63 -> 69 (+6): - ParseComposition reads Equipment/Driver/Alarm sorted by natural key - ParseComposition returns empty for empty blob - Rebuild with dbFactory + sealed deployment artifact triggers exactly one sink.Rebuild call (Equipment topology added) - Rebuild with no artifact is idempotent no-op - Second rebuild with same composition is empty-plan no-op - Rebuild without dbFactory falls back to raw sink.Rebuild (legacy path) All 6 v2 test suites green: 173 tests passing. Closes #109. Engine-wiring data flow is now end-to-end through: Deploy → DriverHostActor.ApplyAndAck → driver spawn + ACK + RebuildAddressSpace → OpcUaPublishActor → Phase7Applier → SDK NodeManager → subscribed OPC UA clients see the change.	2026-05-26 09:55:11 -04:00
Joseph Doherty	7fa863f6da	feat(runtime): #113 DependencyMuxActor — drivers → virtual-tag fan-out ... End-to-end data path is now wired on the read side: driver subscriptions fire AttributeValuePublished → DriverHostActor → DependencyMuxActor → DependencyValueChanged to every interested VirtualTagActor. Previously the publish hit a dead-letter at the host. DependencyMuxActor: - Per-node fan-out router. Maintains tagRef → Set<IActorRef> with a reverse subscriber → refs index so unregister/replace are O(refs). - Watches subscribers; Terminated triggers automatic unregister so dead virtual-tag actors stop receiving publishes. - Re-register replaces the prior interest set — no stale-ref leaks on actor restart. - Drops publishes for refs with no interested subscribers. VirtualTagActor: - New Props params: dependencyRefs + mux ActorRef. - PreStart sends RegisterInterest to the mux; PostStop sends UnregisterInterest. Default both null so older callers stay quiet. DriverHostActor: - New dependencyMux Props param. Steady + Applying states now receive AttributeValuePublished from their DriverInstance children and forward to the mux. Null mux is a no-op (dev/Mac). ServiceCollectionExtensions: - WithOtOpcUaRuntimeActors spawns DependencyMuxActor before DriverHostActor and threads its ActorRef into the host's Props. New DependencyMuxActorKey + DependencyMuxActorName. Tests: Runtime 57 -> 63 (+6): - Mux forwards to only subscribers interested in each ref - Publish for unregistered ref is dropped silently - Unregister stops forwarding - Re-register replaces prior interest set - VirtualTagActor PreStart registration drives end-to-end eval (uses AwaitAssert to race-safely settle the PreStart Tell) - DriverHostActor forwards AttributeValuePublished through to mux All 6 v2 test suites green: 163 tests passing. F8 (#79) state updated — dep subscribe seam shipped, Core.VirtualTags production engine binding (compile + ITagUpstreamSource subscribe) is the residual.	2026-05-26 09:43:06 -04:00
Joseph Doherty	3e3f7588bd	feat(runtime,host): close F7 — driver subscribe + write paths + Host DI ... Three pieces landed in one batch, closing F7-residual + Host DI #106: Runtime/DriverInstanceActor: - Subscribe / Unsubscribe message contracts; the Connected state handles them via IDriver.ISubscribable. On every OnDataChange event the actor publishes AttributeValuePublished to its parent (DriverHostActor → OpcUaPublishActor). OPC UA StatusCode is mapped to the 3-state OpcUaQuality enum via severity bits (00=Good, 01=Uncertain, 10/11=Bad). - DetachSubscription tears the handler off the driver on DisconnectObserved, Unsubscribe, and PostStop so a stale handler never pushes to a dead actor. - WriteAttribute now dispatches IWritable.WriteAsync (batch of one) with a 5s CancellationTokenSource; status-code propagated to WriteAttributeResult on non-Good results. Host: - New ProjectReferences to Core + every cross-platform driver assembly (AbCip/AbLegacy/FOCAS/Galaxy/Modbus/S7/TwinCAT). Galaxy is net10 (gRPC client to mxaccessgw); the COM-bound net48 Wonderware Historian driver stays out of the Host's reference closure — its .Client gRPC wrapper is what binds for historian needs. - New DriverFactoryBootstrap.AddOtOpcUaDriverFactories() registers a singleton DriverFactoryRegistry, invokes each driver's Register(registry, loggerFactory), and binds IDriverFactory to DriverFactoryRegistryAdapter. Replaces the F7 NullDriverFactory default so deploys actually materialise real IDriver instances on driver-role nodes. ShouldStub() still gates per-platform behaviour at spawn time. - Program.cs wires AddOtOpcUaDriverFactories() before AddAkka so the runtime extension can resolve IDriverFactory from DI. Tests: Runtime 46 -> 52 (+6): - Write returns success when StatusCode = Good - Write propagates non-Good status code in failure Reason - Subscribe forwards OnDataChange to parent as AttributeValuePublished - Quality translation: Uncertain (0x40...) and Bad (0x80...) - Subscribe against non-ISubscribable returns failure - DisconnectObserved detaches handler so late events are dropped All 6 v2 test suites green: 152 tests passing. Closes F7. F7-residual sub-tasks #110 (subscribe) and #111 (write) both shipped. Host DI binding #106 shipped.	2026-05-26 09:28:34 -04:00
Joseph Doherty	da141497f8	feat(runtime): F7 spawn lifecycle + F20 ShouldStub gate ... DriverHostActor.ApplyAndAck now reads the deployment artifact and reconciles its set of DriverInstanceActor children — spawn the missing, ApplyDelta to those with changed config, stop the removed/disabled. The diff lives in pure DriverSpawnPlanner so it can be unit-tested without an ActorSystem. Adds IDriverFactory in Core.Abstractions (consumed by Runtime) + DriverFactoryRegistryAdapter in Core.Hosting that wraps the existing v1 DriverFactoryRegistry — Runtime stays decoupled from Polly/Serilog, the Host wires the adapter once driver assemblies have registered. ShouldStub(type, roles) is now actually called on every spawn — Galaxy + Wonderware-Historian boot stubbed on macOS/Linux or whenever the host carries the dev role. Missing factory ⇒ stub fallback, never a crash. Tests: 24 → 34 in Runtime (+10): - DriverSpawnPlannerTests x7 (diff cases, type change ⇒ stop+respawn) - DeploymentArtifactTests x5 (empty/malformed/missing fields tolerant) - DriverHostActorReconcileTests x4 (spawn count, stub fallback, ShouldStub gate, second-apply stops the removed) All 6 v2 test suites green: 120 tests passing. Closes F20 (ShouldStub wired). F7 marked partial — subscription publishing + write path still stubbed in DriverInstanceActor itself.	2026-05-26 08:57:16 -04:00
Joseph Doherty	8f32b89fb9	feat(adminui): FleetDiagnosticsClient real Akka ActorSelection round-trip (F17) ... - New Commons.Messages.Fleet.GetDiagnostics request record. - DriverHostActor handles GetDiagnostics in all three states (Steady, Applying, Stale); replies with a NodeDiagnosticsSnapshot built from _currentRevision + the local NodeId. Drivers list is empty until F7 wires the per-instance children. - FleetDiagnosticsClient now resolves the target via ActorSelection at akka.tcp://{system}@{nodeId}/user/driver-host and Asks with a 3s timeout. On timeout/peer-down it returns an empty snapshot so the UI degrades gracefully rather than throwing. Two new integration tests in Host.IntegrationTests: - GetDiagnostics_returns_snapshot_with_target_NodeId verifies the cross-node Ask/Reply works. - GetDiagnostics_after_deploy_reports_current_revision exercises the end-to-end path: AdminOps starts a deployment, both DriverHostActors apply, then diagnostics reports the new revision on both nodes. All 98 v2 tests pass (was 96 + 2 new).	2026-05-26 06:58:11 -04:00
Joseph Doherty	5cfbe8b5dd	test(host): deploy happy-path + idempotency integration tests (Task 59) ... DeployHappyPathTests exercises the full deploy pipeline on the 2-node harness: AdminOperationsActor → ConfigPublishCoordinator → DistributedPubSub → DriverHostActor on both nodes → ApplyAck → coordinator seals. Verifies both NodeDeploymentState rows reach Applied and Deployment.Status reaches Sealed. Exposed + fixed two production bugs along the way: 1. Coordinator was publishing DispatchDeployment on the "deployments" topic but never subscribed to anything — DriverHostActor ACKs published on the same topic could not reach it. Added dedicated "deployment-acks" topic with coordinator subscription in PreStart, and DriverHostActor publishes ACKs there. 2. NodeId derivation used member.Address.Host only — two cluster members on a shared loopback host (test harness, dev VMs) collided to one identity. The coordinator's expected-ack set became {1} and the system sealed after only half the nodes acked. Switched to host:port everywhere (ClusterRoleInfo + coordinator) so loopback nodes stay distinct and production identities are harmlessly more specific. Tests: 95 v2 tests pass (was 93 + 2 deploy tests), 0 skipped. Failover scenarios (design §8 cases 3-7: node-kill-mid-apply, split-brain, restart-during-deploy) deferred — they need controlled node-down primitives on the harness. Tracked as F22 (failover scenario test cases).	2026-05-26 06:34:36 -04:00
Joseph Doherty	8b4de8080b	feat(runtime): DEV-STUB mode for Windows-only drivers on non-Windows or dev role	2026-05-26 05:23:02 -04:00
Joseph Doherty	64c627f8d6	feat(runtime): DriverInstanceActor state machine with Connecting/Connected/Reconnecting	2026-05-26 05:05:36 -04:00
Joseph Doherty	ed130135ca	feat(runtime): DriverHostActor state machine with PreStart recovery + DispatchDeployment + stale fallback	2026-05-26 05:02:42 -04:00