hecks 1.2.0 → 1.3.0

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

@@ -15,11 +15,12 @@ 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
 
-          populator = catalog[:populators].find { |p| p[:command].equal?(entry[:command]) && p[:aggregate].equal?(aggregate) }
+          populator = populator_for_entry(catalog, entry)
           return unless populator
 
-          key = "#{aggregate.hecks_name}.#{populator[:entity].hecks_name}##{parent_scalar}"
+          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
@@ -33,6 +34,51 @@ module Hecks
               (@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 — `Governance::RoleAssignment.
+        # Assign` 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
@@ -68,8 +114,8 @@ module Hecks
           pool.sample(random: @random)
         end
 
-        def pick_entity_known(aggregate_name, entity_name, parent_id)
-          pool = @entity_known_ids["#{aggregate_name}.#{entity_name}##{parent_id}"]
+        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)

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

@@ -16,10 +16,21 @@ module Hecks
 
           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

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

@@ -40,16 +40,66 @@ module Hecks
           { "query" => entry[:verb], "args" => args }
         end
 
+        # THE ADVERSARIAL LAYER SITS HERE, AND ONLY HERE — after the step's
+        # arguments and identity are fully built, BEFORE the one real
+        # dispatch this generator makes to learn what the step did, and
+        # before the step is returned as corpus data. That ordering is
+        # the whole contract: the mutated `args` are what this generator's
+        # own inline dispatch sees (so `known_ids` tracking reflects what
+        # actually happened), AND they are the bytes `Fuzzing::Replay`
+        # later hands Ruby's runtime and the bytes `JSON.generate({steps:
+        # ...})` hands the compiled Rust binary — one step, one payload,
+        # both engines. Nothing downstream of this method can tell a
+        # mutated step from an ordinary one except by reading the
+        # `"adversarial"` metadata it carries (see adversary.rb).
+        #
+        # TWO MORE DRAWS SIT RIGHT AFTER THE MUTATION, IN A FIXED ORDER —
+        # a caller (`caller_draw!`, adversary.rb: `role:`/`actor_id:` on
+        # the step, bound around this one dispatch exactly the way
+        # `Fuzzing::Replay` and `kernel/cli.rs` will later bind it) and
+        # then the dry-run coin (`{"dry_run": verb}` instead of
+        # `{"verb": verb}` — `Dispatcher#dry_run?` here, the same door on
+        # both replay sides). Order matters for the seed contract: every
+        # draw comes from the one `Random.new(seed)`, so the sequence of
+        # draws per step is what makes a seed reproducible. Both are
+        # off by default and draw nothing when off.
         def build_command_step(runtime, catalog, entry)
           args = args_for(entry[:command].attributes, entry[:aggregate])
           add_identity!(args, entry)
+          steer_grant!(args, entry, catalog)
+          mutations = adversarial_mutations!(args, entry, catalog)
+          caller, caller_note = caller_draw!(entry, catalog)
+          mutations << caller_note if caller_note
 
-          outcome = safe_call { runtime.dispatch(entry[:verb], **symbolize(args)) }
-          if outcome
-            record_outcome(catalog, entry, args)
-            @event_count += outcome.events.length
-          end
-          { "verb" => entry[:verb], "args" => args }
+          step =
+            if dry_run_draw?
+              safe_call { as_caller(caller) { runtime.dry_run?(entry[:verb], **symbolize(args)) } }
+              { "dry_run" => entry[:verb], "args" => args }
+            else
+              outcome = safe_call { as_caller(caller) { runtime.dispatch(entry[:verb], **symbolize(args)) } }
+              if outcome
+                record_outcome(catalog, entry, args)
+                @event_count += outcome.events.length
+              end
+              { "verb" => entry[:verb], "args" => args }
+            end
+          step.merge!(caller) if caller
+          step["adversarial"] = mutations unless mutations.empty?
+          step
+        end
+
+        # No RNG draw at all when the fraction is zero — the same "off is
+        # byte-identical" contract `adversarial?` keeps.
+        def dry_run_draw? = @dry_run.positive? && @random.rand < @dry_run
+
+        # `Hecks.as_caller` for exactly this block, or a bare yield — the
+        # SAME binding `Fuzzing::Replay` makes from the step's own keys
+        # later, so the generator's inline dispatch and both replays see
+        # one caller.
+        def as_caller(caller, &)
+          return yield unless caller
+
+          Hecks.as_caller(role: caller["role"], actor_id: caller["actor_id"], &)
         end
 
         def args_for(attributes, aggregate)
@@ -154,9 +204,23 @@ module Hecks
           if entry[:entity]
             parent_scalar = pick_known(aggregate.hecks_name)
             args[parent_key] = identity_shaped(aggregate, aggregate.identified_by, parent_scalar, aggregate)
-            entity_key = (entry[:entity].identified_by || :id).to_s
-            entity_scalar = pick_entity_known(aggregate.hecks_name, entry[:entity].hecks_name, parent_scalar)
-            args[entity_key] = identity_shaped(entry[:entity], entry[:entity].identified_by, entity_scalar, aggregate)
+            # ONE IDENTITY PER HOP, each drawn from the pool its OWN
+            # parent-plus-hops landed elements in (`entity_pool_key`) —
+            # a depth-1 chain draws exactly what it always did; a
+            # `Board.Card` chain draws a Board under this Workspace, then
+            # a Card under THAT Board. Flat args, one head per hop, is
+            # the legacy addressing `EntityElement#locate_chain` reads
+            # (`args[head]` per identity path); the routed `to: {
+            # aggregate:, entities: [...] }` spelling is an adversarial
+            # shape layered on top (adversary.rb), never the default.
+            scalars = [parent_scalar]
+            names   = []
+            entry[:chain].each do |piece|
+              names << piece.hecks_name
+              scalar = pick_entity_known(entity_pool_key(aggregate.hecks_name, names, scalars))
+              args[(piece.identified_by || :id).to_s] = identity_shaped(piece, piece.identified_by, scalar, aggregate)
+              scalars << scalar
+            end
           elsif entry[:command].creates?
             # A COMPOSITE IDENTITY (`identified_by` answering nil with MORE
             # THAN ONE declared path — Behaviour::Identified's own "a

data/lib/hecks/fuzzing/sequence_generator.rb

@@ -7,6 +7,7 @@ require_relative "sequence_generator/catalog"
 require_relative "sequence_generator/picker"
 require_relative "sequence_generator/step_builder"
 require_relative "sequence_generator/outcome_tracker"
+require_relative "sequence_generator/adversary"
 
 module Hecks
   module Fuzzing
@@ -28,13 +29,16 @@ module Hecks
     #
     # One concern per file beside this one: what the domain offers
     # (sequence_generator/catalog.rb), which step to try next (picker.rb),
-    # how a step is built and dispatched (step_builder.rb), and what a
-    # success taught us (outcome_tracker.rb).
+    # how a step is built and dispatched (step_builder.rb), what a
+    # success taught us (outcome_tracker.rb), and — opt-in, `adversarial:`
+    # — the argument shapes real Ruby/Rust divergences were found through
+    # (adversary.rb).
     class SequenceGenerator
       include Catalog
       include Picker
       include StepBuilder
       include OutcomeTracker
+      include Adversary
 
       # Creating commands are always eligible ; weighting them heavier (not
       # exclusively — a domain with only one or two aggregates would starve
@@ -72,8 +76,22 @@ module Hecks
       # the generating end rather than the scoring end.
       UNEXERCISED_WEIGHT = 4
 
-      def self.generate(domain_path, seed:, steps:, adapter: :memory)
-        new(domain_path, seed: seed, steps: steps, adapter: adapter).call
+      # `adversarial:` — the fraction of generated COMMAND steps (0.0..1.0)
+      # that get one deliberately adversarial argument mutation
+      # (adversary.rb — the shapes BUG#7–#16 were found through). `0.0`,
+      # the default, draws nothing extra from the seeded RNG, so a seed's
+      # output is byte-for-byte what it was before the option existed;
+      # any positive value is just as deterministic per seed, since every
+      # choice the mutation makes comes from the same `Random.new(seed)`.
+      #
+      # `role_draw:` / `dry_run:` — two more opt-in fractions with the
+      # identical contract (adversary.rb's `caller_draw!`, step_builder.rb's
+      # `dry_run_draw?`): `0.0` draws nothing, so every pinned seed is
+      # byte-for-byte what it was; `bin/qa_sweep` reads them from
+      # `QualityControlDials::ROLE_DRAW_PROBABILITY`/`DRY_RUN_FRACTION`.
+      def self.generate(domain_path, seed:, steps:, adapter: :memory, adversarial: 0.0, role_draw: 0.0, dry_run: 0.0)
+        new(domain_path, seed: seed, steps: steps, adapter: adapter, adversarial: adversarial,
+            role_draw: role_draw, dry_run: dry_run).call
       end
 
       # How many EVENTS the generated sequence actually produced — not
@@ -86,16 +104,31 @@ module Hecks
       # replay one.
       attr_reader :event_count
 
-      def initialize(domain_path, seed:, steps:, adapter: :memory)
-        @domain_path      = domain_path
-        @seed             = seed
-        @step_count       = steps
-        @adapter          = adapter
-        @random           = Random.new(seed)
-        @known_ids        = Hash.new { |h, k| h[k] = [] }
-        @entity_known_ids = Hash.new { |h, k| h[k] = [] }
-        @exercised        = Set.new
-        @event_count      = 0
+      def initialize(domain_path, seed:, steps:, adapter: :memory, adversarial: 0.0, role_draw: 0.0, dry_run: 0.0)
+        { adversarial: adversarial, role_draw: role_draw, dry_run: dry_run }.each do |name, fraction|
+          next if fraction.is_a?(Numeric) && fraction.between?(0, 1)
+
+          raise ArgumentError, "#{name}: must be a fraction between 0.0 and 1.0, got #{fraction.inspect}"
+        end
+
+        @domain_path         = domain_path
+        @seed                = seed
+        @step_count          = steps
+        @adapter             = adapter
+        @adversarial         = adversarial.to_f
+        @role_draw           = role_draw.to_f
+        @dry_run             = dry_run.to_f
+        @random              = Random.new(seed)
+        @known_ids           = Hash.new { |h, k| h[k] = [] }
+        @entity_known_ids    = Hash.new { |h, k| h[k] = [] }
+        @appended_identities = Hash.new { |h, k| h[k] = [] }
+        # ROLE => [actor ids] this sequence's own successful
+        # `Governance::RoleAssignment.Assign` steps granted — what the
+        # `actor_known` caller shape draws from (adversary.rb).
+        @granted             = Hash.new { |h, k| h[k] = [] }
+        @precedence_caller   = nil
+        @exercised           = Set.new
+        @event_count         = 0
       end
 
       def call

data/lib/hecks/fuzzing/structural_skips.rb

@@ -0,0 +1,146 @@
+module Hecks
+  module Fuzzing
+    # WHAT A "NOT GENERATED FOR THIS DOMAIN" REFUSAL IS HIDING, PER VERB.
+    #
+    # `RustConformanceHelpers#structurally_refused_verbs` drops every named
+    # query/read model the compiled Rust kernel answers "is not generated
+    # for this domain" from BOTH sides of the differential comparison —
+    # correct (the refusal is codegen's own honest "I cannot execute this
+    # construct at all", `rust/project/queries.rb`'s and `read_models.rb`'s
+    # documented boundary), but SILENT: a sweep over a domain whose every
+    # `offset`/`cursor`/`group_by`/`count`/`median` ask was dropped reads
+    # as "agreed across all steps" with nothing on the record saying how
+    # much of the domain was never compared at all. Worse, the drop keys
+    # on Rust's wording alone, so a codegen regression that started
+    # refusing a plain wheres-only query the same way would ALSO vanish
+    # into "agreed" — the exact quiet divergence the practice hunts.
+    #
+    # This module attributes each dropped verb to the constructs its OWN
+    # Ruby declaration carries, in the vocabulary `queries.rb`/
+    # `read_models.rb`'s skip reasons already use, so `bin/qa_sweep` can
+    # log one Check per sweep saying exactly which verbs were skipped and
+    # WHY — and mark it Surprised whenever a skipped verb declares nothing
+    # the dial `QualityControlDials::STRUCTURAL_REFUSAL_BOUNDARY` admits as
+    # a reason to skip (a wheres-only query on plain fields, a rooted
+    # read model with nothing but heads, a verb Ruby doesn't even declare).
+    #
+    # COARSER THAN CODEGEN'S OWN PREDICATE, ON PURPOSE. `query_where_skip_
+    # reason` decides per where clause from the field's resolved KIND
+    # (number/string/multi-member value object) — reproducing that here
+    # would be a second copy of codegen's typing rules, drifting on its
+    # own. Instead a literal-valued where is reported as `where_literal`,
+    # a family the dial admits, and only shapes with NO admitted family at
+    # all surprise. That trades some sensitivity for zero false surprises
+    # on today's corpus; the Check's observation still names every skipped
+    # verb with its constructs, so a human reading the sweep sees what was
+    # accepted and can narrow the dial when codegen grows.
+    module StructuralSkips
+      module_function
+
+      # `Query#to_h`/`ReadModel#to_h` keys that, when present and
+      # non-empty, are constructs codegen documents as (conditionally or
+      # wholly) ungenerated — the same names as the dial's own vocabulary.
+      QUERY_OPTION_KEYS      = %i[order_by limit offset cursor consistency freshness authorization inspection
+                                  index_hints scope_to].freeze
+      READ_MODEL_OPTION_KEYS = %i[wheres order_by limit offset cursor consistency freshness authorization inspection
+                                  index_hints group_by count median_field].freeze
+
+      # One entry per skipped verb: `{ verb:, constructs: [...] }`, the
+      # constructs sorted so the printed observation is stable across
+      # seeds and runs.
+      def attribute(bluebooks, verbs)
+        verbs.sort.map { |verb| { verb: verb, constructs: constructs_of(bluebooks, verb) } }
+      end
+
+      # Every skipped verb whose constructs are NOT all inside `boundary`
+      # — including a verb with no constructs at all (nothing explains the
+      # skip) and a verb Ruby never declared (`unknown`).
+      def outside_boundary(attributed, boundary)
+        admitted = boundary.map(&:to_s)
+        attributed.select { |entry| entry[:constructs].empty? || (entry[:constructs] - admitted).any? }
+      end
+
+      def constructs_of(bluebooks, verb)
+        if verb.include?("::")
+          query = find_query(bluebooks, verb)
+          return %w[unknown] unless query
+
+          query_constructs(query)
+        else
+          model = find_read_model(bluebooks, verb)
+          return %w[unknown] unless model
+
+          read_model_constructs(model)
+        end
+      end
+
+      # "Domain::Aggregate.Query" or "Domain::Aggregate.Entity.Query" — the
+      # two named-query spellings `Fuzzing::SequenceGenerator`'s catalog
+      # generates (entity queries stay one hop deep there).
+      def find_query(bluebooks, verb)
+        domain, rest = verb.split("::", 2)
+        aggregate_name, *path = rest.to_s.split(".")
+        aggregate = bluebooks[domain]&.aggregate(aggregate_name)
+        return nil unless aggregate && path.any?
+
+        owner = aggregate
+        path[0...-1].each do |entity_name|
+          owner = owner.entities.find { |entity| entity.hecks_name == entity_name }
+          return nil unless owner
+        end
+        owner.query(path.last)
+      end
+
+      # "Domain.report_name" — the bare read-model form `Dispatcher#query`
+      # routes by the absence of "::".
+      def find_read_model(bluebooks, verb)
+        domain, name = verb.split(".", 2)
+        bluebooks[domain]&.read_models&.find { |model| model.query_name.to_s == name.to_s }
+      end
+
+      def query_constructs(query)
+        spec = query.to_h
+        constructs = QUERY_OPTION_KEYS.select { |key| present?(spec[key]) }.map(&:to_s)
+        constructs << "null_semantics" if spec[:null_semantics] && spec[:null_semantics] != { mode: "native" }
+        constructs << "no_wheres" if Array(spec[:wheres]).empty?
+        constructs.concat(where_constructs(Array(spec[:wheres])))
+        constructs.uniq.sort
+      end
+
+      def read_model_constructs(model)
+        spec = model.to_h
+        constructs = READ_MODEL_OPTION_KEYS.select { |key| present?(spec[key]) }.map(&:to_s)
+        constructs << "null_semantics" if spec[:null_semantics] && spec[:null_semantics] != { mode: "native" }
+        constructs << "rootless" if model.reference_target.nil?
+        constructs.concat(where_constructs(Array(spec[:wheres])))
+        constructs.uniq.sort
+      end
+
+      # The where-clause families `query_where_skip_reason` refuses by:
+      # a `/` hop through a reference, a `.` walk into a nested field
+      # (an entity-scoped or value-object path codegen may not resolve),
+      # `none_in_state` (admitted by the vocabulary, deliberately not
+      # generated), and any literal (non-Symbol) value, whose true wire
+      # type codegen may not recover from the IR.
+      def where_constructs(wheres)
+        wheres.flat_map do |where|
+          field = where[:field].to_s
+          value = where[:value].to_s
+          families = []
+          families << "reference_hop_where" if field.include?("/")
+          families << "where_nested_field" if field.include?(".")
+          families << "where_none_in_state" if where[:op].to_s == "none_in_state"
+          families << "where_literal" unless value.start_with?(":")
+          families
+        end
+      end
+
+      def present?(value)
+        return false if value.nil? || value == false
+        return value.any? if value.respond_to?(:empty?)
+
+        true
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/sweep_depth.rb

@@ -0,0 +1,53 @@
+module Hecks
+  module Fuzzing
+    # HOW HARD ONE SWEEP FUZZES, AS A FUNCTION OF `Target.clean_streak`
+    # (qa/bluebook/quality_control.bluebook — that attribute's own comment
+    # says what the streak means). The sibling of `RotationPriority`: the
+    # ledger holds the number, `QualityControlDials::WIDENING_TIERS` holds
+    # the policy, and this module is where the two meet — a pure function
+    # of both, nothing else read.
+    #
+    # WHY THIS IS NOT IN `bin/qa_sweep` ANY MORE. It was — `WIDENING_TIERS`
+    # and `widen_for_streak` lived at the top of that script, which meant
+    # policy data lived in a script (unlike every other dial, which lives
+    # in the bluebook a human edits and reviews) and duplicated itself as
+    # prose in SKILL.md. Now the table is a dial, this is the one reader,
+    # and `bin/qa_sweep` calls it the way it already calls
+    # `RotationPriority.pick`.
+    #
+    # PURE, DELIBERATELY — the same discipline `RotationPriority` keeps:
+    # same streak in, same `[seeds, steps]` out, every time, which is what
+    # lets a human predict what a given sweep is about to do before it
+    # runs one. `tiers:` defaults to the dial but is a plain argument, so
+    # a unit spec can pass its own table with no ledger boot at all and a
+    # `bin/qa_sweep` run against a ledger that declares no dials (an
+    # isolated spec's own fixture) can fall back the same way it already
+    # does for `ADVERSARIAL_FRACTION`.
+    module SweepDepth
+      module_function
+
+      # THE FALLBACK TABLE, for a boot with no `QualityControlDials` at all
+      # — the same shape and the same three rows the dial ships with, so a
+      # dial-less ledger fuzzes exactly as a dialled one does by default.
+      # Never read when the dial exists; `bin/qa_sweep` passes the dial in.
+      DEFAULT_TIERS = [
+        { upto: 4,               seeds: 10, steps: 25 },
+        { upto: 19,              seeds: 25, steps: 50 },
+        { upto: Float::INFINITY, seeds: 50, steps: 100 }
+      ].freeze
+
+      # `[seeds, steps]` for one streak. The first row whose `upto` the
+      # streak does not exceed wins — rows are read in order, so the table
+      # must be ascending, and the last row's `Float::INFINITY` is what
+      # makes it the ceiling rather than a gap.
+      def for_streak(streak, tiers: DEFAULT_TIERS)
+        raise ArgumentError, "streak must not be negative" if streak.negative?
+
+        tier = tiers.find { |row| streak <= row[:upto] }
+        raise ArgumentError, "no tier covers a streak of #{streak} — the last row must be upto: Float::INFINITY" unless tier
+
+        [tier[:seeds], tier[:steps]]
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/target_capabilities.rb

@@ -0,0 +1,149 @@
+module Hecks
+  module Fuzzing
+    # WHAT A SWEEP TARGET CAN ACTUALLY BE CHECKED FOR, read off the
+    # filesystem — never off a stored list.
+    #
+    # `bin/qa_sweep` used to decide its ONE comparison mode inline: "is
+    # there a Cargo feature named after this directory? then
+    # `:differential`, else `:ruby_only`", and a separate hand-typed abort
+    # for `--persistence-parity` ("does any .hecksagon bind PostgresEra?").
+    # Every further mode the practice adds (era boundary, concurrency, a
+    # WASM front) would have grown one more inline `if`, each one a
+    # policy decision hiding in a script. This module is those decisions
+    # as DATA: `MODE_REQUIREMENTS` says which capabilities each mode
+    # needs, `infer` says which capabilities a target's own directory
+    # actually has, and `resolve` is the one rule that joins them —
+    # `modes_to_run = enabled ∩ eligible`.
+    #
+    # INFERENCE DECIDES; A STORED LIST ONLY RECORDS. `Target.capabilities`
+    # (qa/bluebook/quality_control.bluebook, once PR-1's era lands) is
+    # written by the runner from exactly this inference at release time
+    # so `Target.EligibleFor(mode)` can AUDIT the rotation from the
+    # ledger alone — but the runner re-infers every sweep, because a
+    # stored list that lags yesterday's Cargo feature is precisely the
+    # "quiet divergence" (the chapter's own opening comment) this whole
+    # practice exists to hunt. Nothing here ever reads the ledger.
+    #
+    # EVERY REGEX IS ONE THE HARNESS ALREADY OWNED, moved here rather than
+    # re-derived, and each one's provenance is named beside it so a
+    # future edit to the original site is a visible drift, not a silent
+    # one: the Cargo feature line (`RustConformanceHelpers#build_rust_for`),
+    # the PostgresEra binding (`bin/qa_sweep`'s old `POSTGRES_ERA_BINDING`),
+    # the translations glob (`IsolatedBoot#strip_translations!`).
+    module TargetCapabilities
+      module_function
+
+      # `RustConformanceHelpers#build_rust_for`'s own test, scoped to the
+      # `[features]` table the way `bin/project_rust`'s Cargo sync scopes
+      # its own lookup (a `[package] name = "rust"` line must never read
+      # as a feature named `rust`).
+      FEATURES_TABLE = /^\[features\](?:\n(?!\[).*)*$/
+
+      # `bin/qa_sweep`'s former `POSTGRES_ERA_BINDING` — both spellings
+      # `IsolatedBoot#rewrite_bindings!` has to catch: aggregate-scoped
+      # (`Directory::Member.persisted_by("PostgresEra")`) and the bare
+      # domain-level default (`persisted_by "PostgresEra"`).
+      POSTGRES_ERA_BINDING = /persisted_by\s*\(?\s*"PostgresEra"/
+
+      # `HecksagonBuilder#uses_framework` — the one line that attaches
+      # Governance's own `RoleAssignment` lookup to a domain's `role` checks
+      # (`CommandRules::Authorization#governance_attached?`).
+      GOVERNANCE_ATTACHED = /uses_framework\s*\(?\s*"Governance"/
+
+      # A command-level `role "..."` — the only construct
+      # `refuse_role_mismatch` ever has anything to check a caller against.
+      ROLE_GATED = /^\s*role\s+"/
+
+      # `authorize :vault_access, tenant: :branch_code`
+      # (examples/banking/bluebook/safe_deposit_boxes.bluebook) — the one
+      # `tenant:` spelling the corpus has.
+      TENANT_SCOPED = /\btenant:/
+
+      PROCESS_MANAGER = /^\s*process_manager\s+"/
+
+      # WHICH CAPABILITIES EACH MODE NEEDS BEFORE IT CAN SAY ANYTHING TRUE
+      # ABOUT A TARGET. An empty list means "any target at all" — every
+      # domain boots under Memory, so Ruby-only properties and the
+      # self-consistency pass are always answerable. `ruby_only` is listed
+      # requirement-free on purpose and then EXCLUDED by `resolve` whenever
+      # `differential` resolved too: they are the same seat, and a compiled
+      # Rust binary is strictly the better occupant (item 1 of the
+      # detection plan folded the Ruby-only property battery INTO the
+      # differential seat, so nothing is lost by the exclusion).
+      #
+      # The four `false`-by-default modes in `QualityControlDials::MODES`
+      # (`adapter_parity_postgres`, `era_boundary`, `concurrency`,
+      # `wasm_front`) are named here with their requirements even though
+      # nothing runs them yet — so `resolved modes:` can already say, per
+      # target, which of them WOULD be eligible the day a human flips the
+      # dial, and so flipping it is a one-line data change rather than a
+      # code change plus a data change.
+      MODE_REQUIREMENTS = {
+        differential:               %w[rust],
+        ruby_only:                  [],
+        self_consistency:           [],
+        properties_in_differential: %w[rust],
+        structural_skip_report:     %w[rust],
+        adapter_parity_sqlite:      %w[sqlite],
+        persistence_parity:         %w[postgres_era],
+        adapter_parity_postgres:    %w[postgres_era],
+        era_boundary:               %w[translations postgres_era],
+        concurrency:                %w[postgres_era],
+        wasm_front:                 %w[rust]
+      }.freeze
+
+      # MODES THAT NAME A SEPARATE, EXPENSIVE PASS OF THEIR OWN rather than
+      # an extra check folded into the ordinary per-seed loop —
+      # `bin/qa_sweep` runs these only when asked by name (`--modes
+      # persistence_parity`, or its older alias `--persistence-parity`) or
+      # as `--all`'s own second wave, never silently inside a plain
+      # single-target sweep (the seed cap `PERSISTENCE_PARITY_SEED_CAP`
+      # exists because that pass pays for real Postgres I/O per dispatch).
+      DEFERRED_MODES = %i[persistence_parity adapter_parity_postgres era_boundary concurrency].freeze
+
+      # Sorted, plain strings — comma-joined by the runner into the
+      # `Target.Release(capabilities:)` value object and printed verbatim
+      # on the `resolved modes:` line, so the same spelling is what a
+      # human reads, what `--all` parses back, and what the ledger stores.
+      def infer(domain_path, rust_dir: File.expand_path("../../../rust", __dir__))
+        capabilities = %w[sqlite]
+        capabilities << "rust" if rust_feature?(domain_path, rust_dir)
+        capabilities << "postgres_era" if any_file?(domain_path, "*.hecksagon", POSTGRES_ERA_BINDING)
+        capabilities << "translations" if Dir.glob(File.join(domain_path, "**", "translations", "*.bluebook")).any?
+        capabilities << "governance" if any_file?(domain_path, "*.hecksagon", GOVERNANCE_ATTACHED)
+        capabilities << "role_gated" if any_file?(domain_path, "*.bluebook", ROLE_GATED)
+        capabilities << "tenant" if any_file?(domain_path, "*.bluebook", TENANT_SCOPED)
+        capabilities << "sagas" if any_file?(domain_path, "*.bluebook", PROCESS_MANAGER)
+        capabilities.sort
+      end
+
+      def eligible?(mode, capabilities)
+        required = MODE_REQUIREMENTS.fetch(mode.to_sym) { raise ArgumentError, "unknown sweep mode #{mode.inspect}" }
+        (required - capabilities).empty?
+      end
+
+      # THE ONE RULE. `enabled` is whatever the dial (or `--modes`) turned
+      # on, in the dial's own declaration order — that order is preserved
+      # so the printed line reads the same way the dial does. Then the
+      # single exclusion named on `MODE_REQUIREMENTS`.
+      def resolve(enabled, capabilities)
+        resolved = enabled.map(&:to_sym).select { |mode| eligible?(mode, capabilities) }
+        resolved.delete(:ruby_only) if resolved.include?(:differential)
+        resolved
+      end
+
+      def rust_feature?(domain_path, rust_dir)
+        cargo_toml = File.join(rust_dir, "Cargo.toml")
+        return false unless File.file?(cargo_toml)
+
+        feature  = File.basename(domain_path).downcase
+        features = File.read(cargo_toml)[FEATURES_TABLE] || ""
+        features.match?(/^#{Regexp.escape(feature)}\s*=\s*\[\]/)
+      end
+
+      def any_file?(domain_path, glob, pattern)
+        Dir.glob(File.join(domain_path, "**", glob)).any? { |path| File.read(path).match?(pattern) }
+      end
+    end
+  end
+end