Feature Toggle Evaluator · Analysis

01 · Frame the problem

Understand the central challenge

Design a pure feature-toggle evaluator over a supplied validated snapshot. Rules have ordered conditions, typed results and optional percentage allocation. Unknown/malformed context must not silently coerce into a match.

Evaluation should be a pure function of typed rules, context and revision. Analyse missing values, type mismatches, rule priority and cohort hashing so the same inputs do not produce environment-dependent decisions.

02 · Find the design pressure

Start simple, then identify the gap

Begin with immutable snapshots and explicit predicate semantics. Implicit coercion or random per-request rollout makes behavior hard to reproduce. Return a value plus safe reason metadata, without hidden network calls or sensitive context echoing.

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. 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 · Define success

Requirements to preserve

Enforce typed flag values and explicit rule priority.
Use a specified stable hash for percentage cohorts.
Handle missing attributes and invalid context predictably.
Return evaluation reason and snapshot/model metadata without side effects.

04 · Identify the correctness boundary

Invariants, representation and mutation boundaries

Evaluate one immutable typed snapshot without network calls or hidden randomness. Canonicalize the subject and hashing inputs, define missing/type-mismatch predicate behavior, and apply rules in a documented order. Return reason and revision metadata without echoing sensitive targeting context.

05 · Make it concrete

Reason through a worked example

A rule expects numeric age but receives a string. It follows the declared mismatch behavior rather than coercing unexpectedly. The same subject, salt and snapshot produce the same percentage bucket across calls. An absent flag returns its configured safe fallback with an explicit missing-flag reason.