reeve 0.7.0 → 0.8.0

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

@@ -25,10 +25,14 @@ module Reeve
         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)"
 
-        def initialize(entry_class:, keyring:, batch_size: BATCH_SIZE)
+        # `checkpoints` are Checkpoints read from outside the database, and `from` one of them to
+        # walk from instead of the genesis (specs/004; Anchoring).
+        def initialize(entry_class:, keyring:, batch_size: BATCH_SIZE, checkpoints: [], from: nil)
           @entry_class = entry_class
           @keyring = keyring
           @batch_size = batch_size
+          @anchoring = Anchoring.new(entry_class: entry_class, keyring: keyring,
+                                     checkpoints: checkpoints, from: from)
         end
 
         def call
@@ -36,37 +40,70 @@ module Reeve
 
           ChainRecord.require_same_database!(entry_class)
 
+          @breaks = []
           record = read_head
-          return unwalked(:no_chain) unless record&.head_sequence&.positive? || chained_rows?
+          return verify_chain(record) if record&.head_sequence&.positive? || chained_rows?
+          return unwalked(:no_chain) unless anchoring.any?
 
-          verify_chain(record)
+          # A ledger with no chain that checkpoints saw: broken, not "no chain" (FR-013).
+          unwalked(checkpoints: anchoring.emptied(record, report: method(:add)))
         end
 
         private
 
-        attr_reader :entry_class, :keyring, :batch_size, :breaks
+        attr_reader :entry_class, :keyring, :batch_size, :breaks, :anchoring
 
         # 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 = []
           epochs = EpochRules.read(keyring: keyring, entry_class: entry_class)
+          retention = check_retention(record)
+          failed = anchoring.failed_start(record, epochs.records, report: method(:add))
+          return unwalked(record: record, checkpoints: failed) if failed
+
           walk = walk(record, epochs)
+          head_at_end = check_around(record, walk, epochs)
+          anchored = anchoring.check(record, head_at_end || record, epochs.records,
+                                     report: method(:add))
+
+          result(record, head_at_end, walk.last_sequence, epochs,
+                 **anchored, retention: retention, awaiting_purge: awaiting_purge)
+        end
+
+        # The purges, if any (specs/005): the latest that holds is where the walk starts.
+        def check_retention(record)
+          records = Retention::Records.read(entry_class: entry_class)
+          return nil if records.empty?
+
+          checked = Retention::Check.new(keyring: keyring, report: method(:add))
+                                    .call(records, genesis_digest: record&.genesis_digest)
+          anchoring.floor = checked.boundary
+          checked
+        end
+
+        # Rows still at or below the boundary: a purge stopped midway, or a restore (FR-010).
+        def awaiting_purge
+          floor = anchoring.floor
+          floor ? entry_class.where("chain_sequence <= ?", floor.through_sequence).count : 0
+        end
+
+        # The chain record, rows past the head, unchained rows and the epochs, each checked
+        # against what the walk found; returns the head as read after the walk.
+        def check_around(record, walk, 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, epochs)
+          head_at_end
         end
 
         def walk(record, epochs)
           Walk.new(entry_class: entry_class, keyring: keyring, batch_size: batch_size,
-                   link: record&.genesis_digest, report: method(:add), epochs: epochs)
-              .call(record&.head_sequence)
+                   link: anchoring.link(record), report: method(:add), epochs: epochs,
+                   start: anchoring.start).call(record&.head_sequence)
         end
 
         # A seam as well as a read: the specs wrap it to land a write mid-walk.
@@ -127,16 +164,19 @@ module Reeve
           end
         end
 
-        # `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)
+        # `epoch` names the key epoch, and `checkpoint` the checkpoint, a break is about when it has
+        # no sequence (specs/003, specs/004).
+        def add(kind, sequence, detail = nil, invocation_id = nil, key_id = nil, epoch: nil,
+                checkpoint: nil, retention: nil)
           found = { kind: kind, sequence: sequence, detail: detail, invocation_id: invocation_id }
-          breaks << Verification::Break.new(**found, key_id: key_id, epoch: epoch)
+          breaks << Verification::Break.new(**found, key_id: key_id, epoch: epoch,
+                                                     checkpoint: checkpoint, retention: retention)
         end
 
-        def result(record, head_at_end, last_sequence, epochs)
+        def result(record, head_at_end, last_sequence, epochs, **found)
           Verification.new(
             status: Verification.status_for(breaks), breaks: breaks,
-            covered: covered(record, last_sequence),
+            covered: covered(record, last_sequence), walked_from: anchoring.from, **found,
             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,
@@ -146,13 +186,18 @@ module Reeve
 
         def covered(record, last_sequence)
           last = record ? record.head_sequence : last_sequence
-          last.positive? ? 1..last : nil
+          first = anchoring.start + 1
+          last >= first ? first..last : nil
         end
 
-        # An answer given before any walk: no key to walk with, or no chain to walk.
-        def unwalked(status, reason = nil)
-          Verification.new(status: status, reason: reason,
-                           uncovered_now: count_uncovered, unchained_now: count_unchained)
+        # An answer given before any walk: no key to walk with, no chain to walk, or checkpoints
+        # whose own breaks say why there was nothing to walk (specs/004). Without a status, the
+        # breaks decide it.
+        def unwalked(status = nil, reason = nil, record: nil, checkpoints: [])
+          Verification.new(status: status || Verification.status_for(breaks), reason: reason,
+                           breaks: breaks || [], head_at_start: record&.head_sequence,
+                           checkpoints: checkpoints, uncovered_now: count_uncovered,
+                           unchained_now: count_unchained)
         end
 
         def chained_rows?

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

@@ -21,14 +21,19 @@ 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).
         # `epochs` is the EpochRules the rows are checked against (specs/003 FR-011).
-        def initialize(entry_class:, keyring:, batch_size:, link:, report:, epochs:)
+        #
+        # `start` is the sequence of a checkpoint the walk begins after (specs/004 FR-015), with
+        # `link` its digest: the walk is then exactly the one from the genesis, resumed there.
+        def initialize(entry_class:, keyring:, batch_size:, link:, report:, epochs:, start: 0)
           @entry_class = entry_class
           @keyring = keyring
           @batch_size = batch_size
           @report = report
           @epochs = epochs
-          @expected = 1
-          @last_sequence = 0
+          @start = start
+          @expected = start + 1
+          @last_sequence = start
+          @last_digest = start.positive? ? link : nil
           @link = link
           @verify_first_link = !link.nil?
         end
@@ -124,6 +129,7 @@ module Reeve
         # against SC-004's 300. SQLite derived the bound on its own, which hid it there.
         def batch_scope(after, limit)
           scope = entry_class.where.not(chain_sequence: nil)
+          scope = scope.where("chain_sequence > ?", @start) if @start.positive? && after.nil?
           scope = scope.where("chain_sequence <= ?", limit) if limit
           if after
             scope = scope.where("chain_sequence >= ?", after[0])

data/lib/reeve/audit/chain.rb

@@ -36,6 +36,8 @@ 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 chain_epoch].freeze
@@ -55,9 +57,16 @@ 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

data/lib/reeve/audit/chain_record.rb

@@ -50,13 +50,14 @@ module Reeve
       # refusing, with the fix, is the honest answer.
       def self.require_same_database!(entry_class)
         ledger_database = entry_class.connection_db_config.configuration_hash
-        [self, ChainEpoch].each do |model|
+        [self, ChainEpoch, RetentionRecord].each do |model|
           next if model.connection_db_config.configuration_hash == ledger_database
 
           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 " \
+                "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

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

@@ -115,15 +115,31 @@ 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,8 +1,8 @@
 # frozen_string_literal: true
 
 module Reeve
-  # Registers `bin/rails reeve:verify_ledger` and `bin/rails reeve:rotate_ledger_key`, 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").
@@ -15,6 +17,7 @@ module Reeve
     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
 
@@ -23,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)
@@ -31,9 +39,12 @@ 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/
@@ -47,7 +58,71 @@ module Reeve
       require "reeve/audit"
       rotation = Reeve::Audit::Chain.rotate_key!(accept_unverifiable: accept)
       out.puts(rotation.to_s)
-      ROTATE_EXIT.fetch(rotation.status)
+      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)
@@ -65,24 +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
-          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
+          DESCRIPTIONS.each do |name, description|
+            desc description
+            task(name => :environment) { exit Reeve::Tasks.public_send(name) }
           end
         end
       end