hecks 3.5.0 → 3.6.0

data/lib/hecks/runtime/dependency_planning.rb

@@ -40,256 +40,9 @@ module Hecks
           ATOMIC_PUT
         end
       end
-
-      # 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
-            root = node.path.to_s.split(".", 2).first
-            bound_names.include?(root) ? [] : [node.path.to_s]
-          when Bluebook::Expression::Resolver::BlockPredicate
-            collect(node.receiver, bound_names) +
-              collect(node.predicate, bound_names | [node.param.to_s])
-          when Struct
-            node.each_pair.flat_map { |_name, value| collect(value, bound_names) }
-          when Array
-            node.flat_map { |value| collect(value, bound_names) }
-          else
-            []
-          end
-        end
-      end
-
-      # Static dependency analysis for one command: derives a Plan without executing it.
-      # CommandInterpreter and EntityInterpreter consult it before choosing a dispatch strategy.
-      class Analyzer
-        STATEFUL_MUTATIONS = %i[append increment decrement multiply clamp remove].freeze
-
-        # `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 = aggregate.attributes.to_set(&:name)
-          @owner_fields << aggregate.lifecycle.field.to_sym if aggregate.lifecycle
-          @root_owner_fields = root_aggregate.attributes.to_set(&:name)
-          @root_owner_fields << root_aggregate.lifecycle.field.to_sym if root_aggregate.lifecycle
-          # `projects` fields are 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. `parent.*` reads may name the root's too.
-          aggregate.projected_fields.each { |field| @owner_fields << field.name } if aggregate.respond_to?(:projected_fields)
-          if root_aggregate.respond_to?(:projected_fields)
-            root_aggregate.projected_fields.each do |field|
-              @root_owner_fields << field.name
-            end
-          end
-          @payload_fields = command.attributes.to_set(&:name)
-          @state_reads = Set.new
-          @payload_reads = Set.new
-          @writes = Set.new
-          @known_writes = Set.new
-          @unresolved = 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_rules(command.givens, phase: :before)
-          analyze_rules(command.ensures, phase: :after)
-          analyze_rules(aggregate.invariants, phase: :after)
-          add_preservation_reads
-
-          complete = unresolved.empty? && owner_fields.subset?(known_writes)
-          independent = complete && state_reads.empty?
-
-          Plan.new(
-            read_set:                sorted(state_reads),
-            write_set:               sorted(writes),
-            payload_read_set:        sorted(payload_reads),
-            complete_state:          complete,
-            state_independent:       independent,
-            unresolved_dependencies: unresolved.to_a.sort.freeze
-          ).freeze
-        end
-
-        private
-
-        attr_reader :aggregate, :command, :owner_fields, :root_owner_fields, :payload_fields,
-                    :state_reads, :payload_reads, :writes, :known_writes, :unresolved
-
-        # 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 attribute.list? || attribute.optional? || !attribute.default.nil?
-          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 analyze_mutations
-          command.mutations.each do |mutation|
-            target = mutation.target.to_sym
-            writes << target
-
-            unless owner_fields.include?(target)
-              unresolved << "mutation target #{target} is not an aggregate field"
-              next
-            end
-
-            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
-        end
-
-        # True only when the source is known without prior state. Hash sources are append bindings.
-        def analyze_source?(source)
-          case source
-          when Symbol
-            if payload_fields.include?(source)
-              payload_reads << source
-              return true
-            end
-            if owner_fields.include?(source)
-              state_reads << source
-              return false
-            end
-
-            unresolved << "mutation source #{source} has no payload or aggregate field"
-            false
-          when Hash
-            source.values.map { |value| analyze_source?(value) }.all?
-          else
-            true
-          end
-        end
-
-        def analyze_lifecycle
-          lifecycle = aggregate.lifecycle
-          return unless lifecycle
-
-          state_reads << lifecycle.field if command.from
-
-          return if lifecycle.transitions_for(command.hecks_name).empty?
-
-          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
-
-          if name == :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")
-          elsif name == :old
-            resolve_nested_state_read!(path, nested, owner_fields, "does not name prior aggregate state")
-          elsif 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
-
-        def sorted(values) = values.to_a.sort.freeze
-      end
     end
   end
 end
+
+require_relative "dependency_planning/expression_reads"
+require_relative "dependency_planning/analyzer"

data/lib/hecks/runtime/dispatcher/queries.rb

@@ -0,0 +1,62 @@
+require_relative "../errors"
+require_relative "../refusal_wording"
+
+module Hecks
+  module Runtime
+    class Dispatcher
+      # Answers declared queries: aggregate queries, entity queries and read models. Mixed into
+      # {Dispatcher}, which owns the interpreters and the verb parsing these read.
+      module Queries
+        # Answers a declared query: an aggregate query, an entity query, or a read model.
+        #
+        # `"Domain.ReadModel"` (no `::`) is a read model; `"Domain::Aggregate.Query"` and
+        # `"Domain::Aggregate.Entity.Query"` are aggregate and entity queries.
+        #
+        # @param verb [String, Symbol] the query's verb, in one of the three shapes above
+        # @param args [Hash{Symbol => Object}] the query's declared arguments
+        # @return [Array<Hash>] one Hash per matching record or element; a read model returns a
+        #   one-element Array holding a Hash of head name to projected rows
+        # @raise [Runtime::UnknownVerb] if the verb is malformed or names something undeclared
+        # @raise [Runtime::NotFound] if a read model's root reference names no record
+        # @raise [Runtime::TypeMismatch] if an argument cannot be coerced to its declared type
+        def query(verb, **args)
+          domain, query_name = verb.to_s.split(".", 2)
+          return read_model_query(domain, query_name, verb, args) if query_name && !domain.include?("::")
+
+          domain, aggregate_name, query_name = parse(verb)
+          aggregate = resolve_aggregate(domain, aggregate_name, verb)
+
+          @queries.call(domain, aggregate, query_name, args)
+        end
+
+        # Answers an aggregate or entity query through the reference interpreter alone.
+        #
+        # Never answered by the bound adapter's native hook; the fuzzer's query oracle diffs it
+        # against `#query`. Read models have no reference twin.
+        #
+        # @param verb [String] `"Domain::Aggregate.Query"` or `"Domain::Aggregate.Entity.Query"`
+        # @param args [Hash{Symbol => Object}] the query's declared arguments
+        # @return [Array<Hash>] one Hash per matching record or element
+        # @raise [Runtime::UnknownVerb] if the verb is malformed or names something undeclared
+        # @raise [Runtime::TypeMismatch] if an argument cannot be coerced to its declared type
+        def reference_query(verb, **args)
+          domain, aggregate_name, query_name = parse(verb)
+          aggregate = resolve_aggregate(domain, aggregate_name, verb)
+
+          @queries.reference_call(domain, aggregate, query_name, args)
+        end
+
+        private
+
+        def read_model_query(domain, query_name, verb, args)
+          bluebook = @registry.bluebook(domain) ||
+                     raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "no_domain", domain: domain, verb: verb))
+          model = bluebook.read_model(query_name) ||
+                  raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "no_read_model",
+                                                                domain: domain, query: query_name))
+          @read_models.call(domain, model, args)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/dispatcher/result.rb

@@ -0,0 +1,55 @@
+module Hecks
+  module Runtime
+    class Dispatcher
+      # What one dispatch settled on: the verb, the record, the events it announced, and what its
+      # reactions did.
+      Result = Struct.new(:verb, :instance, :events, :execution_plan, :persistence_outcome,
+                          :refused_reactions, :blocking_reactions, :reaction_defects,
+                          keyword_init: true) do
+        # Lists the policy reactions this dispatch caused that the domain refused.
+        #
+        # A policy's trigger that a `given` or invariant refuses does not undo the command that
+        # fired it, which has already persisted, so the outcome above stays a success. The
+        # refusal is recorded here instead of vanishing into the reaction log.
+        #
+        # @return [Array<Hash{Symbol => Object}>] one `{ policy:, trigger:, reason: }` per refused
+        #   reaction, oldest first; empty when every reaction was delivered
+        def refused_reactions = self[:refused_reactions] || []
+
+        # Lists the refused reactions that block the run, as opposed to a benign non-match.
+        #
+        # See `ReactionOutcome`: a refusal is benign when a sibling reaction to the same event
+        # delivered another command on the same aggregate. `--wait` exits 1 on any that remain.
+        #
+        # @return [Array<Hash{Symbol => Object}>] the subset of `refused_reactions` that blocks
+        def blocking_reactions = self[:blocking_reactions] || []
+
+        # Lists the reactions that crashed, as opposed to being refused by the domain.
+        #
+        # A crash is warned and never re-raised, since the emitting command has persisted; it is
+        # recorded here so `--wait` can fail on a chain that stopped halfway.
+        #
+        # @return [Array<Hash{Symbol => Object}>] `{ policy:, trigger:, reason:, error_class: }`
+        #   per crashed reaction; empty when none crashed
+        def reaction_defects = self[:reaction_defects] || []
+
+        # Reads the identity of the record the dispatch settled on.
+        #
+        # @return [String, nil] the record's identity; nil for a port operation (no record)
+        def id    = instance&.id
+
+        # Reads the settled record's attributes as one Hash.
+        #
+        # @return [Hash{Symbol => Object}, nil] the record's state; nil for a port operation
+        def state = instance&.to_h
+
+        def to_s
+          announced = events.empty? ? "no events" : events.map(&:name).join(", ")
+          "#{verb} → #{instance.inspect} | #{announced}"
+        end
+
+        def inspect = "#<Result #{self}>"
+      end
+    end
+  end
+end

data/lib/hecks/runtime/dispatcher/routing.rb

@@ -0,0 +1,107 @@
+require_relative "../errors"
+require_relative "../refusal_wording"
+require_relative "../invocation"
+require_relative "../../naming"
+
+module Hecks
+  module Runtime
+    class Dispatcher
+      # Finds what a verb names and runs it through the interpreter that owns it. Mixed into
+      # {Dispatcher}, which holds the interpreters and the registry these read.
+      module Routing
+        # One dispatch request as the caller spelled it: the verb, its receiver and facts, and
+        # the saga correlation to stamp on emitted events.
+        Call = Struct.new(:verb, :to, :with, :saga_correlation, :flat, keyword_init: true)
+
+        private
+
+        # Sends the call to the interpreter that owns its verb.
+        #
+        # @return [Array] the instance, announced events, execution plan, persistence outcome, and
+        #   the outbox rows (`:enqueue` for a port operation, which saves nothing)
+        def route(call, domain, aggregate, aggregate_name, command_name)
+          return route_aggregate(call, domain, aggregate, aggregate_name, command_name) unless command_name.include?(".")
+
+          head, sub = command_name.split(".", 2)
+          port = aggregate.port(head)
+          # Ports are checked before entities, so a port wins a name an entity also declares.
+          return route_port(call, domain, aggregate, port.operation(sub) || no_operation!(head, sub)) if port
+
+          route_entity(call, domain, aggregate, command_name)
+        end
+
+        def no_operation!(port_name, operation_name)
+          raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "port_no_operation",
+                                                        port: port_name, operation: operation_name))
+        end
+
+        # No instance comes back: a port operation hydrates and saves nothing.
+        def route_port(call, domain, aggregate, operation)
+          [nil, run_port_operation(call, domain, aggregate, operation), nil, nil, :enqueue]
+        end
+
+        def run_port_operation(call, domain, aggregate, operation)
+          invocation = Invocation.from_call(call.verb, to: call.to, with: call.with, flat: call.flat,
+                                                       receiver: :port, aggregate: aggregate) { operation }
+          @port_ops.call(domain, aggregate, operation, invocation)
+        end
+
+        def route_entity(call, domain, aggregate, command_name)
+          resolution = nil
+          invocation = Invocation.from_call(call.verb, to: call.to, with: call.with, flat: call.flat,
+                                                       receiver: :entity, entity_depth: command_name.count(".")) do
+            (resolution = EntityInterpreter::Resolution.of(aggregate, command_name)).command
+          end
+          @entities.call(domain, aggregate, resolution, invocation)
+        end
+
+        def route_aggregate(call, domain, aggregate, aggregate_name, command_name)
+          command = command_of(aggregate, aggregate_name, command_name)
+          invocation = Invocation.from_call(call.verb, to: call.to, with: call.with, flat: call.flat) { command }
+          @commands.call(domain, aggregate, command, invocation, call.saga_correlation)
+        end
+
+        # The entity half of `dry_run?`: refuses a port verb, which has no in-memory form.
+        # `to:`/`with:` are not keywords here; a key named either is an ordinary fact.
+        def dry_run_entity(call, domain, aggregate, command_name)
+          if aggregate.port(command_name.split(".", 2).first)
+            raise WiringError,
+                  "#{call.verb} names a port operation — dry_run? has no in-memory form for one, " \
+                  "only for aggregate and entity commands"
+          end
+
+          resolution = nil
+          invocation = Invocation.from_call(call.verb, to: nil, with: nil, flat: call.flat, receiver: :entity) do
+            (resolution = EntityInterpreter::Resolution.of(aggregate, command_name)).command
+          end
+          @entities.call(domain, aggregate, resolution, invocation, dry_run: true)
+        end
+
+        def dry_run_aggregate(call, domain, aggregate, aggregate_name, command_name)
+          command = command_of(aggregate, aggregate_name, command_name)
+          invocation = Invocation.from_call(call.verb, to: nil, with: nil, flat: call.flat) { command }
+          @commands.call(domain, aggregate, command, invocation, dry_run: true)
+        end
+
+        def parse(verb)
+          Naming.split_verb(verb) ||
+            raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "not_fully_qualified", verb: verb))
+        end
+
+        def command_of(aggregate, aggregate_name, command_name)
+          aggregate.command(command_name) ||
+            raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "aggregate_no_command",
+                                                          aggregate: aggregate_name, command: command_name))
+        end
+
+        def resolve_aggregate(domain, aggregate_name, verb)
+          bluebook = @registry.bluebook(domain) ||
+                     raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "no_domain", domain: domain, verb: verb))
+          bluebook.aggregate(aggregate_name) ||
+            raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "no_aggregate",
+                                                          domain: domain, aggregate: aggregate_name))
+        end
+      end
+    end
+  end
+end