hecks 5.0.0 → 7.0.0

data/lib/hecks/hecks/adapters/journal_store/readings/projection_audit.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "json"
+require "hecks/ports/persistence/plugins/era"
+
+module Hecks
+  module Adapters
+    class JournalStore
+      module Readings
+        # Whether each era's stored hash is the hash of its stored projection. A held projection is
+        # trusted to say what shape an era holds, so one that was edited, copied from another era or
+        # written for another bluebook leaves the era's name describing a shape it does not hold.
+        # The reading only selects: it recomputes `ProjectedBluebook#mint_hash` and compares.
+        module ProjectionAudit
+          # Every bluebook under a domain directory, each against the database its own world names.
+          #
+          # @param domain [Hash, String] the domain directory
+          # @return [Hash] `text:` the audit as JSON: the eras read and each mismatch found
+          # @raise [Runtime::NotFound] if the directory cannot be loaded or a database refuses
+          def projection_audit(domain:)
+            answering do
+              directory = plain(domain)
+              registry = Hecks.describe(directory).registry
+              rows = registry.bluebooks.each_key.flat_map { |name| ProjectionAudit.of(registry, directory, name) }
+              JSON.pretty_generate({ "domain" => directory, "mismatches" => rows })
+            end
+          end
+
+          # @param registry [Runtime::Registry] a described registry
+          # @param directory [String] the domain's bluebook directory
+          # @param name [String] the bluebook's name
+          # @return [Array<Hash>] one row per era whose hash differs from its projection's
+          def self.of(registry, directory, name)
+            held = HeldDomain.new(registry, directory, name)
+            return [] unless held.capable?
+
+            held.reading { |lineage| mismatches(name, held.held_eras(lineage)) }
+          end
+
+          # @param domain [String] the domain's name
+          # @param eras [Array<Hash>] eras as `Lineage#eras` answers them
+          # @return [Array<Hash>] `domain`, `ordinal`, `stored` hash and `recomputed` hash of each
+          #   era whose projection hashes to another value; an era without both is skipped
+          def self.mismatches(domain, eras)
+            eras.filter_map do |era|
+              recomputed = recomputed_hash(era)
+              next if recomputed.nil? || recomputed == era[:hash]
+
+              { "domain" => domain, "ordinal" => era[:ordinal], "stored" => era[:hash], "recomputed" => recomputed }
+            end
+          end
+
+          # @param era [Hash] an era with `hash` and `projection`
+          # @return [String, nil] the hash of the stored projection; nil when the era lacks either
+          def self.recomputed_hash(era)
+            return unless era[:hash] && era[:projection]
+
+            Runtime::ProjectedBluebook.new(era[:projection]).mint_hash
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/journal_store/readings/scaffolding.rb

@@ -6,28 +6,31 @@ module Hecks
       module Readings
         # The edge file that would lead the latest held era to the current shape.
         module Scaffolding
+          # A line of an edge file that still marks a field as unresolved.
+          UNRESOLVED_LINE = /^\s*unresolved /
+
           private
 
           def scaffold(held, lineage, path)
             eras = held.held_eras(lineage)
-            return Readings.no_era(held.bluebook.name, path) if eras.empty?
+            return Readings.no_era(held.domain_name, path) if eras.empty?
 
             scaffold_latest(held, held.named(eras.last))
           end
 
           # The edge text for the latest era, or why there is nothing to scaffold.
           def scaffold_latest(held, latest)
-            shadow = PostgresEra::LineageManager.shadow(latest[:held_text])
-            return "#{held.bluebook.name} matches era #{latest[:ordinal]} — nothing to scaffold." if
-              Runtime::StorageShape.project(shadow) == held.shape
+            return "#{held.domain_name} matches era #{latest[:ordinal]} — nothing to scaffold." if
+              PostgresEra::LineageManager.held_shape(latest) == held.shape
 
-            edge_text(held, latest, Translation::Scaffold.diff(shadow, held.bluebook))
+            declared = PostgresEra::LineageManager.held_bluebook(latest)
+            edge_text(held, latest, Translation::Scaffold.diff(declared, held.bluebook))
           end
 
           def edge_text(held, latest, diffed)
             label = Runtime::StorageShape.mint_hash(held.bluebook)[0, Runtime::StorageShape::LABEL_LENGTH]
             edge = Translation::Scaffold::Edge.new(
-              domain: held.bluebook.name, from: latest[:label], to: label, ordinal: latest[:ordinal] + 1,
+              domain: held.domain_name, from: latest[:label], to: label, ordinal: latest[:ordinal] + 1,
               label: label, aggregates: diffed[:aggregates], retired: diffed[:retired]
             )
             text = Translation::Scaffold.render(edge)
@@ -35,7 +38,7 @@ module Hecks
           end
 
           def scaffold_notes(edge, text, unclaimed)
-            unresolved = text.scan(/^\s*unresolved /).size
+            unresolved = text.scan(UNRESOLVED_LINE).size
             notes = ["# Save as translations/#{edge.ordinal}-#{edge.label}.bluebook."]
             notes << "# #{unresolved} unresolved: decide what each became, then boot." if unresolved.positive?
             unclaimed.each do |name|

data/lib/hecks/hecks/adapters/journal_store/readings/sqlite_status/database_reading.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require_relative "../../../../../adapters/driven/sqlite"
+require_relative "read_only"
+
+module Hecks
+  module Adapters
+    class JournalStore
+      module Readings
+        module SqliteStatus
+          # One SQLite file read against the aggregates bound to it. The file is opened with
+          # read-only (see {ReadOnly}) and only `PRAGMA table_info` and `sqlite_master` are read.
+          class DatabaseReading
+            ADAPTERS = %w[Sqlite SqlitePersistence].freeze
+            # Tables the adapter keeps beside every aggregate's own.
+            ABSENT = "absent: created on first open"
+            SHARED_TABLE = /\A(events|hecks_\w+|sqlite_\w+)\z/
+
+            # The files the registry's aggregates are persisted in, each with its aggregates.
+            #
+            # @param registry [Runtime::Registry] a described registry
+            # @return [Hash{String => Array<Bluebook::Aggregate>}] absolute path to aggregates
+            def self.targets(registry)
+              registry.bluebooks.values.each_with_object({}) do |bluebook, found|
+                bluebook.aggregates.each do |aggregate|
+                  path = path_for(registry, bluebook, aggregate)
+                  (found[path] ||= []) << aggregate if path
+                end
+              end
+            end
+
+            # @return [String, nil] the file the aggregate is bound to, nil unless SQLite
+            def self.path_for(registry, bluebook, aggregate)
+              bind = Ports::Persistence::BindingPolicy.resolve(registry, bluebook.name, aggregate)
+              return unless ADAPTERS.include?(bind.adapter.to_s)
+
+              settings = registry.binding_settings(bluebook.name, Ports::Persistence::VERB, bind.adapter)
+              absolute(registry, registry.with_adapter_defaults(bind.adapter, aggregate, settings))
+            rescue Runtime::WiringError
+              nil
+            end
+
+            # @return [String] the settings' database, resolved against the registry's root
+            def self.absolute(registry, settings)
+              declared = settings.transform_keys(&:to_sym)[:database].to_s
+              declared.start_with?("/") ? declared : File.join(registry.root || Dir.pwd, declared)
+            end
+
+            # @param path [String] the database file
+            # @param aggregates [Array<Bluebook::Aggregate>] the aggregates bound to it
+            def initialize(path, aggregates)
+              @path = path
+              @aggregates = aggregates
+            end
+
+            # @return [Hash] `database`, `tables` (one per aggregate) and `orphans`
+            def row
+              return { database: @path, state: ABSENT, tables: [], orphans: [] } unless File.file?(@path)
+
+              db = ReadOnly.open(@path)
+              present = db.execute("SELECT name FROM sqlite_master WHERE type = 'table'").flatten
+              { database: @path, state: "read", tables: @aggregates.map { |a| table_row(db, present, a) },
+                orphans: orphans(present) }
+            ensure
+              db&.close
+            end
+
+            private
+
+            def table_row(db, present, aggregate)
+              base = { aggregate: aggregate.name, table: aggregate.storage_name }
+              return base.merge(state: ABSENT) unless present.include?(base[:table])
+
+              drift = drift_of(columns(db, base[:table]), expected(aggregate))
+              base.merge(state: drift.key?(:missing) ? "drift" : "ok", **drift)
+            end
+
+            # Column names compare without regard to capitals, as the adapter's open does.
+            def drift_of(held, wanted)
+              held_names = held.map(&:downcase)
+              wanted_names = wanted.map(&:downcase)
+              missing = wanted.reject { |name| held_names.include?(name.downcase) }
+              extra = held.reject { |name| wanted_names.include?(name.downcase) || name.casecmp?("id") }
+              { missing: missing, extra: extra }.reject { |_, names| names.empty? }
+            end
+
+            def columns(db, table)
+              db.execute(%(PRAGMA table_info("#{table.gsub('"', '""')}"))).map { |column| column[1] }
+            end
+
+            # The column names the adapter's codec persists, read without opening the adapter.
+            def expected(aggregate)
+              adapter = Hecks::Adapters::Sqlite.allocate
+              adapter.instance_variable_set(:@aggregate, aggregate)
+              adapter.send(:persisted_fields).map { |field| field[:name].to_s }
+            end
+
+            def orphans(present)
+              known = @aggregates.flat_map { |a| [a.storage_name, "#{a.storage_name}_entries"] }
+              (present - known).grep_v(SHARED_TABLE).map { |name| orphan(name) }
+            end
+
+            def orphan(name)
+              stem = name.delete_suffix("_entries")
+              owner = @aggregates.find { |a| [a.name, a.former_name].compact.map { |n| Naming.snake(n) }.include?(stem) }
+              owner ? { table: name, belongs_to: owner.name, stored_as: owner.storage_name } : { table: name }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/journal_store/readings/sqlite_status/read_only.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    class JournalStore
+      module Readings
+        module SqliteStatus
+          # Opens an existing SQLite file so that reading it creates nothing beside it. A plain
+          # read-only open of a database in write-ahead-log mode makes its `-wal` and `-shm`
+          # files, so a database with no `-wal` file is opened `immutable`, which skips them
+          # altogether. One that has a `-wal` file holds changes the reading must see, and
+          # already has the files a read-only open needs.
+          module ReadOnly
+            UNRESERVED = %r{[^A-Za-z0-9\-._~/]}
+
+            # @param path [String] a database file that exists
+            # @return [SQLite3::Database] the open, read-only database; the caller closes it
+            def self.open(path)
+              require "sqlite3"
+              return SQLite3::Database.new(path, readonly: true) if File.exist?("#{path}-wal")
+
+              SQLite3::Database.new("file:#{escape(path)}?immutable=1",
+                                    flags: SQLite3::Constants::Open::READONLY | SQLite3::Constants::Open::URI)
+            end
+
+            # @return [String] the path with every byte a URI reserves written as a percent escape
+            def self.escape(path) = path.gsub(UNRESERVED) { |char| char.bytes.map { |byte| format("%%%02X", byte) }.join }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/journal_store/readings/sqlite_status.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "sqlite_status/database_reading"
+
+module Hecks
+  module Adapters
+    class JournalStore
+      module Readings
+        # How the SQLite databases a domain's worlds name stand against its aggregates. Each file
+        # is opened read-only, never through the adapter (whose open adds missing columns), so the
+        # reading writes nothing and shows the drift before an open heals it or a write meets it.
+        module SqliteStatus
+          # @param domain [Hash, String] the domain directory
+          # @return [Hash] `text:` the status as JSON, one row per database file
+          # @raise [Runtime::NotFound] if the directory cannot be loaded
+          def sqlite_status(domain:)
+            answering { JSON.pretty_generate(SqliteStatus.of(Hecks.describe(plain(domain)).registry)) }
+          end
+
+          # @param registry [Runtime::Registry] a described registry
+          # @return [Array<Hash>] one row per SQLite file, in the order the aggregates name them
+          def self.of(registry)
+            DatabaseReading.targets(registry).map do |path, aggregates|
+              DatabaseReading.new(path, aggregates).row
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/journal_store/readings.rb

@@ -7,6 +7,12 @@ require_relative "edge_audit"
 require_relative "compaction"
 require_relative "readings/scaffolding"
 require_relative "readings/attestation"
+require_relative "readings/composition"
+require_relative "readings/boot_status"
+require_relative "readings/sqlite_status"
+require_relative "readings/event_trace"
+require_relative "readings/projection_audit"
+require_relative "readings/mint_plan"
 
 module Hecks
   module Adapters
@@ -22,6 +28,12 @@ module Hecks
 
         include Scaffolding
         include Attestation
+        include Composition
+        include BootStatus
+        include SqliteStatus
+        include EventTrace
+        include ProjectionAudit
+        include MintPlan
 
         # Words the answer for a domain that holds no era.
         #
@@ -29,7 +41,7 @@ module Hecks
         # @param path [String] the domain path, as the operator typed it
         # @return [String] the sentence
         def self.no_era(name, path)
-          "#{name} holds no era yet. `hecks hold_first #{path} --confirm` holds the first."
+          "#{name} holds no era yet. `hecks era.hold_first! #{path} --confirm` holds the first."
         end
 
         # The edge file that would lead the latest held era to the current shape, as its text.
@@ -108,10 +120,10 @@ module Hecks
 
         def audit(held, lineage, path)
           eras = held.held_eras(lineage)
-          return Readings.no_era(held.bluebook.name, path) if eras.empty?
+          return Readings.no_era(held.domain_name, path) if eras.empty?
 
           finding = EdgeAudit.call(held, lineage, eras)
-          return "#{held.bluebook.name} stands at era 1 — no edge to audit." unless finding
+          return "#{held.domain_name} stands at era 1 — no edge to audit." unless finding
           raise Runtime::NotFound, "#{finding.report}\nAUDIT REFUSED." unless finding.ok
 
           [finding.report, AUDIT_PASSED].join("\n")

data/lib/hecks/hecks/adapters/journal_store/reconcile_report.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    class JournalStore
+      # Words the reconciliation's dry run and its written report, from the rows it planned.
+      module ReconcileReport
+        module_function
+
+        # @param row [Reconciliation::Row] one bluebook's row
+        # @return [String] the block that reports the row's plan
+        def render_row(row)
+          return "#{row.name}: its store keeps no eras, so there is nothing to reconcile" unless row.plan
+
+          plan = row.plan
+          head = "#{row.name}: current #{plan.current}"
+          head += ", latest era #{plan.latest[:ordinal]} (#{plan.latest[:label]})" if plan.latest
+          [head, *verdict_lines(plan)].join("\n")
+        end
+
+        # @param writes [Array<Reconciliation::Row>] the rows whose plans were carried out
+        # @return [String] what was written and deleted, per domain
+        def written(writes)
+          lines = writes.flat_map { |row| written_lines(row.name, row.plan) }
+          ["the audit passed for each composed edge", *lines].join("\n")
+        end
+
+        def written_lines(name, plan)
+          written = plan.write_path ? ["  wrote #{File.basename(plan.write_path)}"] : []
+          ["#{name}: #{plan.labels.join(" -> ")}", *written,
+           *plan.removals.map { |path| "  removed #{File.basename(path)}" }]
+        end
+
+        def verdict_lines(plan)
+          case plan.status
+          when :no_era then ["  no era held yet; nothing to reconcile"]
+          when :refused then ["  verdict: REFUSED — #{plan.refusal}"]
+          when :clean then ["  verdict: clean — nothing to write or delete", "  mints: #{mint_line(plan)}"]
+          else write_lines(plan)
+          end
+        end
+
+        def write_lines(plan)
+          lines = ["  chain: #{plan.labels.join(" -> ")}"]
+          lines << "  would write: #{File.basename(plan.write_path)}" if plan.write_path
+          lines += plan.removals.map { |path| "  would delete: #{File.basename(path)}" }
+          lines << "  verdict: write"
+          lines << "  mints: #{mint_line(plan)}"
+        end
+
+        def mint_line(plan)
+          return "no era on the next boot" unless plan.mints
+
+          "era #{plan.latest[:ordinal] + 1} (#{plan.current}) on the next boot of a copy whose world " \
+            "declares mint_eras true"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/journal_store/reconciliation.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require_relative "held_domain"
+require_relative "edge_audit"
+require_relative "reconcile_report"
+
+module Hecks
+  module Adapters
+    class JournalStore
+      # The `reconcile` change: plans every bluebook of a project against the eras its store holds,
+      # and when every plan is admitted writes the composed edges, deletes the edges they supersede,
+      # and audits each written edge. Reading is the dry run; only `apply_reconcile` writes, and a
+      # refused plan in any domain writes nothing.
+      module Reconciliation
+        # The project directory a reconciliation reads when none is named: the hecks checkout's own
+        # domain directory, whose `translations/` holds the edges of every domain it loads.
+        DEFAULT_PROJECT = File.expand_path("../..", __dir__)
+
+        # One bluebook's plan; `plan` is nil when its store keeps no eras.
+        Row = Struct.new(:name, :plan, keyword_init: true) do
+          def refusal = plan&.refusal
+
+          def status = plan&.status
+
+          def edge = plan&.edge
+        end
+
+        # The dry run: one report of every domain's plan, written nowhere.
+        #
+        # @param domain [Hash, String, nil] the project directory; the checkout's own when absent
+        # @return [Hash] `text:` the report, one block per domain
+        # @raise [Runtime::NotFound] if the project cannot be loaded
+        def reconcile_plan(domain: nil)
+          answering { project_rows(project_path(domain)).map { |row| ReconcileReport.render_row(row) }.join("\n\n") }
+        end
+
+        private
+
+        # Examines nothing: the plans decide what is admitted, and `apply_reconcile` refuses a store
+        # that keeps no eras.
+        def examine_reconcile(_held) = { capable: true }
+
+        def apply_reconcile(held)
+          path = project_path(held[:domain])
+          rows = project_rows(path)
+          refusals = rows.filter_map(&:refusal)
+          unless refusals.empty?
+            raise Runtime::WiringError, "nothing was written; the reconciliation refused:\n  #{refusals.join("\n  ")}"
+          end
+
+          write_reconciled(path, rows.select { |row| row.status == :write })
+        end
+
+        def write_reconciled(path, writes)
+          return "every domain already leads to its current shape — nothing to reconcile." if writes.empty?
+
+          originals = writes.reduce({}) { |found, row| found.merge(Translation::ReconcileFiles.write!(row.plan)) }
+          begin
+            writes.each { |row| audit_written!(path, row) }
+          rescue StandardError
+            Translation::ReconcileFiles.restore!(originals)
+            raise
+          end
+          ReconcileReport.written(writes)
+        end
+
+        # Audits the composed edge a row wrote; a row that only deleted edges has nothing to audit.
+        #
+        # @raise [Runtime::WiringError] when the audit refuses the composed edge
+        def audit_written!(path, row)
+          return unless row.edge
+
+          project = HeldDomain.open(path)
+          domain = HeldDomain.new(project.registry, project.directory, row.name)
+          finding = domain.reading { |lineage| EdgeAudit.call(domain, lineage, domain.held_eras(lineage)) }
+          return if finding.nil? || finding.ok
+
+          raise Runtime::WiringError,
+                "cannot reconcile #{row.name}: the audit refused the composed edge —\n  " \
+                "#{finding.refusals.join("\n  ")}"
+        end
+
+        def project_path(domain) = plain(domain) || DEFAULT_PROJECT
+
+        # @return [Array<Row>] one row per bluebook the project loads, in the registry's order
+        def project_rows(path)
+          project = HeldDomain.open(path)
+          project.bluebook_names.map { |name| bluebook_row(project, name) }
+        end
+
+        def bluebook_row(project, name)
+          domain = HeldDomain.new(project.registry, project.directory, name)
+          return Row.new(name: name) unless domain.capable?
+
+          domain.reading { |lineage| Row.new(name: name, plan: domain_plan(domain, lineage, project)) }
+        end
+
+        def domain_plan(domain, lineage, project)
+          Translation::Reconcile.plan(
+            Translation::Reconcile::Scope.new(
+              domain: domain.domain_name, held: held_labels(domain, lineage), current: current_label(domain),
+              edges: domain.translations.select { |edge| edge.domain == domain.domain_name },
+              files: Translation::EdgeFiles.scan(project.directory), directory: project.directory
+            )
+          )
+        end
+
+        def held_labels(domain, lineage)
+          domain.held_eras(lineage).map do |era|
+            named = domain.named(era)
+            { ordinal: named[:ordinal], label: named[:label] }
+          end
+        end
+
+        def current_label(domain)
+          Runtime::StorageShape.mint_hash(domain.bluebook)[0, Runtime::StorageShape::LABEL_LENGTH]
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/journal_store/translation_write/shape_edge.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    class JournalStore
+      module TranslationWrite
+        # The edge for a shape that changed under an unchanged label: the scaffold's diff, written from
+        # the label to itself. Only `TranslationWrite` includes it.
+        module ShapeEdge
+          # A line of an edge file that still marks a field as undecided.
+          UNRESOLVED_LINE = /^\s*unresolved /
+
+          private
+
+          # A held label that equals the current one with a different projection: the edge is the
+          # scaffold's diff, from the label to itself. A field the diff cannot decide refuses the write.
+          #
+          # @raise [Runtime::WiringError] when the diff leaves a field or an aggregate to decide
+          def shape_edge_plan(domain, latest, current)
+            diffed = diff_for(domain, latest)
+            refuse_undecided!(domain, "UNCLAIMED #{diffed[:unclaimed].join(", ")}") unless diffed[:unclaimed].empty?
+            text = Translation::Scaffold.render(shape_edge(domain, latest, current, diffed))
+            refuse_undecided!(domain, "unresolved fields") if text.match?(UNRESOLVED_LINE)
+            Plan.new(path: Translation::EdgeFiles.path_for(domain.directory, from: latest[:label], to: current),
+                     text: text, removals: [], labels: [latest[:label], current])
+          end
+
+          def diff_for(domain, latest)
+            Translation::Scaffold.diff(PostgresEra::LineageManager.held_bluebook(latest), domain.bluebook)
+          end
+
+          def shape_edge(domain, latest, current, diffed)
+            Translation::Scaffold::Edge.new(domain: domain.domain_name, from: latest[:label], to: current,
+                                            ordinal: latest[:ordinal] + 1, label: current,
+                                            aggregates: diffed[:aggregates], retired: diffed[:retired])
+          end
+
+          def refuse_undecided!(domain, reason)
+            raise Runtime::WiringError,
+                  "cannot write the translation of #{domain.domain_name}: the shape changed under the same label " \
+                  "and the scaffold leaves #{reason} to decide; write the edge by hand"
+          end
+
+          def already_leads(from, to)
+            Plan.new(message: "one edge already leads #{from} to #{to} — nothing to write.")
+          end
+
+          def edge_plan(domain, from, to, chain)
+            edge = Translation::Compose.compose(domain: domain.domain_name, from: from, to: to, chain: chain)
+            labels = [from, *chain.map(&:to)]
+            stale = Translation::EdgeFiles.stale(domain.directory, domain: domain.domain_name, chain: chain)
+            Plan.new(path: Translation::EdgeFiles.path_for(domain.directory, from: from, to: to),
+                     text: Translation::ComposeRender.render(edge, labels: labels), removals: stale, labels: labels)
+          end
+        end
+      end
+    end
+  end
+end