pangea-core 0.2.0 → 0.3.0

data/lib/pangea/magma/chain.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'workspace'
+require_relative 'runner'
+
+module Pangea
+  module Magma
+    # Typed DAG of Workspaces wired by ChainEdges. Mirrors
+    # `magma_pangea::chain::WorkspaceChain` (per theory/MAGMA.md §II.9
+    # and theory/PANGEA-MAGMA-ORCHESTRATION.md §III.2).
+    #
+    # Authors:
+    #
+    #   chain = Pangea::Magma::Chain.build do |c|
+    #     c.workspace vpc       # Pangea::Magma::Workspace instance
+    #     c.workspace cluster
+    #     c.workspace fluxcd
+    #     c.edge from: vpc, output: :vpc_id,
+    #            to:   cluster, input: :vpc_id
+    #     c.edge from: cluster, output: :kubeconfig,
+    #            to:   fluxcd, input: :kubeconfig
+    #   end
+    #
+    #   chain.reconcile_all   # → AggregateReport Hash (via magma flow run)
+    class Chain
+      ChainEdge = Struct.new(:from, :from_output, :to, :to_input,
+                             keyword_init: true) do
+        def to_h
+          { from: from.to_s, from_output: from_output.to_s,
+            to:   to.to_s,   to_input:    to_input.to_s }
+        end
+      end
+
+      class Builder
+        attr_reader :workspaces, :edges
+        def initialize
+          @workspaces = {}
+          @edges      = []
+        end
+
+        def workspace(ws)
+          unless ws.is_a?(Workspace)
+            raise ArgumentError,
+                  "expected Pangea::Magma::Workspace, got #{ws.class}"
+          end
+          @workspaces[ws.name] = ws
+          self
+        end
+
+        def edge(from:, output:, to:, input:)
+          from_name = from.respond_to?(:name) ? from.name : from
+          to_name   = to.respond_to?(:name)   ? to.name   : to
+          unless @workspaces.key?(from_name)
+            raise ArgumentError, "edge.from references unknown workspace: #{from_name}"
+          end
+          unless @workspaces.key?(to_name)
+            raise ArgumentError, "edge.to references unknown workspace: #{to_name}"
+          end
+          @edges << ChainEdge.new(
+            from: from_name, from_output: output,
+            to:   to_name,   to_input:    input,
+          )
+          self
+        end
+      end
+
+      class << self
+        # Build a typed Chain. Yields a Builder; returns a frozen Chain.
+        def build(optimization: nil)
+          b = Builder.new
+          yield b
+          new(workspaces: b.workspaces, edges: b.edges,
+              optimization: optimization)
+        end
+
+        # Compose: produce a Chain from a list of workspaces with no
+        # cross-workspace edges (used for "deploy these in sequence
+        # without typed-value flow" scenarios).
+        def compose(workspaces, output_propagation: :in_memory, optimization: nil)
+          b = Builder.new
+          workspaces.each { |w| b.workspace(w) }
+          new(workspaces: b.workspaces, edges: b.edges,
+              output_propagation: output_propagation,
+              optimization: optimization)
+        end
+      end
+
+      attr_reader :workspaces, :edges, :output_propagation, :optimization
+
+      def initialize(workspaces:, edges:, output_propagation: :in_memory,
+                     optimization: nil)
+        @workspaces         = workspaces.freeze
+        @edges              = edges.freeze
+        @output_propagation = output_propagation
+        @optimization       = optimization
+        validate!
+      end
+
+      # Return a new Chain with the given optimization hints. Used by
+      # Orchestrator to attach Optimization without rebuilding the chain.
+      def with_optimization(opt)
+        Chain.new(workspaces: @workspaces, edges: @edges,
+                  output_propagation: @output_propagation, optimization: opt)
+      end
+
+      def node_count
+        @workspaces.size
+      end
+
+      def edge_count
+        @edges.size
+      end
+
+      # Topological order across the declared edges.
+      # Raises if a cycle is detected.
+      def topo_order
+        indegree = @workspaces.each_key.to_h { |n| [n, 0] }
+        @edges.each { |e| indegree[e.to] += 1 }
+        queue = indegree.select { |_, d| d.zero? }.keys
+        order = []
+        until queue.empty?
+          n = queue.shift
+          order << n
+          @edges.each do |e|
+            next unless e.from == n
+            indegree[e.to] -= 1
+            queue << e.to if indegree[e.to].zero?
+          end
+        end
+        raise "cycle in chain: #{indegree.keys.inspect}" if order.size < @workspaces.size
+
+        order
+      end
+
+      # The typed flow JSON the chain serializes to. Public so
+      # operators can audit it before reconciliation and rspec can
+      # snapshot-match it.
+      def to_flow_hash
+        h = {
+          workspaces: @workspaces.values.map { |w| { name: w.name.to_s, dir: w.workspace_dir } },
+          edges:      @edges.map(&:to_h),
+        }
+        h[:optimization] = @optimization.to_h if @optimization
+        h
+      end
+
+      # Reconcile every workspace in topological order via the
+      # canonical `magma flow run` engine (magma-flow crate). Returns
+      # an AggregateReport-shaped Hash. Delegates to Pangea::Magma.flow
+      # (which delegates to Runner.invoke) so this method stays one
+      # line of intent.
+      def reconcile_all
+        Pangea::Magma.flow(to_flow_hash)
+      end
+
+      # Subset reconciliation — run a slice of the chain with the rest
+      # mocked out (downstream-from-stub gets typed values from the
+      # `stub_upstream_outputs` map rather than running upstream Workspaces).
+      # Mirrors `WorkspaceChain::reconcile_subset` semantics. For M0.1
+      # this is a thin wrapper that drives `magma flow` with a reduced
+      # workspace set; the typed-value injection lands once magma
+      # exposes a `--stubs <json>` flag.
+      def reconcile_subset(subset_names, stub_upstream_outputs: {})
+        raise NotImplementedError,
+              "Chain#reconcile_subset awaits magma's `--stubs` flag (M0.1.x). " \
+              "subset_names=#{subset_names.inspect}, " \
+              "stub_upstream_outputs=#{stub_upstream_outputs.inspect}"
+      end
+
+      def to_h
+        h = {
+          output_propagation: @output_propagation,
+          workspaces:         @workspaces.transform_values(&:to_h),
+          edges:              @edges.map(&:to_h),
+        }
+        h[:optimization] = @optimization.to_h if @optimization
+        h
+      end
+
+      def to_json(*args)
+        to_h.to_json(*args)
+      end
+
+      private
+
+      def validate!
+        @edges.each do |e|
+          unless @workspaces.key?(e.from)
+            raise ArgumentError, "edge.from references unknown workspace: #{e.from}"
+          end
+          unless @workspaces.key?(e.to)
+            raise ArgumentError, "edge.to references unknown workspace: #{e.to}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pangea/magma/distribution.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'chain'
+
+module Pangea
+  module Magma
+    # Strategy for distributing architecture pieces across workspaces.
+    # Per theory/PANGEA-MAGMA-ORCHESTRATION.md §III.4. The
+    # distribution doesn't change WHAT is deployed — only WHERE it
+    # lives in state organization.
+    #
+    # Authors:
+    #
+    #   dist = Pangea::Magma::Distribution.declare(
+    #     strategy: :tier_separation,
+    #     tiers: {
+    #       network:  [vpc_ws, dns_ws, lb_ws],
+    #       cluster:  [iam_ws, k3s_ws, kms_ws],
+    #       workload: [fluxcd_ws, observability_ws],
+    #     },
+    #     edges: { network: :cluster, cluster: :workload },
+    #     placement: {
+    #       network:  { region: 'us-east-1' },
+    #       cluster:  { region: 'us-east-1' },
+    #       workload: { region: 'us-east-1' },
+    #     },
+    #   )
+    #
+    #   chain = dist.to_chain
+    #
+    # Operators migrate between Distribution strategies via
+    # Pangea::Magma::Migration (M0.2).
+    class Distribution
+      STRATEGIES = %i[tier_separation single_workspace per_provider custom].freeze
+
+      class << self
+        def declare(strategy:, tiers: {}, edges: {}, placement: {})
+          unless STRATEGIES.include?(strategy)
+            raise ArgumentError,
+                  "unknown strategy #{strategy.inspect}; expected one of #{STRATEGIES.inspect}"
+          end
+          new(strategy: strategy, tiers: tiers, edges: edges, placement: placement)
+        end
+      end
+
+      attr_reader :strategy, :tiers, :edges, :placement
+
+      def initialize(strategy:, tiers:, edges:, placement:)
+        @strategy  = strategy
+        @tiers     = tiers
+        @edges     = edges
+        @placement = placement
+      end
+
+      # Convert the distribution to a Pangea::Magma::Chain.
+      # For :tier_separation: build a chain with tier-level edges; each
+      # workspace in a tier links to every workspace in the depending
+      # tier via the canonical outputs.
+      #
+      # For M0.1 this is a structural conversion — full typed-output
+      # wiring per tier requires the workspaces to declare their I/O
+      # slots, which is the M0.1 Workspace.declare path.
+      def to_chain
+        case @strategy
+        when :tier_separation
+          tier_separation_chain
+        when :single_workspace
+          single_workspace_chain
+        when :per_provider, :custom
+          raise NotImplementedError,
+                "Distribution.to_chain(strategy=#{@strategy}) — M0.3"
+        end
+      end
+
+      def to_h
+        {
+          strategy:  @strategy.to_s,
+          tiers:     @tiers.transform_values { |ws_list| ws_list.map { |w| w.name.to_s } },
+          edges:     @edges.transform_keys(&:to_s).transform_values(&:to_s),
+          placement: @placement.transform_keys(&:to_s),
+        }
+      end
+
+      def to_json(*args)
+        to_h.to_json(*args)
+      end
+
+      private
+
+      def tier_separation_chain
+        Chain.build do |c|
+          @tiers.each_value { |ws_list| ws_list.each { |w| c.workspace(w) } }
+          # M0.1: structural edges from each upstream-tier workspace
+          # to each downstream-tier workspace through declared I/O.
+          # Authors declare the typed edges explicitly in M0.x once
+          # tier-level output projection is defined.
+        end
+      end
+
+      def single_workspace_chain
+        all = @tiers.values.flatten
+        Chain.compose(all, output_propagation: :in_memory)
+      end
+    end
+  end
+end

data/lib/pangea/magma/matchers.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require_relative '../magma'
+
+module Pangea
+  module Magma
+    # RSpec custom matchers for "this workspace works under magma".
+    #
+    # # Usage
+    #
+    #   require 'pangea/magma/matchers'
+    #
+    #   RSpec.describe 'seph-vpc workspace' do
+    #     it 'plans cleanly under magma' do
+    #       expect('workspaces/seph-vpc').to plan_cleanly_under_magma
+    #     end
+    #
+    #     it 'declares the expected providers' do
+    #       expect('workspaces/seph-vpc').to plan_cleanly_under_magma
+    #         .with_provider('hashicorp/aws')
+    #     end
+    #
+    #     it 'emits at least 3 resource changes' do
+    #       expect('workspaces/seph-vpc').to plan_cleanly_under_magma
+    #         .with_at_least(3).resource_changes
+    #     end
+    #
+    #     it 'is compatible with magma backend' do
+    #       expect('workspaces/seph-vpc').to be_compatible_with_backend('magma')
+    #     end
+    #   end
+    #
+    # All matchers skip-with-print when magma isn't installed so CI on
+    # machines without the magma binary doesn't fail hard.
+    module Matchers
+      class PlanCleanlyUnderMagma
+        def initialize
+          @required_providers = []
+          @min_resource_changes = nil
+          @resource_types = []
+        end
+
+        # @return self — chains: `with_provider('hashicorp/aws')`
+        def with_provider(source)
+          @required_providers << source
+          self
+        end
+
+        # Alias to read more naturally before `.resource_changes`
+        def with_at_least(n)
+          @min_resource_changes = n
+          self
+        end
+
+        # No-op terminator — lets the chain read
+        # `.with_at_least(3).resource_changes` naturally.
+        def resource_changes
+          self
+        end
+
+        # @return self — chains: `with_resource_type('aws_vpc')`
+        def with_resource_type(type)
+          @resource_types << type
+          self
+        end
+
+        def matches?(workspace_path)
+          unless Pangea::Magma.installed?
+            @failure_message = "magma binary not installed (set MAGMA_BINARY or install)"
+            return false
+          end
+          @report = Pangea::Magma.verify_workspace(workspace_path)
+
+          unless @report.dig('compatibility', 'plans_cleanly')
+            @failure_message = "workspace #{workspace_path} did not plan cleanly: #{@report.inspect}"
+            return false
+          end
+
+          @required_providers.each do |source|
+            unless Array(@report['providers']).include?(source)
+              @failure_message = "expected provider #{source.inspect}; got #{@report['providers']}"
+              return false
+            end
+          end
+
+          if @min_resource_changes
+            actual = @report['resource_change_count'].to_i
+            if actual < @min_resource_changes
+              @failure_message = "expected ≥#{@min_resource_changes} resource changes; got #{actual}"
+              return false
+            end
+          end
+
+          @resource_types.each do |type|
+            unless Array(@report['resource_types']).include?(type)
+              @failure_message = "expected resource type #{type.inspect}; got #{@report['resource_types']}"
+              return false
+            end
+          end
+          true
+        rescue Pangea::Magma::VerificationFailed => e
+          @failure_message = "magma fixture verify raised: #{e.message}"
+          false
+        end
+
+        def failure_message
+          @failure_message || "expected workspace to plan cleanly under magma"
+        end
+
+        def failure_message_when_negated
+          "expected workspace not to plan cleanly under magma, but it did:\n#{@report.inspect}"
+        end
+
+        def description
+          desc = +"plan cleanly under magma"
+          desc << " with providers #{@required_providers.inspect}" unless @required_providers.empty?
+          desc << " emitting ≥#{@min_resource_changes} resource_changes" if @min_resource_changes
+          desc << " declaring resource types #{@resource_types.inspect}" unless @resource_types.empty?
+          desc
+        end
+      end
+
+      class CompatibleWithBackend
+        def initialize(backend)
+          @backend = backend
+          @requires = {}
+        end
+
+        # @example .requiring_feature(:in_memory_pipeline)
+        def requiring_feature(feature)
+          @requires[:feature] = feature
+          self
+        end
+
+        # @example .requiring_input_format('terraform-json')
+        def requiring_input_format(format)
+          @requires[:input_format] = format
+          self
+        end
+
+        def matches?(_workspace_path_or_nil = nil)
+          Pangea::Backend.verify_compatible!(@backend, @requires)
+          true
+        rescue Pangea::Backend::BackendIncompatible => e
+          @failure_message = e.message
+          false
+        rescue Pangea::Backend::BackendUnavailable => e
+          @failure_message = "backend #{@backend} unavailable: #{e.message}"
+          false
+        end
+
+        def failure_message
+          @failure_message || "expected backend #{@backend} to be compatible with requires=#{@requires.inspect}"
+        end
+
+        def description
+          "be compatible with backend #{@backend.inspect}"
+        end
+      end
+
+      def plan_cleanly_under_magma
+        PlanCleanlyUnderMagma.new
+      end
+
+      def be_compatible_with_backend(name)
+        CompatibleWithBackend.new(name)
+      end
+    end
+  end
+end
+
+if defined?(RSpec)
+  RSpec.configure do |config|
+    config.include Pangea::Magma::Matchers
+  end
+end

data/lib/pangea/magma/migration.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'runner'
+
+module Pangea
+  module Magma
+    # Typed state-organization migration — the load-bearing surgical
+    # operation per theory/PANGEA-MAGMA-ORCHESTRATION.md §III.3 + §V.
+    #
+    # Migrations move resources from one workspace's state to another
+    # without recreate, preserving identity (ARNs, UUIDs, etc.).
+    #
+    # Authors:
+    #
+    #   migration = Pangea::Magma::Migration.declare(
+    #     from: :k3s_permissions,
+    #     to:   :platform_iam,
+    #     resources: [
+    #       { kind: :managed,
+    #         address:     'aws_iam_role.k3s_node',
+    #         new_address: 'aws_iam_role.platform_k3s_node' },
+    #     ],
+    #     preserve: [:resource_identity, :tags, :dependent_resources],
+    #     dry_run: true,
+    #   )
+    #
+    #   plan = migration.plan
+    #   plan.summary    # human-readable summary
+    #   plan.apply!     # → `magma migrate <plan.json>`
+    #
+    # The Rust-side `magma_migrate::Migration` + `magma migrate`
+    # subcommand land in M0.2; this Ruby-side declaration ships now
+    # against the typed plan-emission interface.
+    class Migration
+      ResourceMove = Struct.new(:kind, :address, :new_address,
+                                :new_address_pattern, :identity,
+                                keyword_init: true) do
+        def to_h
+          { kind: kind.to_s, address: address, new_address: new_address,
+            new_address_pattern: new_address_pattern,
+            identity: identity }.compact
+        end
+      end
+
+      # Typed migration plan — returned by Migration#plan; consumed by
+      # `magma migrate` subprocess + dry-run inspection.
+      class Plan
+        attr_reader :migration, :actions, :would_recreate, :warnings
+
+        def initialize(migration:, actions:, would_recreate: [], warnings: [])
+          @migration      = migration
+          @actions        = actions
+          @would_recreate = would_recreate
+          @warnings       = warnings
+        end
+
+        def invariants_satisfied?
+          @would_recreate.empty?
+        end
+
+        def summary
+          lines = []
+          lines << "Migration: #{@migration.from} → #{@migration.to}"
+          lines << "  #{@actions.size} action(s)"
+          lines << "  recreates: #{@would_recreate.size}" if @would_recreate.any?
+          lines << "  warnings: #{@warnings.size}" if @warnings.any?
+          lines.join("\n")
+        end
+
+        # Apply the typed Plan via `magma migrate <plan.json>`. Returns
+        # the parsed `MigrationReceipt` Hash on success (with BLAKE3
+        # state-file hashes pre/post per
+        # theory/PANGEA-MAGMA-ORCHESTRATION.md §V). Raises on either
+        # invariant violation or magma exit≠0.
+        def apply!
+          raise InvariantViolation,
+                "would recreate: #{@would_recreate.inspect}" unless invariants_satisfied?
+
+          unless @migration.from_state_path
+            raise ArgumentError,
+                  "Migration#apply! requires from_state_path — declare with " \
+                  "`from_state_path: 'workspaces/<src>/terraform.tfstate'` " \
+                  "(see theory/PANGEA-MAGMA-ORCHESTRATION.md §V)"
+          end
+          unless @migration.to_state_path
+            raise ArgumentError,
+                  "Migration#apply! requires to_state_path — declare with " \
+                  "`to_state_path: 'workspaces/<dst>/terraform.tfstate'`"
+          end
+
+          # Render typed MigrationPlan JSON that `magma migrate` consumes
+          # directly (the on-disk shape of magma_migrate::MigrationPlan)
+          # and dispatch through the shared Runner. The Runner owns
+          # tempfile cleanup + error capture.
+          Runner.invoke('migrate', json_arg: {
+            from: { name: @migration.from.to_s, state_path: @migration.from_state_path },
+            to:   { name: @migration.to.to_s,   state_path: @migration.to_state_path   },
+            moves: @actions.map { |a| { source_address: a.address, target_address: a.new_address } },
+            preserve: {
+              resource_identity:    @migration.preserve.include?(:resource_identity),
+              tags:                 @migration.preserve.include?(:tags),
+              dependent_resources:  @migration.preserve.include?(:dependent_resources),
+            },
+            dry_run: @migration.dry_run,
+          })
+        end
+
+        def to_h
+          {
+            migration: @migration.to_h,
+            actions:   @actions.map(&:to_h),
+            would_recreate: @would_recreate,
+            warnings:  @warnings,
+          }
+        end
+
+        def to_json(*args)
+          to_h.to_json(*args)
+        end
+      end
+
+      # Inherits from Pangea::Magma::Error so `rescue
+      # Pangea::Magma::Error` catches every typed magma failure.
+      class InvariantViolation < Pangea::Magma::Error; end
+
+      class << self
+        def declare(from:, to:, resources:, preserve: [:resource_identity],
+                    dry_run: true, from_state_path: nil, to_state_path: nil)
+          raise ArgumentError, 'from required' if from.nil?
+          raise ArgumentError, 'to required'   if to.nil?
+          raise ArgumentError, 'resources required, got empty' if resources.empty?
+
+          moves = resources.map { |r| ResourceMove.new(**r) }
+          new(from: from.to_sym, to: to.to_sym,
+              resources: moves, preserve: preserve, dry_run: dry_run,
+              from_state_path: from_state_path, to_state_path: to_state_path)
+        end
+      end
+
+      attr_reader :from, :to, :resources, :preserve, :dry_run,
+                  :from_state_path, :to_state_path
+
+      def initialize(from:, to:, resources:, preserve:, dry_run:,
+                     from_state_path: nil, to_state_path: nil)
+        @from            = from
+        @to              = to
+        @resources       = resources
+        @preserve        = preserve
+        @dry_run         = dry_run
+        @from_state_path = from_state_path
+        @to_state_path   = to_state_path
+      end
+
+      # Produce a typed Plan. M0.1 stub: emits a 1:1 action per
+      # declared ResourceMove + checks for obvious recreate triggers.
+      # M0.2 replaces this with a real `magma migrate plan` call.
+      def plan
+        actions = @resources.map do |r|
+          ResourceMove.new(
+            kind:        r.kind || :managed,
+            address:     r.address,
+            new_address: r.new_address || r.address,
+            identity:    "<resolved-at-runtime>",
+          )
+        end
+        # Identify any resource whose preserve flags can't be satisfied
+        # at the declared level. M0.1 placeholder: empty list.
+        would_recreate = []
+        warnings = []
+        warnings << "address-pattern moves require M0.2 magma migrate to expand" if
+          @resources.any? { |r| r.new_address_pattern }
+
+        Plan.new(migration: self, actions: actions,
+                 would_recreate: would_recreate, warnings: warnings)
+      end
+
+      def to_h
+        {
+          from:            @from.to_s,
+          to:              @to.to_s,
+          resources:       @resources.map(&:to_h),
+          preserve:        @preserve.map(&:to_s),
+          dry_run:         @dry_run,
+          from_state_path: @from_state_path,
+          to_state_path:   @to_state_path,
+        }.compact
+      end
+
+      def to_json(*args)
+        to_h.to_json(*args)
+      end
+    end
+  end
+end