hecks 3.5.0 → 3.6.0

data/lib/hecks/fuzzing/replay/observation.rb

@@ -0,0 +1,60 @@
+module Hecks
+  module Fuzzing
+    module Replay
+      # What a session reads off the runtime: the final history and the pre-dispatch snapshot a
+      # `for_each` fan-out is checked against. Mixed into `Session`.
+      module Observation
+        private
+
+        def observed_history
+          { instances: Replay.snapshot_instances(@runtime), events: events, refusals: @refusals,
+            reactions: @runtime.reactions, sagas: @runtime.sagas, saga_instances: saga_instances,
+            queries: @queries, dry_runs: @dry_runs, dry_run_traces: @dry_run_traces,
+            fan_outs: @fan_outs, guard_checks: @guard_checks,
+            mutation_traces: @mutation_traces, outbox_traces: @outbox_traces,
+            saga_dispatches: @runtime.saga_dispatches, policy_dispatches: @runtime.policy_dispatches,
+            bluebook: @runtime.registry.bluebooks.values.first,
+            bluebooks: @runtime.registry.bluebooks.dup }
+        end
+
+        def events
+          @runtime.events.map { |event| { name: event.name, aggregate: event.aggregate, id: event.id, payload: event.payload } }
+        end
+
+        # The live process-manager store, materialised to inert data (`{ pm_name =>
+        # { correlation => { state:, memory: } } }`), captured here because the
+        # runtime goes out of scope with the boot and the Memory rebind leaves no
+        # real saga store for Properties.sagas_rehydrate_cleanly to read otherwise.
+        def saga_instances
+          @runtime.registry.saga_instances.each_with_object({}) do |(pm_name, conversations), out|
+            out[pm_name] = conversations.each_with_object({}) do |(correlation, instance), rows|
+              rows[correlation] = { state: instance[:state], memory: Runtime::Value.materialize(instance[:memory]) }
+            end
+          end
+        end
+
+        # Every `[domain, aggregate_name]` a `for_each` policy could query, resolved
+        # once from every loaded bluebook's own fanning-out policies. Empty when no
+        # domain declares `for_each`, so the snapshot taken before each dispatch costs
+        # nothing until one does.
+        def fan_out_targets
+          @runtime.registry.bluebooks.each_with_object({}) do |(domain, bluebook), targets|
+            bluebook.policies.select(&:fans_out?).each do |policy|
+              query_domain, aggregate_name, = policy.for_each_route(domain)
+              targets[[query_domain, aggregate_name]] ||= @runtime.registry.bluebook(query_domain)&.aggregate(aggregate_name)
+            end
+          end
+        end
+
+        def fan_out_snapshot
+          @fan_out_targets.each_with_object({}) do |((fdomain, faggregate_name), aggregate), snap|
+            next unless aggregate
+
+            snap[[fdomain, faggregate_name]] =
+              @runtime.registry.repository(fdomain, aggregate).all.to_h { |record| [record.id, record.state.dup] }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/replay/read_only_steps.rb

@@ -0,0 +1,84 @@
+module Hecks
+  module Fuzzing
+    module Replay
+      # The steps a session answers without dispatching a command: declared and ad hoc queries,
+      # and dry runs. Mixed into `Session`, whose recorded lists and runtime they use.
+      module ReadOnlySteps
+        private
+
+        def ask(question, args)
+          return ask_filter(question) if question.is_a?(Hash)
+
+          ask_declared(question, args)
+        end
+
+        # A `{aggregate:, field:, op:, value:}` Hash "query" step — the ad hoc
+        # filter kernel/cli.rs's own object-form step also reads, bypassing the
+        # declared bluebook query DSL. Answered via `Ports::Query::InMemory` directly.
+        def ask_filter(question)
+          rows = Replay.run_filter(@runtime, question)
+          @queries << { query: question, rows: rows, instances_at: Replay.snapshot_instances(@runtime) }
+        rescue StandardError => e
+          @refusals << { verb: Replay.filter_label(question), error: e.message, kind: Replay.refusal_kind(e) }
+        end
+
+        # Each engine runs in its own begin/rescue, never a shared one — a shared
+        # rescue would hide "one engine refused, the other didn't" (the real
+        # divergence this differential oracle exists to catch) behind a plain refusal.
+        #
+        # Read-model asks (bare domain form, no "::") have no reference twin at all —
+        # never attempted, not "attempted and agreed."
+        def ask_declared(question, args)
+          native_rows, native_error = native_answer(question, args)
+          has_reference = question.include?("::")
+          reference_rows, reference_error = reference_answer(question, args) if has_reference
+
+          entry = { query: question, args: args, rows: native_rows, instances_at: Replay.snapshot_instances(@runtime) }
+          entry[:error] = native_error.message if native_error
+          add_reference(entry, reference_rows, reference_error) if has_reference
+          @queries << entry
+
+          @refusals << { verb: question, error: native_error.message, kind: Replay.refusal_kind(native_error) } if native_error
+        end
+
+        def add_reference(entry, reference_rows, reference_error)
+          entry[:reference_rows]  = reference_rows
+          entry[:reference_error] = reference_error.message if reference_error
+        end
+
+        def native_answer(question, args)
+          [@runtime.query(question, **args), nil]
+        rescue *Runtime::DOMAIN_REFUSALS, Bluebook::Expression::EvaluationError => e
+          [nil, e]
+        end
+
+        def reference_answer(question, args)
+          [@runtime.reference_query(question, **args), nil]
+        rescue *Runtime::DOMAIN_REFUSALS, Bluebook::Expression::EvaluationError => e
+          [nil, e]
+        end
+
+        # `dry_run` is evaluated hypothetically and recorded, never a refusal.
+        # `dry_runs`' shape (`{verb:, ok:, error?:}`) is compared against
+        # `kernel/cli.rs`'s own answer; `dry_run_traces` is Ruby-only oracle data.
+        def dry_run(step, hypothetical, args)
+          before = state_snapshot
+          entry  = { verb: hypothetical }
+          attempt_dry_run(entry, step, hypothetical, args)
+          after = state_snapshot
+          @dry_runs << entry
+          @dry_run_traces << entry.merge(before: before, after: after)
+        end
+
+        def state_snapshot = { instances: Replay.snapshot_instances(@runtime), events: @runtime.events.size }
+
+        def attempt_dry_run(entry, step, hypothetical, args)
+          Replay.as_step_caller(step) { @runtime.dry_run?(hypothetical, **args) }
+          entry[:ok] = true
+        rescue *Runtime::DOMAIN_REFUSALS, Bluebook::Expression::EvaluationError => e
+          entry.merge!(ok: false, error: e.message)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/replay/session.rb

@@ -0,0 +1,151 @@
+require_relative "observation"
+require_relative "read_only_steps"
+
+module Hecks
+  module Fuzzing
+    module Replay
+      # One replay in flight: plays steps against a booted runtime and accumulates the
+      # observable history, including the oracle traces `Properties` check.
+      #
+      # The oracle snapshots taken around each dispatch are timed relative to it; the order in
+      # which `take_marks` and `dispatch` run them is part of what they mean.
+      class Session
+        include ReadOnlySteps
+        include Observation
+
+        # What is read before a dispatch so its own effects can be sliced out afterwards.
+        #
+        # `outbox_ids` is a set of delivery_ids, not a size, because `runtime.outbox.rows`
+        # concatenates several stores' own arrays, so a plain "grew from N to M" tail slice
+        # could miss or misattribute rows once more than one repository has an outbox.
+        Marks = Struct.new(:reaction, :saga, :outbox_ids, :fan_out_snapshot, :guard_check, :mutation_trace)
+
+        # @param runtime [Hecks::Runtime] a freshly booted runtime
+        def initialize(runtime)
+          @runtime         = runtime
+          @refusals        = []
+          @queries         = []
+          @dry_runs        = []
+          @dry_run_traces  = []
+          @fan_outs        = []
+          @guard_checks    = []
+          @mutation_traces = []
+          @outbox_traces   = []
+          @fan_out_targets = fan_out_targets
+        end
+
+        # Plays every step in order.
+        #
+        # @param steps [Array<Hash>] the step list
+        # @return [Session] self
+        def play(steps)
+          steps.each { |step| play_step(step) }
+          self
+        end
+
+        # The history of everything played so far, with the booted chapter beside it so
+        # properties.rb's lifecycle/saga checks have the declared IR. `bluebook:` (singular) is
+        # the first-loaded chapter; `bluebooks:` (plural) is the full domain-name-keyed map, for
+        # a property that must resolve a verb back to its declaring bluebook.
+        #
+        # `runtime` is still live here, so SelfConsistency runs against the same registry a
+        # second boot couldn't reuse.
+        #
+        # @param self_consistency [Boolean] also run SelfConsistency.check
+        # @return [Hash] instances, events, refusals, reactions, sagas, queries, oracle traces
+        def history(self_consistency: false)
+          history = observed_history
+          history[:self_consistency] = SelfConsistency.check(@runtime, history) if self_consistency
+          history
+        end
+
+        private
+
+        def play_step(step)
+          step = step.transform_keys(&:to_s)
+          args = (step["args"] || {}).transform_keys(&:to_sym)
+
+          if (question = step["query"])
+            ask(question, args)
+          elsif (hypothetical = step["dry_run"])
+            dry_run(step, hypothetical, args)
+          else
+            dispatch(step, args)
+          end
+        end
+
+        def dispatch(step, args)
+          marks = take_marks(step, args)
+
+          # `role:`/`actor_id:` are optional per-step keys; a step with neither
+          # dispatches bare, as every existing corpus step always has. Binds the
+          # ambient caller for exactly this one dispatch, then unbinds, so
+          # back-to-back steps with different (or no) `role:` never leak into each other.
+          result = Replay.as_step_caller(step) { @runtime.dispatch_flat(step["verb"], args) }
+          record_effects(step, result, marks)
+        rescue *Runtime::DOMAIN_REFUSALS, Bluebook::Expression::EvaluationError => e
+          record_refusal(step, e, marks&.guard_check)
+        end
+
+        # Taken before dispatch, so this step's own reactions, sagas and outbox rows can be
+        # sliced out after and matched against an independent recomputation. The fan-out
+        # snapshot is what a `for_each` query would have seen: `deliver_for_each` runs its
+        # query synchronously inside this same dispatch, so reading the live repository
+        # after would see what the fan-out's own dispatched commands already mutated, not what
+        # it matched. The guard is replayed read-only before the real dispatch can mutate
+        # anything a cross-aggregate given dereferences, and the entity element a mutation
+        # step's args address is snapshotted so it can be diffed against its post-dispatch state.
+        def take_marks(step, args)
+          Marks.new(@runtime.reactions.size, @runtime.sagas.size, @runtime.outbox.rows.map(&:delivery_id),
+                    fan_out_snapshot, GuardCheck.build(@runtime, step["verb"], args),
+                    MutationTrace.build(@runtime, step["verb"], args))
+        end
+
+        def record_effects(step, result, marks)
+          @fan_outs.concat(Replay.fan_out_findings(@runtime, marks.fan_out_snapshot, result.events,
+                                                   @runtime.reactions[marks.reaction..]))
+          record_outbox(step, marks)
+          @guard_checks << marks.guard_check.merge(actual_refused: false, actual_kind: nil) if marks.guard_check
+          record_mutation(marks.mutation_trace) if marks.mutation_trace
+        end
+
+        # Every outbox row this step's own dispatch newly wrote, across every
+        # bound repository including any a reaction cascade touched, paired with
+        # the reaction/saga rows that same dispatch produced. Skipped when empty.
+        def record_outbox(step, marks)
+          new_rows = outbox_rows_since(marks)
+          return if new_rows.empty?
+
+          @outbox_traces << { verb: step["verb"], rows: new_rows.map(&:to_h),
+                              reactions: @runtime.reactions[marks.reaction..].dup,
+                              sagas: @runtime.sagas[marks.saga..].dup }
+        end
+
+        def outbox_rows_since(marks)
+          @runtime.outbox.rows.reject { |row| marks.outbox_ids.include?(row.delivery_id) }
+        end
+
+        # After — only on success; a refused step mutated nothing, so there is no "after" to
+        # compare (and `MutationTrace.build` already skipped anything with no mutations to
+        # trace in the first place).
+        def record_mutation(mutation_trace)
+          @mutation_traces << mutation_trace.merge(after: MutationTrace.read_after(@runtime, mutation_trace))
+        end
+
+        # `kind:` is the raised class, not derived from the message: several
+        # refusal templates share the same wording, so only the class tells a
+        # guard refusal apart from the rest.
+        #
+        # Only a refusal raised by the guard itself counts for the guard check. A refusal from a
+        # stage before or after enforce_givens can share TypeMismatch's class, so
+        # anything outside the two guard classes is left out — inconclusive, not a pass.
+        def record_refusal(step, error, guard_check)
+          @refusals << { verb: step["verb"], error: error.message, kind: Replay.refusal_kind(error) }
+          return unless guard_check && GUARD_REFUSAL_CLASSES.include?(error.class)
+
+          @guard_checks << guard_check.merge(actual_refused: true, actual_kind: error.class.name)
+        end
+      end
+    end
+  end
+end