reeve 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 329fc869bdb15c7e60eb1923221aeccb1725821535c25186dafe77bda001cc44
-  data.tar.gz: 0f0781268bc7e90b1fad27a74bef611aa6aa65df3da37fb1351eb3f28524da15
+  metadata.gz: 03d0a3695140d0703272da744486caa3ab21530eddb0d48d275977e3b83047c0
+  data.tar.gz: aa8988dd9d7fc1dfb40b5c7a67f1f0a9f70d5ba72350b7669ba32afb2121f140
 SHA512:
-  metadata.gz: b5d6286339f5f034e76f74052e3d19f9560c55b45e9432e6583b50931ddf4425a1aa5bc5c0ea1200646a9085f972521a3d1e2c38d8cf654e8aa8004fa2be0e3f
-  data.tar.gz: 32c28f2c34294f7d2454b772a1fd7bd52af690c3bc6d46793e2ec23021c6c3bd5d0d4bc6ee5f04b990a36a5f8ada40e03677bd9efa5c2a099b08c6bcf4cac147
+  metadata.gz: 116dbf0359f8666ffa50cb70a9a85aa7a037d76390305b3315fc4ecc37233fe83a5faabb14103c0ae999ae69f5cc5fa020813cd7da3ade8ae86f837639604c98
+  data.tar.gz: 4ae861908807ec1bc3b3363442edda7cf6936d60d01e39b5aa03f6ae91cd7e0daad49ac8a154a53db277894c866cf9adfdb2e8776d99071b20d6d4704647f4b0

data/CHANGELOG.md

@@ -4,6 +4,181 @@ 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.6.0] - 2026-10-10
+
+The ledger has been append-only at the library level since 0.1.0: no API updates or deletes
+an entry, and the generated migration documents the grant that enforces the rest. Nothing
+*detected* a change made outside the library. A DBA, a stolen application credential or a
+well-meant data fix could edit, delete or reorder rows, and the ledger read exactly as
+before. Now every row is chained to the one before it with a keyed digest, and
+`bin/rails reeve:verify_ledger` reports every place the chain no longer holds.
+
+**Audit-entry contract `2` → `3`, and a migration is required.** The new columns are
+nullable, so the shape change is additive; the bump is MAJOR by the contract's own rule,
+because what an absence means changed. On a contract 1–2 row a NULL digest means "written
+before chaining"; on a contract-3 row it means the row was written unchained, which
+verification reports. Upgrading is three steps:
+
+```bash
+bin/rails generate reeve:upgrade
+bin/rails db:migrate
+```
+
+then add the line the generator prints to `config/initializers/reeve.rb`:
+
+```ruby
+config.ledger_key = Rails.application.key_generator.generate_key("reeve audit ledger", 32)
+```
+
+Existing rows are not touched. They are reported as "not covered" from then on, and are
+exactly as trustworthy as they were before.
+
+What this detects and what it does not are set out in the README, under "Tamper-evident,
+within stated limits". In short, it does **not** detect a change made by someone holding
+the key; the newest rows deleted by someone who also rewinds the chain record's head; the
+whole ledger deleted (reported as *no chain*, never as a pass); or anything about rows
+written before the upgrade. It detects; it does not prevent.
+
+Behaviour changes worth reading before upgrading:
+
+- **A ledger key is required.** Without one, every guarded call fails with
+  `Reeve::AuditWriteError` (cause `Reeve::LedgerKeyError`, naming the setting). Under
+  `audit_failure_mode = :warn` the call goes through and the row is written *unchained*, a
+  warning is logged on every such write, and verification reports the row.
+- **Rotating `secret_key_base` rotates the ledger key**, if you keep the generated line. Put
+  the old derived key in `config.retired_ledger_keys`, or entries it signed become
+  unverifiable — reported as such, never as tampered. A dedicated key avoids the coupling.
+- **Writes serialize on the chain record.** About 0.5 ms more per ledger write on SQLite and
+  about 1 ms on PostgreSQL. Under the default recorder inside a transaction the host opened,
+  the lock is held until that transaction ends; `IsolatedRecorder` holds it for one insert.
+- **Rails 7.0 with SQLite:** sqlite3 1.x waits for the write lock while holding Ruby's GVL,
+  so concurrent guarded calls in one process can fail closed after the busy timeout. Rails
+  7.1+ or a server database avoids it. The limit predates this release; the chain's longer
+  write makes it likelier.
+- **The compliance suites run one more check, `LedgerChain`.** It writes an entry of its own
+  and fails without a key, on a broken or unverifiable chain, or on unchained entries. It is
+  skipped, saying so, when there is no compliance tool to write with or no ledger loaded.
+  The test environment needs the key line too; the generated one works there unchanged.
+- **Breaking for custom recorders** that write to `Reeve::Audit::Entry`: rows must be written
+  through `Reeve::Audit::Chain#append!` (or `#append_unchained!` to keep running without a
+  key), or verification reports them as unchained.
+- **A table still at contract 2** now fails with `Reeve::ConfigurationError` naming
+  `reeve:upgrade`, instead of a column error from inside the write.
+- **Known limit, MySQL:** a number in a tool's arguments beyond double precision is stored
+  rounded by MySQL's `JSON` type, and its row then fails to verify. A false alarm, never a
+  false pass.
+- **During a rolling deploy**, servers still on 0.5.0 keep writing contract-2 rows. They
+  are counted as not covered, not reported as tampering.
+
+### Added
+
+- **The ledger chain** (`Reeve::Audit::Chain`). Every entry carries a sequence number, the
+  16-character fingerprint of the key that signed it, and an HMAC-SHA256 digest over its
+  canonical form and its predecessor's digest. The digest is computed over the values the
+  database stores — defaults, casts and JSON normalization included — so a row verifies
+  after a dump and restore with every primary key renumbered.
+- **`Reeve::Audit::Chain.verify`** (optionally with `keys:`, for an auditor's own copy of the
+  key) and **`bin/rails reeve:verify_ledger`**, registered by a Railtie that loads only when
+  Rails is present. Exit status `0` intact, `1` broken, `2` could not verify; `LIMIT=` caps
+  the breaks listed, never the totals; `FORMAT=json` writes every break. Every line that
+  says *intact* or *pass* states the covered range and the uncovered count beside it.
+  `Reeve::Tasks.verify_ledger` is the same check without Rake.
+- **`config.ledger_key`** and **`config.retired_ledger_keys`**, validated at assignment (32
+  bytes minimum) and shown only as fingerprints in `to_h`, `inspect`, logs and reports.
+- **`Checks::LedgerChain`**, in both compliance suites.
+- **`reeve:upgrade`**'s contract-3 step, which prints the initializer line, the rotation
+  warning and how to build the new index concurrently on a large PostgreSQL ledger. A step
+  now counts as applied only when its columns and its tables both exist.
+
+### Fixed
+
+- **A per-tool compliance check with no tools to check is skipped, not passed.** With no
+  tool registered, `compliance_tools` set to `[]`, or `tools: []`, `Reeve::Checks.run`
+  returned an empty `Report` — which reads as passed — so the RSpec shared group and
+  `ComplianceAssertions` showed all six per-tool checks green over zero tools. Each now
+  returns one skipped result, "no compliance tools to check, so GuardDeclared established
+  nothing — the registry is empty and no endpoint inventory routes a tool" (or `the run was
+  given tools: []`, or `compliance_tools is []`), shown as pending in RSpec and as a skip
+  in Minitest. Over an empty registry `run_all` used to report only the ledger-wide checks
+  (two in 0.5.0); it now also reports the six per-tool skips. Nothing that ran over at
+  least one tool changes.
+- **The framework-free gate fails when a check had nothing to check.** The README's
+  `abort report.to_s unless report.passed?` stayed green over zero tools, because a skip is
+  not a failure. The documented gate is now
+  `abort report.to_s if report.failed? || report.nothing_checked?`, using the new
+  `Report#nothing_checked?`. A skip for a missing inventory does not trip it.
+
+
+## [0.5.0] - 2026-10-01
+
+Reeve protects the tools routed through it, and only those. A server that registers its
+tools as names and handler blocks can send some through `Reeve.invoke` and run the rest
+directly — and the direct ones are not unguarded, they are invisible: no denial, no scope,
+no ledger row, and nothing that says so. The compliance suite could not see them either,
+because it walks tools reeve was told about. A green run certified the subset reeve
+happened to know, and read exactly like a green run over the whole endpoint.
+
+**The audit-entry contract is unchanged at `2`, so no migration is required.** One new
+`rule` value, `unbound_tool`, can appear — only for a host that dispatches through an
+inventory.
+
+Behaviour changes worth reading before upgrading:
+
+- Both compliance suites have one more check, `EndpointCoverage`. Until `config.inventory`
+  is set it is **skipped** — pending in RSpec, a skip in Minitest — with a message saying
+  the endpoint was not verified. Nothing that passed before fails.
+- A `Report` now counts and prints skipped results (`8 checks, 7 passed, 0 failed, 1
+  skipped`, followed by `SKIP EndpointCoverage` and its reason). `passed?` is unchanged: a
+  skip is not a failure.
+- A multi-line check message is now indented as one block under its `FAIL` heading.
+
+**On Rails 7.0, keep `json` below 3.0.** json 3.0 dropped the `quirks_mode:` keyword that
+ActiveSupport 7.0 still passes to `JSON.generate`, so the ledger cannot serialize a row.
+Under the default `audit_failure_mode = :fail`, reeve fails closed: every invocation raises
+`Reeve::AuditWriteError` rather than running unrecorded — nothing goes unaudited, and
+nothing runs. Under `:warn`, every call runs and none is recorded. The defect is ActiveSupport's, not
+reeve's, and no reeve version works around it; pin `gem "json", "< 3"` until the
+application is on a Rails that supports json 3. Reeve's own CI pins it on the Ruby 3.0
+job for the same reason.
+
+### Added
+
+- **`Reeve::Inventory`** — the host's registered tool names, which of them route through
+  reeve and to which class, and which are exempt and why. Every part takes a value or a
+  callable, so a Rails initializer can declare it without autoloading application
+  constants. No MCP library involved: a list of names is the whole protocol.
+
+  - `#report` classifies every registered name as protected and guarded, routed but
+    unguarded, bypassing reeve, or exempted — plus anything the inventory names that the
+    server does not register, which is usually a rename that left the real name unbound.
+    The output names tools, classes and exemption reasons, never an argument, a principal
+    or a record, so it is safe in a CI log.
+  - `#verify!` raises `Reeve::IncompleteInventoryError`, carrying the report, unless every
+    registered name is guarded or exempt. For boot, a deploy step, or CI.
+  - `#dispatch(name, ...) { handler }` is the dispatch boundary. A routed name runs through
+    `Reeve.invoke`, with the handler block as the body; an exempt name runs as written; any
+    other name is treated as a tool with no guard — refused with the new `unbound_tool`
+    rule under `unguarded_tools = :deny`, or run unscoped with `guard: "none"` under
+    `:allow_with_warning` — and recorded either way. A host that dispatches through it
+    cannot have a tool that bypasses reeve.
+  - An exemption needs a non-empty reason, and is listed in every report, complete or not.
+
+- **`config.inventory`**, and **`Checks::EndpointCoverage`**, which compares a compliance
+  run against it. Passes only when the inventory is complete and the run covered all of
+  it; fails when the run claimed the whole endpoint and a registered tool bypasses reeve
+  or reaches it unguarded; skipped when no inventory is declared, or when
+  `compliance_tools` or `tools:` narrowed the run, naming what was left out. The
+  incremental path stays open, and a subset can no longer pass for the endpoint.
+
+- **Skipped results.** `Testing::Result.skipped`, `Result#skipped?`, `Report#skips` and
+  `Report#skipped?`. Only `EndpointCoverage` produces one.
+
+### Changed
+
+- The compliance suites' default population includes every class the inventory routes to.
+  A registry of blocks has no reason to `include Reeve::Guard` anywhere, so a routed class
+  with no guard would otherwise never reach `GuardDeclared`.
+
 ## [0.4.0] - 2026-09-03
 
 Everything here came out of a second application integrating the gem — one that had put a
@@ -342,4 +517,4 @@ is for:
 - 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`.
+- The audit-entry contract version is `3`.

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.4.0.** Read the known limitations in
+> **Status: 0.6.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.
 
@@ -52,7 +52,10 @@ 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.
+intended behaviour: the library is safe before it is configured. The initializer also
+derives the key that chains the audit ledger from `secret_key_base`, so that works in
+every environment with nothing to set up — see [Tamper-evident, within stated
+limits](#tamper-evident-within-stated-limits).
 
 **2. Guard a tool.**
 
@@ -186,6 +189,108 @@ transaction holds the write lock; `IsolatedRecorder.available?` lets you branch
 develop on one and deploy on the other. The default recorder warns when it detects the
 case rather than failing silently.
 
+## Tamper-evident, within stated limits
+
+Every row Reeve writes is linked to the one before it by a keyed digest (HMAC-SHA256), with
+a key the database does not hold. Someone who can write to the ledger table but does not
+hold the key can still change it, but the change shows when the chain is checked:
+
+```bash
+bin/rails reeve:verify_ledger
+```
+
+```text
+reeve ledger: INTACT — sequences 1–48,211 verified (head at start: 48,211); 5,000 earlier entries not covered (5,000 when the chain started)
+```
+
+It exits `0` when the chain is intact, `1` when it is broken, and `2` when it could not
+verify (no chain, no key, or rows signed by a key it does not hold). Run it on a schedule
+and alert on anything but `0`. `LIMIT=` caps the breaks it lists, never the totals;
+`FORMAT=json` writes every break. The same answer from Ruby, or with an auditor's own copy
+of the key:
+
+```ruby
+result = Reeve::Audit::Chain.verify
+result.status   # => :intact, :broken, :unverifiable or :no_chain
+result.covered  # => 1..48211
+puts result     # the report above, with every break listed under it
+```
+
+In CI the compliance suite you already run includes `LedgerChain`, in both frameworks:
+it writes entries of its own and fails on a broken chain, a missing key, or entries that
+were not chained.
+
+**The key.** The generated initializer derives it from `secret_key_base`:
+
+```ruby
+config.ledger_key = Rails.application.key_generator.generate_key("reeve audit ledger", 32)
+```
+
+Rotating `secret_key_base` therefore rotates the ledger key. Keep the old one, or the
+entries it signed become *unverifiable* — reported as such, never as tampered:
+
+```ruby
+config.retired_ledger_keys = [old_key]   # verify with these; never sign with them
+```
+
+A dedicated key decouples the two: `config.ledger_key = Rails.application.credentials.reeve_ledger_key`.
+Keys must be at least 32 bytes and are only ever printed as 16-character fingerprints.
+Without a key, every guarded call fails closed; under `audit_failure_mode = :warn` it is
+recorded unchained instead, logged each time, and reported by verification.
+
+**Detected**, provided the key has not leaked:
+
+- a chained row whose recorded content was changed;
+- a chained row removed from anywhere before the newest one;
+- chained rows swapped, renumbered or moved, or a row inserted that Reeve did not write —
+  including one numbered past the head;
+- the newest rows removed while the chain record was left alone;
+- the chain record removed while chained rows remain.
+
+**Not detected** — stated plainly, because these are the limits of the guarantee:
+
+1. **A leaked key.** Anyone holding it can rewrite the chain from any point forward. By
+   default that is anyone holding `secret_key_base`.
+2. **The newest rows deleted by someone who also rewinds the chain record's head.** Only a
+   checkpoint held outside the database could catch that; Reeve does not ship one.
+3. **The whole ledger deleted, chain record included.** Reported as *no chain*, never as a
+   pass — but indistinguishable from a ledger that was never chained.
+4. **Rows written before you upgraded.** They are counted as "not covered" and are exactly
+   as trustworthy as they were before.
+
+And it prevents nothing: it detects a change after the fact. The `GRANT INSERT, SELECT` in
+the generated migration is what prevents one. The chain record needs `UPDATE` as well,
+which is why a role allowed to rewind it is limit 2.
+
+**What it costs.** About half a millisecond per ledger write on SQLite and about one on
+PostgreSQL. Every chained write locks the chain record, so writes serialize. Under the
+default recorder inside a transaction your application opened, that lock is held until the
+transaction ends, and every other guarded call waits behind it — up to the database's own
+lock wait: indefinitely on PostgreSQL (`lock_timeout` is 0 by default), 50 seconds on MySQL
+(`innodb_lock_wait_timeout`), and ActiveRecord's `timeout` on SQLite (5 seconds in a
+generated `database.yml`). `IsolatedRecorder` holds it for the length of one insert. On
+**Rails 7.0 with SQLite**, a thread waiting for SQLite's write lock holds Ruby's GVL
+(sqlite3 1.x), so concurrent guarded calls in one process can fail closed after the busy
+timeout. Rails 7.1+ or a server database avoids it.
+
+**Your own recorder.** A recorder that writes to Reeve's table chains its rows through the
+same door the built-in ones use, or verification reports them as unchained:
+
+```ruby
+Reeve::Audit::Chain.new(entry_class: Reeve::Audit::Entry).append!(row)
+```
+
+**Upgrading from 0.5.0:**
+
+```bash
+bin/rails generate reeve:upgrade
+bin/rails db:migrate
+```
+
+Then add the `config.ledger_key` line the generator prints. Existing rows are not touched;
+the next guarded call starts the chain. Servers still on 0.5.0 during a rolling deploy keep
+writing unchained rows, which are counted as not covered rather than reported as tampering.
+
 ## Provable in CI, in whichever framework you already use
 
 All the logic lives in framework-neutral checks. RSpec and Minitest are thin front-ends
@@ -223,11 +328,13 @@ script, or a boot-time assertion in staging:
 require "reeve/testing"
 
 report = Reeve::Checks.run_all(principals: [alice, bob])
-abort report.to_s unless report.passed?
+abort report.to_s if report.failed? || report.nothing_checked?
 ```
 
 `alice` and `bob` are two fixture principals with disjoint records — that disjointness is
-what makes a shared record identifier proof of a leak.
+what makes a shared record identifier proof of a leak. `passed?` only means nothing failed,
+so a run over no tools at all passes; `nothing_checked?` is what stops this gate when the
+registry is empty, since a script has no pending test to show it.
 
 **The suite walks every tool that included `Reeve::Guard`, not only the ones that declared
 a guard.** A tool that forgot `guard_with` is the one worth finding, and it is absent from
@@ -242,12 +349,10 @@ config.compliance_tools = -> { [InvoiceSearchTool, InvoiceShowTool] }
 ```
 
 Reeve can only see tools that reached it. If your MCP server dispatches tools Reeve has
-never been told about — a custom controller with its own registry — hand it the real
-inventory, or it will certify the subset it happens to know:
-
-```ruby
-Reeve::Checks.run_all(principals: [alice, bob], tools: McpToolRegistry.tool_classes)
-```
+never been told about — a custom controller with its own registry — declare the server's
+real inventory ([below](#every-tool-the-endpoint-dispatches)), or the run certifies the
+subset Reeve happens to know. Until you do, the suite says so: `EndpointCoverage` is
+reported as skipped, never as passed.
 
 As a Rails rake task:
 
@@ -259,7 +364,7 @@ namespace :reeve do
     require "reeve/testing"
 
     report = Reeve::Checks.run_all(principals: Reeve::Testing.compliance_principals)
-    abort report.to_s unless report.passed?
+    abort report.to_s if report.failed? || report.nothing_checked?
     puts report
   end
 end
@@ -380,6 +485,91 @@ Reeve::Checks.run_all(
 That is the whole integration: one call site, your auth untouched, and the same three
 guarantees the fast-mcp adapter gets.
 
+## Every tool the endpoint dispatches
+
+Reeve protects the tools routed through it, and only those. A server that registers tools
+as names and handler blocks can send some through `Reeve.invoke` and run the rest directly
+— and the direct ones are not unguarded, they are invisible: no denial, no scope, no ledger
+row, and nothing that says so. Deny-by-default cannot deny a call it never sees.
+
+`Reeve::Inventory` makes the server's own list of names the thing that gets checked:
+
+```ruby
+# config/initializers/reeve.rb
+McpInventory = Reeve::Inventory.new(
+  registered: -> { McpServer.tool_names },
+  routed: -> { { "search_invoices" => InvoiceSearchTool, "get_invoice" => InvoiceShowTool } },
+  exemptions: { "healthcheck" => { reason: "returns no application data" } }
+)
+
+Reeve.configure { |config| config.inventory = McpInventory }
+```
+
+Each part takes a value or a callable. Callables are read when asked, so the initializer
+neither autoloads application constants nor runs before the server has registered its
+tools.
+
+```text
+reeve inventory: 4 registered
+  2 protected and guarded
+  0 routed through reeve but unguarded
+  1 bypasses reeve
+  1 exempted
+coverage: incomplete
+
+BYPASS export_invoices
+  registered with the server but neither routed through reeve nor exempted — route it to
+  a guarded tool, or exempt it with a reason
+
+EXEMPT healthcheck
+  returns no application data
+```
+
+The report names tools, classes and exemption reasons — never an argument, a principal or
+a record — so it is safe to print in CI. An exemption without a reason is refused, and one
+with a reason is listed every time, complete or not.
+
+**Fail boot or CI on a gap:**
+
+```ruby
+McpInventory.verify!   # raises Reeve::IncompleteInventoryError, carrying the report
+```
+
+**Dispatch through it, and a bypass stops being possible:**
+
+```ruby
+def call_tool
+  name = params.dig(:params, :name)
+  arguments = params.dig(:params, :arguments).to_h.symbolize_keys
+
+  result = McpInventory.dispatch(name, arguments: arguments,
+                                       agent: { id: request.headers["X-MCP-Client"] }) do
+    McpServer.handlers.fetch(name).call(arguments)
+  end
+
+  render json: { jsonrpc: "2.0", id: params[:id], result: serialize(result) }
+rescue Reeve::DeniedError => e
+  render json: { jsonrpc: "2.0", id: params[:id],
+                 error: { code: -32_003, message: e.message } }
+end
+```
+
+- A **routed** name runs through `Reeve.invoke` under its class's guard, with the handler
+  block as the body. A registry of blocks needs one guarded class per tool to name its
+  policy, and nothing else — the block still does the work, and what it returns is scoped.
+  Handlers dispatched this way should not call `Reeve.invoke` themselves.
+- An **exempt** name runs the block as written.
+- **Any other name** is a tool with no guard, and `unguarded_tools` decides: refused with
+  `unbound_tool` under `:deny`, the default; run unscoped and recorded with `guard: "none"`
+  under `:allow_with_warning`. Recorded either way, so a name the inventory missed lands on
+  the same ledger worklist as an unguarded class.
+
+**In the compliance suite,** `EndpointCoverage` compares the run against the inventory. It
+passes only when every registered tool is guarded or exempt and the run covered all of
+them. It fails when the run claimed the whole endpoint and something bypasses Reeve. A run
+narrowed by `compliance_tools` is reported as a subset — skipped, naming what it left out —
+so a retrofit stays green without passing for complete coverage.
+
 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.
@@ -387,7 +577,7 @@ ActiveRecord unless they are not — a plain object with an `id` works.
 ## What you have not gained
 
 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
+out of scope, and the ledger's chain detects tampering rather than preventing it. 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. The fast-mcp adapter needs Ruby 3.1+,

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

@@ -13,12 +13,23 @@
 #   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;
+#   -- the chain record: its head moves on every write
+#   GRANT INSERT, SELECT, UPDATE ON reeve_audit_chains TO app_role;
+#   GRANT USAGE  ON SEQUENCE reeve_audit_chains_id_seq TO app_role;
+#
+# Every row is chained to the one before it with a keyed digest (audit-entry contract 3),
+# so a row changed, removed or reordered outside reeve is reported by
+# `bin/rails reeve:verify_ledger`. That is tamper-evidence, not tamper-proofing: it
+# detects a change after the fact and prevents nothing — the grant above is what
+# prevents. It does not detect a change made by someone holding the ledger key, nor the
+# newest rows being deleted by a role that can also rewind the head in
+# reeve_audit_chains; that role needs UPDATE there, which is why the chain table is
+# granted separately from the ledger.
 #
 # 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.
+#     pruning is your policy, run by a role that is allowed to delete. Deleting rows
+#     breaks the chain by design.
 #
 # `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
@@ -61,6 +72,13 @@ class CreateReeveAuditEntries < ActiveRecord::Migration[7.0]
       # 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
+
+      # The chain (contract 3). Nullable: a row written before the chain began has no
+      # honest value for these, and nothing is backfilled into an append-only table.
+      # `chain_key_id` is the key's fingerprint, never the key.
+      t.bigint   :chain_sequence
+      t.string   :chain_key_id,   limit: 16
+      t.string   :chain_digest,   limit: 64
     end
 
     add_index :reeve_audit_entries, :invocation_id, unique: true
@@ -73,5 +91,25 @@ class CreateReeveAuditEntries < ActiveRecord::Migration[7.0]
     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]
+
+    # One position, one row. NULLs are distinct, so unchained rows never collide; the
+    # index also orders the walk `reeve:verify_ledger` makes.
+    add_index :reeve_audit_entries, :chain_sequence, unique: true
+
+    # The chain record: one row. The genesis columns are written once, when the first
+    # chained entry is; the head moves with every chained write, in the same transaction
+    # as the row it points at.
+    create_table :reeve_audit_chains do |t|
+      t.string   :name,                      null: false
+      t.datetime :genesis_at,                null: false, precision: 6
+      t.bigint   :pre_chain_count,           null: false
+      t.bigint   :pre_chain_unchained_count, null: false
+      t.string   :genesis_key_id,            null: false, limit: 16
+      t.string   :genesis_digest,            null: false, limit: 64
+      t.bigint   :head_sequence,             null: false
+      t.string   :head_digest,               null: false, limit: 64
+    end
+
+    add_index :reeve_audit_chains, :name, unique: true
   end
 end

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

@@ -72,6 +72,26 @@ Reeve.configure do |config|
   #
   # Left unset, which resolves to Reeve::Audit::Recorder.
 
+  # ---------------------------------------------------------------------------
+  # The key that chains the audit ledger, so a row changed, removed or reordered
+  # outside reeve is reported by `bin/rails reeve:verify_ledger`. It must live
+  # outside the database: someone who can write the table but does not hold the
+  # key cannot forge the chain.
+  #
+  # Derived from secret_key_base, it works in every environment — test included —
+  # with no new secret to provision. Without a key, every guarded call fails
+  # closed (or, under audit_failure_mode :warn, is recorded unchained).
+  config.ledger_key = Rails.application.key_generator.generate_key("reeve audit ledger", 32)
+
+  # Rotating secret_key_base rotates this key too. Keep the old one here, or the
+  # entries it signed become unverifiable (reported as such, never as tampered):
+  #
+  #   config.retired_ledger_keys = [old_key]
+  #
+  # Or use a dedicated key, so secret_key_base can rotate on its own schedule:
+  #
+  #   config.ledger_key = Rails.application.credentials.reeve_ledger_key
+
   # 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_ledger_chain_to_reeve_audit_entries.rb.tt

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# Audit-entry contract 2 → 3. Generated by `bin/rails generate reeve:upgrade`.
+#
+# Chains every row reeve writes from here on to the one before it with a keyed digest, so a
+# row changed, removed or reordered outside reeve is reported by
+# `bin/rails reeve:verify_ledger`.
+#
+# Rows already in the table are not touched: there is no honest digest to give a row
+# nobody was there to sign, and nothing is backfilled into an append-only table. They are
+# reported as "not covered" from now on — exactly as trustworthy as they were before this
+# migration, and no more. The three columns are nullable for that reason.
+#
+# The chain needs a key, held outside the database. Add this to
+# config/initializers/reeve.rb, or every guarded call fails closed after you migrate:
+#
+#   config.ledger_key = Rails.application.key_generator.generate_key("reeve audit ledger", 32)
+#
+# The chain record's head moves on every write, so the role your application connects as
+# needs UPDATE on reeve_audit_chains (the ledger itself stays INSERT, SELECT):
+#
+#   GRANT INSERT, SELECT, UPDATE ON reeve_audit_chains TO app_role;
+#
+# A role holding that UPDATE can rewind the head, and a rewound head hides the deletion of
+# the newest rows. Tamper-evidence detects a change after the fact; the grants are what
+# prevent one.
+#
+# On a very large ledger, the unique index below scans the table once. On PostgreSQL that
+# scan blocks writes for its duration; to avoid it, add `disable_ddl_transaction!` to this
+# class and `algorithm: :concurrently` to the add_index call.
+class AddLedgerChainToReeveAuditEntries < ActiveRecord::Migration[7.0]
+  def change
+    add_column :reeve_audit_entries, :chain_sequence, :bigint
+    add_column :reeve_audit_entries, :chain_key_id,   :string, limit: 16
+    add_column :reeve_audit_entries, :chain_digest,   :string, limit: 64
+    add_index  :reeve_audit_entries, :chain_sequence, unique: true
+
+    create_table :reeve_audit_chains do |t|
+      t.string   :name,                      null: false
+      t.datetime :genesis_at,                null: false, precision: 6
+      t.bigint   :pre_chain_count,           null: false
+      t.bigint   :pre_chain_unchained_count, null: false
+      t.string   :genesis_key_id,            null: false, limit: 16
+      t.string   :genesis_digest,            null: false, limit: 64
+      t.bigint   :head_sequence,             null: false
+      t.string   :head_digest,               null: false, limit: 64
+    end
+
+    add_index :reeve_audit_chains, :name, unique: true
+  end
+end