reeve 0.0.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c59f8e6c82441798415dbe8c2a0f53820615dfe8fcce4d96294ccc46d355208
-  data.tar.gz: 670b19c4de2bc2fab5c16b4fbb7c958b3ea64cede00615f219032ef27161626f
+  metadata.gz: aaf976c70abfbb4d56236acface7e1ef95a4e8c177452e4ef918ca22f45933d0
+  data.tar.gz: 9076bbad0582db6c4cda3c38dc89f97840dc3a7e2dbb99ca98a16c5b642ece57
 SHA512:
-  metadata.gz: 148721a9d10024026ff713a59ddf0fdf6cb1c32691f4c78c79961337a654f08c8f08b3445ba8a4630c00ce563553352c59194cc7355f00eae50942cf0f61cae0
-  data.tar.gz: 6b2b69206f97d2ca3278a3ccb37ba63a4ab74447a39de01f6e0c5ebe1c53aff5958a4c2389fafa0d55ae192bdd4035ed1df9d224e8fa49c7c4e52064bcdbe887
+  metadata.gz: 7957d35a7e9df67acaa1c6babcd18b1d2340ffd63595fc88a11e16bd5c81cfa78ddb6b6cf17742f74b1f300d5e35058442d124fe77d6cc7051005e3ed4d5b837
+  data.tar.gz: 543bb727d1abf718053d21a72fe3d3eb62b9e82ebe5a3658046b7d80eb8c897c91e76da7d6c55842f1ee0545b76af94a2d1127ffa2fc814a88bbadab3c827a01

data/CHANGELOG.md

@@ -1,5 +1,196 @@
 # Changelog
 
+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.
+
+### Added
+
+**Authorization**
+
+- `guard_with SomePolicy` declares the policy governing a tool. A tool without one is
+  denied (`no_guard_declared`) unless the host opts into `unguarded_tools =
+  :allow_with_warning`, which runs the tool unscoped and records `guard: "none"`.
+- `redact :argument_name` keeps an argument's value out of the ledger while keeping its
+  name.
+- `scoped(Model)` returns the policy-scoped relation inside a tool body. It is how a
+  guarded tool returns anything that is not a record: a count or a summary computed from
+  `scoped(...)` is safe because the tool never held unscoped data. A derived value
+  returned without it is denied (`unscoped_derived_result`).
+- Policy adapters for plain objects and for Pundit, behind one two-method protocol
+  (`authorize`, `scope`). `:auto` picks one and reports which through
+  `Reeve.config.resolved_policy_adapter`. Neither Pundit nor any authorization library is
+  a runtime dependency.
+- Per-record scoping for relations, arrays, single records, mixed types and derived
+  values. A single record outside the principal's scope is refused without naming it.
+
+**Audit**
+
+- One append-only `reeve_audit_entries` row per invocation, allowed or denied, recording
+  the agent, the principal, the tool, post-redaction arguments, returned identifiers, the
+  outcome, the rule that decided, and why it decided (`detail`).
+- The write happens in its own transaction, so a tool that raises and rolls back its own
+  work still leaves a trace — the invocations most worth recording are the ones that
+  failed.
+- A failed ledger write fails the invocation. `audit_failure_mode = :warn` degrades that
+  deliberately and must be opted into.
+- `Reeve::Audit::Query` queries the ledger by principal, agent, tool, outcome and time
+  range.
+- Entries are read-only after insert and refuse to be destroyed; the generated migration
+  documents the `GRANT INSERT, SELECT` that enforces what a library cannot.
+
+**Testing kit**
+
+- Seven framework-neutral checks (`CrossPrincipalLeak`, `AuditCoverage`, `GuardDeclared`,
+  `RulePresent`, `RedactionHolds`, `PrincipalRequired`, `ContractVersion`) plus
+  `Checks.run_all`, all plain Ruby that loads no test framework.
+- RSpec front-end (`require "reeve/rspec"`): `deny_access_for`, `audit_every_call`,
+  `pass_reeve_check`, and the `"a reeve-compliant server"` shared example group.
+- Minitest front-end (`require "reeve/minitest"`): the same guarantees from a stock
+  `rails new` application, with no RSpec installed.
+- Failure messages are built by the checks, so all three front-ends emit identical text.
+
+**Adoption**
+
+- `rails generate reeve:install` writes the initializer and the ledger migration.
+  `principal_resolver` ships as a TODO, because it is the one thing only the host can
+  answer, and reeve denies every call until it is filled in.
+- fast-mcp adapter (`require "reeve/fast_mcp"`): the DSL on every tool and the envelope
+  around every call, with the principal resolved from the request's headers. Needs Ruby
+  3.1+, because fast-mcp does.
+- `Reeve.invoke` gives the same guarantees with no Rails, no ActiveRecord and no MCP
+  server library.
+
+### Known limitations
+
+Stated here because finding them yourself later is worse than reading them now.
+
+- **A transaction the host wraps around an invocation takes the ledger row with it.** The
+  recorder writes in a savepoint, which protects the trace from a transaction the *tool*
+  opens and rolls back, but not from one already open around the whole call — a controller
+  that wraps each request, or a test suite using transactional fixtures. Reeve detects this
+  and warns, naming the invocation. Real isolation needs a second connection and is not
+  portable: on SQLite the enclosing transaction holds the write lock and a second
+  connection times out. Hosts needing durability there supply their own `audit_recorder`.
+- **An unscoped fetch by id still discloses existence.** `Invoice.find_by(id:)` denies for
+  a record that exists but belongs to someone else, and returns `nil` for one that does not
+  exist. Fetching through `scoped(...)` makes both answers `nil`.
+- **A scope-less type must be tied to its policy.** A plain object with an `id` is a
+  record, but a type with no relation cannot be checked against a policy scope — only
+  against `authorize`, which is often permissive. Such a type is trusted when a policy is
+  named for it or a `scoped(...)` call establishes provenance, and denied otherwise.
+- **A call that cannot be recorded fails, even when it was already failing.** An
+  unrecordable denial raises `AuditWriteError` carrying the denial as `#during`, rather
+  than the denial itself. With no recorder configured at all, that is the first thing you
+  will see, and it names the missing ledger.
+- **`AuditCoverage` proves one invocation is recorded**, not every invocation.
+- **The fast-mcp adapter needs Ruby 3.1+**, because fast-mcp depends on dry-schema. The
+  core supports 3.0.
+- CI runs SQLite only; MySQL and PostgreSQL rest on ActiveRecord's portability.
+
+### Notes
+
+- Ruby 3.0+, Rails 7.0+, zero runtime dependencies.
+- Publishing requires MFA on the owner's account (`rubygems_mfa_required`).
+
 ## [0.0.1] - 2026-08-11
 
 - Placeholder release reserving the gem name. No functionality.
+
+## Versioning policy
+
+Semantic versioning, with one project-specific rule that follows from what this library
+is for:
+
+- **A change that narrows what a tool returns is a security fix and may ship in a patch.**
+  If reeve was letting a record through that a policy did not permit, closing that is not
+  a breaking change, however much it changes behaviour for someone relying on it.
+- **A change that widens access is breaking by definition** — major version, plus a
+  migration note saying exactly what became visible that was not visible before.
+- Adding a nullable ledger column is minor and leaves the audit-entry contract version
+  alone. Removing or renaming a column, or changing what a value means, is major and bumps
+  it.
+- The audit-entry contract version is `1`.

data/README.md

@@ -7,8 +7,9 @@ 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.0.1 is a placeholder release reserving the gem name. There is no working
-> code yet.** Development is in progress — don't install this expecting it to do anything.
+> **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.
 
 *A reeve is an official who acts with delegated authority on behalf of someone else — the
 root of "sheriff" (shire-reeve). That delegation is exactly what this gem governs: an agent
@@ -27,11 +28,38 @@ in CI.
 
 That's the gap Reeve fills. It's an extension layer, not a competitor — it rides all three.
 
-## The shape of it
+## Three steps
+
+```bash
+bundle add reeve
+bin/rails generate reeve:install
+bin/rails db:migrate
+```
+
+**1. Say who the agent is acting for.** This is the only thing Reeve cannot work out for
+itself, and the generated initializer leaves it as a TODO:
+
+```ruby
+# config/initializers/reeve.rb
+Reeve.configure do |config|
+  config.principal_resolver = lambda do |context|
+    ApiToken.find_by(token: context.metadata.dig(:headers, "Authorization"))&.user
+  end
+
+  config.unguarded_tools  = :deny        # :deny | :allow_with_warning
+  config.redact_arguments = %i[password token ssn]
+end
+```
+
+Until that resolver is set, every guarded call denies with `no_principal`. That is the
+intended behaviour: the library is safe before it is configured.
+
+**2. Guard a tool.**
 
 ```ruby
 class InvoiceSearchTool < FastMcp::Tool
   guard_with InvoicePolicy          # the only line you add
+  redact :customer_ssn
 
   def call(query:)
     Invoice.where("number LIKE ?", "%#{query}%")
@@ -39,24 +67,259 @@ class InvoiceSearchTool < FastMcp::Tool
 end
 ```
 
-Three things then hold:
+**3. Prove it in CI.**
+
+```ruby
+RSpec.describe InvoiceSearchTool do
+  it { is_expected.to deny_access_for(stranger).with(query: "AC") }
+  it { is_expected.to audit_every_call }
+end
+```
+
+Three things now hold, and each is a test you can run rather than a claim you have to
+trust.
+
+## Deny by default
+
+A tool returns only the records its principal may see. No principal, no `guard_with`, or a
+policy that raises means no records — never a silent pass. A single record outside the
+principal's scope is refused in a way that does not reveal whether it exists:
+
+```ruby
+Reeve.invoke(tool: InvoiceShowTool, arguments: { id: 41 }, principal: alice)
+# => Reeve::DeniedError: reeve denied invoice_show_tool for principal 1:
+#    out_of_scope_record (the requested record is not within this principal's scope)
+```
+
+The error names the rule and never names the record. One caveat worth knowing: fetching
+from the unscoped model still lets a caller tell "someone else's" (a denial) from "no such
+record" (`nil`). If that distinction matters, fetch through `scoped`, where both answers
+are `nil`:
+
+```ruby
+def call(id:)
+  scoped(Invoice).find_by(id: id)
+end
+```
+
+Anything that is not a record — a count, a sum, a summary — is safe only when it was
+computed from `scoped`, because then the tool never held unscoped data:
+
+```ruby
+class OverdueTotalTool
+  include Reeve::Guard
+  guard_with InvoicePolicy
+
+  def call
+    scoped(Invoice).where(overdue: true).sum(:cents)   # safe by construction
+  end
+end
+```
+
+Reaching for `Invoice.sum(:cents)` there is denied with `unscoped_derived_result`. The
+guarantee is structural, not a matter of remembering.
+
+## Every call leaves a trace
+
+One append-only row per invocation, allowed or denied, naming the agent, the principal, the
+arguments (post-redaction), what came back, and the rule that decided:
+
+```ruby
+Reeve::Audit::Query
+  .for_principal(user)
+  .for_agent("claude-desktop")
+  .between(1.week.ago, Time.current)
+  .pluck(:occurred_at, :tool_name, :outcome, :rule, :record_type, :record_ids)
+```
+
+A call whose tool raised is still recorded — that trace is the one most worth having. A
+call that cannot be recorded fails, unless the host has explicitly opted into
+`audit_failure_mode = :warn`.
+
+## Provable in CI, in whichever framework you already use
+
+All the logic lives in framework-neutral checks. RSpec and Minitest are thin front-ends
+over the same objects, emitting the same messages, so no guarantee is provable in one
+framework only.
+
+```ruby
+# RSpec — require "reeve/rspec"
+it { is_expected.to deny_access_for(stranger) }
+it_behaves_like "a reeve-compliant server"
+```
+
+```ruby
+# Minitest — require "reeve/minitest"
+class ComplianceTest < ActiveSupport::TestCase
+  include Reeve::Testing::Assertions
+  include Reeve::Testing::ComplianceAssertions
+
+  def test_search_denies_a_stranger
+    assert_denies_access_for InvoiceSearchTool, stranger, query: "AC"
+  end
+end
+```
+
+A stock `rails new` application — Minitest, no RSpec — proves every guarantee without
+adding a test framework. That is a spec in this repo, not an aspiration.
+
+### Without a test framework at all
+
+The checks are plain objects, so the same guarantees are assertable from a rake task, a CI
+script, or a boot-time assertion in staging:
+
+<!-- reeve:compliance-gate -->
+```ruby
+require "reeve/testing"
+
+report = Reeve::Checks.run_all(principals: [alice, bob])
+abort report.to_s unless report.passed?
+```
+
+`alice` and `bob` are two fixture principals with disjoint records — that disjointness is
+what makes a shared record identifier proof of a leak. As a Rails rake task:
+
+```ruby
+# lib/tasks/reeve.rake
+namespace :reeve do
+  desc "Fail the build if any guarded tool leaks or goes unaudited"
+  task compliance: :environment do
+    require "reeve/testing"
+
+    report = Reeve::Checks.run_all(principals: Reeve::Testing.compliance_principals)
+    abort report.to_s unless report.passed?
+    puts report
+  end
+end
+```
+
+A failing run names the check, the tool, and the records that leaked:
+
+```text
+reeve compliance: 13 checks, 12 passed, 1 failed
+
+FAIL CrossPrincipalLeak
+  expected InvoiceSearchTool to return no records belonging to another principal, but it
+  returned 3 records to User#1 that also belong to User#2: Invoice#7, Invoice#8,
+  Invoice#9 (guard: InvoicePolicy, decision: allow via InvoicePolicy#index)
+```
+
+## Without Rails, or without fast-mcp
+
+The core needs neither. `Reeve.invoke` is the same envelope with the same guarantees:
+
+```ruby
+require "reeve"
+
+Reeve.invoke(
+  tool: InvoiceSearchTool,
+  arguments: { query: "AC" },
+  principal: current_user,
+  agent: { id: "claude-desktop" }
+)
+```
+
+## 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.
 
-1. **Deny by default.** The tool returns only invoices the acting principal may see. No
-   principal, no guard, or a policy error means no records — never a silent pass.
-2. **Every call leaves a trace.** One append-only ledger row per invocation, allowed or
-   denied, naming the agent, the principal, the arguments, what came back, and the rule
-   that decided.
-3. **Provable in CI.** `expect(tool).to deny_access_for(stranger)` in RSpec,
-   `assert_denies_access_for` in Minitest, or the checks called directly from a rake task.
+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.
 
-## Planned for v1
+## What you have not gained
 
-- Per-record authorization bridging Pundit or plain policy objects
-- Append-only audit ledger with a query interface and an install generator
-- Testing kit: framework-neutral checks with RSpec, Minitest, and plain-Ruby front-ends
-- fast-mcp adapter, plus a plain interface for everyone else
+Rate limiting, prompt-injection defence, cost control, and connection authentication are
+out of scope. This library governs *what an authenticated agent may touch* and *what it
+touched*. Keep your existing auth.
 
-Ruby 3.0+, Rails 7.0+. No runtime dependencies.
+Ruby 3.0+, Rails 7.0+. No runtime dependencies. The fast-mcp adapter needs Ruby 3.1+,
+because fast-mcp does.
 
 ## License
 

data/lib/generators/reeve/install/install_generator.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Reeve
+  module Generators
+    # `bin/rails generate reeve:install` — step two of the three-step adoption path
+    # (Constitution VI). Writes an initializer and the ledger migration, and nothing else.
+    #
+    # The initializer deliberately ships with `principal_resolver` unset: it is the one
+    # thing only the host can answer, and a plausible-looking guess would be worse than a
+    # TODO, because the library fails closed until it is filled in.
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates the reeve initializer and the audit ledger migration."
+
+      def create_initializer
+        template "initializer.rb.tt", "config/initializers/reeve.rb"
+      end
+
+      def create_migration_file
+        migration_template(
+          "create_audit_entries.rb.tt",
+          "db/migrate/create_reeve_audit_entries.rb"
+        )
+      end
+
+      def report_next_step
+        say <<~NEXT
+
+          reeve is installed. Two things left:
+
+            1. Fill in `principal_resolver` in config/initializers/reeve.rb.
+               Until you do, every guarded call denies with `no_principal`.
+            2. Run `bin/rails db:migrate` to create the audit ledger.
+
+          Then add `guard_with SomePolicy` to a tool.
+        NEXT
+      end
+    end
+  end
+end

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

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+# The reeve audit ledger: one row per guarded tool invocation, allowed or denied.
+#
+# The table is yours. Reeve writes to it and reads from it, and exposes no API that
+# updates or deletes a row (FR-010). What the library can enforce, it enforces:
+# Reeve::Audit::Entry is readonly once persisted and aborts destroy. What it cannot
+# enforce, it does not pretend to — a database superuser or a raw `UPDATE` can still
+# rewrite history. If the ledger is a compliance artifact for you, close that gap in the
+# database, not in Ruby:
+#
+#   -- PostgreSQL, for the role your application connects as
+#   REVOKE ALL   ON reeve_audit_entries FROM app_role;
+#   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 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
+#     nullable column, which the audit-entry contract's versioning already permits.
+#
+# `invocation_id` is a UUID stored as a string rather than a native `uuid` column,
+# because reeve supports every database ActiveRecord does and only PostgreSQL has the
+# native type. The unique index on it is what makes "exactly one row per invocation"
+# a checkable property.
+class CreateReeveAuditEntries < ActiveRecord::Migration[7.0]
+  def change
+    create_table :reeve_audit_entries do |t|
+      t.string   :invocation_id,  null: false
+      t.datetime :occurred_at,    null: false
+
+      t.string   :agent_id,       null: false
+      t.string   :agent_name
+      t.string   :principal_type
+      t.string   :principal_id
+
+      t.string   :tool_name,      null: false
+      t.json     :arguments,      null: false
+
+      t.string   :outcome,        null: false
+      t.string   :rule,           null: false
+      # Diagnostic text explaining the rule ("policy raised ArgumentError: boom").
+      # Nullable and free-form: match on `rule`, read `detail`. Never names a record.
+      t.text     :detail
+
+      t.string   :record_type
+      t.json     :record_ids,     null: false
+      t.integer  :record_count,   null: false, default: 0
+      t.boolean  :truncated,      null: false, default: false
+      t.boolean  :derived,        null: false, default: false
+
+      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
+
+    # One index per query axis in FR-013: by principal, by tool, by agent, by outcome —
+    # each paired with occurred_at, since every one of those questions is asked over a
+    # time range.
+    add_index :reeve_audit_entries, %i[principal_type principal_id occurred_at],
+              name: "index_reeve_audit_entries_on_principal"
+    add_index :reeve_audit_entries, %i[tool_name occurred_at]
+    add_index :reeve_audit_entries, %i[agent_id occurred_at]
+    add_index :reeve_audit_entries, %i[outcome occurred_at]
+  end
+end