fix: Store event queue DB outside Documents and exclude from backup

[BrandonStalnaker]

Move the iOS SQLite queue to Application Support (with Documents migration), set NSURLIsExcludedFromBackupKey, and remove leftover SessionNumber files.

Background

• The iOS event queue SQLite database (mParticle{N}.db) was stored in Documents/ and was not marked with NSURLIsExcludedFromBackupKey, so the transient upload queue (sessions, events, device info, cookies, etc.) could be included in iCloud/iTunes backups.
• Documents/ is also the wrong place for SDK-managed support data under Apple’s filesystem guidance; Library/Application Support is preferred.
• This is a privacy hygiene improvement, not a remote exploit (access would require a device backup or app container).
• tvOS already uses Caches/ and should stay there: on physical Apple TV, Application Support is often unwritable, and local storage beyond a small NSUserDefaults budget is expected to be purgeable.

What Has Changed

• Store the iOS event queue DB under Library/Application Support/mParticle/ (tvOS remains on Caches/).
• On startup, migrate any existing mParticle*.db files (and sqlite sidecars) from Documents/ to Application Support; if both copies exist, keep Application Support and delete the Documents leftover.
• Set NSURLIsExcludedFromBackupKey on the Application Support mParticle directory and on the DB when it is opened.
• Delete leftover legacy Documents/SessionNumber files from the old session-count feature.
• Update schema migration to use the new database directory, and add unit coverage for path selection, Documents → Application Support migration, backup exclusion, and SessionNumber cleanup.

Checklist

• I have performed a self-review of my own code.
• I have made corresponding changes to the documentation.
• I have added tests that prove my fix is effective or that my feature works.
• I have tested this locally.

Reference Issue (For employees only. Ignore if you are an outside contributor)

• Closes https://go/j/[ticket-number]

[cursor]

PR Summary

Medium Risk
Changes local persistence paths and startup migration for all iOS installs upgrading from Documents; failure handling is defensive but incorrect migration could affect queued events until the next successful launch.

Overview
Moves the iOS event-queue SQLite database from Documents to Library/Application Support/mParticle (tvOS still uses Caches), and keeps transient queue data out of device backups.

On init, the SDK runs Documents → Application Support migration for mParticle*.db and sqlite sidecars, prefers an existing Application Support copy, drops orphan Documents sidecars instead of attaching them, and falls back to Documents if the move fails so queued events are not lost. It also removes legacy Documents/SessionNumber files and sets NSURLIsExcludedFromBackupKey on the support directory and on the DB when opened.

Schema migration (MPDatabaseMigrationController) now resolves old DB paths via Application Support first, then Documents, so v30→v31 still runs when directory migration left a DB in Documents. +databaseDirectoryPath is exposed on the persistence controller API.

Unit tests cover path selection, directory migration edge cases, backup exclusion, Documents-only schema migration, and SessionNumber cleanup.

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

[github-actions]

📦 SDK Size Impact Report

Measures how much the SDK adds to an app's size (with-SDK minus without-SDK).

Metric	Target Branch	This PR	Change
App Bundle Impact	1.79 MB	1.79 MB	+N/A
Executable Impact	848 bytes	848 bytes	+N/A
XCFramework Size	6.48 MB	6.49 MB	+8 KB

➡️ SDK size impact change is minimal.

Raw measurements

Target branch (main):

{"baseline_app_size_kb":84,"baseline_executable_size_bytes":75464,"with_sdk_app_size_kb":1920,"with_sdk_executable_size_bytes":76312,"sdk_impact_kb":1836,"sdk_executable_impact_bytes":848,"xcframework_size_kb":6636}

This PR:

{"baseline_app_size_kb":84,"baseline_executable_size_bytes":75464,"with_sdk_app_size_kb":1920,"with_sdk_executable_size_bytes":76312,"sdk_impact_kb":1836,"sdk_executable_impact_bytes":848,"xcframework_size_kb":6644}

[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 720d536. Configure here.}