rubik 0.1.0

data/lib/rubik/runtime/fiber_ordering.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# Pure fiber ordering for Runtime::Manager (G4 extraction): Kahn's algorithm
+# over provides/injects/requires with legacy-alias canonicalization. Returns
+# [sorted, cycled] — cycle failure REPORTING stays in the Manager (it touches
+# the context's dmesg service); this module only computes the order.
+module Rubik
+  module Runtime
+    module FiberOrdering
+      module_function
+
+      def sort(fibers)
+        return [fibers, []] if fibers.size <= 1
+
+        provider_map = {}
+        fibers.each do |f|
+          (f.respond_to?(:provides) ? f.provides : [f.name.downcase]).each do |k|
+            (provider_map[k] ||= []) << f
+            canon = Rubik::Coeffects.canonical(k)
+            (provider_map[canon] ||= []) << f if canon && canon != k
+          end
+        end
+
+        dependents = Hash.new { |h, k| h[k] = Set.new }
+        in_degree = Hash.new(0)
+        fibers.each do |consumer|
+          needed = (Array(consumer.inject) + Array(consumer.requires)).map { |d| d.to_s.downcase }
+          prereqs = Set.new
+          needed.each do |k|
+            providers = (provider_map[k] || []) + (provider_map[Rubik::Coeffects.canonical(k)] || [])
+            providers.each { |p| prereqs << p if p != consumer && fibers.include?(p) }
+          end
+          in_degree[consumer] = prereqs.size
+          prereqs.each { |p| dependents[p] << consumer }
+        end
+
+        queue = fibers.select { |f| in_degree[f].zero? }
+        sorted = []
+        until queue.empty?
+          curr = queue.shift
+          sorted << curr
+          dependents[curr].each do |dep|
+            in_degree[dep] -= 1
+            queue << dep if in_degree[dep].zero?
+          end
+        end
+
+        [sorted, fibers - sorted]
+      end
+    end
+  end
+end

data/lib/rubik/runtime/fiber_retry_gate.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+# Failed-fiber retry gate (G4 extraction from Runtime::Manager; review
+# 2026-09-17, Finding 3): a permanently-broken factory used to re-run on EVERY
+# reconcile_all (each provide/register). Failures back off exponentially and
+# stop after MAX_RETRIES attempts; a successful activation or a fresh
+# register_fiber clears the bookkeeping.
+#
+# The backoff sleep must NOT run while holding the Manager Monitor: the sleep
+# happens with the monitor fully released (depth 0) so it never serializes
+# other threads; bookkeeping is committed atomically under it first, and the
+# factory activation re-acquires the lock (depth 1) afterwards.
+module Rubik
+  module Runtime
+    class FiberRetryGate
+      MAX_RETRIES = 5
+      BACKOFF_BASE_S = 0.05
+
+      def initialize(monitor, context)
+        @monitor = monitor
+        @context = context
+        @bookkeeping = {} # name -> { attempts:, last_attempt_at:, warned: }
+      end
+
+      # Explicit re-registration / unregistration resets the retry budget.
+      def clear(name)
+        @monitor.synchronize { @bookkeeping.delete(name) }
+      end
+
+      # No bookkeeping outlives the manager (fresh-eye R2).
+      def clear_all
+        @bookkeeping.clear
+      end
+
+      def attempt(fiber)
+        delay = 0.0
+        elapsed = 0.0
+        @monitor.synchronize do
+          book = @bookkeeping[fiber.name] ||= { attempts: 0, last_attempt_at: nil }
+          if book[:attempts] >= MAX_RETRIES
+            warn_budget_exhausted(fiber, book) # atomic, one-shot, stays under the lock
+            return
+          end
+
+          prev_attempts = book[:attempts]
+          ts_prev = book[:last_attempt_at]
+          now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          delay = ts_prev ? BACKOFF_BASE_S * (2**prev_attempts) : 0.0
+          elapsed = ts_prev ? (now - ts_prev) : Float::INFINITY
+          book[:attempts] += 1
+          book[:last_attempt_at] = now
+        end
+
+        # Sleep happens with the monitor FULLY released (depth 0) so it never
+        # serializes other threads; bookkeeping is already committed above.
+        sleep(delay - elapsed) if delay > elapsed
+
+        # Re-acquire (depth 1) and run the factory: the failing fiber is not in
+        # the manager's activation marker, so the reentrancy guard lets this
+        # re-activate it. A successful activation clears its bookkeeping.
+        @monitor.synchronize do
+          yield fiber
+          @bookkeeping.delete(fiber.name) if fiber.state == :active
+        end
+      end
+
+      private
+
+      # One-shot visibility when a fiber's retry budget is exhausted (fresh-eye
+      # R3): the old always-retry behavior was noisy but visible; without this
+      # warn a permanently-broken factory would sink silently into :failed.
+      # Warns exactly once per budget cycle — re-registration resets the flag.
+      def warn_budget_exhausted(fiber, book)
+        return if book[:warned]
+
+        book[:warned] = true
+        last = fiber.last_error
+        Rubik::Log.warn(:runtime, "fiber '#{fiber.name}' retry budget exhausted " \
+                                  "(#{book[:attempts]} attempts, MAX_FIBER_RETRIES=#{MAX_RETRIES}) — " \
+                                  "staying :failed; re-register to retry. Last error: #{last&.class}: #{last&.message}")
+      end
+    end
+  end
+end

data/lib/rubik/runtime/index_service.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "pathname"
+require_relative "../coeffects"
+require_relative "service_registration"
+
+module Rubik
+  module Runtime
+    module IndexService
+      module_function
+
+      def register(context_or_manager, index)
+        ServiceRegistration.call(context_or_manager) do |ctx|
+          next index unless ctx
+
+          ctx.provide(Rubik::Coeffects::CONTEXT_INDEX, index)
+          index
+        end
+      end
+
+      def sync_roots(context_or_manager, index, additional_roots:, ast_graph: nil, cache_store: nil)
+        return unless index
+
+        index.additional_roots = Array(additional_roots)
+        index.full_scan
+
+        context_or_manager.reconcile_all if context_or_manager.respond_to?(:reconcile_all)
+
+        if ast_graph
+          root_d = index.root_dir
+
+          # Re-index all supported files known to the context index.
+          # Rely on File.exist?(full_path) as the sole guard: a file
+          # already in the graph simply re-indexes harmlessly.
+          index.files.each_key do |rel_file|
+            full_path = File.expand_path(rel_file, root_d)
+            ext = File.extname(rel_file).downcase
+            if defined?(Rubik::AST::Extractor) && Rubik::AST::Extractor.supported_extensions.include?(ext) &&
+               File.exist?(full_path)
+              ast_graph.index_file(full_path)
+            end
+          end
+
+          if cache_store && File.directory?(root_d)
+            begin
+              ast_graph.save_to_cache(cache_store)
+            rescue => e
+              Rubik::Log.warn(:ast, "AST graph cache save failed (#{e.class}: #{e.message}); stale cache retained")
+              nil
+            end
+          end
+        end
+
+        index
+      end
+    end
+  end
+end

data/lib/rubik/runtime/loop_service.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative "fiber"
+require_relative "../coeffects"
+require_relative "service_registration"
+
+module Rubik
+  module Runtime
+    class AgentLoopFiber < ComponentFiber
+      attr_reader :shell
+
+      def initialize(name: "orchestrator_loop", inject: ["llm_client", "tool_registry", "buffer_manager"], config: {}, shell: nil, &factory)
+        @shell = shell
+        super(name: name, inject: inject, config: config, &factory)
+      end
+
+      def build_instance(sub_context, config)
+        LoopService.build_loop(sub_context, shell: @shell, config: config)
+      end
+    end
+
+    module LoopService
+      module_function
+
+      def register(runtime_manager_or_context, shell: nil, name: "orchestrator_loop", inject: ["llm_client", "tool_registry", "buffer_manager"], config: {})
+        fiber = AgentLoopFiber.new(name: name, inject: inject, config: config, shell: shell)
+        # Fiber registration is not a plain provide: Manager#register_fiber
+        # reconciles itself, so the spine's trailing reconcile is suppressed.
+        ServiceRegistration.call(runtime_manager_or_context, reconcile: false) do |ctx|
+          if runtime_manager_or_context.respond_to?(:register_fiber)
+            runtime_manager_or_context.register_fiber(fiber)
+          elsif ctx && fiber.satisfiable?(ctx)
+            fiber.activate!(ctx)
+          end
+          fiber
+        end
+      end
+
+      def build_loop(context, shell: nil, config: {})
+        ctx = context.respond_to?(:context) ? context.context : context
+        provider = config[:provider] || (ctx.respond_to?(:get) ? Rubik::Coeffects.get(ctx, Rubik::Coeffects::LLM_CLIENT) : nil)
+        tool_registry = config[:tool_registry] || (if ctx.respond_to?(:get)
+                                                     Rubik::Coeffects.get(ctx,
+                                                                          Rubik::Coeffects::TOOL_REGISTRY)
+                                                   end) || shell&.build_tool_registry
+        app_config = config[:config] || shell&.config ||
+                     (ctx.respond_to?(:get) ? Rubik::Coeffects.get(ctx, Rubik::Coeffects::CONFIG) : nil)
+
+        max_steps = config[:max_steps] || (app_config.respond_to?(:fetch) ? app_config.fetch("agent.max_steps", 40).to_i : 40)
+        warn_ratio = config[:warn_at_ratio] || (app_config.respond_to?(:fetch) ? app_config.fetch("agent.warn_at_ratio", 0.75).to_f : 0.75)
+        model = config[:model]
+        on_step = config[:on_step]
+        context_limit = config[:context_limit]
+        max_output_tokens = config[:max_output_tokens] ||
+                            (app_config.respond_to?(:fetch) && app_config.fetch("llm.default_max_output_tokens", 4_096)&.to_i) || 4_096
+
+        require_relative "../orchestrator"
+
+        Rubik::Orchestrator::Loop.new(
+          provider: provider,
+          tool_registry: tool_registry,
+          max_steps: max_steps,
+          warn_at_ratio: warn_ratio,
+          model: model,
+          shell: shell,
+          context_limit: context_limit,
+          max_output_tokens: max_output_tokens,
+          on_step: on_step
+        )
+      end
+    end
+  end
+end

data/lib/rubik/runtime/manager.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+require "monitor"
+require_relative "context"
+require_relative "fiber"
+require_relative "fiber_ordering"
+require_relative "fiber_retry_gate"
+
+module Rubik
+  module Runtime
+    class Manager
+      attr_reader :context, :retry_gate
+
+      def initialize(context = nil)
+        @context = context || Context.new
+        @fibers = {}
+        @monitor = Monitor.new
+        # Fiber names with a factory currently in flight (reentrant reconcile
+        # guard): a factory that re-provides its own dependency re-enters
+        # reconcile_all on the same thread; without this marker the pending/
+        # active branches would re-activate the fiber and recurse unbounded
+        # (Monitor is reentrant, so the spiral ends in SystemStackError, not
+        # a deadlock).
+        @activating = {}
+        # Failed-fiber retry budget/backoff (G4): the gate owns the
+        # bookkeeping; the manager routes clear/attempt through it.
+        @retry_gate = FiberRetryGate.new(@monitor, @context)
+        # name -> Set of canonical coeffect keys this fiber's factory injects.
+        # The reactive surface (provide/unprovide) consults this to decide which
+        # fibers are gated on a coeffect that changed, so retracting a service
+        # through the reactive path retracts (deactivates) every fiber gated on
+        # it — matching provide's on-demand reactivation (AGENTS.md §5, Finding B).
+        @fiber_deps = {}
+        @disposed = false
+      end
+
+      # Retry-policy constants moved to FiberRetryGate (G4); aliases keep the
+      # Manager-facing names (tests, warn-message text) stable.
+      MAX_FIBER_RETRIES = FiberRetryGate::MAX_RETRIES
+      RETRY_BACKOFF_BASE_S = FiberRetryGate::BACKOFF_BASE_S
+
+      def fibers
+        @monitor.synchronize { @fibers.dup }
+      end
+
+      def disposed?
+        @monitor.synchronize { @disposed }
+      end
+
+      def register_component(name, inject: [], requires: [], provides: [], config: {}, &factory)
+        name_str = name.to_s
+        fiber = ComponentFiber.new(name: name_str, inject: inject, requires: requires, provides: provides, config: config, &factory)
+        register_fiber(fiber)
+      end
+
+      # Reentrant lock safety: Monitor#synchronize is explicitly reentrant (recursive),
+      # allowing register_fiber to store the fiber and activate it. The activation
+      # is performed OUTSIDE the lock (via reconcile_fiber) so a failing fiber's
+      # backoff sleep never serializes other threads (Finding 3).
+      def register_fiber(fiber)
+        deps = Array(fiber.inject).map { |n| n.to_s.downcase }
+        @monitor.synchronize do
+          raise ContextDisposedError, "Cannot register fiber on a disposed Manager" if @disposed
+
+          @fiber_deps.delete(fiber.name) unless deps.empty?
+          @fiber_deps[fiber.name] = deps.to_set unless deps.empty?
+          @fibers[fiber.name] = fiber
+          @retry_gate.clear(fiber.name) # explicit re-registration resets the retry budget
+        end
+        reconcile_fiber(fiber)
+        fiber
+      end
+
+      def unregister_component(name)
+        @monitor.synchronize do
+          name_str = name.to_s
+          fiber = @fibers.delete(name_str)
+          @fiber_deps.delete(name_str)
+          @retry_gate.clear(name_str) # fresh-eye R2: disposed fibers must not leak their retry budget
+          fiber&.dispose!
+        end
+      end
+
+      # Reactive retraction (AGENTS.md §5, Finding B): unlike Context#unprovide
+      # (which removes a service from the coeffect registry without touching
+      # dependents), retraction here routes through reconcile_all(changed_service:).
+      # Any fiber whose factory injects this coeffect therefore transitions
+      # Active->Pending and its partial inverse runs (LIFO via its sub-context),
+      # instead of orphaning against a now-stale/coeffect-less context. Re-
+      # providing the key afterwards is symmetric to provide: the fiber is
+      # reactivated on-demand.
+      def unprovide(service_name)
+        key = service_name.to_s.downcase
+        @monitor.synchronize { @context.unprovide(key) }
+        reconcile_all(changed_service: key)
+        nil # idempotent no-op returns nil (unprovide has no meaningful return)
+      end
+
+      # Reactive provide (AGENTS.md §5): adding a coeffect activates any pending
+      # fiber gated on it, and reactivates an active fiber when the SAME service
+      # object is re-provided (identity change), so its new instance is injected.
+      # Both transitions run reconcile_all(changed_service:) OUTSIDE the monitor.
+      def provide(service_name, service)
+        @monitor.synchronize { @context.provide(service_name, service) }
+        # reconcile_all runs OUTSIDE this lock so a failing fiber's backoff sleep
+        # never serializes other threads (Finding 3).
+        reconcile_all(changed_service: service_name)
+      end
+
+      # Reentrant lock safety: Monitor#synchronize is explicitly reentrant (recursive),
+      # allowing swap_component to safely invoke unregister_component and register_component
+      # from within the same thread without deadlocking.
+      def swap_component(name, inject: [], requires: [], provides: [], config: {}, &new_factory)
+        @monitor.synchronize do
+          name_str = name.to_s
+          unregister_component(name_str)
+          register_component(name_str, inject: inject, requires: requires, provides: provides, config: config, &new_factory)
+        end
+      end
+
+      def reconcile_all(changed_service: nil)
+        fibers = @monitor.synchronize { @fibers.values.dup }
+        sorted_fibers = topological_sort_fibers(fibers)
+        sorted_fibers.each do |fiber|
+          reconcile_fiber(fiber, changed_service: changed_service)
+        end
+      end
+
+      def topological_sort_fibers(fibers)
+        sorted, cycled = FiberOrdering.sort(fibers)
+        handle_fiber_cycle(cycled) unless cycled.empty?
+        sorted
+      end
+
+      def handle_fiber_cycle(cycle_fibers)
+        names = cycle_fibers.map(&:name).join(", ")
+        msg = "Dependency cycle detected among fibers: #{names}"
+        Rubik::Log.warn(:runtime, msg)
+        dmesg = begin
+          @context.resolve(Rubik::Coeffects::DMESG)
+        rescue StandardError
+          nil
+        end
+        dmesg&.log(:runtime, :err, msg) if dmesg.respond_to?(:log)
+
+        err = StandardError.new(msg)
+        @monitor.synchronize do
+          cycle_fibers.each { |cf| cf.mark_failed!(err) if cf.respond_to?(:mark_failed!) }
+        end
+      end
+
+      def reconcile_fiber(fiber, changed_service: nil)
+        # pending / active branches activate with the monitor held at depth 1
+        # (the factory returns while we still hold it, so nested reconciles see
+        # the newest value). The :failed branch defers activation until AFTER
+        # the monitor is released so the backoff sleep serializes no one.
+        deferred = nil
+        @monitor.synchronize do
+          # Reentrancy guard: skip fibers whose factory is currently running
+          # (nested reconcile from a factory-side provide). The in-flight
+          # factory already observes the newest value it provided, so the
+          # outer activation converges; a skipped re-run would only recurse.
+          return if @activating.key?(fiber.name)
+
+          case fiber.state
+          when :pending
+            with_activation_marker(fiber) { fiber.activate!(@context) } if fiber.ready_to_activate?(@context)
+          when :active
+            if !fiber.ready_to_activate?(@context)
+              fiber.deactivate!
+            elsif changed_service && fiber_depends_on_service?(fiber, changed_service.to_s.downcase)
+              with_activation_marker(fiber) { fiber.reactivate!(@context) }
+            end
+          when :failed
+            deferred = fiber if fiber.ready_to_activate?(@context)
+          end
+        end
+
+        # Monitor is now fully released (depth 0); the deferred retry's backoff
+        # sleep therefore runs with no lock held.
+        return unless deferred
+
+        @retry_gate.attempt(deferred) do |fiber|
+          with_activation_marker(fiber) { fiber.activate!(@context) }
+        end
+      end
+
+      def active_fibers
+        @monitor.synchronize { @fibers.values.select { |f| f.state == :active } }
+      end
+
+      def pending_fibers
+        @monitor.synchronize { @fibers.values.select { |f| f.state == :pending } }
+      end
+
+      def failed_fibers
+        @monitor.synchronize { @fibers.values.select { |f| f.state == :failed } }
+      end
+
+      def dispose!
+        @monitor.synchronize do
+          return if @disposed
+
+          @disposed = true
+          begin
+            @fibers.values.reverse_each do |fiber|
+              fiber.dispose!
+            rescue StandardError => e
+              Rubik::Log.warn(:runtime, "fiber '#{fiber.name}' dispose failed: #{e.class}: #{e.message}")
+            end
+          ensure
+            @fibers.clear
+            @retry_gate.clear_all # fresh-eye R2: no bookkeeping outlives the manager
+            @context.dispose
+          end
+        end
+      end
+
+      private
+
+      # Marks the fiber while its factory runs so nested reconciles skip it;
+      # ensure-based so a raising factory (→ :failed) never wedges the marker.
+      def with_activation_marker(fiber)
+        @activating[fiber.name] = true
+        begin
+          yield
+        ensure
+          @activating.delete(fiber.name)
+        end
+      end
+
+      # A fiber depends on a changed service when it injects the literal key
+      # or a legacy alias of it (Rubik::Coeffects SSOT), so alias-injected
+      # fibers react to canonical re-provides instead of holding stale
+      # service instances.
+      def fiber_depends_on_service?(fiber, changed_key)
+        fiber.inject.any? { |dep| dep == changed_key || Rubik::Coeffects.canonical(dep) == changed_key }
+      end
+    end
+  end
+end