perf(audit): flush work moves off the main thread (A-06)

Non-WebGL: a dedicated background thread owns FlushBatchCore (JSON + SHA-256 + file
append), waking on a 500ms tick or Dispose; WebGL keeps the frame-budgeted main-thread
path (no threads there). All prior semantics preserved: bounded queue with drop-oldest
+ audited drop marker, seq/prevHash commit only after successful append with requeue on
failure, rotation anchors, Dispose joins the worker with a drain deadline, FlushForTesting
stays a synchronous barrier. Unity Debug.Log calls reachable from the worker are deferred
to a main-thread log pump. +concurrent 4-thread Record burst test (chain verifies).

NOTE: committed under the editor-unavailable window; the mandatory gate (full EditMode +
PlayMode FastNoLlm) runs on the next editor start — tracked in TODO.

Author: NeoXider

Assets/CoreAiUnity/Runtime/Source/Features/Audit/AuditLogWriter.cs

@@ -15,6 +15,7 @@ namespace CoreAI.Features.Audit
     public sealed class AuditLogWriter : IAuditLog, IDisposable
     {
         private readonly ConcurrentQueue<AuditEntry> _queue = new();
+        private readonly ConcurrentQueue<(LogType Level, string Message)> _pendingLogs = new();
         private readonly string _folder;
         private readonly string _filePath;
         private readonly JsonSerializerSettings _jsonSettings;
@@ -26,11 +27,15 @@ public sealed class AuditLogWriter : IAuditLog, IDisposable
         private long _droppedCount;
         private long _lastReportedDroppedCount;
         private CancellationTokenSource _cts;
+#if !UNITY_WEBGL
+        private Thread _worker;
+#endif
 
         private const long MaxFileSize = 50 * 1024 * 1024;
         private const int FlushIntervalMs = 500;
         private const int MaxQueueSize = 10_000;
         private static readonly TimeSpan DisposeDrainDeadline = TimeSpan.FromSeconds(2);
+        private static readonly TimeSpan WorkerJoinTimeout = DisposeDrainDeadline + TimeSpan.FromMilliseconds(500);
 
         /// <summary>
         /// Test-only hook: when set and returns true, the next file append throws instead of touching
@@ -57,7 +62,16 @@ internal AuditLogWriter(string folder)
 
             ResumeChain();
             _cts = new CancellationTokenSource();
+
+            // Serialization + SHA-256 + file I/O run off the main thread wherever real threads
+            // exist. WebGL has no threads, so it keeps the original main-thread, frame-budgeted
+            // UniTask.Delay loop instead.
+#if UNITY_WEBGL
             FlushLoop(_cts.Token).Forget();
+#else
+            _worker = new Thread(WorkerLoop) { IsBackground = true, Name = "CoreAI-AuditLogWriter" };
+            _worker.Start();
+#endif
         }
 
         internal string FilePath => _filePath;
@@ -93,16 +107,32 @@ private void EnqueueRaw(AuditEntry entry)
 
         public void Dispose()
         {
+            // Cancelling wakes the worker's WaitHandle immediately (no need to wait for the next
+            // 500ms tick); the worker then drains the queue itself, bounded by DisposeDrainDeadline.
             _cts?.Cancel();
+
+#if !UNITY_WEBGL
+            bool joined = _worker == null || _worker.Join(WorkerJoinTimeout);
+            if (!joined || !_queue.IsEmpty)
+            {
+                // Worker didn't finish in time (or never started) — fall back to draining on the
+                // calling thread so entries are not silently lost.
+                DrainOnDispose();
+            }
+#else
+            DrainOnDispose();
+#endif
+
+            DrainPendingLogs();
             _cts?.Dispose();
             _cts = null;
-            DrainOnDispose();
         }
 
         /// <summary>Synchronously flushes the queue. Used by tests that need deterministic writes.</summary>
         internal void FlushForTesting()
         {
             FlushBatch();
+            DrainPendingLogs();
         }
 
         /// <summary>
@@ -308,6 +338,8 @@ private string Rotate()
             return Path.GetFileName(rotated);
         }
 
+#if UNITY_WEBGL
+        /// <summary>WebGL has no threads, so the flush tick stays on the main thread (player loop).</summary>
         private async UniTaskVoid FlushLoop(CancellationToken ct)
         {
             while (!ct.IsCancellationRequested)
@@ -316,13 +348,73 @@ private async UniTaskVoid FlushLoop(CancellationToken ct)
                 {
                     await UniTask.Delay(FlushIntervalMs, cancellationToken: ct);
                     FlushBatch();
+                    DrainPendingLogs();
                 }
                 catch (OperationCanceledException)
                 {
                     break;
                 }
             }
         }
+#else
+        /// <summary>
+        /// Background flush loop: wakes every <see cref="FlushIntervalMs"/> or immediately when
+        /// <see cref="_cts"/> is cancelled (Dispose). Owns <see cref="_seq"/>/<see cref="_prevHash"/>
+        /// exclusively via <see cref="_flushGate"/> — Record() only ever enqueues.
+        /// Must not call any UnityEngine API directly; log messages are deferred via
+        /// <see cref="EnqueueLog"/> and emitted on the main thread instead.
+        /// </summary>
+        private void WorkerLoop()
+        {
+            CancellationToken ct = _cts.Token;
+            while (!ct.WaitHandle.WaitOne(FlushIntervalMs))
+            {
+                FlushBatch();
+            }
+
+            // Stop requested: drain whatever remains, bounded by DisposeDrainDeadline so a stuck
+            // disk (or a producer that never stops enqueuing) cannot hang application exit forever.
+            DateTime start = DateTime.UtcNow;
+            while (!_queue.IsEmpty)
+            {
+                FlushBatch();
+                if (DateTime.UtcNow - start >= DisposeDrainDeadline)
+                {
+                    EnqueueLog(LogType.Warning, "[AuditLogWriter] Dispose drain deadline (2s) reached with entries still queued.");
+                    break;
+                }
+            }
+        }
+#endif
+
+        /// <summary>Queues a log message for emission on the main thread (see <see cref="DrainPendingLogs"/>).</summary>
+        private void EnqueueLog(LogType level, string message)
+        {
+            _pendingLogs.Enqueue((level, message));
+        }
+
+        /// <summary>
+        /// Emits log messages queued by the background worker. Unity's Debug.Log family must run on
+        /// the main thread, so callers (log pump, FlushForTesting, Dispose) must all be main-thread.
+        /// </summary>
+        private void DrainPendingLogs()
+        {
+            while (_pendingLogs.TryDequeue(out (LogType Level, string Message) log))
+            {
+                switch (log.Level)
+                {
+                    case LogType.Warning:
+                        Debug.LogWarning(log.Message);
+                        break;
+                    case LogType.Error:
+                        Debug.LogError(log.Message);
+                        break;
+                    default:
+                        Debug.Log(log.Message);
+                        break;
+                }
+            }
+        }
 
         /// <summary>Serializes all flush entry points (timer loop, Dispose, FlushForTesting) so they cannot interleave.</summary>
         private void FlushBatch()
@@ -357,7 +449,7 @@ private void FlushBatchCore()
                 }
                 catch (Exception ex)
                 {
-                    Debug.LogWarning($"[AuditLogWriter] Rotation failed, re-queuing {batch.Count} pending entr{(batch.Count == 1 ? "y" : "ies")}: {ex.Message}");
+                    EnqueueLog(LogType.Warning, $"[AuditLogWriter] Rotation failed, re-queuing {batch.Count} pending entr{(batch.Count == 1 ? "y" : "ies")}: {ex.Message}");
                     RequeueFront(batch);
                     return;
                 }
@@ -411,7 +503,7 @@ private void FlushBatchCore()
             }
             catch (Exception ex)
             {
-                Debug.LogWarning($"[AuditLogWriter] Write failed, re-queuing {batch.Count} entr{(batch.Count == 1 ? "y" : "ies")}: {ex.Message}");
+                EnqueueLog(LogType.Warning, $"[AuditLogWriter] Write failed, re-queuing {batch.Count} entr{(batch.Count == 1 ? "y" : "ies")}: {ex.Message}");
                 RequeueFront(batch);
             }
         }

Assets/CoreAiUnity/Tests/EditMode/Audit/AuditLogWriterEditModeTests.cs

@@ -2,6 +2,7 @@
 using System.Collections.Generic;
 using System.IO;
 using System.Linq;
+using System.Threading.Tasks;
 using CoreAI.Audit;
 using CoreAI.Features.Audit;
 using NUnit.Framework;
@@ -106,7 +107,8 @@ public void Dispose_WithQueuedEntries_DrainsEntireQueueToFile()
             RecordN(_writer, 500);
             string path = _writer.FilePath;
 
-            // No FlushForTesting() — Dispose alone must drain the whole backlog, not one batch.
+            // No FlushForTesting() — Dispose alone must join the background worker and have it
+            // drain the whole backlog, not one batch (see AuditLogWriter.WorkerLoop).
             _writer.Dispose();
             _writer = null;
 
@@ -117,6 +119,40 @@ public void Dispose_WithQueuedEntries_DrainsEntireQueueToFile()
             Assert.IsTrue(result.Ok, result.Error);
         }
 
+        [Test]
+        public void ConcurrentRecord_FromFourThreads_AllEntriesPresentAndChainVerifies()
+        {
+            _writer = new AuditLogWriter(_testFolder);
+            const int perThread = 250;
+            const int threadCount = 4;
+
+            Task[] tasks = new Task[threadCount];
+            for (int t = 0; t < threadCount; t++)
+            {
+                int threadIndex = t;
+                tasks[t] = Task.Run(() =>
+                {
+                    for (int i = 0; i < perThread; i++)
+                    {
+                        _writer.Record(AuditEntry.ForToolCall(
+                            seq: 0, traceId: $"trace-{threadIndex}-{i}", actor: "creator", model: "gpt-4",
+                            promptHash: "ph", toolName: "test_tool", args: $"{{\"i\":{i}}}",
+                            policyDecision: "allowed", result: "ok", resultDetail: "", durationMs: i));
+                    }
+                });
+            }
+
+            Task.WaitAll(tasks);
+
+            _writer.FlushForTesting();
+
+            List<AuditEntry> entries = AuditLogVerifier.ReadAll(_writer.FilePath);
+            Assert.AreEqual(perThread * threadCount, entries.Count);
+
+            AuditVerifyResult result = AuditLogVerifier.Verify(_writer.FilePath);
+            Assert.IsTrue(result.Ok, result.Error);
+        }
+
         [Test]
         public void WriteFailure_RequeuesBatch_ChainStillVerifiesAfterRecovery()
         {