docs: explain why stale session envelopes must not clobber newer state

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: buenaflor

sentry/src/main/java/io/sentry/cache/EnvelopeCache.java

@@ -119,6 +119,10 @@ private boolean storeInternal(final @NotNull SentryEnvelope envelope, final @Not
     final File previousSessionFile = getPreviousSessionFile(directoryPath);
 
     if (HintUtils.hasType(hint, SessionEnd.class)) {
+      // A SessionEnd normally clears session.json. Its envelope may have been queued while a
+      // newer session replaced it on disk though, and deleting would then drop that session's
+      // unhandled error before it can be finalized. Only keep the file when the stored session
+      // is provably a different, later one carrying the flag.
       try (final @NotNull ISentryLifecycleToken ignored = sessionLock.acquire()) {
         final @Nullable Session endingSession = readSessionFromEnvelope(envelope);
         final @Nullable Session currentSession = readSessionFromDisk(currentSessionFile);
@@ -149,6 +153,8 @@ private boolean storeInternal(final @NotNull SentryEnvelope envelope, final @Not
         if (startingSession != null) {
           final @Nullable Session currentSession = readSessionFromDisk(currentSessionFile);
           if (currentSession != null && hasSameSessionId(currentSession, startingSession)) {
+            // A start for the id already on disk is a late duplicate, and that stored snapshot
+            // may have advanced since it was written, so overwrite only if it has not.
             if (!isNewerUnhandledOrErrorSnapshot(currentSession, startingSession)) {
               writeSessionToDisk(currentSessionFile, startingSession);
             }