Skip to content

feat: Add the override marker to the model, evaluator, and reason - #450

Draft
kinyoklion wants to merge 1 commit into
rlamb/overrides-ruby-filedatafrom
rlamb/overrides-ruby-model-evaluator
Draft

kinyoklion wants to merge 1 commit into
rlamb/overrides-ruby-filedatafrom
rlamb/overrides-ruby-model-evaluator

Conversation

@kinyoklion

@kinyoklion kinyoklion commented Sep 25, 2026 •

Copy link
Copy Markdown
Member

Summary

This PR is stacked on #449 so that the flag overrides series applies in order. It does not use that PR's code.

Flag overrides, as defined by the OVERRIDE specification, need three pieces below the store: a marker on the flag and segment model that says a definition came from the override store, evaluator marking that follows every definition an evaluation reads, and an indicator on the evaluation reason that reports the marking to callers. This change adds those three pieces. Nothing sets the marker yet, so the SDK behaves exactly as before. The override store, the overlay, and the data system wiring follow in the next PR.

The model classes FeatureFlag and Segment carry the marker as an attribute that is never serialized, because as_json returns the flag data hash. as_override returns a marked shallow copy and leaves the original unchanged. Only the SDK components that manage override entries will set it.

The evaluator marks an evaluation as override-affected when the evaluated flag, a prerequisite flag at any depth, or a segment read during clause matching carries the marker. A segment counts when it is read, so a segment that does not match, or one read through a negated clause, still marks the evaluation. The marking propagates upward only. A prerequisite's own record reflects the definitions its own subtree read, so a plain prerequisite inside a marked evaluation is recorded as usual, and a prerequisite of an overridden flag is not marked by its parent. An error result is marked when a marked definition was read before the failure, including a failure raised while a prerequisite was being evaluated. An evaluation that reads no marked definition keeps the shared precomputed detail instances.

EvaluationReason#override_affected carries the indicator, following the inExperiment and bigSegmentsStatus precedents. It is written to JSON as overrideAffected only when true, so the wire format of ordinary evaluations is unchanged. with_override_affected returns the same instance when nothing changes, and with_big_segments_status keeps the indicator.

Verification: specs for the model marker (default, copy, original unchanged, not serialized), the reason indicator (default, JSON when true and when false, [], equality, interaction with the big segments status), and the evaluator marking rules (direct, prerequisite at any depth, upward-only propagation, unaffected prerequisite record, segment read with and without a match, negated clause, nested segment, unresolved definition, prerequisite failure, malformed override, error raised during a prerequisite evaluation, big segments status kept). Full suite and RuboCop are clean. Each new spec was checked against a deliberate defect in the code it covers.

The existing FDv1 and FDv2 file data sources keep their current behavior. This series does not change them; the override feature is additive.

Flag overrides, as defined by the OVERRIDE specification, need three
pieces below the store: a marker on the flag and segment model that says a
definition came from the override store, evaluator marking that follows
every definition an evaluation reads, and an indicator on the evaluation
reason that reports the marking to callers.

The model classes carry the marker as an attribute that is never
serialized. `as_override` returns a marked shallow copy and leaves the
original unchanged. Only the SDK components that manage override entries
set it.

The evaluator marks an evaluation as override-affected when the evaluated
flag, a prerequisite flag at any depth, or a segment read during clause
matching carries the marker. A segment counts when it is read, so a
segment that does not match, or that is read through a negated clause,
still marks the evaluation. The marking propagates upward only: a
prerequisite's own record reflects the definitions its own subtree read,
and a plain prerequisite inside a marked evaluation is not marked. An
error result is marked when a marked definition was read before the
failure, including when the failure was raised while a prerequisite was
being evaluated. An evaluation that reads no marked definition keeps the
shared precomputed detail instances.

`EvaluationReason#override_affected` carries the indicator. It is
written to JSON as `overrideAffected` only when true, so the wire format
of ordinary evaluations is unchanged. `with_override_affected` follows the
`with_big_segments_status` precedent and returns the same instance when
nothing changes.

Flag overrides are currently experimental and subject to change.
@kinyoklion
kinyoklion force-pushed the rlamb/overrides-ruby-filedata branch from eb26dd7 to 72d5776 Compare September 28, 2026 20:36
@kinyoklion
kinyoklion force-pushed the rlamb/overrides-ruby-model-evaluator branch from 4810ac9 to 20eea70 Compare September 28, 2026 20:36

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant