hecks 5.0.0 → 7.0.0

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,10 +22,16 @@ 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
 
+      # The state a saga parks in when a stage faults, and the memory key that records the state it
+      # faulted from.
+      NEEDS_HUMAN = "needs_human".freeze
+      FAULTED_FROM_KEY = :__hecks_saga_faulted_from__
+
       # A crash gets this many retries before it's treated as something to
       # compensate for, instead of unwinding on the first failure.
       MAX_DEFECT_RETRIES = 3
@@ -32,22 +40,62 @@ 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
-        # Moves the instance into the handler's state, remembering the state it left.
+        # @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. A move into
+        # `needs_human` also records that state in the instance's memory, so a resume knows the
+        # stage that faulted.
         #
         # @param leg_handler [Bluebook::ProcessManager::Handler] the leg being taken
         # @return [void]
         def take(leg_handler)
           self.handler   = leg_handler
           self.pre_state = instance[:state]
-          instance[:state] = leg_handler.to_state
+          to_state = leg_handler.to_state
+          instance[:state] = to_state
+          remember_fault_origin if to_state == NEEDS_HUMAN
         end
 
-        # What a crash between the checkpoint and the dispatches leaves behind, to be surfaced
-        # on the next boot.
+        # Records the state the instance faulted from, under the saga's memory.
         #
-        # @return [Hash{Symbol => Object}] the event, the states moved between, and the commands
+        # @return [void]
+        def remember_fault_origin
+          (instance[:memory] ||= {})[FAULTED_FROM_KEY] = pre_state
+        end
+
+        # 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, 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
 
@@ -82,8 +130,36 @@ module Hecks
         end
       end
 
+      # Puts a faulted saga instance back in the stage it faulted from, so the caller can dispatch
+      # that stage again with the arguments the saga started with. Dispatches nothing itself.
+      #
+      # @param domain [String, Symbol] the domain whose saga is resumed
+      # @param process_manager [String] the declared saga's name
+      # @param correlation [String] the instance's correlation key
+      # @return [Hash{Symbol => Object}] `:resumed` true with the `:stage` to dispatch and the
+      #   saved `:arguments`, or `:resumed` false with a `:reason`
+      def resume(domain, process_manager, correlation)
+        instance = @registry.saga_instances.dig(process_manager, correlation)
+        return { resumed: false, reason: "no saga #{process_manager} with #{correlation}" } unless instance
+        unless instance[:state] == NEEDS_HUMAN
+          return { resumed: false, reason: "saga is #{instance[:state]}, not #{NEEDS_HUMAN}" }
+        end
+
+        restore_faulted_stage(domain, process_manager, correlation, instance)
+      end
+
       private
 
+      # Moves a needs_human instance back to the stage it faulted from, forgets that record, and
+      # checkpoints the move.
+      def restore_faulted_stage(domain, process_manager, correlation, instance)
+        stage = instance[:memory].delete(FAULTED_FROM_KEY)
+        instance[:state] = stage
+        definition = @registry.bluebook(domain).process_managers.find { |pm| pm.name == process_manager }
+        checkpoint(definition, correlation, instance, domain)
+        { resumed: true, stage: stage, arguments: instance[:memory].dup }
+      end
+
       # Holds `saga_mutex` across both the in-memory mutation and the
       # persistence write, never just the mutation — otherwise two threads
       # racing the same (process_manager, correlation) key could interleave

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

data/lib/hecks/runtime/value/admission.rb

@@ -28,12 +28,12 @@ module Hecks
         # Unlike `admit_member`, the set is declared elsewhere and named, not written inline.
         #
         # @param owner [Bluebook::Aggregate, Bluebook::Entity, Bluebook::ValueObject] declares
-        #   `attribute`; the walk to the chapter starts here
+        #   `attribute`; the walk to the bluebook starts here
         # @param attribute [Bluebook::Attribute, nil] nil, or one with no `admits:`, checks nothing
         # @param value [Object, nil] a bare scalar or a one-field `Runtime::Value`; nil is skipped
         # @return [Object, nil] `value`, unchanged
         # @raise [Runtime::InvariantViolation] if the value is not a member of the named set,
-        #   or `admits:` names a set no aggregate in the chapter declares
+        #   or `admits:` names a set no aggregate in the bluebook declares
         def admit_declared_set(owner, attribute, value)
           return value if attribute.nil? || attribute.admits.nil? || value.nil?
 
@@ -56,8 +56,8 @@ module Hecks
         #   `attribute`
         # @param attribute [Bluebook::Attribute] an attribute whose `admits` is `"Aggregate::Set"`
         # @return [Array<String>] each member's first-attribute value as a String, in order
-        # @raise [Runtime::InvariantViolation] if `admits` is not qualified, no chapter is
-        #   reachable from `owner`, or the chapter declares no such aggregate or value object
+        # @raise [Runtime::InvariantViolation] if `admits` is not qualified, no bluebook is
+        #   reachable from `owner`, or the bluebook declares no such aggregate or value object
         def admitted_members(owner, attribute)
           set = declared_set(owner, attribute)
           unless set
@@ -70,13 +70,13 @@ module Hecks
           set.members.map { |member| member.to_h[discriminant].to_s }
         end
 
-        # Walks `hecks_owner` links upward until it reaches the chapter.
+        # Walks `hecks_owner` links upward until it reaches the bluebook.
         #
         # @param construct [Bluebook::ValueObject, Bluebook::Entity, Bluebook::Aggregate,
-        #   Bluebook::Chapter, nil] the construct to start from; the chapter answers itself
-        # @return [Bluebook::Chapter, nil] the first construct on the way up that responds to
+        #   Bluebook::Declaration, nil] the construct to start from; the bluebook answers itself
+        # @return [Bluebook::Declaration, nil] the first construct on the way up that responds to
         #   `aggregate`; nil when the chain ends without one
-        def chapter_of(construct)
+        def bluebook_of(construct)
           node = construct
           node = node.hecks_owner while node && !node.respond_to?(:aggregate) && node.respond_to?(:hecks_owner)
           node.respond_to?(:aggregate) ? node : nil
@@ -111,12 +111,12 @@ module Hecks
           member.all? { |field, value| fields[field].to_s == value.to_s }
         end
 
-        # The value object `attribute.admits` names (`"Aggregate::Set"`), when the chapter declares
+        # The value object `attribute.admits` names (`"Aggregate::Set"`), when the bluebook declares
         # it.
         def declared_set(owner, attribute)
           aggregate_name, set_name = attribute.admits.to_s.split("::", 2)
-          chapter = chapter_of(owner)
-          set_name && chapter&.aggregate(aggregate_name)&.value_object(set_name)
+          declaration = bluebook_of(owner)
+          set_name && declaration&.aggregate(aggregate_name)&.value_object(set_name)
         end
 
         # Applies `admits:` to value-object fields too, which never pass through `for_attribute`.

data/lib/hecks/runtime/value/coercion.rb

@@ -37,25 +37,53 @@ module Hecks
         # Coerces `value` for a single, already-resolved `attribute`, branching on
         # its declared shape (list, reference, composite, or bare scalar).
         #
-        # `boundary: false` is the query entry point, where a declared type documents the
-        # argument for callers/generators rather than naming a shape to enforce.
         # `argument: true` is the command/entity/port dispatch entry point, where a nil for
         # a required attribute is a left-empty argument (C3.7), not ordinary state nil.
+        # A query's arguments are coerced here too, so a bare scalar of the wrong type refuses
+        # for a query exactly as it does for a command.
         #
         # @raise [Runtime::TypeMismatch] if `value` cannot be coerced, or a required
         #   reference/attribute is a wrong-shaped value
         # @raise [Runtime::UnknownArgument] if `value` is a Hash naming an undeclared field
         # @raise [Runtime::InvariantViolation] if a coerced value object breaks an invariant
-        def for_attribute(aggregate, attribute, value, boundary: true, argument: false)
+        def for_attribute(aggregate, attribute, value, argument: false)
           return nil_or_missing(aggregate, attribute, value, argument) if attribute.nil? || value.nil?
           return reference_or_list(aggregate, attribute, value) if attribute.list? || attribute.reference?
           return value unless aggregate.respond_to?(:value_object)
 
-          coerce_scalar(aggregate, attribute, value, boundary)
+          coerce_scalar(aggregate, attribute, value)
+        end
+
+        # Refuses a query argument whose bare value does not match its declared scalar type, with
+        # the refusal a command argument of that type gets. A nil, a list, a reference and a value
+        # object are left to `for_attribute`, which owns their shape.
+        #
+        # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] the queried construct
+        # @param attribute [Bluebook::Attribute] the query's declared argument
+        # @param value [Object] the offered value
+        # @raise [Runtime::TypeMismatch] if `value` is not of the attribute's declared scalar type
+        def check_query_argument!(aggregate, attribute, value)
+          return if value.nil? || attribute.list? || attribute.reference?
+          return unless aggregate.respond_to?(:value_object) && value_object_for(aggregate, attribute.type).nil?
+
+          check_bare_primitive(aggregate, attribute, value)
+        end
+
+        # Shape-checks every declared argument of `declared` that `args` offers, before any store
+        # is read. The Postgres query builder calls it so its own path refuses what the query
+        # interpreter refuses.
+        #
+        # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] the queried construct
+        # @param declared [Bluebook::Query] the declared query whose `attributes` are its arguments
+        # @param args [Hash{Symbol => Object}] the offered argument values
+        # @raise [Runtime::TypeMismatch] if an offered bare scalar does not match its declared type
+        def check_query_arguments!(aggregate, declared, args)
+          attributes = declared.respond_to?(:attributes) ? declared.attributes : []
+          attributes.each { |attribute| check_query_argument!(aggregate, attribute, args[attribute.name.to_sym]) }
         end
 
         # Resolves the value-object class `type` names: `aggregate`'s own
-        # declarations first, then its chapter's other aggregates if they agree.
+        # declarations first, then its bluebook's other aggregates if they agree.
         #
         # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] construct to search first
         # @param type [String, Symbol, #to_s] the declared type name to resolve
@@ -64,10 +92,10 @@ module Hecks
           local = aggregate.value_object(type)
           return local if local
 
-          chapter = aggregate.respond_to?(:hecks_owner) ? aggregate.hecks_owner : nil
-          return nil unless chapter.respond_to?(:aggregates)
+          declaration = aggregate.respond_to?(:hecks_owner) ? aggregate.hecks_owner : nil
+          return nil unless declaration.respond_to?(:aggregates)
 
-          agreed_value_object(chapter, type)
+          agreed_value_object(declaration, type)
         end
 
         # Normalizes an offered value into `value_object`'s own field Hash, before
@@ -150,9 +178,9 @@ module Hecks
         # A bare scalar or a value object. `admits:` is checked here, where the attribute is
         # known — `build` only sees the value object. Checked after coercion: a scalar arrives
         # wrapped in its type's own holder, and checking the raw payload would be wrong.
-        def coerce_scalar(aggregate, attribute, value, boundary)
+        def coerce_scalar(aggregate, attribute, value)
           value_object = value_object_for(aggregate, attribute.type)
-          return bare_primitive(aggregate, attribute, value, boundary) if value_object.nil?
+          return bare_primitive(aggregate, attribute, value) if value_object.nil?
 
           coerced = if value.is_a?(self) && value.type_name == value_object.hecks_name
                       value
@@ -164,9 +192,9 @@ module Hecks
           coerced
         end
 
-        # The one value object every aggregate of the chapter that declares `type` agrees on.
-        def agreed_value_object(chapter, type)
-          matches = chapter.aggregates.filter_map { |candidate| candidate.value_object(type) }
+        # The one value object every aggregate of the bluebook that declares `type` agrees on.
+        def agreed_value_object(declaration, type)
+          matches = declaration.aggregates.filter_map { |candidate| candidate.value_object(type) }
           shapes = matches.group_by do |shape|
             shape.attributes.map { |field| [field.name, field.type.to_s, field.list?, field.optional?] }
           end
@@ -195,8 +223,8 @@ module Hecks
         # A bare primitive is boundary-checked too (C3.8) — wrong-typed input
         # refuses here as a TypeMismatch, never later as a broken predicate.
         # Its `admits:` set is still checked, exactly as a value object's is.
-        def bare_primitive(aggregate, attribute, value, boundary)
-          check_bare_primitive(aggregate, attribute, value) if boundary
+        def bare_primitive(aggregate, attribute, value)
+          check_bare_primitive(aggregate, attribute, value)
           admit_declared_set(aggregate, attribute, value)
           value
         end