feat(abcip): final review I1 — node-level Drivers:AbCip:DefaultTransport

The old AdminUI cannot author the per-driver transport key (#576), so the
'pin before upgrading' recipe had no working path. A node-level appsetting
(env Drivers__AbCip__DefaultTransport) now supplies the default for AbCip
drivers with no key: explicit key > node default > compiled Native. Bound
and validated unconditionally (bad value fails host start); the driver
factory and the Test Connect probe both read it so they agree. AbCip.md
upgrade recipe rewritten around the key; Configuration.md documents it.
Also documents first-wins for AllowPacking/probe and host-alias throttles
(final review M6) and moves the status-bit note out of AbCip.md (M5).

Claude-Session: https://claude.ai/code/session_01Ef2ozxS7QPanGT8uoATbTe

src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.AbCip.Contracts/AbCipDriverOptions.cs

@@ -34,7 +34,8 @@ public sealed class AbCipDriverOptions
 
     /// <summary>
     ///     Which transport stack the driver, its Test Connect probe and the CLI use. <c>null</c> (the
-    ///     <c>transport</c> key absent) means "use the default", which is <see cref="AbCipTransport.Native"/>;
+    ///     <c>transport</c> key absent) means "use the default": the node-level
+    ///     <c>Drivers:AbCip:DefaultTransport</c> appsetting, which itself defaults to <see cref="AbCipTransport.Native"/>;
     ///     an explicit value always wins. The effective transport is resolved in one place,
     ///     <c>AbCipTransportResolver</c>. Set <see cref="AbCipTransport.Libplctag"/> to fall back.
     ///     <para>Changing this takes effect when the driver instance is RECREATED, not on

src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.AbCip/AbCipDriver.cs

@@ -141,19 +141,23 @@ public sealed class AbCipDriver : IDriver, IReadable, IWritable, ITagDiscovery,
     /// <param name="enumeratorFactory">Optional factory for enumerating tags; when null the resolved transport's is used.</param>
     /// <param name="templateReaderFactory">Optional factory for reading UDT templates; when null the resolved transport's is used.</param>
     /// <param name="logger">Optional logger; uses null logger if not provided.</param>
+    /// <param name="defaultTransport">The node-level default for an absent <c>transport</c> key
+    ///     (<c>Drivers:AbCip:DefaultTransport</c>); null means the compiled <see cref="AbCipTransportResolver.Default"/>.</param>
     public AbCipDriver(AbCipDriverOptions options, string driverInstanceId,
         IAbCipTagFactory? tagFactory = null,
         IAbCipTagEnumeratorFactory? enumeratorFactory = null,
         IAbCipTemplateReaderFactory? templateReaderFactory = null,
-        ILogger<AbCipDriver>? logger = null)
+        ILogger<AbCipDriver>? logger = null,
+        AbCipTransport? defaultTransport = null)
     {
         ArgumentNullException.ThrowIfNull(options);
         _options = options;
         _driverInstanceId = driverInstanceId;
         // Chosen once here and held across ReinitializeAsync (Shutdown+Initialize): a changed
         // Transport in a reinit config is inert; a deploy recreates the instance instead.
-        _transport = AbCipTransportResolver.Resolve(options);
-        _transportDescription = AbCipTransportResolver.Describe(options.Transport);
+        var nodeDefault = defaultTransport ?? AbCipTransportResolver.Default;
+        _transport = AbCipTransportResolver.Resolve(options, nodeDefault);
+        _transportDescription = AbCipTransportResolver.Describe(options.Transport, nodeDefault);
         var defaults = AbCipTransportFactories.For(_transport);
         _tagFactory = tagFactory ?? defaults.Tags;
         _enumeratorFactory = enumeratorFactory ?? defaults.Enumerators;
@@ -182,7 +186,7 @@ public sealed class AbCipDriver : IDriver, IReadable, IWritable, ITagDiscovery,
 
     /// <summary>The effective transport resolved at construction (see <see cref="AbCipTransportResolver"/>).
     /// Describes the OPTION only: injected factories (tests) are used regardless.</summary>
-    internal AbCipTransport EffectiveTransport => _transport;
+    public AbCipTransport EffectiveTransport => _transport;
 
     // The transport chosen at construction (see the ctor); logged at every init so an operator can tell
     // from the node log which stack serves this instance.

src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.AbCip/AbCipDriverFactoryExtensions.cs

@@ -24,10 +24,14 @@ public static class AbCipDriverFactoryExtensions
     /// </summary>
     /// <param name="registry">The driver factory registry to register with.</param>
     /// <param name="loggerFactory">Optional logger factory for driver instances.</param>
-    public static void Register(DriverFactoryRegistry registry, ILoggerFactory? loggerFactory = null)
+    /// <param name="defaultTransport">The node-level transport for drivers whose config has no
+    ///     <c>transport</c> key (<c>Drivers:AbCip:DefaultTransport</c>, final review I1). An explicit
+    ///     per-driver key still wins.</param>
+    public static void Register(DriverFactoryRegistry registry, ILoggerFactory? loggerFactory = null,
+        AbCipTransport defaultTransport = AbCipTransportResolver.Default)
     {
         ArgumentNullException.ThrowIfNull(registry);
-        registry.Register(DriverTypeName, (id, json) => CreateInstance(id, json, loggerFactory));
+        registry.Register(DriverTypeName, (id, json) => CreateInstance(id, json, loggerFactory, defaultTransport));
     }
 
     /// <summary>
@@ -43,18 +47,21 @@ public static class AbCipDriverFactoryExtensions
     /// <param name="driverInstanceId">The unique identifier for this driver instance.</param>
     /// <param name="driverConfigJson">The driver configuration as a JSON string.</param>
     /// <param name="loggerFactory">Optional logger factory for the driver instance.</param>
+    /// <param name="defaultTransport">The node-level default for an absent <c>transport</c> key.</param>
     /// <returns>A configured <see cref="AbCipDriver"/> instance.</returns>
     internal static AbCipDriver CreateInstance(
-        string driverInstanceId, string driverConfigJson, ILoggerFactory? loggerFactory)
+        string driverInstanceId, string driverConfigJson, ILoggerFactory? loggerFactory,
+        AbCipTransport defaultTransport = AbCipTransportResolver.Default)
     {
         ArgumentException.ThrowIfNullOrWhiteSpace(driverInstanceId);
         var options = ParseOptions(driverInstanceId, driverConfigJson);
-        return new AbCipDriver(options, driverInstanceId, logger: loggerFactory?.CreateLogger<AbCipDriver>());
+        return new AbCipDriver(options, driverInstanceId, logger: loggerFactory?.CreateLogger<AbCipDriver>(),
+            defaultTransport: defaultTransport);
     }
 
     /// <summary>
     ///     Deserialise an AB CIP driver-config JSON document into <see cref="AbCipDriverOptions"/>.
-    ///     Shared by <see cref="CreateInstance(string, string, ILoggerFactory?)"/> (first construction) and
+    ///     Shared by <see cref="CreateInstance(string, string, ILoggerFactory?, AbCipTransport)"/> (first construction) and
     ///     <see cref="AbCipDriver.InitializeAsync"/> / <see cref="AbCipDriver.ReinitializeAsync"/>
     ///     so a reinitialize with a changed config JSON (new device, new tag, changed timeout)
     ///     actually takes effect rather than being silently discarded.
@@ -155,7 +162,7 @@ public static class AbCipDriverFactoryExtensions
     internal sealed class AbCipDriverConfigDto
     {
         /// <summary>
-        /// Gets or sets the transport (<c>Libplctag</c> or <c>Native</c>, case-insensitive); absent means Libplctag.
+        /// Gets or sets the transport (<c>Libplctag</c> or <c>Native</c>, case-insensitive); absent means the node default.
         /// </summary>
         public string? Transport { get; init; }
 

src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.AbCip/AbCipDriverProbe.cs

@@ -34,11 +34,22 @@ public sealed class AbCipDriverProbe : IDriverProbe
     };
 
     private readonly IAbCipTagFactory? _tagFactory;
+    private readonly AbCipTransport _defaultTransport;
 
     /// <summary>Initializes a new instance of the <see cref="AbCipDriverProbe"/> class.</summary>
     /// <param name="tagFactory">Factory for the probe's tag runtime; when null the config's
     ///     <c>Transport</c> selects the native or libplctag-backed one.</param>
-    public AbCipDriverProbe(IAbCipTagFactory? tagFactory = null) => _tagFactory = tagFactory;
+    /// <param name="defaultTransport">The node-level default for a config with no <c>transport</c> key — the
+    ///     SAME value the node's driver factory uses, so Test Connect probes the stack the driver would run.</param>
+    public AbCipDriverProbe(IAbCipTagFactory? tagFactory = null,
+        AbCipTransport defaultTransport = AbCipTransportResolver.Default)
+    {
+        _tagFactory = tagFactory;
+        _defaultTransport = defaultTransport;
+    }
+
+    /// <summary>The node-level default this probe resolves an absent key to (wiring tests).</summary>
+    public AbCipTransport DefaultTransport => _defaultTransport;
 
     /// <inheritdoc />
     public string DriverType => "AbCip";
@@ -123,7 +134,7 @@ public sealed class AbCipDriverProbe : IDriverProbe
             ConnectionSize: firstDevice?.ConnectionSize ?? profile.DefaultConnectionSize,
             UseConnectedMessaging: profile.SupportsConnectedMessaging);
 
-        var rt = (_tagFactory ?? AbCipTransportFactories.For(AbCipTransportResolver.Resolve(opts)).Tags).Create(p);
+        var rt = (_tagFactory ?? AbCipTransportFactories.For(AbCipTransportResolver.Resolve(opts, _defaultTransport)).Tags).Create(p);
         try
         {
             await rt.InitializeAsync(cts.Token);

src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.AbCip/AbCipTransportResolver.cs

@@ -5,32 +5,61 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.AbCip;
 ///     <see cref="AbCipDriverOptions.Transport"/>. The driver constructor, the Test Connect probe and the
 ///     CLI (through the driver) all resolve through here, so they cannot disagree about what an absent
 ///     <c>transport</c> key means.
+///     <para>Precedence (final review I1): an explicit per-driver <c>transport</c> key wins; otherwise the
+///     node-level default (<c>Drivers:AbCip:DefaultTransport</c>, read in the Host composition root and passed
+///     in as <c>nodeDefault</c>); otherwise the compiled <see cref="Default"/>.</para>
 /// </summary>
 public static class AbCipTransportResolver
 {
-    /// <summary>The transport an absent / null <c>transport</c> key selects.</summary>
+    /// <summary>The compiled default: the transport an absent key selects when no node default is configured.</summary>
     public const AbCipTransport Default = AbCipTransport.Native;
 
-    /// <summary>Returns the effective transport: an explicit value always wins; null means <see cref="Default"/>.</summary>
+    /// <summary>Returns the effective transport: an explicit value always wins; null means <paramref name="nodeDefault"/>.</summary>
     /// <param name="configured">The configured transport, or null for "use the default".</param>
+    /// <param name="nodeDefault">The node-level default for drivers with no key (the compiled <see cref="Default"/> unless pinned).</param>
     /// <returns>The transport the driver runs on.</returns>
-    public static AbCipTransport Resolve(AbCipTransport? configured) => configured ?? Default;
+    public static AbCipTransport Resolve(AbCipTransport? configured, AbCipTransport nodeDefault = Default) =>
+        configured ?? nodeDefault;
 
     /// <summary>Returns the effective transport for <paramref name="options"/>.</summary>
     /// <param name="options">The driver options.</param>
+    /// <param name="nodeDefault">The node-level default for drivers with no key.</param>
     /// <returns>The transport the driver runs on.</returns>
-    public static AbCipTransport Resolve(AbCipDriverOptions options)
+    public static AbCipTransport Resolve(AbCipDriverOptions options, AbCipTransport nodeDefault = Default)
     {
         ArgumentNullException.ThrowIfNull(options);
-        return Resolve(options.Transport);
+        return Resolve(options.Transport, nodeDefault);
+    }
+
+    /// <summary>
+    ///     Parses a transport name the way the driver-config <c>transport</c> key and the node-level default
+    ///     are parsed: a defined enum NAME, case-insensitive. Numeric strings ("0", "7") and the flags form
+    ///     ("Native,Libplctag") are rejected — <c>Enum.TryParse</c> alone accepts both.
+    /// </summary>
+    /// <param name="raw">The raw value.</param>
+    /// <param name="transport">The parsed transport.</param>
+    /// <returns>True when <paramref name="raw"/> names a transport.</returns>
+    public static bool TryParse(string? raw, out AbCipTransport transport)
+    {
+        transport = Default;
+        if (string.IsNullOrWhiteSpace(raw)) return false;
+        // Exact name match only: Enum.TryParse would also accept "1" and the flags form "Native,Libplctag".
+        var name = Enum.GetNames<AbCipTransport>()
+            .FirstOrDefault(n => string.Equals(n, raw.Trim(), StringComparison.OrdinalIgnoreCase));
+        return name is not null && Enum.TryParse(name, out transport);
     }
 
     /// <summary>
     ///     Operator-facing description of the configured-vs-effective transport for the init log line:
-    ///     <c>Native (default)</c> when the key was absent, the bare transport name when it was explicit.
+    ///     <c>Native (default)</c> when the key was absent and the compiled default applies,
+    ///     <c>Libplctag (node default)</c> when the key was absent and the node pinned a different default,
+    ///     <c>Native (configured)</c> when the key was explicit.
     /// </summary>
     /// <param name="configured">The configured transport, or null.</param>
+    /// <param name="nodeDefault">The node-level default.</param>
     /// <returns>A short description.</returns>
-    public static string Describe(AbCipTransport? configured) =>
-        configured is null ? $"{Resolve(configured)} (default)" : $"{configured} (configured)";
+    public static string Describe(AbCipTransport? configured, AbCipTransport nodeDefault = Default) =>
+        configured is not null ? $"{configured} (configured)"
+        : nodeDefault == Default ? $"{nodeDefault} (default)"
+        : $"{nodeDefault} (node default)";
 }