fosm-rails 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: caa495883333e121bf051fcc48f83f16a9182bf0b3ab04257f0c6eb4d6aa107b
-  data.tar.gz: 95d917636381c725c1bc35f105775bf7dd262064143d1779bf2eee24a092fb6a
+  metadata.gz: 632476c001f595b1c39b2eb3a98af17ff6aeca2c54505a373c85bc442d3f07fd
+  data.tar.gz: 1d1401c44b00161288485afa4bb7228cfd88e216b1254d12233345334d437eeb
 SHA512:
-  metadata.gz: b0a8dcc832dc6a0b459023dc630a224d45d321add78a180d96d0e588b7080e1546809001bbd8e48441e67ca39062fca5ad3fb14e2319d2001e3ad20b395217ba
-  data.tar.gz: 73ae82e375097698267f092dbffea06f2472ef36ec4f158213daf3186890d51ec5a53e2f7fb26fa974827f0180bae3bf6bf2e9c62100e7b74828f2bf1f9dafa9
+  metadata.gz: 343cff86bca38d2098bee6b13a577c4d9b2ec1f14dd186d12f1ea239817768a737e86542cd74eb8f6266bcc4388faf615351ed6d8677420863d7f6ca1aa3560d
+  data.tar.gz: 5f811cda70c5a7321af1599ce639da25b746f70a81e7dbbecb108acd4773259cb2b00450979ab6268a4f41436c3b6a4e8c767d393972cc025701d3a00d940e7e

data/AGENTS.md

@@ -128,8 +128,16 @@ The admin explorer renders the lifecycle definition directly from the Ruby code
 
 The `Fosm::Agent` base class generates exactly one Gemlings tool per lifecycle event. The tool calls `fire!` which enforces the machine rules. The AI cannot fire an event that doesn't exist. The AI cannot bypass a guard. The AI cannot modify state directly.
 
+**RBAC adds a third boundary**: if the model has an `access` block, the agent tool inherits the actor's permissions. An agent running as `actor: current_user` cannot fire events the actor doesn't have a role for. The machine refusal and the permission refusal happen at the same layer — inside `fire!`.
+
 When adding new agent capabilities, add new **lifecycle events** (which automatically generate new agent tools), not new raw database tools.
 
+### 7. Access control lives in the lifecycle definition
+
+Role declarations belong in the same block as states and events — not in a separate policy file, config YAML, or initializer. The lifecycle block IS the specification for what the object is, what it can do, and who can do what to it.
+
+**Do not** introduce a separate authorization mechanism (e.g., Pundit policies, CanCanCan abilities) for FOSM-managed events. Use the `access` block. This keeps the specification co-located and removes the possibility of drift between what the machine allows and what the authorization layer allows.
+
 ---
 
 ## Engine architecture
@@ -139,15 +147,19 @@ lib/
   fosm/
     lifecycle.rb                  ← ActiveSupport::Concern — the main DSL mixin
     lifecycle/
-      definition.rb               ← Holds states/events/guards/side_effects for one model
+      definition.rb               ← Holds states/events/guards/side_effects/access for one model
       state_definition.rb         ← Value object: name, initial?, terminal?
       event_definition.rb         ← Value object: name, from_states, to_state, guards, side_effects
       guard_definition.rb         ← Named callable: (record) → bool
       side_effect_definition.rb   ← Named callable: (record, transition) → void
+      access_definition.rb        ← access{} block: roles, default_role, permission lookups
+      role_definition.rb          ← Individual role: CRUD permissions + event permissions
+    current.rb                    ← Per-request RBAC cache (ActiveSupport::CurrentAttributes)
+    transition_buffer.rb          ← :buffered log strategy — thread-safe queue + bulk INSERT
     agent.rb                      ← Base class: model_class DSL + Gemlings tool generation
-    configuration.rb              ← Fosm.configure { } block
+    configuration.rb              ← Fosm.configure { } block (incl. transition_log_strategy)
     registry.rb                   ← Global slug → model_class map
-    errors.rb                     ← Fosm::InvalidTransition, GuardFailed, etc.
+    errors.rb                     ← Fosm::InvalidTransition, GuardFailed, AccessDenied, etc.
     engine.rb                     ← Rails::Engine, migration hooks, auto-registration
   fosm-rails.rb                   ← Entry point
 
@@ -155,16 +167,21 @@ app/
   models/fosm/
     transition_log.rb             ← Immutable audit trail (shared across all FOSM apps)
     webhook_subscription.rb       ← Admin-configured HTTP callbacks
+    role_assignment.rb            ← Actor → role → resource (type-level or record-level)
+    access_event.rb               ← Immutable RBAC audit log (grants/revokes)
   controllers/fosm/
-    application_controller.rb     ← Inherits from configured base_controller
+    application_controller.rb     ← Inherits from base_controller; provides fosm_authorize!
     admin/
       base_controller.rb          ← Admin auth before_action
       dashboard_controller.rb
-      apps_controller.rb
+      apps_controller.rb          ← Renders access control matrix on app detail page
+      roles_controller.rb         ← Grant/revoke roles; superadmin only
       transitions_controller.rb
       webhooks_controller.rb
   jobs/fosm/
     webhook_delivery_job.rb       ← Async HTTP POST with HMAC signing, retries
+    transition_log_job.rb         ← Async transition log write (:async strategy)
+    access_event_job.rb           ← Async RBAC audit log write
 
 lib/generators/fosm/app/
   app_generator.rb                ← rails generate fosm:app
@@ -181,6 +198,8 @@ lib/generators/fosm/app/
 
 ## How `fire!` works
 
+With the RBAC and async audit trail additions, `fire!` now follows this sequence:
+
 ```
 record.fire!(:send_invoice, actor: current_user)
 
@@ -189,16 +208,45 @@ record.fire!(:send_invoice, actor: current_user)
 3. Check: is current state terminal? → raise TerminalState if yes
 4. Check: is the event valid from current state? → raise InvalidTransition if not
 5. Run guards: each guard.call(record) → raise GuardFailed if any return false
-6. Begin database transaction:
+6. RBAC check (if access block declared):
+   a. Bypass if actor is nil, Symbol, or superadmin
+   b. Load actor's roles from per-request cache (one SQL query total, then O(1))
+   c. Check if any actor role permits this event → raise AccessDenied if not
+7. Begin database transaction:
    a. UPDATE record SET state = 'sent'
-   b. INSERT INTO fosm_transition_logs (...)
+   b. [if strategy == :sync] INSERT INTO fosm_transition_logs (...)
    c. Run each side_effect.call(record, transition_data)
    d. COMMIT (or ROLLBACK if any step raises)
-7. Enqueue WebhookDeliveryJob asynchronously (outside transaction)
-8. Return true
+8. [if strategy == :async]    Enqueue TransitionLogJob (non-blocking)
+   [if strategy == :buffered] Push to TransitionBuffer (flushed every ~1s)
+9. Enqueue WebhookDeliveryJob asynchronously (always, outside transaction)
+10. Return true
+```
+
+**Total blocking SQL operations: 1** (the UPDATE). Everything else is either in-memory, cached, or async. The RBAC check at step 6 is O(1) after the first check per actor per request.
+
+### Transition log strategies
+
+| Strategy | Latency | Consistency | When to use |
+|---|---|---|---|
+| `:sync` | +1ms | Strict — log always matches state | Compliance requirements, testing |
+| `:async` | ~0ms | Near-real-time (ms delay via SolidQueue) | Production default |
+| `:buffered` | ~0ms | Up to 1s delay; data loss on crash | Very high throughput (1000+ fire!/sec) |
+
+Configure in `config/initializers/fosm.rb`:
+```ruby
+config.transition_log_strategy = :async  # recommended
 ```
 
-The transaction ensures that if a side effect raises, the state update is rolled back. The webhook job fires outside the transaction so it doesn't delay the response and doesn't roll back if the HTTP call fails.
+### RBAC access model
+
+The access control design draws from three traditions:
+
+- **Linux/POSIX**: permissions live ON the object (in the lifecycle block, not a separate file), deny-by-default once declared, root/superadmin always bypasses
+- **SAP authorization**: separation of duties (the :owner who sends an invoice cannot be the :approver who pays it), activity granularity (CRUD actions + individual events), audit trail for every access change
+- **Rails/DHH**: convention-over-configuration (no `access` block = open by default), rules readable as English in the model file, one query per request via `CurrentAttributes` cache
+
+The `Fosm::Current` cache loads ALL role assignments for the current actor in one SQL query on first access, keyed by `"ClassName:id"`. Subsequent RBAC checks in the same request (across multiple records or events) hit the in-memory hash only. The cache resets automatically at the end of each request.
 
 ---
 

data/README.md

@@ -58,7 +58,7 @@ Rails.application.routes.draw do
 end
 ```
 
-Configure auth in `config/initializers/fosm.rb`:
+Configure auth and performance in `config/initializers/fosm.rb`:
 
 ```ruby
 Fosm.configure do |config|
@@ -71,12 +71,18 @@ Fosm.configure do |config|
   # How to authorize individual FOSM apps
   config.app_authorize = ->(_level) { authenticate_user! }
 
-  # How to get the current user (for transition log actor tracking)
+  # How to get the current user (for transition log actor tracking and RBAC)
   config.current_user_method = -> { current_user }
 
   # Layouts
   config.admin_layout = "admin"    # your admin layout
   config.app_layout   = "application"
+
+  # Transition log write strategy:
+  #   :sync     — INSERT inside the fire! transaction (strictest consistency, default)
+  #   :async    — SolidQueue job after commit (non-blocking, recommended for production)
+  #   :buffered — bulk INSERT every ~1s via background thread (highest throughput)
+  config.transition_log_strategy = :async
 end
 ```
 
@@ -150,6 +156,107 @@ side_effect :send_notification, on: :activate do |record, transition|
 end
 ```
 
+### Access control (RBAC)
+
+Declare role-based access control inside the `lifecycle` block. Without an `access` block the object is **open-by-default** (all authenticated actors can do everything — backwards-compatible). Once you add an `access` block, the object becomes **deny-by-default**: only explicitly granted capabilities work.
+
+```ruby
+lifecycle do
+  state :draft, initial: true
+  state :sent
+  state :paid, terminal: true
+  state :cancelled, terminal: true
+
+  event :send_invoice, from: :draft,          to: :sent
+  event :pay,          from: [:sent],         to: :paid
+  event :cancel,       from: [:draft, :sent], to: :cancelled
+
+  # ── Access control ────────────────────────────────────────────────
+  access do
+    # default: true → this role is auto-assigned to the record creator on create
+    role :owner, default: true do
+      can :crud                      # shorthand: create + read + update + delete
+      can :send_invoice, :cancel     # lifecycle events this role may fire
+    end
+
+    role :approver do
+      can :read                      # view the record
+      can :pay                       # fire the :pay event (separation of duties)
+    end
+
+    role :viewer do
+      can :read                      # read-only, no event access
+    end
+  end
+end
+```
+
+**`can` accepts:**
+
+| Argument | Meaning |
+|---|---|
+| `:crud` | Shorthand for all four CRUD operations |
+| `:create` / `:read` / `:update` / `:delete` | Individual CRUD permission |
+| `:send_invoice`, `:pay`, etc. | Permission to fire that specific lifecycle event |
+
+**Bypass rules (never blocked by RBAC):**
+
+| Actor | Reason |
+|---|---|
+| `actor: nil` | No user context (cron jobs, migrations, console) |
+| `actor: :system` or any Symbol | Programmatic / internal invocations |
+| Superadmin (`actor.superadmin? == true`) | Root equivalent — bypasses all checks |
+
+#### Role assignment database
+
+Roles are stored in `fosm_role_assignments`. Two scopes:
+
+```ruby
+# Type-level: Alice is an :approver for ALL Fosm::Invoice records
+Fosm::RoleAssignment.create!(
+  user_type:     "User",
+  user_id:       alice.id.to_s,
+  resource_type: "Fosm::Invoice",
+  resource_id:   nil,           # nil = type-level
+  role_name:     "approver"
+)
+
+# Record-level: Bob is an :owner for Invoice #42 only
+Fosm::RoleAssignment.create!(
+  user_type:     "User",
+  user_id:       bob.id.to_s,
+  resource_type: "Fosm::Invoice",
+  resource_id:   "42",          # specific record
+  role_name:     "owner"
+)
+```
+
+**Auto-assignment on create:** if `default: true` is set on a role and the record has a `created_by` association, FOSM automatically assigns that role to the creator when the record is saved.
+
+#### Runtime performance
+
+The first RBAC check in a request loads ALL role assignments for the current actor in **one SQL query**, then serves all subsequent checks in the same request from an in-memory hash (O(1)). The cache resets automatically at the end of each request via `ActiveSupport::CurrentAttributes`.
+
+#### CRUD enforcement in controllers
+
+Use `fosm_authorize!` in generated controllers to enforce CRUD permissions:
+
+```ruby
+class Fosm::InvoiceController < Fosm::ApplicationController
+  before_action -> { fosm_authorize!(:read,   Fosm::Invoice) }, only: [:index, :show]
+  before_action -> { fosm_authorize!(:create, Fosm::Invoice) }, only: [:new, :create]
+  before_action -> { fosm_authorize!(:update, @record) },       only: [:edit, :update]
+  before_action -> { fosm_authorize!(:delete, @record) },       only: [:destroy]
+end
+```
+
+Raises `Fosm::AccessDenied` (a subclass of `Fosm::Error`) if the actor lacks the required role. RBAC is only checked if the lifecycle has an `access` block — otherwise `fosm_authorize!` is a no-op.
+
+#### Admin UI for roles
+
+- **App detail page** (`/fosm/admin/apps/:slug`) — shows a read-only access control matrix below the lifecycle definition table, with one column per CRUD action and one per lifecycle event
+- **Role assignments** (`/fosm/admin/roles`) — manage role assignments, view declared roles per app, and browse the immutable access event audit trail
+
 ---
 
 ## Firing events
@@ -225,8 +332,9 @@ The agent cannot fire an event that doesn't exist in the lifecycle. Invalid tran
 
 The engine mounts an admin interface at `/fosm/admin` (access controlled by `config.admin_authorize`):
 
-- **Dashboard** — all FOSM apps with state distribution
-- **App detail** — lifecycle definition table, state distribution chart, stuck record detection
+- **Dashboard** — all FOSM apps with state distribution; link to role assignments
+- **App detail** — lifecycle definition table, state distribution chart, stuck record detection, and **access control matrix** (read-only view of declared roles and permissions)
+- **Role assignments** (`/fosm/admin/roles`) — grant/revoke roles, view declared roles per app, browse immutable access event audit trail; accessible only to `config.admin_authorize` actors
 - **Agent explorer** (`/fosm/admin/apps/:slug/agent`) — the auto-generated tool catalog for the app's AI agent, a direct tool tester (no LLM required), and the system prompt injected into agents
 - **Agent chat** (`/fosm/admin/apps/:slug/agent/chat`) — live multi-turn chat with the agent; see tool calls, thoughts, and state changes in real time
 - **Transition log** — complete audit trail, filterable by app / event / actor (human vs AI agent)
@@ -289,13 +397,22 @@ your_rails_app/
 
 # Engine provides (from gem):
   app/models/fosm/
-    transition_log.rb     ← Shared audit trail
+    transition_log.rb     ← Shared immutable transition audit trail
     webhook_subscription.rb
+    role_assignment.rb    ← RBAC: actor → role → resource
+    access_event.rb       ← RBAC: immutable audit log of grants/revokes
   app/controllers/fosm/admin/
     dashboard_controller.rb
+    roles_controller.rb   ← Role assignment management (superadmin only)
     ...
   lib/fosm/
-    lifecycle.rb          ← The DSL concern
+    lifecycle.rb          ← The DSL concern (states, events, guards, access)
+    lifecycle/
+      definition.rb       ← Holds all lifecycle + access metadata
+      access_definition.rb ← access{} block: role declarations
+      role_definition.rb  ← Individual role with CRUD + event permissions
+    current.rb            ← Per-request RBAC cache (one SQL query per actor)
+    transition_buffer.rb  ← :buffered log strategy (bulk INSERT thread)
     agent.rb              ← Gemlings base agent
     engine.rb
 ```

data/app/controllers/fosm/admin/roles_controller.rb

@@ -0,0 +1,117 @@
+module Fosm
+  module Admin
+    class RolesController < Fosm::Admin::BaseController
+      def index
+        @assignments     = Fosm::RoleAssignment.order(created_at: :desc)
+        @access_events   = Fosm::AccessEvent.recent.limit(20)
+        @apps            = Fosm::Registry.all
+      end
+
+      def new
+        @assignment = Fosm::RoleAssignment.new
+        @apps       = Fosm::Registry.all
+      end
+
+      def create
+        @assignment = Fosm::RoleAssignment.new(assignment_params)
+        @assignment.granted_by_type = fosm_current_user&.class&.name
+        @assignment.granted_by_id   = fosm_current_user&.id&.to_s
+
+        if @assignment.save
+          Fosm::AccessEventJob.perform_later({
+            "action"             => "grant",
+            "user_type"          => @assignment.user_type,
+            "user_id"            => @assignment.user_id,
+            "user_label"         => resolve_user_label(@assignment.user_type, @assignment.user_id),
+            "resource_type"      => @assignment.resource_type,
+            "resource_id"        => @assignment.resource_id,
+            "role_name"          => @assignment.role_name,
+            "performed_by_type"  => fosm_current_user&.class&.name,
+            "performed_by_id"    => fosm_current_user&.id&.to_s,
+            "performed_by_label" => (fosm_current_user.respond_to?(:email) ? fosm_current_user.email : fosm_current_user.to_s)
+          })
+
+          # Invalidate the per-request RBAC cache for the affected user so their
+          # new role is visible immediately in the same request (unlikely but correct)
+          user = @assignment.actor
+          Fosm::Current.invalidate_for(user) if user
+
+          redirect_to fosm.admin_roles_path, notice: "Role :#{@assignment.role_name} granted to #{@assignment.actor_label}."
+        else
+          @apps = Fosm::Registry.all
+          render :new, status: :unprocessable_entity
+        end
+      end
+
+      def users_search
+        q         = params[:q].to_s.strip
+        user_type = params[:user_type].presence || "User"
+        results   = []
+
+        begin
+          klass = user_type.constantize
+          scope = klass.all
+
+          if q.present?
+            searchable = klass.column_names & %w[email name]
+            if searchable.any?
+              conditions = searchable.map { |col| "lower(#{col}) LIKE :q" }.join(" OR ")
+              scope = scope.where(conditions, q: "%#{q.downcase}%")
+            end
+          end
+
+          results = scope.limit(10).map do |user|
+            label = [
+              (user.name if user.respond_to?(:name) && user.name.present?),
+              (user.email if user.respond_to?(:email))
+            ].compact.join(" — ")
+            { id: user.id.to_s, label: label }
+          end
+        rescue NameError
+          # unknown user_type — return empty
+        end
+
+        render json: results
+      end
+
+      def destroy
+        @assignment = Fosm::RoleAssignment.find(params[:id])
+
+        Fosm::AccessEventJob.perform_later({
+          "action"             => "revoke",
+          "user_type"          => @assignment.user_type,
+          "user_id"            => @assignment.user_id,
+          "user_label"         => @assignment.actor_label,
+          "resource_type"      => @assignment.resource_type,
+          "resource_id"        => @assignment.resource_id,
+          "role_name"          => @assignment.role_name,
+          "performed_by_type"  => fosm_current_user&.class&.name,
+          "performed_by_id"    => fosm_current_user&.id&.to_s,
+          "performed_by_label" => (fosm_current_user.respond_to?(:email) ? fosm_current_user.email : fosm_current_user.to_s)
+        })
+
+        user = @assignment.actor
+        @assignment.destroy!
+        Fosm::Current.invalidate_for(user) if user
+
+        redirect_to fosm.admin_roles_path, notice: "Role revoked."
+      end
+
+      private
+
+      def assignment_params
+        params.require(:fosm_role_assignment).permit(
+          :user_type, :user_id, :resource_type, :resource_id, :role_name
+        )
+      end
+
+      def resolve_user_label(user_type, user_id)
+        user = user_type.constantize.find_by(id: user_id)
+        return "#{user_type}##{user_id}" unless user
+        user.respond_to?(:email) ? user.email : user.to_s
+      rescue NameError
+        "#{user_type}##{user_id}"
+      end
+    end
+  end
+end

data/app/controllers/fosm/application_controller.rb

@@ -19,5 +19,37 @@ module Fosm
     def fosm_current_user
       instance_exec(&Fosm.config.current_user_method)
     end
+
+    # Check CRUD permissions for the current actor.
+    # Raises Fosm::AccessDenied if the actor lacks the required role.
+    # No-ops if the lifecycle has no access block declared (open-by-default).
+    #
+    # @param action  [Symbol] :create, :read, :update, or :delete
+    # @param subject [ActiveRecord::Base, Class] a record or model class
+    #
+    # Example usage in generated controllers:
+    #   before_action -> { fosm_authorize!(:read,   Fosm::Invoice) }, only: [:index, :show]
+    #   before_action -> { fosm_authorize!(:create, Fosm::Invoice) }, only: [:new, :create]
+    #   before_action -> { fosm_authorize!(:update, @record) },       only: [:edit, :update]
+    #   before_action -> { fosm_authorize!(:delete, @record) },       only: [:destroy]
+    def fosm_authorize!(action, subject)
+      model_class = subject.is_a?(Class) ? subject : subject.class
+      lifecycle   = model_class.try(:fosm_lifecycle)
+      return unless lifecycle&.access_defined?
+
+      actor = fosm_current_user
+      # Bypass for superadmin and nil/symbol actors (mirrors fire! logic)
+      return if actor.nil?
+      return if actor.is_a?(Symbol)
+      return if actor.respond_to?(:superadmin?) && actor.superadmin?
+
+      record_id       = subject.is_a?(ActiveRecord::Base) ? subject.id : nil
+      actor_roles     = Fosm::Current.roles_for(actor, model_class, record_id)
+      permitted_roles = lifecycle.access_definition.roles_for_crud(action)
+
+      unless (actor_roles & permitted_roles).any?
+        raise Fosm::AccessDenied.new(action, actor)
+      end
+    end
   end
 end

data/app/jobs/fosm/access_event_job.rb

@@ -0,0 +1,12 @@
+module Fosm
+  # Writes an access event audit record asynchronously.
+  # Called whenever a role is granted or revoked.
+  class AccessEventJob < Fosm::ApplicationJob
+    queue_as :fosm_audit
+
+    # @param event_data [Hash] all columns for the access event row (string keys)
+    def perform(event_data)
+      Fosm::AccessEvent.create!(event_data)
+    end
+  end
+end

data/app/jobs/fosm/transition_log_job.rb

@@ -0,0 +1,16 @@
+module Fosm
+  # Writes a single transition log entry asynchronously.
+  # Used when config.transition_log_strategy = :async (SolidQueue default).
+  #
+  # The state UPDATE has already committed before this job runs, so there is
+  # at most a brief delay between the transition completing and the log entry
+  # appearing. For strict consistency, use config.transition_log_strategy = :sync.
+  class TransitionLogJob < Fosm::ApplicationJob
+    queue_as :fosm_audit
+
+    # @param log_data [Hash] all columns for the transition log row (string keys)
+    def perform(log_data)
+      Fosm::TransitionLog.create!(log_data)
+    end
+  end
+end

data/app/models/fosm/access_event.rb

@@ -0,0 +1,33 @@
+module Fosm
+  # Immutable append-only audit log for RBAC operations.
+  #
+  # Records every grant and revoke action so there is a complete audit trail
+  # of who had what access, when, and who authorized it.
+  #
+  # Written asynchronously via Fosm::AccessEventJob (non-blocking).
+  class AccessEvent < Fosm::ApplicationRecord
+    self.table_name = "fosm_access_events"
+
+    ACTIONS = %w[grant revoke auto_grant].freeze
+
+    validates :action,        presence: true, inclusion: { in: ACTIONS }
+    validates :user_type,     presence: true
+    validates :user_id,       presence: true
+    validates :resource_type, presence: true
+    validates :role_name,     presence: true
+
+    # Immutability: access events are append-only, never modified or deleted
+    before_update { raise ActiveRecord::ReadOnlyRecord, "Fosm::AccessEvent records are immutable" }
+    before_destroy { raise ActiveRecord::ReadOnlyRecord, "Fosm::AccessEvent records are immutable" }
+
+    scope :recent,     -> { order(created_at: :desc) }
+    scope :grants,     -> { where(action: "grant") }
+    scope :revokes,    -> { where(action: "revoke") }
+    scope :for_user,   ->(user) { where(user_type: user.class.name, user_id: user.id.to_s) }
+    scope :for_resource_type, ->(model_class) { where(resource_type: model_class.to_s) }
+
+    def grant?      = action == "grant"
+    def revoke?     = action == "revoke"
+    def auto_grant? = action == "auto_grant"
+  end
+end

data/app/models/fosm/role_assignment.rb

@@ -0,0 +1,61 @@
+module Fosm
+  # Persists an actor's role on a FOSM resource.
+  #
+  # Scopes:
+  #   resource_id: nil  → type-level   ("Alice is an :approver for ALL Fosm::Invoice records")
+  #   resource_id: "42" → record-level ("Alice is an :approver for Fosm::Invoice #42 only")
+  #
+  # Role names must match those declared in the model's lifecycle access block.
+  # This model does NOT validate role names against the lifecycle (it would create a
+  # hard coupling between DB state and code). Invalid role names simply have no effect
+  # at runtime because Fosm::Current.roles_for returns them but no permission grants
+  # will ever include them.
+  class RoleAssignment < Fosm::ApplicationRecord
+    self.table_name = "fosm_role_assignments"
+
+    validates :user_type,     presence: true
+    validates :user_id,       presence: true
+    validates :resource_type, presence: true
+    validates :role_name,     presence: true
+
+    validates :user_id, uniqueness: {
+      scope: %i[user_type resource_type resource_id role_name],
+      message: "already has this role on this resource"
+    }
+
+    # Scope: all type-level assignments (applies to every record of resource_type)
+    scope :type_level,   -> { where(resource_id: nil) }
+    # Scope: all record-level assignments (pinned to a specific record)
+    scope :record_level, -> { where.not(resource_id: nil) }
+    # Scope: for a specific FOSM model class
+    scope :for_resource_type, ->(model_class) { where(resource_type: model_class.to_s) }
+    # Scope: for a specific actor
+    scope :for_user, ->(user) { where(user_type: user.class.name, user_id: user.id.to_s) }
+
+    # Try to resolve the actor object (may return nil if class no longer exists)
+    def actor
+      user_type.constantize.find_by(id: user_id)
+    rescue NameError
+      nil
+    end
+
+    # Human-readable display label for the actor
+    def actor_label
+      a = actor
+      return "#{user_type}##{user_id}" unless a
+      a.respond_to?(:email) ? a.email : a.to_s
+    end
+
+    def record_level?
+      resource_id.present?
+    end
+
+    def type_level?
+      resource_id.nil?
+    end
+
+    def scope_label
+      record_level? ? "#{resource_type}##{resource_id}" : "all #{resource_type.demodulize.pluralize}"
+    end
+  end
+end