rubik 0.1.0

data/lib/rubik/repl/turn_recorder.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+require_relative "../prompt/context_compactor"
+require_relative "../coeffects"
+
+module Rubik
+  module REPL
+    # Plan 61: cross-turn conversational memory policy, included by Shell.
+    # Covers sticky route resolution (D-7), per-turn outcome recording for
+    # success/failure/cancel (D-2), and the token-budgeted conversation
+    # window (D-12). All state lives on Shell; this module only encodes
+    # the policy.
+    module TurnRecorder
+      MAX_CONVERSATION_ENTRIES = Rubik::Prompt::ContextCompactor::DEFAULT_MAX_CONVERSATION_ENTRIES
+
+      # Vakanüvis kök-turn olay adı — harness'in TURN_EVENT sabitiyle eş
+      # pinlenir (testler iki taraftan kilitler; isim çelişkisi koşuldan
+      # önce patlar).
+      TURN_EVENT_TARGET = :turn_finished
+
+      # Plan 61 D-7: sticky routing. Once a conversation has started,
+      # free-text turns keep the established provider/model instead of
+      # re-running keyword classification every turn (mid-conversation
+      # model/style/context-limit churn). `!model` resets the stamp via
+      # sync_default_provider; explicit task types (!plan/!goal) never
+      # touch it. Disable with `!config set router.sticky false`.
+      def resolve_turn_route(text)
+        sticky = @config.fetch("router.sticky", true) != false
+        return @conversation_route_stamp if sticky && @conversation_route_stamp && !@conversation_history.empty?
+
+        routed = @router.route(task_type: :auto, prompt: text)
+        @conversation_route_stamp = routed if routed && routed[:provider]
+        routed
+      end
+
+      # Plan 61 D-2: every free-text turn — success, failure, cancel —
+      # leaves a user/assistant pair in the conversation window so the
+      # model keeps the thread and !resume restores it. Failures record a
+      # tagged trace plus the attempted-work summary so the next turn knows
+      # what was already done.
+      def record_turn_outcome!(user_text, assistant_content, tokens: nil, streamed: nil)
+        return if user_text.to_s.strip.empty?
+        return if assistant_content.nil? || assistant_content.to_s.strip.empty?
+
+        @conversation_history << { role: "user", content: user_text }
+        @conversation_history << { role: "assistant", content: assistant_content.to_s }
+        trim_conversation_window!
+        @recorder&.record_assistant_response(assistant_content.to_s, tokens: tokens, streamed: streamed)
+      rescue StandardError => e
+        Rubik::Platform.debug_warn("turn outcome recording failed (#{e.class}: #{e.message}); turn lost from conversation memory")
+        nil
+      end
+
+      def record_failed_turn!(user_text, kind, reason, orchestrator)
+        return if @config.fetch("context.log_failed_turns", true) == false
+
+        label = case kind
+                when "cancelled" then "[Turn cancelled by user (^C)]"
+                when "incomplete" then "[Turn incomplete: #{reason}]"
+                else "[Turn failed: #{reason}]"
+                end
+        summary = if orchestrator.respond_to?(:activity)
+                    orchestrator.activity.summary(orchestrator.buffer_manager).to_s.strip
+                  else
+                    ""
+                  end
+
+        # Plan 85 D-3: kronolojik tool listesi (D-2'deki chronological_summary).
+        chronicle_enabled = @config.fetch("context.tool_chronicle_in_history", true)
+        max_entries = @config.fetch("context.tool_chronicle_max_entries", 15).to_i
+        tool_chronicle = if chronicle_enabled &&
+                            orchestrator.respond_to?(:activity) &&
+                            orchestrator.activity.respond_to?(:chronological_summary)
+                           chron = orchestrator.activity.chronological_summary(max_entries: max_entries).strip
+                           chron.empty? ? "" : "\nTool calls made:\n#{chron}"
+                         else
+                           ""
+                         end
+
+        parts = []
+        parts << label
+        parts << "Partial progress before this outcome:\n#{summary}" unless summary.empty?
+        parts << tool_chronicle unless tool_chronicle.empty?
+        body = "#{parts.first}#{parts[1..].map { |p| "\n#{p}" }.join}"
+
+        # R9: log_failed_turns kapalıysa başarısız turn hiçbir yere
+        # kaydedilmez — kronik de dahil (least surprise).
+        emit_turn_finished(kind: kind, prompt: user_text, outcome: body, orchestrator: orchestrator)
+        record_turn_outcome!(user_text, body)
+      rescue StandardError => e
+        Rubik::Platform.debug_warn("failed-turn recording crashed (#{e.class}: #{e.message}); failure context lost")
+        nil
+      end
+
+      # Vakanüvis kök-turn kapısı (root-turn planı 2026-10-04): her REPL
+      # turn'ünün sonu deterministik tek satıra indirgenip bus'a düşer.
+      # Sessizlik sözleşmesi aynen — :turn_finished WAKE_KINDS dışındadır,
+      # tek abone vakanüvis harness'idir; notice yayılmaz. Emisyon asla
+      # turn'ü bozmaz: bus yoksa no-op, patlarsa debug_warn.
+      def emit_turn_finished(kind:, prompt:, outcome:, orchestrator: nil, tokens: nil)
+        return unless @event_bus.respond_to?(:post)
+
+        # Süs bozulursa olay düşmesin: tally degradasyonu kendi rescue'sunda
+        # ("") kalır, post için ayrılan dış rescue bozulmuş bus'u yakalar.
+        tools = begin
+          orchestrator.respond_to?(:activity) ? orchestrator.activity.tool_tally : ""
+        rescue StandardError => e
+          Rubik::Platform.debug_warn("tool tally failed (#{e.class}: #{e.message}); chronicling without tools")
+          ""
+        end
+        # Loop'ün token sayacı Hash'tir ({input:, output:}) — kronik satırı
+        # tek skaler ister; Hash toplamı alınır (Numeric olmayan üye sessizce
+        # elenir — üretici asla böyle göndermez, savunma derinliği), diğer
+        # şekiller to_i'ye iner. Düzleşme burada (üretici) VE turn_line'da
+        # (derinlemesine savunma) yaşar: iki taraf da tek başına dayanıklı.
+        tokens_val = tokens.is_a?(Hash) ? tokens.values.filter_map { |v| v.to_i if v.respond_to?(:to_i) }.sum : tokens.to_i
+        @event_bus.post(TURN_EVENT_TARGET,
+                        { kind: kind.to_s, prompt: prompt.to_s, outcome: outcome.to_s,
+                          tools: tools.to_s, tokens: tokens_val }, subsystem: :repl)
+      rescue StandardError => e
+        Rubik::Platform.debug_warn("turn-finished emission failed (#{e.class}: #{e.message}); turn not chronicled")
+        nil
+      end
+
+      # Plan 61 D-12: the long-lived REPL memory is trimmed by a token
+      # budget (plus an absolute entry cap) so one huge turn cannot evict
+      # the whole thread, and eviction order stays oldest-first.
+      def trim_conversation_window!
+        ceiling = begin
+          spec = current_model_spec
+          @llm_registry.effective_input_limit_for(spec["provider"], spec["name"])
+        rescue StandardError => e
+          Rubik::Platform.debug_warn("input ceiling lookup failed (#{e.class}: #{e.message}); using nil budget")
+          nil
+        end
+        @conversation_history = Rubik::Prompt::ContextCompactor.trim_history_to_budget(
+          @conversation_history, ceiling: ceiling, max_entries: MAX_CONVERSATION_ENTRIES
+        )
+      rescue StandardError => e
+        Rubik::Log.warn(:repl, "conversation trim failed (#{e.class}: #{e.message}); window may exceed token budget")
+        nil
+      end
+
+      # Plan 85 D-7 (kök neden): turn sonunda turn içi @history'deki tool ara
+      # adımlarını (role: "tool" mesajları) conversation_history'ye kopyalar;
+      # hata veya başarı fark etmez. Böylece continue'da model turn sırasındaki
+      # tüm bağlamı görür ve "sıfırdan keşfe" başlamaz.
+      # loop.rb'ye dokunmaz: caller res[:loop_instance].history üzerinden turn
+      # içi @history'yi okur (turn_result zaten loop_instance + history accessor
+      # döndürür).
+      def merge_turn_tool_history!(turn_history, max_entries: 20)
+        return false if turn_history.nil? || turn_history.empty?
+        return false unless @config.fetch("context.merge_turn_tool_history", true)
+
+        # Yalnızca tool sonucu taşıyan mesajları filtrele; en SON max_entries
+        # adımı al — bir sonraki turn'ün ihtiyacı olan, turn'in güncel arazi
+        # durumudur (hangi edit'ler tuttu, son hatalar), turn'in başı değil.
+        tool_msgs = turn_history.select do |m|
+          role = m[:role] || m["role"]
+          role == "tool" || m[:tool_calls] || m["tool_calls"]
+        end.last(max_entries)
+        return false if tool_msgs.empty?
+
+        @conversation_history.concat(tool_msgs)
+
+        # conversation_history artık tam tool sonuçları taşıdığından trim zorunludur.
+        trim_conversation_window!
+        true
+      rescue StandardError => e
+        Rubik::Platform.debug_warn("tool-history merge failed (#{e.class}: #{e.message}); next turn starts without tool context")
+        nil
+      end
+
+      # Plan 61 D-13: the model spec the CURRENT conversation is bound to
+      # (sticky stamp when present), falling back to the default role.
+      def current_model_spec
+        stamp = @conversation_route_stamp
+        return stamp[:spec] if stamp.is_a?(Hash) && stamp[:spec].is_a?(Hash) && stamp[:spec]["provider"]
+
+        @config.model_spec(:default)
+      end
+
+      # Pruner apply seam (context-pruner 2026-10-09): turn thread'inde,
+      # orchestrator.run pencereyi tohumlamadan HEMEN ÖNCE çağrılır — hem
+      # execute_free_text (input_execution.rb) hem !goal (agent_execution.rb
+      # ctx.apply_staged_prune_plan! üzerinden). Kopyala-doğrula-takas:
+      # take_applicable_plan! yeni dizi döner; herhangi bir ihlalde nil ve
+      # pencere olduğu gibi kalır. Replay sırasında atlanır (yeniden
+      # oynatılan oturumu budamak kaydı çarpıtır); pruner kapalıysa (coeffect
+      # yok) no-op'tur.
+      def apply_staged_prune_plan!
+        return if @replaying
+
+        harness = Rubik::Coeffects.get(@runtime_manager&.context, Rubik::Coeffects::PRUNER)
+        return unless harness
+
+        new_window, receipt = harness.take_applicable_plan!(@conversation_history)
+        return unless new_window
+
+        @conversation_history = new_window
+        line = "[Pruner] Applied staged plan: dropped #{receipt[:dropped]} unit(s), " \
+               "summarized #{receipt[:summarized]} (#{receipt[:skipped_stale]} stale op(s) skipped) — " \
+               "window ~#{receipt[:before_tokens]} -> ~#{receipt[:after_tokens]} tokens."
+        if @terminal_guard
+          @terminal_guard.print_safe_notice(line)
+        else
+          @output.puts(line)
+        end
+      rescue StandardError => e
+        Rubik::Log.warn(:repl, "staged prune apply failed (#{e.class}: #{e.message}); window untouched")
+        nil
+      end
+
+      # Session continuity (Plan 34/61): hydrate a recorded session into
+      # the live conversation window.
+      def resume_session(identifier = :latest)
+        root_d = @buffer_manager&.root_dir || Dir.pwd
+        home_d = @config&.home_dir || ENV.fetch("HOME", nil)
+
+        target_file = if identifier == :latest || identifier.to_s.downcase == "latest"
+                        Rubik::Session::Manager.find_latest_session(root_d, home_d, exclude_file: @recorder&.session_file, config: @config)
+                      else
+                        Rubik::Session::Manager.find_session(identifier, root_d, home_d, config: @config)
+                      end
+
+        return { ok: false, error: "No past session found matching '#{identifier}'" } unless target_file
+
+        res = Rubik::Session::Manager.restore_session(self, target_file)
+        @output.puts "[Rubik::Session] Resumed session: #{File.basename(target_file)} (#{res[:turns_hydrated]} dialogue turns hydrated, 0 API tokens used)" if res[:ok]
+        res
+      end
+    end
+  end
+end

data/lib/rubik/repl.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "repl/command_parser"
+require_relative "repl/hooks"
+require_relative "repl/step_formatter"
+require_relative "repl/commands"
+require_relative "repl/terminal_guard"
+require_relative "repl/pruner"
+require_relative "repl/shell"
+
+module Rubik
+  module REPL
+  end
+end

data/lib/rubik/runtime/ast_service.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative "../ast"
+require_relative "../coeffects"
+require_relative "service_registration"
+
+require_relative "../platform"
+
+module Rubik
+  module Runtime
+    module ASTService
+      module_function
+
+      def register(context_or_manager, ast_graph, cache_store: nil)
+        ServiceRegistration.call(context_or_manager) do |ctx|
+          next ast_graph unless ctx
+
+          ctx.provide(Rubik::Coeffects::AST_GRAPH, ast_graph)
+
+          ctx.on_dispose do
+            begin
+              ast_graph.save_to_cache(cache_store) if cache_store && ast_graph.respond_to?(:save_to_cache)
+            rescue StandardError => e
+              # Report but keep draining: a failed cache save must not abort
+              # the LIFO unwind, and silence here would leak a stale symbol
+              # cache with no trace.
+              warn "[ASTService] cache save failed: #{e.class}: #{e.message}"
+            end
+            ast_graph.clear if ast_graph.respond_to?(:clear)
+          end
+
+          ast_graph
+        end
+      end
+
+      # Drop graph entries for files inside the project root that the context
+      # scanner no longer reports — e.g. subtrees that became covered by an
+      # ignore rule (the scanner's whole-subtree pruning is stronger than the
+      # legacy one-level fnmatch filter). Without this, symbols loaded from a
+      # pre-upgrade cache would linger in the graph and be re-saved forever.
+      # Guarded on a non-empty scan so a failed scan can never wipe the graph.
+      # Files outside the primary root (additional roots, external dirs) are
+      # untouched: the context index may not cover them.
+      # Returns the number of purged entries.
+      def purge_stale_entries!(ast_graph, context_index, root_dir)
+        files = context_index.files
+        return 0 if files.empty?
+
+        is_win = Rubik::Platform.windows?
+        norm_root = Rubik::Platform.normalize_path_raw(root_dir).chomp("/")
+        root_prefix = "#{norm_root}/"
+        root_prefix_cmp = is_win ? root_prefix.downcase : root_prefix
+
+        known_keys = if is_win
+                       files.keys.to_h { |k| [k.downcase, true] }
+                     else
+                       files.keys.to_h { |k| [k, true] }
+                     end
+
+        supported = Rubik::AST::Extractor.supported_extensions
+        stale = []
+
+        ast_graph.file_symbols.each_key do |path|
+          norm = Rubik::Platform.normalize_path_raw(path)
+          norm_cmp = is_win ? norm.downcase : norm
+          next unless norm_cmp.start_with?(root_prefix_cmp)
+
+          rel = norm[root_prefix.length..]
+          rel_key = is_win ? rel.downcase : rel
+          stale << path if supported.include?(File.extname(rel).downcase) && !known_keys.key?(rel_key)
+        end
+
+        stale.each { |path| ast_graph.remove_file(path) }
+        stale.size
+      end
+    end
+  end
+end

data/lib/rubik/runtime/context.rb

@@ -0,0 +1,335 @@
+# frozen_string_literal: true
+
+require "monitor"
+require_relative "../coeffects"
+
+module Rubik
+  module Runtime
+    class CoeffectMissingError < StandardError; end
+
+    # Raised when a disposed context is asked to create new scope. Unlike a
+    # late inverse (which can run now), there is no meaningful fallback for
+    # extend, so it fails fast (AGENTS.md Fail Fast template).
+    class ContextDisposedError < StandardError; end
+
+    class Context
+      attr_reader :parent
+
+      # Legacy alias -> canonical key, derived from the Rubik::Coeffects SSOT
+      # (AGENTS.md §1.B). Providers publish canonical keys only; consumers may
+      # still ask with documented legacy names (e.g. plugin DSL inject: [:tools]).
+      CANONICAL_OF = Rubik::Coeffects::ALIAS_TO_CANONICAL
+      # Canonical key -> legacy alias spellings (forward half of the SSOT).
+      LEGACY_ALIASES = Rubik::Coeffects::LEGACY_ALIASES
+
+      def initialize(parent: nil)
+        @parent = parent
+        @monitor = Monitor.new
+        @services = {}
+        # Delete-inverse handles keyed by service / child, so explicit
+        # removals (unprovide, child prune) can also retract the inverse
+        # from the Omega accumulator instead of leaving dead no-ops behind.
+        @service_inverses = {}
+        @child_inverses = {}
+        @disposables = []
+        @children = []
+        @disposed = false
+        @last_dispose_errors = []
+      end
+
+      def register_disposable(cleanup_fn = nil, &block)
+        inverse = cleanup_fn || block
+        return unless inverse
+
+        @monitor.synchronize do
+          if @disposed
+            # Ω is sealed: the context is already torn down, so there is no
+            # later drain that would run this inverse. Execute it now instead
+            # of silently storing it in a dead accumulator (leaked cleanup).
+            run_inverse(inverse)
+          else
+            @disposables << inverse
+          end
+        end
+        inverse
+      end
+      alias on_dispose register_disposable
+
+      # Number of pending inverse operations in the Omega accumulator.
+      # Exposed for runtime visualization (!agents panel, !runtime).
+      def disposable_count
+        @monitor.synchronize { @disposables.size }
+      end
+
+      def services
+        @monitor.synchronize { @services.dup.freeze }
+      end
+
+      def service_names
+        @monitor.synchronize { @services.keys }
+      end
+
+      def last_dispose_errors
+        @monitor.synchronize { @last_dispose_errors.dup }
+      end
+
+      def provide(name, service)
+        key = name.to_s.downcase
+        @monitor.synchronize do
+          already_provided = @services.key?(key)
+          @services[key] = service
+          return if already_provided
+
+          # Exactly one delete-inverse per key for the context's lifetime:
+          # re-providing a service swaps the value but never stacks a second
+          # inverse into the Omega accumulator (AGENTS.md zero-restart rule).
+          # The handle is kept so unprovide can retract it symmetrically.
+          @service_inverses[key] = register_disposable { @services.delete(key) }
+        end
+      end
+
+      # Removes a service AND its delete-inverse from the accumulator, the
+      # symmetric counterpart of provide. Callers own the reactive surface:
+      # unlike Runtime::Manager#provide, removal triggers no reconciliation.
+      # Re-providing the key afterwards registers a fresh inverse, so
+      # provide/unprovide cycles return Ω to its baseline (zero-restart).
+      def unprovide(name)
+        key = name.to_s.downcase
+        @monitor.synchronize do
+          return unless @services.key?(key)
+
+          @services.delete(key)
+          inverse = @service_inverses.delete(key)
+          @disposables.delete(inverse) if inverse
+        end
+      end
+
+      def require(name)
+        value = resolve_coeffect(name.to_s.downcase)
+        return value unless value.nil?
+
+        raise CoeffectMissingError, "Required coeffect '#{name}' is not satisfied in the context."
+      end
+
+      def get(name, default = nil)
+        val = resolve_coeffect(name.to_s.downcase)
+        val.nil? ? default : val
+      end
+
+      # Walk the context chain for a literal key. Returns nil when the key is
+      # absent (services are always live objects, never nil, in this runtime).
+      # Per-hop locking: each context holds only its own monitor during the
+      # local lookup and releases it before recursing to the parent, so
+      # chained reads never nest child→parent locks (disposal nests only
+      # parent→child; the reverse order would risk deadlock).
+      def resolve(key)
+        found, local = @monitor.synchronize do
+          [@services.key?(key), @services[key]]
+        end
+        return local if found && !local.nil?
+
+        @parent&.resolve(key)
+      end
+
+      def satisfied?(dependencies)
+        Array(dependencies).all? { |dep| has?(dep) }
+      end
+
+      def has?(name)
+        !resolve_coeffect(name.to_s.downcase).nil?
+      end
+
+      # Single-pass coeffect resolution: per hop, under one monitor hold, all
+      # three spellings of the requested key are tried atomically — the
+      # literal key (a third party may have provided the alias itself), its
+      # canonical form (the request used a legacy name), then its legacy
+      # aliases (the request used the canonical name but a provider
+      # registered the short form). Scoping wins over spelling: the nearest
+      # provider wins regardless of which spelling it registered under.
+      # Per-hop locking and the parent→child lock order: see `resolve`.
+      # Protected (not private): the parent-chain recursion needs an
+      # explicit receiver — the same boundary as prune_child, so external
+      # callers get NoMethodError (closes the accidentally-public
+      # resolve_with_alias surface).
+      def resolve_coeffect(key)
+        local = @monitor.synchronize do
+          if @services.key?(key)
+            @services[key]
+          elsif (canonical = CANONICAL_OF[key]) && @services.key?(canonical)
+            @services[canonical]
+          else
+            aliases = LEGACY_ALIASES[key]
+            found = nil
+            aliases&.each do |alias_key|
+              # key? probing, never truthiness (test_coeffects_falsy).
+              next unless @services.key?(alias_key)
+
+              found = @services[alias_key]
+              break
+            end
+            found
+          end
+        end
+        return local unless local.nil?
+
+        @parent&.resolve_coeffect(key)
+      end
+      protected :resolve_coeffect
+
+      def extend
+        child = nil
+        @monitor.synchronize do
+          if @disposed
+            raise ContextDisposedError,
+                  "Cannot extend a disposed context. To fix, check `disposed?` before extending or create a fresh context."
+          end
+
+          child = Context.new(parent: self)
+          @children << child
+          # Keep the cascade-inverse handle so a child disposed before its
+          # parent (epoch close, per-turn loop context, MCP reconnect) can
+          # prune both itself and the dead inverse out of this context.
+          @child_inverses[child] = register_disposable { child.dispose unless child.disposed? }
+        end
+        child
+      end
+
+      def disposed?
+        @disposed
+      end
+
+      # Internal counterpart of extend: a disposed child removes itself and
+      # its dead cascade inverse from this context. Extension contexts open
+      # and close constantly (per-turn loop contexts, MCP reconnects, tool
+      # epochs, fiber reactivations) — without the prune every cycle would
+      # leave a dead child and a no-op inverse in the accumulator forever
+      # (AGENTS.md zero-restart rule). Protected: only Context itself may
+      # strip a child's bookkeeping, so external code cannot unhook a live
+      # child (leak footgun). Must be called AFTER the child released its
+      # own monitor, so child disposal never nests child→parent locks
+      # against the parent→child order used by dispose. No-op on a disposed
+      # parent (its own drain owns the bookkeeping by then).
+      def prune_child(child)
+        @monitor.synchronize do
+          return if @disposed
+
+          @children.delete(child)
+          inverse = @child_inverses.delete(child)
+          @disposables.delete(inverse) if inverse
+        end
+      end
+      protected :prune_child
+
+      def dispose
+        parent = nil
+        deferred_interrupt = nil
+        @monitor.synchronize do
+          return if @disposed
+
+          @disposed = true
+          parent = @parent
+          # Reset BEFORE the child cascade so signals adopted from children
+          # (record_deferred_signal) survive into the final
+          # last_dispose_errors instead of being wiped by this reset.
+          @last_dispose_errors = []
+          dmesg = resolve_dmesg
+          # Counted before the cascade: disposing children prune their
+          # inverses from our accumulator (pre-cascade size is what the
+          # "beginning" log reports).
+          dmesg&.log(:context, :info, "Beginning context dispose with #{@disposables.size} inverse(s)")
+
+          deferred_interrupt = dispose_children
+          drained, drain_signal = drain_inverses(dmesg: dmesg)
+          deferred_interrupt ||= drain_signal
+
+          dmesg&.log(:context, :info, "Context dispose complete; #{drained} inverse(s) executed")
+        end
+        # Release the child's monitor before reaching the parent (lock
+        # order), then prune the parent's record of this child.
+        parent&.prune_child(self)
+        # Re-surface the FIRST deferred signal only after the unwind is
+        # fully complete — Ctrl+C during teardown still reaches the
+        # caller (repo convention: Interrupt is never swallowed), never
+        # at the cost of a half-drained accumulator.
+        raise deferred_interrupt if deferred_interrupt
+      end
+      alias dispose! dispose
+
+      private
+
+      # Phase 1: dispose child contexts first (parent→child lock order;
+      # children never hold their lock while reaching back to the parent).
+      # Each child's prune is a no-op here (@disposed sealed the bookkeeping),
+      # so the descending iteration never observes mutation. A child's
+      # deferred Interrupt/SystemExit is adopted as (possibly) the FIRST
+      # signal of this cascade; returns the first deferred child signal.
+      def dispose_children
+        deferred = nil
+        @children.reverse_each do |child|
+          child.dispose unless child.disposed?
+        rescue Interrupt, SystemExit => e
+          record_deferred_signal(e)
+          deferred ||= e
+        end
+        @children.clear
+        deferred
+      end
+
+      # Phase 2: execute accumulated inverses in strict reverse order
+      # (LIFO — Omega accumulator). A failing inverse never aborts the unwind
+      # (AGENTS.md §5): record it, report, keep draining. Interrupt/SystemExit
+      # get the same complete-drain policy: the signal is recorded and
+      # deferred, the drain ALWAYS finishes, and the first signal is re-raised
+      # by dispose after bookkeeping and the parent prune. Late registration
+      # racing the drain is monitor-serialized (pop loop, or the sealed
+      # immediate-run path). Returns [drained, first_signal].
+      def drain_inverses(dmesg:)
+        drained = 0
+        deferred = nil
+        begin
+          while (inverse = @disposables.pop)
+            begin
+              run_inverse(inverse, dmesg: dmesg)
+              drained += 1
+            rescue Interrupt, SystemExit => e
+              record_deferred_signal(e)
+              deferred ||= e
+            end
+          end
+        ensure
+          @services.clear
+          @service_inverses.clear
+          @child_inverses.clear
+        end
+        [drained, deferred]
+      end
+
+      def resolve_dmesg
+        d = @services["dmesg"] || resolve("dmesg")
+        d if d.respond_to?(:log)
+      rescue StandardError
+        nil
+      end
+
+      def record_deferred_signal(exception)
+        @last_dispose_errors << exception
+        Rubik::Log.warn(:runtime, "dispose inverse raised #{exception.class} (deferred until drain completes): #{exception.message}")
+      end
+
+      # Runs one inverse, never letting a failure abort the unwind (AGENTS.md §5):
+      # record it, report to stderr, keep going. Interrupt/SystemExit are NOT
+      # rescued here: the drain loop in dispose defers them so the unwind
+      # completes first (complete-drain-then-re-raise policy), while the
+      # sealed immediate-run path in register_disposable lets them propagate
+      # as-is — there is no accumulator left to protect there.
+      def run_inverse(inverse, dmesg: nil)
+        inverse.call
+      rescue StandardError => e
+        @last_dispose_errors << e
+        Rubik::Log.warn(:runtime, "dispose inverse failed: #{e.class}: #{e.message}")
+        dmesg ||= resolve_dmesg
+        dmesg&.log(:context, :err, "Dispose inverse failed: #{e.class}: #{e.message}")
+      end
+    end
+  end
+end