fix(IPC-36,IPC-37): guard secondary contracts

docs/Contracts.md

@@ -94,6 +94,15 @@ only and does not share types with `mxaccess_gateway.proto`. See
 [Galaxy Repository Browse](./GalaxyRepository.md) for the RPC catalog and
 behavior.
 
+The retained proto remains the client-generation source of truth while the
+gateway serves the wire-identical descriptor from the
+`ZB.MOM.WW.GalaxyRepository` package. `GalaxyContractParityTests` converts both
+loaded descriptors to `FileDescriptorProto`, removes source locations, and
+normalizes the C# namespace and file name before comparing deterministic bytes.
+Its mutation test also requires drift failures to identify the first differing
+protobuf message. Any parity failure must be resolved before publishing either
+Contracts or clients.
+
 Generated C# output is written to `src/ZB.MOM.WW.MxGateway.Contracts/Generated/`. Do not
 hand-edit generated files.
 
@@ -140,6 +149,13 @@ Run the focused contract tests after changing either `.proto` file:
 dotnet test src/ZB.MOM.WW.MxGateway.Tests/ZB.MOM.WW.MxGateway.Tests.csproj --filter ProtobufContractRoundTripTests
 ```
 
+When changing `galaxy_repository.proto` or the served Galaxy Repository
+package, also run the retained-vs-served parity guard:
+
+```bash
+dotnet test src/ZB.MOM.WW.MxGateway.Tests/ZB.MOM.WW.MxGateway.Tests.csproj --filter GalaxyContractParityTests
+```
+
 The full solution build also regenerates the C# contracts before compiling
 gateway and test projects:
 

docs/MxAccessWorkerInstanceDesign.md

@@ -90,13 +90,22 @@ Expected command-line arguments:
 --protocol-version <version>
 ```
 
-Expected protected environment values:
+Expected launch environment values (the shared names are defined by
+`WorkerLaunchEnvironment` in Contracts):
 
 ```text
 MXGATEWAY_WORKER_NONCE=<random nonce>
-MXGATEWAY_WORKER_LOG_CONTEXT=<optional context>
+MXGATEWAY_WORKER_PIPE_CONNECT_ATTEMPT_TIMEOUT_MS=<milliseconds>
+MXGATEWAY_WORKER_WRITE_COMPLETION_WAIT_MS=<milliseconds>
+MXGATEWAY_EVENT_QUEUE_CAPACITY=<events>
+MXGATEWAY_ALARM_POLL_INTERVAL_MS=<milliseconds>
+MXGATEWAY_ALARM_MAX_ALARMS_PER_FETCH=<alarms>
 ```
 
+The nonce is protected bootstrap material. The remaining values are derived
+from the public `MxGateway:Worker:*` and `MxGateway:Alarms:*` configuration
+keys documented in [Worker Process Launcher](./WorkerProcessLauncher.md).
+
 Startup sequence:
 
 1. Parse command-line arguments.
@@ -312,7 +321,8 @@ write wait still yields the empty-`statuses` unconfirmed reply, and an expired
 per-tag `ReadBulk` wait still reports its own timeout.
 
 The write wait's budget is `MxGateway:Worker:WriteCompletionWaitMilliseconds`
-(default 1500). It is a bounded hold on the STA per unary write, so deployments
+(default 1500). It applies to `Write`, `Write2`, `WriteSecured`, and
+`WriteSecured2` and is a bounded hold on the STA per single-item write, so deployments
 whose write workload is effectively fire-and-forget — no consumer reads the
 reply's `statuses` — can lower it, or set `0` to skip the wait entirely and
 reply on acceptance alone.

docs/WorkerProcessLauncher.md

@@ -26,6 +26,23 @@ The launcher sets the nonce through the `MXGATEWAY_WORKER_NONCE` environment
 variable. The nonce is not included in `WorkerProcessCommandLine` so logs and
 diagnostics can report the launch command without exposing the secret.
 
+All launch-variable names live in the shared Contracts
+`WorkerLaunchEnvironment` class and are consumed by both the launcher and the
+worker. The launcher always exports all six values:
+
+| Environment variable | Gateway source | Worker default when missing/invalid |
+|---|---|---|
+| `MXGATEWAY_WORKER_NONCE` | `WorkerProcessLaunchRequest.Nonce` | None; bootstrap fails because the nonce is required |
+| `MXGATEWAY_WORKER_PIPE_CONNECT_ATTEMPT_TIMEOUT_MS` | `MxGateway:Worker:PipeConnectAttemptTimeoutMilliseconds` | `2000` ms |
+| `MXGATEWAY_WORKER_WRITE_COMPLETION_WAIT_MS` | `MxGateway:Worker:WriteCompletionWaitMilliseconds` | `1500` ms |
+| `MXGATEWAY_EVENT_QUEUE_CAPACITY` | `MxGateway:Worker:EventQueueCapacity` | `10000` events |
+| `MXGATEWAY_ALARM_POLL_INTERVAL_MS` | `MxGateway:Alarms:PollIntervalMilliseconds` | `500` ms |
+| `MXGATEWAY_ALARM_MAX_ALARMS_PER_FETCH` | `MxGateway:Alarms:MaxAlarmsPerFetch` | `1024` alarms |
+
+The write-completion wait applies to the four single-item write variants:
+`Write`, `Write2`, `WriteSecured`, and `WriteSecured2`. Bulk writes report COM
+acceptance per entry and do not wait for `OnWriteComplete` rows.
+
 ## Validation And Cleanup
 
 Before starting the process, the launcher validates that the configured worker
@@ -44,11 +61,8 @@ process remains alive. The policy is configured by
 `WorkerOptions.StartupProbeRetryDelayMilliseconds`; the retry counter is
 recorded as `mxgateway.retries.attempted` with `area=worker_startup`.
 
-The launcher also passes
+The worker uses the exported pipe-attempt value inside its own bounded Polly
-`MXGATEWAY_WORKER_PIPE_CONNECT_ATTEMPT_TIMEOUT_MS` to the worker process from
+retry loop.
-`WorkerOptions.PipeConnectAttemptTimeoutMilliseconds`. The worker uses that
-value as the per-attempt named-pipe connect timeout inside its own bounded
-Polly retry loop.
 
 If startup fails or exceeds `WorkerOptions.StartupTimeoutSeconds`, the launcher
 kills the worker process tree, disposes the process handle, disposes the

src/ZB.MOM.WW.MxGateway.Contracts/WorkerLaunchEnvironment.cs

@@ -0,0 +1,25 @@
+namespace ZB.MOM.WW.MxGateway.Contracts;
+
+/// <summary>Names of environment variables shared by the gateway worker launcher and worker process.</summary>
+public static class WorkerLaunchEnvironment
+{
+    /// <summary>Bootstrap nonce used to authenticate the worker handshake.</summary>
+    public const string WorkerNonce = "MXGATEWAY_WORKER_NONCE";
+
+    /// <summary>Per-attempt named-pipe connection timeout in milliseconds.</summary>
+    public const string PipeConnectAttemptTimeoutMilliseconds =
+        "MXGATEWAY_WORKER_PIPE_CONNECT_ATTEMPT_TIMEOUT_MS";
+
+    /// <summary>Bounded wait for a Write/Write2/WriteSecured/WriteSecured2 completion callback in milliseconds.</summary>
+    public const string WriteCompletionWaitMilliseconds =
+        "MXGATEWAY_WORKER_WRITE_COMPLETION_WAIT_MS";
+
+    /// <summary>Capacity of the worker's outbound MXAccess event queue.</summary>
+    public const string EventQueueCapacity = "MXGATEWAY_EVENT_QUEUE_CAPACITY";
+
+    /// <summary>Worker alarm polling cadence in milliseconds.</summary>
+    public const string AlarmPollIntervalMilliseconds = "MXGATEWAY_ALARM_POLL_INTERVAL_MS";
+
+    /// <summary>Maximum alarm records requested in one current-alarm fetch.</summary>
+    public const string MaxAlarmsPerFetch = "MXGATEWAY_ALARM_MAX_ALARMS_PER_FETCH";
+}

src/ZB.MOM.WW.MxGateway.Contracts/ZB.MOM.WW.MxGateway.Contracts.csproj

@@ -37,7 +37,9 @@
          the wire-identical Galaxy types from the ZB.MOM.WW.GalaxyRepository package. This proto is
          still the generation source of truth for the language clients (Go/Rust/Java/Python compile it
          by path; the .NET client consumes Contracts.Proto.Galaxy.* via this project reference) and for
-         clients/proto/proto-inputs.json. Removing it breaks all five clients — do not delete. -->
+         clients/proto/proto-inputs.json. GalaxyContractParityTests normalizes its descriptor against
+         the descriptor served by the package and fails on wire drift. Removing it breaks all five
+         clients — do not delete. -->
     <Protobuf Include="Protos\galaxy_repository.proto" ProtoRoot="Protos" OutputDir="Generated" GrpcOutputDir="Generated" GrpcServices="Both" />
   </ItemGroup>
 

src/ZB.MOM.WW.MxGateway.Server/Workers/WorkerProcessLauncher.cs

@@ -2,6 +2,7 @@ using System.Diagnostics;
 using Microsoft.Extensions.Logging;
 using Microsoft.Extensions.Logging.Abstractions;
 using Microsoft.Extensions.Options;
+using ZB.MOM.WW.MxGateway.Contracts;
 using ZB.MOM.WW.MxGateway.Server.Configuration;
 using ZB.MOM.WW.MxGateway.Server.Metrics;
 using Polly;
@@ -15,41 +16,47 @@ namespace ZB.MOM.WW.MxGateway.Server.Workers;
 public sealed class WorkerProcessLauncher : IWorkerProcessLauncher
 {
     /// <summary>Environment variable for worker nonce.</summary>
-    public const string WorkerNonceEnvironmentVariableName = "MXGATEWAY_WORKER_NONCE";
+    [Obsolete("Use WorkerLaunchEnvironment.WorkerNonce.")]
+    public const string WorkerNonceEnvironmentVariableName = WorkerLaunchEnvironment.WorkerNonce;
 
     /// <summary>Environment variable for worker pipe connect attempt timeout.</summary>
+    [Obsolete("Use WorkerLaunchEnvironment.PipeConnectAttemptTimeoutMilliseconds.")]
     public const string WorkerPipeConnectAttemptTimeoutEnvironmentVariableName =
-        "MXGATEWAY_WORKER_PIPE_CONNECT_ATTEMPT_TIMEOUT_MS";
+        WorkerLaunchEnvironment.PipeConnectAttemptTimeoutMilliseconds;
 
     /// <summary>
     /// Conveys MxGateway:Worker:WriteCompletionWaitMilliseconds to the worker:
-    /// the bounded wait for the OnWriteComplete callback on
+    /// the bounded wait for the OnWriteComplete callback on Write, Write2,
-    /// WriteSecured/WriteSecured2 replies. 0 disables the wait.
+    /// WriteSecured, and WriteSecured2 replies. 0 disables the wait.
     /// </summary>
+    [Obsolete("Use WorkerLaunchEnvironment.WriteCompletionWaitMilliseconds.")]
     public const string WorkerWriteCompletionWaitEnvironmentVariableName =
-        "MXGATEWAY_WORKER_WRITE_COMPLETION_WAIT_MS";
+        WorkerLaunchEnvironment.WriteCompletionWaitMilliseconds;
 
     /// <summary>
     /// Conveys MxGateway:Alarms:PollIntervalMilliseconds to the worker: the
     /// cadence at which the worker's STA polls the AVEVA alarm consumer.
     /// </summary>
+    [Obsolete("Use WorkerLaunchEnvironment.AlarmPollIntervalMilliseconds.")]
     public const string WorkerAlarmPollIntervalEnvironmentVariableName =
-        "MXGATEWAY_ALARM_POLL_INTERVAL_MS";
+        WorkerLaunchEnvironment.AlarmPollIntervalMilliseconds;
 
     /// <summary>
     /// Conveys MxGateway:Alarms:MaxAlarmsPerFetch to the worker: the cap
     /// passed to GetXmlCurrentAlarms2, which is also the record count at
     /// which the worker treats a fetch as truncated.
     /// </summary>
+    [Obsolete("Use WorkerLaunchEnvironment.MaxAlarmsPerFetch.")]
     public const string WorkerMaxAlarmsPerFetchEnvironmentVariableName =
-        "MXGATEWAY_ALARM_MAX_ALARMS_PER_FETCH";
+        WorkerLaunchEnvironment.MaxAlarmsPerFetch;
 
     /// <summary>
     /// Conveys MxGateway:Worker:EventQueueCapacity to the worker: the capacity
     /// of the outbound MXAccess event queue, whose overflow faults the session.
     /// </summary>
+    [Obsolete("Use WorkerLaunchEnvironment.EventQueueCapacity.")]
     public const string WorkerEventQueueCapacityEnvironmentVariableName =
-        "MXGATEWAY_EVENT_QUEUE_CAPACITY";
+        WorkerLaunchEnvironment.EventQueueCapacity;
 
     private readonly IWorkerProcessFactory _processFactory;
     private readonly IWorkerStartupProbe _startupProbe;
@@ -204,16 +211,16 @@ public sealed class WorkerProcessLauncher : IWorkerProcessLauncher
             startInfo.ArgumentList.Add(argument);
         }
 
-        startInfo.Environment[WorkerNonceEnvironmentVariableName] = request.Nonce;
+        startInfo.Environment[WorkerLaunchEnvironment.WorkerNonce] = request.Nonce;
-        startInfo.Environment[WorkerPipeConnectAttemptTimeoutEnvironmentVariableName] =
+        startInfo.Environment[WorkerLaunchEnvironment.PipeConnectAttemptTimeoutMilliseconds] =
             _workerOptions.PipeConnectAttemptTimeoutMilliseconds.ToString(System.Globalization.CultureInfo.InvariantCulture);
-        startInfo.Environment[WorkerWriteCompletionWaitEnvironmentVariableName] =
+        startInfo.Environment[WorkerLaunchEnvironment.WriteCompletionWaitMilliseconds] =
             _workerOptions.WriteCompletionWaitMilliseconds.ToString(System.Globalization.CultureInfo.InvariantCulture);
-        startInfo.Environment[WorkerEventQueueCapacityEnvironmentVariableName] =
+        startInfo.Environment[WorkerLaunchEnvironment.EventQueueCapacity] =
             _workerOptions.EventQueueCapacity.ToString(System.Globalization.CultureInfo.InvariantCulture);
-        startInfo.Environment[WorkerAlarmPollIntervalEnvironmentVariableName] =
+        startInfo.Environment[WorkerLaunchEnvironment.AlarmPollIntervalMilliseconds] =
             _alarmsOptions.PollIntervalMilliseconds.ToString(System.Globalization.CultureInfo.InvariantCulture);
-        startInfo.Environment[WorkerMaxAlarmsPerFetchEnvironmentVariableName] =
+        startInfo.Environment[WorkerLaunchEnvironment.MaxAlarmsPerFetch] =
             _alarmsOptions.MaxAlarmsPerFetch.ToString(System.Globalization.CultureInfo.InvariantCulture);
 
         commandLine = new WorkerProcessCommandLine(executablePath, arguments);

src/ZB.MOM.WW.MxGateway.Tests/Contracts/GalaxyContractParityTests.cs

@@ -0,0 +1,100 @@
+using Google.Protobuf;
+using Google.Protobuf.Reflection;
+using RetainedGalaxyReflection = ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxy.GalaxyRepositoryReflection;
+using ServedGalaxyReflection = ZB.MOM.WW.GalaxyRepository.Grpc.GalaxyRepositoryReflection;
+
+namespace ZB.MOM.WW.MxGateway.Tests.Contracts;
+
+public sealed class GalaxyContractParityTests
+{
+    /// <summary>Guards the retained client proto against drift from the descriptor served by the gateway.</summary>
+    [Fact]
+    public void RetainedClientDescriptor_MatchesServedGatewayDescriptor()
+    {
+        FileDescriptorProto retained = Normalize(RetainedGalaxyReflection.Descriptor);
+        FileDescriptorProto served = Normalize(ServedGalaxyReflection.Descriptor);
+
+        AssertEquivalentDescriptors(retained, served);
+    }
+
+    /// <summary>Proves descriptor drift diagnostics name the first differing protobuf message.</summary>
+    [Fact]
+    public void DescriptorComparison_WhenMessageDiffers_ReportsDifferingMessage()
+    {
+        FileDescriptorProto retained = Normalize(RetainedGalaxyReflection.Descriptor);
+        FileDescriptorProto changed = retained.Clone();
+        DescriptorProto changedMessage = changed.MessageType.First(message => message.Field.Count > 0);
+        changedMessage.Field[0].Name += "_changed";
+
+        Xunit.Sdk.XunitException exception = Assert.Throws<Xunit.Sdk.XunitException>(
+            () => AssertEquivalentDescriptors(retained, changed));
+
+        Assert.Contains(changedMessage.Name, exception.Message, StringComparison.Ordinal);
+    }
+
+    private static FileDescriptorProto Normalize(FileDescriptor descriptor)
+    {
+        FileDescriptorProto proto = descriptor.ToProto();
+        proto.SourceCodeInfo = null;
+        proto.Name = string.Empty;
+        if (proto.Options is not null)
+        {
+            proto.Options.CsharpNamespace = string.Empty;
+        }
+
+        return proto;
+    }
+
+    private static void AssertEquivalentDescriptors(FileDescriptorProto expected, FileDescriptorProto actual)
+    {
+        byte[] expectedBytes = SerializeDeterministically(expected);
+        byte[] actualBytes = SerializeDeterministically(actual);
+        if (expectedBytes.AsSpan().SequenceEqual(actualBytes))
+        {
+            return;
+        }
+
+        throw new Xunit.Sdk.XunitException(
+            $"Galaxy Repository descriptors differ at {DescribeFirstDifference(expected, actual)}.");
+    }
+
+    private static string DescribeFirstDifference(FileDescriptorProto expected, FileDescriptorProto actual)
+    {
+        int comparableMessageCount = Math.Min(expected.MessageType.Count, actual.MessageType.Count);
+        for (int index = 0; index < comparableMessageCount; index++)
+        {
+            DescriptorProto expectedMessage = expected.MessageType[index];
+            DescriptorProto actualMessage = actual.MessageType[index];
+            if (!SerializeDeterministically(expectedMessage).AsSpan()
+                    .SequenceEqual(SerializeDeterministically(actualMessage)))
+            {
+                string messageName = string.IsNullOrEmpty(expectedMessage.Name)
+                    ? actualMessage.Name
+                    : expectedMessage.Name;
+                return $"message '{Qualify(expected.Package, messageName)}'";
+            }
+        }
+
+        if (expected.MessageType.Count != actual.MessageType.Count)
+        {
+            return "the top-level message list";
+        }
+
+        return "the normalized file descriptor";
+    }
+
+    private static string Qualify(string package, string symbol) =>
+        string.IsNullOrEmpty(package) ? symbol : package + "." + symbol;
+
+    private static byte[] SerializeDeterministically(IMessage message)
+    {
+        using MemoryStream stream = new();
+        using CodedOutputStream output = new(stream, leaveOpen: true)
+        {
+            Deterministic = true,
+        };
+        message.WriteTo(output);
+        output.Flush();
+        return stream.ToArray();
+    }
+}

src/ZB.MOM.WW.MxGateway.Tests/Gateway/Workers/WorkerProcessLauncherTests.cs

@@ -14,6 +14,16 @@ public sealed class WorkerProcessLauncherTests
     private const string PipeName = "mxaccess-gateway-123-session-1";
     private const string Nonce = "super-secret-nonce";
 
+    private static readonly string[] RequiredLaunchEnvironmentVariables =
+    [
+        WorkerLaunchEnvironment.WorkerNonce,
+        WorkerLaunchEnvironment.PipeConnectAttemptTimeoutMilliseconds,
+        WorkerLaunchEnvironment.WriteCompletionWaitMilliseconds,
+        WorkerLaunchEnvironment.EventQueueCapacity,
+        WorkerLaunchEnvironment.AlarmPollIntervalMilliseconds,
+        WorkerLaunchEnvironment.MaxAlarmsPerFetch,
+    ];
+
     /// <summary>Verifies that a valid worker executable starts with correct bootstrap arguments and nonce environment variable.</summary>
     /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
@@ -38,33 +48,38 @@ public sealed class WorkerProcessLauncherTests
         Assert.Equal(
             ["--session-id", SessionId, "--pipe-name", PipeName, "--protocol-version", "1"],
             processFactory.LastStartInfo.ArgumentList);
-        Assert.Equal(Nonce, processFactory.LastStartInfo.Environment[WorkerProcessLauncher.WorkerNonceEnvironmentVariableName]);
+        Assert.Equal(Nonce, processFactory.LastStartInfo.Environment[WorkerLaunchEnvironment.WorkerNonce]);
         Assert.Equal(
             "2000",
             processFactory.LastStartInfo.Environment[
-                WorkerProcessLauncher.WorkerPipeConnectAttemptTimeoutEnvironmentVariableName]);
+                WorkerLaunchEnvironment.PipeConnectAttemptTimeoutMilliseconds]);
         Assert.Equal(
             "1500",
             processFactory.LastStartInfo.Environment[
-                WorkerProcessLauncher.WorkerWriteCompletionWaitEnvironmentVariableName]);
+                WorkerLaunchEnvironment.WriteCompletionWaitMilliseconds]);
         // The worker sizes its outbound event queue from the launch environment;
         // the queue has no drop policy, so this capacity is the session's burst
         // headroom rather than a throttle.
         Assert.Equal(
             "10000",
             processFactory.LastStartInfo.Environment[
-                WorkerProcessLauncher.WorkerEventQueueCapacityEnvironmentVariableName]);
+                WorkerLaunchEnvironment.EventQueueCapacity]);
         // MxGateway:Alarms defaults reach the worker's alarm poll loop and its
         // GetXmlCurrentAlarms2 cap (which is also its truncation threshold)
         // through the launch environment, not the command line.
         Assert.Equal(
             "500",
             processFactory.LastStartInfo.Environment[
-                WorkerProcessLauncher.WorkerAlarmPollIntervalEnvironmentVariableName]);
+                WorkerLaunchEnvironment.AlarmPollIntervalMilliseconds]);
         Assert.Equal(
             "1024",
             processFactory.LastStartInfo.Environment[
-                WorkerProcessLauncher.WorkerMaxAlarmsPerFetchEnvironmentVariableName]);
+                WorkerLaunchEnvironment.MaxAlarmsPerFetch]);
+        Assert.All(
+            RequiredLaunchEnvironmentVariables,
+            variable => Assert.True(
+                processFactory.LastStartInfo.Environment.ContainsKey(variable),
+                $"Worker launch environment is missing required variable '{variable}'."));
         Assert.DoesNotContain(Nonce, handle.CommandLine.ToString(), StringComparison.Ordinal);
         Assert.DoesNotContain(Nonce, string.Join(" ", handle.CommandLine.Arguments), StringComparison.Ordinal);
         Assert.False(pipeReservation.DisposeCalled);
@@ -94,7 +109,7 @@ public sealed class WorkerProcessLauncherTests
         Assert.Equal(
             "65536",
             processFactory.LastStartInfo.Environment[
-                WorkerProcessLauncher.WorkerEventQueueCapacityEnvironmentVariableName]);
+                WorkerLaunchEnvironment.EventQueueCapacity]);
     }
 
     /// <summary>Verifies that a failed startup probe kills and disposes the worker process.</summary>

src/ZB.MOM.WW.MxGateway.Worker.Tests/Bootstrap/WorkerApplicationTests.cs

@@ -137,7 +137,7 @@ public sealed class WorkerApplicationTests
     private static MemoryWorkerEnvironment CreateEnvironment(string nonce)
     {
         MemoryWorkerEnvironment environment = new();
-        environment.Set(WorkerOptions.NonceEnvironmentVariableName, nonce);
+        environment.Set(WorkerLaunchEnvironment.WorkerNonce, nonce);
         return environment;
     }
 

src/ZB.MOM.WW.MxGateway.Worker.Tests/Bootstrap/WorkerOptionsParserTests.cs

@@ -115,7 +115,7 @@ public sealed class WorkerOptionsParserTests
     private static MemoryWorkerEnvironment CreateEnvironment(string nonce)
     {
         MemoryWorkerEnvironment environment = new();
-        environment.Set(WorkerOptions.NonceEnvironmentVariableName, nonce);
+        environment.Set(WorkerLaunchEnvironment.WorkerNonce, nonce);
         return environment;
     }
 }

src/ZB.MOM.WW.MxGateway.Worker.Tests/MxAccess/MxAccessEventQueueTests.cs

@@ -4,6 +4,7 @@ using System.Diagnostics;
 using System.Threading;
 using System.Threading.Tasks;
 using Google.Protobuf.WellKnownTypes;
+using ZB.MOM.WW.MxGateway.Contracts;
 using ZB.MOM.WW.MxGateway.Contracts.Proto;
 using ZB.MOM.WW.MxGateway.Worker.MxAccess;
 
@@ -609,11 +610,11 @@ public sealed class MxAccessEventQueueTests
         int expected)
     {
         string? original = Environment.GetEnvironmentVariable(
-            MxAccessEventQueue.CapacityEnvironmentVariableName);
+            WorkerLaunchEnvironment.EventQueueCapacity);
         try
         {
             Environment.SetEnvironmentVariable(
-                MxAccessEventQueue.CapacityEnvironmentVariableName,
+                WorkerLaunchEnvironment.EventQueueCapacity,
                 environmentValue);
 
             Assert.Equal(expected, MxAccessEventQueue.ResolveCapacity());
@@ -621,7 +622,7 @@ public sealed class MxAccessEventQueueTests
         finally
         {
             Environment.SetEnvironmentVariable(
-                MxAccessEventQueue.CapacityEnvironmentVariableName,
+                WorkerLaunchEnvironment.EventQueueCapacity,
                 original);
         }
     }
@@ -635,11 +636,11 @@ public sealed class MxAccessEventQueueTests
     public void Constructor_WithResolvedCapacity_UsesEnvironmentValue()
     {
         string? original = Environment.GetEnvironmentVariable(
-            MxAccessEventQueue.CapacityEnvironmentVariableName);
+            WorkerLaunchEnvironment.EventQueueCapacity);
         try
         {
             Environment.SetEnvironmentVariable(
-                MxAccessEventQueue.CapacityEnvironmentVariableName,
+                WorkerLaunchEnvironment.EventQueueCapacity,
                 "2500");
 
             MxAccessEventQueue queue = new(MxAccessEventQueue.ResolveCapacity());
@@ -649,7 +650,7 @@ public sealed class MxAccessEventQueueTests
         finally
         {
             Environment.SetEnvironmentVariable(
-                MxAccessEventQueue.CapacityEnvironmentVariableName,
+                WorkerLaunchEnvironment.EventQueueCapacity,
                 original);
         }
     }

src/ZB.MOM.WW.MxGateway.Worker.Tests/MxAccess/MxAccessStaSessionTests.cs

@@ -3,6 +3,7 @@ using System.Collections.Generic;
 using System.Runtime.InteropServices;
 using System.Threading;
 using System.Threading.Tasks;
+using ZB.MOM.WW.MxGateway.Contracts;
 using ZB.MOM.WW.MxGateway.Contracts.Proto;
 using ZB.MOM.WW.MxGateway.Worker.MxAccess;
 using ZB.MOM.WW.MxGateway.Worker.Sta;
@@ -35,11 +36,11 @@ public sealed class MxAccessStaSessionTests
     public void ResolveWriteCompletionTimeout_ParsesEnvironmentValue(string? rawValue, int? expectedMilliseconds)
     {
         string? original = Environment.GetEnvironmentVariable(
-            MxAccessStaSession.WriteCompletionWaitEnvironmentVariableName);
+            WorkerLaunchEnvironment.WriteCompletionWaitMilliseconds);
         try
         {
             Environment.SetEnvironmentVariable(
-                MxAccessStaSession.WriteCompletionWaitEnvironmentVariableName,
+                WorkerLaunchEnvironment.WriteCompletionWaitMilliseconds,
                 rawValue);
 
             TimeSpan resolved = MxAccessStaSession.ResolveWriteCompletionTimeout();
@@ -52,7 +53,7 @@ public sealed class MxAccessStaSessionTests
         finally
         {
             Environment.SetEnvironmentVariable(
-                MxAccessStaSession.WriteCompletionWaitEnvironmentVariableName,
+                WorkerLaunchEnvironment.WriteCompletionWaitMilliseconds,
                 original);
         }
     }
@@ -83,11 +84,11 @@ public sealed class MxAccessStaSessionTests
         int expectedMilliseconds)
     {
         string? original = Environment.GetEnvironmentVariable(
-            MxAccessStaSession.AlarmPollIntervalEnvironmentVariableName);
+            WorkerLaunchEnvironment.AlarmPollIntervalMilliseconds);
         try
         {
             Environment.SetEnvironmentVariable(
-                MxAccessStaSession.AlarmPollIntervalEnvironmentVariableName,
+                WorkerLaunchEnvironment.AlarmPollIntervalMilliseconds,
                 environmentValue);
 
             Assert.Equal(
@@ -97,7 +98,7 @@ public sealed class MxAccessStaSessionTests
         finally
         {
             Environment.SetEnvironmentVariable(
-                MxAccessStaSession.AlarmPollIntervalEnvironmentVariableName,
+                WorkerLaunchEnvironment.AlarmPollIntervalMilliseconds,
                 original);
         }
     }

src/ZB.MOM.WW.MxGateway.Worker.Tests/MxAccess/WnWrapAlarmConsumerXmlTests.cs

@@ -3,6 +3,7 @@ using System.Collections.Generic;
 using System.Linq;
 using System.Reflection;
 using System.Threading;
+using ZB.MOM.WW.MxGateway.Contracts;
 using ZB.MOM.WW.MxGateway.Worker.MxAccess;
 
 namespace ZB.MOM.WW.MxGateway.Worker.Tests.MxAccess;
@@ -506,11 +507,11 @@ public sealed class WnWrapAlarmConsumerXmlTests
         int expected)
     {
         string? original = Environment.GetEnvironmentVariable(
-            WnWrapAlarmConsumer.MaxAlarmsPerFetchEnvironmentVariableName);
+            WorkerLaunchEnvironment.MaxAlarmsPerFetch);
         try
         {
             Environment.SetEnvironmentVariable(
-                WnWrapAlarmConsumer.MaxAlarmsPerFetchEnvironmentVariableName,
+                WorkerLaunchEnvironment.MaxAlarmsPerFetch,
                 environmentValue);
 
             Assert.Equal(expected, WnWrapAlarmConsumer.ResolveMaxAlarmsPerFetch());
@@ -518,7 +519,7 @@ public sealed class WnWrapAlarmConsumerXmlTests
         finally
         {
             Environment.SetEnvironmentVariable(
-                WnWrapAlarmConsumer.MaxAlarmsPerFetchEnvironmentVariableName,
+                WorkerLaunchEnvironment.MaxAlarmsPerFetch,
                 original);
         }
     }

src/ZB.MOM.WW.MxGateway.Worker/Bootstrap/WorkerOptions.cs

@@ -1,10 +1,13 @@
 namespace ZB.MOM.WW.MxGateway.Worker.Bootstrap;
 
+using ZB.MOM.WW.MxGateway.Contracts;
+
 /// <summary>Worker bootstrap options passed via environment variables and named pipes.</summary>
 public sealed class WorkerOptions
 {
     /// <summary>Environment variable name for the worker nonce.</summary>
-    public const string NonceEnvironmentVariableName = "MXGATEWAY_WORKER_NONCE";
+    [Obsolete("Use WorkerLaunchEnvironment.WorkerNonce.")]
+    public const string NonceEnvironmentVariableName = WorkerLaunchEnvironment.WorkerNonce;
 
     /// <summary>Initializes worker options from a bootstrap handshake.</summary>
     /// <param name="sessionId">Identifier of the session.</param>

src/ZB.MOM.WW.MxGateway.Worker/Bootstrap/WorkerOptionsParser.cs

@@ -75,7 +75,7 @@ public sealed class WorkerOptionsParser
                 [$"Unsupported protocol version '{protocolVersionText}'."]);
         }
 
-        string? nonce = _environment.GetEnvironmentVariable(WorkerOptions.NonceEnvironmentVariableName);
+        string? nonce = _environment.GetEnvironmentVariable(WorkerLaunchEnvironment.WorkerNonce);
 
         if (string.IsNullOrWhiteSpace(nonce))
         {

src/ZB.MOM.WW.MxGateway.Worker/Ipc/WorkerPipeClient.cs

@@ -4,6 +4,7 @@ using System.IO;
 using System.IO.Pipes;
 using System.Threading;
 using System.Threading.Tasks;
+using ZB.MOM.WW.MxGateway.Contracts;
 using ZB.MOM.WW.MxGateway.Worker.Bootstrap;
 using Polly;
 using Polly.Retry;
@@ -22,8 +23,9 @@ public sealed class WorkerPipeClient : IWorkerPipeClient
     public const int DefaultConnectAttemptTimeoutMilliseconds = 2000;
 
     /// <summary>Environment variable for overriding the per-attempt connection timeout.</summary>
+    [Obsolete("Use WorkerLaunchEnvironment.PipeConnectAttemptTimeoutMilliseconds.")]
     public const string ConnectAttemptTimeoutEnvironmentVariableName =
-        "MXGATEWAY_WORKER_PIPE_CONNECT_ATTEMPT_TIMEOUT_MS";
+        WorkerLaunchEnvironment.PipeConnectAttemptTimeoutMilliseconds;
 
     private readonly int _connectTimeoutMilliseconds;
     private readonly int _connectAttemptTimeoutMilliseconds;
@@ -255,7 +257,8 @@ public sealed class WorkerPipeClient : IWorkerPipeClient
 
     private static int ResolveDefaultConnectAttemptTimeoutMilliseconds()
     {
-        string? configuredValue = Environment.GetEnvironmentVariable(ConnectAttemptTimeoutEnvironmentVariableName);
+        string? configuredValue = Environment.GetEnvironmentVariable(
+            WorkerLaunchEnvironment.PipeConnectAttemptTimeoutMilliseconds);
         return int.TryParse(configuredValue, out int milliseconds) && milliseconds > 0
             ? milliseconds
             : DefaultConnectAttemptTimeoutMilliseconds;

src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessEventQueue.cs

@@ -5,6 +5,7 @@ using System.Threading;
 using System.Threading.Tasks;
 using Google.Protobuf;
 using Google.Protobuf.WellKnownTypes;
+using ZB.MOM.WW.MxGateway.Contracts;
 using ZB.MOM.WW.MxGateway.Contracts.Proto;
 
 namespace ZB.MOM.WW.MxGateway.Worker.MxAccess;
@@ -45,8 +46,6 @@ public sealed class MxAccessEventQueue
     ///     <see cref="DefaultCapacity"/> — a bad environment value must never
     ///     keep the session from starting.
     /// </summary>
-    internal const string CapacityEnvironmentVariableName = "MXGATEWAY_EVENT_QUEUE_CAPACITY";
-
     /// <summary>
     ///     Floor on the resolved capacity. Mirrors the gateway-side
     ///     <c>MxGateway:Worker:EventQueueCapacity</c> minimum so a value that
@@ -140,7 +139,7 @@ public sealed class MxAccessEventQueue
     /// <returns>The capacity to construct the outbound event queue with.</returns>
     internal static int ResolveCapacity()
     {
-        string? value = Environment.GetEnvironmentVariable(CapacityEnvironmentVariableName);
+        string? value = Environment.GetEnvironmentVariable(WorkerLaunchEnvironment.EventQueueCapacity);
         return int.TryParse(
                 value,
                 NumberStyles.Integer,

src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessStaSession.cs

@@ -3,6 +3,7 @@ using System.Collections.Generic;
 using System.Diagnostics;
 using System.Threading;
 using System.Threading.Tasks;
+using ZB.MOM.WW.MxGateway.Contracts;
 using ZB.MOM.WW.MxGateway.Contracts.Proto;
 using ZB.MOM.WW.MxGateway.Worker.Conversion;
 using ZB.MOM.WW.MxGateway.Worker.Sta;
@@ -16,17 +17,11 @@ public sealed class MxAccessStaSession : IWorkerRuntimeSession
     ///     MxGateway:Worker:WriteCompletionWaitMilliseconds. 0 disables the
     ///     write-completion wait (pure fire-and-forget replies).
     /// </summary>
-    internal const string WriteCompletionWaitEnvironmentVariableName =
-        "MXGATEWAY_WORKER_WRITE_COMPLETION_WAIT_MS";
-
     /// <summary>
     ///     Environment variable the gateway's WorkerProcessLauncher sets from
     ///     MxGateway:Alarms:PollIntervalMilliseconds. A missing or invalid
     ///     value falls back to <see cref="DefaultAlarmPollInterval"/>.
     /// </summary>
-    internal const string AlarmPollIntervalEnvironmentVariableName =
-        "MXGATEWAY_ALARM_POLL_INTERVAL_MS";
-
     /// <summary>
     ///     Floor on the resolved alarm poll cadence. Mirrors the gateway-side
     ///     MxGateway:Alarms:PollIntervalMilliseconds minimum so a value that
@@ -211,7 +206,7 @@ public sealed class MxAccessStaSession : IWorkerRuntimeSession
     /// </summary>
     internal static TimeSpan ResolveWriteCompletionTimeout()
     {
-        string? value = Environment.GetEnvironmentVariable(WriteCompletionWaitEnvironmentVariableName);
+        string? value = Environment.GetEnvironmentVariable(WorkerLaunchEnvironment.WriteCompletionWaitMilliseconds);
         return int.TryParse(
                 value,
                 System.Globalization.NumberStyles.Integer,
@@ -233,7 +228,7 @@ public sealed class MxAccessStaSession : IWorkerRuntimeSession
     /// <returns>The cadence the alarm poll loop waits between polls.</returns>
     internal static TimeSpan ResolveAlarmPollInterval()
     {
-        string? value = Environment.GetEnvironmentVariable(AlarmPollIntervalEnvironmentVariableName);
+        string? value = Environment.GetEnvironmentVariable(WorkerLaunchEnvironment.AlarmPollIntervalMilliseconds);
         if (!int.TryParse(
                 value,
                 System.Globalization.NumberStyles.Integer,

src/ZB.MOM.WW.MxGateway.Worker/MxAccess/WnWrapAlarmConsumer.cs

@@ -5,6 +5,7 @@ using System.Globalization;
 using System.Runtime.InteropServices;
 using System.Xml;
 using WNWRAPCONSUMERLib;
+using ZB.MOM.WW.MxGateway.Contracts;
 
 namespace ZB.MOM.WW.MxGateway.Worker.MxAccess;
 
@@ -75,9 +76,6 @@ public sealed class WnWrapAlarmConsumer : IMxAccessAlarmConsumer
     ///     <see cref="DefaultMaxAlarmsPerFetch"/> — a bad environment value
     ///     must never keep the alarm consumer from starting.
     /// </summary>
-    internal const string MaxAlarmsPerFetchEnvironmentVariableName =
-        "MXGATEWAY_ALARM_MAX_ALARMS_PER_FETCH";
-
     /// <summary>
     ///     Minimum gap between truncated-fetch warnings. A galaxy parked above
     ///     the cap truncates on *every* poll, so an unthrottled warning would
@@ -156,7 +154,7 @@ public sealed class WnWrapAlarmConsumer : IMxAccessAlarmConsumer
     /// <returns>The cap passed to <c>GetXmlCurrentAlarms2</c>.</returns>
     internal static int ResolveMaxAlarmsPerFetch()
     {
-        string? value = Environment.GetEnvironmentVariable(MaxAlarmsPerFetchEnvironmentVariableName);
+        string? value = Environment.GetEnvironmentVariable(WorkerLaunchEnvironment.MaxAlarmsPerFetch);
         return int.TryParse(
                 value,
                 NumberStyles.Integer,