reeve 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a50e8fe479452d3b685dcd79b3022881c76567651444c6204e8db3d601b07c8
-  data.tar.gz: fe9974e2c035ce7c958f75d44a847d4b951f9cd828820aba9468310e2a143acd
+  metadata.gz: 5fec548cc5008459901b118b5bd79b3a3c47899554199c7a8a686ca3e9528cc8
+  data.tar.gz: 277700a1ad87207e90b693e96cfb2536ffec41459d420bd9d93d9fe08a1ebd68
 SHA512:
-  metadata.gz: aa5ff3ffce5221ee1b8baa64461865842faed31d432a0977051f6f3ec8be1846474174d27e19037a1a6b6901af5c6329fd38ac390e2da3fc664f7dfe9b7214ee
-  data.tar.gz: d986d9bd16574387f5529e983e932c1e740068a9b4a833a7220cf03dee30b3e134a5fd101a0ee41d2091bf3fa6660cc7ac67d52d720039bc149e32e6ec1dd33a
+  metadata.gz: 077330b44a698212477ea31db93ade9d0242c8c1a85ac546363a85a296ca5faaadb3865b058720ac74fb9e1a71e2e0afa72c42eb0687b78707cd5588cbad3394
+  data.tar.gz: f6b915ea4c1fb5ade7a2d07c71cc199b5446eca9dcfb8beecbdc233f1d7574e754b026de3a6ecd309fa82f9205af99b65a65c0182e8e5ba5fe31a7c57585fab8

data/CHANGELOG.md

@@ -4,6 +4,121 @@ 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
@@ -690,4 +805,6 @@ is for:
   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.7.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`:
 
@@ -256,6 +257,216 @@ 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
@@ -271,22 +482,32 @@ recorded unchained instead, logged each time, and reported by verification.
 - 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).
+  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. 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,
@@ -310,6 +531,12 @@ 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.

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

@@ -19,6 +19,15 @@
 #   -- 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;
+#   -- retention records: the application only reads them
+#   GRANT SELECT ON reeve_audit_retentions TO app_role;
+#
+#   -- the retention role, used only by `bin/rails reeve:purge_ledger`
+#   GRANT SELECT ON reeve_audit_entries, reeve_audit_chains, reeve_audit_chain_epochs,
+#                   reeve_audit_retentions TO retention_role;
+#   GRANT DELETE ON reeve_audit_entries TO retention_role;
+#   GRANT INSERT ON reeve_audit_retentions TO retention_role;
+#   GRANT USAGE  ON SEQUENCE reeve_audit_retentions_id_seq TO retention_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),
@@ -30,10 +39,10 @@
 # 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. Deleting rows
-#     breaks the chain by design.
+# The table grows until you purge it. Deleting rows by hand breaks the chain by design and
+# is reported as tampering; `bin/rails reeve:purge_ledger` removes the oldest entries up to
+# a checkpoint, archives them, and leaves a signed record in reeve_audit_retentions so the
+# rest still verifies. It runs on the retention role above, never the application's.
 #
 # `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
@@ -133,5 +142,21 @@ class CreateReeveAuditEntries < ActiveRecord::Migration[7.0]
 
     add_index :reeve_audit_chain_epochs, :epoch, unique: true
     add_index :reeve_audit_chain_epochs, :key_id, unique: true
+
+    create_table :reeve_audit_retentions do |t|
+      t.integer  :purge_number,      null: false
+      t.bigint   :through_sequence,  null: false
+      t.string   :through_digest,    null: false, limit: 64
+      t.bigint   :previous_through,  null: false
+      t.bigint   :removed_chained,   null: false
+      t.bigint   :removed_pre_chain, null: false
+      t.boolean  :archived,          null: false
+      t.string   :archive_sha256,    limit: 64
+      t.datetime :purged_at,         null: false, precision: 6
+      t.string   :key_id,            null: false, limit: 16
+      t.string   :retention_digest,  null: false, limit: 64
+    end
+
+    add_index :reeve_audit_retentions, :purge_number, unique: true
   end
 end

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

@@ -102,3 +102,13 @@ end
 
 # The ledger itself is opt-in, so the core stays loadable without ActiveRecord.
 require "reeve/audit"
+
+# Checkpoints of the chain, kept where the database's users cannot change them,
+# catch what the chain alone cannot: the newest entries removed with the head
+# rewound, or the whole ledger deleted. Run `bin/rails reeve:checkpoint_ledger`
+# on a schedule; `reeve:verify_ledger` then checks against them. One anchor per
+# environment, on storage outside the database host — a local file protects
+# nothing:
+#
+#   Reeve.config.ledger_anchor =
+#     Reeve::Audit::FileAnchor.new("/mnt/ledger-anchor/#{Rails.env}.checkpoints")

data/lib/generators/reeve/upgrade/templates/add_ledger_retention_to_reeve_audit_entries.rb.tt

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# Ledger retention. Generated by `bin/rails generate reeve:upgrade`. The audit-entry contract
+# stays 4: no column of reeve_audit_entries changes.
+#
+# Adds reeve_audit_retentions, where `bin/rails reeve:purge_ledger` records each purge: the
+# checkpoint it purged up to, how many rows it removed, and the archive it wrote, signed with
+# the ledger key. Verification reads it to tell a purge from a deletion. Nothing is purged
+# until you run the task.
+#
+# The application role only reads the new table. The retention role, which only the purge
+# uses, needs DELETE on the ledger and INSERT here:
+#
+#   GRANT SELECT ON reeve_audit_retentions TO app_role;
+#   GRANT SELECT ON reeve_audit_entries, reeve_audit_chains, reeve_audit_chain_epochs,
+#                   reeve_audit_retentions TO retention_role;
+#   GRANT DELETE ON reeve_audit_entries TO retention_role;
+#   GRANT INSERT ON reeve_audit_retentions TO retention_role;
+class AddLedgerRetentionToReeveAuditEntries < ActiveRecord::Migration[7.0]
+  def change
+    create_table :reeve_audit_retentions do |t|
+      t.integer  :purge_number,      null: false
+      t.bigint   :through_sequence,  null: false
+      t.string   :through_digest,    null: false, limit: 64
+      t.bigint   :previous_through,  null: false
+      t.bigint   :removed_chained,   null: false
+      t.bigint   :removed_pre_chain, null: false
+      t.boolean  :archived,          null: false
+      t.string   :archive_sha256,    limit: 64
+      t.datetime :purged_at,         null: false, precision: 6
+      t.string   :key_id,            null: false, limit: 16
+      t.string   :retention_digest,  null: false, limit: 64
+    end
+
+    add_index :reeve_audit_retentions, :purge_number, unique: true
+  end
+end

data/lib/generators/reeve/upgrade/upgrade_generator.rb

@@ -58,6 +58,15 @@ module Reeve
           creates: %w[reeve_audit_chain_epochs],
           template: "add_key_epochs_to_reeve_audit_entries.rb.tt",
           destination: "add_key_epochs_to_reeve_audit_entries.rb"
+        },
+        # Retention (specs/005) adds a table and no column, so the contract stays 4.
+        {
+          contract: 4,
+          note: :retention,
+          adds: [],
+          creates: %w[reeve_audit_retentions],
+          template: "add_ledger_retention_to_reeve_audit_entries.rb.tt",
+          destination: "add_ledger_retention_to_reeve_audit_entries.rb"
         }
       ].freeze
 
@@ -124,7 +133,7 @@ module Reeve
           Existing rows are stamped with the contract they were actually written under,
           not with the current one.
         NEXT
-        message + UpgradeNotes.for(@emitted.map { |step| step[:contract] })
+        message + UpgradeNotes.for(@emitted)
       end
 
       # Asked of the table rather than of a version the host recorded: the table is the

data/lib/generators/reeve/upgrade/upgrade_notes.rb

@@ -38,13 +38,24 @@ module Reeve
         The application role needs INSERT and SELECT on reeve_audit_chain_epochs.
       EPOCHS
 
-      BY_CONTRACT = { 3 => CHAIN, 4 => EPOCHS }.freeze
+      # Retention changes nothing until the host runs a purge, but the purge needs a role the
+      # application does not have, and the host should hear that before it needs one.
+      RETENTION = <<~RETENTION
+
+        The ledger can now be purged (reeve_audit_retentions): bin/rails reeve:purge_ledger
+        removes the oldest entries up to a checkpoint and records the purge, so the rest still
+        verifies. Nothing is purged until you run it. The application role needs SELECT on
+        the new table; the purge runs on a retention role of its own (see the migration).
+      RETENTION
+
+      # Keyed by the step's note, or by its contract when it has none.
+      BY_STEP = { 3 => CHAIN, 4 => EPOCHS, retention: RETENTION }.freeze
 
       module_function
 
-      # The notes for the contracts just written, oldest first.
-      def for(contracts)
-        contracts.filter_map { |contract| BY_CONTRACT[contract] }.join
+      # The notes for the steps just written, oldest first.
+      def for(steps)
+        steps.filter_map { |step| BY_STEP[step.fetch(:note, step[:contract])] }.join
       end
     end
   end