phronomy 0.25.0 → 0.27.0

data/lib/phronomy/{workflow_runner.rb → workflow/execution/workflow_runner.rb}

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../../engine/concurrency/worker_input_restricted"
+
 require "securerandom"
 
 module Phronomy
@@ -16,9 +18,9 @@ module Phronomy
   # to the same FSMSession before that session becomes halted/completed.
   # @api private
   class WorkflowRunner
-    include Phronomy::Runnable
+    include Phronomy::Concurrency::WorkerInputRestricted
 
-    FINISH = :__end__
+    include Phronomy::Runnable
 
     Execution = Data.define(
       :context,
@@ -138,7 +140,7 @@ module Phronomy
     end
 
     # Posts an application-defined event to the currently live Workflow owner.
-    # EventLoop resolves workflow_instance_id to the current concrete
+    # WorkflowExecutionRegistry resolves workflow_instance_id to the current concrete
     # fsm_session_id. The opaque admission owner token is deliberately not a
     # routing identity and is not exposed here.
     def signal(workflow_instance_id:, event:, payload: nil)
@@ -151,7 +153,10 @@ module Phronomy
           "Valid events: #{@external_events.keys.inspect}"
       end
 
-      Phronomy::Runtime.instance.event_loop.post_to_workflow(
+      registry = Phronomy::WorkflowExecutionRegistry.existing_for(Phronomy::Runtime.instance)
+      return false unless registry
+
+      registry.post_to_workflow(
         workflow_instance_id: workflow_instance_id,
         event: event_name,
         payload: payload
@@ -216,7 +221,7 @@ module Phronomy
     def start_new_execution(input, config, stable_observer: nil)
       reject_legacy_workflow_identity_key!(config)
       runtime = Phronomy::Runtime.instance
-      result_task = Phronomy::Task.deferred(name: "workflow:preparing")
+      result_task = Phronomy::TaskResult.deferred(name: "workflow:preparing")
       explicit_workflow_instance_id = !config[:workflow_instance_id].nil?
       workflow_instance_id = (config[:workflow_instance_id] || SecureRandom.uuid).to_s.freeze
       Phronomy::Tracing::Automatic.observe_task(
@@ -247,7 +252,7 @@ module Phronomy
     def start_resume_execution(state, input:, event_name:, current_phase:)
       runtime = Phronomy::Runtime.instance
       workflow_instance_id = state.workflow_instance_id.to_s.freeze
-      result_task = Phronomy::Task.deferred(name: "workflow-resume:#{workflow_instance_id}")
+      result_task = Phronomy::TaskResult.deferred(name: "workflow-resume:#{workflow_instance_id}")
       Phronomy::Tracing::Automatic.observe_task(
         result_task,
         "workflow.execution",
@@ -277,7 +282,7 @@ module Phronomy
       runtime = Phronomy::Runtime.instance
       event_loop = runtime.event_loop
       admitted = false
-      event_loop.admit_workflow(
+      Phronomy::WorkflowExecutionRegistry.for(event_loop).admit_workflow(
         request.workflow_instance_id,
         owner_token: request.owner_token
       )
@@ -318,7 +323,7 @@ module Phronomy
       )
     rescue => error
       if admitted
-        event_loop.release_workflow(
+        Phronomy::WorkflowExecutionRegistry.for(event_loop).release_workflow(
           request.workflow_instance_id,
           owner_token: request.owner_token
         )
@@ -330,7 +335,7 @@ module Phronomy
       runtime = Phronomy::Runtime.instance
       event_loop = runtime.event_loop
       admitted = false
-      event_loop.admit_workflow(
+      Phronomy::WorkflowExecutionRegistry.for(event_loop).admit_workflow(
         request.workflow_instance_id,
         owner_token: request.owner_token
       )
@@ -366,7 +371,7 @@ module Phronomy
       )
     rescue => error
       if admitted
-        event_loop.release_workflow(
+        Phronomy::WorkflowExecutionRegistry.for(event_loop).release_workflow(
           request.workflow_instance_id,
           owner_token: request.owner_token
         )
@@ -503,7 +508,7 @@ module Phronomy
       local_snapshot = normalize_snapshot(snapshot_for(state))
       return durable_revision if normalized_durable == local_snapshot
 
-      raise Phronomy::Persistence::ConflictError,
+      raise Phronomy::Storage::ConflictError,
         "Workflow state changed since the supplied halted context for " \
         "workflow_instance_id #{state.workflow_instance_id.inspect}; explicit reload/reconciliation is required"
     end
@@ -576,13 +581,13 @@ module Phronomy
         resume_phase: resume_phase,
         stable_observer: stable_observer
       )
-      event_loop.bind_workflow_session(
+      Phronomy::WorkflowExecutionRegistry.for(event_loop).bind_workflow_session(
         execution.workflow_instance_id,
         owner_token: execution.owner_token,
         fsm_session_id: session.id
       )
 
-      source_task = Phronomy::Task.deferred(name: "workflow-source:#{session.id}")
+      source_task = Phronomy::TaskResult.deferred(name: "workflow-source:#{session.id}")
       source_task.on_complete do |result, error|
         finalize_execution(
           execution: execution,
@@ -591,11 +596,12 @@ module Phronomy
           error: error
         )
       end
-      event_loop.register(session, completion: source_task)
+      event_loop.register(session, completion: source_task,
+        receiver: Phronomy::WorkflowExecutionRegistry.for(event_loop))
       result_task
     rescue => error
       if event_loop&.current?
-        event_loop&.release_workflow(
+        Phronomy::WorkflowExecutionRegistry.for(event_loop).release_workflow(
           execution.workflow_instance_id,
           owner_token: execution.owner_token
         )
@@ -608,7 +614,7 @@ module Phronomy
     def finalize_execution(execution:, result_task:, result:, error:)
       event_loop = Phronomy::Runtime.instance.event_loop
       assert_event_loop!(event_loop)
-      event_loop.release_workflow(
+      Phronomy::WorkflowExecutionRegistry.for(event_loop).release_workflow(
         execution.workflow_instance_id,
         owner_token: execution.owner_token
       )
@@ -624,73 +630,117 @@ module Phronomy
       runtime = Phronomy::Runtime.instance
       event_loop = runtime.event_loop
       assert_event_loop!(event_loop)
-      event_loop.mark_workflow_admission(
+      Phronomy::WorkflowExecutionRegistry.for(event_loop).mark_workflow_admission(
         execution.workflow_instance_id,
         owner_token: execution.owner_token,
         state: :persisting_terminal
       )
 
-      operation = WorkflowTerminalPersistenceCommand.new(
+      operation = Phronomy::WorkflowRunner::WorkflowTerminalPersistenceCommand.new(
         repository: execution.repository,
         workflow_instance_id: execution.workflow_instance_id.to_s.freeze,
         expected_revision: execution.expected_revision,
         snapshot: deep_immutable_copy(snapshot_for(context))
       )
+
       task = runtime.offload.submit(on_full: :raise) do
-        revision = operation.repository.save(
-          operation.workflow_instance_id,
-          expected_revision: operation.expected_revision,
-          snapshot: operation.snapshot
+        persist_terminal_snapshot(operation)
+      end
+      task.on_complete do |result, operation_error|
+        deliver_terminal_persistence_result(execution, event_sink, result, operation_error)
+      end
+      terminal_type
+    end
+
+    def persist_terminal_snapshot(operation)
+      revision = operation.repository.save(
+        operation.workflow_instance_id,
+        expected_revision: operation.expected_revision,
+        snapshot: operation.snapshot
+      )
+      Phronomy::WorkflowRunner::WorkflowTerminalPersistenceResult.new(
+        outcome: :success,
+        revision: revision,
+        error: nil
+      )
+    rescue Phronomy::Storage::ConflictError,
+      Phronomy::Storage::NotFoundError,
+      Phronomy::Storage::SerializationError,
+      Phronomy::Storage::UnsupportedBackendError => error
+      Phronomy::WorkflowRunner::WorkflowTerminalPersistenceResult.new(
+        outcome: :known_failure,
+        revision: nil,
+        error: error
+      )
+    rescue => error
+      reconcile_workflow_terminal_f1(operation, error)
+    end
+
+    def deliver_terminal_persistence_result(execution, event_sink, result, operation_error)
+      delivery = if operation_error
+        Phronomy::WorkflowRunner::WorkflowTerminalPersistenceResult.new(
+          outcome: :outcome_unknown,
+          revision: nil,
+          error: operation_error
         )
-        WorkflowTerminalPersistenceResult.new(
+      else
+        result
+      end
+      accepted = event_sink.post(:workflow_terminal_persistence_result, delivery)
+      unless accepted
+        Phronomy.configuration.logger&.warn(
+          "[Phronomy] EventLoop rejected Workflow terminal persistence result " \
+          "for #{execution.workflow_instance_id.inspect}"
+        )
+      end
+    end
+
+    def reconcile_workflow_terminal_f1(operation, original_error)
+      record = operation.repository.load(operation.workflow_instance_id)
+      case Phronomy::Recovery.compare_revisioned_snapshot(
+        record: record,
+        expected_pre_revision: operation.expected_revision,
+        intended_snapshot: operation.snapshot
+      )
+      when :post_state
+        revision = Phronomy::Recovery.fetch_value(record, :revision)
+        Phronomy::WorkflowRunner::WorkflowTerminalPersistenceResult.new(
           outcome: :success,
           revision: revision,
           error: nil
         )
-      rescue Phronomy::Persistence::ConflictError,
-        Phronomy::Persistence::NotFoundError,
-        Phronomy::Persistence::SerializationError,
-        Phronomy::Persistence::UnsupportedBackendError => error
-        WorkflowTerminalPersistenceResult.new(
+      when :pre_state
+        # The uncertain save is now known not to have committed. Do not blindly
+        # retry it here; surface a known failure through the ordinary terminal
+        # barrier semantics.
+        Phronomy::WorkflowRunner::WorkflowTerminalPersistenceResult.new(
           outcome: :known_failure,
           revision: nil,
-          error: error
+          error: original_error
         )
-      rescue => error
-        # The Backend SPI does not currently provide a portable commit-outcome
-        # classifier for arbitrary storage/transport failures. If non-commit is
-        # not guaranteed by the Phronomy error contract, fail closed as F1.
-        WorkflowTerminalPersistenceResult.new(
+      else
+        conflict = Phronomy::Storage::ConflictError.new(
+          "Workflow terminal Persistence outcome conflicts with both expected " \
+          "pre-state and intended post-state for #{operation.workflow_instance_id.inspect}"
+        )
+        Phronomy::WorkflowRunner::WorkflowTerminalPersistenceResult.new(
           outcome: :outcome_unknown,
           revision: nil,
-          error: error
+          error: conflict
         )
       end
-      task.on_complete do |result, operation_error|
-        delivery = if operation_error
-          WorkflowTerminalPersistenceResult.new(
-            outcome: :outcome_unknown,
-            revision: nil,
-            error: operation_error
-          )
-        else
-          result
-        end
-        accepted = event_sink.post(:workflow_terminal_persistence_result, delivery)
-        unless accepted
-          Phronomy.configuration.logger&.warn(
-            "[Phronomy] EventLoop rejected Workflow terminal persistence result " \
-            "for #{execution.workflow_instance_id.inspect}"
-          )
-        end
-      end
-      terminal_type
+    rescue => reconciliation_error
+      Phronomy::WorkflowRunner::WorkflowTerminalPersistenceResult.new(
+        outcome: :outcome_unknown,
+        revision: nil,
+        error: reconciliation_error
+      )
     end
 
     def release_and_fail(request, error)
       event_loop = Phronomy::Runtime.instance.event_loop
       assert_event_loop!(event_loop)
-      event_loop.release_workflow(
+      Phronomy::WorkflowExecutionRegistry.for(event_loop).release_workflow(
         request.workflow_instance_id,
         owner_token: request.owner_token
       )
@@ -711,17 +761,6 @@ module Phronomy
       resume_phase: nil,
       stable_observer: nil
     )
-      terminal_barrier = if execution.repository && execution.persist
-        ->(terminal_type:, context:, event_sink:) {
-          begin_terminal_persistence_on_event_loop(
-            execution,
-            terminal_type: terminal_type,
-            context: context,
-            event_sink: event_sink
-          )
-        }
-      end
-
       Phronomy::FSMSession.new(
         context: execution.context,
         context_metadata: {
@@ -739,7 +778,22 @@ module Phronomy
         resume_event: resume_event,
         resume_phase: resume_phase,
         stable_observer: stable_observer,
-        terminal_barrier: terminal_barrier
+        terminal_policy: build_terminal_policy(execution)
+      )
+    end
+
+    def build_terminal_policy(execution)
+      return unless execution.repository && execution.persist
+
+      Phronomy::WorkflowTerminalPolicy.new(
+        persist: ->(terminal_type:, context:, event_sink:) {
+          begin_terminal_persistence_on_event_loop(
+            execution,
+            terminal_type: terminal_type,
+            context: context,
+            event_sink: event_sink
+          )
+        }
       )
     end
 
@@ -766,13 +820,10 @@ module Phronomy
     end
 
     def post_control(runtime, command)
-      runtime.event_loop.post(
-        Phronomy::Event.new(
-          type: :workflow_control,
-          target_id: Phronomy::EventLoop::SYSTEM_CHANNEL_ID,
-          payload: {command: command}
-        )
-      )
+      admission = command.is_a?(StartCommand) || command.is_a?(ResumeCommand)
+      completion = admission ? command.result_task : command.request.result_task
+      Phronomy::WorkflowExecutionRegistry.for(runtime.event_loop).post(command,
+        admission: admission, completion: completion)
     end
 
     def runtime_rejected_error(action)
@@ -797,7 +848,7 @@ module Phronomy
     end
 
     def failed_task(name, error)
-      task = Phronomy::Task.deferred(name: name)
+      task = Phronomy::TaskResult.deferred(name: name)
       fail_task(task, error)
       task
     end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Interprets durable Workflow results for the shared FSM terminal gate.
+  # 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
+        FSMProtocol::TerminalDecision.new(action: :complete, error: nil)
+      when :known_failure
+        FSMProtocol::TerminalDecision.new(
+          action: :fail,
+          error: result.error || Phronomy::Error.new("Workflow terminal persistence failed")
+        )
+      when :outcome_unknown
+        FSMProtocol::TerminalDecision.new(action: :retire, error: result.error)
+      else
+        raise Phronomy::Error,
+          "unknown Workflow terminal persistence outcome: #{result.outcome.inspect}"
+      end
+    end
+  end
+end

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,57 @@
+# 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)
+          @view.atomic do |bound|
+            entry = bound.records(Phronomy::WorkflowStorageSchema::STATES).read(workflow_instance_id.to_s)
+            entry && decode(entry, workflow_instance_id)
+          end
+        end
+
+        def save(workflow_instance_id, expected_revision:, snapshot:)
+          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::WorkflowStorageSchema::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
+
+        def delete(workflow_instance_id, expected_revision:)
+          @view.records(Phronomy::WorkflowStorageSchema::STATES).delete(key: workflow_instance_id.to_s, expected_revision: Integer(expected_revision))
+        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/phase_machine_builder.rb

@@ -32,7 +32,7 @@ module Phronomy
 
       def build
         entry = @entry_point
-        all_states = (@declared_states + @wait_state_names + [:__end__]).uniq
+        all_states = (@declared_states + @wait_state_names + [FSMProtocol::FINISH]).uniq
         auto_transitions = @auto_transitions
         external_events = @external_events
         entry_actions = @entry_actions
@@ -139,7 +139,7 @@ module Phronomy
               machine.context,
               machine.current_event
             )
-            if result.is_a?(Phronomy::Task)
+            if result.is_a?(Phronomy::TaskResult)
               raise Phronomy::InvalidAsyncTransitionActionError,
                 transition_task_error_message(metadata)
             end
@@ -151,9 +151,9 @@ module Phronomy
       def build_entry_callback(callable, state_name)
         ->(machine) {
           result = callable.call(machine.context)
-          if result.is_a?(Phronomy::Task)
+          if result.is_a?(Phronomy::TaskResult)
             raise Phronomy::InvalidAsyncEntryActionError,
-              "Entry action for state #{state_name.inspect} returned Phronomy::Task. " \
+              "Entry action for state #{state_name.inspect} returned Phronomy::TaskResult. " \
               "Start the asynchronous operation, register its callback/listener, " \
               "and return the WorkflowContext or nil."
           end
@@ -164,9 +164,9 @@ module Phronomy
       def build_exit_callback(callable, state_name)
         ->(machine) {
           result = callable.call(machine.context)
-          if result.is_a?(Phronomy::Task)
+          if result.is_a?(Phronomy::TaskResult)
             raise Phronomy::InvalidAsyncEntryActionError,
-              "Exit action for state #{state_name.inspect} returned Phronomy::Task. " \
+              "Exit action for state #{state_name.inspect} returned Phronomy::TaskResult. " \
               "Exit actions are synchronous Run-to-Completion callbacks."
           end
         }
@@ -188,7 +188,7 @@ module Phronomy
       end
 
       def public_destination(destination)
-        return :__finish__ if destination == Phronomy::WorkflowRunner::FINISH
+        return :__finish__ if destination == FSMProtocol::FINISH
 
         destination
       end
@@ -196,7 +196,7 @@ module Phronomy
       def transition_task_error_message(metadata)
         "Transition action " \
           "#{metadata[:from].inspect} --#{metadata[:event].inspect}--> " \
-          "#{metadata[:to].inspect} returned Phronomy::Task. " \
+          "#{metadata[:to].inspect} returned Phronomy::TaskResult. " \
           "Start the asynchronous operation, register its callback/listener, " \
           "and return the WorkflowContext or nil."
       end

data/lib/phronomy/workflow/storage_contract/workflow_storage_schema.rb

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