kairos-chain 3.63.0 → 3.64.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 96a6f46091b47614f44d089e6459dde7e8435cf7caa893c9b335b7359ad25394
-  data.tar.gz: 965451d952fb8fa61d3bfcc581241242de0f25eb492dddc56ebe913e4d07683b
+  metadata.gz: 4ba66e678675e9b4e7776676832765d509f0ac7bb49feed159ee1513ba4b7318
+  data.tar.gz: 28af1484af3a0c98529603bfa30fd9ff188e5b18895c06c11a313bcf3a95d8b2
 SHA512:
-  metadata.gz: 1c3812249637a923526a17b29cbbf34549f3f3039f51ae37941fa990ceec99611d68e88de280b39ff673aaf5f64e55be3133b079578b9f2887df8a6a6c81f102
-  data.tar.gz: a3688710826e2de6bd2d05ee24b0f9c6194e32e6d9dd8587c776b5e3bfa1b614549af903eee8a9bac295b5e0efc36c5e50537d5a54b8352acd40e05f2ef291c1
+  metadata.gz: 67e98820708350d674970e3db49f3583efc01491ba8d58f5ecb702b988f64a5ad1efeb083637f45e77897c44dbb30a84569400431e8f669020fb13a2dae7b4aa
+  data.tar.gz: 27fef53ab90cdb4a7745955b49d41e3834d8313f0a0417605a96e21e84b0ab44fcb5c0e3ad27d9ff2cf698bda2a75c0dc7712869ab5e686daeb8cc468da77cdf

data/CHANGELOG.md

@@ -4,6 +4,44 @@ All notable changes to the `kairos-chain` gem will be documented in this file.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [3.64.0] - 2026-08-06
+
+### Fixed
+
+- **An append can no longer erase the chain history on disk.** Two paths
+  erased history before this release, both measured, neither raising an
+  exception: two holders of the chain at the same length both saved and the
+  second save replaced the disk sequence with its own; and a ledger that
+  existed but could not be read collapsed to nil, read as a fresh install,
+  and the next save rebuilt from genesis over it — 687 blocks became 2. An
+  append now takes a key file beside the ledger, re-reads and classifies the
+  disk under that key (absent / unreadable / empty / corrupt / readable),
+  refuses every state but `:readable` and `:absent`, and always builds on
+  the tail that is on disk at that moment. Failures on the read and write
+  side raise `Storage::Error` instead of flattening into nil or false, and
+  every reader consults `Chain#load_state` before trusting the sequence.
+  Includes the 3.62.1 locale fix, and one more of the same family: while
+  the ledger does not yet exist, a symlinked name resolves to its target
+  before the lock key is derived, so a fresh install reached through two
+  names is written under one key (measured pre-fix: 51 blocks shrank to
+  35–49 under concurrent two-name appends). Verified by 149 assertions and
+  a 34-row falsification harness in which each protective mechanism is
+  removed in isolation and its named check confirmed to go red.
+
+## [3.62.1] - 2026-08-06
+
+### Fixed
+
+- **A non-UTF-8 locale no longer erases the ledger on the next append.**
+  Emergency hotfix cut from the shipped 3.62.0 (branch
+  `hotfix/utf8-ledger-read`): `FileBackend#load_blocks` read
+  `blockchain.json` with the locale-derived default encoding, so a
+  LANG-unset start (launchd, cron, plain containers) made a non-ASCII
+  ledger unparseable, the failure was flattened into "no ledger", and one
+  ordinary append overwrote 705 blocks with 2 (measured on a copy of a
+  production ledger). The ledger is now read as UTF-8 explicitly. This is
+  the only change over 3.62.0; 3.64.0 contains the full erasure fix.
+
 ## [3.63.0] - 2026-08-06
 
 ### Changed

data/lib/kairos_mcp/admin/router.rb

@@ -346,6 +346,7 @@ module KairosMcp
 
         html_response(200, render_partial('_chain_blocks',
                                           blocks: paged_blocks,
+                                          load_state: chain.load_state,
                                           total: total,
                                           limit: limit,
                                           offset: offset))
@@ -353,6 +354,10 @@ module KairosMcp
 
       def handle_chain_block_detail_partial(index)
         chain = KairosChain::Chain.new
+        unless chain.valid?
+          return html_response(200, "<p>Block ##{index} unavailable: ledger is #{chain.load_state}.</p>")
+        end
+
         block = chain.chain.find { |b| b.respond_to?(:index) ? b.index == index : b['index'] == index }
 
         if block
@@ -364,13 +369,17 @@ module KairosMcp
 
       def handle_chain_verify_partial
         chain = KairosChain::Chain.new
-        valid = chain.valid?
-        length = chain.chain.length
 
-        result = if valid
-                   "<div class='flash flash-success'>Chain is valid. #{length} blocks verified.</div>"
+        # Three outcomes: a ledger that does not exist yet is not a failure.
+        result = case chain.load_state
+                 when :readable
+                   "<div class='flash flash-success'>Chain is valid. " \
+                     "#{chain.chain.length} blocks verified.</div>"
+                 when :absent
+                   "<div class='flash'>Chain not created yet. Nothing to verify.</div>"
                  else
-                   "<div class='flash flash-error'>Chain integrity check FAILED!</div>"
+                   "<div class='flash flash-error'>Chain integrity check FAILED! " \
+                     "(state: #{chain.load_state})</div>"
                  end
         html_response(200, result)
       end
@@ -475,17 +484,20 @@ module KairosMcp
         backend = SkillsConfig.storage_backend
 
         latest = chain.latest_block
-        latest_h = latest.respond_to?(:to_h) ? latest.to_h : latest
+        latest_h = latest.respond_to?(:to_h) ? latest&.to_h : latest
 
         {
           valid: chain.valid?,
+          state: chain.load_state,
           length: chain.chain.length,
           storage: { backend: backend },
           latest_block: latest_h
         }
       rescue StandardError => e
-        { valid: false, length: 0, storage: { backend: 'unknown' },
-          latest_block: {}, error: e.message }
+        # Chain.new does not raise; this branch is reachable only for failures
+        # outside the ledger (config, rendering). It must not fabricate a state.
+        { valid: false, state: :error, length: 0, storage: { backend: 'unknown' },
+          latest_block: nil, error: e.message }
       end
 
       def fetch_knowledge_list(search: nil)

data/lib/kairos_mcp/admin/views/chain.erb

@@ -11,13 +11,18 @@
     <div>
       <p>
         <strong>Status:</strong>
+        <%# Three displays, not two: an absent ledger is a fresh install. %>
         <% if chain[:valid] %>
           <span class="badge badge-success">Valid</span>
+        <% elsif chain[:state] == :absent %>
+          <span class="badge">Not created yet</span>
         <% else %>
-          <span class="badge badge-error">Invalid</span>
+          <span class="badge badge-error">Invalid (<%= h(chain[:state].to_s) %>)</span>
         <% end %>
       </p>
-      <p><strong>Length:</strong> <%= chain[:length] %> blocks</p>
+      <% if chain[:valid] %>
+        <p><strong>Length:</strong> <%= chain[:length] %> blocks</p>
+      <% end %>
     </div>
     <div>
       <p><strong>Backend:</strong> <%= h(chain.dig(:storage, :backend) || 'unknown') %></p>

data/lib/kairos_mcp/admin/views/dashboard.erb

@@ -9,13 +9,18 @@
   <article>
     <header>Blockchain</header>
     <p>
+      <%# Three displays, not two: an absent ledger is a fresh install. %>
       <% if chain[:valid] %>
         <span class="badge badge-success">Valid</span>
+      <% elsif chain[:state] == :absent %>
+        <span class="badge">Not created yet</span>
       <% else %>
-        <span class="badge badge-error">Invalid</span>
+        <span class="badge badge-error">Invalid (<%= h(chain[:state].to_s) %>)</span>
       <% end %>
     </p>
-    <p><strong><%= chain[:length] %></strong> blocks</p>
+    <% if chain[:valid] %>
+      <p><strong><%= chain[:length] %></strong> blocks</p>
+    <% end %>
     <p><small>Backend: <%= h(chain.dig(:storage, :backend) || 'unknown') %></small></p>
     <footer><a href="/admin/chain">View Chain &rarr;</a></footer>
   </article>

data/lib/kairos_mcp/admin/views/partials/_chain_blocks.erb

@@ -1,5 +1,13 @@
 <% if blocks.empty? %>
-  <p>No blocks found.</p>
+  <%# Three displays, not two: an absent ledger is a fresh install, and an
+      unreadable one must not be reported as an empty history. %>
+  <% if load_state == :readable %>
+    <p>No blocks found.</p>
+  <% elsif load_state == :absent %>
+    <p>Chain not created yet.</p>
+  <% else %>
+    <p>History unavailable: ledger is <%= h(load_state.to_s) %>.</p>
+  <% end %>
 <% else %>
   <div class="overflow-auto">
     <table>

data/lib/kairos_mcp/drift_detection/correspondence_checker.rb

@@ -64,7 +64,23 @@ module KairosMcp
           end
 
           active = Digest::SHA256.hexdigest(File.read(md_file_path))
-          recorded = recorded_digest_for(name, storage_backend)
+
+          chain = KairosChain::Chain.new(storage_backend: storage_backend)
+          # :absent completes normally: a fresh install has no ledger, the scan
+          # over zero blocks finds nothing, and :missing_record is the honest
+          # verdict. The other failed states mean provenance is UNAVAILABLE,
+          # which is not the same claim as "never recorded" — reporting
+          # :missing_record there would accuse every artifact whenever the
+          # ledger cannot be read.
+          unless chain.valid? || chain.load_state == :absent
+            return Result.new(
+              status: :error, name: name,
+              active_digest: active, recorded_digest: nil,
+              message: "L1 '#{name}': provenance unavailable — ledger state is #{chain.load_state}"
+            )
+          end
+
+          recorded = recorded_digest_for(name, chain)
 
           if recorded.nil?
             return Result.new(
@@ -101,8 +117,7 @@ module KairosMcp
         # the most recent knowledge_update record, scanning the chain from head
         # backward. Returns nil when the most recent relevant record removed the
         # artifact (next_hash nil — delete/archive) or when none exists.
-        def recorded_digest_for(name, storage_backend)
-          chain = KairosChain::Chain.new(storage_backend: storage_backend)
+        def recorded_digest_for(name, chain)
           chain.chain.reverse_each do |block|
             Array(block.data).each do |entry|
               record = parse_entry(entry)

data/lib/kairos_mcp/kairos_chain/chain.rb

@@ -1,97 +1,347 @@
 require_relative 'block'
 require_relative 'merkle_tree'
 require 'json'
+require 'time'
 require 'fileutils'
+require_relative '../storage/backend'
 require_relative '../../kairos_mcp'
 
 module KairosMcp
   module KairosChain
+    # Raised when the ledger's state on disk forbids appending, when a re-entrant
+    # append is attempted, or when the storage backend does not declare the
+    # contract of INV-G. Nothing has been written to the ledger; the lock file and
+    # its parent directory may have been created.
+    #
+    # #state carries one of Chain::LOAD_STATES.
+    class ChainStateError < StandardError
+      attr_reader :state
+
+      def initialize(message, state:)
+        super(message)
+        @state = state
+      end
+    end
+
+    # INV-D: an append may only add a block to the end of the sequence that is on
+    #        disk at that moment. The in-memory sequence never replaces the one on
+    #        disk. When the sequence on disk cannot be determined, nothing is
+    #        appended.
+    # INV-E: the ledger's state is carried by one entrance that every reader
+    #        passes through (#load_state), not by the block sequence.
+    # INV-G: under a backend that does not declare its contract, Chain refuses to
+    #        append and reads the ledger as unreadable.
     class Chain
-      attr_reader :chain
+      # The five values #load_state can take. Only :readable and :absent permit an
+      # append; only :readable makes #chain / #latest_block meaningful.
+      LOAD_STATES = %i[absent unreadable empty corrupt readable].freeze
 
-      # Initialize the chain
-      #
-      # @param chain_file [String] Path to blockchain file (for backward compatibility)
-      # @param storage_backend [Storage::Backend, nil] Storage backend to use
+      # Re-entrancy flag. Thread-level (not fiber-level) on purpose: an append may
+      # cross fibers, and a nested append would deadlock on its own flock.
+      APPEND_FLAG = :kairos_chain_append_in_progress
+
+      EMPTY_CHAIN = [].freeze
+
+      attr_reader :load_state
+
+      # @param chain_file [String, nil] dead argument, kept for call-site compatibility
+      # @param storage_backend [Storage::Backend, nil] storage backend to use
+      # Constructing the default backend can itself fail — a malformed config
+      # scalar, a data directory that cannot be created on a read-only or full
+      # mount. That construction is therefore deferred into the protected region
+      # of classify_disk; doing it here would put it outside every rescue and
+      # break "Chain.new never raises".
       def initialize(chain_file: nil, storage_backend: nil)
-        chain_file ||= KairosMcp.blockchain_path
+        # FIX B — NEW CLAIM: Chain.new resolves no paths of its own, so it
+        # returns an object for every input. KairosMcp.blockchain_path here ran
+        # outside every rescue and raised for an unresolvable data directory
+        # (KAIROS_DATA_DIR='~nosuchuser/…' → ArgumentError; deleted CWD →
+        # Errno::ENOENT from Dir.pwd — both measured). @chain_file is dead
+        # (assigned, never read); the argument is kept for call-site
+        # compatibility only. Path resolution now happens solely inside
+        # classify_disk's protected region, where it degrades to :unreadable.
         @chain_file = chain_file
-        @storage_backend = storage_backend || default_storage_backend
-        @chain = load_chain || [Block.genesis]
+        @storage_backend = storage_backend
+        @load_state, @chain = classify_disk
+      end
+
+      # The block sequence, but only when the ledger was readable. Every other
+      # state yields a frozen empty array: callers must consult #load_state first.
+      def chain
+        @load_state == :readable ? @chain : EMPTY_CHAIN
       end
 
       def latest_block
-        @chain.last
+        @load_state == :readable ? @chain.last : nil
+      end
+
+      # An alias for "the ledger was readable". Not a separate integrity pass:
+      # the four predicates of §3 already ran during classification.
+      def valid?
+        @load_state == :readable
       end
 
+      # Append one block to whatever is on disk right now.
+      #
+      # @return [Block] the appended block
+      # @raise [ChainStateError] nothing was written to the ledger
+      # @raise [Storage::Error] it is unknown whether the write landed; re-read
       def add_block(data)
-        # Ensure data is array of strings (serialize if needed)
-        normalized_data = data.map { |d| d.is_a?(String) ? d : d.to_json }
+        # ⓪ flag first, before the lock: a nested append would deadlock on its own
+        #    flock. The path question is asked here too, so a backend that answers
+        #    a relative path is refused before any file is created.
+        if Thread.current.thread_variable_get(APPEND_FLAG)
+          raise ChainStateError.new(
+            'append already in progress on this thread (nested append is forbidden)',
+            state: @load_state
+          )
+        end
+        path = ledger_path
 
-        # 1. Create Merkle Root from data
-        merkle_tree = MerkleTree.new(normalized_data)
-        merkle_root = merkle_tree.root
+        Thread.current.thread_variable_set(APPEND_FLAG, true)
+        begin
+          # ① take the key (a file beside the ledger, never the ledger itself)
+          with_lock(path) do
+            # ② read disk and classify
+            state, disk_blocks = classify_disk
 
-        # 2. Create new block
-        new_block = Block.new(
-          index: latest_block.index + 1,
-          timestamp: Time.now.utc,
-          data: normalized_data,
-          previous_hash: latest_block.hash,
-          merkle_root: merkle_root
-        )
+            # ③ refuse anything that is neither readable nor absent
+            unless %i[readable absent].include?(state)
+              raise ChainStateError.new("cannot append: ledger is #{state}", state: state)
+            end
+
+            # ④ the base is the disk sequence, or a genesis-only sequence
+            base = state == :readable ? disk_blocks : [Block.genesis]
 
-        # 3. Add to chain
-        @chain << new_block
-        
-        # 4. Persist
-        save_chain
-        
-        new_block
+            # ⑤ build on the base's tail and write base + new
+            new_block = build_block(base.last, data)
+            appended = base + [new_block]
+            storage_backend.save_all_blocks(appended.map(&:to_h))
+
+            # ⑥ only a successful write advances this instance's sequence and state
+            @chain = appended
+            @load_state = :readable
+
+            new_block
+          end
+        ensure
+          # ⑦ lower the flag — reached only by the call that raised it, because ⓪
+          #    raises before this begin block
+          Thread.current.thread_variable_set(APPEND_FLAG, nil)
+        end
       end
 
-      def valid?
-        @chain.each_with_index do |block, i|
-          next if i == 0 # Skip genesis block
+      # @return [Symbol] :file, :sqlite, ... or :unavailable when the backend
+      #   could not be constructed
+      def storage_type
+        storage_backend.backend_type
+      rescue StandardError
+        :unavailable
+      end
 
-          previous_block = @chain[i - 1]
+      private
 
-          # 1. Check previous_hash reference
-          return false if block.previous_hash != previous_block.hash
+      # Memoised so the construction is attempted once and its failure is a
+      # failure of the read, not of the object.
+      def storage_backend
+        @storage_backend ||= Storage::Backend.default
+      end
 
-          # 2. Check block hash integrity
-          return false if block.hash != block.calculate_hash
-          
-          # 3. Check Merkle Root integrity
-          calculated_merkle_root = MerkleTree.new(block.data).root
-          return false if block.merkle_root != calculated_merkle_root
+      # INV-G's question: "state the absolute path of your ledger". A backend that
+      # does not answer cannot be appended to; an answer that is not absolute is a
+      # CWD-dependent key, which is a silent loss of exclusion.
+      def ledger_path
+        backend = begin
+          storage_backend
+        rescue StandardError => e
+          raise ChainStateError.new("storage backend unavailable: #{e.message}", state: @load_state)
         end
 
-        true
+        unless backend.respond_to?(:blockchain_file)
+          raise ChainStateError.new(
+            "storage backend #{backend.class} does not declare its ledger path",
+            state: @load_state
+          )
+        end
+
+        path = backend.blockchain_file
+        unless path.is_a?(String) && !path.empty? && File.absolute_path?(path)
+          raise Storage::Error, "storage backend answered a non-absolute ledger path: #{path.inspect}"
+        end
+
+        path
       end
 
-      def save_chain
-        @storage_backend.save_all_blocks(@chain.map(&:to_h))
+      # (あ) the key is a separate file — locking the ledger itself makes a fresh
+      #      install permanently unwritable.
+      # (う) the key file is never unlinked — a deleted key file lets a later
+      #      locker take a different inode and exclusion is lost in silence.
+      def with_lock(path)
+        # Only the key's own I/O is wrapped — a failure inside the yield must
+        # not come back wearing the "lock unavailable" label.
+        # FIX C — NEW CLAIM: every name that reaches one ledger takes one key.
+        # The key path is canonicalised BEFORE ".lock" is appended. The R1
+        # withdrawal of exactly this fix rested on a half-refuted premise: its
+        # fixture ("dir/x", "dir/./x", a symlinked DIRECTORY) does resolve to
+        # one lock inode, because the kernel resolves those inside the lock
+        # path itself — but "link.json.lock" is its own name, so a symlink to
+        # the ledger FILE split the lock ("real.json.lock" vs "link.json.lock";
+        # measured over 8 runs of 2×60 appends: 4 to 21 of 120 blocks lost,
+        # every run, silently — it is a race, so the count varies).
+        # FIX F — NEW CLAIM: a name reaches one key even while the ledger does
+        # not yet exist. R3 refuted FIX C's fallback (four reviewers
+        # independently): while the ledger is absent — a fresh install reached
+        # through two names — realpath fails with ENOENT, the fallback keyed on
+        # the UNRESOLVED basename, and the premise "a ledger realpath cannot
+        # resolve is one classify_disk cannot stat either" is false for exactly
+        # that state, because :absent permits an append (measured: 51 blocks
+        # shrank to 35–49). realdirpath resolves the final component's symlink
+        # without requiring its target to exist, so both names converge on the
+        # target's spelling before any ledger byte exists. The basename
+        # fallback remains only for names realdirpath itself refuses, and no
+        # append completes a write through such a name: ELOOP and EPERM fail
+        # classify_disk's stat (refused as :unreadable), and a symlink whose
+        # target directory is missing classifies :absent but the write through
+        # it fails with ENOENT before any ledger byte lands. Hard links to the
+        # same ledger remain outside what any path-derived key can reach:
+        # realpath cannot distinguish them. The design records this as
+        # limitation L-2 in its "what this does not close" section — it is NOT
+        # in the §7 scope-exclusion list, so it is an acknowledged open hole
+        # rather than a deferred item. An I/O failure while deriving the key
+        # (the directory itself unresolvable) still surfaces as Storage::Error,
+        # as before.
+        lock_path = nil
+        handle = begin
+          FileUtils.mkdir_p(File.dirname(path))
+          canonical = begin
+            File.realpath(path)
+          rescue SystemCallError
+            begin
+              File.realdirpath(path)
+            rescue SystemCallError
+              File.join(File.realpath(File.dirname(path)), File.basename(path))
+            end
+          end
+          lock_path = "#{canonical}.lock"
+          File.open(lock_path, File::RDWR | File::CREAT, 0o644)
+        rescue SystemCallError, IOError => e
+          raise Storage::Error, "ledger lock unavailable (#{lock_path || path}): #{e.message}"
+        end
+
+        completed = false
+        begin
+          begin
+            handle.flock(File::LOCK_EX)
+          rescue SystemCallError, IOError => e
+            raise Storage::Error, "ledger lock unavailable (#{lock_path}): #{e.message}"
+          end
+          result = yield
+          completed = true
+          result
+        ensure
+          # Closing the key must never replace an exception already on its way
+          # out: the caller's rule is read off the exception's class, and an
+          # IOError from close would erase the Storage::Error that told the
+          # caller to re-read. Whether the body finished is tracked explicitly
+          # rather than read off $!, which inside an ensure also carries an
+          # exception being handled further up the stack — under a caller that
+          # wraps add_block in a rescue, $! is non-nil even on the normal path
+          # and a close failure would be swallowed.
+          begin
+            handle.close
+          rescue StandardError => e
+            raise Storage::Error, "ledger lock close failed (#{lock_path}): #{e.message}" if completed
+          end
+        end
       end
 
-      # Get the storage backend type
-      # @return [Symbol] :file or :sqlite
-      def storage_type
-        @storage_backend.backend_type
+      def build_block(tail, data)
+        normalized_data = data.map { |d| d.is_a?(String) ? utf8_for_ledger(d) : d.to_json }
+
+        Block.new(
+          index: tail.index + 1,
+          timestamp: Time.now.utc,
+          data: normalized_data,
+          previous_hash: tail.hash,
+          merkle_root: MerkleTree.new(normalized_data).root
+        )
       end
 
-      private
+      # FIX A — NEW CLAIM: any String add_block accepts round-trips through the
+      # ledger byte-identically — the bytes MerkleTree and Block hash are the
+      # bytes JSON.pretty_generate writes. Decision: a String already in valid
+      # UTF-8 passes unchanged; one in another valid encoding is transcoded to
+      # its UTF-8 spelling (which IS its ledger representation); one holding
+      # bytes invalid for its own encoding raises EncodingError before anything
+      # is written. Before this, hashing the original bytes and writing the
+      # transcoded ones made one ISO-8859-1 append classify a healthy 7-block
+      # ledger :corrupt on reload (measured) — history unreachable, no raise.
+      def utf8_for_ledger(text)
+        utf8 = text.encode(Encoding::UTF_8)
+        # encode is a no-op when source and destination are both UTF-8, so
+        # invalid bytes under a UTF-8 label must be refused explicitly.
+        unless utf8.valid_encoding?
+          raise EncodingError,
+                "block data is not valid #{text.encoding.name}: it cannot round-trip through the ledger"
+        end
+        utf8
+      end
 
-      def default_storage_backend
-        require_relative '../storage/backend'
-        Storage::Backend.default
+      # The single entrance of INV-E. Never raises: every failure becomes one of
+      # the five states.
+      #
+      # @return [Array(Symbol, Array<Block>)]
+      def classify_disk
+        # A backend that cannot even be built is a channel we cannot read
+        # through, not data we have judged. It is the :unreadable case.
+        backend = begin
+          storage_backend
+        rescue StandardError => e
+          note "[Chain] storage backend unavailable: #{e.message}"
+          return [:unreadable, []]
+        end
+
+        # The dividing line: only a backend that declared the contract has its
+        # return read in three shapes. Anything else reads as unreadable.
+        return [:unreadable, []] unless backend.respond_to?(:blockchain_file)
+
+        raw = backend.load_blocks
+        return [:absent, []] if raw.nil?
+
+        blocks = rebuild(raw)
+        return [:empty, []] if blocks.empty?
+        return [:corrupt, []] unless well_formed?(blocks)
+
+        [:readable, blocks]
+      rescue Storage::Error => e
+        note "[Chain] ledger unreadable: #{e.message}"
+        [:unreadable, []]
+      rescue StandardError => e
+        # Totality: an exception raised while rebuilding or while evaluating a
+        # predicate is itself corruption, not a crash.
+        note "[Chain] ledger corrupt: #{e.message}"
+        [:corrupt, []]
       end
 
-      def load_chain
-        blocks_data = @storage_backend.load_blocks
-        return nil unless blocks_data
+      # FIX D — NEW CLAIM: diagnostic output can never change the outcome of a
+      # classification. warn writes to $stderr, and these calls sit inside
+      # classify_disk's rescue branches: when $stderr has been replaced by a
+      # closed or failing writer, warn raises IOError there and escapes
+      # Chain.new (measured with a closed StringIO as $stderr; a close of the
+      # real STDERR alone does not reproduce — MRI falls back to the C-level
+      # stderr). StandardError, not just IOError, because the claim is about
+      # any failing writer, not one failure class of the real console.
+      def note(message)
+        warn message
+      rescue StandardError
+        # the diagnostic is lost; the classification is not
+      end
 
-        blocks_data.map do |block_data|
+      # Classification runs on the rebuilt sequence, not on the backend's raw
+      # array: timestamps are strings there, and the stored `hash` column is
+      # discarded on load, so predicate 3 compares recomputed hashes.
+      def rebuild(raw)
+        raw.map do |block_data|
           Block.new(
             index: block_data[:index],
             timestamp: parse_timestamp(block_data[:timestamp]),
@@ -100,9 +350,27 @@ module KairosMcp
             merkle_root: block_data[:merkle_root]
           )
         end
-      rescue StandardError => e
-        warn "[Chain] Failed to load chain: #{e.message}"
-        nil
+      end
+
+      def well_formed?(blocks)
+        # 1. block 0 is the canonical genesis. Comparing recomputed hashes covers
+        #    exactly the five columns of Block.genesis and nothing else.
+        return false unless blocks.first.hash == Block.genesis.hash
+
+        blocks.each_with_index do |block, i|
+          # 2. indexes run from 0, one at a time
+          return false unless block.index == i
+          next if i.zero?
+
+          # 3. each previous_hash matches the recomputed hash before it
+          return false unless block.previous_hash == blocks[i - 1].hash
+
+          # 4. from block 1 on, the Merkle root matches recomputation from data.
+          #    Genesis is excluded: its merkle_root is the constant filler 0…0.
+          return false unless block.merkle_root == MerkleTree.new(block.data).root
+        end
+
+        true
       end
 
       def parse_timestamp(timestamp)

data/lib/kairos_mcp/storage/backend.rb

@@ -2,6 +2,13 @@
 
 module KairosMcp
   module Storage
+    # Raised when a read or a write against the ledger fails, and when the key or
+    # the ledger path cannot be used. It wraps the underlying exception as #cause.
+    #
+    # For a write, this means **it is unknown whether the write landed**. It must
+    # not be read as "nothing was written" — re-read the ledger to find out.
+    class Error < StandardError; end
+
     # Abstract base class for storage backends
     #
     # KairosChain supports two storage backends:
@@ -34,7 +41,15 @@ module KairosMcp
       # ===========================================================================
 
       # Load all blocks from storage
-      # @return [Array<Hash>, nil] Array of block data or nil if not found
+      #
+      # Read contract (a backend that declares #blockchain_file must honour it):
+      # nil is returned **only when the ledger does not exist**. A ledger that
+      # cannot be opened or cannot be parsed (including a zero-byte file) raises
+      # Storage::Error. Collapsing those into nil would let a damaged ledger pass
+      # as "absent" and be rebuilt from genesis.
+      #
+      # @return [Array<Hash>, nil] Array of block data, or nil when absent
+      # @raise [Storage::Error] the ledger exists but could not be read
       def load_blocks
         raise NotImplementedError, "#{self.class}#load_blocks must be implemented"
       end
@@ -47,8 +62,14 @@ module KairosMcp
       end
 
       # Save all blocks to storage (for file backend bulk write)
+      #
+      # Write contract: failure raises Storage::Error. Returning false for a
+      # failed write is forbidden — the caller cannot distinguish "refused" from
+      # "wrote and then failed", and a false return reads as a benign result.
+      #
       # @param blocks [Array<Hash>] Array of block data
-      # @return [Boolean] Success status
+      # @return [Boolean] true
+      # @raise [Storage::Error] the write failed or its outcome is unknown
       def save_all_blocks(blocks)
         raise NotImplementedError, "#{self.class}#save_all_blocks must be implemented"
       end
@@ -142,6 +163,14 @@ module KairosMcp
         raise NotImplementedError, "#{self.class}#backend_type must be implemented"
       end
 
+      # INV-G — the contract question is a single one: "state the absolute path of
+      # your ledger". A backend answers it by defining #blockchain_file. This base
+      # class deliberately does not, so a backend that has not been written
+      # against the append procedure of INV-D (sqlite's INSERT OR REPLACE never
+      # truncates the sequence; postgresql is registered by a SkillSet) is refused
+      # rather than silently driven by a file-shaped procedure. Under such a
+      # backend, Chain refuses to append and reads the ledger as unreadable.
+
       # ===========================================================================
       # Factory Method
       # ===========================================================================

data/lib/kairos_mcp/storage/file_backend.rb

@@ -32,16 +32,50 @@ module KairosMcp
       # Block Operations
       # ===========================================================================
 
+      # Read contract (see Backend#load_blocks): nil means the ledger does not
+      # exist, and nothing else. A ledger that exists but cannot be opened or
+      # parsed — a zero-byte file included — raises Storage::Error. Returning nil
+      # there would make a damaged ledger indistinguishable from a fresh install,
+      # and the next append would rebuild from genesis over it.
       def load_blocks
-        return nil unless File.exist?(@blockchain_file)
+        # Absence is decided by stat, not by File.exist?. File.exist? answers
+        # false for EVERY stat(2) failure, not only ENOENT — an unsearchable
+        # parent directory, a symlink loop, EIO on a network mount, or a macOS
+        # ACL denying readattr all read as "no ledger here". Measured on darwin
+        # 23.6: with `chmod +a "user deny readattr"` on the ledger, File.exist?
+        # is false while File.read and File.write both still succeed, so the
+        # ledger classified :absent and the next append rebuilt from genesis
+        # over it — 6 blocks became 2. Only ENOENT and ENOTDIR mean the ledger
+        # is not there; every other stat failure means we cannot tell.
+        begin
+          File.stat(@blockchain_file)
+        rescue Errno::ENOENT, Errno::ENOTDIR
+          return nil
+        rescue SystemCallError => e
+          raise Storage::Error,
+                "cannot determine whether ledger #{@blockchain_file} exists: #{e.message}"
+        end
+
+        # FIX E — NEW CLAIM: the bytes on disk alone decide the classification;
+        # the process locale never does. The ledger is always written as UTF-8,
+        # but File.read without an encoding tags the bytes with the locale-derived
+        # default. Started with LANG unset (launchd, cron, plain containers), a
+        # ledger holding non-ASCII text then fails the parse and a healthy 705-block
+        # ledger reads :corrupt (measured on a copy of a production ledger; the
+        # shipped pre-fix code went further and erased it to 2 blocks on the next
+        # append). The bytes were never wrong — only the read was.
+        json_data = JSON.parse(File.read(@blockchain_file, encoding: Encoding::UTF_8), symbolize_names: true)
+        unless json_data.is_a?(Array)
+          raise Storage::Error, "ledger #{@blockchain_file} is not a JSON array (got #{json_data.class})"
+        end
 
-        json_data = JSON.parse(File.read(@blockchain_file), symbolize_names: true)
         json_data.map do |block_data|
           normalize_block_data(block_data)
         end
-      rescue JSON::ParserError, ArgumentError => e
-        warn "[FileBackend] Failed to load blocks: #{e.message}"
-        nil
+      rescue Storage::Error
+        raise
+      rescue JSON::ParserError, ArgumentError, SystemCallError, IOError, NoMethodError, TypeError => e
+        raise Storage::Error, "failed to load blocks from #{@blockchain_file}: #{e.message}"
       end
 
       def save_block(block)
@@ -50,13 +84,15 @@ module KairosMcp
         save_all_blocks(blocks)
       end
 
+      # Write contract (see Backend#save_all_blocks): failure raises
+      # Storage::Error. The previous `false` return collapsed every failure into
+      # a value that reads as benign at the call site.
       def save_all_blocks(blocks)
         FileUtils.mkdir_p(File.dirname(@blockchain_file))
         File.write(@blockchain_file, JSON.pretty_generate(blocks.map { |b| block_to_hash(b) }))
         true
       rescue StandardError => e
-        warn "[FileBackend] Failed to save blocks: #{e.message}"
-        false
+        raise Storage::Error, "failed to save blocks to #{@blockchain_file}: #{e.message}"
       end
 
       def all_blocks

data/lib/kairos_mcp/tools/chain_history.rb

@@ -80,9 +80,13 @@ module KairosMcp
         blocks = blocks.first(limit)
         
         if format == 'json'
-          text_content(JSON.pretty_generate(blocks.map(&:to_h)))
+          # Breaking change: the JSON payload is an object, not a bare array. An
+          # array cannot carry the ledger state, and an empty array from an
+          # unreadable ledger is indistinguishable from an empty history.
+          text_content(JSON.pretty_generate(state: chain.load_state,
+                                            blocks: blocks.map(&:to_h)))
         else
-          format_blocks(blocks)
+          format_blocks(blocks, chain.load_state)
         end
       end
 
@@ -107,12 +111,17 @@ module KairosMcp
         end
       end
 
-      def format_blocks(blocks)
+      def format_blocks(blocks, load_state)
         output = "Blockchain History\n"
         output += "=" * 50 + "\n\n"
+        output += "Ledger state: #{load_state}\n\n"
 
         if blocks.empty?
-          output += "(No blocks found)\n"
+          output += case load_state
+                    when :readable then "(No blocks found)\n"
+                    when :absent then "(Blockchain not created yet)\n"
+                    else "(History unavailable: ledger is #{load_state})\n"
+                    end
           return text_content(output)
         end
 

data/lib/kairos_mcp/tools/chain_status.rb

@@ -54,11 +54,15 @@ module KairosMcp
           storage_info[:wal_mode] = sqlite_config['wal_mode']
         end
         
+        # The ledger's state comes first; `length` and `latest_block` only carry
+        # meaning when the state is :readable. `latest_block` is nil otherwise
+        # (breaking change for consumers that assumed a hash).
         status = {
           valid: chain.valid?,
+          state: chain.load_state,
           length: chain.chain.length,
           storage: storage_info,
-          latest_block: chain.latest_block.to_h
+          latest_block: chain.latest_block&.to_h
         }
         
         text_content(JSON.pretty_generate(status))

data/lib/kairos_mcp/tools/chain_verify.rb

@@ -42,12 +42,16 @@ module KairosMcp
 
       def call(arguments)
         chain = KairosChain::Chain.new
-        is_valid = chain.valid?
-        
-        if is_valid
+
+        # Three outcomes, not two: a ledger that does not exist yet is a fresh
+        # install, not a corrupted one.
+        case chain.load_state
+        when :readable
           text_content("Blockchain Integrity Verified: OK (Length: #{chain.chain.length})")
+        when :absent
+          text_content('Blockchain not created yet (state: absent). Nothing to verify.')
         else
-          text_content("Blockchain Integrity Check FAILED! Chain may be corrupted.")
+          text_content("Blockchain Integrity Check FAILED! (state: #{chain.load_state})")
         end
       end
     end

data/lib/kairos_mcp/tools/formalization_history.rb

@@ -68,6 +68,20 @@ module KairosMcp
         limit = (arguments['limit'] || 20).to_i
 
         chain = KairosChain::Chain.new
+
+        # Three outcomes, not two: an absent ledger is a fresh install with
+        # nothing recorded yet, and the failed states must be named rather than
+        # reported as "no decisions found".
+        case chain.load_state
+        when :readable # fall through to the scan
+        when :absent
+          return text_content('No formalization decisions: blockchain not created yet.')
+        else
+          return text_content(
+            "Cannot scan formalization decisions: ledger state is #{chain.load_state}."
+          )
+        end
+
         decisions = []
 
         # Scan all blocks for formalization decisions

data/lib/kairos_mcp/version.rb

@@ -1,4 +1,4 @@
 module KairosMcp
-  VERSION = "3.63.0"
+  VERSION = "3.64.0"
   CHANGELOG_URL = "https://github.com/masaomi/KairosChain_2026/blob/main/CHANGELOG.md"
 end

data/templates/skillsets/introspection/lib/introspection/safety_inspector.rb

@@ -71,13 +71,17 @@ module KairosMcp
         def inspect_blockchain_health
           chain = ::KairosMcp::KairosChain::Chain.new
           blocks = chain.chain
+
+          # block_count and last_recorded only carry meaning when the ledger's
+          # state is :readable; the state itself is the load-bearing field.
           {
+            state: chain.load_state,
             block_count: blocks.size,
             last_recorded: blocks.last&.timestamp&.iso8601,
             integrity: chain.valid?
           }
         rescue StandardError => e
-          { block_count: 0, integrity: false, error: e.message }
+          { state: :error, block_count: 0, integrity: false, error: e.message }
         end
       end
     end

data/templates/skillsets/introspection/tools/introspection_check.rb

@@ -91,16 +91,27 @@ module KairosMcp
 
           def check_blockchain
             chain = ::KairosMcp::KairosChain::Chain.new
-            valid = chain.valid?
+            state = chain.load_state
             blocks = chain.chain
+
+            # Three outcomes, not two: a ledger that does not exist yet is a
+            # fresh install, not an integrity failure. block_count and
+            # latest_timestamp only carry meaning when the state is :readable.
+            status = case state
+                     when :readable then 'healthy'
+                     when :absent then 'not_created_yet'
+                     else 'INTEGRITY_FAILURE'
+                     end
+
             {
-              valid: valid,
+              valid: chain.valid?,
+              state: state,
               block_count: blocks.size,
               latest_timestamp: blocks.last&.timestamp&.iso8601,
-              status: valid ? 'healthy' : 'INTEGRITY_FAILURE'
+              status: status
             }
           rescue StandardError => e
-            { valid: false, error: e.message, status: 'error' }
+            { valid: false, state: :error, error: e.message, status: 'error' }
           end
 
           def build_recommendations(report)
@@ -119,9 +130,19 @@ module KairosMcp
               end
             end
 
-            # Blockchain issues
-            if report[:blockchain] && !report[:blockchain][:valid]
-              recs << { priority: 'critical', target: 'blockchain', message: 'Blockchain integrity check failed.' }
+            # Blockchain issues. A ledger that does not exist yet is a fresh
+            # install, not an integrity failure — keying off :valid alone would
+            # raise a critical alarm on every new installation.
+            blockchain = report[:blockchain]
+            if blockchain && !blockchain[:valid]
+              case blockchain[:state]&.to_sym
+              when :absent
+                recs << { priority: 'low', target: 'blockchain',
+                          message: 'Blockchain not created yet. It is written on the first recorded change.' }
+              else
+                recs << { priority: 'critical', target: 'blockchain',
+                          message: "Blockchain integrity check failed (state: #{blockchain[:state] || 'unknown'})." }
+              end
             end
 
             # Safety gaps

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kairos-chain
 version: !ruby/object:Gem::Version
-  version: 3.63.0
+  version: 3.64.0
 platform: ruby
 authors:
 - Masaomi Hatakeyama