hecks 1.2.0 → 1.3.0

data/lib/hecks/fuzzing/replay.rb

@@ -1,6 +1,7 @@
 require "fileutils"
 require "tmpdir"
 require_relative "isolated_boot"
+require_relative "self_consistency"
 require_relative "../query_specification/common/comparators"
 require_relative "../query_specification/common/where_clause"
 require_relative "../query_specification/field_path"
@@ -71,20 +72,41 @@ module Hecks
       # rubocop:disable-next Metrics/CyclomaticComplexity
       # rubocop:disable-next Metrics/MethodLength
       # rubocop:disable-next Metrics/PerceivedComplexity
-      def call(domain_path, steps, adapter: :memory)
+      # `self_consistency:` — OFF by default, same "existing callers see no
+      # change" contract `adapter:` already has. `bin/qa_sweep` is the one
+      # real caller that opts in (gated by `QualityControlDials::
+      # SELF_CONSISTENCY_CHECKS`/`--self-consistency`): `bin/fuzz`,
+      # `Properties.check`'s own callers, and every existing spec keep
+      # calling this with no second axis of comparison at all, exactly as
+      # before. Computed HERE, not by a caller reading `runtime` back out
+      # afterward — `runtime` and the whole `IsolatedBoot` tmp directory
+      # go out of scope the moment this method returns (see this file's
+      # own header), so `Hecks::Fuzzing::SelfConsistency.check` has to run
+      # while both are still alive, against the exact same repositories
+      # this replay's own dispatch loop just wrote to.
+      #
+      # `database:`/`schema:` — ONLY meaningful, and REQUIRED, for
+      # `adapter: :postgres_era` — see `IsolatedBoot#rebind_to_postgres_era!`'s
+      # own header for why that one mode takes caller-owned connection
+      # identity rather than a shared default the way `:postgres` does.
+      # Forwarded straight through, unchanged, exactly like `adapter:`
+      # itself already was.
+      def call(domain_path, steps, adapter: :memory, database: nil, schema: nil, self_consistency: false)
         # See isolated_boot.rb's own header: resets data/ AND rebinds
         # persistence to the chosen adapter (Memory by default), since a
         # Postgres-bound domain's real store lives outside the copied
         # directory and cannot be reached by resetting data/ alone.
-        IsolatedBoot.call(domain_path, adapter: adapter) do |copy|
+        IsolatedBoot.call(domain_path, adapter: adapter, database: database, schema: schema) do |copy|
           runtime = Hecks.boot(copy)
 
           refusals        = []
           queries         = []
           dry_runs        = []
+          dry_run_traces  = []
           fan_outs        = []
           guard_checks    = []
           mutation_traces = []
+          outbox_traces   = []
 
           # EVERY AGGREGATE A `for_each` COULD EVER QUERY, resolved ONCE —
           # `[domain, aggregate_name]` pairs, gleaned from every loaded
@@ -181,13 +203,38 @@ module Hecks
             # `{"dry_run": verb, "args": …}` — `Dispatcher#dry_run?`: the command
             # evaluated hypothetically, nothing saved or emitted, no reaction.
             # Recorded, never a refusal: a refused dry run is an ANSWER.
+            #
+            # `dry_runs` STAYS EXACTLY `{verb:, ok:, error?:}` — the SAME
+            # shape it always had, and the SAME shape `kernel/cli.rs`'s own
+            # `dry_run` answers (`{"verb", "ok"}` or `{"verb", "ok": false,
+            # "error"}`, that function's own doc comment) — `spec/rust_
+            # conformance_spec.rb` compares this array against the compiled
+            # binary's own verbatim, so it can never carry a key Rust's own
+            # answer does not. The role-gated binding (`as_step_caller`,
+            # the SAME `role:`/`actor_id:` a real dispatch gets below) still
+            # applies to the dry-run call itself — only what gets RECORDED
+            # about it is unchanged.
+            #
+            # `dry_run_traces` — A SEPARATE, PARALLEL array (same order,
+            # not merged into `dry_runs` above) carrying `before:`/`after:`
+            # snapshots of the whole observable store (every instance, the
+            # event count) on either side of the hypothetical call, so
+            # `Properties.dry_runs_leave_no_trace` can hold `Dispatcher
+            # #dry_run?`'s own contract to the store rather than trusting
+            # it. Ruby's own oracle data — Rust has nothing to compare it
+            # against, so it stays out of the compared surface entirely.
             if (hypothetical = step["dry_run"])
+              before = { instances: snapshot_instances(runtime), events: runtime.events.size }
+              entry  = { verb: hypothetical }
               begin
-                runtime.dry_run?(hypothetical, **args)
-                dry_runs << { verb: hypothetical, ok: true }
+                as_step_caller(step) { runtime.dry_run?(hypothetical, **args) }
+                entry[:ok] = true
               rescue *Runtime::DOMAIN_REFUSALS, Bluebook::Expression::EvaluationError => e
-                dry_runs << { verb: hypothetical, ok: false, error: e.message }
+                entry.merge!(ok: false, error: e.message)
               end
+              after = { instances: snapshot_instances(runtime), events: runtime.events.size }
+              dry_runs << entry
+              dry_run_traces << entry.merge(before: before, after: after)
               next
             end
 
@@ -203,6 +250,32 @@ module Hecks
               # named ask.
               reaction_mark = runtime.reactions.size
 
+              # THE OUTBOX ORACLE'S OWN LOW-WATER MARKS — taken before
+              # dispatch, same idiom as `reaction_mark` right above:
+              # `saga_log_mark` slices `runtime.sagas` (a single flat
+              # array, safe to index into directly) the identical way
+              # `reaction_mark` already slices `runtime.reactions`.
+              # `outbox_before_ids` is a SET OF delivery_ids, not a
+              # size — `runtime.outbox.rows` concatenates every bound
+              # repository's own array in a FIXED per-store order
+              # (`Outbox::Relay#rows`, `stores.flat_map`), so a row a
+              # DIFFERENT step's dispatch enqueues into an
+              # earlier-iterated store would land in the MIDDLE of
+              # that concatenated list, not at its tail — a plain
+              # "grew from N to M, take the tail" slice (the shape
+              # `reaction_mark`/`saga_log_mark` both get away with,
+              # since `reaction_log`/`saga_log` are each already ONE
+              # flat array irrespective of domain) would silently miss
+              # or misattribute rows the moment more than one
+              # repository has an outbox. `delivery_id` is unique per
+              # store by construction (`Row#to_h`'s own header;
+              # `hecks_outbox`'s `UNIQUE` column in the Postgres/Sqlite
+              # DDL, `outbox_enqueue`'s own de-dup check in Memory), so
+              # membership in this set is exactly "existed before this
+              # step's own dispatch ran."
+              saga_log_mark      = runtime.sagas.size
+              outbox_before_ids  = runtime.outbox.rows.map(&:delivery_id)
+
               # THE SNAPSHOT A `for_each` QUERY WOULD HAVE SEEN — taken
               # BEFORE this step's own dispatch, not after. The real
               # `deliver_for_each` runs its query SYNCHRONOUSLY, inside
@@ -249,22 +322,41 @@ module Hecks
               # all, or one whose identity args don't resolve).
               mutation_trace = build_mutation_trace(runtime, step["verb"], args)
 
-              # `role:` — an OPTIONAL per-step key, absent on every one of
-              # the 231 existing `spec/corpus/*.json` steps (their own
+              # `role:`/`actor_id:` — OPTIONAL per-step keys, absent on every
+              # one of the 231 existing `spec/corpus/*.json` steps (their own
               # unwrapped `runtime.dispatch` call, unchanged, so nothing
               # already pinned changes behavior). Binds the SAME ambient
               # caller `refuse_role_mismatch` reads (`Hecks.as_caller`,
               # `Runtime::Caller.as`) for exactly the one dispatch this
               # step makes, then unbinds — mirrors `Caller.as`'s own
               # `ensure`-restore, so back-to-back steps with different (or
-              # no) `role:` never leak into each other.
-              result = if step["role"]
-                         Hecks.as_caller(role: step["role"]) { runtime.dispatch(step["verb"], **args) }
-                       else
-                         runtime.dispatch(step["verb"], **args)
-                       end
+              # no) `role:` never leak into each other. `actor_id:` is the
+              # sibling `kernel/cli.rs` already read (its own comment on
+              # the key): with it, a Governance-attached domain runs the
+              # real `holds_role?` lookup instead of the string fallback.
+              result = as_step_caller(step) { runtime.dispatch(step["verb"], **args) }
 
               fan_outs.concat(fan_out_findings(runtime, fan_out_snapshot, result.events, runtime.reactions[reaction_mark..]))
+
+              # THE OUTBOX ORACLE'S OWN CAPTURE — every outbox row THIS
+              # STEP'S OWN dispatch newly wrote (across every bound
+              # repository, including any a reaction cascade touched —
+              # `outbox_before_ids` was taken before `dispatch`, which
+              # is the same call that runs the whole cascade
+              # synchronously, `reenter` included), paired with the
+              # `reaction_log`/`saga_log` rows that same dispatch
+              # produced. Skipped entirely when empty — a step whose
+              # own aggregate has no outbox enqueues nothing here, and
+              # there is nothing for `Properties.outbox_rows_match_
+              # reactions` to check for it (its own reactions, if any,
+              # went through the direct, pre-outbox path instead).
+              outbox_new_rows = runtime.outbox.rows.reject { |row| outbox_before_ids.include?(row.delivery_id) }
+              if outbox_new_rows.any?
+                outbox_traces << { verb: step["verb"], rows: outbox_new_rows.map(&:to_h),
+                                    reactions: runtime.reactions[reaction_mark..].dup,
+                                    sagas: runtime.sagas[saga_log_mark..].dup }
+              end
+
               guard_checks << guard_check.merge(actual_refused: false, actual_kind: nil) if guard_check
               # AFTER — only on SUCCESS ; a refused step mutated nothing,
               # so there is no "after" to compare (and #build_mutation_
@@ -346,16 +438,34 @@ module Hecks
           # whichever one happened to load first. A property that needs
           # to resolve a verb back to its OWN declaring bluebook — not
           # "the" bluebook — reads this instead.
-          { instances: instances, events: events, refusals: refusals,
-            reactions: runtime.reactions, sagas: runtime.sagas, saga_instances: saga_instances,
-            queries: queries, dry_runs: dry_runs, fan_outs: fan_outs, guard_checks: guard_checks,
-            mutation_traces: mutation_traces,
-            saga_dispatches: runtime.saga_dispatches, policy_dispatches: runtime.policy_dispatches,
-            bluebook: runtime.registry.bluebooks.values.first,
-            bluebooks: runtime.registry.bluebooks.dup }
+          history = { instances: instances, events: events, refusals: refusals,
+                      reactions: runtime.reactions, sagas: runtime.sagas, saga_instances: saga_instances,
+                      queries: queries, dry_runs: dry_runs, dry_run_traces: dry_run_traces,
+                      fan_outs: fan_outs, guard_checks: guard_checks,
+                      mutation_traces: mutation_traces, outbox_traces: outbox_traces,
+                      saga_dispatches: runtime.saga_dispatches, policy_dispatches: runtime.policy_dispatches,
+                      bluebook: runtime.registry.bluebooks.values.first,
+                      bluebooks: runtime.registry.bluebooks.dup }
+
+          # `runtime` IS STILL LIVE HERE — this is the one and only place
+          # it is. See `SelfConsistency`'s own header for why this needs
+          # to happen NOW, against the SAME registry/repositories this
+          # replay's own dispatch loop just populated, not a second boot.
+          history[:self_consistency] = SelfConsistency.check(runtime, history) if self_consistency
+
+          history
         end
       end
 
+      # A step with no `role:` dispatches exactly as every corpus step
+      # always has — bare, no caller bound at all (`Caller.current` nil,
+      # so `refuse_role_mismatch` returns before checking anything).
+      def as_step_caller(step, &)
+        return yield unless step["role"]
+
+        Hecks.as_caller(role: step["role"], actor_id: step["actor_id"], &)
+      end
+
       # THE GUARD ORACLE'S OWN RESOLUTION — "which record, if any, is
       # this step about, and would enforce_givens/enforce_lifecycle_guard
       # have refused it against that record's PRE-DISPATCH state" —

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