samagotchi 0.52.0 → 0.54.0

data/lib/samagotchi/memory_bundle/builder.rb

@@ -3,6 +3,7 @@
 require "digest"
 require "fileutils"
 require "tmpdir"
+require_relative "bundle_hook"
 require_relative "manifest"
 require_relative "placeholder"
 require_relative "../context_providers"
@@ -22,6 +23,16 @@ module Samagotchi
       DEFAULT_VERSION = "1.0.0"
       DEFAULT_SYSTEM_NAME = "chi_system_memories"
 
+      # What a build takes from the installed bundle of the same name (its
+      # record and its dir), else from the scope dir:
+      #   record      the InstalledBundle, nil when none is installed (or
+      #               it doesn't read)
+      #   hooks       basename => BundleHook; hook_files basename => path
+      #   rules       guardrails/*.yml paths
+      #   plugin      the installed plugin file, nil without one
+      #   scripts     file name => path; context_providers the parsed list
+      InstalledParts = Data.define(:record, :hooks, :hook_files, :rules, :plugin, :scripts, :context_providers)
+
       attr_reader :built_files, :warnings, :placeholder_warnings, :out_path, :staging_dir
 
       def initialize(scope: nil, name: nil, version: nil, description: "", out: nil, files: nil, trust_level: nil)
@@ -50,242 +61,225 @@ module Samagotchi
         validate_version!(resolved_version)
         raise BuildError, "invalid scope: #{@scope}" unless %w[system project].include?(@scope)
 
-        # Collect *.md files, excluding index.md and hidden files
-        all_md = Dir.glob(File.join(target_dir, "*.md")).sort
-        candidates = all_md.reject { |p| File.basename(p) == "index.md" }
-        candidates.reject! { |p| File.basename(p).start_with?(".") }
+        refuse_profile!(resolved_name)
+
+        candidates = select_memories(target_dir, resolved_name)
+        files_map = checksum_memories(candidates)
+
+        parts = installed_parts(resolved_name, target_dir)
+        resolved_out, format = resolve_out_path(@out, resolved_name)
+
+        staging = Dir.mktmpdir("samagotchi-build-")
+        @staging_dir = staging
+        begin
+          stage_files(staging, candidates, parts)
+          write_manifest(staging, resolved_name, resolved_version, files_map, parts)
+          write_out(staging, resolved_out, format)
+          @out_path = resolved_out
+        ensure
+          FileUtils.rm_rf(staging) if staging && File.directory?(staging)
+          @staging_dir = nil
+        end
 
+        {
+          out_path: @out_path,
+          format: format,
+          name: resolved_name,
+          version: resolved_version,
+          scope: @scope,
+          files: @built_files.dup,
+          placeholder_warnings: @placeholder_warnings.dup
+        }
+      end
+
+      def summary
+        lines = []
+        lines << "Built #{@built_files.size} file(s) to #{@out_path}"
+        lines << "Files: #{@built_files.join(", ")}" unless @built_files.empty?
+        lines.concat(@placeholder_warnings.map { |w| "Placeholder: #{w}" }) unless @placeholder_warnings.empty?
+        lines.concat(@warnings) unless @warnings.empty?
+        lines.join("\n")
+      end
+
+      private
+
+      # The scope's memories to build: every *.md but index.md and hidden
+      # ones; with an allowlist the named ones (each must exist) with their
+      # model overlays, else all but those another installed bundle owns.
+      # @return [Array<String>] paths
+      def select_memories(target_dir, name)
+        candidates = Dir.glob(File.join(target_dir, "*.md")).sort
+                        .reject { |p| File.basename(p) == "index.md" || File.basename(p).start_with?(".") }
         if candidates.empty?
           raise BuildError, "No memories to build in #{@scope} scope (#{target_dir}): no .md files found"
         end
+        return leave_out_owned(candidates, name) unless @filter_files && !@filter_files.empty?
 
-        # Apply allowlist filter if provided
-        if @filter_files && !@filter_files.empty?
-          allow = @filter_files.map { |f| normalize_filter_entry(f) }
-          # Validate each requested file exists in candidates
-          candidates_by_basename = candidates.map { |p| [File.basename(p), p] }.to_h
-          missing = allow.reject { |k| candidates_by_basename.key?(k) }
-          unless missing.empty?
-            raise BuildError, "Requested file(s) not found in #{@scope} scope: #{missing.join(", ")}"
-          end
+        allow = @filter_files.map { |f| normalize_filter_entry(f) }
+        candidates_by_basename = candidates.to_h { |p| [File.basename(p), p] }
+        missing = allow.reject { |k| candidates_by_basename.key?(k) }
+        raise BuildError, "Requested file(s) not found in #{@scope} scope: #{missing.join(", ")}" unless missing.empty?
 
-          candidates = with_overlays(allow, candidates_by_basename).map { |k| candidates_by_basename[k] }
-        else
-          candidates = leave_out_owned(candidates, resolved_name)
-        end
+        with_overlays(allow, candidates_by_basename).map { |k| candidates_by_basename[k] }
+      end
 
-        # Compute checksums and detect placeholders
-        files_map = {}
-        candidates.each do |path|
+      # file key => "sha256:<hex>" for the manifest; fills @built_files and
+      # a placeholder warning per memory with {{placeholders}}.
+      def checksum_memories(paths)
+        paths.to_h do |path|
           key = File.basename(path)
           content = File.read(path)
-          hex = Digest::SHA256.hexdigest(content)
-          files_map[key] = "sha256:#{hex}"
           @built_files << key
-
           names = Placeholder.new(content: content).placeholders
-          unless names.empty?
-            uniq = names.map(&:strip).uniq.sort
-            @placeholder_warnings << "#{key}: {{#{uniq.join("}}, {{")}}}"
-          end
+          @placeholder_warnings << "#{key}: {{#{names.map(&:strip).uniq.sort.join("}}, {{")}}}" unless names.empty?
+          [key, "sha256:#{Digest::SHA256.hexdigest(content)}"]
         end
+      end
 
-        # ── Hooks: collect hooks for the bundle ──────────────────────
-        hooks_map = {}
-        hooks_to_copy = [] # Array of [src_path, basename]
-        # Try provenance first (if bundle with this name is installed)
+      # The installed bundle's hooks (a recorded one missing on disk left
+      # out; one with no recorded sha gets its file's), guardrail rules,
+      # plugin, scripts and context providers. Without hooks or rules in a
+      # record, the scope dir's hooks/*.rb and guardrails/*.yml (building
+      # from a raw bundle dir that is also the memories dir).
+      # @return [InstalledParts]
+      def installed_parts(name, target_dir)
         prov = nil
-        prov_data = nil
+        record = nil
         begin
           require_relative "provenance"
-          prov = Provenance.new(name: resolved_name)
-          prov_data = prov.read
+          prov = Provenance.new(name: name)
+          record = prov.record
         rescue StandardError
-          prov_data = nil
+          record = nil
         end
-        if prov_data && prov_data[:hooks].is_a?(Hash) && !prov_data[:hooks].empty?
-          prov_data[:hooks].each do |k, meta|
-            basename = k.to_s
+
+        hooks = {}
+        hook_files = {}
+        if record&.hooks&.any?
+          record.hooks.each do |basename, hook|
             src = File.join(prov.hooks_dir, basename)
-            # Skip if hook file missing on disk
             next unless File.exist?(src)
 
-            # meta may be symbol-keyed
-            m = meta.is_a?(Hash) ? meta.transform_keys(&:to_s) : {}
-            sha = (m["sha256"] || m["checksum"] || "").to_s
-            if sha.empty?
-              sha = "sha256:#{Digest::SHA256.hexdigest(File.read(src))}"
-            elsif !sha.start_with?("sha256:")
-              sha = "sha256:#{sha}"
-            end
-            hooks_map[basename] = {
-              "sha256" => sha,
-              "event" => (m["event"] || "").to_s,
-              "on_error" => (m["on_error"] || "skip").to_s,
-              "priority" => (m["priority"] || 100).to_i
-            }
-            hooks_to_copy << [src, basename]
+            hooks[basename] = hook.sha256.empty? ? hook.with(sha256: BundleHook.of_file(src).sha256) : hook
+            hook_files[basename] = src
           end
         else
-          # Fallback: scan target_dir/hooks if present (e.g. building from a raw bundle dir that is also the mem dir)
-          local_hooks_dir = File.join(target_dir, "hooks")
-          if Dir.exist?(local_hooks_dir)
-            Dir.glob(File.join(local_hooks_dir, "*.rb")).sort.each do |src|
-              basename = File.basename(src)
-              sha = Digest::SHA256.hexdigest(File.read(src))
-              hooks_map[basename] = {
-                "sha256" => "sha256:#{sha}",
-                "event" => "",
-                "on_error" => "skip",
-                "priority" => 100
-              }
-              hooks_to_copy << [src, basename]
-            end
+          Dir.glob(File.join(target_dir, "hooks", "*.rb")).sort.each do |src|
+            hooks[File.basename(src)] = BundleHook.of_file(src)
+            hook_files[File.basename(src)] = src
           end
         end
-        # ── Guardrail rules: the installed bundle's, else target_dir's ──
-        rules_dir = prov && prov_data && prov_data[:guardrails].is_a?(Hash) ? prov.guardrails_dir : File.join(target_dir, "guardrails")
-        rules_to_copy = Dir.exist?(rules_dir) ? Dir.glob(File.join(rules_dir, "*.yml")).sort : []
-
-        # ── Plugin: the installed bundle's, with its requires_chi ──
-        plugin_src = prov && prov_data ? prov.plugin_path(prov_data) : nil
-        plugin_src = nil unless plugin_src && File.file?(plugin_src)
-        requires_chi = prov_data && prov_data[:requires_chi]
-        needs = prov_data && prov_data[:needs]
-
-        # ── Scripts and context providers: the installed bundle's ──
-        scripts_to_copy = installed_scripts(prov, prov_data)
-        context_providers = prov_data ? ContextProviders.parse_list(prov_data[:context_providers]) : []
-
-        # Determine trust_level for the built bundle
-        build_trust_level = @trust_level
-        if (build_trust_level.nil? || build_trust_level.empty?) && prov_data && prov_data[:trust_level]
-          build_trust_level = prov_data[:trust_level].to_s
-        end
-
-        # Resolve output path and format
-        resolved_out, format = resolve_out_path(@out, resolved_name)
 
-        # Prepare staging dir (temp)
-        staging = Dir.mktmpdir("samagotchi-build-")
-        @staging_dir = staging
-        begin
-          candidates.each do |src|
-            FileUtils.cp(src, File.join(staging, File.basename(src)))
-          end
-          # Copy hooks into staging/hooks/
-          unless hooks_to_copy.empty?
-            hooks_staging = File.join(staging, "hooks")
-            FileUtils.mkdir_p(hooks_staging)
-            hooks_to_copy.each do |src, basename|
-              FileUtils.cp(src, File.join(hooks_staging, basename))
-            end
-          end
+        rules_dir = record&.guardrails&.any? ? prov.guardrails_dir : File.join(target_dir, "guardrails")
+        plugin = record ? prov.plugin_path(record) : nil
+        InstalledParts.new(
+          record: record, hooks: hooks, hook_files: hook_files,
+          rules: Dir.exist?(rules_dir) ? Dir.glob(File.join(rules_dir, "*.yml")).sort : [],
+          plugin: plugin && File.file?(plugin) ? plugin : nil,
+          scripts: installed_scripts(prov, record),
+          context_providers: record ? ContextProviders.parse_list(record.context_providers) : []
+        )
+      end
 
-          unless rules_to_copy.empty?
-            rules_staging = File.join(staging, "guardrails")
-            FileUtils.mkdir_p(rules_staging)
-            rules_to_copy.each { |src| FileUtils.cp(src, File.join(rules_staging, File.basename(src))) }
-          end
+      # The memories, hooks/, guardrails/, the plugin and scripts/ into the
+      # staging dir, laid out as Installer reads a bundle.
+      def stage_files(staging, candidates, parts)
+        candidates.each { |src| FileUtils.cp(src, File.join(staging, File.basename(src))) }
+        unless parts.hook_files.empty?
+          FileUtils.mkdir_p(File.join(staging, "hooks"))
+          parts.hook_files.each { |basename, src| FileUtils.cp(src, File.join(staging, "hooks", basename)) }
+        end
+        unless parts.rules.empty?
+          FileUtils.mkdir_p(File.join(staging, "guardrails"))
+          parts.rules.each { |src| FileUtils.cp(src, File.join(staging, "guardrails", File.basename(src))) }
+        end
+        FileUtils.cp(parts.plugin, File.join(staging, File.basename(parts.plugin))) if parts.plugin
+        return if parts.scripts.empty?
 
-          FileUtils.cp(plugin_src, File.join(staging, File.basename(plugin_src))) if plugin_src
+        FileUtils.mkdir_p(File.join(staging, "scripts"))
+        parts.scripts.each_value { |src| FileUtils.cp(src, File.join(staging, "scripts", File.basename(src))) }
+      end
 
-          unless scripts_to_copy.empty?
-            FileUtils.mkdir_p(File.join(staging, "scripts"))
-            scripts_to_copy.each_value { |src| FileUtils.cp(src, File.join(staging, "scripts", File.basename(src))) }
-          end
+      # manifest.yml for the staged bundle: requires_chi, needs and the
+      # file descriptions come from the installed bundle's record, the
+      # trust_level from the CLI else the record.
+      def write_manifest(staging, name, version, files_map, parts)
+        record = parts.record
+        trust_level = @trust_level
+        trust_level = record.trust_level if (trust_level.nil? || trust_level.empty?) && record&.trust_level
+        Manifest.write(
+          dir: staging,
+          name: name,
+          version: version,
+          scope: @scope,
+          description: @description,
+          files: files_map,
+          hooks: parts.hooks.empty? ? nil : parts.hooks,
+          trust_level: trust_level,
+          plugin: parts.plugin && { file: File.basename(parts.plugin), sha256: Digest::SHA256.hexdigest(File.binread(parts.plugin)) },
+          requires_chi: record&.requires_chi,
+          needs: record&.needs,
+          scripts: parts.scripts.transform_values { |src| "sha256:#{Digest::SHA256.hexdigest(File.binread(src))}" },
+          context_providers: parts.context_providers,
+          file_descriptions: file_descriptions(record, files_map)
+        )
+      end
 
-          Manifest.write(
-            dir: staging,
-            name: resolved_name,
-            version: resolved_version,
-            scope: @scope,
-            description: @description,
-            files: files_map,
-            hooks: hooks_map.empty? ? nil : hooks_map,
-            trust_level: build_trust_level,
-            plugin: plugin_src && { file: File.basename(plugin_src), sha256: Digest::SHA256.hexdigest(File.binread(plugin_src)) },
-            requires_chi: requires_chi,
-            needs: needs,
-            scripts: scripts_to_copy.transform_values { |src| "sha256:#{Digest::SHA256.hexdigest(File.binread(src))}" },
-            context_providers: context_providers,
-            file_descriptions: file_descriptions(prov_data, files_map)
-          )
-
-          case format
-          when :zip
-            zip_staging(staging, resolved_out)
-            @out_path = resolved_out
-          when :tar_gz, :tar, :tgz
-            tar_staging(staging, resolved_out, format)
-            @out_path = resolved_out
-          when :dir
-            # Copy staging contents to out dir
-            FileUtils.mkdir_p(resolved_out)
-            # Guard: refuse to overwrite non-empty dir without force (error)
-            existing = Dir.entries(resolved_out).reject { |e| e.start_with?(".") }
-            unless existing.empty?
-              # Allow if out is the staging itself? no, staging is temp
-              # Check if out dir already has manifest.yml — treat as existing bundle
-              if File.exist?(File.join(resolved_out, "manifest.yml"))
-                raise BuildError, "Output directory already contains a bundle (#{resolved_out}/manifest.yml) — choose different --out or remove it"
-              end
-              # If dir has any files, still require explicit handling — error
-              unless existing.empty?
-                raise BuildError, "Output directory already exists and is not empty: #{resolved_out}"
-              end
+      # The staged bundle to +out+: a zip or tar archive, or a directory,
+      # which must be new or empty (one holding a bundle says so).
+      def write_out(staging, out, format)
+        case format
+        when :zip then zip_staging(staging, out)
+        when :tar_gz, :tar, :tgz then tar_staging(staging, out, format)
+        when :dir
+          FileUtils.mkdir_p(out)
+          unless Dir.entries(out).reject { |e| e.start_with?(".") }.empty?
+            if File.exist?(File.join(out, "manifest.yml"))
+              raise BuildError, "Output directory already contains a bundle (#{out}/manifest.yml) — choose different --out or remove it"
             end
-            FileUtils.cp_r("#{staging}/.", resolved_out)
-            @out_path = resolved_out
-          else
-            raise BuildError, "unknown format: #{format}"
+
+            raise BuildError, "Output directory already exists and is not empty: #{out}"
           end
-        ensure
-          # Clean up staging temp dir unless out_path == staging (not possible for dir)
-          FileUtils.rm_rf(staging) if staging && File.directory?(staging)
-          @staging_dir = nil
+          FileUtils.cp_r("#{staging}/.", out)
+        else
+          raise BuildError, "unknown format: #{format}"
         end
-
-        {
-          out_path: @out_path,
-          format: format,
-          name: resolved_name,
-          version: resolved_version,
-          scope: @scope,
-          files: @built_files.dup,
-          placeholder_warnings: @placeholder_warnings.dup
-        }
       end
 
-      def summary
-        lines = []
-        lines << "Built #{@built_files.size} file(s) to #{@out_path}"
-        lines << "Files: #{@built_files.join(", ")}" unless @built_files.empty?
-        lines.concat(@placeholder_warnings.map { |w| "Placeholder: #{w}" }) unless @placeholder_warnings.empty?
-        lines.concat(@warnings) unless @warnings.empty?
-        lines.join("\n")
+      # An installed profile (meta bundle) ships only its includes: a build
+      # under its name would make a plain bundle of the scope's memories,
+      # without the includes, carrying the profile's trust_level.
+      def refuse_profile!(name)
+        require_relative "profile"
+        record = Provenance.new(name: name).record
+        return unless Profile.installed_meta?(name, record)
+
+        shipped = File.join(SourceNormalizer::SHIPPED_DIR, name)
+        members = Profile.recorded(record, File.file?(File.join(shipped, "manifest.yml")) ? Manifest.read(dir: shipped) : nil)
+        raise BuildError, "#{name} is an installed profile (includes: #{members.join(", ")}): it ships only its includes, " \
+                          "so a build can't remake it; pick another --name for these memories"
+      rescue JSON::ParserError, SystemCallError, Manifest::ValidationError
+        nil
       end
 
-      private
-
       # The installed bundle's scripts its record lists, file name => path
       # in its scripts/ (a missing one is left out); {} without a record.
-      def installed_scripts(prov, prov_data)
-        return {} unless prov && prov_data && prov_data[:scripts].is_a?(Hash)
+      def installed_scripts(prov, record)
+        return {} unless record
 
-        prov_data[:scripts].keys.map(&:to_s).sort.to_h { |file| [file, File.join(prov.scripts_dir, file)] }
-                           .select { |_, path| File.file?(path) }
+        record.scripts.keys.sort.to_h { |file| [file, File.join(prov.scripts_dir, file)] }
+                     .select { |_, path| File.file?(path) }
       end
 
       # The descriptions the installed bundle's record keeps for the files
       # being built (its manifest's files: mappings), so a rebuild writes
       # them back; {} without a record.
-      def file_descriptions(prov_data, files_map)
-        return {} unless prov_data && prov_data[:files].is_a?(Hash)
+      def file_descriptions(record, files_map)
+        return {} unless record
 
-        prov_data[:files].each_with_object({}) do |(key, entry), acc|
-          text = entry.is_a?(Hash) ? entry[:description].to_s : ""
-          acc[key.to_s] = text if files_map.key?(key.to_s) && !text.empty?
+        record.files.each_with_object({}) do |(key, entry), acc|
+          text = entry[:description].to_s
+          acc[key] = text if files_map.key?(key) && !text.empty?
         end
       end
 

data/lib/samagotchi/memory_bundle/bundle_hook.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Samagotchi
+  module MemoryBundle
+    # One hook's metadata, as a bundle's manifest.yml declares it and its
+    # installed record (manifest.json) keeps it: the file's sha256
+    # ("sha256:<hex>", "" when none is recorded), the event it registers
+    # for ("" when none: it isn't loaded), on_error (skip, log or
+    # fail_closed) and priority. The one place the defaults live.
+    class BundleHook < Data.define(:sha256, :event, :on_error, :priority)
+      DEFAULT_ON_ERROR = "skip"
+      DEFAULT_PRIORITY = 100
+
+      def initialize(sha256: "", event: "", on_error: DEFAULT_ON_ERROR, priority: DEFAULT_PRIORITY)
+        super
+      end
+
+      # @param raw [Hash, BundleHook, nil] string keys (manifest.yml) or
+      #   symbol keys (a read record); missing or blank values get the
+      #   defaults
+      def self.parse(raw)
+        return raw if raw.is_a?(BundleHook)
+
+        h = raw.is_a?(Hash) ? raw.transform_keys(&:to_s) : {}
+        on_error = h["on_error"].to_s.strip
+        new(sha256: prefixed(h["sha256"]), event: h["event"].to_s.strip,
+            on_error: on_error.empty? ? DEFAULT_ON_ERROR : on_error,
+            priority: (h["priority"] || DEFAULT_PRIORITY).to_i)
+      end
+
+      # A hook known only by its file (no declared event): its sha, the defaults.
+      def self.of_file(path)
+        new(sha256: "sha256:#{Digest::SHA256.hexdigest(File.binread(path))}")
+      end
+
+      # "sha256:<hex>" from either form, "" for none.
+      def self.prefixed(sha)
+        sha = sha.to_s.strip
+        sha.empty? || sha.start_with?("sha256:") ? sha : "sha256:#{sha}"
+      end
+
+      # The sha's hex, "" when none is recorded.
+      def hex = sha256.delete_prefix("sha256:")
+
+      # The string-keyed form manifest.yml and manifest.json hold.
+      def to_record = to_h.transform_keys(&:to_s)
+    end
+  end
+end

data/lib/samagotchi/memory_bundle/installed_bundle.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "bundle_hook"
+require_relative "plugin_ref"
+
+module Samagotchi
+  module MemoryBundle
+    # An installed bundle's record, as Provenance#write keeps it in
+    # <bundles>/<name>/manifest.json. Reading is tolerant: an older record
+    # lacks keys a newer chi writes, and a key that is missing or of the
+    # wrong shape reads as empty (nil for the optional strings and lists).
+    #
+    #   files       file key ("x.md") => { checksum:, conflict:, description: } (symbol keys)
+    #   hooks       basename => BundleHook
+    #   guardrails  basename => recorded sha256 ("" when none)
+    #   scripts     file name => recorded sha256 ("" when none)
+    #   plugin      PluginRef, nil without one
+    #   needs, context_providers
+    #               the lists as recorded (nil when absent): Manifest.parse_needs
+    #               and ContextProviders.parse_list check them
+    #   includes    a profile's recorded members, nil for a plain bundle
+    #   error       why manifest.json couldn't be read (the rest empty), else nil
+    class InstalledBundle < Data.define(:name, :version, :scope, :source, :installed_at, :trust_level, :source_commit,
+                                        :requires_chi, :files, :hooks, :guardrails, :scripts, :plugin, :needs,
+                                        :includes, :context_providers, :error)
+      OPTIONAL = { version: nil, scope: nil, source: nil, installed_at: nil, trust_level: nil, source_commit: nil,
+                   requires_chi: nil, files: {}, hooks: {}, guardrails: {}, scripts: {}, plugin: nil, needs: nil,
+                   includes: nil, context_providers: nil, error: nil }.freeze
+
+      def initialize(name:, **fields)
+        super(name: name, **OPTIONAL, **fields)
+      end
+
+      # The record at +path+, nil when there is none.
+      # @raise [JSON::ParserError, SystemCallError] it doesn't read
+      def self.read(name, path)
+        return nil unless File.exist?(path)
+
+        parse(name, JSON.parse(File.read(path)))
+      end
+
+      # One that couldn't be read: +message+ says why.
+      def self.unreadable(name, message) = new(name: name, error: message)
+
+      # @param raw [Hash] the parsed manifest.json (string or symbol keys);
+      #   anything else reads as unreadable
+      def self.parse(name, raw)
+        return unreadable(name, "manifest.json is not an object") unless raw.is_a?(Hash)
+
+        h = raw.transform_keys(&:to_s)
+        new(name: name, version: string(h["version"]), scope: string(h["scope"]), source: string(h["source"]),
+            installed_at: string(h["installed_at"]), trust_level: string(h["trust_level"]),
+            source_commit: string(h["source_commit"]), requires_chi: string(h["requires_chi"]),
+            files: mapping(h["files"]) { |entry| entry.is_a?(Hash) ? entry.transform_keys(&:to_sym) : {} },
+            hooks: mapping(h["hooks"]) { |meta| BundleHook.parse(meta) },
+            guardrails: mapping(h["guardrails"]) { |meta| sha(meta) },
+            scripts: mapping(h["scripts"]) { |meta| sha(meta) },
+            plugin: PluginRef.parse(h["plugin"]), needs: h["needs"], context_providers: h["context_providers"],
+            includes: h["includes"].is_a?(Array) ? h["includes"].map(&:to_s) : nil)
+      end
+
+      def self.string(value) = value&.to_s
+
+      def self.mapping(value, &)
+        value.is_a?(Hash) ? value.to_h { |k, v| [k.to_s, yield(v)] } : {}
+      end
+
+      def self.sha(meta) = meta.is_a?(Hash) ? meta.transform_keys(&:to_s)["sha256"].to_s : ""
+      private_class_method :string, :mapping, :sha
+
+      def error? = !error.nil?
+
+      # The scope its files went to: "system" when none is recorded.
+      def effective_scope = scope.to_s.strip.empty? ? "system" : scope
+
+      # A bundle with no trust_level counts as experimental.
+      def experimental? = (trust_level || "experimental") == "experimental"
+
+      # A profile (meta bundle): it records its members.
+      def profile? = !includes.nil?
+
+      def owns?(file_key) = files.key?(file_key.to_s)
+
+      def needs? = needs.is_a?(Array) && !needs.empty?
+
+      def context_providers? = context_providers.is_a?(Array) && !context_providers.empty?
+    end
+  end
+end