Feature Toggle Evaluator · Approach

01 · Develop the design

Plan the design

Build a pure evaluator over immutable typed snapshots, with explicit predicate semantics and deterministic cohort hashing. Return safe reason metadata so callers can explain results without hidden I/O.

Stage 1

Make the core pure

Accept snapshot, subject and context as values. The evaluator should not fetch configuration or emit side effects while walking rules.

Stage 2

Validate outputs too

Rule variants and defaults must have the flag’s declared type. Unknown flag keys return an explicit caller fallback with a reason.

Stage 3

Return an explanation

Include rule ID, snapshot revision and fallback reason. Do not include raw sensitive context in traces.

02 · Work through the method

Step-by-step approach

Validate the snapshot’s schema, unique flag/rule identities, result types and hash-spec version at load time. Keep a runtime guard for unsupported or corrupt inputs.
Resolve the flag and validate context types. Operators use explicit typed comparisons; missing attributes return nonmatch unless an operator specifically handles absence.
Walk rules in declared order. For a matched percentage rule, derive a stable bucket from canonical salt/subject bytes using the versioned hash contract; compare against configured integer basis points.
Return a typed variant or configured/caller fallback with reason, rule ID and snapshot revision. The evaluator does not mutate context, read clocks implicitly or log raw attributes.

03 · Justify the choices

Why this approach works

Which matching rule wins?

The first match in the snapshot’s explicit ordered rule list

Rule precedence is part of evaluation semantics and cannot rely on incidental storage iteration.

How should missing attributes compare?

Return nonmatch or a declared context error under the operator contract

Missing/type-mismatched context must have specified behavior rather than surprising truthy coercion.

What makes percentage allocation reproducible?

A versioned hash/encoding/salt contract and stable subject identity

Equivalent inputs must yield the same bucket across runs and supported runtimes.

04 · Plan the evidence

Validation strategy

Ordered overlapping rules consistently choose the documented first match.
Missing or mismatched context does not match through truthy coercion.
Known hash vectors preserve cohort allocation at boundary basis points.
Unknown flags and invalid snapshots return typed safe fallbacks without mutating inputs.

Trade-offs to explain

A pure core is easy to test, while network refresh and snapshot staleness belong to an outer provider.
Changing hash input encoding or salt reshuffles cohorts and must be versioned deliberately.
Rich rule languages need bounded expression size/depth and a compatibility policy.