hecks 4.0.0 → 6.0.0

data/lib/hecks/runtime/row_sweep.rb

@@ -0,0 +1,104 @@
+require_relative "../naming"
+require_relative "errors"
+require_relative "query_interpreter"
+require_relative "refusal_wording"
+
+module Hecks
+  module Runtime
+    # One command sent once per row a declared query answers: what a `for_each` policy and a
+    # bulk run (ADR 0125) share. It reads the rows, says which key of the command addresses a
+    # row, and records one row's delivery or refusal; who sends the command is the caller's.
+    class RowSweep
+      # @param registry [Runtime::Registry] the booted registry the query and command resolve in
+      def initialize(registry)
+        @registry = registry
+      end
+
+      # Runs a declared query and answers its rows.
+      #
+      # @param domain [String] the domain the query's aggregate belongs to
+      # @param aggregate [Bluebook::Aggregate] the aggregate declaring the query
+      # @param query_name [String] the query's name
+      # @param args [Hash{Symbol => Object}] the query's arguments
+      # A query that declares `cursor` answers one page per ask, so every page is read: a sweep
+      # reaches every row the query selects, not only its first `limit`.
+      #
+      # @return [Array<Hash{Symbol => Object}>] each row's state with `:id` merged in
+      def rows(domain, aggregate, query_name, args)
+        interpreter = QueryInterpreter.new(@registry)
+        return Array(interpreter.call(domain, aggregate, query_name, args)) unless aggregate.query(query_name)&.cursor
+
+        every_page(interpreter, domain, aggregate, query_name, args)
+      end
+
+      # The rows of every page of a cursor query, in query order.
+      def every_page(interpreter, domain, aggregate, query_name, args)
+        rows = []
+        after = args[:after]
+        loop do
+          page = interpreter.page(domain, aggregate, query_name, args.merge(after: after))
+          rows.concat(page[:rows])
+          after = page[:after]
+          return rows unless after
+        end
+      end
+
+      # The loaded aggregate a query belongs to.
+      #
+      # @param domain [String] the domain the aggregate belongs to
+      # @param aggregate_name [String] the aggregate's name
+      # @param verb [String] the spelling a refusal names, such as the policy's `for_each`
+      # @return [Bluebook::Aggregate] the aggregate
+      # @raise [Runtime::UnknownVerb] if the domain or aggregate is not loaded
+      def query_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
+
+      # Resolves `target` back to its declared command and asks it how a row of `aggregate_name`
+      # addresses it. Raises rather than guessing: an unaddressable target is an authoring mistake.
+      #
+      # @param target [String] the command's verb, `"Domain::Aggregate.Command"`
+      # @param aggregate_name [String] the aggregate whose rows are swept
+      # @param label [String] how a refusal names `target`
+      # @return [Symbol] the argument a row's id fills
+      # @raise [Runtime::UnknownVerb] if `target` names no declared command
+      # @raise [ArgumentError] if the command cannot be addressed by a row of `aggregate_name`
+      def addressing_key_for(target, aggregate_name, label: "the target")
+        key = target_command(target, label: label).addressing_key_for(aggregate_name)
+        return key if key
+
+        raise ArgumentError,
+              "#{target} cannot be addressed by a row of #{aggregate_name} — it declares no self-reference to " \
+              "#{aggregate_name} and no reference-typed attribute targeting it"
+      end
+
+      # The declared command `target` names.
+      #
+      # @param target [String] the command's verb, `"Domain::Aggregate.Command"`
+      # @param label [String] how a refusal names `target`
+      # @return [Bluebook::Command] the command
+      # @raise [Runtime::UnknownVerb] if `target` names no declared command
+      def target_command(target, label: "the target")
+        domain, aggregate_name, command_name = Naming.split_verb(target)
+        command = @registry.bluebook(domain)&.aggregate(aggregate_name)&.command(command_name)
+        command or raise UnknownVerb, "#{label} #{target.inspect} does not resolve to a declared command"
+      end
+
+      # Sends one row and records how it went: `delivered: true`, or the refusal's message.
+      #
+      # @param record [Hash{Symbol => Object}] the row's record so far, such as `{ for_row: id }`
+      # @yield sends the command for this row
+      # @return [Hash{Symbol => Object}] `record` with `delivered:` and, when refused, `reason:`
+      def deliver(record)
+        yield
+        record.merge(delivered: true)
+      rescue *DOMAIN_REFUSALS => e
+        record.merge(delivered: false, reason: e.message)
+      end
+    end
+  end
+end

data/lib/hecks/runtime/saga_interpreter/compensation.rb

@@ -16,8 +16,9 @@ module Hecks
         def record_compensation(leg, spec, ledger)
           return unless spec.compensates && !ledger.recorded
 
-          resolved = dispatch_args(leg.process_manager, spec.compensates, leg.event, leg.instance, leg.correlation)
-          leg.instance[:completed_compensations] << { command_name: spec.compensates.command_name, args: resolved }
+          compensates = spec.compensates
+          resolved = dispatch_args(leg.process_manager, compensates, leg.event, leg.instance, leg.correlation)
+          leg.instance[:completed_compensations] << { command_name: compensates.command_name, args: resolved }
           checkpoint_leg(leg)
           ledger.recorded = true
         end
@@ -44,7 +45,7 @@ module Hecks
         # failure — `compensation_failed: true` tags a refused compensation
         # distinctly rather than as an ordinary failed delivery.
         def deliver_derived_compensation(leg, entry)
-          record = { process_manager: leg.process_manager.name, instance: leg.correlation,
+          record = { process_manager: leg.saga_name, instance: leg.correlation,
                      dispatch: entry[:command_name] }
           attempts = 0
           loop do
@@ -79,7 +80,7 @@ module Hecks
         end
 
         def abandon_compensation(leg, entry, record, error, attempt)
-          warn "[hecks] defect compensating saga #{leg.process_manager.name} — instance #{leg.correlation.inspect} " \
+          warn "[hecks] defect compensating saga #{leg.saga_name} — instance #{leg.correlation.inspect} " \
                "dispatching #{entry[:command_name]} after #{attempt} attempts: #{error.class}: #{error.message}"
           @registry.saga_log << record.merge(delivered: false, reason: error.message, compensation: true,
                                              defect: true, error_class: error.class.name, compensation_failed: true)

data/lib/hecks/runtime/saga_interpreter/delivery.rb

@@ -18,8 +18,9 @@ module Hecks
         # were bound from, then runs the checkpoint/dispatch/compensation ledger protocol with the
         # retries a crash gets.
         # rubocop:disable-next Metrics/ParameterLists -- spec/runtime/reaction_invocation_spec.rb calls it by name
-        def deliver_saga_dispatch(process_manager, spec, event, instance, correlation, domain)
-          leg    = Leg.new(process_manager, event, domain, correlation, nil, instance)
+        def deliver_saga_dispatch(process_manager, spec, event, instance, correlation, domain, dispatch_key: nil)
+          leg = Leg.new(process_manager, event, domain, correlation, nil, instance)
+          leg.dispatch_key = dispatch_key
           args   = dispatch_args(process_manager, spec, event, instance, correlation)
           record = { process_manager: process_manager.name, instance: correlation, dispatch: spec.command_name }
 
@@ -36,8 +37,8 @@ module Hecks
           process_manager = leg.process_manager
           @registry.saga_dispatch_log << { process_manager: process_manager.name, instance: leg.correlation,
                                            dispatch: spec.command_name,
-                                           on: leg.event.name, correlation_head: process_manager.correlation_head,
-                                           event_payload: leg.event.payload,
+                                           on: leg.event_name, correlation_head: process_manager.correlation_head,
+                                           event_payload: leg.event_payload,
                                            memory: Value.materialize(leg.instance[:memory]),
                                            with_spec: spec.with_spec, args: args }
         end
@@ -83,7 +84,7 @@ module Hecks
         def reenter_dispatch(leg, spec, args)
           reenter_command(leg, spec.command_name, args,
                           explicit:        ReactionInvocation.projection_declared?(spec),
-                          source_receiver: { aggregate: leg.event.aggregate, identity: leg.event.id })
+                          source_receiver: leg.event_source)
         end
 
         # A refusal by the target is a recorded outcome, and the leg
@@ -95,14 +96,16 @@ module Hecks
           nil
         end
 
-        # Dispatches `command_name` through the dispatcher, stamped with this saga's correlation.
+        # Dispatches `command_name` through the dispatcher, stamped with this saga's correlation
+        # and, for a leg's own dispatch, its `dispatch_key`.
         def reenter_command(leg, command_name, projected, explicit:, source_receiver:)
-          head = leg.process_manager.correlation_head
+          head = leg.correlation_head
           verb = qualified(command_name, leg.domain)
           invocation = ReactionInvocation.build(registry: @registry, verb: verb, projected: projected,
                                                 explicit: explicit, passthrough: [head],
                                                 source_receiver: source_receiver)
-          @dispatcher.reenter(verb, saga_correlation: { head.to_s => leg.correlation }, **invocation)
+          stamp = { head.to_s => leg.correlation }
+          @dispatcher.reenter(verb, saga_correlation: stamp, dispatch_key: leg.dispatch_key, **invocation)
         end
 
         # Unlike a refusal, a crash isn't a domain decision, so it
@@ -117,7 +120,7 @@ module Hecks
         # `defect_compensated: true` tags an exhausted retry distinctly, so the log never
         # misrepresents a crash as a decision the domain made.
         def abandon_dispatch(leg, spec, record, error, attempt)
-          warn "[hecks] defect in saga #{leg.process_manager.name} — instance #{leg.correlation.inspect} " \
+          warn "[hecks] defect in saga #{leg.saga_name} — instance #{leg.correlation.inspect} " \
                "dispatching #{spec.command_name} after #{attempt} attempts: #{error.class}: #{error.message}"
           @registry.saga_log << record.merge(delivered: false, reason: error.message, defect: true,
                                              error_class: error.class.name, defect_compensated: true)
@@ -137,7 +140,7 @@ module Hecks
         # `command_name`'s shape — unlike a policy's explicit `target_domain`
         # (set by `across`), a saga's `dispatch`/`compensates` has no such
         # field, and every command a saga fires lands inside its own
-        # bluebook chapter.
+        # bluebook.
         def qualified(command_name, domain)
           "#{domain}::#{command_name}"
         end

data/lib/hecks/runtime/saga_interpreter/redrive.rb

@@ -0,0 +1,141 @@
+require_relative "../outbox"
+
+module Hecks
+  module Runtime
+    class SagaInterpreter
+      # Finishes a saga leg a crash cut short. The pending marker names the moving event and how
+      # many of the leg's dispatches settled, so the ones that never began are delivered now. The
+      # one that may have run is delivered again when its store dedupes by dispatch key or its
+      # command is declared idempotent; otherwise it is reported, since a second delivery could
+      # apply it twice. Mixed into {SagaInterpreter}.
+      module Redrive
+        # One rehydrated instance a crash left mid-leg: its declaration, correlation, home domain,
+        # the instance itself and the marker the crash left on it.
+        Stalled = Struct.new(:process_manager, :correlation, :domain, :instance, :marker) do
+          # @return [String] the instance named the way a warning names it
+          def label = "#{process_manager.name} instance #{correlation.inspect}"
+
+          # @return [String] the declared name of the saga
+          def saga_name = process_manager.name
+
+          # @return [Hash{Symbol => Object}] the log record a leg redriven from this stall opens
+          def record = { process_manager: saga_name, on: marker[:on], instance: correlation, redriven: true }
+
+          # @return [Hash{Symbol => Object}] the log row that reports this stall for a person
+          def stall_row = { process_manager: saga_name, instance: correlation, rehydrated_stalled: true }
+
+          # @return [Integer] how many of the leg's dispatches had settled
+          def settled = marker[:settled].to_i
+
+          # @return [Boolean] whether the dispatch after the settled ones had been started
+          def attempting? = marker[:attempting] ? true : false
+        end
+
+        # Redrives every stalled instance of `domain` the registry rehydrated.
+        #
+        # @param domain [String, Symbol] the domain whose stalled instances are finished
+        # @return [void]
+        def redrive_stalled(domain)
+          bluebook = @registry.bluebook(domain)
+          return unless bluebook
+
+          bluebook.process_managers.each do |process_manager|
+            stalled_instances(process_manager).each do |correlation, instance|
+              redrive_instance(process_manager, correlation, instance, domain)
+            end
+          end
+        end
+
+        private
+
+        def stalled_instances(process_manager)
+          @registry.saga_instances[process_manager.name].select { |_, instance| instance[:stalled] }
+        end
+
+        def redrive_instance(process_manager, correlation, instance, domain)
+          stalled = Stalled.new(process_manager, correlation, domain, instance, instance.delete(:stalled))
+          leg     = stalled_leg(stalled)
+          leg ? resume_leg(leg, stalled) : report_unredrivable(stalled)
+        end
+
+        def resume_leg(leg, stalled)
+          remaining = leg.dispatches.drop(stalled.settled)
+          remaining = withhold_ambiguous(leg, stalled, remaining) if stalled.attempting?
+          deliver_dispatches(leg, remaining, from: leg.dispatches.size - remaining.size)
+          finish_stalled(leg) if leg.progress[:settled] == leg.dispatches.size
+        end
+
+        # The leg the marker describes, or nil when it can't be rebuilt safely: the handler is gone,
+        # or it is an unwinding leg whose derived compensations may be half drained.
+        def stalled_leg(stalled)
+          marker = stalled.marker
+          return nil if marker[:on] == REFUSED && stalled.instance[:completed_compensations].to_a.any?
+
+          handler = stalled.process_manager.handler_for(marker[:on], marker[:from])
+          return nil unless handler && handler.to_state == stalled.instance[:state]
+
+          build_stalled_leg(stalled, handler)
+        end
+
+        def build_stalled_leg(stalled, handler)
+          event = Outbox.event_from(stalled.marker[:event])
+          leg   = Leg.new(stalled.process_manager, event, stalled.domain, stalled.correlation, stalled.record,
+                          stalled.instance)
+          leg.handler = handler
+          leg.pre_state = stalled.marker[:from]
+          leg.progress.merge!(settled: stalled.settled, attempting: false)
+          leg
+        end
+
+        # The marker says the next dispatch was started, so it may have run. It is delivered again
+        # when its store dedupes by dispatch key (the key is the one the first delivery used, so a
+        # second application is skipped) or its command is idempotent; otherwise the leg stays
+        # stalled and is reported.
+        def withhold_ambiguous(leg, stalled, remaining)
+          return remaining if remaining.empty? || redeliverable?(leg.domain, remaining.first.command_name)
+
+          report_ambiguous(leg, stalled, remaining.first)
+          []
+        end
+
+        def report_ambiguous(leg, stalled, spec)
+          warn "[hecks] #{leg.domain} #{stalled.label} stalled before #{spec.command_name} settled: it may " \
+               "already have run, its store does not dedupe dispatches and it is not declared idempotent, so it " \
+               "was not redelivered; reconcile this instance by hand."
+          @registry.saga_log << stalled.stall_row.merge(ambiguous: spec.command_name, pending: stalled.marker)
+          checkpoint_leg(leg, pending: leg.pending_marker.merge(attempting: true))
+        end
+
+        def report_unredrivable(stalled)
+          marker = stalled.marker
+          warn "[hecks] #{stalled.label} stalled mid-leg (#{marker[:on].inspect}, #{marker[:from].inspect} -> " \
+               "#{marker[:to].inspect}) and cannot be redriven safely; reconcile this instance by hand."
+          @registry.saga_log << stalled.stall_row.merge(state: stalled.instance[:state], pending: marker)
+        end
+
+        def finish_stalled(leg)
+          log_leg(leg, redriven: true)
+          clear_pending_marker(leg)
+        end
+
+        # Whether a second delivery of the dispatch is safe: its store dedupes by dispatch key, or
+        # its command says it is idempotent. `command_name` is the dispatch's `Aggregate.Command`;
+        # a command owned by an entity is not found, so it counts as neither.
+        def redeliverable?(domain, command_name)
+          aggregate_name, name = command_name.to_s.split(".", 2)
+          aggregate = @registry.bluebook(domain).aggregates.find { |declared| declared.hecks_name == aggregate_name }
+          return false unless aggregate
+
+          deduped_by_store?(domain, aggregate) || command_idempotent?(aggregate, name)
+        end
+
+        def deduped_by_store?(domain, aggregate) = DispatchClaim.supported?(@registry.repository(domain, aggregate))
+
+        def command_idempotent?(aggregate, name)
+          command = aggregate.commands.find { |declared| declared.hecks_name == name }
+          command ? command.idempotent? : false
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/saga_interpreter/transitions.rb

@@ -24,13 +24,13 @@ module Hecks
         # `@dispatcher.reenter` can recursively re-enter this interpreter on the
         # same thread, and `Mutex` is not reentrant.
         def remembered_leg_taken?(leg)
-          leg.instance = @registry.saga_instances[leg.process_manager.name][leg.correlation]
+          leg.instance = @registry.saga_instances[leg.saga_name][leg.correlation]
           unless leg.instance
             log_leg(leg, advanced: false, reason: "no conversation remembers #{leg.correlation.inspect}")
             return false
           end
 
-          leg_taken?(leg, leg.event.name)
+          leg_taken?(leg, leg.event_name)
         end
 
         # Leg chosen by (event, current state) — read under the mutex so
@@ -63,12 +63,41 @@ module Hecks
           log_leg(leg, advanced: true, from: leg.pre_state, to: leg.instance[:state])
 
           drain_derived_compensations(leg) if drain_compensations
-          leg.handler.dispatches.each do |spec|
-            deliver_saga_dispatch(leg.process_manager, spec, leg.event, leg.instance, leg.correlation, leg.domain)
-          end
+          deliver_dispatches(leg, leg.dispatches, from: 0)
           clear_pending_marker(leg)
         end
 
+        # Delivers `specs` from index `from`, writing the leg's progress ahead of each dispatch and
+        # after it, so a crash leaves the store saying exactly which dispatches never began, which
+        # one may have run, and which settled.
+        def deliver_dispatches(leg, specs, from:)
+          specs.each_with_index do |spec, offset|
+            index = from + offset
+            record_progress(leg, settled: index, attempting: true)
+            deliver_saga_dispatch(leg.process_manager, spec, leg.event, leg.instance, leg.correlation, leg.domain,
+                                  dispatch_key: dispatch_key_for(leg, index))
+            record_progress(leg, settled: index + 1, attempting: false)
+          end
+        end
+
+        # The identity of this leg's `index`th dispatch. Built from the moving event the pending
+        # marker carries, so a redrive after a crash computes the same key the first delivery did.
+        def dispatch_key_for(leg, index)
+          DispatchClaim.key(process_manager: leg.saga_name, correlation: leg.correlation,
+                            trigger: leg.record[:on], event: leg.event, index: index)
+        end
+
+        # Same `.equal?` guard as `clear_pending_marker`: a nested reaction may have ended this
+        # instance, and writing progress would resurrect it.
+        def record_progress(leg, **progress)
+          leg.progress.merge!(progress)
+          @registry.saga_mutex.synchronize do
+            next unless @registry.saga_instances[leg.saga_name][leg.correlation].equal?(leg.instance)
+
+            checkpoint_leg(leg, pending: leg.pending_marker)
+          end
+        end
+
         # Guarded by `.equal?` (not `==`): `deliver_saga_dispatch`'s own
         # `reenter` can trigger this correlation's `ends_on` as a nested
         # reaction, deleting this row before this line runs. Clearing
@@ -76,7 +105,7 @@ module Hecks
         # a reborn instance with a stale one's state.
         def clear_pending_marker(leg)
           @registry.saga_mutex.synchronize do
-            next unless @registry.saga_instances[leg.process_manager.name][leg.correlation].equal?(leg.instance)
+            next unless @registry.saga_instances[leg.saga_name][leg.correlation].equal?(leg.instance)
 
             checkpoint_leg(leg, pending: nil)
           end

data/lib/hecks/runtime/saga_interpreter.rb

@@ -9,6 +9,8 @@ require_relative "errors"
 require_relative "reaction_invocation"
 require_relative "value"
 require_relative "saga_pending_dispatch"
+require_relative "saga_interpreter/redrive"
+require_relative "outbox"
 
 module Hecks
   module Runtime
@@ -20,6 +22,7 @@ module Hecks
       include Transitions
       include Delivery
       include Compensation
+      include Redrive
 
       # The trigger lives on the declaration it triggers — see ProcessManager::REFUSED.
       REFUSED = Bluebook::ProcessManager::REFUSED
@@ -32,6 +35,25 @@ module Hecks
       # instance's correlation, the log record of the move, and — once a leg is taken under the
       # mutex — the instance, the leg's handler and the state it left.
       Leg = Struct.new(:process_manager, :event, :domain, :correlation, :record, :instance, :handler, :pre_state) do
+        # @return [String] the declared name of the saga this leg moves
+        def saga_name = process_manager.name
+
+        # @return [Symbol, String] the field the saga correlates its instances on
+        def correlation_head = process_manager.correlation_head
+
+        # @return [String] the name of the event that moves this leg
+        def event_name = event.name
+
+        # @return [Hash] the moving event's payload
+        def event_payload = event.payload
+
+        # @return [Hash{Symbol => Object}] the moving event's aggregate and identity, the
+        #   receiver a reentered command may fall back to
+        def event_source = { aggregate: event.aggregate, identity: event.id }
+
+        # @return [Array] the dispatches the taken handler declares
+        def dispatches = handler.dispatches
+
         # Moves the instance into the handler's state, remembering the state it left.
         #
         # @param leg_handler [Bluebook::ProcessManager::Handler] the leg being taken
@@ -42,12 +64,22 @@ module Hecks
           instance[:state] = leg_handler.to_state
         end
 
-        # What a crash between the checkpoint and the dispatches leaves behind, to be surfaced
-        # on the next boot.
+        # The identity the leg stamps on the dispatch it is delivering.
+        attr_accessor :dispatch_key
+
+        # How far the leg's dispatches got: how many have settled, and whether the next one has
+        # been started, so a crash can tell a dispatch that never began from one that may have run.
+        #
+        # @return [Hash{Symbol => Object}] `:settled` count and `:attempting` flag
+        def progress = (@progress ||= { settled: 0, attempting: false })
+
+        # What a crash between the checkpoint and the dispatches leaves behind, to be redriven on
+        # the next boot. Carries the moving event, so the arguments can be resolved again.
         #
-        # @return [Hash{Symbol => Object}] the event, the states moved between, and the commands
+        # @return [Hash{Symbol => Object}] the event, the states, the commands and progress
         def pending_marker
-          { on: event.name, from: pre_state, to: instance[:state], dispatches: handler.dispatches.map(&:command_name) }
+          { on: event.name, from: pre_state, to: instance[:state], dispatches: handler.dispatches.map(&:command_name),
+            event: Outbox.serialize_event(event) }.merge(progress)
         end
       end
 

data/lib/hecks/runtime/saga_pending_dispatch.rb

@@ -1,7 +1,9 @@
 module Hecks
   module Runtime
-    # Marks a checkpointed saga leg whose dispatch may not have run (persisted in `memory`).
-    # Reported, never redriven: dispatch isn't idempotent, so a replay could double-apply.
+    # Marks a checkpointed saga leg whose dispatches may not all have settled (persisted in
+    # `memory`). The marker records how many settled and whether the next was started, so the
+    # boot redrive delivers the ones that never began, and the one that may have run only when
+    # its store dedupes by dispatch key or its command is declared idempotent.
     SAGA_PENDING_DISPATCH_KEY = :__hecks_saga_pending_dispatch__
   end
 end

data/lib/hecks/runtime/scalar_field.rb

@@ -0,0 +1,73 @@
+require_relative "value"
+
+module Hecks
+  module Runtime
+    # A field of an aggregate's head that holds one String, Integer or Float: the lifecycle field,
+    # or an attribute whose value object has a single field of one of those types. A store can
+    # read such a field as one SQL value, and a bulk run's one-statement form (ADR 0129) compiles
+    # only reads and writes of these.
+    class ScalarField
+      # Each primitive a scalar field may hold, and the type a compiled operand carries for it.
+      PRIMITIVE_TYPES = { "Integer" => :integer, "Float" => :float, "String" => :string }.freeze
+
+      # @return [String] the field's name, which is its column's
+      attr_reader :name
+
+      # @return [String, nil] the value object's one field, nil for the lifecycle field
+      attr_reader :member
+
+      # @return [Symbol] `:integer`, `:float` or `:string`
+      attr_reader :type
+
+      # The scalar field `name` names on `aggregate`, or nil when it is not one.
+      #
+      # @param aggregate [Bluebook::Aggregate] the aggregate whose head holds the field
+      # @param name [String, Symbol] the field's name
+      # @return [Runtime::ScalarField, nil] the field, or nil when it holds anything else
+      def self.of(aggregate, name)
+        return new(name: name.to_s, member: nil, type: :string, writable: false) if aggregate.lifecycle_field.to_s == name.to_s
+
+        attribute = aggregate.attribute(name.to_s)
+        attribute && attribute_field(aggregate, attribute)
+      end
+
+      # @param name [String] the field's name
+      # @param member [String, nil] the value object's one field
+      # @param type [Symbol] the type the field holds
+      # @param writable [Boolean] whether no invariant, pattern or closed set guards it
+      def initialize(name:, member:, type:, writable:)
+        @name = name
+        @member = member
+        @type = type
+        @writable = writable
+      end
+
+      # @return [Boolean] whether the field is the lifecycle field, held as bare text
+      def lifecycle? = member.nil?
+
+      # @return [Boolean] whether a statement may write the field without a check Ruby makes
+      def writable? = @writable
+
+      class << self
+        private
+
+        def attribute_field(aggregate, attribute)
+          return nil if attribute.list? || attribute.reference?
+
+          shape = Value.value_object_for(aggregate, attribute.type)
+          inner = shape&.sole_attribute
+          type = primitive_type(inner)
+          type && new(name: attribute.name.to_s, member: inner.name.to_s, type: type,
+                      writable: unguarded?(attribute, shape, inner))
+        end
+
+        def primitive_type(inner) = inner && !inner.list? && PRIMITIVE_TYPES[inner.type.to_s]
+
+        def unguarded?(attribute, shape, inner)
+          [attribute, inner].all? { |field| field.pattern.nil? && field.admits.nil? } &&
+            shape.invariants.empty? && shape.members.empty?
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/tenant_scope.rb

@@ -21,7 +21,8 @@ module Hecks
       # @raise [Runtime::Unauthorized] if `declared` declares a tenant boundary and `args`
       #   omits that field
       def apply(declared, args)
-        tenant = declared.authorization&.tenant
+        authorization = declared.authorization
+        tenant = authorization&.tenant
         return declared unless tenant
 
         tenant = tenant.to_sym

data/lib/hecks/runtime/validation.rb

@@ -0,0 +1,24 @@
+module Hecks
+  module Runtime
+    # The answer to "would this command be accepted?": every reason it would not be, as data.
+    #
+    # Advisory. A passing validation does not promise the real dispatch will pass, since the state
+    # it read can change in between; the dispatch stays authoritative.
+    class Validation
+      # @return [Array<Hecks::Refused>] the refusals, in the order dispatch would have found them
+      attr_reader :refusals
+
+      # @param refusals [Array<Hecks::Refused>] what refused; one the facts gate and the
+      #   interpreter's gate both found is kept once
+      def initialize(refusals)
+        @refusals = refusals.uniq { |refusal| [refusal.class, refusal.path, refusal.rule, refusal.message] }.freeze
+      end
+
+      # @return [Boolean] whether nothing refused
+      def ok? = refusals.empty?
+
+      # @return [Hash{Symbol => Object}] `ok` and each refusal as plain data
+      def to_h = { ok: ok?, refusals: refusals.map(&:to_h) }
+    end
+  end
+end