WIP evaluator

AI-Session-Id: e73b729a-7564-4bc6-9e12-c7dade8008e6
AI-Tool: claude-code
AI-Model: unknown

Author: gthea

client/pom.xml

@@ -167,6 +167,11 @@
     </properties>
 
     <dependencies>
+        <dependency>
+            <groupId>io.split.client</groupId>
+            <artifactId>targeting-engine</artifactId>
+            <version>${project.version}</version>
+        </dependency>
         <dependency>
             <groupId>io.split.client</groupId>
             <artifactId>pluggable-storage</artifactId>

client/src/main/java/io/split/client/CacheUpdaterService.java

@@ -1,15 +1,13 @@
 package io.split.client;
 
-import com.google.common.collect.Lists;
 import io.split.client.dtos.ConditionType;
-import io.split.client.dtos.MatcherCombiner;
 import io.split.client.dtos.Partition;
 import io.split.engine.experiments.ParsedCondition;
 import io.split.engine.experiments.ParsedSplit;
-import io.split.engine.matchers.AllKeysMatcher;
-import io.split.engine.matchers.AttributeMatcher;
-import io.split.engine.matchers.CombiningMatcher;
-import io.split.engine.matchers.strings.WhitelistMatcher;
+import io.split.rules.matchers.AllKeysMatcher;
+import io.split.rules.matchers.AttributeMatcher;
+import io.split.rules.matchers.CombiningMatcher;
+import io.split.rules.matchers.WhitelistMatcher;
 import io.split.grammar.Treatments;
 import io.split.storages.SplitCacheProducer;
 
@@ -22,15 +20,15 @@
 import java.util.HashMap;
 import java.util.stream.Collectors;
 
-import static com.google.common.base.Preconditions.checkNotNull;
+import java.util.Objects;
 
 public final  class CacheUpdaterService {
 
     private static String LOCALHOST = "localhost";
     private SplitCacheProducer _splitCacheProducer;
 
     public CacheUpdaterService(SplitCacheProducer splitCacheProducer) {
-        _splitCacheProducer = checkNotNull(splitCacheProducer);
+        _splitCacheProducer = Objects.requireNonNull(splitCacheProducer);
     }
 
     public void updateCache(Map<SplitAndKey, LocalhostSplit> map) {
@@ -78,9 +76,10 @@ private List<ParsedCondition> getConditions(String splitKey, ParsedSplit split,
 
     private ParsedCondition createWhitelistCondition(String splitKey, Partition partition) {
         ParsedCondition parsedCondition = new ParsedCondition(ConditionType.WHITELIST,
-                new CombiningMatcher(MatcherCombiner.AND,
-                        Lists.newArrayList(new AttributeMatcher(null, new WhitelistMatcher(Lists.newArrayList(splitKey)), false))),
-                Lists.newArrayList(partition), splitKey);
+                new CombiningMatcher(CombiningMatcher.Combiner.AND,
+                        new java.util.ArrayList<>(java.util.Arrays.asList(
+                                new AttributeMatcher(null, new WhitelistMatcher(java.util.Arrays.asList(splitKey)), false)))),
+                new java.util.ArrayList<>(java.util.Arrays.asList(partition)), splitKey);
         return parsedCondition;
     }
 
@@ -89,9 +88,9 @@ private ParsedCondition createRolloutCondition(Partition partition) {
         rolloutPartition.treatment = "-";
         rolloutPartition.size = 0;
         ParsedCondition parsedCondition = new ParsedCondition(ConditionType.ROLLOUT,
-                new CombiningMatcher(MatcherCombiner.AND,
-                        Lists.newArrayList(new AttributeMatcher(null,  new AllKeysMatcher(), false))),
-                Lists.newArrayList(partition, rolloutPartition), "LOCAL");
+                new CombiningMatcher(CombiningMatcher.Combiner.AND,
+                        new java.util.ArrayList<>(java.util.Arrays.asList(new AttributeMatcher(null, new AllKeysMatcher(), false)))),
+                new java.util.ArrayList<>(java.util.Arrays.asList(partition, rolloutPartition)), "LOCAL");
 
         return parsedCondition;
     }

client/src/main/java/io/split/client/api/SplitView.java

@@ -11,6 +11,7 @@
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
+import java.util.stream.Collectors;
 
 
 /**
@@ -51,7 +52,13 @@ public static SplitView fromParsedSplit(ParsedSplit parsedSplit) {
         splitView.configs = parsedSplit.configurations() == null? Collections.<String, String>emptyMap() : parsedSplit.configurations() ;
         splitView.impressionsDisabled = parsedSplit.impressionsDisabled();
         splitView.prerequisites = parsedSplit.prerequisitesMatcher() != null ?
-                parsedSplit.prerequisitesMatcher().getPrerequisites(): new ArrayList<>();
+                parsedSplit.prerequisitesMatcher().getPrerequisites().stream()
+                        .map(p -> {
+                            Prerequisites prereq = new Prerequisites();
+                            prereq.featureFlagName = p.featureFlagName();
+                            prereq.treatments = p.treatments();
+                            return prereq;
+                        }).collect(Collectors.toList()) : new ArrayList<>();
 
         return splitView;
     }

client/src/main/java/io/split/client/impressions/AGENTS.md

@@ -0,0 +1,56 @@
+# AGENTS.md — client/impressions/
+
+## Purpose
+
+Impression tracking subsystem. Every `getTreatment()` call produces an **impression** — an audit record of what feature flag was evaluated, for which user, and what treatment was returned. This package manages batching, deduplication, and flushing of impressions to the Split API.
+
+**Warning:** Bugs here cause silent data loss — impressions won't be recorded, breaking Split's analytics and A/B testing.
+
+## Three Impression Modes
+
+Controlled by `SplitClientConfig.impressionsMode()`:
+
+| Mode | Class | Behavior |
+|------|-------|----------|
+| `DEBUG` | `ProcessImpressionDebug` | Every impression sent (no dedup) |
+| `OPTIMIZED` (default) | `ProcessImpressionOptimized` | Bloom filter dedup — only first impression per key+flag+treatment sent per hour |
+| `NONE` | `ProcessImpressionNone` | No impressions sent; unique keys tracked via `UniqueKeysTracker` |
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `ImpressionsManagerImpl.java` | Scheduler — batches impressions and flushes periodically |
+| `strategy/ProcessImpressionDebug.java` | DEBUG mode strategy |
+| `strategy/ProcessImpressionOptimized.java` | OPTIMIZED mode strategy |
+| `strategy/ProcessImpressionNone.java` | NONE mode strategy |
+| `filters/` | Bloom filter-based deduplication for OPTIMIZED mode |
+| `UniqueKeysTracker.java` | Tracks unique (key, featureFlag) pairs for NONE mode |
+
+## Data Flow
+
+```
+SplitClientImpl.getTreatment()
+  → EvaluatorImp returns (treatment, label, changeNumber)
+  → ImpressionsManagerImpl.track(Impression)
+    → ActiveStrategy.process(Impression)
+      → [DEBUG] always add to queue
+      → [OPTIMIZED] check Bloom filter; add if not seen
+      → [NONE] track unique keys, don't queue impression
+    → Queue flushes to Split API periodically
+```
+
+## Testing
+
+- **Run tests**: `mvn -pl :client -Dtest="*Impression*" test`
+- Test file pattern: `src/test/java/io/split/client/impressions/`
+
+## DOs
+
+- When changing evaluation logic, verify impressions are still recorded with correct label and change number.
+- When adding a new impression field, update all three strategy classes.
+
+## DON'Ts
+
+- Don't add deduplication logic outside the `filters/` package.
+- Don't assume `ImpressionsMode` is always `OPTIMIZED` — all three modes must work.

client/src/main/java/io/split/client/impressions/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

client/src/main/java/io/split/client/impressions/ImpressionHasher.java

@@ -1,6 +1,6 @@
 package io.split.client.impressions;
 
-import io.split.client.utils.MurmurHash3;
+import io.split.rules.bucketing.MurmurHash3;
 
 public class ImpressionHasher {
 

client/src/main/java/io/split/engine/AGENTS.md

@@ -0,0 +1,64 @@
+# AGENTS.md — engine/
+
+## Purpose
+
+The evaluation engine and synchronization subsystem. This is the most algorithmically complex package in the SDK. It handles:
+1. **Evaluation** — resolving feature flag treatments from `ParsedSplit` domain objects
+2. **Matchers** — 29 matcher implementations for all condition types
+3. **SSE streaming** — push notifications from the Split API
+4. **Polling/streaming orchestration** — `SyncManager` decides between streaming and polling
+
+## Package Structure
+
+```
+engine/
+├── evaluator/    # EvaluatorImp — the hot path for getTreatment()
+├── experiments/  # ParsedSplit domain model, SplitFetcher, SplitParser
+├── matchers/     # All matcher types (BetweenMatcher, Semver*, UserDefinedSegment, etc.)
+├── segments/     # Segment synchronization tasks
+├── sse/          # SSE streaming subsystem (38 classes)
+│   ├── client/   # EventSourceClientImp — manages SSE connection
+│   ├── workers/  # SplitUpdateWorker, SegmentUpdateWorker, etc.
+│   ├── dtos/     # SSE event payload DTOs
+│   └── ...       # PushStatusTrackerImp, NotificationProcessorImp
+├── common/       # SyncManager orchestration
+│   ├── SyncManagerImp.java       # Top-level: picks streaming vs. polling
+│   ├── SynchronizerImp.java      # Polling mode synchronizer
+│   ├── PushManagerImp.java       # Streaming mode manager
+│   └── ConsumerSynchronizer.java # Pluggable storage sync path
+├── splitter/     # Splitter.java — bucket assignment via MurmurHash
+└── metrics/      # (deprecated/noop metrics)
+```
+
+## Evaluation Flow (Hot Path)
+
+```
+SplitClientImpl.getTreatment()
+  → InputValidation
+  → EvaluatorImp.evaluateFeature()
+    → SplitCacheConsumer.get(featureName) → ParsedSplit
+    → Evaluates conditions in order (ParsedCondition[])
+      → Matcher.match(key, attributes)
+    → Splitter.getBucket(key, seed) → treatment
+  → ImpressionsManager.track(impression)
+  → TelemetryRuntimeProducer.recordLatency()
+```
+
+## Streaming vs. Polling Duality
+
+`SyncManagerImp` controls this at startup:
+- **Streaming mode** (default): `PushManagerImp` manages SSE connection. When an SSE update arrives, workers update storage directly and notify `SDKReadinessGates`.
+- **Polling mode** (fallback): `SynchronizerImp` schedules periodic HTTP fetches.
+- **Recovery**: If streaming fails, `SyncManagerImp` falls back to polling automatically.
+
+## Key Distinction: DTOs vs Domain Objects
+
+- `Split` (in `client/dtos/`) = wire format from the API
+- `ParsedSplit` (in `engine/experiments/`) = domain object used for evaluation
+- `SplitParser` converts `Split` → `ParsedSplit`
+- Never pass raw `Split` DTOs to the evaluator
+
+## Testing
+
+- **Run tests**: `mvn -pl :client -Dtest="*Evaluator*,*Matcher*,*Sse*" test`
+- **Key test classes**: `EvaluatorImpTest`, matcher-specific tests in `src/test/java/io/split/engine/`

client/src/main/java/io/split/engine/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

client/src/main/java/io/split/engine/evaluator/EvaluationContext.java

@@ -1,11 +1,17 @@
 package io.split.engine.evaluator;
 
+import io.split.client.dtos.ExcludedSegments;
+import io.split.engine.experiments.ParsedCondition;
+import io.split.engine.experiments.ParsedRuleBasedSegment;
+import io.split.rules.engine.EvaluationResult;
 import io.split.storages.RuleBasedSegmentCacheConsumer;
 import io.split.storages.SegmentCacheConsumer;
 
+import java.util.List;
+import java.util.Map;
 import java.util.Objects;
 
-public class EvaluationContext {
+public class EvaluationContext implements io.split.rules.engine.EvaluationContext {
     private final Evaluator _evaluator;
     private final SegmentCacheConsumer _segmentCacheConsumer;
     private final RuleBasedSegmentCacheConsumer _ruleBasedSegmentCacheConsumer;
@@ -28,4 +34,40 @@ public SegmentCacheConsumer getSegmentCache() {
     public RuleBasedSegmentCacheConsumer getRuleBasedSegmentCache() {
         return _ruleBasedSegmentCacheConsumer;
     }
+
+    @Override
+    public EvaluationResult evaluate(String matchingKey, String bucketingKey, String ruleName, Map<String, Object> attributes) {
+        EvaluatorImp.TreatmentLabelAndChangeNumber r = _evaluator.evaluateFeature(matchingKey, bucketingKey, ruleName, attributes);
+        return new EvaluationResult(r.treatment, r.label, r.changeNumber, r.configurations, r.track);
+    }
+
+    @Override
+    public boolean isInSegment(String segmentName, String key) {
+        return _segmentCacheConsumer.isInSegment(segmentName, key);
+    }
+
+    @Override
+    public boolean isInRuleBasedSegment(String segmentName, String key, String bucketingKey, Map<String, Object> attributes) {
+        ParsedRuleBasedSegment parsedRuleBasedSegment = _ruleBasedSegmentCacheConsumer.get(segmentName);
+        if (parsedRuleBasedSegment == null) {
+            return false;
+        }
+        if (parsedRuleBasedSegment.excludedKeys().contains(key)) {
+            return false;
+        }
+        for (ExcludedSegments excludedSegment : parsedRuleBasedSegment.excludedSegments()) {
+            if (excludedSegment.isStandard() && _segmentCacheConsumer.isInSegment(excludedSegment.name, key)) {
+                return false;
+            }
+            if (excludedSegment.isRuleBased() && isInRuleBasedSegment(excludedSegment.name, key, bucketingKey, attributes)) {
+                return false;
+            }
+        }
+        for (ParsedCondition condition : parsedRuleBasedSegment.parsedConditions()) {
+            if (condition.matcher().match(key, bucketingKey, attributes, this)) {
+                return true;
+            }
+        }
+        return false;
+    }
 }