hecks 0.2.0 → 1.0.0

data/lib/hecks/runtime/remote_dispatcher.rb

@@ -0,0 +1,143 @@
+require_relative "dispatcher"
+require_relative "instance"
+require_relative "event"
+require_relative "errors"
+require_relative "../naming"
+require_relative "../adapters/driven/lambda/client"
+require_relative "../ports/persistence/binding_policy"
+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}", **identity, **args).instance.state`,
+    # and both classes answer that identically.
+    #
+    # 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.
+    class RemoteDispatcher
+      Result = Struct.new(:verb, :instance, :events, keyword_init: true) do
+        def id    = instance.id
+        def state = instance.to_h
+      end
+
+      attr_reader :registry
+
+      def initialize(registry, region: "us-east-1")
+        @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).
+        @client = Adapters::Lambda::Client.new(domain: ENV["DOMAIN_NAME"] || File.basename(registry.root), region: region)
+        # 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
+
+      def dispatch(verb, saga_correlation: nil, **args)
+        domain, aggregate_name, = Naming.split_verb(verb) ||
+                                  raise(UnknownVerb,
+                                        RefusalWording.render("UnknownVerb", "not_fully_qualified", verb: verb.inspect))
+        aggregate = @registry.bluebook(domain)&.aggregate(aggregate_name) ||
+                    raise(UnknownVerb,
+                          RefusalWording.render("UnknownVerb", "no_aggregate", domain: domain, aggregate: aggregate_name.inspect))
+
+        # 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.
+        adapter_name = Ports::Persistence::BindingPolicy.resolve(@registry, domain, aggregate).adapter
+        return @local.dispatch(verb, saga_correlation: saga_correlation, **args) unless @registry.adapter_class(adapter_name) <= Ports::Persistence::RemoteRuntime
+
+        response = @client.dispatch(verb, args)
+
+        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.
+        fqn = "#{domain}::#{aggregate.hecks_name}"
+        mutation = response.fetch("mutations", []).last&.find { |m| m["aggregate"] == fqn } ||
+                   raise(WiringError,
+                         "#{verb} was accepted but rust/host reported no mutation for #{fqn} — response: #{response.inspect}")
+
+        instance = Instance.new(aggregate: aggregate, id: mutation["id"],
+                                state: JSON.parse(JSON.generate(mutation["state"]), symbolize_names: true))
+
+        Result.new(verb: verb, instance: instance, events: step_events(response))
+      end
+
+      def query(verb, **args)           = @local.query(verb, **args)
+      def reference_query(verb, **args) = @local.reference_query(verb, **args)
+
+      # 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.
+      def events
+        @client.read.fetch("events", []).map { |e| build_event(e) }
+      end
+
+      private
+
+      def step_events(response)
+        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.
+      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)
+      end
+    end
+  end
+end

data/lib/hecks/runtime/routing.rb

@@ -0,0 +1,96 @@
+require_relative "errors"
+require_relative "refusal_wording"
+
+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.
+    module Routing
+      Envelope = Struct.new(:aggregate, :entities, keyword_init: true) do
+        def initialize(aggregate:, entities: [])
+          super(aggregate: aggregate.to_s, entities: Array(entities).map(&:to_s).freeze)
+          freeze
+        end
+      end
+
+      module_function
+
+      def envelope(to, entity_depth: 0)
+        return nil if to.nil?
+
+        aggregate, entities = if to.is_a?(Hash)
+                                hash = to.transform_keys(&:to_sym)
+                                unknown = hash.keys - %i[aggregate entity entities]
+                                unless unknown.empty?
+                                  raise TypeMismatch, "to: does not recognize #{unknown.sort.join(', ')}"
+                                end
+
+                                [hash[:aggregate], entity_identities(hash)]
+                              else
+                                [to, []]
+                              end
+
+        if aggregate.nil? || aggregate.to_s.empty?
+          raise TypeMismatch, "to: must name the receiving aggregate identity"
+        end
+        if entities.size != entity_depth
+          raise TypeMismatch,
+                "to: for an entity command needs #{entity_depth} entity " \
+                "#{entity_depth == 1 ? 'identity' : 'identities'} after the aggregate — got #{entities.size}"
+        end
+        if entities.any? { |identity| identity.nil? || identity.to_s.empty? }
+          raise TypeMismatch, "to: contains a blank entity identity"
+        end
+
+        Envelope.new(aggregate: aggregate, entities: entities)
+      end
+
+      # `with:` is deliberately strict. Compatibility-only calls still pass
+      # loose keyword arguments through the old addressing gate, but a caller
+      # choosing the explicit envelope cannot smuggle receiver identity back
+      # into the payload.
+      def payload(command, with:, legacy:)
+        if with && !legacy.empty?
+          raise TypeMismatch, "dispatch takes command facts in with:, not both with: and loose keyword arguments"
+        end
+
+        return legacy unless with
+        unless with.is_a?(Hash)
+          raise TypeMismatch, "with: must be a hash of command facts"
+        end
+
+        offered = with.transform_keys(&:to_sym)
+        declared = command.attributes.map { |attribute| attribute.name.to_sym }
+        unknown = (offered.keys - declared).sort
+        unless unknown.empty?
+          reading = declared.empty? ? "none" : declared.join(", ")
+          raise UnknownArgument,
+                RefusalWording.render("UnknownArgument", "unknown_args",
+                                      command: command.hecks_name, unknown: unknown.join(", "),
+                                      declared: reading)
+        end
+
+        absent = command.attributes.reject(&:optional?).map { |attribute| attribute.name.to_sym } - offered.keys
+        unless absent.empty?
+          reading = declared.empty? ? "none" : declared.join(", ")
+          raise AbsentArgument,
+                RefusalWording.render("AbsentArgument", "absent_args",
+                                      command: command.hecks_name, absent: absent.sort.join(", "),
+                                      declared: reading)
+        end
+
+        offered
+      end
+
+      def entity_identities(hash)
+        if hash.key?(:entities) && hash.key?(:entity)
+          raise TypeMismatch, "to: takes entity: or entities:, not both"
+        end
+
+        hash.key?(:entities) ? Array(hash[:entities]) : Array(hash[:entity])
+      end
+      private_class_method :entity_identities
+    end
+  end
+end

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

@@ -0,0 +1,97 @@
+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.
+      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.
+        def saga_correlation(pm, event)
+          path  = pm.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.
+          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.
+          stamped = event.correlation && event.correlation[pm.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. 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.
+          #
+          # `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 pm 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.
+          self_identified?(pm, event) ? event.id : nil
+        end
+
+        def self_identified?(pm, event)
+          domain, bare_name = event.aggregate.to_s.split("::", 2)
+          return false unless bare_name
+
+          construct = @registry.bluebook(domain)&.aggregate(bare_name)
+          return false unless construct
+
+          construct.identity_heads.map(&:to_s).include?(pm.correlation_head.to_s)
+        end
+      end
+    end
+  end
+end