dials 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 616a841d2067499823a017f9b83bf151c2a7df9128ac044154c37a473a275770
+  data.tar.gz: 6d32168d1c2c5bf45742db53b95d1eace0a145ec046e911a21eba1231660812b
+SHA512:
+  metadata.gz: 149a10e661a7fc3ca2504d06f33e5c69294c9445373542d66970bb340e6313968170486c1d2184a927b7c08d223bbd20864474b4811c18272adb5b8cbe2459f4
+  data.tar.gz: 74f42bde26e31ed6c2f8ee2f0591c100d921d4282072718c5650237e59027a0981d7c3e454436047f20b6536fb241772c0ec37d93c02c1b52608fe4a73b53a87

data/CHANGELOG.md

@@ -0,0 +1,76 @@
+# Changelog
+
+## [0.1.0] - 2026-09-02
+
+Initial release.
+
+- **Code-declared registry.** `Dials.define` with
+  `dial :checkout_fee_bps, default: 250, type: :integer, minimum: 1, maximum: 10_000`
+  — types (boolean, integer, float, string, json) plus labels, units, and
+  descriptions. Constraints speak JSON Schema directly (snake_cased keywords:
+  `minimum:`/`maximum:`/`exclusive_minimum:`/`exclusive_maximum:`/
+  `multiple_of:` for numbers, `min_length:`/`max_length:`/`pattern:` for
+  strings, `enum:` for any type, `properties:`/`required:` for `:json`
+  objects), with `validate:` (a callable) as the escape hatch for rules a
+  schema cannot express. `Definition#to_json_schema` emits each declaration
+  as a real JSON Schema fragment for admin surfaces and agents.
+- **Generated per-dial methods are the primary API.** Declaring a dial
+  defines real methods at declaration time: readers are the bare dial name
+  (`Dials.checkout_fee_bps(market: "KE")`), writers keep their verbs
+  (`Dials.adjust_checkout_fee_bps(value, actor:, **scope)` and
+  `Dials.clear_checkout_fee_bps(actor:, **scope)`), so a bare name is always
+  a read. The key-taking primitives (`Dials.get` / `Dials.set` /
+  `Dials.clear`) remain public as the dynamic-access layer for code that
+  receives the key at runtime. Name collisions with existing `Dials` methods
+  raise `InvalidDefinition`; `actor` and `expected_version` are reserved
+  dimension names.
+- **Dimensions and scoped overrides.** `dimensions:` declares a dial's axes
+  (closed `enum:` option lists or open, length-capped values). The database
+  stores overrides only; resolution is scoped override → global override →
+  code default, with a most-specific-wins matcher. Clearing an override
+  returns resolution to the layer below.
+- **The log is the state — one append-only table.** Every write INSERTs
+  exactly one row into a single `dials` table; the newest row per
+  (key, scope) stream is the current override (`set` carries a value,
+  `clear` ends it). Current state, attributed history (`Dials.changes`),
+  and the cache's version counter are the same rows, so history can never
+  disagree with state, and `changes` derives old values from the previous
+  row instead of trusting a stored copy.
+- **Stale-write protection (compare-and-swap).** Every write path accepts
+  `expected_version:` — an opaque per-override token from `Dials.overview`
+  or a previous CAS write's return value. Tokens are stream `seq` numbers
+  claimed under `UNIQUE(key, scope, seq)`, so of two concurrent claims the
+  database rejects one: the comparison is atomic with the write, holds
+  against every concurrent writer without anyone opting in, and unrelated
+  overrides can never false-conflict. A mismatch raises `Dials::StaleWrite`
+  with the write unapplied and nothing logged, and is deliberately never
+  auto-retried. Cleared overrides keep a tombstone token, so
+  `Dials::ABSENT_VERSION` strictly means "never written" and absent
+  assertions cannot be fooled by set-then-clear activity (no ABA).
+- **Attributed writes.** Writers require `actor:` and every write lands in
+  the append-only log. Apps without a user identity can declare
+  `config.default_actor` (a value, or a callable evaluated per write) once;
+  an explicit `actor:` always wins.
+- **Enumeration API.** `Dials.overview` returns every registered dial's full
+  state — definition (with its JSON Schema), global override, scoped
+  overrides, and CAS tokens — from one snapshot stamped with a single
+  version token; `Dials.scoped_overrides(key)` returns one dial's stored
+  overrides keyed by parsed scope. Both read through the same path as the
+  generated readers and return frozen structures.
+- **Per-process snapshot cache** with a throttled staleness probe
+  (`cache_ttl`), single-flight refreshes, and a last-known-good snapshot
+  served (with a warning) when the store blips. Writes inside an application
+  database transaction never leak uncommitted state into the shared cache —
+  the writing thread reads its own view until commit, and the cache busts
+  again on commit.
+- **Hardened by adversarial review.** Corrupt rows written around the gem
+  are quarantined with a warning instead of failing reads; values
+  JSON-round-trip identically in both stores (no retained caller references,
+  no store-dependent shapes); declaration defaults are deep-frozen; write
+  retries cover deadlocks and serialization failures but never run inside an
+  outer application transaction.
+- **Stores:** in-memory (default, zero dependencies) and ActiveRecord
+  (Rails/AR >= 7.2, portable JSON-text columns), with a
+  `rails g dials:install` generator (migration + initializer).
+- **`Dials::Testing.with_overrides`** for client test suites.
+- **Zero runtime dependencies.**

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 ZAR Labs Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,78 @@
+# dials
+
+Operator-adjustable values with per-scope overrides, attribution, and
+caching.
+
+You wrote a constant. Then you needed to change it without a deploy, so you
+built an admin surface. Then you needed a different value per market. Dials is
+that whole arc as one small library:
+
+```ruby
+# config/initializers/dials.rb
+Dials.define do
+  dial :merchant_fee_bps, default: 100,
+       type: :integer, minimum: 1, maximum: 10_000, unit: "bps",
+       dimensions: { market: { enum: %w[KE NG BD] } }
+
+  dial :signups_enabled, default: true, type: :boolean,
+       description: "Global kill switch for new signups."
+end
+```
+
+The constraint keywords are **JSON Schema**, snake_cased (`minimum:`,
+`maximum:`, `enum:`, `pattern:`, `properties:`/`required:` for `:json`
+values) — if you've written an OpenAPI spec or a JSON Schema, you already
+know this vocabulary, and `definition.to_json_schema` hands the real
+fragment to admin UIs and client-side validators.
+
+Each declaration generates the dial's methods:
+
+```ruby
+Dials.merchant_fee_bps(market: "KE")   # => 100 (the code default)
+
+Dials.adjust_merchant_fee_bps(90, actor: current_admin, market: "KE")
+Dials.merchant_fee_bps(market: "KE")   # => 90
+Dials.merchant_fee_bps(market: "NG")   # => 100
+
+Dials.clear_merchant_fee_bps(actor: current_admin, market: "KE")
+Dials.merchant_fee_bps(market: "KE")   # => 100 again
+
+Dials.changes(key: :merchant_fee_bps)      # attributed, append-only history
+```
+
+The key-taking primitives (`Dials.get`, `Dials.set`, `Dials.clear`) stay
+public underneath, for code that receives the key at runtime — an admin
+surface iterating the registry, a console one-liner.
+
+Resolution is always **scoped override → global override → code default**.
+The database is one append-only table storing only overrides — state,
+attributed history, and the cache's version counter are the same rows, and
+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.
+
+## Installation
+
+```bash
+bundle add dials
+bin/rails generate dials:install   # migration (3 tables) + initializer
+bin/rails db:migrate
+```
+
+Full documentation: <https://zarpay.github.io/dials/> — including the design
+decisions, the caching model, retrofit guides for existing apps, and when a
+value should *not* be a dial.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake       # minitest + rubocop
+```
+
+The sibling `demo/` package in this repository is a Rails app whose test
+suite exercises the entire public API against a real database.
+
+## License
+
+MIT.

data/lib/dials/active_record/models.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+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
+    # 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.
+
+    # 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
+    # gone (resolution falls to the next layer). A global override is simply
+    # the stream at the empty scope, stored under the canonical encoding
+    # "{}". History cannot disagree with state because they are the same
+    # rows, and an override's previous value is literally its previous row.
+    #
+    # `seq` numbers each stream's rows 1, 2, 3...; UNIQUE(key, scope, seq)
+    # is what makes writes atomic without locks or guarded updates: every
+    # writer claims the stream's next slot, and of two concurrent claims the
+    # database rejects one. Rows are immutable and seq only grows, so a
+    # stale-write token (the live row's seq) can never be revisited.
+    #
+    # NOTE: uniqueness is textual, under the column's collation. Scope
+    # strings are canonical (sorted keys, string values) so gem writes can
+    # never collide cosmetically; on MySQL, a case-insensitive default
+    # 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
+      self.table_name = "dials"
+
+      validates :key, :scope, :seq, presence: true
+      validates :action, presence: true, inclusion: { in: %w[set clear] }
+      validates :value, presence: true, if: -> { action == "set" }
+
+      # App-level append-only: a persisted row refuses update and destroy
+      # through ActiveRecord. (Raw SQL and delete_all can still bypass this —
+      # rows are state, history, AND the cache's version counter, so don't.)
+      def readonly?
+        persisted?
+      end
+    end
+  end
+end

data/lib/dials/active_record/store.rb

@@ -0,0 +1,365 @@
+# frozen_string_literal: true
+
+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.
+    #
+    # Concurrency control is the stream sequence: each row claims its
+    # stream's next `seq` under UNIQUE(key, scope, seq), so of two concurrent
+    # writes the database rejects one — atomic, with no lock table, no
+    # advisory locks, and no guarded updates. A rejected unconditional write
+    # re-runs with fresh reads; a rejected compare-and-swap re-runs, sees the
+    # interleaved write, and raises StaleWrite. Rows are immutable and seq
+    # 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
+
+      # Database races a write can lose and safely re-run: two writers
+      # claiming the same seq (RecordNotUnique — the re-run reads the new
+      # newest row), and adapter-reported deadlocks / serialization failures
+      # (TransactionRollbackError covers both). StaleWrite is deliberately
+      # NOT here — a retried CAS would recompute against the new state and
+      # silently defeat the mechanism (the re-run raises it AFTER re-reading,
+      # which is the correct outcome, not a retry of the comparison).
+      RETRYABLE = [
+        ::ActiveRecord::RecordNotUnique,
+        ::ActiveRecord::TransactionRollbackError
+      ].freeze
+
+      # Attempts per write: the first, plus retries for lost seq claims.
+      # Operator write rates make even the second attempt rare.
+      WRITE_ATTEMPTS = 3
+
+      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
+        # version move and rebuilds — stale in the safe direction only.
+        current_version = version
+
+        globals = {}
+        scoped = {}
+        row_versions = {}
+        newest_rows.each do |row|
+          case row.action
+          when "clear"
+            # Tombstones carry no value but DO carry the stream's stale-write
+            # stamp — an "absent" token must go stale when set/clear activity
+            # happened since it was read. Their scopes are validated like any
+            # other row's: a malformed tombstone scope must be quarantined
+            # here, not crash Dials.overview when it tries to parse the stamp
+            # map later.
+            if row.scope == Scope::GLOBAL || valid_scope_string?(row.key, row.scope)
+              (row_versions[row.key.to_sym] ||= {})[row.scope] = row.seq
+            end
+            next
+          when "set"
+            nil # fall through to the value path
+          else
+            quarantine("dials(#{row.key}, #{row.scope})", "unknown action #{row.action.inspect}")
+            next
+          end
+
+          value = decode_row(row.value, "dials(#{row.key}, #{row.scope})")
+          next if value.equal?(SKIP)
+
+          if row.scope == Scope::GLOBAL
+            globals[row.key.to_sym] = value
+          elsif valid_scope_string?(row.key, row.scope)
+            (scoped[row.key.to_sym] ||= {})[row.scope] = value
+          else
+            next
+          end
+          (row_versions[row.key.to_sym] ||= {})[row.scope] = row.seq
+        end
+
+        { globals: globals, scoped_overrides: scoped, version: current_version, row_versions: row_versions }
+      end
+
+      # The table is append-only, so its row count moves on every committed
+      # write and only ever grows. Count alone would be enough; max id is
+      # included as a belt against direct table surgery. Max id alone would
+      # NOT be enough: transaction A can claim id 10, B claim and commit id
+      # 11, and only then A commits — MAX(id) never moves for a process that
+      # already saw 11, so A's write would stay invisible until the next
+      # 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]
+      end
+
+      # The stale-write stamp of one override stream: the seq of its newest
+      # row, LIVE OR TOMBSTONE — a cleared override keeps its clear row's
+      # stamp, so an absent → set → clear cycle can never make an old
+      # "absent" token current again (no ABA). Only a stream with no rows at
+      # all is 0, the StoreVersion::ABSENT state.
+      def override_version(key, canonical_scope)
+        newest(key, canonical_scope)&.seq || 0
+      end
+
+      # True when the current thread's connection is inside an open
+      # transaction (typically an application transaction wrapping a dial
+      # write). The facade uses this to keep uncommitted dial state out of
+      # the shared cache.
+      def transaction_open?
+        pool = Entry.connection_pool
+        return false unless pool.active_connection?
+
+        connection = pool.respond_to?(:lease_connection) ? pool.lease_connection : pool.connection
+        connection.transaction_open?
+      end
+
+      # Runs the block after the current application transaction commits
+      # (immediately when no transaction is open). Discarded on rollback.
+      # The AR >= 7.2 floor enforced at require time guarantees the hook
+      # exists.
+      def after_commit(&)
+        if transaction_open?
+          ::ActiveRecord.after_all_transactions_commit(&)
+        else
+          yield
+        end
+      end
+
+      # The two mutations. `canonical_scope` is always a canonical string —
+      # Scope::GLOBAL for the global override. Both return [result, seq]:
+      # the usual result (previous value / did-anything-exist) plus the
+      # stream's seq after the write, so the facade can mint the caller's
+      # next token from the row it KNOWS was written — never from a second
+      # read that a concurrent writer could slip in front of.
+      def set_override(key, canonical_scope, value, actor, expected_version: nil)
+        write(expected_version) do
+          row = newest(key, canonical_scope)
+          assert_version!(expected_version, row&.seq || 0)
+
+          old = live?(row) ? decode(row.value) : nil
+          seq = (row&.seq || 0) + 1
+          append(key, canonical_scope, seq, "set", encode(value), actor)
+          [old, seq]
+        end
+      end
+
+      # Clearing appends a "clear" row, ending the stream's live override —
+      # resolution falls to the next layer, and the history of how it got
+      # there is preserved. Clearing what is not live is a no-op and appends
+      # nothing (but the version comparison, if requested, already ran: a
+      # stale no-op is still stale).
+      def clear_override(key, canonical_scope, actor, expected_version: nil)
+        write(expected_version) do
+          row = newest(key, canonical_scope)
+          assert_version!(expected_version, row&.seq || 0)
+          next [false, row&.seq || 0] unless live?(row)
+
+          seq = row.seq + 1
+          append(key, canonical_scope, seq, "clear", nil, actor)
+          [true, seq]
+        end
+      end
+
+      def changes(key: nil, limit: 50)
+        relation = Entry.order(id: :desc).limit(limit)
+        relation = relation.where(key: key.to_s) if key
+        rows = relation.to_a
+        previous = predecessors_of(rows)
+
+        rows.filter_map do |row|
+          # History applies the same quarantine rules as state: an unknown
+          # 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}")
+          end
+
+          parsed_scope =
+            if row.scope == Scope::GLOBAL
+              nil
+            elsif valid_scope_string?(row.key, row.scope)
+              Scope.parse(row.scope)
+            else
+              next nil
+            end
+
+          pred = previous[[row.key, row.scope, row.seq - 1]]
+          ChangeRecord.new(
+            key: row.key.to_sym,
+            scope: parsed_scope,
+            action: row.action,
+            old_value: pred && pred.action == "set" ? decode(pred.value) : nil,
+            new_value: row.action == "set" ? decode(row.value) : nil,
+            actor_type: row.actor_type,
+            actor_id: row.actor_id,
+            actor_label: row.actor_label,
+            created_at: row.created_at
+          )
+        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})")
+          nil
+        end
+      end
+
+      private
+
+      # 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
+      end
+
+      def live?(row)
+        !row.nil? && row.action == "set"
+      end
+
+      # 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.
+      def newest_rows
+        Entry.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
+          )
+        SQL
+      end
+
+      def append(key, canonical_scope, seq, action, encoded_value, actor)
+        Entry.create!(
+          key: key.to_s,
+          scope: canonical_scope,
+          seq: seq,
+          action: action,
+          value: encoded_value,
+          actor_type: actor[:actor_type],
+          actor_id: actor[:actor_id],
+          actor_label: actor[:actor_label]
+        )
+      end
+
+      # The predecessor row (seq - 1) for each listed change, fetched with
+      # one exact predicate per stream (no Cartesian over-fetch across
+      # unrelated keys/scopes) — old_value is derived from history itself,
+      # so history cannot disagree with what was actually replaced.
+      def predecessors_of(rows)
+        wanted = rows.filter_map { |r| [r.key, r.scope, r.seq - 1] if r.seq > 1 }
+        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)) }
+              .reduce(:or)
+              .index_by { |r| [r.key, r.scope, r.seq] }
+      end
+
+      # The compare half of compare-and-swap; `current` is the stream's
+      # newest seq, tombstones included (ABSENT strictly means "this stream
+      # was never written"). The comparison itself is a read; atomicity
+      # comes from the seq claim under UNIQUE(key, scope, seq) — a writer
+      # that interleaves between this check and our INSERT takes our slot,
+      # our INSERT raises RecordNotUnique, and write() converts that
+      # directly to StaleWrite for CAS callers (a lost claim PROVES an
+      # interleaver). Nothing applied, nothing logged.
+      def assert_version!(expected, current)
+        return if expected.nil? || expected == StoreVersion.token(current)
+
+        raise StaleWrite,
+              "the override has changed since version #{expected} was read — " \
+              "re-read (Dials.overview) and retry deliberately"
+      end
+
+      # A CAS write that loses its seq claim is STALE by definition — the
+      # lost claim proves a concurrent write landed after the version was
+      # read — so RecordNotUnique converts straight to StaleWrite, with no
+      # retry and no re-read (correct even inside an aborted outer
+      # transaction, where re-reading is impossible). Unconditional writes
+      # re-run the WHOLE transaction with fresh reads — but only when we are
+      # NOT inside an application transaction: after a database error there,
+      # the outer transaction is in an aborted state (PostgreSQL) and
+      # re-running statements would fail differently — the error must
+      # propagate to whoever owns that transaction. A seq claim that loses
+      # every attempt surfaces as WriteConflict (unconditional writes racing
+      # each other — essentially never at operator rates).
+      def write(expected_version, &)
+        attempts = 0
+        begin
+          Entry.transaction(&)
+        rescue ::ActiveRecord::RecordNotUnique
+          if expected_version
+            raise StaleWrite,
+                  "a concurrent write landed after version #{expected_version} was read — re-read (Dials.overview) and retry deliberately"
+          end
+
+          attempts += 1
+          retry if attempts < WRITE_ATTEMPTS && !transaction_open?
+          raise WriteConflict, "concurrent writes kept racing this override — safe to retry"
+        rescue ::ActiveRecord::TransactionRollbackError
+          attempts += 1
+          retry if attempts < WRITE_ATTEMPTS && !transaction_open?
+          raise
+        end
+      end
+
+      def encode(value)
+        JSON.generate(value)
+      end
+
+      # Values round-trip through JSON, so a :json dial's hash keys come back
+      # as strings — the same value a JSON API would hand you. Scalar types
+      # (boolean, integer, float, string) round-trip exactly.
+      def decode(raw)
+        JSON.parse(raw)
+      end
+
+      # Rows written around the gem (console surgery, bad imports) must not
+      # take down every dial read in the process: a row that does not decode
+      # to a legal stored value is skipped with a warning, and every other
+      # dial keeps resolving.
+      def decode_row(raw, where)
+        value = decode(raw)
+        if value.nil?
+          quarantine(where, "stored value is JSON null")
+          return SKIP
+        end
+
+        value
+      rescue TypeError, JSON::ParserError
+        quarantine(where, "stored value is not valid JSON")
+        SKIP
+      end
+
+      # For non-global streams only — the global's "{}" was matched before
+      # this runs, so an empty object here is corrupt (a hand-written row).
+      # Canonical exactness is required, not just shape: a noncanonical
+      # spelling ({"b":1,"a":2}, spaces, non-string values) would be a
+      # stream the resolver can never match against a canonicalized request.
+      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")
+          return false
+        end
+        return true if Scope.canonical(Scope.parse(scope)) == scope
+
+        quarantine("dials(#{key})", "scope #{scope.inspect} is not canonical")
+        false
+      rescue JSON::ParserError, InvalidScope
+        quarantine("dials(#{key})", "scope #{scope.inspect} is not a valid canonical scope")
+        false
+      end
+
+      def quarantine(where, reason)
+        warn "[dials] skipping corrupt row in #{where}: #{reason} (fix or delete the row; it was not written through the Dials API)"
+        nil
+      end
+    end
+  end
+end

data/lib/dials/active_record.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "active_record"
+require "dials"
+
+# The adapter's cache-coherence contract for writes inside application
+# transactions depends on ActiveRecord.after_all_transactions_commit
+# (added in 7.2). On older ActiveRecord there is no safe commit-time bust:
+# a mid-transaction republish of pre-commit state could outlive the commit
+# indefinitely. Failing loudly here beats shipping that silent gap.
+if Gem::Version.new(ActiveRecord::VERSION::STRING) < Gem::Version.new("7.2")
+  raise Dials::Error,
+        "dials/active_record requires ActiveRecord >= 7.2 " \
+        "(found #{ActiveRecord::VERSION::STRING}); the :memory store works on any version"
+end
+
+require_relative "active_record/models"
+require_relative "active_record/store"

data/lib/dials/actor.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Dials
+  # Normalizes whatever the caller passes as `actor:` into the three strings
+  # the change log stores. An ActiveRecord-ish object contributes its class
+  # name and id; a plain string is stored as the label; anything else uses
+  # its class and to_s. The label can be customized app-wide via
+  # `Dials.configure { |c| c.actor_label = ->(actor) { actor.email } }`.
+  #
+  # A nil actor falls back to `config.default_actor` (for apps without user
+  # identity); when that is also nil/absent, MissingActor — there is no
+  # anonymous mutation path the app didn't explicitly declare.
+  module Actor
+    module_function
+
+    def normalize(actor)
+      actor = default_actor 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"
+      end
+
+      {
+        actor_type: actor_type(actor),
+        actor_id: actor_id(actor),
+        actor_label: Dials.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
+      configured.respond_to?(:call) ? configured.call : configured
+    end
+
+    def actor_type(actor)
+      actor.is_a?(String) ? nil : actor.class.name
+    end
+
+    def actor_id(actor)
+      actor.respond_to?(:id) ? actor.id.to_s : nil
+    end
+
+    DEFAULT_LABEL = lambda do |actor|
+      if actor.is_a?(String)
+        actor
+      elsif actor.respond_to?(:email) && actor.email
+        actor.email
+      elsif actor.respond_to?(:name) && actor.name
+        actor.name
+      else
+        [actor.class.name, actor.respond_to?(:id) ? actor.id : nil].compact.join("#")
+      end
+    end
+  end
+end