feat(flags): minimize $feature_flag_called events for non-experiment flags

[haacked]

💡 Motivation and Context

$feature_flag_called events carry the full enriched properties (event context, global properties, system context) on every flag call, even for flags not linked to an experiment. This PR trims those events to a strict allowlist iff the server-controlled gate is on (top-level minimalFlagCalledEvents in the v2 /flags response) and the flag's has_experiment is exactly false. Any missing signal (gate absent or unparseable, has_experiment unknown, experiment-linked flag) sends the full legacy shape unchanged.

Server-gated because rolling this out unconditionally could break existing insights; announcement/comms come before enablement. The goal is to establish $feature_flag_called as a special system event.

Part of a cross-SDK rollout; reference implementation and fuller context: PostHog/posthog-python#748.

How it works in this SDK

• posthog-elixir has no local evaluation, so only the /flags remote path applies: the gate is read from the top-level minimalFlagCalledEvents field of the v2 response.
• The gate rides PostHog.FeatureFlags.Result (alongside the other response-level fields like request_id and errors_while_computing), so events fired later from an Evaluations snapshot respect it per flag.
• Minimal properties are assembled through the normal three-source pipeline (event context, then explicit properties, then global properties — same precedence as capture/3 + bare_capture/4) and then projected onto the allowlist via Map.take with a dual atom/string key allowlist. Kept: flag identity and evaluation metadata ($feature_flag, $feature_flag_response, $feature_flag_has_experiment, $feature_flag_id, $feature_flag_version, $feature_flag_reason, $feature_flag_request_id, $feature_flag_evaluated_at, $feature_flag_error when set), $groups, $process_person_profile, $lib, $lib_version, and $is_server. Everything else is stripped, including the $feature/<key> property, context tags, and customer global properties.
• before_send still runs after the projection and may re-inflate the event — the accepted customer escape hatch; the SDK itself adds nothing after the allowlist.
• The minimal path sends through a new internal capture_prepared/4 that skips re-enrichment; bare_capture/4 behavior is unchanged and the public API snapshot is untouched.

💚 How did you test it?

• mix test — 345 tests, 0 failures (18 integration-tagged excluded)
• mix format --check-formatted — clean
• mix credo --strict — 0 issues
• mix compile --warnings-as-errors — clean
• mix posthog.public_api --check — snapshot up to date

Note: run locally on Elixir 1.18.3 / OTP 27.3.3 (.tool-versions pins 1.20.0-otp-29, which wasn't installed locally); CI runs the pinned toolchain.

Coverage added:

• Gate matrix: gated + no experiment → minimal; gated + experiment → full; gate absent / false / unparseable ("yes") → full; gated but has_experiment missing → full.
• Exact-map-equality assertions on minimal events (including $is_server: true, $lib, $lib_version, and $feature_flag_error when the response signals errors), so any extra or missing property fails the test.
• String-keyed context case: string-keyed $groups / $process_person_profile survive the allowlist while string-keyed junk is stripped (pins the string half of the dual allowlist).
• Evaluations snapshot flow: per-flag gate behavior from one snapshot (minimal for the non-experiment flag, full for the experiment flag) plus the missing-flag full-shape fallback.

A minor changeset is included (.sampo/changesets/mellow-ibex-sointu.md).

📝 Checklist

• I reviewed the submitted code.
• I added tests to verify the changes.
• I updated the docs if needed.
• No breaking change or entry added to the changelog.

If releasing new changes

• Ran sampo add to generate a changeset file

---

Created with PostHog Code

[github-actions]

posthog-elixir Compliance Report

Date: 2026-07-18 04:26:45 UTC
Duration: 117525ms

✅ All Tests Passed!

46/46 tests passed

---

Capture Tests

✅ 29/29 tests passed

View Details

Test	Status	Duration
Format Validation.Event Has Required Fields	✅	608ms
Format Validation.Event Has Uuid	✅	608ms
Format Validation.Event Has Lib Properties	✅	608ms
Format Validation.Distinct Id Is String	✅	609ms
Format Validation.Token Is Present	✅	608ms
Format Validation.Custom Properties Preserved	✅	609ms
Format Validation.Event Has Timestamp	✅	609ms
Retry Behavior.Retries On 503	✅	5613ms
Retry Behavior.Does Not Retry On 400	✅	2612ms
Retry Behavior.Does Not Retry On 401	✅	2612ms
Retry Behavior.Respects Retry After Header	✅	5615ms
Retry Behavior.Implements Backoff	✅	15625ms
Retry Behavior.Retries On 500	✅	5615ms
Retry Behavior.Retries On 502	✅	5614ms
Retry Behavior.Retries On 504	✅	5615ms
Retry Behavior.Max Retries Respected	✅	15626ms
Deduplication.Generates Unique Uuids	✅	621ms
Deduplication.Preserves Uuid On Retry	✅	5614ms
Deduplication.Preserves Uuid And Timestamp On Retry	✅	10620ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry	✅	5617ms
Deduplication.No Duplicate Events In Batch	✅	615ms
Deduplication.Different Events Have Different Uuids	✅	612ms
Compression.Sends Gzip When Enabled	✅	608ms
Batch Format.Uses Proper Batch Structure	✅	609ms
Batch Format.Flush With No Events Sends Nothing	✅	607ms
Batch Format.Multiple Events Batched Together	✅	612ms
Error Handling.Does Not Retry On 403	✅	2611ms
Error Handling.Does Not Retry On 413	✅	2611ms
Error Handling.Retries On 408	✅	5615ms

Feature_Flags Tests

✅ 17/17 tests passed

View Details

Test	Status	Duration
Request Payload.Request With Person Properties Device Id	✅	609ms
Request Payload.Flags Request Uses V2 Query Param	✅	609ms
Request Payload.Flags Request Hits Flags Path Not Decide	✅	608ms
Request Payload.Flags Request Omits Authorization Header	✅	607ms
Request Payload.Token In Flags Body Matches Init	✅	609ms
Request Payload.Groups Round Trip	✅	608ms
Request Payload.Groups Default To Empty Object	✅	608ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False	✅	607ms
Request Payload.Disable Geoip Omitted Defaults To False	✅	607ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key	✅	609ms
Request Lifecycle.No Flags Request On Init Alone	✅	3ms
Request Lifecycle.No Flags Request On Normal Capture	✅	608ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests	✅	1212ms
Request Lifecycle.Mock Response Value Is Returned To Caller	✅	608ms
Retry Behavior.Retries Flags On 502	✅	910ms
Retry Behavior.Retries Flags On 504	✅	911ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event	✅	1211ms

[dustinbyrne]

[P1] Minimal flag calls drop the session ID populated by the Plug integration.

PostHog.Integrations.Plug stores x-posthog-session-id in event context as $session_id. The minimal path merges that context before applying Map.take/2, but $session_id isn't in this allowlist, so gated non-experiment flag calls lose their session linkage.

Could we add $session_id to the atom/string allowlist and cover this through the Plug integration in a public-entry test, proving the session ID survives while unrelated request context remains stripped?

[github-actions]

This PR hasn't seen activity in a week! Should it be merged, closed, or further worked on? If you want to keep it open, post a comment or remove the stale label – otherwise this will be closed in another week.