[posthog]

Why

The on-feature-flags spec records Android's only listener surfaces as the config field PostHogConfig.onFeatureFlags and the reloadFeatureFlags(...) completion, and Behavior item 5 names browser and iOS as the only SDKs that invoke a listener registered after flags are already loaded.

posthog-android#878 (merged into the 4.0 line) changes that. It adds PostHog.onFeatureFlags(PostHogFeatureFlagsCallback) — on the instance and the static facade — returning a PostHogFeatureFlagsSubscription with unsubscribe(), replays the current flags to a late subscriber, and delivers on the main thread. It matches posthog-ios 4.0's onFeatureFlags(_:) and posthog-js's onFeatureFlags, which the spec already records as method-style surfaces.

What changed in the spec

• Surface variants: Android gains the 4.0 method-style registration and its subscription handle; the config field and reload completion stay recorded as the single config-time callback.
• Behavior item 5: Android's onFeatureFlags(...) registration joins browser and iOS as a surface that replays current values to a late-registered listener. Android's config field and reload completion are explicitly not in that group.
• Concurrency: records Android 4.0's thread split — onFeatureFlags(...) listeners on the main thread, config callback and reload completion on the background thread — the same split posthog-ios makes.
• Two added requirements: a runtime listener registration stays active until unsubscribe() (including across a close()/setup() cycle), and a load already in flight when reset() or close() ran reaches no listener and is not replayed to a later one.

Proposed, applied and archived on this branch under openspec/changes/archive/2026-10-30-record-android-flag-listener-subscription/, as AGENTS.md asks. openspec validate on-feature-flags --type spec --strict passes.

Uncertain / for review

• The in-flight-load rule is derived from posthog-android#878 alone. It was not checked against posthog-ios or posthog-js source. It is stated as canonical because delivering the discarded identity's flags is a defect on any platform, but it is the part most worth a second look. Same for "a registration survives close()/setup()".
• Overlaps #158, which edits the same Surface variants and Behavior item 4 for the flags-loaded result. docs(flags): record the flags-loaded result Android and Flutter now pass #158 deliberately left item 5 alone ("neither SDK is recorded as [replaying]"), which was true when it was written; posthog-android#878 landed after it. Expect a small conflict in the Android surface-variant bullet — whichever lands second should keep both the PostHogFeatureFlagsCallback payload shape from docs(flags): record the flags-loaded result Android and Flutter now pass #158 and the subscription surface from here.
• The three new scenarios live in spec.md only; acceptance/ has no harness steps for a teardown/re-setup cycle or for a load completing after reset().

---

Created with PostHog Desktop

🤖 Generated with Claude Code