fix(http): evict stale devices and isolate DeviceReceived handler faults

Lands four §19 review findings on the issue-176 surface:

- F-001: clear the _devices cache at the start of every probe inside
  the same lock block that clears _cachedComponents and _cachedDataItems
  so devices the agent no longer advertises are evicted before the new
  probe is loaded. The Devices accessor's XML doc claimed the snapshot
  reflected the most recent probe; without the clear, stale UUIDs
  persisted indefinitely.

- F-002: wrap DeviceReceived?.Invoke in try/catch and route subscriber
  exceptions through InternalError. A throwing handler previously
  aborted the populate loop mid-stream, leaving the cache half-filled
  and suppressing ProbeReceived for that probe. The Worker loop's
  outer catch around the same fan-out at line 860 already used this
  pattern; this finding extends it to the per-device event.

- F-004: wrap the snapshot in ReadOnlyDictionary so a consumer cannot
  mutate the cache through a downcast. The Devices XML doc promised a
  read-only contract; without the wrapper the runtime type stayed a
  plain Dictionary that downcasts could mutate.

- F-005: tighten spaced em-dashes in the DeviceReceived summary to the
  unspaced form per CONVENTIONS §1.0d-decies.

Adds three NUnit tests pinning the new invariants and closing two §10a
negative-coverage gaps the review surfaced (F-008, F-009):

- DeviceReceivedFiresOnEverySubsequentProbe — restarts the client so a
  second probe round-trip runs through the same agent and asserts the
  event re-fires for every device on the second probe.
- DevicesAccessorReflectsLatestProbeWithStaleEntriesEvicted — pins the
  F-001 eviction contract.
- DeviceReceivedHandlerThrowingDoesNotBreakCachePopulation — pins the
  F-002 isolation contract.

Author: ottobolyos

libraries/MTConnect.NET-HTTP/Clients/MTConnectHttpClient.cs

@@ -11,6 +11,7 @@
 using MTConnect.Streams;
 using System;
 using System.Collections.Generic;
+using System.Collections.ObjectModel;
 using System.Linq;
 using System.Threading;
 using System.Threading.Tasks;
@@ -183,7 +184,9 @@ private void Init()
         /// A snapshot of the device model received from the most recent Probe response,
         /// keyed by device UUID. The dictionary is empty until the first probe succeeds.
         /// Each call returns a fresh snapshot reflecting the most recently completed probe;
-        /// previously returned snapshots are unaffected by subsequent probes. Each
+        /// previously returned snapshots are unaffected by subsequent probes, and devices
+        /// that disappear between probes are evicted at the start of the next probe so the
+        /// snapshot never carries entries the agent no longer advertises. Each
         /// <see cref="IDevice"/>'s DataItems carry the fully wired
         /// <see cref="IDataItem.Container"/> and <see cref="IDataItem.Device"/>
         /// back-pointers set during parsing, so consumers can walk the component ancestry
@@ -192,23 +195,30 @@ private void Init()
         /// <remarks>
         /// <para>
         /// The dictionary returned by each call is a fresh allocation independent of the
-        /// cache; the <see cref="IDevice"/> values within are shared references to cached
-        /// instances that the client replaces wholesale on each probe. The accessor
-        /// acquires the client's internal lock, so callers may enumerate the snapshot
-        /// without synchronizing against the worker thread that processes subsequent probes.
+        /// cache, wrapped in a <see cref="ReadOnlyDictionary{TKey, TValue}"/>
+        /// so consumers cannot mutate the snapshot through a downcast. The <see cref="IDevice"/>
+        /// values within are shared references to cached instances that the client replaces
+        /// wholesale on each probe. The accessor acquires the client's internal lock, so
+        /// callers may enumerate the snapshot without synchronizing against the worker thread
+        /// that processes subsequent probes.
         /// </para>
         /// <para>
         /// Each access allocates a fresh dictionary. Cache the returned reference if you
         /// read repeatedly between probes.
         /// </para>
+        /// <para>
+        /// Empty probe responses (where the agent answers with no devices) do not clear the
+        /// cache; the previous snapshot stays presented until the next non-empty probe.
+        /// </para>
         /// </remarks>
         public IReadOnlyDictionary<string, IDevice> Devices
         {
             get
             {
                 lock (_lock)
                 {
-                    return new Dictionary<string, IDevice>(_devices);
+                    return new ReadOnlyDictionary<string, IDevice>(
+                        new Dictionary<string, IDevice>(_devices));
                 }
             }
         }
@@ -218,15 +228,17 @@ public IReadOnlyDictionary<string, IDevice> Devices
 
         /// <summary>
         /// Raised once per parsed device for every Probe response the client receives,
-        /// carrying the fully wired <see cref="IDevice"/> instance — the same instance
-        /// the <see cref="Devices"/> snapshot accessor would return for that UUID — with
-        /// its DataItems' <see cref="IDataItem.Container"/> and <see cref="IDataItem.Device"/>
+        /// carrying the fully wired <see cref="IDevice"/> instance—the same instance the
+        /// <see cref="Devices"/> snapshot accessor would return for that UUID—with its
+        /// DataItems' <see cref="IDataItem.Container"/> and <see cref="IDataItem.Device"/>
         /// back-pointers set, and the agent's <c>InstanceId</c> stamped on each DataItem.
         /// </summary>
         /// <remarks>
         /// Handlers fire in document order while the cache is still being populated.
         /// Subscribe to <see cref="ProbeReceived"/> to receive notification after the full
-        /// probe response has been processed.
+        /// probe response has been processed. A handler that throws is isolated by the
+        /// client: the exception is forwarded through <see cref="InternalError"/> and the
+        /// cache fill plus subsequent fan-out continue normally.
         /// </remarks>
         public event EventHandler<IDevice> DeviceReceived;
 
@@ -871,11 +883,13 @@ private void ProcessProbeDocument(IDevicesResponseDocument document)
         {
             if (document != null && !document.Devices.IsNullOrEmpty())
             {
-                // Clear Cached DataItems and Components
+                // Clear cached DataItems, Components, and the device snapshot so devices
+                // the agent no longer advertises are evicted before the new probe is loaded.
                 lock (_lock)
                 {
                     _cachedComponents.Clear();
                     _cachedDataItems.Clear();
+                    _devices.Clear();
                 }
 
                 foreach (var device in document.Devices)
@@ -890,7 +904,16 @@ private void ProcessProbeDocument(IDevicesResponseDocument document)
                     }
 
                     // Fire per-device inside the populate loop so the cache and event stay in lockstep.
-                    DeviceReceived?.Invoke(this, outputDevice);
+                    // Isolate subscriber exceptions so one bad handler cannot abort the populate loop
+                    // or suppress ProbeReceived; route the fault through InternalError instead.
+                    try
+                    {
+                        DeviceReceived?.Invoke(this, outputDevice);
+                    }
+                    catch (Exception ex)
+                    {
+                        InternalError?.Invoke(this, ex);
+                    }
                 }
 
                 // Raise ProbeReceived Event

tests/MTConnect.NET-HTTP-Tests/Clients/HttpClientDeviceModel.cs

@@ -190,5 +190,141 @@ public void DeviceReceivedCarriesWiredDataItemBackPointers()
                 client.Stop();
             }
         }
+
+        /// <summary>Pins the behaviour expressed by the test name: device received fires on every subsequent probe, not just the first.</summary>
+        [Test]
+        public void DeviceReceivedFiresOnEverySubsequentProbe()
+        {
+            var client = new MTConnectHttpClient(Hostname, Port);
+
+            using var firstProbeSignal = new ManualResetEventSlim(false);
+            using var secondProbeSignal = new ManualResetEventSlim(false);
+            var probeCount = 0;
+            client.ProbeReceived += (_, _) =>
+            {
+                var n = Interlocked.Increment(ref probeCount);
+                if (n == 1) firstProbeSignal.Set();
+                else if (n == 2) secondProbeSignal.Set();
+            };
+
+            var deviceFireCount = 0;
+            client.DeviceReceived += (_, _) => Interlocked.Increment(ref deviceFireCount);
+
+            try
+            {
+                client.Start();
+                Assert.That(firstProbeSignal.Wait(ProbeWaitTimeoutMs), Is.True, "First ProbeReceived did not fire within the timeout");
+
+                var firstFireCount = Volatile.Read(ref deviceFireCount);
+                Assert.That(firstFireCount, Is.EqualTo(ExpectedDocumentEntryCount), "DeviceReceived did not fire once per device on the first probe");
+            }
+            finally
+            {
+                client.Stop();
+            }
+
+            // Restart the client to force a second probe round-trip through the same
+            // agent; the event must fire again for every device in the second probe,
+            // not stay quiet.
+            try
+            {
+                client.Start();
+                Assert.That(secondProbeSignal.Wait(ProbeWaitTimeoutMs), Is.True, "Second ProbeReceived did not fire within the timeout");
+
+                var totalFireCount = Volatile.Read(ref deviceFireCount);
+                Assert.That(totalFireCount, Is.EqualTo(ExpectedDocumentEntryCount * 2), "DeviceReceived did not re-fire on the second probe");
+            }
+            finally
+            {
+                client.Stop();
+            }
+        }
+
+        /// <summary>Pins the behaviour expressed by the test name: devices accessor reflects the latest probe with stale entries evicted.</summary>
+        [Test]
+        public void DevicesAccessorReflectsLatestProbeWithStaleEntriesEvicted()
+        {
+            var client = new MTConnectHttpClient(Hostname, Port);
+
+            using var firstProbeSignal = new ManualResetEventSlim(false);
+            using var secondProbeSignal = new ManualResetEventSlim(false);
+            var probeCount = 0;
+            client.ProbeReceived += (_, _) =>
+            {
+                var n = Interlocked.Increment(ref probeCount);
+                if (n == 1) firstProbeSignal.Set();
+                else if (n == 2) secondProbeSignal.Set();
+            };
+
+            try
+            {
+                client.Start();
+                Assert.That(firstProbeSignal.Wait(ProbeWaitTimeoutMs), Is.True, "First ProbeReceived did not fire within the timeout");
+            }
+            finally
+            {
+                client.Stop();
+            }
+
+            try
+            {
+                client.Start();
+                Assert.That(secondProbeSignal.Wait(ProbeWaitTimeoutMs), Is.True, "Second ProbeReceived did not fire within the timeout");
+
+                // The cache is cleared at the start of every probe, so the post-second-probe
+                // snapshot count must equal the agent's device count, not double it. This
+                // pins the eviction-on-reprobe contract surfaced by the §19 review.
+                var snapshot = client.Devices;
+                Assert.That(snapshot.Count, Is.EqualTo(ExpectedDocumentEntryCount), "Devices accessor accumulated devices across probes instead of evicting stale entries");
+            }
+            finally
+            {
+                client.Stop();
+            }
+        }
+
+        /// <summary>Pins the behaviour expressed by the test name: device received handler throwing does not break cache population.</summary>
+        [Test]
+        public void DeviceReceivedHandlerThrowingDoesNotBreakCachePopulation()
+        {
+            var client = new MTConnectHttpClient(Hostname, Port);
+
+            var internalErrorCount = 0;
+            client.InternalError += (_, _) => Interlocked.Increment(ref internalErrorCount);
+
+            // First subscriber throws on every fan-out; second subscriber records every
+            // device it sees. With exception-isolation in place, the cache must still
+            // fully populate, the second subscriber must still see every device, and the
+            // throw must surface through InternalError.
+            client.DeviceReceived += (_, _) => throw new InvalidOperationException("intentional test fault");
+
+            var receivedDevices = new List<IDevice>();
+            var receivedLock = new object();
+            client.DeviceReceived += (_, device) =>
+            {
+                lock (receivedLock) { receivedDevices.Add(device); }
+            };
+
+            using var probeSignal = new ManualResetEventSlim(false);
+            client.ProbeReceived += (_, _) => probeSignal.Set();
+
+            try
+            {
+                client.Start();
+
+                Assert.That(probeSignal.Wait(ProbeWaitTimeoutMs), Is.True, "ProbeReceived did not fire within the timeout");
+
+                List<IDevice> snapshot;
+                lock (receivedLock) { snapshot = new List<IDevice>(receivedDevices); }
+
+                Assert.That(snapshot.Count, Is.EqualTo(ExpectedDocumentEntryCount), "Throwing handler suppressed downstream subscribers");
+                Assert.That(client.Devices.Count, Is.EqualTo(ExpectedDocumentEntryCount), "Throwing handler corrupted the cache fill");
+                Assert.That(Volatile.Read(ref internalErrorCount), Is.GreaterThanOrEqualTo(ExpectedDocumentEntryCount), "Throwing handler did not surface through InternalError");
+            }
+            finally
+            {
+                client.Stop();
+            }
+        }
     }
 }