kairos-chain 3.93.0 → 3.94.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a1624b7fa2adf2856c0f55ca0012dc527870d5649cdcad7ebe2d8ae90cda1d4a
-  data.tar.gz: 12cdc74b57b87266ca3364654468fa077774665e9b1bef090dea9806907c4b1b
+  metadata.gz: 05055bfa3f7c4377e2e88011754c85d8d87c690e07f19837c4dca5a0c1cd033c
+  data.tar.gz: 48b9c8a70d27304e21293440f121ec069cb0c7ec47ed41b01573cdd2e3c80505
 SHA512:
-  metadata.gz: 9e47baf8089acd2fb9cc4f7f5fc4264d55d4096f8ed21aacb1a736ab27099beebda372d429de1e5a424e66307ccda5a274f5532073e7e21eaa4bc5d58684a718
-  data.tar.gz: 4deb91c26655f7c6e11a72802635a7c088aa0a7246124785984d2fe2f20fbb0ab02e0b2d27e425948a8107be69fe5cd1f72d4ca90efc069f12731bef9ec36e79
+  metadata.gz: '08ee4ff5f61407bdcc390eb8c4cda6c286472672a6549ded81d5d0b1c7cf29f8203a472f9cfa5d4cfc811b1b8d923d4ee77ee6746decad1893a33c01187ecc1e'
+  data.tar.gz: 0b94dde53ddce2444defb9933515dda0d4e754bb0e6053129927d82032bdb9b73383b5d67234a9b57f3e003e82e1b004c17c94f6e551a45ba2fc5dca412bd340

data/CHANGELOG.md

@@ -6,6 +6,32 @@ This project follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [3.94.0] - 2026-10-20
+
+### Added — L0 changes proposed for later approval, L0 restores on the record, L1 body history
+
+- **L0 proposals.** `skills_evolve` keeps a pending L0 change as (base, result,
+  content) without evaluating it; `command: "pending"` lists the proposals and
+  `apply` takes a `proposal_id`. Applying writes exactly the stored bytes under
+  an exclusive lock, only while the base is still the L0 in force and the
+  content hashes to its result. A failed load, an interrupt or a killed thread
+  never leaves an unrecorded L0 on disk.
+- **L0 restore on the record.** `skills_rollback` restores a snapshot only if
+  its hash appears in a transition recorded on the chain. Without
+  `approved: true` it writes nothing and returns a pending proposal; with
+  `proposal_id` the approval applies exactly the proposal that was shown.
+- **L1 body history.** `knowledge_update` gains `history`, `restore` and
+  `erase_body` (the last is irreversible and needs `approved: true`). Bodies
+  are kept by content address from a recorded activation point, and restore and
+  erasure decide from the chain whether their record landed.
+
+### Changed — read before upgrading
+
+- `VersionManager.rollback` is removed; nothing shipped calls it. Code that
+  called it should use `skills_rollback` with a `proposal_id`.
+- `chain_import` never overwrites an existing chain: it is refused when the
+  target already holds chain data. Import into a new data directory instead.
+
 ## [3.93.0] - 2026-10-19
 
 ### Added — `proactive_tutorial`, an opt-in mode that suggests KairosChain's own workflow

data/lib/kairos_mcp/kairos_chain/landed_probe.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'chain'
+
+module KairosMcp
+  module KairosChain
+    # Answers "did this exact entry reach the ledger?" after an append did not
+    # return normally.
+    #
+    # Chain#add_block raises Storage::Error when it cannot tell whether the
+    # write landed, and a thread can be interrupted after the write but before
+    # add_block returns. Either way the caller holds a change it must keep
+    # (the record is on the chain) or undo (it is not). Looking only at the last
+    # block answers wrongly once anything else has been appended since, so the
+    # caller takes a mark before appending and the probe scans every block after
+    # that mark for an entry equal to the one the caller tried to append.
+    module LandedProbe
+      # The ledger length now, i.e. the index from which the caller's block can
+      # appear. nil when the ledger cannot be read; every later status is then
+      # :unknown.
+      def self.mark(storage_backend: nil)
+        chain = Chain.new(storage_backend: storage_backend)
+        case chain.load_state
+        when :readable then chain.chain.length
+        when :absent then 0
+        end
+      rescue StandardError
+        nil
+      end
+
+      # :landed  -- a block after the mark carries an entry equal to entry_json
+      # :absent  -- the ledger is readable (or absent) and no such entry is there
+      # :unknown -- the mark or the ledger could not be read
+      #
+      # Equality is on the parsed entry, so a backend that re-serialises the JSON
+      # still matches. Only StandardError is absorbed: an interrupt during the
+      # probe propagates, and callers run their undo in an ensure for that case.
+      def self.status(mark, entry_json, storage_backend: nil)
+        return :unknown if mark.nil?
+
+        expected = JSON.parse(entry_json)
+        chain = Chain.new(storage_backend: storage_backend)
+        return :absent if chain.load_state == :absent
+        return :unknown unless chain.load_state == :readable
+
+        found = chain.chain.drop(mark).any? do |block|
+          Array(block.data).any? do |raw|
+            begin
+              JSON.parse(raw.to_s) == expected
+            rescue JSON::ParserError
+              false
+            end
+          end
+        end
+        found ? :landed : :absent
+      rescue StandardError
+        :unknown
+      end
+    end
+  end
+end

data/lib/kairos_mcp/knowledge_provider.rb

@@ -1,12 +1,16 @@
 # frozen_string_literal: true
 
 require 'digest'
+require 'json'
 require 'fileutils'
 require 'yaml'
+require 'securerandom'
 require_relative 'anthropic_skill_parser'
 require_relative 'path_containment'
 require_relative 'skillset_manager'
 require_relative 'kairos_chain/chain'
+require_relative 'kairos_chain/landed_probe'
+require_relative 'l1_history'
 require_relative 'vector_search/provider'
 require_relative '../kairos_mcp'
 
@@ -189,6 +193,10 @@ module KairosMcp
         return { success: false, error: "Knowledge '#{name}' already exists" }
       end
 
+      # C2: store the body before the file write and before the chain record
+      refusal = keep_bodies!(content)
+      return refusal if refusal
+
       skill = AnthropicSkillParser.create(@knowledge_dir, name, content, create_subdirs: create_subdirs)
       
       # Record hash reference to blockchain
@@ -232,6 +240,10 @@ module KairosMcp
         return { success: false, error: "No changes detected" }
       end
 
+      # C2: both bodies kept before anything is written or recorded
+      refusal = keep_bodies!(prev_content, new_content)
+      return refusal if refusal
+
       # Update the file
       updated_skill = AnthropicSkillParser.update(skill.base_path, new_content)
 
@@ -269,6 +281,10 @@ module KairosMcp
       prev_content = File.read(skill.md_file_path)
       prev_hash = Digest::SHA256.hexdigest(prev_content)
 
+      # C2: keep the previous body before the directory goes away
+      refusal = keep_bodies!(prev_content)
+      return refusal if refusal
+
       # Delete the directory
       FileUtils.rm_rf(skill.base_path)
 
@@ -290,6 +306,367 @@ module KairosMcp
       { success: true, deleted: name, prev_hash: prev_hash }
     end
 
+    # C3: return an entry to a body already kept in history
+    def restore(name, content_hash, reason: nil)
+      unless content_hash.to_s.match?(L1History::HASH_PATTERN)
+        return { success: false, error: "invalid content hash: #{content_hash}" }
+      end
+
+      # A quarantine left by an interrupted erasure is settled first, so a body
+      # whose erasure is on the chain is not restored from its quarantine.
+      settle_quarantine!
+
+      # The body must be present before anything else is decided
+      body = history_store.retrievable?(content_hash) ? history_store.fetch(content_hash) : nil
+      return { success: false, error: "body not retrievable: #{content_hash}" } if body.nil?
+
+      skill = get(name)
+
+      if skill
+        return not_owned(name) unless owned?(skill)
+
+        prev_content = File.read(skill.md_file_path)
+        prev_hash = Digest::SHA256.hexdigest(prev_content)
+        if prev_hash == content_hash
+          return { success: false, error: "#{name} already holds the content of hash #{content_hash}" }
+        end
+
+        # C2: previous body and restored body, both before the write
+        refusal = keep_bodies!(prev_content, body)
+        return refusal if refusal
+
+        tracked_action = 'update'
+      else
+        # Same name checks as create, in the same order (safe_segment first:
+        # it is the check that tolerates a non-String argument).
+        unless PathContainment.safe_segment?(name)
+          return { success: false, error: "Invalid knowledge name #{name.inspect}: not a single path segment" }
+        end
+        return { success: false, error: "Invalid knowledge name '#{name}': reserved by the knowledge store" } if reserved_name?(name)
+
+        skill_dir = File.join(@knowledge_dir, name)
+        unless PathContainment.contained?(@knowledge_dir, skill_dir)
+          return { success: false, error: "Invalid knowledge name '#{name}': resolves outside the knowledge directory" }
+        end
+        return { success: false, error: "Knowledge '#{name}' already exists" } if File.exist?(skill_dir)
+
+        refusal = keep_bodies!(body)
+        return refusal if refusal
+
+        prev_hash = nil
+        tracked_action = 'create'
+      end
+
+      # restore_id makes the record unique, so the landed check below finds
+      # this restore and not an identical one made in the same second.
+      entry = hash_reference_entry(
+        name: name,
+        action: 'restore',
+        prev_hash: prev_hash,
+        next_hash: content_hash,
+        reason: "returned to content of hash #{content_hash}#{reason ? ": #{reason}" : ''}",
+        extra: { restored_from: content_hash, restore_id: SecureRandom.hex(8) }
+      )
+      mark = KairosChain::LandedProbe.mark(storage_backend: storage_backend)
+      status = nil
+      error = nil
+      attempted = false
+
+      # Undo touches the live file only while it holds the restored bytes. A
+      # write that never took effect, or content a same-name writer has put
+      # there since, is not this restore's to undo.
+      live_md = skill ? skill.md_file_path : File.join(skill_dir, "#{name}.md")
+      holds_restored = lambda do
+        File.file?(live_md) && Digest::SHA256.hexdigest(File.binread(live_md)) == content_hash
+      rescue StandardError
+        false
+      end
+
+      # The live write sits inside the guarded region, so no interrupt can fall
+      # between the write and the ensure that undoes it.
+      begin
+        restored_skill = if skill
+                           AnthropicSkillParser.update(skill.base_path, body)
+                         else
+                           AnthropicSkillParser.create(@knowledge_dir, name, body)
+                         end
+        attempted = true
+        status, error = append_entry(entry, mark)
+      ensure
+        # In ensure, so an interrupt or a thread kill cannot leave the live
+        # entry changed without its record. A record that is on the chain
+        # stands whatever add_block raised; any other answer, including an
+        # unknown one, puts the live entry back exactly as it was: an entry
+        # that already existed gets its previous body written back, one that
+        # was recreated here is removed again -- provided it still holds what
+        # this restore wrote.
+        begin
+          status ||= KairosChain::LandedProbe.status(mark, entry, storage_backend: storage_backend) if attempted
+        ensure
+          if status != :landed && holds_restored.call
+            if skill
+              AnthropicSkillParser.update(skill.base_path, prev_content)
+            else
+              FileUtils.rm_rf(skill_dir)
+            end
+          end
+        end
+      end
+
+      unless status == :landed
+        return { success: false, error: "restore not recorded (#{error&.message || status}); entry left as it was" }
+      end
+
+      # After the record, and outside it: a metadata failure is reported but
+      # never undoes a restore the chain already holds.
+      update_knowledge_meta(name, content_hash)
+      update_vector_index(name, body, restored_skill)
+      track_pending_change(layer: 'L1', action: tracked_action, skill_id: name, reason: reason)
+
+      {
+        success: true,
+        name: name,
+        action: 'restore',
+        content_hash: content_hash,
+        restored_from: content_hash
+      }
+    end
+
+    # C3: every body this entry has pointed at, in chain order
+    def history(name)
+      # Settled first, so `retrievable` below reflects what the chain records.
+      settle_quarantine!
+      chain = KairosChain::Chain.new(storage_backend: storage_backend)
+      # L1: start inactive; only an l1_history_activation record flips this.
+      active = false
+      rows = []
+
+      chain.chain.each do |block|
+        Array(block.data).each do |raw|
+          record = begin
+            JSON.parse(raw, symbolize_names: true)
+          rescue JSON::ParserError, TypeError
+            nil
+          end
+          next unless record.is_a?(Hash)
+
+          case record[:type]
+          when 'l1_history_activation'
+            # Activation threads forward from the block that declared it
+            flag = record.key?(:active) ? record[:active] : record[:enabled]
+            active = (flag == true || flag == 'true')
+          when 'knowledge_update'
+            next unless record[:knowledge_id] == name && record[:next_hash]
+
+            rows << {
+              index: block.index,
+              timestamp: record[:timestamp],
+              action: record[:action],
+              next_hash: record[:next_hash],
+              retrievable: begin
+                history_store.retrievable?(record[:next_hash])
+              rescue ArgumentError
+                false
+              end,
+              recorded_while_active: active
+            }
+          end
+        end
+      end
+
+      rows
+    end
+
+    # C4: drop one stored body; the chain keeps the fact of the removal
+    def erase_body(name, content_hash, reason:)
+      if reason.nil? || reason.to_s.strip.empty?
+        return { success: false, error: 'a reason is required' }
+      end
+      unless content_hash.to_s.match?(L1History::HASH_PATTERN)
+        return { success: false, error: "invalid content hash: #{content_hash}" }
+      end
+      # Nothing was ever stored; checked before the lock, which would create
+      # the store root.
+      unless File.directory?(history_store.root)
+        return { success: false, error: "body not stored: #{content_hash}" }
+      end
+
+      # The checks, the quarantine and the record run under one lock, so a
+      # second erasure cannot settle this one's quarantine as a leftover while
+      # its record is still being appended.
+      history_store.with_erase_lock do
+        settle_quarantine!(locked: true)
+
+        # E3: live content blocks the erasure. Judged per directory, so an entry
+        # whose directory name differs from its declared name is still seen.
+        live = live_directories_for_body(content_hash)
+        unless live.empty?
+          return { success: false,
+                   error: "body is live content in: #{live.sort.join(', ')}" }
+        end
+
+        # E2: the hash must be cited by a knowledge_update of this entry, and by
+        # no other entry. A hash cited elsewhere is a body shared between entries,
+        # and erasing it would remove the other entry's history too.
+        citing = knowledge_ids_citing_body(content_hash)
+        unless citing.include?(name)
+          return { success: false,
+                   error: "#{name} never pointed at this body: #{content_hash}" }
+        end
+        shared_with = (citing - [name]).sort
+        unless shared_with.empty?
+          return { success: false,
+                   error: "body is shared with: #{shared_with.join(', ')}" }
+        end
+
+        unless history_store.retrievable?(content_hash)
+          return { success: false, error: "body not stored: #{content_hash}" }
+        end
+
+        # E1: quarantine first, append second. Nothing is removed until the
+        # erasure record is on the chain. The record carries the quarantine's
+        # erase id, which is what lets a leftover quarantine be matched to
+        # exactly this record later.
+        # The mark is taken before the quarantine, so the only step between the
+        # quarantine and the guarded region below is building the record. A
+        # quarantine orphaned there anyway is settled by settle_quarantine!.
+        mark = KairosChain::LandedProbe.mark(storage_backend: storage_backend)
+        erase_id = history_store.begin_erase(content_hash)
+        return { success: false, error: "body not stored: #{content_hash}" } unless erase_id
+
+        entry = {
+          type: 'l1_body_erasure',
+          layer: 'L1',
+          knowledge_id: name,
+          content_hash: content_hash,
+          erase_id: erase_id,
+          reason: reason,
+          timestamp: Time.now.iso8601
+        }.to_json
+        status = nil
+        error = nil
+        settled = true
+
+        begin
+          status, error = append_entry(entry, mark)
+        ensure
+          # In ensure, so an interrupt cannot leave a quarantine behind without
+          # deciding it. Landed: drop the bytes. Known absent: put them back.
+          # Unknown: leave the quarantine; settle_quarantine! decides it from the
+          # chain once the chain can be read.
+          begin
+            status ||= KairosChain::LandedProbe.status(mark, entry, storage_backend: storage_backend)
+          ensure
+            begin
+              case status
+              when :landed then history_store.commit_erase(content_hash, erase_id)
+              when :absent then history_store.abort_erase(content_hash, erase_id)
+              end
+            rescue StandardError => e
+              # The quarantine stays and is settled on the next history access.
+              warn "[l1_history] quarantine #{erase_id} left for settling: #{e.message}"
+              settled = false
+            end
+          end
+        end
+
+        case status
+        when :landed
+          { success: true, name: name, content_hash: content_hash, erased: settled }
+        when :absent
+          { success: false, error: "erasure not recorded, body kept: #{error&.message}" }
+        else
+          { success: false,
+            error: "erasure outcome unknown (#{error&.message}); the body stays quarantined " \
+                   'and is settled from the chain on the next history access' }
+        end
+      end
+    end
+
+    # Settle quarantines an interrupted erasure left behind (L1History
+    # #reconcile_quarantine!). Cheap when there are none: the chain is read only
+    # when a quarantine exists. Takes the erase lock unless the caller holds it.
+    private def settle_quarantine!(locked: false)
+      return if history_store.quarantined.empty?
+      return history_store.reconcile_quarantine!(recorded_erase_ids) if locked
+
+      history_store.with_erase_lock { history_store.reconcile_quarantine!(recorded_erase_ids) }
+    end
+
+    # Erase ids in l1_body_erasure records on the chain; nil when the chain
+    # cannot be read, which leaves every quarantine undecided.
+    private def recorded_erase_ids
+      chain = KairosChain::Chain.new(storage_backend: storage_backend)
+      return [] if chain.load_state == :absent
+      return nil unless chain.load_state == :readable
+
+      chain.chain.each_with_object([]) do |block, ids|
+        Array(block.data).each do |raw|
+          record = begin
+            JSON.parse(raw.to_s)
+          rescue JSON::ParserError
+            nil
+          end
+          next unless record.is_a?(Hash) && record['type'] == 'l1_body_erasure' && record['erase_id']
+
+          ids << record['erase_id']
+        end
+      end
+    rescue StandardError
+      nil
+    end
+
+    # E3 helper. Every entry directory whose current body hashes to
+    # content_hash blocks the erasure: the main knowledge dir and every external
+    # knowledge dir a SkillSet registered, as `list` exposes them. Each
+    # directory is parsed on its own and never looked up by its declared name,
+    # which is what let a directory whose name differs slip past the old guard.
+    # A directory that cannot be parsed is skipped rather than treated as a
+    # match.
+    private def live_directories_for_body(content_hash)
+      candidates = skill_dirs.map { |dir| [dir, File.basename(dir)] }
+      @external_dirs.each do |ext|
+        external_skill_dirs(ext[:dir], only: ext[:only]).each do |dir|
+          candidates << [dir, "#{ext[:source]}:#{File.basename(dir)}"]
+        end
+      end
+
+      candidates.each_with_object([]) do |(dir, label), found|
+        begin
+          skill = AnthropicSkillParser.parse(dir)
+          path = skill && skill.md_file_path
+          next unless path && File.exist?(path)
+
+          found << label if Digest::SHA256.hexdigest(File.read(path)) == content_hash
+        rescue StandardError
+          next
+        end
+      end
+    end
+
+    # E2 helper. The knowledge ids whose knowledge_update records cite this hash
+    # as the body before or after the update. Each block's data is an array of
+    # JSON strings; an unparsable entry is skipped rather than fatal.
+    private def knowledge_ids_citing_body(content_hash)
+      ids = []
+      KairosChain::Chain.new(storage_backend: storage_backend).chain.each do |block|
+        data = block.respond_to?(:data) ? block.data : block['data']
+        Array(data).each do |raw|
+          record = begin
+            JSON.parse(raw.to_s)
+          rescue StandardError
+            nil
+          end
+          next unless record.is_a?(Hash)
+          next unless record['type'] == 'knowledge_update'
+          next unless [record['prev_hash'], record['next_hash']].include?(content_hash)
+
+          ids << record['knowledge_id'] if record['knowledge_id']
+        end
+      end
+      ids.uniq
+    end
+
     # List scripts in a knowledge skill
     #
     # @param name [String] Skill name
@@ -433,6 +810,10 @@ module KairosMcp
       content = File.read(skill.md_file_path)
       content_hash = Digest::SHA256.hexdigest(content)
 
+      # C2: `content` is the body being archived; keep it before the move
+      refusal = keep_bodies!(content)
+      return refusal if refusal
+
       dest_path = File.join(archived_dir, name)
       meta_path = File.join(dest_path, ARCHIVE_META_FILE)
 
@@ -532,6 +913,11 @@ module KairosMcp
       meta_file = archived_meta
       meta = File.exist?(meta_file) ? YAML.safe_load(File.read(meta_file)) : {}
 
+      # C2: read the archived body while it is still at the archived path
+      archived_body = File.read(AnthropicSkillParser.parse(archived_path).md_file_path)
+      refusal = keep_bodies!(archived_body)
+      return refusal if refusal
+
       # Move back to active
       FileUtils.mv(archived_path, active_path)
 
@@ -835,9 +1221,63 @@ module KairosMcp
       basename.match?(BACKUP_DIR_PATTERN)
     end
 
-    def record_hash_reference(name:, action:, prev_hash:, next_hash:, reason:)
-      chain = KairosChain::Chain.new(storage_backend: storage_backend)
-      chain.add_block([{
+    # Memoized body store
+    def history_store
+      @history_store ||= L1History.new(@knowledge_dir)
+    end
+
+    # C2: store every body whose hash enters the chain, before any write.
+    # nil = nothing to refuse (stored, or history inactive); hash = refusal.
+    def keep_bodies!(*bodies)
+      unless defined?(@history_active)
+        if L1History.enabled?
+          begin
+            FileUtils.mkdir_p(history_store.root)
+          rescue StandardError => e
+            # L2: no store root means nothing may be appended; stay unmemoized
+            # so a later write retries.
+            return { success: false, error: "history store unavailable: #{e.message}" }
+          end
+        end
+
+        @history_active = begin
+          history_store.sync_activation!(KairosChain::Chain.new(storage_backend: storage_backend))
+        rescue StandardError => e
+          # Chain unwritable: warn and fall back; never block L1 writes on activation
+          warn "[l1_history] activation sync failed: #{e.message}"
+          L1History.enabled?
+        end
+      end
+      return nil unless @history_active
+
+      bodies.compact.each do |body|
+        begin
+          history_store.store(body)
+        rescue StandardError => e
+          return { success: false, error: "history store failed: #{e.message}" }
+        end
+      end
+
+      nil
+    end
+
+    # Record a knowledge_update. A failed append is warned about and the caller
+    # continues (restore, which must undo its write, appends on its own path).
+    def record_hash_reference(name:, action:, prev_hash:, next_hash:, reason:, extra: {})
+      entry = hash_reference_entry(name: name, action: action, prev_hash: prev_hash,
+                                   next_hash: next_hash, reason: reason, extra: extra)
+      status, error = append_entry(entry, KairosChain::LandedProbe.mark(storage_backend: storage_backend))
+      unless status == :landed
+        # Log but don't fail if blockchain recording fails
+        warn "Failed to record to blockchain: #{error&.message || status}"
+        return
+      end
+
+      update_knowledge_meta(name, next_hash)
+    end
+
+    def hash_reference_entry(name:, action:, prev_hash:, next_hash:, reason:, extra: {})
+      {
         type: 'knowledge_update',
         layer: 'L1',
         knowledge_id: name,
@@ -846,22 +1286,40 @@ module KairosMcp
         next_hash: next_hash,
         reason: reason,
         timestamp: Time.now.iso8601
-      }.to_json])
+      }.merge(extra).to_json
+    end
 
-      # If using SQLite backend, also update knowledge metadata
-      if storage_backend.backend_type == :sqlite
-        meta = {
+    # Append one entry. => [status, error]. status is :landed when add_block
+    # returned, or when it raised but the entry is on the chain after `mark`
+    # (LandedProbe); otherwise :absent or :unknown, with the StandardError that
+    # add_block raised. An exception that is not a StandardError propagates;
+    # a caller that must undo something on failure probes again in its ensure.
+    def append_entry(entry, mark)
+      KairosChain::Chain.new(storage_backend: storage_backend).add_block([entry])
+      [:landed, nil]
+    rescue StandardError => e
+      [KairosChain::LandedProbe.status(mark, entry, storage_backend: storage_backend), e]
+    end
+
+    # SQLite keeps knowledge metadata beside the chain. Runs only after the
+    # record landed, and a failure here never reaches the record's caller: the
+    # chain already holds the change.
+    def update_knowledge_meta(name, next_hash)
+      return unless storage_backend.backend_type == :sqlite
+
+      if next_hash
+        skill = get(name)
+        storage_backend.save_knowledge_meta(name, {
           content_hash: next_hash,
-          version: get(name)&.version,
-          description: get(name)&.description,
-          tags: get(name)&.tags
-        }
-        storage_backend.save_knowledge_meta(name, meta) if next_hash
-        storage_backend.delete_knowledge_meta(name) unless next_hash
+          version: skill&.version,
+          description: skill&.description,
+          tags: skill&.tags
+        })
+      else
+        storage_backend.delete_knowledge_meta(name)
       end
     rescue StandardError => e
-      # Log but don't fail if blockchain recording fails
-      warn "Failed to record to blockchain: #{e.message}"
+      warn "[KnowledgeProvider] Recorded; knowledge metadata update failed: #{e.message}"
     end
 
     def storage_backend