rubik 0.1.0

data/lib/rubik/coeffects.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Rubik
+  # Canonical runtime-context coeffect keys (AGENTS.md §1.B — explicit
+  # dependency contracts). Single source of truth for service key names
+  # shared between providers (Runtime::*Service) and consumers (tools,
+  # registry). Legacy alias keys remain readable for backward compatibility
+  # but must not be referenced by name outside this module.
+  module Coeffects
+    CONTEXT_INDEX  = "context_index"
+    AST_GRAPH      = "ast_graph"
+    BUFFER_MANAGER = "buffer_manager"
+    SNAPSHOT_STORE = "snapshot_store"
+    LSP_MANAGER    = "lsp_manager"
+    MCP_MANAGER    = "mcp_manager"
+    SKILL_MANAGER  = "skill_manager"
+    # REPL composition root, published by wire_runtime_context (repl/lifecycle.rb).
+    # The sanctioned access path; the ambient root accessor pair in lib/rubik.rb
+    # is deprecated (sunset — review Öneri 4).
+    SHELL          = "shell"
+    ADAPTER_REGISTRY = "adapter_registry"
+    LLM_CLIENT     = "llm_client"
+    TOOL_REGISTRY  = "tool_registry"
+    TASK_MANAGER   = "task_manager"
+    SUBAGENT_SUPERVISOR = "subagent_supervisor"
+    # Shared security guard (operator policy carrier), published by
+    # wire_runtime_context and consumed via the Registry build_default
+    # triple chain.
+    GUARD          = "guard"
+    # Layered config object, published by wire_runtime_context for consumers
+    # that need config-derived values outside constructor injection.
+    CONFIG         = "config"
+    # Keys wire_runtime_context historically published as literals; surfaced
+    # as constants by Candidate 05's ServiceCatalog so every provided entry
+    # references this module (key names stay the SSOT here).
+    EVENTS         = "events"
+    SANDBOX_RUNNER = "sandbox"
+    ROUTER         = "router"
+    PLUGIN_MANAGER = "plugin_manager"
+    PLUGIN_STORAGE = "plugin_storage"
+    DMESG          = "dmesg"
+    DISPATCHER     = "dispatcher"
+    INIT           = "init"
+    # Live !goal run snapshot (Rubik::Orchestrator::GoalState), provided by
+    # the goal command and rendered to agents via read_file rubik://goal/state.
+    GOAL_STATE     = "goal_state"
+    # Structured goal ledger (GoalLedger::Ledger), provided by !goal when goal.ledger.enabled; unsatisfied outside a running !goal.
+    GOAL_LEDGER    = "goal_ledger"
+    # Central rubik://storage store (Rubik::Storage::Store), provided by
+    # Storage::Service at shell boot and resolved by the storage tool /
+    # read_file rubik://storage routes / supervisor transcript indexing.
+    STORAGE_STORE  = "storage_store"
+    # The ask-maestro bridge (Subagent::Instance mixing in Questioner):
+    # supervisor#spawn provides each instance into its own child context so
+    # the subagent-plane ask_question resolves it at execute time; unsatisfied
+    # on the root context, where the tool keeps its human-dialog plane.
+    SUBAGENT_QUESTION_ASKER = "subagent_question_asker"
+    # The send_message attribution bridge: supervisor#spawn (and redeploy)
+    # provide each subagent's conversation id into its own child context so
+    # a subagent-plane message routes to the maestro under its REAL sender
+    # id; unsatisfied on the root context, where Supervisor#send_message
+    # keeps its machine default sender ("agent-0").
+    SUBAGENT_SENDER_ID = "subagent_sender_id"
+    # The Vakanüvis chronicler harness (Storage::Vakanuvis::Harness),
+    # provided by Vakanuvis::Service at shell boot (Phase 4) and resolved
+    # by the vakanuvis tool (recall/record/forget/digest). Unsatisfied when
+    # the chronicler is disabled — the tool hides from the model surface.
+    VAKANUIS = "vakanuvis"
+    # The ROOT conversation-window pruner harness (REPL::Pruner::Harness),
+    # provided by Pruner::Service at shell boot (Phase 4; default ON via
+    # subagents.pruner.enabled — opt-out: false) and resolved by the
+    # prune_context tool and the !prune command. Unsatisfied when the
+    # pruner is disabled.
+    PRUNER = "pruner"
+
+    # Read-side bridge: third-party providers may still register services
+    # under these legacy alias keys; canonical keys are always tried first.
+    LEGACY_ALIASES = {
+      CONTEXT_INDEX => ["index"],
+      AST_GRAPH => ["ast"],
+      BUFFER_MANAGER => ["buffer"],
+      SNAPSHOT_STORE => ["snapshot"],
+      LSP_MANAGER => ["lsp"],
+      MCP_MANAGER => ["mcp"],
+      ADAPTER_REGISTRY => ["adapters"],
+      LLM_CLIENT => ["llm"],
+      TOOL_REGISTRY => ["tools"],
+      TASK_MANAGER => ["tasks"],
+      SUBAGENT_SUPERVISOR => ["subagents", "subagent_pool"],
+      STORAGE_STORE => ["storage"]
+    }.freeze
+
+    # Reverse map: legacy alias -> canonical key, derived from LEGACY_ALIASES.
+    # Powers the read-side bridge and reactive matching (Manager#reconcile_fiber),
+    # so alias-injected fibers react to canonical re-provides.
+    ALIAS_TO_CANONICAL = LEGACY_ALIASES.each_with_object({}) do |(canonical, aliases), map|
+      aliases.each { |alias_key| map[alias_key] = canonical }
+    end.freeze
+
+    class << self
+      # Canonical key for any request: identity for canonical or unknown keys,
+      # the mapped canonical for legacy alias names.
+      def canonical(key)
+        ALIAS_TO_CANONICAL.fetch(key.to_s.downcase, key.to_s.downcase)
+      end
+
+      # Read a coeffect by canonical key, falling back to legacy aliases.
+      # Resolution itself (literal -> canonical -> alias, parent-chain walk)
+      # is owned by the context: Rubik::Runtime::Context resolves all three
+      # spellings per hop under one monitor hold. A duck-typed ctx — the only
+      # contract here is respond_to?(:get) — resolves by exact key; the
+      # alias loop that used to live below is gone with it.
+      # Returns nil when the dependency is unsatisfied anywhere on the
+      # context chain.
+      def get(ctx, key)
+        return nil unless ctx.respond_to?(:get)
+
+        ctx.get(key)
+      end
+
+      # Tool-side resolution order: runtime context first, then the
+      # constructor-injected instance.
+      def resolve(ctx, key, injected = nil)
+        val = get(ctx, key)
+        val.nil? ? injected : val
+      end
+    end
+  end
+end

data/lib/rubik/concurrency/boundary.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative "event_loop"
+require_relative "scheduler"
+
+module Rubik
+  module Concurrency
+    # Thread-scoped scope around an event loop: install scheduler → run body
+    # as a fiber → drain every spawned fiber → uninstall (revertible by
+    # construction — the install's inverse lives in the same ensure).
+    #
+    # The active marker is a THREAD variable (not fiber-local): fibers on the
+    # thread share the boundary. Nested opens reuse the outer loop, so a
+    # .map inside .silently joins the same drain instead of nesting loops.
+    module Boundary
+      ACTIVE_KEY = :"rubik.concurrency.boundary"
+
+      module_function
+
+      # Returns the block's value. Error policy (K7): the body's own error
+      # wins; otherwise the LOWEST-ordinal spawned-fiber error is raised
+      # after the drain, and its siblings are logged (never swallowed). An
+      # exception arriving during the drain (Interrupt, Ctrl-Break's
+      # SignalException, …) finishes the drain once, resiliently, then
+      # surfaces only if the body did not already fail. The uninstall tail
+      # is unconditional: an exception raised inside an ensure block skips
+      # the REST of that ensure, so the tail lives in its own nested ensure
+      # (otherwise a second Ctrl-C mid-drain could leave the scheduler
+      # installed on the thread, hanging every later boundary).
+      def open(&)
+        return yield if ::Thread.current.thread_variable_get(ACTIVE_KEY)
+
+        loop = EventLoop.new
+        scheduler = Scheduler.new(loop)
+        drain_error = nil
+
+        ::Fiber.set_scheduler(scheduler)
+        ::Thread.current.thread_variable_set(ACTIVE_KEY, scheduler)
+        begin
+          result, body_error = loop.run(&)
+        ensure
+          begin
+            begin
+              loop.run_until_drained
+            rescue ::Exception => e # rubocop:disable Lint/RescueException -- cleanup isolation; re-raised below
+              drain_error = e
+              Rubik::Log.warn(:concurrency, "#{e.class} during drain; finishing drain")
+              begin
+                loop.run_until_drained
+              rescue ::Exception => e2 # rubocop:disable Lint/RescueException -- second failure: abandon the drain
+                Rubik::Log.warn(:concurrency, "#{e2.class} during second drain; abandoning remaining work")
+              end
+            end
+          ensure
+            ::Thread.current.thread_variable_set(ACTIVE_KEY, nil)
+            ::Fiber.set_scheduler(nil)
+            loop.shutdown
+          end
+        end
+
+        raise body_error if body_error
+        raise drain_error if drain_error
+
+        errors = loop.spawn_errors.sort_by(&:first)
+        errors.each do |(ordinal, error)|
+          Rubik::Log.warn(:concurrency, "spawned fiber ##{ordinal} failed: #{error.class}: #{error.message}")
+        end
+        raise errors.first[1] if errors.any?
+
+        result
+      end
+    end
+  end
+end

data/lib/rubik/concurrency/dns_pool.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Rubik
+  module Concurrency
+    # Bounded worker pool for getaddrinfo: MRI's resolver blocks the whole OS
+    # thread, so a scheduler-side address_resolve must run it elsewhere or a
+    # single slow DNS lookup would stall the event loop. Workers deliver the
+    # Addrinfo list (or an exception to raise) back to the parked fiber via
+    # EventLoop#unpark, which self-pipe-wakes the loop.
+    class DnsPool
+      SIZE = 4
+      SHUTDOWN = Object.new
+
+      def initialize(loop)
+        @loop = loop
+        @jobs = ::Queue.new
+        @workers = SIZE.times.map do
+          ::Thread.new { worker_loop }
+        end
+      end
+
+      def resolve(hostname)
+        blocker = ::Object.new
+        @jobs << [hostname, ::Fiber.current, blocker]
+        @loop.park(blocker)
+      end
+
+      # Never raises; sentinel per worker, bounded join, kill as last resort.
+      def shutdown
+        SIZE.times { @jobs << SHUTDOWN }
+        @workers.each do |thread|
+          thread.join(0.1)
+          thread.kill if thread.alive?
+        end
+      rescue StandardError
+        nil
+      end
+
+      private
+
+      def worker_loop
+        while (job = @jobs.pop)
+          break if job.equal?(SHUTDOWN)
+
+          hostname, fiber, blocker = job
+          value = begin
+            # The VM's address_resolve contract on 4.0 is a list of IP
+            # strings, NOT Addrinfo objects (verified; ruby's own test
+            # scheduler maps to ip_address for the same reason).
+            ::Addrinfo.getaddrinfo(hostname, nil).map(&:ip_address).uniq
+          rescue StandardError => e
+            e
+          end
+          begin
+            @loop.unpark(blocker, fiber, value: value)
+          rescue StandardError => e
+            # Delivery failure must never strand the fiber parked with no
+            # wakeup source (a silent boundary hang): interrupt it instead.
+            Rubik::Log.warn(:concurrency, "dns unpark failed: #{e.class}: #{e.message}")
+            @loop.interrupt(fiber, Interrupted.new("dns delivery failed"))
+          end
+        end
+      rescue StandardError => e
+        Rubik::Log.warn(:concurrency, "dns worker died: #{e.class}: #{e.message}")
+      end
+    end
+  end
+end

data/lib/rubik/concurrency/errors.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Rubik
+  module Concurrency
+    class Error < StandardError; end
+
+    # Raised into a fiber interrupted through the Ruby 4.0 fiber_interrupt
+    # hook (a safety net — a healthy boundary drains every fiber before
+    # close, so this only surfaces when teardown must cut work short).
+    class Interrupted < Interrupt; end
+
+    # Truthy stand-in for Process::Status when a watched pid was already
+    # reaped elsewhere (Open3's wait_thr beat us to it): process_wait must
+    # return something non-nil or the VM would spin on the dead pid forever.
+    StatusLike = Struct.new(:pid, :exitstatus, keyword_init: true)
+  end
+end