From 93a903c6583a70b09d71edfb0d45d17d5fde18e8 Mon Sep 17 00:00:00 2001
From: Corneille Tshibasu <89458796+c-tshibas@users.noreply.github.com>
Date: Wed, 12 Aug 2026 14:31:23 +0100
Subject: [PATCH] [ctshibas/replay-race-sdk] Provide comment on behaviour based
 on RUMS-6240 replay-race issue

---
 .../src/domain/contexts/sessionContext.ts                 | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/packages/browser-rum-core/src/domain/contexts/sessionContext.ts b/packages/browser-rum-core/src/domain/contexts/sessionContext.ts
index 0cf15e4358..c228168788 100644
--- a/packages/browser-rum-core/src/domain/contexts/sessionContext.ts
+++ b/packages/browser-rum-core/src/domain/contexts/sessionContext.ts
@@ -36,6 +36,14 @@ export function startSessionContext(
       sampledForReplay = computeSessionReplayState(session, configuration) === SessionReplayState.SAMPLED
       isActive = view.sessionIsActive ? undefined : false
     } else {
+      // KNOWN GAP (RUMS-6240): unlike the VIEW branch above, this is a live, one-shot read of
+      // `isRecording()` with no retry or history. `isRecording()` requires the Deflate worker's
+      // async init handshake to have fully completed (see recorderApi.ts), which is a strictly
+      // later condition than the recorder actually starting to capture DOM mutations (`record()`
+      // in datadogRecorder.ts only needs the worker instance to exist, not be initialized).
+      // An error/action/resource firing in that window gets `has_replay: undefined` baked in
+      // permanently, even if a segment covering that exact moment is captured moments later --
+      // there is no mechanism (analogous to getReplayStats' history) to retroactively correct it.
       hasReplay = recorderApi.isRecording() ? true : undefined
     }