hecks 3.5.0 → 3.7.0

data/lib/hecks/fuzzing/failure_triage.rb

@@ -0,0 +1,80 @@
+require "digest"
+require "fileutils"
+require "json"
+
+module Hecks
+  module Fuzzing
+    # Tells one fuzz finding from another and keeps the smallest repro of each.
+    #
+    # A finding's identity is its property (or exception class), its message with the minted
+    # parts normalized away, and the shape of its shrunk steps (the verbs, in order). Two seeds
+    # that break the same property the same way share an identity however their ids differ.
+    module FailureTriage
+      # Directory, under the checkout, where minimized repros are kept.
+      REGRESSION_DIR = "spec/corpus/regressions".freeze
+
+      module_function
+
+      # @param property [String] the property name or exception class the finding opens with
+      # @param message [String, nil] the finding's message
+      # @param steps [Array<Hash>] the shrunk steps that reproduce it
+      # @return [String] a stable twelve-character identity
+      def signature(property, message, steps)
+        shape = steps.map { |step| step.key?("verb") ? step["verb"] : step[:verb] }
+        Digest::SHA256.hexdigest([property, normalize(message), shape].to_json)[0, 12]
+      end
+
+      # Strips the parts a run mints (ids, hex, numbers, quoted literals) so two runs of one
+      # defect read the same.
+      #
+      # @param message [String, nil]
+      # @return [String]
+      def normalize(message)
+        message.to_s
+               .gsub(/\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/i, "<uuid>")
+               .gsub(/\b0x[0-9a-f]+\b|\b[0-9a-f]{16,}\b/i, "<hex>")
+               .gsub(/(["']).*?\1/, "<str>")
+               .gsub(/-?\d+(?:\.\d+)?/, "<n>")
+               .squeeze(" ").strip
+      end
+
+      # Collapses findings to one per identity, keeping the smallest sequence of each.
+      #
+      # @param failures [Array<Hash>] findings carrying `:signature`, `:message` and `:steps`
+      # @return [Array<Hash>] one finding per distinct identity, each with `:triage` (the
+      #   identity) and `:duplicates` (how many findings it stands for)
+      def dedupe(failures)
+        failures.group_by { |failure| signature(failure[:signature], failure[:message], failure[:steps]) }
+                .map do |identity, group|
+          group.min_by { |failure| failure[:steps].length }.merge(triage: identity, duplicates: group.length)
+        end
+      end
+
+      # Writes a minimized repro under `<root>/spec/corpus/regressions/<domain>/`, in the
+      # `{name, note, steps}` shape `hecks run` replays. An existing file is never touched: the
+      # identity is in the file name, so a finding already kept is left as it was.
+      #
+      # @param root [String] the checkout
+      # @param domain_name [String] the domain's basename
+      # @param finding [Hash] a `dedupe` result carrying `:triage`, `:steps`, `:seed`, `:message`
+      # @return [String, nil] the path written, or nil when that finding was already kept
+      def persist(root, domain_name, finding)
+        dir = File.join(root, REGRESSION_DIR, domain_name)
+        path = File.join(dir, "#{finding.fetch(:triage)}.json")
+        return nil if File.exist?(path)
+
+        FileUtils.mkdir_p(dir)
+        File.write(path, JSON.pretty_generate(document(domain_name, finding)), mode: "wx")
+        path
+      rescue Errno::EEXIST
+        nil
+      end
+
+      def document(domain_name, finding)
+        { name:  "#{domain_name}-regression-#{finding.fetch(:triage)}",
+          note:  "hecks fuzz found #{finding[:signature]} at seed #{finding[:seed]}: #{finding[:message]}",
+          steps: finding.fetch(:steps) }
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/form_census/chapter_forms.rb

@@ -0,0 +1,38 @@
+module Hecks
+  module Fuzzing
+    module FormCensus
+      # The chapter-level constructs an aggregate takes part in, folded onto its own hash so the
+      # per-aggregate forms can read them.
+      #
+      # Policies and read models live on the chapter, not the aggregate: an `across` policy is
+      # attributed to the aggregate whose event it answers, and a read model to each aggregate it
+      # takes a head from.
+      module ChapterForms
+        module_function
+
+        # @param aggregate [Hash] one aggregate of an exported chapter
+        # @param chapter_ir [Hash] the exported chapter it belongs to
+        # @return [Hash] the aggregate with `across_policies` and `multi_head_read_models` added
+        def onto(aggregate, chapter_ir)
+          aggregate.merge("across_policies"        => across_policies(aggregate, chapter_ir),
+                          "multi_head_read_models" => multi_head_read_models(aggregate, chapter_ir))
+        end
+
+        # Policies with a target domain whose triggering event is qualified by this aggregate.
+        def across_policies(aggregate, chapter_ir)
+          (chapter_ir["policies"] || []).select do |policy|
+            !policy["target_domain"].to_s.empty? && policy["on_event"].to_s.split(".", 2).first == aggregate["name"]
+          end
+        end
+
+        # Read models composing two or more aggregate heads, one of them this aggregate.
+        def multi_head_read_models(aggregate, chapter_ir)
+          (chapter_ir["read_models"] || []).select do |read_model|
+            heads = read_model["aggregate_heads"] || []
+            heads.size >= 2 && heads.any? { |head| head["aggregate"] == aggregate["name"] }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/form_census/reference_forms.rb

@@ -0,0 +1,49 @@
+module Hecks
+  module Fuzzing
+    module FormCensus
+      # The reference-hop forms: a path crossing references, and a reference re-declared under
+      # another type. Each reads one aggregate's exported hash.
+      module ReferenceForms
+        # A given path crossing two references has at least this many segments.
+        TWO_HOP_GIVEN_PATH_LENGTH = 3
+
+        module_function
+
+        def two_hop_given?(aggregate)
+          FormCensus.commands(aggregate).any? do |verb|
+            (verb["givens"] || []).any? { |given| deep_lookup?(given["ast"]) }
+          end
+        end
+
+        # A `where` whose field crosses two `/` hops, as in `member/sponsor/standing`.
+        def multi_hop_where?(aggregate)
+          FormCensus.queries(aggregate).any? do |query|
+            (query["wheres"] || []).any? { |where| where["field"].to_s.count("/") >= 2 }
+          end
+        end
+
+        # A command attribute reusing the name of a reference attribute under a non-reference type.
+        def revalued_reference?(aggregate)
+          references = FormCensus.attributes(aggregate).select { |held| FormCensus.reference?(held) }
+                                 .to_set { |held| held["name"].to_s }
+          FormCensus.commands(aggregate).any? do |verb|
+            (verb["attributes"] || []).any? { |held| references.include?(held["name"].to_s) && !FormCensus.reference?(held) }
+          end
+        end
+
+        def deep_lookup?(node)
+          case node
+          when Hash
+            return true if node["op"] == "lookup" && Array(node["path"]).size >= TWO_HOP_GIVEN_PATH_LENGTH
+
+            node.each_value.any? { |child| deep_lookup?(child) }
+          when Array
+            node.any? { |child| deep_lookup?(child) }
+          else
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/form_census.rb

@@ -1,5 +1,7 @@
 require "json"
 require_relative "../corpus"
+require_relative "form_census/chapter_forms"
+require_relative "form_census/reference_forms"
 
 module Hecks
   module Fuzzing
@@ -9,29 +11,35 @@ module Hecks
     # they cannot drift. The unit is one aggregate: forms on one head meet at dispatch, forms in one
     # chapter do not.
     module FormCensus
-      # 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? },
-        "two_entities"       => ->(a) { entities(a).size >= 2 },
-        "composite_piece"    => ->(a) { entities(a).any? { |piece| (piece["identified_by"] || []).size >= 2 } },
-        "multi_emit"         => ->(a) { commands(a).any? { |verb| (verb["emits"] || []).size >= 2 } },
-        "lifecycle"          => ->(a) { !a["lifecycle"].nil? },
-        "piece_lifecycle"    => ->(a) { entities(a).any? { |piece| !piece["lifecycle"].nil? } },
-        "has_query"          => ->(a) { queries(a).any? },
-        "list_attr"          => ->(a) { attributes(a).any? { |held| held["list"] } },
-        "reference_attr"     => ->(a) { attributes(a).any? { |held| reference?(held) } },
-        "closed_set"         => ->(a) { (a["value_objects"] || []).any? { |shape| shape["closed_set"] } },
-        "has_default"        => ->(a) { attributes(a).any? { |held| !held["default"].nil? } },
-        "has_optional"       => ->(a) { commands(a).any? { |verb| (verb["attributes"] || []).any? { |held| held["optional"] } } },
+        "composite_id"          => ->(a) { (a["identified_by"] || []).size >= 2 },
+        "has_entity"            => ->(a) { entities(a).any? },
+        "two_entities"          => ->(a) { entities(a).size >= 2 },
+        "composite_piece"       => ->(a) { entities(a).any? { |piece| (piece["identified_by"] || []).size >= 2 } },
+        "multi_emit"            => ->(a) { commands(a).any? { |verb| (verb["emits"] || []).size >= 2 } },
+        "lifecycle"             => ->(a) { !a["lifecycle"].nil? },
+        "piece_lifecycle"       => ->(a) { entities(a).any? { |piece| !piece["lifecycle"].nil? } },
+        "has_query"             => ->(a) { queries(a).any? },
+        "list_attr"             => ->(a) { attributes(a).any? { |held| held["list"] } },
+        "reference_attr"        => ->(a) { attributes(a).any? { |held| reference?(held) } },
+        "closed_set"            => ->(a) { (a["value_objects"] || []).any? { |shape| shape["closed_set"] } },
+        "has_default"           => ->(a) { attributes(a).any? { |held| !held["default"].nil? } },
+        "has_optional"          => ->(a) { optional_command_attribute?(a) },
         # Reference-hop forms, then `corrects` and `role`; entity commands count too.
-        "corrects"           => ->(a) { every_command(a).any? { |verb| corrects?(verb) } },
-        "role_gated"         => ->(a) { every_command(a).any? { |verb| !verb["role"].to_s.empty? } },
-        "two_hop_given"      => ->(a) { two_hop_given?(a) },
-        "multi_hop_where"    => ->(a) { multi_hop_where?(a) },
-        "revalued_reference" => ->(a) { revalued_reference?(a) }
+        "corrects"              => ->(a) { every_command(a).any? { |verb| corrects?(verb) } },
+        "role_gated"            => ->(a) { every_command(a).any? { |verb| !verb["role"].to_s.empty? } },
+        "two_hop_given"         => ->(a) { ReferenceForms.two_hop_given?(a) },
+        "multi_hop_where"       => ->(a) { ReferenceForms.multi_hop_where?(a) },
+        "revalued_reference"    => ->(a) { ReferenceForms.revalued_reference?(a) },
+        # Chapter-level constructs, attributed to the aggregate they name (see `ChapterForms`).
+        "cross_domain_policy"   => ->(a) { (a["across_policies"] || []).any? },
+        "multi_head_read_model" => ->(a) { (a["multi_head_read_models"] || []).any? }
       }.freeze
 
       module_function
@@ -45,42 +53,16 @@ module Hecks
 
       def corrects?(verb) = (verb["mutations"] || []).any? { |change| change["op"].to_s == "corrects" }
 
+      def optional_command_attribute?(aggregate)
+        commands(aggregate).any? { |verb| (verb["attributes"] || []).any? { |held| held["optional"] } }
+      end
+
       def attributes(aggregate) = aggregate["attributes"] || []
 
       def queries(aggregate)    = aggregate["queries"] || []
 
       def reference?(attribute) = attribute["type"].to_s.start_with?("Reference<")
 
-      def two_hop_given?(aggregate)
-        commands(aggregate).any? { |verb| (verb["givens"] || []).any? { |given| deep_lookup?(given["ast"]) } }
-      end
-
-      # A `where` whose field crosses two `/` hops, as in `member/sponsor/standing`.
-      def multi_hop_where?(aggregate)
-        queries(aggregate).any? { |query| (query["wheres"] || []).any? { |where| where["field"].to_s.count("/") >= 2 } }
-      end
-
-      # A command attribute reusing the name of a reference attribute under a non-reference type.
-      def revalued_reference?(aggregate)
-        references = attributes(aggregate).select { |held| reference?(held) }.to_set { |held| held["name"].to_s }
-        commands(aggregate).any? do |verb|
-          (verb["attributes"] || []).any? { |held| references.include?(held["name"].to_s) && !reference?(held) }
-        end
-      end
-
-      def deep_lookup?(node)
-        case node
-        when Hash
-          return true if node["op"] == "lookup" && Array(node["path"]).size >= TWO_HOP_GIVEN_PATH_LENGTH
-
-          node.each_value.any? { |child| deep_lookup?(child) }
-        when Array
-          node.any? { |child| deep_lookup?(child) }
-        else
-          false
-        end
-      end
-
       def properties(aggregate)
         FORMS.transform_values { |form| form.call(aggregate) }
       end
@@ -101,7 +83,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(ChapterForms.onto(aggregate, chapter_ir))]
         end
       end
 
@@ -114,22 +96,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,148 @@
+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 this process's
+        # 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   ||= scratch_schema(database)
+          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
+
+        # Several pool children may reach this at once: one wins the CREATE, and the rest see the
+        # database exist, or wait out the moment the template database is busy and look again.
+        def create_database_if_missing(database)
+          admin = PG.connect(dbname: "postgres")
+          3.times do
+            break if database_exists?(admin, database)
+
+            create_database(admin, database)
+          end
+          admin.close
+        end
+
+        def database_exists?(admin, database)
+          admin.exec_params("SELECT 1 FROM pg_database WHERE datname = $1", [database]).ntuples.positive?
+        end
+
+        def create_database(admin, database)
+          admin.exec(%(CREATE DATABASE "#{database}"))
+        rescue PG::DuplicateDatabase, PG::UniqueViolation
+          nil
+        rescue PG::ObjectInUse
+          sleep(0.2)
+        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/scratch_schema.rb

@@ -0,0 +1,27 @@
+module Hecks
+  module Fuzzing
+    module IsolatedBoot
+      # Which Postgres scratch schema a fuzz boot uses: one per pool child, so children can fuzz
+      # one database at once, or the shared default for any other process.
+      module ScratchSchema
+        # The schema this process boots into. A pool child names its own in `FUZZ_SCHEMA_ENV`, so
+        # several children can fuzz one database at once; it is dropped when the child exits.
+        # Any other process shares `FUZZ_POSTGRES_SCHEMA`, which is safe only one boot at a time.
+        def scratch_schema(database)
+          named = ENV.fetch(FUZZ_SCHEMA_ENV, nil)
+          return FUZZ_POSTGRES_SCHEMA unless named
+
+          @fuzz_schema_cleanups ||= {}
+          @fuzz_schema_cleanups[named] ||= at_exit { drop_schema_quietly(database, named) }
+          named
+        end
+
+        def drop_schema_quietly(database, schema)
+          reset_schema!(database, schema, create: false)
+        rescue PG::Error
+          nil
+        end
+      end
+    end
+  end
+end