reeve 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 03d0a3695140d0703272da744486caa3ab21530eddb0d48d275977e3b83047c0
-  data.tar.gz: aa8988dd9d7fc1dfb40b5c7a67f1f0a9f70d5ba72350b7669ba32afb2121f140
+  metadata.gz: 4a50e8fe479452d3b685dcd79b3022881c76567651444c6204e8db3d601b07c8
+  data.tar.gz: fe9974e2c035ce7c958f75d44a847d4b951f9cd828820aba9468310e2a143acd
 SHA512:
-  metadata.gz: 116dbf0359f8666ffa50cb70a9a85aa7a037d76390305b3315fc4ecc37233fe83a5faabb14103c0ae999ae69f5cc5fa020813cd7da3ade8ae86f837639604c98
-  data.tar.gz: 4ae861908807ec1bc3b3363442edda7cf6936d60d01e39b5aa03f6ae91cd7e0daad49ac8a154a53db277894c866cf9adfdb2e8776d99071b20d6d4704647f4b0
+  metadata.gz: aa5ff3ffce5221ee1b8baa64461865842faed31d432a0977051f6f3ec8be1846474174d27e19037a1a6b6901af5c6329fd38ac390e2da3fc664f7dfe9b7214ee
+  data.tar.gz: d986d9bd16574387f5529e983e932c1e740068a9b4a833a7220cf03dee30b3e134a5fd101a0ee41d2091bf3fa6660cc7ac67d52d720039bc149e32e6ec1dd33a

data/CHANGELOG.md

@@ -4,6 +4,178 @@ 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
@@ -515,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 `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.
+- 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.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.
 
@@ -230,9 +230,32 @@ 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.
+
 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,7 +268,10 @@ 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).
 
 **Not detected** — stated plainly, because these are the limits of the guarantee:
 
@@ -256,7 +282,11 @@ recorded unchained instead, logged each time, and reported by verification.
 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.
+   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,
@@ -280,6 +310,10 @@ 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.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 +617,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).

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

@@ -16,8 +16,12 @@
 #   -- 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 (audit-entry contract 3),
+# 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
@@ -79,6 +83,10 @@ class CreateReeveAuditEntries < ActiveRecord::Migration[7.0]
       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
@@ -111,5 +119,19 @@ class CreateReeveAuditEntries < ActiveRecord::Migration[7.0]
     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/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

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

@@ -2,6 +2,7 @@
 
 require "rails/generators"
 require "rails/generators/active_record"
+require_relative "upgrade_notes"
 
 module Reeve
   module Generators
@@ -50,11 +51,17 @@ module Reeve
           creates: %w[reeve_audit_chains],
           template: "add_ledger_chain_to_reeve_audit_entries.rb.tt",
           destination: "add_ledger_chain_to_reeve_audit_entries.rb"
+        },
+        {
+          contract: 4,
+          adds: %w[chain_epoch],
+          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"
         }
       ].freeze
 
-      KEY_LINE = "config.ledger_key = " \
-                 'Rails.application.key_generator.generate_key("reeve audit ledger", 32)'
+      KEY_LINE = UpgradeNotes::KEY_LINE
 
       source_root File.expand_path("templates", __dir__)
 
@@ -117,29 +124,7 @@ module Reeve
           Existing rows are stamped with the contract they were actually written under,
           not with the current one.
         NEXT
-        message += chain_message if @emitted.any? { |step| step[:contract] == 3 }
-        message
-      end
-
-      # Contract 3 changes what the application must configure, not only the table: without
-      # a key, every guarded call fails closed once the migration runs. The host is reading
-      # this output at exactly the moment they need to know that.
-      def chain_message
-        <<~CHAIN
-
-          The ledger is now chained (contract 3). Add this line to config/initializers/reeve.rb
-          before you deploy, or every guarded call fails closed:
-
-            #{KEY_LINE}
-
-          It derives the key from secret_key_base, so rotating secret_key_base rotates the
-          ledger key: keep the old derived key in config.retired_ledger_keys, or entries it
-          signed become unverifiable. A dedicated key avoids that coupling.
-
-          Very large ledger on PostgreSQL? The migration builds a unique index that blocks
-          writes while it scans; the migration's header shows how to build it with
-          algorithm: :concurrently instead.
-        CHAIN
+        message + UpgradeNotes.for(@emitted.map { |step| step[:contract] })
       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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Generators
+    # What `reeve:upgrade` tells the host after writing a step whose contract changes more
+    # than the table. The host is reading this output at exactly the moment they need it.
+    module UpgradeNotes
+      KEY_LINE = "config.ledger_key = " \
+                 'Rails.application.key_generator.generate_key("reeve audit ledger", 32)'
+
+      # Contract 3 changes what the application must configure, not only the table: without
+      # a key, every guarded call fails closed once the migration runs.
+      CHAIN = <<~CHAIN.freeze
+
+        The ledger is now chained (contract 3). Add this line to config/initializers/reeve.rb
+        before you deploy, or every guarded call fails closed:
+
+          #{KEY_LINE}
+
+        It derives the key from secret_key_base, so rotating secret_key_base rotates the
+        ledger key: keep the old derived key in config.retired_ledger_keys, or entries it
+        signed become unverifiable. A dedicated key avoids that coupling.
+
+        Very large ledger on PostgreSQL? The migration builds a unique index that blocks
+        writes while it scans; the migration's header shows how to build it with
+        algorithm: :concurrently instead.
+      CHAIN
+
+      # Contract 4 changes how a rotation is done, so the host learns the command here.
+      EPOCHS = <<~EPOCHS
+
+        The ledger now records key epochs (contract 4): the first chained write opens
+        epoch 0 with the configured ledger key. To rotate the key later, set the new key
+        as config.ledger_key, keep the old one in config.retired_ledger_keys, deploy, and run:
+
+          bin/rails reeve:rotate_ledger_key
+
+        The application role needs INSERT and SELECT on reeve_audit_chain_epochs.
+      EPOCHS
+
+      BY_CONTRACT = { 3 => CHAIN, 4 => EPOCHS }.freeze
+
+      module_function
+
+      # The notes for the contracts just written, oldest first.
+      def for(contracts)
+        contracts.filter_map { |contract| BY_CONTRACT[contract] }.join
+      end
+    end
+  end
+end

data/lib/reeve/audit/chain/canonical.rb

@@ -31,19 +31,27 @@ module Reeve
         ENTRY_TAG = "reeve-ledger-entry-v1"
         GENESIS_TAG = "reeve-ledger-genesis-v1"
 
+        EPOCH_TAG = "reeve-ledger-epoch-v1"
+
+        CONTRACT_3_FIELDS = %w[
+          chain_sequence chain_key_id contract_version
+          invocation_id occurred_at agent_id agent_name principal_type principal_id
+          tool_name arguments outcome rule detail record_type record_ids record_count
+          truncated derived guard duration_ms metadata
+        ].freeze
+
+        # Contract 4 (specs/003) adds the key epoch, next to the key it names.
         ENTRY_FIELDS = {
-          3 => %w[
-            chain_sequence chain_key_id contract_version
-            invocation_id occurred_at agent_id agent_name principal_type principal_id
-            tool_name arguments outcome rule detail record_type record_ids record_count
-            truncated derived guard duration_ms metadata
-          ].freeze
+          3 => CONTRACT_3_FIELDS,
+          4 => CONTRACT_3_FIELDS.dup.insert(2, "chain_epoch").freeze
         }.freeze
 
         GENESIS_FIELDS = %w[genesis_at pre_chain_count pre_chain_unchained_count
                             genesis_key_id].freeze
 
-        TIME_FIELDS = %w[occurred_at genesis_at].freeze
+        EPOCH_FIELDS = %w[epoch key_id first_sequence opened_at].freeze
+
+        TIME_FIELDS = %w[occurred_at genesis_at opened_at].freeze
 
         module_function
 
@@ -56,6 +64,13 @@ module Reeve
           hmac(secret, GENESIS_TAG, dump(pairs))
         end
 
+        # An epoch record (specs/003 FR-002), linked to the epoch before it — or, for epoch 0,
+        # to the genesis — so the epochs are a chain of their own.
+        def epoch_digest(secret, epoch, previous_digest:)
+          pairs = EPOCH_FIELDS.map { |field| [field, value(epoch, field)] }
+          hmac(secret, EPOCH_TAG, dump([["previous_digest", previous_digest], *pairs]))
+        end
+
         def entry_message_body(row, previous_digest)
           version = value(row, "contract_version")
           fields = ENTRY_FIELDS.fetch(version) do