hecks 3.4.2 → 3.6.0

data/lib/hecks/runtime/command_rules/operands.rb

@@ -0,0 +1,88 @@
+require_relative "../../rendering"
+require_relative "../errors"
+require_relative "../refusal_wording"
+require_relative "../value"
+
+module Hecks
+  module Runtime
+    class CommandRules
+      module Arithmetic
+        # What arithmetic does to its operands before combining them: unwrapping a value object
+        # to its number, picking the one numeric field two value objects share, and wording the
+        # refusal when an operand is not a number. Mixed into {Arithmetic}.
+        module Operands
+          private
+
+          def value_objects?(current, amount)
+            current.is_a?(Value) && amount.is_a?(Value)
+          end
+
+          def sign_symbol(sign)
+            sign.positive? ? "+" : "-"
+          end
+
+          # Refuses an amount, then a current value, that is not a number.
+          def refuse_non_numeric!(verb, target, amount, current)
+            return if amount.is_a?(Numeric) && current.is_a?(Numeric)
+
+            site, offered = amount.is_a?(Numeric) ? ["arithmetic_current", current] : ["arithmetic_amount", amount]
+            raise TypeMismatch, RefusalWording.render_site("TypeMismatch", site,
+                                                           op: verb, target: target, offered: Rendering.describe(offered))
+          end
+
+          # Refuses a product with a side that is not a number, offering the side that is not.
+          def refuse_unmultipliable!(target, amount, current)
+            return if amount.is_a?(Numeric) && current.is_a?(Numeric)
+
+            raise TypeMismatch, RefusalWording.render_site("TypeMismatch", "arithmetic_amount",
+                                                           op: "multiply", target: target,
+                                                           offered: Rendering.describe(current.is_a?(Numeric) ? amount : current))
+          end
+
+          # Only meaningful once `current` is known not to itself be a Value (the
+          # both-sides-are-Values branch owns that case in each caller). Refuses
+          # rather than guesses when more than one field is numeric.
+          def unwrap_single_numeric_field(value)
+            fields = value.to_h
+            numeric_fields = fields.keys.select { |field| fields[field].is_a?(Numeric) }
+            return value unless numeric_fields.size == 1
+
+            fields[numeric_fields.first]
+          end
+
+          def combine_value_object(current, amount, target, oper)
+            field = shared_numeric_field(current, amount, target, oper)
+            current.with(field, yield(current[field], amount[field]))
+          end
+
+          # The one numeric field both value objects carry; refuses when there is not exactly one.
+          def shared_numeric_field(current, amount, target, oper)
+            current_fields = current.to_h
+            amount_fields  = amount.to_h
+            shared_numeric = current_fields.keys.select do |field|
+              current_fields[field].is_a?(Numeric) && amount_fields[field].is_a?(Numeric)
+            end
+            return shared_numeric.first if shared_numeric.size == 1
+
+            raise TypeMismatch,
+                  RefusalWording.render_site("TypeMismatch", "arithmetic_shared_field", op: oper, target: target)
+          end
+
+          # Bounds a value object's one numeric field into `[min, max]`.
+          def clamp_value_object(current, min, max, target)
+            fields = current.to_h
+            field  = fields.keys.find { |f| fields[f].is_a?(Numeric) } or
+              raise TypeMismatch, RefusalWording.render_site("TypeMismatch", "arithmetic_current",
+                                                             op: "clamp", target: target, offered: Rendering.describe(current))
+            current.with(field, fields[field].clamp(min, max))
+          end
+
+          def refuse_clamp_current!(current, target)
+            raise TypeMismatch, RefusalWording.render_site("TypeMismatch", "arithmetic_current",
+                                                           op: "clamp", target: target, offered: Rendering.describe(current))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/command_rules/references.rb

@@ -2,7 +2,7 @@ require_relative "../errors"
 require_relative "../refusal_wording"
 require_relative "../value"
 require_relative "../../rendering"
-require_relative "../../ports/query/in_memory"
+require_relative "tenant_boundary"
 
 module Hecks
   module Runtime
@@ -15,16 +15,9 @@ module Hecks
         # @raise [Runtime::NotFound] if an argument names an identity that does not exist
         def resolve_references(domain, command, args)
           command.attributes.each do |attribute|
-            next unless attribute.reference?
-            next unless args.key?(attribute.name)
-
-            held = args[attribute.name]
-            next if held.nil?
+            next unless attribute.reference? && args.key?(attribute.name)
 
-            target = referenced_aggregate(attribute)
-            next unless target
-
-            validate_reference_values(domain, target, held, list: attribute.list?)
+            validate_reference_argument(domain, attribute, args[attribute.name])
           end
         end
 
@@ -34,31 +27,54 @@ module Hecks
         # @raise [Runtime::NotFound] if a reference names an identity that does not exist
         # @raise [Runtime::Unauthorized] if a referenced record belongs to another tenant
         def resolve_state_references(domain, construct, state)
-          own_tenant_field = tenant_field_for(construct)
+          boundary = TenantBoundary.new(self, domain, construct, state, tenant_field_for(construct))
 
           construct.attributes.each do |attribute|
             next unless attribute.reference?
 
-            held = state[attribute.name]
-            validate_relationship_cardinality(construct, attribute, held)
-            next if held.nil?
+            resolve_state_reference(domain, construct, attribute, state, boundary)
+          end
+
+          resolve_entity_references(domain, construct, state)
+        end
 
-            target = referenced_aggregate(attribute)
-            next unless target
+        # One reference-typed argument's value, refused unless its target identity exists.
+        def validate_reference_argument(domain, attribute, held)
+          return if held.nil?
 
-            validate_reference_values(domain, target, held, list: attribute.list?)
-            enforce_tenant_boundary(domain, construct, attribute, target, held, state, own_tenant_field)
-          end
+          target = referenced_aggregate(attribute)
+          validate_reference_values(domain, target, held, list: attribute.list?) if target
+        end
 
+        # One reference-typed attribute of settled state: cardinality, target and tenant.
+        def resolve_state_reference(domain, construct, attribute, state, boundary)
+          held = state[attribute.name]
+          validate_relationship_cardinality(construct, attribute, held)
+          return if held.nil?
+
+          target = referenced_aggregate(attribute)
+          return unless target
+
+          validate_reference_values(domain, target, held, list: attribute.list?)
+          enforce_tenant_boundary(boundary, attribute, target, held)
+        end
+
+        # Re-checks the rows of each entity list `construct` holds, as their own constructs.
+        def resolve_entity_references(domain, construct, state)
           Array(construct.entities).each do |entity|
-            field = construct.attribute(Naming.snake(entity.hecks_name).to_sym) ||
-                    construct.attributes.find { |attribute| attribute.type.to_s == entity.hecks_name.to_s }
+            field = entity_list_field(construct, entity)
             next unless field
 
             Array(state[field.name]).each { |row| resolve_state_references(domain, entity, row) }
           end
         end
 
+        # The attribute of `construct` that holds `entity`'s rows, by name or by type.
+        def entity_list_field(construct, entity)
+          construct.attribute(Naming.snake(entity.hecks_name).to_sym) ||
+            construct.attributes.find { |attribute| attribute.type.to_s == entity.hecks_name.to_s }
+        end
+
         # `has_one` and `belongs_to` require a target unless optional. Checked on state,
         # since a command may leave the field untouched.
         def validate_relationship_cardinality(construct, attribute, held)
@@ -95,33 +111,8 @@ module Hecks
 
         # Refuses a write whose record and referenced record disagree about their tenant.
         # Hooked into `resolve_state_references` so both interpreters are covered.
-        def enforce_tenant_boundary(domain, construct, attribute, target, held, state, own_tenant_field)
-          return unless own_tenant_field && state.key?(own_tenant_field)
-
-          target_tenant_field = tenant_field_for(target)
-          return unless target_tenant_field
-
-          own_tenant = Ports::Query::InMemory.comparable(state[own_tenant_field])
-
-          values = attribute.list? ? Array(held) : [held]
-          values.each do |value|
-            key = reference_key(value)
-            next if key.empty?
-
-            record = @registry.repository(domain, target).find(key)
-            next unless record&.state&.key?(target_tenant_field)
-
-            target_tenant = Ports::Query::InMemory.comparable(record.state[target_tenant_field])
-            next if target_tenant == own_tenant
-
-            raise Unauthorized,
-                  RefusalWording.render_site("Unauthorized", "cross_tenant_reference",
-                                             aggregate: construct.hecks_name, field: own_tenant_field,
-                                             tenant: Rendering.describe(state[own_tenant_field]),
-                                             attribute: attribute.name, target: target.name,
-                                             target_field: target_tenant_field,
-                                             other: Rendering.describe(record.state[target_tenant_field]))
-          end
+        def enforce_tenant_boundary(boundary, attribute, target, held)
+          boundary.enforce(attribute, target, held, tenant_field_for(target))
         end
 
         # The field a query names in `authorize policy, tenant: :field`, or nil.
@@ -156,19 +147,30 @@ module Hecks
           owner.attributes.each_with_object({}) do |attribute, hydrated|
             next unless attribute.reference?
 
-            id = source[attribute.name]
-            next if id.nil?
-
-            target = referenced_aggregate(attribute)
-            next unless target
-
-            record = @registry.repository(domain, target).find(id.to_s)
+            target, record = dereferenced_record(domain, attribute, source)
             next unless record
 
-            name = attribute.name.to_s.sub(/_id\z/, "").to_sym
-            hydrated[name] = record.state.merge(dereference(domain, target, record.state, depth: depth - 1))
+            hydrated[dereferenced_name(attribute)] =
+              record.state.merge(dereference(domain, target, record.state, depth: depth - 1))
           end
         end
+
+        def dereferenced_name(attribute)
+          attribute.name.to_s.delete_suffix("_id").to_sym
+        end
+
+        # The target aggregate and stored record a reference argument names, or nil when it names
+        # nothing that exists.
+        def dereferenced_record(domain, attribute, source)
+          id = source[attribute.name]
+          return if id.nil?
+
+          target = referenced_aggregate(attribute)
+          return unless target
+
+          record = @registry.repository(domain, target).find(id.to_s)
+          [target, record] if record
+        end
       end
     end
   end

data/lib/hecks/runtime/command_rules/tenant_boundary.rb

@@ -0,0 +1,69 @@
+require_relative "../errors"
+require_relative "../refusal_wording"
+require_relative "../../rendering"
+require_relative "../../ports/query/in_memory"
+
+module Hecks
+  module Runtime
+    class CommandRules
+      # Refuses a write whose record and referenced record disagree about their tenant. One
+      # instance covers one record's state, so every reference it holds is checked against the
+      # same tenant.
+      class TenantBoundary
+        # @param rules [Runtime::CommandRules] the rules engine, for its registry and key rendering
+        # @param domain [String, Symbol] the domain the record belongs to
+        # @param construct [Bluebook::Aggregate, Bluebook::Entity] the record's declaring construct
+        # @param state [Hash{Symbol => Object}] the record's settled state
+        # @param own_field [Symbol, nil] the record's tenant field, nil when it declares none
+        def initialize(rules, domain, construct, state, own_field)
+          @rules     = rules
+          @domain    = domain
+          @construct = construct
+          @state     = state
+          @own_field = own_field
+        end
+
+        # Checks every record `held` names through `attribute` against the record's own tenant.
+        #
+        # @param attribute [Bluebook::Attribute] the reference-typed attribute
+        # @param target [Bluebook::Aggregate] the aggregate the reference points at
+        # @param held [Object, Array<Object>] the reference value (or values, for a list)
+        # @param target_field [Symbol, nil] the target's tenant field, nil when it declares none
+        # @return [void]
+        # @raise [Runtime::Unauthorized] a referenced record belongs to another tenant
+        def enforce(attribute, target, held, target_field)
+          return unless @own_field && @state.key?(@own_field) && target_field
+
+          own_tenant = Ports::Query::InMemory.comparable(@state[@own_field])
+          (attribute.list? ? Array(held) : [held]).each do |value|
+            record = referenced_record(target, value)
+            refuse_crossing(attribute, target, target_field, record) if crosses?(record, target_field, own_tenant)
+          end
+        end
+
+        private
+
+        # Whether the record carries a tenant that differs from `own_tenant`.
+        def crosses?(record, target_field, own_tenant)
+          record&.state&.key?(target_field) &&
+            Ports::Query::InMemory.comparable(record.state[target_field]) != own_tenant
+        end
+
+        def referenced_record(target, value)
+          key = @rules.reference_key(value)
+          @rules.registry.repository(@domain, target).find(key) unless key.empty?
+        end
+
+        def refuse_crossing(attribute, target, target_field, record)
+          raise Unauthorized,
+                RefusalWording.render_site("Unauthorized", "cross_tenant_reference",
+                                           aggregate: @construct.hecks_name, field: @own_field,
+                                           tenant: Rendering.describe(@state[@own_field]),
+                                           attribute: attribute.name, target: target.name,
+                                           target_field: target_field,
+                                           other: Rendering.describe(record.state[target_field]))
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/dependency_planning/analyzer.rb

@@ -0,0 +1,90 @@
+require_relative "mutation_analysis"
+require_relative "rule_analysis"
+
+module Hecks
+  module Runtime
+    module DependencyPlanning
+      # Static dependency analysis for one command: derives a Plan without executing it.
+      # CommandInterpreter and EntityInterpreter consult it before choosing a dispatch strategy.
+      class Analyzer
+        include MutationAnalysis
+        include RuleAnalysis
+
+        STATEFUL_MUTATIONS = MutationAnalysis::STATEFUL_MUTATIONS
+
+        # `root_aggregate:` is the owner a `parent.*` read resolves against. An entity-owned
+        # command passes `aggregate:` as the entity, whose fields never include root-level ones.
+        #
+        # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] the construct the command
+        #   is dispatched against; an entity for an entity-owned command
+        # @param command [Bluebook::Command] the command to analyze
+        # @param root_aggregate [Bluebook::Aggregate] the owning aggregate a `parent.*` read
+        #   resolves against; defaults to `aggregate` for a plain-aggregate command
+        # @return [Hecks::Runtime::DependencyPlanning::Plan] the derived, frozen plan
+        def self.call(aggregate:, command:, root_aggregate: aggregate) = new(aggregate, command, root_aggregate).call
+
+        # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] the construct the command
+        #   is dispatched against
+        # @param command [Bluebook::Command] the command to analyze
+        # @param root_aggregate [Bluebook::Aggregate] the owning aggregate `parent.*` reads
+        #   resolve against; defaults to `aggregate`
+        def initialize(aggregate, command, root_aggregate = aggregate)
+          @aggregate = aggregate
+          @command = command
+          @owner_fields = owner_field_names(aggregate)
+          @root_owner_fields = owner_field_names(root_aggregate)
+          @payload_fields = command.attributes.to_set(&:name)
+          @state_reads, @payload_reads, @writes, @known_writes, @unresolved = Array.new(5) { Set.new }
+        end
+
+        # Runs the analysis and derives the command's dependency plan.
+        #
+        # @return [Hecks::Runtime::DependencyPlanning::Plan] the derived, frozen plan
+        def call
+          analyze_initial_state
+          analyze_mutations
+          analyze_lifecycle
+          analyze_command_rules
+          add_preservation_reads
+
+          build_plan(unresolved.empty? && owner_fields.subset?(known_writes))
+        end
+
+        private
+
+        attr_reader :aggregate, :command, :owner_fields, :root_owner_fields, :payload_fields,
+                    :state_reads, :payload_reads, :writes, :known_writes, :unresolved
+
+        # The fields a rule may read off `construct`: its attributes, its lifecycle field, and its
+        # `projects` fields. A projected field is owner state: a rule reading one reads this
+        # record's stored field. Left out of `known_writes` so `add_preservation_reads` keeps it
+        # as a read; the interpreter reseeds it on save.
+        def owner_field_names(construct)
+          fields = construct.attributes.to_set(&:name)
+          fields << construct.lifecycle.field.to_sym if construct.lifecycle
+          construct.projected_fields.each { |field| fields << field.name } if construct.respond_to?(:projected_fields)
+          fields
+        end
+
+        def analyze_command_rules
+          analyze_rules(command.givens, phase: :before)
+          analyze_rules(command.ensures, phase: :after)
+          analyze_rules(aggregate.invariants, phase: :after)
+        end
+
+        def build_plan(complete)
+          Plan.new(
+            read_set:                sorted(state_reads),
+            write_set:               sorted(writes),
+            payload_read_set:        sorted(payload_reads),
+            complete_state:          complete,
+            state_independent:       complete && state_reads.empty?,
+            unresolved_dependencies: unresolved.to_a.sort.freeze
+          ).freeze
+        end
+
+        def sorted(values) = values.to_a.sort.freeze
+      end
+    end
+  end
+end

data/lib/hecks/runtime/dependency_planning/expression_reads.rb

@@ -0,0 +1,73 @@
+require_relative "../../bluebook/expression"
+
+module Hecks
+  module Runtime
+    module DependencyPlanning
+      # Collects the dotted paths a canonical expression reads, without evaluating it.
+      # Used by Analyzer to classify rule dependencies.
+      module ExpressionReads
+        module_function
+
+        # Paths by canonical text: parsing is a pure function of the text, and the analyzer asks
+        # for the same rule text on every dispatch of a command. A text that fails to parse
+        # raises before it is stored, so a failure is never cached. Written from dispatch
+        # threads, so every access holds PATHS_LOCK; the cache is cleared when it reaches
+        # PATHS_CACHE_LIMIT entries, so distinct texts cannot grow it without bound.
+        # rubocop:disable-next Style/MutableConstant
+        PATHS_CACHE = {}
+        PATHS_LOCK = Mutex.new
+        PATHS_CACHE_LIMIT = 4096
+        private_constant :PATHS_CACHE, :PATHS_LOCK
+
+        # Finds every dotted path a canonical expression reads.
+        #
+        # Walks the parsed nodes the evaluator uses; only Lookup nodes carry dependencies.
+        #
+        # @param canonical [String] the canonical expression text
+        # @return [Array<String>] the dotted paths the expression reads (frozen)
+        def paths(canonical)
+          cached = PATHS_LOCK.synchronize { PATHS_CACHE[canonical] }
+          return cached if cached
+
+          found = collect(Bluebook::Expression::Evaluator.parse(canonical), Set.new).freeze
+          PATHS_LOCK.synchronize do
+            PATHS_CACHE.clear if PATHS_CACHE.size >= PATHS_CACHE_LIMIT && !PATHS_CACHE.key?(canonical)
+            PATHS_CACHE[canonical] ||= found
+          end
+        end
+
+        # Walks one parsed node, skipping names bound by an enclosing block predicate.
+        def collect(node, bound_names)
+          case node
+          when Bluebook::Expression::Resolver::Lookup
+            collect_lookup(node, bound_names)
+          when Bluebook::Expression::Resolver::BlockPredicate
+            collect_block(node, bound_names)
+          when Struct, Array
+            collect_children(node, bound_names)
+          else
+            []
+          end
+        end
+
+        # A block predicate's receiver reads under the outer names; its predicate also under the
+        # parameter the block binds.
+        def collect_block(node, bound_names)
+          collect(node.receiver, bound_names) +
+            collect(node.predicate, bound_names | [node.param.to_s])
+        end
+
+        def collect_children(node, bound_names)
+          children = node.is_a?(Struct) ? node.each_pair.map { |_name, value| value } : node
+          children.flat_map { |value| collect(value, bound_names) }
+        end
+
+        # The path a lookup reads, unless its root is a name an enclosing block bound.
+        def collect_lookup(node, bound_names)
+          root = node.path.to_s.split(".", 2).first
+          bound_names.include?(root) ? [] : [node.path.to_s]
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/dependency_planning/mutation_analysis.rb

@@ -0,0 +1,89 @@
+module Hecks
+  module Runtime
+    module DependencyPlanning
+      class Analyzer
+        # What a command's mutations read and write, and what a fresh record already holds.
+        # Mixed into {Analyzer}, which owns the sets these methods fill.
+        module MutationAnalysis
+          STATEFUL_MUTATIONS = %i[append increment decrement multiply clamp remove].freeze
+
+          private
+
+          # A fresh Instance supplies these values without a stored record; keep aligned with
+          # Instance.defaults/default_for. They are not command mutations, so not in write_set.
+          def analyze_initial_state
+            aggregate.attributes.each do |attribute|
+              known_writes << attribute.name if deterministic_initial_value?(attribute)
+            end
+
+            known_writes << aggregate.lifecycle.field.to_sym if aggregate.lifecycle
+          end
+
+          def deterministic_initial_value?(attribute)
+            return true if declared_without_prior_state?(attribute)
+            return false unless aggregate.respond_to?(:value_object)
+
+            value_object = aggregate.value_object(attribute.type)
+            value_object&.attributes&.all? { |field| !field.default.nil? }
+          end
+
+          def declared_without_prior_state?(attribute)
+            attribute.list? || attribute.optional? || !attribute.default.nil?
+          end
+
+          def analyze_mutations
+            command.mutations.each { |mutation| analyze_mutation(mutation) }
+          end
+
+          def analyze_mutation(mutation)
+            target = mutation.target.to_sym
+            writes << target
+
+            if owner_fields.include?(target)
+              analyze_operation(mutation, target)
+            else
+              unresolved << "mutation target #{target} is not an aggregate field"
+            end
+          end
+
+          def analyze_operation(mutation, target)
+            if mutation.op == :set
+              known_writes << target if analyze_source?(mutation.source)
+            elsif STATEFUL_MUTATIONS.include?(mutation.op)
+              state_reads << target
+              analyze_source?(mutation.source)
+            else
+              unresolved << "mutation operation #{mutation.op} has no dependency rule"
+            end
+          end
+
+          # True only when the source is known without prior state. Hash sources are append
+          # bindings.
+          def analyze_source?(source)
+            case source
+            when Symbol
+              analyze_symbol_source?(source)
+            when Hash
+              source.values.map { |value| analyze_source?(value) }.all?
+            else
+              true
+            end
+          end
+
+          def analyze_symbol_source?(source)
+            if payload_fields.include?(source)
+              payload_reads << source
+              true
+            elsif owner_fields.include?(source)
+              state_reads << source
+              false
+            else
+              unresolved << "mutation source #{source} has no payload or aggregate field"
+              false
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/dependency_planning/rule_analysis.rb

@@ -0,0 +1,82 @@
+require_relative "expression_reads"
+
+module Hecks
+  module Runtime
+    module DependencyPlanning
+      class Analyzer
+        # What a command's lifecycle, givens, ensures and invariants read. Mixed into
+        # {Analyzer}, which owns the sets these methods fill.
+        module RuleAnalysis
+          private
+
+          def analyze_lifecycle
+            lifecycle = aggregate.lifecycle
+            return unless lifecycle
+
+            state_reads << lifecycle.field if command.from
+            record_lifecycle_write(lifecycle) unless lifecycle.transitions_for(command.hecks_name).empty?
+          end
+
+          def record_lifecycle_write(lifecycle)
+            writes << lifecycle.field
+            known_writes << lifecycle.field
+          end
+
+          def analyze_rules(rules, phase:)
+            rules.each do |rule|
+              ExpressionReads.paths(rule.canonical).each { |path| classify_path(path, phase) }
+            rescue ArgumentError => e
+              unresolved << "expression #{rule.canonical.inspect} could not be analyzed: #{e.message}"
+            end
+          end
+
+          # Gap: the `as:` name bound by `corrects` is not special-cased like `:old`/`:parent`, so a
+          # rule reading it lands in `unresolved` and dispatch takes the safe `hydrate_existing`
+          # path. Runtime binding is unaffected.
+          def classify_path(path, phase)
+            head, nested = path.split(".", 2)
+            name = head.to_sym
+
+            case name
+            when :parent
+              # `parent.X` names the root aggregate's field, not the entity's `owner_fields`;
+              # the two sets are identical for a plain aggregate command.
+              resolve_nested_state_read!(path, nested, root_owner_fields, "does not name parent aggregate state")
+            when :old
+              resolve_nested_state_read!(path, nested, owner_fields, "does not name prior aggregate state")
+            else
+              classify_named_path(path, name, phase)
+            end
+          end
+
+          def classify_named_path(path, name, phase)
+            if payload_fields.include?(name)
+              payload_reads << name
+            elsif owner_fields.include?(name)
+              state_reads << name if phase == :before || !known_writes.include?(name)
+            else
+              unresolved << "expression path #{path} has no payload or aggregate field"
+            end
+          end
+
+          # Shared by the `:parent`/`:old` branches: checks the nested field against `field_set`
+          # and records a state read, or refuses with `message`.
+          def resolve_nested_state_read!(path, nested, field_set, message)
+            field = nested.to_s.split(".", 2).first
+            if field.empty? || !field_set.include?(field.to_sym)
+              unresolved << "#{path} #{message}"
+            else
+              state_reads << field.to_sym
+            end
+          end
+
+          # A partial mutation must preserve every untouched field, so those prior values are
+          # reads even when no rule names them.
+          def add_preservation_reads
+            state_reads.merge(owner_fields - known_writes)
+          end
+        end
+      end
+    end
+  end
+end