hecks 2.7.0 → 2.8.0

data/lib/hecks/fuzzing/rotation_priority.rb

@@ -1,114 +0,0 @@
-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.
-      #
-      # @param old_score [Integer] the target's `Target.yield_score` before this period
-      # @param surprises_this_period [Integer] how many Surprised checks this period found
-      # @param decay_percent [Integer] percent of `old_score` that survives into the new
-      #   score; defaults to `QualityControlDials::YIELD_DECAY_PERCENT`
-      # @return [Integer] the next `Target.yield_score` to store
-      # @raise [ArgumentError] if `old_score` is negative
-      # @raise [ArgumentError] if `surprises_this_period` is negative
-      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.
-      #
-      # @param rows [Array<Hash>] rows from `Target.Rotation`, each carrying at least
-      #   `:last_swept` and `:yield_score` as `{ value: Integer }`
-      # @param now [Integer] the current time, Unix epoch seconds
-      # @param weight_seconds [Integer] seconds of extra staleness one point of yield is
-      #   worth; defaults to `QualityControlDials::YIELD_WEIGHT_SECONDS`
-      # @param floor_seconds [Integer] staleness, in seconds, past which a row is picked
-      #   ahead of every row not yet that stale; defaults to
-      #   `QualityControlDials::ROTATION_STALE_FLOOR_SECONDS`
-      # @return [Hash, nil] the picked row, or `nil` if `rows` is empty
-      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

@@ -1,139 +0,0 @@
-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`) drops a query or
-    # read-model verb 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 — never by pattern-matching Rust's
-    # refusal wording ("is not generated for this domain"), which would
-    # tolerate whatever Rust happened to say, including a codegen
-    # regression that silently started refusing a construct it once
-    # generated. 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
-
-      # Builds the manifest reader for the pinned conformance binary at `binary`.
-      #
-      # @param binary [String] path to a pinned binary, `<rust_dir>/target/debug/rust-<feature>`
-      # @return [Fuzzing::RustGapManifest] the manifest reader for that binary's feature
-      # @raise [ArgumentError] if `binary` does not match the pinned-binary path shape
-      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.
-      #
-      # @param rust_dir [String] path to the Rust project root (holds `src/generated/*/`)
-      # @return [Array<Hash>] every `src/generated/*/manifest.json` entry, each a
-      #   String-keyed manifest Hash plus `"module" => String` naming the directory it came from
-      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
-
-      # @param rust_dir [String] path to the Rust project root (holds `src/generated/*/`)
-      # @param feature [String] the domain feature this manifest reader describes
-      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.
-      #
-      # @param verb [String, Object] the wire-spelled query or read-model verb to look up
-      # @return [Hash, nil] the String-keyed manifest entry declaring `verb` not generated,
-      #   or nil if `verb` is not a String or no entry declares it
-      def not_generated(verb)
-        return nil unless verb.is_a?(String)
-
-        @not_generated[verb]
-      end
-
-      # Answers whether `verb` is declared not generated by this manifest.
-      #
-      # @param verb [String, Object] the wire-spelled query or read-model verb to look up
-      # @return [Boolean] whether the manifest declares `verb` not generated
-      def not_generated?(verb) = !not_generated(verb).nil?
-
-      # Lists every verb this manifest declares not generated.
-      #
-      # @return [Set<String>] every verb the manifest declares not generated
-      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