fix(common): tighten DeviceValidationLevel setter and preserve cycle-2 hardening

build/MTConnect.NET-DocsGen/Renderers.cs

@@ -383,12 +383,36 @@ public static string Render(IReadOnlyList<ConfigClassInfo> classes)
             sb.AppendLine("| --- | --- | --- | --- |");
             foreach (var p in c.Properties)
             {
-                sb.AppendLine($"| `{p.SerialisedKey}` | `{p.Name}` | `{Escape(p.Type)}` | {Escape(p.Summary)} |");
+                sb.AppendLine($"| `{p.SerialisedKey}` | `{p.Name}` | {RenderType(p.Type)} | {Escape(p.Summary)} |");
             }
             sb.AppendLine();
         }
         return sb.ToString();
     }
 
+    /// <summary>
+    /// Maps a config property's type name to its authored docfx API page,
+    /// keyed on exact type-name equality (no prefix/substring matching).
+    /// </summary>
+    private static readonly IReadOnlyDictionary<string, string> TypeApiLinks = new Dictionary<string, string>
+    {
+        ["DeviceValidationLevel"] = "/api/MTConnect.Agents.DeviceValidationLevel",
+        ["InputValidationLevel"] = "/api/MTConnect.Agents.InputValidationLevel",
+    };
+
+    /// <summary>
+    /// Renders the Type column for a config property: a markdown link into
+    /// the docfx API namespace for types with an authored API page (see
+    /// <see cref="TypeApiLinks"/>), or a plain backtick-fenced type name
+    /// otherwise. The type name is escaped before either shape is emitted.
+    /// </summary>
+    private static string RenderType(string type)
+    {
+        var escaped = Escape(type);
+        return TypeApiLinks.TryGetValue(type, out var href)
+            ? $"[`{escaped}`]({href})"
+            : $"`{escaped}`";
+    }
+
     private static string Escape(string s) => s.Replace("|", "\\|").Replace("\n", " ").Replace("\r", " ");
 }

docs/cli/agent.md

@@ -106,7 +106,7 @@ Backed by `AgentApplicationConfiguration` and the inherited `AgentConfiguration`
 | `ignoreObservationCase` | bool | `false` | Case-insensitive comparison of incoming observation values to the data item's value-space (CONDITION severities, enum members, etc.). |
 | `enableValidation` | bool | `false` | Emit per-observation validation diagnostics on the `agent-validation` logger. |
 | `inputValidationLevel` | enum: `Ignore` (`0`), `Warning` (`1`), `Remove` (`2`), `Strict` (`3`) | `Warning` | What the agent does when an observation or asset arrives that fails per-DataItem validation. `Ignore` accepts everything; `Warning` accepts and logs; `Remove` rejects but does not log; `Strict` rejects and logs. Governs `InvalidObservationAdded` and `InvalidAssetAdded`. |
-| `deviceValidationLevel` | enum: `Ignore` (`0`), `Warning` (`1`), `Remove` (`2`), `Strict` (`3`) | `Warning` | What the agent does when device-shape validation fails on a Component, Composition, or DataItem while a Device is being added or normalised. Independent from `inputValidationLevel` — a common integrator profile is `inputValidationLevel: Strict` alongside `deviceValidationLevel: Warning` (reject bad observations, tolerate minor device-model drift). Governs `InvalidComponentAdded`, `InvalidCompositionAdded`, `InvalidDataItemAdded`, and `InvalidDeviceAdded`. |
+| `deviceValidationLevel` | enum: `Ignore` (`0`), `Warning` (`1`), `Remove` (`2`), `Strict` (`3`) | mirrors `inputValidationLevel` when omitted (`Warning` when both are omitted) | What the agent does when device-shape validation fails on a Component, Composition, or DataItem while a Device is being added or normalised. Independent from `inputValidationLevel` — a common integrator profile is `inputValidationLevel: Strict` alongside `deviceValidationLevel: Warning` (reject bad observations, tolerate minor device-model drift). Governs `InvalidComponentAdded`, `InvalidCompositionAdded`, `InvalidDataItemAdded`, and `InvalidDeviceAdded`. When the key is omitted, the effective value mirrors `inputValidationLevel` — see `AgentConfiguration.Normalize`. |
 | `allowEmptyResultForEnumEvents` | bool | `false` | When `true`, preserves an empty Result verbatim on VALUE-representation EVENT DataItems whose Type has a controlled vocabulary (`EXECUTION`, `CONTROLLER_MODE`, `AVAILABILITY`, and every other Event whose value is defined by an `MTConnect.Observations.Events.<Type>` enum). Default coerces the empty Result to `UNAVAILABLE`. Free-form String and Numeric-typed Events are unaffected — free-form String preserves the empty Result unconditionally; Numeric-typed always coerces. |
 | `enableAgentDevice` | bool | `true` | Whether the agent emits its own meta-device (`Agent`) on `/probe`, exposing availability and the `mtconnect:ChangeToken` data item. |
 | `enableMetrics` | bool | `true` | Emit per-minute observation-rate and asset-update-rate metrics on the `agent-metrics` logger. |

docs/concepts/agent-validation-events.md

@@ -144,7 +144,7 @@ The handler runs first; what the agent does next depends on the applicable knob
 - **`Ignore`** — the event does not fire, and the input is kept. Useful only for debugging.
 - **`Warning`** — the event fires; the input is kept.
 - **`Remove`** — the event fires; the offending node is pruned from its parent (e.g. `device.RemoveDataItem(id)`), or the input is dropped for the observation / asset case.
-- **`Strict`** — the event fires; the entire Device is rejected (the `AddDevice` call returns `false` and no part of the tree is added), or the observation / asset input is rejected.
+- **`Strict`** — the event fires; the entire Device is rejected (the `AddDevice` call returns `null` and no part of the tree is added), or the observation / asset input call returns `false`.
 
 ## Contributor POV
 
@@ -196,10 +196,10 @@ The event family is designed to grow. When a new element class becomes validatab
        var fired = false;
        agent.InvalidDeviceModelAdded += (_, _, _) => fired = true;
 
-       var ok = agent.AddDevice(BrokenDeviceModelFixture());
+       var added = agent.AddDevice(BrokenDeviceModelFixture());
 
+       Assert.That(added, Is.Null);
        Assert.That(fired, Is.True);
-       Assert.That(ok,    Is.False);
        Assert.That(agent.GetDevices(), Is.Empty);
    }
    ```

docs/reference/configuration.md

@@ -84,13 +84,13 @@ Configuration for an MTConnect Agent
 | `changeToken` | `ChangeToken` | `string` | An opaque token regenerated each time the configuration is saved, allowing consumers to detect that the configuration has changed. |
 | `convertUnits` | `ConvertUnits` | `bool` | Gets or Sets the default for Converting Units when adding Observations |
 | `defaultVersion` | `DefaultVersionValue` | `string` | The string form of <see cref="DefaultVersion"/> used for serialization; assigning a parseable version string updates <see cref="DefaultVersion"/>. |
-| `deviceValidationLevel` | `DeviceValidationLevel` | `DeviceValidationLevel` | Gets or Sets the default Device (MTConnectDevices) validation level. 0 = Ignore, 1 = Warning, 2 = Remove, 3 = Strict |
+| `deviceValidationLevel` | `DeviceValidationLevel` | `DeviceValidationLevel` | Gets or Sets the default Device (MTConnectDevices) validation level. 0 = Ignore, 1 = Warning, 2 = Remove, 3 = Strict. |
 | `enableAgentDevice` | `EnableAgentDevice` | `bool` | Gets or Sets whether the Agent Device is output |
 | `enableMetrics` | `EnableMetrics` | `bool` | Gets or Sets whether Metrics are captured (ex. ObserationUpdateRate, AssetUpdateRate) |
 | `enableValidation` | `EnableValidation` | `bool` | Gets or Sets whether validation information is output |
 | `ignoreObservationCase` | `IgnoreObservationCase` | `bool` | Gets or Sets the default for Ignoring the case of Observation values |
 | `ignoreTimestamps` | `IgnoreTimestamps` | `bool` | Overwrite timestamps with the agent time. This will correct clock drift but will not give as accurate relative time since it will not take into consideration network latencies. This can be overridden on a per adapter basis. |
-| `inputValidationLevel` | `InputValidationLevel` | `InputValidationLevel` | Gets or Sets the default Input (Observation or Asset) validation level. 0 = Ignore, 1 = Warning, 2 = Remove, 3 = Strict |
+| `inputValidationLevel` | `InputValidationLevel` | `InputValidationLevel` | Gets or Sets the default Input (Observation or Asset) validation level. 0 = Ignore, 1 = Warning, 2 = Remove, 3 = Strict. |
 | `observationBufferSize` | `ObservationBufferSize` | `uint` | The maximum number of Observations the agent can hold in its buffer |
 | `timezoneOutput` | `TimeZoneOutput` | `string` | Sets the TimeZone to use when timestamps are output from the Agent |
 
@@ -197,7 +197,7 @@ Configuration for an MTConnect Agent
 | `changeToken` | `ChangeToken` | `string` | An opaque token that changes whenever the underlying configuration source is reloaded, allowing consumers to detect that the configuration has been replaced. |
 | `convertUnits` | `ConvertUnits` | `bool` | Gets the default for Converting Units when adding Observations |
 | `defaultVersion` | `DefaultVersion` | `Version` | Gets the default MTConnect version to output response documents for. |
-| `deviceValidationLevel` | `DeviceValidationLevel` | `DeviceValidationLevel` | Gets or Sets the default Device (MTConnectDevices) validation level. 0 = Ignore, 1 = Warning, 2 = Remove, 3 = Strict |
+| `deviceValidationLevel` | `DeviceValidationLevel` | `DeviceValidationLevel` | Gets the default Device (MTConnectDevices) validation level. 0 = Ignore, 1 = Warning, 2 = Remove, 3 = Strict |
 | `enableAgentDevice` | `EnableAgentDevice` | `bool` | Gets or Sets whether the Agent Device is output |
 | `enableMetrics` | `EnableMetrics` | `bool` | Gets whether Metrics are captured (ex. ObserationUpdateRate, AssetUpdateRate) |
 | `enableValidation` | `EnableValidation` | `bool` | Gets or Sets whether validation information is output |

libraries/MTConnect.NET-Common/Agents/DeviceValidationLevel.cs

@@ -29,4 +29,4 @@ public enum DeviceValidationLevel
         /// </summary>
         Strict
     }
-}
+}

libraries/MTConnect.NET-Common/Agents/MTConnectAgent.cs

@@ -2342,17 +2342,15 @@ private static bool IsEmptyResult(IObservationInput input)
         /// Rewrites the observation's Result value to <see cref="Observation.Unavailable"/> and flags the input as unavailable.
         /// </summary>
         /// <remarks>
-        /// Removes any prior Result entry (so the Values collection does not carry a duplicate ValueKey),
-        /// adds the UNAVAILABLE sentinel, and sets <see cref="IObservationInput.IsUnavailable"/> so downstream
-        /// consumers that branch on the flag observe the coerced state. Spec authority: MTConnect Part 2
-        /// Devices Information Model - Observation Information Model - Representation - Observation Values.
+        /// Delegates the Values-collection housekeeping to
+        /// <see cref="ObservationInput.AddValue(string, object)"/>, which already
+        /// replaces any prior entry with the same ValueKey — the earlier hand-written
+        /// pre-filter (Where + ToList + assign) was redundant work. Spec authority:
+        /// MTConnect Part 2 Devices Information Model - Observation Information Model -
+        /// Representation - Observation Values.
         /// </remarks>
         private static void CoerceEmptyResultToUnavailable(IObservationInput input)
         {
-            var preserved = (input.Values ?? Enumerable.Empty<ObservationValue>())
-                .Where(v => v.Key != ValueKeys.Result)
-                .ToList();
-            input.Values = preserved;
             input.AddValue(ValueKeys.Result, Observation.Unavailable);
             input.IsUnavailable = true;
         }