using System.Globalization;
using Microsoft.Extensions.Logging;
using Opc.Ua;
using Opc.Ua.Server;
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
using ZB.MOM.WW.OtOpcUa.Core.Resilience;
using ZB.MOM.WW.OtOpcUa.Server.Security;
using DriverWriteRequest = ZB.MOM.WW.OtOpcUa.Core.Abstractions.WriteRequest;
// Core.Abstractions defines a type-named HistoryReadResult (driver-side samples + continuation
// point) that collides with Opc.Ua.HistoryReadResult (service-layer per-node result). We
// assign driver-side results to an explicitly-aliased local and construct only the service
// type in the overrides below.
using OpcHistoryReadResult = Opc.Ua.HistoryReadResult;

namespace ZB.MOM.WW.OtOpcUa.Server.OpcUa;

/// <summary>
///     Concrete <see cref="CustomNodeManager2"/> that materializes the driver's address space
///     into OPC UA nodes. Implements <see cref="IAddressSpaceBuilder"/> itself so
///     <c>GenericDriverNodeManager.BuildAddressSpaceAsync</c> can stream nodes directly into the
///     OPC UA server's namespace. PR 15's <c>MarkAsAlarmCondition</c> hook creates a sibling
///     <see cref="AlarmConditionState"/> node per alarm-flagged variable; subsequent driver
///     <c>OnAlarmEvent</c> pushes land through the returned sink to drive Activate /
///     Acknowledge / Deactivate transitions.
/// </summary>
/// <remarks>
///     Read / Subscribe / Write are routed to the driver's capability interfaces — the node
///     manager holds references to <see cref="IReadable"/>, <see cref="ISubscribable"/>, and
///     <see cref="IWritable"/> when present. Nodes with no driver backing (plain folders) are
///     served directly from the internal PredefinedNodes table.
/// </remarks>
public sealed class DriverNodeManager : CustomNodeManager2, IAddressSpaceBuilder
{
    private readonly IDriver _driver;
    private readonly IReadable? _readable;
    private readonly IWritable? _writable;
    private readonly CapabilityInvoker _invoker;
    private readonly ILogger<DriverNodeManager> _logger;

    // Per-variable idempotency flag populated during Variable() registration from
    // DriverAttributeInfo.WriteIdempotent. Drives ExecuteWriteAsync's retry gating in
    // OnWriteValue; absent entries default to false (decisions #44, #45, #143).
    private readonly Dictionary<string, bool> _writeIdempotentByFullRef = new(StringComparer.OrdinalIgnoreCase);

    /// <summary>The driver whose address space this node manager exposes.</summary>
    public IDriver Driver => _driver;

    private FolderState? _driverRoot;
    private readonly Dictionary<string, BaseDataVariableState> _variablesByFullRef = new(StringComparer.OrdinalIgnoreCase);

    // PR 26: SecurityClassification per variable, populated during Variable() registration.
    // OnWriteValue looks up the classification here to gate the write by the session's roles.
    // Drivers never enforce authz themselves — the classification is discovery-time metadata
    // only (feedback_acl_at_server_layer.md).
    private readonly Dictionary<string, SecurityClassification> _securityByFullRef = new(StringComparer.OrdinalIgnoreCase);

    // Active building folder — set per Folder() call so Variable() lands under the right parent.
    // A stack would support nested folders; we use a single current folder because IAddressSpaceBuilder
    // returns a child builder per Folder call and the caller threads nesting through those references.
    private FolderState _currentFolder = null!;

    public DriverNodeManager(IServerInternal server, ApplicationConfiguration configuration,
        IDriver driver, CapabilityInvoker invoker, ILogger<DriverNodeManager> logger)
        : base(server, configuration, namespaceUris: $"urn:OtOpcUa:{driver.DriverInstanceId}")
    {
        _driver = driver;
        _readable = driver as IReadable;
        _writable = driver as IWritable;
        _invoker = invoker;
        _logger = logger;
    }

    protected override NodeStateCollection LoadPredefinedNodes(ISystemContext context) => new();

    public override void CreateAddressSpace(IDictionary<NodeId, IList<IReference>> externalReferences)
    {
        lock (Lock)
        {
            _driverRoot = new FolderState(null)
            {
                SymbolicName = _driver.DriverInstanceId,
                ReferenceTypeId = ReferenceTypeIds.Organizes,
                TypeDefinitionId = ObjectTypeIds.FolderType,
                NodeId = new NodeId(_driver.DriverInstanceId, NamespaceIndex),
                BrowseName = new QualifiedName(_driver.DriverInstanceId, NamespaceIndex),
                DisplayName = new LocalizedText(_driver.DriverInstanceId),
                // Driver root is the conventional event notifier for HistoryReadEvents — clients
                // request alarm history by targeting it and the node manager routes through
                // IHistoryProvider.ReadEventsAsync. SubscribeToEvents is also set so live-event
                // subscriptions (Alarm & Conditions) can point here in a future PR; today the
                // alarm events are emitted by per-variable AlarmConditionState siblings but a
                // "subscribe to all events from this driver" path would use this notifier.
                EventNotifier = (byte)(EventNotifiers.SubscribeToEvents | EventNotifiers.HistoryRead),
            };

            // Link under Objects folder so clients see the driver subtree at browse root.
            if (!externalReferences.TryGetValue(ObjectIds.ObjectsFolder, out var references))
            {
                references = new List<IReference>();
                externalReferences[ObjectIds.ObjectsFolder] = references;
            }
            references.Add(new NodeStateReference(ReferenceTypeIds.Organizes, false, _driverRoot.NodeId));

            AddPredefinedNode(SystemContext, _driverRoot);
            _currentFolder = _driverRoot;
        }
    }

    // ------- IAddressSpaceBuilder implementation (PR 15 contract) -------

    public IAddressSpaceBuilder Folder(string browseName, string displayName)
    {
        lock (Lock)
        {
            var folder = new FolderState(_currentFolder)
            {
                SymbolicName = browseName,
                ReferenceTypeId = ReferenceTypeIds.Organizes,
                TypeDefinitionId = ObjectTypeIds.FolderType,
                NodeId = new NodeId($"{_currentFolder.NodeId.Identifier}/{browseName}", NamespaceIndex),
                BrowseName = new QualifiedName(browseName, NamespaceIndex),
                DisplayName = new LocalizedText(displayName),
            };
            _currentFolder.AddChild(folder);
            AddPredefinedNode(SystemContext, folder);
            return new NestedBuilder(this, folder);
        }
    }

    public IVariableHandle Variable(string browseName, string displayName, DriverAttributeInfo attributeInfo)
    {
        lock (Lock)
        {
            var v = new BaseDataVariableState(_currentFolder)
            {
                SymbolicName = browseName,
                ReferenceTypeId = ReferenceTypeIds.Organizes,
                TypeDefinitionId = VariableTypeIds.BaseDataVariableType,
                NodeId = new NodeId(attributeInfo.FullName, NamespaceIndex),
                BrowseName = new QualifiedName(browseName, NamespaceIndex),
                DisplayName = new LocalizedText(displayName),
                DataType = MapDataType(attributeInfo.DriverDataType),
                ValueRank = attributeInfo.IsArray ? ValueRanks.OneDimension : ValueRanks.Scalar,
                // Historized attributes get the HistoryRead access bit so the stack dispatches
                // incoming HistoryRead service calls to this node. Without it the base class
                // returns BadHistoryOperationUnsupported before our per-kind hook ever runs.
                // HistoryWrite isn't granted — history rewrite is a separate capability the
                // driver doesn't support today.
                AccessLevel = (byte)(AccessLevels.CurrentReadOrWrite
                    | (attributeInfo.IsHistorized ? AccessLevels.HistoryRead : 0)),
                UserAccessLevel = (byte)(AccessLevels.CurrentReadOrWrite
                    | (attributeInfo.IsHistorized ? AccessLevels.HistoryRead : 0)),
                Historizing = attributeInfo.IsHistorized,
            };
            _currentFolder.AddChild(v);
            AddPredefinedNode(SystemContext, v);
            _variablesByFullRef[attributeInfo.FullName] = v;
            _securityByFullRef[attributeInfo.FullName] = attributeInfo.SecurityClass;
            _writeIdempotentByFullRef[attributeInfo.FullName] = attributeInfo.WriteIdempotent;

            v.OnReadValue = OnReadValue;
            v.OnWriteValue = OnWriteValue;
            return new VariableHandle(this, v, attributeInfo.FullName);
        }
    }

    public void AddProperty(string browseName, DriverDataType dataType, object? value)
    {
        lock (Lock)
        {
            var p = new PropertyState(_currentFolder)
            {
                SymbolicName = browseName,
                ReferenceTypeId = ReferenceTypeIds.HasProperty,
                TypeDefinitionId = VariableTypeIds.PropertyType,
                NodeId = new NodeId($"{_currentFolder.NodeId.Identifier}/{browseName}", NamespaceIndex),
                BrowseName = new QualifiedName(browseName, NamespaceIndex),
                DisplayName = new LocalizedText(browseName),
                DataType = MapDataType(dataType),
                ValueRank = ValueRanks.Scalar,
                Value = value,
            };
            _currentFolder.AddChild(p);
            AddPredefinedNode(SystemContext, p);
        }
    }

    private ServiceResult OnReadValue(ISystemContext context, NodeState node, NumericRange indexRange,
        QualifiedName dataEncoding, ref object? value, ref StatusCode statusCode, ref DateTime timestamp)
    {
        if (_readable is null)
        {
            statusCode = StatusCodes.BadNotReadable;
            return ServiceResult.Good;
        }

        try
        {
            var fullRef = node.NodeId.Identifier as string ?? "";
            var result = _invoker.ExecuteAsync(
                DriverCapability.Read,
                _driver.DriverInstanceId,
                async ct => (IReadOnlyList<DataValueSnapshot>)await _readable.ReadAsync([fullRef], ct).ConfigureAwait(false),
                CancellationToken.None).AsTask().GetAwaiter().GetResult();
            if (result.Count == 0)
            {
                statusCode = StatusCodes.BadNoData;
                return ServiceResult.Good;
            }
            var snap = result[0];
            value = snap.Value;
            statusCode = snap.StatusCode;
            timestamp = snap.ServerTimestampUtc;
        }
        catch (Exception ex)
        {
            _logger.LogWarning(ex, "OnReadValue failed for {NodeId}", node.NodeId);
            statusCode = StatusCodes.BadInternalError;
        }
        return ServiceResult.Good;
    }

    private static NodeId MapDataType(DriverDataType t) => t switch
    {
        DriverDataType.Boolean => DataTypeIds.Boolean,
        DriverDataType.Int32 => DataTypeIds.Int32,
        DriverDataType.Float32 => DataTypeIds.Float,
        DriverDataType.Float64 => DataTypeIds.Double,
        DriverDataType.String => DataTypeIds.String,
        DriverDataType.DateTime => DataTypeIds.DateTime,
        _ => DataTypeIds.BaseDataType,
    };

    /// <summary>
    ///     Nested builder returned by <see cref="Folder"/>. Temporarily retargets the parent's
    ///     <see cref="_currentFolder"/> during each call so Variable/Folder calls land under the
    ///     correct subtree. Not thread-safe if callers drive Discovery concurrently — but
    ///     <c>GenericDriverNodeManager</c> discovery is sequential per driver.
    /// </summary>
    private sealed class NestedBuilder(DriverNodeManager owner, FolderState folder) : IAddressSpaceBuilder
    {
        public IAddressSpaceBuilder Folder(string browseName, string displayName)
        {
            var prior = owner._currentFolder;
            owner._currentFolder = folder;
            try { return owner.Folder(browseName, displayName); }
            finally { owner._currentFolder = prior; }
        }

        public IVariableHandle Variable(string browseName, string displayName, DriverAttributeInfo attributeInfo)
        {
            var prior = owner._currentFolder;
            owner._currentFolder = folder;
            try { return owner.Variable(browseName, displayName, attributeInfo); }
            finally { owner._currentFolder = prior; }
        }

        public void AddProperty(string browseName, DriverDataType dataType, object? value)
        {
            var prior = owner._currentFolder;
            owner._currentFolder = folder;
            try { owner.AddProperty(browseName, dataType, value); }
            finally { owner._currentFolder = prior; }
        }
    }

    private sealed class VariableHandle : IVariableHandle
    {
        private readonly DriverNodeManager _owner;
        private readonly BaseDataVariableState _variable;
        public string FullReference { get; }

        public VariableHandle(DriverNodeManager owner, BaseDataVariableState variable, string fullRef)
        {
            _owner = owner;
            _variable = variable;
            FullReference = fullRef;
        }

        public IAlarmConditionSink MarkAsAlarmCondition(AlarmConditionInfo info)
        {
            lock (_owner.Lock)
            {
                var alarm = new AlarmConditionState(_variable)
                {
                    SymbolicName = _variable.BrowseName.Name + "_Condition",
                    ReferenceTypeId = ReferenceTypeIds.HasComponent,
                    NodeId = new NodeId(FullReference + ".Condition", _owner.NamespaceIndex),
                    BrowseName = new QualifiedName(_variable.BrowseName.Name + "_Condition", _owner.NamespaceIndex),
                    DisplayName = new LocalizedText(info.SourceName),
                };
                alarm.Create(_owner.SystemContext, alarm.NodeId, alarm.BrowseName, alarm.DisplayName, false);
                alarm.SourceName.Value = info.SourceName;
                alarm.Severity.Value = (ushort)MapSeverity(info.InitialSeverity);
                alarm.Message.Value = new LocalizedText(info.InitialDescription ?? info.SourceName);
                alarm.EnabledState.Value = new LocalizedText("Enabled");
                alarm.EnabledState.Id.Value = true;
                alarm.Retain.Value = false;
                alarm.AckedState.Value = new LocalizedText("Acknowledged");
                alarm.AckedState.Id.Value = true;
                alarm.ActiveState.Value = new LocalizedText("Inactive");
                alarm.ActiveState.Id.Value = false;

                _variable.AddChild(alarm);
                _owner.AddPredefinedNode(_owner.SystemContext, alarm);

                return new ConditionSink(_owner, alarm);
            }
        }

        private static int MapSeverity(AlarmSeverity s) => s switch
        {
            AlarmSeverity.Low => 250,
            AlarmSeverity.Medium => 500,
            AlarmSeverity.High => 700,
            AlarmSeverity.Critical => 900,
            _ => 500,
        };
    }

    private sealed class ConditionSink(DriverNodeManager owner, AlarmConditionState alarm)
        : IAlarmConditionSink
    {
        public void OnTransition(AlarmEventArgs args)
        {
            lock (owner.Lock)
            {
                alarm.Severity.Value = (ushort)MapSeverity(args.Severity);
                alarm.Time.Value = args.SourceTimestampUtc;
                alarm.Message.Value = new LocalizedText(args.Message);

                // Map the driver's transition type to OPC UA Part 9 state. The driver uses
                // AlarmEventArgs but the state transition kind is encoded in AlarmType by
                // convention — Galaxy's GalaxyAlarmTracker emits "Active"/"Acknowledged"/"Inactive".
                switch (args.AlarmType)
                {
                    case "Active":
                        alarm.SetActiveState(owner.SystemContext, true);
                        alarm.SetAcknowledgedState(owner.SystemContext, false);
                        alarm.Retain.Value = true;
                        break;
                    case "Acknowledged":
                        alarm.SetAcknowledgedState(owner.SystemContext, true);
                        break;
                    case "Inactive":
                        alarm.SetActiveState(owner.SystemContext, false);
                        // Retain stays true until the condition is both Inactive and Acknowledged
                        // so alarm clients keep the record in their condition refresh snapshot.
                        if (alarm.AckedState.Id.Value) alarm.Retain.Value = false;
                        break;
                }

                alarm.ClearChangeMasks(owner.SystemContext, true);
                alarm.ReportEvent(owner.SystemContext, alarm);
            }
        }

        private static int MapSeverity(AlarmSeverity s) => s switch
        {
            AlarmSeverity.Low => 250,
            AlarmSeverity.Medium => 500,
            AlarmSeverity.High => 700,
            AlarmSeverity.Critical => 900,
            _ => 500,
        };
    }

    /// <summary>
    ///     Per-variable write hook wired on each <see cref="BaseDataVariableState"/>. Routes the
    ///     value into the driver's <see cref="IWritable"/> and surfaces its per-tag status code.
    /// </summary>
    private ServiceResult OnWriteValue(ISystemContext context, NodeState node, NumericRange indexRange,
        QualifiedName dataEncoding, ref object? value, ref StatusCode statusCode, ref DateTime timestamp)
    {
        if (_writable is null) return StatusCodes.BadNotWritable;
        var fullRef = node.NodeId.Identifier as string;
        if (string.IsNullOrEmpty(fullRef)) return StatusCodes.BadNodeIdUnknown;

        // PR 26: server-layer write authorization. Look up the attribute's classification
        // (populated during Variable() in Discover) and check the session's roles against the
        // policy table. Drivers don't participate in this decision — IWritable.WriteAsync
        // never sees a request we'd have refused here.
        if (_securityByFullRef.TryGetValue(fullRef!, out var classification))
        {
            var roles = context.UserIdentity is IRoleBearer rb ? rb.Roles : [];
            if (!WriteAuthzPolicy.IsAllowed(classification, roles))
            {
                _logger.LogInformation(
                    "Write denied for {FullRef}: classification={Classification} userRoles=[{Roles}]",
                    fullRef, classification, string.Join(",", roles));
                return new ServiceResult(StatusCodes.BadUserAccessDenied);
            }
        }

        try
        {
            var isIdempotent = _writeIdempotentByFullRef.GetValueOrDefault(fullRef!, false);
            var capturedValue = value;
            var results = _invoker.ExecuteWriteAsync(
                _driver.DriverInstanceId,
                isIdempotent,
                async ct => (IReadOnlyList<WriteResult>)await _writable.WriteAsync(
                    [new DriverWriteRequest(fullRef!, capturedValue)],
                    ct).ConfigureAwait(false),
                CancellationToken.None).AsTask().GetAwaiter().GetResult();
            if (results.Count > 0 && results[0].StatusCode != 0)
            {
                statusCode = results[0].StatusCode;
                return ServiceResult.Good;
            }
            return ServiceResult.Good;
        }
        catch (Exception ex)
        {
            _logger.LogWarning(ex, "Write failed for {FullRef}", fullRef);
            return new ServiceResult(StatusCodes.BadInternalError);
        }
    }

    // Diagnostics hook for tests — number of variables registered in this node manager.
    internal int VariableCount => _variablesByFullRef.Count;
    internal bool TryGetVariable(string fullRef, out BaseDataVariableState? v)
        => _variablesByFullRef.TryGetValue(fullRef, out v!);

    // ===================== HistoryRead service handlers (LMX #1, PR 38) =====================
    //
    // Wires the driver's IHistoryProvider capability (PR 35 added ReadAtTimeAsync / ReadEventsAsync
    // alongside the PR 19 ReadRawAsync / ReadProcessedAsync) to the OPC UA HistoryRead service.
    // CustomNodeManager2 has four protected per-kind hooks; the base dispatches to the right one
    // based on the concrete HistoryReadDetails subtype. Each hook is sync-returning-void — the
    // per-driver async calls are bridged via GetAwaiter().GetResult(), matching the pattern
    // OnReadValue / OnWriteValue already use in this class so HistoryRead doesn't introduce a
    // different sync-over-async convention.
    //
    // Per-node routing: every HistoryReadValueId in nodesToRead has a NodeHandle in
    // nodesToProcess; the NodeHandle's NodeId.Identifier is the driver-side full reference
    // (set during Variable() registration) so we can dispatch straight to IHistoryProvider
    // without a second lookup. Nodes without IHistoryProvider backing (drivers that don't
    // implement the capability) surface BadHistoryOperationUnsupported per slot and the
    // rest of the batch continues — same failure-isolation pattern as OnWriteValue.
    //
    // Continuation-point handling is pass-through only in this PR: the driver returns null
    // from its ContinuationPoint field today so the outer result's ContinuationPoint stays
    // empty. Full Session.SaveHistoryContinuationPoint plumbing is a follow-up when a driver
    // actually needs paging — the dispatch shape doesn't change, only the result-population.

    private IHistoryProvider? History => _driver as IHistoryProvider;

    protected override void HistoryReadRawModified(
        ServerSystemContext context, ReadRawModifiedDetails details, TimestampsToReturn timestamps,
        IList<HistoryReadValueId> nodesToRead, IList<OpcHistoryReadResult> results,
        IList<ServiceResult> errors, List<NodeHandle> nodesToProcess,
        IDictionary<NodeId, NodeState> cache)
    {
        if (History is null)
        {
            MarkAllUnsupported(nodesToProcess, results, errors);
            return;
        }

        // IsReadModified=true requests a "modifications" history (who changed the data, when
        // it was re-written). The driver side has no modifications store — surface that
        // explicitly rather than silently returning raw data, which would mislead the client.
        if (details.IsReadModified)
        {
            MarkAllUnsupported(nodesToProcess, results, errors, StatusCodes.BadHistoryOperationUnsupported);
            return;
        }

        for (var n = 0; n < nodesToProcess.Count; n++)
        {
            var handle = nodesToProcess[n];
            // NodeHandle.Index points back to the slot in the outer results/errors/nodesToRead
            // arrays. nodesToProcess is the filtered subset (just the nodes this manager
            // claimed), so writing to results[n] lands in the wrong slot when N > 1 and nodes
            // are interleaved across multiple node managers.
            var i = handle.Index;
            var fullRef = ResolveFullRef(handle);
            if (fullRef is null)
            {
                WriteNodeIdUnknown(results, errors, i);
                continue;
            }

            try
            {
                var driverResult = _invoker.ExecuteAsync(
                    DriverCapability.HistoryRead,
                    _driver.DriverInstanceId,
                    async ct => await History.ReadRawAsync(
                        fullRef,
                        details.StartTime,
                        details.EndTime,
                        details.NumValuesPerNode,
                        ct).ConfigureAwait(false),
                    CancellationToken.None).AsTask().GetAwaiter().GetResult();

                WriteResult(results, errors, i, StatusCodes.Good,
                    BuildHistoryData(driverResult.Samples), driverResult.ContinuationPoint);
            }
            catch (NotSupportedException)
            {
                WriteUnsupported(results, errors, i);
            }
            catch (Exception ex)
            {
                _logger.LogWarning(ex, "HistoryReadRaw failed for {FullRef}", fullRef);
                WriteInternalError(results, errors, i);
            }
        }
    }

    protected override void HistoryReadProcessed(
        ServerSystemContext context, ReadProcessedDetails details, TimestampsToReturn timestamps,
        IList<HistoryReadValueId> nodesToRead, IList<OpcHistoryReadResult> results,
        IList<ServiceResult> errors, List<NodeHandle> nodesToProcess,
        IDictionary<NodeId, NodeState> cache)
    {
        if (History is null)
        {
            MarkAllUnsupported(nodesToProcess, results, errors);
            return;
        }

        // AggregateType is one NodeId shared across every item in the batch — map once.
        var aggregate = MapAggregate(details.AggregateType?.FirstOrDefault());
        if (aggregate is null)
        {
            MarkAllUnsupported(nodesToProcess, results, errors, StatusCodes.BadAggregateNotSupported);
            return;
        }

        var interval = TimeSpan.FromMilliseconds(details.ProcessingInterval);
        for (var n = 0; n < nodesToProcess.Count; n++)
        {
            var handle = nodesToProcess[n];
            // NodeHandle.Index points back to the slot in the outer results/errors/nodesToRead
            // arrays. nodesToProcess is the filtered subset (just the nodes this manager
            // claimed), so writing to results[n] lands in the wrong slot when N > 1 and nodes
            // are interleaved across multiple node managers.
            var i = handle.Index;
            var fullRef = ResolveFullRef(handle);
            if (fullRef is null)
            {
                WriteNodeIdUnknown(results, errors, i);
                continue;
            }

            try
            {
                var driverResult = _invoker.ExecuteAsync(
                    DriverCapability.HistoryRead,
                    _driver.DriverInstanceId,
                    async ct => await History.ReadProcessedAsync(
                        fullRef,
                        details.StartTime,
                        details.EndTime,
                        interval,
                        aggregate.Value,
                        ct).ConfigureAwait(false),
                    CancellationToken.None).AsTask().GetAwaiter().GetResult();

                WriteResult(results, errors, i, StatusCodes.Good,
                    BuildHistoryData(driverResult.Samples), driverResult.ContinuationPoint);
            }
            catch (NotSupportedException)
            {
                WriteUnsupported(results, errors, i);
            }
            catch (Exception ex)
            {
                _logger.LogWarning(ex, "HistoryReadProcessed failed for {FullRef}", fullRef);
                WriteInternalError(results, errors, i);
            }
        }
    }

    protected override void HistoryReadAtTime(
        ServerSystemContext context, ReadAtTimeDetails details, TimestampsToReturn timestamps,
        IList<HistoryReadValueId> nodesToRead, IList<OpcHistoryReadResult> results,
        IList<ServiceResult> errors, List<NodeHandle> nodesToProcess,
        IDictionary<NodeId, NodeState> cache)
    {
        if (History is null)
        {
            MarkAllUnsupported(nodesToProcess, results, errors);
            return;
        }

        var requestedTimes = (IReadOnlyList<DateTime>)(details.ReqTimes?.ToArray() ?? Array.Empty<DateTime>());
        for (var n = 0; n < nodesToProcess.Count; n++)
        {
            var handle = nodesToProcess[n];
            // NodeHandle.Index points back to the slot in the outer results/errors/nodesToRead
            // arrays. nodesToProcess is the filtered subset (just the nodes this manager
            // claimed), so writing to results[n] lands in the wrong slot when N > 1 and nodes
            // are interleaved across multiple node managers.
            var i = handle.Index;
            var fullRef = ResolveFullRef(handle);
            if (fullRef is null)
            {
                WriteNodeIdUnknown(results, errors, i);
                continue;
            }

            try
            {
                var driverResult = _invoker.ExecuteAsync(
                    DriverCapability.HistoryRead,
                    _driver.DriverInstanceId,
                    async ct => await History.ReadAtTimeAsync(fullRef, requestedTimes, ct).ConfigureAwait(false),
                    CancellationToken.None).AsTask().GetAwaiter().GetResult();

                WriteResult(results, errors, i, StatusCodes.Good,
                    BuildHistoryData(driverResult.Samples), driverResult.ContinuationPoint);
            }
            catch (NotSupportedException)
            {
                WriteUnsupported(results, errors, i);
            }
            catch (Exception ex)
            {
                _logger.LogWarning(ex, "HistoryReadAtTime failed for {FullRef}", fullRef);
                WriteInternalError(results, errors, i);
            }
        }
    }

    protected override void HistoryReadEvents(
        ServerSystemContext context, ReadEventDetails details, TimestampsToReturn timestamps,
        IList<HistoryReadValueId> nodesToRead, IList<OpcHistoryReadResult> results,
        IList<ServiceResult> errors, List<NodeHandle> nodesToProcess,
        IDictionary<NodeId, NodeState> cache)
    {
        if (History is null)
        {
            MarkAllUnsupported(nodesToProcess, results, errors);
            return;
        }

        // SourceName filter extraction is deferred — EventFilter SelectClauses + WhereClause
        // handling is a dedicated concern (proper per-select-clause Variant population + where
        // filter evaluation). This PR treats the event query as "all events in range for the
        // node's source" and populates only the standard BaseEventType fields. Richer filter
        // handling is a follow-up; clients issuing empty/default filters get the right answer
        // today which covers the common alarm-history browse case.
        var maxEvents = (int)details.NumValuesPerNode;
        if (maxEvents <= 0) maxEvents = 1000;

        for (var n = 0; n < nodesToProcess.Count; n++)
        {
            var handle = nodesToProcess[n];
            // NodeHandle.Index points back to the slot in the outer results/errors/nodesToRead
            // arrays. nodesToProcess is the filtered subset (just the nodes this manager
            // claimed), so writing to results[n] lands in the wrong slot when N > 1 and nodes
            // are interleaved across multiple node managers.
            var i = handle.Index;
            // Event history queries may target a notifier object (e.g. the driver-root folder)
            // rather than a specific variable — in that case we pass sourceName=null to mean
            // "all sources in the driver's namespace" per the IHistoryProvider contract.
            var fullRef = ResolveFullRef(handle);

            try
            {
                var driverResult = _invoker.ExecuteAsync(
                    DriverCapability.HistoryRead,
                    _driver.DriverInstanceId,
                    async ct => await History.ReadEventsAsync(
                        sourceName: fullRef,
                        startUtc: details.StartTime,
                        endUtc: details.EndTime,
                        maxEvents: maxEvents,
                        cancellationToken: ct).ConfigureAwait(false),
                    CancellationToken.None).AsTask().GetAwaiter().GetResult();

                WriteResult(results, errors, i, StatusCodes.Good,
                    BuildHistoryEvent(driverResult.Events), driverResult.ContinuationPoint);
            }
            catch (NotSupportedException)
            {
                WriteUnsupported(results, errors, i);
            }
            catch (Exception ex)
            {
                _logger.LogWarning(ex, "HistoryReadEvents failed for {FullRef}", fullRef);
                WriteInternalError(results, errors, i);
            }
        }
    }

    private string? ResolveFullRef(NodeHandle handle) => handle.NodeId?.Identifier as string;

    // Both the results list AND the parallel errors list must be populated — MasterNodeManager
    // merges them and the merged StatusCode is what the client sees. Leaving errors[i] at its
    // default (BadHistoryOperationUnsupported) overrides a Good result with Unsupported, which
    // masks a correctly-constructed HistoryData response. This was the subtle failure mode
    // that cost most of PR 38's debugging budget.
    private static void WriteResult(IList<OpcHistoryReadResult> results, IList<ServiceResult> errors,
        int i, uint statusCode, ExtensionObject historyData, byte[]? continuationPoint)
    {
        results[i] = new OpcHistoryReadResult
        {
            StatusCode = statusCode,
            HistoryData = historyData,
            ContinuationPoint = continuationPoint,
        };
        errors[i] = statusCode == StatusCodes.Good
            ? ServiceResult.Good
            : new ServiceResult(statusCode);
    }

    private static void WriteUnsupported(IList<OpcHistoryReadResult> results, IList<ServiceResult> errors, int i)
    {
        results[i] = new OpcHistoryReadResult { StatusCode = StatusCodes.BadHistoryOperationUnsupported };
        errors[i] = StatusCodes.BadHistoryOperationUnsupported;
    }

    private static void WriteInternalError(IList<OpcHistoryReadResult> results, IList<ServiceResult> errors, int i)
    {
        results[i] = new OpcHistoryReadResult { StatusCode = StatusCodes.BadInternalError };
        errors[i] = StatusCodes.BadInternalError;
    }

    private static void WriteNodeIdUnknown(IList<OpcHistoryReadResult> results, IList<ServiceResult> errors, int i)
    {
        WriteNodeIdUnknown(results, errors, i);
        errors[i] = StatusCodes.BadNodeIdUnknown;
    }

    private static void MarkAllUnsupported(
        List<NodeHandle> nodes, IList<OpcHistoryReadResult> results, IList<ServiceResult> errors,
        uint statusCode = StatusCodes.BadHistoryOperationUnsupported)
    {
        foreach (var handle in nodes)
        {
            results[handle.Index] = new OpcHistoryReadResult { StatusCode = statusCode };
            errors[handle.Index] = statusCode == StatusCodes.Good ? ServiceResult.Good : new ServiceResult(statusCode);
        }
    }

    /// <summary>
    ///     Map the OPC UA Part 13 aggregate-function NodeId to the driver's
    ///     <see cref="HistoryAggregateType"/>. Internal so the test suite can pin the mapping
    ///     without exposing public API. Returns null for unsupported aggregates so the service
    ///     handler can surface <c>BadAggregateNotSupported</c> on the whole batch.
    /// </summary>
    internal static HistoryAggregateType? MapAggregate(NodeId? aggregateNodeId)
    {
        if (aggregateNodeId is null) return null;

        // Every AggregateFunction_* identifier is a numeric uint on the Server (0) namespace.
        // Comparing NodeIds by value handles all the cross-encoding cases (expanded vs plain).
        if (aggregateNodeId == ObjectIds.AggregateFunction_Average) return HistoryAggregateType.Average;
        if (aggregateNodeId == ObjectIds.AggregateFunction_Minimum) return HistoryAggregateType.Minimum;
        if (aggregateNodeId == ObjectIds.AggregateFunction_Maximum) return HistoryAggregateType.Maximum;
        if (aggregateNodeId == ObjectIds.AggregateFunction_Total) return HistoryAggregateType.Total;
        if (aggregateNodeId == ObjectIds.AggregateFunction_Count) return HistoryAggregateType.Count;
        return null;
    }

    /// <summary>
    ///     Wrap driver samples as <c>HistoryData</c> in an <c>ExtensionObject</c> — the on-wire
    ///     shape the OPC UA HistoryRead service expects for raw / processed / at-time reads.
    /// </summary>
    internal static ExtensionObject BuildHistoryData(IReadOnlyList<DataValueSnapshot> samples)
    {
        var values = new DataValueCollection(samples.Count);
        foreach (var s in samples) values.Add(ToDataValue(s));
        return new ExtensionObject(new HistoryData { DataValues = values });
    }

    /// <summary>
    ///     Wrap driver events as <c>HistoryEvent</c> in an <c>ExtensionObject</c>. Populates
    ///     the minimum BaseEventType field set (SourceName, Message, Severity, Time,
    ///     ReceiveTime, EventId) so clients that request the default
    ///     <c>SimpleAttributeOperand</c> select-clauses see useful data. Custom EventFilter
    ///     SelectClause evaluation is deferred — when a client sends a specific operand list,
    ///     they currently get the standard fields back and ignore the extras. Documented on the
    ///     public follow-up list.
    /// </summary>
    internal static ExtensionObject BuildHistoryEvent(IReadOnlyList<HistoricalEvent> events)
    {
        var fieldLists = new HistoryEventFieldListCollection(events.Count);
        foreach (var e in events)
        {
            var fields = new VariantCollection
            {
                // Order must match BaseEventType's conventional field ordering so clients that
                // didn't customize the SelectClauses still see recognizable columns. A future
                // PR that respects the client's SelectClause list will drive this from the filter.
                new Variant(e.EventId),
                new Variant(e.SourceName ?? string.Empty),
                new Variant(new LocalizedText(e.Message ?? string.Empty)),
                new Variant(e.Severity),
                new Variant(e.EventTimeUtc),
                new Variant(e.ReceivedTimeUtc),
            };
            fieldLists.Add(new HistoryEventFieldList { EventFields = fields });
        }
        return new ExtensionObject(new HistoryEvent { Events = fieldLists });
    }

    internal static DataValue ToDataValue(DataValueSnapshot s)
    {
        var dv = new DataValue
        {
            Value = s.Value,
            StatusCode = new StatusCode(s.StatusCode),
            ServerTimestamp = s.ServerTimestampUtc,
        };
        if (s.SourceTimestampUtc.HasValue) dv.SourceTimestamp = s.SourceTimestampUtc.Value;
        return dv;
    }
}