Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-11-03
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
## Why

Nothing in the specs says that a `$feature_flag_called` event identifies which flag definition produced
the value. `feature-flag-called-tracker` names `$feature_flag_id` and `$feature_flag_version` only in
passing, inside the minimal-event allowlist, as "evaluation debug scalars the server/SDK already
attaches". That phrasing reads as "whatever the remote response happened to carry", so a server SDK that
evaluates a flag locally has no stated obligation to attach either one — and the two server SDKs that
send these properties both read them from the remote `/flags` response metadata only.

posthog-python closed that gap in [PostHog/posthog-python#1149](https://github.com/PostHog/posthog-python/pull/1149).
A locally evaluated read now takes `id` and `version` from the local flag definition that produced the
value, across `get_feature_flag()`, `feature_enabled()`, `get_feature_flag_result()` and the
`get_feature_flag_payload(..., send_feature_flag_events=True)` path. `evaluate_flags()` previously set
`$feature_flag_id` but hardcoded `version=None` on the belief that local definitions carry no version;
they do, so the snapshot record now takes it from the definition.

Without this property, a locally evaluated `$feature_flag_called` event cannot be attributed to a flag
definition or a definition revision downstream, while the same read against the remote endpoint can be.
posthog-go still reads both properties from `evalResult.FlagDetail` only (`posthog.go`), so its locally
evaluated events omit them. Recording posthog-python's behavior as the winner states which side of that
divergence is correct.

## What Changes

- `feature-flag-called-tracker` gains a **Flag definition identity on flag-called events** requirement:
a `$feature_flag_called` event carries `$feature_flag_id` and `$feature_flag_version` for a locally
evaluated read as well as a remote one, taken from the local flag definition; each property is omitted
when its source does not carry it; and a structured snapshot read records the same values on the
locally evaluated flag record it exposes.
- The local values are read from the same definitions snapshot that produced the value, so a definitions
refresh between evaluation and capture cannot report a different definition's identity.
- No change to any public API, to the dedupe contract, or to the minimal-event allowlist. The two
properties were already on that allowlist, so a minimized event carries them too.

## Capabilities

### New Capabilities

_None._

### Modified Capabilities

- `feature-flag-called-tracker`: one added requirement.

## Impact

- **posthog-python**: already compliant.
- **posthog-go**: attaches both properties only from remote `/flags` metadata; its locally evaluated
`$feature_flag_called` events need the definition's `id` and `version`. Recorded as a known gap.
- **posthog-node**: attaches `$feature_flag_id` but not `$feature_flag_version` on locally evaluated reads,
and its snapshot record hardcodes `version: undefined`. Recorded as a known gap.
- **Other server SDKs with local evaluation** (posthog-php, posthog-ruby, posthog-dotnet,
posthog-java, posthog-rs, posthog-elixir): attach both properties on locally evaluated reads.
- **Client SDKs**: not applicable — they do not evaluate flags locally.
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
## ADDED Requirements

### Requirement: Flag definition identity on flag-called events

A `$feature_flag_called` event SHALL identify the flag definition that produced the value through
`$feature_flag_id` and `$feature_flag_version`, whether the value came from a remote evaluation
response or from local evaluation.

- A remotely evaluated read SHALL take both values from the flag's evaluation metadata in the response.
- A locally evaluated read SHALL take them from the `id` and `version` of the local flag definition that
produced the value. An SDK SHALL NOT treat local definitions as carrying no version.
- The SDK SHALL read the local definition from the same definitions snapshot that produced the value,
not from its current definitions state, so a definitions refresh between evaluation and capture cannot
report another revision's identity.
- Each property SHALL be omitted when its source does not carry it. A missing `version` SHALL NOT
suppress `$feature_flag_id`, and an absent definition SHALL NOT fail the read or the event.
- Every read path that emits `$feature_flag_called` SHALL follow this rule, including value-only,
enabled-state and structured-result getters, and a payload read that the caller opted into tracking.
- A structured snapshot read (`evaluate-flags`) SHALL record the same `id` and `version` on the locally
evaluated flag record it exposes, so an exposure captured from the snapshot carries them too.

`$feature_flag_id` and `$feature_flag_version` are already on the minimal-event allowlist, so a minimized
event carries whichever of them the read resolved.

Known gap: posthog-node sends `$feature_flag_id` but not `$feature_flag_version` on a locally evaluated
read, and its snapshot record hardcodes `version: undefined` for a locally evaluated flag. posthog-go sends
neither property on a locally evaluated read, because it reads both from the remote `FlagDetail` only, and
its snapshot record for a locally evaluated flag leaves both unset. A follow-up should take them from the
local definition in both SDKs.

#### Scenario: A locally evaluated read reports the definition's id and version (@server)
- **GIVEN** a fresh SDK acceptance test harness
- **AND** persistent storage is empty
- **AND** the mock PostHog server is reset
- **GIVEN** the SDK is initialized with token "test-token" and a personal API key for local evaluation
- **AND** local feature flag definitions include a flag "local-flag" with id 4211 and version 7 rolled out to distinct id "user-123"
- **WHEN** get feature flag "local-flag" is called for distinct id "user-123"
- **THEN** no remote flag evaluation request should be sent
- **AND** one event named "$feature_flag_called" should be enqueued
- **AND** the enqueued event properties should include:
| property | value |
| $feature_flag | local-flag |
| locally_evaluated | true |
| $feature_flag_id | 4211 |
| $feature_flag_version | 7 |

#### Scenario: A local definition without a version still reports its id (@server)
- **GIVEN** a fresh SDK acceptance test harness
- **AND** persistent storage is empty
- **AND** the mock PostHog server is reset
- **GIVEN** the SDK is initialized with token "test-token" and a personal API key for local evaluation
- **AND** local feature flag definitions include a flag "unversioned-flag" with id 4212 and no version rolled out to distinct id "user-123"
- **WHEN** get feature flag "unversioned-flag" is called for distinct id "user-123"
- **THEN** one event named "$feature_flag_called" should be enqueued
- **AND** the enqueued event properties should include:
| property | value |
| $feature_flag_id | 4212 |
- **AND** the enqueued event properties should not include "$feature_flag_version"

#### Scenario: A snapshot read carries the local definition's identity (@server)
- **GIVEN** a fresh SDK acceptance test harness
- **AND** persistent storage is empty
- **AND** the mock PostHog server is reset
- **GIVEN** the SDK is initialized with token "test-token" and a personal API key for local evaluation
- **AND** local feature flag definitions include a flag "local-flag" with id 4211 and version 7 rolled out to distinct id "user-123"
- **WHEN** flags are evaluated once for distinct id "user-123"
- **AND** the enabled state of "local-flag" is read from the resulting snapshot
- **THEN** one event named "$feature_flag_called" should be enqueued
- **AND** the enqueued event properties should include:
| property | value |
| $feature_flag_id | 4211 |
| $feature_flag_version | 7 |
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
## 1. Spec delta

- [x] 1.1 Add **Flag definition identity on flag-called events** to `feature-flag-called-tracker`, covering the remote and local sources of `$feature_flag_id` / `$feature_flag_version`, the omit-when-absent rule, the snapshot-consistency rule, and the structured snapshot record

## 2. Validation

- [x] 2.1 Confirm each added requirement has at least one scenario
- [x] 2.2 Sync the delta into `openspec/specs/feature-flag-called-tracker/spec.md` and archive the change
71 changes: 71 additions & 0 deletions openspec/specs/feature-flag-called-tracker/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -691,3 +691,74 @@ When the decision is `false`, the read SHALL emit no `$feature_flag_called` even
- **WHEN** get feature flag result "beta-ui" is called with tracking disabled
- **AND** get feature flag result "beta-ui" is called
- **THEN** exactly one event named "$feature_flag_called" should be enqueued for flag "beta-ui"

### Requirement: Flag definition identity on flag-called events

A `$feature_flag_called` event SHALL identify the flag definition that produced the value through
`$feature_flag_id` and `$feature_flag_version`, whether the value came from a remote evaluation
response or from local evaluation.

- A remotely evaluated read SHALL take both values from the flag's evaluation metadata in the response.
- A locally evaluated read SHALL take them from the `id` and `version` of the local flag definition that
produced the value. An SDK SHALL NOT treat local definitions as carrying no version.
- The SDK SHALL read the local definition from the same definitions snapshot that produced the value,
not from its current definitions state, so a definitions refresh between evaluation and capture cannot
report another revision's identity.
- Each property SHALL be omitted when its source does not carry it. A missing `version` SHALL NOT
suppress `$feature_flag_id`, and an absent definition SHALL NOT fail the read or the event.
- Every read path that emits `$feature_flag_called` SHALL follow this rule, including value-only,
enabled-state and structured-result getters, and a payload read that the caller opted into tracking.
- A structured snapshot read (`evaluate-flags`) SHALL record the same `id` and `version` on the locally
evaluated flag record it exposes, so an exposure captured from the snapshot carries them too.

`$feature_flag_id` and `$feature_flag_version` are already on the minimal-event allowlist, so a minimized
event carries whichever of them the read resolved.

Known gap: posthog-node sends `$feature_flag_id` but not `$feature_flag_version` on a locally evaluated
read, and its snapshot record hardcodes `version: undefined` for a locally evaluated flag. posthog-go sends
neither property on a locally evaluated read, because it reads both from the remote `FlagDetail` only, and
its snapshot record for a locally evaluated flag leaves both unset. A follow-up should take them from the
local definition in both SDKs.

#### Scenario: A locally evaluated read reports the definition's id and version (@server)
- **GIVEN** a fresh SDK acceptance test harness
- **AND** persistent storage is empty
- **AND** the mock PostHog server is reset
- **GIVEN** the SDK is initialized with token "test-token" and a personal API key for local evaluation
- **AND** local feature flag definitions include a flag "local-flag" with id 4211 and version 7 rolled out to distinct id "user-123"
- **WHEN** get feature flag "local-flag" is called for distinct id "user-123"
- **THEN** no remote flag evaluation request should be sent
- **AND** one event named "$feature_flag_called" should be enqueued
- **AND** the enqueued event properties should include:
| property | value |
| $feature_flag | local-flag |
| locally_evaluated | true |
| $feature_flag_id | 4211 |
| $feature_flag_version | 7 |

#### Scenario: A local definition without a version still reports its id (@server)
- **GIVEN** a fresh SDK acceptance test harness
- **AND** persistent storage is empty
- **AND** the mock PostHog server is reset
- **GIVEN** the SDK is initialized with token "test-token" and a personal API key for local evaluation
- **AND** local feature flag definitions include a flag "unversioned-flag" with id 4212 and no version rolled out to distinct id "user-123"
- **WHEN** get feature flag "unversioned-flag" is called for distinct id "user-123"
- **THEN** one event named "$feature_flag_called" should be enqueued
- **AND** the enqueued event properties should include:
| property | value |
| $feature_flag_id | 4212 |
- **AND** the enqueued event properties should not include "$feature_flag_version"

#### Scenario: A snapshot read carries the local definition's identity (@server)
- **GIVEN** a fresh SDK acceptance test harness
- **AND** persistent storage is empty
- **AND** the mock PostHog server is reset
- **GIVEN** the SDK is initialized with token "test-token" and a personal API key for local evaluation
- **AND** local feature flag definitions include a flag "local-flag" with id 4211 and version 7 rolled out to distinct id "user-123"
- **WHEN** flags are evaluated once for distinct id "user-123"
- **AND** the enabled state of "local-flag" is read from the resulting snapshot
- **THEN** one event named "$feature_flag_called" should be enqueued
- **AND** the enqueued event properties should include:
| property | value |
| $feature_flag_id | 4211 |
| $feature_flag_version | 7 |
Loading