hecks 2.9.0 → 3.0.0

data/lib/hecks/fuzzing/era_boundary.rb

@@ -0,0 +1,71 @@
+require "hecks/ports/persistence/plugins/era"
+
+module Hecks
+  module Fuzzing
+    # Checks a target's real, already-configured `PostgresEra` ledger for
+    # ancestor eras still holding writes nobody has merged forward.
+    module EraBoundary
+      module_function
+
+      # `kind:` on a `checked: false` result distinguishes a target with no
+      # lineage to audit (`:not_applicable`) from an audit that failed to
+      # run (`:error`) — `hecks quality_control ask run` holds the first and surfaces the
+      # second as a finding, instead of treating both as a clean audit.
+      def diverged_ancestor_writes(domain_path)
+        registry, directory = load_registry(domain_path)
+        bluebook = registry.bluebooks.values.first
+        return failed("no bluebook in #{directory}") unless bluebook
+
+        first = bluebook.aggregates.first
+        return not_applicable("#{bluebook.name} declares no aggregates") unless first
+
+        adapter_name = Hecks::Ports::Persistence::BindingPolicy.resolve(registry, bluebook.name, first).adapter
+        unless adapter_name == "PostgresEra"
+          return not_applicable("#{bluebook.name} is bound to #{adapter_name}, not PostgresEra")
+        end
+
+        settings = registry.binding_settings(bluebook.name, Hecks::Ports::Persistence::VERB, adapter_name)
+        db = Hecks::Adapters::PostgresEra.connect_for(bluebook.name, settings)
+        begin
+          lineage = Hecks::Adapters::PostgresEra::Lineage.new(db, bluebook.name)
+          lineage.ensure_base!
+          eras = lineage.eras
+          breakdown = if eras.size > 1
+                        (1...eras.last[:ordinal]).map do |ordinal|
+                          { ordinal: ordinal, diverged: lineage.diverged_count(ordinal) }
+                        end
+                      else
+                        []
+                      end
+          { checked: true, era_count: eras.size, breakdown: breakdown, diverged_total: breakdown.sum { |b| b[:diverged] } }
+        ensure
+          db.close
+        end
+      rescue StandardError => e
+        # A refused connection or malformed `.world` settings is not the
+        # same as nothing to audit, so this reports `:error`, never the
+        # benign `:not_applicable` shape.
+        failed("#{e.class}: #{e.message}")
+      end
+
+      def not_applicable(reason) = { checked: false, kind: :not_applicable, reason: reason }
+
+      def failed(reason) = { checked: false, kind: :error, reason: reason }
+
+      # Boots a fresh registry for the target domain, never the ledger's own
+      # registry (this asks about the swept target's lineage, not
+      # QualityControl's own).
+      def load_registry(domain_path)
+        loading = Hecks::Ports::Loading.bootstrap
+        directory = loading.bluebook_directory(domain_path)
+        registry = Hecks::Runtime::Registry.new(root: File.dirname(directory))
+        Hecks.with_registry(registry) do
+          loading.load_library
+          loading.load_project(loading.shared_root(nil, directory))
+          loading.load_domain(directory)
+        end
+        [registry, directory]
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/form_census.rb

@@ -0,0 +1,136 @@
+require "json"
+require_relative "../corpus"
+
+module Hecks
+  module Fuzzing
+    # The declared forms an aggregate can exhibit, and the pairs it puts together.
+    #
+    # Shared by the combination-coverage spec and `hecks quality_control judge_novelty` so 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
+
+      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"] } } },
+        # 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) }
+      }.freeze
+
+      module_function
+
+      def entities(aggregate)   = aggregate["entities"] || []
+
+      def commands(aggregate)   = aggregate["commands"] || []
+
+      # An aggregate's commands, its entities' included.
+      def every_command(aggregate) = commands(aggregate) + entities(aggregate).flat_map { |piece| commands(piece) }
+
+      def corrects?(verb) = (verb["mutations"] || []).any? { |change| change["op"].to_s == "corrects" }
+
+      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
+
+      def pairs
+        FORMS.keys.combination(2).map { |pair| pair_key(*pair) }
+      end
+
+      def pair_key(left, right) = [left, right].sort.join(" + ")
+
+      def covered_pairs(held)
+        held.each_with_object(Hash.new { |h, k| h[k] = [] }) do |(name, shows), covered|
+          shows.select { |_, present| present }.keys.combination(2).each do |left, right|
+            covered[pair_key(left, right)] << name
+          end
+        end
+      end
+
+      def aggregates_in(chapter_ir)
+        (chapter_ir["aggregates"] || []).map do |aggregate|
+          ["#{chapter_ir['name']}::#{aggregate['name']}", properties(aggregate)]
+        end
+      end
+
+      def bluebook_files(domain_path)
+        Hecks::Corpus.bluebook_files(domain_path)
+      end
+
+      # The census over a domain on disk, booted lightweight (no `Hecks.boot`, no database).
+      # Only the first-loaded chapter is measured.
+      #
+      # @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"))
+          files.each { |file| Kernel.load(file) }
+        end
+
+        chapter_name = registry.bluebooks.keys.first
+        exported = JSON.parse(JSON.generate(Hecks::Projector::Exporter.call(registry).fetch(chapter_name)))
+        aggregates_in(exported)
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/generated_domain_check.rb

@@ -0,0 +1,93 @@
+require "json"
+require_relative "isolated_boot"
+require_relative "sequence_generator"
+require_relative "replay"
+require_relative "shrinker"
+require_relative "differential"
+
+module Hecks
+  module Fuzzing
+    # The child-process half of `hecks quality_control check_generated_domains`: checks one
+    # generated domain.
+    #
+    # One domain per process, since every generated domain is named `QaGenerated`.
+    # A domain that fails to boot is `invalid` (a generator defect), not a finding.
+    module GeneratedDomainCheck
+      DIFFERENTIAL_MODES = %i[differential self_consistency properties_in_differential].freeze
+
+      module_function
+
+      # Checks one generated domain over up to `seeds` sequences, stopping at the first finding.
+      #
+      # With a compiled `binary` it diffs Ruby against Rust; without one it replays Ruby only.
+      # `match` (`{"mode" =>, "signature" =>}`) keeps only a finding that still matches, so
+      # domain-level shrinking can ask whether a smaller domain shows the same finding.
+      #
+      # @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)
+        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)
+        end
+        { "status" => "clean", "seeds_run" => seeds }
+      end
+
+      def boot_error(domain_path)
+        IsolatedBoot.call(domain_path) { |copy| Hecks.boot(copy, environment: nil) }
+        nil
+      rescue StandardError, ScriptError => e
+        "#{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)
+      rescue StandardError => e
+        finding(seed, :generator, [{ field: "generator_crash", detail: "#{e.class}: #{e.message}" }], [], match)
+      else
+        outcomes(domain_path, sequence, binary, differ).each do |mode, divergences|
+          found = finding(seed, mode, divergences, sequence, match)
+          return found if found
+        end
+        nil
+      end
+
+      # Diffs against Rust when `binary` is given, otherwise replays Ruby only.
+      def outcomes(domain_path, sequence, binary, differ)
+        return Differential.diff(differ, domain_path, sequence, binary, modes: DIFFERENTIAL_MODES) if binary
+
+        history = Replay.call(domain_path, sequence, self_consistency: true)
+        { ruby_only:        Differential.property_divergences(history),
+          self_consistency: Differential.self_consistency_divergences(history) }
+      rescue StandardError => e
+        { ruby_only: [{ field: "crash", detail: "#{e.class}: #{e.message}" }] }
+      end
+
+      def finding(seed, mode, divergences, sequence, match)
+        return nil if divergences.empty?
+
+        signature = Shrinker.signature(divergences)
+        return nil if match && !(match["mode"] == mode.to_s && Set.new(match["signature"]).subset?(signature))
+
+        { "seed" => seed, "mode" => mode.to_s, "signature" => signature.to_a.sort, "steps" => sequence,
+          "divergences" => JSON.parse(JSON.generate(divergences)) }
+      end
+
+      # The step-level half of shrinking; the parent already made the domain as small as it could.
+      def shrink(domain_path, found, binary, differ, budget)
+        original = Set.new(found["signature"])
+        mode = found["mode"].to_sym
+        Shrinker.call(found["steps"], budget: budget) do |candidate|
+          divergences = outcomes(domain_path, candidate, binary, differ)[mode] || []
+          Shrinker.reproduces?(original, divergences)
+        end.steps
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/invalid_value_generator.rb

@@ -0,0 +1,64 @@
+module Hecks
+  module Fuzzing
+    # Values deliberately the wrong shape for an attribute; the sibling of ValueGenerator.
+    #
+    # Refusals are answers whose wording is pinned byte-for-byte, so these probe the refusal
+    # sentence rather than the happy path.
+    module InvalidValueGenerator
+      module_function
+
+      # Each kind names a real confusion, not random noise.
+      KINDS = %i[
+        object_for_scalar
+        scalar_for_object
+        float_for_integer
+        numeral_string
+        array_for_scalar
+        boolean_for_string
+        null
+      ].freeze
+
+      def corrupt(attribute, aggregate, random:)
+        kind = kinds_for(attribute, aggregate).sample(random: random)
+        build(kind, attribute, aggregate, random: random)
+      end
+
+      # Only the confusions that mean something for this attribute's declared type.
+      def kinds_for(attribute, aggregate)
+        value_object = aggregate.value_object(attribute.type.to_s)
+        return %i[scalar_for_object array_for_scalar null] if value_object
+        return %i[object_for_scalar float_for_integer numeral_string array_for_scalar null] if attribute.type.to_s == "Integer"
+
+        %i[object_for_scalar array_for_scalar boolean_for_string null]
+      end
+
+      def build(kind, attribute, aggregate, random:)
+        case kind
+        when :object_for_scalar then { "cents" => random.rand(1..1000) }
+        when :scalar_for_object then scalar_for(attribute, aggregate, random: random)
+        when :float_for_integer then random.rand(1.0..100.0).round(2)
+        when :numeral_string    then random.rand(1..1000).to_s
+        when :array_for_scalar  then [random.rand(1..10), random.rand(1..10)]
+        when :boolean_for_string then random.rand(2).zero?
+        end
+      end
+
+      # A bare scalar where a value object is declared.
+      # A single-field value object accepts one, so only a multi-field one makes it a refusal.
+      def scalar_for(attribute, aggregate, random:)
+        value_object = aggregate.value_object(attribute.type.to_s)
+        sole = value_object&.sole_attribute
+        return "a bare scalar" unless sole
+
+        # One field, so a scalar is legal; corrupt the field's own type instead.
+        { sole.name.to_s => ["nested", "array"] }
+      end
+
+      # An argument the command never declares, which exercises `refuse_unknown_arguments`.
+      def undeclared_argument(random:)
+        name = %w[colour flavour rank note].sample(random: random)
+        [name, %w[red loud third scribbled].sample(random: random)]
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/isolated_boot.rb

@@ -0,0 +1,301 @@
+require "fileutils"
+require "tmpdir"
+require "securerandom"
+require_relative "outside_world"
+require_relative "../runtime/adapter_lookup"
+
+module Hecks
+  module Fuzzing
+    # Rewrites a copied domain's persistence bindings before an ephemeral
+    # fuzz/replay boot; a directory copy alone does not isolate Postgres state.
+    module IsolatedBoot
+      module_function
+
+      # Copies `domain_path` to a tmpdir, rebinds its persistence to `adapter`, and
+      # yields the copy's root. `:postgres` is expensive: use smaller seed/step counts.
+      #
+      # The block runs with `OutsideWorld` standing in for every adapter a port or a port-answered
+      # query reaches: a fuzz or replay checks the domain's own rules, and the adapters of the
+      # chapters that drive tools would run shells and write files from a generated sequence.
+      def call(domain_path, adapter: :memory, database: nil, schema: nil, scratch: {})
+        Dir.mktmpdir("hecks-fuzz") do |tmp|
+          copy = File.join(tmp, File.basename(domain_path))
+          copy_dereferencing(domain_path, copy)
+          FileUtils.rm_rf(File.join(copy, "data"))
+          case adapter
+          when :memory       then rebind_to_memory!(copy)
+          when :sqlite       then rebind_to_sqlite!(copy)
+          when :postgres     then rebind_to_postgres!(copy, **scratch)
+          when :postgres_era then rebind_to_postgres_era!(copy, database: database, schema: schema)
+          else raise ArgumentError,
+                     "unknown fuzz adapter #{adapter.inspect} — :memory, :sqlite, :postgres, or :postgres_era"
+          end
+          Runtime::AdapterLookup.standing_in(OutsideWorld) { yield copy }
+        end
+      end
+
+      # 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))
+
+          target = File.join(destination, path.delete_prefix("#{source}/"))
+          if File.directory?(path)
+            FileUtils.mkdir_p(target)
+          else
+            FileUtils.mkdir_p(File.dirname(target))
+            begin
+              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
+          end
+        end
+      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|
+          File.read(path).scan(/uses_embryonaut_bluebook\s*\(?\s*"([\w-]+)"/).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
+
+      # Rewrites every `.hecksagon` in the copy to bind through Memory and replaces its
+      # `.world` files with a `default_adapter "Memory"` one, so the boot needs no settings.
+      def rebind_to_memory!(copy)
+        rewrite_bindings!(copy, "Memory")
+        strip_translations!(copy)
+
+        # Also replaces the settings, not just the bind: a bare fallback setting (like
+        # Postgres's `database:`) would otherwise still apply and WiringError refuses it.
+        write_default_worlds!(copy, "Memory")
+      end
+
+      # Same as `rebind_to_memory!`, one adapter over — Sqlite also needs no `.world`
+      # settings, since `Sqlite#resolve_path` defaults `database` to `data/<table>.db`.
+      def rebind_to_sqlite!(copy)
+        rewrite_bindings!(copy, "SqlitePersistence")
+        strip_translations!(copy)
+        write_default_worlds!(copy, "SqlitePersistence")
+      end
+
+      # Postgres has no zero-config default (Postgres.connect_for refuses without a
+      # `database` setting), so every domain name gets a fresh `.world` written for it.
+      # One shared schema, dropped and recreated per boot, not a fresh name per call —
+      # safe only because callers run one ephemeral boot at a time.
+      FUZZ_POSTGRES_DATABASE = "hecks_fuzz".freeze
+      FUZZ_POSTGRES_SCHEMA   = "hecks_fuzz".freeze
+
+      # 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") do |name|
+          <<~WORLD
+            Hecks.world "#{name}" do
+              default_adapter "Postgres"
+              persisted_by("Postgres") do
+                database "#{database}"
+                schema "#{schema}"
+              end
+            end
+          WORLD
+        end
+        write_unbound_chapter_worlds!(copy)
+      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]
+          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
+          @fuzz_databases_ready[database] = true
+        end
+
+        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}")
+        db.close
+      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 ask run --persistence-parity`) owns that database's
+      # lifecycle.
+      def rebind_to_postgres_era!(copy, database:, schema:)
+        require "pg"
+        if 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
+
+        rewrite_bindings!(copy, "PostgresEra")
+        ensure_postgres_era_schema!(database: database, schema: schema)
+
+        # `schema:` isolates one ephemeral boot from the next, the same job
+        # `FUZZ_POSTGRES_SCHEMA` does for `:postgres` (`connect_for` idempotently
+        # creates it; this method only needs to drop it first, in
+        # `ensure_postgres_era_schema!`).
+        #
+        # `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.
+        write_worlds!(copy, "hecks_fuzz_postgres_era.world") do |name|
+          <<~WORLD
+            Hecks.world "#{name}" do
+              default_adapter "PostgresEra"
+              persisted_by("PostgresEra") do
+                database "#{database}"
+                schema "#{schema}"
+                allow_superuser true
+              end
+            end
+          WORLD
+        end
+        write_unbound_chapter_worlds!(copy)
+      end
+
+      # 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 do |path|
+          File.read(path).scan(/Hecks\.hecksagon\s+"([^"]+)"/).flatten
+        end
+        bluebooks = Dir.glob(File.join(copy, "**", "*.bluebook")).group_by { |path| File.dirname(path) }
+        bluebooks.each do |dir, files|
+          unbound = files.flat_map { |path| File.read(path).scan(/Hecks\.bluebook[\s(]+"([^"]+)"/).flatten }
+                         .uniq - named
+          named.concat(unbound)
+          next if unbound.empty?
+
+          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
+      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)
+        names_by_dir = Hash.new { |hash, dir| hash[dir] = [] }
+        Dir.glob(File.join(copy, "**", "*.hecksagon")).each do |hecksagon_path|
+          names = File.read(hecksagon_path).scan(/Hecks\.hecksagon\s+"([^"]+)"/).flatten
+          names_by_dir[File.dirname(hecksagon_path)].concat(names)
+        end
+        names_by_dir.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
+
+      # 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
+
+        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
+
+        db = PG.connect(dbname: database)
+        db.exec("SET client_min_messages = warning")
+        quoted = db.quote_ident(schema)
+        db.exec("DROP SCHEMA IF EXISTS #{quoted} CASCADE")
+        db.close
+      end
+
+      # 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