From cf13d4e83a42bd843c7a17dd1f4d5f9dfc888a22 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Fri, 6 Nov 2026 15:06:19 -0500 Subject: [PATCH 1/3] docs(flags): read an empty variant as disabled in get-feature-flag-result --- .../public/get-feature-flag-result.feature | 16 ++++++++++ .../.openspec.yaml | 2 ++ .../proposal.md | 30 +++++++++++++++++++ .../specs/get-feature-flag-result/spec.md | 29 ++++++++++++++++++ .../tasks.md | 10 +++++++ .../specs/get-feature-flag-result/spec.md | 29 ++++++++++++++++-- openspec/specs/is-feature-enabled/spec.md | 2 +- 7 files changed, 115 insertions(+), 3 deletions(-) create mode 100644 openspec/changes/archive/2026-11-06-empty-variant-disabled/.openspec.yaml create mode 100644 openspec/changes/archive/2026-11-06-empty-variant-disabled/proposal.md create mode 100644 openspec/changes/archive/2026-11-06-empty-variant-disabled/specs/get-feature-flag-result/spec.md create mode 100644 openspec/changes/archive/2026-11-06-empty-variant-disabled/tasks.md diff --git a/acceptance/public/get-feature-flag-result.feature b/acceptance/public/get-feature-flag-result.feature index 70721309..42204dbd 100644 --- a/acceptance/public/get-feature-flag-result.feature +++ b/acceptance/public/get-feature-flag-result.feature @@ -42,6 +42,22 @@ Feature: Get Feature Flag Result When get feature flag result "missing-flag" is called Then no feature flag result should be returned + # The value "" is the empty string, a variant PostHog no longer accepts for new flags. + @both + Scenario: Empty variant flag result is disabled + Given the SDK is initialized with token "test-token" + And cached feature flags are: + | key | value | + | legacy-ui | "" | + When get feature flag result "legacy-ui" is called + Then the returned feature flag result should include: + | field | value | + | key | legacy-ui | + | enabled | false | + And its variant should equal the JSON value "" + When is feature enabled "legacy-ui" is called + Then the returned enabled state should be false + # serialized_payload_json encodes the serialized input as a JSON string. @client Scenario Outline: Invalid cached payload does not change the flag result diff --git a/openspec/changes/archive/2026-11-06-empty-variant-disabled/.openspec.yaml b/openspec/changes/archive/2026-11-06-empty-variant-disabled/.openspec.yaml new file mode 100644 index 00000000..8a94d769 --- /dev/null +++ b/openspec/changes/archive/2026-11-06-empty-variant-disabled/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-11-06 diff --git a/openspec/changes/archive/2026-11-06-empty-variant-disabled/proposal.md b/openspec/changes/archive/2026-11-06-empty-variant-disabled/proposal.md new file mode 100644 index 00000000..68326b06 --- /dev/null +++ b/openspec/changes/archive/2026-11-06-empty-variant-disabled/proposal.md @@ -0,0 +1,30 @@ +## Why + +A flag whose variant is the empty string `""` reads as disabled from `isFeatureEnabled` in posthog-js (browser) and posthog-android, and in posthog-ios since [posthog-ios#1001](https://github.com/PostHog/posthog-ios/pull/1001). The same SDKs still report it as `enabled: true` from `getFeatureFlagResult`, and some include it in the flags-loaded callback, so one flag reads as both enabled and disabled depending on the call ([review thread](https://github.com/PostHog/posthog-ios/pull/1001#discussion_r4449050127)). posthog-js (browser) is consistent: `""` is disabled everywhere. + +PostHog has rejected new `""` variant keys since [PostHog/posthog#118803](https://github.com/PostHog/posthog/pull/118803) (2026-10-16), so only flags created earlier through the API, MCP or Terraform can hit this. + +The client-side flow of `is-feature-enabled` already says only a non-empty variant string is `true`. The server-side flow and `get-feature-flag-result` don't say what an empty variant is. + +## What Changes + +- **`is-feature-enabled`.** The server-side flow treats only a non-empty variant string as `true`, matching the client-side flow. +- **`get-feature-flag-result`.** A new requirement: a flag whose variant is `""` returns `enabled: false` with `variant: ""`, and `is-feature-enabled` returns `false` for it. Both flow descriptions say so. +- **Acceptance.** A matching scenario in `acceptance/public/get-feature-flag-result.feature`. + +## Capabilities + +### New Capabilities + +_None._ + +### Modified Capabilities + +- `get-feature-flag-result`: new **Empty variant reads as disabled** requirement, and the client and server flow descriptions. +- `is-feature-enabled`: the server-side flow description only (recorded in the `get-feature-flag-result` delta, since it has no requirement changes). + +## Impact + +- posthog-ios 4.0, posthog-android 4.0 and posthog-flutter 6.0 change `getFeatureFlagResult().enabled` (and Flutter desktop also `isFeatureEnabled`) to `false` for an empty variant in their major releases. +- `getFeatureFlag` and the `$feature_flag_called` response keep reporting `""`. +- Server SDKs were not audited for this case. diff --git a/openspec/changes/archive/2026-11-06-empty-variant-disabled/specs/get-feature-flag-result/spec.md b/openspec/changes/archive/2026-11-06-empty-variant-disabled/specs/get-feature-flag-result/spec.md new file mode 100644 index 00000000..ddfefdc2 --- /dev/null +++ b/openspec/changes/archive/2026-11-06-empty-variant-disabled/specs/get-feature-flag-result/spec.md @@ -0,0 +1,29 @@ +## ADDED Requirements + +### Requirement: Empty variant reads as disabled + +A flag whose value is the empty string `""` SHALL read as disabled. The SDK SHALL return a result with `enabled: false` and `variant: ""`, and `is-feature-enabled` SHALL return `false` for it, whether or not the caller supplies a default. + +#### Scenario: Empty variant flag result is disabled (@both) +- **GIVEN** a fresh SDK acceptance test harness +- **AND** the SDK clock is fixed at "2025-01-01T00:00:00Z" +- **AND** persistent storage is empty +- **AND** the mock PostHog server is reset +- **GIVEN** the SDK is initialized with token "test-token" +- **AND** cached feature flags are: + | key | value | + | legacy-ui | "" | +- **WHEN** get feature flag result "legacy-ui" is called +- **THEN** the returned feature flag result should include: + | field | value | + | key | legacy-ui | + | enabled | false | +- **AND** its variant should equal the JSON value "" +- **WHEN** is feature enabled "legacy-ui" is called +- **THEN** the returned enabled state should be false + +## Narrative alignment + +When syncing this delta, in both the client-side and server-side flows, replace "Multivariate flag → `enabled = true`, `variant = ''`" with "Multivariate flag with a non-empty variant → `enabled = true`, `variant = ''`" and add "Empty variant `''` → `enabled = false`, `variant = ''`". + +Also sync `is-feature-enabled`: in its server-side flow replace "variant string → `true`" with "non-empty variant string → `true`", matching its client-side flow. No `is-feature-enabled` requirement changes. diff --git a/openspec/changes/archive/2026-11-06-empty-variant-disabled/tasks.md b/openspec/changes/archive/2026-11-06-empty-variant-disabled/tasks.md new file mode 100644 index 00000000..fccee3a8 --- /dev/null +++ b/openspec/changes/archive/2026-11-06-empty-variant-disabled/tasks.md @@ -0,0 +1,10 @@ +## 1. Spec delta + +- [x] 1.1 Add the **Empty variant reads as disabled** requirement to `get-feature-flag-result`, and describe empty variants in its client and server flows +- [x] 1.2 Say "non-empty variant string" in the `is-feature-enabled` server-side flow +- [x] 1.3 Add the scenario to `acceptance/public/get-feature-flag-result.feature` + +## 2. Validation + +- [x] 2.1 Run `openspec validate --strict` +- [x] 2.2 Sync the delta into `specs/` and archive the change diff --git a/openspec/specs/get-feature-flag-result/spec.md b/openspec/specs/get-feature-flag-result/spec.md index 4774cf55..310d020b 100644 --- a/openspec/specs/get-feature-flag-result/spec.md +++ b/openspec/specs/get-feature-flag-result/spec.md @@ -94,7 +94,8 @@ type FeatureFlagResult = { 1. **Read the cached flag entry** from the SDK's local feature-flag cache. 2. **Assemble the result object** from the cached value and payload. - Boolean flag → `enabled = true|false`, `variant = undefined` - - Multivariate flag → `enabled = true`, `variant = ''` + - Multivariate flag with a non-empty variant → `enabled = true`, `variant = ''` + - Empty variant `''` → `enabled = false`, `variant = ''` - Payload is attached if available. 3. **Handle missing/unknown flags.** If the SDK cannot determine the flag from cache, return `undefined` / `nil` rather than a partial result object. 4. **Optionally emit `$feature_flag_called`.** In audited client SDKs this is on by default and can be suppressed with a per-call option in some implementations. @@ -106,7 +107,8 @@ type FeatureFlagResult = { 2. **Evaluate the flag** locally and/or remotely according to SDK configuration. 3. **Construct the result object** from the resolved value and payload. - Boolean flag → `enabled = true|false`, `variant = undefined` - - Multivariate flag → `enabled = true`, `variant = ''` + - Multivariate flag with a non-empty variant → `enabled = true`, `variant = ''` + - Empty variant `''` → `enabled = false`, `variant = ''` - Attach payload when available 4. **Return `undefined` / `None` when no result is available.** This usually covers unknown flags, unavailable caches, or evaluation failure with no fallback. 5. **Optionally emit `$feature_flag_called`.** Server SDKs commonly track accesses by default. @@ -286,3 +288,26 @@ A flag-reading API that lets the caller suppress `$feature_flag_called` for that - **WHEN** get feature flag result "beta-ui" is called without the feature flag event option - **THEN** the returned result value should be true - **AND** one event named "$feature_flag_called" should be enqueued + +### Requirement: Empty variant reads as disabled + +A flag whose value is the empty string `""` SHALL read as disabled. The SDK SHALL return a result with `enabled: false` and `variant: ""`, and `is-feature-enabled` SHALL return `false` for it, whether or not the caller supplies a default. + +#### Scenario: Empty variant flag result is disabled (@both) +- **GIVEN** a fresh SDK acceptance test harness +- **AND** the SDK clock is fixed at "2025-01-01T00:00:00Z" +- **AND** persistent storage is empty +- **AND** the mock PostHog server is reset +- **GIVEN** the SDK is initialized with token "test-token" +- **AND** cached feature flags are: + | key | value | + | legacy-ui | "" | +- **WHEN** get feature flag result "legacy-ui" is called +- **THEN** the returned feature flag result should include: + | field | value | + | key | legacy-ui | + | enabled | false | +- **AND** its variant should equal the JSON value "" +- **WHEN** is feature enabled "legacy-ui" is called +- **THEN** the returned enabled state should be false + diff --git a/openspec/specs/is-feature-enabled/spec.md b/openspec/specs/is-feature-enabled/spec.md index 366987fd..c45a1a41 100644 --- a/openspec/specs/is-feature-enabled/spec.md +++ b/openspec/specs/is-feature-enabled/spec.md @@ -91,7 +91,7 @@ isFeatureEnabled( 3. **Convert the result to boolean semantics:** - boolean-enabled → `true` - boolean-disabled → `false` - - variant string → `true` + - non-empty variant string → `true` - unavailable / unknown → the caller-supplied `defaultValue` when provided; otherwise `undefined` / `None` in some SDKs, or `false` in others 4. **Optionally emit `$feature_flag_called`.** Server SDKs commonly track accesses by default. From 578a074893e33ef16a18b03cc78172813080e1b7 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Sun, 8 Nov 2026 12:16:14 -0500 Subject: [PATCH 2/3] docs(flags): drop an empty variant from flags-loaded listeners and $active_feature_flags Add on-feature-flags and capture requirements, list posthog-kmp in the impact, and record the posthog-js core and react-native gap. Also refresh the Android 4.0 and Flutter 6.0 reload signatures and Flutter 6.0's per-call sendFeatureFlagEvent option. --- acceptance/public/capture.feature | 14 +++++++++++ acceptance/public/on-feature-flags.feature | 14 +++++++++++ .../proposal.md | 13 +++++++--- .../specs/capture/spec.md | 23 ++++++++++++++++++ .../specs/get-feature-flag-result/spec.md | 2 ++ .../specs/on-feature-flags/spec.md | 24 +++++++++++++++++++ .../tasks.md | 2 ++ openspec/specs/capture/spec.md | 22 +++++++++++++++++ .../specs/feature-flag-called-tracker/spec.md | 2 +- .../specs/get-feature-flag-result/spec.md | 2 ++ openspec/specs/on-feature-flags/spec.md | 23 ++++++++++++++++++ openspec/specs/reload-feature-flags/spec.md | 4 ++-- 12 files changed, 139 insertions(+), 6 deletions(-) create mode 100644 openspec/changes/archive/2026-11-06-empty-variant-disabled/specs/capture/spec.md create mode 100644 openspec/changes/archive/2026-11-06-empty-variant-disabled/specs/on-feature-flags/spec.md diff --git a/acceptance/public/capture.feature b/acceptance/public/capture.feature index 230a1538..5562d78f 100644 --- a/acceptance/public/capture.feature +++ b/acceptance/public/capture.feature @@ -252,3 +252,17 @@ Feature: Capture | property | value | | $process_person_profile | false | | $is_identified | false | + + # The value "" is the empty string, a variant PostHog no longer accepts for new flags. + @client + Scenario: Empty variant flag is left out of active feature flags + Given the SDK is initialized with token "test-token" + And cached feature flags are: + | key | value | + | beta-ui | true | + | legacy-ui | "" | + When capture is called with event "Signed Up" + Then one event named "Signed Up" should be enqueued + And the enqueued event property "$active_feature_flags" should contain "beta-ui" + And the enqueued event property "$active_feature_flags" should not contain "legacy-ui" + And the enqueued event property "$feature/legacy-ui" should equal "" diff --git a/acceptance/public/on-feature-flags.feature b/acceptance/public/on-feature-flags.feature index 8d7392df..0d2628ff 100644 --- a/acceptance/public/on-feature-flags.feature +++ b/acceptance/public/on-feature-flags.feature @@ -49,3 +49,17 @@ Feature: On Feature Flags | key | value | | beta-ui | true | And payload-carrying feature flag listeners should be told that loading flags errored + + # The value "" is the empty string, a variant PostHog no longer accepts for new flags. + Scenario: Listener does not receive an empty variant flag + Given the SDK is initialized with token "test-token" + And a feature flag listener is registered + When feature flags are loaded with values: + | key | value | + | beta-ui | true | + | legacy-ui | "" | + Then the feature flag listener should be invoked + And payload-carrying feature flag listeners should receive flags: + | key | value | + | beta-ui | true | + And payload-carrying feature flag listeners should not receive flag "legacy-ui" diff --git a/openspec/changes/archive/2026-11-06-empty-variant-disabled/proposal.md b/openspec/changes/archive/2026-11-06-empty-variant-disabled/proposal.md index 68326b06..514f6afa 100644 --- a/openspec/changes/archive/2026-11-06-empty-variant-disabled/proposal.md +++ b/openspec/changes/archive/2026-11-06-empty-variant-disabled/proposal.md @@ -4,13 +4,16 @@ A flag whose variant is the empty string `""` reads as disabled from `isFeatureE PostHog has rejected new `""` variant keys since [PostHog/posthog#118803](https://github.com/PostHog/posthog/pull/118803) (2026-10-16), so only flags created earlier through the API, MCP or Terraform can hit this. -The client-side flow of `is-feature-enabled` already says only a non-empty variant string is `true`. The server-side flow and `get-feature-flag-result` don't say what an empty variant is. +The client-side flow of `is-feature-enabled` already says only a non-empty variant string is `true`. The server-side flow, `get-feature-flag-result`, `on-feature-flags` and the `$active_feature_flags` event property don't say what an empty variant is. ## What Changes - **`is-feature-enabled`.** The server-side flow treats only a non-empty variant string as `true`, matching the client-side flow. - **`get-feature-flag-result`.** A new requirement: a flag whose variant is `""` returns `enabled: false` with `variant: ""`, and `is-feature-enabled` returns `false` for it. Both flow descriptions say so. -- **Acceptance.** A matching scenario in `acceptance/public/get-feature-flag-result.feature`. +- **`on-feature-flags`.** A new requirement: payload-carrying listeners leave a `""` flag out of the keys and variants they receive. +- **`capture`.** A new requirement: client SDKs leave a `""` flag out of `$active_feature_flags`; `$feature/` still carries `""`. +- **Stale surface notes.** `reload-feature-flags` lists the Android 4.0 and Flutter 6.0 signatures, and `feature-flag-called-tracker` says Flutter 6.0 adds `sendFeatureFlagEvent` to `getFeatureFlag` and `isFeatureEnabled`. No requirement changes. +- **Acceptance.** Matching scenarios in `acceptance/public/get-feature-flag-result.feature`, `on-feature-flags.feature` and `capture.feature`. ## Capabilities @@ -21,10 +24,14 @@ _None._ ### Modified Capabilities - `get-feature-flag-result`: new **Empty variant reads as disabled** requirement, and the client and server flow descriptions. +- `on-feature-flags`: new **Empty variant is left out of the flags a listener receives** requirement. +- `capture`: new **Empty variant is not an active feature flag** requirement. - `is-feature-enabled`: the server-side flow description only (recorded in the `get-feature-flag-result` delta, since it has no requirement changes). ## Impact -- posthog-ios 4.0, posthog-android 4.0 and posthog-flutter 6.0 change `getFeatureFlagResult().enabled` (and Flutter desktop also `isFeatureEnabled`) to `false` for an empty variant in their major releases. +- posthog-ios 4.0, posthog-android 4.0 and posthog-flutter 6.0 change `getFeatureFlagResult().enabled` (and Flutter desktop also `isFeatureEnabled`) to `false` for an empty variant in their major releases. posthog-ios 4.0 and posthog-android 4.0 also leave it out of `PostHogFeatureFlagsLoaded` (the `onFeatureFlags` and `reloadFeatureFlags` callback payload) and `$active_feature_flags`. +- posthog-kmp treats an empty variant as disabled in `isFeatureEnabled()`, `FeatureFlagResult.enabled`, `getAllFeatureFlags()` and `$active_feature_flags` on every platform, in the release that adopts posthog-ios 4.0 and posthog-android 4.0. +- Known gap: posthog-js core and react-native still return `enabled: true` from `getFeatureFlagResult` (`getEnabledFromValue` reads any string as enabled), still pass `""` to `onFeatureFlags` listeners, and still list it in `$active_feature_flags`, while their `isFeatureEnabled` returns `false`. A follow-up should align them. - `getFeatureFlag` and the `$feature_flag_called` response keep reporting `""`. - Server SDKs were not audited for this case. diff --git a/openspec/changes/archive/2026-11-06-empty-variant-disabled/specs/capture/spec.md b/openspec/changes/archive/2026-11-06-empty-variant-disabled/specs/capture/spec.md new file mode 100644 index 00000000..c8b7c499 --- /dev/null +++ b/openspec/changes/archive/2026-11-06-empty-variant-disabled/specs/capture/spec.md @@ -0,0 +1,23 @@ +## ADDED Requirements + +### Requirement: Empty variant is not an active feature flag + +When a client SDK stamps cached feature flags onto a captured event, a flag whose value is the empty string `""` SHALL NOT be listed in `$active_feature_flags`. Its `$feature/` property SHALL still carry `""`. + +Known gap: posthog-js core and react-native list every cached flag key in `$active_feature_flags`, including one whose value is `""`. A follow-up should leave it out there. + +#### Scenario: Empty variant flag is left out of active feature flags (@client) +- **GIVEN** a fresh SDK acceptance test harness +- **AND** the SDK clock is fixed at "2025-01-01T00:00:00Z" +- **AND** persistent storage is empty +- **AND** the mock PostHog server is reset +- **GIVEN** the SDK is initialized with token "test-token" +- **AND** cached feature flags are: + | key | value | + | beta-ui | true | + | legacy-ui | "" | +- **WHEN** capture is called with event "Signed Up" +- **THEN** one event named "Signed Up" should be enqueued +- **AND** the enqueued event property "$active_feature_flags" should contain "beta-ui" +- **AND** the enqueued event property "$active_feature_flags" should not contain "legacy-ui" +- **AND** the enqueued event property "$feature/legacy-ui" should equal "" diff --git a/openspec/changes/archive/2026-11-06-empty-variant-disabled/specs/get-feature-flag-result/spec.md b/openspec/changes/archive/2026-11-06-empty-variant-disabled/specs/get-feature-flag-result/spec.md index ddfefdc2..9d1583d1 100644 --- a/openspec/changes/archive/2026-11-06-empty-variant-disabled/specs/get-feature-flag-result/spec.md +++ b/openspec/changes/archive/2026-11-06-empty-variant-disabled/specs/get-feature-flag-result/spec.md @@ -4,6 +4,8 @@ A flag whose value is the empty string `""` SHALL read as disabled. The SDK SHALL return a result with `enabled: false` and `variant: ""`, and `is-feature-enabled` SHALL return `false` for it, whether or not the caller supplies a default. +Known gap: posthog-js core and react-native still return `enabled: true` from `getFeatureFlagResult` for `""`, because `getEnabledFromValue` reads any string as enabled, while their `isFeatureEnabled` returns `false`. A follow-up should make `getFeatureFlagResult` match. + #### Scenario: Empty variant flag result is disabled (@both) - **GIVEN** a fresh SDK acceptance test harness - **AND** the SDK clock is fixed at "2025-01-01T00:00:00Z" diff --git a/openspec/changes/archive/2026-11-06-empty-variant-disabled/specs/on-feature-flags/spec.md b/openspec/changes/archive/2026-11-06-empty-variant-disabled/specs/on-feature-flags/spec.md new file mode 100644 index 00000000..64814d4a --- /dev/null +++ b/openspec/changes/archive/2026-11-06-empty-variant-disabled/specs/on-feature-flags/spec.md @@ -0,0 +1,24 @@ +## ADDED Requirements + +### Requirement: Empty variant is left out of the flags a listener receives + +A payload-carrying listener SHALL treat a flag whose value is the empty string `""` as disabled and leave it out of the flag keys and variants it receives, like a flag whose value is `false`. Readiness-only listeners are not affected. + +Known gap: posthog-js core and react-native pass the raw flag map, which still contains the `""` entry. A follow-up should drop it there. + +#### Scenario: Listener does not receive an empty variant flag +- **GIVEN** a fresh SDK acceptance test harness +- **AND** the SDK clock is fixed at "2025-01-01T00:00:00Z" +- **AND** persistent storage is empty +- **AND** the mock PostHog server is reset +- **GIVEN** the SDK is initialized with token "test-token" +- **AND** a feature flag listener is registered +- **WHEN** feature flags are loaded with values: + | key | value | + | beta-ui | true | + | legacy-ui | "" | +- **THEN** the feature flag listener should be invoked +- **AND** payload-carrying feature flag listeners should receive flags: + | key | value | + | beta-ui | true | +- **AND** payload-carrying feature flag listeners should not receive flag "legacy-ui" diff --git a/openspec/changes/archive/2026-11-06-empty-variant-disabled/tasks.md b/openspec/changes/archive/2026-11-06-empty-variant-disabled/tasks.md index fccee3a8..83da4d29 100644 --- a/openspec/changes/archive/2026-11-06-empty-variant-disabled/tasks.md +++ b/openspec/changes/archive/2026-11-06-empty-variant-disabled/tasks.md @@ -3,6 +3,8 @@ - [x] 1.1 Add the **Empty variant reads as disabled** requirement to `get-feature-flag-result`, and describe empty variants in its client and server flows - [x] 1.2 Say "non-empty variant string" in the `is-feature-enabled` server-side flow - [x] 1.3 Add the scenario to `acceptance/public/get-feature-flag-result.feature` +- [x] 1.4 Add the **Empty variant is left out of the flags a listener receives** requirement to `on-feature-flags` and its scenario to `acceptance/public/on-feature-flags.feature` +- [x] 1.5 Add the **Empty variant is not an active feature flag** requirement to `capture` and its scenario to `acceptance/public/capture.feature` ## 2. Validation diff --git a/openspec/specs/capture/spec.md b/openspec/specs/capture/spec.md index e1c4654d..a67fb443 100644 --- a/openspec/specs/capture/spec.md +++ b/openspec/specs/capture/spec.md @@ -622,3 +622,25 @@ A backward clock change SHALL only pause refill until the clock catches up. It S - **AND** no event named "Four" should be enqueued - **AND** one event named "Five" should be enqueued + +### Requirement: Empty variant is not an active feature flag + +When a client SDK stamps cached feature flags onto a captured event, a flag whose value is the empty string `""` SHALL NOT be listed in `$active_feature_flags`. Its `$feature/` property SHALL still carry `""`. + +Known gap: posthog-js core and react-native list every cached flag key in `$active_feature_flags`, including one whose value is `""`. A follow-up should leave it out there. + +#### Scenario: Empty variant flag is left out of active feature flags (@client) +- **GIVEN** a fresh SDK acceptance test harness +- **AND** the SDK clock is fixed at "2025-01-01T00:00:00Z" +- **AND** persistent storage is empty +- **AND** the mock PostHog server is reset +- **GIVEN** the SDK is initialized with token "test-token" +- **AND** cached feature flags are: + | key | value | + | beta-ui | true | + | legacy-ui | "" | +- **WHEN** capture is called with event "Signed Up" +- **THEN** one event named "Signed Up" should be enqueued +- **AND** the enqueued event property "$active_feature_flags" should contain "beta-ui" +- **AND** the enqueued event property "$active_feature_flags" should not contain "legacy-ui" +- **AND** the enqueued event property "$feature/legacy-ui" should equal "" diff --git a/openspec/specs/feature-flag-called-tracker/spec.md b/openspec/specs/feature-flag-called-tracker/spec.md index 51baf48f..03259161 100644 --- a/openspec/specs/feature-flag-called-tracker/spec.md +++ b/openspec/specs/feature-flag-called-tracker/spec.md @@ -37,7 +37,7 @@ In some SDKs, `shouldTrack` and `markSeen` are combined into one atomic "add if 3. **Suppress duplicate tracking events.** If the same combination has already been seen, do not emit another `$feature_flag_called` event. 4. **Allow new tracking when the response or evaluation context changes.** If a flag's value changes for the same key, or if a server-side call evaluates the same flag/value for a different `distinct_id` or group context, allow a new `$feature_flag_called` event. 5. **Reset on flag change and lifecycle boundaries.** When feature flag state changes, caches are reset, identity is reset, or the SDK is closed/shut down, clear the dedupe tracker so post-reset/reloaded SDK state can emit fresh tracking events and shutdown state cannot leak across SDK lifetimes. On client-side flag reloads, SDKs MAY retain the tracker if they can reliably compare the complete relevant flag state before and after reload (including flag keys, values, payloads, and other cached flag metadata used by accessors) and determine it is unchanged; otherwise, they SHOULD clear the tracker after reload. -6. **Expose tracking controls unevenly at the wrapper layer when applicable.** For example, Flutter delegates to the underlying native/browser trackers and only exposes a per-call suppression flag on `getFeatureFlagResult(sendFeatureFlagEvent: ...)` (named `sendEvent` before 6.0), while `getFeatureFlag(...)` and `isFeatureEnabled(...)` always use the default tracking path. +6. **Expose tracking controls unevenly at the wrapper layer when applicable.** For example, Flutter delegates to the underlying native/browser trackers. Flutter 6.0 exposes a per-call `sendFeatureFlagEvent` option on `getFeatureFlag(...)`, `isFeatureEnabled(...)` and `getFeatureFlagResult(...)`; before 6.0 only `getFeatureFlagResult(sendEvent: ...)` had one, and `getFeatureFlag(...)` and `isFeatureEnabled(...)` always used the default tracking path. 7. **Cap memory usage where needed.** Larger-scale implementations evict old entries using bounded maps or LRU-style caches. When a bounded tracker reaches its capacity, it SHOULD evict the oldest or least-recently-used entries incrementally. Capacity pressure SHOULD NOT clear the entire tracker, because doing so can flood analytics with duplicate `$feature_flag_called` events. Full tracker clears are reserved for explicit lifecycle/context boundaries such as observed flag-state change/cache reset, identity reset, or SDK close/shutdown. ## State & lifecycle diff --git a/openspec/specs/get-feature-flag-result/spec.md b/openspec/specs/get-feature-flag-result/spec.md index 310d020b..300c072c 100644 --- a/openspec/specs/get-feature-flag-result/spec.md +++ b/openspec/specs/get-feature-flag-result/spec.md @@ -293,6 +293,8 @@ A flag-reading API that lets the caller suppress `$feature_flag_called` for that A flag whose value is the empty string `""` SHALL read as disabled. The SDK SHALL return a result with `enabled: false` and `variant: ""`, and `is-feature-enabled` SHALL return `false` for it, whether or not the caller supplies a default. +Known gap: posthog-js core and react-native still return `enabled: true` from `getFeatureFlagResult` for `""`, because `getEnabledFromValue` reads any string as enabled, while their `isFeatureEnabled` returns `false`. A follow-up should make `getFeatureFlagResult` match. + #### Scenario: Empty variant flag result is disabled (@both) - **GIVEN** a fresh SDK acceptance test harness - **AND** the SDK clock is fixed at "2025-01-01T00:00:00Z" diff --git a/openspec/specs/on-feature-flags/spec.md b/openspec/specs/on-feature-flags/spec.md index c849b1ba..7ec800f8 100644 --- a/openspec/specs/on-feature-flags/spec.md +++ b/openspec/specs/on-feature-flags/spec.md @@ -226,3 +226,26 @@ A flag load already in flight when `reset()` or `close()` ran SHALL NOT be deliv | beta-ui | true | - **AND** a feature flag listener is registered - **THEN** the feature flag listener should not be invoked + +### Requirement: Empty variant is left out of the flags a listener receives + +A payload-carrying listener SHALL treat a flag whose value is the empty string `""` as disabled and leave it out of the flag keys and variants it receives, like a flag whose value is `false`. Readiness-only listeners are not affected. + +Known gap: posthog-js core and react-native pass the raw flag map, which still contains the `""` entry. A follow-up should drop it there. + +#### Scenario: Listener does not receive an empty variant flag +- **GIVEN** a fresh SDK acceptance test harness +- **AND** the SDK clock is fixed at "2025-01-01T00:00:00Z" +- **AND** persistent storage is empty +- **AND** the mock PostHog server is reset +- **GIVEN** the SDK is initialized with token "test-token" +- **AND** a feature flag listener is registered +- **WHEN** feature flags are loaded with values: + | key | value | + | beta-ui | true | + | legacy-ui | "" | +- **THEN** the feature flag listener should be invoked +- **AND** payload-carrying feature flag listeners should receive flags: + | key | value | + | beta-ui | true | +- **AND** payload-carrying feature flag listeners should not receive flag "legacy-ui" diff --git a/openspec/specs/reload-feature-flags/spec.md b/openspec/specs/reload-feature-flags/spec.md index e3a619d1..d6ddbb45 100644 --- a/openspec/specs/reload-feature-flags/spec.md +++ b/openspec/specs/reload-feature-flags/spec.md @@ -21,14 +21,14 @@ reloadFeatureFlags(callback?: (flags?: Record, error?: ### Surface variants - **posthog-js core / browser:** `reloadFeatureFlags(options?: { cb?: (err?: Error, flags?: FeatureFlags) => void }): void` -- **flutter:** `reloadFeatureFlags(): Future` +- **flutter:** `reloadFeatureFlags(): Future` (6.0+; before 6.0 it returned `Future`) - **react-native:** - `reloadFeatureFlags(): void` - `reloadFeatureFlagsAsync(): Promise | undefined>` - **iOS:** - `reloadFeatureFlags()` - `reloadFeatureFlags(_ callback: @escaping (PostHogFeatureFlagsLoaded) -> Void)` (4.0+; before 4.0 the callback took no arguments) -- **Android:** `reloadFeatureFlags(onFeatureFlags: PostHogOnFeatureFlags? = null): void` +- **Android:** `reloadFeatureFlags(onFeatureFlags: PostHogFeatureFlagsCallback? = null): void`, whose callback receives `PostHogFeatureFlagsLoaded` (4.0+; before 4.0 it took a `PostHogOnFeatureFlags` with no arguments) - **Unity:** `ReloadFeatureFlagsAsync(): Task` ## Behavior From 4b5703f143a0c1a25ae37fca769b1527af93aaa5 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Mon, 9 Nov 2026 15:28:13 -0500 Subject: [PATCH 3/3] docs(flags): read an empty variant as disabled in getAllFeatureFlags results Where getAllFeatureFlags() returns flag result objects (iOS 4.0+, Android 4.0+, Flutter 6.0+, KMP), each entry matches getFeatureFlagResult, so a "" flag stays in the list with enabled: false. Key-to-value maps keep "". Co-Authored-By: Claude Opus 5.5 --- acceptance/public/get-feature-flags.feature | 16 +++++++++++++ .../proposal.md | 6 +++-- .../specs/get-feature-flags/spec.md | 22 ++++++++++++++++++ .../tasks.md | 1 + openspec/specs/get-feature-flags/spec.md | 23 ++++++++++++++++++- 5 files changed, 65 insertions(+), 3 deletions(-) create mode 100644 openspec/changes/archive/2026-11-06-empty-variant-disabled/specs/get-feature-flags/spec.md diff --git a/acceptance/public/get-feature-flags.feature b/acceptance/public/get-feature-flags.feature index def8d482..38db0654 100644 --- a/acceptance/public/get-feature-flags.feature +++ b/acceptance/public/get-feature-flags.feature @@ -42,3 +42,19 @@ Feature: Get Feature Flags | beta-ui | true | When get feature flags is called with tracking disabled Then no event named "$feature_flag_called" should be enqueued + + # Only SDKs whose getAllFeatureFlags() returns flag result objects (iOS 4.0+, Android 4.0+, Flutter 6.0+, KMP). + # The value "" is the empty string, a variant PostHog no longer accepts for new flags. + @client @flag_result_list_capable + Scenario: Flag result list reads an empty variant as disabled + Given the SDK is initialized with token "test-token" + And cached feature flags are: + | key | value | + | beta-ui | true | + | legacy-ui | "" | + When get all feature flag results is called + Then the returned feature flag results should include: + | key | enabled | + | beta-ui | true | + | legacy-ui | false | + And the returned feature flag result for "legacy-ui" should have variant equal to the JSON value "" diff --git a/openspec/changes/archive/2026-11-06-empty-variant-disabled/proposal.md b/openspec/changes/archive/2026-11-06-empty-variant-disabled/proposal.md index 514f6afa..38beb4ce 100644 --- a/openspec/changes/archive/2026-11-06-empty-variant-disabled/proposal.md +++ b/openspec/changes/archive/2026-11-06-empty-variant-disabled/proposal.md @@ -11,9 +11,10 @@ The client-side flow of `is-feature-enabled` already says only a non-empty varia - **`is-feature-enabled`.** The server-side flow treats only a non-empty variant string as `true`, matching the client-side flow. - **`get-feature-flag-result`.** A new requirement: a flag whose variant is `""` returns `enabled: false` with `variant: ""`, and `is-feature-enabled` returns `false` for it. Both flow descriptions say so. - **`on-feature-flags`.** A new requirement: payload-carrying listeners leave a `""` flag out of the keys and variants they receive. +- **`get-feature-flags`.** A new requirement: where `getAllFeatureFlags()` returns flag result objects, a `""` flag stays in the list with `enabled: false`, matching `get-feature-flag-result`. - **`capture`.** A new requirement: client SDKs leave a `""` flag out of `$active_feature_flags`; `$feature/` still carries `""`. - **Stale surface notes.** `reload-feature-flags` lists the Android 4.0 and Flutter 6.0 signatures, and `feature-flag-called-tracker` says Flutter 6.0 adds `sendFeatureFlagEvent` to `getFeatureFlag` and `isFeatureEnabled`. No requirement changes. -- **Acceptance.** Matching scenarios in `acceptance/public/get-feature-flag-result.feature`, `on-feature-flags.feature` and `capture.feature`. +- **Acceptance.** Matching scenarios in `acceptance/public/get-feature-flag-result.feature`, `on-feature-flags.feature`, `get-feature-flags.feature` and `capture.feature`. ## Capabilities @@ -25,12 +26,13 @@ _None._ - `get-feature-flag-result`: new **Empty variant reads as disabled** requirement, and the client and server flow descriptions. - `on-feature-flags`: new **Empty variant is left out of the flags a listener receives** requirement. +- `get-feature-flags`: new **Flag result list reads an empty variant as disabled** requirement. - `capture`: new **Empty variant is not an active feature flag** requirement. - `is-feature-enabled`: the server-side flow description only (recorded in the `get-feature-flag-result` delta, since it has no requirement changes). ## Impact -- posthog-ios 4.0, posthog-android 4.0 and posthog-flutter 6.0 change `getFeatureFlagResult().enabled` (and Flutter desktop also `isFeatureEnabled`) to `false` for an empty variant in their major releases. posthog-ios 4.0 and posthog-android 4.0 also leave it out of `PostHogFeatureFlagsLoaded` (the `onFeatureFlags` and `reloadFeatureFlags` callback payload) and `$active_feature_flags`. +- posthog-ios 4.0, posthog-android 4.0 and posthog-flutter 6.0 change `getFeatureFlagResult().enabled` and the `enabled` of each `getAllFeatureFlags()` entry (and Flutter desktop also `isFeatureEnabled`) to `false` for an empty variant in their major releases. posthog-ios 4.0 and posthog-android 4.0 also leave it out of `PostHogFeatureFlagsLoaded` (the `onFeatureFlags` and `reloadFeatureFlags` callback payload) and `$active_feature_flags`. - posthog-kmp treats an empty variant as disabled in `isFeatureEnabled()`, `FeatureFlagResult.enabled`, `getAllFeatureFlags()` and `$active_feature_flags` on every platform, in the release that adopts posthog-ios 4.0 and posthog-android 4.0. - Known gap: posthog-js core and react-native still return `enabled: true` from `getFeatureFlagResult` (`getEnabledFromValue` reads any string as enabled), still pass `""` to `onFeatureFlags` listeners, and still list it in `$active_feature_flags`, while their `isFeatureEnabled` returns `false`. A follow-up should align them. - `getFeatureFlag` and the `$feature_flag_called` response keep reporting `""`. diff --git a/openspec/changes/archive/2026-11-06-empty-variant-disabled/specs/get-feature-flags/spec.md b/openspec/changes/archive/2026-11-06-empty-variant-disabled/specs/get-feature-flags/spec.md new file mode 100644 index 00000000..d9f28dad --- /dev/null +++ b/openspec/changes/archive/2026-11-06-empty-variant-disabled/specs/get-feature-flags/spec.md @@ -0,0 +1,22 @@ +## ADDED Requirements + +### Requirement: Flag result list reads an empty variant as disabled + +On SDKs where `getAllFeatureFlags()` returns a list of flag result objects (iOS 4.0+, Android 4.0+, Flutter 6.0+, KMP), each entry SHALL match what `get-feature-flag-result` returns for that key. A flag whose value is the empty string `""` SHALL stay in the list with `enabled: false` and `variant: ""`. SDKs that return a key → value map keep reporting `""`, as `get-feature-flag` does. + +#### Scenario: Flag result list reads an empty variant as disabled +- **GIVEN** a fresh SDK acceptance test harness +- **AND** the SDK clock is fixed at "2025-01-01T00:00:00Z" +- **AND** persistent storage is empty +- **AND** the mock PostHog server is reset +- **GIVEN** the SDK is initialized with token "test-token" +- **AND** cached feature flags are: + | key | value | + | beta-ui | true | + | legacy-ui | "" | +- **WHEN** get all feature flag results is called +- **THEN** the returned feature flag results should include: + | key | enabled | + | beta-ui | true | + | legacy-ui | false | +- **AND** the returned feature flag result for "legacy-ui" should have variant equal to the JSON value "" diff --git a/openspec/changes/archive/2026-11-06-empty-variant-disabled/tasks.md b/openspec/changes/archive/2026-11-06-empty-variant-disabled/tasks.md index 83da4d29..920f7a20 100644 --- a/openspec/changes/archive/2026-11-06-empty-variant-disabled/tasks.md +++ b/openspec/changes/archive/2026-11-06-empty-variant-disabled/tasks.md @@ -5,6 +5,7 @@ - [x] 1.3 Add the scenario to `acceptance/public/get-feature-flag-result.feature` - [x] 1.4 Add the **Empty variant is left out of the flags a listener receives** requirement to `on-feature-flags` and its scenario to `acceptance/public/on-feature-flags.feature` - [x] 1.5 Add the **Empty variant is not an active feature flag** requirement to `capture` and its scenario to `acceptance/public/capture.feature` +- [x] 1.6 Add the **Flag result list reads an empty variant as disabled** requirement to `get-feature-flags` and its scenario to `acceptance/public/get-feature-flags.feature` ## 2. Validation diff --git a/openspec/specs/get-feature-flags/spec.md b/openspec/specs/get-feature-flags/spec.md index 16164404..46f9e447 100644 --- a/openspec/specs/get-feature-flags/spec.md +++ b/openspec/specs/get-feature-flags/spec.md @@ -56,7 +56,7 @@ getAllFlags( ### Surface variants - **posthog-js core / browser / react-native:** `getFeatureFlags()` -- **iOS (4.0+), Android (4.0+), flutter (6.0+):** `getAllFeatureFlags()` returns a list of flag result objects (key, enabled, variant, payload), or `null` when flags are unavailable, instead of a key-to-value map. It never sends `$feature_flag_called`. +- **iOS (4.0+), Android (4.0+), flutter (6.0+):** `getAllFeatureFlags()` returns a list of flag result objects (key, enabled, variant, payload), or `null` when flags are unavailable, instead of a key-to-value map. Each entry matches `getFeatureFlagResult` for that key, so an empty variant reads as disabled. It never sends `$feature_flag_called`. - **Node:** `getAllFlags(distinctId, options?)` - **Python:** `get_all_flags(distinct_id, *, ...)` - **Ruby:** `get_all_flags(distinct_id, groups: {}, person_properties: {}, group_properties: {}, only_evaluate_locally: false)` @@ -161,3 +161,24 @@ The SDK SHALL implement the canonical `get-feature-flags` behavior described by | beta-ui | true | - **WHEN** get feature flags is called with tracking disabled - **THEN** no event named "$feature_flag_called" should be enqueued + +### Requirement: Flag result list reads an empty variant as disabled + +On SDKs where `getAllFeatureFlags()` returns a list of flag result objects (iOS 4.0+, Android 4.0+, Flutter 6.0+, KMP), each entry SHALL match what `get-feature-flag-result` returns for that key. A flag whose value is the empty string `""` SHALL stay in the list with `enabled: false` and `variant: ""`. SDKs that return a key → value map keep reporting `""`, as `get-feature-flag` does. + +#### Scenario: Flag result list reads an empty variant as disabled (@client) +- **GIVEN** a fresh SDK acceptance test harness +- **AND** the SDK clock is fixed at "2025-01-01T00:00:00Z" +- **AND** persistent storage is empty +- **AND** the mock PostHog server is reset +- **GIVEN** the SDK is initialized with token "test-token" +- **AND** cached feature flags are: + | key | value | + | beta-ui | true | + | legacy-ui | "" | +- **WHEN** get all feature flag results is called +- **THEN** the returned feature flag results should include: + | key | enabled | + | beta-ui | true | + | legacy-ui | false | +- **AND** the returned feature flag result for "legacy-ui" should have variant equal to the JSON value ""