rubik 0.1.0

data/lib/rubik/concurrency/timers.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Rubik
+  module Concurrency
+    # Monotonic min-heap of fiber wakeups. Entries are
+    # [deadline, fiber, resume_value, generation]; only the EventLoop thread
+    # touches this structure (timers are registered from VM hooks, which run
+    # on the loop thread), so no locking is needed.
+    #
+    # Staleness: a timer for a fiber that has since re-parked (new park
+    # generation) or been resumed dead is inert. The EventLoop passes a
+    # stale? check at construction; entries failing it are pruned lazily by
+    # every query, so a dead timer never gates idle-draining — without this
+    # an interrupted 30 s sleep would hold the whole loop hostage until its
+    # deadline despite the fiber being long gone.
+    class Timers
+      def initialize(&staleness)
+        @staleness = staleness
+        @heap = []
+      end
+
+      # Returns the stored entry (opaque; useful for diagnostics only).
+      def add(deadline, fiber, resume_value, generation)
+        entry = [deadline, fiber, resume_value, generation]
+        @heap << entry
+        sift_up(@heap.size - 1)
+        entry
+      end
+
+      def empty?
+        prune!
+        @heap.empty?
+      end
+
+      def size
+        prune!
+        @heap.size
+      end
+
+      # Seconds until the earliest deadline (0.0 when already due), or nil
+      # when no timers are pending.
+      def next_gap(now)
+        return nil if empty?
+
+        gap = @heap[0][0] - now
+        gap.positive? ? gap : 0.0
+      end
+
+      # Calls sink.call(fiber, resume_value, generation) for every due entry,
+      # removing it. Returns the number of entries fired. The sink decides
+      # whether a stale entry actually resumes its fiber.
+      def fire_due!(now, &sink)
+        return 0 if empty? || sink.nil?
+
+        fired = 0
+        while !empty? && @heap[0][0] <= now
+          entry = @heap[0]
+          last = @heap.pop
+          if @heap.empty?
+            @heap << last unless last.equal?(entry)
+          else
+            @heap[0] = last
+            sift_down(0)
+          end
+          sink.call(entry[1], entry[2], entry[3])
+          fired += 1
+        end
+        fired
+      end
+
+      private
+
+      def prune!
+        return unless @staleness
+
+        @heap.reject! { |entry| @staleness.call(entry[1], entry[3]) }
+      end
+
+      def sift_up(index)
+        entry = @heap[index]
+        while index.positive?
+          parent = (index - 1) / 2
+          break if @heap[parent][0] <= entry[0]
+
+          @heap[index] = @heap[parent]
+          index = parent
+        end
+        @heap[index] = entry
+      end
+
+      def sift_down(index)
+        size = @heap.size
+        entry = @heap[index]
+        loop do
+          child = (2 * index) + 1
+          break if child >= size
+
+          right = child + 1
+          child = right if right < size && @heap[right][0] < @heap[child][0]
+          break if @heap[child][0] >= entry[0]
+
+          @heap[index] = @heap[child]
+          index = child
+        end
+        @heap[index] = entry
+      end
+    end
+  end
+end

data/lib/rubik/concurrency.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require_relative "log"
+require_relative "concurrency/errors"
+require_relative "concurrency/event_loop"
+require_relative "concurrency/scheduler"
+require_relative "concurrency/boundary"
+require_relative "concurrency/join"
+
+module Rubik
+  # Silent concurrency over Ruby's Fiber Scheduler: plain blocking I/O —
+  # Net::HTTP, sleep backoffs, Open3 pipe reads, Mutex/ConditionVariable
+  # waits, Thread#join — interleaves cooperatively on a background event
+  # loop while a boundary is open, with ZERO changes at the I/O call sites.
+  # "Silently" = no async/await-style syntax noise ever reaches callers.
+  #
+  # Envelope (documented limits, plan §9): this is I/O concurrency, not CPU
+  # parallelism (the GVL still serializes computation); regular-file reads
+  # never park (read_nonblock on files returns immediately — they simply run
+  # serially, which is harmless); Timeout.timeout-backed code paths are not
+  # adopted inside boundaries in v1 (Thread.raise cannot be aimed at a
+  # specific fiber). Escape hatch: RUBIK_FIBER_SCHEDULER=off degrades every
+  # boundary to plain sequential execution.
+  module Concurrency
+    module_function
+
+    # Runs the block on the current OS thread with a fiber scheduler
+    # installed. Fibers spawned inside (via .map or Fiber.schedule) drain
+    # before the block returns. Returns the block's value; errors surface
+    # per Boundary.open's drain-then-raise policy. Nested calls reuse the
+    # outer boundary. The scheduler is always uninstalled on exit.
+    def silently(&block)
+      disabled? ? block.call : Boundary.open(&block)
+    end
+
+    # Ordered fan-out: runs the block for every item concurrently and
+    # returns results in INPUT order. concurrency: bounds simultaneously
+    # live fibers (fiber stacks cost real memory — pass a bound for very
+    # large enumerables). Drain-then-raise: after every item completes, the
+    # lowest-INPUT-index error is raised and its siblings are logged.
+    def map(enum, concurrency: nil, &block)
+      return enum.map(&block) if disabled?
+
+      items = enum.to_a
+      return [] if items.empty?
+
+      limit = concurrency&.positive? ? concurrency.to_i : nil
+      slots = Boundary.open do
+        loop = ::Thread.current.thread_variable_get(Boundary::ACTIVE_KEY).loop
+        results = ::Array.new(items.size)
+        latch = ::Object.new
+        waiter = ::Fiber.current
+        remaining = items.size
+        slot_lock = ::Mutex.new
+        slot_free = ::ConditionVariable.new
+        used = 0
+
+        items.each_with_index do |item, index|
+          ::Fiber.schedule do
+            acquired = false
+            begin
+              slot_lock.synchronize do
+                slot_free.wait(slot_lock) while limit && used >= limit
+                used += 1
+              end
+              acquired = true
+              results[index] = { ok: true, value: block.call(item) }
+            rescue StandardError => e
+              results[index] = { ok: false, error: e }
+            ensure
+              # The ensure spans the ACQUISITION too: an Exception-level
+              # death while parked on the semaphore (interrupt delivery)
+              # must still count this item down or the latch never fires and
+              # the boundary hangs. Mutex#synchronize releases on raise, so
+              # re-locking here is safe.
+              if acquired
+                slot_lock.synchronize do
+                  used -= 1
+                  slot_free.signal
+                end
+              end
+              remaining -= 1 # fibers serialize on the loop thread — no race
+              loop.unpark(latch, waiter) if remaining.zero?
+            end
+          end
+        end
+        loop.park(latch)
+        results
+      end
+
+      failures = slots.filter_map.with_index { |slot, i| [i, slot[:error]] if slot && !slot[:ok] }
+      failures.each do |(index, error)|
+        Rubik::Log.warn(:concurrency, "fan-out item #{index} failed: #{error.class}: #{error.message}")
+      end
+      raise failures.first[1] if failures.any?
+
+      slots.map { |slot| slot[:value] }
+    end
+
+    # True while a boundary is installed on the current OS thread.
+    def active?
+      !::Thread.current.thread_variable_get(Boundary::ACTIVE_KEY).nil?
+    end
+
+    # RUBIK_FIBER_SCHEDULER=off degrades boundaries to sequential execution
+    # (memoized at first use — the process-wide kill switch, plan K14).
+    def disabled?
+      return @disabled unless @disabled.nil?
+
+      @disabled = ::ENV["RUBIK_FIBER_SCHEDULER"].to_s.casecmp("off").zero?
+    end
+
+    class << self
+      # Test seam: reset the memoized kill-switch state after stubbing ENV.
+      def reset_disabled_cache!
+        @disabled = nil
+        nil
+      end
+    end
+  end
+end
+
+# Ruby prints "IO::Buffer is experimental" on the first buffer use; our
+# io_read/io_write hooks exercise it on every boundary. Pay that one-shot
+# warning now, silently, so it never surfaces mid-session.
+original_verbose = $VERBOSE
+begin
+  $VERBOSE = nil
+  IO::Buffer.new(1)
+ensure
+  $VERBOSE = original_verbose
+end

data/lib/rubik/config/deep_ops.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Rubik
+  class Config
+    module DeepOps
+      private
+
+      def deep_dup(obj)
+        case obj
+        when Hash
+          obj.transform_values { |v| deep_dup(v) }
+        when Array
+          obj.map { |v| deep_dup(v) }
+        else
+          begin
+            obj.dup
+          rescue TypeError
+            # nil/true/false are undupable immediates; YAML-derived config
+            # values raise nothing else here. A custom #dup raising anything
+            # else must fail loud, not silently alias the value.
+            obj
+          end
+        end
+      end
+
+      # Merges source over target.
+      # Invariant (W6): Arrays are replaced as whole units by default so config overrides
+      # can completely reset lists. If array_union: true, arrays are merged via union.
+      def deep_merge(target, source, array_union: false)
+        return deep_dup(target) unless source.is_a?(Hash)
+
+        result = deep_dup(target)
+        source.each do |key, val|
+          result[key] = if result[key].is_a?(Hash) && val.is_a?(Hash)
+                          deep_merge(result[key], val, array_union: array_union)
+                        elsif array_union && result[key].is_a?(Array) && val.is_a?(Array)
+                          (result[key] + val).uniq
+                        else
+                          deep_dup(val)
+                        end
+        end
+        result
+      end
+
+      def deep_stringify_keys(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) do |(k, v), result|
+            result[k.to_s] = deep_stringify_keys(v)
+          end
+        when Array
+          obj.map { |v| deep_stringify_keys(v) }
+        else
+          obj
+        end
+      end
+
+      # Deletes the dot-path leaf from nested string-keyed hashes. Returns
+      # :deleted when the leaf existed and was removed, :absent when any
+      # segment of the path is missing (nothing to delete), :blocked when
+      # the path traverses an existing non-Hash (nothing was changed).
+      def deep_delete(obj, path)
+        keys = path.to_s.split(".")
+        return :blocked unless obj.is_a?(Hash)
+
+        node = keys[0...-1].reduce(obj) do |acc, k|
+          return :absent unless acc.is_a?(Hash) && acc.key?(k)
+
+          child = acc[k]
+          return :blocked unless child.is_a?(Hash)
+
+          child
+        end
+        return :blocked unless node.is_a?(Hash)
+
+        node.delete(keys.last) ? :deleted : :absent
+      end
+    end
+  end
+end

data/lib/rubik/config/defaults.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require_relative "../platform"
+
+module Rubik
+  class Config
+    module Defaults
+      DEFAULT_CONFIG = {
+        "llm" => {
+          "stream" => true,
+          "stream_timeout" => 120,
+          "open_timeout" => 15,
+          "default_max_output_tokens" => 4096,
+          "capture_reasoning" => true,
+          "auto_continue_on_length" => true,
+          "max_auto_continues" => 3,
+          # Plan 90 bridge (loop.rb): nil = not sent; non-nil reasoning_effort also flips reasoning_model?.
+          "thinking_budget_ratio" => nil, # Anthropic thinking budget share (0.0-0.8) -> opts[:thinking_budget_ratio]
+          "reasoning_effort" => nil,      # OpenAI reasoning effort "low"|"medium"|"high" -> opts[:reasoning_effort]
+          "headers" => {}
+        },
+        "model" => { "provider" => "ollama", "name" => "qwen2.5-coder:7b", "endpoint" => "http://localhost:11434" },
+        "models" => {
+          "default" => { "provider" => "ollama", "name" => "qwen2.5-coder:7b", "endpoint" => "http://localhost:11434" },
+          "fast" => { "provider" => "ollama", "name" => "qwen2.5-coder:1.5b", "endpoint" => "http://localhost:11434" },
+          "advanced" => { "provider" => "ollama", "name" => "qwen2.5-coder:14b", "endpoint" => "http://localhost:11434" }
+        },
+        "providers" => {},
+        "agent" => {
+          "max_steps" => 40,
+          "goal_max_steps" => 100,
+          "plan_max_steps" => 15,
+          "warn_at_ratio" => 0.75,
+          "ask_continue_on_limit" => true, "goal_wait_timeout" => 300
+        },
+        # rubik://storage sanal FS-DB (Rubik::Storage): hedef/plan/bellek/wiki/transcript varlıkları
+        # + worktree'yi temiz tutan artifact absorb'u. root "~" içerebilir; project nil ise slug türetilir.
+        "storage" => {
+          "enabled" => true,
+          "root" => "~/.rubik/rubikstorage",
+          "project" => nil,
+          "absorb_artifacts" => true
+        },
+        "tools" => {
+          "circuit_breaker" => { "enabled" => false, "threshold" => 5, "cooldown_seconds" => 60 },
+          "max_output_chars" => 12_000,
+          "max_output_lines" => 300,
+          "truncation_strategy" => "head_tail",
+          "timeout_seconds" => 30,
+          "native" => "auto"
+        },
+        "router" => { "mode" => "auto", "sticky" => true },
+        "repair" => { "max_attempts" => 3 },
+        "sandbox" => {
+          "enabled" => false,
+          "driver" => "bwrap",
+          "image" => "rubik-sandbox:latest",
+          "timeout_seconds" => 15,
+          "memory_limit_mb" => 512,
+          "cpus" => "1.0",
+          "allow_network" => false,
+          "shell" => "auto", # sandbox shell resolution: auto | bash | powershell (sandbox/runner.rb)
+          "prompt_on_startup" => true, "isolation_note" => true # append the 🔍 isolation line to run_command output (sandbox/runner.rb)
+        },
+        "security" => {
+          # NOTE: no audit_log_path default — Guard.default_audit_log_path (security/guard.rb) is the
+          # single source so the value resolves at call time; a load-time snapshot would pin require-time HOME.
+          "command_allowlist" => [], # operator-managed token-prefix entries (e.g. "node .gitnexus/run.cjs")
+          "allow_safe_probes" => true # `bash --version`-style version/help probes bypass the blocklist
+        },
+        "network" => { "allow" => false },
+        "buffer" => {
+          "auto_apply" => "manual",
+          "model_can_apply" => true,
+          "prompt_indicator" => true,
+          "exit_guard" => true,
+          "reminder_interval" => 3,
+          "on_external_modification" => "skip"
+        },
+        "lsp" => {
+          "enabled" => true,
+          "auto_start" => true,
+          "auto_diagnostics" => true,
+          "servers" => {
+            "go" => "gopls", "rust" => "rust-analyzer", "zig" => "zls", "c" => "clangd", "cpp" => "clangd",
+            "vue" => "vue-language-server --stdio", "python" => "ruff server", "ruby" => "typeprof --lsp --stdio",
+            "typescript" => "typescript-language-server --stdio", "javascript" => "typescript-language-server --stdio",
+            "bash" => "bash-language-server start", "crystal" => "crystalline", "gleam" => "gleam lsp"
+          }
+        },
+        "mcp" => { "enabled" => true, "servers" => {}, "timeout" => 10, "call_timeout" => 30, "async_load" => nil }, # async_load nil = env-aware; per-server "timeout" overrides
+        "ast" => { "async_warm" => nil }, # nil = env-aware default (false under RUBIK_TEST); repl/lifecycle.rb warm_up!
+        "context" => {
+          "include" => [],
+          "exclude" => [],
+          "max_tokens" => 32_768, # subagent context-window fallback when the routed model spec carries no context_limit (subagent/instance.rb, subagent/supervisor.rb)
+          "compaction_strategy" => "hybrid", # "hybrid", "prune_tool_results", "sliding_window", "off"
+          "max_tokens_ratio" => 0.85,
+          "tool_result_prune_chars" => 1500,
+          "preserve_first_n" => 2,
+          "preserve_last_n" => 6,
+          "safety_margin_tokens" => 1024,
+          "auto_recover_on_overflow" => true,
+          "log_failed_turns" => true,
+          "tool_chronicle_in_history" => true,  # Plan 85 D-2/D-3
+          "tool_chronicle_max_entries" => 15,   # Plan 85 D-2/D-3
+          "merge_turn_tool_history" => true,    # Plan 85 D-7
+          "merge_turn_tool_max_entries" => 20,  # Plan 85 D-7
+          "emergency_truncate_strategy" => "head_tail" # EmergencyCompactor hard-truncate layer: "head_tail" | "head_only" | "tail_only"
+        },
+        "ui" => {
+          "verbosity" => "normal",
+          "color" => "auto",
+          "glyphs" => "unicode",
+          "banner" => true,
+          "spinner" => true,
+          "spinner_verbs" => [], # empty = built-in verb set (ui/theme.rb from_config)
+          "markdown" => "live",
+          "statusline" => true,
+          "statusline_template" => "{model} · ctx {ctx} · {dirty} · sandbox {sandbox}",
+          "input_box" => false,
+          "paste_join_window_ms" => 120, # Plan 91: lines arriving within this gap join into one paste turn
+          "quiet_notices" => false # Plan 105: buffer background notices to inbox until prompt/enter
+        },
+        "workspace" => {
+          "additional_roots" => [],
+          "allowed_external_dirs" => [],
+          "allow_external_writes" => false,
+          "auto_index_additional" => true
+        },
+        "plugins" => {
+          "load" => [],
+          "aliases" => {},
+          "autoload_dropin" => true
+        },
+        "skills" => {
+          "enabled" => true,
+          "paths" => [],     # extra skill directories (absolute or root-relative)
+          "disabled" => [],  # skill names excluded from discovery
+          "max_body_chars" => 8000 # keep below tools.max_output_chars (head_tail would cut the middle)
+        },
+        "subagents" => {
+          "max_concurrency" => 10,
+          "max_depth" => 2,
+          "default_max_steps" => 88,
+          "provider_concurrency" => 2,
+          "budget_wait_timeout" => 180,
+          "auto_apply_buffer" => true,
+          "network_retry_count" => 3,
+          "network_backoff_base" => 0.5,
+          "error_wait_timeout" => 300,
+          "question_timeout" => 300,
+          # Bitmiş subagent bu grace (sn) sonrasında reap edilir (0 = kapalı);
+          # tombstone_limit sorgulanabilir mezar taşı sayısını sınırlar:
+          "reap_finished_after" => 300,
+          "tombstone_limit" => 25,
+          # Maestro kapısı: maestro write_file/replace_file_content/run_command/
+          # run_tests araçlarını doğrudan ÇALIŞTIRAMAZ — subagent'a devir zorunlu
+          # (false = doktrin yalnız prompt düzeyinde, kapı kapalı):
+          "maestro_gate" => true,
+          "auto_pause_on_network_error" => true,
+          "reactive_wakeup" => true,
+          # Vakanüvis arka plan kronikçisi (storage/vakanuvis; plan
+          # 2026-10-04 K1-K9): deterministik annal + wiki derleyicisi.
+          # enabled: Düzlem 1 harness'i kur/kurulama; distiller: Düzlem 2
+          # LLM doğumu (token üst sınırı flush_events x max_steps);
+          # flush_events: damıtıcı doğumu için olay eşiği; model: nil =
+          # root provider; retention: supersede (iz bırak) | purge (sil);
+          # root_turns: REPL kök-turn'leri de annal'a yazılsın mı
+          # (root-turn planı 2026-10-04; kapalıyken abonelik kurulmaz).
+          "vakanuvis" => {
+            "enabled" => true,
+            "distiller" => true,
+            "max_steps" => 8,
+            "flush_events" => 10,
+            "model" => nil,
+            "retention" => "supersede",
+            "root_turns" => true
+          },
+          # Pruner (repl/pruner): yarı deterministik KÖK pencere temizleyicisi.
+          # DEFAULT ON (kullanıcı kararı 2026-10-10) — deterministik yığın
+          # (trim_conversation_window! / ContextCompactor / EmergencyCompactor)
+          # her zaman güvenlik ağıdır; subagent kanalları bu özellikten asla
+          # etkilenmez; opt-out: "enabled" => false (kill-switch). enabled:
+          # harness'i kur (prune_context aracı + !prune komutu açılır);
+          # trigger_ratio: turn sonu pencere tahmini girdi tavanının bu
+          # oranına ulaşınca LLM budayıcı doğar (0.85'lik kör trim'den ÖNCE
+          # anlamsal sıkıştırma); target_ratio: plan yalnızca sonuç bu
+          # orana sığıyorsa uygulanır; max_steps/model: budayıcı bütçesi
+          # (nil = root provider); min_turns_between: otomatik doğum oranı
+          # sınırlayıcısı (turn sayısı).
+          "pruner" => {
+            "enabled" => true,
+            "trigger_ratio" => 0.6,
+            "target_ratio" => 0.35,
+            "max_steps" => 16,
+            "model" => nil,
+            "min_turns_between" => 5
+          }
+        },
+        # Goal ledger (SKILL.state ailesi, plan A): !goal'nun yapılandırılmış
+        # ΔΣ defteri — DEFAULT ON (kullanıcı kararı 2026-10-10; opt-out:
+        # enabled=false, o zaman araç/prompt/storage yüzü tamamen sessiz).
+        # max_patch_retries: ardışık reddedilen update_goal_ledger bütçesi.
+        # B/D anahtarları (verify / observe_projection) aynı hash'e eklenir.
+        "goal" => {
+          "ledger" => { "enabled" => true, "verify" => true, "observe_projection" => true,
+                        "observe_window" => 5, "max_patch_retries" => 2 }
+        },
+        "project" => { "test_command" => nil },
+        "test" => { "timeout" => 30, "runners" => {} }, # run_tests timeout (adapter/base.rb); per-language runner overrides (exec.rb)
+        "adapter" => {}
+      }.freeze
+
+      private
+
+      def validate_schema(config, schema = DEFAULT_CONFIG, prefix = "", strict: false)
+        raise ArgumentError, "Configuration must be a Hash, got #{config.class}" unless config.is_a?(Hash)
+
+        config.each do |key, val|
+          current_key = prefix.empty? ? key.to_s : "#{prefix}.#{key}"
+          if schema.is_a?(Hash) && !schema.key?(key.to_s)
+            candidate_keys = schema.keys
+            candidates = if defined?(Rubik::Tools::FuzzyMatcher)
+                           Rubik::Tools::FuzzyMatcher.best_matches(key.to_s, candidate_keys)
+                         else
+                           []
+                         end
+
+            suggestion_msg = if candidates && !candidates.empty?
+                               suggested_full = prefix.empty? ? candidates.first : "#{prefix}.#{candidates.first}"
+                               "Unknown config key '#{current_key}'. Did you mean '#{suggested_full}'?"
+                             else
+                               "Unknown config key '#{current_key}'."
+                             end
+
+            raise ArgumentError, suggestion_msg if strict
+
+            @warnings << suggestion_msg
+
+          elsif val.is_a?(Hash) && schema.is_a?(Hash) && schema[key.to_s].is_a?(Hash) && !schema[key.to_s].empty?
+            validate_schema(val, schema[key.to_s], current_key, strict: strict)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubik/config/model_catalog.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+# Provider/model catalog CRUD (G21 extraction from config.rb): the mutating
+# verbs over the `models.<role>` and `providers.<name>` storage shapes. The
+# read-side `model_spec` stays typed access in config.rb (Plan 66 ruling).
+# Public API is unchanged — these are Config instance methods via include;
+# config never prints, outcome hashes (ok/error/reason) let callers report.
+module Rubik
+  class Config
+    module ModelCatalog
+      def set_model_spec(role, provider:, name:, endpoint: nil, host: nil, persist: nil)
+        role_str = role.to_s.downcase
+        old_spec = fetch("models.#{role_str}")
+        @data["models"] ||= {}
+        spec_hash = {
+          "provider" => provider.to_s,
+          "name" => name.to_s
+        }
+        target_endpoint = endpoint || host
+        spec_hash["endpoint"] = target_endpoint if target_endpoint
+        @data["models"][role_str] = spec_hash
+
+        @data["model"] = spec_hash.dup if role_str == "default"
+
+        res = persisting?(persist) ? persist_result(save!(persist)) : { ok: true }
+        res[:reason] = :persist_failed unless res[:ok]
+        notify_change("models.#{role_str}", spec_hash, old_spec)
+        notify_change("model", spec_hash, old_spec) if role_str == "default"
+        res
+      end
+
+      # ── Provider-model catalog (providers.<name> storage shape) ──────────
+      # The spec hash and its "models" array (Hash entries with "name" /
+      # "context_limit"; legacy bare String names tolerated) are storage
+      # shape: commands ask intent here instead of re-encoding it per
+      # !model/!provider branch.
+
+      # Live spec hash for `provider`, or nil when unknown (absent or empty —
+      # the historical !provider "not found" semantics).
+      def provider_spec(provider)
+        spec = fetch("providers.#{provider}")
+        spec.is_a?(Hash) && !spec.empty? ? spec : nil
+      end
+
+      # Replace (or append) provider's catalog entry for `model` with the
+      # given context limit. {ok: false, reason: :unknown_provider} when the
+      # provider is unknown.
+      def upsert_provider_model(provider, model, context_limit:, persist: nil)
+        mutate_provider_models(provider, persist: persist) do |models|
+          models.reject! { |m| model_entry_name(m) == model }
+          models << { "name" => model, "context_limit" => context_limit }
+        end
+      end
+
+      # Drop provider's catalog entry for `model`. {ok: false,
+      # reason: :unknown_provider} when the provider is unknown; removing an
+      # absent model is a successful no-op (matches the historical
+      # !provider remove-model report).
+      def remove_provider_model(provider, model, persist: nil)
+        mutate_provider_models(provider, persist: persist) do |models|
+          models.reject! { |m| model_entry_name(m) == model }
+        end
+      end
+
+      # Drop a provider and its catalog entirely. Like the model verbs this
+      # notifies no listener — callers refresh the runtime explicitly. Routed
+      # through delete so the removal survives the disk merge.
+      def remove_provider(provider, persist: nil)
+        return { ok: false, error: "Provider '#{provider}' not found", reason: :unknown_provider } unless provider_spec(provider)
+
+        delete("providers.#{provider}", persist: persist)
+      end
+
+      private
+
+      def mutate_provider_models(provider, persist:)
+        p_spec = provider_spec(provider)
+        return { ok: false, error: "Provider '#{provider}' not found", reason: :unknown_provider } unless p_spec
+
+        models = Array(p_spec["models"]).dup
+        yield models
+        p_spec["models"] = models
+        set("providers.#{provider}", p_spec, persist: persist)
+      end
+
+      # Catalog entries are Hash-shaped today; older configs stored bare model
+      # name Strings. One predicate keeps the tolerance from drifting per verb.
+      def model_entry_name(entry)
+        entry.is_a?(Hash) ? entry["name"] : entry.to_s
+      end
+    end
+  end
+end