hecks 2.8.0 → 2.9.0

data/lib/hecks/runtime/remote_dispatcher.rb

@@ -9,123 +9,61 @@ require_relative "../ports/persistence/remote_runtime"
 
 module Hecks
   module Runtime
-    # **The write-side half of lambda routing** — `Runtime::Loader.boot`
-    # constructs this instead of `Dispatcher` when the booted domain's
-    # own `.world` declares Lambda routing (see loader.rb's own
-    # `dispatcher_class_for`). Matches `Dispatcher`'s public shape
-    # closely enough that everything built on top of a dispatcher —
-    # `Handle`, `AggregateDoor`, `Facade::Surface` — needs no changes
-    # at all: `Handle#run`'s entire contract is
-    # `@dispatcher.dispatch("#{fqn}.#{command}", to: @id, with: args).instance.state`,
-    # and both classes answer that identically.
+    # Dispatcher for a domain whose `.world` declares Lambda routing.
+    # Same public shape as `Dispatcher`; writes go remote, reads stay local.
     #
-    # **Reads delegate, writes don't**. `query`/`reference_query` hand off
-    # to a real `Dispatcher` built over the same registry — since that
-    # registry's own repositories are already Lambda-backed
-    # (`Adapters::Lambda`, `persisted_by("Lambda")`, Phase 2's other
-    # half), the inherited query machinery (`QueryInterpreter`,
-    # `Ports::Query::InMemory.execute`) works completely unchanged, no
-    # query logic duplicated here. `dispatch` can't delegate the same
-    # way: command validation (givens, constraints) has to actually
-    # run in Rust for a Lambda-routed domain, not get pre-checked here
-    # against incomplete local state and then merely persisted.
+    # Reads delegate to a local `Dispatcher` because the registry's repositories are
+    # already Lambda-backed. Writes cannot: givens and constraints must run in Rust,
+    # not be pre-checked here against incomplete local state.
     class RemoteDispatcher
       Result = Struct.new(:verb, :instance, :events, keyword_init: true) do
-        # Reads the identity of the record the dispatch settled on.
+        # The settled record's identity.
         #
-        # @return [String] the settled record's identity
+        # @return [String]
         def id    = instance.id
 
-        # Reads the settled record's attributes as one Hash.
+        # The settled record's attributes.
         #
-        # @return [Hash{Symbol => Object}] the settled record's attributes, `:id` merged
-        #   in last
+        # @return [Hash{Symbol => Object}] `:id` merged in last
         def state = instance.to_h
       end
 
       attr_reader :registry
 
-      # @param registry [Runtime::Registry] the booted registry this dispatcher fronts;
-      #   read-side calls (`query`/`reference_query`) delegate to a local `Dispatcher`
-      #   built over the same registry
+      # @param registry [Runtime::Registry] the booted registry this dispatcher fronts
       # @param region [String] the AWS region the routed Lambda function lives in
-      # @param function [String, nil] the `.world`'s own `dispatched_by("Lambda")`
-      #   function name, when the deployment stack is not named `hecks-<domain>`; nil
-      #   resolves the function name from `ENV["DOMAIN_NAME"]` or `registry.root`
+      # @param function [String, nil] the `dispatched_by("Lambda")` function name; nil
+      #   resolves it from `ENV["DOMAIN_NAME"]` or `registry.root`
       def initialize(registry, region: "us-east-1", function: nil)
         @registry = registry
-        # `File.basename(registry.root)`, not `bluebooks.keys.first` —
-        # matches `Adapters::Lambda`'s own function-name resolution
-        # exactly (see its own comment on why: one merged Lambda per
-        # deploy, not one per attached chapter, and `root` is the one
-        # signal every bluebook in this registry shares regardless of
-        # which one attached it) — including that same adapter's own
-        # `ENV["DOMAIN_NAME"]`-first fix: `root` is always `/var/task`
-        # inside a deployed Lambda, giving "task" instead of the real
-        # domain name (a real, live AccessDeniedException on
-        # "hecks-task" caught this).
-        # `function:` — the `.world`'s own `dispatched_by("Lambda")`
-        # naming of which function this is, for a deployment whose stack
-        # name isn't `hecks-<domain>` (Client's own comment has the real
-        # case). Absent, the resolution above is unchanged.
+        # ENV["DOMAIN_NAME"] first: inside a deployed Lambda `root` is always
+        # `/var/task`, which would resolve the function name to "task".
         @client = Adapters::Lambda::Client.new(domain: ENV["DOMAIN_NAME"] || File.basename(registry.root),
                                                region: region, function: function)
-        # Read-side delegate only (see class comment) — never dispatched
-        # through; a real Dispatcher's own `query`/`reference_query`
-        # already resolve generically via `registry.repository(...)`,
-        # so building one here reuses that instead of duplicating it.
         @local = Dispatcher.new(registry)
       end
 
-      # Dispatches a command by verb, routing to the local `Dispatcher` or the
-      # remote Lambda depending on the aggregate's bound adapter.
-      #
-      # Same shape as `Dispatcher#dispatch_flat` — everything but
-      # `saga_correlation:` is forwarded through unread, `to:`/`with:`
-      # included, and lifted out downstream by whichever path actually
-      # dispatches (`@local.dispatch_flat` locally, the flat wire form
-      # remotely). Not the strict `to:`/`with:`-only door `Dispatcher#
-      # dispatch` is — see that class's own comment for why this file
-      # never had one.
+      # Dispatches a command by verb, locally or through the routed Lambda depending
+      # on the aggregate's bound adapter.
       #
       # @param verb [String] the fully qualified verb, `"Domain::Aggregate.Command"`
-      #   or `"Domain::Aggregate.Entity.Command"`
-      # @param saga_correlation [Hash, nil] correlation head => value, stamped on every
-      #   emitted event when a saga leg causes this dispatch; nil otherwise
-      # @param args [Hash] the facts, plus optional `:to`/`:with` keys, read the same
-      #   way `dispatch_flat` reads them
+      # @param saga_correlation [Hash, nil] correlation head => value stamped on emitted events
+      # @param args [Hash] the facts, plus optional `:to`/`:with` keys
       # @return [RemoteDispatcher::Result] the verb, settled instance and emitted events
-      # @raise [Runtime::UnknownVerb] if the verb is not fully qualified, or names a
-      #   domain or aggregate that is not declared
-      # @raise [StandardError] any class in `Runtime::DOMAIN_REFUSALS` when a
-      #   locally-routed aggregate refuses the call
-      # @raise [Runtime::StaleWrite] if concurrent local writers beat this one through
-      #   every retry, for a locally-routed aggregate
-      # @raise [Runtime::WiringError] if the aggregate's adapter or repository cannot be
-      #   resolved, or the remote call is accepted but reports no mutation for it
+      # @raise [Runtime::UnknownVerb] if the verb is not fully qualified or names an
+      #   undeclared domain or aggregate
       # @raise [Runtime::RemoteRefusal] if the routed Lambda refuses the call
+      # @raise [Runtime::WiringError] if the adapter cannot be resolved, or the remote call
+      #   reports no mutation for the aggregate
       def dispatch(verb, saga_correlation: nil, **args)
         dispatch_flat(verb, args.merge(saga_correlation: saga_correlation))
       end
 
-      # Routes a dispatch to the local `Dispatcher` when the aggregate's bound
-      # adapter is not remote-backed (`Ports::Persistence::RemoteRuntime`),
-      # otherwise dispatches through the routed Lambda. Same flat-facts wire
-      # form as `Dispatcher#dispatch_flat`.
+      # Same routing as `dispatch`, with the flat-facts wire form of `Dispatcher#dispatch_flat`.
       #
-      # @param verb [String] the fully qualified verb, in any shape `dispatch` accepts
-      # @param args [Hash] the facts, plus optional Symbol keys `:to`, `:with` and
-      #   `:saga_correlation`, read as `dispatch`'s keywords of the same names; not mutated
+      # @param verb [String] the fully qualified verb
+      # @param args [Hash] the facts, plus optional Symbol keys `:to`, `:with`, `:saga_correlation`
       # @return [RemoteDispatcher::Result] the verb, settled instance and emitted events
-      # @raise [Runtime::UnknownVerb] if the verb is not fully qualified, or names a
-      #   domain or aggregate that is not declared
-      # @raise [StandardError] any class in `Runtime::DOMAIN_REFUSALS` when a
-      #   locally-routed aggregate refuses the call
-      # @raise [Runtime::StaleWrite] if concurrent local writers beat this one through
-      #   every retry, for a locally-routed aggregate
-      # @raise [Runtime::WiringError] if the aggregate's adapter or repository cannot be
-      #   resolved, or the remote call is accepted but reports no mutation for it
-      # @raise [Runtime::RemoteRefusal] if the routed Lambda refuses the call
       def dispatch_flat(verb, args = {})
         args = args.dup
         saga_correlation = args.delete(:saga_correlation)
@@ -136,21 +74,8 @@ module Hecks
                     raise(UnknownVerb,
                           RefusalWording.render_site("UnknownVerb", "no_aggregate", domain: domain, aggregate: aggregate_name))
 
-        # Not every aggregate in a lambda-routed domain is itself
-        # lambda-bound — Member's real name->email rekey carries a
-        # `compute` rule (era_check.rb's own `check_compute_rules!`),
-        # which can only ever run against Postgres, permanently. Its
-        # own `.hecksagon` bind stays "Postgres" even when
-        # `dispatched_by("Lambda")` is on for everything else — checked
-        # here by real capability (`Ports::Persistence::RemoteRuntime`,
-        # §1), not by comparing the adapter's own name to the string
-        # "Lambda" — a bind resolves to whatever adapter class actually
-        # backs it, and only a class shaped like "the real interpreter
-        # lives behind a call boundary" forwards here; anything else
-        # (Postgres, Memory, any future local adapter) falls through to
-        # the real local Dispatcher instead of being forwarded to a
-        # Lambda that has no way to represent its lineage history at
-        # all.
+        # Not every aggregate in a routed domain is Lambda-bound (a `compute` rule can
+        # only run against Postgres). Test the adapter's capability, not its name.
         adapter_name = Ports::Persistence::BindingPolicy.resolve(@registry, domain, aggregate).adapter
         unless @registry.adapter_class(adapter_name) <= Ports::Persistence::RemoteRuntime
           return @local.dispatch_flat(verb, args.merge(saga_correlation: saga_correlation))
@@ -161,15 +86,8 @@ module Hecks
         refusal = response.fetch("refusals", []).find { |r| r["verb"] == verb }
         raise RemoteRefusal, "#{verb} refused: #{refusal['error']}" if refusal
 
-        # This step's own mutations — `mutations` is one entry per
-        # replayed step (rust/host's rehydrate-and-replay design,
-        # Phase 1), so `.last` is exactly the step just dispatched.
-        # Matched by fully-qualified aggregate name, not just "the
-        # first mutation" — a command whose reaction also mutates a
-        # different aggregate (a policy, a saga leg) puts more than
-        # one mutation in the same step, and the direct effect of
-        # this verb is the one this dispatch's own caller expects
-        # `.instance` to be.
+        # `mutations` has one entry per replayed step, so `.last` is this step. Match by
+        # aggregate name: a reaction can mutate other aggregates in the same step.
         fqn = "#{domain}::#{aggregate.hecks_name}"
         mutation = response.fetch("mutations", []).last&.find { |m| m["aggregate"] == fqn } ||
                    raise(WiringError,
@@ -181,46 +99,17 @@ module Hecks
         Result.new(verb: verb, instance: instance, events: step_events(response))
       end
 
-      # Delegates to the local `Dispatcher` built over the same registry — see the
-      # class comment on why reads, unlike writes, need no remote-specific logic.
-      #
-      # @param verb [String, Symbol] the query's verb, in one of `Dispatcher#query`'s
-      #   three shapes
-      # @param args [Hash{Symbol => Object}] the query's declared arguments
-      # @return [Array<Hash>] see `Dispatcher#query`'s own return
-      # @raise [Runtime::UnknownVerb] if the verb is not fully qualified, or names a
-      #   domain, aggregate, entity, query or read model that is not declared
-      # @raise [Runtime::NotFound] if a read model's root reference names no record
-      # @raise [Runtime::TypeMismatch] if an argument cannot be coerced to its declared type
-      # @raise [KeyError] if a rooted read model is asked without its reference argument
-      # @raise [Runtime::WiringError] if the aggregate's repository cannot be resolved
+      # Delegates to the local `Dispatcher`; see `Dispatcher#query`.
       def query(verb, **args)           = @local.query(verb, **args)
 
-      # Delegates to the local `Dispatcher` built over the same registry — see the
-      # class comment on why reads, unlike writes, need no remote-specific logic.
-      #
-      # @param verb [String] the fully qualified query verb, `"Domain::Aggregate.Query"`
-      #   or `"Domain::Aggregate.Entity.Query"`
-      # @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; for an entity query, one Hash per matching element
-      # @raise [Runtime::UnknownVerb] if the verb is not fully qualified, or names a
-      #   domain, aggregate, entity or query that is not declared
-      # @raise [Runtime::TypeMismatch] if an argument cannot be coerced to its declared type
-      # @raise [Runtime::WiringError] if the aggregate's repository cannot be resolved
+      # Delegates to the local `Dispatcher`; see `Dispatcher#reference_query`.
       def reference_query(verb, **args) = @local.reference_query(verb, **args)
 
-      # Fetches the full domain's event history, on every call — `{"read":
-      # true}` replays the whole journal (Phase 1's `dispatch::read`),
-      # so its own `events` array already is the complete log, the
-      # same thing `@registry.event_log` would answer for a local
-      # dispatch. Not cached: `AggregateDoor.events`/`Handle#events`
-      # are not called in this codebase's own hot paths today: if that
-      # changes, caching belongs here, not in every caller.
+      # Fetches the domain's whole event history from the routed Lambda on every call.
+      # Uncached: nothing calls it on a hot path.
       #
-      # @return [Array<Runtime::Event>] every event in the routed Lambda's domain
-      #   journal, oldest first, with `occurred_at` always nil (the kernel is
-      #   timestamp-free by design)
+      # @return [Array<Runtime::Event>] every journaled event, oldest first, with
+      #   `occurred_at` always nil
       def events
         @client.read.fetch("events", []).map { |e| build_event(e) }
       end
@@ -231,12 +120,8 @@ module Hecks
         response.fetch("events", []).map { |e| build_event(e) }
       end
 
-      # Rust's own event JSON (kernel/cli.rs's `event_to_json`) carries
-      # `name`/`aggregate`/`id`/`payload` only — no `occurred_at`
-      # (nothing in the kernel tracks wall-clock time; every
-      # replay is deterministic and timestamp-free by design). `nil`
-      # here, not a synthesized `Time.now` that would silently lie
-      # about when something actually happened.
+      # The kernel's event JSON carries no timestamp, so `occurred_at` stays nil
+      # rather than a synthesized `Time.now`.
       def build_event(json)
         Event.new(name: json["name"], aggregate: json["aggregate"], id: json["id"],
                   payload: JSON.parse(JSON.generate(json["payload"]), symbolize_names: true), occurred_at: nil)

data/lib/hecks/runtime/routing.rb

@@ -1,13 +1,7 @@
 module Hecks
   module Runtime
-    # The invocation address is not part of a command's domain payload.
-    # Aggregate commands carry one receiver identity; entity commands carry
-    # the aggregate receiver followed by one identity for every entity hop.
-    #
-    # Reading a call's shape — what `to:` and `with:` mean, the BUG#7/#17/#18
-    # rules — lives in `Runtime::Invocation.from_call` now (invocation.rb).
-    # `envelope`/`payload` are kept as thin delegators for any caller still
-    # naming them; the dispatcher itself builds an Invocation instead.
+    # The invocation address (`to:`), kept apart from a command's domain payload.
+    # Thin delegators to `Runtime::Invocation`, which reads a call's shape.
     module Routing
       Envelope = Struct.new(:aggregate, :entities, keyword_init: true) do
         # @param aggregate [String, #to_s] the receiving aggregate's identity
@@ -21,8 +15,7 @@ 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.
+      # Resolves a `to:` argument into a routing envelope (see `Invocation.route`).
       #
       # @param to [String, Hash, nil] a bare aggregate identity, or a Hash with
       #   `aggregate:` and `entity:`/`entities:`; nil for no receiver
@@ -32,11 +25,7 @@ module Hecks
       #   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.
+      # Resolves a command's offered facts into its flat args hash (see `Invocation.facts_for`).
       #
       # @param command [Class] a `Bluebook::Command` subclass (or port-operation class)
       #   responding to `hecks_name` and `attributes`

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

@@ -3,80 +3,33 @@ require_relative "../value"
 module Hecks
   module Runtime
     class SagaInterpreter
-      # How a saga decides which conversation an event belongs to — three
-      # tiers, each one a lesson.
+      # How a saga decides which conversation an event belongs to.
       module Correlation
         private
 
-        # A dotted path names the scalar field, rather than asking a value object
-        # to stand in for one. `correlates_by :end_to_end` would key a saga on
-        # the whole ExternalTransfer::EndToEndReference — and what a non-scalar
-        # correlation key even is is representation-dependent (the object
-        # itself? its serialised text?). `:"end_to_end.value"` reads the one
-        # field with a single unambiguous rendering.
+        # Resolves the correlation key in three tiers: the payload path, the stamp from
+        # the dispatching saga, then the emitting record's own identity.
+        # A dotted path (`:"end_to_end.value"`) names one scalar; a whole value object
+        # has no single unambiguous rendering as a key.
         def saga_correlation(process_manager, event)
           path  = process_manager.correlates_by.to_s.split(".")
-          # A later event may already hold the scalar. `reference.value` digs a
-          # value object's field out of a fresh declaration (TransferRequested's
-          # `reference` is a TransferReference) — but a downstream event this
-          # same value was smuggled through as a passthrough argument
-          # (AccountDebited's `reference:`, resolved by `dispatch_args` to the
-          # bare correlation string) carries it as a scalar already, with
-          # nothing left to dig. `"xfer-1".respond_to?(:[])` is true — String
-          # has its own `[]` (substring indexing) — so checking for keyed
-          # lookup explicitly, rather than "responds to `[]` at all", is what
-          # stops the second segment from being read as a symbol index into a
-          # string that has already arrived.
+          # A downstream event may carry the bare scalar already. Strings respond to `[]`,
+          # so test for Hash/Value explicitly rather than `respond_to?(:[])`.
           value = path.reduce(event.payload) do |held, segment|
             held.is_a?(Hash) || held.is_a?(Value) ? held[segment.to_sym] : held
           end
           return value unless value.to_s.empty?
 
-          # **The stamp** — `deliver_saga_dispatch` marks its own event before this
-          # saga's next step ever asks, for a leg whose command declares
-          # neither the correlation field itself nor the emitting aggregate's
-          # own reference key (the two tiers above). command_interpreter/
-          # argument_gate.rb names the old payload-only lookup "the weakest
-          # part of the gate" : a correlation key arriving on a command only
-          # because `correlation_keys` widens the undeclared-argument
-          # allow-list domain-wide. This is the additive fix — a leg that
-          # carries nothing correlation-shaped at all still correlates,
-          # because the saga that dispatched it already knows the answer.
-          # Keyed by `correlation_head`
-          # rather than a bare scalar so an event stamped by one saga cannot be
-          # misread by an unrelated one correlating on a different field.
+          # The stamp `deliver_saga_dispatch` puts on its own event, for legs whose command
+          # carries no correlation field. Keyed by `correlation_head` so another saga
+          # correlating on a different field cannot misread it.
           stamped = event.correlation && event.correlation[process_manager.correlation_head.to_s]
           return stamped unless stamped.nil? || stamped.to_s.empty?
 
-          # 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, 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" —
-          # and unlike a payload dig it is populated by the record itself,
-          # not by which dispatch convention the caller happened to use.
-          #
-          # Gated, still — a manually-dispatched command on a wholly
-          # unrelated aggregate can share an event name this process_manager happens to
-          # handle (`Drawer.Take` also emits "Taken", the same name a
-          # saga-dispatched leg uses) with nothing this saga should read as
-          # its own conversation. What makes a leg genuinely
-          # self-referencing — the one fact worth trusting `event.id`
-          # for — is that `correlates_by`'s own head field is this event's
-          # own aggregate's declared identity, not merely a same-shaped
-          # name: `OnboardingCase.identity_heads` really does include
-          # `:reference`, `correlates_by :"reference.value"`'s own head ;
-          # `Drawer.identity_heads` is `[:number]`, nowhere close.
+          # A self-referencing leg correlates by `event.id`: routing keys never ride in the
+          # payload, so a payload dig finds nothing for legs with no declared attributes.
+          # Gated on the head being the aggregate's own identity, so an unrelated aggregate
+          # emitting a same-named event is not read as this saga's conversation.
           self_identified?(process_manager, event) ? event.id : nil
         end