feat(audience): add DiskStore and EventQueue for persistent event batching (SDK-127)

[nattb8]

Summary

• Adds DiskStore (Runtime/Transport/DiskStore.cs): file-per-event persistent store writing {ticks}_{uuid}.json files atomically to imtbl_audience/queue/; supports ReadBatch (oldest-first, max 100, stale-event pruning after 30 days), Delete, and Count; crash-safe (survives restarts by scanning the queue directory on init)
• Adds EventQueue (Runtime/Transport/EventQueue.cs): wraps ConcurrentQueue<string> with a background drain thread; flushes to DiskStore every FlushIntervalSeconds or when FlushSize events accumulate; FlushAsync() for on-demand drain; Shutdown()/Dispose() for clean exit with final flush
• Adds DiskStoreTests and EventQueueTests covering write, batch read, stale pruning, crash recovery, size-triggered flush, interval flush, shutdown, and post-shutdown enqueue

Test plan

• DiskStoreTests: write creates file, contents match JSON, batch returns oldest first, max size respected, clamped to MaxBatchSize, stale files excluded and deleted, Delete removes files, Count tracks file count, empty/zero cases, crash recovery
• EventQueueTests: enqueue + FlushAsync persists, multiple events, FlushSize auto-drain, Shutdown flushes remainder, double-shutdown safe, enqueue-after-shutdown ignored, interval auto-flush, Dispose flushes

🤖 Generated with Claude Code

---

Note

Medium Risk
Introduces new background-thread and on-disk persistence behavior that can affect event delivery reliability and performance (timing, race conditions, and file I/O edge cases), though changes are additive and covered by tests.

Overview
Adds a disk-backed batching layer to the Audience SDK by introducing DiskStore (file-per-event persistence under imtbl_audience/queue/, batched reads capped to Constants.MaxBatchSize, and automatic pruning of events older than Constants.StaleEventDays) and EventQueue (thread-safe in-memory enqueue with a background drain thread that flushes by size threshold or time interval, plus Shutdown/Dispose for final flush).

Includes new NUnit runtime tests covering atomic writes, ordering and batch sizing, stale-file cleanup and crash recovery for DiskStore, plus flush triggers, interval draining, and shutdown/dispose behavior for EventQueue.

^{Reviewed by Cursor Bugbot for commit 14b57a1. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 14b57a1. Configure here.}

[cursor]

Integer overflow in flush interval kills drain thread

Medium Severity

Math.Max(1, flushIntervalSeconds) * 1000 performs unchecked int multiplication that silently overflows for flushIntervalSeconds values ≥ 2,147,484 (~24.8 days), producing a negative _flushIntervalMs. When the drain thread calls _flushGate.Wait(_flushIntervalMs) with that negative value, it throws ArgumentOutOfRangeException (only -1 is valid for negative). Since DrainLoop has no try-catch, the background thread dies silently and events are never persisted to disk. A user setting Int32.MaxValue to disable interval flushing would trigger this immediately.

Additional Locations (1)

• src/Packages/Audience/Runtime/Transport/EventQueue.cs#L99-L100

 

^{Reviewed by Cursor Bugbot for commit 14b57a1. Configure here.}