reeve 0.4.0 → 0.6.0

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

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Audit
+    class Chain
+      # Checks the chain and reports every place it no longer holds (specs/002 FR-012–FR-015,
+      # research R6).
+      #
+      # The chain record is read first; its head is where the walk (Walk) stops. After the
+      # walk the record is checked against what was found — the genesis against its digest,
+      # the head against the last row — and the head is read again. Rows between the two
+      # reads are writes that committed during the walk: legitimate, and left for the next
+      # run. A row above the second read cannot be legitimate, because reeve commits a row
+      # and its head move together, so it is reported. Without that second read, a row
+      # forged past the head would never be examined by any run.
+      #
+      # == What it cannot say
+      #
+      # A failing digest means the row's content, its position or its predecessor changed;
+      # which one is not knowable from the digest, and the report does not guess. Rows
+      # written before the chain began are counted, never verified.
+      class Verifier
+        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)"
+
+        def initialize(entry_class:, keyring:, batch_size: BATCH_SIZE)
+          @entry_class = entry_class
+          @keyring = keyring
+          @batch_size = batch_size
+        end
+
+        def call
+          return unwalked(:unverifiable, :no_key) if keyring.empty?
+
+          ChainRecord.require_same_database!(entry_class)
+
+          record = read_head
+          return unwalked(:no_chain) unless record&.head_sequence&.positive? || chained_rows?
+
+          verify_chain(record)
+        end
+
+        private
+
+        attr_reader :entry_class, :keyring, :batch_size, :breaks
+
+        def verify_chain(record)
+          @breaks = []
+          walk = walk(record)
+          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)
+        end
+
+        def walk(record)
+          Walk.new(entry_class: entry_class, keyring: keyring, batch_size: batch_size,
+                   link: record&.genesis_digest, report: method(:add))
+              .call(record&.head_sequence)
+        end
+
+        # A seam as well as a read: the specs wrap it to land a write mid-walk.
+        def read_head
+          ChainRecord.uncached { ChainRecord.find_by(name: ChainRecord::LEDGER) }
+        end
+
+        def check_record(record, walk)
+          return add(:chain_record_missing, nil, RECORD_MISSING) if record.nil?
+
+          check_genesis(record)
+          head = record.head_sequence
+          last_digest = walk.last_sequence.zero? ? record.genesis_digest : walk.last_digest
+          return if walk.last_sequence == head && last_digest == record.head_digest
+
+          add(:head_mismatch, head,
+              "the head is at #{head}, the last chained row found is #{walk.last_sequence}")
+        end
+
+        def check_genesis(record)
+          key_id = record.genesis_key_id
+          secret = keyring.for(key_id)
+          if secret.nil?
+            return add(:unknown_key, 0, "the genesis is signed by key #{key_id}", nil, key_id)
+          end
+          return if Canonical.genesis_digest(secret, record) == record.genesis_digest
+
+          add(:genesis_altered, 0, "the genesis does not match its digest")
+        end
+
+        def check_beyond_head(record)
+          return if record.nil?
+
+          candidates = entry_class.where("chain_sequence > ?", record.head_sequence)
+                                  .order(:chain_sequence).pluck(:chain_sequence)
+          return if candidates.empty?
+
+          # Read the head once more, after the search. A row committed between the last read
+          # and the search moved the head with it, so the head now covers it; a row above
+          # this read cannot have been written by reeve.
+          head = read_head&.head_sequence || record.head_sequence
+          detail = "numbered past the head (#{Report.number(head)} at the end of the walk); " \
+                   "reeve did not write it"
+          candidates.select { |sequence| sequence > head }
+                    .each { |sequence| add(:beyond_head, sequence, detail) }
+        end
+
+        # Contract-3 rows with no digest, beyond the number that already existed when the
+        # chain began (research R5). Which ones are new is known only by clock, and the
+        # detail says so.
+        def check_unchained(record)
+          return if count_unchained <= (record ? record.pre_chain_unchained_count : 0)
+
+          scope = entry_class.where(UNCHAINED)
+          scope = scope.where("occurred_at > ?", record.genesis_at) if record
+          scope.order(:occurred_at).pluck(:invocation_id).each do |invocation_id|
+            add(:unchained, nil, UNCHAINED_ROW, invocation_id)
+          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)
+        end
+
+        def result(record, head_at_end, last_sequence)
+          Verification.new(
+            status: Verification.status_for(breaks), breaks: breaks,
+            covered: covered(record, last_sequence),
+            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
+          )
+        end
+
+        def covered(record, last_sequence)
+          last = record ? record.head_sequence : last_sequence
+          last.positive? ? 1..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)
+        end
+
+        def chained_rows?
+          entry_class.where.not(chain_sequence: nil).exists?
+        end
+
+        def count_uncovered = (@count_uncovered ||= entry_class.where("contract_version < 3").count)
+
+        def count_unchained = (@count_unchained ||= entry_class.where(UNCHAINED).count)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Audit
+    class Chain
+      # The verifier's row-by-row pass (research R6): every chained row up to a sequence, in
+      # order, a batch at a time.
+      #
+      # Each row's digest is recomputed against its predecessor's *recorded* digest, not a
+      # recomputed one, so one edited row is one break rather than a cascade to the end of
+      # the ledger. Gaps and repeated sequences are reported where they occur.
+      #
+      # Keyset pagination on (chain_sequence, id), never OFFSET, and never inside a
+      # transaction: memory stays flat whatever the ledger's size, and no writer waits.
+      class Walk
+        MISMATCH = "does not verify at its position — its content, its sequence number or " \
+                   "its predecessor changed"
+
+        attr_reader :last_sequence, :last_digest
+
+        # `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:)
+          @entry_class = entry_class
+          @keyring = keyring
+          @batch_size = batch_size
+          @report = report
+          @expected = 1
+          @last_sequence = 0
+          @link = link
+          @verify_first_link = !link.nil?
+        end
+
+        # Walks up to `limit` (the head read at the start), or every chained row if nil.
+        def call(limit)
+          each_chained(limit) { |entry| visit(entry) }
+          self
+        end
+
+        private
+
+        attr_reader :entry_class, :keyring, :batch_size
+
+        def visit(entry)
+          sequence = entry.chain_sequence
+          return revisit(entry) if sequence == @last_sequence
+
+          report_gap(@expected..(sequence - 1)) if sequence > @expected
+          verify(entry, @link)
+          advance(entry)
+        end
+
+        def report_gap(range)
+          count = range.size
+          @report.call(:missing, range, "#{count} #{count == 1 ? 'entry' : 'entries'} not found")
+        end
+
+        # A second row claiming the sequence just seen: reported, and checked against the
+        # same predecessor the first one was.
+        def revisit(entry)
+          @report.call(:duplicate, entry.chain_sequence)
+          verify(entry, @previous_link)
+        end
+
+        def advance(entry)
+          @previous_link = @link
+          @link = entry.chain_digest
+          @last_sequence = entry.chain_sequence
+          @last_digest = entry.chain_digest
+          @expected = entry.chain_sequence + 1
+        end
+
+        def verify(entry, previous)
+          # 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
+
+          key_id = entry.chain_key_id
+          sequence = entry.chain_sequence
+          secret = keyring.for(key_id)
+          if secret.nil?
+            return @report.call(:unknown_key, sequence, "signed by key #{key_id}", nil, key_id)
+          end
+
+          expected = Canonical.entry_digest(secret, entry, previous_digest: previous)
+          @report.call(:digest_mismatch, sequence, MISMATCH) unless expected == entry.chain_digest
+        rescue ArgumentError => e
+          @report.call(:digest_mismatch, entry.chain_sequence, e.message)
+        end
+
+        def each_chained(limit, &block)
+          after = nil
+          loop do
+            batch = batch_after(after, limit)
+            batch.each(&block)
+            break if batch.size < batch_size
+
+            after = [batch.last.chain_sequence, batch.last.id]
+          end
+        end
+
+        def batch_after(after, limit)
+          entry_class.uncached { batch_scope(after, limit).to_a }
+        end
+
+        # Resumes after (sequence, id). The `>=` is what the index can use; the OR beneath it
+        # only breaks ties between rows sharing that sequence. Written as the OR alone, the
+        # condition is the same set of rows, but PostgreSQL applied it as a filter and scanned
+        # every batch from the first row: the walk was quadratic, and a million rows took 331 s
+        # 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 <= ?", limit) if limit
+          if after
+            scope = scope.where("chain_sequence >= ?", after[0])
+                         .where("chain_sequence > ? OR id > ?", after[0], after[1])
+          end
+          scope.order(:chain_sequence, :id).limit(batch_size)
+        end
+      end
+    end
+  end
+end

data/lib/reeve/audit/chain.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Audit
+    # The ledger's chain (specs/002): every row reeve writes is linked to the one before it
+    # by a keyed digest, so a row changed, removed or reordered outside reeve is reported by
+    # verification.
+    #
+    #   Reeve::Audit::Chain.new(entry_class: Reeve::Audit::Entry).append!(row)   # write
+    #   Reeve::Audit::Chain.verify                                               # check
+    #
+    # `append!` is the only door a chained row comes through. Recorder and IsolatedRecorder
+    # use it; a host with its own recorder uses it too (FR-007), or its rows are reported as
+    # unchained.
+    #
+    # == How a write is serialized (research R3)
+    #
+    #   UPDATE the chain record's head_sequence by one   -- the lock, taken first
+    #   SELECT the new head_sequence and the old head_digest
+    #   INSERT the row with its sequence, key id and digest
+    #   UPDATE the head_digest to the row's digest
+    #
+    # all inside one savepoint on the entry class's own connection. The first statement is
+    # a write, so on PostgreSQL and MySQL it takes the row lock and on SQLite the database
+    # write lock: every writer queues at the same point with the same SQL. Reading first
+    # would be refused outright by SQLite (a shared lock cannot be upgraded while another
+    # writer waits), and SELECT ... FOR UPDATE is ignored there.
+    #
+    # Because the row and the head move commit together, a rolled-back write consumes no
+    # sequence — and a committed row can never sit beyond a committed head, which is what
+    # lets the verifier call such a row forged.
+    #
+    # == The cost, stated
+    #
+    # Under the default Recorder inside a transaction the host opened, the chain record
+    # stays locked until that transaction ends, so every other guarded call waits behind it.
+    # IsolatedRecorder holds it for one insert.
+    class Chain
+      TABLE = "reeve_audit_chains"
+
+      COLUMNS = %w[chain_sequence chain_key_id chain_digest].freeze
+
+      # 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
+      # genesis (the baseline it records) and the verifier (the count it compares), because
+      # the baseline means something only while the two count the same rows. It keys on the
+      # missing sequence, not the missing digest: a forged row with a digest and no sequence
+      # once sat outside every count.
+      UNCHAINED = "contract_version >= 3 AND chain_sequence IS NULL"
+
+      # 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
+      end
+
+      def initialize(entry_class: Entry, keyring: nil)
+        @entry_class = entry_class
+        @keyring = keyring
+      end
+
+      # Writes `row` as the next link and returns the entry. The row carries every column
+      # but the three chain ones; it is normalized here (research R2).
+      #
+      # Raises LedgerKeyError with no signing key, and whatever the database raises if the
+      # write fails. A replayed invocation_id returns the existing entry and consumes
+      # nothing. What a failure means for the caller — fail the call or warn — is the
+      # caller's decision, not this method's.
+      def append!(row)
+        require_columns!
+        signer = keyring
+        raise LedgerKeyError unless signer.signing?
+
+        normalized = normalizer.call(row)
+        with_connection do |connection|
+          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) }
+          end
+        end
+      end
+
+      # Writes `row` at its contract version with no chain columns, around the chain: no lock,
+      # no sequence. For a caller that has decided to keep running without a key (Recorder
+      # under audit_failure_mode :warn). Verification reports such a row as unchained.
+      def append_unchained!(row)
+        require_columns!
+        normalized = normalizer.call(row)
+        with_connection do
+          insert_once(normalized) do
+            entry_class.transaction(requires_new: true) { entry_class.create!(normalized) }
+          end
+        end
+      end
+
+      private
+
+      attr_reader :entry_class
+
+      def keyring
+        @keyring || Keyring.from(Reeve.config)
+      end
+
+      def normalizer
+        @normalizer ||= Chain::Normalizer.new(entry_class)
+      end
+
+      # The digest is computed over the model instance, not the hash: ActiveRecord fills in
+      # 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.
+      def link!(head, normalized, signer)
+        sequence, previous = head.advance!
+        entry = entry_class.new(normalized.merge(chain_sequence: sequence,
+                                                 chain_key_id: signer.signing_id))
+        entry.chain_digest = Canonical.entry_digest(signer.signing_secret, entry,
+                                                    previous_digest: previous)
+        entry.save!
+        head.point_at!(entry.chain_digest)
+        entry
+      end
+
+      # A replayed invocation_id returns the row already written, whether the pre-check sees
+      # it or the insert collides with it.
+      def insert_once(normalized)
+        existing = replayed(normalized)
+        return existing if existing
+
+        yield
+      rescue ActiveRecord::RecordNotUnique, ActiveRecord::RecordInvalid => e
+        replayed(normalized) || raise(e)
+      end
+
+      # 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?
+
+        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`."
+      end
+
+      def replayed(normalized)
+        id = normalized[:invocation_id]
+        id && entry_class.find_by(invocation_id: id)
+      end
+
+      # Checked out for one append and returned, never leased to the thread: from Rails 7.2
+      # `entry_class.connection` pins a connection to the thread for good, which would undo
+      # IsolatedRecorder's promise to hold none between writes. ConnectionPool#with_connection
+      # exists on every Rails this gem supports, and reuses a connection the thread already
+      # holds — so the transaction and the INSERT run on the same one.
+      #
+      # The connection is passed down as an argument, never kept on the instance. A Chain
+      # holds no per-call state, so one instance can be shared by every thread that writes:
+      # an earlier version stored it in an instance variable, and two threads appending
+      # through one Chain drove a single PostgreSQL connection at once.
+      def with_connection(&block)
+        entry_class.connection_pool.with_connection(&block)
+      end
+    end
+  end
+end

data/lib/reeve/audit/chain_record.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Audit
+    # The ledger's chain record: one row holding the genesis and the head (specs/002
+    # data-model "reeve_audit_chains").
+    #
+    # The genesis is link 0 — when the chain started, how many rows preceded it, and the
+    # digest the first chained row links to. It is written once, with the first chained
+    # row, and the model refuses to change it afterwards. The head is the latest sequence
+    # and digest; Chain advances it with SQL of its own, inside the same transaction as
+    # the row it points at, so it is never updated through this model.
+    #
+    # As with Entry, this protects against the library, not against raw SQL. A role that
+    # can UPDATE this table can rewind the head; that is one of the stated limits of the
+    # chain, and the verifier's job is to report what it can.
+    class ChainRecord < ActiveRecord::Base
+      self.table_name = "reeve_audit_chains"
+
+      # Always this. A name rather than a primary key, because ids change on restore.
+      LEDGER = "ledger"
+
+      GENESIS_COLUMNS = %w[
+        name genesis_at pre_chain_count pre_chain_unchained_count genesis_key_id genesis_digest
+      ].freeze
+
+      attr_readonly(*GENESIS_COLUMNS)
+
+      # attr_readonly ignores the change silently on Rails 7.0 and raises from 7.1; this
+      # makes every version refuse it out loud.
+      before_update do
+        changed = changed_attribute_names_to_save & GENESIS_COLUMNS
+        unless changed.empty?
+          raise ActiveRecord::ReadOnlyRecord,
+                "the genesis of the ledger chain is written once; refused to change " \
+                "#{changed.join(', ')}"
+        end
+      end
+
+      before_destroy { throw :abort }
+
+      def self.ledger
+        find_by(name: LEDGER)
+      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.
+      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
+
+        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."
+      end
+    end
+  end
+end

data/lib/reeve/audit/isolated_recorder.rb

@@ -34,6 +34,11 @@ module Reeve
     # and it also survives a rollback of an invocation the host *meant* to undo entirely.
     # A ledger of what was attempted is the intended reading of Constitution II, but it is
     # a choice, and it should be made rather than inherited.
+    #
+    # It is also the answer to the chain's one real cost (specs/002). Every chained write
+    # locks the ledger's chain record; under Recorder inside a host transaction that lock is
+    # held until the host commits, so every other guarded call waits behind it. Here the
+    # chain record is written on this connection too, and the lock is held for one insert.
     class IsolatedRecorder < Recorder
       UNSUPPORTED_ADAPTERS = %w[sqlite sqlite3].freeze
 

data/lib/reeve/audit/recorder.rb

@@ -10,9 +10,10 @@ module Reeve
     # ActiveJob. An asynchronous ledger cannot be relied on and would make FR-012
     # unenforceable.
     #
-    # The insert runs in `requires_new: true`, which is what makes the trace survive a
-    # tool body that opens a transaction and rolls it back (R5) — the case this was built
-    # for, and the one it does solve.
+    # Every row goes through Chain#append! (specs/002), which links it to the row before it
+    # and runs the insert in `requires_new: true` — what makes the trace survive a tool body
+    # that opens a transaction and rolls it back (R5), the case this was built for and the
+    # one it does solve.
     #
     # What it does **not** do, corrected after review: `requires_new` is a SAVEPOINT, not
     # an independent transaction. If the host has already opened a transaction *around*
@@ -54,20 +55,28 @@ module Reeve
 
       # Returns the entry. Raises if the row could not be written, so the envelope can
       # fail the invocation.
+      #
+      # A replayed invocation is the same invocation: one row per invocation_id means a
+      # retry returns the existing row and never writes a second (contracts/audit-entry.md).
+      # Chain#append! owns that, because it must also consume no sequence number.
+      #
+      # With no ledger key (specs/002 FR-010): under :fail, Chain raises LedgerKeyError and
+      # the envelope fails the call like any other ledger failure. Under :warn the row is
+      # still written, at contract 3 and unchained, and the log says so every time —
+      # :warn keeps calls running, it does not drop traces, and verification reports the
+      # row as unchained rather than letting it pass unseen.
       def record(attributes)
         row = row_for(attributes)
         warn_about_enclosing_transaction(row[:invocation_id])
 
-        entry_class.transaction(requires_new: true) do
-          entry_class.create!(row)
-        end
-      rescue ActiveRecord::RecordNotUnique, ActiveRecord::RecordInvalid => e
-        # A replayed invocation is the same invocation. One row per invocation_id means
-        # a retry is a no-op insert, never a second row (contracts/audit-entry.md).
-        existing = entry_class.find_by(invocation_id: row[:invocation_id])
-        raise e if existing.nil?
+        keyring = Chain::Keyring.from(config)
+        chain = Chain.new(entry_class: entry_class, keyring: keyring)
+        return chain.append!(row) if keyring.signing? || config.audit_failure_mode == :fail
 
-        existing
+        warn("reeve: invocation #{row[:invocation_id]} was recorded unchained: no ledger key is " \
+             "configured and audit_failure_mode is :warn. Verification will report the row as " \
+             "unchained. Set config.ledger_key to chain the ledger.")
+        chain.append_unchained!(row)
       end
 
       private
@@ -78,6 +87,11 @@ module Reeve
         @config || Reeve.config
       end
 
+      def warn(message)
+        logger = config.logger
+        logger ? logger.warn(message) : Kernel.warn(message)
+      end
+
       def row_for(attributes)
         ids, count, truncated = identifiers(attributes)
 
@@ -163,13 +177,12 @@ module Reeve
       def warn_about_enclosing_transaction(invocation_id)
         return unless enclosing_transaction?
 
-        message = "reeve: invocation #{invocation_id} was recorded inside a transaction " \
-                  "the host opened around it, so the ledger row will be rolled back with " \
-                  "it. Set Reeve.config.audit_recorder = Reeve::Audit::IsolatedRecorder " \
-                  "to write on a connection the transaction cannot reach (needs a " \
-                  "database with concurrent writers; not SQLite)."
-        logger = config.logger
-        logger ? logger.warn(message) : Kernel.warn(message)
+        warn("reeve: invocation #{invocation_id} was recorded inside a transaction " \
+             "the host opened around it, so the ledger row will be rolled back with " \
+             "it, and the ledger chain stays locked until it ends, so every other " \
+             "guarded call waits behind it. Set Reeve.config.audit_recorder = " \
+             "Reeve::Audit::IsolatedRecorder to write on a connection the transaction " \
+             "cannot reach (needs a database with concurrent writers; not SQLite).")
       end
 
       def enclosing_transaction?

data/lib/reeve/audit.rb

@@ -44,9 +44,14 @@ module Reeve
   #   documents the `GRANT INSERT, SELECT` that enforces the rest where it can actually be
   #   enforced, and the gem makes no stronger claim than that.
   # * No retention, rotation or archival yet — the table is host-owned and the host's
-  #   existing policies apply.
-  # * No cryptographic chaining or tamper-evidence yet. If that lands it arrives as a
-  #   nullable column, which the audit-entry contract's versioning already permits.
+  #   existing policies apply. Deleting rows breaks the chain, by design.
+  # * Tamper-evidence, not tamper-proofing. Every row is chained to the one before it
+  #   (Reeve::Audit::Chain, contract 3), so a change made outside the library is reported
+  #   by verification — after the fact; it prevents nothing. It does not detect a change
+  #   made by someone holding the ledger key, the newest rows deleted by a role that can
+  #   also rewind the chain record's head, the whole ledger deleted, or anything about
+  #   rows written before contract 3. specs/001-guardrails-core/contracts/audit-entry.md,
+  #   guarantee 9, is the authoritative statement.
   #
   # ("yet" rather than "in v1": the gem version and the audit-entry contract version are
   # different numbers that move independently, and writing v1 for one of them read as the
@@ -57,11 +62,16 @@ module Reeve
     # 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.
     #
+    # 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
+    # it is a row written unchained, which verification reports, where on an older row it
+    # only means the row predates chaining.
+    #
     # 2 — `metadata` carries the transport detail the caller passed. Through version 1 it
     # 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 = 2
+    CONTRACT_VERSION = 3
 
     TABLE_NAME = "reeve_audit_entries"
 
@@ -94,5 +104,15 @@ require_relative "audit/entry"
 require_relative "audit/recorder"
 require_relative "audit/isolated_recorder"
 require_relative "audit/query"
+require_relative "audit/chain/keyring"
+require_relative "audit/chain/normalizer"
+require_relative "audit/chain/canonical"
+require_relative "audit/chain_record"
+require_relative "audit/chain/verification"
+require_relative "audit/chain/report"
+require_relative "audit/chain/head"
+require_relative "audit/chain/walk"
+require_relative "audit/chain/verifier"
+require_relative "audit/chain"
 
 Reeve::Audit.install!