hecks 6.0.0 → 7.0.0

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

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require_relative "../../edge_audit"
+
+module Hecks
+  module Adapters
+    class JournalStore
+      module Readings
+        module MintPlan
+          # The guards on the edge a mint would take, each the very function the mint runs: the
+          # shared decision's refusal (`LineageManager.resolve_edge!`, which words a missing or a
+          # duplicate edge), the coverage check (`check_coverage!`) and the translation audit the
+          # rehearsal runs over the rows (`EdgeAudit`), here over the live store in place.
+          class EdgeGuards
+            LATER = %w[coverage audit].freeze
+
+            # @param report [Report] where each guard is recorded
+            # @param held [HeldDomain] the loaded domain
+            # @param lineage [Lineage] a read-only lineage over the store
+            def initialize(report, held, lineage)
+              @report = report
+              @held = held
+              @lineage = lineage
+            end
+
+            # @param eras [Array<Hash>] the held eras
+            # @param verdict [LineageManager::MintDecision::Verdict] the latest era's decision
+            # @return [Object, nil] the edge the mint would take; nil when a guard refused
+            def call(eras, verdict)
+              latest = @held.named(eras.last)
+              edge = decided(latest, verdict)
+              return stop(LATER, "the edge guard refused") unless edge
+              return stop(%w[audit], "the coverage check refused") unless covered?(latest, edge)
+
+              audit(eras, edge)
+              edge
+            end
+
+            private
+
+            def stop(names, why)
+              @report.skip(names, why)
+              nil
+            end
+
+            def decided(latest, verdict)
+              if verdict.verdict == "would_mint"
+                @report.add("edge", :pass, edge_words(verdict))
+                return verdict.edge
+              end
+
+              @report.add("edge", :refuse, refusal(latest, verdict))
+              nil
+            end
+
+            def edge_words(verdict)
+              edge = verdict.edge
+              "#{verdict.source} edge #{edge.from} -> #{edge.to}; #{verdict.edges.size} written edge(s) lead there"
+            end
+
+            # The words the mint refuses with, from its own function. The scaffold branch of that
+            # function writes a file, so a run that asked for it is worded from the verdict instead.
+            def refusal(latest, verdict)
+              return "the decision is #{verdict.verdict}: #{verdict.reason}" if ENV["HECKS_SCAFFOLD"] == "1"
+
+              PostgresEra::LineageManager.resolve_edge!(context(latest))
+              "the decision is #{verdict.verdict}: #{verdict.reason}"
+            rescue Runtime::WiringError => e
+              e.message
+            end
+
+            def context(latest)
+              PostgresEra::LineageManager::Context.new(
+                registry: @held.registry, bluebook: @held.bluebook, current_text: nil, lineage: @lineage, role: nil,
+                directory: @held.directory, latest: latest
+              )
+            end
+
+            def covered?(latest, edge)
+              held = PostgresEra::LineageManager.held_bluebook(latest)
+              status = @report.check("coverage") do
+                PostgresEra::LineageManager.check_coverage!(@held.registry, @held.bluebook, held, edge)
+                [:pass, "no change in the shape goes unexplained by the edge"]
+              end
+              status == "pass"
+            end
+
+            def audit(eras, edge)
+              @report.check("audit") do
+                finding = EdgeAudit.call(@held, @lineage, eras, edge: edge)
+                finding.ok ? [:pass, audited(finding)] : [:refuse, refused(finding)]
+              end
+            end
+
+            def audited(finding)
+              rows = finding.after.values.sum(&:size)
+              "Ruby audit over #{rows} translated record(s), in place, read-only; parity not run: " \
+                "parity needs the full rehearsal"
+            end
+
+            def refused(finding) = "the audit refused: #{finding.refusals.first(5).join("; ")}"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require_relative "edge_guards"
+require_relative "watermark_guards"
+require_relative "command_line"
+require_relative "store"
+
+module Hecks
+  module Adapters
+    class JournalStore
+      module Readings
+        module MintPlan
+          # The guards that need the store, in the order the mint runs them: the era resolution
+          # (`EraResolution`, the one answer a boot and a rehearsal read), the held-shape refusal,
+          # then the edge guards, then the watermark.
+          class Inspection
+            LATER = %w[edge coverage audit].freeze
+
+            # @param report [Report] where each guard is recorded
+            # @param held [HeldDomain] the loaded domain
+            # @param options [Hash] `rehearsal_ref`, `rehearsal_watermark`, `rehearsal_verdict`
+            def initialize(report, held, options)
+              @report = report
+              @held = held
+              @options = options
+            end
+
+            # @return [String, nil] the command line to run when the mint would go ahead
+            def call
+              Store.reading(@held) { |lineage, db| inspect_store(lineage, db) }
+            end
+
+            private
+
+            def inspect_store(lineage, db)
+              eras = []
+              answer = nil
+              @report.check("eras") do
+                eras, answer = resolve(lineage)
+                [:pass, resolved_words(answer)]
+              end
+              watermark = WatermarkGuards.new(@report, db, lineage)
+              edge = proceed(lineage, eras, answer) if answer
+              watermark.call(**ref_options)
+              line(answer, eras, watermark) if edge
+            end
+
+            def resolve(lineage)
+              eras = @held.held_eras(lineage)
+              raise Runtime::WiringError, "#{@held.domain_name} holds no era; hold the first era before a mint" if eras.empty?
+
+              named = [*eras[0...-1], @held.named(eras.last)]
+              [eras, PostgresEra::LineageManager::EraResolution.resolve(
+                eras: named, bluebook: @held.bluebook, translations: @held.translations, directory: @held.directory
+              ) { lineage.last_ordinal }]
+            end
+
+            def resolved_words(answer)
+              "#{answer.status}: #{answer.reason || "the latest era holds the current shape"} " \
+                "(#{answer.held_count} era(s) held)"
+            end
+
+            def proceed(lineage, eras, answer)
+              return held_shape(answer) unless %w[behind unminted].include?(answer.status)
+
+              verdict = answer.verdict
+              @report.add("decision", :info, "#{verdict.verdict}#{": #{verdict.reason}" if verdict.reason} (#{answer.status})")
+              EdgeGuards.new(@report, @held, lineage).call(eras, verdict)
+            end
+
+            # The mint refuses a shape an era already holds; a current shape is no change at all.
+            def held_shape(answer)
+              @report.skip(LATER, "no mint: the shape is held")
+              return @report.settle("no_change") && nil if answer.status == "current"
+
+              @report.add("held_shape", :refuse, answer.reason)
+              nil
+            end
+
+            def ref_options
+              { ref: @options[:rehearsal_ref], watermark: @options[:rehearsal_watermark], verdict: @options[:rehearsal_verdict] }
+            end
+
+            def line(answer, eras, watermark)
+              return if @report.refused?
+
+              CommandLine.new(@held, answer.verdict, @held.named(eras.last), watermark.live).to_s
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative "../../held_domain"
+require_relative "report"
+require_relative "world"
+require_relative "inspection"
+
+module Hecks
+  module Adapters
+    class JournalStore
+      module Readings
+        module MintPlan
+          # The preflight of a mint: every guard the mint runs, against the store it would mint in,
+          # read-only. It decides nothing of its own; each guard calls the function the mint calls.
+          class Plan
+            AFTER_WORLD = %w[eras held_shape edge coverage audit watermark].freeze
+
+            # @param directory [String] the domain directory
+            # @param options [Hash] `bluebook`, `rehearsal_ref`, `rehearsal_watermark`,
+            #   `rehearsal_verdict`, `dev_dir`
+            def initialize(directory, **options)
+              @directory = directory
+              @options = options
+              @report = Report.new
+            end
+
+            # @return [Hash] `plan`, `guards`, `command` and `seconds`
+            def to_h
+              loaded = @report.check("load") { load_domain } == "pass"
+              held = @held if loaded
+              command = held && gather(held)
+              { domain: held&.domain_name, directory: @directory, plan: @report.plan,
+                guards: @report.guards, command: command, seconds: @report.seconds }
+            end
+
+            private
+
+            def load_domain
+              @held = HeldDomain.open(@directory, mode: :translated)
+              name = @options[:bluebook]
+              @held = HeldDomain.new(@held.registry, @held.directory, name) unless name.to_s.empty?
+              [:pass, "#{@held.domain_name} loaded from #{@held.directory}, no domain booted"]
+            end
+
+            def gather(held)
+              world = World.new(held, dev_dir: @options[:dev_dir])
+              @report.add("world", :info, world.flags)
+              @report.check("stranded") { world.stranded }
+              @report.add("quiesce", *world.quiesce)
+              return settle("disposable", "disposable: no mint needed") if world.disposable?
+              return settle("no_change", "#{held.adapter_name} holds no eras: no mint") unless held.capable?
+
+              Inspection.new(@report, held, @options).call
+            end
+
+            def settle(plan, why)
+              @report.settle(plan)
+              @report.skip(AFTER_WORLD, why)
+              nil
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    class JournalStore
+      module Readings
+        module MintPlan
+          # The guards a plan has run, in order, each with its status, its words and the seconds it
+          # took, and the plan they add up to.
+          class Report
+            STATUSES = %w[pass refuse skipped info].freeze
+
+            attr_reader :guards
+
+            def initialize
+              @guards = []
+              @started = now
+              @settled = nil
+            end
+
+            # Runs a guard's check, which answers `[status, detail]`, and records it with its
+            # time. A refusal the mint raises as a `WiringError` is the guard's refusal.
+            #
+            # @param name [String] the guard
+            # @yieldreturn [Array(Symbol, String)] the status and the detail
+            # @return [String] the status recorded
+            def check(name)
+              began = now
+              status, detail = yield
+              record(name, status, detail, began)
+            rescue Runtime::WiringError, Runtime::NotFound => e
+              record(name, :refuse, e.message.strip, began)
+            end
+
+            # @return [String] the status recorded
+            def add(name, status, detail) = record(name, status, detail, now)
+
+            # @param names [Array<String>] guards that did not run
+            # @param why [String] the reason, which is the guard that stopped the plan
+            # @return [void]
+            def skip(names, why) = names.each { |name| add(name, :skipped, why) }
+
+            # Fixes the plan whatever the guards say: a shape that did not move, a disposable
+            # ledger.
+            #
+            # @param plan [String] `no_change` or `disposable`
+            # @return [void]
+            def settle(plan) = @settled = plan
+
+            # @return [Boolean] whether a guard refused
+            def refused? = guards.any? { |guard| guard[:status] == "refuse" }
+
+            # @return [String] `would_mint`, `would_refuse`, `no_change` or `disposable`
+            def plan = @settled || (refused? ? "would_refuse" : "would_mint")
+
+            # @return [Float] the seconds since the plan began
+            def seconds = (now - @started).round(3)
+
+            private
+
+            def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+            def record(name, status, detail, began)
+              guards << { guard: name, status: status.to_s, detail: detail, seconds: (now - began).round(3) }
+              status.to_s
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    class JournalStore
+      module Readings
+        module MintPlan
+          # The store a plan reads: a connection that refuses every write, nothing provisioned, and
+          # a lineage over it that names no era. No temporary database or table is made.
+          module Store
+            module_function
+
+            # @param held [HeldDomain] the loaded domain
+            # @yield [Lineage, PG::Connection] the read-only lineage and its connection
+            # @return [Object] the block's value
+            # @raise [Runtime::WiringError] if the connection is refused
+            def reading(held)
+              db = PostgresEra.connect_for(held.domain_name, held.settings, provision: false)
+              db.exec("SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY")
+              yield lineage_over(db, held), db
+            ensure
+              db&.close
+            end
+
+            def lineage_over(db, held)
+              bluebook = held.bluebook
+              PostgresEra::Lineage.new(db, bluebook.name, formerly_known_as: bluebook.formerly_known_as, reading: true)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "../../../../../quality_control/adapters/qa_auto_mint"
+
+module Hecks
+  module Adapters
+    class JournalStore
+      module Readings
+        module MintPlan
+          # The watermark the mint reads and the freshness of a rehearsal against it, by the mint's
+          # own rule (`QaAutoMint.stale_watermark`): the ledger may move only by the run's own
+          # `Maintenance` record, counted by `Lineage#rows_of_after`.
+          class WatermarkGuards
+            RECORDED = <<~SQL
+              SELECT payload->>'watermark' AS watermark, payload->'rehearsal_verdict'->>'value' AS verdict
+              FROM events
+              WHERE name IN ('RehearsalVerdict', 'MintRequested')
+                AND (payload->>'rehearsal_ref' = $1 OR payload->'run'->>'value' = $1 OR aggregate_id = $1)
+              ORDER BY id DESC LIMIT 1
+            SQL
+            RULE = "the mint refuses when the ledger moved by anything but the run's own Maintenance record"
+
+            # @param report [Report] where each guard is recorded
+            # @param db [PG::Connection] the read-only connection
+            # @param lineage [Lineage] a read-only lineage over the store
+            def initialize(report, db, lineage)
+              @report = report
+              @db = db
+              @lineage = lineage
+            end
+
+            # @return [Integer] the live watermark, which is the `watermark=` the mint call takes
+            def live
+              @live ||= @lineage.last_ordinal
+            end
+
+            # Records the live watermark and, when a rehearsal ref is given, whether that rehearsal
+            # is stale.
+            #
+            # @param ref [String, nil] the rehearsal's run id
+            # @param watermark [Integer, nil] the watermark that rehearsal read
+            # @param verdict [String, nil] the verdict that rehearsal gave, when the caller has it
+            # @return [void]
+            def call(ref: nil, watermark: nil, verdict: nil)
+              @report.add("watermark", :info, "live watermark #{live}; pass watermark=#{live}; #{RULE}")
+              return unless ref
+
+              @report.check("rehearsal_ref") { rehearsal(ref, watermark, verdict) }
+            end
+
+            private
+
+            def rehearsal(ref, watermark, verdict)
+              watermark, verdict = recorded(ref) if watermark.nil? || verdict.nil?
+              return [:refuse, unknown(ref)] if watermark.nil?
+              return [:refuse, "rehearsal #{ref} said #{verdict.inspect}, not would_mint"] unless verdict == "would_mint"
+
+              freshness(ref, watermark)
+            end
+
+            def freshness(ref, watermark)
+              own = @lineage.rows_of_after(watermark, "maintenance", ref)
+              stale = QaAutoMint.stale_watermark(watermark, live, own_rows: own)
+              return [:refuse, stale] if stale
+
+              [:pass, "rehearsal #{ref} read watermark #{watermark}; #{own} row(s) above it are the run's own record"]
+            end
+
+            def unknown(ref)
+              "no record of rehearsal #{ref}: a rehearsal is kept by the process that ran it; pass " \
+                "rehearsal_watermark= and rehearsal_verdict= from its answer"
+            end
+
+            # The verdict and watermark of a rehearsal the ledger recorded, or a mint that took it.
+            def recorded(ref)
+              return [nil, nil] unless @db.exec("SELECT to_regclass('events')").getvalue(0, 0)
+
+              row = @db.exec_params(RECORDED, [ref]).first
+              row ? [row["watermark"]&.to_i, row["verdict"]] : [nil, nil]
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Hecks
+  module Adapters
+    class JournalStore
+      module Readings
+        module MintPlan
+          # What the world around a store says about a mint: the flags its world declares, the
+          # marker a stranded landing leaves (`MainMaintenance` refuses every mint while it stands)
+          # and the marker another agent leaves to quiesce the ledger. Only files and settings are
+          # read.
+          class World
+            # @param held [HeldDomain] the loaded domain
+            # @param dev_dir [String, nil] where the markers live; `HECKS_DEV_STATE`, else
+            #   `~/.claude/hecks-dev`
+            def initialize(held, dev_dir: nil)
+              @held = held
+              @dev_dir = dev_dir || ENV.fetch("HECKS_DEV_STATE", File.expand_path("~/.claude/hecks-dev"))
+            end
+
+            # @return [Boolean] whether the world declares `disposable_ledger true`
+            def disposable?
+              PostgresEra::LineageManager::DisposableLedger.declared?(@held.settings)
+            end
+
+            # @return [String] the flags, in words
+            def flags
+              "bound to #{@held.adapter_name}; mint_eras=#{setting(:mint_eras)}; " \
+                "disposable_ledger=#{setting(:disposable_ledger)}"
+            end
+
+            # @return [Boolean] whether the world lets a copy mint
+            def mint_eras? = [true, "true"].include?(setting(:mint_eras, false))
+
+            # @return [Array(Symbol, String)] refuse while a stranded landing stands
+            def stranded
+              return [:pass, "no stranded landing (#{stranded_path})"] unless File.exist?(stranded_path)
+
+              [:refuse, "mints are refused until the stranded landing is resolved: #{File.read(stranded_path).strip}"]
+            end
+
+            # @return [Array(Symbol, String)] the quiesce markers that stand, if any
+            def quiesce
+              found = Dir.glob([File.join(@dev_dir, "quiesce"), File.join(@dev_dir, "qa_quiesce.*")])
+              return [:info, "no quiesce marker in #{@dev_dir}"] if found.empty?
+
+              [:info, "quiesced by another agent: #{found.join(", ")}"]
+            end
+
+            private
+
+            def setting(key, default = "unset")
+              PostgresEra.setting(@held.settings, key, default: default)
+            end
+
+            def stranded_path
+              File.join(ENV.fetch("HECKS_MINT_STATE", File.join(@dev_dir, "mint")), "stranded.json")
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "mint_plan/plan"
+
+module Hecks
+  module Adapters
+    class JournalStore
+      module Readings
+        # The preflight of a mint, answered from the live store without copying it. It runs
+        # every guard the mint runs, each by the function the mint calls, over a connection that
+        # refuses writes, and never boots the domain, so it cannot claim an outbox row. The Rust
+        # parity pass and the engine run belong to the full rehearsal and are not part of it.
+        module MintPlan
+          # @param domain [Hash, String] the domain directory
+          # @param bluebook [Hash, String, nil] the bluebook of the directory to plan; the first
+          #   when absent
+          # @param rehearsal_ref [Hash, String, nil] the rehearsal run whose freshness to judge
+          # @param rehearsal_watermark [Hash, Integer, nil] the watermark that rehearsal read
+          # @param rehearsal_verdict [Hash, String, nil] the verdict that rehearsal gave
+          # @return [Hash] `text:` the plan as JSON: per guard `guard`, `status`, `detail`,
+          #   `seconds`; the overall `plan`; the `command` to run; the total `seconds`
+          # @raise [Runtime::NotFound] if a lower layer refuses outside a guard
+          def mint_plan(domain:, bluebook: nil, rehearsal_ref: nil, rehearsal_watermark: nil, rehearsal_verdict: nil)
+            answering do
+              asked = { bluebook: bluebook, rehearsal_ref: rehearsal_ref, rehearsal_verdict: rehearsal_verdict,
+                        rehearsal_watermark: rehearsal_watermark }.transform_values { |value| plain(value) }
+              asked[:rehearsal_watermark] &&= asked[:rehearsal_watermark].to_i
+              JSON.pretty_generate(Plan.new(plain(domain), **asked).to_h)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -20,11 +20,11 @@ module Hecks
 
           # 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.domain_name} matches era #{latest[:ordinal]} — nothing to scaffold." if
-              Runtime::StorageShape.project(shadow) == held.shape
+              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)