reeve 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aaf976c70abfbb4d56236acface7e1ef95a4e8c177452e4ef918ca22f45933d0
-  data.tar.gz: 9076bbad0582db6c4cda3c38dc89f97840dc3a7e2dbb99ca98a16c5b642ece57
+  metadata.gz: 329fc869bdb15c7e60eb1923221aeccb1725821535c25186dafe77bda001cc44
+  data.tar.gz: 0f0781268bc7e90b1fad27a74bef611aa6aa65df3da37fb1351eb3f28524da15
 SHA512:
-  metadata.gz: 7957d35a7e9df67acaa1c6babcd18b1d2340ffd63595fc88a11e16bd5c81cfa78ddb6b6cf17742f74b1f300d5e35058442d124fe77d6cc7051005e3ed4d5b837
-  data.tar.gz: 543bb727d1abf718053d21a72fe3d3eb62b9e82ebe5a3658046b7d80eb8c897c91e76da7d6c55842f1ee0545b76af94a2d1127ffa2fc814a88bbadab3c827a01
+  metadata.gz: b5d6286339f5f034e76f74052e3d19f9560c55b45e9432e6583b50931ddf4425a1aa5bc5c0ea1200646a9085f972521a3d1e2c38d8cf654e8aa8004fa2be0e3f
+  data.tar.gz: 32c28f2c34294f7d2454b772a1fd7bd52af690c3bc6d46793e2ec23021c6c3bd5d0d4bc6ee5f04b990a36a5f8ada40e03677bd9efa5c2a099b08c6bcf4cac147

data/CHANGELOG.md

@@ -4,6 +4,155 @@ 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
+contract is unchanged — **no migration is required to take this release**.
+
+Two of the "Known limitations" under 0.1.0 below no longer hold, and are left in place
+because that section records what was true of that release:
+
+- *"A transaction the host wraps around an invocation takes the ledger row with it"* —
+  `IsolatedRecorder` closes it where the database has concurrent writers.
+- *"CI runs SQLite only"* — the suite now runs on PostgreSQL and MySQL too.
+
+Still open from that list: an unscoped fetch by id disclosing existence, a scope-less type
+needing to be tied to its policy, `AuditCoverage` proving one invocation rather than every
+one, and the fast-mcp adapter needing Ruby 3.1+.
+
+### Added
+
+- **`Reeve::Audit::IsolatedRecorder`** — the ledger row on a connection of its own, which
+  closes the R5 limitation the first release documented rather than fixed. The default
+  recorder writes in a savepoint: the trace survives a rollback by the *tool*, but a
+  transaction the *host* wrapped around the whole invocation takes the row with it, and
+  the calls most worth auditing are exactly the ones that rolled back. A transaction on
+  one connection cannot roll back an INSERT committed on another.
+
+  ```ruby
+  config.audit_recorder = Reeve::Audit::IsolatedRecorder
+  ```
+
+  Opt-in rather than the default, because it cannot work everywhere the default does: on
+  SQLite an open transaction holds the database write lock, so a second connection would
+  block until it timed out and fail every guarded call. It raises `ConfigurationError`
+  there rather than degrading quietly, and `IsolatedRecorder.available?` answers the
+  question in an initializer for a host that develops on SQLite and deploys on PostgreSQL.
+  The default recorder's warning now names it.
+
+  Worth deciding knowingly: this also keeps the row when the host rolls back an
+  invocation it meant to undo entirely. A ledger of what was *attempted* is the intended
+  reading of Constitution II, but it is a choice.
+
+- **CI runs the suite on PostgreSQL and MySQL as well as SQLite.** The gem claims to work
+  on every database ActiveRecord supports — the ledger stores `invocation_id` as a string
+  rather than a native `uuid` precisely so that holds — and until now that claim had only
+  ever been executed against SQLite. The three engines disagree about exactly what this
+  gem leans on: what `t.json` becomes, what a boolean literal is, what
+  `change_column_default` does to a NOT NULL column, and how a savepoint behaves inside a
+  transaction the caller opened. Select an engine with `DB=postgresql` or `DB=mysql2`
+  (`DB=postgresql bundle install` first — the drivers are `install_if`-gated so the
+  default install needs no native client libraries).
+
+  All 545 examples pass on all three. The one portability defect it found was in the
+  `reeve:upgrade` spec rather than the library: a fixture row inserted `0` into boolean
+  columns, which is a boolean on SQLite and MySQL and a type error on PostgreSQL. The
+  `change_column_default` the upgrade migration depends on behaves identically on all
+  three, which was the specific thing worth knowing after shipping it against SQLite only.
+
+- **`bin/rails generate reeve:upgrade`** — brings an existing ledger up to the current
+  audit-entry contract. It asks the table which columns it has and emits only the steps
+  that are missing, so it is a no-op on a current ledger and safe to run twice before
+  migrating. Replaces the hand-written `add_column` the 0.2.0 notes had to give.
+  ([#11](https://github.com/vicmaster/reeve/issues/11))
+- `contracts/audit-entry.md` states the rule the upgrade path depends on: **changes to the
+  table must be additive**, and a new column must be nullable or carry a default that is
+  true of the rows already written. An append-only ledger has no honest value to backfill
+  into a historical row. A change that cannot be expressed additively is a new table, not
+  a new version of this one.
+
+### Fixed
+
+- `Checks::ContractVersion` names `reeve:upgrade` when the table is missing a column. It
+  said `reeve:install`, which is wrong for exactly the case it fires in: the table exists,
+  so Rails resolves that migration by name and either emits nothing or offers to overwrite
+  one that has already run — which does not touch the database and destroys the record of
+  what was applied. The install generator now says the same thing on its way out.
+
 ## [0.2.0] - 2026-08-12
 
 Everything here came out of running 0.1.0 against a real Rails 8.1 application rather than

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.2.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
@@ -136,6 +172,20 @@ A call whose tool raised is still recorded — that trace is the one most worth
 call that cannot be recorded fails, unless the host has explicitly opted into
 `audit_failure_mode = :warn`.
 
+If your application wraps invocations in a transaction — a controller that opens one per
+request, a job runner — a rollback takes the ledger row with it, and exactly the calls
+worth auditing are the ones that rolled back. Write on a connection the rollback cannot
+reach:
+
+```ruby
+config.audit_recorder = Reeve::Audit::IsolatedRecorder
+```
+
+It needs a database with concurrent writers and refuses on SQLite, where an open
+transaction holds the write lock; `IsolatedRecorder.available?` lets you branch if you
+develop on one and deploy on the other. The default recorder warns when it detects the
+case rather than failing silently.
+
 ## Provable in CI, in whichever framework you already use
 
 All the logic lives in framework-neutral checks. RSpec and Minitest are thin front-ends
@@ -177,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/generators/reeve/install/install_generator.rb

@@ -39,6 +39,10 @@ module Reeve
             2. Run `bin/rails db:migrate` to create the audit ledger.
 
           Then add `guard_with SomePolicy` to a tool.
+
+          Upgrading an existing ledger later? Use `rails g reeve:upgrade`, not this
+          generator — Rails resolves a migration by name, so re-running install cannot
+          deliver a shape change to a table that already exists.
         NEXT
       end
     end

data/lib/generators/reeve/install/templates/initializer.rb.tt

@@ -53,6 +53,25 @@ Reeve.configure do |config|
   #            guarantee for availability.
   config.audit_failure_mode = :fail
 
+  # ---------------------------------------------------------------------------
+  # Does your application wrap the invocation in a transaction?
+  #
+  # A controller that opens one per request, a job runner, a test suite with
+  # transactional fixtures — if that transaction rolls back, it takes the ledger
+  # row with it, and the default recorder can only warn about it.
+  #
+  #   config.audit_recorder = Reeve::Audit::IsolatedRecorder
+  #
+  # writes on a connection of its own, which a rollback on yours cannot reach.
+  # It needs a database with concurrent writers and refuses to run on SQLite, so
+  # a host that develops on SQLite and deploys on PostgreSQL branches:
+  #
+  #   config.audit_recorder =
+  #     Reeve::Audit::IsolatedRecorder.available? ? Reeve::Audit::IsolatedRecorder
+  #                                              : Reeve::Audit::Recorder
+  #
+  # Left unset, which resolves to Reeve::Audit::Recorder.
+
   # Cap on how many record identifiers one entry stores. The true count is
   # always recorded, and the entry says when the list was truncated.
   config.max_recorded_ids = 1000

data/lib/generators/reeve/upgrade/templates/add_contract_version_to_reeve_audit_entries.rb.tt

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Audit-entry contract 1 → 2. Generated by `bin/rails generate reeve:upgrade`.
+#
+# Adds the column that lets a row name the shape it was written under. Contract 1 wrote
+# `metadata` NULL whatever the caller passed, and contract 2 writes what was passed, so
+# without this column a NULL `metadata` is ambiguous: "never recorded" and "the caller
+# passed none" look identical, separable only by knowing when the gem was deployed.
+#
+# `default: 1` is not a fallback, it is the truth about the rows already in the table:
+# every one of them was written under contract 1. The default is then dropped, so a row
+# inserted from here on has to say what it is — which matches the shape a fresh
+# `reeve:install` creates, and keeps the two paths converged.
+class AddContractVersionToReeveAuditEntries < ActiveRecord::Migration[7.0]
+  def change
+    add_column :reeve_audit_entries, :contract_version, :integer, null: false, default: 1
+    change_column_default :reeve_audit_entries, :contract_version, from: 1, to: nil
+  end
+end

data/lib/generators/reeve/upgrade/upgrade_generator.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Reeve
+  module Generators
+    # `bin/rails generate reeve:upgrade` — brings an existing ledger up to the audit-entry
+    # contract this version of the gem writes.
+    #
+    # Why this exists as a second generator rather than as a re-run of `reeve:install`:
+    # Rails resolves a migration by name, so `install` on a host that already has
+    # `create_reeve_audit_entries` reports `identical` and emits nothing, or — once the
+    # template has changed, which is exactly the upgrade case — offers to overwrite a
+    # migration that has already run. Overwriting an applied migration does not touch the
+    # database and destroys the record of what was applied, so the one thing a host must
+    # never be told to do about an out-of-date ledger is run the install generator again.
+    #
+    # What it emits is decided by the table, not by a version number the host might have
+    # recorded wrongly or not at all: each step declares the columns it adds, and a step
+    # whose columns are all present has already been applied. That makes running this on a
+    # current ledger a no-op it can report rather than a duplicate migration.
+    class UpgradeGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      TABLE = "reeve_audit_entries"
+
+      # The ladder, oldest first. One entry per contract bump that touches the table.
+      #
+      # `adds` is what makes a step detectable, so it must name every column the step
+      # creates. A step that changes a column without adding one cannot be detected this
+      # way and needs its own predicate — see the additive-only rule in
+      # contracts/audit-entry.md, which exists so that stays hypothetical: an append-only
+      # ledger cannot be backfilled, so a column that is not additive has no honest value
+      # to give the rows already written.
+      STEPS = [
+        {
+          contract: 2,
+          adds: %w[contract_version],
+          template: "add_contract_version_to_reeve_audit_entries.rb.tt",
+          destination: "add_contract_version_to_reeve_audit_entries.rb"
+        }
+      ].freeze
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Brings an existing reeve audit ledger up to the current audit-entry contract."
+
+      def verify_ledger_exists
+        return if table_exists?
+
+        say <<~MISSING
+
+          There is no #{TABLE} table to upgrade.
+
+          This generator is for a ledger that already exists. For a new one:
+
+            bin/rails generate reeve:install
+            bin/rails db:migrate
+        MISSING
+
+        # Not an exception: "you wanted the other generator" is a normal thing to get
+        # wrong, and a backtrace would suggest reeve broke.
+        @halted = true
+      end
+
+      def create_upgrade_migrations
+        return if @halted
+
+        pending = STEPS.reject { |step| applied?(step) }
+        return @nothing_to_do = true if pending.empty?
+
+        pending.each do |step|
+          migration_template(step[:template], "db/migrate/#{step[:destination]}")
+        end
+
+        @emitted = pending
+      end
+
+      def report_next_step
+        return if @halted
+
+        say(@nothing_to_do ? up_to_date_message : pending_message)
+      end
+
+      private
+
+      def up_to_date_message
+        <<~CURRENT
+
+          #{TABLE} is already at audit-entry contract #{STEPS.last[:contract]}. Nothing to do.
+        CURRENT
+      end
+
+      def pending_message
+        <<~NEXT
+
+          #{@emitted.size} migration#{'s' if @emitted.size != 1} written, taking the ledger
+          to audit-entry contract #{@emitted.last[:contract]}. Run:
+
+            bin/rails db:migrate
+
+          Existing rows are stamped with the contract they were actually written under,
+          not with the current one.
+        NEXT
+      end
+
+      # Asked of the table rather than of a version the host recorded: the table is the
+      # thing being changed, and it is the only party that cannot be out of date about
+      # itself.
+      def applied?(step)
+        (step[:adds] - existing_columns).empty?
+      end
+
+      def existing_columns
+        @existing_columns ||= connection.columns(TABLE).map(&:name)
+      end
+
+      def table_exists?
+        connection.table_exists?(TABLE)
+      rescue StandardError
+        false
+      end
+
+      def connection
+        ActiveRecord::Base.connection
+      end
+    end
+  end
+end

data/lib/reeve/audit/isolated_recorder.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Audit
+    # The ledger row, written on a connection of its own.
+    #
+    # `Recorder` writes in a savepoint, which protects the trace from a transaction the
+    # *tool* opens and rolls back. It cannot protect the trace from a transaction the
+    # *host* opened around the whole invocation — a controller that wraps each request in
+    # one, a job runner, a test suite with transactional fixtures. A savepoint released
+    # into that transaction goes down with it, and the envelope has no way to learn
+    # otherwise: the write reported success, the invocation returned records, and no row
+    # survives to say so. Constitution II says every call leaves a trace; on one
+    # connection that is not achievable, only detectable, which is why `Recorder` warns.
+    #
+    # A second connection is the only thing that actually closes it. A transaction on
+    # connection A cannot roll back an INSERT committed on connection B, so the row lands
+    # whatever the host's transaction does next.
+    #
+    #   config.audit_recorder = Reeve::Audit::IsolatedRecorder
+    #
+    # == Why this is not the default
+    #
+    # It cannot be. On SQLite the host's open transaction holds the database write lock,
+    # so the second connection blocks until it times out and every guarded call fails —
+    # the isolation is not merely unavailable there, it is actively worse than the
+    # savepoint. Rather than degrade quietly on the database most hosts develop against,
+    # this refuses to run on SQLite and says why. `Recorder` remains the default, and a
+    # host that needs durability under a wrapping transaction opts in on a database where
+    # opting in means something.
+    #
+    # It also costs a connection per pool, and moves the ledger write outside the host's
+    # transaction in both directions: the row survives a rollback, which is the point,
+    # and it also survives a rollback of an invocation the host *meant* to undo entirely.
+    # A ledger of what was attempted is the intended reading of Constitution II, but it is
+    # a choice, and it should be made rather than inherited.
+    class IsolatedRecorder < Recorder
+      UNSUPPORTED_ADAPTERS = %w[sqlite sqlite3].freeze
+
+      class << self
+        def record(attributes)
+          new.record(attributes)
+        end
+
+        # True when a second connection can actually be used here. Lets a host branch in
+        # an initializer — SQLite in development, PostgreSQL in production — rather than
+        # discovering the answer on the first guarded call.
+        def available?
+          verify_supported!
+          true
+        rescue Reeve::Error
+          false
+        end
+
+        def verify_supported!
+          adapter = IsolatedEntry.adapter_name
+          return unless UNSUPPORTED_ADAPTERS.include?(adapter.to_s.downcase)
+
+          raise ConfigurationError,
+                "Reeve::Audit::IsolatedRecorder cannot be used on #{adapter}: an open " \
+                "transaction holds the database write lock, so a second connection " \
+                "blocks until it times out and every guarded call fails. Use " \
+                "Reeve::Audit::Recorder here — it warns when a host transaction is " \
+                "wrapped around an invocation — and configure this recorder only where " \
+                "the database supports concurrent writers."
+        end
+      end
+
+      def initialize(config: nil)
+        super(entry_class: IsolatedEntry, config: config)
+      end
+
+      # Checked out and returned around each write rather than held: the pool exists to
+      # keep the ledger off the host's connection, not to keep a connection per thread
+      # alive for the life of the process.
+      def record(attributes)
+        self.class.verify_supported!
+        IsolatedEntry.connection_pool.with_connection { super }
+      end
+
+      private
+
+      # The savepoint `Recorder` uses is what makes the trace survive the *tool's* own
+      # rollback, and that is still worth having here: this connection is not in a
+      # transaction the host controls, but the tool body may have opened one on the main
+      # connection, and a single INSERT wants the same all-or-nothing treatment either
+      # way. Nothing about it is inherited from the host's transaction.
+      #
+      # The warning the parent emits is correctly silent here: it asks whether *this*
+      # connection has a transaction open, and this one never does.
+      def enclosing_transaction?
+        false
+      end
+    end
+
+    # The same table and the same rules, on a pool of its own.
+    #
+    # A subclass rather than a second model so that validations, readonly-once-persisted
+    # and the destroy guard are defined in exactly one place. The table has no
+    # inheritance column, so ActiveRecord adds no type condition and this reads and writes
+    # the same rows `Entry` does.
+    class IsolatedEntry < Entry
+      class << self
+        def adapter_name
+          establish_own_connection!
+          connection_pool.db_config.adapter
+        rescue StandardError => e
+          raise Error, "could not reach the audit ledger on its own connection: " \
+                       "#{e.class}: #{e.message}"
+        end
+
+        def connection_pool
+          establish_own_connection!
+          super
+        end
+
+        private
+
+        # Idempotent, and deliberately lazy: a Rails initializer naming this recorder runs
+        # before the database is necessarily reachable, so the pool is built on first use
+        # rather than at configure time.
+        def establish_own_connection!
+          return if @own_connection
+
+          establish_connection(::ActiveRecord::Base.connection_db_config)
+          @own_connection = true
+        end
+      end
+    end
+  end
+end

data/lib/reeve/audit/recorder.rb

@@ -26,10 +26,14 @@ module Reeve
     # A genuinely independent write needs a second connection, and that is not portable:
     # on SQLite the enclosing transaction holds the write lock, so a second connection
     # blocks until it times out. Rather than fail every call on the databases where
-    # isolation is impossible, the recorder detects the enclosing transaction and warns
-    # that the guarantee is suspended for that call. A host that needs durability under a
-    # wrapping transaction supplies its own `audit_recorder` — writing to a separate
-    # connection, a queue, or an append-only log — which is what that setting is for.
+    # isolation is impossible, this recorder detects the enclosing transaction and warns
+    # that the guarantee is suspended for that call.
+    #
+    # `Reeve::Audit::IsolatedRecorder` is the answer where the database has concurrent
+    # writers: same rows, same redaction, on a pool of its own, so a rollback on the
+    # host's connection cannot reach it. It is opt-in rather than the default precisely
+    # because it cannot work everywhere this one does. A host with a different answer
+    # again — a queue, an append-only log — still supplies its own `audit_recorder`.
     #
     # The other known limit, unchanged: on a single connection there is a narrow window
     # where the tool's data commits and the ledger write then fails. The caller learns by
@@ -161,8 +165,9 @@ module Reeve
 
         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. Configure Reeve.config.audit_recorder with a recorder that writes " \
-                  "outside this transaction if the trace must survive."
+                  "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)
       end

data/lib/reeve/audit.rb

@@ -92,6 +92,7 @@ end
 require_relative "audit/redactor"
 require_relative "audit/entry"
 require_relative "audit/recorder"
+require_relative "audit/isolated_recorder"
 require_relative "audit/query"
 
 Reeve::Audit.install!

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/contract_version.rb

@@ -79,10 +79,14 @@ module Reeve
           )
         end
 
+        # Names the generator that actually fixes this. It used to say `reeve:install`,
+        # which is wrong for the case this failure describes: the table exists, so Rails
+        # resolves that migration by name and either emits nothing or offers to overwrite
+        # one that has already run.
         def missing_columns(missing)
           failed(
             "expected the ledger to implement audit-entry contract version #{@expected}, " \
-            "but #{TABLE} is missing: #{missing.join(', ')} — run `rails g reeve:install` " \
+            "but #{TABLE} is missing: #{missing.join(', ')} — run `rails g reeve:upgrade` " \
             "and migrate",
             version: @expected, missing: missing
           )

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.2.0"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: reeve
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Victor Velazquez
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-12 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)
@@ -30,9 +30,12 @@ files:
 - lib/generators/reeve/install/install_generator.rb
 - lib/generators/reeve/install/templates/create_audit_entries.rb.tt
 - lib/generators/reeve/install/templates/initializer.rb.tt
+- lib/generators/reeve/upgrade/templates/add_contract_version_to_reeve_audit_entries.rb.tt
+- lib/generators/reeve/upgrade/upgrade_generator.rb
 - lib/reeve.rb
 - lib/reeve/audit.rb
 - lib/reeve/audit/entry.rb
+- lib/reeve/audit/isolated_recorder.rb
 - lib/reeve/audit/query.rb
 - lib/reeve/audit/recorder.rb
 - lib/reeve/audit/redactor.rb