hecks 3.6.0 → 3.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e303214451e949201a80bb0aa29d33e0e8a240e78eda156a4ff6d4913913f20
-  data.tar.gz: de457dd9cd8212c61114a4f6c939479807de32716f0a40cd24c13c51ccaf5a7b
+  metadata.gz: 1f5088f868a4fb798d8295bdf93ad836ac63abeeac372d19ea486ed445587944
+  data.tar.gz: 526e4623eeb9947b2ccf74cf8599ee8f0820b677335c36f33905f20695fdb0bc
 SHA512:
-  metadata.gz: a35c1b98ca37e475d237288e1c7670ed7ecc32ad8b91a2c3fc6c3a010973673a5441755e3fda5bc2f2b84b2dfeaee2d873276ea14043ea787e959aebc5706130
-  data.tar.gz: 54222db25bfab9416ef092b467a243fac8df095997274f69be0f3105b1edf6cd39fb2b86b87360bf5a270ddbb62e53bc2c3b6db2dd840f93743e49c12085ef67
+  metadata.gz: e6a604f67014c7c7136749ad1d2d661652083a5ab03274faa5531a221f0e6a27e81b4be0e0a464ec5d7253eac7ebc33aae342308fd58a724cc65d90f77d5a68c
+  data.tar.gz: c087ba04b615b664d1895fc040c75c4a906b330d080e24e360f9086b2893250f71cf7970d77253064e4ec91d1be12962497fce4097bcb8df66f45cbc1e31effe

data/lib/hecks/bluebook/meta_validator/modes.rb

@@ -118,6 +118,20 @@ module Hecks
           @shadow_parsing = previous
         end
 
+        # Wraps `block` with `shadow_parsing?` false, restoring it afterward. The language's own
+        # grammar is built once per process and memoized, so it cannot take the mode of whichever
+        # caller happens to ask for it first.
+        #
+        # @yield the one-time grammar build, with `shadow_parsing?` false throughout
+        # @return [Object] the block's own return value
+        def while_not_shadow_parsing
+          previous        = @shadow_parsing
+          @shadow_parsing = false
+          yield
+        ensure
+          @shadow_parsing = previous
+        end
+
         # Wraps `block` with `disabled?` forced false, restoring it afterward.
         # Only `grammar_registry`'s one-time fixpoint build uses this.
         #

data/lib/hecks/bluebook/meta_validator/syntax_boot/disk_cache.rb

@@ -4,6 +4,10 @@ module Hecks
       module SyntaxBoot
         # The grammar table's memo keys and its cross-process copy on disk.
         module DiskCache
+          # How long an entry nobody has read stays before the next write sweeps it away. A read
+          # marks an entry as used, so only the tables of other code age out.
+          UNREAD_KEEP_SECONDS = 24 * 60 * 60
+
           # `equal?`, not `==` — chapter identity, not value equality, is the
           # fact this cache key tracks.
           def same_chapters?(cached, current)
@@ -23,18 +27,29 @@ module Hecks
           def disk_cache_enabled? = ENV["HECKS_SYNTAX_BOOT_CACHE"] != "off"
 
           # Fails toward a real boot, never toward a wrong table: a missing
-          # file, a corrupt blob, or a permission error just misses the cache.
+          # file, a corrupt blob, or a permission error just misses the cache. A table
+          # the user has not cached is looked for among the ones the gem ships.
           def read_disk_cache(chapters)
             return nil unless disk_cache_enabled?
 
             path = disk_cache_path(chapters)
-            return nil unless File.exist?(path)
+            return load_table(path, touch: true) if File.exist?(path)
 
-            Marshal.load(File.binread(path)) # rubocop:disable Security/MarshalLoad -- own process-local cache, never external input
+            shipped = Hecks::CacheDir.prebuilt(File.basename(path))
+            File.exist?(shipped) ? load_table(shipped) : nil
           rescue StandardError
             nil
           end
 
+          # @param path [String] a table file
+          # @param touch [Boolean] whether to mark it as used (a shipped file is read-only)
+          # @return [Hash, nil] the table
+          def load_table(path, touch: false)
+            table = Marshal.load(File.binread(path)) # rubocop:disable Security/MarshalLoad -- own cache or the gem's own file, never external input
+            FileUtils.touch(path) if touch
+            table
+          end
+
           # Writes to a PID-suffixed temp file and renames it into place, so a
           # concurrent writer's rename can only overwrite with identical
           # content, never leave a torn file for a concurrent reader.
@@ -46,10 +61,20 @@ module Hecks
             tmp_path = "#{path}.#{Process.pid}.tmp"
             File.binwrite(tmp_path, Marshal.dump(result))
             File.rename(tmp_path, path)
+            prune_disk_cache
           rescue StandardError
             nil
           end
 
+          # Removes the tables no process has read for `UNREAD_KEEP_SECONDS`.
+          def prune_disk_cache
+            Dir.glob(File.join(cache_dir, "*.marshal")).each do |file|
+              File.delete(file) if Time.now - File.mtime(file) > UNREAD_KEEP_SECONDS
+            rescue SystemCallError
+              next
+            end
+          end
+
           def disk_cache_path(chapters)
             File.join(cache_dir, "#{disk_cache_key(chapters)}.marshal")
           end

data/lib/hecks/bluebook/meta_validator/verdict_cache/prebuilt.rb

@@ -0,0 +1,44 @@
+module Hecks
+  module Bluebook
+    module MetaValidator
+      module VerdictCache
+        # The verdict file the process reads (its own, else the one a packaged gem ships) and the
+        # Ruby series that file is valid for.
+        module Prebuilt
+          # The Ruby the judging code ran on, to the minor version: a patch release changes neither
+          # a verdict nor the encoding of one, so a cache built on one patch serves the others.
+          #
+          # @return [String] such as `ruby-3.3`
+          def ruby_series = "#{RUBY_ENGINE}-#{RUBY_VERSION[/\A\d+\.\d+/]}"
+
+          # The file the gem ships for the current code's verdicts, when it ships one.
+          #
+          # @return [String] an absolute path
+          def prebuilt_path = Hecks::CacheDir.prebuilt(File.basename(path))
+
+          # Reads and decodes the current code's file: the user's own, else the gem's prebuilt one.
+          #
+          # @return [Hash{String => Hash}] entries, or `{}` on any problem
+          def read
+            own = path
+            return read_file(own) if File.file?(own) && trusted?(own)
+
+            File.file?(prebuilt_path) ? read_file(prebuilt_path) : {}
+          end
+
+          # @param file [String] a verdict file already trusted
+          # @return [Hash{String => Hash}] its entries, or `{}` on any problem
+          def read_file(file)
+            doc = JSON.parse(File.binread(file), max_nesting: false)
+            return {} unless doc.is_a?(Hash) && doc["format"] == FORMAT
+
+            decoded = decode(doc["entries"])
+            well_formed?(decoded) ? decoded : {}
+          rescue StandardError
+            {}
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/meta_validator/verdict_cache.rb

@@ -4,6 +4,7 @@ require "json"
 require_relative "../../cache_dir"
 require_relative "../../version"
 require_relative "verdict_cache/tagging"
+require_relative "verdict_cache/prebuilt"
 
 module Hecks
   module Bluebook
@@ -22,6 +23,7 @@ module Hecks
       #   VerdictCache.flush  # also runs at process exit
       module VerdictCache
         extend Tagging
+        extend Prebuilt
 
         module_function
 
@@ -70,7 +72,7 @@ module Hecks
         #   file's relative path and bytes, in sorted order
         def digest_of(lib)
           state = Digest::SHA256.new
-          state << "#{FORMAT}\0#{RUBY_VERSION}\0#{Hecks::VERSION}\0"
+          state << "#{FORMAT}\0#{ruby_series}\0#{Hecks::VERSION}\0"
           judging_files(lib).each do |file|
             state << file.delete_prefix(lib) << "\0" << File.binread(file) << "\0"
           end
@@ -146,22 +148,6 @@ module Hecks
         # @return [Hash{String => Hash}] every verdict this process knows
         def entries = @entries ||= {}
 
-        # Reads and decodes the current code's file.
-        #
-        # @return [Hash{String => Hash}] entries, or `{}` on any problem
-        def read
-          file = path
-          return {} unless File.file?(file) && trusted?(file)
-
-          doc = JSON.parse(File.binread(file), max_nesting: false)
-          return {} unless doc.is_a?(Hash) && doc["format"] == FORMAT
-
-          decoded = decode(doc["entries"])
-          well_formed?(decoded) ? decoded : {}
-        rescue StandardError
-          {}
-        end
-
         # Whether `file` and its directory belong to this user and nobody else
         # can write them.
         #

data/lib/hecks/bluebook/meta_validator.rb

@@ -168,12 +168,14 @@ module Hecks
       end
 
       # The booted, self-judged language registry every ordinary bluebook is
-      # judged against — built once per process and memoized.
+      # judged against — built once per process and memoized, with shadow parsing off: a caller
+      # inside `while_shadow_parsing` that is first to ask would otherwise memoize a grammar
+      # parsed in that mode, or fail to load it.
       #
       # @return [Runtime::Registry] the booted, fixpoint-judged language
       #   registry
       def self.grammar_registry
-        @grammar_registry ||= begin
+        @grammar_registry ||= while_not_shadow_parsing do
           registry = load_grammar_into(Runtime::Registry.new)
           # Assigned before the fixpoint judge below, since judging re-enters
           # grammar_registry (via fresh_runtime/Plan.for) and a bare `||=`

data/lib/hecks/cache_dir.rb

@@ -20,6 +20,16 @@ module Hecks
       File.join(root, name)
     end
 
+    # The directory the gem ships prebuilt cache files in, beside `lib/` so the digest of `lib/`
+    # that names a cache file never covers the files built from it. It exists only in a packaged
+    # gem, and it is part of the gem's own code, so it needs no ownership check.
+    #
+    # @param name [String] the file name inside it
+    # @return [String] the absolute path of `name` under the gem's `prebuilt/`
+    def prebuilt(name)
+      File.join(File.expand_path("../..", __dir__), "prebuilt", name)
+    end
+
     # The cache root, resolved once per process.
     #
     # @return [String] the absolute path of the directory every `path` lives under

data/lib/hecks/corpus/routes.rb

@@ -27,7 +27,7 @@ module Hecks
       # hecks fuzz sweeps it too, once Fuzzing::Replay coerces value-object args
       # before recomputing givens — today it doesn't, so this given reads as
       # wrongly admitted.
-      Route.new(%r{\Aspec/fixtures/rust_host/}, :named_in, "rust/host/src/web.rs", "checkout_fixture",
+      Route.new(%r{\Aspec/fixtures/rust_host/}, :named_in, "rust/host/src/web/commerce.rs", "checkout_fixture",
                 "the Rust host's checkout fixture, pinned by its web and /api tests")
     ].freeze
   end

data/lib/hecks/deploy/bluebook/deploy.bluebook

@@ -274,6 +274,115 @@ Hecks.bluebook "Deploy" do
     end
   end
 
+  aggregate "VercelTarget" do
+    description "One domain's validated Vercel deploy target — what deployed_to(\"Vercel\") must resolve to before hecks deploy project generates a Vercel function's configuration from it"
+
+    identified_by :domain
+
+    attribute :domain,       DomainName
+    attribute :region,       Region
+    attribute :memory,       Memory
+    attribute :max_duration, MaxDuration
+
+    value_object "DomainName" do
+      attribute :value, String
+      invariant("a domain is named") { !value.to_s.empty? }
+    end
+
+    # A Vercel region id such as iad1 or fra1: three letters and a digit. Vercel refuses an
+    # unknown id at deploy; this checks the shape only.
+    value_object "Region" do
+      attribute :value, String
+      invariant("a region is a Vercel id such as iad1") { value.to_s.match?(/\A[a-z]{3}[0-9]\z/) }
+    end
+
+    # Function memory in MB. Vercel sells 128 MB up to a plan's ceiling; the ceiling is the
+    # plan's to enforce.
+    value_object "Memory" do
+      attribute :value, Integer
+      invariant("memory is at least 128 MB") { value >= 128 }
+      invariant("memory is at most 10240 MB") { value <= 10240 }
+    end
+
+    # Seconds a single invocation may run. 800 is the longest any plan allows.
+    value_object "MaxDuration" do
+      attribute :value, Integer
+      invariant("a duration is at least 1 second") { value >= 1 }
+      invariant("a duration is at most 800 seconds") { value <= 800 }
+    end
+
+    # All four required for the same reason as `BoxTarget.Declare`; this validates a target
+    # already resolved by `hecks deploy project`'s defaults.
+    command "Declare" do
+      goal "Validate one domain's Vercel deploy target before anything is generated from it"
+
+      attribute :domain,       DomainName
+      attribute :region,       Region
+      attribute :memory,       Memory
+      attribute :max_duration, MaxDuration
+
+      sets :domain
+      sets :region
+      sets :memory
+      sets :max_duration
+
+      emits "VercelTargetDeclared"
+    end
+  end
+
+  aggregate "SharedDatabaseTarget" do
+    description "One platform's validated shared database instance — what deployed_to(\"AwsSharedDatabase\") must resolve to before hecks deploy project generates the RDS stack that several client sites each keep a database on."
+
+    identified_by :domain
+
+    attribute :domain,         DomainName
+    attribute :region,         Region
+    attribute :database_class, DatabaseClass
+    attribute :storage_gb,     StorageGb
+
+    value_object "DomainName" do
+      attribute :value, String
+      invariant("a domain is named") { !value.to_s.empty? }
+    end
+
+    value_object "Region" do
+      attribute :value, String
+      invariant("a region is named") { !value.to_s.empty? }
+    end
+
+    # An RDS instance class such as db.t4g.small.
+    value_object "DatabaseClass" do
+      attribute :value, String
+      invariant("a database class is db.family.size, such as db.t4g.small") { value.to_s.match?(/\Adb\.[a-z][a-z0-9-]*\.[a-z0-9]+\z/) }
+    end
+
+    # Every client's database lives on this disk, so it is sized for all of them; 20 GB is
+    # RDS's gp3 floor.
+    value_object "StorageGb" do
+      attribute :value, Integer
+      invariant("storage is at least 20 GB") { value >= 20 }
+      invariant("storage is at most 65536 GB") { value <= 65536 }
+    end
+
+    # All four required for the same reason as `BoxTarget.Declare`; this validates a target
+    # already resolved by `hecks deploy project`'s defaults.
+    command "Declare" do
+      goal "Validate one platform's shared database target before anything is generated from it"
+
+      attribute :domain,         DomainName
+      attribute :region,         Region
+      attribute :database_class, DatabaseClass
+      attribute :storage_gb,     StorageGb
+
+      sets :domain
+      sets :region
+      sets :database_class
+      sets :storage_gb
+
+      emits "SharedDatabaseTargetDeclared"
+    end
+  end
+
   # The validated shape of `hecks deploy tenant.provision`, which does the generating and provisioning.
   # Not a saga: each of its steps is idempotent and local, so there is nothing to resume.
   aggregate "Tenant" do

data/lib/hecks/deploy/oidc.json

@@ -301,6 +301,11 @@
       "verb": "Deploy::ServiceRoll.Verify",
       "role": null
     },
+    {
+      "scope": "deploy:shared_database_target.declare",
+      "verb": "Deploy::SharedDatabaseTarget.Declare",
+      "role": null
+    },
     {
       "scope": "deploy:smoke_run.flag",
       "verb": "Deploy::SmokeRun.Flag",
@@ -355,6 +360,11 @@
       "scope": "deploy:tenant.reprovision",
       "verb": "Deploy::Tenant.Reprovision",
       "role": null
+    },
+    {
+      "scope": "deploy:vercel_target.declare",
+      "verb": "Deploy::VercelTarget.Declare",
+      "role": null
     }
   ],
   "roles": [

data/lib/hecks/doors/usage_cache.rb

@@ -8,8 +8,9 @@ module Hecks
     #
     # The help is a pure function of the domain's declarations and of the gem that projects them,
     # and reading those is most of what a launcher costs. The answer is kept in a file named for a
-    # digest of everything it depends on (the domain's declaration files, the gem's own library,
-    # the hecks and Ruby versions, the environment overlay, the command line and the program name),
+    # digest of everything it depends on (the domain's declaration files, the gem's judging code and
+    # doors, the hecks and Ruby versions, the environment overlay, the command line and the
+    # program name),
     # so any edit to one of them is simply a different entry: nothing is ever stale, only unused.
     # Only an answer that ended well is kept, and any trouble with the cache itself is ignored
     # and the help is worked out as if it did not exist.
@@ -71,15 +72,20 @@ module Hecks
       # @return [String, nil] nil when the digest cannot be taken
       def entry_path(domain, argv, program, audience = "")
         digest = Digest::SHA256.new
-        [Hecks::VERSION, RUBY_VERSION, ENV["HECKS_ENVIRONMENT"].to_s, program, audience, argv.join("\0")].each do |part|
-          digest << part.to_s << "\0"
-        end
-        [domain, library].each { |root| fingerprint(root, digest) }
+        key_parts(program, audience, argv).each { |part| digest << part.to_s << "\0" }
+        fingerprint_code(domain, digest)
         File.join(directory, "usage-#{digest.hexdigest}.json")
       rescue SystemCallError
         nil
       end
 
+      # @return [Array<String>] what the answer depends on besides the files: the gem and Ruby
+      #   series, the environment overlay, the program and audience and the command line
+      def key_parts(program, audience, argv)
+        [Hecks::VERSION, Hecks::Bluebook::MetaValidator::VerdictCache.ruby_series,
+         ENV["HECKS_ENVIRONMENT"].to_s, program, audience, argv.join("\0")]
+      end
+
       # Feeds the digest every declaration file under `root`: its path below `root` and its bytes,
       # so a touch or a checkout elsewhere keeps the entry and an edit does not.
       def fingerprint(root, digest)
@@ -88,9 +94,13 @@ module Hecks
         end
       end
 
-      # @return [String] the gem's own library directory, which the frameworks load from
-      def library
-        File.expand_path("..", __dir__)
+      # Feeds the digest what shapes a help text: the domain's declarations, the judging trees of
+      # the gem (the same set the verdict cache keys on) and the doors that render the text. An
+      # edit to the gem's projections, deploy or release code cannot change a help line.
+      def fingerprint_code(domain, digest)
+        fingerprint(domain, digest)
+        digest << Hecks::Bluebook::MetaValidator::VerdictCache.code_digest << "\0"
+        fingerprint(__dir__, digest)
       end
 
       # Reads the remembered answer and marks the entry as used, so a sweep keeps what is read.

data/lib/hecks/fuzzing/coverage_campaign.rb

@@ -26,6 +26,7 @@ module Hecks
         @max_prefix_depth   = max_prefix_depth
         @corpus             = []
         @seen               = Set.new
+        @runtime_seen       = Set.new
         @verb_hits          = Hash.new(0)
         @declared_verbs     = Set.new
         @seeds = @spliced = @seeds_with_new = 0
@@ -43,34 +44,39 @@ module Hecks
       end
 
       # Folds one seed's trace into the running coverage; admits a corpus entry if it reached
-      # a new tuple.
+      # a new tuple, or, when `runtime` is given, a new runtime line or branch.
       #
       # @param seed [Integer] the seed the trace was generated from
       # @param plan [Fuzzing::CoverageCampaign::Plan] the plan that seed ran with
       # @param trace [Fuzzing::SequenceGenerator::Trace] from `SequenceGenerator.trace`
+      # @param runtime [Enumerable<String>, nil] keys from `RuntimeCoverage.measure`; nil when
+      #   runtime feedback is off, which leaves admission to tuples alone
       # @return [void]
-      def record(seed, plan, trace)
-        @seeds   += 1
-        @spliced += 1 if plan.spliced?
-        @declared_verbs.merge(trace.verbs)
-
-        new_at = trace.coverage.filter_map do |index, tuple|
-          @verb_hits[tuple.split(" | ").first] += 1
-          index if @seen.add?(tuple)
-        end
-        return if new_at.empty?
+      def record(seed, plan, trace, runtime: nil)
+        tally(plan, trace)
+        new_at = new_tuple_steps(trace)
+        fresh_runtime = new_runtime?(runtime)
+        return if new_at.empty? && !fresh_runtime
 
         @seeds_with_new += 1
-        admit(seed, plan, new_at.max + 1)
+        # A tuple cuts the entry at the step that reached it; a runtime key is not tied to a step,
+        # so a seed that reached only new runtime keeps its whole sequence.
+        admit(seed, plan, new_at.empty? ? [trace.steps.size, 1].max : new_at.max + 1)
       end
 
+      # The number of distinct runtime lines and branches reached so far; zero while runtime
+      # feedback is off.
+      def runtime_seen = @runtime_seen.size
+
       # The number of distinct coverage tuples reached so far.
       def tuples_seen = @seen.size
 
       # One line of running totals: tuples seen, seeds run, seeds with new coverage, splices.
       def summary
-        "coverage: #{@seen.size} distinct (verb, kind, state, mutation, outcome) tuple(s) over #{@seeds} seed(s); " \
-          "#{@seeds_with_new} seed(s) reached something new; #{@spliced} spliced from a corpus of #{@corpus.size}"
+        runtime = @runtime_seen.empty? ? "" : " and #{@runtime_seen.size} runtime line/branch key(s)"
+        "coverage: #{@seen.size} distinct (verb, kind, state, mutation, outcome) tuple(s)#{runtime} over " \
+          "#{@seeds} seed(s); #{@seeds_with_new} seed(s) reached something new; " \
+          "#{@spliced} spliced from a corpus of #{@corpus.size}"
       end
 
       # Serializes the accumulated corpus and coverage knowledge, JSON-safe, so a later process can
@@ -78,10 +84,12 @@ module Hecks
       # favor count, corpus and prefix-depth bounds — are configuration a caller supplies fresh each
       # time, not state, so they are not part of this.
       #
-      # @return [Hash] with string keys "corpus", "seen", "verb_hits", "declared_verbs"
+      # @return [Hash] with string keys "corpus", "seen", "runtime_seen", "verb_hits" and
+      #   "declared_verbs"
       def to_h
         { "corpus"         => @corpus.map { |entry| { "spec" => entry[:spec], "attempts" => entry[:attempts] } },
           "seen"           => @seen.to_a,
+          "runtime_seen"   => @runtime_seen.to_a.sort,
           "verb_hits"      => @verb_hits.dup,
           "declared_verbs" => @declared_verbs.to_a }
       end
@@ -94,9 +102,8 @@ module Hecks
       def restore!(state)
         state = state.transform_keys(&:to_s)
         @corpus = Array(state["corpus"]).map { |entry| { spec: entry["spec"], attempts: entry["attempts"] } }
-        @seen = Set.new(Array(state["seen"]))
+        @seen, @runtime_seen, @declared_verbs = %w[seen runtime_seen declared_verbs].map { |key| Set.new(Array(state[key])) }
         @verb_hits = Hash.new(0).merge(state["verb_hits"] || {})
-        @declared_verbs = Set.new(Array(state["declared_verbs"]))
       end
 
       # Builds a campaign that already knows what a prior campaign's `#to_h` reached, configured
@@ -116,6 +123,24 @@ module Hecks
 
       private
 
+      def tally(plan, trace)
+        @seeds   += 1
+        @spliced += 1 if plan.spliced?
+        @declared_verbs.merge(trace.verbs)
+      end
+
+      # The step indexes whose tuples nothing had reached before; each tuple's verb counts as a hit.
+      def new_tuple_steps(trace)
+        trace.coverage.filter_map do |index, tuple|
+          @verb_hits[tuple.split(" | ").first] += 1
+          index if @seen.add?(tuple)
+        end
+      end
+
+      def new_runtime?(runtime)
+        runtime.to_a.map { |key| @runtime_seen.add?(key) }.any?
+      end
+
       def splice_prefix(random)
         entry = @corpus[random.rand(@corpus.size)]
         entry[:spec].merge("steps" => random.rand(1..entry[:attempts]))

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