reeve 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bea7ce4962daf51d8ac269ab8fa8d95198d3dd0ab22fe534c2ddd0a0f79a8981
-  data.tar.gz: 8000630e05686b6d1a29c81e5b007f7a1b46f586aca9688870465c1b8b8d1d3a
+  metadata.gz: 225a220bbfd6168a26fdf67a816c8a580ca57ba996f97c7d1c9317755252d497
+  data.tar.gz: a5633fe99dedbc03796c82abf560eca68187fa783e5a9ceef1fb764b9a47d351
 SHA512:
-  metadata.gz: 40886bd0fa070325c4e52eb41a9aa87e4f8cda355d71d68993641b62201aadd37243ce8988f0b9831d2aa33ef80a219d663a2c8b78cd4bd317dca411bbc70c48
-  data.tar.gz: b12725979b28ffa95cbd6838c9e6f1faadc47675894bd1d824c99632f7b0c715441b8c690eabd8f9d8873139a8be97b9cfa75eba22e97b0fa0a254287003f65b
+  metadata.gz: c9bccface22cb54d935720a927dd5aff7c61582403f6d0aeada860be4f178d110d4ac94801a84d6a15993c0abad8a6b14ee0c1058311809ddf5575ddb57d1741
+  data.tar.gz: e43b1e0a1fb8900a45cb998997b45152ab726b21961c2b86ea5dea0cc0adb3e0f9e015cf7aed8cdcd6e39aa28d7e9c827ff85d11653b8aa5fab769844b1cdecb

data/CHANGELOG.md

@@ -4,6 +4,160 @@ 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
+against its own test suite. The Pundit fix is the one that blocks adoption.
+
+**Audit-entry contract version: `1` → `2`.** Two changes, one bump.
+
+`metadata` was written NULL on every row through version 1 and now carries what the caller
+passed. Anything mapping version 1 rows could reasonably have read that column as always
+empty, and this project's own versioning rule calls a change in what a value means MAJOR —
+hence 0.2.0 rather than a patch.
+
+New non-null `contract_version` column, stamped on every row. Version 1 rows could not
+name their own shape, which is exactly what made the `metadata` change ambiguous to a
+reader: on a version 1 row a NULL `metadata` means "never recorded", on a version 2 row it
+means "the caller passed none". Stamping the row settles that at read time instead of
+requiring a reader to know when the writing gem was deployed, and it makes every future
+bump legible on the row. It also gives `Checks::ContractVersion` real teeth — a stale
+table now fails on the missing column even when a bump was purely semantic.
+
+**Upgrading from 0.1.0:**
+
+- Re-run `bin/rails generate reeve:install` and migrate, or add the column by hand:
+  `add_column :reeve_audit_entries, :contract_version, :integer, null: false, default: 1`
+  — `default: 1` is correct for existing rows, since that is the contract they were
+  written under. Drop the default afterwards if you prefer; the recorder always sets it.
+- A host pinning `Reeve::Checks::ContractVersion.new(expected: 1)` moves it to `2`.
+- **A custom `audit_recorder` that writes to `Reeve::Audit::Entry` must now set
+  `contract_version`.** The model rejects a row without it.
+
+### Added
+
+- README: **Wrapping your own JSON-RPC server** — the integration path for a Rails app
+  that already exposes `/mcp` from its own controller and tool registry. Covers mapping
+  JSON-RPC tool names to `Reeve.invoke`, passing request headers as `metadata`, resolving
+  the principal from `Current.user` or a bearer token while keeping the host's existing
+  authentication, adopting one tool at a time through `:allow_with_warning`, and pointing
+  the compliance checks at the host's own dispatcher. The recipe is executed by
+  `spec/reeve/integrations/custom_dispatcher_spec.rb` rather than only written down.
+  ([#5](https://github.com/vicmaster/reeve/issues/5))
+
+### Fixed
+
+- `metadata` passed to `Reeve.invoke` is written to the ledger. The column, the recorder
+  mapping and the contract check all existed, but `Context#to_h` did not carry the value,
+  so `metadata` was NULL on every call ever recorded — including the header hash the
+  fast-mcp adapter collects. It is redacted on the way in, by the same redactor and the
+  same declared names as the arguments, so `Authorization` does not land in the ledger.
+  This is the change behind the contract-version bump above.
+- `contracts/audit-entry.md` no longer claims the contract version is "recorded in the
+  initializer". It never was — which is what prompted the `contract_version` column above,
+  so that from contract 2 the claim is simply true.
+- The envelope-overhead spec compares the fastest call on each side rather than the mean
+  of two separately-timed windows. A single GC pause or scheduler preemption landing in
+  one window and not the other lands whole in the difference — 300ms over fifty runs is
+  6ms per call against a 5ms budget, from a busy machine rather than a regression. It
+  loses no sensitivity: a regression is paid on every call, so it slows the fastest trial
+  too. Verified both ways — an injected one-off stall moves the measurement from 6.65ms to
+  0.23ms, and 6ms added to every call still fails at 7.13ms.
+- The spec suite declares UTF-8 (`spec/spec_helper.rb`). The README-spec encoding bug was
+  one instance of five: eleven examples across `readme_spec`, `contract_version_spec`,
+  `migration_spec`, `install_generator_spec`, `framework_neutrality_spec`,
+  `isolation_spec` and `verification_spec` died on `invalid byte sequence` whenever a file
+  was run on its own, and passed in a full run only because some other file happened to
+  set the encoding first. Every spec file now passes in isolation, and the suite passes
+  under `LC_ALL=C`.
+- A Pundit policy that inherits its `Scope` from a base policy (`class LeadPolicy <
+  LeadBasePolicy`) is now recognised. Policy detection looked only at the policy's own
+  namespace, so the ordinary Pundit inheritance pattern was refused at declaration time
+  with `ConfigurationError`. Detection now walks the policy's ancestry, stopping before
+  `Object` so a top-level `Scope` constant still cannot make an unrelated class look
+  Pundit-shaped. ([#3](https://github.com/vicmaster/reeve/issues/3))
+- `lib/reeve.rb` no longer describes the kernel as unreleased work in progress. The note
+  belonged to the 0.0.1 name-claim release and contradicted 0.1.0 for anyone reading the
+  installed gem. ([#4](https://github.com/vicmaster/reeve/issues/4))
+- The README compliance specs read the file as UTF-8. Under a POSIX locale they read it
+  as US-ASCII and every example failed on the first em dash, so the guarantees they
+  exist to enforce were never actually checked.
+
 ## [0.1.0] - 2026-08-11
 
 First working release. The published 0.0.1 was a placeholder holding the gem name.

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.1.0, the first working release.** 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
@@ -219,6 +233,95 @@ Reeve.invoke(
 )
 ```
 
+## Wrapping your own JSON-RPC server
+
+Plenty of Rails apps expose `/mcp` from a controller they wrote themselves, with their own
+tool registry and their own bearer-token authentication. There is no adapter to install
+for that, and none is needed: `Reeve.invoke` is the adapter interface. An MCP integration
+is a function from a JSON-RPC request to one `Reeve.invoke` call.
+
+Keep the authentication you have. Reeve does not do connection auth (see [What you have
+not gained](#what-you-have-not-gained)) — the controller still decides whether the caller
+gets in the door, and Reeve decides what they may touch once inside.
+
+**Dispatch through the envelope.** Map the JSON-RPC tool name to the class, then call:
+
+```ruby
+# app/controllers/mcp_controller.rb
+def call_tool
+  tool = McpServer.registry.fetch(params.dig(:params, :name))
+
+  records = Reeve.invoke(
+    tool: tool,
+    arguments: params.dig(:params, :arguments).to_h.symbolize_keys,
+    agent: { id: request.headers["X-MCP-Client"] || "unknown" },
+    metadata: { headers: request.headers.to_h.slice(*AUDITED_HEADERS) }
+  )
+
+  render json: { jsonrpc: "2.0", id: params[:id], result: serialize(records) }
+rescue Reeve::DeniedError => e
+  render json: { jsonrpc: "2.0", id: params[:id],
+                 error: { code: -32_003, message: e.message } }
+end
+```
+
+Note what is *not* passed: `principal:`. Omit it and the resolver in your initializer runs,
+which is what you want when the controller has already set `Current.user` — one place
+decides who the principal is, and the ledger records the same answer the guard used.
+Passing `principal:` explicitly overrides the resolver for that call, which is useful in
+tests and in scripts.
+
+**`metadata:` is transport detail, and it is recorded.** It reaches the resolver as
+`context.metadata` and is written to the ledger's `metadata` column, so it is what a
+reviewer has to reconstruct *which request* a row came from. It goes through the same
+redactor as the arguments, so `Authorization` and friends are replaced by name — but pass
+the headers you would want in an audit rather than all of them.
+
+**Resolve the principal from whichever the controller established:**
+
+```ruby
+Reeve.configure do |config|
+  config.principal_resolver = lambda do |context|
+    Current.user || ApiToken.find_by(
+      token: context.metadata.dig(:headers, "Authorization").to_s.delete_prefix("Bearer ")
+    )&.user
+  end
+end
+```
+
+A resolver that returns nil — or raises — denies with `no_principal` and still writes a
+row. There is no configuration in which an unidentified caller reaches a tool.
+
+**Adopt one tool at a time.** A registry of thirty tools does not need thirty policies
+before any of this is worth turning on:
+
+```ruby
+config.unguarded_tools = :allow_with_warning   # migrating
+```
+
+Tools with `guard_with` are authorized and scoped normally. Tools without one still run —
+unscoped, which is the entire point of the warning — and are recorded with `guard: "none"`
+and rule `unguarded_tool`, so the ledger itself is your worklist:
+
+```ruby
+Reeve::Audit::Entry.where(guard: "none").distinct.pluck(:tool_name)
+```
+
+Flip to `:deny` when that comes back empty, and the mode stops being reachable by accident.
+
+The compliance checks work here too, and they take an `invoke:` argument precisely so they
+run against your dispatcher rather than a synthetic call:
+
+```ruby
+Reeve::Checks.run_all(
+  principals: [alice, bob],
+  invoke: ->(tool:, principal:, arguments:) { McpServer.dispatch(tool, principal, arguments) }
+)
+```
+
+That is the whole integration: one call site, your auth untouched, and the same three
+guarantees the fast-mcp adapter gets.
+
 Policies are plain objects unless you want Pundit (`authorize` and `scope`, two methods).
 The ledger is an ActiveRecord table unless you supply your own recorder. Records are
 ActiveRecord unless they are not — a plain object with an `id` works.

data/lib/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/create_audit_entries.rb.tt

@@ -14,7 +14,7 @@
 #   GRANT INSERT, SELECT ON reeve_audit_entries TO app_role;
 #   GRANT USAGE  ON SEQUENCE reeve_audit_entries_id_seq TO app_role;
 #
-# Also explicitly out of scope for v1, so you can plan around it:
+# Also explicitly out of scope for now, so you can plan around it:
 #   * no retention, rotation or archival — this table grows until you prune it, and
 #     pruning is your policy, run by a role that is allowed to delete;
 #   * no cryptographic chaining or tamper-evidence. If that lands later it arrives as a
@@ -53,6 +53,14 @@ class CreateReeveAuditEntries < ActiveRecord::Migration[7.0]
       t.string   :guard,          null: false
       t.integer  :duration_ms
       t.json     :metadata
+
+      # The audit-entry contract version this row was written under. A ledger outlives
+      # the gem version that wrote it, and a row that cannot name its own shape has to be
+      # interpreted by guesswork: contract 1 wrote `metadata` NULL whatever the caller
+      # passed, so on a version 1 row NULL means "never recorded" and on a version 2 row
+      # it means "the caller passed none". Stamping each row keeps an export readable
+      # across an upgrade instead of collapsing that distinction.
+      t.integer  :contract_version, null: false
     end
 
     add_index :reeve_audit_entries, :invocation_id, unique: true

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

@@ -16,7 +16,9 @@ module Reeve
       DENY  = "deny"
       OUTCOMES = [ALLOW, DENY].freeze
 
-      REQUIRED = %i[invocation_id occurred_at agent_id tool_name outcome rule guard].freeze
+      REQUIRED = %i[
+        invocation_id occurred_at agent_id tool_name outcome rule guard contract_version
+      ].freeze
 
       validates(*REQUIRED, presence: true)
       validates :invocation_id, uniqueness: true
@@ -24,8 +26,12 @@ module Reeve
 
       before_destroy { throw :abort }
 
-      # The contract version this table's shape implements (FR-015). Exposed on the model
-      # so an export can stamp the rows it carries.
+      # The contract version this build of the gem writes (FR-015).
+      #
+      # Class-level, and deliberately not the same question as `entry.contract_version`:
+      # this is what the gem implements *now*, while the column on each row is the shape
+      # that row was actually written under. They differ for every row written before an
+      # upgrade, which is the whole reason the column exists.
       def self.contract_version
         CONTRACT_VERSION
       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
@@ -89,7 +93,11 @@ module Reeve
           derived: attributes[:derived] ? true : false,
           guard: blank?(attributes[:guard]) ? "policy" : attributes[:guard].to_s,
           duration_ms: attributes[:duration_ms],
-          metadata: attributes[:metadata]
+          metadata: redact_metadata(attributes),
+          # Stamped from the constant rather than from the caller: the row records the
+          # shape the gem that wrote it implements, which is not something an adapter or
+          # a host is in a position to assert.
+          contract_version: CONTRACT_VERSION
         )
       end
 
@@ -115,6 +123,20 @@ module Reeve
         Redactor.for(attributes[:tool_name], config: config).call(attributes[:arguments])
       end
 
+      # Metadata is transport detail, and the transport is where the credentials are: the
+      # fast-mcp bridge puts the whole header hash in here, `Authorization` included. It
+      # goes through the same redactor as the arguments — which recurses into nested
+      # hashes and already knows `authorization`, `token` and friends by name — so
+      # recording metadata does not turn the ledger into a place bearer tokens accumulate.
+      # nil stays nil rather than becoming `{}`: a call that carried no metadata should
+      # not be indistinguishable from one whose metadata was emptied.
+      def redact_metadata(attributes)
+        metadata = attributes[:metadata]
+        return nil if metadata.nil? || metadata.empty?
+
+        Redactor.for(attributes[:tool_name], config: config).call(metadata)
+      end
+
       # FR-014: identifiers are capped, never silently dropped — the count stays true and
       # the row says it was truncated. The scoper caps first; this is the backstop that
       # makes the guarantee hold at the ledger regardless of who produced the list.
@@ -143,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

@@ -43,16 +43,25 @@ module Reeve
   #   table. Immutability is enforced at the library level; the generated migration
   #   documents the `GRANT INSERT, SELECT` that enforces the rest where it can actually be
   #   enforced, and the gem makes no stronger claim than that.
-  # * No retention, rotation or archival in v1 — the table is host-owned and the host's
+  # * No retention, rotation or archival yet — the table is host-owned and the host's
   #   existing policies apply.
-  # * No cryptographic chaining or tamper-evidence in v1. If that lands it arrives as a
+  # * No cryptographic chaining or tamper-evidence yet. If that lands it arrives as a
   #   nullable column, which the audit-entry contract's versioning already permits.
+  #
+  # ("yet" rather than "in v1": the gem version and the audit-entry contract version are
+  # different numbers that move independently, and writing v1 for one of them read as the
+  # other.)
   module Audit
     # The version of the audit-entry shape, as documented in
     # specs/001-guardrails-core/contracts/audit-entry.md (FR-015). Adding a nullable
     # column is a MINOR change and leaves this alone; removing or renaming a column, or
     # changing what a value means, is MAJOR and bumps it.
-    CONTRACT_VERSION = 1
+    #
+    # 2 — `metadata` carries the transport detail the caller passed. Through version 1 it
+    # was written NULL on every row regardless of what was passed, so anything mapping
+    # version 1 rows could reasonably have read the column as "always empty". The shape
+    # did not change; what a value means did.
+    CONTRACT_VERSION = 2
 
     TABLE_NAME = "reeve_audit_entries"
 
@@ -83,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/adapters/pundit.rb

@@ -22,15 +22,28 @@ module Reeve
           return false unless pundit_loaded?
           return false unless policy.is_a?(Class)
 
-          # `false` matters: const_defined? otherwise walks up to Object, where any
-          # top-level Scope constant would make an unrelated policy look Pundit-shaped.
-          policy.const_defined?(:Scope, false) &&
+          scope_defined?(policy) &&
             policy.public_instance_methods.any? { |method| method.to_s.end_with?("?") }
         end
 
+        # Pundit policies ordinarily inherit their Scope from a base policy
+        # (`class LeadPolicy < LeadBasePolicy`), so asking only the policy's own namespace
+        # rejected the common case. This walks the ancestry instead, stopping before
+        # Object — which is the whole reason the check was narrow to begin with: a
+        # top-level `Scope` constant must never make an unrelated class look
+        # Pundit-shaped. `policy::Scope` resolves along the same ancestry, so what
+        # `supports?` accepts is exactly what `scope` can later reach.
+        def self.scope_defined?(policy)
+          policy_ancestry(policy).any? { |ancestor| ancestor.const_defined?(:Scope, false) }
+        end
+
+        def self.policy_ancestry(policy)
+          policy.ancestors.take_while { |ancestor| ancestor != Object }
+        end
+
         def self.missing_methods(policy)
           return [] if supports?(policy)
-          return [:Scope] if policy.is_a?(Class) && !policy.const_defined?(:Scope, false)
+          return [:Scope] if policy.is_a?(Class) && !scope_defined?(policy)
 
           %i[query_method Scope]
         end

data/lib/reeve/context.rb

@@ -56,6 +56,12 @@ module Reeve
 
     # The audit-facing projection. The recorder adds the outcome, rule and records;
     # everything here is known before the tool runs.
+    #
+    # `metadata` belongs here even though nothing in the envelope reads it: the ledger has
+    # a column for it, the recorder maps it, and the contract check requires it — but this
+    # method used to omit it, so the column was written NULL on every call ever made. The
+    # transport detail a reviewer most wants after an incident (which request, which
+    # headers, which client) was accepted at the front door and dropped before the write.
     def to_h
       {
         invocation_id: invocation_id,
@@ -65,7 +71,8 @@ module Reeve
         agent_name: agent_name,
         principal_type: principal_type,
         principal_id: principal_id,
-        arguments: arguments
+        arguments: arguments,
+        metadata: metadata
       }
     end
 

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

@@ -11,20 +11,44 @@ module Reeve
       # upgraded the gem and skipped the migration has a ledger one shape behind, and every
       # other check in this kit would go on passing while columns quietly went unwritten.
       #
+      # What each half of this check is worth, stated plainly because it is easy to read
+      # more into the version number than it carries:
+      #
+      # * The **column list** is the real test. It is compared against the columns the
+      #   host's table actually has, and it is written out by hand rather than read back
+      #   off the model — a check that derives its expectation from the thing it is
+      #   checking checks nothing.
+      # * The **version number** is compared against what the ledger model reports, which
+      #   is this gem's own +Audit::CONTRACT_VERSION+ — so by default it compares the gem
+      #   to itself and can only pass. It earns its keep when a host passes `expected:` to
+      #   pin the version it built its exports against.
+      #
+      # Those two are not as separate as they look, and that is by design. A contract bump
+      # is defined as a change to the shape or to what a value means; every such bump also
+      # moves the `contract_version` column, which means the column list catches a stale
+      # table even when the bump was purely semantic. Contract 2 is the worked example: the
+      # change was `metadata`'s meaning, no existing column moved, and a host still on the
+      # contract 1 table fails here on a missing `contract_version` column rather than
+      # passing while writing rows nothing can interpret.
+      #
+      # The constant below is written out rather than read from +Audit+ for the same
+      # reason the column list is, and one more: the testing kit loads with no ledger and
+      # no ActiveRecord at all (spec/reeve/testing/isolation_spec.rb), so it cannot
+      # reference the audit module. Bumping the contract means editing both by hand, and
+      # spec/reeve/audit/contract_version_spec.rb fails if they drift.
+      #
       #   Reeve::Checks::ContractVersion.new.call
+      #   Reeve::Checks::ContractVersion.new(expected: 2).call   # pinned by the host
       class ContractVersion < Base
         TABLE = "reeve_audit_entries"
 
-        # Contract version 1, as documented in contracts/audit-entry.md. This list is
-        # deliberately written out rather than read back off the model: a check that
-        # derives its expectation from the thing it is checking checks nothing.
         COLUMNS = %w[
           invocation_id occurred_at agent_id agent_name principal_type principal_id
           tool_name arguments outcome rule detail record_type record_ids record_count
-          truncated derived guard duration_ms metadata
+          truncated derived guard duration_ms metadata contract_version
         ].freeze
 
-        EXPECTED_VERSION = 1
+        EXPECTED_VERSION = 2
 
         def initialize(tool: nil, expected: EXPECTED_VERSION, ledger: nil)
           super(tool: tool, ledger: ledger)
@@ -55,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.1.0"
+  VERSION = "0.3.0"
 end

data/lib/reeve.rb

@@ -12,7 +12,8 @@ require_relative "reeve/authorization"
 # Reeve — per-record authorization and an append-only audit ledger for the MCP tools
 # a Rails application exposes to AI agents.
 #
-# The published 0.0.1 is a placeholder release reserving the gem name; the kernel below
-# is unreleased work in progress. See https://github.com/vicmaster/reeve.
+# A tool declares the policy that governs it with `guard_with`; every invocation is
+# authorized, scoped to what the principal may see, and recorded. See
+# https://github.com/vicmaster/reeve.
 module Reeve
 end

metadata

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