hecks 2.9.0 → 3.0.1

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

@@ -0,0 +1,175 @@
+module Hecks
+  module Fuzzing
+    module Properties
+      # Properties that check a query's answer against an independent recomputation.
+      module Querying
+        # Differential oracle: each replayed ask is answered natively and by the reference
+        # interpreter, and the two must agree.
+        #
+        # Refusal is read by key presence (`:error` / `:reference_error`), not truthiness;
+        # one side refusing while the other answers is a divergence. Read-model asks
+        # (no "::" in the verb) have no reference twin and are skipped.
+        #
+        # @param history [Hash] a replayed history as returned by `Replay.call`
+        # @return [true, String] true, or a message naming each disagreeing query
+        def query_answers_match_reference(history)
+          offenders = history.fetch(:queries).filter_map do |asked|
+            next unless asked[:query].is_a?(String) && asked[:query].include?("::")
+
+            native_refused    = asked.key?(:error)
+            reference_refused = asked.key?(:reference_error)
+
+            if native_refused != reference_refused
+              next "#{asked[:query]} #{asked[:args].inspect} — native " \
+                   "#{native_refused ? "refused (#{asked[:error]})" : 'answered'}, " \
+                   "but the reference interpreter #{reference_refused ? "refused (#{asked[:reference_error]})" : 'answered'} — " \
+                   "a refusal-shaped divergence, not just a differing row set"
+            end
+
+            next if native_refused
+            next if asked[:rows] == asked[:reference_rows]
+
+            "#{asked[:query]} #{asked[:args].inspect} answered #{asked[:rows].inspect} " \
+              "natively but #{asked[:reference_rows].inspect} through the reference interpreter"
+          end
+
+          offenders.empty? || offenders.join("; ")
+        end
+
+        # Recomputes order/offset/limit from `history[:instances]` and compares it with the
+        # real answer of every paged query (`order_by` with `offset` or `limit`).
+        #
+        # Ordering reuses `Ports::Query::Ordering.apply` so "in order" cannot drift from the
+        # interpreter; only the offset-then-limit slice is restated. Comparing the interpreter's
+        # native and reference paths instead could share one bug.
+        #
+        # Kept as one method: the steps run once, in order, and share every intermediate.
+        # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+        #
+        # @param history [Hash] a replayed history as returned by `Replay.call`
+        # @return [true, String] true, or a message naming each mismatching query
+        def paging_offset_partitions_correctly(history)
+          bluebooks = history.fetch(:bluebooks)
+
+          offenders = history.fetch(:queries).filter_map do |asked|
+            next if asked[:error] || !asked[:query].is_a?(String) || !asked[:query].include?("::")
+
+            declared = query_for_verb(bluebooks, asked[:query])
+            next unless declared&.order_by && (declared.offset || declared.limit)
+
+            domain, aggregate_name, = Naming.split_verb(asked[:query])
+            aggregate = bluebooks[domain]&.aggregate(aggregate_name)
+            args = normalize_query_args(aggregate, declared, asked[:args] || {})
+            rows = query_eligible_rows(asked.fetch(:instances_at), domain, aggregate_name, declared.wheres, args,
+                                       bluebooks: bluebooks)
+            ordered = Ports::Query::Ordering.apply(
+              rows, declared.order_by, declared.null_semantics, identity: ->(row) { row[:id].to_s }
+            ) { |row| Ports::Query::InMemory.comparable(QuerySpecification::FieldPath.dig(row, declared.order_by.field)) }
+
+            skipped  = declared.offset ? ordered.drop(resolve_paging_value(declared.offset.value, args).to_i) : ordered
+            expected = declared.limit ? skipped.first(resolve_paging_value(declared.limit.value, args).to_i) : skipped
+            actual   = asked[:rows]
+            next if actual == expected
+
+            "#{asked[:query]} #{args.inspect} answered #{actual.inspect}, but independently recomputing " \
+              "order/offset/limit from #{rows.length} eligible row(s) gives #{expected.inspect}"
+          end
+
+          offenders.empty? || offenders.join("; ")
+        end
+
+        # Real dispatch normalizes a query's own declared arguments
+        # (`QueryInterpreter#normalize_args`) before ever evaluating a where clause,
+        # filling a composite argument's own declared defaults along the way
+        # (`Value.for_attribute` -> `Value.build`). The language's own ambiguous-
+        # comparison guard (`refuse_ambiguous_comparison!`) rules out comparing most
+        # multi-field value objects whole, but a single-attribute one (still eligible,
+        # since it is never ambiguous) can still arrive with that one field omitted —
+        # recomputing eligibility against the raw fuzzed args instead of this normalized
+        # copy would then disagree with real dispatch — the same false-divergence shape
+        # `build_guard_check` guards against for the guard check. `Runtime::QueryInterpreter.
+        # new(nil)` is safe: `normalize_args` never reads the registry it would otherwise need.
+        def normalize_query_args(aggregate, declared, args)
+          return args unless aggregate
+
+          Runtime::QueryInterpreter.new(nil).send(:normalize_args, aggregate, declared, args)
+        rescue StandardError
+          args
+        end
+
+        # Resolves the declared Query for a replayed verb.
+        #
+        # Entity-level queries (dotted query path) return nil: they are not one aggregate's
+        # own rows, which #query_eligible_rows assumes.
+        #
+        # @param bluebooks [Hash{String => Bluebook::Chapter}] every loaded domain
+        # @param verb [String] `"Domain::Aggregate.Query"`
+        # @return [Bluebook::Query, nil]
+        def query_for_verb(bluebooks, verb)
+          domain, aggregate_name, query_path = Naming.split_verb(verb)
+          return nil unless query_path && !query_path.include?(".")
+
+          bluebook  = bluebooks[domain]
+          aggregate = bluebook&.aggregate(aggregate_name)
+          aggregate&.query(query_path)
+        end
+
+        # Recomputes which of an aggregate's own stored rows a query's `wheres` admit.
+        #
+        # Rows get `id:` merged in because Ordering.apply's `identity:` and the real answer
+        # both use it. `bluebooks:` is needed only to resolve a `/` hop clause, whose head
+        # names a declared reference; without it the clause would be dug as a local path.
+        #
+        # @param instances [Hash{String => Hash}] `history[:instances]` or an `:instances_at`
+        #   snapshot
+        # @param wheres [Array<QuerySpecification::Common::WhereClause>] clauses every row
+        #   must satisfy
+        # @param args [Hash] the query's call args, for clauses whose value is a Symbol
+        # @return [Array<Hash>] each admitted row's state, merged with its `id:`
+        def query_eligible_rows(instances, domain, aggregate_name, wheres, args, bluebooks: {})
+          aggregate = bluebooks[domain]&.aggregate(aggregate_name)
+          prefix = "#{domain}::#{aggregate_name}#"
+          instances.filter_map do |key, state|
+            next unless key.start_with?(prefix)
+
+            row = state.merge(id: key.split("#").last)
+            next unless wheres.all? do |clause|
+              resolved = resolve_hop_clause(instances, domain, aggregate, clause, args, bluebooks)
+              held = Ports::Query::InMemory.comparable(QuerySpecification::FieldPath.dig(row, resolved.field))
+              Ports::Query::InMemory.holds?(resolved, held, args)
+            end
+
+            row
+          end
+        end
+
+        # Resolves one hop of a `/`-chained clause into a local `in` clause over the target's ids.
+        #
+        # Restates `Runtime::ReferenceHop#fold` over the replay snapshot, so the property never
+        # checks the runtime against its own code path. A clause with no resolvable hop head
+        # is returned unchanged.
+        #
+        # @param aggregate [Bluebook::Aggregate, nil] nil skips hop resolution
+        # @return [QuerySpecification::Common::WhereClause] `clause`, or the `in` clause
+        def resolve_hop_clause(instances, domain, aggregate, clause, args, bluebooks)
+          return clause unless aggregate && QuerySpecification::HopPath.hop_head?(clause.field, aggregate.attributes)
+
+          hop, rest = QuerySpecification::HopPath.next_hop(clause.field, aggregate.attributes)
+          target = hop.target
+          return clause unless target
+
+          inner = QuerySpecification::Common::WhereClause.new(field: rest, op: clause.op, value: clause.value)
+          ids   = query_eligible_rows(instances, domain, target.hecks_name, [inner], args, bluebooks: bluebooks)
+                  .map { |row| row[:id].to_s }.uniq
+
+          QuerySpecification::Common::WhereClause.new(field: hop.attribute.name, op: "in", value: ids)
+        end
+
+        # Resolves a declared limit/offset: a literal, or a Symbol naming a call arg.
+        def resolve_paging_value(value, args)
+          value.is_a?(Symbol) ? args[value] : value
+        end
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/properties.rb

@@ -0,0 +1,162 @@
+require "json"
+require_relative "../bluebook/model_check"
+require_relative "../bluebook/meta_validator"
+require_relative "../ports/query/in_memory"
+require_relative "../query_specification/field_path"
+require_relative "../runtime/value"
+require_relative "properties/lifecycle_and_replay"
+require_relative "properties/querying"
+require_relative "properties/guards"
+require_relative "properties/dispatch_and_mutations"
+require_relative "properties/invariants_and_aggregation"
+require_relative "properties/corrections"
+require_relative "properties/outbox"
+
+module Hecks
+  module Fuzzing
+    # Declared properties, checked over a replayed history: each maps a name
+    # to `->(history) { true, or a message string naming what broke }`.
+    module Properties
+      # Grouped by responsibility across properties/*.rb; `extend`ed so each
+      # stays reachable as `Properties.foo(history)`, matching `module_function` below.
+      extend LifecycleAndReplay
+      extend Querying
+      extend Guards
+      extend DispatchAndMutations
+      extend DryRuns
+      extend InvariantsAndAggregation
+      extend Corrections
+      extend Outbox
+
+      module_function
+
+      # 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],
+        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],
+        # 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
+
+      # Runs the standard property battery over one replayed history — all but
+      # determinism, which replays twice itself and so is checked separately.
+      #
+      # @param history [Hash] a replayed history, as returned by `Fuzzing::Replay.call`
+      # @return [Hash{Symbol => true, String}] each property name mapped to `true`
+      #   (passed) or a message string naming what broke
+      def check(history)
+        { lifecycle_values_are_declared:                    lifecycle_values_are_declared(history),
+          saga_advances_follow_declared_handlers:           saga_advances_follow_declared_handlers(history),
+          query_answers_match_reference:                    query_answers_match_reference(history),
+          guard_refusals_are_declared:                      guard_refusals_are_declared(history),
+          sagas_rehydrate_cleanly:                          sagas_rehydrate_cleanly(history),
+          fanout_dispatches_once_per_matching_row:          fanout_dispatches_once_per_matching_row(history),
+          aggregation_matches_recompute:                    aggregation_matches_recompute(history),
+          stored_records_satisfy_declared_invariants:       stored_records_satisfy_declared_invariants(history),
+          group_by_matches_recompute:                       group_by_matches_recompute(history),
+          paging_offset_partitions_correctly:               paging_offset_partitions_correctly(history),
+          lifecycle_guard_and_given_violations_are_refused: lifecycle_guard_and_given_violations_are_refused(history),
+          authorize_scopes_or_refuses:                      authorize_scopes_or_refuses(history),
+          commands_respect_tenant_scope:                    commands_respect_tenant_scope(history),
+          dispatch_binding_fidelity:                        dispatch_binding_fidelity(history),
+          mutations_match_recompute:                        mutations_match_recompute(history),
+          dry_runs_leave_no_trace:                          dry_runs_leave_no_trace(history),
+          corrections_reference_an_emitted_event:           corrections_reference_an_emitted_event(history),
+          outbox_rows_match_reactions:                      outbox_rows_match_reactions(history) }
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/qa_settings.rb

@@ -0,0 +1,123 @@
+require "yaml"
+
+module Hecks
+  module Fuzzing
+    # Loads and validates `qa/settings.yml`, the hecks_qa dials.
+    #
+    # Fails loud: a missing key, unknown key or wrong-typed value raises at load time.
+    # The meaning of each dial is documented on `QualityControlDials` in the bluebook.
+    class QaSettings
+      # Accessor name to the class (or classes) a valid value must be an instance of.
+      # Booleans list both TrueClass and FalseClass; Numeric admits `0` as well as `0.0`.
+      EXPECTED_TYPES = {
+        cadence_seconds:              Integer,
+        pr_cap_per_day:               Integer,
+        widening_tiers:               Array,
+        sweep_max_parallel:           Integer,
+        liveness_fallback_seconds:    Integer,
+        draft_only:                   [TrueClass, FalseClass],
+        auto_merge:                   [TrueClass, FalseClass],
+        branch_prefix:                String,
+        adversarial_fraction:         Numeric,
+        guided_generation:            [TrueClass, FalseClass],
+        corpus_splice_probability:    Numeric,
+        favor_rare_verbs:             Integer,
+        self_consistency_checks:      [TrueClass, FalseClass],
+        shrink_budget:                Integer,
+        yield_weight_seconds:         Integer,
+        yield_decay_percent:          Integer,
+        rotation_stale_floor_seconds: Integer,
+        persistence_parity_seed_cap:  Integer,
+        concurrency_seed_cap:         Integer,
+        adapter_parity_pairs:         Hash,
+        modes:                        Hash,
+        role_draw_probability:        Numeric,
+        dry_run_fraction:             Numeric,
+        generated_domains_per_tick:   Integer,
+        generated_domains_rust:       [TrueClass, FalseClass],
+        generated_domain_seeds:       Integer,
+        structural_refusal_boundary:  Array
+      }.freeze
+
+      attr_reader(*EXPECTED_TYPES.keys)
+
+      # The one real file, resolved from this file's `__dir__` rather than the bluebook's: the
+      # chapter ships in `lib/hecks/quality_control/`, the settings stay in `qa/`, and IsolatedBoot
+      # copies only `qa/bluebook`, so a bluebook-relative path would miss it.
+      DEFAULT_PATH = File.expand_path("../../../qa/settings.yml", __dir__)
+
+      class << self
+        # Loads and validates `qa/settings.yml` (or `path`), returning a frozen instance.
+        #
+        # @param path [String] path to the YAML settings file; defaults to `DEFAULT_PATH`
+        # @return [Hecks::Fuzzing::QaSettings] the validated, frozen settings
+        # @raise [ArgumentError] if `path` does not exist, is not valid YAML, is not a
+        #   YAML mapping at the top level, is missing a required key, declares an
+        #   unknown key, or gives a value the wrong type for its dial
+        def load(path = DEFAULT_PATH)
+          raise ArgumentError, "qa settings file not found: #{path}" unless File.file?(path)
+
+          raw = begin
+            YAML.safe_load_file(path, symbolize_names: true)
+          rescue Psych::SyntaxError => e
+            raise ArgumentError, "#{path} is not valid YAML: #{e.message}"
+          end
+          raise ArgumentError, "#{path} must be a YAML mapping at the top level, got #{raw.class}" unless raw.is_a?(Hash)
+
+          new(raw, path)
+        end
+      end
+
+      # @param raw [Hash] parsed YAML settings keyed by symbol, one entry per dial in
+      #   `EXPECTED_TYPES`
+      # @param path [String] path to the settings file, used only in error messages
+      # @raise [ArgumentError] if `raw` is missing a required key, declares an unknown
+      #   key, or gives a value the wrong type for its dial
+      def initialize(raw, path)
+        missing = EXPECTED_TYPES.keys - raw.keys
+        raise ArgumentError, "#{path} is missing #{missing.sort.join(', ')}" if missing.any?
+
+        extra = raw.keys - EXPECTED_TYPES.keys
+        if extra.any?
+          raise ArgumentError,
+                "#{path} declares unknown key(s) #{extra.sort.join(', ')} — " \
+                "Hecks::Fuzzing::QaSettings::EXPECTED_TYPES doesn't recognise them"
+        end
+
+        EXPECTED_TYPES.each do |key, expected|
+          value = raw.fetch(key)
+          expected_classes = Array(expected)
+          unless expected_classes.any? { |klass| value.is_a?(klass) }
+            raise ArgumentError,
+                  "#{path}: #{key} must be a #{expected_classes.map(&:name).join(' or ')}, " \
+                  "got #{value.class} (#{value.inspect})"
+          end
+
+          instance_variable_set(:"@#{key}", value)
+        end
+
+        symbolize_adapter_parity_pairs!(path)
+        freeze_values!
+      end
+
+      private
+
+      # YAML cannot spell a Symbol value, and IsolatedBoot case-matches adapters by symbol.
+      def symbolize_adapter_parity_pairs!(path)
+        @adapter_parity_pairs = @adapter_parity_pairs.to_h do |mode, pair|
+          unless pair.is_a?(Hash) && pair.key?(:left) && pair.key?(:right)
+            raise ArgumentError,
+                  "#{path}: adapter_parity_pairs.#{mode} must have both left and right, got #{pair.inspect}"
+          end
+
+          [mode, { left: pair[:left].to_sym, right: pair[:right].to_sym }]
+        end
+      end
+
+      def freeze_values!
+        EXPECTED_TYPES.each_key { |key| instance_variable_get(:"@#{key}").freeze }
+        freeze
+      end
+    end
+  end
+end