Domain Language & Concepts

Copy Markdown View Source

Welcome to Rulestead! Feature flag vocabulary varies widely across the industry. Teams often use flag, feature, toggle, switch, rule, and remote config interchangeably.

To ensure clear communication and prevent mental model leaks from other systems, Rulestead uses a strict, unified vocabulary. This guide defines the core concepts you will see in the UI, API, and telemetry.

Core Distinctions

Flag vs Feature vs Toggle

  • Flag (Canonical) — A named runtime decision point with an owner, a lifecycle, a value type, and rules that produce a value given a context. This is the term used everywhere in Rulestead.
  • Feature — The actual product capability the flag gates. Flags gate features; flags are not features.
  • Toggle — A specific kind of flag (boolean-typed, release category). Every toggle is a flag, but not every flag is a toggle.

Rule vs Strategy vs Condition

  • Rule (Canonical) — One ordered entry in a ruleset. It matches a set of conditions and produces an outcome. Rulestead uses an ordered-rules model (like a firewall) rather than a precedence-based gate model.
  • Condition — A predicate inside a rule (e.g., plan == "enterprise").
  • Strategy — How a matched rule produces a value (e.g., forced value, percentage rollout, variant split).

Audience vs Segment vs Cohort

  • Audience (Canonical) — A reusable targeting definition, surfaced in the Admin UI. Every audience has a key, description, and targeting criteria.
  • Segment — Internal implementation detail. Never surfaced in user-facing copy.

Variant vs Value

  • Variant — One named option in a multivariate flag (e.g., :control, :treatment_a), with a value and an optional weight.
  • Value (Canonical) — The resolved, typed output of an evaluation.

Rollout

  • Rollout (Canonical) — The progressive expansion of a flag's exposure (0% → N% → 100%) over time or conditions. A flag can have at most one active rollout at a time.

Kill Switch

  • Kill Switch (Canonical) — An immediate, flag-wide override that forces a specific variant (usually the safe default) regardless of rules. Engaging or releasing a kill switch always generates an audit trail.

Context & Actor

  • Context (Canonical) — The full evaluation input, including the actor, tenant, environment, attributes, and request metadata.
  • Actor (Canonical) — The entity whose experience the flag affects (e.g., a user, service, or job).
  • Targeting Key (Canonical) — The stable identifier used for deterministic bucketing (usually the actor ID, but can be overridden).

Architecture Concepts

Snapshot vs Manifest

  • Snapshot — The in-memory compiled representation of all flags, rulesets, and audiences for fast local evaluation. Snapshots are versioned, immutable, and automatically refreshed via PubSub.
  • Manifest — The declarative source-of-truth document (YAML/JSON) used in flag-as-code workflows. Manifests are imported; snapshots are compiled.

Lifecycle States

  • Draft — Created, not yet activated.
  • Active — Being evaluated in the intended environment.
  • Archived — No longer evaluated; kept for audit history.
  • Killswitched — Active but forcibly overridden by an engaged kill switch.
  • Potentially Stale — Nearing its expected_lifetime_days without recent evaluations.
  • Stale — Past expected lifetime, no evaluations recently. Surfaced in the UI for cleanup.
  • Retired — Explicitly removed from production after cleanup.