Class: Pangea::Magma::Optimization

Inherits:
Object
  • Object
show all
Defined in:
lib/pangea/magma/optimization.rb

Overview

Typed orchestration hints — how the chain should be executed, not what it executes. Per theory/PANGEA-MAGMA-ORCHESTRATION.md §III.5 (M0.4).

Authors:

opt = Pangea::Magma::Optimization.declare(
  strategy:        :parallel_by_tier,
  max_concurrency: 4,
  retries:         { max: 2, backoff_ms: 500 },
  timeout_ms:      10 * 60 * 1000,
)

The hints serialize into the flow.json that ‘magma flow run` consumes; on the Rust side they configure the shigoto Scheduler that wraps each workspace as a Job. M0 ships the serialization + validation surface; the scheduler honors them as soon as `magma flow run` lands its shigoto-wrapped apply path (currently plan-only, sequential).

Defined Under Namespace

Classes: Retries

Constant Summary collapse

STRATEGIES = 
%i[sequential parallel parallel_by_tier].freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(strategy:, max_concurrency:, retries:, timeout_ms:) ⇒ Optimization

Returns a new instance of Optimization.



67
68
69
70
71
72
 
# File 'lib/pangea/magma/optimization.rb', line 67

def initialize(strategy:, max_concurrency:, retries:, timeout_ms:)
  @strategy        = strategy
  @max_concurrency = max_concurrency
  @retries         = retries
  @timeout_ms      = timeout_ms
end

Instance Attribute Details

#max_concurrency ⇒ Object (readonly)

Returns the value of attribute max_concurrency.



65
66
67
 
# File 'lib/pangea/magma/optimization.rb', line 65

def max_concurrency
  @max_concurrency
end

#retries ⇒ Object (readonly)

Returns the value of attribute retries.



65
66
67
 
# File 'lib/pangea/magma/optimization.rb', line 65

def retries
  @retries
end

#strategy ⇒ Object (readonly)

Returns the value of attribute strategy.



65
66
67
 
# File 'lib/pangea/magma/optimization.rb', line 65

def strategy
  @strategy
end

#timeout_ms ⇒ Object (readonly)

Returns the value of attribute timeout_ms.



65
66
67
 
# File 'lib/pangea/magma/optimization.rb', line 65

def timeout_ms
  @timeout_ms
end

Class Method Details

.declare(strategy: :sequential, max_concurrency: 1, retries: nil, timeout_ms: nil) ⇒ Object 



36
37
38
39
40
41
42
43
44
45
46
47
48
49
 
# File 'lib/pangea/magma/optimization.rb', line 36

def declare(strategy: :sequential, max_concurrency: 1,
            retries: nil, timeout_ms: nil)
  unless STRATEGIES.include?(strategy)
    raise ArgumentError,
          "unknown strategy #{strategy.inspect}; expected one of #{STRATEGIES.inspect}"
  end
  if max_concurrency < 1
    raise ArgumentError, "max_concurrency must be >= 1 (got #{max_concurrency})"
  end
  retries_obj = retries.is_a?(Hash) ? Retries.new(**retries) : retries

  new(strategy: strategy, max_concurrency: max_concurrency,
      retries: retries_obj, timeout_ms: timeout_ms)
end

.parallel_by_tier(max_concurrency: 4, retries: { max: 2, backoff_ms: 500 }) ⇒ Object

Convenience: tier-parallel — leaves with no upstream edge run in parallel, downstream tiers wait. Honors the chain’s topo order at execution time.



59
60
61
62
 
# File 'lib/pangea/magma/optimization.rb', line 59

def parallel_by_tier(max_concurrency: 4, retries: { max: 2, backoff_ms: 500 })
  declare(strategy: :parallel_by_tier,
          max_concurrency: max_concurrency, retries: retries)
end

.sequential ⇒ Object

Convenience: sequential default — safest, slowest.



52
53
54
 
# File 'lib/pangea/magma/optimization.rb', line 52

def sequential
  declare(strategy: :sequential, max_concurrency: 1)
end

Instance Method Details

#to_h ⇒ Object 



74
75
76
77
78
79
80
81
 
# File 'lib/pangea/magma/optimization.rb', line 74

def to_h
  {
    strategy:        @strategy.to_s,
    max_concurrency: @max_concurrency,
    retries:         @retries&.to_h,
    timeout_ms:      @timeout_ms,
  }.compact
end

#to_json(*args) ⇒ Object 



83
84
85
 
# File 'lib/pangea/magma/optimization.rb', line 83

def to_json(*args)
  to_h.to_json(*args)
end