rails_ai_admin 0.1.0

data/lib/rails_ai_admin/fields/association.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  module Fields
+    # Resolves belongs_to references only through the target resource's current
+    # policy relation, record show grant and title. A target that is missing, in
+    # another tenant or not shown to this actor is indistinguishable: pages show
+    # only the already-readable key, and writes reject it with one message.
+    #
+    # One instance is a request-local cache. It never survives authentication.
+    class Association
+      MAX_CHOICES = 100
+      MAX_BATCH = 500
+      UNAVAILABLE = "is not an available choice"
+      INTEGER_KEY = /\A[1-9]\d{0,18}\z/
+      # visible is true only for a target in the current relation with a show grant.
+      Reference = Data.define(:id, :label, :resource_key, :visible)
+      # complete is false when the picker would exceed MAX_CHOICES or the actor
+      # cannot list the target resource; forms then accept a typed key instead.
+      Choices = Data.define(:options, :complete)
+
+      class << self
+        def target(field, registry: RailsAiAdmin.registry)
+          raise ConfigurationError, "Expected a belongs_to or references field" unless field.is_a?(Field) && Field::REFERENCE_TYPES.include?(field.scalar_type)
+          key = field.options.fetch(:resource).to_s
+          registry.resources.find { |resource| resource.key.to_s == key } ||
+            raise(ConfigurationError, "belongs_to #{field.name} names an unregistered resource")
+        end
+
+        # The declaration must match a non-polymorphic model belongs_to whose
+        # foreign key is the declared column and whose primary key is the target
+        # resource's single primary key. Nothing here queries domain rows.
+        def validate!(resource, field, registry: RailsAiAdmin.registry)
+          target = target(field, registry: registry)
+          return validate_collection!(resource, field, target) if field.scalar_type == :references
+          target_model = target.model_class
+          reflection = resource.model_class.reflect_on_association(field.name)
+          valid = reflection && reflection.macro == :belongs_to && !reflection.polymorphic? &&
+            reflection.foreign_key.to_s == field.column && target_model.primary_key.is_a?(String) &&
+            reflection.klass == target_model && reflection.association_primary_key.to_s == target_model.primary_key
+          unless valid
+            raise ConfigurationError, "belongs_to #{field.name} must match a non-polymorphic model association on #{field.column} to the #{target.key} primary key"
+          end
+          target
+        rescue NameError, ArgumentError
+          raise ConfigurationError, "belongs_to #{field.name} could not resolve its model association", cause: nil
+        end
+
+        # A references field must match a non-polymorphic has_many (including
+        # through) or has_and_belongs_to_many to the target model, whose
+        # <singular>_ids writer is the declared foreign_key.
+        def validate_collection!(resource, field, target)
+          target_model = target.model_class
+          reflection = resource.model_class.reflect_on_association(field.name)
+          valid = reflection && %i[has_many has_and_belongs_to_many].include?(reflection.macro) && !reflection.polymorphic? &&
+            reflection.klass == target_model && target_model.primary_key.is_a?(String) &&
+            "#{reflection.name.to_s.singularize}_ids" == field.column && resource.model_class.method_defined?("#{field.column}=")
+          unless valid
+            raise ConfigurationError, "references #{field.name} must match a has_many or has_and_belongs_to_many association to the #{target.key} model with #{field.column}"
+          end
+          target
+        rescue NameError, ArgumentError
+          raise ConfigurationError, "references #{field.name} could not resolve its model association", cause: nil
+        end
+      end
+
+      # resource: the declaring resource. Its own fields are checked against the
+      # model reflection; operation input fields only need a registered target.
+      def initialize(context, resource = nil)
+        raise AccessDenied, "UNAUTHENTICATED" unless context.is_a?(Context)
+        @context, @resource = context, resource
+        @accesses = {}
+        @references = Hash.new { |hash, key| hash[key] = {} }
+      end
+
+      # Loads every unresolved key for field with one bounded target query, so
+      # an index page costs one query per association column, not per row.
+      def prime(field, ids)
+        cache = @references[cache_key(field)]
+        pending = ids.compact.map(&:to_s).uniq.reject { |id| cache.key?(id) }
+        return self if pending.empty?
+        raise ConfigurationError, "Too many references to resolve at once" if pending.size > MAX_BATCH
+        access = target_access(field)
+        model = access.resource.model_class
+        keys = pending.select { |id| key_shape?(model, id) }
+        found = keys.empty? ? {} : access.relation.where(model.primary_key => keys).to_a.index_by { |record| record.id.to_s }
+        pending.each { |id| cache[id] = build(field, access, found[id], id) }
+        self
+      end
+
+      def reference(field, id)
+        return if id.nil?
+        prime(field, [ id ])
+        @references[cache_key(field)].fetch(id.to_s)
+      end
+
+      def admissible?(field, id) = reference(field, id)&.visible == true
+
+      # Current picker options as [label, key] pairs. Order follows the target
+      # title only while that title is a granted sort field, then the key.
+      def choices(field)
+        access = target_access(field)
+        begin
+          access.authorize!(:index)
+        rescue AccessDenied
+          return Choices.new([].freeze, false)
+        end
+        model = access.resource.model_class
+        table = model.arel_table
+        title = access.fields(:sort).find { |candidate| candidate.name == access.resource.title }
+        relation = access.relation.reorder(nil)
+        relation = relation.order(table[title.column].asc) if title
+        records = relation.order(table[model.primary_key].asc).limit(MAX_CHOICES + 1).to_a
+        cache = @references[cache_key(field)]
+        options = records.first(MAX_CHOICES).filter_map do |record|
+          reference = cache[record.id.to_s] ||= build(field, access, record, record.id.to_s)
+          [ reference.label, reference.id ] if reference.visible
+        end
+        Choices.new(options.freeze, records.size <= MAX_CHOICES)
+      end
+
+      # Picker search over a target resource, for forms and filters whose
+      # choices are incomplete. Results are exactly what the target's own index
+      # would show this actor for the same term: its policy relation, its
+      # granted search fields, and a show grant per record. A term shaped like
+      # the target's primary key also matches that record. Returns [label, key]
+      # pairs, at most limit.
+      SEARCH_LIMIT = 20
+      def self.search(context, target, term, limit: SEARCH_LIMIT)
+        raise ConfigurationError, "Invalid picker limit" unless limit.is_a?(Integer) && limit.between?(1, SEARCH_LIMIT)
+        access = Authorization::Access.new(context, target)
+        access.authorize!(:index)
+        term = term.strip if term.is_a?(String) && term.valid_encoding?
+        return [] if term.blank?
+        model = target.model_class
+        exact = access.canonical_id?(term) ? access.relation.where(model.primary_key => term).limit(1).to_a : []
+        matches = if access.fields(:search).any?
+          Queries::List.new(context, target).call(search: term, scope: Queries::NamedScope::NONE, page_size: limit).records
+        else
+          # Unsearchable targets still accept an exact key; the term itself
+          # is validated the same way the list validates search text.
+          raise AccessDenied, "INVALID_QUERY" unless Queries::List::FILTER_VALUE.call(term)
+          []
+        end
+        (exact + matches).uniq(&:id).first(limit).filter_map do |record|
+          access.authorize!(:show, record)
+          [ access.record_label(record).freeze, record.id.to_s.freeze ]
+        rescue AccessDenied
+          nil
+        end
+      end
+
+      private
+
+      def cache_key(field) = field.options.fetch(:resource).to_s
+
+      def target_access(field)
+        @accesses[cache_key(field)] ||= begin
+          own = @resource&.fields&.any? { |candidate| candidate.equal?(field) }
+          target = own ? self.class.validate!(@resource, field) : self.class.target(field)
+          Authorization::Access.new(@context, target)
+        end
+      end
+
+      # Integer keys are checked before the query so malformed text never reaches
+      # an integer comparison; other key types rely on the column's own cast.
+      def key_shape?(model, id)
+        return false unless id.match?(Field::REFERENCE)
+        column = model.columns_hash[model.primary_key]
+        column&.type == :integer ? id.match?(INTEGER_KEY) && Integer(id, 10) <= 2**63 - 1 : true
+      end
+
+      def build(field, access, record, id)
+        if record
+          access.authorize!(:show, record)
+          return Reference.new(id.dup.freeze, access.record_label(record).freeze, access.resource.key, true)
+        end
+        unavailable(field, id)
+      rescue AccessDenied
+        unavailable(field, id)
+      end
+
+      def unavailable(field, id)
+        Reference.new(id.dup.freeze, "#{self.class.target(field).label.singularize} ##{id}".freeze, nil, false)
+      end
+    end
+  end
+end

data/lib/rails_ai_admin/fields/computation.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  module Fields
+    # Trusted pure host code receives only declared, currently authorized scalar
+    # dependencies. It cannot acquire authority from the field declaration.
+    class Computation
+      extend HookSignatures
+      class << self
+        def version(value = nil)
+          @version = value if value
+          @version || "1"
+        end
+
+        def metadata
+          unless name && version.is_a?(String) && version.match?(/\A[a-zA-Z0-9][a-zA-Z0-9_.-]{0,63}\z/)
+            raise ConfigurationError, "Computation needs a named class and bounded version"
+          end
+          unless respond_to?(:new) && accepts?(method(:new), 0, []) && accepts?(instance_method(:initialize), 0, []) &&
+              public_instance_methods.include?(:call) && instance_method(:call).owner != Computation && accepts?(instance_method(:call), 1, %i[field time_zone])
+            raise ConfigurationError, "Computation has an incompatible public constructor or call signature"
+          end
+          { handler: name, version: version }
+        end
+      end
+
+      def call(_values, field:, time_zone:)
+        raise NotImplementedError
+      end
+
+      Definition = Data.define(:handler_name) do
+        def handler_class
+          klass = handler_name.constantize
+          raise ConfigurationError, "Computed field requires a Computation subclass" unless klass.is_a?(Class) && klass < Computation
+          klass
+        rescue NameError
+          raise ConfigurationError, "Computed field class could not be loaded", cause: nil
+        end
+        def metadata = handler_class.metadata
+      end
+    end
+  end
+end

data/lib/rails_ai_admin/fields/dependency_graph.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  module Fields
+    module DependencyGraph
+      MAX_FIELDS = 128
+      MAX_DEPTH = 8
+      MAX_DEPENDENCIES = 20
+
+      def self.validate!(fields)
+        return unless fields.any?(&:virtual?)
+        raise ConfigurationError, "Computed resource exceeds field bound" if fields.size > MAX_FIELDS
+        declared = fields.index_by(&:name)
+        depths = {}
+        visit = lambda do |field, path|
+          return 0 unless field.virtual?
+          return depths[field.name] if depths.key?(field.name)
+          raise ConfigurationError, "Computed dependency cycle" if path.include?(field.name)
+          depth = 1 + (field.dependencies.map do |name|
+            dependency = declared.fetch(name) { raise ConfigurationError, "Computed dependency must be a declared field" }
+            visit.call(dependency, path + [ field.name ])
+          end.max || 0)
+          raise ConfigurationError, "Computed dependency depth exceeds bound" if depth > MAX_DEPTH
+          depths[field.name] = depth
+        end
+        fields.select(&:virtual?).each { |field| visit.call(field, []) }
+      end
+
+      def self.readable(fields)
+        granted = fields.index_by(&:name)
+        eligible = {}
+        visit = lambda do |field, path|
+          return eligible[field.name] if eligible.key?(field.name)
+          return eligible[field.name] = true unless field.virtual?
+          raise ConfigurationError, "Invalid computed dependency graph" if path.include?(field.name) || path.size >= MAX_DEPTH
+          eligible[field.name] = field.dependencies.all? do |name|
+            dependency = granted[name]
+            dependency && visit.call(dependency, path + [ field.name ])
+          end
+        end
+        fields.select { |field| visit.call(field, []) }
+      end
+    end
+  end
+end

data/lib/rails_ai_admin/fields/file_value.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  module Fields
+    # Raster images a browser may show inline. SVG and HTML never are: they
+    # can carry script.
+    INLINE_IMAGE_TYPES = %w[image/png image/jpeg image/gif image/webp image/avif].freeze
+
+    # A chosen file the page refused before uploading it (too large).
+    RejectedUpload = Data.define(:reason, :limit)
+
+    # The readable facts about one attached file. Pages link to it through the
+    # admin's own download route, never through a public blob URL.
+    # id is the attachment id of one of several files (has_many_attached).
+    FileValue = Data.define(:filename, :content_type, :byte_size, :checksum, :id) do
+      def self.from(blob, id: nil)
+        new(blob.filename.to_s.freeze, blob.content_type.to_s.freeze, blob.byte_size, blob.checksum.to_s.freeze, id&.to_s&.freeze)
+      end
+
+      def image? = INLINE_IMAGE_TYPES.include?(content_type)
+    end
+  end
+end

data/lib/rails_ai_admin/fields/hook_signatures.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  module Fields
+    module HookSignatures
+      private
+
+      def accepts?(method, count, keywords)
+        params = method.parameters
+        minimum = params.count { |kind, _| kind == :req }
+        maximum = params.any? { |kind, _| kind == :rest } ? Float::INFINITY : minimum + params.count { |kind, _| kind == :opt }
+        (minimum..maximum).cover?(count) && (params.filter_map { |kind, key| key if kind == :keyreq } - keywords).empty? &&
+          !params.any? { |kind, _| kind == :nokey } &&
+          (params.any? { |kind, _| kind == :keyrest } || (keywords - params.filter_map { |kind, key| key if %i[key keyreq].include?(kind) }).empty?)
+      end
+    end
+  end
+end

data/lib/rails_ai_admin/fields/projection.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  module Fields
+    # One current projection, with no cross-request/identity value cache.
+    class Projection
+      MAX_VALUE_BYTES = 16_384
+      MAX_OUTPUT_BYTES = 65_536
+      MAX_SECONDS = 1.0
+
+      def initialize(access, record, fields)
+        @access, @record = access, record
+        @fields = fields.index_by(&:name)
+        @computed = fields.any?(&:virtual?)
+        @cache = {}
+        @bytes = 0
+        @deadline = monotonic + MAX_SECONDS
+      end
+
+      def values(fields: @fields.values)
+        result = fields.to_h { |field| [ field.name.to_s, value(field) ] }
+        check_deadline!
+        result
+      end
+
+      def value(field)
+        check_deadline!
+        raise AccessDenied unless @fields[field.name].equal?(field)
+        return @cache[field.name] if @cache.key?(field.name)
+        unless field.virtual?
+          scalar = @access.read_attribute(@record, field)
+          check_deadline!
+          return @cache[field.name] = scalar
+        end
+        computed = ActiveRecord::Base.while_preventing_writes do
+          dependencies = field.dependencies.to_h { |name| [ name.to_s, snapshot(value(@fields.fetch(name))) ] }.freeze
+          check_bound!(dependencies)
+          field.compute(dependencies, time_zone: @access.context.time_zone)
+        end
+        check_deadline!
+        @bytes += check_bound!(computed)
+        raise ConfigurationError, "Computed projection exceeds output bound" if @bytes > MAX_OUTPUT_BYTES
+        @cache[field.name] = computed
+      end
+
+      private
+
+      def snapshot(value)
+        copy = case value
+        when nil, true, false, Integer then value
+        when String then String.new(value)
+        when BigDecimal
+          raise ConfigurationError, "Computed dependencies require finite decimals" unless value.finite?
+          value
+        when Time, ActiveSupport::TimeWithZone, DateTime then value.to_time.getutc
+        when Date then Date.iso8601(value.iso8601)
+        else raise ConfigurationError, "Computed dependencies require supported scalars"
+        end
+        check_bound!(copy)
+        copy.freeze
+      end
+
+      def check_bound!(value)
+        bytes = JSON.generate(InputSchema.canonical(value)).bytesize
+        raise ConfigurationError, "Computed scalar exceeds size bound" if bytes > MAX_VALUE_BYTES
+        bytes
+      rescue JSON::GeneratorError, EncodingError
+        raise ConfigurationError, "Computed scalar encoding is invalid", cause: nil
+      end
+
+      def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      def check_deadline!
+        raise ConfigurationError, "Computed projection exceeded its cooperative budget" if @computed && monotonic > @deadline
+      end
+    end
+  end
+end

data/lib/rails_ai_admin/fields/registry.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  module Fields
+    class Registry
+      Definition = Data.define(:key, :handler_name) do
+        def handler_class
+          klass = handler_name.constantize
+          unless klass.is_a?(Class) && klass < Type && klass.name
+            raise ConfigurationError, "Registered field type must inherit RailsAiAdmin::Fields::Type"
+          end
+          klass
+        rescue NameError
+          raise ConfigurationError, "Registered field type could not be loaded", cause: nil
+        end
+
+        def metadata = handler_class.metadata
+      end
+
+      def initialize(types)
+        unless types.is_a?(Hash) && types.all? { |key, name| (key.is_a?(String) || key.is_a?(Symbol)) && key.to_s.match?(/\A[a-z][a-z0-9_]{0,39}\z/) && name.is_a?(String) && name.match?(/\A[A-Z]\w*(?:::[A-Z]\w*)*\z/) }
+          raise ConfigurationError, "field_types must map stable keys to class-name strings"
+        end
+        @mapping = types.transform_keys(&:to_s).transform_values(&:dup)
+        if @mapping.size != types.size || (@mapping.keys & Field::TYPES.map(&:to_s)).any?
+          raise ConfigurationError, "Field registrations cannot duplicate or replace built-in types"
+        end
+        @mapping.each { |key, name| key.freeze; name.freeze }
+        @mapping.freeze
+        @entries = @mapping.to_h { |key, name| [ key, Definition.new(key, name) ] }.freeze
+        freeze
+      end
+
+      def matches?(types) = types.is_a?(Hash) && types.transform_keys(&:to_s) == @mapping
+      def definitions = @entries.values
+      def validate!
+        definitions.each(&:metadata)
+        self
+      end
+
+      def build(name, type:, source: nil, **options)
+        return Field.new(name, type: type, source: source, **options) if Field::TYPES.include?(type.to_sym)
+        definition = @entries.fetch(type.to_s) { raise ConfigurationError, "Unregistered field type" }
+        Field.new(name, type: type, plugin: definition, source: source, **options)
+      end
+    end
+  end
+end

data/lib/rails_ai_admin/fields/scalar_schema.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "json_schemer"
+
+module RailsAiAdmin
+  module Fields
+    # A deliberately scalar-only subset of the released Surface schema contract.
+    # Core constraints stay outside the extension in an intersection.
+    module ScalarSchema
+      SHARED_KEYS = %w[type enum const title description].freeze
+      TYPE_KEYS = { "string" => %w[pattern minLength maxLength], "integer" => %w[minimum maximum], "boolean" => [] }.freeze
+      def self.scalar?(value)
+        value.nil? || value == true || value == false || value.is_a?(String) && value.valid_encoding? ||
+          value.is_a?(Integer) || value.is_a?(Float) && value.finite?
+      end
+      private_class_method :scalar?
+
+      def self.compile(base, constraints)
+        unless constraints.is_a?(Hash) && constraints.keys.all? { |key| key.is_a?(String) || key.is_a?(Symbol) } && constraints.stringify_keys.size == constraints.size
+          raise ConfigurationError, "Field schema constraints must be a scalar keyword hash"
+        end
+        constraints = constraints.stringify_keys
+        allowed_keys = SHARED_KEYS + TYPE_KEYS.fetch(base.fetch("type"))
+        if (constraints.keys - allowed_keys).any? || constraints.key?("type") && constraints["type"] != base.fetch("type")
+          raise ConfigurationError, "Field schema cannot change the core scalar type or use unsupported keywords"
+        end
+        if constraints["pattern"] && (!constraints["pattern"].is_a?(String) || constraints["pattern"].bytesize > 1000)
+          raise ConfigurationError, "Field schema pattern must be bounded text"
+        end
+        %w[title description].each do |key|
+          raise ConfigurationError, "Field schema text must be bounded" if constraints[key] && (!constraints[key].is_a?(String) || constraints[key].bytesize > 300)
+        end
+        if constraints.key?("const") && !scalar?(constraints["const"]) || constraints.key?("enum") &&
+            (!constraints["enum"].is_a?(Array) || !constraints["enum"].all? { |value| scalar?(value) })
+          raise ConfigurationError, "Field enum and const constraints must contain JSON scalars"
+        end
+        encoded = JSON.generate(constraints)
+        raise ConfigurationError, "Field schema is too large" if encoded.bytesize > 8192
+        constraints = JSON.parse(encoded)
+        schema = constraints.empty? ? base : base.merge("allOf" => [ constraints ])
+        validator = JSONSchemer.schema(schema, ref_resolver: ->(*) { raise ConfigurationError, "Field schema references are unsupported" })
+        raise ConfigurationError, "Invalid scalar field schema" unless validator.valid_schema?
+        [ schema, validator ]
+      rescue JSON::GeneratorError, JSON::ParserError, EncodingError, RegexpError, ArgumentError
+        raise ConfigurationError, "Invalid scalar field schema", cause: nil
+      end
+    end
+  end
+end

data/lib/rails_ai_admin/fields/type.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  module Fields
+    # Pure refinements of an explicitly granted core scalar. Never an authority
+    # or record lookup API. Each invocation gets a new, stateless instance.
+    class Type
+      extend HookSignatures
+      class << self
+        def scalar(value = nil)
+          @scalar = value.to_sym if value
+          @scalar
+        end
+
+        def version(value = nil)
+          @version = value if value
+          @version || "1"
+        end
+
+        %i[form_partial index_partial show_partial].each do |method|
+          define_method(method) do |value = nil|
+            instance_variable_set("@#{method}", value) if value
+            instance_variable_get("@#{method}")
+          end
+        end
+
+        def metadata
+          unless scalar && Field::TYPES.include?(scalar) && scalar != :belongs_to && version.is_a?(String) && version.match?(/\A[a-zA-Z0-9][a-zA-Z0-9_.-]{0,63}\z/)
+            raise ConfigurationError, "Field type needs a built-in scalar and bounded version"
+          end
+          partials = %i[form_partial index_partial show_partial].to_h { |key| [ key, public_send(key) ] }
+          unless partials.values.all? { |path| path.nil? || path.is_a?(String) && path.length <= 200 && path.match?(/\A[a-z][a-z0-9_]*(?:\/[a-z][a-z0-9_]*)*\z/) }
+            raise ConfigurationError, "Field partials must be trusted relative Rails view paths"
+          end
+          methods = { normalize: [ 1, %i[field time_zone] ], valid?: [ 1, %i[field time_zone] ], format: [ 1, %i[field time_zone] ], schema: [ 0, [ :field ] ] }
+          unless respond_to?(:new) && accepts?(method(:new), 0, []) && accepts?(instance_method(:initialize), 0, []) &&
+              methods.all? { |key, (count, keywords)| public_instance_methods.include?(key) && accepts?(instance_method(key), count, keywords) }
+            raise ConfigurationError, "Field type has an incompatible public constructor or hook signature"
+          end
+          { handler: name, scalar: scalar, version: version, **partials }
+        end
+      end
+
+      def normalize(value, field:, time_zone:) = value
+      def valid?(value, field:, time_zone:) = true
+      def format(text, field:, time_zone:) = text
+      def schema(field:) = {}
+    end
+  end
+end

data/lib/rails_ai_admin/forms/plan.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  module Forms
+    # Presentation-only snapshots; callers supply currently authorized fields.
+    # No record, denied value, query or persistence lives in this plan.
+    class Plan
+      Entry = Data.define(:field, :editable, :value)
+      Panel = Data.define(:label, :entries)
+      Tab = Data.define(:label, :panels)
+      MAX_FIELDS = 128
+      MAX_TABS = 8
+      MAX_PANELS = 16
+      MAX_VALUE_BYTES = 262_144
+      MAX_BYTES = 1_048_576
+      attr_reader :tabs, :entries
+
+      def initialize(fields:, values:, readonly_fields: [], readonly_values: {}, order: nil)
+        unless values.is_a?(Hash) && readonly_values.is_a?(Hash)
+          raise ConfigurationError, "Form values must be scalar maps"
+        end
+        writable = fields.reject(&:hidden?).index_by(&:name)
+        readable = readonly_fields.reject(&:hidden?).index_by(&:name).except(*writable.keys)
+        @bytes = 0
+        @entries = (Array(order) + fields + readonly_fields).uniq(&:name).filter_map do |field|
+          next unless writable.key?(field.name) || readable.key?(field.name)
+          editable = writable.key?(field.name)
+          source = editable ? values : readonly_values
+          value = source.key?(field.name.to_s) ? source[field.name.to_s] : source[field.name]
+          Entry.new(field, editable, scalar(value, type: field.scalar_type))
+        end.freeze
+        raise ConfigurationError, "Form field bound exceeded" if @entries.size > MAX_FIELDS
+        @tabbed = @entries.any? { |entry| entry.field.options[:tab] }
+        groups = @entries.group_by { |entry| entry.field.options[:tab] || (@tabbed ? "Details" : nil) }
+        raise ConfigurationError, "Form tab bound exceeded" if groups.size > MAX_TABS
+        @tabs = groups.map do |label, entries|
+          panels = entries.group_by { |entry| entry.field.options[:panel] }
+          raise ConfigurationError, "Form panel bound exceeded" if panels.size > MAX_PANELS
+          Tab.new(label, panels.map { |title, items| Panel.new(title, items.freeze) }.freeze)
+        end.freeze
+        @tabbed &&= @tabs.size > 1
+        freeze
+      end
+
+      def tabbed? = @tabbed
+
+      private
+
+      def scalar(value, type: nil)
+        copy = case value
+        when nil, true, false, Integer then value
+        when String then String.new(value).encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+        when BigDecimal
+          raise ConfigurationError, "Form decimals must be finite" unless value.finite?
+          value
+        when Time, ActiveSupport::TimeWithZone, DateTime then value.to_time.getutc
+        when Date then Date.iso8601(value.iso8601)
+        when Fields::FileValue then value
+        # A references field carries its target keys.
+        when Array
+          if type == :files
+            raise ConfigurationError, "Form files must be file values" unless value.all? { |item| item.is_a?(Fields::FileValue) }
+            value.dup.freeze
+          elsif type == :references
+            raise ConfigurationError, "Form references must be key text" unless value.all? { |item| item.is_a?(String) }
+            value.map { |item| String.new(item).freeze }.freeze
+          else
+            raise ConfigurationError, "Form values require supported scalars" unless type == :json
+            json_text(value)
+          end
+        # A JSON field edits its document as indented text.
+        when Hash, Float
+          raise ConfigurationError, "Form values require supported scalars" unless type == :json
+          json_text(value)
+        else raise ConfigurationError, "Form values require supported scalars"
+        end
+        bytes = JSON.generate(InputSchema.canonical(copy)).bytesize
+        @bytes += bytes
+        raise ConfigurationError, "Form value bound exceeded" if bytes > MAX_VALUE_BYTES || @bytes > MAX_BYTES
+        copy.freeze
+      end
+
+      def json_text(value)
+        JSON.pretty_generate(value)
+      rescue JSON::GeneratorError
+        raise ConfigurationError, "Form JSON values must be finite", cause: nil
+      end
+    end
+  end
+end