rails_ai_admin 0.1.0

data/lib/rails_ai_admin/schema_suggestions.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  # Reads schema metadata only. Suggestions never register or expose a field.
+  class SchemaSuggestions
+    Suggestion = Data.define(:name, :type, :options) do
+      def declaration
+        suffix = options.map { |key, value| ", #{key}: #{value.inspect}" }.join
+        "#{type} :#{name}#{suffix}"
+      end
+    end
+    Report = Data.define(:suggestions, :omitted, :available)
+    TYPES = { string: :text, text: :textarea, integer: :integer, decimal: :decimal,
+      boolean: :boolean, date: :date, datetime: :datetime, timestamp: :datetime, time: :time,
+      json: :json, jsonb: :json }.freeze
+    EMAIL_NAME = /(?:\A|_)email(?:_address)?\z/
+    URL_NAME = /(?:\A|_)(?:url|website|homepage)\z/
+    # Heuristics are a conservative starting point, never a sensitivity proof.
+    SENSITIVE = /password|token|secret|credential|ciphertext|encrypted|(?:\A|_)(?:api_key|private_key|access_key|signing_key|otp|ssn|salt|session|digest|role|roles|permission|permissions|security_version|admin|superuser)(?:_|\z)|_digest\z/i
+    IDENTIFIER = /\A[a-z][a-z0-9_]*\z/
+    # Reassigning a tenant is an authority change, so tenant-like references are
+    # never suggested, even as comments.
+    TENANT = /\A(?:account|tenant|organization|organisation|workspace|company|team)\z/
+
+    def self.sensitive?(model, name)
+      encrypted = model.respond_to?(:encrypted_attributes) ? model.encrypted_attributes : []
+      name.to_s.match?(SENSITIVE) || Array(encrypted&.to_a).map(&:to_s).include?(name.to_s)
+    end
+
+    def self.array?(column)
+      column.respond_to?(:array) && column.array
+    end
+
+    def initialize(model)
+      @model = model
+    end
+
+    def call
+      return unavailable unless @model.is_a?(Class) && @model < ActiveRecord::Base
+      columns = @model.columns
+      foreign_keys = @model.reflect_on_all_associations(:belongs_to).flat_map { |association| Array(association.foreign_key) }.map(&:to_s)
+      foreign_keys.concat(@model.reflect_on_all_associations(:belongs_to).filter_map { |association| association.foreign_type if association.polymorphic? })
+      foreign_keys.concat(@model.connection.foreign_keys(@model.table_name).flat_map { |foreign_key| Array(foreign_key.column) }.map(&:to_s))
+      # A declared non-polymorphic belongs_to may become a commented reference.
+      references = @model.reflect_on_all_associations(:belongs_to).reject(&:polymorphic?).to_h { |association| [ association.foreign_key.to_s, association ] }
+      omitted = 0
+      suggestions = columns.filter_map do |column|
+        name = column.name
+        next if name == @model.primary_key || name == "id"
+        if (reference = suggest_reference(references[name], column))
+          next reference
+        end
+        if !name.match?(IDENTIFIER) || [ "lock_version", @model.inheritance_column ].include?(name) || name.end_with?("_id") || foreign_keys.include?(name) || self.class.sensitive?(@model, name) || self.class.array?(column)
+          omitted += 1
+          next
+        end
+        type = TYPES[column.type]
+        unless type
+          omitted += 1
+          next
+        end
+        options = {}
+        enum = @model.defined_enums[name]
+        if enum && (!enum.keys.all? { |value| value.length <= 100 } || !enum.size.between?(1, 100))
+          omitted += 1
+          next
+        end
+        type = :email if type == :text && name.match?(EMAIL_NAME)
+        type = :url if type == :text && name.match?(URL_NAME)
+        if enum
+          type = :enum
+          options[:values] = enum.keys
+        end
+        options[:nullable] = false unless column.null
+        options[:max_length] = column.limit if %i[text textarea email url].include?(type) && column.limit.is_a?(Integer) && column.limit.positive?
+        # Explicit limits keep the declaration reviewable; coercion would
+        # otherwise read the same values from the column on first use.
+        if type == :decimal && column.precision.is_a?(Integer) && column.precision.between?(1, 1000)
+          options[:precision] = column.precision
+          options[:scale] = column.scale if column.scale.is_a?(Integer) && column.scale.between?(0, column.precision)
+        end
+        options[:readonly] = true if %w[created_at updated_at].include?(name)
+        Suggestion.new(name, type, options.freeze)
+      end
+      Report.new(suggestions.freeze, omitted, true)
+    rescue ActiveRecord::ActiveRecordError
+      unavailable
+    end
+
+    private
+
+    def suggest_reference(association, column)
+      return unless association && association.name.to_s.match?(IDENTIFIER) && column.name.match?(IDENTIFIER)
+      return if association.name.to_s.match?(TENANT) || self.class.sensitive?(@model, association.name) || self.class.sensitive?(@model, column.name)
+      options = {}
+      options[:foreign_key] = column.name unless column.name == "#{association.name}_id"
+      options[:nullable] = false unless column.null
+      Suggestion.new(association.name.to_s, :belongs_to, options.freeze)
+    end
+
+    def unavailable
+      Report.new([].freeze, 0, false)
+    end
+  end
+end

data/lib/rails_ai_admin/selections/builder.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module RailsAiAdmin
+  module Selections
+    # Captures exact scoped targets; never saves a query to expand during execution.
+    class Builder
+      LIMIT = 100
+      Target = Data.define(:id, :expected_version, :label)
+      Snapshot = Data.define(:selection_ref, :resource_key, :manifest_digest, :expires_at, :targets)
+
+      def capture(context:, resource:, target_ids:)
+        access = Authorization::Access.new(context, resource)
+        raise AccessDenied unless RailsAiAdmin.registry.fetch(resource.key).equal?(resource)
+        ensure_storage!(resource)
+        targets = ActiveRecord::Base.while_preventing_writes do
+          access.authorize_selection!
+          ids = canonical_ids(resource, target_ids)
+          records = scoped_records(access, ids)
+          records.map { |record| target(access, record) }.sort_by(&:id).freeze
+        end
+        version = resource_version(resource)
+        selection = Selection.transaction(requires_new: true) do
+          row = Selection.create!(id: SecureRandom.uuid, actor_ref: context.actor_ref, tenant_ref: context.tenant_ref,
+            security_version: context.security_version, resource_key: resource.key.to_s, resource_version: version,
+            manifest_digest: manifest_digest(version, targets), item_count: targets.size,
+            expires_at: Time.current + RailsAiAdmin.configuration.intent_ttl)
+          SelectionItem.insert_all!(targets.each_with_index.map { |item, position| { selection_id: row.id,
+            target_id: item.id, expected_version: item.expected_version, position: position } })
+          row
+        end
+        raise ConfigurationError, "Selection creation was rolled back" unless selection
+        snapshot(selection, targets)
+      rescue ActiveRecord::ReadOnlyError
+        raise ConfigurationError, "Selection lookup must be read-only", cause: nil
+      end
+
+      # This is a fresh check, not a lock or authorization for a later write.
+      # Execution must bind this digest and recheck each item in its transaction.
+      # A block receives each current record, inside the same read-only check.
+      def revalidate(context:, selection_ref:, resource: nil, manifest_digest: nil, &block)
+        read_snapshot(context: context, selection_ref: selection_ref, resource: resource, manifest_digest: manifest_digest, labels: true, &block)
+      end
+
+      # Internal admission path: no title projection or domain preflight under
+      # the parent lock. Only exact target checks and the given authorization run.
+      def validate_for_admission(context:, selection_ref:, resource:, manifest_digest:, &authorize_target)
+        read_snapshot(context: context, selection_ref: selection_ref, resource: resource, manifest_digest: manifest_digest, labels: false, &authorize_target)
+      end
+
+      private
+
+      def read_snapshot(context:, selection_ref:, resource:, manifest_digest:, labels:)
+        raise AccessDenied, "UNAUTHENTICATED" unless context.is_a?(Context)
+        unless selection_ref.is_a?(String) && selection_ref.match?(/\A[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}\z/)
+          raise AccessDenied
+        end
+        selection = Selection.find_by(id: selection_ref, actor_ref: context.actor_ref, tenant_ref: context.tenant_ref)
+        raise AccessDenied unless selection
+        raise AccessDenied, "SELECTION_INVALIDATED" unless selection.security_version == context.security_version
+        raise AccessDenied, "SELECTION_EXPIRED" unless selection.expires_at > Time.current
+        registered = RailsAiAdmin.registry.fetch(selection.resource_key)
+        raise AccessDenied unless resource.nil? || registered.equal?(resource)
+        ensure_storage!(registered)
+        raise AccessDenied, "SELECTION_INVALIDATED" unless selection.resource_version == resource_version(registered)
+        items = SelectionItem.where(selection_id: selection.id).order(:position).limit(LIMIT + 1).to_a
+        verify_manifest!(selection, items)
+        raise AccessDenied, "SELECTION_INVALIDATED" if manifest_digest && manifest_digest != selection.manifest_digest
+        access = Authorization::Access.new(context, registered)
+        targets = ActiveRecord::Base.while_preventing_writes do
+          access.authorize_selection!
+          records = scoped_records(access, items.map(&:target_id)).index_by { |record| record.id.to_s }
+          items.map do |item|
+            record = records.fetch(item.target_id)
+            access.authorize!(:show, record)
+            raise AccessDenied, "CONFLICT" unless RecordVersion.of(record) == item.expected_version
+            value = target(access, record, labels: labels, authorized: true)
+            yield record if block_given?
+            value
+          end.freeze
+        end
+        snapshot(selection, targets)
+      rescue ActiveRecord::ReadOnlyError
+        raise ConfigurationError, "Selection lookup must be read-only", cause: nil
+      end
+
+      private
+
+      def ensure_storage!(resource)
+        model = resource.model_class
+        unless [ Selection, SelectionItem ].all? { |klass| klass.connection_pool.equal?(model.connection_pool) } &&
+            RecordVersion.supported?(model) &&
+            %w[SQLite PostgreSQL].include?(model.connection.adapter_name)
+          raise ConfigurationError, "Selections require one SQLite/PostgreSQL pool, a single primary key and lock_version or updated_at"
+        end
+      end
+
+      def canonical_ids(resource, values)
+        unless values.is_a?(Array) && values.size.between?(1, LIMIT)
+          raise AccessDenied, "INVALID_QUERY"
+        end
+        type = resource.model_class.type_for_attribute(resource.model_class.primary_key)
+        unless %i[integer string uuid].include?(type.type)
+          raise ConfigurationError, "Selection primary keys must be integer, string or UUID"
+        end
+        ids = values.map do |value|
+          unless (value.is_a?(String) || value.is_a?(Integer)) && value.to_s.bytesize.between?(1, 150) && !value.to_s.match?(/[[:cntrl:]]/) &&
+              (type.type != :integer || value.to_s.match?(/\A[+-]?\d+\z/))
+            raise AccessDenied, "INVALID_QUERY"
+          end
+          cast = type.cast(value)
+          raise AccessDenied, "INVALID_QUERY" if cast.nil? || cast.to_s.bytesize > 150
+          cast.to_s
+        end
+        # A repeated box (or "1" and "01") is one target, not an invalid query (RAA-013).
+        ids.uniq
+      end
+
+      def scoped_records(access, ids)
+        model = access.resource.model_class
+        primary_key = model.arel_table[model.primary_key]
+        authorized_ids = access.relation.where(primary_key.in(ids)).reorder(nil).select(primary_key).distinct
+        # Reconstitute only IDs selected by the complete authorized relation.
+        # DISTINCT on model.* fails for PostgreSQL JSON columns; deduplicate IDs
+        # inside the scoped subquery before applying the outer bound instead.
+        records = model.unscoped.where(model.primary_key => authorized_ids).order(primary_key.asc).limit(LIMIT + 1).to_a
+        raise AccessDenied unless records.map { |record| record.id.to_s }.sort == ids.sort
+        records
+      end
+
+      def target(access, record, labels: true, authorized: false)
+        access.authorize!(:show, record) unless authorized
+        version = RecordVersion.of(record)
+        raise ConfigurationError, "Selection versions must be nonnegative integers" unless version.is_a?(Integer) && version >= 0
+        label = labels ? access.record_label(record) : "Record ##{record.id}"
+        Target.new(record.id.to_s.freeze, version, label.freeze)
+      end
+
+      def resource_version(resource)
+        InputSchema.digest(key: resource.key, identity: ResourceIdentity.call(resource), policy: resource.policy, readonly: resource.readonly?,
+          adapter: RailsAiAdmin.configuration.authorization_adapter, fields: resource.fields.map(&:contract))
+      end
+
+      def manifest_digest(version, targets)
+        InputSchema.digest(resource_version: version, targets: targets.map { |item| [ item.id, item.expected_version ] })
+      end
+
+      def verify_manifest!(selection, items)
+        unless selection.item_count.between?(1, LIMIT) && items.size == selection.item_count && items.map(&:position) == (0...items.size).to_a &&
+            items.map(&:target_id).uniq.size == items.size && selection.manifest_digest == InputSchema.digest(resource_version: selection.resource_version,
+              targets: items.map { |item| [ item.target_id, item.expected_version ] })
+          raise ConfigurationError, "Selection manifest is inconsistent"
+        end
+      end
+
+      def snapshot(selection, targets)
+        Snapshot.new(selection.id.freeze, selection.resource_key.freeze, selection.manifest_digest.freeze, selection.expires_at, targets)
+      end
+    end
+  end
+end

data/lib/rails_ai_admin/templates/catalog.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module RailsAiAdmin
+  module Templates
+    # Explicit public presentation paths. Revision changes track context/locals
+    # compatibility even when the template bytes themselves do not change.
+    class Catalog
+      Entry = Data.define(:key, :path, :revision, :assigns, :locals)
+      DEFINITIONS = {
+        "layout" => [ "layouts/rails_ai_admin/application.html.erb", %i[context admin_csp_nonce], [] ],
+        "status_layout" => [ "layouts/rails_ai_admin/status.html.erb", %i[admin_status], [] ],
+        "status_page" => [ "rails_ai_admin/statuses/show.html.erb", %i[admin_status status_sign_in_path], [] ],
+        "session_links" => [ "rails_ai_admin/shared/_session.html.erb", %i[context], [] ],
+        "resource_navigation" => [ "rails_ai_admin/shared/_navigation.html.erb", [], %i[groups] ],
+        "dashboard" => [ "rails_ai_admin/dashboard/index.html.erb", %i[context counts widgets], [] ],
+        "audit_log" => [ "rails_ai_admin/audit/index.html.erb", %i[context log filters page actor_labels], [] ],
+        "resource_import" => [ "rails_ai_admin/imports/new.html.erb", %i[context resource import report problem], [] ],
+        "search" => [ "rails_ai_admin/search/index.html.erb", %i[context query sections], [] ],
+        "resource_index" => [ "rails_ai_admin/resources/index.html.erb", %i[context resource page columns rows searchable selectable exportable importable sortable_fields list_scopes current_scope filter_fields omitted_rows], [] ],
+        "resource_show" => [ "rails_ai_admin/resources/show.html.erb", %i[context resource record values fields operations association_panels], [] ],
+        "resource_history" => [ "rails_ai_admin/resources/history.html.erb", %i[context resource record history actor_labels], [] ],
+        "resource_associations" => [ "rails_ai_admin/resources/_associations.html.erb", [], %i[panels] ],
+        "resource_new" => [ "rails_ai_admin/resources/new.html.erb", %i[context resource record operation intent_ref form_fields form_values form_plan errors failure_code needs_reload], [] ],
+        "resource_edit" => [ "rails_ai_admin/resources/edit.html.erb", %i[context resource record operation intent_ref form_fields form_values form_plan errors failure_code needs_reload], [] ],
+        "resource_form" => [ "rails_ai_admin/resources/form.html.erb", %i[context resource record operation intent_ref form_fields form_values form_plan errors failure_code needs_reload], [] ],
+        "resource_destroy" => [ "rails_ai_admin/resources/confirm_destroy.html.erb", %i[context resource record intent_ref errors failure_code needs_reload], [] ],
+        "form_recovery" => [ "rails_ai_admin/resources/_recovery.html.erb", [], [] ],
+        "resource_errors" => [ "rails_ai_admin/resources/_errors.html.erb", %i[errors failure_code needs_reload], %i[form fields] ],
+        "field_index" => [ "rails_ai_admin/fields/_index.html.erb", [], %i[field value text] ],
+        "field_show" => [ "rails_ai_admin/fields/_show.html.erb", [], %i[field value text] ],
+        "field_reference" => [ "rails_ai_admin/fields/_reference.html.erb", [], %i[field value reference] ],
+        "field_form" => [ "rails_ai_admin/fields/_input.html.erb", [], %i[field form value input_options] ],
+        "field_row" => [ "rails_ai_admin/fields/_row.html.erb", [], %i[form entry errors] ],
+        "input_fields" => [ "rails_ai_admin/shared/_input_fields.html.erb", %i[resource], %i[form fields values errors plan] ],
+        "operation_form" => [ "rails_ai_admin/operations/form.html.erb", %i[context resource record definition flow_id form_fields form_values errors failure_code needs_reload], [] ],
+        "operation_confirmation" => [ "rails_ai_admin/operations/confirmation.html.erb", %i[context resource record definition flow_id proposal form_fields form_values wire_input], [] ],
+        "operation_failure" => [ "rails_ai_admin/operations/failure.html.erb", %i[context resource failure_code], [] ],
+        "collection_form" => [ "rails_ai_admin/collection_operations/new.html.erb", %i[context resource definition selection form_fields form_values errors failure_code], [] ],
+        "collection_confirmation" => [ "rails_ai_admin/collection_operations/confirmation.html.erb", %i[context resource definition proposal wire_input], [] ],
+        "collection_failure" => [ "rails_ai_admin/collection_operations/failure.html.erb", %i[context resource failure_code uncertain_job_ref], [] ],
+        "job_index" => [ "rails_ai_admin/collection_jobs/index.html.erb", %i[context jobs], [] ],
+        "job_show" => [ "rails_ai_admin/collection_jobs/show.html.erb", %i[context resource job], [] ],
+        "selection" => [ "rails_ai_admin/selections/show.html.erb", %i[context resource selection operations deletable], [] ],
+        "selection_destroy" => [ "rails_ai_admin/selections/confirm_destroy.html.erb", %i[context resource selection deletable skipped], [] ],
+        "selection_destroy_result" => [ "rails_ai_admin/selections/destroyed.html.erb", %i[context resource selection deleted skipped failed], [] ]
+      }.freeze
+      ENTRIES = DEFINITIONS.map do |key, (path, assigns, locals)|
+        navigation = %w[layout resource_index resource_show resource_history resource_new resource_edit resource_form resource_destroy operation_form operation_confirmation operation_failure collection_form collection_confirmation collection_failure job_show selection selection_destroy selection_destroy_result].include?(key)
+        assigns += [ :list_navigation ] if navigation
+        revision = if key == "layout"
+          4 # page titles, environment label and the session_links slot (RAA-024)
+        elsif key == "dashboard"
+          4 # counts, widgets
+        elsif key == "resource_index"
+          8 # exportable, importable (CSV)
+        elsif key == "resource_show"
+          3
+        elsif %w[resource_new resource_edit resource_form].include?(key)
+          5 # intent_ref replaces intent (ADR 0025)
+        elsif %w[resource_destroy resource_errors].include?(key)
+          3 # intent_ref; outcome sentences and RESTRICTED
+        elsif navigation || %w[input_fields field_form].include?(key)
+          2
+        else
+          1
+        end
+        Entry.new(key.freeze, path.freeze, revision, assigns.freeze, locals.freeze)
+      end.freeze
+
+      def initialize(source_root: Engine.root.join("app/views"), entries: ENTRIES)
+        @source_root = Pathname.new(source_root).expand_path
+        @entries = entries.freeze
+      end
+
+      def entries = @entries
+      def fetch(key) = entries.find { |entry| entry.key == key.to_s } || raise(ConfigurationError, "Unknown override key; use --list")
+      def for_path(path) = entries.find { |entry| entry.path == path }
+      def source_path(entry) = @source_root.join(entry.path)
+      def source_digest(entry) = Digest::SHA256.file(source_path(entry)).hexdigest
+    end
+  end
+end

data/lib/rails_ai_admin/templates/inspector.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "rails_ai_admin/templates/catalog"
+require "rails_ai_admin/templates/metadata"
+require "rails_ai_admin/templates/safe_paths"
+
+module RailsAiAdmin
+  module Templates
+    class Inspector
+      Finding = Data.define(:key, :status, :code, :path, :source_version)
+      MAX_FILES = 256
+      MAX_ENTRIES = 1024
+
+      def initialize(root:, catalog: Catalog.new, max_files: MAX_FILES, max_entries: MAX_ENTRIES)
+        unless max_files.is_a?(Integer) && max_files.between?(1, MAX_FILES) && max_entries.is_a?(Integer) && max_entries.between?(1, MAX_ENTRIES)
+          raise ConfigurationError, "Override inspection bounds may only narrow the defaults"
+        end
+        @root, @catalog = Pathname.new(root).realpath, catalog
+        @max_files, @max_entries = max_files, max_entries
+      end
+
+      def checks
+        @findings, @visited, @files = [], 0, 0
+        catch(:limit) do
+          %w[rails_ai_admin layouts/rails_ai_admin].each do |namespace|
+            path = @root.join("app/views", namespace)
+            begin
+              SafePaths.check!(@root, path)
+              next unless path.exist?
+              raise ConfigurationError unless path.directory?
+              walk(path)
+            rescue ConfigurationError, SystemCallError
+              @findings << Finding.new(namespace, :error, "UNSAFE_PATH", "app/views/#{namespace}", nil)
+            end
+          end
+        end
+        @findings.sort_by(&:key).freeze
+      end
+
+      private
+
+      def walk(directory)
+        Dir.each_child(directory) do |name|
+          path = directory.join(name)
+          @visited += 1
+          incomplete! if @visited > @max_entries
+          stat = path.lstat
+          if stat.directory?
+            if @catalog.for_path(path.relative_path_from(@root.join("app/views")).to_s)
+              relative = path.relative_path_from(@root).to_s
+              @findings << Finding.new(relative, :error, "UNSAFE_PATH", relative, nil)
+            else
+              walk(path)
+            end
+          elsif stat.symlink? || !stat.file?
+            relative = path.relative_path_from(@root).to_s
+            @findings << Finding.new(relative, :error, "UNSAFE_PATH", relative, nil)
+          elsif path.basename.to_s.end_with?(".html.erb")
+            @files += 1
+            incomplete! if @files > @max_files
+            @findings << inspect_file(path)
+          end
+        end
+      end
+
+      def incomplete!
+        @findings << Finding.new("inventory", :review, "INCOMPLETE", "app/views", nil)
+        throw :limit
+      end
+
+      def inspect_file(path)
+        relative = path.relative_path_from(@root.join("app/views")).to_s
+        entry = @catalog.for_path(relative)
+        key = entry&.key || relative
+        return Finding.new(key, :review, "UNCATALOGED", "app/views/#{relative}", nil) unless entry
+        SafePaths.check!(@root, path)
+        metadata = Metadata.read(path, entry)
+        return Finding.new(key, :review, "UNTRACKED", "app/views/#{relative}", nil) unless metadata
+        code, status = if metadata["contract"] != entry.revision
+          [ "STALE_CONTRACT", :review ]
+        elsif metadata["source_sha256"] != @catalog.source_digest(entry)
+          [ "STALE_SOURCE", :review ]
+        else
+          [ "CURRENT", :ok ]
+        end
+        Finding.new(key, status, code, "app/views/#{relative}", metadata["gem_version"])
+      rescue ConfigurationError, JSON::ParserError
+        Finding.new(key, :error, "INVALID_HEADER", "app/views/#{relative}", nil)
+      rescue SystemCallError
+        Finding.new(key, :error, "UNSAFE_PATH", "app/views/#{relative}", nil)
+      end
+    end
+  end
+end

data/lib/rails_ai_admin/templates/metadata.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "json"
+require "rails_ai_admin/version"
+
+module RailsAiAdmin
+  module Templates
+    module Metadata
+      PREFIX = "<%# rails_ai_admin:override "
+      MAX_BYTES = 1024
+      KEYS = %w[format key gem_version source_sha256 contract].freeze
+      class HeaderObject < Hash
+        def []=(key, value)
+          raise JSON::ParserError, "Duplicate metadata key" if key?(key)
+          super
+        end
+      end
+
+      def self.line(entry, catalog)
+        data = { "format" => 1, "key" => entry.key, "gem_version" => VERSION,
+          "source_sha256" => catalog.source_digest(entry), "contract" => entry.revision }
+        "#{PREFIX}#{JSON.generate(data)} %>\n"
+      end
+
+      def self.read(path, entry)
+        flags = File::RDONLY
+        flags |= File::NOFOLLOW if File.const_defined?(:NOFOLLOW)
+        line = File.open(path, flags) { |file| file.gets("\n", MAX_BYTES + 1) }.to_s.force_encoding(Encoding::UTF_8)
+        return unless line.b.start_with?(PREFIX.b)
+        raise ConfigurationError, "Invalid override header" if line.bytesize > MAX_BYTES || !line.valid_encoding?
+        json = line.match(/\A<%# rails_ai_admin:override (\{.*\}) %>\r?\n?\z/)&.captures&.first
+        raise ConfigurationError, "Invalid override header" unless json
+        # json 2.x builds objects without HeaderObject#[]=, so the parser's own
+        # duplicate check is what rejects a repeated key there.
+        data = JSON.parse(json, object_class: HeaderObject, max_nesting: 2, allow_duplicate_key: false)
+        unless data.keys.sort == KEYS.sort && data["format"].is_a?(Integer) && data["format"] == 1 && data["key"] == entry.key &&
+            data["contract"].is_a?(Integer) && data["contract"].between?(1, 1_000_000) &&
+            data["source_sha256"].is_a?(String) && data["source_sha256"].match?(/\A[0-9a-f]{64}\z/) &&
+            data["gem_version"].is_a?(String) && data["gem_version"].match?(/\A[0-9a-zA-Z][0-9a-zA-Z.-]{0,63}\z/) && Gem::Version.correct?(data["gem_version"])
+          raise ConfigurationError, "Invalid override header"
+        end
+        data.freeze
+      rescue JSON::ParserError, EncodingError
+        raise ConfigurationError, "Invalid override header", cause: nil
+      end
+    end
+  end
+end

data/lib/rails_ai_admin/templates/safe_paths.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  module Templates
+    module SafePaths
+      # Do not follow existing parent/leaf symlinks, including dangling links.
+      # The host root itself is explicitly selected and resolved by its owner.
+      def self.check!(root, path)
+        requested_root = Pathname.new(root).expand_path
+        relative = Pathname.new(path).expand_path.relative_path_from(requested_root)
+        root = requested_root.realpath
+        raise ConfigurationError, "Override path is outside host root" if relative.each_filename.any? { |part| part == ".." }
+        parts = relative.each_filename.to_a
+        current = root
+        parts.each_with_index do |part, index|
+          current = current.join(part)
+          begin
+            stat = current.lstat
+          rescue Errno::ENOENT
+            next
+          end
+          if stat.symlink? || index < parts.size - 1 && !stat.directory?
+            raise ConfigurationError, "Override path contains a symlink or invalid parent"
+          end
+        end
+        root.join(relative)
+      end
+    end
+  end
+end

data/lib/rails_ai_admin/test_kit.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "rails_ai_admin"
+
+module RailsAiAdmin
+  # Framework-neutral host assertions. Raises AssertionError without Minitest/RSpec.
+  module TestKit
+    class AssertionError < StandardError; end
+    FIELD_ACTIONS = %i[read write search sort filter].freeze
+
+    # Supply a host controller/request representing an anonymous session. This
+    # checks the adapter contract; also test the real anonymous HTTP entry point.
+    def self.assert_unauthenticated(adapter:, controller:)
+      raise AssertionError, "Anonymous context must resolve to nil" unless adapter.resolve(controller).nil?
+      true
+    end
+
+    # Snapshots independent field grants, intersected with DSL flags. No record
+    # values are returned. Action permission and SQL membership are separate.
+    def self.field_grants(context:, resource:, record: nil, operation: :update)
+      raise ArgumentError, "Use create or update field grants" unless %w[create update].include?(operation.to_s)
+      access = Authorization::Access.new(context, resource)
+      FIELD_ACTIONS.to_h do |action|
+        [ action.to_s, access.fields(action, record, operation: operation).map { |field| field.name.to_s }.sort ]
+      end
+    end
+
+    def self.assert_field_grants(context:, resource:, expected:, record: nil, operation: :update)
+      unless expected.is_a?(Hash) && expected.keys.map(&:to_s).sort == FIELD_ACTIONS.map(&:to_s).sort && expected.values.all? { |names| names.is_a?(Array) }
+        raise ArgumentError, "Expected read/write/search/sort/filter arrays"
+      end
+      normalized = expected.to_h { |action, names| [ action.to_s, names.map(&:to_s).sort ] }
+      actual = field_grants(context: context, resource: resource, record: record, operation: operation)
+      differences = FIELD_ACTIONS.map(&:to_s).select { |action| actual.fetch(action) != normalized.fetch(action) }
+      raise AssertionError, "Field grants differ for #{resource.key}: #{differences.join(', ')}" if differences.any?
+      true
+    end
+
+    # Declared named scopes currently granted to this context, sorted by name.
+    def self.named_scope_grants(context:, resource:)
+      Authorization::Access.new(context, resource).named_scopes.map { |definition| definition.name.to_s }.sort
+    end
+
+    def self.assert_named_scopes(context:, resource:, expected:)
+      raise ArgumentError, "Expected an array of scope names" unless expected.is_a?(Array)
+      actual = named_scope_grants(context: context, resource: resource)
+      unless actual == expected.map(&:to_s).sort
+        raise AssertionError, "Named scope grants differ for #{resource.key}: expected #{expected.map(&:to_s).sort.inspect}, got #{actual.inspect}"
+      end
+      true
+    end
+
+    def self.assert_access(context:, resource:, action:, allowed:, record: nil)
+      access = Authorization::Access.new(context, resource)
+      actual = begin
+        access.authorize!(action, record)
+        true
+      rescue AccessDenied
+        false
+      end
+      raise AssertionError, "Expected #{resource.key}.#{action} allowed=#{allowed}, got #{actual}" unless actual == allowed
+      true
+    end
+
+    def self.assert_isolated(context:, resource:, foreign_id:)
+      access = Authorization::Access.new(context, resource)
+      raise AssertionError, "Policy scope includes another tenant's record" if access.relation.where(resource.model_class.primary_key => foreign_id).exists?
+      true
+    end
+
+    # The policy scope and the record-level show decision should agree: list
+    # pages omit in-scope records whose show is denied (RAA-001), which reads as
+    # missing data. Checks up to sample records in primary-key order and names
+    # only how many disagree, never their content.
+    def self.assert_scope_matches_show(context:, resource:, sample: 100)
+      raise ArgumentError, "sample must be between 1 and 1000" unless sample.is_a?(Integer) && sample.between?(1, 1000)
+      access = Authorization::Access.new(context, resource)
+      model = resource.model_class
+      records = access.relation.reorder(model.arel_table[model.primary_key].asc).limit(sample).to_a
+      denied = records.count do |record|
+        access.authorize!(:show, record)
+        false
+      rescue AccessDenied
+        true
+      end
+      if denied.positive?
+        raise AssertionError, "#{denied} of #{records.size} sampled #{resource.key} records are in the policy scope but deny show; " \
+          "narrow the scope or allow show so list pages do not omit them"
+      end
+      true
+    end
+
+    def self.assert_hidden(context:, resource:, field:, actions: FIELD_ACTIONS, record: nil)
+      access = Authorization::Access.new(context, resource)
+      actions.each do |action|
+        if access.fields(action, record).any? { |entry| entry.name == field.to_sym }
+          raise AssertionError, "#{field} is exposed through #{action}"
+        end
+      end
+      true
+    end
+  end
+end

data/lib/rails_ai_admin/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  VERSION = "0.1.0"
+end