orfeas_petri_flow 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c5a34cd217d871bd070846e941ca8d8b50f82cd4711e6bb6cc9f5380fdbefea5
-  data.tar.gz: 288f20a6d9edb8ddbc3a6bb763e9fefce9b28146c4aec4cd7edad026c9e352dc
+  metadata.gz: 72c3710503d8edda7e6e26f9272e57f3a8446f59df0f4abefa63e7153bce2c4d
+  data.tar.gz: dc3293f07ee62eeed5dfba86037f7eaa04be50e00a101b5aa0d88853e371eaff
 SHA512:
-  metadata.gz: 693dff90c3b1e3e7a1487c3f9cf515d27e54035cf826d154b7cd3d5e67a60d7107f3b5b7f1f0dbe026af04100c97a0e20667107fc54e5fbccf992e1d28ae4589
-  data.tar.gz: 70112373f5043dfae1c1b44e1050416a37fb8ec45e637ad77ffc22a50a2d19cb58ce3c575ee3bd5dd803d80afec5f34c9a49318ab67bf5ca9d75de34eec153c8
+  metadata.gz: 93f9fde29280050100fc099baa016a39ff29a8765eab84269503eaf7d7cd14c20953421cd6efd0555504d4ae126b57bfc815bd427a7963ff6af21f8072350822
+  data.tar.gz: 4fd31d7d6ee40d4c8065cc0638b19b528cc03ac0bd922e7b597c44579e2ea154c8c61c28eae3587104e677571f75ecf46f1ddcb3429fb4c34e4f109adec2ce57

data/CHANGELOG.md

@@ -4,6 +4,30 @@ All notable changes to the PetriFlow gem will be documented in this file.
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-10-10
+
+### Added
+- **Terminal-aware deadlock-freedom** — `PetriFlow.verify` and `Verification::LivenessChecker`
+  take `terminal_places:`. The liveness report adds `terminal_places`, `terminates_properly`
+  (no reachable dead marking outside the terminal places) and `improper_dead_markings` (the
+  count of those that remain). The raw `deadlock_free`, which counts the intended end of a net
+  as a deadlock, is unchanged. `Workflow#verify!` now passes the workflow's `terminal_places`.
+  First liveness tests for the gem.
+
+### Changed
+- **Ruby 4.0 or later is required** (`required_ruby_version >= 4.0`; none was declared before).
+
+### Fixed
+- **`PetriFlow.verify` left the net in the marking its checks ended in** — the liveness and
+  reachability checks fire transitions on the net they are given; `verify` now restores the
+  marking the net had when it was called.
+- **Undeclared `rexml` dependency** — the PNML and CPN Tools exporters `require "rexml/document"`,
+  but the gemspec did not declare `rexml`, which has not been a default gem since Ruby 3.4.
+  Requiring `petri_flow` then failed with a `LoadError` part-way through, which Lyra rescued
+  as "PetriFlow not installed", leaving `PetriFlow` half-defined (no `PetriFlow::Workflow`);
+  any app that eager-loads Lyra's `app/workflows` then failed to boot. `rexml` is now a
+  runtime dependency.
+
 ## [0.8.0] - 2026-08-09
 
 No changes since 0.6.0 apart from the gem's name (`orfeas_petri_flow`); released with Lyra and

data/README.md

@@ -17,7 +17,6 @@ PetriFlow is a Ruby gem that provides a complete toolkit for modeling, analyzing
 - **Token Colors**: Typed tokens carrying structured data
 - **Guards**: Conditional transition firing (e.g., privacy policies)
 - **Arc Expressions**: Data transformations during transitions
-- **Hierarchical Nets**: Multi-level system modeling
 
 ### 📊 Matrix Analysis
 - **CRUD-Event Mapping Matrix**: Track which CRUD operations generate which events
@@ -29,7 +28,7 @@ PetriFlow is a Ruby gem that provides a complete toolkit for modeling, analyzing
 ### 🔍 Formal Verification
 - **Reachability Analysis**: What states are reachable?
 - **Boundedness Checking**: Are token counts bounded?
-- **Liveness Checking**: Can transitions fire? Deadlock detection
+- **Liveness Checking**: Can transitions fire? Deadlock detection, optionally relative to designated terminal places
 - **Invariant Checking**: Custom property verification
 
 ### 🎬 Simulation
@@ -48,9 +47,12 @@ PetriFlow is a Ruby gem that provides a complete toolkit for modeling, analyzing
 Add to your Gemfile:
 
 ```ruby
-gem 'petri_flow', path: 'gems/petri_flow'
+gem "orfeas_petri_flow", require: "petri_flow"
 ```
 
+The gem is published as `orfeas_petri_flow`; the library is required as
+`petri_flow`. It needs Ruby 4.0 or later.
+
 Then:
 ```bash
 bundle install
@@ -138,8 +140,8 @@ analyzer.analyze_events(events)
 # Get CRUD mapping
 puts analyzer.crud_mapping.to_table
 
-# Get data lineage
-lineage = analyzer.field_history("email")
+# Get data lineage (fields are keyed as given in :changes, here symbols)
+lineage = analyzer.field_history(:email)
 lineage.each do |mod|
   puts "#{mod[:timestamp]}: #{mod[:old_value]} → #{mod[:new_value]}"
 end
@@ -160,6 +162,13 @@ puts "Bounded: #{results[:boundedness][:is_bounded]}"
 puts "Safe: #{results[:boundedness][:is_safe]}"
 puts "Deadlock-free: #{results[:liveness][:deadlock_free]}"
 
+# deadlock_free counts every reachable dead marking as a deadlock, including
+# the intended end of the net. Pass terminal_places: to check deadlock-freedom
+# except at markings that mark one of those places.
+results = PetriFlow.verify(net, terminal_places: [:completed, :rejected])
+puts "Terminates properly: #{results[:liveness][:terminates_properly]}"
+puts "Improper dead markings: #{results[:liveness][:improper_dead_markings]}"
+
 # Custom invariants
 checker = PetriFlow::Verification::InvariantChecker.new(net)
 
@@ -222,6 +231,24 @@ ascii = PetriFlow.visualize(net, format: :ascii)
 puts ascii
 ```
 
+### Export
+
+Nets (plain and colored) can be exported to PNML, CPN Tools XML, JSON and YAML:
+
+```ruby
+pnml = PetriFlow.export(net, format: :pnml)
+cpn  = PetriFlow.export(net, format: :cpn)    # CPN Tools XML
+json = PetriFlow.export(net, format: :json)   # pretty: true by default
+yaml = PetriFlow.export(net, format: :yaml)
+
+# Write to a file; the format is detected from the extension
+# (.pnml, .cpn, .json, .yaml/.yml; .xml is PNML unless the name contains "cpn")
+PetriFlow.save(net, "order.pnml")
+PetriFlow.save(net, "order.xml", format: :cpn)
+```
+
+See [docs/PETRIFLOW_EXPORT.md](docs/PETRIFLOW_EXPORT.md) and `examples/export_example.rb`.
+
 ## Rails Integration: Workflow DSL
 
 PetriFlow includes a declarative DSL for defining workflows in Rails applications,
@@ -276,15 +303,38 @@ rake workflows:verify
 rake workflows:list
 ```
 
+### Generating Workflows from State Machines
+
+Models that use `aasm` or `state_machines-activerecord` can be turned into
+workflow classes:
+
+```bash
+# List models with a supported state machine
+rake petri_flow:generate:scan
+
+# Write app/workflows/order_workflow.rb from Order's state machine
+# (state attribute defaults to :state), then verify it
+rake petri_flow:generate:from_state_machine[Order,state]
+
+# Aliases
+rake workflows:scan
+rake workflows:from_state_machine[Order,state]
+```
+
+`Workflow#verify!` passes the workflow's `terminal_places` to `PetriFlow.verify`,
+so its results include `liveness[:terminates_properly]`.
+
 ### Generated Reports
 
 Reports are saved to `reports/petri_flow_<timestamp>/`:
 
 - `verification_report.md` - Summary of all workflows
-- `<workflow_name>.md` - Individual workflow report
-- `<workflow_name>_petri.png` - Petri net diagram
-- `<workflow_name>_petri.dot` - GraphViz source
-- `<workflow_name>_petri.mmd` - Mermaid diagram
+- `<workflow_id>.md` - Individual workflow report
+- `<workflow_id>_petri.dot` - GraphViz source
+- `<workflow_id>_petri.mmd` - Mermaid diagram
+- `<workflow_id>_petri.png`, `.pdf`, `.svg` - Petri net diagram (only when GraphViz's `dot` is installed)
+
+`<workflow_id>` is the underscored workflow name (`refund_request_workflow` for the example above).
 
 ### Configuration
 
@@ -337,15 +387,20 @@ class FlawedApprovalWorkflow < PetriFlow::Workflow
 end
 ```
 
-Running verification will detect this:
+Running verification (`rake petri_flow:verify`) will detect this:
 
 ```
-Terminal State Reachability:
-  completed    ✓ REACHABLE
-  rejected     ✓ REACHABLE
-  escalated    ✗ UNREACHABLE
+  Terminal State Reachability:
+    completed            ✓ REACHABLE
+    rejected             ✓ REACHABLE
+    escalated            ✗ UNREACHABLE
+```
+
+and the workflow's report is marked `✗ UNREACHABLE STATES DETECTED`, with:
 
-> WARNING: Some terminal states are unreachable from the initial state.
+```
+> **WARNING:** Some terminal states are unreachable from the initial state.
+> This indicates a workflow design issue that should be investigated.
 ```
 
 This is valuable for GDPR compliance - proving that the `anonymized` state IS reachable
@@ -418,20 +473,25 @@ end
 ### 3. Event Flow Analysis
 
 ```ruby
-# Build causation matrix from event store
+# Build causation matrix from events. Each event is a hash; causation is
+# recorded between event ids, from :event_id and :caused_by_event_id.
 analyzer = PetriFlow.create_analyzer
 
-events = EventStore.read_all_events
+events = [
+  { event_id: "order-created-1" },
+  { event_id: "invoice-issued-1", caused_by_event_id: "order-created-1" },
+  { event_id: "email-sent-1", caused_by_event_id: "invoice-issued-1" }
+]
 analyzer.analyze_events(events)
 
 # Find causation chain
-chain = analyzer.find_causation_chain("OrderCreated", "EmailSent")
+chain = analyzer.find_causation_chain("order-created-1", "email-sent-1")
 puts "Causation chain: #{chain.join(' → ')}"
 
 # Get transitive causation
 closure = analyzer.causation.transitive_closure
-puts "Events caused by OrderCreated (transitively):"
-puts closure.effects_of("OrderCreated")
+puts "Events caused by order-created-1 (transitively):"
+puts closure.effects_of("order-created-1")
 
 # Identify most influential events
 centrality = analyzer.causation.centrality_scores
@@ -473,28 +533,30 @@ puts "Total modifications: #{impact[:total_modifications]}"
 
 ## Architecture Integration with Lyra
 
+Lyra uses PetriFlow at verification time; PetriFlow enforces nothing while the
+application runs. Lyra builds Petri nets of its own write paths and hands them
+to PetriFlow for analysis:
+
 ```
-┌─────────────────────────────────────────────────┐
-│              Lyra Framework                     │
-│                                                 │
-│  ┌─────────────┐         ┌─────────────┐      │
-│  │   CRUD      │────────▶│   Events    │      │
-│  │ Operations  │         │   Store     │      │
-│  └─────────────┘         └──────┬──────┘      │
-│                                  │             │
-│                                  ▼             │
-│                          ┌──────────────┐     │
-│                          │  PetriFlow   │     │
-│                          │   Analysis   │     │
-│                          └──────────────┘     │
-│                                  │             │
-│            ┌─────────────────────┼──────────┐ │
-│            ▼                     ▼          ▼ │
-│     ┌──────────┐        ┌──────────┐  ┌──────────┐
-│     │ CPN      │        │ Matrix   │  │ Verify   │
-│     │ Model    │        │ Analysis │  │ Props    │
-│     └──────────┘        └──────────┘  └──────────┘
-└─────────────────────────────────────────────────┘
+┌──────────────────────────── Lyra ─────────────────────────────┐
+│                                                               │
+│  CRUD lifecycle and Create/Update/Destroy mode nets           │
+│  (Lyra::Verification::CrudLifecycleWorkflow and friends)      │
+│  Bypass-write net (Lyra::Verification::BypassWorkflow)        │
+│  Per-mode nets (Lyra::Verification::WorkflowGenerator,        │
+│  app/workflows/*_workflow.rb)                                 │
+│                                                               │
+└───────────────────────────────┬───────────────────────────────┘
+                                │ PetriFlow::Workflow nets
+                                ▼
+                 ┌────────────────────────────┐
+                 │         PetriFlow          │
+                 │ reachability, boundedness, │
+                 │ liveness, invariants,      │
+                 │ simulation, export         │
+                 └──────────────┬─────────────┘
+                                ▼
+  Lyra.verify_mapping!, rake lyra:workflows:verify, rake petri_flow:verify
 ```
 
 ## Research Foundation
@@ -552,14 +614,24 @@ It provides the formal verification foundation for the CRUD-to-Event mapping fra
 - `PetriFlow::Visualization::Graphviz` - DOT/GraphViz output
 - `PetriFlow::Visualization::Mermaid` - Mermaid diagrams
 
+### Export
+
+- `PetriFlow::Export` - `export` / `save` dispatch by format
+- `PetriFlow::Export::PnmlExporter`, `CpnToolsExporter`, `JsonExporter`, `YamlExporter`
+
+### Workflows
+
+- `PetriFlow::Workflow` - Declarative workflow DSL
+- `PetriFlow::Generators::WorkflowGenerator` - Workflow classes from AASM / state_machines
+
 ## Development
 
 ```bash
 # Install dependencies
 bundle install
 
-# Run tests
-bundle exec rspec
+# Run tests (Minitest)
+bundle exec rake test
 
 # Run examples
 ruby examples/crud_mapping_example.rb
@@ -587,6 +659,6 @@ MIT License. See MIT-LICENSE file.
   author={Pantelelis, Michail},
   year={2026},
   note={Part of ORFEAS PhD Thesis},
-  url={https://github.com/mpantel/lyra-engine/gems/petri-flow}
+  url={https://github.com/mpantel/lyra-engine/tree/main/gems/petri_flow}
 }
 ```

data/lib/petri_flow/verification/liveness_checker.rb

@@ -14,10 +14,13 @@ module PetriFlow
       # L3 (Potentially firable infinitely): Can fire infinitely
       # L4 (Live): Can always eventually fire
 
-      def initialize(net, reachability_analyzer = nil)
+      # terminal_places: places whose marking means the net finished rather
+      # than got stuck. See #terminates_properly?.
+      def initialize(net, reachability_analyzer = nil, terminal_places: [])
         @net = net
         @reachability_analyzer = reachability_analyzer ||
                                  ReachabilityAnalyzer.new(net)
+        @terminal_places = Array(terminal_places).map(&:to_sym)
       end
 
       # Check if transition is dead (L0)
@@ -51,6 +54,23 @@ module PetriFlow
         end
       end
 
+      # Deadlock-freedom relative to designated terminal places: a reachable
+      # marking in which no transition is enabled is a deadlock unless it
+      # marks at least one terminal place. deadlock_free? counts every dead
+      # marking, so it is false for any net that is meant to finish; with no
+      # terminal places the two agree.
+      def terminates_properly?
+        improper_dead_markings.empty?
+      end
+
+      # Reachable dead markings that mark no terminal place.
+      def improper_dead_markings
+        @reachability_analyzer.reachable_markings.select do |marking|
+          @net.set_marking(marking)
+          @net.deadlocked? && @terminal_places.none? { |place| marking.tokens_at(place).positive? }
+        end
+      end
+
       # Find dead transitions
       def dead_transitions
         @net.transitions.keys.select { |tid| dead?(tid) }
@@ -86,6 +106,9 @@ module PetriFlow
 
         {
           deadlock_free: deadlock_free?,
+          terminal_places: @terminal_places,
+          terminates_properly: terminates_properly?,
+          improper_dead_markings: improper_dead_markings.size,
           dead_transitions: classification.select { |_, v| v == :dead }.keys,
           live_transitions: classification.select { |_, v| v == :live }.keys,
           potentially_firable: classification.select { |_, v| v == :potentially_firable }.keys,

data/lib/petri_flow/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PetriFlow
-  VERSION = "0.8.0"
+  VERSION = "0.9.0"
 end

data/lib/petri_flow/workflow.rb

@@ -143,7 +143,7 @@ module PetriFlow
     # @return [Hash] Verification results
     def verify!
       reset_to_initial!
-      @verification_results = PetriFlow.verify(@net)
+      @verification_results = PetriFlow.verify(@net, terminal_places: self.class.defined_terminal_places || [])
       verify_terminal_reachability
       @verification_results
     end

data/lib/petri_flow.rb

@@ -106,20 +106,28 @@ module PetriFlow
     #   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
+    # @param terminal_places [Array<Symbol>] Places whose marking means the
+    #   net has finished; liveness[:terminates_properly] is deadlock-freedom
+    #   except at markings that mark one of them.
+    # The analysis fires transitions to explore the state space; the net's
+    # marking is restored afterwards, so verifying a net does not change it.
+    def verify(net, initial_marking: nil, pt_abstraction: false, terminal_places: [])
+      marking_before = net.current_marking
+      initial_marking ||= marking_before
 
       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)
+      liveness = Verification::LivenessChecker.new(net, reachability, terminal_places: terminal_places)
 
       {
         reachability: reachability.report,
         boundedness: boundedness.report,
         liveness: liveness.report
       }
+    ensure
+      net.set_marking(marking_before) if marking_before
     end
 
     # Quick simulation

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: orfeas_petri_flow
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Michail Pantelelis
@@ -37,6 +37,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.4'
+- !ruby/object:Gem::Dependency
+  name: rexml
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -147,13 +161,13 @@ files:
 - 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
+homepage: https://github.com/mpantel/lyra-engine/tree/main/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
+  homepage_uri: https://github.com/mpantel/lyra-engine/tree/main/gems/petri_flow
+  source_code_uri: https://github.com/mpantel/lyra-engine/tree/main/gems/petri_flow
+  changelog_uri: https://github.com/mpantel/lyra-engine/blob/main/gems/petri_flow/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib
@@ -161,7 +175,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '4.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="