dials 0.1.0

data/lib/dials/cache.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module Dials
+  # Per-process, in-memory snapshot cache.
+  #
+  # Reads never query the store per-dial: they read from the current
+  # Snapshot. The snapshot is (re)built from the store on first use, and
+  # thereafter freshness is maintained two ways:
+  #
+  #   1. Local writes bust the cache immediately — the process that made a
+  #      change reads its own write on the next get.
+  #   2. Other processes converge via a throttled staleness probe: at most
+  #      once per `ttl` seconds, a read asks the store for its version (a
+  #      single cheap query) and rebuilds only when it moved.
+  #
+  # ttl = 0 probes on every read (strong consistency, one extra query per
+  # read); ttl = nil never probes (bust!/reload! only). Default is 5 seconds.
+  #
+  # Concurrency rules (each one is a production lesson, not a style choice):
+  #
+  #   - The store is NEVER queried while holding a lock. Holding a mutex
+  #     across a database call can deadlock a multi-threaded server: the
+  #     builder waits for a pooled connection while every connection is held
+  #     by threads blocked on the mutex.
+  #   - A stale refresh is single-flight (try_lock); threads that lose the
+  #     race serve the still-valid current snapshot instead of stampeding
+  #     the database. The probe timestamp is claimed BEFORE the version
+  #     query, so a burst of readers crossing the TTL boundary doesn't fan
+  #     out into a probe stampede either.
+  #   - A bust! that lands while a rebuild is in flight WINS: the rebuild
+  #     read state before the bust's write, so publishing it would hide that
+  #     write for a full TTL. The generation counter detects this and drops
+  #     the stale publish (the requesting reader still gets the built
+  #     snapshot; the next reader rebuilds fresh).
+  #   - Once a snapshot has EVER been built, probe and rebuild failures
+  #     serve last-known-good (with a warning) rather than raising — a
+  #     database blip must not take down every dial read, including the read
+  #     right after a local write busted the current snapshot. Only a cold
+  #     process that has never built one raises: nothing honest exists to
+  #     serve there.
+  class Cache
+    def initialize(store:, ttl: 5.0)
+      @store = store
+      @ttl = ttl
+      @build_mutex = Mutex.new
+      @state_mutex = Mutex.new # guards @generation/@snapshot writes; never held across store calls
+      @snapshot = nil
+      @last_good = nil
+      @probed_at = nil
+      @generation = 0
+    end
+
+    attr_accessor :ttl
+
+    def snapshot
+      current = @snapshot
+      return build_or_last_good if current.nil?
+      return current unless probe_due?
+
+      # Claim the probe slot up front: concurrent readers crossing the TTL
+      # boundary see a fresh timestamp and skip their own probes.
+      @probed_at = monotonic_now
+
+      begin
+        return current if @store.version == current.version
+      rescue StandardError => e
+        warn "[dials] staleness probe failed; serving the cached snapshot (#{e.class}: #{e.message})"
+        return current
+      end
+
+      refresh(current)
+    end
+
+    # A fresh, UNPUBLISHED snapshot straight from the store. Used for reads
+    # that must not pollute (or be served from) the shared cache — e.g. a
+    # thread that wrote a dial inside a still-open database transaction and
+    # must see its own uncommitted state without leaking it to other threads.
+    def uncached_snapshot
+      Snapshot.new(**@store.state)
+    end
+
+    # Busting discards the published snapshot but NOT the last-known-good
+    # copy: if the rebuild after a write fails, reads degrade to slightly
+    # stale values instead of exceptions.
+    def bust!
+      @state_mutex.synchronize do
+        @generation += 1
+        @snapshot = nil
+        @probed_at = nil
+      end
+    end
+
+    private
+
+    def probe_due?
+      return false if @ttl.nil?
+      return true if @ttl.zero?
+
+      last = @probed_at
+      last.nil? || (monotonic_now - last) >= @ttl
+    end
+
+    # No published snapshot (cold start, or just busted by a write): build,
+    # and on failure fall back to the last snapshot this process ever built —
+    # a database blip right after a write must not turn every dial read into
+    # an exception. A truly cold process (nothing ever built) raises.
+    def build_or_last_good
+      build_and_publish
+    rescue StandardError => e
+      last = @last_good
+      raise if last.nil?
+
+      warn "[dials] snapshot rebuild failed; serving last-known-good (#{e.class}: #{e.message})"
+      last
+    end
+
+    # Build without any lock. Concurrent cold readers each build once (a
+    # bounded, once-per-boot herd against one small table); the last
+    # assignment wins with a valid snapshot either way.
+    def build_and_publish
+      generation = @state_mutex.synchronize { @generation }
+      built = Snapshot.new(**@store.state)
+
+      # Publish only if no bust! landed while we were reading the store —
+      # otherwise this snapshot predates a write and must not become the
+      # shared state. Check and assignment share the state mutex so a bust!
+      # cannot slip between them. The caller still gets the built snapshot.
+      # Either way the build becomes last-known-good: even a snapshot that
+      # predates a concurrent write is honest data — exactly what LKG serves.
+      @state_mutex.synchronize do
+        @last_good = built
+        if generation == @generation
+          @probed_at = monotonic_now
+          @snapshot = built
+        end
+      end
+
+      built
+    end
+
+    def refresh(current)
+      return current unless @build_mutex.try_lock
+
+      begin
+        build_and_publish
+      rescue StandardError => e
+        warn "[dials] snapshot rebuild failed; serving the cached snapshot (#{e.class}: #{e.message})"
+        current
+      ensure
+        @build_mutex.unlock
+      end
+    end
+
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/dials/change_record.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Dials
+  # One entry in the change log, in a store-independent shape. `scope` is nil
+  # for global changes; `old_value` is nil when no override existed before
+  # (the write introduced the override); `new_value` is nil for clears.
+  #
+  # The change log is append-only and doubles as the store's version counter,
+  # so every mutation the public API performs lands here by construction.
+  ChangeRecord = Data.define(:key, :scope, :action, :old_value, :new_value,
+                             :actor_type, :actor_id, :actor_label, :created_at) do
+    def global?
+      scope.nil?
+    end
+  end
+end

data/lib/dials/config.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Dials
+  # App-wide configuration, set once at boot via Dials.configure.
+  class Config
+    # Seconds between staleness probes (see Cache). 0 probes every read;
+    # nil never probes.
+    attr_reader :cache_ttl
+
+    # Builds the human label stored on every change-log entry.
+    attr_accessor :actor_label
+
+    # Fallback attribution for writes that pass no actor: — for apps without
+    # user identity (no User model, single-operator tools, scripts). A
+    # string/object, or a callable evaluated per write
+    # (`-> { ENV.fetch("USER", "console") }`). nil (the default) keeps
+    # actor: required on every write. This is a declared app-level fallback,
+    # not discovery — the gem still never guesses (no Current.user magic),
+    # and an explicit actor: always wins.
+    attr_accessor :default_actor
+
+    def initialize
+      @store = nil
+      @cache_ttl = 5.0
+      @actor_label = Actor::DEFAULT_LABEL
+      @default_actor = nil
+    end
+
+    def cache_ttl=(seconds)
+      @cache_ttl = seconds
+      Dials.cache.ttl = seconds
+    end
+
+    # Accepts a store instance, or the symbols :memory / :active_record.
+    def store=(store)
+      @store = case store
+               when :memory then Stores::Memory.new
+               when :active_record
+                 require "dials/active_record"
+                 Stores::ActiveRecordStore.new
+               else store
+               end
+      Dials.reset_cache!
+    end
+
+    def store
+      @store ||= Stores::Memory.new
+    end
+  end
+end

data/lib/dials/definition.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+module Dials
+  # A dial's declaration: its identity, its code default, and the rules a
+  # stored value must satisfy. Definitions live in code (the registry), never
+  # in the database — the database stores only values.
+  #
+  # type::   :boolean, :integer, :float, :string, or :json (any
+  #          JSON-serializable structure).
+  # constraints:: optional keywords on top of the type, in JSON Schema's
+  #          vocabulary — `minimum: 1, maximum: 10_000`, `enum: %w[low high]`,
+  #          `pattern: /.../`, `properties:`/`required:` for :json objects.
+  #          See Schema for the full keyword set per type.
+  # validate:: optional callable returning truthy when a value is storable —
+  #          the escape hatch for rules a schema cannot express. Unlike the
+  #          schema keywords it cannot be rendered or serialized; prefer the
+  #          keywords whenever they can say it.
+  # dimensions:: the axes the dial can vary along (per market, per
+  #          platform, ...). Declaring dimensions is the arming gate: a dial
+  #          with none is global-only by construction, and adding the
+  #          declaration belongs in the same change as the code that reads
+  #          the dimensioned value.
+  class Definition
+    TYPES = %i[boolean integer float string json].freeze
+
+    # Keys land in an indexed VARCHAR(100) that shares a composite unique
+    # index with the 255-byte canonical scope; the explicit cap keeps that
+    # index inside every supported database's budget (and generated method
+    # names sane).
+    MAX_KEY_LENGTH = 100
+
+    # Keys become method names (the bare reader, adjust_<key>, clear_<key>),
+    # so they must be plain callable identifiers — no spaces, hyphens,
+    # question marks, or leading digits.
+    KEY_FORMAT = /\A[a-zA-Z_][a-zA-Z0-9_]*\z/
+
+    attr_reader :key, :default, :type, :label, :unit, :description, :dimensions, :schema
+
+    def initialize(key, default:, type:, label: nil, unit: nil, description: nil,
+                   dimensions: nil, validate: nil, **constraints)
+      @key = key.to_sym
+      @type = type.to_sym
+      @label = label || @key.to_s.tr("_", " ").capitalize
+      @unit = unit
+      @description = description
+      @validate = validate
+
+      # Type first: Schema derives its allowed keywords from it.
+      raise InvalidDefinition, "#{@key}: unknown type #{@type.inspect} (use one of #{TYPES.join(', ')})" unless TYPES.include?(@type)
+
+      @schema = Schema.new(@key, @type, constraints)
+      @dimensions = build_dimensions(dimensions)
+      @default = default
+
+      # Validate BEFORE freezing: a default that fails validation (including
+      # a cyclic structure, which the JSON round-trip rejects) must raise
+      # InvalidDefinition without having frozen the caller's object — and
+      # Freeze.deep would recurse forever on a cycle.
+      validate_definition!
+
+      # Deep-frozen: resolution returns the default directly when nothing is
+      # stored, and a caller must not be able to mutate the code default for
+      # every other reader in the process.
+      @default = Freeze.deep(default)
+      freeze
+    end
+
+    def dimensions?
+      !dimensions.empty?
+    end
+
+    def dimension_names
+      dimensions.map(&:name)
+    end
+
+    # The declaration as a JSON Schema fragment — what an admin surface (or
+    # an agent reading the dial catalog) needs to render inputs and validate
+    # client-side. A `validate:` callable is not representable and is simply
+    # absent; the server-side check still runs on every write.
+    def to_json_schema
+      out = {}
+      out["type"] = json_schema_type if json_schema_type
+      out["title"] = label
+      out["description"] = description if description
+      out.merge!(schema.to_json_schema)
+      out["default"] = default
+      out
+    end
+
+    # Validation problems for a candidate stored value; [] when storable.
+    # `nil` is never storable — removing an override is a clear, so a stored
+    # nil could only ever be an accident.
+    def problems_for(value)
+      return ["cannot be nil (use clear to remove an override)"] if value.nil?
+
+      problem = type_problem(value)
+      return [problem] if problem
+
+      problems = schema.problems_for(value)
+      problems << "fails its validate check" if @validate && !@validate.call(value)
+      problems
+    end
+
+    def validate_value!(value)
+      problems = problems_for(value)
+      return value if problems.empty?
+
+      raise InvalidValue, "#{key}: value #{value.inspect} #{problems.join('; ')}"
+    end
+
+    private
+
+    def json_schema_type
+      case type
+      when :float then "number"
+      when :json then schema.object? ? "object" : nil
+      else type.to_s
+      end
+    end
+
+    def build_dimensions(declared)
+      case declared
+      when nil then [].freeze
+      when Array
+        declared.map { |name| Dimension.new(name) }.freeze
+      when Hash
+        declared.map { |name, spec| Dimension.new(name, enum: dimension_enum(name, spec)) }.freeze
+      else
+        raise InvalidDefinition, "#{key}: dimensions must be a Hash or Array, got #{declared.class}"
+      end
+    end
+
+    # Strict on shape: a typo like `{ "enum" => [...] }` (string key) or
+    # `{ market: "KE" }` must raise, not silently become an OPEN dimension
+    # that accepts any value.
+    def dimension_enum(name, spec)
+      case spec
+      when nil then nil
+      when Hash
+        unknown = spec.keys - [:enum]
+        unless unknown.empty?
+          raise InvalidDefinition,
+                "#{key}: dimension #{name} has unknown keys #{unknown.inspect} (use enum: with a symbol key)"
+        end
+        spec[:enum]
+      when Array then spec
+      else
+        return spec if spec.respond_to?(:call)
+
+        raise InvalidDefinition, "#{key}: dimension #{name} spec must be an Array, a callable, or { enum: ... }"
+      end
+    end
+
+    def validate_definition!
+      if key.length > MAX_KEY_LENGTH
+        raise InvalidDefinition, "#{key}: key exceeds #{MAX_KEY_LENGTH} characters"
+      end
+      unless KEY_FORMAT.match?(key.to_s)
+        raise InvalidDefinition,
+              "#{key.inspect}: key must be a plain identifier (letters, digits, underscores; " \
+              "it becomes the dial's method names)"
+      end
+
+      names = dimension_names
+      raise InvalidDefinition, "#{key}: duplicate dimension" unless names.uniq.length == names.length
+
+      # Generated adjust_/clear_ methods take scope as bare keywords next to
+      # actor: and expected_version:, so dimensions by those names could
+      # never be passed to them.
+      if names.include?(:actor)
+        raise InvalidDefinition, "#{key}: actor is a reserved dimension name (it means attribution on every write)"
+      end
+      if names.include?(:expected_version)
+        raise InvalidDefinition,
+              "#{key}: expected_version is a reserved dimension name (it means stale-write protection on every write)"
+      end
+
+      if @validate && !@validate.respond_to?(:call)
+        raise InvalidDefinition, "#{key}: validate must be a callable"
+      end
+
+      problems = problems_for(default)
+      return if problems.empty?
+
+      raise InvalidDefinition, "#{key}: default #{default.inspect} #{problems.join('; ')}"
+    end
+
+    def type_problem(value)
+      case type
+      when :boolean
+        # `false` is a first-class storable value. Anything presence-shaped
+        # that rejects false makes a kill switch impossible to turn off.
+        "must be true or false" unless [true, false].include?(value)
+      when :integer
+        "must be an integer" unless value.is_a?(Integer)
+      when :float
+        # Only Integer and Float survive a JSON round-trip as numbers —
+        # BigDecimal and Rational would come back from the store as strings.
+        # Non-finite floats (NaN, Infinity) are not representable in JSON.
+        if !(value.is_a?(Integer) || value.is_a?(Float))
+          "must be an Integer or Float"
+        elsif value.is_a?(Float) && !value.finite?
+          "must be finite"
+        end
+      when :string
+        "must be a string" unless value.is_a?(String)
+      when :json
+        json_problem(value)
+      end
+    end
+
+    # A :json value must survive the JSON round-trip UNCHANGED. Ruby's JSON
+    # generator happily stringifies symbols, Times, and arbitrary objects —
+    # which means a write would succeed and the very next read would return
+    # a different value. Requiring round-trip equality rejects those at
+    # write time (use string keys and JSON-native types).
+    def json_problem(value)
+      decoded = JSON.parse(JSON.generate(value))
+      return nil if decoded == value
+
+      "must round-trip through JSON unchanged (use string keys and JSON-native types)"
+    rescue StandardError
+      "must be JSON-serializable"
+    end
+  end
+end

data/lib/dials/dimension.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Dials
+  # One dimension of a dial: a name (:market, :platform, ...) and an
+  # optional set of allowed values — `enum`, the same word JSON Schema and
+  # the dial value constraints use. The enum may be given as an Array or as a
+  # callable (for values that are expensive to build or defined elsewhere,
+  # e.g. `-> { ISO3166::Country.codes }`); a callable is resolved once, on
+  # first use, under a lock (so a stateful or expensive callable cannot be
+  # raced into running twice by concurrent first reads).
+  #
+  # Dimension values are always compared as strings — "KE" and :KE name the
+  # same market. A dimension without an enum accepts any non-empty string up
+  # to MAX_VALUE_LENGTH characters (canonical scopes land in an indexed
+  # VARCHAR column; unbounded values would overflow or collide there).
+  class Dimension
+    MAX_VALUE_LENGTH = 128
+
+    attr_reader :name
+
+    def initialize(name, enum: nil)
+      @name = name.to_sym
+      @raw_enum = enum
+      @enum = nil
+      @mutex = Mutex.new
+      validate_shape!
+    end
+
+    # Allowed values as an Array of strings, or nil when the dimension is
+    # open (accepts any value).
+    def enum
+      return nil if @raw_enum.nil?
+
+      # Double-checked so the hot read path (every scope validation) skips
+      # the mutex once resolved.
+      resolved = @enum
+      return resolved if resolved
+
+      @mutex.synchronize do
+        @enum ||= Array(@raw_enum.respond_to?(:call) ? @raw_enum.call : @raw_enum)
+                  .map { |o| o.to_s.freeze }.freeze
+      end
+    end
+
+    def valid_value?(value)
+      value = value.to_s
+      return false if value.empty? || value.length > MAX_VALUE_LENGTH
+
+      enum.nil? || enum.include?(value)
+    end
+
+    private
+
+    def validate_shape!
+      return if @raw_enum.nil? || @raw_enum.is_a?(Array) || @raw_enum.respond_to?(:call)
+
+      raise InvalidDefinition, "dimension #{@name}: enum must be an Array or a callable, got #{@raw_enum.class}"
+    end
+  end
+end

data/lib/dials/errors.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Dials
+  # Base class for every error the gem raises deliberately.
+  class Error < StandardError; end
+
+  # Raised when a key is read or written that no `dial` declaration defined.
+  class UnknownDial < Error; end
+
+  # Raised when the same key is declared twice. A dial's declaration is its
+  # identity; a silent second declaration would make "which bounds apply?"
+  # ambiguous.
+  class DuplicateDial < Error; end
+
+  # Raised when a definition itself is malformed (bad type, bad dimensions
+  # shape, unknown schema keyword, default that fails its own schema).
+  # Definitions fail at boot, not at first read in production.
+  class InvalidDefinition < Error; end
+
+  # Raised when a candidate value is not storable for its dial: wrong type,
+  # schema violation, or nil (nil is never a value — use clear to remove an
+  # override).
+  class InvalidValue < Error; end
+
+  # Raised when a scope does not match the dial's declared dimensions:
+  # unknown dimension, missing dimension, or a value outside a dimension's
+  # declared enum. Also raised when a scope is given for a dial that
+  # declares no dimensions at all.
+  class InvalidScope < Error; end
+
+  # Raised when a write arrives without an actor. Every write is attributed;
+  # there is no anonymous mutation path through the public API.
+  class MissingActor < Error; end
+
+  # Raised when a write carries `expected_version:` and the override it
+  # targets has changed (or appeared, or vanished) since that version was
+  # read — the caller acted on a stale picture. The write is not applied and
+  # nothing is appended to the change log. Deliberately NOT retried by the
+  # stores (a retried compare-and-swap would recompute against the new
+  # version and succeed, silently defeating the mechanism): the surface
+  # should re-render from Dials.overview and let the operator decide again.
+  class StaleWrite < Error; end
+
+  # Raised when concurrent UNCONDITIONAL writes to the same override race
+  # each other faster than the store's bounded retries can absorb —
+  # essentially never at operator write rates. Safe to retry; carries no
+  # staleness meaning (that is StaleWrite).
+  class WriteConflict < Error; end
+end

data/lib/dials/freeze.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Dials
+  # Recursive freeze for JSON-shaped values (hashes, arrays, scalars). Used on
+  # snapshot contents and on declaration defaults, so no code path can hand a
+  # caller a mutable reference into shared dial state.
+  module Freeze
+    module_function
+
+    def deep(object)
+      case object
+      when Hash
+        object.each { |k, v| deep(k) && deep(v) }
+      when Array
+        object.each { |v| deep(v) }
+      end
+      object.freeze
+    end
+  end
+end

data/lib/dials/generated.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Dials
+  # Per-dial generated methods. Declaring `dial :base_fee, ...` defines
+  #
+  #   Dials.base_fee(**scope)                       # read  (Dials.get)
+  #   Dials.adjust_base_fee(value, actor:, **scope) # write (Dials.set)
+  #   Dials.clear_base_fee(actor:, **scope)         # clear (Dials.clear)
+  #
+  # The reader is the bare dial name — reading is what you do with a dial
+  # all day, so it pays no prefix tax; the writers carry their verbs. These
+  # are real methods defined at declaration time — never method_missing — so
+  # respond_to?, tab completion, and a grep for `base_fee` all work. A dial
+  # whose name collides with an existing Dials method (:store, :cache,
+  # :changes, ...) fails at boot rather than shadowing the API.
+  #
+  # Scope travels as bare keywords here (`market: "KE"`), which is why
+  # `actor` and `expected_version` are reserved dimension names: on
+  # adjust_/clear_ they must always mean attribution and stale-write
+  # protection, never scope. Definition enforces the reservation.
+  #
+  # The methods live on this module (which Dials extends) rather than on
+  # Dials directly so Registry#reset! can strip every generated method
+  # without touching the core API.
+  module Generated
+    class << self
+      # Define the three methods for a definition. Collisions are checked
+      # first — all three names, including against private methods, since a
+      # method on Dials itself would shadow anything defined here — so a
+      # raise leaves nothing half-installed.
+      def install!(definition)
+        key = definition.key
+        names = [key, :"adjust_#{key}", :"clear_#{key}"]
+
+        names.each do |name|
+          next unless Dials.respond_to?(name, true)
+
+          raise InvalidDefinition, "dial #{key} would define Dials.#{name}, which already exists"
+        end
+
+        # actor: defaults to nil rather than being a required keyword so that
+        # apps declaring config.default_actor can write without one; with no
+        # default configured, Actor.normalize still raises MissingActor.
+        define_method(names[0]) { |**scope| get(key, **scope) }
+        define_method(names[1]) do |value, actor: nil, expected_version: nil, **scope|
+          set(key, value, actor: actor, scope: scope, expected_version: expected_version)
+        end
+        define_method(names[2]) do |actor: nil, expected_version: nil, **scope|
+          clear(key, actor: actor, scope: scope, expected_version: expected_version)
+        end
+      end
+
+      def uninstall_all!
+        instance_methods(false).each { |name| remove_method(name) }
+      end
+    end
+  end
+
+  extend Generated
+end

data/lib/dials/overview.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Dials
+  # The complete stored state of every registered dial, read from ONE
+  # snapshot in one call — so an admin page renders a coherent picture.
+  #
+  #   overview.version         # the store's write-clock token (informational:
+  #                            # "rendered as of"; freshness displays, cheap
+  #                            # did-anything-change checks)
+  #   overview.dials           # [DialState, ...] in registry order
+  #
+  # Stale-write tokens are PER OVERRIDE — see DialState#global_version and
+  # #scoped_override_versions; feed those back as `expected_version:` on writes.
+  Overview = Data.define(:version, :dials)
+
+  # One dial's declaration plus its stored overrides at the snapshot moment.
+  #
+  # `global_override?` is explicit — a boolean dial overridden to `false`
+  # must never be confusable with "no override" (`global_value` alone could
+  # not distinguish them; it is nil when no global override exists).
+  #
+  # `global_version` and `scoped_override_versions` are the per-override
+  # stale-write tokens: echo the one for the override you are writing as
+  # `expected_version:`. Cleared overrides keep a TOMBSTONE token (the
+  # stream's clear stamp) — so `scoped_override_versions` can carry entries
+  # for scopes with no value in `scoped_overrides`, and `global_version` is
+  # Dials::ABSENT_VERSION only when the global was never written at all.
+  # For an override with no token listed anywhere, pass
+  # Dials::ABSENT_VERSION to assert it has never been written.
+  DialState = Data.define(:definition, :global_override, :global_value, :global_version,
+                          :scoped_overrides, :scoped_override_versions) do
+    def key
+      definition.key
+    end
+
+    def global_override?
+      global_override
+    end
+
+    # The declaration as a JSON Schema fragment (see Definition#to_json_schema).
+    def json_schema
+      definition.to_json_schema
+    end
+  end
+end