feat(ipc): negotiate worker frame max, add gRPC headroom, bound DrainEvents (IPC-02/03/04 gateway half)

Proto foundation + gateway-side of the size/backpressure pass:

- IPC-02: add GatewayHello.max_frame_bytes (regen Generated/); gateway sends
  its negotiated worker-frame max in the handshake so the worker can adopt it
  instead of a hard-coded default. Worker read-half lands separately.
- IPC-03: give the pipe frame max envelope-overhead headroom above the public
  gRPC cap (WorkerFrameProtocolOptions.EnvelopeOverheadReserveBytes = 64 KiB;
  default Worker.MaxMessageBytes bumped to 16 MiB + reserve), cross-validate the
  headroom at startup, and pre-check command envelope size in WorkerClient so an
  oversized command fails only that correlation (ResourceExhausted) instead of
  faulting the whole session.
- IPC-04: reject DrainEvents max_events above a public ceiling in the request
  validator (worker per-reply cap lands with the worker half).

Docs: GatewayConfiguration, WorkerFrameProtocol, gateway.md.
Tests: headroom validation, DrainEvents bound, oversized-command per-command
failure (pipe-harness, verified on windev).

src/ZB.MOM.WW.MxGateway.Server/Configuration/GatewayOptionsValidator.cs

@@ -1,6 +1,7 @@
 using ZB.MOM.WW.Auth.Abstractions.Ldap;
 using ZB.MOM.WW.Configuration;
 using ZB.MOM.WW.MxGateway.Contracts;
+using ZB.MOM.WW.MxGateway.Server.Workers;
 
 namespace ZB.MOM.WW.MxGateway.Server.Configuration;
 
@@ -46,6 +47,7 @@ public sealed class GatewayOptionsValidator : OptionsValidatorBase<GatewayOption
         ValidateEvents(options.Events, builder);
         ValidateDashboard(options.Dashboard, builder, _isProduction);
         ValidateProtocol(options.Protocol, builder);
+        ValidateFrameSizeHeadroom(options.Worker, options.Protocol, builder);
         ValidateAlarms(options.Alarms, builder);
         ValidateTls(options.Tls, builder);
         ValidateSecurity(options.Security, builder);
@@ -466,6 +468,35 @@ public sealed class GatewayOptionsValidator : OptionsValidatorBase<GatewayOption
         }
     }
 
+    // The worker-frame (pipe) maximum must stay above the public gRPC cap by the envelope-overhead
+    // reserve, otherwise a maximally-sized accepted gRPC payload does not fit one worker frame once
+    // wrapped in a WorkerEnvelope and the outbound write faults the whole session (IPC-03). Fail fast
+    // at startup rather than mid-traffic. Only checked when both knobs are themselves in range so the
+    // message is not doubled up with the individual range errors.
+    private static void ValidateFrameSizeHeadroom(
+        WorkerOptions worker,
+        ProtocolOptions protocol,
+        ValidationBuilder builder)
+    {
+        bool workerInRange = worker.MaxMessageBytes is >= MinimumMaxMessageBytes and <= MaximumMaxMessageBytes;
+        bool grpcInRange = protocol.MaxGrpcMessageBytes is >= MinimumMaxMessageBytes and <= MaximumMaxMessageBytes;
+        if (!workerInRange || !grpcInRange)
+        {
+            return;
+        }
+
+        long requiredWorkerMax =
+            (long)protocol.MaxGrpcMessageBytes + WorkerFrameProtocolOptions.EnvelopeOverheadReserveBytes;
+        if (worker.MaxMessageBytes < requiredWorkerMax)
+        {
+            builder.Add(
+                $"MxGateway:Worker:MaxMessageBytes ({worker.MaxMessageBytes}) must be at least "
+                + $"MxGateway:Protocol:MaxGrpcMessageBytes ({protocol.MaxGrpcMessageBytes}) plus the "
+                + $"{WorkerFrameProtocolOptions.EnvelopeOverheadReserveBytes}-byte worker-frame envelope reserve "
+                + $"(>= {requiredWorkerMax}).");
+        }
+    }
+
     private static void AddIfBlank(string? value, string message, ValidationBuilder builder)
     {
         builder.RequireThat(!string.IsNullOrWhiteSpace(value), message);

src/ZB.MOM.WW.MxGateway.Server/Configuration/WorkerOptions.cs

@@ -33,6 +33,14 @@ public sealed class WorkerOptions
     /// <summary>The grace period in seconds after a heartbeat before considering the worker unresponsive.</summary>
     public int HeartbeatGraceSeconds { get; init; } = 15;
 
-    /// <summary>The maximum message size in bytes for IPC communication.</summary>
-    public int MaxMessageBytes { get; init; } = 16 * 1024 * 1024;
+    /// <summary>
+    /// The maximum worker-frame (pipe) message size in bytes. Must stay at least
+    /// <see cref="Workers.WorkerFrameProtocolOptions.EnvelopeOverheadReserveBytes"/> above
+    /// <see cref="ProtocolOptions.MaxGrpcMessageBytes"/> so a maximally-sized accepted gRPC payload
+    /// still fits one worker frame (IPC-03); the gateway conveys this value to the worker in the
+    /// handshake (<c>GatewayHello.max_frame_bytes</c>, IPC-02). Default is the 16 MB public gRPC cap
+    /// plus that reserve.
+    /// </summary>
+    public int MaxMessageBytes { get; init; } =
+        (16 * 1024 * 1024) + Workers.WorkerFrameProtocolOptions.EnvelopeOverheadReserveBytes;
 }

src/ZB.MOM.WW.MxGateway.Server/Grpc/MxAccessGatewayService.cs

@@ -946,6 +946,7 @@ public sealed class MxAccessGatewayService(
             WorkerClientErrorCode.GatewayShutdown => StatusCode.Cancelled,
             WorkerClientErrorCode.InvalidState => StatusCode.FailedPrecondition,
             WorkerClientErrorCode.ProtocolViolation => StatusCode.Internal,
+            WorkerClientErrorCode.CommandTooLarge => StatusCode.ResourceExhausted,
             _ => StatusCode.Unavailable,
         };
 

src/ZB.MOM.WW.MxGateway.Server/Grpc/MxAccessGrpcRequestValidator.cs

@@ -5,6 +5,13 @@ namespace ZB.MOM.WW.MxGateway.Server.Grpc;
 
 public sealed class MxAccessGrpcRequestValidator
 {
+    // Upper bound on a single DrainEvents request. DrainEvents is a diagnostics RPC that returns
+    // buffered events in one non-streaming reply, so an unbounded max_events could pack the whole
+    // queue into a session-killing frame (IPC-04). The worker independently caps each reply at its
+    // own MaxDrainEventsPerReply; this public bound rejects an obviously-abusive request loudly at
+    // the boundary. max_events = 0 is allowed and means "the worker's default batch cap".
+    private const uint MaxDrainEventsPerRequest = 10_000;
+
     /// <summary>Validates an open session request.</summary>
     /// <param name="request">The request to validate.</param>
     public void ValidateOpenSession(OpenSessionRequest request)
@@ -69,6 +76,14 @@ public sealed class MxAccessGrpcRequestValidator
             throw InvalidArgument(
                 $"Command kind {command.Kind} requires payload {expectedPayload} but received {command.PayloadCase}.");
         }
+
+        // The payload case now matches the kind, so command.DrainEvents is non-null here.
+        if (command.Kind is MxCommandKind.DrainEvents && command.DrainEvents.MaxEvents > MaxDrainEventsPerRequest)
+        {
+            throw InvalidArgument(
+                $"DrainEvents max_events ({command.DrainEvents.MaxEvents}) must not exceed {MaxDrainEventsPerRequest}; "
+                + "use 0 to request the worker default batch cap.");
+        }
     }
 
     private static MxCommand.PayloadOneofCase ExpectedPayload(MxCommandKind kind)

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

@@ -187,7 +187,23 @@ public sealed class WorkerClient : IWorkerClient
 
         try
         {
-            await EnqueueAsync(CreateCommandEnvelope(correlationId, command), cancellationToken).ConfigureAwait(false);
+            WorkerEnvelope commandEnvelope = CreateCommandEnvelope(correlationId, command);
+
+            // Reject an oversized command at the enqueue boundary so only this correlation fails
+            // (ResourceExhausted) rather than the frame reaching the write loop and faulting the whole
+            // session (IPC-03). Command envelopes are the only gateway-authored outbound payload whose
+            // size the caller controls; checking here keeps a MessageTooLarge in the write loop a
+            // genuine desync signal.
+            int envelopeSize = commandEnvelope.CalculateSize();
+            if (envelopeSize > _connection.FrameOptions.MaxMessageBytes)
+            {
+                throw new WorkerClientException(
+                    WorkerClientErrorCode.CommandTooLarge,
+                    $"Worker command {method} serializes to {envelopeSize} bytes, exceeding the negotiated "
+                    + $"worker-frame maximum of {_connection.FrameOptions.MaxMessageBytes} bytes.");
+            }
+
+            await EnqueueAsync(commandEnvelope, cancellationToken).ConfigureAwait(false);
             using CancellationTokenSource timeoutCts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
             Task timeoutTask = Task.Delay(timeout, timeoutCts.Token);
             Task<WorkerCommandReply> replyTask = pendingCommand.Task;
@@ -910,6 +926,10 @@ public sealed class WorkerClient : IWorkerClient
                 SupportedProtocolVersion = _connection.FrameOptions.ProtocolVersion,
                 Nonce = _connection.Nonce,
                 GatewayVersion = typeof(GatewayContractInfo).Assembly.GetName().Version?.ToString() ?? GatewayVersionFallback,
+
+                // Convey the negotiated worker-frame maximum so the worker adopts it instead of a
+                // hard-coded default (IPC-02). Sits above the public gRPC cap by the envelope reserve.
+                MaxFrameBytes = (uint)_connection.FrameOptions.MaxMessageBytes,
             });
     }
 

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

@@ -12,4 +12,9 @@ public enum WorkerClientErrorCode
     GatewayShutdown,
     WriteFailed,
     PendingCommandLimitExceeded,
+
+    // The serialized command envelope exceeds the negotiated worker-frame maximum. Rejected at the
+    // enqueue boundary so only the offending command fails (mapped to ResourceExhausted) instead of
+    // the oversized frame reaching the write loop and faulting the whole session (IPC-03).
+    CommandTooLarge,
 }

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

@@ -10,6 +10,15 @@ public sealed class WorkerFrameProtocolOptions
     /// <summary>Default maximum message size in bytes (16 MB).</summary>
     public const int DefaultMaxMessageBytes = 16 * 1024 * 1024;
 
+    /// <summary>
+    /// Byte margin the worker-frame (pipe) maximum must keep above the public gRPC message cap so a
+    /// gRPC payload accepted at the public boundary always fits inside one worker frame once wrapped
+    /// in a <c>WorkerEnvelope</c> (correlation id, timestamps, oneof framing). Without this headroom
+    /// the pipe max equals the gRPC max and a maximally-sized accepted request faults the whole
+    /// session on the outbound write (IPC-03). 64 KiB is far larger than the fixed envelope overhead.
+    /// </summary>
+    public const int EnvelopeOverheadReserveBytes = 64 * 1024;
+
     /// <summary>
     /// Initializes worker frame protocol options with a session ID.
     /// </summary>

src/ZB.MOM.WW.MxGateway.Server/appsettings.json

@@ -38,7 +38,7 @@
       "ShutdownTimeoutSeconds": 10,
       "HeartbeatIntervalSeconds": 5,
       "HeartbeatGraceSeconds": 15,
-      "MaxMessageBytes": 16777216
+      "MaxMessageBytes": 16842752
     },
     "Sessions": {
       "DefaultCommandTimeoutSeconds": 30,