lcp 0.1.0

data/docs/reference/workflow.md

@@ -0,0 +1,651 @@
+# Workflow Reference
+
+Workflows add a behavioral state machine layer on top of model enum fields. They enforce allowed transitions, guard conditions, role restrictions, auto-set fields, fire events, and log every state change in a dedicated audit table.
+
+When a workflow is active on a model, direct enum updates are blocked — the record can only change state through defined transitions.
+
+## Prerequisites
+
+### Required Model Fields
+
+Every model bound to a workflow **must** have an integer `workflow_version` field. The engine emits a validator warning at boot if it is missing, and runtime transitions cannot snapshot which workflow version was active when the record was created without it (audit log linking breaks).
+
+DSL:
+
+```ruby
+# config/lcp_ruby/models/incident.rb
+model :incident do
+  field :workflow_version, :integer
+  # ... other fields
+end
+```
+
+YAML:
+
+```yaml
+# config/lcp_ruby/models/incident.yml
+model:
+  name: incident
+  fields:
+    - name: workflow_version
+      type: integer
+```
+
+The value is set automatically when the record is created and never modified afterward — it lets the audit log replay the historical workflow definition even after the workflow YAML is edited. See the [audit log schema](#audit-log-model-contract) for how it links rows.
+
+### Workflow Audit Log Model
+
+Generate the workflow audit log model (required if any workflow has `audit_log: true`):
+
+```bash
+rails generate lcp_ruby:workflow_audit_log
+```
+
+This creates a model, presenter, and permissions for the audit log table.
+
+## Workflow File
+
+Workflow definitions live in `config/lcp_ruby/workflows/` as `.yml` or `.rb` files. Each file defines one workflow.
+
+### YAML Format
+
+```yaml
+# config/lcp_ruby/workflows/purchase_order.yml
+workflow:
+  name: purchase_order_workflow
+  model: purchase_order
+  field: status
+  version: 1
+  audit_log: true
+
+  states:
+    draft:
+      initial: true
+      category: draft
+      color: gray
+      icon: file-text
+
+    pending_approval:
+      category: waiting
+      color: blue
+      icon: clock
+      readonly_fields: [title, total_amount, department_id]
+      on_entry: [notify_approvers]
+      on_exit: [log_approval_exit]
+
+    approved:
+      category: terminal
+      color: green
+      icon: check-circle
+      readonly_fields: all
+
+    rejected:
+      category: rejected
+      color: red
+      icon: x-circle
+
+  transitions:
+    submit:
+      from: draft
+      to: pending_approval
+      label: "Submit for Approval"
+      icon: send
+      style: primary
+      roles: [author, admin]
+      guard:
+        all:
+          - { field: title, operator: present }
+          - { field: total_amount, operator: gt, value: 0 }
+      set_fields:
+        submitted_at: current_datetime
+        submitted_by: current_user.id
+      events: [po_submitted]
+      confirm: true
+      confirm_message: "Submit this PO for approval?"
+
+    approve:
+      from: pending_approval
+      to: approved
+      roles: [admin]
+      trigger: system
+      set_fields:
+        approved_at: current_datetime
+
+    reject:
+      from: pending_approval
+      to: rejected
+      roles: [admin]
+      trigger: system
+      require_comment: true
+      set_fields:
+        rejected_at: current_datetime
+
+    rework:
+      from: [rejected, pending_approval]
+      to: draft
+      label: "Return to Draft"
+      icon: rotate-ccw
+      roles: [author, admin]
+
+    force_approve:
+      from: pending_approval
+      to: approved
+      label: "Force Approve"
+      icon: shield
+      roles: [admin]
+      require_comment: true
+```
+
+### DSL Format
+
+```ruby
+# config/lcp_ruby/workflows/purchase_order.rb
+define_workflow :purchase_order_workflow do
+  model :purchase_order
+  field :status
+  version 1
+  audit_log true
+
+  state :draft, initial: true, category: :draft, color: "gray", icon: "file-text"
+  state :pending_approval, category: :waiting, color: "blue", icon: "clock",
+    readonly_fields: [:title, :total_amount, :department_id],
+    on_entry: [:notify_approvers],
+    on_exit: [:log_approval_exit]
+  state :approved, category: :terminal, color: "green", icon: "check-circle",
+    readonly_fields: :all
+  state :rejected, category: :rejected, color: "red", icon: "x-circle"
+
+  transition :submit, from: :draft, to: :pending_approval,
+    label: "Submit for Approval", icon: "send", style: :primary,
+    roles: [:author, :admin], confirm: true do
+    guard all: [
+      { field: :title, operator: :present },
+      { field: :total_amount, operator: :gt, value: 0 }
+    ]
+    set_fields submitted_at: :now, submitted_by: "current_user.id"
+    fire_events :po_submitted
+  end
+
+  transition :approve, from: :pending_approval, to: :approved,
+    roles: [:admin], trigger: :system do
+    set_fields approved_at: :now
+  end
+
+  transition :reject, from: :pending_approval, to: :rejected,
+    roles: [:admin], trigger: :system, require_comment: true do
+    set_fields rejected_at: :now
+  end
+
+  transition :rework, from: [:rejected, :pending_approval], to: :draft,
+    label: "Return to Draft", icon: "rotate-ccw", roles: [:author, :admin]
+
+  transition :force_approve, from: :pending_approval, to: :approved,
+    label: "Force Approve", icon: "shield", roles: [:admin], require_comment: true
+end
+```
+
+## Workflow-Level Keys
+
+| Key | Type | Required | Default | Description |
+|-----|------|----------|---------|-------------|
+| `name` | String | yes | — | Unique workflow identifier |
+| `model` | String | yes | — | LCP model name this workflow governs. When no workflow is defined for an [STI child](models.md#single-table-inheritance-sti), the platform falls back to the parent model's workflow. |
+| `field` | String | yes | — | Enum field name used as the state machine |
+| `version` | Integer | no | `1` | Definition version. Records store this at creation time |
+| `audit_log` | Boolean | no | `true` | Log every transition to `workflow_audit_logs` table |
+| `timeline_states` | Array | no | — | Ordered list of state names for timeline renderer display. When omitted, all states except `category: rejected` are used. |
+
+### `timeline_states`
+
+An optional ordered list of state names that defines the "happy path" shown by the `workflow_timeline` renderer. This is a visualization-only key — it does not affect the state machine behavior.
+
+```yaml
+workflow:
+  name: candidate_workflow
+  model: candidate
+  field: status
+  timeline_states: [applied, screening, interviewing, offer, hired]
+
+  states:
+    applied: { initial: true }
+    screening: {}
+    interviewing: {}
+    offer: {}
+    hired: { category: terminal }
+    rejected: { category: rejected }  # excluded from timeline
+```
+
+```ruby
+# DSL equivalent:
+define_workflow :candidate_workflow do
+  model :candidate
+  field :status
+  timeline_states :applied, :screening, :interviewing, :offer, :hired
+
+  state :applied, initial: true
+  # ...
+end
+```
+
+When `timeline_states` is not set, the timeline renderer automatically uses all states except those with `category: rejected`.
+
+All referenced state names must exist in the `states` definition (validated at boot time).
+
+#### How `workflow_timeline` resolves the step list
+
+The renderer picks the first non-empty source from this order:
+
+1. **`options.states: [...]`** on the renderer call site — per-presenter override (e.g. show one happy path on the customer presenter, a different one on the recruiter presenter for the same workflow).
+2. **`timeline_states: [...]`** on the workflow definition — the canonical happy path shown above.
+3. **All states except `category: rejected`** — automatic fallback.
+
+Example of a per-presenter override:
+
+```yaml
+# in a presenter YAML
+fields:
+  - name: status
+    renderer: workflow_timeline
+    options:
+      states: [applied, screening, hired]   # condensed view for this screen
+```
+
+This is purely a display concern — it does **not** alter what transitions are allowed, what states exist, or how `workflow.timeline_states_for_display` evaluates elsewhere.
+
+## State Keys
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `initial` | Boolean | `false` | Exactly one state must be `initial: true` |
+| `category` | String | — | Semantic grouping: `draft`, `in_progress`, `waiting`, `approved`, `rejected`, `terminal` |
+| `color` | String | — | Badge/indicator color |
+| `icon` | String | — | Icon name |
+| `description` | String | — | Human-readable description |
+| `readonly_fields` | Array or `"all"` | `[]` | Fields locked while record is in this state. `"all"` locks every field |
+| `on_entry` | Array | `[]` | Event names fired when a record enters this state (any transition) |
+| `on_exit` | Array | `[]` | Event names fired when a record leaves this state (any transition) |
+
+### State Categories
+
+Categories are semantic labels for grouping and display. The engine treats `terminal` specially — terminal states have no outgoing transitions by default.
+
+| Category | Meaning |
+|----------|---------|
+| `draft` | Initial editable state |
+| `in_progress` | Work is happening |
+| `waiting` | Waiting for external action (e.g., approval) |
+| `approved` | Positively resolved |
+| `rejected` | Negatively resolved |
+| `terminal` | Process complete, no further transitions |
+
+### `readonly_fields`
+
+When set to an array, those specific fields become non-writable while the record is in this state. When set to `"all"` (YAML) or `:all` (DSL), all model fields are locked.
+
+Readonly enforcement:
+- **Controller**: `permitted_params` filters out readonly fields, preventing form submissions from changing them.
+- **Presenter**: Readonly fields render with disabled styling on edit forms.
+
+## Transition Keys
+
+| Key | Type | Required | Default | Description |
+|-----|------|----------|---------|-------------|
+| `from` | String or Array | yes | — | Source state(s) |
+| `to` | String | yes | — | Target state |
+| `label` | String | no | humanized name | Button label. i18n key: `lcp_ruby.workflows.<name>.transitions.<transition>` |
+| `icon` | String | no | — | Icon name for the button |
+| `style` | String | no | `"default"` | Button style: `default`, `primary`, `success`, `danger`, `warning` |
+| `roles` | Array | no | all roles | Roles allowed to trigger this transition |
+| `guard` | Hash | no | — | Condition that must be true. Uses `ConditionEvaluator` (all operators, compound syntax) |
+| `set_fields` | Hash | no | `{}` | Field values to auto-set on transition |
+| `events` | Array | no | `[]` | Named events fired after transition completes |
+| `require_comment` | Boolean | no | `false` | Mandatory comment input before transition. Stored only in `workflow_audit_log.comment` — see [Audit Log](#audit-log). |
+| `confirm` | Boolean | no | `false` | Show confirmation dialog before executing |
+| `confirm_message` | String | no | `"Are you sure?"` | Custom confirmation text |
+| `trigger` | String | no | `"user"` | `user` = UI button, `system` = programmatic only, `both` = both |
+
+### `trigger` Values
+
+| Value | UI Button | Programmatic | Use Case |
+|-------|-----------|-------------|----------|
+| `user` | Yes | Yes | Normal user-initiated transitions |
+| `system` | No | Yes | Transitions fired by approval engine or background jobs |
+| `both` | Yes | Yes | Available both ways |
+
+### `set_fields` Value Expressions
+
+Value expressions use the unified dotted-string grammar — see
+[Dynamic References](dynamic-references.md) for the full vocabulary, runtime
+contract, and boot-time validation guarantees.
+
+| Expression | Resolves To |
+|------------|-------------|
+| `current_datetime` | `Time.current` |
+| `current_date` | `Date.current` |
+| `current_user.id` | Authenticated user's ID |
+| `current_user.<method>` | Any method on the user (validated at boot) |
+| `record.<field>` | Copy value from another field on the record |
+| `{ value: "literal" }` | Literal string (escape hatch — strings that look like dynamic refs need this wrapper) |
+| `{ value: 42 }` | Literal number |
+| `{ value: null }` | `nil` (clears the field) |
+
+**DSL shorthand:** In the Ruby DSL, convenience shortcuts are available:
+- `:now` → `"current_datetime"`
+- `:today` → `"current_date"`
+- `:null` → `{ value: "null" }`
+
+### Guard Conditions
+
+Guards use `ConditionEvaluator` — the same engine as `visible_when`, `record_rules`, and `item_classes`. All 15 operators and compound syntax (`all`/`any`/`not`) are supported. See [Condition Operators](condition-operators.md).
+
+```yaml
+# Simple condition
+guard:
+  field: amount
+  operator: gt
+  value: 0
+
+# Compound condition
+guard:
+  all:
+    - { field: title, operator: present }
+    - { field: amount, operator: gt, value: 0 }
+    - { field: department_id, operator: present }
+```
+
+## Execution Order
+
+When a transition executes (e.g., `draft` → `pending_approval`):
+
+1. Guard condition evaluated
+2. Role check performed
+3. `set_fields` values resolved and applied to record
+4. Workflow field updated (`status = "pending_approval"`)
+5. Record saved (within transaction)
+6. Audit log entry written (within same transaction)
+7. `on_exit` events for old state fired
+8. `on_entry` events for new state fired
+9. Transition-level `events` fired
+
+Steps 7–9 happen after the transaction commits. Event handlers see the record in its new state.
+
+## Transition Visibility
+
+A transition button appears on the show page when ALL conditions are true:
+
+1. User has `update` permission on the record
+2. User's role is in `transition.roles` (or roles is empty)
+3. Record's current state is in `transition.from`
+4. Guard condition passes (if defined)
+5. `transition.trigger` is `"user"` or `"both"`
+6. Presenter has not suppressed it (`visible: false`)
+
+## Direct Enum Update Blocking
+
+When a workflow is active, a `before_save` callback blocks direct changes to the workflow field:
+
+```ruby
+record.update!(status: "approved")  # => TransitionDeniedError
+
+record.execute_transition!("approve", user: current_user, evaluator: evaluator)  # OK
+```
+
+The blocking is bypassed internally by `TransitionExecutor` using a flag during execution.
+
+## Presenter Integration
+
+Transitions auto-generate action buttons. The presenter can customize or suppress them:
+
+```yaml
+actions:
+  single:
+    # Override a transition's appearance
+    - name: submit
+      style: primary
+
+    # Hide a transition from this presenter
+    - name: force_approve
+      visible: false
+
+    # Non-workflow actions work as before
+    - { name: show, type: built_in, icon: eye }
+```
+
+## Audit Log
+
+When `audit_log: true`, every transition is recorded in the workflow audit log table.
+
+### Audit Log Model Contract
+
+Required fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `record_type` | string | LCP model name |
+| `record_id` | integer | Record primary key |
+| `workflow_name` | string | Workflow definition name |
+| `transition_name` | string | Name of the transition executed |
+| `from_state` | string | State before transition |
+| `to_state` | string | State after transition |
+
+Recommended fields (warnings if missing):
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `workflow_version` | integer | Workflow version at time of transition |
+| `user_id` | integer | User who triggered the transition |
+| `user_snapshot` | json | `{ id, email, name, role }` captured at transition time |
+| `comment` | text | User-provided comment (if `require_comment`). Written **only here** — never persisted on the parent record. If the `comment` column is absent from the audit model, the text is silently dropped (validate with `rake lcp_ruby:validate`). |
+| `metadata` | json | Extra context: `{ triggered_by: "approval_engine" }` |
+
+### Coexistence with Data Auditing
+
+When a model has both `auditing: true` and a workflow, both systems operate independently:
+
+| | Data Audit (`lcp_audit_logs`) | Workflow Audit (`workflow_audit_logs`) |
+|---|---|---|
+| Trigger | `after_save` callback | `TransitionExecutor` |
+| Records | Field-level diffs | Transition metadata |
+| Purpose | "What changed?" | "What state transitions occurred and why?" |
+
+Both are written within the same transaction. No conflict.
+
+## Renderer Integration
+
+Workflow fields are automatically rendered with visual components when no explicit renderer is set:
+
+| Context | Auto-detected renderer | Description |
+|---------|----------------------|-------------|
+| Show page | `workflow_timeline` | Linear progress bar with completed/current/future steps |
+| Index page | `workflow_badge` | Colored badge using the state's `color` from the workflow definition |
+
+Auto-detection applies when ALL of these are true:
+- The field has an active workflow definition
+- No explicit `renderer:` is set on the field
+- The field type is `enum`
+
+To opt out, set any explicit renderer on the field (e.g., `renderer: badge`).
+
+Both renderers also support manual mode without a workflow — pass `states` and `colors` options explicitly. See the [Renderers Guide](../guides/display-types.md#workflow-renderers) for full options.
+
+The `workflow_graph` widget renders a full Mermaid.js state diagram on composite pages. See [Pages Reference — workflow_graph](pages.md#workflow_graph) for configuration.
+
+### i18n Keys
+
+State and transition labels use these i18n keys (with humanized fallback):
+
+```yaml
+lcp_ruby:
+  workflows:
+    purchase_order_workflow:
+      states:
+        draft: "Draft"
+        pending_approval: "Pending Approval"
+        approved: "Approved"
+        rejected: "Rejected"
+      transitions:
+        submit: "Submit for Approval"
+        approve: "Approve"
+        reject: "Reject"
+```
+
+Pattern: `lcp_ruby.workflows.<workflow_name>.states.<state_name>` and `lcp_ruby.workflows.<workflow_name>.transitions.<transition_name>`.
+
+## Convenience Methods
+
+Models with a workflow-eligible enum field get these instance methods:
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `workflow_definition` | `WorkflowDefinition` or `nil` | The workflow definition for this model |
+| `available_transitions(user:, evaluator:)` | `Array<TransitionDefinition>` | Transitions available from the current state for the given user |
+| `execute_transition!(name, user:, evaluator:, comment: nil, triggered_by: nil)` | `TransitionResult` | Execute a named transition |
+| `current_workflow_state` | `StateDefinition` or `nil` | The state definition for the current enum value |
+| `workflow_audit_logs` | `ActiveRecord::Relation` | Audit log entries for this record |
+
+**Example — programmatic transition:**
+
+```ruby
+perm_def = LcpRuby.loader.permission_definition("purchase_order")
+evaluator = LcpRuby::Authorization::PermissionEvaluator.new(perm_def, user, "purchase_order")
+
+begin
+  result = record.execute_transition!(
+    "submit",
+    user: user,
+    evaluator: evaluator,
+    comment: "Submitted for approval"  # required when the transition has require_comment: true
+  )
+  redirect_to record  # result.success? is always true on the happy path
+rescue LcpRuby::Workflow::TransitionDeniedError,
+       LcpRuby::Workflow::CommentRequiredError => e
+  flash[:alert] = e.message
+end
+```
+
+`execute_transition!` raises on every failure (see [Error Classes](#error-classes)) and returns a `TransitionResult` only on success. For richer usage patterns (conditional branches, batch flows, seed scripts), see [Workflow Guide — Execute a Transition](../guides/workflow.md#execute-a-transition).
+
+## Three Definition Sources
+
+Workflow definitions support three interchangeable sources, following the platform's configuration source principle.
+
+### Configuration
+
+```ruby
+LcpRuby.configure do |config|
+  config.workflow_source = :static     # :static | :model | :host
+
+  # DB model source
+  config.workflow_model = "workflow_definition"
+  config.workflow_model_fields = {
+    name: "name", model_name: "model_name", field_name: "field_name",
+    states: "states", transitions: "transitions",
+    version: "version", active: "active", audit_log: "audit_log"
+  }
+
+  # Host source
+  config.workflow_provider = nil
+
+  # Audit log model
+  config.workflow_audit_model = "workflow_audit_log"
+  config.workflow_audit_model_fields = {
+    record_type: "record_type", record_id: "record_id",
+    workflow_name: "workflow_name", workflow_version: "workflow_version",
+    transition_name: "transition_name", from_state: "from_state",
+    to_state: "to_state", user_id: "user_id", user_snapshot: "user_snapshot",
+    comment: "comment", metadata: "metadata"
+  }
+end
+```
+
+### `workflow_source`
+
+| Value | Behavior |
+|-------|----------|
+| `:static` | YAML/DSL files in `config/lcp_ruby/workflows/`. Always loaded if files exist. |
+| `:model` | DB-backed definitions. Requires a model satisfying the workflow contract. |
+| `:host` | Host application provides a Ruby class implementing `StateMachineContract`. |
+
+Static source is always active (if files exist). The configured source is additive. Priority on name conflicts: **static > model > host**.
+
+### Model Source Contract
+
+The DB model must have these fields:
+
+| Logical Name | Type | Description |
+|---|---|---|
+| `name` | string | Unique workflow name |
+| `model_name` | string | Target model name |
+| `field_name` | string | Enum field name |
+| `states` | json | States hash |
+| `transitions` | json | Transitions hash |
+| `version` | integer | Definition version |
+| `active` | boolean | Only active definitions are loaded |
+
+### Host Source Contract
+
+The provider class must implement:
+
+```ruby
+class WorkflowProvider
+  include LcpRuby::Workflow::StateMachineContract
+
+  def workflows_for(model_name)
+    # Return Array of WorkflowDefinition or Hash
+  end
+
+  def workflow_by_name(name)
+    # Return WorkflowDefinition, Hash, or nil
+  end
+end
+```
+
+## Routing
+
+| Method | Path | Action |
+|--------|------|--------|
+| POST | `/:lcp_slug/:id/transitions/:transition_name` | Execute a transition |
+
+The transition name comes from the URL. Optional `transition_comment` parameter for comments.
+
+## Error Classes
+
+| Error | Raised When |
+|-------|-------------|
+| `Workflow::TransitionDeniedError` | Transition not allowed (wrong state, role, guard) |
+| `Workflow::CommentRequiredError` | `require_comment: true` but no comment provided |
+| `Workflow::WorkflowError` | Base class for all workflow errors |
+
+## Architecture
+
+```
+Workflow YAML/DSL
+  → Metadata::Loader.load_workflows
+  → WorkflowDefinition.from_hash (validates states, transitions)
+  → Workflow::Setup.apply! (sources, resolver, registry, audit setup)
+  → WorkflowApplicator installs before_save guard + convenience methods
+
+User clicks transition button
+  → POST /:slug/:id/transitions/:name
+  → ResourcesController#execute_transition
+  → TransitionExecutor.execute
+    → StateMachine.validate_transition! (state, role, guard)
+    → ValueResolver.resolve (set_fields expressions)
+    → Record saved in transaction
+    → AuditWriter.log (if audit_log enabled)
+    → Events::Dispatcher (on_exit, on_entry, transition events)
+  → TransitionResult
+
+ActionSet (show page)
+  → TransitionActionBuilder.build_actions
+  → Filters system-only, applies presenter overrides
+  → Renders _transition_button.html.erb
+```
+
+Source: `lib/lcp_ruby/workflow/`, `lib/lcp_ruby/model_factory/workflow_applicator.rb`, `lib/lcp_ruby/dsl/workflow_builder.rb`
+
+---
+
+## Approvals
+
+The approval engine adds multi-step approval processes on top of the state machine. See the [Workflow Approvals Reference](workflow-approvals.md) for the full specification.

data/examples/crm/Gemfile

@@ -0,0 +1,9 @@
+source "https://rubygems.org"
+
+gem "rails", "~> 7.1"
+gem "sqlite3", "~> 1.4"
+gem "puma", "~> 6.0"
+gem "sprockets-rails"
+gem "image_processing", "~> 1.2"
+gem "chartkick"
+gem "lcp", path: "../.."