fosm-rails 0.2.3 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50ac8659af44dfad52d33f333001e6b3b846cfbb635e56534366ca371631501a
-  data.tar.gz: 5d727e837eefe74fa85677199b6cbc78b7e3df28fe33f8275e4c8bd93900383b
+  metadata.gz: 41f74b1b8b8a51fde040030b20b00e076a302be054bb6f7a5cd7dff22201c889
+  data.tar.gz: 6030364793d6d6cd82ceef77f257c2998771d12108e433011e4c61e61eb4cf13
 SHA512:
-  metadata.gz: e3adb965398f95f843d6d58f39f6b1b54d6c0084c46761b0f30678c7484bf6ca6c4e182e21ce5504b391cf147d9495da4d0d1fcad3ec4992693d7129c40c80c0
-  data.tar.gz: 04e1e7595f6dc9c211d7eb923ef167e80d612fab71149f1b5624cc5cbffd46ed64f16d909efd8a4c4a418a4895ba02fba39926fd98f1bcb1a09a028b06e7ca3e
+  metadata.gz: 92649aff68edd9a5d932c3e674fe45628a08ab98334faa1a0477c464a0029671322ba643695461a3aef866d8f38fe3cf0304d23901b0c3a4c84bd2318276ae51
+  data.tar.gz: a9f6ba8159d2b61e2519c7758127149b5d83288c30f99ad715664ae632cfcde6f778c7944593e2b30d9773af7412fa5e52cafde06bf7b788af0c126b219afade

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/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/layouts/fosm/application.html.erb

@@ -21,8 +21,9 @@
           <%= 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 "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/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

data/lib/fosm/version.rb

@@ -1,3 +1,3 @@
 module Fosm
-  VERSION = "0.2.3"
+  VERSION = "0.2.4"
 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.4
 platform: ruby
 authors:
 - Abhishek Parolkar
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-18 00:00:00.000000000 Z
+date: 2026-05-03 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