lcp 0.1.0

data/docs/reference/auditing.md

@@ -0,0 +1,277 @@
+# Auditing Reference
+
+Auditing records field-level change history (create, update, destroy, discard, undiscard) for models with `auditing: true`. Changes are stored in a dedicated audit log model.
+
+## Prerequisites
+
+Generate the audit log model:
+
+```bash
+rails generate lcp_ruby:auditing
+```
+
+This creates:
+- `config/lcp_ruby/models/audit_log.yml` — model with required fields
+- `config/lcp_ruby/presenters/audit_logs.yml` — presenter for browsing logs
+- `config/lcp_ruby/permissions/audit_log.yml` — read-only permissions
+- `config/lcp_ruby/views/audit_logs.yml` — view group with navigation
+
+## Model Option
+
+### `auditing`
+
+| | |
+|---|---|
+| **Default** | `false` (disabled) |
+| **Type** | `true`, `false`, or Hash |
+
+**Simple form** — tracks all fields:
+
+```yaml
+options:
+  auditing: true
+```
+
+**Hash form** — fine-grained control:
+
+```yaml
+options:
+  auditing:
+    only:
+      - title
+      - status
+    track_associations: true
+    expand_custom_fields: true
+    expand_json_fields:
+      - addresses
+```
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `only` | array of strings | all fields | Track only these fields. Mutually exclusive with `ignore`. |
+| `ignore` | array of strings | none | Track all fields except these. Mutually exclusive with `only`. |
+| `track_associations` | boolean | `true` | Include nested_attributes child changes in parent audit entry |
+| `track_attachments` | boolean | `false` | Include attachment changes in audit trail (reserved, not yet implemented) |
+| `expand_custom_fields` | boolean | `true` | Expand `custom_data` JSON into individual `cf:` prefixed field changes |
+| `expand_json_fields` | array of strings | `[]` | JSON columns to expand into dot-path key changes |
+
+`only` and `ignore` are mutually exclusive — specifying both causes a validation error at boot time.
+
+## Audit Log Model Contract
+
+The audit log model must have these required fields:
+
+| Field | Type | Purpose |
+|-------|------|---------|
+| `auditable_type` | string | Model name of the audited record |
+| `auditable_id` | integer | Primary key of the audited record |
+| `action` | string | Operation: `create`, `update`, `destroy`, `discard`, `undiscard` |
+| `changes_data` | json | Field-level diffs: `{ "field": [old, new] }` |
+
+Recommended fields (warnings if missing):
+
+| Field | Type | Purpose |
+|-------|------|---------|
+| `user_id` | integer | ID of the user who made the change |
+| `user_snapshot` | json | JSON snapshot of the user at write time (see fields below) |
+
+#### `user_snapshot` Fields
+
+The snapshot is captured by `LcpRuby::UserSnapshot.capture(user)` (`lib/lcp_ruby/user_snapshot.rb`) and only includes keys for methods the user object responds to. Always defensive-access in views — any key may be missing.
+
+| Key | Type | Source | Captured when |
+|-----|------|--------|---------------|
+| `id` | integer | `current_user.id` | always (snapshot is `nil` if user is anonymous) |
+| `email` | string | `current_user.email` | `user.respond_to?(:email)` |
+| `name` | string | `current_user.name` | `user.respond_to?(:name)` |
+| `role` | string \| array | `current_user.send(role_method)` | `user.respond_to?(role_method)` (default `:lcp_role`, see [engine configuration](engine-configuration.md#role_method)) |
+
+Defensive access in views:
+
+```erb
+<%= log.user_snapshot&.dig("name") || log.user_snapshot&.dig("email") || "—" %>
+```
+
+Additional fields supported:
+
+| Field | Type | Purpose |
+|-------|------|---------|
+| `metadata` | json | Request ID and other context |
+| `created_at` | datetime | Timestamp (or enable `timestamps: true`) |
+
+The contract is validated at boot time. Missing required fields raise `MetadataError`. Missing recommended fields produce warnings.
+
+## Changes Data Format
+
+### Scalar Fields
+
+```json
+{
+  "title": ["Old Title", "New Title"],
+  "amount": [100, 200],
+  "active": [true, false]
+}
+```
+
+Each entry is `[old_value, new_value]`. On create, old is `null`. On destroy, new is `null`.
+
+### Custom Field Expansion
+
+When `expand_custom_fields` is `true` (default), changes to the `custom_data` column are expanded:
+
+```json
+{
+  "cf:risk_level": [30, 80],
+  "cf:priority": ["low", "high"]
+}
+```
+
+Keys unchanged between old and new values are omitted.
+
+### JSON Field Expansion
+
+Fields listed in `expand_json_fields` are expanded into dot-path keys for Hash values:
+
+```json
+{
+  "addresses.city": ["Prague", "Bratislava"],
+  "addresses.zip": ["11000", "81101"]
+}
+```
+
+Non-Hash JSON values (arrays, scalars) are stored as whole-value diffs.
+
+### Nested Association Changes
+
+When `track_associations` is `true` (default), nested_attributes child changes use colon-separated keys:
+
+```json
+{
+  "items:created": [{"name": "Widget", "quantity": 5}],
+  "items:updated": [{"id": 3, "quantity": [2, 10]}],
+  "items:destroyed": [{"id": 7, "name": "Deleted Item"}]
+}
+```
+
+Only loaded associations with `nested_attributes: true` are tracked.
+
+### Discard/Undiscard
+
+Discard and undiscard actions record the action type with empty changes:
+
+```json
+{"action": "discard", "changes_data": {}}
+```
+
+Soft delete columns are excluded from diffs; the action type conveys the operation.
+
+## Excluded Fields
+
+These fields are always excluded from audit diffs:
+
+| Category | Fields |
+|----------|--------|
+| Framework | `id`, `created_at`, `updated_at` |
+| Userstamps | `created_by_id`, `updated_by_id`, `created_by_name`, `updated_by_name` (when userstamps enabled) |
+| Soft delete | `discarded_at`, `discarded_by_type`, `discarded_by_id` (when soft delete enabled) |
+
+## Instance Methods
+
+Models with `auditing: true` get these methods:
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `audit_logs` | `ActiveRecord::Relation` | All audit entries for this record, ordered by `created_at DESC` |
+| `audit_history(limit: 50)` | `ActiveRecord::Relation` | Audit entries with a limit |
+
+These are query methods (not ActiveRecord associations), so `includes(:audit_logs)` is not supported.
+
+## Show Page Section
+
+Audited models automatically get an `audit_history` section appended to their show page. To control placement, add it explicitly:
+
+```yaml
+show:
+  layout:
+    - section: "Details"
+      fields: [...]
+    - type: audit_history
+```
+
+The auto-append is skipped if an `audit_history` section is already present in the layout.
+
+## Engine Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `audit_model` | String | `"audit_log"` | Name of the LCP Ruby model that stores audit entries |
+| `audit_model_fields` | Hash | See below | Maps logical field names to actual column names |
+| `audit_writer` | Object | `nil` | Custom writer; when set, bypasses built-in audit log model |
+
+### `audit_model_fields` Default
+
+```ruby
+{
+  auditable_type: "auditable_type",
+  auditable_id: "auditable_id",
+  action: "action",
+  changes_data: "changes_data",
+  user_id: "user_id",
+  user_snapshot: "user_snapshot",
+  metadata: "metadata"
+}
+```
+
+### Custom Audit Writer
+
+Must implement `#log(action:, record:, changes:, user:, metadata:)`. When configured, the built-in audit log model is not used.
+
+## Generator
+
+```bash
+rails generate lcp_ruby:auditing
+```
+
+Creates the standard audit log model, presenter, permissions, and view group files. Run once before enabling `auditing: true` on any model.
+
+## DSL
+
+```ruby
+LcpRuby.define_model(:project) do
+  field :title, :string
+
+  auditing                           # all fields
+  auditing only: [:title, :status]   # specific fields
+  auditing ignore: [:description]    # exclude fields
+end
+```
+
+## Validation
+
+The `ConfigurationValidator` checks:
+- `only` and `ignore` are mutually exclusive (error)
+- `only`/`ignore` reference existing field names (warning)
+- `expand_json_fields` references fields of type `json`/`jsonb` (warning)
+
+## Architecture
+
+```
+Model YAML (auditing: true)
+  → AuditingApplicator installs after_create/update/destroy callbacks
+  → Callbacks call AuditWriter.log
+  → AuditWriter computes diffs, filters, expands JSON/custom fields
+  → Writes to audit log model (or delegates to custom writer)
+
+SoftDeleteApplicator (discard!/undiscard!)
+  → Calls AuditWriter.log directly (update_columns bypasses AR callbacks)
+
+LayoutBuilder (show page)
+  → Auto-appends audit_history section if model has auditing + registry available
+
+Auditing::Setup (boot time)
+  → Checks any model has auditing: true
+  → Validates audit model exists and satisfies contract
+  → Marks Auditing::Registry as available
+```
+
+Source: `lib/lcp_ruby/auditing/`, `lib/lcp_ruby/model_factory/auditing_applicator.rb`, `lib/lcp_ruby/presenter/layout_builder.rb`

data/docs/reference/boot_lifecycle.md

@@ -0,0 +1,188 @@
+# Boot / Reload Lifecycle Reference
+
+This document is the canonical reference for **when** the engine
+loads metadata, **how** dev mode reloads it, **how** the database
+lifecycle interacts with platform-managed tables, and which
+extension hooks fire at which stage.
+
+For the design rationale (why this shape was chosen, what was
+considered and rejected), see
+[`docs/design/boot_reload_lifecycle.md`](../design/boot_reload_lifecycle.md)
+and
+[`docs/design/authorization_hardening.md`](../design/authorization_hardening.md).
+
+For the host-author's view of the extension hooks specifically,
+see [`docs/guides/extensibility.md` § Hook Timing](../guides/extensibility.md#hook-timing).
+
+## Phases of engine boot
+
+Every engine boot proceeds through five ordered phases. Most host
+extension code wants to live in phase 4.
+
+| # | Phase | Triggers | What runs |
+|---|---|---|---|
+| 1 | `before_configuration` | Rails app initialization | Engine constants load |
+| 2 | Engine initializers | Rails initializer chain | `lcp_ruby.configuration`, `lcp_ruby.load_metadata` (registers `on_load`), `lcp_ruby.dev_metadata_watch`, `lcp_ruby.api_tokens`, … |
+| 3 | `on_load(:active_record)` | First touch of `AR::Base` | `LcpRuby::Engine.load_metadata!` body — model build, schema, registries, validator |
+| 4 | `after_initialize` | Rails app boot completes | Audit subscriber install, host `on_models_loaded` callbacks already drained |
+| 5 | Per-request reload (dev only) | `Reloader.to_prepare` | `dev_metadata_watch` checker may fire `Engine.reload!` |
+
+Phase 3 is the load-bearing one for everything else — it is what
+populates `LcpRuby.loader.*_definitions`, materialises tables, fires
+`LcpRuby.on_models_loaded` callbacks, runs the
+`RuntimeInvariantValidator`, and finally instruments
+[`boot.lcp_ruby`](#instrumentation).
+
+## Extension hooks (when each fires)
+
+The engine exposes three boot-time hooks. Pick the one whose timing
+matches what you need to register.
+
+| Hook | Fires when | Per | Re-fires on `LcpRuby.reload!` |
+|---|---|---|---|
+| `LcpRuby.configuration.on_model_ready(name) { \|klass\| … }` | Inside `ModelFactory::Builder#build` for one named model — as soon as that single dynamic class is built. | Per-model | Yes — `Engine.reload!` calls `reset_for_reload!` which preserves `@configuration` (and therefore `model_extensions`); the callback fires again when the model is rebuilt. |
+| `LcpRuby.on_models_loaded { \|loader\| … }` | Inside `Engine.load_metadata!`, after every model is 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. |
+| `Rails.application.config.after_initialize { … }` | Standard Rails hook, after the entire app boot completes. | Globally (once per Rails process) | **No** — process-scoped |
+
+**Rule of thumb.** If your code references `LcpRuby::Dynamic::*` or
+any LCP registry that `LcpRuby.reset!` clears, use
+`LcpRuby.on_models_loaded`. Reserve `after_initialize` for things
+that have nothing to do with LCP metadata. Detailed comparison and
+examples in
+[`docs/guides/extensibility.md` § Hook Timing](../guides/extensibility.md#hook-timing).
+
+## Dev mode metadata reload
+
+In any environment with `Rails.application.config.enable_reloading =
+true` (development by default; custom envs that opt in), the
+engine watches `LcpRuby.configuration.metadata_path` (default
+`config/lcp_ruby/`) for changes to `*.yml` and `*.rb` files.
+
+```text
+configurator edits config/lcp_ruby/permissions/student.yml
+   ↓
+ActiveSupport::Reloader.to_prepare callback runs (next request)
+   ↓
+FileUpdateChecker reports updated → block fires
+   ↓
+LcpRuby::Engine.reload!  (mutex-protected, see below)
+   ↓
+LcpRuby.reset_for_reload!  →  load_metadata!  →  on_models_loaded drain
+   ↓
+reload.lcp_ruby AS::Notifications event
+   ↓
+request resumes against fresh metadata
+```
+
+**What is and isn't reloaded.** YAML / DSL Ruby files under
+`metadata_path` trigger reload. Files under `app/` (`app/actions/`,
+`app/event_handlers/`, `app/condition_services/`, `app/renderers/`,
+`app/lcp_services/`) are managed by Zeitwerk's own reloader; their
+class definitions reload independently. **Important asymmetry:**
+when YAML changes, `Engine.reload!` re-fires every `discover!` call
+that touches `app/` (some are wired into `on_models_loaded` via
+`Phase 1`'s install_generator block, others are called directly
+inside `Engine.load_metadata!`), so registries stay consistent on
+the YAML-edit path. When only an `app/`-side file changes, our
+checker doesn't fire and the registry retains a stale class
+reference until the next YAML edit. See
+[`docs/design/boot_reload_lifecycle.md` § Q5](../design/boot_reload_lifecycle.md#open-questions)
+for the open follow-up.
+
+**Concurrency.** `Engine.reload!` is serialized against itself by
+`RELOAD_MUTEX`. In-flight requests holding old `LcpRuby::Dynamic::*`
+class references see stale data for their remaining lifetime;
+the next request's pundit lookup and policy build see the fresh
+state. Production never auto-reloads (deploy contract is rolling
+restart / blue-green); test disables `enable_reloading` so the
+watcher is silent there.
+
+**Failure handling.** If a YAML edit is invalid (typo, broken DSL),
+the reload raises `MetadataError` or
+`Authorization::InvariantError`; engine state is rolled back to a
+clean reset and the underlying error renders on the request page.
+The next save re-triggers the watcher.
+
+## Database lifecycle
+
+Platform-managed tables are materialised by `SchemaManager` —
+called both inside `Engine.load_metadata!` (the normal request-stack
+path) and from a dedicated rake task for the rake lifecycle path.
+
+### `lcp_ruby:ensure_tables`
+
+```bash
+bundle exec rake lcp_ruby:ensure_tables
+```
+
+Idempotent. Bootstraps `Engine.load_metadata!` if not yet booted,
+then iterates `LcpRuby.loader.model_definitions` in topological
+order (parents before STI children) and invokes
+`SchemaManager.ensure_table!` on every non-`bind_to`, non-virtual
+model. Existing tables are checked via `connection.table_exists?`
+and left untouched.
+
+### Rails `db:*` integration
+
+The engine enhances `db:prepare` and `db:setup` to invoke
+`lcp_ruby:ensure_tables` as a post-action. `db:reset` chains to
+`db:setup` and inherits the fix transitively. Concretely:
+
+```bash
+bundle exec rails db:drop db:prepare db:seed
+# db:prepare runs Rails migrations (e.g. active_storage)
+# db:prepare's post-action invokes lcp_ruby:ensure_tables
+#   → bootstraps load_metadata! if needed
+#   → recreates LCP-managed tables idempotently
+# db:seed runs against a complete schema
+```
+
+Without the post-action, the chain `db:drop → db:prepare → db:seed`
+in one process would fail: `db:drop` removes the tables but the
+in-memory `@metadata_loaded` flag survives, so a subsequent
+`Engine.load_metadata!` short-circuits without re-running the
+schema. The post-action's per-model `SchemaManager.ensure_table!`
+loop bypasses that flag.
+
+## Instrumentation
+
+The engine emits two `ActiveSupport::Notifications` events that
+host apps can subscribe to.
+
+| Event | Fires when | Payload |
+|---|---|---|
+| `boot.lcp_ruby` | End of every `Engine.load_metadata!` call | `models_count`, `presenters_count`, `pages_count` |
+| `reload.lcp_ruby` | End of every successful `Engine.reload!` (after the inner `load_metadata!` succeeds) | Same fields |
+
+`boot.lcp_ruby` fires both on initial process boot AND on every
+reload (because reload calls `load_metadata!` internally).
+`reload.lcp_ruby` fires *only* on the reload path. Subscribers
+that need to differentiate "first boot" from "subsequent reload"
+should listen to `reload.lcp_ruby`; subscribers that just need to
+know "metadata is loaded and ready" should listen to
+`boot.lcp_ruby`.
+
+```ruby
+# config/initializers/lcp_observability.rb
+ActiveSupport::Notifications.subscribe("reload.lcp_ruby") do |*args|
+  event = ActiveSupport::Notifications::Event.new(*args)
+  Rails.logger.info(
+    "[host-app] LCP reloaded — #{event.payload[:models_count]} models, " \
+    "#{event.payload[:presenters_count]} presenters"
+  )
+end
+```
+
+> **Subscribe location.** Wire subscriptions in
+> `Rails.application.config.after_initialize` (or any `Rails.application
+> .config.to_prepare` block), **not** inside `LcpRuby.on_models_loaded`.
+> AS::Notifications subscribers are process-scoped and survive
+> `LcpRuby.reset!`; subscribing inside `on_models_loaded` would add a
+> duplicate subscription on every reload.
+
+## Related references
+
+- [`docs/design/boot_reload_lifecycle.md`](../design/boot_reload_lifecycle.md) — design rationale, decisions, open questions
+- [`docs/design/authorization_hardening.md`](../design/authorization_hardening.md) — `on_models_loaded` hook origin, RELOAD_MUTEX, invariant validator
+- [`docs/guides/extensibility.md` § Hook Timing](../guides/extensibility.md#hook-timing) — host-author guide for the extension hooks
+- [`docs/reference/invariant_check.md`](invariant_check.md) — boot-time invariant validator that runs after the metadata-load drain

data/docs/reference/cascading_selects.md

@@ -0,0 +1,189 @@
+# Cascading Selects
+
+Cascading `<select>` widgets where the available options of a child
+select depend on the value(s) of one or more parent selects. The same
+JS controller drives both **AR-record forms** (presenter forms, edit /
+new) and **page filter forms** — adding a new context just sets a
+different form-level data attribute.
+
+> **Spec:** the JS generalization (`data-lcp-cascade-name-format`,
+> multi-parent array URL builder, reverse-cascade opt-out) shipped in
+> PR 3 of [Page Filters as Virtual Forms](../design/page_filters_as_virtual_forms.md).
+> Earlier the controller hard-coded the `record[<field>]` name pattern
+> and the cascade was form-only.
+
+## Quick anatomy
+
+```
+┌─ <form data-controller="lcp-cascading-selects">
+│    data-lcp-select-options-path="/showcase/.../select_options"
+│    data-lcp-cascade-name-format="page_filter[{field}]"   (or record[{field}])
+│    data-lcp-reverse-cascade="off"   (filter forms; presenter forms omit it)
+│
+│  ┌─ <select name="page_filter[department_id]"> (PARENT)
+│  └─ <select name="page_filter[team_id]"             (CHILD)
+│           data-lcp-depends-on="department_id"
+│           data-lcp-depends-fk="department_id"
+│           data-lcp-depends-reset="clear">           (or "keep_if_valid")
+```
+
+## Form-level data attributes
+
+These live on the `<form>` and are read once on Stimulus `connect()`.
+
+| Attribute | Purpose | Default |
+|---|---|---|
+| `data-controller` | Must include `lcp-cascading-selects` | — |
+| `data-lcp-select-options-path` | URL path of the `/select_options` endpoint | required |
+| `data-lcp-cascade-name-format` | Templated parent-input `name` pattern. `{field}` is replaced by the child's `data-lcp-depends-on` value. | `record[{field}]` |
+| `data-lcp-reverse-cascade` | `"off"` disables reverse cascade (child → ancestors auto-fill). Filter forms set this; presenter forms typically don't. | (reverse cascade enabled) |
+
+`data-lcp-cascade-name-format` is the contract that lets one
+controller drive both `record[department_id]` (presenter forms) and
+`page_filter[department_id]` (filter forms) without special-casing the
+name pattern in JS.
+
+**Why a plain `data-lcp-...` attribute (not a Stimulus `*-value`).**
+The controller reads `form.dataset.lcpSelectOptionsPath` directly, not
+via Stimulus' `static values = { … }` API. The Stimulus-values
+convention would map to `data-lcp-cascading-selects-select-options-path-value`,
+which is verbose and easy to mistype. The shorter form is part of the
+controller's public contract. Setting the Stimulus-values name instead
+silently disables the controller — the controller early-returns when
+`selectOptionsPath` is undefined.
+
+## Per-child data attributes
+
+These live on each child `<select>` and are read by the controller for
+that specific cascade edge.
+
+| Attribute | Purpose |
+|---|---|
+| `data-lcp-depends-on` | Field name of the parent select (matches `{field}` in the form-level name format). |
+| `data-lcp-depends-fk` | Column on the child's target model used to filter by parent value (`WHERE foreign_key = ?`). |
+| `data-lcp-depends-reset` | `clear` (default — child blanks on parent change) or `keep_if_valid` (child keeps its value if still present in the new option set). |
+| `data-lcp-tom-select-depends-on-value` | Mirror of `depends_on` for the Tom Select widget — Tom Select reads this to know which input to subscribe to. |
+
+These four are emitted by `form_helper.rb#apply_depends_on_attrs!`
+when the YAML field has `input_options.depends_on:`.
+
+## Forward cascade
+
+When a parent input fires `change`:
+
+1. Controller reads `parentValue` via `getFieldValues(form, parentField)`
+   (Array for `<select multiple>`) falling back to `getFieldValue`
+   (scalar). Empty value → reset child to blank, no AJAX.
+2. Builds URL `selectOptionsPath?field=<child>&depends_on[<parent>]=<v>`
+   (or `&depends_on[<parent>][]=v1&[…][]=v2` for multi-parent).
+3. `fetch()` with `Accept: application/json`. Adds `aria-busy="true"`
+   on the child during fetch.
+4. On response: destroy Tom Select if present, rebuild `<option>` set,
+   reinitialize Tom Select.
+5. Restores focus to the previously-focused element (Tom Select 2.x
+   derives `*-ts-control` ids deterministically; the stashed id
+   resolves after rebuild).
+6. Dispatches `lcp:cascade-done` CustomEvent on the child for tests
+   and downstream listeners.
+7. Updates the singleton `#lcp-cascade-live` ARIA region with a
+   polite announcement (`lcp_ruby.form.cascade_loading` i18n key).
+
+`getFieldValue` / `getFieldValues` live in
+[`app/assets/javascripts/lcp_ruby/utils.js`](../../app/assets/javascripts/lcp_ruby/utils.js)
+and handle the `[name][]` array-suffix that Rails appends to multi-value
+form helpers.
+
+## Reverse cascade
+
+When a child select fires `change` and the cascade chain has at least
+one empty ancestor, the controller fetches
+`selectOptionsPath?field=<child>&ancestors_for=<selected_value>` and
+auto-fills the ancestor selects from the response's `ancestors:` array.
+
+**Opt out** with `data-lcp-reverse-cascade="off"` on the form. Filter
+forms set this — a filter "team = Backend" should NOT auto-set
+"department = Engineering" because the user might pick teams across
+departments. Presenter record forms typically leave reverse cascade
+enabled.
+
+## `/select_options` endpoint
+
+The controller posts to a single endpoint that resolves field-config
+from a fallback chain (in `resources_controller.rb`):
+
+1. Presenter form fields (`current_presenter.form.sections[].fields[]`)
+2. **Filter form fields (`current_page.filter_form_definition`)** ← added in PR 5
+3. Presenter search parameters (`current_presenter.search.parameters[]`)
+
+Each layer returns a `{field, association, multi_select_association, input_options}`
+hash; downstream code (`AssociationOptionsBuilder.build_options_query`,
+`policy_scope`, sorting, label resolution) is identical across layers.
+
+On dashboards where `current_presenter` is nil, only layer 2 fires —
+the helper `filter_options_url_for(field_name)` builds the URL from
+`current_page.slug` without requiring `current_presenter`.
+
+## Multi-parent cascade
+
+A child select can declare multiple parents via repeated chain (each
+`<select>` in the DOM with its own `data-lcp-depends-on`). The
+controller walks the chain at `_initForwardCascade`:
+
+```html
+<select name="page_filter[bu_code]"           multiple>...</select>
+<select name="page_filter[division_id]"       data-lcp-depends-on="bu_code">...</select>
+<select name="page_filter[subdivision_id]"    data-lcp-depends-on="division_id">...</select>
+```
+
+A change on `bu_code` (multi-value `[10, 20]`) → AJAX with
+`?depends_on[bu_code][]=10&depends_on[bu_code][]=20` →
+`AssociationOptionsBuilder` UNIONs divisions across both BUs.
+
+Grandparent-level cascades happen by the child's listener also firing
+on its grandparent change indirectly: when `division_id` rebuilds
+(triggered by bu_code change), the `subdivision_id` listener picks
+up `division_id`'s change event and re-fetches.
+
+## Accessibility
+
+| Affordance | Implementation |
+|---|---|
+| `aria-busy="true"` during AJAX | Set on the child select before fetch; cleared after rebuild |
+| Polite live region | Singleton `#lcp-cascade-live` div with `role="status"`, `aria-live="polite"`, `aria-atomic="true"` |
+| Live announcement | `lcp_ruby.form.cascade_loading` i18n template (`"Options updated for %{field}"`) — `%{field}` is the child's `<label>` text |
+| Focus restoration | `document.activeElement.id` stashed before Tom Select destroy; restored via `getElementById(...).focus()` after rebuild |
+
+Pinned by `spec/system/cascading_selects_spec.rb` (acceptance test #21).
+
+## Reset strategies
+
+`data-lcp-depends-reset` on the child controls what happens when the
+parent value disappears or no longer makes the current child value
+reachable:
+
+| Value | Behavior |
+|---|---|
+| `clear` (default) | Child blanks on parent change |
+| `keep_if_valid` | Child keeps its current value IF that value is still in the new option set; otherwise blanks |
+
+`keep_if_valid` is the right choice when the parent change is
+incidental (e.g. a user editing a related field) and the child value is
+expected to remain valid. `clear` is the default because most cascade
+chains have a strict tree shape where a parent change does invalidate
+the child.
+
+## Race semantics
+
+**Last-write-wins.** If the user changes the parent twice in quick
+succession, the second AJAX response wins regardless of which fetch
+finishes first. `fetch()` promises are not cancelled. This is the
+spec § 3 invariant; a strict cancel-in-flight strategy is an open
+question in the spec § 8.
+
+## Source
+
+- JS controller: [`app/assets/javascripts/lcp_ruby/controllers/cascading_selects_controller.js`](../../app/assets/javascripts/lcp_ruby/controllers/cascading_selects_controller.js)
+- Form-helper emission: [`app/helpers/lcp_ruby/form_helper.rb#apply_depends_on_attrs!`](../../app/helpers/lcp_ruby/form_helper.rb)
+- Endpoint: `select_options` action in [`app/controllers/lcp_ruby/resources_controller.rb`](../../app/controllers/lcp_ruby/resources_controller.rb)
+- Option resolution: [`app/helpers/lcp_ruby/association_options_builder.rb`](../../app/helpers/lcp_ruby/association_options_builder.rb)
+- System tests: [`spec/system/cascading_selects_spec.rb`](../../spec/system/cascading_selects_spec.rb), [`spec/system/filter_form_spec.rb`](../../spec/system/filter_form_spec.rb)