reeve 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aaf976c70abfbb4d56236acface7e1ef95a4e8c177452e4ef918ca22f45933d0
-  data.tar.gz: 9076bbad0582db6c4cda3c38dc89f97840dc3a7e2dbb99ca98a16c5b642ece57
+  metadata.gz: 225a220bbfd6168a26fdf67a816c8a580ca57ba996f97c7d1c9317755252d497
+  data.tar.gz: a5633fe99dedbc03796c82abf560eca68187fa783e5a9ceef1fb764b9a47d351
 SHA512:
-  metadata.gz: 7957d35a7e9df67acaa1c6babcd18b1d2340ffd63595fc88a11e16bd5c81cfa78ddb6b6cf17742f74b1f300d5e35058442d124fe77d6cc7051005e3ed4d5b837
-  data.tar.gz: 543bb727d1abf718053d21a72fe3d3eb62b9e82ebe5a3658046b7d80eb8c897c91e76da7d6c55842f1ee0545b76af94a2d1127ffa2fc814a88bbadab3c827a01
+  metadata.gz: c9bccface22cb54d935720a927dd5aff7c61582403f6d0aeada860be4f178d110d4ac94801a84d6a15993c0abad8a6b14ee0c1058311809ddf5575ddb57d1741
+  data.tar.gz: e43b1e0a1fb8900a45cb998997b45152ab726b21961c2b86ea5dea0cc0adb3e0f9e015cf7aed8cdcd6e39aa28d7e9c827ff85d11653b8aa5fab769844b1cdecb

data/CHANGELOG.md

@@ -4,6 +4,81 @@ 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.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.3.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.
 
@@ -136,6 +136,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

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

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: reeve
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Victor Velazquez
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-12 00:00:00.000000000 Z
+date: 2026-08-17 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