ruact 0.0.19 → 0.0.20

data/lib/ruact/controller/streaming.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+module Ruact
+  module Controller
+    # Story 19-1 (ADR D6, option A) — which actions send their page as it
+    # renders: the shell first, then each `<Suspense>`'s content when it is
+    # ready.
+    #
+    # Streaming needs `ActionController::Live`, and Live is decided before the
+    # action runs: it gives the action a response whose body is a queue, and
+    # runs the action in a thread of its own. So the app says which actions
+    # stream (`ruact_streaming`), and ruact applies Live to those and only
+    # those. The other actions of the controller respond as they did — a
+    # buffered response with its `ETag`, on the request's thread.
+    #
+    # A controller that includes `ActionController::Live` itself, and declares
+    # nothing, streams every action.
+    module Streaming
+      extend ActiveSupport::Concern
+
+      # Where `Controller.action(:name)` leaves the action's name: a route that
+      # names no action (`get "/x", to: PagesController.action(:show)`) gives
+      # `make_response!` nothing else to go on.
+      ACTION_ENV = "ruact.action"
+
+      # The thread that received the request. Under Live the action runs in
+      # another one, and what that thread leased from the connection pool is
+      # its own to give back.
+      REQUEST_THREAD_ENV = "ruact.request_thread"
+
+      included do
+        # Story 19-1 — the actions this controller declared with
+        # `ruact_streaming`, or nil. Inherited, and redeclarable by a subclass.
+        class_attribute :__ruact_streaming, instance_accessor: false, instance_predicate: false, default: nil
+        singleton_class.prepend(ResponseChoice)
+      end
+
+      class_methods do
+        # Story 19-1 — the actions whose page is sent as it renders: the shell
+        # and the `<Suspense>` fallbacks first, then each `<Suspense>`'s
+        # content, rendered after the shell is sent, as it is ready. On the
+        # first load and on a navigation.
+        #
+        # Without arguments, every ruact page of the controller streams (an
+        # action with no template of its own, a JSON one, does not); `only:`
+        # names the actions, `except:` leaves some out. One line in
+        # `ApplicationController` makes every page of the app stream.
+        #
+        # The actions that stream run under `ActionController::Live`, in a
+        # thread of their own: an `ETag` is not computed for them, and what a
+        # middleware set up for the request's thread (a thread variable, the
+        # locale) is not theirs — set it in the controller (`around_action`).
+        # The other actions are untouched.
+        #
+        # @param only [Symbol, String, Array<Symbol, String>] the actions that stream
+        # @param except [Symbol, String, Array<Symbol, String>] every page but these
+        # @return [void]
+        # @raise [ArgumentError] when given both `only:` and `except:`
+        # @example The show page streams
+        #   class PostsController < ApplicationController
+        #     include Ruact::Controller
+        #     ruact_streaming only: :show
+        #   end
+        def ruact_streaming(only: nil, except: nil)
+          raise ArgumentError, "ruact_streaming takes only: or except:, not both (#{name})" if only && except
+
+          Streaming.include_live(self)
+          # Directly above Live, so the actions that do not stream skip it.
+          include LiveChoice unless include?(LiveChoice)
+          # Ahead of Live's `make_response!`, which this class now extends and
+          # which would otherwise answer before the choice the parent has.
+          singleton_class.prepend(ResponseChoice)
+          self.__ruact_streaming = { only: only && Array(only).map(&:to_s).freeze,
+                                     except: except && Array(except).map(&:to_s).freeze,
+                                     declared_in: self }.freeze
+        end
+
+        # Whether `action` sends its page as it renders: an action declared
+        # with `ruact_streaming`, or any action of a controller that includes
+        # `ActionController::Live` and declares nothing.
+        #
+        # @param action [String, Symbol]
+        # @return [Boolean]
+        # @raise [Ruact::ConfigurationError] when `ruact_streaming only:` names
+        #   an action this controller does not have
+        def ruact_streaming?(action)
+          declared = __ruact_streaming
+          return include?(ActionController::Live) if declared.nil?
+
+          name = action.to_s
+          if declared[:only]
+            Streaming.check_declared!(self, declared) if declared[:declared_in].equal?(self)
+            return declared[:only].include?(name)
+          end
+          return false if declared[:except]&.include?(name)
+
+          ruact_page?(name)
+        end
+
+        # Whether `action` runs under `ActionController::Live`: it streams a
+        # ruact page, or the app included Live itself — in this controller or
+        # in a parent — for actions of its own (an SSE stream, `send_stream`),
+        # which keep it.
+        #
+        # @api private
+        # @param action [String, Symbol]
+        # @return [Boolean]
+        def __ruact_live?(action)
+          ruact_streaming?(action) || Streaming.live_by_app?(self)
+        end
+      end
+
+      # Includes `ActionController::Live` in +controller+ for `ruact_streaming`,
+      # marked as ruact's doing so {LiveInclusion} does not take it for the app's.
+      #
+      # @api private
+      def self.include_live(controller)
+        return if controller.include?(ActionController::Live)
+
+        controller.instance_variable_set(:@__ruact_including_live, true)
+        controller.include(ActionController::Live)
+      ensure
+        controller.remove_instance_variable(:@__ruact_including_live) if
+          controller.instance_variable_defined?(:@__ruact_including_live)
+      end
+
+      # Whether the app included `ActionController::Live` in +controller+ or a
+      # parent, itself and not through `ruact_streaming` (see {LiveInclusion}).
+      #
+      # @api private
+      def self.live_by_app?(controller)
+        controller.ancestors.any? { |ancestor| ancestor.instance_variable_get(:@__ruact_live_by_app) }
+      end
+
+      # Notes, on a class, that the app included `ActionController::Live` in it
+      # itself. Ruby calls `append_features` on every `include`, even of a
+      # module the class already has — the case of a controller that includes
+      # Live under a parent that declared `ruact_streaming`, where the include
+      # changes nothing and has to be seen anyway.
+      module LiveInclusion
+        def append_features(base)
+          unless base.instance_variable_defined?(:@__ruact_including_live)
+            base.instance_variable_set(:@__ruact_live_by_app, true)
+          end
+          super
+        end
+      end
+      ActionController::Live.singleton_class.prepend(LiveInclusion)
+
+      # The typo check for `ruact_streaming only:`, as `ruact_pages` has it
+      # (see {Pages.check_declared!}).
+      #
+      # @api private
+      # @raise [Ruact::ConfigurationError]
+      def self.check_declared!(owner, declared)
+        unknown = declared[:only] - owner.action_methods.to_a
+        unknown = unknown.reject { |action| File.exist?(owner.ruact_template_path(action)) }
+        return if unknown.empty?
+
+        what = unknown.one? ? "is not an action" : "are not actions"
+        raise Ruact::ConfigurationError,
+              "#{owner.name} declares ruact_streaming for #{unknown.join(', ')}, which #{what} of it " \
+              "(no method and no template). Check the spelling in `ruact_streaming`."
+      end
+
+      # `process` for an action that does not stream, in a controller that
+      # includes Live: everything but Live's own `process`, which would run the
+      # action in another thread.
+      #
+      # @api private
+      def self.process_without_live(controller, name)
+        method = controller.method(:process)
+        method = method.super_method until method.owner == ActionController::Live
+        method.super_method.call(name)
+      end
+
+      # The response, chosen per action: Live's for an action that streams, the
+      # ordinary one for the rest. Prepended to every ruact controller's
+      # singleton class.
+      module ResponseChoice
+        def make_response!(request)
+          request.set_header(REQUEST_THREAD_ENV, Thread.current)
+          return super unless __ruact_streaming
+
+          name = request.get_header(ACTION_ENV) || request.path_parameters[:action]
+          return super if name.nil? || __ruact_live?(name)
+
+          ActionController::Metal.singleton_class.instance_method(:make_response!).bind_call(self, request)
+        end
+
+        # The app `Controller.action(:name)` returns, which tells
+        # `make_response!` the action's name on the way in.
+        def action(name)
+          app = super
+          action_name = name.to_s.freeze
+          lambda do |env|
+            env[ACTION_ENV] = action_name
+            app.call(env)
+          end
+        end
+      end
+
+      # Included right after Live by `ruact_streaming`: an action that does not
+      # stream runs on the request's thread, as without Live — unless the app
+      # included Live itself, for actions of its own.
+      module LiveChoice
+        def process(name)
+          return super if self.class.__ruact_live?(name)
+
+          Streaming.process_without_live(self, name)
+        end
+      end
+
+      private
+
+      # Story 19-1 (D4) — under Live the action ran in a thread of the pool, and
+      # Rails gives back what the request's thread leased, not what this one
+      # did. Without this a `Model.connection` in a streamed action keeps its
+      # connection until the thread is reused (measured in 19-0, in 0.0.19
+      # too). Not when the action ran on the request's thread (Rails' test
+      # support runs Live inline).
+      def process_action(*)
+        super
+      ensure
+        __ruact_check_writes_after_stream
+        __ruact_release_connections if __ruact_on_live_thread?
+      end
+
+      def __ruact_on_live_thread?
+        request_thread = request&.get_header(REQUEST_THREAD_ENV)
+        !request_thread.nil? && !request_thread.equal?(Thread.current)
+      end
+
+      def __ruact_release_connections
+        return unless defined?(::ActiveRecord::Base)
+
+        ::ActiveRecord::Base.connection_handler.clear_active_connections!(:all)
+      end
+    end
+  end
+end

data/lib/ruact/controller.rb

@@ -7,6 +7,8 @@ require_relative "redirect_path"
 require_relative "view_helper"
 require_relative "validation_errors_collector"
 require_relative "controller/document_rendering"
+require_relative "controller/delivery"
+require_relative "controller/streaming"
 require_relative "controller/pages"
 require_relative "controller/page_rendering"
 require_relative "controller/format_negotiation"
@@ -36,9 +38,14 @@ module Ruact
     # and so the shared `vite_dev_running?` / `vite_manifest_entry` helpers are
     # reachable here without duplication.
     include Ruact::ViewHelper
-    # Who owns the `<head>` — the host app's layout, with ruact's built-in shell
-    # as the un-migrated fallback. See Ruact::Controller::DocumentRendering.
-    include Ruact::Controller::DocumentRendering
+    # How a rendered page is written — a Flight body, all at once or row by
+    # row, or an HTML document whose `<head>` the app's layout owns. See
+    # Ruact::Controller::Delivery and Ruact::Controller::DocumentRendering.
+    include Ruact::Controller::Delivery
+    # Which actions send their page as it renders — `ruact_streaming`, or a
+    # controller that includes `ActionController::Live` (Story 19-1). See
+    # Ruact::Controller::Streaming.
+    include Ruact::Controller::Streaming
     # Which actions are ruact pages — the whole controller, or the ones it
     # declares with `ruact_pages` (Story 17.0g). See Ruact::Controller::Pages.
     include Ruact::Controller::Pages
@@ -79,11 +86,13 @@ module Ruact
 
     private
 
-    # `ruact_js_assets` / `__ruact_component__` are public VIEW helpers, but on a
-    # controller a public instance method is exposed as a routable action. Demote
-    # the mixed-in helper methods so they are never callable as actions (they are
-    # only ever invoked internally by `ruact_html_shell`).
-    private :ruact_js_assets, :ruact_head_assets, :__ruact_component__
+    # The ruact helpers are public VIEW helpers, but on a controller a public
+    # instance method is exposed as a routable action. Demote the mixed-in
+    # helper methods so they are never callable as actions (the asset helpers
+    # are only ever invoked internally by `ruact_html_shell`; the others only
+    # by templates).
+    private :ruact_js_assets, :ruact_head_assets, :__ruact_component__, :__ruact_component_open__,
+            :__ruact_suspense__
 
     # Resolves the manifest for this render. In PRODUCTION this is the boot-time
     # cached +Ruact.manifest+ (set by Railtie#config.to_prepare) — no per-request
@@ -171,7 +180,13 @@ module Ruact
       pipeline  = RenderPipeline.new(ruact_manifest,
                                      controller_path: controller_path, logger: logger,
                                      development: Flight::Renderer.development_default)
-      streaming = ruact_request? && self.class.ancestors.include?(ActionController::Live)
+      # Story 19-1 — in an action that streams, the first load and a
+      # navigation alike, each `<Suspense>`'s content renders after the shell
+      # is sent: the view keeps its blocks instead of running them. Only when
+      # the response really is Live's: on HTTP/1.0 (nginx's default to its
+      # upstream) Live gives an ordinary response, which the server sends as
+      # soon as anything is written — the page then renders whole, in place.
+      streaming = self.class.ruact_streaming?(action_name) && response.is_a?(ActionController::Live::Response)
 
       # Allocate a per-render context and expose it to the view via a normal
       # (non-`@_`-prefixed) instance variable on the controller. Rails 8's
@@ -186,7 +201,7 @@ module Ruact
       # controller instance is per-request (Rails allocates a new one per
       # action), so this is per-request safe under multi-threaded servers
       # (NFR8). See Story 7.9 / Bug 7.8-B.
-      with_render_context do |render_context|
+      with_render_context(deferring: streaming) do |render_context|
         opts = template ? { template: template } : { action: action_name }
         html = render_to_string(opts.merge(details).merge(layout: false, locals: locals))
         emit_ruact_response(pipeline, html, render_context, streaming: streaming)
@@ -201,10 +216,10 @@ module Ruact
     # `nil` would leak a phantom assignment into `view_assigns`
     # (`{"ruact_render_context" => nil}`) on any subsequent error/rescue
     # render in the same request.
-    def with_render_context
+    def with_render_context(deferring: false)
       had_previous = instance_variable_defined?(:@ruact_render_context)
       previous     = @ruact_render_context if had_previous
-      render_context = RenderContext.new
+      render_context = RenderContext.new(deferring: deferring)
       @ruact_render_context = render_context
       begin
         yield render_context
@@ -217,38 +232,6 @@ module Ruact
       end
     end
 
-    # Build the wire output and write it to the response. Streaming responses
-    # only fire after `pipeline.render` returns without raising — that way a
-    # missing-component error can still surface as a normal 500 response
-    # (matching the legacy `#from_html` ordering) before any streaming
-    # response headers are mutated.
-    def emit_ruact_response(pipeline, html, render_context, streaming:)
-      # Story 15.5 (FR109) — record which page shape ruact rendered so the
-      # `Ruact::Server` dev log (`__ruact_log_response_shape!`) can name it and,
-      # crucially, stay SILENT on a plain Rails render (this flag is never set
-      # there). `@__`-prefixed → never leaks into `view_assigns`.
-      @__ruact_negotiated_page = ruact_request? ? :flight : :html_shell
-
-      if ruact_request? && streaming
-        enumerator = pipeline.render({ html: html, render_context: render_context }, mode: :stream)
-        response.headers["Content-Type"]      = "text/x-component; charset=utf-8"
-        response.headers["Cache-Control"]     = "no-cache"
-        response.headers["X-Accel-Buffering"] = "no"
-        begin
-          enumerator.each { |row| response.stream.write(row) }
-        ensure
-          response.stream.close
-        end
-      else
-        payload = pipeline.render({ html: html, render_context: render_context }, mode: :string)
-        if ruact_request?
-          render plain: payload, content_type: "text/x-component"
-        else
-          render_ruact_document(payload)
-        end
-      end
-    end
-
     # Overrides Rails redirect_to for RSC requests: emits a Flight redirect row
     # (`0:` followed by a JSON object with `redirectUrl` and `redirectType: "push"`)
     # instead of a 302 response.
@@ -291,13 +274,11 @@ module Ruact
       # Story 15.5 (FR109) — mark the Flight-redirect sub-shape for the dev log.
       @__ruact_negotiated_page = :flight_redirect
 
-      render plain: "0:#{JSON.generate({ 'redirectUrl' => redirect_url, 'redirectType' => 'push' })}\n",
-             content_type: "text/x-component"
+      __ruact_render_flight_redirect(redirect_url)
     end
 
     def ruact_request?
-      request.headers["Accept"]&.include?("text/x-component") ||
-        request.headers["Ruact-Request"] == "1"
+      RequestKind.flight?(request)
     end
 
     # Rails keeps `redirect_to` PUBLIC, and this module's body is private from

data/lib/ruact/deferred_render.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require "json"
+require "timeout"
+
+module Ruact
+  # Story 19-1 — the render of a page whose `<Suspense>` content runs after the
+  # shell is sent: the shell first, then each boundary, one at a time, in page
+  # order, each block evaluated only when its row is due.
+  #
+  #   run = DeferredRender.new(html, render_context, pipeline)
+  #   write(run.shell)
+  #   write(run.next_rows) while run.pending?
+  #
+  # A block runs in the view it was written in, with the template path Rails
+  # had when it met the tag, under `Ruact.config.suspense_timeout`. A block
+  # that raises, or runs past the timeout, becomes an error row for its
+  # boundary — reported through `Rails.error` and logged — and the next block
+  # runs. {Flight::Renderer} only ever serializes elements: evaluating, logging
+  # and reporting are here, outside `lib/ruact/flight/` (NFR10).
+  #
+  # Internal API: not part of the public compatibility contract.
+  class DeferredRender
+    TIMEOUT_DIGEST = "ruact:suspense-timeout"
+    ERROR_DIGEST   = "ruact:suspense-error"
+
+    # The content ran past `suspense_timeout`. Its own: a `Timeout::Error` the
+    # content raised itself (`Net::ReadTimeout` is one) is the content's error.
+    class Expired < StandardError; end
+
+    # What production says about a block that raised: nothing of the error.
+    PRODUCTION_MESSAGE = "An error occurred in a <Suspense>"
+
+    # React's development client reads an error's `stack` as frames; a few
+    # name the template and the gem without burying the overlay.
+    STACK_FRAMES = 12
+
+    # @param html [String] the page ActionView rendered with its blocks kept
+    #   (`RenderContext.new(deferring: true)`)
+    # @param pipeline [RenderPipeline] the manifest, controller path, logger
+    #   and wire flavour the render uses
+    # @param guard [#call, nil] wraps each block's evaluation, inside the
+    #   timeout: called with a block, returns its value or raises (the
+    #   controller's development check for writes the response can no longer
+    #   carry)
+    def initialize(html, render_context, pipeline, guard: nil)
+      @render_context  = render_context
+      @manifest        = pipeline.manifest
+      @controller_path = pipeline.controller_path
+      @development     = pipeline.development
+      @logger          = pipeline.logger
+      @guard           = guard
+      @registry        = []
+      @renderer = Flight::Renderer.new(convert(html), @manifest,
+                                       strict_serialization: Ruact.config.strict_serialization,
+                                       on_as_json_warning: pipeline.as_json_warning_callback,
+                                       development: @development)
+    end
+
+    # The shell's rows, as one string.
+    def shell
+      @renderer.shell.join
+    end
+
+    # Whether a boundary is still to be rendered.
+    def pending?
+      @renderer.pending?
+    end
+
+    # How many boundaries are still to be rendered.
+    def pending_count
+      @renderer.pending_count
+    end
+
+    # Renders the next boundary and returns its rows, as one string: the rows
+    # its content brings and its model row, or an error row.
+    def next_rows
+      boundary = @renderer.take_boundary
+      within_timeout(boundary[:delay]) do
+        @renderer.boundary_rows(boundary[:id], content(boundary[:element]))
+      end.join
+    rescue StandardError => e
+      raise if boundary.nil?
+
+      skip_unconverted_components
+      report(e, boundary)
+      @renderer.error_rows(boundary[:id], error_payload(e), boundary: boundary).join
+    end
+
+    private
+
+    # A block that failed may have registered components its HTML, now thrown
+    # away, was going to use: the next block's conversion starts after them.
+    def skip_unconverted_components
+      @registry.fill(nil, @registry.length...@render_context.components.length)
+    end
+
+    # The block's HTML as elements; content that is already elements as is.
+    def content(element)
+      return element unless element.is_a?(Flight::DeferredContent)
+
+      block = @render_context.block(element.index)
+      html = @guard ? @guard.call { evaluate(block) } : evaluate(block)
+      convert(html)
+    end
+
+    # Runs the block in its view, with the template path restored, and returns
+    # what it wrote. Only what it writes: a value it ends on is not content.
+    def evaluate(pending)
+      pending.view.instance_exec(pending) do |entry|
+        saved = [@virtual_path, @current_template]
+        @virtual_path = entry.virtual_path
+        @current_template = entry.template
+        begin
+          capture do
+            entry.block.call
+            nil
+          end
+        ensure
+          @virtual_path, @current_template = saved
+        end
+      end
+    end
+
+    # The components registered since the last conversion are resolved and
+    # added: a block registers its own as it runs. One the manifest cannot
+    # resolve fails this conversion and keeps its place (nil), so the next
+    # block does not meet it again.
+    def convert(html)
+      failure = nil
+      @render_context.components.drop(@registry.length).each do |entry|
+        @registry << @render_context.resolve_entry(entry, @manifest, controller_path: @controller_path)
+      rescue StandardError => e
+        @registry << nil
+        failure ||= e
+      end
+      raise failure if failure
+
+      HtmlConverter.convert(html.to_s, @registry.compact)
+    end
+
+    # The block's `delay` and the block itself, within `suspense_timeout`.
+    # `Timeout.timeout` with no exception class unwinds the block with an
+    # exception that is not a StandardError, so a `rescue` in the view, or
+    # Active Record wrapping what a query raised, cannot take it; it raises
+    # `Timeout::Error` out here. It interrupts Ruby code, not a query running
+    # inside a database driver that holds the VM lock (measured in 19-0).
+    # A `delay` longer than the limit ends in the timeout row at once, as it
+    # did before blocks ran later.
+    def within_timeout(delay, &)
+      limit = Ruact.config.suspense_timeout
+      return wait_then(delay, &) unless limit&.positive?
+      raise Expired, "the delay (#{delay}s) is longer than suspense_timeout" if delay && delay > limit
+
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      begin
+        Timeout.timeout(limit) { wait_then(delay, &) }
+      rescue Timeout::Error => e
+        # Ours only when the limit has passed; earlier, it is the content's.
+        raise if Process.clock_gettime(Process::CLOCK_MONOTONIC) - started < limit
+
+        raise Expired, "ran past suspense_timeout (#{limit}s)", cause: e
+      end
+    end
+
+    def wait_then(delay)
+      sleep(delay) if delay&.positive?
+      yield
+    end
+
+    def timed_out?(error)
+      error.is_a?(Expired)
+    end
+
+    def error_payload(error)
+      return Flight::RowEmitter.error_payload("Suspense timeout exceeded", digest: TIMEOUT_DIGEST) if timed_out?(error)
+      return Flight::RowEmitter.error_payload(PRODUCTION_MESSAGE, digest: ERROR_DIGEST) unless @development
+
+      payload = Flight::RowEmitter.error_payload("#{error.class}: #{error.message}", digest: ERROR_DIGEST)
+      payload["stack"] = development_stack(error)
+      payload
+    end
+
+    # React's development client reads `stack` as `[function, file, line, column]`.
+    def development_stack(error)
+      Array(error.backtrace).first(STACK_FRAMES).filter_map do |frame|
+        match = frame.match(/\A(.+?):(\d+)(?::in [`'](.+)')?\z/)
+        match && [match[3] || "(ruby)", match[1], Integer(match[2], 10), 0]
+      end
+    end
+
+    def report(error, boundary)
+      what = timed_out?(error) ? "ran past suspense_timeout (#{Ruact.config.suspense_timeout}s)" : "raised"
+      @logger&.error("[ruact] <Suspense> content#{where(boundary)} #{what}: #{error.class}: #{error.message}")
+      return unless defined?(Rails) && Rails.respond_to?(:error)
+
+      Rails.error.report(error, handled: true, severity: :error, source: "ruact.suspense")
+    end
+
+    def where(boundary)
+      element = boundary[:element]
+      return "" unless element.is_a?(Flight::DeferredContent)
+
+      location = @render_context.block(element.index).location
+      location ? " at #{location.path}:#{location.lineno}" : ""
+    end
+  end
+end

data/lib/ruact/doctor.rb

@@ -8,7 +8,7 @@ module Ruact
   # Runs a suite of installation health checks and prints ✓/✗ per check.
   # Extracted from the ruact:doctor Rake task for direct testability (FR27).
   class Doctor # rubocop:disable Metrics/ClassLength
-    CHECKS = %i[manifest vite flight_client controller layout head_assets streaming legacy_constant
+    CHECKS = %i[manifest vite flight_client controller layout head_assets streaming load_async legacy_constant
                 serialize_only flight_middleware].freeze
     # Built via Array#join so the gem-CI `name-propagation` guard does not
     # match these literals against itself (Story 5.1 review F4 — the doctor
@@ -487,6 +487,23 @@ module Ruact
       [:pass, "streaming: #{label} (#{streaming_server_hint})"]
     end
 
+    # Story 19-1 (ADR D1) — whether `load_async` runs its query in the
+    # background. It is how a page starts its queries early, so they finish
+    # while the shell is sent; without an executor (a new Rails app's default)
+    # it loads where it is called. A warning, not a failure: an app that never
+    # calls `load_async` has nothing to fix.
+    def check_load_async
+      return [:pass, "load_async: Active Record is not loaded"] unless defined?(::ActiveRecord::Base)
+
+      executor = ::ActiveRecord.async_query_executor
+      return [:pass, "load_async: runs in the background (async_query_executor = #{executor.inspect})"] if executor
+
+      [:warn,
+       "load_async: runs its query where it is called — config.active_record.async_query_executor is not " \
+       "set. Set it to :global_thread_pool (config/application.rb) so a page's queries start early and " \
+       "finish while its shell is sent."]
+    end
+
     # Detects host-app references to the legacy gem constant or require path
     # left over from the rename to `ruact`. Literal names are interpolated
     # from LEGACY_CONST / LEGACY_GEM so this file passes the gem-CI