feat: Keep override-affected evaluations out of individual events

packages/shared/common/__tests__/internal/evaluation/EventFactoryBase.test.ts

@@ -0,0 +1,35 @@
+import Context from '../../../src/Context';
+import EventFactoryBase from '../../../src/internal/evaluation/EventFactoryBase';
+
+const context = Context.fromLDContext({ key: 'user-key' });
+
+function evalEvent(factory: EventFactoryBase, overrideAffected?: boolean) {
+  return factory.evalEvent({
+    context,
+    defaultVal: 'default',
+    flagKey: 'flag',
+    trackEvents: true,
+    value: 'value',
+    variation: 1,
+    version: 3,
+    reason: { kind: 'FALLTHROUGH' },
+    overrideAffected,
+  });
+}
+
+it('carries the override marking on the evaluation event', () => {
+  const event = evalEvent(new EventFactoryBase(true), true);
+  expect(event.overrideAffected).toBe(true);
+  expect(event.key).toEqual('flag');
+  expect(event.trackEvents).toBe(true);
+});
+
+it('omits the marking when the evaluation was not affected', () => {
+  expect(evalEvent(new EventFactoryBase(true), false).overrideAffected).toBe(false);
+  expect(evalEvent(new EventFactoryBase(true))).not.toHaveProperty('overrideAffected');
+});
+
+it('does not mark an unknown flag event', () => {
+  const event = new EventFactoryBase(false).unknownFlagEvent('flag', 'default', context);
+  expect(event).not.toHaveProperty('overrideAffected');
+});

packages/shared/common/__tests__/internal/events/EventProcessor.test.ts

@@ -243,6 +243,54 @@ describe('given an event processor', () => {
     ]);
   });
 
+  it('produces no feature or debug event for an override-affected evaluation and marks its counter', async () => {
+    Date.now = jest.fn(() => 1000);
+    // Both flags request individual feature events and debug events. Only the override-affected
+    // evaluation is kept out of the individual event stream.
+    const base = {
+      kind: 'feature' as const,
+      creationDate: 1000,
+      context: Context.fromLDContext(user),
+      version: 11,
+      variation: 1,
+      value: 'value',
+      trackEvents: true,
+      debugEventsUntilDate: 2000,
+      default: 'default',
+      samplingRatio: 1,
+      withReasons: true,
+    };
+    eventProcessor.sendEvent({ ...base, key: 'flagkey', overrideAffected: true });
+    eventProcessor.sendEvent({ ...base, key: 'plain' });
+
+    await eventProcessor.flush();
+
+    expect(mockSendEventData).toBeCalledWith(LDEventType.AnalyticsEvents, [
+      testIndexEvent,
+      makeFeatureEvent(1000, 11, false, 'plain'),
+      makeFeatureEvent(1000, 11, true, 'plain'),
+      {
+        endDate: 1000,
+        features: {
+          flagkey: {
+            contextKinds: ['user'],
+            counters: [
+              { count: 1, value: 'value', variation: 1, version: 11, overrideAffected: true },
+            ],
+            default: 'default',
+          },
+          plain: {
+            contextKinds: ['user'],
+            counters: [{ count: 1, value: 'value', variation: 1, version: 11 }],
+            default: 'default',
+          },
+        },
+        kind: 'summary',
+        startDate: 1000,
+      },
+    ]);
+  });
+
   it('uses sampling ratio for feature events', async () => {
     Date.now = jest.fn(() => 1000);
     eventProcessor.sendEvent({

packages/shared/common/__tests__/internal/events/EventSummarizer.test.ts

@@ -318,3 +318,38 @@ describe('given an event summarizer', () => {
     expect(secondSummary.endDate).toBe(0);
   });
 });
+
+it('keeps override-affected evaluations in a separate counter that carries the marker', () => {
+  const summarizer = new EventSummarizer();
+  const context = Context.fromLDContext({ key: 'key' });
+  const base = {
+    kind: 'feature',
+    creationDate: 1000,
+    key: 'key1',
+    version: 11,
+    context,
+    variation: 1,
+    value: 100,
+    default: 111,
+  };
+
+  summarizer.summarizeEvent(base as any);
+  summarizer.summarizeEvent({ ...base, overrideAffected: true } as any);
+  summarizer.summarizeEvent({ ...base, overrideAffected: true } as any);
+
+  const data = summarizer.getSummary();
+  const { counters } = data.features.key1;
+  expect(counters).toHaveLength(2);
+
+  const plain = counters.find((counter) => !counter.overrideAffected);
+  const marked = counters.find((counter) => counter.overrideAffected);
+  expect(plain).toEqual({ value: 100, count: 1, variation: 1, version: 11 });
+  expect(plain).not.toHaveProperty('overrideAffected');
+  expect(marked).toEqual({
+    value: 100,
+    count: 2,
+    variation: 1,
+    version: 11,
+    overrideAffected: true,
+  });
+});

packages/shared/common/src/internal/evaluation/EventFactoryBase.ts

@@ -9,6 +9,7 @@ export type EvalEventArgs = {
   defaultVal: any;
   excludeFromSummaries?: boolean;
   flagKey: string;
+  overrideAffected?: boolean;
   prereqOfFlagKey?: string;
   reason?: LDEvaluationReason;
   samplingRatio?: number;
@@ -37,6 +38,7 @@ export default class EventFactoryBase {
       e.debugEventsUntilDate,
       e.excludeFromSummaries,
       e.samplingRatio,
+      e.overrideAffected,
     );
   }
 

packages/shared/common/src/internal/events/EventProcessor.ts

@@ -287,9 +287,14 @@ export default class EventProcessor implements LDEventProcessor {
 
     const isFeatureEvent = isFeature(inputEvent);
 
-    const addFullEvent = (isFeatureEvent && inputEvent.trackEvents) || !isFeatureEvent;
+    // An override-affected evaluation appears only in the summary counters. It produces no
+    // individual feature event and no debug event, even when the flag requests them.
+    const overrideAffected = isFeatureEvent && !!inputEvent.overrideAffected;
 
-    const addDebugEvent = this._shouldDebugEvent(inputEvent);
+    const addFullEvent =
+      (isFeatureEvent && inputEvent.trackEvents && !overrideAffected) || !isFeatureEvent;
+
+    const addDebugEvent = !overrideAffected && this._shouldDebugEvent(inputEvent);
 
     const isIdentifyEvent = isIdentify(inputEvent);
     const shouldNotDeduplicate = this._contextDeduplicator?.processContext(inputEvent.context);

packages/shared/common/src/internal/events/EventSummarizer.ts

@@ -10,10 +10,14 @@ import LDEventSummarizer, {
 } from './LDEventSummarizer';
 import SummaryCounter from './SummaryCounter';
 
+// The override marker is part of the key, so override-affected and other evaluations of the same
+// flag, variation, and version accumulate into separate counters.
 function counterKey(event: InputEvalEvent) {
   return `${event.key}:${
     event.variation !== null && event.variation !== undefined ? event.variation : ''
-  }:${event.version !== null && event.version !== undefined ? event.version : ''}`;
+  }:${event.version !== null && event.version !== undefined ? event.version : ''}:${
+    event.overrideAffected ? 'overrideAffected' : ''
+  }`;
 }
 
 /**
@@ -59,6 +63,7 @@ export default class EventSummarizer implements LDEventSummarizer {
           event.default,
           event.version,
           event.variation,
+          event.overrideAffected,
         );
       }
 
@@ -96,6 +101,10 @@ export default class EventSummarizer implements LDEventSummarizer {
         } else {
           counterOut.unknown = true;
         }
+        if (counter.overrideAffected) {
+          // The marker is present only when true, like the unknown marker.
+          counterOut.overrideAffected = true;
+        }
         flagSummary.counters.push(counterOut);
 
         return acc;

packages/shared/common/src/internal/events/InputEvalEvent.ts

@@ -24,6 +24,13 @@ export default class InputEvalEvent {
 
   public readonly excludeFromSummaries?: boolean;
 
+  /**
+   * True when an override affected the evaluation, directly or transitively. The SDK sets it
+   * from the evaluation result, not from the reason. A marked evaluation produces no individual
+   * feature or debug event and is counted in a summary counter that carries the marker.
+   */
+  public readonly overrideAffected?: boolean;
+
   constructor(
     public readonly withReasons: boolean,
     public readonly context: Context,
@@ -38,6 +45,7 @@ export default class InputEvalEvent {
     debugEventsUntilDate?: number,
     excludeFromSummaries?: boolean,
     public readonly samplingRatio: number = 1,
+    overrideAffected?: boolean,
   ) {
     this.creationDate = Date.now();
     this.value = value;
@@ -70,5 +78,9 @@ export default class InputEvalEvent {
     if (excludeFromSummaries !== undefined) {
       this.excludeFromSummaries = excludeFromSummaries;
     }
+
+    if (overrideAffected !== undefined) {
+      this.overrideAffected = overrideAffected;
+    }
   }
 }

packages/shared/common/src/internal/events/LDEventSummarizer.ts

@@ -9,6 +9,10 @@ export interface FlagCounter {
   variation?: number;
   version?: number;
   unknown?: boolean;
+  /**
+   * Present, and true, only for a counter that aggregates override-affected evaluations.
+   */
+  overrideAffected?: boolean;
 }
 
 /**

packages/shared/common/src/internal/events/SummaryCounter.ts

@@ -11,6 +11,7 @@ export default class SummaryCounter {
     defValue: any,
     public version?: number,
     public variation?: number,
+    public overrideAffected?: boolean,
   ) {
     this.default = defValue;
   }