[andehen]

Why

evaluateFlags() is the preferred server API, and the single-flag getters it supersedes (getFeatureFlag, isFeatureEnabled, getFeatureFlagResult, …) now log deprecation warnings that tell users to migrate to it. Those getters let the caller control $feature_flag_called: every server SDK takes a per-call option, and some SDKs also have a client-level default. The evaluate-flags contract mentions neither control, so snapshot reads honor neither.

• Customers turn these events off on purpose. They do it for flags they don't use with flag analytics or experiments, to cut event volume and noise in their project.
• Following our deprecation guidance should not undo that setting. Today a Python caller that passed send_feature_flag_events=False gets every event back after migrating. A posthog-node client created with sendFeatureFlagEvent: false gets them back from snapshot reads.
• Customers who need experiment exposures must keep them. A client with the default off that opts specific flags back in, typically experiment flags via getFeatureFlag(key, id, { sendFeatureFlagEvents: true }), has no snapshot equivalent. Once snapshot reads honor the client default, those experiments would see no exposures.
• The control belongs on each read, not on the snapshot. One request typically reads experiment flags and operational flags (kill switches, config) from the same snapshot, so a per-snapshot setting would force a second evaluateFlags(), and a second /flags request, to mix them.
• Dedupe and access stay separate. A suppressed read must not mark the dedupe tracker, or a later opted-in read of the same key would be swallowed. It still counts as access for onlyAccessed(), because the code did branch on that flag.

What changed

New requirement Snapshot feature flag event control in evaluate-flags:

• The enablement and value accessors (including a value accessor that returns a rich result) accept an optional per-read sendFeatureFlagEvents option, in platform casing (send_feature_flag_events), with the same meaning as the per-call option on the server getters. Payload, key enumeration and filters take no option.
• The SDK decides each read in this order: the per-read value, then the SDK's client-level default where one exists, then true. This is the order the legacy getters already use.
• When the decision is false, the read emits no $feature_flag_called, including flag_missing. It doesn't consult or update the dedupe tracker, so a later opted-in read of the same key still emits. It still marks the key as accessed for onlyAccessed().
• evaluateFlags() takes no per-snapshot option.

Amended requirements:

• Server-side snapshot evaluation API. The supersession table gains a row: getFeatureFlag(key, id, { sendFeatureFlagEvents: x }) → evaluateFlags(id).getFlag(key, { sendFeatureFlagEvents: x }). The "not side-effect-preserving" note now says exposure-event control is preserved. The other documented differences (bulk maps, payload silence, Go's legacy payload exposure) are unchanged.
• Lazy feature-flag access tracking. Event routing and flag_missing reporting now defer to the new control. Access marking is unchanged.

Unchanged: creating a snapshot emits nothing, payload reads stay silent, and a read with no option anywhere still emits.

acceptance/public/evaluate-flags.feature adds six scenarios that mirror the spec scenarios. They use the request-local snapshot read steps from #107: the per-read option goes in a read's options as send_feature_flag_events, and the client-level default goes in the setup configuration as send_feature_flag_event. They are tagged @server, not @sdk:server, because no SDK has run them end to end through the shared harness yet. The two client-default scenarios also carry @requires:flag_event_default, because only some SDKs have a client-level default.

Proposed, applied and archived on this branch under openspec/changes/archive/2026-10-08-honor-snapshot-flag-event-opt-out/. The design doc records the SDK survey and a migration note: an SDK whose snapshot reads ignored its client-level default until now should say in its changelog that callers who relied on snapshot reads for exposures while that default was off must now opt those reads in.

Validation

• openspec validate --specs --strict (CLI 1.4.1, as in CI): 64 passed, 0 failed.
• The change validated strictly before archiving.
• The acceptance feature parses with @cucumber/gherkin: 58 scenario definitions, up from 52 on main.
• git diff --check is clean.

These are specification checks. No SDK conformance was executed.

Evidence

Server SDK survey of default branches on 2026-10-08:

SDK	Client-level default	Per-call option	Snapshot reads
posthog-node	sendFeatureFlagEvent	sendFeatureFlagEvents	ignore both (draft #5252 adds the client default and the per-read option)
JVM server	PostHogConfig.sendFeatureFlagEvent	sendFeatureFlagEvent on getFeatureFlagResult	honor the client default; no per-read option
posthog-python	none	send_feature_flag_events	no control
posthog-ruby	none	send_feature_flag_events:	no control
posthog-php	none	$sendFeatureFlagEvents	no control
posthog-go	none	FeatureFlagPayload.SendFeatureFlagEvents	no control
posthog-dotnet	none	FeatureFlagOptions.SendFeatureFlagEvents	no control
posthog-elixir	none	send_event: on get_feature_flag_result	no control

• posthog-node snapshot host: _getFeatureFlagEvaluationsHost forwards every snapshot read to _captureFlagCalledEventIfNeeded without checking the client option. The legacy getters resolve options?.sendFeatureFlagEvents ?? this.options.sendFeatureFlagEvent ?? true (getFeatureFlag, isFeatureEnabled). The snapshot accessors isEnabled and getFlag take no event option.
• posthog-js #5252 (draft, feat(node): honor sendFeatureFlagEvent in evaluateFlags snapshots, with a per-read override posthog-js#5252): makes snapshot isEnabled() and getFlag() honor sendFeatureFlagEvent, and adds a per-read sendFeatureFlagEvents option to both, with the precedence, dedupe and access rules in this PR. A separate commit makes the OpenFeature Node provider leave sendFeatureFlagEvents unset unless its caller sets it.
• posthog-python: evaluate_flags takes no event control. Neither do is_enabled and get_flag. The client has no client-level option.
• JVM server: the snapshot host returns early when sendFeatureFlagEvent is false, and the legacy path uses the same precedence. It is the existing reference for the client-default half of this change.
• This spec's own design: the supersession mapping "is functional, not side-effect-preserving" (design.md:40), and exposure-on-access is defined without an opt-out (design.md:70–74).

Considered alternatives

• A per-snapshot option on evaluateFlags(). Rejected. Mixing experiment and operational flags in one request would need two evaluations and two /flags requests, which defeats the single-evaluation purpose of the API. This is the same reasoning that put the runtime filter on the snapshot.
• Only honor the client-level default (the first version of #5252). Necessary but not enough. There is no way to opt experiment flags back in, a default-on client cannot silence one read (health checks, bulk scans), and six of the eight surveyed SDKs have no client-level default at all.
• Mark the dedupe tracker on suppressed reads. Rejected, because it swallows a later opted-in exposure for the same identity, key and value.
• Skip access marking on suppressed reads. Rejected. onlyAccessed() would drop flags the code branched on.

Related

• test: observe remote feature flag snapshot reads #107 (test: observe remote feature flag snapshot reads) has landed, and this PR is rebased onto it.
  • The spec edits don't overlap: test: observe remote feature flag snapshot reads #107 appended a requirement at the end, and this PR edits two requirements and inserts one after lazy access tracking. test: observe remote feature flag snapshot reads #107's requirement defers to the lazy-tracking contract, and its scenarios set neither event option, so their exposure counts still hold.
  • The six scenarios are converted to test: observe remote feature flag snapshot reads #107's style: per-scenario setup, JSON reads, an explicit flush and checks on delivered exposures. Their spec scenarios now use the same wording as test: observe remote feature flag snapshot reads #107's.
• docs(flags): name the per-call feature flag event option #109 (docs(flags): name the per-call feature flag event option) names the option sendFeatureFlagEvents on server SDKs, and this PR uses that name for the per-read option. There is no file overlap, so either can land first. Two notes for docs(flags): name the per-call feature flag event option #109:
  • Its "SHALL default to sending the event" should allow the client-level fallback described here.
  • The JVM server SDK's per-call option is singular (sendFeatureFlagEvent) and posthog-elixir's is send_event, so the plural server rule doesn't yet match every server SDK.
• feat(node): honor sendFeatureFlagEvent in evaluateFlags snapshots, with a per-read override posthog-js#5252: the Node implementation described above.

Follow-ups

• posthog-node: land #5252. It adds the client default and the per-read sendFeatureFlagEvents option on isEnabled() / getFlag(), and its changeset tells users who relied on snapshot reads for exposures while sendFeatureFlagEvent was false to opt those reads in.
• posthog-python: add a send_feature_flag_events keyword to is_enabled() / get_flag().
• Ruby, PHP, Go, .NET, JVM server, Elixir: add the per-read option.
• OpenFeature providers: no spec here governs them. packages/openfeature-node-provider in posthog-js defaults its sendFeatureFlagEvents to true (provider.ts:78) and passes it on every call (provider.ts:154). That overrides a client created with sendFeatureFlagEvent: false. The provider should leave the option unset unless its caller sets it. #5252 makes that change in a separate commit.
• Acceptance harness: forward send_feature_flag_events on is_enabled and get_flag reads, and send_feature_flag_event in the setup configuration, to the SDK's public options. Declare flag_event_default for SDKs with a client-level default. Once the six scenarios pass end to end against an SDK with the option, change their tag to @sdk:server.

🤖 Generated with Claude Code