chore!: remove the v2 legacy queue migration for v4

[turnipdabeets]

💡 Motivation and Context

Part of the 4.0 stack, on top of #873 (chore/v4-remove-deprecated). It removes the migration of the event queue written by the 2.x Objective-C SDK.

• What the v2 queue is: a single file, posthog.queue.plist, written only by SDK 2.x. No 3.x release writes it; 3.0.0 shipped in January 2024.
• What changes: the SDK no longer imports events from that file. It still deletes the file, so nothing is left orphaned on disk.
• What is lost: unsent events queued by a 2.x SDK, for an app that updates straight from 2.x to 4.0.
• What is kept: distinct ID, anonymous ID, groups and cached feature flags. They are carried by migrateLegacyStorage, which this PR does not touch.
• The removed migration was already lossy: it named each file by event timestamp, so events in the same millisecond overwrote each other. In the device test, 4 queued v2 events became 2 files.

Migrations that stay, because recent 3.x releases still depend on them:

Migration	Shipped
posthog.queueFolder to posthog.queueFolder.uuid	3.48.3
posthog.replayFolder to posthog.replayFolder.uuid	3.59.0
migrateLegacyStorage (bundle-ID folder to per-token folder)	3.20.0
App-group container merge	3.27.0

No public API change.

Cross-SDK note: posthog-android still has its equivalent legacy-queue import (flushLegacyEvents). The persistent-storage sdk-spec asks SDKs to support migrations when storage layout changes but sets no retention period, so removing this one in a major is a mild divergence from Android.

The second commit stops PostHogEvent.fromJSON from reading the 2.x event fields (a top-level $set and message_id). Only events copied unchanged by the removed migration used them. An event in that format is still read and sent, but with a new UUID and without its top-level $set.

💚 How did you test it?

• make test passes locally (910 tests, macOS), including a new test that a v2 queue file is deleted without importing its events.
• make apiCheck reports the snapshot up to date.
• Second commit: make test passes (912 Swift Testing tests, 167 XCTest), including two new tests that the 2.x fields are ignored and uuid is still read; make apiCheck reports the snapshot up to date.
• iOS simulator (iPhone 17 Pro, iOS 26.4): 2 failures of 1283, both in PostHogLogsQueueTests. Rerunning that suite three times failed 2 of 3 on this branch and 2 of 3 on the base commit, with different tests each time. The logs queue has no old storage keys and never reaches the changed line.
• Physical device (iPhone 14 Pro Max, iOS 26.5.2): seeded with an app built against the 2.1.0 SDK source (identify plus three captures, offline), then PostHogExample installed over it from the base commit and from this branch.

	Base commit	This branch
Crash or setup problem	none	none
Distinct ID and anonymous ID	preserved	preserved
posthog.queue.plist after setup	gone	gone
v2 events in the new queue	2 of 4	none
New events	queued	queued and sent

• A test in PostHogStorageTest seeds posthog.queue.plist in the legacy base folder, then builds PostHogStorage and the events queue. It checks that the storage migration moves the file and the queue deletes it without importing anything.
• Not run: make testDowngradeCompatibility, make build for the other platforms.
• Not tested: app-group and extension setups, a 2.x app configured with crypto, and 2.x on tvOS.

📝 Checklist

• I reviewed the submitted code.
• I added tests to verify the changes.
• I updated the docs if needed.
• No breaking change or entry added to the changelog.

If releasing new changes

• Ran pnpm changeset to generate a changeset file

The changeset is major and was written by hand in the changeset format.

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

• Written with Claude Code (Opus 5.5).
• The file is deleted rather than ignored because migrateLegacyStorage would otherwise keep moving it into the per-token folder, where only reset() would remove it.
• The four newer migrations were checked individually (trigger, data moved, release) before deciding that only the plist import is removable.

🤖 Generated with Claude Code

[github-actions]

posthog-ios Compliance Report

Date: 2026-10-06 22:16:32 UTC
Duration: 210169ms

⚠️ Some Tests Failed

44/45 tests passed, 1 failed

---

Capture Tests

⚠️ 28/29 tests passed, 1 failed

View Details

Test	Status	Duration
Format Validation.Event Has Required Fields	✅	2729ms
Format Validation.Event Has Uuid	✅	2665ms
Format Validation.Event Has Lib Properties	✅	247ms
Format Validation.Distinct Id Is String	✅	2675ms
Format Validation.Token Is Present	✅	2788ms
Format Validation.Custom Properties Preserved	✅	2864ms
Format Validation.Event Has Timestamp	✅	317ms
Retry Behavior.Retries On 503	✅	5328ms
Retry Behavior.Does Not Retry On 400	✅	2384ms
Retry Behavior.Does Not Retry On 401	✅	4736ms
Retry Behavior.Respects Retry After Header	✅	7686ms
Retry Behavior.Implements Backoff	✅	21368ms
Retry Behavior.Retries On 500	✅	9450ms
Retry Behavior.Retries On 502	✅	9266ms
Retry Behavior.Retries On 504	✅	9233ms
Retry Behavior.Max Retries Respected	❌	15402ms
Deduplication.Generates Unique Uuids	✅	533ms
Deduplication.Preserves Uuid On Retry	✅	9168ms
Deduplication.Preserves Uuid And Timestamp On Retry	✅	16687ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry	✅	7915ms
Deduplication.No Duplicate Events In Batch	✅	2885ms
Deduplication.Different Events Have Different Uuids	✅	2915ms
Compression.Sends Gzip When Enabled	✅	2653ms
Batch Format.Uses Proper Batch Structure	✅	401ms
Batch Format.Flush With No Events Sends Nothing	✅	332ms
Batch Format.Multiple Events Batched Together	✅	2920ms
Error Handling.Does Not Retry On 403	✅	4797ms
Error Handling.Does Not Retry On 413	✅	4920ms
Error Handling.Retries On 408	✅	9302ms

Failures

retry_behavior.max_retries_respected

Expected 4 requests, got 5

Feature_Flags Tests

✅ 16/16 tests passed

View Details

Test	Status	Duration
Request Payload.Request With Person Properties Device Id	✅	2791ms
Request Payload.Flags Request Uses V2 Query Param	✅	2672ms
Request Payload.Flags Request Hits Flags Path Not Decide	✅	2817ms
Request Payload.Flags Request Omits Authorization Header	✅	2734ms
Request Payload.Token In Flags Body Matches Init	✅	2902ms
Request Payload.Groups Round Trip	✅	2660ms
Request Payload.Groups Default To Empty Object	✅	2813ms
Request Payload.Person Properties Distinct Id Auto Populated When Caller Omits It	✅	2823ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False	✅	2808ms
Request Payload.Disable Geoip Omitted Defaults To False	✅	2739ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key	✅	2877ms
Request Lifecycle.No Flags Request On Init Alone	✅	96ms
Request Lifecycle.No Flags Request On Normal Capture	✅	2770ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests	✅	5532ms
Request Lifecycle.Mock Response Value Is Returned To Caller	✅	2906ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event	✅	3021ms

[dustinbyrne]

Looks good for the v4 retirement of legacy queue import and decoding. No blocking findings.

One non-blocking migration note: 3.x imported v2 records unchanged, so a 2→3→4 upgrade with undelivered imported records also loses root $set handling and generates fresh UUIDs when decoding message_id-only records. These are consequences of retiring the legacy format, not requests to retain it. Consider narrowing the changeset’s ‘Apps on any 3.x release are not affected’ wording to events created by 3.x.

No new downgrade crash issue identified. Existing startup smoke tests pass for 3.48.0, 3.48.3, and 3.58.0; this does not promise identical behavior or queue delivery after downgrade.

Agent-led review; conclusions discussed with and approved by @dustinbyrne before posting. The human considered migration intent and no-crash downgrade compatibility. Validation was static inspection and existing CI evidence; no tests were executed by the reviewer.

[turnipdabeets]

@dustinbyrne Thanks! Narrowed the changeset wording to events created by 3.x, and called out that pending 2.x events imported by 3.x lose the $set / message_id handling (62f33bb).

For sizing: over the last 7 days (US), 2.x is ~1% of iOS SDK users (~153K) and ~0.3% of events, across 79 apps — almost all on 2.1.0. 55 of those apps have never shipped 3.x. Only events still unsent on disk at the moment of a direct 2.x → 4.0 update are lost; identity is still migrated.