reeve 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67bc82ca855e0385d021e54477cbcfcef697a1134d3c93e4fc073fea2ff3b748
-  data.tar.gz: 0c11093e604b6a056a23bec7ebd419620d4dd1780f93ff7e30fc8a08bdbd92d3
+  metadata.gz: 4a50e8fe479452d3b685dcd79b3022881c76567651444c6204e8db3d601b07c8
+  data.tar.gz: fe9974e2c035ce7c958f75d44a847d4b951f9cd828820aba9468310e2a143acd
 SHA512:
-  metadata.gz: 0524a6cd7376dc9cc8b7f2611d4a0a6a8b1fa81b6b5ff59ab662d3e5f5f313b4f47e7ad5b2d52d272da8bab1f1c19042ae937300beb382f57804f2fc72b77d3e
-  data.tar.gz: 4ead6c668edcde8b543c1e4ead9817e08015ecbf42adfbc34d44c5fa31426206284efb3ffdd88dad4cd983033be7708e256ac9cc2e5eb4758a6fc92f2ac14a19
+  metadata.gz: aa5ff3ffce5221ee1b8baa64461865842faed31d432a0977051f6f3ec8be1846474174d27e19037a1a6b6901af5c6329fd38ac390e2da3fc664f7dfe9b7214ee
+  data.tar.gz: d986d9bd16574387f5529e983e932c1e740068a9b4a833a7220cf03dee30b3e134a5fd101a0ee41d2091bf3fa6660cc7ac67d52d720039bc149e32e6ec1dd33a

data/CHANGELOG.md

@@ -4,6 +4,283 @@ 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.7.0] - 2026-10-23
+
+0.6.0 let a ledger be verified across a key rotation, provided the old key was kept as a
+retired key. It did not record the rotation itself: nothing in the ledger said which key had
+signed which stretch of it. So an entry whose key id was rewritten to a fingerprint nobody
+holds read as "signed by a key you don't have" (exit 2), not as tampering, and an operator
+who replaced the key without keeping the old one learned it only when verification later
+came back unverifiable. Now every key that signs the ledger opens a numbered **key epoch**,
+every new entry records its epoch inside its digest, and `bin/rails reeve:rotate_ledger_key`
+performs and checks a rotation.
+
+**Audit-entry contract `3` → `4`, and a migration is required.** One nullable column,
+`chain_epoch`, and one new table, `reeve_audit_chain_epochs`. The bump is MAJOR by the
+contract's own rule, for two reasons: `chain_digest` on a contract-4 entry covers the epoch,
+which a contract-3 digest does not, and a NULL epoch means "chained before key epochs" on a
+contract-3 entry where a chained contract-4 entry always has one. The rule's wording now
+states that exception instead of leaving it to precedent.
+
+### Upgrading from 0.6.0
+
+1. Update the gem, then generate and run the migration. Nothing in your initializer changes.
+
+   ```bash
+   bundle update reeve
+   bin/rails generate reeve:upgrade
+   bin/rails db:migrate
+   ```
+
+   Migrate before the new code serves traffic: until the table is migrated, every chained
+   write fails with a `Reeve::ConfigurationError` naming `reeve:upgrade`, so guarded calls fail
+   closed. (`bin/rails reeve:verify_ledger` keeps working on an unmigrated table and checks it
+   as 0.6.0 did.)
+
+2. Grant the application's database role `INSERT` and `SELECT` on the new table — never
+   `UPDATE`:
+
+   ```sql
+   GRANT INSERT, SELECT ON reeve_audit_chain_epochs TO app_role;
+   ```
+
+3. Deploy. The first chained write after the migration — normally the first guarded tool
+   call — opens epoch 0 with your configured `ledger_key`. Until then, verification shows no
+   epochs. Entries already in the ledger are not touched; verification lists them as "before
+   epoch 0" and checks them exactly as 0.6.0 did.
+
+Servers still running 0.6.0 during the deploy keep writing contract-3 entries. They are never
+reported as tampering: they verify wherever their key is configured, and are unverifiable
+where it is not, exactly as in 0.6.0.
+
+### Rotating the ledger key
+
+Do these in order. The old key stays configured throughout: it is what verifies the
+entries it signed, for as long as you keep it.
+
+1. Configure the new key as `ledger_key` and move the old one to `retired_ledger_keys`.
+   Assign `ledger_key` first — a key may not be both the signing key and a retired one,
+   even for the moment between the two lines:
+
+   ```ruby
+   config.ledger_key = Rails.application.credentials.reeve_ledger_key_2026
+   config.retired_ledger_keys = [Rails.application.credentials.reeve_ledger_key_2025]
+   ```
+
+   If your `ledger_key` is the one the generated initializer derives from
+   `secret_key_base`, rotating `secret_key_base` is this step, and the old derived key must be
+   captured *before* you change `secret_key_base`, while the app can still derive it:
+
+   ```bash
+   bin/rails runner 'puts [Rails.application.key_generator.generate_key("reeve audit ledger", 32)].pack("m0")'
+   ```
+
+   Store the printed value in credentials (say as `reeve_ledger_key_previous`), rotate
+   `secret_key_base`, and keep the derived line as it is:
+
+   ```ruby
+   config.ledger_key = Rails.application.key_generator.generate_key("reeve audit ledger", 32)
+   config.retired_ledger_keys = [Rails.application.credentials.reeve_ledger_key_previous.unpack1("m0")]
+   ```
+
+2. Deploy everywhere. From the first write a server makes with the new key, that key opens
+   the next epoch. Servers still on the old key during the deploy keep writing under the old
+   epoch; those entries verify. No write fails because a rotation is under way.
+
+3. Run the rotation task once the deploy has finished, on a host configured like your
+   servers (both keys):
+
+   ```bash
+   bin/rails reeve:rotate_ledger_key
+   ```
+
+   It prints one of three first lines and exits accordingly:
+
+   | First line | Exit | Meaning |
+   |---|---|---|
+   | `reeve ledger key: ROTATED — epoch N opened with key …` | 0 | The task opened the new epoch, starting one past the newest entry. |
+   | `reeve ledger key: CURRENT — epoch N already signs with the configured key …` | 0 | A write already opened it — the usual result on a ledger that was written to during the deploy — or you ran the task twice. Nothing written. |
+   | `reeve ledger key: REFUSED — …; nothing was written` | 1 | See below. Nothing written. |
+
+   It refuses when no `ledger_key` is configured; when the configured key already opened an
+   earlier epoch (a key opens one epoch, ever — configure a new one); and when the current
+   epoch's key is not configured on the host running the task, because that epoch's entries
+   would become unverifiable there. The last refusal names the fix: add the old key to
+   `retired_ledger_keys`. Only if that key is truly lost, run
+   `ACCEPT_UNVERIFIABLE=1 bin/rails reeve:rotate_ledger_key`: it reports ROTATED (exit 0) and
+   adds a line starting `warning: ` saying the earlier epoch is unverifiable on this host. The
+   same `warning: ` line on a CURRENT result means the same thing about the previous epoch.
+
+   Keys are never printed, only their 16-character fingerprints. The same result is
+   available from Ruby as a value: `Reeve::Audit::Chain.rotate_key!` returns a `Rotation`
+   with `status`, `reason`, `epoch`, `key_id`, `first_sequence`, `previous_epoch`,
+   `previous_key_id` and `warnings`.
+
+4. Verify:
+
+   ```bash
+   bin/rails reeve:verify_ledger
+   ```
+
+   With both keys configured it reports INTACT and, under the summary, one line per epoch
+   with its key fingerprint, the sequence it begins at, how many entries named it, and
+   `verified`. An epoch whose key is not configured where you run it is listed as
+   `key not configured`, and the run is UNVERIFIABLE (exit 2) — never INTACT.
+
+5. Keep the old key in `retired_ledger_keys` for as long as the entries it signed must
+   verify — in practice, for the life of the ledger. Removing it makes every run on that host
+   UNVERIFIABLE (exit 2) from then on; nothing re-signs those entries under a new key.
+
+Behaviour changes worth reading before upgrading:
+
+- **Entries name their epoch.** Every chained entry written at contract 4 records
+  `chain_epoch`. Query by it: `Reeve::Audit::Entry.where(contract_version: 4, chain_epoch: 1)`
+  (on a contract-3 entry the column is outside the digest and means nothing).
+- **A rewritten key id or epoch is now tampering.** An entry whose `chain_key_id` or
+  `chain_epoch` no longer matches the epoch records, and an entry that names an epoch with no
+  record, are reported as BROKEN (exit 1), with the new break kinds `epoch_mismatch` and
+  `epoch_missing`. In 0.6.0 the first of these was UNVERIFIABLE. An epoch record that was
+  edited or renumbered is BROKEN too (`epoch_altered`); so is one deleted while entries name
+  it. An epoch record forged under a key the verifier does not hold reads as UNVERIFIABLE —
+  never INTACT — and deleting the newest epoch before anything was written under it is not
+  detected.
+- **Entries without an epoch are unchanged.** Entries chained before epoch 0, and contract-3
+  entries written by 0.6.0 servers during the deploy, are checked exactly as in 0.6.0: a
+  rewritten key id on one of them still reads as unverifiable. The ledger has no record of
+  which keys signed them, and reeve does not invent one after the fact.
+- **Two rotations with no write between them** open two epochs that begin at the same
+  sequence; the first never signs anything. Not a break.
+- **The unverifiable count includes epoch records.** `unverifiable_count` (and the JSON
+  `totals`) count an epoch record whose key is not configured, as they already counted the
+  genesis.
+- **JSON output** gains `epochs` — an array of `{ "epoch", "key_id", "first_sequence",
+  "entries", "status" }`, `status` one of `verified`, `key_not_configured`, `altered` — and
+  `before_first_epoch`, the integer count of entries chained before epoch 0 (null, like
+  `head_at_start`, when nothing was walked). Each break gains `epoch`. Every existing field is unchanged.
+  The text report is unchanged for a ledger with one verified epoch and nothing before it.
+- **Custom recorders** that call `Reeve::Audit::Chain#append!` need no change: rows at
+  contract 4 are stamped with their epoch; rows passed at contract 3 are chained as before,
+  without one.
+- **A ledger on its own database**: connect `Reeve::Audit::ChainEpoch` the same way as
+  `Reeve::Audit::ChainRecord` (for example with the same `connects_to`). Verification refuses,
+  naming the model, if either reads from another database.
+
+What this adds to the guarantee, and what it does not, is in the README under
+"Tamper-evident, within stated limits". In short: a key the verifier does not hold still
+cannot be checked — epochs make that loss visible and attribute it to a named epoch, they do
+not undo it — and a leaked key, retired or current, can still rewrite what it signed.
+
+### Added
+
+- `bin/rails reeve:rotate_ledger_key` and `Reeve::Audit::Chain.rotate_key!`.
+- Key epochs: `reeve_audit_chain_epochs`, `chain_epoch`, and their verification.
+- The `reeve:upgrade` step to contract 4.
+
+## [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
@@ -410,6 +687,7 @@ is for:
 - **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 `2`.
+  alone — unless what its absence means, or what an existing value covers, differs between
+  rows written before and after it, which is major (contracts 3 and 4 are both examples).
+  Removing or renaming a column, or changing what a value means, is major and bumps it.
+- The audit-entry contract version is `4`.

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.5.0.** Read the known limitations in
+> **Status: 0.7.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,142 @@ 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; new epochs never open with them
+```
+
+**Rotating the key.** Every key that signs the ledger opens a numbered *key epoch*, and every
+entry records its epoch inside its digest. To rotate: set the new key as `ledger_key` and the
+old one in `retired_ledger_keys` (in that order), deploy, then run
+
+```bash
+bin/rails reeve:rotate_ledger_key
+```
+
+It reports `ROTATED` or `CURRENT` (exit `0`), or `REFUSED` (exit `1`, nothing written) — for
+instance when the current epoch's key is not configured where it runs, since that epoch's
+entries would become unverifiable there. Writes never wait for it: the first write with the
+new key opens its epoch, and servers still on the old key during the deploy keep writing
+under theirs. From Ruby:
+
+```ruby
+rotation = Reeve::Audit::Chain.rotate_key!
+rotation.status   # => :rotated, :current or :refused
+rotation.epoch    # => 1
+```
+
+Verification then lists each epoch under its summary line, with the key fingerprint, where
+it begins, and whether it verified. The CHANGELOG has the full procedure.
+
+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;
+- an entry whose key id or key epoch was changed, or that names an epoch with no record, and
+  an epoch record that was changed, or removed while entries name it (one forged under a key
+  you do not hold reads as unverifiable, never intact).
+
+**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. Likewise, entries without a key epoch — chained by
+   0.6.0, before or during the upgrade — are checked as 0.6.0 checked them: a rewritten key id
+   on one of them reads as unverifiable, not as tampering.
+5. **A key you no longer hold.** Entries it signed cannot be checked, by anyone. Epochs make
+   that visible and name the epoch; they do not undo it.
+
+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.6.0:** `bin/rails generate reeve:upgrade && bin/rails db:migrate` before
+the new code serves traffic, and grant `INSERT, SELECT` on `reeve_audit_chain_epochs`. The next guarded call opens epoch 0;
+earlier entries are listed as "before epoch 0" and checked as before.
+
+**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 +362,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
@@ -257,7 +398,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
@@ -470,12 +611,16 @@ 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+,
 because fast-mcp does.
 
+## Who built this
+
+Built by [Victor Velázquez](https://victorvelazquez.dev) — COO at [MagmaLabs](https://www.magmalabs.io) and author of [*The Agentic Engineer*](https://leanpub.com/theagenticengineer). Reeve guards MCP tools in production at MagmaLabs.
+
 ## License
 
 MIT. See [LICENSE.txt](LICENSE.txt).

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

@@ -13,12 +13,27 @@
 #   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;
+#   -- the key epochs: written once each, never updated
+#   GRANT INSERT, SELECT ON reeve_audit_chain_epochs TO app_role;
+#   GRANT USAGE  ON SEQUENCE reeve_audit_chain_epochs_id_seq TO app_role;
+#
+# Every row is chained to the one before it with a keyed digest, and names the key epoch
+# that signed it (audit-entry contract 4),
+# 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 +76,17 @@ 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
+
+      # The key epoch whose key signed the row (contract 4), inside the digest. Nullable for
+      # the same reason as the chain columns, and NULL on an unchained row.
+      t.integer  :chain_epoch
     end
 
     add_index :reeve_audit_entries, :invocation_id, unique: true
@@ -73,5 +99,39 @@ 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
+
+    # One row per key that has signed the ledger (contract 4): written when the key first
+    # signs, or by `bin/rails reeve:rotate_ledger_key`, and never updated. A key opens one
+    # epoch only, hence the unique key_id.
+    create_table :reeve_audit_chain_epochs do |t|
+      t.integer  :epoch,          null: false
+      t.string   :key_id,         null: false, limit: 16
+      t.bigint   :first_sequence, null: false
+      t.datetime :opened_at,      null: false, precision: 6
+      t.string   :epoch_digest,   null: false, limit: 64
+    end
+
+    add_index :reeve_audit_chain_epochs, :epoch, unique: true
+    add_index :reeve_audit_chain_epochs, :key_id, 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_key_epochs_to_reeve_audit_entries.rb.tt

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# Audit-entry contract 3 → 4. Generated by `bin/rails generate reeve:upgrade`.
+#
+# Records which key signed which stretch of the chain. Each key that signs the ledger opens
+# a numbered key epoch, recorded once in reeve_audit_chain_epochs, and every row reeve chains
+# from here on names its epoch in `chain_epoch`, inside its digest. Verification then reports
+# a row whose key or epoch was changed as tampering, where before it could only say the row
+# was signed by a key it did not have.
+#
+# Rows already in the table are not touched. Rows chained before the first epoch opens keep
+# exactly the verification they had; the column is nullable for that reason. The first
+# chained write after this migration opens epoch 0 with the configured ledger key.
+#
+# Rotate the key with `bin/rails reeve:rotate_ledger_key` (see the CHANGELOG).
+#
+# The application role needs INSERT and SELECT on the new table, never UPDATE:
+#
+#   GRANT INSERT, SELECT ON reeve_audit_chain_epochs TO app_role;
+class AddKeyEpochsToReeveAuditEntries < ActiveRecord::Migration[7.0]
+  def change
+    add_column :reeve_audit_entries, :chain_epoch, :integer
+
+    create_table :reeve_audit_chain_epochs do |t|
+      t.integer  :epoch,          null: false
+      t.string   :key_id,         null: false, limit: 16
+      t.bigint   :first_sequence, null: false
+      t.datetime :opened_at,      null: false, precision: 6
+      t.string   :epoch_digest,   null: false, limit: 64
+    end
+
+    add_index :reeve_audit_chain_epochs, :epoch, unique: true
+    add_index :reeve_audit_chain_epochs, :key_id, unique: true
+  end
+end