hecks 1.4.0 → 1.5.0

data/lib/hecks/runtime/routing.rb

@@ -10,6 +10,9 @@ module Hecks
     # naming them; the dispatcher itself builds an Invocation instead.
     module Routing
       Envelope = Struct.new(:aggregate, :entities, keyword_init: true) do
+        # @param aggregate [String, #to_s] the receiving aggregate's identity
+        # @param entities [Array<String, #to_s>, nil] the entity-hop identities after the
+        #   aggregate, in call order; empty for an aggregate-level command
         def initialize(aggregate:, entities: [])
           super(aggregate: aggregate.to_s, entities: Array(entities).map(&:to_s).freeze)
           freeze
@@ -18,12 +21,34 @@ module Hecks
 
       module_function
 
+      # Resolves a `to:` argument into a routing envelope. A thin delegator to
+      # `Invocation.route`; the dispatcher itself builds an `Invocation` instead.
+      #
+      # @param to [String, Hash, nil] a bare aggregate identity, or a Hash with
+      #   `aggregate:` and `entity:`/`entities:`; nil for no receiver
+      # @param entity_depth [Integer] the number of entity-hop identities the call expects
+      # @return [Routing::Envelope, nil] the resolved envelope, or nil when `to` is nil
+      # @raise [Runtime::TypeMismatch] if `to` is malformed or its entity count does not
+      #   match `entity_depth`
       def envelope(to, entity_depth: 0) = Invocation.route(to, entity_depth: entity_depth)
 
+      # Resolves a command's offered facts into its flat args hash. A thin
+      # delegator to `Invocation.facts_for` for any caller still naming it.
+      #
       # Loaded by invocation.rb (which requires this file), so `Invocation`
       # is always defined by the time either method runs.
-      def payload(command, with:, legacy:)
-        facts = Invocation.facts_for(command, with: with, legacy: legacy)
+      #
+      # @param command [Class] a `Bluebook::Command` subclass (or port-operation class)
+      #   responding to `hecks_name` and `attributes`
+      # @param with [Hash, nil] the command's facts, keyed by attribute name; nil when the
+      #   caller offers `flat` instead
+      # @param flat [Hash] the command's facts as a flat args hash, used when `with` is nil
+      # @return [Hash{String, Symbol => Object}] the offered facts by attribute name; an
+      #   attribute offered as nil is kept as nil
+      # @raise [Runtime::TypeMismatch] if both `with` and a non-empty `flat` are given, if
+      #   `with` is not a Hash, or if `with` names an unknown or omits a required attribute
+      def payload(command, with:, flat:)
+        facts = Invocation.facts_for(command, with: with, flat: flat)
         Invocation.new(verb: nil, target: nil, facts: facts).to_args
       end
     end

data/lib/hecks/runtime/saga_interpreter/correlation.rb

@@ -50,18 +50,16 @@ module Hecks
 
           # A self-referencing leg carries the correlation forward under its
           # own emitting record's identity — `event.id`, not a field dug back
-          # out of the payload. This used to read `event.payload[own_key]`
-          # (`own_key` the aggregate's own reference-key convention, "wire",
-          # "transfer"), which only ever held a value because legacy dispatch
-          # left the self-addressing key riding along in the payload
-          # unfiltered. Routing separated from payload (`to:`/`with:`, the
-          # facade's own `Handle#run` always uses it) closed exactly that
-          # leak — correctly, since an addressing key is not a fact the
-          # payload should carry — which left this tier reading an empty
-          # Hash for any self-referencing leg with no other declared
-          # attributes (`OnboardingCase.Clear`, `.Decline` — no `attribute`
-          # lines at all): the saga silently stopped advancing, forever, for
-          # exactly the leg this tier exists to correlate.
+          # out of the payload, because an addressing key is not a fact the
+          # payload should carry: routing is kept separate from payload
+          # (`to:`/`with:`, the facade's own `Handle#run` always uses it), so
+          # `own_key` (the aggregate's own reference-key convention, "wire",
+          # "transfer") never rides along in the payload unfiltered. Digging
+          # for it there would read an empty Hash for any self-referencing
+          # leg with no other declared attributes (`OnboardingCase.Clear`,
+          # `.Decline` — no `attribute` lines at all), silently stopping the
+          # saga from advancing, forever, for exactly the leg this tier
+          # exists to correlate.
           #
           # `event.id` says the identical thing this tier always meant —
           # "the record that just emitted this event, by its own identity" —

data/lib/hecks/runtime/saga_interpreter.rb

@@ -28,14 +28,29 @@ module Hecks
 
       attr_reader :registry
 
+      # @param registry [Runtime::Registry] the booted registry whose declared
+      #   process managers and saga persistence this interpreter runs against
+      # @param door [Runtime::Dispatcher] the dispatcher a saga leg's own dispatch
+      #   re-enters through
       def initialize(registry, door:)
         @registry = registry
         @door     = door
       end
 
+      # Runs `domain`'s declared process managers against `event`: begins,
+      # advances or ends each matching saga instance, checkpointing durably
+      # before its own dispatches run.
+      #
       # `only:` — one process manager, the outbox relay's way of running
       # exactly the consumer a row names (`Runtime::Outbox::Relay#
       # run_consumer`); nil advances every manager the domain declares.
+      #
+      # @param event [Runtime::Event] the just-emitted event to react to
+      # @param domain [String, Symbol] the domain whose declared process managers
+      #   are checked
+      # @param only [Bluebook::ProcessManager, nil] one process manager to run
+      #   exactly, instead of every manager `domain` declares
+      # @return [void]
       def advance(event, domain, only: nil)
         bluebook = @registry.bluebook(domain)
         return unless bluebook
@@ -56,12 +71,11 @@ module Hecks
       # could otherwise interleave their writes out of order, silently
       # reordering a saga's own transition history — worse for the
       # adapters with no locking of their own (Heki) than for Postgres.
-      # `deep_copy` guards against the exact shape of bug PR #175 itself
-      # already found once (over-freezing a live, still-mutated Hash) —
-      # never hand a persistence adapter the same object `advance_saga`/
-      # `unwind` go on to mutate in place; round-tripping through JSON
-      # is also what guarantees the value is safe for every adapter that
-      # itself calls `JSON.generate` on it.
+      # `deep_copy` guards against a real bug shape (over-freezing a live,
+      # still-mutated Hash) — never hand a persistence adapter the same
+      # object `advance_saga`/`unwind` go on to mutate in place;
+      # round-tripping through JSON is also what guarantees the value is
+      # safe for every adapter that itself calls `JSON.generate` on it.
       # `pending:` — see saga_pending_dispatch.rb. Injected into the
       # written copy of memory only, never into `instance[:memory]`
       # itself: every other reader of a live instance's memory
@@ -423,7 +437,7 @@ module Hecks
         # Same non-reentrancy reasoning as `advance_saga`'s own comment —
         # the mutex covers only the check-and-mutate-and-checkpoint step.
         advanced = @registry.saga_mutex.synchronize do
-          # The compensating leg is selected by (REFUSED, current state)
+          # The compensating leg is selected by (`REFUSED`, current state)
           # too — C10.3, one rule for every leg.
           handler = process_manager.handler_for(REFUSED, instance[:state])
           unless handler
@@ -507,9 +521,9 @@ module Hecks
       end
 
       # BUG#6 — unconditionally the saga's own home domain, never inferred
-      # from `command_name`'s own shape. This used to guess: a leftover
-      # `::` after `Naming.command_ref`'s own rewrite was read as "already
-      # domain-qualified" and left alone. That heuristic cannot actually
+      # from `command_name`'s own shape. Guessing from a leftover
+      # `::` after `Naming.command_ref`'s own rewrite (read as "already
+      # domain-qualified" and left alone) cannot actually
       # tell a genuinely cross-domain reference (`Banking::Account::
       # Debit` -> one `::` survives) apart from a same-domain entity
       # command reference (`Manifest::Slot::Fill` -> one `::` survives
@@ -519,11 +533,11 @@ module Hecks
       # (confirmed against `Naming.command_ref`'s own rewrite: it only
       # ever strips the last `::`, so the count of what remains is blind
       # to why it's there). Picking the cross-domain reading unconditionally
-      # left `qa/stress_domains/waybill`'s own `Packing` saga dispatching
+      # would leave `qa/stress_domains/waybill`'s own `Packing` saga dispatching
       # `Manifest::Slot::Fill` — an entity command in its own domain —
-      # unprefixed, so `Naming.split_verb` read "Manifest" as a domain
+      # unprefixed, so `Naming.split_verb` would read "Manifest" as a domain
       # name instead of this chapter's own aggregate, and the dispatch
-      # failed with `UnknownVerb`, silently recorded as an ordinary
+      # would fail with `UnknownVerb`, silently recorded as an ordinary
       # domain refusal rather than surfacing as the real bug it is.
       #
       # The fix mirrors `PolicyInterpreter#deliver`'s own mechanism,

data/lib/hecks/runtime/tenant_check.rb

@@ -10,10 +10,11 @@ module Hecks
     # Dispatcher, its own adapter instances) rather than one shared
     # process switching connections mid-dispatch.
     #
-    # That last part is the finding this module encodes. The project
-    # register (Bluebook::ProjectRegister) already resolves an address's
-    # realm to a dispatcher at registration time — Router#resolve looks
-    # the FQN up in one flat table keyed by realm::domain::aggregate.verb,
+    # ## Why no ambient "current tenant"
+    #
+    # The project register (Bluebook::ProjectRegister) already resolves an
+    # address's realm to a dispatcher at registration time — Router#resolve
+    # looks the FQN up in one flat table keyed by realm::domain::aggregate.verb,
     # and each entry already carries its own dispatcher from its own
     # boot. So "which tenant" is decided once, at boot/registration time
     # (which of possibly many boots of the same directory a request's
@@ -23,8 +24,9 @@ module Hecks
     # already gives for free — each tenant's own PostgresEra instance
     # is its own connection, held for the life of that boot.
     #
-    # So `tenant_capable?` asks a narrower question than it might sound:
-    # not "can this adapter switch tenants," but "does booting this
+    # ## What `tenant_capable?` really asks
+    #
+    # Not "can this adapter switch tenants," but "does booting this
     # adapter twice, with different settings, for the same directory,
     # actually keep the two boots' data apart." Memory answers true
     # trivially — a `@records` Hash is a plain instance variable, and
@@ -41,6 +43,9 @@ module Hecks
     module TenantCheck
       module_function
 
+      # Refuses to let `domain` boot for more than one tenant unless every
+      # aggregate's resolved persistence adapter is `tenant_capable?`.
+      #
       # A domain is safe to boot for more than one tenant only if every
       # aggregate's resolved persistence adapter is tenant_capable? — one
       # ungoverned adapter sharing state across two tenant boots is a
@@ -48,6 +53,12 @@ module Hecks
       # a second tenant boot of the same directory is trusted, the same
       # severity EraCheck/refuse_ungoverned_roles! already hold their
       # own gates to.
+      #
+      # @param registry [Runtime::Registry] the booted registry to check
+      # @param domain [String, Symbol] the domain name to check every aggregate of
+      # @return [void]
+      # @raise [Runtime::WiringError] if any aggregate in `domain` is bound to an adapter
+      #   that is not `tenant_capable?`
       def refuse_unless_tenant_capable!(registry, domain)
         bluebook = registry.bluebook(domain)
         return unless bluebook
@@ -67,12 +78,21 @@ module Hecks
               "or keep #{domain} single-tenant."
       end
 
+      # Answers whether `adapter_name`'s Ruby implementation keeps two
+      # tenants' boots of the same directory from sharing data.
+      #
       # The capability idiom itself — an adapter class that answers
       # tenant_capable? with true keeps two boots' data apart by
       # construction (Memory) or by an explicit per-boot isolation
       # setting (PostgresEra's schema:). Same defensive shape
       # EraCheck#lineage_capable? already uses: a class that doesn't
       # respond at all is false, not an error.
+      #
+      # @param registry [Runtime::Registry] the booted registry the adapter is wired into
+      # @param adapter_name [String] the adapter's declared name, such as `"PostgresEra"`
+      # @return [Boolean] true when the adapter is registered, has a Ruby implementation,
+      #   and answers `tenant_capable?` true; false for any other case, including a
+      #   missing adapter or one whose lookup raises
       def tenant_capable?(registry, adapter_name)
         adapter_class = registry.adapters[adapter_name] && registry.adapter_class(adapter_name)
         adapter_class.respond_to?(:tenant_capable?) && adapter_class.tenant_capable?

data/lib/hecks/runtime/tenant_scope.rb

@@ -29,6 +29,16 @@ module Hecks
     module TenantScope
       module_function
 
+      # Wraps a declared query/read-model spec with its tenant boundary clause, if it has one.
+      #
+      # @param declared [Bluebook::Query, Bluebook::ReadModel] the declared specification to
+      #   scope
+      # @param args [Hash] the query's arguments, checked for the declared tenant field
+      # @return [Bluebook::Query, Bluebook::ReadModel, Runtime::TenantScope::Scoped]
+      #   `declared` unchanged when it declares no `authorize policy, tenant:`; otherwise a
+      #   `Scoped` wrapper whose `#wheres` adds the tenant `eq` clause
+      # @raise [Runtime::Unauthorized] if `declared` declares a tenant boundary and `args`
+      #   omits that field
       def apply(declared, args)
         tenant = declared.authorization&.tenant
         return declared unless tenant
@@ -50,11 +60,19 @@ module Hecks
       # own internal `.wheres` read would bypass this override (see this
       # module's own header for why).
       class Scoped < SimpleDelegator
+        # @param declared [Bluebook::Query, Bluebook::ReadModel] the specification to wrap,
+        #   delegated to for everything but `#wheres`
+        # @param clause [QuerySpecification::Common::WhereClause] the synthetic tenant `eq`
+        #   clause to append
         def initialize(declared, clause)
           super(declared)
           @clause = clause
         end
 
+        # Reads the wrapped specification's where-clauses, with the tenant clause appended.
+        #
+        # @return [Array<QuerySpecification::Common::WhereClause>] `declared.wheres` with the
+        #   tenant clause appended
         def wheres = __getobj__.wheres + [@clause]
       end
     end