docs(audience-session): plain-language comment pass

Rewrites jargon-heavy comments (off-thread, serialise, wire-ordered,
fence, CAS, Timer thread) into plain language that reads without a
threading background.

No code changes. All 220 tests pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: ImmutableJeffrey

src/Packages/Audience/Runtime/Core/Session.cs

@@ -12,13 +12,15 @@ namespace Immutable.Audience
     internal delegate void TrackDelegate(string eventName, Dictionary<string, object> properties);
 
     // Unity session lifecycle. Emits session_start / session_heartbeat / session_end.
-    // duration is engagement time (excludes pause). Heartbeat fires off-thread;
-    // public methods run on the caller's thread. _track fires outside _lock.
+    // duration is engagement time (excludes pause). The heartbeat runs on a
+    // background thread; other methods run on the thread that called them. The
+    // track callback is invoked with the internal lock released.
     //
-    // Serialisation: Start / End / Dispose are NOT reentrant-safe from multiple
-    // threads. Callers serialise them (ImmutableAudience holds _initLock across
-    // Init / SetConsent / Shutdown / Reset, which are the only public entry points
-    // that touch a Session). Pause / Resume / OnHeartbeat are thread-safe.
+    // Start / End / Dispose are not safe to call from multiple threads at once.
+    // Callers run them one at a time (ImmutableAudience holds its init lock while
+    // calling Init / SetConsent / Shutdown / Reset — the only public entry points
+    // that touch a Session). Pause / Resume / OnHeartbeat are safe to call from
+    // any thread.
     internal sealed class Session : IDisposable
     {
         internal const int HeartbeatIntervalMs = 60_000;
@@ -63,9 +65,10 @@ internal Session(
         // Starts a session. Fires session_start and arms the heartbeat timer.
         internal void Start()
         {
-            // Phase 1: drain old timer outside _lock (callback re-enters _lock).
-            // Old state left intact so a trailing callback emits for the old session
-            // — wire-ordered before the new session_start.
+            // Phase 1: shut down the old timer with the internal lock released
+            // (the callback takes that lock itself). Old state left intact so a
+            // trailing callback sends a heartbeat for the old session — the
+            // backend receives it before the new session_start.
             Timer? oldTimer;
             lock (_lock)
             {
@@ -216,7 +219,8 @@ internal void OnHeartbeat()
             lock (_lock)
             {
                 if (_disposed || _sessionId == null) return;
-                // Paused sessions don't ship heartbeats (timer still fires; this gates _track).
+                // A paused session doesn't send heartbeats. The timer keeps
+                // firing internally; this check stops the event from going out.
                 if (_pausedAt.HasValue) return;
                 sessionId = _sessionId!;
 
@@ -244,8 +248,10 @@ internal void OnHeartbeat()
             SafeTrack("session_heartbeat", properties);
         }
 
-        // Guards _track from escaping. Heartbeat is a Timer callback (process
-        // kill on .NET 5+); Start/End are caller-thread (would bubble to Init/Shutdown).
+        // Stops exceptions from the track callback from reaching upstream.
+        // Heartbeat runs on a background timer — an uncaught exception there
+        // crashes the game on modern .NET. Start / End run on the caller's
+        // thread, where it would bubble into Init / Shutdown.
         private void SafeTrack(string eventName, Dictionary<string, object> properties)
         {
             try
@@ -258,7 +264,8 @@ private void SafeTrack(string eventName, Dictionary<string, object> properties)
             }
         }
 
-        // Guards the studio-supplied snapshot from escaping to the timer thread.
+        // Stops exceptions from the studio-supplied snapshot callback from
+        // reaching the background timer.
         private Dictionary<string, object>? SafePerformanceSnapshot()
         {
             if (_performanceSnapshot == null) return null;
@@ -288,7 +295,8 @@ private void DrainHeartbeatTimer()
             using var waited = new ManualResetEvent(false);
             try
             {
-                // Dispose(wh)=false: already disposed, wh never signals — skip the wait.
+                // Timer was already disposed. The signal handle won't fire, so
+                // don't wait for it.
                 if (!timer.Dispose(waited))
                     return;
 

src/Packages/Audience/Runtime/ImmutableAudience.cs

@@ -12,9 +12,11 @@ namespace Immutable.Audience
     // Entry point for the Immutable Audience SDK.
     public static class ImmutableAudience
     {
-        // Reference fields are written inside _initLock; readers fence off the volatile _initialized load.
-        // _consent, _session are written in _initLock, read outside → volatile.
-        // _userId is written outside the lock (Identify, Reset) → volatile.
+        // Reference fields are written inside _initLock; readers check the
+        // `volatile _initialized` flag first so they never see a half-initialised state.
+        // _consent and _session are written only inside _initLock but read outside,
+        // so they stay `volatile` to make writes visible across threads.
+        // _userId is written outside the lock (Identify, Reset) — `volatile` for the same reason.
         private static AudienceConfig? _config;
         private static DiskStore? _store;
         private static EventQueue? _queue;
@@ -610,7 +612,8 @@ private static bool CanTrack()
             return _initialized && _consent.CanTrack();
         }
 
-        // Shallow-copy so post-call mutation can't race the drain-thread serialiser.
+        // Copy the dictionary so the caller editing it later can't corrupt the
+        // message while the background thread is writing it to disk.
         private static Dictionary<string, object>? SnapshotCallerDict(Dictionary<string, object>? src) =>
             src != null ? new Dictionary<string, object>(src) : null;
 
@@ -625,8 +628,8 @@ private static void Enqueue(Dictionary<string, object>? msg)
 
         private static void SendBatch()
         {
-            // CAS the gate; a previous tick still running → skip (including reschedule,
-            // which the in-flight tick handles in its finally).
+            // If a previous send is still running, skip this one. That send
+            // will reschedule the next tick when it finishes.
             if (Interlocked.CompareExchange(ref _sendInFlight, 1, 0) != 0)
                 return;
 

src/Packages/Audience/Runtime/Utility/Log.cs

@@ -22,9 +22,10 @@ internal static void Warn(string message) =>
 
         private static void Emit(string line)
         {
-            // Swallow Writer/Console throws so Log.Warn/Debug is never-throwing.
-            // SDK safety wrappers log from inside their own catches; a throwing
-            // Writer would otherwise reach the Timer thread (process kill on .NET 5+).
+            // Swallow anything the Writer or Console throws so Log.Warn and
+            // Log.Debug never throw themselves. If they did, an exception from
+            // logging inside a catch block would reach the background timer
+            // and crash the game on modern .NET.
             try
             {
                 if (Writer != null)