rubik 0.1.0

data/lib/rubik/runtime/diagnostic_engine.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require_relative "../platform"
+
+module Rubik
+  module Runtime
+    class ExecutionFailure
+      attr_reader :cmd, :exit_code, :stdout, :stderr, :duration, :category, :suggestion, :metadata, :timestamp
+
+      def initialize(cmd:, exit_code:, stdout: "", stderr: "", duration: 0.0, category: :unknown_failure, suggestion: nil, metadata: {})
+        @cmd = cmd.to_s
+        @exit_code = exit_code.to_i
+        @stdout = stdout.to_s
+        @stderr = stderr.to_s
+        @duration = duration.to_f
+        @category = category.to_sym
+        @suggestion = suggestion.to_s
+        @metadata = metadata || {}
+        @timestamp = begin
+          Time.now.utc.iso8601
+        rescue NoMethodError
+          Time.now.to_s
+        end
+      end
+
+      def to_h
+        {
+          cmd: @cmd,
+          exit_code: @exit_code,
+          stdout: @stdout,
+          stderr: @stderr,
+          duration: @duration,
+          category: @category,
+          suggestion: @suggestion,
+          metadata: @metadata,
+          timestamp: @timestamp
+        }
+      end
+
+      def format_for_llm
+        lines = [
+          "=== Runtime Execution Diagnostic ===",
+          "• Command     : #{@cmd}",
+          "• Exit Code   : #{@exit_code}",
+          "• Duration    : #{@duration.round(4)}s",
+          "• Category    : #{@category.to_s.upcase}"
+        ]
+        lines << "• Stderr      : #{@stderr.strip}" unless @stderr.strip.empty?
+        lines << "• Stdout      : #{@stdout.strip}" if @stderr.strip.empty? && !@stdout.strip.empty?
+        lines << "• Suggestion  : #{@suggestion}" unless @suggestion.strip.empty?
+        lines.join("\n")
+      end
+    end
+
+    module DiagnosticEngine
+      class << self
+        def diagnose(cmd:, exit_code:, stdout: "", stderr: "", duration: 0.0, metadata: {})
+          cmd_str = cmd.to_s
+          stderr_str = stderr.to_s
+          stdout_str = stdout.to_s
+          combined = "#{stderr_str}\n#{stdout_str}"
+
+          category = determine_category(cmd_str, exit_code, stderr_str, stdout_str, combined)
+          suggestion = generate_suggestion(category, cmd_str, combined)
+
+          ExecutionFailure.new(
+            cmd: cmd_str,
+            exit_code: exit_code,
+            stdout: stdout_str,
+            stderr: stderr_str,
+            duration: duration,
+            category: category,
+            suggestion: suggestion,
+            metadata: metadata
+          )
+        end
+
+        def analyze_process_result(process_result, cmd: nil, metadata: {})
+          return nil if process_result.nil?
+
+          res_cmd = cmd || process_result[:cmd] || "unknown_command"
+          diagnose(
+            cmd: res_cmd,
+            exit_code: process_result[:exit_code] || (process_result[:ok] ? 0 : 1),
+            stdout: process_result[:stdout] || "",
+            stderr: process_result[:stderr] || (process_result[:ok] ? "" : process_result[:output].to_s),
+            duration: process_result[:duration] || 0.0,
+            metadata: metadata
+          )
+        end
+
+        # Search tools whose ONLY exit-1 meaning is "pattern matched nothing"
+        # (session review B8): grep/rg/findstr exit 1 on no match and 2 on a
+        # real error, so exit 1 + clean streams is a normal empty result, not
+        # an UNKNOWN_FAILURE alarm.
+        NO_MATCH_TOOLS = ["grep", "rg", "findstr", "ag", "ack"].freeze
+        NO_MATCH_PREFIXES = ["git grep"].freeze
+
+        private
+
+        def no_match_tool?(cmd)
+          tokens = cmd.to_s.split
+          return false if tokens.empty?
+
+          NO_MATCH_TOOLS.include?(tokens.first) || NO_MATCH_PREFIXES.any? { |p| cmd.to_s.start_with?("#{p} ") }
+        end
+
+        # Cargo plugin convention: `cargo <name>` resolves the binary
+        # `cargo-<name>` in PATH. A "no such command" from cargo therefore
+        # means the plugin is missing — name the exact install command.
+        def cargo_plugin_suggestion(cmd, combined)
+          return nil unless combined.match?(/no such (?:command|subcommand)/i)
+
+          tokens = cmd.to_s.split
+          return nil unless tokens.shift == "cargo" && tokens.first.to_s.match?(/\A[a-z][\w-]*\z/i)
+
+          plugin = tokens.first
+          "cargo's plugin binary 'cargo-#{plugin}' is not installed. Install it with " \
+            "`cargo install cargo-#{plugin}` (e.g. cargo install cargo-nextest), pick a runner that is " \
+            "installed (plain `cargo test`), or configure one via repair_runtime_service."
+        end
+
+        def determine_category(cmd, exit_code, _stderr, stdout, combined)
+          return :success if exit_code.zero?
+          return :no_match if exit_code == 1 && no_match_tool?(cmd) && stdout.strip.empty? && !combined.match?(/\b(error|fatal)\b/i)
+
+          if exit_code == 124 || combined.match?(/(timed out|timeout after|\btimeout\b)/i)
+            :timeout
+          # The second alternative is the runner-wrapper signature (e.g.
+          # cargo without its plugin): the wrapper reports on stderr while
+          # the suite produced no output. A genuine failing suite that merely
+          # prints the phrase keeps its real category.
+          elsif (exit_code == 127 || exit_code == 9009 || exit_code == 49 ||
+                 combined.match?(/(not recognized|\bnot found\b|command not found|cannot find|bulunamad|\bENOENT\b)/i)) ||
+                (stdout.strip.empty? && combined.match?(/no such (?:command|subcommand)/i))
+            :missing_binary
+          elsif combined.match?(/(permission denied|\bEACCES\b|operation not permitted)/i)
+            :permission_denied
+          elsif combined.match?(/(unrecognized option|unknown option|invalid option|requires stdio|--stdio|flag provided but not defined|unknown flag)/i)
+            :missing_flag_or_option
+          elsif combined.match?(
+            /(cannot load such file|ModuleNotFoundError|No module named|package .* not found|bundle install|npm install|pnpm install|yarn install)/i
+          )
+            :dependency_missing
+          elsif combined.match?(/(syntax error|unexpected token|compilation error|error\[E\d+\]|parse error|fatal error)/i)
+            :syntax_or_compile_error
+          elsif combined.match?(/(failures:|assertions|tests failed|failed tests|FAILED \(|FAIL:|\d+ failures, \d+ errors)/i)
+            :test_failure
+          else
+            :unknown_failure
+          end
+        end
+
+        def generate_suggestion(category, cmd, combined)
+          bin = cmd.split.first || "command"
+
+          case category
+          when :no_match
+            "'#{cmd.split.first(2).join(' ')}' completed normally: the pattern matched nothing (exit 1 with clean " \
+            "output is success for search tools). Refine the pattern or broaden the search path instead of debugging a failure."
+          when :missing_binary
+            cargo_plugin_suggestion(cmd, combined) ||
+              "The executable binary '#{bin}' was not found in PATH or root workspace. " \
+              "Install the required tool or use `repair_runtime_service` / `!synthesize` to configure a working alternative."
+          when :missing_flag_or_option
+            "Command line flags or arguments appear invalid. Check supported flags (e.g. `--stdio`, `stdio`) " \
+            "or use `repair_runtime_service` to probe correct options."
+          when :dependency_missing
+            "Required dependencies are missing. Run appropriate package manager install " \
+            "(e.g., `bundle install`, `npm install`, `pip install`) before proceeding."
+          when :syntax_or_compile_error
+            "A syntax or compilation error occurred. Inspect the reported source file and line numbers to resolve the error."
+          when :permission_denied
+            "Permission denied for '#{bin}'. Check file permissions (chmod +x) or sandbox security constraints."
+          when :timeout
+            "Process execution exceeded timeout threshold. Increase timeout limit or investigate potential infinite loops / blocking calls."
+          when :test_failure
+            "One or more tests failed. Review assertion failure outputs and update the corresponding implementation."
+          when :success
+            "Command executed successfully."
+          else
+            "Process exited with non-zero code. Review stderr/stdout traces to investigate cause."
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubik/runtime/discovery.rb

@@ -0,0 +1,342 @@
+# frozen_string_literal: true
+
+require "shellwords"
+require_relative "../platform"
+
+module Rubik
+  module Runtime
+    module Discovery
+      LSP_CANDIDATES = {
+        "ruby" => [
+          "solargraph stdio",
+          "ruby-lsp",
+          "typeprof --lsp --stdio"
+        ],
+        "python" => [
+          "pyright-langserver --stdio",
+          "pylsp",
+          "jedi-language-server"
+        ],
+        "rust" => [
+          "rust-analyzer"
+        ],
+        "go" => [
+          "gopls"
+        ],
+        "zig" => [
+          "zls"
+        ],
+        "c" => [
+          "clangd"
+        ],
+        "cpp" => [
+          "clangd"
+        ],
+        "typescript" => [
+          "typescript-language-server --stdio",
+          "vtsls --stdio"
+        ],
+        "javascript" => [
+          "typescript-language-server --stdio",
+          "vtsls --stdio"
+        ],
+        "bash" => [
+          "bash-language-server start"
+        ],
+        "crystal" => [
+          "crystalline"
+        ],
+        "gleam" => [
+          "gleam lsp"
+        ],
+        "vue" => [
+          "vue-language-server --stdio",
+          "@vue/language-server --stdio",
+          "vls"
+        ]
+      }.freeze
+
+      FORMATTER_CANDIDATES = {
+        "ruby" => [
+          "rubocop -a",
+          "standardrb --fix",
+          "rufo"
+        ],
+        "python" => [
+          "ruff format",
+          "black"
+        ],
+        "rust" => [
+          "rustfmt"
+        ],
+        "go" => [
+          "gofmt -w",
+          "goimports -w"
+        ],
+        "c" => [
+          "clang-format -i"
+        ],
+        "cpp" => [
+          "clang-format -i"
+        ],
+        "zig" => [
+          "zig fmt"
+        ],
+        "typescript" => [
+          "prettier --write",
+          "biome format --write"
+        ],
+        "javascript" => [
+          "prettier --write",
+          "biome format --write"
+        ],
+        "node" => [
+          "prettier --write",
+          "biome format --write"
+        ],
+        "vue" => [
+          "prettier --write",
+          "biome format --write"
+        ],
+        "crystal" => [
+          "crystal tool format"
+        ]
+      }.freeze
+
+      TEST_RUNNER_MARKERS = {
+        "ruby" => [
+          { marker: "Gemfile", candidates: ["bundle exec rspec", "bundle exec rake test", "rake test"] },
+          { marker: "Rakefile", candidates: ["bundle exec rake test", "rake test"] }
+        ],
+        "python" => [
+          { marker: "pyproject.toml", candidates: ["pytest", "python3 -m unittest"] },
+          { marker: "pytest.ini", candidates: ["pytest"] },
+          { marker: "setup.py", candidates: ["pytest", "python3 -m unittest"] },
+          { marker: "requirements.txt", candidates: ["pytest", "python3 -m unittest"] }
+        ],
+        "rust" => [
+          { marker: "Cargo.toml", candidates: ["cargo nextest run", "cargo test"] }
+        ],
+        "go" => [
+          { marker: "go.mod", candidates: ["go test ./..."] }
+        ],
+        "zig" => [
+          { marker: "build.zig", candidates: ["zig build test", "zig test"] }
+        ],
+        "typescript" => [
+          { marker: "pnpm-lock.yaml", candidates: ["pnpm test"] },
+          { marker: "yarn.lock", candidates: ["yarn test"] },
+          { marker: "package-lock.json", candidates: ["npm test"] },
+          { marker: "package.json", candidates: ["npm test", "pnpm test", "yarn test"] }
+        ],
+        "javascript" => [
+          { marker: "pnpm-lock.yaml", candidates: ["pnpm test"] },
+          { marker: "yarn.lock", candidates: ["yarn test"] },
+          { marker: "package-lock.json", candidates: ["npm test"] },
+          { marker: "package.json", candidates: ["npm test", "pnpm test", "yarn test"] }
+        ],
+        "vue" => [
+          { marker: "pnpm-lock.yaml", candidates: ["pnpm test"] },
+          { marker: "yarn.lock", candidates: ["yarn test"] },
+          { marker: "bun.lockb", candidates: ["bun test"] },
+          { marker: "package-lock.json", candidates: ["npm test"] },
+          { marker: "package.json", candidates: ["npm test", "pnpm test", "yarn test", "bun test"] }
+        ],
+        "node" => [
+          { marker: "pnpm-lock.yaml", candidates: ["pnpm test"] },
+          { marker: "yarn.lock", candidates: ["yarn test"] },
+          { marker: "bun.lockb", candidates: ["bun test"] },
+          { marker: "package-lock.json", candidates: ["npm test"] },
+          { marker: "package.json", candidates: ["npm test", "pnpm test", "yarn test", "bun test"] }
+        ],
+        "c" => [
+          { marker: "CMakeLists.txt", candidates: ["ctest", "make test"] },
+          { marker: "Makefile", candidates: ["make test", "ctest"] }
+        ],
+        "crystal" => [
+          { marker: "shard.yml", candidates: ["crystal spec"] },
+          { marker: "shard.lock", candidates: ["crystal spec"] }
+        ]
+      }.freeze
+
+      DEFAULT_TEST_RUNNERS = {
+        "ruby" => "rake test",
+        "python" => "pytest",
+        "rust" => "cargo test",
+        "go" => "go test ./...",
+        "zig" => "zig test",
+        "c" => "ctest",
+        "crystal" => "crystal spec",
+        "typescript" => "npm test",
+        "javascript" => "npm test",
+        "vue" => "npm test",
+        "node" => "npm test"
+      }.freeze
+
+      class << self
+        def lsp_candidates(lang)
+          LSP_CANDIDATES[lang.to_s.downcase] || []
+        end
+
+        def binary_available?(cmd, root_dir: nil)
+          return false if cmd.nil? || cmd.to_s.strip.empty?
+
+          bin = cmd.to_s.strip.split.first
+          if root_dir && bin && (bin.include?("/") || (Rubik::Platform.windows? && bin.include?("\\")))
+            full_path = File.expand_path(bin, root_dir)
+            return true if Rubik::Platform.executable_file?(full_path)
+          end
+
+          !Rubik::Platform.which(cmd).nil?
+        end
+
+        def probe_lsp(lang, dir = nil, root_dir: nil, custom_cmd: nil)
+          effective_root = root_dir || dir || Dir.pwd
+          lang_key = lang.to_s.downcase
+          candidates = []
+          candidates << custom_cmd.to_s.strip if custom_cmd && !custom_cmd.to_s.strip.empty?
+          candidates.concat(lsp_candidates(lang_key))
+          candidates.uniq!
+
+          candidates.find { |c| binary_available?(c, root_dir: effective_root) }
+        end
+
+        def test_runner_candidates(lang, dir = nil, root_dir: nil, config: nil)
+          effective_root = root_dir || dir || Dir.pwd
+          lang_key = lang.to_s.downcase
+          marker_rules = TEST_RUNNER_MARKERS[lang_key] || []
+          matched_candidates = []
+          # Ruby-specific: a committed Gemfile.lock pins the gem stack, so any
+          # bare (non-bundler) fallback runner must be suppressed — otherwise
+          # a default-gem (e.g. minitest 6) silently diverges from the pinned
+          # stack. See _plan/test-stratifikasyonu-2026-09-14.md (Package C).
+          ruby_lock_pinned = lang_key == "ruby" &&
+                             File.exist?(File.join(effective_root, "Gemfile.lock"))
+
+          marker_rules.each do |rule|
+            marker_path = File.join(effective_root, rule[:marker])
+            next unless File.exist?(marker_path)
+
+            candidates = rule[:candidates]
+            if lang_key == "ruby" && rule[:marker] == "Gemfile"
+              has_spec_dir = File.directory?(File.join(effective_root, "spec"))
+              has_lock = File.exist?(File.join(effective_root, "Gemfile.lock"))
+              # A committed lockfile means the operator pinned the gem stack;
+              # running bare `rake`/`ruby` would bypass it and can silently
+              # load a different (e.g. default-gem) version. With a lockfile
+              # only bundler-wrapped commands are offered; without one the
+              # historical candidate order is preserved.
+              candidates = if has_spec_dir
+                             ["bundle exec rspec", "bundle exec rake test", "rake test"]
+                           elsif has_lock
+                             ["bundle exec rake test"]
+                           else
+                             ["bundle exec rake test", "rake test", "bundle exec rspec"]
+                           end
+            end
+            matched_candidates.concat(candidates)
+          end
+
+          # Add default fallback (suppressed when a ruby lockfile pins bundler)
+          default_runner = DEFAULT_TEST_RUNNERS[lang_key]
+          matched_candidates << default_runner if default_runner && !(ruby_lock_pinned && !default_runner.start_with?("bundle exec"))
+
+          # Prepend explicit test command from config if configured
+          cfg_cmd = resolve_config_test_cmd(config, lang_key)
+          matched_candidates.unshift(cfg_cmd) if cfg_cmd && !cfg_cmd.empty?
+
+          matched_candidates.uniq
+        end
+
+        def discover_test_runners(dir = nil, root_dir: nil, lang: nil, config: nil)
+          effective_root = root_dir || (dir.is_a?(String) ? dir : nil) || Dir.pwd
+          target_lang = lang ? lang.to_s.downcase : detect_primary_language(effective_root)
+          return [] unless target_lang
+
+          candidates = test_runner_candidates(target_lang, root_dir: effective_root, config: config)
+          candidates.select { |cmd| binary_available?(cmd, root_dir: effective_root) }
+        end
+
+        def discover_formatters(dir = nil, root_dir: nil, lang: nil)
+          effective_root = root_dir || (dir.is_a?(String) ? dir : nil) || Dir.pwd
+          target_lang = lang ? lang.to_s.downcase : detect_primary_language(effective_root)
+          return [] unless target_lang
+
+          candidates = FORMATTER_CANDIDATES[target_lang] || []
+          candidates.select { |cmd| binary_available?(cmd, root_dir: effective_root) }
+        end
+
+        def detect_primary_language(dir = nil, root_dir: nil)
+          effective_root = root_dir || dir || Dir.pwd
+
+          # Check root project marker files
+          return "ruby" if File.exist?(File.join(effective_root, "Gemfile")) || File.exist?(File.join(effective_root, "Rakefile"))
+          return "rust" if File.exist?(File.join(effective_root, "Cargo.toml"))
+          return "go" if File.exist?(File.join(effective_root, "go.mod"))
+          return "zig" if File.exist?(File.join(effective_root, "build.zig"))
+          return "python" if File.exist?(File.join(effective_root,
+                                                   "pyproject.toml")) || File.exist?(File.join(effective_root,
+                                                                                               "setup.py")) || File.exist?(File.join(effective_root,
+                                                                                                                                     "requirements.txt"))
+          return "typescript" if File.exist?(File.join(effective_root, "tsconfig.json"))
+          return "javascript" if File.exist?(File.join(effective_root, "package.json"))
+          return "c" if File.exist?(File.join(effective_root, "CMakeLists.txt"))
+
+          # Fallback: inspect extensions in directory
+          ext_counts = Hash.new(0)
+          begin
+            Dir.children(effective_root).each do |entry|
+              next if entry.start_with?(".")
+
+              full_p = File.join(effective_root, entry)
+              if File.file?(full_p)
+                ext = File.extname(entry).downcase
+                ext_counts[ext] += 1
+              end
+            end
+          rescue Errno::ENOENT, Errno::EACCES, Errno::ENOTDIR
+            # ignore
+          end
+
+          ext_to_lang = {
+            ".rb" => "ruby",
+            ".rs" => "rust",
+            ".go" => "go",
+            ".py" => "python",
+            ".zig" => "zig",
+            ".ts" => "typescript",
+            ".js" => "javascript",
+            ".vue" => "vue",
+            ".c" => "c",
+            ".cpp" => "c"
+          }
+
+          best_ext = ext_counts.max_by { |_ext, count| count }&.first
+          ext_to_lang[best_ext] || "ruby"
+        end
+
+        private
+
+        def resolve_config_test_cmd(config, lang_key)
+          return nil unless config
+
+          cmd = if config.is_a?(Hash)
+                  config["adapter.#{lang_key}.test_command"] ||
+                    config["project.test_command"] ||
+                    config.dig("adapter", lang_key, "test_command") ||
+                    config.dig("adapter", lang_key.to_sym, "test_command") ||
+                    config.dig("project", "test_command")
+                elsif config.respond_to?(:fetch)
+                  begin
+                    config.fetch("adapter.#{lang_key}.test_command", nil) ||
+                      config.fetch("project.test_command", nil)
+                  rescue KeyError, NoMethodError, TypeError
+                    nil
+                  end
+                end
+          cmd&.to_s&.strip
+        end
+      end
+    end
+  end
+end

data/lib/rubik/runtime/fiber.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require_relative "context"
+
+module Rubik
+  module Runtime
+    # = Rubik::Runtime::ComponentFiber
+    #
+    # Component Lifecycle Unit for Spatiotemporal Composability (AGENTS.md §2).
+    #
+    # == Architecture & State Machine:
+    # A ComponentFiber represents the running instance of a pluggable runtime component.
+    # It strictly follows the Fiber Lifecycle State Machine defined in AGENTS.md:
+    #
+    #   [Registered] -> PENDING <-------------------------+
+    #                      |                              |
+    #                      | Coeffects Satisfied          | Coeffects Lost /
+    #                      v                              | Unload Requested
+    #                    ACTIVE --------------------------+
+    #                      |
+    #                      | Error during Activation
+    #                      v
+    #                    FAILED -> (Partial Inverses / Rollback) -> DISPOSED
+    #
+    # == Distinction from Ruby's ::Fiber:
+    # Rubik::Runtime::ComponentFiber is NOT a Ruby standard library coroutine (::Fiber) or
+    # lightweight cooperative thread. Instead, it is an architectural lifecycle fiber
+    # that encapsulates a component's coeffect dependencies (:inject), scoped sub-context
+    # (@sub_context = context.extend), and LIFO effect inverses (Omega accumulator)
+    # ensuring zero-restart reloading and atomic rollback.
+    #
+    # == Concurrency Contract (review 2026-09-17, Finding 2):
+    # ComponentFiber is intentionally lock-free: correctness relies on external
+    # serialization, NOT on internal locking. State mutations (@state,
+    # @sub_context, @instance) and the multi-step activate!/deactivate! sequences
+    # MUST happen under the owning Manager's Monitor (via register_component /
+    # provide / reconcile_all / swap_component) or in single-threaded code.
+    #
+    # Why no blanket per-fiber Mutex: the factory passed to activate! runs while
+    # the caller holds the Manager's Monitor, and factories may call back into
+    # the Manager (Monitor is reentrant). A fiber-local mutex would create a
+    # lock-order inversion (fiber lock -> Manager Monitor vs Manager Monitor ->
+    # fiber lock) and deadlock. The Manager's reentrant Monitor is the single
+    # serialization point; this class deliberately stays lock-free.
+    class ComponentFiber
+      STATES = [:unloaded, :pending, :active, :failed, :disposed].freeze
+
+      attr_reader :name, :inject, :requires, :provides, :config, :state, :last_error, :sub_context, :instance
+
+      def initialize(name:, inject: [], requires: [], provides: [], config: {}, &factory)
+        @name = name.to_s
+        @inject = Array(inject).map(&:to_s).map(&:downcase)
+        @requires = Array(requires).map(&:to_s).map(&:downcase)
+        @provides = ([@name.downcase] + Array(provides).map(&:to_s).map(&:downcase)).uniq
+        @config = config || {}
+        @factory = factory
+        @state = :pending
+        @last_error = nil
+        @sub_context = nil
+        @instance = nil
+      end
+
+      def satisfiable?(context)
+        @inject.all? { |dep| context.has?(dep) }
+      end
+
+      # A fiber is ready to activate when its inject dependencies are satisfied
+      # AND all its requires: coeffect prerequisites are also present in the context.
+      # `requires:` is a pre-activation gate (Plan 86 D-3): the fiber stays Pending
+      # until every declared requirement is available, preventing partial activation.
+      def ready_to_activate?(context)
+        satisfiable?(context) && @requires.all? { |dep| context.has?(dep) }
+      end
+
+      def activate!(context)
+        return true if @state == :active
+        return false unless ready_to_activate?(context)
+
+        # Scoped sub-context for fiber lifecycle
+        @sub_context = context.extend
+
+        begin
+          @instance = if @factory
+                        @factory.call(@sub_context, @config)
+                      else
+                        build_instance(@sub_context, @config)
+                      end
+          @state = :active
+          @last_error = nil
+          true
+        rescue StandardError => e
+          # Atomic Rollback on Error: unwind partial inverses immediately
+          @sub_context&.dispose
+          @sub_context = nil
+          @instance = nil
+          @state = :failed
+          @last_error = e
+          false
+        end
+      end
+
+      def deactivate!
+        return false unless @state == :active
+
+        if @sub_context
+          @sub_context.dispose
+          @sub_context = nil
+        end
+        @instance = nil
+        @state = :pending
+        true
+      end
+
+      def reactivate!(context)
+        deactivate! if @state == :active
+        activate!(context)
+      end
+
+      def mark_failed!(error = nil)
+        deactivate! if @state == :active
+        @state = :failed
+        @last_error = error || StandardError.new("Fiber '#{@name}' marked failed")
+      end
+
+      def dispose!
+        deactivate! if @state == :active
+        @state = :disposed
+      end
+
+      def build_instance(_sub_context, _config)
+        nil
+      end
+    end
+
+    # Backwards-compatibility alias (AGENTS.md terminology). Kept for external
+    # consumers and pin test `test_component_fiber_naming_and_alias_compatibility`;
+    # internal code must use ComponentFiber directly — a bare `Fiber` inside
+    # Rubik::Runtime shadows ::Fiber and corrupts grep/grep-ability (review
+    # Finding 6). Enforced by test_no_bare_fiber_alias_use_in_lib.
+    Fiber = ComponentFiber
+  end
+end