rails_ai_admin 0.1.0

data/lib/rails_ai_admin/configuration.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  # Declares host adapters as names so development reload resolves fresh classes.
+  class Configuration
+    INTERNAL_PATH = /\A\/(?:[a-zA-Z0-9_-]+\/)*[a-zA-Z0-9_-]*\z/.freeze
+    # Gems an opt-in feature needs in the host's own Gemfile. The gemspec does
+    # not depend on them, so a conventional install pulls no AI code; boot
+    # enforces the supported range instead (RAA-026).
+    OPTIONAL_GEMS = {
+      "rails_tool_views" => { constant: "::RailsToolViews::VERSION", requirement: [ "~> 1.0.2" ].freeze }.freeze,
+      "ruby_llm" => { constant: "::RubyLLM::VERSION", requirement: [ ">= 2.2.0", "< 3" ].freeze }.freeze
+    }.freeze
+
+    # Nil when the loaded version of an optional gem is supported, otherwise a
+    # message naming the feature, the range and what is loaded.
+    def self.optional_gem_problem(name, feature, version: OPTIONAL_GEMS.fetch(name).fetch(:constant).safe_constantize)
+      requirement = Gem::Requirement.new(*OPTIONAL_GEMS.fetch(name).fetch(:requirement))
+      return if version && requirement.satisfied_by?(Gem::Version.new(version))
+      "#{feature} needs #{name} #{requirement} in the host Gemfile (#{version ? "#{version} is loaded" : 'it is not loaded'})"
+    end
+
+    attr_accessor :context_adapter, :authorization_adapter, :resources, :title, :intent_ttl,
+      :work_handlers, :outbox_auto_dispatch, :collection_auto_dispatch, :field_types, :authentication_path,
+      # Opt-in rails_tool_views review Surfaces. The host loads rails_tool_views
+      # and owns its global configuration; the admin never changes it.
+      :surfaces,
+      # Opt-in admin Chat. The host loads ruby_llm and names an adapter that
+      # builds a RubyLLM::Context per admin Context; global RubyLLM settings
+      # are never read for credentials or changed.
+      :assistant, :assistant_adapter, :assistant_model, :assistant_provider, :assistant_protocol,
+      # Messages one actor may send the assistant in any 24 hours; nil removes
+      # the limit. Each message can cost several provider calls.
+      :assistant_daily_message_limit,
+      # Stream replies into the transcript (true by default); turn off for a
+      # provider endpoint that cannot stream.
+      :assistant_streaming,
+      # :model shows the host model's validation messages for writable fields;
+      # :generic shows "is invalid" for each, for hosts whose messages may
+      # carry values an editor should not see (RAA-011).
+      :validation_messages,
+      # Optional short header badge such as "Staging" (RAA-024); none by default.
+      :environment_label,
+      # Active Job queue for collection, outbox and assistant jobs (RAA-020).
+      # Workers with explicit queue lists must include it.
+      :queue_name,
+      # Most rows one CSV export may contain (1..100,000). A larger list asks
+      # the person to narrow it first.
+      :export_limit,
+      # Most data rows one CSV import may contain (1..5,000). Each row is its
+      # own synchronous create.
+      :import_limit,
+      # Opt-in MCP server for outside agents; requires the assistant setup.
+      :mcp
+
+    def initialize
+      @authentication_path = nil
+      @context_adapter = nil
+      @authorization_adapter = "RailsAiAdmin::Authorization::Adapter"
+      @resources = []
+      @title = "Administration"
+      @intent_ttl = 15.minutes
+      @work_handlers = {}
+      @outbox_auto_dispatch = false
+      @collection_auto_dispatch = false
+      @field_types = {}
+      @surfaces = false
+      @queue_name = "rails_ai_admin"
+      @validation_messages = :model
+      @assistant = false
+      @assistant_adapter = nil
+      @assistant_model = nil
+      @assistant_provider = nil
+      @assistant_protocol = nil
+      @assistant_daily_message_limit = 100
+      @assistant_streaming = true
+      @export_limit = 10_000
+      @import_limit = 500
+      @mcp = false
+    end
+
+    # Validates and freezes the boot configuration without reading domain tables.
+    def finalize!
+      [ context_adapter, authorization_adapter ].compact.each do |name|
+        raise ConfigurationError, "Adapters must be constant name strings" unless name.is_a?(String) && name.match?(/\A[A-Z]\w*(?:::[A-Z]\w*)*\z/)
+      end
+      unless resources.is_a?(Array) && resources.all? { |name| name.is_a?(String) }
+        raise ConfigurationError, "resources must contain constant name strings"
+      end
+      raise ConfigurationError, "intent_ttl must be between 60 and 3600 seconds" unless (60..3600).cover?(intent_ttl)
+      unless work_handlers.is_a?(Hash) && work_handlers.all? { |kind, name| kind.is_a?(String) && kind.match?(/\A[a-z][a-z0-9_.-]{0,99}\z/) && name.is_a?(String) && name.match?(/\A[A-Z]\w*(?:::[A-Z]\w*)*\z/) } && [ true, false ].include?(outbox_auto_dispatch)
+        raise ConfigurationError, "work_handlers needs stable string keys/class names and outbox_auto_dispatch must be boolean"
+      end
+      raise ConfigurationError, "collection_auto_dispatch must be boolean" unless [ true, false ].include?(collection_auto_dispatch)
+      raise ConfigurationError, "surfaces must be boolean" unless [ true, false ].include?(surfaces)
+      unless environment_label.nil? || environment_label.is_a?(String) && environment_label.valid_encoding? && environment_label.length.between?(1, 40) && !environment_label.match?(/[[:cntrl:]]/)
+        raise ConfigurationError, "environment_label must be nil or 1 to 40 characters of plain text"
+      end
+      environment_label&.freeze
+      raise ConfigurationError, "validation_messages must be :model or :generic" unless %i[model generic].include?(validation_messages)
+      raise ConfigurationError, "export_limit must be an Integer from 1 to 100000" unless export_limit.is_a?(Integer) && export_limit.between?(1, 100_000)
+      raise ConfigurationError, "import_limit must be an Integer from 1 to 5000" unless import_limit.is_a?(Integer) && import_limit.between?(1, 5_000)
+      unless (queue_name.is_a?(String) || queue_name.is_a?(Symbol)) && queue_name.to_s.match?(/\A[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}\z/)
+        raise ConfigurationError, "queue_name must be a short queue name"
+      end
+      self.queue_name = queue_name.to_s.freeze
+      if surfaces && !defined?(::RailsToolViews::Engine)
+        raise ConfigurationError, "surfaces requires the host to load rails_tool_views (add it to the Gemfile and run its installer)"
+      end
+      if surfaces && (problem = self.class.optional_gem_problem("rails_tool_views", "surfaces"))
+        raise ConfigurationError, problem
+      end
+      if surfaces && (problem = surfaces_parent_controller_problem)
+        raise ConfigurationError, problem
+      end
+      validate_assistant!
+      raise ConfigurationError, "mcp must be boolean" unless [ true, false ].include?(mcp)
+      raise ConfigurationError, "assistant_streaming must be boolean" unless [ true, false ].include?(assistant_streaming)
+      raise ConfigurationError, "mcp requires config.assistant (its tables, ruby_llm and resolve_job)" if mcp && !assistant
+      unless authentication_path.nil? || authentication_path.is_a?(String) && authentication_path.valid_encoding? && authentication_path.ascii_only? && authentication_path.match?(INTERNAL_PATH)
+        raise ConfigurationError, "authentication_path must be a fixed internal path without query or fragment"
+      end
+      authentication_path&.freeze
+      Fields::Registry.new(field_types).validate!
+      field_types.each { |key, name| key.freeze; name.freeze }
+      field_types.freeze
+      work_handlers.each { |kind, name| kind.freeze; name.freeze }
+      work_handlers.freeze
+      resources.each(&:freeze)
+      resources.freeze
+      title.freeze
+      context_adapter&.freeze
+      authorization_adapter.freeze
+      [ assistant_adapter, assistant_model, assistant_provider, assistant_protocol ].each { |value| value&.freeze }
+      freeze
+    end
+
+    # rails_tool_views' own controller inherits its parent_controller when the
+    # host eager loads; a missing "::ApplicationController" (an API-only or
+    # minimal host) would otherwise fail production boot with a bare NameError
+    # (RAA-009, DEP-010). Returns nil when the parent resolves.
+    def surfaces_parent_controller_problem
+      return unless defined?(::RailsToolViews) && ::RailsToolViews.respond_to?(:configuration)
+      name = ::RailsToolViews.configuration.parent_controller.to_s
+      parent = name.safe_constantize
+      return if parent.is_a?(Class) && parent <= ::ActionController::Base
+      "surfaces needs rails_tool_views' parent_controller (#{name.inspect}) to name an ActionController::Base subclass. " \
+        "Add that controller, or set config.parent_controller in your RailsToolViews.configure block."
+    end
+
+    private
+
+    PROVIDER_NAME = /\A[a-z][a-z0-9_]{0,39}\z/
+
+    def validate_assistant!
+      raise ConfigurationError, "assistant must be boolean" unless [ true, false ].include?(assistant)
+      return unless assistant
+      unless defined?(::RubyLLM::Railtie)
+        raise ConfigurationError, "assistant requires the host to load ruby_llm (add it to the Gemfile)"
+      end
+      if (problem = self.class.optional_gem_problem("ruby_llm", "assistant"))
+        raise ConfigurationError, problem
+      end
+      unless assistant_adapter.is_a?(String) && assistant_adapter.match?(/\A[A-Z]\w*(?:::[A-Z]\w*)*\z/)
+        raise ConfigurationError, "assistant_adapter must be a constant name string"
+      end
+      unless assistant_model.is_a?(String) && assistant_model.match?(/\A[A-Za-z0-9][A-Za-z0-9._:\/-]{0,99}\z/)
+        raise ConfigurationError, "assistant_model must name one model"
+      end
+      unless assistant_daily_message_limit.nil? || assistant_daily_message_limit.is_a?(Integer) && assistant_daily_message_limit.between?(1, 100_000)
+        raise ConfigurationError, "assistant_daily_message_limit must be nil or a whole number from 1 to 100000"
+      end
+      [ assistant_provider, assistant_protocol ].each do |value|
+        raise ConfigurationError, "assistant_provider and assistant_protocol must be short lowercase names" unless value.nil? || value.is_a?(String) && value.match?(PROVIDER_NAME)
+      end
+    end
+  end
+end

data/lib/rails_ai_admin/context.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  # Holds authority resolved by the host for one request or job attempt.
+  # No process-global Current state or provider credentials are retained.
+  class Context
+    attr_reader :actor, :tenant, :actor_ref, :tenant_ref, :security_version, :time_zone
+
+    def initialize(actor:, tenant:, security_version:, time_zone: "UTC")
+      @actor, @tenant = actor, tenant
+      @actor_ref = reference("actor", actor)
+      @tenant_ref = reference("tenant", tenant)
+      @security_version = security_version.to_s.dup.freeze
+      raise AccessDenied, "UNAUTHENTICATED" if @security_version.empty? || @security_version.bytesize > 150
+      raise ConfigurationError, "Unknown time zone" unless ActiveSupport::TimeZone[time_zone]
+      @time_zone = time_zone.dup.freeze
+      freeze
+    end
+
+    private
+
+    def reference(kind, object)
+      raise AccessDenied, "UNAUTHENTICATED" unless object && object.class.name.present? && object.respond_to?(:id) && object.id.present?
+      ref = "raa:#{kind}:#{object.class.name}:#{object.id}"
+      raise AccessDenied, "UNAUTHENTICATED" if ref.bytesize > 150 || ref.match?(/[\x00-\x1f\x7f]/)
+      ref.freeze
+    end
+  end
+end

data/lib/rails_ai_admin/doctor.rb

@@ -0,0 +1,301 @@
+# frozen_string_literal: true
+
+require "rails_ai_admin/schema_suggestions"
+require "rails_ai_admin/templates/inspector"
+
+module RailsAiAdmin
+  # Reports support boundaries without probing credentials or calling providers.
+  class Doctor
+    Check = Data.define(:name, :status, :message)
+
+    def initialize(configuration: RailsAiAdmin.configuration, registry: RailsAiAdmin.registry, application: Rails.application,
+      operation_registry: RailsAiAdmin.operation_registry, work_registry: RailsAiAdmin.work_registry)
+      @configuration, @registry, @application = configuration, registry, application
+      @operation_registry, @work_registry = operation_registry, work_registry
+    end
+
+    # Admin Surfaces never change the host-owned rails_tool_views runtime; this
+    # reports whether the opt-in can work, not whether it is authorized.
+    def surface_check
+      surfaces = @configuration.respond_to?(:surfaces) && @configuration.surfaces
+      unless surfaces
+        return Check.new("surfaces", :closed, "Admin review Surfaces are off. The host owns any rails_tool_views runtime; the admin does not configure it.")
+      end
+      require "rails_ai_admin/integrations/tool_views"
+      return Check.new("surfaces", :error, "surfaces is enabled but rails_tool_views is not loaded.") unless Integrations::ToolViews.available?
+      if @configuration.respond_to?(:surfaces_parent_controller_problem) && (problem = @configuration.surfaces_parent_controller_problem)
+        return Check.new("surfaces", :error, problem)
+      end
+      unless ::RailsToolViews::Surface.table_exists? && ::RailsToolViews::ActionExecution.table_exists?
+        return Check.new("surfaces", :error, "Run the rails_tool_views installer migrations before enabling admin Surfaces.")
+      end
+      Integrations::ToolViews.ensure_registered!
+      operations = @registry.resources.sum { |resource| resource.operation_declarations.keys.count { |key| resource.surface_operation?(key) } }
+      assistant = @configuration.respond_to?(:assistant) && @configuration.assistant
+      Check.new("surfaces", :review, "#{Integrations::ToolViews::KEY} is registered for #{operations} member operations through admin-owned endpoints. " \
+        "#{assistant ? 'Assistant proposals present it and confirmed outcomes continue their chat once.' : 'Assistant presentation is off.'}")
+    rescue ConfigurationError => error
+      Check.new("surfaces", :error, error.message)
+    end
+
+    # Reports whether the opt-in MCP endpoint can authenticate tokens.
+    def mcp_check
+      return Check.new("mcp", :closed, "The MCP endpoint is off.") unless @configuration.respond_to?(:mcp) && @configuration.mcp
+      require "rails_ai_admin/mcp"
+      return Check.new("mcp", :error, "Run rails_ai_admin:assistant and db:migrate; the access token table is missing.") unless Mcp::AccessToken.table_exists?
+      active = Mcp::AccessToken.active.count
+      Check.new("mcp", :review, "MCP clients use personal access tokens (#{active} active). Each request resolves the owner through resolve_job " \
+        "and applies the assistant? grant and the owner's current grants; proposals wait for confirmation in the admin. Serve it over HTTPS only.")
+    end
+
+    # Reports whether opt-in admin Chat can run. It never calls the adapter or
+    # a provider, so it cannot prove credentials, model access or grants.
+    def assistant_check
+      unless @configuration.respond_to?(:assistant) && @configuration.assistant
+        return Check.new("assistant", :closed, "Admin Chat is off. No RubyLLM code, tables or provider calls are used.")
+      end
+      require "rails_ai_admin/assistant"
+      missing = [ Assistant::Chat, Assistant::Message, Assistant::Turn, ::RubyLLM::ActiveRecord::ToolCall, ::RubyLLM::ActiveRecord::Usage ]
+        .reject(&:table_exists?).map(&:table_name)
+      return Check.new("assistant", :error, "Run rails_ai_admin:assistant and db:migrate; missing tables: #{missing.join(', ')}.") if missing.any?
+      adapter = @configuration.assistant_adapter.safe_constantize
+      unless adapter.is_a?(Class) && adapter.method_defined?(:llm_context) && adapter.instance_method(:llm_context).parameters.include?([ :keyreq, :context ])
+        return Check.new("assistant", :error, "#{@configuration.assistant_adapter} must define llm_context(context:) returning a RubyLLM::Context or nil.")
+      end
+      job = @configuration.context_adapter&.safe_constantize
+      unless job.is_a?(Class) && job.method_defined?(:resolve_job)
+        return Check.new("assistant", :error, "Assistant turns run in jobs; the context adapter must define resolve_job.")
+      end
+      Check.new("assistant", :review, "Model #{@configuration.assistant_model}; tools apply each actor's current grants and the independent assistant? grant. " \
+        "Schedule rails_ai_admin:assistant:scan, keep provider credentials in the adapter's own RubyLLM::Context, and verify real-provider behavior separately.")
+    rescue NameError, ConfigurationError => error
+      Check.new("assistant", :error, "Assistant configuration failed (#{error.class.name}).")
+    end
+
+    def checks
+      config = @configuration
+      collections = @registry.resources.sum { |resource| @operation_registry.custom(resource).count { |definition| definition.scope == :collection } }
+      result = [
+        adapter_check("context", config.context_adapter, { resolve: [ 1, [] ] }),
+        adapter_check("policy", config.authorization_adapter, { scope: [ 0, %i[context resource relation] ], allowed?: [ 0, %i[context action resource record] ], fields: [ 0, %i[context resource action record] ] }),
+        autoload_check,
+        rails_check,
+        assistant_check,
+        mcp_check,
+        Check.new("files", :unsupported, "Private attachment management is not implemented."),
+        selection_check,
+        Check.new("queue", @work_registry.definitions.empty? && collections.zero? ? :closed : :review,
+          "#{@work_registry.definitions.size} outbox handlers; #{collections} collection handlers; auto_dispatch=#{config.outbox_auto_dispatch}/#{config.collection_auto_dispatch}; " \
+          "jobs use the #{queue_name(config).inspect} queue. Schedule the pending scans, make sure a worker processes that queue, and verify persistent queues/downstream idempotency."),
+        backlog_check,
+        surface_check
+      ]
+      result.concat(override_checks)
+      if @work_registry.definitions.any? || collections > 0
+        result << adapter_check("job_context", config.context_adapter, { resolve_job: [ 0, %i[actor_ref tenant_ref security_version] ] })
+        result << Check.new("work_delivery_policy", :review, "Delivery and receipt grants are independent of command preconditions; default denies. Verify fresh tenant/epoch, record-version policy and one effect per item in host tests.")
+      end
+      @registry.resources.each do |resource|
+        begin
+          if config.authorization_adapter == "RailsAiAdmin::Authorization::PunditAdapter"
+            configured = Authorization::PunditAdapter.new.configured?(resource)
+            policy_status = resource.policy.nil? ? :closed : (configured ? :review : :error)
+            result << Check.new("policy:#{resource.key}", policy_status,
+              "Explicit Pundit policy and policy-owned Scope required; field grants are independent. Mapping complete=#{configured}; authorization still needs host tests.")
+          end
+          model = resource.model_class
+          same_pool = model.connection_pool.equal?(OperationRun.connection_pool) && model.connection_pool.equal?(AuditEvent.connection_pool) && model.connection_pool.equal?(WorkItem.connection_pool)
+          version = RecordVersion.strategy(model)
+          writable = !resource.readonly?
+          status = writable && (!same_pool || version.nil? || model.composite_primary_key?) ? :error : :ok
+          status = :error if writable && !%w[SQLite PostgreSQL].include?(model.connection.adapter_name)
+          message = "same_pool=#{same_pool}; version=#{version || "missing"}; readonly=#{resource.readonly?}. Host callbacks must be database-only. " \
+            "List pages omit in-scope records that deny show; check scope/show agreement with TestKit.assert_scope_matches_show."
+          result << Check.new("resource:#{resource.key}", status, message)
+          result.concat(schema_checks(resource, model))
+          @operation_registry.custom(resource).each do |definition|
+            models = definition.handler_class.atomic_models.map(&:constantize)
+            valid = models.all? { |related| related.is_a?(Class) && related < ActiveRecord::Base && related.connection_pool.equal?(model.connection_pool) }
+            result << Check.new("operation:#{resource.key}:#{definition.key}", valid ? :review : :error,
+              "Scope=#{definition.scope}; declared atomic models share pool=#{valid}; handler/input metadata validated. Trusted Ruby is not a sandbox: test callbacks, preflight purity and external-effect boundaries. Duration checks are cooperative, not a hard SQL/Ruby interrupt. Collection inputs persist once: minimize payloads, never submit credentials, and review retention.")
+          end
+        rescue ActiveRecord::ActiveRecordError, NameError, ConfigurationError => error
+          result << Check.new("resource:#{resource.key}", :error, "Inspect model/migrations (#{error.class.name}); no record content was printed.")
+        end
+      end
+      result
+    end
+
+    private
+
+    BACKLOG_AGE = 15.minutes
+
+    def count_of(fields, noun) = "#{fields.size} #{fields.size == 1 ? noun : noun.pluralize}"
+    def named(fields) = fields.empty? ? "" : " (#{fields.first(10).map(&:name).join(', ')}#{fields.size > 10 ? ', …' : ''})"
+
+    def queue_name(config) = config.respond_to?(:queue_name) ? config.queue_name.to_s : "rails_ai_admin"
+
+    # The gemspec admits Rails 8.0.5.2 and up, the patched 8.0 release, but
+    # cannot also exclude 8.1 releases older than their patch, 8.1.4.1.
+    PATCHED_RAILS = { "8.0" => "8.0.5.2", "8.1" => "8.1.4.1" }.freeze
+
+    def rails_check(version: Rails.gem_version)
+      series = version.segments.first(2).join(".")
+      patched = PATCHED_RAILS[series]
+      return Check.new("rails", :ok, "Rails #{version} is at or above the patched #{series} release.") if patched && version >= Gem::Version.new(patched)
+      Check.new("rails", :error, "Rails #{version} is older than the patched #{series} release (#{patched || 'unknown series'}). " \
+        "Update Rails; known advisories affect this version.")
+    end
+
+    # Work that has been due for a while means no worker or scan is running it
+    # (RAA-020). Counts only; no record content or payload is read.
+    def backlog_check(now: Time.current)
+      cutoff = now - BACKLOG_AGE
+      due = ->(relation, table) { relation.where(table[:next_attempt_at].eq(nil).or(table[:next_attempt_at].lteq(now))).where(table[:created_at].lt(cutoff)) }
+      collection = due.call(BatchItem.where(status: "queued"), BatchItem.arel_table).count
+      outbox = due.call(WorkItem.where(status: "pending"), WorkItem.arel_table).count
+      turns = 0
+      if @configuration.respond_to?(:assistant) && @configuration.assistant
+        require "rails_ai_admin/assistant"
+        turns = due.call(Assistant::Turn.where(status: "queued"), Assistant::Turn.arel_table).count if Assistant::Turn.table_exists?
+      end
+      total = collection + outbox + turns
+      return Check.new("backlog", :ok, "No admin work has waited longer than #{BACKLOG_AGE.inspect}.") if total.zero?
+      Check.new("backlog", :review, "#{collection} collection items, #{outbox} outbox items and #{turns} assistant turns have waited longer than #{BACKLOG_AGE.inspect}. " \
+        "Check that a worker processes the #{queue_name(@configuration).inspect} queue and that the rails_ai_admin scans are scheduled.")
+    rescue ActiveRecord::ActiveRecordError, NameError
+      Check.new("backlog", :review, "Cannot inspect queued admin work. Check database connectivity and pending engine migrations.")
+    end
+
+    def override_checks
+      return [ Check.new("overrides", :review, "Run doctor inside the host to inspect standard app/views override metadata.") ] unless @application
+      findings = Templates::Inspector.new(root: @application.root).checks
+      return [ Check.new("overrides", :ok, "No standard-path admin template overrides found; custom view paths require host review.") ] if findings.empty?
+      findings.map do |finding|
+        Check.new("override:#{finding.key.gsub(/[^a-zA-Z0-9_\/.-]/, '_')[0, 200]}", finding.status,
+          "#{finding.code}: #{finding.path.inspect}; source version=#{finding.source_version || 'untracked'}. Source/context metadata only; review host edits for authority, CSRF and escaping. Custom view paths are not inspected.")
+      end
+    rescue ConfigurationError, SystemCallError
+      [ Check.new("overrides", :error, "Cannot inspect standard host override paths; no template was evaluated.") ]
+    end
+
+    def selection_check
+      installed = [ Selection, SelectionItem, BatchItem ].all?(&:table_exists?)
+      Check.new("selections", installed ? :review : :error,
+        "Fixed selection tables installed=#{installed}; at most 100 targets with lock_version or updated_at in one pool. Separate select_records? grant, current scope/show/fields and expiry apply. Selection alone is not approval; collection admission/leases require current host policies and persistent queue scans.")
+    rescue ActiveRecord::ActiveRecordError
+      Check.new("selections", :error, "Cannot inspect selection tables. Check database connectivity and pending engine migrations.")
+    end
+
+    def adapter_check(kind, name, methods)
+      if name.nil? || name == "RailsAiAdmin::Authorization::Adapter"
+        return Check.new(kind, :closed, "Default denies access. Implement and test the host context, scopes, actions and independent field grants.")
+      end
+      klass = name.safe_constantize
+      complete = klass.is_a?(Class) && (methods.keys - klass.public_instance_methods).empty? &&
+        klass.respond_to?(:new) && accepts_arguments?(klass.method(:new), 0, []) &&
+        accepts_arguments?(klass.instance_method(:initialize), 0, []) &&
+        methods.all? { |method, (positional, keywords)| accepts_arguments?(klass.instance_method(method), positional, keywords) }
+      Check.new(kind, complete ? :review : :error,
+        "Adapter public interface complete=#{complete}. Metadata does not prove anonymous denial or authorization; run host TestKit and HTTP tests.")
+    rescue NameError, LoadError
+      Check.new(kind, :error, "Adapter could not be loaded. Inspect its constant name and autoload path; no exception content was printed.")
+    end
+
+    def accepts_arguments?(method, positional, keywords)
+      parameters = method.parameters
+      keyword_parameters = parameters.any? { |kind, _| %i[key keyreq keyrest].include?(kind) }
+      return false if keywords.any? && parameters.any? { |kind, _| kind == :nokey }
+      positional += 1 if keywords.any? && !keyword_parameters
+      required = parameters.count { |kind, _| kind == :req }
+      maximum = parameters.any? { |kind, _| kind == :rest } ? Float::INFINITY : required + parameters.count { |kind, _| kind == :opt }
+      return false unless (required..maximum).cover?(positional)
+      return false unless (parameters.filter_map { |kind, name| name if kind == :keyreq } - keywords).empty?
+      parameters.any? { |kind, _| kind == :keyrest } || !keyword_parameters ||
+        (keywords - parameters.filter_map { |kind, name| name if %i[key keyreq].include?(kind) }).empty?
+    end
+
+    def autoload_check
+      unless @application
+        return Check.new("autoload", :review, "Run doctor inside the host Rails application to check app/rails_ai_admin loading.")
+      end
+      path = @application.root.join("app/rails_ai_admin").to_s
+      registered = @application.autoloaders.main.dirs.include?(path)
+      conventional = "rails_ai_admin".camelize == "RailsAiAdmin"
+      Check.new("autoload", conventional ? :review : :error,
+        "Default app/rails_ai_admin is an autoload root=#{registered}; RailsAiAdmin inflection preserved=#{conventional}. If the directory exists but is ignored, restore loading or verify explicit host loading. Custom host_paths configuration is not implemented.")
+    end
+
+    def schema_checks(resource, model)
+      columns = model.columns_hash
+      Fields::DependencyGraph.validate!(resource.fields)
+      physical_fields = resource.fields.reject(&:virtual?)
+      invalid = physical_fields.reject do |field|
+        column = columns[field.column]
+        column && (SchemaSuggestions::TYPES.key?(column.type) || column.type == :uuid) && !SchemaSuggestions.array?(column) ||
+          (field.scalar_type == :id && field.name == :id && model.primary_key.is_a?(String) && columns.key?(model.primary_key)) ||
+          # has_secure_password defines password= over a digest column.
+          (field.scalar_type == :password && model.method_defined?("#{field.column}=")) ||
+          (field.scalar_type == :file && model.respond_to?(:reflect_on_attachment) && model.reflect_on_attachment(field.column)&.macro == :has_one_attached) ||
+          (field.scalar_type == :files && model.respond_to?(:reflect_on_attachment) && model.reflect_on_attachment(field.column)&.macro == :has_many_attached) ||
+          (field.scalar_type == :rich_text && model.reflect_on_association("rich_text_#{field.column}").present?) ||
+          (field.scalar_type == :references && model.reflect_on_association(field.name)&.collection?)
+      end
+      result = [ Check.new("schema:#{resource.key}", invalid.empty? ? :ok : :error,
+        "#{invalid.size} declared fields lack supported scalar columns. Check field names/types; computed fields use declared dependency graphs. No records were sampled.") ]
+      mismatches = physical_fields.count do |field|
+        column = columns[field.column]
+        next false unless column
+        case field.scalar_type
+        when :belongs_to then !%i[integer string uuid].include?(column.type)
+        when :datetime then !%i[datetime timestamp].include?(column.type)
+        when :date then column.type != :date
+        when :boolean then column.type != :boolean
+        when :integer then column.type != :integer || model.defined_enums.key?(field.name.to_s)
+        when :decimal then column.type != :decimal
+        when :time then column.type != :time
+        when :json then !%i[json jsonb].include?(column.type)
+        when :email, :url, :text, :textarea then !%i[string text].include?(column.type)
+        else false
+        end
+      end
+      result << Check.new("field_types:#{resource.key}", mismatches.zero? ? :ok : :review,
+        "#{mismatches} declarations need scalar type compatibility review. Validate coercion and presentation with host data; metadata alone cannot prove them.")
+      # Each line names the declarations it counts (RAA-026); names are schema
+      # metadata, never record content.
+      sensitive = resource.fields.select { |field| SchemaSuggestions.sensitive?(model, field.name) }
+      result << Check.new("sensitivity:#{resource.key}", sensitive.empty? ? :ok : :review,
+        "Declarations matching sensitive names or encrypted attributes: #{count_of(sensitive, 'field')}#{named(sensitive)}. Review explicit grants, including the assistant? grant; naming heuristics cannot establish safety.")
+      indexes = model.connection.indexes(model.table_name)
+      missing = resource.fields.select do |field|
+        field.options[:sortable] && field.column != model.primary_key && !indexes.any? { |index| index.columns.is_a?(Array) && index.columns.first == field.column }
+      end
+      result << Check.new("sort_indexes:#{resource.key}", missing.empty? ? :ok : :review,
+        "Sortable declarations without a leading-column index: #{count_of(missing, 'field')}#{named(missing)}. Review query plans and tenant-composite indexes; this hint is not a performance verdict.")
+      unindexed_filters = resource.fields.select do |field|
+        !field.hidden? && field.filter_operators.any? && field.column != model.primary_key && !indexes.any? { |index| index.columns.is_a?(Array) && index.columns.include?(field.column) }
+      end
+      result << Check.new("filter_indexes:#{resource.key}", unindexed_filters.empty? ? :ok : :review,
+        "Filterable declarations in no index: #{count_of(unindexed_filters, 'field')}#{named(unindexed_filters)}. Review query plans with the tenant scope; low-cardinality filters may not need one.")
+      searchable = resource.fields.select { |field| field.options[:searchable] && !field.hidden? && !field.virtual? }
+      if searchable.any?
+        modes = searchable.map { |field| "#{field.name} (#{field.options[:searchable] == true ? :prefix : field.options[:searchable]})" }.join(", ")
+        result << Check.new("search:#{resource.key}", :review,
+          "Search uses case-insensitive LIKE on SQLite and ILIKE on PostgreSQL over #{modes}. A plain B-tree index cannot serve ILIKE or contains search; " \
+          "on PostgreSQL use a pg_trgm GIN index, or lower(column) text_pattern_ops for prefix search. SQLite folds ASCII case only, so non-ASCII case differs by database.")
+      end
+      references = resource.fields.select { |field| Field::REFERENCE_TYPES.include?(field.scalar_type) }
+      if references.any?
+        failures = references.filter_map do |field|
+          Fields::Association.validate!(resource, field, registry: @registry)
+          nil
+        rescue ConfigurationError => error
+          error.message
+        end
+        result << Check.new("associations:#{resource.key}", failures.empty? ? :review : :error,
+          failures.empty? ? "#{references.size} belongs_to declarations match model reflections. A changed reference must be visible in its target resource; verify target policies and foreign-key constraints." : failures.join("; "))
+      end
+      result
+    end
+  end
+end

data/lib/rails_ai_admin/engine.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  # Mountable Rails engine. AI integrations remain unloaded during this slice.
+  class Engine < ::Rails::Engine
+    isolate_namespace RailsAiAdmin
+
+    initializer "rails_ai_admin.request_logging" do |app|
+      app.middleware.insert_before Rails::Rack::Logger, RequestLogFilter
+    end
+
+    initializer "rails_ai_admin.assets" do |app|
+      if app.config.respond_to?(:assets)
+        app.config.assets.paths << root.join("app/assets/builds").to_s
+        if app.config.assets.respond_to?(:precompile)
+          app.config.assets.precompile += %w[rails_ai_admin.css rails_ai_admin.js]
+        end
+      end
+    end
+
+    config.to_prepare { RailsAiAdmin.prepare! }
+    config.after_initialize { RailsAiAdmin.configuration.finalize! }
+  end
+end

data/lib/rails_ai_admin/error.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  # Identifies a configuration that cannot safely serve administrative requests.
+  class ConfigurationError < StandardError; end
+
+  # Carries a stable, non-sensitive failure code across the execution boundary.
+  class AccessDenied < StandardError
+    attr_reader :code
+
+    def initialize(code = "NOT_FOUND")
+      @code = code
+      super(code)
+    end
+  end
+end