hecks 5.0.0 → 7.0.0

data/lib/hecks/runtime/dispatcher.rb

@@ -13,7 +13,11 @@ require_relative "saga_interpreter"
 require_relative "outbox"
 require_relative "dispatcher/result"
 require_relative "dispatcher/routing"
+require_relative "dispatcher/validating"
 require_relative "dispatcher/queries"
+require_relative "declarations"
+require_relative "dry_run_plan"
+require_relative "dispatcher/planning"
 require_relative "../naming"
 
 module Hecks
@@ -22,7 +26,10 @@ module Hecks
     # and saga reactions its events trigger; tracks reaction depth to bound cascades.
     class Dispatcher
       include Routing
+      include Validating
       include Queries
+      include Declarations
+      include Planning
 
       MAX_REACTION_DEPTH = 5
 
@@ -63,6 +70,10 @@ module Hecks
       # @return [Array<Hash{Symbol => Object}>]
       def sagas = @registry.saga_log
 
+      # The interpreter that moves sagas through their stages, for `resume` and redelivery.
+      # @return [SagaInterpreter]
+      def saga_interpreter = @sagas
+
       # Exposes the raw inputs each saga dispatch bound its arguments from (Ruby-only).
       #
       # @return [Array<Hash{Symbol => Object}>]
@@ -74,6 +85,12 @@ module Hecks
       #   `:with_spec` and `:args`
       def policy_dispatches = @registry.policy_dispatch_log
 
+      # Exposes what each cross-domain (`across`) policy was about to deliver (Ruby-only).
+      #
+      # @return [Array<Hash{Symbol => Object}>] entries keyed `:policy`, `:target_verb` and
+      #   `:payload`
+      def cross_domain_deliveries = @registry.cross_domain_log
+
       # Lists every verb the loaded bluebooks declare.
       #
       # @return [Array<String>] sorted
@@ -97,8 +114,8 @@ module Hecks
 
       # Dispatches a verb whose receiver and facts arrive together in one flat Hash.
       #
-      # The wire form: Symbol keys `:to`, `:with` and `:saga_correlation` are lifted out as
-      # the keywords of `dispatch`; every other key, including a String "to", is a fact.
+      # The wire form: Symbol keys `:to`, `:with`, `:saga_correlation` and `:dispatch_key` are
+      # lifted out as the keywords of `dispatch`; every other key, even a String "to", is a fact.
       #
       # @param verb [String] the fully qualified verb, in any shape `dispatch` accepts
       # @param args [Hash] the facts plus the optional Symbol keys above; not mutated
@@ -106,11 +123,7 @@ module Hecks
       # @raise [Runtime::UnknownVerb] if the verb is malformed or names something undeclared
       # @raise [StandardError] a `Runtime::DOMAIN_REFUSALS` class when the domain refuses
       def dispatch_flat(verb, args = {})
-        facts = args.dup
-        to = facts.delete(:to)
-        with = facts.delete(:with)
-        saga_correlation = facts.delete(:saga_correlation)
-        dispatch_invocation(Call.new(verb: verb, to: to, with: with, saga_correlation: saga_correlation, flat: facts))
+        dispatch_invocation(flat_call(verb, args))
       end
 
       # Answers whether a command would succeed right now, without saving, emitting or reacting.
@@ -126,16 +139,7 @@ module Hecks
       # @raise [Runtime::UnknownVerb] if the verb is malformed or names something undeclared
       # @raise [StandardError] any `Runtime::DOMAIN_REFUSALS` class the real dispatch would raise
       def dry_run?(verb, **args)
-        domain, aggregate_name, command_name = parse(verb)
-        aggregate = resolve_aggregate(domain, aggregate_name, verb)
-        call = Call.new(verb: verb, flat: args)
-
-        if command_name.include?(".")
-          dry_run_entity(call, domain, aggregate, command_name)
-        else
-          dry_run_aggregate(call, domain, aggregate, aggregate_name, command_name)
-        end
-
+        dry_run_call(Call.new(verb: verb, flat: args))
         true
       end
 
@@ -150,7 +154,6 @@ module Hecks
       # @raise [Runtime::UnknownVerb] if the domain, aggregate, port or operation is undeclared
       # @raise [Runtime::TypeMismatch] if no receiving identity is found, or `to:`/`with:` is bad
       # @raise [Runtime::NotFound] if the receiving record does not exist
-      # rubocop:disable-next Metrics/ParameterLists -- the public dispatcher's parts, one argument per verb segment
       def dispatch_port(domain, aggregate_name, port_name, operation_name, to: nil, with: nil, flat: {})
         verb = "#{domain}::#{aggregate_name}.#{port_name}.#{operation_name}"
         aggregate = resolve_aggregate(domain, aggregate_name, verb)
@@ -166,23 +169,30 @@ module Hecks
       # Dispatches a reaction's command one level deeper in the cascade, as the system.
       #
       # The ambient caller is cleared (Runtime::Caller.without) so the triggering caller's role
-      # neither satisfies nor blocks the reaction. Depth lives in `Thread.current`, not an ivar
-      # or Mutex: the dispatcher is shared across threads and cascades re-enter on one thread.
-      # The depth limit is checked by the reacting interpreter, not here.
+      # neither satisfies nor blocks the reaction. Depth lives in `Thread.current`, not an ivar or
+      # Mutex: the dispatcher is shared across threads. The reacting interpreter checks the limit.
       #
       # @param verb [String] the fully qualified verb of the reaction's target command
       # @param saga_correlation [Hash{String => Object}, nil] set when a saga leg dispatches
-      # @param args [Hash{Symbol => Object}] flat facts, read as `dispatch_flat` reads them
+      # @param dispatch_key [String, nil] the saga dispatch's identity (`DispatchClaim.key`)
+      # @param args [Hash{Symbol => Object}] flat facts, as `dispatch_flat` reads them
       # @return [Runtime::Dispatcher::Result] the nested dispatch's result
       # @raise [StandardError] any `Runtime::DOMAIN_REFUSALS` class; interpreters rescue these
-      def reenter(verb, saga_correlation: nil, **args)
+      def reenter(verb, saga_correlation: nil, dispatch_key: nil, **args)
         depth = Thread.current[:hecks_reaction_depth].to_i
         Thread.current[:hecks_reaction_depth] = depth + 1
-        Caller.without { dispatch_flat(verb, args.merge(saga_correlation: saga_correlation)) }
+        Caller.without { dispatch_flat(verb, args.merge(saga_correlation: saga_correlation, dispatch_key: dispatch_key)) }
       ensure
         Thread.current[:hecks_reaction_depth] = depth
       end
 
+      # Finishes the saga legs a crash cut short in every domain whose sagas persist.
+      #
+      # @return [void]
+      def redrive_sagas!
+        @registry.saga_domains.each { |domain| @sagas.redrive_stalled(domain) }
+      end
+
       # Answers whether the calling thread's reaction cascade is as deep as it may go.
       #
       # @return [Boolean] true once nested `reenter` calls on this thread reach the limit
@@ -214,6 +224,7 @@ module Hecks
 
       def result_of(verb, settled, reactions)
         instance, announced, execution_plan, persistence_outcome, = settled
+        warn_blocked(reactions)
         Result.new(verb: verb, instance: instance, events: announced,
                    execution_plan: execution_plan, persistence_outcome: persistence_outcome,
                    refused_reactions: refused_from(reactions),
@@ -221,6 +232,17 @@ module Hecks
                    reaction_defects: ReactionOutcome.defects(reactions))
       end
 
+      # Says on stderr which reactions the domain refused and nothing excused, so a policy that
+      # did not take is seen by the caller, not only found later in the reaction log. Only the
+      # outermost dispatch speaks: a nested reaction's refusal is reported once, by its root.
+      def warn_blocked(reactions)
+        return unless Thread.current[:hecks_reaction_depth].to_i.zero?
+
+        ReactionOutcome.blocking(reactions, event_of: @registry.method(:reaction_event)).each do |row|
+          warn "[hecks] reaction #{row[:policy]} was refused (#{row[:trigger]}): #{row[:reason]}"
+        end
+      end
+
       # 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.

data/lib/hecks/runtime/dry_run_plan.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Runtime
+    # What an in-memory dispatch would have written and announced, collected while the dispatch
+    # runs. The command interpreter reports each save and each emitted event here when it runs
+    # in dry mode, so every command gets a plan from the same seam with no per-command code.
+    module DryRunPlan
+      KEY = :hecks_dry_run_plan
+
+      module_function
+
+      # Runs the block and returns the lines it would have produced.
+      #
+      # @yield the in-memory dispatch
+      # @return [Array<String>] one `would …` line per write or event, in order
+      def collect
+        previous = Thread.current[KEY]
+        Thread.current[KEY] = []
+        yield
+        Thread.current[KEY]
+      ensure
+        Thread.current[KEY] = previous
+      end
+
+      # Records one write the dispatch would make.
+      #
+      # @param aggregate [Bluebook::Aggregate] the aggregate the record belongs to
+      # @param instance [Runtime::Instance] the record the dispatch would write
+      # @return [void]
+      def write(aggregate, instance)
+        record("would write #{aggregate.hecks_name} #{instance.id}")
+      end
+
+      # Records one event the dispatch would announce.
+      #
+      # @param name [String] the event's name
+      # @return [void]
+      def emit(name)
+        record("would emit #{name}")
+      end
+
+      # Records each event a command announces.
+      #
+      # @param command [Bluebook::Command] the command the dispatch runs
+      # @return [void]
+      def emits(command)
+        command.emits.each { |name| emit(name) }
+      end
+
+      # Appends a line when a plan is being collected; otherwise does nothing.
+      #
+      # @param line [String]
+      # @return [void]
+      def record(line)
+        Thread.current[KEY]&.push(line)
+      end
+    end
+  end
+end

data/lib/hecks/runtime/entity_element/location.rb

@@ -12,12 +12,20 @@ module Hecks
       module Location
         # One step down the chain: the owner holding the list, the entity whose elements it
         # holds, the container the list is read from, and how the element is named.
-        Hop = Struct.new(:root_aggregate, :owner, :entity, :command_name, :container, :args, :routed_identity)
+        Hop = Struct.new(:root_aggregate, :owner, :entity, :command_name, :container, :args, :routed_identity) do
+          # @return [String] the entity's declared name
+          def entity_name = entity.hecks_name
+
+          # @return [String] the declared name of the construct holding the list
+          def owner_name = owner.hecks_name
+
+          # @return [Array<String, Symbol>] the entity's declared identity paths
+          def identity_paths = entity.identity_paths
+        end
 
         # Walks `chain` one hop at a time and returns the located element (or `instance`
         # itself when `chain` is empty). `route`, when given, offers each hop's identity
         # before falling back to `args`.
-        # rubocop:disable-next Metrics/ParameterLists -- the positional entry point EntityInterpreter and delegation call
         def locate_chain(root_aggregate, chain, instance, args, command_name, route = nil)
           container = instance
           owner     = root_aggregate
@@ -33,8 +41,7 @@ module Hecks
         # stored Hash, not a dispatch payload).
         def element_identity(entity, element)
           parts = entity.identity_paths.map do |path|
-            head = path.to_s.split(".").first.to_sym
-            Identity.scalar(path, element[head])
+            Identity.scalar(path, element[Identity.head(path)])
           end
 
           Naming.identity(parts)
@@ -74,8 +81,8 @@ module Hecks
         # The `[head, path, wanted value, raw]` the dispatch's arguments name for each part of
         # the entity's identity.
         def identity_wants(hop)
-          hop.entity.identity_paths.map do |path|
-            head = path.to_s.split(".").first.to_sym
+          hop.identity_paths.map do |path|
+            head = Identity.head(path)
             raw  = hop.args[head] || refuse_no_identity(hop)
 
             [head, path, wanted_value(hop, head, raw), raw]
@@ -112,9 +119,9 @@ module Hecks
           container = hop.container
           raise NotFound, RefusalWording.render_site(
             "NotFound", "entity_element_missing",
-            entity: hop.entity.hecks_name, identity: Identity.reading(hop.entity),
+            entity: hop.entity_name, identity: Identity.reading(hop.entity),
             wants: wants&.map { |_h, path, _want, raw| Identity.scalar(path, raw) }&.join(", "),
-            aggregate: hop.owner.hecks_name,
+            aggregate: hop.owner_name,
             parent_id: container.respond_to?(:id) ? container.id.inspect : Rendering.describe(container)
           )
         end

data/lib/hecks/runtime/entity_element/mutations.rb

@@ -16,6 +16,9 @@ module Hecks
           def attribute = entity.attribute(target)
           def source_value = rules.resolve_source(mutation.source, args)
           def current = pre[target]
+
+          # @return [Symbol] the mutation's op (`:increment`, `:set`, ...)
+          def op = mutation.op
         end
 
         # The handler each mutation op dispatches to. `corrects` applies nothing here: the target
@@ -34,7 +37,6 @@ module Hecks
         # Applies one declared mutation to an entity element, in place. `pre` is the
         # element as it stood before this command: every read goes through it, every
         # write lands on `element`.
-        # rubocop:disable-next Metrics/ParameterLists -- the positional signature callers (and specs) wrap
         def apply_to_element(rules, aggregate, entity, element, mutation, args, pre = element)
           handler = OP_HANDLERS.fetch(mutation.op) do
             # Backstop: an unhandled op must refuse, not silently apply nothing.
@@ -92,7 +94,7 @@ module Hecks
 
         def apply_arithmetic(app)
           apply_numeric(app) do |current, amount|
-            app.rules.arithmetic(current, amount, app.target, app.rules.sign_of(app.mutation.op))
+            app.rules.arithmetic(current, amount, app.target, app.rules.sign_of(app.op))
           end
         end
 

data/lib/hecks/runtime/entity_interpreter/enforcement.rb

@@ -31,7 +31,7 @@ module Hecks
         # built once and read pre-mutation by enforce_givens.
         def step_enforce_ensures(ctx)
           step(:enforce_ensures) do
-            settled = Instance.new(aggregate: ctx.entity, id: ctx.view.id, state: ctx.element)
+            settled = Instance.new(aggregate: ctx.entity, id: ctx.element_id, state: ctx.element)
             # `correction:` reuses the `as:`-bound bindings `step_enforce_givens`
             # already located; `|| {}` covers a command with no `corrects`
             # mutation, where `ctx.correction_bindings` may be unset.

data/lib/hecks/runtime/entity_interpreter/locating.rb

@@ -19,7 +19,12 @@ module Hecks
           ctx.instance = step(:hydrate_parent) { parent_record(ctx) }
         end
 
+        # A validation records `hydrate_parent`'s refusal and goes on within the stage, so the
+        # parent may be missing here: then there is nothing to locate in, and the one refusal
+        # already recorded is the answer a dispatch raises.
         def step_locate_element(ctx)
+          return unless ctx.instance
+
           ctx.element = step(:locate_element) do
             EntityElement.locate_chain(ctx.aggregate, ctx.chain, ctx.instance, ctx.args, ctx.command_name, ctx.route)
           end
@@ -49,7 +54,7 @@ module Hecks
 
         def parent_identity(ctx)
           aggregate = ctx.aggregate
-          ctx.route&.aggregate ||
+          ctx.routed_identity ||
             Identity.of(aggregate, ctx.args) ||
             Identity.from(aggregate, ctx.args, :id) ||
             raise(NotFound, RefusalWording.render_site("NotFound", "entity_parent_no_identity",

data/lib/hecks/runtime/entity_interpreter/saving.rb

@@ -13,7 +13,7 @@ module Hecks
         # `dry_run:` skips only the persist — the reference-existence check
         # above stays unconditional either way.
         def step_save(ctx)
-          step(:save) { @rules.resolve_state_references(ctx.domain, ctx.aggregate, ctx.instance.state) }
+          step(:save) { @rules.resolve_state_references(ctx.domain, ctx.aggregate, ctx.state) }
 
           return if ctx.dry_run
 
@@ -23,16 +23,16 @@ module Hecks
         def persist_parent(ctx)
           # `expected_version:` is nil for a non-CAS repository or an instance
           # never read from storage — either falls through to a plain save.
-          ctx.persistence_outcome = ctx.repository.save(ctx.instance, expected_version: ctx.instance.version)
-          raise_lost_race(ctx) if ctx.persistence_outcome.status == :stale
+          ctx.persistence_outcome = ctx.repository.save(ctx.instance, expected_version: ctx.instance_version)
+          raise_lost_race(ctx) if ctx.outcome_status == :stale
         end
 
         # Intentionally not a `RefusalWording.render` call — see `Runtime::StaleWrite`'s own
         # comment.
         def raise_lost_race(ctx)
           raise(StaleWrite,
-                "#{ctx.command.hecks_name} on #{ctx.aggregate.hecks_name} " \
-                "(#{Identity.reading(ctx.aggregate)}: #{Rendering.describe(ctx.instance.id)}) lost a race — " \
+                "#{ctx.command_hecks_name} on #{ctx.aggregate_hecks_name} " \
+                "(#{Identity.reading(ctx.aggregate)}: #{Rendering.describe(ctx.instance_id)}) lost a race — " \
                 "another write committed against this record after it was read")
         end
 

data/lib/hecks/runtime/entity_interpreter.rb

@@ -1,4 +1,5 @@
 require_relative "interpreting"
+require_relative "dispatch_context"
 require_relative "../naming"
 require_relative "../rendering"
 require_relative "errors"
@@ -47,11 +48,15 @@ module Hecks
       # `element`/`view` are the entity piece itself, pre- and
       # post-mutation. `:chain` intentionally shadows Enumerable#chain —
       # every read is the struct field, never enumerable-combining.
-      # rubocop:disable-next Lint/StructNewOverride
       Context = Struct.new(:domain, :aggregate, :entity, :entity_name, :command, :command_name,
                            :args, :repository, :instance, :chain, :element, :view, :transition,
                            :old_element, :result, :route, :plan, :persistence_outcome, :dry_run, :outbox_rows,
-                           :correction_bindings, :invocation, keyword_init: true)
+                           :correction_bindings, :invocation, keyword_init: true) do
+        include DispatchContext
+
+        # @return [String] the located element's identity
+        def element_id = view.id
+      end
 
       # @param registry [Runtime::Registry] the booted registry this interpreter reads
       # @param rules [Runtime::CommandRules] the shared rules engine (admissibility,
@@ -149,13 +154,13 @@ module Hecks
       end
 
       def step_apply_mutations(ctx)
-        ctx.old_element = ctx.element.dup unless ctx.command.ensures.empty?
+        ctx.old_element = ctx.element.dup unless ctx.command_ensures.empty?
         step(:apply_mutations) { mutate_element(ctx) }
       end
 
       def mutate_element(ctx)
         pre = ctx.element.dup # the update set reads the element as it stood before mutation
-        ctx.command.mutations.each do |mutation|
+        ctx.command_mutations.each do |mutation|
           EntityElement.apply_to_element(@rules, ctx.aggregate, ctx.entity, ctx.element, mutation, ctx.args, pre)
         end
       end
@@ -163,7 +168,8 @@ module Hecks
       def step_advance_lifecycle(ctx)
         return unless ctx.transition
 
-        step(:advance_lifecycle) { ctx.element[ctx.entity.lifecycle.field] = ctx.transition.target }
+        entity = ctx.entity
+        step(:advance_lifecycle) { ctx.element[entity.lifecycle_field] = ctx.transition_target }
       end
 
       # Entity element helpers (`locate_chain`, `element_of`, `element_identity`,

data/lib/hecks/runtime/errors.rb

@@ -1,3 +1,4 @@
+require_relative "../refused"
 require_relative "value/invariant_violation"
 require_relative "../vocabulary"
 
@@ -8,21 +9,22 @@ module Hecks
   # See `lib/hecks/runtime.rb` for the module's own facade and boot entry points.
   module Runtime
     # A dispatched verb names no aggregate, entity or command.
-    class UnknownVerb < StandardError; end
+    class UnknownVerb < Hecks::Refused; end
     # A settled record failed a command's `ensures`.
-    class EnsuresNotMet < StandardError; end
+    class EnsuresNotMet < Hecks::Refused; end
 
     # A command's `given` refused. `detail` holds the failing comparison's resolved operands
     # ("left: X, right: Y") when the given is a bare comparison, else nil.
     #
     # `detail` rides on `#detailed_message`; `#message` stays byte-for-byte, as specs pin it.
-    class GivenNotMet < StandardError
+    class GivenNotMet < Hecks::Refused
       attr_reader :detail
 
       # @param message [String, nil] the refusal text
       # @param detail [String, nil] the failing comparison's resolved operands, if any
-      def initialize(message = nil, detail: nil)
-        super(message)
+      # @param options [Hash] `attribute:`, `rule:`, `stage:` and `path:`, as `Hecks::Refused` takes
+      def initialize(message = nil, detail: nil, **)
+        super(message, **)
         @detail = detail
       end
 
@@ -36,37 +38,47 @@ module Hecks
     end
 
     # A command addressed a record that does not exist.
-    class NotFound < StandardError; end
+    class NotFound < Hecks::Refused; end
+
     # A command is not admissible from the record's current lifecycle state.
-    class LifecycleRefused < StandardError; end
+    class LifecycleRefused < Hecks::Refused; end
     # An argument carries the wrong kind of value for its declared type.
-    class TypeMismatch < StandardError; end
+    class TypeMismatch < Hecks::Refused; end
     # An argument the command does not declare.
-    class UnknownArgument < StandardError; end
+    class UnknownArgument < Hecks::Refused; end
+
     # An argument the command declares but the call omitted.
-    class AbsentArgument < StandardError; end
+    class AbsentArgument < Hecks::Refused; end
+
     # A creating command whose derived identity already names a record.
-    class AlreadyExists < StandardError; end
+    class AlreadyExists < Hecks::Refused; end
     # A required attribute the stored record predates, with no default or translation to fill it.
     # Raised only by `GuardState`; an optional attribute reads nil instead (ADR 0025).
-    class AttributeAbsent < StandardError; end
+    class AttributeAbsent < Hecks::Refused; end
     # A `projects` field the record predates or no rebuild sweep has populated yet.
     # Raised by `GuardState`.
-    class ProjectionAbsent < StandardError; end
+    class ProjectionAbsent < Hecks::Refused; end
+
     # A query or read model declares `authorize policy, tenant: :field` and the caller omitted it.
-    class Unauthorized < StandardError; end
+    class Unauthorized < Hecks::Refused; end
+
     # A `corrects` command whose target event this record never emitted.
     # Raised by `CommandRules::Admissibility#enforce_correction_target`.
-    class NothingToCorrect < StandardError; end
+    class NothingToCorrect < Hecks::Refused; end
 
     # A CAS write (`expected_version:`) found the stored version moved since the read.
     # A runtime fault, not a domain refusal: the interpreters retry, so it escapes only under
     # sustained contention.
     class StaleWrite < StandardError; end
 
-    # A Lambda-routed domain's refusal (`Runtime::RemoteDispatcher`), with Rust's text verbatim.
+    # A Lambda-routed domain's refusal (`Adapters::Lambda::RemoteDispatcher`), with Rust's text
+    # verbatim.
     # It is not mapped back to a specific class such as GivenNotMet.
-    class RemoteRefusal < StandardError; end
+    class RemoteRefusal < Hecks::Refused; end
+
+    # A wasm plugin's refusal of a question it was asked (`Runtime::WasmPlugin`), with its own
+    # words: a time zone it does not know, a window it will not expand.
+    class PluginRefusal < StandardError; end
 
     # The refusals that are the domain saying no, which a reaction records as undelivered.
     # Anything else is a runtime defect and must propagate rather than read as a refusal.
@@ -74,6 +86,33 @@ module Hecks
     # UnknownVerb is included on purpose: a cross-domain policy fires where its target domain is
     # not loaded. InvariantViolation is included too, so a value object's refusal is declined.
     # Names come from the language; resolving them here fails at load if one is undefined.
+    # Each is a `Hecks::Refused`, and nothing else is, so rescuing either catches the same set.
     DOMAIN_REFUSALS = Hecks::Vocabulary.fetch("DomainRefusal").map { |name| const_get(name) }.freeze
+
+    # The errors that mean the code is wrong, not that the outside world said no: a name that
+    # does not resolve (`NameError`, and `NoMethodError` under it), a value of the wrong class
+    # (`TypeError`), a write to a frozen value (`FrozenError`), and code that would not load
+    # (`ScriptError`: `LoadError`, `NotImplementedError`, `SyntaxError`). An ask that meets one
+    # raises it instead of announcing its `refuses` event, so the defect is seen where it happens.
+    #
+    # `ArgumentError` is left out on purpose: adapters raise its subclasses to refuse input they
+    # were handed (`TenantProvisioner::Refused`, `Composer::Workspace::OutsideWorkspace`), and
+    # parsing outside data raises it (`Integer("x")`, `Date::Error`), so it is the world saying no
+    # as often as it is a wrong call.
+    PROGRAMMING_ERRORS = [NameError, TypeError, FrozenError, ScriptError].freeze
+
+    # @param error [Exception] the error an adapter raised
+    # @return [Boolean] whether `error` is a defect in the code rather than a refusal
+    def self.programming_error?(error) = PROGRAMMING_ERRORS.any? { |kind| error.is_a?(kind) }
+
+    # The refusal text of a failure an ask records: its class and message. An error raised with no
+    # message still names its class, so a refusal never arrives empty.
+    #
+    # @param error [Exception] the error an adapter raised
+    # @return [String] `"Class: message"`, never blank
+    def self.failure_reason(error)
+      message = error.message.to_s.strip
+      "#{error.class}: #{message.empty? ? "raised with no message" : message}"
+    end
   end
 end

data/lib/hecks/runtime/identity.rb

@@ -17,6 +17,15 @@ module Hecks
         hash.key?(sym) ? hash[sym] : hash[key]
       end
 
+      # The attribute an identity path starts at: `:number` for `"number.value"`.
+      #
+      # @param path [String, Symbol] a dotted identity path
+      # @return [Symbol] the path's first segment
+      def head(path)
+        segments = path.to_s.split(".")
+        segments.first.to_sym
+      end
+
       # Digs the fields of `path` out of `held`, past the head the caller consumed.
       # A path with no fields past the head returns `held` unchanged.
       def scalar(path, held)

data/lib/hecks/runtime/instance.rb

@@ -19,7 +19,6 @@ module Hecks
       # `hydrate_with:` replaces the default hydration with a callable that takes the given
       # state and answers the hydrated one (defaults filled), for an adapter that can reuse
       # work across saves.
-      # rubocop:disable-next Metrics/ParameterLists -- the public keyword constructor every caller spells out
       def initialize(aggregate:, id:, state: nil, args: nil, hydrate: true, hydrate_with: nil)
         @aggregate = aggregate
         @id        = id
@@ -45,7 +44,8 @@ module Hecks
           # Frozen so pushing into an untouched list cannot write into the aggregate's state.
           [attr.name, attr.list? ? Freezer.deep([]) : default_for(aggregate, attr)]
         end
-        state[aggregate.lifecycle.field.to_sym] = aggregate.lifecycle.default if aggregate.lifecycle
+        lifecycle = aggregate.lifecycle
+        state[lifecycle.field.to_sym] = lifecycle.default if lifecycle
         state
       end
 
@@ -126,7 +126,7 @@ module Hecks
         return unless args
 
         @aggregate.identity_paths.each do |path|
-          head = path.to_s.split(".").first.to_sym
+          head = Identity.head(path)
           attribute = @aggregate.attribute(head)
           next unless attribute && @state[head].nil?