feat(events): persist events to disk so they survive the process (tier 3)

[abelonogov-ld]

Third in the event-durability stack, on top of #536. Recorded events go to an on-disk log rather than an in-memory buffer, so an application that dies moments after recording one still reports it: the next run delivers what the last one left behind.

What changes

EventStore is a new on-disk log, with capacity, framing, interrupted-log recovery, and multi-process safety. NullEventStore stands in where the platform gave the SDK nowhere to write, which is the behaviour the SDK had before.

Recording no longer encodes on the caller's thread. An evaluation appends to a held run and updates a counter; a commit turns the whole run into bytes at once. Recording a custom or identify event is a commit point, because an application reporting something it chose to report is saying it matters more than the microseconds it costs. Evaluations commit once pendingCommitThreshold of them accumulate, when a delivery starts, or on flush.

LDConfig.eventPersistence lets the application choose whether a commit point runs on the caller's thread (.immediate), off it (.deferred), or not at all (.disabled).

Delivery sends batches oldest first and stops at the first retryable failure, so the rest keep their place in the log instead of the SDK spending the session's requests on a service that is refusing them.

Reconciling with tier 2

Tier 2 replaced the delivery gate this branch was built on, so the merge had to pick one design rather than keep both.

Coalescing comes from tier 2: flushes arriving before a delivery starts join it, one already started is never joined, and nothing holds the drain back while a retry runs. What tier 2 did not need is a way to keep an in-flight batch from being sent twice — it empties its buffer before publishing, so a second delivery finds nothing. Here a batch stays on disk until its response arrives, which is what isDelivering guarded.

batchesInFlight takes its place. A delivery claims the batches it lists and releases them once it has an answer, so a later delivery still runs and still sends what it closed for itself; only the batches already on their way are left out. A caller whose own events are all that remain unsent is answered true, which is exactly the contract tier 2 documents: an answer is about the batch the caller's own delivery took, never one an earlier delivery lost.

The loss flag is now taken once per delivery rather than once per caller, so everyone joined to it hears about a loss instead of only whoever was answered first, and a scheduled delivery with no waiters leaves it for the caller who is owed it. This branch had also fixed the duplicate event reporter independently; that now comes from #537, so the local copy is gone.

Verification

• 824 tests pass on iOS; macOS and tvOS build. No new SwiftLint violations.
• The in-flight claim is load-bearing: removing the filter fails 5 tests, including does not send a batch again when a delivery is asked for while one is in flight.
• DiagnosticReporterSpec.testRetries flaked once under load and passed on re-run; it has a 0.1 s timeout and is unrelated to these changes.

---

Note

Overview
Adds Tier 3 event durability: analytics events can be appended to an on-disk log (EventStore with framed EventLogFormat, recovery of interrupted logs, and macOS file locking) so they survive process death and are delivered on the next launch. LDConfig.eventPersistence (.disabled / .deferred / .immediate) controls whether commits run off-thread, on the caller’s thread at track/identify, or not at all; default eventCapacity rises from 100 to 1000.

Flush behavior moves to LDClientFlush and grows: fire-and-forget flush(), flush(completion:) and flushAndWait(timeout:) (plus Obj-C equivalents) aggregate all environment clients and report delivery success via flushReportingOutcome. On iOS/tvOS background, the client commitAtCommitPoint() then flushes under a BackgroundActivity assertion so events are durable and a best-effort send runs before suspension.

Encoding path changes: EventJSONWriter, JSONWriter, ContextEncodingCache, and LDContextJSONWriter replace context copying for anonymous redaction—redaction is driven per event kind via Event.redactsAnonymousAttributes. ContextSummarizer keys contexts by full equality (with caps when too many distinct contexts) instead of contextHash() alone.

Supporting tweaks: DiagnosticCache uses UnfairLock instead of a serial queue; DarklyService.publishEventData invokes completion when the mobile key is missing so reporters do not stall.

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

[cursor]

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

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

^{Reviewed by Cursor Bugbot for commit 81a7856. Configure here.}

[cursor]

Closed event count races deliveries

Medium Severity

pendingBatches replaces closedEvents with a snapshot taken before it acquires bufferLock, while remove adjusts that counter from the network callback. Overlapping deliveries, which this change allows, can leave the counter too high and shed new events, or too low and store more than eventCapacity.

Additional Locations (1)

• LaunchDarkly/LaunchDarkly/ServiceObjects/EventStore.swift#L445-L461

 

^{Reviewed by Cursor Bugbot for commit 81a7856. Configure here.}