hecks 1.3.0 → 1.5.0

data/lib/hecks/fuzzing/nondeterministic.rb

@@ -0,0 +1,79 @@
+module Hecks
+  module Fuzzing
+    # The one declared set of `FIELDS` that leave a comparison — partition,
+    # not filter. Every comparison in lib/hecks/fuzzing that drops a field
+    # before comparing two histories names a group here instead of writing
+    # its own literal `except(...)` list, so the reason for dropping a field
+    # is written exactly once, beside the field.
+    #
+    # Two specs hold this set honest (spec/fuzzing/nondeterministic_spec.rb):
+    # a literal except-list naming any of these fields anywhere under
+    # lib/hecks/fuzzing fails the build (the tolerance must be declared
+    # here, not re-derived at a call site), and every declared field must
+    # actually be produced where its group says — a field nothing emits any
+    # more is a stale tolerance and fails too.
+    #
+    # Groups are keyed by the shape the field rides on, since the same name
+    # can be compared on one surface and dropped on another:
+    #
+    # - `query_row`  — one entry of `Replay.call`'s `:queries`.
+    # - `outbox_row` — one row of an `:outbox_traces` entry's `:rows`.
+    # - `event`      — an event hash in full `Event#to_h` form (an outbox
+    #                  row's `:event`, or a Rust binary's `events` entries,
+    #                  string-keyed there).
+    # - `history`    — the top-level `Replay.call` history hash itself.
+    module Nondeterministic
+      FIELDS = {
+        query_row:  {
+          instances_at: "a full state snapshot taken for the query oracle's own use " \
+                        "(Properties::Querying); the same state is already compared as `instances`, " \
+                        "so keeping it would re-report one instances divergence under every query step"
+        }.freeze,
+        outbox_row: {
+          event_uid:   "`Runtime::Outbox::Fanout#rows_for`'s own SecureRandom.uuid, minted fresh per " \
+                       "enqueue and kept off `Event#to_h` — relay bookkeeping, never something the " \
+                       "domain produced, so two otherwise-identical replays carry two different uuids",
+          delivery_id: "`\"\#{event_uid}/\#{consumer}\"` — inherits event_uid's per-enqueue uuid"
+        }.freeze,
+        event:      {
+          occurred_at: "a wall-clock read; never reproducible byte-for-byte between two independent " \
+                       "runs (Replay's own projected `:events` leave it off for the same reason)"
+        }.freeze,
+        history:    {
+          bluebook:  "a live IR object (the first-loaded bluebook) handed to properties — an object " \
+                     "identity, not a value, so two boots never compare equal on it",
+          bluebooks: "the full live IR map, keyed by domain — object identities, same as `bluebook`"
+        }.freeze
+      }.freeze
+
+      module_function
+
+      # Lists the nondeterministic field names declared for one comparison group.
+      #
+      # @param group [Symbol] a key of `FIELDS`, such as `:query_row` or `:event`
+      # @return [Array<Symbol>] the field names declared for `group`
+      # @raise [KeyError] if `group` names no declared group
+      def names(group)
+        FIELDS.fetch(group).keys
+      end
+
+      # Every declared name, across every group.
+      #
+      # @return [Array<Symbol>] the union of every group's field names, deduplicated
+      def all_names
+        FIELDS.values.flat_map(&:keys).uniq
+      end
+
+      # `hash` without `group`'s fields — symbol keys, the shape every
+      # Ruby-side history carries.
+      #
+      # @param hash [Hash] a symbol-keyed row, event, or history hash to compare
+      # @param group [Symbol] a key of `FIELDS` naming which fields to drop
+      # @return [Hash] `hash` with `group`'s declared fields removed
+      # @raise [KeyError] if `group` names no declared group
+      def strip(hash, group)
+        hash.except(*names(group))
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/persistence_parity.rb

@@ -1,16 +1,19 @@
 require "json"
 require_relative "replay"
+require_relative "nondeterministic"
 
 module Hecks
   module Fuzzing
-    # THE SECOND DIFFERENTIAL AXIS — bin/qa_sweep's own `diff_ruby_vs_rust`
-    # compares two DIFFERENT ENGINES (the Ruby interpreter vs the compiled
-    # Rust kernel) against the SAME persistence (Memory, always — see
-    # `SequenceGenerator`'s own header: sequence GENERATION stays
+    # ## The second differential axis
+    #
+    # bin/qa_sweep's own `diff_ruby_vs_rust`
+    # compares two different engines (the Ruby interpreter vs the compiled
+    # Rust kernel) against the same persistence (Memory, always — see
+    # `SequenceGenerator`'s own header: sequence generation stays
     # Memory-only, and `IsolatedBoot`'s own header explains why every
     # existing fuzz/replay path structurally cannot reach a real Postgres-
     # bound domain's own SQL compilation). This module compares the
-    # opposite pairing: the SAME ONE Ruby engine, against two DIFFERENT
+    # opposite pairing: the same one Ruby engine, against two different
     # persistences — Memory (the reference, exactly as fast and as
     # deterministic as every other fuzz check) and a real, disposable
     # `PostgresEra` database (the actual SQL compute/rekey/query-pushdown
@@ -26,20 +29,24 @@ module Hecks
     # Memory, unconditionally, no matter what `directory.world` itself
     # declares.
     #
-    # NOT a replacement for `bin/qa_sweep`'s own Ruby-vs-Rust differential
+    # ## A separate axis, not a replacement
+    #
+    # Not a replacement for `bin/qa_sweep`'s own Ruby-vs-Rust differential
     # mode — a genuinely separate axis, opt-in (`--persistence-parity`),
     # because this one pays for a real `PG.connect` and real SQL per
     # dispatch where Memory-vs-Rust pays for neither. See `bin/qa_sweep`'s
     # own `--persistence-parity` handling for the seed-count dial that
     # keeps that cost bounded.
     #
-    # GENERALIZED TO `left:`/`right:` — originally hardcoded to Memory vs
+    # ## `left:`/`right:`
+    #
+    # Generalized — originally hardcoded to Memory vs
     # PostgresEra (the only pairing that existed), now any two of
     # `IsolatedBoot`'s own adapter symbols (`:memory`, `:sqlite`,
     # `:postgres`, `:postgres_era`). Defaults preserve the original
     # pairing exactly, so every existing caller (this file's own spec,
     # `bin/qa_sweep`'s `--persistence-parity`) is unchanged. The second
-    # pairing this generalization exists FOR is Memory vs SQLite
+    # pairing this generalization exists for is Memory vs SQLite
     # (`QualityControlDials::ADAPTER_PARITY_PAIRS`, `bin/qa_sweep`'s own
     # `adapter_parity_sqlite` mode) — `:sqlite` is nearly as cheap as
     # Memory itself (`IsolatedBoot#rebind_to_sqlite!`'s own header: an
@@ -48,7 +55,9 @@ module Hecks
     # loop instead of needing a deferred wave of its own the way
     # PostgresEra does.
     #
-    # `database:`/`schema:` — REQUIRED only when `:postgres_era` is one of
+    # ## `database:`/`schema:`
+    #
+    # Required only when `:postgres_era` is one of
     # the two adapters (the caller — today, only `bin/qa_sweep` — owns the
     # disposable database's whole lifecycle: created before the sweep,
     # dropped after — see that script's own comment, and the discipline
@@ -58,21 +67,21 @@ module Hecks
     module PersistenceParity
       module_function
 
-      # THE SAME SIX FIELDS `bin/qa_sweep`'s own `diff_ruby_vs_rust`
+      # The same six fields `bin/qa_sweep`'s own `diff_ruby_vs_rust`
       # compares (its own comment: "instances, events, refusals, queries,
       # sagas, reactions") — deliberately the identical set, so a report
       # this mode produces reads exactly like the sibling mode's own,
       # differing only in which two things were compared, not in what
       # "found something" means.
       #
-      # SIMPLER NORMALIZATION THAN `diff_ruby_vs_rust`, on purpose — that
-      # method reduces Rust's OWN JSON-over-stdout output to "wire
+      # Simpler normalization than `diff_ruby_vs_rust`, on purpose — that
+      # method reduces Rust's own JSON-over-stdout output to "wire
       # precision" and filters known Ruby/Rust structural gaps, because
       # it is comparing two genuinely different engines that are allowed
       # to differ in already-catalogued, understood ways. Both sides here
-      # are the SAME Ruby engine (`Replay.call`, called twice, adapter
+      # are the same Ruby engine (`Replay.call`, called twice, adapter
       # only) — there is no second engine's own known-gap catalogue to
-      # filter against, so any real difference IS the finding. Both
+      # filter against, so any real difference is the finding. Both
       # results still round-trip through `JSON.generate`/`JSON.parse`
       # before comparing, matching `diff_ruby_vs_rust`'s own discipline —
       # not because either side needs a wire-format reduction, but so
@@ -80,6 +89,21 @@ module Hecks
       # sides identically (a `Runtime::Value`, a `Symbol` key, a `Time`
       # nobody asked for — none of that survives an accidental leak into
       # this comparison unnoticed).
+      #
+      # @param domain_path [String] path to the domain directory to boot
+      # @param steps [Array<Hash>] the step list to replay against both adapters
+      # @param left [Symbol] the first adapter to replay against, one of
+      #   `IsolatedBoot`'s adapter symbols (`:memory`, `:sqlite`, `:postgres`,
+      #   `:postgres_era`)
+      # @param right [Symbol] the second adapter to replay against, same set as `left`
+      # @param database [String, nil] connection identity for `:postgres_era`; required
+      #   when `left` or `right` is `:postgres_era`, ignored otherwise
+      # @param schema [String, nil] disposable schema name for `:postgres_era`; required
+      #   when `left` or `right` is `:postgres_era`, ignored otherwise
+      # @return [Array<Hash>] divergence entries, each `{field: String, left => Object,
+      #   right => Object}` — `left`'s and `right`'s own adapter symbols become the
+      #   entry's own keys, holding each side's JSON-shaped value for that field; empty
+      #   if both sides agree on every field
       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)
@@ -94,8 +118,25 @@ module Hecks
         divergences
       end
 
+      # Round-trips `value` through JSON, the same wire-precision reduction
+      # `diff_ruby_vs_rust` uses so `Hash#==`/`Array#==` compares plain,
+      # JSON-shaped data on both sides.
+      #
+      # @param value [Object] any JSON-serializable value from a replay result
+      # @return [Object] `value`, JSON-round-tripped: Symbol keys become Strings,
+      #   and any non-JSON-native value surfaces as its own JSON form
       def as_json(value) = JSON.parse(JSON.generate(value))
 
+      # Compares both sides' stored instances.
+      #
+      # @param left_result [Hash] `left`'s replay result, as returned by `Fuzzing::Replay.call`
+      # @param right_result [Hash] `right`'s replay result, as returned by `Fuzzing::Replay.call`
+      # @param left [Symbol] the adapter `left_result` was replayed against; becomes
+      #   this entry's own key
+      # @param right [Symbol] the adapter `right_result` was replayed against; becomes
+      #   this entry's own key
+      # @return [Array<Hash>] one `{field: "instances", left => Object, right => Object}`
+      #   entry if the two sides' JSON-shaped instances differ; empty otherwise
       def diff_instances(left_result, right_result, left, right)
         l = as_json(left_result[:instances])
         r = as_json(right_result[:instances])
@@ -104,6 +145,16 @@ module Hecks
         [{ field: "instances", left => l, right => r }]
       end
 
+      # Compares both sides' emitted events.
+      #
+      # @param left_result [Hash] `left`'s replay result, as returned by `Fuzzing::Replay.call`
+      # @param right_result [Hash] `right`'s replay result, as returned by `Fuzzing::Replay.call`
+      # @param left [Symbol] the adapter `left_result` was replayed against; becomes
+      #   this entry's own key
+      # @param right [Symbol] the adapter `right_result` was replayed against; becomes
+      #   this entry's own key
+      # @return [Array<Hash>] one `{field: "events", left => Object, right => Object}`
+      #   entry if the two sides' JSON-shaped events differ; empty otherwise
       def diff_events(left_result, right_result, left, right)
         l = as_json(left_result[:events])
         r = as_json(right_result[:events])
@@ -112,11 +163,22 @@ module Hecks
         [{ field: "events", left => l, right => r }]
       end
 
+      # Compares both sides' refusals.
+      #
       # `verb:`/`kind:` normalized to plain strings the same way
       # `diff_ruby_vs_rust`'s own `ruby_refusals` mapping does — both
       # sides here already answer strings (`Replay#refusal_kind` always
       # returns one), so this is belt-and-suspenders consistency with the
       # sibling mode's own shape, not a real coercion.
+      #
+      # @param left_result [Hash] `left`'s replay result, as returned by `Fuzzing::Replay.call`
+      # @param right_result [Hash] `right`'s replay result, as returned by `Fuzzing::Replay.call`
+      # @param left [Symbol] the adapter `left_result` was replayed against; becomes
+      #   this entry's own key
+      # @param right [Symbol] the adapter `right_result` was replayed against; becomes
+      #   this entry's own key
+      # @return [Array<Hash>] one `{field: "refusals", left => Object, right => Object}`
+      #   entry if the two sides' normalized refusals differ; empty otherwise
       def diff_refusals(left_result, right_result, left, right)
         normalize = lambda do |refusals|
           refusals.map { |r| { "verb" => r[:verb].to_s, "kind" => r[:kind].to_s, "error" => r[:error] } }
@@ -128,14 +190,22 @@ module Hecks
         [{ field: "refusals", left => l, right => r }]
       end
 
-      # `instances_at:` dropped from every entry — the same reason
-      # `diff_ruby_vs_rust` excludes it (`row.except(:instances_at)`):
-      # it is a full state snapshot taken for the QUERY oracle's own use,
-      # already covered by `diff_instances` above, and would make every
-      # query-step entry re-litigate the SAME instances divergence a
-      # second time under a different field name.
+      # Compares both sides' query answers.
+      #
+      # `Nondeterministic`'s `query_row` group dropped from every entry —
+      # the same group `Differential.diff` drops, for the reason declared
+      # there (already covered by `diff_instances` above).
+      #
+      # @param left_result [Hash] `left`'s replay result, as returned by `Fuzzing::Replay.call`
+      # @param right_result [Hash] `right`'s replay result, as returned by `Fuzzing::Replay.call`
+      # @param left [Symbol] the adapter `left_result` was replayed against; becomes
+      #   this entry's own key
+      # @param right [Symbol] the adapter `right_result` was replayed against; becomes
+      #   this entry's own key
+      # @return [Array<Hash>] one `{field: "queries", left => Object, right => Object}`
+      #   entry if the two sides' stripped, JSON-shaped queries differ; empty otherwise
       def diff_queries(left_result, right_result, left, right)
-        strip = ->(rows) { rows.map { |row| row.except(:instances_at) } }
+        strip = ->(rows) { rows.map { |row| Nondeterministic.strip(row, :query_row) } }
         l = as_json(strip.call(left_result[:queries]))
         r = as_json(strip.call(right_result[:queries]))
         return [] if l == r
@@ -143,6 +213,16 @@ module Hecks
         [{ field: "queries", left => l, right => r }]
       end
 
+      # Compares both sides' saga logs.
+      #
+      # @param left_result [Hash] `left`'s replay result, as returned by `Fuzzing::Replay.call`
+      # @param right_result [Hash] `right`'s replay result, as returned by `Fuzzing::Replay.call`
+      # @param left [Symbol] the adapter `left_result` was replayed against; becomes
+      #   this entry's own key
+      # @param right [Symbol] the adapter `right_result` was replayed against; becomes
+      #   this entry's own key
+      # @return [Array<Hash>] one `{field: "sagas", left => Object, right => Object}`
+      #   entry if the two sides' JSON-shaped sagas differ; empty otherwise
       def diff_sagas(left_result, right_result, left, right)
         l = as_json(left_result[:sagas])
         r = as_json(right_result[:sagas])
@@ -151,6 +231,16 @@ module Hecks
         [{ field: "sagas", left => l, right => r }]
       end
 
+      # Compares both sides' reaction logs.
+      #
+      # @param left_result [Hash] `left`'s replay result, as returned by `Fuzzing::Replay.call`
+      # @param right_result [Hash] `right`'s replay result, as returned by `Fuzzing::Replay.call`
+      # @param left [Symbol] the adapter `left_result` was replayed against; becomes
+      #   this entry's own key
+      # @param right [Symbol] the adapter `right_result` was replayed against; becomes
+      #   this entry's own key
+      # @return [Array<Hash>] one `{field: "reactions", left => Object, right => Object}`
+      #   entry if the two sides' JSON-shaped reactions differ; empty otherwise
       def diff_reactions(left_result, right_result, left, right)
         l = as_json(left_result[:reactions])
         r = as_json(right_result[:reactions])

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

@@ -1,7 +1,7 @@
 module Hecks
   module Fuzzing
     module Properties
-      # ANGLE-9 — `corrects` (retroactive correction) had exactly one
+      # Angle-9 — `corrects` (retroactive correction) had exactly one
       # declaration anywhere in the corpus (`examples/banking/bluebook/
       # deposit_accounts.bluebook:353`, aggregate-level) and no property
       # anywhere in this file ever checked it, and no `FEATURE_COVERAGE`
@@ -9,7 +9,7 @@ module Hecks
       # stress_domains/corrections` gives it its first real coverage; see
       # that domain's own NOTES.md for what it found (an entity-level
       # `corrects` crashes Ruby at dispatch outright, and Rust's own
-      # generated code has NO admissibility check for it AT ALL — neither
+      # generated code has no admissibility check for it at all — neither
       # engine can be compared on the untested combination this property
       # was written to watch, which is itself the headline finding).
       module Corrections
@@ -19,32 +19,37 @@ module Hecks
         # entities`, below, is the same recursive walk `SequenceGenerator::
         # Catalog#each_entity_chain` already uses, for the identical reason:
         # `Aggregate#entities`/`Entity#entities` nest, ADR 0026, S17). For
-        # every such command, every event THIS history actually recorded
+        # every such command, every event this history actually recorded
         # under one of the command's own `emits` names must have an event
         # named by the command's own `corrects` target — same aggregate-
-        # qualified name, same id — appearing STRICTLY EARLIER in the same
+        # qualified name, same id — appearing strictly earlier in the same
         # history.
         #
         # `history[:events]` is already in occurrence order (`Replay.call`'s
         # own `runtime.events`, appended as each step dispatches) — "earlier"
         # is therefore "earlier in this array," no timestamp comparison
         # needed, and no per-step attribution back to which command produced
-        # which event is needed either: an event's own declared NAME already
+        # which event is needed either: an event's own declared name already
         # identifies the one command in its aggregate that can produce it
         # (`AggregateBuilder::Sealing#seal_correction_targets`'s own
         # `emitted_by` hash reads the identical fact, one level shallower).
         #
-        # WHY THIS CANNOT BE `GUARANTEED_BY_CONSTRUCTION` THE WAY THE
-        # AGGREGATE-LEVEL CASE ALMOST IS: `CommandRules::Admissibility#
+        # Why this cannot be `GUARANTEED_BY_CONSTRUCTION` the way the
+        # aggregate-level case almost is: `CommandRules::Admissibility#
         # enforce_correction_target` (the dispatch-time check) and
         # `AggregateBuilder::Sealing#seal_correction_targets` (the build-time
-        # check) both exist ONLY for an aggregate-level `corrects` —
+        # check) both exist only for an aggregate-level `corrects` —
         # `EntityInterpreter#step_enforce_givens` never calls the former at
         # all, and the latter walks only `@commands` (the aggregate's own
         # top-level list), never `@entities`. An entity-level `corrects`
-        # mutation is invisible to BOTH doors today — this property is the
+        # mutation is invisible to both doors today — this property is the
         # only thing anywhere, on either engine, that would ever catch one
         # going wrong.
+        #
+        # @param history [Hash] a replayed history as returned by `Replay.call`
+        # @return [true, String] true if every event emitted by a `corrects`-bearing
+        #   command has a matching, strictly earlier corrected event in the same
+        #   history; otherwise a message listing every unmatched correction
         def corrections_reference_an_emitted_event(history)
           violations = []
 
@@ -72,6 +77,17 @@ module Hecks
           violations.empty? || violations.uniq.join("; ")
         end
 
+        # Finds every occurrence of `produced_event_name`, on `aggregate_key`, with no
+        # matching `corrected_event` for the same id appearing earlier in `events`.
+        #
+        # @param events [Array<Hash>] `history[:events]`, in occurrence order
+        # @param aggregate_key [String] `"domain::AggregateName"` the events belong to
+        # @param produced_event_name [String] name of the event a `corrects` mutation's
+        #   command emits
+        # @param corrected_event [String] name of the event the mutation claims to correct
+        # @param command_name [String] the command's own `hecks_name`, for the message
+        # @return [Array<String>] one message per occurrence with no matching earlier
+        #   corrected event; empty when every occurrence is matched
         def unmatched_corrections(events, aggregate_key, produced_event_name, corrected_event, command_name)
           own_events = events.each_with_index.select do |event, _index|
             event[:name] == produced_event_name && event[:aggregate] == aggregate_key
@@ -90,6 +106,15 @@ module Hecks
           end
         end
 
+        # Yields every command declared on `owner`, then recurses into each of its
+        # entities to yield theirs too, at any nesting depth (ADR 0026, S17).
+        #
+        # @param owner [Bluebook::Aggregate, Bluebook::Entity] the aggregate or entity
+        #   whose own commands, and whose entities' commands, to walk
+        # @yield [command] once per declared command, aggregate-level or nested
+        # @yieldparam command [Bluebook::Command] a command declared on `owner` or one
+        #   of its entities
+        # @return [void]
         def each_command_including_entities(owner, &block)
           owner.commands.each(&block)
           owner.entities.each { |entity| each_command_including_entities(entity, &block) }