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

The OVERRIDE specification requires an evaluation to be marked as
override-affected when any definition it read carried the override
marker: the evaluated flag, a prerequisite at any depth, or a segment
consulted during matching, whether or not the segment matched. The
marking propagates upward only. A prerequisite's own record reflects
only the definitions that its own subtree read. An evaluation that fails
is still marked when it read a marked definition.

DataModel.FeatureFlag and DataModel.Segment carry a transient
isOverride marker that is never serialized and never read from JSON,
with a markedAsOverride() shallow copy that the override layer will use
without modifying the source's entity.

The evaluator tracks the marking per evaluation scope: the scope starts
from its own flag's marker, each segment read can set it, and the value
is saved, reset to the prerequisite's marker, and restored around each
prerequisite evaluation. The result and every prerequisite record carry
the marking on their reason. EvalResult exposes isOverrideAffected() and
withOverrideAffected(), which copies rather than mutating the shared
precomputed results. A requested-type mismatch keeps the marking on its
error reason.

The server SDK now depends on launchdarkly-java-sdk-common 2.6.0, which
adds the overrideAffected indicator to EvaluationReason. CI for this
change cannot pass until that version is released.

Flag overrides are currently experimental and subject to change.

Author: kinyoklion

lib/sdk/server/build.gradle

@@ -70,7 +70,7 @@ ext.versions = [
     "gson": "2.13.1",
     "guava": "32.0.1-jre",
     "jackson": "2.11.2",
-    "launchdarklyJavaSdkCommon": "2.3.0",
+    "launchdarklyJavaSdkCommon": "2.6.0",
     "launchdarklyJavaSdkInternal": "1.11.1",
     "launchdarklyLogging": "1.1.0",
     "okhttp": "4.12.0", // specify this for the SDK build instead of relying on the transitive dependency from okhttp-eventsource

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/DataModel.java

@@ -145,6 +145,15 @@ static final class FeatureFlag implements VersionedData, JsonHelpers.PostProcess
     private Migration migration;
     private boolean excludeFromSummaries;
 
+    // True if this definition came from the SDK's override store rather than from LaunchDarkly. The
+    // field is transient so that it never appears in the JSON form of the flag and never takes part
+    // in deserialization. Only the override layer sets it, on a copy that it owns. Evaluation reads
+    // it to mark the evaluation as override-affected. Other readers treat a marked flag the same as
+    // any other flag.
+    //
+    // Flag overrides are currently experimental and subject to change.
+    private transient boolean isOverride;
+
     /**
      * Container for migration specific flag data.
      */
@@ -267,6 +276,31 @@ boolean isExcludeFromSummaries() {
       return excludeFromSummaries;
     }
 
+    /**
+     * Returns true if this definition came from the override store.
+     *
+     * @return true for an override entry
+     */
+    boolean isOverride() {
+      return isOverride;
+    }
+
+    /**
+     * Returns a shallow copy of this flag that carries the override marker. The copy shares its
+     * nested lists and its preprocessing data with this flag and never writes to them. This flag is
+     * not modified.
+     *
+     * @return a marked copy
+     */
+    FeatureFlag markedAsOverride() {
+      FeatureFlag copy = new FeatureFlag(key, version, on, prerequisites, salt, targets, contextTargets, rules,
+          fallthrough, offVariation, variations, clientSide, trackEvents, trackEventsFallthrough,
+          debugEventsUntilDate, deleted, samplingRatio, migration, excludeFromSummaries);
+      copy.preprocessed = preprocessed;
+      copy.isOverride = true;
+      return copy;
+    }
+
     public void afterDeserialized() {
       DataModelPreprocessing.preprocessFlag(this);
     }
@@ -507,6 +541,10 @@ static final class Segment implements VersionedData, JsonHelpers.PostProcessingD
     private ContextKind unboundedContextKind;
     private Integer generation;
 
+    // True if this definition came from the SDK's override store rather than from LaunchDarkly. See
+    // the note on the same field in FeatureFlag.
+    private transient boolean isOverride;
+
     Segment() {}
 
     Segment(String key,
@@ -588,6 +626,28 @@ public Integer getGeneration() {
       return generation;
     }
 
+    /**
+     * Returns true if this definition came from the override store.
+     *
+     * @return true for an override entry
+     */
+    boolean isOverride() {
+      return isOverride;
+    }
+
+    /**
+     * Returns a shallow copy of this segment that carries the override marker. The copy shares its
+     * nested collections with this segment and never writes to them. This segment is not modified.
+     *
+     * @return a marked copy
+     */
+    Segment markedAsOverride() {
+      Segment copy = new Segment(key, included, excluded, includedContexts, excludedContexts, salt, rules,
+          version, deleted, unbounded, unboundedContextKind, generation);
+      copy.isOverride = true;
+      return copy;
+    }
+
     public void afterDeserialized() {
       DataModelPreprocessing.preprocessSegment(this);
     }

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/EvalResult.java

@@ -228,6 +228,14 @@ public EvaluationDetail<String> getAsString() {
    */
   public boolean isForceReasonTracking() { return forceReasonTracking; }
 
+  /**
+   * Returns true if an override affected this evaluation, directly or transitively. The value is
+   * the reason's indicator, so the result and the reason it returns to the caller always agree.
+   * Flag overrides are currently experimental and subject to change.
+   * @return true if an override affected the evaluation
+   */
+  public boolean isOverrideAffected() { return anyType.getReason().isOverrideAffected(); }
+
   public List<PrerequisiteEvalRecord> getPrerequisiteEvalRecords() { return prerequisiteEvalRecords; }
 
   /**
@@ -251,6 +259,17 @@ public EvalResult withForceReasonTracking(boolean newValue) {
   public EvalResult withPrerequisiteEvalRecords(List<PrerequisiteEvalRecord> newValue) {
     return this.prerequisiteEvalRecords == newValue ? this : new EvalResult(this, newValue);
   }
+
+  /**
+   * Returns a transformed copy of this EvalResult whose reason carries the given override-affected
+   * indicator, or this same instance if the indicator is unchanged. Precomputed results are shared
+   * between evaluations, so a marked result is always a new instance.
+   * @param newValue the new value for the indicator
+   * @return a transformed copy
+   */
+  public EvalResult withOverrideAffected(boolean newValue) {
+    return withReason(anyType.getReason().withOverrideAffected(newValue));
+  }
 
   @Override
   public boolean equals(Object other) {

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/Evaluator.java

@@ -124,6 +124,12 @@ private static class EvaluatorState {
     private List<String> prerequisiteStack = null;
     private List<PrerequisiteEvalRecord> prerequisiteEvalRecords =  new ArrayList<>(0); // 0 initial capacity uses a static instance for performance
     private List<String> segmentStack = null;
+    // True if the current evaluation scope has read a definition that carries the override marker.
+    // The scope starts from its own flag's marker. Each segment read can set it. Around a
+    // prerequisite evaluation the value is saved and reset, so the prerequisite's record reflects
+    // only the definitions that its own subtree read, and the parent scope accumulates that result
+    // afterwards. The marking therefore propagates upward only.
+    private boolean overrideAffected = false;
   }
 
   Evaluator(Getters getters, LDLogger logger) {
@@ -146,6 +152,8 @@ EvalResult evaluate(FeatureFlag flag, LDContext context, @Nonnull EvaluationReco
 
     EvaluatorState state = new EvaluatorState();
     state.originalFlag = flag;
+    // Reading the flag's own definition is the first read of this scope.
+    state.overrideAffected = flag.isOverride();
 
     try {
       EvalResult result = evaluateInternal(flag, context, recorder, state);
@@ -160,10 +168,12 @@ EvalResult evaluate(FeatureFlag flag, LDContext context, @Nonnull EvaluationReco
         result = result.withPrerequisiteEvalRecords(state.prerequisiteEvalRecords);
       }
 
-      return result;
+      return result.withOverrideAffected(state.overrideAffected);
     } catch (EvaluationException e) {
       logger.error("Could not evaluate flag \"{}\": {}", flag.getKey(), e.getMessage());
-      return EvalResult.error(e.errorKind);
+      // An error result is marked too. A malformed override definition yields the caller's default
+      // value with an error reason, and an override still affected that result.
+      return EvalResult.error(e.errorKind).withOverrideAffected(state.overrideAffected);
     }
   }
 
@@ -246,7 +256,20 @@ private EvalResult checkPrerequisites(FeatureFlag flag, LDContext context, @Nonn
           logger.error("Could not retrieve prerequisite flag \"{}\" when evaluating \"{}\"", prereq.getKey(), flag.getKey());
           prereqOk = false;
         } else {
-          EvalResult prereqEvalResult = evaluateInternal(prereqFeatureFlag, context, recorder, state);
+          // The prerequisite evaluation is a scope of its own. Its marking starts from its own flag's
+          // marker, so its record reflects only the definitions that its subtree read. This scope
+          // accumulates that result afterwards, whether the nested evaluation returns or throws.
+          boolean parentOverrideAffected = state.overrideAffected;
+          state.overrideAffected = prereqFeatureFlag.isOverride();
+          EvalResult prereqEvalResult;
+          boolean prereqOverrideAffected;
+          try {
+            prereqEvalResult = evaluateInternal(prereqFeatureFlag, context, recorder, state);
+          } finally {
+            prereqOverrideAffected = state.overrideAffected;
+            state.overrideAffected = parentOverrideAffected || prereqOverrideAffected;
+          }
+          prereqEvalResult = prereqEvalResult.withOverrideAffected(prereqOverrideAffected);
           // 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 (!prereqFeatureFlag.isOn() || prereqEvalResult.getVariationIndex() != prereq.getVariation()) {
@@ -461,6 +484,12 @@ private boolean matchAnySegment(List<LDValue> values, LDContext context, Evaluat
       }
       Segment segment = getters.getSegment(segmentKey);
       if (segment != null) {
+        // The segment definition is read at this point, so an override segment marks the scope here.
+        // A match is not required. A negated clause turns a non-match into a match, so the definition
+        // shapes the result either way.
+        if (segment.isOverride()) {
+          state.overrideAffected = true;
+        }
         if (segmentMatchesContext(segment, context, state)) {
           return true;
         }

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/InputValidatingEvaluator.java

@@ -135,7 +135,11 @@ EvalResultAndFlag evaluate(String flagKey, LDContext context, LDValue defaultVal
             value.getType() != requireType) {
           logger.error("Feature flag \"{}\"; evaluation expected result as {}, but got {}", flagKey, defaultValue.getType(), value.getType());
           recorder.recordEvaluationError(featureFlag, context, defaultValue, ErrorKind.WRONG_TYPE);
-          return new EvalResultAndFlag(EvalResult.error(ErrorKind.WRONG_TYPE, defaultValue), featureFlag);
+          // The type mismatch replaces the reason. The evaluation read the same definitions, so the
+          // new reason keeps the override-affected marking.
+          return new EvalResultAndFlag(
+              EvalResult.error(ErrorKind.WRONG_TYPE, defaultValue).withOverrideAffected(result.isOverrideAffected()),
+              featureFlag);
         }
       }
 

lib/sdk/server/src/test/java/com/launchdarkly/sdk/server/DataModelTest.java

@@ -11,9 +11,20 @@
 import com.launchdarkly.sdk.server.DataModel.SegmentRule;
 import com.launchdarkly.sdk.server.DataModel.Target;
 
+import com.launchdarkly.sdk.LDValue;
+import com.launchdarkly.sdk.server.subsystems.DataStoreTypes.ItemDescriptor;
+
 import org.junit.Test;
 
+import static com.launchdarkly.sdk.server.ModelBuilders.flagBuilder;
+import static com.launchdarkly.sdk.server.ModelBuilders.prerequisite;
+import static com.launchdarkly.sdk.server.ModelBuilders.segmentBuilder;
 import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNotSame;
+import static org.junit.Assert.assertNull;
+import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertTrue;
 
 @SuppressWarnings("javadoc")
 public class DataModelTest {
@@ -108,4 +119,82 @@ private Segment segmentWithAllZeroValuedFields() {
     // and no preprocessing has happened.
     return new Segment();
   }
+
+  @Test
+  public void flagAndSegmentAreNotOverridesByDefault() {
+    assertFalse(flagBuilder("f").build().isOverride());
+    assertFalse(segmentBuilder("s").build().isOverride());
+    assertFalse(((FeatureFlag) DataModel.FEATURES.deserialize("{\"key\":\"f\",\"version\":1}").getItem()).isOverride());
+    assertFalse(((Segment) DataModel.SEGMENTS.deserialize("{\"key\":\"s\",\"version\":1}").getItem()).isOverride());
+  }
+
+  @Test
+  public void markedFlagCopyCarriesMarkerAndSharesDataWithoutMutatingSource() {
+    FeatureFlag source = flagBuilder("f").version(7).on(true).variations(LDValue.of("a"), LDValue.of("b"))
+        .fallthroughVariation(1).offVariation(0).prerequisites(prerequisite("p", 1)).trackEvents(true)
+        .debugEventsUntilDate(1000L).build();
+
+    FeatureFlag marked = source.markedAsOverride();
+
+    assertTrue(marked.isOverride());
+    assertFalse(source.isOverride());
+    assertNotSame(source, marked);
+    assertEquals(source.getKey(), marked.getKey());
+    assertEquals(source.getVersion(), marked.getVersion());
+    assertEquals(source.isOn(), marked.isOn());
+    assertSame(source.getVariations(), marked.getVariations());
+    assertSame(source.getPrerequisites(), marked.getPrerequisites());
+    assertSame(source.getFallthrough(), marked.getFallthrough());
+    assertEquals(source.getOffVariation(), marked.getOffVariation());
+    assertEquals(source.isTrackEvents(), marked.isTrackEvents());
+    assertEquals(source.getDebugEventsUntilDate(), marked.getDebugEventsUntilDate());
+    assertSame(source.preprocessed, marked.preprocessed);
+  }
+
+  @Test
+  public void markedFlagCopyOfUnpreprocessedFlagHasNoPreprocessing() {
+    FeatureFlag source = flagBuilder("f").disablePreprocessing(true).build();
+    FeatureFlag marked = source.markedAsOverride();
+    assertNull(marked.preprocessed);
+    assertNull(source.preprocessed);
+    assertTrue(marked.isOverride());
+  }
+
+  @Test
+  public void markedSegmentCopyCarriesMarkerAndSharesDataWithoutMutatingSource() {
+    Segment source = segmentBuilder("s").version(3).included("u1").excluded("u2").unbounded(false).build();
+
+    Segment marked = source.markedAsOverride();
+
+    assertTrue(marked.isOverride());
+    assertFalse(source.isOverride());
+    assertNotSame(source, marked);
+    assertEquals(source.getKey(), marked.getKey());
+    assertEquals(source.getVersion(), marked.getVersion());
+    assertSame(source.getIncluded(), marked.getIncluded());
+    assertSame(source.getExcluded(), marked.getExcluded());
+    assertSame(source.getRules(), marked.getRules());
+  }
+
+  @Test
+  public void overrideMarkerIsNeverSerialized() {
+    FeatureFlag flag = flagBuilder("f").version(7).build().markedAsOverride();
+    String flagJson = DataModel.FEATURES.serialize(new ItemDescriptor(flag.getVersion(), flag));
+    assertFalse(flagJson.toLowerCase().contains("override"));
+    assertEquals(LDValue.of("f"), LDValue.parse(flagJson).get("key"));
+
+    Segment segment = segmentBuilder("s").version(3).build().markedAsOverride();
+    String segmentJson = DataModel.SEGMENTS.serialize(new ItemDescriptor(segment.getVersion(), segment));
+    assertFalse(segmentJson.toLowerCase().contains("override"));
+  }
+
+  @Test
+  public void overrideMarkerInJsonIsIgnoredWhenDeserializing() {
+    FeatureFlag flag = (FeatureFlag) DataModel.FEATURES.deserialize(
+        "{\"key\":\"f\",\"version\":1,\"isOverride\":true}").getItem();
+    assertFalse(flag.isOverride());
+    Segment segment = (Segment) DataModel.SEGMENTS.deserialize(
+        "{\"key\":\"s\",\"version\":1,\"isOverride\":true}").getItem();
+    assertFalse(segment.isOverride());
+  }
 }

lib/sdk/server/src/test/java/com/launchdarkly/sdk/server/EvalResultTest.java

@@ -13,6 +13,7 @@
 import static org.hamcrest.MatcherAssert.assertThat;
 import static org.hamcrest.Matchers.equalTo;
 import static org.hamcrest.Matchers.is;
+import static org.hamcrest.Matchers.not;
 import static org.hamcrest.Matchers.sameInstance;
 
 @SuppressWarnings("javadoc")
@@ -134,6 +135,52 @@ public void withForceReasonTracking() {
     assertThat(r1.getAnyType(), sameInstance(r.getAnyType()));
   }
 
+  @Test
+  public void overrideAffectedFollowsTheReason() {
+    EvalResult r = EvalResult.of(SOME_VALUE, SOME_VARIATION, SOME_REASON);
+    assertThat(r.isOverrideAffected(), is(false));
+    assertThat(EvalResult.of(SOME_VALUE, SOME_VARIATION, SOME_REASON.withOverrideAffected(true)).isOverrideAffected(),
+        is(true));
+    assertThat(EvalResult.error(EvaluationReason.ErrorKind.MALFORMED_FLAG).isOverrideAffected(), is(false));
+  }
+
+  @Test
+  public void withOverrideAffected() {
+    EvalResult r = EvalResult.of(SOME_VALUE, SOME_VARIATION, SOME_REASON);
+
+    // Unchanged value keeps the same instance, so shared precomputed results stay shared.
+    assertThat(r.withOverrideAffected(false), sameInstance(r));
+
+    EvalResult marked = r.withOverrideAffected(true);
+    assertThat(marked, not(sameInstance(r)));
+    assertThat(marked.isOverrideAffected(), is(true));
+    assertThat(marked.getReason(), equalTo(SOME_REASON.withOverrideAffected(true)));
+    assertThat(marked.getValue(), equalTo(r.getValue()));
+    assertThat(marked.getVariationIndex(), equalTo(r.getVariationIndex()));
+    assertThat(marked.withOverrideAffected(true), sameInstance(marked));
+    assertThat(marked.withOverrideAffected(false), equalTo(r));
+
+    // Every typed view carries the marked reason.
+    assertThat(marked.getAsBoolean().getReason().isOverrideAffected(), is(true));
+    assertThat(marked.getAsInteger().getReason().isOverrideAffected(), is(true));
+    assertThat(marked.getAsDouble().getReason().isOverrideAffected(), is(true));
+    assertThat(marked.getAsString().getReason().isOverrideAffected(), is(true));
+    assertThat(marked.getAnyType().getReason().isOverrideAffected(), is(true));
+
+    // The original is untouched.
+    assertThat(r.isOverrideAffected(), is(false));
+  }
+
+  @Test
+  public void withOverrideAffectedKeepsPrerequisiteRecordsAndForceTracking() {
+    EvalResult r = EvalResult.of(SOME_VALUE, SOME_VARIATION, EvaluationReason.fallthrough(true))
+        .withPrerequisiteEvalRecords(java.util.Collections.singletonList(
+            new PrerequisiteEvalRecord(null, null, EvalResult.of(SOME_VALUE, SOME_VARIATION, SOME_REASON))));
+    EvalResult marked = r.withOverrideAffected(true);
+    assertThat(marked.isForceReasonTracking(), is(true));
+    assertThat(marked.getPrerequisiteEvalRecords(), sameInstance(r.getPrerequisiteEvalRecords()));
+  }
+
   private <T> void testForType(T value, LDValue ldValue, Function<EvalResult, T> getter) {
     assertThat(
         getter.apply(EvalResult.of(EvaluationDetail.fromValue(ldValue, SOME_VARIATION, SOME_REASON))),