lcp 0.1.0

data/docs/reference/virtual_forms.md

@@ -0,0 +1,196 @@
+# Virtual Forms
+
+Shared infrastructure for synthetic, per-request form-like objects. The
+platform uses this to render forms that aren't backed by an
+ActiveRecord row — currently page filter forms (PR 5), with hooks for
+future consumers: multi-step wizards, virtual show pages, PaaS config
+UI, custom-field designer.
+
+> **Status:** infrastructure landed in PR 4, first consumer
+> (`LcpRuby::Pages::FilterForm`) lands in PR 5.
+> Spec: [docs/design/page_filters_as_virtual_forms.md](../design/page_filters_as_virtual_forms.md).
+
+## Quick map
+
+| Class | Purpose | File |
+|---|---|---|
+| `LcpRuby::VirtualFields::VirtualField` | Field-shaped object backing one input on a VirtualForm | `lib/lcp_ruby/virtual_fields/virtual_field.rb` |
+| `LcpRuby::VirtualFields::VirtualForm` | Builds an anonymous AM::API class per request, declares attributes, whitelists params | `lib/lcp_ruby/virtual_fields/virtual_form.rb` |
+| `LcpRuby::VirtualFields::Types::ArrayOf` | AM::Attributes type for `multi:` fields. Defensive: never `Array(value)` | `lib/lcp_ruby/virtual_fields/types/array_of.rb` |
+| `LcpRuby::VirtualFields::SyntheticMarker` | Marker module included on every synthetic class — enables GC lifecycle test | `lib/lcp_ruby/virtual_fields/synthetic_marker.rb` |
+
+## How it works
+
+```
+your code
+    │
+    ▼
+VirtualForm.new(name:, fields:, target_model:, context: { params:, current_user: })
+    │
+    ▼  (lazy on first to_model call)
+build_synthetic_class:
+    Class.new {
+      include ActiveModel::API
+      include ActiveModel::Attributes
+      include SyntheticMarker          ← marker, no methods
+    }.tap { |klass|
+      fields.each { |vf|
+        # One VirtualField can declare ONE OR MORE synthetic attributes.
+        # Scalar fields (text, select, …) yield [name]. Range fields
+        # (date_range) yield [name+"_from", name+"_to"]. See § Range
+        # decomposition below.
+        vf.attribute_names.each { |attr_name|
+          klass.attribute(attr_name, vf.attribute_type(attr_name), default: vf.default)
+        }
+      }
+    }
+    │
+    ▼
+klass.new(**whitelist_and_coerce(params))
+    │
+    ▼
+form_with(model: virtual_form.to_model, scope: :page_filter, method: :get) do |f|
+  render_form_input(f, vfield.name, vfield.input_type, field_config, vfield)
+```
+
+The synthetic class is anonymous. Once the `VirtualForm` and its
+`to_model` instance go out of scope at the end of the response, the
+class is reclaimed — DescendantsTracker uses `ObjectSpace::WeakMap` on
+MRI, so it does not retain.
+
+## Security invariants
+
+The defensive shape is non-negotiable — adding shortcuts here is how
+filter forms leak data.
+
+1. **Attribute names come from the boot-validated field list, never
+   from URL keys.** `VirtualForm` iterates `@fields` and calls
+   `klass.attribute(name, type)`. URL params are *values* assigned to
+   declared attributes, never the source of attribute names.
+   Pinned by spec acceptance test #17.
+
+2. **Incoming params are whitelisted against
+   `fields.map(&:name).to_set`** before assignment. `__send__`,
+   `unknown`, and any attacker-supplied key is dropped silently.
+
+3. **`Type::ArrayOf#cast` rejects non-Array, non-scalar inputs.**
+   `Array(value)` is forbidden — `Array({"admin"=>"1"})` returns
+   `[["admin","1"]]` and would propagate attacker keys. The cast
+   method branches on `value.is_a?(Array)` explicitly; `Hash`,
+   `ActionController::Parameters`, and other non-scalar types coerce
+   to `[]`. Pinned by spec acceptance test #16.
+
+4. **`Hash` / `Parameters` values for plain attributes coerce to
+   `nil`** (not `Array(value)`). Same defensive posture as `ArrayOf`
+   applied to scalar attributes.
+
+5. **`AM::Validations` is included transitively via `AM::API`.** This
+   was a concern in earlier spec drafts (DescendantsTracker
+   retention), but modern Rails (8.x) uses `ObjectSpace::WeakMap` so
+   synthetic classes are GC'd cleanly. Pinned by spec acceptance
+   test #10.
+
+## Range decomposition
+
+A single VirtualField can back **more than one** AM::Attributes
+attribute. The canonical case is `date_range`: the configurator writes
+one filter entry, but the form emits two paired date inputs and the
+URL carries two paired keys.
+
+```ruby
+class LcpRuby::VirtualFields::VirtualField
+  def attribute_names
+    case @input_type
+    when "date_range" then [ "#{@name}_from", "#{@name}_to" ]
+    else                  [ @name ]
+    end
+  end
+
+  def attribute_type(_attr_name = nil)
+    case @input_type
+    when "date_range" then ActiveModel::Type.lookup(:date)
+    else                  @am_type
+    end
+  end
+end
+```
+
+Why the decomposition lives on `VirtualField` and not on `VirtualForm`:
+
+- `each_field` still yields ONE entry per configurator field, so the
+  partial renders `render_date_range` once (with its `<fieldset>`
+  affordance) rather than two unrelated date inputs.
+- URL keys are independent (`hired_at_from`, `hired_at_to`) so the
+  param whitelist + Rails strong-params machinery treats them as
+  ordinary scalar attributes — no special-cased nested Hash.
+- `ScopeApplicator.resolve_filter_value` composes the two attributes
+  back into a Hash at apply time — see
+  [Page Filters § Date range](page_filters.md#date-range-input_type-date_range).
+
+Future range inputs (`numeric_range`, time-of-day, …) follow the same
+shape: extend the `case` in `attribute_names` and `attribute_type`,
+add a renderer in `form_helper.rb`, and `ScopeApplicator.resolve_filter_value`'s
+existing branch handles the rest.
+
+## Type coercion behaviour
+
+`VirtualForm#whitelist_and_coerce` slices URL params against
+`fields.flat_map(&:attribute_names)` and then casts each value through
+the declared AM type. Upstream Rails has quirks worth knowing — see
+[Page Filters § Type coercion edge cases](page_filters.md#type-coercion-edge-cases--what-bad-url-params-actually-filter)
+for the full table (Integer `"abc" → 0`, Boolean `"maybe" → true`,
+etc.). The contract here is just **never raises** — bad input either
+casts to a safe value or to `nil`, and `ScopeApplicator.blank_filter_value?`
+treats `nil` / empty as "no filter".
+
+## The dispatcher contract
+
+`render_form_input` (and its sub-renderers) reads exactly five methods
+on `field_def`:
+
+| Method | Used by |
+|---|---|
+| `#type == "json"` | text-area JSON pretty-printing branch |
+| `#enum?` | select / radio / json-field input |
+| `#enum_value_names` | same |
+| `#enum_label_for(value, model_name:)` | same |
+| `#attachment_options` | file-upload input (boot-rejected for filter forms in v1) |
+
+`VirtualField` implements all five (stubs for enum / attachment since
+filter forms don't use those branches — values flow through
+`field_config["select_options"]` instead, populated by the consumer's
+`field_config_for` method). Future consumers can override these stubs
+if they need richer behavior.
+
+## Subclassing for a new feature
+
+`Pages::FilterForm < VirtualForm` is the worked example. To add a new
+consumer:
+
+```ruby
+class MyWizard::Step1Form < LcpRuby::VirtualFields::VirtualForm
+  def initialize(user:, params:)
+    fields = [
+      LcpRuby::VirtualFields::VirtualField.new(name: "email", input_type: "email"),
+      LcpRuby::VirtualFields::VirtualField.new(name: "role", input_type: "select",
+        input_options: { "values" => Role::OPTIONS })
+    ]
+    super(name: "step_1", fields: fields, context: { params: params, current_user: user })
+  end
+
+  # Optional: enrich field_config for form_helper
+  def field_config_for(name)
+    vf = field(name)
+    { "field" => vf.name, "input_options" => vf.input_options,
+      "select_options" => vf.input_options["values"]&.map { |k, v| [v, k] } }
+  end
+end
+```
+
+## Garbage collection (acceptance test #10)
+
+`spec/lib/lcp_ruby/virtual_fields/lifecycle_spec.rb` allocates 1000
+VirtualForms, forces GC, and asserts the surviving SyntheticMarker
+class count stays bounded. If you see flakes in CI, the test message
+points at the mitigation (raise the bound or switch to a `WeakRef`
+check).

data/docs/reference/workflow-approvals.md

@@ -0,0 +1,387 @@
+# Workflow Approvals Reference
+
+The approval engine extends the workflow state machine with multi-step approval processes. It connects through three existing mechanisms: `on_entry` events (activation), `on_exit` events (cleanup), and system triggers (resolution transitions).
+
+## Prerequisites
+
+Generate the approval model tables:
+
+```bash
+rails generate lcp_ruby:workflow_approvals
+```
+
+This creates three models: `workflow_approval_request`, `workflow_approval_step`, and `workflow_approval_task` with their presenters and permissions.
+
+## YAML Configuration
+
+The `approvals` section lives inside a workflow definition, keyed by the state that triggers the approval:
+
+```yaml
+workflow:
+  name: purchase_order_workflow
+  model: purchase_order
+  field: status
+
+  states:
+    draft:
+      initial: true
+    pending_approval:
+      category: active
+    approved:
+      category: terminal
+    rejected:
+      category: terminal
+
+  transitions:
+    submit:
+      from: draft
+      to: pending_approval
+      roles: [author, admin]
+    approve_transition:
+      from: pending_approval
+      to: approved
+      trigger: system
+    reject_transition:
+      from: pending_approval
+      to: rejected
+      trigger: system
+    return_transition:
+      from: pending_approval
+      to: draft
+      trigger: system
+
+  approvals:
+    pending_approval:
+      strategy: sequential          # sequential | parallel
+      resolution:
+        approved: approve_transition   # required
+        rejected: reject_transition    # optional
+        returned: return_transition    # optional
+      bypass_when:                     # optional condition
+        field: amount
+        operator: lte
+        value: 1000
+      on_reject: any                   # any | all
+      short_circuit: true              # cancel remaining on resolution
+      rework_policy:
+        reset: true                    # restart from step 1 on resubmit
+      require_reject_comment: true
+      allow_approve_with_comment: true
+      allow_delegation: true
+      delegation_roles: [admin, manager]
+      max_delegation_depth: 2
+      steps:
+        - name: manager_review
+          label: "Manager Review"
+          approvers:
+            type: field
+            field: manager_id
+          required: 1
+          assignment: all
+        - name: director_review
+          label: "Director Review"
+          approvers:
+            type: role
+            role: director
+          required: 1
+          condition:
+            field: amount
+            operator: gt
+            value: 10000
+```
+
+## Approval Definition Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `strategy` | string | `sequential` | `sequential` (steps run in order) or `parallel` (all steps active at once) |
+| `resolution` | hash | — | Maps outcomes to transition names. `approved` is required |
+| `bypass_when` | condition | — | If true, approval is auto-approved immediately |
+| `on_reject` | string | `any` | `any`: one rejection resolves. `all`: all must reject |
+| `short_circuit` | boolean | `true` | Cancel remaining steps/tasks when outcome is determined |
+| `rework_policy` | hash | — | `reset: "all"` (or `true`) restarts from step 1; `"pending_only"` resets only pending steps; `"none"` (or `false`) resumes |
+| `require_reject_comment` | boolean | `false` | Require a comment when rejecting |
+| `allow_approve_with_comment` | boolean | `true` | Allow optional comment on approve |
+| `allow_delegation` | boolean | `false` | Enable task delegation |
+| `delegation_roles` | array | `[]` | Restrict delegation to these roles |
+| `max_delegation_depth` | integer | `1` | Maximum delegation chain length |
+
+## Step Definition Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `name` | string | — | Unique step identifier (required) |
+| `label` | string | name | Display label |
+| `approvers` | hash | — | Approver source configuration (required) |
+| `required` | integer | `1` | Number of approvals needed to complete the step |
+| `assignment` | string | `all` | `all`: everyone can decide. `claim`: one person claims the task. `single`: auto-assigned to one |
+| `condition` | condition | — | Step is skipped if condition evaluates to false |
+| `fallback` | hash | — | Fallback approver source if primary returns empty |
+
+## Approver Types
+
+### role
+Query users by their role attribute:
+```yaml
+approvers:
+  type: role
+  role: manager
+```
+
+### field
+Read approver user ID from a record field:
+```yaml
+approvers:
+  type: field
+  field: manager_id
+```
+
+### group
+Use group membership to find approvers:
+```yaml
+approvers:
+  type: group
+  group: finance_team
+```
+
+### hierarchy
+Use a configured hierarchy resolver:
+```yaml
+approvers:
+  type: hierarchy
+  levels_up: 1
+```
+Requires `LcpRuby.configure { |c| c.hierarchy_resolver = MyResolver.new }`.
+
+### service
+Call a custom service class:
+```yaml
+approvers:
+  type: service
+  service: ApproverServices::RegionalManager
+```
+The service must implement `.call(record:, current_user:)` returning an array of user IDs.
+
+## DSL Configuration
+
+```ruby
+LcpRuby.define_workflow(:purchase_order_workflow) do
+  model :purchase_order
+  field :status
+
+  state :draft, initial: true
+  state :pending_approval
+  state :approved, category: :terminal
+
+  transition :submit, from: :draft, to: :pending_approval
+  transition :approve_transition, from: :pending_approval, to: :approved, trigger: :system
+
+  approval(:pending_approval) do
+    strategy :sequential
+    resolution approved: "approve_transition"
+    bypass_when field: "amount", operator: "lte", value: 1000
+
+    step :manager_review, label: "Manager Review" do
+      approvers type: "field", field: "manager_id"
+      required 1
+    end
+
+    step :director_review, label: "Director Review" do
+      approvers type: "role", role: "director"
+      required 1
+      condition field: "amount", operator: "gt", value: 10000
+    end
+  end
+end
+```
+
+## Task Actions
+
+Programmatic task operations via `TaskManager`:
+
+```ruby
+# Approve a task
+Workflow::Approval::TaskManager.approve_task(task, user: current_user, comment: "Looks good")
+
+# Reject a task (comment required if configured)
+Workflow::Approval::TaskManager.reject_task(task, user: current_user, comment: "Budget exceeded")
+
+# Return for rework
+Workflow::Approval::TaskManager.return_task(task, user: current_user, comment: "Fix description")
+
+# Claim a task (assignment: claim mode)
+Workflow::Approval::TaskManager.claim_task(task, user: current_user)
+
+# Delegate to another user
+Workflow::Approval::TaskManager.delegate_task(task, user: current_user, delegate_to_user_id: other_user.id)
+```
+
+## Convenience Methods
+
+Records with workflows gain these methods:
+
+```ruby
+record.active_approval_request    # Current pending ApprovalRequest or nil
+record.approval_tasks_for_user(user)  # Pending/claimed tasks for this user
+```
+
+## Configuration
+
+```ruby
+LcpRuby.configure do |c|
+  # Model names (defaults match generator output)
+  c.approval_request_model = "workflow_approval_request"
+  c.approval_step_model = "workflow_approval_step"
+  c.approval_task_model = "workflow_approval_task"
+
+  # Optional: hierarchy resolver for hierarchy-type approvers
+  c.hierarchy_resolver = MyHierarchyResolver.new
+end
+```
+
+## Three Definition Sources
+
+Approval definitions live inside workflow definitions (the `approvals:` section). They travel with the workflow through all three sources automatically:
+
+- **Static (YAML/DSL):** Parsed via `WorkflowDefinition.from_hash`
+- **Model (DB):** Include `approvals` JSON column in the workflow model
+- **Host:** Host adapter returns full workflow hashes including approvals
+
+## Request Lifecycle
+
+```
+1. Record transitions to approval state (on_entry fires)
+2. Engine.activate evaluates bypass_when
+   → If bypass: auto-approve, fire resolution transition
+   → If not: create ApprovalRequest + ApprovalSteps + ApprovalTasks
+3. Approvers review and decide (approve/reject/return/delegate)
+4. StepEvaluator checks step completion after each decision
+5. For sequential: advance to next step. For parallel: check all steps.
+6. ResolutionHandler fires the resolution transition via TransitionExecutor
+7. Record transitions to final state (approved/rejected/draft)
+```
+
+## UI Layer
+
+### Approval Status Widget
+
+The `approval_status` widget displays approval progress on a record's show page. It can be used in two ways:
+
+**Automatic (view slot):** When the approval engine is configured, a view slot is automatically registered on all show pages. It renders below the record's sections whenever the record has an active approval request — no configuration needed.
+
+**Explicit (widget zone):** Add an `approval_status` widget zone to a composite page for explicit placement:
+
+```yaml
+page:
+  name: order_detail
+  zones:
+    - name: approval
+      type: widget
+      area: below
+      widget:
+        type: approval_status
+```
+
+The widget shows:
+- Step progress indicator (completed / total)
+- Step list with status badges
+- Task details per step (approver name from snapshot, status, comment, date)
+- Action buttons for the current user's pending/claimed tasks
+
+### Routes
+
+Five POST routes handle approval task actions:
+
+```
+POST /:lcp_slug/:id/approval_tasks/:task_id/approve      → approve task
+POST /:lcp_slug/:id/approval_tasks/:task_id/reject        → reject task
+POST /:lcp_slug/:id/approval_tasks/:task_id/return_task   → return for rework
+POST /:lcp_slug/:id/approval_tasks/:task_id/claim         → claim task
+POST /:lcp_slug/:id/approval_tasks/:task_id/delegate      → delegate task
+```
+
+Authorization: requires `show` permission on the record. Task-level authorization (correct user, correct status, delegation rules) is enforced by `TaskManager`.
+
+### Path Helper
+
+```ruby
+approval_task_action_path(record, task, :approve)
+approval_task_action_path(record, task, :reject)
+approval_task_action_path(record, task, :return_task)
+approval_task_action_path(record, task, :claim)
+approval_task_action_path(record, task, :delegate)
+```
+
+### DataBuilder
+
+`Workflow::Approval::DataBuilder.build(record:, user:)` returns a hash used by both the widget and the view slot:
+
+```ruby
+{
+  request:,              # Active ApprovalRequest record
+  steps:,                # Ordered ApprovalStep records
+  steps_by_id:,          # Hash { step_id => step } for O(1) lookup
+  tasks_by_step:,        # Hash { step_id => [tasks] }
+  user_tasks:,           # Pending/claimed tasks for the given user in active steps
+  approval_definition:,  # ApprovalDefinition from workflow metadata
+  delegation_allowed:,   # Boolean
+  record:                # The business record
+}
+```
+
+Returns `nil` if the approval registry is not available or the record has no active approval request.
+
+## Error Classes
+
+| Class | Parent | Description |
+|-------|--------|-------------|
+| `ApprovalError` | `WorkflowError` | Base approval error |
+| `TaskActionError` | `ApprovalError` | Invalid task action (wrong status, wrong user) |
+| `DelegationError` | `ApprovalError` | Delegation not allowed or depth exceeded |
+| `ApproverResolutionError` | `ApprovalError` | Cannot resolve approvers |
+
+Source: `lib/lcp_ruby/workflow/approval/`
+
+### Localized error messages
+
+`WorkflowError`, `TaskActionError`, `DelegationError`, and any subclass of `LcpRuby::Error` support an i18n-aware constructor. When the raise site passes an i18n key (a symbol, or a string starting with `lcp_ruby.`), the exception carries both the English text (for logs and stack traces under `:en`) and the translation metadata (resolved at the catch site under `I18n.locale`):
+
+```ruby
+# Raise site — task_manager.rb
+raise Workflow::TaskActionError.new(
+  "lcp_ruby.workflow.errors.task.not_pending",
+  status: task.status
+)
+
+# Catch site — approval_tasks_controller.rb
+rescue_from Workflow::TaskActionError, Workflow::DelegationError do |e|
+  redirect_to resource_path(@record), alert: e.localized_message
+end
+```
+
+`#message` returns the English template (operator-friendly in Rails logs); `#localized_message` resolves the i18n key under the current `I18n.locale` with the stored interpolations, falling back to `#message` if no key is set. Flash messages and JSON error bodies should call `#localized_message`; log lines and re-raised exceptions should stick with `#message`.
+
+Engine-raised approval errors already use this pattern. When adding a new error class in a host-app workflow provider, inherit from `LcpRuby::Error` (or a subclass) to get the `i18n_key` / `localized_message` API for free.
+
+Shipped i18n keys for the errors above (override in host locale files to translate):
+
+```yaml
+lcp_ruby:
+  workflow:
+    errors:
+      registry_unavailable: "Workflow registry is not available"
+      task:
+        comment_not_allowed: "Comments are not allowed on approve actions for this approval"
+        comment_required: "A comment is required when rejecting"
+        not_pending: "Task is not in pending status (current: %{status})"
+        not_claim_mode: "Task assignment mode is not 'claim' (current: %{assignment})"
+        not_assigned_to_user: "Task is not assigned to this user"
+        not_actionable: "Task is not actionable (current status: %{status})"
+      delegation:
+        not_allowed: "Delegation is not allowed for this approval"
+        max_depth: "Maximum delegation depth (%{depth}) exceeded"
+        user_not_found: "Delegate user not found"
+        role_denied: "User does not have a permitted delegation role"
+```
+
+See the [i18n reference](i18n.md#contributing-new-strings) for the full `LcpRuby::Error` contract.