hecks 3.5.0 → 3.6.0

data/lib/hecks/fuzzing/form_census.rb

@@ -12,6 +12,12 @@ module Hecks
       # A given path crossing two references has at least this many segments.
       TWO_HOP_GIVEN_PATH_LENGTH = 3
 
+      # Ports and adapters a census boots with, relative to the repository root.
+      CENSUS_SUPPORT = [
+        "lib/hecks/ports/persistence.port", "lib/hecks/ports/extraction.port",
+        "lib/hecks/adapters/driven/memory.adapter", "lib/hecks/adapters/driven/prism.adapter"
+      ].freeze
+
       FORMS = {
         "composite_id"       => ->(a) { (a["identified_by"] || []).size >= 2 },
         "has_entity"         => ->(a) { entities(a).any? },
@@ -101,7 +107,7 @@ module Hecks
 
       def aggregates_in(chapter_ir)
         (chapter_ir["aggregates"] || []).map do |aggregate|
-          ["#{chapter_ir['name']}::#{aggregate['name']}", properties(aggregate)]
+          ["#{chapter_ir["name"]}::#{aggregate["name"]}", properties(aggregate)]
         end
       end
 
@@ -114,22 +120,26 @@ module Hecks
       #
       # @raise [ArgumentError] if `domain_path` has no bluebook files
       def census(domain_path)
-        root = File.expand_path("../../..", __dir__)
         files = bluebook_files(domain_path)
         raise ArgumentError, "#{domain_path} has no bluebook/*.bluebook (or *.bluebook) to measure" if files.nil?
 
         registry = Hecks::Runtime::Registry.new(root: File.expand_path(domain_path))
         Hecks.with_registry(registry) do
-          Kernel.load(File.join(root, "lib/hecks/ports/persistence.port"))
-          Kernel.load(File.join(root, "lib/hecks/ports/extraction.port"))
-          Kernel.load(File.join(root, "lib/hecks/adapters/driven/memory.adapter"))
-          Kernel.load(File.join(root, "lib/hecks/adapters/driven/prism.adapter"))
+          support_files.each { |file| Kernel.load(file) }
           files.each { |file| Kernel.load(file) }
         end
 
+        aggregates_in(exported_chapter(registry))
+      end
+
+      def support_files
+        root = File.expand_path("../../..", __dir__)
+        CENSUS_SUPPORT.map { |relative| File.join(root, relative) }
+      end
+
+      def exported_chapter(registry)
         chapter_name = registry.bluebooks.keys.first
-        exported = JSON.parse(JSON.generate(Hecks::Projector::Exporter.call(registry).fetch(chapter_name)))
-        aggregates_in(exported)
+        JSON.parse(JSON.generate(Hecks::Projector::Exporter.call(registry).fetch(chapter_name)))
       end
     end
   end

data/lib/hecks/fuzzing/generated_domain_check.rb

@@ -15,6 +15,9 @@ module Hecks
     module GeneratedDomainCheck
       DIFFERENTIAL_MODES = %i[differential self_consistency properties_in_differential].freeze
 
+      # What one check run is configured with beyond the domain and seed count.
+      Settings = Struct.new(:steps, :adversarial, :binary, :differ, :match, :shrink_budget, keyword_init: true)
+
       module_function
 
       # Checks one generated domain over up to `seeds` sequences, stopping at the first finding.
@@ -23,22 +26,30 @@ module Hecks
       # `match` (`{"mode" =>, "signature" =>}`) keeps only a finding that still matches, so
       # domain-level shrinking can ask whether a smaller domain shows the same finding.
       #
+      # Beyond the required keywords it takes `binary:`, `differ:`, `match:` (default nil) and
+      # `shrink_budget:` (default 0).
+      #
       # @return [Hash] `"status"` is `"invalid"`, `"clean"` or `"found"`; a found finding is
       #   `#finding` merged with `"seeds_run"`, plus `"shrunk_steps"` if `shrink_budget` > 0
-      def run(domain_path, seeds:, steps:, adversarial:, binary: nil, differ: nil, match: nil, shrink_budget: 0)
+      def run(domain_path, seeds:, steps:, adversarial:, **)
+        settings = Settings.new(shrink_budget: 0, steps: steps, adversarial: adversarial, **)
         error = boot_error(domain_path)
         return { "status" => "invalid", "error" => error } if error
 
         (1..seeds).each do |seed|
-          finding = check_seed(domain_path, seed, steps, adversarial, binary, differ, match)
-          next unless finding
-
-          finding["shrunk_steps"] = shrink(domain_path, finding, binary, differ, shrink_budget) if shrink_budget.positive?
-          return finding.merge("status" => "found", "seeds_run" => seed)
+          finding = check_seed(domain_path, seed, settings)
+          return found(domain_path, finding, settings, seed) if finding
         end
         { "status" => "clean", "seeds_run" => seeds }
       end
 
+      def found(domain_path, finding, settings, seed)
+        if settings.shrink_budget.positive?
+          finding["shrunk_steps"] = shrink(domain_path, finding, settings.binary, settings.differ, settings.shrink_budget)
+        end
+        finding.merge("status" => "found", "seeds_run" => seed)
+      end
+
       def boot_error(domain_path)
         IsolatedBoot.call(domain_path) { |copy| Hecks.boot(copy, environment: nil) }
         nil
@@ -46,13 +57,14 @@ module Hecks
         "#{e.class}: #{e.message.lines.first&.strip}"
       end
 
-      def check_seed(domain_path, seed, steps, adversarial, binary, differ, match)
-        sequence = SequenceGenerator.generate(domain_path, seed: seed, steps: steps, adversarial: adversarial)
+      def check_seed(domain_path, seed, settings)
+        sequence = SequenceGenerator.generate(domain_path, seed: seed, steps: settings.steps,
+                                                           adversarial: settings.adversarial)
       rescue StandardError => e
-        finding(seed, :generator, [{ field: "generator_crash", detail: "#{e.class}: #{e.message}" }], [], match)
+        finding(seed, :generator, [{ field: "generator_crash", detail: "#{e.class}: #{e.message}" }], [], settings.match)
       else
-        outcomes(domain_path, sequence, binary, differ).each do |mode, divergences|
-          found = finding(seed, mode, divergences, sequence, match)
+        outcomes(domain_path, sequence, settings.binary, settings.differ).each do |mode, divergences|
+          found = finding(seed, mode, divergences, sequence, settings.match)
           return found if found
         end
         nil

data/lib/hecks/fuzzing/isolated_boot/copying.rb

@@ -0,0 +1,62 @@
+require "fileutils"
+
+module Hecks
+  module Fuzzing
+    module IsolatedBoot
+      # Copies a domain directory, following symlinks, together with the vendored bluebooks
+      # its hecksagons name.
+      module Copying
+        # A vendored package named by `attaches "name", from: :vendor`.
+        VENDORED_ATTACHED = /attaches\s*\(?\s*"([\w-]+)"\s*\)?\s*,\s*from:\s*:vendor/
+
+        # Copies `source` into `destination`, following symlinks rather than reproducing
+        # them (cp_r would copy a symlink as a symlink, dangling once the source tree is
+        # gone), and carries any vendored bluebooks the copy's hecksagons name.
+        def copy_dereferencing(source, destination)
+          copy_files(source, destination)
+          carry_vendored_bluebooks!(source, destination)
+        end
+
+        # Copies every file under `source` into `destination`, following symlinks.
+        def copy_files(source, destination)
+          FileUtils.mkdir_p(destination)
+          Dir.glob(File.join(source, "**", "*"), File::FNM_DOTMATCH).each do |path|
+            next if [".", ".."].include?(File.basename(path))
+
+            copy_entry(path, File.join(destination, path.delete_prefix("#{source}/")))
+          end
+        end
+
+        # Copies one file or creates one directory at `target`.
+        def copy_entry(path, target)
+          return FileUtils.mkdir_p(target) if File.directory?(path)
+
+          FileUtils.mkdir_p(File.dirname(target))
+          copy_if_present(path, target)
+        end
+
+        def copy_if_present(path, target)
+          FileUtils.cp(path, target)
+        rescue Errno::ENOENT
+          # A sibling can vanish between listing and copy under parallel workers;
+          # skip a file that's already gone.
+        end
+
+        # Copies vendored bluebook packages a copy's hecksagons name into the copy, since
+        # `Hecks.boot` only sees the domain directory itself, not `vendor/`.
+        def carry_vendored_bluebooks!(source, destination)
+          names = Dir.glob(File.join(destination, "**", "*.hecksagon")).flat_map do |path|
+            text = File.read(path)
+            text.scan(VENDORED_ATTACHED).flatten
+          end
+          names.uniq.each do |name|
+            package = File.join(File.dirname(source), "vendor", "embryonaut_bluebooks", name)
+            next unless File.directory?(package)
+
+            copy_files(package, File.join(File.dirname(destination), "vendor", "embryonaut_bluebooks", name))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/isolated_boot/postgres_scratch.rb

@@ -0,0 +1,133 @@
+module Hecks
+  module Fuzzing
+    module IsolatedBoot
+      # Rebinds a copied domain to a scratch Postgres schema and prepares that schema.
+      module PostgresScratch
+        # Rewrites every `.hecksagon` in the copy to bind through Postgres, against the
+        # shared scratch schema unless the caller names its own via `scratch:`.
+        def rebind_to_postgres!(copy, database: nil, schema: nil)
+          require "pg"
+          database ||= FUZZ_POSTGRES_DATABASE
+          schema   ||= FUZZ_POSTGRES_SCHEMA
+          rewrite_bindings!(copy, "Postgres")
+          strip_translations!(copy)
+          ensure_fuzz_schema!(database, schema)
+
+          # One `.world` per directory a `.hecksagon` lives in, not one at the copy's
+          # root — `Folder#load_domain` globs `*.world` non-recursively.
+          write_worlds!(copy, "hecks_fuzz_postgres.world") { |name| postgres_world(name, database, schema) }
+          write_unbound_chapter_worlds!(copy)
+        end
+
+        def postgres_world(name, database, schema)
+          <<~WORLD
+            Hecks.world "#{name}" do
+              default_adapter "Postgres"
+              persisted_by("Postgres") do
+                database "#{database}"
+                schema "#{schema}"
+              end
+            end
+          WORLD
+        end
+
+        # Creates `database` once per process (memoized) and drops/recreates `schema`
+        # inside it on every call — that's what isolates one ephemeral boot from the next.
+        def ensure_fuzz_schema!(database = FUZZ_POSTGRES_DATABASE, schema = FUZZ_POSTGRES_SCHEMA)
+          # PG::Connection only closes its socket when GC finalizes it, and a tight fuzz
+          # loop opens connections faster than GC reclaims them — without this, a run
+          # exhausts Postgres's max_connections after a few dozen ephemeral boots.
+          GC.start
+
+          @fuzz_databases_ready ||= {}
+          unless @fuzz_databases_ready[database]
+            create_database_if_missing(database)
+            @fuzz_databases_ready[database] = true
+          end
+
+          reset_schema!(database, schema, create: true)
+        end
+
+        # `:postgres_era` is the only mode that exercises era/lineage-bound SQL; plain
+        # `:postgres` never touches that machinery. Unlike `:postgres`, there's no shared
+        # scratch constant here — `database:`/`schema:` are required keyword args because
+        # the caller (`hecks quality_control query sweep.run --persistence-parity`) owns that
+        # database's lifecycle.
+        def rebind_to_postgres_era!(copy, database:, schema:)
+          require "pg"
+          require_owned_scratch!(database, schema)
+
+          rewrite_bindings!(copy, "PostgresEra")
+          ensure_postgres_era_schema!(database: database, schema: schema)
+
+          write_worlds!(copy, "hecks_fuzz_postgres_era.world") { |name| postgres_era_world(name, database, schema) }
+          write_unbound_chapter_worlds!(copy)
+        end
+
+        def require_owned_scratch!(database, schema)
+          return unless database.to_s.empty? || schema.to_s.empty?
+
+          raise ArgumentError,
+                "adapter: :postgres_era requires both database: and schema: — a throwaway database/schema " \
+                "THIS CALLER creates and drops itself (see rebind_to_postgres_era!'s own header). " \
+                "There is no shared default, unlike :postgres, so the caller cannot forget to own the lifecycle."
+        end
+
+        # The world text for one chapter on `PostgresEra`.
+        #
+        # `schema:` isolates one ephemeral boot from the next, the same job
+        # `FUZZ_POSTGRES_SCHEMA` does for `:postgres` (`connect_for` idempotently
+        # creates it; `ensure_postgres_era_schema!` only needs to drop it first).
+        #
+        # `allow_superuser true` is deliberate: PostgresEra normally refuses to boot as
+        # a superuser (its era write-fence is row-level security, which a superuser
+        # bypasses), to protect a real ledger from stale writes. This is a throwaway
+        # schema the caller creates and drops, comparing Memory against PostgresEra's
+        # SQL — the era fence isn't under test, so opting in here is safe.
+        def postgres_era_world(name, database, schema)
+          <<~WORLD
+            Hecks.world "#{name}" do
+              default_adapter "PostgresEra"
+              persisted_by("PostgresEra") do
+                database "#{database}"
+                schema "#{schema}"
+                allow_superuser true
+              end
+            end
+          WORLD
+        end
+
+        # Mirrors `ensure_fuzz_schema!`'s GC.start-before-connecting fix for the same
+        # max_connections exhaustion. Creates `database` if missing, but never drops
+        # it — that's the caller's job (see `rebind_to_postgres_era!`).
+        def ensure_postgres_era_schema!(database:, schema:)
+          GC.start
+
+          create_database_if_missing(database)
+          reset_schema!(database, schema, create: false)
+        end
+
+        def create_database_if_missing(database)
+          admin = PG.connect(dbname: "postgres")
+          exists = admin.exec_params(
+            "SELECT 1 FROM pg_database WHERE datname = $1", [database]
+          ).ntuples.positive?
+          admin.exec(%(CREATE DATABASE "#{database}")) unless exists
+          admin.close
+        end
+
+        # Drops `schema` from `database`, and creates it again when `create` is true.
+        def reset_schema!(database, schema, create:)
+          db = PG.connect(dbname: database)
+          # Quiet on purpose: an ordinary DROP CASCADE NOTICEs per dropped object, which
+          # would bury hecks fuzz's own output on every boot after the first.
+          db.exec("SET client_min_messages = warning")
+          quoted = db.quote_ident(schema)
+          db.exec("DROP SCHEMA IF EXISTS #{quoted} CASCADE")
+          db.exec("CREATE SCHEMA #{quoted}") if create
+          db.close
+        end
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/isolated_boot/worlds.rb

@@ -0,0 +1,102 @@
+module Hecks
+  module Fuzzing
+    module IsolatedBoot
+      # Rewrites the `.hecksagon` bindings and `.world` files of a copied domain.
+      module Worlds
+        # The name of a `Hecks.hecksagon` block.
+        HECKSAGON_NAME = /Hecks\.hecksagon\s+"([^"]+)"/
+
+        # The name of a `Hecks.bluebook` block.
+        BLUEBOOK_NAME = /Hecks\.bluebook[\s(]+"([^"]+)"/
+
+        # Replaces every `.world` in the copy with one that declares only `default_adapter`,
+        # so an aggregate left unbound by its hecksagon still falls back to `adapter_name`.
+        def write_default_worlds!(copy, adapter_name)
+          write_worlds!(copy, "hecks_fuzz_default.world") do |name|
+            <<~WORLD
+              Hecks.world "#{name}" do
+                default_adapter "#{adapter_name}"
+              end
+            WORLD
+          end
+        end
+
+        # Gives every chapter with no hecksagon block (so no bind) a world of its own that
+        # falls back to Memory, since the worlds `write_worlds!` wrote require a database
+        # a chapter with no bind can't provide.
+        def write_unbound_chapter_worlds!(copy)
+          named = Dir.glob(File.join(copy, "**", "*.hecksagon")).flat_map { |path| hecksagon_names_in(path) }
+          bluebooks = Dir.glob(File.join(copy, "**", "*.bluebook")).group_by { |path| File.dirname(path) }
+          bluebooks.each do |dir, files|
+            unbound = unbound_names(files, named)
+            named.concat(unbound)
+            write_unbound_world(dir, unbound) unless unbound.empty?
+          end
+        end
+
+        # The bluebook names `files` declare that `named` does not already cover.
+        def unbound_names(files, named)
+          files.flat_map { |path| File.read(path).scan(BLUEBOOK_NAME).flatten }.uniq - named
+        end
+
+        # Writes `dir`'s one world file falling every `unbound` chapter back to Memory.
+        def write_unbound_world(dir, unbound)
+          worlds = unbound.map { |name| %(Hecks.world "#{name}" do\n  default_adapter "Memory"\nend\n) }
+          File.write(File.join(dir, "hecks_fuzz_unbound.world"), worlds.join("\n"))
+        end
+
+        # Writes one `.world` per directory holding a `.hecksagon`, naming every
+        # `Hecks.hecksagon` block found there, and deletes every other `.world` in the
+        # copy. One write per directory, not per file — a domain can split hecksagon
+        # blocks (e.g. `context_map.hecksagon` beside the main one) across sibling files
+        # in the same directory, and a second `File.write` to the same path would drop
+        # the first file's names.
+        def write_worlds!(copy, world_file, &world_for)
+          hecksagon_names_by_dir(copy).each do |dir, names|
+            next if names.empty?
+
+            File.write(File.join(dir, world_file), names.uniq.map(&world_for).join("\n"))
+          end
+
+          Dir.glob(File.join(copy, "**", "*.world")).each do |path|
+            File.delete(path) unless File.basename(path) == world_file
+          end
+        end
+
+        # The `Hecks.hecksagon` names declared in each directory under `copy`.
+        def hecksagon_names_by_dir(copy)
+          names_by_dir = Hash.new { |hash, dir| hash[dir] = [] }
+          Dir.glob(File.join(copy, "**", "*.hecksagon")).each do |hecksagon_path|
+            names_by_dir[File.dirname(hecksagon_path)].concat(hecksagon_names_in(hecksagon_path))
+          end
+          names_by_dir
+        end
+
+        def hecksagon_names_in(path) = File.read(path).scan(HECKSAGON_NAME).flatten
+
+        # Deletes every `translations/*.bluebook` in the copy. A compute/rekey translation
+        # edge refuses to boot under any non-lineage-capable adapter (only `PostgresEra`
+        # answers `lineage_capable? == true`), so every other mode strips it here rather
+        # than tripping that refusal. Safe to drop: an ephemeral, zero-history boot never
+        # has a pre-existing era-1 row to translate — the edge only matters at mint time,
+        # against a real database, never here.
+        def strip_translations!(copy)
+          Dir.glob(File.join(copy, "**", "translations", "*.bluebook")).each { |path| File.delete(path) }
+        end
+
+        # Rewrites every `persisted_by` bind — aggregate-scoped or bare at the hecksagon's
+        # own root, naming its adapter as a literal or through a local variable — to name
+        # `adapter_name`, and drops every `projected_by` bind outright (unread rather than
+        # broken, since `Registry#read_repository` falls back to the authoritative repo).
+        def rewrite_bindings!(copy, adapter_name)
+          Dir.glob(File.join(copy, "**", "*.hecksagon")).each do |path|
+            lines = File.readlines(path).grep_v(/\bprojected_by\s*\(?\s*"/)
+            # Horizontal space only: a newline ends the statement, and the next one must stay.
+            bind = /persisted_by[ \t]*\(?[ \t]*(?:"[^"]+"|[a-z_]\w*)[ \t]*\)?/
+            File.write(path, lines.join.gsub(bind, "persisted_by(\"#{adapter_name}\")"))
+          end
+        end
+      end
+    end
+  end
+end