empeira 0.1.0.pre.alpha.1

data/lib/empeira/node/inventory.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Node
+    # rubocop:disable-next Metrics/ModuleLength -- Provider inventories share one explicit ownership envelope.
+    module Inventory
+      def self.valid?(nodes)
+        return false unless nodes.is_a?(Hash)
+
+        nodes.all? { |name, record| valid_record?(name, record) }
+      end
+
+      def self.valid_record?(name, record)
+        return false unless record.is_a?(Hash) && record['hostname'] == name && valid_name?(name)
+        return false unless valid_guest_settings?(record)
+
+        case record['provider']
+        when 'container' then valid_container?(record)
+        when 'vm' then valid_vm?(name, record)
+        else false
+        end
+      end
+
+      def self.valid_guest_settings?(record)
+        CommandMocks.valid_inventory?(record.fetch('command_mocks', {})) &&
+          (!record.key?('runtime_proxy') || RuntimeProxy.valid_inventory?(record['runtime_proxy'])) &&
+          (!record.key?('interactive_tools') || InteractiveTools.valid_inventory?(record['interactive_tools'])) &&
+          valid_fact_revision?(record)
+      end
+
+      def self.valid_fact_revision?(record)
+        return true unless record.key?('empeira_fact')
+
+        record['empeira_fact'].is_a?(String) && record['empeira_fact'].match?(/\A[0-9a-f]{64}\z/)
+      end
+
+      def self.valid_container?(record)
+        Runtime.registry.names.include?(record['runtime']) &&
+          [true, false].include?(record['provisioned']) &&
+          valid_definition?(record) && valid_metadata?(record) && valid_ssh?(record)
+      end
+
+      def self.valid_ssh?(record)
+        return true unless record.key?('ssh_host') || record.key?('ssh_port')
+
+        record['ssh_host'] == '127.0.0.1' && %w[loopback tunnel].include?(record['ssh_transport']) &&
+          (record['ssh_port'].nil? || (record['ssh_port'].is_a?(Integer) && record['ssh_port'].between?(1, 65_535)))
+      end
+
+      def self.valid_vm?(name, record)
+        valid_vm_image?(record['base_image']) && valid_vm_process?(record) &&
+          valid_vm_network?(name, record) && valid_vm_metadata?(record) &&
+          valid_vm_management_layout?(record) &&
+          (!record.key?('network_interfaces') || ::Empeira::VM::Interfaces.valid_inventory?(record['network_interfaces']))
+      end
+
+      def self.valid_vm_management_layout?(record)
+        record['management_layout'] == ::Empeira::VM::Management::VERSION && valid_management_socket?(record)
+      end
+
+      def self.valid_management_socket?(record)
+        valid_socket_identity?(record['management_socket']) && valid_management_slots?(record)
+      end
+
+      # rubocop:disable-next Metrics/CyclomaticComplexity -- Match all slot identities and the original primary endpoint.
+      def self.valid_management_slots?(record)
+        return true unless record.key?('management_sockets')
+
+        slots = record['management_sockets']
+        slots.is_a?(Hash) && slots.keys.sort == (0...::Empeira::VM::Management::SLOTS).map(&:to_s) &&
+          slots.values.all? { |value| !value.nil? && valid_socket_identity?(value) } &&
+          slots['0'] == record['management_socket']
+      end
+
+      def self.valid_socket_identity?(socket)
+        socket.nil? || (socket.is_a?(Hash) && socket.keys.sort == %w[device inode] &&
+          socket.values.all? { |value| value.is_a?(Integer) && value >= 0 })
+      end
+
+      def self.valid_vm_image?(image)
+        return false unless image.is_a?(Hash)
+
+        required = %w[distribution version architecture source revision checksum]
+        required.all? { |key| image[key].is_a?(String) && !image[key].empty? } &&
+          image['source'].start_with?('https://') &&
+          image['checksum'].match?(/\A[0-9a-f]{64}\z/)
+      end
+
+      def self.valid_vm_process?(record)
+        record['engine'] == 'qemu' && %w[kvm hvf].include?(record['accelerator']) &&
+          %w[amd64 arm64].include?(record['architecture']) &&
+          valid_vm_resources?(record) && valid_vm_identity?(record)
+      end
+
+      def self.valid_vm_resources?(record)
+        %w[memory cpus].all? { |key| record[key].is_a?(Integer) && record[key].positive? }
+      end
+
+      def self.valid_vm_identity?(record)
+        (record['pid'].nil? || (record['pid'].is_a?(Integer) && record['pid'].positive?)) &&
+          %w[preparing running stopped].include?(record['state'])
+      end
+
+      def self.valid_vm_network?(name, record)
+        record['overlay'] == "vms/#{name}/disk.qcow2" &&
+          record['network'].is_a?(String) && record['network'].match?(/\A[a-f0-9]{24}:environment\z/) &&
+          record['mac_address'].is_a?(String) &&
+          record['mac_address'].match?(/\A52:54:(?:[0-9a-f]{2}:){3}[0-9a-f]{2}\z/)
+      end
+
+      def self.valid_vm_metadata?(record)
+        valid_certificate?(record['certificate_key']) && [true, false].include?(record['provisioned']) &&
+          %w[os version created_at].all? { |key| record[key].is_a?(String) && !record[key].empty? }
+      end
+
+      def self.valid_definition?(record)
+        definition = record['definition']
+        definition.is_a?(Hash) && definition['hostname'] == record['hostname'] &&
+          definition['image'] == record['image'] && valid_id?(record['id'])
+      end
+
+      def self.valid_metadata?(record)
+        %w[amd64 arm64].include?(record['architecture']) && valid_certificate?(record['certificate_key']) &&
+          %w[os version image created_at].all? do |key|
+            record[key].is_a?(String) && !record[key].empty?
+          end
+      end
+
+      def self.valid_certificate?(key)
+        key.nil? || (key.is_a?(String) && key.match?(/\A[a-f0-9]{64}\z/))
+      end
+
+      def self.valid_id?(id)
+        id.nil? || (id.is_a?(String) && id.match?(/\A[a-zA-Z0-9][a-zA-Z0-9_.-]*\z/))
+      end
+
+      def self.valid_name?(name)
+        name.is_a?(String) && name.size <= 253 &&
+          name.split('.', -1).all? { |label| label.match?(/\A[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\z/) }
+      end
+    end
+  end
+end

data/lib/empeira/node/package_bootstrap.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Node
+    class PackageBootstrap
+      FAMILIES = {
+        'ubuntu' => 'debian', 'debian' => 'debian',
+        'rhel' => 'redhat', 'rocky' => 'redhat', 'almalinux' => 'redhat', 'oraclelinux' => 'redhat'
+      }.freeze
+      ACTIONS = %w[install remove].freeze
+      GROUPS = %w[default debian redhat].freeze
+
+      # rubocop:disable-next Metrics/CyclomaticComplexity -- Validate the two-level public package matrix in place.
+      def self.validate!(value, path = 'bootstrap.packages', effective: false)
+        unless valid_keys?(value, ACTIONS, effective)
+          raise ConfigurationError, "#{path} must contain only install and remove mappings"
+        end
+
+        value.each do |action, groups|
+          unless valid_keys?(groups, GROUPS, effective)
+            raise ConfigurationError, "#{path}.#{action} must contain only default, debian and redhat arrays"
+          end
+
+          groups.each do |family, packages|
+            next if packages.is_a?(Array) && packages.all? { |package| valid_package?(package) }
+
+            raise ConfigurationError, "#{path}.#{action}.#{family} must contain valid nonempty package names"
+          end
+        end
+      end
+
+      def self.valid_keys?(value, permitted, effective)
+        value.is_a?(Hash) && value.keys.all? { |key| permitted.include?(key) } &&
+          (!effective || value.keys.sort == permitted.sort)
+      end
+
+      def self.valid_package?(package)
+        package.is_a?(String) && package == package.strip && !package.empty? &&
+          !package.start_with?('-') && !package.match?(/[\x00-\x20\x7f]/)
+      end
+
+      def initialize(config:, os:, execute:, copy: nil, progress: nil, rpm_options: [])
+        @config = config
+        @os = os
+        @execute = execute
+        @copy = copy
+        @progress = progress || ->(_message) {}
+        @rpm_options = rpm_options
+      end
+
+      def required?
+        ACTIONS.any? { |action| packages(action).any? }
+      end
+
+      def run(proxy_url:)
+        return unless required?
+
+        @proxy_url = proxy_url
+        @package_proxy = PackageProxy.new(family: family, execute: @execute, copy: @copy)
+        @package_proxy.prepare(proxy_url)
+        execute('remove', packages('remove'))
+        execute('update', []) if packages('install').any?
+        execute('install', packages('install'))
+      ensure
+        @package_proxy&.cleanup
+      end
+
+      private
+
+      def family
+        FAMILIES.fetch(@os) { raise ConfigurationError, "Unsupported package-bootstrap distribution: #{@os}" }
+      end
+
+      def packages(action)
+        values = @config.fetch(action)
+        (values.fetch('default') + values.fetch(family)).uniq
+      end
+
+      def execute(action, packages)
+        return if action != 'update' && packages.empty?
+
+        @progress.call(progress_message(action, packages.size))
+        arguments = command(action, packages)
+        result = @execute.call(arguments)
+        return if result.success?
+
+        raise_failure(action, result)
+      end
+
+      def raise_failure(action, result)
+        manager = family == 'debian' ? 'apt-get' : 'dnf'
+        text = PackageProxy.redact("#{result.stderr}\n#{result.stdout}", @proxy_url)
+        detail = Execution::Diagnostics.native(result.with(stderr: text, stdout: ''),
+                                               operation: "Package bootstrap #{action}", tool: manager)
+        raise Error, "Package bootstrap #{action} failed with #{manager} " \
+                     "(exit=#{result.exit_status}, timeout=#{result.timed_out}); " \
+                     "node retained and Puppet was not run\n#{detail}", cause: nil
+      end
+
+      def progress_message(action, count)
+        return 'Refreshing package metadata...' if action == 'update'
+
+        verb = action == 'remove' ? 'Removing' : 'Installing'
+        "#{verb} #{count} package#{'s' unless count == 1}..."
+      end
+
+      def command(action, packages)
+        return apt_command(action, packages) if family == 'debian'
+
+        dnf_command(action, packages)
+      end
+
+      def apt_command(action, packages)
+        if action == 'update'
+          return ['apt-get', *@package_proxy.arguments, '-o', 'APT::Update::Error-Mode=any',
+                  'update']
+        end
+
+        ['apt-get', *@package_proxy.arguments, action, '--yes', '--', *packages]
+      end
+
+      def dnf_command(action, packages)
+        return ['dnf', *@package_proxy.arguments, *@rpm_options, 'makecache'] if action == 'update'
+
+        ['dnf', *@package_proxy.arguments, *@rpm_options, action, '--assumeyes', '--', *packages]
+      end
+    end
+  end
+end

data/lib/empeira/node/package_proxy.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'tempfile'
+require 'uri'
+
+module Empeira
+  module Node
+    # One private guest configuration for APT/DNF proxy credentials; never put them in argv.
+    class PackageProxy
+      APT_PATH = '/etc/apt/apt.conf.d/00-empeira-agent-proxy'
+      DNF_PATH = '/var/tmp/empeira-agent-dnf.conf'
+
+      def initialize(family:, execute:, copy:)
+        @family = family
+        @execute = execute
+        @copy = copy
+      end
+
+      def self.copy_text(copy, content, destination, mode: '0600')
+        Tempfile.create('empeira-agent-') do |file|
+          file.chmod(0o600)
+          file.write(content)
+          file.flush
+          copy.call(file.path, destination, mode)
+        end
+      end
+
+      def self.redact(diagnostic, proxy_url)
+        values = URI(proxy_url).userinfo.to_s.split(':') if proxy_url
+        values = [*values, ENV.fetch('EMPEIRA_AGENT_REPO_USERNAME', nil), ENV.fetch('EMPEIRA_AGENT_REPO_PASSWORD', nil)]
+        values.compact.reject(&:empty?).sort_by { |value| -value.length }
+              .reduce(diagnostic) { |text, value| text.gsub(value, '[REDACTED]') }
+      end
+
+      def prepare(url)
+        content = if @family == 'debian'
+                    "Acquire::http::Proxy #{url.dump};\nAcquire::https::Proxy #{url.dump};\n"
+                  else
+                    dnf_configuration(url)
+                  end
+        self.class.copy_text(@copy, content, path)
+      end
+
+      def arguments
+        @family == 'debian' ? ['-c', path] : ["--config=#{path}"]
+      end
+
+      def path
+        @family == 'debian' ? APT_PATH : DNF_PATH
+      end
+
+      def cleanup
+        result = @execute.call(['rm', '-f', '--', path])
+        return if result.success?
+
+        diagnostic = Execution::Diagnostics.command(result, operation: 'Temporary package proxy cleanup', tool: 'rm')
+        raise Error, "Cannot remove temporary package proxy configuration; Puppet was not run\n#{diagnostic}",
+              cause: nil
+      end
+
+      private
+
+      # rubocop:disable-next Metrics/AbcSize -- Preserve native sections while enforcing private, verified bootstrap settings.
+      def dnf_configuration(url)
+        lines = original_dnf_lines
+        main = lines.index { |line| line.strip == '[main]' }
+        raise Error, 'Original DNF configuration has no main section; Puppet was not run' unless main
+
+        finish = ((main + 1)...lines.size).find { |index| lines[index].lstrip.start_with?('[') } || lines.size
+        settings = lines[(main + 1)...finish].grep_v(/\A\s*(?:proxy(?:_[a-z_]+)?|gpgcheck|sslverify|logfilelevel)\s*=/i)
+        lines[main] = "[main]\n"
+        lines[(main + 1)...finish] = [*dnf_proxy_settings(url), *settings]
+        lines.join
+      end
+
+      def dnf_proxy_settings(url)
+        endpoint = URI(url)
+        username = endpoint.user
+        password = endpoint.password
+        endpoint.user = nil
+        endpoint.password = nil
+        settings = ["proxy=#{endpoint}\n", "gpgcheck=1\n", "sslverify=1\n", "logfilelevel=0\n"]
+        if username || password
+          settings.push("proxy_username=#{URI::DEFAULT_PARSER.unescape(username.to_s)}\n",
+                        "proxy_password=#{URI::DEFAULT_PARSER.unescape(password.to_s)}\n",
+                        "proxy_auth_method=basic\n")
+        end
+        settings
+      end
+
+      def original_dnf_lines
+        result = @execute.call(['cat', '/etc/dnf/dnf.conf'])
+        unless result.success?
+          diagnostic = Execution::Diagnostics.command(result, operation: 'Original DNF configuration', tool: 'cat')
+          raise Error, "Cannot read original DNF configuration; Puppet was not run\n#{diagnostic}", cause: nil
+        end
+
+        result.stdout.lines
+      end
+    end
+  end
+end

data/lib/empeira/node/package_sources.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Node
+    module PackageSources
+      def self.verify!(execute:)
+        script = Pathname(__dir__).join('../../../resources/nodes/apt_sources.rb').read
+        result = execute.call([Certificates::RUBY, '-e', script])
+        return if result.success?
+
+        details = Execution::Diagnostics.command(result, operation: 'Active distribution APT source verification',
+                                                         tool: 'ruby')
+        raise Error, 'Cannot verify an active Ubuntu/Debian distribution APT source before the first catalog. ' \
+                     'Check /etc/apt/sources.list and sources.list.d/*.list or *.sources in the image/bootstrap; ' \
+                     "Puppet was not run. Node retained for diagnosis.\n#{details}", cause: nil
+      end
+    end
+  end
+end

data/lib/empeira/node/puppet_command.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Node
+    module PuppetCommand
+      def self.arguments
+        [Certificates::PUPPET, 'agent', '--test', '--detailed-exitcodes', '--waitforcert', '0',
+         '--color', Execution::Terminal.color? ? 'ansi' : 'false']
+      end
+    end
+  end
+end

data/lib/empeira/node/rpm_configuration.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'pathname'
+
+module Empeira
+  module Node
+    # Restore native DNF repository configuration after the temporary agent source.
+    class RpmConfiguration
+      DISTRIBUTIONS = %w[rocky almalinux oraclelinux rhel].freeze
+      BACKUP = '/root/.empeira-dnf-before-bootstrap.tar'
+
+      def initialize(os:, execute:, root: '/', backup: BACKUP)
+        @os = os
+        @execute = execute
+        @root = Pathname(root).cleanpath
+        @backup = Pathname(backup).cleanpath
+      end
+
+      def preserve
+        return yield unless DISTRIBUTIONS.include?(@os)
+
+        capture!
+        begin
+          yield
+        ensure
+          restore!
+        end
+      end
+
+      private
+
+      def capture!
+        execute!(['install', '--mode', '0600', '/dev/null', @backup.to_s], 'Cannot prepare DNF configuration backup')
+        execute!(['tar', '--create', '--file', @backup.to_s, '--directory', @root.to_s,
+                  'etc/yum.repos.d', 'etc/dnf'],
+                 'Cannot preserve base image DNF configuration')
+      rescue StandardError
+        @execute.call(['rm', '--force', '--', @backup.to_s])
+        raise
+      end
+
+      def restore!
+        message = 'Cannot restore and verify base image DNF configuration; ' \
+                  'Puppet was not run. Node retained for diagnosis'
+        execute!(['tar', '--list', '--file', @backup.to_s], message)
+        execute!(['rm', '--recursive', '--force', '--', @root.join('etc/yum.repos.d').to_s,
+                  @root.join('etc/dnf').to_s], message)
+        execute!(['tar', '--extract', '--file', @backup.to_s, '--directory', @root.to_s], message)
+        execute!(['tar', '--compare', '--file', @backup.to_s, '--directory', @root.to_s], message)
+        execute!(['rm', '--force', '--', @backup.to_s], message)
+      end
+
+      def execute!(arguments, message)
+        result = @execute.call(arguments)
+        return if result.success?
+
+        details = Execution::Diagnostics.command(result, operation: message, tool: arguments.first)
+        raise Error, "#{message}\n#{details}", cause: nil
+      end
+    end
+  end
+end

data/lib/empeira/node/run_request.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Node
+    RunRequest = Data.define(:hostname, :provider, :os, :version, :memory, :cpus) do
+      def self.from_config(hostname:, provider:, config:)
+        defaults = config.fetch('node_defaults').slice('os', 'version', 'memory', 'cpus')
+        new(hostname: hostname, provider: provider, **defaults.transform_keys(&:to_sym))
+      end
+
+      def initialize(**attributes)
+        validate_hostname!(attributes.fetch(:hostname))
+        unless Node.registry.names.include?(attributes.fetch(:provider))
+          raise Error, "provider must be one of: #{Node.registry.names.join(', ')}"
+        end
+
+        validate_resources!(attributes)
+        validate_os!(attributes)
+        super(**attributes.transform_values { |value| value.is_a?(String) ? value.dup.freeze : value })
+      end
+
+      private
+
+      def validate_resources!(attributes)
+        %i[memory cpus].each do |key|
+          value = attributes.fetch(key)
+          next if value.nil? || (value.is_a?(Integer) && value.positive?)
+
+          raise Error, "#{key} must be a positive integer or null"
+        end
+      end
+
+      def validate_os!(attributes)
+        %i[os version].each do |key|
+          value = attributes.fetch(key)
+          next if value.nil? || (value.is_a?(String) && !value.strip.empty? && value == value.strip)
+
+          raise Error, "#{key} must be a non-empty string without surrounding whitespace or null"
+        end
+      end
+
+      def validate_hostname!(hostname)
+        label = /\A[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\z/
+        return if hostname.is_a?(String) && !hostname.empty? && hostname.length <= 64 &&
+                  hostname.split('.', -1).all? { |part| part.match?(label) }
+
+        raise Error, 'hostname must contain DNS labels of 1 to 63 letters, digits or internal hyphens ' \
+                     'and fit the 64-byte guest kernel hostname limit'
+      end
+    end
+  end
+end

data/lib/empeira/node/runtime_proxy.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Node
+    # Normal, credential-free guest policy, after verified bootstrap cleanup.
+    class RuntimeProxy
+      VARIABLES = %w[HTTP_PROXY HTTPS_PROXY http_proxy https_proxy NO_PROXY no_proxy ALL_PROXY all_proxy].freeze
+
+      def initialize(context:, record:, execute:, persist:)
+        @context = context
+        @record = record
+        @execute = execute
+        @persist = persist
+      end
+
+      def self.command(context, arguments)
+        environment = ControlPlane::Plan.new(context: context).node_proxy_environment
+        ['env', *VARIABLES.map { |key| "#{key}=#{environment.fetch(key, '')}" }, *arguments]
+      end
+
+      def self.valid_inventory?(entry)
+        entry.is_a?(Hash) && (entry.keys - %w[current previous]).empty? && entry.key?('current') &&
+          [entry['current'], entry['previous']].compact.all? { |definition| valid_definition?(definition) }
+      end
+
+      def self.valid_definition?(definition)
+        definition.is_a?(Hash) && definition.keys.sort == %w[direct no_proxy url] &&
+          definition['url'] == 'http://proxy.empeira.internal:3128' &&
+          definition['no_proxy'].is_a?(String) && definition['no_proxy'].match?(/\A[a-zA-Z0-9.,:-]+\z/) &&
+          valid_direct?(definition['direct'])
+      end
+
+      def self.valid_direct?(hosts)
+        hosts.is_a?(Array) && hosts.all? do |host|
+          host.is_a?(String) && host.match?(/\A[a-zA-Z0-9][a-zA-Z0-9.-]*\z/)
+        end
+      end
+
+      def reconcile
+        desired = definition
+        entry = @record['runtime_proxy']
+        return false unless desired || entry
+
+        recovered = recover(entry) if entry&.key?('previous')
+        previous = [entry&.fetch('current')].compact
+        @record['runtime_proxy'] = { 'current' => desired, 'previous' => previous.first }
+        @persist.call
+        changed = execute(desired, previous)
+        @record['runtime_proxy'] = { 'current' => desired }
+        @persist.call
+        changed || recovered || false
+      end
+
+      private
+
+      def recover(entry)
+        execute(entry.fetch('current'), [entry['current'], entry['previous']].compact)
+      end
+
+      def definition
+        environment = ControlPlane::Plan.new(context: @context).node_proxy_environment
+        return if environment.empty?
+
+        naming = Network::Naming.new
+        internal = naming.reserved(@context.configuration).flat_map { |name| naming.aliases(name) }
+        { 'url' => environment.fetch('http_proxy'), 'no_proxy' => environment.fetch('no_proxy'),
+          'direct' => ['localhost', '127.0.0.1', *internal,
+                       *Network::DirectEgress.destinations(@context.configuration.dig('network', 'egress'))].uniq }
+      end
+
+      def execute(desired, previous)
+        helper = Pathname(__dir__).join('../../../resources/nodes/runtime_proxy.rb').read
+        request = JSON.generate('desired' => desired, 'accepted' => [desired, *previous].compact)
+        result = @execute.call([Certificates::RUBY, '-e', helper, request])
+        unless result.success?
+          details = Execution::Diagnostics.command(result, operation: 'Normal guest proxy reconciliation', tool: 'ruby')
+          raise Error, "Cannot reconcile normal guest proxy; node retained for diagnosis\n#{details}", cause: nil
+        end
+
+        JSON.parse(result.stdout).fetch('changed')
+      rescue JSON::ParserError, KeyError
+        raise Error, 'Cannot verify normal guest proxy reconciliation; node retained for diagnosis', cause: nil
+      end
+    end
+  end
+end

data/lib/empeira/node/service.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Node
+    class Service
+      # Preserve explicit injection at the existing provider composition boundary.
+      # rubocop:disable-next Metrics/ParameterLists
+      def initialize(context:, runner:, providers: Node.registry, runtimes: Runtime.registry, engines: ::Empeira::VM.registry,
+                     build_info: BuildInfo.load, progress: Progress.new, ssh_preferences: {})
+        @context = context
+        @runner = runner
+        @providers = providers
+        @ssh_preferences = Configuration::SSHPreferences.new(ssh_preferences)
+        @dependencies = { context: context, runner: runner, runtimes: runtimes, engines: engines,
+                          build_info: build_info, progress: progress }
+      end
+
+      def run(request)
+        provider(request.provider).run(request)
+      end
+
+      %i[start stop inspect_resource shell console exec puppet logs].each do |operation|
+        define_method(operation) do |name:, **options|
+          record = Infrastructure::Store.new(context: @context).load&.dig('nodes', name.downcase)
+          selected = record&.fetch('provider') || 'container'
+          provider(selected).public_send(operation, name: name, **options)
+        end
+      end
+
+      def destroy(name:)
+        Infrastructure::Cleanup.new(context: @context, runner: @runner,
+                                    runtimes: @dependencies.fetch(:runtimes),
+                                    progress: @dependencies.fetch(:progress)).node(name)
+      end
+
+      def ssh(name:, user: nil, identity: nil, port: nil)
+        record = Infrastructure::Store.new(context: @context).load&.dig('nodes', name.downcase)
+        options = @ssh_preferences.resolve(hostname: name, user: user, identity: identity, port: port)
+        provider(record&.fetch('provider') || 'container').ssh(name: name, **options)
+      end
+
+      def list
+        provider('container').list + provider('vm').list
+      end
+
+      def names
+        Infrastructure::Store.new(context: @context).load&.fetch('nodes', {})&.keys || []
+      end
+
+      # The infrastructure caller already holds the workspace mutation lock.
+      # rubocop:disable-next Naming/PredicateMethod -- Reconciliation mutates guest resources.
+      def reconcile(state:)
+        return false unless state
+
+        records = state.fetch('nodes', {}).values
+        reconciliation_providers(records).map do |name|
+          provider(name).reconcile_all(state: state)
+        end.any?
+      end
+
+      private
+
+      def reconciliation_providers(records)
+        records.map { |record| record.fetch('provider') }.uniq
+      end
+
+      def provider(name)
+        @providers.build(name, **@dependencies)
+      end
+    end
+  end
+end