hecks 2.9.0 → 3.0.0

data/lib/hecks/runtime/dependency_planning.rb

@@ -46,14 +46,32 @@ module Hecks
       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
+        # @return [Array<String>] the dotted paths the expression reads (frozen)
         def paths(canonical)
-          collect(Bluebook::Expression::Evaluator.parse(canonical), Set.new)
+          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.

data/lib/hecks/runtime/dispatcher.rb

@@ -1,5 +1,6 @@
 require_relative "errors"
 require_relative "refusal_wording"
+require_relative "reaction_outcome"
 require_relative "caller"
 require_relative "invocation"
 require_relative "command_rules"
@@ -19,7 +20,36 @@ module Hecks
     class Dispatcher
       MAX_REACTION_DEPTH = 5
 
-      Result = Struct.new(:verb, :instance, :events, :execution_plan, :persistence_outcome, keyword_init: true) do
+      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)
@@ -126,6 +156,14 @@ module Hecks
       end
 
       def dispatch_invocation(verb, to:, with:, saga_correlation:, flat:)
+        @registry.collecting_reactions do |reactions|
+          dispatch_collecting(verb, reactions, to: to, with: with, saga_correlation: saga_correlation, flat: flat)
+        end
+      end
+      private :dispatch_invocation
+
+      # One dispatch, with `reactions` receiving every reaction its events cause.
+      def dispatch_collecting(verb, reactions, to:, with:, saga_correlation:, flat:)
         domain, aggregate_name, command_name = parse(verb)
         aggregate = resolve_aggregate(domain, aggregate_name, verb)
 
@@ -161,9 +199,21 @@ module Hecks
         react(announced, domain, aggregate, outbox_rows)
 
         Result.new(verb: verb, instance: instance, events: announced,
-                   execution_plan: execution_plan, persistence_outcome: persistence_outcome)
+                   execution_plan: execution_plan, persistence_outcome: persistence_outcome,
+                   refused_reactions: refused_from(reactions),
+                   blocking_reactions: ReactionOutcome.blocking(reactions, event_of: @registry.method(:reaction_event)),
+                   reaction_defects: ReactionOutcome.defects(reactions))
       end
-      private :dispatch_invocation
+      private :dispatch_collecting
+
+      # The reactions among `logged` that the domain refused, as plain facts.
+      #
+      # A crash in a reaction is a defect, not a refusal, and is warned where it happens.
+      def refused_from(logged)
+        logged.select { |entry| entry[:delivered] == false && !entry[:defect] }
+              .map { |entry| entry.slice(:policy, :trigger, :reason) }
+      end
+      private :refused_from
 
       # Runs the policy and saga reactions owed because `announced` committed.
       #

data/lib/hecks/runtime/interpreting.rb

@@ -62,6 +62,9 @@ module Hecks
           next unless normalized.key?(attribute.name)
 
           Value.refuse_object_reference(command, attribute, normalized[attribute.name])
+          # A has_many argument mirrors the aggregate's reference list, which words its own refusal.
+          reference_list = aggregate.attribute(attribute.name)&.reference?
+          Value.refuse_scalar_list(command, attribute, normalized[attribute.name]) unless reference_list
           normalized[attribute.name] = Value.for_attribute(aggregate, attribute, normalized[attribute.name], argument: true)
         end
       end

data/lib/hecks/runtime/loader.rb

@@ -1,4 +1,4 @@
-require_relative "../facade/surface"
+require_relative "../doors/ruby_door"
 require_relative "../ports/loading"
 require_relative "../ports/persistence"
 require_relative "dispatcher"
@@ -11,18 +11,23 @@ module Hecks
     # Boots a domain: loads its bluebook directory into a fresh Registry, runs
     # every boot gate, and hands back the bound Dispatcher (or RemoteDispatcher).
     class Loader
+      # Default for a boot's `environment:` keyword: read `HECKS_ENVIRONMENT`. An explicit
+      # `nil` means no overlay, whatever the variable holds.
+      FROM_ENV = :from_env
+
       # Boots `path`: loads its bluebook directory into a fresh Registry, runs
       # every registered boot gate, and returns the bound dispatcher. Pass
-      # `install_facade: false` to skip the `Widget::Item.Add(...)` global
+      # `install_doors: false` to skip the `Widget::Item.Add(...)` global
       # facade sugar (only a caller dispatching by FQN string needs to).
       #
       # @param path [String] a domain directory to boot
       # @param shared [String, nil] shared ports/adapters root; nil walks up from `path`
-      # @param environment [String, nil] environment overlay loaded after the domain; nil for none
+      # @param environment [String, nil] environment overlay loaded after the domain; defaults
+      #   to `HECKS_ENVIRONMENT`, and an explicit nil loads none
       # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted dispatcher
       # @raise [Errno::ENOENT] if `path` names no domain directory
       # @raise [Runtime::WiringError] if a boot gate finds a wiring problem
-      def self.boot(path, shared: nil, install_facade: true, environment: nil)
+      def self.boot(path, shared: nil, install_doors: true, install_facade: nil, environment: FROM_ENV)
         loading   = Ports::Loading.bootstrap
         directory = loading.bluebook_directory(path)
         root      = loading.shared_root(shared, directory)
@@ -31,14 +36,55 @@ module Hecks
         Hecks.with_registry(registry) do
           loading.load_library
           loading.load_project(root)
-          loading.load_domain(directory, environment: environment)
+          loading.load_domain(directory, environment: selected_environment(environment))
         end
 
         run_boot_gates!(registry, directory)
         dispatcher = dispatcher_for(registry)
         redrive_outbox!(dispatcher)
         seed_privacy_markings!(dispatcher, registry)
-        install_facade ? bind_runtime(dispatcher) : dispatcher
+        Doors.install?(install_doors, install_facade) ? bind_runtime(dispatcher) : dispatcher
+      end
+
+      # What `describe` answers: the loaded declarations and nothing bound to run them.
+      Described = Struct.new(:registry)
+
+      # Loads `path`'s declarations into a fresh Registry and stops: no boot gate runs, no
+      # persistence adapter is resolved or bound, nothing connects to a database.
+      #
+      # This is what answers a question about the domain's own shape (its verbs, arguments and
+      # usage) in any environment, including one where the bound adapter cannot load.
+      #
+      # @param path [String] a domain directory to read
+      # @param shared [String, nil] shared ports/adapters root; nil walks up from `path`
+      # @param environment [String, nil] environment overlay loaded after the domain
+      # @return [Described] answers `registry` like a booted dispatcher does
+      # @raise [Errno::ENOENT] if `path` names no domain directory
+      def self.describe(path, shared: nil, environment: FROM_ENV)
+        loading   = Ports::Loading.bootstrap
+        directory = loading.bluebook_directory(path)
+        root      = loading.shared_root(shared, directory)
+        registry  = Registry.new(root: File.dirname(directory))
+
+        Hecks.with_registry(registry) do
+          loading.load_library
+          loading.load_project(root)
+          loading.load_domain(directory, environment: selected_environment(environment))
+        end
+        Described.new(registry)
+      end
+
+      # The overlay a boot loads: the caller's own choice (nil meaning none), else the
+      # `HECKS_ENVIRONMENT` variable when the caller left the keyword at its default. A domain
+      # with no `environments/<name>.*` files ignores either.
+      #
+      # @param environment [String, nil, Symbol] the overlay a caller passed, or `FROM_ENV`
+      # @return [String, nil] the overlay name; nil for none
+      def self.selected_environment(environment)
+        return environment unless environment == FROM_ENV
+
+        named = ENV["HECKS_ENVIRONMENT"].to_s.strip
+        named.empty? ? nil : named
       end
 
       # Redrives pending outbox rows after the dispatcher and saga
@@ -77,10 +123,11 @@ module Hecks
       #
       # @param paths [Array<String>, String] the exact file paths to boot, in load order
       # @param shared [String, nil] shared ports/adapters root; nil walks up from the first path
-      # @param environment [String, nil] environment overlay loaded after the named files
+      # @param environment [String, nil] environment overlay loaded after the named files;
+      #   defaults to `HECKS_ENVIRONMENT`, and an explicit nil loads none
       # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted dispatcher
       # @raise [Runtime::WiringError] if a boot gate finds a wiring problem
-      def self.boot_files(paths, shared: nil, install_facade: true, environment: nil)
+      def self.boot_files(paths, shared: nil, install_doors: true, install_facade: nil, environment: FROM_ENV)
         loading   = Ports::Loading.bootstrap
         files     = Array(paths).map { |path| File.expand_path(path) }
         directory = File.dirname(files.first)
@@ -90,12 +137,12 @@ module Hecks
         Hecks.with_registry(registry) do
           loading.load_library
           loading.load_project(root)
-          loading.load_selected(files, environment: environment)
+          loading.load_selected(files, environment: selected_environment(environment))
         end
 
         run_boot_gates!(registry, directory)
         dispatcher = dispatcher_for(registry)
-        install_facade ? bind_runtime(dispatcher) : dispatcher
+        Doors.install?(install_doors, install_facade) ? bind_runtime(dispatcher) : dispatcher
       end
 
       # Runs every registered boot gate against `registry`, in order:
@@ -117,7 +164,8 @@ module Hecks
         gates
       end
 
-      # Resolves the Ruby implementation of every adapter a hecksagon binds.
+      # Resolves the Ruby implementation of every adapter a hecksagon binds, and of every
+      # `default_adapter` a world names (a chapter that binds nothing takes its world's).
       # An adapter's implementation can register its own persistence plugin as
       # a side effect of loading (e.g. `PostgresEra`) — resolving here, before
       # gates are collected, is what registers those plugins' gates without
@@ -131,6 +179,11 @@ module Hecks
             next
           end
         end
+        registry.worlds.each_value do |world|
+          registry.adapter_class(world.default_adapter) if world.default_adapter
+        rescue WiringError
+          next
+        end
       end
 
       # A backstop only: fires when a translation declares a `computes`/
@@ -169,7 +222,7 @@ module Hecks
       # `dispatcher`. The binding lives in the facade's own modules, not a
       # class-level global, so two boots in one process don't share one name.
       def self.bind_runtime(dispatcher)
-        Facade::Surface.install(dispatcher)
+        Doors::RubyDoor.install(dispatcher)
         dispatcher
       end
     end

data/lib/hecks/runtime/outbox.rb

@@ -240,7 +240,7 @@ module Hecks
           when "policy"
             policy = @registry.bluebook(home)&.policies&.find { |candidate| candidate.name == name } ||
                      raise(WiringError, "outbox row #{row.delivery_id} names policy #{fqn}, which no bluebook declares")
-            @policies.react(event, row.domain, only: [policy, home])
+            @policies.react(event, row.domain, only: [policy, home], event_uid: row.event_uid)
           when "saga"
             process_manager = @registry.bluebook(home)&.process_managers&.find { |candidate| candidate.name == name } ||
                               raise(WiringError,

data/lib/hecks/runtime/policy_interpreter.rb

@@ -31,15 +31,18 @@ module Hecks
       # @param only [Array(Bluebook::Policy, String), nil] one `[policy, home_domain]`
       #   pair to run exactly (the outbox relay's consumer), instead of scanning every
       #   loaded bluebook for candidates
+      # @param event_uid [String, nil] the outbox uid every consumer of this event shares, when the
+      #   event was rebuilt from an outbox row; otherwise the event object itself is the identity
       # @return [void]
-      def react(event, domain, only: nil)
+      def react(event, domain, only: nil, event_uid: nil)
         selected = only ? [only] : policies_for(event, domain)
         selected.each do |policy, home_domain|
           result = deliver(policy, event, home_domain)
           next if result.nil?
 
           # A for_each policy answers an array; Array(...) would explode a record Hash.
-          (result.is_a?(Array) ? result : [result]).each { |record| @registry.reaction_log << record }
+          identity = event_uid || event.object_id
+          (result.is_a?(Array) ? result : [result]).each { |record| @registry.log_reaction(record, event: identity) }
         end
       end
 

data/lib/hecks/runtime/port_operation_interpreter.rb

@@ -1,3 +1,4 @@
+require_relative "adapter_lookup"
 require_relative "interpreting"
 require_relative "command_interpreter/argument_gate"
 require_relative "event"
@@ -125,16 +126,7 @@ module Hecks
       end
 
       def adapter_for(ctx)
-        name = port_name_for(ctx)
-        implementations = @registry.adapters.values.select { |adapter| adapter.port == name }
-
-        case implementations.size
-        when 1 then Adapters.const_get(implementations.first.name).new
-        when 0 then raise WiringError, "no adapter implements the #{name} port — nothing can answer #{ctx.operation.hecks_name}"
-        else raise WiringError,
-                   "#{implementations.size} adapters implement the #{name} port " \
-                   "(#{implementations.map(&:name).sort.join(', ')}) — the runtime will not choose for you"
-        end
+        AdapterLookup.call(@registry, port_name_for(ctx), asked: ctx.operation.hecks_name)
       end
 
       # Adapters are handed plain data, never a Value.

data/lib/hecks/runtime/query_interpreter.rb

@@ -1,4 +1,5 @@
 require_relative "../naming"
+require_relative "adapter_lookup"
 require_relative "../ports/query"
 require_relative "../ports/query/ordering"
 require_relative "../query_specification/field_path"
@@ -33,6 +34,10 @@ module Hecks
 
         declared = declared_query(aggregate, query_name)
         args = normalize_args(aggregate, declared, args)
+        if (port = aggregate.query_binding(declared.name))
+          return answered_from_outside(aggregate, declared, args, port)
+        end
+
         declared = TenantScope.apply(declared, args)
         # Applied after TenantScope so its tenant clause rides through as an ordinary
         # local clause; it is deliberately not propagated into the hop's inner query.
@@ -66,6 +71,11 @@ module Hecks
 
         declared = declared_query(aggregate, query_name)
         args = normalize_args(aggregate, declared, args)
+        # No records to interpret: the adapter is the only answer there is, and the reference
+        # takes it through the same shape check, so a diff against #call sees only the adapter.
+        port = aggregate.query_binding(declared.name)
+        return answered_from_outside(aggregate, declared, args, port) if port
+
         declared = TenantScope.apply(declared, args)
         reference_interpret(@registry.repository(domain, aggregate).all, declared, args,
                             domain: domain, shape: aggregate)
@@ -73,6 +83,73 @@ module Hecks
 
       private
 
+      # Asks the port's adapter the question the hecksagon bound to this query, by the query's
+      # snake-cased name and with its arguments as plain data. Each row of the answer is built as
+      # the value object the query `returns`, so an answer that is not that shape is refused
+      # before it enters the domain. The aggregate's records are never read.
+      #
+      # @return [Array<Hash>] the rows as the returned value object's fields, frozen
+      # @raise [Runtime::WiringError] if no adapter answers the port or the adapter lacks the method
+      # @raise [Runtime::TypeMismatch, Runtime::InvariantViolation, Runtime::UnknownArgument,
+      #   Runtime::AbsentArgument] naming the query, if the answer is not its declared shape
+      def answered_from_outside(aggregate, declared, args, port)
+        asked = "#{aggregate.hecks_name}.#{declared.name}"
+        refuse_offered_arguments!(declared, args, asked)
+        adapter = AdapterLookup.call(@registry, port.name, asked: asked)
+        method  = Naming.snake(declared.name)
+        # The real adapter's class is what must answer; a fuzz replay's stand-in refuses instead.
+        klass   = AdapterLookup.adapter_class(@registry, port.name, asked: asked)
+        AdapterLookup.check_answers!(klass, port.name, method, declared, asked: asked)
+
+        answer = adapter.public_send(method, **Value.materialize(args))
+        Freezer.deep(shaped(aggregate, declared, answer, asked))
+      end
+
+      # Refuses arguments the adapter cannot be handed: a required one left out, or one the query
+      # does not declare. The adapter is asked by keyword, so either would otherwise reach it as a
+      # raw ArgumentError.
+      #
+      # @raise [Runtime::AbsentArgument] if a non-optional declared argument is missing
+      # @raise [Runtime::UnknownArgument] if `args` names an argument the query does not declare
+      def refuse_offered_arguments!(declared, args, asked)
+        names   = declared.attributes.map { |attribute| attribute.name.to_sym }
+        offered = args.keys.map(&:to_sym)
+        unknown = (offered - names).sort
+        unless unknown.empty?
+          raise UnknownArgument, RefusalWording.render_site("UnknownArgument", "unknown_args",
+                                                            command: asked, unknown: unknown, declared: names)
+        end
+
+        required = declared.attributes.reject(&:optional?).map { |attribute| attribute.name.to_sym }
+        absent   = (required - offered).sort
+        return if absent.empty?
+
+        raise AbsentArgument, RefusalWording.render_site("AbsentArgument", "absent_args",
+                                                         command: asked, absent: absent, declared: names)
+      end
+
+      # Builds the adapter's answer as the declared value object: one row, or a list of rows for
+      # `returns list_of(...)`. A refusal keeps its class and gains the query's name.
+      def shaped(aggregate, declared, answer, asked)
+        value_object = Value.value_object_for(aggregate, declared.returns_name) or
+          raise WiringError, "#{asked} returns #{declared.returns_name.inspect}, which the aggregate " \
+                             "declares no value object for"
+        offered = declared.returns_list? ? answer : [answer]
+        unless offered.is_a?(Array) && offered.all?(Hash)
+          raise TypeMismatch, "#{asked} answered outside the domain, but #{answer.class} is not " \
+                              "#{declared.returns_list? ? 'a list of' : 'a'} #{value_object.hecks_name} row"
+        end
+
+        offered.map { |row| answered_row(value_object, row, aggregate, declared, asked) }
+      end
+
+      # One row of an outside answer, built and validated as the returned value object.
+      def answered_row(value_object, row, aggregate, declared, asked)
+        Value.build(value_object, row, aggregate).to_h
+      rescue TypeMismatch, InvariantViolation, UnknownArgument, AbsentArgument => e
+        raise e.class, "#{asked} answered outside the domain, but not as its #{declared.returns} — #{e.message}"
+      end
+
       def declared_query(aggregate, query_name)
         aggregate.query(query_name) ||
           raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "no_query",

data/lib/hecks/runtime/reaction_outcome.rb

@@ -0,0 +1,89 @@
+require_relative "refusal_wording"
+
+module Hecks
+  module Runtime
+    # Tells a refused policy reaction that blocks a run from one that is a benign non-match.
+    #
+    # A policy pair such as `RecordTheMatch` / `RecordTheDrift` reacts to one event with two
+    # commands on one aggregate, each `given`-gated so exactly one applies; the other is refused
+    # by design and the run passed. A refusal is benign when another reaction to the same event
+    # instance delivered a different command on the same aggregate: an alternative took over. It
+    # is also benign when the creating command it triggered reports the record already exists (a
+    # re-run's idempotent registration: the record the run wanted is there). Every other refusal
+    # (a release's `Accept` refused by a dirty tree, with no alternative) blocks the outcome. A
+    # crash (`defect`) is never a refusal: it is warned where it happens and listed by
+    # `defects`.
+    module ReactionOutcome
+      # A reaction entry, with the identity of the event instance it answered, when known.
+      Row = Struct.new(:fields, :event) do
+        def delivered = fields[:delivered]
+      end
+
+      module_function
+
+      # Picks the refused reactions that block the run.
+      #
+      # An alternative counts only when it answered the same event instance, which `event_of`
+      # reads (an outbox uid, or the event object's id). Without it (a remote host's JSON carries
+      # no event identity) the event's name is all there is to match.
+      #
+      # @param entries [Array<Hash>] every reaction one dispatch caused, delivered or not; keys
+      #   are Symbols (local) or Strings (a remote host's JSON)
+      # @param event_of [#call, nil] maps an entry, as given, to the event instance it answered
+      # @return [Array<Hash{Symbol => Object}>] `{ policy:, trigger:, reason: }` per blocker
+      def blocking(entries, event_of: nil)
+        rows = Array(entries).map { |entry| Row.new(entry.transform_keys(&:to_sym), event_of&.call(entry)) }
+        rows.select { |row| row.delivered == false && !row.fields[:defect] }
+            .reject { |row| already_there?(row) }
+            .reject { |row| rows.any? { |other| alternative?(row, other) } }
+            .map { |row| row.fields.slice(:policy, :trigger, :reason) }
+      end
+
+      # Whether `row` is its own creating command reporting the record already exists.
+      def already_there?(row)
+        RefusalWording.already_exists?(row.fields[:reason], **creating(row.fields[:trigger]))
+      end
+
+      # Whether `other` delivered a different command on the aggregate `refused` targeted, in
+      # answer to the same event.
+      def alternative?(refused, other)
+        other.delivered == true && same_event?(refused, other) &&
+          other.fields[:trigger] != refused.fields[:trigger] &&
+          aggregate_of(other.fields[:trigger]) == aggregate_of(refused.fields[:trigger])
+      end
+
+      # Whether both reactions answered one event: the same instance when both are known, else
+      # the same event name.
+      def same_event?(refused, other)
+        return false unless other.fields[:on] == refused.fields[:on]
+
+        refused.event.nil? || other.event.nil? || refused.event == other.event
+      end
+
+      # The `Domain::Aggregate` part of a `Domain::Aggregate.Command` trigger.
+      def aggregate_of(trigger) = trigger.to_s.split(".").first
+
+      # The command and aggregate a trigger names, spelled as the AlreadyExists sentence does.
+      def creating(trigger)
+        target, command = trigger.to_s.split(".", 2)
+        return { command: target&.split("::")&.last } unless command
+
+        { command: command.split(".").last, aggregate: target.split("::").last }
+      end
+
+      # Picks the reactions that crashed, which no refusal rule excuses.
+      #
+      # A chain that crashes halfway leaves its record short of the state the run was meant to
+      # reach, so a caller that waits on the run must treat every one as a failure.
+      #
+      # @param entries [Array<Hash>] every reaction one dispatch caused, keys as for `blocking`
+      # @return [Array<Hash{Symbol => Object}>] `{ policy:, trigger:, reason:, error_class: }`
+      #   per crashed reaction
+      def defects(entries)
+        Array(entries).map { |entry| entry.transform_keys(&:to_sym) }
+                      .select { |row| row[:defect] }
+                      .map { |row| row.slice(:policy, :trigger, :reason, :error_class) }
+      end
+    end
+  end
+end

data/lib/hecks/runtime/refusal_wording.rb

@@ -19,6 +19,28 @@ module Hecks
         substitute(template(refusal, site), values)
       end
 
+      # Whether `reason` is the AlreadyExists refusal for a duplicate creation, matched by the
+      # template's own wording so a remote host's reason reads the same as a local one.
+      #
+      # With `command` (and `aggregate`), the sentence must be that command's own: text that only
+      # resembles the template but names another command is not a duplicate creation.
+      #
+      # @param reason [String, nil] the refusal message
+      # @param command [String, nil] the bare name of the creating command that was refused
+      # @param aggregate [String, nil] the bare name of the aggregate it creates
+      # @return [Boolean]
+      def already_exists?(reason, command: nil, aggregate: nil)
+        given   = { "command" => command, "aggregate" => aggregate }
+        pieces  = TEMPLATES.fetch(%w[AlreadyExists creating_duplicate]).split(/(\{\w+\})/, -1)
+        pattern = pieces.map do |piece|
+          name = piece[/\A\{(\w+)\}\z/, 1]
+          next Regexp.escape(piece) unless name
+
+          given[name] ? Regexp.escape(given[name]) : ".*"
+        end.join
+        Regexp.new("\\A#{pattern}\\z", Regexp::MULTILINE).match?(reason.to_s)
+      end
+
       # Renders a site's template from raw `arguments`, formatting each per its row.
       # Raises ArgumentError on a missing or undeclared argument, KeyError on an unknown site.
       def render_site(refusal, site, **arguments)
@@ -65,7 +87,7 @@ module Hecks
         end
       end
 
-      # Read lazily: bin/project_vocabulary boots this file before it writes these rows.
+      # Read lazily: hecks project_vocabulary boots this file before it writes these rows.
       def argument_rows(refusal, site)
         @argument_rows ||= Hecks::Vocabulary.rows("RefusalSiteArgument")
                                             .group_by { |row| [row["refusal"], row["site"]] }