orfeas_petri_flow 0.6.0

data/lib/petri_flow/workflow.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+module PetriFlow
+  # Base class for defining workflow Petri nets using a declarative DSL.
+  #
+  # @example Define a workflow
+  #   class RefundRequestWorkflow < PetriFlow::Workflow
+  #     workflow_name "RefundRequestWorkflow"
+  #
+  #     places :requested, :under_review, :approved, :rejected, :processed, :cancelled
+  #     initial_place :requested
+  #     terminal_places :rejected, :processed, :cancelled
+  #
+  #     transition :start_review, from: :requested, to: :under_review
+  #     transition :approve, from: :under_review, to: :approved
+  #     transition :reject, from: :requested, to: :rejected
+  #     transition :reject, from: :under_review, to: :rejected
+  #     transition :process, from: :approved, to: :processed
+  #     transition :cancel, from: :requested, to: :cancelled
+  #     transition :cancel, from: :under_review, to: :cancelled
+  #   end
+  #
+  class Workflow
+    class << self
+      attr_reader :defined_places, :defined_transitions, :defined_initial_place,
+                  :defined_terminal_places, :defined_workflow_name
+
+      # DSL: Set workflow name
+      # @param name [String] The name for this workflow
+      def workflow_name(name)
+        @defined_workflow_name = name
+      end
+
+      # DSL: Define places (states) in the workflow
+      # @param place_ids [Array<Symbol>] List of place identifiers
+      # Note: This also resets transitions to handle file reloading gracefully
+      def places(*place_ids)
+        @defined_places = place_ids.flatten.map(&:to_sym)
+        # Reset transitions when places are redefined (handles `load` being called multiple times)
+        @defined_transitions = []
+      end
+
+      # DSL: Set the initial place (starting state)
+      # @param place_id [Symbol] The initial place identifier
+      def initial_place(place_id)
+        @defined_initial_place = place_id.to_sym
+      end
+
+      # DSL: Set terminal places (end states)
+      # @param place_ids [Array<Symbol>] List of terminal place identifiers
+      def terminal_places(*place_ids)
+        @defined_terminal_places = place_ids.flatten.map(&:to_sym)
+      end
+
+      # DSL: Define a transition between places
+      #
+      # Supports three patterns:
+      # - Simple: `from: :a, to: :b` (one input, one output)
+      # - Fork: `from: :a, to: [:b, :c]` (one input, multiple outputs - parallel split)
+      # - Join: `from: [:a, :b], to: :c` (multiple inputs, one output - synchronization)
+      #
+      # @param name [Symbol] Transition name (e.g., :approve, :reject)
+      # @param from [Symbol, Array<Symbol>] Source place(s) - array for join pattern
+      # @param to [Symbol, Array<Symbol>] Target place(s) - array for fork pattern
+      # @param method [String] Optional method name for audit trail
+      # @param trigger [String] Optional trigger description
+      def transition(name, from:, to:, method: nil, trigger: nil)
+        @defined_transitions ||= []
+
+        # Normalize to arrays for uniform handling
+        from_places = Array(from).map(&:to_sym)
+        to_places = Array(to).map(&:to_sym)
+
+        # Generate unique ID based on all input places
+        transition_id = generate_transition_id(name, from_places.first)
+
+        @defined_transitions << {
+          id: transition_id,
+          name: name.to_sym,
+          from: from_places,
+          to: to_places,
+          method: method || "#{name}!",
+          trigger: trigger
+        }
+      end
+
+      # Hook called when a class inherits from Workflow
+      # Registers the subclass with the Registry
+      def inherited(subclass)
+        super
+        Registry.register(subclass) if defined?(Registry) && Registry.respond_to?(:register)
+      end
+
+      private
+
+      def generate_transition_id(name, from)
+        :"t_#{name}_from_#{from}"
+      end
+    end
+
+    attr_reader :net, :verification_results, :terminal_reachability
+
+    def initialize
+      @net = PetriFlow.create_net(name: workflow_name)
+      @verification_results = {}
+      @terminal_reachability = {}
+      build_net
+    end
+
+    # Get the workflow name
+    # @return [String] The workflow name
+    def workflow_name
+      self.class.defined_workflow_name || self.class.name
+    end
+
+    # Get a URL-safe identifier for this workflow
+    # @return [String] Underscored workflow name
+    def workflow_id
+      workflow_name.underscore.gsub("::", "_").gsub(/\s+/, "_")
+    end
+
+    # Build the Petri net from class definitions
+    def build_net
+      add_places
+      add_transitions
+    end
+
+    # Create initial marking (token distribution)
+    # @return [PetriFlow::Core::Marking] The initial marking
+    def initial_marking
+      tokens = self.class.defined_places.each_with_object({}) do |place, hash|
+        hash[place] = (place == self.class.defined_initial_place) ? 1 : 0
+      end
+      PetriFlow::Core::Marking.new(tokens)
+    end
+
+    # Reset net to initial state
+    def reset_to_initial!
+      @net.set_marking(initial_marking)
+    end
+
+    # Run full verification
+    # @return [Hash] Verification results
+    def verify!
+      reset_to_initial!
+      @verification_results = PetriFlow.verify(@net)
+      verify_terminal_reachability
+      @verification_results
+    end
+
+    # Export as Mermaid diagram
+    # @return [String] Mermaid diagram source
+    def to_mermaid
+      PetriFlow.visualize(@net, format: :mermaid)
+    end
+
+    # Export as DOT diagram
+    # @return [String] GraphViz DOT source
+    def to_dot
+      PetriFlow.visualize(@net, format: :dot)
+    end
+
+    # Run simulation
+    # @param steps [Integer] Number of simulation steps
+    # @param strategy [Symbol] Simulation strategy (:random, :priority, :least_used)
+    # @return [PetriFlow::Simulation::Trace] Simulation trace
+    def simulate(steps: 20, strategy: :random)
+      reset_to_initial!
+      simulator = PetriFlow::Simulation::Simulator.new(@net)
+      simulator.run(steps: steps, strategy: strategy)
+    end
+
+    private
+
+    def add_places
+      self.class.defined_places.each do |place_id|
+        initial_tokens = (place_id == self.class.defined_initial_place) ? 1 : 0
+        @net.add_place(
+          id: place_id,
+          name: place_id.to_s.titleize,
+          initial_tokens: initial_tokens
+        )
+      end
+    end
+
+    def add_transitions
+      self.class.defined_transitions.each do |transition|
+        @net.add_transition(
+          id: transition[:id],
+          name: transition[:method] || transition[:trigger] || transition[:name].to_s
+        )
+
+        # Handle fork pattern: multiple output places
+        # Handle join pattern: multiple input places
+        from_places = Array(transition[:from])
+        to_places = Array(transition[:to])
+
+        # Add input arcs (place → transition)
+        from_places.each do |place_id|
+          @net.add_arc(source_id: place_id, target_id: transition[:id])
+        end
+
+        # Add output arcs (transition → place)
+        to_places.each do |place_id|
+          @net.add_arc(source_id: transition[:id], target_id: place_id)
+        end
+      end
+    end
+
+    def verify_terminal_reachability
+      analyzer = PetriFlow::Verification::ReachabilityAnalyzer.new(@net, initial_marking)
+      analyzer.analyze
+
+      # Get all reachable markings
+      reachable_markings = analyzer.reachable_markings
+
+      self.class.defined_terminal_places&.each do |state|
+        # Check if ANY reachable marking has a token in this terminal place
+        # This correctly handles fork patterns where multiple places have tokens
+        @terminal_reachability[state] = reachable_markings.any? do |marking|
+          marking.tokens_at(state) > 0
+        end
+      end
+
+      reset_to_initial!
+    end
+  end
+end

data/lib/petri_flow.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/core_ext"
+require "matrix"
+require "securerandom"
+require "digest"
+require "set"
+
+require_relative "petri_flow/version"
+
+# Core Petri net components
+require_relative "petri_flow/core/place"
+require_relative "petri_flow/core/transition"
+require_relative "petri_flow/core/arc"
+require_relative "petri_flow/core/token"
+require_relative "petri_flow/core/marking"
+require_relative "petri_flow/core/net"
+
+# Colored Petri net extensions
+require_relative "petri_flow/colored/color"
+require_relative "petri_flow/colored/guard"
+require_relative "petri_flow/colored/arc_expression"
+require_relative "petri_flow/colored/colored_net"
+
+# Matrix analysis
+require_relative "petri_flow/matrix/crud_event_mapping"
+require_relative "petri_flow/matrix/correlation"
+require_relative "petri_flow/matrix/causation"
+require_relative "petri_flow/matrix/lineage"
+require_relative "petri_flow/matrix/reachability"
+require_relative "petri_flow/matrix/analyzer"
+
+# Visualization
+require_relative "petri_flow/visualization/graphviz"
+require_relative "petri_flow/visualization/mermaid"
+
+# Formal verification
+require_relative "petri_flow/verification/reachability_analyzer"
+require_relative "petri_flow/verification/boundedness_checker"
+require_relative "petri_flow/verification/liveness_checker"
+require_relative "petri_flow/verification/invariant_checker"
+
+# Simulation
+require_relative "petri_flow/simulation/simulator"
+require_relative "petri_flow/simulation/trace"
+
+# Export functionality
+require_relative "petri_flow/export"
+
+# Workflow base class and registry (always available)
+require_relative "petri_flow/registry"
+require_relative "petri_flow/workflow"
+require_relative "petri_flow/verification_runner"
+
+# Generators for creating workflows from state machines
+require_relative "petri_flow/generators/state_machine_adapter"
+require_relative "petri_flow/generators/adapters/state_machines_adapter"
+require_relative "petri_flow/generators/adapters/aasm_adapter"
+require_relative "petri_flow/generators/workflow_generator"
+
+# Load Rails integration if Rails is available
+require_relative "petri_flow/railtie" if defined?(Rails::Railtie)
+
+module PetriFlow
+  class Error < StandardError; end
+
+  class << self
+    # Rails configuration (set by Railtie)
+    attr_accessor :rails_config
+
+    # Create a new Petri net
+    def create_net(name: "PetriNet")
+      Core::Net.new(name: name)
+    end
+
+    # Create a new Colored Petri net
+    def create_colored_net(name: "ColoredPetriNet")
+      Colored::ColoredNet.new(name: name)
+    end
+
+    # Create a matrix analyzer
+    def create_analyzer
+      Matrix::Analyzer.new
+    end
+
+    # Quick visualization
+    def visualize(net, format: :dot)
+      case format
+      when :dot, :graphviz
+        Visualization::Graphviz.new(net).to_dot
+      when :mermaid
+        Visualization::Mermaid.new(net).to_mermaid
+      when :ascii
+        Visualization::Graphviz.new(net).to_ascii
+      else
+        raise Error, "Unknown visualization format: #{format}"
+      end
+    end
+
+    # Quick verification
+    #
+    # @param net [PetriFlow::Core::Net] The Petri net to verify
+    # @param initial_marking [PetriFlow::Core::Marking] Initial marking
+    # @param pt_abstraction [Boolean] Enable P/T abstraction (ignore guards)
+    #   Use true for full state-space exploration of colored nets.
+    #   Guards are treated as non-deterministic choice, which is sound
+    #   for structural properties (boundedness, liveness, reachability).
+    def verify(net, initial_marking: nil, pt_abstraction: false)
+      initial_marking ||= net.current_marking
+
+      reachability = Verification::ReachabilityAnalyzer.new(net, initial_marking, pt_abstraction: pt_abstraction)
+      reachability.analyze
+
+      boundedness = Verification::BoundednessChecker.new(net, reachability)
+      liveness = Verification::LivenessChecker.new(net, reachability)
+
+      {
+        reachability: reachability.report,
+        boundedness: boundedness.report,
+        liveness: liveness.report
+      }
+    end
+
+    # Quick simulation
+    def simulate(net, steps: 100, strategy: :random)
+      simulator = Simulation::Simulator.new(net)
+      simulator.run(steps: steps, strategy: strategy)
+    end
+
+    # Quick export
+    def export(net, format:, **options)
+      Export.export(net, format: format, **options)
+    end
+
+    # Save net to file
+    def save(net, filename, format: nil, **options)
+      Export.save(net, filename, format: format, **options)
+    end
+
+    # Version info
+    def version
+      VERSION
+    end
+
+    # Gem info
+    def info
+      {
+        name: "PetriFlow",
+        version: VERSION,
+        description: "Petri Net and Matrix Analysis for Event Sourcing",
+        components: {
+          core: "Basic Petri nets with places, transitions, arcs",
+          colored: "Colored Petri nets with guards and arc expressions",
+          matrix: "Matrix analysis for CRUD-Event mapping, causation, lineage",
+          visualization: "GraphViz, Mermaid, and ASCII visualization",
+          verification: "Reachability, boundedness, liveness, invariants",
+          simulation: "Monte Carlo simulation and trace analysis",
+          export: "PNML, CPN Tools XML, JSON, and YAML export formats"
+        }
+      }
+    end
+  end
+end

metadata

@@ -0,0 +1,174 @@
+--- !ruby/object:Gem::Specification
+name: orfeas_petri_flow
+version: !ruby/object:Gem::Version
+  version: 0.6.0
+platform: ruby
+authors:
+- Michail Pantelelis
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: matrix
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: minitest-reporters
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+description: A comprehensive gem for Petri net modeling, colored Petri nets, matrix
+  analysis, visualization, and formal verification for event sourcing and CRUD-to-Event
+  mapping analysis. Part of the ORFEAS (Object-Relational to Event-Sourcing Architecture)
+  framework.
+email:
+- mpantel@aegean.gr
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/petri_flow.rb
+- lib/petri_flow/colored/arc_expression.rb
+- lib/petri_flow/colored/color.rb
+- lib/petri_flow/colored/colored_net.rb
+- lib/petri_flow/colored/guard.rb
+- lib/petri_flow/core/arc.rb
+- lib/petri_flow/core/marking.rb
+- lib/petri_flow/core/net.rb
+- lib/petri_flow/core/place.rb
+- lib/petri_flow/core/token.rb
+- lib/petri_flow/core/transition.rb
+- lib/petri_flow/export.rb
+- lib/petri_flow/export/cpn_tools_exporter.rb
+- lib/petri_flow/export/json_exporter.rb
+- lib/petri_flow/export/pnml_exporter.rb
+- lib/petri_flow/export/yaml_exporter.rb
+- lib/petri_flow/generators/adapters/aasm_adapter.rb
+- lib/petri_flow/generators/adapters/state_machines_adapter.rb
+- lib/petri_flow/generators/state_machine_adapter.rb
+- lib/petri_flow/generators/workflow_generator.rb
+- lib/petri_flow/matrix/analyzer.rb
+- lib/petri_flow/matrix/causation.rb
+- lib/petri_flow/matrix/correlation.rb
+- lib/petri_flow/matrix/crud_event_mapping.rb
+- lib/petri_flow/matrix/lineage.rb
+- lib/petri_flow/matrix/reachability.rb
+- lib/petri_flow/railtie.rb
+- lib/petri_flow/registry.rb
+- lib/petri_flow/simulation/simulator.rb
+- lib/petri_flow/simulation/trace.rb
+- lib/petri_flow/tasks/petri_flow.rake
+- lib/petri_flow/verification/boundedness_checker.rb
+- lib/petri_flow/verification/invariant_checker.rb
+- lib/petri_flow/verification/liveness_checker.rb
+- lib/petri_flow/verification/reachability_analyzer.rb
+- lib/petri_flow/verification_runner.rb
+- lib/petri_flow/version.rb
+- lib/petri_flow/visualization/graphviz.rb
+- lib/petri_flow/visualization/mermaid.rb
+- lib/petri_flow/workflow.rb
+homepage: https://github.com/mpantel/lyra-engine/gems/petri-flow
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/mpantel/lyra-engine/gems/petri-flow
+  source_code_uri: https://github.com/mpantel/lyra-engine/gems/petri-flow/tree/main/gems/petri_flow
+  changelog_uri: https://github.com/mpantel/lyra-engine/gems/petri-flow/blob/main/gems/petri_flow/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Petri Net and Matrix Analysis for ORFEAS Framework
+test_files: []