hecks 2.7.0 → 2.8.0

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

@@ -1,171 +0,0 @@
-module Hecks
-  module Fuzzing
-    class SequenceGenerator
-      # Everything the booted domain offers, indexed for the picker:
-      # creating vs instance commands, entity commands, queries, and the
-      # populators that predict where an appended element lands.
-      module Catalog
-        private
-
-        def build_catalog(runtime)
-          creating = []
-          instance = []
-          entity_commands = []
-          queries = []
-          entity_queries = []
-          read_models = []
-
-          runtime.registry.bluebooks.each do |domain_name, bluebook|
-            bluebook.aggregates.each do |aggregate|
-              aggregate.commands.each do |command|
-                entry = { verb: "#{domain_name}::#{aggregate.hecks_name}.#{command.hecks_name}",
-                          command: command, aggregate: aggregate }
-                (command.creates? ? creating : instance) << entry
-              end
-              aggregate.queries.each do |query|
-                queries << { verb: "#{domain_name}::#{aggregate.hecks_name}.#{query.name}",
-                             query: query, aggregate: aggregate }
-              end
-              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
-            # 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
-            # hand-built specs, never a single real generated sequence,
-            # because nothing here ever asked one. `model:`, not
-            # `aggregate:` — a rootless report has no aggregate of its
-            # own to be eligible against (see picker.rb's own use of
-            # `model.reference_target`).
-            bluebook.read_models.each do |model|
-              read_models << { verb: "#{domain_name}.#{model.query_name}", model: model }
-            end
-          end
-
-          { creating: creating, instance: instance, entity_commands: entity_commands,
-            queries: queries, entity_queries: entity_queries, read_models: read_models,
-            populators: populators(runtime),
-            # The aggregates a query filters on, and the fields it compares
-            # (query_binding.rb).
-            query_bindings: build_query_bindings(runtime),
-            # Every `role "..."` any command in the boot declares — the
-            # "wrong hat" pool the caller draw's `mismatched` shape picks
-            # 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`
-        # inside `Workspace` (qa/stress_domains/nested_pieces) walks in
-        # as `chain: [Board, Card]`, the exact hop list
-        # `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
-        # by "the entity"); `chain:` is the whole path.
-        #
-        # 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)
-          each_entity_chain(aggregate) do |chain|
-            entity = chain.last
-            path   = chain.map(&:hecks_name).join(".")
-            entity.commands.each do |command|
-              entity_commands << { verb: "#{domain_name}::#{aggregate.hecks_name}.#{path}.#{command.hecks_name}",
-                                   command: command, aggregate: aggregate, entity: entity, chain: chain }
-            end
-            next unless chain.size == 1
-
-            entity.queries.each do |query|
-              entity_queries << { verb: "#{domain_name}::#{aggregate.hecks_name}.#{path}.#{query.name}",
-                                  query: query, aggregate: aggregate, entity: entity }
-            end
-          end
-        end
-
-        # Depth-first, parents before children, in declaration order — so
-        # 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.
-        def each_entity_chain(owner, chain = [], &block)
-          owner.entities.each do |entity|
-            path = chain + [entity]
-            yield path
-            each_entity_chain(entity, path, &block)
-          end
-        end
-
-        # Which command, on which owner, appends to which entity list — so a
-        # successful dispatch can predict the identity the element it just
-        # added landed on. Entity#identified_by is filled by `Array(current).size + 1`
-        # (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
-        # 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
-        # (`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
-        # 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
-        # auto-mint prediction already keys on.
-        def populators(runtime)
-          runtime.registry.bluebooks.each_value.flat_map do |bluebook|
-            bluebook.aggregates.flat_map do |aggregate|
-              owners = [[aggregate, []]]
-              each_entity_chain(aggregate) { |chain| owners << [chain.last, chain] }
-
-              owners.flat_map do |owner, chain|
-                owner.commands.filter_map { |command| populator_for(aggregate, owner, chain, command) }
-              end
-            end
-          end
-        end
-
-        def populator_for(aggregate, owner, chain, command)
-          append = command.mutations.find { |mutation| mutation.op == :append }
-          return unless append
-
-          list_attribute = owner.attribute(append.target)
-          return unless list_attribute&.list?
-
-          entity = owner.entities.find { |candidate| candidate.hecks_name == list_attribute.type.to_s }
-          return unless entity
-
-          identity_field = entity.identified_by
-          mapped = identity_field && append.source[identity_field]
-          identity_arguments = entity.identity_heads.filter_map do |head|
-            source = append.source[head]
-            source if source.is_a?(Symbol)
-          end
-          { command: command, aggregate: aggregate, owner: owner, owner_chain: chain, entity: entity,
-            identity_field: identity_field, identity_argument: mapped.is_a?(Symbol) ? mapped : nil,
-            identity_arguments: identity_arguments }
-        end
-      end
-    end
-  end
-end

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

@@ -1,127 +0,0 @@
-require_relative "../value_generator"
-require_relative "../../naming"
-
-module Hecks
-  module Fuzzing
-    class SequenceGenerator
-      # What a successful step created, and how a later step draws on it —
-      # the state tracking that makes multi-step sequences reach further
-      # than single calls ever did.
-      module OutcomeTracker
-        private
-
-        def record_outcome(catalog, entry, args)
-          aggregate = entry[:aggregate]
-          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 catalog[:grant_verbs].include?(entry[:verb])
-
-          populator = populator_for_entry(catalog, entry)
-          return unless populator
-
-          key = append_pool_key(populator, args)
-
-          # The auto-minted case (CommandInterpreter#entity_element): the
-          # element just landed at count-so-far + 1. The explicit case: this
-          # generator itself supplied whatever value sits at
-          # args[identity_argument] — no guessing needed, it's read straight
-          # back.
-          new_id =
-            if populator[:identity_argument]
-              ValueGenerator.scalar_of(args[populator[:identity_argument].to_s])
-            else
-              (@entity_known_ids[key].size + 1).to_s
-            end
-          @entity_known_ids[key] << new_id
-
-          # 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
-          # 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 — 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
-        # than only its refusing one.
-        def record_grant(args)
-          role  = ValueGenerator.scalar_of(args["role_name"]).to_s
-          actor = ValueGenerator.scalar_of(args["actor_id"]).to_s
-          @granted[role] << actor unless role.empty? || actor.empty?
-        end
-
-        # 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).
-        def append_pool_key(populator, args)
-          parent_scalar = identity_scalar_of(populator[:aggregate], args)
-          owner_scalars = populator[:owner_chain].map do |piece|
-            ValueGenerator.scalar_of(args[(piece.identified_by || :id).to_s])
-          end
-          entity_pool_key(populator[:aggregate].hecks_name,
-                          populator[:owner_chain].map(&:hecks_name) + [populator[:entity].hecks_name],
-                          [parent_scalar] + owner_scalars)
-        end
-
-        # `"Agg.Board#w1"` for a depth-1 pool — byte-identical to the key
-        # this always used, so nothing a pinned seed draws from moves —
-        # and `"Agg.Board.Card#w1/1"` one hop deeper.
-        def entity_pool_key(aggregate_name, chain_names, scalars)
-          "#{aggregate_name}.#{chain_names.join('.')}##{scalars.join('/')}"
-        end
-
-        # 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
-        # `: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?`,
-        # 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
-        # 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
-        # own untyped fallback, reached when `identity_of` finds no
-        # top-level field args to join, reads a bare `id:` straight
-        # through unattributed).
-        def identity_scalar_of(aggregate, args)
-          parent_key = (aggregate.identified_by || :id).to_s
-          return ValueGenerator.scalar_of(args[parent_key]) unless composite_identity?(aggregate)
-
-          parts = aggregate.identity_paths.map { |path| ValueGenerator.scalar_of(args[path.to_s.split(".").first]) }
-          Naming.identity(parts)
-        end
-
-        def pick_known(name)
-          pool = @known_ids[name]
-          return ValueGenerator.random_id(@random) if pool.empty? || @random.rand < ValueGenerator::INVALID_REFERENCE_PROBABILITY
-
-          pool.sample(random: @random)
-        end
-
-        def pick_entity_known(key)
-          pool = @entity_known_ids[key]
-          return ValueGenerator.random_id(@random) if pool.empty? || @random.rand < ValueGenerator::INVALID_REFERENCE_PROBABILITY
-
-          pool.sample(random: @random)
-        end
-      end
-    end
-  end
-end

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

@@ -1,116 +0,0 @@
-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
-      # new).
-      module Picker
-        private
-
-        def pick(catalog)
-          rest = catalog[:queries].dup
-          catalog[:instance].each { |entry| rest << entry if actionable?(catalog, entry) }
-          catalog[:entity_commands].each { |entry| rest << entry if actionable?(catalog, entry) }
-          catalog[:entity_queries].each { |entry| rest << entry if @known_ids[entry[:aggregate].hecks_name].any? }
-          catalog[:read_models].each { |entry| rest << entry if read_model_actionable?(entry) }
-
-          makers = catalog[:creating].select { |entry| satisfiable?(catalog, entry) }
-          pool   = rest + makers.flat_map { |entry| [entry] * creating_weight(rest.size) }
-          pool  += deep_entity_bias(rest) if adversarial?
-
-          steer(pool).sample(random: @random)
-        end
-
-        # 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
-        # still decide what is possible, and a default-mode pool is
-        # exactly the pool it always was.
-        def deep_entity_bias(rest)
-          deep = rest.select { |entry| (entry[:chain] || []).size >= Adversary::DEEP_ENTITY_DEPTH }
-          deep * Adversary::DEEP_ENTITY_WEIGHT
-        end
-
-        # 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
-        # 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
-        # at all.
-        #
-        # So while nothing exists, creation matches everything else put together.
-        # After that the ordinary weight applies and the run gets on with
-        # exercising what it made.
-        def creating_weight(rest_size)
-          return CREATING_WEIGHT if @known_ids.each_value.any?(&:any?)
-
-          [rest_size, CREATING_WEIGHT].max
-        end
-
-        def actionable?(catalog, entry)
-          @known_ids[entry[:aggregate].hecks_name].any? && satisfiable?(catalog, entry)
-        end
-
-        # 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
-        # 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
-        # just be refused (`refuse_object_reference`/`NotFound`) the same
-        # way `Account.Credit` would be, for the identical reason.
-        def read_model_actionable?(entry)
-          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
-        # not offered until something does.
-        #
-        # `ValueGenerator.reference_value` has no real id to hand over when its
-        # pool is empty, so it mints `missing-…` and the dispatch is refused
-        # before it starts — a guaranteed waste of a step, and worse, one that
-        # never fills the pool it was waiting on. Banking cascades from it:
-        # Account.Open needs a Customer, ATMCard.Issue needs an Account,
-        # Transfer.Request needs two, so a run that opened with the wrong verb
-        # 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.
-        # 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.
-        def satisfiable?(catalog, entry)
-          entry[:command].attributes.select(&:reference?).all? do |attribute|
-            target = attribute.type.target_name.to_s
-            !catalog[:creatable].include?(target) || @known_ids[target].any?
-          end
-        end
-
-        # 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
-        # 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]) }
-          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?
-
-          favored = pool.uniq.select { |entry| @favor.include?(entry[:verb]) }
-          pool + (favored * SequenceGenerator::FAVOR_WEIGHT)
-        end
-      end
-    end
-  end
-end

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

@@ -1,138 +0,0 @@
-require_relative "../../query_specification/field_path"
-require_relative "../../runtime/value"
-
-module Hecks
-  module Fuzzing
-    class SequenceGenerator
-      # Query arguments drawn from what the sequence has already written.
-      #
-      # A query is only a real test of an adapter when its argument names a row
-      # that exists. A `where(site_reference: :site_reference)` asked with a
-      # freshly generated word matches nothing on every adapter, so an adapter
-      # that compiles the comparison wrongly (and so also matches nothing) is
-      # indistinguishable from a correct one. Every argument `args_for` draws
-      # is independent of the store, and the chance that one lands on a stored
-      # value is small enough that a whole persistence-parity sweep can pass
-      # without a single query returning a row.
-      #
-      # ## What is written, and what is bound
-      #
-      # After each command that took effect, every aggregate a query filters
-      # on is read back from the repository, and the values of exactly the
-      # fields those queries compare (`bound_fields`) are remembered as one
-      # row per record. A row is what the store holds, not what a command was
-      # given, so a value a `sets` mapping renamed, a policy wrote in another
-      # aggregate, or a lifecycle transition assigned is covered too. A later
-      # query step usually takes its arguments from one remembered row, so
-      # several parameters filter the same record. The rest of the time it
-      # keeps the generated argument, which is what reaches the empty answer.
-      #
-      # ## Why a separate random stream
-      #
-      # The choice draws from its own `Random`, seeded from the sequence's
-      # seed and restarted wherever `@random` is (`restart_random`). Drawing
-      # from `@random` would shift every later step of every seed. This way
-      # each seed generates the same commands, in the same order, with the
-      # same arguments as before, and only the arguments of a query step
-      # change. A query changes no state, so nothing downstream moves.
-      module QueryBinding
-        # How often a query step whose aggregate has written rows takes its
-        # arguments from one of them. High, because a query that misses a
-        # stored row tests nothing, and the miss is still drawn the other
-        # quarter of the time.
-        BOUND_QUERY_PROBABILITY = 0.75
-
-        # Comparators whose argument is one scalar or value, so a stored value
-        # is a legitimate operand. `in` takes a list and `none_in_state` an
-        # `"Aggregate:state"` string; a stored value is neither.
-        BINDABLE_OPERATORS = %i[eq ne lt lte gt gte].freeze
-
-        # Keeps the binding stream apart from `@random`'s, which is seeded
-        # with the bare seed.
-        BINDING_SEED_OFFSET = 0x9e3779b1
-
-        private
-
-        # `{"Domain::Aggregate" => {domain:, aggregate:, fields: [String]}}`
-        # for every aggregate some query filters on, where `fields` is the
-        # union of the stored fields those queries compare.
-        def build_query_bindings(runtime)
-          runtime.registry.bluebooks.each_with_object({}) do |(domain_name, bluebook), bindings|
-            bluebook.aggregates.each do |aggregate|
-              fields = aggregate.queries.flat_map { |query| bound_fields(query).values }.uniq
-              next if fields.empty?
-
-              bindings["#{domain_name}::#{aggregate.hecks_name}"] =
-                { domain: domain_name, aggregate: aggregate, fields: fields }
-            end
-          end
-        end
-
-        # `{parameter name => stored field}` for each `where` clause whose
-        # operand is one of the query's own parameters. A clause on a literal,
-        # or aimed at another aggregate's field (`target`), binds nothing.
-        def bound_fields(query)
-          query.wheres.each_with_object({}) do |clause, fields|
-            next unless clause.value.is_a?(Symbol) && clause.target.nil?
-            next unless BINDABLE_OPERATORS.include?(clause.op.to_sym)
-
-            fields[clause.value.to_s] ||= clause.field.to_s
-          end
-        end
-
-        # Remembers the compared fields of every stored record of every
-        # aggregate a query filters on, as one row per distinct record shape.
-        def harvest_written_rows(runtime, catalog)
-          catalog[:query_bindings].each do |key, binding|
-            repository = runtime.registry.repository(binding[:domain], binding[:aggregate])
-            repository.all.each do |record|
-              row = binding[:fields].to_h { |field| [field, written_value(field_of(record, field))] }.compact
-              @written_rows[key] << row unless row.empty? || @written_rows[key].include?(row)
-            end
-          end
-        end
-
-        def field_of(record, field) = QuerySpecification::FieldPath.dig(record.state, field)
-
-        # A stored value as the JSON-shaped argument a step carries: string
-        # keys, nested values opened. `nil` for anything a query argument
-        # cannot be (a missing value, a list, a timestamp object).
-        def written_value(value)
-          case value
-          when Runtime::Value then written_value(value.to_h)
-          when Hash           then value.to_h { |key, inner| [key.to_s, written_value(inner)] }
-          when String, Integer, Float, true, false then value
-          end
-        end
-
-        # Replaces the generated arguments of a query step with a remembered
-        # row's, most of the time. Only a parameter the step already carries
-        # is replaced, so an optional argument left out, or a required one a
-        # malformation dropped, stays that way.
-        def bind_to_written_row!(args, entry)
-          return if entry[:entity]
-
-          rows   = @written_rows[entry[:verb].split(".").first]
-          params = bound_fields(entry[:query]).select { |param, _| args.key?(param) }
-          return if rows.empty? || params.empty?
-          return unless @binding_random.rand < BOUND_QUERY_PROBABILITY
-
-          row = rows.select { |candidate| params.values.any? { |field| candidate.key?(field) } }
-                    .sample(random: @binding_random)
-          params.each do |param, field|
-            args[param] = shaped_like(args[param], row[field]) if row&.key?(field)
-          end
-        end
-
-        # A single-field value object is written `{"value" => x}` but may be
-        # asked with the bare `x`; keeps whichever spelling the generator
-        # already chose for this argument.
-        def shaped_like(current, written)
-          return written unless written.is_a?(Hash) && written.size == 1 && !current.is_a?(Hash)
-
-          written.values.first
-        end
-      end
-    end
-  end
-end