samagotchi 0.6.0 → 0.8.0

data/lib/samagotchi/llm/native_backend.rb

@@ -32,17 +32,17 @@ module Samagotchi
           pending_input: pending_input
         )
         ModelResult.new(
-          text: kernel_result.respond_to?(:output) ? kernel_result.output.to_s : kernel_result.to_s,
+          text: kernel_result.output.to_s,
           tool_calls: nil,
           provider: :native,
           usage: usage.usage(prompt_text: Array(messages).sum("") { |message| message[:content].to_s }),
-          conversation: kernel_result.respond_to?(:conversation) ? kernel_result.conversation : nil,
-          canceled: kernel_result.respond_to?(:canceled?) && kernel_result.canceled?,
-          cancellation_reason: kernel_result.respond_to?(:cancellation_reason) ? kernel_result.cancellation_reason : nil,
-          exhausted: kernel_result.respond_to?(:exhausted) && kernel_result.exhausted,
-          tool_activity: kernel_result.respond_to?(:tool_activity) ? kernel_result.tool_activity : [],
-          context_status: kernel_result.respond_to?(:context_status) ? kernel_result.context_status : nil,
-          pending_tool_calls: kernel_result.respond_to?(:pending_tool_calls) && kernel_result.pending_tool_calls
+          conversation: kernel_result.conversation,
+          canceled: kernel_result.canceled?,
+          cancellation_reason: kernel_result.cancellation_reason,
+          exhausted: kernel_result.exhausted,
+          tool_activity: kernel_result.tool_activity,
+          context_status: kernel_result.context_status,
+          pending_tool_calls: kernel_result.pending_tool_calls
         )
       end
     end

data/lib/samagotchi/llm/openai_chat.rb

@@ -7,6 +7,7 @@ require_relative "../sampling_settings"
 require_relative "errors"
 require_relative "http"
 require_relative "usage"
+require_relative "utf8_scrub"
 
 module Samagotchi
   module LLM
@@ -220,8 +221,8 @@ module Samagotchi
         SamplingSettings.log_text(body.except(:model, :messages, :stream, :stream_options, :tools, :tool_choice))
       end
 
-      # A String stays a String; an Array of parts passes as given, its text
-      # parts scrubbed like a String.
+      # A String stays a String, an Array of parts an Array; both scrubbed
+      # of invalid UTF-8 (Utf8Scrub).
       def wire_message(message)
         wire = message.to_h.transform_keys(&:to_sym)
         wire[:content] = format_content(wire[:content]) if wire.key?(:content)
@@ -230,22 +231,8 @@ module Samagotchi
 
       def format_content(content)
         return content if content.nil?
-        return content.map { |part| scrub_part(part) } if content.is_a?(Array)
 
-        scrub(content.to_s)
-      end
-
-      def scrub_part(part)
-        return part unless part.is_a?(Hash)
-
-        part.to_h do |key, value|
-          [key, key.to_s == "text" && value.is_a?(String) ? scrub(value) : value]
-        end
-      end
-
-      # Invalid UTF-8 (a tool's garbled output) would make to_json raise.
-      def scrub(text)
-        text.encoding == Encoding::UTF_8 && !text.valid_encoding? ? text.scrub("?") : text
+        Utf8Scrub.call(content.is_a?(Array) ? content : content.to_s)
       end
 
       def chat_once(request, cancel_controller, log_fields)

data/lib/samagotchi/llm/utf8_scrub.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  module LLM
+    # Conversation content (system prompt + tool responses + model output)
+    # can contain invalid UTF-8, e.g. a shell/file op writes a garbled
+    # multibyte sequence (a truncated em-dash, a stray replacement byte).
+    # `JSON#to_json` raises `JSON::GeneratorError` on such input, which would
+    # abort the whole turn, so a request body is scrubbed first: only
+    # offending bytes are replaced with "?", every valid UTF-8 string passes
+    # through untouched. Non-UTF-8 encodings are left alone because
+    # `#to_json` already handles them without raising.
+    module Utf8Scrub
+      module_function
+
+      # +obj+ with every String in it (Array elements, Hash keys and
+      # values, at any depth) scrubbed; anything else as is.
+      def call(obj)
+        case obj
+        when String
+          obj.encoding == Encoding::UTF_8 && !obj.valid_encoding? ? obj.scrub("?") : obj
+        when Array
+          obj.map { |element| call(element) }
+        when Hash
+          obj.each_with_object({}) { |(key, value), memo| memo[call(key)] = call(value) }
+        else
+          obj
+        end
+      end
+    end
+  end
+end

data/lib/samagotchi/log_path.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "config"
+require_relative "paths"
 
 module Samagotchi
   # Where the debug log (DebugLog) goes, for the REPL, the attached terminal
@@ -23,9 +24,7 @@ module Samagotchi
     end
 
     def default_path(env: ENV)
-      xdg = env.fetch("XDG_STATE_HOME", "").to_s.strip
-      base = xdg.empty? ? File.join(Dir.home, ".local", "state") : xdg
-      File.join(base, "samagotchi", FILENAME)
+      File.join(Paths.state_dir(env: env), FILENAME)
     end
   end
 end

data/lib/samagotchi/memory_bundle/index_updater.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 require "fileutils"
 require "digest"
+require_relative "../atomic_file"
 require_relative "../memory_paths"
 module Samagotchi
   module MemoryBundle
@@ -66,19 +67,9 @@ module Samagotchi
           lock.flock(File::LOCK_EX)
           content = File.exist?(index_path) ? File.read(index_path) : nil
           updated = yield content
-          atomic_write(index_path, updated) unless updated.nil?
+          Samagotchi::AtomicFile.write(index_path, updated) unless updated.nil?
         end
       end
-      # Write aside and rename, so a reader never sees a half-written file. The
-      # temp name must not end in .md, or it would be listed as a memory. A
-      # symlinked target is replaced by a regular file (accepted).
-      def self.atomic_write(path, body)
-        tmp_path = "#{path}.#{Process.pid}.#{Thread.current.object_id}.tmp"
-        File.write(tmp_path, body)
-        File.rename(tmp_path, path)
-      ensure
-        FileUtils.rm_f(tmp_path) if tmp_path
-      end
       def self.managed_line(name, scope, byte_count, description)
         line = "- **#{name}** · #{scope} · #{date_str} · #{byte_count}"
         desc = description&.to_s&.strip

data/lib/samagotchi/memory_bundle/installer.rb

@@ -180,10 +180,9 @@ module Samagotchi
             if @upgrade && existing_provenance && File.exist?(dest) && !@force
               prev_meta = existing_provenance[:hooks] ? (existing_provenance[:hooks][basename.to_sym] || existing_provenance[:hooks][basename]) : nil
               if prev_meta
-                prev_sha = (prev_meta[:sha256] || prev_meta["sha256"] || "").to_s.sub(/\Asha256:/, "")
+                prev_sha = prev_meta[:sha256] || prev_meta["sha256"]
                 if File.exist?(dest)
-                  cur_sha = Digest::SHA256.hexdigest(File.read(dest))
-                  if cur_sha != prev_sha && !prev_sha.empty?
+                  if !Provenance.recorded_sha(prev_sha).empty? && !Provenance.sha_matches?(dest, prev_sha)
                     @warnings << "Hook #{basename} was locally modified; overwriting"
                   end
                 end
@@ -441,10 +440,9 @@ module Samagotchi
       # Whether the file on disk is what the previous install wrote: its
       # recorded checksum, else the base snapshot. Unknown counts as edited.
       def installed_unchanged?(target, meta, base_path)
-        current = Digest::SHA256.hexdigest(File.read(target))
-        recorded = meta.is_a?(Hash) ? (meta[:checksum] || meta["checksum"]).to_s.sub(/\Asha256:/, "") : ""
-        return current == recorded unless recorded.empty?
-        File.exist?(base_path) && current == Digest::SHA256.hexdigest(File.read(base_path))
+        recorded = meta.is_a?(Hash) ? meta[:checksum] || meta["checksum"] : nil
+        return Provenance.sha_matches?(target, recorded) unless Provenance.recorded_sha(recorded).empty?
+        File.exist?(base_path) && Provenance.file_sha(target) == Provenance.file_sha(base_path)
       end
 
       def remove_target_index(scope, file_key)

data/lib/samagotchi/memory_bundle/listing.rb

@@ -11,11 +11,15 @@ module Samagotchi
     # each with the shipped version when chi ships a newer one, and the
     # bundles shipped with chi that aren't installed yet. The system bundle
     # is left out of the shipped ones: chi installs and upgrades it itself.
+    # A profile (a meta bundle) that isn't installed lists its members on
+    # its own line, and they aren't listed again.
     module Listing
-      # error is set (and the rest nil) when the provenance manifest.json can't be read.
-      Installed = Struct.new(:name, :version, :scope, :files, :installed_at, :upgrade, :error, keyword_init: true)
-      # source is the name `chi bundle install` takes (the shipped dir's name).
-      Shipped = Struct.new(:name, :source, :version, :description, keyword_init: true)
+      # error is set (and the rest nil) when the provenance manifest.json
+      # can't be read; includes is a profile's recorded members, else nil.
+      Installed = Struct.new(:name, :version, :scope, :files, :installed_at, :upgrade, :error, :includes, keyword_init: true)
+      # source is the name `chi bundle install` takes (the shipped dir's
+      # name); includes is a profile's members ([] for a plain bundle).
+      Shipped = Struct.new(:name, :source, :version, :description, :includes, keyword_init: true)
 
       module_function
 
@@ -28,7 +32,7 @@ module Samagotchi
           next unless File.file?(File.join(dir, source, "manifest.yml"))
           m = Manifest.read(dir: File.join(dir, source))
           next if m.name == SystemBundle::BUNDLE_NAME
-          Shipped.new(name: m.name, source: source, version: m.version, description: m.description)
+          Shipped.new(name: m.name, source: source, version: m.version, description: m.description, includes: m.includes)
         rescue Manifest::ValidationError, Psych::Exception
           nil
         end.sort_by(&:name)
@@ -36,30 +40,33 @@ module Samagotchi
 
       # @return [Array<Installed>] by name; upgrade is the Shipped when it is newer
       def installed(shipped: self.shipped)
-        dir = Provenance.bundles_dir
-        return [] unless File.directory?(dir)
-
         by_name = shipped.to_h { |s| [s.name, s] }
-        Dir.children(dir).reject { |e| e.start_with?(".") }.sort.filter_map do |name|
-          begin
-            data = Provenance.new(name: name).read
-          rescue JSON::ParserError, SystemCallError
-            data = :unreadable
-          end
-          next unless data
-          next Installed.new(name: name, error: "manifest.json unreadable") unless data.is_a?(Hash)
+        Provenance.each_installed.map do |name, data|
+          next Installed.new(name: name, error: "manifest.json unreadable") if data[:error]
 
           ship = by_name[name]
           Installed.new(name: name, version: data[:version], scope: data[:scope],
                         files: (data[:files] || {}).size, installed_at: data[:installed_at],
-                        upgrade: ship && newer?(ship.version, data[:version]) ? ship : nil)
+                        upgrade: ship && newer?(ship.version, data[:version]) ? ship : nil,
+                        includes: data[:includes].is_a?(Array) ? data[:includes].map(&:to_s) : nil)
         end
       end
 
-      # The shipped bundles not installed under their manifest name.
+      # The shipped bundles not installed under their manifest name, a
+      # profile's members folded into it (grouped).
       def available(shipped: self.shipped, installed: self.installed(shipped: shipped))
-        names = installed.map(&:name)
-        shipped.reject { |s| names.include?(s.name) }
+        grouped(shipped, installed.map(&:name))
+      end
+
+      # The shipped bundles not in +installed_names+; a profile among them
+      # keeps only its members not installed, and those aren't listed
+      # again on their own.
+      def grouped(shipped, installed_names)
+        left = shipped.reject { |s| installed_names.include?(s.name) }
+        folded = left.flat_map(&:includes)
+        left.reject { |s| folded.include?(s.name) }.map do |s|
+          s.includes.empty? ? s : s.dup.tap { |d| d.includes = s.includes - installed_names }
+        end
       end
 
       def newer?(candidate, current)

data/lib/samagotchi/memory_bundle/manifest.rb

@@ -25,6 +25,9 @@ module Samagotchi
     #       why: reads PRs     #   optional
     #       hint: brew install gh   # optional
     #     - jq                 #   short form: just the command
+    #   includes: [a, b]       # optional — a profile (meta bundle): the
+    #                          #   shipped bundles it installs; its dir holds
+    #                          #   only manifest.yml (MemoryBundle::Profile)
     class Manifest
       class ValidationError < StandardError; end
 
@@ -32,8 +35,10 @@ module Samagotchi
       PLUGIN_FILE = /\A[A-Za-z0-9_][A-Za-z0-9_.-]*\.rb\z/
       # A need is a plain executable name: no path, no spaces.
       NEED_COMMAND = /\A[A-Za-z0-9][A-Za-z0-9._+-]*\z/
+      # A bundle name, as `chi bundle install <name>` takes a shipped one.
+      BUNDLE_NAME = /\A[A-Za-z0-9][A-Za-z0-9_-]*\z/
 
-      attr_reader :name, :version, :scope, :description, :files, :hooks, :trust_level, :plugin, :requires_chi, :needs
+      attr_reader :name, :version, :scope, :description, :files, :hooks, :trust_level, :plugin, :requires_chi, :needs, :includes
 
       def initialize(path:)
         @path = path
@@ -48,6 +53,12 @@ module Samagotchi
         @plugin = parse_plugin(raw["plugin"])
         @requires_chi = parse_requires_chi(raw["requires_chi"])
         @needs = self.class.parse_needs(raw["needs"])
+        @includes = parse_includes(raw["includes"])
+      end
+
+      # A profile: it installs the bundles in includes instead of files.
+      def meta?
+        !@includes.empty?
       end
 
       def self.read(dir:)
@@ -194,6 +205,26 @@ module Samagotchi
         { file: file, sha256: sha }
       end
 
+      # includes: → the names in order, duplicates dropped; [] when absent.
+      # A meta ships nothing of its own, so files, hooks or a plugin next
+      # to it is a ValidationError.
+      def parse_includes(raw)
+        return [] if raw.nil?
+        raise ValidationError, "includes: must be a list of bundle names" unless raw.is_a?(Array)
+
+        names = raw.map do |item|
+          name = item.to_s.strip
+          raise ValidationError, "includes: #{item.inspect} is not a bundle name" unless name.match?(BUNDLE_NAME)
+
+          name
+        end.uniq
+        if !names.empty? && (!@files.empty? || !@hooks.empty? || @plugin)
+          raise ValidationError, "a bundle with includes: holds only its includes (no files, hooks or plugin)"
+        end
+
+        names
+      end
+
       def parse_requires_chi(raw)
         return nil if raw.nil?
 

data/lib/samagotchi/memory_bundle/profile.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require_relative "installer"
+require_relative "manifest"
+require_relative "provenance"
+require_relative "source"
+require_relative "uninstaller"
+require_relative "../version"
+
+module Samagotchi
+  module MemoryBundle
+    # Profiles: a shipped meta bundle (a dir holding only manifest.yml, with
+    # includes:) installs a set of shipped bundles. Every entry point (chi
+    # bundle install/upgrade/uninstall, chi update, chi bootstrap) goes
+    # through here, and all of them follow one rule:
+    #
+    #   to_install = shipped includes - recorded includes - installed bundles
+    #
+    # The meta's provenance records the members it installed or found
+    # installed, so a member the user uninstalls stays out, re-running is a
+    # no-op, and a bundle new to the profile is the only one installed. A
+    # member this chi is too old for, or one that fails, isn't recorded and
+    # is tried again next time. Members come from the shipped dir, never
+    # from a name lookup, so they stay updatable by chi update. Only a
+    # shipped meta expands: includes: in any other bundle is ignored.
+    module Profile
+      # installed: members installed now; already: members found installed
+      # (recorded, not reinstalled); skipped and failed: name => why.
+      InstallResult = Struct.new(:name, :version, :installed, :already, :skipped, :failed, keyword_init: true) do
+        def failed? = !failed.empty?
+      end
+      # removed: members uninstalled; blocked: name => why; gone: the meta
+      # itself was removed (only once every member is).
+      UninstallResult = Struct.new(:name, :removed, :blocked, :gone, keyword_init: true)
+
+      module_function
+
+      # Whether +dir+ is a meta bundle in the shipped dir.
+      def shipped_meta?(dir, shipped_dir: SourceNormalizer::SHIPPED_DIR)
+        return false unless File.expand_path(File.dirname(dir.to_s)) == File.expand_path(shipped_dir)
+
+        Manifest.read(dir: dir).meta?
+      rescue Manifest::ValidationError, Psych::Exception, SystemCallError
+        false
+      end
+
+      # Whether the installed bundle +name+ (its provenance +data+) is a
+      # meta: it records includes, or it came from chi and chi ships it as
+      # a meta.
+      def installed_meta?(name, data, shipped_dir: SourceNormalizer::SHIPPED_DIR)
+        return false unless data.is_a?(Hash)
+        return true if data[:includes].is_a?(Array)
+
+        data[:source].to_s.match?(SourceNormalizer::SHIPPED_SOURCE) && shipped_meta?(File.join(shipped_dir, name), shipped_dir: shipped_dir)
+      end
+
+      # The members the meta has recorded: none when it isn't installed,
+      # all of +manifest+'s (the shipped meta, nil when chi ships none) when
+      # its provenance has no includes: an unknown record is taken as
+      # everything.
+      def recorded(data, manifest)
+        return [] unless data
+        return manifest&.includes || [] unless data[:includes].is_a?(Array)
+
+        data[:includes].map(&:to_s)
+      end
+
+      def installed_names = Provenance.each_installed.map { |name, _| name }
+
+      # The one rule.
+      def to_install(manifest, data = Provenance.new(name: manifest.name).read, installed: installed_names)
+        manifest.includes - recorded(data, manifest) - installed
+      end
+
+      # Installs the shipped meta at +dir+: its to_install members from the
+      # shipped dir, then its provenance (the recorded members plus the
+      # ones installed now or found installed). Never raises for a member.
+      # @return [InstallResult]
+      def install(dir, shipped_dir: SourceNormalizer::SHIPPED_DIR, chi_version: Samagotchi::VERSION, dry_run: false, force: false)
+        manifest = Manifest.read(dir: dir)
+        data = Provenance.new(name: manifest.name).read
+        was = recorded(data, manifest)
+        installed = installed_names
+        result = InstallResult.new(name: manifest.name, version: manifest.version, installed: [],
+                                   already: (manifest.includes - was) & installed, skipped: {}, failed: {})
+
+        to_install(manifest, data, installed: installed).each do |member|
+          install_member(member, shipped_dir, chi_version, dry_run, force, result)
+        end
+        return result if dry_run
+
+        now = was | result.installed | result.already
+        includes = (manifest.includes & now) + (now - manifest.includes)
+        # Nothing new: the record stays as it is (installed_at too).
+        return result if data && data[:version] == manifest.version && data[:source] == dir && data[:includes] == includes
+
+        Provenance.new(name: manifest.name).write(
+          files: {}, scope: "system", version: manifest.version, source_path: dir,
+          trust_level: manifest.trust_level, requires_chi: manifest.requires_chi, includes: includes
+        )
+        result
+      end
+
+      def install_member(member, shipped_dir, chi_version, dry_run, force, result)
+        member_dir = File.join(shipped_dir, member)
+        failure = Manifest.requires_chi_failure(Manifest.read(dir: member_dir).requires_chi, chi_version)
+        return result.skipped[member] = failure if failure
+        return result.installed << member if dry_run
+
+        Installer.new(source: member_dir, name: member, scope: "system", force: force, strict: true).run
+        result.installed << member
+      rescue StandardError => e
+        result.failed[member] = e.message.lines.first.to_s.strip
+      end
+      private_class_method :install_member
+
+      # Uninstalls each recorded member still installed, then the meta. A
+      # member that won't go (an edited .md file, without +force+) is
+      # reported and the rest carry on; the meta then stays, still
+      # recording it.
+      # @return [UninstallResult]
+      # @raise [Uninstaller::UninstallError] when +name+ isn't installed
+      def uninstall(name, shipped_dir: SourceNormalizer::SHIPPED_DIR, force: false)
+        data = Provenance.new(name: name).read
+        raise Uninstaller::UninstallError, "Bundle '#{name}' is not installed" unless data
+
+        shipped = File.join(shipped_dir, name)
+        manifest = File.file?(File.join(shipped, "manifest.yml")) ? Manifest.read(dir: shipped) : nil
+        members = recorded(data, manifest)
+        result = UninstallResult.new(name: name, removed: [], blocked: {}, gone: false)
+        (members & installed_names).each do |member|
+          Uninstaller.new(name: member, force: force).run
+          result.removed << member
+        rescue Uninstaller::UninstallError => e
+          result.blocked[member] = e.message
+        end
+        return result unless result.blocked.empty?
+
+        Uninstaller.new(name: name, force: force).run
+        result.gone = true
+        result
+      end
+    end
+  end
+end

data/lib/samagotchi/memory_bundle/provenance.rb

@@ -4,6 +4,7 @@ require "json"
 require "digest"
 require "date"
 require "fileutils"
+require_relative "../atomic_file"
 require_relative "../memory_paths"
 
 module Samagotchi
@@ -53,65 +54,54 @@ module Samagotchi
         File.join(@bundle_dir, "bases", "plugin", file.to_s)
       end
 
-      # Yields [name, data] for each installed bundle with a plugin, by
-      # name. A manifest that doesn't parse is yielded as {error:} when its
-      # bundle has a plugin/ dir.
-      def self.each_installed_with_plugin
-        return enum_for(:each_installed_with_plugin) unless block_given?
-        dir = bundles_dir
+      # Yields [name, data] for each installed bundle (a dir under
+      # bundles_dir holding a manifest.json, dot dirs aside), by name. data
+      # is the manifest with symbol keys, or {error:} when it doesn't parse
+      # or isn't an object; the rest still come.
+      #
+      # With holding: (:hooks, :guardrails or :plugin) only the bundles
+      # whose manifest has a non-empty mapping under that key come, and a
+      # manifest that doesn't parse comes as {error:} only when its bundle
+      # has that dir (hooks/, guardrails/, plugin/): what it would load
+      # can't be checked. One that isn't an object is skipped there.
+      # @param dir [String] the bundles dir (bundles_dir by default)
+      def self.each_installed(holding: nil, dir: bundles_dir)
+        return enum_for(:each_installed, holding: holding, dir: dir) unless block_given?
         return unless Dir.exist?(dir)
-        Dir[File.join(dir, "*", "manifest.json")].sort.each do |mjson|
-          name = File.basename(File.dirname(mjson))
+
+        Dir.children(dir).reject { |e| e.start_with?(".") }.sort.each do |name|
+          mjson = File.join(dir, name, "manifest.json")
+          next unless File.exist?(mjson)
+
           begin
             data = JSON.parse(File.read(mjson), symbolize_names: true)
           rescue JSON::ParserError, SystemCallError => e
-            yield name, { error: "manifest.json is unreadable: #{e.message}" } if Dir.exist?(File.join(File.dirname(mjson), "plugin"))
+            yield name, { error: "manifest.json is unreadable: #{e.message}" } if holding.nil? || Dir.exist?(File.join(dir, name, holding.to_s))
             next
           end
-          next unless data.is_a?(Hash) && data[:plugin].is_a?(Hash)
+          if holding
+            next unless data.is_a?(Hash) && data[holding].is_a?(Hash) && !data[holding].empty?
+          elsif !data.is_a?(Hash)
+            data = { error: "manifest.json is not an object" }
+          end
           yield name, data
         end
       end
 
-      # Yields [name, data] for each installed bundle with guardrail rule
-      # files, by name. A manifest that doesn't parse is yielded as
-      # {error:} when its bundle has a guardrails/ dir (its rules can't be
-      # checked), and skipped otherwise.
-      def self.each_installed_with_guardrails
-        return enum_for(:each_installed_with_guardrails) unless block_given?
-        dir = bundles_dir
-        return unless Dir.exist?(dir)
-        Dir[File.join(dir, "*", "manifest.json")].sort.each do |mjson|
-          name = File.basename(File.dirname(mjson))
-          begin
-            data = JSON.parse(File.read(mjson), symbolize_names: true)
-          rescue JSON::ParserError, SystemCallError => e
-            yield name, { error: "manifest.json is unreadable: #{e.message}" } if Dir.exist?(File.join(File.dirname(mjson), "guardrails"))
-            next
-          end
-          next unless data.is_a?(Hash) && data[:guardrails].is_a?(Hash) && !data[:guardrails].empty?
-          yield name, data
-        end
+      # The hex digest a manifest records, in either of its formats:
+      # "sha256:<hex>" (hooks, rules, the plugin) or bare <hex> (a memory
+      # file's checksum:). "" when none is recorded.
+      def self.recorded_sha(value)
+        value.to_s.delete_prefix("sha256:")
       end
 
-      # Yields [name, data] for each installed bundle with hooks, by name.
-      # A manifest that doesn't parse is yielded as {error:} when its
-      # bundle has a hooks/ dir, and skipped otherwise; the rest still load.
-      def self.each_installed_holding_hooks
-        return enum_for(:each_installed_holding_hooks) unless block_given?
-        dir = self.bundles_dir
-        return unless Dir.exist?(dir)
-        Dir[File.join(dir, "*", "manifest.json")].sort.each do |mjson|
-          name = File.basename(File.dirname(mjson))
-          begin
-            data = JSON.parse(File.read(mjson), symbolize_names: true)
-          rescue JSON::ParserError, SystemCallError => e
-            yield name, { error: "manifest.json is unreadable: #{e.message}" } if Dir.exist?(File.join(File.dirname(mjson), "hooks"))
-            next
-          end
-          next unless data.is_a?(Hash) && data[:hooks].is_a?(Hash) && !data[:hooks].empty?
-          yield name, data
-        end
+      def self.file_sha(path)
+        Digest::SHA256.hexdigest(File.binread(path))
+      end
+
+      # Whether the file's content is the one recorded (either format).
+      def self.sha_matches?(path, recorded)
+        file_sha(path) == recorded_sha(recorded)
       end
 
       # Writes provenance for an installation: merges into existing manifest.json
@@ -127,8 +117,10 @@ module Samagotchi
       # @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 includes [Array<String>, nil] a profile's recorded members
+      #   (MemoryBundle::Profile); nil for a plain bundle
       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: [])
+                guardrails_files: {}, plugin_file: nil, requires_chi: nil, needs: nil, conflicts: [], includes: nil)
         FileUtils.mkdir_p(@bundle_dir)
         bases_dir = File.join(@bundle_dir, "bases")
         FileUtils.mkdir_p(bases_dir)
@@ -237,6 +229,7 @@ module Samagotchi
         end
         manifest_data["requires_chi"] = requires_chi.to_s if requires_chi && !requires_chi.to_s.empty?
         manifest_data["needs"] = needs.map { |n| n.transform_keys(&:to_s).compact } if needs.is_a?(Array) && !needs.empty?
+        manifest_data["includes"] = includes.map(&:to_s) if includes.is_a?(Array)
 
         write_manifest(manifest_data)
       end
@@ -274,11 +267,7 @@ module Samagotchi
       # chi start) never parses a truncated manifest.json.
       def write_manifest(manifest_data)
         manifest_path = File.join(@bundle_dir, "manifest.json")
-        tmp_path = "#{manifest_path}.#{Process.pid}.tmp"
-        File.write(tmp_path, JSON.pretty_generate(manifest_data))
-        File.rename(tmp_path, manifest_path)
-      ensure
-        FileUtils.rm_f(tmp_path) if tmp_path
+        AtomicFile.write(manifest_path, JSON.pretty_generate(manifest_data))
       end
       private :write_manifest