[kinyoklion]

Summary

This is the second step of the flag overrides port described by the OVERRIDE specification. It is based on the shared file data branch because the phases are stacked; retarget to feat/overrides once that branch merges.

The FeatureFlag and Segment models gain an override marker, is_override. The SDK represents stored entities with typed model classes distinct from their JSON form, so the marker is carried on the type and never in the JSON: to_json_dict(), the data kind encoder, and ModelEncoder produce the same output for a marked and an unmarked entity, and a persistent store never sees it. with_override_marker() returns a marked shallow copy that shares the definition and leaves the source unmarked, so a source can retain and resupply its entities. Only the SDK components that manage override entries (added in the next step) set the marker.

The evaluator marks an evaluation as override-affected when any definition it reads carries the marker: the evaluated flag, a prerequisite flag at any depth, or a segment consulted during clause matching. A read counts whether or not the segment matches, including through a negated clause and through a segment referenced by another segment's rule. A definition that cannot be resolved contributes nothing, because nothing was read. The marking propagates upward only: a prerequisite is an evaluation in its own right, its record reflects only the definitions its own subtree read, so an unaffected prerequisite inside a marked evaluation stays unmarked and a marked prerequisite does not mark a sibling. An evaluation that fails with an error reason, including a prerequisite cycle, is still marked when it read an override definition.

The marking is reported in two places that always agree: the overrideAffected indicator on the evaluation reason, present only when true so an unaffected reason serializes exactly as before, and EvalResult.override_affected, which the client and event processing read in the following steps. The AsyncEvaluator receives the same changes.

Tests cover each marking condition for both evaluators (flag off, fallthrough, and rule match; plain evaluations; malformed flag and prerequisite cycle errors; prerequisite records at depth one and two; unaffected sibling and downward non-propagation; segment reads with and without a match, negated, nested, and through a prerequisite; missing definitions; scalar and indicator agreement) and the model marker (default, marked copy, never serialized, shared definition).

SDK-3250

---

Note

Overview
Adds experimental flag override tracking: FeatureFlag and Segment now expose is_override and with_override_marker() on in-memory models only—the marker never appears in JSON or persisted data.

Sync and async evaluators set EvalResult.override_affected and, when true, add overrideAffected to the evaluation reason (documented on EvaluationDetail.reason). An evaluation is marked when the root flag, any prerequisite flag read during evaluation, or any segment loaded for rule matching carries the override marker; unresolved flags/segments do not count, and segment reads count even when the segment does not match (including negated clauses and nested segment rules). Prerequisite evaluation uses scoped marking that merges upward so sibling prereq events stay unmarked while affected subtrees and the top-level result reflect overrides; error outcomes are still marked if an override definition was read.

Extensive tests cover model serialization, marking rules, and parity between sync and async evaluators.

^{Reviewed by Cursor Bugbot for commit 1debdc2. Bugbot is set up for automated code reviews on this repo. Configure here.}

[kinyoklion]

bugbot review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 0013c0e. Configure here.}