query_stash 0.1.0

data/lib/query_stash/railtie.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/cache"
+require "active_support/core_ext/numeric/bytes"
+require "active_support/isolated_execution_state"
+require "active_support/notifications"
+
+# The railtie is the only part of QueryStash that expects ActiveSupport: it hands the rest what it
+# needs from it, as options of `config.query_stash`.
+module QueryStash
+  class Railtie < Rails::Railtie
+    # The options an adapter can set for itself, in `config.query_stash.active_record` and
+    # `config.query_stash.mongo`. What it does not set, it takes from `config.query_stash`.
+    ADAPTER_OPTIONS = %i[enabled isolated_state instrumenter error_reporter cache_store].freeze
+
+    # The adapters' sections of `config.query_stash`, which are not options of their own.
+    ADAPTER_SECTIONS = %i[active_record mongo sequel].freeze
+
+    class << self
+      # The `adapter` (QueryStash::ActiveRecord or QueryStash::Mongo) for the app's `config`, with
+      # its own options over the ones of `config.query_stash`, and the cache store they name.
+      #: (singleton(Base) adapter, untyped config) -> Base
+      def build(adapter, config)
+        options = options_for(adapter, config)
+
+        # `cache_store` takes the same values as Rails' `config.cache_store`.
+        adapter.new(
+          **options.slice(:enabled, :isolated_state, :instrumenter, :error_reporter, :raise_on_cache_error),
+          cache_store: ActiveSupport::Cache.lookup_store(*Array(options.cache_store))
+        )
+      end
+
+      # `config.query_stash`, with what the adapter's own section sets on top of it. A section only
+      # holds what the user set, so an option it has, even a `false` or a `nil`, is the user's choice.
+      #: (singleton(Base) adapter, untyped config) -> untyped
+      def options_for(adapter, config)
+        root = config.query_stash
+        own = root[adapter.name.to_s.demodulize.underscore.to_sym] || {}
+
+        ActiveSupport::OrderedOptions.new.update(root.except(*ADAPTER_SECTIONS)).update(own.slice(*ADAPTER_OPTIONS))
+      end
+    end
+
+    # What follows is Rails' own DSL: it runs blocks with another `self` and reaches methods that are
+    # added at runtime, so there is nothing for Steep to check it against.
+    # steep:ignore:start
+    config.before_configuration do
+      config.query_stash = ActiveSupport::OrderedOptions.new.update(
+        enabled: true,
+        isolated_state: ActiveSupport::IsolatedExecutionState,
+        instrumenter: ActiveSupport::Notifications,
+        error_reporter: ActiveSupport.error_reporter,
+        cache_store: [:memory_store, { size: 128.megabytes, compress: true }],
+        raise_on_cache_error: Rails.env.development? || Rails.env.test?
+      )
+
+      # Only for the adapters that are loaded.
+      config.query_stash.active_record = ActiveSupport::OrderedOptions.new if defined?(::ActiveRecord::Railtie)
+      config.query_stash.mongo = ActiveSupport::OrderedOptions.new if defined?(::Rails::Mongoid::Railtie)
+      config.query_stash.sequel = ActiveSupport::OrderedOptions.new if defined?(::SequelRails::Railtie)
+    end
+
+    # Builds each adapter's instance from the app's config, which the environment files have already
+    # set by now, and before config/initializers run, so those can configure its rules.
+    #
+    # The middleware stack is built before ActiveRecord::Base and Mongoid::Document load, so the
+    # middlewares can't be added from their on_load hooks: they go in whenever the framework is present.
+    initializer "query_stash", before: :load_config_initializers do |app|
+      if defined?(::ActiveRecord::Railtie)
+        require_relative "active_record"
+
+        QueryStash::ActiveRecord.set(app, QueryStash::Railtie.build(QueryStash::ActiveRecord, app.config))
+        app.config.middleware.use QueryStash::ActiveRecord::Middleware, app
+
+        # What the stash does for the Rails in use needs ActiveRecord.
+        ActiveSupport.on_load(:active_record) do
+          QueryStash::ActiveRecord[app].extend(QueryStash::ActiveRecord.implementation::Stash)
+        end
+      end
+
+      if defined?(::Rails::Mongoid::Railtie)
+        require_relative "mongo"
+
+        QueryStash::Mongo.set(app, QueryStash::Railtie.build(QueryStash::Mongo, app.config))
+        app.config.middleware.use QueryStash::Mongo::Middleware, app
+      end
+
+      if defined?(::SequelRails::Railtie)
+        require_relative "sequel"
+
+        QueryStash::Sequel.set(app, QueryStash::Railtie.build(QueryStash::Sequel, app.config))
+        app.config.middleware.use QueryStash::Sequel::Middleware, app
+
+        # Every database that loads the extension is stashed by the app's stash.
+        QueryStash::Sequel.stash_builder = ->(_db) { QueryStash::Sequel[app] }
+      end
+    end
+
+    # The database the app uses is the one sequel-rails connected, which is `Sequel::Model.db`: by now it has
+    # connected, unless it was told not to. The other databases of the app are up to it (see the README).
+    config.after_initialize do
+      ::Sequel::Model.db.extension(:query_stash) if defined?(::SequelRails::Railtie) && ::Sequel::DATABASES.any?
+    end
+
+    initializer "query_stash.active_job" do |app|
+      ActiveSupport.on_load(:active_job) do
+        if defined?(::ActiveRecord::Railtie)
+          around_perform { |_job, block| QueryStash::ActiveRecord[app].enable!(&block) }
+        end
+
+        around_perform { |_job, block| QueryStash::Mongo[app].enable!(&block) } if defined?(::Rails::Mongoid::Railtie)
+
+        around_perform { |_job, block| QueryStash::Sequel[app].enable!(&block) } if defined?(::SequelRails::Railtie)
+      end
+    end
+
+    config.to_prepare do |_app|
+      ActiveSupport.on_load(:active_record) do
+        require_relative "active_record"
+
+        implementation = QueryStash::ActiveRecord.implementation
+        if implementation.const_defined?(:IntentPatch)
+          ::ActiveRecord::ConnectionAdapters::QueryIntent.prepend(implementation::IntentPatch)
+        end
+
+        %i[
+          active_record_sqlite3adapter
+          active_record_postgresqladapter
+          active_record_mysql2adapter
+          active_record_trilogyadapter
+        ].each do |hook|
+          ActiveSupport.on_load(hook) do
+            patch = implementation::AdapterPatch
+            prepend patch
+          end
+        end
+      end
+
+      ActiveSupport.on_load(:mongoid) do
+        require_relative "mongo"
+
+        ::Mongo::Collection::View::Iterable.prepend(
+          QueryStash::Mongo::AdapterPatch
+        )
+      end
+    end
+    # steep:ignore:end
+  end
+end

data/lib/query_stash/registry/sql.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "../registry"
+
+module QueryStash
+  class Registry
+    # The rules of the adapters that stash SQL: a rule's selector is a regexp, matched against the query.
+    class Sql < Registry
+      # @rbs override
+      def add_rule(regex, ...)
+        raise Error, "Regex must be a Regexp, got #{regex.class}" if regex.class != Regexp
+
+        super
+      end
+    end
+  end
+end

data/lib/query_stash/registry.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module QueryStash
+  class Registry
+    # @rbs!
+    #   # How long a result is kept: a number of seconds, or something that works it out from the result.
+    #   type ttl = _ToI | ^(untyped result) -> _ToI
+
+    Rule = Data.define(
+      :selector, #: untyped
+      :name, #: String
+      :ttl_seconds, #: ttl
+      :ttl_jitter_seconds, #: ttl
+      :enabled, #: (^() -> boolish)?
+      :store #: _CacheStore?
+    )
+
+    class Rule
+      # The seconds a result is kept for, for `result`.
+      #: (untyped result) -> Integer
+      def ttl_seconds_for(result)
+        seconds = ttl_seconds #: untyped
+        seconds.respond_to?(:call) ? seconds.call(result).to_i : seconds.to_i
+      end
+
+      # The jitter added to that, for `result`.
+      #: (untyped result) -> Integer
+      def ttl_jitter_seconds_for(result)
+        seconds = ttl_jitter_seconds #: untyped
+        seconds.respond_to?(:call) ? seconds.call(result).to_i : seconds.to_i
+      end
+    end
+
+    # What `set_rule_defaults` can set: the options of `add_rule` other than the selector and the name.
+    RULE_DEFAULTS = %i[ttl_seconds ttl_jitter_seconds enabled store].freeze #: Array[Symbol]
+
+    # What an option of `add_rule` is when it is not given (`nil` is a value too: `enabled: nil`).
+    UNSET = Object.new.freeze #: Object
+
+    # @rbs @rules: Array[Rule]
+    # @rbs @rule_defaults: Hash[Symbol, untyped]
+
+    attr_reader :rules #: Array[Rule]
+
+    #: () -> void
+    def initialize
+      @rules = []
+      @rule_defaults = {}
+    end
+
+    # Sets what the rules added from now on take for the options they don't give, so that a block of rules
+    # needs to say only what is different about each one:
+    #
+    #   registry.set_rule_defaults(ttl_seconds: 60, ttl_jitter_seconds: 10)
+    #   registry.add_rule(/SELECT .*users/, name: "users")                   # 60 seconds, 10 of jitter
+    #   registry.add_rule(/SELECT .*orders/, name: "orders", ttl_seconds: 5) # 5 seconds, 10 of jitter
+    #
+    # The rules that exist are left as they are. A later call changes only the options it names, and `nil`
+    # takes a default away.
+    #
+    # @rbs **defaults: untyped
+    # @rbs return: Hash[Symbol, untyped]
+    def set_rule_defaults(**defaults)
+      unknown = defaults.keys - RULE_DEFAULTS
+      unless unknown.empty?
+        raise Error, "Unknown rule defaults: #{unknown.join(", ")} (use #{RULE_DEFAULTS.join(", ")})"
+      end
+
+      @rule_defaults = @rule_defaults.merge(defaults).compact
+    end
+
+    # `ttl_seconds` and `ttl_jitter_seconds` are required, unless `set_rule_defaults` gave them.
+    #
+    # @rbs selector: untyped
+    # @rbs name: String
+    # @rbs ttl_seconds: ttl | Object
+    # @rbs ttl_jitter_seconds: ttl | Object
+    # @rbs enabled: (^() -> boolish)? | Object
+    # @rbs store: _CacheStore? | Object
+    # @rbs return: Array[Rule]
+    def add_rule(
+      selector, # required
+      name:,
+      ttl_seconds: UNSET,
+      ttl_jitter_seconds: UNSET,
+      enabled: UNSET,
+      store: UNSET
+    )
+      raise Error, "Rule name is required" if name.nil? || name.empty?
+
+      raise Error, "Rule name #{name.inspect} is already taken" if @rules.any? { |r| r.name == name }
+
+      given = { ttl_seconds: ttl_seconds, ttl_jitter_seconds: ttl_jitter_seconds, enabled: enabled, store: store }
+      given = given.reject { |_, value| UNSET.equal?(value) }
+      options = { enabled: nil, store: nil }.merge(@rule_defaults, given) #: Hash[Symbol, untyped]
+      %i[ttl_seconds ttl_jitter_seconds].each do |required|
+        raise Error, "Rule #{name.inspect} needs #{required}, or a default for it" if options[required].nil?
+      end
+
+      @rules << Rule.new(
+        selector: selector,
+        name: name,
+        ttl_seconds: options[:ttl_seconds],
+        ttl_jitter_seconds: options[:ttl_jitter_seconds],
+        enabled: options[:enabled],
+        store: options[:store]
+      )
+    end
+
+    #: (String name) -> Array[Rule]
+    def delete_rule(name)
+      @rules.delete_if { |r| r.name == name }
+    end
+
+    # Selector / options / collection-based lookup
+    #: (untyped selector) -> Rule?
+    def match_rule(selector)
+      @rules.detect do |rule|
+        value_matches_pattern?(selector, rule.selector)
+      end
+    end
+
+    private
+
+    # Pattern matching for hashes.
+    #
+    # `pattern` is a subset / pattern-form of `full`:
+    # - wildcards and special values are interpreted via value_matches_pattern?
+    #
+    #: (Hash[untyped, untyped] full, Hash[untyped, untyped] pattern) -> bool
+    def hash_matches_pattern?(full, pattern)
+      pattern.all? do |k, expected|
+        full.key?(k) && value_matches_pattern?(full[k], expected)
+      end
+    end
+
+    # Pattern semantics:
+    #
+    # - Proc:
+    #     pattern.call(actual) must be truthy
+    # - Regexp:
+    #     actual.to_s must match pattern
+    # - Hash:
+    #     pattern is a nested hash pattern, recurse
+    # - Array:
+    #     pattern is a "prefix" array pattern:
+    #       - pattern length <= actual length
+    #       - each element is matched via value_matches_pattern?
+    # - Fallback:
+    #     actual == pattern
+    #
+    #: (untyped actual, untyped pattern) -> bool
+    def value_matches_pattern?(actual, pattern)
+      # Proc – fully custom predicate (Note: ANY is not a Proc)
+      return !!pattern.call(actual) if pattern.respond_to?(:call)
+
+      # Regexp – string-like match
+      return pattern.match?(actual.to_s) if pattern.is_a?(Regexp)
+
+      # Hash – recursive hash pattern
+      return hash_matches_pattern?(actual, pattern) if pattern.is_a?(Hash) && actual.is_a?(Hash)
+
+      # Array – element-wise prefix pattern
+      if pattern.is_a?(Array) && actual.is_a?(Array)
+        return false if pattern.length > actual.length
+
+        return pattern.each_with_index.all? do |pat_elem, idx|
+          value_matches_pattern?(actual[idx], pat_elem)
+        end
+      end
+
+      # Fallback: strict equality
+      actual == pattern
+    end
+  end
+end

data/lib/query_stash/sequel.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "digest"
+require "sequel/core"
+require_relative "base"
+require_relative "registry/sql"
+
+module QueryStash
+  # Stashes the `SELECT`s of Sequel datasets, matched by regexp like the ActiveRecord ones.
+  #
+  # A database stashes once it loads the extension, which gives it a stash of its own, from the options in its
+  # `:query_stash` option:
+  #
+  #   DB = Sequel.connect(url, query_stash: { cache_store: store, enabled: true })
+  #   DB.extension(:query_stash)
+  #   QueryStash::Sequel[DB].configure { |rules| ... }
+  #
+  # (`cache_store:` and the options of `QueryStash::Base#initialize`.) With sequel-rails, the railtie makes it
+  # the app's stash instead: `Sequel::Model.db.extension(:query_stash)` is all it takes for another database.
+  #
+  # (Inside this class `Sequel` is this class: the library is `::Sequel`.)
+  class Sequel < Base
+    # What the patch asks of Sequel's own objects.
+    #
+    # @rbs!
+    #   # A dataset, as far as the patch and the stash look at it.
+    #   interface _Dataset
+    #     def fetch_rows: (String sql) { (Hash[Symbol, untyped] row) -> untyped } -> untyped
+    #
+    #     def db: () -> ::Sequel::Database
+    #
+    #     def opts: () -> Hash[Symbol, untyped]
+    #
+    #     def is_a?: (Module mod) -> bool
+    #   end
+
+    CACHEABLE_SQL_REGEX = /\ASELECT/i #: Regexp
+    private_constant :CACHEABLE_SQL_REGEX
+
+    # Enables the stash for the duration of each request. `application` is the Rails application the
+    # middleware stack belongs to; `app` is the next middleware.
+    class Middleware
+      # @rbs @app: _RackApp
+      # @rbs @application: untyped
+
+      #: (_RackApp app, untyped application) -> void
+      def initialize(app, application)
+        @app = app
+        @application = application
+      end
+
+      #: (Hash[String, untyped] env) -> untyped
+      def call(env)
+        QueryStash::Sequel[@application].enable! { @app.call(env) }
+      end
+    end
+
+    # Included in the dataset class of each database that loads the extension. Every query a dataset runs
+    # goes through `fetch_rows`, which each adapter defines for its own dataset class, so this has to sit
+    # in front of those rather than in `Sequel::Dataset`.
+    #
+    # A database's stash is the one set for the database itself, which the extension does (see
+    # `QueryStash::Sequel.stash_builder`).
+    # @rbs module-self _Dataset
+    module DatasetPatch
+      #: (String sql) { (Hash[Symbol, untyped] row) -> untyped } -> untyped
+      def fetch_rows(sql, &consumer)
+        QueryStash::Sequel[db].wrap(self, sql, consumer) { |&rows| super(sql, &rows) }
+      end
+    end
+
+    # What builds the stash of a database that loads the extension without one: from its `:query_stash`
+    # option. (The railtie replaces it, to hand out the app's stash.)
+    DEFAULT_STASH_BUILDER = lambda do |db|
+      options = db.opts[:query_stash]
+      cache_store = options.is_a?(Hash) && options[:cache_store]
+      raise Error, "Give the database a :query_stash option with a :cache_store, to stash it" unless cache_store
+
+      QueryStash::Sequel.new(cache_store: cache_store, **options.except(:cache_store))
+    end #: ^(::Sequel::Database) -> QueryStash::Sequel
+
+    class << self
+      # @rbs self.@stash_builder: ^(::Sequel::Database) -> QueryStash::Sequel
+
+      # Builds the stash of a database that loads the extension without having one.
+      #: () -> (^(::Sequel::Database) -> QueryStash::Sequel)
+      def stash_builder
+        @stash_builder ||= DEFAULT_STASH_BUILDER
+      end
+
+      #: (^(::Sequel::Database) -> QueryStash::Sequel builder) -> void
+      attr_writer :stash_builder
+    end
+
+    ::Sequel::Database.register_extension(:query_stash) do |db|
+      QueryStash::Sequel.set(db, QueryStash::Sequel.stash_builder.call(db)) unless QueryStash::Sequel.key?(db)
+      db.extend_datasets(DatasetPatch)
+    end
+
+    # Runs the dataset's query through the stash: `cursor` fetches its rows into the block it is given,
+    # and `consumer` is the block `fetch_rows` was called with. (RBS can't say that a block takes a block,
+    # so the parameters of `cursor` are not typed.)
+    #: (_Dataset dataset, String sql, (^(Hash[Symbol, untyped]) -> untyped)? consumer) { (?) -> untyped } -> untyped
+    def wrap(dataset, sql, consumer, &cursor)
+      rule = rule_for(dataset, sql)
+      # Avoid eager loading every row unless this query actually matches a rule.
+      return cursor.call(&consumer) unless rule
+
+      rows = read(rule, dataset, sql) || write(rule, load_rows(&cursor), dataset, sql)
+      rows.each(&consumer)
+    end
+
+    # The rule the query is stashed under, or nil when it isn't to be stashed: the stash is off, it has
+    # binds or runs through a cursor (not supported), it is not a SELECT, or no rule matches it.
+    #: (_Dataset dataset, String sql) -> Registry::Rule?
+    def rule_for(dataset, sql)
+      return unless stashing?
+      return if bound?(dataset) || dataset.opts[:cursor]
+      return unless CACHEABLE_SQL_REGEX.match?(sql)
+
+      rule = registry.match_rule(sql)
+      rule if rule && (rule.enabled.nil? || rule.enabled.call)
+    end
+
+    # The same SQL is not the same query on another database, or on another server of the same one.
+    #: (_Dataset dataset, String sql) -> String
+    def cache_key_for(dataset, sql)
+      db = dataset.db
+      database = [db.database_type, db.opts[:host], db.opts[:database]].join("/")
+
+      "v1:#{dataset.opts[:server] || :default}:#{database}:#{Digest::SHA256.hexdigest(sql)}"
+    end
+
+    private
+
+    #: () -> Registry::Sql
+    def build_registry
+      Registry::Sql.new
+    end
+
+    # Whether the dataset is a prepared statement, or has bind variables.
+    #: (_Dataset dataset) -> bool
+    def bound?(dataset)
+      options = dataset.opts
+      !!(options[:bind_vars] || options[:bind_arguments] || dataset.is_a?(::Sequel::Dataset::PreparedStatementMethods))
+    end
+
+    #: () { (?) -> untyped } -> Array[Hash[Symbol, untyped]]
+    def load_rows(&cursor)
+      rows = [] #: Array[Hash[Symbol, untyped]]
+      cursor.call { |row| rows << row }
+      rows
+    end
+  end
+end

data/lib/query_stash/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module QueryStash
+  # Merging a change to this file into main releases the gem (.github/workflows/release.yml).
+  VERSION = "0.1.0" #: String
+end

data/lib/query_stash.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "query_stash/version"
+require_relative "query_stash/railtie" if defined?(Rails::Railtie)
+
+module QueryStash
+  # What a stash needs from the objects it is given. None of them has to be an ActiveSupport one: the
+  # railtie hands over the ActiveSupport ones, and anything that responds the same way works.
+  #
+  # @rbs!
+  #   # Where `enable!` and `disable!` keep what they set, like `ActiveSupport::IsolatedExecutionState`.
+  #   interface _IsolatedState
+  #     def []: (untyped key) -> untyped
+  #
+  #     def []=: (untyped key, untyped value) -> untyped
+  #
+  #     def key?: (untyped key) -> bool
+  #
+  #     def delete: (untyped key) -> untyped
+  #   end
+  #
+  #   # Where results are kept, like an `ActiveSupport::Cache::Store`. `write` is given `expires_in:`.
+  #   interface _CacheStore
+  #     def read: (String key) -> untyped
+  #
+  #     def write: (String key, untyped value, ?Hash[Symbol, untyped] options) -> untyped
+  #
+  #     def clear: () -> untyped
+  #   end
+  #
+  #   # Told about what the stash does, like `ActiveSupport::Notifications`.
+  #   interface _Instrumenter
+  #     def instrument: (String name, ?Hash[Symbol, untyped] payload) ?{ (Hash[Symbol, untyped]) -> untyped } -> untyped
+  #   end
+  #
+  #   # Told about the errors the stash handles, like `ActiveSupport.error_reporter`.
+  #   interface _ErrorReporter
+  #     def report: (Exception error, ?handled: bool) -> untyped
+  #   end
+  #
+  #   # The next middleware.
+  #   interface _RackApp
+  #     def call: (Hash[String, untyped] env) -> untyped
+  #   end
+
+  class Error < StandardError; end
+end

data/lib/sequel/extensions/query_stash.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# `Sequel::Database.extension(:query_stash)` (or `DB.extension(:query_stash)`) loads this, which registers
+# the extension.
+require "query_stash/sequel"

data/sig/query_stash/active_record.rbs

@@ -0,0 +1,118 @@
+# Generated from lib/query_stash/active_record.rb with RBS::Inline
+
+module QueryStash
+  class ActiveRecord < Base
+    # An ActiveRecord adapter, up to Rails 8.1.
+    interface _InternalExecQueryAdapter
+      def internal_exec_query: (String sql, ?String name, ?Array[untyped] binds, **untyped) -> ::ActiveRecord::Result
+    end
+
+    # An ActiveRecord adapter, from Rails 8.2.
+    interface _IntentAdapter
+      def execute_intent: (_QueryIntent intent) -> untyped
+
+      def cast_result: (untyped raw_result) -> ::ActiveRecord::Result
+    end
+
+    # A query, from Rails 8.2.
+    interface _QueryIntent
+      def raw_sql: () -> String
+
+      def has_binds?: () -> bool
+
+      def deliver_result: (::ActiveRecord::Result result) -> untyped
+
+      def cast_result: () -> ::ActiveRecord::Result
+    end
+
+    CACHEABLE_SQL_REGEX: Regexp
+
+    # Enables the stash for the duration of each request.
+    class Middleware
+      @app: _RackApp
+
+      @application: untyped
+
+      # : (_RackApp app, untyped application) -> void
+      def initialize: (_RackApp app, untyped application) -> void
+
+      # : (Hash[String, untyped] env) -> untyped
+      def call: (Hash[String, untyped] env) -> untyped
+    end
+
+    # Patch wraps queries run through `internal_exec_query` (rails 7.2 to 8.1).
+    # See `QueryStash::ActiveRecord.implementation`.
+    module InternalExecQuery
+      # @rbs module-self _InternalExecQueryAdapter
+      module AdapterPatch : _InternalExecQueryAdapter
+        # @rbs override
+        def internal_exec_query: ...
+      end
+
+      # @rbs module-self QueryStash::ActiveRecord
+      module Stash : QueryStash::ActiveRecord
+        # Runs the query through the stash, or just yields when the stash is off or the query isn't
+        # stashable.
+        # : (String sql, Array[untyped]? binds) { () -> ::ActiveRecord::Result } -> ::ActiveRecord::Result
+        def wrap: (String sql, Array[untyped]? binds) { () -> ::ActiveRecord::Result } -> ::ActiveRecord::Result
+      end
+    end
+
+    # Rails 8.2 runs queries as intents: the adapter's `execute_intent` runs one and hands its raw result
+    # back to the intent, which turns it into an ActiveRecord::Result in `QueryIntent#cast_result`.
+    module ExecuteIntent
+      # @rbs module-self _IntentAdapter
+      module AdapterPatch : _IntentAdapter
+        # : (_QueryIntent intent) -> untyped
+        def execute_intent: (_QueryIntent intent) -> untyped
+
+        private
+
+        # A stash hit is delivered as the ActiveRecord::Result it already is.
+        # : (untyped raw_result) -> ::ActiveRecord::Result
+        def cast_result: (untyped raw_result) -> ::ActiveRecord::Result
+      end
+
+      # @rbs module-self _QueryIntent
+      module IntentPatch : _QueryIntent
+        # : () -> ::ActiveRecord::Result
+        def cast_result: () -> ::ActiveRecord::Result
+      end
+
+      # @rbs module-self QueryStash::ActiveRecord
+      module Stash : QueryStash::ActiveRecord
+        @intent_rules: ObjectSpace::WeakMap[_QueryIntent, Registry::Rule]
+
+        # The rule each intent that missed the stash is to be stored under, until its result is cast.
+        # : (QueryStash::ActiveRecord stash) -> void
+        def self.extended: (QueryStash::ActiveRecord stash) -> void
+
+        # The stashed result of an intent (see AdapterPatch), or nil: when there is none, the intent is
+        # remembered for `write_intent` to store its result.
+        # : (_QueryIntent intent) -> ::ActiveRecord::Result?
+        def read_intent: (_QueryIntent intent) -> ::ActiveRecord::Result?
+
+        # Stores the result of an intent `read_intent` found nothing for.
+        # : (_QueryIntent intent, ::ActiveRecord::Result result) -> untyped
+        def write_intent: (_QueryIntent intent, ::ActiveRecord::Result result) -> untyped
+      end
+    end
+
+    # The implementation for the Rails in use: only to be asked once ActiveRecord is loaded.
+    # : () -> (singleton(InternalExecQuery) | singleton(ExecuteIntent))
+    def self.implementation: () -> (singleton(InternalExecQuery) | singleton(ExecuteIntent))
+
+    # The rule the query is stashed under, or nil when it isn't to be stashed: the stash is off, it has
+    # binds (not supported), it is not a SELECT, or no rule matches it.
+    # : (String sql, ?has_binds: bool?) -> Registry::Rule?
+    def rule_for: (String sql, ?has_binds: bool?) -> Registry::Rule?
+
+    # : (String sql) -> String
+    def cache_key_for: (String sql) -> String
+
+    private
+
+    # : () -> Registry::Sql
+    def build_registry: () -> Registry::Sql
+  end
+end