feat: Add the override marker to the models and mark evaluations

Adds an override marker to the FeatureFlag and Segment models. The marker is
an attribute of the model type, never part of the JSON representation, so
serializing an entity or writing it to a persistent store never carries it.
A marked shallow copy is produced with with_override_marker(), which leaves
the source entity unmarked and shares its definition.

The evaluator marks an evaluation as override-affected when any definition
it reads carries the marker: the evaluated flag, a prerequisite at any depth,
or a segment consulted during rule matching, including a segment that does
not match and a segment referenced by another segment. The marking propagates
upward only. A prerequisite's own record reflects the definitions its subtree
read, so an unaffected prerequisite inside a marked evaluation is not marked
and a marked prerequisite does not mark a sibling. An evaluation that fails
with an error reason is still marked when it read an override definition.

The marking appears on the evaluation reason as the overrideAffected
indicator, present only when true, and on EvalResult.override_affected for
the client and event processing. The async evaluator mirrors the sync one.

Author: kinyoklion

ldclient/evaluation.py

@@ -57,6 +57,12 @@ def reason(self) -> dict:
         * ``inExperiment``: This is true if the evaluation resulted in an experiment rollout and
           served one of the variations in the experiment. Otherwise it is false.
 
+        * ``overrideAffected``: This is true if a flag override affected the evaluation, directly
+          or indirectly. It is present only when true. An evaluation is affected when the flag
+          itself, a prerequisite flag at any depth, or a segment consulted during rule matching
+          came from the SDK's override store. Flag overrides are currently experimental and
+          subject to change.
+
         * ``bigSegmentsStatus``: describes the validity of Big Segment information, if and only if
           the flag evaluation required querying at least one Big Segment; otherwise it returns None.
           Allowable values are defined in :class:`BigSegmentsStatus`. For more information, read the

ldclient/impl/async_evaluator.py

@@ -15,7 +15,8 @@
     _match_clause_by_kind,
     _match_single_context_value,
     _maybe_negate,
-    check_targets
+    check_targets,
+    mark_override_affected
 )
 from ldclient.impl.events.types import EventFactory
 from ldclient.impl.model import *
@@ -56,15 +57,23 @@ def __init__(
     async def evaluate(self, flag: FeatureFlag, context: Context, event_factory: EventFactory) -> EvalResult:
         state = EvalResult()
         state.original_flag_key = flag.key
+        # Reading the flag's own definition is the first read of the evaluation, so the marking
+        # starts from the flag's override marker.
+        state.override_affected = flag.is_override
         try:
             state.detail = await self._evaluate(flag, context, state, event_factory)
         except EvaluationException as e:
             if self.__logger is not None:
                 self.__logger.error('Could not evaluate flag "%s": %s' % (flag.key, e.message))
             state.detail = EvaluationDetail(None, None, {'kind': 'ERROR', 'errorKind': e.error_kind})
+            # An evaluation that fails is still marked when it read an override definition.
+            if state.override_affected:
+                mark_override_affected(state.detail)
             return state
         if state.big_segments_status is not None:
             state.detail.reason['bigSegmentsStatus'] = state.big_segments_status
+        if state.override_affected:
+            mark_override_affected(state.detail)
         return state
 
     async def _evaluate(self, flag: FeatureFlag, context: Context, state: EvalResult, event_factory: EventFactory) -> EvaluationDetail:
@@ -120,9 +129,21 @@ async def _check_prerequisites(self, flag: FeatureFlag, context: Context, state:
                     log.warning("Missing prereq flag: " + prereq_key)
                     failed_prereq = prereq
                 else:
-                    state.depth += 1
-                    prereq_res = await self._evaluate(prereq_flag, context, state, event_factory)
-                    state.depth -= 1
+                    # The prerequisite is an evaluation in its own right. Its marking starts from
+                    # its own definition and covers only the definitions its subtree reads. The
+                    # parent's marking is restored and merged afterward, so the marking propagates
+                    # upward only. A failure inside the subtree still merges what was read.
+                    parent_override_affected = state.override_affected
+                    state.override_affected = prereq_flag.is_override
+                    try:
+                        state.depth += 1
+                        prereq_res = await self._evaluate(prereq_flag, context, state, event_factory)
+                        state.depth -= 1
+                    finally:
+                        prereq_override_affected = state.override_affected
+                        state.override_affected = parent_override_affected or prereq_override_affected
+                    if prereq_override_affected:
+                        mark_override_affected(prereq_res)
                     # Note that if the prerequisite flag is off, we don't consider it a match no matter what its
                     # off variation was. But we still need to evaluate it in order to generate an event.
                     if (not prereq_flag.on) or prereq_res.variation_index != prereq.variation:
@@ -146,7 +167,14 @@ async def _clause_matches_context(self, clause: Clause, context: Context, state:
         if clause.op == 'segmentMatch':
             for seg_key in clause.values:
                 segment = await self.__get_segment(seg_key)
-                if segment is not None and await self._segment_matches_context(segment, context, state):
+                if segment is None:
+                    continue
+                # The segment definition was read at this point, so an override segment marks the
+                # evaluation whether or not it matches. A segment that does not match still shapes
+                # the outcome, for example through a negated clause.
+                if segment.is_override:
+                    state.override_affected = True
+                if await self._segment_matches_context(segment, context, state):
                     return _maybe_negate(clause, True)
             return _maybe_negate(clause, False)
 

ldclient/impl/evaluator.py

@@ -17,7 +17,8 @@
     _maybe_negate,
     _variation_index_for_context,
     check_targets,
-    error_reason
+    error_reason,
+    mark_override_affected
 )
 from ldclient.impl.events.types import EventFactory
 from ldclient.impl.model import *
@@ -57,15 +58,23 @@ def __init__(
     def evaluate(self, flag: FeatureFlag, context: Context, event_factory: EventFactory) -> EvalResult:
         state = EvalResult()
         state.original_flag_key = flag.key
+        # Reading the flag's own definition is the first read of the evaluation, so the marking
+        # starts from the flag's override marker.
+        state.override_affected = flag.is_override
         try:
             state.detail = self._evaluate(flag, context, state, event_factory)
         except EvaluationException as e:
             if self.__logger is not None:
                 self.__logger.error('Could not evaluate flag "%s": %s' % (flag.key, e.message))
             state.detail = EvaluationDetail(None, None, {'kind': 'ERROR', 'errorKind': e.error_kind})
+            # An evaluation that fails is still marked when it read an override definition.
+            if state.override_affected:
+                mark_override_affected(state.detail)
             return state
         if state.big_segments_status is not None:
             state.detail.reason['bigSegmentsStatus'] = state.big_segments_status
+        if state.override_affected:
+            mark_override_affected(state.detail)
         return state
 
     def _evaluate(self, flag: FeatureFlag, context: Context, state: EvalResult, event_factory: EventFactory) -> EvaluationDetail:
@@ -118,9 +127,21 @@ def _check_prerequisites(self, flag: FeatureFlag, context: Context, state: EvalR
                     log.warning("Missing prereq flag: " + prereq_key)
                     failed_prereq = prereq
                 else:
-                    state.depth += 1
-                    prereq_res = self._evaluate(prereq_flag, context, state, event_factory)
-                    state.depth -= 1
+                    # The prerequisite is an evaluation in its own right. Its marking starts from
+                    # its own definition and covers only the definitions its subtree reads. The
+                    # parent's marking is restored and merged afterward, so the marking propagates
+                    # upward only. A failure inside the subtree still merges what was read.
+                    parent_override_affected = state.override_affected
+                    state.override_affected = prereq_flag.is_override
+                    try:
+                        state.depth += 1
+                        prereq_res = self._evaluate(prereq_flag, context, state, event_factory)
+                        state.depth -= 1
+                    finally:
+                        prereq_override_affected = state.override_affected
+                        state.override_affected = parent_override_affected or prereq_override_affected
+                    if prereq_override_affected:
+                        mark_override_affected(prereq_res)
                     # Note that if the prerequisite flag is off, we don't consider it a match no matter what its
                     # off variation was. But we still need to evaluate it in order to generate an event.
                     if (not prereq_flag.on) or prereq_res.variation_index != prereq.variation:
@@ -144,7 +165,14 @@ def _clause_matches_context(self, clause: Clause, context: Context, state: EvalR
         if clause.op == 'segmentMatch':
             for seg_key in clause.values:
                 segment = self.__get_segment(seg_key)
-                if segment is not None and self._segment_matches_context(segment, context, state):
+                if segment is None:
+                    continue
+                # The segment definition was read at this point, so an override segment marks the
+                # evaluation whether or not it matches. A segment that does not match still shapes
+                # the outcome, for example through a negated clause.
+                if segment.is_override:
+                    state.override_affected = True
+                if self._segment_matches_context(segment, context, state):
                     return _maybe_negate(clause, True)
             return _maybe_negate(clause, False)
 

ldclient/impl/evaluator_common.py

@@ -25,7 +25,7 @@
 # prerequisite evaluations, and the cached state of any Big Segments query that we may have
 # ended up having to do for the context.
 class EvalResult:
-    __slots__ = ['detail', 'events', 'big_segments_status', 'big_segments_membership', 'original_flag_key', 'prereq_stack', 'segment_stack', 'depth', 'prerequisites']
+    __slots__ = ['detail', 'events', 'big_segments_status', 'big_segments_membership', 'original_flag_key', 'prereq_stack', 'segment_stack', 'depth', 'prerequisites', 'override_affected']
 
     def __init__(self):
         self.detail = None
@@ -37,6 +37,11 @@ def __init__(self):
         self.segment_stack = None  # type: Optional[List[str]]
         self.depth = 0
         self.prerequisites = []  # type: List[str]
+        # True when the evaluation in progress has read a flag or segment definition that carries
+        # the override marker. While a prerequisite is evaluated, this holds the marking of the
+        # prerequisite's own subtree. The evaluator merges it into the parent's marking afterward,
+        # so the marking propagates upward only.
+        self.override_affected = False
 
     def record_prerequisite(self, key: str):
         if self.depth == 0:
@@ -255,3 +260,12 @@ def check_targets(flag: FeatureFlag, context: Context) -> Optional[EvaluationDet
 
 def error_reason(error_kind: str) -> dict:
     return {'kind': 'ERROR', 'errorKind': error_kind}
+
+
+def mark_override_affected(detail: EvaluationDetail) -> None:
+    """
+    Sets the override-affected indicator on the evaluation reason. The indicator is present
+    only when true, so a reason that was not affected by an override is left untouched and
+    serializes exactly as before.
+    """
+    detail.reason['overrideAffected'] = True

ldclient/impl/model/feature_flag.py

@@ -1,3 +1,4 @@
+import copy
 from typing import Any, Dict, List, Optional, Set, Union
 
 from ldclient.impl.model.clause import Clause
@@ -96,10 +97,12 @@ class FeatureFlag(ModelEntity):
         '_salt',
         '_track_events',
         '_debug_events_until_date',
+        '_is_override',
     ]
 
     def __init__(self, data: dict):
         super().__init__(data)
+        self._is_override = False
         # In the following logic, we're being somewhat lenient in terms of allowing most properties to
         # be absent even if they are really required in the schema. That's for backward compatibility
         # with test logic that constructed incomplete JSON, and also with the file data source which
@@ -202,3 +205,24 @@ def exclude_from_summaries(self) -> bool:
     @property
     def sampling_ratio(self) -> Optional[int]:
         return self._sampling_ratio
+
+    @property
+    def is_override(self) -> bool:
+        """
+        True if this flag definition was supplied by an SDK override source rather than by
+        LaunchDarkly data. The marker is never part of the JSON representation. Only the SDK
+        components that manage override entries set it. Components that read a definition
+        through the store may treat a marked definition the same as any other.
+
+        Flag overrides are currently experimental and subject to change.
+        """
+        return self._is_override
+
+    def with_override_marker(self) -> 'FeatureFlag':
+        """
+        Returns a shallow copy of this flag with the override marker set. The copy shares the
+        underlying data with this instance, which is left unmarked.
+        """
+        marked = copy.copy(self)
+        marked._is_override = True
+        return marked

ldclient/impl/model/segment.py

@@ -1,3 +1,4 @@
+import copy
 from typing import Any, List, Optional, Set
 
 from ldclient.impl.model.attribute_ref import (
@@ -65,10 +66,12 @@ class Segment(ModelEntity):
         '_unbounded',
         '_unbounded_context_kind',
         '_generation',
+        '_is_override',
     ]
 
     def __init__(self, data: dict):
         super().__init__(data)
+        self._is_override = False
         # In the following logic, we're being somewhat lenient in terms of allowing most properties to
         # be absent even if they are really required in the schema. That's for backward compatibility
         # with test logic that constructed incomplete JSON, and also with the file data source which
@@ -137,3 +140,24 @@ def unbounded_context_kind(self) -> Optional[str]:
     @property
     def generation(self) -> Optional[int]:
         return self._generation
+
+    @property
+    def is_override(self) -> bool:
+        """
+        True if this segment definition was supplied by an SDK override source rather than by
+        LaunchDarkly data. The marker is never part of the JSON representation. Only the SDK
+        components that manage override entries set it. Components that read a definition
+        through the store may treat a marked definition the same as any other.
+
+        Flag overrides are currently experimental and subject to change.
+        """
+        return self._is_override
+
+    def with_override_marker(self) -> 'Segment':
+        """
+        Returns a shallow copy of this segment with the override marker set. The copy shares the
+        underlying data with this instance, which is left unmarked.
+        """
+        marked = copy.copy(self)
+        marked._is_override = True
+        return marked