hecks 1.3.0 → 1.5.0

data/lib/hecks/runtime/policy_interpreter.rb

@@ -16,22 +16,36 @@ module Hecks
     class PolicyInterpreter
       attr_reader :registry
 
+      # @param registry [Runtime::Registry] the booted registry whose loaded
+      #   bluebooks are scanned for candidate policies
+      # @param door [Runtime::Dispatcher] the dispatcher reactions re-enter through,
+      #   and whose reaction-depth guard is checked before each delivery
       def initialize(registry, door:)
         @registry = registry
         @door     = door
       end
 
+      # Fires every declared policy `event` triggers, recording each outcome on
+      # the registry's reaction log.
+      #
       # `deliver` returns `nil` for a policy whose `where` did not hold —
-      # SILENTLY, the same as a policy `policies_for` never selected at all
+      # silently, the same as a policy `policies_for` never selected at all
       # (an `event_qualifier` miss carries no reaction_log entry either) —
-      # so nothing is appended for it. A `for_each` policy answers an ARRAY
+      # so nothing is appended for it. A `for_each` policy answers an array
       # (one record per matched row) rather than one record ; `Array(...)`
       # is wrong here (it would explode a plain record Hash into its own
       # key/value pairs), so the two shapes are told apart explicitly.
-      # `only:` — ONE `[policy, home_domain]` pair, the outbox relay's
+      # `only:` — one `[policy, home_domain]` pair, the outbox relay's
       # way of running exactly the consumer a row names (`Runtime::
       # Outbox::Relay#run_consumer`) instead of every policy that
       # matches the event. Selection is otherwise identical.
+      #
+      # @param event [Runtime::Event] the just-emitted event to react to
+      # @param domain [String, Symbol] the domain `event`'s own aggregate belongs
+      #   to, the emitting domain's policies fire first
+      # @param only [Array(Bluebook::Policy, String), nil] one `[policy, home_domain]`
+      #   pair to run exactly, instead of scanning every loaded bluebook for candidates
+      # @return [void]
       def react(event, domain, only: nil)
         selected = only ? [only] : policies_for(event, domain)
         selected.each do |policy, home_domain|
@@ -44,13 +58,13 @@ module Hecks
 
       private
 
-      # SCANS EVERY LOADED BLUEBOOK, not just the emitting command's own —
-      # a policy commonly lives in the CONSUMER's bluebook, reacting
+      # Scans every loaded bluebook, not just the emitting command's own —
+      # a policy commonly lives in the consumer's bluebook, reacting
       # passively to an event a different domain's aggregate emits (the
       # corpus-standard shape : `world/conception/bluebook/domain_cell.bluebook`'s
       # ConceiveOnAbsorption reacts `on "DomainAbsorbed"`, an event
       # `body/organs/bluebook/gut.bluebook`'s Gut.Absorb emits — two
-      # different bluebooks, joined only by the event's NAME). Restricting
+      # different bluebooks, joined only by the event's name). Restricting
       # the scan to the emitting domain's own bluebook (the previous
       # shape) silently drops every cross-domain reaction : the policy is
       # never even a candidate, no refusal, no log entry, nothing —
@@ -58,12 +72,12 @@ module Hecks
       # which encode this exact cross-bluebook cascade as their contract.
       #
       # Returns [policy, home_domain] pairs rather than bare policies —
-      # `deliver`/`deliver_for_each` fall back to the REACTING policy's
-      # OWN domain (not the emitting one) when a trigger or for_each route
+      # `deliver`/`deliver_for_each` fall back to the reacting policy's
+      # own domain (not the emitting one) when a trigger or for_each route
       # is bare, and that fallback has to travel with each match now that
       # a single event can surface policies from several different homes.
       #
-      # THE EMITTING DOMAIN'S OWN POLICIES FIRST, in declaration order,
+      # The emitting domain's own policies first, in declaration order,
       # then other bluebooks' in load order (C10.2) — the same order the
       # outbox lays its rows in (`Outbox::Fanout.policies`) and the Rust
       # kernel runs (`react_policies`: its own table, then cross-domain).
@@ -79,7 +93,7 @@ module Hecks
         end
       end
 
-      # THE GUARD, evaluated against the triggering event's own payload —
+      # The guard, evaluated against the triggering event's own payload —
       # a policy has no aggregate instance of its own to read state from,
       # so `state` is empty and every bare name a `where` resolves comes
       # from `attrs` (Expression::Resolver#fetch checks `attrs` before
@@ -88,7 +102,7 @@ module Hecks
       # policy simply has none of). Called from inside `deliver`'s own
       # rescue-guarded body (both callers, below) — never guarded here —
       # so an EvaluationError (an unresolvable field, a bad comparison) is
-      # caught the SAME way any other reaction defect is, not swallowed as
+      # caught the same way any other reaction defect is, not swallowed as
       # though the policy had merely declined to fire.
       def where_holds?(policy, event)
         return true if policy.where.to_s.empty?
@@ -97,7 +111,7 @@ module Hecks
       end
 
       def deliver(policy, event, domain)
-        # `record` ASSIGNED BEFORE ANY BRANCH THAT CAN RAISE, same reason
+        # `record` assigned before any branch that can raise, same reason
         # `deliver_for_each`'s own header gives : both rescue clauses below
         # call `.merge` on it, and a defect raised before it existed would
         # be caught here only to raise a second, different NoMethodError
@@ -121,7 +135,7 @@ module Hecks
         # fatal to the command that emitted the event.
         record.merge(delivered: false, reason: e.message)
       rescue StandardError => e
-        # A DEFECT, not a refusal — a NoMethodError in an interpreter, a
+        # A defect, not a refusal — a NoMethodError in an interpreter, a
         # NameError from a missing constant, a TypeError from a bad
         # assumption : exactly the class of thing DOMAIN_REFUSALS
         # (errors.rb, see the comment above that constant) deliberately
@@ -129,19 +143,19 @@ module Hecks
         # folding a crash into the same `delivered: false` shape as an
         # ordinary refusal makes a broken runtime read as normal operation
         # in the log. This clause does not reopen that hole: it is a
-        # SECOND, narrower rescue, tried only once the first one above has
+        # second, narrower rescue, tried only once the first one above has
         # already declined to match, so a legitimate refusal still takes
         # the branch above and a defect always takes this one.
         #
-        # Catching it HERE is safe for a fact this method's caller cannot
+        # Catching it here is safe for a fact this method's caller cannot
         # see from where it sits: by the time `react` runs, the command
-        # that EMITTED `event` has already succeeded and PERSISTED —
+        # that emitted `event` has already succeeded and persisted —
         # `Dispatcher#dispatch` calls `@policies.react` only after its own
         # `announced` events are already in hand. Letting this exception
         # keep propagating would not undo that command (nothing here is
         # transactional across aggregates) — it would only blow up the
-        # ORIGINAL caller's `dispatch` call for a failure that happened in
-        # a DIFFERENT command, one the caller never asked to run and has no
+        # original caller's `dispatch` call for a failure that happened in
+        # a different command, one the caller never asked to run and has no
         # way to compensate for. So the defect is recorded, distinguishably
         # (`defect: true`, plus the error's own class — nothing here is
         # allowed to read like an ordinary refusal), warned to STDERR so it
@@ -152,19 +166,19 @@ module Hecks
         record.merge(delivered: false, reason: e.message, defect: true, error_class: e.class.name)
       end
 
-      # THE FAN-OUT — `policy.for_each` names a query ; this runs it
+      # **The fan-out** — `policy.for_each` names a query ; this runs it
       # against the triggering event's own payload (the same source
       # `deliver`'s own ordinary path forwards to `trigger` wholesale) and
       # fires `trigger` once per row, merging each row's own id into the
-      # forwarded payload under whichever key THE TARGET COMMAND ITSELF
+      # forwarded payload under whichever key the target command itself
       # expects to be addressed by (`Behaviour::Command#addressing_key_for`
       # — never a guessed, one-size mint: `Account.Freeze`, addressed by
-      # `account` because it is declared ON Account and self-references
+      # `account` because it is declared on Account and self-references
       # it, refused every dispatch for as long as this hardcoded
       # `<aggregate>_id` instead — a real bug, found wiring `for_each`
       # into a real domain for the first time, not a hypothetical). A
       # refusal is recorded per row and the fan-out continues ; a crash
-      # resolving the QUERY ITSELF, or the TARGET COMMAND'S OWN inability
+      # resolving the query itself, or the target command's own inability
       # to address this aggregate at all (`addressing_key_for` answering
       # `nil` — a domain-authoring mistake, not a data problem), is a
       # single top-level defect for the policy, the same shape `deliver`'s
@@ -174,9 +188,9 @@ module Hecks
 
         query_domain, aggregate_name, query_name = policy.for_each_route(domain)
         aggregate = resolve_query_aggregate(query_domain, aggregate_name, policy.for_each)
-        # THE QUERY READS THE EVENT, never the projection — `with:` says
-        # what the TRIGGER is given, and the fan-out's query is asking a
-        # different question (WHICH rows) in the event's own vocabulary.
+        # The query reads the event, never the projection — `with:` says
+        # what the trigger is given, and the fan-out's query is asking a
+        # different question (which rows) in the event's own vocabulary.
         query_args    = for_each_query_args(aggregate.query(query_name), event)
         rows          = QueryInterpreter.new(@registry).call(query_domain, aggregate, query_name, query_args)
         reference_key = addressing_key_for(target, aggregate_name)
@@ -192,20 +206,19 @@ module Hecks
         record.merge(delivered: false, reason: e.message, defect: true, error_class: e.class.name)
       end
 
-      # THE EVENT'S OWN IDENTITY IS A FACT TOO, not only its payload. A
-      # for_each query commonly filters by the EMITTING record's own
+      # The event's own identity is a fact too, not only its payload. A
+      # for_each query commonly filters by the emitting record's own
       # identity (`OpenForCustomer`'s own `reference:`, scoping by the
-      # very customer who was just suspended) — which used to arrive for
-      # free because LEGACY dispatch left the self-addressing key riding
-      # along in `event.payload` unfiltered. Routing separated from
-      # payload (`to:`/`with:`, what the facade's own bang-methods always
-      # use) correctly stopped carrying it there, which left this query
-      # silently seeing NEITHER the field it needs NOR any error saying
-      # why — an empty result read as "nothing to freeze" instead of "the
-      # customer" the whole reaction exists to catch.
+      # very customer who was just suspended) — a fact routing keeps
+      # separate from payload (`to:`/`with:`, what the facade's own
+      # bang-methods always use), so `event.payload` alone does not carry
+      # it. Without this, the query would silently see neither the field
+      # it needs nor any error saying why — an empty result read as
+      # "nothing to freeze" instead of "the customer" the whole reaction
+      # exists to catch.
       #
-      # Merged in ONLY when the query declares an argument by that exact
-      # name AND the emitting aggregate's own identity is genuinely what
+      # Merged in only when the query declares an argument by that exact
+      # name and the emitting aggregate's own identity is genuinely what
       # that name means (`construct.identity_heads`) — the same guard
       # `SagaInterpreter::Correlation#self_identified?` uses for the
       # identical shape one call away, so an unrelated aggregate sharing
@@ -229,22 +242,22 @@ module Hecks
         args
       end
 
-      # WHAT THE TRIGGER IS GIVEN. Undeclared, the event's whole payload
+      # **What the trigger is given**. Undeclared, the event's whole payload
       # forwards verbatim — the behaviour every policy had before `with:`
       # existed, and still the right default for a trigger shaped like
       # its event.
       #
       # Declared, it is the same reading a saga's own `dispatch ...,
       # with:` gets (`SagaInterpreter#dispatch_args`): a Symbol names a
-      # field on the SOURCE below, anything else is a literal the policy
+      # field on the source below, anything else is a literal the policy
       # supplies itself. A saga additionally resolves against its own
       # memory and correlation key; a policy has neither — it holds
       # nothing between events — so the source is the event, plus:
       #
-      # `extra` is a FAN-OUT'S ROW KEY, merged into the source BEFORE the
+      # `extra` is a fan-out's row key, merged into the source before the
       # projection rather than after it. That is what lets a `for_each`
       # policy name the row it is acting on — `with: { account: :account }`
-      # — and therefore what lets one send the row and NOTHING ELSE. A
+      # — and therefore what lets one send the row and nothing else. A
       # trigger needing only which record to act on is the ordinary case
       # for a fan-out, and before this it could not be written: the whole
       # event rode along, and the target had to declare every field of it
@@ -261,26 +274,26 @@ module Hecks
           label:     "#{policy.name}'s trigger"
         )
 
-        # THE RAW INPUTS `args` WAS RESOLVED FROM — same additive,
+        # The raw inputs `args` was resolved from — same additive,
         # Ruby-only shape SagaInterpreter#deliver_saga_dispatch's own
         # saga_dispatch_log gets, for Properties.dispatch_binding_
         # fidelity's own independent re-derivation of Policy#with_spec's
         # 2-branch resolution (Symbol → payload lookup, anything else →
         # literal — a policy holds no correlation and no memory, so
         # `payload` — the merged event-payload-plus-fan-out-row source —
-        # is the WHOLE source, unlike a saga's own 4-branch one).
+        # is the whole source, unlike a saga's own 4-branch one).
         @registry.policy_dispatch_log << { policy: policy.name, on: event.name, payload: payload,
                                             with_spec: policy.with_spec, args: args }
         args
       end
 
-      # THE EMITTING RECORD'S OWN IDENTITY IS A FACT A PROJECTION MAY READ
+      # The emitting record's own identity is a fact a projection may read
       # — the same reasoning `for_each_query_args` gives one method up,
-      # extended from the fan-out's QUERY to the trigger's own `with:`.
+      # extended from the fan-out's query to the trigger's own `with:`.
       # Routing separated from payload (`to:`/`with:`) stopped carrying
       # the emitting aggregate's identity in the payload, which is right
       # for the event (a KnightCaptured is a fact about a knight, not a
-      # re-statement of which game) but left a CROSS-aggregate reaction
+      # re-statement of which game) but left a cross-aggregate reaction
       # with no way to say which record to address: chess's Graveyard is
       # one-per-game, fed by policy from every piece's own Captured
       # event, and its burials had no way to name the game — the
@@ -288,10 +301,10 @@ module Hecks
       # graveyard's identity and refused every one ("no Graveyard with
       # label.value \"bb\""). Same-aggregate targets were already covered
       # (`ReactionInvocation.source_receiver_for` lifts Event.id), so
-      # this is the OTHER aggregate's half of that.
+      # this is the other aggregate's half of that.
       #
       # Offered under the emitting aggregate's own identity heads, only
-      # to an EXPLICIT projection (a legacy wholesale forward keeps its
+      # to an explicit projection (a legacy wholesale forward keeps its
       # exact old payload), and never over a value the payload itself
       # carries. `event.id` is the scalar the identity resolves to, so a
       # projection naming it as the target's own identity head routes it
@@ -309,9 +322,9 @@ module Hecks
         construct.identity_heads.to_h { |head| [head.to_sym, event.id] }
       end
 
-      # RESOLVES `target` ("Domain::Aggregate.Command", the same shape
-      # `deliver`'s own caller already built) back to its OWN declared
-      # command, then asks IT how it expects to be addressed by a row of
+      # Resolves `target` ("Domain::Aggregate.Command", the same shape
+      # `deliver`'s own caller already built) back to its own declared
+      # command, then asks it how it expects to be addressed by a row of
       # `aggregate_name` — see `Behaviour::Command#addressing_key_for`'s
       # own comment for the two shapes that answers. Raises (caught by
       # `deliver_for_each`'s own outer `rescue StandardError`, the same
@@ -342,8 +355,8 @@ module Hecks
                                   reason:    "reaction depth #{@door.max_reaction_depth} reached")
         end
 
-        # ALREADY MERGED, by `trigger_args` — the row key belongs in the
-        # source a `with:` projection reads FROM, not bolted onto its
+        # Already merged, by `trigger_args` — the row key belongs in the
+        # source a `with:` projection reads from, not bolted onto its
         # result, or a projection could never name the row it acts on.
         @door.reenter(target, **reaction_invocation(target, args, policy, event))
         row_record.merge(delivered: true)
@@ -361,20 +374,20 @@ module Hecks
         )
       end
 
-      # `for_each`'s own QUERY route moved onto the Policy itself
+      # `for_each`'s own query route moved onto the Policy itself
       # (Behaviour::Policy#for_each_route) — one reading the interpreter
       # and the fuzzer's fan-out property both call, rather than the
-      # same split spelled twice. The reference-KEY the dispatch itself
-      # uses is `addressing_key_for`, above — a property of the TARGET
-      # COMMAND, not of the policy, so it lives on `Behaviour::Command`
+      # same split spelled twice. The reference-key the dispatch itself
+      # uses is `addressing_key_for`, above — a property of the target
+      # command, not of the policy, so it lives on `Behaviour::Command`
       # instead.
 
       def resolve_query_aggregate(domain, aggregate_name, verb)
         bluebook = @registry.bluebook(domain) ||
-                   raise(UnknownVerb, RefusalWording.render("UnknownVerb", "no_domain", domain: domain.inspect, verb: verb))
+                   raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "no_domain", domain: domain, verb: verb))
         bluebook.aggregate(aggregate_name) ||
-          raise(UnknownVerb, RefusalWording.render("UnknownVerb", "no_aggregate",
-                                                   domain: domain, aggregate: aggregate_name.inspect))
+          raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "no_aggregate",
+                                                        domain: domain, aggregate: aggregate_name))
       end
     end
   end

data/lib/hecks/runtime/port_operation_interpreter.rb

@@ -19,20 +19,43 @@ module Hecks
       include Interpreting
       include CommandInterpreter::ArgumentGate
 
-      Context = Struct.new(:domain, :aggregate, :operation, :args, :route, :instance, :result)
+      Context = Struct.new(:domain, :aggregate, :operation, :args, :route, :instance, :result, :invocation)
 
       DISPATCH_ORDER = %i[
         refuse_unknown_arguments refuse_absent_arguments normalize_args resolve_references resolve_route emit
       ].freeze
 
+      # @param registry [Runtime::Registry] the booted registry this interpreter dispatches
+      #   against
+      # @param rules [Runtime::CommandRules] the shared command-rule checks (references) this
+      #   interpreter's steps call
       def initialize(registry, rules:)
         @registry = registry
         @rules    = rules
       end
 
-      def call(domain, aggregate, operation, args, route:)
-        ctx = Context.new(domain, aggregate, operation, args)
-        ctx.route = route
+      # `invocation` — the `Runtime::Invocation` `Dispatcher` built;
+      # `ctx.args` is its `to_args`, `ctx.route` its `target`.
+      #
+      # @param domain [String] the domain the aggregate belongs to
+      # @param aggregate [Bluebook::Aggregate] the aggregate the port operation belongs to
+      # @param operation [Bluebook::PortOperation] the port operation to dispatch
+      # @param invocation [Runtime::Invocation] the invocation `Dispatcher` built for this call
+      # @return [Array<Runtime::Event>] the events recorded: the operation's own `emits` for
+      #   an inbound operation, or a single `answers`/`refuses` event for an outbound one
+      #   (an adapter failure is recorded as a `refuses` event, not raised)
+      # @raise [Runtime::UnknownArgument] if `invocation` offers an argument the operation
+      #   does not declare
+      # @raise [Runtime::AbsentArgument] if `invocation` omits a non-optional declared
+      #   argument
+      # @raise [Runtime::TypeMismatch] if an offered argument does not coerce to its declared
+      #   type
+      # @raise [Runtime::NotFound] if an offered reference or the operation's own receiving
+      #   record cannot be found
+      def call(domain, aggregate, operation, invocation)
+        ctx = Context.new(domain, aggregate, operation, invocation.to_args)
+        ctx.invocation = invocation
+        ctx.route = invocation.target
         run_dispatch_order(DISPATCH_ORDER, ctx)
         ctx.result
       end
@@ -66,13 +89,13 @@ module Hecks
         ctx.result = step(:emit) { ctx.operation.outbound? ? ask(ctx) : emit(ctx) }
       end
 
-      # THE DOMAIN CALLING OUT, AND BOTH ENDINGS RECORDED.
+      # The domain calling out, and both endings recorded.
       #
       # The adapter is found the same way every other port's is — by name,
       # across whatever adapters this boot loaded — so an `asks` is bound by
       # an adapter declaring `port "IssueTracker"` and nothing new to learn.
       #
-      # EVERY FAILURE IS AN ANSWER. A raise from the far side of a boundary is
+      # Every failure is an answer. A raise from the far side of a boundary is
       # not an exception in this domain's terms, it is the outside saying no,
       # and the chapter already named the word for that. So the rescue is
       # deliberately wide: a timeout, a bad credential, an adapter that does
@@ -80,22 +103,22 @@ module Hecks
       # `refuses` event, carrying what was said. A policy reacts to it, a
       # retry counter reads it, and nothing has to catch anything.
       #
-      # AN ASK IS HANDED THE RECORD IT IS ABOUT.
+      # An ask is handed the record it is about.
       #
-      # An INBOUND operation deliberately cannot read state — it is the
+      # An inbound operation deliberately cannot read state — it is the
       # anti-corruption boundary, translating a fact from outside, and letting
       # it read the aggregate would make it a second place rules live. That
       # rule was written for that direction and does not survive the crossing.
       #
       # An outbound one almost always needs the record. `asks "File"` names
       # `reference_to Ticket` and the adapter needs the ticket's repository,
-      # title and body — which are ON the ticket, and which the policy that
+      # title and body — which are on the ticket, and which the policy that
       # triggered this cannot supply because a command's event payload is its
-      # ARGUMENTS, not its state. Without this, every ask would have to have
+      # arguments, not its state. Without this, every ask would have to have
       # its data re-passed through the command that fired it, so the same text
       # would live in two places and could differ.
       #
-      # ARGUMENTS WIN over state, because an argument is what THIS call said
+      # Arguments win over state, because an argument is what this call said
       # and state is what the record happens to hold.
       def ask(ctx)
         payload = held_state(ctx).merge(materialise(ctx.args))
@@ -105,13 +128,13 @@ module Hecks
         announce(ctx, ctx.operation.refuses, ctx.args.merge(refusal: { value: "#{e.class}: #{e.message}" }))
       end
 
-      # THE ANSWER IS SPREAD, NOT NESTED — and that is what makes the loop
-      # close. A policy re-enters its target with the event payload VERBATIM;
+      # The answer is spread, not nested — and that is what makes the loop
+      # close. A policy re-enters its target with the event payload verbatim;
       # it cannot reach inside a key. So an answer tucked under `answered:`
       # can be read by a human and by nothing else, and the command that
       # should record the issue number never gets one.
       #
-      # Spread, the adapter's own keys ARE the arguments of whatever command
+      # Spread, the adapter's own keys are the arguments of whatever command
       # reacts to the answering event. Which is a real contract on the adapter
       # — it must return what that command takes, in the shape the runtime
       # coerces (`{ number: { value: 43 } }`, not `43`) — and naming it here
@@ -134,7 +157,7 @@ module Hecks
         end
       end
 
-      # THE RECORD, IF THERE IS ONE. A record that does not exist yet is not
+      # The record, if there is one. A record that does not exist yet is not
       # an error here — the ask still goes, carrying only its arguments, and
       # whatever the adapter makes of that is its own business. Refusing
       # would put a second existence check behind the one `resolve_references`
@@ -145,10 +168,10 @@ module Hecks
         {}
       end
 
-      # THE PORT THIS OPERATION BELONGS TO, found by asking the aggregate
+      # The port this operation belongs to, found by asking the aggregate
       # rather than threading it through the call — the dispatcher already
       # resolved it once to get here, and a second parameter carried purely so
-      # this method can read it would be a parameter every OTHER step ignores.
+      # this method can read it would be a parameter every other step ignores.
       def port_name_for(ctx)
         owning = ctx.aggregate.ports.find { |port| port.operations.any? { |op| op.equal?(ctx.operation) } }
         owning&.name or raise WiringError,
@@ -185,9 +208,9 @@ module Hecks
         [event]
       end
 
-      # THE ONE PLACE THIS DIFFERS FROM CommandRules::Emission — there is no
+      # The one place this differs from CommandRules::Emission — there is no
       # mutated instance to read an id off, because nothing was hydrated or
-      # saved. The record this event is ABOUT is named by whichever attribute
+      # saved. The record this event is about is named by whichever attribute
       # is a reference to the owning aggregate (PortOperationBuilder#build
       # already refused to build an operation with none), so its coerced
       # value — already a plain id, never an object, per