reeve 0.6.0 → 0.7.0

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

@@ -23,7 +23,7 @@ module Reeve
         BATCH_SIZE = 1_000
 
         RECORD_MISSING = "chained rows exist but the chain record does not"
-        UNCHAINED_ROW = "a contract-3 row outside the chain, written after it started (by clock)"
+        UNCHAINED_ROW = "a contract-3+ row outside the chain, written after it started (by clock)"
 
         def initialize(entry_class:, keyring:, batch_size: BATCH_SIZE)
           @entry_class = entry_class
@@ -46,20 +46,26 @@ module Reeve
 
         attr_reader :entry_class, :keyring, :batch_size, :breaks
 
+        # The epochs are read after the head: every row the walk visits committed, with any
+        # epoch it opened, before that read. They are checked against the head read *after*
+        # the walk, which is later than they were read, so an epoch opened by a rotation
+        # during the run is never mistaken for one placed beyond the head.
         def verify_chain(record)
           @breaks = []
-          walk = walk(record)
+          epochs = EpochRules.read(keyring: keyring, entry_class: entry_class)
+          walk = walk(record, epochs)
           check_record(record, walk)
           head_at_end = record && read_head
           check_beyond_head(head_at_end || record)
           check_unchained(record)
+          epochs.check!(record, head_at_end || record, report: method(:add))
 
-          result(record, head_at_end, walk.last_sequence)
+          result(record, head_at_end, walk.last_sequence, epochs)
         end
 
-        def walk(record)
+        def walk(record, epochs)
           Walk.new(entry_class: entry_class, keyring: keyring, batch_size: batch_size,
-                   link: record&.genesis_digest, report: method(:add))
+                   link: record&.genesis_digest, report: method(:add), epochs: epochs)
               .call(record&.head_sequence)
         end
 
@@ -121,15 +127,17 @@ module Reeve
           end
         end
 
-        def add(kind, sequence, detail = nil, invocation_id = nil, key_id = nil)
-          breaks << Verification::Break.new(kind: kind, sequence: sequence, detail: detail,
-                                            invocation_id: invocation_id, key_id: key_id)
+        # `epoch` names the key epoch a break is about when it has no sequence (specs/003).
+        def add(kind, sequence, detail = nil, invocation_id = nil, key_id = nil, epoch: nil)
+          found = { kind: kind, sequence: sequence, detail: detail, invocation_id: invocation_id }
+          breaks << Verification::Break.new(**found, key_id: key_id, epoch: epoch)
         end
 
-        def result(record, head_at_end, last_sequence)
+        def result(record, head_at_end, last_sequence, epochs)
           Verification.new(
             status: Verification.status_for(breaks), breaks: breaks,
             covered: covered(record, last_sequence),
+            epochs: epochs.summaries, before_first_epoch: epochs.before_first_epoch,
             head_at_start: record&.head_sequence, head_at_end: head_at_end&.head_sequence,
             uncovered_now: count_uncovered, uncovered_at_genesis: record&.pre_chain_count,
             unchained_now: count_unchained, unchained_at_genesis: record&.pre_chain_unchained_count

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

@@ -20,11 +20,13 @@ module Reeve
 
         # `link` is the digest the first row must link to (the genesis), or nil when there
         # is no chain record to take it from. `report` receives (kind, sequence, detail).
-        def initialize(entry_class:, keyring:, batch_size:, link:, report:)
+        # `epochs` is the EpochRules the rows are checked against (specs/003 FR-011).
+        def initialize(entry_class:, keyring:, batch_size:, link:, report:, epochs:)
           @entry_class = entry_class
           @keyring = keyring
           @batch_size = batch_size
           @report = report
+          @epochs = epochs
           @expected = 1
           @last_sequence = 0
           @link = link
@@ -39,7 +41,7 @@ module Reeve
 
         private
 
-        attr_reader :entry_class, :keyring, :batch_size
+        attr_reader :entry_class, :keyring, :batch_size, :epochs
 
         def visit(entry)
           sequence = entry.chain_sequence
@@ -71,6 +73,10 @@ module Reeve
         end
 
         def verify(entry, previous)
+          # A row whose key or epoch contradicts the epoch records is a break on its own; its
+          # digest would only repeat it.
+          return if epoch_break?(entry)
+
           # With no chain record there is no genesis for the first row to link to. That is
           # reported once, as chain_record_missing, not again here as a mismatch.
           return if !@verify_first_link && entry.chain_sequence == 1
@@ -88,6 +94,14 @@ module Reeve
           @report.call(:digest_mismatch, entry.chain_sequence, e.message)
         end
 
+        def epoch_break?(entry)
+          kind, detail = epochs.judge(entry)
+          return false unless kind
+
+          @report.call(kind, entry.chain_sequence, detail)
+          true
+        end
+
         def each_chained(limit, &block)
           after = nil
           loop do

data/lib/reeve/audit/chain.rb

@@ -38,7 +38,12 @@ module Reeve
     class Chain
       TABLE = "reeve_audit_chains"
 
-      COLUMNS = %w[chain_sequence chain_key_id chain_digest].freeze
+      COLUMNS = %w[chain_sequence chain_key_id chain_digest chain_epoch].freeze
+
+      EPOCHS_TABLE = "reeve_audit_chain_epochs"
+
+      # The first contract whose rows name their key epoch.
+      EPOCH_CONTRACT = 4
 
       # A contract-3 row outside the chain: the walk only reads rows with a sequence, so a
       # row without one is counted here or nowhere. Written once and used by both the
@@ -55,6 +60,12 @@ module Reeve
         Verifier.new(entry_class: entry_class, keyring: keyring, batch_size: batch_size).call
       end
 
+      # Makes the configured ledger key the key of the latest epoch (specs/003 FR-006) and
+      # returns a Rotation saying what happened. `bin/rails reeve:rotate_ledger_key` runs it.
+      def self.rotate_key!(accept_unverifiable: false, entry_class: Entry)
+        new(entry_class: entry_class).rotate_key!(accept_unverifiable: accept_unverifiable)
+      end
+
       def initialize(entry_class: Entry, keyring: nil)
         @entry_class = entry_class
         @keyring = keyring
@@ -77,7 +88,9 @@ module Reeve
           insert_once(normalized) do
             head = Head.new(connection: connection, entry_class: entry_class)
             head.start!(signer)
-            entry_class.transaction(requires_new: true) { link!(head, normalized, signer) }
+            schema.explaining do
+              entry_class.transaction(requires_new: true) { link!(head, normalized, signer) }
+            end
           end
         end
       end
@@ -95,6 +108,26 @@ module Reeve
         end
       end
 
+      # Starts the chain if it has not started — the genesis needs the key the epoch will
+      # open with — then decides under the head's lock, so a write and a rotation never
+      # interleave. A refusal writes nothing.
+      def rotate_key!(accept_unverifiable: false)
+        signer = keyring
+        return Rotation.refused(:no_key) unless signer.signing?
+
+        require_columns!
+        with_connection do |connection|
+          head = Head.new(connection: connection, entry_class: entry_class)
+          head.start!(signer)
+          schema.explaining do
+            entry_class.transaction(requires_new: true) do
+              Rotation.decide(Epochs.new(connection: connection), signer,
+                              head_sequence: head.lock!, accept_unverifiable: accept_unverifiable)
+            end
+          end
+        end
+      end
+
       private
 
       attr_reader :entry_class
@@ -111,10 +144,18 @@ module Reeve
       # column defaults (`truncated: false`) and casts on assignment (an Integer principal_id
       # becomes a String), and the instance is exactly what the database will be given.
       # Digesting the hash a caller passed would sign values that are never stored.
+      #
+      # A row at contract 4 or later names the key epoch its key opened, opening the next one
+      # if the key has none (specs/003 FR-004); a contract-3 row from a custom recorder is
+      # chained exactly as 0.6.0 chained it.
       def link!(head, normalized, signer)
         sequence, previous = head.advance!
-        entry = entry_class.new(normalized.merge(chain_sequence: sequence,
-                                                 chain_key_id: signer.signing_id))
+        chain = { chain_sequence: sequence, chain_key_id: signer.signing_id, chain_epoch: nil }
+        if normalized[:contract_version].to_i >= EPOCH_CONTRACT
+          chain[:chain_epoch] = Epochs.new(connection: head.connection)
+                                      .for_signing!(signer, sequence: sequence)
+        end
+        entry = entry_class.new(normalized.merge(chain))
         entry.chain_digest = Canonical.entry_digest(signer.signing_secret, entry,
                                                     previous_digest: previous)
         entry.save!
@@ -136,13 +177,11 @@ module Reeve
       # A table one contract behind the gem fails here, naming the fix, rather than as an
       # "unknown attribute" or "no such column" from deep inside the write.
       def require_columns!
-        missing = COLUMNS - entry_class.column_names
-        return if missing.empty?
+        schema.require_columns!
+      end
 
-        raise ConfigurationError,
-              "#{entry_class.table_name} is missing #{missing.join(', ')}: the ledger is at an " \
-              "older audit-entry contract than this reeve writes (#{CONTRACT_VERSION}). Run " \
-              "`bin/rails generate reeve:upgrade` and `bin/rails db:migrate`."
+      def schema
+        @schema ||= Schema.new(entry_class)
       end
 
       def replayed(normalized)

data/lib/reeve/audit/chain_epoch.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Audit
+    # One key epoch: the key that began signing the ledger at `first_sequence` (specs/003
+    # data-model "reeve_audit_chain_epochs").
+    #
+    # Written by Chain — when a key first signs, or by `bin/rails reeve:rotate_ledger_key` —
+    # through the ledger's own connection, inside the write that needs it. This model only
+    # reads them, for verification, and refuses to change one: an epoch is written once.
+    # As with ChainRecord, that protects against the library, not against raw SQL; the
+    # verifier reports an epoch changed outside reeve.
+    class ChainEpoch < ActiveRecord::Base
+      self.table_name = "reeve_audit_chain_epochs"
+
+      before_update { raise ActiveRecord::ReadOnlyRecord, "a key epoch is written once" }
+      before_destroy { throw :abort }
+
+      def readonly?
+        persisted? || super
+      end
+    end
+  end
+end

data/lib/reeve/audit/chain_record.rb

@@ -44,17 +44,22 @@ module Reeve
       end
 
       # The record is written through the ledger's own connection (Chain::Head) and read
-      # through this model's. A host that moves the ledger to a database of its own and
-      # leaves this model behind would have verification read the wrong record and report
-      # tampering on every run; refusing, with the fix, is the honest answer.
+      # through this model's — and so are the key epochs (ChainEpoch, specs/003 FR-019a). A
+      # host that moves the ledger to a database of its own and leaves either model behind
+      # would have verification read the wrong rows and report tampering on every run;
+      # refusing, with the fix, is the honest answer.
       def self.require_same_database!(entry_class)
         ledger_database = entry_class.connection_db_config.configuration_hash
-        return if connection_db_config.configuration_hash == ledger_database
+        [self, ChainEpoch].each do |model|
+          next if model.connection_db_config.configuration_hash == ledger_database
 
-        raise ConfigurationError,
-              "Reeve::Audit::ChainRecord is connected to a different database than " \
-              "#{entry_class.name}. Connect ChainRecord the same way as the ledger (for " \
-              "example with the same connects_to) so the chain is read where it is written."
+          short = model.name.split("::").last
+          raise ConfigurationError,
+                "#{model.name} is connected to a different database than #{entry_class.name}. " \
+                "Connect ChainRecord and ChainEpoch the same way as the ledger (for example " \
+                "with the same connects_to) so the chain is read where it is written; #{short} " \
+                "is the one that is not."
+        end
       end
     end
   end

data/lib/reeve/audit.rb

@@ -59,8 +59,14 @@ module Reeve
   module Audit
     # The version of the audit-entry shape, as documented in
     # specs/001-guardrails-core/contracts/audit-entry.md (FR-015). Adding a nullable
-    # column is a MINOR change and leaves this alone; removing or renaming a column, or
-    # changing what a value means, is MAJOR and bumps it.
+    # column is a MINOR change and leaves this alone — unless what its absence means, or
+    # what an existing value covers, differs between rows written before and after it;
+    # removing or renaming a column, or changing what a value means, is MAJOR and bumps it.
+    #
+    # 4 — entries name their key epoch (specs/003). One nullable column, `chain_epoch`, but
+    # it is inside the digest, so `chain_digest` on a contract-4 row covers something a
+    # contract-3 digest does not, and a NULL epoch means "before key epochs" on a contract-3
+    # row where a chained contract-4 row always has one.
     #
     # 3 — entries are chained (specs/002). The three chain columns are nullable, so the
     # shape change is additive, but what a NULL digest means changed: on a contract-3 row
@@ -71,7 +77,7 @@ module Reeve
     # was written NULL on every row regardless of what was passed, so anything mapping
     # version 1 rows could reasonably have read the column as "always empty". The shape
     # did not change; what a value means did.
-    CONTRACT_VERSION = 3
+    CONTRACT_VERSION = 4
 
     TABLE_NAME = "reeve_audit_entries"
 
@@ -108,9 +114,14 @@ require_relative "audit/chain/keyring"
 require_relative "audit/chain/normalizer"
 require_relative "audit/chain/canonical"
 require_relative "audit/chain_record"
+require_relative "audit/chain_epoch"
 require_relative "audit/chain/verification"
 require_relative "audit/chain/report"
 require_relative "audit/chain/head"
+require_relative "audit/chain/epochs"
+require_relative "audit/chain/rotation"
+require_relative "audit/chain/epoch_rules"
+require_relative "audit/chain/schema"
 require_relative "audit/chain/walk"
 require_relative "audit/chain/verifier"
 require_relative "audit/chain"

data/lib/reeve/railtie.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 module Reeve
-  # Registers `bin/rails reeve:verify_ledger`, and does nothing else.
+  # Registers `bin/rails reeve:verify_ledger` and `bin/rails reeve:rotate_ledger_key`, and
+  # does nothing else.
   #
   # Loaded by lib/reeve.rb only when Rails::Railtie is already defined, so `require "reeve"`
   # in a plain Ruby process still loads nothing beyond reeve's own files and its short stdlib

data/lib/reeve/tasks.rb

@@ -14,6 +14,7 @@ module Reeve
   module Tasks
     EXIT = { intact: 0, broken: 1, unverifiable: 2, no_chain: 2 }.freeze
     FORMATS = %w[text json].freeze
+    ROTATE_EXIT = { rotated: 0, current: 0, refused: 1 }.freeze
 
     module_function
 
@@ -35,6 +36,28 @@ module Reeve
       EXIT.fetch(result.status)
     end
 
+    # Makes the configured ledger key the latest epoch's key (specs/003, contracts/
+    # key-rotation.md), writes what happened to `out`, and returns the exit status: 0 rotated
+    # or already current, 1 refused.
+    #
+    # ACCEPT_UNVERIFIABLE=1 opens the epoch even though the outgoing epoch's key is not
+    # configured here — for a key that is lost, and only then.
+    def rotate_ledger_key(env: ENV, out: $stdout)
+      accept = accept_unverifiable_from(env)
+      require "reeve/audit"
+      rotation = Reeve::Audit::Chain.rotate_key!(accept_unverifiable: accept)
+      out.puts(rotation.to_s)
+      ROTATE_EXIT.fetch(rotation.status)
+    end
+
+    def accept_unverifiable_from(env)
+      raw = env.fetch("ACCEPT_UNVERIFIABLE", "")
+      return false if raw.empty?
+      return true if raw == "1"
+
+      raise ArgumentError, "ACCEPT_UNVERIFIABLE must be 1 or unset, got #{raw.inspect}"
+    end
+
     def limit_from(env)
       raw = env.fetch("LIMIT", Reeve::Audit::Chain::Verification::DEFAULT_LIMIT.to_s)
       Integer(raw, 10).tap { |limit| raise ArgumentError if limit.negative? }
@@ -55,6 +78,12 @@ module Reeve
           task verify_ledger: :environment do
             exit Reeve::Tasks.verify_ledger
           end
+
+          desc "Make config.ledger_key the ledger's current key epoch (exit 0 rotated or " \
+               "current, 1 refused; ACCEPT_UNVERIFIABLE=1 if the old key is lost)"
+          task rotate_ledger_key: :environment do
+            exit Reeve::Tasks.rotate_ledger_key
+          end
         end
       end
     end

data/lib/reeve/testing/checks/contract_version.rb

@@ -46,10 +46,10 @@ module Reeve
           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 contract_version
-          chain_sequence chain_key_id chain_digest
+          chain_sequence chain_key_id chain_digest chain_epoch
         ].freeze
 
-        EXPECTED_VERSION = 3
+        EXPECTED_VERSION = 4
 
         def initialize(tool: nil, expected: EXPECTED_VERSION, ledger: nil)
           super(tool: tool, ledger: ledger)

data/lib/reeve/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Reeve
-  VERSION = "0.6.0"
+  VERSION = "0.7.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: reeve
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Victor Velazquez
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-10 00:00:00.000000000 Z
+date: 2026-10-23 00:00:00.000000000 Z
 dependencies: []
 description: |
   Reeve makes it safe for a Rails application to expose MCP (Model Context Protocol)
@@ -31,19 +31,26 @@ files:
 - lib/generators/reeve/install/templates/create_audit_entries.rb.tt
 - lib/generators/reeve/install/templates/initializer.rb.tt
 - lib/generators/reeve/upgrade/templates/add_contract_version_to_reeve_audit_entries.rb.tt
+- lib/generators/reeve/upgrade/templates/add_key_epochs_to_reeve_audit_entries.rb.tt
 - lib/generators/reeve/upgrade/templates/add_ledger_chain_to_reeve_audit_entries.rb.tt
 - lib/generators/reeve/upgrade/upgrade_generator.rb
+- lib/generators/reeve/upgrade/upgrade_notes.rb
 - lib/reeve.rb
 - lib/reeve/audit.rb
 - lib/reeve/audit/chain.rb
 - lib/reeve/audit/chain/canonical.rb
+- lib/reeve/audit/chain/epoch_rules.rb
+- lib/reeve/audit/chain/epochs.rb
 - lib/reeve/audit/chain/head.rb
 - lib/reeve/audit/chain/keyring.rb
 - lib/reeve/audit/chain/normalizer.rb
 - lib/reeve/audit/chain/report.rb
+- lib/reeve/audit/chain/rotation.rb
+- lib/reeve/audit/chain/schema.rb
 - lib/reeve/audit/chain/verification.rb
 - lib/reeve/audit/chain/verifier.rb
 - lib/reeve/audit/chain/walk.rb
+- lib/reeve/audit/chain_epoch.rb
 - lib/reeve/audit/chain_record.rb
 - lib/reeve/audit/entry.rb
 - lib/reeve/audit/isolated_recorder.rb