hecks 3.5.0 → 3.7.0

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

@@ -0,0 +1,89 @@
+module Hecks
+  module Fuzzing
+    module Properties
+      # The standard battery, in the order `check` reports it.
+      PROPERTY_NAMES = [
+        :lifecycle_values_are_declared,
+        :saga_advances_follow_declared_handlers,
+        :query_answers_match_reference,
+        :guard_refusals_are_declared,
+        :sagas_rehydrate_cleanly,
+        :fanout_dispatches_once_per_matching_row,
+        :aggregation_matches_recompute,
+        :stored_records_satisfy_declared_invariants,
+        :group_by_matches_recompute,
+        :paging_offset_partitions_correctly,
+        :lifecycle_guard_and_given_violations_are_refused,
+        :authorize_scopes_or_refuses,
+        :commands_respect_tenant_scope,
+        :dispatch_binding_fidelity,
+        :mutations_match_recompute,
+        :dry_runs_leave_no_trace,
+        :corrections_reference_an_emitted_event,
+        :outbox_rows_match_reactions,
+        :policy_reactions_follow_declared_wiring,
+        :declared_undelivered_policies_stay_undelivered,
+        :references_resolve_to_earlier_records,
+        :role_checks_agree_with_grants,
+        :read_model_names_resolve_uniquely,
+        :read_model_heads_compose_from_references
+      ].freeze
+
+      # Which language feature each property is answerable for — exhaustive of
+      # what would go unchecked without it, not of everything its body touches.
+      FEATURE_COVERAGE = {
+        lifecycle_values_are_declared:                    %w[Aggregate#state_field Aggregate#state_start Aggregate#transitions
+                                                             Entity#state_field Entity#state_start Entity#transitions],
+        saga_advances_follow_declared_handlers:           %w[Handler#from_state Handler#to_state Handler#event_type],
+        query_answers_match_reference:                    %w[Query#wheres Query#order_field Query#order_way Query#limit],
+        paging_offset_partitions_correctly:               %w[Query#options],
+        authorize_scopes_or_refuses:                      %w[Query#options],
+        guard_refusals_are_declared:                      %w[Command#givens Command#ensures Command#needs],
+        lifecycle_guard_and_given_violations_are_refused: %w[Command#from Aggregate#preconditions Entity#preconditions],
+        # Dispatch#command_name/with_spec aren't claimable feature names — the
+        # coverage walk only reaches one level of entity nesting and Dispatch
+        # sits two deep — but this property still checks the real behavior
+        # (dispatch_args) those names would have covered.
+        dispatch_binding_fidelity:                        %w[Handler#dispatches Policy#with_spec],
+        mutations_match_recompute:                        %w[Command#mutations],
+        sagas_rehydrate_cleanly:                          %w[ProcessManager#states ProcessManager#correlates_by
+                                                             ProcessManager#starts_on ProcessManager#ends_on],
+        fanout_dispatches_once_per_matching_row:          %w[Policy#for_each Policy#where],
+        aggregation_matches_recompute:                    %w[ReadModel#count ReadModel#median_field ReadModel#sum_field
+                                                             ReadModel#avg_field ReadModel#min_field ReadModel#max_field
+                                                             ReadModel#percentile_field ReadModel#percentile_at
+                                                             ReadModel#any_field ReadModel#all_field],
+        stored_records_satisfy_declared_invariants:       %w[Aggregate#invariants Entity#invariants],
+        group_by_matches_recompute:                       %w[ReadModel#group_by],
+        # A runtime door, not a grammar construct — `Dispatcher#dry_run?` is not
+        # a word a bluebook declares. Listed empty rather than omitted, so every
+        # property still names what it is answerable for.
+        dry_runs_leave_no_trace:                          [],
+        # Another runtime door, not a grammar construct — same reasoning as
+        # dry_runs_leave_no_trace above.
+        outbox_rows_match_reactions:                      [],
+        # Reads command.mutations for :corrects ops — the same list
+        # mutations_match_recompute reads, for a different question.
+        corrections_reference_an_emitted_event:           %w[Command#mutations],
+        # Reads each logged reaction back against the policy that produced it: the event it
+        # answers, the trigger it builds, and the domain `across` sends it to.
+        policy_reactions_follow_declared_wiring:          %w[Policy#on_event Policy#trigger_command Policy#target_domain],
+        # model_check holds the static half of `expect_undelivered`; this is the runtime half.
+        declared_undelivered_policies_stay_undelivered:   %w[Policy#expect_undelivered],
+        # An accepted referencing command addressed a record an earlier event created.
+        references_resolve_to_earlier_records:            %w[Command#references],
+        # The grants read back through the verb the authorization provider declares in `provides`.
+        role_checks_agree_with_grants:                    %w[Bluebook#provides],
+        read_model_names_resolve_uniquely:                %w[ReadModel#query_name],
+        # Each head's rows recomputed from the references; options apply to targeted heads only.
+        read_model_heads_compose_from_references:         %w[ReadModel#reference_name ReadModel#reference_target
+                                                             ReadModel#aggregate_heads ReadModel#options],
+        # No feature string exists for what this reads: an argument's own
+        # `relationship` (Argument is a value object, outside the meta-domain
+        # walk). Its declaration side, `Query#options`, is already claimed by
+        # authorize_scopes_or_refuses.
+        commands_respect_tenant_scope:                    []
+      }.freeze
+    end
+  end
+end

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

@@ -19,26 +19,25 @@ module Hecks
 
           (history[:bluebooks] || {}).each do |domain, bluebook|
             bluebook.aggregates.each do |aggregate|
-              aggregate_key = "#{domain}::#{aggregate.hecks_name}"
-
-              each_command_including_entities(aggregate) do |command|
-                corrects_mutations = command.mutations.select { |mutation| mutation.op == :corrects }
-                next if corrects_mutations.empty?
+              violations.concat(aggregate_corrections(history[:events], "#{domain}::#{aggregate.hecks_name}", aggregate))
+            end
+          end
 
-                corrects_mutations.each do |mutation|
-                  corrected_event = mutation.target.to_s
+          violations.empty? || violations.uniq.join("; ")
+        end
 
-                  command.emits.each do |produced_event_name|
-                    violations.concat(unmatched_corrections(history[:events], aggregate_key,
-                                                            produced_event_name.to_s, corrected_event,
-                                                            command.hecks_name))
-                  end
-                end
+        # Every unmatched correction among the commands of `aggregate` and its entities.
+        def aggregate_corrections(events, aggregate_key, aggregate)
+          found = []
+          each_command_including_entities(aggregate) do |command|
+            command.mutations.select { |mutation| mutation.op == :corrects }.each do |mutation|
+              command.emits.each do |produced_event_name|
+                found.concat(unmatched_corrections(events, aggregate_key, produced_event_name.to_s,
+                                                   mutation.target.to_s, command.hecks_name))
               end
             end
           end
-
-          violations.empty? || violations.uniq.join("; ")
+          found
         end
 
         # Finds every occurrence of `produced_event_name`, on `aggregate_key`, with no
@@ -58,11 +57,7 @@ module Hecks
           end
 
           own_events.filter_map do |event, index|
-            preceding = events.first(index)
-            next if preceding.any? do |earlier|
-              earlier[:name] == corrected_event && earlier[:aggregate] == aggregate_key &&
-              earlier[:id].to_s == event[:id].to_s
-            end
+            next if corrected_earlier?(events.first(index), aggregate_key, corrected_event, event)
 
             "#{command_name} (#{aggregate_key}##{event[:id]}) emitted #{produced_event_name}, claiming to " \
               "correct #{corrected_event}, but no #{corrected_event} for the same aggregate/id appears " \
@@ -70,6 +65,14 @@ module Hecks
           end
         end
 
+        # Whether `preceding` holds the corrected event for `event`'s aggregate and id.
+        def corrected_earlier?(preceding, aggregate_key, corrected_event, event)
+          preceding.any? do |earlier|
+            earlier[:name] == corrected_event && earlier[:aggregate] == aggregate_key &&
+              earlier[:id].to_s == event[:id].to_s
+          end
+        end
+
         # Yields every command on `owner` and, recursively, on its entities (ADR 0026).
         #
         # @param owner [Bluebook::Aggregate, Bluebook::Entity] the aggregate or entity

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

@@ -1,3 +1,5 @@
+require_relative "mutation_recompute"
+
 module Hecks
   module Fuzzing
     module Properties
@@ -11,26 +13,36 @@ module Hecks
         # @return [true, String] true if every dry-run trace shows no change; otherwise
         #   a semicolon-joined message naming each offending dry run
         def dry_runs_leave_no_trace(history)
-          offenders = Array(history[:dry_run_traces]).filter_map do |entry|
-            before = entry[:before]
-            after  = entry[:after]
-            next unless before && after
+          offenders = Array(history[:dry_run_traces]).filter_map { |entry| dry_run_offender(entry) }
+          offenders.empty? || offenders.join("; ")
+        end
 
-            traces = []
-            traces << "events #{before[:events]} -> #{after[:events]}" unless before[:events] == after[:events]
-            traces << "instances changed" unless before[:instances] == after[:instances]
-            next if traces.empty?
+        # The message for one dry run that left a trace, or nil.
+        def dry_run_offender(entry)
+          before = entry[:before]
+          after  = entry[:after]
+          return unless before && after
 
-            "dry run of #{entry[:verb]} (ok: #{entry[:ok]}) left a trace: #{traces.join(', ')}"
-          end
+          traces = dry_run_changes(before, after)
+          return if traces.empty?
 
-          offenders.empty? || offenders.join("; ")
+          "dry run of #{entry[:verb]} (ok: #{entry[:ok]}) left a trace: #{traces.join(", ")}"
+        end
+
+        # What differs between a dry run's before and after snapshots.
+        def dry_run_changes(before, after)
+          traces = []
+          traces << "events #{before[:events]} -> #{after[:events]}" unless before[:events] == after[:events]
+          traces << "instances changed" unless before[:instances] == after[:instances]
+          traces
         end
       end
 
       # Properties: saga/policy dispatch args match their `with_spec`, and command
       # mutations match an independent recomputation.
       module DispatchAndMutations
+        include MutationRecompute
+
         # Checks saga and policy dispatch args against an independent re-derivation of
         # `with_spec`. Re-deriving, not calling the interpreter again, keeps the check
         # from agreeing with itself. Args are compared as captured live, because a
@@ -41,7 +53,13 @@ module Hecks
         #   match an independent re-derivation of their `with_spec`; otherwise a
         #   semicolon-joined message naming each offending dispatch
         def dispatch_binding_fidelity(history)
-          saga_offenders = history.fetch(:saga_dispatches, []).filter_map do |entry|
+          offenders = saga_binding_offenders(history) + policy_binding_offenders(history)
+          offenders.empty? || offenders.join("; ")
+        end
+
+        # One message per saga dispatch whose bound args differ from the re-derivation.
+        def saga_binding_offenders(history)
+          history.fetch(:saga_dispatches, []).filter_map do |entry|
             expected = resolve_dispatch_binding(entry)
             next if expected == entry[:args]
 
@@ -49,17 +67,17 @@ module Hecks
               "bound #{entry[:args].inspect}, but independently re-deriving with_spec's own resolution gives " \
               "#{expected.inspect}"
           end
+        end
 
-          policy_offenders = history.fetch(:policy_dispatches, []).filter_map do |entry|
+        # One message per policy dispatch whose bound args differ from the re-derivation.
+        def policy_binding_offenders(history)
+          history.fetch(:policy_dispatches, []).filter_map do |entry|
             expected = resolve_trigger_binding(entry)
             next if expected == entry[:args]
 
             "#{entry[:policy]} on #{entry[:on]} — bound #{entry[:args].inspect}, but independently re-deriving " \
               "with_spec's own resolution gives #{expected.inspect}"
           end
-
-          offenders = saga_offenders + policy_offenders
-          offenders.empty? || offenders.join("; ")
         end
 
         # Re-derives SagaInterpreter#dispatch_args: a literal, the correlation key,
@@ -106,33 +124,44 @@ module Hecks
         #   naming each offending mutation
         def mutations_match_recompute(history)
           bluebooks = history.fetch(:bluebooks)
+          offenders = history.fetch(:mutation_traces, []).flat_map { |entry| mutation_offenders(bluebooks, entry) }
+          offenders.empty? || offenders.join("; ")
+        end
 
-          offenders = history.fetch(:mutation_traces, []).flat_map do |entry|
-            next [] unless entry[:after]
+        # One message per recomputable mutation of `entry` whose real after-state differs.
+        def mutation_offenders(bluebooks, entry)
+          return [] unless entry[:after]
 
-            command = command_for_verb(bluebooks, entry[:verb])
-            next [] unless command
+          context = mutation_context(bluebooks, entry)
+          return [] unless context
 
-            aggregate = aggregate_for_verb(bluebooks, entry[:verb])
-            next [] unless aggregate
+          recomputable = context.command.mutations.select { |m| RECOMPUTABLE_MUTATION_OPS.include?(m.op) }
+          recomputable.filter_map { |mutation| mutation_offender(mutation, entry, context) }
+        end
 
-            owner = owner_for_verb(bluebooks, entry[:verb]) || aggregate
+        # What recomputing `entry` needs, or nil when its verb names no command or aggregate.
+        def mutation_context(bluebooks, entry)
+          command = command_for_verb(bluebooks, entry[:verb])
+          return unless command
 
-            args = with_declared_defaults(command, entry[:args])
-            command.mutations.select { |m| RECOMPUTABLE_MUTATION_OPS.include?(m.op) }.filter_map do |mutation|
-              expected = recompute_mutation(mutation, entry[:before][mutation.target], args, entry[:before],
-                                            aggregate, command, owner)
-              next if expected == :unrecomputable
+          aggregate = aggregate_for_verb(bluebooks, entry[:verb])
+          return unless aggregate
 
-              actual = entry[:after][mutation.target]
-              next if symbolize_deep(expected) == symbolize_deep(actual)
+          owner = owner_for_verb(bluebooks, entry[:verb]) || aggregate
+          MutationRecompute::Context.new(aggregate, command, owner, entry[:before],
+                                         with_declared_defaults(command, entry[:args]))
+        end
 
-              "#{entry[:verb]} — #{mutation.op} on #{mutation.target} — recomputing independently gives " \
-                "#{expected.inspect}, but the real dispatch left #{actual.inspect}"
-            end
-          end
+        # The message for one mutation whose recomputation disagrees with the real dispatch.
+        def mutation_offender(mutation, entry, context)
+          expected = recompute_mutation(mutation, entry[:before][mutation.target], context)
+          return if expected == :unrecomputable
 
-          offenders.empty? || offenders.join("; ")
+          actual = entry[:after][mutation.target]
+          return if symbolize_deep(expected) == symbolize_deep(actual)
+
+          "#{entry[:verb]} — #{mutation.op} on #{mutation.target} — recomputing independently gives " \
+            "#{expected.inspect}, but the real dispatch left #{actual.inspect}"
         end
 
         # The arguments the command actually ran with: an argument the caller left out takes the
@@ -174,156 +203,6 @@ module Hecks
           entity_name, = command_path.split(".", 2)
           aggregate.entities.find { |candidate| candidate.hecks_name == entity_name }
         end
-
-        # Dispatches to the recompute rule for `mutation.op`.
-        def recompute_mutation(mutation, current, args, before_scope, aggregate, command, owner = aggregate)
-          case mutation.op
-          when :append
-            recompute_append(current, mutation.source, before_scope, args, aggregate, command, owner, mutation.target)
-          when :remove   then recompute_remove(current, mutation.source, args)
-          when :multiply then recompute_multiply(current, resolve_mutation_source(mutation.source, args))
-          when :clamp    then recompute_clamp(current, mutation.source)
-          when :set      then recompute_set(mutation.source, args, aggregate, owner, mutation.target)
-          end
-        end
-
-        # Re-derives the `:set` branch of `EntityElement#apply_to_element`. The
-        # attribute comes from `owner`, not the root aggregate, which would leave a
-        # nested entity's value uncoerced and disagree with the real after-state.
-        # Any raise means the raw material was wrong, so the result is `:unrecomputable`.
-        def recompute_set(source, args, aggregate, owner, target)
-          raw = resolve_mutation_source(source, args)
-          attribute = owner&.attribute(target)
-          coerced = attribute ? Runtime::Value.for_attribute(aggregate, attribute, raw) : raw
-          Runtime::Value.materialize(coerced)
-        rescue StandardError
-          :unrecomputable
-        end
-
-        # Re-derives `EntityElement#appended_to_element`: each field resolves from a
-        # caller arg (coerced as `Interpreting#coerce_declared_arguments` does) or from
-        # the entity's current field (already materialized), then the element is appended.
-        # A nested-entity element also gets its declared defaults.
-        def recompute_append(current, source_map, before_scope, args, aggregate, command, owner = aggregate, target = nil)
-          fields = source_map.transform_values do |source|
-            resolve_mutation_append_field(source, before_scope, args, aggregate, command)
-          end
-          fill_recompute_declared_defaults(aggregate, owner, target, fields)
-          Array(current) + [symbolize_deep(fields)]
-        end
-
-        # Fills defaults for a nested-entity element via `Instance.default_for`, which is
-        # independently tested. No-op unless `target` names an entity under `owner`
-        # (`owner.entities`, not `aggregate.entities`).
-        #
-        # A value-object element type (the more common shape: `list_of` a plain composite,
-        # not a nested entity) defaults the other way real dispatch does — through
-        # `Runtime::Value.apply_defaults`, the exact primitive `EntityElement#appended_to_
-        # element`'s own `Value.build` call uses. Without this branch, a caller-omitted,
-        # VO-declared `default:` field is left out of the recomputed element entirely,
-        # disagreeing with real dispatch's fully-defaulted one.
-        def fill_recompute_declared_defaults(aggregate, owner, target, fields)
-          return fields unless target
-
-          element_type = owner&.attribute(target)&.type
-          return fields unless element_type
-
-          entity = owner.entities.find { |piece| piece.hecks_name == element_type.to_s }
-          if entity
-            entity.attributes.each do |attribute|
-              next if fields.key?(attribute.name)
-
-              fields[attribute.name] = attribute.list? ? [] : Runtime::Instance.default_for(aggregate, attribute)
-            end
-            return fields
-          end
-
-          value_object = aggregate.value_object(element_type)
-          return fields unless value_object
-
-          Runtime::Value.apply_defaults(value_object, fields)
-        end
-
-        # Resolves one appended field's value from its declared source.
-        def resolve_mutation_append_field(source, before_scope, args, aggregate, command)
-          return source unless source.is_a?(Symbol)
-          return before_scope[source] unless args.key?(source)
-
-          coerce_recompute_append_arg(aggregate, command, source, args[source])
-        end
-
-        # Coerces a raw arg only when `source` is a declared attribute of the command,
-        # as a real dispatch does. Materialized so the comparison is plain data on both sides.
-        def coerce_recompute_append_arg(aggregate, command, source, raw)
-          attribute = command.attribute(source)
-          return raw unless attribute
-
-          Runtime::Value.materialize(Runtime::Value.for_attribute(aggregate, attribute, raw, argument: true))
-        end
-
-        # Re-derives `MutationApplier#removed`: removes every value-equal element.
-        # `Value.materialize` first: once `args` arrives normalized (replay.rb's
-        # `build_mutation_trace`), a composite `remove:` source is already a built
-        # `Runtime::Value` with its own declared defaults filled — comparing it
-        # unmaterialized against `current`'s plain Hashes would never match, wrongly
-        # keeping an element real dispatch correctly removed.
-        def recompute_remove(current, source, args)
-          target = symbolize_deep(Runtime::Value.materialize(resolve_mutation_source(source, args)))
-          Array(current).reject { |element| symbolize_deep(element) == target }
-        end
-
-        # Re-derives `CommandRules::Arithmetic#multiply` on plain data: a Hash with one
-        # numeric field scales that field, a bare Numeric scales itself. A nil
-        # `current` is treated as 0.
-        def recompute_multiply(current, amount)
-          return :unrecomputable unless amount.is_a?(Numeric)
-
-          current ||= 0
-          if current.is_a?(Hash)
-            field = current.keys.find { |f| current[f].is_a?(Numeric) }
-            return :unrecomputable unless field
-
-            current.merge(field => current[field] * amount)
-          elsif current.is_a?(Numeric)
-            current * amount
-          else
-            :unrecomputable
-          end
-        end
-
-        # Re-derives `CommandRules::Arithmetic#clamp` like #recompute_multiply. The
-        # source is always a literal `[min, max]`, never an argument reference.
-        def recompute_clamp(current, bounds)
-          return :unrecomputable unless bounds.is_a?(Array) && bounds.size == 2
-
-          min, max = bounds
-          current ||= 0
-          if current.is_a?(Hash)
-            field = current.keys.find { |f| current[f].is_a?(Numeric) }
-            return :unrecomputable unless field
-
-            current.merge(field => current[field].clamp(min, max))
-          elsif current.is_a?(Numeric)
-            current.clamp(min, max)
-          else
-            :unrecomputable
-          end
-        end
-
-        # A mutation source is an argument name (Symbol) or a literal.
-        def resolve_mutation_source(source, args)
-          source.is_a?(Symbol) ? args[source] : source
-        end
-
-        # Symbolizes hash keys recursively. Generated args carry string keys while
-        # materialized trace state carries symbols, and `Hash#==` would otherwise differ.
-        def symbolize_deep(value)
-          case value
-          when Hash  then value.to_h { |key, val| [key.to_sym, symbolize_deep(val)] }
-          when Array then value.map { |val| symbolize_deep(val) }
-          else value
-          end
-        end
       end
     end
   end

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

@@ -0,0 +1,69 @@
+module Hecks
+  module Fuzzing
+    module Properties
+      # Independent nestings of a `group_by` read model's rows, for
+      # `InvariantsAndAggregation#group_by_matches_recompute` to compare against the answer.
+      module GroupByRecompute
+        # Judges one `group_by` ask against the rows it was eligible to see:
+        # refused exactly when two of them share a checked key path, and
+        # otherwise nested exactly as `nest_rows` nests them.
+        def group_by_offense(bluebook, asked, model, grouped_head)
+          rows = eligible_rows(bluebook, asked.fetch(:instances_at), model, grouped_head, asked[:args] || {})
+          materialized = rows.map { |state| Runtime::Value.materialize_unwrapped(state) }
+          shared = shared_key_paths(materialized, model.group_by_fields)
+          return nesting_offense(asked, model, grouped_head, materialized) if shared.empty?
+
+          collision_offense(asked, model.group_by_fields, shared.length, checked_key_paths?(bluebook, model, grouped_head))
+        end
+
+        # Whether the grouped key paths are checked, i.e. do not cover the head's identity.
+        def checked_key_paths?(bluebook, model, grouped_head)
+          !model.groups_by_identity?(bluebook.aggregate(grouped_head[:aggregate]))
+        end
+
+        # Judges an ask with no shared key path: it must not have refused, and its grouping must
+        # equal the independent nesting.
+        def nesting_offense(asked, model, grouped_head, materialized)
+          return nil if asked[:error]
+          return nil if asked[:rows]&.first&.dig(grouped_head[:as]) == nest_rows(materialized, model.group_by_fields)
+
+          "#{asked[:query]} #{asked[:args].inspect} answered a #{grouped_head[:as]} grouping that disagrees " \
+            "with independently nesting group_by #{model.group_by_fields.inspect} over #{materialized.length} " \
+            "eligible row(s)"
+        end
+
+        # Judges an ask whose eligible rows share at least one full key path:
+        # a checked key path must have refused, and an identity-covering one
+        # cannot be shared by rows that hold their identity.
+        def collision_offense(asked, fields, shared, checked)
+          return nil if checked && asked[:error]
+
+          "#{asked[:query]} #{asked[:args].inspect} #{checked ? "answered" : "reached"}, but #{shared} key " \
+            "path(s) of group_by #{fields.inspect} are shared by more than one eligible row, " \
+            "#{checked ? "so the ask must refuse" : "though they cover the identity"}"
+        end
+
+        # Every full `group_by` key path more than one row reaches, found by
+        # tallying each row's tuple of grouped values, with no nesting at all.
+        def shared_key_paths(rows, fields)
+          rows.map { |row| fields.map { |field| row[field] } }.tally.select { |_, count| count > 1 }.keys
+        end
+
+        # One level of nesting per `group_by` field in declared order; the leaf
+        # is the row with every grouped field stripped. Called only when no key
+        # path is shared (`shared_key_paths` rules that out), so each leaf holds
+        # exactly one row; a second row raises rather than being picked over.
+        def nest_rows(rows, fields)
+          field, *rest = fields
+          rows.group_by { |row| row[field] }.transform_values do |group|
+            stripped = group.map { |row| row.reject { |key, _| key == field } }
+            next nest_rows(stripped, rest) unless rest.empty?
+            raise ArgumentError, "nest_rows reached a key path #{stripped.length} rows share" unless stripped.length == 1
+
+            stripped[0]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,63 @@
+module Hecks
+  module Fuzzing
+    module Properties
+      # Features a replay could never observe violated, because construction
+      # makes the violation impossible to produce — not untested, but
+      # unfalsifiable. Each entry names the runtime path that guarantees it;
+      # add one only after reading and confirming that path (mirrors the
+      # discipline spec/fuzzing/meta_domain_coverage_spec.rb's KNOWN_GAPS demands
+      # in the other direction).
+      GUARANTEED_BY_CONSTRUCTION = {
+        "Aggregate#attributes"    => "every field's pattern/closed-set/type passes through Value.build's one coercion " \
+                                     "door (value/coercion.rb#check_patterns, value/admission.rb) before it can exist " \
+                                     "— a stored value that violated its own declared shape was never producible to " \
+                                     "begin with",
+        "Aggregate#value_objects" => "the shape being coerced above — same door, same guarantee",
+        # S17, ADR 0026 — saga_advances_follow_declared_handlers already walks
+        # this list to find event_type/from_state/to_state; same door, same guarantee.
+        "ProcessManager#handlers" => "saga_advances_follow_declared_handlers already walks this list to find " \
+                                     "event_type/from_state/to_state — same door, same guarantee",
+        "Aggregate#identified_by" => "CommandInterpreter's data-driven dispatch order refuses AlreadyExists " \
+                                     "(command_interpreter.rb, command.creates?) for every creating command uniformly, " \
+                                     "before a duplicate id can ever be stored — collision is refused at the door, not " \
+                                     "produced and later caught",
+        "Entity#identified_by"    => "EntityElement.check_entity_collision (runtime/entity_element.rb, moved there " \
+                                     "BUG#145 so both call sites share it) checks Array(current) against every part " \
+                                     "of the entity's own identity before an append can land — MutationApplier#" \
+                                     "entity_element's aggregate-owned call (Workspace.boards, on both branches " \
+                                     "identity arrives by: caller-supplied, or composite) AND EntityElement#" \
+                                     "appended_to_element's entity-owned, nested-one-hop-further call (Board.cards — " \
+                                     "unconditional, no auto-mint branch exists at that depth) — the same " \
+                                     "AlreadyExists refusal Aggregate#identified_by gets above, one or two levels " \
+                                     "down. Auto-minted (aggregate-owned) entities never reach the check " \
+                                     "(current.size + 1 can't repeat unless something remove:s from the list between " \
+                                     "mints, which no real domain does today — see the comment on #entity_element " \
+                                     "itself)",
+        "Command#attributes"      => "command arguments are coerced through the SAME Value.build door as any other " \
+                                     "attribute — an accepted dispatch's own args already passed pattern/admits/invariant checks",
+        "Command#emits"           => "CommandRules::Emission#emit iterates command.emits ITSELF to construct every " \
+                                     "announced Event (command_rules/emission.rb) — there is no other path to emit, so " \
+                                     "a command can never announce a name its own declaration doesn't list",
+        "Query#attributes"        => "query arguments are coerced through the same Value.build door — same guarantee as " \
+                                     "Command#attributes",
+        "Query#returns"           => "every row a port answers is built as the returned value object by Value.build " \
+                                     "(QueryInterpreter#shaped) before it enters the domain — an answer of any other " \
+                                     "shape is refused, so none can be accepted",
+        "Entity#attributes"       => "same coercion door, one level in — an entity's own attributes are Value-typed exactly " \
+                                     "the way an aggregate's are",
+        "ValueObject#attributes"  => "the shape Value.build enforces IS this declaration — the guarantee and the " \
+                                     "feature are the same fact seen from two sides",
+        "ValueObject#invariants"  => "run inside the SAME coercion call (coercion.rb, before construction returns) " \
+                                     "that pattern-checks a VO's fields — a VO whose invariant did not hold could not " \
+                                     "finish being built",
+        "ValueObject#rows"        => "closed-set membership is checked in value/admission.rb, the second half of the same " \
+                                     "one construction door",
+        # S17, ADR 0026 — Member is a genuine entity, so this reads Member#pairs,
+        # not Member#shape. ValueObject#members is the same fact ValueObject#rows
+        # counts, seen from the other side.
+        "ValueObject#members"     => "the members list IS what ValueObject#rows counts — same door, same guarantee",
+        "Member#pairs"            => "one level into ValueObject#rows — same door"
+      }.freeze
+    end
+  end
+end