hecks 2.6.0 → 2.8.0

data/lib/hecks/fuzzing/nondeterministic.rb

@@ -1,79 +0,0 @@
-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,253 +0,0 @@
-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
-    # 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
-    # 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
-    # path a Postgres-bound domain's users really hit).
-    #
-    # `examples/directory` is why this exists at all: the one domain in
-    # this corpus with a real `compute`/`rekey` translation edge
-    # (docs/prds/02-fuzzer-real-adapters.md's own "What shipped" section
-    # names it directly), which no existing fuzz/replay/property check has
-    # ever been able to exercise against real PostgresEra SQL — every one
-    # of them boots through `IsolatedBoot`, and until `adapter:
-    # :postgres_era` existed (isolated_boot.rb's own header), that meant
-    # Memory, unconditionally, no matter what `directory.world` itself
-    # declares.
-    #
-    # ## 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.
-    #
-    # ## `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
-    # (`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
-    # on-disk file, no server, no disposable database/schema lifecycle to
-    # own), so that pairing folds straight into the ordinary per-seed
-    # loop instead of needing a deferred wave of its own the way
-    # PostgresEra does.
-    #
-    # ## `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
-    # `IsolatedBoot#rebind_to_postgres_era!` itself refuses to let a
-    # caller skip); every other adapter ignores both, same as `Replay.
-    # call`/`IsolatedBoot.call` already do for their own `adapter:`.
-    module PersistenceParity
-      module_function
-
-      # 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
-      # 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
-      # only) — there is no second engine's own known-gap catalogue to
-      # 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
-      # `Hash#==`/`Array#==` compares plain, JSON-shaped data on both
-      # 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)
-
-        divergences = []
-        divergences.concat(diff_instances(left_result, right_result, left, right))
-        divergences.concat(diff_events(left_result, right_result, left, right))
-        divergences.concat(diff_refusals(left_result, right_result, left, right))
-        divergences.concat(diff_queries(left_result, right_result, left, right))
-        divergences.concat(diff_sagas(left_result, right_result, left, right))
-        divergences.concat(diff_reactions(left_result, right_result, left, right))
-        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])
-        return [] if l == r
-
-        [{ 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])
-        return [] if l == r
-
-        [{ 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] } }
-        end
-        l = normalize.call(left_result[:refusals])
-        r = normalize.call(right_result[:refusals])
-        return [] if l == r
-
-        [{ field: "refusals", left => l, right => r }]
-      end
-
-      # 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| 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
-
-        [{ 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])
-        return [] if l == r
-
-        [{ 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])
-        return [] if l == r
-
-        [{ field: "reactions", left => l, right => r }]
-      end
-    end
-  end
-end

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

@@ -1,125 +0,0 @@
-module Hecks
-  module Fuzzing
-    module Properties
-      # 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`
-      # claim either — confirmed absent before this file existed. `qa/
-      # 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
-      # engine can be compared on the untested combination this property
-      # was written to watch, which is itself the headline finding).
-      module Corrections
-        # Every event named by a `corrects` mutation, on any command a
-        # booted history's own bluebooks declare — aggregate-level, or
-        # nested inside an entity at any depth (`each_command_including_
-        # 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
-        # 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
-        # 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
-        # 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#
-        # 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` —
-        # `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
-        # 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 = []
-
-          (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?
-
-                corrects_mutations.each do |mutation|
-                  corrected_event = mutation.target.to_s
-
-                  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
-              end
-            end
-          end
-
-          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
-          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
-
-            "#{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 " \
-              "earlier in this history"
-          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) }
-        end
-      end
-    end
-  end
-end