reeve 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 329fc869bdb15c7e60eb1923221aeccb1725821535c25186dafe77bda001cc44
-  data.tar.gz: 0f0781268bc7e90b1fad27a74bef611aa6aa65df3da37fb1351eb3f28524da15
+  metadata.gz: 67bc82ca855e0385d021e54477cbcfcef697a1134d3c93e4fc073fea2ff3b748
+  data.tar.gz: 0c11093e604b6a056a23bec7ebd419620d4dd1780f93ff7e30fc8a08bdbd92d3
 SHA512:
-  metadata.gz: b5d6286339f5f034e76f74052e3d19f9560c55b45e9432e6583b50931ddf4425a1aa5bc5c0ea1200646a9085f972521a3d1e2c38d8cf654e8aa8004fa2be0e3f
-  data.tar.gz: 32c28f2c34294f7d2454b772a1fd7bd52af690c3bc6d46793e2ec23021c6c3bd5d0d4bc6ee5f04b990a36a5f8ada40e03677bd9efa5c2a099b08c6bcf4cac147
+  metadata.gz: 0524a6cd7376dc9cc8b7f2611d4a0a6a8b1fa81b6b5ff59ab662d3e5f5f313b4f47e7ad5b2d52d272da8bab1f1c19042ae937300beb382f57804f2fc72b77d3e
+  data.tar.gz: 4ead6c668edcde8b543c1e4ead9817e08015ecbf42adfbc34d44c5fa31426206284efb3ffdd88dad4cd983033be7708e256ac9cc2e5eb4758a6fc92f2ac14a19

data/CHANGELOG.md

@@ -4,6 +4,76 @@ All notable changes are recorded here. This project follows [Semantic
 Versioning](https://semver.org), with one rule specific to what it does — see
 [Versioning policy](#versioning-policy).
 
+## [0.5.0] - 2026-10-01
+
+Reeve protects the tools routed through it, and only those. A server that registers its
+tools as names and handler blocks can send some through `Reeve.invoke` and run the rest
+directly — and the direct ones are not unguarded, they are invisible: no denial, no scope,
+no ledger row, and nothing that says so. The compliance suite could not see them either,
+because it walks tools reeve was told about. A green run certified the subset reeve
+happened to know, and read exactly like a green run over the whole endpoint.
+
+**The audit-entry contract is unchanged at `2`, so no migration is required.** One new
+`rule` value, `unbound_tool`, can appear — only for a host that dispatches through an
+inventory.
+
+Behaviour changes worth reading before upgrading:
+
+- Both compliance suites have one more check, `EndpointCoverage`. Until `config.inventory`
+  is set it is **skipped** — pending in RSpec, a skip in Minitest — with a message saying
+  the endpoint was not verified. Nothing that passed before fails.
+- A `Report` now counts and prints skipped results (`8 checks, 7 passed, 0 failed, 1
+  skipped`, followed by `SKIP EndpointCoverage` and its reason). `passed?` is unchanged: a
+  skip is not a failure.
+- A multi-line check message is now indented as one block under its `FAIL` heading.
+
+**On Rails 7.0, keep `json` below 3.0.** json 3.0 dropped the `quirks_mode:` keyword that
+ActiveSupport 7.0 still passes to `JSON.generate`, so the ledger cannot serialize a row.
+Under the default `audit_failure_mode = :fail`, reeve fails closed: every invocation raises
+`Reeve::AuditWriteError` rather than running unrecorded — nothing goes unaudited, and
+nothing runs. Under `:warn`, every call runs and none is recorded. The defect is ActiveSupport's, not
+reeve's, and no reeve version works around it; pin `gem "json", "< 3"` until the
+application is on a Rails that supports json 3. Reeve's own CI pins it on the Ruby 3.0
+job for the same reason.
+
+### Added
+
+- **`Reeve::Inventory`** — the host's registered tool names, which of them route through
+  reeve and to which class, and which are exempt and why. Every part takes a value or a
+  callable, so a Rails initializer can declare it without autoloading application
+  constants. No MCP library involved: a list of names is the whole protocol.
+
+  - `#report` classifies every registered name as protected and guarded, routed but
+    unguarded, bypassing reeve, or exempted — plus anything the inventory names that the
+    server does not register, which is usually a rename that left the real name unbound.
+    The output names tools, classes and exemption reasons, never an argument, a principal
+    or a record, so it is safe in a CI log.
+  - `#verify!` raises `Reeve::IncompleteInventoryError`, carrying the report, unless every
+    registered name is guarded or exempt. For boot, a deploy step, or CI.
+  - `#dispatch(name, ...) { handler }` is the dispatch boundary. A routed name runs through
+    `Reeve.invoke`, with the handler block as the body; an exempt name runs as written; any
+    other name is treated as a tool with no guard — refused with the new `unbound_tool`
+    rule under `unguarded_tools = :deny`, or run unscoped with `guard: "none"` under
+    `:allow_with_warning` — and recorded either way. A host that dispatches through it
+    cannot have a tool that bypasses reeve.
+  - An exemption needs a non-empty reason, and is listed in every report, complete or not.
+
+- **`config.inventory`**, and **`Checks::EndpointCoverage`**, which compares a compliance
+  run against it. Passes only when the inventory is complete and the run covered all of
+  it; fails when the run claimed the whole endpoint and a registered tool bypasses reeve
+  or reaches it unguarded; skipped when no inventory is declared, or when
+  `compliance_tools` or `tools:` narrowed the run, naming what was left out. The
+  incremental path stays open, and a subset can no longer pass for the endpoint.
+
+- **Skipped results.** `Testing::Result.skipped`, `Result#skipped?`, `Report#skips` and
+  `Report#skipped?`. Only `EndpointCoverage` produces one.
+
+### Changed
+
+- The compliance suites' default population includes every class the inventory routes to.
+  A registry of blocks has no reason to `include Reeve::Guard` anywhere, so a routed class
+  with no guard would otherwise never reach `GuardDeclared`.
+
 ## [0.4.0] - 2026-09-03
 
 Everything here came out of a second application integrating the gem — one that had put a
@@ -342,4 +412,4 @@ is for:
 - Adding a nullable ledger column is minor and leaves the audit-entry contract version
   alone. Removing or renaming a column, or changing what a value means, is major and bumps
   it.
-- The audit-entry contract version is `1`.
+- The audit-entry contract version is `2`.

data/README.md

@@ -7,7 +7,7 @@ A Ruby gem that makes it safe for a Rails application to expose MCP tools to AI
 declarative per-record authorization, an append-only audit ledger, and a testing kit that
 proves both hold.
 
-> **Status: 0.4.0.** Read the known limitations in
+> **Status: 0.5.0.** Read the known limitations in
 > [CHANGELOG.md](CHANGELOG.md) before adopting it — particularly the one about a
 > transaction wrapped around an invocation, if your application wraps requests in one.
 
@@ -242,12 +242,10 @@ config.compliance_tools = -> { [InvoiceSearchTool, InvoiceShowTool] }
 ```
 
 Reeve can only see tools that reached it. If your MCP server dispatches tools Reeve has
-never been told about — a custom controller with its own registry — hand it the real
-inventory, or it will certify the subset it happens to know:
-
-```ruby
-Reeve::Checks.run_all(principals: [alice, bob], tools: McpToolRegistry.tool_classes)
-```
+never been told about — a custom controller with its own registry — declare the server's
+real inventory ([below](#every-tool-the-endpoint-dispatches)), or the run certifies the
+subset Reeve happens to know. Until you do, the suite says so: `EndpointCoverage` is
+reported as skipped, never as passed.
 
 As a Rails rake task:
 
@@ -380,6 +378,91 @@ Reeve::Checks.run_all(
 That is the whole integration: one call site, your auth untouched, and the same three
 guarantees the fast-mcp adapter gets.
 
+## Every tool the endpoint dispatches
+
+Reeve protects the tools routed through it, and only those. A server that registers tools
+as names and handler blocks can send some through `Reeve.invoke` and run the rest directly
+— and the direct ones are not unguarded, they are invisible: no denial, no scope, no ledger
+row, and nothing that says so. Deny-by-default cannot deny a call it never sees.
+
+`Reeve::Inventory` makes the server's own list of names the thing that gets checked:
+
+```ruby
+# config/initializers/reeve.rb
+McpInventory = Reeve::Inventory.new(
+  registered: -> { McpServer.tool_names },
+  routed: -> { { "search_invoices" => InvoiceSearchTool, "get_invoice" => InvoiceShowTool } },
+  exemptions: { "healthcheck" => { reason: "returns no application data" } }
+)
+
+Reeve.configure { |config| config.inventory = McpInventory }
+```
+
+Each part takes a value or a callable. Callables are read when asked, so the initializer
+neither autoloads application constants nor runs before the server has registered its
+tools.
+
+```text
+reeve inventory: 4 registered
+  2 protected and guarded
+  0 routed through reeve but unguarded
+  1 bypasses reeve
+  1 exempted
+coverage: incomplete
+
+BYPASS export_invoices
+  registered with the server but neither routed through reeve nor exempted — route it to
+  a guarded tool, or exempt it with a reason
+
+EXEMPT healthcheck
+  returns no application data
+```
+
+The report names tools, classes and exemption reasons — never an argument, a principal or
+a record — so it is safe to print in CI. An exemption without a reason is refused, and one
+with a reason is listed every time, complete or not.
+
+**Fail boot or CI on a gap:**
+
+```ruby
+McpInventory.verify!   # raises Reeve::IncompleteInventoryError, carrying the report
+```
+
+**Dispatch through it, and a bypass stops being possible:**
+
+```ruby
+def call_tool
+  name = params.dig(:params, :name)
+  arguments = params.dig(:params, :arguments).to_h.symbolize_keys
+
+  result = McpInventory.dispatch(name, arguments: arguments,
+                                       agent: { id: request.headers["X-MCP-Client"] }) do
+    McpServer.handlers.fetch(name).call(arguments)
+  end
+
+  render json: { jsonrpc: "2.0", id: params[:id], result: serialize(result) }
+rescue Reeve::DeniedError => e
+  render json: { jsonrpc: "2.0", id: params[:id],
+                 error: { code: -32_003, message: e.message } }
+end
+```
+
+- A **routed** name runs through `Reeve.invoke` under its class's guard, with the handler
+  block as the body. A registry of blocks needs one guarded class per tool to name its
+  policy, and nothing else — the block still does the work, and what it returns is scoped.
+  Handlers dispatched this way should not call `Reeve.invoke` themselves.
+- An **exempt** name runs the block as written.
+- **Any other name** is a tool with no guard, and `unguarded_tools` decides: refused with
+  `unbound_tool` under `:deny`, the default; run unscoped and recorded with `guard: "none"`
+  under `:allow_with_warning`. Recorded either way, so a name the inventory missed lands on
+  the same ledger worklist as an unguarded class.
+
+**In the compliance suite,** `EndpointCoverage` compares the run against the inventory. It
+passes only when every registered tool is guarded or exempt and the run covered all of
+them. It fails when the run claimed the whole endpoint and something bypasses Reeve. A run
+narrowed by `compliance_tools` is reported as a subset — skipped, naming what it left out —
+so a retrofit stays green without passing for complete coverage.
+
 Policies are plain objects unless you want Pundit (`authorize` and `scope`, two methods).
 The ledger is an ActiveRecord table unless you supply your own recorder. Records are
 ActiveRecord unless they are not — a plain object with an `id` works.

data/lib/reeve/authorization.rb

@@ -42,7 +42,7 @@ module Reeve
           registry: registry,
           authorizer: Authorization::Authorizer.new,
           scoper: Authorization::Scoper.new,
-          config: configuration_for(principal)
+          config: config.with_principal(principal)
         ) { body ? body.call : run(tool, arguments) }
       end
     end
@@ -62,15 +62,5 @@ module Reeve
 
       Authorization::Declaration.new(tool_class: klass, policy: nil, action: :index).tool_name
     end
-
-    # An explicitly supplied principal is just a resolver that returns it. Routing it
-    # through the same resolution step rather than around it keeps one answer to "where
-    # did this principal come from" — the envelope still resolves, records and denies
-    # identically, and a nil passed in still denies with `no_principal`.
-    def configuration_for(principal)
-      return config if principal == :unset
-
-      config.dup.tap { |scoped| scoped.principal_resolver = ->(_context) { principal } }
-    end
   end
 end

data/lib/reeve/configuration.rb

@@ -24,7 +24,7 @@ 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
+      compliance_principals compliance_tools inventory
     ].freeze
 
     attr_reader(*SETTINGS)
@@ -41,6 +41,30 @@ module Reeve
       @logger             = nil
       @compliance_principals = nil
       @compliance_tools = nil
+      @inventory = nil
+    end
+
+    # The host's whole tool inventory (Reeve::Inventory). Optional. Setting it is what lets
+    # the compliance suite say whether it covered the endpoint or only the tools reeve
+    # happened to be told about.
+    def inventory=(inventory)
+      unless inventory.nil? || inventory.is_a?(Inventory)
+        raise ArgumentError, "inventory must be a Reeve::Inventory, got #{inventory.inspect}"
+      end
+
+      @inventory = inventory
+    end
+
+    # This configuration with the principal fixed for one invocation.
+    #
+    # An explicitly supplied principal is just a resolver that returns it. Routing it
+    # through the same resolution step rather than around it keeps one answer to "where
+    # did this principal come from" — the envelope still resolves, records and denies
+    # identically, and a nil passed in still denies with `no_principal`.
+    def with_principal(principal)
+      return self if principal == :unset
+
+      dup.tap { |scoped| scoped.principal_resolver = ->(_context) { principal } }
     end
 
     # Two fixture principals with disjoint records — the only host setup the compliance

data/lib/reeve/decision.rb

@@ -18,6 +18,10 @@ module Reeve
     # ledger records it as a deny — the trace of a call that blew up is the one most
     # worth having (R5).
     TOOL_ERROR              = "tool_error"
+    # A name dispatched through an Inventory that neither routes it through reeve nor
+    # exempts it. Not `no_guard_declared`: there may be no class to declare one on, and
+    # the fix is in the inventory.
+    UNBOUND_TOOL            = "unbound_tool"
 
     # The one reserved *allow* rule: a tool with no guard, permitted because the host
     # opted into :allow_with_warning. Kept out of RESERVED_RULES, which names deny paths.
@@ -33,7 +37,8 @@ module Reeve
       UNSCOPED_DERIVED_RESULT,
       OUT_OF_SCOPE_RECORD,
       AUDIT_WRITE_FAILED,
-      TOOL_ERROR
+      TOOL_ERROR,
+      UNBOUND_TOOL
     ].freeze
 
     OUTCOMES = %i[allow deny].freeze

data/lib/reeve/errors.rb

@@ -57,6 +57,19 @@ module Reeve
     end
   end
 
+  # Raised by Inventory#verify! when a registered tool is not protected: routed through
+  # reeve with no guard, not routed at all, or declared in the inventory but not registered
+  # with the server. The message is the whole report — tool names, classes and exemption
+  # reasons, never an argument, a principal or a record.
+  class IncompleteInventoryError < Error
+    attr_reader :report
+
+    def initialize(report)
+      @report = report
+      super(report.to_s)
+    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/inventory/report.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Reeve
+  class Inventory
+    # Every registered name, in one of four states, plus whatever the inventory declares
+    # that the server does not register.
+    #
+    # The output names tools, tool classes and exemption reasons, and nothing else. It is
+    # built before any invocation and knows no arguments, principals or records, so it is
+    # safe to print in a CI log or a boot failure — there is nothing in it to redact.
+    #
+    #   reeve inventory: 6 registered
+    #     4 protected and guarded
+    #     1 routed through reeve but unguarded
+    #     1 bypasses reeve
+    #     0 exempted
+    #   coverage: incomplete
+    class Report
+      attr_reader :entries
+
+      def initialize(registered, routes, reasons)
+        @entries = (classify(registered, routes, reasons) +
+                    unregistered(registered, routes, reasons)).freeze
+        freeze
+      end
+
+      # Every registered name is either guarded or deliberately exempt, and the inventory
+      # names nothing the server does not register.
+      #
+      # That last part is not tidiness. A route for a name the server does not register is
+      # almost always a rename or a typo — and the real name, the one being dispatched, is
+      # then the one with no route.
+      def complete?
+        unguarded.empty? && bypassing.empty? && unregistered_entries.empty?
+      end
+
+      def registered
+        entries.reject { |entry| entry.status == :unregistered }
+      end
+
+      def guarded
+        select(:guarded)
+      end
+
+      def unguarded
+        select(:unguarded)
+      end
+
+      def bypassing
+        select(:bypass)
+      end
+
+      def exempted
+        select(:exempt)
+      end
+
+      def unregistered_entries
+        select(:unregistered)
+      end
+
+      # The classes routed to a registered name.
+      def routed_tools
+        entries.filter_map(&:tool).uniq
+      end
+
+      def to_s
+        [summary, *entries.filter_map { |entry| detail(entry) }].join("\n")
+      end
+
+      def inspect
+        "#<Reeve::Inventory::Report #{registered.size} registered, " \
+          "coverage: #{complete? ? 'complete' : 'incomplete'}>"
+      end
+
+      private
+
+      def select(status)
+        entries.select { |entry| entry.status == status }
+      end
+
+      def classify(registered, routes, reasons)
+        registered.map do |name|
+          tool = routes[name]
+          if tool
+            status = Reeve.registry.for_class(tool) ? :guarded : :unguarded
+            Entry.new(name: name, status: status, tool: tool)
+          elsif reasons.key?(name)
+            Entry.new(name: name, status: :exempt, reason: reasons[name])
+          else
+            Entry.new(name: name, status: :bypass)
+          end
+        end
+      end
+
+      def unregistered(registered, routes, reasons)
+        (routes.keys | reasons.keys).reject { |name| registered.include?(name) }.map do |name|
+          Entry.new(name: name, status: :unregistered, tool: routes[name],
+                    reason: reasons[name])
+        end
+      end
+
+      def summary
+        ["reeve inventory: #{registered.size} registered", *counts.map { |line| "  #{line}" },
+         "coverage: #{complete? ? 'complete' : 'incomplete'}"].join("\n")
+      end
+
+      def counts
+        lines = [
+          "#{guarded.size} protected and guarded",
+          "#{unguarded.size} routed through reeve but unguarded",
+          "#{bypassing.size} #{bypassing.size == 1 ? 'bypasses' : 'bypass'} reeve",
+          "#{exempted.size} exempted"
+        ]
+        return lines if unregistered_entries.empty?
+
+        lines << "#{unregistered_entries.size} declared but not registered"
+      end
+
+      # One line saying what is wrong and one saying what to do, for everything but a
+      # guarded tool — which needs neither. Exemptions are listed even when coverage is
+      # complete: a deliberate hole is still a hole, and it should be read every time.
+      def detail(entry)
+        case entry.status
+        when :unguarded
+          "\nUNGUARDED #{entry.name}\n  routed to #{label(entry.tool)}, which has no " \
+          "guard_with declaration — reeve denies it, or runs it unscoped under " \
+          ":allow_with_warning"
+        when :bypass
+          "\nBYPASS #{entry.name}\n  registered with the server but neither routed " \
+          "through reeve nor exempted — route it to a guarded tool, or exempt it with a " \
+          "reason"
+        when :exempt
+          "\nEXEMPT #{entry.name}\n  #{entry.reason}"
+        when :unregistered
+          what = entry.tool ? "routed to #{label(entry.tool)}" : "exempted"
+          "\nNOT REGISTERED #{entry.name}\n  #{what}, but the server registers no tool " \
+            "by that name — if it was renamed, the new name is unbound"
+        end
+      end
+
+      def label(tool)
+        tool.name || tool.inspect
+      end
+    end
+  end
+end

data/lib/reeve/inventory.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+module Reeve
+  # The host's whole tool inventory, stated against what reeve was told about.
+  #
+  # Reeve only sees an invocation that reaches `Reeve.invoke`. A server that registers its
+  # tools as names and handler blocks can route some of them through the envelope and
+  # dispatch the rest directly, and the direct ones are invisible: neither guarded nor
+  # reported as unguarded. Every guarantee reeve makes — deny by default, scoping, the
+  # ledger — is skipped together for them, and nothing anywhere says so. The registry
+  # cannot answer "is every tool this endpoint dispatches protected?" because the tools
+  # that are not are, by construction, the ones it never heard of.
+  #
+  # The inventory makes the host's list of registered names the thing being checked:
+  #
+  #   McpInventory = Reeve::Inventory.new(
+  #     registered: -> { McpServer.tool_names },
+  #     routed: -> { { "search_invoices" => InvoiceSearchTool } },
+  #     exemptions: { "healthcheck" => { reason: "returns no application data" } }
+  #   )
+  #
+  #   McpInventory.verify!   # at boot, or in CI
+  #
+  # and, optionally, the place the host dispatches through, so that a name it has no
+  # entry for is refused rather than run:
+  #
+  #   McpInventory.dispatch(name, arguments: args) { handlers.fetch(name).call(args) }
+  #
+  # Every part takes a value or a callable returning one. A Rails initializer cannot
+  # reference application constants, and a server registers its tools after the
+  # initializer runs, so the lists are read when asked for rather than when declared.
+  #
+  # Nothing here depends on an MCP library. A list of names is the whole protocol.
+  class Inventory
+    # One registered name, classified. +tool+ is the class it is routed to, if any;
+    # +reason+ is the stated reason for an exemption.
+    Entry = Struct.new(:name, :status, :tool, :reason, keyword_init: true)
+
+    def initialize(registered:, routed: {}, exemptions: {})
+      @registered = registered
+      @routed     = routed
+      @exemptions = exemptions
+
+      # Literal values are checked now, so a blank exemption reason fails on the line that
+      # declared it. Callables cannot be until they are asked; #report checks those.
+      resolve unless [registered, routed, exemptions].any? { |part| part.respond_to?(:call) }
+    end
+
+    # The classification, read fresh. Raises ArgumentError if the inventory is malformed:
+    # a report built from a list it could not read would be a report about nothing.
+    def report
+      Report.new(*resolve)
+    end
+
+    # The strict gate: the report when coverage is complete, IncompleteInventoryError
+    # otherwise. Call it where failing is what you want — boot, a deploy step, CI.
+    def verify!
+      report.tap do |result|
+        raise IncompleteInventoryError, result unless result.complete?
+      end
+    end
+
+    # The tool classes the inventory routes through reeve. The testing kit certifies these.
+    def routed_tools
+      routes.values.uniq
+    end
+
+    # The dispatch boundary. A host that sends every tool call through here cannot have a
+    # tool that bypasses reeve, because the three answers are exhaustive:
+    #
+    # * **routed** — runs through `Reeve.invoke` with the class it is routed to. A handler
+    #   block, if given, is the body, so a registry of blocks needs one guarded class per
+    #   tool to say which policy governs it and nothing else.
+    # * **exempt** — the handler runs as it would have without reeve. That is what the
+    #   exemption says, and why it needs a reason.
+    # * **neither** — governed by `config.unguarded_tools`, exactly like a tool with no
+    #   guard. Under `:deny`, the default, the call is refused with `unbound_tool`; under
+    #   `:allow_with_warning` it runs unscoped. Either way it is recorded, so a name the
+    #   inventory missed shows up in the ledger rather than nowhere.
+    #
+    # +registered+ is not consulted. The host's own dispatcher already decided the name
+    # exists; what this decides is whether reeve stands in front of it.
+    def dispatch(name, arguments: {}, principal: :unset, agent: nil, metadata: {}, &handler)
+      name = name.to_s
+      tool = routes[name]
+      if tool
+        return Reeve.invoke(tool: tool, arguments: arguments, principal: principal,
+                            agent: agent, metadata: metadata, &handler)
+      end
+
+      if handler.nil?
+        raise ArgumentError, "#{name} is not routed to a tool, so dispatch needs the " \
+                             "handler block that runs it"
+      end
+
+      return handler.call if exemption_reasons.key?(name)
+
+      dispatch_unbound(name, arguments: arguments, principal: principal, agent: agent,
+                             metadata: metadata, &handler)
+    end
+
+    def inspect
+      "#<Reeve::Inventory>"
+    end
+
+    private
+
+    def resolve
+      names = registered_names
+      routes = self.routes
+      reasons = exemption_reasons
+
+      both = routes.keys & reasons.keys
+      unless both.empty?
+        raise ArgumentError, "a tool is either routed through reeve or exempt from it, " \
+                             "not both: #{both.join(', ')}"
+      end
+
+      [names, routes, reasons]
+    end
+
+    def registered_names
+      names = read(:registered, @registered)
+      unless names.respond_to?(:to_a) && !names.is_a?(Hash)
+        raise ArgumentError, "registered must list tool names, got #{names.inspect}"
+      end
+
+      names.to_a.map { |name| name_from(:registered, name) }.uniq
+    end
+
+    def routes
+      read_hash(:routed, @routed).to_h do |name, tool|
+        unless tool.is_a?(Class)
+          raise ArgumentError, "routed must map each name to a tool class; " \
+                               "#{name} maps to #{tool.inspect}"
+        end
+
+        [name_from(:routed, name), tool]
+      end
+    end
+
+    # An exemption with no reason is a hole someone forgot about. With one, it is a
+    # decision someone can be asked about.
+    def exemption_reasons
+      read_hash(:exemptions, @exemptions).to_h do |name, options|
+        name = name_from(:exemptions, name)
+        reason = options.is_a?(Hash) ? (options[:reason] || options["reason"]) : nil
+        if reason.nil? || reason.to_s.strip.empty?
+          raise ArgumentError, "the exemption for #{name} needs a reason, e.g. " \
+                               "{ \"#{name}\" => { reason: \"returns no application data\" } }"
+        end
+
+        [name, reason.to_s.strip]
+      end
+    end
+
+    def read_hash(part, source)
+      value = read(part, source)
+      return value if value.is_a?(Hash)
+
+      raise ArgumentError, "#{part} must be a Hash keyed by tool name, got #{value.inspect}"
+    end
+
+    def read(part, source)
+      value = source.respond_to?(:call) ? source.call : source
+      raise ArgumentError, "#{part} is nil" if value.nil?
+
+      value
+    end
+
+    def name_from(part, name)
+      string = name.respond_to?(:to_str) || name.is_a?(Symbol) ? name.to_s.strip : nil
+      return string unless string.nil? || string.empty?
+
+      raise ArgumentError, "#{part} contains a blank or non-string tool name: #{name.inspect}"
+    end
+
+    # A name the inventory has no entry for still goes through the envelope, under its
+    # own name and with nothing to look up. The registry answer below is what makes the
+    # refusal name the real cause — the inventory, not a missing `guard_with` on a class
+    # that may not exist.
+    def dispatch_unbound(name, arguments:, principal:, agent:, metadata:, &handler)
+      config = Reeve.config.with_principal(principal)
+      context = Context.new(tool_name: name, agent: agent, arguments: arguments,
+                            metadata: metadata)
+
+      Invocation.call(context, registry: Unbound.new(name, config), config: config, &handler)
+    end
+
+    # The registry the envelope consults for an unbound name. Under `:deny` it answers
+    # with the refusal itself; under `:allow_with_warning` it has no guard to offer, and
+    # the envelope runs the tool unscoped and records `guard: "none"` — the same worklist
+    # an unguarded class lands on.
+    class Unbound
+      def initialize(name, config)
+        @name = name
+        @config = config
+      end
+
+      def guard_for(_tool_name)
+        return nil if @config.unguarded_tools == :allow_with_warning
+
+        Decision.deny(
+          rule: Decision::UNBOUND_TOOL,
+          detail: "#{@name} is neither routed through reeve nor exempted in the inventory"
+        )
+      end
+    end
+  end
+end
+
+require_relative "inventory/report"

data/lib/reeve/invocation.rb

@@ -90,7 +90,9 @@ module Reeve
       context.principal = principal
 
       guard = look_up_guard
-      return guard if guard.is_a?(Decision) # registry blew up
+      # A registry may answer with a refusal instead of a guard: the lookup raised, or an
+      # Inventory is refusing a name it has no entry for.
+      return guard if guard.is_a?(Decision)
 
       if guard.nil?
         if deny_unguarded?

data/lib/reeve/testing/assertions.rb

@@ -56,14 +56,14 @@ module Reeve
         )
       end
 
-      # SC-009's escape hatch: any of the seven, straight from Minitest.
+      # SC-009's escape hatch: any check, straight from Minitest.
       def assert_reeve_check(check)
         result = check.call
         assert result.passed?, result.message
         result
       end
 
-      # A whole Report at once, for a host that would rather have one test than seven.
+      # A whole Report at once, for a host that would rather have one test than one per check.
       def assert_reeve_compliance(principals: nil, **options)
         report = Checks.run_all(
           principals: principals || Testing.compliance_principals, **options

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

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Testing
+    module Checks
+      # Whether the run covered the endpoint, or only the tools reeve was told about.
+      #
+      # Every other check walks a population reeve assembled itself: the classes that
+      # included `Reeve::Guard`. A server that dispatches some tools without ever handing
+      # them to reeve leaves them out of that population, and the run goes green on the
+      # subset it could see. This check compares the run against the host's own list of
+      # registered names (`config.inventory`), so a green run can only mean the endpoint.
+      #
+      # Four answers, and only one of them is a pass:
+      #
+      # * **no inventory declared** — skipped. Reeve cannot know what the server registers
+      #   unless told, and a pass here would be the green that means "did not look".
+      # * **a subset** — skipped, when the host narrowed the run with `compliance_tools` or
+      #   `tools:`. That is the incremental-adoption path; the run says what it certified
+      #   and that it is not the endpoint, without turning the build red mid-retrofit.
+      # * **incomplete** — failed: a registered tool bypasses reeve or reaches it unguarded,
+      #   and the run claimed to cover everything.
+      # * **complete** — passed.
+      #
+      #   Reeve::Checks::EndpointCoverage.new.call
+      #   Reeve::Checks::EndpointCoverage.new(inventory: McpInventory).call
+      class EndpointCoverage < Base
+        def initialize(inventory: :configured, tools: nil, ledger: nil)
+          super(ledger: ledger)
+          @inventory = inventory == :configured ? Reeve.config.inventory : inventory
+          @tools = tools
+        end
+
+        def call
+          return unverified if inventory.nil?
+
+          report = inventory.report
+          if narrowed?
+            subset(report)
+          elsif report.complete?
+            complete(report)
+          else
+            incomplete(report)
+          end
+        rescue StandardError => e
+          failed("the endpoint inventory could not be read, so its coverage is unknown: " \
+                 "#{e.class}: #{e.message}", coverage: :unknown)
+        end
+
+        private
+
+        attr_reader :inventory
+
+        def narrowed?
+          !@tools.nil? || Testing.compliance_tools_narrowed?
+        end
+
+        def certified
+          @certified ||= @tools || Testing.compliance_tools
+        end
+
+        def unverified
+          skipped(
+            "no endpoint inventory is declared, so this run certifies the " \
+            "#{pluralize(certified.size, 'tool')} reeve knows about and cannot say whether " \
+            "the server dispatches others outside it — set config.inventory to a " \
+            "Reeve::Inventory to verify the endpoint",
+            coverage: :unverified
+          )
+        end
+
+        def complete(report)
+          passed(
+            "every one of the #{pluralize(report.registered.size, 'tool')} the server " \
+            "registers is protected and guarded (#{report.guarded.size}) or exempted " \
+            "(#{report.exempted.size})",
+            coverage: :complete
+          )
+        end
+
+        def incomplete(report)
+          failed(
+            "expected every tool the server registers to be protected by reeve or " \
+            "exempted, but #{gaps(report)}\n\n#{report}",
+            coverage: :incomplete
+          )
+        end
+
+        # Complete coverage with a narrowed run is still a subset: the inventory is sound,
+        # but this run did not certify all of it.
+        def subset(report)
+          routed = report.routed_tools
+          missing = routed - certified
+          lines = [
+            "this run certifies a subset, not the endpoint: " \
+            "#{(routed - missing).size} of the #{pluralize(routed.size, 'tool')} routed " \
+            "through reeve (compliance_tools or tools: narrowed it)"
+          ]
+          lines << "not certified: #{missing.map { |tool| tool.name || tool.inspect }.join(', ')}" \
+            unless missing.empty?
+          lines << "" << report.to_s unless report.complete?
+
+          skipped(lines.join("\n"), coverage: :subset)
+        end
+
+        def gaps(report)
+          [
+            gap(report.bypassing, "bypasses it", "bypass it"),
+            gap(report.unguarded, "is routed through it unguarded",
+                "are routed through it unguarded"),
+            gap(report.unregistered_entries, "declared in the inventory is not registered",
+                "declared in the inventory are not registered")
+          ].compact.join(", ")
+        end
+
+        def gap(entries, one, many)
+          return nil if entries.empty?
+
+          "#{entries.size} #{entries.size == 1 ? one : many}"
+        end
+
+        # Only this check can come back with nothing established either way.
+        def skipped(message, details = {})
+          Result.skipped(check: check_name, message: message, details: details)
+        end
+
+        def base_details
+          {}
+        end
+      end
+    end
+  end
+end

data/lib/reeve/testing/checks.rb

@@ -8,10 +8,11 @@ require_relative "checks/rule_present"
 require_relative "checks/redaction_holds"
 require_relative "checks/principal_required"
 require_relative "checks/contract_version"
+require_relative "checks/endpoint_coverage"
 
 module Reeve
   module Testing
-    # The seven guarantees, as objects.
+    # The guarantees, as objects.
     #
     # This is the whole of the testing kit's logic. The RSpec matchers and the Minitest
     # assertions are adapters over it and contain no assertions of their own, which is why
@@ -29,11 +30,13 @@ module Reeve
         RulePresent,
         RedactionHolds,
         PrincipalRequired,
-        ContractVersion
+        ContractVersion,
+        EndpointCoverage
       ].freeze
 
-      # The checks that are asked once about the ledger rather than once per tool.
-      GLOBAL = [ContractVersion].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
 
       # The compliance suite's engine (FR-018): every check, against every registered
       # guarded tool, in one Report.
@@ -53,7 +56,10 @@ module Reeve
       # test method out of, so that a failing suite names the guarantee that broke rather
       # than reporting "compliance" as one undifferentiated red.
       def self.run(check, principals:, tools: nil, arguments: {}, invoke: nil, ledger: nil)
-        return Report.new([check.new(ledger: ledger).call]) if GLOBAL.include?(check)
+        if GLOBAL.include?(check)
+          return Report.new([build(check, tool: nil, principals: principals, tools: tools,
+                                          ledger: ledger).call])
+        end
 
         subjects = tools || Testing.compliance_tools
         Report.new(
@@ -74,12 +80,17 @@ module Reeve
 
       # The one place that knows what each check's constructor wants. Front-ends and hosts
       # ask for a check by class and get a configured one back.
-      def self.build(check, tool:, principals:, arguments: {}, invoke: nil, ledger: nil)
+      #
+      # +tools+ is the population the run was given, which only EndpointCoverage reads: an
+      # explicit list is a narrowed run, and it must say so.
+      def self.build(check, tool:, principals:, arguments: {}, invoke: nil, ledger: nil,
+                     tools: nil)
         common = { tool: tool, arguments: arguments, invoke: invoke, ledger: ledger }
 
         case check.check_name
         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 "PrincipalRequired"  then PrincipalRequired.new(**common)
         when "CrossPrincipalLeak" then CrossPrincipalLeak.new(principals: Array(principals),
                                                               **common)

data/lib/reeve/testing/compliance_assertions.rb

@@ -15,7 +15,8 @@ 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.
+    # undifferentiated failure. A check that could establish nothing either way is
+    # skipped with its reason, never passed.
     module ComplianceAssertions
       include Assertions
 
@@ -25,6 +26,7 @@ module Reeve
 
         define_method(method_name) do
           report = Checks.run(check, principals: Testing.compliance_principals)
+          skip(report.to_s) if report.skipped?
           assert report.passed?, report.to_s
           report
         end

data/lib/reeve/testing/compliance_suite.rb

@@ -11,11 +11,14 @@
 #   Reeve::Testing.compliance_principals = -> { [users(:alice), users(:bob)] }
 #
 # 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.
+# 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.
 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
       report = Reeve::Checks.run(check, principals: Reeve::Testing.compliance_principals)
+      skip(report.to_s) if report.skipped?
 
       expect(report).to be_passed, report.to_s
     end

data/lib/reeve/testing/matchers/pass_reeve_check.rb

@@ -3,7 +3,7 @@
 module Reeve
   module Testing
     module Matchers
-      # The escape hatch that keeps SC-009 honest: every one of the seven checks is
+      # The escape hatch that keeps SC-009 honest: every check is
       # assertable from RSpec, not only the two with names of their own.
       #
       #   expect(Reeve::Checks::RedactionHolds.new(tool: T, principal: alice))

data/lib/reeve/testing/report.rb

@@ -15,6 +15,8 @@ module Reeve
         freeze
       end
 
+      # Nothing failed. A skip is not a failure — and it is printed, so it is not
+      # mistaken for a pass either.
       def passed?
         failures.empty?
       end
@@ -23,20 +25,31 @@ module Reeve
         !passed?
       end
 
+      # Every result was a skip: the run established nothing either way. The front-ends
+      # report this as a skipped test rather than a green one.
+      def skipped?
+        !results.empty? && results.all?(&:skipped?)
+      end
+
       def failures
-        results.reject(&:passed?)
+        results.select(&:failed?)
       end
 
       def passes
         results.select(&:passed?)
       end
 
+      def skips
+        results.select(&:skipped?)
+      end
+
       def size
         results.size
       end
 
       def to_s
-        [summary, *failures.map { |result| detail(result) }].join("\n")
+        [summary, *failures.map { |result| detail("FAIL", result) },
+         *skips.map { |result| detail("SKIP", result) }].join("\n")
       end
 
       def inspect
@@ -46,12 +59,15 @@ module Reeve
       private
 
       def summary
-        "reeve compliance: #{size} #{size == 1 ? 'check' : 'checks'}, " \
-          "#{passes.size} passed, #{failures.size} failed"
+        line = "reeve compliance: #{size} #{size == 1 ? 'check' : 'checks'}, " \
+               "#{passes.size} passed, #{failures.size} failed"
+        skips.empty? ? line : "#{line}, #{skips.size} skipped"
       end
 
-      def detail(result)
-        "\nFAIL #{result.check}\n  #{result.message}"
+      # Every line of a multi-line message indented, so it reads as one block under its
+      # heading rather than as stray lines of the report.
+      def detail(heading, result)
+        "\n#{heading} #{result.check}\n  #{result.message.gsub("\n", "\n  ")}"
       end
     end
   end

data/lib/reeve/testing/result.rb

@@ -9,31 +9,51 @@ module Reeve
     # Minitest assertion, a rake task — reads +message+ and prints it; none of them
     # composes their own (FR-019). That is what makes the same violation read identically
     # from all three.
+    #
+    # A result is passed, failed, or skipped. Skipped is for a guarantee the run could not
+    # establish either way — endpoint coverage with no inventory declared. Reporting that
+    # as a pass would be the green that means "we did not look"; reporting it as a failure
+    # would turn every build red over a question the host never asked. A skip is printed,
+    # and shows up yellow in both test frameworks, so it is neither.
     class Result
-      attr_reader :check, :message, :details
+      STATUSES = %i[passed failed skipped].freeze
+
+      attr_reader :check, :message, :details, :status
 
       def self.passed(check:, message:, details: {})
-        new(check: check, passed: true, message: message, details: details)
+        new(check: check, status: :passed, message: message, details: details)
       end
 
       def self.failed(check:, message:, details: {})
-        new(check: check, passed: false, message: message, details: details)
+        new(check: check, status: :failed, message: message, details: details)
+      end
+
+      def self.skipped(check:, message:, details: {})
+        new(check: check, status: :skipped, message: message, details: details)
       end
 
-      def initialize(check:, passed:, message:, details: {})
+      def initialize(check:, status:, message:, details: {})
+        unless STATUSES.include?(status)
+          raise ArgumentError, "status must be one of #{STATUSES.inspect}, got #{status.inspect}"
+        end
+
         @check   = check.to_s
-        @passed  = passed ? true : false
+        @status  = status
         @message = message.to_s
         @details = details.freeze
         freeze
       end
 
       def passed?
-        @passed
+        status == :passed
       end
 
       def failed?
-        !@passed
+        status == :failed
+      end
+
+      def skipped?
+        status == :skipped
       end
 
       def to_s
@@ -41,7 +61,7 @@ module Reeve
       end
 
       def inspect
-        "#<Reeve::Testing::Result #{check} #{passed? ? 'passed' : 'failed'} " \
+        "#<Reeve::Testing::Result #{check} #{status} " \
           "#{message.inspect}>"
       end
     end

data/lib/reeve/testing.rb

@@ -41,17 +41,23 @@ module Reeve
       end
 
       # The tools the suite walks. Unset means every tool reeve knows about — the classes
-      # that included the DSL, guarded or not. That default is what makes an unguarded
-      # tool visible rather than merely absent.
+      # that included the DSL, guarded or not, plus every class the endpoint inventory
+      # routes to, which need not have included anything. That default is what makes an
+      # unguarded tool visible rather than merely absent.
       attr_writer :compliance_tools
 
       def compliance_tools
         source = @compliance_tools || Reeve.config.compliance_tools
-        return Reeve.registry.tool_classes if source.nil?
+        return Reeve.registry.tool_classes | inventory_tools if source.nil?
 
         Array(source.respond_to?(:call) ? source.call : source)
       end
 
+      # The host said which tools it is certifying, so a run is a subset by its own account.
+      def compliance_tools_narrowed?
+        !(@compliance_tools || Reeve.config.compliance_tools).nil?
+      end
+
       def compliance_principals?
         !(@compliance_principals || Reeve.config.compliance_principals).nil?
       end
@@ -63,6 +69,16 @@ module Reeve
 
       private
 
+      # An inventory that cannot be read adds nothing here; EndpointCoverage fails on it
+      # by name, which is a better place to learn about it than an exception in every
+      # per-tool check.
+      def inventory_tools
+        inventory = Reeve.config.inventory
+        inventory ? inventory.routed_tools : []
+      rescue StandardError
+        []
+      end
+
       def missing_principals_message
         "the reeve compliance suite needs two fixture principals with disjoint records. " \
           "Set them in your test helper:\n\n  " \

data/lib/reeve/version.rb

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

data/lib/reeve.rb

@@ -8,6 +8,7 @@ require_relative "reeve/context"
 require_relative "reeve/scope_result"
 require_relative "reeve/invocation"
 require_relative "reeve/authorization"
+require_relative "reeve/inventory"
 
 # 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.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Victor Velazquez
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-03 00:00:00.000000000 Z
+date: 2026-10-01 00:00:00.000000000 Z
 dependencies: []
 description: |
   Reeve makes it safe for a Rails application to expose MCP (Model Context Protocol)
@@ -56,6 +56,8 @@ files:
 - lib/reeve/fast_mcp.rb
 - lib/reeve/integrations/fast_mcp/context_builder.rb
 - lib/reeve/integrations/fast_mcp/tool_extension.rb
+- lib/reeve/inventory.rb
+- lib/reeve/inventory/report.rb
 - lib/reeve/invocation.rb
 - lib/reeve/minitest.rb
 - lib/reeve/rspec.rb
@@ -67,6 +69,7 @@ files:
 - lib/reeve/testing/checks/base.rb
 - lib/reeve/testing/checks/contract_version.rb
 - 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/principal_required.rb
 - lib/reeve/testing/checks/redaction_holds.rb