reeve 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 03d0a3695140d0703272da744486caa3ab21530eddb0d48d275977e3b83047c0
-  data.tar.gz: aa8988dd9d7fc1dfb40b5c7a67f1f0a9f70d5ba72350b7669ba32afb2121f140
+  metadata.gz: 5fec548cc5008459901b118b5bd79b3a3c47899554199c7a8a686ca3e9528cc8
+  data.tar.gz: 277700a1ad87207e90b693e96cfb2536ffec41459d420bd9d93d9fe08a1ebd68
 SHA512:
-  metadata.gz: 116dbf0359f8666ffa50cb70a9a85aa7a037d76390305b3315fc4ecc37233fe83a5faabb14103c0ae999ae69f5cc5fa020813cd7da3ade8ae86f837639604c98
-  data.tar.gz: 4ae861908807ec1bc3b3363442edda7cf6936d60d01e39b5aa03f6ae91cd7e0daad49ac8a154a53db277894c866cf9adfdb2e8776d99071b20d6d4704647f4b0
+  metadata.gz: 077330b44a698212477ea31db93ade9d0242c8c1a85ac546363a85a296ca5faaadb3865b058720ac74fb9e1a71e2e0afa72c42eb0687b78707cd5588cbad3394
+  data.tar.gz: f6b915ea4c1fb5ade7a2d07c71cc199b5446eca9dcfb8beecbdc233f1d7574e754b026de3a6ecd309fa82f9205af99b65a65c0182e8e5ba5fe31a7c57585fab8

data/CHANGELOG.md

@@ -4,6 +4,293 @@ 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.8.0] - 2026-10-25
+
+Two additions to the tamper-evident ledger: **anchoring**, checkpoints of the chain kept
+outside the database, so deleting the newest entries or the whole ledger is caught; and
+**retention**, purging the oldest entries up to a checkpoint without breaking verification.
+No audit-entry contract change: it stays `4`.
+
+### Upgrading from 0.7.0
+
+1. `bundle update reeve`, then `bin/rails generate reeve:upgrade && bin/rails db:migrate`. It
+   adds one table, `reeve_audit_retentions`; nothing in the ledger table changes.
+2. Grant the application's database role `SELECT` on `reeve_audit_retentions`.
+3. If anything reads the text output of `bin/rails reeve:verify_ledger`, switch it to
+   `FORMAT=json`: every summary line now ends with its anchoring (`; not anchored` until you
+   set one up). Existing JSON keys are unchanged.
+
+Anchoring and retention are both opt-in; the README shows how to set each up.
+
+### Anchoring
+
+The chain's own records live in the same database as the entries, so two kinds of tampering
+went unseen: deleting the newest entries and rewinding the head to match, and deleting the
+whole ledger, which read as "no chain". A new epoch nobody had written under yet could also
+be deleted without trace. Now reeve can make a **checkpoint**, one signed line saying how far
+the chain reached, and hand it to an **anchor**: storage you choose, outside the database.
+Verification checks the ledger against every checkpoint.
+
+**No contract change.** The audit-entry contract stays `4`. Nothing changes for a ledger
+write. (Retention, below, adds one table.)
+
+#### Added
+
+- `bin/rails reeve:checkpoint_ledger` (`Reeve::Tasks.checkpoint_ledger`,
+  `Reeve::Audit::Chain.checkpoint!`): makes a checkpoint, publishes it, and prints it. Exit `0`
+  made, `1` refused (no key, no chain yet) or the anchor failed; the line is printed either way
+  so it can be stored by hand.
+- `config.ledger_anchor`: any object with `publish(line)` and `checkpoints`. reeve ships
+  `Reeve::Audit::FileAnchor`, a file it only ever appends to. It is a building block: on the
+  database host it protects nothing. Point it at storage the database's users cannot change,
+  such as a mount backed by an object-locked bucket, and use one per environment.
+- `reeve:verify_ledger` checks against the anchor's checkpoints when one is configured.
+  `CHECKPOINTS=path` reads a file of checkpoint lines instead, `CHECKPOINTS=` (empty) uses
+  none, and `FROM=latest` walks only what came after the newest checkpoint. A checkpoint line
+  that does not read is exit `2`, naming its position.
+- New breaks, all exit `1`: `checkpoint_not_reached`, `checkpoint_mismatch`,
+  `checkpoint_altered`. A checkpoint signed by a key not configured is unverifiable (exit `2`).
+  With a checkpoint, an emptied ledger is BROKEN, not NO CHAIN.
+- `reeve:rotate_ledger_key` makes a checkpoint after opening an epoch when an anchor is
+  configured, so the new epoch is pinned before anything is written under it.
+- `Reeve::Checks::LedgerChain.new(anchored: true)`: also makes a checkpoint, reads it back
+  from the anchor and verifies against it. Run it as a test of its own (the README shows how);
+  the suite's own `LedgerChain` never reads the anchor, since checkpoints earlier runs left
+  name test databases that are gone.
+
+#### Changed
+
+- **Every summary line that follows a walk now ends with its anchoring**: `; not anchored`,
+  or `; anchored at #48,000 (checkpoint 2026-10-25 14:00 UTC), 211 entries after it`. This
+  applies whether or not you configure an anchor. If something reads the text report, read
+  `FORMAT=json` instead; its existing keys are unchanged, and it gains `checkpoints`,
+  `anchored_at`, `beyond_anchor`, `walked_from` and `breaks[].checkpoint`.
+
+#### Limits, stated plainly
+
+- Entries written after the latest checkpoint can still be removed without trace. The summary
+  line counts the entries still there after it, not ones deleted; how often you checkpoint is
+  the size of that window.
+- A checkpoint is only as safe as its store. One an attacker can delete or overwrite protects
+  nothing, and reeve cannot make a store append-only.
+- A leaked key can still rewrite the chain from any point, but not a checkpoint made before
+  the leak: rewriting an entry it saw changes the digest it names.
+- Restoring a backup older than a checkpoint reads as BROKEN, because the restored ledger lost
+  entries that checkpoint saw. A database reset on purpose needs a new anchor file.
+- A checkpoint's time is the producing host's clock, for people. Verification never uses it.
+
+### Retention
+
+The ledger could only grow, and deleting old rows by hand broke the chain and read as
+tampering. Now `bin/rails reeve:purge_ledger` removes the oldest entries up to a checkpoint
+your anchor holds, writes an archive of them first, and leaves a signed **retention record**, so
+the rest still verifies and the purge reads as a purge.
+
+**One migration, no contract change.** `bin/rails generate reeve:upgrade` adds the table
+`reeve_audit_retentions`; the audit-entry contract stays `4`. Grant the application's role
+`SELECT` on it. Nothing is purged until you run the task.
+
+**The constitution's append-only rule now has one exception** (1.1.0): application code still
+cannot update or delete an entry; only this operator-run purge can, and only behind a verified,
+anchored checkpoint, on a database role the application does not use, after writing a signed
+record.
+
+- `config.ledger_retention_connection`: an abstract ActiveRecord class connected to the ledger's
+  database as a role with `DELETE`; the purge refuses another database, or the application's
+  own user (SQLite has no roles, so there it warns).
+- `bin/rails reeve:purge_ledger`: `OLDER_THAN=365d` or `THROUGH=sequence`; exactly one of
+  `ARCHIVE=path` (a new file each run) and `NO_ARCHIVE=1`; nothing removed without `CONFIRM=1`.
+  Exit `0` for a dry run, a purge, or nothing to purge (the first line says which); `1` refused,
+  with the reason and the fix. It requires the whole ledger to verify INTACT first. A purge
+  stopped midway leaves rows "awaiting purge" (INTACT, not a break); any rerun finishes it first.
+  The README shows the role, the grants and the `database.yml` entry.
+- `bin/rails reeve:verify_archive ARCHIVE=path`: verifies an archive on its own, from its start to
+  its boundary checkpoint. It needs the application (for the table's column types), not the
+  purged rows.
+- Verification starts after the latest purge, names the purged range on every summary line,
+  reports checkpoints older than it as purged, and gains `retention_altered` (BROKEN) and the JSON
+  keys `retention` and `awaiting_purge`.
+
+Keep every ledger key: epoch and retention records stay in the ledger and are checked under
+their own keys, and archives need the keys of the rows they hold.
+
+Limits, in plain words: what a purge removed without an archive is gone for good, and the record
+proves only that it existed and verified. An archive is a file you must keep safe, as you do the
+anchor. A row edited inside the purged range while the purge runs is not reported by the ledger,
+because it is being removed; the archive holds what was read.
+
+## [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
@@ -515,6 +802,9 @@ 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 `3`.
+  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.
+- A new table beside the ledger that leaves its rows unchanged is minor and leaves the
+  contract alone (`reeve_audit_retentions`, 0.8.0).
+- 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.6.0.** Read the known limitations in
+> **Status: 0.8.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.
 
@@ -200,7 +200,7 @@ 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)
+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); not anchored
 ```
 
 It exits `0` when the chain is intact, `1` when it is broken, and `2` when it could not
@@ -218,7 +218,8 @@ 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.
+were not chained. "Not anchored" on the summary line is explained under **Anchoring the
+chain** below.
 
 **The key.** The generated initializer derives it from `secret_key_base`:
 
@@ -230,9 +231,242 @@ Rotating `secret_key_base` therefore rotates the ledger key. Keep the old one, o
 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
+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.
+
+**Anchoring the chain.** The chain's own records live in the same database as the entries, so
+someone who deletes the newest entries and rewinds the head to match, or deletes the whole
+ledger, leaves nothing behind that verification can see. A *checkpoint* is a second witness:
+one signed line saying how far the chain reached (its genesis, its head, its latest key
+epoch), kept where the database's users cannot change it. It holds digests and counts only,
+never entry content or a key.
+
+Point an anchor at that storage. The line goes at the bottom of
+`config/initializers/reeve.rb`, after `require "reeve/audit"` (which defines `FileAnchor`),
+outside the `Reeve.configure` block, hence `Reeve.config`:
+
+```ruby
+require "reeve/audit"
+
+Reeve.config.ledger_anchor =
+  Reeve::Audit::FileAnchor.new("/mnt/ledger-anchor/#{Rails.env}.checkpoints")
+```
+
+Use one anchor per environment, on storage outside the database host, such as a mount backed
+by an object-locked bucket; a file next to the database protects nothing. The hosts that make
+checkpoints need to write the file (it is created on the first one), and the hosts that verify
+need to read it. Any object with `publish(line)` and `checkpoints` works in its place.
+
+Then make a checkpoint on a schedule, from one host (hourly, say), and keep verifying as
+before. Alert on anything but `0` from either task. `reeve:checkpoint_ledger` exits `1` when
+it refused (no key, or no chain until the first guarded call) or the anchor failed, and still
+prints the line so it can be stored by hand. Two runs at once are safe.
+
+```bash
+bin/rails reeve:checkpoint_ledger   # exit 0 made and published
+bin/rails reeve:verify_ledger       # checks the ledger against every checkpoint
+```
+
+```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); anchored at #48,000 (checkpoint 2026-10-25 14:00 UTC), 211 entries after it
+```
+
+Every checkpoint is checked: a ledger that no longer reaches one, holds another entry where it
+saw one, or lost an epoch record it named, is BROKEN (exit `1`), and so is an emptied ledger,
+which without a checkpoint reads only as "no chain". The newest entries deleted with the head
+rewound read like this:
+
+```text
+reeve ledger: BROKEN — 1 break in sequences 1–46,211; 5,000 earlier entries not covered (5,000 when the chain started); anchored at #44,000 (checkpoint 2026-10-25 13:00 UTC), 2,211 entries after it
+  totals: checkpoint_not_reached 1
+  checkpoint #48,000 checkpoint_not_reached the head is at 46,211; entries the checkpoint saw were removed
+```
+
+What it does not cover: entries written after the latest checkpoint can still be removed
+without trace. "211 entries after it" counts the entries still there past the checkpoint; it
+cannot see ones that were deleted, so how often you checkpoint is the size of that window.
+`reeve:rotate_ledger_key` makes a checkpoint itself after opening an epoch. Writes never touch
+the anchor.
+
+*Restores and resets.* Restoring a backup older than a checkpoint reads as BROKEN, truthfully:
+the restored ledger lost entries that checkpoint saw. Resetting a database on purpose (a
+staging rebuild) is the same, so start a new anchor file for the new ledger: change the path
+(`staging-2026-10-25.checkpoints`, say), keep the old file as the record of the old ledger, and
+make a checkpoint. Until then the run reads "not anchored". `CHECKPOINTS=` (empty) verifies
+without any checkpoint, for a one-off check, never as the fix.
+
+*Other sources, large ledgers.* `CHECKPOINTS=path` verifies against a file of checkpoint lines
+instead of the anchor, say an auditor's copy. `FROM=latest` walks only what came after the
+newest checkpoint: it first checks that checkpoint (its signature, the genesis and epoch it
+names, and that its entry still has the digest it saw), then verifies every entry after it.
+Entries before it are not re-verified by that run, and the summary says how many; keep a full
+run on a slower schedule. With no checkpoint to start from it exits `2`. From Ruby:
+
+```ruby
+Reeve::Audit::Chain.checkpoint!.checkpoint.to_line            # => "{\"epoch\":1,…}"
+Reeve::Audit::Chain.verify(checkpoints: lines).anchored_at    # the highest checkpoint that held
+```
+
+*In CI.* The `LedgerChain` check the compliance suite runs never reads the anchor, so
+configuring one does not change it: a test database is emptied between runs, and old
+checkpoints name ledgers that are gone. To prove the anchor works, run the anchored variant as
+a test of its own, with the test environment's anchor pointed at a scratch file such as
+`Rails.root.join("tmp/ledger.checkpoints")`. It makes a checkpoint, reads it back through the
+anchor, and verifies against that one alone:
+
+```ruby
+# RSpec
+it "anchors the ledger" do
+  result = Reeve::Checks::LedgerChain.new(anchored: true).call
+  expect(result).to be_passed, result.message
+end
+
+# Minitest
+def test_anchors_the_ledger
+  result = Reeve::Checks::LedgerChain.new(anchored: true).call
+  assert result.passed?, result.message
+end
+```
+
+**Purging old entries.** The ledger grows until you purge it. Deleting rows by hand breaks
+the chain and is reported as tampering, so reeve purges for you: the oldest entries, up to a
+checkpoint your anchor holds, after verifying the whole ledger INTACT, leaving a signed
+*retention record* so the rest still verifies and the purge reads as a purge. It also removes
+rows written before the chain began, and nothing else. It stops at a checkpoint, so with
+`OLDER_THAN=365d` a few entries just over a year old can remain until the next run.
+
+*Setting it up, once.* Run `bin/rails generate reeve:upgrade && bin/rails db:migrate` (it adds
+`reeve_audit_retentions`), then create a database role only the purge uses; the application's
+role never gains `DELETE`. On PostgreSQL (the migration's header shows the same grants):
+
+```sql
+CREATE ROLE reeve_retention LOGIN PASSWORD '…';
+GRANT SELECT ON reeve_audit_entries, reeve_audit_chains, reeve_audit_chain_epochs,
+                reeve_audit_retentions TO reeve_retention;
+GRANT DELETE ON reeve_audit_entries TO reeve_retention;
+GRANT INSERT ON reeve_audit_retentions TO reeve_retention;
+GRANT USAGE  ON SEQUENCE reeve_audit_retentions_id_seq TO reeve_retention;
+GRANT SELECT ON reeve_audit_retentions TO app_role;   -- the application only reads it
+```
+
+Add the role to `config/database.yml` as a second database entry pointing at the same
+database, and a class that connects through it:
+
+```yaml
+production:
+  primary:
+    <<: *default
+    database: app_production
+  ledger_retention:
+    <<: *default
+    database: app_production          # the same database
+    username: reeve_retention
+    password: <%= ENV["REEVE_RETENTION_PASSWORD"] %>
+    database_tasks: false             # never migrated through this entry
+```
+
+```ruby
+# app/models/ledger_retention_record.rb
+class LedgerRetentionRecord < ActiveRecord::Base
+  self.abstract_class = true
+  connects_to database: { writing: :ledger_retention }
+end
+
+# config/initializers/reeve.rb, after require "reeve/audit"
+Reeve.config.ledger_retention_connection = LedgerRetentionRecord
+```
+
+The purge refuses a connection to another database, or one that logs in as the application's
+own user. On SQLite, which has no roles, it can only warn. The task needs the ledger key, as
+every chain task does.
+
+*Running it.* Monthly, from one host, a dry run first (no `CONFIRM`), then the purge. The
+archive path must be new each run: an existing archive is never overwritten.
+
+```bash
+bin/rails reeve:purge_ledger OLDER_THAN=365d ARCHIVE=/mnt/archive/ledger-2026-10.jsonl            # dry run
+bin/rails reeve:purge_ledger OLDER_THAN=365d ARCHIVE=/mnt/archive/ledger-2026-10.jsonl CONFIRM=1
+```
+
+```text
+reeve ledger purge: WOULD PURGE — sequences 1–6,000 through checkpoint #6,000 (2025-10-01 14:00 UTC): 6,000 chained entries and 5,000 pre-chain rows; archive to /mnt/archive/ledger-2026-10.jsonl; run again with CONFIRM=1
+```
+
+In crontab, escape the date's `%`: `ledger-$(date +\%Y-\%m).jsonl`. `THROUGH=6000` names a
+checkpoint's sequence instead of an age. Exactly one of `ARCHIVE=path` and `NO_ARCHIVE=1` is
+required; with neither the task refuses, with both it raises. Exit `0` covers a dry run, a
+purge, and nothing old enough (the first line says which: `WOULD PURGE`, `PURGED`, `NOTHING TO
+PURGE`); exit `1` is a refusal, which removes nothing and names the fix:
+
+| Refusal says | Fix |
+|---|---|
+| no anchor configured | set `config.ledger_anchor` and schedule checkpoints (above) |
+| no retention connection / another database / the application's own database user | `config.ledger_retention_connection` and the role above |
+| the ledger does not verify intact | read `bin/rails reeve:verify_ledger`; nothing is purged while anything is broken or unverifiable |
+| no checkpoint the anchor holds is at that sequence | use one of the two it names, or `OLDER_THAN` |
+| the archive … already exists, or cannot be written | a new path, in a directory the task can write |
+
+Any other failure (a lost connection, a full disk) raises, exit `1` from Rake, like any task.
+
+*If it stops midway.* The archive is written in full and the retention record committed
+before any row is deleted. If the host dies during the deletes, verification reads INTACT,
+exit `0`, with `; 120 entries awaiting purge` beside the purged range, which is not a break.
+Run the purge again, the same command or any other: it first finishes the interrupted purge
+(`PURGED — … (resumed; 120 rows removed this run)`), whatever boundary the new run names, and
+skips the archive, which already exists. Run it once more to purge further.
+
+*The archive.* Every purged row with every column, so the range can be checked without the
+ledger's rows:
+
+```bash
+bin/rails reeve:verify_archive ARCHIVE=/mnt/archive/ledger-2026-10.jsonl   # reeve archive: INTACT — sequences 1–6,000 verified, …
+```
+
+It runs inside the application (it needs the entries table's columns, from any database with
+the schema, not the purged rows), with the keys that signed the archived rows configured as
+`ledger_key` or `retired_ledger_keys`; the anchor is not needed. Each archive covers the range
+its purge removed, named in its first line, so name files by the month they were made. Keep
+archives where they cannot be changed, as you do the anchor. `NO_ARCHIVE=1` deletes without
+one, for data you must not keep; the record and the output then say no archive was written.
+
+*Keys.* Keep every key you ever signed with. A purge removes entries, not epoch records or
+retention records, and verification still checks those under their own keys; archives need
+the keys of the rows they hold.
+
+After a purge, every summary line names what was purged before its coverage; with
+`FORMAT=json`, `retention` and `awaiting_purge` hold the same:
+
+```text
+reeve ledger: INTACT — sequences 6,001–10,000 verified (head at start: 10,000); 1–6,000 purged (retention record 0, 2026-10-25); 0 earlier entries not covered (5,000 when the chain started, 5,000 purged); anchored at #10,000 (checkpoint 2026-10-25 14:00 UTC), 0 entries after it
+```
+
+Checkpoints older than the boundary read as purged. Deleting entries a retention record does
+not cover, or editing or deleting a record, is BROKEN (`retention_altered` or `missing`), as
+before.
+
 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
@@ -245,18 +479,35 @@ recorded unchained instead, logged each time, and reported by verification.
 - 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.
+- 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);
+- with checkpoints: any entry the latest checkpoint saw removed, even with the head rewound;
+  the whole ledger deleted or replaced; an epoch record a checkpoint named, removed or changed;
+  a checkpoint edited, or forged without a key you hold.
 
 **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.
+   default that is anyone holding `secret_key_base`. Not past a checkpoint made before the
+   leak, though: rewriting an entry it saw changes the digest it names.
+2. **The newest rows deleted by someone who also rewinds the chain record's head**, unless a
+   checkpoint saw them. Rows after the latest checkpoint stay exposed; the summary line counts
+   them.
+3. **The whole ledger deleted, chain record included**, without a checkpoint. Reported as
+   *no chain*, never as a pass, but indistinguishable from a ledger that was never chained.
+   And checkpoints are only as safe as their store: one an attacker can delete protects nothing.
 4. **Rows written before you upgraded.** They are counted as "not covered" and are exactly
-   as trustworthy as they were before.
+   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.
+6. **What a purge removed.** Without an archive, nobody can read it again; the retention record
+   proves only that it existed, verified, and was removed on purpose. A row edited inside the
+   range while the purge runs is not reported by the ledger, since it is being removed; the
+   archive holds what was read.
 
 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,
@@ -280,6 +531,16 @@ same door the built-in ones use, or verification reports them as unchained:
 Reeve::Audit::Chain.new(entry_class: Reeve::Audit::Entry).append!(row)
 ```
 
+**Upgrading from 0.7.0:** `bin/rails generate reeve:upgrade && bin/rails db:migrate` adds
+`reeve_audit_retentions`; grant the application's role `SELECT` on it. Nothing is purged until
+you run the task, and anchoring is opt-in. Every summary line now ends with its anchoring
+(`; not anchored` until you set one up), so anything that matches the whole text line should
+read `FORMAT=json` instead, whose existing keys are unchanged.
+
+**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
@@ -583,6 +844,10 @@ 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).