rubik 0.1.0

data/lib/rubik/tools/preflight_runner.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require "json"
+require "rbconfig"
+require "stringio"
+require "timeout"
+
+require_relative "../security/errors"
+
+module Rubik
+  module Tools
+    # Runs synthesized handler code in a short-lived child ruby process with a
+    # hard kill deadline (AGENTS.md §3.4 Session Isolation).
+    #
+    # Why a subprocess: Timeout.timeout relies on Thread.raise, which cannot
+    # preempt C extensions or uninterruptible blocking syscalls — a runaway
+    # handler could hang the whole REPL past its budget. A child process can
+    # always be killed. When spawning is impossible (exotic embeddings, strict
+    # sandboxes) the runner reports :spawn_failed so callers can fall back to
+    # the in-process Timeout path.
+    module PreflightRunner
+      DEFAULT_TIMEOUT = 5
+
+      # Child evaluator: reads {code:, args:, mode:} from stdin, calls the
+      # handler, prints a single JSON verdict line. Single-quoted heredoc —
+      # never interpolated into the parent's source.
+      CHILD_SCRIPT = <<~'RUBY'
+        require "json"
+        require "stringio"
+        begin
+          payload = JSON.parse($stdin.read)
+          handler = eval(payload["code"], Object.new.instance_eval { binding }, __FILE__, __LINE__)
+          raise "code did not evaluate to a callable Proc" unless handler.respond_to?(:call)
+          # 2-arity command handlers receive the live CommandContext at
+          # dispatch; preflight mirrors its OUTPUT VIEW (out/puts/print/
+          # flush delegate to a throwaway StringIO) without the repl/
+          # require. Service reads fail loudly here — such handlers should
+          # declare 3-arity and be verified with the raw shell instead.
+          command_view = Struct.new(:out) do
+            def puts(*args)
+              out.puts(*args)
+            end
+
+            def print(*args)
+              out.print(*args)
+            end
+
+            def flush
+              out.flush if out.respond_to?(:flush)
+            end
+          end
+          case payload["mode"]
+          when "tool"
+            handler.call(payload["args"])
+          else
+            view = command_view.new(StringIO.new)
+            case handler.arity
+            when 1 then handler.call(payload["args"])
+            when 2 then handler.call(payload["args"], view)
+            else handler.call(payload["args"], view.out, nil)
+            end
+          end
+          STDOUT.puts JSON.dump(ok: true)
+        rescue StandardError, ScriptError => e
+          STDOUT.puts JSON.dump(ok: false, error: "#{e.class}: #{e.message}")
+        end
+      RUBY
+
+      module_function
+
+      # Executes +code+ (a self-contained lambda) with +args+ in an isolated
+      # child process. mode: :tool mirrors the ToolWrapper contract (exactly
+      # one argument); :command mirrors the REPL arity dispatch (args, out,
+      # nil shell — the real shell is unavailable in the child).
+      #
+      # The child process has no Rubik loaded, so payload["code"] cannot be
+      # verified there — the ONLY verification it can rely on is whatever
+      # the parent proved BEFORE spawning. guard is a REQUIRED kwarg on
+      # purpose: a future caller cannot skip the spawn-boundary check
+      # silently (ArgumentError at the call site).
+      #
+      # Returns nil on success, an error-detail String on failure, or
+      # :spawn_failed when the child infrastructure is unusable.
+      def run(code, args, guard:, mode: :command, timeout: DEFAULT_TIMEOUT)
+        # Shared gate at the spawn boundary: the duck-typed downgrade (a
+        # test-double affordance — production guards always define
+        # verify_synthesis_safety!) warns loudly at the single seam instead
+        # of silently skipping the AST deny surface here too.
+        Rubik::Security::Guard.run_synthesis_gate(guard, code)
+        payload = JSON.dump(code: code, args: args || {}, mode: mode.to_s)
+        run_subprocess(payload, timeout)
+      rescue Rubik::Security::BlockedWriteError => e
+        # Must precede the generic rescue: BlockedWriteError is a
+        # StandardError, and a block verdict downgraded to :spawn_failed
+        # would make the caller's in-process fallback run the blocked code.
+        "security verification failed: #{e.message}"
+      rescue TypeError, JSON::GeneratorError, SystemCallError
+        # Non-JSON-serializable args (TypeError/GeneratorError) or any other
+        # payload problem — caller falls back to in-process.
+        :spawn_failed
+      end
+
+      # In-process fallback (subprocess unavailable). Yields the caller's
+      # verification block under a Timeout guard. Returns nil on success or
+      # an error-detail String. Same caveat as before: Timeout cannot preempt
+      # C extensions or uninterruptible syscalls.
+      def verify_in_process(timeout: DEFAULT_TIMEOUT, &)
+        Timeout.timeout(timeout, &)
+        nil
+      rescue Timeout::Error
+        "execution timed out after #{timeout} seconds"
+      rescue StandardError, ScriptError => e
+        "#{e.class}: #{e.message}"
+      end
+
+      # Parent-side mirror of the child evaluator's dispatch (see CHILD_SCRIPT).
+      # Keeps the fallback path semantically identical to the subprocess path.
+      def call_handler(handler, args, mode: :command, shell: nil)
+        if mode == :tool
+          handler.call(args)
+        else
+          command_view = Struct.new(:out) do
+            def puts(*)
+              out.puts(*)
+            end
+
+            def print(*)
+              out.print(*)
+            end
+
+            def flush
+              out.flush if out.respond_to?(:flush)
+            end
+          end
+          view = command_view.new(StringIO.new)
+          case handler.arity
+          when 1 then handler.call(args)
+          when 2 then handler.call(args, view)
+          else handler.call(args, view.out, shell)
+          end
+        end
+      end
+
+      def run_subprocess(payload, timeout)
+        rd_in = wr_in = rd_out = wr_out = nil
+        rd_in, wr_in = IO.pipe
+        rd_out, wr_out = IO.pipe
+        pid = Process.spawn(RbConfig.ruby, "-e", CHILD_SCRIPT, in: rd_in, out: wr_out, err: File::NULL)
+        rd_in.close
+        wr_out.close
+        wr_in.write(payload)
+        wr_in.close
+
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        output = +""
+        loop do
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          if remaining <= 0
+            kill_child(pid)
+            return "execution timed out after #{timeout} seconds (subprocess killed)"
+          end
+          # wait_readable returning false (deadline slice elapsed) must NOT
+          # break: the deadline check above is what kills a runaway child.
+          next unless rd_out.wait_readable(remaining)
+
+          chunk = rd_out.read_nonblock(4096, exception: false)
+          break if chunk.nil? # EOF — child finished
+          next if chunk == :wait_readable
+
+          output << chunk
+        end
+        begin
+          Process.wait(pid)
+        rescue StandardError
+          nil
+        end
+        parse_verdict(output)
+      rescue StandardError
+        kill_child(pid) if defined?(pid) && pid
+        :spawn_failed
+      ensure
+        [rd_in, wr_in, rd_out, wr_out].each do |io|
+          io.close unless io.nil? || io.closed?
+        rescue StandardError
+          nil
+        end
+      end
+
+      def kill_child(pid)
+        Process.kill("KILL", pid)
+        Process.wait(pid)
+      rescue StandardError
+        nil
+      end
+
+      def parse_verdict(output)
+        line = output.lines.reverse.find { |l| l.start_with?("{") }
+        return "subprocess produced no verdict" unless line
+
+        verdict = JSON.parse(line)
+        return nil if verdict["ok"]
+
+        verdict["error"].to_s
+      rescue JSON::ParserError
+        "subprocess produced unreadable output"
+      end
+    end
+  end
+end

data/lib/rubik/tools/registry.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+require "monitor"
+require_relative "base"
+require_relative "services"
+require_relative "../coeffects"
+
+module Rubik
+  module Tools
+    class Registry
+      def initialize(coeffect_ctx: nil)
+        @tools = {}
+        @aliases = {}
+        @tool_aliases = {}
+        @origins = {}
+        @coeffect_ctx = coeffect_ctx
+        @monitor = Monitor.new
+      end
+
+      # origin labels where a tool came from (:builtin, :overlay, :mcp,
+      # :synthesis). The synthesizer uses it to refuse shadowing built-ins
+      # while still allowing hot-updates of non-builtin tools.
+      def register(tool_instance, aliases: [], origin: :builtin)
+        @monitor.synchronize do
+          @tools[tool_instance.name] = tool_instance
+          @origins[tool_instance.name] = origin
+          all_aliases = (tool_instance.respond_to?(:aliases) ? Array(tool_instance.aliases) : []) + Array(aliases)
+          @tool_aliases[tool_instance.name] ||= []
+          all_aliases.each do |al|
+            clean_al = al.to_s.downcase
+            @aliases[clean_al] = tool_instance.name
+            @tool_aliases[tool_instance.name] << clean_al
+          end
+          tool_instance
+        end
+      end
+
+      def unregister(name)
+        @monitor.synchronize do
+          canonical_name = @tools.key?(name.to_s) ? name.to_s : @aliases[name.to_s.downcase]
+          removed_tool = @tools.delete(canonical_name) if canonical_name
+          @origins.delete(canonical_name) if canonical_name
+          if canonical_name && @tool_aliases[canonical_name]
+            @tool_aliases.delete(canonical_name).each do |al|
+              @aliases.delete(al) if @aliases[al] == canonical_name
+            end
+          else
+            @aliases.delete_if { |_k, v| v == canonical_name || v == name.to_s }
+          end
+          @aliases.delete(name.to_s.downcase) if @aliases[name.to_s.downcase] == canonical_name
+          removed_tool
+        end
+      end
+
+      # Atomic hot-swap of an existing tool with a new tool instance.
+      # Reentrant lock safety: Monitor#synchronize is explicitly reentrant (recursive),
+      # meaning the calling thread can safely enter unregister and register without deadlock.
+      def swap(name, new_tool, origin: :builtin)
+        @monitor.synchronize do
+          unregister(name)
+          register(new_tool, origin: origin) if new_tool
+        end
+      end
+
+      def get(tool_name)
+        @monitor.synchronize do
+          @tools[tool_name.to_s] || begin
+            canonical = @aliases[tool_name.to_s.downcase]
+            canonical ? @tools[canonical] : nil
+          end
+        end
+      end
+
+      # Registration origin of the tool resolved by name (canonical or alias),
+      # or nil when no such tool is registered.
+      def origin(name)
+        @monitor.synchronize do
+          canonical = @tools.key?(name.to_s) ? name.to_s : @aliases[name.to_s.downcase]
+          canonical ? @origins[canonical] : nil
+        end
+      end
+
+      def list
+        @monitor.synchronize do
+          @tools.values.dup
+        end
+      end
+
+      # Schemas of tools whose declared coeffects (REQUIRES) are currently
+      # satisfied — the toolbelt-side of the fiber state machine (AGENTS.md
+      # §2): a tool missing its coeffects sits PENDING (hidden from the LLM)
+      # and activates reactively when a provider supplies the service.
+      # Called per agent step, so the filter re-evaluates live. Tools remain
+      # invocable via Registry#get for graceful self-correction errors.
+      def schemas
+        @monitor.synchronize do
+          @tools.values.select { |t| coeffects_satisfied?(t) }.map(&:to_h)
+        end
+      end
+
+      def aliases_map
+        @monitor.synchronize do
+          @aliases.dup
+        end
+      end
+
+      # Service slots (guard, context_index, adapter_registry, ast_graph,
+      # task_manager, sandbox_runner, subagent_supervisor) resolve through
+      # the house triple chain in Tools::Services — explicit kwarg (the
+      # **service_overrides above), then the runtime coeffect, then a fresh
+      # standalone default — so standalone/test constructions stay
+      # fail-closed. Unknown service kwargs raise ArgumentError, naming the
+      # valid slots.
+      def self.build_default(
+        buffer_manager:, shell: nil, overlay_storage: nil, runtime_manager: nil,
+        lsp_manager: nil, config: nil, root_dir: Dir.pwd, **service_overrides
+      )
+        ctx = runtime_manager&.context
+        registry = new(coeffect_ctx: ctx.respond_to?(:satisfied?) ? ctx : nil)
+        native_switch = config || shell&.config
+        svc = Services.new(ctx: ctx, overrides: service_overrides, root_dir: root_dir, native_switch: native_switch)
+        # Raw kwarg, NOT svc.context_index — preserved verbatim from the
+        # pre-catalog registry: RunTestsTool takes the caller-supplied (and
+        # possibly nil) index while list/grep tools take the resolved one.
+        raw_context_index = service_overrides[:context_index]
+
+        register_file_and_search_tools(registry, buffer_manager: buffer_manager, svc: svc, root_dir: root_dir, native_switch: native_switch, ctx: ctx)
+        register_lsp_tools(registry, lsp_manager: lsp_manager, buffer_manager: buffer_manager)
+        register_execution_tools(registry, svc: svc, raw_context_index: raw_context_index, root_dir: root_dir, native_switch: native_switch, ctx: ctx)
+        register_repl_and_synthesis_tools(
+          registry,
+          shell: shell,
+          overlay_storage: overlay_storage,
+          runtime_manager: runtime_manager,
+          lsp_manager: lsp_manager,
+          svc: svc,
+          native_switch: native_switch,
+          root_dir: root_dir
+        )
+        register_buffer_and_ui_tools(registry, buffer_manager: buffer_manager, shell: shell, ctx: ctx)
+        register_subagent_tools(registry, svc: svc, ctx: ctx)
+        register_system_tools(registry, svc: svc, native_switch: native_switch, root_dir: root_dir, ctx: ctx)
+
+        overlay_storage&.load_tools(registry)
+        # Inverse-by-construction (AGENTS.md §1.A): one monoidal inverse for
+        # the whole registry — context teardown unregisters every tool in
+        # strict LIFO order together with the rest of the session effects.
+        ctx&.register_disposable { registry.list.each { |t| registry.unregister(t.name) } } if ctx.respond_to?(:register_disposable)
+        registry
+      end
+
+      def self.register_file_and_search_tools(registry, buffer_manager:, svc:, root_dir:, native_switch:, ctx:)
+        registry.register(ReadFileTool.new(buffer_manager, runtime_context: ctx))
+        registry.register(ReplaceFileContentTool.new(buffer_manager))
+        registry.register(WriteFileTool.new(buffer_manager))
+        registry.register(ListFilesTool.new(svc.context_index, root_dir: root_dir, runtime_context: ctx))
+        registry.register(GrepSearchTool.new(buffer_manager, svc.context_index, root_dir: root_dir, runtime_context: ctx, config: native_switch))
+        registry.register(SearchSymbolsTool.new(svc.ast_graph, runtime_context: ctx))
+        registry.register(GetOutlineTool.new(svc.ast_graph, runtime_context: ctx))
+        registry.register(FindReferencesTool.new(svc.ast_graph, runtime_context: ctx))
+        registry.register(GetSymbolTool.new(svc.ast_graph, runtime_context: ctx))
+      end
+
+      def self.register_lsp_tools(registry, lsp_manager:, buffer_manager:)
+        registry.register(LSPDiagnosticsTool.new(lsp_manager, buffer_manager: buffer_manager))
+        registry.register(LSPHoverTool.new(lsp_manager, buffer_manager: buffer_manager))
+        registry.register(LSPDefinitionTool.new(lsp_manager, buffer_manager: buffer_manager))
+      end
+
+      def self.register_execution_tools(registry, svc:, raw_context_index:, root_dir:, native_switch:, ctx:)
+        registry.register(RunTestsTool.new(svc.adapter_registry, raw_context_index, root_dir: root_dir,
+                                                                                    config: native_switch, guard: svc.guard))
+        registry.register(RunCommandTool.new(
+                            guard: svc.guard,
+                            runner: svc.sandbox_runner,
+                            root_dir: root_dir,
+                            task_manager: svc.task_manager,
+                            runtime_context: ctx
+                          ))
+        registry.register(ManageTaskTool.new(task_manager: svc.task_manager, guard: svc.guard, runtime_context: ctx))
+      end
+
+      def self.register_repl_and_synthesis_tools(registry, shell:, overlay_storage:, runtime_manager:, lsp_manager:, svc:, native_switch:, root_dir:)
+        registry.register(ExecReplCommandTool.new(shell))
+        registry.register(SynthesizeCommandTool.new(shell, overlay_storage, svc.guard, runtime_manager: runtime_manager))
+        registry.register(SynthesizeToolTool.new(registry, overlay_storage, svc.guard, runtime_manager: runtime_manager))
+        registry.register(UnsynthesizeTool.new(shell, registry, overlay_storage, runtime_manager: runtime_manager))
+        registry.register(InspectRuntimeTool.new(runtime_manager, registry, shell))
+        registry.register(ProvideServiceTool.new(runtime_manager))
+        registry.register(RepairRuntimeTool.new(
+                            runtime_manager: runtime_manager,
+                            lsp_manager: lsp_manager,
+                            adapter_registry: svc.adapter_registry,
+                            overlay_storage: overlay_storage,
+                            config: native_switch,
+                            root_dir: root_dir,
+                            guard: svc.guard
+                          ))
+      end
+
+      def self.register_buffer_and_ui_tools(registry, buffer_manager:, shell:, ctx:)
+        registry.register(ApplyBufferTool.new(buffer_manager, shell))
+        registry.register(AskQuestionTool.new(shell: shell, runtime_context: ctx))
+      end
+
+      def self.register_subagent_tools(registry, svc:, ctx:)
+        registry.register(InvokeSubagentTool.new(supervisor: svc.subagent_supervisor, runtime_context: ctx))
+        registry.register(ManageSubagentsTool.new(supervisor: svc.subagent_supervisor, runtime_context: ctx))
+        registry.register(SendMessageTool.new(supervisor: svc.subagent_supervisor, runtime_context: ctx))
+        registry.register(DefineSubagentTool.new(supervisor: svc.subagent_supervisor, runtime_context: ctx))
+      end
+
+      def self.register_system_tools(registry, svc:, native_switch:, root_dir:, ctx:)
+        registry.register(DmesgTool.new(svc.dmesg, runtime_context: ctx))
+        registry.register(StorageTool.new(nil, runtime_context: ctx, config: native_switch, root_dir: root_dir))
+        registry.register(VakanuvisTool.new(runtime_context: ctx))
+        registry.register(PruneContextTool.new(runtime_context: ctx))
+        registry.register(UpdateGoalLedgerTool.new(runtime_context: ctx))
+        registry.register(ShowFileTool.new(runtime_context: ctx))
+        registry.register(FinishTool.new)
+      end
+
+      private_class_method :register_file_and_search_tools,
+                           :register_lsp_tools,
+                           :register_execution_tools,
+                           :register_repl_and_synthesis_tools,
+                           :register_buffer_and_ui_tools,
+                           :register_subagent_tools,
+                           :register_system_tools
+
+      private
+
+      # A tool is satisfied when it declares no REQUIRES, when no coeffect
+      # context is wired (plain registries keep advertising everything), or
+      # when the context chain satisfies every declared dependency.
+      def coeffects_satisfied?(tool)
+        return true unless tool.class.const_defined?(:REQUIRES)
+
+        deps = tool.class.const_get(:REQUIRES)
+        return true if deps.nil? || deps.empty?
+        return true unless @coeffect_ctx.respond_to?(:satisfied?)
+
+        @coeffect_ctx.satisfied?(deps)
+      end
+    end
+  end
+end

data/lib/rubik/tools/result.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "../platform"
+
+module Rubik
+  module Tools
+    class Result
+      attr_reader :tool_name, :call_id, :status, :output, :error, :exit_code, :duration_ms, :truncated, :metadata
+
+      def initialize(tool_name:, call_id: nil, status: :ok, output: "", error: nil, exit_code: nil, duration_ms: 0.0, truncated: false, metadata: {})
+        @tool_name = tool_name.to_s
+        @call_id = call_id.to_s
+        @status = status.to_sym
+        @output = output.to_s
+        @error = error
+        @exit_code = exit_code
+        @duration_ms = duration_ms.to_f.round(1)
+        @truncated = truncated ? true : false
+        @metadata = metadata || {}
+      end
+
+      def ok?
+        @status == :ok
+      end
+
+      def error?
+        @status == :error
+      end
+
+      # Returns the tool result output as a plain string.
+      #
+      # @return [String] the output content of this tool result
+      def to_s
+        @output
+      end
+
+      # XML envelope for the conversation history. Both attributes and the
+      # output body are escaped: tool output is untrusted content (file
+      # contents, command output) and an unescaped "</tool_result>" or XML
+      # tag inside it could break the envelope or smuggle instructions into
+      # the prompt.
+      def to_xml
+        esc = Rubik::Platform.method(:xml_escape)
+        attrs = [
+          %(tool="#{esc.call(@tool_name)}"),
+          @call_id && !@call_id.empty? ? %(id="#{esc.call(@call_id)}") : nil,
+          %(status="#{@status}"),
+          @exit_code ? %(exit_code="#{@exit_code}") : nil,
+          %(duration_ms="#{@duration_ms}"),
+          @truncated ? %(truncated="true") : nil
+        ].compact.join(" ")
+
+        "<tool_result #{attrs}>\n#{esc.call(@output)}\n</tool_result>"
+      end
+
+      def to_h
+        {
+          tool: @tool_name,
+          call_id: @call_id,
+          status: @status,
+          output: @output,
+          error: @error,
+          exit_code: @exit_code,
+          duration_ms: @duration_ms,
+          truncated: @truncated,
+          metadata: @metadata
+        }
+      end
+    end
+  end
+end

data/lib/rubik/tools/services.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require_relative "../coeffects"
+require_relative "../kernel/dmesg" unless defined?(Rubik::Kernel::Dmesg)
+
+module Rubik
+  module Tools
+    # Lazy per-key resolution view for the tool layer (architecture-review
+    # Candidate 05): ONE home for the house triple chain — explicit override
+    # kwarg, then the runtime coeffect (Coeffects.get), then a fresh
+    # standalone default. Collapses Registry.build_default's hand-written
+    # effective_* locals into a tier table.
+    #
+    #   owns   : the resolution tiers per service and the fresh-default
+    #            table — standalone construction policy: a zero-policy Guard
+    #            and a guard-chained sandbox Runner keep toolbelt-only
+    #            builds fail-closed (never wider policy than the caller gave)
+    #   leaves : key STRINGS (Rubik::Coeffects SSOT); full-graph construction
+    #            (REPL::ServiceCatalog — the fresh tier is deliberately the
+    #            DEGENERATE construction, not Composition's); tool
+    #            constructor signatures (tools layer)
+    #
+    # The coeffect tier exists exactly where wire_runtime_context publishes
+    # the key (guard, context_index, adapter_registry, ast_graph,
+    # task_manager, sandbox, subagent supervisor), so a shell-built registry
+    # always resolves the session's own instances. ORDER is load-bearing:
+    # sandbox_runner's fresh default chains onto the RESOLVED guard, so
+    # :guard resolves first.
+    class Services
+      # Hash literal order IS resolution order: :guard resolves first because
+      # sandbox_runner's fresh default chains onto the RESOLVED guard. ORDER
+      # derives from the keys so the reader methods and the validation
+      # message can never drift from the table.
+      COEFFECTS = {
+        guard: Rubik::Coeffects::GUARD,
+        context_index: Rubik::Coeffects::CONTEXT_INDEX,
+        adapter_registry: Rubik::Coeffects::ADAPTER_REGISTRY,
+        ast_graph: Rubik::Coeffects::AST_GRAPH,
+        task_manager: Rubik::Coeffects::TASK_MANAGER,
+        sandbox_runner: Rubik::Coeffects::SANDBOX_RUNNER,
+        subagent_supervisor: Rubik::Coeffects::SUBAGENT_SUPERVISOR,
+        dmesg: Rubik::Coeffects::DMESG
+      }.freeze
+
+      ORDER = COEFFECTS.keys.freeze
+
+      FRESH = {
+        guard: ->(_s) { Rubik::Security::Guard.new },
+        context_index: ->(s) { Rubik::Context::Index.new(root_dir: s.root_dir, native: s.native_switch&.fetch("tools.native")) },
+        adapter_registry: ->(_s) { Rubik::Adapter::Registry.new },
+        ast_graph: ->(_s) { Rubik::AST::Graph.new },
+        sandbox_runner: ->(s) { Rubik::Sandbox::Runner.new(root_dir: s.root_dir, guard: s.resolved_guard) },
+        dmesg: ->(_s) { Rubik::Kernel::Dmesg.new }
+      }.freeze
+
+      attr_reader :root_dir, :native_switch
+
+      def initialize(ctx: nil, overrides: {}, root_dir: Dir.pwd, native_switch: nil)
+        unknown = overrides.keys - ORDER
+        raise ArgumentError, "unknown service override(s) #{unknown.inspect}; valid slots: #{ORDER.inspect}" unless unknown.empty?
+
+        @ctx = ctx
+        @overrides = overrides
+        @root_dir = root_dir
+        @native_switch = native_switch
+        @resolved = {}
+      end
+
+      ORDER.each do |slot|
+        define_method(slot) { resolve(slot) }
+      end
+
+      # The guard the sandbox fresh default chains onto (resolved first by
+      # ORDER). Public for the FRESH lambdas and for the tier tests.
+      def resolved_guard
+        resolve(:guard)
+      end
+
+      private
+
+      # The triple chain, memoized per slot: explicit override, then the
+      # runtime coeffect (canonical key first, legacy alias second via
+      # Coeffects.get), then the fresh standalone default. Slots without a
+      # tier (task_manager, subagent_supervisor) resolve to nil when neither
+      # the override nor the context supplies one — matching the registry's
+      # pre-catalog behavior.
+      def resolve(name)
+        return @resolved[name] if @resolved.key?(name)
+
+        @resolved[name] = @overrides[name] ||
+                          (@ctx && Rubik::Coeffects.get(@ctx, COEFFECTS.fetch(name))) ||
+                          FRESH[name]&.call(self)
+      end
+    end
+  end
+end