lmxopcua/docs/plans/2026-06-14-galaxy-phase-c-historian-design.md

Galaxy Phase C — Server-side OPC UA HistoryRead — Design

Date: 2026-06-14 Status: Approved (brainstorming) — ready for implementation planning Branch: feat/galaxy-phase-c-historian off master c9a0f627 Parent design: docs/plans/2026-06-12-galaxy-standard-driver-design.md (workstream 3 / Phase C). Follow-up: pending.md open item #2 ("Phase C — server-side HistoryRead backend over the Wonderware reader").

Goal

Make the OtOpcUa server answer OPC UA HistoryRead for an authored equipment tag flagged historized — driver-agnostically — by dispatching to the already-built, already-hardened server-side IHistorianDataSource (the Wonderware TCP client). No mxaccessgw history RPC; no EF migration. A historized tag's raw / processed / at-time samples and an equipment folder's event-history come back to any OPC UA client (e.g. Client.CLI historyread).

What already exists (grounded in code, 2026-06-14)

Phase C is mostly wiring — the read surface is built:

• IHistorianDataSource (src/Core/.../Core.Abstractions/Historian/IHistorianDataSource.cs) — the server-side read seam, with required ReadRawAsync / ReadProcessedAsync / ReadAtTimeAsync / ReadEventsAsync / GetHealthSnapshot. Returns HistoryReadResult(IReadOnlyList<DataValueSnapshot> Samples, byte[]? ContinuationPoint) and HistoricalEventsResult(IReadOnlyList<HistoricalEvent> Events, byte[]? ContinuationPoint) (both in IHistoryProvider.cs). DataValueSnapshot(object? Value, uint StatusCode, DateTime? SourceTimestampUtc, DateTime ServerTimestampUtc) mirrors Opc.Ua.DataValue.
• WonderwareHistorianClient (Driver.Historian.Wonderware.Client, .NET 10) implements IHistorianDataSource over a hardened TCP/TLS/shared-secret channel. The Host is the only project that references it (same as the alarm-historian writer).
• DriverAttributeInfo.IsHistorized already exists; Galaxy + OpcUaClient drivers populate it (informational — the equipment-tag path does not consume DriverAttributeInfo, it carries TagConfig; see below).
• The Phase B alarm-object-in-TagConfig carrier — EquipmentTagPlan.Alarm parsed by Phase7Composer.ExtractTagAlarm and the byte-parity DeploymentArtifact.ExtractTagAlarm. This is the exact precedent for carrying isHistorized / historianTagname.
• The wiring pattern — the node manager exposes settable props (AlarmCommandRouter, NodeWriteGateway); OtOpcUaSdkServer.Set* methods set them; the Host's OtOpcUaServerHostedService.StartAsync wires them post-start.
• The DI pattern — AddAlarmHistorian(config, writerFactory) (Null default via AddOtOpcUaRuntime's TryAddSingleton, config-gated real impl), Host supplies the Wonderware client factory in Program.cs.
• EnsureFolderIsEventNotifier already promotes alarm-owning equipment folders to EventNotifiers.SubscribeToEvents + AddRootNotifier (guarded by _notifierFolders).

What's missing (the Phase C work)

1. No HistoryRead override. OtOpcUaNodeManager : CustomNodeManager2 overrides only CreateAddressSpace. Historizing is hardcoded false in EnsureVariable (:846) and CreateVariable (:977); no AccessLevels.HistoryRead bit, no event-notifier HistoryRead bit.
2. No carrier for isHistorized / historianTagname through EquipmentTagPlan → artifact → materialization.
3. No IHistorianDataSource registration / Null default / node-manager wiring / config section.

Locked decisions (this Phase C brainstorming)

Decision	Choice
Read variants	All four — Raw, Processed, AtTime over historized variable nodes; Events over historized equipment-folder event-notifier nodes. (User-selected.)
Authoring	Raw TagConfig JSON — "isHistorized": true (+ optional "historianTagname") rides in the existing TagConfig blob, mirroring the Phase B alarm object. No UI control, no EF migration. Galaxy already uses the raw-JSON tag editor. (User-selected.)
Tagname mapping	Default = the tag's driver FullName (already on EquipmentTagPlan); optional explicit override via TagConfig.historianTagname.
Async bridge	The override is synchronous and blocks on the async data source with its own call-timeout. No actor — HistoryRead is read-only and is not invoked under the node-manager Lock (unlike OnWriteValue), so blocking is safe and won't freeze the address space.
Redundancy / auth	No Primary gate (reads are safe from any node). Auth is the standard NodePermissions.HistoryRead enforced by the SDK via the AccessLevels.HistoryRead bit we set at materialization.
Graceful degrade	A NullHistorianDataSource (returns empty Samples / Events) is the default. A historized node with the Null source returns GoodNoData (empty), not an error spike (parent-design invariant). A non-historized node returns BadHistoryOperationUnsupported.
Continuation points	Single-shot read honoring the client's NumValuesPerNode; results[i].ContinuationPoint = null. releaseContinuationPoints == true → Good (we never issue one). Server-managed paging is an explicit follow-up.
Config	New ServerHistorian appsettings section (Host/Port/SharedSecret/UseTls/ServerCertThumbprint/Enabled) + AddServerHistorian(config, factory), mirroring AlarmHistorian. Independent of the alarm-write path (its own enable + its own client instance to the same sidecar).

Rejected / out of scope

• Server-object fleet-wide event history. The Server object belongs to the SDK's CoreNodeManager, not ours; the MasterNodeManager routes HistoryRead by node ownership. We expose event history only on our equipment-folder event-notifiers (per-equipment sourceName). Clean ownership boundary.
• An historian read actor (mirroring HistorianAdapterActor). The write path needs an actor for fire-and-forget + redundancy gating; reads are synchronous, ungated, and ownerless — a direct blocking bridge is simpler and correct.
• Continuation-point paging / HistoryUpdate / live UI authoring control. Follow-ups.

Carrier seam (mirrors Phase B alarm exactly)

Tag.TagConfig JSON  { "FullName":"…", "isHistorized":true, "historianTagname":"…"? , "alarm":{…}? }
   → Phase7Composer.ExtractTagHistorize(tagConfig)  →  (bool IsHistorized, string? HistorianTagname)
   → EquipmentTagPlan { …, IsHistorized, HistorianTagname }            (+2 fields)
   → ConfigComposer snapshot → artifact JSON
   → DeploymentArtifact.ExtractTagHistorize(tagConfig)   ← BYTE-PARITY copy of the composer parse
   → Phase7Applier.MaterialiseEquipmentTags
        historianTagname := tag.IsHistorized ? (tag.HistorianTagname ?? tag.FullName) : null
        → IOpcUaAddressSpaceSink.EnsureVariable(…, string? historianTagname)   (+1 nullable param)
   → OtOpcUaNodeManager.EnsureVariable
        if historianTagname is not null:
            Historizing = true
            AccessLevel |= AccessLevels.HistoryRead   (Read + History; ReadWrite + History)
            _historizedTagnames[nodeId] = historianTagname

Single nullable param. The sink seam gains exactly one string? historianTagname (null ⇒ not historized) across IOpcUaAddressSpaceSink / NullOpcUaAddressSpaceSink / DeferredAddressSpaceSink / SdkAddressSpaceSink / Phase7Applier.SafeEnsureVariable. The applier resolves default-vs-override so the node manager just consumes the final tagname.

HistoryRead dispatch (the new override)

OtOpcUaNodeManager gains a settable public IHistorianDataSource HistorianDataSource { get; set; } (defaults to NullHistorianDataSource.Instance; volatile-backed like NodeWriteGateway) and a ConcurrentDictionary<string,string> _historizedTagnames (NodeId-string → historian tagname).

Override the CustomNodeManager2 HistoryRead surface. The exact override point is version-sensitive — the implementer confirms it against the installed OPCFoundation.NetStandard.Opc.Ua.Server (use the DeepWiki MCP OPCFoundation/UA-.NETStandard, per CLAUDE.md). Recommended: override the per-details protected virtuals (HistoryReadRawModified / HistoryReadProcessed / HistoryReadAtTime / HistoryReadEvents); fallback: override the single HistoryRead and switch on details. Per nodesToRead[i]:

• Resolve. NodeId.Identifier (string) → _historizedTagnames. Miss ⇒ errors[i] = BadHistoryOperationUnsupported, Processed = true. (Reading _historizedTagnames needs no Lock — it's a concurrent dict.)
• Data (variable nodes): switch on the details type → HistorianDataSource.ReadRawAsync(tagname, start, end, NumValuesPerNode, ct) / ReadProcessedAsync(…interval, MapAggregate(aggregateId)…) / ReadAtTimeAsync(tagname, reqTimes, ct). Block with the data source's timeout (.GetAwaiter().GetResult() inside try). Map each DataValueSnapshot → Opc.Ua.DataValue(new Variant(Value), new StatusCode(StatusCode), SourceTs, ServerTs); wrap the list in HistoryData { DataValues = … }; set results[i].HistoryData = new ExtensionObject(historyData), results[i].StatusCode = samples.Count == 0 ? GoodNoData : Good, ContinuationPoint = null, Processed = true.
• Events (equipment-folder notifier nodes): ReadEventDetails target folder → _eventNotifierSources[folderNodeId] (sourceName, default = the folder's string id = equipment id, registered when EnsureFolderIsEventNotifier promotes it) → ReadEventsAsync(sourceName, start, end, maxEvents, ct). Project each HistoricalEvent into a HistoryEventFieldList per the request's ReadEventDetails.Filter SelectClauses — support the standard BaseEventType operands (EventId, SourceName, Time, Message, Severity); an unsupported operand yields a null field (spec-conformant). Wrap in HistoryEvent { Events = … }.
• Errors never escape. A backend throw / timeout → errors[i] = BadHistoryOperationUnsupported (or BadUnexpectedError) + log; one node's failure never faults the batch.

MapAggregate(NodeId aggregateId) maps the OPC UA Part 13 aggregate NodeIds (ObjectIds.AggregateFunction_Average/Minimum/Maximum/Total/Count) → HistoryAggregateType; an unsupported aggregate ⇒ BadAggregateNotSupported.

Materialization: Historizing + access bits

• Variable nodes — EnsureVariable sets Historizing = historianTagname is not null and ORs AccessLevels.HistoryRead into both AccessLevel and UserAccessLevel when historized; registers _historizedTagnames. CreateVariable (lazy, never historized) stays Historizing = false.
• Event-notifier folders — EnsureFolderIsEventNotifier ORs EventNotifiers.HistoryRead into the promoted folder's EventNotifier when a non-Null historian is wired, and registers _eventNotifierSources[folder.NodeId-string] = folder.NodeId.Identifier (the equipment id). On RebuildAddressSpace, clear _historizedTagnames + _eventNotifierSources alongside the existing guards.

Wiring + DI

• NullHistorianDataSource (Core.Abstractions/Historian) — empty Samples/Events, disabled health snapshot. The node-manager prop default + the DI default.
• ServerHistorianOptions (Runtime/Historian, SectionName = "ServerHistorian") + AddServerHistorian(this IServiceCollection, IConfiguration, Func<ServerHistorianOptions, IServiceProvider, IHistorianDataSource> factory) — Enabled=false ⇒ no-op (Null default from AddOtOpcUaRuntime's new TryAddSingleton<IHistorianDataSource>(NullHistorianDataSource.Instance)); Enabled=true ⇒ AddSingleton the factory result; Validate() warnings mirror AlarmHistorian.
• OtOpcUaSdkServer.SetHistorianDataSource(IHistorianDataSource?) — mirrors SetNodeWriteGateway (null-coalesces to the Null default; returns false if NodeManager not up yet).
• Host — Program.cs adds AddServerHistorian(config, (opts,sp) => new WonderwareHistorianClient( new WonderwareHistorianClientOptions(opts.Host, opts.Port, opts.SharedSecret){ UseTls=…, ServerCertThumbprint=… }, sp.GetService<ILogger<WonderwareHistorianClient>>())); OtOpcUaServerHostedService.StartAsync resolves IHistorianDataSource from DI and calls _server.SetHistorianDataSource(...) (right after SetNodeWriteGateway); StopAsync clears it.

Error handling / edge cases

• Byte-parity invariant — Phase7Composer.ExtractTagHistorize and DeploymentArtifact.ExtractTagHistorize must parse identically; a parity round-trip test guards it (precedent: DeploymentArtifactAliasParityTests).
• Non-historized HistoryRead → BadHistoryOperationUnsupported (node not in _historizedTagnames); the SDK's own AccessLevel check already blocks most before we see them.
• Null / unconfigured historian → GoodNoData empty (not an error).
• Backend timeout / throw → per-node BadHistoryOperationUnsupported + log; batch survives.
• Redeploy → RebuildAddressSpace clears the two new maps; re-materialization re-registers.

Testing (no bUnit, offline xUnit + Shouldly)

• Composer ExtractTagHistorize — true / false / absent / override / malformed-JSON (never throws).
• Artifact parity — composer plan == artifact plan for a historized tag (incl. override) round-trip.
• EnsureVariable — historized ⇒ Historizing==true + HistoryRead access bit + registry entry; non-historized ⇒ unchanged; default-vs-override tagname resolution in the applier.
• HistoryRead override (data) — fake IHistorianDataSource; assert Raw / Processed / AtTime dispatch, tagname passed (default + override), DataValueSnapshot→DataValue mapping (value / status / timestamps), GoodNoData on empty, BadHistoryOperationUnsupported on non-historized, BadAggregateNotSupported on an unknown aggregate.
• HistoryRead override (events) — fake source; assert folder→sourceName resolution + event-field projection for the standard select clauses + empty/Null.
• DI — AddServerHistorian leaves Null when disabled, swaps the real source when enabled; NullHistorianDataSource returns empty.

Live docker-dev /run (user-driven; the agent does NOT sign in) — DEFERRED. Requires the Wonderware sidecar + AVEVA Historian (the WW Historian VM 10.100.0.48), which is not part of the local docker-dev rig, so this gate is inherently operator-driven. When run: author a historized Galaxy equipment tag, set ServerHistorian:Enabled=true pointed at the sidecar, deploy, then Client.CLI historyread → samples return.

Hard rules (carried into implementation)

• Stage by path; never git add .. Never stage sql_login.txt, src/Server/ZB.MOM.WW.OtOpcUa.Host/pki/, pending.md, current.md, or docker-dev/docker-compose.yml. Never echo the gateway API key or the historian SharedSecret into a tracked file. No force-push, no --no-verify.
• NO EF/Configuration entity or migration change — the flag rides in the existing TagConfig blob (the Phase A NamespaceKind migration was a one-off already shipped; Phase C adds none).
• Build on feat/galaxy-phase-c-historian off master c9a0f627.

Authoritative touched-code list

• src/Server/.../OpcUaServer/Phase7Composer.cs — EquipmentTagPlan +2 fields; ExtractTagHistorize.
• src/Server/.../Runtime/Drivers/DeploymentArtifact.cs — byte-parity ExtractTagHistorize + thread.
• src/Core/.../Commons/OpcUa/IOpcUaAddressSpaceSink.cs (+ NullOpcUaAddressSpaceSink, DeferredAddressSpaceSink) — EnsureVariable gains string? historianTagname.
• src/Server/.../OpcUaServer/SdkAddressSpaceSink.cs — pass-through.
• src/Server/.../OpcUaServer/Phase7Applier.cs — resolve + thread the tagname.
• src/Server/.../OpcUaServer/OtOpcUaNodeManager.cs — HistorianDataSource prop, _historizedTagnames, _eventNotifierSources, EnsureVariable/EnsureFolderIsEventNotifier/RebuildAddressSpace edits, the HistoryRead override + mapping helpers.
• src/Server/.../OpcUaServer/OtOpcUaSdkServer.cs — SetHistorianDataSource.
• src/Core/.../Core.Abstractions/Historian/NullHistorianDataSource.cs (new).
• src/Server/.../Runtime/Historian/ServerHistorianOptions.cs (new) + src/Server/.../Runtime/ServiceCollectionExtensions.cs — AddServerHistorian + Null default in AddOtOpcUaRuntime.
• src/Server/.../Host/Program.cs + Host/OpcUa/OtOpcUaServerHostedService.cs — wire the data source.
• Docs: new docs/Historian.md (or a Galaxy-driver note) + a CLAUDE.md pointer; appsettings.json ServerHistorian block (disabled).