hecks 1.4.0 → 1.5.0

data/lib/hecks/runtime/dispatcher.rb

@@ -1,5 +1,4 @@
 require_relative "errors"
-require_relative "../deprecation"
 require_relative "refusal_wording"
 require_relative "caller"
 require_relative "invocation"
@@ -121,22 +120,21 @@ module Hecks
       # Runs one command, entity command or port operation, then every policy and saga reaction
       # its events are owed.
       #
-      # Loose keyword facts are deprecated (roadmap I3) — `dispatch(verb,
-      # amount: 5)` still works, and warns once per call site; pass
-      # `with: { amount: 5 }` (and the receiver in `to:`) instead. The
-      # keyword door closes in `LEGACY_ARGS_REMOVAL`. `bin/codemod_legacy_
-      # dispatch_args` rewrites existing callers.
+      # The receiver in `to:`, the facts in `with:`, and nothing else.
+      # Loose keyword facts — `dispatch(verb, amount: 5)`, one bag holding
+      # both the route and the payload — were deprecated in 1.3.x and are
+      # gone: Ruby now refuses them itself, by name ("unknown keyword:
+      # :amount"). Code holding a bag of data rather than written keywords
+      # calls `dispatch_flat` below; that door is not going anywhere.
       #
       # @param verb [String] the fully qualified verb: `"Domain::Aggregate.Command"`,
       #   `"Domain::Aggregate.Entity.Command"` or `"Domain::Aggregate.Port.Operation"`
       # @param to [String, Hash, nil] the receiver: an aggregate identity, or an entity route
       #   Hash with `:aggregate` and one of `:entity`/`:entities`; nil when the facts carry
       #   the identity themselves
-      # @param with [Hash, nil] the command's facts, keyed by argument name (String or Symbol);
-      #   may not be combined with loose keyword facts
+      # @param with [Hash, nil] the command's facts, keyed by argument name (String or Symbol)
       # @param saga_correlation [Hash, nil] correlation head => value, stamped on every
       #   emitted event when a saga leg causes this dispatch; nil otherwise
-      # @param legacy_args [Hash{Symbol => Object}] deprecated loose keyword facts
       # @return [Runtime::Dispatcher::Result] the verb, settled instance (nil for a port
       #   operation), emitted events, execution plan and persistence outcome
       # @raise [Runtime::UnknownVerb] if the verb is not fully qualified, or names a domain,
@@ -145,39 +143,20 @@ module Hecks
       #   the call (`GivenNotMet`, `TypeMismatch`, `Unauthorized`, `NotFound`, …)
       # @raise [Runtime::StaleWrite] if concurrent writers beat this one through every retry
       # @raise [Runtime::WiringError] if the aggregate's repository cannot be resolved
-      # @raise [Deprecation::Error] if loose keyword facts are given where
-      #   `Deprecation.raise_on!(:legacy_dispatch_args)` applies
-      def dispatch(verb, to: nil, with: nil, saga_correlation: nil, **legacy_args)
-        Dispatcher.deprecate_loose_facts(legacy_args)
-        dispatch_invocation(verb, to: to, with: with, saga_correlation: saga_correlation, legacy_args: legacy_args)
-      end
-
-      LEGACY_ARGS_REMOVAL = "1.5.0".freeze
-      LEGACY_ARGS_WARNING =
-        "passing command facts to dispatch as loose keyword arguments is deprecated and will be removed in " \
-        "hecks #{LEGACY_ARGS_REMOVAL} — pass them as `with: { ... }`, with the receiver identity in `to:` " \
-        "(bin/codemod_legacy_dispatch_args rewrites existing callers)".freeze
-
-      # Warns, once per call site, that a dispatch passed its facts as loose keyword arguments.
-      #
-      # @param legacy_args [Hash] the loose keyword facts a dispatch received; empty means
-      #   nothing deprecated was used, and nothing is warned
-      # @return [nil] always, whether or not a warning was issued
-      # @raise [Deprecation::Error] if `legacy_args` is not empty where
-      #   `Deprecation.raise_on!(:legacy_dispatch_args)` applies
-      def self.deprecate_loose_facts(legacy_args)
-        Deprecation.call(:legacy_dispatch_args, LEGACY_ARGS_WARNING) unless legacy_args.empty?
+      def dispatch(verb, to: nil, with: nil, saga_correlation: nil)
+        dispatch_invocation(verb, to: to, with: with, saga_correlation: saga_correlation, flat: {})
       end
 
       # Dispatches a verb whose receiver and facts arrive together in one flat Hash.
       #
-      # **The flat-facts wire form** — one Hash, not keywords, and not
-      # deprecated: the shape `spec/corpus/*.json` steps, the Rust kernel's
-      # `cli.rs` contract, a reaction without a `with:` projection, and the
-      # self-hosted meta-domain all carry. Routes exactly as
-      # `dispatch(verb, **args)` does: a Symbol `:to`, `:with` or
+      # **The flat-facts wire form** — one Hash, not keywords: the shape
+      # `spec/corpus/*.json` steps, the Rust kernel's `cli.rs` contract, a
+      # reaction without a `with:` projection, and the self-hosted
+      # meta-domain all carry, where the receiver's identity is one of the
+      # keys because that is how the wire spells it. Routes exactly as the
+      # removed keyword door did: a Symbol `:to`, `:with` or
       # `:saga_correlation` key is lifted out as that keyword, everything
-      # else is a fact (so a String "to" key stays a fact).
+      # else is a fact (so a String "to" key stays a fact, as it did).
       # Framework code that replays data calls this; application code
       # calls `dispatch(verb, to:, with:)`.
       #
@@ -196,10 +175,10 @@ module Hecks
         to = facts.delete(:to)
         with = facts.delete(:with)
         saga_correlation = facts.delete(:saga_correlation)
-        dispatch_invocation(verb, to: to, with: with, saga_correlation: saga_correlation, legacy_args: facts)
+        dispatch_invocation(verb, to: to, with: with, saga_correlation: saga_correlation, flat: facts)
       end
 
-      def dispatch_invocation(verb, to:, with:, saga_correlation:, legacy_args:)
+      def dispatch_invocation(verb, to:, with:, saga_correlation:, flat:)
         domain, aggregate_name, command_name = parse(verb)
         aggregate = resolve_aggregate(domain, aggregate_name, verb)
 
@@ -222,12 +201,12 @@ module Hecks
               operation = port.operation(sub) ||
                           raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "port_no_operation",
                                                                         port: head, operation: sub))
-              invocation = Invocation.from_call(verb, to: to, with: with, legacy: legacy_args,
+              invocation = Invocation.from_call(verb, to: to, with: with, flat: flat,
                                                       receiver: :port, aggregate: aggregate) { operation }
               [nil, @port_ops.call(domain, aggregate, operation, invocation), nil, nil, :enqueue]
             else
               resolution = nil
-              invocation = Invocation.from_call(verb, to: to, with: with, legacy: legacy_args,
+              invocation = Invocation.from_call(verb, to: to, with: with, flat: flat,
                                                       receiver: :entity, entity_depth: command_name.count(".")) do
                 (resolution = EntityInterpreter::Resolution.of(aggregate, command_name)).command
               end
@@ -235,7 +214,7 @@ module Hecks
             end
           else
             command = command_of(aggregate, aggregate_name, command_name)
-            invocation = Invocation.from_call(verb, to: to, with: with, legacy: legacy_args) { command }
+            invocation = Invocation.from_call(verb, to: to, with: with, flat: flat) { command }
             @commands.call(domain, aggregate, command, invocation, saga_correlation)
           end
 
@@ -328,13 +307,13 @@ module Hecks
           # `to:`/`with:` are not keywords of this method — a key named
           # either is an ordinary fact here (BUG#131), so both go in as nil.
           resolution = nil
-          invocation = Invocation.from_call(verb, to: nil, with: nil, legacy: args, receiver: :entity) do
+          invocation = Invocation.from_call(verb, to: nil, with: nil, flat: args, receiver: :entity) do
             (resolution = EntityInterpreter::Resolution.of(aggregate, command_name)).command
           end
           @entities.call(domain, aggregate, resolution, invocation, dry_run: true)
         else
           command = command_of(aggregate, aggregate_name, command_name)
-          invocation = Invocation.from_call(verb, to: nil, with: nil, legacy: args) { command }
+          invocation = Invocation.from_call(verb, to: nil, with: nil, flat: args) { command }
           @commands.call(domain, aggregate, command, invocation, dry_run: true)
         end
 
@@ -360,7 +339,9 @@ module Hecks
       # @param to [String, Hash, nil] the receiving aggregate's identity; when nil it is read
       #   from the facts, by the operation's reference or identity attribute
       # @param with [Hash, nil] the operation's facts, keyed by argument name
-      # @param legacy_args [Hash{Symbol => Object}] deprecated loose keyword facts
+      # @param flat [Hash] the wire form `dispatch_flat` takes, for the driving adapter
+      #   holding a decoded webhook rather than written keywords; it is where the operation's
+      #   own reference attribute is read from and lifted into `to:` when `to:` is nil
       # @return [Array<Runtime::Event>] the events the operation announced: one per declared
       #   `emits` for an inbound operation, the one answering or refusing event for an
       #   outbound one
@@ -369,10 +350,7 @@ module Hecks
       #   is malformed
       # @raise [Runtime::NotFound] if the receiving aggregate record does not exist
       # @raise [Runtime::WiringError] if the aggregate's repository cannot be resolved
-      # @raise [Deprecation::Error] if loose keyword facts are given where
-      #   `Deprecation.raise_on!(:legacy_dispatch_args)` applies
-      def dispatch_port(domain, aggregate_name, port_name, operation_name, to: nil, with: nil, **legacy_args)
-        Dispatcher.deprecate_loose_facts(legacy_args)
+      def dispatch_port(domain, aggregate_name, port_name, operation_name, to: nil, with: nil, flat: {})
         aggregate = resolve_aggregate(domain, aggregate_name, "#{domain}::#{aggregate_name}.#{port_name}.#{operation_name}")
         port = aggregate.port(port_name) ||
                raise(UnknownVerb, "#{aggregate_name} has no port #{port_name.inspect}")
@@ -380,7 +358,7 @@ module Hecks
                     raise(UnknownVerb, "#{port_name} has no operation #{operation_name.inspect}")
 
         invocation = Invocation.from_call("#{domain}::#{aggregate_name}.#{port_name}.#{operation_name}",
-                                          to: to, with: with, legacy: legacy_args,
+                                          to: to, with: with, flat: flat,
                                           receiver: :port, aggregate: aggregate) { operation }
         announced = @port_ops.call(domain, aggregate, operation, invocation)
 

data/lib/hecks/runtime/entity_element.rb

@@ -33,6 +33,9 @@ module Hecks
       UNMATCHABLE = Object.new.freeze
       private_constant :UNMATCHABLE
 
+      # Walks `chain`, one hop per entry, and returns the located element (or
+      # `instance` itself, when `chain` is empty).
+      #
       # **One hop per chain entry**. `container` starts as `instance` (the root
       # aggregate record) and becomes each just-located element in turn —
       # Dispatch's own element is found inside the Handler element
@@ -52,6 +55,22 @@ module Hecks
       # split's own consequence: an entity's own identity may arrive via
       # `to:` rather than duplicated into `args`, so each hop is offered
       # its routed identity ahead of falling back to `args`.
+      #
+      # @param root_aggregate [Bluebook::Aggregate] the root aggregate record's
+      #   own construct, held constant across every hop for coercion
+      # @param chain [Array<Bluebook::Entity>] the entity chain to walk, root-first
+      # @param instance [Runtime::Instance] the root aggregate record to walk from
+      # @param args [Hash{String, Symbol => Object}] the offered command arguments,
+      #   read for each hop's own identity when `route` does not supply it
+      # @param command_name [String] the command name, quoted in a refusal
+      # @param route [Runtime::Routing::Envelope, nil] the call's resolved routing
+      #   envelope, if any; its own `entities` supply each hop's identity first
+      # @return [Runtime::Instance, Hash{Symbol => Object}] the located element;
+      #   `instance` itself, unchanged, when `chain` is empty
+      # @raise [Runtime::UnknownVerb] if a hop's owner declares no list attribute
+      #   for that entity
+      # @raise [Runtime::NotFound] if a hop's identity is absent from `args`, or no
+      #   element matches it
       def locate_chain(root_aggregate, chain, instance, args, command_name, route = nil)
         container = instance
         owner     = root_aggregate
@@ -81,6 +100,24 @@ module Hecks
       # rubocop:disable-next Metrics/CyclomaticComplexity
       # rubocop:disable-next Metrics/PerceivedComplexity
       # rubocop:disable-next Metrics/MethodLength
+      #
+      # @param root_aggregate [Bluebook::Aggregate] the root aggregate record's own
+      #   construct, used for value-object coercion
+      # @param owner [Bluebook::Aggregate, Bluebook::Entity] the construct whose own
+      #   attribute declares the list `entity` is searched in
+      # @param entity [Bluebook::Entity] the entity type being located
+      # @param command_name [String] the command name, quoted in a refusal
+      # @param container [Runtime::Instance, Hash{Symbol => Object}] the record or
+      #   element holding the list to search
+      # @param args [Hash{String, Symbol => Object}] the offered command arguments,
+      #   read for the element's own identity when `routed_identity` is nil
+      # @param routed_identity [String, nil] the routing envelope's own identity
+      #   string for this hop, matched directly instead of deriving one from `args`
+      # @return [Hash{Symbol => Object}] a fresh copy of the located element; the
+      #   owning list inside `container` is replaced with a fresh copy too
+      # @raise [Runtime::UnknownVerb] if `owner` declares no list attribute for `entity`
+      # @raise [Runtime::NotFound] if an identity part is absent from `args`
+      #   (`routed_identity` nil only), or no element matches
       def element_of(root_aggregate, owner, entity, command_name, container, args, routed_identity = nil)
         entity_name = entity.hecks_name
         list_attr = owner.attributes.find { |a| a.list? && a.type.to_s == entity_name } ||
@@ -173,6 +210,12 @@ module Hecks
       # that does not name its fields is refused when the bluebook loads ("an
       # entity says what it is known by", "an identity part names something"),
       # so by the time a dispatch arrives here there is always a path to dig.
+      #
+      # @param entity [Bluebook::Entity] the entity type whose identity paths
+      #   are read
+      # @param element [Hash{Symbol => Object}] the stored element to read an
+      #   identity off
+      # @return [String] the element's identity, joined from its declared parts
       def element_identity(entity, element)
         parts = entity.identity_paths.map do |path|
           head = path.to_s.split(".").first.to_sym
@@ -215,8 +258,32 @@ module Hecks
       # intentional mirroring, which is what lets the two be diffed
       # against each other when one gets a fix the other needs too.
       # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity
+      # Applies one declared mutation to an entity element, in place.
+      #
       # `pre` — the element as it was before this command (C4.2): every
       # read below goes through it, every write lands on `element`.
+      #
+      # @param rules [Runtime::CommandRules] the shared rules engine `resolve_source`/
+      #   `arithmetic`/`multiply`/`clamp`/`sign_of` are read through
+      # @param aggregate [Bluebook::Aggregate] the root aggregate, for value-object
+      #   coercion
+      # @param entity [Bluebook::Entity] the entity type `element` is an instance of
+      # @param element [Hash{Symbol => Object}] the element to mutate; written in place
+      # @param mutation [Bluebook::Mutation] the declared mutation to apply
+      # @param args [Hash{String, Symbol => Object}] the offered command arguments,
+      #   a mutation's source may read from
+      # @param pre [Hash{Symbol => Object}] the element as it stood before this
+      #   command; every read goes through this, every write lands on `element`
+      # @return [void]
+      # @raise [Runtime::TypeMismatch] if a mutation's own value cannot be coerced,
+      #   or an arithmetic op's operands are not numeric or compatible value objects
+      # @raise [Runtime::InvariantViolation] if a coerced or arithmetic-derived value
+      #   object breaks one of its own invariants
+      # @raise [Runtime::AlreadyExists] if an `:append` mints a nested entity whose
+      #   identity collides with an existing element
+      # @raise [Bluebook::Expression::EvaluationError] if an arithmetic op's product
+      #   does not fit a signed 64-bit Integer, or is a non-finite Float
+      # @raise [Runtime::WiringError] if `mutation.op` names no handled mutation kind
       def apply_to_element(rules, aggregate, entity, element, mutation, args, pre = element)
         case mutation.op
         when :set
@@ -269,22 +336,47 @@ module Hecks
         end
       end
 
+      # Rewraps a plain-Numeric arithmetic result into `attribute`'s own declared
+      # value-object type, when the arithmetic itself ran unwrapped.
+      #
       # `MutationApplier#rewrap_arithmetic_result`'s own entity-scoped
       # twin, byte-for-byte the same fix — see that method's own
       # comment for the full "phantom-field asymmetric wrapping" story.
       # A no-op whenever `current` was already a Value (the arithmetic
       # call already returned one) or the mutation targets no declared
       # attribute at all.
+      #
+      # @param aggregate [Bluebook::Aggregate] the root aggregate, for value-object
+      #   coercion
+      # @param attribute [Bluebook::Attribute, nil] the mutated field's own declared
+      #   attribute; a no-op when nil (targets no declared attribute)
+      # @param current [Object] the field's pre-mutation value, as read off `pre`
+      # @param result [Object] the arithmetic op's own result
+      # @return [Runtime::Value, Object] `result` unchanged when already a `Value`,
+      #   `current` is a `Value`, or `attribute` is nil; otherwise `result` coerced
+      #   into `attribute`'s own declared type
       def rewrap_arithmetic_result(aggregate, attribute, current, result)
         return result if current.is_a?(Value) || attribute.nil? || result.is_a?(Value)
 
         Value.for_attribute(aggregate, attribute, result)
       end
 
+      # Resolves an `:append` mutation's own field source against the offered
+      # arguments, falling back to the element's own current field.
+      #
       # `MutationApplier#resolve_append_source`'s own entity-scoped
       # twin — a caller-supplied arg first, falling back to the
       # element's own current field (never the parent instance's) when
       # it isn't one.
+      #
+      # @param source [Symbol, Object] the mutation's own field source: a Symbol
+      #   names a command argument or, failing that, an element field; anything
+      #   else is returned as is
+      # @param element [Hash{Symbol => Object}] the element to fall back to reading
+      #   from
+      # @param args [Hash{String, Symbol => Object}] the offered command arguments
+      # @return [Object, nil] the named argument's value; failing that, the named
+      #   element field's value; `source` itself when it is not a Symbol
       def resolve_element_append_source(source, element, args)
         return source unless source.is_a?(Symbol)
         return args[source] if args.key?(source)
@@ -314,6 +406,20 @@ module Hecks
       # every declared attribute the append mapping doesn't name gets its
       # own default the same way a fresh aggregate's own attributes
       # already do (`Instance.defaults`), whichever branch built `fields`.
+      #
+      # @param aggregate [Bluebook::Aggregate] the root aggregate, for value-object
+      #   coercion
+      # @param entity [Bluebook::Entity] the entity type `element`'s mutated list
+      #   attribute belongs to
+      # @param element [Hash{Symbol => Object}] the element being appended to, read
+      #   as the source for a field the mutation's own map does not supply directly
+      # @param mutation [Bluebook::Mutation] the declared `:append` mutation
+      # @param args [Hash{String, Symbol => Object}] the offered command arguments
+      # @return [Array] `element[mutation.target]`'s existing elements, frozen deep,
+      #   with the newly built element (a `Runtime::Value`, or a Hash for an entity
+      #   or untyped element) appended last
+      # @raise [Runtime::AlreadyExists] if the appended element is a nested entity
+      #   whose identity collides with an existing one
       def appended_to_element(aggregate, entity, element, mutation, args)
         fields       = mutation.source.transform_values { |source| resolve_element_append_source(source, element, args) }
         element_type = entity.attribute(mutation.target)&.type
@@ -389,6 +495,15 @@ module Hecks
       # what "the default" means. Additive only — a key `fields` already
       # holds (the append mapping, an auto-minted identity, a lifecycle
       # default) is never overwritten.
+      #
+      # @param aggregate [Bluebook::Aggregate] the root aggregate, for value-object
+      #   coercion
+      # @param entity [Bluebook::Entity] the entity type whose declared attributes
+      #   are defaulted
+      # @param fields [Hash{Symbol => Object}] the element fields already resolved;
+      #   written in place
+      # @return [Hash{Symbol => Object}] `fields`, with every declared attribute it
+      #   did not already hold filled with its own default
       def fill_declared_defaults(aggregate, entity, fields)
         entity.attributes.each do |attribute|
           next if fields.key?(attribute.name)
@@ -404,6 +519,18 @@ module Hecks
       # the list this targets is itself entity-typed — see
       # `list_element_match?`, below, which both this and
       # `MutationApplier#removed` now share.
+      #
+      # @param rules [Runtime::CommandRules] the shared rules engine `resolve_source`
+      #   is read through
+      # @param aggregate [Bluebook::Aggregate] the root aggregate, for value-object
+      #   coercion
+      # @param entity [Bluebook::Entity] the entity type `element`'s mutated list
+      #   attribute belongs to
+      # @param element [Hash{Symbol => Object}] the element being removed from
+      # @param mutation [Bluebook::Mutation] the declared `:remove` mutation
+      # @param args [Hash{String, Symbol => Object}] the offered command arguments
+      # @return [Array] `element[mutation.target]`'s existing elements, with any
+      #   matching the resolved remove target left out
       def removed_from_element(rules, aggregate, entity, element, mutation, args)
         value     = rules.resolve_source(mutation.source, args)
         attribute = entity.attribute(mutation.target)
@@ -443,6 +570,17 @@ module Hecks
       # "matches" means — the same reasoning this file's own header
       # gives for centralizing `locate_chain`/`element_of` once rather
       # than twice.
+      #
+      # @param aggregate [Bluebook::Aggregate] the root aggregate, to resolve
+      #   whether `attribute`'s own type is an entity
+      # @param attribute [Bluebook::Attribute, nil] the list attribute `element`
+      #   belongs to
+      # @param element [Object] the stored list element to check: a Hash for an
+      #   entity-typed list, a `Runtime::Value` otherwise
+      # @param value [Object] the `remove:` target to match `element` against
+      # @return [Boolean] whole-value equality for a non-entity-typed list;
+      #   identity-field equality for an entity-typed one with a single identity
+      #   head; false for a composite or absent identity
       def list_element_match?(aggregate, attribute, element, value)
         entity = attribute&.list? ? Value.find_entity(aggregate, attribute.type.to_s) : nil
         return element == value unless entity
@@ -453,24 +591,27 @@ module Hecks
         element.is_a?(Hash) && element[head] == value
       end
 
-      # BUG#13 (PR #549) — the same check #hydrate gives every creating
+      # Refuses a caller-supplied or composite identity that already names an
+      # element on `current`.
+      #
+      # BUG#13 — the same check #hydrate gives every creating
       # aggregate command (`repository.find(id)`,
-      # `command_interpreter.rb`), one level down. Originally lived in
-      # `MutationApplier` (mutation_applier.rb), called only from
+      # `command_interpreter.rb`), one level down. Shared with
+      # `MutationApplier` (mutation_applier.rb), called from
       # `#entity_element` — an aggregate's own entity list (`Workspace.
-      # boards`, `Ledger.entries`). Moved here (BUG#145) so `#appended_
+      # boards`, `Ledger.entries`) — and, moved here (BUG#145), from `#appended_
       # to_element`, above — an entity's own nested entity list one hop
-      # further in (`Board.cards`) — can share it too, rather than
-      # reimplementing it a second time the same way `#list_element_
+      # further in (`Board.cards`) — so neither call site reimplements
+      # it a second time, the same way `#list_element_
       # match?` already avoids that split for `remove:`.
       #
       # Reached, at the aggregate-owned call site, only on the two
       # branches that do not auto-mint: a caller-supplied identity (the
       # field is already in the append's own field map) or a composite
       # one (`entity.identified_by` is nil for those — Runtime::
-      # Identified#derive_identity). Neither used to check the sibling
+      # Identified#derive_identity). Without this, neither checks the sibling
       # list at all: a second LogVisit with the same date+sequence, or a
-      # second IssueKey with the same serial, appended a silent
+      # second IssueKey with the same serial, would append a silent
       # duplicate — worse than an ordinary duplicate row, because
       # `EntityElement#element_of`'s own `find_index` always matches the
       # first match, so the second becomes permanently unaddressable by
@@ -491,6 +632,18 @@ module Hecks
       # hops up). Used for that naming purpose only (`owner.hecks_name`) —
       # never for `Value`/namespace resolution, which is why an `Entity`
       # (not just an `Aggregate`) is a valid thing to pass here.
+      #
+      # @param owner [Bluebook::Aggregate, Bluebook::Entity] the construct named
+      #   in a refusal as what the duplicate "already exists on"
+      # @param entity [Bluebook::Entity] the entity type being checked for a
+      #   colliding identity
+      # @param current [Array<Hash>, Object] the entity's own existing elements;
+      #   coerced through `Array()`, so a single element or nil is also accepted
+      # @param fields [Hash{Symbol => Object}] the new element's own fields, whose
+      #   identity heads are checked against every element in `current`
+      # @return [void]
+      # @raise [Runtime::AlreadyExists] if `current` already holds an element
+      #   whose identity heads match `fields`'s own
       def check_entity_collision(owner, entity, current, fields)
         heads = entity.identity_heads
         return if heads.empty?

data/lib/hecks/runtime/entity_interpreter.rb

@@ -24,8 +24,8 @@ module Hecks
     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
+      # 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
@@ -83,7 +83,19 @@ module Hecks
       # 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?
@@ -119,6 +131,9 @@ module Hecks
         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
@@ -136,6 +151,26 @@ module Hecks
       # `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
@@ -239,7 +274,7 @@ module Hecks
       # 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** —
+      # 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
@@ -399,12 +434,12 @@ module Hecks
       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,6 +2,10 @@ 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
@@ -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
@@ -119,10 +133,10 @@ module Hecks
     #
     # 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
     # (`across "Notifications"`) fires in deployments where that domain is not

data/lib/hecks/runtime/event.rb

@@ -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
+      # 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
       # each event that stops changing once it exists.
+      #
+      # @return [void]
       def emit!
         Freezer.deep(payload)
         Freezer.deep(correlation)