hecks 1.3.0 → 1.4.0

data/lib/hecks/fuzzing/sequence_generator/adversary.rb

@@ -5,12 +5,12 @@ require_relative "../../runtime/value"
 module Hecks
   module Fuzzing
     class SequenceGenerator
-      # THE ARGUMENT SHAPES THE RUBY/RUST DIVERGENCES WERE ACTUALLY FOUND
-      # THROUGH, injected on purpose, on every domain.
+      # The argument shapes the Ruby/Rust divergences were actually found
+      # through, injected on purpose, on every domain.
       #
       # Ten bugs in one QA session (BUG#7–#16, `QualityControl`'s own
       # ledger) clustered in a handful of mechanisms — and several were
-      # only ever reachable because ONE domain happened to declare the
+      # only ever reachable because one domain happened to declare the
       # argument that tripped them: `Roster::Roster.Mark`'s own `to:`
       # collided with the dispatcher's routing `to:` (BUG#7), a present-
       # but-null `to:` was misread as a routing envelope (BUG#16), a blank
@@ -20,28 +20,28 @@ module Hecks
       # in the rotation could ever have found any of those, because
       # nothing generated ever produced the shape. This module produces
       # them — for a configurable fraction of command steps, chosen and
-      # parameterised from the SAME seeded RNG the rest of the generator
+      # parameterised from the same seeded RNG the rest of the generator
       # already draws from, so `generate(domain, seed:, steps:,
       # adversarial:)` stays exactly as reproducible per seed as it was.
       #
-      # OPT-IN, BY CONSTRUCTION. `adversarial: 0.0` (the default) returns
+      # **Opt-in, by construction**. `adversarial: 0.0` (the default) returns
       # before drawing a single random number, so every pinned seed in
       # spec/fuzzing, spec/rust_conformance_fuzz_spec.rb, bin/fuzz and
       # bin/generate produces byte-for-byte what it produced before this
       # module existed. `bin/qa_sweep` turns it on (reading
       # `QualityControlDials::ADVERSARIAL_FRACTION`) — that script is the
-      # one place a mutated step's own divergence is a FINDING rather than
+      # one place a mutated step's own divergence is a finding rather than
       # a red CI gate.
       #
-      # ONE MUTATION PER STEP, applied in `StepBuilder#build_command_step`
-      # after the arguments and identity are built and BEFORE the step's
+      # One mutation per step, applied in `StepBuilder#build_command_step`
+      # after the arguments and identity are built and before the step's
       # own inline dispatch — so the generator's own `known_ids` tracking
-      # sees what really happened, and so the returned step's `args` ARE
+      # sees what really happened, and so the returned step's `args` are
       # the mutated bytes both `Fuzzing::Replay` (Ruby) and the compiled
       # conformance binary (Rust) later receive. The step carries an
       # `"adversarial"` key naming what was done (`mutation`, the bug
       # class it exercises, and the exact sub-shape), which `bin/qa_sweep`
-      # prints on a FOUND SOMETHING report so the agent logging the Bug
+      # prints on a found something report so the agent logging the Bug
       # can name the mechanism, not guess it. Both replay paths ignore
       # the key: `Replay.call` reads only verb/query/dry_run/args/role,
       # and `kernel/cli.rs` reads step keys by name.
@@ -72,19 +72,19 @@ module Hecks
         VALUE_OBJECT_SHAPES = %w[null empty_object].freeze
 
         # BUG#7/#8/#14's class — an unknown key, a type-mismatched declared
-        # key and an absent required key in the SAME step, so both engines
+        # key and an absent required key in the same step, so both engines
         # have to pick which refusal wins; and each pair, so the ordering
         # of any two is observable on a command too small for all three.
         #
-        # THE SECOND ROW REACHES FURTHER DOWN `DISPATCH_ORDER`
+        # The second row reaches further down `DISPATCH_ORDER`
         # (lib/hecks/vocabulary.rb): `nonexistent` addresses an id nothing
         # holds (a `hydrate`-stage NotFound), `lifecycle` aims a
         # transition-guarded command at a real record (an
-        # `admissible_transition`-stage refusal, IF the record's state
+        # `admissible_transition`-stage refusal, if the record's state
         # refuses it), `role` binds a caller whose role the command does
         # not name (the `refuse_role_mismatch` stage no generated step
         # had ever reached). Paired with an argument-stage fault each,
-        # so the ordering of an EARLY stage against a LATE one is
+        # so the ordering of an early stage against a late one is
         # observable — BUG#13 (ledger_ordering's own NOTES.md) was
         # exactly an argument-invariant-vs-entity-existence ordering
         # split, and nothing generated had ever asked the question on
@@ -94,8 +94,8 @@ module Hecks
           nonexistent+mismatch nonexistent+unknown lifecycle+mismatch role+absent role+nonexistent
         ].freeze
 
-        # ITEM 2 OF THE DETECTION PLAN (ANGLE-5) — A DRAWN CALLER ON A
-        # ROLE-GATED COMMAND. `refuse_role_mismatch` is a `DISPATCH_ORDER`
+        # Item 2 of the detection plan (angle-5) — a drawn caller on a
+        # role-gated command. `refuse_role_mismatch` is a `DISPATCH_ORDER`
         # step both engines implement (`command_rules/authorization.rb`,
         # `rust/src/kernel/repository.rs check_role`) and both replay doors
         # already read (`Fuzzing::Replay` binds `Hecks.as_caller` from a
@@ -109,24 +109,24 @@ module Hecks
         #   absent_on_gated no caller at all on a gated command — the
         #                   unchecked default, recorded so the step reads
         #                   as a deliberate control, not an omission
-        #   actor_known     the role PLUS an actor this same sequence
-        #                   already granted it to (`Governance::
-        #                   RoleAssignment.Assign` succeeded earlier) —
+        #   actor_known     the role plus an actor this same sequence
+        #                   already granted it to (the authorization
+        #                   provider's declared `grant:` verb succeeded
+        #                   earlier — `catalog[:grant_verbs]`) —
         #                   the real `holds_role?` lookup, both sides
         #   actor_unknown   the role plus an actor nothing granted —
         #                   `holds_role?` must refuse on both
-        # A SEPARATE LAYER FROM `KINDS`, with its own probability
+        # a separate layer from `KINDS`, with its own probability
         # (`role_draw:` — `QualityControlDials::ROLE_DRAW_PROBABILITY`):
         # a caller composes with any argument mutation above rather than
         # competing with it for the one-mutation-per-step slot, and draws
         # nothing from the RNG when off, so every pinned seed is
         # byte-identical to before it existed.
         CALLER_SHAPES = %w[matching mismatched absent_on_gated actor_known actor_unknown].freeze
-        GRANT_VERB    = "Governance::RoleAssignment.Assign".freeze
         UNKNOWN_ROLE  = "Nobody the domain names".freeze
 
         # BUG#11 — an entity command two or more hops deep. Not a mutation
-        # of arguments but a PREFERENCE (picker.rb weights these up when
+        # of arguments but a preference (picker.rb weights these up when
         # adversarial) plus an addressing coin: flat one-head-per-hop args
         # (what every other generated entity step uses) or the routed
         # `to: { aggregate:, entities: [...] }` envelope BUG#11's own fix
@@ -136,7 +136,7 @@ module Hecks
         DEEP_ENTITY_WEIGHT = 4
 
         # BUG#13's mutation is only ever applicable on a step whose
-        # parent ALREADY holds an element this same sequence appended —
+        # parent already holds an element this same sequence appended —
         # a rare moment (an append has to have succeeded first, and most
         # mutated appends are refused), so when it is on offer it is
         # weighted up the same way the picker weights an unexercised
@@ -147,10 +147,10 @@ module Hecks
 
         def adversarial? = @adversarial.positive?
 
-        # `[]` — and NO RNG DRAW — when adversarial mode is off. Otherwise
+        # `[]` — and no RNG draw — when adversarial mode is off. Otherwise
         # the deep-entity addressing note (every deep step, when
         # adversarial), then with probability `@adversarial` exactly one
-        # mutation among those applicable to THIS step's own command.
+        # mutation among those applicable to this step's own command.
         def adversarial_mutations!(args, entry, catalog)
           return [] unless adversarial?
 
@@ -176,7 +176,7 @@ module Hecks
 
           heads   = [entry[:aggregate], *entry[:chain]].map { |construct| (construct.identified_by || :id).to_s }
           scalars = heads.map { |head| ValueGenerator.scalar_of(args[head]) }
-          # The heads leave the flat args — this is the CLEAN routed
+          # The heads leave the flat args — this is the clean routed
           # caller BUG#11's own spec pins (`to: {...}, note: {...}`) —
           # unless the command itself declares an attribute of that name
           # (chess's `Piece.Move` declares `id` as a fact too), which
@@ -236,7 +236,7 @@ module Hecks
 
         def blank_identity_applicable?(args, entry, catalog) = blank_identity_targets(args, entry, catalog).any?
 
-        # The identity heads THIS step supplies itself: a creating
+        # The identity heads this step supplies itself: a creating
         # aggregate command's own (every part of a composite), and an
         # append's caller-supplied entity identity arguments (an entity is
         # "created" by its append, and BUG#15's blank-identity question
@@ -344,8 +344,8 @@ module Hecks
           precedence_shapes_for(args, entry).any?
         end
 
-        # EVERY SHAPE WHOSE EVERY PART THIS STEP CAN CARRY. `nonexistent`
-        # and `lifecycle` need a command that ACTS on a record (a creating
+        # Every shape whose every part this step can carry. `nonexistent`
+        # and `lifecycle` need a command that acts on a record (a creating
         # step has no addressed id to point elsewhere, and no state to be
         # in) and flat addressing (`deep_entity_addressing!`'s routed `to:`
         # envelope owns the ids then); `lifecycle` additionally needs a
@@ -401,14 +401,14 @@ module Hecks
             applied << "unknown"
           end
           apply_late_stage_parts!(wanted, args, entry, detail, applied, catalog)
-          # Reported as what was ACTUALLY done — a command with a single
+          # Reported as what was actually done — a command with a single
           # attribute cannot carry both a dropped and a corrupted one.
           detail.merge("shape" => applied.sort.join("+"))
         end
 
-        # The three parts that reach PAST the argument gate — see
+        # The three parts that reach past the argument gate — see
         # `PRECEDENCE_SHAPES`' own second row. `nonexistent` re-addresses
-        # the step's LAST hop (the entity element for an entity command,
+        # the step's last hop (the entity element for an entity command,
         # the aggregate itself otherwise) to an id nothing holds;
         # `lifecycle` mutates nothing (the record's own state is what
         # refuses, or doesn't) and is recorded so the pairing is visible;
@@ -433,7 +433,7 @@ module Hecks
           applied << "role"
         end
 
-        # ── ANGLE-5: a drawn caller on a role-gated command ──────────────
+        # ── Angle-5: a drawn caller on a role-gated command ──────────────
 
         def role_draw? = @role_draw.positive?
 
@@ -491,7 +491,7 @@ module Hecks
           end
         end
 
-        # A GRANT AIMED AT A ROLE SOME COMMAND ACTUALLY DECLARES. Left to
+        # A grant aimed at a role some command actually declares. Left to
         # `ValueGenerator`, `Assign`'s `role_name` is random text
         # ("hotel"), which no command is gated on — so a granted actor
         # could never satisfy `holds_role?` for anything, and the
@@ -500,7 +500,7 @@ module Hecks
         # domain's own declared roles instead; with it off, nothing here
         # runs (no RNG draw, no change to the args).
         def steer_grant!(args, entry, catalog)
-          return unless role_draw? && entry[:verb] == GRANT_VERB && catalog[:roles].any?
+          return unless role_draw? && catalog[:grant_verbs].include?(entry[:verb]) && catalog[:roles].any?
           return unless args.key?("role_name")
 
           args["role_name"] = { "value" => catalog[:roles].sample(random: @random) }

data/lib/hecks/fuzzing/sequence_generator/catalog.rb

@@ -29,8 +29,8 @@ module Hecks
               catalog_entities(domain_name, aggregate, entity_commands, entity_queries)
             end
 
-            # THE BARE DOMAIN FORM — "Domain.report_name", no "::" — the
-            # SAME shape `Dispatcher#query` itself branches on to route a
+            # **The bare domain form** — "Domain.report_name", no "::" — the
+            # same shape `Dispatcher#query` itself branches on to route a
             # read-model ask apart from an aggregate query. A report was
             # never in this catalog at all before: `aggregation_matches_
             # recompute` (count/median) has only ever been exercised by
@@ -52,24 +52,31 @@ module Hecks
             # from (adversary.rb `other_role`).
             roles: (creating + instance + entity_commands).filter_map { |e| e[:command].role }
                                                           .map(&:to_s).reject(&:empty?).uniq.sort,
+            # The grant verb every loaded authorization provider declares
+            # (`provides "authorization", grant: ...`) — what the caller
+            # draw steers at a declared role and records as a real grant.
+            # Read off the declaration, never the literal Governance name.
+            grant_verbs: runtime.registry.authorization_providers
+                                .filter_map { |chapter| chapter.provided_verb(Bluebook::Capabilities::AUTHORIZATION, :grant) }
+                                .sort,
             # Which aggregates this corpus can actually make one of — the ones
             # `satisfiable?` is entitled to wait for.
             creatable: creating.to_set { |entry| entry[:aggregate].hecks_name } }
         end
 
-        # EVERY ENTITY, AT EVERY DEPTH — `Card` nested inside `Board`
+        # Every entity, at every depth — `Card` nested inside `Board`
         # inside `Workspace` (qa/stress_domains/nested_pieces) walks in
         # as `chain: [Board, Card]`, the exact hop list
-        # `EntityInterpreter#walk_entity_chain` resolves the dotted verb
+        # `EntityInterpreter::Resolution.of` resolves the dotted verb
         # back into. Before this walk existed the catalog only ever read
         # `aggregate.entities` one level down, so a two-hop entity
         # command (BUG#11's whole class) could never be generated at all
         # — the one shape the differential harness most needed to reach
         # was structurally absent from every sequence it ever produced.
-        # `entity:` stays the LAST hop (what every existing reader means
+        # `entity:` stays the last hop (what every existing reader means
         # by "the entity"); `chain:` is the whole path.
         #
-        # Entity QUERIES stay one hop deep, exactly as before — a nested
+        # Entity queries stay one hop deep, exactly as before — a nested
         # entity's query has no established wire spelling this generator
         # can vouch for, and nothing in the corpus declares one.
         def catalog_entities(domain_name, aggregate, entity_commands, entity_queries)
@@ -90,7 +97,7 @@ module Hecks
         end
 
         # Depth-first, parents before children, in declaration order — so
-        # the depth-1 entries land in `entity_commands` in EXACTLY the
+        # the depth-1 entries land in `entity_commands` in exactly the
         # order they always did (a pinned seed's picker pool is the same
         # pool it was), and a nested entity's own entries follow its
         # parent's.
@@ -108,16 +115,16 @@ module Hecks
         # (CommandInterpreter#entity_element) when the append's own field
         # mapping doesn't already assign it — the common case, predicted here.
         # A domain whose append explicitly assigns identity through a mapped
-        # argument is covered too, without guessing: whatever value THIS
-        # generator supplied for that argument at dispatch time IS the
+        # argument is covered too, without guessing: whatever value this
+        # generator supplied for that argument at dispatch time is the
         # identity, and gets recorded directly (see `record_outcome`).
         #
         # `owner_chain:` — `[]` for an aggregate-level append (`Board.AddList`,
-        # `Folder.AddSlip`), the entity path for an ENTITY-level one
+        # `Folder.AddSlip`), the entity path for an entity-level one
         # (`Board.AddCard` appending into `Board.cards`, owner_chain
         # `[Board]`) — so `record_outcome` can key the appended element
         # under the exact parent-plus-hops it landed beneath.
-        # `identity_arguments:` — EVERY identity head the mapping sources
+        # `identity_arguments:` — every identity head the mapping sources
         # from a command argument (a composite entity identity has several),
         # what the adversarial duplicate-identity mutation replays;
         # `identity_argument:` stays the single-head reading the existing

data/lib/hecks/fuzzing/sequence_generator/outcome_tracker.rb

@@ -15,7 +15,7 @@ module Hecks
           parent_scalar = identity_scalar_of(aggregate, args)
 
           @known_ids[aggregate.hecks_name] << parent_scalar if entry[:entity].nil? && entry[:command].creates?
-          record_grant(args) if entry[:verb] == Adversary::GRANT_VERB
+          record_grant(args) if catalog[:grant_verbs].include?(entry[:verb])
 
           populator = populator_for_entry(catalog, entry)
           return unless populator
@@ -35,24 +35,25 @@ module Hecks
             end
           @entity_known_ids[key] << new_id
 
-          # THE CALLER-SUPPLIED IDENTITY TUPLE, kept whole — every mapped
+          # The caller-supplied identity tuple, kept whole — every mapped
           # identity argument and the exact value this step offered for it
           # — so the adversarial duplicate-identity mutation (BUG#13's own
           # shape, `Folder.AddSlip` twice under the same `reference`) can
-          # offer it AGAIN later against the same parent, composite
-          # identities included (BUG#13's fix explicitly did NOT cover
+          # offer it again later against the same parent, composite
+          # identities included (BUG#13's fix explicitly did not cover
           # those; this is how a sequence gets to ask).
           return if populator[:identity_arguments].empty?
 
           @appended_identities[key] << populator[:identity_arguments].to_h { |name| [name.to_s, args[name.to_s]] }
         end
 
-        # A GRANT THIS SEQUENCE MADE FOR REAL — `Governance::RoleAssignment.
-        # Assign` succeeded with these exact args, so `actor_id` now holds
+        # A grant this sequence made for real — the authorization provider's
+        # declared `grant:` verb (`Governance::RoleAssignment.Assign` in
+        # every boot today) succeeded with these exact args, so `actor_id` now holds
         # `role_name` in this boot's own store, on both replay sides. The
         # `actor_known` caller shape (adversary.rb) replays that identity
         # against a command gated on the same role: the one way a
-        # generated step reaches `holds_role?`'s AUTHORIZED branch rather
+        # generated step reaches `holds_role?`'s authorized branch rather
         # than only its refusing one.
         def record_grant(args)
           role  = ValueGenerator.scalar_of(args["role_name"]).to_s
@@ -60,7 +61,7 @@ module Hecks
           @granted[role] << actor unless role.empty? || actor.empty?
         end
 
-        # THE POOL AN APPENDED ELEMENT LANDS IN — the aggregate's own
+        # The pool an appended element lands in — the aggregate's own
         # identity, then one scalar per owning hop (an aggregate-level
         # append has none; `Board.AddCard` has `Board`'s own `number`,
         # read straight back off the args this step addressed it by).
@@ -81,18 +82,18 @@ module Hecks
           "#{aggregate_name}.#{chain_names.join('.')}##{scalars.join('/')}"
         end
 
-        # THE SCALAR THIS STEP'S OWN AGGREGATE IDENTITY RESOLVES TO, from the
+        # The scalar this step's own aggregate identity resolves to, from the
         # args a creating (or entity-populating) command actually
-        # dispatched — a SINGLE declared head (or the untyped default
+        # dispatched — a single declared head (or the untyped default
         # `:id`) reads straight off its own top-level arg the way this
         # always has (`ValueGenerator.scalar_of`, opening the identity value
-        # object). A genuinely COMPOSITE identity (`composite_identity?`,
+        # object). A genuinely composite identity (`composite_identity?`,
         # shared with StepBuilder#add_identity! — see its own comment) has
         # no such top-level arg at all: `add_identity!` deliberately leaves
         # a composite creating command's own individually-declared fields
         # alone rather than forcing a synthetic `id` neither the bluebook
         # nor the command ever declared, so this joins those fields itself,
-        # in the SAME declaration order `Runtime::Identity.of` joins them
+        # in the same declaration order `Runtime::Identity.of` joins them
         # at dispatch (`Naming.identity`, `Naming::IDENTITY_JOIN`) — which
         # is exactly what makes the result usable later as the bare `id:`
         # a composite Revoke/act-again command expects (`Identity.from`'s

data/lib/hecks/fuzzing/sequence_generator/picker.rb

@@ -1,8 +1,8 @@
 module Hecks
   module Fuzzing
     class SequenceGenerator
-      # Which step to try next: eligibility (what is POSSIBLE from the
-      # state so far) and weighting (what is LIKELY to reach somewhere
+      # Which step to try next: eligibility (what is possible from the
+      # state so far) and weighting (what is likely to reach somewhere
       # new).
       module Picker
         private
@@ -23,7 +23,7 @@ module Hecks
 
         # BUG#11's own preference (adversary.rb) — an entity command two
         # or more hops deep is weighted up the same way an unexercised
-        # verb is, ONLY in adversarial mode: the eligibility rules above
+        # verb is, only in adversarial mode: the eligibility rules above
         # still decide what is possible, and a default-mode pool is
         # exactly the pool it always was.
         def deep_entity_bias(rest)
@@ -31,11 +31,11 @@ module Hecks
           deep * Adversary::DEEP_ENTITY_WEIGHT
         end
 
-        # WHILE THERE IS NOTHING TO FIND, MAKING SOMETHING IS THE ONLY USEFUL MOVE.
+        # While there is nothing to find, making something is the only useful move.
         #
         # A flat weight is right once the domain has records in it, and badly
         # wrong before: banking declares ten queries, and from an empty store
-        # exactly ONE creating command is satisfiable — Customer.Register, the
+        # exactly one creating command is satisfiable — Customer.Register, the
         # verb the whole cascade waits on. Two entries against ten left runs
         # spending their entire budget querying a store nothing had been written
         # to ; one seed answered ten empty queries in a row and emitted nothing
@@ -54,9 +54,9 @@ module Hecks
           @known_ids[entry[:aggregate].hecks_name].any? && satisfiable?(catalog, entry)
         end
 
-        # A ROOTLESS report (no `reference_to` at all) has nothing to wait
+        # A rootless report (no `reference_to` at all) has nothing to wait
         # for — it reads whole tables, the same "always eligible" position
-        # `catalog[:queries]` itself takes. A ROOTED one needs a real
+        # `catalog[:queries]` itself takes. A rooted one needs a real
         # instance of its own `reference_target` to ask about first, same
         # rule `actionable?` already gives an instance command — asking
         # `Banking.disputed_payment_count` before any Account exists would
@@ -66,7 +66,7 @@ module Hecks
           entry[:model].reference_target.nil? || @known_ids[entry[:model].reference_target].any?
         end
 
-        # A COMMAND THAT REFERENCES NOTHING THAT EXISTS CANNOT SUCCEED, so it is
+        # A command that references nothing that exists cannot succeed, so it is
         # not offered until something does.
         #
         # `ValueGenerator.reference_value` has no real id to hand over when its
@@ -78,7 +78,7 @@ module Hecks
         # spent its whole budget being refused.
         #
         # This is the rule instance commands already follow — `known_ids.any?` —
-        # applied to what a command REFERENCES rather than to what it acts on.
+        # applied to what a command references rather than to what it acts on.
         # A target no creating command in this corpus can make (a cross-domain
         # reference, which `CommandRules#resolve_references` skips anyway) is
         # exempt, or the whole domain would starve waiting for it.
@@ -92,14 +92,23 @@ module Hecks
         # Coverage-guided rather than uniformly random : a verb this sequence has
         # not dispatched yet is weighted up, so a run spends its budget on the
         # commands it has not reached instead of re-rolling the ones it has. The
-        # eligibility rules above still decide what is POSSIBLE — this only decides
+        # eligibility rules above still decide what is possible — this only decides
         # what is likely, so a verb gated behind state it does not have yet stays
         # out of the pool entirely rather than being preferred forever.
         def steer(pool)
           fresh = pool.reject { |entry| @exercised.include?(entry[:verb]) }
-          return pool if fresh.empty?
+          steered = fresh.empty? ? pool : pool + (fresh * UNEXERCISED_WEIGHT)
+          favor(steered)
+        end
+
+        # `favor:` (CoverageCampaign's rare verbs) — weighted up when
+        # eligible, never made eligible. An empty favor list returns the
+        # pool untouched, so an unguided seed draws exactly what it did.
+        def favor(pool)
+          return pool if @favor.empty?
 
-          pool + (fresh * UNEXERCISED_WEIGHT)
+          favored = pool.uniq.select { |entry| @favor.include?(entry[:verb]) }
+          pool + (favored * SequenceGenerator::FAVOR_WEIGHT)
         end
       end
     end