samagotchi 0.53.0 → 0.55.0

data/lib/samagotchi/memory_bundle/listing.rb

@@ -43,14 +43,14 @@ module Samagotchi
       # @return [Array<Installed>] by name; upgrade is the Shipped when it is newer
       def installed(shipped: self.shipped)
         by_name = shipped.to_h { |s| [s.name, s] }
-        Provenance.each_installed.map do |name, data|
-          next Installed.new(name: name, error: "manifest.json unreadable") if data[:error]
+        Provenance.each_installed.map do |name, bundle|
+          next Installed.new(name: name, error: "manifest.json unreadable") if bundle.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,
-                        includes: data[:includes].is_a?(Array) ? data[:includes].map(&:to_s) : nil)
+          Installed.new(name: name, version: bundle.version, scope: bundle.scope,
+                        files: bundle.files.size, installed_at: bundle.installed_at,
+                        upgrade: ship && newer?(ship.version, bundle.version) ? ship : nil,
+                        includes: bundle.includes)
         end
       end
 

data/lib/samagotchi/memory_bundle/manifest.rb

@@ -99,9 +99,11 @@ module Samagotchi
         raw.start_with?("sha256:") ? raw[7..] : raw
       end
 
-      # Returns sha256 hex for a hook basename (e.g. "guardrails.rb").
+      # Returns sha256 hex for a hook basename (e.g. "guardrails.rb"), nil
+      # when it declares none (nothing to verify).
       def checksum_for_hook(basename)
-        @hooks[basename]&.hex
+        hex = @hooks[basename]&.hex
+        hex unless hex.nil? || hex.empty?
       end
 
       # @return [String, nil] the plugin's sha256 hex, "sha256:" stripped

data/lib/samagotchi/memory_bundle/plugin_ref.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  module MemoryBundle
+    # The plugin an installed bundle's record (manifest.json) names: its
+    # file under plugin/ and the sha256 recorded at install ("" when none
+    # is; either "sha256:<hex>" or a bare hex, Provenance.recorded_sha
+    # reads both).
+    PluginRef = Data.define(:file, :sha256) do
+      def initialize(file:, sha256: "")
+        super
+      end
+
+      # @param raw [Hash, PluginRef, nil] the record's plugin: mapping
+      #   (symbol or string keys)
+      # @return [PluginRef, nil] nil when there is none or it names no file
+      def self.parse(raw)
+        return raw if raw.is_a?(PluginRef)
+        return nil unless raw.is_a?(Hash)
+
+        h = raw.transform_keys(&:to_s)
+        file = h["file"].to_s
+        file.empty? ? nil : new(file: file, sha256: h["sha256"].to_s)
+      end
+    end
+  end
+end

data/lib/samagotchi/memory_bundle/profile.rb

@@ -46,32 +46,32 @@ module Samagotchi
         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)
+      # Whether the installed bundle +name+ (its record +bundle+, an
+      # InstalledBundle or nil) is a meta: it records includes, or it came
+      # from chi and chi ships it as a meta.
+      def installed_meta?(name, bundle, shipped_dir: SourceNormalizer::SHIPPED_DIR)
+        return false unless bundle
+        return true if bundle.profile?
+
+        bundle.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)
+      def recorded(bundle, manifest)
+        return [] unless bundle
+        return manifest&.includes || [] unless bundle.profile?
 
-        data[:includes].map(&:to_s)
+        bundle.includes
       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
+      def to_install(manifest, bundle = Provenance.new(name: manifest.name).record, installed: installed_names)
+        manifest.includes - recorded(bundle, manifest) - installed
       end
 
       # Installs the shipped meta at +dir+: its to_install members from the
@@ -80,13 +80,13 @@ module Samagotchi
       # @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)
+        bundle = Provenance.new(name: manifest.name).record
+        was = recorded(bundle, 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|
+        to_install(manifest, bundle, installed: installed).each do |member|
           install_member(member, shipped_dir, chi_version, dry_run, force, result)
         end
         return result if dry_run
@@ -94,7 +94,7 @@ module Samagotchi
         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
+        return result if bundle && bundle.version == manifest.version && bundle.source == dir && bundle.includes == includes
 
         Provenance.new(name: manifest.name).write(
           files: {}, scope: "system", version: manifest.version, source_path: dir,
@@ -123,12 +123,12 @@ module Samagotchi
       # @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
+        bundle = Provenance.new(name: name).record
+        raise Uninstaller::UninstallError, "Bundle '#{name}' is not installed" unless bundle
 
         shipped = File.join(shipped_dir, name)
         manifest = File.file?(File.join(shipped, "manifest.yml")) ? Manifest.read(dir: shipped) : nil
-        members = recorded(data, manifest)
+        members = recorded(bundle, manifest)
         result = UninstallResult.new(name: name, removed: [], blocked: {}, gone: false, trash: {}, warnings: [])
         (members & installed_names).each do |member|
           uninstaller = Uninstaller.new(name: member, force: force)

data/lib/samagotchi/memory_bundle/provenance.rb

@@ -7,6 +7,7 @@ require "fileutils"
 require_relative "../atomic_file"
 require_relative "../memory_paths"
 require_relative "bundle_hook"
+require_relative "installed_bundle"
 
 module Samagotchi
   module MemoryBundle
@@ -47,9 +48,10 @@ module Samagotchi
       end
 
       # The plugin file as installed, or nil when the bundle has none.
-      def plugin_path(data = read)
-        file = data && data[:plugin].is_a?(Hash) ? data[:plugin][:file].to_s : ""
-        file.empty? ? nil : File.join(plugin_dir, file)
+      # @param bundle [InstalledBundle, nil] its record (read when not given)
+      def plugin_path(bundle = record)
+        file = bundle&.plugin&.file
+        file ? File.join(plugin_dir, file) : nil
       end
 
       # The plugin's base snapshot (bases/plugin/<file>), for bundle diff.
@@ -57,14 +59,14 @@ module Samagotchi
         File.join(@bundle_dir, "bases", "plugin", file.to_s)
       end
 
-      # 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.
+      # Yields [name, bundle] for each installed bundle (a dir under
+      # bundles_dir holding a manifest.json, dot dirs aside), by name. bundle
+      # is its InstalledBundle, one with error set when manifest.json 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
+      # manifest that doesn't parse comes (with 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)
@@ -79,15 +81,14 @@ module Samagotchi
           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 holding.nil? || Dir.exist?(File.join(dir, name, holding.to_s))
+            if holding.nil? || Dir.exist?(File.join(dir, name, holding.to_s))
+              yield name, InstalledBundle.unreadable(name, "manifest.json is unreadable: #{e.message}")
+            end
             next
           end
-          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
+          next if holding && !(data.is_a?(Hash) && data[holding].is_a?(Hash) && !data[holding].empty?)
+
+          yield name, InstalledBundle.parse(name, data)
         end
       end
 
@@ -96,10 +97,9 @@ module Samagotchi
       # A project-scoped record doesn't say which project: one from another
       # repo counts too, which errs on keeping the file.
       def self.claimants(file_key, scope:, except: nil, dir: bundles_dir)
-        each_installed(dir: dir).filter_map do |name, data|
-          next if name == except || data[:error]
-          next unless (data[:scope].to_s.empty? ? "system" : data[:scope].to_s) == scope.to_s
-          next unless data[:files].is_a?(Hash) && data[:files].keys.map(&:to_s).include?(file_key.to_s)
+        each_installed(dir: dir).filter_map do |name, bundle|
+          next if name == except || bundle.error?
+          next unless bundle.effective_scope == scope.to_s && bundle.owns?(file_key)
 
           name
         end
@@ -146,11 +146,10 @@ module Samagotchi
         bases_dir = File.join(@bundle_dir, "bases")
         FileUtils.mkdir_p(bases_dir)
 
-        # Read existing manifest to merge file entries and find stale files.
-        # read symbolizes keys; stringify them so incoming string keys replace
-        # them instead of sitting next to them as duplicates.
-        existing = read
-        merged_entries = existing && existing[:files] ? existing[:files].transform_keys(&:to_s) : {}
+        # The existing record: its file entries merge with these, and its
+        # files and hooks not in this install are stale.
+        existing = record
+        merged_entries = existing ? existing.files.dup : {}
 
         files.each do |file_key, file_path|
           content = File.read(file_path)
@@ -163,10 +162,9 @@ module Samagotchi
         end
 
         # Prune stale base snapshots for files no longer in the bundle.
-        if existing && existing[:files]
-          existing[:files].keys.each do |old_key|
-            old_key_str = old_key.to_s
-            next if files.key?(old_key_str) || files.key?(old_key)
+        if existing
+          existing.files.each_key do |old_key_str|
+            next if files.key?(old_key_str) || files.key?(old_key_str.to_sym)
 
             old_base = File.join(bases_dir, old_key_str)
             FileUtils.rm_f(old_base)
@@ -176,8 +174,6 @@ module Samagotchi
 
         # Hooks provenance: persist metadata and base snapshots for hooks
         hooks_map = {}
-        # existing hooks for pruning
-        existing_hooks = existing && existing[:hooks] ? existing[:hooks] : {}
         # Incoming hooks: basename => BundleHook (or its metadata hash)
         normalized_hooks = {}
         if hooks.is_a?(Hash)
@@ -189,14 +185,8 @@ module Samagotchi
           end
         end
         # Prune stale hook bases
-        if existing_hooks.is_a?(Hash)
-          existing_hooks.keys.each do |old_key|
-            old_key_str = old_key.to_s
-            unless normalized_hooks.key?(old_key_str) || normalized_hooks.key?(old_key_str.to_sym)
-              old_base = File.join(bases_dir, old_key_str)
-              FileUtils.rm_f(old_base)
-            end
-          end
+        existing&.hooks&.each_key do |old_key_str|
+          FileUtils.rm_f(File.join(bases_dir, old_key_str)) unless normalized_hooks.key?(old_key_str)
         end
         # Save base snapshots for hooks where a file path was provided, and
         # record the sha256 of the installed file itself: the load-time check
@@ -276,7 +266,15 @@ module Samagotchi
         write_manifest(raw)
       end
 
-      # Reads provenance data (returns nil if not installed).
+      # The installed bundle's record, nil when it isn't installed.
+      # @return [InstalledBundle, nil]
+      # @raise [JSON::ParserError] manifest.json doesn't parse
+      def record
+        InstalledBundle.read(@name, File.join(@bundle_dir, "manifest.json"))
+      end
+
+      # manifest.json as it is on disk, symbol keys (nil if not installed).
+      # Readers take #record.
       def read
         manifest_path = File.join(@bundle_dir, "manifest.json")
         return nil unless File.exist?(manifest_path)
@@ -299,7 +297,7 @@ module Samagotchi
 
       # Checks whether the bundle is installed.
       def installed?
-        read.nil? ? false : true
+        !record.nil?
       end
     end
   end

data/lib/samagotchi/memory_bundle/shipped_update.rb

@@ -45,8 +45,8 @@ module Samagotchi
       # @return [Array<Row>] by name
       def plan(shipped_dir: SourceNormalizer::SHIPPED_DIR, chi_version: Samagotchi::VERSION)
         shipped = Listing.shipped(dir: shipped_dir).to_h { |s| [s.name, s] }
-        installed.map do |name, data|
-          plan_row(name, data, shipped[name], shipped_dir, chi_version)
+        installed.map do |name, bundle|
+          plan_row(name, bundle, shipped[name], shipped_dir, chi_version)
         end
       end
 
@@ -88,24 +88,24 @@ module Samagotchi
         end
       end
 
-      # [name, data] for each installed bundle but the system one, by name.
+      # [name, InstalledBundle] for each installed bundle but the system one, by name.
       def installed
         Provenance.each_installed.reject { |name, _| name == SystemBundle::BUNDLE_NAME }
       end
 
-      def plan_row(name, data, ship, shipped_dir, chi_version)
+      def plan_row(name, bundle, ship, shipped_dir, chi_version)
         row = Row.new(name: name, kept: [], replaced: [])
-        return skip(row, "manifest.json unreadable") if data[:error]
+        return skip(row, "manifest.json unreadable") if bundle.error?
 
-        row.from = data[:version].to_s
-        row.scope = data[:scope].to_s.empty? ? "system" : data[:scope].to_s
-        return skip(row, "not from chi") unless ship && data[:source].to_s.match?(SourceNormalizer::SHIPPED_SOURCE)
+        row.from = bundle.version.to_s
+        row.scope = bundle.effective_scope
+        return skip(row, "not from chi") unless ship && bundle.source.to_s.match?(SourceNormalizer::SHIPPED_SOURCE)
 
         row.to = ship.version.to_s
         return skip(row, "newer than shipped: left") if Listing.newer?(row.from, row.to)
 
         row.source_dir = File.join(shipped_dir, ship.source)
-        return profile_row(row, data, shipped_dir, chi_version) if Profile.shipped_meta?(row.source_dir, shipped_dir: shipped_dir)
+        return profile_row(row, bundle, shipped_dir, chi_version) if Profile.shipped_meta?(row.source_dir, shipped_dir: shipped_dir)
         return row.tap { |r| r.status = :up_to_date; r.to = nil } unless Listing.newer?(row.to, row.from)
 
         manifest = Manifest.read(dir: row.source_dir)
@@ -115,20 +115,20 @@ module Samagotchi
         return skip(row, "project scope: chi bundle upgrade #{ship.source} in the project") if row.scope == "project"
         return skip(row, "unknown scope #{row.scope}: upgrade chi or reinstall") unless MemoryPaths.scope_dir(row.scope)
 
-        row.kept = conflicts(row, data)
-        row.replaced = edited_executables(name, data)
+        row.kept = conflicts(row, bundle)
+        row.replaced = edited_executables(name, bundle)
         row.status = :would_update
         row
       end
 
-      def profile_row(row, data, shipped_dir, chi_version)
+      def profile_row(row, bundle, shipped_dir, chi_version)
         manifest = Manifest.read(dir: row.source_dir)
         newer = Listing.newer?(row.to, row.from)
         if newer && Manifest.requires_chi_failure(manifest.requires_chi, chi_version)
           return skip(row, "needs chi #{manifest.requires_chi}", keep_to: true)
         end
 
-        row.adds = Profile.to_install(manifest, data).reject do |member|
+        row.adds = Profile.to_install(manifest, bundle).reject do |member|
           Manifest.requires_chi_failure(Manifest.read(dir: File.join(shipped_dir, member)).requires_chi, chi_version)
         rescue Manifest::ValidationError, Psych::Exception
           false # apply reports it failing
@@ -147,12 +147,10 @@ module Samagotchi
 
       # The bundle's .md files whose local edits conflict with the shipped
       # version (a same-name file it didn't install is skipped, not merged).
-      def conflicts(row, data)
+      def conflicts(row, bundle)
         provenance = Provenance.new(name: row.name)
         target_dir = MemoryPaths.scope_dir!(row.scope)
-        return [] unless data[:files].is_a?(Hash)
-
-        owned = data[:files].keys.map(&:to_s)
+        owned = bundle.files.keys
         (Dir.glob(File.join(row.source_dir, "*.md")).map { |f| File.basename(f) }.sort & owned).select do |key|
           Merger.classify(base_path: provenance.base_path(key), current_path: File.join(target_dir, key),
                           incoming_path: File.join(row.source_dir, key)) == :conflict
@@ -161,22 +159,22 @@ module Samagotchi
 
       # Installed hooks, rules and the plugin whose sha differs from the
       # recorded one (they didn't load), as hooks/F, guardrails/F, plugin/F.
-      def edited_executables(name, data)
+      def edited_executables(name, bundle)
         provenance = Provenance.new(name: name)
         edited = []
-        (data[:hooks] || {}).each do |file, meta|
-          edited << "hooks/#{file}" if edited?(File.join(provenance.hooks_dir, file.to_s), meta)
+        bundle.hooks.each do |file, hook|
+          edited << "hooks/#{file}" if edited?(File.join(provenance.hooks_dir, file), hook.sha256)
         end
-        (data[:guardrails] || {}).each do |file, meta|
-          edited << "guardrails/#{file}" if edited?(File.join(provenance.guardrails_dir, file.to_s), meta)
+        bundle.guardrails.each do |file, sha|
+          edited << "guardrails/#{file}" if edited?(File.join(provenance.guardrails_dir, file), sha)
         end
-        plugin = provenance.plugin_path(data)
-        edited << "plugin/#{File.basename(plugin)}" if plugin && edited?(plugin, data[:plugin])
+        plugin = provenance.plugin_path(bundle)
+        edited << "plugin/#{File.basename(plugin)}" if plugin && edited?(plugin, bundle.plugin.sha256)
         edited
       end
 
-      def edited?(path, meta)
-        recorded = meta.is_a?(Hash) ? meta[:sha256] : nil
+      # Whether the file differs from its recorded sha (none recorded: no).
+      def edited?(path, recorded)
         return false if Provenance.recorded_sha(recorded).empty? || !File.file?(path)
 
         !Provenance.sha_matches?(path, recorded)

data/lib/samagotchi/memory_bundle/status.rb

@@ -17,30 +17,28 @@ module Samagotchi
       # unchecked (no disk reads, nothing counted as missing).
       def self.bundle_status(name, scope_override: nil)
         provenance = Provenance.new(name: name)
-        data = provenance.read
-        return nil unless data
+        bundle = provenance.record
+        return nil unless bundle
 
-        raw_scope = scope_override || data[:scope]&.to_s
-        scope = raw_scope.nil? || raw_scope.strip.empty? ? "system" : raw_scope
+        scope = (scope_override ? bundle.with(scope: scope_override) : bundle).effective_scope
         target_dir = MemoryPaths.scope_dir(scope)
-        files = data[:files] || {}
+        files = bundle.files
         details = {}
-        files.each do |file_key, meta|
-          file_key_str = file_key.to_s
+        files.each do |file_key_str, meta|
           next details[file_key_str] = unchecked_file(meta) unless target_dir
 
           target_path = File.join(target_dir, file_key_str)
           base_path = provenance.base_path(file_key_str)
-          stored_checksum = meta[:checksum] || meta["checksum"]
+          stored_checksum = meta[:checksum]
           current_checksum = File.exist?(target_path) ? Digest::SHA256.hexdigest(File.read(target_path)) : nil
           base_checksum = File.exist?(base_path) ? Digest::SHA256.hexdigest(File.read(base_path)) : nil
           modified = base_checksum && current_checksum && base_checksum != current_checksum
           missing = !File.exist?(target_path)
           # A model overlay has no index line (Installer#note_overlay).
-          overlay = ModelOverlay.bundle_overlay?(file_key_str, bundle_files: files.keys.map(&:to_s), target_dir: target_dir)
+          overlay = ModelOverlay.bundle_overlay?(file_key_str, bundle_files: files.keys, target_dir: target_dir)
           index_present = overlay ? nil : index_has_entry?(scope, file_key_str)
           details[file_key_str] = {
-            conflict: meta.is_a?(Hash) && meta[:conflict] == true,
+            conflict: meta[:conflict] == true,
             stored_checksum: stored_checksum,
             current_checksum: current_checksum,
             base_checksum: base_checksum,
@@ -52,23 +50,23 @@ module Samagotchi
             base_path: base_path
           }
         end
-        { provenance: data, scope: scope, scope_error: target_dir ? nil : "unknown scope: #{scope}",
-          target_dir: target_dir, files: details, plugin: plugin_status(provenance, data),
-          hooks_requires_failure: hooks_requires_failure(data), needs: needs_status(data) }
+        { provenance: bundle, scope: scope, scope_error: target_dir ? nil : "unknown scope: #{scope}",
+          target_dir: target_dir, files: details, plugin: plugin_status(provenance, bundle),
+          hooks_requires_failure: hooks_requires_failure(bundle), needs: needs_status(bundle) }
       end
 
       # Why none of the bundle's hooks load (this chi doesn't meet its
       # requires_chi, Hooks::BundleLoader), or nil: it has no hooks or meets it.
-      def self.hooks_requires_failure(data)
-        return nil if (data[:hooks] || {}).empty?
+      def self.hooks_requires_failure(bundle)
+        return nil if bundle.hooks.empty?
 
-        Manifest.requires_chi_failure(data[:requires_chi], Samagotchi::VERSION)
+        Manifest.requires_chi_failure(bundle.requires_chi, Samagotchi::VERSION)
       end
 
       # The stored needs, each with found: from this process's PATH (the
       # shell's; a worker's PATH can differ, see docs/memory.md).
-      def self.needs_status(data, path: ENV["PATH"])
-        Manifest.parse_needs(data[:needs]).map do |need|
+      def self.needs_status(bundle, path: ENV["PATH"])
+        Manifest.parse_needs(bundle.needs).map do |need|
           need.merge(found: BundleNeeds.found?(need[:command], path: path))
         end
       rescue Manifest::ValidationError
@@ -86,20 +84,20 @@ module Samagotchi
       # The installed plugin: {file:, path:, state:, requires_chi:,
       # requires_failure:}; state is "ok", "modified" (its sha256 differs
       # from the installed one: it won't load) or "missing". nil without one.
-      def self.plugin_status(provenance, data)
-        path = provenance.plugin_path(data)
+      def self.plugin_status(provenance, bundle)
+        path = provenance.plugin_path(bundle)
         return nil unless path
 
         state = if !File.file?(path) then "missing"
-                elsif Provenance.sha_matches?(path, data[:plugin][:sha256]) then "ok"
+                elsif Provenance.sha_matches?(path, bundle.plugin.sha256) then "ok"
                 else "modified"
                 end
-        { file: File.basename(path), path: path, state: state, requires_chi: data[:requires_chi],
-          requires_failure: Manifest.requires_chi_failure(data[:requires_chi], Samagotchi::VERSION) }
+        { file: File.basename(path), path: path, state: state, requires_chi: bundle.requires_chi,
+          requires_failure: Manifest.requires_chi_failure(bundle.requires_chi, Samagotchi::VERSION) }
       end
 
       def self.unchecked_file(meta)
-        { conflict: meta.is_a?(Hash) && meta[:conflict] == true, stored_checksum: meta.is_a?(Hash) ? meta[:checksum] || meta["checksum"] : nil,
+        { conflict: meta[:conflict] == true, stored_checksum: meta[:checksum],
           unchecked: true, modified: false, missing: false, index_present: nil, overlay: false }
       end
       private_class_method :unchecked_file

data/lib/samagotchi/memory_bundle/system_bundle.rb

@@ -72,10 +72,10 @@ module Samagotchi
         to = gem_manifest.version.to_s
 
         with_lock do
-          data = Provenance.new(name: BUNDLE_NAME).read
-          from = data && data[:version].to_s
+          bundle = Provenance.new(name: BUNDLE_NAME).record
+          from = bundle&.version.to_s
 
-          if data.nil?
+          if bundle.nil?
             dry_run ? result(:installed, to: to) : install_fresh(to)
           elsif installed_newer?(from, to)
             # Running an older checkout/gem: never downgrade the user's system memories
@@ -174,8 +174,7 @@ module Samagotchi
       # here and changed in the shipped bundle (a dry run's kept).
       def conflicting(gem_manifest)
         provenance = Provenance.new(name: BUNDLE_NAME)
-        owned = (provenance.read || {})[:files]
-        owned = owned.is_a?(Hash) ? owned.keys.map(&:to_s) : []
+        owned = provenance.record&.files&.keys || []
         (gem_manifest.files.keys.map(&:to_s).sort & owned).select do |key|
           Merger.classify(base_path: provenance.base_path(key), current_path: File.join(MemoryPaths.system_dir, key),
                           incoming_path: File.join(GEM_BUNDLE_DIR, key)) == :conflict

data/lib/samagotchi/memory_bundle/uninstaller.rb

@@ -33,17 +33,15 @@ module Samagotchi
 
       def run
         provenance = Provenance.new(name: @name)
-        data = provenance.read
-        raise UninstallError, "Bundle '#{@name}' is not installed" unless data
+        bundle = provenance.record
+        raise UninstallError, "Bundle '#{@name}' is not installed" unless bundle
 
-        # Determine scope from flag or provenance
-        cli_scope = @scope.to_s.strip.empty? ? nil : @scope
-        raw = cli_scope || data[:scope]&.to_s
-        target_scope = raw.nil? || raw.strip.empty? ? "system" : raw
+        # The scope from the flag, else the record's
+        target_scope = @scope.to_s.strip.empty? ? bundle.effective_scope : @scope
         target_dir = MemoryPaths.scope_dir(target_scope) or raise UninstallError, "invalid scope: #{target_scope}"
 
-        files = data[:files] || {}
-        hooks = data[:hooks] || {}
+        files = bundle.files
+        hooks = bundle.hooks
         if files.empty? && hooks.empty?
           # No file list, just remove provenance
           FileUtils.rm_rf(provenance.bundle_dir)
@@ -99,7 +97,7 @@ module Samagotchi
         # ── Hooks removal (bundle-owned) ──────────────────────────
         # Hooks are stored under <bundle_dir>/hooks/ and are not part of the index.
         # Explicit removal for intent; the final rm_rf sweeps it anyway.
-        if hooks.is_a?(Hash) && !hooks.empty?
+        if hooks.any?
           hooks_dir = provenance.hooks_dir
           hooks.each do |hook_key, _meta|
             hook_key_str = hook_key.to_s
@@ -117,7 +115,7 @@ module Samagotchi
           FileUtils.rm_rf(provenance.hooks_dir)
         end
 
-        plugin_path = provenance.plugin_path(data)
+        plugin_path = provenance.plugin_path(bundle)
         @removed_files << "plugin/#{File.basename(plugin_path)}" if plugin_path && File.exist?(plugin_path)
         FileUtils.rm_rf(provenance.bundle_dir)
         true

data/lib/samagotchi/plugin/loader.rb

@@ -44,8 +44,8 @@ module Samagotchi
       # @return [Array<String>] the bundles whose plugin loaded
       def load_installed(registries, failures: nil, settings: {})
         loaded = []
-        MemoryBundle::Provenance.each_installed(holding: :plugin) do |bundle_name, data|
-          ok = load_bundle(bundle_name, data, registries, failures: failures, settings: settings[bundle_name.to_s] || {})
+        MemoryBundle::Provenance.each_installed(holding: :plugin) do |bundle_name, bundle|
+          ok = load_bundle(bundle_name, bundle, registries, failures: failures, settings: settings[bundle_name.to_s] || {})
           loaded << bundle_name if ok
         end
         loaded
@@ -56,10 +56,10 @@ module Samagotchi
       end
 
       # @return [Boolean] whether the plugin loaded
-      def load_bundle(bundle_name, data, registries, failures: nil, settings: {})
-        file = MemoryBundle::Provenance.new(name: bundle_name).plugin_path(data) unless data[:error]
+      def load_bundle(bundle_name, bundle, registries, failures: nil, settings: {})
+        file = MemoryBundle::Provenance.new(name: bundle_name).plugin_path(bundle) unless bundle.error?
         basename = file ? File.basename(file) : "plugin"
-        reason = data[:error] || unloadable_reason(file, data)
+        reason = bundle.error || unloadable_reason(file, bundle)
         return failed(bundle_name, basename, reason, failures) if reason
 
         api = nil
@@ -82,12 +82,12 @@ module Samagotchi
       def label(bundle_name, basename) = "#{basename} (bundle #{bundle_name})"
 
       # Why the installed file can't be loaded, or nil.
-      def unloadable_reason(file, data)
-        failure = MemoryBundle::Manifest.requires_chi_failure(data[:requires_chi], Samagotchi::VERSION)
+      def unloadable_reason(file, bundle)
+        failure = MemoryBundle::Manifest.requires_chi_failure(bundle.requires_chi, Samagotchi::VERSION)
         return failure if failure
         return "the file is missing" unless file && File.file?(file)
 
-        Hooks::BundleLoader.sha_mismatch(file, data[:plugin][:sha256], required: true)
+        Hooks::BundleLoader.sha_mismatch(file, bundle.plugin.sha256, required: true)
       end
 
       # module_eval the file into a fresh module in the bundle's namespace

data/lib/samagotchi/self_report.rb

@@ -406,8 +406,8 @@ module Samagotchi
     # "samagotchi-system 0.1.5 (shipped 0.1.5), other 1.0.0"
     def bundles_summary
       shipped = MemoryBundle::Manifest.read(dir: MemoryBundle::SystemBundle::GEM_BUNDLE_DIR).version rescue nil
-      installed = MemoryBundle::Provenance.each_installed.map do |name, data|
-        version = data[:version] || "?"
+      installed = MemoryBundle::Provenance.each_installed.map do |name, bundle|
+        version = bundle.version || "?"
         label = "#{name} #{version}"
         label += " (shipped #{shipped})" if name == MemoryBundle::SystemBundle::BUNDLE_NAME
         label