samagotchi 0.160.0 → 0.161.0

data/lib/samagotchi/memory_bundle/asset_installer.rb

@@ -50,7 +50,8 @@ module Samagotchi
       # @param chi_version [String] the chi this install is for (the Installer's;
       #   a caller that checks its own bundles against another version passes it)
       def initialize(name:, source_dir:, manifest:, provenance:, existing:, results:, warnings:, conflicts:, trash:,
-                     force: false, strict: true, upgrade: false, dry_run: false, dev: false, chi_version: Samagotchi::VERSION)
+                     force: false, strict: true, upgrade: false, dry_run: false, dev: false, chi_version: Samagotchi::VERSION,
+                     refuse_mismatch: false)
         @name = name
         @bundle_dir = source_dir
         @manifest = manifest
@@ -66,11 +67,42 @@ module Samagotchi
         @dry_run = dry_run
         @dev = dev
         @chi_version = chi_version
+        @refuse_mismatch = refuse_mismatch
+      end
+
+      # Raises for the first plugin or script the manifest names that the
+      # bundle doesn't have (or ships as a link), writing nothing: the
+      # Installer runs it before its first write.
+      # @raise [Installer::InstallError]
+      def check_named_files
+        plugin_source
+        scripts_sources
+      end
+
+      # The same early pass on the shas: the plugin and each script against the
+      # bundle's own bytes, before anything is written. Only when the caller
+      # refuses a mismatch (`chi bundle install/upgrade`; chi update, a profile
+      # and a dev install keep their warning), and not with --force, which
+      # installs a mismatch anyway.
+      # @raise [Installer::InstallError] one line per mismatched file
+      def check_named_checksums
+        return unless @refuse_mismatch && @strict && !@dev && !@force && @manifest
+
+        lines = []
+        if @manifest.plugin
+          lines << Installer.mismatch_refusal("plugin #{@manifest.plugin[:file]}", plugin_source,
+                                              @manifest.checksum_for_plugin, upgrade: @upgrade)
+        end
+        scripts_sources.each do |name, src|
+          lines << Installer.mismatch_refusal("script #{name}", src, declared_sha(:script, name), upgrade: @upgrade)
+        end
+        lines = lines.compact
+        raise Installer::InstallError, lines.join("\n") unless lines.empty?
       end
 
       # @return [Installed]
-      # @raise [Installer::InstallError] the manifest names a plugin or
-      #   script the bundle doesn't have
+      # @raise [Installer::InstallError] the same, when #check_named_files
+      #   wasn't run first
       def run
         incoming_rules = Dir.glob(File.join(@bundle_dir, "guardrails", "*.yml")).sort
                             .reject { |src| linked_out?(src, "guardrails/#{File.basename(src)}") }
@@ -137,30 +169,45 @@ module Samagotchi
         plugin = @manifest&.plugin
         return {} unless plugin
 
-        src = File.join(@bundle_dir, plugin[:file])
-        raise Installer::InstallError, "the manifest names plugin #{plugin[:file]}, which the bundle doesn't have" unless File.file?(src)
-        raise Installer::InstallError, "plugin #{plugin[:file]} is a symlink (not installed)" if linked?(src)
-
+        src = plugin_source
         if (failure = Manifest.requires_chi_failure(@manifest.requires_chi, @chi_version))
           @warnings << "Plugin #{plugin[:file]} won't load: #{failure}"
         end
         { plugin[:file] => src }
       end
 
-      # The manifest's scripts (a dev install warns of one it can't run).
+      # The manifest's plugin file in the source, checked; nil without one.
+      def plugin_source
+        plugin = @manifest&.plugin
+        return unless plugin
+
+        src = File.join(@bundle_dir, plugin[:file])
+        raise Installer::InstallError, "the manifest names plugin #{plugin[:file]}, which the bundle doesn't have" unless File.file?(src)
+        raise Installer::InstallError, "plugin #{plugin[:file]} is a symlink (not installed)" if linked?(src)
+
+        src
+      end
+
+      # The manifest's scripts in the source, checked.
       # @return [Hash{String => String}] file name => the source file
-      def scripts_incoming
-        scripts = @manifest&.scripts || {}
-        scripts.keys.to_h do |file|
+      def scripts_sources
+        (@manifest&.scripts || {}).keys.to_h do |file|
           src = File.join(@bundle_dir, "scripts", file)
           raise Installer::InstallError, "the manifest names scripts/#{file}, which the bundle doesn't have" unless File.file?(src)
           raise Installer::InstallError, "scripts/#{file} is a symlink (not installed)" if linked?(src)
 
-          @warnings << "scripts/#{file} is not executable; chmod +x #{src}" if @dev && !File.executable?(src) && !page_only?(file)
           [file, src]
         end
       end
 
+      # The manifest's scripts (a dev install warns of one it can't run).
+      # @return [Hash{String => String}] file name => the source file
+      def scripts_incoming
+        scripts_sources.each do |file, src|
+          @warnings << "scripts/#{file} is not executable; chmod +x #{src}" if @dev && !File.executable?(src) && !page_only?(file)
+        end
+      end
+
       # One folder of the bundle's own dir (guardrails/, plugin/, scripts/),
       # replaced whole by +incoming+: each file's AssetState and its action
       # (FileActions' ASSET_INSTALL, or ASSET_UPGRADE over an installed

data/lib/samagotchi/memory_bundle/file_state.rb

@@ -11,6 +11,10 @@ module Samagotchi
     # the record's entry (R). Derived, never stored. FileActions says what each
     # acting command does in each state.
     #
+    # A file whose disk bytes are the text an interrupted run journaled
+    # (Provenance#write_pending) reads as the bundle's, at that run's
+    # version: owned (an entry made up if the record has none), its own base.
+    #
     # kind, with a source (install, upgrade, remerge, restore, plan):
     #   :new               not the bundle's, not on disk
     #   :user_same         not the bundle's, on disk with I's bytes
@@ -82,6 +86,7 @@ module Samagotchi
       # @return [FileState]
       def of(key, record:, provenance:, target_dir:, source_dir:, claimants: nil, shipped: true)
         entry = record&.files&.fetch(key, nil)
+        pending = provenance.pending_shas(key, target_dir: target_dir)
         paths = { base: provenance.base_path(key), current: File.join(target_dir, key),
                   incoming: source_dir && File.join(source_dir, key) }
         mark = mark_of(entry)
@@ -90,6 +95,12 @@ module Samagotchi
           incoming: source_dir && shipped ? digest(paths[:incoming]) : nil, recorded: entry && Provenance.recorded_sha(entry[:checksum]),
           marked_incoming: mark == :none ? nil : entry[:incoming_sha]
         )
+        if !pending.empty? && pending.include?(digests.disk)
+          # An interrupted run put this text here (Provenance#write_pending): it is the bundle's at
+          # that version, owned and its own base, not the user's file or an edit of the recorded one.
+          entry = (entry || {}).merge(checksum: digests.disk)
+          digests = digests.with(base: digests.disk, recorded: digests.disk)
+        end
         shared = nil
         lookup = -> { shared ||= claimants ? claimants.call(key) : [] }
         state = FileState.new(key: key, kind: nil, mark: mark, digests: digests, entry: entry, paths: paths, claimants: lookup)

data/lib/samagotchi/memory_bundle/index_updater.rb

@@ -14,8 +14,11 @@ module Samagotchi
       # @param source [String, false, nil] the bundle the memory came from
       #   ("· from <bundle>"): a name sets it, false drops it, nil keeps the
       #   line's (memory_write and write/edit pass nil)
-      def self.update_index(scope, entry_name, byte_count, description = nil, source: nil)
-        index_path = index_path_for(scope)
+      # @param target_dir [String, nil] the folder whose index.md to edit, when
+      #   it is not the one +scope+ resolves from the current folder (an
+      #   uninstall of a bundle journaled into another project)
+      def self.update_index(scope, entry_name, byte_count, description = nil, source: nil, target_dir: nil)
+        index_path = target_dir ? File.join(target_dir, "#{MEMORY_INDEX}.md") : index_path_for(scope)
         return true unless index_path
 
         locked_write(File.dirname(index_path)) do |content|
@@ -39,8 +42,8 @@ module Samagotchi
         /^- \*\*#{Regexp.escape(name)}\*\*[ \t]*(?:[·•].*|:.*)?(\r?\n|\z)/
       end
 
-      def self.remove_index(scope, entry_name)
-        index_path = index_path_for(scope)
+      def self.remove_index(scope, entry_name, target_dir: nil)
+        index_path = target_dir ? File.join(target_dir, "#{MEMORY_INDEX}.md") : index_path_for(scope)
         return true unless index_path && File.exist?(index_path)
 
         locked_write(File.dirname(index_path)) do |content|

data/lib/samagotchi/memory_bundle/installer.rb

@@ -61,7 +61,8 @@ module Samagotchi
       # chi_version: the chi this install is for (Profile and ShippedUpdate
       # check their bundles against a version they are given); default this chi.
       def initialize(source:, name:, scope: nil, force: false, strict: true, upgrade: false, dry_run: false, prepared: nil,
-                     shipped_dir: SourceNormalizer::SHIPPED_DIR, dev: false, chi_version: Samagotchi::VERSION)
+                     shipped_dir: SourceNormalizer::SHIPPED_DIR, dev: false, chi_version: Samagotchi::VERSION,
+                     refuse_mismatch: false)
         @source = source
         @shipped_dir = shipped_dir
         @prepared = prepared
@@ -73,6 +74,10 @@ module Samagotchi
         @dry_run = dry_run
         @dev = dev
         @chi_version = chi_version
+        # `chi bundle install/upgrade` refuses a file whose bytes disagree with
+        # its manifest sha before writing anything; the callers that only warn
+        # (ShippedUpdate, SystemBundle, Profile) leave it unset.
+        @refuse_mismatch = refuse_mismatch
         @results = {}
         @warnings = []
         @placeholder_warnings = []
@@ -119,10 +124,11 @@ module Samagotchi
       def run
         load_source
         refuse_too_new
+        @provenance = Provenance.new(name: @name)
+        refuse_newer_record_format
         warn_unknown_keys(@manifest) if @manifest
         @target_scope, @target_dir = resolve_target
         @file_descriptions = @manifest&.file_descriptions || {}
-        @provenance = Provenance.new(name: @name)
         @existing = @provenance.record
         check_source
         # A plain install over an installed bundle: its summary says so.
@@ -212,6 +218,18 @@ module Samagotchi
           "(to leave dev mode: chi bundle uninstall #{name}, then chi bundle install without --dev)"
       end
 
+      # The line a refused install names one file with: the checksum warning and
+      # the way past it. Only `chi bundle install/upgrade` refuses a mismatch
+      # (--force skips the early check and keeps the post-write warning); the
+      # callers that only warn (chi update, SystemBundle, a profile) never reach
+      # this.
+      # @param label [String] "a.md", "plugin plugin.rb", "script s.sh"
+      # @param upgrade [Boolean] which command the hint names
+      def self.mismatch_refusal(label, path, expected, upgrade:)
+        warning = FileDigest.mismatch(label, path, expected)
+        warning && "#{warning}; chi bundle #{upgrade ? "upgrade" : "install"} --force installs it anyway"
+      end
+
       private
 
       # The files whose result has one of +words+, in the order they ran.
@@ -233,28 +251,71 @@ module Samagotchi
         line
       end
 
-      # The steps that replace files: memories, the bundle's own folder, then
-      # the files it dropped. The record isn't written yet, so a failed run is
+      # The steps that replace files, after the check of the files the manifest
+      # names: memories, the bundle's own folder, then the files it dropped. The record isn't written yet, so a failed run is
       # retried as the same upgrade.
       # @return [AssetInstaller::Installed]
       # @raise [InstallError] a file system error (a file it can't read, a
       #   .trash it can't write)
       def replace_files
-        install_memories
-
-        installed = AssetInstaller.new(
+        assets = AssetInstaller.new(
           name: @name, source_dir: @bundle_dir, manifest: @manifest, provenance: @provenance, existing: @existing,
           results: @results, warnings: @warnings, conflicts: @conflicts, trash: @trash,
-          force: @force, strict: @strict, upgrade: @upgrade, dry_run: @dry_run, dev: @dev, chi_version: @chi_version
-        ).run
+          force: @force, strict: @strict, upgrade: @upgrade, dry_run: @dry_run, dev: @dev, chi_version: @chi_version,
+          refuse_mismatch: @refuse_mismatch
+        )
+        # Before the first write: a plugin or script the bundle lacks refuses the run with disk and record as they were.
+        assets.check_named_files
+        # And, for the commands that refuse it (--force aside), a file whose
+        # bytes disagree with the sha its manifest declares.
+        refuse_memory_mismatches
+        assets.check_named_checksums
+        write_pending
+        install_memories
+        installed = assets.run
 
         # Files the previous version shipped and this one doesn't.
-        prune_dropped_files(@existing.files, @bundle_md, @target_dir, @target_scope, @provenance) if @upgrade && @existing
+        previous_files = @provenance.files_with_pending(@existing, target_dir: @target_dir)
+        prune_dropped_files(previous_files, @bundle_md, @target_dir, @target_scope, @provenance) if @upgrade && @existing
         installed
       rescue SystemCallError => e
         raise InstallError, Trash.failure_message(e)
       end
 
+      # The intent journal (Provenance#write_pending): the text of each memory
+      # this run will change, noted before the first write, so a run that
+      # stops before its record leaves files a retry still knows as the
+      # bundle's.
+      def write_pending
+        return if @dry_run || @manifest.nil?
+
+        incoming = memory_files.to_h { |key| [key, FileDigest.hex(File.join(@bundle_dir, key))] }
+        incoming.reject! do |key, sha|
+          sha.nil? || sha == FileDigest.hex(File.join(@target_dir, key))
+        rescue SystemCallError
+          true
+        end
+        @provenance.write_pending(version: @manifest.version, scope: @target_scope, target_dir: @target_dir, files: incoming) unless incoming.empty?
+      rescue SystemCallError => e
+        raise InstallError, Trash.failure_message(e)
+      end
+
+      # Before the first write, the bundle's own bytes against the sha its
+      # manifest declares for each memory: `chi bundle install/upgrade` refuses
+      # a mismatch (--force skips the check, and #verify_memory_checksums keeps
+      # the post-write warning for the callers that only warn). A dev install
+      # follows its own tree; a non-strict run has no shas to trust.
+      # @raise [InstallError] one line per mismatched file
+      def refuse_memory_mismatches
+        return unless @refuse_mismatch && @strict && !@dev && !@force && @manifest
+
+        lines = memory_files.filter_map do |file_key|
+          self.class.mismatch_refusal(file_key, File.join(@bundle_dir, file_key),
+                                      @manifest.checksum_for(file_key), upgrade: @upgrade)
+        end
+        raise InstallError, lines.join("\n") unless lines.empty?
+      end
+
       # Who may install under this name (a manifest can take any name: a
       # repo calling itself guardrails). Sources compare by SourceIdentity
       # (a shipped dir by name, in any gem or checkout; a git URL without
@@ -384,6 +445,12 @@ module Samagotchi
         raise InstallError, "#{@name} can't be installed: #{failure} (chi update, or --force to install it anyway)"
       end
 
+      def refuse_newer_record_format
+        @provenance.ensure_supported_record_format!
+      rescue StateFormat::InvalidDocument => e
+        raise InstallError, e.message
+      end
+
       # The scope the files go to (the CLI's wins over the manifest's) and
       # its dir, created.
       # @return [Array(String, String)] scope, dir
@@ -785,8 +852,8 @@ module Samagotchi
 
       # Not fatal, like update_target_index: a warning says so.
       def remove_target_index(scope, file_key)
-        IndexUpdater.remove_index(scope, file_key.delete_suffix(".md"))
-        IndexUpdater.remove_index(scope, file_key) # legacy "name.md" line
+        IndexUpdater.remove_index(scope, file_key.delete_suffix(".md"), target_dir: @target_dir)
+        IndexUpdater.remove_index(scope, file_key, target_dir: @target_dir) # legacy "name.md" line
       rescue StandardError => e
         @warnings << "index.md: line for #{file_key.delete_suffix(".md")} not removed (#{e.message})"
       end

data/lib/samagotchi/memory_bundle/provenance.rb

@@ -7,6 +7,7 @@ require "fileutils"
 require "tmpdir"
 require_relative "../atomic_file"
 require_relative "../memory_paths"
+require_relative "../state_format"
 require_relative "../version"
 require_relative "file_digest"
 require_relative "installed_bundle"
@@ -32,6 +33,38 @@ module Samagotchi
       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
+      RECORD_FORMAT_VERSION = 1
+      RECORD_FORMAT = StateFormat.new(
+        version: RECORD_FORMAT_VERSION,
+        members: [
+          StateFormat.required(:name),
+          StateFormat.required(:version),
+          StateFormat.required(:scope),
+          StateFormat.required(:source),
+          StateFormat.required(:installed_at),
+          StateFormat.required(:files),
+          StateFormat.required(:hooks),
+          StateFormat.added(:record_format, in_version: 1, default: 1),
+          StateFormat.added(:dev, in_version: 1, default: false),
+          StateFormat.added(:guardrails, in_version: 1, default: {}),
+          StateFormat.added(:source_commit, in_version: 1, default: nil),
+          StateFormat.added(:plugin, in_version: 1, default: nil),
+          StateFormat.added(:includes, in_version: 1, default: nil),
+          StateFormat.added(:scripts, in_version: 1, default: {}),
+          StateFormat.added(:manifest_sha, in_version: 1, default: nil),
+          StateFormat.added(:installed_by, in_version: 1, default: nil),
+          StateFormat.added(:requires_chi, in_version: 1, default: nil),
+          StateFormat.added(:trust_level, in_version: 1, default: nil),
+          StateFormat.added(:needs, in_version: 1, default: nil),
+          StateFormat.added(:context_providers, in_version: 1, default: nil),
+          StateFormat.added(:block_renderers, in_version: 1, default: nil),
+          StateFormat.added(:session_settings, in_version: 1, default: nil),
+          StateFormat.added(:session_setting_types, in_version: 1, default: nil),
+          StateFormat.added(:settings, in_version: 1, default: nil),
+          StateFormat.added(:setting_types, in_version: 1, default: nil),
+          StateFormat.extra(:extra, in_version: 1)
+        ]
+      )
 
       def initialize(name:)
         @name = name
@@ -65,6 +98,55 @@ module Samagotchi
         File.join(@bundle_dir, "scripts")
       end
 
+      # The intent journal of a run that has not written its record yet
+      # (#write_pending): its scope and target dir, plus the files and sha256s
+      # of the texts a run meant to put there. #write removes it.
+      def pending_path
+        File.join(@bundle_dir, "pending.json")
+      end
+
+      # Notes, before an install's first write, the texts it is about to put
+      # in the memories dir, atomically. A journal an earlier interrupted run
+      # left keeps its shas (that run's files are still on disk).
+      # @param files [Hash{String => String}] memory => the incoming sha256
+      def write_pending(version:, scope:, target_dir:, files:)
+        shas = pending_files(target_dir: target_dir)
+        files.each { |key, sha| shas[key] = (shas.fetch(key, []) + [sha]).uniq }
+        FileUtils.mkdir_p(@bundle_dir)
+        AtomicFile.write(pending_path, JSON.pretty_generate(
+          "version" => version.to_s, "scope" => scope.to_s, "target_dir" => File.expand_path(target_dir), "files" => shas
+        ))
+      end
+
+      # The shas the journal names for +file_key+ (none without a journal, or
+      # with one that doesn't read or belongs to another target).
+      def pending_shas(file_key, target_dir:)
+        pending_files(target_dir: target_dir).fetch(file_key.to_s, [])
+      end
+
+      def pending_scope
+        pending_metadata&.fetch("scope")
+      end
+
+      def pending_target_dir
+        pending_metadata&.fetch("target_dir")
+      end
+
+      # The record's files plus interrupted files whose current bytes match a
+      # journaled sha. Files whose bytes no longer match are not claimed.
+      def files_with_pending(record, target_dir:)
+        files = record&.files&.dup || {}
+        pending_files(target_dir: target_dir).each do |key, shas|
+          next if files.key?(key)
+
+          disk_sha = FileDigest.hex(File.join(target_dir, key))
+          files[key] = {} if shas.include?(disk_sha)
+        rescue SystemCallError
+          next
+        end
+        files
+      end
+
       # The bundle's manifest.yml as installed (InstalledBundle#kept_manifest_path).
       def kept_manifest_path
         File.join(@bundle_dir, "manifest.yml")
@@ -233,6 +315,7 @@ module Samagotchi
                 guardrails_files: {}, plugin_file: nil, plugin_required: false, 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, manifest_from: nil)
+        record_extra = format_record(read)&.extra || {}
         FileUtils.mkdir_p(@bundle_dir)
         bases_dir = File.join(@bundle_dir, "bases")
         FileUtils.mkdir_p(bases_dir)
@@ -280,6 +363,7 @@ module Samagotchi
 
         manifest_data = {
           "name" => @name,
+          "record_format" => RECORD_FORMAT_VERSION,
           "version" => version.to_s,
           "scope" => scope.to_s,
           "source" => source_path.to_s,
@@ -314,8 +398,10 @@ module Samagotchi
           end
         end
         manifest_data.merge!(kept_manifest_fields(existing, manifest_from, dev))
+        manifest_data = record_extra.merge(manifest_data)
 
         write_manifest(manifest_data)
+        FileUtils.rm_f(pending_path)
         marked.each_key { |key| save_incoming(key, incoming_dir) }
         prune_incoming(marked.keys)
       end
@@ -330,7 +416,7 @@ module Samagotchi
       def resolve_conflicts(conflicts)
         return [] unless installed?
 
-        raw = JSON.parse(File.read(File.join(@bundle_dir, "manifest.json")))
+        raw = writable_record
         raw["files"] ||= {}
         settled = conflicts.filter_map do |file_key, info|
           key = file_key.to_s
@@ -349,7 +435,7 @@ module Samagotchi
       # 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")))
+        raw = writable_record
         content = File.binread(path)
         File.binwrite(base_path(file_key), content)
         entry = { "checksum" => Digest::SHA256.hexdigest(content) }
@@ -369,7 +455,7 @@ module Samagotchi
       def refresh_marks(marks, incoming_dir)
         return unless installed?
 
-        raw = JSON.parse(File.read(File.join(@bundle_dir, "manifest.json")))
+        raw = writable_record
         marks.each do |mark|
           entry = raw.dig("files", mark.file)
           next unless entry&.fetch("conflict", nil)
@@ -393,7 +479,7 @@ module Samagotchi
       def note_merged(files, version:, trash:, at: Time.now)
         return unless installed?
 
-        raw = JSON.parse(File.read(File.join(@bundle_dir, "manifest.json")))
+        raw = writable_record
         files.each do |key|
           raw.dig("files", key)&.merge!({ "merged_version" => version.to_s, "merged_at" => at.iso8601, "merged_trash" => trash }.compact)
         end
@@ -409,7 +495,7 @@ module Samagotchi
       def clear_merge_notes(notes, files: [])
         return if notes.empty? && files.empty?
 
-        raw = JSON.parse(File.read(File.join(@bundle_dir, "manifest.json")))
+        raw = writable_record
         stale = notes.select do |note|
           entry = raw.dig("files", note.file)
           entry && entry["merged_version"] == note.version && entry["merged_at"] == note.at
@@ -419,6 +505,8 @@ module Samagotchi
           MERGE_NOTE_FIELDS.each { |field| entry.delete(field) } if entry
         end
         write_manifest(raw)
+      rescue StateFormat::InvalidDocument => e
+        e.message
       rescue JSON::ParserError, SystemCallError
         nil
       end
@@ -437,7 +525,10 @@ module Samagotchi
       def adopt_manifest(dir, dry_run: false)
         bundle = record
         return "#{@name} isn't installed" unless bundle
+
         return "#{@name} is a dev install" if bundle.dev
+
+        raw = writable_record
         return "#{@name} keeps its manifest already" unless bundle.manifest_unkept?
 
         source = File.join(dir.to_s, "manifest.yml")
@@ -449,9 +540,10 @@ module Samagotchi
         return why if why || dry_run
 
         AtomicFile.write(kept_manifest_path, bytes)
-        raw = JSON.parse(File.read(File.join(@bundle_dir, "manifest.json")))
         write_manifest(raw.merge("manifest_sha" => "sha256:#{Digest::SHA256.hexdigest(bytes)}"))
         nil
+      rescue StateFormat::InvalidDocument => e
+        e.message
       rescue JSON::ParserError, SystemCallError => e
         "#{@name}'s record can't take it: #{e.message}"
       end
@@ -463,6 +555,32 @@ module Samagotchi
         InstalledBundle.read(@name, File.join(@bundle_dir, "manifest.json"))
       end
 
+      def ensure_supported_record_format!
+        format_record(read)
+      end
+
+      # The journal's memory => shas, {} when it doesn't belong to this target
+      # or doesn't read.
+      def pending_files(target_dir:)
+        return {} if target_dir.to_s.empty?
+
+        metadata = pending_metadata
+        return {} unless metadata && File.expand_path(target_dir.to_s) == metadata["target_dir"]
+
+        files = metadata["files"]
+        files.is_a?(Hash) ? files.to_h { |key, shas| [key, Array(shas).grep(String)] } : {}
+      end
+
+      def pending_metadata
+        data = JSON.parse(File.read(pending_path))
+        return unless data.is_a?(Hash) && data["scope"].is_a?(String) && data["target_dir"].is_a?(String)
+
+        data
+      rescue JSON::ParserError, EncodingError, SystemCallError
+        nil
+      end
+      private :pending_files, :pending_metadata
+
       # manifest.json as it is on disk, symbol keys (nil if not installed).
       # Readers take #record.
       def read
@@ -472,6 +590,40 @@ module Samagotchi
         JSON.parse(File.read(manifest_path), symbolize_names: true)
       end
 
+      def writable_record
+        raw = JSON.parse(File.read(File.join(@bundle_dir, "manifest.json")))
+        format_record(raw)
+        raw
+      end
+      private :writable_record
+
+      def format_record(data)
+        return unless data
+        raise StateFormat::InvalidDocument, "manifest.json must contain a JSON object" unless data.is_a?(Hash)
+
+        data = data.transform_keys(&:to_s)
+        version = data["record_format"]
+        unless version.nil? || (version.is_a?(Integer) && version >= 0)
+          raise StateFormat::InvalidDocument, "manifest.json has an invalid record_format"
+        end
+
+        document = RECORD_FORMAT.read({ "version" => version, "records" => [data] }, collection: "records")
+        if document.version > RECORD_FORMAT_VERSION
+          raise StateFormat::InvalidDocument,
+                "manifest.json record_format #{document.version} is newer than supported #{RECORD_FORMAT_VERSION}; update chi before writing it"
+        end
+
+        record = document.entries.first
+        unless record&.readable?
+          raise StateFormat::InvalidDocument,
+                "manifest.json is missing required record fields; repair with chi bundle uninstall #{@name} --force, " \
+                "then chi bundle install <source> --force"
+        end
+
+        record
+      end
+      private :format_record
+
       # Write aside and rename, so a reader in another process (a parallel
       # chi start) never parses a truncated manifest.json.
       def write_manifest(manifest_data)

data/lib/samagotchi/memory_bundle/shipped_update.rb

@@ -292,8 +292,9 @@ module Samagotchi
       # Merger::Upgrade#forecast.
       def forecast(row, bundle)
         shipped = Dir.glob(File.join(row.source_dir, "*.md")).map { |f| File.basename(f) }.sort
+        files = Provenance.new(name: row.name).files_with_pending(bundle, target_dir: MemoryPaths.scope_dir!(row.scope))
         Merger::Upgrade.new(provenance: Provenance.new(name: row.name), target_dir: MemoryPaths.scope_dir!(row.scope),
-                            source_dir: row.source_dir).forecast(shipped & bundle.files.keys, version: row.to)
+                            source_dir: row.source_dir).forecast(shipped & files.keys, version: row.to)
       end
 
       # What the upgrade from +source_dir+ copies to the trash, as

data/lib/samagotchi/memory_bundle/status.rb

@@ -39,7 +39,7 @@ module Samagotchi
 
         scope = (scope_override ? bundle.with(scope: scope_override) : bundle).effective_scope
         target_dir = MemoryPaths.scope_dir(scope)
-        files = bundle.files
+        files = provenance.files_with_pending(bundle, target_dir: target_dir)
         details = {}
         behind = bundle.behind_files(target_dir).to_h { |file| [file.file, file] }
         notes = bundle.merge_notes.to_h { |note| [note.file, note] }

data/lib/samagotchi/memory_bundle/system_bundle.rb

@@ -84,6 +84,8 @@ module Samagotchi
       # Those notes have been shown (Provenance#clear_merge_notes), under the lock.
       def clear_merge_notes(notes, files: [])
         with_lock { Provenance.new(name: BUNDLE_NAME).clear_merge_notes(notes, files: files) }
+      rescue StateFormat::InvalidDocument => e
+        e.message
       rescue StandardError
         nil
       end