hecks 1.4.0 → 1.5.0

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

data/lib/hecks/runtime/rebuild_sweep.rb

@@ -32,6 +32,12 @@ module Hecks
       # `save` only runs when a projected value would differ from what
       # is already stored, so re-running a sweep with nothing having
       # moved on the target side touches the append log not at all.
+      #
+      # @param registry [Runtime::Registry] the booted registry to read repositories from
+      # @param domain [String] the domain the aggregate belongs to
+      # @param aggregate [Bluebook::Aggregate] the aggregate whose `projected_fields` to
+      #   refresh
+      # @return [Integer] the number of records actually changed and saved
       def call(registry, domain, aggregate)
         return 0 if aggregate.projected_fields.empty?
 
@@ -39,6 +45,16 @@ module Hecks
         repository.all.count { |record| refresh(registry, domain, aggregate, record, repository) }
       end
 
+      # Refreshes one record's own projected fields in place, saving it if any changed.
+      #
+      # @param registry [Runtime::Registry] the booted registry to read the target's
+      #   repository from
+      # @param domain [String] the domain the aggregate belongs to
+      # @param aggregate [Bluebook::Aggregate] the aggregate `record` is an instance of
+      # @param record [Runtime::Instance] the record to refresh, mutated in place
+      # @param repository [Ports::Persistence::AppendOnly] the repository to save `record`
+      #   through when it changes
+      # @return [Boolean] true if any projected field's value changed and `record` was saved
       def refresh(registry, domain, aggregate, record, repository)
         changed = false
 
@@ -55,10 +71,22 @@ module Hecks
         changed
       end
 
+      # Reads the current value of one projected field's remote target field.
+      #
       # `nil` when the reference itself does not resolve in this
       # chapter (a cross-domain target left "unfollowed" the same way
       # References#dereference already leaves one) or when the record
       # names no target at all — an optional reference nobody set.
+      #
+      # @param registry [Runtime::Registry] the booted registry to read the target's
+      #   repository from
+      # @param domain [String] the domain the aggregate belongs to
+      # @param aggregate [Bluebook::Aggregate] the aggregate declaring `field`
+      # @param record [Runtime::Instance] the record holding the reference to follow
+      # @param field [Bluebook::ProjectedField] the projected field to resolve
+      # @return [Object, nil] the target record's own `field.remote_field` value; nil if the
+      #   reference type does not resolve, the record names no target, or the target record
+      #   cannot be found
       def remote_value(registry, domain, aggregate, record, field)
         target = aggregate.attribute(field.reference)&.type&.resolve
         return nil unless target

data/lib/hecks/runtime/reference_hop.rb

@@ -31,6 +31,21 @@ module Hecks
     module ReferenceHop
       module_function
 
+      # Folds every hop clause in `declared.wheres` into a synthetic local `in` clause.
+      #
+      # @param declared [Bluebook::Query, Runtime::TenantScope::Scoped,
+      #   QuerySpecification::Common::Options] the declared query specification to fold hop
+      #   clauses of
+      # @param args [Hash] the query's arguments, read when resolving each hop's own query
+      # @param registry [Runtime::Registry] the booted registry to resolve each hop's target
+      #   repository from
+      # @param domain [String] the domain `aggregate` belongs to
+      # @param aggregate [Bluebook::Aggregate] the aggregate `declared` queries
+      # @return [Bluebook::Query, Runtime::TenantScope::Scoped, QuerySpecification::Common::
+      #   Options, Hecks::Runtime::ReferenceHop::Folded] `declared` unchanged when it has no
+      #   hop clauses; otherwise a `Folded` wrapper whose `#wheres` replaces each hop clause
+      #   with its folded `in` clause
+      # @raise [Runtime::WiringError] if a hop's target no longer resolves (see `fold`)
       def apply(declared, args, registry:, domain:, aggregate:)
         hopped, local = declared.wheres.partition { |clause| QuerySpecification::HopPath.hop_head?(clause.field, aggregate.attributes) }
         return declared if hopped.empty?
@@ -39,6 +54,18 @@ module Hecks
         Folded.new(declared, local + folded)
       end
 
+      # Folds one hop clause into a synthetic `in` clause over the hop attribute's own ids.
+      #
+      # @param clause [QuerySpecification::Common::WhereClause] the hop clause to fold; its
+      #   `field` names the hop path, dotted past the first segment
+      # @param args [Hash] the query's arguments, read when resolving the inner query
+      # @param registry [Runtime::Registry] the booted registry to resolve the hop's target
+      #   repository from
+      # @param domain [String] the domain `aggregate` belongs to
+      # @param aggregate [Bluebook::Aggregate] the aggregate `clause` is declared against
+      # @return [QuerySpecification::Common::WhereClause] a synthetic `in` clause on the hop
+      #   attribute's name, whose value is every id the inner clause admits on the target
+      # @raise [Runtime::WiringError] if the hop's target aggregate no longer resolves
       def fold(clause, args, registry:, domain:, aggregate:)
         step = QuerySpecification::HopPath.next_hop(clause.field, aggregate.attributes)
         hop, rest = step
@@ -70,6 +97,16 @@ module Hecks
       # aggregate is actually bound to (which may not be the engine
       # the outer aggregate is bound to at all) rather than by a
       # second reading of the comparators.
+      #
+      # @param domain [String] the domain `target` belongs to
+      # @param target [Bluebook::Aggregate] the hop's target aggregate to query
+      # @param wheres [Array<QuerySpecification::Common::WhereClause>] the inner clause(s) to
+      #   run against `target`
+      # @param args [Hash] the outer query's arguments, read when resolving the inner query
+      # @param registry [Runtime::Registry] the booted registry to resolve `target`'s
+      #   repository from
+      # @return [Array<String>] every distinct id the inner clause(s) admit on `target`
+      # @raise [Runtime::WiringError] if a hop nested inside `wheres` no longer resolves
       def matching_ids(domain, target, wheres, args, registry:)
         spec       = apply(QuerySpecification::Common::Options.new(wheres: wheres), args,
                            registry: registry, domain: domain, aggregate: target)
@@ -87,6 +124,11 @@ module Hecks
       # same reason: SimpleDelegator only intercepts calls made
       # directly on the wrapper.
       class Folded < SimpleDelegator
+        # @param declared [Bluebook::Query, Runtime::TenantScope::Scoped,
+        #   QuerySpecification::Common::Options] the wrapped query specification, delegated to
+        #   for everything but `#wheres`
+        # @param wheres [Array<QuerySpecification::Common::WhereClause>] the replacement
+        #   where-clauses, hop clauses folded to synthetic `in` clauses
         def initialize(declared, wheres)
           super(declared)
           @wheres = wheres

data/lib/hecks/runtime/refusal_wording.rb

@@ -31,9 +31,18 @@ module Hecks
 
       module_function
 
+      # Renders `refusal`/`site`'s template, substituting `values` verbatim.
+      #
       # Plain text substitution, never expression syntax — a template is
       # read, not evaluated. Values arrive already formatted; prefer
       # `render_site`, which formats them off the declared rows.
+      #
+      # @param refusal [String] the `DomainRefusal` class name, such as `"UnknownArgument"`
+      # @param site [String] the template site within `refusal`, such as `"unknown_args"`
+      # @param values [Hash{Symbol => #to_s}] each `{name}` placeholder's already-formatted
+      #   replacement text
+      # @return [String] the rendered refusal message
+      # @raise [KeyError] if no `RefusalTemplate` row declares `refusal`/`site`
       def render(refusal, site, **values)
         substitute(template(refusal, site), values)
       end
@@ -46,6 +55,16 @@ module Hecks
       #   RefusalWording.render_site("UnknownArgument", "unknown_args",
       #                              command: "Close", unknown: [:parcel], declared: [])
       #   # => "Close does not declare parcel — it takes none"
+      #
+      # @param refusal [String] the `DomainRefusal` class name, such as `"UnknownArgument"`
+      # @param site [String] the template site within `refusal`, such as `"unknown_args"`
+      # @param arguments [Hash{Symbol => Object}] raw values, one per `RefusalSiteArgument`
+      #   row declared for `refusal`/`site`; formatted per row before substitution
+      # @return [String] the rendered refusal message
+      # @raise [ArgumentError] if `arguments` is missing a declared argument or offers one
+      #   `refusal`/`site` does not declare
+      # @raise [KeyError] if no `RefusalTemplate`/`RefusalSiteArgument` rows declare
+      #   `refusal`/`site`
       def render_site(refusal, site, **arguments)
         specs    = argument_rows(refusal, site)
         declared = specs.map { |spec| spec["argument"].to_sym }
@@ -62,6 +81,12 @@ module Hecks
       # `render_site` without the registry lookups: a template, its
       # argument rows, and raw values. The Rust projection calls this with
       # the chapter's own rows to compute the expected wording it pins.
+      #
+      # @param template [String] the raw template, `{name}` placeholders unsubstituted
+      # @param specs [Array<Hash>] the `RefusalSiteArgument` rows to format `arguments`
+      #   against, one per declared argument name
+      # @param arguments [Hash{Symbol => Object}] raw values, one per entry in `specs`
+      # @return [String] the rendered refusal message
       def render_with(template, specs, arguments)
         values = specs.to_h do |spec|
           name = spec["argument"].to_sym
@@ -73,6 +98,12 @@ module Hecks
       # One argument, written the way its row says. A list is sorted first
       # (before quoting), then each item quoted, then joined; an empty list
       # reads `when_empty`. A scalar is quoted or taken as its own text.
+      #
+      # @param spec [Hash] the argument's `RefusalSiteArgument` row (`"shape"`, `"quoting"`,
+      #   and, for a list, `"sorted"`, `"separator"`, `"when_empty"`)
+      # @param value [Object, Array] the raw value to format; an Array (or anything
+      #   `Array()`-coercible) for a `"list"`-shaped spec, a scalar otherwise
+      # @return [String] the formatted text
       def format_argument(spec, value)
         inspect = spec.fetch("quoting") == "inspect"
         return inspect ? value.inspect : value.to_s unless spec.fetch("shape") == "list"
@@ -83,10 +114,22 @@ module Hecks
         items.empty? ? spec.fetch("when_empty") : items.join(spec.fetch("separator"))
       end
 
+      # Replaces each `{name}` placeholder in `template` with its value's text.
+      #
+      # @param template [String] the raw template, `{name}` placeholders unsubstituted
+      # @param values [Hash{Symbol => #to_s}] each placeholder name mapped to its
+      #   replacement text
+      # @return [String] `template` with every `{name}` placeholder substituted
       def substitute(template, values)
         values.reduce(template) { |text, (key, value)| text.gsub("{#{key}}", value.to_s) }
       end
 
+      # Looks up the raw template text declared for one refusal site.
+      #
+      # @param refusal [String] the `DomainRefusal` class name, such as `"UnknownArgument"`
+      # @param site [String] the template site within `refusal`, such as `"unknown_args"`
+      # @return [String] the raw `RefusalTemplate` text, `{name}` placeholders unsubstituted
+      # @raise [KeyError] if no `RefusalTemplate` row declares `refusal`/`site`
       def template(refusal, site)
         TEMPLATES.fetch([refusal, site]) do
           raise KeyError, "no refusal template for #{refusal}/#{site} — declare it in " \
@@ -94,9 +137,16 @@ module Hecks
         end
       end
 
+      # The declared arguments for one refusal site.
+      #
       # Read lazily, not into a constant: bin/project_vocabulary boots
       # `hecks` (and so this file) before it writes the table a newly
       # declared site's rows live in.
+      #
+      # @param refusal [String] the `DomainRefusal` class name, such as `"UnknownArgument"`
+      # @param site [String] the template site within `refusal`, such as `"unknown_args"`
+      # @return [Array<Hash>] the `RefusalSiteArgument` rows declared for `refusal`/`site`
+      # @raise [KeyError] if no `RefusalSiteArgument` rows declare `refusal`/`site`
       def argument_rows(refusal, site)
         @argument_rows ||= Hecks::Vocabulary.rows("RefusalSiteArgument")
                                             .group_by { |row| [row["refusal"], row["site"]] }

data/lib/hecks/runtime/registry/saga_persistence.rb

@@ -40,6 +40,15 @@ module Hecks
         # state lands in). Double-checked locking against a dedicated mutex
         # — never `@saga_mutex` — see `Registry#initialize`'s own comment for
         # why reusing that one would deadlock.
+        # Resolves and memoizes the adapter a domain's sagas persist through.
+        #
+        # @param domain [String, Symbol] the domain to resolve saga persistence for
+        # @return [Adapters::Heki, Adapters::Postgres, Adapters::Sqlite, Adapters::D1,
+        #   Ports::Persistence::Plugins::Era::PostgresEra, Ports::Persistence::NullSagaStore]
+        #   the same adapter instance the domain's anchor aggregate persists through, when it
+        #   implements `save_saga`; `NULL_SAGA_STORE` for a domain with no anchor aggregate, an
+        #   adapter that does not implement the capability, a `RemoteRuntime`-shaped adapter,
+        #   or a `Runtime::WiringError` resolving the anchor's own bind
         def saga_persistence(domain)
           key = domain.to_s
           @saga_persistence[key] || @saga_persistence_mutex.synchronize do
@@ -67,6 +76,8 @@ module Hecks
         # points inside `@saga_mutex.synchronize` blocks (`saga_interpreter.
         # rb`), which genuinely do and are guarded accordingly.
         # rubocop:disable-next Hecks/ThreadSharedIvarMutation
+        #
+        # @return [Hecks::Runtime::Registry] self
         def rehydrate_sagas!
           @hecksagons.each_key do |domain|
             saga_persistence(domain).each_saga do |process_manager, correlation, state, memory, completed_compensations = []|