phronomy 0.26.0 → 0.28.0

data/lib/phronomy/workflow/persistence/codec.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class Workflow
+    module Persistence
+      # Current-format record schemas and conversion for this domain.
+      # @api private
+      module Codec
+        extend Phronomy::Storage::RecordCodec
+
+        WORKFLOW_STATE_RECORD_TYPE = "phronomy.workflow_state"
+        WORKFLOW_STATE_FORMAT_VERSION = "0.1"
+        WORKFLOW_STATE_KEYS = %w[
+          workflow_instance_id workflow_revision snapshot
+        ].freeze
+
+        WORKFLOW_SNAPSHOT_KEYS = %w[fields phase].freeze
+
+        module_function
+
+        def encode_workflow_state(workflow_instance_id:, workflow_revision:, snapshot:)
+          normalized_snapshot = canonicalize_workflow_snapshot(snapshot)
+          validate_workflow_snapshot!(normalized_snapshot)
+          revision = Integer(workflow_revision)
+          unless revision.positive?
+            raise Phronomy::Storage::SerializationError,
+              "Workflow durable revision must be positive"
+          end
+
+          payload = {
+            "workflow_instance_id" => String(workflow_instance_id),
+            "workflow_revision" => revision,
+            "snapshot" => normalized_snapshot
+          }
+          validate_workflow_state_payload!(payload)
+          build_record(WORKFLOW_STATE_RECORD_TYPE, WORKFLOW_STATE_FORMAT_VERSION, payload)
+        rescue Phronomy::Storage::SerializationError
+          raise
+        rescue => error
+          serialization_error("cannot encode Workflow state", error)
+        end
+
+        def decode_workflow_state(record, expected_workflow_instance_id: nil)
+          payload = current_payload!(
+            record,
+            record_type: WORKFLOW_STATE_RECORD_TYPE,
+            format_version: WORKFLOW_STATE_FORMAT_VERSION,
+            keys: WORKFLOW_STATE_KEYS,
+            label: "Workflow state payload"
+          )
+          validate_workflow_state_payload!(payload)
+          workflow_instance_id = payload.fetch("workflow_instance_id")
+          if expected_workflow_instance_id &&
+              workflow_instance_id != expected_workflow_instance_id.to_s
+            raise Phronomy::Storage::SerializationError,
+              "Workflow state identity mismatch: #{workflow_instance_id.inspect} != " \
+              "#{expected_workflow_instance_id.to_s.inspect}"
+          end
+
+          {
+            snapshot: immutable_copy(payload.fetch("snapshot")),
+            revision: payload.fetch("workflow_revision")
+          }.freeze
+        rescue Phronomy::Storage::SerializationError
+          raise
+        rescue => error
+          serialization_error("cannot decode Workflow state", error)
+        end
+
+        def validate_workflow_state_payload!(payload)
+          validate_exact_keys!(payload, WORKFLOW_STATE_KEYS, label: "Workflow state payload")
+          require_nonempty_string!(payload, "workflow_instance_id", label: "Workflow state payload")
+          require_positive_integer!(payload, "workflow_revision", label: "Workflow state payload")
+          validate_workflow_snapshot!(payload.fetch("snapshot"))
+          payload
+        end
+
+        def validate_workflow_snapshot!(snapshot)
+          validate_exact_keys!(snapshot, WORKFLOW_SNAPSHOT_KEYS, label: "Workflow snapshot")
+          unless snapshot.fetch("fields").is_a?(Hash)
+            raise Phronomy::Storage::SerializationError,
+              "Workflow snapshot fields must be a Hash"
+          end
+          phase = snapshot.fetch("phase")
+          unless phase.nil? || phase.is_a?(String)
+            raise Phronomy::Storage::SerializationError,
+              "Workflow snapshot phase must be a String or nil"
+          end
+          Phronomy::CanonicalJSON.dump(snapshot)
+          snapshot
+        rescue ArgumentError => error
+          raise Phronomy::Storage::SerializationError,
+            "Workflow snapshot is not canonical JSON compatible: #{error.message}"
+        end
+
+        def canonicalize_workflow_snapshot(snapshot)
+          source = top_level_string_keys(snapshot, label: "Workflow snapshot")
+          fields = source.fetch("fields")
+          unless fields.is_a?(Hash)
+            raise Phronomy::Storage::SerializationError,
+              "Workflow snapshot fields must be a Hash"
+          end
+          {
+            "fields" => canonicalize_workflow_value(fields),
+            "phase" => source["phase"]&.to_s
+          }
+        end
+
+        def canonicalize_workflow_value(value)
+          case value
+          when Hash
+            value.each_with_object({}) do |(key, child), result|
+              unless key.is_a?(String) || key.is_a?(Symbol)
+                raise Phronomy::Storage::SerializationError,
+                  "Workflow field key must be String or Symbol, got #{key.class}"
+              end
+              string_key = key.to_s
+              if result.key?(string_key)
+                raise Phronomy::Storage::SerializationError,
+                  "duplicate Workflow field key after normalization: #{string_key.inspect}"
+              end
+              result[string_key] = canonicalize_workflow_value(child)
+            end
+          when Array
+            value.map { |child| canonicalize_workflow_value(child) }
+          when Symbol
+            value.to_s
+          when String, Integer, Float, TrueClass, FalseClass, NilClass
+            value
+          else
+            raise Phronomy::Storage::SerializationError,
+              "unsupported Workflow durable value: #{value.class}"
+          end
+        end
+
+        def immutable_copy(value)
+          case value
+          when Hash
+            value.each_with_object({}) do |(key, child), result|
+              result[key.dup.freeze] = immutable_copy(child)
+            end.freeze
+          when Array
+            value.map { |child| immutable_copy(child) }.freeze
+          when String
+            value.dup.freeze
+          else
+            value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/workflow/persistence/state_repository.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class Workflow
+    module Persistence
+      # Owns Workflow snapshot encoding and the initial revision.
+      # @api private
+      class StateRepository
+        def initialize(view) = @view = view
+
+        def load(workflow_instance_id)
+          Phronomy::Persistence::StorageBoundary.call do
+            @view.atomic do |bound|
+              entry = bound.records(Phronomy::Workflow::Persistence::StorageSchema::STATES).read(workflow_instance_id.to_s)
+              entry && decode(entry, workflow_instance_id)
+            end
+          end
+        end
+
+        def save(workflow_instance_id, expected_revision:, snapshot:)
+          Phronomy::Persistence::StorageBoundary.call do
+            expected = expected_revision.nil? ? nil : Integer(expected_revision)
+            revision = expected.nil? ? 1 : expected + 1
+            record = Codec.encode_workflow_state(workflow_instance_id: workflow_instance_id,
+              workflow_revision: revision, snapshot: snapshot)
+            @view.atomic do |bound|
+              records = bound.records(Phronomy::Workflow::Persistence::StorageSchema::STATES)
+              values = {key: workflow_instance_id.to_s, attributes: {}, record: record}
+              entry = if expected.nil?
+                records.insert(**values, revision: revision)
+              else
+                records.replace(**values, expected_revision: expected, next_revision: revision)
+              end
+              decoded = decode(entry, workflow_instance_id)
+              unless decoded.fetch(:revision) == revision
+                raise Phronomy::Storage::SerializationError, "backend returned another Workflow revision"
+              end
+              revision
+            end
+          rescue Phronomy::Storage::NotFoundError => error
+            raise Phronomy::Storage::ConflictError, error.message
+          end
+        end
+
+        def delete(workflow_instance_id, expected_revision:)
+          Phronomy::Persistence::StorageBoundary.call do
+            @view.records(Phronomy::Workflow::Persistence::StorageSchema::STATES).delete(key: workflow_instance_id.to_s, expected_revision: Integer(expected_revision))
+          end
+        end
+
+        private
+
+        def decode(entry, workflow_instance_id)
+          decoded = Codec.decode_workflow_state(entry.record, expected_workflow_instance_id: workflow_instance_id)
+          unless entry.key == workflow_instance_id.to_s && decoded.fetch(:revision) == entry.revision
+            raise Phronomy::Storage::SerializationError, "backend returned another Workflow identity/revision"
+          end
+          decoded
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/workflow/persistence/storage_schema.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Domain-owned Workflow metadata, loadable without the Workflow runtime.
+  # @api private
+  class Workflow
+    module Persistence
+      module StorageSchema
+        STATES = Phronomy::Storage::Resource.new(id: "workflow.states", kind: :records)
+      end
+    end
+  end
+end

data/lib/phronomy/workflow/runtime_binding/workflow_engine_environment.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Connects one compiled Workflow to its owning Runtime. Construction and
+  # transition compilation do not start workers or register execution state.
+  # @api private
+  class WorkflowEngineEnvironment < WorkflowExecutionEnvironment
+    def initialize(runtime: Phronomy::Runtime.instance)
+      @runtime = runtime
+    end
+
+    def registry = WorkflowExecutionRegistry.for(@runtime.event_loop)
+    def existing_registry = WorkflowExecutionRegistry.existing_for(@runtime)
+    def executing? = @runtime.event_loop.current?
+
+    def submit(**options, &operation)
+      Phronomy::Execution.submit(runtime: @runtime, **options, &operation)
+    end
+
+    def compile_transitions(**definition)
+      WorkflowPhaseMachineBuilder.new(**definition).build
+    end
+
+    def build_session(entry_actions:, persist: nil, **options)
+      # Preserve nil/scalar results: initial entry must not re-adopt metadata
+      # unless the application actually returns a context.
+      initial_actions = entry_actions.to_h do |state_name, callbacks|
+        [state_name, callbacks.map { |callback| ->(context) { WorkflowActionRules.entry(callback, context, state_name) } }]
+      end
+      Phronomy::FSMSession.new(**options, entry_actions: initial_actions, event_loop: @runtime.event_loop,
+        terminal_policy: persist && WorkflowTerminalPolicy.new(persist: persist))
+    end
+
+    def register_session(session, completion:)
+      @runtime.event_loop.register(session, completion: completion, receiver: registry)
+    end
+  end
+end

data/lib/phronomy/workflow/runtime_binding/workflow_phase_machine_builder.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "state_machines"
+require_relative "../execution/workflow_action_rules"
+
+module Phronomy
+  # Builds the anonymous state-machine Class used by WorkflowRunner.
+  #
+  # This class compiles Workflow topology into state_machines declarations.
+  # It intentionally does not await Tasks, register completion callbacks,
+  # cancel external work, or interpret application event payloads.
+  #
+  # @api private
+  class WorkflowPhaseMachineBuilder
+    def initialize(
+      entry_point:,
+      declared_states:,
+      wait_state_names:,
+      external_events:,
+      entry_actions:,
+      auto_transitions:,
+      exit_actions:
+    )
+      @entry_point = entry_point
+      @declared_states = declared_states
+      @wait_state_names = wait_state_names
+      @external_events = external_events.transform_values { |items| items.map { |transition| convert_transition(transition) } }
+      @entry_actions = entry_actions
+      @auto_transitions = auto_transitions.map { |transition| convert_transition(transition) }
+      @exit_actions = exit_actions
+    end
+
+    def build
+      entry = @entry_point
+      all_states = (@declared_states + @wait_state_names + [FSMProtocol::FINISH]).uniq
+      auto_transitions = @auto_transitions
+      external_events = @external_events
+      entry_actions = @entry_actions
+      exit_actions = @exit_actions
+      condition_builder = method(:build_transition_condition)
+      entry_callback_builder = method(:build_entry_callback)
+      exit_callback_builder = method(:build_exit_callback)
+      transition_callback = build_transition_action_callback
+
+      Class.new do
+        attr_accessor(
+          :context,
+          :current_event,
+          :selected_transition_action,
+          :selected_transition_metadata
+        )
+
+        state_machine :phase, initial: entry do
+          all_states.each { |state_name| state state_name }
+
+          event :state_completed do
+            auto_transitions.each do |transition_definition|
+              transition(
+                transition_definition[:from] => transition_definition[:to],
+                :if => condition_builder.call(transition_definition)
+              )
+            end
+          end
+
+          external_events.each do |event_name, transitions|
+            event event_name do
+              transitions.each do |transition_definition|
+                transition(
+                  transition_definition[:from] => transition_definition[:to],
+                  :if => condition_builder.call(transition_definition)
+                )
+              end
+            end
+          end
+
+          entry_actions.each do |state_name, callables|
+            callables.each do |callable|
+              after_transition(
+                to: state_name,
+                &entry_callback_builder.call(callable, state_name)
+              )
+            end
+          end
+
+          # Both source exit callbacks and the transition action are
+          # before_transition callbacks. Register exits first to preserve the
+          # required exit -> transition action -> entry ordering.
+          exit_actions.each do |state_name, callables|
+            callables.each do |callable|
+              before_transition(
+                from: state_name,
+                &exit_callback_builder.call(callable, state_name)
+              )
+            end
+          end
+
+          before_transition(&transition_callback)
+        end
+      end
+    rescue => error
+      raise ArgumentError, "Failed to build phase machine: #{error.message}"
+    end
+
+    private
+
+    def convert_transition(transition)
+      destination = transition[:to]
+      destination = FSMProtocol::FINISH if destination == Workflow::Completion::FINISH
+      transition.merge(to: destination)
+    end
+
+    def build_transition_condition(transition_definition)
+      guard = transition_definition[:guard]
+      action = transition_definition[:action]
+      metadata = {
+        from: transition_definition[:from],
+        event: transition_definition[:event],
+        to: public_destination(transition_definition[:to])
+      }.freeze
+
+      ->(machine) {
+        matched = WorkflowActionRules.allowed?(guard, machine.context, machine.current_event)
+        if matched
+          machine.selected_transition_action = action
+          machine.selected_transition_metadata = metadata
+        end
+        matched
+      }
+    end
+
+    def build_transition_action_callback
+      ->(machine) {
+        machine.context = WorkflowActionRules.transition(
+          machine.selected_transition_action, machine.context, machine.current_event,
+          metadata: machine.selected_transition_metadata || {}
+        )
+      }
+    end
+
+    def build_entry_callback(callable, state_name)
+      ->(machine) {
+        machine.context = WorkflowActionRules.apply_entry(callable, machine.context, state_name)
+      }
+    end
+
+    def build_exit_callback(callable, state_name)
+      ->(machine) { WorkflowActionRules.exit(callable, machine.context, state_name) }
+    end
+
+    def public_destination(destination)
+      return Workflow::Completion::FINISH if destination == FSMProtocol::FINISH
+
+      destination
+    end
+  end
+end

data/lib/phronomy/workflow/runtime_binding/workflow_terminal_policy.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Translates classified Workflow outcomes into shared FSM terminal decisions.
+  # The session owns pending state; Runner owns persistence and reconciliation.
+  # @api private
+  class WorkflowTerminalPolicy
+    include Phronomy::Concurrency::WorkerInputRestricted
+
+    def initialize(persist:)
+      @persist = persist
+    end
+
+    def start(terminal_type:, context:, event_sink:)
+      @persist.call(terminal_type: terminal_type, context: context, event_sink: event_sink)
+    end
+
+    def handles?(event)
+      event.type == :workflow_terminal_persistence_result
+    end
+
+    def decision_for(event)
+      result = event.payload
+      case result.outcome
+      when :success
+        Phronomy::TerminalDecision.new(action: :complete, error: nil)
+      when :known_failure
+        Phronomy::TerminalDecision.new(
+          action: :fail,
+          error: result.error || Phronomy::Error.new("Workflow terminal persistence failed")
+        )
+      when :outcome_unknown
+        Phronomy::TerminalDecision.new(action: :retire, error: result.error)
+      else
+        raise Phronomy::Error,
+          "unknown Workflow terminal persistence outcome: #{result.outcome.inspect}"
+      end
+    end
+  end
+end