hecks 2.8.0 → 2.9.0

data/lib/hecks/runtime/command_rules/arithmetic.rb

@@ -6,127 +6,59 @@ require_relative "../value"
 module Hecks
   module Runtime
     class CommandRules
-      # The arithmetic half of mutation: what a source resolves to, and how
-      # increment/decrement land on an Integer or a one-numeric-field value
-      # object.
+      # The arithmetic half of mutation: source resolution, and how
+      # increment/decrement land on an Integer or a one-numeric-field value object.
       module Arithmetic
-        # The ops Runtime::CommandInterpreter applies — Vocabulary::MutationOp
-        # (language/bluebook/vocabulary.bluebook), read off the generated
-        # table, so increment/decrement's sign cannot drift from what the
-        # language says each op means. Every other op (set, append, multiply,
-        # clamp, remove, delegate, corrects) declares an empty sign — it does
-        # no add-or-subtract arithmetic — which reads here as nil.
+        # Mirrors Vocabulary::MutationOp (language/bluebook/vocabulary.bluebook) so
+        # increment/decrement's sign cannot drift from the language's own definition.
+        # Ops with no arithmetic (set, append, multiply, clamp, remove, delegate,
+        # corrects) declare an empty sign, which reads here as nil.
         MutationOp = Struct.new(:name, :sign, keyword_init: true)
 
         MUTATION_OPS = Hecks::Vocabulary.rows("MutationOp").map do |row|
           MutationOp.new(name: row["name"], sign: row["sign"].empty? ? nil : Integer(row["sign"]))
         end.freeze
 
-        # Reads what a mutation's source means: an argument's value for a Symbol, the literal
-        # itself for anything else.
+        # Resolves a mutation's source: an argument's value for a Symbol, the
+        # literal itself otherwise.
         #
-        # A mutation's source is either the name of an argument or a literal, and
-        # the two are told apart by type : a Symbol is always a name, a String or a
-        # number is always a value. Checked across all eight chapters — `to: :name`
-        # and `to: "sold"`, never a Symbol meant as a value.
+        # Looked up unconditionally, with no `args.key?` guard, so an absent
+        # optional argument resolves to nil instead of falling back to the
+        # symbol itself as a value.
         #
-        # The lookup is unconditional, with no `&& args.key?(source)` guard: such a
-        # guard makes an absent argument fall through to `source` and return the symbol
-        # itself as the value. `Customer.Register` without its `name` would set name to
-        # the literal `:name`, coercion would meet a Symbol where a PersonName belongs,
-        # and the refusal would read "name is a PersonName — pass its fields as an
-        # object, not :name" — a message describing a mistake the caller had not
-        # made. The real mistake, an absent argument, would never be the one refused,
-        # which is what fuzz surfaced.
-        #
-        # An absent argument resolving to nil is correct, not pending work. The
-        # language can say which arguments are optional (`attribute ...,
-        # optional: true` — `CommandBuilder#attribute_impl`,
-        # `attribute_collector.rb`): `sets` sources correctly from
-        # an optional attribute, resolving absent to nil exactly as this
-        # method does, and refusing it here would be wrong, not merely
-        # undone work — `TillRoom::Till.TakeIn`'s own `note` (spec/
-        # fixtures/till.bluebook) and Banking's `CardPayment.Authorize`'s
-        # `tags` (payment_cards.bluebook) are real, live commands whose
-        # `sets` mutation is deliberately sourced from an optional
-        # attribute the caller may omit — `spec/runtime/command_rules_spec
-        # .rb`'s own "says an absent optional argument is nil, not the
-        # name of the argument" pins exactly this as correct, not pending.
-        # The meta-domain's own self-hosted commands (Command.Declare's
-        # `role`/`goal`/`provenance`/`from`/`position`, and ~35 more sites
-        # across the language) all lean on the identical pattern — nil is
-        # the right answer for a `sets` sourced from a declared-optional
-        # attribute the caller left out, every time.
-        #
-        # The one narrow gap that leaves — a `sets` source Symbol naming
-        # nothing the command declares at all (a typo, not an optional
-        # argument), which would resolve to nil here, indistinguishable
-        # from a legitimate optional absence — is closed at build time
-        # instead of here: `CommandBuilder#refuse_unknown_argument_sources!`
-        # refuses it the moment the `.bluebook` file loads, mirroring
-        # `AggregateBuilder#seal_query_argument`'s identical check for a
-        # query's own where-clause argument. This function stays a pure,
-        # unconditional lookup because by the time any mutation reaches
-        # it, the source has already been proven to name either a real,
-        # possibly-optional argument, or a StateRef/literal; there is
-        # nothing left here to refuse.
-        #
-        # @param source [Symbol, Object] a mutation's source: a Symbol names a command argument,
-        #   anything else (String, Numeric, Array, Hash, `StateRef`) is returned as is
+        # @param source [Symbol, Object] a Symbol names a command argument, anything else
+        #   is returned as is
         # @param args [Hash{Symbol => Object}] the normalized command arguments
-        # @return [Object, nil] the named argument's value, nil when the caller left that
-        #   argument out; otherwise `source` itself
+        # @return [Object, nil] the argument's value, nil if omitted, or `source` itself
         def resolve_source(source, args)
           return args[source] if source.is_a?(Symbol)
 
           source
         end
 
-        # Adds or subtracts `amount` from an attribute's current value, on a bare number or on
-        # the one numeric field two value objects share.
+        # Adds or subtracts `amount`, on a bare number or the one numeric field two value
+        # objects share.
         #
-        # @param current [Numeric, Runtime::Value, nil] the attribute's pre-dispatch value; nil
-        #   (never set) counts as 0
-        # @param amount [Numeric, Runtime::Value] how much to move by; a value object is combined
-        #   field by field with a value-object `current`, and otherwise unwrapped to its single
-        #   numeric field
-        # @param target [Symbol, String] name of the attribute, used only to word a refusal
-        # @param sign [Integer] 1 to increment, -1 to decrement, as `sign_of` answers
-        # @return [Numeric, Runtime::Value] the new value: a `Runtime::Value` when both sides
-        #   are value objects, otherwise a bare number the caller re-wraps
-        # @raise [Runtime::TypeMismatch] if `amount` or `current` is not numeric, or two value
-        #   objects do not share exactly one numeric field
-        # @raise [Runtime::InvariantViolation] if a value-object result breaks one of its own
-        #   invariants
-        # @raise [Bluebook::Expression::EvaluationError] if the result does not fit a signed
-        #   64-bit Integer, or is a non-finite Float
+        # @param current [Numeric, Runtime::Value, nil] pre-dispatch value; nil (unset) is 0
+        # @param amount [Numeric, Runtime::Value] amount to move by
+        # @param target [Symbol, String] attribute name, for refusal wording only
+        # @param sign [Integer] 1 to increment, -1 to decrement
+        # @return [Numeric, Runtime::Value] `Runtime::Value` if both sides are, else a bare number
+        # @raise [Runtime::TypeMismatch] if either side isn't numeric, or shares no numeric field
+        # @raise [Runtime::InvariantViolation] if a value-object result breaks an invariant
+        # @raise [Bluebook::Expression::EvaluationError] if the result overflows Integer, or isn't
+        #   finite
         def arithmetic(current, amount, target, sign)
           op = sign.positive? ? "increment" : "decrement"
           current ||= 0
 
           return arithmetic_value_object(current, amount, target, sign, op) if current.is_a?(Value) && amount.is_a?(Value)
 
-          # `current` genuinely absent (no declared default, never set) and
-          # `amount` arrives VO-wrapped — a real command argument typed the
-          # same as the attribute, but with nothing to combine field-by-
-          # field against yet (that is what `arithmetic_value_object`,
-          # above, is for once both sides carry real fields). Before this,
-          # falling straight to `unless amount.is_a?(Numeric)` below
-          # refused with "increment needs an Integer, got 500" — true of
-          # nothing: 500 is exactly the Integer it asked for, just still
-          # wearing the Money wrapper the command's own declared attribute
-          # type put it in. Unwrapped here, the same shape #clamp already
-          # falls through to for an absent VO-typed attribute
-          # (`current ||= 0`, then a raw scalar) — the mutation applier
-          # re-wraps the raw result into the declared VO type on write,
-          # the same way it already does for clamp's own result.
+          # A VO-typed attribute with no declared default is genuinely absent
+          # here (`current` is 0, not a Value), so `amount` still needs
+          # unwrapping to compare against a bare number.
           amount = unwrap_single_numeric_field(amount) if amount.is_a?(Value)
 
-          # Widened from Integer to Numeric (migration plan task 4, i106):
-          # an external project's organ math increments a Float (`increment: 0.02`) --
-          # the raw, non-value-object path only ever mattered for Integer
-          # counters before this corpus existed. Integer stays the common
-          # case; Float is now accepted the same way.
           unless amount.is_a?(Numeric)
             raise TypeMismatch, RefusalWording.render_site("TypeMismatch", "arithmetic_amount",
                                                            op: op, target: target, offered: Rendering.describe(amount))
@@ -139,22 +71,19 @@ module Hecks
           bounded(current + (sign * amount), op, current, sign * amount, sign.positive? ? "+" : "-")
         end
 
-        # C3.3/C3.4 — an effect's arithmetic is held to the same value
-        # model an expression's is: Integer is signed 64-bit, Float is
-        # finite. A result outside that is an evaluation fault (never a
-        # refusal, C8.3), worded as the Rust kernel's own generated
-        # `checked_add`/`checked_sub`/`checked_mul` word it.
+        # An effect's arithmetic is held to the same value model an expression's is:
+        # Integer signed 64-bit, Float finite. Out of range is an evaluation fault,
+        # not a refusal (ADR checked_add/checked_sub/checked_mul wording).
         INT64_RANGE = (-(2**63))..((2**63) - 1)
 
-        # Passes an arithmetic result through only if it fits the value model: a signed 64-bit
-        # Integer or a finite Float.
+        # Passes an arithmetic result through only if it fits the value model: a signed
+        # 64-bit Integer or a finite Float.
         #
         # @param result [Numeric] the computed value to check
-        # @param oper [String] the op's name (`"increment"`, `"decrement"`, `"multiply"`),
-        #   the first word of the fault message
+        # @param oper [String] the op's name, the first word of the fault message
         # @param lhs [Numeric] the left operand, quoted in the fault message
         # @param rhs [Numeric] the right operand; its absolute value is quoted
-        # @param symbol [String] the operator to print between the operands: `"+"`, `"-"`, `"*"`
+        # @param symbol [String] the operator to print between the operands
         # @return [Numeric] `result`, unchanged
         # @raise [Bluebook::Expression::EvaluationError] if an Integer result is outside
         #   `INT64_RANGE`, or a Float result is NaN or infinite
@@ -171,31 +100,23 @@ module Hecks
                 "#{oper} overflowed: #{lhs} #{symbol} #{rhs.abs} is not a finite number"
         end
 
-        # Adds or subtracts on the one numeric field two value objects share, answering a new
-        # value object of `current`'s type.
+        # Adds or subtracts on the one numeric field two value objects share.
         #
         # @param current [Runtime::Value] the attribute's pre-dispatch value
-        # @param amount [Runtime::Value] how much to move by, coerced to the attribute's type
-        # @param target [Symbol, String] name of the attribute, used only to word a refusal
+        # @param amount [Runtime::Value] how much to move by
+        # @param target [Symbol, String] attribute name, for refusal wording only
         # @param sign [Integer] 1 to add, -1 to subtract
-        # @param oper [String] `"increment"` or `"decrement"`, for refusal and fault wording
-        # @return [Runtime::Value] a copy of `current` with the shared field replaced, rebuilt
-        #   and re-validated through `Value#with`
-        # @raise [Runtime::TypeMismatch] if the two do not share exactly one numeric field, or
-        #   the rebuilt value object refuses the new field value
-        # @raise [Runtime::InvariantViolation] if the new field value breaks one of the value
-        #   object's own invariants
-        # @raise [Bluebook::Expression::EvaluationError] if the result does not fit a signed
-        #   64-bit Integer, or is a non-finite Float
+        # @param oper [String] `"increment"`/`"decrement"`, for refusal/fault wording
+        # @return [Runtime::Value] `current`, with the shared field replaced
+        # @raise [Runtime::TypeMismatch] if the two share no numeric field, or the rebuilt refuses
+        # @raise [Runtime::InvariantViolation] if the new field value breaks an invariant
+        # @raise [Bluebook::Expression::EvaluationError] if the result overflows Integer, or isn't
+        #   finite
         def arithmetic_value_object(current, amount, target, sign, oper)
           current_fields = current.to_h
           amount_fields  = amount.to_h
-          # Widened from Integer to Numeric -- see #arithmetic's own
-          # comment. A synthesised value-object wrapper around a bare
-          # Float attribute (an external project's Synapse#strength, auto-wrapped per
-          # Part 3a's "bare primitives forbidden" finding) lands here as
-          # a one-Float-field Value exactly the way a one-Integer-field
-          # Value already did.
+          # A synthesized value-object wrapper around a bare numeric attribute
+          # always carries exactly one numeric field.
           shared_numeric = current_fields.keys.select do |field|
             current_fields[field].is_a?(Numeric) && amount_fields[field].is_a?(Numeric)
           end
@@ -209,54 +130,32 @@ module Hecks
                                       current[field], amount[field], sign.positive? ? "+" : "-"))
         end
 
-        # Looks up whether a mutation op adds or subtracts, from the generated `MUTATION_OPS` table.
+        # Looks up whether a mutation op adds or subtracts, from the generated
+        # `MUTATION_OPS` table.
         #
-        # Not a bare `.find(...)&.sign || -1` — that would silently answer
-        # decrement's sign for both an op this table has never heard of
-        # and a declared, real op that simply carries no sign at all
-        # (set/append/multiply/clamp/remove — see `MUTATION_OPS` above).
-        # Callers today only ever reach this for :increment/:decrement
-        # (both MutationApplier#apply and EntityInterpreter#
-        # apply_to_element gate every other op through their own `case`
-        # first, each with its own loud WiringError backstop), so this
-        # raise is not a real runtime path yet — it is the same
-        # backstop one level down, in case a future caller reaches
-        # #sign_of directly for an op that was never meant to have one.
+        # Not a bare `.find(...)&.sign || -1`: that would silently answer
+        # decrement's sign both for an unknown op and for a real op declared
+        # with no sign at all (set/append/multiply/clamp/remove/delegate/corrects).
         #
         # @param oper [Symbol, String] the mutation op's name, such as `:increment`
         # @return [Integer] 1 for increment, -1 for decrement
         # @raise [Runtime::WiringError] if the op is unknown, or is declared with no sign
-        #   (set, append, multiply, clamp, remove, delegate, corrects)
         def sign_of(oper)
           MUTATION_OPS.find { |candidate| candidate.name == oper.to_s }&.sign ||
             raise(WiringError, "no sign declared for mutation op #{oper.inspect} — add one before calling #sign_of")
         end
 
-        # Scales an attribute's current value by `amount`, on a bare number or on the one numeric
+        # Scales an attribute's current value by `amount`, on a bare number or the one numeric
         # field two value objects share.
         #
-        # Vendored addition, not (yet) upstream hecks (migration plan
-        # task 4, i106): `current * amount` -- the scaling counterpart to
-        # increment/decrement's add/subtract. Same raw-vs-value-object
-        # branch shape as #arithmetic/#arithmetic_value_object, reused
-        # rather than duplicated verb-for-verb (a `Proc` picks the actual
-        # arithmetic; everything else -- the Value unwrap/rewrap, the
-        # TypeMismatch refusals -- is identical to the additive pair).
-        #
-        # @param current [Numeric, Runtime::Value, nil] the attribute's pre-dispatch value; nil
-        #   (never set) counts as 0
-        # @param amount [Numeric, Runtime::Value] the factor; a value object is combined field
-        #   by field with a value-object `current`, and otherwise unwrapped to its single
-        #   numeric field
-        # @param target [Symbol, String] name of the attribute, used only to word a refusal
-        # @return [Numeric, Runtime::Value] the product: a `Runtime::Value` when both sides are
-        #   value objects, otherwise a bare number the caller re-wraps
-        # @raise [Runtime::TypeMismatch] if `amount` or `current` is not numeric, or two value
-        #   objects do not share exactly one numeric field
-        # @raise [Runtime::InvariantViolation] if a value-object result breaks one of its own
-        #   invariants
-        # @raise [Bluebook::Expression::EvaluationError] if the product does not fit a signed
-        #   64-bit Integer, or is a non-finite Float
+        # @param current [Numeric, Runtime::Value, nil] pre-dispatch value; nil (unset) is 0
+        # @param amount [Numeric, Runtime::Value] the factor
+        # @param target [Symbol, String] attribute name, for refusal wording only
+        # @return [Numeric, Runtime::Value] the product, a `Runtime::Value` when both sides are
+        # @raise [Runtime::TypeMismatch] if either side isn't numeric, or shares no numeric field
+        # @raise [Runtime::InvariantViolation] if a value-object result breaks an invariant
+        # @raise [Bluebook::Expression::EvaluationError] if the product overflows Integer, or isn't
+        #   finite
         def multiply(current, amount, target)
           current ||= 0
 
@@ -266,8 +165,7 @@ module Hecks
             end
           end
 
-          # Same absent-`current`, VO-wrapped-`amount` gap as `#arithmetic`
-          # — see that method's own comment.
+          # Same absent-current, VO-wrapped-amount gap as #arithmetic, above.
           amount = unwrap_single_numeric_field(amount) if amount.is_a?(Value)
 
           unless amount.is_a?(Numeric) && current.is_a?(Numeric)
@@ -282,35 +180,15 @@ module Hecks
         # Bounds an attribute's current value into `[min, max]`, on a bare number or on
         # the one numeric field the wrapping value object carries.
         #
-        # Vendored addition, not (yet) upstream hecks (migration plan
-        # task 4, i106): bound the current value into `[min, max]` -- no
-        # "amount" to combine, so it does not go through
-        # #arithmetic/#multiply's shared-numeric-field matching at all;
-        # it clamps whichever single numeric field the wrapping value
-        # object carries (a synthesised wrapper always carries exactly
-        # one, per Part 3a's auto-synthesis).
-        #
-        # @param current [Numeric, Runtime::Value, nil] the attribute's pre-dispatch value; nil
-        #   (never set) counts as 0
+        # @param current [Numeric, Runtime::Value, nil] pre-dispatch value; nil (unset) is 0
         # @param bounds [Array<Numeric>] the two-element `[min, max]` range to clamp into
-        # @param target [Symbol, String] name of the attribute, used only to word a refusal
+        # @param target [Symbol, String] attribute name, used only to word a refusal
         # @return [Numeric, Runtime::Value] the clamped value: a `Runtime::Value` when
         #   `current` is one, otherwise a bare number the caller re-wraps
         # @raise [Runtime::TypeMismatch] if `current` is a value object with no single
         #   numeric field, or is neither numeric nor a value object
         def clamp(current, bounds, target)
           min, max = bounds
-          # The same `current ||= 0` #arithmetic/#multiply both give a
-          # phantom (never-set) numeric field, one line up from each —
-          # this was the one arithmetic op that didn't, so a VO-typed
-          # attribute with no declared `default:` (genuinely absent,
-          # `Instance.defaults`/`#default_for`) hit TypeMismatch on the
-          # first clamp. (#arithmetic/#multiply's own absent-current gap
-          # is a real, separate bug: they do not silently treat an absent
-          # field as zero; they raise too, blaming a perfectly valid
-          # `amount` for not being an Integer when it is one, just still
-          # Money-wrapped. Fixed alongside this one — see
-          # #unwrap_single_numeric_field.)
           current ||= 0
           if current.is_a?(Value)
             fields = current.to_h
@@ -330,17 +208,9 @@ module Hecks
 
         private
 
-        # `amount` arrives VO-wrapped whenever the command's own declared
-        # attribute type says so (a real `Money`, not a bare Integer) —
-        # true whether or not `current` has ever been set. Only meaningful
-        # to call once `current` is known not to be a Value itself (the
-        # `current.is_a?(Value) && amount.is_a?(Value)` branch, above in
-        # both callers, already owns the case where both sides carry real
-        # fields to combine). Refuses rather than guesses when more than
-        # one field is numeric — genuinely ambiguous which one an absent
-        # `current` should be treated as zero for, the same reasoning
-        # `combine_value_object`'s own `shared_numeric.size == 1` check
-        # already holds to when both sides are present.
+        # Only meaningful once `current` is known not to itself be a Value (the
+        # both-sides-are-Values branch owns that case in each caller). Refuses
+        # rather than guesses when more than one field is numeric.
         def unwrap_single_numeric_field(value)
           fields = value.to_h
           numeric_fields = fields.keys.select { |field| fields[field].is_a?(Numeric) }

data/lib/hecks/runtime/command_rules/authorization.rb

@@ -6,44 +6,21 @@ require_relative "../../ports/authorization"
 module Hecks
   module Runtime
     class CommandRules
-      # Whether the caller may run this command at all — a `role` mismatch,
-      # the one check that runs before any domain-state work, alongside the
-      # argument gate rather than after it.
+      # Refuses a command whose declared `role` the ambient caller does not hold.
       #
-      # **Two checks, not a replacement** — ADR 0025 §9's own caution against
-      # "silently downgrading `role` to documentation" cuts both ways: a
-      # caller who never named who they are (every caller before this) is
-      # checked exactly the way it always has been, string equality
-      # against the command's own `role`. Only a caller that also binds an
-      # `actor_id` (`Hecks.as_caller(role:, actor_id:)`) reaches the
-      # real check — a live lookup through `Ports::Authorization`, once the
-      # command's domain has an authorization provider: its own chapter,
-      # or a framework member it attaches, declaring `provides
-      # "authorization"` (Governance, via `uses_framework "Governance"`).
-      # Boot refuses a domain that declares a `role` and has no provider —
-      # `Registry::Verification#refuse_ungoverned_roles!`. An identified caller is never
-      # let back through the string fallback: a real identity that holds
-      # no matching grant is refused, not waved through because it also
-      # happens to type the right word.
+      # A caller with an `actor_id` is checked against live grants when the domain has an
+      # authorization provider (ADR 0025); one without is compared by role string only.
       module Authorization
-        # Refuses the command when the ambient caller (`Caller.current`) does not hold the role
-        # the command declares.
+        # Refuses the command when the ambient caller (`Caller.current`) lacks its declared role.
         #
-        # Opt-in, on both sides. No caller bound: unchecked, exactly as
-        # today. No role declared: unchecked too — `role` is genuinely
-        # optional in this language (roughly a third of banking's own
-        # commands declare none), so a command that never named a role has
-        # nothing to check a caller against.
+        # Opt-in on both sides: no caller bound, or no role declared, means no check.
         #
-        # @param command [Bluebook::Command] the command about to run; its `role` is the one
-        #   required, and a nil or empty role means no check
-        # @param domain [String] name of the command's domain, whose authorization provider
-        #   answers the check
-        # @return [nil] when no caller is bound, no role is declared, or the caller is authorized
-        # @raise [Runtime::Unauthorized] if an identified caller holds no live grant of the role
-        #   where a provider is attached, or otherwise if the caller's role string differs
-        # @raise [Runtime::WiringError] if an identified caller is checked and zero or more than
-        #   one adapter implements the authorization port
+        # @param command [Bluebook::Command] the command about to run
+        # @param domain [String] name of the command's domain, whose provider answers the check
+        # @return [nil] when unchecked or authorized
+        # @raise [Runtime::Unauthorized] if the caller holds no grant of the role (identified
+        #   caller) or its role string differs (unidentified caller)
+        # @raise [Runtime::WiringError] if zero or several adapters implement the port
         def refuse_role_mismatch(command, domain)
           caller = Caller.current
           return unless caller
@@ -66,17 +43,8 @@ module Hecks
 
         private
 
-        # **Declared, not named** — `Registry#authorization_provider_for`.
-        #
-        # The provider's own commands are looked up too, not waved through
-        # the string fallback: `Governance::RoleAssignment.Assign` declares
-        # `role "Governance administrator"`, and an identified caller
-        # dispatching it is checked against a live assignment of that role
-        # like any other gated command (ADR 0025 §9). The Rust kernel's
-        # `check_role` (`rust/src/kernel/repository.rs`) does the same. The
-        # consequence is deliberate: the first administrator grant has to
-        # come from a caller that binds no `actor_id` (the unchecked,
-        # string-compared path) — a bootstrap step, not a hole.
+        # The provider's own commands are checked too, so the first administrator grant must
+        # come from a caller with no `actor_id` (the string-compared path).
         def governance_attached?(domain)
           !registry.authorization_provider_for(domain).nil?
         end

data/lib/hecks/runtime/command_rules/emission.rb

@@ -3,33 +3,20 @@ require_relative "../event"
 module Hecks
   module Runtime
     class CommandRules
-      # What a command's `emits` becomes: an Event in the registry's log,
-      # and — where the store can hold one — a recorded event beside the
-      # data it describes.
+      # Turns a command's `emits` into events in the registry's log and, where possible, the store.
       module Emission
-        # Builds one frozen event per name the command `emits`, appends each to the registry's
-        # event log, and records it in the store when the repository keeps events.
+        # Builds one frozen event per name the command `emits` and records each.
         #
-        # `correlation` arrives here rather than being merged onto the
-        # event afterwards. It is part of the transaction — known from
-        # `dispatch`'s own argument before anything is emitted — and an
-        # event that is still being written to is not yet a record of
-        # what happened. Setting it at construction is what lets the
-        # event be frozen the moment it exists.
+        # `correlation` is set at construction so the event can be frozen the moment it exists.
         #
         # @param command [Bluebook::Command] the command whose `emits` names the events
-        # @param domain [String] name of the emitting domain, the prefix of each event's
-        #   `aggregate` (`"Domain::Aggregate"`)
+        # @param domain [String] the emitting domain's name
         # @param aggregate [Bluebook::Aggregate] the aggregate the record belongs to
         # @param instance [Runtime::Instance] the settled record; its `id` stamps every event
-        # @param args [Hash{Symbol => Object}] the normalized command arguments, used as each
-        #   event's payload and deep-frozen by this call
-        # @param repository [Ports::Persistence::AppendOnly] the aggregate's repository; asked to
-        #   `record_event` only if it responds to it
-        # @param correlation [Hash, nil] saga correlation head => value for a saga-caused
-        #   dispatch; nil otherwise
-        # @return [Array<Runtime::Event>] the emitted events in `emits` order, each frozen;
-        #   `[]` when the command emits nothing
+        # @param args [Hash{Symbol => Object}] the normalized arguments, used as each payload
+        # @param repository [Ports::Persistence::AppendOnly] asked to `record_event` if it can
+        # @param correlation [Hash, nil] saga correlation for a saga-caused dispatch
+        # @return [Array<Runtime::Event>] the emitted events in `emits` order
         def emit(command, domain, aggregate, instance, args, repository, correlation = nil)
           command.emits.map do |event_name|
             event = Event.new(