reeve 0.5.0 → 0.7.0

data/lib/generators/reeve/upgrade/templates/add_ledger_chain_to_reeve_audit_entries.rb.tt

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# Audit-entry contract 2 → 3. Generated by `bin/rails generate reeve:upgrade`.
+#
+# Chains every row reeve writes from here on to the one before it with a keyed digest, so a
+# row changed, removed or reordered outside reeve is reported by
+# `bin/rails reeve:verify_ledger`.
+#
+# Rows already in the table are not touched: there is no honest digest to give a row
+# nobody was there to sign, and nothing is backfilled into an append-only table. They are
+# reported as "not covered" from now on — exactly as trustworthy as they were before this
+# migration, and no more. The three columns are nullable for that reason.
+#
+# The chain needs a key, held outside the database. Add this to
+# config/initializers/reeve.rb, or every guarded call fails closed after you migrate:
+#
+#   config.ledger_key = Rails.application.key_generator.generate_key("reeve audit ledger", 32)
+#
+# The chain record's head moves on every write, so the role your application connects as
+# needs UPDATE on reeve_audit_chains (the ledger itself stays INSERT, SELECT):
+#
+#   GRANT INSERT, SELECT, UPDATE ON reeve_audit_chains TO app_role;
+#
+# A role holding that UPDATE can rewind the head, and a rewound head hides the deletion of
+# the newest rows. Tamper-evidence detects a change after the fact; the grants are what
+# prevent one.
+#
+# On a very large ledger, the unique index below scans the table once. On PostgreSQL that
+# scan blocks writes for its duration; to avoid it, add `disable_ddl_transaction!` to this
+# class and `algorithm: :concurrently` to the add_index call.
+class AddLedgerChainToReeveAuditEntries < ActiveRecord::Migration[7.0]
+  def change
+    add_column :reeve_audit_entries, :chain_sequence, :bigint
+    add_column :reeve_audit_entries, :chain_key_id,   :string, limit: 16
+    add_column :reeve_audit_entries, :chain_digest,   :string, limit: 64
+    add_index  :reeve_audit_entries, :chain_sequence, unique: true
+
+    create_table :reeve_audit_chains do |t|
+      t.string   :name,                      null: false
+      t.datetime :genesis_at,                null: false, precision: 6
+      t.bigint   :pre_chain_count,           null: false
+      t.bigint   :pre_chain_unchained_count, null: false
+      t.string   :genesis_key_id,            null: false, limit: 16
+      t.string   :genesis_digest,            null: false, limit: 64
+      t.bigint   :head_sequence,             null: false
+      t.string   :head_digest,               null: false, limit: 64
+    end
+
+    add_index :reeve_audit_chains, :name, unique: true
+  end
+end

data/lib/generators/reeve/upgrade/upgrade_generator.rb

@@ -2,6 +2,7 @@
 
 require "rails/generators"
 require "rails/generators/active_record"
+require_relative "upgrade_notes"
 
 module Reeve
   module Generators
@@ -33,15 +34,35 @@ module Reeve
       # contracts/audit-entry.md, which exists so that stays hypothetical: an append-only
       # ledger cannot be backfilled, so a column that is not additive has no honest value
       # to give the rows already written.
+      # `creates` names any table a step builds. A step is applied only when every column it
+      # adds and every table it creates exist: a ledger with one half and not the other is
+      # half-migrated, and calling it current would leave the host with no way forward.
       STEPS = [
         {
           contract: 2,
           adds: %w[contract_version],
+          creates: [],
           template: "add_contract_version_to_reeve_audit_entries.rb.tt",
           destination: "add_contract_version_to_reeve_audit_entries.rb"
+        },
+        {
+          contract: 3,
+          adds: %w[chain_sequence chain_key_id chain_digest],
+          creates: %w[reeve_audit_chains],
+          template: "add_ledger_chain_to_reeve_audit_entries.rb.tt",
+          destination: "add_ledger_chain_to_reeve_audit_entries.rb"
+        },
+        {
+          contract: 4,
+          adds: %w[chain_epoch],
+          creates: %w[reeve_audit_chain_epochs],
+          template: "add_key_epochs_to_reeve_audit_entries.rb.tt",
+          destination: "add_key_epochs_to_reeve_audit_entries.rb"
         }
       ].freeze
 
+      KEY_LINE = UpgradeNotes::KEY_LINE
+
       source_root File.expand_path("templates", __dir__)
 
       desc "Brings an existing reeve audit ledger up to the current audit-entry contract."
@@ -93,7 +114,7 @@ module Reeve
       end
 
       def pending_message
-        <<~NEXT
+        message = <<~NEXT
 
           #{@emitted.size} migration#{'s' if @emitted.size != 1} written, taking the ledger
           to audit-entry contract #{@emitted.last[:contract]}. Run:
@@ -103,13 +124,15 @@ module Reeve
           Existing rows are stamped with the contract they were actually written under,
           not with the current one.
         NEXT
+        message + UpgradeNotes.for(@emitted.map { |step| step[:contract] })
       end
 
       # Asked of the table rather than of a version the host recorded: the table is the
       # thing being changed, and it is the only party that cannot be out of date about
       # itself.
       def applied?(step)
-        (step[:adds] - existing_columns).empty?
+        (step[:adds] - existing_columns).empty? &&
+          step[:creates].all? { |table| connection.table_exists?(table) }
       end
 
       def existing_columns

data/lib/generators/reeve/upgrade/upgrade_notes.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Generators
+    # What `reeve:upgrade` tells the host after writing a step whose contract changes more
+    # than the table. The host is reading this output at exactly the moment they need it.
+    module UpgradeNotes
+      KEY_LINE = "config.ledger_key = " \
+                 'Rails.application.key_generator.generate_key("reeve audit ledger", 32)'
+
+      # Contract 3 changes what the application must configure, not only the table: without
+      # a key, every guarded call fails closed once the migration runs.
+      CHAIN = <<~CHAIN.freeze
+
+        The ledger is now chained (contract 3). Add this line to config/initializers/reeve.rb
+        before you deploy, or every guarded call fails closed:
+
+          #{KEY_LINE}
+
+        It derives the key from secret_key_base, so rotating secret_key_base rotates the
+        ledger key: keep the old derived key in config.retired_ledger_keys, or entries it
+        signed become unverifiable. A dedicated key avoids that coupling.
+
+        Very large ledger on PostgreSQL? The migration builds a unique index that blocks
+        writes while it scans; the migration's header shows how to build it with
+        algorithm: :concurrently instead.
+      CHAIN
+
+      # Contract 4 changes how a rotation is done, so the host learns the command here.
+      EPOCHS = <<~EPOCHS
+
+        The ledger now records key epochs (contract 4): the first chained write opens
+        epoch 0 with the configured ledger key. To rotate the key later, set the new key
+        as config.ledger_key, keep the old one in config.retired_ledger_keys, deploy, and run:
+
+          bin/rails reeve:rotate_ledger_key
+
+        The application role needs INSERT and SELECT on reeve_audit_chain_epochs.
+      EPOCHS
+
+      BY_CONTRACT = { 3 => CHAIN, 4 => EPOCHS }.freeze
+
+      module_function
+
+      # The notes for the contracts just written, oldest first.
+      def for(contracts)
+        contracts.filter_map { |contract| BY_CONTRACT[contract] }.join
+      end
+    end
+  end
+end

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

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "json"
+require "openssl"
+
+module Reeve
+  module Audit
+    class Chain
+      # The exact text a digest is computed over (specs/002 FR-002, FR-003; research R1, R2
+      # step 2; data-model "Canonical entry").
+      #
+      # Computed once when a row is written and again, from what the database returns,
+      # when it is verified — so everything here exists to make those two readings produce
+      # identical text:
+      #
+      # * object keys sorted at every depth, so a database that reorders JSON keys
+      #   (PostgreSQL jsonb, MySQL JSON) changes nothing;
+      # * one spelling per number, so `1.0e+20` written and `100000000000000000000` read
+      #   back are the same number;
+      # * times as integer microseconds since the epoch, so neither the time zone nor the
+      #   driver's Time class matters;
+      # * strings, booleans and nil typed, so "1" and 1 never digest alike.
+      #
+      # The field list is written out rather than read from the table — a check that
+      # derives its expectation from the thing it checks checks nothing — and is keyed by
+      # contract version, so a future column joins the digest for rows written under that
+      # contract only. The tags keep an entry digest and a genesis digest from ever being
+      # interchangeable, and let a future canonical form be told apart from this one.
+      module Canonical
+        ENTRY_TAG = "reeve-ledger-entry-v1"
+        GENESIS_TAG = "reeve-ledger-genesis-v1"
+
+        EPOCH_TAG = "reeve-ledger-epoch-v1"
+
+        CONTRACT_3_FIELDS = %w[
+          chain_sequence chain_key_id contract_version
+          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
+        ].freeze
+
+        # Contract 4 (specs/003) adds the key epoch, next to the key it names.
+        ENTRY_FIELDS = {
+          3 => CONTRACT_3_FIELDS,
+          4 => CONTRACT_3_FIELDS.dup.insert(2, "chain_epoch").freeze
+        }.freeze
+
+        GENESIS_FIELDS = %w[genesis_at pre_chain_count pre_chain_unchained_count
+                            genesis_key_id].freeze
+
+        EPOCH_FIELDS = %w[epoch key_id first_sequence opened_at].freeze
+
+        TIME_FIELDS = %w[occurred_at genesis_at opened_at].freeze
+
+        module_function
+
+        def entry_digest(secret, row, previous_digest:)
+          hmac(secret, ENTRY_TAG, entry_message_body(row, previous_digest))
+        end
+
+        def genesis_digest(secret, genesis)
+          pairs = GENESIS_FIELDS.map { |field| [field, value(genesis, field)] }
+          hmac(secret, GENESIS_TAG, dump(pairs))
+        end
+
+        # An epoch record (specs/003 FR-002), linked to the epoch before it — or, for epoch 0,
+        # to the genesis — so the epochs are a chain of their own.
+        def epoch_digest(secret, epoch, previous_digest:)
+          pairs = EPOCH_FIELDS.map { |field| [field, value(epoch, field)] }
+          hmac(secret, EPOCH_TAG, dump([["previous_digest", previous_digest], *pairs]))
+        end
+
+        def entry_message_body(row, previous_digest)
+          version = value(row, "contract_version")
+          fields = ENTRY_FIELDS.fetch(version) do
+            raise ArgumentError,
+                  "there is no canonical field list for audit-entry contract " \
+                  "#{version.inspect}; only contract " \
+                  "#{ENTRY_FIELDS.keys.join(', ')} rows are chained"
+          end
+
+          pairs = fields.map { |field| [field, value(row, field)] }
+          dump([["previous_digest", previous_digest], *pairs])
+        end
+
+        def microseconds(time)
+          (time.to_r * 1_000_000).floor
+        end
+
+        def dump(value)
+          case value
+          when Array then "[#{value.map { |item| dump(item) }.join(',')}]"
+          when Hash then object(value)
+          else scalar(value)
+          end
+        end
+
+        def scalar(value)
+          case value
+          when nil, true, false then value.nil? ? "null" : value.to_s
+          when Integer, Float, BigDecimal then number(value)
+          when String, Symbol then JSON.generate(value.to_s)
+          else
+            raise ArgumentError,
+                  "#{value.class} has no canonical form; normalize it before it is digested"
+          end
+        end
+
+        def object(hash)
+          pairs = hash.map { |key, item| [key.to_s, item] }.sort_by(&:first)
+          "{#{pairs.map { |key, item| "#{JSON.generate(key)}:#{dump(item)}" }.join(',')}}"
+        end
+
+        # The shortest exact decimal: no exponent, no trailing zeros, no "-0".
+        def number(value)
+          if value.is_a?(Float) && !value.finite?
+            raise ArgumentError,
+                  "a non-finite number has no canonical form; normalize it before it is digested"
+          end
+
+          decimal = value.is_a?(Float) ? BigDecimal(value.to_s) : BigDecimal(value)
+          return "0" if decimal.zero?
+          return decimal.to_i.to_s if decimal.frac.zero?
+
+          decimal.to_s("F")
+        end
+
+        def value(row, field)
+          raw = if row.is_a?(Hash)
+                  row.key?(field) ? row[field] : row[field.to_sym]
+                else
+                  row[field]
+                end
+          TIME_FIELDS.include?(field) && !raw.nil? ? microseconds(raw) : raw
+        end
+
+        def hmac(secret, tag, body)
+          OpenSSL::HMAC.hexdigest("SHA256", secret, "#{tag}\n#{body}")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Audit
+    class Chain
+      # The key epochs as verification sees them (specs/003 FR-011): read once, then asked
+      # about every row the walk visits. Counts, as it goes, the rows that named each epoch and
+      # the rows chained before the first, for the report.
+      #
+      # A row at contract 4 names its epoch, and must carry that epoch's key and not precede
+      # its start. A contract-3 row names none and is checked exactly as 0.6.0 checked it,
+      # wherever it sits: one written by a 0.6.0 server after the first epoch opened may carry
+      # any key that server had, and a verifier without that key cannot tell it from a
+      # rewritten one — calling it tampered would report a rolling deploy as an attack.
+      class EpochRules
+        attr_reader :records, :counts, :before_first_epoch, :summaries
+
+        # Every epoch record, in one query whatever the ledger's size (FR-014). A ledger whose
+        # gem was upgraded before its table was migrated has none — and no row that could
+        # name one, since writes refuse until it is migrated (FR-018).
+        def self.read(keyring:, entry_class:)
+          present = entry_class.connection_pool.with_connection do |connection|
+            connection.table_exists?(EPOCHS_TABLE)
+          end
+          new(present ? ChainEpoch.uncached { ChainEpoch.all.to_a } : [], keyring: keyring)
+        end
+
+        # `records` are ChainEpoch rows, in any order.
+        def initialize(records, keyring:)
+          @records = records.sort_by(&:epoch).freeze
+          @keyring = keyring
+          @by_number = @records.to_h { |record| [record.epoch, record] }
+          @first_start = @records.map(&:first_sequence).min
+          @counts = Hash.new(0)
+          @before_first_epoch = 0
+          @summaries = []
+        end
+
+        # Checks the records themselves once the walk has counted their rows (EpochCheck);
+        # `head` is the chain record as read after the walk. Leaves the result in `summaries`.
+        def check!(record, head, report:)
+          @summaries = EpochCheck.new(keyring: keyring, report: report)
+                                 .call(self, genesis_digest: record&.genesis_digest, head: head)
+        end
+
+        # [kind, detail] for a row that contradicts the epoch records, or nil.
+        def judge(entry)
+          return epoch_bearing(entry) if entry.contract_version.to_i >= EPOCH_CONTRACT
+
+          @before_first_epoch += 1 if before_first?(entry.chain_sequence)
+          nil
+        end
+
+        private
+
+        attr_reader :keyring
+
+        def epoch_bearing(entry)
+          number = entry.chain_epoch
+          epoch = number && @by_number[number]
+          return [:epoch_missing, missing(number)] unless epoch
+
+          @counts[number] += 1
+          if epoch.key_id != entry.chain_key_id
+            [:epoch_mismatch,
+             "signed by key #{entry.chain_key_id}, but epoch #{number}'s key is #{epoch.key_id}"]
+          elsif entry.chain_sequence < epoch.first_sequence
+            [:epoch_mismatch,
+             "names epoch #{number}, which begins at sequence #{epoch.first_sequence}"]
+          end
+        end
+
+        # True for a row chained before any epoch began — and for every row when none has.
+        def before_first?(sequence)
+          @first_start.nil? || sequence < @first_start
+        end
+
+        def missing(number)
+          number.nil? ? "names no key epoch" : "names epoch #{number}, which has no record"
+        end
+      end
+
+      # The epoch records themselves (specs/003 FR-010): numbered 0..n, each beginning after
+      # the one before (or with it: two rotations with no write between them begin at the same
+      # sequence) and no later than one past the head, one key each, and each matching
+      # its digest — which links it to the epoch before, or, for epoch 0, to the genesis. A
+      # record whose key is not configured cannot be checked, and that is said, never passed
+      # over. Returns one Verification::EpochSummary per record; breaks go to `report`, as
+      # (kind, nil, detail, nil, key_id, epoch:) — the verifier's own `add`.
+      class EpochCheck
+        def initialize(keyring:, report:)
+          @keyring = keyring
+          @report = report
+        end
+
+        # `head` is the chain record as read after the walk — later than the epochs were
+        # read, so an epoch a rotation opened mid-run is never taken for one past the head.
+        def call(rules, genesis_digest:, head:)
+          previous = { digest: genesis_digest, first_sequence: 0, keys: [] }
+          expected = 0
+          rules.records.map do |epoch|
+            (expected...epoch.epoch).each do |gap|
+              report(:epoch_missing, gap, "epoch #{gap} has no record")
+            end
+            expected = epoch.epoch + 1
+            summary(epoch, rules.counts[epoch.epoch], check(epoch, previous, head)).tap do
+              previous = { digest: epoch.epoch_digest, first_sequence: epoch.first_sequence,
+                           keys: previous[:keys] + [epoch.key_id] }
+            end
+          end
+        end
+
+        private
+
+        attr_reader :keyring
+
+        # :altered, :key_not_configured or :verified, reporting what makes it so.
+        def check(epoch, previous, head)
+          problem = out_of_place(epoch, previous, head) || digest_problem(epoch, previous)
+          return :altered.tap { report(:epoch_altered, epoch.epoch, problem) } if problem
+          return :verified if keyring.for(epoch.key_id)
+
+          report(:unknown_key, epoch.epoch, "epoch #{epoch.epoch} is signed by key #{epoch.key_id}",
+                 epoch.key_id)
+          :key_not_configured
+        end
+
+        def report(kind, number, detail, key_id = nil)
+          @report.call(kind, nil, detail, nil, key_id, epoch: number)
+        end
+
+        def out_of_place(epoch, previous, head)
+          name = "epoch #{epoch.epoch}"
+          if epoch.epoch.positive? && epoch.first_sequence < previous[:first_sequence]
+            "#{name} begins at sequence #{epoch.first_sequence}, before the epoch before it"
+          elsif head && epoch.first_sequence > head.head_sequence + 1
+            "#{name} begins at sequence #{epoch.first_sequence}, past the head"
+          elsif previous[:keys].include?(epoch.key_id)
+            "#{name} reuses the key of an earlier epoch"
+          end
+        end
+
+        def digest_problem(epoch, previous)
+          secret = keyring.for(epoch.key_id)
+          return nil if secret.nil? || previous[:digest].nil?
+
+          expected = Canonical.epoch_digest(secret, epoch, previous_digest: previous[:digest])
+          "epoch #{epoch.epoch} does not match its digest" unless expected == epoch.epoch_digest
+        end
+
+        def summary(epoch, count, status)
+          Verification::EpochSummary.new(epoch: epoch.epoch, key_id: epoch.key_id,
+                                         first_sequence: epoch.first_sequence, entry_count: count,
+                                         status: status)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Audit
+    class Chain
+      # The key epochs, as a write sees them (specs/003 FR-001–FR-005).
+      #
+      # One instance per append or rotation, bound to the connection it runs on and used
+      # only under the chain record's lock (Head), so finding a key's epoch and opening the
+      # next one are a single step as far as any other writer can tell. The epoch record
+      # commits or rolls back with the write that opened it.
+      #
+      # A key opens one epoch, ever. A process signing with a key whose epoch is not the
+      # latest — one still on the old key during a rolling deploy — writes under that
+      # earlier epoch: a straggler, legitimate, and verified by its own key.
+      class Epochs
+        def initialize(connection:)
+          @connection = connection
+        end
+
+        # The number of the epoch `signer`'s key opened, opening the next one at `sequence`
+        # if it has none.
+        def for_signing!(signer, sequence:)
+          number_for(signer.signing_id) || open!(signer, first_sequence: sequence)[:epoch]
+        end
+
+        def number_for(key_id)
+          sql = "SELECT epoch FROM #{EPOCHS_TABLE} WHERE key_id = #{connection.quote(key_id)}"
+          value = connection.select_value(current(sql))
+          value.nil? ? nil : Integer(value)
+        end
+
+        # Every epoch, oldest first, as hashes with symbol keys.
+        def all
+          sql = "SELECT epoch, key_id, first_sequence FROM #{EPOCHS_TABLE} ORDER BY epoch"
+          connection.select_all(current(sql))
+                    .map do |row|
+                      { epoch: Integer(row["epoch"]), key_id: row["key_id"],
+                        first_sequence: Integer(row["first_sequence"]) }
+                    end
+        end
+
+        # Writes epoch `max + 1` (or 0) for `signer`'s key and returns it. Linked to the
+        # latest epoch's digest, or to the genesis for epoch 0, so the chain must have
+        # started.
+        def open!(signer, first_sequence:)
+          sql = "SELECT epoch, epoch_digest FROM #{EPOCHS_TABLE} ORDER BY epoch DESC LIMIT 1"
+          latest = connection.select_one(current(sql))
+          epoch = { epoch: latest ? Integer(latest["epoch"]) + 1 : 0, key_id: signer.signing_id,
+                    first_sequence: first_sequence, opened_at: Time.now.utc.floor(6) }
+          previous = latest ? latest["epoch_digest"] : genesis_digest
+          digest = Canonical.epoch_digest(signer.signing_secret, epoch, previous_digest: previous)
+          epoch.merge(epoch_digest: digest).tap { |values| insert(values) }
+        end
+
+        private
+
+        attr_reader :connection
+
+        def current(sql)
+          Head.current(connection, sql)
+        end
+
+        def insert(values)
+          quoted = values.values.map { |value| connection.quote(value) }
+          connection.insert("INSERT INTO #{EPOCHS_TABLE} (#{values.keys.join(', ')}) " \
+                            "VALUES (#{quoted.join(', ')})")
+        end
+
+        def genesis_digest
+          connection.select_value("SELECT genesis_digest FROM #{TABLE} " \
+                                  "WHERE name = #{connection.quote(ChainRecord::LEDGER)}")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Audit
+    class Chain
+      # The chain record's head, advanced under its lock (research R3).
+      #
+      # One instance per append, bound to the connection that append runs on; every
+      # statement here goes through that connection, so the lock, the row and the head move
+      # share one transaction and commit or roll back together.
+      #
+      #   UPDATE head_sequence by one   -- the lock, taken first
+      #   SELECT the new head_sequence and the old head_digest
+      #   ... the caller inserts the row ...
+      #   UPDATE head_digest to the row's digest
+      #
+      # Taking the lock with a write is what makes this behave the same on all three
+      # engines: SQLite cannot upgrade a read lock while another writer waits, and ignores
+      # SELECT ... FOR UPDATE.
+      class Head
+        LOCKING_READ_ADAPTERS = /mysql|trilogy/i
+
+        # A read made under the head's lock must see the latest committed rows. PostgreSQL
+        # and SQLite read them anyway; InnoDB at REPEATABLE READ serves a plain SELECT from
+        # the snapshot of the caller's transaction, which a writer that committed while this
+        # one queued for the lock is not in (code review, specs/003). A locking read is
+        # current; LOCK IN SHARE MODE is the spelling every MySQL version accepts.
+        def self.current(connection, sql)
+          connection.adapter_name.match?(LOCKING_READ_ADAPTERS) ? "#{sql} LOCK IN SHARE MODE" : sql
+        end
+
+        def initialize(connection:, entry_class:)
+          @connection = connection
+          @entry_class = entry_class
+        end
+
+        # Creates the chain record with its genesis — link 0, head 0 — unless it exists.
+        #
+        # Deliberately not part of the write that follows. Run first inside it, an UPDATE that
+        # matched no row took a gap lock on MySQL's unique index, and two writers starting the
+        # chain at once each tried to INSERT into the gap the other held: a deadlock, found
+        # by CI, invisible on PostgreSQL, which has no gap locks. On its own, two concurrent
+        # INSERTs of one unique name serialize: one wins and the other gets a duplicate key,
+        # which means the chain has started and is all it needs to know.
+        #
+        # So a started chain can exist with nothing in it yet (head 0) — if the first chained
+        # write then fails, say. The verifier reports that as no chain, not as a pass.
+        def start!(signer)
+          return if connection.select_value("SELECT 1 FROM #{TABLE} WHERE #{named}")
+
+          genesis = genesis_for(signer)
+          digest = Canonical.genesis_digest(signer.signing_secret, genesis)
+          values = genesis.merge(name: ChainRecord::LEDGER, genesis_digest: digest,
+                                 head_sequence: 0, head_digest: digest)
+          quoted = values.values.map { |value| connection.quote(value) }
+
+          entry_class.transaction(requires_new: true) do
+            connection.insert("INSERT INTO #{TABLE} (#{values.keys.join(', ')}) " \
+                              "VALUES (#{quoted.join(', ')})")
+          end
+        rescue ActiveRecord::RecordNotUnique
+          nil
+        end
+
+        # Locks the head and returns the next sequence and the digest it links to. The chain
+        # must have been started.
+        def advance!
+          vanished = increment.zero?
+          raise ActiveRecord::StatementInvalid, "the ledger chain record vanished" if vanished
+
+          head = connection.select_one("SELECT head_sequence, head_digest FROM #{TABLE} " \
+                                       "WHERE #{named}")
+          [Integer(head["head_sequence"]), head["head_digest"]]
+        end
+
+        # Takes the head's lock without consuming a sequence (specs/003 FR-008) and returns the
+        # head: a rotation queues at the same point as a write, so the epoch it opens begins
+        # exactly one past the last row any writer committed. A write that changes nothing
+        # still takes the row lock on PostgreSQL and MySQL and the write lock on SQLite.
+        def lock!
+          updated = connection.update("UPDATE #{TABLE} SET head_sequence = head_sequence " \
+                                      "WHERE #{named}")
+          raise ActiveRecord::StatementInvalid, "the ledger chain record vanished" if updated.zero?
+
+          sql = "SELECT head_sequence FROM #{TABLE} WHERE #{named}"
+          Integer(connection.select_value(Head.current(connection, sql)))
+        end
+
+        def point_at!(digest)
+          connection.update("UPDATE #{TABLE} SET head_digest = #{connection.quote(digest)} " \
+                            "WHERE #{named}")
+        end
+
+        # The connection this append runs on; Epochs uses it so the epoch an append opens
+        # commits or rolls back with the append.
+        attr_reader :connection
+
+        private
+
+        attr_reader :entry_class
+
+        def increment
+          connection.update("UPDATE #{TABLE} SET head_sequence = head_sequence + 1 WHERE #{named}")
+        end
+
+        def genesis_for(signer)
+          {
+            genesis_at: Time.now.utc.floor(6),
+            pre_chain_count: entry_class.where("contract_version < 3").count,
+            pre_chain_unchained_count:
+              entry_class.where(UNCHAINED).count,
+            genesis_key_id: signer.signing_id
+          }
+        end
+
+        def named
+          "name = #{connection.quote(ChainRecord::LEDGER)}"
+        end
+      end
+    end
+  end
+end