reeve 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 225a220bbfd6168a26fdf67a816c8a580ca57ba996f97c7d1c9317755252d497
-  data.tar.gz: a5633fe99dedbc03796c82abf560eca68187fa783e5a9ceef1fb764b9a47d351
+  metadata.gz: 329fc869bdb15c7e60eb1923221aeccb1725821535c25186dafe77bda001cc44
+  data.tar.gz: 0f0781268bc7e90b1fad27a74bef611aa6aa65df3da37fb1351eb3f28524da15
 SHA512:
-  metadata.gz: c9bccface22cb54d935720a927dd5aff7c61582403f6d0aeada860be4f178d110d4ac94801a84d6a15993c0abad8a6b14ee0c1058311809ddf5575ddb57d1741
-  data.tar.gz: e43b1e0a1fb8900a45cb998997b45152ab726b21961c2b86ea5dea0cc0adb3e0f9e015cf7aed8cdcd6e39aa28d7e9c827ff85d11653b8aa5fab769844b1cdecb
+  metadata.gz: b5d6286339f5f034e76f74052e3d19f9560c55b45e9432e6583b50931ddf4425a1aa5bc5c0ea1200646a9085f972521a3d1e2c38d8cf654e8aa8004fa2be0e3f
+  data.tar.gz: 32c28f2c34294f7d2454b772a1fd7bd52af690c3bc6d46793e2ec23021c6c3bd5d0d4bc6ee5f04b990a36a5f8ada40e03677bd9efa5c2a099b08c6bcf4cac147

data/CHANGELOG.md

@@ -4,6 +4,80 @@ 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.4.0] - 2026-09-03
+
+Everything here came out of a second application integrating the gem — one that had put a
+handful of its MCP tools behind reeve and was about to guard its write tools next. Two
+defects surfaced from reviewing that work, and both were failures of the same kind: the
+gem reporting a guarantee it had not actually established.
+
+**The audit-entry contract is unchanged at `2`, so no migration is required.**
+
+Behaviour changes worth reading before upgrading:
+
+- A denied invocation now rolls the tool's work back. A guarded tool that writes and is
+  then refused used to leave the write behind.
+- A guarded tool that raises after writing now has that write rolled back too.
+- The compliance suite now reports tools that never declared a guard, so a suite that
+  passed before may legitimately fail now. That is the fix, not a regression — set
+  `config.compliance_tools` to what you have certified so far.
+
+### Fixed
+
+- **The compliance suite can see a tool that has no guard.** It walked the guard registry,
+  which holds one entry per `guard_with` — so every subject it checked had a guard by
+  construction, and `GuardDeclared`, the check whose whole job is naming tools that lack
+  one, could not fail. An application with three guarded tools and one that was forgotten
+  reported `4 checks, 4 passed`. The gem's own quickstart demonstrated this: it ships a
+  deliberately unguarded tool and then asserted that the compliance run passed.
+
+  Tools are now recorded when they include `Reeve::Guard`, declared or not — through
+  inheritance too, so an adapter that includes the DSL into a base class once (fast-mcp)
+  no longer hides every tool built on it. `Reeve.registry.unguarded_tool_classes` is the
+  worklist. A base class that carries the DSL for its subclasses declares itself with
+  `reeve_abstract!` rather than being guessed at: inferring "anything with a subclass is a
+  base" would silently drop a real tool from the run the moment someone subclassed it.
+
+  **Reeve can only see tools that reached it.** An MCP server dispatching tools reeve was
+  never told about is still invisible to it — pass `tools:` to certify the real inventory.
+
+- **A denied invocation no longer leaves the host's data changed.** The envelope
+  authorizes before the tool runs, with the model class as the subject because no record
+  exists yet, and scopes the return value afterwards. A write tool lives between those two
+  points: it fetched a record, changed it, and only then was refused. The caller saw
+  `out_of_scope_record`, the ledger recorded a denial — and the row in the database had
+  already been rewritten by a principal who could not see it. A `deny` that follows a
+  committed write is not a partial guarantee, it is a false statement in the artifact the
+  ledger exists to be.
+
+  The tool body now runs in a transaction and a scope denial rolls it back. `requires_new`
+  makes it a savepoint, so a transaction the host opened around the invocation is left
+  alone — the rollback reaches the tool's work and stops there. Measured overhead is at or
+  below noise on a read-only call.
+
+  Two consequences worth knowing:
+
+  - A tool that **writes and then raises** now has that write rolled back too. It was
+    already recorded as `tool_error`; the data now matches what the ledger said.
+  - A host with no ActiveRecord, or with the library loaded but no connection, keeps the
+    previous behaviour — there is nothing to roll back, and neither should be made to fail.
+
+### Added
+
+- **`config.compliance_tools`** — which tools the suite certifies, as an array or a
+  callable, defaulting to every tool reeve knows about. A retrofit is the normal state of
+  an application adopting this, and now that unguarded tools are reported, one that has
+  guarded three of thirty has a red build it cannot honestly turn green. A build expected
+  to be red is a build nobody reads. Narrowing the list states what has been certified —
+  a claim that can go green and stay green as the list grows.
+
+- **`authorize!(record)`** inside a tool body — asks the declared policy about one record
+  and returns it, raising `DeniedError` if the policy says no. For the part of a tool a
+  rollback cannot reach: a sent email, a webhook, a written file. A denial raised this way
+  carries the policy's own rule into the ledger rather than being filed as `tool_error`,
+  and names no record, so a refusal and a record that does not exist still read the same
+  (FR-006).
+
 ## [0.3.0] - 2026-08-17
 
 Three of the limitations 0.1.0 shipped knowingly are now closed, and the audit-entry

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.3.0.** Read the known limitations in
+> **Status: 0.4.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.
 
@@ -119,6 +119,42 @@ end
 Reaching for `Invoice.sum(:cents)` there is denied with `unscoped_derived_result`. The
 guarantee is structural, not a matter of remembering.
 
+## Tools that write
+
+A denial means nothing happened. Authorization runs before the tool, but with the model
+class as its subject — for an index-style check there is no record yet — so the per-record
+answer only arrives once the tool has returned something to scope. A write tool sits
+between those two points:
+
+```ruby
+def call(id:, number:)
+  invoice = Invoice.find(id)        # unscoped fetch
+  invoice.update!(number: number)   # ...then a write
+  invoice
+end
+```
+
+The tool body runs in a transaction, and a scope denial rolls it back. Someone else's
+record is refused *and* unchanged, and the ledger's `deny` is a true statement about the
+database. A transaction the host opened around the invocation is untouched — the rollback
+reaches the tool's work and stops there.
+
+What a rollback cannot reach is anything that was never in the transaction. A tool that
+sends an email, calls a webhook or writes a file before it knows whether it is allowed to
+must ask first:
+
+```ruby
+def call(id:, to:)
+  invoice = authorize!(Invoice.find(id))   # raises DeniedError if the policy says no
+  InvoiceMailer.reminder(invoice, to).deliver_now
+  invoice
+end
+```
+
+`authorize!` asks the declared policy about one record and returns it, so it reads inline.
+The denial carries the policy's own rule into the ledger, and names no record — a refusal
+and a record that does not exist have to read the same.
+
 ## Every call leaves a trace
 
 One append-only row per invocation, allowed or denied, naming the agent, the principal, the
@@ -191,7 +227,29 @@ abort report.to_s unless report.passed?
 ```
 
 `alice` and `bob` are two fixture principals with disjoint records — that disjointness is
-what makes a shared record identifier proof of a leak. As a Rails rake task:
+what makes a shared record identifier proof of a leak.
+
+**The suite walks every tool that included `Reeve::Guard`, not only the ones that declared
+a guard.** A tool that forgot `guard_with` is the one worth finding, and it is absent from
+the guard registry by definition — so a run that only inspected guarded tools reported
+all-green on precisely the application that had a problem.
+
+Mid-retrofit that means a red build, which is honest but unreadable if it stays red for
+weeks. Say what you have certified so far, and grow the list:
+
+```ruby
+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)
+```
+
+As a Rails rake task:
 
 ```ruby
 # lib/tasks/reeve.rake

data/lib/reeve/authorization/guard.rb

@@ -16,10 +16,22 @@ module Reeve
   module Guard
     def self.included(base)
       base.extend(ClassMethods)
+      Reeve.registry.note(base)
     end
 
     # Class-level DSL. See contracts/tool-dsl.md.
     module ClassMethods
+      # Declares this class a base rather than a tool: it carries the DSL so its
+      # subclasses have it, and the compliance suite should not ask whether it is guarded.
+      #
+      #   class ApplicationTool
+      #     include Reeve::Guard
+      #     reeve_abstract!
+      #   end
+      def reeve_abstract!
+        Reeve.registry.mark_abstract(self)
+      end
+
       # Declares which policy governs this tool. Absence is not neutral: a tool with no
       # declaration is denied by the envelope (FR-002, FR-004).
       def guard_with(policy, action: nil)
@@ -59,8 +71,16 @@ module Reeve
 
       # A subclass of a guarded tool is itself guarded, and is registered under its own
       # name so the envelope — which only ever has a name — can find it.
+      #
+      # The note comes first and unconditionally, because a subclass of an *unguarded*
+      # base is the case worth catching: subclasses acquire the DSL without ever running
+      # `included`, so without this every fast-mcp tool would be invisible to the
+      # compliance suite — that adapter includes Guard into `FastMcp::Tool` once and lets
+      # inheritance do the rest.
       def inherited(subclass)
         super
+        Reeve.registry.note(subclass)
+
         declaration = reeve_guard
         # An anonymous subclass has no name to be looked up by; it still inherits the
         # declaration through the ancestry walk in Registry#for_class.
@@ -93,5 +113,38 @@ module Reeve
 
       Authorization::Scoper.scoped_relation(state, model_or_relation)
     end
+
+    # Asks the declared policy about one record, before the tool acts on it. Returns the
+    # record so it reads inline; raises +DeniedError+ if the policy says no.
+    #
+    #   def call(id:, to:)
+    #     invoice = authorize!(Invoice.find(id))
+    #     InvoiceMailer.reminder(invoice, to).deliver_now
+    #     invoice
+    #   end
+    #
+    # The envelope authorizes before the tool runs and scopes what it returns, and between
+    # those two points a tool can do things neither of them can reach. A rolled-back write
+    # leaves no trace; a sent email does. `scoped(...)` is the answer when a tool can work
+    # from a relation; this is the answer when it cannot — when the tool holds one record
+    # and is about to do something to the world with it.
+    #
+    # The denial carries the policy's own rule, so the ledger names what refused rather
+    # than reporting the tool as broken. It names no record: an out-of-scope record and a
+    # record that does not exist have to be indistinguishable (FR-006), and a tool that
+    # reached this line has already fetched the record it must not talk about.
+    def authorize!(record)
+      state = Authorization::Current.state
+      raise Error, "authorize!(...) may only be called inside a guarded invocation" if state.nil?
+
+      decision = state.adapter.authorize(
+        principal: state.context.principal, policy: state.declaration.policy,
+        action: state.declaration.action, record: record
+      )
+      return record if decision.allowed?
+
+      raise DeniedError.from(decision, tool_name: state.context.tool_name,
+                                       principal_id: state.context.principal_id)
+    end
   end
 end

data/lib/reeve/authorization/registry.rb

@@ -13,10 +13,49 @@ module Reeve
 
       def initialize
         @declarations = {}
+        @known = {}     # every class that included Guard, declared or not
+        @abstract = {}  # bases others inherit from; not tools themselves
         @name_index = nil # invalidated on every add; see #name_index
         @mutex = Mutex.new
       end
 
+      # A class that included the DSL. Recorded whether or not it goes on to declare
+      # anything, because a tool that forgot `guard_with` is precisely the one worth
+      # finding, and it is absent from `@declarations` by definition.
+      def note(tool_class)
+        @mutex.synchronize { @known[tool_class] = true }
+        tool_class
+      end
+
+      # A base others inherit from — `FastMcp::Tool`, or a host's own `ApplicationTool`.
+      # It acquires the DSL so its subclasses have it, and it is not itself a tool, so
+      # asking whether it declared a guard is a question with no useful answer.
+      #
+      # Explicit rather than inferred. The obvious heuristic — "a class something else
+      # inherits from is a base" — silently drops a real tool from the compliance run the
+      # moment someone subclasses it, and a check that quietly stops checking is the
+      # failure mode this whole file exists to prevent.
+      def mark_abstract(tool_class)
+        @mutex.synchronize { @abstract[tool_class] = true }
+        tool_class
+      end
+
+      def abstract?(tool_class)
+        @abstract.key?(tool_class)
+      end
+
+      # Every tool reeve knows about: the ones that declared a guard and the ones that
+      # only included the DSL. This is what the compliance suite walks, so that "all
+      # checks passed" cannot mean "we only looked at the tools that were already safe".
+      def tool_classes
+        (@known.keys | @declarations.keys).reject { |klass| abstract?(klass) }
+      end
+
+      # The worklist.
+      def unguarded_tool_classes
+        tool_classes.reject { |klass| @declarations.key?(klass) }
+      end
+
       # The DSL's `guard_with`. Declaring twice on one class is a mistake worth naming;
       # `add` is the quiet path used by `redact` and by inheritance, which refine an
       # existing declaration rather than compete with it.
@@ -74,6 +113,8 @@ module Reeve
       def remove(tool_class)
         @mutex.synchronize do
           @declarations.delete(tool_class)
+          @known.delete(tool_class)
+          @abstract.delete(tool_class)
           @name_index = nil
         end
       end
@@ -81,6 +122,8 @@ module Reeve
       def reset!
         @mutex.synchronize do
           @declarations = {}
+          @known = {}
+          @abstract = {}
           @name_index = nil
         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_principals compliance_tools
     ].freeze
 
     attr_reader(*SETTINGS)
@@ -40,11 +40,33 @@ module Reeve
       @audit_recorder     = nil
       @logger             = nil
       @compliance_principals = nil
+      @compliance_tools = nil
     end
 
     # Two fixture principals with disjoint records — the only host setup the compliance
     # suite needs (contracts/testing-kit.md). A callable rather than a value, because in a
     # Rails test suite the fixtures do not exist yet when the helper is loaded.
+    # Which tools the compliance suite certifies. Defaults to every tool reeve knows
+    # about, which is the answer a finished application wants.
+    #
+    # A host part-way through a retrofit needs the other answer. Once the suite reports
+    # unguarded tools — which is the whole point of it — an application with thirty tools
+    # and three guarded ones has a red build it cannot honestly turn green, and a red
+    # build that is expected to be red stops being read. Narrowing the list says "these
+    # are the ones I have certified", which is a claim that can go green and then stay
+    # green as the list grows.
+    #
+    #   config.compliance_tools = -> { [InvoiceSearchTool, InvoiceShowTool] }
+    def compliance_tools=(tools)
+      unless tools.nil? || tools.respond_to?(:call) || tools.is_a?(Array)
+        raise ArgumentError,
+              "compliance_tools must be an Array or a callable returning one, " \
+              "got #{tools.inspect}"
+      end
+
+      @compliance_tools = tools
+    end
+
     def compliance_principals=(principals)
       unless principals.nil? || principals.respond_to?(:call) || principals.is_a?(Array)
         raise ArgumentError,

data/lib/reeve/integrations/fast_mcp/tool_extension.rb

@@ -37,7 +37,11 @@ module Reeve
       # Idempotent: requiring "reeve/fast_mcp" twice must not stack two envelopes around
       # the same call.
       def install!(tool_base = ::FastMcp::Tool)
-        tool_base.include(Reeve::Guard) unless tool_base.include?(Reeve::Guard)
+        unless tool_base.include?(Reeve::Guard)
+          tool_base.include(Reeve::Guard)
+          # FastMcp::Tool carries the DSL for its subclasses; it is not itself a tool.
+          tool_base.reeve_abstract!
+        end
 
         unless tool_base.singleton_class.include?(Inheritance)
           tool_base.singleton_class.prepend(Inheritance)

data/lib/reeve/invocation.rb

@@ -152,13 +152,51 @@ module Reeve
       Decision.deny(rule: Decision::POLICY_ERROR, detail: "policy raised #{e.class}: #{e.message}")
     end
 
+    # A denial has to mean nothing happened.
+    #
+    # Authorization runs before the tool, but with the *class* as its subject — for an
+    # index-style check there is no record yet. The per-record answer only exists once the
+    # tool has returned something to scope. So a write tool used to mutate the record and
+    # then be refused its response: the caller saw `out_of_scope_record`, the ledger
+    # recorded a denial, and the row in the host's database had already changed. A denial
+    # in a compliance artifact that follows a committed write is not a partial guarantee,
+    # it is a false statement.
+    #
+    # Running the tool inside a transaction closes that. `requires_new` matters: under a
+    # transaction the host opened around the invocation this is a savepoint, so rolling
+    # back takes the tool's work and leaves the host's alone.
+    #
+    # What it cannot undo is anything that was never in the transaction — a sent email, a
+    # webhook, a file. A tool that reaches outside the database before it knows whether it
+    # is allowed to must ask first; `authorize!` in the tool body is for exactly that.
     def run_guarded(guard, decision, &tool)
+      return run_and_narrow(guard, decision, &tool) unless rollback_available?
+
+      ::ActiveRecord::Base.transaction(requires_new: true) do
+        outcome = run_and_narrow(guard, decision, &tool)
+        raise ::ActiveRecord::Rollback if @scope_result.denied?
+
+        outcome
+      end || @scope_result.decision
+    end
+
+    def run_and_narrow(guard, decision, &tool)
       result = execute(&tool)
 
       @scope_result = narrow(guard, result)
       @scope_result.denied? ? @scope_result.decision : decision
     end
 
+    # The core runs with no ActiveRecord at all (SC-008), and a host may have the library
+    # loaded without a connection. Neither can roll anything back, and neither should be
+    # made to fail here — they get the behaviour they had before, which the ledger still
+    # records truthfully because it records what the scoper decided either way.
+    def rollback_available?
+      defined?(::ActiveRecord::Base) && ::ActiveRecord::Base.connected?
+    rescue StandardError
+      false
+    end
+
     # The degraded mode a host opts into while retrofitting guards onto existing tools
     # (FR-023). The call is unscoped — that is the whole point of the warning.
     def run_unguarded(&tool)
@@ -171,6 +209,14 @@ module Reeve
 
     def execute(&tool)
       tool.call
+    rescue DeniedError => e
+      # A denial the tool raised on itself through `authorize!`. It is an authorization
+      # outcome, not a crash, and recording it as `tool_error` would file a policy saying
+      # no under the same rule as a NoMethodError. The rule the policy gave is carried
+      # through to the ledger unchanged.
+      @decision = Decision.deny(rule: e.rule, detail: e.detail)
+      @scope_result = ScopeResult.deny(rule: e.rule, detail: e.detail)
+      raise
     rescue StandardError => e
       # The tool's own failure propagates untouched, but not before the ensure block
       # records it: the invocations most worth having a trace of are the ones that broke.

data/lib/reeve/testing/checks.rb

@@ -55,7 +55,7 @@ module Reeve
       def self.run(check, principals:, tools: nil, arguments: {}, invoke: nil, ledger: nil)
         return Report.new([check.new(ledger: ledger).call]) if GLOBAL.include?(check)
 
-        subjects = tools || Reeve.registry.map(&:tool_class)
+        subjects = tools || Testing.compliance_tools
         Report.new(
           subjects.map do |tool|
             build(check, tool: tool, principals: principals, arguments: arguments,

data/lib/reeve/testing.rb

@@ -40,12 +40,25 @@ module Reeve
         principals
       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.
+      attr_writer :compliance_tools
+
+      def compliance_tools
+        source = @compliance_tools || Reeve.config.compliance_tools
+        return Reeve.registry.tool_classes if source.nil?
+
+        Array(source.respond_to?(:call) ? source.call : source)
+      end
+
       def compliance_principals?
         !(@compliance_principals || Reeve.config.compliance_principals).nil?
       end
 
       def reset!
         @compliance_principals = nil
+        @compliance_tools = nil
       end
 
       private

data/lib/reeve/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: reeve
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Victor Velazquez
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-17 00:00:00.000000000 Z
+date: 2026-09-03 00:00:00.000000000 Z
 dependencies: []
 description: |
   Reeve makes it safe for a Rails application to expose MCP (Model Context Protocol)