hecks 2.7.0 → 2.9.0

data/lib/hecks/fuzzing/properties/outbox.rb

@@ -1,180 +0,0 @@
-require_relative "../../bluebook/expression/evaluator"
-
-module Hecks
-  module Fuzzing
-    module Properties
-      # The transactional outbox's own contract (`Runtime::Outbox`, that
-      # file's own header), held to the history a replay actually produced
-      # rather than trusted. Two facts, each independently checkable from
-      # `history[:outbox_traces]` (`Replay#call`'s own before/after
-      # capture, one entry per step whose dispatch enqueued at least one
-      # row):
-      #
-      # ## The two checks
-      #
-      #   1. "delivery is inline by default" — a row this replay's own
-      #      dispatch enqueued must not still be `pending`/`claimed` once
-      #      that same call returns (nothing here ever simulates a
-      #      crash), and must not be `failed` either — `deliver_row`'s
-      #      own rescue only reaches `failed` for a genuine defect in the
-      #      relay's own consumer resolution (a row naming a policy/
-      #      process_manager `run_consumer`'s own independent registry
-      #      lookup cannot find — `WiringError`), never an ordinary
-      #      domain refusal (`PolicyInterpreter#deliver`/`SagaInterpreter#
-      #      advance` both rescue those themselves, recording `delivered:
-      #      false` on the reaction/saga log and letting `run_consumer`
-      #      return normally). Both checked for every row, `saga:` and
-      #      `policy:` alike.
-      #
-      #   2. A `policy:` row specifically — `PolicyInterpreter#deliver`
-      #      returns `nil` (no `reaction_log` entry appended at all)
-      #      exactly when its own `where` (or, for a fan-out policy, the
-      #      same `where`, gating the whole `for_each`) does not hold;
-      #      every other outcome (delivered, refused, a defect,
-      #      reaction-depth-reached) is still a non-nil record `#react`
-      #      appends. So a `delivered` policy row with no matching
-      #      `reaction_log` entry is legitimate only when that policy's
-      #      own `where`, independently re-evaluated here against the
-      #      row's own recorded event, genuinely does not hold. A
-      #      `for_each` policy's own fan-out correctness (how many rows
-      #      it should have dispatched to) is `fanout_dispatches_once_
-      #      per_matching_row`'s job, not this one's.
-      #
-      # ## Why a `saga:` row is exempt from check 2
-      #
-      # Deliberately: `Fanout.sagas`' own `listens?` (starts_on/ends_on/
-      # handler_for matching the event name alone) says nothing about
-      # whether a correlation resolves or a live instance exists, and
-      # `begin_saga`/`end_saga` (saga_interpreter.rb) both have silent,
-      # perfectly ordinary no-op paths that append nothing to `saga_log`
-      # — `begin_saga` when an instance under that correlation already
-      # exists, `end_saga` when no live instance exists to end (an
-      # `AccountOpened` fired by opening an account directly, bypassing
-      # the onboarding flow whose `ends_on` names that same event,
-      # reproduces this exactly: `Fanout.listens?` enqueues the row
-      # because the event name matches `ends_on`, `end_saga` finds
-      # nothing under that correlation to delete, and neither logs a
-      # word). A `saga:` row draining to `delivered` with zero matching
-      # `saga_log` entries is therefore not a finding — only check 1
-      # applies to it.
-      #
-      # ## Not a grammar construct
-      #
-      # `FEATURE_COVERAGE`'s own `dry_runs_leave_no_trace` precedent: the
-      # outbox is a runtime door (`Runtime::Outbox`), not a word a
-      # bluebook declares, so there is no feature string here to claim.
-      module Outbox
-        # Checks every outbox row a replay's history recorded against the
-        # outbox's own contract (see this file's own header).
-        #
-        # @param history [Hash] a replayed history, as returned by `Fuzzing::Replay.call`
-        # @return [true, String] true if every outbox row satisfies the contract; otherwise
-        #   a semicolon-joined message naming each offending row
-        def outbox_rows_match_reactions(history)
-          bluebooks = history.fetch(:bluebooks, {})
-
-          offenders = Array(history[:outbox_traces]).flat_map do |trace|
-            trace[:rows].flat_map { |row| outbox_row_offenders(row, trace, bluebooks) }
-          end
-
-          offenders.empty? || offenders.join("; ")
-        end
-
-        # Checks one outbox row against the outbox's own contract.
-        #
-        # @param row [Hash] one `Runtime::Outbox::Row#to_h` entry, `trace[:rows]`'s shape:
-        #   at least `:status`, `:delivery_id`, `:consumer`, `:event`, and (when failed)
-        #   `:error`
-        # @param trace [Hash] this row's outbox trace entry, one of `history[:outbox_traces]`,
-        #   carrying `:rows` and `:reactions`
-        # @param bluebooks [Hash{String => Bluebook::Chapter}] every loaded domain,
-        #   keyed by domain name
-        # @return [Array<String>] zero or one offending message naming what this row got
-        #   wrong; empty when the row is fine or its status names no check
-        def outbox_row_offenders(row, trace, bluebooks)
-          on = row.dig(:event, :name)
-
-          case row[:status]
-          when "pending", "claimed"
-            ["outbox row #{row[:delivery_id]} (#{row[:consumer]} on #{on}) never drained inline — status stayed " \
-             "#{row[:status].inspect} though delivery is inline by contract (Runtime::Outbox's own header)"]
-          when "failed"
-            ["outbox row #{row[:delivery_id]} (#{row[:consumer]} on #{on}) failed to deliver: #{row[:error]} — " \
-             "a domain refusal never reaches this far; a failed row names a defect in the relay's own consumer " \
-             "resolution"]
-          when "delivered"
-            outbox_delivered_policy_offenders(row, on, trace, bluebooks)
-          else
-            []
-          end
-        end
-
-        # Checks one delivered `policy:` outbox row for a missing `reaction_log` entry.
-        #
-        # See this file's own header for why a `saga:` row is exempt: its
-        # own `listens?` gives no such guarantee, unlike a policy's single,
-        # deterministic `where` gate.
-        #
-        # @param row [Hash] the delivered outbox row being checked
-        # @param on [String] the row's event name, `row.dig(:event, :name)`
-        # @param trace [Hash] this row's outbox trace entry, carrying `:reactions`
-        # @param bluebooks [Hash{String => Bluebook::Chapter}] every loaded domain,
-        #   keyed by domain name
-        # @return [Array<String>] zero or one offending message; empty when the row is
-        #   not a policy row, the policy is undeclared or fans out, or the policy's
-        #   `where` does not independently re-evaluate true
-        def outbox_delivered_policy_offenders(row, on, trace, bluebooks)
-          kind, fqn = row[:consumer].to_s.split(":", 2)
-          return [] unless kind == "policy"
-
-          home, name = fqn.to_s.split("::", 2)
-          return [] if trace[:reactions].any? { |entry| entry[:policy] == name && entry[:on] == on }
-
-          policy = bluebooks[home]&.policies&.find { |candidate| candidate.name == name }
-          # Nothing declared under this name — inconclusive, not a claimed mismatch.
-          return [] unless policy
-          # Fan-out row count is fanout_dispatches_once_per_matching_row's job.
-          return [] if policy.fans_out?
-
-          held = independently_re_evaluate_policy_where(policy, row[:event])
-          # False, or inconclusive (the where itself raised) — never a claimed mismatch.
-          return [] if held != true
-
-          ["outbox row #{row[:delivery_id]} (#{row[:consumer]} on #{on}) drained as delivered, but no matching " \
-           "reaction_log entry exists and the policy's own where clause independently re-evaluates true — " \
-           "PolicyInterpreter#deliver only ever returns nil (no reaction_log entry) when where does not hold"]
-        end
-
-        # `PolicyInterpreter#where_holds?`'s own two branches, reproduced —
-        # never calling that method again, which would only ever agree
-        # with itself (the same rule `resolve_dispatch_binding`'s own
-        # comment states). `Evaluator.call` (the raw-string entry, parsed
-        # and cached — never `call_rule`, which needs the policy's own
-        # build-time `where_rule` AST, an object this history has no
-        # reason to carry) is the exact same call `Replay#fan_out_finding`
-        # already makes for the identical fact one property over
-        # (`policy.where.to_s.empty? || Evaluator.call(policy.where, {},
-        # payload)`), reused rather than re-derived a second, slightly
-        # different way. `rescue`d to `nil`, not `false`: a where clause
-        # that cannot be re-evaluated from the row's own recorded payload
-        # alone is inconclusive, not proof either way — the same "never a
-        # claimed pass or a claimed mismatch from a resolution this replay
-        # cannot actually reproduce" discipline `build_guard_check`'s own
-        # rescue clause already follows.
-        #
-        # @param policy [Bluebook::Policy] the policy whose `where` clause is re-evaluated
-        # @param event [Hash] the outbox row's own recorded event, read for `:payload`
-        # @return [Boolean, nil] whether `policy`'s `where` holds against `event`'s payload,
-        #   or nil if the where clause cannot be re-evaluated from it
-        def independently_re_evaluate_policy_where(policy, event)
-          return true if policy.where.to_s.empty?
-
-          payload = (event[:payload] || {}).transform_keys(&:to_sym)
-          Bluebook::Expression::Evaluator.call(policy.where, {}, payload)
-        rescue StandardError
-          nil
-        end
-      end
-    end
-  end
-end

data/lib/hecks/fuzzing/properties/querying.rb

@@ -1,260 +0,0 @@
-module Hecks
-  module Fuzzing
-    module Properties
-      # Query-answering properties: a query's own answer matches a from-
-      # scratch reference recomputation, paging partitions its rows the same
-      # way, and the shared query/paging helpers both lean on.
-
-      # Holds query_answers_match_reference and paging_offset_partitions_correctly,
-      # plus the shared verb-resolution and eligible-rows/hop-chain helpers
-      # (#query_for_verb, #query_eligible_rows, #resolve_hop_clause) other
-      # property modules in this directory also call.
-      module Querying
-        # The query oracle — differential testing within the one runtime,
-        # the shape the retired cross-runtime harness should always have
-        # been. Every generated ask was answered twice at the same instant
-        # (Replay records both): once through whatever the aggregate is
-        # actually bound to (Memory's native hook is Ports::Query::InMemory;
-        # a SQL binding would compile it), once through the reference
-        # interpreter's own evaluation. The two are separate, live
-        # implementations of the same comparator vocabulary, and they have
-        # drifted before — an adapter that accepts what the reference says
-        # matches nothing, or orders what it refuses to order, shows up
-        # here as a finding no self-referential adapter spec could see.
-        # M23 — `Replay` runs the native and reference engines independently
-        # (each in its own begin/rescue — see that file's own comment at the
-        # capture site), so this property can tell apart "both engines
-        # refused" (fine — the ask was genuinely bad, nothing to compare)
-        # from "one refused and the other did not" (a real divergence — the
-        # two engines disagree about whether the ask was even valid, never
-        # mind what it answers). `native_refused`/`reference_refused` are
-        # read by key presence, not truthiness — `Replay` only ever adds
-        # `:error`/`:reference_error` to an entry when that side actually
-        # raised, so an absent key is an unambiguous "this side answered." A
-        # read-model ask (no reference twin attempted at all, `asked[:query]`
-        # without "::") is skipped entirely, same as always — there is no
-        # second engine to disagree with.
-        #
-        # @param history [Hash] a replayed history as returned by `Replay.call`
-        # @return [true, String] true if every native/reference query answer, and every
-        #   refusal of one, agrees; otherwise a message naming the offending query, its
-        #   args, and how the two engines disagreed
-        def query_answers_match_reference(history)
-          offenders = history.fetch(:queries).filter_map do |asked|
-            next unless asked[:query].is_a?(String) && asked[:query].include?("::")
-
-            native_refused    = asked.key?(:error)
-            reference_refused = asked.key?(:reference_error)
-
-            if native_refused != reference_refused
-              next "#{asked[:query]} #{asked[:args].inspect} — native " \
-                   "#{native_refused ? "refused (#{asked[:error]})" : 'answered'}, " \
-                   "but the reference interpreter #{reference_refused ? "refused (#{asked[:reference_error]})" : 'answered'} — " \
-                   "a refusal-shaped divergence, not just a differing row set"
-            end
-
-            next if native_refused
-            next if asked[:rows] == asked[:reference_rows]
-
-            "#{asked[:query]} #{asked[:args].inspect} answered #{asked[:rows].inspect} " \
-              "natively but #{asked[:reference_rows].inspect} through the reference interpreter"
-          end
-
-          offenders.empty? || offenders.join("; ")
-        end
-
-        # The same "two engines, compared" shape query_answers_match_reference
-        # already uses, aimed squarely at Query#options' offset/limit pair —
-        # but recomputed from history[:instances] directly, a third,
-        # independent computation, rather than comparing QueryInterpreter's
-        # own native and reference paths against each other (which could
-        # share the identical bug neither implementation happened to hit —
-        # see #4's own fix, which touched both #interpret and
-        # #reference_interpret at once). `order_by` declared alongside
-        # `offset` or `limit` names a genuinely paged query. Ports::Query::
-        # Ordering.apply is the same engine QueryInterpreter#ordered calls,
-        # reused here rather than re-derived, so this oracle cannot drift
-        # from what "in order" means without the interpreter drifting the
-        # identical way — only the offset-then-limit .drop/.first slice
-        # (#4's own fix) is independently reproduced, in plain Ruby.
-        #
-        # Real target: ATMCard.ByFee (`limit 3; offset 1`).
-        #
-        # One independent recomputation, order-dependent by construction
-        # (declared query -> eligible rows -> ordered -> offset-sliced ->
-        # limit-sliced -> compared against the real answer, per the doc
-        # comment above): splitting it would scatter `rows`/`ordered`/
-        # `skipped`/`expected` across method boundaries as params/returns
-        # for a sequence that's only ever computed once, in this order.
-        # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
-        #
-        # @param history [Hash] a replayed history as returned by `Replay.call`
-        # @return [true, String] true if every paged query's real answer matches an
-        #   independent order/offset/limit recomputation over its eligible rows;
-        #   otherwise a message naming the query, its args, and the two answers
-        def paging_offset_partitions_correctly(history)
-          bluebooks = history.fetch(:bluebooks)
-
-          offenders = history.fetch(:queries).filter_map do |asked|
-            next if asked[:error] || !asked[:query].is_a?(String) || !asked[:query].include?("::")
-
-            declared = query_for_verb(bluebooks, asked[:query])
-            next unless declared&.order_by && (declared.offset || declared.limit)
-
-            domain, aggregate_name, = Naming.split_verb(asked[:query])
-            args = asked[:args] || {}
-            rows = query_eligible_rows(asked.fetch(:instances_at), domain, aggregate_name, declared.wheres, args,
-                                       bluebooks: bluebooks)
-            ordered = Ports::Query::Ordering.apply(
-              rows, declared.order_by, declared.null_semantics, identity: ->(row) { row[:id].to_s }
-            ) { |row| Ports::Query::InMemory.comparable(QuerySpecification::FieldPath.dig(row, declared.order_by.field)) }
-
-            skipped  = declared.offset ? ordered.drop(resolve_paging_value(declared.offset.value, args).to_i) : ordered
-            expected = declared.limit ? skipped.first(resolve_paging_value(declared.limit.value, args).to_i) : skipped
-            actual   = asked[:rows]
-            next if actual == expected
-
-            "#{asked[:query]} #{args.inspect} answered #{actual.inspect}, but independently recomputing " \
-              "order/offset/limit from #{rows.length} eligible row(s) gives #{expected.inspect}"
-          end
-
-          offenders.empty? || offenders.join("; ")
-        end
-
-        # The declared Query itself, resolved from a replayed verb — the
-        # same shape #command_for_verb resolves a command by, one
-        # construct over. Entity-level queries (a dotted query_path) are
-        # out of scope here — paging on an entity's own list has no real
-        # corpus site yet, and the "one many-side head, one aggregate,
-        # no FK-join" shape #query_eligible_rows assumes doesn't hold for
-        # one.
-        #
-        # @param bluebooks [Hash{String => Bluebook::Chapter}] every loaded domain,
-        #   keyed by domain name
-        # @param verb [String] the asked verb, `"Domain::Aggregate.Query"`
-        # @return [Bluebook::Query, nil] the declared query, or nil if `verb` names an
-        #   entity-level query path, or a domain, aggregate, or query not found among
-        #   `bluebooks`
-        def query_for_verb(bluebooks, verb)
-          domain, aggregate_name, query_path = Naming.split_verb(verb)
-          return nil unless query_path && !query_path.include?(".")
-
-          bluebook  = bluebooks[domain]
-          aggregate = bluebook&.aggregate(aggregate_name)
-          aggregate&.query(query_path)
-        end
-
-        # Independently recomputes which of an aggregate's own stored rows a
-        # query's `wheres` admit.
-        #
-        # A query's own rows — unlike #eligible_rows (a ReadModel's
-        # reduced/grouped many-side head, possibly FK-joined against a
-        # root), a Query always asks about its own owning aggregate
-        # directly ; no join, no reference_target. `id:` merged in the
-        # same way #eligible_rows' own rows are, since a stable sort
-        # (Ordering.apply's own `identity:`) and the real answer's own
-        # `record.state.merge(id: record.id)` both need it.
-        # `bluebooks:` — needed only to recognise and resolve a `/` hop
-        # clause (`engagement/client/status`, hop_chain.bluebook's own
-        # PricedAboveViaEngagement): a hop's head names one of the owning
-        # aggregate's declared references, and only the declaration graph
-        # can say which attribute that is and which aggregate it targets.
-        # A local clause never consults it. Latent gap this closed, found
-        # by the fuzzer itself the first time a generated sequence ever
-        # built a full hop chain and had its paged query answer a row
-        # (seed 1, the moment scalar_value_objects.bluebook joined the
-        # fixtures corpus and shifted every seeded draw): the recompute
-        # dug `engagement/client/status` as a local dotted path, found
-        # nil, and declared every genuinely-eligible row ineligible — a
-        # false property violation against a correct runtime answer,
-        # reproducible on an untouched main with this same 4-step script.
-        #
-        # @param instances [Hash{String => Hash}] `history[:instances]`, or an
-        #   `:instances_at` snapshot from a replayed query entry
-        # @param domain [String] the domain name the target aggregate belongs to
-        # @param aggregate_name [String] the target aggregate's own declared name
-        # @param wheres [Array<QuerySpecification::Common::WhereClause>] the clauses
-        #   every returned row must satisfy
-        # @param args [Hash] the query's own call args, for a clause whose value is a
-        #   Symbol naming one
-        # @param bluebooks [Hash{String => Bluebook::Chapter}] every loaded domain, keyed
-        #   by domain name; needed only to resolve a `/` hop clause
-        # @return [Array<Hash>] each admitted row's own state, merged with its `id:`
-        def query_eligible_rows(instances, domain, aggregate_name, wheres, args, bluebooks: {})
-          aggregate = bluebooks[domain]&.aggregate(aggregate_name)
-          prefix = "#{domain}::#{aggregate_name}#"
-          instances.filter_map do |key, state|
-            next unless key.start_with?(prefix)
-
-            row = state.merge(id: key.split("#").last)
-            next unless wheres.all? do |clause|
-              resolved = resolve_hop_clause(instances, domain, aggregate, clause, args, bluebooks)
-              held = Ports::Query::InMemory.comparable(QuerySpecification::FieldPath.dig(row, resolved.field))
-              Ports::Query::InMemory.holds?(resolved, held, args)
-            end
-
-            row
-          end
-        end
-
-        # Resolves one hop of a `/`-chained clause into a local `in` clause against
-        # the target aggregate's own ids.
-        #
-        # `Runtime::ReferenceHop#fold`, independently restated over the
-        # replay's own `:instances_at` snapshot instead of live
-        # repositories — the same shape every other recompute in this
-        # file takes (never the runtime's own code path, or the property
-        # would be checking the runtime against itself). One hop peels
-        # off the head (`HopPath.next_hop`, the identical one-step
-        # primitive the live fold uses), the inner clause recurses
-        # through `query_eligible_rows` against the target's own
-        # snapshot rows (so a multi-hop tail resolves hop by hop, exactly
-        # as the live path's own recursion does), and the ids that
-        # answered fold back as the same local `in` membership clause the
-        # live fold builds. A clause with no `/`, or one whose head this
-        # aggregate's declarations cannot resolve, passes through
-        # untouched and evaluates locally as it always did.
-        #
-        # @param instances [Hash{String => Hash}] `history[:instances]`, or an
-        #   `:instances_at` snapshot from a replayed query entry
-        # @param domain [String] the domain name `aggregate` belongs to
-        # @param aggregate [Bluebook::Aggregate, nil] the aggregate `clause` is
-        #   evaluated against; nil skips hop resolution entirely
-        # @param clause [QuerySpecification::Common::WhereClause] the clause to resolve
-        # @param args [Hash] the query's own call args, passed through to the inner
-        #   hop's own `query_eligible_rows` recursion
-        # @param bluebooks [Hash{String => Bluebook::Chapter}] every loaded domain, keyed
-        #   by domain name
-        # @return [QuerySpecification::Common::WhereClause] `clause` unchanged if it has
-        #   no resolvable hop head; otherwise a local `in` clause over the matching
-        #   target ids
-        def resolve_hop_clause(instances, domain, aggregate, clause, args, bluebooks)
-          return clause unless aggregate && QuerySpecification::HopPath.hop_head?(clause.field, aggregate.attributes)
-
-          hop, rest = QuerySpecification::HopPath.next_hop(clause.field, aggregate.attributes)
-          target = hop.target
-          return clause unless target
-
-          inner = QuerySpecification::Common::WhereClause.new(field: rest, op: clause.op, value: clause.value)
-          ids   = query_eligible_rows(instances, domain, target.hecks_name, [inner], args, bluebooks: bluebooks)
-                  .map { |row| row[:id].to_s }.uniq
-
-          QuerySpecification::Common::WhereClause.new(field: hop.attribute.name, op: "in", value: ids)
-        end
-
-        # Resolves a declared limit/offset value against the query's own call args.
-        #
-        # `QueryInterpreter#resolve_query_value`, reproduced: a declared
-        # limit/offset is either a literal or a Symbol naming an argument
-        # the caller supplied.
-        #
-        # @param value [Integer, Symbol] the declared limit/offset value
-        # @param args [Hash] the query's own call args
-        # @return [Object] `value` unchanged if not a Symbol; otherwise `args[value]`
-        def resolve_paging_value(value, args)
-          value.is_a?(Symbol) ? args[value] : value
-        end
-      end
-    end
-  end
-end