lcp 0.1.0

data/docs/guides/import.md

@@ -0,0 +1,165 @@
+# Import Guide
+
+This guide walks through setting up data import on your presenters, from basic CSV import to nested `has_one` associations.
+
+## Prerequisites
+
+- A working LCP Ruby application with at least one model and presenter
+- For XLSX support: add `gem 'roo'` to your Gemfile
+- For import profiles and per-row tracking: run the import generator (see below)
+
+## Basic Setup
+
+### 1. Run the Generators
+
+```bash
+# Background jobs (required first)
+rails generate lcp_ruby:background_jobs
+
+# Import models (import_row, import_profile, data_import job)
+rails generate lcp_ruby:import
+```
+
+### 2. Add Import Config to Your Presenter
+
+**DSL:**
+
+```ruby
+define_presenter :employees do
+  model :employee
+
+  import formats: [:csv, :xlsx], max_rows: 5000
+
+  action :import, type: :built_in, on: :collection, icon: "upload"
+end
+```
+
+**YAML:**
+
+```yaml
+presenter:
+  name: employees
+  model: employee
+
+  import:
+    formats: [csv, xlsx]
+    max_rows: 5000
+
+  actions:
+    collection:
+      - { name: import, type: built_in, icon: upload }
+```
+
+### 3. Upload and Import
+
+1. Click the **Import** button in the collection toolbar
+2. **Phase 1:** Upload a CSV/XLSX file, select strategy, pick match attribute (for update/upsert)
+3. **Phase 2:** Review column mapping (auto-mapped by header names), adjust as needed
+4. Click **Start Import** — the job runs in the background
+
+## Import Strategies
+
+| Strategy | When to use |
+|----------|-------------|
+| `create_only` | First-time data load, all rows are new records |
+| `upsert` | Regular sync — update existing, create new |
+| `update_only` | Patch existing records only, error if not found |
+| `skip_existing` | Import only records that don't exist yet |
+
+For `upsert`, `update_only`, and `skip_existing`, the user selects a **match attribute** (e.g., `email`, `sku`) used to find existing records.
+
+## Nested has_one Import
+
+Import flat CSV rows into a parent record and its `has_one` associations in one operation.
+
+### 1. Enable nested_attributes on the Model
+
+```ruby
+define_model :employee do
+  has_one :employee_profile, model: :employee_profile,
+    dependent: :destroy, inverse_of: :employee,
+    nested_attributes: true  # safe defaults: reject_if: all_blank, update_only: true
+end
+```
+
+The boolean shorthand `nested_attributes: true` is equivalent to:
+
+```ruby
+nested_attributes: { reject_if: :all_blank, update_only: true }
+```
+
+### 2. Configure the Presenter
+
+```ruby
+define_presenter :employees do
+  import formats: [:csv, :xlsx], max_rows: 5000,
+    nested_associations: [:employee_profile],    # whitelist (optional)
+    nested_blank_strategy: "skip"                # preserve existing values on blank
+end
+```
+
+| Option | Description |
+|--------|-------------|
+| `nested_associations` | Array of association names to expose. When omitted, all `has_one` with `nested_attributes` are shown. |
+| `nested_blank_strategy` | `"null"` (default): blank → nil (overwrites). `"skip"`: blank → omit (preserves existing). |
+
+### 3. Prepare the CSV
+
+Use dot-notation in your mental model — the UI handles it automatically:
+
+```csv
+Name,Email,Hire Date,Salary,Contact Name,Relationship
+Alice,alice@co.cz,2024-01-15,72000,Karel,spouse
+Bob,bob@co.cz,2024-06-01,65000,,,
+```
+
+In the mapping step, map:
+- `Hire Date` → `employee_profile.hire_date` (auto-mapped by suffix)
+- `Salary` → `employee_profile.salary` (auto-mapped)
+- `Contact Name` → `employee_emergency_contact.contact_name` (auto-mapped)
+
+### 4. How Blank Values Work
+
+**All nested columns blank** (like Bob's Contact Name + Relationship above):
+- No nested record is created (`reject_if: :all_blank`)
+
+**Some nested columns blank** (e.g., Salary blank but Hire Date present):
+- `nested_blank_strategy: "null"`: Salary set to nil (overwrites existing data)
+- `nested_blank_strategy: "skip"`: Salary omitted, existing value preserved
+
+### 5. Upsert with Nested Records
+
+When re-importing with `upsert` strategy:
+- Existing nested record → updated in-place (same DB record ID preserved)
+- No existing nested record → new one created
+- All nested columns blank → existing nested record untouched
+
+## Type Coercion
+
+Configure parsing options for non-standard formats:
+
+```ruby
+import formats: [:csv], parsing: {
+  date_format: ["%d.%m.%Y", "%Y-%m-%d"],
+  boolean_true: %w[true yes 1 ano],
+  boolean_false: %w[false no 0 ne],
+  decimal_separator: ","
+}
+```
+
+## Permissions
+
+- The `import` action must be in the role's `actions` list
+- Only `writable_fields` appear in the mapping picker
+- For nested fields, write permission is checked on the **target model** (not the parent)
+- A viewer role that can read Employee but not write to EmployeeProfile won't see nested profile fields
+
+## Saved Profiles
+
+During Phase 2, check **Save as profile** and enter a name. Next time, load the profile to pre-fill all mappings.
+
+## See Also
+
+- [Import Reference](../reference/import.md) — Full attribute reference
+- [Models Reference — Nested Attributes](../reference/models.md#nested-attributes) — Model configuration
+- [Export Guide](export.md) — Data export setup

data/docs/guides/inherited-permissions.md

@@ -0,0 +1,459 @@
+# Inherited Permissions
+
+`inherits_from:` is the declarative way to express *"a record is visible iff its parent record is visible"* — without writing Ruby scopes for every leaf model in a hierarchy. It is the recommended pattern for cascading visibility through `belongs_to` chains.
+
+For the underlying scope mechanism (`field_match`, `association`, `where`, `custom`), see the [Permissions Reference](../reference/permissions.md#scope). This guide focuses on the **inherits_from cascade** — when to use it, what it composes with, and how it interacts with the rest of the platform.
+
+## Motivation
+
+Consider a school registry:
+
+- Teachers should see students in their class (and only those students).
+- Parents should see their own children (and only their own).
+- Both should see grades for the students they're allowed to see.
+
+Without `inherits_from`, every leaf model (`grade`, `attendance`, `comment`, `note`) needs its own duplicated `accessible_by_user` Ruby scope walking back to the same root. With `inherits_from`, you write the visibility rule **once** on the parent, and every child reuses it through one declarative line.
+
+The same pain point is captured in [docs/improve-tasks/oncall-alerting.md #39](../improve-tasks/oncall-alerting.md) ("ownership by responsibility shortcut") for an on-call incident system: *"you can edit an incident only if you are currently assigned to its service's team's schedule"* — a 3-hop chain that becomes one `inherits_from` line per leaf.
+
+## Canonical example: school registry
+
+> **Runnable references.** Two complete versions of this example ship with the platform:
+>
+> - **Test fixture** — [`spec/fixtures/integration/inherits_from/`](../../spec/fixtures/integration/inherits_from/) exercised end-to-end by [`spec/integration/inherits_from_spec.rb`](../../spec/integration/inherits_from_spec.rb) (12 tests covering single-hop, 2-hop transitive, multi-role, scope overrides, and individual record `show?` cascade). Read the fixture for the wire-format YAML; read the spec for what each pattern produces against real ActiveRecord rows.
+> - **Showcase app** — [`examples/showcase/config/lcp_ruby/permissions/showcase_{school_class,student,grade}.yml`](../../examples/showcase/config/lcp_ruby/permissions/) is the same model exposed as a browsable UI in the showcase Rails app under **Permissions & Roles → Classes / Students / Grades**, with seed data ([`examples/showcase/db/seeds.rb`](../../examples/showcase/db/seeds.rb), search "Inherits-from cascade vignette") that demonstrates how visibility narrows under different roles.
+
+```yaml
+# permissions/school_class.yml
+permissions:
+  model: school_class
+  roles:
+    teacher:
+      crud: [index, show, update]
+      scope: { type: field_match, field: teacher_id, value: current_user.id }
+```
+
+```yaml
+# permissions/student.yml
+permissions:
+  model: student
+  inherits_from: school_class    # student visible iff its class visible
+  roles:
+    teacher:
+      crud: [index, show, update]
+      # no scope: → inherits from school_class
+    parent:
+      crud: [index, show]
+      scope: { type: field_match, field: guardian_id, value: current_user.id }
+      # parent role explicitly overrides inheritance with its own scope
+```
+
+```yaml
+# permissions/grade.yml
+permissions:
+  model: grade
+  inherits_from: student         # transitively cascades to school_class
+  roles:
+    teacher: { crud: [index, show, update] }
+    parent:  { crud: [index, show] }
+```
+
+What teacher A (assigned to class Alpha) sees:
+
+| Action | Student in class Alpha | Student in class Beta |
+|---|---|---|
+| `GET /students` index | Visible | Hidden |
+| `GET /students/:id` show | Permitted | 404 (scope) or denied (record check) |
+| `GET /grades?student=alice` | Visible (Alice in Alpha) | Hidden (Carol in Beta) |
+| `PUT /grades/:id` update | Permitted | Denied |
+
+The teacher writes nothing on `grade.yml` about `school_class` or `teacher_id`. The cascade emerges automatically through `inherits_from`.
+
+## Override per role
+
+A role can opt out of inheritance by defining its own `scope:`:
+
+```yaml
+inherits_from: student
+roles:
+  admin:
+    crud: [index, show, create, update, destroy]
+    scope: all                # admin sees ALL grades, regardless of student visibility
+  teacher:
+    crud: [index, show, update]
+    # no scope: → uses inherited scope
+  reporting_bot:
+    crud: [index]
+    scope:                    # role-level override, no inheritance
+      type: where
+      conditions: { exported: false }
+```
+
+**Override semantics — the four states of role.scope:**
+
+| Role-level YAML | Interpretation |
+|---|---|
+| `scope:` key absent | Inherit from `inherits_from` |
+| `scope: all` | Opt out — role sees all records |
+| `scope: { type: ..., ... }` | Override — role uses its own scope |
+| `scope: ~` (explicit nil) | **Rejected by validator** — write `scope: all` instead |
+
+The fourth state is rejected explicitly because YAML round-trips can blur the distinction between "key absent" and "key with nil value." The validator forces a clear choice.
+
+## Multi-parent inheritance
+
+When a child has multiple `belongs_to` to different parent models that should both gate visibility:
+
+```yaml
+# permissions/grade.yml
+permissions:
+  model: grade
+  inherits_from:
+    parent: [student, subject]
+    mode: intersection         # default: BOTH parents must permit
+  roles:
+    teacher: { crud: [index, show, update] }
+```
+
+**Mode options:**
+- `intersection` (default): all parents must permit visibility (AND).
+- `union`: any single parent permitting visibility is enough (OR).
+
+Use `union` sparingly — it widens access. The conservative default `intersection` matches how most domains read "the record's parents grant access."
+
+## STI parents and children
+
+Single-table inheritance composes naturally with `inherits_from`, both as parent and as child of the cascade.
+
+**STI as parent.** When `inherits_from: vehicle` points at an STI parent and a child record is created against an STI subclass (`Car`, `Truck`), the runtime resolves the parent record through `record.<association>` — which AR returns as the concrete subclass instance. The parent's policy_scope filters subclass instances correctly, no extra wiring needed.
+
+**STI as child.** When the child of the cascade is an STI parent (`vehicle` with subclasses `car`, `truck`) and one subclass has no permission file of its own, `Loader#yaml_permission_definition` falls back to the STI parent's permissions. So:
+
+```yaml
+# permissions/vehicle.yml — STI parent
+permissions:
+  model: vehicle
+  inherits_from: factory
+  roles:
+    operator: { crud: [index, show, update] }
+```
+
+A `Car` record (no `permissions/car.yml`) inherits `vehicle`'s `inherits_from: factory` automatically — the cascade applies to all subclasses by default.
+
+**STI subclass overrides shadow the parent.** When a subclass DOES ship its own permission file, that file takes precedence and the parent's `inherits_from` no longer applies to the subclass:
+
+```yaml
+# permissions/electric_car.yml — STI subclass with its own perms
+permissions:
+  model: electric_car
+  # No inherits_from here → ElectricCar instances skip the cascade entirely
+  roles:
+    operator: { crud: [index, show, update] }
+```
+
+If you want the subclass to keep cascading like the parent does, repeat `inherits_from: factory` (or the appropriate parent) in the subclass file. The platform doesn't merge YAML across the STI chain — the subclass file is a complete replacement.
+
+## Composition with other features
+
+`inherits_from` interacts cleanly with the rest of the platform:
+
+| Surface | Auto-protected? | Notes |
+|---|---|---|
+| Index listings | Yes | Index queries filter via inherited scope |
+| Show / edit / destroy | Yes | `policy_scope.find` + per-record cascade |
+| Export (CSV / XLSX) | Yes | `export_handler` uses `policy_scope` |
+| Batch actions | Yes | `batch_action_handler` uses `policy_scope` |
+| Approval tasks | Yes | Controller uses `policy_scope` |
+| Dashboard widgets | Yes | Widget data resolvers apply `policy_scope` |
+| Saved filter results | Yes | Filter conditions compose on top of `policy_scope` |
+| Ransack search | Yes | Ransack runs after `policy_scope` |
+| Custom field definitions | Composes | Orthogonal to scoped permissions for custom fields |
+| Workflow approvals | Composes | Inheritance gates visibility; transition `allowed_roles` gates state changes |
+| Cached aggregates | **No** | Precomputed values are global; for per-user counts use `aggregate_columns` (which IS scoped) or `policy_scope.count` directly |
+| `update_columns` / `update_all` | **No** | Rails skips validations; documented bypass — see Create-time validation below |
+
+The largest practical benefit: writing `inherits_from: project` on `task` correctly filters every export, every dashboard widget, every saved filter, every search query for tasks — without auditing 14 separate integration points.
+
+## Multi-tenant cascade pattern
+
+Multi-tenant SaaS apps typically partition data by tenant — a `belongs_to :organization` on every domain model plus per-request filtering by the signed-in user's organization. With `inherits_from`, you wire the cascade once at the tenant root and every domain model inherits the per-tenant gate automatically. No per-controller `where(organization_id:)`, no per-presenter scope blocks, no audit of every export and widget for "did I remember the tenant filter."
+
+### Worked example: organization → project → issue
+
+The pattern is three permission files (one self-scope at the root, two cascades):
+
+```yaml
+# config/lcp_ruby/permissions/organization.yml — root: each user sees only their own org
+permissions:
+  model: organization
+  roles:
+    member:
+      scope:
+        type: field_match
+        field: id
+        value: current_user.organization_id
+      crud: [index, show]
+```
+
+```yaml
+# config/lcp_ruby/permissions/project.yml — projects inherit visibility from organization
+permissions:
+  model: project
+  inherits_from: organization
+  roles:
+    member: { crud: [index, show, create, update] }
+```
+
+```yaml
+# config/lcp_ruby/permissions/issue.yml — issues inherit transitively via project
+permissions:
+  model: issue
+  inherits_from: project
+  roles:
+    member: { crud: [index, show, create, update, destroy] }
+```
+
+The `current_user.organization_id` value is interpolated at scope-resolve time by calling `organization_id` on `LcpRuby::Current.user`. Any `current_user.<method>` token dispatches the same way — typos are caught at boot by `lcp_ruby:validate`. See [Dynamic References](../reference/dynamic-references.md) for the full grammar. Your `User` model must expose `organization_id` (a real column or a delegated method).
+
+Every read path on `issue` — index, show, export, dashboard widget, saved filter, ransack search — resolves to a SQL shape equivalent to:
+
+```sql
+SELECT * FROM issues
+WHERE project_id IN (
+  SELECT id FROM projects
+  WHERE organization_id IN (
+    SELECT id FROM organizations WHERE id = $current_user.organization_id
+  )
+)
+```
+
+The cascade composes automatically. You wrote the tenant gate once.
+
+### The leak failure mode
+
+Multi-tenant cascade is a guideline, not an invariant. The platform cannot enforce "every model must inherit from organization" — tenant identity is application-domain. The risk: a configurator adds a new model and forgets the `inherits_from:` line.
+
+Concretely, suppose someone adds a `Comment` model:
+
+```yaml
+# config/lcp_ruby/models/comment.yml
+model:
+  name: comment
+  fields:
+    - { name: body, type: text }
+  associations:
+    - { type: belongs_to, name: issue, target_model: issue, foreign_key: issue_id }
+    - { type: belongs_to, name: organization, target_model: organization, foreign_key: organization_id }
+```
+
+```yaml
+# config/lcp_ruby/permissions/comment.yml — bug: no inherits_from
+permissions:
+  model: comment
+  roles:
+    member: { crud: [index, show, create] }
+```
+
+A user from organization A visits `/comments` and sees comments from organizations B, C, D — all of them. The SQL has no `organization_id` clause because nothing told the platform `comment` was tenant-scoped. The model has the FK column, but FKs alone don't gate reads; permission cascade does.
+
+This is silent: no error, no log entry, no test failure unless someone wrote a per-tenant integration test. Reviewers don't notice the missing line because the model "looks fine."
+
+### Boot-time validation
+
+Set `LcpRuby.configuration.tenant_association_name` to opt every model into a boot-time audit. The validator walks each model with a `belongs_to` matching that name and warns if the inheritance chain doesn't reach the tenant root.
+
+```ruby
+# config/initializers/lcp_ruby.rb
+LcpRuby.configure do |config|
+  config.tenant_association_name = :organization
+end
+```
+
+Now `bundle exec rake lcp_ruby:validate` (or boot in development) emits:
+
+```
+[WARN] Model 'comment' has belongs_to :organization but is not in the tenant cascade.
+       Add `inherits_from: organization` (directly, or via a parent that already inherits)
+       to the permission for 'comment', or set
+       `LcpRuby.configuration.tenant_association_name = nil` to disable this check.
+       Without it, queries on 'comment' may leak rows across tenants.
+```
+
+Default is `nil` — single-tenant apps see no behavior change. The check is a warning, not an error: hosts that genuinely have models exempt from the cascade (e.g. a public marketing-content table that should be visible cross-tenant) can leave them unflagged by either removing the `belongs_to` or accepting the warning. The transitive case `issue → project → organization` is recognized — leaves don't have to repeat `inherits_from: organization`.
+
+### Retrofit checklist
+
+Adding the cascade to an existing app:
+
+1. **Pick the tenant association name.** Whatever your `User` belongs to: `organization`, `tenant`, `account`, `workspace`. Stick to one across all models.
+2. **Write the root permission.** Self-scope using `field_match` with `current_user.<name>_id`. The user model must expose the matching method/column. See [Dynamic References](../reference/dynamic-references.md) for the grammar.
+3. **Add `inherits_from: <tenant>` to every domain model's permission.** Direct on first-tier models; transitively via a parent on deeper ones (no need to repeat the root on every leaf — the chain composes).
+4. **Enable the audit.** `LcpRuby.configuration.tenant_association_name = :<tenant>` in `config/initializers/lcp_ruby.rb`.
+5. **Run validate, resolve every warning.** `bundle exec rake lcp_ruby:validate`. Each warning names the offending model. Either add `inherits_from:` or accept the cross-tenant exposure as documented intent.
+
+The audit is a one-shot retrofit aid; once green, leave it on so future model additions can't silently regress the cascade.
+
+### Composition with scoped permissions
+
+If your app uses [scoped permissions](../design/scoped_permissions.md) for polymorphic sub-resources (e.g. `custom_field_definition` shared across multiple parent contexts), `inherits_from` and the scoped permission selector compose orthogonally: scoped permissions choose **which** profile applies; `inherits_from` declares **which records** that profile filters to. A scoped permission `project.task` can declare `inherits_from: project` and the tenant cascade still works — the chain extends through `project` to `organization`.
+
+## Order of evaluation
+
+For `policy.show?(record)`:
+
+1. **Role CRUD list** — does the role include `:show`?
+2. **Inheritance check (the new step)** — for each declared parent:
+   1. Is the parent record in `parent.policy_scope(user)`? (query layer)
+   2. Does `parent.policy.show?(parent_record)` pass? (record-rules layer)
+3. **Local `record_rules`** — does any rule deny `:show` for this record?
+
+All three layers must pass. There is no escape hatch — a parent denying via `record_rule` cannot be overridden by a child. The child can only be **stricter** than its parent.
+
+For `policy_scope.find(id)`:
+
+1. The base scope is `Model.where(<fk> IN parent.policy_scope(user).select(:id))`.
+2. `.find(id)` returns 404 (`ActiveRecord::RecordNotFound`) if the id is outside the scope.
+3. After load, the controller's `authorize @record` runs the `show?` check above for redundant safety.
+
+## Create-time parent validation
+
+Read paths (`index`, `show`, `edit`, `destroy`) cascade through the parent's policy scope as described above. The `:create` action is a special case — the child record does not yet exist, so the cascade has no parent association to traverse. Without extra protection, a user with `crud: [create]` on `grade` and **no visibility** on `student #999` could submit `student_id: 999` and successfully create a grade pointing at a hidden student. This is the [design's documented attack vector](../design/hierarchical_record_permissions.md#closing-the-id-guess-gap) for the create path.
+
+To close the gap, the platform auto-wires `LcpRuby::Authorization::InheritedParentValidator` onto every dynamic AR model whose YAML/DSL permission declares `inherits_from:`. The validator runs on `save` (both create and update) and rejects records whose declared FK does not resolve to a record visible under the parent's `policy_scope(LcpRuby::Current.user)`.
+
+**You don't have to write anything.** Declaring `inherits_from: student` on `grade.yml` wires the validator. Saving a grade with an out-of-scope `student_id` adds an error like `"Student is not accessible to the current user"` and `record.save` returns `false`.
+
+**When it fires.** Whenever `LcpRuby::Current.user` is set during save:
+
+| Save path | `Current.user` set by | Validator runs? |
+|---|---|---|
+| Standard CRUD controller (`POST /grades`, `PATCH /grades/:id`) | `Authentication` concern's `before_action` | Yes |
+| Bearer-token API endpoint | `BearerAuthentication` `prepend_before_action` | Yes |
+| `LcpRuby::ImportJobHandler` | `setup_context!` per `import/import_job_handler.rb` | Yes |
+| `LcpRuby::BatchActionHandler` | `load_user` per `batch_actions/batch_action_handler.rb` | Yes |
+
+**When it skips silently.** When `LcpRuby::Current.user` is `nil`:
+
+| Context | Behavior |
+|---|---|
+| `db/seeds.rb` | Skip (system context) |
+| Rake task without explicit user setup | Skip |
+| `bin/rails console` | Skip |
+| Generic `ExecutorJob` without handler-specific user setup | Skip |
+
+This matches the platform-wide convention that authorization checks no-op without a current user — seeds are not adversarial, and the platform doesn't know who "should" own seeded data.
+
+**Bypass paths — not enforced.** The validator runs through ActiveRecord's `validates_with` machinery, which is bypassed by Rails' raw-SQL save methods:
+
+| Path | Bypassed? | Mitigation |
+|---|---|---|
+| `Grade.create!(...)` | No | — |
+| `grade.update!(...)` | No | — |
+| `grade.update_columns(student_id: 999)` | **Yes** | Avoid in app code; documented gap |
+| `Grade.update_all(student_id: 999)` | **Yes** | Avoid in app code; documented gap |
+| `Grade.insert_all([...])` | **Yes** | Run `valid?` manually before insert |
+| `Grade.upsert_all([...])` | **Yes** | Run `valid?` manually before upsert |
+
+This is the intended Rails behavior — `update_columns` is documented as "skips validations and callbacks." The platform does not monkey-patch raw-SQL paths. Configurators who need bullet-proof enforcement at all paths must use the controller stack (which goes through `update!` and Pundit).
+
+**Surprise during admin imports.** Because `LcpRuby::ImportJobHandler` does set `LcpRuby::Current.user`, bulk imports from an admin who lacks visibility into specific parent records will **fail validation row-by-row**. This is correct security behavior but can surprise operators expecting "admin imports bypass row-level rules." A model-level opt-out (`bypass_inherited_parent_validation_for: [:import]`) is tracked as an Open Question in the design doc.
+
+**Real user, not impersonated user.** Model-level validators run far below the controller's impersonation layer. The validator reads `LcpRuby::Current.user` (the real user); impersonation operates at the controller via `effective_user`. This is a deliberate gap — impersonation is admin-only and admins typically have `scope: all` on parents, so the gap is benign in practice.
+
+### bind_to host AR models
+
+When LCP wraps an existing host AR class via `bind_to: "::Article"` and the corresponding permission declares `inherits_from:`, the platform auto-wires `InheritedParentValidator` on the host class — same contract as for dynamic models. Configurators don't have to remember a manual `validates_with` step in the host AR class.
+
+Smart-auto path (no extra YAML needed):
+
+```yaml
+# config/lcp_ruby/models/article.yml
+model:
+  name: article
+  bind_to: "::Article"
+
+# config/lcp_ruby/permissions/article.yml
+permissions:
+  model: article
+  inherits_from: author      # smart-auto wires the validator on ::Article
+  roles:
+    contributor: { crud: [index, show, create, update] }
+```
+
+If the permission is DB-backed (`permission_source: :model`) and not visible at boot, opt in explicitly via `bind_to_apply: [inherited_parent_validator]`:
+
+```yaml
+model:
+  name: incident
+  bind_to: "::Incident"
+  bind_to_apply: [inherited_parent_validator]
+```
+
+The runtime validator then resolves the live permission through `Permissions::SourceResolver` and short-circuits if no `inherits_from` is currently declared.
+
+**Boot-time validation for bind_to.** `ConfigurationValidator` introspects the host class's `belongs_to` reflections (not the YAML-declared associations, which are typically empty for bind_to models) when checking that the declared `inherits_from` parent has a corresponding belongs_to. If the host class isn't autoloaded yet at validate time (rare; happens when `lcp_ruby:validate` runs before full Rails boot), the boot-time check is skipped with a warning — the runtime validator still enforces parent visibility.
+
+**Limitation: multiple LCP models pointing at one host AR class.** The validator derives the model name from `record.class.name.demodulize.underscore`, which resolves to a single permission key. If two LCP models bind to the same host class with different LCP names, only one permission's `inherits_from` is honored. This is a pre-existing bind_to limitation; consolidate to one LCP model name per host class.
+
+## Soft-delete interaction
+
+`inherits_from` does **not** automatically hide children of soft-deleted parents at the cascade layer. The platform's soft-delete feature layers `kept` / `discarded` scopes at the **controller** layer (`apply_soft_delete_scope` in `crud_helpers.rb`) — NOT inside the base `policy_scope`. So `Authorization::Cache.parent_policy_scope` returns all parents the user can see by role-scope, including discarded ones, and the cascade permits their children.
+
+**To opt in to "hide children of discarded parents"**, add `discarded_at: nil` to the parent role's scope explicitly:
+
+```yaml
+# permissions/school_class.yml
+roles:
+  teacher:
+    crud: [index, show, update]
+    scope:
+      type: where
+      conditions:
+        teacher_id: { current_user: id }
+        discarded_at: null    # explicit kept-only
+```
+
+The cascade now picks up the kept-only filter because it composes through `parent_policy_scope`.
+
+This is consistent with how soft-delete works elsewhere — the controller decides whether to show discarded records (e.g. trash views set `presenter.scope = "discarded"`). At the inheritance layer there is no controller intent to consult, so the conservative default is "include all parents the role can see by role-scope; let the configurator opt in to soft-delete filtering."
+
+## Constraints on parent scopes
+
+The cascade compiles to `WHERE child.fk IN (SELECT id FROM <parent_scope>)`. The sub-query reads the parent's `policy_scope.select(:id)`, which works **only** when the parent's resolved scope reduces to a plain `WHERE` chain over a single table. If the parent's scope uses any of the constructs below, the `select(:id)` rewrite produces invalid SQL or silently incorrect results across databases:
+
+- `.distinct` — the wrapper sub-query loses the `DISTINCT` qualifier; counts and joins downstream may double up.
+- `.group(...)` / `.having(...)` — `select(:id)` doesn't compose with grouping.
+- `eager_load(...)` with table aliases — the `:id` column becomes ambiguous when multiple tables expose `id`.
+- Custom `select(:something_other_than_id)` — `select(:id)` overrides; the sub-query no longer matches the configurator's intent.
+- Database-specific constructs (e.g. `FOR UPDATE`, materialized CTEs) — sub-query position rejects most of them.
+
+**Rule:** parent permissions used as `inherits_from` targets must keep their `scope:` reducible to a `WHERE` chain. The shipped scope types (`field_match`, `association`, `where`, `custom`) all do. Custom Ruby scopes referenced via `type: custom, method: :foo` fall under your control — keep them simple.
+
+If your parent visibility legitimately needs `.distinct` or aggregation, lift it into a denormalized column on the child (e.g. `grade.school_id`) and scope the child directly via `field_match` / `association`, bypassing inheritance for that hop.
+
+## Performance
+
+- **Per-request memoization** of `parent_policy_scope`. The `Authorization::Cache` (backed by `LcpRuby::Current`, auto-reset by Rails per request) memoizes the resolved parent **Relation** per `(parent_name, user.id)`. A 4-deep transitive chain across 25 sibling records resolves the chain four times per request, not 4×25 times.
+
+- **What the cache does NOT memoize: per-record `exists?` results.** The cascade's create-time validator calls `parent_scope.exists?(id: fk)` for each saved record. The cache holds the *Relation* (so the SQL is built once) but each `exists?` call still issues one `SELECT 1 FROM parent WHERE ... AND id = ? LIMIT 1` query.
+
+  Two regimes to be aware of:
+
+  | Workload shape | Per-save cost | Notes |
+  |---|---|---|
+  | **Many children, same parent** (e.g. 1000 grades for one student) | 1 Relation build + 1000 cheap `exists?` queries | Each `exists?` is a fast index lookup on `parent.id`; total cost is dominated by AR overhead, not SQL. |
+  | **Many children, distinct parents** (e.g. bulk-import 1000 grades each pointing at a different student) | 1 Relation build + 1000 distinct `exists?` queries | The query plan is identical, but you actually hit 1000 different parent rows. Same result; slightly more cache miss in the DB. |
+
+  **If the import is hot enough to matter:** pre-fetch all parent IDs once (`accessible_ids = parent_scope.pluck(:id).to_set`), set `LcpRuby::Current.user = nil` for the duration of the import, and check membership in app code (`raise unless accessible_ids.include?(parent_id)`). Trade-off: loads the full parent ID set into memory; only worth it for tight loops where 1000 SQL round-trips show up in profiles.
+
+- **Sub-query SQL shape.** `inherits_from` generates `WHERE child.fk IN (SELECT id FROM parent ...)`. PostgreSQL optimizes this well; SQLite is weaker for deep chains. If profiling shows a hot path, denormalize the root id (the same pattern recommended in the [hierarchical-authorization guide](hierarchical-authorization.md)) — `inherits_from` does not preclude denormalization, it just removes the **need** for it.
+
+- **Eager loading.** `policy_scope` automatically chains `.includes(...)` along the `inherits_from` chain — a 3-tier `grade → student → school_class` cascade auto-preloads as `.includes(student: :school_class)`. Index pages, exports, batch actions, and dashboard widgets all benefit without per-controller wiring. The hint is purely additive: caller-side `.includes(...)` (e.g. presenter-driven preloads in `IncludesResolver`) compose into one consolidated load. See `lib/lcp_ruby/authorization/includes_hint.rb` for the implementation.
+
+## Related
+
+- [Permissions Reference — `inherits_from`](../reference/permissions.md#inherits_from)
+- [Hierarchical Authorization Guide](hierarchical-authorization.md) — the path-based pattern this complements
+- [Design: Hierarchical Record Permissions](../design/hierarchical_record_permissions.md) — full design rationale, edge cases, decisions
+- [Design: Unified Permission Scopes](../design/unified_permission_scopes.md) — the broader scope-syntax refactor that subsumes path-based scope (out of this proposal)
+