lcp 0.1.0

data/app/controllers/lcp_ruby/resources_controller.rb

@@ -0,0 +1,2218 @@
+require "digest"
+
+module LcpRuby
+  class ResourcesController < ApplicationController
+    include LcpRuby::AssociationOptionsBuilder
+    include LcpRuby::DialogRendering
+    include LcpRuby::FormActionExecution
+    include LcpRuby::ZoneResolution
+    include LcpRuby::AuthorizedController
+    include LcpRuby::PageAuthorization
+
+    before_action :set_record, only: [ :show, :edit, :update, :destroy, :evaluate_conditions, :reorder, :reparent, :kanban_move, :zone, :execute_transition ]
+    before_action :set_record_with_discarded, only: [ :restore, :permanently_destroy ]
+    # Declared AFTER :set_record so PageGate.evaluate sees the loaded
+    # @record on show/edit/update/destroy paths (Rails before_actions
+    # run in declaration order; registering inside the concern's
+    # `included do` would put the gate before set_record). The
+    # `routable?` guard scopes to slug-resolved page paths —
+    # dialog-only pages render through a separate pipeline.
+    # See docs/design/authorization_hardening.md § "Concern include
+    # order in ResourcesController is load-bearing".
+    before_action :authorize_page_if_present,
+                  if: -> { current_page.present? && current_page.routable? }
+
+    def index
+      if raw_format?
+        return head :not_acceptable if raw_index_unsupported?
+        return render_raw_index
+      end
+
+      # Standalone grid pages (dashboards) bypass normal CRUD authorization.
+      # Page-level access is gated by LcpRuby::PageAuthorization (before_action
+      # above), which calls skip_authorization on :allow so verify_authorized
+      # sees authorization-having-happened.
+      if current_page&.standalone? && current_page&.grid?
+        load_dashboard
+        return
+      end
+
+      # Composite pages may specify a separate index_presenter for index actions
+      if current_page&.index_presenter
+        @presenter_definition = LcpRuby.loader.presenter_definition(current_page.index_presenter)
+      else
+        # Check for index composite page — either the current page itself,
+        # or an explicit composite page defined for this model
+        @index_composite_page = if current_page&.index_composite?
+          current_page
+        else
+          find_index_composite_for_model
+        end
+
+        if @index_composite_page
+          @presenter_definition = LcpRuby.loader.presenter_definitions[@index_composite_page.main_presenter_name]
+          authorize @model_class
+          load_index_composite
+          return
+        end
+      end
+
+      authorize @model_class
+
+      if api_model?
+        load_api_index
+        return
+      end
+
+      scope = policy_scope(@model_class)
+      scope = apply_soft_delete_scope(scope)
+
+      apply_default_saved_filter!
+
+      if current_presenter.index_render_with
+        load_flat_index(scope)
+      else
+        case current_presenter.index_layout
+        when :tree
+          load_tree_index(scope) if current_model_definition.tree?
+        when :grouped
+          load_grouped_index(scope)
+        when :tiles
+          load_flat_index(scope)
+        when :kanban
+          load_kanban_index(scope)
+        else
+          load_flat_index(scope)
+        end
+      end
+    end
+
+    def show
+      authorize @record
+
+      if raw_format?
+        return head :not_acceptable if raw_show_unsupported?
+        return render_raw_show
+      end
+
+      warn_missing_presenter_config(:show)
+
+      if dialog_context?
+        setup_show_view_objects(current_presenter)
+        return render partial: "lcp_ruby/dialogs/dialog_show_frame",
+                       locals: {
+                         record: @record,
+                         layout_builder: @layout_builder,
+                         column_set: @column_set,
+                         field_resolver: @field_resolver
+                       },
+                       layout: false
+      end
+
+      if current_page&.composite?
+        load_composite_page
+        return
+      end
+
+      if api_model?
+        setup_show_view_objects(current_presenter)
+        return
+      end
+
+      setup_show_view_objects(current_presenter)
+      load_show_virtual_columns
+      preload_associations(@record, :show)
+      @record.strict_loading! if LcpRuby.configuration.strict_loading_enabled?
+    end
+
+    def zone
+      authorize @record, :show?
+
+      zone_name = params[:zone_name]
+      zone = find_composite_zone(zone_name)
+      return head(:not_found) unless zone
+      return head(:not_found) unless zone_accessible?(zone)
+
+      data = resolve_zone_data(zone, zone_params: zone_params(zone))
+
+      frame_id = zone.area == "tabs" ? "lcp-zone-tab-content" : "lcp-zone-#{zone.name}"
+
+      render partial: "lcp_ruby/zones/zone_frame",
+             locals: { zone: zone, data: data, frame_id: frame_id, record: @record },
+             layout: false
+    end
+
+    def new
+      return head(:not_found) if api_model?
+      @record = @model_class.new
+      authorize @record
+      warn_missing_presenter_config(:form)
+      apply_presenter_defaults(@record)
+      @form_actions = current_form_actions(@record)
+
+      if dialog_context?
+        return render_dialog_form
+      end
+
+      build_nested_records(@record)
+      @layout_builder = Presenter::LayoutBuilder.new(current_presenter, current_model_definition)
+    end
+
+    def create
+      return head(:not_found) if api_model?
+      @record = @model_class.new(permitted_params)
+      authorize @record
+      fa_config = resolve_form_action(@record)
+
+      process_json_field_params(@record)
+      validate_association_values!(@record)
+      apply_set_fields!(@record, fa_config)
+
+      if @record.errors.any?
+        return render_create_failure
+      end
+
+      result = execute_form_action_pipeline(@record, fa_config)
+
+      if result.success?
+        dispatch_deferred_events(result)
+        broadcast_model_change(current_model_definition.name)
+
+        if dialog_context?
+          behavior = form_action_dialog_behavior(fa_config)
+          flash_msg = behavior == "reset" ? pipeline_flash_message("create", result) : nil
+          return render_dialog_success(behavior, flash_message: flash_msg, result_config: fa_config["result"])
+        end
+
+        redirect_to pipeline_redirect_path("create", fa_config, @record, result),
+          status: :see_other,
+          notice: pipeline_flash_message("create", result)
+      else
+        render_create_failure
+      end
+    end
+
+    def edit
+      return head(:not_found) if api_model?
+      authorize @record
+      warn_missing_presenter_config(:form)
+      @form_actions = current_form_actions(@record)
+
+      if dialog_context?
+        return render_dialog_form
+      end
+
+      @layout_builder = Presenter::LayoutBuilder.new(current_presenter, current_model_definition)
+      load_edit_virtual_columns
+      preload_associations(@record, :form)
+      @record.strict_loading! if LcpRuby.configuration.strict_loading_enabled?
+    end
+
+    def update
+      return head(:not_found) if api_model?
+      authorize @record
+      @record.assign_attributes(permitted_params)
+      fa_config = resolve_form_action(@record)
+      purge_removed_attachments!(@record)
+
+      process_json_field_params(@record)
+      validate_association_values!(@record)
+      apply_set_fields!(@record, fa_config)
+
+      if @record.errors.any?
+        return render_update_failure
+      end
+
+      result = execute_form_action_pipeline(@record, fa_config)
+
+      if result.success?
+        dispatch_deferred_events(result)
+        broadcast_model_change(current_model_definition.name)
+
+        if dialog_context?
+          behavior = form_action_dialog_behavior(fa_config)
+          flash_msg = behavior == "reset" ? pipeline_flash_message("update", result) : nil
+          return render_dialog_success(behavior, flash_message: flash_msg, result_config: fa_config["result"])
+        end
+
+        path = if current_page&.form_zone&.submit_redirect_self?
+          resource_path(@record)
+        else
+          pipeline_redirect_path("update", fa_config, @record, result)
+        end
+        redirect_to path, status: :see_other,
+          notice: pipeline_flash_message("update", result)
+      else
+        render_update_failure
+      end
+    end
+
+    def destroy
+      return head(:not_found) if api_model?
+      authorize @record
+      if current_model_definition.soft_delete?
+        @record.discard!(by: current_user)
+      else
+        @record.destroy!
+      end
+
+      broadcast_model_change(current_model_definition.name)
+
+      notice_key = current_model_definition.soft_delete? ? "lcp_ruby.flash.archived" : "lcp_ruby.flash.deleted"
+      default_msg = current_model_definition.soft_delete? ? "%{model} was successfully archived." : "%{model} was successfully deleted."
+      redirect_to resources_path,
+        notice: I18n.t(notice_key, model: current_model_definition.resolved_label, default: default_msg)
+    end
+
+    def execute_transition
+      authorize @record, :update?
+
+      transition_name = params[:transition_name]
+      comment = params[:transition_comment]
+
+      Workflow::TransitionExecutor.execute(
+        @record, transition_name,
+        user: current_user, evaluator: current_evaluator,
+        comment: comment, triggered_by: "user"
+      )
+
+      redirect_to resource_path(@record), status: :see_other,
+        notice: I18n.t("lcp_ruby.flash.transition_executed",
+          transition: resolve_transition_label(transition_name),
+          default: "Transition '%{transition}' executed successfully.")
+    rescue Workflow::CommentRequiredError
+      redirect_to resource_path(@record), status: :see_other,
+        alert: I18n.t("lcp_ruby.flash.transition_comment_required",
+          default: "A comment is required for this transition.")
+    rescue Workflow::TransitionDeniedError => e
+      redirect_to resource_path(@record), status: :see_other, alert: e.localized_message
+    end
+
+    def restore
+      authorize @record
+      @record.undiscard!
+      redirect_to resources_path, status: :see_other,
+        notice: I18n.t("lcp_ruby.flash.restored", model: current_model_definition.resolved_label,
+                       default: "%{model} was successfully restored.")
+    end
+
+    def permanently_destroy
+      authorize @record
+      @record.destroy!
+      redirect_to resources_path, status: :see_other,
+        notice: I18n.t("lcp_ruby.flash.permanently_deleted", model: current_model_definition.resolved_label,
+          default: "%{model} was permanently deleted.")
+    end
+
+    def select_options
+      field_name = params[:field]
+      field_config = find_form_field_config(field_name)
+      unless field_config
+        skip_authorization
+        return render(json: [])
+      end
+
+      # Resolve association from enriched field config (covers association_select + multi_select)
+      assoc = field_config["association"] || field_config["multi_select_association"]
+      # Fallback to FK lookup for non-enriched cases
+      assoc ||= resolve_association_for_field(field_name)
+      unless assoc&.lcp_model?
+        skip_authorization
+        return render(json: [])
+      end
+
+      # Authorize against the TARGET model's policy, not the page-level
+      # presenter model. The user is requesting a list of records FROM
+      # `assoc.target_model`; access to the presenter alone does not
+      # imply read access to the association target. `before_action
+      # :authorize_presenter_access` (Controller::Authorization) already
+      # gates presenter visibility, so we only need the additional
+      # target-model `:index?` check here.
+      authorize_select_options_target!(assoc.target_model)
+
+      input_options = field_config["input_options"] || {}
+
+      # API-backed target model: delegate to data source
+      if api_target_model?(assoc)
+        return render json: build_api_select_options(assoc, input_options)
+      end
+
+      # Reverse cascade: resolve ancestor chain for a given value
+      if params[:ancestors_for].present?
+        ancestors = resolve_field_ancestors(field_name, params[:ancestors_for])
+        return render json: { ancestors: ancestors }
+      end
+
+      # Tree select mode
+      if params[:tree] == "true"
+        tree = build_tree_select_options(assoc, input_options)
+        return render json: tree
+      end
+
+      # Paginated search mode when q or page param present
+      if params[:q].present? || params[:page].present?
+        result = build_select_options_search(assoc, input_options)
+        render json: result
+      else
+        options = build_select_options_json(assoc, input_options)
+        render json: options
+      end
+    end
+
+    def evaluate_conditions
+      authorize @record, :edit?
+      @record.assign_attributes(permitted_params)
+      render json: evaluate_service_conditions(@record)
+    end
+
+    def evaluate_conditions_new
+      @record = @model_class.new(permitted_params)
+      authorize @record, :create?
+      render json: evaluate_service_conditions(@record)
+    end
+
+    def parse_ql
+      authorize @model_class, :index?
+
+      ql_text = params[:ql].to_s.first(Search::QueryLanguageParser::MAX_INPUT_LENGTH + 1)
+      max_depth = current_presenter.advanced_filter_config["max_nesting_depth"] || 2
+      parser = Search::QueryLanguageParser.new(ql_text, max_nesting_depth: max_depth)
+      tree = parser.parse
+
+      render json: { success: true, tree: tree }
+    rescue Search::QueryLanguageParser::ParseError => e
+      render json: { success: false, error: e.message, position: e.position }
+    end
+
+    def filter_fields
+      authorize @model_class, :index?
+
+      builder = Search::FilterMetadataBuilder.new(current_presenter, current_model_definition, current_evaluator)
+      metadata = builder.build
+
+      result = { fields: metadata[:fields] }
+      result[:scopes] = metadata[:scopes] if metadata[:scopes]&.any?
+      render json: result
+    end
+
+    def batch_count
+      authorize @model_class, "index?"
+      scope = policy_scope(@model_class)
+      scope = apply_soft_delete_scope(scope)
+      scope = apply_advanced_search(scope)
+      render json: { count: scope.count }
+    end
+
+    def export_fields
+      authorize @model_class, "index?"
+      head(:forbidden) and return unless current_evaluator.can_execute_action?(:export)
+
+      tree = Export::FieldTreeBuilder.build(
+        model_definition: current_model_definition,
+        evaluator: current_evaluator,
+        presenter: current_presenter,
+        current_user: current_user
+      )
+      render json: tree
+    end
+
+    def export_profiles
+      authorize @model_class, "index?"
+      head(:forbidden) and return unless current_evaluator.can_execute_action?(:export)
+
+      profile_model = LcpRuby.registry.model_for("export_profile")
+      profiles = profile_model
+        .for_presenter(current_presenter.name)
+        .where(
+          profile_model.arel_table[:visibility].eq("global")
+            .or(profile_model.arel_table[:visibility].eq("role")
+              .and(profile_model.arel_table[:target_role].in(current_evaluator.roles)))
+            .or(profile_model.arel_table[:visibility].eq("personal")
+              .and(profile_model.arel_table[:owner_id].eq(current_user&.id)))
+        )
+        .order(:profile_name)
+
+      # Build field tree to detect stale fields
+      field_tree = Export::FieldTreeBuilder.build(
+        model_definition: current_model_definition,
+        evaluator: current_evaluator,
+        presenter: current_presenter,
+        current_user: current_user
+      )
+      available_paths = collect_field_paths(field_tree)
+
+      render json: profiles.map { |p|
+        selected = Array(p.selected_fields)
+        stale = selected - available_paths
+        valid = selected - stale
+
+        {
+          id: p.id,
+          profile_name: p.profile_name,
+          format: p.format,
+          selected_fields: valid,
+          formatting_options: p.formatting_options,
+          stale_fields: stale
+        }
+      }
+    rescue LcpRuby::Error
+      render json: []
+    end
+
+    def import_fields
+      authorize @model_class, "index?"
+      head(:forbidden) and return unless current_evaluator.can_execute_action?(:import)
+
+      tree = Import::FieldTreeBuilder.build(
+        model_definition: current_model_definition,
+        evaluator: current_evaluator,
+        presenter: current_presenter,
+        current_user: current_user
+      )
+      render json: tree
+    end
+
+    def import_profiles
+      authorize @model_class, "index?"
+      head(:forbidden) and return unless current_evaluator.can_execute_action?(:import)
+
+      profile_model = LcpRuby.registry.model_for("import_profile")
+      profiles = profile_model
+        .for_model(current_model_definition.name)
+        .where(
+          profile_model.arel_table[:visibility].eq("global")
+            .or(profile_model.arel_table[:visibility].eq("role")
+              .and(profile_model.arel_table[:target_role].in(current_evaluator.roles)))
+            .or(profile_model.arel_table[:visibility].eq("personal")
+              .and(profile_model.arel_table[:owner_id].eq(current_user&.id)))
+        )
+        .order(:profile_name)
+
+      render json: profiles.map { |p|
+        {
+          id: p.id,
+          profile_name: p.profile_name,
+          strategy: p.strategy,
+          match_attribute: p.match_attribute,
+          column_mapping: p.column_mapping,
+          lookup_config: p.lookup_config,
+          parsing_options: p.parsing_options
+        }
+      }
+    rescue LcpRuby::Error
+      render json: []
+    end
+
+    def batch_selection
+      authorize @model_class, "index?"
+      ids = params[:ids] || []
+      token = SecureRandom.uuid
+      session[:batch_selections] ||= {}
+      session[:batch_selections][token] = ids.map(&:to_s)
+      render json: { token: token }
+    end
+
+    # PATCH /:id/kanban_move — dispatches the move through the configured
+    # provider and maps Kanban::MoveResult → HTTP per docs/design/kanban_view.md.
+    def kanban_move
+      unless current_presenter.kanban?
+        head :not_found
+        return
+      end
+
+      authorize @record, :update?
+
+      provider_class = kanban_provider_class
+      provider = build_kanban_provider(provider_class)
+
+      target_column   = params[:target_column]
+      target_swimlane = params[:target_swimlane]
+      target_position = params[:target_position].presence&.to_i
+      comment         = params[:transition_comment]
+
+      group_by_field = current_presenter.kanban_config["group_by"].to_s
+      source_column = group_by_field.present? ? @record.public_send(group_by_field).to_s : params[:source_column].to_s
+
+      result =
+        begin
+          provider.move(
+            record: @record,
+            target_column: target_column,
+            target_swimlane: target_swimlane,
+            target_position: target_position,
+            user: current_user,
+            comment: comment
+          )
+        rescue StandardError => e
+          raise unless Rails.env.production?
+          LcpRuby.record_error(e, subsystem: "kanban", record_id: @record.id, presenter: current_presenter.name) if LcpRuby.respond_to?(:record_error)
+          LcpRuby::Kanban::MoveResult.error(code: :unknown, message: e.message)
+        end
+
+      handle_kanban_move_result(result, source_column: source_column, target_column: target_column.to_s, group_by_field: group_by_field, provider_class: provider_class)
+    end
+
+    def reorder
+      unless current_model_definition.positioned?
+        head :not_found
+        return
+      end
+
+      authorize @record, :update?
+      authorize_position_field!
+
+      stale = verify_list_version!
+      return if stale
+
+      position_value = parse_position_param
+      pos_field = current_model_definition.positioning_field
+      @record.update!(pos_field => position_value)
+
+      render json: {
+        position: @record.reload.send(pos_field),
+        list_version: compute_list_version(@record)
+      }
+    end
+
+    def reparent
+      unless current_model_definition.tree?
+        head :not_found
+        return
+      end
+
+      authorize @record, :update?
+      authorize_parent_field_writable!
+
+      stale = verify_tree_version!
+      return if stale
+
+      parent_field = current_model_definition.tree_parent_field
+      new_parent_id = parse_parent_id_param
+
+      @record.send("#{parent_field}=", new_parent_id)
+
+      # Optional position when tree is ordered
+      if params[:position].present? && current_model_definition.tree_ordered?
+        pos_field = current_model_definition.tree_position_field
+        @record.send("#{pos_field}=", parse_position_param)
+      end
+
+      if @record.save
+        render json: {
+          id: @record.id,
+          parent_id: @record[parent_field],
+          tree_version: compute_tree_version
+        }
+      else
+        render json: { errors: @record.errors.full_messages }, status: :unprocessable_content
+      end
+    end
+
+    def inline_create_form
+      target_model_name = params[:target_model]
+      return head(:bad_request) unless target_model_name.present?
+
+      target_presenter = find_presenter_for_inline_create(target_model_name)
+      return head(:not_found) unless target_presenter
+
+      target_model_def = LcpRuby.loader.model_definition(target_model_name)
+      target_class = LcpRuby.registry.model_for(target_model_name)
+      target_record = target_class.new
+
+      authorize_inline_target!(target_model_name, target_record, :create?)
+
+      layout_builder = Presenter::LayoutBuilder.new(target_presenter, target_model_def)
+      @inline_fields = inline_form_fields(layout_builder, target_model_def)
+
+      render partial: "lcp_ruby/resources/inline_create_form",
+             locals: { fields: @inline_fields, model_name: target_model_name },
+             layout: false
+    end
+
+    def inline_create
+      target_model_name = params[:target_model]
+      return head(:bad_request) unless target_model_name.present?
+
+      target_model_def = LcpRuby.loader.model_definition(target_model_name)
+      target_class = LcpRuby.registry.model_for(target_model_name)
+      target_record = target_class.new
+
+      authorize_inline_target!(target_model_name, target_record, :create?)
+
+      permitted = inline_create_params(target_model_def)
+      record = target_class.new(permitted)
+
+      if record.save
+        label_method = resolve_inline_label_method(target_model_def, params[:label_method])
+        render json: { id: record.id, label: resolve_label(record, label_method) }, status: :created
+      else
+        render json: { errors: record.errors.full_messages }, status: :unprocessable_content
+      end
+    end
+
+    private
+
+    # Authorizes a Pundit policy query against an arbitrary target model
+    # that is *different* from the current presenter's model. Goes around
+    # `Controller::Authorization#authorize` (which hardcodes
+    # `current_presenter.model` for policy lookup) by going through
+    # `PolicyFactory.policy_for(target_model_name)` directly. Logs denial
+    # via the standard channel and raises `Pundit::NotAuthorizedError` so
+    # the existing rescue_from chain renders 403/redirect uniformly.
+    # Calls `mark_authorized!` on success so `verify_authorized` is
+    # satisfied.
+    #
+    # @param target_model_name [String] LCP model name
+    # @param target_record [Object] record (or class) passed to
+    #   `policy.new(current_user, target_record)` — use the class for
+    #   class-level queries like `:index?`, an instance for
+    #   record-level queries like `:show?` / `:create?`
+    # @param query [Symbol] policy query method (e.g. :index?, :create?)
+    # @param action_label [String] human-readable action name used in
+    #   the denial log + raised error message
+    def authorize_target!(target_model_name, target_record, query, action_label:)
+      target_policy = Authorization::PolicyFactory
+        .policy_for(target_model_name)
+        .new(current_user, target_record)
+      if target_policy.public_send(query)
+        mark_authorized!
+        return
+      end
+
+      log_authorization_denied(
+        action: action_label,
+        resource: target_model_name,
+        detail: "#{action_label} #{query} on target denied"
+      )
+      raise Pundit::NotAuthorizedError, "#{action_label} #{query} on #{target_model_name} denied"
+    end
+
+    # Authorizes a CRUD action against an inline-create target (e.g. the
+    # inline-create dropdown creating an associated record).
+    def authorize_inline_target!(target_model_name, target_record, query)
+      authorize_target!(target_model_name, target_record, query, action_label: "inline")
+    end
+
+    # Authorizes a read against the target model behind a `/select_options`
+    # request. The user needs `:index?` on the association's target, not
+    # on the presenter model (the presenter access check is handled by
+    # `before_action :authorize_presenter_access`).
+    def authorize_select_options_target!(target_model_name)
+      target_class = LcpRuby.registry.model_for(target_model_name)
+      authorize_target!(target_model_name, target_class, :index?, action_label: "select_options")
+    end
+
+    # Returns an ActiveRecord::Relation scoped through the target model's
+    # Pundit Scope class for `current_user`. Used by `/select_options` and
+    # reverse-cascade `ancestors_for` lookups so that records the user
+    # cannot see never appear in dropdown options or ancestor chains.
+    def scoped_for_user(target_model_name, target_class)
+      Authorization::ScopeResolver.resolve(current_user, target_class, target_model_name)
+    end
+
+    # Raw `.json` / `.csv` index/show endpoints. See docs/design/raw_data_endpoints.md.
+    def raw_index_unsupported?
+      return true if current_page&.standalone? && current_page&.grid?
+      return true if current_page&.composite?
+      return true if api_model?
+      return true if dialog_context?
+
+      false
+    end
+
+    def raw_show_unsupported?
+      return true if current_page&.composite?
+      return true if api_model?
+      return true if dialog_context?
+
+      false
+    end
+
+    def render_raw_index
+      authorize @model_class
+      scope = policy_scope(@model_class)
+      scope = apply_soft_delete_scope(scope)
+      apply_default_saved_filter!
+      load_flat_index(scope)
+
+      allowed = @column_set.visible_table_columns.map { |c| c["field"] }.compact
+      requested = parse_fields_param(params[:fields])
+      return unless validate_fields_subset(requested, allowed)
+
+      selected = requested || allowed
+      generator = Export::DataGenerator.new(
+        records: @records,
+        selected_fields: selected,
+        model_definition: current_model_definition,
+        evaluator: current_evaluator,
+        raw: true
+      )
+
+      envelope = ActiveModel::Type::Boolean.new.cast(params[:envelope])
+      send_raw_payload(generator, base_filename: current_presenter.name, envelope: envelope)
+    end
+
+    def render_raw_show
+      # Mirror the HTML show pipeline: VC values must be resolved before the
+      # generator runs, and association field paths (`?fields=author.name`)
+      # need eager-loading to avoid N+1.
+      load_show_virtual_columns
+      preload_associations(@record, :show)
+
+      allowed = readable_show_field_paths
+      requested = parse_fields_param(params[:fields])
+      return unless validate_fields_subset(requested, allowed)
+
+      selected = requested || allowed
+      generator = Export::DataGenerator.new(
+        records: [ @record ],
+        selected_fields: selected,
+        model_definition: current_model_definition,
+        evaluator: current_evaluator,
+        raw: true
+      )
+
+      send_raw_payload(generator, base_filename: "#{current_presenter.name}-#{@record.id}", single: true)
+    end
+
+    def readable_show_field_paths
+      # Virtual columns aren't in `all_field_names`, so `field_readable?`
+      # always rejects them. Include them unconditionally — they are computed
+      # model expressions, not user-managed data.
+      concrete = current_evaluator.readable_fields.select { |name| current_evaluator.field_readable?(name) }
+      (concrete + current_model_definition.virtual_column_names).uniq
+    end
+
+    def parse_fields_param(raw)
+      return nil if raw.blank?
+
+      tokens = raw.to_s.split(",").map(&:strip).reject(&:empty?).uniq
+      tokens.empty? ? nil : tokens
+    end
+
+    def validate_fields_subset(requested, allowed)
+      return true if requested.nil?
+
+      unknown = requested - allowed
+      return true if unknown.empty?
+
+      message = I18n.t("lcp_ruby.errors.unknown_fields",
+                       fields: unknown.join(", "),
+                       default: "Unknown field(s): %{fields}")
+      render json: { error: message }, status: :bad_request
+      false
+    end
+
+    def send_raw_payload(generator, base_filename:, single: false, envelope: false)
+      respond_to do |format|
+        format.json do
+          payload = generator.to_json_array
+          if single
+            render json: payload.first
+          elsif envelope
+            render json: {
+              data: payload,
+              meta: {
+                total: @records.total_count,
+                page: @records.current_page,
+                per_page: @records.limit_value,
+                total_pages: @records.total_pages
+              }
+            }
+          else
+            render json: payload
+          end
+        end
+        format.csv do
+          send_data generator.to_csv,
+                    type: :csv,
+                    filename: "#{base_filename}.csv",
+                    disposition: "attachment"
+        end
+      end
+    end
+
+    def resolve_transition_label(transition_name)
+      workflow_def = Workflow::Registry.workflow_for_model(current_model_definition.name)
+      return transition_name.to_s.humanize unless workflow_def
+
+      transition = workflow_def.transition(transition_name) || transition_name
+      Workflow::TransitionLabelResolver.resolve(workflow_def.name, transition)
+    end
+
+    def render_create_failure
+      @form_actions = current_form_actions(@record)
+
+      if dialog_context?
+        return render_dialog_form_with_errors
+      end
+
+      @layout_builder = Presenter::LayoutBuilder.new(current_presenter, current_model_definition)
+      render :new, status: :unprocessable_content
+    end
+
+    def render_update_failure
+      @form_actions = current_form_actions(@record)
+
+      if dialog_context?
+        return render_dialog_form_with_errors
+      end
+
+      if current_page&.form_zone
+        load_composite_page_for_form_error
+        render :show, status: :unprocessable_content
+      else
+        @layout_builder = Presenter::LayoutBuilder.new(current_presenter, current_model_definition)
+        load_dirty_record_virtual_columns
+        render :edit, status: :unprocessable_content
+      end
+    end
+
+    def collect_field_paths(nodes, prefix = "")
+      nodes.flat_map do |node|
+        name = (node[:name] || node["name"]).to_s
+        type = (node[:type] || node["type"]).to_s
+        if type == "group"
+          children = node[:children] || node["children"] || []
+          # Custom fields group is a UI grouping only — field paths stay flat
+          is_custom_fields_group = children.any? { |c| c[:custom_field] || c["custom_field"] }
+          child_prefix = if is_custom_fields_group
+            prefix
+          else
+            prefix.empty? ? name : "#{prefix}.#{name}"
+          end
+          collect_field_paths(children, child_prefix)
+        else
+          prefix.empty? ? name : "#{prefix}.#{name}"
+        end
+      end
+    end
+
+    def warn_missing_presenter_config(context)
+      presenter = current_presenter
+      return unless presenter
+
+      case context
+      when :show
+        unless presenter.has_show_sections?
+          Rails.logger.warn("[LcpRuby] Presenter '#{presenter.name}' is rendering show page " \
+                            "but has no show layout configured. The page will be empty or show only custom fields.")
+        end
+      when :form
+        form_sections = presenter.form_config["sections"]
+        unless form_sections.is_a?(Array) && form_sections.any?
+          Rails.logger.warn("[LcpRuby] Presenter '#{presenter.name}' is rendering a form " \
+                            "but has no form sections configured. The form will be empty or show only custom fields.")
+        end
+      end
+    end
+
+    def load_api_index
+      # Translate filter params for API data source
+      field_names = current_model_definition.fields.map(&:name)
+      # SECURITY: to_unsafe_h needed for dynamic filter keys. Validated by ApiFilterTranslator against field_names.
+      raw_filters = params[:f]&.to_unsafe_h || {}
+      supported_ops = @model_class.lcp_data_source&.supported_operators
+
+      filters = DataSource::ApiFilterTranslator.translate(
+        raw_filters,
+        field_names: field_names,
+        supported_operators: supported_ops
+      )
+
+      # Sort
+      sort = if current_sort_field.present?
+        { field: current_sort_field, direction: current_sort_direction }
+      end
+
+      page = (params[:page] || 1).to_i
+      per = effective_per_page
+
+      @api_result = @model_class.lcp_search(filters: filters, sort: sort, page: page, per: per)
+
+      # Wrap in Kaminari-compatible array for view pagination
+      @records = Kaminari.paginate_array(
+        @api_result.to_a,
+        total_count: @api_result.total_count
+      ).page(page).per(per)
+
+      setup_index_view_objects
+    end
+
+    def load_composite_page
+      @active_tab = params[:tab]
+
+      # Set up main zone view objects
+      main_zone = current_page.main_zone
+      if main_zone&.form_zone?
+        # Form zone: authorize edit, set up form context
+        authorize @record, :edit?
+        main_presenter = LcpRuby.loader.presenter_definition(main_zone.presenter)
+        @layout_builder = Presenter::LayoutBuilder.new(main_presenter, current_model_definition)
+        @action_set = Presenter::ActionSet.new(main_presenter, current_evaluator, context: condition_context)
+        @form_actions = current_form_actions(@record)
+        load_edit_virtual_columns
+        preload_associations(@record, :form)
+        @record.strict_loading! if LcpRuby.configuration.strict_loading_enabled?
+      elsif main_zone&.presenter_zone?
+        main_presenter = LcpRuby.loader.presenter_definition(main_zone.presenter)
+        setup_show_view_objects(main_presenter)
+        load_show_virtual_columns
+        preload_associations(@record, :show)
+        @record.strict_loading! if LcpRuby.configuration.strict_loading_enabled?
+      end
+
+      load_secondary_zones(main_zone)
+    end
+
+    # Re-renders the composite page after a form zone validation error.
+    # Uses dirty VCs (singleton methods) to preserve @record's errors and changed attributes.
+    def load_composite_page_for_form_error
+      @active_tab = params[:tab]
+
+      main_zone = current_page.main_zone
+      main_presenter = LcpRuby.loader.presenter_definition(main_zone.presenter)
+      @layout_builder = Presenter::LayoutBuilder.new(main_presenter, current_model_definition)
+      @action_set = Presenter::ActionSet.new(main_presenter, current_evaluator, context: condition_context)
+      @form_actions = current_form_actions(@record)
+      load_dirty_record_virtual_columns
+
+      load_secondary_zones(main_zone)
+    end
+
+    def load_index_composite
+      build_filter_form(@index_composite_page)
+
+      # Master-detail: extract selection and active tab from URL params
+      if @index_composite_page.master_detail?
+        @selected_id = params[:selected].presence
+        @active_tab = params[:tab].presence
+      end
+
+      scope = policy_scope(@model_class)
+      scope = apply_soft_delete_scope(scope)
+
+      # Apply filter_form: + scope_filters: to the main index scope.
+      # No-op when the page has no filter_form / scope_filters declarations.
+      scope = Widgets::ScopeApplicator.apply_filter_form(scope, @model_class, @filter_form)
+      scope = Widgets::ScopeApplicator.apply_scope_filters(scope, @model_class, @scope_filter_set)
+
+      apply_default_saved_filter!
+
+      case current_presenter.index_layout
+      when :tree
+        load_tree_index(scope) if current_model_definition.tree?
+      when :tiles
+        load_flat_index(scope)
+      else
+        load_flat_index(scope)
+      end
+
+      # For master-detail, the selection zone is the "primary" (rendered by the index pipeline),
+      # so exclude it from secondary zones. For standard index composites, exclude the main zone.
+      primary_zone = if @index_composite_page.master_detail?
+        @index_composite_page.selection_zone
+      else
+        @index_composite_page.main_zone
+      end
+      load_secondary_zones(primary_zone, page: @index_composite_page)
+    end
+
+    # Find an explicit index composite page for the current model
+    def find_index_composite_for_model
+      return nil unless current_page&.model
+
+      # Only search for index composites when on the primary page of a view group
+      # (or no view group). Non-primary views (e.g., tiles alternative) must not be hijacked.
+      vg = current_view_group
+      return nil if vg && !vg.primary_page?(current_page.name)
+
+      LcpRuby.loader.page_definitions.each_value do |page|
+        next if page == current_page
+        next unless page.model == current_page.model
+
+        return page if page.index_composite?
+      end
+      nil
+    end
+
+    # Builds the per-request FilterForm + ScopeFilterSet for the
+    # current page. Both are nil if the page declares no filters,
+    # letting downstream code short-circuit with `@filter_form&.any?`.
+    def build_filter_form(page)
+      return unless page
+
+      @filter_form = Pages::FilterForm.new(
+        page: page, params: params, current_user: current_user
+      ) if page.respond_to?(:filter_form_definition) && page.filter_form_definition.any?
+
+      @scope_filter_set = Pages::ScopeFilterSet.new(
+        page: page, params: params
+      ) if page.respond_to?(:scope_filter_definitions) && page.scope_filter_definitions.any?
+    end
+
+    def broadcast_model_change(model_name)
+      return unless defined?(Turbo::StreamsChannel) && defined?(ActionCable)
+
+      Turbo::StreamsChannel.broadcast_refresh_to("lcp_model_#{model_name}")
+    rescue StandardError => e
+      raise unless Rails.env.production?
+      LcpRuby.record_error(e, subsystem: "broadcast", model: model_name)
+    end
+
+    def load_dashboard
+      build_filter_form(current_page)
+
+      @zone_data = {}
+      current_page.zones.each do |zone|
+        next unless zone.widget? || zone.presenter_zone?
+        next unless zone_accessible?(zone)
+
+        @zone_data[zone] = resolve_zone_data(zone)
+      end
+    end
+
+    def load_flat_index(scope)
+      scope = apply_advanced_search(scope)
+      scope = apply_sort(scope)
+      scope = apply_virtual_columns(scope)
+
+      # Load saved filters for the UI
+      if SavedFilters::Registry.available? && current_presenter.saved_filters_enabled?
+        @saved_filters = SavedFilters::Resolver.visible_filters(
+          presenter_name: current_presenter.name,
+          user: current_user,
+          evaluator: current_evaluator
+        )
+        @slot_locals = (@slot_locals || {}).merge(
+          saved_filters: @saved_filters,
+          active_saved_filter: @active_saved_filter,
+          saved_filter_warnings: @saved_filter_warnings
+        )
+      end
+
+      if @filter_form&.any?
+        @slot_locals = (@slot_locals || {}).merge(
+          page_parameter_fields: @filter_form.fields.map(&:name)
+        )
+      end
+
+      @summaries = compute_summaries(scope) if summary_columns_present?
+      compute_summary_bar(scope) if current_presenter.summary_enabled?
+
+      strategy = resolve_loading_strategy(:index)
+      scope = strategy.apply(scope)
+      scope = scope.strict_loading if LcpRuby.configuration.strict_loading_enabled?
+
+      @records = scope.page(params[:page]).per(effective_per_page)
+
+      # Batch-preload API associations after AR scope materializes
+      strategy.apply_api_preloads(@records.to_a) if strategy.api_preloads.any?
+
+      # GROUP BY scopes break Kaminari's .count (returns Hash instead of Integer).
+      # Pre-compute total via a clean scope and inject it.
+      if @has_grouped_virtual_columns
+        total = scope.except(:select, :group, :joins).distinct.count(:id)
+        @records.define_singleton_method(:total_count) { total }
+      end
+
+      setup_index_view_objects
+    end
+
+    # Maps a Kanban::MoveResult to the HTTP response shape declared in
+    # docs/design/kanban_view.md → "Drag endpoint". On success: recompute
+    # counts for source + target columns only, broadcast model change, and
+    # emit `kanban.card_moved` instrumentation.
+    def handle_kanban_move_result(result, source_column:, target_column:, group_by_field:, provider_class:)
+      if result.ok?
+        counts = recompute_kanban_counts(source: source_column, target: target_column, group_by_field: group_by_field)
+        broadcast_model_change(current_model_definition.name)
+        ActiveSupport::Notifications.instrument(
+          "kanban.card_moved",
+          model: current_model_definition.name,
+          from_col: source_column,
+          to_col: target_column,
+          user_id: current_user&.id,
+          provider: provider_class.name
+        )
+        render json: {
+          ok: true,
+          record_id: @record.id,
+          column: target_column,
+          counts: counts
+        }
+        return
+      end
+
+      case result.code
+      when :comment_required
+        render json: { error: "comment_required", transition_name: result.details[:transition_name], message: result.message }, status: :unprocessable_content
+      when :no_transition, :guard_failed, :wip_exceeded, :field_readonly, :validation, :not_allowed
+        render json: { error: result.code.to_s, message: result.message, details: result.details }, status: :unprocessable_content
+      when :forbidden
+        render json: { error: "forbidden", message: result.message }, status: :forbidden
+      when :conflict
+        render json: { error: "conflict", message: result.message }, status: :conflict
+      else
+        render json: { error: "unknown", message: result.message }, status: :internal_server_error
+      end
+    end
+
+    # Recomputes column counts after a successful move. Per spec: only the
+    # affected columns (source + target) — not the whole board.
+    def recompute_kanban_counts(source:, target:, group_by_field:)
+      return {} if group_by_field.blank?
+
+      affected = [ source, target ].compact.uniq.reject(&:blank?)
+      return {} if affected.empty?
+
+      scope = policy_scope(@model_class)
+      scope = apply_soft_delete_scope(scope)
+      grouped = scope.where(group_by_field => affected).group(group_by_field).count
+      affected.each_with_object({}) { |val, h| h[val.to_s] = grouped[val].to_i }
+    rescue StandardError => e
+      raise unless Rails.env.production?
+      LcpRuby.record_error(e, subsystem: "kanban_counts") if LcpRuby.respond_to?(:record_error)
+      {}
+    end
+
+    # Resolves the configured provider, applies the filter pipeline + the
+    # configured eager-loading strategy, then asks the provider for `columns`
+    # and `fetch_records`. Builds `@kanban_board` for `_kanban_index.html.erb`.
+    # When `params[:kanban_column]` is present, renders only that column's
+    # Turbo Frame ("Load more" pagination contract).
+    def load_kanban_index(scope)
+      scope = apply_advanced_search(scope)
+      scope = apply_sort(scope)
+      scope = apply_virtual_columns(scope)
+
+      strategy = resolve_loading_strategy(:index)
+      scope = strategy.apply(scope)
+      scope = scope.strict_loading if LcpRuby.configuration.strict_loading_enabled?
+
+      provider_class = kanban_provider_class
+      @kanban_provider = build_kanban_provider(provider_class)
+
+      context = {
+        params: params.to_unsafe_h,
+        locale: I18n.locale,
+        saved_filter: @active_saved_filter,
+        view_group: @active_view_group,
+        presenter_slug: current_presenter.slug,
+        kanban_column: params[:kanban_column].presence,
+        kanban_page: params[:kanban_page].presence&.to_i
+      }
+
+      all_columns = @kanban_provider.columns(scope: scope, user: current_user, context: context)
+
+      cols_to_fetch =
+        if context[:kanban_column]
+          col = all_columns.find { |c| c.value.to_s == context[:kanban_column].to_s }
+          [ col ].compact
+        else
+          all_columns
+        end
+
+      records_by_value = if cols_to_fetch.empty?
+        {}
+      else
+        @kanban_provider.fetch_records(
+          scope: scope,
+          columns: cols_to_fetch,
+          user: current_user,
+          context: context
+        )
+      end
+
+      if strategy.api_preloads.any?
+        all_records = records_by_value.values.flatten
+        strategy.apply_api_preloads(all_records) if all_records.any?
+      end
+
+      cells = records_by_value.each_with_object({}) do |(col_value, records), h|
+        h[[ col_value, :_default ]] = records
+      end
+
+      @kanban_board = LcpRuby::Kanban::Board.new(
+        columns: all_columns,
+        cells: cells,
+        provider: @kanban_provider
+      )
+      @kanban_columns_to_render = cols_to_fetch
+      @kanban_partial_request = context[:kanban_column].present?
+
+      setup_index_view_objects
+
+      # Lazy-load contract: when ?kanban_column=<value> is set, return ONLY
+      # that column's Turbo Frame, without page chrome.
+      if @kanban_partial_request
+        target = cols_to_fetch.first
+        if target
+          render partial: "lcp_ruby/resources/kanban_column",
+                 locals: { column: target, board: @kanban_board },
+                 layout: false
+        else
+          head :not_found
+        end
+      end
+    end
+
+    def kanban_provider_class
+      current_presenter.kanban_config["provider"]&.safe_constantize \
+        || LcpRuby::Kanban::DefaultProvider
+    end
+
+    def build_kanban_provider(provider_class)
+      provider_class.new(
+        config: current_presenter.kanban_config,
+        model_definition: current_model_definition
+      )
+    end
+
+    def load_grouped_index(scope)
+      scope = apply_advanced_search(scope)
+      scope = GroupedQuery::Builder.apply(scope, current_presenter, current_model_definition)
+      scope = apply_grouped_sort(scope)
+
+      if current_presenter.group_limit
+        @records = scope.limit(current_presenter.group_limit).to_a
+        @records = GroupedQuery::ResultWrapper.wrap(@records, current_presenter, current_model_definition)
+        @grouped_limited = true
+      else
+        # Kaminari GROUP BY fix: count groups via subquery instead of .count.length
+        paginated = scope.page(params[:page]).per(effective_per_page)
+        count_scope = scope.except(:select, :order)
+        total_groups = scope.connection.select_value(
+          "SELECT COUNT(*) FROM (#{count_scope.select('1').to_sql}) AS grouped_count"
+        ).to_i
+        paginated.define_singleton_method(:total_count) { total_groups }
+
+        @records = GroupedQuery::ResultWrapper.wrap(paginated, current_presenter, current_model_definition)
+
+        # Restore Kaminari pagination methods lost during Array wrapping
+        cp = paginated.current_page
+        lv = paginated.limit_value
+        tp = paginated.total_pages
+        tg = total_groups
+        @records.define_singleton_method(:current_page) { cp }
+        @records.define_singleton_method(:limit_value) { lv }
+        @records.define_singleton_method(:total_pages) { tp }
+        @records.define_singleton_method(:total_count) { tg }
+      end
+
+      setup_index_view_objects
+      @fk_map = {}
+    end
+
+    def apply_grouped_sort(scope)
+      sort_field = params[:sort] || current_presenter.index_config.dig("default_sort", "field")
+      return scope unless sort_field
+
+      direction = params[:direction] || current_presenter.index_config.dig("default_sort", "direction") || "asc"
+      direction = "asc" unless %w[asc desc].include?(direction.to_s.downcase)
+
+      # Validate sort field is a defined column
+      valid_columns = current_presenter.table_columns.map { |c| c["field"] }
+      return scope unless valid_columns.include?(sort_field.to_s)
+
+      conn = scope.connection
+      strategy = Sort::EnumSortOrder.resolve_strategy(sort_field, current_presenter, current_model_definition)
+      if strategy == "definition_order"
+        col_config = current_presenter.table_columns.find { |c| c["field"] == sort_field.to_s }
+        source_field = col_config&.dig("group_field") || sort_field.to_s
+        enum_field = Sort::EnumSortOrder.enum_field_for(source_field, current_model_definition)
+        case_sql = Sort::EnumSortOrder.case_when_sql(enum_field, current_model_definition.table_name, conn)
+        scope.order(Arel.sql("#{case_sql} #{direction}"))
+      else
+        scope.order(Arel.sql("#{conn.quote_column_name(sort_field)} #{direction}"))
+      end
+    end
+
+    def load_tree_index(scope)
+      parent_field = current_model_definition.tree_parent_field
+      scope = scope.all unless scope.is_a?(ActiveRecord::Relation)
+      scope = apply_virtual_columns(scope)
+
+      # Detect if search is active
+      @search_active = search_active?
+
+      if @search_active
+        # Run search pipeline to get matching IDs
+        filtered_scope = apply_advanced_search(scope)
+        filtered_scope = apply_sort(filtered_scope)
+        @match_ids = Set.new(filtered_scope.pluck(:id))
+
+        # Load all records to build complete tree with ancestor context
+        all_records = scope.to_a
+        @children_map, @roots = build_filtered_tree(all_records, @match_ids, parent_field)
+      else
+        # Load all records (no pagination for tree view)
+        sorted = apply_sort(scope)
+        sorted = sorted.all unless sorted.is_a?(ActiveRecord::Relation)
+        all_records = sorted.to_a
+        @children_map = all_records.group_by { |r| r[parent_field] }
+        @roots = @children_map[nil] || []
+        @match_ids = nil
+      end
+
+      @records = all_records
+
+      @tree_version = compute_tree_version if current_presenter.reparentable?
+
+      # Precompute subtree IDs from in-memory children_map (avoids N+1 CTE queries per row)
+      if current_presenter.reparentable?
+        @subtree_ids_map = precompute_subtree_ids(@children_map)
+      end
+
+      setup_index_view_objects
+    end
+
+    # Inject virtual column subqueries/expressions into the scope for index/tree views.
+    def apply_virtual_columns(scope)
+      vc_names = collect_virtual_column_names(:index)
+      return scope if vc_names.empty?
+
+      scope, _service_only, @has_grouped_virtual_columns = VirtualColumns::Builder.apply(
+        scope, current_model_definition, vc_names.to_a, current_user: current_user
+      )
+
+      scope
+    end
+
+    # Collect virtual column names needed for a given context.
+    def collect_virtual_column_names(context)
+      VirtualColumns::Collector.collect(
+        presenter_def: current_presenter,
+        model_def: current_model_definition,
+        context: context,
+        sort_field: context == :index ? params[:sort] : nil
+      )
+    end
+
+    def effective_per_page
+      options = current_presenter.per_page_options
+      if options.is_a?(Array) && params[:per_page].present?
+        requested = params[:per_page].to_i
+        return requested if options.include?(requested)
+      end
+      current_presenter.per_page
+    end
+
+    def compute_summary_bar(scope)
+      fields = current_presenter.summary_config["fields"]
+      return unless fields.is_a?(Array) && fields.any?
+
+      col_names = @model_class.column_names
+      summary_bar = fields.filter_map do |field_config|
+        field_name = field_config["field"]
+        function = field_config["function"]
+        next unless field_name && function
+        next unless col_names.include?(field_name)
+
+        # Strip aggregate subquery columns that would produce invalid SQL
+        # inside COUNT/SUM/etc.
+        plain = scope.unscope(:select)
+        value = case function
+        when "sum"   then plain.sum(field_name)
+        when "avg"   then plain.average(field_name)
+        when "count" then plain.count
+        when "min"   then plain.minimum(field_name)
+        when "max"   then plain.maximum(field_name)
+        end
+
+        { value: value, function: function, config: field_config }
+      end
+
+      @slot_locals = (@slot_locals || {}).merge(summary_bar: summary_bar)
+    end
+
+    # Load virtual column values for a show page record.
+    def load_show_virtual_columns
+      load_record_virtual_columns(:show)
+    end
+
+    # Load virtual column values for an edit page record.
+    def load_edit_virtual_columns
+      load_record_virtual_columns(:edit)
+    end
+
+    # Load virtual columns onto a dirty record (update validation failure).
+    # Loads a clean record with VC expressions and copies values as singleton methods.
+    def load_dirty_record_virtual_columns
+      load_record_virtual_columns(:edit, dirty: true)
+    end
+
+    # Shared loader: re-queries @record with VC subqueries and resolves service VCs.
+    # When dirty: true, copies values as singleton methods instead of replacing @record.
+    def load_record_virtual_columns(context, dirty: false)
+      vc_names = collect_virtual_column_names(context)
+      return if vc_names.empty?
+
+      scope = @model_class.where(id: @record.id)
+      scope, service_only, _grouped = VirtualColumns::Builder.apply(
+        scope, current_model_definition, vc_names.to_a, current_user: current_user
+      )
+
+      clean_record = scope.first
+
+      if dirty
+        (vc_names - service_only.to_set).each do |name|
+          value = clean_record&.public_send(name)
+          @record.define_singleton_method(name) { value }
+        end
+      elsif clean_record
+        @record = clean_record
+      end
+
+      resolve_service_virtual_columns(@record, service_only)
+    end
+
+    # Compute service virtual column values and define singleton methods on the record.
+    def resolve_service_virtual_columns(record, service_names)
+      return if service_names.blank?
+
+      service_names.each do |vc_name|
+        vc_def = current_model_definition.virtual_column(vc_name)
+        next unless vc_def
+
+        service = Services::Registry.lookup_vc_service(vc_def.service)
+        next unless service
+
+        value = service.call(record, options: vc_def.options)
+        record.define_singleton_method(vc_name) { value }
+      end
+    end
+
+    def search_active?
+      params[:qs].present? || params[:f].present? || params[:filter].present? || params[:cf].present?
+    end
+
+    def build_filtered_tree(all_records, match_ids, parent_field)
+      # Build lookup
+      by_id = all_records.index_by(&:id)
+
+      # Collect ancestor IDs for all matching records
+      ancestor_ids = Set.new
+      match_ids.each do |mid|
+        record = by_id[mid]
+        next unless record
+
+        pid = record[parent_field]
+        while pid.present? && !ancestor_ids.include?(pid)
+          ancestor_ids << pid
+          parent_record = by_id[pid]
+          break unless parent_record
+          pid = parent_record[parent_field]
+        end
+      end
+
+      display_ids = match_ids | ancestor_ids
+      display_records = all_records.select { |r| display_ids.include?(r.id) }
+
+      children_map = display_records.group_by { |r| r[parent_field] }
+      roots = children_map[nil] || []
+
+      [ children_map, roots ]
+    end
+
+    # Build a Hash { record_id => "id1,id2,..." } of subtree IDs from the in-memory children_map.
+    # This replaces per-row `record.subtree_ids` calls that each fire a recursive CTE query.
+    def precompute_subtree_ids(children_map)
+      result = {}
+      collect_subtree = ->(record_id) do
+        ids = [ record_id ]
+        (children_map[record_id] || []).each { |child| ids.concat(collect_subtree.call(child.id)) }
+        ids
+      end
+      children_map.each_value do |records|
+        records.each do |record|
+          result[record.id] = collect_subtree.call(record.id).join(",") unless result.key?(record.id)
+        end
+      end
+      result
+    end
+
+    def compute_tree_version
+      parent_field = current_model_definition.tree_parent_field
+      pairs = @model_class.order(:id).pluck(:id, parent_field)
+      Digest::SHA256.hexdigest(pairs.map { |id, pid| "#{id}:#{pid}" }.join(","))
+    end
+
+    def no_explicit_filter_params?
+      params[:f].blank? && params[:filter].blank? && params[:qs].blank? &&
+        params[:saved_filter].blank? && params[:scope].blank?
+    end
+
+    # Resolve the user's default saved filter (if any) and set params[:saved_filter]
+    # so the downstream pipeline applies it. Shared by HTML and raw `.json` / `.csv` paths.
+    def apply_default_saved_filter!
+      return unless no_explicit_filter_params?
+      return unless SavedFilters::Registry.available? && current_presenter.saved_filters_enabled?
+
+      default = SavedFilters::Resolver.default_filter_for(
+        presenter_name: current_presenter.name,
+        user: current_user,
+        evaluator: current_evaluator
+      )
+      params[:saved_filter] = default.id.to_s if default
+    end
+
+    VALID_REDIRECT_TARGETS = %w[index show edit new].freeze
+
+    def redirect_path_for(action, record)
+      target = current_presenter.options&.dig("redirect_after", action)
+
+      if target && !VALID_REDIRECT_TARGETS.include?(target)
+        Rails.logger.warn("[LcpRuby] Invalid redirect_after target '#{target}' for action '#{action}' " \
+                          "in presenter '#{current_presenter.name}', falling back to 'show'")
+        target = nil
+      end
+
+      case target
+      when "index" then resources_path
+      when "show" then resource_path(record)
+      when "edit" then edit_resource_path(record)
+      when "new" then new_resource_path
+      else resource_path(record)
+      end
+    end
+
+    def purge_removed_attachments!(record)
+      current_model_definition.fields.select(&:attachment?).each do |field|
+        remove_key = "remove_#{field.name}"
+        next unless params[:record]&.dig(remove_key) == "1"
+
+        attachment = record.send(field.name)
+        attachment.purge if attachment.attached?
+      end
+    end
+
+    def find_form_field_config(field_name)
+      return nil unless field_name.present?
+
+      if current_presenter
+        layout_builder = Presenter::LayoutBuilder.new(current_presenter, current_model_definition)
+        config = layout_builder.form_sections
+          .flat_map { |s| s["fields"] || [] }
+          .find { |f| f["field"] == field_name }
+        return config if config
+
+        sp_config = find_search_parameter_field_config(field_name)
+        return sp_config if sp_config
+      end
+
+      # Filter-form fallback (PR 5): dashboards have no current_presenter,
+      # so the lookup walks current_page.filter_form_definition via the
+      # FilterForm enrichment helper. Spec § 5 step 12 (additive
+      # fallback chain entry — does not displace the presenter or
+      # search-parameter sources).
+      find_filter_form_field_config(field_name)
+    end
+
+    def find_filter_form_field_config(field_name)
+      return nil unless current_page&.respond_to?(:filter_form_definition)
+      return nil if current_page.filter_form_definition.blank?
+
+      ff = @filter_form ||= Pages::FilterForm.new(
+        page: current_page, params: params, current_user: current_user
+      )
+      config = ff.field_config_for(field_name)
+      config.empty? ? nil : config
+    end
+
+    def find_search_parameter_field_config(field_name)
+      return nil unless current_presenter.has_search_parameters?
+
+      param = current_presenter.search_parameters.find { |p|
+        p.association_select? && p.field == field_name
+      }
+      return nil unless param
+
+      assoc = current_model_definition.belongs_to_fk_map[field_name]
+      return nil unless assoc
+
+      { "field" => field_name, "association" => assoc, "input_options" => param.to_input_options.merge("search" => true) }
+    end
+
+    def resolve_association_for_field(field_name)
+      current_model_definition.associations.find { |a| a.foreign_key == field_name.to_s }
+    end
+
+    # Walk up the depends_on chain from a field and resolve parent values.
+    # Returns an array of {field, value, label} hashes from the immediate parent
+    # up to the root of the dependency chain.
+    def resolve_field_ancestors(field_name, value_id)
+      ancestors = []
+      seen = Set.new
+      current_field = field_name.to_s
+      # Keep value as a string — the join column may be a business key
+      # like "EUR" or "0042" which must not be coerced to integer.
+      current_value = value_id.to_s
+
+      loop do
+        break if seen.include?(current_field)
+        seen << current_field
+
+        # Find the field config for the current field
+        field_config = find_form_field_config(current_field)
+        break unless field_config
+
+        input_options = field_config["input_options"] || {}
+        depends_on = input_options["depends_on"]
+        break unless depends_on
+
+        parent_field = depends_on["field"]
+        parent_fk = depends_on["foreign_key"]
+        break unless parent_field && parent_fk
+
+        # Look up the current record to get the parent FK value
+        assoc = field_config["association"] || resolve_association_for_field(current_field)
+        break unless assoc&.lcp_model?
+
+        target_class = LcpRuby.registry.model_for(assoc.target_model)
+        join_col = LcpRuby::AssociationJoinColumn.for(assoc, target_class).to_sym
+        record = scoped_for_user(assoc.target_model, target_class).find_by(join_col => current_value)
+        break unless record
+
+        parent_value = record.respond_to?(parent_fk) ? record.send(parent_fk) : nil
+        break unless parent_value.present?
+
+        # Resolve the parent's label. When the parent is an lcp_model
+        # association and the user cannot see the parent record (because
+        # the target Pundit::Scope filters it out), break the chain
+        # rather than leaking the parent_value. Without this guard,
+        # ancestors_for would expose the IDs of records the user is
+        # forbidden to read, just by walking depends_on:.
+        parent_field_config = find_form_field_config(parent_field)
+        parent_assoc = parent_field_config && (parent_field_config["association"] || resolve_association_for_field(parent_field))
+        parent_label = parent_value.to_s
+        if parent_assoc&.lcp_model?
+          parent_input_options = (parent_field_config["input_options"] || {}) if parent_field_config
+          label_method = ((parent_input_options && parent_input_options["label_method"]) || resolve_default_label_method(parent_assoc)).to_sym
+          parent_class = LcpRuby.registry.model_for(parent_assoc.target_model)
+          parent_join_col = LcpRuby::AssociationJoinColumn.for(parent_assoc, parent_class).to_sym
+          parent_record = scoped_for_user(parent_assoc.target_model, parent_class).find_by(parent_join_col => parent_value)
+          break unless parent_record
+          parent_label = resolve_label(parent_record, label_method)
+        end
+
+        ancestors << { field: parent_field, value: parent_value, label: parent_label }
+
+        # Move up the chain
+        current_field = parent_field
+        current_value = parent_value.to_s
+      end
+
+      ancestors
+    end
+
+    def build_select_options_json(assoc, input_options)
+      depends_on_values = extract_depends_on_from_params(input_options)
+      oq = build_options_query(assoc, input_options, role: current_user_role_name,
+                               depends_on_values: depends_on_values, user: current_user)
+      format_options_for_json(oq, input_options)
+    end
+
+    def extract_depends_on_from_params(input_options)
+      depends_on = input_options["depends_on"]
+      return {} unless depends_on && params[:depends_on].present?
+
+      field = depends_on["field"]
+      { field => params[:depends_on][field] }
+    end
+
+    def build_select_options_search(assoc, input_options)
+      target_class = LcpRuby.registry.model_for(assoc.target_model)
+      depends_on_values = extract_depends_on_from_params(input_options)
+      query = apply_option_scope(target_class, input_options, role: current_user_role_name,
+                                 user: current_user, target_model_name: assoc.target_model)
+      query = query.where(input_options["filter"]) if input_options["filter"]
+
+      depends_on = input_options["depends_on"]
+      if depends_on && depends_on_values.present?
+        fk = depends_on["foreign_key"]
+        parent_value = depends_on_values[depends_on["field"]]
+        query = query.where(fk => parent_value) if fk && parent_value.present?
+      end
+
+      # Fulltext LIKE search on configured search_fields
+      search_fields = Array(input_options["search_fields"])
+      if params[:q].present? && search_fields.any?
+        conn = target_class.connection
+        conditions = search_fields
+          .select { |f| target_class.column_names.include?(f.to_s) }
+          .map { |f| "#{conn.quote_column_name(f)} LIKE :q" }
+          .join(" OR ")
+        sanitized_q = ActiveRecord::Base.sanitize_sql_like(params[:q])
+        query = query.where(conditions, q: "%#{sanitized_q}%") if conditions.present?
+      end
+
+      query = query.order(input_options["sort"]) if input_options["sort"]
+
+      label_method = (input_options["label_method"] || resolve_default_label_method(assoc)).to_sym
+      join_col = LcpRuby::AssociationJoinColumn.for(assoc, target_class).to_sym
+      disabled_ids = resolve_disabled_values(assoc, input_options)
+
+      # Pagination
+      page = [ (params[:page] || 1).to_i, 1 ].max
+      per_page = [ [ (params[:per_page] || input_options["per_page"] || 25).to_i, 1 ].max, 100 ].min
+      offset = (page - 1) * per_page
+
+      total = query.count
+      records = query.offset(offset).limit(per_page)
+
+      options = records.map do |r|
+        value = r.public_send(join_col)
+        opt = { value: value, label: resolve_label(r, label_method) }
+        opt[:disabled] = true if disabled_ids.include?(value)
+        opt
+      end
+
+      {
+        options: options,
+        has_more: (offset + per_page) < total,
+        total: total
+      }
+    end
+
+    def build_tree_select_options(assoc, input_options)
+      target_class = LcpRuby.registry.model_for(assoc.target_model)
+      query = apply_option_scope(target_class, input_options, role: current_user_role_name,
+                                 user: current_user, target_model_name: assoc.target_model)
+      query = query.order(input_options["sort"]) if input_options["sort"]
+
+      max = (input_options["max_options"] || MAX_SELECT_OPTIONS).to_i
+      query = query.limit(max)
+
+      label_method = (input_options["label_method"] || resolve_default_label_method(assoc)).to_sym
+      parent_field = input_options["parent_field"] || "parent_id"
+      max_depth = (input_options["max_depth"] || 10).to_i
+      join_col = LcpRuby::AssociationJoinColumn.for(assoc, target_class).to_sym
+
+      records = query.to_a
+      build_tree_json(records, parent_field, label_method, max_depth, join_col: join_col)
+    end
+
+    # Check if the association's target model is API-backed.
+    def api_target_model?(assoc)
+      target_class = LcpRuby.registry.model_for(assoc.target_model)
+      target_class.respond_to?(:lcp_api_model?) && target_class.lcp_api_model?
+    rescue LcpRuby::RegistryError
+      false
+    end
+
+    # Build select options for an API-backed target model via its data source.
+    def build_api_select_options(assoc, input_options)
+      target_class = LcpRuby.registry.model_for(assoc.target_model)
+      label_method = input_options["label_method"] || resolve_default_label_method(assoc)
+      limit = (input_options["max_options"] || MAX_SELECT_OPTIONS).to_i
+
+      options = target_class.lcp_select_options(
+        search: params[:q],
+        sort: input_options["sort"],
+        label_method: label_method,
+        limit: limit
+      )
+
+      if params[:q].present? || params[:page].present?
+        { options: options, has_more: false, total: options.size }
+      else
+        options
+      end
+    end
+
+    # Internal recursion stays on r.id because the target's parent_field
+    # references the actual id column. The emitted payload carries
+    # `value: r.send(join_col)` which is what the JS tree_select
+    # controller reads — see form_helper.rb#build_tree_data for the
+    # matching schema.
+    def build_tree_json(records, parent_field, label_method, max_depth, parent_id = nil, depth = 0, join_col: :id)
+      return [] if depth >= max_depth
+
+      records.select { |r| r.send(parent_field) == parent_id }.map do |r|
+        {
+          value: r.public_send(join_col),
+          label: resolve_label(r, label_method),
+          children: build_tree_json(records, parent_field, label_method, max_depth, r.id, depth + 1, join_col: join_col)
+        }
+      end
+    end
+
+    def current_user_role_name
+      current_user&.send(LcpRuby.configuration.role_method).to_s
+    rescue NoMethodError
+      ""
+    end
+
+    def summary_columns_present?
+      current_presenter.table_columns.any? { |c| c["summary"].present? }
+    end
+
+    def compute_summaries(scope)
+      columns = current_presenter.table_columns.select { |c| c["summary"].present? }
+      columns.each_with_object({}) do |col, h|
+        field = col["field"]
+        next unless @model_class.column_names.include?(field)
+
+        case col["summary"]
+        when "sum"   then h[field] = scope.sum(field)
+        when "avg"   then h[field] = scope.average(field)
+        when "count" then h[field] = scope.where.not(field => nil).count
+        end
+      end
+    end
+
+    def validate_association_values!(record)
+      layout_builder = Presenter::LayoutBuilder.new(current_presenter, current_model_definition)
+      layout_builder.form_sections
+        .flat_map { |s| s["fields"] || [] }
+        .each do |field_config|
+          field_name = field_config["field"]
+          next unless field_name
+
+          assoc = field_config["association"] || field_config["multi_select_association"]
+          next unless assoc&.lcp_model?
+
+          submitted_value = record.public_send(field_name)
+          next if submitted_value.blank?
+
+          input_options = field_config["input_options"] || {}
+
+          # Build the allowed options using the same logic as the select builder
+          options = build_select_options_json(assoc, input_options)
+          allowed_ids = extract_allowed_ids(options)
+          disabled_ids = resolve_disabled_values(assoc, input_options)
+
+          # Do not coerce — the join column may be a string business
+          # key. Comparison happens as strings on both sides below.
+          submitted_ids = Array(submitted_value)
+          allowed_ids_s = allowed_ids.map(&:to_s)
+          disabled_ids_s = disabled_ids.map(&:to_s)
+
+          submitted_ids.each do |sid|
+            sid_s = sid.to_s
+            unless allowed_ids_s.include?(sid_s) && !disabled_ids_s.include?(sid_s)
+              # Allow legacy scope values on existing records (edit)
+              if input_options["legacy_scope"] && !record.new_record?
+                legacy = resolve_legacy_record(assoc, input_options, sid)
+                next if legacy
+              end
+
+              record.errors.add(field_name, I18n.t("lcp_ruby.form.errors.contains_not_allowed"))
+              break
+            end
+          end
+        end
+    end
+
+    def extract_allowed_ids(options)
+      ids = Set.new
+      if options.is_a?(Array) && options.first.is_a?(Hash) && options.first.key?(:group)
+        # Grouped format: [{group: "...", options: [{value:, label:}]}]
+        # Do NOT coerce o[:value] — string business keys must
+        # round-trip unchanged.
+        options.each { |g| g[:options].each { |o| ids << o[:value] } }
+      elsif options.is_a?(Array)
+        # Flat format: [{value:, label:}]
+        options.each { |o| ids << o[:value] }
+      end
+      ids
+    end
+
+    def build_nested_records(record)
+      sections = current_presenter.form_config["sections"] || []
+      sections.each do |section|
+        next unless section["type"] == "nested_fields"
+
+        if section["json_field"]
+          # Pre-populate empty JSON items for min requirement
+          json_field_name = section["json_field"]
+          min = (section["min"] || 0).to_i
+          next unless min > 0
+
+          current_items = record.respond_to?(json_field_name) ? (record.send(json_field_name) || []) : []
+          if current_items.size < min
+            empty_items = (min - current_items.size).times.map { {} }
+            record.send("#{json_field_name}=", current_items + empty_items)
+          end
+          next
+        end
+
+        assoc_name = section["association"]
+        min = (section["min"] || 0).to_i
+        next unless min > 0
+
+        if record.respond_to?(assoc_name) && record.public_send(assoc_name).size < min
+          existing_count = record.public_send(assoc_name).size
+          pos = sortable_position_field(section)
+          (min - existing_count).times do |i|
+            new_record = record.public_send(assoc_name).build
+            if pos && new_record.respond_to?("#{pos}=")
+              new_record[pos] = existing_count + i
+            end
+          end
+        end
+      end
+    end
+
+    # Process json_field sections: parse hash-of-hashes params into array of hashes.
+    # For model-backed sections (target_model), wraps items in JsonItemWrapper
+    # for type coercion and validation.
+    def process_json_field_params(record)
+      layout_builder = Presenter::LayoutBuilder.new(current_presenter, current_model_definition)
+      sections = layout_builder.form_sections
+
+      sections.each do |section|
+        next unless section["type"] == "nested_fields" && section["json_field"]
+
+        json_field_name = section["json_field"]
+        raw = params.dig(:record, json_field_name)
+        next unless raw.is_a?(ActionController::Parameters) || raw.is_a?(Hash)
+
+        # Collect allowed field names from the section (including sub_sections)
+        allowed_keys = (section["fields"] || []).map { |f| f["field"] }.compact
+        (section["sub_sections"] || []).each do |ss|
+          allowed_keys += (ss["fields"] || []).map { |f| f["field"] }.compact
+        end
+        allowed_keys.uniq!
+        target_model_def = section["target_model_definition"]
+
+        items = []
+        raw.each_value.with_index do |item_params, idx|
+          item_params = ActionController::Parameters.new(item_params) unless item_params.is_a?(ActionController::Parameters)
+          item_params = item_params.permit(*allowed_keys, :_destroy)
+          next if item_params[:_destroy].to_s.in?(%w[1 true])
+
+          item = {}
+          allowed_keys.each do |key|
+            item[key] = item_params[key] if item_params.key?(key)
+          end
+          # Skip rows where every permitted value is blank (empty template rows).
+          # Note: boolean "0" is not blank in Ruby, so unchecked checkboxes survive.
+          next if item.values.all?(&:blank?)
+
+          if target_model_def
+            # Wrap in JsonItemWrapper for type coercion and validation
+            wrapper = JsonItemWrapper.new(item, target_model_def)
+            wrapper.validate_with_model_rules!
+
+            if wrapper.errors.any?
+              wrapper.errors.each do |error|
+                record.errors.add(
+                  :base,
+                  "#{json_field_name} item #{idx + 1}: #{error.attribute} #{error.message}"
+                )
+              end
+            end
+
+            items << wrapper.to_hash
+          else
+            items << item
+          end
+        end
+
+        # Enforce min/max item limits
+        min = section["min"]&.to_i
+        if min && min > 0 && items.size < min
+          record.errors.add(:base, "#{json_field_name}: too few items (minimum is #{min})")
+        end
+
+        max = section["max"]&.to_i
+        if max && max > 0 && items.size > max
+          record.errors.add(:base, "#{json_field_name}: too many items (maximum is #{max})")
+          items = items.first(max)
+        end
+
+        record.send("#{json_field_name}=", items)
+      end
+    end
+
+    def sortable_position_field(section)
+      return unless section["sortable"]
+      section["sortable"].is_a?(String) ? section["sortable"] : "position"
+    end
+
+    def evaluate_service_conditions(record)
+      ctx = condition_context
+      results = {}
+      sections = current_presenter.form_config["sections"] || []
+      sections.each_with_index do |section, idx|
+        %w[visible_when disable_when].each do |cond_key|
+          cond = section[cond_key]
+          next unless cond.is_a?(Hash) && !ConditionEvaluator.client_evaluable?(cond)
+
+          result_key = "section_#{idx}_#{cond_key == 'visible_when' ? 'visible' : 'disable'}"
+          results[result_key] = ConditionEvaluator.evaluate_any(record, cond, context: ctx)
+        end
+
+        (section["fields"] || []).each do |field_config|
+          field_name = field_config["field"]
+          next unless field_name
+
+          %w[visible_when disable_when].each do |cond_key|
+            cond = field_config[cond_key]
+            next unless cond.is_a?(Hash) && !ConditionEvaluator.client_evaluable?(cond)
+
+            result_key = "#{field_name}_#{cond_key == 'visible_when' ? 'visible' : 'disable'}"
+            results[result_key] = ConditionEvaluator.evaluate_any(record, cond, context: ctx)
+          end
+        end
+      end
+      results
+    end
+
+    def resolve_loading_strategy(context)
+      sort_field = params[:sort] if context == :index
+      search_fields = current_presenter.search_config["searchable_fields"] if context == :index && params[:qs].present?
+      Presenter::IncludesResolver.resolve(
+        presenter_def: current_presenter,
+        model_def: current_model_definition,
+        context: context,
+        sort_field: sort_field,
+        search_fields: search_fields
+      )
+    rescue StandardError => e
+      LcpRuby.record_error(e, subsystem: "eager_loading", context: context)
+      Presenter::IncludesResolver::LoadingStrategy.new
+    end
+
+    def preload_associations(record, context)
+      strategy = resolve_loading_strategy(context)
+      return if strategy.empty?
+
+      assocs = strategy.includes + strategy.eager_load
+      ActiveRecord::Associations::Preloader.new(records: [ record ], associations: assocs).call if assocs.any?
+    rescue StandardError => e
+      LcpRuby.record_error(e, subsystem: "eager_loading", context: context)
+    end
+
+    # -- Inline create helpers --
+
+    def find_presenter_for_inline_create(model_name)
+      LcpRuby.loader.presenter_definitions.values.find do |p|
+        p.model == model_name && p.form_config["sections"]&.any?
+      end
+    end
+
+    def inline_create_params(model_def)
+      all_fields = model_def.fields.map { |f| f.name.to_sym }
+
+      # Filter through permission evaluator to respect field-level write restrictions
+      begin
+        perm_def = LcpRuby.loader.permission_definition(model_def.name)
+        evaluator = Authorization::PermissionEvaluator.new(perm_def, current_user, model_def.name)
+        writable = evaluator.writable_fields.map(&:to_sym)
+        allowed = all_fields & writable
+      rescue LcpRuby::MetadataError
+        # No permission definition found; allow all model fields
+        allowed = all_fields
+      end
+
+      params.require(:inline_record).permit(*allowed)
+    end
+
+    def resolve_inline_label_method(model_def, explicit_method)
+      return explicit_method.to_sym if explicit_method.present?
+      method = model_def.label_method
+      method && method != "to_s" ? method.to_sym : :to_label
+    end
+
+    def authorize_parent_field_writable!
+      authorize_field_writable!(current_model_definition.tree_parent_field, "tree parent")
+    end
+
+    def parse_parent_id_param
+      raw = params[:parent_id]
+      return nil if raw.blank? || raw == "null"
+      raw.to_i
+    end
+
+    def verify_tree_version!
+      return false unless params[:tree_version].present?
+
+      current_version = compute_tree_version
+      return false if current_version == params[:tree_version]
+
+      render json: { error: "tree_version_mismatch", tree_version: current_version },
+             status: :conflict
+      true
+    end
+
+    def authorize_position_field!
+      authorize_field_writable!(current_model_definition.positioning_field, "positioning")
+    end
+
+    def authorize_field_writable!(field, label = field)
+      unless current_evaluator.field_writable?(field)
+        raise Pundit::NotAuthorizedError,
+          "Not allowed to write #{label} field '#{field}'"
+      end
+    end
+
+    def verify_list_version!
+      return false unless params[:list_version].present?
+
+      current_version = compute_list_version(@record)
+      return false if current_version == params[:list_version]
+
+      render json: { error: "list_version_mismatch", list_version: current_version },
+             status: :conflict
+      true
+    end
+
+    def compute_list_version(record)
+      scope = @model_class.all
+      current_model_definition.positioning_scope.each do |col|
+        scope = scope.where(col => record.send(col))
+      end
+      pos_field = current_model_definition.positioning_field
+      ids_in_order = scope.order(pos_field => :asc).pluck(:id)
+      Digest::SHA256.hexdigest(ids_in_order.join(","))
+    end
+
+    VALID_POSITION_KEYS = %i[after before].freeze
+
+    def parse_position_param
+      raw = params[:position]
+      case raw
+      when ActionController::Parameters, Hash
+        # SECURITY: to_unsafe_h needed for position hash. Validated by VALID_POSITION_KEYS whitelist below.
+        h = raw.to_unsafe_h.transform_values { |v| v.to_i }.symbolize_keys
+        invalid = h.keys - VALID_POSITION_KEYS
+        if invalid.any?
+          raise ActionController::BadRequest, "Invalid position keys: #{invalid.join(', ')}. Expected: after, before"
+        end
+        h
+      when "first"
+        :first
+      when "last"
+        :last
+      else
+        raw.to_i
+      end
+    end
+
+    def inline_form_fields(layout_builder, model_def)
+      simple_types = %w[string text integer float decimal boolean date datetime enum email phone url color]
+      layout_builder.form_sections
+        .flat_map { |s| s["fields"] || [] }
+        .select do |f|
+          field_def = model_def.fields.find { |fd| fd.name == f["field"] }
+          next false unless field_def
+          # Only include simple field types (no associations, no nested)
+          simple_types.include?(field_def.type.to_s) || field_def.enum?
+        end
+        .map do |f|
+          field_def = model_def.fields.find { |fd| fd.name == f["field"] }
+          {
+            name: f["field"],
+            label: f["label"] || f["field"].humanize,
+            type: field_def.type.to_s,
+            required: field_def.validations&.any? { |v| v.type == "presence" },
+            enum_values: field_def.enum? ? field_def.enum_value_names : nil,
+            placeholder: f["placeholder"]
+          }
+        end
+    end
+  end
+end