hecks 1.3.0 → 1.5.0

data/lib/hecks/fuzzing/properties.rb

@@ -14,32 +14,36 @@ require_relative "properties/outbox"
 
 module Hecks
   module Fuzzing
-    # Declared properties, checked over a REPLAYED history — the other
+    # Declared properties, checked over a replayed history — the other
     # half of property-based testing the fuzzer was missing: it already
     # generates and (with bin/fuzz's shrinker) minimizes, but checked
     # nothing beyond "did the interpreter crash" and "did the replay
     # match the claim." A property here is a fact that should hold of
-    # ANY history a valid domain produces, independent of which seed
+    # any history a valid domain produces, independent of which seed
     # produced it.
     #
+    # ## Property shape
+    #
     # Each property is `name => ->(history) { true/false, or a message
     # string naming what broke }` — a truthy return (including `true`)
-    # is a pass; a String return is a failure, and the string IS the
+    # is a pass; a String return is a failure, and the string is the
     # finding. `history` is Replay's return shape.
     #
-    # EVERY PROPERTY DECLARES THE LANGUAGE FEATURE IT COVERS, in
+    # ## Feature coverage
+    #
+    # Every property declares the language feature it covers, in
     # `FEATURE_COVERAGE` below — a "Construct#attribute" pair spelled
     # exactly as `Bluebook::MetaValidator.grammar_registry` names it,
-    # the SAME meta-domain that judges every real bluebook (see that
+    # the same meta-domain that judges every real bluebook (see that
     # module's own header: "the language IS the source"). That is the
     # link this file exists to make real: a construct the language
     # declares is a fact `spec/meta_domain_coverage_spec.rb` can
     # enumerate on its own, without anyone re-typing the list here —
     # so a new attribute added to `language/bluebook/*.bluebook` shows
-    # up in that spec as UNCLAIMED the moment it lands, not whenever
+    # up in that spec as unclaimed the moment it lands, not whenever
     # someone remembers to go looking. Claiming a feature here is a
     # deliberate act (a real property, checked at least once failing
-    # AND once passing — `spec/fuzzing/properties_spec.rb`'s own
+    # and once passing — `spec/fuzzing/properties_spec.rb`'s own
     # discipline) or an explicit, reasoned exemption in that same
     # spec — never silence.
     module Properties
@@ -64,11 +68,11 @@ module Hecks
 
       module_function
 
-      # WHICH LANGUAGE FEATURE EACH PROPERTY IS ANSWERABLE FOR. Not
+      # Which language feature each property is answerable for. Not
       # exhaustive of everything a property's body happens to touch —
       # `Command#attributes`, say, is exercised by nearly every property
-      # here without being what any of them was WRITTEN to guard — but
-      # exhaustive of the feature that would go UNCHECKED if this
+      # here without being what any of them was written to guard — but
+      # exhaustive of the feature that would go unchecked if this
       # property did not exist. That is the question the coverage gate
       # actually asks.
       FEATURE_COVERAGE = {
@@ -80,17 +84,17 @@ module Hecks
         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/Dispatch#with_spec are NOT claimable
-        # feature names — META_DOMAIN_ALL_FEATURES only walks ONE level
+        # Dispatch#command_name/Dispatch#with_spec are not claimable
+        # feature names — META_DOMAIN_ALL_FEATURES only walks one level
         # of entity nesting (`agg.entities.flat_map`, meta_domain_
-        # coverage_spec.rb), and Dispatch sits TWO deep (ProcessManager
+        # coverage_spec.rb), and Dispatch sits two deep (ProcessManager
         # -> Handler -> Dispatch), so those strings never exist there
         # to claim — a pre-existing meta-domain coverage-generation gap,
         # found here (their old META_DOMAIN_KNOWN_GAPS entries were
         # themselves already-orphaned strings no completeness check ever
         # verified, since KNOWN_GAPS has no "never lets a gap rot" check
         # the way FEATURE_COVERAGE/GUARANTEED_BY_CONSTRUCTION both do).
-        # This property still closes the REAL behavior both would have
+        # This property still closes the real behavior both would have
         # named — a Dispatch's own command_name/with_spec are exactly
         # what dispatch_args resolves and this property checks — the
         # grammar just has no feature string for either one.
@@ -102,58 +106,78 @@ module Hecks
         aggregation_matches_recompute:                    %w[ReadModel#count ReadModel#median_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?`
+        # A runtime door, not a grammar construct — `Dispatcher#dry_run?`
         # is something an application asks of a booted domain, not a
         # word a bluebook can declare, so there is no feature string
         # for it to claim. Listed (empty) rather than omitted so the
         # discipline this table states — every property names what it
         # is answerable for — has no silent exception.
         dry_runs_leave_no_trace:                          [],
-        # ANOTHER RUNTIME DOOR, NOT A GRAMMAR CONSTRUCT — same reasoning
+        # Another runtime door, not a grammar construct — same reasoning
         # as dry_runs_leave_no_trace right above: `Runtime::Outbox` is
         # something a persistence adapter provides underneath a booted
         # domain, never a word a bluebook declares.
-        outbox_rows_match_reactions:                      []
+        outbox_rows_match_reactions:                      [],
+        # **The `corrects` mutation's own target** — this property reads
+        # `command.mutations.select { op == :corrects }` and asks whether
+        # the event each one names was ever actually emitted, so the
+        # feature it answers for is the mutation list, the same one
+        # `mutations_match_recompute` reads for a different question.
+        # (Not `Command#references`: that field is the dangling-reference
+        # question no property asks yet, and it stays a named gap.)
+        corrections_reference_an_emitted_event:           %w[Command#mutations],
+        # No feature string exists for what this one reads. It depends on
+        # an argument's own `relationship` (which reference-typed argument
+        # points at which aggregate) — but `Argument` is a value object,
+        # and the meta-domain walk enumerates aggregate and entity fields
+        # only, so no `Argument#…` name is claimable. The declaration side
+        # it shares with queries, `authorize …, tenant:`, is
+        # `Query#options`, already claimed by `authorize_scopes_or_refuses`;
+        # claiming it twice would say this property covers a query
+        # question it never asks. Listed (empty) rather than omitted, the
+        # same discipline the two runtime doors above keep.
+        commands_respect_tenant_scope:                    []
       }.freeze
 
-      # FEATURES A REPLAY PROPERTY COULD NEVER CATCH VIOLATED, because the
-      # RUNTIME'S OWN CONSTRUCTION makes the violation impossible to
+      # Features a replay property could never catch violated, because the
+      # runtime's own construction makes the violation impossible to
       # produce in the first place — not "untested," but unfalsifiable by
       # a history, the same class of guarantee this codebase already
-      # states for identity ("NOTHING IS MINTED" — command_interpreter.rb's
-      # own header) and now generalises. Each entry names the ONE place in
+      # states for identity ("nothing is minted" — command_interpreter.rb's
+      # own header) and now generalises. Each entry names the one place in
       # the runtime that makes it true, universally, for every domain and
       # every adapter — never per-domain logic a future domain could
       # accidentally route around.
       #
-      # THE BLUEBOOK/HECKSAGON BOUNDARY IS WHY THIS WORKS: a bluebook
-      # declares SHAPE (attribute types, patterns, closed sets, VO
+      # The bluebook/hecksagon boundary is why this works: a bluebook
+      # declares shape (attribute types, patterns, closed sets, VO
       # invariants — see docs/decisions/0009), and shape is enforced by
-      # ONE coercion door every domain's every attribute passes through
+      # one coercion door every domain's every attribute passes through
       # (`Runtime::Value.build`, via value/coercion.rb + value/admission.rb)
       # regardless of which hecksagon later binds the aggregate to Memory,
       # Postgres, or anything else. A value that violated its own declared
-      # pattern, invariant, or closed set could never be COERCED, so it
-      # could never be STORED, so it could never appear in a replay's own
+      # pattern, invariant, or closed set could never be coerced, so it
+      # could never be stored, so it could never appear in a replay's own
       # `:instances` to be caught violating it. Checking for it after the
       # fact would be watching for something the construction path already
       # made impossible.
       #
-      # NOT a place to hide a real gap — a feature belongs here only once
-      # the SPECIFIC enforcing code path has been read and confirmed, the
+      # Not a place to hide a real gap — a feature belongs here only once
+      # the specific enforcing code path has been read and confirmed, the
       # same discipline `spec/fuzzing/meta_domain_coverage_spec.rb` demands
-      # of `KNOWN_GAPS` in the other direction. `Entity#identified_by` was
-      # checked FOR this category once before and found NOT to qualify —
-      # `command_interpreter.rb`'s `AlreadyExists` refusal was given to
-      # every CREATING AGGREGATE command uniformly, and MutationApplier
-      # (command_interpreter/mutation_applier.rb) had no matching check on
-      # an entity's own append. It does now: #check_entity_collision runs
-      # unconditionally on both branches an entity identity can arrive by
-      # (caller-supplied, or composite — the two the auto-mint branch
-      # doesn't cover), the same way command_interpreter#hydrate's own
-      # check is unconditional for every creating aggregate command. Real,
-      # confirmed live before the fix (SafeDepositBox's Visit/KeyIssuance —
-      # see spec/runtime/safe_deposit_box_spec.rb).
+      # of `KNOWN_GAPS` in the other direction. `Entity#identified_by`
+      # illustrates the discipline: `command_interpreter.rb`'s
+      # `AlreadyExists` refusal covers every creating aggregate command
+      # uniformly, but nothing else on its own covers an entity's own
+      # append — so this entry names the path that actually does,
+      # `MutationApplier#check_entity_collision` (command_interpreter/
+      # mutation_applier.rb), which runs unconditionally on both branches
+      # an entity identity can arrive by (caller-supplied, or composite —
+      # the two the auto-mint branch doesn't cover), the same way
+      # `command_interpreter#hydrate`'s own check is unconditional for
+      # every creating aggregate command. The collision this closes is
+      # real, not hypothetical: SafeDepositBox's Visit/KeyIssuance entities
+      # reproduce it, confirmed by spec/runtime/safe_deposit_box_spec.rb.
       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 " \
@@ -171,13 +195,18 @@ module Hecks
                                      "(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"    => "MutationApplier#check_entity_collision (command_interpreter/mutation_applier.rb) " \
-                                     "checks Array(current) against every part of the entity's own identity before an " \
-                                     "append can land, on both branches identity arrives by (caller-supplied, or " \
-                                     "composite) — the same AlreadyExists refusal Aggregate#identified_by gets above, " \
-                                     "one level down. Auto-minted 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)",
+        "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 " \
@@ -198,7 +227,7 @@ module Hecks
         # ValueObject), so this reads "Member#pairs", not "Member#shape" —
         # the free-text, un-parsed spelling a standalone root once needed
         # no longer exists at all, an entity's own element is never
-        # serialized as text. "ValueObject#members" is the SAME fact
+        # serialized as text. "ValueObject#members" is the same fact
         # "ValueObject#rows" already counts, seen from the other side — a
         # value object cannot declare admitted rows without a members list
         # to hold them, and vice versa.
@@ -206,9 +235,13 @@ module Hecks
         "Member#pairs"            => "one level into ValueObject#rows — same door"
       }.freeze
 
-      # THE STANDARD BATTERY, run over one replayed history — everything
-      # except determinism, which needs to replay TWICE itself and so
-      # takes the steps directly rather than a single history.
+      # Runs the standard property battery over one replayed history —
+      # everything except determinism, which needs to replay twice itself
+      # and so takes the steps directly rather than a single history.
+      #
+      # @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),

data/lib/hecks/fuzzing/qa_settings.rb

@@ -0,0 +1,164 @@
+require "yaml"
+
+module Hecks
+  module Fuzzing
+    # Reads `qa/settings.yml` — the hecks_qa practice's own dials, now
+    # data in a file rather than Ruby constant literals. The why of each
+    # dial (what it does, who reads it) stays exactly one place: the
+    # comments on `QualityControlDials` in `qa/bluebook/quality_control.
+    # bluebook`, which now sources every value from an instance of this
+    # class instead of writing it inline. This class is only the loading
+    # and the validation — no dial policy lives here.
+    #
+    # **Fails loud, not quiet** — the whole practice's own opening line
+    # ("the enemy is the quiet divergence") applies to its own settings
+    # file too: a missing key, an extra key nothing recognises, or a
+    # value of the wrong shape all raise immediately, at load time
+    # (which is bluebook-load time, i.e. `Hecks.boot`), naming exactly
+    # what's wrong — never a `nil` dial silently reaching a script that
+    # assumes a number.
+    #
+    # **Plain data in, frozen data out**. `.load` parses the YAML with
+    # `Psych.safe_load_file` (no custom tags, no arbitrary Ruby objects)
+    # and hands back an instance whose accessors are the exact values a
+    # human wrote in the file — a `Hash`/`Array` for the nested dials,
+    # never a second, richer wrapper type nothing else in this practice
+    # expects.
+    class QaSettings
+      # One entry per dial this class knows about: the accessor name
+      # (matching `qa/settings.yml`'s own key, and `QualityControlDials`'
+      # constant name snake_cased) mapped to the class (or classes) a
+      # valid value must be an instance of. `TrueClass`/`FalseClass`
+      # both name a boolean dial — Ruby has no single class both `true`
+      # and `false` share. `Numeric` admits both an Integer and a Float
+      # for a fraction dial (`0` and `0.0` are both a human plausibly
+      # types for "off").
+      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 real file, always** — resolved off this file's own `__dir__`
+      # (lib/hecks/fuzzing/), never off the caller's. `QualityControlDials`
+      # is defined inside `qa/bluebook/quality_control.bluebook`, and that
+      # exact directory gets copied to a tmpdir for every isolated/replayed
+      # boot (`Hecks::Fuzzing::IsolatedBoot#copy_dereferencing` copies only
+      # `qa/bluebook`'s own contents, never its parent `qa/`) — a path
+      # resolved from the bluebook's own `__dir__` would silently point at
+      # a copy with no `settings.yml` beside it at all. `qa/settings.yml`
+      # is read-only, human-edited data with no lifecycle (see this class's
+      # own header) — there is no isolation reason to ever read a copy of
+      # it, real boot or fuzzed one, so every caller gets the one real file
+      # by default. `qa_settings_spec.rb` passes its own fixture paths
+      # explicitly instead, the same way every other test in this practice
+      # that needs a non-default dial passes one in rather than mutating
+      # global state.
+      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
+
+      # `left:`/`right:` name adapters `IsolatedBoot` case-matches by
+      # symbol (`case adapter when :memory ...`), and YAML has no way to
+      # spell a bare Ruby Symbol as a mapping value — only
+      # `symbolize_names:` turns a key into one. So `adapter_parity_
+      # pairs` is the one dial that needs a coercion step after the
+      # type check above, rather than every dial growing one.
+      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