rename: prefix gateway projects/namespaces with ZB.MOM.WW + sln→slnx

Apply the ZB.MOM.WW. prefix to all gateway-side projects, folders, .csproj/.sln contents, C# namespaces, using directives, generated proto C# (csharp_namespace + checked-in generated files), InternalsVisibleTo attributes, project-name string literals (LoadProject, .sln lookups, worker exe paths, staticwebassets manifest), and the install/script/doc references that point at any of the above. Migrate the solution from .sln to .slnx via `dotnet sln migrate` and delete the old file. External-runtime identifiers are intentionally NOT prefixed so external configuration keeps working: - GatewayMetrics.cs MeterName ("MxGateway.Server") - DashboardAuthenticationDefaults Scheme/Policy ("MxGateway.Dashboard") - GatewayRequestLoggingMiddleware logger category ("MxGateway.Request") - StaRuntime thread name ("MxGateway.Worker.STA") - appsettings.json root section "MxGateway" + env-var prefix MxGateway__... and secret-name MxGateway:ApiKeyPepper - C:\ProgramData\MxGateway\ data dir paths Also fixes two tests that were not rename-related but became visible while validating the rename: - WorkerLiveMxAccessSmokeTests.ShutDownAsync: cancellation that the gateway service correctly maps to RpcException(Cancelled) per gRPC convention was being misclassified as a stream fault. Added a sibling catch on RpcException with StatusCode.Cancelled. - IntegrationTestEnvironment.ResolveRepositoryRoot: extracted IsRepositoryRoot and made it accept either a .git marker OR a .sln/.slnx next to src/ so the worker-exe walker works in non-git working copies. clients/proto/proto-inputs.json's protoRoot updated to point at src/ZB.MOM.WW.MxGateway.Contracts/Protos. Verified by `dotnet build` and a full `dotnet test` of the .slnx with MXGATEWAY_RUN_LIVE_{MXACCESS,LDAP,GALAXY}_TESTS=1: Tests: 472/472 pass Worker.Tests: 280/280 pass (4 dev-rig [Fact(Skip=...)] skipped) IntegrationTests: 18/18 pass Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-23 16:22:23 -04:00
parent 867bf18116
commit dc9c0c950c
491 changed files with 32854 additions and 8414 deletions
@@ -0,0 +1,351 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Runtime.InteropServices;
+using System.Threading;
+using System.Threading.Tasks;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Worker.Sta;
+using ZB.MOM.WW.MxGateway.Worker.Tests.TestSupport;
+
+namespace ZB.MOM.WW.MxGateway.Worker.Tests.Sta;
+
+/// <summary>
+/// Tests for StaCommandDispatcher command queueing and execution.
+/// </summary>
+public sealed class StaCommandDispatcherTests
+{
+    /// <summary>
+    /// Verifies commands execute on the STA thread in queue order.
+    /// </summary>
+    [Fact]
+    public async Task DispatchAsync_ExecutesCommandsOnStaInQueueOrder()
+    {
+        using StaRuntime runtime = CreateRuntime();
+        runtime.Start();
+        RecordingCommandExecutor executor = new();
+        StaCommandDispatcher dispatcher = new(runtime, executor);
+
+        Task<MxCommandReply> first = dispatcher.DispatchAsync(CreateCommand("correlation-1", MxCommandKind.Register));
+        Task<MxCommandReply> second = dispatcher.DispatchAsync(CreateCommand("correlation-2", MxCommandKind.AddItem));
+
+        MxCommandReply[] replies = await Task.WhenAll(first, second);
+
+        Assert.Equal(new[] { "correlation-1", "correlation-2" }, executor.CorrelationIds);
+        Assert.All(executor.ThreadIds, threadId => Assert.Equal(runtime.StaThreadId, threadId));
+        Assert.Equal("correlation-1", replies[0].CorrelationId);
+        Assert.Equal("correlation-2", replies[1].CorrelationId);
+        Assert.Equal(ProtocolStatusCode.Ok, replies[0].ProtocolStatus.Code);
+    }
+
+    /// <summary>
+    /// Verifies executor exceptions are captured as HResult in the reply without exposing message details.
+    /// </summary>
+    [Fact]
+    public async Task DispatchAsync_WhenExecutorThrows_ReturnsFailureReplyWithHResult()
+    {
+        using StaRuntime runtime = CreateRuntime();
+        runtime.Start();
+        StaCommandDispatcher dispatcher = new(
+            runtime,
+            new ThrowingCommandExecutor(new COMException("provider detail", unchecked((int)0x80070057))));
+
+        MxCommandReply reply = await dispatcher.DispatchAsync(CreateCommand("correlation-1", MxCommandKind.Register));
+
+        Assert.Equal("session-1", reply.SessionId);
+        Assert.Equal("correlation-1", reply.CorrelationId);
+        Assert.Equal(MxCommandKind.Register, reply.Kind);
+        Assert.Equal(ProtocolStatusCode.MxaccessFailure, reply.ProtocolStatus.Code);
+        Assert.Equal(unchecked((int)0x80070057), reply.Hresult);
+        Assert.Contains("0x80070057", reply.DiagnosticMessage);
+        Assert.DoesNotContain("provider detail", reply.DiagnosticMessage);
+    }
+
+    /// <summary>
+    /// Verifies cancellation before execution prevents the command from running.
+    /// </summary>
+    [Fact]
+    public async Task DispatchAsync_WhenCanceledBeforeExecution_ReturnsCanceledReplyWithoutExecuting()
+    {
+        using StaRuntime runtime = CreateRuntime();
+        runtime.Start();
+        BlockingCommandExecutor executor = new();
+        StaCommandDispatcher dispatcher = new(runtime, executor);
+        Task<MxCommandReply> blocked = dispatcher.DispatchAsync(CreateCommand("blocked", MxCommandKind.Register));
+        Assert.True(executor.Started.Wait(TimeSpan.FromSeconds(2)));
+
+        using CancellationTokenSource cancellation = new();
+        Task<MxCommandReply> canceled = dispatcher.DispatchAsync(
+            CreateCommand("canceled", MxCommandKind.AddItem, cancellation.Token));
+        cancellation.Cancel();
+
+        executor.Release();
+        MxCommandReply canceledReply = await canceled;
+        await blocked;
+
+        Assert.Equal(ProtocolStatusCode.Canceled, canceledReply.ProtocolStatus.Code);
+        Assert.DoesNotContain("canceled", executor.CorrelationIds);
+    }
+
+    /// <summary>
+    /// Verifies cancellation cannot abort a command already executing on the STA:
+    /// once the executor has started, cancelling the token is a no-op and the
+    /// command still runs to completion and returns its normal reply. This
+    /// matches <c>gateway.md</c>: cancellation "cannot safely abort an in-flight
+    /// COM call on the STA". The test does not — and cannot — distinguish "cancel
+    /// observed and ignored" from "cancel never checked"; it only proves the
+    /// in-flight command is not aborted.
+    /// </summary>
+    [Fact]
+    public async Task DispatchAsync_WhenCanceledWhileExecuting_DoesNotAbortInFlightCommand()
+    {
+        using StaRuntime runtime = CreateRuntime();
+        runtime.Start();
+        BlockingCommandExecutor executor = new();
+        StaCommandDispatcher dispatcher = new(runtime, executor);
+        using CancellationTokenSource cancellation = new();
+
+        Task<MxCommandReply> replyTask = dispatcher.DispatchAsync(
+            CreateCommand("late-reply", MxCommandKind.Register, cancellation.Token));
+
+        Assert.True(executor.Started.Wait(TimeSpan.FromSeconds(2)));
+        cancellation.Cancel();
+        executor.Release();
+
+        MxCommandReply reply = await replyTask;
+
+        Assert.Equal(ProtocolStatusCode.Ok, reply.ProtocolStatus.Code);
+        Assert.Contains("late-reply", executor.CorrelationIds);
+    }
+
+    /// <summary>
+    /// Verifies shutdown rejects new dispatch attempts.
+    /// </summary>
+    [Fact]
+    public async Task DispatchAsync_WhenShutdownRequested_RejectsNewCommands()
+    {
+        using StaRuntime runtime = CreateRuntime();
+        runtime.Start();
+        StaCommandDispatcher dispatcher = new(runtime, new RecordingCommandExecutor());
+
+        dispatcher.RequestShutdown();
+        MxCommandReply reply = await dispatcher.DispatchAsync(CreateCommand("correlation-1", MxCommandKind.Register));
+
+        Assert.Equal(ProtocolStatusCode.WorkerUnavailable, reply.ProtocolStatus.Code);
+        Assert.Equal("correlation-1", reply.CorrelationId);
+    }
+
+    /// <summary>
+    /// Verifies shutdown allows the current command to complete but rejects queued commands.
+    /// </summary>
+    [Fact]
+    public async Task RequestShutdown_RejectsQueuedCommandButLetsCurrentCommandFinish()
+    {
+        using StaRuntime runtime = CreateRuntime();
+        runtime.Start();
+        BlockingCommandExecutor executor = new();
+        StaCommandDispatcher dispatcher = new(runtime, executor);
+        Task<MxCommandReply> current = dispatcher.DispatchAsync(CreateCommand("current", MxCommandKind.Register));
+        Assert.True(executor.Started.Wait(TimeSpan.FromSeconds(2)));
+        Task<MxCommandReply> pending = dispatcher.DispatchAsync(CreateCommand("pending", MxCommandKind.AddItem));
+
+        dispatcher.RequestShutdown();
+        MxCommandReply pendingReply = await pending;
+        executor.Release();
+        MxCommandReply currentReply = await current;
+
+        Assert.Equal(ProtocolStatusCode.WorkerUnavailable, pendingReply.ProtocolStatus.Code);
+        Assert.Equal(ProtocolStatusCode.Ok, currentReply.ProtocolStatus.Code);
+        Assert.Equal(new[] { "current" }, executor.CorrelationIds);
+    }
+
+    /// <summary>
+    /// Verifies heartbeat reports current command correlation ID and pending command count.
+    /// </summary>
+    [Fact]
+    public async Task PopulateHeartbeat_ReportsCurrentCorrelationAndPendingCount()
+    {
+        using StaRuntime runtime = CreateRuntime();
+        runtime.Start();
+        BlockingCommandExecutor executor = new();
+        StaCommandDispatcher dispatcher = new(runtime, executor);
+
+        Task<MxCommandReply> current = dispatcher.DispatchAsync(CreateCommand("current", MxCommandKind.Register));
+        Assert.True(executor.Started.Wait(TimeSpan.FromSeconds(2)));
+        Task<MxCommandReply> pending = dispatcher.DispatchAsync(CreateCommand("pending", MxCommandKind.AddItem));
+
+        WorkerHeartbeat heartbeat = new();
+        dispatcher.PopulateHeartbeat(heartbeat);
+
+        Assert.Equal("current", heartbeat.CurrentCommandCorrelationId);
+        Assert.Equal(1u, heartbeat.PendingCommandCount);
+
+        executor.Release();
+        await Task.WhenAll(current, pending);
+    }
+
+    private static StaCommand CreateCommand(
+        string correlationId,
+        MxCommandKind kind,
+        CancellationToken cancellationToken = default)
+    {
+        return new StaCommand(
+            "session-1",
+            correlationId,
+            new MxCommand
+            {
+                Kind = kind,
+                Ping = new PingCommand
+                {
+                    Message = correlationId,
+                },
+            },
+            cancellationToken: cancellationToken);
+    }
+
+    private static StaRuntime CreateRuntime()
+    {
+        return new StaRuntime(
+            new NoopComApartmentInitializer(),
+            new StaMessagePump(),
+            TimeSpan.FromMilliseconds(25));
+    }
+
+    /// <summary>
+    /// Test executor that records executed command correlations and thread IDs.
+    /// </summary>
+    private sealed class RecordingCommandExecutor : IStaCommandExecutor
+    {
+        private readonly object gate = new();
+        private readonly List<string> correlationIds = new();
+        private readonly List<int> threadIds = new();
+
+        /// <summary>
+        /// List of correlation IDs from executed commands.
+        /// </summary>
+        public IReadOnlyList<string> CorrelationIds
+        {
+            get
+            {
+                lock (gate)
+                {
+                    return correlationIds.ToArray();
+                }
+            }
+        }
+
+        /// <summary>
+        /// List of thread IDs on which commands executed.
+        /// </summary>
+        public IReadOnlyList<int> ThreadIds
+        {
+            get
+            {
+                lock (gate)
+                {
+                    return threadIds.ToArray();
+                }
+            }
+        }
+
+        /// <inheritdoc />
+        public MxCommandReply Execute(StaCommand command)
+        {
+            lock (gate)
+            {
+                correlationIds.Add(command.CorrelationId);
+                threadIds.Add(Thread.CurrentThread.ManagedThreadId);
+            }
+
+            return new MxCommandReply
+            {
+                ProtocolStatus = new ProtocolStatus
+                {
+                    Code = ProtocolStatusCode.Ok,
+                    Message = "OK",
+                },
+            };
+        }
+    }
+
+    /// <summary>
+    /// Test executor that blocks execution until explicitly released.
+    /// </summary>
+    private sealed class BlockingCommandExecutor : IStaCommandExecutor
+    {
+        private readonly ManualResetEventSlim release = new(false);
+        private readonly object gate = new();
+        private readonly List<string> correlationIds = new();
+
+        /// <summary>
+        /// Signals when execution of the current command has started.
+        /// </summary>
+        public ManualResetEventSlim Started { get; } = new(false);
+
+        /// <summary>
+        /// List of correlation IDs from executed commands.
+        /// </summary>
+        public IReadOnlyList<string> CorrelationIds
+        {
+            get
+            {
+                lock (gate)
+                {
+                    return correlationIds.ToArray();
+                }
+            }
+        }
+
+        /// <inheritdoc />
+        public MxCommandReply Execute(StaCommand command)
+        {
+            lock (gate)
+            {
+                correlationIds.Add(command.CorrelationId);
+            }
+
+            Started.Set();
+            release.Wait(TimeSpan.FromSeconds(5));
+
+            return new MxCommandReply
+            {
+                ProtocolStatus = new ProtocolStatus
+                {
+                    Code = ProtocolStatusCode.Ok,
+                    Message = "OK",
+                },
+            };
+        }
+
+        /// <summary>
+        /// Unblocks the waiting command execution.
+        /// </summary>
+        public void Release()
+        {
+            release.Set();
+        }
+    }
+
+    /// <summary>
+    /// Test executor that always throws a configured exception.
+    /// </summary>
+    private sealed class ThrowingCommandExecutor : IStaCommandExecutor
+    {
+        private readonly Exception exception;
+
+        /// <summary>
+        /// Initializes with the exception to throw.
+        /// </summary>
+        /// <param name="exception">Exception to throw on execution.</param>
+        public ThrowingCommandExecutor(Exception exception)
+        {
+            this.exception = exception;
+        }
+
+        /// <inheritdoc />
+        public MxCommandReply Execute(StaCommand command)
+        {
+            throw exception;
+        }
+    }
+}
@@ -0,0 +1,260 @@
+using System;
+using System.Diagnostics;
+using System.Threading;
+using System.Threading.Tasks;
+using ZB.MOM.WW.MxGateway.Worker.Sta;
+
+namespace ZB.MOM.WW.MxGateway.Worker.Tests.Sta;
+
+/// <summary>
+/// Tests for <see cref="StaMessagePump"/>.
+/// </summary>
+/// <remarks>
+/// Boundary: the <c>MsgWaitFailed</c> failure branch of <c>WaitForWorkOrMessages</c>
+/// is not exercised. Forcing <c>MsgWaitForMultipleObjectsEx</c> to fail requires
+/// passing a deliberately invalid native handle, which is unsafe to construct in a
+/// managed test and can corrupt the thread's wait state. The other behavior — null
+/// argument validation, waking on a signalled event, returning on timeout, the
+/// timeout conversion edge cases observable through wait latency, and the
+/// pump's drain count — is covered directly here.
+/// </remarks>
+public sealed class StaMessagePumpTests
+{
+    /// <summary>
+    /// Verifies that WaitForWorkOrMessages throws ArgumentNullException for a null wake event.
+    /// </summary>
+    [Fact]
+    public void WaitForWorkOrMessages_NullWakeEvent_ThrowsArgumentNullException()
+    {
+        StaMessagePump pump = new();
+
+        ArgumentNullException exception = Assert.Throws<ArgumentNullException>(
+            () => pump.WaitForWorkOrMessages(null!, TimeSpan.FromMilliseconds(10)));
+
+        Assert.Equal("commandWakeEvent", exception.ParamName);
+    }
+
+    /// <summary>
+    /// Verifies that WaitForWorkOrMessages returns promptly when the wake event is already signalled.
+    /// </summary>
+    [Fact]
+    public async Task WaitForWorkOrMessages_WakeEventAlreadySignalled_ReturnsImmediately()
+    {
+        StaMessagePump pump = new();
+        using ManualResetEventSlim wakeEvent = new(initialState: true);
+
+        await RunOnStaThreadAsync(() =>
+        {
+            Stopwatch stopwatch = Stopwatch.StartNew();
+            pump.WaitForWorkOrMessages(wakeEvent.WaitHandle, TimeSpan.FromSeconds(30));
+            stopwatch.Stop();
+
+            // A 30s timeout was supplied; returning quickly proves the signalled
+            // wake handle — not the timeout — ended the wait.
+            Assert.True(
+                stopwatch.Elapsed < TimeSpan.FromSeconds(5),
+                $"Wait took {stopwatch.Elapsed}; a pre-signalled wake event should return immediately.");
+        });
+    }
+
+    /// <summary>
+    /// Verifies that WaitForWorkOrMessages wakes when the wake event is signalled from another thread.
+    /// </summary>
+    [Fact]
+    public async Task WaitForWorkOrMessages_WakeEventSignalledDuringWait_Returns()
+    {
+        StaMessagePump pump = new();
+        using ManualResetEventSlim wakeEvent = new(initialState: false);
+
+        Task signalTask = Task.Run(async () =>
+        {
+            await Task.Delay(150, CancellationToken.None);
+            wakeEvent.Set();
+        });
+
+        await RunOnStaThreadAsync(() =>
+        {
+            Stopwatch stopwatch = Stopwatch.StartNew();
+            pump.WaitForWorkOrMessages(wakeEvent.WaitHandle, TimeSpan.FromSeconds(30));
+            stopwatch.Stop();
+
+            Assert.True(
+                stopwatch.Elapsed < TimeSpan.FromSeconds(10),
+                $"Wait took {stopwatch.Elapsed}; signalling the wake event should end the 30s wait early.");
+        });
+
+        await signalTask;
+    }
+
+    /// <summary>
+    /// Verifies that WaitForWorkOrMessages returns on timeout when the wake event is never signalled.
+    /// </summary>
+    [Fact]
+    public async Task WaitForWorkOrMessages_WakeEventNeverSignalled_ReturnsAfterTimeout()
+    {
+        StaMessagePump pump = new();
+        using ManualResetEventSlim wakeEvent = new(initialState: false);
+
+        await RunOnStaThreadAsync(() =>
+        {
+            Stopwatch stopwatch = Stopwatch.StartNew();
+            pump.WaitForWorkOrMessages(wakeEvent.WaitHandle, TimeSpan.FromMilliseconds(150));
+            stopwatch.Stop();
+
+            // The wait must end of its own accord (timeout). Lower bound is loose
+            // because the timeout converts via Math.Ceiling and the OS scheduler
+            // adds slack; upper bound proves it is not waiting indefinitely.
+            Assert.True(
+                stopwatch.Elapsed < TimeSpan.FromSeconds(10),
+                $"Wait took {stopwatch.Elapsed}; a 150ms timeout should end the wait without a signal.");
+        });
+    }
+
+    /// <summary>
+    /// Verifies that a zero timeout (the TimeSpan.Zero conversion branch) returns without blocking.
+    /// </summary>
+    [Fact]
+    public async Task WaitForWorkOrMessages_ZeroTimeout_ReturnsWithoutBlocking()
+    {
+        StaMessagePump pump = new();
+        using ManualResetEventSlim wakeEvent = new(initialState: false);
+
+        await RunOnStaThreadAsync(() =>
+        {
+            Stopwatch stopwatch = Stopwatch.StartNew();
+
+            // TimeSpan.Zero exercises the "<= Zero -> 0 ms" conversion branch:
+            // MsgWaitForMultipleObjectsEx polls and returns immediately.
+            pump.WaitForWorkOrMessages(wakeEvent.WaitHandle, TimeSpan.Zero);
+            stopwatch.Stop();
+
+            Assert.True(
+                stopwatch.Elapsed < TimeSpan.FromSeconds(2),
+                $"Wait took {stopwatch.Elapsed}; a zero timeout must not block.");
+        });
+    }
+
+    /// <summary>
+    /// Verifies that PumpPendingMessages returns zero when the STA thread message queue is empty.
+    /// </summary>
+    [Fact]
+    public async Task PumpPendingMessages_NoMessagesPosted_ReturnsZero()
+    {
+        StaMessagePump pump = new();
+
+        int pumped = await RunOnStaThreadAsync(() =>
+        {
+            // Drain anything the apartment/thread start posted, then measure a clean queue.
+            pump.PumpPendingMessages();
+            return pump.PumpPendingMessages();
+        });
+
+        Assert.Equal(0, pumped);
+    }
+
+    /// <summary>
+    /// Verifies that PumpPendingMessages dispatches and counts messages posted to the STA thread.
+    /// </summary>
+    [Fact]
+    public async Task PumpPendingMessages_MessagesPostedToStaThread_ReturnsCountProcessed()
+    {
+        StaMessagePump pump = new();
+
+        int pumped = await RunOnStaThreadAsync(() =>
+        {
+            // Clear any startup messages so the count reflects only what we post.
+            pump.PumpPendingMessages();
+
+            uint threadId = GetCurrentThreadId();
+            Assert.True(PostThreadMessage(threadId, WmNull, UIntPtr.Zero, IntPtr.Zero));
+            Assert.True(PostThreadMessage(threadId, WmNull, UIntPtr.Zero, IntPtr.Zero));
+            Assert.True(PostThreadMessage(threadId, WmNull, UIntPtr.Zero, IntPtr.Zero));
+
+            return pump.PumpPendingMessages();
+        });
+
+        Assert.Equal(3, pumped);
+    }
+
+    /// <summary>
+    /// Verifies that WaitForWorkOrMessages returns once a Windows message is posted to the STA thread.
+    /// </summary>
+    [Fact]
+    public async Task WaitForWorkOrMessages_WindowsMessagePosted_ReturnsForInputAvailable()
+    {
+        StaMessagePump pump = new();
+        using ManualResetEventSlim wakeEvent = new(initialState: false);
+        using ManualResetEventSlim threadReady = new(initialState: false);
+        uint staThreadId = 0;
+
+        Task staTask = RunOnStaThreadAsync(() =>
+        {
+            staThreadId = GetCurrentThreadId();
+            pump.PumpPendingMessages();
+            threadReady.Set();
+
+            Stopwatch stopwatch = Stopwatch.StartNew();
+            // The wake event is never signalled. Only the posted Windows message
+            // (QS_ALLINPUT wake mask) can end this 30s wait early.
+            pump.WaitForWorkOrMessages(wakeEvent.WaitHandle, TimeSpan.FromSeconds(30));
+            stopwatch.Stop();
+
+            Assert.True(
+                stopwatch.Elapsed < TimeSpan.FromSeconds(10),
+                $"Wait took {stopwatch.Elapsed}; a posted Windows message should wake the pump.");
+        });
+
+        Assert.True(threadReady.Wait(TimeSpan.FromSeconds(5)), "STA thread did not start.");
+        await Task.Delay(100, CancellationToken.None);
+        Assert.True(
+            PostThreadMessage(staThreadId, WmNull, UIntPtr.Zero, IntPtr.Zero),
+            "Failed to post a Windows message to the STA thread.");
+
+        await staTask;
+    }
+
+    private const uint WmNull = 0x0000;
+
+    /// <summary>Runs an action on a dedicated STA thread and returns when it completes.</summary>
+    private static Task RunOnStaThreadAsync(Action action)
+    {
+        return RunOnStaThreadAsync(() =>
+        {
+            action();
+            return 0;
+        });
+    }
+
+    /// <summary>Runs a function on a dedicated STA thread and returns its result.</summary>
+    private static Task<T> RunOnStaThreadAsync<T>(Func<T> function)
+    {
+        TaskCompletionSource<T> completion = new();
+        Thread thread = new(() =>
+        {
+            try
+            {
+                completion.SetResult(function());
+            }
+            catch (Exception exception)
+            {
+                completion.SetException(exception);
+            }
+        })
+        {
+            IsBackground = true,
+        };
+        thread.SetApartmentState(ApartmentState.STA);
+        thread.Start();
+        return completion.Task;
+    }
+
+    [System.Runtime.InteropServices.DllImport("kernel32.dll")]
+    private static extern uint GetCurrentThreadId();
+
+    [System.Runtime.InteropServices.DllImport("user32.dll", SetLastError = true)]
+    private static extern bool PostThreadMessage(
+        uint threadId,
+        uint message,
+        UIntPtr wParam,
+        IntPtr lParam);
+}
@@ -0,0 +1,181 @@
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+using ZB.MOM.WW.MxGateway.Worker.Sta;
+
+namespace ZB.MOM.WW.MxGateway.Worker.Tests.Sta;
+
+public sealed class StaRuntimeTests
+{
+    /// <summary>Verifies that InvokeAsync executes commands on the STA thread.</summary>
+    [Fact]
+    public async Task InvokeAsync_ExecutesCommandOnStaThread()
+    {
+        RecordingComApartmentInitializer initializer = new();
+        using StaRuntime runtime = CreateRuntime(initializer);
+
+        runtime.Start();
+
+        StaCommandObservation observation = await runtime.InvokeAsync(
+            () => new StaCommandObservation(
+                Thread.CurrentThread.ManagedThreadId,
+                Thread.CurrentThread.GetApartmentState()));
+
+        Assert.Equal(runtime.StaThreadId, observation.ThreadId);
+        Assert.Equal(initializer.InitializeThreadId, observation.ThreadId);
+        Assert.Equal(ApartmentState.STA, observation.ApartmentState);
+    }
+
+    /// <summary>
+    /// Verifies that InvokeAsync wakes the idle pump when a command is queued.
+    /// The pump is configured with a 30-second idle period — far longer than
+    /// any reasonable test run — so the awaited command completing at all proves
+    /// the command wake event (not the idle pump tick) drove the dispatch. No
+    /// wall-clock assertion is used: a loaded CI agent can stall an otherwise
+    /// correct dispatch past an arbitrary millisecond budget, which would be a
+    /// false failure.
+    /// </summary>
+    [Fact]
+    public async Task InvokeAsync_WakesIdlePumpForQueuedCommand()
+    {
+        RecordingComApartmentInitializer initializer = new();
+        using StaRuntime runtime = new(
+            initializer,
+            new StaMessagePump(),
+            TimeSpan.FromSeconds(30));
+        runtime.Start();
+
+        int threadId = await runtime.InvokeAsync(() => Thread.CurrentThread.ManagedThreadId);
+
+        Assert.Equal(runtime.StaThreadId, threadId);
+    }
+
+    /// <summary>Verifies that Shutdown stops the thread and uninitializes the COM apartment.</summary>
+    [Fact]
+    public void Shutdown_StopsThreadAndUninitializesComApartment()
+    {
+        RecordingComApartmentInitializer initializer = new();
+        using StaRuntime runtime = CreateRuntime(initializer);
+        runtime.Start();
+
+        bool stopped = runtime.Shutdown(TimeSpan.FromSeconds(2));
+
+        Assert.True(stopped);
+        Assert.False(runtime.IsRunning);
+        Assert.Equal(1, initializer.InitializeCount);
+        Assert.Equal(1, initializer.UninitializeCount);
+        Assert.Equal(initializer.InitializeThreadId, initializer.UninitializeThreadId);
+    }
+
+    /// <summary>Verifies that LastActivityUtc updates while the pump is idle.</summary>
+    [Fact]
+    public void LastActivityUtc_UpdatesWhilePumpIsIdle()
+    {
+        RecordingComApartmentInitializer initializer = new();
+        using StaRuntime runtime = CreateRuntime(initializer);
+        runtime.Start();
+        DateTimeOffset firstActivity = runtime.LastActivityUtc;
+
+        bool updated = SpinWait.SpinUntil(
+            () => runtime.LastActivityUtc > firstActivity,
+            TimeSpan.FromSeconds(2));
+
+        Assert.True(updated);
+    }
+
+    /// <summary>Verifies that InvokeAsync faults the returned task when a command raises an exception without stopping the runtime.</summary>
+    [Fact]
+    public async Task InvokeAsync_CommandException_FaultsReturnedTaskWithoutStoppingRuntime()
+    {
+        RecordingComApartmentInitializer initializer = new();
+        using StaRuntime runtime = CreateRuntime(initializer);
+        runtime.Start();
+
+        InvalidOperationException exception = await Assert.ThrowsAsync<InvalidOperationException>(
+            () => runtime.InvokeAsync<int>(() => throw new InvalidOperationException("command failed")));
+
+        int threadId = await runtime.InvokeAsync(() => Thread.CurrentThread.ManagedThreadId);
+        Assert.Equal("command failed", exception.Message);
+        Assert.Equal(runtime.StaThreadId, threadId);
+    }
+
+    /// <summary>
+    ///     Verifies that InvokeAsync returns a faulted task when called after
+    ///     Shutdown. Worker-016 introduced <see cref="StaRuntimeShutdownException"/>
+    ///     (a dedicated subtype of <see cref="InvalidOperationException"/>) so
+    ///     callers — notably <c>MxAccessStaSession.RunAlarmPollLoopAsync</c> —
+    ///     can distinguish the graceful shutdown signal from a vanilla
+    ///     <see cref="InvalidOperationException"/> such as an STA-affinity
+    ///     assertion. The test pins the exact type so a regression that
+    ///     reverts to a plain <c>InvalidOperationException</c> fails here.
+    /// </summary>
+    [Fact]
+    public async Task InvokeAsync_AfterShutdown_ReturnsFaultedTask()
+    {
+        RecordingComApartmentInitializer initializer = new();
+        using StaRuntime runtime = CreateRuntime(initializer);
+        runtime.Start();
+        runtime.Shutdown(TimeSpan.FromSeconds(2));
+
+        StaRuntimeShutdownException exception = await Assert.ThrowsAsync<StaRuntimeShutdownException>(
+            () => runtime.InvokeAsync(() => Thread.CurrentThread.ManagedThreadId));
+
+        Assert.Contains("shutting down", exception.Message);
+    }
+
+    private static StaRuntime CreateRuntime(RecordingComApartmentInitializer initializer)
+    {
+        return new StaRuntime(
+            initializer,
+            new StaMessagePump(),
+            TimeSpan.FromMilliseconds(25));
+    }
+
+    /// <summary>Records the thread ID and apartment state of an STA command execution.</summary>
+    private sealed class StaCommandObservation
+    {
+        /// <summary>Initializes a new instance of the StaCommandObservation class.</summary>
+        /// <param name="threadId">Managed thread ID where the command executed.</param>
+        /// <param name="apartmentState">COM apartment state of the thread.</param>
+        public StaCommandObservation(int threadId, ApartmentState apartmentState)
+        {
+            ThreadId = threadId;
+            ApartmentState = apartmentState;
+        }
+
+        /// <summary>The thread ID where the command executed.</summary>
+        public int ThreadId { get; }
+
+        /// <summary>The apartment state of the thread.</summary>
+        public ApartmentState ApartmentState { get; }
+    }
+
+    private sealed class RecordingComApartmentInitializer : IStaComApartmentInitializer
+    {
+        /// <summary>The number of times Initialize was called.</summary>
+        public int InitializeCount { get; private set; }
+
+        /// <summary>The number of times Uninitialize was called.</summary>
+        public int UninitializeCount { get; private set; }
+
+        /// <summary>The thread ID where Initialize was called.</summary>
+        public int? InitializeThreadId { get; private set; }
+
+        /// <summary>The thread ID where Uninitialize was called.</summary>
+        public int? UninitializeThreadId { get; private set; }
+
+        /// <summary>Initializes the COM apartment and records the calling thread.</summary>
+        public void Initialize()
+        {
+            InitializeCount++;
+            InitializeThreadId = Thread.CurrentThread.ManagedThreadId;
+        }
+
+        /// <summary>Uninitializes the COM apartment and records the calling thread.</summary>
+        public void Uninitialize()
+        {
+            UninitializeCount++;
+            UninitializeThreadId = Thread.CurrentThread.ManagedThreadId;
+        }
+    }
+}