dials 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd4dd1c05a2c416e08b2c22d7e338119a402f9b5c6837060525fdd2f3b01f42e
-  data.tar.gz: 4ad1737c0a22254df563055ebdab250087a6490e05c116944b56207d96950627
+  metadata.gz: b86f0661acabf1181381d1b427daa25ab6cfa3a165bfa0df5cc8aef73bb0f3e6
+  data.tar.gz: fe4aeaa5c53ec38b2bc23232ef780ebd535992dcc806664e50a064aac8c86356
 SHA512:
-  metadata.gz: b350111d9f196d576eea8ca2a077bacfc1913e3d1698492863760ce74d8612f593ec2a94cf4e757b7e1b3ac04e9dd48ea912ac044f2c3d98441d3e076a8a571c
-  data.tar.gz: 956c518db63ae813c313b8c5cf1d6b1b8adc17b5f5cd3d15c92fc35943a179ca841a5a2969c32d1575f95515b037442fb8a8f665e4de30c8f5de0454f7147db9
+  metadata.gz: 518a76d9607ba4c79a867bc4efa30436ed35a83eae76243a46020b9ed0033f2edf46eafbdd6d3e81b0194d8e23e11592fba9b02f3452ba3138bc06be6ad86072
+  data.tar.gz: 567beee01c929e743ee9d1a8257e4c8e8cdd071686cf74d269f37513f89f83a42554ec9aae44d6fb62c229f93a632d967b46cd1cfc0520794a319895b7e2aed7

data/CHANGELOG.md

@@ -1,5 +1,62 @@
 # Changelog
 
+## [0.4.0] - 2026-09-09
+
+- **Namespaces.** A subsystem can own its dials:
+  `Dials.namespace(:shipping) { |config| config.store = :active_record }`
+  returns a dials instance of its own — its own registry, config, store,
+  table (`shipping_dials`), cache, change log, generated readers and test
+  overrides. A key is unique inside its namespace, so two namespaces may
+  declare the same one, and a dial resolves inside its namespace only.
+  `Dials.namespaces` lists every namespace (root first) for an admin surface
+  that groups dials by subsystem, and `Dials.default` names the root.
+  Unset options (`cache_ttl`, `actor_label`, `default_actor`) inherit the
+  root's config; `store` inherits by kind, so an inheriting namespace still
+  owns its table (a store *object* is not inheritable — sharing one would
+  put two namespaces in one key space). `config.table_name` renames a namespace's table;
+  `config.table_name_prefix` still names the root's.
+- **Newly reserved dial keys.** A dial's reader must not shadow a method on
+  its namespace, and the namespace object carries methods the `Dials` module
+  did not: `label`, `with_overrides`, `default_label`, `root?`, `storage`,
+  `txn_write_key`, `generated_module`, `install_generated!`,
+  `uninstall_generated!`, `apply_cache_ttl`, `apply_store`,
+  `inherit_cache_ttl`, `inherit_store`, `adopt`, `forget_children!` and
+  `reset_config!` — plus the new module methods `default`, `namespace`,
+  `namespaces`, `reload_all!` and `reset_namespaces!`. A dial declared under
+  one of those names now raises `InvalidDefinition` at boot instead of at no
+  point.
+- A namespace name must be segments of lowercase letters and digits, each
+  starting with a letter, joined by single underscores (`InvalidNamespace`
+  otherwise): it becomes a table name and a model class name, and that rule
+  keeps both one-to-one with the namespace. (`tier_2` is refused because it
+  and `tier2` would derive the same model class, and the second namespace
+  would silently repoint the first one's table.)
+- **`Dials::InvalidTableName`.** A table name must be lowercase letters,
+  digits and underscores, at most 63 characters — a table the namespace owns
+  outright, not a schema-qualified or case-sensitive reference, and
+  PostgreSQL truncates identifiers past 63 bytes — and no two namespaces may
+  resolve to one table. Both are checked at boot, on `config.table_name`,
+  `config.table_name_prefix`, and the name a namespace derives from its own.
+- The ActiveRecord store quotes the table name in the one query it writes by
+  hand, so a table named for a reserved word (`order`) loads state instead of
+  raising a SQL syntax error on the first read.
+- Configuration is boot-time only: declare namespaces and configure `Dials`
+  during boot. Reconfiguration concurrent with live traffic is unsupported.
+- **`Dials.reload_all!`** reloads every namespace, and
+  **`Dials.reset_namespaces!`** discards all but the root — for test suites.
+- The `Dials` module is now the default namespace: `Dials.define`,
+  `Dials.configure`, the generated readers, `Dials::Testing.with_overrides`,
+  `Dials.reload!` and `Dials::ActiveRecord::Entry` behave exactly as before.
+  Internals moved with the refactor, none of them documented API:
+  `Dials::Testing::THREAD_KEY` and `Dials::Testing.override_for` are gone
+  (each namespace keeps its own thread-local pins); `Dials::CACHE_LOCK` and
+  `Stores::ActiveRecordStore::Entry` are gone (the store now takes
+  `model:`); `Dials::ActiveRecord::Entry` subclasses a new abstract
+  `Dials::ActiveRecord::Record`, and its `DEFAULT_TABLE_NAME` moved to the
+  new `Dials::Storage`, which owns a namespace's store kind, table and
+  model; `Dials::Actor.normalize`, `Registry.new` and `Config.new` now take
+  the namespace (or its config and storage) they act for.
+
 ## [0.3.0] - 2026-09-07
 
 - **`Dials.global(key)`.** Read a dial's Global layer by key: the stored

data/README.md

@@ -51,6 +51,21 @@ clearing every override returns you to exactly what the code says. Reads
 come from a per-process cache with a throttled staleness probe, so a dial
 read costs a hash lookup, not a query.
 
+A subsystem that owns its operator settings declares a **namespace**: a
+dials instance with its own registry, table, cache and change log.
+
+```ruby
+Shipping = Dials.namespace(:shipping, label: "Shipping") do |config|
+  config.store = :active_record   # table: "shipping_dials"
+end
+
+Shipping.define { dial :max_parcel_kg, default: 20, type: :integer, minimum: 1 }
+Shipping.max_parcel_kg            # => 20
+```
+
+`Dials` is the default namespace, so an app that never mentions namespaces
+has exactly one.
+
 ## Installation
 
 ```bash

data/lib/dials/active_record/models.rb

@@ -2,17 +2,17 @@
 
 module Dials
   module ActiveRecord
-    # The one gem-owned table. Values are stored as JSON text (not jsonb)
-    # so the schema is portable across PostgreSQL, MySQL, and SQLite; nothing
+    # One namespace's table. Values are stored as JSON text (not jsonb) so
+    # the schema is portable across PostgreSQL, MySQL, and SQLite; nothing
     # ever queries inside a value or a scope — reads go through the
     # in-process cache, so the database is durable storage, not a query
     # surface.
     #
-    # This model is internal plumbing for Stores::ActiveRecordStore.
-    # Application code reads and writes through the Dials facade, which is
-    # where validation, attribution, and cache busting live. Writing to it
-    # directly bypasses all of that.
-
+    # These models are internal plumbing for Stores::ActiveRecordStore.
+    # Application code reads and writes through a namespace (the Dials
+    # facade is the default one), which is where validation, attribution,
+    # and cache busting live. Writing to them directly bypasses all of that.
+    #
     # One row per WRITE — the table is append-only, so the change log IS the
     # state. The newest row per (key, scope) stream is the current override:
     # action "set" carries the value; action "clear" says the override is
@@ -33,12 +33,8 @@ module Dials
     # collation additionally treats scopes differing only by case ("KE" vs
     # "ke") as one stream — don't declare dimension enums that differ only
     # by case, or give the table a binary collation.
-    class Entry < ::ActiveRecord::Base
-      # Prefixable via Dials.configure { |c| c.table_name_prefix = "zar_" }
-      # for apps where "dials" collides with an existing table (see
-      # Config#table_name_prefix).
-      DEFAULT_TABLE_NAME = "dials"
-      self.table_name = DEFAULT_TABLE_NAME
+    class Record < ::ActiveRecord::Base
+      self.abstract_class = true
 
       validates :key, :scope, :seq, presence: true
       validates :action, presence: true, inclusion: { in: %w[set clear] }
@@ -51,5 +47,19 @@ module Dials
         persisted?
       end
     end
+
+    # The default namespace's table; renamed by Config#table_name_prefix.
+    class Entry < Record
+      self.table_name = Dials::Storage::DEFAULT_TABLE_NAME
+    end
+
+    # The model for a non-default namespace, named after it so a validation
+    # error or a query log says which subsystem's table it is.
+    def self.model(namespace_name)
+      const = "#{namespace_name.to_s.split('_').map(&:capitalize).join}Entry"
+      return const_get(const, false) if const_defined?(const, false)
+
+      const_set(const, Class.new(Record))
+    end
   end
 end

data/lib/dials/active_record/store.rb

@@ -2,12 +2,12 @@
 
 module Dials
   module Stores
-    # The production store: ONE ActiveRecord-backed, append-only table (see
-    # Dials::ActiveRecord::Entry). Every write INSERTs a row; the newest row
-    # per (key, scope) stream is the current override, and the same rows are
-    # the attributed history and the cache's version counter. The global
-    # override is the stream at Scope::GLOBAL (the canonical empty scope).
-    # Implements the same interface as Stores::Memory.
+    # The production store: ONE ActiveRecord-backed, append-only table per
+    # namespace (see Dials::ActiveRecord::Record). Every write INSERTs a row;
+    # the newest row per (key, scope) stream is the current override, and the
+    # same rows are the attributed history and the cache's version counter.
+    # The global override is the stream at Scope::GLOBAL (the canonical empty
+    # scope). Implements the same interface as Stores::Memory.
     #
     # Concurrency control is the stream sequence: each row claims its
     # stream's next `seq` under UNIQUE(key, scope, seq), so of two concurrent
@@ -18,8 +18,6 @@ module Dials
     # only grows, so a stale-write token (the live row's seq) can never be
     # revisited by a later delete-and-recreate.
     class ActiveRecordStore
-      Entry = Dials::ActiveRecord::Entry
-
       # Sentinel for "this row could not be decoded; skip it".
       SKIP = Object.new
 
@@ -39,6 +37,13 @@ module Dials
       # Operator write rates make even the second attempt rare.
       WRITE_ATTEMPTS = 3
 
+      # The namespace's model; its table is the namespace's table.
+      def initialize(model: Dials::ActiveRecord::Entry)
+        @model = model
+      end
+
+      attr_reader :model
+
       def state
         # Version first: if a write lands between these reads, the snapshot
         # carries an older version than its data, and the next probe sees the
@@ -64,11 +69,11 @@ module Dials
           when "set"
             nil # fall through to the value path
           else
-            quarantine("dials(#{row.key}, #{row.scope})", "unknown action #{row.action.inspect}")
+            quarantine("#{@model.table_name}(#{row.key}, #{row.scope})", "unknown action #{row.action.inspect}")
             next
           end
 
-          value = decode_row(row.value, "dials(#{row.key}, #{row.scope})")
+          value = decode_row(row.value, "#{@model.table_name}(#{row.key}, #{row.scope})")
           next if value.equal?(SKIP)
 
           if row.scope == Scope::GLOBAL
@@ -93,7 +98,7 @@ module Dials
       # unrelated write. Count catches it (N → N+1). Both aggregates come
       # from ONE statement so they describe one committed state, never two.
       def version
-        count, max = Entry.pick(Arel.sql("COUNT(*)"), Arel.sql("COALESCE(MAX(id), 0)"))
+        count, max = @model.pick(Arel.sql("COUNT(*)"), Arel.sql("COALESCE(MAX(id), 0)"))
         [count, max]
       end
 
@@ -111,7 +116,7 @@ module Dials
       # write). The facade uses this to keep uncommitted dial state out of
       # the shared cache.
       def transaction_open?
-        pool = Entry.connection_pool
+        pool = @model.connection_pool
         return false unless pool.active_connection?
 
         connection = pool.respond_to?(:lease_connection) ? pool.lease_connection : pool.connection
@@ -166,7 +171,7 @@ module Dials
       end
 
       def changes(key: nil, limit: 50)
-        relation = Entry.order(id: :desc).limit(limit)
+        relation = @model.order(id: :desc).limit(limit)
         relation = relation.where(key: key.to_s) if key
         rows = relation.to_a
         previous = predecessors_of(rows)
@@ -176,7 +181,7 @@ module Dials
           # action or a noncanonical scope is a row written around the gem,
           # and the two views must agree on which rows are valid.
           unless %w[set clear].include?(row.action)
-            next quarantine("dials(id #{row.id})", "unknown action #{row.action.inspect}")
+            next quarantine("#{@model.table_name}(id #{row.id})", "unknown action #{row.action.inspect}")
           end
 
           parsed_scope =
@@ -203,7 +208,7 @@ module Dials
         rescue StandardError => e
           # Same quarantine rule as state: one corrupt row (written around
           # the gem) must not take down the whole history listing.
-          quarantine("dials(id #{row.id})", "row does not decode (#{e.class})")
+          quarantine("#{@model.table_name}(id #{row.id})", "row does not decode (#{e.class})")
           nil
         end
       end
@@ -212,7 +217,7 @@ module Dials
 
       # The newest row of one (key, scope) stream, live or not.
       def newest(key, canonical_scope)
-        Entry.where(key: key.to_s, scope: canonical_scope).order(seq: :desc).first
+        @model.where(key: key.to_s, scope: canonical_scope).order(seq: :desc).first
       end
 
       def live?(row)
@@ -221,20 +226,24 @@ module Dials
 
       # Every stream's newest row, in one query. The correlated NOT EXISTS
       # is portable across PostgreSQL, MySQL, and SQLite (no window
-      # functions) and walks the (key, scope, seq) index.
+      # functions) and walks the (key, scope, seq) index. The table name is
+      # quoted by the adapter: this is the one place the gem writes SQL by
+      # hand, so a table named for a reserved word must not become a syntax
+      # error the first time a namespace loads its state.
       def newest_rows
-        Entry.where(<<~SQL.squish)
+        table = @model.quoted_table_name
+        @model.where(<<~SQL.squish)
           NOT EXISTS (
-            SELECT 1 FROM #{Entry.table_name} newer
-            WHERE newer.key = #{Entry.table_name}.key
-              AND newer.scope = #{Entry.table_name}.scope
-              AND newer.seq > #{Entry.table_name}.seq
+            SELECT 1 FROM #{table} newer
+            WHERE newer.key = #{table}.key
+              AND newer.scope = #{table}.scope
+              AND newer.seq > #{table}.seq
           )
         SQL
       end
 
       def append(key, canonical_scope, seq, action, encoded_value, actor)
-        Entry.create!(
+        @model.create!(
           key: key.to_s,
           scope: canonical_scope,
           seq: seq,
@@ -255,7 +264,7 @@ module Dials
         return {} if wanted.empty?
 
         wanted.group_by { |k, s, _| [k, s] }
-              .map { |(k, s), triples| Entry.where(key: k, scope: s, seq: triples.map(&:last)) }
+              .map { |(k, s), triples| @model.where(key: k, scope: s, seq: triples.map(&:last)) }
               .reduce(:or)
               .index_by { |r| [r.key, r.scope, r.seq] }
       end
@@ -291,7 +300,7 @@ module Dials
       def write(expected_version, &)
         attempts = 0
         begin
-          Entry.transaction(&)
+          @model.transaction(&)
         rescue ::ActiveRecord::RecordNotUnique
           if expected_version
             raise StaleWrite,
@@ -344,15 +353,15 @@ module Dials
       def valid_scope_string?(key, scope)
         parsed = JSON.parse(scope)
         unless parsed.is_a?(Hash) && !parsed.empty?
-          quarantine("dials(#{key})", "scope #{scope.inspect} is not a non-empty JSON object")
+          quarantine("#{@model.table_name}(#{key})", "scope #{scope.inspect} is not a non-empty JSON object")
           return false
         end
         return true if Scope.canonical(Scope.parse(scope)) == scope
 
-        quarantine("dials(#{key})", "scope #{scope.inspect} is not canonical")
+        quarantine("#{@model.table_name}(#{key})", "scope #{scope.inspect} is not canonical")
         false
       rescue JSON::ParserError, InvalidScope
-        quarantine("dials(#{key})", "scope #{scope.inspect} is not a valid canonical scope")
+        quarantine("#{@model.table_name}(#{key})", "scope #{scope.inspect} is not a valid canonical scope")
         false
       end
 

data/lib/dials/actor.rb

@@ -13,8 +13,8 @@ module Dials
   module Actor
     module_function
 
-    def normalize(actor)
-      actor = default_actor if actor.nil?
+    def normalize(actor, config)
+      actor = default_actor(config) if actor.nil?
       if actor.nil?
         raise MissingActor, "every write requires an actor: (who is making this change?) — " \
                             "pass actor:, or set config.default_actor for apps without user identity"
@@ -23,14 +23,14 @@ module Dials
       {
         actor_type: actor_type(actor),
         actor_id: actor_id(actor),
-        actor_label: Dials.config.actor_label.call(actor).to_s
+        actor_label: config.actor_label.call(actor).to_s
       }
     end
 
     # The configured fallback; a callable is evaluated per write (so
     # `-> { ENV.fetch("USER", "console") }` names whoever runs the console).
-    def default_actor
-      configured = Dials.config.default_actor
+    def default_actor(config)
+      configured = config.default_actor
       configured.respond_to?(:call) ? configured.call : configured
     end
 

data/lib/dials/config.rb

@@ -1,14 +1,32 @@
 # frozen_string_literal: true
 
 module Dials
-  # App-wide configuration, set once at boot via Dials.configure.
+  # One namespace's options, set once at boot via Dials.configure (the root)
+  # or the block Dials.namespace takes.
+  #
+  # An option a namespace does not set reads through to the root's: an engine
+  # that configures nothing but its store still honours the app's cache_ttl,
+  # actor_label, and default_actor. Where the namespace's values live is the
+  # one option with rules of its own — see Storage.
   class Config
+    def initialize(namespace, storage, parent: nil)
+      @namespace = namespace
+      @storage = storage
+      @parent = parent
+      @explicit = {}
+      @label = nil
+    end
+
     # Seconds between staleness probes (see Cache). 0 probes every read;
     # nil never probes.
-    attr_reader :cache_ttl
+    def cache_ttl
+      inherited_option(:cache_ttl) { 5.0 }
+    end
 
     # Builds the human label stored on every change-log entry.
-    attr_accessor :actor_label
+    def actor_label
+      inherited_option(:actor_label) { Actor::DEFAULT_LABEL }
+    end
 
     # Fallback attribution for writes that pass no actor: — for apps without
     # user identity (no User model, single-operator tools, scripts). A
@@ -17,60 +35,87 @@ module Dials
     # 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 default_actor
+      inherited_option(:default_actor) { nil }
+    end
 
-    # Prefix for the gem-owned table, mirroring Rails' table_name_prefix
-    # convention: used verbatim, so include the trailing underscore
-    # ("ops_" makes the table "ops_dials"). nil (the default) keeps "dials".
-    # Set it when "dials" collides with an existing table, and pass the same
-    # prefix to the install generator (--table-name-prefix) so the migration
-    # matches.
-    attr_reader :table_name_prefix
+    # How this namespace is named on an admin surface. Never inherited —
+    # every namespace needs a name of its own.
+    def label
+      @label || @namespace.default_label
+    end
+
+    attr_writer :label
+
+    def cache_ttl=(seconds)
+      @explicit[:cache_ttl] = seconds
+      @namespace.apply_cache_ttl
+    end
 
-    def initialize
-      @store = nil
-      @cache_ttl = 5.0
-      @actor_label = Actor::DEFAULT_LABEL
-      @default_actor = nil
-      @table_name_prefix = nil
+    def actor_label=(builder)
+      @explicit[:actor_label] = builder
     end
 
-    # Order-independent with store=: whichever runs second applies the name.
-    def table_name_prefix=(prefix)
-      @table_name_prefix = prefix
-      apply_table_name
-      Dials.reset_cache!
+    def default_actor=(actor)
+      @explicit[:default_actor] = actor
     end
 
-    def cache_ttl=(seconds)
-      @cache_ttl = seconds
-      Dials.cache.ttl = seconds
+    # True when this config declares the option itself rather than reading
+    # the root's.
+    def explicitly_set?(option)
+      @explicit.key?(option)
     end
 
+    # -- storage -------------------------------------------------------------
+
     # 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"
-                 apply_table_name
-                 Stores::ActiveRecordStore.new
-               else store
-               end
-      Dials.reset_cache!
+      @storage.kind = store
+      @namespace.apply_store
     end
 
     def store
-      @store ||= Stores::Memory.new
+      @storage.store
+    end
+
+    # The table this namespace's ActiveRecord store owns; a namespace never
+    # shares one.
+    def table_name
+      @storage.table_name
+    end
+
+    def table_name=(name)
+      @storage.table_name = name
+      @namespace.reset_cache!
+    end
+
+    # Prefix for the ROOT's table, mirroring Rails' table_name_prefix
+    # convention: used verbatim, so include the trailing underscore
+    # ("ops_" makes the table "ops_dials"). nil (the default) keeps "dials".
+    # Set it when "dials" collides with an existing table, and pass the same
+    # prefix to the install generator (--table-name-prefix) so the migration
+    # matches. A non-root namespace names its table with table_name instead.
+    def table_name_prefix
+      @storage.table_name_prefix
+    end
+
+    def table_name_prefix=(prefix)
+      unless @namespace.root?
+        raise Error, "table_name_prefix names the root's table; namespace #{@namespace.name} " \
+                     "names its own with config.table_name"
+      end
+
+      @storage.table_name_prefix = prefix
+      @namespace.reset_cache!
     end
 
     private
 
-    def apply_table_name
-      return unless defined?(Dials::ActiveRecord::Entry)
+    def inherited_option(name)
+      return @explicit[name] if @explicit.key?(name)
+      return @parent.public_send(name) if @parent
 
-      Dials::ActiveRecord::Entry.table_name =
-        "#{@table_name_prefix}#{Dials::ActiveRecord::Entry::DEFAULT_TABLE_NAME}"
+      yield
     end
   end
 end

data/lib/dials/errors.rb

@@ -46,4 +46,22 @@ module Dials
   # essentially never at operator write rates. Safe to retry; carries no
   # staleness meaning (that is StaleWrite).
   class WriteConflict < Error; end
+
+  # Raised when a namespace is declared twice. A namespace owns a registry
+  # and a table; a silent second declaration would make "whose dials are
+  # these?" ambiguous.
+  class DuplicateNamespace < Error; end
+
+  # Raised when a namespace is fetched that was never declared.
+  class UnknownNamespace < Error; end
+
+  # Raised when a namespace name's segments are not lowercase letters and
+  # digits each starting with a letter (see Namespace::NAME_FORMAT).
+  class InvalidNamespace < Error; end
+
+  # Raised when a namespace's table name is not a plain identifier, is
+  # longer than a database will keep whole, or is already another
+  # namespace's table. A namespace owns its table; sharing one would
+  # interleave two subsystems' rows with nothing to tell them apart.
+  class InvalidTableName < Error; end
 end

data/lib/dials/generated.rb

@@ -11,50 +11,53 @@ module Dials
   # 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.
+  # whose name collides with an existing method on its namespace (: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.
+  # The methods live in a module the namespace extends (never on the
+  # namespace directly) so Registry#reset! can strip every generated method
+  # without touching the core API. Each namespace owns its own module, so
+  # two namespaces can declare the same key.
   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)
+      # Define the three methods for a definition in `into`, a module the
+      # namespace extends. Collisions are checked first — all three names
+      # against every owner, including private methods, since a method on
+      # the owner itself would shadow anything defined here — so a raise
+      # leaves nothing half-installed. `owners` maps the name a user would
+      # type ("Dials") to the object that answers it.
+      def install!(definition, into:, owners:)
         key = definition.key
         names = [key, :"adjust_#{key}", :"clear_#{key}"]
 
         names.each do |name|
-          next unless Dials.respond_to?(name, true)
+          owners.each do |label, owner|
+            next unless owner.respond_to?(name, true)
 
-          raise InvalidDefinition, "dial #{key} would define Dials.#{name}, which already exists"
+            raise InvalidDefinition, "dial #{key} would define #{label}.#{name}, which already exists"
+          end
         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|
+        into.define_method(names[0]) { |**scope| get(key, **scope) }
+        into.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|
+        into.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) }
+      def uninstall_all!(from:)
+        from.instance_methods(false).each { |name| from.remove_method(name) }
       end
     end
   end
-
-  extend Generated
 end