hecks 1.0.2 → 1.1.0

data/lib/hecks/fqn.rb

@@ -6,22 +6,30 @@ module Hecks
   class Fqn
     class Invalid < ArgumentError; end
 
-    attr_reader :realm, :domain, :version, :aggregate, :verb
+    attr_reader :realm, :domain, :version, :aggregate, :verb, :kind
 
     def self.command(realm:, domain:, aggregate:, command:, version: nil)
       new(realm: realm, domain: domain, version: version, aggregate: aggregate, verb: command, kind: :command)
     end
 
-    def self.query(realm:, domain:, aggregate: nil, query:, version: nil)
+    def self.query(realm:, domain:, query:, aggregate: nil, version: nil)
       new(realm: realm, domain: domain, version: version, aggregate: aggregate, verb: query, kind: :query)
     end
 
+    # ONE ORDER-DEPENDENT PARSE PIPELINE: split -> shape-validate -> dispatch
+    # on segment count -> split domain/version -> classify kind -> cross-
+    # field validate -> construct. Each step consumes locals (segments, verb,
+    # kind) the step before it derived; splitting would mean threading all of
+    # them back out as parameters/returns between new methods, for no
+    # readability gain over reading the pipeline top to bottom once.
+    # rubocop:disable-next Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
     def self.parse(text)
       head, separator, verb = text.to_s.rpartition(".")
       raise Invalid, "FQN must be Realm::Domain::Aggregate.verb — got #{text.inspect}" if separator.empty?
 
       segments = head.split("::", -1)
-      raise Invalid, "FQN must be Realm::Domain::Aggregate.verb — got #{text.inspect}" unless [1, 2, 3].include?(segments.length) && segments.none?(&:empty?) && !verb.empty?
+      valid_fqn = [1, 2, 3].include?(segments.length) && segments.none?(&:empty?) && !verb.empty?
+      raise Invalid, "FQN must be Realm::Domain::Aggregate.verb — got #{text.inspect}" unless valid_fqn
 
       realm, domain_spec, aggregate = case segments.length
                                       when 3 then segments
@@ -48,7 +56,7 @@ module Hecks
     def self.command_name?(name) = /\A[A-Z][A-Za-z0-9]*\z/.match?(name.to_s)
     def self.query_name?(name)   = /\A[a-z][a-z0-9_]*\z/.match?(name.to_s)
 
-    def initialize(realm:, domain:, version: nil, aggregate:, verb:, kind:)
+    def initialize(realm:, domain:, aggregate:, verb:, kind:, version: nil)
       @realm     = realm && segment(realm, "realm")
       @domain    = segment(domain, "domain")
       @version   = version && segment(version, "version")
@@ -62,7 +70,6 @@ module Hecks
 
     def command? = @kind == :command
     def query?   = @kind == :query
-    def kind     = @kind
 
     def to_s
       domain = @version ? "#{@domain}@#{@version}" : @domain
@@ -77,16 +84,21 @@ module Hecks
 
     def self.split_domain(value)
       domain, version, extra = value.to_s.split("@", 3)
-      raise Invalid,
-            "FQN domain version is malformed: #{value.inspect}" if domain.empty? || extra || (value.include?("@") && version.to_s.empty?)
+      if domain.empty? || extra || (value.include?("@") && version.to_s.empty?)
+        raise Invalid,
+              "FQN domain version is malformed: #{value.inspect}"
+      end
 
       [domain, version]
     end
+    private_class_method :split_domain
 
     def segment(value, label)
       text = value.to_s
-      raise Invalid,
-            "FQN #{label} cannot be empty or contain a separator" if text.empty? || text.include?("::") || text.include?(".") || text.include?("@")
+      if text.empty? || text.include?("::") || text.include?(".") || text.include?("@")
+        raise Invalid,
+              "FQN #{label} cannot be empty or contain a separator"
+      end
 
       text
     end

data/lib/hecks/fuzzing/bounded_exhaustive_expressions.rb

@@ -101,7 +101,7 @@ module Hecks
       # actually bound to.
       ARRAY_ELEMENT_TYPE = { "arr_num" => :numeric, "arr_str" => :string }.freeze
 
-      BLOCK_PARAM = "el"
+      BLOCK_PARAM = "el".freeze
 
       MAX_DEPTH = 3
 
@@ -217,7 +217,9 @@ module Hecks
         when :string   then string_productions(depth)
         when :boolean  then boolean_productions(depth)
         when :array    then array_productions(depth)
-        when :nil_type then [] # no recursive producer of nil in this grammar — Find's "not found" is a runtime OUTCOME, not a distinct construct to render as source text
+        # no recursive producer of nil in this grammar — Find's "not found" is a
+        # runtime OUTCOME, not a distinct construct to render as source text
+        when :nil_type then []
         else raise ArgumentError, "no production rule for type #{type.inspect}"
         end
       end
@@ -291,8 +293,12 @@ module Hecks
       def resolver_boolean_leaves(depth)
         leaves(:boolean) +
           resolver_numeric_leaves(depth).flat_map { |n| ["#{n}.positive?", "#{n}.negative?", "#{n}.zero?"] } +
-          bounded(:string, depth).flat_map { |s| ["#{s}.present?", "#{s}.blank?", "#{s}.match?(/a/)", "#{s}.start_with?(\"a\")", "#{s}.end_with?(\"a\")"] } +
-          (sample(numeric_array_productions(depth)) + sample(string_array_productions(depth)) + bounded(:array, depth)).map { |x| "#{x}.empty?" } +
+          bounded(:string, depth).flat_map do |s|
+            ["#{s}.present?", "#{s}.blank?", "#{s}.match?(/a/)", "#{s}.start_with?(\"a\")", "#{s}.end_with?(\"a\")"]
+          end +
+          (sample(numeric_array_productions(depth)) + sample(string_array_productions(depth)) + bounded(:array, depth)).map do |x|
+            "#{x}.empty?"
+          end +
           sample(block_predicate_productions(depth))
       end
 
@@ -386,6 +392,15 @@ module Hecks
       # typed at its own top level (`Evaluator.truthy?`), so this is also
       # the set `all_predicates` (below) draws its top-level cases from
       # directly.
+      # One declarative table of boolean productions, not several
+      # unrelated things bolted together — each `+`-joined term is a
+      # distinct grammar rule, and several carry their own comment
+      # explaining a specific inclusion/exclusion choice (the
+      # `resolver_numeric_leaves`-not-`num` note above, `arr_num`'s non-
+      # empty twin, etc). Extracting terms into separate methods would
+      # need `sub`/`num`/`str` threaded into each as parameters and
+      # would separate every rule from the comment justifying it.
+      # rubocop:disable-next Metrics/AbcSize
       def boolean_productions(depth)
         sub = bounded(:boolean, depth - 1)
         num = bounded(:numeric, depth - 1)
@@ -404,8 +419,11 @@ module Hecks
           # documents (`"0 + 0.positive?"` would parse as `0 + (0
           # .positive?)`, not `(0 + 0).positive?`).
           resolver_numeric_leaves(depth - 1).flat_map { |n| ["#{n}.positive?", "#{n}.negative?", "#{n}.zero?"] } +
-          (str + sample(numeric_array_productions(depth - 1)) + sample(string_array_productions(depth - 1)) + bounded(:array, depth - 1))
-          .map { |x| "#{x}.empty?" } +
+          (str + sample(numeric_array_productions(depth - 1)) + sample(string_array_productions(depth - 1)) + bounded(:array,
+                                                                                                                      depth - 1))
+          .map do |x|
+            "#{x}.empty?"
+          end +
           str.map { |s| "#{s}.match?(/a/)" } +
           str.flat_map { |s| ["#{s}.present?", "#{s}.blank?"] } +
           str.flat_map { |s| ["#{s}.start_with?(\"a\")", "#{s}.end_with?(\"a\")"] } +
@@ -461,8 +479,12 @@ module Hecks
       def include_productions(depth)
         str = bounded(:string, depth)
         pairs(str).map { |haystack, needle| "#{haystack}.include?(#{needle})" } +
-          sample(numeric_array_productions(depth)).product(bounded(:numeric, depth)).map { |arr, needle| "#{arr}.include?(#{needle})" } +
-          sample(string_array_productions(depth)).product(bounded(:string, depth)).map { |arr, needle| "#{arr}.include?(#{needle})" }
+          sample(numeric_array_productions(depth)).product(bounded(:numeric, depth)).map do |arr, needle|
+            "#{arr}.include?(#{needle})"
+          end +
+          sample(string_array_productions(depth)).product(bounded(:string, depth)).map do |arr, needle|
+            "#{arr}.include?(#{needle})"
+          end
       end
 
       # SAMPLED, NOT A FULL CROSS PRODUCT — a full `list.product(list)`

data/lib/hecks/fuzzing/invalid_value_generator.rb

@@ -57,7 +57,6 @@ module Hecks
         when :numeral_string    then random.rand(1..1000).to_s
         when :array_for_scalar  then [random.rand(1..10), random.rand(1..10)]
         when :boolean_for_string then random.rand(2).zero?
-        else nil
         end
       end
 

data/lib/hecks/fuzzing/isolated_boot.rb

@@ -103,7 +103,15 @@ module Hecks
             FileUtils.mkdir_p(target)
           else
             FileUtils.mkdir_p(File.dirname(target))
-            FileUtils.cp(path, target)
+            begin
+              FileUtils.cp(path, target)
+            rescue Errno::ENOENT
+              # A transient sibling (an adapter's atomic-write `.tmp.<pid>`
+              # file, caught mid-rename by the glob above) can vanish
+              # between listing and copy — under parallel_r-spec two
+              # workers share the real example tree. A file that no longer
+              # exists was never part of the state this copy needs.
+            end
           end
         end
       end
@@ -160,8 +168,8 @@ module Hecks
       # process-unique schema name (`SecureRandom.hex` is already
       # `require`d here for exactly that day) — flagged, not solved,
       # since nothing today calls this from more than one thread.
-      FUZZ_POSTGRES_DATABASE = "hecks_fuzz"
-      FUZZ_POSTGRES_SCHEMA   = "hecks_fuzz"
+      FUZZ_POSTGRES_DATABASE = "hecks_fuzz".freeze
+      FUZZ_POSTGRES_SCHEMA   = "hecks_fuzz".freeze
 
       def rebind_to_postgres!(copy)
         require "pg"
@@ -182,7 +190,7 @@ module Hecks
           next if names.empty?
 
           world_path = File.join(File.dirname(hecksagon_path), "hecks_fuzz_postgres.world")
-          File.write(world_path, names.map { |name|
+          File.write(world_path, names.map do |name|
             <<~WORLD
               Hecks.world "#{name}" do
                 persisted_by("Postgres") do
@@ -191,7 +199,7 @@ module Hecks
                 end
               end
             WORLD
-          }.join("\n"))
+          end.join("\n"))
         end
 
         # Any PRE-EXISTING `.world` this copy shipped with (a real
@@ -277,7 +285,7 @@ module Hecks
       # never wires is simply unread, not broken.
       def rewrite_bindings!(copy, adapter_name)
         Dir.glob(File.join(copy, "**", "*.hecksagon")).each do |path|
-          lines = File.readlines(path).reject { |line| line.match?(/\bprojected_by\s*\(?\s*"/) }
+          lines = File.readlines(path).grep_v(/\bprojected_by\s*\(?\s*"/)
           File.write(path, lines.join.gsub(/persisted_by\s*\(?\s*"[^"]+"\s*\)?/, "persisted_by(\"#{adapter_name}\")"))
         end
       end

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

@@ -0,0 +1,264 @@
+module Hecks
+  module Fuzzing
+    module Properties
+      # Dispatch-binding and mutation-recomputation properties: a saga/
+      # policy dispatch is bound to the value its own with_spec names, and a
+      # command's append/remove/multiply/clamp mutations land on the same
+      # after-state an independent recomputation of the SAME rule produces.
+
+      # Holds dispatch_binding_fidelity and mutations_match_recompute, plus
+      # the independently-written re-derivations (#resolve_dispatch_binding,
+      # #resolve_trigger_binding, #recompute_append/#remove/#multiply/#clamp)
+      # each checks the real dispatch/mutation against.
+      module DispatchAndMutations
+        # Closes Handler#dispatches and — the same shape, one construct
+        # over — Policy#with_spec (Dispatch#command_name/Dispatch#with_spec
+        # are not claimable feature strings at all — see FEATURE_COVERAGE's
+        # own comment on this entry). history[:saga_dispatches]/[:policy_dispatches]
+        # (Registry#saga_dispatch_log/#policy_dispatch_log — additive,
+        # Ruby-only, NEVER touching saga_log/reaction_log, the byte-for-
+        # byte shape spec/rust_conformance_spec.rb holds Rust to) each
+        # carry the RAW inputs a dispatch's own args were resolved from,
+        # captured live at the moment the resolution actually ran — a
+        # saga's own memory keeps changing across a run, so re-deriving
+        # from history[:saga_instances]'s FINAL memory (the only other
+        # place it would be visible) would grade the wrong moment,
+        # lifecycle_guard_and_given_violations_are_refused's own false
+        # positive one item earlier, in a different shape.
+        #
+        # #resolve_dispatch_binding/#resolve_trigger_binding are SEPARATE,
+        # independently-written re-derivations of SagaInterpreter#
+        # dispatch_args/PolicyInterpreter#trigger_args's own resolution —
+        # never calling either method again, which would only ever agree
+        # with itself. Exactly the class of bug this closes: "a wrong
+        # argument binding on a fan-out dispatch that produces a perfectly
+        # normal-looking log entry (`delivered: true`) and would only ever
+        # surface as a downstream assertion failure, if it surfaces at
+        # all" — PR #325's own defect class, one level over.
+        #
+        # Real targets: Settlement (mixed literal/correlation-head/event-
+        # payload/memory-fallback bindings across three legs, plus a
+        # compensation leg that deliberately omits `reference:`, a field
+        # the forward Credit leg carries), ExternalSettlement, Onboarding
+        # (no compensation leg, by design — nothing to check there beyond
+        # the forward leg's own event-payload binding).
+        def dispatch_binding_fidelity(history)
+          saga_offenders = history.fetch(:saga_dispatches, []).filter_map do |entry|
+            expected = resolve_dispatch_binding(entry)
+            next if expected == entry[:args]
+
+            "#{entry[:process_manager]}##{entry[:instance]} dispatching #{entry[:dispatch]} on #{entry[:on]} — " \
+              "bound #{entry[:args].inspect}, but independently re-deriving with_spec's own resolution gives " \
+              "#{expected.inspect}"
+          end
+
+          policy_offenders = history.fetch(:policy_dispatches, []).filter_map do |entry|
+            expected = resolve_trigger_binding(entry)
+            next if expected == entry[:args]
+
+            "#{entry[:policy]} on #{entry[:on]} — bound #{entry[:args].inspect}, but independently re-deriving " \
+              "with_spec's own resolution gives #{expected.inspect}"
+          end
+
+          offenders = saga_offenders + policy_offenders
+          offenders.empty? || offenders.join("; ")
+        end
+
+        # SagaInterpreter#dispatch_args's own 4-branch resolution,
+        # reproduced independently: a literal, the correlation key itself,
+        # the CURRENT triggering event's own payload, or — the fallback —
+        # the saga's own carried memory (seeded from the STARTING event's
+        # payload, at begin_saga).
+        def resolve_dispatch_binding(entry)
+          entry[:with_spec].to_h do |key, value|
+            resolved = if !value.is_a?(Symbol) then value
+                       elsif value == entry[:correlation_head] then entry[:instance]
+                       elsif entry[:event_payload].key?(value) then entry[:event_payload][value]
+                       else entry[:memory][value]
+                       end
+            [key.to_sym, Runtime::Value.materialize(resolved)]
+          end
+        end
+
+        # PolicyInterpreter#trigger_args's own 2-branch resolution — a
+        # policy holds no correlation and no memory, so `payload` (the
+        # triggering event's own payload, already merged with a fan-out
+        # row's id when there is one) is the WHOLE source.
+        def resolve_trigger_binding(entry)
+          entry[:with_spec].to_h do |key, value|
+            resolved = value.is_a?(Symbol) ? entry[:payload][value] : value
+            [key.to_sym, Runtime::Value.materialize(resolved)]
+          end
+        end
+
+        # Closes Command#mutations — the last of the five, and the
+        # largest: no real corpus entity anywhere uses `append`/`remove`/
+        # `multiply`/`clamp` (every real aggregate-owned mutation is
+        # aggregate-scoped — Account.Credit's :ledger, LogVisit's
+        # :visits); the only entity-owned use of these four ops in the
+        # whole repository is spec/fixtures/entity_list_mutations, now a
+        # real, bootable, Memory-default domain (no .hecksagon needed at
+        # all — a domain with none boots every aggregate against Memory
+        # by construction, confirmed live) rather than the raw-Kernel.
+        # load-only fixture it was.
+        #
+        # `history[:mutation_traces]` (Replay's own bounded, additive
+        # extension — see #build_mutation_trace's own comment) carries a
+        # per-step before/after snapshot of the ENTITY ELEMENT an
+        # entity-dispatched command's own mutations acted on, materialized
+        # to plain data, plus the step's own raw args — the delta
+        # `aggregation_matches_recompute` never had to ask for, because
+        # count/median are pure functions of FINAL state and a mutation
+        # is not (the same "captured live, not re-derived from final
+        # state" lesson item 8's own saga_dispatch_log already learned).
+        #
+        # #recompute_append/#recompute_remove/#recompute_multiply/
+        # #recompute_clamp are SEPARATE, independently-written
+        # reproductions of MutationApplier#appended/#removed and
+        # CommandRules::Arithmetic#multiply/#clamp — never calling either
+        # again, which would only ever agree with itself. `:set`/
+        # `:increment`/`:decrement` are out of scope on purpose (the four
+        # "vendored, not yet upstream" ops this item exists for); a
+        # command mixing them with a recomputable op still gets the
+        # recomputable one checked.
+        #
+        # `:unrecomputable` (never compared, never a finding) covers the
+        # generator's own deliberate arg-malforming (`StepBuilder#malform`)
+        # landing a non-Numeric amount/non-2-element bounds where
+        # multiply/clamp need one — the SAME shape `guard_check`'s own
+        # AbsentArgument false positive taught: a step whose raw material
+        # doesn't fit the op's own contract is inconclusive, not a claimed
+        # mismatch.
+        RECOMPUTABLE_MUTATION_OPS = %i[append remove multiply clamp].freeze
+
+        def mutations_match_recompute(history)
+          bluebooks = history.fetch(:bluebooks)
+
+          offenders = history.fetch(:mutation_traces, []).flat_map do |entry|
+            next [] unless entry[:after]
+
+            command = command_for_verb(bluebooks, entry[:verb])
+            next [] unless command
+
+            command.mutations.select { |m| RECOMPUTABLE_MUTATION_OPS.include?(m.op) }.filter_map do |mutation|
+              expected = recompute_mutation(mutation, entry[:before][mutation.target], entry[:args], entry[:before])
+              next if expected == :unrecomputable
+
+              actual = entry[:after][mutation.target]
+              next if symbolize_deep(expected) == symbolize_deep(actual)
+
+              "#{entry[:verb]} — #{mutation.op} on #{mutation.target} — recomputing independently gives " \
+                "#{expected.inspect}, but the real dispatch left #{actual.inspect}"
+            end
+          end
+
+          offenders.empty? || offenders.join("; ")
+        end
+
+        def recompute_mutation(mutation, current, args, before_scope)
+          case mutation.op
+          when :append   then recompute_append(current, mutation.source, before_scope, args)
+          when :remove   then recompute_remove(current, mutation.source, args)
+          when :multiply then recompute_multiply(current, resolve_mutation_source(mutation.source, args))
+          when :clamp    then recompute_clamp(current, mutation.source)
+          end
+        end
+
+        # `MutationApplier#appended`'s own value-object branch (never the
+        # entity_element branch — see #build_mutation_trace's own comment
+        # on why an entity-dispatched command's own mutations never reach
+        # it), reproduced: the field map resolved the SAME two-tier way
+        # (`MutationApplier#resolve_append_source` — a caller-supplied
+        # arg, or the entity's own current field), then appended.
+        def recompute_append(current, source_map, before_scope, args)
+          fields = source_map.transform_values { |source| resolve_mutation_append_field(source, before_scope, args) }
+          Array(current) + [symbolize_deep(fields)]
+        end
+
+        def resolve_mutation_append_field(source, before_scope, args)
+          return source unless source.is_a?(Symbol)
+          return args[source] if args.key?(source)
+
+          before_scope[source]
+        end
+
+        # `MutationApplier#removed`'s own value-equality match, reproduced.
+        def recompute_remove(current, source, args)
+          target = symbolize_deep(resolve_mutation_source(source, args))
+          Array(current).reject { |element| symbolize_deep(element) == target }
+        end
+
+        # `CommandRules::Arithmetic#multiply`'s own two branches,
+        # reproduced on plain materialized data instead of a real Value:
+        # a single-numeric-field Hash (the VO-typed case — ListCount, one
+        # Integer field) scales that field ; a bare Numeric scales itself.
+        # `current ||= 0` — the SAME phantom-field fallback #multiply
+        # itself already gives (unaffected by this session's #clamp fix,
+        # since #multiply never needed one).
+        def recompute_multiply(current, amount)
+          return :unrecomputable unless amount.is_a?(Numeric)
+
+          current ||= 0
+          if current.is_a?(Hash)
+            field = current.keys.find { |f| current[f].is_a?(Numeric) }
+            return :unrecomputable unless field
+
+            current.merge(field => current[field] * amount)
+          elsif current.is_a?(Numeric)
+            current * amount
+          else
+            :unrecomputable
+          end
+        end
+
+        # `CommandRules::Arithmetic#clamp`'s own two branches, reproduced
+        # the same way #recompute_multiply is — including THIS SESSION'S
+        # OWN `current ||= 0` fix (command_rules/arithmetic.rb), the one
+        # arithmetic op that didn't have it until now. `mutation.source`
+        # is always a literal `[min, max]`, never an argument reference
+        # (MutationApplier's own comment on why `resolve_source` is
+        # skipped for clamp) — so nothing here reads `args` for it at all.
+        def recompute_clamp(current, bounds)
+          return :unrecomputable unless bounds.is_a?(Array) && bounds.size == 2
+
+          min, max = bounds
+          current ||= 0
+          if current.is_a?(Hash)
+            field = current.keys.find { |f| current[f].is_a?(Numeric) }
+            return :unrecomputable unless field
+
+            current.merge(field => current[field].clamp(min, max))
+          elsif current.is_a?(Numeric)
+            current.clamp(min, max)
+          else
+            :unrecomputable
+          end
+        end
+
+        # `CommandRules::Arithmetic#resolve_source`, reproduced: a
+        # mutation's source is either the NAME OF AN ARGUMENT or a
+        # LITERAL, told apart by type.
+        def resolve_mutation_source(source, args)
+          source.is_a?(Symbol) ? args[source] : source
+        end
+
+        # A generated step's own `args` arrive with STRING keys on every
+        # nested Hash (the wire/JSON shape `spec/corpus/*.json` already
+        # uses) while `history[:mutation_traces]`' own materialized
+        # before/after state carries SYMBOL keys throughout (Runtime::
+        # Value.materialize's own convention) — two hashes holding the
+        # identical fact compare UNEQUAL by Ruby's own `Hash#==` unless
+        # both sides are normalized the same way first. Recursive, since
+        # an appended/removed element can itself nest a value object
+        # (RemoveTag's own `Tag` argument, `{"key"=>..., "value"=>...}`).
+        def symbolize_deep(value)
+          case value
+          when Hash  then value.to_h { |key, val| [key.to_sym, symbolize_deep(val)] }
+          when Array then value.map { |val| symbolize_deep(val) }
+          else value
+          end
+        end
+      end
+    end
+  end
+end