Repository navigation
feat(flags): accept a flag call that drops a broken rule pair (contract 9.0.0) - #101
Merged
Merged
Conversation
Follow PostHog/sdk-specs#162. On a config version 2 $feature_flag_called, $feature_flag_rule_id and $feature_flag_rule_type are sent together or not at all, and only with a rule type the reason code allows. A record with a missing rule ID, a missing rule type or a disallowed rule type loses the whole pair; the call keeps the config version and reason code. The called-context schema only tolerated this for a malformed experiment_split. The presence-schema generator now emits one dropped-attribution branch per reason that names a rule in the matrix (targeting_match, experiment_split, rollout_miss, experiment_paused, holdout). The malformed-split branch is generated the same way, with the same shape. A half pair and a disallowed rule type are still rejected. The meta-tests check a call without attribution for each of those reasons, the complete call for every matrix row, and each half pair and disallowed rule type. The set of accepted calls grows, so this is contract package 9.0.0.
minimal-adapter Compliance ReportDate: 2026-11-04T12:48:52.853592+00:00 ✅ All Tests Passed!17/17 tests passed Feature_Flags Tests✅ 17/17 tests passed View Details
|
parallel-adapter Compliance ReportDate: 2026-11-04T12:49:04.903692+00:00 ✅ All Tests Passed!17/17 tests passed Feature_Flags Tests✅ 17/17 tests passed View Details
|
5 tasks done
A failed record reads as disabled, so the legacy payload accessor yields
no payload for it, even when the record still carries metadata.payload.
readers.v1_failed is such a record: a producer-valid failed config
version 1 record with payload {"columns":2}. The contract defined its
error code but said nothing about the payload.
Reader expectations gain an optional legacy_payload: null for no
payload, otherwise the JSON-encoded payload string. readers.v1_failed
pins null. A meta-test checks every declared legacy_payload against the
record, and requires one on any failed reader case that carries a
payload. Part of contract package 9.0.0.
This was referenced Nov 4, 2026
andehen
marked this pull request as ready for review
November 4, 2026 11:30
This was referenced Nov 4, 2026
…tribution - `legacy_payload` is the decoded JSON value the payload accessor returns, not the encoded wire string, as the reader section already says accessors decode. The meta-test decodes the wire payload and treats invalid JSON as no payload. `readers.v1_at_v4` declares its decoded payload so the encoding is pinned. - The called-context meta-tests add each attribution field to a call without attribution, for every reason that names a rule and for `flag_disabled`, and check that a `flag_disabled` call without attribution is valid. Before this, a generator that stopped forbidding a field on a dropped call still passed.
stamphog
Bot
dismissed
their stale review
November 4, 2026 12:37
A new stamphog review started for this PR — the fresh verdict replaces this approval.
… code A config version 2 `$feature_flag_called` whose `$feature_flag_reason_code` is missing, or is not a registered reason code, is now valid if it carries no rule, variant or experiment attribution. It keeps config version 2 and the raw code, if any. - The generator adds one branch for these calls. It excludes every reason that has a branch of its own, and every other branch now requires its reason code, so the branches do not overlap. A registered code still goes through its own branches: a `targeting_match` call with a half pair is still rejected. - The `then` clause no longer requires a reason code on every version 2 call. - Meta-tests: an unknown and a missing code without attribution are valid; each attribution field, and each complete rule pair, on such a call is invalid; the catch-all excludes exactly the registry's reason codes.
stamphog
Bot
dismissed
their stale review
November 4, 2026 12:48
A new stamphog review started for this PR — the fresh verdict replaces this approval.
There was a problem hiding this comment.
Not approved — this change needs a human reviewer.
The public-contract changes have current-head assurance and a STRONG-familiarity author, with no outstanding review concerns. However, the additional acceptance of missing or unregistered reason codes is undisclosed risky behavior; document that expansion and request human review before re-requesting.
- Author wrote 100% of the modified lines and has 13 merged PRs in these paths (familiarity STRONG).
- PostHog Review (Standard) reviewed the current head: no findings.
- Undisclosed risky behavior: bin/update-feature-flag-rules-v2-presence-schemas.py adds unregistered_reason_branch, and the generated called-context schema now accepts version 2 events with missing or unregistered reason codes. The title and description discuss dropping broken attribution for known reasons but do not disclose this additional contract expansion. Update the PR description to disclose it and request human review of that expansion before re-requesting.
Gate mechanics and policy version
| Gate | Result | |
|---|---|---|
| prerequisites | ✓ | all clear |
| deny-list | ✓ | no deny categories matched |
| size | ✓ | 295L, 4F substantive, 477L/7F incl. docs/generated/snapshots — within ceiling |
| tier | ✓ | T1-agent / T1d-complex (477L, 7F, cross-cutting, feat) |
| stamphog 2.7.0 | .stamphog/policy.yml @ c429b69 · reviewed head c429b69 |
dustinbyrne
approved these changes
Nov 4, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
PostHog/sdk-specs#162 says that on a config version 2
$feature_flag_called,$feature_flag_rule_idand$feature_flag_rule_typeare sent together or not at all, and only with a rule type the reason code allows:targeting_matchtargeted_release,percentage_rolloutrollout_misspercentage_rollout,experimentexperiment_paused,holdoutexperimentIf the record has no rule ID, no rule type or a disallowed type, the SDK sends neither rule field. The event keeps the config version and reason code, and the read's value does not change.
Contract 8.0.0's
feature_flag_called_context.schema.jsononly accepts a call without attribution for a malformedexperiment_split. For the four reasons above, a call that follows the spec and drops the pair fails the schema.Changes
bin/update-feature-flag-rules-v2-presence-schemas.pygenerates one dropped-attribution branch for each reason that names a rule inrules/response_presence.json. Each branch allows a call with the reason code and none of the rule, variant or experiment fields. This coverstargeting_match,experiment_split,rollout_miss,experiment_pausedandholdout.flag_disabledstays hand-written.targeting_matchwithexperiment, are still rejected. Complete pairs are unchanged.flag_disabled(invalid);flag_disabledcall without attribution (valid);Missing or unregistered reason code
The spec sends
$feature_flag_reason_codeonly when the record has one, and sends no rule fields for any other reason code. Contract 8.0.0 required a registered reason code on every config version 2 call.reason_codes, is valid with no rule, variant or experiment attribution. It keeps config version 2 and the raw code, if any.targeting_matchcall with a half pair is still rejected.thenclause no longer requires a reason code on every version 2 call.No legacy payload for a failed record
A failed record reads as disabled, so the legacy payload accessor yields no payload for it, even when the record still carries
metadata.payload. A payload on a flag that reads as disabled would surprise users.readers.v1_failedis such a record: a producer-valid failed config version 1 record with payload{"columns":2}. The contract defined its error code but said nothing about the payload.legacy_payload:nullfor no payload, otherwise the decoded JSON value the accessor returns, not the encoded string on the wire.readers.v1_failedpinsnull. Its other expectations are unchanged.readers.v1_at_v4declares{"columns": 2}for the wire payload"{\"columns\":2}", so the encoding is pinned by a fixture.legacy_payloadagainst the record (decoding the wire payload, with invalid JSON as no payload), and fails if a failed reader case that carries a payload does not declare one.Versioning
minorchangeset.RELEASING.mduses minor for new tests and backwards-compatible additions. That matches the earlier contract changes (feat(flags): name the rules v2 response record v4 (contract 7.0.0) #91, feat(flags): trim the SDK experiment exposure contract #98), which were also minor harness releases.Checks
uv run --frozen pytest: full suite passes.ruff check,black --checkon the changed files andgit diff --checkall pass.uv build --sdist: the archive'scontracts/feature_flag_rules_v2matches the tree.🤖 Generated with Claude Code