Class: Legion::Gaia::Workflow::Instance

Inherits:
Object
  • Object
show all
Defined in:
lib/legion/gaia/workflow/instance.rb

Overview

A running instance of a workflow Definition.

Each instance has:

- a reference to its Definition
- a current_state (Symbol)
- a transition history (Array of hashes)
- arbitrary metadata provided at creation
- an id (auto-generated Integer, or user-supplied)

Thread-safety: each instance holds a Mutex so concurrent calls to ‘transition!` serialize correctly.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(definition:, metadata: {}, id: nil) ⇒ Instance

Returns a new instance of Instance.

Parameters:

  • definition (Definition)
  • metadata (Hash) (defaults to: {}) —

    arbitrary caller-supplied data stored on the instance

  • id (Integer, String, nil) (defaults to: nil) —

    optional identifier; auto-incremented if nil



23
24
25
26
27
28
29
30
31
 
# File 'lib/legion/gaia/workflow/instance.rb', line 23

def initialize(definition:, metadata: {}, id: nil)
  @definition   = definition
  @metadata     = metadata.dup.freeze
  @id           = id || self.class.next_id
  @created_at   = Time.now
  @history      = []
  @mutex        = Mutex.new
  @current_state = definition.initial_state
end

Instance Attribute Details

#created_at ⇒ Object (readonly)

Returns the value of attribute created_at.



18
19
20
 
# File 'lib/legion/gaia/workflow/instance.rb', line 18

def created_at
  @created_at
end

#current_state ⇒ Object (readonly)

Returns the value of attribute current_state.



18
19
20
 
# File 'lib/legion/gaia/workflow/instance.rb', line 18

def current_state
  @current_state
end

#definition ⇒ Object (readonly)

Returns the value of attribute definition.



18
19
20
 
# File 'lib/legion/gaia/workflow/instance.rb', line 18

def definition
  @definition
end

#history ⇒ Object (readonly)

Returns the value of attribute history.



18
19
20
 
# File 'lib/legion/gaia/workflow/instance.rb', line 18

def history
  @history
end

#id ⇒ Object (readonly)

Returns the value of attribute id.



18
19
20
 
# File 'lib/legion/gaia/workflow/instance.rb', line 18

def id
  @id
end

#metadata ⇒ Object (readonly)

Returns the value of attribute metadata.



18
19
20
 
# File 'lib/legion/gaia/workflow/instance.rb', line 18

def metadata
  @metadata
end

Class Method Details

.next_id ⇒ Object 



99
100
101
 
# File 'lib/legion/gaia/workflow/instance.rb', line 99

def next_id
  @id_mutex.synchronize { @id_counter += 1 }
end

.reset_id_counter! ⇒ Object

Reset counter — for test isolation only



104
105
106
 
# File 'lib/legion/gaia/workflow/instance.rb', line 104

def reset_id_counter!
  @id_mutex.synchronize { @id_counter = 0 }
end

Instance Method Details

#available_transitions ⇒ Object

Returns the list of states reachable from the current state (no guard eval).



76
77
78
 
# File 'lib/legion/gaia/workflow/instance.rb', line 76

def available_transitions
  definition.transitions_from(current_state).map { |t| t[:to] }
end

#can_transition_to?(to_state) ⇒ Boolean

Returns true if the instance can transition to to_state right now (definition-level check only — does not evaluate guards).

Returns:

  • (Boolean) 


70
71
72
73
 
# File 'lib/legion/gaia/workflow/instance.rb', line 70

def can_transition_to?(to_state)
  to_state = to_state.to_sym
  definition.transitions_from(current_state).any? { |t| t[:to] == to_state }
end

#in_state?(state) ⇒ Boolean

Returns true if the instance is currently in state.

Returns:

  • (Boolean) 


64
65
66
 
# File 'lib/legion/gaia/workflow/instance.rb', line 64

def in_state?(state)
  current_state == state.to_sym
end

#status ⇒ Object

Human-readable status summary



81
82
83
84
85
86
87
88
89
90
91
 
# File 'lib/legion/gaia/workflow/instance.rb', line 81

def status
  {
    id: id,
    workflow: definition.name,
    current_state: current_state,
    history_length: history.size,
    available_transitions: available_transitions,
    created_at: created_at,
    last_transitioned_at: history.last&.dig(:at)
  }
end

#transition(to_state, **ctx) ⇒ Boolean

Non-raising variant — returns true on success, false on guard/checkpoint failure. Unknown-state and invalid-transition errors still propagate.

Parameters:

  • to_state (Symbol)
  • ctx (Hash)

Returns:

  • (Boolean) 


56
57
58
59
60
61
 
# File 'lib/legion/gaia/workflow/instance.rb', line 56

def transition(to_state, **ctx)
  transition!(to_state, **ctx)
  true
rescue GuardRejected, CheckpointBlocked
  false
end

#transition!(to_state, **ctx) ⇒ self

Attempt to transition to to_state, passing ctx to guards, checkpoints, and callbacks.

Raises on any failure (guard rejection, checkpoint block, unknown state, or invalid transition).

Parameters:

  • to_state (Symbol)
  • ctx (Hash) —

    passed to guards and checkpoint conditions

Returns:

  • (self) 


44
45
46
47
48
 
# File 'lib/legion/gaia/workflow/instance.rb', line 44

def transition!(to_state, **ctx)
  to_state = to_state.to_sym
  @mutex.synchronize { perform_transition!(to_state, ctx) }
  self
end