hecks 1.2.0 → 1.4.0

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

@@ -0,0 +1,142 @@
+require_relative "../../bluebook/expression/evaluator"
+
+module Hecks
+  module Fuzzing
+    module Properties
+      # The transactional outbox's own contract (`Runtime::Outbox`, that
+      # file's own header), held to the history a replay actually produced
+      # rather than trusted. Two facts, each independently checkable from
+      # `history[:outbox_traces]` (`Replay#call`'s own before/after
+      # capture, one entry per step whose dispatch enqueued at least one
+      # row):
+      #
+      #   1. "delivery is inline by default" — a row this replay's own
+      #      dispatch enqueued must not still be `pending`/`claimed` once
+      #      that same call returns (nothing here ever simulates a
+      #      crash), and must not be `failed` either — `deliver_row`'s
+      #      own rescue only reaches `failed` for a genuine defect in the
+      #      relay's own consumer resolution (a row naming a policy/
+      #      process_manager `run_consumer`'s own independent registry
+      #      lookup cannot find — `WiringError`), never an ordinary
+      #      domain refusal (`PolicyInterpreter#deliver`/`SagaInterpreter#
+      #      advance` both rescue those themselves, recording `delivered:
+      #      false` on the reaction/saga log and letting `run_consumer`
+      #      return normally). Both checked for every row, `saga:` and
+      #      `policy:` alike.
+      #
+      #   2. A `policy:` row specifically — `PolicyInterpreter#deliver`
+      #      returns `nil` (no `reaction_log` entry appended at all)
+      #      exactly when its own `where` (or, for a fan-out policy, the
+      #      same `where`, gating the whole `for_each`) does not hold;
+      #      every other outcome (delivered, refused, a defect,
+      #      reaction-depth-reached) is still a non-nil record `#react`
+      #      appends. So a `delivered` policy row with no matching
+      #      `reaction_log` entry is legitimate only when that policy's
+      #      own `where`, independently re-evaluated here against the
+      #      row's own recorded event, genuinely does not hold. A
+      #      `for_each` policy's own fan-out correctness (how many rows
+      #      it should have dispatched to) is `fanout_dispatches_once_
+      #      per_matching_row`'s job, not this one's.
+      #
+      # A `saga:` row has no equivalent second check, deliberately — this
+      # was the first shape this property shipped with, and it was wrong,
+      # caught live against `examples/banking` before this comment
+      # existed: `Fanout.sagas`' own `listens?` (starts_on/ends_on/
+      # handler_for matching the event name alone) says nothing about
+      # whether a correlation resolves or a live instance exists, and
+      # `begin_saga`/`end_saga` (saga_interpreter.rb) both have silent,
+      # perfectly ordinary no-op paths that append nothing to `saga_log`
+      # — `begin_saga` when an instance under that correlation already
+      # exists, `end_saga` when no live instance exists to end (an
+      # `AccountOpened` fired by opening an account directly, bypassing
+      # the onboarding flow whose `ends_on` names that same event,
+      # reproduces this exactly: `Fanout.listens?` enqueues the row
+      # because the event name matches `ends_on`, `end_saga` finds
+      # nothing under that correlation to delete, and neither logs a
+      # word). A `saga:` row draining to `delivered` with zero matching
+      # `saga_log` entries is therefore not a finding — only check 1
+      # applies to it.
+      #
+      # **Not a grammar construct** — `FEATURE_COVERAGE`'s own `dry_runs_
+      # leave_no_trace` precedent: the outbox is a runtime door
+      # (`Runtime::Outbox`), not a word a bluebook declares, so there is
+      # no feature string here to claim.
+      module Outbox
+        def outbox_rows_match_reactions(history)
+          bluebooks = history.fetch(:bluebooks, {})
+
+          offenders = Array(history[:outbox_traces]).flat_map do |trace|
+            trace[:rows].flat_map { |row| outbox_row_offenders(row, trace, bluebooks) }
+          end
+
+          offenders.empty? || offenders.join("; ")
+        end
+
+        def outbox_row_offenders(row, trace, bluebooks)
+          on = row.dig(:event, :name)
+
+          case row[:status]
+          when "pending", "claimed"
+            ["outbox row #{row[:delivery_id]} (#{row[:consumer]} on #{on}) never drained inline — status stayed " \
+             "#{row[:status].inspect} though delivery is inline by contract (Runtime::Outbox's own header)"]
+          when "failed"
+            ["outbox row #{row[:delivery_id]} (#{row[:consumer]} on #{on}) failed to deliver: #{row[:error]} — " \
+             "a domain refusal never reaches this far; a failed row names a defect in the relay's own consumer " \
+             "resolution"]
+          when "delivered"
+            outbox_delivered_policy_offenders(row, on, trace, bluebooks)
+          else
+            []
+          end
+        end
+
+        # See this file's own header for why a `saga:` row is exempt: its
+        # own `listens?` gives no such guarantee, unlike a policy's single,
+        # deterministic `where` gate.
+        def outbox_delivered_policy_offenders(row, on, trace, bluebooks)
+          kind, fqn = row[:consumer].to_s.split(":", 2)
+          return [] unless kind == "policy"
+
+          home, name = fqn.to_s.split("::", 2)
+          return [] if trace[:reactions].any? { |entry| entry[:policy] == name && entry[:on] == on }
+
+          policy = bluebooks[home]&.policies&.find { |candidate| candidate.name == name }
+          return [] unless policy # nothing declared under this name — inconclusive, not a claimed mismatch
+          return [] if policy.fans_out? # fan-out row count is fanout_dispatches_once_per_matching_row's job
+
+          held = independently_re_evaluate_policy_where(policy, row[:event])
+          return [] if held != true # false, or inconclusive (the where itself raised) — never a claimed mismatch
+
+          ["outbox row #{row[:delivery_id]} (#{row[:consumer]} on #{on}) drained as delivered, but no matching " \
+           "reaction_log entry exists and the policy's own where clause independently re-evaluates true — " \
+           "PolicyInterpreter#deliver only ever returns nil (no reaction_log entry) when where does not hold"]
+        end
+
+        # `PolicyInterpreter#where_holds?`'s own two branches, reproduced —
+        # never calling that method again, which would only ever agree
+        # with itself (the same rule `resolve_dispatch_binding`'s own
+        # comment states). `Evaluator.call` (the raw-string entry, parsed
+        # and cached — never `call_rule`, which needs the policy's own
+        # build-time `where_rule` AST, an object this history has no
+        # reason to carry) is the exact same call `Replay#fan_out_finding`
+        # already makes for the identical fact one property over
+        # (`policy.where.to_s.empty? || Evaluator.call(policy.where, {},
+        # payload)`), reused rather than re-derived a second, slightly
+        # different way. `rescue`d to `nil`, not `false`: a where clause
+        # that cannot be re-evaluated from the row's own recorded payload
+        # alone is inconclusive, not proof either way — the same "never a
+        # claimed pass or a claimed mismatch from a resolution this replay
+        # cannot actually reproduce" discipline `build_guard_check`'s own
+        # rescue clause already follows.
+        def independently_re_evaluate_policy_where(policy, event)
+          return true if policy.where.to_s.empty?
+
+          payload = (event[:payload] || {}).transform_keys(&:to_sym)
+          Bluebook::Expression::Evaluator.call(policy.where, {}, payload)
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -10,7 +10,7 @@ module Hecks
       # (#query_for_verb, #query_eligible_rows, #resolve_hop_clause) other
       # property modules in this directory also call.
       module Querying
-        # THE QUERY ORACLE — differential testing within the one runtime,
+        # The query oracle — differential testing within the one runtime,
         # the shape the retired cross-runtime harness should always have
         # been. Every generated ask was answered twice at the same instant
         # (Replay records both): once through whatever the aggregate is
@@ -18,17 +18,17 @@ module Hecks
         # a SQL binding would compile it), once through the reference
         # interpreter's own evaluation. The two are separate, live
         # implementations of the same comparator vocabulary, and they have
-        # drifted before — an adapter that ACCEPTS what the reference says
+        # drifted before — an adapter that accepts what the reference says
         # matches nothing, or orders what it refuses to order, shows up
         # here as a finding no self-referential adapter spec could see.
         # M23 — `Replay` now runs the native and reference engines
-        # INDEPENDENTLY (each in its own begin/rescue — see that file's own
+        # independently (each in its own begin/rescue — see that file's own
         # comment at the capture site), so this property can tell apart what
         # used to be indistinguishable: "both engines refused" (fine — the
         # ask was genuinely bad, nothing to compare) from "one refused and
         # the other did not" (a real divergence — the two engines disagree
-        # about whether the ask was even VALID, never mind what it answers).
-        # `native_refused`/`reference_refused` are read by KEY PRESENCE, not
+        # about whether the ask was even valid, never mind what it answers).
+        # `native_refused`/`reference_refused` are read by key presence, not
         # truthiness — `Replay` only ever adds `:error`/`:reference_error`
         # to an entry when that side actually raised, so an absent key is an
         # unambiguous "this side answered." A read-model ask (no reference
@@ -59,16 +59,16 @@ module Hecks
           offenders.empty? || offenders.join("; ")
         end
 
-        # THE SAME "TWO ENGINES, COMPARED" SHAPE query_answers_match_reference
+        # The same "two engines, compared" shape query_answers_match_reference
         # already uses, aimed squarely at Query#options' offset/limit pair —
-        # but recomputed from history[:instances] directly, a THIRD,
+        # but recomputed from history[:instances] directly, a third,
         # independent computation, rather than comparing QueryInterpreter's
         # own native and reference paths against each other (which could
         # share the identical bug neither implementation happened to hit —
-        # see #4's own fix, which touched BOTH #interpret and
+        # see #4's own fix, which touched both #interpret and
         # #reference_interpret at once). `order_by` declared alongside
         # `offset` or `limit` names a genuinely paged query. Ports::Query::
-        # Ordering.apply is the SAME engine QueryInterpreter#ordered calls,
+        # Ordering.apply is the same engine QueryInterpreter#ordered calls,
         # reused here rather than re-derived, so this oracle cannot drift
         # from what "in order" means without the interpreter drifting the
         # identical way — only the offset-then-limit .drop/.first slice
@@ -112,7 +112,7 @@ module Hecks
           offenders.empty? || offenders.join("; ")
         end
 
-        # THE DECLARED Query ITSELF, resolved from a replayed verb — the
+        # The declared Query itself, resolved from a replayed verb — the
         # same shape #command_for_verb resolves a command by, one
         # construct over. Entity-level queries (a dotted query_path) are
         # out of scope here — paging on an entity's own list has no real
@@ -128,24 +128,24 @@ module Hecks
           aggregate&.query(query_path)
         end
 
-        # A QUERY'S OWN ROWS — unlike #eligible_rows (a ReadModel's
+        # A query's own rows — unlike #eligible_rows (a ReadModel's
         # reduced/grouped many-side head, possibly FK-joined against a
-        # root), a Query always asks about its OWN owning aggregate
+        # root), a Query always asks about its own owning aggregate
         # directly ; no join, no reference_target. `id:` merged in the
         # same way #eligible_rows' own rows are, since a stable sort
         # (Ordering.apply's own `identity:`) and the real answer's own
         # `record.state.merge(id: record.id)` both need it.
-        # `bluebooks:` — needed ONLY to recognise and resolve a `/` HOP
+        # `bluebooks:` — needed only to recognise and resolve a `/` hop
         # clause (`engagement/client/status`, hop_chain.bluebook's own
-        # PricedAboveViaEngagement): a hop's head names one of the OWNING
+        # PricedAboveViaEngagement): a hop's head names one of the owning
         # aggregate's declared references, and only the declaration graph
         # can say which attribute that is and which aggregate it targets.
         # A local clause never consults it. Latent gap this closed, found
         # by the fuzzer itself the first time a generated sequence ever
-        # built a full hop chain AND had its paged query answer a row
+        # built a full hop chain and had its paged query answer a row
         # (seed 1, the moment scalar_value_objects.bluebook joined the
         # fixtures corpus and shifted every seeded draw): the recompute
-        # dug `engagement/client/status` as a LOCAL dotted path, found
+        # dug `engagement/client/status` as a local dotted path, found
         # nil, and declared every genuinely-eligible row ineligible — a
         # false property violation against a correct runtime answer,
         # reproducible on an untouched main with this same 4-step script.
@@ -173,7 +173,7 @@ module Hecks
         # would be checking the runtime against itself). One hop peels
         # off the head (`HopPath.next_hop`, the identical one-step
         # primitive the live fold uses), the inner clause recurses
-        # through `query_eligible_rows` against the TARGET's own
+        # through `query_eligible_rows` against the target's own
         # snapshot rows (so a multi-hop tail resolves hop by hop, exactly
         # as the live path's own recursion does), and the ids that
         # answered fold back as the same local `in` membership clause the

data/lib/hecks/fuzzing/properties.rb

@@ -9,35 +9,37 @@ 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 — 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.
     #
     # 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
+    # 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
@@ -55,15 +57,18 @@ module Hecks
       extend Querying
       extend Guards
       extend DispatchAndMutations
+      extend DryRuns
       extend InvariantsAndAggregation
+      extend Corrections
+      extend Outbox
 
       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 = {
@@ -75,17 +80,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.
@@ -96,39 +101,70 @@ module Hecks
         fanout_dispatches_once_per_matching_row:          %w[Policy#for_each Policy#where],
         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]
+        group_by_matches_recompute:                       %w[ReadModel#group_by],
+        # 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
+        # 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:                      [],
+        # **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 —
+      # 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
+      # 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
@@ -154,13 +190,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 " \
@@ -181,7 +222,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.
@@ -189,8 +230,8 @@ 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
+      # 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.
       def check(history)
         { lifecycle_values_are_declared:                    lifecycle_values_are_declared(history),
@@ -205,8 +246,12 @@ module Hecks
           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) }
+          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

data/lib/hecks/fuzzing/qa_settings.rb

@@ -0,0 +1,152 @@
+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
+        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
+
+      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