reeve 0.6.0 → 0.8.0

data/lib/reeve/audit/chain.rb

@@ -36,9 +36,16 @@ module Reeve
     # stays locked until that transaction ends, so every other guarded call waits behind it.
     # IsolatedRecorder holds it for one insert.
     class Chain
+      extend Entrypoints
+
       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
@@ -50,9 +57,22 @@ module Reeve
 
       # Verifies the whole ledger. With `keys:`, verifies with those keys alone — how an
       # auditor checks a ledger with their own copy of the key.
-      def self.verify(keys: nil, entry_class: Entry, batch_size: Verifier::BATCH_SIZE)
-        keyring = keys ? Keyring.new(signing: nil, retired: keys) : Keyring.from(Reeve.config)
-        Verifier.new(entry_class: entry_class, keyring: keyring, batch_size: batch_size).call
+      #
+      # `checkpoints:` (specs/004) are checkpoint lines or Checkpoints to check the ledger
+      # against; nil means the configured anchor's, and [] none. They are never read from the
+      # database. A line that does not parse raises CheckpointError before anything is walked.
+      #
+      # `from: :latest` walks from the checkpoint with the highest sequence instead of the
+      # genesis (FR-015), after checking that checkpoint on its own; a Checkpoint names one.
+      def self.verify(keys: nil, entry_class: Entry, checkpoints: nil, from: nil, **options)
+        Verifier.new(entry_class: entry_class, keyring: Keyring.verifying(keys), from: from,
+                     checkpoints: Checkpoint.read_all(checkpoints), **options).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)
@@ -77,7 +97,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 +117,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 +153,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 +186,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,23 @@ 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, RetentionRecord].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, ChainEpoch and RetentionRecord 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/file_anchor.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Audit
+    # The anchor reeve ships (specs/004 FR-006a, research R6): a file it only ever appends to,
+    # one checkpoint per line.
+    #
+    #   config.ledger_anchor = Reeve::Audit::FileAnchor.new("/mnt/ledger-anchor/production.checkpoints")
+    #
+    # A building block, not a guarantee. A checkpoint is worth exactly as much as the store's
+    # refusal to let the database's users change or delete it, and a file on the database host
+    # refuses nothing. Point it at storage those users cannot reach, such as a mount backed by
+    # an object-locked bucket or a path a separate shipper collects.
+    #
+    # Append mode puts every write at the end of the file even with several processes writing,
+    # and the lock keeps each line whole; the file is never opened any other way for writing.
+    class FileAnchor
+      attr_reader :path
+
+      def initialize(path)
+        @path = path.to_s
+        freeze
+      end
+
+      def publish(line)
+        if line.include?("\n")
+          raise ArgumentError,
+                "a checkpoint is one line; this one has a line break in it"
+        end
+
+        File.open(path, File::WRONLY | File::APPEND | File::CREAT, 0o644) do |file|
+          file.flock(File::LOCK_EX)
+          file.write("#{line}\n")
+          file.fsync
+        end
+      end
+
+      def checkpoints
+        return [] unless File.exist?(path)
+
+        File.readlines(path, chomp: true).reject { |line| line.strip.empty? }
+      end
+
+      def inspect
+        "#<#{self.class.name} #{path}>"
+      end
+    end
+  end
+end

data/lib/reeve/audit/retention_record.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Audit
+    # One purge (specs/005 data-model "reeve_audit_retentions"): which checkpoint the ledger
+    # was purged up to, what was removed, and the archive written, signed and chained to the
+    # purge before it.
+    #
+    # Written by `bin/rails reeve:purge_ledger` through the retention connection, never this
+    # model; the model only reads, for verification, and refuses to change one. As with
+    # ChainEpoch, that protects against the library, not against raw SQL; the verifier reports
+    # a record changed outside reeve.
+    class RetentionRecord < ActiveRecord::Base
+      self.table_name = "reeve_audit_retentions"
+
+      before_update { raise ActiveRecord::ReadOnlyRecord, "a retention record is written once" }
+      before_destroy { throw :abort }
+
+      def readonly?
+        persisted? || super
+      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,11 +114,32 @@ 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/retention_record"
 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/checkpoint"
+require_relative "audit/chain/epoch_rules"
+require_relative "audit/chain/checkpoint_check"
+require_relative "audit/chain/anchoring"
+require_relative "audit/chain/retention/records"
+require_relative "audit/chain/retention/digest"
+require_relative "audit/chain/retention/check"
+require_relative "audit/chain/retention/connection"
+require_relative "audit/chain/retention/purge_result"
+require_relative "audit/chain/retention/plan"
+require_relative "audit/chain/retention/archive"
+require_relative "audit/chain/retention/archive_check"
+require_relative "audit/chain/retention/preflight"
+require_relative "audit/chain/retention/purge"
+require_relative "audit/chain/entrypoints"
+require_relative "audit/chain/schema"
 require_relative "audit/chain/walk"
 require_relative "audit/chain/verifier"
 require_relative "audit/chain"
+require_relative "audit/file_anchor"
 
 Reeve::Audit.install!

data/lib/reeve/configuration.rb

@@ -25,6 +25,7 @@ module Reeve
       principal_resolver unguarded_tools audit_failure_mode redact_arguments
       max_recorded_ids policy_adapter default_action audit_recorder logger
       compliance_principals compliance_tools inventory ledger_key retired_ledger_keys
+      ledger_anchor ledger_retention_connection
     ].freeze
 
     # Shown by #to_h and #inspect as fingerprints. A configuration object gets printed —
@@ -48,6 +49,8 @@ module Reeve
       @inventory = nil
       @ledger_key = nil
       @retired_ledger_keys = []
+      @ledger_anchor = nil
+      @ledger_retention_connection = nil
     end
 
     # The key that signs the audit ledger's chain (specs/002). Held in configuration, never
@@ -203,6 +206,28 @@ module Reeve
         recorder.nil? ? nil : require_protocol!(:audit_recorder, recorder, [:record])
     end
 
+    # Where ledger checkpoints are kept (specs/004): an object with #publish(line) and
+    # #checkpoints, such as Reeve::Audit::FileAnchor. It must be storage the database's users
+    # cannot change; nil (the default) means checkpoints are made only on request and stored by
+    # whoever asked.
+    def ledger_anchor=(anchor)
+      @ledger_anchor =
+        anchor.nil? ? nil : require_protocol!(:ledger_anchor, anchor, %i[publish checkpoints])
+    end
+
+    # The database connection `bin/rails reeve:purge_ledger` deletes through (specs/005): an
+    # abstract ActiveRecord class the host connects to the ledger's database under a role of
+    # its own, the only one with DELETE on the ledger. Never the application's connection.
+    def ledger_retention_connection=(retention)
+      @ledger_retention_connection =
+        if retention.nil?
+          nil
+        else
+          require_protocol!(:ledger_retention_connection, retention,
+                            %i[connection_pool connection_db_config])
+        end
+    end
+
     def logger=(logger)
       @logger = logger.nil? ? nil : require_protocol!(:logger, logger, [:warn])
     end

data/lib/reeve/errors.rb

@@ -85,6 +85,21 @@ module Reeve
     end
   end
 
+  # Raised when a ledger checkpoint cannot be read (specs/004 research R5): a line that is
+  # not a checkpoint, or one in a format this version does not know. Not a break — it says
+  # nothing about the ledger — but never skipped either: a store whose lines do not read
+  # cannot be counted as anchoring anything. `position` is the line's place in its list,
+  # from 1, so the operator can find it; the line itself is not repeated.
+  class CheckpointError < Error
+    attr_reader :position
+
+    def initialize(reason, position: nil)
+      @position = position
+      where = position ? "checkpoint #{position}" : "a checkpoint"
+      super("#{where} cannot be read: #{reason}")
+    end
+  end
+
   # Raised when the ledger write fails and audit_failure_mode is :fail (FR-012).
   #
   # It carries a rule like any other denial, because the failure is not recorded anywhere

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 the ledger tasks (`bin/rails reeve:verify_ledger`, `reeve:rotate_ledger_key`,
+  # `reeve:checkpoint_ledger`, `reeve:purge_ledger`, `reeve:verify_archive`), 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/descriptions.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Reeve
+  # The ledger's Rake tasks, as `bin/rails -T` lists them (Reeve::Tasks.define).
+  module Tasks
+    # Each task's description, and the method of this module it runs.
+    DESCRIPTIONS = {
+      verify_ledger: "Verify the audit ledger's chain " \
+                     "(exit 0 intact, 1 broken, 2 could not verify; LIMIT=, FORMAT=json)",
+      checkpoint_ledger: "Checkpoint the audit ledger's chain to config.ledger_anchor " \
+                         "(exit 0 made, 1 refused or the anchor failed)",
+      purge_ledger: "Purge the audit ledger's oldest entries up to a checkpoint (THROUGH= or " \
+                    "OLDER_THAN=Nd; ARCHIVE=path or NO_ARCHIVE=1; nothing removed without " \
+                    "CONFIRM=1)",
+      verify_archive: "Verify an archive reeve:purge_ledger wrote, on its own " \
+                      "(ARCHIVE=path; exit 0 intact, 1 broken, 2 could not verify)",
+      rotate_ledger_key: "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)"
+    }.freeze
+  end
+end

data/lib/reeve/tasks/purge_options.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Tasks
+    # The environment `bin/rails reeve:purge_ledger` reads (specs/005, contracts/retention.md
+    # "Rake"), as keyword arguments for Reeve::Audit::Chain.purge!. Anything it does not accept
+    # is an ArgumentError naming what it does.
+    module PurgeOptions
+      module_function
+
+      def from(env)
+        through = env.fetch("THROUGH", "")
+        older = env.fetch("OLDER_THAN", "")
+        {
+          through: through.empty? ? nil : whole_number("THROUGH", through),
+          older_than: older.empty? ? nil : days("OLDER_THAN", older),
+          archive: env["ARCHIVE"].to_s.empty? ? nil : env["ARCHIVE"],
+          no_archive: flag("NO_ARCHIVE", env), confirm: flag("CONFIRM", env)
+        }.tap { |options| require_one_archive_choice!(options) }
+      end
+
+      def require_one_archive_choice!(options)
+        return unless options[:archive] && options[:no_archive]
+
+        raise ArgumentError, "give ARCHIVE=path or NO_ARCHIVE=1, not both"
+      end
+
+      def whole_number(name, raw)
+        Integer(raw, 10).tap { |value| raise ArgumentError unless value.positive? }
+      rescue ArgumentError
+        raise ArgumentError,
+              "#{name} must be a checkpoint's sequence (a whole number), got #{raw.inspect}"
+      end
+
+      def days(name, raw)
+        match = /\A(\d+)d\z/.match(raw)
+        unless match
+          raise ArgumentError,
+                "#{name} must be a number of days such as 365d, got #{raw.inspect}"
+        end
+
+        Integer(match[1], 10)
+      end
+
+      def flag(name, env)
+        raw = env.fetch(name, "")
+        return false if raw.empty?
+        return true if raw == "1"
+
+        raise ArgumentError, "#{name} must be 1 or unset, got #{raw.inspect}"
+      end
+    end
+  end
+end

data/lib/reeve/tasks.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require "json"
+require_relative "tasks/purge_options"
+require_relative "tasks/descriptions"
 
 module Reeve
   # `bin/rails reeve:verify_ledger` (specs/002 FR-017, contracts/ledger-chain.md "Rake").
@@ -14,6 +16,8 @@ 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
+    PURGE_EXIT = { dry_run: 0, purged: 0, nothing_to_purge: 0, refused: 1 }.freeze
 
     module_function
 
@@ -22,6 +26,11 @@ module Reeve
     #
     # LIMIT caps the breaks listed in the text report (default 100; the totals are never
     # capped). FORMAT=json writes the whole result, every break, and ignores LIMIT.
+    #
+    # Checks the ledger against config.ledger_anchor's checkpoints, if one is configured
+    # (specs/004). CHECKPOINTS=path reads them from a file of checkpoint lines instead, and
+    # CHECKPOINTS= (empty) verifies without any. A checkpoint that cannot be read is exit 2.
+    # FROM=latest walks from the highest checkpoint instead of the genesis.
     def verify_ledger(env: ENV, out: $stdout)
       format = env.fetch("FORMAT", "text")
       unless FORMATS.include?(format)
@@ -30,9 +39,98 @@ module Reeve
 
       limit = limit_from(env)
       require "reeve/audit"
-      result = Reeve::Audit::Chain.verify
+      result = Reeve::Audit::Chain.verify(checkpoints: checkpoints_from(env), from: from_env(env))
       out.puts(format == "json" ? JSON.generate(result.as_json) : result.to_s(limit: limit))
       EXIT.fetch(result.status)
+    rescue Reeve::CheckpointError => e
+      out.puts("reeve ledger: #{e.message}; nothing was verified")
+      EXIT.fetch(:unverifiable)
+    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)
+      status = ROTATE_EXIT.fetch(rotation.status)
+      return status unless rotation.rotated? && Reeve.config.ledger_anchor
+
+      checkpoint_after_rotation(out)
+    end
+
+    # Pins the epoch just opened, which no entry names yet (specs/004 FR-008). A failed anchor
+    # fails the task but does not undo the rotation: the epoch is open either way.
+    def checkpoint_after_rotation(out)
+      result = Reeve::Audit::Chain.checkpoint!
+      out.puts(result.to_s)
+      result.made? && !result.anchor_failed? ? 0 : 1
+    end
+
+    # Makes a checkpoint of the ledger's chain and hands it to config.ledger_anchor (specs/004,
+    # contracts/anchoring.md), writes what happened and the checkpoint's line to `out`, and
+    # returns the exit status: 0 made (and published, if there is an anchor), 1 refused or the
+    # anchor failed. The line is printed either way, so a failed store does not lose it.
+    def checkpoint_ledger(env: ENV, out: $stdout)
+      require "reeve/audit"
+      result = Reeve::Audit::Chain.checkpoint!
+      out.puts(result.to_s)
+      result.made? && !result.anchor_failed? ? 0 : 1
+    end
+
+    def from_env(env)
+      raw = env.fetch("FROM", "")
+      return nil if raw.empty?
+      return :latest if raw == "latest"
+
+      raise ArgumentError, "FROM must be latest or unset, got #{raw.inspect}"
+    end
+
+    # Purges the ledger's oldest entries up to a checkpoint (specs/005, contracts/retention.md),
+    # writes what it did to `out`, and returns the exit status: 0 for a dry run, a purge, or
+    # nothing to purge; 1 refused. Nothing is removed without CONFIRM=1.
+    def purge_ledger(env: ENV, out: $stdout)
+      options = PurgeOptions.from(env)
+      require "reeve/audit"
+      result = Reeve::Audit::Chain.purge!(**options)
+      out.puts(result.to_s)
+      PURGE_EXIT.fetch(result.status)
+    end
+
+    # Verifies an archive a purge wrote, on its own (specs/005 FR-012); exit codes as
+    # verify_ledger's. ARCHIVE=path names it.
+    def verify_archive(env: ENV, out: $stdout)
+      path = env.fetch("ARCHIVE", "")
+      raise ArgumentError, "ARCHIVE must name an archive file" if path.empty?
+
+      require "reeve/audit"
+      result = Reeve::Audit::Chain.verify_archive(path)
+      out.puts(result.to_s)
+      EXIT.fetch(result.status)
+    end
+
+    # nil (the configured anchor's) unless CHECKPOINTS is set.
+    def checkpoints_from(env)
+      return nil unless env.key?("CHECKPOINTS")
+
+      path = env["CHECKPOINTS"].to_s
+      return [] if path.empty?
+      raise Reeve::CheckpointError, "no checkpoint file at #{path}" unless File.file?(path)
+
+      Reeve::Audit::FileAnchor.new(path).checkpoints
+    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)
@@ -42,18 +140,17 @@ module Reeve
       raise ArgumentError, "LIMIT must be a whole number of breaks to list, got #{raw.inspect}"
     end
 
-    # The Rake task, defined on the current Rake application. Depends on :environment, so
-    # the host's initializer — and with it the ledger key — is loaded first.
+    # The Rake tasks, defined on the current Rake application. Each depends on :environment,
+    # so the host's initializer — and with it the ledger key — is loaded first.
     #
     # The DSL is borrowed by a throwaway object, so Reeve::Tasks itself never gains `task`,
     # `sh` and the rest of Rake's methods.
     def define
       Object.new.extend(Rake::DSL).instance_exec do
         namespace :reeve do
-          desc "Verify the audit ledger's chain " \
-               "(exit 0 intact, 1 broken, 2 could not verify; LIMIT=, FORMAT=json)"
-          task verify_ledger: :environment do
-            exit Reeve::Tasks.verify_ledger
+          DESCRIPTIONS.each do |name, description|
+            desc description
+            task(name => :environment) { exit Reeve::Tasks.public_send(name) }
           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)