reeve 0.6.0 → 0.8.0

data/lib/reeve/audit/chain/retention/purge_result.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Audit
+    class Chain
+      # What `bin/rails reeve:purge_ledger` did, or why it did nothing (specs/005 data-model,
+      # contracts/retention.md). A value, so a script can act on it without reading the text.
+      #
+      #   :dry_run           — what a run with CONFIRM=1 would remove; nothing removed
+      #   :purged            — removed through `through`, recorded as retention record `purge`
+      #   :nothing_to_purge  — no checkpoint above the current boundary qualifies
+      #   :refused           — nothing removed; `reason` says why
+      class PurgeResult
+        PREFIX = "reeve ledger purge:"
+        AGAIN = "run again with CONFIRM=1"
+
+        FIELDS = %i[status reason detail from through through_made_at removed_chained
+                    removed_pre_chain archive archive_sha256 purge resumed warnings].freeze
+
+        REFUSALS = {
+          no_key: "no ledger key configured (config.ledger_key)",
+          no_anchor: "no anchor configured (config.ledger_anchor): a purge must stop at a " \
+                     "checkpoint kept outside the database",
+          no_retention_connection: "no retention connection configured " \
+                                   "(config.ledger_retention_connection)",
+          other_database: "config.ledger_retention_connection reaches another database than " \
+                          "the ledger's",
+          application_role: "config.ledger_retention_connection connects as the application's " \
+                            "own database user; the purge must run on a role the application " \
+                            "does not use",
+          no_checkpoint: "no checkpoint the anchor holds is at that sequence (nearest below: %s, " \
+                         "above: %s)",
+          not_intact: "the ledger does not verify intact, and a purge never removes what it " \
+                      "cannot prove: %s",
+          no_archive_choice: "give ARCHIVE=path to keep the purged entries, or NO_ARCHIVE=1 to " \
+                             "delete them without one",
+          archive_exists: "the archive %s already exists; an archive is never overwritten",
+          archive_unwritable: "the archive %s cannot be written there",
+          purge_running: "another purge took the next retention record number; run again once " \
+                         "it is done"
+        }.freeze
+
+        attr_reader(*FIELDS)
+
+        def self.refused(reason, detail: nil)
+          new(status: :refused, reason: reason, detail: detail)
+        end
+
+        def self.nothing(reason, current:)
+          new(status: :nothing_to_purge, reason: reason, through: current)
+        end
+
+        def self.from(plan, status, **fields)
+          new(status: status, from: plan.from, through: plan.through,
+              through_made_at: plan.checkpoint.made_at, removed_chained: plan.removed_chained,
+              removed_pre_chain: plan.removed_pre_chain, **fields)
+        end
+
+        def self.resumed(record, removed, warnings:)
+          new(status: :purged, from: record.previous_through + 1, through: record.through_sequence,
+              purge: record.purge_number, removed_chained: record.removed_chained,
+              removed_pre_chain: record.removed_pre_chain, resumed: removed,
+              archive_sha256: record.archive_sha256, warnings: warnings)
+        end
+
+        def initialize(status:, warnings: [], **fields)
+          @status = status
+          @warnings = warnings.freeze
+          (FIELDS - %i[status warnings]).each do |name|
+            instance_variable_set(:"@#{name}", fields[name])
+          end
+          freeze
+        end
+
+        def dry_run? = status == :dry_run
+        def purged? = status == :purged
+        def refused? = status == :refused
+
+        def to_s
+          [first_line, *warnings.map { |warning| "warning: #{warning}" }].join("\n")
+        end
+
+        private
+
+        def first_line
+          case status
+          when :dry_run then "#{PREFIX} WOULD PURGE — #{removal}; #{archive_text}; #{AGAIN}"
+          when :purged then "#{PREFIX} PURGED — #{purged_text}"
+          when :nothing_to_purge then "#{PREFIX} NOTHING TO PURGE — #{nothing_text}"
+          else "#{PREFIX} REFUSED — #{refusal}; nothing was removed"
+          end
+        end
+
+        def purged_text
+          record = "#{removal}; retention record #{purge}"
+          return "#{record} (resumed; #{n(resumed)} rows removed this run)" if resumed
+
+          "#{record}; #{archive_text}"
+        end
+
+        def removal
+          made = through_made_at ? " (#{AnchorText.made_on(through_made_at)})" : ""
+          "sequences #{n(from || 1)}–#{n(through)} through checkpoint ##{n(through)}#{made}: " \
+            "#{n(removed_chained)} chained entries and #{n(removed_pre_chain)} pre-chain rows"
+        end
+
+        def archive_text
+          return "no archive written (NO_ARCHIVE=1)" if archive.nil?
+          return "archive to #{archive}" if dry_run?
+
+          "archive #{archive} (sha256 #{archive_sha256})"
+        end
+
+        def nothing_text
+          where = "above the current boundary (##{n(through)})"
+          return "no checkpoint old enough #{where}" unless reason == :at_or_below
+
+          "the ledger is already purged through that sequence #{where}"
+        end
+
+        def refusal
+          template = REFUSALS.fetch(reason)
+          return template unless template.include?("%s")
+
+          format(template, *Array(detail))
+        end
+
+        def n(value)
+          Report.number(value.to_i)
+        end
+      end
+    end
+  end
+end

data/lib/reeve/audit/chain/retention/records.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Audit
+    class Chain
+      # The ledger's purges (specs/005), as verification and the purge read them.
+      module Retention
+        # Every retention record, oldest first, in one query. None for a ledger never purged,
+        # or one whose table has not been migrated: it verifies exactly as before.
+        module Records
+          module_function
+
+          def read(entry_class:)
+            present = entry_class.connection_pool.with_connection do |connection|
+              connection.table_exists?(RetentionRecord.table_name)
+            end
+            present ? RetentionRecord.uncached { RetentionRecord.order(:purge_number).to_a } : []
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Audit
+    class Chain
+      # What `bin/rails reeve:rotate_ledger_key` did, or why it did nothing (specs/003 FR-006,
+      # FR-009, contracts/key-rotation.md). A value, so a deploy script can act on it without
+      # reading the text. Names keys by fingerprint only, never by value (FR-007).
+      #
+      #   :rotated  — opened `epoch` with the configured key, from `first_sequence`
+      #   :current  — the configured key opened the latest epoch already; nothing written
+      #   :refused  — nothing written; `reason` is :no_key, :key_reused or :outgoing_key_missing
+      class Rotation
+        PREFIX = "reeve ledger key:"
+
+        FIELDS = %i[status reason epoch key_id first_sequence previous_epoch previous_key_id
+                    warnings].freeze
+
+        attr_reader(*FIELDS)
+
+        # Run under the chain record's lock (Chain#rotate_key!). `epochs` writes; `keyring`
+        # is this host's — the configured key and the retired ones.
+        def self.decide(epochs, keyring, head_sequence:, accept_unverifiable:)
+          all = epochs.all
+          own = all.find { |epoch| epoch[:key_id] == keyring.signing_id }
+          # `own` first: with no epochs at all, nil would equal the missing latest one.
+          return current(all, keyring) if own && all.last.equal?(own)
+          return refused(:key_reused, epoch: own[:epoch], key_id: own[:key_id]) if own
+
+          open_next(epochs, keyring, all.last, head_sequence: head_sequence,
+                                               accept_unverifiable: accept_unverifiable)
+        end
+
+        def self.refused(reason, **fields)
+          new(status: :refused, reason: reason, **fields)
+        end
+
+        def self.open_next(epochs, keyring, latest, head_sequence:, accept_unverifiable:)
+          lost = latest && keyring.for(latest[:key_id]).nil?
+          return refused(:outgoing_key_missing, **previous(latest)) if lost && !accept_unverifiable
+
+          opened = epochs.open!(keyring, first_sequence: head_sequence + 1)
+          new(status: :rotated, epoch: opened[:epoch], key_id: opened[:key_id],
+              first_sequence: opened[:first_sequence], **previous(latest),
+              warnings: lost ? [unverifiable(latest)] : [])
+        end
+
+        def self.current(all, keyring)
+          latest = all.last
+          before = all[-2]
+          lost = before && keyring.for(before[:key_id]).nil?
+          new(status: :current, epoch: latest[:epoch], key_id: latest[:key_id],
+              first_sequence: latest[:first_sequence], **previous(before),
+              warnings: lost ? [unverifiable(before)] : [])
+        end
+
+        def self.previous(epoch)
+          epoch ? { previous_epoch: epoch[:epoch], previous_key_id: epoch[:key_id] } : {}
+        end
+
+        def self.unverifiable(epoch)
+          "epoch #{epoch[:epoch]}'s key #{epoch[:key_id]} is not configured on this host, so " \
+            "its entries are unverifiable here"
+        end
+
+        private_class_method :open_next, :current, :previous, :unverifiable
+
+        def initialize(status:, warnings: [], **fields)
+          @status = status
+          @warnings = warnings.freeze
+          (FIELDS - %i[status warnings]).each do |name|
+            instance_variable_set(:"@#{name}", fields[name])
+          end
+          freeze
+        end
+
+        def rotated? = status == :rotated
+        def current? = status == :current
+        def refused? = status == :refused
+
+        def to_s
+          [first_line, *warnings.map { |warning| "warning: #{warning}" }].join("\n")
+        end
+
+        private
+
+        def first_line
+          case status
+          when :rotated then "#{PREFIX} ROTATED — #{rotated_text}"
+          when :current
+            "#{PREFIX} CURRENT — epoch #{epoch} already signs with the configured key " \
+            "#{key_id}; nothing to do"
+          else "#{PREFIX} REFUSED — #{refusal}; nothing was written"
+          end
+        end
+
+        def rotated_text
+          text = "epoch #{epoch} opened with key #{key_id} from sequence " \
+                 "#{Report.number(first_sequence)}"
+          return text if previous_epoch.nil?
+
+          previous = "epoch #{previous_epoch} (key #{previous_key_id})"
+          return "#{text}; the previous epoch was #{previous}" if warnings.any?
+
+          "#{text}; epoch #{previous_epoch} (key #{previous_key_id}) stays verifiable while " \
+            "that key is in retired_ledger_keys"
+        end
+
+        def refusal
+          case reason
+          when :no_key then "no ledger key configured (config.ledger_key)"
+          when :key_reused
+            "the configured key #{key_id} already opened epoch #{epoch}; a key opens one " \
+            "epoch only — configure a new key"
+          else
+            "epoch #{previous_epoch}'s key #{previous_key_id} is not configured on this host, " \
+            "so its entries would become unverifiable here — add it to " \
+            "config.retired_ledger_keys, or run with ACCEPT_UNVERIFIABLE=1 if that key is lost"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Audit
+    class Chain
+      # Whether the ledger has the shape this reeve writes: every chain column and, from
+      # contract 4, the epochs table (specs/003 FR-018). A table one contract behind fails
+      # with the fix named.
+      #
+      # The columns are checked before every write — ActiveRecord caches them, so that costs
+      # nothing. The epochs table is not: asking the catalog would be a query per guarded
+      # call (FR-019b), so its absence is diagnosed only once the database has refused a
+      # write that needed it.
+      class Schema
+        def initialize(entry_class)
+          @entry_class = entry_class
+        end
+
+        def require_columns!
+          missing = COLUMNS - entry_class.column_names
+          outdated!("#{entry_class.table_name} is missing #{missing.join(', ')}") if missing.any?
+        end
+
+        # Runs the write; if the database refuses it, names a missing epochs table as the
+        # cause. Recorder builds a Chain per write, so asking up front would be a catalog
+        # query per guarded call.
+        def explaining
+          yield
+        rescue ActiveRecord::StatementInvalid => e
+          explain!(e)
+        end
+
+        # Re-raises `error` unless the epochs table is what the ledger lacks. A ledger with no
+        # entries table at all is not an older contract but a missing ledger, and keeps the
+        # database's own error.
+        def explain!(error)
+          missing = entry_class.connection_pool.with_connection do |connection|
+            !connection.table_exists?(EPOCHS_TABLE) &&
+              connection.table_exists?(entry_class.table_name)
+          end
+          raise error unless missing
+
+          outdated!("there is no #{EPOCHS_TABLE} table")
+        end
+
+        private
+
+        attr_reader :entry_class
+
+        def outdated!(problem)
+          raise ConfigurationError,
+                "#{problem}: 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`."
+        end
+      end
+    end
+  end
+end

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

@@ -15,13 +15,33 @@ module Reeve
         # `sequence` is an Integer or a Range (a gap), or nil for a break that has no
         # position; an unchained row has none and is named by `invocation_id` instead.
         # `key_id` is set for unknown_key: the fingerprint of the key the verifier lacked.
-        Break = Struct.new(:kind, :sequence, :detail, :invocation_id, :key_id, keyword_init: true)
+        # `epoch` is set for a break about a key epoch's record (specs/003), whose sequence is nil.
+        # `checkpoint` is the head sequence of the checkpoint a break is about (specs/004); such a
+        # break has no sequence of its own.
+        # `retention` is the number of the retention record a break is about (specs/005).
+        Break = Struct.new(:kind, :sequence, :detail, :invocation_id, :key_id, :epoch, :checkpoint,
+                           :retention, keyword_init: true)
+
+        # One key epoch as verification found it (specs/003 FR-013). `entry_count` counts the
+        # walked rows that named it; `status` is :verified, :key_not_configured or :altered.
+        EpochSummary = Struct.new(:epoch, :key_id, :first_sequence, :entry_count, :status,
+                                  keyword_init: true) do
+          def as_json(*)
+            { "epoch" => epoch, "key_id" => key_id, "first_sequence" => first_sequence,
+              "entries" => entry_count, "status" => status.to_s }
+          end
+        end
+
+        EPOCH_STATUSES = %i[verified key_not_configured altered].freeze
 
         DEFAULT_LIMIT = 100
 
         KINDS = %i[
           digest_mismatch missing duplicate unchained head_mismatch beyond_head
           genesis_altered chain_record_missing unknown_key
+          epoch_missing epoch_mismatch epoch_altered
+          checkpoint_not_reached checkpoint_mismatch checkpoint_altered
+          retention_altered
         ].freeze
 
         # The status rules (data-model), for a verification that had a key and found a
@@ -38,11 +58,15 @@ module Reeve
 
         attr_reader :status, :covered, :breaks, :head_at_start, :head_at_end,
                     :uncovered_now, :uncovered_at_genesis, :unchained_now, :unchained_at_genesis,
-                    :reason
+                    :reason, :epochs, :before_first_epoch,
+                    :checkpoints, :anchored_at, :beyond_anchor, :walked_from,
+                    :retention, :awaiting_purge
 
         def initialize(status:, covered: nil, breaks: [], head_at_start: nil, head_at_end: nil,
                        uncovered_now: 0, uncovered_at_genesis: nil, unchained_now: 0,
-                       unchained_at_genesis: nil, reason: nil)
+                       unchained_at_genesis: nil, reason: nil, epochs: [], before_first_epoch: nil,
+                       checkpoints: [], anchored_at: nil, beyond_anchor: nil, walked_from: nil,
+                       retention: nil, awaiting_purge: 0)
           raise ArgumentError, "unknown status #{status.inspect}" unless STATUSES.include?(status)
 
           @status = status
@@ -55,12 +79,18 @@ module Reeve
           @unchained_now = unchained_now
           @unchained_at_genesis = unchained_at_genesis
           @reason = reason
+          @epochs = epochs.freeze
+          @before_first_epoch = before_first_epoch
+          @checkpoints = checkpoints.freeze
+          @anchored_at = anchored_at
+          @beyond_anchor = beyond_anchor
+          @walked_from = walked_from
+          @retention = retention
+          @awaiting_purge = awaiting_purge
           freeze
         end
 
-        def intact?
-          status == :intact
-        end
+        def intact? = status == :intact
 
         # Never capped, whatever the display does with the list.
         def totals
@@ -86,18 +116,31 @@ module Reeve
             "uncovered_now" => uncovered_now, "uncovered_at_genesis" => uncovered_at_genesis,
             "unchained_now" => unchained_now, "unchained_at_genesis" => unchained_at_genesis,
             "unverifiable_count" => unverifiable_count,
-            "totals" => totals.transform_keys(&:to_s), "reason" => reason&.to_s,
-            "breaks" => breaks.map { |b| break_json(b) }
-          }
+            "totals" => totals.transform_keys(&:to_s), "reason" => reason&.to_s
+          }.merge(listing_json)
         end
 
         private
 
+        def listing_json
+          { "breaks" => breaks.map { |b| break_json(b) }, "epochs" => epochs.map(&:as_json),
+            "before_first_epoch" => before_first_epoch, "checkpoints" => checkpoints.map(&:as_json),
+            "anchored_at" => point_json(anchored_at), "beyond_anchor" => beyond_anchor,
+            "walked_from" => point_json(walked_from), "retention" => retention&.as_json,
+            "awaiting_purge" => awaiting_purge }
+        end
+
+        def point_json(checkpoint)
+          checkpoint && { "head_sequence" => checkpoint.head_sequence,
+                          "made_at" => checkpoint.made_at }
+        end
+
         def break_json(found)
           {
             "kind" => found.kind.to_s, "sequence" => range_json(found.sequence),
             "detail" => found.detail, "invocation_id" => found.invocation_id,
-            "key_id" => found.key_id
+            "key_id" => found.key_id, "epoch" => found.epoch, "checkpoint" => found.checkpoint,
+            "retention" => found.retention
           }
         end
 

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

@@ -23,12 +23,16 @@ 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)
+        # `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,31 +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 = []
-          walk = walk(record)
+          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)
-
-          result(record, head_at_end, walk.last_sequence)
+          epochs.check!(record, head_at_end || record, report: method(:add))
+          head_at_end
         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))
-              .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.
@@ -121,15 +164,20 @@ 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, 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,
+                                                     checkpoint: checkpoint, retention: retention)
         end
 
-        def result(record, head_at_end, last_sequence)
+        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,
             unchained_now: count_unchained, unchained_at_genesis: record&.pre_chain_unchained_count
@@ -138,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

@@ -20,13 +20,20 @@ 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).
+        #
+        # `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
-          @expected = 1
-          @last_sequence = 0
+          @epochs = epochs
+          @start = start
+          @expected = start + 1
+          @last_sequence = start
+          @last_digest = start.positive? ? link : nil
           @link = link
           @verify_first_link = !link.nil?
         end
@@ -39,7 +46,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 +78,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 +99,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
@@ -110,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])