docs+test(closeout): final-review reservations — stale ACL prose, worker test gaps, config sample fix

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

@@ -168,13 +168,20 @@ public sealed class WorkerPipeSession
             // Closing the transport is what actually ends a pipe read parked in the kernel: on net48
             // NamedPipeClientStream.ReadAsync ignores its CancellationToken, so the message loop's
             // cancellation can never reach one (WRK-31). It is deliberately the LAST teardown step,
-            // because in the ordinary case every frame this session will ever write has completed by
-            // the time control reaches here: WorkerFrameWriter.WriteAsync signals only after the
-            // frame is written AND flushed, and each exit path awaits its final write before
-            // unwinding — the shutdown ack and shutdown-timeout fault inside the loop's dispatch, the
-            // event-drain and oversized-event faults inside the drain task the loop awaits, the
-            // watchdog fault inside the heartbeat task the loop awaits, and the handshake fault
-            // inside CompleteStartupHandshakeAsync's catch.
+            // because in the ordinary case every frame this session will ever write has been written
+            // AND flushed by the time control reaches here: WorkerFrameWriter.WriteAsync signals only
+            // after both, and each exit path awaits its final write before unwinding — the shutdown
+            // ack and shutdown-timeout fault inside the loop's dispatch, the event-drain and
+            // oversized-event faults inside the drain task the loop awaits, the watchdog fault inside
+            // the heartbeat task the loop awaits, and the handshake fault inside
+            // CompleteStartupHandshakeAsync's catch.
+            //
+            // That is a statement about frames, not about the writer being idle. A caller that
+            // returned on its own completion while another drainer held the write lock leaves a
+            // detached lock acquisition behind (WorkerFrameWriter.DetachLockWait), so a drain pass can
+            // still be scheduled after every caller has unwound. It is harmless here — the queues are
+            // empty by then, and a pass with nothing to dequeue writes and flushes nothing — but the
+            // invariant to rely on is "no frame is left undelivered", not "no writer work remains".
             //
             // "Ordinary" is the honest word, not "always": the loop's wait on the heartbeat and
             // drain tasks is budgeted (BackgroundTaskStopTimeout), and a stream write is genuinely

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

@@ -77,10 +77,15 @@ public interface IAlarmCommandHandler : IDisposable
     ///     rather than read from a separate property, both so the pair comes from
     ///     one atomic consumer read and because it is the only carrier left once
     ///     <paramref name="alarmFilterPrefix"/> (or an empty galaxy) filters the
-    ///     records down to none. <see langword="false"/> when there is no active
-    ///     subscription: no fetch has happened, so nothing is capped.
+    ///     records down to none. Never assigned when there is no active
+    ///     subscription — that case throws rather than reporting an empty,
+    ///     never-capped set, so a query issued before <c>SubscribeAlarms</c> is a
+    ///     caller error and not a silent all-clear.
     /// </param>
     /// <returns>The currently active alarms matching the filter.</returns>
+    /// <exception cref="InvalidOperationException">
+    ///     Thrown when there is no active subscription.
+    /// </exception>
     IReadOnlyList<ActiveAlarmSnapshot> QueryActive(string? alarmFilterPrefix, out bool snapshotTruncated);
 
     /// <summary>