feat(clients): CLI-15 surface ReplayGap reconnect sentinel as typed signal (4/5 clients)

The gateway emits a ReplayGap sentinel MxEvent at the head of a StreamEvents
stream resumed via after_worker_sequence when the requested cursor predates the
oldest retained event. Clients previously ignored it, silently mis-treating a
lossy resume as continuous. Each client now surfaces the sentinel as a distinct,
typed, non-terminal signal (never synthesized, never swallowed) so a consumer can
detect the gap and re-snapshot; resume contract is
after_worker_sequence = oldest_available_sequence - 1.

- .NET: MxEventStreamItem (IsReplayGap/ReplayGap/Event) via new StreamEventItemsAsync
  + AsStreamItemsAsync extension. Build clean, 87 passed.
- Go: EventResult.ReplayGap field + IsReplayGap(); ReplayGap type alias. build/vet/test clean.
- Rust: EventItem enum (Event/ReplayGap); EventStream now yields Result<EventItem, Error>;
  CLI renders REPLAY_GAP line / replayGap JSON. fmt/check/test/clippy clean.
- Python: ReplayGap dataclass; stream_events yields pb.MxEvent | ReplayGap. 131 passed.
- Shared docs: ClientLibrariesDesign non-goals reframed (reconnect-replay protocol is
  consumable; auto-reconnect stays a non-goal); CrossLanguageSmokeMatrix resume-gap note.

Java client is deferred to the windev batch (no local JRE); CLI-15 stays open until it lands.

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

clients/rust/tests/client_behavior.rs

@@ -27,13 +27,13 @@ use zb_mom_ww_mxgateway_client::generated::mxaccess_gateway::v1::{
     CloseSessionReply, CloseSessionRequest, MxCommandKind, MxCommandReply, MxDataType, MxEvent,
     MxEventFamily, MxSparseArray, MxSparseElement, MxStatusCategory, MxStatusProxy, MxStatusSource,
     MxValue, OnAlarmTransitionEvent, OpenSessionReply, OpenSessionRequest, ProtocolStatus,
-    ProtocolStatusCode, QueryActiveAlarmsRequest, RegisterReply, SessionState, StreamAlarmsRequest,
-    StreamEventsRequest, SubscribeResult, Write2BulkEntry, WriteBulkEntry, WriteCommand,
-    WriteSecured2BulkEntry, WriteSecuredBulkEntry,
+    ProtocolStatusCode, QueryActiveAlarmsRequest, RegisterReply, ReplayGap, SessionState,
+    StreamAlarmsRequest, StreamEventsRequest, SubscribeResult, Write2BulkEntry, WriteBulkEntry,
+    WriteCommand, WriteSecured2BulkEntry, WriteSecuredBulkEntry,
 };
 use zb_mom_ww_mxgateway_client::{
-    next_correlation_id, ApiKey, ClientOptions, CommandError, Error, GatewayClient, MxStatus,
-    MxValue as ClientMxValue, MxValueProjection,
+    next_correlation_id, ApiKey, ClientOptions, CommandError, Error, EventItem, GatewayClient,
+    MxStatus, MxValue as ClientMxValue, MxValueProjection,
 };
 
 #[tokio::test]
@@ -128,8 +128,28 @@ async fn event_stream_preserves_order_and_drop_cancels_server_stream() {
         .await
         .unwrap();
 
-    assert_eq!(stream.next().await.unwrap().unwrap().worker_sequence, 1);
-    assert_eq!(stream.next().await.unwrap().unwrap().worker_sequence, 2);
+    assert_eq!(
+        stream
+            .next()
+            .await
+            .unwrap()
+            .unwrap()
+            .as_event()
+            .unwrap()
+            .worker_sequence,
+        1
+    );
+    assert_eq!(
+        stream
+            .next()
+            .await
+            .unwrap()
+            .unwrap()
+            .as_event()
+            .unwrap()
+            .worker_sequence,
+        2
+    );
 
     drop(stream);
     for _ in 0..20 {
@@ -142,6 +162,55 @@ async fn event_stream_preserves_order_and_drop_cancels_server_stream() {
     assert!(state.stream_dropped.load(Ordering::SeqCst));
 }
 
+#[tokio::test]
+async fn replay_gap_sentinel_surfaces_as_typed_event_item() {
+    let state = Arc::new(FakeState::default());
+    // Script a resumed stream: the reconnect-replay gap sentinel at the head
+    // (family UNSPECIFIED, no body, `replay_gap` set) followed by a normal
+    // event. The client must promote the sentinel to `EventItem::ReplayGap`
+    // and leave the following event as a normal `EventItem::Event`.
+    *state.stream_events_script.lock().await = Some(vec![
+        MxEvent {
+            replay_gap: Some(ReplayGap {
+                requested_after_sequence: 5,
+                oldest_available_sequence: 42,
+            }),
+            ..MxEvent::default()
+        },
+        event(42),
+    ]);
+    let endpoint = spawn_fake_gateway(state.clone()).await;
+    let client = GatewayClient::connect(ClientOptions::new(endpoint))
+        .await
+        .unwrap();
+
+    let mut stream = client
+        .stream_events(StreamEventsRequest {
+            session_id: "session-fixture".to_owned(),
+            after_worker_sequence: 5,
+        })
+        .await
+        .unwrap();
+
+    // First item is the typed gap sentinel, not a normal event.
+    let first = stream.next().await.unwrap().unwrap();
+    match &first {
+        EventItem::ReplayGap(gap) => {
+            assert_eq!(gap.requested_after_sequence, 5);
+            assert_eq!(gap.oldest_available_sequence, 42);
+        }
+        EventItem::Event(_) => panic!("expected a ReplayGap sentinel, got a normal event"),
+    }
+    // Accessor helpers reflect the variant.
+    assert!(first.as_event().is_none());
+    assert_eq!(first.replay_gap().unwrap().oldest_available_sequence, 42);
+
+    // The normal event that follows is unaffected.
+    let second = stream.next().await.unwrap().unwrap();
+    assert_eq!(second.as_event().unwrap().worker_sequence, 42);
+    assert!(second.replay_gap().is_none());
+}
+
 #[tokio::test]
 async fn acknowledge_alarm_returns_reply_with_native_status() {
     let state = Arc::new(FakeState::default());
@@ -672,6 +741,11 @@ struct FakeState {
     /// handler to emit a synthetic ConditionRefresh -> snapshot_complete
     /// -> transition sequence.
     stream_alarms_script: Mutex<Option<Vec<AlarmFeedMessage>>>,
+    /// Optional per-test override that pins the fake's `StreamEvents`
+    /// handler to emit a scripted `MxEvent` sequence (e.g. a `replay_gap`
+    /// sentinel followed by a normal event). When `None`, the handler falls
+    /// back to the default `event(1)` / `event(2)` pair.
+    stream_events_script: Mutex<Option<Vec<MxEvent>>>,
 }
 
 /// Per-test override for the fake's `Invoke` handler.
@@ -921,9 +995,12 @@ impl MxAccessGateway for FakeGateway {
         &self,
         _request: Request<StreamEventsRequest>,
     ) -> Result<Response<Self::StreamEventsStream>, Status> {
-        let (sender, receiver) = mpsc::channel(4);
-        sender.send(Ok(event(1))).await.unwrap();
-        sender.send(Ok(event(2))).await.unwrap();
+        let script = self.state.stream_events_script.lock().await.take();
+        let events = script.unwrap_or_else(|| vec![event(1), event(2)]);
+        let (sender, receiver) = mpsc::channel(events.len().max(1));
+        for event in events {
+            sender.send(Ok(event)).await.unwrap();
+        }
 
         Ok(Response::new(DropAwareStream {
             inner: ReceiverStream::new(receiver),