hecks 2.7.0 → 2.9.0

data/lib/hecks/runtime/policy_interpreter.rb

@@ -8,11 +8,8 @@ require_relative "../bluebook/expression/evaluator"
 
 module Hecks
   module Runtime
-    # Fires the declared `policy` reactions triggered by one just-emitted
-    # event: scans every loaded bluebook (a policy commonly lives in a
-    # different domain than the event it reacts to), checks each
-    # candidate's `where` guard, and re-enters the dispatcher for each
-    # delivery — recording every outcome on the reaction log.
+    # Fires the declared `policy` reactions triggered by one just-emitted event,
+    # recording every outcome on the reaction log.
     class PolicyInterpreter
       attr_reader :registry
 
@@ -26,25 +23,14 @@ module Hecks
       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
-      # (an `event_qualifier` miss carries no reaction_log entry either) —
-      # 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
-      # 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.
+      # the registry's reaction log. A policy whose `where` does not hold logs nothing.
       #
       # @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
+      #   pair to run exactly (the outbox relay's consumer), instead of scanning every
+      #   loaded bluebook for candidates
       # @return [void]
       def react(event, domain, only: nil)
         selected = only ? [only] : policies_for(event, domain)
@@ -52,35 +38,17 @@ module Hecks
           result = deliver(policy, event, home_domain)
           next if result.nil?
 
+          # A for_each policy answers an array; Array(...) would explode a record Hash.
           (result.is_a?(Array) ? result : [result]).each { |record| @registry.reaction_log << record }
         end
       end
 
       private
 
-      # 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
-      # 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 —
-      # confirmed against the corpus's own .behaviors fixtures, several of
-      # 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
-      # 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,
-      # 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).
+      # 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
+      # emitting domain first, then load order, matching Outbox::Fanout and the Rust kernel.
       def policies_for(event, domain)
         emitting = Naming.demodulise(event.aggregate)
 
@@ -93,17 +61,9 @@ module Hecks
         end
       end
 
-      # 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
-      # `state`, so this is exactly the shape `enforce_givens` already
-      # gives a command's own given, minus the settled-record half a
-      # 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
-      # though the policy had merely declined to fire.
+      # 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.
       def where_holds?(policy, event)
         return true if policy.where.to_s.empty?
 
@@ -111,11 +71,7 @@ module Hecks
       end
 
       def deliver(policy, event, domain)
-        # `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
-        # trying to record the first one.
+        # `record` must exist before anything can raise: both rescues call `.merge` on it.
         target = "#{policy.target_domain || domain}::#{policy.trigger_command}"
         record = { policy: policy.name, on: event.name, trigger: target }
 
@@ -131,66 +87,26 @@ module Hecks
         @door.reenter(target, **reaction_invocation(target, args, policy, event))
         record.merge(delivered: true)
       rescue *DOMAIN_REFUSALS => e
-        # The target refused — a fact about the domain, recorded and not
-        # 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
-        # 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
-        # excludes, and for the reason that comment gives at length —
-        # 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
-        # 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
-        # see from where it sits: by the time `react` runs, the command
-        # 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
-        # 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
-        # is never silent, and left exactly where it happened for a human
-        # to find — never re-raised, and never swallowed either.
+        # A defect, not a refusal: recorded with `defect: true` and warned, never
+        # re-raised. The emitting command has already persisted, so propagating would
+        # only fail an unrelated caller. See DOMAIN_REFUSALS for why the two stay apart.
         warn "[hecks] defect in reaction — policy #{policy.name} on #{event.name} " \
              "firing #{target}: #{e.class}: #{e.message}"
         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
-      # 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
-      # 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
-      # 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
-      # 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
-      # own outer rescue already gives every other reaction.
+      # Runs the `for_each` query against the event payload and fires the trigger once
+      # per row, addressing each row by `addressing_key_for`. A refusal is recorded per
+      # row and the fan-out continues; a crash resolving the query or an unaddressable
+      # target is one top-level defect for the policy.
       def deliver_for_each(policy, event, domain, target, record)
         return nil unless where_holds?(policy, event)
 
         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 `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)
         reference_key = addressing_key_for(target, aggregate_name)
@@ -206,24 +122,9 @@ 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
-      # identity (`OpenForCustomer`'s own `reference:`, scoping by the
-      # 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
-      # 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
-      # an argument name by coincidence never gets misread as this one.
-      # Never overrides a value the payload already supplied.
+      # 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)
         return args unless query
@@ -242,26 +143,10 @@ module Hecks
         args
       end
 
-      # **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
-      # 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
-      # 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
-      # 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
-      # whether it read them or not.
+      # What the trigger is given: the whole event payload verbatim when no `with:` is
+      # declared, otherwise the projection (a Symbol names a payload field, anything else
+      # is a literal). `extra` is a fan-out's row key, merged into the source before the
+      # projection so a `with:` can name the row it acts on.
       def trigger_args(policy, event, extra = {})
         payload = event.payload.transform_keys(&:to_sym).merge(extra)
         return payload unless ReactionInvocation.projection_declared?(policy)
@@ -274,44 +159,16 @@ module Hecks
           label:     "#{policy.name}'s trigger"
         )
 
-        # 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).
+        # Raw inputs kept for Properties.dispatch_binding_fidelity's re-derivation.
         @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 same reasoning `for_each_query_args` gives one method up,
-      # 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
-      # 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
-      # dispatcher fell through to the captured piece's `id` as the
-      # 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.
-      #
-      # Offered under the emitting aggregate's own identity heads, only
-      # 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
-      # as the receiver (`Identity.of` coerces a scalar against a
-      # single-field VO head), and one naming it as a declared attribute
-      # carries it as a fact. The build-time validator admits the same
-      # names (`BluebookBuilder.check_with_spec!`).
+      # The emitting record's identity, offered to an explicit `with:` projection under
+      # the emitting aggregate's identity heads (never over a payload value). Without it
+      # a cross-aggregate reaction cannot say which record to address. The build-time
+      # validator admits the same names (`BluebookBuilder.check_with_spec!`).
       def emitter_identity(event)
         return {} if event.id.nil? || event.id.to_s.empty?
 
@@ -322,18 +179,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
-      # `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
-      # "a defect, not a refusal" treatment `resolve_query_aggregate`'s
-      # own `UnknownVerb` already gets one level up) rather than
-      # silently falling back on a guess when the target command cannot
-      # be resolved, or genuinely cannot be addressed by this aggregate
-      # at all — either is a domain-authoring mistake worth surfacing
-      # loudly, not a row this fan-out simply skips.
+      # 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)
@@ -355,9 +203,7 @@ 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
-        # result, or a projection could never name the row it acts on.
+        # The row key is already merged by `trigger_args`, so a projection can name it.
         @door.reenter(target, **reaction_invocation(target, args, policy, event))
         row_record.merge(delivered: true)
       rescue *DOMAIN_REFUSALS => e
@@ -374,14 +220,6 @@ module Hecks
         )
       end
 
-      # `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`
-      # instead.
-
       def resolve_query_aggregate(domain, aggregate_name, verb)
         bluebook = @registry.bluebook(domain) ||
                    raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "no_domain", domain: domain, verb: verb))

data/lib/hecks/runtime/port_operation_interpreter.rb

@@ -6,15 +6,8 @@ require_relative "../naming"
 
 module Hecks
   module Runtime
-    # The dispatch pipeline for a port operation — called by an adapter living
-    # outside the bluebook entirely, never by the domain itself. Deliberately
-    # a trimmed CommandInterpreter: the same payload gate and coercion
-    # (ArgumentGate, Interpreting#normalize_args), but no `given`, no
-    # `mutations`, no lifecycle, no save. A port operation does not act on an
-    # aggregate instance — it translates an external call into an event in
-    # this domain's own vocabulary, and whatever mutation follows happens
-    # wherever a `policy` reacts to that event, exactly as it would for any
-    # command-emitted one.
+    # Dispatch pipeline for a port operation, called by an adapter outside the bluebook.
+    # A trimmed CommandInterpreter: argument gate and coercion, but no `given`, mutations or save.
     class PortOperationInterpreter
       include Interpreting
       include CommandInterpreter::ArgumentGate
@@ -34,24 +27,17 @@ module Hecks
         @rules    = rules
       end
 
-      # `invocation` — the `Runtime::Invocation` `Dispatcher` built;
-      # `ctx.args` is its `to_args`, `ctx.route` its `target`.
-      #
+      # `ctx.args` is the invocation's `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
+      # @return [Array<Runtime::Event>] `emits` (inbound), or one `answers`/`refuses`
+      #   event (outbound; an adapter failure is recorded as `refuses`, not raised)
+      # @raise [Runtime::UnknownArgument] if `invocation` offers an undeclared argument
+      # @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 receiving record is missing
       def call(domain, aggregate, operation, invocation)
         ctx = Context.new(domain, aggregate, operation, invocation.to_args)
         ctx.invocation = invocation
@@ -89,37 +75,13 @@ module Hecks
         ctx.result = step(:emit) { ctx.operation.outbound? ? ask(ctx) : emit(ctx) }
       end
 
-      # 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
-      # 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
-      # not exist, a nil where a number was wanted — all of them become the
-      # `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.
+      # 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.
       #
-      # 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
-      # triggered this cannot supply because a command's event payload is its
-      # 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
-      # and state is what the record happens to hold.
+      # 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)
         payload = held_state(ctx).merge(materialise(ctx.args))
         answer  = adapter_for(ctx).public_send(Naming.snake(ctx.operation.hecks_name), **payload)
@@ -128,21 +90,10 @@ 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;
-      # 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
-      # 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
-      # is cheaper than a mapping layer nobody could see into.
-      #
-      # A non-Hash answer keeps the old shape: a port that returns a URL
-      # string has nothing to spread, and `answered:` is the honest word for
-      # a single unnamed value.
+      # The answer is spread, not nested: a policy re-enters its target with the event
+      # payload verbatim and cannot reach inside a key. The adapter's keys are therefore the
+      # arguments of the reacting command, in the shape the runtime coerces
+      # (`{ number: { value: 43 } }`, not `43`). A non-Hash answer is kept under `answered:`.
       def spread(answer)
         return { answered: answer } unless answer.is_a?(Hash)
 
@@ -157,21 +108,16 @@ module Hecks
         end
       end
 
-      # 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`
-      # already performed.
+      # 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.
       def held_state(ctx)
         ctx.instance ? Value.materialize(ctx.instance.state) : {}
       rescue StandardError
         {}
       end
 
-      # 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.
+      # 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) } }
         owning&.name or raise WiringError,
@@ -191,9 +137,7 @@ module Hecks
         end
       end
 
-      # A Value never crosses the boundary — an adapter is somebody else's
-      # code and should be handed plain data, the same reasoning `JsonDoor`
-      # gives for materialising before it hands anything to an HTTP caller.
+      # Adapters are handed plain data, never a Value.
       def materialise(args) = Value.materialize(args)
 
       def announce(ctx, event_name, payload)
@@ -208,13 +152,8 @@ module Hecks
         [event]
       end
 
-      # 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
-      # 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
-      # Value::Coercion#refuse_object_reference — is what stamps the event.
+      # 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|
           event = Event.new(