reeve 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bea7ce4962daf51d8ac269ab8fa8d95198d3dd0ab22fe534c2ddd0a0f79a8981
-  data.tar.gz: 8000630e05686b6d1a29c81e5b007f7a1b46f586aca9688870465c1b8b8d1d3a
+  metadata.gz: aaf976c70abfbb4d56236acface7e1ef95a4e8c177452e4ef918ca22f45933d0
+  data.tar.gz: 9076bbad0582db6c4cda3c38dc89f97840dc3a7e2dbb99ca98a16c5b642ece57
 SHA512:
-  metadata.gz: 40886bd0fa070325c4e52eb41a9aa87e4f8cda355d71d68993641b62201aadd37243ce8988f0b9831d2aa33ef80a219d663a2c8b78cd4bd317dca411bbc70c48
-  data.tar.gz: b12725979b28ffa95cbd6838c9e6f1faadc47675894bd1d824c99632f7b0c715441b8c690eabd8f9d8873139a8be97b9cfa75eba22e97b0fa0a254287003f65b
+  metadata.gz: 7957d35a7e9df67acaa1c6babcd18b1d2340ffd63595fc88a11e16bd5c81cfa78ddb6b6cf17742f74b1f300d5e35058442d124fe77d6cc7051005e3ed4d5b837
+  data.tar.gz: 543bb727d1abf718053d21a72fe3d3eb62b9e82ebe5a3658046b7d80eb8c897c91e76da7d6c55842f1ee0545b76af94a2d1127ffa2fc814a88bbadab3c827a01

data/CHANGELOG.md

@@ -4,6 +4,85 @@ 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.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.2.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.
 
@@ -219,6 +219,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/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/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/recorder.rb

@@ -89,7 +89,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 +119,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.

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"
 

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)

data/lib/reeve/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Reeve
-  VERSION = "0.1.0"
+  VERSION = "0.2.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.2.0
 platform: ruby
 authors:
 - Victor Velazquez
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-11 00:00:00.000000000 Z
+date: 2026-08-12 00:00:00.000000000 Z
 dependencies: []
 description: |
   Reeve makes it safe for a Rails application to expose MCP (Model Context Protocol)