lcp 0.1.0

data/lib/lcp_ruby/engine.rb

@@ -0,0 +1,680 @@
+require "pundit"
+require "ransack"
+require "kaminari"
+require "positioning"
+require "view_component"
+require "turbo-rails"
+require "stimulus-rails"
+require "devise"
+
+module LcpRuby
+  class Engine < ::Rails::Engine
+    isolate_namespace LcpRuby
+
+    config.autoload_paths << root.join("lib")
+
+    rake_tasks do
+      load LcpRuby::Engine.root.join("lib", "tasks", "lcp_ruby.rake")
+      load LcpRuby::Engine.root.join("lib", "tasks", "lcp_ruby_assets.rake")
+      load LcpRuby::Engine.root.join("lib", "tasks", "lcp_ruby_auth.rake")
+      load LcpRuby::Engine.root.join("lib", "tasks", "lcp_ruby_db.rake")
+      load LcpRuby::Engine.root.join("lib", "tasks", "lcp_ruby_doctor.rake")
+      load LcpRuby::Engine.root.join("lib", "tasks", "lcp_ruby_feature_catalog.rake")
+      load LcpRuby::Engine.root.join("lib", "tasks", "lcp_ruby_i18n_lint.rake")
+      load LcpRuby::Engine.root.join("lib", "tasks", "lcp_ruby_invariant_check.rake")
+    end
+
+    initializer "lcp_ruby.i18n" do
+      config.i18n.load_path += Dir[root.join("config", "locales", "**", "*.{rb,yml}")]
+    end
+
+    initializer "lcp_ruby.filter_parameters" do |app|
+      app.config.filter_parameters += [ :Authorization, "Authorization", :authorization, :plaintext_token, :token, :token_hash ]
+    end
+
+    initializer "lcp_ruby.configuration" do
+      LcpRuby.configuration.metadata_path ||= Rails.root.join("config", "lcp_ruby")
+    end
+
+    # Always set up Devise so that Warden middleware is properly configured.
+    # This is needed because Devise is always a dependency and Warden middleware
+    # is always in the stack. Only routes are conditional on :built_in mode.
+    initializer "lcp_ruby.authentication", before: :add_routing_paths do |_app|
+      LcpRuby::Authentication.setup_devise!
+    end
+
+    # Install Warden audit hooks after Devise middleware is loaded.
+    config.after_initialize do
+      LcpRuby::Authentication::AuditSubscriber.install!
+    end
+
+    initializer "lcp_ruby.ignore_renderers", before: :set_autoload_paths do |app|
+      renderers_path = Rails.root.join("app", "renderers")
+      if renderers_path.directory?
+        Rails.autoloaders.main.ignore(renderers_path)
+      end
+    end
+
+    initializer "lcp_ruby.load_metadata", after: :load_config_initializers do
+      ActiveSupport.on_load(:active_record) do
+        LcpRuby::Engine.load_metadata!
+      end
+    end
+
+    # Dev-mode metadata watcher: triggers Engine.reload! on YAML/DSL
+    # edits under `LcpRuby.configuration.metadata_path`, so changes to
+    # permission YAML, presenter DSL, etc. take effect on the next
+    # request without a manual server restart. Production never
+    # auto-reloads (deploy contract is rolling restart). Test disables
+    # `enable_reloading`, so the watcher is silent there too —
+    # IntegrationHelper#load_integration_metadata! controls reload
+    # explicitly.
+    #
+    # See docs/design/boot_reload_lifecycle.md for the full design;
+    # the glob-form FileUpdateChecker (second-arg hash) is load-bearing
+    # — a snapshot list (Dir[...]) misses files added after boot,
+    # which is the typical configurator workflow.
+    # Wires `Metadata::PathTemplate.run_deferred_checks!` into Rails'
+    # `to_prepare` callback. Templates collected during eager validation
+    # in `validate_menu_items` are drained here once the route table is
+    # fully drawn (engine + application). The to_prepare callback re-runs
+    # at boot AND on every `Rails.application.reload_routes!` (LCP's
+    # `SchemaManager` triggers reloads when YAML models change at runtime,
+    # which can introduce or remove route helpers — re-validation catches
+    # broken `{lcp_ruby.foo_path}` references).
+    initializer "lcp_ruby.path_template_deferred_check", after: "lcp_ruby.load_metadata" do |app|
+      app.config.to_prepare do
+        LcpRuby::Metadata::PathTemplate.run_deferred_checks!
+      end
+    end
+
+    initializer "lcp_ruby.dev_metadata_watch", after: "lcp_ruby.load_metadata" do |app|
+      next unless app.config.enable_reloading
+
+      metadata_path = LcpRuby.configuration.metadata_path
+      next unless metadata_path && File.directory?(metadata_path)
+
+      reloader = ActiveSupport::FileUpdateChecker.new(
+        [],
+        { metadata_path.to_s => [ :rb, :yml ] }
+      ) do
+        Rails.logger.info("[LcpRuby] Metadata file change detected; reloading...")
+        LcpRuby::Engine.reload!
+      end
+
+      app.reloaders << reloader
+      ActiveSupport::Reloader.to_prepare { reloader.execute_if_updated }
+    end
+
+    # OIDC strategy registration. Runs after host config initializers so
+    # LcpRuby.configuration.host_url and host hooks (role_resolver,
+    # user_provisioner) are visible to AuthValidator at boot.
+    # No-op when auth.yml is absent or only Devise providers are configured.
+    initializer "lcp_ruby.omniauth", after: :load_config_initializers do |app|
+      LcpRuby::Authentication::OmniAuthBuilder.install_middleware!(app)
+    end
+
+    # `LcpRuby.configuration.mount_path` is the single source of truth for
+    # both the OIDC redirect_uri (baked at OmniAuthBuilder.install_middleware!
+    # time) and OmniAuth.config.path_prefix. Hosts that mount the engine at
+    # a non-root path MUST set `config.mount_path` to match `routes.rb`;
+    # we don't try to autodetect from `Rails.application.routes` because in
+    # development those are drawn lazily and any post-boot check would race
+    # with the first request.
+
+    # API tokens — register pieces unconditionally. The model extension is
+    # applied during ModelFactory::Builder#build (via on_model_ready, which
+    # runs BEFORE validate_external_methods! — required because plaintext_token
+    # is declared `source: external` and needs its accessor before that check).
+    # When the host has not generated the api_token YAML, on_model_ready is a
+    # no-op (the block never fires) and the resolver/action keys are harmless.
+    initializer "lcp_ruby.api_tokens" do
+      # Action register fires once here and is also re-applied at the
+      # start of every `Engine.load_metadata!` (idempotent overwrite),
+      # because `LcpRuby.reset!` clears `Actions::ActionRegistry`.
+      Engine.register_engine_action_keys!
+
+      # `on_model_ready` registration only needs to fire once per process
+      # — `LcpRuby.reset!` deliberately preserves `@configuration` (and
+      # therefore `model_extensions`), so the callback survives every
+      # subsequent `Engine.reload!` without re-registration.
+      LcpRuby.configuration.on_model_ready("api_token") do |klass|
+        klass.include(LcpRuby::ApiTokens::ModelExtension)
+
+        LcpRuby::ApiTokens::ResolverRegistry.register(
+          :api_token,
+          priority: 100,
+          matcher:  ->(t) { LcpRuby::ApiTokens::TokenGenerator.valid_format?(t) },
+          resolver: ->(t) { LcpRuby::ApiTokens::Verifier.verify(t) }
+        )
+      end
+    end
+
+    # OIDC bearer — register the JWT resolver if at least one OIDC provider
+    # has a non-empty `audience`. The matcher only matches JWT-shape strings,
+    # so PATs and garbage never reach the verifier. See
+    # docs/design/oidc_auth.md "Phase 2 — Bearer Validation" for rationale.
+    initializer "lcp_ruby.oidc_bearer", after: "lcp_ruby.api_tokens" do
+      Engine.register_oidc_bearer_resolver_if_enabled!
+    end
+
+    # Re-applies engine-internal `Actions::ActionRegistry.register` calls.
+    # Called from the `lcp_ruby.api_tokens` initializer at boot AND from
+    # the start of every `Engine.load_metadata!` — `LcpRuby.reset!` clears
+    # `Actions::ActionRegistry`, so the bare initializer-once registration
+    # would lose these keys on `Engine.reload!`. `register` overwrites by
+    # name, so re-firing at every load is idempotent. Engine-internal
+    # `on_model_ready` registrations live in the initializer body directly
+    # — they survive reload via `@configuration` preservation in
+    # `LcpRuby.reset!` and would accumulate if re-fired here.
+    def self.register_engine_action_keys!
+      LcpRuby::Actions::ActionRegistry.register(
+        "api_token/revoke",
+        LcpRuby::Actions::ApiTokens::Revoke
+      )
+    end
+
+    # Drains the `on_load(:active_record)` queue at the caller's expense
+    # rather than during `load_metadata!`. The engine's
+    # `lcp_ruby.load_metadata` initializer registers a callback there;
+    # in non-eager-load contexts (rake, `bin/rails runner`) AR::Base is
+    # loaded lazily, so the callback fires synchronously the first time
+    # `build_model` references it — re-entering `load_metadata!`. Rake
+    # tasks that call `load_metadata!` directly should call this first
+    # to make the on_load fire deterministically. The `@metadata_loading`
+    # guard inside `load_metadata!` is the in-engine backstop.
+    def self.ensure_active_record_loaded!
+      ActiveRecord::Base
+    end
+
+    # Boot-time gate for the OIDC bearer resolver. Extracted as a class
+    # method so it can be unit-tested without booting Rails — see
+    # spec/lib/lcp_ruby/engine_oidc_bearer_spec.rb. Idempotent: re-registering
+    # by name overwrites in the registry.
+    def self.register_oidc_bearer_resolver_if_enabled!
+      return false unless LcpRuby::Authentication::ProviderRegistry.configured?
+      return false unless LcpRuby::Authentication::ProviderRegistry.oidc_enabled?
+      return false if LcpRuby::Authentication::ProviderRegistry.oidc_providers.none? { |p| p.audience.to_s.length.positive? }
+
+      LcpRuby::Authentication::OidcBearerResolver.register!
+      true
+    rescue LcpRuby::Authentication::ConfigurationError => e
+      # Symmetric to OmniAuthBuilder.install_middleware!: in production, fail
+      # loud; in dev/test, log + skip so `rake lcp_ruby:validate` can run
+      # and surface the problem.
+      raise if defined?(Rails) && Rails.respond_to?(:env) && Rails.env.production?
+
+      Rails.logger.warn(
+        "[lcp_ruby] OIDC bearer resolver NOT registered — auth.yml is invalid: #{e.message}"
+      ) if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+      false
+    end
+
+    initializer "lcp_ruby.assets" do |app|
+      if app.config.respond_to?(:assets)
+        app.config.assets.precompile += %w[
+          lcp_ruby/application.css
+          lcp_ruby/application.js
+          lcp_ruby/tom-select.complete.min.js
+          lcp_ruby/tom-select.css
+          lcp_ruby/activestorage.min.js
+          lcp_ruby/lucide.min.js
+          lcp_ruby/lucide_init.js
+          lcp_ruby/dev_toolbar.css
+          lcp_ruby/dev_toolbar.js
+          lcp_ruby/highlight.min.js
+          lcp_ruby/highlight-github.min.css
+        ]
+        app.config.assets.paths << root.join("app", "assets", "javascripts")
+        app.config.assets.paths << root.join("app", "assets", "stylesheets")
+        app.config.assets.paths << root.join("vendor", "assets", "javascripts")
+        app.config.assets.paths << root.join("vendor", "assets", "stylesheets")
+      end
+    end
+
+    BIND_TO_APPLICATOR_MAP = {
+      "ransack"          => ModelFactory::RansackApplicator,
+      "scopes"           => ModelFactory::ScopeApplicator,
+      "validations"      => ModelFactory::ValidationApplicator,
+      "virtual_columns"  => ModelFactory::AggregateApplicator,
+      "transforms"       => ModelFactory::TransformApplicator,
+      "computed_fields"  => ModelFactory::ComputedApplicator,
+      "custom_fields"    => CustomFields::Applicator,
+      "workflow"         => ModelFactory::WorkflowApplicator,
+      "userstamps"       => ModelFactory::UserstampsApplicator,
+      "soft_delete"      => ModelFactory::SoftDeleteApplicator,
+      "auditing"         => ModelFactory::AuditingApplicator,
+      "tree"             => ModelFactory::TreeApplicator,
+      "sequences"        => ModelFactory::SequenceApplicator,
+      "positioning"      => ModelFactory::PositioningApplicator,
+      "attachments"      => ModelFactory::AttachmentApplicator,
+      "enums"            => ModelFactory::EnumApplicator,
+      "service_accessors" => ModelFactory::ServiceAccessorApplicator,
+      "defaults"         => ModelFactory::DefaultApplicator,
+      "inherited_parent_validator" => ModelFactory::InheritedParentValidatorApplicator
+    }.freeze
+
+    # Serializes `reload!` against itself in dev/test so a YAML edit
+    # that triggers autoreload while another thread is mid-`reset!` does
+    # not crash the in-flight request with `RegistryError`. Production
+    # deploys are expected to drain traffic before reload (rolling
+    # restart, blue-green) and never hit this; the mutex is a no-op
+    # there but costs nothing on the read path which never enters
+    # `reload!`.
+    RELOAD_MUTEX = Mutex.new
+
+    class << self
+      def load_metadata!
+        return if @metadata_loaded
+        # Re-entrance guard: model building below references ActiveRecord::Base,
+        # which fires the `on_load(:active_record)` hook registered by the
+        # `lcp_ruby.load_metadata` initializer. In dev/test rake contexts the
+        # boot-time AR load is deferred, so that hook fires for the first time
+        # *during* this method — re-entering it. Without this flag the second
+        # entry would run `loader.load_all` on the already-populated, memoized
+        # Loader and raise "Duplicate presenter/model ...". @metadata_loaded
+        # is set true only at the end, so it cannot serve as the re-entry
+        # guard on its own.
+        return if @metadata_loading
+        @metadata_loading = true
+
+        # Re-register engine-internal action keys and (re-)evaluate the
+        # OIDC bearer gate on every load. Both registries are cleared by
+        # `LcpRuby.reset!` (called from `Engine.reload!`), so the bare
+        # initializer-once registrations are gone by the time we get here
+        # on a reload. Idempotent — safe at first boot too.
+        register_engine_action_keys!
+        register_oidc_bearer_resolver_if_enabled!
+
+        Types::BuiltInTypes.register_all!
+        Services::BuiltInTransforms.register_all!
+        Services::BuiltInDefaults.register_all!
+        Services::BuiltInAccessors.register_all!
+        Services::Registry.discover!(Rails.root.join("app").to_s)
+        Display::RendererRegistry.register_built_ins!
+        Display::RendererRegistry.discover!(Rails.root.join("app").to_s)
+        ViewSlots::Registry.register_built_ins!
+        ConditionServiceRegistry.register_built_ins!
+
+        loader = LcpRuby.loader
+        loader.load_all
+
+        # Build models in topological order (parents before children) for STI
+        sorted_model_defs = Metadata::ModelInheritanceResolver.sort_definitions(loader.model_definitions)
+        sorted_model_defs.each do |model_def|
+          build_model(model_def, loader)
+        end
+
+        CustomFields::Setup.apply!(loader)
+        RecordAliases::Setup.apply!(loader)
+        Roles::Setup.apply!(loader)
+        Permissions::Setup.apply!(loader)
+        Groups::Setup.apply!(loader)
+        Auditing::Setup.apply!(loader)
+        Workflow::Setup.apply!(loader)
+        BackgroundJobs::Setup.apply!(loader)
+        SavedFilters::Setup.apply!(loader)
+        Export::Setup.apply!(loader)
+        Import::Setup.apply!(loader)
+        Pages::Setup.apply!(loader)
+        loader.merge_db_pages!
+        DataSource::Setup.apply!(loader)
+
+        # Late-bound host extensions (e.g. `LcpRuby.on_models_loaded { ... }`
+        # registering custom AR scopes referenced by permission YAML) fire
+        # *before* the runtime invariant validator, so AUTH-001's
+        # `klass.respond_to?(method)` check sees them.
+        LcpRuby._drain_models_loaded_callbacks!(loader)
+        Authorization::RuntimeInvariantValidator.new(loader).run!
+
+        Metrics::Setup.apply!(loader)
+
+        LcpRuby.check_services!
+        LcpRuby.check_action_text_compat!
+
+        @metadata_loaded = true
+        LcpRuby.instance_variable_set(:@booted, true)
+
+        ActiveSupport::Notifications.instrument("boot.lcp_ruby", instrumentation_payload(loader))
+      ensure
+        @metadata_loading = false
+      end
+
+      def reload!
+        RELOAD_MUTEX.synchronize do
+          @metadata_loaded = false
+          # `reset_for_reload!` (NOT `reset!`) — preserves
+          # `@configuration` and `@models_loaded_callbacks` so host
+          # settings and host-registered callbacks from
+          # `config/initializers/lcp_ruby.rb` survive the reload.
+          # See docs/design/boot_reload_lifecycle.md § Q7.
+          LcpRuby.reset_for_reload!
+          begin
+            load_metadata!
+          rescue Authorization::InvariantError, MetadataError
+            # Rollback half-loaded state so the next request re-boots
+            # cleanly rather than serving from a partially-populated
+            # registry. Rescue scope is intentionally narrow — host-side
+            # StandardError from a custom `on_models_loaded` callback or
+            # unexpected platform bugs propagate without rollback so the
+            # host's restart path handles them. See
+            # docs/design/authorization_hardening.md § "Reload-failure
+            # rollback".
+            @metadata_loaded = false
+            LcpRuby.reset_for_reload!
+            raise
+          end
+
+          # Reload-only signal so host apps can subscribe to "metadata
+          # was reloaded" without also being notified on initial boot.
+          # `boot.lcp_ruby` fires from inside `load_metadata!` and so
+          # also fires here — that is the general "metadata is now
+          # loaded" signal. `reload.lcp_ruby` is the more specific "and
+          # it was a reload, not an initial boot" signal.
+          ActiveSupport::Notifications.instrument("reload.lcp_ruby", instrumentation_payload(LcpRuby.loader))
+        end
+      end
+
+      # Re-apply `lcp_managed:` schema (additive columns) and AR macros
+      # for a bind_to: host class. Idempotent. Used by
+      # `lcp_ruby:ensure_tables` to recover after `db:schema:load` has
+      # recreated the host table without the managed columns (those
+      # columns are LCP-runtime-added and never present in `schema.rb`).
+      #
+      # Safe to call repeatedly: `SchemaManager.apply_managed!` skips
+      # existing columns; `AssociationApplicator` short-circuits on
+      # `already_managed?` for previously-installed macros.
+      def apply_bind_to_managed!(model_def)
+        return unless model_def.bind_to?
+
+        host_class = LcpRuby.registry.model_for(model_def.name)
+        return unless host_class
+
+        apply_bind_to_managed_schema(host_class, model_def)
+        apply_bind_to_managed_associations(host_class, model_def)
+      end
+
+      private
+
+      # Shared payload shape for `boot.lcp_ruby` and `reload.lcp_ruby`
+      # AS::Notifications events.
+      def instrumentation_payload(loader)
+        {
+          models_count: loader.model_definitions.size,
+          presenters_count: loader.presenter_definitions.size,
+          pages_count: loader.page_definitions.size
+        }
+      end
+
+      def build_model(model_def, loader)
+        # Virtual models exist only as metadata (no table, no AR class)
+        return if model_def.virtual?
+
+        if model_def.bind_to?
+          model_class = build_bind_to_model(model_def, loader)
+        elsif model_def.api_model?
+          builder = ModelFactory::ApiBuilder.new(model_def)
+          model_class = builder.build
+        else
+          # For STI children, use the full definition for schema (to add child columns
+          # to parent table) but use the child-only definition for Builder (to avoid
+          # double-applying parent's validations/callbacks/enums inherited via AR).
+          schema_manager = ModelFactory::SchemaManager.new(model_def)
+          schema_manager.ensure_table! if LcpRuby.configuration.auto_migrate
+
+          builder_def = if model_def.sti_child?
+            loader.sti_builder_definition(model_def.name) || model_def
+          else
+            model_def
+          end
+
+          builder = ModelFactory::Builder.new(builder_def)
+          model_class = builder.build
+        end
+
+        LcpRuby.registry.register(model_def.name, model_class)
+      end
+
+      def build_bind_to_model(model_def, loader)
+        # Step 1: Resolve class
+        resolved_class = begin
+          model_def.bind_to.constantize
+        rescue NameError => e
+          raise LcpRuby::MetadataError,
+            "Model '#{model_def.name}': bind_to class '#{model_def.bind_to}' not found. " \
+            "Ensure the class exists and follows Zeitwerk naming conventions. " \
+            "Original error: #{e.message}"
+        end
+
+        unless resolved_class < ActiveRecord::Base
+          raise LcpRuby::MetadataError,
+            "Model '#{model_def.name}': bind_to class '#{model_def.bind_to}' " \
+            "is not an ActiveRecord model (does not inherit from ActiveRecord::Base)."
+        end
+
+        # Step 2: Sync table_name from the resolved class
+        model_def.table_name = resolved_class.table_name
+
+        # Step 3: Builder skipped — host class is used as-is.
+
+        # Step 4a: Additive schema for fields and belongs_to FK columns marked
+        # `lcp_managed: true`. Runs BEFORE apply_bind_to_features so subsequent
+        # applicators that read columns ([validations], [ransack], [transforms],
+        # [computed_fields], [sequences], [positioning], [userstamps], [auditing], …)
+        # see the new columns.
+        apply_bind_to_managed_schema(resolved_class, model_def)
+
+        # Step 4b: Declare AR macros for associations marked `lcp_managed: true`
+        # on the host class. Symmetric gate with Step 4a — without the FK
+        # columns in place, declaring belongs_to would crash on first query.
+        apply_bind_to_managed_associations(resolved_class, model_def)
+
+        # Step 5: Apply opt-in + auto-included applicators (with idempotence guard).
+        apply_bind_to_features(resolved_class, model_def, auto_features: model_def.bind_to_auto_features)
+
+        # Step 5a: Apply label_method (always, not opt-in)
+        apply_bind_to_label_method(resolved_class, model_def)
+
+        # Step 5b: Apply host-registered model extensions
+        apply_bind_to_model_extensions(resolved_class, model_def)
+
+        # Step 6: Validate Ransack availability for presenters that need it
+        validate_ransack_for_bind_to(resolved_class, model_def, loader)
+
+        # Step 7: Validate fields against bound class columns/methods
+        validate_bind_to_fields(resolved_class, model_def)
+
+        resolved_class
+      end
+
+      # Step 4a — additive schema for `lcp_managed: true` fields and FKs.
+      # Gated on auto_migrate: when disabled, warn and skip — production hosts
+      # that pre-migrate the columns are then handled by Step 4b's column
+      # presence check (see `apply_bind_to_managed_associations`).
+      def apply_bind_to_managed_schema(host_class, model_def)
+        return unless any_managed_schema?(model_def)
+
+        unless LcpRuby.configuration.auto_migrate
+          Rails.logger.warn(
+            "[LcpRuby] bind_to #{model_def.name} (#{model_def.display_bind_to}): " \
+            "lcp_managed columns declared but auto_migrate is false. Columns NOT added; " \
+            "either pre-migrate them via your own Rails migration or temporarily enable " \
+            "auto_migrate to bootstrap. Managed associations will be skipped too unless " \
+            "all FK columns are already present on the host class."
+          )
+          return
+        end
+
+        ModelFactory::SchemaManager.new(model_def, host_class: host_class, mode: :managed_only)
+                                   .ensure_table!
+      end
+
+      # Step 4b — apply AR macros for `lcp_managed: true` associations.
+      # Symmetric gate with apply_bind_to_managed_schema: only runs when
+      # auto_migrate is on (columns just added) OR when the host has
+      # pre-migrated all required FK columns by hand. Otherwise skip — better
+      # to log and skip than to declare a belongs_to over a missing column.
+      def apply_bind_to_managed_associations(host_class, model_def)
+        return unless model_def.associations.any?(&:lcp_managed?)
+
+        # Bootstrap guard, symmetric with apply_bind_to_managed_schema:
+        # `host_class.columns` raises `ActiveRecord::StatementInvalid`
+        # when the table doesn't exist yet (e.g. fresh checkout before
+        # `db:prepare`). Skip with a warn — the next boot after
+        # migrations will declare the macros.
+        unless host_class.table_exists?
+          Rails.logger.warn(
+            "[LcpRuby] bind_to #{model_def.name} (#{model_def.display_bind_to}): " \
+            "managed associations skipped — host table '#{host_class.table_name}' " \
+            "does not exist yet. Run `rails db:prepare`, then restart."
+          )
+          return
+        end
+
+        unless LcpRuby.configuration.auto_migrate
+          missing = model_def.managed_fk_columns - host_class.columns.map(&:name)
+          unless missing.empty?
+            Rails.logger.warn(
+              "[LcpRuby] bind_to #{model_def.name} (#{model_def.display_bind_to}): " \
+              "managed associations skipped because FK columns are missing on the " \
+              "host table: #{missing.join(', ')}. AR macros NOT declared. Either " \
+              "enable auto_migrate or pre-migrate the missing columns."
+            )
+            return
+          end
+        end
+
+        ModelFactory::AssociationApplicator.new(host_class, model_def, filter: :managed).apply!
+      end
+
+      def any_managed_schema?(model_def)
+        model_def.fields.any?(&:lcp_managed?) ||
+          model_def.associations.any? { |a| a.belongs_to? && a.lcp_managed? }
+      end
+
+      def apply_bind_to_features(model_class, model_def, auto_features: [])
+        features = (model_def.bind_to_apply + auto_features).uniq
+
+        # Smart-auto: include `inherited_parent_validator` when the YAML
+        # permission declares `inherits_from`. Mirrors the always-wire
+        # contract that dynamic ModelFactory::Builder provides for
+        # platform-managed models. DB-backed permissions aren't visible
+        # at boot — power users with those declare
+        # `bind_to_apply: [inherited_parent_validator]` explicitly to
+        # force the wiring.
+        perm = LcpRuby.loader.yaml_permission_definition(model_def.name)
+        if perm&.inherits_from && !features.include?("inherited_parent_validator")
+          features << "inherited_parent_validator"
+        end
+
+        return if features.empty?
+
+        # Idempotence guard: track which features have been applied
+        unless model_class.instance_variable_defined?(:@lcp_applied_features)
+          model_class.instance_variable_set(:@lcp_applied_features, Set.new)
+        end
+        applied = model_class.instance_variable_get(:@lcp_applied_features)
+
+        features.each do |feature|
+          next if applied.include?(feature)
+
+          applicator_class = BIND_TO_APPLICATOR_MAP[feature]
+          raise LcpRuby::MetadataError,
+            "Model '#{model_def.name}': unknown bind_to_apply feature '#{feature}'" unless applicator_class
+
+          applicator_class.new(model_class, model_def).apply!
+          applied << feature
+        end
+      end
+
+      def apply_bind_to_label_method(model_class, model_def)
+        LcpRuby::ModelFactory::LabelMethodBuilder.define(
+          model_class, model_def.label_method, model_def: model_def
+        )
+      end
+
+      def apply_bind_to_model_extensions(model_class, model_def)
+        extensions = LcpRuby.configuration.model_extensions[model_def.name] || []
+        extensions.each { |block| block.call(model_class) }
+      end
+
+      def validate_ransack_for_bind_to(resolved_class, model_def, loader)
+        loader.presenter_definitions.each_value do |presenter|
+          next unless presenter.model == model_def.name
+          next unless presenter.has_search_parameters? || presenter.advanced_filter_enabled?
+
+          # Check if ransackable_attributes is explicitly defined on the class itself
+          # (not inherited from Ransack's default Ransack::Adapters::ActiveRecord::Base module).
+          has_ransack = if resolved_class.singleton_class.method_defined?(:ransackable_attributes)
+            owner = resolved_class.method(:ransackable_attributes).owner
+            owner != Ransack::Adapters::ActiveRecord::Base
+          else
+            false
+          end
+
+          unless has_ransack
+            raise LcpRuby::MetadataError,
+              "Model '#{model_def.name}': presenter '#{presenter.name}' declares search_parameters " \
+              "or advanced_filter, but the bound class '#{model_def.bind_to}' does not define " \
+              "ransackable_attributes. Add 'ransack' to bind_to_apply or define " \
+              "self.ransackable_attributes on the class."
+          end
+        end
+      end
+
+      def validate_bind_to_fields(resolved_class, model_def)
+        # Skip validation if the table doesn't exist yet (e.g., before migrations).
+        # Log a warning so the developer notices instead of getting silent skips.
+        unless resolved_class.connection.table_exists?(resolved_class.table_name)
+          Rails.logger.warn(
+            "[LcpRuby] Model '#{model_def.name}': bound class '#{model_def.bind_to}' " \
+            "table '#{resolved_class.table_name}' does not exist — skipping field validation. " \
+            "Run migrations to enable boot-time field checks."
+          )
+          return
+        end
+
+        column_names = resolved_class.column_names.to_set
+        method_names = resolved_class.instance_methods.to_set { |m| m.to_s }
+        defined_enums = resolved_class.defined_enums
+
+        model_def.fields.each do |field|
+          next if field.virtual?  # Virtual fields (computed, external) don't need DB columns
+          next if field.lcp_managed?  # Managed columns are LCP's responsibility (Step 4a)
+          next if column_names.include?(field.name)
+          next if method_names.include?(field.name)
+
+          Rails.logger.warn(
+            "[LcpRuby] Model '#{model_def.name}': field '#{field.name}' declared in YAML " \
+            "but not found as column or method on #{model_def.bind_to}. " \
+            "Available columns: #{column_names.to_a.join(', ')}"
+          )
+        end
+
+        # Enum cross-check: verify YAML enum fields match the host class's defined_enums
+        model_def.fields.each do |field|
+          next unless field.type.to_s == "enum"
+
+          host_enum = defined_enums[field.name]
+          if host_enum.nil?
+            Rails.logger.warn(
+              "[LcpRuby] Model '#{model_def.name}': field '#{field.name}' is type: enum in YAML " \
+              "but #{model_def.bind_to} does not define it as an enum (defined_enums). " \
+              "The presenter may render incorrect select options."
+            )
+          elsif field.respond_to?(:enum_values) && field.enum_values.present?
+            yaml_values = field.enum_values.map(&:to_s).sort
+            host_values = host_enum.keys.map(&:to_s).sort
+            if yaml_values != host_values
+              Rails.logger.warn(
+                "[LcpRuby] Model '#{model_def.name}': field '#{field.name}' enum_values in YAML " \
+                "#{yaml_values} do not match #{model_def.bind_to}.defined_enums " \
+                "#{host_values}. The presenter may render incorrect select options."
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end