hecks 4.0.0 → 6.0.0

data/lib/hecks/framework_bluebooks.rb

@@ -0,0 +1,156 @@
+require_relative "naming"
+require_relative "framework"
+require_relative "runtime/registry"
+require_relative "bluebook/meta_validator"
+require_relative "sentence_form"
+
+module Hecks
+  # The bluebooks the gem carries that a hecksagon can attach by name (ADR 0080): the language
+  # declared in itself, Expression, Tenancy, Deploy, Site, Tickets, Composer, QualityControl and
+  # Bulk.
+  # Framework members stay in `Framework`; `table` and `attach!` find a name across both.
+  #
+  # A bluebook is named by the `Hecks.bluebook "Name"` header of its files, and may span several.
+  # Beside its bluebook a bluebook may carry what every hecksagon attaching it needs, whatever
+  # its store: `<snake_name>.ports.hecksagon` (the ports it declares, as a `Hecks.hecksagon`
+  # block that merges into the attaching one) and `adapters/*.adapter` (the adapters binding them).
+  module FrameworkBluebooks
+    # Where attachable bluebooks live, relative to `lib/hecks/`.
+    GLOBS = %w[language/**/*.bluebook grammar/expression.bluebook tenancy/bluebook/*.bluebook
+               deploy/bluebook/*.bluebook site/bluebook/*.bluebook rails_app/bluebook/*.bluebook tickets/bluebook/*.bluebook
+               composer/bluebook/*.bluebook quality_control/*.bluebook bulk/bluebook/*.bluebook].freeze
+
+    # A `Hecks.bluebook "Name"` header line, capturing the bluebook's name.
+    BLUEBOOK_HEADER = /\A\s*Hecks\.bluebook\s+"([^"]+)"/
+
+    # Every attachable bluebook, by name, with the files that declare it.
+    #
+    # @return [Hash{String => Array<String>}] bluebook name to its files' absolute paths, sorted
+    def self.index
+      @index ||= bluebook_files.group_by { |path| declaration_name(path) }
+                               .reject { |name, _| name.nil? }
+                               .freeze
+    end
+
+    # @return [Array<String>] every file the globs find, sorted
+    def self.bluebook_files
+      GLOBS.flat_map { |glob| Dir.glob(File.join(__dir__, glob)) }.sort
+    end
+
+    # Every bluebook the gem carries, whichever module loads it: the one lookup table `attaches`
+    # finds a name in.
+    #
+    # @return [Hash{String => Array<String>}] bluebook name to its files' absolute paths, the
+    #   framework members (`Framework.members`) and the attachable bluebooks (`index`) together
+    def self.table
+      Framework.members.transform_values { |path| [path] }.merge(index)
+    end
+
+    # Loads one gem bluebook by name, found in `table`: a framework member through
+    # `Framework.load!`, any other bluebook through `load!`.
+    #
+    # @param name [String, Symbol] the bluebook's name, such as `"Governance"` or `"Deploy"`
+    # @return [Boolean, nil] true when this call loaded it, nil when it was already held
+    # @raise [Runtime::WiringError] if the gem carries no bluebook of that name; the message
+    #   lists the known names and says how to attach a vendored package
+    def self.attach!(name)
+      key = name.to_s
+      return Framework.load!(key) if Framework.members.key?(key)
+      return load!(key) if index.key?(key)
+
+      raise Runtime::WiringError,
+            "attaches #{name.inspect}: the gem carries no bluebook of that name — known: " \
+            "#{table.keys.sort.join(", ")}. To attach a vendored package, write " \
+            "`attaches #{name.to_s.inspect}, from: :vendor`"
+    end
+
+    # Loads a bluebook's files into the current registry, unless it already holds the bluebook.
+    #
+    # The files load together inside `MetaValidator.defer`, so a bluebook spread over several files
+    # is judged once, whole. The bluebook's ports file and adapters load after it, since a port
+    # names the bluebook's aggregates.
+    #
+    # @param name [String] the bluebook's name, such as `"Deploy"`
+    # @return [Boolean, nil] true when this call loaded the bluebook, nil when it was already held
+    # @raise [Runtime::WiringError] if no attachable bluebook has that name
+    def self.load!(name)
+      paths = bluebook_paths(name)
+      registry = open_registry(name)
+      return refuse_own_bluebook(registry, name.to_s) if registry.bluebook(name.to_s)
+
+      load_atomically(registry, name.to_s, paths)
+      true
+    end
+
+    # @return [Array<String>] the files of the named bluebook
+    # @raise [Runtime::WiringError] if no attachable bluebook has that name
+    def self.bluebook_paths(name)
+      index.fetch(name.to_s) do
+        raise Runtime::WiringError,
+              "no attachable bluebook named #{name.inspect} — known: #{index.keys.join(", ")}"
+      end
+    end
+
+    # @return [Runtime::Registry] the registry the current boot is loading into
+    # @raise [Runtime::WiringError] when no boot is open
+    def self.open_registry(name)
+      Hecks.current_registry or
+        raise Runtime::WiringError, "attaches #{name.to_s.inspect} outside a boot: no registry is open"
+    end
+
+    # Loads a bluebook whole or not at all: a raise anywhere leaves the registry as it was, so a
+    # retry loads the bluebook again instead of finding a half-built one already held.
+    def self.load_atomically(registry, name, paths)
+      before = { queued: Bluebook::MetaValidator.deferred_bluebooks.dup, ports: registry.ports.keys,
+                 adapters: registry.adapters.keys }
+      Bluebook::MetaValidator.defer { paths.each { |path| SentenceForm.load_file(path) } }
+      Bluebook::MetaValidator.judge_deferred!(registry)
+      load_wiring(name, paths)
+    rescue Exception # rubocop:disable Lint/RescueException -- rolls back, then re-raises
+      roll_back(registry, name, before)
+      raise
+    end
+
+    # Puts the registry back as `load_atomically` found it.
+    def self.roll_back(registry, name, before)
+      registry.forget_bluebook(name)
+      Bluebook::MetaValidator.deferred_bluebooks.replace(before[:queued])
+      registry.ports.delete_if { |key, _| !before[:ports].include?(key) }
+      registry.adapters.delete_if { |key, _| !before[:adapters].include?(key) }
+    end
+    private_class_method :bluebook_files, :bluebook_paths, :open_registry, :load_atomically, :roll_back
+
+    # Returns nil for a bluebook this gem already loaded; raises for a bluebook of the same name
+    # that a user's own file declared, which `attaches` would otherwise silently take for the
+    # gem's.
+    def self.refuse_own_bluebook(registry, name)
+      foreign = Array(registry.bluebook_sources[name]).compact
+                                                      .reject { |path| File.expand_path(path).start_with?("#{__dir__}/") }
+      return if foreign.empty?
+
+      raise Runtime::WiringError,
+            "attaches #{name.inspect}, but a bluebook named #{name.inspect} is already declared in " \
+            "#{foreign.join(", ")} — rename it, since the gem's own #{name} bluebook cannot merge into it"
+    end
+    private_class_method :refuse_own_bluebook
+
+    # Loads what a bluebook ships beside its bluebook: its ports file, then its adapters.
+    #
+    # @param name [String] the bluebook's name
+    # @param paths [Array<String>] the bluebook's bluebook files
+    # @return [void]
+    def self.load_wiring(name, paths)
+      directory = File.dirname(paths.first)
+      ports     = File.join(directory, "#{Naming.snake(name)}.ports.hecksagon")
+      Kernel.load(ports) if File.file?(ports)
+      Dir.glob(File.join(directory, "adapters", "*.adapter")).each { |adapter| Kernel.load(adapter) }
+    end
+    private_class_method :load_wiring
+
+    # The name a file's `Hecks.bluebook "Name"` header declares, or nil for a file without one.
+    def self.declaration_name(path)
+      File.foreach(path) { |line| return Regexp.last_match(1) if line =~ BLUEBOOK_HEADER }
+      nil
+    end
+  end
+end

data/lib/hecks/freezer.rb

@@ -41,10 +41,16 @@ module Hecks
     def first_unfrozen_child(held, path)
       case held
       when Hash  then held.lazy.filter_map { |key, inner| unfrozen_within(inner, path + [key.to_s]) }.first
-      when Array then held.each_with_index.lazy.filter_map { |inner, i| unfrozen_within(inner, path + [i.to_s]) }.first
+      when Array then first_unfrozen_element(held, path)
       end
     end
 
+    # @return [String, nil] the path to the first mutable value inside an Array, or nil
+    def first_unfrozen_element(held, path)
+      indexed = held.each_with_index.lazy
+      indexed.filter_map { |inner, i| unfrozen_within(inner, path + [i.to_s]) }.first
+    end
+
     # @param path [Array<String>] the owner path walked so far
     # @return [String] the path as dotted text, or `"(the value itself)"` for the root
     def mutable_path(path) = path.empty? ? "(the value itself)" : path.join(".")

data/lib/hecks/fuzzing/combination_miner.rb

@@ -1,6 +1,7 @@
 require "json"
 require "open3"
 require_relative "form_census"
+require_relative "../text"
 
 module Hecks
   module Fuzzing
@@ -10,13 +11,14 @@ module Hecks
     module CombinationMiner
       PROMPT_TEMPLATE = "qa/combination_miner/prompt.md".freeze
       HYPOTHESIS_FILE = "HYPOTHESIS.md".freeze
+      # A `{{name}}` placeholder in the prompt template, capturing the name.
+      PLACEHOLDER = /\{\{(\w+)\}\}/
 
       module_function
 
       def corpus_paths(root)
-        Hecks::Corpus.members(:stress, :example, root: root).map(&:path)
-                     .select { |path| Hecks::Corpus.bluebook_files(path) }
-                     .sort
+        member_paths = Hecks::Corpus.members(:stress, :example, root: root).map(&:path)
+        member_paths.select { |path| Hecks::Corpus.bluebook_files(path) }.sort
       end
 
       def recent_bug_titles(root, limit: 60)
@@ -43,7 +45,7 @@ module Hecks
         [covered, skipped]
       end
 
-      def skip_note(path, error) = "#{path} (#{error.class}: #{error.message.lines.first&.strip})"
+      def skip_note(path, error) = "#{path} (#{error.class}: #{Hecks::Text.first_line(error.message)})"
 
       def single_carrier_pairs(covered)
         covered.select { |_, names| names.uniq.size == 1 }.map { |pair, names| "#{pair} (only #{names.first})" }.sort
@@ -51,7 +53,7 @@ module Hecks
 
       def prompt(root, brief, count:, out_dir:)
         substitutions = prompt_substitutions(brief, count, out_dir)
-        File.read(File.join(root, PROMPT_TEMPLATE)).gsub(/\{\{(\w+)\}\}/) { substitutions.fetch(Regexp.last_match(1)) }
+        File.read(File.join(root, PROMPT_TEMPLATE)).gsub(PLACEHOLDER) { substitutions.fetch(Regexp.last_match(1)) }
       end
 
       def prompt_substitutions(brief, count, out_dir)
@@ -86,7 +88,8 @@ module Hecks
 
       # Informational, never a gate: an agent may aim at a shape the census does not name yet.
       def new_pairs(candidate_dir, covered)
-        FormCensus.covered_pairs(FormCensus.census(candidate_dir)).keys.reject { |pair| covered.key?(pair) }.sort
+        candidate_pairs = FormCensus.covered_pairs(FormCensus.census(candidate_dir)).keys
+        candidate_pairs.reject { |pair| covered.key?(pair) }.sort
       end
 
       def relative(path, root) = path.delete_prefix("#{root}/")

data/lib/hecks/fuzzing/concurrent_dispatch/world_copy.rb

@@ -8,6 +8,8 @@ module Hecks
       # Copies a target domain, rebinds it to a shared `PostgresEra` schema and boots it there.
       module WorldCopy
         FUZZ_WORLD_FILE = "hecks_fuzz_postgres_era.world".freeze
+        # A `Hecks.hecksagon "Name"` declaration, capturing the name.
+        HECKSAGON_DECLARATION = /Hecks\.hecksagon\s+"([^"]+)"/
 
         # Same copy-and-rebind IsolatedBoot.call(..., adapter: :postgres_era) does,
         # minus the schema wipe — this schema already holds what setup wrote, and
@@ -43,7 +45,7 @@ module Hecks
         def hecksagon_names_by_dir(copy)
           worlds_by_dir = Hash.new { |h, k| h[k] = [] }
           Dir.glob(File.join(copy, "**", "*.hecksagon")).each do |hecksagon_path|
-            names = File.read(hecksagon_path).scan(/Hecks\.hecksagon\s+"([^"]+)"/).flatten
+            names = File.read(hecksagon_path).scan(HECKSAGON_DECLARATION).flatten
             worlds_by_dir[File.dirname(hecksagon_path)].concat(names)
           end
           worlds_by_dir

data/lib/hecks/fuzzing/concurrent_dispatch.rb

@@ -91,10 +91,10 @@ module Hecks
         domain, aggregate_name, = Naming.split_verb(verb)
         return false unless domain && aggregate_name
 
-        aggregate = runtime.registry.bluebook(domain)&.aggregate(aggregate_name)
+        aggregate = runtime.bluebook(domain)&.aggregate(aggregate_name)
         return false unless aggregate
 
-        repository = runtime.registry.repository(domain, aggregate)
+        repository = runtime.repository(domain, aggregate)
         repository.capabilities.include?(:cross_process_lock)
       rescue StandardError => e
         # Still `false` — a verb this boot cannot resolve is not raced on a

data/lib/hecks/fuzzing/domain_generator.rb

@@ -24,6 +24,11 @@ module Hecks
       REFERENCE_FORMS = %w[reference_attr revalued_reference].freeze
       CHAIN_FORMS     = %w[two_hop_given multi_hop_where].freeze
 
+      # A `Hecks.bluebook "Name"` opening, with or without parentheses, up to the closing quote.
+      BLUEBOOK_OPENING = /Hecks\.bluebook\s*\(?\s*(["'])[^"']+\1/
+      # A lowercase letter followed by an uppercase one: a camelCase word boundary.
+      CAMEL_BOUNDARY = /([a-z])([A-Z])/
+
       extend Rendering
       extend Pruning
 
@@ -40,7 +45,7 @@ module Hecks
       end
 
       # `blueprint.json` is written beside the domain directory, never
-      # inside it — a stray file under `bluebook/` would load as a chapter.
+      # inside it — a stray file under `bluebook/` would load as a bluebook.
       def write(blueprint, root)
         domain = File.join(root, DIRECTORY)
         FileUtils.rm_rf(domain)
@@ -53,10 +58,10 @@ module Hecks
 
       # Renamed to `QaGenerated` — the fixed name child processes expect.
       def adopt(source)
-        source.sub(/Hecks\.bluebook\s*\(?\s*(["'])[^"']+\1/) { "Hecks.bluebook #{DOMAIN_NAME.inspect}" }
+        source.sub(BLUEBOOK_OPENING) { "Hecks.bluebook #{DOMAIN_NAME.inspect}" }
       end
 
-      def snake(name) = name.gsub(/([a-z])([A-Z])/, '\1_\2').downcase
+      def snake(name) = name.gsub(CAMEL_BOUNDARY, '\1_\2').downcase
 
       # What this generator can build, not everything FormCensus knows about.
       # A form with no `Builder::FORM_STEPS` recipe is simply never

data/lib/hecks/fuzzing/era_boundary.rb

@@ -13,7 +13,7 @@ module Hecks
       # 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
+        bluebook = registry.first_bluebook
         return failed("no bluebook in #{directory}") unless bluebook
 
         reason = unaudited_reason(registry, bluebook)

data/lib/hecks/fuzzing/failure_triage.rb

@@ -14,6 +14,17 @@ module Hecks
       # Directory, under the checkout, where minimized repros are kept.
       REGRESSION_DIR = "spec/corpus/regressions".freeze
 
+      # A UUID anywhere in a message.
+      UUID = /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/i
+      # A `0x` hex literal or a run of sixteen or more hex digits.
+      HEX = /\b0x[0-9a-f]+\b|\b[0-9a-f]{16,}\b/i
+      # A single- or double-quoted literal.
+      QUOTED = /(["']).*?\1/
+      # An integer or decimal number, optionally negative.
+      NUMBER = /-?\d+(?:\.\d+)?/
+      # Each minted part of a message, in the order it is replaced, with its placeholder.
+      MINTED_PARTS = [[UUID, "<uuid>"], [HEX, "<hex>"], [QUOTED, "<str>"], [NUMBER, "<n>"]].freeze
+
       module_function
 
       # @param property [String] the property name or exception class the finding opens with
@@ -31,12 +42,8 @@ module Hecks
       # @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
+        normalized = MINTED_PARTS.reduce(message.to_s) { |text, (part, placeholder)| text.gsub(part, placeholder) }
+        normalized.squeeze(" ").strip
       end
 
       # Collapses findings to one per identity, keeping the smallest sequence of each.

data/lib/hecks/fuzzing/form_census/{chapter_forms.rb → bluebook_forms.rb}

@@ -1,33 +1,33 @@
 module Hecks
   module Fuzzing
     module FormCensus
-      # The chapter-level constructs an aggregate takes part in, folded onto its own hash so the
+      # The bluebook-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
+      # Policies and read models live on the bluebook, 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 BluebookForms
         module_function
 
-        # @param aggregate [Hash] one aggregate of an exported chapter
-        # @param chapter_ir [Hash] the exported chapter it belongs to
+        # @param aggregate [Hash] one aggregate of an exported bluebook
+        # @param bluebook_ir [Hash] the exported bluebook 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))
+        def onto(aggregate, bluebook_ir)
+          aggregate.merge("across_policies"        => across_policies(aggregate, bluebook_ir),
+                          "multi_head_read_models" => multi_head_read_models(aggregate, bluebook_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|
+        def across_policies(aggregate, bluebook_ir)
+          (bluebook_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|
+        def multi_head_read_models(aggregate, bluebook_ir)
+          (bluebook_ir["read_models"] || []).select do |read_model|
             heads = read_model["aggregate_heads"] || []
             heads.size >= 2 && heads.any? { |head| head["aggregate"] == aggregate["name"] }
           end

data/lib/hecks/fuzzing/form_census.rb

@@ -1,6 +1,6 @@
 require "json"
 require_relative "../corpus"
-require_relative "form_census/chapter_forms"
+require_relative "form_census/bluebook_forms"
 require_relative "form_census/reference_forms"
 
 module Hecks
@@ -9,7 +9,7 @@ module Hecks
     #
     # Shared by the combination-coverage spec and `hecks quality_control target.judge_novelty` so
     # they cannot drift. The unit is one aggregate: forms on one head meet at dispatch, forms in one
-    # chapter do not.
+    # bluebook do not.
     module FormCensus
       # Ports and adapters a census boots with, relative to the repository root.
       CENSUS_SUPPORT = [
@@ -37,7 +37,7 @@ module Hecks
         "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`).
+        # Bluebook-level constructs, attributed to the aggregate they name (see `BluebookForms`).
         "cross_domain_policy"   => ->(a) { (a["across_policies"] || []).any? },
         "multi_head_read_model" => ->(a) { (a["multi_head_read_models"] || []).any? }
       }.freeze
@@ -75,15 +75,17 @@ module Hecks
 
       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|
+          present_forms(shows).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(ChapterForms.onto(aggregate, chapter_ir))]
+      def present_forms(shows) = shows.select { |_, present| present }.keys
+
+      def aggregates_in(bluebook_ir)
+        (bluebook_ir["aggregates"] || []).map do |aggregate|
+          ["#{bluebook_ir["name"]}::#{aggregate["name"]}", properties(BluebookForms.onto(aggregate, bluebook_ir))]
         end
       end
 
@@ -92,7 +94,7 @@ module Hecks
       end
 
       # The census over a domain on disk, booted lightweight (no `Hecks.boot`, no database).
-      # Only the first-loaded chapter is measured.
+      # Only the first-loaded bluebook is measured.
       #
       # @raise [ArgumentError] if `domain_path` has no bluebook files
       def census(domain_path)
@@ -105,7 +107,7 @@ module Hecks
           files.each { |file| Kernel.load(file) }
         end
 
-        aggregates_in(exported_chapter(registry))
+        aggregates_in(exported_bluebook(registry))
       end
 
       def support_files
@@ -113,9 +115,9 @@ module Hecks
         CENSUS_SUPPORT.map { |relative| File.join(root, relative) }
       end
 
-      def exported_chapter(registry)
-        chapter_name = registry.bluebooks.keys.first
-        JSON.parse(JSON.generate(Hecks::Projector::Exporter.call(registry).fetch(chapter_name)))
+      def exported_bluebook(registry)
+        declaration_name = registry.bluebooks.keys.first
+        JSON.parse(JSON.generate(Hecks::Projector::Exporter.call(registry).fetch(declaration_name)))
       end
     end
   end

data/lib/hecks/fuzzing/generated_domain_check.rb

@@ -4,6 +4,7 @@ require_relative "sequence_generator"
 require_relative "replay"
 require_relative "shrinker"
 require_relative "differential"
+require_relative "../text"
 
 module Hecks
   module Fuzzing
@@ -54,7 +55,7 @@ module Hecks
         IsolatedBoot.call(domain_path) { |copy| Hecks.boot(copy, environment: nil) }
         nil
       rescue StandardError, ScriptError => e
-        "#{e.class}: #{e.message.lines.first&.strip}"
+        "#{e.class}: #{Hecks::Text.first_line(e.message)}"
       end
 
       def check_seed(domain_path, seed, settings)

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

@@ -16,7 +16,7 @@ module Hecks
           # 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)
+          write_unbound_bluebook_worlds!(copy)
         end
 
         def postgres_world(name, database, schema)
@@ -33,7 +33,7 @@ module Hecks
 
         # 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)
+        def ensure_fuzz_schema!(database = FUZZ_POSTGRES_DATABASE, schema = scratch_schema(database))
           # 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.
@@ -61,7 +61,7 @@ module Hecks
           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)
+          write_unbound_bluebook_worlds!(copy)
         end
 
         def require_owned_scratch!(database, schema)
@@ -73,10 +73,10 @@ module Hecks
                 "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`.
+        # The world text for one bluebook on `PostgresEra`.
         #
         # `schema:` isolates one ephemeral boot from the next, the same job
-        # `FUZZ_POSTGRES_SCHEMA` does for `:postgres` (`connect_for` idempotently
+        # `ScratchSchema#scratch_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

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

@@ -1,19 +1,29 @@
 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.
+      # Which Postgres scratch schema a fuzz boot uses: one per process, so processes can fuzz one
+      # database at once without dropping a schema another process is booting into.
       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.
+        # The schema this process boots into: `FUZZ_POSTGRES_SCHEMA` suffixed with this process's
+        # pid, so a sweep's forked pool children each get their own. It is dropped when the
+        # process that first asked for it exits.
+        #
+        # @param database [String] the scratch database the schema lives in
+        # @return [String] the schema name
         def scratch_schema(database)
-          named = ENV.fetch(FUZZ_SCHEMA_ENV, nil)
-          return FUZZ_POSTGRES_SCHEMA unless named
+          schema = "#{FUZZ_POSTGRES_SCHEMA}_#{Process.pid}"
+          drop_at_exit(database, schema)
+          schema
+        end
 
+        # Registers one drop of `schema` for when this process exits. A forked child inherits the
+        # hook, so the hook drops only in the process that registered it.
+        def drop_at_exit(database, schema)
+          owner = Process.pid
           @fuzz_schema_cleanups ||= {}
-          @fuzz_schema_cleanups[named] ||= at_exit { drop_schema_quietly(database, named) }
-          named
+          @fuzz_schema_cleanups[schema] ||= at_exit do
+            drop_schema_quietly(database, schema) if Process.pid == owner
+          end
         end
 
         def drop_schema_quietly(database, schema)

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

@@ -9,6 +9,13 @@ module Hecks
         # The name of a `Hecks.bluebook` block.
         BLUEBOOK_NAME = /Hecks\.bluebook[\s(]+"([^"]+)"/
 
+        # A `projected_by "Adapter"` bind, with or without parentheses.
+        PROJECTED_BY_BIND = /\bprojected_by\s*\(?\s*"/
+
+        # A `persisted_by` bind naming its adapter as a literal or a local, on one line only:
+        # a newline ends the statement, and the next one must stay.
+        PERSISTED_BY_BIND = /persisted_by[ \t]*\(?[ \t]*(?:"[^"]+"|[a-z_]\w*)[ \t]*\)?/
+
         # 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)
@@ -21,10 +28,10 @@ module Hecks
           end
         end
 
-        # Gives every chapter with no hecksagon block (so no bind) a world of its own that
+        # Gives every bluebook 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)
+        # a bluebook with no bind can't provide.
+        def write_unbound_bluebook_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|
@@ -39,7 +46,7 @@ module Hecks
           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.
+        # Writes `dir`'s one world file falling every `unbound` bluebook 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"))
@@ -87,10 +94,8 @@ module Hecks
         # 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}\")"))
+            lines = File.readlines(path).grep_v(PROJECTED_BY_BIND)
+            File.write(path, lines.join.gsub(PERSISTED_BY_BIND, "persisted_by(\"#{adapter_name}\")"))
           end
         end
       end

data/lib/hecks/fuzzing/isolated_boot.rb

@@ -15,12 +15,11 @@ module Hecks
     module IsolatedBoot
       # 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 schema per process, dropped and recreated per boot, not a fresh name per call —
-      # a process runs one ephemeral boot at a time. The default is shared by every process that
-      # does not name its own schema in `FUZZ_SCHEMA_ENV`, as a sweep's pool children do.
+      # One schema per process (see `ScratchSchema#scratch_schema`), dropped and recreated per
+      # boot, not a fresh name per call: a process runs one ephemeral boot at a time, and
+      # processes running side by side (parallel spec workers, a sweep's pool) never share one.
       FUZZ_POSTGRES_DATABASE = "hecks_fuzz".freeze
       FUZZ_POSTGRES_SCHEMA   = "hecks_fuzz".freeze
-      FUZZ_SCHEMA_ENV        = "HECKS_FUZZ_SCHEMA".freeze
 
       extend Copying
       extend Worlds
@@ -34,7 +33,7 @@ module Hecks
       #
       # 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.
+      # bluebooks 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))