hecks 1.3.0 → 1.5.0

data/lib/hecks/runtime/entity_interpreter.rb

@@ -6,7 +6,7 @@ require_relative "identity"
 require_relative "instance"
 require_relative "value"
 require_relative "refusal_wording"
-require_relative "routing"
+require_relative "invocation"
 require_relative "dependency_planning"
 require_relative "../ports/persistence/execution"
 require_relative "entity_element"
@@ -23,9 +23,9 @@ module Hecks
     # entity-owned commands.
     class EntityInterpreter
       include Interpreting
-      # THE SAME PAYLOAD GATE aggregate commands and port operations already
-      # run — bug audit H1 (docs/audits/2026-08-10-main-bug-audit.md): this
-      # class used to run NEITHER refuse_unknown_arguments NOR
+      # The same payload gate aggregate commands and port operations already
+      # run — bug audit H1 (docs/audits/2026-08-10-main-bug-audit.md): without
+      # this, this class runs neither refuse_unknown_arguments nor
       # refuse_absent_arguments, on a comment claiming "an entity inherits
       # its aggregate's own gate." Nothing on the entity dispatch path ever
       # ran one — confirmed live, `LedgerEntry.Reverse` accepted an
@@ -39,11 +39,9 @@ module Hecks
 
       attr_reader :registry
 
-      # THE DECLARED ORDER, HAND-TYPED — mirrors Vocabulary::EntityDispatchOrder
-      # (language/bluebook/vocabulary.bluebook:217-232), held equal to it by
-      # spec/vocabulary_conformance_spec.rb the same way CommandInterpreter's
-      # own DISPATCH_ORDER is; see that constant's doc comment for why this is
-      # hand-typed rather than read live off the meta-domain at every dispatch.
+      # **The declared order** — Vocabulary::EntityDispatchOrder
+      # (language/bluebook/vocabulary.bluebook), read off the generated table
+      # the same way CommandInterpreter's own DISPATCH_ORDER is.
       # `refuse_unknown_arguments`/`refuse_absent_arguments` now lead it, same
       # position `AggregateDispatchOrder` holds them at (H1, above) — the only
       # remaining difference from the aggregate order is no
@@ -55,7 +53,7 @@ module Hecks
       # see that constant's own comment.
       MAX_STALE_WRITE_RETRIES = 5
 
-      # `instance` is the PARENT aggregate record (what gets saved and
+      # `instance` is the parent aggregate record (what gets saved and
       # returned) ; `element`/`view` are the entity piece itself — `view`
       # wraps `element` as it stood at `locate_element`, pre-mutation, and
       # `enforce_ensures` builds its own settled wrapper off `element` as it
@@ -63,7 +61,7 @@ module Hecks
       #
       # `chain` — S17, ADR 0026 — every entity the dotted verb passes
       # through, root-first (`[Handler, Dispatch]` for `Handler.Dispatch.
-      # Bind`) ; `entity`/`entity_name` stay the CHAIN'S OWN LAST entry,
+      # Bind`) ; `entity`/`entity_name` stay the chain's own last entry,
       # the one a command actually belongs to and a mutation actually
       # targets, so every step written before this ADR (enforce_givens,
       # apply_mutations, advance_lifecycle, element_identity, ...) reads
@@ -76,8 +74,66 @@ module Hecks
       Context = Struct.new(:domain, :aggregate, :entity, :entity_name, :command, :command_name,
                            :args, :repository, :instance, :chain, :element, :view, :transition,
                            :old_element, :result, :route, :plan, :persistence_outcome, :dry_run, :outbox_rows,
-                           :correction_bindings)
+                           :correction_bindings, :invocation)
 
+      # A dotted entity verb resolved against its aggregate. `Resolution.of`
+      # lives here rather than as a second public verb on the interpreter
+      # (spec/runtime/command_rules_spec.rb holds each interpreter to one),
+      # so `Dispatcher` can resolve it at the point `Invocation.from_call`
+      # reads the declaring command — after `to:` is parsed, before the
+      # facts are.
+      Resolution = Data.define(:entity_names, :chain, :command_name, :command) do
+        # Resolves a dotted entity verb against `aggregate` into the entity
+        # chain it walks and the command it names.
+        #
+        # Refuses UnknownVerb for an unknown entity or command.
+        #
+        # @param aggregate [Bluebook::Aggregate] the root aggregate the dotted verb
+        #   is resolved against
+        # @param dotted [String, Symbol] the entity verb, with the leading
+        #   "Domain::Aggregate." already stripped (e.g. `"Handler.Dispatch.Bind"`)
+        # @return [EntityInterpreter::Resolution] the resolved entity names, chain,
+        #   command name and command class
+        # @raise [Runtime::UnknownVerb] if `dotted` names no entity, or the located
+        #   entity declares no such command
+        def self.of(aggregate, dotted)
+          *entity_names, command_name = dotted.to_s.split(".")
+          if entity_names.empty?
+            raise UnknownVerb, RefusalWording.render_site("UnknownVerb", "entity_unknown",
+                                                          aggregate: aggregate.hecks_name, entity: dotted.to_s)
+          end
+
+          chain = walk(aggregate, entity_names)
+          command = chain.last.command(command_name) ||
+                    raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "entity_no_command",
+                                                                  entity: chain.last.hecks_name, command: command_name))
+          new(entity_names: entity_names, chain: chain, command_name: command_name, command: command)
+        end
+
+        # **One hop per dotted segment** — `ProcessManager.Handler.Dispatch.Bind`
+        # (once the dispatcher has already stripped "Domain::Aggregate.")
+        # walks Handler off the aggregate, then Dispatch off Handler, each
+        # step reading `.entities` exactly the way the single-level case
+        # always did — a nested entity is "structurally interchangeable
+        # with an aggregate" (Entity's own header) for precisely this
+        # reason. Two levels is what Handler/Dispatch need today ; nothing
+        # here assumes it stops at two.
+        def self.walk(aggregate, entity_names)
+          owner = aggregate
+          entity_names.map do |name|
+            found = owner.entities.find { |piece| piece.hecks_name == name } ||
+                    raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "entity_unknown",
+                                                                  aggregate: owner.hecks_name, entity: name))
+            owner = found
+            found
+          end
+        end
+        private_class_method :walk
+      end
+
+      # @param registry [Runtime::Registry] the booted registry this interpreter reads
+      # @param rules [Runtime::CommandRules] the shared rules engine (admissibility,
+      #   references, arithmetic, authorization, emission) dispatch runs through
       def initialize(registry, rules:)
         @registry = registry
         @rules    = rules
@@ -87,39 +143,57 @@ module Hecks
       # comment for the shared reasoning (Dispatcher#dry_run?'s own entry
       # point). `step_save`/`step_emit` are the only two steps here that
       # read it either.
-      # RETRIES THE WHOLE METHOD BODY on `StaleWrite` — same reasoning as
+      # Retries the whole method body on `StaleWrite` — same reasoning as
       # `CommandInterpreter#call`'s own retry: a fresh `ctx`, a fresh
       # `step_hydrate_parent`/`step_locate_element` re-reading current
       # state.
-      def call(domain, aggregate, dotted, legacy_args, route: nil, with: nil, dry_run: false)
-        *entity_names, command_name = dotted.to_s.split(".")
-        if entity_names.empty?
-          raise UnknownVerb, RefusalWording.render("UnknownVerb", "entity_unknown",
-                                                   aggregate: aggregate.hecks_name, entity: dotted.to_s.inspect)
-        end
-
-        chain  = walk_entity_chain(aggregate, entity_names)
-        entity = chain.last
-        command = entity.command(command_name) ||
-                  raise(UnknownVerb, RefusalWording.render("UnknownVerb", "entity_no_command",
-                                                           entity: entity.hecks_name, command: command_name.inspect))
-
-        args = Routing.payload(command, with: with, legacy: legacy_args)
+      #
+      # `resolution` is #resolve's answer; `invocation` the
+      # `Runtime::Invocation` `Dispatcher` built — `ctx.args` is its
+      # `to_args`, `ctx.route` its `target`.
+      #
+      # @param domain [String, Symbol] the domain `aggregate` belongs to
+      # @param aggregate [Bluebook::Aggregate] the root aggregate owning the entity
+      #   chain the command targets
+      # @param resolution [EntityInterpreter::Resolution] the resolved entity chain
+      #   and command, as `Resolution.of` builds it
+      # @param invocation [Runtime::Invocation] the invocation `Dispatcher` built for
+      #   this call
+      # @param dry_run [Boolean] whether to run every step through validation without
+      #   saving, emitting or enqueueing
+      # @return [Array(Runtime::Instance, Array<Runtime::Event>,
+      #   Runtime::DependencyPlanning::Plan, Ports::Persistence::Execution,
+      #   Array<Runtime::Outbox::Row>)] the settled parent aggregate instance, emitted
+      #   events, execution plan, persistence outcome and outbox rows — the last
+      #   three nil on a dry run, which skips save/emit/outbox
+      # @raise [StandardError] any class in `Runtime::DOMAIN_REFUSALS` when a
+      #   given/ensures/invariant/authorization/admissibility rule refuses
+      # @raise [Runtime::StaleWrite] if concurrent writers beat this one through every
+      #   retry (`MAX_STALE_WRITE_RETRIES`)
+      # @raise [Runtime::WiringError] if the aggregate's repository cannot be resolved
+      def call(domain, aggregate, resolution, invocation, dry_run: false)
+        chain        = resolution.chain
+        entity       = chain.last
+        command      = resolution.command
+        command_name = resolution.command_name
+        route        = invocation.target
+        args         = invocation.to_args
         attempt = 0
         begin
-          ctx = Context.new(domain, aggregate, entity, entity_names.join("."), command, command_name, args)
+          ctx = Context.new(domain, aggregate, entity, resolution.entity_names.join("."), command, command_name, args)
+          ctx.invocation = invocation
           ctx.chain = chain
           ctx.route = route
           ctx.dry_run = dry_run
           # `root_aggregate:` — `entity` is the immediate owner (what
           # `owner_fields` inside the Analyzer means), but a `parent.X`
-          # read inside this command's own given/ensures means the ROOT
-          # aggregate's own field, not the entity's — `aggregate` here IS
+          # read inside this command's own given/ensures means the root
+          # aggregate's own field, not the entity's — `aggregate` here is
           # that root (this method's own first parameter, never the
           # entity). See DependencyPlanning::Analyzer.call's own header
           # for the bug this closes.
           ctx.plan = DependencyPlanning::Analyzer.call(aggregate: entity, command: command, root_aggregate: aggregate)
-          # RESOLVED HERE, ONCE — see CommandInterpreter#call's own comment;
+          # **Resolved here, once** — see CommandInterpreter#call's own comment;
           # `step_hydrate_parent` reads `ctx.repository` without re-fetching.
           ctx.repository = @registry.repository(domain, aggregate)
           lock_id = Identity.best_effort(aggregate, args, route)
@@ -134,28 +208,13 @@ module Hecks
 
       private
 
-      # ONE HOP PER DOTTED SEGMENT — `ProcessManager.Handler.Dispatch.Bind`
-      # (once the dispatcher has already stripped "Domain::Aggregate.")
-      # walks Handler off the aggregate, then Dispatch off Handler, each
-      # step reading `.entities` exactly the way the single-level case
-      # always did — a nested entity is "structurally interchangeable
-      # with an aggregate" (Entity's own header) for precisely this
-      # reason. Two levels is what Handler/Dispatch need today ; nothing
-      # here assumes it stops at two.
-      def walk_entity_chain(aggregate, entity_names)
-        owner = aggregate
-        entity_names.map do |name|
-          found = owner.entities.find { |piece| piece.hecks_name == name } ||
-                  raise(UnknownVerb, RefusalWording.render("UnknownVerb", "entity_unknown",
-                                                           aggregate: owner.hecks_name, entity: name.inspect))
-          owner = found
-          found
-        end
-      end
+      # **A no-op, and untraced** — Vocabulary::EntityDispatchOrder's
+      # decode_arguments. See CommandInterpreter#step_decode_arguments.
+      def step_decode_arguments(_ctx); end
 
       # `extra_identity_heads:` — every entity `ctx.chain` walks through, not
       # just the root aggregate `ArgumentGate` already knows about. A
-      # two-hop dispatch (`Handler.Dispatch.Bind`) is addressed by BOTH
+      # two-hop dispatch (`Handler.Dispatch.Bind`) is addressed by both
       # hops' own identity, each read straight out of `args` by
       # `EntityElement#element_of` — refusing those as unknown would refuse
       # every legitimate nested-entity dispatch there is, the same reasoning
@@ -202,30 +261,30 @@ module Hecks
         ctx.element = step(:locate_element) do
           EntityElement.locate_chain(ctx.aggregate, ctx.chain, ctx.instance, ctx.args, ctx.command_name, ctx.route)
         end
-        # `view` was hydrated ONCE, here, into its OWN state hash
+        # `view` was hydrated once, here, into its own state hash
         # (Value.hydrate builds a fresh Hash — never aliased with `element`)
         # — exactly right for enforce_givens, which must read pre-mutation.
         ctx.view = Instance.new(aggregate: ctx.entity, id: EntityElement.element_identity(ctx.entity, ctx.element).to_s,
                                 state: ctx.element)
       end
 
-      # BUG#30 — THE ENTITY-LEVEL HALF OF `CommandInterpreter#step_enforce_
+      # BUG#30 — the entity-level half of `CommandInterpreter#step_enforce_
       # givens`'s own structural-before-declared ordering (see that
       # method's comment for the shared reasoning): "does the fact this
       # command's `corrects` names even exist" is checked here too, once,
       # before the entity's own `given`s.
       #
-      # ADMISSIBILITY IS CHECKED AGAINST THE PARENT/ROOT, NOT THE ENTITY —
-      # deliberately `ctx.instance`/`ctx.aggregate` (the PARENT aggregate
-      # record and the ROOT aggregate construct), never `ctx.view`/
+      # Admissibility is checked against the parent/root, not the entity —
+      # deliberately `ctx.instance`/`ctx.aggregate` (the parent aggregate
+      # record and the root aggregate construct), never `ctx.view`/
       # `ctx.entity` (the entity's own pre-mutation view/construct). This
-      # is not a simplification; it is the ONLY choice that lines up with
+      # is not a simplification; it is the only choice that lines up with
       # how the event being corrected was actually recorded: an entity has
       # no event stream of its own — `CommandRules::Emission#emit` (called
-      # from THIS class's own `step_emit`, and from `CommandInterpreter`'s
+      # from this class's own `step_emit`, and from `CommandInterpreter`'s
       # `step_emit` for an aggregate-level command alike) always stamps an
-      # emitted event with the ROOT aggregate's own qualified name
-      # (`"#{domain}::#{aggregate.hecks_name}"`) and the PARENT record's
+      # emitted event with the root aggregate's own qualified name
+      # (`"#{domain}::#{aggregate.hecks_name}"`) and the parent record's
       # own id (`ctx.instance.id`), regardless of which level dispatched
       # it. `enforce_correction_target` (CommandRules::Admissibility)
       # looks a correction target up by exactly those two fields plus the
@@ -234,31 +293,31 @@ module Hecks
       # carry, and every entity-level correction would refuse
       # (NothingToCorrect) even against a real, already-emitted event.
       # `qa/stress_domains/corrections`' own `Entry.Amend` (corrects
-      # "EntryRecorded", which `Ledger.Record` — an AGGREGATE-level
+      # "EntryRecorded", which `Ledger.Record` — an aggregate-level
       # command — actually emits) is exactly this shape: the corrected
-      # event's `aggregate`/`id` are the LEDGER's, never the Entry's own
+      # event's `aggregate`/`id` are the ledger's, never the Entry's own
       # (an Entry has no id an event could be filed under in the first
       # place). `Fuzzing::Properties::Corrections#corrections_reference_
       # an_emitted_event` independently encodes the identical rule
-      # (`aggregate_key` built off the OUTER aggregate for both the
+      # (`aggregate_key` built off the outer aggregate for both the
       # `corrects` target and the `emits` produced event, regardless of
       # entity nesting depth) — this is that property's dispatch-time
       # enforcement counterpart, not a new invention.
       #
       # One structural consequence, worth being explicit about for a
-      # Rust port: because the lookup is scoped to the PARENT record
+      # Rust port: because the lookup is scoped to the parent record
       # (not to any one entity element within it), an entity-level
       # `corrects` only proves "this parent record has emitted the named
-      # event at some point" — it does NOT, and cannot, further narrow
+      # event at some point" — it does not, and cannot, further narrow
       # to "...specifically for THIS entity element" (a Ledger with three
       # Entries all satisfy the same `EntryRecorded`-was-emitted check).
-      # That is not a gap this fix introduces: it is the SAME granularity
+      # That is not a gap this fix introduces: it is the same granularity
       # the aggregate-level check already has (one record, one event
       # history), just observed from one level down. A command wanting a
       # tighter, element-specific correlation has to encode it itself, in
       # its own `given`s, off `correction`-bound payload fields.
       #
-      # `correction:` bindings computed here are threaded through to BOTH
+      # `correction:` bindings computed here are threaded through to both
       # halves of the same command's admissibility, same as the
       # aggregate-level path: `ctx.correction_bindings` is read again by
       # `step_enforce_ensures`, below, so an `as:`-named binding is
@@ -292,7 +351,7 @@ module Hecks
         step(:advance_lifecycle) { ctx.element[ctx.entity.lifecycle.field] = ctx.transition.target }
       end
 
-      # An ensures reads the SETTLED record, so it needs a view hydrated from
+      # An ensures reads the settled record, so it needs a view hydrated from
       # `element` as it stands now, mutations included — unlike `view` above,
       # built once and read pre-mutation by enforce_givens.
       def step_enforce_ensures(ctx)
@@ -309,9 +368,9 @@ module Hecks
         end
       end
 
-      # THE PARENT AGGREGATE's own invariants — `ctx.instance` is the
+      # The parent aggregate's own invariants — `ctx.instance` is the
       # parent record an entity mutation writes into (this file's own
-      # `Context` comment), the SAME boundary an aggregate-level
+      # `Context` comment), the same boundary an aggregate-level
       # invariant guards regardless of which interpreter changed it. No
       # separate "entity invariant" exists (S10, ADR 0025 scopes
       # `invariant` to the aggregate only) — see `Admissibility#
@@ -320,21 +379,23 @@ module Hecks
         step(:enforce_invariants) { @rules.enforce_invariants(ctx.instance, ctx.aggregate, domain: ctx.domain) }
       end
 
-      # `dry_run:` skips this — see CommandInterpreter#step_save's own
-      # comment, same reasoning and the same precedent
-      # (`step_assign_creation_attributes`'s own conditional-skip).
+      # `dry_run:` skips the write half of this step — see
+      # CommandInterpreter#step_save's own comment (BUG#127): the
+      # reference-existence check stays unconditional, only the actual
+      # persist is behind the early return.
       def step_save(ctx)
+        step(:save) { @rules.resolve_state_references(ctx.domain, ctx.aggregate, ctx.instance.state) }
+
         return if ctx.dry_run
 
         step(:save) do
-          @rules.resolve_state_references(ctx.domain, ctx.aggregate, ctx.instance.state)
           # `expected_version:` — see CommandInterpreter#step_save's own
           # comment: nil for a repository that isn't CAS-capable, or an
           # instance never read from storage, either of which falls
           # through to a plain save inside `AppendOnly#save`.
           ctx.persistence_outcome = ctx.repository.save(ctx.instance, expected_version: ctx.instance.version)
           if ctx.persistence_outcome.status == :stale
-            # NOT a `RefusalWording.render` call — see
+            # Not a `RefusalWording.render` call — see
             # `CommandInterpreter#step_save`'s identical branch and
             # `Runtime::StaleWrite`'s own comment.
             raise(StaleWrite,
@@ -353,7 +414,7 @@ module Hecks
         ctx.result = step(:emit) { @rules.emit(ctx.command, ctx.domain, ctx.aggregate, ctx.instance, ctx.args, ctx.repository) }
       end
 
-      # THE PARENT AGGREGATE, addressed exactly as `CommandInterpreter#hydrate`
+      # The parent aggregate, addressed exactly as `CommandInterpreter#hydrate`
       # addresses one acting on itself — derive from the declared identity first
       # (`Identity.of`), and let a bare `id:` name an already-derived record when
       # the identity itself is not what the caller is holding.
@@ -361,24 +422,24 @@ module Hecks
         parent_id = route&.aggregate ||
                     Identity.of(aggregate, args) ||
                     Identity.from(aggregate, args, :id) ||
-                    raise(NotFound, RefusalWording.render("NotFound", "entity_parent_no_identity",
-                                                          command: command_name, aggregate: aggregate.hecks_name,
-                                                          entity: entity_name, identity: Identity.reading(aggregate)))
+                    raise(NotFound, RefusalWording.render_site("NotFound", "entity_parent_no_identity",
+                                                               command: command_name, aggregate: aggregate.hecks_name,
+                                                               entity: entity_name, identity: Identity.reading(aggregate)))
         found = repository.find(parent_id) ||
-                raise(NotFound, RefusalWording.render("NotFound", "record_missing",
-                                                      aggregate: aggregate.hecks_name,
-                                                      identity:  Identity.reading(aggregate),
-                                                      offered:   Rendering.describe(parent_id)))
+                raise(NotFound, RefusalWording.render_site("NotFound", "record_missing",
+                                                           aggregate: aggregate.hecks_name,
+                                                           identity:  Identity.reading(aggregate),
+                                                           offered:   Rendering.describe(parent_id)))
         found.dup
       end
 
       # `locate_chain`/`element_of`/`element_identity`/`apply_to_element` and
-      # their own helpers used to live here — moved to `Runtime::EntityElement`
-      # (see that file's own header) so `CommandInterpreter`'s own
-      # `delegate_to_entity` step can locate and mutate the same element the
-      # same way, against an aggregate record already held in memory. `call`,
-      # above, and every `step_*` method reach them through that module now;
-      # nothing about the STEPS themselves changed.
+      # their own helpers live in `Runtime::EntityElement`
+      # (see that file's own header), shared rather than kept here, so
+      # `CommandInterpreter`'s own `delegate_to_entity` step can locate and
+      # mutate the same element the same way, against an aggregate record
+      # already held in memory. `call`, above, and every `step_*` method
+      # reach them through that module.
     end
   end
 end

data/lib/hecks/runtime/errors.rb

@@ -2,17 +2,21 @@ require_relative "value/invariant_violation"
 require_relative "../vocabulary"
 
 module Hecks
+  # What runs a booted domain: dispatch, the command/entity/query/policy/saga
+  # interpreters, the registry a boot assembles, and the errors below —
+  # everything downstream of a `.bluebook`/`.hecksagon`/`.world` declaration.
+  # See `lib/hecks/runtime.rb` for the module's own facade and boot entry points.
   module Runtime
     class UnknownVerb < StandardError; end
     class EnsuresNotMet < StandardError; end
 
     # `detail` — the failing comparison's own resolved operands, "left: X,
-    # right: Y" — set only when the given's TOP-LEVEL shape is a bare
+    # right: Y" — set only when the given's top-level shape is a bare
     # comparison (`Evaluator.comparison_detail`'s own comment has the full
-    # scoping); nil otherwise. Deliberately NOT folded into `#message`:
+    # scoping); nil otherwise. Deliberately not folded into `#message`:
     # that string is pinned byte-for-byte across this corpus's own specs
     # (`raise_error(GivenNotMet, "...")`, command_rules_spec.rb and every
-    # domain that vendors this gem) as CONTRACT, so changing its shape by
+    # domain that vendors this gem) as contract, so changing its shape by
     # default would be a breaking change for every one of them. Riding on
     # `#detailed_message` instead (Ruby 3.2+, what irb/a Rails console's
     # own unhandled-exception banner already calls to show more than
@@ -21,11 +25,21 @@ module Hecks
     class GivenNotMet < StandardError
       attr_reader :detail
 
+      # @param message [String, nil] the refusal text, pinned byte-for-byte across specs
+      # @param detail [String, nil] the failing comparison's resolved operands ("left: X,
+      #   right: Y"), or nil when the given's top-level shape is not a bare comparison
       def initialize(message = nil, detail: nil)
         super(message)
         @detail = detail
       end
 
+      # Renders `message` with `detail` appended, for a human reading an unhandled refusal.
+      #
+      # @param highlight [Boolean] unused; accepted for compatibility with `Exception#
+      #   detailed_message`'s own signature
+      # @param opts [Hash] unused; accepted for compatibility with `Exception#
+      #   detailed_message`'s own signature
+      # @return [String] `message`, with `" (#{detail})"` appended when `detail` is present
       def detailed_message(highlight: false, **opts)
         base = super
         detail ? "#{base} (#{detail})" : base
@@ -39,7 +53,7 @@ module Hecks
     # is the right name carrying the wrong thing, this one is a name the command
     # never had. Both are the payload gate refusing before any rule runs.
     class UnknownArgument < StandardError; end
-    # The third of the trio, and the one that was missing : a name the command DOES
+    # The third of the trio, and the one that was missing : a name the command does
     # declare, absent. TypeMismatch is the right name carrying the wrong thing,
     # UnknownArgument a name that was never declared, AbsentArgument a declared name
     # that never arrived. Between them they say a command takes exactly the
@@ -56,18 +70,18 @@ module Hecks
     # `given`/`ensures`/`invariant` that reads the field would otherwise
     # evaluate against a value nobody wrote, which is the same silent-
     # wrong-answer class as an unpopulated projection reading "not
-    # active" (ADR 0025, "Added attributes and absence"). An OPTIONAL
+    # active" (ADR 0025, "Added attributes and absence"). An optional
     # attribute in the same spot reads nil instead — that is what
     # optional means, and this refusal is deliberately narrower than the
     # nil-read it sits beside, not a replacement for it.
     class AttributeAbsent < StandardError; end
-    # THE SAME SILENT-WRONG-ANSWER CLASS AS ABOVE, one line up — a
+    # The same silent-wrong-answer class as above, one line up — a
     # `projects` field (S12, ADR 0025) this record predates, or that no
     # rebuild sweep has populated yet, read by a `given`/`ensures`/
     # `invariant` as though it carried a real value. `GuardState` is
     # the one place this is raised, the same way AttributeAbsent is —
-    # a DECLARED field the record does not yet carry, distinguished
-    # from that one only in WHY: an ordinary attribute is absent
+    # a declared field the record does not yet carry, distinguished
+    # from that one only in why: an ordinary attribute is absent
     # because nobody backfilled it, a projected field is absent
     # because nobody has swept it yet.
     class ProjectionAbsent < StandardError; end
@@ -79,14 +93,14 @@ module Hecks
     class Unauthorized < StandardError; end
     # `corrects` names a past event this record must have already emitted
     # (CommandBuilder#corrects_impl's own comment) — a fact the expression
-    # evaluator cannot check (it is not a predicate over the record's OWN
+    # evaluator cannot check (it is not a predicate over the record's own
     # fields, it is "did this exact record ever announce this"), so it is
     # raised structurally, the same way AlreadyExists/NotFound are, rather
     # than being expressible as an ordinary `given`. Raised by
     # `CommandRules::Admissibility#enforce_correction_target`.
     class NothingToCorrect < StandardError; end
 
-    # A RUNTIME FAULT, NOT A DOMAIN REFUSAL — deliberately absent from
+    # A runtime fault, not a domain refusal — deliberately absent from
     # `DOMAIN_REFUSALS` below and from `vocabulary.bluebook`'s own
     # `DomainRefusal` list. Raised when an optimistic-concurrency CAS write
     # (`AppendOnly#save`'s `expected_version:`) finds the stored version has
@@ -102,29 +116,29 @@ module Hecks
 
     # A Lambda-routed domain's own refusal (rust/host, `Runtime::
     # RemoteDispatcher`), carrying Rust's own refusal text verbatim —
-    # NOT yet mapped back to the specific matching class above
+    # not yet mapped back to the specific matching class above
     # (GivenNotMet vs. EnsuresNotMet vs. ...), a real, known,
     # documented gap: the WASM projector's own event/refusal-wording
-    # parity work (ADR 0021) makes the TEXT match Ruby's, but nothing
+    # parity work (ADR 0021) makes the text match Ruby's, but nothing
     # yet parses that text back into a typed Ruby exception the way a
     # local dispatch already raises one directly. Callers that only
     # need "the domain said no" (not which specific rule) are
-    # unaffected; callers pattern-matching a SPECIFIC refusal class
+    # unaffected; callers pattern-matching a specific refusal class
     # against a Lambda-routed domain are the ones this gap would bite.
     class RemoteRefusal < StandardError; end
 
-    # The domain saying NO — the errors a reaction may legitimately meet and
+    # The domain saying no — the errors a reaction may legitimately meet and
     # record as an undelivered outcome. A policy whose target refuses is a fact
     # about the domain ; the originating command still stands.
     #
-    # Everything ELSE is a defect : a NoMethodError in an interpreter, a
+    # Everything else is a defect : a NoMethodError in an interpreter, a
     # NameError from a missing constant, a TypeError from a bad assumption. A
-    # blanket `rescue StandardError` used to fold both into one line —
-    # `delivered: false, reason: "..."` — so a crash in the runtime was
-    # indistinguishable from a rule doing its job, and read as normal operation
-    # in the log.
+    # blanket `rescue StandardError` would fold both into one line —
+    # `delivered: false, reason: "..."` — making a crash in the runtime
+    # indistinguishable from a rule doing its job, reading as normal
+    # operation in the log.
     #
-    # UnknownVerb IS one of these, and deliberately : a cross-domain policy
+    # UnknownVerb is one of these, and deliberately : a cross-domain policy
     # (`across "Notifications"`) fires in deployments where that domain is not
     # loaded, and recording the undelivered reaction rather than raising is the
     # design — spec/policy_spec states it in so many words, "records a reaction
@@ -133,12 +147,12 @@ module Hecks
     # its own rule is the domain saying no as plainly as a given is — but the
     # class is declared over in value.rb and never made the list, so the policy
     # and saga interpreters, which rescue exactly these, would let it propagate
-    # as though the RUNTIME had broken. A reaction whose target violates an
+    # as though the runtime had broken. A reaction whose target violates an
     # invariant is declined, not crashed. Found by spec/domain_refusal_spec on
     # its first run : every corpus refusal must be a class named here, and 23
     # of banking's were InvariantViolation.
-    # THE NAMES COME FROM THE LANGUAGE, the classes from this module.
-    # `DomainRefusal` declares WHICH refusals are the domain's own —
+    # The names come from the language, the classes from this module.
+    # `DomainRefusal` declares which refusals are the domain's own —
     # a rule the caller broke — as against a runtime fault. Resolving
     # each name here means a refusal declared but never defined fails
     # at load with a NameError, rather than being quietly absent from

data/lib/hecks/runtime/event.rb

@@ -2,7 +2,7 @@ require "time"
 
 module Hecks
   module Runtime
-    # `correlation` is NOT on the wire — `to_h` below deliberately omits it,
+    # `correlation` is not on the wire — `to_h` below deliberately omits it,
     # the same as `bin/run`'s own event projection does. It is runtime
     # bookkeeping stamped by `Dispatcher#dispatch` when a saga leg's own
     # dispatch causes this event (see `SagaInterpreter#deliver_saga_dispatch`
@@ -11,20 +11,25 @@ module Hecks
     # one correlating on a different field. Absent for any event no saga
     # dispatch caused, which is most of them.
     Event = Struct.new(:name, :aggregate, :id, :payload, :occurred_at, :correlation, keyword_init: true) do
-      # AN EMITTED EVENT IS A RECORD OF SOMETHING THAT HAPPENED, and a
-      # mutable audit trail is not one. The PAYLOAD — the domain fact the
-      # event carries — is frozen THROUGH on emission: freezing the Hash
+      # Freezes the event deep, so nothing about it can change after it happens.
+      #
+      # An emitted event is a record of something that happened, and a
+      # mutable audit trail is not one. The payload — the domain fact the
+      # event carries — is frozen through on emission: freezing the Hash
       # alone would leave every value in it editable in place, which is
       # the shape all four previous freezing bugs had.
       #
-      # THE WHOLE EVENT, not just its payload. Correlation used to be
-      # merged onto already-emitted events by `Dispatcher#dispatch`, which
-      # is what kept an event writable after it had happened; it is set at
-      # construction now, because it is part of the transaction and known
-      # from `dispatch`'s own argument before anything is emitted.
+      # The whole event, not just its payload. Correlation is set at
+      # construction rather than merged in here by `Dispatcher#dispatch`
+      # after the event already exists, because it is part of the
+      # transaction and known from `dispatch`'s own argument before
+      # anything is emitted — that is what keeps an event immutable once
+      # it exists.
       #
-      # The LOG stays appendable: new events are still recorded. It is
+      # The log stays appendable: new events are still recorded. It is
       # each event that stops changing once it exists.
+      #
+      # @return [void]
       def emit!
         Freezer.deep(payload)
         Freezer.deep(correlation)