From 8f08143d42fdc85906c3ccde1c80391d115f5c56 Mon Sep 17 00:00:00 2001
From: ImmutableJeffrey <jeffrey.wong@immutable.com>
Date: Thu, 30 Apr 2026 18:46:03 +1000
Subject: [PATCH 1/2] docs(audience-sdk): apply XML doc style to public surface
 (SDK-216)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds XML doc comments to every public type and member of
Immutable.Audience.Runtime, enables doc-file generation, and turns
on CS1591 enforcement so future public surface without a <summary>
breaks the build.

Files documented:
- ConsentLevel.cs: enum + 3 cases.
- IdentityType.cs: enum + 8 cases.
- AudienceError.cs: AudienceErrorCode enum (5 cases) plus
  AudienceError class, Code property, and constructor.
- AudienceConfig.cs: class plus 11 public properties.
- Events/IEvent.cs: interface plus EventName and ToProperties.
- Events/TypedEvents.cs: ProgressionStatus, ResourceFlow enums plus
  Progression, Resource, Purchase, MilestoneReached classes (with
  <inheritdoc/> on the IEvent impls).
- ImmutableAudience.cs: static class plus 6 properties (Initialized,
  CurrentConsent, UserId, AnonymousId, SessionId, QueueSize) and 11
  methods (Init, Track x2, Identify x2, Alias x2, Reset, DeleteData,
  SetConsent, FlushAsync, Shutdown).
- Core/Constants.cs: DistributionPlatforms class plus 5 string
  constants.

Style applied:
- Property summaries are noun-phrase, not "Gets..." or imperative.
- Method summaries are imperative.
- Sentence case, period at end. British spelling.
- Negative-space stated for nullable members where non-trivial.
- <see cref> for sibling references; <seealso cref> for See Also.
- <param> per parameter; <returns> on Tasks; <exception cref> on
  documented throws.
- <inheritdoc/> on interface impls.
- <remarks> only where it carries load-bearing consumer-facing info
  (handling semantics, persistence guarantees, swallow contracts,
  negative-space). Internal mechanics stay out of public docs.
- No "Gets/Sets" prefix, no "(RO)" suffix, no marketing language.
- No em-dash, no emoji or symbol glyphs.
- See code-review/audience-comment-style.md for the full ruleset.

Maintainer-only blocks (threading invariants, lock notes, Phase
1/Phase 2 commentary, IL2CPP rationale) stay as // line comments
per §6 of the style doc.

Audience.Runtime.csproj:
- <GenerateDocumentationFile>true</> emits Immutable.Audience.Runtime.xml
  beside the DLL on every build.
- CS1591 fires when any future public surface is added without a
  <summary>. No NoWarn suppression.

dotnet build clean: 0 warnings, 0 errors. No code behaviour changes.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../Audience/Runtime/Audience.Runtime.csproj  |   4 +
 .../Audience/Runtime/AudienceConfig.cs        |  75 +++++++--
 .../Audience/Runtime/AudienceError.cs         |  62 ++++++-
 src/Packages/Audience/Runtime/ConsentLevel.cs |  23 ++-
 .../Audience/Runtime/Core/Constants.cs        |  15 +-
 .../Audience/Runtime/Events/IEvent.cs         |  26 ++-
 .../Audience/Runtime/Events/TypedEvents.cs    | 143 ++++++++++++++---
 src/Packages/Audience/Runtime/IdentityType.cs |  26 ++-
 .../Audience/Runtime/ImmutableAudience.cs     | 151 ++++++++++++++----
 9 files changed, 441 insertions(+), 84 deletions(-)

diff --git a/src/Packages/Audience/Runtime/Audience.Runtime.csproj b/src/Packages/Audience/Runtime/Audience.Runtime.csproj
index 46635dc4e..8a7e3eb4a 100644
--- a/src/Packages/Audience/Runtime/Audience.Runtime.csproj
+++ b/src/Packages/Audience/Runtime/Audience.Runtime.csproj
@@ -5,6 +5,10 @@
     <Nullable>disable</Nullable>
     <!-- Match the Unity asmdef assembly name so InternalsVisibleTo works in both contexts -->
     <AssemblyName>Immutable.Audience.Runtime</AssemblyName>
+    <!-- Emit Immutable.Audience.Runtime.xml so Rider/IntelliSense show summaries.
+         CS1591 (missing XML comment on publicly visible type or member) is
+         enabled so future undocumented public members break the build. -->
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
   </PropertyGroup>
   <!--
     The Unity/ subtree belongs to the sibling Immutable.Audience.Unity asmdef.
diff --git a/src/Packages/Audience/Runtime/AudienceConfig.cs b/src/Packages/Audience/Runtime/AudienceConfig.cs
index 49cb55fd9..c26815096 100644
--- a/src/Packages/Audience/Runtime/AudienceConfig.cs
+++ b/src/Packages/Audience/Runtime/AudienceConfig.cs
@@ -4,46 +4,89 @@
 
 namespace Immutable.Audience
 {
-    // Configuration passed to ImmutableAudience.Init.
+    /// <summary>
+    /// Configuration passed to <see cref="ImmutableAudience.Init"/>.
+    /// </summary>
     public class AudienceConfig
     {
-        // Studio API key. Required — Init throws if null.
+        /// <summary>
+        /// Studio API key issued by Immutable Hub.
+        /// </summary>
+        /// <remarks>
+        /// Required. <see cref="ImmutableAudience.Init"/> throws if null or empty.
+        /// </remarks>
         public string? PublishableKey { get; set; }
 
-        // Override the default API base URL. When null, keys starting with
-        // "pk_imapik-test-" resolve to Sandbox and all other keys resolve
-        // to Production. Set explicitly to target a different backend.
+        /// <summary>
+        /// Override the default API base URL.
+        /// </summary>
+        /// <remarks>
+        /// When null, publishable keys starting with <c>pk_imapik-test-</c>
+        /// resolve to Sandbox. All other keys resolve to Production. Set
+        /// explicitly to target a different backend.
+        /// </remarks>
         public string? BaseUrl { get; set; }
 
-        // Initial consent level.
+        /// <summary>
+        /// Initial consent level.
+        /// </summary>
+        /// <remarks>
+        /// If the SDK persisted a different level on a previous launch, that
+        /// persisted level overrides this default at
+        /// <see cref="ImmutableAudience.Init"/>.
+        /// </remarks>
         public ConsentLevel Consent { get; set; } = ConsentLevel.None;
 
-        // Distribution platform the game is running on.
+        /// <summary>
+        /// Distribution platform the game is running on.
+        /// </summary>
+        /// <seealso cref="DistributionPlatforms"/>
         public string? DistributionPlatform { get; set; }
 
-        // Enable debug logging.
+        /// <summary>
+        /// Whether the SDK emits debug log lines for every event, flush,
+        /// and consent change.
+        /// </summary>
         public bool Debug { get; set; } = false;
 
-        // How often pending events are flushed to the backend.
+        /// <summary>
+        /// Interval between automatic flushes to the backend, in seconds.
+        /// </summary>
         public int FlushIntervalSeconds { get; set; } = Constants.DefaultFlushIntervalSeconds;
 
-        // Flush as soon as this many events are queued.
+        /// <summary>
+        /// Queued-event threshold that triggers an automatic flush before the
+        /// next interval tick.
+        /// </summary>
         public int FlushSize { get; set; } = Constants.DefaultFlushSize;
 
-        // Optional error callback.
+        /// <summary>
+        /// Callback fired when the SDK encounters a recoverable failure.
+        /// </summary>
+        /// <remarks>
+        /// Exceptions thrown from the callback are swallowed so a bad handler
+        /// cannot wedge the SDK.
+        /// </remarks>
         public Action<AudienceError>? OnError { get; set; }
 
-        // Directory the SDK uses for identity, consent, and queued events.
-        // Unity hooks populate this from Application.persistentDataPath.
+        /// <summary>
+        /// Directory the SDK uses for identity, consent, and queued events.
+        /// Usually populated automatically by Unity hooks.
+        /// </summary>
         public string? PersistentDataPath { get; set; }
 
-        // Library version sent on every message.
+        /// <summary>
+        /// Library version sent on every message.
+        /// </summary>
         public string PackageVersion { get; set; } = Constants.LibraryVersion;
 
-        // Maximum time Shutdown waits for the final flush.
+        /// <summary>
+        /// Maximum time <see cref="ImmutableAudience.Shutdown"/> waits for
+        /// the final flush, in milliseconds.
+        /// </summary>
         public int ShutdownFlushTimeoutMs { get; set; } = 2_000;
 
-        // Test seam for HttpTransport; not part of the public API.
+        // Test seam for HttpTransport. Not part of the public API.
         internal System.Net.Http.HttpMessageHandler? HttpHandler { get; set; }
     }
 }
diff --git a/src/Packages/Audience/Runtime/AudienceError.cs b/src/Packages/Audience/Runtime/AudienceError.cs
index 2d8e07b08..c8da67049 100644
--- a/src/Packages/Audience/Runtime/AudienceError.cs
+++ b/src/Packages/Audience/Runtime/AudienceError.cs
@@ -2,24 +2,76 @@
 
 namespace Immutable.Audience
 {
+    /// <summary>
+    /// Categorises errors raised through <see cref="AudienceConfig.OnError"/>.
+    /// </summary>
     public enum AudienceErrorCode
     {
-        // An event batch failed to flush. Either a local storage read error (batch dropped) or a non-2xx/non-4xx server response — typically 5xx (batch retained and retried with backoff).
+        /// <summary>
+        /// An event batch failed to flush.
+        /// </summary>
+        /// <remarks>
+        /// Either a local storage read error (batch dropped) or a non-2xx /
+        /// non-4xx server response, typically 5xx (batch retained and retried
+        /// with backoff).
+        /// </remarks>
         FlushFailed,
-        // Server rejected an event batch with a 4xx status. The batch was dropped; retrying will not help (typically indicates a malformed payload).
+
+        /// <summary>
+        /// Server rejected an event batch with a 4xx status.
+        /// </summary>
+        /// <remarks>
+        /// The batch was dropped. Retrying will not help (typically indicates
+        /// a malformed payload).
+        /// </remarks>
         ValidationRejected,
-        // Failed to sync a consent change to the backend. The local consent level has already been applied; the server-side audit trail may be out of date.
+
+        /// <summary>
+        /// Failed to sync a consent change to the backend.
+        /// </summary>
+        /// <remarks>
+        /// The local consent level has already been applied. The server-side
+        /// audit trail may be out of date.
+        /// </remarks>
         ConsentSyncFailed,
-        // A network call failed (exception, timeout, or non-2xx response on data deletion). Event batches are retained for retry; data-delete requests are not retried automatically.
+
+        /// <summary>
+        /// A network call failed.
+        /// </summary>
+        /// <remarks>
+        /// Causes include exceptions, timeouts, or a non-2xx response on data
+        /// deletion. Event batches are retained for retry. Data-delete
+        /// requests are not retried automatically.
+        /// </remarks>
         NetworkError,
-        // Failed to persist the consent level to disk. In-memory level still applied but will revert on next launch.
+
+        /// <summary>
+        /// Failed to persist the consent level to disk.
+        /// </summary>
+        /// <remarks>
+        /// The in-memory level is still applied but will revert on next
+        /// launch.
+        /// </remarks>
         ConsentPersistFailed
     }
 
+    /// <summary>
+    /// Error raised through <see cref="AudienceConfig.OnError"/> when the SDK
+    /// encounters a recoverable failure.
+    /// </summary>
     public class AudienceError : Exception
     {
+        /// <summary>
+        /// The reason this error was raised.
+        /// </summary>
         public AudienceErrorCode Code { get; }
 
+        /// <summary>
+        /// Wraps a code and message into an <see cref="AudienceError"/> for
+        /// delivery through <see cref="AudienceConfig.OnError"/>.
+        /// </summary>
+        /// <param name="code">The reason for the failure.</param>
+        /// <param name="message">Human-readable description.</param>
         public AudienceError(AudienceErrorCode code, string message)
             : base(message)
         {
diff --git a/src/Packages/Audience/Runtime/ConsentLevel.cs b/src/Packages/Audience/Runtime/ConsentLevel.cs
index db650a344..2b3db4724 100644
--- a/src/Packages/Audience/Runtime/ConsentLevel.cs
+++ b/src/Packages/Audience/Runtime/ConsentLevel.cs
@@ -2,14 +2,29 @@
 
 namespace Immutable.Audience
 {
-    // How much data the Audience SDK is allowed to collect.
+    /// <summary>
+    /// How much data the Audience SDK is allowed to collect.
+    /// </summary>
+    /// <seealso cref="ImmutableAudience.SetConsent"/>
     public enum ConsentLevel
     {
-        // No tracking
+        /// <summary>
+        /// No tracking.
+        /// </summary>
         None,
-        // Anonymous tracking only
+
+        /// <summary>
+        /// Anonymous tracking. Events carry the device's anonymous ID. Identifying
+        /// the player via
+        /// <see cref="ImmutableAudience.Identify(string, IdentityType, System.Collections.Generic.Dictionary{string, object})"/>
+        /// is rejected at this level.
+        /// </summary>
         Anonymous,
-        // Full tracking
+
+        /// <summary>
+        /// Full tracking. Events may carry a known user ID set via
+        /// <see cref="ImmutableAudience.Identify(string, IdentityType, System.Collections.Generic.Dictionary{string, object})"/>.
+        /// </summary>
         Full
     }
 
diff --git a/src/Packages/Audience/Runtime/Core/Constants.cs b/src/Packages/Audience/Runtime/Core/Constants.cs
index f567aef8a..f217812d5 100644
--- a/src/Packages/Audience/Runtime/Core/Constants.cs
+++ b/src/Packages/Audience/Runtime/Core/Constants.cs
@@ -60,13 +60,26 @@ internal static class MessageFields
         internal const string UserId = "userId";
     }
 
-    // Common distribution platform values for AudienceConfig.DistributionPlatform.
+    /// <summary>
+    /// Common values for <see cref="AudienceConfig.DistributionPlatform"/>.
+    /// </summary>
     public static class DistributionPlatforms
     {
+        /// <summary>Steam.</summary>
         public const string Steam = "steam";
+
+        /// <summary>Epic Games Store.</summary>
         public const string Epic = "epic";
+
+        /// <summary>GOG.com.</summary>
         public const string GOG = "gog";
+
+        /// <summary>itch.io.</summary>
         public const string Itch = "itch";
+
+        /// <summary>
+        /// Standalone build, distributed outside any storefront.
+        /// </summary>
         public const string Standalone = "standalone";
     }
 }
diff --git a/src/Packages/Audience/Runtime/Events/IEvent.cs b/src/Packages/Audience/Runtime/Events/IEvent.cs
index 0ef5a28d0..c4fbfdea1 100644
--- a/src/Packages/Audience/Runtime/Events/IEvent.cs
+++ b/src/Packages/Audience/Runtime/Events/IEvent.cs
@@ -1,13 +1,35 @@
 #nullable enable
 
+using System;
 using System.Collections.Generic;
 
 namespace Immutable.Audience
 {
-    // Typed event contract for ImmutableAudience.Track(IEvent).
+    /// <summary>
+    /// Typed event contract for
+    /// <see cref="ImmutableAudience.Track(IEvent)"/>.
+    /// </summary>
+    /// <remarks>
+    /// Implementations validate required fields inside
+    /// <see cref="ToProperties"/>;
+    /// <see cref="ImmutableAudience.Track(IEvent)"/> catches the throw and
+    /// drops the event with a warning.
+    /// </remarks>
     public interface IEvent
     {
+        /// <summary>
+        /// The event name sent (e.g. <c>"purchase"</c>, <c>"progression"</c>).
+        /// </summary>
         string EventName { get; }
+
+        /// <summary>
+        /// Returns the event's properties as a dictionary, validating
+        /// required fields.
+        /// </summary>
+        /// <returns>A fresh dictionary on every call.</returns>
+        /// <exception cref="ArgumentException">
+        /// A required field is missing or invalid.
+        /// </exception>
         Dictionary<string, object> ToProperties();
     }
-}
\ No newline at end of file
+}
diff --git a/src/Packages/Audience/Runtime/Events/TypedEvents.cs b/src/Packages/Audience/Runtime/Events/TypedEvents.cs
index 5f137b30c..f4b3dce1c 100644
--- a/src/Packages/Audience/Runtime/Events/TypedEvents.cs
+++ b/src/Packages/Audience/Runtime/Events/TypedEvents.cs
@@ -5,18 +5,31 @@
 
 namespace Immutable.Audience
 {
-    // Progression event state.
+    /// <summary>
+    /// State of a progression step.
+    /// </summary>
     public enum ProgressionStatus
     {
+        /// <summary>
+        /// Player has begun this progression step.
+        /// </summary>
         Start,
+
+        /// <summary>
+        /// Player finished this progression step successfully.
+        /// </summary>
         Complete,
+
+        /// <summary>
+        /// Player failed or abandoned this progression step.
+        /// </summary>
         Fail
     }
 
     internal static class ProgressionStatusExtensions
     {
         // Throws on unknown casts. Progression.ToProperties propagates, and
-        // Track(IEvent) catches + drops with a warning.
+        // Track(IEvent) catches and drops with a warning.
         internal static string ToLowercaseString(this ProgressionStatus status) => status switch
         {
             ProgressionStatus.Start => "start",
@@ -27,21 +40,47 @@ internal static class ProgressionStatusExtensions
         };
     }
 
-    // Player progressing through a world / level / stage.
+    /// <summary>
+    /// Player progressing through a world / level / stage. Track via
+    /// <see cref="ImmutableAudience.Track(IEvent)"/>.
+    /// </summary>
     public class Progression : IEvent
     {
-        // Required. Nullable so an unset caller produces a clear validation
-        // error at send time instead of silently shipping the enum default.
+        /// <summary>
+        /// Required. Where the player is in the progression flow.
+        /// </summary>
         public ProgressionStatus? Status { get; set; }
-        // Optional.
+
+        /// <summary>
+        /// Optional. The world the player is in.
+        /// </summary>
         public string? World { get; set; }
+
+        /// <summary>
+        /// Optional. The level within the world.
+        /// </summary>
         public string? Level { get; set; }
+
+        /// <summary>
+        /// Optional. The stage within the level.
+        /// </summary>
         public string? Stage { get; set; }
+
+        /// <summary>
+        /// Optional. The player's current score.
+        /// </summary>
         public int? Score { get; set; }
+
+        /// <summary>
+        /// Optional. Time the player spent on this progression step, in
+        /// seconds.
+        /// </summary>
         public float? DurationSec { get; set; }
 
+        /// <inheritdoc/>
         public string EventName => "progression";
 
+        /// <inheritdoc/>
         public Dictionary<string, object> ToProperties()
         {
             if (Status is null)
@@ -62,17 +101,26 @@ public Dictionary<string, object> ToProperties()
         }
     }
 
-    // Resource flow direction.
+    /// <summary>
+    /// Direction an in-game resource flowed.
+    /// </summary>
     public enum ResourceFlow
     {
+        /// <summary>
+        /// Player gained the resource (loot, daily bonus, quest reward).
+        /// </summary>
         Source,
+
+        /// <summary>
+        /// Player spent the resource (purchase, consumed, lost).
+        /// </summary>
         Sink
     }
 
     internal static class ResourceFlowExtensions
     {
         // Throws on unknown casts. Resource.ToProperties propagates, and
-        // Track(IEvent) catches + drops with a warning.
+        // Track(IEvent) catches and drops with a warning.
         internal static string ToLowercaseString(this ResourceFlow flow) => flow switch
         {
             ResourceFlow.Source => "source",
@@ -82,21 +130,42 @@ internal static class ResourceFlowExtensions
         };
     }
 
-    // In-game currency earned or spent.
+    /// <summary>
+    /// In-game currency earned or spent. Track via
+    /// <see cref="ImmutableAudience.Track(IEvent)"/>.
+    /// </summary>
     public class Resource : IEvent
     {
-        // Required. Nullable so an unset caller produces a clear validation
-        // error at send time instead of silently shipping the enum / zero
-        // default.
+        /// <summary>
+        /// Required. Whether this is a gain or a spend.
+        /// </summary>
         public ResourceFlow? Flow { get; set; }
+
+        /// <summary>
+        /// Required. The in-game currency name (for example, gold, gems,
+        /// energy).
+        /// </summary>
         public string? Currency { get; set; }
+
+        /// <summary>
+        /// Required. How much of the currency was gained or spent.
+        /// </summary>
         public float? Amount { get; set; }
-        // Optional.
+
+        /// <summary>
+        /// Optional. The kind of item involved (for example, weapon, skin).
+        /// </summary>
         public string? ItemType { get; set; }
+
+        /// <summary>
+        /// Optional. The specific item identifier.
+        /// </summary>
         public string? ItemId { get; set; }
 
+        /// <inheritdoc/>
         public string EventName => "resource";
 
+        /// <inheritdoc/>
         public Dictionary<string, object> ToProperties()
         {
             if (Flow is null)
@@ -120,21 +189,44 @@ public Dictionary<string, object> ToProperties()
         }
     }
 
-    // Real-money transaction.
+    /// <summary>
+    /// Real-money transaction. Track via
+    /// <see cref="ImmutableAudience.Track(IEvent)"/>.
+    /// </summary>
     public class Purchase : IEvent
     {
-        // Required. ISO 4217 three-letter uppercase currency code.
+        /// <summary>
+        /// Required. ISO 4217 three-letter uppercase currency code (for
+        /// example, <c>USD</c>, <c>EUR</c>).
+        /// </summary>
         public string? Currency { get; set; }
-        // Required. Nullable so an unset caller produces a clear validation
-        // error at send time instead of silently shipping a zero-value
-        // purchase that breaks attribution and conversion reporting.
+
+        /// <summary>
+        /// Required. The transaction amount in <see cref="Currency"/>.
+        /// </summary>
         public decimal? Value { get; set; }
-        // Optional.
+
+        /// <summary>
+        /// Optional. Stable identifier of the item purchased.
+        /// </summary>
         public string? ItemId { get; set; }
+
+        /// <summary>
+        /// Optional. Human-readable name of the item.
+        /// </summary>
         public string? ItemName { get; set; }
+
+        /// <summary>
+        /// Optional. Number of items in this transaction.
+        /// </summary>
         public int? Quantity { get; set; }
+
+        /// <summary>
+        /// Optional. Studio's own transaction identifier.
+        /// </summary>
         public string? TransactionId { get; set; }
 
+        /// <inheritdoc/>
         public string EventName => "purchase";
 
         // Hand-rolled to avoid pulling System.Text.RegularExpressions into the IL2CPP build.
@@ -149,6 +241,7 @@ private static bool IsIso4217(string s)
             return true;
         }
 
+        /// <inheritdoc/>
         public Dictionary<string, object> ToProperties()
         {
             if (Currency == null || !IsIso4217(Currency))
@@ -172,14 +265,22 @@ public Dictionary<string, object> ToProperties()
         }
     }
 
-    // Named milestone or achievement.
+    /// <summary>
+    /// Named milestone or achievement reached by the player. Track via
+    /// <see cref="ImmutableAudience.Track(IEvent)"/>.
+    /// </summary>
     public class MilestoneReached : IEvent
     {
-        // Required.
+        /// <summary>
+        /// Required. The milestone identifier (for example,
+        /// <c>tutorial_complete</c>).
+        /// </summary>
         public string? Name { get; set; }
 
+        /// <inheritdoc/>
         public string EventName => "milestone_reached";
 
+        /// <inheritdoc/>
         public Dictionary<string, object> ToProperties()
         {
             if (string.IsNullOrEmpty(Name))
diff --git a/src/Packages/Audience/Runtime/IdentityType.cs b/src/Packages/Audience/Runtime/IdentityType.cs
index 2df6e70a1..327924a5c 100644
--- a/src/Packages/Audience/Runtime/IdentityType.cs
+++ b/src/Packages/Audience/Runtime/IdentityType.cs
@@ -2,16 +2,38 @@
 
 namespace Immutable.Audience
 {
-    // Identity provider accepted by the Audience backend.
+    /// <summary>
+    /// Identity provider accepted by the Audience backend.
+    /// </summary>
+    /// <seealso cref="ImmutableAudience.Identify(string, IdentityType, System.Collections.Generic.Dictionary{string, object})"/>
+    /// <seealso cref="ImmutableAudience.Alias(string, IdentityType, string, IdentityType)"/>
     public enum IdentityType
     {
+        /// <summary>Immutable Passport.</summary>
         Passport,
+
+        /// <summary>Steam.</summary>
         Steam,
+
+        /// <summary>Epic Games Store.</summary>
         Epic,
+
+        /// <summary>Google.</summary>
         Google,
+
+        /// <summary>Apple.</summary>
         Apple,
+
+        /// <summary>Discord.</summary>
         Discord,
+
+        /// <summary>Email.</summary>
         Email,
+
+        /// <summary>
+        /// Studio-defined identity that does not match any of the other
+        /// providers.
+        /// </summary>
         Custom,
     }
 
@@ -19,7 +41,7 @@ internal static class IdentityTypeExtensions
     {
         // Throws on unknown casts. Every identify / alias event must carry an
         // identityType so downstream data-deletion requests can match records
-        // to the correct identity namespace; an out-of-range cast must fail
+        // to the correct identity namespace. An out-of-range cast must fail
         // loudly rather than ship an event with a missing or empty namespace.
         internal static string ToLowercaseString(this IdentityType type) => type switch
         {
diff --git a/src/Packages/Audience/Runtime/ImmutableAudience.cs b/src/Packages/Audience/Runtime/ImmutableAudience.cs
index f346ed710..d1b70138b 100644
--- a/src/Packages/Audience/Runtime/ImmutableAudience.cs
+++ b/src/Packages/Audience/Runtime/ImmutableAudience.cs
@@ -9,7 +9,9 @@
 
 namespace Immutable.Audience
 {
-    // Entry point for the Immutable Audience SDK.
+    /// <summary>
+    /// Entry point for the Immutable Audience SDK.
+    /// </summary>
     public static class ImmutableAudience
     {
         // Reference fields are written inside _initLock; readers check the
@@ -51,19 +53,38 @@ public static class ImmutableAudience
         // assignments from SetConsent without taking _initLock.
         private static volatile Session? _session;
 
-        // True between Init() and Shutdown().
+        /// <summary>
+        /// True between <see cref="Init"/> and <see cref="Shutdown"/>.
+        /// </summary>
         public static bool Initialized => _initialized;
 
-        // The consent level the SDK is currently honouring.
+        /// <summary>
+        /// The consent level the SDK is currently honouring.
+        /// </summary>
+        /// <seealso cref="SetConsent"/>
         public static ConsentLevel CurrentConsent => _state.Level;
 
-        // The user ID from the most recent Identify() call. Null after
-        // Reset() or when consent is below Full.
+        /// <summary>
+        /// The user ID from the most recent
+        /// <see cref="Identify(string, IdentityType, Dictionary{string, object})"/>
+        /// call.
+        /// </summary>
+        /// <remarks>
+        /// Null after <see cref="Reset"/> or when consent is below
+        /// <see cref="ConsentLevel.Full"/>.
+        /// </remarks>
         public static string? UserId => _state.UserId;
 
-        // An anonymous, persistent ID — unlike SessionId (rotates per
-        // session) and UserId (identifies the user). Reset() and
-        // SetConsent(None) wipe it; null while consent is None.
+        /// <summary>
+        /// An anonymous, persistent ID for this device.
+        /// </summary>
+        /// <remarks>
+        /// Unlike <see cref="SessionId"/> (rotates per session) and
+        /// <see cref="UserId"/> (identifies the player), this stays stable
+        /// across sessions. <see cref="Reset"/> and <see cref="SetConsent"/>
+        /// with <see cref="ConsentLevel.None"/> wipe it. Null while consent
+        /// is None.
+        /// </remarks>
         public static string? AnonymousId
         {
             get
@@ -76,12 +97,19 @@ public static string? AnonymousId
             }
         }
 
-        // The current session's ID. A new ID is assigned at Init(), at Reset(),
-        // and when the app resumes after the previous session has timed out.
-        // Null while consent is None.
+        /// <summary>
+        /// The current session's ID.
+        /// </summary>
+        /// <remarks>
+        /// A new ID is assigned at <see cref="Init"/>, at <see cref="Reset"/>,
+        /// and when the app resumes after the previous session has timed
+        /// out. Null while consent is None.
+        /// </remarks>
         public static string? SessionId => _session?.SessionId;
 
-        // Number of unsent events (in memory and on disk).
+        /// <summary>
+        /// Number of unsent events, in memory and on disk.
+        /// </summary>
         public static int QueueSize
         {
             get
@@ -101,7 +129,12 @@ public static int QueueSize
             }
         }
 
-        // Starts the SDK. Call once at launch.
+        /// <summary>
+        /// Starts the SDK. Call once at launch.
+        /// </summary>
+        /// <param name="config">
+        /// SDK configuration. <see cref="AudienceConfig.PublishableKey"/> is required.
+        /// </param>
         public static void Init(AudienceConfig config)
         {
             if (config == null) throw new ArgumentNullException(nameof(config));
@@ -186,8 +219,11 @@ internal static void OnResume()
         // Track
         // -----------------------------------------------------------------
 
-        // Sends a typed event. Prefer this over the string overload —
-        // IEvent implementations validate required fields at compile time.
+        /// <summary>
+        /// Sends a typed event. Prefer over the string overload for
+        /// compile-time required-field validation.
+        /// </summary>
+        /// <param name="evt">The event to send.</param>
         public static void Track(IEvent evt)
         {
             var state = _state;
@@ -228,9 +264,13 @@ public static void Track(IEvent evt)
             EnqueueTrack(msg);
         }
 
-        // Sends a custom event. For predefined names (purchase, progression,
-        // resource, milestone_reached), prefer the typed overload which
-        // validates required fields.
+        /// <summary>
+        /// Sends a custom event. For <c>purchase</c>, <c>progression</c>,
+        /// <c>resource</c>, and <c>milestone_reached</c>, prefer the typed
+        /// overload.
+        /// </summary>
+        /// <param name="eventName">The wire-format event name.</param>
+        /// <param name="properties">Optional event properties.</param>
         public static void Track(string eventName, Dictionary<string, object>? properties = null)
         {
             var state = _state;
@@ -255,12 +295,25 @@ public static void Track(string eventName, Dictionary<string, object>? propertie
         // Identity
         // -----------------------------------------------------------------
 
-        // Attaches a known user id to subsequent events.
+        /// <summary>
+        /// Attaches a known user ID to subsequent events.
+        /// </summary>
+        /// <param name="userId">The player's identifier within the chosen provider.</param>
+        /// <param name="identityType">The identity provider that issued <paramref name="userId"/>.</param>
+        /// <param name="traits">Optional player attributes (email, name, etc.).</param>
         public static void Identify(string userId, IdentityType identityType, Dictionary<string, object>? traits = null) =>
             Identify(userId, identityType.ToLowercaseString(), traits);
 
-        // String overload for providers outside the IdentityType enum.
-        // identityType is required — data-deletion matches events by this namespace.
+        /// <summary>
+        /// Attaches a known user ID to subsequent events. String overload
+        /// for providers outside the <see cref="IdentityType"/> enum.
+        /// </summary>
+        /// <param name="userId">The player's identifier within the chosen provider.</param>
+        /// <param name="identityType">
+        /// The identity provider name. Required. Data-deletion requests
+        /// match events by this namespace.
+        /// </param>
+        /// <param name="traits">Optional player attributes (email, name, etc.).</param>
         public static void Identify(string userId, string identityType, Dictionary<string, object>? traits = null)
         {
             if (!_initialized) return;
@@ -297,12 +350,29 @@ public static void Identify(string userId, string identityType, Dictionary<strin
             EnqueueIdentity(msg);
         }
 
-        // Links two user ids for the same player.
+        /// <summary>
+        /// Links two user IDs for the same player.
+        /// </summary>
+        /// <param name="fromId">The previously-known identifier.</param>
+        /// <param name="fromType">Identity provider for <paramref name="fromId"/>.</param>
+        /// <param name="toId">The new identifier.</param>
+        /// <param name="toType">Identity provider for <paramref name="toId"/>.</param>
         public static void Alias(string fromId, IdentityType fromType, string toId, IdentityType toType) =>
             Alias(fromId, fromType.ToLowercaseString(), toId, toType.ToLowercaseString());
 
-        // String overload for providers outside the IdentityType enum.
-        // from/toType are required — data-deletion matches by these namespaces.
+        /// <summary>
+        /// Links two user IDs for the same player. String overload for
+        /// providers outside the <see cref="IdentityType"/> enum.
+        /// </summary>
+        /// <param name="fromId">The previously-known identifier.</param>
+        /// <param name="fromType">
+        /// Identity provider for <paramref name="fromId"/>. Required.
+        /// Data-deletion requests match events by this namespace.
+        /// </param>
+        /// <param name="toId">The new identifier.</param>
+        /// <param name="toType">
+        /// Identity provider for <paramref name="toId"/>. Required.
+        /// </param>
         public static void Alias(string fromId, string fromType, string toId, string toType)
         {
             if (!_initialized) return;
@@ -326,10 +396,10 @@ public static void Alias(string fromId, string fromType, string toId, string toT
             EnqueueIdentity(msg);
         }
 
-        // Logs out the current player. Clears userId, discards queued events,
-        // mints a fresh anonymousId, and starts a new session. Matches Web SDK
-        // reset(): no session_end is emitted for the old session (it is enqueued
-        // and then purged). Call FlushAsync() first to preserve queued events.
+        /// <summary>
+        /// Logs out the current player. Call <see cref="FlushAsync"/> first
+        /// to preserve queued events.
+        /// </summary>
         public static void Reset()
         {
             // Phase 1 under _initLock: atomic _state.UserId clear + _session swap.
@@ -367,7 +437,14 @@ public static void Reset()
             newSession?.Start();
         }
 
-        // Asks the backend to erase this player's data. Await for ack, or discard for fire-and-forget.
+        /// <summary>
+        /// Asks the backend to erase this player's data.
+        /// </summary>
+        /// <param name="userId">
+        /// Optional. The known user ID to delete. When null, the SDK uses
+        /// the device's persisted anonymous ID.
+        /// </param>
+        /// <returns>A task that completes when the backend has responded.</returns>
         public static Task DeleteData(string? userId = null)
         {
             if (!_initialized) return Task.CompletedTask;
@@ -438,7 +515,10 @@ private static void NotifyErrorCallback(Action<AudienceError>? onError, Audience
         // Consent
         // -----------------------------------------------------------------
 
-        // Changes the player's consent level.
+        /// <summary>
+        /// Changes the player's consent level. Persists across restart.
+        /// </summary>
+        /// <param name="level">The new consent level.</param>
         public static void SetConsent(ConsentLevel level)
         {
             if (!_initialized) return;
@@ -612,8 +692,11 @@ private static void SyncConsentToBackend(AudienceConfig config, ConsentLevel lev
         // Flush / Shutdown
         // -----------------------------------------------------------------
 
-        // Sends all pending events now. Respects cancellationToken for both
-        // the gate wait and the HTTP send.
+        /// <summary>
+        /// Sends all pending events now.
+        /// </summary>
+        /// <param name="cancellationToken">Cancellation token.</param>
+        /// <returns>A task that completes when the flush finishes.</returns>
         public static async Task FlushAsync(CancellationToken cancellationToken = default)
         {
             if (!_initialized) return;
@@ -652,7 +735,9 @@ await transport.SendBatchAsync(cancellationToken).ConfigureAwait(false))
             }
         }
 
-        // Flushes and stops the SDK.
+        /// <summary>
+        /// Flushes and stops the SDK.
+        /// </summary>
         public static void Shutdown()
         {
             // Fire session_end before taking _initLock. _initialized is still

From 4051a6b2286b8ebabf7b0552ec55bc8f97efc392 Mon Sep 17 00:00:00 2001
From: ImmutableJeffrey <jeffrey.wong@immutable.com>
Date: Thu, 30 Apr 2026 19:03:59 +1000
Subject: [PATCH 2/2] chore(audience-sdk): remove em-dashes from runtime and
 tests
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Removes em-dash (U+2014) from every // line comment, /// XML doc,
Log.Warn message, and ArgumentException message in the audience SDK
runtime and test projects. Replaced contextually with period plus new
sentence, semicolon for tight clause linkage, colon for "purpose:
mechanism", or parentheses for asides. Per
code-review/audience-comment-style.md §1.5.

Touches 11 runtime files (~57 sites) and 11 test files (~55 sites).

Runtime user-visible string changes worth noting (the wire format
and AudienceErrorCode contract are unchanged):
- ArgumentException messages on Progression/Resource/Purchase
  validation now end with a full stop and split the prescriptive
  clause into a second sentence.
- Log.Warn messages from Init / Track / Identify / Alias /
  SetConsent / Shutdown swap em-dash for period or colon.
- FormatException messages from Json.Serialize use period.

dotnet test: 274 passed, 0 failed.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../Audience/Runtime/Core/ConsentState.cs     |  2 +-
 .../Audience/Runtime/Core/Identity.cs         | 14 +++---
 src/Packages/Audience/Runtime/Core/Session.cs | 10 ++---
 .../Audience/Runtime/Events/TypedEvents.cs    | 10 ++---
 .../Audience/Runtime/ImmutableAudience.cs     | 44 +++++++++----------
 .../Audience/Runtime/Transport/EventQueue.cs  | 12 ++---
 .../Runtime/Transport/HttpTransport.cs        | 20 ++++-----
 .../Audience/Runtime/Unity/DeviceCollector.cs |  2 +-
 .../Runtime/Unity/UnityLifecycleBridge.cs     |  2 +-
 src/Packages/Audience/Runtime/Utility/Json.cs |  4 +-
 .../Audience/Runtime/Utility/TimerDisposal.cs |  2 +-
 .../Audience/Tests/Runtime/ConstantsTests.cs  |  2 +-
 .../Tests/Runtime/Core/SessionTests.cs        | 18 ++++----
 .../Audience/Tests/Runtime/DeleteDataTests.cs |  4 +-
 .../Runtime/Events/MessageBuilderTests.cs     |  2 +-
 .../Tests/Runtime/IdentityTypeTests.cs        |  4 +-
 .../Tests/Runtime/ImmutableAudienceTests.cs   | 38 ++++++++--------
 .../Tests/Runtime/OfflineResilienceTests.cs   |  2 +-
 .../Runtime/PublishableKeyPrefixTests.cs      |  4 +-
 .../Tests/Runtime/ThreadSafetyStressTests.cs  | 10 ++---
 .../Tests/Runtime/Transport/DiskStoreTests.cs |  2 +-
 .../Runtime/Transport/HttpTransportTests.cs   | 22 +++++-----
 .../Tests/Runtime/Utility/JsonTests.cs        |  4 +-
 23 files changed, 117 insertions(+), 117 deletions(-)

diff --git a/src/Packages/Audience/Runtime/Core/ConsentState.cs b/src/Packages/Audience/Runtime/Core/ConsentState.cs
index d5a7aacce..665b05863 100644
--- a/src/Packages/Audience/Runtime/Core/ConsentState.cs
+++ b/src/Packages/Audience/Runtime/Core/ConsentState.cs
@@ -11,7 +11,7 @@ internal static class IsExternalInit { }
 namespace Immutable.Audience
 {
     // 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
+    // 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)
     {
diff --git a/src/Packages/Audience/Runtime/Core/Identity.cs b/src/Packages/Audience/Runtime/Core/Identity.cs
index 2df440eb1..3c2e1943a 100644
--- a/src/Packages/Audience/Runtime/Core/Identity.cs
+++ b/src/Packages/Audience/Runtime/Core/Identity.cs
@@ -13,7 +13,7 @@ namespace Immutable.Audience
     // Reset() at startup to ensure a clean state in that scenario.
     internal sealed class Identity
     {
-        // In-memory cache — volatile so background threads always see the latest write.
+        // In-memory cache. Volatile so background threads always see the latest write.
         private static volatile string? _cachedId;
         private static readonly object _sync = new object();
 
@@ -66,11 +66,11 @@ internal static void ClearCache()
             if (!consent.CanTrack())
                 return null;
 
-            // Fast path — already loaded this session, no lock needed.
+            // Fast path: already loaded this session, no lock needed.
             if (_cachedId != null)
                 return _cachedId;
 
-            // Slow path — first call or after Reset(). Only one thread does the work.
+            // Slow path: first call or after Reset(). Only one thread does the work.
             lock (_sync)
             {
                 // Re-check after acquiring the lock in case another thread beat us here.
@@ -82,14 +82,14 @@ internal static void ClearCache()
 
                 var filePath = AudiencePaths.IdentityFile(persistentDataPath);
 
-                // Returning player — read the ID we wrote on a previous launch.
+                // Returning player: read the ID we wrote on a previous launch.
                 if (File.Exists(filePath))
                 {
                     _cachedId = File.ReadAllText(filePath).Trim();
                     return _cachedId;
                 }
 
-                // New install — generate a UUID and persist it atomically.
+                // New install: generate a UUID and persist it atomically.
                 // Write to a .tmp file first so a crash mid-write leaves no corrupt file.
                 var newId = Guid.NewGuid().ToString();
                 var tmpPath = filePath + ".tmp";
@@ -101,7 +101,7 @@ internal static void ClearCache()
                 }
                 catch (IOException)
                 {
-                    // Unexpected — file appeared between our Exists check and Move (shouldn't happen in practice).
+                    // Unexpected: file appeared between our Exists check and Move (shouldn't happen in practice).
                     // Delete and retry to ensure a clean state.
                     File.Delete(filePath);
                     File.Move(tmpPath, filePath);
@@ -128,7 +128,7 @@ internal static void Reset(string persistentDataPath)
                 }
                 catch (Exception e) when (e is FileNotFoundException || e is DirectoryNotFoundException)
                 {
-                    // File was never written (e.g. consent was None) — nothing to do.
+                    // File was never written (e.g. consent was None). Nothing to do.
                 }
             }
         }
diff --git a/src/Packages/Audience/Runtime/Core/Session.cs b/src/Packages/Audience/Runtime/Core/Session.cs
index 434d43098..c7c091921 100644
--- a/src/Packages/Audience/Runtime/Core/Session.cs
+++ b/src/Packages/Audience/Runtime/Core/Session.cs
@@ -18,7 +18,7 @@ namespace Immutable.Audience
     //
     // 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
+    // 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
@@ -63,7 +63,7 @@ internal void 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
+            // trailing callback sends a heartbeat for the old session, and the
             // backend receives it before the new session_start.
             Timer? oldTimer;
             lock (_lock)
@@ -77,7 +77,7 @@ internal void Start()
                 }
             }
 
-            // 500ms budget — double-Start is a misuse path.
+            // 500ms budget. Double-Start is a misuse path.
             TimerDisposal.DisposeAndWait(oldTimer, TimeSpan.FromMilliseconds(500));
 
             // Phase 2: populate new state. Re-check _disposed (may have flipped during drain).
@@ -112,7 +112,7 @@ internal void Pause()
                 // when End fires while paused), over-crediting engagement.
                 if (_pausedAt.HasValue)
                 {
-                    Log.Debug("Session: Pause while already paused — ignoring.");
+                    Log.Debug("Session: Pause while already paused. Ignoring.");
                     return;
                 }
                 _pausedAt = _getUtcNow();
@@ -248,7 +248,7 @@ internal void OnHeartbeat()
         }
 
         // Stops exceptions from the track callback from reaching upstream.
-        // Heartbeat runs on a background timer — an uncaught exception there
+        // Heartbeat runs on a background timer, where an uncaught exception
         // 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)
diff --git a/src/Packages/Audience/Runtime/Events/TypedEvents.cs b/src/Packages/Audience/Runtime/Events/TypedEvents.cs
index f4b3dce1c..ccf549137 100644
--- a/src/Packages/Audience/Runtime/Events/TypedEvents.cs
+++ b/src/Packages/Audience/Runtime/Events/TypedEvents.cs
@@ -84,7 +84,7 @@ public class Progression : IEvent
         public Dictionary<string, object> ToProperties()
         {
             if (Status is null)
-                throw new ArgumentException("Progression.Status is required — set it before calling Track(IEvent)");
+                throw new ArgumentException("Progression.Status is required. Set it before calling Track(IEvent).");
 
             var props = new Dictionary<string, object>
             {
@@ -169,11 +169,11 @@ public class Resource : IEvent
         public Dictionary<string, object> ToProperties()
         {
             if (Flow is null)
-                throw new ArgumentException("Resource.Flow is required — set it before calling Track(IEvent)");
+                throw new ArgumentException("Resource.Flow is required. Set it before calling Track(IEvent).");
             if (string.IsNullOrEmpty(Currency))
-                throw new ArgumentException("Resource.Currency is required — set a non-empty string before calling Track(IEvent)");
+                throw new ArgumentException("Resource.Currency is required. Set a non-empty string before calling Track(IEvent).");
             if (Amount is null)
-                throw new ArgumentException("Resource.Amount is required — set it before calling Track(IEvent)");
+                throw new ArgumentException("Resource.Amount is required. Set it before calling Track(IEvent).");
 
             var props = new Dictionary<string, object>
             {
@@ -248,7 +248,7 @@ public Dictionary<string, object> ToProperties()
                 throw new ArgumentException(
                     $"Purchase.Currency '{Currency}' must be a three-letter uppercase ISO 4217 code");
             if (Value is null)
-                throw new ArgumentException("Purchase.Value is required — set it before calling Track(IEvent)");
+                throw new ArgumentException("Purchase.Value is required. Set it before calling Track(IEvent).");
 
             var props = new Dictionary<string, object>
             {
diff --git a/src/Packages/Audience/Runtime/ImmutableAudience.cs b/src/Packages/Audience/Runtime/ImmutableAudience.cs
index d1b70138b..4e03b290b 100644
--- a/src/Packages/Audience/Runtime/ImmutableAudience.cs
+++ b/src/Packages/Audience/Runtime/ImmutableAudience.cs
@@ -18,7 +18,7 @@ public static class ImmutableAudience
         // `volatile _initialized` flag first so they never see a half-initialised state.
         // _state (consent level + userId) and _session are volatile so a write
         // on one thread is visible on any other. Every _state write happens
-        // under _initLock so level and userId always move together — callers
+        // under _initLock so level and userId always move together. Callers
         // never observe (Anonymous, oldUserId).
         //
         // Init / Shutdown / Reset / SetConsent hold _initLock only to flip state
@@ -117,7 +117,7 @@ public static int QueueSize
                 // Fence off the volatile _initialized load first, matching
                 // the protocol documented on the reference fields. Without
                 // this, a weak-memory-order reader could observe
-                // _initialized=true but _queue/_store still null — the ?.
+                // _initialized=true but _queue/_store still null; the ?.
                 // short-circuits to 0 in that case, but the inconsistency
                 // would break the protocol the file claims to follow.
                 if (!_initialized) return 0;
@@ -152,7 +152,7 @@ public static void Init(AudienceConfig config)
             {
                 if (_initialized)
                 {
-                    Log.Warn("Init called more than once — ignoring; original config retained. " +
+                    Log.Warn("Init called more than once. Ignoring; original config retained. " +
                              "Call Shutdown() first if reconfiguring is intended.");
                     return;
                 }
@@ -230,7 +230,7 @@ public static void Track(IEvent evt)
             if (!_initialized || !state.Level.CanTrack()) return;
             if (evt == null)
             {
-                Log.Warn("Track(IEvent) called with null event — dropping.");
+                Log.Warn("Track(IEvent) called with null event. Dropping.");
                 return;
             }
 
@@ -247,13 +247,13 @@ public static void Track(IEvent evt)
             }
             catch (Exception ex)
             {
-                Log.Warn($"Track(IEvent) — {evt.GetType().Name}.ToProperties()/EventName threw {ex.GetType().Name}: {ex.Message}. Dropping.");
+                Log.Warn($"Track(IEvent): {evt.GetType().Name}.ToProperties()/EventName threw {ex.GetType().Name}: {ex.Message}. Dropping.");
                 return;
             }
 
             if (string.IsNullOrEmpty(eventName))
             {
-                Log.Warn($"Track(IEvent) — {evt.GetType().Name}.EventName returned null or empty. Dropping.");
+                Log.Warn($"Track(IEvent): {evt.GetType().Name}.EventName returned null or empty. Dropping.");
                 return;
             }
 
@@ -277,7 +277,7 @@ public static void Track(string eventName, Dictionary<string, object>? propertie
             if (!_initialized || !state.Level.CanTrack()) return;
             if (string.IsNullOrEmpty(eventName))
             {
-                Log.Warn("Track(string) called with null or empty event name — dropping.");
+                Log.Warn("Track(string) called with null or empty event name. Dropping.");
                 return;
             }
 
@@ -321,14 +321,14 @@ public static void Identify(string userId, string identityType, Dictionary<strin
             // Validate inputs before consent so null-arg callers get the right warning.
             if (string.IsNullOrEmpty(userId))
             {
-                Log.Warn("Identify called with null or empty userId — dropping.");
+                Log.Warn("Identify called with null or empty userId. Dropping.");
                 return;
             }
 
             AudienceConfig? config;
             ConsentLevel level;
             // Update consent + userId under the init lock so they always move
-            // together — another thread reading _state never sees one half-updated.
+            // together; another thread reading _state never sees one half-updated.
             lock (_initLock)
             {
                 if (!_initialized) return;
@@ -336,7 +336,7 @@ public static void Identify(string userId, string identityType, Dictionary<strin
                 level = current.Level;
                 if (!level.CanIdentify())
                 {
-                    Log.Warn($"Identify discarded — requires Full consent, current is {level}");
+                    Log.Warn($"Identify discarded. Requires Full consent, current is {level}.");
                     return;
                 }
                 config = _config;
@@ -379,13 +379,13 @@ public static void Alias(string fromId, string fromType, string toId, string toT
 
             if (string.IsNullOrEmpty(fromId) || string.IsNullOrEmpty(toId))
             {
-                Log.Warn("Alias called with null or empty fromId/toId — dropping.");
+                Log.Warn("Alias called with null or empty fromId/toId. Dropping.");
                 return;
             }
             var state = _state;
             if (!state.Level.CanIdentify())
             {
-                Log.Warn($"Alias discarded — requires Full consent, current is {state.Level}");
+                Log.Warn($"Alias discarded. Requires Full consent, current is {state.Level}.");
                 return;
             }
 
@@ -422,7 +422,7 @@ public static void Reset()
                 _state = _state with { UserId = null };
 
                 // Swap under the lock so racing SetConsent/OnPause/OnResume see
-                // either the old, the new, or null — never a torn reference.
+                // either the old, the new, or null; never a torn reference.
                 _session = _state.Level.CanTrack() ? new Session(Track) : null;
                 newSession = _session;
             }
@@ -488,7 +488,7 @@ public static Task DeleteData(string? userId = null)
                 }
                 catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
                 {
-                    // Shutdown cancelled — caller is tearing down, no error fired.
+                    // Shutdown cancelled; caller is tearing down, no error fired.
                 }
                 catch (Exception ex)
                 {
@@ -534,7 +534,7 @@ public static void SetConsent(ConsentLevel level)
             // Identity methods hold their own _sync lock; disk I/O on a cold
             // cache (None → Anonymous/Full upgrade creates the UUID file) does
             // not block _initLock. A racing SetConsent may change _state
-            // between this read and our lock acquire — acceptable, the racing
+            // between this read and our lock acquire (acceptable, the racing
             // call fires its own PUT and our slightly-stale ID still
             // identifies the user.
             var anonymousIdForPut = snapshotPrevious == ConsentLevel.None
@@ -600,7 +600,7 @@ public static void SetConsent(ConsentLevel level)
             }
             catch (Exception ex) when (ex is IOException || ex is UnauthorizedAccessException)
             {
-                Log.Warn($"SetConsent — failed to persist consent level: {ex.GetType().Name}: {ex.Message}. " +
+                Log.Warn($"SetConsent: failed to persist consent level. {ex.GetType().Name}: {ex.Message}. " +
                          "In-memory level is updated but will revert on next launch.");
                 NotifyErrorCallback(config.OnError, AudienceErrorCode.ConsentPersistFailed,
                     $"Consent persist failed: {ex.Message}");
@@ -726,7 +726,7 @@ await transport.SendBatchAsync(cancellationToken).ConfigureAwait(false))
             }
             catch (ObjectDisposedException)
             {
-                // Concurrent Shutdown disposed the transport. Exit silently —
+                // Concurrent Shutdown disposed the transport. Exit silently;
                 // caller is tearing down.
             }
             finally
@@ -743,7 +743,7 @@ public static void Shutdown()
             // Fire session_end before taking _initLock. _initialized is still
             // true here so Track's CanTrack gate lets it through. Idempotent
             // under concurrent Shutdown / SetConsent(None) via the _sessionId
-            // reset inside EmitEndAndSeal — a second call finds _sessionId
+            // reset inside EmitEndAndSeal: a second call finds _sessionId
             // null and no-ops. Heartbeat timer drain still runs in Phase 2
             // via session.Dispose(); its re-emission inside End() also no-ops.
             _session?.EmitEndAndSeal();
@@ -770,7 +770,7 @@ public static void Shutdown()
                 // before the flag flip. Idempotent on the same instance (no-op
                 // via _sessionId null check); the slow path only runs when
                 // Reset fully completed its Start() between the outside-lock
-                // call above and this point — a narrow window.
+                // call above and this point (a narrow window).
                 _session?.EmitEndAndSeal();
 
                 // Flip the gate. Init / SetConsent / Reset acquiring after
@@ -810,7 +810,7 @@ public static void Shutdown()
             TimerDisposal.DisposeAndWait(timer, TimeSpan.FromSeconds(2));
 
             // Clear the gate in case WaitOne timed out with SendBatch still running
-            // — a later Init would otherwise be stranded at 1.
+            // (a later Init would otherwise be stranded at 1).
             Interlocked.Exchange(ref _sendInFlight, 0);
 
             queue?.Shutdown();
@@ -823,7 +823,7 @@ public static void Shutdown()
                     var send = transport.SendBatchAsync();
                     if (!send.Wait(timeoutMs))
                     {
-                        Log.Warn($"Shutdown flush exceeded {timeoutMs}ms — abandoning. " +
+                        Log.Warn($"Shutdown flush exceeded {timeoutMs}ms. Abandoning. " +
                                  "Queued events remain on disk and will retry on next startup.");
                     }
                 }
@@ -844,7 +844,7 @@ public static void Shutdown()
         }
 
         // -----------------------------------------------------------------
-        // Internal — shared with tests and AudienceUnityHooks
+        // Internal: shared with tests and AudienceUnityHooks
         // -----------------------------------------------------------------
 
         // Providers reassigned by SubsystemRegistration.
diff --git a/src/Packages/Audience/Runtime/Transport/EventQueue.cs b/src/Packages/Audience/Runtime/Transport/EventQueue.cs
index 7c457cbb1..2890542f6 100644
--- a/src/Packages/Audience/Runtime/Transport/EventQueue.cs
+++ b/src/Packages/Audience/Runtime/Transport/EventQueue.cs
@@ -50,8 +50,8 @@ internal EventQueue(DiskStore store, int flushIntervalSeconds, int flushSize)
         }
 
         // Approximate count of events currently in the in-memory queue
-        // awaiting drain to disk. Lock-free read on ConcurrentQueue.Count
-        // — a snapshot that can race with concurrent enqueue / dequeue.
+        // awaiting drain to disk. Lock-free read on ConcurrentQueue.Count:
+        // a snapshot that can race with concurrent enqueue / dequeue.
         // Good enough for status-panel display; not an invariant.
         internal int InMemoryCount => _memory.Count;
 
@@ -71,7 +71,7 @@ internal void Enqueue(Dictionary<string, object>? msg)
         }
 
         // Queues the message under the drain lock. The caller supplies a
-        // transform that runs while the lock is held — it can edit the
+        // 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
@@ -144,7 +144,7 @@ internal void Shutdown()
         {
             if (_disposed) return;
 
-            // Stop accepting new events first — closes the race window where
+            // Stop accepting new events first. This closes the race window where
             // events enqueued between Cancel and final drain would be lost.
             _disposed = true;
 
@@ -186,8 +186,8 @@ private void DrainMemoryToDisk()
                 {
                     try
                     {
-                        // Serialise on the drain thread, not on the caller thread —
-                        // keeps Track() lock-free and allocation-light.
+                        // Serialise on the drain thread, not on the caller thread.
+                        // Keeps Track() lock-free and allocation-light.
                         _store.Write(Json.Serialize(msg));
                     }
                     catch (IOException)
diff --git a/src/Packages/Audience/Runtime/Transport/HttpTransport.cs b/src/Packages/Audience/Runtime/Transport/HttpTransport.cs
index bec7805d2..6ed286c07 100644
--- a/src/Packages/Audience/Runtime/Transport/HttpTransport.cs
+++ b/src/Packages/Audience/Runtime/Transport/HttpTransport.cs
@@ -103,8 +103,8 @@ internal async Task<bool> SendBatchAsync(CancellationToken ct = default)
                 {
                     // Server accepted the batch. Count how many messages it
                     // rejected; if any, tell the studio via onError. Rejected
-                    // messages are validation failures — retrying won't help,
-                    // so the batch is deleted either way.
+                    // messages are validation failures, so retrying won't help.
+                    // The batch is deleted either way.
                     var rejected = await ParseRejectedCount(response, ct).ConfigureAwait(false);
                     _store.Delete(batch);
                     ResetBackoff();
@@ -118,7 +118,7 @@ internal async Task<bool> SendBatchAsync(CancellationToken ct = default)
                 {
                     // 429 is retryable (RFC 6585). Keep the batch, honor Retry-After
                     // if present else use the existing 5xx backoff schedule. No
-                    // onError — next flush tick retries; persistent rate-limits
+                    // onError. The next flush tick retries; persistent rate-limits
                     // surface as a growing on-disk queue.
                     var retryAfter = HttpRetry.ParseRetryAfter(response);
                     if (retryAfter.HasValue)
@@ -129,8 +129,8 @@ internal async Task<bool> SendBatchAsync(CancellationToken ct = default)
                 else if (statusCode >= 400 && statusCode < 500)
                 {
                     // 4xx (non-429): server rejected the payload. Drop it (retry
-                    // won't help) and reset backoff — server is healthy, our data
-                    // was the problem. Capture the response body so the caller's
+                    // won't help) and reset backoff. The server is healthy, our
+                    // data was the problem. Capture the response body so the caller's
                     // OnError surfaces the server's reason string ("unknown
                     // publishable key", "missing field X", etc.) rather than a
                     // bare status code.
@@ -154,7 +154,7 @@ internal async Task<bool> SendBatchAsync(CancellationToken ct = default)
             {
                 // Caller cancelled the token (e.g. on shutdown). Events stay
                 // on disk, no failure recorded. Rethrow so the caller's send
-                // loop exits — swallowing here returns `true`, and the loop
+                // loop exits. Swallowing here returns `true`, and the loop
                 // would re-enter on the same cancelled token and spin because
                 // the batch is still on disk. HttpClient timeouts throw the
                 // same exception but without ct.IsCancellationRequested set,
@@ -212,7 +212,7 @@ private void RecordFailure()
             lock (_backoffLock)
             {
                 var now = _getUtcNow();
-                if (now < _nextAttemptAt) return;  // inside prior window — don't compound backoff
+                if (now < _nextAttemptAt) return;  // inside prior window; don't compound backoff
                 _consecutiveFailures++;
                 _nextAttemptAt = now.AddMilliseconds(BackoffMsLocked());
             }
@@ -259,7 +259,7 @@ private void ResetBackoff()
                 catch (IOException)
                 {
                     // Transient disk race: the file was deleted or locked between
-                    // ReadBatch and now. Safe to skip — the remaining paths in the
+                    // ReadBatch and now. Safe to skip; the remaining paths in the
                     // batch may still read fine. Non-IOException failures escape
                     // and are handled by the caller (SendBatchAsync) as a batch-
                     // wide storage error.
@@ -273,7 +273,7 @@ private void ResetBackoff()
         }
 
         // Reads the response body and pulls out the "rejected" count. Returns
-        // 0 if the body is missing or unreadable — the body is only for
+        // 0 if the body is missing or unreadable. The body is only for
         // reporting, so failing to read it must not break the success path.
         private static async Task<int> ParseRejectedCount(HttpResponseMessage response, CancellationToken ct = default)
         {
@@ -312,7 +312,7 @@ private static async Task<int> ParseRejectedCount(HttpResponseMessage response,
 
         // Best-effort body extraction; null on read failure.
         // Catches narrowed so OOM, OperationCanceledException, and ThreadAbortException
-        // propagate — body extraction must not mask process-level faults.
+        // propagate. Body extraction must not mask process-level faults.
         private static async Task<string?> ReadBodyForErrorAsync(HttpResponseMessage response)
         {
             try
diff --git a/src/Packages/Audience/Runtime/Unity/DeviceCollector.cs b/src/Packages/Audience/Runtime/Unity/DeviceCollector.cs
index d9926770c..62be7dfa8 100644
--- a/src/Packages/Audience/Runtime/Unity/DeviceCollector.cs
+++ b/src/Packages/Audience/Runtime/Unity/DeviceCollector.cs
@@ -92,7 +92,7 @@ internal static Dictionary<string, object> CollectGameLaunchProperties()
         private static string Truncate(string s, int max)
         {
             if (string.IsNullOrEmpty(s) || s.Length <= max) return s;
-            // Step back one if the cut would split a surrogate pair — leaving
+            // Step back one if the cut would split a surrogate pair. Leaving
             // a lone high-surrogate produces invalid UTF-16 on the wire.
             var cut = max;
             if (char.IsHighSurrogate(s[cut - 1])) cut--;
diff --git a/src/Packages/Audience/Runtime/Unity/UnityLifecycleBridge.cs b/src/Packages/Audience/Runtime/Unity/UnityLifecycleBridge.cs
index 919a58860..a133c8bd6 100644
--- a/src/Packages/Audience/Runtime/Unity/UnityLifecycleBridge.cs
+++ b/src/Packages/Audience/Runtime/Unity/UnityLifecycleBridge.cs
@@ -33,7 +33,7 @@ private void OnApplicationPause(bool paused)
         }
 
 #if !UNITY_ANDROID && !UNITY_IOS
-        // Desktop only — mobile focus events fire spuriously (soft keyboard, notifications).
+        // Desktop only. Mobile focus events fire spuriously (soft keyboard, notifications).
         private void OnApplicationFocus(bool hasFocus)
         {
             if (!hasFocus) ImmutableAudience.OnPause();
diff --git a/src/Packages/Audience/Runtime/Utility/Json.cs b/src/Packages/Audience/Runtime/Utility/Json.cs
index 6ee4d515d..724061431 100644
--- a/src/Packages/Audience/Runtime/Utility/Json.cs
+++ b/src/Packages/Audience/Runtime/Utility/Json.cs
@@ -141,7 +141,7 @@ private static void GuardDepth(int depth)
         {
             if (depth >= MaxDepth)
                 throw new FormatException(
-                    $"JSON nesting exceeds {MaxDepth} levels — refusing to serialize. " +
+                    $"JSON nesting exceeds {MaxDepth} levels. Refusing to serialize. " +
                     "Check for a cyclic or excessively deep dictionary/list.");
         }
 
@@ -149,7 +149,7 @@ private static HashSet<object> EnterContainer(object container, HashSet<object>?
         {
             visited ??= new HashSet<object>(ReferenceEqualityComparer.Instance);
             if (!visited.Add(container))
-                throw new FormatException("JSON graph contains a cycle — refusing to serialize.");
+                throw new FormatException("JSON graph contains a cycle. Refusing to serialize.");
             return visited;
         }
 
diff --git a/src/Packages/Audience/Runtime/Utility/TimerDisposal.cs b/src/Packages/Audience/Runtime/Utility/TimerDisposal.cs
index baeea4c76..c40febff9 100644
--- a/src/Packages/Audience/Runtime/Utility/TimerDisposal.cs
+++ b/src/Packages/Audience/Runtime/Utility/TimerDisposal.cs
@@ -22,7 +22,7 @@ internal static bool DisposeAndWait(Timer? timer, TimeSpan timeout)
             {
                 if (!timer.Dispose(handle))
                 {
-                    // Already disposed — no signal to wait for.
+                    // Already disposed: no signal to wait for.
                     return true;
                 }
 
diff --git a/src/Packages/Audience/Tests/Runtime/ConstantsTests.cs b/src/Packages/Audience/Tests/Runtime/ConstantsTests.cs
index 03d641382..fd7258eae 100644
--- a/src/Packages/Audience/Tests/Runtime/ConstantsTests.cs
+++ b/src/Packages/Audience/Tests/Runtime/ConstantsTests.cs
@@ -75,7 +75,7 @@ private static string ReadPackageJson()
             // package directory. Originally this hard-coded four "../" hops
             // which only worked when bin/ sat inside Tests/. Directory.Build
             // .props redirects bin/ to the repo-root /artifacts/ folder so
-            // dotnet build outputs don't leak into Unity's scan path — the
+            // dotnet build outputs don't leak into Unity's scan path; the
             // relative walk no longer resolves to the package. Searching
             // upward is robust against either layout.
             var current = new DirectoryInfo(TestContext.CurrentContext.TestDirectory);
diff --git a/src/Packages/Audience/Tests/Runtime/Core/SessionTests.cs b/src/Packages/Audience/Tests/Runtime/Core/SessionTests.cs
index b8913741d..dd4864b46 100644
--- a/src/Packages/Audience/Tests/Runtime/Core/SessionTests.cs
+++ b/src/Packages/Audience/Tests/Runtime/Core/SessionTests.cs
@@ -189,7 +189,7 @@ public void Pause_CalledTwice_SecondCallIsNoOp()
             session.Pause(); // first Pause anchors _pausedAt at T=5
 
             now = now.AddSeconds(3);
-            session.Pause(); // second Pause at T=8 — should be ignored
+            session.Pause(); // second Pause at T=8, should be ignored
 
             now = now.AddSeconds(2); // paused for another 2s
             session.Resume(); // resume at T=10, pause window spans T=5 to T=10
@@ -251,7 +251,7 @@ public void Resume_NegativePauseDuration_ClampsAccumulatorToZero()
             // pause duration was clamped to 0, so engaged seconds = 7 - 0 = 7.
             // Without the clamp, _accumulatedPause would be -5, the
             // subtraction would over-credit, and engaged seconds would
-            // be 12 — well outside the wall-clock window.
+            // be 12, well outside the wall-clock window.
             Assert.AreEqual(7L, duration,
                 "negative pauseDuration must clamp to zero so the accumulator does not over-credit engagement");
         }
@@ -290,8 +290,8 @@ public void End_ClockRewindsWhilePaused_DoesNotInflateDuration()
             // fires End). Without the livePause ≥ 0 clamp in
             // ComputeEngagedSecondsLocked, livePause goes negative and,
             // being subtracted, inflates duration past the wall-clock window
-            // — the final engagedSeconds ≥ 0 clamp only catches negatives,
-            // not over-credit. Sabotage: removing the livePause clamp lets
+            // (the final engagedSeconds ≥ 0 clamp only catches negatives,
+            // not over-credit). Sabotage: removing the livePause clamp lets
             // this test report 15s instead of the ≤ 5s wall-clock window.
             var now = new DateTime(2026, 4, 20, 12, 0, 0, DateTimeKind.Utc);
             DateTime Clock() => now;
@@ -377,7 +377,7 @@ public void End_AfterExtendedPauseRollover_ReportsPrePauseDuration()
             now = now.AddSeconds(10); // 10 s engaged before pause
             session.Pause();
 
-            now = now.AddSeconds(40); // 40 s paused — extended (>30 s threshold)
+            now = now.AddSeconds(40); // 40 s paused: extended (>30 s threshold)
             session.Resume();
 
             var sessionEnd = _events.First(e => e.name == "session_end");
@@ -761,7 +761,7 @@ public void OnPauseAndOnResume_RouteThroughActiveSession()
             //
             // Signature-pin (rename / parameter change) also still holds
             // via the direct ImmutableAudience.OnPause() / OnResume() call
-            // sites — a change there breaks compilation here.
+            // sites; a change there breaks compilation here.
             ImmutableAudience.Init(MakeConfig());
 
             ImmutableAudience.OnPause();
@@ -770,7 +770,7 @@ public void OnPauseAndOnResume_RouteThroughActiveSession()
 
             Assert.IsFalse(
                 ReadQueueFiles().Any(c => c.Contains("\"session_heartbeat\"")),
-                "OnPause must route to Session.Pause — paused sessions quiesce heartbeats");
+                "OnPause must route to Session.Pause; paused sessions quiesce heartbeats");
 
             ImmutableAudience.OnResume();
             ImmutableAudience.InvokeSessionHeartbeatForTesting();
@@ -778,7 +778,7 @@ public void OnPauseAndOnResume_RouteThroughActiveSession()
 
             Assert.IsTrue(
                 ReadQueueFiles().Any(c => c.Contains("\"session_heartbeat\"")),
-                "OnResume must route to Session.Resume — resumed sessions emit heartbeats again");
+                "OnResume must route to Session.Resume; resumed sessions emit heartbeats again");
 
             ImmutableAudience.Shutdown();
         }
@@ -798,7 +798,7 @@ public void Reset_StartsNewSession_DoesNotEmitSessionEnd()
         {
             // Reset must end the old session and start a new one so subsequent
             // Track events carry a fresh sessionId alongside the fresh
-            // anonymousId — matches Web SDK reset() semantics. The old
+            // anonymousId; matches Web SDK reset() semantics. The old
             // session's session_end is enqueued by Session.Dispose but wiped
             // by the PurgeAll in Reset, so the wire sees only a session_start
             // for the new session.
diff --git a/src/Packages/Audience/Tests/Runtime/DeleteDataTests.cs b/src/Packages/Audience/Tests/Runtime/DeleteDataTests.cs
index 9c930e292..54233e1ce 100644
--- a/src/Packages/Audience/Tests/Runtime/DeleteDataTests.cs
+++ b/src/Packages/Audience/Tests/Runtime/DeleteDataTests.cs
@@ -113,7 +113,7 @@ public void DeleteData_NoUserId_WithExistingAnonymousId_FiresDelete_WithAnonymou
         [Test]
         public void DeleteData_NoUserId_NoAnonymousId_DoesNotFireRequest()
         {
-            // Use Consent.None so Init's game_launch is suppressed — the only way
+            // Use Consent.None so Init's game_launch is suppressed: the only way
             // to guarantee no HTTP request fires at all.
             var handler = new CapturingHandler();
             ImmutableAudience.Init(MakeConfig(handler, ConsentLevel.None));
@@ -165,7 +165,7 @@ public async Task DeleteData_ReturnsTask_ThatCompletesAfterRequest()
         [Test]
         public void DeleteData_BeforeInit_ReturnsCompletedTask()
         {
-            // Not initialised — must not throw, must return a completed Task.
+            // Not initialised: must not throw, must return a completed Task.
             ImmutableAudience.ResetState();
 
             var task = ImmutableAudience.DeleteData(userId: "player-42");
diff --git a/src/Packages/Audience/Tests/Runtime/Events/MessageBuilderTests.cs b/src/Packages/Audience/Tests/Runtime/Events/MessageBuilderTests.cs
index 378b67c7c..abe12f166 100644
--- a/src/Packages/Audience/Tests/Runtime/Events/MessageBuilderTests.cs
+++ b/src/Packages/Audience/Tests/Runtime/Events/MessageBuilderTests.cs
@@ -124,7 +124,7 @@ public void Track_MessageId_IsUniquePerCall()
         [Test]
         public void AllMessages_EventTimestamp_IsRoundTripIso8601Utc()
         {
-            // SDK uses DateTime.UtcNow.ToString("o") — round-trippable ISO 8601.
+            // SDK uses DateTime.UtcNow.ToString("o"): round-trippable ISO 8601.
             // Backend schema requires this exact shape; previously only verified
             // indirectly via backend rejection.
             var before = DateTime.UtcNow.AddSeconds(-2);
diff --git a/src/Packages/Audience/Tests/Runtime/IdentityTypeTests.cs b/src/Packages/Audience/Tests/Runtime/IdentityTypeTests.cs
index 746b7e3f7..d20939613 100644
--- a/src/Packages/Audience/Tests/Runtime/IdentityTypeTests.cs
+++ b/src/Packages/Audience/Tests/Runtime/IdentityTypeTests.cs
@@ -29,8 +29,8 @@ public void ToLowercaseString_UnknownValue_Throws()
             //
             // An unknown enum value must throw so the bug surfaces at the
             // cast site. Returning a default string instead would ship the
-            // event with a blank identityType — invisible to the deletion
-            // lookup — and hide the bug.
+            // event with a blank identityType (invisible to the deletion
+            // lookup) and hide the bug.
             var invalid = (IdentityType)999;
 
             Assert.Throws<ArgumentOutOfRangeException>(() => invalid.ToLowercaseString());
diff --git a/src/Packages/Audience/Tests/Runtime/ImmutableAudienceTests.cs b/src/Packages/Audience/Tests/Runtime/ImmutableAudienceTests.cs
index 60b2e4cb2..b57166c56 100644
--- a/src/Packages/Audience/Tests/Runtime/ImmutableAudienceTests.cs
+++ b/src/Packages/Audience/Tests/Runtime/ImmutableAudienceTests.cs
@@ -41,7 +41,7 @@ private AudienceConfig MakeConfig(ConsentLevel consent = ConsentLevel.Anonymous)
                 PublishableKey = "pk_imapik-test-key1",
                 Consent = consent,
                 PersistentDataPath = _testDir,
-                FlushIntervalSeconds = 600, // large — we flush manually in tests
+                FlushIntervalSeconds = 600, // large; we flush manually in tests
                 FlushSize = 1000,
                 HttpHandler = new KeepOnDiskHandler()
             };
@@ -205,7 +205,7 @@ public void ContextProvider_Set_MergesFieldsIntoEveryMessageContext()
         public void ContextProvider_Set_MergesOnIdentifyPath()
         {
             // EnqueueIdentity must merge ContextProvider fields the same way
-            // EnqueueTrack does — otherwise Identify events ship without the
+            // EnqueueTrack does. Otherwise Identify events ship without the
             // userAgent / locale / timezone / screen context every other
             // event carries.
             ImmutableAudience.ContextProvider = () => new Dictionary<string, object>
@@ -317,7 +317,7 @@ public void Track_IEventMissingRequiredField_DropsWithWarn()
             Log.Writer = lines.Add;
             try
             {
-                // Purchase with no Value set — ToProperties throws; Track must
+                // Purchase with no Value set: ToProperties throws; Track must
                 // catch, warn, and drop rather than ship an incomplete event.
                 Assert.DoesNotThrow(() => ImmutableAudience.Track(new Purchase { Currency = "USD" }));
                 Assert.That(lines, Has.Some.Contains("Purchase"));
@@ -346,7 +346,7 @@ public void Track_NullOrEmptyEventName_DoesNotEnqueue()
             // Assert the invariant directly: no enqueued message carries a
             // null or empty eventName. Earlier versions counted files
             // before/after the Track calls, which raced with the async
-            // disk drain — Init enqueues session_start + game_launch, and
+            // disk drain: Init enqueues session_start + game_launch, and
             // Shutdown adds session_end, so the file count after Shutdown
             // is deterministic but the before-count is not. Counting is
             // the wrong axis: what the test actually wants to pin is
@@ -478,7 +478,7 @@ public void Init_ConcurrentCalls_OnlyOneSucceeds_OthersWarn()
         }
 
         // -----------------------------------------------------------------
-        // Track — custom events
+        // Track: custom events
         // -----------------------------------------------------------------
 
         [Test]
@@ -529,7 +529,7 @@ public void Track_ConsentNone_DoesNotEnqueue()
             var queueDir = AudiencePaths.QueueDir(_testDir);
             if (!Directory.Exists(queueDir))
             {
-                Assert.Pass("queue directory not created — no events");
+                Assert.Pass("queue directory not created; no events");
                 return;
             }
 
@@ -537,7 +537,7 @@ public void Track_ConsentNone_DoesNotEnqueue()
         }
 
         // -----------------------------------------------------------------
-        // Track — typed events
+        // Track: typed events
         // -----------------------------------------------------------------
 
         private class NullNameEvent : IEvent
@@ -697,7 +697,7 @@ public void Reset_DiscardsQueuedEventsOnDisk()
         }
 
         // -----------------------------------------------------------------
-        // SetConsent — purge + persistence
+        // SetConsent: purge + persistence
         // -----------------------------------------------------------------
 
         [Test]
@@ -723,7 +723,7 @@ public void SetConsent_DowngradeToNone_PurgesQueueOnDiskAndInMemory()
         public void SetConsent_DowngradeToNone_DropsInFlightTrack_ThatRacesThePurge()
         {
             // Reproduces the window where a Track call observed consent=Anonymous,
-            // built its message, and is about to enqueue — while a concurrent
+            // built its message, and is about to enqueue, while a concurrent
             // SetConsent(None) sets consent and purges. Without the re-check inside
             // the drain lock, the enqueue lands after the purge and the event leaks
             // to disk past revocation.
@@ -737,7 +737,7 @@ public void SetConsent_DowngradeToNone_DropsInFlightTrack_ThatRacesThePurge()
 
             // Gate the Track thread so it's poised to enqueue at the moment SetConsent
             // completes its purge. We approximate the race by kicking Track off a
-            // threadpool thread and racing SetConsent after a tiny stagger — if the
+            // threadpool thread and racing SetConsent after a tiny stagger; if the
             // re-check is missing, this leaks deterministically under contention over
             // repeated runs.
             var trackStarted = new ManualResetEventSlim(false);
@@ -789,7 +789,7 @@ public void SetConsent_DowngradeToNone_StressTest_NoLeak()
 
                 // All trackers spin up and block on the barrier so they all release
                 // simultaneously. The main thread joins the barrier too and fires
-                // SetConsent immediately after release — maximising contention.
+                // SetConsent immediately after release, maximising contention.
                 var barrier = new Barrier(trackersPerIteration + 1);
                 var trackers = new Task[trackersPerIteration];
                 for (int t = 0; t < trackersPerIteration; t++)
@@ -840,7 +840,7 @@ public void Init_ConcurrentWithSetConsent_LeavesConsistentState()
             //
             // Limitation: the race window is narrow and not deterministically
             // reproducible without a test hook inside Init. This is a
-            // probabilistic guard — many iterations of concurrent Init /
+            // probabilistic guard: many iterations of concurrent Init /
             // SetConsent(None) from two threads, asserting only that the
             // final state is consistent (consent is whichever the last lock
             // holder set, no exceptions escape, Init did not silently ignore
@@ -1078,7 +1078,7 @@ public void SetConsent_PersistsAcrossInit()
             ImmutableAudience.SetConsent(ConsentLevel.Full);
             ImmutableAudience.Shutdown();
 
-            // Re-init with the *original* (Anonymous) config — persisted Full should win.
+            // Re-init with the *original* (Anonymous) config. Persisted Full should win.
             ImmutableAudience.Init(MakeConfig(ConsentLevel.Anonymous));
 
             Assert.AreEqual(ConsentLevel.Full, ImmutableAudience.CurrentConsent,
@@ -1224,7 +1224,7 @@ public void Shutdown_ReleasesInitLock_BeforeBlockingTeardown()
         {
             // Hanging handler: the final flush inside Shutdown's Phase 2 will
             // block in transport.SendBatchAsync().Wait(timeoutMs). Pre-refactor,
-            // _initLock was held across that wait — SetConsent / Reset on another
+            // _initLock was held across that wait; SetConsent / Reset on another
             // thread would be stranded for the full ShutdownFlushTimeoutMs.
             var handler = new BlockingHandler();
             var config = MakeConfig();
@@ -1312,7 +1312,7 @@ public void FullToAnonymous_FutureTracksOmitUserId()
         }
 
         // -----------------------------------------------------------------
-        // SendBatch — overlapping timer tick guard
+        // SendBatch: overlapping timer tick guard
         // -----------------------------------------------------------------
 
         [Test]
@@ -1326,7 +1326,7 @@ public void SendBatch_ConcurrentTicks_OnlyOneReachesTransport()
             ImmutableAudience.Track("event_to_send");
             ImmutableAudience.FlushQueueToDiskForTesting();
 
-            // Kick off one SendBatch on a worker — it will block inside the
+            // Kick off one SendBatch on a worker. It will block inside the
             // handler until we signal, holding _sendInFlight = 1.
             var blocked = Task.Run(() => ImmutableAudience.SendBatchForTesting());
 
@@ -1334,7 +1334,7 @@ public void SendBatch_ConcurrentTicks_OnlyOneReachesTransport()
             Assert.IsTrue(handler.EnteredSendAsync.Wait(TimeSpan.FromSeconds(2)),
                 "first SendBatch should have reached the HTTP handler");
 
-            // Second tick while the first is still in flight — must return
+            // Second tick while the first is still in flight: must return
             // immediately without issuing another request.
             ImmutableAudience.SendBatchForTesting();
 
@@ -1366,7 +1366,7 @@ public void FlushAsync_ConcurrentCallers_OnlyOneReachesTransport()
             Assert.IsTrue(handler.EnteredSendAsync.Wait(TimeSpan.FromSeconds(2)),
                 "first FlushAsync should reach the HTTP handler");
 
-            // Second caller starts while the first holds the gate — it must
+            // Second caller starts while the first holds the gate; it must
             // wait, not issue a second request.
             var flush2 = Task.Run(() => ImmutableAudience.FlushAsync());
 
@@ -1410,7 +1410,7 @@ public async Task FlushAsync_CancelledToken_Terminates_DoesNotHotLoop()
             Assert.LessOrEqual(handler.CallCount, 1,
                 "a cancelled token must not drive repeated SendAsync attempts");
 
-            // Gate must be released by the finally block — a follow-up flush
+            // Gate must be released by the finally block; a follow-up flush
             // on an uncancelled token should proceed, proving _sendInFlight
             // is not stranded at 1.
             handler.AcceptNextAsSuccess = true;
diff --git a/src/Packages/Audience/Tests/Runtime/OfflineResilienceTests.cs b/src/Packages/Audience/Tests/Runtime/OfflineResilienceTests.cs
index 351280a46..b8d6f6715 100644
--- a/src/Packages/Audience/Tests/Runtime/OfflineResilienceTests.cs
+++ b/src/Packages/Audience/Tests/Runtime/OfflineResilienceTests.cs
@@ -103,7 +103,7 @@ public void Shutdown_DiskWritesBlocked_DoesNotThrow()
 
         [Test]
         [Ignore("Target behaviour: memory-only fallback without losing in-flight events. " +
-                "EventQueue currently drops on IOException — remove [Ignore] once it retains.")]
+                "EventQueue currently drops on IOException; remove [Ignore] once it retains.")]
         public void Track_DiskWritesBlocked_RetainsEventsInMemory_AndSurfacesOnError()
         {
             var errors = new ConcurrentBag<AudienceError>();
diff --git a/src/Packages/Audience/Tests/Runtime/PublishableKeyPrefixTests.cs b/src/Packages/Audience/Tests/Runtime/PublishableKeyPrefixTests.cs
index 7e329fb67..43d549afe 100644
--- a/src/Packages/Audience/Tests/Runtime/PublishableKeyPrefixTests.cs
+++ b/src/Packages/Audience/Tests/Runtime/PublishableKeyPrefixTests.cs
@@ -105,7 +105,7 @@ public void Init_TestKeyAgainstSandboxUrl_DoesNotWarn()
                 ImmutableAudience.Init(MakeConfig(TestPrefixKey, SandboxUrl));
 
                 Assert.That(lines.Where(l => l.Contains("BaseUrl")), Is.Empty,
-                    "test-key + sandbox-URL is the canonical pairing — no warning expected");
+                    "test-key + sandbox-URL is the canonical pairing; no warning expected");
             }
             finally { Log.Writer = null; }
         }
@@ -136,7 +136,7 @@ public void Init_NoBaseUrlOverride_DoesNotWarn()
                 ImmutableAudience.Init(MakeConfig(TestPrefixKey, baseUrl: null));
 
                 Assert.That(lines.Where(l => l.Contains("BaseUrl")), Is.Empty,
-                    "no override means no mismatch — no warning expected");
+                    "no override means no mismatch; no warning expected");
             }
             finally { Log.Writer = null; }
         }
diff --git a/src/Packages/Audience/Tests/Runtime/ThreadSafetyStressTests.cs b/src/Packages/Audience/Tests/Runtime/ThreadSafetyStressTests.cs
index b7c2e3e5d..9e9845c91 100644
--- a/src/Packages/Audience/Tests/Runtime/ThreadSafetyStressTests.cs
+++ b/src/Packages/Audience/Tests/Runtime/ThreadSafetyStressTests.cs
@@ -54,7 +54,7 @@ private AudienceConfig MakeConfig(ConsentLevel consent = ConsentLevel.Full) =>
             };
 
         // -----------------------------------------------------------------
-        // Track — sustained throughput across N threads
+        // Track: sustained throughput across N threads
         // -----------------------------------------------------------------
 
         [Test]
@@ -108,7 +108,7 @@ private void RunSustainedTrackLoad(int threadCount, int durationSeconds)
             sw.Stop();
 
             CollectionAssert.IsEmpty(exceptions,
-                $"sustained Track load must not throw — observed {exceptions.Count} exception(s)");
+                $"sustained Track load must not throw; observed {exceptions.Count} exception(s)");
 
             int totalFired = firedPerThread.Sum();
             double perThreadRate = totalFired / (double)threadCount / sw.Elapsed.TotalSeconds;
@@ -117,7 +117,7 @@ private void RunSustainedTrackLoad(int threadCount, int durationSeconds)
                 $"Track threads={threadCount} fired={totalFired} elapsed={sw.Elapsed.TotalSeconds:F2}s rate={perThreadRate:F0}/sec/thread");
 
             Assert.GreaterOrEqual(perThreadRate, 200,
-                $"sustained Track throughput collapsed below floor — observed {perThreadRate:F0}/sec/thread");
+                $"sustained Track throughput collapsed below floor; observed {perThreadRate:F0}/sec/thread");
 
             ImmutableAudience.FlushQueueToDiskForTesting();
 
@@ -196,7 +196,7 @@ public void TrackIdentifySetConsent_ConcurrentLoad_NoRaceExceptions()
             foreach (var th in threads) th.Join();
 
             CollectionAssert.IsEmpty(exceptions,
-                $"concurrent Track / Identify / SetConsent must not throw — observed {exceptions.Count} exception(s)");
+                $"concurrent Track / Identify / SetConsent must not throw; observed {exceptions.Count} exception(s)");
             Assert.IsTrue(ImmutableAudience.Initialized,
                 "SDK should remain initialised after the mixed-workload run");
 
@@ -207,7 +207,7 @@ public void TrackIdentifySetConsent_ConcurrentLoad_NoRaceExceptions()
         }
 
         // -----------------------------------------------------------------
-        // Allocation profile — bounded growth + no Gen 2 churn
+        // Allocation profile: bounded growth + no Gen 2 churn
         // -----------------------------------------------------------------
 
         [Test]
diff --git a/src/Packages/Audience/Tests/Runtime/Transport/DiskStoreTests.cs b/src/Packages/Audience/Tests/Runtime/Transport/DiskStoreTests.cs
index 3a6d6378e..d3ee554a5 100644
--- a/src/Packages/Audience/Tests/Runtime/Transport/DiskStoreTests.cs
+++ b/src/Packages/Audience/Tests/Runtime/Transport/DiskStoreTests.cs
@@ -61,7 +61,7 @@ public void ReadBatch_ReturnsOldestFirst()
             var batch = _store.ReadBatch(10);
 
             Assert.AreEqual(3, batch.Count);
-            // Filenames are {ticks}_{uuid}.json — lexicographic sort == oldest first
+            // Filenames are {ticks}_{uuid}.json: lexicographic sort == oldest first
             var names = batch.Select(Path.GetFileName).ToList();
             Assert.That(names, Is.Ordered.Ascending);
         }
diff --git a/src/Packages/Audience/Tests/Runtime/Transport/HttpTransportTests.cs b/src/Packages/Audience/Tests/Runtime/Transport/HttpTransportTests.cs
index fbd31d803..d049705eb 100644
--- a/src/Packages/Audience/Tests/Runtime/Transport/HttpTransportTests.cs
+++ b/src/Packages/Audience/Tests/Runtime/Transport/HttpTransportTests.cs
@@ -71,7 +71,7 @@ public async Task SendBatchAsync_200_SendsGzippedPayloadWithCorrectHeaders()
             string? capturedKey = null;
             string? capturedContentType = null;
             string? capturedContentEncoding = null;
-            // Read body inside the callback — the request content is disposed after SendAsync returns.
+            // Read body inside the callback. The request content is disposed after SendAsync returns.
             var handler = new MockHandler(HttpStatusCode.OK, "{\"accepted\":1,\"rejected\":0}",
                 onRequest: req =>
                 {
@@ -197,7 +197,7 @@ public async Task SendBatchAsync_4xx_DeletesFilesAndResetsBackoff()
 
             await transport.SendBatchAsync();
 
-            Assert.AreEqual(0, _store.Count(), "4xx should delete files — won't succeed on retry");
+            Assert.AreEqual(0, _store.Count(), "4xx should delete files; won't succeed on retry");
             Assert.IsFalse(transport.IsInBackoffWindow);
             Assert.IsNotNull(reportedError);
             Assert.AreEqual(AudienceErrorCode.ValidationRejected, reportedError!.Code);
@@ -218,7 +218,7 @@ public async Task SendBatchAsync_429_NoRetryAfter_KeepsFilesAndUsesExpoBackoff_N
             Assert.AreEqual(1, _store.Count(), "429 must keep files for retry");
             Assert.IsTrue(transport.IsInBackoffWindow);
             Assert.AreEqual(5_000, transport.BackoffMs);
-            Assert.IsNull(reportedError, "429 is transient — must not fire onError");
+            Assert.IsNull(reportedError, "429 is transient; must not fire onError");
         }
 
         [Test]
@@ -444,7 +444,7 @@ public async Task BackoffMs_DoesNotEscalateWhileInsidePreviousWindow()
             Assert.AreEqual(firstDeadline, transport.NextAttemptAt,
                 "NextAttemptAt should not move when the window hasn't elapsed");
 
-            // Another premature retry — still no escalation.
+            // Another premature retry: still no escalation.
             Advance(3_000);
             await transport.SendBatchAsync();
             Assert.AreEqual(5_000, transport.BackoffMs);
@@ -509,7 +509,7 @@ public async Task SendBatchAsync_HttpClientTimeout_TreatedAsNetworkError()
         {
             // Regression guard: HttpClient.Timeout throws TaskCanceledException, which
             // derives from OperationCanceledException. Without a `when (ct.IsCancellationRequested)`
-            // guard, timeouts would be silently swallowed as "shutdown" — no backoff, no error
+            // guard, timeouts would be silently swallowed as "shutdown": no backoff, no error
             // callback, next cycle hot-loops. This test ensures timeouts flow through the
             // NetworkError path.
             _store.Write("{\"type\":\"track\"}");
@@ -519,7 +519,7 @@ public async Task SendBatchAsync_HttpClientTimeout_TreatedAsNetworkError()
             using var transport = new HttpTransport(_store, "pk_imapik-test-key1",
                 onError: e => reportedError = e, handler: handler);
 
-            // Pass default CancellationToken so ct.IsCancellationRequested is false — this
+            // Pass default CancellationToken so ct.IsCancellationRequested is false; this
             // simulates a real HttpClient timeout (not a caller-initiated cancellation).
             await transport.SendBatchAsync();
 
@@ -537,7 +537,7 @@ public async Task SendBatchAsync_CallerCancelled_Throws_DoesNotDeleteOrRecordFai
             // swallowed the exception, SendBatchAsync would return `true`
             // with the batch still on disk, and a FlushAsync loop watching
             // that return value would re-enter on the same cancelled token
-            // forever — nothing ever drains, nothing ever throws.
+            // forever: nothing ever drains, nothing ever throws.
             _store.Write("{\"type\":\"track\"}");
 
             var handler = new MockHandler(() => throw new OperationCanceledException("simulated"));
@@ -563,8 +563,8 @@ public async Task SendBatchAsync_CallerCancelled_Throws_DoesNotDeleteOrRecordFai
             }
 
             Assert.AreEqual(1, _store.Count(), "cancelled send must not delete the batch");
-            Assert.IsFalse(transport.IsInBackoffWindow, "cancel is not a failure — no backoff engaged");
-            Assert.IsNull(reportedError, "cancel is caller-initiated — no onError fires");
+            Assert.IsFalse(transport.IsInBackoffWindow, "cancel is not a failure; no backoff engaged");
+            Assert.IsNull(reportedError, "cancel is caller-initiated; no onError fires");
         }
 
         [Test]
@@ -582,11 +582,11 @@ public async Task IsInBackoffWindow_ClearsAfterNextAttemptAtElapses()
             Assert.IsTrue(transport.IsInBackoffWindow, "within window immediately after failure");
             Assert.AreEqual(now.AddMilliseconds(5_000), transport.NextAttemptAt);
 
-            // Advance the clock just before NextAttemptAt — still backing off.
+            // Advance the clock just before NextAttemptAt: still backing off.
             now = now.AddMilliseconds(4_999);
             Assert.IsTrue(transport.IsInBackoffWindow);
 
-            // Advance past NextAttemptAt — window closed, next send may proceed.
+            // Advance past NextAttemptAt: window closed, next send may proceed.
             now = now.AddMilliseconds(2);
             Assert.IsFalse(transport.IsInBackoffWindow, "window closes at NextAttemptAt");
         }
diff --git a/src/Packages/Audience/Tests/Runtime/Utility/JsonTests.cs b/src/Packages/Audience/Tests/Runtime/Utility/JsonTests.cs
index 9ad95adeb..178325c91 100644
--- a/src/Packages/Audience/Tests/Runtime/Utility/JsonTests.cs
+++ b/src/Packages/Audience/Tests/Runtime/Utility/JsonTests.cs
@@ -136,7 +136,7 @@ public void Serialize_FloatValue_NormalRange()
         [Test]
         public void Serialize_FloatValue_LargeExponent_PreservesValue()
         {
-            // 1e30f in scientific notation is valid JSON — must not be silently zeroed
+            // 1e30f in scientific notation is valid JSON; must not be silently zeroed
             var data = new Dictionary<string, object> { { "v", 1e30f } };
             var result = Json.Serialize(data);
             var serialised = result.Substring(result.IndexOf(':') + 1, result.Length - result.IndexOf(':') - 2);
@@ -147,7 +147,7 @@ public void Serialize_FloatValue_LargeExponent_PreservesValue()
         [Test]
         public void Serialize_FloatValue_SmallNegativeExponent_PreservesValue()
         {
-            // 1e-30f — the old F6 fallback turned this into "0.000000"
+            // 1e-30f: the old F6 fallback turned this into "0.000000"
             var data = new Dictionary<string, object> { { "v", 1e-30f } };
             var result = Json.Serialize(data);
             var serialised = result.Substring(result.IndexOf(':') + 1, result.Length - result.IndexOf(':') - 2);