reeve 0.5.0 → 0.7.0

data/lib/reeve/audit/recorder.rb

@@ -10,9 +10,10 @@ module Reeve
     # ActiveJob. An asynchronous ledger cannot be relied on and would make FR-012
     # unenforceable.
     #
-    # The insert runs in `requires_new: true`, which is what makes the trace survive a
-    # tool body that opens a transaction and rolls it back (R5) — the case this was built
-    # for, and the one it does solve.
+    # Every row goes through Chain#append! (specs/002), which links it to the row before it
+    # and runs the insert in `requires_new: true` — what makes the trace survive a tool body
+    # that opens a transaction and rolls it back (R5), the case this was built for and the
+    # one it does solve.
     #
     # What it does **not** do, corrected after review: `requires_new` is a SAVEPOINT, not
     # an independent transaction. If the host has already opened a transaction *around*
@@ -54,20 +55,28 @@ module Reeve
 
       # Returns the entry. Raises if the row could not be written, so the envelope can
       # fail the invocation.
+      #
+      # A replayed invocation is the same invocation: one row per invocation_id means a
+      # retry returns the existing row and never writes a second (contracts/audit-entry.md).
+      # Chain#append! owns that, because it must also consume no sequence number.
+      #
+      # With no ledger key (specs/002 FR-010): under :fail, Chain raises LedgerKeyError and
+      # the envelope fails the call like any other ledger failure. Under :warn the row is
+      # still written, at contract 3 and unchained, and the log says so every time —
+      # :warn keeps calls running, it does not drop traces, and verification reports the
+      # row as unchained rather than letting it pass unseen.
       def record(attributes)
         row = row_for(attributes)
         warn_about_enclosing_transaction(row[:invocation_id])
 
-        entry_class.transaction(requires_new: true) do
-          entry_class.create!(row)
-        end
-      rescue ActiveRecord::RecordNotUnique, ActiveRecord::RecordInvalid => e
-        # A replayed invocation is the same invocation. One row per invocation_id means
-        # a retry is a no-op insert, never a second row (contracts/audit-entry.md).
-        existing = entry_class.find_by(invocation_id: row[:invocation_id])
-        raise e if existing.nil?
+        keyring = Chain::Keyring.from(config)
+        chain = Chain.new(entry_class: entry_class, keyring: keyring)
+        return chain.append!(row) if keyring.signing? || config.audit_failure_mode == :fail
 
-        existing
+        warn("reeve: invocation #{row[:invocation_id]} was recorded unchained: no ledger key is " \
+             "configured and audit_failure_mode is :warn. Verification will report the row as " \
+             "unchained. Set config.ledger_key to chain the ledger.")
+        chain.append_unchained!(row)
       end
 
       private
@@ -78,6 +87,11 @@ module Reeve
         @config || Reeve.config
       end
 
+      def warn(message)
+        logger = config.logger
+        logger ? logger.warn(message) : Kernel.warn(message)
+      end
+
       def row_for(attributes)
         ids, count, truncated = identifiers(attributes)
 
@@ -163,13 +177,12 @@ module Reeve
       def warn_about_enclosing_transaction(invocation_id)
         return unless enclosing_transaction?
 
-        message = "reeve: invocation #{invocation_id} was recorded inside a transaction " \
-                  "the host opened around it, so the ledger row will be rolled back with " \
-                  "it. Set Reeve.config.audit_recorder = Reeve::Audit::IsolatedRecorder " \
-                  "to write on a connection the transaction cannot reach (needs a " \
-                  "database with concurrent writers; not SQLite)."
-        logger = config.logger
-        logger ? logger.warn(message) : Kernel.warn(message)
+        warn("reeve: invocation #{invocation_id} was recorded inside a transaction " \
+             "the host opened around it, so the ledger row will be rolled back with " \
+             "it, and the ledger chain stays locked until it ends, so every other " \
+             "guarded call waits behind it. Set Reeve.config.audit_recorder = " \
+             "Reeve::Audit::IsolatedRecorder to write on a connection the transaction " \
+             "cannot reach (needs a database with concurrent writers; not SQLite).")
       end
 
       def enclosing_transaction?

data/lib/reeve/audit.rb

@@ -44,9 +44,14 @@ module Reeve
   #   documents the `GRANT INSERT, SELECT` that enforces the rest where it can actually be
   #   enforced, and the gem makes no stronger claim than that.
   # * No retention, rotation or archival yet — the table is host-owned and the host's
-  #   existing policies apply.
-  # * No cryptographic chaining or tamper-evidence yet. If that lands it arrives as a
-  #   nullable column, which the audit-entry contract's versioning already permits.
+  #   existing policies apply. Deleting rows breaks the chain, by design.
+  # * Tamper-evidence, not tamper-proofing. Every row is chained to the one before it
+  #   (Reeve::Audit::Chain, contract 3), so a change made outside the library is reported
+  #   by verification — after the fact; it prevents nothing. It does not detect a change
+  #   made by someone holding the ledger key, the newest rows deleted by a role that can
+  #   also rewind the chain record's head, the whole ledger deleted, or anything about
+  #   rows written before contract 3. specs/001-guardrails-core/contracts/audit-entry.md,
+  #   guarantee 9, is the authoritative statement.
   #
   # ("yet" rather than "in v1": the gem version and the audit-entry contract version are
   # different numbers that move independently, and writing v1 for one of them read as the
@@ -54,14 +59,25 @@ module Reeve
   module Audit
     # The version of the audit-entry shape, as documented in
     # specs/001-guardrails-core/contracts/audit-entry.md (FR-015). Adding a nullable
-    # column is a MINOR change and leaves this alone; removing or renaming a column, or
-    # changing what a value means, is MAJOR and bumps it.
+    # column is a MINOR change and leaves this alone — unless what its absence means, or
+    # what an existing value covers, differs between rows written before and after it;
+    # removing or renaming a column, or changing what a value means, is MAJOR and bumps it.
+    #
+    # 4 — entries name their key epoch (specs/003). One nullable column, `chain_epoch`, but
+    # it is inside the digest, so `chain_digest` on a contract-4 row covers something a
+    # contract-3 digest does not, and a NULL epoch means "before key epochs" on a contract-3
+    # row where a chained contract-4 row always has one.
+    #
+    # 3 — entries are chained (specs/002). The three chain columns are nullable, so the
+    # shape change is additive, but what a NULL digest means changed: on a contract-3 row
+    # it is a row written unchained, which verification reports, where on an older row it
+    # only means the row predates chaining.
     #
     # 2 — `metadata` carries the transport detail the caller passed. Through version 1 it
     # was written NULL on every row regardless of what was passed, so anything mapping
     # version 1 rows could reasonably have read the column as "always empty". The shape
     # did not change; what a value means did.
-    CONTRACT_VERSION = 2
+    CONTRACT_VERSION = 4
 
     TABLE_NAME = "reeve_audit_entries"
 
@@ -94,5 +110,20 @@ require_relative "audit/entry"
 require_relative "audit/recorder"
 require_relative "audit/isolated_recorder"
 require_relative "audit/query"
+require_relative "audit/chain/keyring"
+require_relative "audit/chain/normalizer"
+require_relative "audit/chain/canonical"
+require_relative "audit/chain_record"
+require_relative "audit/chain_epoch"
+require_relative "audit/chain/verification"
+require_relative "audit/chain/report"
+require_relative "audit/chain/head"
+require_relative "audit/chain/epochs"
+require_relative "audit/chain/rotation"
+require_relative "audit/chain/epoch_rules"
+require_relative "audit/chain/schema"
+require_relative "audit/chain/walk"
+require_relative "audit/chain/verifier"
+require_relative "audit/chain"
 
 Reeve::Audit.install!

data/lib/reeve/configuration.rb

@@ -24,9 +24,13 @@ module Reeve
     SETTINGS = %i[
       principal_resolver unguarded_tools audit_failure_mode redact_arguments
       max_recorded_ids policy_adapter default_action audit_recorder logger
-      compliance_principals compliance_tools inventory
+      compliance_principals compliance_tools inventory ledger_key retired_ledger_keys
     ].freeze
 
+    # Shown by #to_h and #inspect as fingerprints. A configuration object gets printed —
+    # in a console, a bug report, a failing spec — and a secret must not travel with it.
+    SECRET_SETTINGS = %i[ledger_key retired_ledger_keys].freeze
+
     attr_reader(*SETTINGS)
 
     def initialize
@@ -42,6 +46,47 @@ module Reeve
       @compliance_principals = nil
       @compliance_tools = nil
       @inventory = nil
+      @ledger_key = nil
+      @retired_ledger_keys = []
+    end
+
+    # The key that signs the audit ledger's chain (specs/002). Held in configuration, never
+    # in the database: that separation is the whole of the tamper-evidence guarantee.
+    # Validated here so a short key fails on the initializer line that set it.
+    #
+    #   config.ledger_key = Rails.application.key_generator.generate_key("reeve audit ledger", 32)
+    def ledger_key=(secret)
+      unless secret.nil?
+        LedgerKey.validate!(secret, :ledger_key)
+        if @retired_ledger_keys.include?(secret)
+          raise ArgumentError, "ledger_key is also listed in retired_ledger_keys; a key " \
+                               "either signs or is retired, not both"
+        end
+      end
+
+      @ledger_key = secret
+    end
+
+    # Keys that signed older entries, kept so those entries still verify. Never used to
+    # sign. Removing one leaves the entries it signed unverifiable — reported as such,
+    # never as tampered.
+    def retired_ledger_keys=(secrets)
+      unless secrets.is_a?(Array)
+        raise ArgumentError, "retired_ledger_keys must be an Array of keys, got a #{secrets.class}"
+      end
+
+      secrets.each { |secret| LedgerKey.validate!(secret, :retired_ledger_keys) }
+      if !@ledger_key.nil? && secrets.include?(@ledger_key)
+        raise ArgumentError, "retired_ledger_keys includes the current ledger_key; a key " \
+                             "either signs or is retired, not both"
+      end
+
+      @retired_ledger_keys = secrets.dup.freeze
+    end
+
+    # The fingerprint stored on every row this configuration signs, or nil with no key.
+    def ledger_key_id
+      @ledger_key && LedgerKey.fingerprint(@ledger_key)
     end
 
     # The host's whole tool inventory (Reeve::Inventory). Optional. Setting it is what lets
@@ -163,11 +208,30 @@ module Reeve
     end
 
     def to_h
-      SETTINGS.to_h { |setting| [setting, public_send(setting)] }
+      SETTINGS.to_h { |setting| [setting, shown(setting)] }
+    end
+
+    def inspect
+      "#<#{self.class.name} #{to_h.map do |setting, value|
+        "#{setting}=#{value.inspect}"
+      end.join(', ')}>"
     end
 
     private
 
+    def shown(setting)
+      value = public_send(setting)
+      return value unless SECRET_SETTINGS.include?(setting)
+
+      if value.is_a?(Array)
+        value.map do |secret|
+          LedgerKey.fingerprint(secret)
+        end
+      else
+        value && LedgerKey.fingerprint(value)
+      end
+    end
+
     def require_one_of!(setting, value, allowed)
       symbol = value.is_a?(Symbol) ? value : nil
       return symbol if allowed.include?(symbol)

data/lib/reeve/errors.rb

@@ -70,6 +70,21 @@ module Reeve
     end
   end
 
+  # Raised when a chained ledger write or a verification has no key to use (specs/002
+  # FR-010). On the invocation path the envelope wraps it in AuditWriteError, exactly as it
+  # wraps any other ledger failure, so a host rescues one class either way.
+  class LedgerKeyError < Error
+    def initialize(message = nil)
+      super(message || <<~MESSAGE.chomp)
+        no ledger key is configured, so the audit ledger cannot be chained. Set one in
+        config/initializers/reeve.rb — derived from secret_key_base, it works in every
+        environment with no new secret:
+
+          config.ledger_key = Rails.application.key_generator.generate_key("reeve audit ledger", 32)
+      MESSAGE
+    end
+  end
+
   # Raised when the ledger write fails and audit_failure_mode is :fail (FR-012).
   #
   # It carries a rule like any other denial, because the failure is not recorded anywhere

data/lib/reeve/ledger_key.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Reeve
+  # What makes a ledger key acceptable, and the name a key goes by (specs/002, research R7).
+  #
+  # Core rather than under reeve/audit, because configuration validates keys at assignment
+  # and configuration loads without ActiveRecord. Validation needs nothing beyond Ruby;
+  # `openssl` is required only when a fingerprint is computed, so `require "reeve"` stays on
+  # its short stdlib allowlist (spec/load_safety_spec.rb) and a host that never configures
+  # a key never loads it.
+  module LedgerKey
+    # HMAC-SHA256 takes a key of any length, but one shorter than the hash's own output
+    # weakens it. Bytes, not characters: that is what the HMAC sees.
+    MINIMUM_BYTES = 32
+
+    FINGERPRINT_LABEL = "reeve-ledger-key-id"
+    FINGERPRINT_LENGTH = 16
+
+    module_function
+
+    # The identifier stored on each chained row in place of the key. Derived from the key
+    # rather than chosen by the host, so an identifier can never be pinned to the wrong
+    # secret, and a renamed key cannot orphan the history it signed. An HMAC output, so it
+    # says nothing about the key it names.
+    def fingerprint(secret)
+      require "openssl"
+      OpenSSL::HMAC.hexdigest("SHA256", secret, FINGERPRINT_LABEL)[0, FINGERPRINT_LENGTH]
+    end
+
+    # Raises ArgumentError naming the setting and the rule. Never the value: a key that is
+    # too short is still a secret, and error messages end up in logs.
+    def validate!(secret, setting)
+      unless secret.is_a?(String)
+        raise ArgumentError, "#{setting} must be a String of at least #{MINIMUM_BYTES} " \
+                             "bytes, got a #{secret.class}"
+      end
+      if secret.strip.empty?
+        raise ArgumentError, "#{setting} must not be blank; it must be at least " \
+                             "#{MINIMUM_BYTES} bytes"
+      end
+      return secret if secret.bytesize >= MINIMUM_BYTES
+
+      raise ArgumentError, "#{setting} must be at least #{MINIMUM_BYTES} bytes, got " \
+                           "#{secret.bytesize}"
+    end
+  end
+end

data/lib/reeve/railtie.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Reeve
+  # Registers `bin/rails reeve:verify_ledger` and `bin/rails reeve:rotate_ledger_key`, 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,91 @@
+# 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
+    ROTATE_EXIT = { rotated: 0, current: 0, refused: 1 }.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
+
+    # Makes the configured ledger key the latest epoch's key (specs/003, contracts/
+    # key-rotation.md), writes what happened to `out`, and returns the exit status: 0 rotated
+    # or already current, 1 refused.
+    #
+    # ACCEPT_UNVERIFIABLE=1 opens the epoch even though the outgoing epoch's key is not
+    # configured here — for a key that is lost, and only then.
+    def rotate_ledger_key(env: ENV, out: $stdout)
+      accept = accept_unverifiable_from(env)
+      require "reeve/audit"
+      rotation = Reeve::Audit::Chain.rotate_key!(accept_unverifiable: accept)
+      out.puts(rotation.to_s)
+      ROTATE_EXIT.fetch(rotation.status)
+    end
+
+    def accept_unverifiable_from(env)
+      raw = env.fetch("ACCEPT_UNVERIFIABLE", "")
+      return false if raw.empty?
+      return true if raw == "1"
+
+      raise ArgumentError, "ACCEPT_UNVERIFIABLE must be 1 or unset, got #{raw.inspect}"
+    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
+
+          desc "Make config.ledger_key the ledger's current key epoch (exit 0 rotated or " \
+               "current, 1 refused; ACCEPT_UNVERIFIABLE=1 if the old key is lost)"
+          task rotate_ledger_key: :environment do
+            exit Reeve::Tasks.rotate_ledger_key
+          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 chain_epoch
         ].freeze
 
-        EXPECTED_VERSION = 2
+        EXPECTED_VERSION = 4
 
         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