samagotchi 0.38.0 → 0.40.0

data/lib/samagotchi/kernel_loop.rb

@@ -24,6 +24,10 @@ require_relative "muted_memories"
 require_relative "tool_activity"
 require_relative "tool_runner"
 require_relative "tool_response"
+require_relative "tool_ids"
+require_relative "llm_context_view"
+require_relative "llm_context_apply"
+require_relative "llm_context_forget"
 require_relative "answer_display"
 require_relative "llm/model_result"
 require_relative "llm/turn_settings"
@@ -94,6 +98,10 @@ module Samagotchi
       rescue StandardError => e
         "Error: ask_user_question handler failed: #{e.message}"
       end
+
+      # forget_outputs: the forget layer's call on the running turn's
+      # conversation (KernelLoop#forget_outputs).
+      def forget_outputs(call) = @kernel.forget_outputs(call)
     end
 
     DEFAULT_MAX_TOOL_OUTPUT_CHARS = 10_000
@@ -162,6 +170,9 @@ module Samagotchi
     # The Engine's PromptWarmup: a request asks it for a slot pin
     # (#take_pin) while the turn-end warm-up still runs; nil: never pinned.
     attr_accessor :warmup
+    # The turn a forget_outputs call works on (LLMContextForget::Turn: its
+    # conversation and ContextStatus); both loops set it as a turn starts.
+    attr_accessor :llm_context_turn
     # @return [Integer, nil] the llama.cpp slot (`id_slot`) the last
     #   request of the last run streamed from; nil when the server named
     #   none (other transports) or no request was made
@@ -196,7 +207,10 @@ module Samagotchi
         turn.iteration = iteration_index + 1
         outcome = iterate(turn)
         return outcome if outcome.is_a?(LLM::ModelResult)
-        break if outcome == :answer
+        next unless outcome == :answer
+
+        turn.answered = true
+        break
       rescue Client::RequestCancelled => e
         emit(turn, type: :generation_cancelled, iteration: turn.iteration, reason: e.reason,
                    stopped_by: turn.cancel_controller&.stopped_by)
@@ -248,7 +262,7 @@ module Samagotchi
     Turn = Struct.new(:conversation, :context, :empty_retry, :tool_activity, :buffer, :streamed_thinking, :qwen_attempts,
                       :qwen_partial, :prefill, :pending_tool_calls, :model_name, :pending_input, :on_stream_event,
                       :cancel_controller, :cap, :emit, :iteration, :empty_steps, :ended_empty, :malformed_retried,
-                      :uncached_next, keyword_init: true)
+                      :uncached_next, :answered, keyword_init: true)
     # One request: the prompt and its images as sent, the images' token
     # estimate, and the window it was measured against.
     Request = Struct.new(:prompt, :images, :image_tokens, :window, :prefill, keyword_init: true)
@@ -264,8 +278,10 @@ module Samagotchi
 
     def start_turn(messages, on_stream_event:, cancel_controller:, pending_input:, cap:)
       conversation = prepare_conversation(messages)
+      context = ContextStatus.new(conversation: conversation, llm_context: @turn_settings.llm_context)
+      @llm_context_turn = LLMContextForget::Turn.new(conversation: conversation, context: context)
       Turn.new(
-        conversation: conversation, context: ContextStatus.new(conversation: conversation),
+        conversation: conversation, context: context,
         empty_retry: EmptyAnswerRetry.new, empty_steps: [], tool_activity: [], buffer: +"", streamed_thinking: +"",
         qwen_attempts: 0, qwen_partial: nil,
         # Qwen with thinking off: an empty thought after the cue, so the model
@@ -305,6 +321,7 @@ module Samagotchi
     # (the prompt cache keeps its prefix), and the prompt is formatted again
     # with it.
     def prepare_request(turn)
+      apply_llm_context!(turn.conversation, context: turn.context)
       prompt, images = format_prompt(turn)
       image_tokens = images.empty? ? 0 : ImagePlan.estimated_tokens(turn.conversation)
       window = ContextWindow.resolve(client: @client, model: turn.model_name, setting: @turn_settings.window_setting)
@@ -321,7 +338,8 @@ module Samagotchi
     end
 
     def format_prompt(turn)
-      Prompt.format_with_images(turn.conversation, profile: @profile, vision: @turn_settings.vision, prefill: turn.prefill)
+      Prompt.format_with_images(llm_context_view.messages(turn.conversation), profile: @profile,
+                                                                             vision: @turn_settings.vision, prefill: turn.prefill)
     end
 
     # One streamed request, under the generation's own controller: a
@@ -420,6 +438,11 @@ module Samagotchi
 
     def cache_fields(cache) = cache ? TokenUsage.cache_fields(**cache) : {}
 
+    def reprefill_field(model, cache)
+      tokens = cache && reprefilled_tokens(model, prompt: cache[:prompt], cached: cache[:cached])
+      tokens ? { reprefill_tokens: tokens } : {}
+    end
+
     # The cut stream's visible text goes with it: the buffer as it was
     # before (the next generation gets a fresh splitter).
     def cut_generation(turn, generation, buffer_mark)
@@ -437,7 +460,8 @@ module Samagotchi
       emit(turn, type: :generation_completed, iteration: turn.iteration, content_length: response.length,
                  thinking_chars: thinking_chars(response, generation.streamed_thinking),
                  served_model: generation.served_model, requested_model: turn.model_name,
-                 finish_reason: generation.finish_reason, **cache_fields(generation.cache))
+                 finish_reason: generation.finish_reason, **cache_fields(generation.cache),
+                 **reprefill_field(turn.model_name, generation.cache))
       dump_log("response", generation.response, iteration: turn.iteration)
       # The after_generation hook (after the model returns, before the tool
       # parse), with a read-only copy of the conversation as sent.
@@ -541,8 +565,9 @@ module Samagotchi
       runs = ToolResponse.run_batch(tool_runner, calls, iteration: turn.iteration, emit: turn.emit,
                                                         on_stream_event: turn.on_stream_event, cap: turn.cap)
       turn.tool_activity.concat(ToolResponse.activities(runs))
-      # One entry for the batch: the capped outputs joined (ToolResponse.joined).
-      turn.conversation << ToolResponse.joined(runs)
+      # One entry for the batch: the capped outputs joined (ToolResponse.joined),
+      # an id per run (ToolIds).
+      turn.conversation << ToolResponse.joined(runs, ids: ToolIds.next_ids(turn.conversation, runs.size))
       turn.pending_tool_calls = true
       :next
     end
@@ -552,6 +577,10 @@ module Samagotchi
     # then the answer shows only its text.
     def finish(turn)
       exhausted = turn.pending_tool_calls && tool_response_turn?(turn.conversation.last)
+      # The model answered: the staged edits reach the session now (a turn
+      # that ran out of steps, on tool results or on a retry's nudge, is
+      # mid-task; they wait).
+      apply_llm_context!(turn.conversation, moment: :turn_end) if turn.answered
       # An empty answer left the conversation: an earlier model message
       # isn't this turn's answer.
       output = turn.ended_empty ? "" : strip_thought_blocks(last_model_content(turn.conversation))
@@ -710,11 +739,18 @@ module Samagotchi
     # The next turn's prompt up to where its user message starts, for the
     # turn-end warm-up (PromptWarmup): +messages+ as the next turn sends
     # them before its prompt (the history under the system head), formatted
-    # as #run formats them, with a stand-in user message cut off at its
-    # opener. Returns [prompt, images], or nil when the cut isn't found.
-    def warmup_prompt(messages)
-      conversation = prepare_conversation(messages) << { role: "user", content: WARMUP_CUT }
-      prompt, images = Prompt.format_with_images(conversation, profile: @profile, vision: @turn_settings.vision)
+    # as #run formats them (through the LLMContextView too), with a
+    # stand-in user message cut off at its opener. +llm_context+: the next
+    # turn's strategy (LLMContextStrategy::Resolved; the Engine resolves it
+    # for the model the next turn runs on, after a /model switch too),
+    # else the last turn's. Returns [prompt, images], or nil when the cut
+    # isn't found.
+    def warmup_prompt(messages, llm_context: @turn_settings&.llm_context)
+      conversation = prepare_conversation(messages)
+      apply_llm_context!(conversation, llm_context, warmup: true)
+      conversation << { role: "user", content: WARMUP_CUT }
+      prompt, images = Prompt.format_with_images(llm_context_view(llm_context).messages(conversation),
+                                                 profile: @profile, vision: @turn_settings.vision)
       head = prompt[0, prompt.index(WARMUP_CUT) || 0]
       cut = head.rindex(user_opener)
       cut&.positive? ? [head[0, cut], images] : nil
@@ -723,6 +759,98 @@ module Samagotchi
     WARMUP_CUT = "chi-warmup-cut"
     private_constant :WARMUP_CUT
 
+    # What both loops send of the conversation (LLMContextView), under the
+    # turn's strategy (TurnSettings#llm_context, none without one), or the
+    # one given (the warm-up's, the next turn's): the prompt, the warm-up
+    # and the chat messages all format through it, so the warm-up warms
+    # the prompt the next turn sends.
+    def llm_context_view(llm_context = @turn_settings&.llm_context)
+      LLMContextView.new(strategy: llm_context&.strategy || LLMContextView::NONE)
+    end
+
+    # The turn's LLM context layers ([] under none): the tools they add
+    # (Tools::Registry#entries) are the turn's to offer and dispatch.
+    def llm_context_layers = @turn_settings&.llm_context&.active_layers || []
+
+    # The model's forget_outputs call (LLMContextForget) on the running
+    # turn, under its strategy; the apply rule runs on the turn's
+    # conversation at once, as at a request, so the result says whether the
+    # stubs go with the next request or wait for the turn's end.
+    # @return [String] the tool result
+    def forget_outputs(call)
+      llm_context = @turn_settings&.llm_context
+      turn = @llm_context_turn
+      unless turn && llm_context&.active_layers&.include?(:forget)
+        return "Error: forget_outputs is off (the llm_context strategy has no forget layer)"
+      end
+
+      LLMContextForget.call(turn, call, llm_context: llm_context,
+                                        apply: -> { apply_llm_context!(turn.conversation, llm_context, context: turn.context) })
+    end
+
+    # Before each request of both loops (+moment+ :request; the warm-up
+    # too, on its own copy, as the next turn's first request) and at the
+    # end of a turn the model answered (:turn_end): the strategy's layers
+    # stage their edits on +conversation+ and the apply rule
+    # (LLMContextApply, llm_context.apply) saves the batch it lets through
+    # as applied, so the request about to be sent (or the next turn's
+    # first, and the warm-up) is the first with the stubs. +context+: the
+    # turn's ContextStatus (payoff applies in its top bucket; an applied
+    # batch rebases its estimate, ContextStatus#edited!). none changes
+    # nothing. Logged as llm_context_apply when a batch is applied.
+    # @return [LLMContextApply::Outcome]
+    def apply_llm_context!(conversation, llm_context = @turn_settings&.llm_context, moment: :request, context: nil,
+                           warmup: false)
+      view = llm_context_view(llm_context)
+      return LLMContextApply::Outcome.none if view.none?
+
+      outcome = LLMContextApply.run!(conversation, layers: view.layers, rule: llm_context.apply, moment: moment,
+                                                   protect_steps: llm_context.protect_steps,
+                                                   top_bucket: context&.top_bucket? || false,
+                                                   changes: llm_context.stale_edits)
+      if outcome.applied?
+        # The prompt just shrank: the context estimate counts from it.
+        context&.edited!
+        log_llm_context(outcome, llm_context, moment) unless warmup
+      end
+      outcome
+    end
+
+    def log_llm_context(outcome, llm_context, moment)
+      Log.info(:model, "llm_context_apply", rule: llm_context.apply, at: moment, why: outcome.why,
+                                            applied: outcome.applied.size, ids: outcome.applied.map(&:id).join(","),
+                                            staged: outcome.staged, freed: (outcome.freed_chars / TokenUsage::CHARS_PER_TOKEN).ceil,
+                                            tail: (outcome.tail_chars / TokenUsage::CHARS_PER_TOKEN).ceil,
+                                            model: @turn_settings&.model_name)
+    end
+    private :log_llm_context
+
+    # A request's re-prefilled tokens, for both loops: of the prompt the
+    # last request on +model+ sent (this kernel's, any turn), what the
+    # server didn't reuse from its cache this time (that prompt less
+    # +cached+), so an LLM context edit's cache break shows, and so does
+    # anything else that rewrote the prompt's middle or lost the cache. nil
+    # under TokenUsage::REPREFILL_MIN_TOKENS (a cache block's rounding), for
+    # a server that reports no cached count (or 0: a cold cache isn't told
+    # from no cache), the first request, a model switch, and the first
+    # request after a warm-up (#warmed_up!).
+    # @return [Integer, nil]
+    def reprefilled_tokens(model, prompt:, cached:)
+      previous = @reprefill_baseline
+      @reprefill_baseline = { model: model, prompt: prompt.to_i } if prompt.to_i.positive?
+      return nil unless previous && previous[:model] == model && cached.to_i.positive?
+
+      tokens = previous[:prompt] - cached.to_i
+      tokens >= TokenUsage::REPREFILL_MIN_TOKENS ? tokens : nil
+    end
+
+    # The Engine started a turn-end warm-up: it prefills the next prompt
+    # off the clock, so the next request's cache counts are against it, not
+    # the last request (#reprefilled_tokens starts over).
+    def warmed_up!
+      @reprefill_baseline = nil
+    end
+
     # Public wrapper so other loops (e.g. the chat loop) can strip
     # per-profile thought blocks from finished model text without duplicating the
     # Gemma 4 / Qwen 3.6 logic. Mirrors the native loop's "strip before deciding
@@ -809,9 +937,9 @@ module Samagotchi
     private
 
     def dispatch(call)
-      entry = @tools[call[:name]]
+      entry = @tools.offered(call[:name], layers: llm_context_layers)
       unless entry
-        available = @tools.names.join(", ")
+        available = @tools.names(layers: llm_context_layers).join(", ")
         result = "Error: unknown tool '#{call[:name]}'. Available: #{available}"
         return {
           output: result,

data/lib/samagotchi/llm/chat_loop.rb

@@ -16,6 +16,7 @@ require_relative "../context_window"
 require_relative "../context_note"
 require_relative "../tool_runner"
 require_relative "../tool_response"
+require_relative "../tool_ids"
 require_relative "../tool_declarations"
 require_relative "../vision_context"
 require_relative "../log"
@@ -74,10 +75,11 @@ module Samagotchi
       end
 
       # Tool definitions for the request: the schemas the native prompts are
-      # rendered from (the kernel's registry), with the chat-only enums and
-      # closed parameters.
+      # rendered from (the kernel's registry, the tools the turn's LLM
+      # context layers offer), with the chat-only enums and closed
+      # parameters.
       def tool_definitions
-        ToolDeclarations.chat_schemas(tools.schemas).map do |schema|
+        ToolDeclarations.chat_schemas(tools.schemas(layers: llm_context_layers)).map do |schema|
           { type: "function", function: schema.slice(:name, :description, :parameters) }
         end
       end
@@ -85,6 +87,28 @@ module Samagotchi
       # The kernel's tools.
       def tools = @kernel.tools
 
+      # The turn's LLM context layers (KernelLoop#llm_context_layers).
+      def llm_context_layers = @kernel.llm_context_layers
+
+      # The turn's LLM context strategy (LLMContextStrategy::Resolved), nil
+      # when none was resolved.
+      def llm_context = @kernel.turn_settings&.llm_context
+
+      # KernelLoop#reprefilled_tokens, the kernel's request history.
+      def reprefilled_tokens(model, **) = @kernel.reprefilled_tokens(model, **)
+
+      # The kernel's LLMContextView, the turn's strategy.
+      def llm_context_view = @kernel.llm_context_view
+
+      # The strategy's own edits before a request and at turn end
+      # (KernelLoop#apply_llm_context!).
+      def apply_llm_context!(conversation, **) = @kernel.apply_llm_context!(conversation, **)
+
+      # The running turn, for forget_outputs (KernelLoop#llm_context_turn).
+      def llm_context_turn=(turn)
+        @kernel.llm_context_turn = turn
+      end
+
       # engine-format conversation -> OpenAI wire messages. Model turns are
       # thought-stripped and carry their tool_calls; tool responses go as tool
       # messages with their tool_call_id; user content goes as parts (a String
@@ -100,7 +124,11 @@ module Samagotchi
       # message takes text only, so a run of tool results' images follows it
       # as one user message "[images from tool results]". Images the request
       # leaves out (ImagePlan) become placeholder lines in the text.
+      #
+      # The conversation goes through the kernel's LLMContextView first,
+      # as the native prompt does.
       def wire_messages(conversation)
+        conversation = llm_context_view.messages(conversation)
         paired = paired_call_ids(conversation)
         plan = ImagePlan.new(conversation, vision)
         tool_images = []
@@ -329,7 +357,8 @@ module Samagotchi
           # The empty generations, never saved: the UIs draw the turn's
           # steps from them (ModelResult#empty_steps).
           @empty_steps = []
-          @context = ContextStatus.new(conversation: conversation)
+          @context = ContextStatus.new(conversation: conversation, llm_context: loop.llm_context)
+          loop.llm_context_turn = LLMContextForget::Turn.new(conversation: conversation, context: @context)
         end
 
         def call(max_iterations:, cap:)
@@ -424,6 +453,9 @@ module Samagotchi
         # One streamed request. Returns [response, nil], or [reason, partial
         # text] when it was cancelled.
         def generate(iteration)
+          # The strategy's edits the apply rule lets through first (stale):
+          # this request sends them.
+          @loop.apply_llm_context!(@conversation, context: @context)
           window = @window = @loop.context_window(@model_name)
           observe_context(iteration, window)
           retry_generation = @empty_retry.take_sampling!
@@ -452,7 +484,7 @@ module Samagotchi
           emit(type: :generation_completed, iteration: iteration, content_length: response.text.length,
                thinking_chars: response.reasoning.to_s.length, served_model: response.model,
                served_provider: response.provider, requested_model: @model_name, finish_reason: response.finish_reason,
-               **(response.usage&.cache_fields || {}))
+               **(response.usage&.cache_fields || {}), **reprefill_field(response.usage))
           dump_response(response, iteration)
           @loop.fire_hook(:after_generation, { type: :after_generation, iteration: iteration, response: response.text,
                                                messages: AnswerDisplay.strip_all(@conversation).map(&:dup).freeze })
@@ -461,6 +493,14 @@ module Samagotchi
           [e.reason, streamed, thought]
         end
 
+        # The request's re-prefilled tokens (KernelLoop#reprefilled_tokens).
+        def reprefill_field(usage)
+          return {} unless usage&.source == :server
+
+          tokens = @loop.reprefilled_tokens(@model_name, prompt: usage.prompt_tokens, cached: usage.cached_tokens)
+          tokens ? { reprefill_tokens: tokens } : {}
+        end
+
         # The request runs under the generation's own controller (the turn
         # controller's child), so a plugin's stop_generation cuts it alone.
         def with_generation(&)
@@ -525,18 +565,12 @@ module Samagotchi
           @request_chars = prompt_chars
         end
 
-        # The conversation's text as the request carries it: contents (a
-        # parts list's text parts) and the tool calls' names and arguments.
+        # The conversation's text as the request carries it, through the
+        # kernel's LLMContextView (a stub counts, not the output it stands
+        # for): contents (a parts list's text parts) and the tool calls'
+        # names and arguments.
         def prompt_chars
-          @conversation.sum do |entry|
-            content = entry[:content]
-            chars = if content.is_a?(Array)
-                      content.sum { |part| part.is_a?(Hash) ? (part[:text] || part["text"]).to_s.length : 0 }
-                    else
-                      content.to_s.length
-                    end
-            chars + Array(entry[:tool_calls]).sum { |call| call[:name].to_s.length + call[:arguments].to_json.length }
-          end
+          LLMContextView.chars(@loop.llm_context_view.messages(@conversation))
         end
 
         # The server's counts for this request (prompt + answer): the status
@@ -565,12 +599,14 @@ module Samagotchi
         end
 
         # Each call's result goes on the conversation as it finishes, paired
-        # with its call (ToolResponse.single: the capped output).
+        # with its call (ToolResponse.single: the capped output), with the
+        # next id (ToolIds).
         def dispatch(tool_calls, iteration, cap)
           calls = tool_calls.map { |tool_call| NativeToolNormalizer.normalize(tool_call) }
           runs = ToolResponse.run_batch(@loop.tool_runner, calls, iteration: iteration, emit: method(:emit),
                                                                   on_stream_event: @on_stream_event, cap: cap) do |run, index|
-            @conversation << ToolResponse.single(run, tool_call_id: tool_calls[index].id)
+            @conversation << ToolResponse.single(run, tool_call_id: tool_calls[index].id,
+                                                      ids: ToolIds.next_ids(@conversation, 1))
           end
           @tool_activity.concat(ToolResponse.activities(runs))
         end
@@ -602,6 +638,9 @@ module Samagotchi
         end
 
         def result(text, exhausted:)
+          # The model answered: the staged edits reach the session now (a
+          # turn that ran out of steps is mid-task; they wait).
+          @loop.apply_llm_context!(@conversation, moment: :turn_end) unless exhausted
           ModelResult.new(text: text, conversation: @loop.plain(@conversation), exhausted: exhausted,
                           tool_activity: @tool_activity, empty_steps: @empty_steps, empty_retries: @empty_retry.attempts,
                           context_status: @context.display)

data/lib/samagotchi/llm/turn_settings.rb

@@ -10,12 +10,13 @@ module Samagotchi
     # (SamplingSettings.for; empty sends none), its thinking level
     # (Thinking.resolve), the bare model id the turn runs on (every debug
     # dump is tagged with it) and the model's or host's configured context
-    # window (ContextWindow.setting, nil for none). The Engine sets them
-    # once per turn, in Engine#generate, after the model's host is synced.
-    TurnSettings = Data.define(:vision, :sampling, :thinking, :model_name, :window_setting) do
+    # window (ContextWindow.setting, nil for none) and LLM context strategy
+    # (LLMContextStrategy.resolve, nil for none). The Engine sets them once
+    # per turn, in Engine#generate, after the model's host is synced.
+    TurnSettings = Data.define(:vision, :sampling, :thinking, :model_name, :window_setting, :llm_context) do
       # No vision, no sampling, the default thinking, no model name.
       def self.none = new(vision: nil, sampling: {}.freeze, thinking: Thinking::DEFAULT, model_name: nil,
-                          window_setting: nil)
+                          window_setting: nil, llm_context: nil)
     end
   end
 end

data/lib/samagotchi/llm_context_apply.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "llm_context_edit"
+require_relative "llm_context_stale"
+require_relative "llm_context_view"
+
+module Samagotchi
+  # When a layer's edits reach the prompt: the apply rule
+  # (llm_context.apply, LLMContextStrategy). Every edit breaks the prompt
+  # cache from the earliest entry it changes, so the edits due at one point
+  # go in one batch, under one cache break.
+  #
+  # Two points ask (#run!): each request of both loops (+moment+ :request,
+  # the warm-up too, as the next turn's first request) and the end of a
+  # turn the model answered (+moment+ :turn_end). What waits between them is
+  # staged: for the stale layer it is worked out again at each point from
+  # the conversation itself (LLMContextStale.found with changes), so
+  # nothing is kept for it and a --resume stages the same; an edit saved
+  # with no applied_at (a later layer's, forget) is staged too. Only an
+  # applied edit is saved (LLMContextEdit.store), and it stays.
+  #
+  # The rules, at a request:
+  # - next_request: a read a later read superseded is applied at once (P2's
+  #   behaviour); one only an edit or write superseded waits for turn end.
+  # - turn_end: nothing; all of it at turn end. Where a warm-up follows
+  #   (the native loop on a local llama.cpp) it warms the edited prompt;
+  #   elsewhere the break moves to the next turn's first request.
+  # - payoff: the whole batch is applied when the tokens it frees are at
+  #   least the tail it makes the server read again (from the earliest
+  #   edited entry to the end, as sent after it), or the context is in the
+  #   top ContextStatus bucket; otherwise it waits for turn end.
+  # At turn end every staged edit is applied, under each rule.
+  #
+  # Never applied, at any point: a stale stub of a read of a file the
+  # last +protect_steps+ steps edited (LLMContextStale.protected_ids); a
+  # forget was checked against them when the model made it.
+  module LLMContextApply
+    RULES = %i[payoff next_request turn_end].freeze
+    MOMENTS = %i[request turn_end].freeze
+
+    # One staged edit: the entry it goes on, the edit (applied_at nil) and
+    # whether only a change superseded its read (never sent mid-edit).
+    Staged = Data.define(:index, :edit, :change) do
+      def change? = change
+    end
+
+    # What a point did: the edits it applied (saved on the entries), how
+    # many stay staged, and for the batch it weighed (the applied one, or
+    # under payoff the one it held back) the chars it frees and the tail
+    # it makes the server read again; +why+: :next_request, :turn_end,
+    # :payoff or :top_bucket when it applied, :held when payoff held a
+    # batch back, nil when there was nothing to weigh.
+    Outcome = Data.define(:applied, :staged, :freed_chars, :tail_chars, :why) do
+      def self.none = new(applied: [], staged: 0, freed_chars: 0, tail_chars: 0, why: nil)
+
+      def applied? = !applied.empty?
+    end
+
+    module_function
+
+    # Stages what +layers+ find on +conversation+ and applies what +rule+
+    # lets through at +moment+.
+    # @param top_bucket [Boolean] the context is in the top ContextStatus bucket
+    # @param changes [Boolean] an edit or write makes a read stale too
+    #   (llm_context.stale_edits; off: later reads only, P2's rule)
+    # @return [Outcome]
+    def run!(conversation, layers:, rule:, moment:, protect_steps:, top_bucket: false, root: Dir.pwd,
+             now: Time.now.utc.iso8601(3), changes: false)
+      layers = Array(layers)
+      return Outcome.none if layers.empty?
+
+      staged = stage(conversation, layers, protect_steps, root, now, changes)
+      return Outcome.none if staged.empty?
+
+      batch, why, measured = choose(conversation, layers, staged, rule, moment, top_bucket)
+      freed, tail = measured || measure(conversation, layers, batch, now)
+      applied = batch.map do |item|
+        edit = item.edit.with(applied_at: now)
+        LLMContextEdit.store(conversation[item.index], edit)
+        edit
+      end
+      Outcome.new(applied: applied, staged: staged.size - batch.size, freed_chars: freed, tail_chars: tail, why: why)
+    end
+
+    # The edits waiting to reach the prompt.
+    # @return [Array<Staged>]
+    def stage(conversation, layers, protect_steps, root, now, changes)
+      staged = []
+      kept = LLMContextStale.protected_ids(conversation, steps: protect_steps, root: root)
+      if layers.include?(:stale)
+        LLMContextStale.found(conversation, root: root, changes: changes).each do |stale|
+          edit = LLMContextEdit.new(id: stale.run.ref.id, kind: :stale, note: stale.note, by: LLMContextStale::BY,
+                                    staged_at: now, applied_at: nil)
+          staged << Staged.new(index: stale.run.index, edit: edit, change: stale.change?)
+        end
+      end
+      # A forget passed its own check when the model made it
+      # (LLMContextForget: a read the model edits against goes only with
+      # lines kept); the rule holds back only stale's.
+      staged.concat(saved_staged(conversation, layers))
+            .reject { |item| item.edit.kind == :stale && kept.include?(item.edit.id) }
+    end
+
+    # [the batch to apply, why, its [freed, tail] when payoff measured it]
+    # at +moment+ under +rule+.
+    def choose(conversation, layers, staged, rule, moment, top_bucket)
+      return [staged, :turn_end] if moment == :turn_end
+
+      case rule
+      when :next_request
+        batch = staged.reject(&:change?)
+        [batch, batch.empty? ? nil : :next_request]
+      when :payoff
+        return [staged, :top_bucket] if top_bucket
+
+        measured = measure(conversation, layers, staged)
+        freed, tail = measured
+        freed >= tail ? [staged, :payoff, measured] : [[], :held, measured]
+      else
+        [[], nil]
+      end
+    end
+
+    # The chars +batch+ frees from what +conversation+ sends now, and the
+    # chars sent after it from its earliest entry on (the tail the server
+    # reads again).
+    # @return [Array(Integer, Integer)]
+    def measure(conversation, layers, batch, now = "now")
+      return [0, 0] if batch.empty?
+
+      view = LLMContextView.new(strategy: layers)
+      trial = conversation.dup
+      batch.each do |item|
+        trial[item.index] = trial[item.index].dup if trial[item.index].equal?(conversation[item.index])
+        LLMContextEdit.store(trial[item.index], item.edit.with(applied_at: now))
+      end
+      after = view.messages(trial)
+      first = batch.map(&:index).min
+      [sent_chars(view.messages(conversation)) - sent_chars(after), sent_chars(after[first..])]
+    end
+
+    def sent_chars(entries) = LLMContextView.chars(entries)
+
+    # What applying +edits+ ([entry index, LLMContextEdit] pairs) would
+    # free under +layers+, and the tail after them, in chars (#measure).
+    # @return [Array(Integer, Integer)]
+    def weigh(conversation, layers:, edits:)
+      measure(conversation, Array(layers), edits.map { |index, edit| Staged.new(index: index, edit: edit, change: false) })
+    end
+
+    # Edits saved unapplied on the entries, of +layers+ (forget saves its
+    # edits so, LLMContextForget).
+    def saved_staged(conversation, layers)
+      conversation.each_with_index.flat_map do |entry, index|
+        next [] unless entry[:role].to_s == "tool_response"
+
+        LLMContextEdit.on(entry).values.reject(&:applied?).select { |edit| layers.include?(edit.kind) }
+                      .map { |edit| Staged.new(index: index, edit: edit, change: false) }
+      end
+    end
+
+    private_class_method :stage, :choose, :measure, :saved_staged
+  end
+end