rails_ai_admin 0.1.0

data/lib/rails_ai_admin/queries/list.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  module Queries
+    # Bounded, permission-aware scalar index query. No SQL expressions enter it.
+    class List
+      # scope is the applied named scope's name, or nil for the policy relation.
+      # sort/direction describe the applied order (nil sort: primary key only).
+      # count is nil unless the resource opts in; count_capped marks COUNT_LIMIT.
+      Page = Data.define(:records, :number, :has_next, :scope, :sort, :direction, :page_size, :count, :count_capped)
+      # Default page size; resources may choose 1..100 through `index`.
+      PAGE_SIZE = 25
+      COUNT_LIMIT = Presentation::IndexSettings::COUNT_LIMIT
+      MAX_FILTER_CONDITIONS = 20
+      FILTER_VALUE = ->(value) { value.is_a?(String) && value.valid_encoding? && (value.encoding == Encoding::UTF_8 || value.ascii_only?) && value.length.between?(1, 200) && !value.match?(/[\x00-\x1f\x7f]/) }
+      AREL_PREDICATES = { "eq" => :eq, "gte" => :gteq, "lte" => :lteq }.freeze
+
+      def initialize(context, resource)
+        @access = Authorization::Access.new(context, resource)
+        @resource = resource
+      end
+
+      # scope: nil uses the declared default when it is currently granted;
+      # NamedScope::NONE applies no named scope at all.
+      # A named scope must be declared and granted; it is never discarded here.
+      # filters: { "field" => { "eq" | "gte" | "lte" => "wire string" } }, ANDed.
+      # Every field needs a current :filter grant and a declared operator.
+      def call(search: nil, sort: nil, direction: "asc", page: "1", recover_empty_page: false, scope: nil, filters: nil, page_size: nil, offset: nil)
+        @access.authorize!(:index)
+        unless (page.is_a?(String) || page.is_a?(Integer)) && page.to_s.valid_encoding? && page.to_s.ascii_only? && page.to_s.match?(/\A[1-9]\d{0,3}\z/) && page.to_i <= 1000
+          raise AccessDenied, "INVALID_QUERY"
+        end
+        raise AccessDenied, "INVALID_QUERY" unless %w[asc desc].include?(direction)
+        relation, named = filtered_relation(search: search, scope: scope, filters: filters)
+        settings = @resource.index
+        size = page_size || settings.page_size
+        raise AccessDenied, "INVALID_QUERY" unless size.is_a?(Integer) && size.between?(1, Presentation::IndexSettings::MAX_PAGE_SIZE)
+        raise AccessDenied, "INVALID_QUERY" unless offset.nil? || offset.is_a?(Integer) && offset.between?(0, 99_999) && !recover_empty_page
+        relation, field, direction = sorted(relation, sort, direction)
+        records = relation.offset(offset || (page.to_i - 1) * size).limit(size + 1).to_a
+        number = page.to_i
+        if recover_empty_page && records.empty? && number > 1
+          count = relation.except(:order).limit(number * size).count
+          number = [ 1, (count - 1).div(size) + 1 ].max
+          records = relation.offset((number - 1) * size).limit(size + 1).to_a
+        end
+        total = relation.except(:order).limit(COUNT_LIMIT + 1).count if settings.count == :exact
+        Page.new(records: records.first(size), number: number, has_next: records.size > size, scope: named&.name&.to_s,
+          sort: field&.name&.to_s, direction: field ? direction : "asc", page_size: size,
+          count: total && [ total, COUNT_LIMIT ].min, count_capped: !!total && total > COUNT_LIMIT)
+      end
+
+      # The complete ordered relation the index shows across all its pages,
+      # with the same grants and validation. Callers bound it themselves.
+      def relation(search: nil, sort: nil, direction: "asc", scope: nil, filters: nil)
+        @access.authorize!(:index)
+        raise AccessDenied, "INVALID_QUERY" unless %w[asc desc].include?(direction)
+        relation, = filtered_relation(search: search, scope: scope, filters: filters)
+        sorted(relation, sort, direction).first
+      end
+
+      # The bounded number of records the same search/scope/filters match,
+      # capped like the index count. Same grants and validation as call.
+      CountResult = Data.define(:count, :capped, :scope)
+      def count(search: nil, scope: nil, filters: nil)
+        @access.authorize!(:index)
+        relation, named = filtered_relation(search: search, scope: scope, filters: filters)
+        total = relation.except(:order).limit(COUNT_LIMIT + 1).count
+        CountResult.new([ total, COUNT_LIMIT ].min, total > COUNT_LIMIT, named&.name&.to_s)
+      end
+
+      # Coerces each wire value through the field's scalar contract. Values are
+      # bound by Arel; no operator, column or SQL text comes from the request.
+      def self.filter_value(field, operator, raw, time_zone:)
+        raise AccessDenied, "INVALID_QUERY" unless field.filter_operators.include?(operator.to_sym) && FILTER_VALUE.call(raw)
+        value = field.coerce(raw, time_zone: time_zone)
+        raise AccessDenied, "INVALID_QUERY" if value.nil?
+        value
+      rescue ArgumentError
+        raise AccessDenied, "INVALID_QUERY", cause: nil
+      end
+
+      private
+
+      def sorted(relation, sort, direction)
+        settings = @resource.index
+        table = @resource.model_class.arel_table
+        primary = @resource.model_class.primary_key
+        sortable = @access.fields(:sort)
+        field = if sort.present?
+          sortable.find { |entry| entry.name.to_s == sort } || raise(AccessDenied, "INVALID_QUERY")
+        elsif settings.default_sort
+          # An ungranted default would reveal order on a hidden basis; skip it.
+          direction = settings.default_direction
+          sortable.find { |entry| entry.name == settings.default_sort }
+        end
+        if field
+          # Empty values sort last in both directions on every database (RAA-028).
+          relation = relation.reorder(table[field.column].public_send(direction).nulls_last)
+          relation = relation.order(table[primary].asc) unless field.column == primary
+        else
+          relation = relation.reorder(table[primary].asc)
+        end
+        [ relation, field, direction ]
+      end
+
+      def filtered_relation(search:, scope:, filters:)
+        # Leading and trailing spaces are never part of the term (RAA-021).
+        search = search.strip if search.is_a?(String) && search.valid_encoding?
+        unless search.nil? || search.is_a?(String) && search.valid_encoding? && (search.encoding == Encoding::UTF_8 || search.ascii_only?) && search.length <= 200 && !search.match?(/[\x00-\x1f\x7f]/)
+          raise AccessDenied, "INVALID_QUERY"
+        end
+        unless scope.nil? || scope == NamedScope::NONE || scope.is_a?(String) && scope.valid_encoding? && scope.ascii_only? && scope.match?(NamedScope::NAME)
+          raise AccessDenied, "INVALID_QUERY"
+        end
+        granted = @access.named_scopes
+        unscoped = scope == NamedScope::NONE
+        named = if unscoped then nil
+        elsif scope.nil? then granted.find(&:default?)
+        else granted.find { |definition| definition.name.to_s == scope }
+        end
+        raise AccessDenied, "INVALID_QUERY" if scope && !unscoped && !named
+        relation = @access.relation
+        relation = named.apply(relation) if named
+        relation = apply_filters(relation, filters)
+        if search.present?
+          fields = @access.fields(:search)
+          raise AccessDenied, "INVALID_QUERY" if fields.empty?
+          predicates = fields.map do |field|
+            term = ActiveRecord::Base.sanitize_sql_like(search)
+            pattern = case field.options[:searchable]
+            when :exact then term
+            when :contains then "%#{term}%"
+            else "#{term}%"
+            end
+            @resource.model_class.arel_table[field.column].matches(pattern, "\\")
+          end
+          relation = relation.where(predicates.reduce(&:or))
+        end
+        [ relation, named ]
+      end
+
+      def apply_filters(relation, filters)
+        return relation if filters.nil?
+        unless filters.is_a?(Hash) && filters.keys.all? { |key| key.is_a?(String) || key.is_a?(Symbol) } &&
+            filters.values.all? { |conditions| conditions.is_a?(Hash) && conditions.any? && conditions.keys.all? { |key| AREL_PREDICATES.key?(key.to_s) } } &&
+            filters.values.sum(&:size) <= MAX_FILTER_CONDITIONS
+          raise AccessDenied, "INVALID_QUERY"
+        end
+        granted = @access.fields(:filter).index_by { |field| field.name.to_s }
+        table = @resource.model_class.arel_table
+        filters.reduce(relation) do |scoped, (name, conditions)|
+          field = granted[name.to_s] or raise AccessDenied, "INVALID_QUERY"
+          conditions.reduce(scoped) do |inner, (operator, raw)|
+            value = self.class.filter_value(field, operator.to_s, raw, time_zone: @access.context.time_zone)
+            inner.where(table[field.column].public_send(AREL_PREDICATES.fetch(operator.to_s), value))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rails_ai_admin/queries/named_scope.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  module Queries
+    # A declared list tab. It can only narrow the current authorized relation:
+    # its body builds a separate candidate relation whose primary keys are then
+    # intersected with the policy scope, so `unscoped`, `or` or a replaced
+    # condition inside the body cannot widen the result.
+    class NamedScope
+      NAME = /\A[a-z][a-z0-9_]{0,39}\z/
+      # List state for "no list tab": the whole policy relation even when a
+      # default scope exists (RAA-006). It cannot collide with NAME, and it
+      # narrows nothing the policy relation does not already allow.
+      NONE = "_none"
+      MAX_SCOPES = 20
+      attr_reader :name, :label, :body
+
+      def initialize(name, body = nil, label: nil, default: false)
+        unless (name.is_a?(String) || name.is_a?(Symbol)) && name.to_s.match?(NAME)
+          raise ConfigurationError, "Named scope needs a lowercase identifier of at most 40 characters"
+        end
+        unless body.nil? || body.is_a?(Proc) && body.lambda? && body.arity.zero?
+          raise ConfigurationError, "Named scope body must be a zero-argument lambda"
+        end
+        raise ConfigurationError, "Named scope default must be boolean" unless [ true, false ].include?(default)
+        @name = name.to_sym
+        @label = Navigation::Settings.caption(label) || Navigation::Settings.caption(@name.to_s.humanize)
+        @body = body
+        @default = default
+        freeze
+      end
+
+      def default? = @default
+
+      # Returns the policy relation narrowed to this scope. Trusted host Ruby
+      # still runs here; writes are prevented and failures stay generic.
+      def apply(relation)
+        return relation if body.nil?
+        model = relation.klass
+        primary_key = model.primary_key
+        raise ConfigurationError, "Named scopes require a single-column primary key" unless primary_key.is_a?(String)
+        candidate = build(model)
+        unless candidate.is_a?(ActiveRecord::Relation) && candidate.klass == model
+          raise ConfigurationError, "Named scope #{name} must return the resource's ActiveRecord relation"
+        end
+        if candidate.limit_value || candidate.offset_value || candidate.select_values.any? || candidate.group_values.any? ||
+            !candidate.having_clause.empty? || !candidate.from_clause.empty? ||
+            candidate.includes_values.any? || candidate.eager_load_values.any? || candidate.preload_values.any?
+          raise ConfigurationError, "Named scope #{name} must be a filter relation without limit, offset, select, group, having, from or eager loading"
+        end
+        relation.where(primary_key => candidate.unscope(:order).select(model.arel_table[primary_key]))
+      end
+
+      private
+
+      def build(model)
+        ActiveRecord::Base.while_preventing_writes { model.all.instance_exec(&body) }
+      rescue ConfigurationError
+        raise
+      rescue StandardError
+        raise ConfigurationError, "Named scope #{name} failed", cause: nil
+      end
+    end
+  end
+end

data/lib/rails_ai_admin/record_version.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  # The optimistic version a form, intent, selection or work item carries for
+  # one record. Models with Rails optimistic locking use lock_version. Other
+  # models use updated_at, as whole microseconds since the epoch, compared
+  # after the record is loaded with a row lock inside the write transaction.
+  module RecordVersion
+    STRATEGIES = %i[lock_version updated_at].freeze
+
+    module_function
+
+    # :lock_version, :updated_at or nil when the model cannot carry a version.
+    def strategy(model)
+      return :lock_version if model.locking_enabled? && model.locking_column == "lock_version"
+      column = model.columns_hash["updated_at"]
+      return :updated_at if column && %i[datetime timestamp].include?(column.type) && model.record_timestamps
+      nil
+    end
+
+    def supported?(model)
+      !strategy(model).nil? && !model.composite_primary_key?
+    end
+
+    # A nonnegative Integer. A record whose updated_at is still NULL is
+    # version 0 until its first write sets it.
+    def of(record)
+      case strategy(record.class)
+      when :lock_version then record.lock_version
+      when :updated_at
+        time = record.read_attribute("updated_at")
+        time.nil? ? 0 : (time.to_r * 1_000_000).to_i
+      else raise ConfigurationError, "Writes require lock_version or an updated_at timestamp"
+      end
+    end
+
+    # The column a resource must never let a person write directly.
+    def column(model) = strategy(model)&.to_s
+  end
+end

data/lib/rails_ai_admin/registry.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  # Maps stable slugs to explicit reloadable resources, never arbitrary constants.
+  class Registry
+    RESERVED = %w[assistant audit dashboards exports imports jobs selections settings doctor assets search mcp].freeze
+
+    def initialize(names)
+      @entries = {}
+      names.each do |name|
+        resource = name.constantize
+        raise ConfigurationError, "#{name} must inherit Resource" unless resource < Resource
+        key = resource.key.to_s
+        if !key.match?(/\A[a-z][a-z0-9_]*\z/) || RESERVED.include?(key)
+          raise ConfigurationError, "Invalid or reserved resource key #{key}"
+        end
+        raise ConfigurationError, "Duplicate resource key #{key}" if @entries.key?(key)
+        @entries[key] = resource.validate!
+      end
+      # Targets resolve at boot without loading models; reflection agreement
+      # is checked on first use and by doctor.
+      @entries.each_value do |resource|
+        resource.fields.each do |field|
+          next unless Field::REFERENCE_TYPES.include?(field.scalar_type) && !@entries.key?(field.options[:resource].to_s)
+          raise ConfigurationError, "#{resource.name} #{field.scalar_type} #{field.name} names unregistered resource #{field.options[:resource]}"
+        end
+        resource.has_many_declarations.each do |panel|
+          child = @entries[panel.resource.to_s]
+          via = child&.fields&.find { |field| field.name == panel.via(resource) }
+          unless via&.scalar_type == :belongs_to
+            raise ConfigurationError, "#{resource.name} has_many #{panel.name} needs registered resource #{panel.resource} with belongs_to #{panel.via(resource)}"
+          end
+        end
+      end
+      @entries.freeze
+      freeze
+    end
+
+    def fetch(key)
+      @entries.fetch(key.to_s) { raise AccessDenied }
+    end
+
+    def resources = @entries.values
+  end
+end

data/lib/rails_ai_admin/request_log_filter.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  # Redacts admin query values before Rails logs the initial request URL.
+  # The documented mount name is required; its path can be customized/reloaded.
+  class RequestLogFilter
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      helpers = Rails.application.routes.url_helpers
+      if helpers.respond_to?(:rails_ai_admin_path)
+        prefix = helpers.rails_ai_admin_path(script_name: "").delete_suffix("/")
+        path = env["PATH_INFO"].to_s
+        if path == prefix || path.start_with?("#{prefix}/")
+          filter = /\A(?!(?:controller|action|resource|id|format)\z)/
+          env["action_dispatch.parameter_filter"] = Array(env["action_dispatch.parameter_filter"]) + [ filter ]
+        end
+      end
+      @app.call(env)
+    end
+  end
+end

data/lib/rails_ai_admin/resource.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  # Describes explicit exposure of a host model. No attributes are auto-published.
+  class Resource
+    class << self
+      def inherited(child)
+        super
+        child.instance_variable_set(:@fields, {})
+        child.instance_variable_set(:@scopes, {})
+        child.instance_variable_set(:@index, Presentation::IndexSettings.new)
+        child.instance_variable_set(:@disabled_actions, [])
+        child.instance_variable_set(:@operations, {})
+        child.instance_variable_set(:@operation_scopes, {})
+        child.instance_variable_set(:@surface_operations, [])
+        child.instance_variable_set(:@assistant_operations, [])
+        child.instance_variable_set(:@navigation, Navigation::Settings.new)
+        child.instance_variable_set(:@has_many, {})
+        child.instance_variable_set(:@dashboard, [])
+        child.instance_variable_set(:@assistant_changes, [])
+      end
+
+      def model(name = nil)
+        @model_name = name if name
+        @model_name
+      end
+
+      def key(value = nil)
+        @key = value.to_sym if value
+        @key
+      end
+
+      def label(value = nil)
+        @label = value if value
+        @label || key.to_s.humanize
+      end
+
+      def title(value = nil)
+        @title = value.to_sym if value
+        @title
+      end
+
+      # Names an explicit optional policy for this resource, independent of aliases.
+      def policy(name = nil)
+        @policy_name = name if name
+        @policy_name
+      end
+
+      # Cosmetic configuration never grants or revokes direct resource access.
+      def navigation(value = :read, **options)
+        return @navigation if value == :read && options.empty?
+        unless value == :read || value == false && options.empty?
+          raise ConfigurationError, "Use navigation options or navigation false"
+        end
+        @navigation = Navigation::Settings.new(**(value == false ? { hidden: true } : options))
+      rescue ArgumentError
+        raise ConfigurationError, "Unknown navigation option", cause: nil
+      end
+
+      def readonly(value = true)
+        @readonly = value
+      end
+
+      def readonly? = @readonly == true
+
+      def disable(*actions)
+        @disabled_actions.concat(actions.map(&:to_sym))
+      end
+
+      def action_enabled?(action)
+        action = action.to_sym
+        known = %i[index show create update destroy].include?(action) || @operations.key?(action)
+        known && !@disabled_actions.include?(action) && !(readonly? && (%i[create update destroy].include?(action) || @operations.key?(action)))
+      end
+
+      # surface: true also allows reviewing a native member intent in an
+      # admin-owned rails_tool_views Surface; assistant: true further lets an
+      # assistant propose (never execute) it through that Surface. Neither adds
+      # authority: the current policy and a human confirmation still decide.
+      def operation(key, handler:, scope: :member, confirmation: :required, surface: false, assistant: false)
+        unless key.to_s.match?(/\A[a-z][a-z0-9_]*\z/) && !%w[index show create update destroy new edit].include?(key.to_s)
+          raise ConfigurationError, "Custom operation needs a distinct stable key"
+        end
+        unless handler.is_a?(String) && handler.match?(/\A[A-Z]\w*(?:::[A-Z]\w*)*\z/) && %i[member collection].include?(scope) && confirmation == :required
+          raise ConfigurationError, "Use a handler class-name string, member/collection scope and required confirmation"
+        end
+        raise ConfigurationError, "Duplicate operation #{key}" if @operations.key?(key.to_sym)
+        raise ConfigurationError, "Operation surface must be boolean and is only for member operations" unless [ true, false ].include?(surface) && (!surface || scope == :member)
+        raise ConfigurationError, "Operation assistant must be boolean and requires surface: true" unless [ true, false ].include?(assistant) && (!assistant || surface)
+        @operations[key.to_sym] = handler.freeze
+        @operation_scopes[key.to_sym] = scope
+        @surface_operations << key.to_sym if surface
+        @assistant_operations << key.to_sym if assistant
+      end
+
+      # A readonly child list on the show page. The child resource's own policy,
+      # index grant and a readable belongs_to field (via) decide what appears;
+      # declaring it grants nothing and adds no write path.
+      def has_many(name, resource: name, via: nil, label: nil, limit: 10)
+        definition = Presentation::AssociationPanel::Definition.build(name, resource: resource, via: via, label: label, limit: limit)
+        raise ConfigurationError, "Duplicate has_many #{definition.name}" if @has_many.key?(definition.name)
+        raise ConfigurationError, "A resource declares at most #{Presentation::AssociationPanel::MAX_PANELS} has_many panels" if @has_many.size >= Presentation::AssociationPanel::MAX_PANELS
+        @has_many[definition.name] = definition
+      end
+
+      # A readonly panel for the one child record that points back here (a
+      # model has_one). The same grants as has_many apply.
+      def has_one(name, resource: name.to_s.pluralize, via: nil, label: nil)
+        definition = Presentation::AssociationPanel::Definition.build(name, resource: resource, via: via, label: label, limit: 1, single: true)
+        raise ConfigurationError, "Duplicate association panel #{definition.name}" if @has_many.key?(definition.name)
+        raise ConfigurationError, "A resource declares at most #{Presentation::AssociationPanel::MAX_PANELS} association panels" if @has_many.size >= Presentation::AssociationPanel::MAX_PANELS
+        @has_many[definition.name] = definition
+      end
+
+      def has_many_declarations = @has_many.values
+
+      # Native changes the admin assistant may propose. Each proposal is shown
+      # as a review the human confirms; it runs with the human's own grants.
+      def assistant_changes(*actions)
+        return @assistant_changes if actions.empty?
+        actions = actions.map { |action| action.to_s.to_sym }
+        raise ConfigurationError, "assistant_changes accepts :create, :update and :destroy" unless (actions - %i[create update destroy]).empty?
+        @assistant_changes = (@assistant_changes | actions).freeze
+      end
+
+      def assistant_change?(action) = @assistant_changes.include?(action.to_s.to_sym) && action_enabled?(action)
+
+      def operation_declarations = @operations
+      def surface_operation?(key) = @surface_operations.include?(key.to_sym)
+      def assistant_operation?(key) = @assistant_operations.include?(key.to_sym)
+      def assistant_operations = @assistant_operations
+      def operation_scopes = @operation_scopes
+
+      def fields(&block)
+        FieldBuilder.new(@fields, source: self).instance_eval(&block) if block
+        @fields.values
+      end
+
+      # Overview widgets: metric counts over a list tab and daily trends over
+      # a date field. They read through the same grants as the list.
+      def dashboard(&block)
+        return @dashboard unless block
+        builder = Presentation::Dashboard::Builder.new
+        begin
+          builder.instance_eval(&block)
+        rescue NoMethodError => error
+          raise ConfigurationError, "Unknown dashboard option #{error.name}", cause: nil
+        end
+        @dashboard = builder.widgets.freeze
+      end
+
+      # Static index table presentation: column order, default sort, page size
+      # and count strategy. It is not part of operation or Selection identity.
+      def index(&block)
+        return @index unless block
+        raise ConfigurationError, "Index settings are declared twice" if @index_declared
+        builder = Presentation::IndexBuilder.new
+        begin
+          builder.instance_eval(&block)
+        rescue NoMethodError => error
+          raise ConfigurationError, "Unknown index option #{error.name}", cause: nil
+        end
+        @index = Presentation::IndexSettings.new(**builder.options)
+        @index_declared = true
+        @index
+      end
+
+      # Named list tabs narrow the policy relation; they never grant or widen it.
+      def scopes(&block)
+        ScopeBuilder.new(@scopes).instance_eval(&block) if block
+        @scopes.values
+      end
+
+      def model_class
+        raise ConfigurationError, "model must be a constant name string" unless model.is_a?(String)
+        klass = model.constantize
+        raise ConfigurationError, "model must inherit ActiveRecord::Base" unless klass < ActiveRecord::Base
+        klass
+      end
+
+      def validate!
+        raise ConfigurationError, "model must be a constant name string" unless model.is_a?(String)
+        if policy && (!policy.is_a?(String) || !policy.match?(/\A[A-Z]\w*(?:::[A-Z]\w*)*\z/))
+          raise ConfigurationError, "policy must be a constant name string"
+        end
+        raise ConfigurationError, "A resource must declare fields and a title" if fields.empty? || !title || !@fields.key?(title)
+        raise ConfigurationError, "A resource cannot declare lock_version as a field" if @fields.key?(:lock_version)
+        raise ConfigurationError, "A password field cannot be the title" if @fields[title].scalar_type == :password
+        Fields::DependencyGraph.validate!(fields)
+        index.validate!(fields)
+        Presentation::Dashboard.validate!(self)
+        # Fail at registration rather than on every menu render; explicit labels
+        # were already bounded when declared.
+        Navigation::Settings.caption(label) unless navigation.hidden || navigation.label
+        @policy_name&.freeze
+        @fields.freeze
+        @scopes.freeze
+        @disabled_actions.freeze
+        @operations.freeze
+        @operation_scopes.freeze
+        @surface_operations.freeze
+        @has_many.freeze
+        @assistant_operations.freeze
+        self
+      end
+    end
+
+    # Collects named list scopes. Bodies are not evaluated at declaration time.
+    class ScopeBuilder
+      def initialize(scopes)
+        @scopes = scopes
+      end
+
+      def scope(name, body = nil, label: nil, default: false)
+        definition = Queries::NamedScope.new(name, body, label: label, default: default)
+        raise ConfigurationError, "Duplicate named scope #{definition.name}" if @scopes.key?(definition.name)
+        raise ConfigurationError, "A resource declares at most #{Queries::NamedScope::MAX_SCOPES} named scopes" if @scopes.size >= Queries::NamedScope::MAX_SCOPES
+        raise ConfigurationError, "A resource declares at most one default named scope" if definition.default? && @scopes.values.any?(&:default?)
+        @scopes[definition.name] = definition
+      end
+    end
+
+    # Collects field declarations without consulting the database at boot.
+    class FieldBuilder
+      # source is the declaring Resource, consulted lazily for column limits.
+      def initialize(fields, source: nil)
+        @fields = fields
+        @source = source
+      end
+
+      def field(name, type:, **options)
+        raise ConfigurationError, "Duplicate field #{name}" if @fields.key?(name.to_sym)
+        @fields[name.to_sym] = RailsAiAdmin.field_registry.build(name, type: type, source: @source, **options)
+      end
+
+      def virtual(name, type:, depends_on:, compute:, **options)
+        field(name, type: type, compute: compute, depends_on: depends_on, **options)
+      end
+
+      def readonly(name, type: :text, **options)
+        field(name, type: type, **options.merge(readonly: true))
+      end
+
+      Field::TYPES.each do |type|
+        define_method(type) { |name, **options| field(name, type: type, **options) }
+      end
+    end
+  end
+end

data/lib/rails_ai_admin/resource_identity.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  # Stable across processes, but changes when a model's record IDs change meaning.
+  module ResourceIdentity
+    def self.call(resource)
+      model = resource.model_class
+      primary_key = model.primary_key
+      column = primary_key.is_a?(String) ? model.columns_hash[primary_key] : nil
+      { model: resource.model, table: model.table_name, primary_key: primary_key,
+        column_type: column&.type, sql_type: column&.sql_type,
+        attribute_type: primary_key.is_a?(String) ? model.type_for_attribute(primary_key).type : nil }
+    end
+  end
+end