[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. 4.0 removes PostHogConfig.onFeatureFlags (recorded by docs(flags): record the mobile majors' flag API surfaces #164, merged into this branch); reloadFeatureFlags(...) stays as a one-off completion.
• 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 reload completion is explicitly not in that group.
• Concurrency: records Android 4.0's thread split: onFeatureFlags(...) listeners run on the main thread and the 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.

Conformance (checked 2026-11-03)

Requirement	posthog-android 4.0	posthog-ios 4.0	posthog-js	posthog_flutter 6.0
Registration survives close() / setup()	Pass	Pass	Pass	Pass
In-flight load across reset() / close() not delivered	Pass	Fails for reset()	Pass	Pass

posthog-js drops a superseded load the same way Android does: _requestGeneration in browser-common is bumped in reset() and dispose(). posthog-ios writes a /flags response that was in flight at reset() to its cache and delivers it to listeners. That bug is already on iOS main and needs an SDK fix; the requirement is right. The change record (design.md, proposal.md) now says so.

For review

• 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