hecks 5.0.0 → 7.0.0

data/lib/hecks/runtime/outbox/relay.rb

@@ -1,4 +1,6 @@
 require_relative "consumer_runner"
+require_relative "redrive"
+require_relative "runnable"
 
 module Hecks
   module Runtime
@@ -7,6 +9,8 @@ module Hecks
       # them inline, and redrives whatever a crash left behind.
       class Relay
         include ConsumerRunner
+        include Redrive
+        include Runnable
 
         attr_reader :registry, :log
 
@@ -27,6 +31,31 @@ module Hecks
 
         def attached? = !@policies.nil?
 
+        # Runs one policy's reaction to `event`, as a row's delivery runs it: its outcome is
+        # recorded on the registry's reaction log, a refusal included, and nothing is raised.
+        #
+        # @param event [Runtime::Event] the event the policy reacts to
+        # @param policy [Bluebook::Policy] the policy to run
+        # @param home [String] the bluebook the policy is declared in
+        # @param domain [String] the domain the event came from
+        # @param event_uid [String] the identity the reaction log records for the event
+        # @return [void]
+        def react_policy(event, policy:, home:, domain:, event_uid:)
+          @policies.react(event, domain, only: [policy, home], event_uid: event_uid)
+        end
+
+        # Answers the policies `event` triggers in `domain`, as `[policy, home]` pairs.
+        #
+        # @param event [Runtime::Event] the event to react to
+        # @param domain [String] the domain the event came from
+        # @return [Array(Bluebook::Policy, String)]
+        def policies_for(event, domain) = @policies.policies_for(event, domain)
+
+        # Forgets every delivery the relay recorded, as a fresh boot starts with none.
+        #
+        # @return [void]
+        def clear_log = @log.clear
+
         # Called inside the save transaction for command/entity paths, and
         # outside one for port operations (which save nothing). Returns nil
         # when the repository has no outbox — callers then react directly.
@@ -35,7 +64,8 @@ module Hecks
           return [] if events.empty?
 
           rows = Fanout.rows_for(@registry, events, domain)
-          rows.each { |row| row.aggregate = repository.aggregate.storage_name }
+          aggregate = repository.aggregate
+          rows.each { |row| row.aggregate = aggregate.storage_name }
           repository.outbox_enqueue(rows)
         end
 
@@ -69,21 +99,15 @@ module Hecks
           stores.flat_map { |repository| repository.outbox_rows(status: status) }
         end
 
-        # `pending` rows are always safe to redrive (never claimed yet).
-        # `claimed` rows are only surfaced — redelivering a maybe-already-run
-        # consumer needs an explicit `claimed: true`.
-        def redrive!(claimed: false)
-          stores.flat_map { |repository| redrive_store(repository, claimed) }
-        end
-
         private
 
         def settle_delivery(row, repository)
-          run_consumer(row)
-          repository.outbox_settle(row.id, status: "delivered")
-          row.status = "delivered"
+          reason = run_consumer(row)
+          row.status = reason ? "refused" : "delivered"
+          repository.outbox_settle(row.id, status: row.status, error: reason)
+          row.error = reason
           true
-        rescue StandardError => e
+        rescue StandardError, ScriptError => e
           settle_failed(row, repository, e)
           false
         end
@@ -99,37 +123,6 @@ module Hecks
                     reason: row.error }
         end
 
-        # The rows of one store that redrove: its pending rows first, then its claimed ones.
-        def redrive_store(repository, claimed)
-          redriven = repository.outbox_rows(status: "pending").select { |row| deliver_row(row, repository) }
-          redriven + repository.outbox_rows(status: "claimed").select { |row| redrive_claimed?(row, repository, claimed) }
-        end
-
-        def redrive_claimed?(row, repository, claimed)
-          unless claimed
-            warn_stalled(row)
-            return false
-          end
-
-          repository.outbox_settle(row.id, status: "pending")
-          row.status = "pending"
-          deliver_row(row, repository)
-        end
-
-        def warn_stalled(row)
-          warn stalled_wording(row)
-          @log << { outbox: row.delivery_id, consumer: row.consumer, kind: row.kind, stalled: true,
-                    event: row.event[:name], aggregate: row.event[:aggregate], id: row.event[:id] }
-        end
-
-        def stalled_wording(row)
-          "[hecks] outbox row #{row.delivery_id} (#{row.consumer} on #{row.event[:name]} for " \
-            "#{row.event[:aggregate]}##{row.event[:id]}) was claimed before the last crash/restart and never " \
-            "settled — its #{row.kind} may or may not have actually run. hecks does not auto-redrive a claimed " \
-            "row (the outcome is unknown, and redelivering it could double the effect); inspect it and " \
-            "redrive by hand with `runtime.outbox.redrive!(claimed: true)` once you know it is safe."
-        end
-
         # Bluebooks, not hecksagons: a domain with no hecksagon is still
         # bound to the default Memory adapter. An aggregate a hecksagon left
         # unbound raises WiringError here and is skipped.

data/lib/hecks/runtime/outbox/runnable.rb

@@ -0,0 +1,62 @@
+require_relative "../adapter_lookup"
+require_relative "../errors"
+
+module Hecks
+  module Runtime
+    module Outbox
+      # Whether this process can run what a redriven row asks of the outside. A policy's `ask` is
+      # answered by the adapter bound to its port, and a process that booted without that adapter
+      # (a one-shot command that loads no application constants, say) would only turn the row into
+      # a refusal nobody sees. It leaves the row pending for a process that has the adapter, and
+      # says so once. Mixed into {Relay}, which supplies `registry` and `log`.
+      module Runnable
+        private
+
+        # Records that a row was left pending, and warns the first time its reason is seen.
+        #
+        # @return [Boolean] true when the row must not be claimed here
+        def withheld?(row)
+          reason = unrunnable_reason(row) or return false
+
+          @log << { outbox: row.delivery_id, consumer: row.consumer, withheld: true, reason: reason }
+          @withheld_reasons ||= []
+          warn withheld_wording(row, reason) if @withheld_reasons.push(reason).count(reason) == 1
+          true
+        end
+
+        def withheld_wording(row, reason)
+          "[hecks] outbox row #{row.delivery_id} (#{row.consumer} on #{row.event[:name]}) left pending: " \
+            "#{reason}. A process that has the adapter will run it; it stays visible in `outbox.rows`."
+        end
+
+        # @return [String, nil] why the row's ask cannot run in this process, nil when it can
+        def unrunnable_reason(row)
+          target = ask_target(row) or return nil
+
+          adapter_bound?(*target) ? nil : "no adapter bound for #{target.join(".")} in this process"
+        end
+
+        def adapter_bound?(port, operation)
+          AdapterLookup.adapter_class(@registry, port, asked: operation)
+          true
+        rescue WiringError, NameError
+          false
+        end
+
+        # @return [Array(String, String), nil] the port and operation the row's policy asks, nil
+        #   when the row is not an ask
+        def ask_target(row)
+          kind, fqn = row.consumer.split(":", 2)
+          home, name = fqn.split("::", 2)
+          return nil unless kind == "policy"
+
+          policy = @registry.bluebook(home)&.policies&.find { |candidate| candidate.name == name }
+          return nil unless policy&.asks?
+
+          aggregate_and_port, operation = policy.trigger_command.split(".", 2)
+          [aggregate_and_port.split("::").last, operation]
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/outbox.rb

@@ -10,15 +10,33 @@ module Hecks
     # A durable outbox (ADR 0053): one row per (event, consumer), written in
     # the same transaction as the aggregate save so a reaction is never lost.
     module Outbox
-      # pending -> claimed -> delivered | failed
-      STATUSES = %w[pending claimed delivered failed].freeze
+      # pending -> claimed -> delivered | failed | refused. A reaction the domain refused (its
+      # trigger was declined, its `with:` read a key the event lacked, the cascade was too deep)
+      # is settled `refused` with the reason in `error`: it ran and said no, which is neither
+      # delivery nor a defect, and a trace reads it back.
+      STATUSES = %w[pending claimed delivered failed refused].freeze
 
+      # How long a row stays claimed before it counts as stalled: a claim that old was left by a
+      # process that is gone, where a younger one is a reaction running in another process. Ten
+      # minutes is the ceiling a reaction is expected to stay inside.
+      STALLED_AFTER = 600
+
+      # `claimed_for` is the seconds since the row was claimed, read from the store's own clock; nil
+      # when the store does not say.
       Row = Struct.new(:id, :delivery_id, :event_uid, :aggregate, :domain, :kind, :consumer, :event,
-                       :status, :attempts, :error, keyword_init: true) do
+                       :status, :attempts, :error, :claimed_for, keyword_init: true) do
         def pending?   = status == "pending"
         def claimed?   = status == "claimed"
         def delivered? = status == "delivered"
         def failed?    = status == "failed"
+        def refused?   = status == "refused"
+
+        # A claimed row is stalled when its age is unknown or past `STALLED_AFTER`; a younger one is
+        # a reaction still running.
+        def stalled? = claimed? && (claimed_for.nil? || claimed_for >= STALLED_AFTER)
+
+        # @return [Integer, nil] whole seconds since the claim, or nil when the store does not say
+        def claimed_seconds_ago = claimed_for&.round
 
         # Wire shape persisted by adapters; `Outbox.event_from` reverses it.
         def to_h

data/lib/hecks/runtime/policy_interpreter/arguments.rb

@@ -19,10 +19,16 @@ module Hecks
           payload = event.payload.transform_keys(&:to_sym).merge(extra)
           return payload unless ReactionInvocation.projection_declared?(policy)
 
-          source = row.transform_keys(&:to_sym).merge(emitter_identity(event)).merge(payload)
+          source = emitter_id(event).merge(row.transform_keys(&:to_sym)).merge(emitter_identity(event)).merge(payload)
           projected_args(policy, event, source)
         end
 
+        # The emitting record's whole identity as `:id`, below everything else: a fan-out row
+        # carries its own `id`, and a payload field of that name wins (ADR 0153).
+        def emitter_id(event)
+          event.id.nil? || event.id.to_s.empty? ? {} : { id: event.id }
+        end
+
         def projected_args(policy, event, payload)
           args = ReactionInvocation.resolve_mapping(
             with_spec: policy.with_spec,

data/lib/hecks/runtime/policy_interpreter/fan_out.rb

@@ -1,14 +1,15 @@
-require_relative "../../naming"
 require_relative "../errors"
-require_relative "../query_interpreter"
-require_relative "../refusal_wording"
+require_relative "../row_sweep"
 
 module Hecks
   module Runtime
     class PolicyInterpreter
       # A `for_each` policy: asks a query which rows the event concerns, and fires the trigger
-      # once per row. Mixed into {PolicyInterpreter}.
+      # once per row through the {RowSweep} a bulk run shares. Mixed into {PolicyInterpreter}.
       module FanOut
+        # The bare scalar types a `for_each` query may declare as an argument.
+        SCALAR_ARGUMENT_TYPES = %w[String Integer Float].freeze
+
         private
 
         # Runs the `for_each` query against the event payload and fires the trigger once
@@ -32,22 +33,37 @@ module Hecks
         # The rows the `for_each` query answers, and the key by which the trigger addresses a row.
         def for_each_rows(policy, event, domain, target)
           query_domain, aggregate_name, query_name = policy.for_each_route(domain)
-          aggregate = resolve_query_aggregate(query_domain, aggregate_name, policy.for_each)
+          aggregate = row_sweep.query_aggregate(query_domain, aggregate_name, verb: policy.for_each)
           # The query reads the event, never the `with:` projection: it asks which rows.
           query_args = for_each_query_args(aggregate.query(query_name), event)
-          rows = QueryInterpreter.new(@registry).call(query_domain, aggregate, query_name, query_args)
-          [rows, addressing_key_for(target, aggregate_name)]
+          rows = row_sweep.rows(query_domain, aggregate, query_name, query_args)
+          [rows, row_sweep.addressing_key_for(target, aggregate_name, label: "for_each's own trigger")]
         end
 
+        def row_sweep = @row_sweep ||= RowSweep.new(@registry)
+
         # The event's own identity is not in its payload, so a query argument named
         # after an identity head of the emitting aggregate is filled from `event.id`.
         # Without it the query silently sees nothing. Never overrides a payload value.
         def for_each_query_args(query, event)
           args = event.payload.transform_keys(&:to_sym)
           construct = query && emitting_construct(event)
-          return args unless construct
+          lent_attributes(query, construct, args).each { |attribute| args[attribute.name] = event.id } if construct
+          unwrap_scalar_arguments(query, args)
+        end
+
+        # A bare-scalar query argument takes the one value its single-field value object carries:
+        # the payload hands over the object, but the query declares the scalar, and a query's
+        # argument is shape-checked against its declared type.
+        def unwrap_scalar_arguments(query, args)
+          return args unless query
 
-          lent_attributes(query, construct, args).each { |attribute| args[attribute.name] = event.id }
+          query.attributes.each do |attribute|
+            value = args[attribute.name]
+            next unless value.is_a?(Hash) && value.size == 1 && SCALAR_ARGUMENT_TYPES.include?(attribute.type.to_s)
+
+            args[attribute.name] = value.values.first
+          end
           args
         end
 
@@ -57,38 +73,11 @@ module Hecks
           query.attributes.select { |attribute| heads.include?(attribute.name.to_s) && !args.key?(attribute.name) }
         end
 
-        # Resolves `target` back to its declared command and asks it how a row of
-        # `aggregate_name` addresses it. Raises rather than guessing when the command is
-        # unresolvable or cannot be addressed: a domain-authoring mistake to surface.
-        def addressing_key_for(target, aggregate_name)
-          target_domain, target_aggregate_name, target_command_name = Naming.split_verb(target)
-          command = @registry.bluebook(target_domain)&.aggregate(target_aggregate_name)&.command(target_command_name)
-          raise UnknownVerb, "for_each's own trigger #{target.inspect} does not resolve to a declared command" unless command
-
-          key = command.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
-
         def deliver_for_each_row(target, row_record, args, policy, event)
           return depth_refusal(row_record) if @dispatcher.reaction_depth_reached?
 
           # The row key is already merged by `trigger_args`, so a projection can name it.
-          @dispatcher.reenter(target, **reaction_invocation(target, args, policy, event))
-          row_record.merge(delivered: true)
-        rescue *DOMAIN_REFUSALS => e
-          row_record.merge(delivered: false, reason: e.message)
-        end
-
-        def resolve_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))
+          row_sweep.deliver(row_record) { @dispatcher.reenter(target, **reaction_invocation(target, args, policy, event)) }
         end
       end
     end

data/lib/hecks/runtime/policy_interpreter.rb

@@ -36,23 +36,27 @@ module Hecks
       # @param only [Array(Bluebook::Policy, String), nil] one `[policy, home_domain]`
       #   pair to run exactly (the outbox relay's consumer), instead of scanning every
       #   loaded bluebook for candidates
-      # @param event_uid [String, nil] the outbox uid every consumer of this event shares, when the
-      #   event was rebuilt from an outbox row; otherwise the event object itself is the identity
-      # @return [void]
+      # @param event_uid [String, nil] the outbox uid every consumer of this event shares; the
+      #   reaction identity only when the event has no id
+      # @return [Array<Hash>] the reactions recorded, one per delivery attempted
       def react(event, domain, only: nil, event_uid: nil)
         selected = only ? [only] : policies_for(event, domain)
-        selected.each do |policy, home_domain|
+        selected.flat_map do |policy, home_domain|
           result = deliver(policy, event, home_domain)
-          next if result.nil?
-
-          # A for_each policy answers an array; Array(...) would explode a record Hash.
-          identity = event_uid || event.object_id
-          (result.is_a?(Array) ? result : [result]).each { |record| @registry.log_reaction(record, event: identity) }
+          # A for_each policy answers an array; Array(...) would explode a record Hash. The identity
+          # is the event's own id: a later run recognises the reaction, whichever path ran it.
+          records = result.is_a?(Array) ? result : [result].compact
+          records.each { |record| @registry.log_reaction(record, event: reaction_identity(event, event_uid)) }
         end
       end
 
       private
 
+      # The identity a reaction is logged under: the event's own id, so a later run can recognise
+      # the reaction whichever path delivered the event; the outbox uid or the object when the event
+      # has no id.
+      def reaction_identity(event, event_uid) = event.id || event_uid || event.object_id
+
       # Scans every loaded bluebook, since a policy commonly lives in a different
       # domain than the event it reacts to. Returns [policy, home_domain] pairs: the
       # home domain is the fallback for a bare trigger or for_each route. Order is the
@@ -69,6 +73,10 @@ module Hecks
         end
       end
 
+      # Answers the policies `event` triggers in `domain`, as `[policy, home_domain]` pairs, in
+      # the order a delivery tries them. The event pump reads this, then runs one of them at a time.
+      public :policies_for
+
       # Evaluated against the event payload alone (a policy has no aggregate state).
       # Not rescued here: an EvaluationError must reach `deliver`'s defect rescue, not
       # read as a policy that declined to fire.
@@ -99,10 +107,18 @@ module Hecks
         return depth_refusal(record) if @dispatcher.reaction_depth_reached?
 
         args = trigger_args(policy, event)
+        log_cross_domain(policy, target, args)
         @dispatcher.reenter(target, **reaction_invocation(target, args, policy, event))
         record.merge(delivered: true)
       end
 
+      # What an `across` policy hands the other domain, noted before the delivery is attempted.
+      def log_cross_domain(policy, target, args)
+        return unless policy.target_domain
+
+        @registry.cross_domain_log << { policy: policy.name, target_verb: target, payload: args }
+      end
+
       def depth_refusal(record)
         record.merge(delivered: false, reason: "reaction depth #{@dispatcher.max_reaction_depth} reached")
       end

data/lib/hecks/runtime/port_operation_interpreter.rb

@@ -1,5 +1,7 @@
 require_relative "adapter_lookup"
+require_relative "asking"
 require_relative "interpreting"
+require_relative "dispatch_context"
 require_relative "command_interpreter/argument_gate"
 require_relative "event"
 require_relative "value"
@@ -13,7 +15,15 @@ module Hecks
       include Interpreting
       include CommandInterpreter::ArgumentGate
 
-      Context = Struct.new(:domain, :aggregate, :operation, :args, :route, :instance, :result, :invocation)
+      Context = Struct.new(:domain, :aggregate, :operation, :args, :route, :instance, :result, :invocation) do
+        include DispatchContext
+
+        # @return [String] the operation's declared name
+        def operation_hecks_name = operation.hecks_name
+
+        # @return [Object] the identity of the record the route names
+        def route_identity = route.aggregate
+      end
 
       DISPATCH_ORDER = %i[
         refuse_unknown_arguments refuse_absent_arguments normalize_args resolve_references resolve_route emit
@@ -67,8 +77,8 @@ module Hecks
 
       def step_resolve_route(ctx)
         ctx.instance = step(:resolve_route) do
-          @registry.repository(ctx.domain, ctx.aggregate).find(ctx.route.aggregate) ||
-            raise(NotFound, "#{ctx.aggregate.hecks_name} #{ctx.route.aggregate.inspect} does not exist")
+          @registry.repository(ctx.domain, ctx.aggregate).find(ctx.route_identity) ||
+            raise(NotFound, "#{ctx.aggregate_hecks_name} #{ctx.route_identity.inspect} does not exist")
         end
       end
 
@@ -76,22 +86,37 @@ module Hecks
         ctx.result = step(:emit) { ctx.operation.outbound? ? ask(ctx) : emit(ctx) }
       end
 
-      # The domain calling out. Any failure, however wide (timeout, bad credential, missing
-      # adapter), becomes the `refuses` event rather than a raise, so a policy can react to it.
-      # The adapter is found by port name across the adapters this boot loaded.
+      # The domain calling out. A failure of the outside world (timeout, bad credential, missing
+      # adapter, the adapter's own refusal) becomes the `refuses` event rather than a raise, so a
+      # policy can react to it. A defect in the code (`Runtime::PROGRAMMING_ERRORS`) is raised:
+      # read as a refusal, it hides its cause behind a domain event. The adapter is found by port
+      # name across the adapters this boot loaded.
       #
       # Unlike an inbound operation, an ask is handed the record's held state: the adapter
       # needs data that lives on the record, and an event payload carries only arguments.
       # Arguments win over state.
       def ask(ctx)
-        announce(ctx, ctx.operation.answers, ctx.args.merge(spread(adapter_answer(ctx))))
+        operation = ctx.operation
+        announce(ctx, operation.answers, ctx.args.merge(spread(adapter_answer(ctx))))
+      rescue Interrupt
+        refuse_ask(ctx, operation, interrupted(ctx))
       rescue StandardError => e
-        announce(ctx, ctx.operation.refuses, ctx.args.merge(refusal: { value: "#{e.class}: #{e.message}" }))
+        raise if Runtime.programming_error?(e)
+
+        refuse_ask(ctx, operation, Runtime.failure_reason(e))
       end
 
+      # Announces an ask's refusal with the text it failed with.
+      def refuse_ask(ctx, operation, text) = announce(ctx, operation.refuses, ctx.args.merge(refusal: { value: text }))
+
+      # The refusal an interrupted ask records: the operation it was in and that it was not
+      # finished, so the run ends faulted with the stage it reached, not open with no record.
+      def interrupted(ctx) = "interrupted during #{ctx.operation_hecks_name}: the run stopped before it finished"
+
       def adapter_answer(ctx)
         payload = held_state(ctx).merge(materialise(ctx.args))
-        adapter_for(ctx).public_send(Naming.snake(ctx.operation.hecks_name), **payload)
+        adapter = adapter_for(ctx)
+        Asking.with(@registry) { adapter.public_send(Naming.snake(ctx.operation_hecks_name), **payload) }
       end
 
       # The answer is spread, not nested: a policy re-enters its target with the event
@@ -105,23 +130,25 @@ module Hecks
       end
 
       # The record, if there is one. A missing record is not an error here: the ask still
-      # goes with only its arguments, since `resolve_references` already checked existence.
+      # goes with only its arguments, since `resolve_references` already checked existence. A
+      # defect in reading the state is raised, as an adapter's is.
       def held_state(ctx)
-        ctx.instance ? Value.materialize(ctx.instance.state) : {}
-      rescue StandardError
-        {}
+        ctx.instance ? Value.materialize(ctx.state) : {}
+      rescue StandardError => e
+        Runtime.programming_error?(e) ? raise : {}
       end
 
       # The port this operation belongs to, found through the aggregate rather than
       # threaded through the call.
       def port_name_for(ctx)
-        owning = ctx.aggregate.ports.find { |port| port.operations.any? { |op| op.equal?(ctx.operation) } }
+        aggregate = ctx.aggregate
+        owning = aggregate.ports.find { |port| port.operations.any? { |op| op.equal?(ctx.operation) } }
         owning&.name or raise WiringError,
-                              "#{ctx.operation.hecks_name} belongs to no port on #{ctx.aggregate.hecks_name}"
+                              "#{ctx.operation_hecks_name} belongs to no port on #{aggregate.hecks_name}"
       end
 
       def adapter_for(ctx)
-        AdapterLookup.call(@registry, port_name_for(ctx), asked: ctx.operation.hecks_name)
+        AdapterLookup.call(@registry, port_name_for(ctx), asked: ctx.operation_hecks_name, aggregate: ctx.aggregate)
       end
 
       # Adapters are handed plain data, never a Value.
@@ -136,7 +163,8 @@ module Hecks
       # Unlike CommandRules::Emission there is no mutated instance to read an id off; the
       # event is stamped with the coerced reference to the owning aggregate (already a plain id).
       def emit(ctx)
-        ctx.operation.emits.map do |event_name|
+        operation = ctx.operation
+        operation.emits.map do |event_name|
           event = event_for(ctx, event_name, ctx.args)
           @registry.event_log << event.emit!
           event
@@ -146,8 +174,8 @@ module Hecks
       def event_for(ctx, event_name, payload)
         Event.new(
           name:        event_name,
-          aggregate:   "#{ctx.domain}::#{ctx.aggregate.hecks_name}",
-          id:          ctx.route.aggregate,
+          aggregate:   "#{ctx.domain}::#{ctx.aggregate_hecks_name}",
+          id:          ctx.route_identity,
           payload:     payload,
           occurred_at: Event.stamp
         )

data/lib/hecks/runtime/query_interpreter/arguments.rb

@@ -9,10 +9,11 @@ module Hecks
       module Arguments
         private
 
-        # Coerces with `boundary: false`: a query's declared argument types are not a
-        # runtime shape check. The exception is a nil for a required value-object-typed
-        # argument, which must refuse as a command argument does; passing it through
-        # would run an unfiltered query (a Ruby/Rust divergence).
+        # Coerces a query's arguments exactly as a command's are: a bare scalar of the wrong
+        # type refuses with TypeMismatch before any store is read, and so does a nil for a
+        # required value-object-typed argument, which would otherwise run an unfiltered query
+        # (a Ruby/Rust divergence). The Postgres query builder checks the same shapes
+        # (`Value.check_query_arguments!`), so both engines refuse the same way.
         #
         # It does not use `Value::Coercion#nil_argument`, which builds a null value object
         # from field defaults and only refuses when a field has none. `null_vo_argument!`
@@ -29,7 +30,7 @@ module Hecks
         def coerce_argument(aggregate, attribute, value)
           return null_vo_argument!(aggregate, attribute) if checked_vo?(aggregate, attribute, value)
 
-          Value.for_attribute(aggregate, attribute, value, boundary: false)
+          Value.for_attribute(aggregate, attribute, value)
         end
 
         def checked_vo?(aggregate, attribute, value)

data/lib/hecks/runtime/query_interpreter/outside_answer.rb

@@ -25,7 +25,7 @@ module Hecks
         def answered_from_outside(aggregate, declared, args, port)
           asked = "#{aggregate.hecks_name}.#{declared.name}"
           refuse_offered_arguments!(declared, args, asked)
-          adapter = AdapterLookup.call(@registry, port.name, asked: asked)
+          adapter = AdapterLookup.call(@registry, port.name, asked: asked, aggregate: aggregate)
           method  = Naming.snake(declared.name)
           # The real adapter's class is what must answer; a fuzz replay's stand-in refuses instead.
           klass   = AdapterLookup.adapter_class(@registry, port.name, asked: asked)

data/lib/hecks/runtime/query_interpreter/paging.rb

@@ -0,0 +1,42 @@
+require_relative "../../ports/query/cursor"
+
+module Hecks
+  module Runtime
+    class QueryInterpreter
+      # Answers a cursor query a page at a time (ADR 0130). Mixed into {QueryInterpreter}.
+      module Paging
+        # Answers one page of a cursor query: the rows, and the token of the page after them.
+        #
+        # The query is asked for one row past its page; that row proves a next page exists and is
+        # not answered.
+        #
+        # @param query_name [String] a declared aggregate query that declares `cursor`
+        # @param args [Hash] the query's arguments; `:after` is the position, absent on page one
+        # @return [Hash{Symbol => Object}] `rows` (frozen Hashes) and `after` (a String, nil on the
+        #   last page)
+        # @param page_size [Integer, nil] a page smaller than the query's own `limit`; never larger
+        # @raise [ArgumentError] if the query has no cursor, or `after` is not a token it handed out
+        def page(domain, aggregate, query_name, args, page_size: nil)
+          declared = declared_query(aggregate, query_name)
+          raise ArgumentError, "#{query_name} declares no cursor, so it has no pages" unless declared.cursor
+
+          size = [declared_page_size(declared, normalize_args(aggregate, declared, args)), page_size || Float::INFINITY].min
+          rows, after = Ports::Query::Cursor.split(call(domain, aggregate, query_name, args, widen: size), declared, size)
+          { rows: rows, after: after }
+        end
+
+        private
+
+        # The cursor's position, then offset, then limit. Offset comes before limit, as SQL's
+        # `LIMIT n OFFSET m` and Ports::Query::InMemory do.
+        def paginate(ordered, declared, args)
+          ordered = Ports::Query::Cursor.after(ordered, declared, args) if declared.cursor
+          skipped = declared.offset ? ordered.drop(resolve_query_value(declared.offset.value, args).to_i) : ordered
+          declared.limit ? skipped.first(resolve_query_value(declared.limit.value, args).to_i) : skipped
+        end
+
+        def declared_page_size(declared, args) = resolve_query_value(declared.limit.value, args).to_i
+      end
+    end
+  end
+end