hecks 1.4.0 → 1.5.1

data/lib/hecks/runtime/outbox.rb

@@ -13,7 +13,9 @@ module Hecks
     # outbound port operation) the external effects those reactions
     # cause. `future-features.md` item 8, built.
     #
-    # **The shape**. One row per (event, consumer). A consumer is a named
+    # ## The shape
+    #
+    # One row per (event, consumer). A consumer is a named
     # policy or process manager that would react to the event — resolved
     # at enqueue time from the registry (`Fanout`), so the outbox records
     # who was owed what, not just that an event happened. Rows move
@@ -33,18 +35,22 @@ module Hecks
     #              tracks delivery, not the domain's answer.
     #   failed     the consumer raised a defect (non-refusal error).
     #
-    # **Delivery is inline by default** — the dispatcher drains the rows it
+    # ## Delivery is inline by default
+    #
+    # The dispatcher drains the rows it
     # just wrote, in the same call, in the order C10.2 fixes (per event
     # in `emits` order: that event's policy rows, then its saga rows —
     # the emitting domain's own policies before other domains'). Nothing about the
     # happy path is deferred or asynchronous; a caller still sees every
     # reaction settled when `dispatch` returns. What changes is the
-    # crash window: a process that dies between commit and reaction
-    # used to lose the reaction silently. Now the row survives, and
-    # `Relay#redrive!` — run at boot by `Loader.run_boot_gates!` —
+    # crash window: without a durable row, a process that dies between
+    # commit and reaction loses the reaction silently. The row survives,
+    # and `Relay#redrive!` — run at boot by `Loader.run_boot_gates!` —
     # finds it.
     #
-    # **What redrive does, and deliberately doesn't**. A `pending` row is
+    # ## What redrive does, and deliberately doesn't
+    #
+    # A `pending` row is
     # redriven: its consumer provably never started (claiming is the
     # first thing delivery does), so running it now is exactly-once by
     # construction. A `claimed` row is not auto-redriven: the consumer
@@ -57,7 +63,9 @@ module Hecks
     # unique per store, so a re-enqueue of the same fact to the same
     # consumer is a no-op rather than a second row.
     #
-    # **Which adapters**. Memory (in-process rows — visible to specs,
+    # ## Which adapters
+    #
+    # Memory (in-process rows — visible to specs,
     # gone with the process, exactly like everything else Memory holds),
     # Sqlite and Postgres (a `hecks_outbox` table in the aggregate's own
     # database — the only way the enqueue can share the save's
@@ -71,13 +79,30 @@ module Hecks
 
       Row = Struct.new(:id, :delivery_id, :event_uid, :aggregate, :domain, :kind, :consumer, :event,
                        :status, :attempts, :error, keyword_init: true) do
+        # Reports whether this row is still waiting to be claimed.
+        #
+        # @return [Boolean] true if this row's status is `"pending"`
         def pending?   = status == "pending"
+
+        # Reports whether this row's consumer is currently running.
+        #
+        # @return [Boolean] true if this row's status is `"claimed"`
         def claimed?   = status == "claimed"
+
+        # Reports whether this row's consumer ran to completion.
+        #
+        # @return [Boolean] true if this row's status is `"delivered"`
         def delivered? = status == "delivered"
+
+        # Reports whether this row's consumer raised a defect.
+        #
+        # @return [Boolean] true if this row's status is `"failed"`
         def failed?    = status == "failed"
 
         # Wire-shaped — what an adapter persists. `event` is the event's
         # own `to_h` plus correlation; `Row.event_from` reverses it.
+        #
+        # @return [Hash{Symbol => Object}] this row's own fields, keyed by name
         def to_h
           { id: id, delivery_id: delivery_id, event_uid: event_uid, aggregate: aggregate, domain: domain,
             kind: kind, consumer: consumer, event: event, status: status, attempts: attempts, error: error }
@@ -89,6 +114,12 @@ module Hecks
 
       module_function
 
+      # Renders an event as the wire-shaped Hash an outbox row's own `event`
+      # field stores.
+      #
+      # @param event [Runtime::Event] the event to serialize
+      # @return [Hash{Symbol => Object}] `event`'s own `to_h`, with `correlation`
+      #   merged in
       def serialize_event(event)
         event.to_h.merge(correlation: event.correlation)
       end
@@ -96,11 +127,21 @@ module Hecks
       # The emitting domain's own bluebook first, then the rest in load
       # order (C10.2) — the one policy ordering both `PolicyInterpreter#
       # policies_for` and `Fanout.policies` read.
+      #
+      # @param registry [Runtime::Registry] the booted registry whose loaded
+      #   bluebooks are ordered
+      # @param domain [String, Symbol] the emitting domain, sorted first
+      # @return [Array<Bluebook::Chapter>] every loaded chapter, `domain`'s own first
       def bluebooks_home_first(registry, domain)
         home, others = registry.bluebooks.each_value.partition { |bluebook| bluebook.name == domain }
         home + others
       end
 
+      # Rebuilds a frozen event from an outbox row's own stored `event` field.
+      #
+      # @param hash [Hash{String, Symbol => Object}] the wire-shaped event Hash,
+      #   as `serialize_event` built it (String or Symbol keys either way)
+      # @return [Runtime::Event] the rebuilt, frozen event
       def event_from(hash)
         hash = hash.transform_keys(&:to_sym)
         Event.new(
@@ -113,6 +154,12 @@ module Hecks
         ).emit!
       end
 
+      # Recursively symbolizes every Hash key reachable from `value`.
+      #
+      # @param value [Object] the value to symbolize; typically a Hash or Array,
+      #   possibly nested
+      # @return [Object] `value` with every Hash key (at any depth) turned into a
+      #   Symbol; a non-Hash, non-Array value passes through unchanged
       def deep_symbolize(value)
         case value
         when Hash  then value.to_h { |k, v| [k.to_sym, deep_symbolize(v)] }
@@ -137,6 +184,12 @@ module Hecks
         # this consumer".
         # Row order is delivery order (C10.2): per event, in `emits`
         # order — that event's policy rows, then its saga rows.
+        #
+        # @param registry [Runtime::Registry] the booted registry every candidate
+        #   consumer is resolved against
+        # @param events [Array<Runtime::Event>] the just-emitted events to build rows for
+        # @param domain [String, Symbol] the emitting domain
+        # @return [Array<Runtime::Outbox::Row>] one pending row per (event, consumer)
         def rows_for(registry, events, domain)
           uids = events.to_h { |event| [event, SecureRandom.uuid] }
           events.flat_map do |event|
@@ -144,6 +197,16 @@ module Hecks
           end
         end
 
+        # Builds one pending row per policy `event` triggers.
+        #
+        # @param registry [Runtime::Registry] the booted registry policies are
+        #   resolved against
+        # @param event [Runtime::Event] the just-emitted event
+        # @param domain [String, Symbol] the emitting domain
+        # @param uid [String] this event's own enqueue-time UID, shared by every row
+        #   built for it
+        # @return [Array<Runtime::Outbox::Row>] one pending row per matching policy,
+        #   emitting domain's own bluebook first
         def policies(registry, event, domain, uid)
           emitting = Naming.demodulise(event.aggregate)
           Outbox.bluebooks_home_first(registry, domain).flat_map do |bluebook|
@@ -159,6 +222,18 @@ module Hecks
           end
         end
 
+        # Builds one pending row per process manager `event` advances, in `domain`
+        # only (a saga never reacts across domains).
+        #
+        # @param registry [Runtime::Registry] the booted registry process managers
+        #   are resolved against
+        # @param event [Runtime::Event] the just-emitted event
+        # @param domain [String, Symbol] the domain whose declared process managers
+        #   are checked
+        # @param uid [String] this event's own enqueue-time UID, shared by every row
+        #   built for it
+        # @return [Array<Runtime::Outbox::Row>] one pending row per process manager
+        #   `event` starts, ends, or advances
         def sagas(registry, event, domain, uid)
           bluebook = registry.bluebook(domain)
           return [] unless bluebook
@@ -170,6 +245,13 @@ module Hecks
           end
         end
 
+        # Reports whether `event` starts, ends, or advances `process_manager`.
+        #
+        # @param process_manager [Bluebook::ProcessManager] the declared process
+        #   manager to check
+        # @param event [Runtime::Event] the just-emitted event
+        # @return [Boolean] true if `event` names `process_manager`'s own
+        #   `starts_on`, `ends_on`, or a declared handler
         def listens?(process_manager, event)
           process_manager.starts_on == event.name || process_manager.ends_on == event.name ||
             !process_manager.handler_for(event.name).nil?
@@ -179,6 +261,14 @@ module Hecks
         # operation — the row is the durable record that an external
         # call was owed, claimed right before the adapter is asked and
         # settled right after. Everything else is a plain "reaction".
+        #
+        # @param registry [Runtime::Registry] the booted registry the trigger's own
+        #   aggregate/port are resolved against
+        # @param policy [Bluebook::Policy] the policy whose trigger is classified
+        # @param home_domain [String, Symbol] the domain `policy` is declared in,
+        #   used when `policy` declares no `target_domain`
+        # @return [String] `"effect"` when the trigger resolves to an outbound port
+        #   operation, `"reaction"` otherwise
         def kind_for(registry, policy, home_domain)
           target = "#{policy.target_domain || home_domain}::#{policy.trigger_command}"
           parsed = Naming.split_verb(target)
@@ -204,11 +294,16 @@ module Hecks
         # by the Rust kernel (`spec/rust_conformance_spec.rb`); this is
         # an additive, Ruby-only log, the same rule `saga_dispatch_log`
         # and `policy_dispatch_log` already follow.
+        #
+        # @param registry [Runtime::Registry] the booted registry this relay drains
+        #   rows for
         def initialize(registry)
           @registry = registry
           @log      = []
         end
 
+        # Attaches the interpreters a delivered row's own consumer runs through.
+        #
         # A Dispatcher hands over the interpreters a consumer runs
         # through (`Dispatcher#initialize`). Until then this relay can
         # enqueue (that needs only the registry) but not deliver — and
@@ -216,20 +311,38 @@ module Hecks
         # to. The registry holds one relay for its lifetime; a second
         # dispatcher fronting the same registry re-attaches, which is
         # fine because both dispatchers share every log and store.
+        #
+        # @param policies [Runtime::PolicyInterpreter] the interpreter a `"policy:"`
+        #   consumer reacts through
+        # @param sagas [Runtime::SagaInterpreter] the interpreter a `"saga:"` consumer
+        #   advances through
+        # @return [Runtime::Outbox::Relay] self
         def attach(policies:, sagas:)
           @policies = policies
           @sagas    = sagas
           self
         end
 
+        # Reports whether a dispatcher has attached its interpreters.
+        #
+        # @return [Boolean] true once `attach` has run
         def attached? = !@policies.nil?
 
+        # Writes one pending row per (event, consumer) `events` owes a reaction to.
+        #
         # Called inside the save transaction by `Interpreting` for the
         # command/entity paths, and outside one by `Dispatcher` for port
         # operations (which save nothing, so there is no transaction to
         # share). Returns the rows as stored (ids assigned), or nil when
         # the repository has no outbox — the dispatcher then reacts
         # directly, exactly as before.
+        #
+        # @param repository [Persistence::AppendOnly] the repository whose store the
+        #   rows are enqueued into; a no-op unless it has an outbox
+        # @param events [Array<Runtime::Event>] the events this dispatch just emitted
+        # @param domain [String, Symbol] the emitting domain
+        # @return [Array<Runtime::Outbox::Row>, nil] the stored rows, `id` assigned;
+        #   `nil` when `repository` has no outbox; `[]` when `events` is empty
         def enqueue(repository, events, domain)
           return nil unless repository.outbox?
           return [] if events.empty?
@@ -241,6 +354,15 @@ module Hecks
 
         # Drain the rows a dispatch just committed. `rows` nil means "no
         # outbox here" — react directly, the pre-outbox path.
+        #
+        # @param rows [Array<Runtime::Outbox::Row>, nil] the just-enqueued rows to
+        #   deliver; nil to react directly instead (no outbox on this repository)
+        # @param events [Array<Runtime::Event>] the events this dispatch just emitted,
+        #   read when `rows` is nil
+        # @param domain [String, Symbol] the emitting domain
+        # @param repository [Persistence::AppendOnly] the repository `rows` were
+        #   enqueued into
+        # @return [void]
         def deliver(rows, events, domain, repository)
           if rows.nil?
             # Per event, in `emits` order — its policies, then its sagas
@@ -258,6 +380,11 @@ module Hecks
 
         # One row: claim, run its consumer, settle. A claim that fails
         # means another relay (or this one, re-entrantly) already has it.
+        #
+        # @param row [Runtime::Outbox::Row] the row to claim and deliver
+        # @param repository [Persistence::AppendOnly] the repository `row` is stored in
+        # @return [Boolean] true when this call claimed and delivered `row`; false
+        #   when the claim failed, or the consumer raised a defect (recorded on `log`)
         def deliver_row(row, repository)
           return false unless repository.outbox_claim(row.id)
 
@@ -283,13 +410,24 @@ module Hecks
         end
 
         # Every row in every bound store, newest last. `status:` narrows.
+        #
+        # @param status [String, Symbol, nil] keep only rows with this status; nil
+        #   for every row
+        # @return [Array<Runtime::Outbox::Row>] copies of the matching rows, across
+        #   every store with an outbox
         def rows(status: nil)
           stores.flat_map { |repository| repository.outbox_rows(status: status) }
         end
 
+        # Runs the boot-time reconciliation over every bound store.
+        #
         # **Boot-time reconciliation**. Redrives `pending` rows (never
         # claimed — safe by construction); surfaces `claimed` rows and
         # redrives them only when told to (`claimed: true`).
+        #
+        # @param claimed [Boolean] whether to also redrive `claimed` rows (an
+        #   explicit operator decision); false leaves them surfaced and untouched
+        # @return [Array<Runtime::Outbox::Row>] every row this call actually delivered
         def redrive!(claimed: false)
           redriven = []
           stores.each do |repository|

data/lib/hecks/runtime/policy_interpreter.rb

@@ -16,11 +16,18 @@ module Hecks
     class PolicyInterpreter
       attr_reader :registry
 
+      # @param registry [Runtime::Registry] the booted registry whose loaded
+      #   bluebooks are scanned for candidate policies
+      # @param door [Runtime::Dispatcher] the dispatcher reactions re-enter through,
+      #   and whose reaction-depth guard is checked before each delivery
       def initialize(registry, door:)
         @registry = registry
         @door     = door
       end
 
+      # Fires every declared policy `event` triggers, recording each outcome on
+      # the registry's reaction log.
+      #
       # `deliver` returns `nil` for a policy whose `where` did not hold —
       # silently, the same as a policy `policies_for` never selected at all
       # (an `event_qualifier` miss carries no reaction_log entry either) —
@@ -32,6 +39,13 @@ module Hecks
       # way of running exactly the consumer a row names (`Runtime::
       # Outbox::Relay#run_consumer`) instead of every policy that
       # matches the event. Selection is otherwise identical.
+      #
+      # @param event [Runtime::Event] the just-emitted event to react to
+      # @param domain [String, Symbol] the domain `event`'s own aggregate belongs
+      #   to, the emitting domain's policies fire first
+      # @param only [Array(Bluebook::Policy, String), nil] one `[policy, home_domain]`
+      #   pair to run exactly, instead of scanning every loaded bluebook for candidates
+      # @return [void]
       def react(event, domain, only: nil)
         selected = only ? [only] : policies_for(event, domain)
         selected.each do |policy, home_domain|
@@ -195,14 +209,13 @@ module Hecks
       # The event's own identity is a fact too, not only its payload. A
       # for_each query commonly filters by the emitting record's own
       # identity (`OpenForCustomer`'s own `reference:`, scoping by the
-      # very customer who was just suspended) — which used to arrive for
-      # free because legacy dispatch left the self-addressing key riding
-      # along in `event.payload` unfiltered. Routing separated from
-      # payload (`to:`/`with:`, what the facade's own bang-methods always
-      # use) correctly stopped carrying it there, which left this query
-      # silently seeing neither the field it needs nor any error saying
-      # why — an empty result read as "nothing to freeze" instead of "the
-      # customer" the whole reaction exists to catch.
+      # very customer who was just suspended) — a fact routing keeps
+      # separate from payload (`to:`/`with:`, what the facade's own
+      # bang-methods always use), so `event.payload` alone does not carry
+      # it. Without this, the query would silently see neither the field
+      # it needs nor any error saying why — an empty result read as
+      # "nothing to freeze" instead of "the customer" the whole reaction
+      # exists to catch.
       #
       # Merged in only when the query declares an argument by that exact
       # name and the emitting aggregate's own identity is genuinely what
@@ -261,7 +274,7 @@ module Hecks
           label:     "#{policy.name}'s trigger"
         )
 
-        # **The raw inputs `args` was resolved from** — same additive,
+        # The raw inputs `args` was resolved from — same additive,
         # Ruby-only shape SagaInterpreter#deliver_saga_dispatch's own
         # saga_dispatch_log gets, for Properties.dispatch_binding_
         # fidelity's own independent re-derivation of Policy#with_spec's

data/lib/hecks/runtime/port_operation_interpreter.rb

@@ -25,6 +25,10 @@ module Hecks
         refuse_unknown_arguments refuse_absent_arguments normalize_args resolve_references resolve_route emit
       ].freeze
 
+      # @param registry [Runtime::Registry] the booted registry this interpreter dispatches
+      #   against
+      # @param rules [Runtime::CommandRules] the shared command-rule checks (references) this
+      #   interpreter's steps call
       def initialize(registry, rules:)
         @registry = registry
         @rules    = rules
@@ -32,6 +36,22 @@ module Hecks
 
       # `invocation` — the `Runtime::Invocation` `Dispatcher` built;
       # `ctx.args` is its `to_args`, `ctx.route` its `target`.
+      #
+      # @param domain [String] the domain the aggregate belongs to
+      # @param aggregate [Bluebook::Aggregate] the aggregate the port operation belongs to
+      # @param operation [Bluebook::PortOperation] the port operation to dispatch
+      # @param invocation [Runtime::Invocation] the invocation `Dispatcher` built for this call
+      # @return [Array<Runtime::Event>] the events recorded: the operation's own `emits` for
+      #   an inbound operation, or a single `answers`/`refuses` event for an outbound one
+      #   (an adapter failure is recorded as a `refuses` event, not raised)
+      # @raise [Runtime::UnknownArgument] if `invocation` offers an argument the operation
+      #   does not declare
+      # @raise [Runtime::AbsentArgument] if `invocation` omits a non-optional declared
+      #   argument
+      # @raise [Runtime::TypeMismatch] if an offered argument does not coerce to its declared
+      #   type
+      # @raise [Runtime::NotFound] if an offered reference or the operation's own receiving
+      #   record cannot be found
       def call(domain, aggregate, operation, invocation)
         ctx = Context.new(domain, aggregate, operation, invocation.to_args)
         ctx.invocation = invocation

data/lib/hecks/runtime/query_interpreter.rb

@@ -22,10 +22,26 @@ module Hecks
     class QueryInterpreter
       attr_reader :registry
 
+      # @param registry [Runtime::Registry] the booted registry queries are answered
+      #   against
       def initialize(registry)
         @registry = registry
       end
 
+      # Answers one declared aggregate or entity query, preferring a native adapter
+      # hook and falling back to interpreting the query over every loaded record.
+      #
+      # @param domain [String, Symbol] the domain `aggregate` belongs to
+      # @param aggregate [Bluebook::Aggregate] the aggregate the query is declared on
+      # @param query_name [String] the query's declared name, or an entity query's
+      #   dotted `"Entity.Query"` name
+      # @param args [Hash{Symbol => Object}] the query's declared arguments
+      # @return [Array<Hash>] one frozen Hash per matching record, its state with
+      #   `:id` merged in last
+      # @raise [Runtime::UnknownVerb] if `query_name` names no declared query
+      # @raise [Runtime::TypeMismatch] if an argument cannot be coerced to its
+      #   declared type
+      # @raise [Runtime::WiringError] if the aggregate's repository cannot be resolved
       def call(domain, aggregate, query_name, args)
         return entity_rows(domain, aggregate, query_name, args) if query_name.include?(".")
 
@@ -55,7 +71,7 @@ module Hecks
           # Instance#to_h's own comment: an aggregate free to declare its
           # own attribute literally named `id` has that attribute's own
           # wrapped value sitting in `record.state[:id]` already; merging
-          # it over a `{id:}.merge(state)` used to let it silently
+          # it over a `{id:}.merge(state)` would let it silently
           # clobber the correct bare identity this row is supposed to
           # carry.
           # A query row is an answer, not a handle. Mutating one edits
@@ -81,6 +97,18 @@ module Hecks
       # adapters, but the fold itself — the empty candidate set, a
       # duplicate id, a dangling reference, a chain's inside-out
       # resolution order — would only ever be compared against itself.
+      #
+      # @param domain [String, Symbol] the domain `aggregate` belongs to
+      # @param aggregate [Bluebook::Aggregate] the aggregate the query is declared on
+      # @param query_name [String] the query's declared name, or an entity query's
+      #   dotted `"Entity.Query"` name
+      # @param args [Hash{Symbol => Object}] the query's declared arguments
+      # @return [Array<Hash>] one Hash per matching record, its state with `:id`
+      #   merged in last
+      # @raise [Runtime::UnknownVerb] if `query_name` names no declared query
+      # @raise [Runtime::TypeMismatch] if an argument cannot be coerced to its
+      #   declared type
+      # @raise [Runtime::WiringError] if the aggregate's repository cannot be resolved
       def reference_call(domain, aggregate, query_name, args)
         return entity_rows(domain, aggregate, query_name, args) if query_name.include?(".")
 
@@ -104,9 +132,9 @@ module Hecks
         ordered = ordered(matched, declared.order_by, declared.null_semantics)
         # **Offset first, then limit** — the order SQL means by `LIMIT n
         # OFFSET m`, and the order Ports::Query::InMemory#execute already
-        # applies (see that file's own comment). This interpreter used to
-        # never read declared.offset at all — offset silently vanished for
-        # any query answered here, not just come out reversed.
+        # applies (see that file's own comment). Without reading
+        # `declared.offset`, offset would silently vanish for any query
+        # answered here, not just come out reversed.
         skipped = declared.offset ? ordered.drop(resolve_query_value(declared.offset.value, args).to_i) : ordered
         capped  = declared.limit ? skipped.first(resolve_query_value(declared.limit.value, args).to_i) : skipped
 
@@ -249,12 +277,12 @@ module Hecks
       end
 
       # The comparator table itself lives in
-      # QuerySpecification::Common::Comparison. This method and
-      # Ports::Query::InMemory#holds? used to carry a copy each and the
-      # two drifted — `none_in_state` reached only one of them, and
-      # `comparable` disagreed about value objects with two numeric
-      # members. What stays here is how a value is reached for this
-      # path: the registry is instance state rather than an argument.
+      # QuerySpecification::Common::Comparison, shared with
+      # Ports::Query::InMemory#holds? rather than each carrying its own
+      # copy — two copies once drifted: `none_in_state` reached only one
+      # of them, and `comparable` disagreed about value objects with two
+      # numeric members. What stays here is how a value is reached for
+      # this path: the registry is instance state rather than an argument.
       def holds?(clause, held, args, record: nil, domain: nil)
         QuerySpecification::Common::Comparison.holds?(
           clause.op, comparable(held), comparable(resolve_query_value(clause.value, args)), registry: @registry
@@ -273,8 +301,8 @@ module Hecks
       # the same way a command argument's own is, so a `nil` offered for
       # a non-optional value-object-typed query attribute
       # (Governance::RoleAssignment.AssignmentsForActor's `actor_id`, say)
-      # has to refuse — passing it through unchecked (as this used to)
-      # let it through as a silent, unfiltered query instead, a real
+      # has to refuse — passing it through unchecked would let it through
+      # as a silent, unfiltered query instead, a real
       # Ruby/Rust divergence the fuzzer caught (QualityControl BUG#2).
       #
       # `checked_vo?` true is handled by `null_vo_argument!` directly,

data/lib/hecks/runtime/reaction_invocation.rb

@@ -6,10 +6,10 @@ require_relative "value"
 module Hecks
   module Runtime
     # Turns facts selected by a policy or process manager into the same
-    # receiver/payload envelope an outside caller uses. Reaction declarations
-    # historically selected both through one `with:` map, so this is the one
-    # compatibility seam that separates receiver identities from facts after
-    # resolving the declaration and before re-entering the dispatcher.
+    # receiver/payload envelope an outside caller uses. A reaction declares
+    # both receiver identities and facts through one `with:` map, so this is
+    # the one compatibility seam that separates them after resolving the
+    # declaration and before re-entering the dispatcher.
     module ReactionInvocation
       Target = Struct.new(:aggregate, :entities, :command, keyword_init: true)
       # :facts, not :values — Struct.new already defines #values (every
@@ -19,10 +19,17 @@ module Hecks
 
       module_function
 
-      # The holding IR historically represented both an omitted projection and
-      # an explicitly empty `with: {}` as the same empty array. Builders now
-      # preserve declaration presence off-wire; reconstructed/legacy IR falls
-      # back to the old non-empty reading.
+      # Reports whether a reaction declared an explicit `with:` projection.
+      #
+      # An omitted projection and an explicitly empty `with: {}` both hold
+      # as the same empty array on the holding IR. Builders preserve
+      # declaration presence off-wire, in `@projection_declared`;
+      # reconstructed/legacy IR without that ivar falls back to reading
+      # presence off whether `with_spec` is non-empty.
+      #
+      # @param declaration [Bluebook::Policy, Bluebook::DispatchSpec] the reacting
+      #   declaration to check
+      # @return [Boolean] true if the declaration names an explicit `with:` projection
       def projection_declared?(declaration)
         if declaration.instance_variable_defined?(:@projection_declared)
           declaration.instance_variable_get(:@projection_declared)
@@ -31,11 +38,27 @@ module Hecks
         end
       end
 
+      # Resolves a declared `with:` projection against the scopes and bindings visible to it.
+      #
       # A reaction's source names resolve lexically, not globally. Policies
       # supply one event/row scope. Process managers supply current event then
       # opening-event memory, while correlation is an explicit binding ahead
       # of both. Missing names are refused here rather than materialized as nil
       # and accidentally presented as target command facts.
+      #
+      # @param with_spec [Hash{Symbol => Object}] each target fact name mapped to its source:
+      #   a Symbol naming a fact visible in `bindings` or `scopes`, or any other value taken
+      #   as a literal
+      # @param scopes [Array<Hecks::Runtime::ReactionInvocation::Scope, Array(String,
+      #   Hash)>] the named fact scopes to resolve a Symbol source against, checked in order;
+      #   a bare `[name, facts]` pair is wrapped into a `Scope`
+      # @param bindings [Hash] explicit bindings (such as a saga's correlation key), checked
+      #   before any scope
+      # @param label [String] names this resolution in an `UnknownArgument` refusal
+      # @return [Hash{Symbol => Object}] `with_spec`'s keys mapped to their resolved,
+      #   materialized values
+      # @raise [Runtime::UnknownArgument] if a Symbol source names a fact visible in no
+      #   binding and no scope
       def resolve_mapping(with_spec:, scopes:, bindings: {}, label: "reaction")
         normalized_bindings = bindings.transform_keys(&:to_sym)
         normalized_scopes = scopes.map do |scope|
@@ -86,6 +109,28 @@ module Hecks
       # piece that is self-contained; what remains is the sequencing
       # itself, which further splitting would only relocate, not remove.
       # rubocop:disable-next Metrics/MethodLength, Metrics/PerceivedComplexity
+      #
+      # @param registry [Runtime::Registry] the booted registry to resolve `verb` against
+      # @param verb [String] the fully qualified target command verb
+      # @param projected [Hash] the facts to send, already resolved (e.g. by
+      #   `resolve_mapping`) or, for a legacy reaction, the raw event/row payload
+      # @param explicit [Boolean] true when the reaction declared its own `with:` projection
+      #   (`projection_declared?`); false forwards `projected` wholesale as legacy args
+      # @param passthrough [Array<String, Symbol>] extra fact names allowed to ride along
+      #   unconsumed, beyond the receiver identity and declared command facts
+      # @param source_receiver [Hash{Symbol => Object}, nil] the triggering event's own
+      #   `{aggregate:, identity:}`, offered as a same-aggregate receiver when nothing else
+      #   supplies one; nil when there is no such event to inherit from
+      # @return [Hash{Symbol => Object}] `{to:, with:}` for an explicit projection targeting
+      #   a non-creating command (`with:` only for a creating command); otherwise `projected`
+      #   (with `to:` merged in when a receiver could be inherited)
+      # @raise [Runtime::UnknownVerb] if `verb` does not resolve to a declared command,
+      #   entity command, or port operation (only when `explicit` is true; a legacy call
+      #   resolving `verb` only to check inheritance swallows this and forwards unchanged)
+      # @raise [Runtime::TypeMismatch] if an explicit projection resolves no receiver
+      #   identity for the target aggregate or one of its entities
+      # @raise [Runtime::UnknownArgument] if an explicit projection's facts include a name
+      #   that is neither a consumed receiver identity nor a declared command fact
       def build(registry:, verb:, projected:, explicit:, passthrough: [], source_receiver: nil)
         args = projected.transform_keys(&:to_sym)
         unless explicit

data/lib/hecks/runtime/read_model_interpreter.rb

@@ -16,16 +16,32 @@ module Hecks
     # model is simple enough for one; otherwise runs the whole join
     # in-process against loaded records.
     class ReadModelInterpreter
+      # @param registry [Runtime::Registry] the booted registry whose repositories
+      #   this interpreter reads
       def initialize(registry) = @registry = registry
 
+      # Runs one declared read model and returns its projected rows.
+      #
+      # @param domain [String, Symbol] the domain the read model is declared in
+      # @param model [Bluebook::ReadModel] the read model to run
+      # @param args [Hash{Symbol => Object}] the query's declared arguments
+      # @return [Array<Hash>] a one-element Array holding a Hash of head name to
+      #   projected rows (or a single row, for a non-`:many` head)
+      # @raise [Runtime::TypeMismatch] if the reference argument is offered as a whole
+      #   object rather than a plain identity, or a `median` field is not numeric
+      # @raise [Runtime::NotFound] if the reference argument names no record
+      # @raise [KeyError] if a rooted read model is asked without its reference argument
+      # @raise [ArgumentError] if `group_by` or `median` names a field its target
+      #   aggregate does not declare
+      # @raise [Runtime::WiringError] if the aggregate's repository cannot be resolved
       def call(domain, model, args)
         project(domain, model, args)
       end
 
       private
 
-      # **Root-first, then the SQLite escape hatch, then the join loop** —
-      # each step's own comment names a real, previously-shipped bug the
+      # Root-first, then the SQLite escape hatch, then the join loop —
+      # each step's own comment names a real, already-shipped bug the
       # current order fixes (the reference/TenantScope refusal ordering
       # above, the root-first head processing below). Splitting this
       # into smaller methods would scatter that ordering across method
@@ -77,11 +93,11 @@ module Hecks
         # bluebook. `read_model_builder.rb`'s own `include` is
         # documented "Order-independent" (the `:many` flag is resolved
         # at build time, once `@reference_target` is known), but that
-        # promise was never kept here: this loop used to run heads in
-        # their literal declared order and match each "many" head
-        # against whatever was already in `projected` — empty, the
-        # very first time through, if a many-side head happened to be
-        # declared before the root. A real, live bug (not a guess):
+        # promise is not kept without this: running heads in
+        # their literal declared order and matching each "many" head
+        # against whatever was already in `projected` would leave it
+        # empty, the very first time through, if a many-side head happened
+        # to be declared before the root. A real, live bug (not a guess):
         # `include Promotion` before `include Item` on a read model
         # whose root is Item silently returned an empty array for
         # Promotion — no error, just a wrong, too-small answer — while