samagotchi 0.149.0 → 0.151.0

data/lib/samagotchi/memory_bundle/merger.rb

@@ -1,32 +1,162 @@
 # frozen_string_literal: true
 
 require "digest"
+require_relative "../atomic_file"
+require_relative "installed_bundle"
 
 module Samagotchi
   module MemoryBundle
+    # Most processes that load this never merge.
+    autoload :TextMerge, File.expand_path("text_merge", __dir__)
+    autoload :ShippedHistory, File.expand_path("shipped_history", __dir__)
+
     # 3-way merge helper for bundle upgrades.
     #
     # Compare base (provenance snapshot), current (on-disk), incoming (new bundle)
     # and classify per file. Used by Installer#run when provenance exists.
     module Merger
+      # What an upgrade does to one file. status names the case; base is where
+      # the file's next base comes from:
+      #   :on_disk   the file as the install leaves it: it took the bundle's
+      #              bytes, or already had them.
+      #   :recorded  the base it has (none stays none): the file stays as the
+      #              user has it, and the next upgrade must still see the edit.
+      #   :incoming  the bundle's new file: a merged file keeps the user's
+      #              edits, so it must never become the base (the edit is what
+      #              differs from the base, and the next upgrade would
+      #              fast-forward over it).
+      # Installer#next_base reads it. A new outcome and its base go here; it
+      # also needs a branch in Installer#merge_memory (which raises without
+      # one), #next_base if its base is a new kind, and its status word in
+      # Installer#preview_memory, #verify_memory_checksums' list and #summary.
+      #
+      # merge is Upgrade#outcome's TextMerge::Result, so a merge runs git once
+      # and its answer travels with the outcome: a :merged outcome's text, a
+      # :conflict's why (nil for a real one). current_sha is the digest of the
+      # file that merge read: write_merged checks it. .classify leaves both nil.
+      Outcome = Data.define(:status, :base, :merge, :current_sha) do
+        def initialize(status:, base:, merge: nil, current_sha: nil) = super
+
+        def conflict? = status == :conflict
+
+        def merged? = status == :merged
+
+        # Why no merge was possible, nil when one wasn't tried or it found a
+        # real conflict.
+        def why = merge&.why
+      end
+
+      INSTALL = Outcome.new(status: :install, base: :on_disk)
+      FAST_FORWARD = Outcome.new(status: :fast_forward, base: :on_disk)
+      NOOP = Outcome.new(status: :noop, base: :on_disk)
+      KEEP = Outcome.new(status: :keep, base: :recorded)
+      CONFLICT = Outcome.new(status: :conflict, base: :recorded)
+      # Nothing to take: the bundle has no such file, so whatever is on disk
+      # (the user's text, perhaps) must not become the base. A noop to callers.
+      NO_INCOMING = Outcome.new(status: :noop, base: :recorded)
+      # Both changed it, and the text merge adds nothing: the user's file already
+      # has what the bundle brings. Kept, but the base moves on. (Upgrade#outcome)
+      ALREADY_MERGED = Outcome.new(status: :keep, base: :incoming)
+
+      # What an upgrade would do to the files asked about, by what callers say
+      # of them. merged: file names; behind: FileStanding::Behind.
+      Forecast = Data.define(:merged, :behind) do
+        def conflicts = behind.map(&:file)
+      end
+
+      # One bundle's upgrade as seen before it runs: what it does to a file,
+      # nothing written. The one way to ask: Installer's merge and dry run,
+      # ShippedUpdate's plan and SystemBundle's dry run. Which files to ask
+      # about is the caller's, and they differ (see #forecast).
+      Upgrade = Data.define(:provenance, :target_dir, :source_dir) do
+        # What the upgrade does to the file: .classify, then, where both sides
+        # changed it, the text merge (git runs here, once per call). A mark from
+        # an older chi fast-forwards only if no line of the file goes or its base
+        # is proved: see .merge_outcome.
+        # @return [Outcome]
+        def outcome(file_key)
+          classified = classified(file_key)
+          return classified unless classified.conflict? || classified == FAST_FORWARD
+
+          legacy = InstalledBundle.legacy_mark?(provenance.record&.files&.fetch(file_key, nil))
+          # Asked only when the guard would otherwise fire.
+          unproved = -> { legacy && !ShippedHistory.shipped?(provenance.name, file_key, paths(file_key)[:base]) }
+          return Merger.merge_outcome(paths(file_key), unproved: unproved) if classified.conflict?
+
+          # The guard's own case at its plainest: the file is the base, which
+          # may be the user's text. One that only gains lines loses nothing, and
+          # save_marked_file keeps a copy.
+          sides = paths(file_key)
+          return classified unless legacy && Merger.removes_lines?(File.binread(sides[:current]), File.binread(sides[:incoming]))
+
+          unproved.call ? CONFLICT.with(merge: TextMerge.failed(FileStanding::LEGACY_BASE)) : classified
+        end
+
+        # .classify alone: no merge is tried.
+        # @return [Outcome]
+        def classified(file_key)
+          sides = paths(file_key)
+          Merger.classify(base_path: sides[:base], current_path: sides[:current], incoming_path: sides[:incoming])
+        end
+
+        # The ones among +file_keys+ that would merge or end in a conflict. The
+        # Installer's own list is MemoryFiles.select, and a plan may ask about
+        # others: ShippedUpdate about every *.md shipped, SystemBundle about the
+        # manifest's files:. So a plan can name a file the upgrade itself
+        # doesn't merge (docs/internals/bundles.md).
+        # @param version [String, nil] the version it would bring
+        # @return [Forecast]
+        def forecast(file_keys, version: nil)
+          outcomes = file_keys.to_h { |key| [key, outcome(key)] }
+          Forecast.new(merged: outcomes.select { |_, o| o.merged? }.keys,
+                       behind: outcomes.select { |_, o| o.conflict? }.map { |key, o| behind(key, o, version) })
+        end
+
+        # A :conflict outcome as a report and the mark read it: why no merge was
+        # possible, and what the bundle changed that the file doesn't get. A base
+        # that may be the user's own text (an older mark) can't say what changed.
+        # @param version [String, nil] the version the file stays behind
+        # @return [FileStanding::Behind]
+        def behind(file_key, outcome, version)
+          why = outcome.why && FileStanding.no_merge(outcome.why)
+          base = paths(file_key)[:base]
+          if InstalledBundle.legacy_mark?(provenance.record&.files&.fetch(file_key, nil))
+            return FileStanding::Behind.new(file: file_key, version: version, why: why || FileStanding::LEGACY_CONFLICT)
+          end
+          return FileStanding::Behind.new(file: file_key, version: version, why: why) unless File.exist?(base)
+
+          sides = paths(file_key)
+          headings, unnamed = TextMerge.changed_sections(File.binread(base), File.binread(sides[:incoming]), File.binread(sides[:current]))
+          # Only the places under no heading: the others are named.
+          places = unnamed ? [outcome.merge&.hunks&.count { |hunk| !hunk.union? && hunk.heading.nil? }.to_i, 1].max : 0
+          FileStanding::Behind.new(file: file_key, version: version, why: why, missed: headings, places: places)
+        end
+
+        # @return [Hash{Symbol => String}] the file's :base, :current, :incoming
+        def paths(file_key)
+          { base: provenance.base_path(file_key), current: File.join(target_dir, file_key),
+            incoming: File.join(source_dir, file_key) }
+        end
+      end
+
       # Classify a single file for upgrade.
-      # Returns :install, :keep, :fast_forward, :conflict, :noop
+      # @return [Outcome]
       def self.classify(base_path:, current_path:, incoming_path:)
         base_exists = base_path && File.exist?(base_path)
         current_exists = File.exist?(current_path)
         incoming_exists = File.exist?(incoming_path)
 
-        return :noop unless incoming_exists
+        return NO_INCOMING unless incoming_exists
 
         unless current_exists
-          return :install
+          return INSTALL
         end
 
         # No base (legacy bundle without provenance or first file) -> treat as modified
         unless base_exists
           incoming_digest = Digest::SHA256.hexdigest(File.read(incoming_path))
           current_digest = Digest::SHA256.hexdigest(File.read(current_path))
-          return current_digest == incoming_digest ? :noop : :conflict
+          return current_digest == incoming_digest ? NOOP : CONFLICT
         end
 
         base_digest = Digest::SHA256.hexdigest(File.read(base_path))
@@ -34,14 +164,85 @@ module Samagotchi
         incoming_digest = Digest::SHA256.hexdigest(File.read(incoming_path))
 
         if current_digest == incoming_digest
-          :noop
+          NOOP
         elsif current_digest == base_digest
-          :fast_forward
+          FAST_FORWARD
         elsif incoming_digest == base_digest
-          :keep
+          KEEP
         else
-          :conflict
+          CONFLICT
+        end
+      end
+
+      # Both sides changed the file: the text merge's answer as an Outcome. No
+      # base means no merge: the file stays as a conflict.
+      #
+      # unproved: the file's mark may be 0.149's, whose base can be the user's own
+      # text. Merging against it reads the bundle's text as undoing that text,
+      # with no conflict to show for it, so a merge that would take any line out
+      # of the file stays a conflict, and so does such a fast-forward (Upgrade#outcome).
+      # A base some installed chi shipped can't be the user's text
+      # (ShippedHistory), and a mark from this chi has a real base: a merge there
+      # may take what the bundle removed. With no such gem left, a real base
+      # looks the same, and the file stays behind.
+      # @param sides [Hash{Symbol => String}] Upgrade#paths
+      # @param unproved [#call] whether the base may be the user's text; called
+      #   only when the merge would take a line out
+      # @return [Outcome]
+      def self.merge_outcome(sides, unproved: -> { false })
+        unless sides[:base] && File.exist?(sides[:base])
+          return CONFLICT.with(merge: TextMerge.failed(TextMerge::NO_BASE))
         end
+
+        ours = File.binread(sides[:current])
+        result = TextMerge.merge(base: File.binread(sides[:base]), ours: ours, theirs: File.binread(sides[:incoming]))
+        return CONFLICT.with(merge: result) unless result.clean?
+        return ALREADY_MERGED if result.text.b == ours.b
+        return CONFLICT.with(merge: TextMerge.failed(FileStanding::LEGACY_BASE)) if removes_lines?(ours, result.text) && unproved.call
+
+        Outcome.new(status: :merged, base: :incoming, merge: result, current_sha: Digest::SHA256.hexdigest(ours))
+      end
+
+      # Whether +merged+ holds fewer copies of any line of +ours+.
+      def self.removes_lines?(ours, merged)
+        kept = merged.b.each_line.map(&:chomp).tally
+        ours.b.each_line.map(&:chomp).tally.any? { |line, count| kept.fetch(line, 0) < count }
+      end
+
+      # A :merged outcome's text goes in +path+, unless the file changed since
+      # the merge read it (a live memory_write): a last check just before the
+      # rename, so that write isn't lost. Through a symlink, its mode kept, the
+      # old file copied to +trash+ first.
+      # @return [Boolean] false: the file changed, nothing was replaced
+      def self.write_merged(path, outcome, trash)
+        return false unless digest(path) == outcome.current_sha
+
+        real = File.realpath(path)
+        trash.copy(path)
+        AtomicFile.write(real, outcome.merge.text, perm: File.stat(real).mode & 0o7777) do
+          raise ChangedDuringMerge unless digest(real) == outcome.current_sha
+        end
+        true
+      rescue ChangedDuringMerge
+        false
+      end
+
+      class ChangedDuringMerge < StandardError
+      end
+      private_constant :ChangedDuringMerge
+
+      # A line a merge tool leaves around a conflict. "=======" isn't one: it
+      # is also a Markdown heading's underline.
+      CONFLICT_MARKER = /^(?:<{7}|>{7})(?: |$)/
+
+      # Whether the file holds a merge's conflict markers.
+      def self.markers?(path)
+        File.exist?(path) && File.binread(path).match?(CONFLICT_MARKER)
+      end
+
+      # The file's digest, nil when there is none.
+      def self.digest(path)
+        File.exist?(path) ? Digest::SHA256.hexdigest(File.binread(path)) : nil
       end
 
       def self.current_modified?(base_path, current_path)

data/lib/samagotchi/memory_bundle/placeholder.rb

@@ -25,7 +25,8 @@ module Samagotchi
       private
 
       def extract_placeholders(content)
-        content.scan(PLACEHOLDER_RE).flatten
+        # A memory may hold bytes that aren't UTF-8: a hint must not fail an install.
+        content.scrub.scan(PLACEHOLDER_RE).flatten
       end
     end
   end

data/lib/samagotchi/memory_bundle/profile.rb

@@ -27,8 +27,10 @@ module Samagotchi
       # installed: members installed now; already: members found installed
       # (recorded, not reinstalled); skipped and failed: name => why;
       # kept_own: member installed now => its memory files the user already
-      # had, left as they are and not owned (Installer#skip_existing).
-      InstallResult = Struct.new(:name, :version, :installed, :already, :skipped, :failed, :kept_own, keyword_init: true) do
+      # had, left as they are and not owned (Installer#skip_existing);
+      # trash_copies: "member: line" for what --force copied to the trash
+      # (Installer#trash_copy_line).
+      InstallResult = Struct.new(:name, :version, :installed, :already, :skipped, :failed, :kept_own, :trash_copies, keyword_init: true) do
         def failed? = !failed.empty?
 
         # One line per kept file (Profile.kept_own_line).
@@ -98,7 +100,7 @@ module Samagotchi
         was = recorded(bundle, manifest)
         installed = installed_names
         result = InstallResult.new(name: manifest.name, version: manifest.version, installed: [],
-                                   already: (manifest.includes - was) & installed, skipped: {}, failed: {}, kept_own: {})
+                                   already: (manifest.includes - was) & installed, skipped: {}, failed: {}, kept_own: {}, trash_copies: [])
 
         to_install(manifest, bundle, installed: installed).each do |member|
           install_member(member, shipped_dir, chi_version, dry_run, force, result)
@@ -130,6 +132,7 @@ module Samagotchi
         result.installed << member
         kept = installer.results.select { |_, entry| kept_own?(entry) }.keys
         result.kept_own[member] = kept.sort unless kept.empty?
+        result.trash_copies << "#{member}: #{installer.trash_copy_line}" if installer.trash_copy_line
       rescue StandardError => e
         result.failed[member] = e.message.lines.first.to_s.strip
       end
@@ -164,6 +167,7 @@ module Samagotchi
           result.removed << member
           result.trash[member] = [uninstaller.trashed_files, uninstaller.trash_dir] if uninstaller.trash_dir
           result.warnings.concat(uninstaller.warnings.map { |w| "#{member}: #{w}" })
+          result.warnings << "#{member}: #{uninstaller.trash_copy_line}" if uninstaller.trash_copy_line
         rescue Uninstaller::UninstallError => e
           result.blocked[member] = e.message
         end

data/lib/samagotchi/memory_bundle/provenance.rb

@@ -22,11 +22,23 @@ module Samagotchi
 
       attr_reader :name, :bundle_dir
 
+      # What a conflict mark adds to a file's entry.
+      MARK_FIELDS = %w[conflict incoming_sha legacy_base why missed missed_places].freeze
+      # What a merge no report has shown adds to a file's entry (#note_merged).
+      MERGE_NOTE_FIELDS = %w[merged_version merged_at merged_trash].freeze
+
       def initialize(name:)
         @name = name
         @bundle_dir = File.join(self.class.bundles_dir, name)
       end
 
+      # The bundle's text a marked file missed: incoming/<file>, there until the
+      # file settles, so it outlives a git or zip source's extract. Nothing globs
+      # the bundle's folder for memories, and an uninstall's rm_rf sweeps it.
+      def incoming_path(file_key)
+        File.join(@bundle_dir, "incoming", file_key.to_s)
+      end
+
       def hooks_dir
         File.join(@bundle_dir, "hooks")
       end
@@ -80,7 +92,7 @@ module Samagotchi
 
           begin
             data = JSON.parse(File.read(mjson), symbolize_names: true)
-          rescue JSON::ParserError, SystemCallError => e
+          rescue JSON::ParserError, EncodingError, SystemCallError => e # a key that isn't UTF-8 can't be a symbol
             if holding.nil? || Dir.exist?(File.join(dir, name, holding.to_s))
               yield name, InstalledBundle.unreadable(name, "manifest.json is unreadable: #{e.message}")
             end
@@ -135,6 +147,11 @@ module Samagotchi
       # Writes provenance for an installation: merges into existing manifest.json
       # and saves base snapshots. Stale base snapshots (files removed from bundle)
       # are pruned.
+      # @param files [Hash{String => String, nil}] every file the record keeps
+      #   => the file whose content is its base; a key left out is dropped from
+      #   the record. nil keeps an entry with no base (a kept edit that has
+      #   none: the user's file must never become it), with its recorded
+      #   checksum.
       # @param hooks_files [Hash] basename => path for hook file snapshots (optional)
       # @param guardrails_files [Hash] basename => installed rule file; the
       #   sha256 of each is recorded (the Engine checks it at load)
@@ -143,18 +160,24 @@ module Samagotchi
       #   snapshot
       # @param requires_chi [String, nil] the manifest's requirement
       # @param needs [Array<Hash>] the manifest's needs ({command:, why:, hint:})
-      # @param conflicts [Array<String>] files an upgrade kept with local
-      #   edits that conflict with it; their entries get conflict: true
+      # @param marks [Array<FileStanding::Behind>] files an upgrade left behind;
+      #   their entries get conflict: true, and what the Behind says
+      # @param incoming_dir [String, nil] the bundle's source: each marked file's
+      #   digest goes with the mark (incoming_sha: what Remerge retries) and its
+      #   text is saved (#incoming_path), a settled file's going. A mark from an
+      #   older chi that stays a mark gets legacy_base: true
+      #   (InstalledBundle.legacy_mark?)
       # @param includes [Array<String>, nil] a profile's recorded members
       #   (MemoryBundle::Profile); nil for a plain bundle
       # @param scripts_files [Hash] file name => installed script; the
       #   sha256 of each is recorded (ContextFetch checks it before a run)
       # @param context_providers [Array<ContextProviders::Provider>]
+      # @param block_renderers [Array<BlockRenderers::Renderer>]
       # @param dev [Boolean] a dev install: its files are links to the
       #   source, recorded as DEV_SHA (no sha256 check) with "dev": true
       def write(files:, scope:, version:, source_path:, hooks: {}, trust_level: nil, source_commit: nil, hooks_files: {},
-                guardrails_files: {}, plugin_file: nil, requires_chi: nil, needs: nil, conflicts: [], includes: nil,
-                scripts_files: {}, context_providers: [], file_descriptions: {}, session_settings: [], session_setting_types: {}, settings: nil, setting_types: {},
+                guardrails_files: {}, plugin_file: nil, requires_chi: nil, needs: nil, marks: [], incoming_dir: nil, includes: nil,
+                scripts_files: {}, context_providers: [], block_renderers: [], file_descriptions: {}, session_settings: [], session_setting_types: {}, settings: nil, setting_types: {},
                 dev: false)
         FileUtils.mkdir_p(@bundle_dir)
         bases_dir = File.join(@bundle_dir, "bases")
@@ -164,14 +187,26 @@ module Samagotchi
         # files and hooks not in this install are stale.
         existing = record
         merged_entries = existing ? existing.files.dup : {}
+        marked = marks.to_h { |mark| [mark.file, mark] }
 
         files.each do |file_key, file_path|
-          content = File.read(file_path)
-          checksum = Digest::SHA256.hexdigest(content)
-          # Save base snapshot — use file_key as-is (it already includes .md).
-          File.write(File.join(bases_dir, file_key), content)
-          merged_entries[file_key] = { checksum: checksum }
-          merged_entries[file_key][:conflict] = true if conflicts.include?(file_key.to_s)
+          legacy = InstalledBundle.legacy_mark?(merged_entries[file_key])
+          note = merged_entries.fetch(file_key, {}).slice(*MERGE_NOTE_FIELDS.map(&:to_sym))
+          if file_path
+            content = File.read(file_path)
+            # Save base snapshot — use file_key as-is (it already includes .md).
+            File.write(File.join(bases_dir, file_key), content)
+            merged_entries[file_key] = { checksum: Digest::SHA256.hexdigest(content) }
+          else
+            merged_entries[file_key] = merged_entries.fetch(file_key, {}).slice(:checksum)
+          end
+          merged_entries[file_key].merge!(note)
+          if (mark = marked[file_key.to_s])
+            merged_entries[file_key].merge!(mark_fields(mark))
+            merged_entries[file_key][:legacy_base] = true if legacy
+            sha = incoming_dir && incoming_sha(File.join(incoming_dir, file_key.to_s))
+            merged_entries[file_key][:incoming_sha] = sha if sha
+          end
           merged_entries[file_key][:description] = file_descriptions[file_key.to_s] if file_descriptions[file_key.to_s]
         end
 
@@ -255,35 +290,118 @@ module Samagotchi
           end
         end
         manifest_data["context_providers"] = context_providers.map(&:to_h) unless context_providers.empty?
+        manifest_data["block_renderers"] = block_renderers.map(&:to_h) unless block_renderers.empty?
         manifest_data["session_settings"] = Array(session_settings).map(&:to_s) unless Array(session_settings).empty?
         manifest_data["session_setting_types"] = session_setting_types.to_h { |k, v| [k.to_s, v.to_s] } unless session_setting_types.to_h.empty?
         manifest_data["settings"] = settings.map(&:to_s) unless settings.nil?
         manifest_data["setting_types"] = setting_types.to_h { |k, v| [k.to_s, v.to_s] } unless setting_types.to_h.empty?
 
         write_manifest(manifest_data)
+        marked.each_key { |key| save_incoming(key, incoming_dir) }
+        prune_incoming(marked.keys)
       end
 
-      # After a conflict was resolved by hand: each file's base becomes the
-      # bundle's version (the incoming file, else what's on disk now) and
-      # its conflict mark goes. The rest of the manifest stays as is.
+      # After a conflict was settled: each file's base becomes the incoming
+      # file and its conflict mark goes. The rest of the manifest (its
+      # description too) stays as is. A file whose incoming copy is gone keeps
+      # its mark and base: taking the file on disk would make the user's text
+      # the base, and the next upgrade would fast-forward over it.
       # @param conflicts [Hash{String => Hash}] Installer#conflicts
+      # @return [Array<String>] the files it settled
       def resolve_conflicts(conflicts)
-        return unless installed?
+        return [] unless installed?
 
         raw = JSON.parse(File.read(File.join(@bundle_dir, "manifest.json")))
         raw["files"] ||= {}
-        conflicts.each do |file_key, info|
+        settled = conflicts.filter_map do |file_key, info|
           key = file_key.to_s
-          next unless raw["files"].key?(key)
+          next unless raw["files"].key?(key) && info[:incoming] && File.exist?(info[:incoming])
 
-          src = [info[:incoming], info[:current]].find { |p| p && File.exist?(p) }
-          next unless src
-
-          content = File.read(src)
+          content = File.read(info[:incoming])
           File.write(base_path(key), content)
-          raw["files"][key] = { "checksum" => Digest::SHA256.hexdigest(content) }
+          raw["files"][key] = raw["files"][key].except(*MARK_FIELDS).merge("checksum" => Digest::SHA256.hexdigest(content))
+          key
+        end
+        write_manifest(raw)
+        prune_incoming(marked_in(raw))
+        settled
+      end
+
+      # A missing file was put back with the bundle's bytes: +path+ is its base,
+      # its entry is made or rebuilt (no mark), and the rest of the manifest stays.
+      def record_restored(file_key, path, description: nil)
+        raw = JSON.parse(File.read(File.join(@bundle_dir, "manifest.json")))
+        content = File.binread(path)
+        File.binwrite(base_path(file_key), content)
+        entry = { "checksum" => Digest::SHA256.hexdigest(content) }
+        kept = description || raw.dig("files", file_key, "description")
+        entry["description"] = kept if kept
+        (raw["files"] ||= {})[file_key] = entry
+        write_manifest(raw)
+        prune_incoming(marked_in(raw))
+      end
+
+      # What a retry found of files still marked: the mark says it, its digest
+      # recorded if it had none (a mark made before chi kept it; legacy_base keeps
+      # that known, InstalledBundle.legacy_mark?), the bundle's text saved. The
+      # rest of the manifest stays.
+      # @param marks [Array<FileStanding::Behind>]
+      # @param incoming_dir [String] the bundle's source
+      def refresh_marks(marks, incoming_dir)
+        return unless installed?
+
+        raw = JSON.parse(File.read(File.join(@bundle_dir, "manifest.json")))
+        marks.each do |mark|
+          entry = raw.dig("files", mark.file)
+          next unless entry&.fetch("conflict", nil)
+
+          save_incoming(mark.file, incoming_dir)
+          entry.reject! { |field, _| %w[why missed missed_places].include?(field) }
+          entry.merge!(mark_fields(mark).transform_keys(&:to_s))
+          sha = incoming_sha(File.join(incoming_dir, mark.file))
+          entry.merge!("incoming_sha" => sha, "legacy_base" => true) if sha && !entry["incoming_sha"]
+        end
+        write_manifest(raw)
+      end
+
+      # Every merge leaves a note on the file's entry, one no one may have seen (a
+      # worker's start logs it and nothing else, an automatic update's rows are
+      # read by no one). It stays through later upgrades, until #clear_merge_notes,
+      # which a report someone reads does once it has shown the merge.
+      # @param files [Array<String>]
+      # @param version [String] what merged
+      # @param trash [String, nil] the dir holding the old copy
+      def note_merged(files, version:, trash:, at: Time.now)
+        return unless installed?
+
+        raw = JSON.parse(File.read(File.join(@bundle_dir, "manifest.json")))
+        files.each do |key|
+          raw.dig("files", key)&.merge!({ "merged_version" => version.to_s, "merged_at" => at.iso8601, "merged_trash" => trash }.compact)
+        end
+        write_manifest(raw)
+      end
+
+      # These notes go, and a later merge's on the same file stays. A note that
+      # can't be cleared shows once more: nothing about it fails a report.
+      # @param notes [Array<FileStanding::MergeNote>] as #record gave them, read
+      #   before a run
+      # @param files [Array<String>] files whose note goes whatever it says: the run
+      #   just merged or replaced them. Another file's, a worker's meanwhile, stays.
+      def clear_merge_notes(notes, files: [])
+        return if notes.empty? && files.empty?
+
+        raw = JSON.parse(File.read(File.join(@bundle_dir, "manifest.json")))
+        stale = notes.select do |note|
+          entry = raw.dig("files", note.file)
+          entry && entry["merged_version"] == note.version && entry["merged_at"] == note.at
+        end
+        (stale.map(&:file) + files).each do |file|
+          entry = raw.dig("files", file)
+          MERGE_NOTE_FIELDS.each { |field| entry.delete(field) } if entry
         end
         write_manifest(raw)
+      rescue JSON::ParserError, SystemCallError
+        nil
       end
 
       # The installed bundle's record, nil when it isn't installed.
@@ -310,6 +428,48 @@ module Samagotchi
       end
       private :write_manifest
 
+      def mark_fields(mark)
+        { conflict: true, why: mark.why, missed: mark.missed.empty? ? nil : mark.missed,
+          missed_places: mark.places.zero? ? nil : mark.places }.compact
+      end
+      private :mark_fields
+
+      def incoming_sha(path)
+        File.exist?(path) ? self.class.file_sha(path) : nil
+      rescue SystemCallError
+        nil
+      end
+      private :incoming_sha
+
+      # The saved text is a convenience, and an install's assets are already in
+      # place when this runs: failing here would leave them under the old record's
+      # shas, and a plugin that doesn't load. So nothing about it fails a write.
+      def save_incoming(file_key, incoming_dir)
+        source = incoming_dir && File.join(incoming_dir, file_key.to_s)
+        return unless source && File.exist?(source)
+
+        FileUtils.mkdir_p(File.dirname(incoming_path(file_key)))
+        FileUtils.cp(source, incoming_path(file_key))
+      rescue SystemCallError
+        nil
+      end
+      private :save_incoming
+
+      def marked_in(raw) = (raw["files"] || {}).select { |_, entry| entry["conflict"] }.keys
+      private :marked_in
+
+      # Each file that settled loses its saved text; the folder goes with the last.
+      def prune_incoming(keep)
+        dir = File.join(@bundle_dir, "incoming")
+        return unless Dir.exist?(dir)
+
+        (Dir.children(dir) - keep).each { |file| FileUtils.rm_f(File.join(dir, file)) }
+        Dir.rmdir(dir) if Dir.empty?(dir)
+      rescue SystemCallError
+        nil
+      end
+      private :prune_incoming
+
       # Returns the path to a base snapshot for a given file key.
       def base_path(file_key)
         File.join(@bundle_dir, "bases", file_key)