fosm-rails 0.2.3 → 0.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50ac8659af44dfad52d33f333001e6b3b846cfbb635e56534366ca371631501a
-  data.tar.gz: 5d727e837eefe74fa85677199b6cbc78b7e3df28fe33f8275e4c8bd93900383b
+  metadata.gz: 6f80bae4ce6fd6dba16419a7a68ac6cec93439bb0296caf5e3c335f039e216ab
+  data.tar.gz: 468c55584847418dc48a49466bd1b13fba8268deb40c20086bce383f8b7221ba
 SHA512:
-  metadata.gz: e3adb965398f95f843d6d58f39f6b1b54d6c0084c46761b0f30678c7484bf6ca6c4e182e21ce5504b391cf147d9495da4d0d1fcad3ec4992693d7129c40c80c0
-  data.tar.gz: 04e1e7595f6dc9c211d7eb923ef167e80d612fab71149f1b5624cc5cbffd46ed64f16d909efd8a4c4a418a4895ba02fba39926fd98f1bcb1a09a028b06e7ca3e
+  metadata.gz: 988a291c82244fd9249e4698df06f921e0a0eddfb20811238dd42b6d780a90560a3aaded7027260b79e7a4d6e31d5489c877d9b7ea0567ba4bd5e65eea95644c
+  data.tar.gz: 2a294a01dd336497e1437a536c8b2e6b1ca69bcffaaea6240e05572e1c9e632ae599c4abd2e099cafb98e8d91c3786fd9a377d9805f43feadef296bbccc1fbc1

data/README.md

@@ -337,6 +337,7 @@ The engine mounts an admin interface at `/fosm/admin` (access controlled by `con
 - **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
+- **Data retention** (`/fosm/admin/data_retention`) — configurable retention policies (default 10 years) with a dashboard showing purge-eligible records per model. Supports single-record and bulk purge with safe-to-purge guards; transition logs are never deleted.
 - **Transition log** — complete audit trail, filterable by app / event / actor (human vs AI agent)
 - **Webhooks** — configure HTTP callbacks for any FOSM event (with HMAC-SHA256 signing)
 - **Settings** — LLM provider key status, engine configuration overview

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

@@ -0,0 +1,125 @@
+module Fosm
+  module Admin
+    # Admin dashboard for data retention policy enforcement.
+    #
+    # Shows all archival-eligible FOSM models (terminal state containing "archiv"
+    # + archived_at column) and lets admins review and purge records that have
+    # exceeded the configured retention window.
+    #
+    # All destructive actions run asynchronously via DataRetentionPurgeJob so
+    # the request/response cycle is never blocked by bulk deletes.
+    class DataRetentionController < BaseController
+      PER_PAGE = 50
+
+      # GET /fosm/admin/data_retention
+      # Lists every archival-eligible model with counts.
+      def index
+        @retention_days  = Fosm.config.data_retention_days
+        @cutoff_date     = Fosm::DataRetention.retention_cutoff_date
+
+        @eligible_models = Fosm::DataRetention.archival_eligible_models.map do |model_class|
+          slug = Fosm::Registry.all.find { |_s, klass| klass.name == model_class.name }&.first
+          {
+            model_class:        model_class,
+            slug:               slug,
+            name:               model_class.name.demodulize.titleize,
+            archival_states:    Fosm::DataRetention.archival_states_for(model_class),
+            total_in_archive:   Fosm::DataRetention.total_in_archival_state(model_class),
+            eligible_for_purge: Fosm::DataRetention.total_eligible_for_purge(model_class)
+          }
+        end
+      end
+
+      # GET /fosm/admin/data_retention/:id   (:id = model slug, e.g. "faas_account")
+      # Paginated list of purge-eligible records for one model.
+      def show
+        @model_class  = resolve_eligible_model!(params[:id])
+        @slug         = params[:id]
+        @name         = @model_class.name.demodulize.titleize
+
+        @retention_days  = Fosm.config.data_retention_days
+        @cutoff_date     = Fosm::DataRetention.retention_cutoff_date
+        @archival_states = Fosm::DataRetention.archival_states_for(@model_class)
+
+        @page        = [params[:page].to_i, 1].max
+        @total       = Fosm::DataRetention.total_eligible_for_purge(@model_class)
+        @total_pages = [(@total.to_f / PER_PAGE).ceil, 1].max
+        @records     = Fosm::DataRetention.records_eligible_for_purge(
+          @model_class, page: @page, per_page: PER_PAGE
+        )
+      end
+
+      # POST /fosm/admin/data_retention/:id/purge_record
+      # Enqueues a single-record purge. params[:record_id] identifies the row.
+      def purge_record
+        @model_class = resolve_eligible_model!(params[:id])
+        record = @model_class.find_by(id: params[:record_id])
+
+        unless record
+          redirect_to fosm.admin_data_retention_path(params[:id]),
+            alert: "Record not found — it may have already been purged."
+          return
+        end
+
+        unless Fosm::DataRetention.safe_to_purge?(record)
+          redirect_to fosm.admin_data_retention_path(params[:id]),
+            alert: "Record ##{record.id} is not eligible for purge " \
+                   "(within the #{Fosm.config.data_retention_days}-day retention window)."
+          return
+        end
+
+        Fosm::DataRetentionPurgeJob.perform_later(
+          model_class_name: @model_class.name,
+          record_id:        record.id.to_s,
+          purged_by_label:  current_admin_label
+        )
+
+        redirect_to fosm.admin_data_retention_path(params[:id]),
+          notice: "Record ##{record.id} has been queued for purge."
+      end
+
+      # POST /fosm/admin/data_retention/:id/purge_all_expired
+      # Enqueues a bulk purge of all retention-expired records for this model.
+      def purge_all_expired
+        @model_class = resolve_eligible_model!(params[:id])
+        total = Fosm::DataRetention.total_eligible_for_purge(@model_class)
+
+        if total.zero?
+          redirect_to fosm.admin_data_retention_path(params[:id]),
+            notice: "No records are eligible for purge."
+          return
+        end
+
+        Fosm::DataRetentionPurgeJob.perform_later(
+          model_class_name: @model_class.name,
+          bulk:             true,
+          purged_by_label:  current_admin_label
+        )
+
+        redirect_to fosm.admin_data_retention_path(params[:id]),
+          notice: "#{total} record(s) queued for bulk purge. This runs asynchronously."
+      end
+
+      private
+
+      def resolve_eligible_model!(slug)
+        model_class = Fosm::Registry.find(slug)
+        raise ActionController::RoutingError, "Unknown FOSM model: #{slug}" unless model_class
+        unless Fosm::DataRetention.archival_eligible?(model_class)
+          raise ActionController::RoutingError,
+            "Model '#{slug}' is not archival-eligible " \
+            "(needs a terminal state containing 'archiv' AND an archived_at column)."
+        end
+        model_class
+      end
+
+      def current_admin_label
+        user = instance_exec(&Fosm.config.current_user_method)
+        return "admin" unless user
+        user.respond_to?(:email) ? user.email : user.to_s
+      rescue
+        "admin"
+      end
+    end
+  end
+end

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

@@ -100,7 +100,7 @@ module Fosm
       private
 
       def assignment_params
-        params.require(:fosm_role_assignment).permit(
+        params.require(:role_assignment).permit(
           :user_type, :user_id, :resource_type, :resource_id, :role_name
         )
       end

data/app/jobs/fosm/data_retention_purge_job.rb

@@ -0,0 +1,129 @@
+module Fosm
+  # Safely purges FOSM records that have exceeded the configured data retention
+  # window. Designed to be triggered from the Data Archival admin UI.
+  #
+  # == Safety guarantees
+  #
+  # 1. Re-checks archival eligibility of the model class on entry.
+  # 2. Re-checks +Fosm::DataRetention.safe_to_purge?+ per record inside the job
+  #    — the controller's pre-check is advisory only; the retention window or
+  #    record state could change between the UI request and job execution.
+  # 3. Missing records are silently skipped (already purged — idempotent).
+  # 4. Records within the retention window are NEVER deleted, even when
+  #    explicitly enqueued — this is the absolute last line of defence.
+  # 5. +fosm_transition_logs+ rows are NOT deleted. The audit trail is
+  #    preserved forever for compliance purposes.
+  # 6. Errors on individual records are logged, not re-raised, so a bulk job
+  #    continues processing the remaining records.
+  # 7. Unknown or non-eligible model class names abort immediately without
+  #    side-effects.
+  #
+  # == Usage
+  #
+  #   # Single record
+  #   Fosm::DataRetentionPurgeJob.perform_later(
+  #     model_class_name: "Fosm::FaasAccount",
+  #     record_id:        "42",
+  #     purged_by_label:  current_user.email
+  #   )
+  #
+  #   # Bulk — purges every eligible record for the model
+  #   Fosm::DataRetentionPurgeJob.perform_later(
+  #     model_class_name: "Fosm::FaasAccount",
+  #     bulk:             true,
+  #     purged_by_label:  current_user.email
+  #   )
+  class DataRetentionPurgeJob < Fosm::ApplicationJob
+    queue_as :default
+
+    # @param model_class_name [String]  e.g. "Fosm::FaasAccount"
+    # @param record_id [String, nil]    ID of a single record to purge
+    # @param bulk [Boolean]             true → purge all eligible records
+    # @param purged_by_label [String]   actor label for audit logging
+    def perform(model_class_name:, record_id: nil, bulk: false, purged_by_label: "system")
+      model_class = resolve_model_class(model_class_name)
+      return unless model_class
+
+      unless Fosm::DataRetention.archival_eligible?(model_class)
+        log_warn "#{model_class_name} is not archival-eligible. Purge aborted."
+        return
+      end
+
+      if bulk
+        purge_all_expired(model_class, purged_by_label)
+      elsif record_id.present?
+        purge_single(model_class, record_id.to_s, purged_by_label)
+      else
+        log_warn "Neither bulk: true nor record_id provided. Nothing to purge."
+      end
+    end
+
+    private
+
+    def resolve_model_class(name)
+      name.constantize
+    rescue NameError => e
+      log_error "Unknown model class '#{name}': #{e.message}"
+      nil
+    end
+
+    def purge_single(model_class, record_id, purged_by_label)
+      record = model_class.find_by(id: record_id)
+      unless record
+        log_warn "#{model_class.name}##{record_id} not found — already purged or never existed."
+        return
+      end
+
+      # CRITICAL: re-verify retention window even if the controller already checked.
+      # The window or state may have changed between the UI click and job execution.
+      unless Fosm::DataRetention.safe_to_purge?(record)
+        log_warn(
+          "#{model_class.name}##{record_id} is within the " \
+          "#{Fosm.config.data_retention_days}-day retention window or not in an " \
+          "archival state. Skipping."
+        )
+        return
+      end
+
+      log_info "Purging #{model_class.name}##{record_id} " \
+               "(archived_at: #{record.archived_at}, purged_by: #{purged_by_label})"
+      record.destroy!
+      log_info "Purged #{model_class.name}##{record_id} successfully."
+    rescue => e
+      log_error "Failed to purge #{model_class.name}##{record_id}: #{e.message}"
+    end
+
+    def purge_all_expired(model_class, purged_by_label)
+      purged  = 0
+      skipped = 0
+
+      Fosm::DataRetention.all_eligible_for_purge(model_class).find_each do |record|
+        # Per-record safety check — never blindly trust the scope alone.
+        unless Fosm::DataRetention.safe_to_purge?(record)
+          log_warn "Skipping #{model_class.name}##{record.id} — within retention window."
+          skipped += 1
+          next
+        end
+
+        begin
+          record.destroy!
+          purged += 1
+        rescue => e
+          log_error "Failed to purge #{model_class.name}##{record.id}: #{e.message}"
+          skipped += 1
+        end
+      end
+
+      log_info "Bulk purge complete for #{model_class.name}: " \
+               "#{purged} purged, #{skipped} skipped (purged_by: #{purged_by_label})."
+    end
+
+    def log_info(msg)  = logger.info("[Fosm::DataRetentionPurgeJob] #{msg}")
+    def log_warn(msg)  = logger.warn("[Fosm::DataRetentionPurgeJob] #{msg}")
+    def log_error(msg) = logger.error("[Fosm::DataRetentionPurgeJob] #{msg}")
+
+    def logger
+      defined?(Rails) && Rails.respond_to?(:logger) ? Rails.logger : Logger.new($stdout)
+    end
+  end
+end

data/app/views/fosm/admin/data_retention/index.html.erb

@@ -0,0 +1,68 @@
+<div class="p-6 space-y-6">
+
+  <!-- Header -->
+  <div>
+    <h1 class="text-2xl font-bold text-gray-900">Data Archival &amp; Deletion</h1>
+    <p class="text-sm text-gray-500 mt-1">
+      Retention policy: <strong><%= @retention_days %> days</strong>
+      &mdash; records archived before
+      <strong><%= @cutoff_date.strftime("%b %d, %Y") %></strong>
+      are eligible for purge.
+    </p>
+  </div>
+
+  <!-- Compliance notice -->
+  <div class="bg-amber-50 border border-amber-200 rounded-lg p-4 text-sm text-amber-800 flex gap-3">
+    <span class="text-amber-500 text-lg leading-none">&#9888;</span>
+    <div>
+      <strong>Compliance notice:</strong> Purging permanently deletes business records.
+      Transition logs (<code class="bg-amber-100 px-1 rounded">fosm_transition_logs</code>)
+      are <em>always</em> preserved for audit compliance — only the source records are removed.
+      Configure <code class="bg-amber-100 px-1 rounded">config.data_retention_days</code>
+      in <code class="bg-amber-100 px-1 rounded">config/initializers/fosm.rb</code>.
+    </div>
+  </div>
+
+  <!-- Model cards -->
+  <% if @eligible_models.empty? %>
+    <div class="bg-gray-50 border border-gray-200 rounded-lg p-8 text-center">
+      <h2 class="font-semibold text-gray-700">No archival-eligible models found</h2>
+      <p class="text-sm text-gray-500 mt-2 max-w-md mx-auto">
+        A model is eligible when it has a terminal state containing
+        <code class="bg-gray-100 px-1 rounded">archiv</code>
+        (e.g. <code class="bg-gray-100 px-1 rounded">:archived</code>)
+        <em>and</em> an
+        <code class="bg-gray-100 px-1 rounded">archived_at</code>
+        datetime column on its table.
+      </p>
+    </div>
+  <% else %>
+    <div class="space-y-3">
+      <% @eligible_models.each do |model| %>
+        <div class="bg-white border border-gray-200 rounded-lg p-5 flex items-center justify-between gap-4">
+          <div class="flex-1 min-w-0">
+            <h2 class="font-semibold text-gray-900"><%= model[:name] %></h2>
+            <p class="text-xs text-gray-400 mt-0.5">
+              Archival states:
+              <% model[:archival_states].each do |s| %>
+                <span class="inline-flex items-center px-1.5 py-0.5 rounded text-xs bg-gray-100 text-gray-600 font-mono"><%= s %></span>
+              <% end %>
+              &middot;
+              <%= model[:total_in_archive] %> total in archive
+            </p>
+          </div>
+          <div class="text-right shrink-0">
+            <p class="text-2xl font-bold <%= model[:eligible_for_purge] > 0 ? 'text-red-600' : 'text-gray-300' %>">
+              <%= model[:eligible_for_purge] %>
+            </p>
+            <p class="text-xs text-gray-500">eligible for purge</p>
+          </div>
+          <%= link_to "Manage &rarr;".html_safe,
+              fosm.admin_data_retention_path(model[:slug]),
+              class: "shrink-0 text-sm text-blue-600 hover:underline font-medium" %>
+        </div>
+      <% end %>
+    </div>
+  <% end %>
+
+</div>

data/app/views/fosm/admin/data_retention/show.html.erb

@@ -0,0 +1,124 @@
+<div class="p-6 space-y-6">
+
+  <!-- Breadcrumb + header -->
+  <div>
+    <%= link_to "&larr; Data Archival".html_safe,
+        fosm.admin_data_retention_index_path,
+        class: "text-sm text-gray-400 hover:text-gray-600 mb-2 block" %>
+    <div class="flex items-start justify-between gap-4">
+      <div>
+        <h1 class="text-2xl font-bold text-gray-900"><%= @name %></h1>
+        <p class="text-sm text-gray-500 mt-1">
+          Records archived before
+          <strong><%= @cutoff_date.strftime("%b %d, %Y") %></strong>
+          (<%= @retention_days %>-day policy) &mdash;
+          <strong><%= @total %></strong> record(s) eligible for purge.
+        </p>
+        <p class="text-xs text-gray-400 mt-0.5">
+          Archival states:
+          <% @archival_states.each do |s| %>
+            <span class="inline-flex items-center px-1.5 py-0.5 rounded text-xs bg-gray-100 text-gray-600 font-mono"><%= s %></span>
+          <% end %>
+        </p>
+      </div>
+
+      <% if @total > 0 %>
+        <%= button_to fosm.purge_all_expired_admin_data_retention_path(@slug),
+            method: :post,
+            data: {
+              confirm: "This will permanently delete ALL #{@total} eligible #{@name} record(s). " \
+                       "Transition logs will be preserved. This cannot be undone. Continue?"
+            },
+            class: "shrink-0 bg-red-600 text-white text-sm font-semibold px-4 py-2 rounded-lg hover:bg-red-700 transition" do %>
+          Purge All <%= @total %> Eligible
+        <% end %>
+      <% end %>
+    </div>
+  </div>
+
+  <!-- Records table -->
+  <% if @records.empty? %>
+    <div class="bg-gray-50 border border-gray-200 rounded-lg p-8 text-center">
+      <p class="text-gray-500 font-medium">No records eligible for purge</p>
+      <p class="text-xs text-gray-400 mt-1">
+        All archived records are within the <%= @retention_days %>-day retention window.
+      </p>
+    </div>
+  <% else %>
+    <div class="bg-white border border-gray-200 rounded-lg overflow-hidden">
+      <table class="w-full text-sm">
+        <thead class="bg-gray-50 text-gray-500 text-xs uppercase tracking-wide">
+          <tr>
+            <th class="px-4 py-3 text-left">ID</th>
+            <th class="px-4 py-3 text-left">State</th>
+            <th class="px-4 py-3 text-left">Archived At</th>
+            <th class="px-4 py-3 text-left">Retention Age</th>
+            <th class="px-4 py-3 text-right">Action</th>
+          </tr>
+        </thead>
+        <tbody class="divide-y divide-gray-100">
+          <% @records.each do |record| %>
+            <tr class="hover:bg-gray-50">
+              <td class="px-4 py-3 text-gray-600 font-mono text-xs">#<%= record.id %></td>
+              <td class="px-4 py-3">
+                <span class="inline-flex items-center px-2 py-0.5 rounded text-xs font-medium bg-gray-100 text-gray-700">
+                  <%= record.state %>
+                </span>
+              </td>
+              <td class="px-4 py-3 text-gray-600 text-xs">
+                <%= record.archived_at&.strftime("%b %d, %Y %H:%M") %> UTC
+              </td>
+              <td class="px-4 py-3 text-xs">
+                <% days_overdue = ((Time.current - record.archived_at) / 1.day).round %>
+                <span class="text-red-600 font-medium"><%= days_overdue %> days</span>
+                <span class="text-gray-400">(+<%= days_overdue - @retention_days %> past window)</span>
+              </td>
+              <td class="px-4 py-3 text-right">
+                <%= button_to fosm.purge_record_admin_data_retention_path(@slug),
+                    params: { record_id: record.id },
+                    method: :post,
+                    data: {
+                      confirm: "Permanently delete #{@name} ##{record.id}? " \
+                               "Transition logs will be preserved. This cannot be undone."
+                    },
+                    class: "text-xs font-medium text-red-600 hover:text-red-800 border border-red-200 hover:border-red-400 px-2 py-1 rounded hover:bg-red-50 transition" do %>
+                  Purge
+                <% end %>
+              </td>
+            </tr>
+          <% end %>
+        </tbody>
+      </table>
+    </div>
+
+    <!-- Pagination -->
+    <% if @total_pages > 1 %>
+      <div class="flex items-center justify-between text-sm text-gray-600">
+        <span>
+          Showing page <%= @page %> of <%= @total_pages %>
+          &middot; <%= @total %> total records eligible
+        </span>
+        <div class="flex gap-2">
+          <% if @page > 1 %>
+            <%= link_to "&larr; Previous".html_safe,
+                fosm.admin_data_retention_path(@slug, page: @page - 1),
+                class: "px-3 py-1.5 border border-gray-200 rounded text-sm hover:bg-gray-50 transition" %>
+          <% end %>
+          <% if @page < @total_pages %>
+            <%= link_to "Next &rarr;".html_safe,
+                fosm.admin_data_retention_path(@slug, page: @page + 1),
+                class: "px-3 py-1.5 border border-gray-200 rounded text-sm hover:bg-gray-50 transition" %>
+          <% end %>
+        </div>
+      </div>
+    <% end %>
+  <% end %>
+
+  <!-- Compliance reminder -->
+  <div class="text-xs text-gray-400 border-t border-gray-100 pt-4">
+    Purge operations run asynchronously via <code>Fosm::DataRetentionPurgeJob</code>.
+    Each record is re-verified against the retention window before deletion.
+    Transition audit logs are never deleted.
+  </div>
+
+</div>

data/app/views/fosm/admin/roles/new.html.erb

@@ -122,12 +122,21 @@
         })();
       </script>
 
+      <%# Build a JSON map: { "Fosm::PartnershipAgreement" => ["owner","viewer"], ... }
+          Used by the JS below to filter Role Name options when resource type changes. %>
+      <% roles_by_type = @apps.each_with_object({}) { |(_, klass), h|
+           next unless klass.fosm_lifecycle&.access_defined?
+           h[klass.name] = klass.fosm_lifecycle.access_definition.role_names.map(&:to_s).sort
+         } %>
+
       <div>
         <label class="block text-sm font-medium text-gray-700 mb-1">Resource Type</label>
         <%= f.select :resource_type,
             @apps.map { |_, klass| [klass.name.demodulize, klass.name] },
             { include_blank: "— Select a FOSM app —" },
-            class: "w-full border border-gray-300 rounded px-3 py-2 text-sm focus:outline-none focus:ring-1 focus:ring-blue-500" %>
+            id: "role_assignment_resource_type",
+            class: "w-full border border-gray-300 rounded px-3 py-2 text-sm focus:outline-none focus:ring-1 focus:ring-blue-500",
+            data: { roles: roles_by_type.to_json } %>
       </div>
 
       <div>
@@ -141,29 +150,130 @@
         </p>
       </div>
 
-      <div>
+      <div id="role-name-field">
         <label class="block text-sm font-medium text-gray-700 mb-1">Role Name</label>
-        <% role_options = @apps.flat_map { |_, klass|
-             next [] unless klass.fosm_lifecycle&.access_defined?
-             klass.fosm_lifecycle.access_definition.role_names.map { |rn|
-               ["#{klass.name.demodulize} → :#{rn}", rn.to_s]
-             }
-           }.uniq(&:last) %>
-        <% if role_options.any? %>
+        <%# Initial render: all known roles sorted. JS narrows this on resource type change. %>
+        <% all_roles = roles_by_type.values.flatten.uniq.sort %>
+        <% if all_roles.any? %>
           <%= f.select :role_name,
-              role_options,
+              all_roles.map { |rn| [":#{rn}", rn] },
               { include_blank: "— Select a role —" },
+              id: "role_assignment_role_name",
               class: "w-full border border-gray-300 rounded px-3 py-2 text-sm focus:outline-none focus:ring-1 focus:ring-blue-500" %>
         <% else %>
-          <%= f.text_field :role_name,
-              placeholder: "owner, approver, viewer…",
+          <%= f.select :role_name,
+              [],
+              { include_blank: "— Select a role —" },
+              id: "role_assignment_role_name",
               class: "w-full border border-gray-300 rounded px-3 py-2 text-sm focus:outline-none focus:ring-1 focus:ring-blue-500" %>
         <% end %>
-        <p class="text-xs text-gray-400 mt-1">Must match a role declared in the lifecycle <code>access</code> block.</p>
+        <p class="text-xs text-gray-400 mt-1" id="role-name-hint">
+          Must match a role declared in the lifecycle <code>access</code> block.
+        </p>
+      </div>
+
+      <div id="no-rbac-warning" class="hidden rounded-lg border border-amber-200 bg-amber-50 px-4 py-3 text-sm text-amber-800">
+        <strong>No RBAC on this resource type.</strong>
+        <span id="no-rbac-warning-name"></span> has no <code>access</code> block in its lifecycle —
+        all authenticated users can already fire any transition.
+        Role assignments for this type would be stored but never enforced.
       </div>
 
+      <script>
+        (function() {
+          var resourceSelect = document.getElementById('role_assignment_resource_type');
+          var roleField      = document.getElementById('role-name-field');
+          var roleHint       = document.getElementById('role-name-hint');
+          var warning        = document.getElementById('no-rbac-warning');
+          var warningName    = document.getElementById('no-rbac-warning-name');
+          var rolesByType    = JSON.parse(resourceSelect.dataset.roles || '{}');
+
+          // Looked up lazily — the submit button appears after this script tag in the DOM.
+          function submitBtn() { return document.getElementById('role-grant-submit'); }
+
+          function currentRoleInput() {
+            return document.getElementById('role_assignment_role_name');
+          }
+
+          function allRoles() {
+            return Object.values(rolesByType).flat()
+              .filter(function(v, i, a) { return a.indexOf(v) === i; })
+              .sort();
+          }
+
+          function buildSelect(roles, inputName, inputClass) {
+            var sel = document.createElement('select');
+            sel.id        = 'role_assignment_role_name';
+            sel.name      = inputName;
+            sel.className = inputClass;
+            var blank = document.createElement('option');
+            blank.value = '';
+            blank.textContent = '— Select a role —';
+            sel.appendChild(blank);
+            roles.forEach(function(rn) {
+              var opt = document.createElement('option');
+              opt.value = rn;
+              opt.textContent = ':' + rn;
+              sel.appendChild(opt);
+            });
+            return sel;
+          }
+
+          function replaceInput(newEl) {
+            var old = currentRoleInput();
+            old.parentNode.replaceChild(newEl, old);
+          }
+
+          function setNoRbac(typeName) {
+            roleField.classList.add('hidden');
+            warning.classList.remove('hidden');
+            warningName.textContent = ' ' + typeName;
+            var btn = submitBtn();
+            if (btn) {
+              btn.disabled = true;
+              btn.classList.add('opacity-50', 'cursor-not-allowed');
+              btn.classList.remove('hover:bg-gray-700', 'cursor-pointer');
+            }
+          }
+
+          function clearNoRbac() {
+            roleField.classList.remove('hidden');
+            warning.classList.add('hidden');
+            warningName.textContent = '';
+            var btn = submitBtn();
+            if (btn) {
+              btn.disabled = false;
+              btn.classList.remove('opacity-50', 'cursor-not-allowed');
+              btn.classList.add('hover:bg-gray-700', 'cursor-pointer');
+            }
+          }
+
+          resourceSelect.addEventListener('change', function() {
+            var selectedType = resourceSelect.value;
+            var old          = currentRoleInput();
+            var inputName    = old.name;
+            var inputClass   = old.className;
+            var roles        = rolesByType[selectedType];
+
+            if (!selectedType) {
+              clearNoRbac();
+              replaceInput(buildSelect(allRoles(), inputName, inputClass));
+              roleHint.innerHTML = 'Must match a role declared in the lifecycle <code>access</code> block.';
+            } else if (roles && roles.length > 0) {
+              clearNoRbac();
+              replaceInput(buildSelect(roles, inputName, inputClass));
+              roleHint.textContent = roles.length + ' role' + (roles.length !== 1 ? 's' : '') +
+                ' available for ' + selectedType.split('::').pop() + '.';
+            } else {
+              setNoRbac(selectedType.split('::').pop());
+            }
+          });
+        })();
+      </script>
+
       <div class="flex items-center gap-3 pt-2">
         <%= f.submit "Grant Role",
+            id: "role-grant-submit",
             class: "bg-gray-900 text-white text-sm px-4 py-2 rounded hover:bg-gray-700 cursor-pointer" %>
         <%= link_to "Cancel", fosm.admin_roles_path,
             class: "text-sm text-gray-500 hover:underline" %>

data/app/views/layouts/fosm/application.html.erb

@@ -19,10 +19,12 @@
         <nav class="p-3 space-y-1 flex-1">
           <%= link_to "Dashboard",   fosm.admin_root_path,        class: "block px-3 py-2 rounded text-sm text-gray-700 hover:bg-gray-100" %>
           <%= link_to "Transitions", fosm.admin_transitions_path, class: "block px-3 py-2 rounded text-sm text-gray-700 hover:bg-gray-100" %>
+          <%= link_to "Roles",       fosm.admin_roles_path,       class: "block px-3 py-2 rounded text-sm text-gray-700 hover:bg-gray-100" %>
           <%= link_to "Webhooks",    fosm.admin_webhooks_path,    class: "block px-3 py-2 rounded text-sm text-gray-700 hover:bg-gray-100" %>
         </nav>
-        <div class="p-3 border-t border-gray-100">
-          <%= link_to "Settings", fosm.admin_settings_path, class: "block px-3 py-2 rounded text-sm text-gray-500 hover:bg-gray-100" %>
+        <div class="p-3 border-t border-gray-100 space-y-1">
+          <%= link_to "Settings",     fosm.admin_settings_path,         class: "block px-3 py-2 rounded text-sm text-gray-500 hover:bg-gray-100" %>
+          <%= link_to "Data Archival", fosm.admin_data_retention_index_path, class: "block px-3 py-2 rounded text-sm text-gray-500 hover:bg-gray-100" %>
         </div>
       </div>
 

data/config/routes.rb

@@ -18,5 +18,11 @@ Fosm::Engine.routes.draw do
       end
     end
     resource :settings,    only: [ :show ]
+    resources :data_retention, only: [ :index, :show ] do
+      member do
+        post :purge_record
+        post :purge_all_expired
+      end
+    end
   end
 end

data/lib/fosm/configuration.rb

@@ -1,4 +1,8 @@
 module Fosm
+  # Default data retention period in days (10 years).
+  # Override per-project via: config.data_retention_days = 2555  # 7 years
+  DATA_RETENTION_DEFAULT_DAYS = 3650
+
   class Configuration
     # The base controller class the engine's controllers will inherit from.
     # Set this to match your app's ApplicationController.
@@ -56,6 +60,15 @@ module Fosm
     #   config.webhooks_enabled = false
     attr_accessor :webhooks_enabled
 
+    # Data retention policy in days. Records in an archival terminal state
+    # (state name contains "archiv") with an `archived_at` timestamp older
+    # than this many days are eligible for purge from the Data Archival admin.
+    #
+    # Gem default: Fosm::DATA_RETENTION_DEFAULT_DAYS (3650 = 10 years).
+    # Override per-project in config/initializers/fosm.rb:
+    #   config.data_retention_days = 2555  # 7 years
+    attr_accessor :data_retention_days
+
     def initialize
       @base_controller          = "ApplicationController"
       @admin_authorize          = -> { true } # Override in initializer!
@@ -67,6 +80,7 @@ module Fosm
       @webhook_job_queue        = :default
       @transition_log_job_queue = :fosm_audit
       @webhooks_enabled         = true
+      @data_retention_days      = Fosm::DATA_RETENTION_DEFAULT_DAYS
     end
   end
 

data/lib/fosm/data_retention.rb

@@ -0,0 +1,160 @@
+module Fosm
+  # Service for discovering and managing FOSM objects under a data retention policy.
+  #
+  # == Eligibility criteria
+  #
+  # A model is "archival-eligible" when it satisfies BOTH of the following:
+  #   1. It has at least one *terminal* state whose name contains "archiv"
+  #      (case-insensitive — covers :archived, :archival, :archiviert, etc.)
+  #   2. Its database table has an `archived_at` datetime/timestamp column.
+  #
+  # == Retention window
+  #
+  # Driven by +Fosm.config.data_retention_days+ (default 3650 = 10 years).
+  # Records with a non-nil +archived_at+ older than the cutoff are
+  # "eligible for purge".
+  #
+  # == Audit-safety guarantee
+  #
+  # Purging a business record NEVER touches +fosm_transition_logs+. The audit
+  # trail is intentionally kept forever for compliance purposes. Only the
+  # source record (e.g. the Invoice or FaasAccount row) is deleted.
+  module DataRetention
+    class << self
+      # All registered FOSM model classes that meet both eligibility criteria.
+      #
+      # @return [Array<Class>]
+      def archival_eligible_models
+        Fosm::Registry.model_classes.select { |mc| archival_eligible?(mc) }
+      end
+
+      # Returns true when the model has an archival terminal state AND an
+      # `archived_at` column.
+      #
+      # @param model_class [Class]
+      # @return [Boolean]
+      def archival_eligible?(model_class)
+        has_archival_terminal_state?(model_class) && has_archived_at_column?(model_class)
+      end
+
+      # Returns true when at least one terminal state name includes "archiv".
+      #
+      # @param model_class [Class]
+      # @return [Boolean]
+      def has_archival_terminal_state?(model_class)
+        lifecycle = model_class.try(:fosm_lifecycle)
+        return false unless lifecycle
+        lifecycle.states.any? { |s| s.terminal? && s.name.to_s.downcase.include?("archiv") }
+      end
+
+      # Returns true when the model's table has an `archived_at` column.
+      #
+      # Rescues gracefully if the table doesn't exist yet (e.g. during migrations).
+      #
+      # @param model_class [Class]
+      # @return [Boolean]
+      def has_archived_at_column?(model_class)
+        model_class.column_names.include?("archived_at")
+      rescue => _e
+        false
+      end
+
+      # All archival terminal state names for the model (as strings).
+      #
+      # @param model_class [Class]
+      # @return [Array<String>]
+      def archival_states_for(model_class)
+        lifecycle = model_class.try(:fosm_lifecycle)
+        return [] unless lifecycle
+        lifecycle.states
+          .select { |s| s.terminal? && s.name.to_s.downcase.include?("archiv") }
+          .map { |s| s.name.to_s }
+      end
+
+      # The cutoff timestamp: records with `archived_at` before this moment are
+      # eligible for purge.
+      #
+      # @return [ActiveSupport::TimeWithZone]
+      def retention_cutoff_date
+        Fosm.config.data_retention_days.days.ago
+      end
+
+      # Total records currently in any archival terminal state, regardless of
+      # whether they have passed the retention window.
+      #
+      # @param model_class [Class]
+      # @return [Integer]
+      def total_in_archival_state(model_class)
+        states = archival_states_for(model_class)
+        return 0 if states.empty?
+        model_class.where(state: states).count
+      end
+
+      # Total records eligible for purge: in an archival state, with a non-nil
+      # `archived_at` older than the retention cutoff.
+      #
+      # @param model_class [Class]
+      # @return [Integer]
+      def total_eligible_for_purge(model_class)
+        eligible_scope(model_class).count
+      end
+
+      # Returns a paginated ActiveRecord relation of purge-eligible records,
+      # ordered oldest-first (most overdue first).
+      #
+      # Pagination is offset-based. Pages are 1-indexed.
+      #
+      # @param model_class [Class]
+      # @param page [Integer] 1-based page number (clamped to >= 1)
+      # @param per_page [Integer] max records per page
+      # @return [ActiveRecord::Relation]
+      def records_eligible_for_purge(model_class, page: 1, per_page: 50)
+        offset = ([page.to_i, 1].max - 1) * per_page
+        eligible_scope(model_class).offset(offset).limit(per_page)
+      end
+
+      # An unbounded scope of all purge-eligible records for use in batch jobs.
+      # Callers should use +find_each+ to avoid loading all rows into memory.
+      #
+      # @param model_class [Class]
+      # @return [ActiveRecord::Relation]
+      def all_eligible_for_purge(model_class)
+        eligible_scope(model_class)
+      end
+
+      # Returns true when a single record is safe to purge:
+      #
+      #   - Its class has an `archived_at` column (defensive belt-and-suspenders).
+      #   - +archived_at+ is not nil.
+      #   - +archived_at+ is strictly older than the retention cutoff.
+      #   - The record's current state is an archival terminal state.
+      #
+      # This is the *authoritative* pre-purge check. Always call this immediately
+      # before destroying, even when the controller already checked — the
+      # retention window or record state may have changed since the UI check.
+      #
+      # @param record [ActiveRecord::Base]
+      # @return [Boolean]
+      def safe_to_purge?(record)
+        return false unless record.class.column_names.include?("archived_at")
+        archived_at = record.archived_at
+        return false if archived_at.nil?
+        return false if archived_at >= retention_cutoff_date
+        archival_states_for(record.class).include?(record.state.to_s)
+      end
+
+      private
+
+      # Shared base scope for eligibility queries.
+      def eligible_scope(model_class)
+        states = archival_states_for(model_class)
+        return model_class.none if states.empty?
+        model_class
+          .where(state: states)
+          .where.not(archived_at: nil)
+          .where("archived_at < ?", retention_cutoff_date)
+          .order(archived_at: :asc)
+      end
+    end
+  end
+end

data/lib/fosm/engine.rb

@@ -114,23 +114,22 @@ module Fosm
       end
     end
 
-    # Auto-register all Fosm models with the registry after app loads.
+    # Re-register all Fosm models after every code reload (development) and
+    # once at boot (all environments).  to_prepare fires on every reload in
+    # development, and once in production/test — making the registry always
+    # consistent with the currently-loaded class objects.
     # Use ::Rails to avoid ambiguity with Fosm::Rails module.
-    config.after_initialize do
+    config.to_prepare do
       ::Rails.application.eager_load! if ::Rails.env.development? && !::Rails.application.config.eager_load
 
-      ObjectSpace.each_object(Class).select { |klass|
-        klass < ActiveRecord::Base &&
-          klass.name&.start_with?("Fosm::") &&
-          klass.respond_to?(:fosm_lifecycle) &&
-          klass.fosm_lifecycle.present?
-      }.each do |klass|
-        slug = klass.name.demodulize.underscore
-        Fosm::Registry.register(klass, slug: slug)
-      end
+      Fosm::Registry.clear!
+      Fosm::Registry.repopulate!
+    end
 
-      # Start the background flusher thread for the :buffered log strategy.
-      # Only starts in long-running server processes (not in test/rake/console tasks).
+    # Start the background flusher thread for the :buffered log strategy.
+    # Kept in after_initialize (runs once) so the thread is not re-spawned on
+    # every development reload.
+    config.after_initialize do
       if Fosm.config.transition_log_strategy == :buffered && !::Rails.env.test?
         Fosm::TransitionBuffer.start_flusher!
       end

data/lib/fosm/registry.rb

@@ -23,7 +23,13 @@ module Fosm
       end
 
       def model_classes
-        @registered.values
+        @registered.values.map { |klass| klass.name.constantize rescue klass }
+      end
+
+      def slug_for(model_class)
+        target_name = model_class.name
+        @registered.each { |slug, klass| return slug if klass.name == target_name }
+        nil
       end
 
       def slugs
@@ -33,6 +39,28 @@ module Fosm
       def each(&block)
         @registered.each(&block)
       end
+
+      # Remove all registered entries.
+      # Called by to_prepare in development so stale class references are
+      # replaced after Rails reloads the application code.
+      def clear!
+        @registered = {}
+      end
+
+      # Scan ObjectSpace for all ActiveRecord subclasses that include
+      # Fosm::Lifecycle and register them.  Calling this after clear! is
+      # equivalent to the boot-time registration that after_initialize performs.
+      def repopulate!
+        ObjectSpace.each_object(Class).select { |klass|
+          klass < ActiveRecord::Base &&
+            klass.name&.start_with?("Fosm::") &&
+            klass.respond_to?(:fosm_lifecycle) &&
+            klass.fosm_lifecycle.present?
+        }.each do |klass|
+          slug = klass.name.demodulize.underscore
+          register(klass, slug: slug)
+        end
+      end
     end
   end
 end

data/lib/fosm/version.rb

@@ -1,3 +1,3 @@
 module Fosm
-  VERSION = "0.2.3"
+  VERSION = "0.2.5"
 end

data/lib/fosm-rails.rb

@@ -6,6 +6,7 @@ require "fosm/registry"
 require "fosm/current"
 require "fosm/transition_buffer"
 require "fosm/lifecycle"
+require "fosm/data_retention"
 require "fosm/agent"
 require "fosm/engine"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fosm-rails
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.2.5
 platform: ruby
 authors:
 - Abhishek Parolkar
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-18 00:00:00.000000000 Z
+date: 2026-05-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -56,6 +56,7 @@ files:
 - app/controllers/fosm/admin/apps_controller.rb
 - app/controllers/fosm/admin/base_controller.rb
 - app/controllers/fosm/admin/dashboard_controller.rb
+- app/controllers/fosm/admin/data_retention_controller.rb
 - app/controllers/fosm/admin/roles_controller.rb
 - app/controllers/fosm/admin/settings_controller.rb
 - app/controllers/fosm/admin/transitions_controller.rb
@@ -66,6 +67,7 @@ files:
 - app/helpers/fosm/rails/application_helper.rb
 - app/jobs/fosm/access_event_job.rb
 - app/jobs/fosm/application_job.rb
+- app/jobs/fosm/data_retention_purge_job.rb
 - app/jobs/fosm/rails/application_job.rb
 - app/jobs/fosm/transition_log_job.rb
 - app/jobs/fosm/webhook_delivery_job.rb
@@ -79,6 +81,8 @@ files:
 - app/views/fosm/admin/agents/show.html.erb
 - app/views/fosm/admin/apps/show.html.erb
 - app/views/fosm/admin/dashboard/index.html.erb
+- app/views/fosm/admin/data_retention/index.html.erb
+- app/views/fosm/admin/data_retention/show.html.erb
 - app/views/fosm/admin/roles/index.html.erb
 - app/views/fosm/admin/roles/new.html.erb
 - app/views/fosm/admin/settings/show.html.erb
@@ -97,6 +101,7 @@ files:
 - lib/fosm/agent.rb
 - lib/fosm/configuration.rb
 - lib/fosm/current.rb
+- lib/fosm/data_retention.rb
 - lib/fosm/engine.rb
 - lib/fosm/errors.rb
 - lib/fosm/lifecycle.rb