lcp 0.1.0

data/docs/guides/extensibility.md

@@ -0,0 +1,761 @@
+# Extensibility Guide
+
+LCP Ruby generates full CRUD applications from YAML metadata, but real-world systems need custom business logic. This guide covers all extensibility mechanisms.
+
+## Overview
+
+LCP Ruby provides extensibility through two systems:
+
+1. **Services::Registry** — unified auto-discover registry for transforms, validators, defaults, computed fields, conditions, and data providers. Services live in `app/lcp_services/{category}/` and are discovered automatically.
+2. **Dedicated registries** — custom actions (`app/actions/`), event handlers (`app/event_handlers/`), condition services (`app/condition_services/`), and custom renderers (`app/renderers/`) use their own registries with auto-discovery.
+
+### Service Categories
+
+| Category | Contract | Side Effects? | Directory | Used In |
+|----------|----------|---------------|-----------|---------|
+| `transforms` | `def call(value) -> value` | No | `app/lcp_services/transforms/` | Field `transforms:`, type `transforms:` |
+| `validators` | `def self.call(record, **opts) -> void` | No | `app/lcp_services/validators/` | Validation `type: service` |
+| `defaults` | `def self.call(record, field_name) -> value` | No | `app/lcp_services/defaults/` | Field `default: { service: }` |
+| `computed` | `def self.call(record) -> value` | No | `app/lcp_services/computed/` | Field `computed: { service: }` |
+| `conditions` | `def self.call(record) -> boolean` | No | `app/lcp_services/conditions/` | `visible_when: { service: }`, `when: { service: }` |
+| `data_providers` | `def self.call(user:) -> data or nil` | No | `app/lcp_services/data_providers/` | Menu badge `provider:` |
+
+### Other Extension Points
+
+| Mechanism | Contract | Side Effects? | Base Class | Docs |
+|-----------|----------|---------------|------------|------|
+| Custom Actions | `(record, user, params) -> Result` | Yes | `Actions::BaseAction` | [Guide](custom-actions.md) |
+| Event Handlers | `(record, changes) -> void` | Yes | `Events::HandlerBase` | [Guide](event-handlers.md) |
+| Custom Renderers | `(value, options) -> HTML` | No | `Display::BaseRenderer` | [Guide](custom-renderers.md) |
+| Custom Render Blocks | Host-app partials for sections, zones, pages | No | YAML/DSL config | [Guide](rendering-extension-points.md) |
+| View Slots | Inject content into named positions | No | `ViewSlots::Registry` | [Guide](view-slots.md) |
+| Custom Validations | `(record, field) -> errors` | No | `ActiveModel::Validator` | [Reference](../reference/models.md#validations) |
+| Custom Fields | Runtime field definitions | No | `custom_fields: true` option | [Guide](custom-fields.md) |
+| Scopes | `(relation) -> relation` | No | YAML/DSL config | [Reference](../reference/models.md#scopes) |
+
+## Choosing the Right Mechanism
+
+Use this decision tree to pick the right extensibility point:
+
+- **User clicks a button** (explicit action) -> [Custom Action](#custom-actions)
+- **React to data changes** (implicit side effect) -> [Event Handler](#event-handlers)
+- **Normalize field values on write** (transform input) -> [Custom Transform](#custom-transforms)
+- **Enforce data constraints on a single field** (reject invalid data) -> [Custom Validation](#custom-validations) or declarative [comparison](../reference/models.md#comparison)
+- **Enforce cross-record business rules** (e.g., aggregate limits) -> [Service Validator](#service-validators)
+- **Calculate a field from other fields** -> [Computed Field](#computed-fields)
+- **Set field default at record creation** -> [Dynamic Default](#dynamic-defaults)
+- **Compute field/section visibility dynamically** (server-side condition) -> [Condition Service](#condition-services)
+- **Replace a section/zone/page with a custom partial** -> [Custom Render Blocks](rendering-extension-points.md)
+- **Inject content alongside LCP content** (toolbar buttons, banners) -> [View Slots](view-slots.md)
+- **Run validation only in certain states** -> [Conditional Validation](../reference/models.md#conditional-validations-when) (declarative `when:`)
+- **Reusable query filters** (named queries) -> [Scope](#scopes)
+- **End-users need to add fields at runtime** (no code/migration) -> [Custom Fields](custom-fields.md)
+
+## Quick Examples
+
+### Custom Actions
+
+Actions execute business logic when a user clicks a button in the UI. They receive a record, user, and params, and return a success/failure result.
+
+```ruby
+# app/actions/invoice/send_email.rb
+module LcpRuby
+  module HostActions
+    module Invoice
+      class SendEmail < LcpRuby::Actions::BaseAction
+        def call
+          return failure(message: "No invoice specified") unless record
+
+          InvoiceMailer.send_invoice(record, current_user).deliver_later
+          success(message: "Invoice ##{record.number} sent!")
+        end
+      end
+    end
+  end
+end
+```
+
+Register in presenter YAML:
+
+```yaml
+actions:
+  single:
+    - name: send_email
+      type: custom
+      label: "Send Invoice"
+      icon: mail
+      confirm: true
+```
+
+See the [Custom Actions guide](custom-actions.md) for the full API including `visible?`, `authorized?`, and `param_schema`.
+
+### Event Handlers
+
+Handlers respond to lifecycle events and field changes. They run automatically when data changes — no user interaction required.
+
+```ruby
+# app/event_handlers/deal/on_stage_change.rb
+module LcpRuby
+  module HostEventHandlers
+    module Deal
+      class OnStageChange < LcpRuby::Events::HandlerBase
+        def self.handles_event
+          "on_stage_change"
+        end
+
+        def call
+          if new_value("stage") == "closed_won"
+            Rails.logger.info("[CRM] Deal '#{record.title}' won!")
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+Declare the event in model YAML:
+
+```yaml
+events:
+  - name: on_stage_change
+    type: field_change
+    field: stage
+    condition:
+      field: stage
+      operator: not_in
+      value: [lead]
+```
+
+See the [Event Handlers guide](event-handlers.md) for async handlers, lifecycle events, and the full `HandlerBase` API.
+
+### Custom Transforms
+
+Transforms normalize field values on assignment. They are pure functions: `value in -> value out`.
+
+Transforms can be used at the **field level** (directly on a field) or at the **type level** (bundled with a custom type). For simple cases, field-level transforms avoid the need for a custom type entirely.
+
+**Field-level transform** (no custom type needed):
+
+```yaml
+# YAML
+- name: title
+  type: string
+  transforms: [strip]
+```
+
+```ruby
+# DSL
+field :first_name, :string, transforms: [:strip, :titlecase]
+```
+
+**Custom transform service** — register in `app/lcp_services/transforms/`:
+
+```ruby
+# app/lcp_services/transforms/titlecase.rb
+module LcpRuby
+  module HostServices
+    module Transforms
+      class Titlecase
+        def call(value)
+          value.respond_to?(:titlecase) ? value.titlecase : value
+        end
+      end
+    end
+  end
+end
+```
+
+The service is auto-discovered and can be referenced by key (`titlecase`) in both field-level `transforms:` and type-level `transforms:`.
+
+Transforms chain in order via `ActiveRecord.normalizes` — each transform's output feeds the next. Field-level transforms extend type-level transforms (deduplicated). See the [Types Reference](../reference/types.md#custom-transforms) for details.
+
+### Custom Validations
+
+Custom validators enforce business rules that go beyond the built-in validation types. They follow the standard ActiveModel validator pattern.
+
+```ruby
+# app/validators/business_rule_validator.rb
+class BusinessRuleValidator < ActiveModel::Validator
+  def validate(record)
+    if record.respond_to?(:start_date) && record.respond_to?(:end_date)
+      if record.start_date.present? && record.end_date.present? && record.end_date < record.start_date
+        record.errors.add(:end_date, "must be after start date")
+      end
+    end
+  end
+end
+```
+
+Reference in model YAML:
+
+```yaml
+# Field-level
+fields:
+  - name: email
+    type: string
+    validations:
+      - type: custom
+        validator_class: "EmailFormatValidator"
+
+# Model-level (cross-field validation)
+validations:
+  - type: custom
+    validator_class: "BusinessRuleValidator"
+```
+
+The engine calls `validator_class.constantize` at build time, so the class must be loaded before models are built.
+
+> **Tip:** For cross-field date/number comparisons, consider using the declarative [`comparison`](../reference/models.md#comparison) validation type instead of writing a custom validator class. For cross-record business rules, use a [service validator](#service-validators).
+
+### Service Validators
+
+Service validators enforce business rules that span multiple records or require database queries. They are auto-discovered from `app/lcp_services/validators/`.
+
+```ruby
+# app/lcp_services/validators/deal_credit_limit.rb
+module LcpRuby
+  module HostServices
+    module Validators
+      class DealCreditLimit
+        def self.call(record, **opts)
+          return unless record.respond_to?(:company_id) && record.company_id
+
+          company_deals = record.class.where(company_id: record.company_id)
+          company_deals = company_deals.where.not(id: record.id) if record.persisted?
+          total = company_deals.sum(:value).to_f + record.value.to_f
+
+          if total > 1_000_000
+            record.errors.add(:value, "total company deals exceed credit limit (1M)")
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+Reference in model YAML/DSL:
+
+```yaml
+# Model-level service validation
+validations:
+  - type: service
+    service: deal_credit_limit
+```
+
+```ruby
+# DSL
+validates_model :service, service: "deal_credit_limit"
+```
+
+### Computed Fields
+
+Computed fields derive their values from other fields and are automatically calculated before save. They are rendered as readonly in forms.
+
+**Template computed field** — string interpolation using `{field_name}` syntax:
+
+```ruby
+# DSL
+field :full_name, :string, computed: "{first_name} {last_name}"
+```
+
+```yaml
+# YAML
+- name: full_name
+  type: string
+  computed: "{first_name} {last_name}"
+```
+
+**Service computed field** — delegates to a registered service in `app/lcp_services/computed/`:
+
+```ruby
+# app/lcp_services/computed/weighted_deal_value.rb
+module LcpRuby
+  module HostServices
+    module Computed
+      class WeightedDealValue
+        def self.call(record)
+          value = record.value.to_f
+          progress = record.progress.to_f
+          (value * progress / 100.0).round(2)
+        end
+      end
+    end
+  end
+end
+```
+
+```ruby
+# DSL
+field :weighted_value, :decimal, computed: { service: "weighted_deal_value" }
+```
+
+See [Computed Fields](../reference/models.md#computed) in the Models Reference.
+
+### Dynamic Defaults
+
+Dynamic defaults set field values at record creation time using runtime logic. They run via `after_initialize` on new records only.
+
+**Built-in defaults:**
+
+```yaml
+- name: start_date
+  type: date
+  default: current_date
+```
+
+Built-in keys: `current_date`, `current_datetime`, `current_user.id`.
+
+**Service defaults** — custom logic in `app/lcp_services/defaults/`:
+
+```ruby
+# app/lcp_services/defaults/thirty_days_out.rb
+module LcpRuby
+  module HostServices
+    module Defaults
+      class ThirtyDaysOut
+        def self.call(record, field_name)
+          Date.current + 30
+        end
+      end
+    end
+  end
+end
+```
+
+```yaml
+- name: expected_close_date
+  type: date
+  default:
+    service: thirty_days_out
+```
+
+See [Dynamic Defaults](../reference/models.md#default) in the Models Reference.
+
+### Condition Services
+
+Condition services compute dynamic visibility for fields or sections. They are pure functions: `record in -> boolean out`. Use them when declarative `visible_when` operators are not expressive enough.
+
+```ruby
+# app/condition_services/credit_check.rb
+module LcpRuby
+  module HostConditionServices
+    class CreditCheck
+      def self.call(record)
+        record.credit_score.present? && record.credit_score > 500
+      end
+    end
+  end
+end
+```
+
+Used in presenter YAML:
+
+```yaml
+fields:
+  - field: premium_options
+    visible_when: { service: credit_check }
+```
+
+When the presenter evaluates `visible_when` and encounters a `service` key, it looks up the named condition service in the `ConditionServiceRegistry` and calls it with the current record. The field is visible only if the service returns `true`.
+
+Condition services can also be used in validation `when:` conditions:
+
+```yaml
+validations:
+  - type: presence
+    when:
+      service: requires_approval
+```
+
+### Custom Filter Methods
+
+Custom filter methods let host apps define complex filtering logic that cannot be expressed as Ransack predicates — multi-table JOINs, subqueries, external service lookups, or authorization-aware filters. They follow a naming convention: `self.filter_{name}(scope, value, evaluator)`.
+
+**Where to define them:** In model extensions (see [Model Extensions](#model-extensions) below), as class methods on the dynamic model.
+
+```ruby
+# config/initializers/lcp_ruby_extensions.rb
+LcpRuby.on_models_loaded do
+  LcpRuby::Dynamic::Deal.class_eval do
+    class << self
+      # Simple boolean filter
+      def filter_active(scope, value, evaluator)
+        return scope unless ActiveModel::Type::Boolean.new.cast(value)
+        scope.where(stage: %w[lead qualified proposal])
+      end
+
+      # Complex JOIN-based filter
+      def filter_region(scope, value, evaluator)
+        scope.joins(company: :country)
+             .where(countries: { region: value })
+      end
+
+      # Authorization-aware filter
+      def filter_my_records(scope, value, evaluator)
+        return scope unless ActiveModel::Type::Boolean.new.cast(value)
+        scope.where(owner_id: evaluator.user.id)
+      end
+    end
+  end
+end
+```
+
+> See [Hook timing](#hook-timing) for why `LcpRuby.on_models_loaded` is the right hook here (rather than `Rails.application.config.after_initialize`).
+
+**How it works:** Before passing filter params to Ransack, the controller checks each parameter key. If the model has a matching `filter_*` class method, it calls that method and removes the key from Ransack's params. The method must return an `ActiveRecord::Relation` — if it returns anything else, the filter is ignored and a warning is logged.
+
+**Exposing in the UI:** To make custom filters appear in the filter dropdown, declare them in the presenter YAML under `advanced_filter.custom_filters`:
+
+```yaml
+search:
+  advanced_filter:
+    custom_filters:
+      - name: region
+        label: "Region"
+        type: string           # Value input type in the UI
+      - name: my_records
+        label: "My Records"
+        type: boolean
+      - name: active
+        label: "Active Only"
+        type: boolean
+```
+
+When `custom_filters` is declared, these appear as selectable fields in the filter dropdown under a "Custom" group. Without the declaration, `filter_*` methods still work when parameters arrive (e.g., via URL), but they don't appear in the UI.
+
+**Security:** Only methods matching the `filter_` prefix convention are callable. The method must be defined directly on the model class (not inherited from `ActiveRecord::Base`). The return value is validated to be an `ActiveRecord::Relation`.
+
+### Scopes
+
+Declarative scopes are defined in YAML using `where`, `where_not`, `order`, and `limit`:
+
+```yaml
+scopes:
+  - name: active
+    where: { status: active }
+  - name: recent
+    order: { created_at: desc }
+    limit: 10
+```
+
+For complex queries, mark the scope as `type: custom` and define it in Ruby via a model extension (see [Model Extensions](#model-extensions) below):
+
+```yaml
+scopes:
+  - name: overdue
+    type: custom
+```
+
+## Model Extensions
+
+Dynamic models live under `LcpRuby::Dynamic::<ModelName>`. You can extend them with custom methods after the engine builds them. This is necessary for:
+
+- Custom scopes (`type: "custom"` in YAML)
+- Conditional validation methods (`if: "active?"`, `unless: "draft?"`)
+- Custom instance methods referenced elsewhere
+
+### Defining Extensions
+
+Add methods to the dynamic model class in an initializer, after LCP Ruby has built the models. Use `LcpRuby.on_models_loaded` — it fires inside `Engine.load_metadata!` once every dynamic class is built, *before* the boot-time invariant validator runs (so a `type: custom` scope that references a method defined here passes [AUTH-001](../reference/invariant_check.md#codes)).
+
+```ruby
+# config/initializers/lcp_ruby_extensions.rb
+LcpRuby.on_models_loaded do
+  # Custom scope — must match a scope with type: "custom" in model YAML.
+  # Registered before AUTH-001 evaluates `klass.respond_to?(method)`.
+  LcpRuby::Dynamic::Task.scope :overdue, -> {
+    where("due_date < ?", Date.current).where(completed: false)
+  }
+
+  # Predicate methods for conditional validations
+  LcpRuby::Dynamic::Task.class_eval do
+    def active?
+      status == "active"
+    end
+
+    def draft?
+      status == "draft"
+    end
+  end
+end
+```
+
+> See [Hook timing](#hook-timing) for the order between `on_model_ready`, `on_models_loaded`, and `Rails.application.config.after_initialize`.
+
+### How It Connects
+
+The `ScopeApplicator` skips code generation for scopes marked `type: "custom"`:
+
+```ruby
+# lib/lcp_ruby/model_factory/scope_applicator.rb
+if scope_config["type"] == "custom"
+  # Custom scopes are defined by Ruby code in model extensions
+  return
+end
+```
+
+The scope entry in YAML serves as documentation and allows it to be referenced from predefined filters in presenters. The actual query logic comes from the Ruby extension.
+
+Conditional validation options (`if`, `unless`) reference method names on the model instance:
+
+```yaml
+validations:
+  - type: presence
+    options: { if: "active?" }
+```
+
+The `active?` method must exist on the model — either from a model extension or a custom validator.
+
+## JavaScript i18n Bridge
+
+Host-app Stimulus controllers that render user-visible text must resolve strings through the engine's JavaScript i18n bridge so runtime locale switching works. The bridge is populated in every request under the current `I18n.locale` by `LcpRuby::I18nPayloadHelper` (rendered as an inline `<script>` in the layout `<head>`), so controllers see localized values immediately — no asset recompilation or extra fetch.
+
+### Global API
+
+Two helpers live on `window.LcpI18n`:
+
+```js
+// Dotted-path lookup with per-segment guard
+window.LcpI18n.t("advanced_filter.toggle", "Filters");
+// -> "Filters" (or the translated value under the current locale)
+
+// %{name} interpolation
+window.LcpI18n.format("Deleted %{count} records.", { count: 7 });
+// -> "Deleted 7 records."
+```
+
+`t(path, fallback)` walks the dotted path on `window.LcpI18n`, returning the fallback on any missing segment or non-string leaf. The bridge namespace mirrors `config/locales/en.yml` 1:1 (e.g., `lcp_ruby.advanced_filter.toggle` → `LcpI18n.advanced_filter.toggle`), so a lookup key is the engine key minus the `lcp_ruby.` prefix.
+
+### Usage from a Stimulus controller
+
+```js
+import { Controller } from "@hotwired/stimulus";
+
+export default class extends Controller {
+  static targets = ["status"];
+
+  connect() {
+    this.statusTarget.textContent = window.LcpI18n.t(
+      "upload.in_progress",
+      "Uploading..."
+    );
+  }
+
+  onError(err) {
+    const tmpl = window.LcpI18n.t(
+      "file_upload.too_large",
+      "File too large: %{limit}"
+    );
+    this.statusTarget.textContent = window.LcpI18n.format(tmpl, {
+      limit: err.limit,
+    });
+  }
+}
+```
+
+The `|| "fallback"` defensive pattern in legacy controllers (`(window.LcpI18n && window.LcpI18n.x) || "..."`) is no longer needed — `LcpI18n.t(...)` handles missing namespaces internally.
+
+### Exposing new host-app keys
+
+If your controller needs a key that the engine does not ship, add it to your host locale file and extend the payload helper by monkey-patching or by rendering your own `<script>` tag in the layout:
+
+```ruby
+# config/initializers/lcp_ruby_i18n.rb
+module MyApp::I18nPayloadExtensions
+  def lcp_i18n_payload
+    super.merge(
+      my_app: {
+        custom_action_confirm: t("my_app.custom_action_confirm")
+      }
+    )
+  end
+end
+LcpRuby::I18nPayloadHelper.prepend(MyApp::I18nPayloadExtensions)
+```
+
+Then in your Stimulus controller: `window.LcpI18n.t("my_app.custom_action_confirm", "Really?")`.
+
+### Rules
+
+- **Never bake user-visible strings into `.js.erb` assets.** Precompiled assets freeze strings to the asset-build locale; request-scoped rendering is the engine's single source of truth.
+- **Every `LcpI18n.t(...)` call passes a fallback.** Matches the Ruby `I18n.t(..., default: "…")` contract — the English wording stays visible in PR diffs.
+- **The regression guard** `lcp_ruby:i18n_lint` catches hardcoded `alert()`, `.textContent = "…"`, and `new Error("…")` in new JS controllers (see [Developer Tools](developer-tools.md#lcp_rubyi18n_lint)).
+
+Full namespace catalog: [`docs/reference/i18n.md`](../reference/i18n.md).
+
+## Auto-Discovery Setup
+
+LCP Ruby extension directories (`app/actions/`, `app/event_handlers/`, `app/condition_services/`, `app/lcp_services/`) use their own namespacing conventions (e.g., `LcpRuby::HostActions::*`) which conflict with Rails Zeitwerk autoloader expectations. You **must** exclude these directories from Zeitwerk before any `discover!` calls.
+
+### Step 1: Exclude from Zeitwerk
+
+Add an initializer in `config/application.rb` to ignore LCP extension directories:
+
+```ruby
+# config/application.rb
+module MyApp
+  class Application < Rails::Application
+    # ...
+
+    initializer "my_app.ignore_lcp_services", before: :set_autoload_paths do
+      %w[condition_services lcp_services actions event_handlers].each do |dir|
+        path = Rails.root.join("app", dir)
+        Rails.autoloaders.main.ignore(path) if path.directory?
+      end
+    end
+  end
+end
+```
+
+Without this, Zeitwerk will raise a `NameError` at boot because the file `app/condition_services/my_check.rb` defines `LcpRuby::HostConditionServices::MyCheck` instead of the expected top-level `MyCheck`.
+
+### Step 2: Register Discover Calls
+
+A typical host app registers all extensibility points in a single initializer:
+
+```ruby
+# config/initializers/lcp_ruby.rb
+LcpRuby.on_models_loaded do
+  app_path = Rails.root.join("app")
+
+  # Discover custom actions from app/actions/
+  LcpRuby::Actions::ActionRegistry.discover!(app_path.to_s)
+
+  # Discover event handlers from app/event_handlers/
+  LcpRuby::Events::HandlerRegistry.discover!(app_path.to_s)
+
+  # Discover condition services from app/condition_services/
+  LcpRuby::ConditionServiceRegistry.discover!(app_path.to_s)
+
+  # Discover custom renderers from app/renderers/
+  LcpRuby::Display::RendererRegistry.discover!(app_path.to_s)
+
+  # Discover services (transforms, validators, defaults, computed, conditions)
+  # from app/lcp_services/
+  LcpRuby::Services::Registry.discover!(app_path.to_s)
+end
+```
+
+> Use `LcpRuby.on_models_loaded` rather than `Rails.application.config.after_initialize` so the registries are repopulated after `LcpRuby.reload!` (autoreload on YAML edits in dev clears the registries via `LcpRuby.reset!`). See [Hook timing](#hook-timing).
+
+### Directory Convention
+
+```
+app/
+  actions/
+    deal/
+      close_won.rb              # LcpRuby::HostActions::Deal::CloseWon
+  event_handlers/
+    deal/
+      on_stage_change.rb        # LcpRuby::HostEventHandlers::Deal::OnStageChange
+  renderers/
+    conditional_badge.rb        # LcpRuby::HostRenderers::ConditionalBadge
+    charts/
+      sparkline.rb              # LcpRuby::HostRenderers::Charts::Sparkline
+  condition_services/
+    credit_check.rb             # LcpRuby::HostConditionServices::CreditCheck
+  lcp_services/
+    transforms/
+      titlecase.rb              # LcpRuby::HostServices::Transforms::Titlecase
+    validators/
+      deal_credit_limit.rb      # LcpRuby::HostServices::Validators::DealCreditLimit
+    defaults/
+      thirty_days_out.rb        # LcpRuby::HostServices::Defaults::ThirtyDaysOut
+    computed/
+      weighted_deal_value.rb    # LcpRuby::HostServices::Computed::WeightedDealValue
+  validators/
+    business_rule_validator.rb  # BusinessRuleValidator
+config/
+  lcp_ruby/
+    types/
+      proper_name.yml           # references "titlecase" transform
+    models/
+      deal.yml                  # references scopes, events, validations, computed, defaults
+```
+
+## Hook Timing
+
+LCP exposes three boot-time hooks that look superficially similar; pick the one whose timing matches what you need to register.
+
+| Hook | Fires when | Per | Re-fires on `LcpRuby.reload!` | Use for |
+|---|---|---|---|---|
+| `LcpRuby.configuration.on_model_ready(name) { |klass| … }` | Inside `ModelFactory::Builder#build` for one named model — i.e. as soon as that single dynamic class is built. | Per-model (one block per model name) | Yes — `Engine.reload!` calls `LcpRuby.reset_for_reload!`, which preserves `@configuration` (and therefore `model_extensions`); the registered callback fires again when the model is rebuilt. | Patching a specific dynamic class as soon as it exists — e.g. mixing in a host module before any other code references the class. Earliest available hook. |
+| `LcpRuby.on_models_loaded { |loader| … }` | Inside `Engine.load_metadata!`, after every dynamic class has been built and every Setup pass has run, **before** `RuntimeInvariantValidator` runs. | Globally (one drain per `load_metadata!`) | Yes — callbacks are persistent across drains: the same registered block fires on every `load_metadata!` call, including reloads. `Engine.reload!` does not blank the callback list. | Late-bound scope registrations referenced by permission YAML (`type: custom`), filter methods, predicate methods, and host-app registry discovery (`Actions::ActionRegistry.discover!`, etc.). The boot validator's AUTH-001 evaluates `klass.respond_to?(method)` *after* this drain, so scopes registered here pass the check. |
+| `Rails.application.config.after_initialize { … }` | Standard Rails hook, after the entire app boot completes (well after `Engine.load_metadata!`). | Globally (once per Rails process) | **No** — `after_initialize` is process-scoped; it does not re-run when `LcpRuby.reload!` rebuilds the metadata. | Rails-level concerns unrelated to LCP metadata: subscribing to `ActiveSupport::Notifications`, configuring third-party gems that depend on a fully-booted app. **Avoid for LCP extension registration** — the registry will be empty after a YAML reload in dev. |
+
+**Rule of thumb:** If the code references `LcpRuby::Dynamic::*` or any LCP registry that `Engine.reload!` clears, use `LcpRuby.on_models_loaded`. If you need to patch *one specific* dynamic class as soon as it's built (uncommon), use `on_model_ready`. Reserve `after_initialize` for things that have nothing to do with LCP metadata.
+
+The boot lifecycle in detail is documented in [`docs/design/authorization_hardening.md`](../design/authorization_hardening.md#boot-lifecycle-lcprubyon_models_loaded-new-hook).
+
+## Future Architecture
+
+This section outlines planned evolution of the extensibility system. None of this is implemented yet — it represents the target architecture.
+
+### Typed Parameter Contracts
+
+Actions currently receive raw `params`. The planned `param` DSL will provide typed, validated parameters with automatic form generation:
+
+```ruby
+class CloseWon < LcpRuby::Actions::BaseAction
+  param :reason, :string, required: true
+  param :close_date, :date, default: -> { Date.current }
+
+  def call
+    record.update!(stage: "closed_won", close_reason: params[:reason])
+    success(message: "Deal closed")
+  end
+end
+```
+
+The `param` declarations would:
+- Validate and coerce parameter types before `call` executes
+- Generate a `to_contract` representation for cross-language clients
+- Auto-generate form UIs for actions that require user input
+
+### Snapshot with Eager-Loaded Associations
+
+Actions and handlers currently receive a live ActiveRecord instance. A future `includes` declaration would eager-load associations into a snapshot, reducing N+1 queries and making the data available for serialization:
+
+```ruby
+class GenerateReport < LcpRuby::Actions::BaseAction
+  includes :line_items, :customer
+
+  def call
+    # record.line_items and record.customer are pre-loaded
+  end
+end
+```
+
+### Cross-Language Protocol
+
+The current extensibility system is Ruby-only. A future protocol layer would allow actions and handlers to be implemented in any language via JSON-RPC:
+
+```
+┌─────────────┐    JSON-RPC     ┌──────────────────┐
+│  LCP Ruby   │ ──────────────> │  External Process │
+│  (host)     │ <────────────── │  (Python, Node)   │
+└─────────────┘                 └──────────────────┘
+```
+
+Three approaches are under consideration:
+
+| Approach | What Crosses the Wire | Extension Complexity | Engine Complexity |
+|----------|----------------------|---------------------|-------------------|
+| **Thin protocol** | Minimal context, extensions call back for data | Low engine work | Extensions must handle API calls |
+| **Rich snapshot** | Pre-built data snapshot with eager-loaded associations | Medium engine work | Extensions are simpler |
+| **Full SDK** | Client SDK with ORM-like API over the wire | High engine work | Extensions feel native |
+
+The likely path is starting with the rich snapshot approach — serialize the record plus declared `includes` into a JSON payload, send to the external process, receive a result or mutation list back.
+
+### ProcessRunner
+
+A `ProcessRunner` would manage external process lifecycle for the cross-language protocol:
+
+- Start/stop external processes on demand
+- Health checks and automatic restart
+- Timeout and circuit-breaker patterns
+- Stdin/stdout JSON-RPC communication
+
+This enables a deployment model where the host Rails app manages extension processes as children, without requiring separate infrastructure.