docs(audience): plain-language comment pass

Rewrites jargon-heavy comments (polyfill, atomic reference, release/
acquire, drain-lock, serialise) into plain language.

No code changes. All 181 tests pass.

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

Author: ImmutableJeffrey

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

@@ -2,16 +2,17 @@
 
 namespace System.Runtime.CompilerServices
 {
-    // Polyfill: record { init } properties compile to init-only setters that
-    // reference IsExternalInit. .NET Standard 2.1 (Unity) doesn't ship it.
+    // Unity's .NET runtime doesn't include this type, but the C# compiler
+    // needs it to exist to build the ConsentState record below. Declaring
+    // an empty one here gives the compiler what it looks for.
     internal static class IsExternalInit { }
 }
 
 namespace Immutable.Audience
 {
-    // Immutable consent + userId pair. Stored as a volatile reference so
-    // readers observe both fields atomically — a SetConsent(Full → Anonymous)
-    // swap cannot be observed as Anonymous+oldUserId.
+    // Pairs the consent level with the user id so the two always move
+    // together. Updates swap the whole pair at once — a reader never sees
+    // the new consent level alongside a leftover user id.
     internal sealed record ConsentState(ConsentLevel Level, string? UserId)
     {
         internal static readonly ConsentState None = new(ConsentLevel.None, null);

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.
-        // _state (consent + userId) is volatile for release/acquire visibility; writes
-        // are serialised under _initLock (Identify / Reset also take it to keep the pair atomic).
+        // Reference fields are written inside _initLock; readers check the
+        // `volatile _initialized` flag first so they never see a half-initialised state.
+        // _state (consent + userId) is `volatile` so a write on one thread is
+        // visible on any other. Writes happen under _initLock (Identify / Reset
+        // also take it) so the two fields always move together.
         private static AudienceConfig? _config;
         private static DiskStore? _store;
         private static EventQueue? _queue;
@@ -200,7 +202,8 @@ public static void Identify(string userId, string identityType, Dictionary<strin
 
             AudienceConfig? config;
             ConsentLevel level;
-            // Update _state under _initLock so (consent, userId) stays a consistent pair.
+            // Update consent + userId under the init lock so they always move
+            // together — another thread reading _state never sees one half-updated.
             lock (_initLock)
             {
                 if (!_initialized) return;
@@ -592,8 +595,9 @@ private static bool CanTrack()
         private static Dictionary<string, object>? SnapshotCallerDict(Dictionary<string, object>? src) =>
             src != null ? new Dictionary<string, object>(src) : null;
 
-        // Re-reads _state under _drainLock to close the Track-races-SetConsent
-        // window: drops on downgrade to None, strips userId on downgrade to Anonymous.
+        // Checks the current consent inside the drain lock. If consent has
+        // since dropped to None the message is discarded. If it dropped to
+        // Anonymous the userId is stripped.
         private static void EnqueueTrack(Dictionary<string, object>? msg)
         {
             _queue?.EnqueueChecked(msg, m =>

src/Packages/Audience/Runtime/Transport/EventQueue.cs

@@ -64,11 +64,12 @@ internal void Enqueue(Dictionary<string, object>? msg)
                 _flushGate.Set();
         }
 
-        // Enqueues under _drainLock, giving the caller a transform callback
-        // that runs inside the lock. The transform returns the (possibly
-        // mutated) message or null to drop. Serialises the decision against
-        // PurgeAll / ApplyAnonymousDowngrade so consent-race leaks and stale
-        // userIds can be dropped or stripped atomically.
+        // Queues the message under the drain lock. The caller supplies a
+        // transform that runs while the lock is held — it can edit the
+        // message or return null to drop it. Running under the lock means
+        // PurgeAll and ApplyAnonymousDowngrade can't slip in mid-decision, so
+        // a Track that races a consent downgrade gets its userId stripped or
+        // the message dropped before it reaches the queue.
         internal void EnqueueChecked(
             Dictionary<string, object>? msg,
             Func<Dictionary<string, object>, Dictionary<string, object>?>? transform)