hecks 3.4.2 → 3.6.0

data/lib/hecks/fuzzing/isolated_boot.rb

@@ -3,14 +3,25 @@ require "tmpdir"
 require "securerandom"
 require_relative "outside_world"
 require_relative "../runtime/adapter_lookup"
+require_relative "isolated_boot/copying"
+require_relative "isolated_boot/worlds"
+require_relative "isolated_boot/postgres_scratch"
 
 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
-      # A vendored package named by `attaches "name", from: :vendor`.
-      VENDORED_ATTACHED = /attaches\s*\(?\s*"([\w-]+)"\s*\)?\s*,\s*from:\s*:vendor/
+      # 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
+
+      extend Copying
+      extend Worlds
+      extend PostgresScratch
 
       module_function
 
@@ -25,59 +36,22 @@ module Hecks
           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
+          rebind!(copy, adapter, database: database, schema: schema, scratch: scratch)
           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|
-          text = File.read(path)
-          text.scan(VENDORED_ATTACHED).flatten
-        end
-        names.uniq.each do |name|
-          package = File.join(File.dirname(source), "vendor", "embryonaut_bluebooks", name)
-          next unless File.directory?(package)
-
-          copy_files(package, File.join(File.dirname(destination), "vendor", "embryonaut_bluebooks", name))
+      # Rewrites the copy's bindings for `adapter`.
+      #
+      # @raise [ArgumentError] if `adapter` is not one of the fuzz adapters
+      def rebind!(copy, adapter, database:, schema:, scratch:)
+        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
       end
 
@@ -99,207 +73,6 @@ module Hecks
         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 query sweep.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

data/lib/hecks/fuzzing/persistence_parity.rb

@@ -17,13 +17,13 @@ module Hecks
       # @param left [Symbol] an `IsolatedBoot` adapter: `:memory`, `:sqlite`, `:postgres`,
       #   `:postgres_era`
       # @param right [Symbol] the second adapter, same set as `left`
-      # @param database [String, nil] required when either side is `:postgres_era`
-      # @param schema [String, nil] required when either side is `:postgres_era`
+      # @param storage [Hash] connection settings `Replay.call` takes, passed to both sides:
+      #   `database:` and `schema:` (strings, required when either side is `:postgres_era`)
       # @return [Array<Hash>] entries `{field: String, left => Object, right => Object}`,
       #   keyed by the adapter symbols; empty if both sides agree
-      def diff(domain_path, steps, left: :memory, right: :postgres_era, database: nil, schema: nil)
-        left_result  = Replay.call(domain_path, steps, adapter: left, database: database, schema: schema)
-        right_result = Replay.call(domain_path, steps, adapter: right, database: database, schema: schema)
+      def diff(domain_path, steps, left: :memory, right: :postgres_era, **storage)
+        left_result  = Replay.call(domain_path, steps, adapter: left, **storage)
+        right_result = Replay.call(domain_path, steps, adapter: right, **storage)
 
         divergences = []
         divergences.concat(diff_instances(left_result, right_result, left, right))

data/lib/hecks/fuzzing/properties/aggregation_recompute.rb

@@ -0,0 +1,121 @@
+module Hecks
+  module Fuzzing
+    module Properties
+      # Independent recomputations of read-model reductions and `group_by` nestings, for
+      # `InvariantsAndAggregation` to compare against what a query actually answered.
+      module AggregationRecompute
+        # The read model a recorded ask named, when it belongs to `bluebook`.
+        def asked_read_model(bluebook, asked)
+          domain, name = asked[:query].to_s.split(".", 2)
+          bluebook.read_model(name) if name && domain == bluebook.name
+        end
+
+        # The head a read model reduces or groups: the one declared `many`.
+        def many_head(model) = model.aggregate_heads.find { |head| head[:many] }
+
+        # ADR 0078's siblings of `count`/`median`, each an independent fold over the same
+        # eligible rows — never reusing ReadModelInterpreter#reduce's own arithmetic, only the
+        # shared field-reading primitives `recompute_median` already relied on.
+        def recompute_reduction(model, rows)
+          return rows.length if model.count?
+          return recompute_median(rows, model.median_field) if model.median_field
+          return recompute_values(rows, model.sum_field).sum if model.sum_field
+          return recompute_avg(rows, model.avg_field) if model.avg_field
+
+          recompute_extremum_or_flag(model, rows)
+        end
+
+        # The `min`, `max`, `percentile`, `any` and `all` folds of `recompute_reduction`.
+        def recompute_extremum_or_flag(model, rows)
+          return recompute_values(rows, model.min_field).min if model.min_field
+          return recompute_values(rows, model.max_field).max if model.max_field
+
+          recompute_percentile_or_flag(model, rows)
+        end
+
+        # The `percentile`, `any` and `all` folds of `recompute_reduction`.
+        def recompute_percentile_or_flag(model, rows)
+          return recompute_percentile(rows, model.percentile_field, model.percentile_at) if model.percentile_field
+          return recompute_values(rows, model.any_field).any? if model.any_field
+
+          recompute_values(rows, model.all_field).all?
+        end
+
+        def recompute_values(rows, field)
+          rows.map { |state| comparable_field(state, field) }.compact
+        end
+
+        # A field's value as the interpreter itself compares it.
+        def comparable_field(state, field)
+          Ports::Query::InMemory.comparable(QuerySpecification::FieldPath.dig(state, field))
+        end
+
+        def recompute_avg(rows, field)
+          values = recompute_values(rows, field)
+          values.empty? ? nil : values.sum.to_f / values.length
+        end
+
+        # Same linear-interpolation formula as `ReadModelInterpreter#percentile`, written
+        # independently here rather than called, for the same reason `recompute_median`
+        # already is: an oracle that calls the interpreter's own fold agrees with a bug in it
+        # by construction (ADR 0061's `nest_rows` lesson).
+        def recompute_percentile(rows, field, at)
+          values = recompute_values(rows, field).sort
+          return nil if values.empty?
+
+          interpolate(values, at * (values.length - 1))
+        end
+
+        def interpolate(values, position)
+          lower = position.floor
+          fraction = position - lower
+          fraction.zero? ? values[lower] : values[lower] + (fraction * (values[lower + 1] - values[lower]))
+        end
+
+        # ReadModelInterpreter#median's own definition, reproduced: the true
+        # middle for an odd count, the average of the two middles for an even
+        # count, `nil` for empty — never zero, so "nothing" isn't "zero."
+        def recompute_median(rows, field)
+          values = rows.map { |state| comparable_field(state, field) }.compact.sort
+          return nil if values.empty?
+
+          middle = values.length / 2
+          values.length.odd? ? values[middle] : (values[middle - 1] + values[middle]) / 2.0
+        end
+
+        # The eligible rows a `count`/`median` head reduces: every instance of
+        # the reduced head's own aggregate, FK-matched against the report's root
+        # reference (if any), then narrowed by the report's own `where` clauses.
+        def eligible_rows(bluebook, instances, model, reduced_head, args)
+          prefix = "#{bluebook.name}::#{reduced_head[:aggregate]}#"
+          # `id:` merged in, the same shape every live head row carries —
+          # count/median never read it, but group_by's own nesting does.
+          rows = instances.filter_map { |key, state| state.merge(id: key.split("#").last) if key.start_with?(prefix) }
+          rows = rows_for_reference(rows, bluebook.aggregate(reduced_head[:aggregate]), model, args) if model.reference_target
+
+          rows.select { |state| satisfies_wheres?(model, state, args) }
+        end
+
+        # The rows whose foreign key holds the root reference the ask named.
+        def rows_for_reference(rows, aggregate, model, args)
+          reference_id = args[model.reference_name].to_s
+          fk_fields = foreign_key_fields(aggregate, model)
+          rows.select { |state| fk_fields.any? { |field| state[field].to_s == reference_id } }
+        end
+
+        # The names of `aggregate`'s attributes referencing the read model's root.
+        def foreign_key_fields(aggregate, model)
+          aggregate.attributes.select do |attribute|
+            attribute.reference? && attribute.type.target_name == model.reference_target.to_s
+          end.map(&:name)
+        end
+
+        def satisfies_wheres?(model, state, args)
+          model.wheres.all? do |clause|
+            Ports::Query::InMemory.holds?(clause, comparable_field(state, clause.field), args)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/properties/catalog.rb

@@ -0,0 +1,138 @@
+module Hecks
+  module Fuzzing
+    module Properties
+      # The standard battery, in the order `check` reports it.
+      PROPERTY_NAMES = [
+        :lifecycle_values_are_declared,
+        :saga_advances_follow_declared_handlers,
+        :query_answers_match_reference,
+        :guard_refusals_are_declared,
+        :sagas_rehydrate_cleanly,
+        :fanout_dispatches_once_per_matching_row,
+        :aggregation_matches_recompute,
+        :stored_records_satisfy_declared_invariants,
+        :group_by_matches_recompute,
+        :paging_offset_partitions_correctly,
+        :lifecycle_guard_and_given_violations_are_refused,
+        :authorize_scopes_or_refuses,
+        :commands_respect_tenant_scope,
+        :dispatch_binding_fidelity,
+        :mutations_match_recompute,
+        :dry_runs_leave_no_trace,
+        :corrections_reference_an_emitted_event,
+        :outbox_rows_match_reactions,
+        :policy_reactions_follow_declared_wiring,
+        :declared_undelivered_policies_stay_undelivered,
+        :references_resolve_to_earlier_records
+      ].freeze
+
+      # Which language feature each property is answerable for — exhaustive of
+      # what would go unchecked without it, not of everything its body touches.
+      FEATURE_COVERAGE = {
+        lifecycle_values_are_declared:                    %w[Aggregate#state_field Aggregate#state_start Aggregate#transitions
+                                                             Entity#state_field Entity#state_start Entity#transitions],
+        saga_advances_follow_declared_handlers:           %w[Handler#from_state Handler#to_state Handler#event_type],
+        query_answers_match_reference:                    %w[Query#wheres Query#order_field Query#order_way Query#limit],
+        paging_offset_partitions_correctly:               %w[Query#options],
+        authorize_scopes_or_refuses:                      %w[Query#options],
+        guard_refusals_are_declared:                      %w[Command#givens Command#ensures Command#needs],
+        lifecycle_guard_and_given_violations_are_refused: %w[Command#from Aggregate#preconditions Entity#preconditions],
+        # Dispatch#command_name/with_spec aren't claimable feature names — the
+        # coverage walk only reaches one level of entity nesting and Dispatch
+        # sits two deep — but this property still checks the real behavior
+        # (dispatch_args) those names would have covered.
+        dispatch_binding_fidelity:                        %w[Handler#dispatches Policy#with_spec],
+        mutations_match_recompute:                        %w[Command#mutations],
+        sagas_rehydrate_cleanly:                          %w[ProcessManager#states ProcessManager#correlates_by
+                                                             ProcessManager#starts_on ProcessManager#ends_on],
+        fanout_dispatches_once_per_matching_row:          %w[Policy#for_each Policy#where],
+        aggregation_matches_recompute:                    %w[ReadModel#count ReadModel#median_field ReadModel#sum_field
+                                                             ReadModel#avg_field ReadModel#min_field ReadModel#max_field
+                                                             ReadModel#percentile_field ReadModel#percentile_at
+                                                             ReadModel#any_field ReadModel#all_field],
+        stored_records_satisfy_declared_invariants:       %w[Aggregate#invariants Entity#invariants],
+        group_by_matches_recompute:                       %w[ReadModel#group_by],
+        # A runtime door, not a grammar construct — `Dispatcher#dry_run?` is not
+        # a word a bluebook declares. Listed empty rather than omitted, so every
+        # property still names what it is answerable for.
+        dry_runs_leave_no_trace:                          [],
+        # Another runtime door, not a grammar construct — same reasoning as
+        # dry_runs_leave_no_trace above.
+        outbox_rows_match_reactions:                      [],
+        # Reads command.mutations for :corrects ops — the same list
+        # mutations_match_recompute reads, for a different question.
+        corrections_reference_an_emitted_event:           %w[Command#mutations],
+        # Reads each logged reaction back against the policy that produced it: the event it
+        # answers, the trigger it builds, and the domain `across` sends it to.
+        policy_reactions_follow_declared_wiring:          %w[Policy#on_event Policy#trigger_command Policy#target_domain],
+        # model_check holds the static half of `expect_undelivered`; this is the runtime half.
+        declared_undelivered_policies_stay_undelivered:   %w[Policy#expect_undelivered],
+        # An accepted referencing command addressed a record an earlier event created.
+        references_resolve_to_earlier_records:            %w[Command#references],
+        # No feature string exists for what this reads: an argument's own
+        # `relationship` (Argument is a value object, outside the meta-domain
+        # walk). Its declaration side, `Query#options`, is already claimed by
+        # authorize_scopes_or_refuses.
+        commands_respect_tenant_scope:                    []
+      }.freeze
+
+      # Features a replay could never observe violated, because construction
+      # makes the violation impossible to produce — not untested, but
+      # unfalsifiable. Each entry names the runtime path that guarantees it;
+      # add one only after reading and confirming that path (mirrors the
+      # discipline spec/fuzzing/meta_domain_coverage_spec.rb's KNOWN_GAPS demands
+      # in the other direction).
+      GUARANTEED_BY_CONSTRUCTION = {
+        "Aggregate#attributes"    => "every field's pattern/closed-set/type passes through Value.build's one coercion " \
+                                     "door (value/coercion.rb#check_patterns, value/admission.rb) before it can exist " \
+                                     "— a stored value that violated its own declared shape was never producible to " \
+                                     "begin with",
+        "Aggregate#value_objects" => "the shape being coerced above — same door, same guarantee",
+        # S17, ADR 0026 — saga_advances_follow_declared_handlers already walks
+        # this list to find event_type/from_state/to_state; same door, same guarantee.
+        "ProcessManager#handlers" => "saga_advances_follow_declared_handlers already walks this list to find " \
+                                     "event_type/from_state/to_state — same door, same guarantee",
+        "Aggregate#identified_by" => "CommandInterpreter's data-driven dispatch order refuses AlreadyExists " \
+                                     "(command_interpreter.rb, command.creates?) for every creating command uniformly, " \
+                                     "before a duplicate id can ever be stored — collision is refused at the door, not " \
+                                     "produced and later caught",
+        "Entity#identified_by"    => "EntityElement.check_entity_collision (runtime/entity_element.rb, moved there " \
+                                     "BUG#145 so both call sites share it) checks Array(current) against every part " \
+                                     "of the entity's own identity before an append can land — MutationApplier#" \
+                                     "entity_element's aggregate-owned call (Workspace.boards, on both branches " \
+                                     "identity arrives by: caller-supplied, or composite) AND EntityElement#" \
+                                     "appended_to_element's entity-owned, nested-one-hop-further call (Board.cards — " \
+                                     "unconditional, no auto-mint branch exists at that depth) — the same " \
+                                     "AlreadyExists refusal Aggregate#identified_by gets above, one or two levels " \
+                                     "down. Auto-minted (aggregate-owned) entities never reach the check " \
+                                     "(current.size + 1 can't repeat unless something remove:s from the list between " \
+                                     "mints, which no real domain does today — see the comment on #entity_element " \
+                                     "itself)",
+        "Command#attributes"      => "command arguments are coerced through the SAME Value.build door as any other " \
+                                     "attribute — an accepted dispatch's own args already passed pattern/admits/invariant checks",
+        "Command#emits"           => "CommandRules::Emission#emit iterates command.emits ITSELF to construct every " \
+                                     "announced Event (command_rules/emission.rb) — there is no other path to emit, so " \
+                                     "a command can never announce a name its own declaration doesn't list",
+        "Query#attributes"        => "query arguments are coerced through the same Value.build door — same guarantee as " \
+                                     "Command#attributes",
+        "Query#returns"           => "every row a port answers is built as the returned value object by Value.build " \
+                                     "(QueryInterpreter#shaped) before it enters the domain — an answer of any other " \
+                                     "shape is refused, so none can be accepted",
+        "Entity#attributes"       => "same coercion door, one level in — an entity's own attributes are Value-typed exactly " \
+                                     "the way an aggregate's are",
+        "ValueObject#attributes"  => "the shape Value.build enforces IS this declaration — the guarantee and the " \
+                                     "feature are the same fact seen from two sides",
+        "ValueObject#invariants"  => "run inside the SAME coercion call (coercion.rb, before construction returns) " \
+                                     "that pattern-checks a VO's fields — a VO whose invariant did not hold could not " \
+                                     "finish being built",
+        "ValueObject#rows"        => "closed-set membership is checked in value/admission.rb, the second half of the same " \
+                                     "one construction door",
+        # S17, ADR 0026 — Member is a genuine entity, so this reads Member#pairs,
+        # not Member#shape. ValueObject#members is the same fact ValueObject#rows
+        # counts, seen from the other side.
+        "ValueObject#members"     => "the members list IS what ValueObject#rows counts — same door, same guarantee",
+        "Member#pairs"            => "one level into ValueObject#rows — same door"
+      }.freeze
+    end
+  end
+end

data/lib/hecks/fuzzing/properties/corrections.rb

@@ -19,26 +19,25 @@ module Hecks
 
           (history[:bluebooks] || {}).each do |domain, bluebook|
             bluebook.aggregates.each do |aggregate|
-              aggregate_key = "#{domain}::#{aggregate.hecks_name}"
-
-              each_command_including_entities(aggregate) do |command|
-                corrects_mutations = command.mutations.select { |mutation| mutation.op == :corrects }
-                next if corrects_mutations.empty?
+              violations.concat(aggregate_corrections(history[:events], "#{domain}::#{aggregate.hecks_name}", aggregate))
+            end
+          end
 
-                corrects_mutations.each do |mutation|
-                  corrected_event = mutation.target.to_s
+          violations.empty? || violations.uniq.join("; ")
+        end
 
-                  command.emits.each do |produced_event_name|
-                    violations.concat(unmatched_corrections(history[:events], aggregate_key,
-                                                            produced_event_name.to_s, corrected_event,
-                                                            command.hecks_name))
-                  end
-                end
+        # Every unmatched correction among the commands of `aggregate` and its entities.
+        def aggregate_corrections(events, aggregate_key, aggregate)
+          found = []
+          each_command_including_entities(aggregate) do |command|
+            command.mutations.select { |mutation| mutation.op == :corrects }.each do |mutation|
+              command.emits.each do |produced_event_name|
+                found.concat(unmatched_corrections(events, aggregate_key, produced_event_name.to_s,
+                                                   mutation.target.to_s, command.hecks_name))
               end
             end
           end
-
-          violations.empty? || violations.uniq.join("; ")
+          found
         end
 
         # Finds every occurrence of `produced_event_name`, on `aggregate_key`, with no
@@ -58,11 +57,7 @@ module Hecks
           end
 
           own_events.filter_map do |event, index|
-            preceding = events.first(index)
-            next if preceding.any? do |earlier|
-              earlier[:name] == corrected_event && earlier[:aggregate] == aggregate_key &&
-              earlier[:id].to_s == event[:id].to_s
-            end
+            next if corrected_earlier?(events.first(index), aggregate_key, corrected_event, event)
 
             "#{command_name} (#{aggregate_key}##{event[:id]}) emitted #{produced_event_name}, claiming to " \
               "correct #{corrected_event}, but no #{corrected_event} for the same aggregate/id appears " \
@@ -70,6 +65,14 @@ module Hecks
           end
         end
 
+        # Whether `preceding` holds the corrected event for `event`'s aggregate and id.
+        def corrected_earlier?(preceding, aggregate_key, corrected_event, event)
+          preceding.any? do |earlier|
+            earlier[:name] == corrected_event && earlier[:aggregate] == aggregate_key &&
+              earlier[:id].to_s == event[:id].to_s
+          end
+        end
+
         # Yields every command on `owner` and, recursively, on its entities (ADR 0026).
         #
         # @param owner [Bluebook::Aggregate, Bluebook::Entity] the aggregate or entity