Skip to content

feat(flags): support known-absent property keys in local evaluation - #261

Open
marandaneto wants to merge 6 commits into
mainfrom
feat/flags-known-absent-property-keys
Open

marandaneto wants to merge 6 commits into
mainfrom
feat/flags-known-absent-property-keys

Conversation

@marandaneto

@marandaneto marandaneto commented Nov 19, 2026 •

Copy link
Copy Markdown
Member

💡 Motivation and Context

Local feature flag evaluation treats a property key missing from person_properties or group_properties as unknown. That is the right default, because the SDK can't tell "this person has no plan" apart from "the caller didn't pass plan". But it means callers have no way to say "this person definitely doesn't have plan". A flag with an is_not_set condition on plan can't resolve locally and falls back to /flags. The local result and the /flags result could also disagree.

This PR adds an optional way to list property keys the caller knows are absent. It follows the cross-SDK spec in PostHog/sdk-specs#233 and the backend support in PostHog/posthog#138239.

Closes part of PostHog/posthog#88947.

New options

Every flag evaluation entry point that takes a body accepts two new optional keys. That covers evaluate_flags/2, get_feature_flag_result/4, check/3, flags/2 and flags_for/2, plus bodies built from PostHog.set_context/2.

  • :person_property_keys_known_absent is a list of person property keys.
  • :group_property_keys_known_absent is a map from group type to a list of group property keys.

Keys can be strings or atoms.

PostHog.FeatureFlags.evaluate_flags(%{
  distinct_id: "user-123",
  groups: %{organization: "acme"},
  person_properties: %{email: "a@example.com"},
  person_property_keys_known_absent: ["plan"],
  group_property_keys_known_absent: %{organization: ["tier"]}
})

Local evaluation

  • For a listed key, is_not_set, is_not, not_icontains, not_starts_with, not_ends_with and not_regex match without a /flags call.
  • is_set and every other operator do not match. That includes exact, the search and regex operators, numeric comparisons, all semver_* operators (including semver_neq) and the date operators.
  • A listed key counts as absent even when the caller also passed a value for it. It also wins over values the SDK adds itself, such as distinct_id for person properties and $group_key for group properties.
  • A key that is missing and not listed stays unknown, the same as today.
  • Person keys that start with __posthog_person_metadata__ are ignored.
  • Group keys only apply to their own group type.
  • Operators the SDK doesn't support, and malformed condition values, keep their current result. For example icontains_multi on a listed key still falls back to /flags.
  • Dynamic cohort property filters use the listed key before applying the filter's negation. Static cohorts and holdouts are unchanged.
  • Operator support is checked before the known-absent table, in flag conditions and in cohort leaves, as required by the latest spec revision (docs(flags): specify known-absent property keys sdk-specs#233). The test unsupported not_between in a dynamic cohort leaf on a listed key stays inconclusive covers a cohort leaf, with and without negation.
  • Flag dependencies are evaluated with the same listed keys.

/flags request body

When the SDK calls /flags and the caller listed keys, the request sends person_property_keys_known_absent: [...] and group_property_keys_known_absent: %{group_type => [...]}. This happens on local fallback and on remote-only calls. A field is left out when the caller didn't provide it or it is empty. Group types with an empty list are dropped.

Validation and the 1000-key limit

Each list holds at most 1000 keys. Duplicates count, and each group type is counted on its own. A longer list returns {:error, %PostHog.Error{}}. The SDK does not truncate the list and does not send a request. The same error is returned for values of the wrong type. That covers a non-list, non-string keys, invalid UTF-8, improper lists, and a group type given both as an atom and as a string. String-keyed bodies passed to flags/2 are checked the same way as atom-keyed ones.

Not included

Links

💚 How did you test it?

New tests in test/posthog/feature_flags/known_absent_property_keys_test.exs cover:

  • the result of each supported operator on a listed key, with and without a supplied value
  • listed keys winning over the injected distinct_id and $group_key
  • an unlisted missing key staying unknown
  • the metadata prefix being ignored
  • group type scoping, including group conditions inside a person flag
  • unsupported operators and malformed values on a listed key keeping their current result
  • dynamic cohort negation and flag dependencies
  • the /flags body including the fields on fallback and leaving them out when empty or not provided
  • string-keyed bodies passed to flags/2
  • the 1000-key limit and wrong-type inputs returning an error without a request
  • an unsupported not_between in a dynamic cohort leaf on a listed key staying inconclusive with unsupported_definition, with and without negation

I ran these locally. All passed.

  • mix test: 1131 passed, 18 excluded (integration tests, which need a real API key, were not run). One earlier full run had a single failure that did not come back in three later runs.
  • mix format --check-formatted
  • mix compile --warnings-as-errors
  • mix credo --strict
  • mix posthog.public_api --check

CI now runs SDK test harness 1.34.0 (47 of 47 compliance tests passed). The feature_flags_known_absent suite does not run, because the adapter declares only capture_v0 and encoding_gzip, not feature_flags_local_evaluation_v1 or feature_flags_known_absent_v1.

📝 Checklist

  • All commits are signed (see Commit signing)
  • 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

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Written with Pi agents (Claude) as one lane of a change across several SDKs. An automated review (autoreview, GPT model) ran three rounds. The first two rounds found input validation gaps: string-keyed bodies, improper lists, invalid group type keys, invalid UTF-8, and duplicate group types. Those are fixed in follow-up commits. The third round asked to reject a nil list for one group type. I kept that case as "nothing listed" to match how a top-level nil or an empty list is handled.

@marandaneto marandaneto self-assigned this Nov 19, 2026
@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

posthog-elixir Compliance Report

Date: 2026-11-20T09:52:15.527262+00:00
Duration: 111200ms

✅ All Tests Passed!

47/47 tests passed


Capture Tests

✅ 30/30 tests passed

View Details
Test Status Duration
Format Validation.Event Has Required Fields ✅ 608ms
Format Validation.Event Has Uuid ✅ 609ms
Format Validation.Event Has Lib Properties ✅ 609ms
Format Validation.Distinct Id Is String ✅ 609ms
Format Validation.Token Is Present ✅ 609ms
Format Validation.Custom Properties Preserved ✅ 607ms
Format Validation.Event Has Timestamp ✅ 609ms
Format Validation.Non Utc Event Timestamp Is Converted To Utc ✅ 609ms
Retry Behavior.Retries On 503 ✅ 5613ms
Retry Behavior.Does Not Retry On 400 ✅ 2610ms
Retry Behavior.Does Not Retry On 401 ✅ 2611ms
Retry Behavior.Respects Retry After Header ✅ 5614ms
Retry Behavior.Implements Backoff ✅ 15615ms
Retry Behavior.Retries On 500 ✅ 5615ms
Retry Behavior.Retries On 502 ✅ 5614ms
Retry Behavior.Retries On 504 ✅ 5613ms
Retry Behavior.Max Retries Respected ✅ 15611ms
Deduplication.Generates Unique Uuids ✅ 618ms
Deduplication.Preserves Uuid On Retry ✅ 5609ms
Deduplication.Preserves Uuid And Timestamp On Retry ✅ 10616ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry ✅ 5615ms
Deduplication.No Duplicate Events In Batch ✅ 613ms
Deduplication.Different Events Have Different Uuids ✅ 611ms
Compression.Sends Gzip When Enabled ✅ 609ms
Batch Format.Uses Proper Batch Structure ✅ 608ms
Batch Format.Flush With No Events Sends Nothing ✅ 606ms
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 ✅ 5614ms

Feature_Flags Tests

✅ 17/17 tests passed

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

@marandaneto
marandaneto marked this pull request as ready for review November 20, 2026 10:29
@marandaneto
marandaneto requested a review from a team as a code owner November 20, 2026 10:29
@veria-ai

veria-ai Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

PR overview

No security issues were found in this pull request.

Reviews

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant