fix(ab): destroy the native libplctag tag a failed initialisation leaves behind (T21 press pass 1 crash)

The T21 press pass 1 test host died at exit with "A callback was made on a garbage
collected delegate of type ...plctag+callback_func_ex::Invoke". The cause is in
libplctag.NET 1.5.2. When a tag's create fails, for example with NotFound,
InitializeAsync throws with the callback still registered. Dispose() destroys a tag
only if it is initialised, so the native tag outlives its wrapper. The GC then frees
the delegate, and libplctag's atexit plc_tag_shutdown raises DESTROYED into it.
Reproduced against ab_server: the production LibplctagTagRuntime with a NotFound tag
exits 134 with that exact message, and exits 0 with this fix.

A timed-out create unregisters its callback but never destroys the handle either,
so that native tag keeps reconnecting for the life of the process.

The fix adds LibplctagOrphanRelease (AbCip and AbLegacy). After a failed
initialise/read/write that leaves the tag uninitialised, it reads the handle through
the pinned wrapper's private fields, unregisters the callback and destroys the tag.
If those fields cannot be read, it roots the tag for the life of the process
instead. It is applied in both tag runtimes, the symbol-listing reader and the
template reader. GetStatus keeps the status the tag held before it was destroyed.

Pins: offline refused-connection tests in AbCip.Tests and AbLegacy.Tests, a live
NotFound test on ab_server, and a reflection-shape pin. All go red with the release
disabled. The differential harness also asserts that no orphan had to be rooted.

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

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

@@ -0,0 +1,117 @@
+using System.Collections.Concurrent;
+using System.Reflection;
+using libplctag;
+using libplctag.NativeImport;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.AbCip;
+
+/// <summary>
+///     Releases the native tag a FAILED libplctag initialisation leaves behind (T21 press pass 1 crash).
+/// </summary>
+/// <remarks>
+///     <para>libplctag.NET 1.5.2's <c>NativeTagWrapper.InitializeAsync</c> calls <c>plc_tag_create_ex</c>, which returns a
+///     native handle with the wrapper's <c>callback_func_ex</c> delegate registered, and only then waits for the
+///     <c>Created</c> event. When that event carries an error (a tag the controller does not have, a refused path, ...)
+///     it throws WITHOUT setting <c>_isInitialized</c>, and <c>Dispose()</c> unregisters and destroys only
+///     <c>if (_isInitialized)</c>. So the native tag outlives its wrapper with the callback still registered; once the
+///     wrapper is collected the delegate's thunk is freed, and the next event libplctag raises on that tag — at the
+///     latest the <c>DESTROYED</c> event from <c>plc_tag_shutdown</c>, which the native library runs from
+///     <c>atexit</c> — kills the process with "A callback was made on a garbage collected delegate of type
+///     'libplctag.NativeImport!libplctag.NativeImport.plctag+callback_func_ex::Invoke'". A timed-out initialisation
+///     unregisters the callback but never destroys the handle either, so that native tag keeps reconnecting in the
+///     background for the life of the process.</para>
+///     <para>The wrapper exposes no handle, so it is read by reflection from the two private fields of the pinned
+///     1.5.2 wrapper (<c>Tag._tag</c>, <c>NativeTagWrapper.nativeTagHandle</c>). If a future wrapper renames them the
+///     release cannot run; the tag is then rooted for the life of the process instead, which keeps its delegate
+///     alive (no crash, a bounded leak) — and <c>LibplctagOrphanReleaseTests</c> fails, so the bump is noticed.</para>
+/// </remarks>
+internal static class LibplctagOrphanRelease
+{
+    private const BindingFlags Private = BindingFlags.NonPublic | BindingFlags.Instance;
+
+    private static readonly FieldInfo? WrapperField = typeof(Tag).GetField("_tag", Private);
+    private static readonly FieldInfo? HandleField = WrapperField?.FieldType.GetField("nativeTagHandle", Private);
+
+    /// <summary>Tags whose handle could not be read: kept reachable so their callback delegate is never collected.</summary>
+    private static readonly ConcurrentBag<Tag> Rooted = [];
+
+    private static int _released;
+
+    /// <summary>True when the pinned wrapper's private fields were found, so a failed tag can be destroyed.</summary>
+    internal static bool CanReadHandles => HandleField is not null;
+
+    /// <summary>Orphaned native tags destroyed so far (process-wide; diagnostics and tests).</summary>
+    internal static int Released => Volatile.Read(ref _released);
+
+    /// <summary>Orphaned tags rooted for the process lifetime because their handle could not be read.</summary>
+    internal static int RootedCount => Rooted.Count;
+
+    /// <summary>The native handle the wrapper holds (0 when none was ever created, or unreadable).</summary>
+    internal static int HandleOf(Tag tag) =>
+        HandleField is not null && WrapperField!.GetValue(tag) is { } wrapper ? (int)HandleField.GetValue(wrapper)! : 0;
+
+    /// <summary>
+    ///     Runs a libplctag operation that may initialise <paramref name="tag"/> (InitializeAsync, or a first
+    ///     Read/Write, which initialise on demand). If it fails and leaves the tag uninitialised, the native tag it
+    ///     created is unregistered and destroyed before the failure propagates.
+    /// </summary>
+    internal static async Task RunAsync(Tag tag, Func<Task> op)
+    {
+        try
+        {
+            await op().ConfigureAwait(false);
+        }
+        catch
+        {
+            ReleaseIfOrphaned(tag);
+            throw;
+        }
+    }
+
+    /// <inheritdoc cref="RunAsync(Tag, Func{Task})"/>
+    internal static async Task<T> RunAsync<T>(Tag tag, Func<Task<T>> op)
+    {
+        try
+        {
+            return await op().ConfigureAwait(false);
+        }
+        catch
+        {
+            ReleaseIfOrphaned(tag);
+            throw;
+        }
+    }
+
+    /// <summary>
+    ///     Destroys the native tag behind an UNINITIALISED wrapper, unregistering its callback first. No-op for an
+    ///     initialised tag (its own <c>Dispose</c> handles it) or one that never got a handle. Never throws.
+    /// </summary>
+    /// <returns>The status the native tag held just before it was destroyed (what <c>GetStatus()</c> would have
+    ///     reported), or null when nothing was destroyed.</returns>
+    internal static Status? ReleaseIfOrphaned(Tag tag)
+    {
+        try
+        {
+            if (tag.IsInitialized) return null;
+            if (!CanReadHandles)
+            {
+                Rooted.Add(tag);
+                return null;
+            }
+            var handle = HandleOf(tag);
+            if (handle <= 0) return null;   // plc_tag_create_ex refused synchronously: nothing native exists
+            var status = (Status)plctag.plc_tag_status(handle);
+            plctag.plc_tag_unregister_callback(handle);
+            plctag.plc_tag_destroy(handle);
+            Interlocked.Increment(ref _released);
+            return status;
+        }
+        catch (Exception)
+        {
+            // A release must never mask the initialisation failure it follows. Root the tag so that, whatever
+            // state the native side is in, its callback delegate stays alive.
+            Rooted.Add(tag);
+            return null;
+        }
+    }
+}

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

@@ -12,12 +12,13 @@ internal static class LibplctagListingReader
         AbCipTagCreateParams deviceParams, string listingName, CancellationToken cancellationToken)
     {
         using var tag = BuildSymbolListTag(deviceParams, listingName);
-        return await LibplctagStatusTranslation.Wrap(async () =>
+        // A failed initialisation would otherwise leave the native tag (and its callback) behind: see LibplctagOrphanRelease.
+        return await LibplctagOrphanRelease.RunAsync(tag, () => LibplctagStatusTranslation.Wrap(async () =>
         {
             await tag.InitializeAsync(cancellationToken).ConfigureAwait(false);
             await tag.ReadAsync(cancellationToken).ConfigureAwait(false);
             return tag.GetBuffer();
-        }).ConfigureAwait(false);
+        })).ConfigureAwait(false);
     }
 
     /// <summary>

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

@@ -14,6 +14,12 @@ internal sealed class LibplctagTagRuntime : IAbCipTagRuntime
 {
     private readonly Tag _tag;
 
+    /// <summary>
+    ///     The status the native tag held when a failed initialisation destroyed it (see
+    ///     <see cref="LibplctagOrphanRelease"/>); null while the wrapper's own handle is authoritative.
+    /// </summary>
+    private Status? _releasedStatus;
+
     /// <summary>Initializes a new instance of the LibplctagTagRuntime class.</summary>
     /// <param name="p">The tag creation parameters.</param>
     public LibplctagTagRuntime(AbCipTagCreateParams p)
@@ -42,18 +48,42 @@ internal sealed class LibplctagTagRuntime : IAbCipTagRuntime
 
     /// <inheritdoc />
     public Task InitializeAsync(CancellationToken cancellationToken) =>
-        LibplctagStatusTranslation.Wrap(() => _tag.InitializeAsync(cancellationToken));
+        RunReleasingOrphanAsync(() => _tag.InitializeAsync(cancellationToken));
 
     /// <inheritdoc />
+    /// <remarks>libplctag initialises an uninitialised tag on its first read, so this path can orphan one too.</remarks>
     public Task ReadAsync(CancellationToken cancellationToken) =>
-        LibplctagStatusTranslation.Wrap(() => _tag.ReadAsync(cancellationToken));
+        RunReleasingOrphanAsync(() => _tag.ReadAsync(cancellationToken));
 
     /// <inheritdoc />
     public Task WriteAsync(CancellationToken cancellationToken) =>
-        LibplctagStatusTranslation.Wrap(() => _tag.WriteAsync(cancellationToken));
+        RunReleasingOrphanAsync(() => _tag.WriteAsync(cancellationToken));
+
+    /// <summary>
+    ///     Runs a libplctag operation; when it fails and leaves the tag uninitialised, destroys the native tag it
+    ///     created before the failure propagates, so its callback can never fire into a collected delegate (T21 press
+    ///     pass 1 crash). The status that tag held is kept for <see cref="GetStatus"/>.
+    /// </summary>
+    private async Task RunReleasingOrphanAsync(Func<Task> op)
+    {
+        try
+        {
+            await LibplctagStatusTranslation.Wrap(op).ConfigureAwait(false);
+            _releasedStatus = null;
+        }
+        catch
+        {
+            if (LibplctagOrphanRelease.ReleaseIfOrphaned(_tag) is { } status) _releasedStatus = status;
+            throw;
+        }
+    }
+
+    /// <summary>The native libplctag handle this runtime's tag holds or last held (0 if none was created). Tests only.</summary>
+    internal int NativeHandle => LibplctagOrphanRelease.HandleOf(_tag);
 
     /// <inheritdoc />
-    public int GetStatus() => (int)LibplctagStatusTranslation.ToAbStatus(_tag.GetStatus());
+    public int GetStatus() =>
+        (int)LibplctagStatusTranslation.ToAbStatus(_releasedStatus ?? _tag.GetStatus());
 
     /// <inheritdoc />
     public int GetSize() => LibplctagStatusTranslation.WrapSync(() => _tag.GetSize());

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

@@ -21,12 +21,13 @@ internal sealed class LibplctagTemplateReader : IAbCipTemplateReader
         _tag?.Dispose();
         _tag = BuildTemplateTag(deviceParams, templateInstanceId);
         var tag = _tag;
-        return await LibplctagStatusTranslation.Wrap(async () =>
+        // A failed initialisation would otherwise leave the native tag (and its callback) behind: see LibplctagOrphanRelease.
+        return await LibplctagOrphanRelease.RunAsync(tag, () => LibplctagStatusTranslation.Wrap(async () =>
         {
             await tag.InitializeAsync(cancellationToken).ConfigureAwait(false);
             await tag.ReadAsync(cancellationToken).ConfigureAwait(false);
             return tag.GetBuffer();
-        }).ConfigureAwait(false);
+        })).ConfigureAwait(false);
     }
 
     /// <summary>Builds the (uninitialized) libplctag tag for the <c>@udt/{id}</c> pseudo.</summary>

src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/LibplctagLegacyTagRuntime.cs

@@ -13,6 +13,12 @@ internal sealed class LibplctagLegacyTagRuntime : IAbLegacyTagRuntime
 {
     private readonly Tag _tag;
 
+    /// <summary>
+    ///     The status the native tag held when a failed initialisation destroyed it (see
+    ///     <see cref="LibplctagOrphanRelease"/>); null while the wrapper's own handle is authoritative.
+    /// </summary>
+    private Status? _releasedStatus;
+
     /// <summary>Initializes a new instance of the <see cref="LibplctagLegacyTagRuntime"/> class.</summary>
     /// <param name="p">The parameters for tag creation.</param>
     public LibplctagLegacyTagRuntime(AbLegacyTagCreateParams p)
@@ -38,18 +44,42 @@ internal sealed class LibplctagLegacyTagRuntime : IAbLegacyTagRuntime
 
     /// <inheritdoc />
     public Task InitializeAsync(CancellationToken cancellationToken) =>
-        LibplctagLegacyStatusTranslation.Wrap(() => _tag.InitializeAsync(cancellationToken));
+        RunReleasingOrphanAsync(() => _tag.InitializeAsync(cancellationToken));
 
     /// <inheritdoc />
+    /// <remarks>libplctag initialises an uninitialised tag on its first read, so this path can orphan one too.</remarks>
     public Task ReadAsync(CancellationToken cancellationToken) =>
-        LibplctagLegacyStatusTranslation.Wrap(() => _tag.ReadAsync(cancellationToken));
+        RunReleasingOrphanAsync(() => _tag.ReadAsync(cancellationToken));
 
     /// <inheritdoc />
     public Task WriteAsync(CancellationToken cancellationToken) =>
-        LibplctagLegacyStatusTranslation.Wrap(() => _tag.WriteAsync(cancellationToken));
+        RunReleasingOrphanAsync(() => _tag.WriteAsync(cancellationToken));
+
+    /// <summary>
+    ///     Runs a libplctag operation; when it fails and leaves the tag uninitialised, destroys the native tag it
+    ///     created before the failure propagates, so its callback can never fire into a collected delegate (T21 press
+    ///     pass 1 crash). The status that tag held is kept for <see cref="GetStatus"/>.
+    /// </summary>
+    private async Task RunReleasingOrphanAsync(Func<Task> op)
+    {
+        try
+        {
+            await LibplctagLegacyStatusTranslation.Wrap(op).ConfigureAwait(false);
+            _releasedStatus = null;
+        }
+        catch
+        {
+            if (LibplctagOrphanRelease.ReleaseIfOrphaned(_tag) is { } status) _releasedStatus = status;
+            throw;
+        }
+    }
+
+    /// <summary>The native libplctag handle this runtime's tag holds or last held (0 if none was created). Tests only.</summary>
+    internal int NativeHandle => LibplctagOrphanRelease.HandleOf(_tag);
 
     /// <inheritdoc />
-    public int GetStatus() => (int)LibplctagLegacyStatusTranslation.ToAbStatus(_tag.GetStatus());
+    public int GetStatus() =>
+        (int)LibplctagLegacyStatusTranslation.ToAbStatus(_releasedStatus ?? _tag.GetStatus());
 
     /// <inheritdoc />
     public object? DecodeValue(AbLegacyDataType type, int? bitIndex) => type switch

src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/LibplctagOrphanRelease.cs

@@ -0,0 +1,117 @@
+using System.Collections.Concurrent;
+using System.Reflection;
+using libplctag;
+using libplctag.NativeImport;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.AbLegacy;
+
+/// <summary>
+///     Releases the native tag a FAILED libplctag initialisation leaves behind (T21 press pass 1 crash).
+/// </summary>
+/// <remarks>
+///     <para>libplctag.NET 1.5.2's <c>NativeTagWrapper.InitializeAsync</c> calls <c>plc_tag_create_ex</c>, which returns a
+///     native handle with the wrapper's <c>callback_func_ex</c> delegate registered, and only then waits for the
+///     <c>Created</c> event. When that event carries an error (a tag the controller does not have, a refused path, ...)
+///     it throws WITHOUT setting <c>_isInitialized</c>, and <c>Dispose()</c> unregisters and destroys only
+///     <c>if (_isInitialized)</c>. So the native tag outlives its wrapper with the callback still registered; once the
+///     wrapper is collected the delegate's thunk is freed, and the next event libplctag raises on that tag — at the
+///     latest the <c>DESTROYED</c> event from <c>plc_tag_shutdown</c>, which the native library runs from
+///     <c>atexit</c> — kills the process with "A callback was made on a garbage collected delegate of type
+///     'libplctag.NativeImport!libplctag.NativeImport.plctag+callback_func_ex::Invoke'". A timed-out initialisation
+///     unregisters the callback but never destroys the handle either, so that native tag keeps reconnecting in the
+///     background for the life of the process.</para>
+///     <para>The wrapper exposes no handle, so it is read by reflection from the two private fields of the pinned
+///     1.5.2 wrapper (<c>Tag._tag</c>, <c>NativeTagWrapper.nativeTagHandle</c>). If a future wrapper renames them the
+///     release cannot run; the tag is then rooted for the life of the process instead, which keeps its delegate
+///     alive (no crash, a bounded leak) — and <c>LibplctagLegacyOrphanReleaseTests</c> fails, so the bump is noticed.</para>
+/// </remarks>
+internal static class LibplctagOrphanRelease
+{
+    private const BindingFlags Private = BindingFlags.NonPublic | BindingFlags.Instance;
+
+    private static readonly FieldInfo? WrapperField = typeof(Tag).GetField("_tag", Private);
+    private static readonly FieldInfo? HandleField = WrapperField?.FieldType.GetField("nativeTagHandle", Private);
+
+    /// <summary>Tags whose handle could not be read: kept reachable so their callback delegate is never collected.</summary>
+    private static readonly ConcurrentBag<Tag> Rooted = [];
+
+    private static int _released;
+
+    /// <summary>True when the pinned wrapper's private fields were found, so a failed tag can be destroyed.</summary>
+    internal static bool CanReadHandles => HandleField is not null;
+
+    /// <summary>Orphaned native tags destroyed so far (process-wide; diagnostics and tests).</summary>
+    internal static int Released => Volatile.Read(ref _released);
+
+    /// <summary>Orphaned tags rooted for the process lifetime because their handle could not be read.</summary>
+    internal static int RootedCount => Rooted.Count;
+
+    /// <summary>The native handle the wrapper holds (0 when none was ever created, or unreadable).</summary>
+    internal static int HandleOf(Tag tag) =>
+        HandleField is not null && WrapperField!.GetValue(tag) is { } wrapper ? (int)HandleField.GetValue(wrapper)! : 0;
+
+    /// <summary>
+    ///     Runs a libplctag operation that may initialise <paramref name="tag"/> (InitializeAsync, or a first
+    ///     Read/Write, which initialise on demand). If it fails and leaves the tag uninitialised, the native tag it
+    ///     created is unregistered and destroyed before the failure propagates.
+    /// </summary>
+    internal static async Task RunAsync(Tag tag, Func<Task> op)
+    {
+        try
+        {
+            await op().ConfigureAwait(false);
+        }
+        catch
+        {
+            ReleaseIfOrphaned(tag);
+            throw;
+        }
+    }
+
+    /// <inheritdoc cref="RunAsync(Tag, Func{Task})"/>
+    internal static async Task<T> RunAsync<T>(Tag tag, Func<Task<T>> op)
+    {
+        try
+        {
+            return await op().ConfigureAwait(false);
+        }
+        catch
+        {
+            ReleaseIfOrphaned(tag);
+            throw;
+        }
+    }
+
+    /// <summary>
+    ///     Destroys the native tag behind an UNINITIALISED wrapper, unregistering its callback first. No-op for an
+    ///     initialised tag (its own <c>Dispose</c> handles it) or one that never got a handle. Never throws.
+    /// </summary>
+    /// <returns>The status the native tag held just before it was destroyed (what <c>GetStatus()</c> would have
+    ///     reported), or null when nothing was destroyed.</returns>
+    internal static Status? ReleaseIfOrphaned(Tag tag)
+    {
+        try
+        {
+            if (tag.IsInitialized) return null;
+            if (!CanReadHandles)
+            {
+                Rooted.Add(tag);
+                return null;
+            }
+            var handle = HandleOf(tag);
+            if (handle <= 0) return null;   // plc_tag_create_ex refused synchronously: nothing native exists
+            var status = (Status)plctag.plc_tag_status(handle);
+            plctag.plc_tag_unregister_callback(handle);
+            plctag.plc_tag_destroy(handle);
+            Interlocked.Increment(ref _released);
+            return status;
+        }
+        catch (Exception)
+        {
+            // A release must never mask the initialisation failure it follows. Root the tag so that, whatever
+            // state the native side is in, its callback delegate stays alive.
+            Rooted.Add(tag);
+            return null;
+        }
+    }
+}