samagotchi 0.151.0 → 0.152.0

data/lib/samagotchi/child_env.rb

@@ -48,6 +48,21 @@ module Samagotchi
     # @return [Hash]
     def scrub(env) = env.except(*spawner_keys(env))
 
+    # +env+ as a spawn argument that really removes what it leaves out. A Hash
+    # given to Process.spawn, Open3 or exec is merged onto the spawner's
+    # environment: a key only deleted from it is still inherited by the child.
+    # Every key +spawner+ has and +env+ doesn't is mapped to nil, which
+    # Process.spawn unsets, so the child sees exactly +env+ (and #scrub is
+    # safe to use with it). +env+ is not changed.
+    # @param env [Hash]
+    # @param spawner [Hash] the spawner's environment (default: ENV)
+    # @return [Hash]
+    def spawn_env(env, spawner: ENV)
+      out = env.dup
+      spawner.each_key { |key| out[key] = nil unless out.key?(key) }
+      out
+    end
+
     # In gem mode, what Bundler changed in +env+ mapped back
     # (InstalledGem.unbundled_env_changes): a child activates the installed
     # gem itself rather than inherit this app's bundle. {} in a checkout.

data/lib/samagotchi/context_providers.rb

@@ -46,6 +46,11 @@ module Samagotchi
     RUBY = "{ruby}"
     URL = "{url}"
     MIN_EVERY_SECONDS = 30
+    # A bundle whose requires_chi this chi doesn't meet, already logged: said
+    # once per process per bundle and version, the way GuardrailWiring says a
+    # bundle's kept rules are.
+    TOO_NEW_LOGGED = Set.new
+    TOO_NEW_LOG_LOCK = Mutex.new
 
     module_function
 
@@ -79,15 +84,16 @@ module Samagotchi
 
     # The source the installed bundles' providers make of +url+: the first
     # bundle (by name) whose provider matches. A bundle whose providers
-    # don't parse is skipped (logged).
+    # don't parse, or whose requires_chi this chi doesn't meet, is skipped
+    # (logged).
     # @return [Resolved, nil] nil when none matches
     # @raise [Invalid] the provider makes a name that isn't a source name
     def resolve(url)
       url = url.to_s.strip
       MemoryBundle::Provenance.each_installed do |bundle, record|
-        next if record.error? || !record.context_providers?
+        next if record.error? || too_new?(bundle, record.manifest)
 
-        providers(bundle, record).each do |provider|
+        providers(bundle, record.manifest).each do |provider|
           match = provider.regexp.match(url) or next
           return resolved(bundle, provider, match)
         end
@@ -97,14 +103,33 @@ module Samagotchi
 
     # Whether an installed bundle declares a provider (the web's "+ URL").
     def any?
-      MemoryBundle::Provenance.each_installed.any? { |_bundle, record| !record.error? && record.context_providers? }
+      MemoryBundle::Provenance.each_installed.any? do |bundle, record|
+        !record.error? && !too_new?(bundle, record.manifest) && record.manifest.context_providers?
+      end
     end
 
-    def providers(bundle, record)
-      parse_list(record.context_providers)
-    rescue Invalid => e
-      Log.warn(:context, "providers_unreadable", bundle: bundle, msg: e.message)
-      []
+    # A bundle this chi is too old for has no usable providers: skip it, and
+    # say so once per process per bundle and version.
+    # @return [Boolean]
+    def too_new?(bundle, manifest)
+      return false unless manifest.context_providers?
+
+      failure = manifest.requires_chi_failure
+      return false if failure.nil?
+
+      if TOO_NEW_LOG_LOCK.synchronize { TOO_NEW_LOGGED.add?([bundle, manifest.version.to_s]) }
+        Log.warn(:context, "providers_too_new", bundle: bundle, version: manifest.version.to_s,
+                                            requires_chi: manifest.requires_chi.to_s, msg: failure)
+      end
+      true
+    end
+
+    # Its parsed providers; a list that doesn't parse is none (logged).
+    def providers(bundle, manifest)
+      if (problem = manifest.problems["context_providers"])
+        Log.warn(:context, "providers_unreadable", bundle: bundle, msg: problem)
+      end
+      manifest.context_providers
     end
 
     def resolved(bundle, provider, match)
@@ -124,7 +149,8 @@ module Samagotchi
     # installed (they run outside the guardrails gate, as a plugin loads:
     # checked the same way).
     # @return [String]
-    # @raise [Invalid] the bundle is gone or a script changed
+    # @raise [Invalid] the bundle is gone, a script changed, or this chi
+    #   doesn't meet the bundle's requires_chi
     def command_for(source)
       return source.cmd unless source.provider
 
@@ -132,6 +158,12 @@ module Samagotchi
       record = provenance.record
       raise Invalid, "bundle #{source.provider} isn't installed" unless record
 
+      # Its bundle is too new for this chi (installed with --force, or chi
+      # was downgraded): its script won't run, as its plugin wouldn't load.
+      if (failure = record.manifest.requires_chi_failure)
+        raise Invalid, "bundle #{source.provider}: #{failure}"
+      end
+
       record.scripts.each do |file, sha|
         path = File.join(provenance.scripts_dir, file)
         next if File.file?(path) && MemoryBundle::Provenance.sha_matches?(path, sha)

data/lib/samagotchi/engine.rb

@@ -1037,8 +1037,7 @@ module Samagotchi
     end
 
     def show_objective_proposals
-      proposals = @objective_proposals_mutex.synchronize { @objective_proposals.slice!(0..) }
-      proposals.each do |proposal|
+      drain_objective_proposals.each do |proposal|
         id = "objectives-#{SecureRandom.hex(4)}"
         show_card(source: Objectives::SOURCE, id: id, title: proposal.title, body: proposal.body,
                   actions: [{ label: "Apply", command: proposal.action_line(id) },
@@ -1049,6 +1048,22 @@ module Samagotchi
     end
     private :show_objective_proposals
 
+    # A turn that did not complete (canceled, failed) takes its proposals
+    # off the buffer without showing them: their Apply card would sit after a
+    # turn whose `objectives propose` call is not in the history (a rollback
+    # after Ctrl-C drops it), and leaving them in the buffer would show them
+    # at the end of the next turn.
+    def discard_objective_proposals(turn)
+      dropped = drain_objective_proposals
+      Log.info(:turn, "objectives_proposals_dropped", count: dropped.size, outcome: turn.outcome.to_s) unless dropped.empty?
+    end
+    private :discard_objective_proposals
+
+    def drain_objective_proposals
+      @objective_proposals_mutex.synchronize { @objective_proposals.slice!(0..) }
+    end
+    private :drain_objective_proposals
+
     # The strategy the working set is built under now, as LLMContextView
     # takes it: the running turn's, else the next turn's (#emit_working_set).
     # /working-set's ops act under it.
@@ -1748,6 +1763,7 @@ module Samagotchi
     # no Revise on its answer, verdict or not, as a reload does).
     def end_turn(turn, outcome, save: false, exhausted: false)
       seconds = turn.elapsed
+      turn.outcome = outcome
       synchronize_events do
         kept, event = yield(seconds)
         event[:turn_id] = turn.id
@@ -2322,9 +2338,13 @@ module Samagotchi
     # :turn_started event's at and its user message's (and reminders') stamp.
     # +verify+, +revises+: a Verify turn's claim, a Revise turn's draft.
     Turn = Struct.new(:session, :prompt, :continue, :on_event, :controller, :origin, :started_at, :messages, :ended,
-                      :settings, :id, :limit, :resumed, :resume_from, :wall, :verify, :revises) do
+                      :settings, :id, :limit, :resumed, :resume_from, :wall, :verify, :revises, :outcome) do
       def resumed? = resumed ? true : false
 
+      # The turn ended as a completed one (not canceled, not failed): the
+      # test the between-turns cards of it (an objectives proposal) use.
+      def completed? = outcome == "completed"
+
       # The turn's boundary events carry the origin only when it names a
       # sender (not TurnOrigin::NONE), so payloads stay unchanged for callers
       # that don't pass one; as its wire Hash (TurnOrigin#to_h), which the
@@ -2448,7 +2468,10 @@ module Samagotchi
       ensure
         release_turn(probe_cancel_before)
         show_context_cards_after_turn
-        show_objective_proposals
+        # Only a completed turn shows its proposal cards: a canceled, failed
+        # or rolled-back turn keeps none, and its proposals are dropped here
+        # so the next turn does not show them either.
+        turn.completed? ? show_objective_proposals : discard_objective_proposals(turn)
       end
     end
 

data/lib/samagotchi/extension_load.rb

@@ -87,13 +87,14 @@ module Samagotchi
         end
         bundle_dir = File.join(MemoryBundle::Provenance.bundles_dir, bundle_name)
         hooks_dir = File.join(bundle_dir, "hooks")
-        if bundle.experimental?
+        manifest = bundle.manifest
+        if manifest.experimental?
           Log.info(:hooks, "experimental_bundle", echo: "[hooks] Bundle '#{bundle_name}' is experimental — its hooks may change or misbehave.", bundle: bundle_name)
         end
         begin
-          Hooks::BundleLoader.load(bundle_name: bundle_name, hooks_dir: hooks_dir, metadata: bundle.hooks, registry: registry,
+          Hooks::BundleLoader.load(bundle_name: bundle_name, hooks_dir: hooks_dir, metadata: manifest.hooks, registry: registry,
                                    failures: @hook_failures, settings: settings[bundle_name.to_s] || {},
-                                   requires_chi: bundle.requires_chi, hook_failed: @hook_failed)
+                                   manifest: manifest, hook_failed: @hook_failed)
         rescue Exception => e # rubocop:disable Lint/RescueException -- a hook's SyntaxError or exit must not stop chi
           raise if e.is_a?(SignalException) # Ctrl-C and kill signals are the user's
 

data/lib/samagotchi/guardrail_wiring.rb

@@ -228,8 +228,9 @@ module Samagotchi
           @failures.add("rules (bundle #{bundle_name})", bundle.error, required: true, group: :rules)
           next
         end
-        if (too_new = MemoryBundle::Manifest.requires_chi_failure(bundle.requires_chi, Samagotchi::VERSION))
-          rules.concat(too_new_bundle_rules(bundle_name, bundle, too_new))
+        manifest = bundle.manifest
+        if (too_new = manifest.requires_chi_failure)
+          rules.concat(too_new_bundle_rules(bundle_name, manifest, too_new))
           next
         end
         dir = MemoryBundle::Provenance.new(name: bundle_name).guardrails_dir
@@ -323,7 +324,8 @@ module Samagotchi
       # one that passes every gate is allowed once without reaching them
       # (docs/guardrails.md, "System 1").
       judgment = begin
-        system_one_judge(payload, targets: verdict.targets, ask_user: verdict.fresh_ask? || verdict.second_rule_ask?)
+        system_one_judge(payload, targets: verdict.targets, ask_user: verdict.fresh_ask? || verdict.second_rule_ask?,
+                         other_rules: verdict.other_ask_rules)
       rescue LLM::RequestCancelled
         return turn_stopped(verdict)
       end
@@ -367,8 +369,9 @@ module Samagotchi
     # host) means no line at all. A judgment that fails is logged with p nil,
     # so the failures are in the log too.
     # With +ask_user+ (a fresh ask, a second rule's) it is judged and logged, never answered.
+    # +other_rules+ are the ids of the other rules asking about the same call.
     # @return [Hash, nil] {id:, p:, auto:}, nil when nothing was written
-    def system_one_judge(payload, targets: nil, ask_user: false)
+    def system_one_judge(payload, targets: nil, ask_user: false, other_rules: nil)
       return nil if Steer.participant_author?(turn_author)
 
       client = @system_one.call
@@ -401,12 +404,16 @@ module Samagotchi
       auto = !ask_user && system_one_auto_allow?(client, approval, p, entries, targets: targets)
       decision = system_one_decision(client, auto)
 
-      id = log.judgment(id: run_id, session_id: @session_lookup.call&.id,
-                        rule: approval.rule, source: approval.source, tool: approval.tool,
-                        **SystemOne::ApprovalQuestion.call_fields(approval),
-                        repo_name: approval.repo_name, repo: targets&.repo,
-                        p: p, threshold: Config.get("guardrails.system_one.threshold"), model: client.model,
-                        latency_ms: latency_ms, decision: decision, origin: "live")
+      fields = { session_id: @session_lookup.call&.id, rule: approval.rule, source: approval.source,
+                 tool: approval.tool, **SystemOne::ApprovalQuestion.call_fields(approval),
+                 repo_name: approval.repo_name, repo: targets&.repo, p: p,
+                 threshold: Config.get("guardrails.system_one.threshold"), model: client.model,
+                 latency_ms: latency_ms, decision: decision, origin: "live" }
+      # A call two rules ask about names only one; the others ride along so
+      # each rule's record (SystemOne::Record) counts this ask.
+      others = Array(other_rules).map(&:to_s).reject(&:empty?) - [approval.rule.to_s]
+      fields[:other_rules] = others unless others.empty?
+      id = log.judgment(id: run_id, **fields)
       # A judgment the log cannot hold is no judgment: the user is asked.
       system_one_run_facts(run_id, approval, targets, id.nil? && auto ? "asked" : decision)
       { id: id, p: p, auto: auto && !id.nil? }
@@ -520,7 +527,8 @@ module Samagotchi
     # load the new ones). Never loaded (a chi older than the bundle it
     # starts with): none, and a required load failure, as the hook loader
     # does for a guardrail hook, so the calls aren't quietly unguarded.
-    def too_new_bundle_rules(bundle_name, bundle, reason)
+    # @param manifest [MemoryBundle::InstalledManifest]
+    def too_new_bundle_rules(bundle_name, manifest, reason)
       kept = @loaded_bundle_rules[bundle_name]
       unless kept
         Log.warn(:guardrails, "bundle_rules_requires_chi", echo: "[samagotchi:guardrails] bundle #{bundle_name}: its rules are not loaded: #{reason}",
@@ -530,29 +538,30 @@ module Samagotchi
         return []
       end
 
-      key = [bundle_name, bundle.version.to_s]
+      key = [bundle_name, manifest.version.to_s]
       return kept if @kept_noticed[key]
 
       @kept_noticed[key] = true
-      Log.warn(:guardrails, "bundle_rules_kept", bundle: bundle_name, version: bundle.version.to_s,
-                                                 requires_chi: bundle.requires_chi.to_s)
-      @notify.call(kept_notice(bundle_name, bundle))
+      Log.warn(:guardrails, "bundle_rules_kept", bundle: bundle_name, version: manifest.version.to_s,
+                                                 requires_chi: manifest.requires_chi.to_s)
+      @notify.call(kept_notice(bundle_name, manifest))
       kept
     end
 
-    def kept_notice(bundle_name, bundle)
+    def kept_notice(bundle_name, manifest)
       id = @session_lookup.call&.id || "ID"
-      "bundle #{bundle_name} #{bundle.version} needs chi #{bundle.requires_chi} and this session runs chi #{Samagotchi::VERSION}: " \
+      "bundle #{bundle_name} #{manifest.version} needs chi #{manifest.requires_chi} and this session runs chi #{Samagotchi::VERSION}: " \
         "its new rules are not loaded, the ones loaded before still apply. Restart the session to load them " \
         "(chi sessions stop #{id}, then chi --resume #{id})"
     end
 
     # [path, mtime, size] of config.yml and every installed bundle's
-    # manifest.json and guardrails/ file.
+    # manifest.json, kept manifest.yml (its requires_chi is read from there)
+    # and guardrails/ file.
     def rules_stamp
       require_relative "memory_bundle/provenance"
       paths = [Samagotchi::ConfigFile.global_path] +
-              Dir[File.join(MemoryBundle::Provenance.bundles_dir, "*", "{manifest.json,guardrails/*}")]
+              Dir[File.join(MemoryBundle::Provenance.bundles_dir, "*", "{manifest.json,manifest.yml,guardrails/*}")]
       paths.compact.sort.map do |path|
         stat = File.stat(path)
         [path, stat.mtime.to_r, stat.size]

data/lib/samagotchi/guardrails/approval.rb

@@ -213,8 +213,8 @@ module Samagotchi
         end
       end
 
-      # What a session answer covers, as Approvals.key_for keys it: a file
-      # tool's later calls on the same paths, else this one exact call.
+      # What a session answer covers, as Guardrails::Approvals.key_for keys
+      # it: a file tool's later calls on the same paths, else this one exact call.
       def session_subject(targets)
         return "this call" if targets.nil? || targets.command || targets.paths.empty?
 

data/lib/samagotchi/guardrails/rules.rb

@@ -325,6 +325,7 @@ module Samagotchi
           if rule.verdict == :deny
             verdict.deny!(rule.reason, rule: rule.id, source: rule.source, decided_by: "rule")
           else
+            verdict.note_ask_rule(rule.id)
             verdict.ask!(rule.reason, scopes: rule.scopes, rule: rule.id, source: rule.source, decided_by: "rule")
             verdict.second_rule_asks!(rule.scopes) if asking && asking != rule.id
             asking ||= rule.id

data/lib/samagotchi/guardrails/verdict.rb

@@ -63,6 +63,26 @@ module Samagotchi
         @note = nil
         @voter = nil
         @advice = nil
+        @ask_rules = []
+      end
+
+      # Every rule id that asked about this call, in the order they voted
+      # (Rules#check), including one whose vote did not take over. The ask
+      # names a single rule (#rule); the rest are #other_ask_rules.
+      attr_reader :ask_rules
+
+      # A rule that asks, recorded whatever became of its vote.
+      def note_ask_rule(rule)
+        id = rule.to_s
+        @ask_rules << id unless id.empty? || @ask_rules.include?(id)
+        self
+      end
+
+      # The rules that asked besides the one the ask names: nil when only one
+      # rule asked, so a judgment line carries nothing extra.
+      def other_ask_rules
+        others = @ask_rules - [rule.to_s]
+        others.empty? ? nil : others
       end
 
       # @param rule [String, nil] the rule id, when a rule decided

data/lib/samagotchi/hooks/bundle_loader.rb

@@ -6,8 +6,6 @@ require_relative "../log"
 require_relative "../guardrails/load_failures"
 require_relative "../memory_bundle/bundle_hook"
 require_relative "../memory_bundle/provenance"
-require_relative "../memory_bundle/manifest"
-require_relative "../version"
 
 module Samagotchi
   # Namespace that wraps hook plugin classes per-bundle. Each bundle's hooks are
@@ -57,17 +55,17 @@ module Samagotchi
         # @param settings [Hash] the bundle's section of config.yml
         #   `bundles:` (string keys); a hook class whose initialize takes an
         #   argument gets it
-        # @param requires_chi [String, nil] the bundle's requirement; when
-        #   this chi doesn't meet it no hook loads (each is reported, as the
-        #   plugin loader does)
+        # @param manifest [MemoryBundle::InstalledManifest, nil] the installed
+        #   bundle's manifest; when this chi doesn't meet its requires_chi no
+        #   hook loads (each is reported, as the plugin loader does)
         # @param hook_failed [#call, nil] (label, "Class: message", effect:)
         #   when a hook file raises at fire time — the Engine's HookRoutes;
         #   nil when there is no UI to tell (the test kit)
         # @return [Integer] number of hooks successfully registered
-        def load(bundle_name:, hooks_dir:, metadata:, registry:, failures: nil, settings: {}, requires_chi: nil, hook_failed: nil)
+        def load(bundle_name:, hooks_dir:, metadata:, registry:, failures: nil, settings: {}, manifest: nil, hook_failed: nil)
           return 0 unless metadata.is_a?(Hash)
 
-          too_old = MemoryBundle::Manifest.requires_chi_failure(requires_chi, Samagotchi::VERSION)
+          too_old = manifest&.requires_chi_failure
           loaded = 0
           metadata.each do |raw_basename, raw_meta|
             basename = raw_basename.to_s

data/lib/samagotchi/memory_bundle/asset_installer.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require "fileutils"
-require "digest"
+require_relative "file_digest"
 require_relative "bundle_hook"
 require_relative "manifest"
 require_relative "provenance"
@@ -36,8 +36,10 @@ module Samagotchi
       # @param results, warnings, conflicts the Installer's (results and
       #   warnings are added to)
       # @param trash [Trash] the Installer's
+      # @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)
+                     force: false, strict: true, upgrade: false, dry_run: false, dev: false, chi_version: Samagotchi::VERSION)
         @name = name
         @bundle_dir = source_dir
         @manifest = manifest
@@ -52,6 +54,7 @@ module Samagotchi
         @upgrade = upgrade
         @dry_run = dry_run
         @dev = dev
+        @chi_version = chi_version
       end
 
       # @return [Installed]
@@ -175,7 +178,7 @@ module Samagotchi
           dest = File.join(@provenance.hooks_dir, basename)
           next unless File.exist?(dest)
 
-          actual = Digest::SHA256.hexdigest(File.read(dest))
+          actual = FileDigest.hex(dest)
           if actual != expected
             @warnings << "Checksum mismatch for hook #{basename}: expected #{expected[0..7]}..., got #{actual[0..7]}..."
           end
@@ -229,7 +232,7 @@ module Samagotchi
         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)
 
-        if (failure = Manifest.requires_chi_failure(@manifest.requires_chi, Samagotchi::VERSION))
+        if (failure = Manifest.requires_chi_failure(@manifest.requires_chi, @chi_version))
           @warnings << "Plugin #{plugin[:file]} won't load: #{failure}"
         end
         if @dry_run
@@ -251,7 +254,7 @@ module Samagotchi
                                     { status: "installed" }
                                   end
         expected = @manifest.checksum_for_plugin
-        actual = Digest::SHA256.hexdigest(File.binread(dest))
+        actual = FileDigest.hex(dest)
         if @strict && !@dev && expected && actual != expected
           @warnings << "Checksum mismatch for plugin #{plugin[:file]}: expected #{expected[0..7]}..., got #{actual[0..7]}..."
         end
@@ -291,7 +294,7 @@ module Samagotchi
                                         else { status: "installed" }
                                         end
           FileUtils.chmod(0o755, dest) unless @dev
-          actual = Digest::SHA256.hexdigest(File.binread(dest))
+          actual = FileDigest.hex(dest)
           expected = declared.to_s.delete_prefix("sha256:")
           if @strict && !@dev && !expected.empty? && actual != expected
             @warnings << "Checksum mismatch for script #{file}: expected #{expected[0..7]}..., got #{actual[0..7]}..."
@@ -341,7 +344,7 @@ module Samagotchi
       def warn_hooks_requires_chi
         return if @manifest.nil? || @bundle_hooks.empty?
 
-        if (failure = Manifest.requires_chi_failure(@manifest.requires_chi, Samagotchi::VERSION))
+        if (failure = Manifest.requires_chi_failure(@manifest.requires_chi, @chi_version))
           @warnings << "Bundle #{@name}: its hooks won't load: #{failure}"
         end
       end
@@ -353,7 +356,7 @@ module Samagotchi
       def warn_rules_requires_chi(rule_files)
         return if @manifest.nil? || rule_files.empty?
 
-        if (failure = Manifest.requires_chi_failure(@manifest.requires_chi, Samagotchi::VERSION))
+        if (failure = Manifest.requires_chi_failure(@manifest.requires_chi, @chi_version))
           @warnings << "Bundle #{@name}: its guardrail rules won't load: #{failure}; until chi is updated " \
                        "(chi update), guarded tool calls are refused"
         end

data/lib/samagotchi/memory_bundle/builder.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
 require "digest"
+require_relative "file_digest"
 require "fileutils"
 require "tmpdir"
 require_relative "bundle_hook"
 require_relative "manifest"
 require_relative "placeholder"
-require_relative "../context_providers"
 require_relative "../memory_paths"
 require_relative "../model_overlay"
 
@@ -140,7 +140,8 @@ module Samagotchi
 
       # 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
+      # plugin, scripts, context providers and block renderers (its
+      # InstalledManifest's). 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]
@@ -174,13 +175,18 @@ module Samagotchi
 
         rules_dir = record&.guardrails&.any? ? prov.guardrails_dir : File.join(target_dir, "guardrails")
         plugin = record ? prov.plugin_path(record) : nil
+        manifest = record&.manifest
+        # A key of the record that doesn't parse isn't built as empty: the build refuses, as it always has.
+        problem = manifest&.key_problems&.values&.first
+        raise BuildError, "the installed #{name}'s record: #{problem}" if problem
+
         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) : [],
-          block_renderers: record ? BlockRenderers.parse_list(record.block_renderers) : []
+          context_providers: manifest ? manifest.context_providers : [],
+          block_renderers: manifest ? manifest.block_renderers : []
         )
       end
 
@@ -204,33 +210,45 @@ module Samagotchi
       end
 
       # manifest.yml for the staged bundle: requires_chi, needs, session_settings and settings (typed) and the
-      # file descriptions come from the installed bundle's record, the
-      # trust_level from the CLI else the record.
+      # file descriptions come from the installed bundle's manifest (InstalledManifest), the
+      # trust_level and description from the CLI else that manifest. A key of its kept manifest.yml
+      # this chi doesn't know is carried as installed (the build is the bundle again), with a warning.
       def write_manifest(staging, name, version, files_map, parts)
-        record = parts.record
+        manifest = parts.record&.manifest
         trust_level = @trust_level
-        trust_level = record.trust_level if (trust_level.nil? || trust_level.empty?) && record&.trust_level
+        trust_level = manifest.trust_level if (trust_level.nil? || trust_level.empty?) && manifest&.trust_level
+        description = @description.empty? && manifest&.description ? manifest.description : @description
         Manifest.write(
           dir: staging,
           name: name,
           version: version,
           scope: @scope,
-          description: @description,
+          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))}" },
+          plugin: parts.plugin && { file: File.basename(parts.plugin), sha256: FileDigest.sha256(parts.plugin) },
+          requires_chi: manifest&.requires_chi,
+          needs: manifest&.needs,
+          scripts: parts.scripts.transform_values { |src| FileDigest.sha256(src) },
           context_providers: parts.context_providers,
           block_renderers: parts.block_renderers,
-          file_descriptions: file_descriptions(record, files_map),
-          session_settings: record&.session_settings || [],
-          session_setting_types: record&.session_setting_types || {},
-          settings: record&.settings,
-          setting_types: record&.setting_types || {}
+          file_descriptions: manifest ? manifest.file_descriptions.slice(*files_map.keys) : {},
+          session_settings: manifest&.session_settings || [],
+          session_setting_types: manifest&.session_setting_types || {},
+          settings: manifest&.settings,
+          setting_types: manifest&.setting_types || {}
         )
+        carry_unknown_keys(staging, parts.record, manifest) if manifest&.origin == :kept && !manifest.unknown_keys.empty?
+      end
+
+      def carry_unknown_keys(staging, record, manifest)
+        path = File.join(staging, "manifest.yml")
+        kept = YAML.load_file(record.kept_manifest_path) || {}
+        File.write(path, YAML.dump(YAML.load_file(path).merge(kept.slice(*manifest.unknown_keys))))
+        manifest.unknown_keys.each do |key|
+          @warnings << "#{Manifest.unknown_key_line(key)}; the build carries it as installed"
+        end
       end
 
       # The staged bundle to +out+: a zip or tar archive, or a directory,
@@ -279,18 +297,6 @@ module Samagotchi
                      .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(record, files_map)
-        return {} unless record
-
-        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
-
       # Without an allowlist, a memory another installed bundle owns (its
       # record lists it) isn't the user's to share: left out, one line
       # each. The bundle being built (same name) keeps its own.

data/lib/samagotchi/memory_bundle/bundle_hook.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "digest"
+require_relative "file_digest"
 
 module Samagotchi
   module MemoryBundle
@@ -38,8 +38,9 @@ module Samagotchi
       end
 
       # A hook known only by its file (no declared event): its sha, the defaults.
+      # Callers pass a file that is there (FileDigest is nil for one that isn't).
       def self.of_file(path)
-        new(sha256: "sha256:#{Digest::SHA256.hexdigest(File.binread(path))}")
+        new(sha256: FileDigest.sha256(path))
       end
 
       # "sha256:<hex>" from either form, "" for none.

data/lib/samagotchi/memory_bundle/file_digest.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Samagotchi
+  module MemoryBundle
+    # The one digest of a file on disk, so the sha256 written by a record and
+    # the one read back at load time come from the same code.
+    #
+    # Only files are digested here. Bytes already in memory (a merged file's
+    # text, a memory's content that is also its base) keep their own
+    # Digest::SHA256.hexdigest call at the place that has them.
+    module FileDigest
+      # The file's SHA256 hex, read as bytes and streamed. nil when +path+
+      # isn't a file (missing, or a directory); an unreadable file raises
+      # SystemCallError, which callers that must keep going rescue.
+      def self.hex(path)
+        return nil unless File.file?(path)
+
+        Digest::SHA256.file(path).hexdigest
+      end
+
+      # The form a manifest or a record writes for a hook, rule, plugin or
+      # script: "sha256:<hex>", nil for a file that isn't there.
+      def self.sha256(path)
+        hex = hex(path)
+        hex && "sha256:#{hex}"
+      end
+    end
+  end
+end