hecks 1.2.0 → 1.4.0

data/lib/hecks/fuzzing/rotation_priority.rb

@@ -0,0 +1,94 @@
+module Hecks
+  module Fuzzing
+    # The weighted half of `QualityControl::Target.Rotation`
+    # (qa/bluebook/quality_control.bluebook) — see that query's own
+    # comment for why the ledger itself still only offers
+    # least-recently-swept order: `order_by` sorts by exactly one stored
+    # field, and a target's actual rotation priority wants two blended
+    # together (time since last swept, and recent yield), which nothing
+    # in the query sublanguage can express. `Rotation` stays the raw
+    # view; this module is where the blend actually happens, against the
+    # rows that query already returns.
+    #
+    # **Pure, deliberately**. Every method here is a function of its own
+    # arguments only — no clock read, no query dispatched, nothing
+    # random — so this is unit-testable with plain hashes and no ledger
+    # boot at all, and reruns identically given the same rotation, the
+    # same `now` and the same dials. `now` arrives as an argument for
+    # the exact reason `Target.Claim`'s own comment already gives: a
+    # pure function cannot ask the time, so whoever calls this supplies
+    # it, exactly as it supplies an id.
+    #
+    # Where this actually matters, and where it does not — checked
+    # against `bin/qa_sweep`'s own code, not assumed. `bin/qa_sweep
+    # --all` sweeps every currently-waiting target in one pass,
+    # regardless of order (`run_all_mode`'s own `waiting.map { spawn_
+    # sweep_child }` — every element the query returned, never
+    # `.first`), so nothing about this module's own ordering changes
+    # what `--all` does; it already sweeps everything the ledger has to
+    # offer. What it changes is `bin/qa_sweep` invoked with no target
+    # argument, which today picks exactly one target via `Target.
+    # Rotation.first` — wiring `.pick` in there instead is this module's
+    # one real caller, and (per the same investigation) its only one:
+    # there is no separate scheduling or concurrency-limit mechanism
+    # elsewhere in this repository for it to feed instead.
+    module RotationPriority
+      module_function
+
+      # The next stored `Target.yield_score` — decay what survives from
+      # before, then add whatever this just-concluded period actually
+      # found. Integer division, like every other count in this ledger
+      # (`Sweep.CheckCount`, `Bug.BugOrder`): a yield score is a
+      # priority signal, not a precise statistic, and a fractional score
+      # would need a value object this ledger does not have.
+      #
+      # `decay_percent` defaults to the dial, not a literal, so a caller
+      # that does not care still gets the practice's own current answer
+      # to "how much of this is 'recent'" rather than a second, silently
+      # drifting copy of the same number.
+      def next_yield_score(old_score:, surprises_this_period:,
+                           decay_percent: QualityControlDials::YIELD_DECAY_PERCENT)
+        raise ArgumentError, "old_score must not be negative" if old_score.negative?
+        raise ArgumentError, "surprises_this_period must not be negative" if surprises_this_period.negative?
+
+        ((old_score * decay_percent) / 100) + surprises_this_period
+      end
+
+      # The pick itself. `rows` is whatever `Target.Rotation` returned —
+      # each row a hash carrying at least `:last_swept` and
+      # `:yield_score`, both `{ value: Integer }`, the shape every
+      # VO-typed field in this ledger already comes back as. Returns
+      # `nil` for an empty rotation, the same "nothing waiting" case
+      # `bin/qa_sweep` already handles by seeding the default targets.
+      #
+      # The floor wins outright — no starvation, on purpose (see
+      # `QualityControlDials::ROTATION_STALE_FLOOR_SECONDS`'s own
+      # comment for why a floor and not a total exclusion). A row stale
+      # past `floor_seconds` is picked ahead of every row that is not,
+      # oldest-first among however many have crossed it — the same
+      # tiebreak `Rotation` itself already uses for everything, which
+      # keeps the floor from becoming a new source of starvation between
+      # two long-neglected targets.
+      #
+      # Below the floor, highest combined score wins. `staleness +
+      # (yield_score * weight_seconds)` — plain addition, never a ratio
+      # or anything that could divide by zero, and the units are
+      # deliberately the same (seconds) so `weight_seconds` reads as
+      # "how many seconds of extra staleness one point of yield is
+      # worth" rather than an opaque multiplier nobody could sanity
+      # check by eye.
+      def pick(rows, now:, weight_seconds: QualityControlDials::YIELD_WEIGHT_SECONDS,
+               floor_seconds: QualityControlDials::ROTATION_STALE_FLOOR_SECONDS)
+        return nil if rows.empty?
+
+        floored = rows.select { |row| staleness(row, now) >= floor_seconds }
+        return floored.min_by { |row| row[:last_swept][:value] } unless floored.empty?
+
+        rows.max_by { |row| staleness(row, now) + (row[:yield_score][:value] * weight_seconds) }
+      end
+
+      def staleness(row, now) = now - row[:last_swept][:value]
+      private_class_method :staleness
+    end
+  end
+end

data/lib/hecks/fuzzing/rust_gap_manifest.rb

@@ -0,0 +1,113 @@
+require "json"
+require "hecks/naming"
+
+module Hecks
+  module Fuzzing
+    # What a compiled Rust binary declares it did not generate — read off the
+    # `manifest.json` files `rust/project/domain_generator.rb` writes beside
+    # every generated module, never inferred from Rust's refusal wording.
+    #
+    # The differential fuzzer (`Differential.diff`) used to drop any refusal
+    # whose Rust error contained "is not generated for this domain". That
+    # tolerated whatever Rust happened to say, including a codegen regression
+    # that started refusing a construct it used to generate. Now a query or
+    # read-model verb is dropped from the comparison if and only if the
+    # generator's own manifest recorded it as `generated: false`, with the
+    # `gap_class` and `construct` that explain why. A refusal the manifest
+    # does not account for stays in the comparison and fails it.
+    #
+    # **Which manifests describe a binary**. `build_and_pin` (spec/support/
+    # rust_conformance_helpers.rb) and `bin/qa_generated_domains` both pin a
+    # feature's binary at `<rust_dir>/target/debug/rust-<feature>`. That
+    # binary compiles `src/generated/<feature>/` plus every shared framework
+    # chapter (a generated directory with no `merged.rs` of its own —
+    # `governance`, `identity`; see the generated `mod.rs` header). Ids in
+    # those manifests are domain-qualified, so a chapter a domain never
+    # attaches contributes entries no sequence for that domain can name.
+    #
+    # **A missing manifest tolerates nothing**. A hand-written fixture crate, or
+    # a tree generated before manifests existed, has no declaration to
+    # honour, so every refusal it produces is compared as-is. That is the
+    # fail-closed direction.
+    class RustGapManifest
+      # The only kinds the kernel answers as a query step. A not-generated
+      # command changes state, so dropping its refusal would not make the
+      # comparison honest; those stay compared and fail.
+      TOLERABLE_KINDS = %w[query read_model].freeze
+      PINNED_BINARY = %r{\A(?<rust_dir>.+)/target/debug/rust-(?<feature>[a-z0-9_]+)\z}
+
+      attr_reader :rust_dir, :feature, :entries
+
+      def self.for_binary(binary)
+        match = PINNED_BINARY.match(File.expand_path(binary.to_s))
+        unless match
+          raise ArgumentError, "#{binary.inspect} is not a pinned conformance binary " \
+                               "(<rust_dir>/target/debug/rust-<feature>) — cannot tell which manifest describes it"
+        end
+
+        new(rust_dir: match[:rust_dir], feature: match[:feature])
+      end
+
+      # Every committed manifest entry under `rust_dir`, each tagged with the
+      # generated module it came from — what the boundary ratchet and
+      # bin/rust_coverage's allowlist staleness check read.
+      def self.all_entries(rust_dir)
+        Dir.glob(File.join(rust_dir, "src/generated/*/manifest.json")).flat_map do |path|
+          module_name = File.basename(File.dirname(path))
+          JSON.parse(File.read(path)).map { |entry| entry.merge("module" => module_name) }
+        end
+      end
+
+      def initialize(rust_dir:, feature:)
+        @rust_dir = rust_dir
+        @feature  = feature
+        @entries  = manifest_paths.flat_map { |path| JSON.parse(File.read(path)) }.freeze
+        @not_generated = index_not_generated
+      end
+
+      # The manifest entry that declares `verb` not generated, or nil. `verb`
+      # is the wire spelling a sequence step uses; an ad hoc filter (a Hash)
+      # is never declared and answers nil.
+      def not_generated(verb)
+        return nil unless verb.is_a?(String)
+
+        @not_generated[verb]
+      end
+
+      def not_generated?(verb) = !not_generated(verb).nil?
+
+      def not_generated_verbs = @not_generated.keys.to_set
+
+      private
+
+      def manifest_paths
+        generated = File.join(rust_dir, "src/generated")
+        own = File.join(generated, feature, "manifest.json")
+        chapters = Dir.glob(File.join(generated, "*/manifest.json")).reject do |path|
+          dir = File.dirname(path)
+          File.basename(dir) == feature || File.exist?(File.join(dir, "merged.rs"))
+        end
+        ([own] + chapters.sort).select { |path| File.exist?(path) }
+      end
+
+      def index_not_generated
+        @entries.each_with_object({}) do |entry, index|
+          next unless TOLERABLE_KINDS.include?(entry["kind"]) && entry["generated"] == false
+
+          wire_verbs(entry).each { |verb| index[verb] = entry }
+        end.freeze
+      end
+
+      # A query is asked by its id. A read model's id is "Domain::Name", but
+      # it is asked as "Domain.Name" or "Domain.name_in_snake_case" — the two
+      # spellings `kernel::read_model::find` accepts (`matches_snake_alias`,
+      # a port of `Hecks::Naming.snake`).
+      def wire_verbs(entry)
+        return [entry["id"]] if entry["kind"] == "query"
+
+        domain, name = entry["id"].split("::", 2)
+        ["#{domain}.#{name}", "#{domain}.#{Hecks::Naming.snake(name)}"].uniq
+      end
+    end
+  end
+end