samagotchi 0.155.0 → 0.157.0

data/lib/samagotchi/llm_context_strategy.rb

@@ -35,11 +35,9 @@ module Samagotchi
     LAYERS = %i[stale forget].freeze
     # The layers a turn can run under so far.
     BUILT = %i[stale forget].freeze
-    # The sentence forget_outputs' description carries (global only):
-    # the plan's D7 line, adapted from CLM's steering example.
+    # The sentence forget_outputs' description carries (global only; its
+    # default is Config::DEFAULT_LLM_CONTEXT_POLICY).
     POLICY_SETTING = "llm_context.policy"
-    DEFAULT_POLICY = "Tidy at subtask boundaries: once a subtask is done, forget its tool outputs and note what it " \
-                     "established; keep anything you'll still edit against."
 
     APPLY_SETTING = "llm_context.apply"
     APPLY_KEY = "llm_context_apply"
@@ -150,10 +148,10 @@ module Samagotchi
     end
 
     # Where one value came from: :session, :model_setting, :host_setting
-    # or :config, and the place as a warning names it ("the session",
-    # "models: deepseek", "hosts entry 'box'", "llm_context.apply").
+    # or :config, and the place, named as the other settings name theirs
+    # ("session", "models: deepseek", "hosts.box", "llm_context.apply").
     Origin = Data.define(:source, :where)
-    SESSION_ORIGIN = Origin.new(source: :session, where: "the session")
+    SESSION_ORIGIN = Origin.new(source: :session, where: "session")
 
     # What a turn's strategy, apply rule and budget are, each with its
     # Origin (/llm-context, /stats, the web's info bar).
@@ -171,26 +169,22 @@ module Samagotchi
       end
     end
 
-    # The strategy for +target+'s turn.
-    # @param target [HostRegistry::ModelTarget, nil]
-    # @param names [Array<String>] HostRegistry#lookup_names
-    # @param models [Hash{String => ModelSettings}, nil] ConfigFile.model_settings (specs)
+    # The strategy for +lookup+'s model's turn.
+    # @param lookup [ModelLookup] the model's layers (EffectiveModel#lookup)
     # @param session [Array<Symbol>, nil] the session's own layers ([]: none)
     # @param session_apply [Symbol, nil] the session's own apply rule
     # @param session_budget [Integer, nil] the session's own budget (0: off)
     # @return [Resolved]
-    def resolve(target, names:, models: nil, session: nil, session_apply: nil, session_budget: nil)
-      explain(target, names: names, models: models, session: session, session_apply: session_apply,
-                      session_budget: session_budget).resolved
+    def resolve(lookup, session: nil, session_apply: nil, session_budget: nil)
+      explain(lookup, session: session, session_apply: session_apply, session_budget: session_budget).resolved
     end
 
     # #resolve, with where each value came from.
     # @return [Explained]
-    def explain(target, names:, models: nil, session: nil, session_apply: nil, session_budget: nil)
-      models ||= ConfigFile.model_settings
-      layers, source, where = layers_for(target, names, models, session)
-      apply, apply_origin = apply_for(target, names, models, session_apply)
-      budget, budget_origin = budget_for(target, names, models, session_budget)
+    def explain(lookup, session: nil, session_apply: nil, session_budget: nil)
+      layers, source, where = layers_for(lookup, session)
+      apply, apply_origin = apply_for(lookup, session_apply)
+      budget, budget_origin = budget_for(lookup, session_budget)
       resolved = resolved(layers, source, where).with(apply: apply, protect_steps: protect_steps,
                                                       stale_edits: Config.get(STALE_EDITS_SETTING) == true,
                                                       budget_tokens: budget)
@@ -198,79 +192,47 @@ module Samagotchi
                     budget_tokens: budget_origin)
     end
 
-    # A session's LLM context strategy, apply rule and budget, each with
-    # where it came from (Explained#summary), as its worker would resolve
-    # them; nil when they can't be (an unreadable config, a model that
-    # resolves nowhere). Resolves from config and the registry only: no
-    # network, no model call. What a session page, a session list's ctx %
-    # and a spawn-time check all read.
-    # @param session [Session, nil]
-    # @param registry [HostRegistry, nil] the hosts to resolve against;
-    #   HostRegistry.new by default (what the caller usually has)
-    # @return [Hash, nil] Explained#summary, symbol keys
-    def for_session(session, registry: nil)
-      return nil if session.nil?
-
-      # Here, not at the top: config.rb requires this file before ConfigFile
-      # exists, and effective_model.rb requires config.rb (via host_registry.rb).
-      require_relative "effective_model"
-      registry ||= HostRegistry.new
-      own = session.llm_context
-      EffectiveModel.of_session(session, registry: registry).llm_context_explained(own&.resolve_args || {})&.summary(own)
-    rescue StandardError
-      nil
-    end
-
-    # The budget a session's turns run under (for_session's :budget_tokens),
-    # nil when it is off or can't be resolved. What a session list's ctx %
-    # counts against, so a saved session's fill reads as the live meter.
-    # @param session [Session, nil]
-    # @param registry [HostRegistry, nil] see .for_session
-    # @return [Integer, nil]
-    def session_budget(session, registry: nil)
-      for_session(session, registry: registry)&.fetch(:budget_tokens, nil)
-    end
-
     # [the budget, its Origin]: the session's own first (0 there is off,
     # whatever the model says).
-    def budget_for(target, names, models, session_budget)
+    def budget_for(lookup, session_budget)
       return [session_budget.positive? ? session_budget : nil, SESSION_ORIGIN] unless session_budget.nil?
 
-      if (setting = ConfigFile.model_setting(names, :llm_context_budget_tokens, models: models))
+      if (setting = lookup.model(:llm_context_budget_tokens))
         return [setting.value, Origin.new(source: :model_setting, where: "models: #{setting.key}")]
       end
 
-      budget = target&.entry&.llm_context_budget_tokens
-      return [budget, Origin.new(source: :host_setting, where: "hosts entry '#{target.entry.name}'")] if budget
+      budget = lookup.host(:llm_context_budget_tokens)
+      return [budget, Origin.new(source: :host_setting, where: "hosts.#{lookup.host_name}")] if budget
 
-      [parse_budget(Config.get(BUDGET_SETTING), BUDGET_SETTING), Origin.new(source: :config, where: BUDGET_SETTING)]
+      [parse_budget(lookup.global(BUDGET_SETTING).first, BUDGET_SETTING), Origin.new(source: :config, where: BUDGET_SETTING)]
     end
 
-    def layers_for(target, names, models, session)
+    def layers_for(lookup, session)
       return [session, :session, SESSION_ORIGIN.where] if session
 
-      if (setting = ConfigFile.model_setting(names, :llm_context_strategy, models: models))
+      if (setting = lookup.model(:llm_context_strategy))
         return [setting.value, :model_setting, "models: #{setting.key}"]
       end
 
-      layers = target&.entry&.llm_context_strategy
-      return [layers, :host_setting, "hosts entry '#{target.entry.name}'"] if layers
+      layers = lookup.host(:llm_context_strategy)
+      return [layers, :host_setting, "hosts.#{lookup.host_name}"] if layers
 
-      [parse(Config.get(SETTING), SETTING) || [], :config, SETTING]
+      [parse(lookup.global(SETTING).first, SETTING) || [], :config, SETTING]
     end
 
     # [the apply rule, its Origin].
-    def apply_for(target, names, models, session_apply)
+    def apply_for(lookup, session_apply)
       return [session_apply, SESSION_ORIGIN] if session_apply
 
-      if (setting = ConfigFile.model_setting(names, :llm_context_apply, models: models))
+      if (setting = lookup.model(:llm_context_apply))
         return [setting.value, Origin.new(source: :model_setting, where: "models: #{setting.key}")]
       end
 
-      apply = target&.entry&.llm_context_apply
-      return [apply, Origin.new(source: :host_setting, where: "hosts entry '#{target.entry.name}'")] if apply
+      apply = lookup.host(:llm_context_apply)
+      return [apply, Origin.new(source: :host_setting, where: "hosts.#{lookup.host_name}")] if apply
 
-      [parse_apply(Config.get(APPLY_SETTING), APPLY_SETTING) || DEFAULT_APPLY, Origin.new(source: :config, where: APPLY_SETTING)]
+      [parse_apply(lookup.global(APPLY_SETTING).first, APPLY_SETTING) || DEFAULT_APPLY,
+       Origin.new(source: :config, where: APPLY_SETTING)]
     end
 
     # llm_context.protect_steps: 0 or more (a negative one is the default).

data/lib/samagotchi/llm_context_view.rb

@@ -73,6 +73,15 @@ module Samagotchi
       end
     end
 
+    # The view under +llm_context+'s strategy (LLMContextStrategy::Resolved,
+    # a turn's TurnSettings#llm_context), none without one: what both loops
+    # format the conversation through, so the warm-up warms the prompt the
+    # next turn sends.
+    # @return [LLMContextView]
+    def self.for(llm_context)
+      new(strategy: llm_context&.strategy || NONE)
+    end
+
     # @param strategy [Symbol, Array<Symbol>] :none, or the layers
     def initialize(strategy: NONE)
       @layers = strategy == NONE ? [] : Array(strategy).map(&:to_sym) & LAYERS

data/lib/samagotchi/memory_bundle/asset_installer.rb

@@ -75,6 +75,20 @@ module Samagotchi
                       plugin_file: plugin_file, script_files: script_files)
       end
 
+      # Whether the bundle file +src+ reads through a symlink: it is one, or
+      # it (or its dir, hooks/ say) resolves outside +bundle_dir+. A tar,
+      # zip or git repo keeps links; copying through one would install any
+      # file the user can read. MemoryFiles skips linked memories the same
+      # way. ShippedUpdate's plan reads it too.
+      def self.linked?(src, bundle_dir)
+        return true if File.symlink?(src)
+
+        root = File.realpath(bundle_dir)
+        !File.realpath(src).start_with?("#{root}/")
+      rescue SystemCallError
+        true
+      end
+
       private
 
       # Copies the bundle's hooks/*.rb into <bundle_dir>/hooks/: the ones
@@ -107,10 +121,8 @@ module Samagotchi
       # One listed hook; an upgrade overwrites a local edit with a warning.
       def install_hook(basename, src)
         dest = File.join(@provenance.hooks_dir, basename)
-        if @dry_run
-          @results[basename] = { status: File.exist?(dest) && !@force ? "would_skip" : "would_install" }
-          return
-        end
+        result = result_for(src, dest, updated: @upgrade && @existing)
+        return @results[basename] = planned(result) if @dry_run
 
         prev_sha = @existing&.hooks&.dig(basename)&.sha256
         if @upgrade && File.exist?(dest) && !@force && !Provenance.recorded_sha(prev_sha).empty? && !Provenance.sha_matches?(dest, prev_sha)
@@ -118,16 +130,9 @@ module Samagotchi
         end
 
         FileUtils.mkdir_p(@provenance.hooks_dir)
-        unchanged = File.exist?(dest) && FileUtils.identical?(src, dest)
         @trash.copy_edit(dest, as: "hooks/#{basename}", recorded: prev_sha, incoming: src)
         place(src, dest)
-        @results[basename] = if unchanged
-                               { status: "skipped", reason: "already up to date" }
-                             elsif @upgrade && @existing
-                               { status: "updated" }
-                             else
-                               { status: "installed" }
-                             end
+        @results[basename] = result
         @hook_files[basename] = dest
       end
 
@@ -139,13 +144,13 @@ module Samagotchi
 
           @bundle_hooks << basename
           if @dry_run
-            @results[basename] = { status: "would_install" }
+            @results[basename] = Installer::FileResult.new(word: :would_install)
           else
             FileUtils.mkdir_p(@provenance.hooks_dir)
             dest = File.join(@provenance.hooks_dir, basename)
             @trash.copy_edit(dest, as: "hooks/#{basename}", recorded: @existing&.hooks&.dig(basename)&.sha256, incoming: src)
             place(src, dest)
-            @results[basename] = { status: "installed" }
+            @results[basename] = Installer::FileResult.new(word: :installed)
             @hook_files[basename] = dest
           end
         end
@@ -166,22 +171,17 @@ module Samagotchi
         end
       end
 
-      # Strict mode: an installed hook whose sha256 differs from the one its
-      # manifest declares warns (as verify_memory_checksums does).
+      # Strict mode: a hook whose sha256 differs from the one its manifest
+      # declares warns (as verify_memory_checksums does). The bundle's file is
+      # checked, the one the install copies, so a dry run checks what it
+      # would install, not the old hook in place.
       def verify_hook_checksums
         @bundle_hooks.each do |basename|
           next if @conflicts.key?(basename)
 
-          expected = @manifest.checksum_for_hook(basename)
-          next unless expected
-
-          dest = File.join(@provenance.hooks_dir, basename)
-          next unless File.exist?(dest)
-
-          actual = FileDigest.hex(dest)
-          if actual != expected
-            @warnings << "Checksum mismatch for hook #{basename}: expected #{expected[0..7]}..., got #{actual[0..7]}..."
-          end
+          warning = FileDigest.mismatch("hook #{basename}", File.join(@bundle_dir, "hooks", basename),
+                                        @manifest.checksum_for_hook(basename))
+          @warnings << warning if warning
         end
       end
 
@@ -190,16 +190,13 @@ module Samagotchi
       # installed are reported up to date, not "Installed".
       # @return [Hash{String => String}] basename => installed path ({} on a dry run)
       def install_guardrails(incoming_rules)
+        target = @provenance.guardrails_dir
+        results = incoming_rules.to_h { |src| [src, result_for(src, File.join(target, File.basename(src)), updated: false)] }
         if @dry_run
-          incoming_rules.each { |src| @results["guardrails/#{File.basename(src)}"] = { status: "would_install" } }
+          results.each { |src, result| @results["guardrails/#{File.basename(src)}"] = planned(result) }
           return {}
         end
 
-        target = @provenance.guardrails_dir
-        unchanged = incoming_rules.select do |src|
-          dest = File.join(target, File.basename(src))
-          File.file?(dest) && FileUtils.identical?(src, dest)
-        end
         @trash.copy_edits(target, "guardrails", @existing&.guardrails, incoming_rules.to_h { |src| [File.basename(src), src] })
         FileUtils.rm_rf(target)
         return {} if incoming_rules.empty?
@@ -208,8 +205,7 @@ module Samagotchi
         incoming_rules.to_h do |src|
           dest = File.join(target, File.basename(src))
           place(src, dest)
-          @results["guardrails/#{File.basename(src)}"] =
-            unchanged.include?(src) ? { status: "skipped", reason: "already up to date" } : { status: "installed" }
+          @results["guardrails/#{File.basename(src)}"] = results[src]
           [File.basename(src), dest]
         end
       end
@@ -235,29 +231,20 @@ module Samagotchi
         if (failure = Manifest.requires_chi_failure(@manifest.requires_chi, @chi_version))
           @warnings << "Plugin #{plugin[:file]} won't load: #{failure}"
         end
+        dest = File.join(@provenance.plugin_dir, plugin[:file])
+        result = result_for(src, dest, updated: @upgrade && @provenance.installed?)
         if @dry_run
-          @results[plugin[:file]] = { status: "would_install" }
+          @results[plugin[:file]] = planned(result)
           return nil
         end
 
-        dest = File.join(@provenance.plugin_dir, plugin[:file])
-        unchanged = File.file?(dest) && FileUtils.identical?(src, dest)
         @trash.copy_edits(@provenance.plugin_dir, "plugin", @existing&.plugin_shas, { plugin[:file] => src })
         FileUtils.rm_rf(@provenance.plugin_dir)
         FileUtils.mkdir_p(@provenance.plugin_dir)
         place(src, dest)
-        @results[plugin[:file]] = if unchanged
-                                    { status: "skipped", reason: "already up to date" }
-                                  elsif @upgrade && @provenance.installed?
-                                    { status: "updated" }
-                                  else
-                                    { status: "installed" }
-                                  end
-        expected = @manifest.checksum_for_plugin
-        actual = FileDigest.hex(dest)
-        if @strict && !@dev && expected && actual != expected
-          @warnings << "Checksum mismatch for plugin #{plugin[:file]}: expected #{expected[0..7]}..., got #{actual[0..7]}..."
-        end
+        @results[plugin[:file]] = result
+        warning = FileDigest.mismatch("plugin #{plugin[:file]}", dest, @manifest.checksum_for_plugin) if @strict && !@dev
+        @warnings << warning if warning
         dest
       end
 
@@ -274,12 +261,15 @@ module Samagotchi
 
           @warnings << "scripts/#{file} is not executable; chmod +x #{src}" if @dev && !File.executable?(src) && !page_only?(file)
         end
-        return {} if @dry_run
-
-        unchanged = scripts.keys.select do |file|
-          dest = File.join(@provenance.scripts_dir, file)
-          File.file?(dest) && FileUtils.identical?(File.join(@bundle_dir, "scripts", file), dest)
+        results = scripts.keys.to_h do |file|
+          [file, result_for(File.join(@bundle_dir, "scripts", file), File.join(@provenance.scripts_dir, file),
+                            updated: @upgrade && @provenance.installed?)]
+        end
+        if @dry_run
+          results.each { |file, result| @results["scripts/#{file}"] = planned(result) }
+          return {}
         end
+
         @trash.copy_edits(@provenance.scripts_dir, "scripts", @existing&.scripts,
                           scripts.keys.to_h { |file| [file, File.join(@bundle_dir, "scripts", file)] })
         FileUtils.rm_rf(@provenance.scripts_dir)
@@ -289,20 +279,36 @@ module Samagotchi
         scripts.to_h do |file, declared|
           dest = File.join(@provenance.scripts_dir, file)
           place(File.join(@bundle_dir, "scripts", file), dest)
-          @results["scripts/#{file}"] = if unchanged.include?(file) then { status: "skipped", reason: "already up to date" }
-                                        elsif @upgrade && @provenance.installed? then { status: "updated" }
-                                        else { status: "installed" }
-                                        end
+          @results["scripts/#{file}"] = results[file]
           FileUtils.chmod(0o755, dest) unless @dev
-          actual = FileDigest.hex(dest)
-          expected = declared.to_s.delete_prefix("sha256:")
-          if @strict && !@dev && !expected.empty? && actual != expected
-            @warnings << "Checksum mismatch for script #{file}: expected #{expected[0..7]}..., got #{actual[0..7]}..."
-          end
+          warning = FileDigest.mismatch("script #{file}", dest, declared.to_s.delete_prefix("sha256:")) if @strict && !@dev
+          @warnings << warning if warning
           [file, dest]
         end
       end
 
+      # What the real run reports for +src+ over +dest+: up to date when the
+      # bytes are the same, else updated (+updated+: an upgrade over an
+      # install) or installed. A dry run records #planned of it, so the two
+      # can't drift.
+      def result_for(src, dest, updated:)
+        word = if File.file?(dest) && FileUtils.identical?(src, dest) then :up_to_date
+               elsif updated then :updated
+               else :installed
+               end
+        Installer::FileResult.new(word: word)
+      end
+
+      # A dry run's word for a result: would_install, would_update, or the
+      # up to date result as it is (nothing would be written).
+      def planned(result)
+        case result.word
+        when :installed then result.with(word: :would_install)
+        when :updated then result.with(word: :would_update)
+        else result
+        end
+      end
+
       # A file only a block renderer's load names: the page loads it, nothing runs it.
       def page_only?(file)
         @manifest.block_renderers.any? { |renderer| renderer.load.include?(file) } &&
@@ -316,19 +322,8 @@ module Samagotchi
         @dev ? File.symlink(File.realpath(src), dest) : FileUtils.cp(src, dest)
       end
 
-      # Whether the bundle file +src+ reads through a symlink: it is one, or
-      # it (or its dir, hooks/ say) resolves outside the bundle dir. A tar,
-      # zip or git repo keeps links; copying through one would install any
-      # file the user can read. MemoryFiles skips linked memories the same
-      # way.
-      def linked?(src)
-        return true if File.symlink?(src)
-
-        root = File.realpath(@bundle_dir)
-        !File.realpath(src).start_with?("#{root}/")
-      rescue SystemCallError
-        true
-      end
+      # AssetInstaller.linked? for this bundle's source.
+      def linked?(src) = self.class.linked?(src, @bundle_dir)
 
       # linked? with a "<label> is a symlink (not installed)" warning.
       def linked_out?(src, label)

data/lib/samagotchi/memory_bundle/builder.rb

@@ -227,7 +227,8 @@ module Samagotchi
           files: files_map,
           hooks: parts.hooks.empty? ? nil : parts.hooks,
           trust_level: trust_level,
-          plugin: parts.plugin && { file: File.basename(parts.plugin), sha256: FileDigest.sha256(parts.plugin) },
+          plugin: parts.plugin && { file: File.basename(parts.plugin), sha256: FileDigest.sha256(parts.plugin),
+                                    required: manifest&.plugin_required },
           requires_chi: manifest&.requires_chi,
           needs: manifest&.needs,
           scripts: parts.scripts.transform_values { |src| FileDigest.sha256(src) },

data/lib/samagotchi/memory_bundle/file_actions.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require_relative "file_state"
+
+module Samagotchi
+  module MemoryBundle
+    # What each command that acts on a bundle memory does in each FileState:
+    # one table per command, so a reader sees one command on one screen. A cell
+    # is keyed [kind, mark] or [kind, :any]; a dropped file another bundle
+    # lists too is [kind, :shared] (FileState#shared_with, asked only there).
+    # A dry run reads its command's row and doesn't execute it.
+    #
+    # A new kind or a new command adds a row in each table it reaches
+    # (docs/internals/bundles.md).
+    module FileActions
+      # do:         what happens to the file's bytes
+      #   :write_incoming  the bundle's text replaces it (or is put there)
+      #   :merge           the text merge's result replaces it (Merger::Outcome)
+      #   :decide          not a function of kind and mark: the caller asks
+      #                    Merger::Upgrade#decision, and FileActions.decided
+      #                    turns its Outcome into the action
+      #   :keep            left as it is (already the bundle's, or kept)
+      #   :skip            left as it is, the bundle doesn't take it
+      #   :move_to_trash   moved to the trash (a removal)
+      #   :refuse          the command stops
+      #   :restore         the bundle's text put back (SystemBundle at its version)
+      # save_first: a copy of the old bytes goes to the trash before a write
+      #   (when they differ from what is written)
+      # next_base:  :on_disk (the file as the command leaves it), :incoming,
+      #   :recorded (the base it has; none stays none), :none (no entry left)
+      #   -- Merger::Outcome#base's vocabulary
+      # word:       the report bucket the file is on (Installer#summary)
+      # record:     the entry afterwards: :own (rebuilt, no mark), :keep_entry
+      #   (kept with its base, no mark), :mark (marked behind), :hold_mark (as
+      #   it was, mark and all), :clear_mark, :drop, :not_owned (never recorded)
+      Action = Data.define(:do, :save_first, :next_base, :word, :record) do
+        def initialize(do:, word:, next_base: :recorded, record: :own, save_first: false) = super
+
+        # The file stays behind the bundle, marked (a conflict to the report).
+        def behind? = record == :mark
+
+        # The bundle's text goes into the file: written (installed, forced or
+        # fast-forwarded) or merged into a local edit. The source file is the
+        # download, so the manifest's sha checks it (Installer's integrity
+        # check). :restore is SystemBundle's; it checks its own copy.
+        def takes_source? = %i[write_incoming merge].include?(self.do)
+      end
+
+      WRITE = Action.new(do: :write_incoming, word: :installed, next_base: :on_disk)
+      UP_TO_DATE = Action.new(do: :keep, word: :up_to_date, next_base: :on_disk)
+      USER_SAME = Action.new(do: :keep, word: :up_to_date, next_base: :none, record: :not_owned)
+      USERS_OWN = Action.new(do: :skip, word: :kept_own, next_base: :none, record: :not_owned)
+      KEPT_OWN = Action.new(do: :skip, word: :kept_own, record: :keep_entry)
+      HELD = Action.new(do: :skip, word: :kept_own, record: :hold_mark)
+      FAST_FORWARD = Action.new(do: :write_incoming, word: :updated, next_base: :on_disk)
+      KEEP = Action.new(do: :keep, word: :kept)
+      # No base: no merge is possible, so the file stays behind, marked.
+      BEHIND = Action.new(do: :keep, word: :behind, record: :mark)
+      DECIDE = Action.new(do: :decide, word: nil)
+      REFUSE = Action.new(do: :refuse, word: nil, record: :hold_mark)
+      FORCED = Action.new(do: :write_incoming, word: :installed, next_base: :on_disk, save_first: true)
+      # The bundle dropped it: a plain install keeps it and its entry (the
+      # upgrade it points at moves it), an upgrade moves it unless edited.
+      DROPPED_KEPT = Action.new(do: :keep, word: nil, record: :keep_entry)
+      DROPPED_GONE = Action.new(do: :skip, word: nil, next_base: :none, record: :drop)
+      REMOVE = Action.new(do: :move_to_trash, word: :removed, next_base: :none, record: :drop)
+      KEPT_PRUNED = Action.new(do: :keep, word: :kept_pruned, record: :keep_entry)
+      KEPT_SHARED = Action.new(do: :keep, word: :kept_shared, next_base: :none, record: :drop)
+
+      # Rows every installing command shares: files the bundle doesn't own.
+      NOT_OWNED = {
+        %i[new any] => WRITE, %i[user_same any] => USER_SAME, %i[user_file any] => USERS_OWN,
+        %i[missing any] => WRITE, %i[level any] => UP_TO_DATE, %i[unreadable any] => REFUSE
+      }.freeze
+
+      # A plain install (a re-install over the record, or a fresh one).
+      INSTALL = NOT_OWNED.merge(
+        # A file never edited takes the source's text, as an upgrade's
+        # fast-forward does (D4); an edited one stays (an upgrade merges it).
+        %i[pristine none] => FAST_FORWARD, %i[pristine_no_base none] => FAST_FORWARD,
+        %i[edited none] => KEPT_OWN, %i[diverged none] => KEPT_OWN, %i[edited_no_base none] => KEPT_OWN,
+        # A marked file it skips has missed the bundle's change as much as before.
+        %i[pristine any] => HELD, %i[edited any] => HELD, %i[diverged any] => HELD,
+        %i[pristine_no_base any] => HELD, %i[edited_no_base any] => HELD,
+        %i[dropped_pristine any] => DROPPED_KEPT, %i[dropped_edited any] => DROPPED_KEPT,
+        %i[dropped_missing any] => DROPPED_GONE
+      ).freeze
+
+      # install --force and upgrade --force: the bundle's text everywhere, an
+      # edit copied to the trash first. Its dropped rows are upgrade --force's
+      # (a plain install --force never prunes: its dropped files are INSTALL's).
+      FORCE = NOT_OWNED.merge(
+        # A file that already has the bundle's text is written all the same
+        # (nothing to save): it is installed, and checked, as any other.
+        %i[new any] => FORCED, %i[user_same any] => FORCED, %i[user_file any] => FORCED, %i[level any] => FORCED,
+        %i[pristine any] => FORCED, %i[edited any] => FORCED, %i[diverged any] => FORCED,
+        %i[pristine_no_base any] => FORCED, %i[edited_no_base any] => FORCED,
+        %i[dropped_pristine any] => REMOVE, %i[dropped_edited any] => REMOVE, %i[dropped_missing any] => DROPPED_GONE,
+        %i[dropped_pristine shared] => KEPT_SHARED, %i[dropped_edited shared] => KEPT_SHARED
+      ).freeze
+
+      # An upgrade's 3-way view (Merger::Upgrade#outcome).
+      UPGRADE = NOT_OWNED.merge(
+        %i[pristine none] => FAST_FORWARD,
+        # A marked file that equals its base takes the update; a copy is kept.
+        %i[pristine current] => FAST_FORWARD.with(save_first: true),
+        # An older chi's mark: fast-forward unless it takes a line out and
+        # ShippedHistory can't prove the base (the legacy guard).
+        %i[pristine legacy] => DECIDE,
+        %i[edited any] => KEEP,
+        # The text merge: merged, a conflict, or already merged.
+        %i[diverged any] => DECIDE,
+        # No base: no merge. One never edited (the checksum vouches for it)
+        # takes the update as a file equal to its base would (U4); a marked
+        # one, or an edit, stays behind.
+        %i[pristine_no_base none] => FAST_FORWARD,
+        %i[pristine_no_base any] => BEHIND, %i[edited_no_base any] => BEHIND,
+        %i[dropped_pristine any] => REMOVE, %i[dropped_edited any] => KEPT_PRUNED, %i[dropped_missing any] => DROPPED_GONE,
+        %i[dropped_pristine shared] => KEPT_SHARED, %i[dropped_edited shared] => KEPT_SHARED
+      ).freeze
+
+      # Remerge: the retry of a marked file at the same version. Unmarked
+      # files are never asked. Before the table, a mark whose source moved
+      # stays behind as it is (FileState#source_moved?).
+      REMERGE = {
+        %i[level any] => Action.new(do: :keep, word: :settled, next_base: :on_disk, record: :clear_mark),
+        %i[edited any] => Action.new(do: :keep, word: :settled, record: :clear_mark),
+        %i[diverged any] => DECIDE,
+        # It matches its old base: the next upgrade takes the update.
+        %i[pristine current] => BEHIND,
+        %i[pristine legacy] => DECIDE,
+        %i[pristine_no_base any] => BEHIND, %i[edited_no_base any] => BEHIND,
+        # Not shipped now: behind, nothing to merge.
+        %i[dropped_pristine any] => BEHIND, %i[dropped_edited any] => BEHIND,
+        %i[dropped_missing any] => Action.new(do: :skip, word: nil, record: :hold_mark),
+        # The next upgrade or a restore puts it back.
+        %i[missing any] => Action.new(do: :skip, word: nil, record: :hold_mark),
+        %i[unreadable any] => Action.new(do: :keep, word: :behind, record: :hold_mark)
+      }.freeze
+
+      # SystemBundle at its version: a memory not on disk is put back, one the
+      # record doesn't own too (research Q2, today's behaviour).
+      RESTORE = {
+        %i[missing any] => Action.new(do: :restore, word: :restored, next_base: :on_disk),
+        %i[new any] => Action.new(do: :restore, word: :restored, next_base: :on_disk)
+      }.freeze
+
+      # Uninstall, on the source-less kinds: an edit refuses (Uninstaller's
+      # --force moves it instead); a file another bundle lists stays.
+      UNINSTALL = {
+        %i[pristine any] => REMOVE, %i[pristine_no_base any] => REMOVE,
+        %i[edited any] => REFUSE, %i[edited_no_base any] => REFUSE, %i[unreadable any] => REFUSE,
+        %i[missing any] => DROPPED_GONE,
+        %i[pristine shared] => KEPT_SHARED, %i[pristine_no_base shared] => KEPT_SHARED,
+        %i[edited shared] => KEPT_SHARED, %i[edited_no_base shared] => KEPT_SHARED
+      }.freeze
+
+      TABLES = { install: INSTALL, force: FORCE, upgrade: UPGRADE, remerge: REMERGE, restore: RESTORE,
+                 uninstall: UNINSTALL }.freeze
+      # The kinds whose row depends on another bundle listing the file.
+      SHARED_ASKED = %i[dropped_pristine dropped_edited pristine pristine_no_base edited edited_no_base].freeze
+
+      # The command's action for +state+: [kind, :shared] when another bundle
+      # lists a file that has such a row, else [kind, mark], then [kind, :any].
+      # @param command [Symbol] a TABLES key
+      # @return [Action, nil] nil: the command never meets the state
+      def self.for(command, state)
+        table = TABLES.fetch(command)
+        if SHARED_ASKED.include?(state.kind) && table.key?([state.kind, :shared]) && state.shared_with.any?
+          return table.fetch([state.kind, :shared])
+        end
+
+        table[[state.kind, state.mark]] || table[[state.kind, :any]]
+      end
+
+      # A :decide cell's answer: the action Merger::Upgrade#decision's Outcome
+      # stands for. Remerge never fast-forwards (the next upgrade does) and
+      # settles a file with nothing left to miss.
+      # @param outcome [Merger::Outcome]
+      # @param command [Symbol] :upgrade or :remerge
+      def self.decided(outcome, command = :upgrade)
+        case outcome.status
+        when :merged then Action.new(do: :merge, word: :merged, next_base: :incoming, save_first: true)
+        when :conflict then BEHIND
+        when :fast_forward then command == :remerge ? BEHIND : FAST_FORWARD.with(save_first: true)
+        when :keep, :noop
+          command == :remerge ? Action.new(do: :keep, word: :settled, next_base: outcome.base, record: :clear_mark) : KEEP.with(next_base: outcome.base)
+        else raise ArgumentError, "no action for outcome #{outcome.status.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/samagotchi/memory_bundle/file_digest.rb

@@ -26,6 +26,19 @@ module Samagotchi
         hex = hex(path)
         hex && "sha256:#{hex}"
       end
+
+      # The integrity check's one warning: +path+'s bytes against the sha
+      # hex a manifest declares for it. nil when they match, or when there is
+      # nothing to check (no sha declared, no file).
+      # @param label [String] what the file is ("a.md", "hook guard.rb")
+      def self.mismatch(label, path, expected)
+        return nil if expected.nil? || expected.empty?
+
+        actual = hex(path)
+        return nil if actual.nil? || actual == expected
+
+        "Checksum mismatch for #{label}: expected #{expected[0..7]}..., got #{actual[0..7]}..."
+      end
     end
   end
 end