hecks 3.5.0 → 3.6.0

data/lib/hecks/runtime/saga_interpreter.rb

@@ -1,5 +1,9 @@
 require "json"
 require_relative "saga_interpreter/correlation"
+require_relative "saga_interpreter/lifecycle"
+require_relative "saga_interpreter/transitions"
+require_relative "saga_interpreter/delivery"
+require_relative "saga_interpreter/compensation"
 require_relative "../bluebook/process_manager"
 require_relative "errors"
 require_relative "reaction_invocation"
@@ -12,6 +16,10 @@ module Hecks
     # event, checkpointing each transition durably before its dispatches run.
     class SagaInterpreter
       include Correlation
+      include Lifecycle
+      include Transitions
+      include Delivery
+      include Compensation
 
       # The trigger lives on the declaration it triggers — see ProcessManager::REFUSED.
       REFUSED = Bluebook::ProcessManager::REFUSED
@@ -20,6 +28,29 @@ module Hecks
       # compensate for, instead of unwinding on the first failure.
       MAX_DEFECT_RETRIES = 3
 
+      # One transition of one saga instance: the declaration, the event that moves it, the
+      # instance's correlation, the log record of the move, and — once a leg is taken under the
+      # mutex — the instance, the leg's handler and the state it left.
+      Leg = Struct.new(:process_manager, :event, :domain, :correlation, :record, :instance, :handler, :pre_state) do
+        # Moves the instance into the handler's state, remembering the state it left.
+        #
+        # @param leg_handler [Bluebook::ProcessManager::Handler] the leg being taken
+        # @return [void]
+        def take(leg_handler)
+          self.handler   = leg_handler
+          self.pre_state = instance[:state]
+          instance[:state] = leg_handler.to_state
+        end
+
+        # What a crash between the checkpoint and the dispatches leaves behind, to be surfaced
+        # on the next boot.
+        #
+        # @return [Hash{Symbol => Object}] the event, the states moved between, and the commands
+        def pending_marker
+          { on: event.name, from: pre_state, to: instance[:state], dispatches: handler.dispatches.map(&:command_name) }
+        end
+      end
+
       attr_reader :registry
 
       # @param registry [Runtime::Registry] the booted registry whose declared
@@ -68,332 +99,22 @@ module Hecks
         )
       end
 
+      # The checkpoint of the instance a leg is moving.
+      def checkpoint_leg(leg, pending: nil)
+        checkpoint(leg.process_manager, leg.correlation, leg.instance, leg.domain, pending: pending)
+      end
+
+      # Appends the leg's log record, with `fields` merged over it.
+      def log_leg(leg, fields)
+        @registry.saga_log << leg.record.merge(fields)
+      end
+
       # Wrapped in a Hash before the round-trip since `JSON.parse` only
       # accepts an object at the top level. `|| []` rehydrates a ledger
       # that has never completed a compensable leg to empty, never nil.
       def deep_copy_array(array) = deep_copy(list: array || [])[:list]
 
       def deep_copy(hash) = JSON.parse(JSON.generate(hash), symbolize_names: true)
-
-      def begin_saga(process_manager, event, domain)
-        return unless event.name == process_manager.starts_on
-
-        correlation = saga_correlation(process_manager, event)
-        if correlation.to_s.empty?
-          @registry.saga_log << { process_manager: process_manager.name, on: event.name,
-                                  born: false, reason: "no #{process_manager.correlates_by} in the payload" }
-          return
-        end
-
-        created = @registry.saga_mutex.synchronize do
-          next false if @registry.saga_instances[process_manager.name].key?(correlation)
-
-          # `.dup` — a fresh saga's own memory starts as a copy of the
-          # starting event's payload, never the frozen payload itself,
-          # since memory is written into over the saga's lifetime.
-          instance = { state: process_manager.states.first, memory: event.payload.dup, completed_compensations: [] }
-          @registry.saga_instances[process_manager.name][correlation] = instance
-          checkpoint(process_manager, correlation, instance, domain)
-          true
-        end
-        return unless created
-
-        @registry.saga_log << { process_manager: process_manager.name, on: event.name,
-                                instance: correlation, born: true, state: process_manager.states.first }
-      end
-
-      # The mutex covers only the check-mutate-checkpoint step, never the
-      # dispatch cascade that follows — `deliver_saga_dispatch`'s
-      # `@door.reenter` can recursively re-enter this interpreter on the
-      # same thread, and `Mutex` is not reentrant.
-      def advance_saga(process_manager, event, domain)
-        return unless process_manager.handles?(event.name)
-
-        correlation = saga_correlation(process_manager, event)
-        return if correlation.to_s.empty?
-
-        record    = { process_manager: process_manager.name, on: event.name, instance: correlation }
-        instance  = nil
-        handler   = nil
-        pre_state = nil
-
-        advanced = @registry.saga_mutex.synchronize do
-          instance = @registry.saga_instances[process_manager.name][correlation]
-          unless instance
-            @registry.saga_log << record.merge(advanced: false, reason: "no conversation remembers #{correlation.inspect}")
-            next false
-          end
-          # Leg chosen by (event, current state) — read under the mutex so
-          # two legs on the same event pick based on the state that's
-          # actually current right now.
-          handler = process_manager.handler_for(event.name, instance[:state])
-          unless handler
-            @registry.saga_log << record.merge(advanced: false,
-                                               reason:   leg_mismatch(process_manager, event.name, instance[:state]))
-            next false
-          end
-
-          pre_state = instance[:state]
-          instance[:state] = handler.to_state
-          checkpoint(process_manager, correlation, instance, domain,
-                     pending: pending_marker(event, handler, pre_state, instance[:state]))
-          true
-        end
-        return unless advanced
-
-        settle_transition(process_manager, event, handler, instance, correlation, domain, record, pre_state)
-      end
-
-      def leg_mismatch(process_manager, event_name, state)
-        expected = process_manager.handlers_for(event_name).map { |h| h.from_state.inspect }.uniq
-        "in #{state.inspect}, not #{expected.join(' or ')}"
-      end
-
-      def pending_marker(event, handler, from_state, to_state)
-        { on: event.name, from: from_state, to: to_state, dispatches: handler.dispatches.map(&:command_name) }
-      end
-
-      # The shared tail of `advance_saga` and `unwind`, both of which guard,
-      # mutate and checkpoint under the mutex before calling this.
-      def settle_transition(process_manager, event, handler, instance, correlation, domain, record, pre_state,
-                            drain_compensations: false)
-        # from:/to: read back from `instance` itself, never re-derived from
-        # `handler.from_state`/`to_state` — otherwise a log entry checked
-        # against that same handler object could never actually disagree
-        # with it, no matter what the runtime did.
-        @registry.saga_log << record.merge(advanced: true, from: pre_state, to: instance[:state])
-
-        # Derived compensations run newest-first, before any hand-written
-        # `on :refused` dispatches below. Drained (popped), not just read —
-        # that's what keeps a re-entrant `on :refused` from running twice.
-        if drain_compensations
-          compensations = instance[:completed_compensations] || []
-          deliver_derived_compensation(process_manager, compensations.pop, correlation, domain) until compensations.empty?
-          checkpoint(process_manager, correlation, instance, domain)
-        end
-
-        handler.dispatches.each do |spec|
-          deliver_saga_dispatch(process_manager, spec, event, instance, correlation, domain)
-        end
-
-        # Guarded by `.equal?` (not `==`): `deliver_saga_dispatch`'s own
-        # `reenter` can trigger this correlation's `ends_on` as a nested
-        # reaction, deleting this row before this line runs. Clearing
-        # unconditionally would resurrect an already-ended saga, or stamp
-        # a reborn instance with a stale one's state.
-        @registry.saga_mutex.synchronize do
-          next unless @registry.saga_instances[process_manager.name][correlation].equal?(instance)
-
-          checkpoint(process_manager, correlation, instance, domain, pending: nil)
-        end
-      end
-
-      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength -- the checkpoint/
-      # dispatch/compensation ledger protocol reads best as one sequence.
-      def deliver_saga_dispatch(process_manager, spec, event, instance, correlation, domain)
-        args   = dispatch_args(process_manager, spec, event, instance, correlation)
-        record = { process_manager: process_manager.name, instance: correlation, dispatch: spec.command_name }
-
-        # Raw inputs captured alongside the resolved result — never
-        # re-derived later from saga_instances, which only ever holds the
-        # final memory, not what it was at the moment this dispatch fired.
-        unless spec.with_spec.to_a.empty?
-          @registry.saga_dispatch_log << { process_manager: process_manager.name, instance: correlation,
-                                           dispatch: spec.command_name,
-                                            on: event.name, correlation_head: process_manager.correlation_head,
-                                            event_payload: event.payload, memory: Value.materialize(instance[:memory]),
-                                            with_spec: spec.with_spec, args: args }
-        end
-
-        if @door.reaction_depth_reached?
-          # Not a domain decision, but unambiguous — the leg didn't run, so
-          # it unwinds like a refusal rather than stranding the instance.
-          @registry.saga_log << record.merge(delivered: false,
-                                             reason:    "reaction depth #{@door.max_reaction_depth} reached")
-          unwind(process_manager, event, instance, correlation, domain)
-          return
-        end
-
-        attempt = 0
-        compensation_recorded = false
-        begin
-          # Recorded before dispatching, not after `@door.reenter` returns —
-          # reenter can recursively re-enter this interpreter and refuse
-          # before ever returning here, and recording only on success would
-          # be too late for that nested refusal to see this leg's own
-          # compensation. Popped back off in the rescues below if this
-          # leg's own attempt is the one that failed.
-          if spec.compensates && !compensation_recorded
-            resolved = dispatch_args(process_manager, spec.compensates, event, instance, correlation)
-            instance[:completed_compensations] << { command_name: spec.compensates.command_name, args: resolved }
-            checkpoint(process_manager, correlation, instance, domain)
-            compensation_recorded = true
-          end
-
-          invocation = ReactionInvocation.build(
-            registry:        @registry,
-            verb:            qualified(spec.command_name, domain),
-            projected:       args,
-            explicit:        ReactionInvocation.projection_declared?(spec),
-            passthrough:     [process_manager.correlation_head],
-            source_receiver: { aggregate: event.aggregate, identity: event.id }
-          )
-          @door.reenter(qualified(spec.command_name, domain),
-                        saga_correlation: { process_manager.correlation_head.to_s => correlation }, **invocation)
-          @registry.saga_log << record.merge(delivered: true)
-        rescue *DOMAIN_REFUSALS => e
-          unrecord_compensation(instance, correlation, domain, process_manager) if compensation_recorded
-          # A refusal by the target is a recorded outcome, and the leg
-          # that raised it unwinds and runs its own compensation there.
-          @registry.saga_log << record.merge(delivered: false, reason: e.message)
-          unwind(process_manager, event, instance, correlation, domain)
-        rescue StandardError => e
-          unrecord_compensation(instance, correlation, domain, process_manager) if compensation_recorded
-          compensation_recorded = false
-          # Unlike a refusal, a crash isn't a domain decision, so it
-          # doesn't unwind on the first failure — MAX_DEFECT_RETRIES lets a
-          # transient failure clear on retry. `defect_compensated: true`
-          # tags an exhausted retry distinctly, so the log never
-          # misrepresents a crash as a decision the domain made.
-          attempt += 1
-          if attempt <= MAX_DEFECT_RETRIES
-            @registry.saga_log << record.merge(delivered: false, reason: e.message,
-                                               defect: true, error_class: e.class.name,
-                                               attempt: attempt, retrying: true)
-            retry
-          end
-
-          warn "[hecks] defect in saga #{process_manager.name} — instance #{correlation.inspect} " \
-               "dispatching #{spec.command_name} after #{attempt} attempts: #{e.class}: #{e.message}"
-          @registry.saga_log << record.merge(delivered: false, reason: e.message, defect: true,
-                                             error_class: e.class.name, defect_compensated: true)
-          unwind(process_manager, event, instance, correlation, domain)
-        end
-      end
-      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
-
-      # `.pop`, not search-and-delete — nothing else can have pushed after
-      # this leg's own entry without this leg's own `reenter` having
-      # already returned first.
-      def unrecord_compensation(instance, correlation, domain, process_manager)
-        instance[:completed_compensations].pop
-        checkpoint(process_manager, correlation, instance, domain)
-      end
-
-      # A refused leg unwinds by running its own declared `on :refused`
-      # handler, where compensation lives — also the destination for a
-      # leg that hit the reaction-depth ceiling or exhausted its defect
-      # retries.
-      #
-      # A compensation that is itself refused does not unwind again: the
-      # state moves to the compensating leg's to_state before its
-      # dispatches run, so a second refusal finds the instance already
-      # out of from_state and records that instead.
-      def unwind(process_manager, event, instance, correlation, domain)
-        return unless instance && process_manager.handles?(REFUSED)
-
-        record    = { process_manager: process_manager.name, on: REFUSED, instance: correlation }
-        handler   = nil
-        pre_state = nil
-
-        # Same non-reentrancy reasoning as `advance_saga`'s own comment —
-        # the mutex covers only the check-mutate-checkpoint step.
-        advanced = @registry.saga_mutex.synchronize do
-          handler = process_manager.handler_for(REFUSED, instance[:state])
-          unless handler
-            @registry.saga_log << record.merge(advanced: false,
-                                               reason:   leg_mismatch(process_manager, REFUSED, instance[:state]))
-            next false
-          end
-
-          pre_state = instance[:state]
-          instance[:state] = handler.to_state
-          checkpoint(process_manager, correlation, instance, domain,
-                     pending: pending_marker(event, handler, pre_state, instance[:state]))
-          true
-        end
-        return unless advanced
-
-        # `drain_compensations: true` only here — `advance_saga`'s own call
-        # never fires derived compensation.
-        settle_transition(process_manager, event, handler, instance, correlation, domain, record, pre_state,
-                          drain_compensations: true)
-      end
-
-      # `entry[:args]` is already resolved, so this skips `dispatch_args`
-      # and goes straight to delivery. Never re-enters `unwind` on its own
-      # failure — `compensation_failed: true` tags a refused compensation
-      # distinctly rather than as an ordinary failed delivery.
-      def deliver_derived_compensation(process_manager, entry, correlation, domain)
-        record = { process_manager: process_manager.name, instance: correlation, dispatch: entry[:command_name] }
-
-        attempt = 0
-        begin
-          invocation = ReactionInvocation.build(
-            registry:        @registry,
-            verb:            qualified(entry[:command_name], domain),
-            projected:       entry[:args],
-            explicit:        true,
-            passthrough:     [process_manager.correlation_head],
-            source_receiver: nil
-          )
-          @door.reenter(qualified(entry[:command_name], domain),
-                        saga_correlation: { process_manager.correlation_head.to_s => correlation }, **invocation)
-          @registry.saga_log << record.merge(delivered: true, compensation: true)
-        rescue *DOMAIN_REFUSALS => e
-          @registry.saga_log << record.merge(delivered: false, reason: e.message, compensation: true,
-                                             compensation_failed: true)
-        rescue StandardError => e
-          attempt += 1
-          if attempt <= MAX_DEFECT_RETRIES
-            @registry.saga_log << record.merge(delivered: false, reason: e.message, compensation: true,
-                                               defect: true, error_class: e.class.name,
-                                               attempt: attempt, retrying: true)
-            retry
-          end
-
-          warn "[hecks] defect compensating saga #{process_manager.name} — instance #{correlation.inspect} " \
-               "dispatching #{entry[:command_name]} after #{attempt} attempts: #{e.class}: #{e.message}"
-          @registry.saga_log << record.merge(delivered: false, reason: e.message, compensation: true,
-                                             defect: true, error_class: e.class.name, compensation_failed: true)
-        end
-      end
-
-      def dispatch_args(process_manager, spec, event, instance, correlation)
-        ReactionInvocation.resolve_mapping(
-          with_spec: spec.with_spec,
-          scopes:    [["current event payload", event.payload], ["opening event memory", instance[:memory]]],
-          bindings:  { process_manager.correlation_head => correlation },
-          label:     "#{process_manager.name}'s dispatch #{spec.command_name}"
-        )
-      end
-
-      # Unconditionally the saga's own home domain, never inferred from
-      # `command_name`'s shape — unlike a policy's explicit `target_domain`
-      # (set by `across`), a saga's `dispatch`/`compensates` has no such
-      # field, and every command a saga fires lands inside its own
-      # bluebook chapter.
-      def qualified(command_name, domain)
-        "#{domain}::#{command_name}"
-      end
-
-      def end_saga(process_manager, event, domain)
-        return unless event.name == process_manager.ends_on
-
-        correlation = saga_correlation(process_manager, event)
-        return if correlation.to_s.empty?
-
-        ended = @registry.saga_mutex.synchronize do
-          next false unless @registry.saga_instances[process_manager.name].delete(correlation)
-
-          @registry.saga_persistence(domain).delete_saga(process_manager: process_manager.name, correlation: correlation)
-          true
-        end
-        return unless ended
-
-        @registry.saga_log << { process_manager: process_manager.name, on: event.name,
-                                instance: correlation, ended: true }
-      end
     end
   end
 end

data/lib/hecks/runtime/tenant_check.rb

@@ -15,18 +15,23 @@ module Hecks
         return unless bluebook
 
         offender = bluebook.aggregates.find do |aggregate|
-          adapter_name = Ports::Persistence::BindingPolicy.resolve(registry, domain, aggregate).adapter
-          !tenant_capable?(registry, adapter_name)
+          !tenant_capable?(registry, bound_adapter(registry, domain, aggregate))
         end
         return unless offender
 
-        adapter_name = Ports::Persistence::BindingPolicy.resolve(registry, domain, offender).adapter
-        raise WiringError,
-              "#{domain}::#{offender.hecks_name} is bound to #{adapter_name}, which is not " \
-              "tenant_capable? — booting #{domain} for more than one tenant would share " \
-              "#{adapter_name}'s own storage across tenants that must never see each other's data. " \
-              "Bind a tenant-capable adapter (Memory, PostgresEra with its own schema: per tenant), " \
-              "or keep #{domain} single-tenant."
+        raise WiringError, ungoverned_wording(domain, offender, bound_adapter(registry, domain, offender))
+      end
+
+      def bound_adapter(registry, domain, aggregate)
+        Ports::Persistence::BindingPolicy.resolve(registry, domain, aggregate).adapter
+      end
+
+      def ungoverned_wording(domain, offender, adapter_name)
+        "#{domain}::#{offender.hecks_name} is bound to #{adapter_name}, which is not " \
+          "tenant_capable? — booting #{domain} for more than one tenant would share " \
+          "#{adapter_name}'s own storage across tenants that must never see each other's data. " \
+          "Bind a tenant-capable adapter (Memory, PostgresEra with its own schema: per tenant), " \
+          "or keep #{domain} single-tenant."
       end
 
       # Same defensive shape as EraCheck#lineage_capable? — a class that

data/lib/hecks/runtime/value/admission.rb

@@ -18,22 +18,9 @@ module Hecks
         #   admitted values of the first attribute and the one offered
         def admit_member(value_object, fields)
           return if value_object.members.empty?
-
-          discriminant = value_object.attributes.first.name
-          offered      = fields[discriminant]
-          admitted     = value_object.members.map { |member| member[discriminant].to_s }
           return if value_object.members.any? { |member| member_matches?(member, fields) }
 
-          raise InvariantViolation,
-                RefusalWording.render_site("InvariantViolation", "closed_set_member",
-                                           type: value_object.hecks_name,
-                                           admitted: admitted, offered: offered.inspect)
-        end
-
-        # Compares every declared field, not only the first: a multi-column `member` row is a
-        # whole tuple, so a matching first column with a wrong second is not a member.
-        private def member_matches?(member, fields)
-          member.all? { |field, value| fields[field].to_s == value.to_s }
+          refuse_non_member!(value_object, fields)
         end
 
         # Checks a value against the closed set its attribute names with `admits:`.
@@ -72,10 +59,7 @@ module Hecks
         # @raise [Runtime::InvariantViolation] if `admits` is not qualified, no chapter is
         #   reachable from `owner`, or the chapter declares no such aggregate or value object
         def admitted_members(owner, attribute)
-          aggregate_name, set_name = attribute.admits.to_s.split("::", 2)
-          chapter = chapter_of(owner)
-          set     = set_name && chapter&.aggregate(aggregate_name)&.value_object(set_name)
-
+          set = declared_set(owner, attribute)
           unless set
             raise InvariantViolation,
                   RefusalWording.render_site("InvariantViolation", "undeclared_set",
@@ -110,8 +94,33 @@ module Hecks
           fields.size == 1 ? fields.values.first : value
         end
 
+        private
+
+        def refuse_non_member!(value_object, fields)
+          discriminant = value_object.attributes.first.name
+          admitted     = value_object.members.map { |member| member[discriminant].to_s }
+          raise InvariantViolation,
+                RefusalWording.render_site("InvariantViolation", "closed_set_member",
+                                           type: value_object.hecks_name,
+                                           admitted: admitted, offered: fields[discriminant].inspect)
+        end
+
+        # Compares every declared field, not only the first: a multi-column `member` row is a
+        # whole tuple, so a matching first column with a wrong second is not a member.
+        def member_matches?(member, fields)
+          member.all? { |field, value| fields[field].to_s == value.to_s }
+        end
+
+        # The value object `attribute.admits` names (`"Aggregate::Set"`), when the chapter declares
+        # it.
+        def declared_set(owner, attribute)
+          aggregate_name, set_name = attribute.admits.to_s.split("::", 2)
+          chapter = chapter_of(owner)
+          set_name && chapter&.aggregate(aggregate_name)&.value_object(set_name)
+        end
+
         # Applies `admits:` to value-object fields too, which never pass through `for_attribute`.
-        private def check_admitted(value_object, fields)
+        def check_admitted(value_object, fields)
           value_object.attributes.each do |attribute|
             next unless attribute.admits