reeve 0.5.0 → 0.6.0

data/lib/reeve/railtie.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Reeve
+  # Registers `bin/rails reeve:verify_ledger`, and does nothing else.
+  #
+  # Loaded by lib/reeve.rb only when Rails::Railtie is already defined, so `require "reeve"`
+  # in a plain Ruby process still loads nothing beyond reeve's own files and its short stdlib
+  # allowlist (spec/load_safety_spec.rb).
+  class Railtie < ::Rails::Railtie
+    rake_tasks do
+      require "reeve/tasks"
+      Reeve::Tasks.define
+    end
+  end
+end

data/lib/reeve/tasks.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Reeve
+  # `bin/rails reeve:verify_ledger` (specs/002 FR-017, contracts/ledger-chain.md "Rake").
+  #
+  # A Ruby file rather than a .rake one on purpose: reeve.gemspec packages lib/**/*.rb, and a
+  # .rake file would pass every spec in the working tree and be missing from the gem users
+  # install. Registered by Reeve::Railtie; callable without Rake for anything else that
+  # wants the same answer — a deploy gate, a scheduled job, a console.
+  #
+  #   status = Reeve::Tasks.verify_ledger(env: { "LIMIT" => "0" })
+  module Tasks
+    EXIT = { intact: 0, broken: 1, unverifiable: 2, no_chain: 2 }.freeze
+    FORMATS = %w[text json].freeze
+
+    module_function
+
+    # Verifies the ledger, writes the report to `out`, and returns the exit status:
+    # 0 intact, 1 broken, 2 could not verify (unverifiable, or no chain).
+    #
+    # LIMIT caps the breaks listed in the text report (default 100; the totals are never
+    # capped). FORMAT=json writes the whole result, every break, and ignores LIMIT.
+    def verify_ledger(env: ENV, out: $stdout)
+      format = env.fetch("FORMAT", "text")
+      unless FORMATS.include?(format)
+        raise ArgumentError, "FORMAT must be one of #{FORMATS.join(', ')}, got #{format.inspect}"
+      end
+
+      limit = limit_from(env)
+      require "reeve/audit"
+      result = Reeve::Audit::Chain.verify
+      out.puts(format == "json" ? JSON.generate(result.as_json) : result.to_s(limit: limit))
+      EXIT.fetch(result.status)
+    end
+
+    def limit_from(env)
+      raw = env.fetch("LIMIT", Reeve::Audit::Chain::Verification::DEFAULT_LIMIT.to_s)
+      Integer(raw, 10).tap { |limit| raise ArgumentError if limit.negative? }
+    rescue ArgumentError, TypeError
+      raise ArgumentError, "LIMIT must be a whole number of breaks to list, got #{raw.inspect}"
+    end
+
+    # The Rake task, defined on the current Rake application. Depends on :environment, so
+    # the host's initializer — and with it the ledger key — is loaded first.
+    #
+    # The DSL is borrowed by a throwaway object, so Reeve::Tasks itself never gains `task`,
+    # `sh` and the rest of Rake's methods.
+    def define
+      Object.new.extend(Rake::DSL).instance_exec do
+        namespace :reeve do
+          desc "Verify the audit ledger's chain " \
+               "(exit 0 intact, 1 broken, 2 could not verify; LIMIT=, FORMAT=json)"
+          task verify_ledger: :environment do
+            exit Reeve::Tasks.verify_ledger
+          end
+        end
+      end
+    end
+  end
+end

data/lib/reeve/testing/checks/contract_version.rb

@@ -46,9 +46,10 @@ module Reeve
           invocation_id occurred_at agent_id agent_name principal_type principal_id
           tool_name arguments outcome rule detail record_type record_ids record_count
           truncated derived guard duration_ms metadata contract_version
+          chain_sequence chain_key_id chain_digest
         ].freeze
 
-        EXPECTED_VERSION = 2
+        EXPECTED_VERSION = 3
 
         def initialize(tool: nil, expected: EXPECTED_VERSION, ledger: nil)
           super(tool: tool, ledger: ledger)

data/lib/reeve/testing/checks/ledger_chain.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Testing
+    module Checks
+      # Whether the ledger's chain holds (specs/002 FR-018).
+      #
+      # It writes entries of its own first — the first compliance tool, once per fixture
+      # principal — because a suite with transactional fixtures starts every example with
+      # an empty ledger, and a check that only looked would find nothing and say nothing.
+      # Then it verifies the whole ledger the run can see, not only its own rows: a break an
+      # earlier run left behind is reported, not hidden.
+      #
+      # * **intact** — passed; the message is the verification's own summary line, so it
+      #   states the range covered and what was not.
+      # * **broken, unverifiable, or no chain after writing** — failed. The run signed its own
+      #   entries, so a key it lacks or a recorder that did not chain is a configuration
+      #   error, not an absence.
+      # * **no key configured** — failed, naming the setting.
+      # * **nothing to write or read** (no compliance tools, ledger not loaded) — skipped,
+      #   saying the chain was not verified. Never passed.
+      #
+      #   Reeve::Checks::LedgerChain.new.call
+      class LedgerChain < Base
+        NOT_VERIFIED = "the ledger chain was not verified"
+
+        def initialize(tools: nil, principals: nil, arguments: {}, invoke: nil, ledger: nil)
+          @tools = tools
+          @principals = principals
+          super(tool: nil, arguments: arguments, invoke: invoke, ledger: ledger)
+        end
+
+        def call
+          return skipped("there is no compliance tool to write an entry with") if subject.nil?
+          return skipped(unreadable_reason) unless readable?
+          return no_key if Reeve.config.ledger_key.nil?
+
+          unwritten = write_entries
+          return unwritten_entry(unwritten) if unwritten
+
+          judge(ledger.verify_chain)
+        end
+
+        private
+
+        def subject
+          @subject ||= Array(@tools || Testing.compliance_tools).first
+        end
+
+        def principals
+          configured = Testing.compliance_principals? ? Testing.compliance_principals : nil
+          list = Array(@principals || configured)
+          list.empty? ? [nil] : list
+        end
+
+        # Each principal on its own, so one refusal does not stop the next. A denial, or the
+        # tool's own error, still leaves a ledger entry — the envelope records before it
+        # re-raises — which is all this needs. A failed ledger write leaves none, and is
+        # returned as the reason the chain could not be checked.
+        #
+        # Returns nil when entries were written, or the reason none were — including the case
+        # where every invocation failed before reaching reeve, which a chain left by an
+        # earlier run must not be allowed to pass for.
+        def write_entries
+          before = ledger.count
+          principals.each do |principal|
+            invoke.call(tool: subject, arguments: arguments, principal: principal)
+          rescue Reeve::AuditWriteError => e
+            return "#{e.class}: #{e.message}"
+          rescue StandardError
+            next
+          end
+          ledger.count == before ? "its invocations wrote no entry" : nil
+        end
+
+        def readable?
+          ledger.available? && ledger.respond_to?(:verify_chain)
+        end
+
+        def unwritten_entry(reason)
+          failed("#{NOT_VERIFIED}: it wrote no entry of its own — #{reason}",
+                 coverage: :unwritten)
+        end
+
+        def unreadable_reason
+          ledger.unavailable_reason || "this ledger cannot verify a chain"
+        end
+
+        def judge(verification)
+          return skipped("the audit ledger is not loaded") if verification.nil?
+
+          summary = verification.to_s
+          return passed(summary.lines.first.chomp, coverage: :intact) if verification.intact?
+
+          failed(summary, coverage: verification.status)
+        end
+
+        def no_key
+          failed("expected the ledger to be chained, but no ledger key is configured: set " \
+                 "config.ledger_key (the generated initializer derives one from secret_key_base)",
+                 coverage: :no_key)
+        end
+
+        # Every skip says, first, that the chain was not verified — then why.
+        def skipped(reason)
+          Result.skipped(check: check_name, message: "#{NOT_VERIFIED}: #{reason}",
+                         details: { coverage: :unverified })
+        end
+
+        def base_details
+          {}
+        end
+      end
+    end
+  end
+end

data/lib/reeve/testing/checks.rb

@@ -9,6 +9,7 @@ require_relative "checks/redaction_holds"
 require_relative "checks/principal_required"
 require_relative "checks/contract_version"
 require_relative "checks/endpoint_coverage"
+require_relative "checks/ledger_chain"
 
 module Reeve
   module Testing
@@ -19,7 +20,7 @@ module Reeve
     # the same violation reads identically from either — and from neither:
     #
     #   report = Reeve::Checks.run_all(principals: [alice, bob])
-    #   abort report.to_s unless report.passed?
+    #   abort report.to_s if report.failed? || report.nothing_checked?
     #
     # Nothing here loads a test framework (FR-026).
     module Checks
@@ -31,12 +32,13 @@ module Reeve
         RedactionHolds,
         PrincipalRequired,
         ContractVersion,
-        EndpointCoverage
+        EndpointCoverage,
+        LedgerChain
       ].freeze
 
       # The checks that are asked once — about the ledger, or about the endpoint as a
       # whole — rather than once per tool.
-      GLOBAL = [ContractVersion, EndpointCoverage].freeze
+      GLOBAL = [ContractVersion, EndpointCoverage, LedgerChain].freeze
 
       # The compliance suite's engine (FR-018): every check, against every registered
       # guarded tool, in one Report.
@@ -58,10 +60,12 @@ module Reeve
       def self.run(check, principals:, tools: nil, arguments: {}, invoke: nil, ledger: nil)
         if GLOBAL.include?(check)
           return Report.new([build(check, tool: nil, principals: principals, tools: tools,
-                                          ledger: ledger).call])
+                                          invoke: invoke, ledger: ledger).call])
         end
 
         subjects = tools || Testing.compliance_tools
+        return Report.new([nothing_to_check(check, tools)]) if subjects.empty?
+
         Report.new(
           subjects.map do |tool|
             build(check, tool: tool, principals: principals, arguments: arguments,
@@ -70,6 +74,25 @@ module Reeve
         )
       end
 
+      # A per-tool check over no tools establishes nothing, and an empty Report reads as
+      # passed — the green that means "did not look". So an empty population is one skip,
+      # saying which of the three ways the run came to have nothing in it.
+      def self.nothing_to_check(check, tools)
+        reason =
+          if !tools.nil? then "the run was given tools: []"
+          elsif Testing.compliance_tools_narrowed? then "compliance_tools is []"
+          else "the registry is empty and no endpoint inventory routes a tool"
+          end
+
+        Result.skipped(
+          check: check.check_name,
+          message: "no compliance tools to check, so #{check.check_name} established " \
+                   "nothing — #{reason}",
+          details: { coverage: :none }
+        )
+      end
+      private_class_method :nothing_to_check
+
       # Every per-tool check for one tool, instantiated but not run.
       def self.for_tool(tool, principals:, arguments: {}, invoke: nil, ledger: nil)
         (ALL - GLOBAL).map do |check|
@@ -91,6 +114,8 @@ module Reeve
         when "GuardDeclared"      then GuardDeclared.new(tool: tool, ledger: ledger)
         when "ContractVersion"    then ContractVersion.new(ledger: ledger)
         when "EndpointCoverage"   then EndpointCoverage.new(tools: tools, ledger: ledger)
+        when "LedgerChain"        then LedgerChain.new(tools: tools, principals: principals,
+                                                       invoke: invoke, ledger: ledger)
         when "PrincipalRequired"  then PrincipalRequired.new(**common)
         when "CrossPrincipalLeak" then CrossPrincipalLeak.new(principals: Array(principals),
                                                               **common)

data/lib/reeve/testing/compliance_assertions.rb

@@ -15,8 +15,9 @@ module Reeve
     #
     # One method per check, matching the RSpec shared example group one for one, so a red
     # build names the guarantee that broke rather than reporting "compliance" as one
-    # undifferentiated failure. A check that could establish nothing either way is
-    # skipped with its reason, never passed.
+    # undifferentiated failure. A check that could establish nothing either way — no
+    # inventory declared, or no tools to run a per-tool check over — is skipped with its
+    # reason, never passed.
     module ComplianceAssertions
       include Assertions
 

data/lib/reeve/testing/compliance_suite.rb

@@ -12,8 +12,8 @@
 #
 # One example per check rather than one for the lot, so a red build names the guarantee
 # that broke — "CrossPrincipalLeak" is an incident, "compliance" is a shrug. A check that
-# could establish nothing either way (EndpointCoverage with no inventory) is skipped, with
-# its reason, rather than passed.
+# could establish nothing either way (EndpointCoverage with no inventory, or a per-tool
+# check with no tools to run over) is skipped, with its reason, rather than passed.
 RSpec.shared_examples "a reeve-compliant server" do
   Reeve::Checks::ALL.each do |check|
     it "satisfies #{check.check_name} for every registered guarded tool" do

data/lib/reeve/testing/ledger.rb

@@ -10,7 +10,8 @@ module Reeve
     # the ledger is absent.
     #
     # A host with its own non-ActiveRecord recorder can pass any object with these six
-    # methods as `ledger:` to any ledger-reading check.
+    # methods as `ledger:` to any ledger-reading check; LedgerChain also asks for
+    # #verify_chain, and is skipped by a ledger that has none.
     class Ledger
       def self.default
         new
@@ -67,6 +68,15 @@ module Reeve
         entry_class.column_names.map(&:to_s)
       end
 
+      # The chain's verification of the whole ledger (specs/002), or nil when the ledger is
+      # not loaded. The kit's only way to the chain: it names Reeve::Audit::Chain here, at
+      # call time, so `require "reeve/testing"` still loads with no ActiveRecord at all.
+      def verify_chain
+        return nil unless available? && Reeve::Audit.const_defined?(:Chain, false)
+
+        Reeve::Audit::Chain.verify(entry_class: entry_class)
+      end
+
       private
 
       def entry_class

data/lib/reeve/testing/report.rb

@@ -31,6 +31,14 @@ module Reeve
         !results.empty? && results.all?(&:skipped?)
       end
 
+      # A check had nothing to examine — a per-tool check run over no tools at all. passed?
+      # is still true then, since nothing failed; a test framework shows the skip, but a
+      # gate with no framework (a CI script, a deploy step) has only this to stop on. A skip
+      # for a missing inventory is not this: there the tools existed and were checked.
+      def nothing_checked?
+        results.any? { |result| result.skipped? && result.details[:coverage] == :none }
+      end
+
       def failures
         results.select(&:failed?)
       end

data/lib/reeve/testing.rb

@@ -18,7 +18,7 @@ module Reeve
   #
   #   require "reeve/testing"
   #   report = Reeve::Checks.run_all(principals: [alice, bob])
-  #   abort report.to_s unless report.passed?
+  #   abort report.to_s if report.failed? || report.nothing_checked?
   module Testing
     class << self
       # The two fixture principals the compliance suite runs every tool against. Set once,

data/lib/reeve/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Reeve
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

data/lib/reeve.rb

@@ -2,6 +2,7 @@
 
 require_relative "reeve/version"
 require_relative "reeve/errors"
+require_relative "reeve/ledger_key"
 require_relative "reeve/decision"
 require_relative "reeve/configuration"
 require_relative "reeve/context"
@@ -9,6 +10,7 @@ require_relative "reeve/scope_result"
 require_relative "reeve/invocation"
 require_relative "reeve/authorization"
 require_relative "reeve/inventory"
+require_relative "reeve/railtie" if defined?(Rails::Railtie)
 
 # Reeve — per-record authorization and an append-only audit ledger for the MCP tools
 # a Rails application exposes to AI agents.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: reeve
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Victor Velazquez
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-01 00:00:00.000000000 Z
+date: 2026-10-10 00:00:00.000000000 Z
 dependencies: []
 description: |
   Reeve makes it safe for a Rails application to expose MCP (Model Context Protocol)
@@ -31,9 +31,20 @@ files:
 - lib/generators/reeve/install/templates/create_audit_entries.rb.tt
 - lib/generators/reeve/install/templates/initializer.rb.tt
 - lib/generators/reeve/upgrade/templates/add_contract_version_to_reeve_audit_entries.rb.tt
+- lib/generators/reeve/upgrade/templates/add_ledger_chain_to_reeve_audit_entries.rb.tt
 - lib/generators/reeve/upgrade/upgrade_generator.rb
 - lib/reeve.rb
 - lib/reeve/audit.rb
+- lib/reeve/audit/chain.rb
+- lib/reeve/audit/chain/canonical.rb
+- lib/reeve/audit/chain/head.rb
+- lib/reeve/audit/chain/keyring.rb
+- lib/reeve/audit/chain/normalizer.rb
+- lib/reeve/audit/chain/report.rb
+- lib/reeve/audit/chain/verification.rb
+- lib/reeve/audit/chain/verifier.rb
+- lib/reeve/audit/chain/walk.rb
+- lib/reeve/audit/chain_record.rb
 - lib/reeve/audit/entry.rb
 - lib/reeve/audit/isolated_recorder.rb
 - lib/reeve/audit/query.rb
@@ -59,9 +70,12 @@ files:
 - lib/reeve/inventory.rb
 - lib/reeve/inventory/report.rb
 - lib/reeve/invocation.rb
+- lib/reeve/ledger_key.rb
 - lib/reeve/minitest.rb
+- lib/reeve/railtie.rb
 - lib/reeve/rspec.rb
 - lib/reeve/scope_result.rb
+- lib/reeve/tasks.rb
 - lib/reeve/testing.rb
 - lib/reeve/testing/assertions.rb
 - lib/reeve/testing/checks.rb
@@ -71,6 +85,7 @@ files:
 - lib/reeve/testing/checks/cross_principal_leak.rb
 - lib/reeve/testing/checks/endpoint_coverage.rb
 - lib/reeve/testing/checks/guard_declared.rb
+- lib/reeve/testing/checks/ledger_chain.rb
 - lib/reeve/testing/checks/principal_required.rb
 - lib/reeve/testing/checks/redaction_holds.rb
 - lib/reeve/testing/checks/rule_present.rb