hecks 3.9.1 → 3.11.0

data/lib/hecks/hecks/adapters/rehearsal/declaration.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Hecks
+  module Adapters
+    # Everything a rehearsal does on a client's domain: where its data copy comes from, how the
+    # mint's audit is run over it, and what is reported. The two port adapters (`RehearsalStore`
+    # and `RehearsalSubject`) are thin; the work lives here.
+    module Rehearsal
+      # A rehearsal that was not admitted or could not be carried on: the port answers it as a
+      # refusal, which the run keeps as `refusal`.
+      class Refused < StandardError; end
+
+      # What a subject's own `.world` says about the copy of its data, read from its
+      # `rehearsed_by` block and checked before anything is touched.
+      #
+      # A connection is only ever named by an environment variable (`connection_env`); a literal
+      # connection string, user or password in the world is refused, so the file holds no secret.
+      class Declaration
+        KINDS = %w[memory postgres].freeze
+        MODES = %w[empty dump readonly_copy].freeze
+        LITERALS = %i[database url connection password user].freeze
+        LOCAL_HOSTS = [nil, "", "localhost", "127.0.0.1", "::1", "[::1]"].freeze
+
+        NAME = /\A[A-Za-z0-9_-]+\z/
+
+        attr_reader :kind, :mode, :connection_env, :dump, :rows, :drop_after, :allow_remote, :schema, :environment
+
+        # @param world [#for_verb, nil] the subject's world, as the registry holds it
+        # @param directory [String] the domain's bluebook directory, which a relative file is under
+        # @return [Declaration] the checked declaration
+        # @raise [Refused] if the world declares no `rehearsed_by`, or declares it wrongly
+        def self.from_world(world, directory)
+          settings = world&.for_verb("rehearsed_by") || {}
+          raise Refused, "the domain's world declares no `rehearsed_by`: nothing says where its data copy is" if settings.empty?
+
+          new(settings, directory).tap(&:check!)
+        end
+
+        # @param settings [Hash] the block's settings, `adapter:` among them
+        # @param directory [String] where a relative `dump` or `rows` is found
+        def initialize(settings, directory)
+          @kind           = settings[:adapter].to_s.downcase
+          @connection_env = settings[:connection_env]&.to_s
+          @dump           = expand(settings[:dump], directory)
+          @rows           = expand(settings[:rows], directory)
+          @mode           = settings.fetch(:mode) { default_mode }.to_s
+          read_switches(settings)
+        end
+
+        # @return [void]
+        # @raise [Refused] naming what is wrong with the declaration
+        def check!
+          check_names!
+          raise Refused, literal_wording unless @literals.empty?
+
+          kind == "postgres" ? check_postgres! : check_memory!
+        end
+
+        # @return [String] the connection the environment holds
+        # @raise [Refused] if the variable the world names is unset or empty, or names a server
+        #   that is not this machine and the world did not say `allow_remote true`
+        def connection
+          value = ENV.fetch(connection_env, "")
+          raise Refused, "the environment variable #{connection_env} is not set" if value.strip.empty?
+
+          refuse_remote!(value)
+          value
+        end
+
+        private
+
+        def refuse_remote!(value)
+          host = URI.parse(value).host
+          return if allow_remote || LOCAL_HOSTS.include?(host)
+
+          raise Refused, "#{connection_env} names the server #{host.inspect}, which is not this machine: " \
+                         "a rehearsal reads a local copy; say `allow_remote true` in rehearsed_by to point it elsewhere"
+        rescue URI::InvalidURIError
+          nil
+        end
+
+        def read_switches(settings)
+          @drop_after   = settings.fetch(:drop_after, true) != false
+          @allow_remote = settings.fetch(:allow_remote, false) == true
+          @literals     = LITERALS & settings.keys.map(&:to_sym)
+          @schema       = settings[:schema]&.to_s
+          @environment  = settings[:environment]&.to_s
+        end
+
+        def default_mode = dump || rows ? "dump" : "empty"
+
+        def check_names!
+          raise Refused, "rehearsed_by names #{kind.inspect}; the stores are #{KINDS.join(" and ")}" unless KINDS.include?(kind)
+
+          raise Refused, "rehearsed_by mode #{mode.inspect} is not one of #{MODES.join(", ")}" unless MODES.include?(mode)
+
+          check_label!("schema", schema)
+          check_label!("environment", environment)
+        end
+
+        def check_label!(word, value)
+          return if value.nil? || NAME.match?(value)
+
+          raise Refused, "rehearsed_by #{word} #{value.inspect} is not a name (letters, digits, `_`, `-`)"
+        end
+
+        def expand(path, directory)
+          path && File.expand_path(path.to_s, directory)
+        end
+
+        def literal_wording
+          "rehearsed_by holds #{@literals.join(", ")}: name the environment variable in `connection_env`, " \
+            "never the value, so the world file holds no secret"
+        end
+
+        def check_postgres!
+          unless connection_env
+            raise Refused,
+                  "a postgres rehearsal needs `connection_env`, the name of the variable holding the server"
+          end
+          raise Refused, "mode dump needs `dump`, the file to restore" if mode == "dump" && !dump
+        end
+
+        def check_memory!
+          raise Refused, "mode readonly_copy is a postgres mode: a memory store has no copy to read" if mode == "readonly_copy"
+          raise Refused, "mode dump needs `rows`, the JSON file the memory store holds" if mode == "dump" && !rows
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/rehearsal/environment.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    module Rehearsal
+      # Which environment overlay (`environments/<name>.hecksagon` and `.world`) a rehearsal loads
+      # the subject under, and where that was decided.
+      #
+      # A rehearsal is about the era the production binds will mint, so it loads `production` when
+      # the domain has `environments/production.hecksagon`, the same default the Rust host build
+      # takes (`ProjectRust::DomainLoader#load_environment`). Most domains bind their aggregates
+      # to a database only in that overlay, so the base files alone have no `persisted_by` bind.
+      # The choice is a reported fact (`environment_loaded`), never a silent one.
+      class Environment
+        # Where the name came from, in the order they are tried.
+        SOURCES = %w[world HECKS_PROJECT_ENVIRONMENT default none].freeze
+
+        NONE_WORDS = "no environment overlay (none named in rehearsed_by or HECKS_PROJECT_ENVIRONMENT, " \
+                     "and no environments/production.hecksagon)"
+
+        # @!attribute [r] name
+        #   @return [String] the overlay's name, or `""` when none was loaded
+        # @!attribute [r] source
+        #   @return [String] one of `SOURCES`
+        # @!attribute [r] directory
+        #   @return [String] the bluebook directory the overlay is looked for under
+        attr_reader :name, :source, :directory
+
+        # @param declared [String, nil] what the world's `rehearsed_by` names (`environment "..."`)
+        # @param directory [String] the domain's bluebook directory
+        # @return [Environment] the choice: the world's, else `HECKS_PROJECT_ENVIRONMENT`, else
+        #   `production` when its overlay exists, else none
+        def self.resolve(declared, directory)
+          env = ENV.fetch("HECKS_PROJECT_ENVIRONMENT", "")
+          return new(declared, "world", directory) if declared && !declared.empty?
+          return new(env, "HECKS_PROJECT_ENVIRONMENT", directory) unless env.empty?
+          return new("production", "default", directory) if File.exist?(File.join(directory, "environments",
+                                                                                  "production.hecksagon"))
+
+          new("", "none", directory)
+        end
+
+        # @param name [String] the overlay's name
+        # @param source [String] one of `SOURCES`
+        # @param directory [String] the bluebook directory
+        def initialize(name, source, directory)
+          @name = name
+          @source = source
+          @directory = directory
+        end
+
+        # @return [String, nil] the name to load, nil when no overlay is wanted
+        def overlay = name.empty? ? nil : name
+
+        # @return [Boolean] whether the hecksagon file of this overlay exists
+        def overlay_file? = File.exist?(file)
+
+        # @return [String] the hecksagon file the overlay is looked for in
+        def file = File.join(directory, "environments", "#{name}.hecksagon")
+
+        # @return [Hash] the report fact, as the `Environment` value object holds it
+        def facts = { name: name, source: source, file: name.empty? ? "" : file }
+
+        # @return [String] what the overlay choice was, in words
+        def to_s
+          return NONE_WORDS if name.empty?
+
+          "environment #{name.inspect} (#{source}), file #{file} #{overlay_file? ? "found" : "NOT FOUND"}"
+        end
+
+        # The overlays the directory holds, so a refusal can say what could be chosen.
+        #
+        # @return [Array<String>] the names of `environments/*.hecksagon`
+        def available
+          Dir.glob(File.join(directory, "environments", "*.hecksagon")).map { |path| File.basename(path, ".hecksagon") }.sort
+        end
+
+        # @return [String] the overlays the directory holds, comma separated, or `none`
+        def available_words = available.empty? ? "none" : available.join(", ")
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/rehearsal/inquiry.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require_relative "subject"
+require_relative "memory_store"
+require_relative "postgres_store"
+require_relative "rust_audit"
+require_relative "audit_report"
+
+module Hecks
+  module Adapters
+    module Rehearsal
+      # The two questions a rehearsal asks of a subject and its data copy: where the shape stands
+      # (`survey`) and what the mint's audit would refuse (`examine`). Each answer is the facts, as
+      # the `RehearsalRun` commands take them.
+      class Inquiry
+        # What every rehearsal says it did not check.
+        ENGINE_LIMIT = { what: "the Rust host's mint audit",
+                         why:  "no validate_harness was built, so the Ruby audit alone ran over the rows" }.freeze
+
+        ALWAYS = [
+          { what: "the mint itself",
+            why:  "no era was written: the edge, its approval and the audit were evaluated, nothing minted" },
+          { what: "an edge's coverage of every change in the shape", why: "the mint checks it; the rehearsal does not yet" },
+          { what: "commands, policies and requests", why: "no traffic was run: only the stored data and the shape were read" },
+          { what: "data written after the copy was made", why: "a copy is a moment; the mint sees the data of its own" }
+        ].freeze
+
+        # @param subject [Subject] the loaded domain
+        # @param store [MemoryStore, PostgresStore] its prepared data copy
+        def initialize(subject, store)
+          @subject = subject
+          @store = store
+        end
+
+        # @return [Hash] `booted`, `host_version`, `store`, `mode`, `before`, `after`, `minting`,
+        #   the schema and environment that were read, and what the copy holds
+        def survey
+          shape.merge(environment_loaded: @subject.environment.facts, copy_note: plain(copy_note)).merge(copy_facts)
+        end
+
+        # @return [Hash] the edge facts, every refused row and its total, what was read, the parity
+        #   of the two engines, and what was not checked
+        def examine
+          edge = minting == "next" ? @subject.edge_from(before) : nil
+          refusals, after = edge ? @store.audit(@subject, edge) : [[], {}]
+          rust = RustAudit.call(@subject, after)
+          report = AuditReport.new(minting: minting, edge: edge, states: after, ruby: refusals, rust: rust)
+          answer(edge, report, (refusals + rust.violations).uniq, limits(edge, rust, report))
+        end
+
+        private
+
+        def plain(value) = { value: value }
+
+        def shape
+          { booted: flag(true), host_version: plain(Rehearsal.host_version), store: plain(@subject.declaration.kind),
+            mode: plain(@subject.declaration.mode), before: plain(before), after: plain(@subject.label),
+            minting: plain(minting) }
+        end
+
+        def answer(edge, report, refused, unchecked)
+          rows, total = Rows.from(refused)
+          edge_facts(edge).merge(refused_rows: rows, refusal_total: plain(total), parity: report.parity,
+                                 unchecked: unchecked).merge(report.facts)
+        end
+
+        def flag(value) = plain(value)
+
+        def census = @census ||= @store.census(@subject)
+
+        def copy_note
+          domain = @subject.bluebook.name
+          copy_empty? ? census.refusal(domain) : census.summary(domain)
+        end
+
+        def copy_empty?
+          census.empty? && @subject.declaration.mode != "empty" && @subject.bluebook.aggregates.any?
+        end
+
+        # The copy is empty when a dump or a readonly copy was asked for and it holds no row of a
+        # domain that declares aggregates; a mode of `empty` is asked to hold nothing.
+        def copy_facts = census.facts.merge(copy_empty: flag(copy_empty?))
+
+        def edge_facts(edge)
+          { minting: plain(minting), edge_present: flag(!edge.nil?), edge_approved: flag(approved?(edge)) }
+        end
+
+        def eras = @eras ||= @store.eras(@subject)
+
+        def latest = @latest ||= eras.last && @subject.held.named(eras.last)
+
+        def before = latest ? latest[:label] : "none"
+
+        def minting
+          return "first" unless latest
+
+          before == @subject.label ? "none" : "next"
+        end
+
+        def approved?(edge)
+          return false unless edge
+
+          !Translation::ApprovalFile.needs_rehearsal?(edge) ||
+            !Translation::ApprovalFile.applicable(@subject.directory, edge).nil?
+        end
+
+        def limits(edge, rust, report)
+          engine = rust.ran ? [] : [ENGINE_LIMIT]
+          engine + report.limits + ALWAYS + @store.limits(edge) + [journal_limit] + attached_limits +
+            (@subject.held.capable? ? [] : [binding_note])
+        end
+
+        # The audit reads the journal's latest entry of each record, never the head tables.
+        def journal_limit
+          { what: "the head tables",
+            why:  "the audit reads each record's latest journal entry (hecks_journal_<domain>_era_N), not the head " \
+                  "tables, so an edit to a head table is not seen. The copy holds #{census.head_rows} head rows " \
+                  "and #{census.journal_rows} journal records#{divergence}" }
+        end
+
+        def divergence
+          census.head_rows == census.journal_rows ? "." : ": they differ, and only the journal's are audited."
+        end
+
+        # The chapters loaded beside the domain's own (a vendored package): the host holds eras
+        # for the domain's own aggregates only, so theirs can neither mint nor be refused.
+        def attached_limits
+          names = @subject.held.registry.bluebooks.values.map(&:name) - [@subject.bluebook.name]
+          return [] if names.empty?
+
+          [{ what: "the shape of the attached chapters (#{names.sort.join(", ")})",
+             why:  "their aggregates have no era row of their own, so a change to them is not a mint" }]
+        end
+
+        def binding_note
+          { what: "that a boot would mint", why: "the domain is bound to #{@subject.held.adapter_name}, which holds no eras " \
+                                                 "in this environment" }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/rehearsal/memory_store.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "rows"
+require_relative "census"
+
+module Hecks
+  module Adapters
+    module Rehearsal
+      # The data copy as a JSON document the world names (`rows`): the eras held and the records
+      # stored under the latest, in that era's shape. Nothing is created or dropped, so specs and
+      # fixtures rehearse without a database.
+      #
+      # The document is `{"eras": [{"ordinal": 1, "held_text": "<bluebook text>"}], "records":
+      # {"Aggregate": {"id": {"field": ...}}}}`.
+      class MemoryStore
+        # @param declaration [Declaration] a `memory` declaration
+        def initialize(declaration)
+          path = declaration.rows
+          @document = path ? JSON.parse(File.read(path)) : {}
+        end
+
+        # @return [void]
+        def prepare! = nil
+
+        # @return [void] there is nothing to drop
+        def drop! = nil
+
+        # @param _subject [Subject] unused: the document holds its own eras
+        # @return [Array<Hash>] the eras, `ordinal` and `held_text`
+        def eras(_subject)
+          Array(@document["eras"]).map { |era| { ordinal: era["ordinal"], held_text: era["held_text"] } }
+        end
+
+        # What the document holds: it keeps the latest state of each record only, so the head and
+        # the journal counts are the same number.
+        #
+        # @param subject [Subject] the loaded domain
+        # @return [Census] the counts
+        def census(subject)
+          counts = subject.bluebook.aggregates.map do |aggregate|
+            held = records(aggregate.name).size
+            Census::Count.new(aggregate: aggregate.name, head: held, journal: held)
+          end
+          Census.new(schema: "(memory document)", source: "memory", present: true, eras: eras(subject).size,
+                     journal_entries: counts.sum(&:journal), counts: counts)
+        end
+
+        # Runs the mint's audit over the stored records, translated through the edge in process.
+        #
+        # @param subject [Subject] the loaded domain
+        # @param edge [Bluebook::Translation] the edge leading to the shape
+        # @return [Array(Array<String>, Hash)] the audit's refusals, and the translated records
+        #   by aggregate name and id
+        def audit(subject, edge)
+          refusals = []
+          after = subject.bluebook.aggregates.to_h do |aggregate|
+            declared = edge.for_aggregate(aggregate.name)
+            before = records(declared&.was || aggregate.name)
+            translated = translate(aggregate, declared, before)
+            refusals.concat(Translation::Audit.check(aggregate: aggregate, declared: declared, before: before,
+                                                     after: translated).violations)
+            [aggregate.name, translated]
+          end
+          [refusals, after]
+        end
+
+        # @param edge [Bluebook::Translation] the edge
+        # @return [Array<Hash>] what memory cannot apply, as report limits
+        def limits(edge)
+          return [] unless edge && Translation::ApprovalFile.needs_rehearsal?(edge)
+
+          [{ what: "the edge's compute and rekey rules",
+             why:  "they are SQL, which only a postgres copy runs; memory leaves those fields as stored" }]
+        end
+
+        private
+
+        def records(name) = @document.dig("records", name.to_s) || {}
+
+        def translate(aggregate, declared, before)
+          lineage = Ports::Persistence::Lineage.from_declared(declared, aggregate.name)
+          return before unless lineage
+
+          before.to_h { |id, state| [id, lineage.translate(entry(id, state)).state] }
+        end
+
+        def entry(id, state)
+          Ports::Persistence::Entry.new(operation: "save", id: id, state: symbolise(state), mirrors: {})
+        end
+
+        def symbolise(state) = JSON.parse(JSON.generate(state), symbolize_names: true)
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/rehearsal/postgres_census.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require_relative "census"
+
+module Hecks
+  module Adapters
+    module Rehearsal
+      # Counts what a Postgres copy holds for the domain without creating anything: a plain
+      # connection, the schemas looked up before one is chosen, and counts over the relations that
+      # exist. A schema that is not in the copy is reported, never created.
+      class PostgresCensus
+        JOURNAL_LATEST = <<~SQL
+          SELECT aggregate, count(*) AS live FROM (
+            SELECT DISTINCT ON (aggregate, aggregate_id) aggregate, operation
+            FROM %<journal>s ORDER BY aggregate, aggregate_id, ordinal DESC
+          ) latest WHERE operation = 'save' GROUP BY aggregate
+        SQL
+
+        # @param url [String] the copy's database URL
+        # @param subject [Subject] the loaded domain
+        # @param candidates [Array<Array(String, String)>] schema and source, in the order tried
+        def initialize(url, subject, candidates)
+          @url = url
+          @subject = subject
+          @candidates = candidates
+        end
+
+        # @return [Census] the counts, in the first candidate schema that holds a lineage, else the
+        #   first that exists, else the first named
+        def read
+          db = PG.connect(@url)
+          present = schemas(db)
+          lineage = holders(db)
+          name, source = choose(present, lineage)
+          return absent(name, source, lineage) unless present.include?(name)
+
+          db.exec("SET search_path TO #{db.quote_ident(name)}")
+          counted(db, name, source, lineage - [name])
+        ensure
+          db&.close
+        end
+
+        private
+
+        def schemas(db) = db.exec("SELECT schema_name FROM information_schema.schemata").map { |row| row["schema_name"] }
+
+        def holders(db)
+          sql = "SELECT table_schema FROM information_schema.tables WHERE table_name = 'hecks_eras'"
+          db.exec(sql).map { |row| row["table_schema"] }.sort
+        end
+
+        def choose(present, lineage)
+          @candidates.find { |name, _| lineage.include?(name) } || @candidates.find { |name, _| present.include?(name) } ||
+            @candidates.first
+        end
+
+        def absent(name, source, lineage)
+          Census.new(schema: name, source: source, present: false, eras: 0, journal_entries: 0,
+                     counts: empty_counts, elsewhere: lineage)
+        end
+
+        def empty_counts = @subject.bluebook.aggregates.map { |a| Census::Count.new(aggregate: a.name, head: 0, journal: 0) }
+
+        def counted(db, name, source, elsewhere)
+          lineage = PostgresEra::Lineage.new(db, @subject.bluebook.name)
+          Census.new(schema: name, source: source, present: true, eras: eras(db), counts: counts(db, lineage),
+                     journal_entries: rows(db, lineage.journal), elsewhere: elsewhere)
+        end
+
+        def counts(db, lineage)
+          live = latest(db, lineage)
+          @subject.bluebook.aggregates.map do |aggregate|
+            Census::Count.new(aggregate: aggregate.name, head: rows(db, lineage.head_view(aggregate.storage_name)),
+                              journal: live.fetch(aggregate.storage_name, 0))
+          end
+        end
+
+        def eras(db)
+          return 0 unless relation?(db, "hecks_eras")
+
+          db.exec_params("SELECT count(*) FROM hecks_eras WHERE domain = $1", [@subject.bluebook.name])[0]["count"].to_i
+        end
+
+        def latest(db, lineage)
+          return {} unless relation?(db, lineage.journal)
+
+          db.exec(format(JOURNAL_LATEST, journal: db.quote_ident(lineage.journal))).to_h { |r| [r["aggregate"], r["live"].to_i] }
+        end
+
+        def rows(db, name)
+          relation?(db, name) ? db.exec("SELECT count(*) FROM #{db.quote_ident(name)}")[0]["count"].to_i : 0
+        rescue PG::Error
+          0
+        end
+
+        def relation?(db, name) = !db.exec_params("SELECT to_regclass($1) AS found", [db.quote_ident(name)])[0]["found"].nil?
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/rehearsal/postgres_reading.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "postgres_census"
+
+module Hecks
+  module Adapters
+    module Rehearsal
+      # What a `PostgresStore` reads from its database: the eras it holds and the mint's audit over
+      # the records under them. No table is provisioned and no era written; a copy somebody else
+      # made is read in a read-only session, and the database a run made is its own to touch.
+      #
+      # The schema is the world's `schema`, else `HECKS_SCHEMA`, else the one the domain's name
+      # gives (`Shop` is `shop`), else `public` when that holds the lineage. It is looked up
+      # before it is used, so a schema the copy does not have is reported and never created.
+      module PostgresReading
+        # @param subject [Subject] the loaded domain
+        # @return [Census] what the copy holds for the domain, counted once
+        def census(subject)
+          @census ||= PostgresCensus.new(url, subject, schema_candidates(subject)).read.tap do |found|
+            subject.held.read_schema(found.schema)
+          end
+        end
+
+        # @param subject [Subject] the loaded domain
+        # @return [Array<Hash>] the eras the database holds, none when it holds no lineage
+        def eras(subject)
+          return [] unless census(subject).present
+
+          reading(subject) { |lineage| subject.held.held_eras(lineage) }
+        end
+
+        # @param subject [Subject] the loaded domain
+        # @param _edge [Bluebook::Translation] the edge leading to the shape
+        # @return [Array(Array<String>, Hash)] what the audit's layers refuse over the stored
+        #   records, and the records as translated, by aggregate name and id
+        def audit(subject, _edge)
+          return [[], {}] unless census(subject).present
+
+          reading(subject) do |lineage|
+            finding = JournalStore::EdgeAudit.call(subject.held, lineage, subject.held.held_eras(lineage))
+            finding ? [finding.refusals, finding.after] : [[], {}]
+          end
+        end
+
+        # @param _edge [Bluebook::Translation] unused
+        # @return [Array<Hash>] none: a postgres copy runs the compiled rules itself
+        def limits(_edge) = []
+
+        private
+
+        def schema_candidates(subject)
+          return [[@declaration.schema, "world"]] if @declaration.schema
+          return [[ENV.fetch("HECKS_SCHEMA"), "HECKS_SCHEMA"]] if ENV.fetch("HECKS_SCHEMA", "") != ""
+
+          [[Naming.snake(subject.bluebook.name), "derived"], %w[public default]]
+        end
+
+        def reading(subject)
+          subject.held.read_from(url)
+          db = PostgresEra.connect_for(subject.bluebook.name, subject.held.settings)
+          db.exec("SET default_transaction_read_only = on") if @declaration.mode == "readonly_copy"
+          yield PostgresEra::Lineage.new(db, subject.bluebook.name)
+        ensure
+          db&.close
+        end
+      end
+    end
+  end
+end