orfeas_lyra 0.6.0 → 0.9.0

data/app/controllers/lyra/application_controller.rb

@@ -3,6 +3,12 @@ module Lyra
     # Base controller for Lyra engine
     protect_from_forgery with: :exception, unless: -> { request.format.json? }
 
+    # Every engine action is authorized first: the routes expose a data
+    # subject's personal data (privacy/subject, portable_export, gdpr_report,
+    # pii_inventory), so the dashboard fails closed. See
+    # Lyra::Configuration#dashboard_authorization.
+    before_action :authorize_lyra_dashboard!
+
     helper_method :pam_dsl_available?, :user_tracking_configured?, :petri_flow_available?
 
     # Check if PAM DSL is available for privacy features
@@ -19,5 +25,47 @@ module Lyra
     def user_tracking_configured?
       defined?(::Current) && ::Current.respond_to?(:user)
     end
+
+    private
+
+    # config.dashboard_authorization is evaluated with instance_exec on this
+    # controller, so its body may call the controller's methods directly,
+    # private ones included (request, session, cookies, params, and any
+    # helper on ActionController::Base, such as Devise's current_user). A
+    # proc taking an argument is also given the controller:
+    #
+    #   config.dashboard_authorization = ->(controller) { controller.current_user&.admin? }
+    #   config.dashboard_authorization = -> { session[:admin] == true }
+    #
+    # This controller inherits ActionController::Base, not the host's
+    # ApplicationController, so methods defined only there are not reachable.
+    #
+    # Truthy allows the request; falsy answers 403. Unset (nil), the dashboard
+    # is open only in the development and test environments.
+    def authorize_lyra_dashboard!
+      check = Lyra.config.dashboard_authorization
+
+      allowed =
+        if check.nil?
+          lyra_dashboard_open_by_default?
+        elsif check.arity.zero?
+          instance_exec(&check)
+        else
+          instance_exec(self, &check)
+        end
+
+      head :forbidden unless allowed
+    end
+
+    def lyra_dashboard_open_by_default?
+      return true if Rails.env.development? || Rails.env.test?
+
+      Rails.logger&.warn(
+        "[Lyra] Dashboard request refused (403): set config.dashboard_authorization " \
+        "in the Lyra initializer to allow access outside development and test, " \
+        "e.g. ->(controller) { controller.current_user&.admin? }"
+      )
+      false
+    end
   end
 end

data/app/controllers/lyra/dashboard_controller.rb

@@ -84,7 +84,6 @@ module Lyra
         @model_configs[model_class.name] = {
           event_prefix: config.event_prefix,
           aggregate_class: config.aggregate_class,
-          command_handler: config.command_handler,
           privacy_policy: config.privacy_policy
         }
       end

data/app/views/lyra/dashboard/projections.html.erb

@@ -286,10 +286,6 @@ end</code></pre>
               <dt>Aggregate Class</dt>
               <dd><code><%= config[:aggregate_class] %></code></dd>
             <% end %>
-            <% if config[:command_handler] %>
-              <dt>Command Handler</dt>
-              <dd><code><%= config[:command_handler] %></code></dd>
-            <% end %>
             <% if config[:privacy_policy] %>
               <dt>Privacy Policy</dt>
               <dd><code><%= config[:privacy_policy] %></code></dd>

data/app/views/lyra/dashboard/verification.html.erb

@@ -105,6 +105,12 @@
         </div>
         <div class="label">Deadlock Free</div>
       </div>
+      <div class="stat-card">
+        <div class="value <%= @summary[:bypass_covered] ? 'pass' : 'fail' %>">
+          <%= @summary[:bypass_covered] ? "✓" : "✗" %>
+        </div>
+        <div class="label">Bypass Writes Recorded</div>
+      </div>
     </div>
 
     <div class="recommendations" style="margin-top: 20px; margin-bottom: 20px;">
@@ -161,8 +167,8 @@
             <div class="value"><%= @lifecycle[:verification][:boundedness][:is_safe] ? "Yes" : "No" %></div>
           </div>
           <div class="property">
-            <div class="name">Deadlock Free</div>
-            <div class="value"><%= @lifecycle[:verification][:liveness][:deadlock_free] ? "Yes" : "No" %></div>
+            <div class="name">Deadlock Free (except at terminal)</div>
+            <div class="value"><%= @lifecycle[:verification][:liveness][:terminates_properly] ? "Yes" : "No" %></div>
           </div>
         </div>
 

data/app/workflows/es_async_mode_workflow.rb

@@ -1,80 +1,44 @@
 # frozen_string_literal: true
 # Auto-generated by Lyra::Verification::WorkflowGenerator
-# Generated at: 2026-01-04 17:33:03 UTC
-# Updated: Fork pattern for true async parallelism
+# Generated at: 2026-10-05 05:52:34 UTC
 
 # Event Sourcing Async Mode Workflow
-# Full event sourcing with asynchronous (non-blocking) projection
-#
-# Uses Petri net FORK pattern to model true parallelism:
-# After events are stored, a single fork transition places tokens in
-# BOTH response_returned AND job_processing simultaneously.
-# This correctly models async behavior where:
-# 1. Response returns immediately to caller (non-blocking)
-# 2. Background worker processes projection independently
+# The event is stored; a job projects it into the table after commit
 class EsAsyncModeWorkflow < PetriFlow::Workflow
   workflow_name "Event Sourcing Async Mode Workflow"
 
-  places :idle, :command_received, :aggregate_loading, :aggregate_loaded,
-         :command_applying, :events_generated, :events_storing, :events_stored,
-         :response_returned, :job_processing, :projecting_async, :projection_complete
+  places :idle, :command_built, :event_built, :event_applied, :event_stored, :response_returned, :job_enqueued, :projection_complete
   initial_place :idle
   terminal_places :response_returned, :projection_complete
 
-  # Command processing flow (sequential)
-  transition :receive_command,
+  transition :intercept_write,
              from: :idle,
-             to: :command_received,
-             trigger: "CommandHandler receives command"
+             to: :command_built,
+             trigger: "WriteHooks: a Lyra::Command (a create first reserves its id); the row write is withheld"
 
-  transition :load_aggregate,
-             from: :command_received,
-             to: :aggregate_loading,
-             trigger: "Load aggregate from event stream"
+  transition :build_event,
+             from: :command_built,
+             to: :event_built,
+             trigger: "Lyra::CommandHandler.handle: create_events"
 
-  transition :aggregate_ready,
-             from: :aggregate_loading,
-             to: :aggregate_loaded,
-             trigger: "Aggregate hydrated from events"
+  transition :apply_event,
+             from: :event_built,
+             to: :event_applied,
+             trigger: "aggregate.apply(event)"
 
-  transition :apply_command,
-             from: :aggregate_loaded,
-             to: :command_applying,
-             trigger: "Aggregate.apply(command)"
+  transition :store_event,
+             from: :event_applied,
+             to: :event_stored,
+             trigger: "after_* callback lyra_finalize_event_source: Lyra.append_events"
 
-  transition :generate_events,
-             from: :command_applying,
-             to: :events_generated,
-             trigger: "Domain events created"
-
-  transition :store_events,
-             from: :events_generated,
-             to: :events_storing,
-             trigger: "EventStore.append_to_stream"
-
-  transition :events_persisted,
-             from: :events_storing,
-             to: :events_stored,
-             trigger: "Events committed to store"
-
-  # FORK: Parallel split - one transition produces tokens in TWO places
-  # This models the async behavior where both happen simultaneously:
-  # - Response returns immediately to caller
-  # - Background job is enqueued for processing
   transition :async_fork,
-             from: :events_stored,
-             to: [:response_returned, :job_processing],
-             trigger: "Enqueue job & return response (parallel)"
-
-  # Background projection flow (runs independently after fork)
-  transition :project_async,
-             from: :job_processing,
-             to: :projecting_async,
-             trigger: "ModelProjection.apply (async)"
+             from: :event_stored,
+             to: [:response_returned, :job_enqueued],
+             trigger: "AsyncProjectionJob.perform_later, after commit"
 
-  transition :async_complete,
-             from: :projecting_async,
+  transition :project_row,
+             from: :job_enqueued,
              to: :projection_complete,
-             trigger: "Read model eventually consistent"
+             trigger: "AsyncProjectionJob writes the row from the event, under a per-stream lock"
 
 end

data/app/workflows/es_sync_mode_workflow.rb

@@ -1,64 +1,39 @@
 # frozen_string_literal: true
 # Auto-generated by Lyra::Verification::WorkflowGenerator
-# Generated at: 2026-01-04 17:33:03 UTC
+# Generated at: 2026-10-05 05:52:34 UTC
 
 # Event Sourcing Sync Mode Workflow
-# Full event sourcing with synchronous (blocking) projection
+# The event is stored, then projected into the table in the same transaction
 class EsSyncModeWorkflow < PetriFlow::Workflow
   workflow_name "Event Sourcing Sync Mode Workflow"
 
-  places :idle, :command_received, :aggregate_loading, :aggregate_loaded, :command_applying, :events_generated, :events_storing, :events_stored, :projecting_sync, :projection_complete, :completed
+  places :idle, :command_built, :event_built, :event_applied, :event_stored, :completed
   initial_place :idle
   terminal_places :completed
 
-  transition :receive_command,
+  transition :intercept_write,
              from: :idle,
-             to: :command_received,
-             trigger: "CommandHandler receives command"
-
-  transition :load_aggregate,
-             from: :command_received,
-             to: :aggregate_loading,
-             trigger: "Load aggregate from event stream"
-
-  transition :aggregate_ready,
-             from: :aggregate_loading,
-             to: :aggregate_loaded,
-             trigger: "Aggregate hydrated from events"
-
-  transition :apply_command,
-             from: :aggregate_loaded,
-             to: :command_applying,
-             trigger: "Aggregate.apply(command)"
-
-  transition :generate_events,
-             from: :command_applying,
-             to: :events_generated,
-             trigger: "Domain events created"
-
-  transition :store_events,
-             from: :events_generated,
-             to: :events_storing,
-             trigger: "EventStore.append_to_stream"
-
-  transition :events_persisted,
-             from: :events_storing,
-             to: :events_stored,
-             trigger: "Events committed to store"
-
-  transition :project_sync,
-             from: :events_stored,
-             to: :projecting_sync,
-             trigger: "ModelProjection.apply (synchronous)"
-
-  transition :sync_complete,
-             from: :projecting_sync,
-             to: :projection_complete,
-             trigger: "Read model updated"
-
-  transition :finalize,
-             from: :projection_complete,
+             to: :command_built,
+             trigger: "WriteHooks: a Lyra::Command (a create first reserves its id); the row write is withheld"
+
+  transition :build_event,
+             from: :command_built,
+             to: :event_built,
+             trigger: "Lyra::CommandHandler.handle: create_events"
+
+  transition :apply_event,
+             from: :event_built,
+             to: :event_applied,
+             trigger: "aggregate.apply(event)"
+
+  transition :store_event,
+             from: :event_applied,
+             to: :event_stored,
+             trigger: "after_* callback lyra_finalize_event_source: Lyra.append_events"
+
+  transition :project_row,
+             from: :event_stored,
              to: :completed,
-             trigger: "Response returned to caller"
+             trigger: "synchronous projection writes the row from the event"
 
 end

data/app/workflows/hijack_mode_workflow.rb

@@ -1,54 +1,39 @@
 # frozen_string_literal: true
 # Auto-generated by Lyra::Verification::WorkflowGenerator
-# Generated at: 2026-01-04 17:33:03 UTC
+# Generated at: 2026-10-05 05:52:34 UTC
 
 # Hijack Mode Workflow
-# Intercepts CRUD operations and converts to event sourcing
+# The event is built and stored before the row, which is written from it
 class HijackModeWorkflow < PetriFlow::Workflow
   workflow_name "Hijack Mode Workflow"
 
-  places :idle, :crud_intercepted, :command_created, :command_validating, :command_valid, :event_created, :event_stored, :projecting, :completed
+  places :idle, :command_built, :event_built, :event_applied, :event_stored, :completed
   initial_place :idle
   terminal_places :completed
 
-  transition :intercept_crud,
+  transition :intercept_write,
              from: :idle,
-             to: :crud_intercepted,
-             trigger: "before_* callback intercepts operation"
+             to: :command_built,
+             trigger: "WriteHooks, after the model's before_* callbacks: a Lyra::Command (a create first reserves its id)"
 
-  transition :create_command,
-             from: :crud_intercepted,
-             to: :command_created,
-             trigger: "Convert CRUD to Lyra::Command"
+  transition :build_event,
+             from: :command_built,
+             to: :event_built,
+             trigger: "Lyra::CommandHandler.handle: create_events"
 
-  transition :validate_command,
-             from: :command_created,
-             to: :command_validating,
-             trigger: "CommandHandler.validate"
-
-  transition :command_passes,
-             from: :command_validating,
-             to: :command_valid,
-             trigger: "Validation passes"
-
-  transition :emit_event,
-             from: :command_valid,
-             to: :event_created,
-             trigger: "CommandHandler.execute creates event"
+  transition :apply_event,
+             from: :event_built,
+             to: :event_applied,
+             trigger: "aggregate.apply(event): the event joins the aggregate's pending events"
 
   transition :store_event,
-             from: :event_created,
+             from: :event_applied,
              to: :event_stored,
-             trigger: "RailsEventStore.publish"
+             trigger: "aggregate.store: Lyra.append_events"
 
-  transition :project_state,
+  transition :write_row,
              from: :event_stored,
-             to: :projecting,
-             trigger: "Projection.apply(event)"
-
-  transition :projection_complete,
-             from: :projecting,
              to: :completed,
-             trigger: "Model state updated from event"
+             trigger: "ActiveRecord writes the row with the event's attributes"
 
 end

data/app/workflows/lifecycle_workflow.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 # Auto-generated by Lyra::Verification::WorkflowGenerator
-# Generated at: 2026-01-04 17:33:03 UTC
+# Generated at: 2026-10-05 05:52:34 UTC
 
 # CRUD Entity Lifecycle (Generated)
 class LifecycleWorkflow < PetriFlow::Workflow

data/app/workflows/monitor_mode_workflow.rb

@@ -1,39 +1,29 @@
 # frozen_string_literal: true
 # Auto-generated by Lyra::Verification::WorkflowGenerator
-# Generated at: 2026-01-04 17:33:03 UTC
+# Generated at: 2026-10-05 05:52:34 UTC
 
 # Monitor Mode Workflow
-# Passively observes CRUD operations without modification
+# The row is written as usual; the event follows in the same transaction
 class MonitorModeWorkflow < PetriFlow::Workflow
   workflow_name "Monitor Mode Workflow"
 
-  places :idle, :crud_executing, :crud_completed, :event_building, :event_publishing, :completed
+  places :idle, :row_written, :event_built, :completed
   initial_place :idle
   terminal_places :completed
 
-  transition :receive_crud,
+  transition :write_row,
              from: :idle,
-             to: :crud_executing,
-             trigger: "ActiveRecord callback triggered"
-
-  transition :crud_success,
-             from: :crud_executing,
-             to: :crud_completed,
-             trigger: "CRUD operation completes successfully"
+             to: :row_written,
+             trigger: "ActiveRecord writes the row"
 
   transition :build_event,
-             from: :crud_completed,
-             to: :event_building,
-             trigger: "Extract changes from model"
-
-  transition :publish_event,
-             from: :event_building,
-             to: :event_publishing,
-             trigger: "Lyra::Event.publish"
+             from: :row_written,
+             to: :event_built,
+             trigger: "after_* callback: CrudInterceptor#publish_event builds it (Lyra::DomainEvents.build)"
 
-  transition :store_event,
-             from: :event_publishing,
+  transition :append_event,
+             from: :event_built,
              to: :completed,
-             trigger: "RailsEventStore.publish"
+             trigger: "Lyra.append_events, in a savepoint of the same transaction"
 
 end

data/config/privacy_policies.rb

@@ -110,9 +110,9 @@ PamDsl.define_policy :university_system do
   purpose :communication do
     describe "Important academic and administrative communications"
     basis :legitimate_interests
+    lia_documented!
     requires :email
     optionally :phone, :name
-    meta :balancing_test_performed, true
   end
 
   purpose :academic_records do
@@ -140,6 +140,7 @@ PamDsl.define_policy :university_system do
   purpose :analytics do
     describe "Improving educational services and user experience"
     basis :legitimate_interests
+    lia_documented!
     requires :student_id
     meta :anonymization_applied, true
   end

data/config/routes.rb

@@ -1,6 +1,8 @@
 Lyra::Engine.routes.draw do
-  # Root redirect to dashboard
-  root to: redirect('/lyra/dashboard')
+  # Root redirect to dashboard, relative to wherever the engine is mounted:
+  # Rails prefixes a relative redirect path with the request's script name
+  # (the mount point), so /admin/lyra goes to /admin/lyra/dashboard.
+  root to: redirect('dashboard')
 
   # Dashboard routes
   get 'dashboard', to: 'dashboard#index'

data/lib/lyra/access_log.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Lyra
+  # Records every access the privacy policy validates (PAM's
+  # validate_access!) as an event, when config.record_access_events is on:
+  # who accessed which declared attributes of which subject, for which
+  # purpose under which legal basis, and whether it was granted.
+  #
+  # - DataAccessed: the access went ahead, outcome "granted", or "audited"
+  #   when audit mode let it through despite violations (listed).
+  # - DataAccessDenied: strict mode refused it (violations listed).
+  #
+  # Each goes to the subject's access stream, Lyra::DataAccess$<subject>
+  # (Lyra::DataAccess$Registration$5 for a record), never to the record's
+  # own stream, so replay, DualView and mode transitions do not see it.
+  # Field names only, never values.
+  #
+  # Who accessed goes in the metadata: user_id (Current.user) and
+  # ip_address (Current.ip_address) when the application keeps them in
+  # Current, request and correlation ids, and whatever
+  # config.access_metadata_proc returns for the access (a console, a job,
+  # an API token: anything Current does not know). Without either, an
+  # access carries no user: set one.
+  #
+  # Every access is recorded, with no sampling. An access that cannot be
+  # recorded does not go ahead: the store's error propagates from
+  # validate_access!. Off by default, and nothing is recorded in disabled
+  # mode: reads can outnumber writes by orders of magnitude, so its cost is
+  # measured separately (LYRA_RECORD_ACCESS=1 in the Aegean testbed).
+  #
+  # The Article 30 record of processing does not depend on it: PAM's
+  # reporter generates that from the declared policy. The access log is
+  # the evidence of what was actually accessed.
+  module AccessLog
+    STREAM = "Lyra::DataAccess"
+
+    class << self
+      # PamDsl.access_recorder protocol.
+      def record?(_policy)
+        Lyra.config.record_access_events && !Lyra.config.disabled_mode?
+      end
+
+      def call(access)
+        event_class = access.outcome == :denied ? Lyra::Events::DataAccessDenied : Lyra::Events::DataAccessed
+        subject = subject_key(access.subject)
+        event = event_class.new(data: data_for(access, subject), metadata: metadata(access))
+        Lyra.append_events(event, stream_name: stream_for(subject))
+      end
+
+      def stream_for(subject)
+        subject ? "#{STREAM}$#{subject}" : STREAM
+      end
+
+      # "Registration$5" for a record, the value itself for an id.
+      def subject_key(subject)
+        case subject
+        when nil then nil
+        when ActiveRecord::Base then Lyra.stream_name(subject.class, subject.id)
+        else subject.to_s
+        end
+      end
+
+      # The accesses recorded for +subject+ (a record or an id), oldest first.
+      def for(subject)
+        Lyra.config.event_store.read.stream(stream_for(subject_key(subject))).to_a
+      end
+
+      private
+
+      def data_for(access, subject)
+        data = {
+          policy: access.policy.to_s,
+          purpose: access.purpose.to_s,
+          legal_basis: access.legal_basis&.to_s,
+          fields: access.fields.map(&:to_s),
+          subject: subject,
+          outcome: access.outcome.to_s,
+          accessed_at: access.at
+        }
+        if access.violations.any?
+          data[:violations] = access.violations.map { |error| { error: error.class.name, message: error.message } }
+        end
+        data
+      end
+
+      def metadata(access)
+        {
+          user_id: current(:user)&.id,
+          ip_address: current(:ip_address),
+          request_id: current(:request_id),
+          correlation_id: Lyra::Correlation.current_id,
+          causation_id: Lyra::Causation.current_id
+        }.merge(custom_metadata(access)).merge(source: "lyra_access_log").compact
+      end
+
+      def current(attribute)
+        defined?(::Current) && ::Current.respond_to?(attribute) ? ::Current.public_send(attribute) : nil
+      end
+
+      # config.access_metadata_proc's hash, with symbol keys. A failing proc
+      # is logged and skipped: the access is still recorded, without it.
+      def custom_metadata(access)
+        proc = Lyra.config.access_metadata_proc
+        return {} unless proc
+
+        result = proc.call(access)
+        result.is_a?(Hash) ? result.transform_keys(&:to_sym) : {}
+      rescue => e
+        Rails.logger.warn("Lyra: access_metadata_proc failed - #{e.message}")
+        {}
+      end
+    end
+  end
+
+  module Events
+    class DataAccessed < Lyra::Event; end
+    class DataAccessDenied < Lyra::Event; end
+  end
+end
+
+PamDsl.access_recorder = Lyra::AccessLog if defined?(PamDsl) && PamDsl.respond_to?(:access_recorder=)

data/lib/lyra/advisory_lock.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Lyra
+  # A PostgreSQL transaction-level advisory lock, released at commit. Genesis,
+  # ES-Lazy's catch-up and ES-Async's per-stream projection take one so that
+  # several processes running them at once never do the same work twice.
+  #
+  # SQLite needs none: it serialises writers. Other adapters have no such lock
+  # here, so the call does nothing there and warns once per purpose, since
+  # those paths are then safe in a single process only.
+  module AdvisoryLock
+    @warned = {}
+
+    class << self
+      # Returns true when a lock was taken, false otherwise.
+      def xact_lock(connection, key, purpose:)
+        adapter = connection.adapter_name
+        if adapter.match?(/postgres/i)
+          connection.execute("SELECT pg_advisory_xact_lock(hashtext(#{connection.quote(key)}))")
+          return true
+        end
+
+        warn_once(adapter, purpose) unless adapter.match?(/sqlite/i)
+        false
+      end
+
+      # Forget which purposes have warned (tests).
+      def reset_warnings!
+        @warned = {}
+      end
+
+      private
+
+      def warn_once(adapter, purpose)
+        return if @warned[purpose]
+
+        @warned[purpose] = true
+        logger = defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        message = "Lyra: #{purpose} runs without a lock on #{adapter} (only PostgreSQL has the " \
+                  "advisory lock Lyra uses); it is safe in a single process only"
+        logger ? logger.warn(message) : Kernel.warn(message)
+      end
+    end
+  end
+end