Skip to content

feat(flags): accept a flag call that drops a broken rule pair (contract 9.0.0) - #101

Merged
andehen merged 4 commits into
mainfrom
andehen/called-context-tolerant-rule-pair
Nov 5, 2026
Merged

andehen merged 4 commits into
mainfrom
andehen/called-context-tolerant-rule-pair

Conversation

@andehen

@andehen andehen commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

Problem

PostHog/sdk-specs#162 says that 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:

Reason code Allowed rule types
targeting_match targeted_release, percentage_rollout
rollout_miss percentage_rollout, experiment
experiment_paused, holdout experiment

If 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.json only accepts a call without attribution for a malformed experiment_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.py generates one dropped-attribution branch for each reason that names a rule in rules/response_presence.json. Each branch allows a call with the reason code and none of the rule, variant or experiment fields. This covers targeting_match, experiment_split, rollout_miss, experiment_paused and holdout.
  • The hand-written malformed-split branch is now generated the same way, with the same shape. Only flag_disabled stays hand-written.
  • A half pair and a disallowed rule type, such as targeting_match with experiment, are still rejected. Complete pairs are unchanged.
  • Regenerating the schemas is a no-op, and the meta-test checks that.
  • The wire meta-tests add:
    • a call without attribution for each of the five reasons (valid);
    • the complete call for every matrix row (valid);
    • each missing required rule field for every row that names a rule (invalid);
    • each rule type the reason does not allow (invalid);
    • a call without attribution plus any one attribution field, for each of the five reasons and for flag_disabled (invalid);
    • a flag_disabled call without attribution (valid);
    • a call with an unregistered reason code, and one with no reason code, without attribution (valid);
    • each attribution field, and each complete rule pair, on such a call (invalid).
  • The event schemas still have no fixture set, as in feat(flags): trim the SDK experiment exposure contract #98, so the cases build their projections in the tests.
  • The contract README describes the pair rule.

Missing or unregistered reason code

The spec sends $feature_flag_reason_code only 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.

  • The generator adds one more branch: a config version 2 call whose reason code is missing, or is not one of the registry's reason_codes, is valid with no rule, variant or experiment attribution. It keeps config version 2 and the raw code, if any.
  • That branch excludes every reason that has a branch of its own, and every other branch now requires its reason code, so no call matches two branches. 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.
  • Checked against the previous head on 2304 generated calls (every reason, rule type and attribution combination, config versions 1, 2 and absent): only the two intended calls changed, from invalid to valid.

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_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 decoded JSON value the accessor returns, not the encoded string on the wire. readers.v1_failed pins null. Its other expectations are unchanged. readers.v1_at_v4 declares {"columns": 2} for the wire payload "{\"columns\":2}", so the encoding is pinned by a fixture.
  • A meta-test checks every declared legacy_payload against 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.
  • The contract README's reader section states the rule and how to model it.

Versioning

Checks

  • uv run --frozen pytest: full suite passes.
  • ruff check, black --check on the changed files and git diff --check all pass.
  • uv build --sdist: the archive's contracts/feature_flag_rules_v2 matches the tree.

🤖 Generated with Claude Code

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.
@github-actions

github-actions Bot commented Nov 4, 2026 •

Copy link
Copy Markdown

minimal-adapter Compliance Report

Date: 2026-11-04T12:48:52.853592+00:00
Duration: 2856ms

✅ All Tests Passed!

17/17 tests passed


Feature_Flags Tests

✅ 17/17 tests passed

View Details
Test Status Duration
Request Payload.Request With Person Properties Device Id ✅ 11ms
Request Payload.Flags Request Uses V2 Query Param ✅ 8ms
Request Payload.Flags Request Hits Flags Path Not Decide ✅ 6ms
Request Payload.Flags Request Omits Authorization Header ✅ 7ms
Request Payload.Token In Flags Body Matches Init ✅ 7ms
Request Payload.Groups Round Trip ✅ 7ms
Request Payload.Groups Default To Empty Object ✅ 7ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False ✅ 6ms
Request Payload.Disable Geoip Omitted Defaults To False ✅ 8ms
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 ✅ 9ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests ✅ 11ms
Request Lifecycle.Mock Response Value Is Returned To Caller ✅ 7ms
Retry Behavior.Retries Flags On 502 ✅ 1010ms
Retry Behavior.Retries Flags On 504 ✅ 1011ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event ✅ 11ms

@github-actions

github-actions Bot commented Nov 4, 2026 •

Copy link
Copy Markdown

parallel-adapter Compliance Report

Date: 2026-11-04T12:49:04.903692+00:00
Duration: 1714ms

✅ All Tests Passed!

17/17 tests passed


Feature_Flags Tests

✅ 17/17 tests passed

View Details
Test Status Duration
Request Payload.Request With Person Properties Device Id ✅ 22ms
Request Payload.Flags Request Uses V2 Query Param ✅ 22ms
Request Payload.Flags Request Hits Flags Path Not Decide ✅ 24ms
Request Payload.Flags Request Omits Authorization Header ✅ 22ms
Request Payload.Token In Flags Body Matches Init ✅ 17ms
Request Payload.Groups Round Trip ✅ 28ms
Request Payload.Groups Default To Empty Object ✅ 16ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False ✅ 24ms
Request Payload.Disable Geoip Omitted Defaults To False ✅ 23ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key ✅ 21ms
Request Lifecycle.No Flags Request On Init Alone ✅ 8ms
Request Lifecycle.No Flags Request On Normal Capture ✅ 20ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests ✅ 29ms
Request Lifecycle.Mock Response Value Is Returned To Caller ✅ 19ms
Retry Behavior.Retries Flags On 502 ✅ 1022ms
Retry Behavior.Retries Flags On 504 ✅ 1023ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event ✅ 16ms

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.
stamphog[bot]

This comment was marked as outdated.

…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
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.

stamphog[bot]

This comment was marked as outdated.

… 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
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.

@stamphog stamphog Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@andehen
andehen merged commit 425e9cd into main Nov 5, 2026
14 checks passed
@andehen
andehen deleted the andehen/called-context-tolerant-rule-pair branch November 5, 2026 09:21
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.

2 participants