hecks 3.4.2 → 3.6.0

data/lib/hecks/runtime/loader.rb

@@ -5,12 +5,16 @@ require_relative "dispatcher"
 require_relative "remote_dispatcher"
 require_relative "boot_gates"
 require_relative "registry"
+require_relative "loader/boot_steps"
+require_relative "loader/described"
 
 module Hecks
   module Runtime
     # Boots a domain: loads its bluebook directory into a fresh Registry, runs
     # every boot gate, and hands back the bound Dispatcher (or RemoteDispatcher).
     class Loader
+      extend BootSteps
+
       # Default for a boot's `environment:` keyword: read `HECKS_ENVIRONMENT`. An explicit
       # `nil` means no overlay, whatever the variable holds.
       FROM_ENV = :from_env
@@ -48,28 +52,6 @@ module Hecks
         install_doors ? bind_runtime(dispatcher) : dispatcher
       end
 
-      # What `describe` answers: the loaded declarations and nothing bound to run them.
-      #
-      # The declarations load the first time `registry` is asked for, not when `describe` returns,
-      # so a caller that can answer from `directory` alone (a launcher with its help already
-      # remembered) never pays for the load. The directory is checked at once.
-      class Described
-        # @return [String] the domain directory that was described
-        attr_reader :directory
-
-        # @param directory [String] the domain directory
-        # @yield loads the declarations; answers the registry
-        def initialize(directory, &load)
-          @directory = directory
-          @load = load
-        end
-
-        # @return [Registry] the declarations, loaded on first use
-        def registry
-          @registry ||= @load.call
-        end
-      end
-
       # Loads `path`'s declarations into a fresh Registry and stops: no boot gate runs, no
       # persistence adapter is resolved or bound, nothing connects to a database.
       #
@@ -86,17 +68,20 @@ module Hecks
         directory = loading.bluebook_directory(path)
         overlay   = selected_environment(environment)
 
-        Described.new(directory) do
-          root     = loading.shared_root(shared, directory)
-          registry = Registry.new(root: File.dirname(directory))
+        Described.new(directory) { load_declarations(loading, directory, shared, overlay) }
+      end
 
-          Hecks.with_registry(registry) do
-            loading.load_library
-            loading.load_project(root)
-            loading.load_domain(directory, environment: overlay)
-          end
-          registry
+      # Loads the directory's declarations into a fresh Registry, answering it.
+      def self.load_declarations(loading, directory, shared, overlay)
+        root     = loading.shared_root(shared, directory)
+        registry = Registry.new(root: File.dirname(directory))
+
+        Hecks.with_registry(registry) do
+          loading.load_library
+          loading.load_project(root)
+          loading.load_domain(directory, environment: overlay)
         end
+        registry
       end
 
       # The overlay a boot loads: the caller's own choice (nil meaning none), else the
@@ -122,25 +107,6 @@ module Hecks
         dispatcher.outbox.redrive!
       end
 
-      # Turns every `.hecksagon`-declared `mark_sensitive` fact into a real
-      # `Privacy::Marking.Mark`. Idempotent across reboots — a marking already
-      # present is never re-dispatched. A no-op when nothing declared one, or
-      # the domain never attached Privacy at all.
-      def self.seed_privacy_markings!(dispatcher, registry)
-        return if registry.pending_privacy_markings.empty?
-        return unless registry.bluebook("Privacy")
-
-        already_marked_by_domain = registry.pending_privacy_markings.map { |marking| marking[:domain] }.uniq.to_h do |domain|
-          [domain, dispatcher.query("Privacy::Marking.ForDomain", domain: domain).map { |row| row[:attribute_path][:value] }]
-        end
-
-        registry.pending_privacy_markings.each do |marking|
-          next if already_marked_by_domain[marking[:domain]].include?(marking[:attribute_path])
-
-          dispatcher.dispatch_flat("Privacy::Marking.Mark", marking)
-        end
-      end
-
       # Boots the exact bluebook/hecksagon/world files in `paths`, in place —
       # unlike `boot`, no directory globbing and no copying into a temp dir
       # (a `persisted_by` path must resolve against the real project root,
@@ -156,78 +122,25 @@ module Hecks
         loading   = Ports::Loading.bootstrap
         files     = Array(paths).map { |path| File.expand_path(path) }
         directory = File.dirname(files.first)
-        root      = loading.shared_root(shared, directory)
-        registry  = Registry.new(root: File.dirname(directory))
-
-        Hecks.with_registry(registry) do
-          loading.load_library
-          loading.load_project(root)
-          loading.load_selected(files, environment: selected_environment(environment))
-        end
+        registry  = load_files(loading, files, shared, selected_environment(environment))
 
         run_boot_gates!(registry, directory)
         dispatcher = dispatcher_for(registry)
         install_doors ? bind_runtime(dispatcher) : dispatcher
       end
 
-      # Runs every registered boot gate against `registry`, in order:
-      # era-checking (if a plugin contributes one) before `verify!`, saga
-      # rehydration after. No era-specific class is named here — each loaded
-      # persistence plugin contributes its own gates generically (ADR 0031).
-      def self.run_boot_gates!(registry, directory)
-        gates = BootGates.new
-        load_bound_adapters!(registry)
-        Ports::Persistence.each_plugin { |plugin| plugin.contribute_boot_gates(registry, gates) }
-        check_compute_rules_backstop!(registry)
-
-        gates.run!(:pre_verify, registry, directory)
-        registry.verify!
-
-        gates.register(:saga_rehydration, ->(reg, _dir) { reg.rehydrate_sagas! }, phase: :post_verify) if
-          registry.saga_domains.any? { |domain| registry.saga_persistence(domain) != Ports::Persistence::NULL_SAGA_STORE }
-        gates.run!(:post_verify, registry, directory)
-        gates
-      end
-
-      # Resolves the Ruby implementation of every adapter a hecksagon binds, and of every
-      # `default_adapter` a world names (a chapter that binds nothing takes its world's).
-      # An adapter's implementation can register its own persistence plugin as
-      # a side effect of loading (e.g. `PostgresEra`) — resolving here, before
-      # gates are collected, is what registers those plugins' gates without
-      # the app requiring them itself. A bind with no implementation is left
-      # for `verify!` to refuse.
-      def self.load_bound_adapters!(registry)
-        registry.hecksagons.each_value do |hexagon|
-          hexagon.binds.each do |bind|
-            registry.adapter_class(bind.adapter)
-          rescue WiringError
-            next
-          end
-        end
-        registry.worlds.each_value do |world|
-          registry.adapter_class(world.default_adapter) if world.default_adapter
-        rescue WiringError
-          next
-        end
-      end
+      # Loads exactly `files` into a fresh Registry rooted beside their directory, answering it.
+      def self.load_files(loading, files, shared, overlay)
+        directory = File.dirname(files.first)
+        root      = loading.shared_root(shared, directory)
+        registry  = Registry.new(root: File.dirname(directory))
 
-      # A backstop only: fires when a translation declares a `computes`/
-      # `rekeys` rule but no persistence plugin is loaded to interpret it.
-      # Any loaded plugin's own compute-rules gate refuses earlier, by name,
-      # whenever one is loaded — this only runs when nothing was.
-      def self.check_compute_rules_backstop!(registry)
-        return if Ports::Persistence.plugins_loaded?
-
-        registry.translations.each do |translation|
-          translation.aggregates.each do |aggregate|
-            next if aggregate.computes.empty? && aggregate.rekeys.empty?
-
-            raise WiringError,
-                  "cannot boot #{translation.domain}::#{aggregate.name}: a compute/rekey rule is declared, but no " \
-                  "persistence plugin that can interpret it is loaded (e.g. require " \
-                  "\"hecks/ports/persistence/plugins/era\")"
-          end
+        Hecks.with_registry(registry) do
+          loading.load_library
+          loading.load_project(root)
+          loading.load_selected(files, environment: overlay)
         end
+        registry
       end
 
       # `RemoteDispatcher` for a domain declaring `dispatched_by("Lambda")`,

data/lib/hecks/runtime/outbox/consumer_runner.rb

@@ -0,0 +1,40 @@
+require_relative "../errors"
+
+module Hecks
+  module Runtime
+    module Outbox
+      # Runs the consumer a row names: the policy or process manager that owes the reaction.
+      # Mixed into {Relay}, which holds the registry and the interpreters it attached.
+      module ConsumerRunner
+        private
+
+        def run_consumer(row)
+          raise WiringError, "outbox relay has no dispatcher attached — nothing can run #{row.consumer}" unless attached?
+
+          event = Outbox.event_from(row.event)
+          kind, fqn = row.consumer.split(":", 2)
+          home, name = fqn.split("::", 2)
+          case kind
+          when "policy" then run_policy(row, event, fqn, home, name)
+          when "saga" then run_saga(row, event, fqn, home, name)
+          else
+            raise WiringError, "outbox row #{row.delivery_id} has an unknown consumer kind #{kind.inspect}"
+          end
+        end
+
+        def run_policy(row, event, fqn, home, name)
+          policy = @registry.bluebook(home)&.policies&.find { |candidate| candidate.name == name } ||
+                   raise(WiringError, "outbox row #{row.delivery_id} names policy #{fqn}, which no bluebook declares")
+          @policies.react(event, row.domain, only: [policy, home], event_uid: row.event_uid)
+        end
+
+        def run_saga(row, event, fqn, home, name)
+          process_manager = @registry.bluebook(home)&.process_managers&.find { |candidate| candidate.name == name } ||
+                            raise(WiringError,
+                                  "outbox row #{row.delivery_id} names process_manager #{fqn}, which no bluebook declares")
+          @sagas.advance(event, row.domain, only: process_manager)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/outbox/fanout.rb

@@ -0,0 +1,82 @@
+require "securerandom"
+require_relative "../../naming"
+
+module Hecks
+  module Runtime
+    module Outbox
+      # Resolves each event's consumers once, at enqueue time, in the same
+      # order a direct dispatch would react to them (policies then sagas).
+      module Fanout
+        module_function
+
+        # One UID per event, kept off `Event#to_h` (parity/golden specs pin
+        # its shape) — policy and saga rows for the same event share it, which
+        # is what makes `delivery_id` mean "this fact, this consumer".
+        def rows_for(registry, events, domain)
+          uids = events.to_h { |event| [event, SecureRandom.uuid] }
+          events.flat_map do |event|
+            policies(registry, event, domain, uids[event]) + sagas(registry, event, domain, uids[event])
+          end
+        end
+
+        def policies(registry, event, domain, uid)
+          emitting = Naming.demodulise(event.aggregate)
+          Outbox.bluebooks_home_first(registry, domain).flat_map do |bluebook|
+            bluebook.policies.filter_map do |policy|
+              next unless reacts?(policy, event, emitting)
+
+              consumer = "policy:#{bluebook.name}::#{policy.name}"
+              row_for(event, domain, uid, consumer, kind_for(registry, policy, bluebook.name))
+            end
+          end
+        end
+
+        # Whether the policy answers this event, from the aggregate that emitted it.
+        def reacts?(policy, event, emitting)
+          policy.event_name == event.name && (policy.event_qualifier.nil? || policy.event_qualifier == emitting)
+        end
+
+        # A saga only ever reacts within its own domain.
+        def sagas(registry, event, domain, uid)
+          bluebook = registry.bluebook(domain)
+          return [] unless bluebook
+
+          bluebook.process_managers.select { |process_manager| listens?(process_manager, event) }.map do |process_manager|
+            row_for(event, domain, uid, "saga:#{bluebook.name}::#{process_manager.name}", "reaction")
+          end
+        end
+
+        def row_for(event, domain, uid, consumer, kind)
+          Outbox::Row.new(delivery_id: "#{uid}/#{consumer}", event_uid: uid, domain: domain, kind: kind,
+                          consumer: consumer, event: Outbox.serialize_event(event), status: "pending", attempts: 0)
+        end
+
+        def listens?(process_manager, event)
+          process_manager.starts_on == event.name || process_manager.ends_on == event.name ||
+            !process_manager.handler_for(event.name).nil?
+        end
+
+        # An "effect" is a reaction whose trigger resolves to an outbound port
+        # operation, claimed right before the adapter call and settled right
+        # after; everything else is a plain "reaction".
+        def kind_for(registry, policy, home_domain)
+          target = "#{policy.target_domain || home_domain}::#{policy.trigger_command}"
+          parsed = Naming.split_verb(target)
+          return "reaction" unless parsed
+
+          outbound_operation?(registry, parsed) ? "effect" : "reaction"
+        end
+
+        def outbound_operation?(registry, parsed)
+          target_domain, aggregate_name, path = parsed
+          head, rest = path.to_s.split(".", 2)
+          return false unless rest
+
+          aggregate = registry.bluebook(target_domain)&.aggregate(aggregate_name)
+          port = aggregate&.port(head)
+          port&.operation(rest)&.outbound?
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/outbox/relay.rb

@@ -0,0 +1,149 @@
+require_relative "consumer_runner"
+
+module Hecks
+  module Runtime
+    module Outbox
+      # One per Dispatcher: enqueues rows into a repository's outbox, drains
+      # them inline, and redrives whatever a crash left behind.
+      class Relay
+        include ConsumerRunner
+
+        attr_reader :registry, :log
+
+        # Additive and Ruby-only, unlike `saga_log`/`reaction_log`, which the
+        # Rust kernel ports byte-for-byte (spec/rust_conformance_spec.rb).
+        def initialize(registry)
+          @registry = registry
+          @log      = []
+        end
+
+        # Re-attaching (a second Dispatcher fronting the same registry) is
+        # safe: both dispatchers share this relay's log and every store.
+        def attach(policies:, sagas:)
+          @policies = policies
+          @sagas    = sagas
+          self
+        end
+
+        def attached? = !@policies.nil?
+
+        # Called inside the save transaction for command/entity paths, and
+        # outside one for port operations (which save nothing). Returns nil
+        # when the repository has no outbox — callers then react directly.
+        def enqueue(repository, events, domain)
+          return nil unless repository.outbox?
+          return [] if events.empty?
+
+          rows = Fanout.rows_for(@registry, events, domain)
+          rows.each { |row| row.aggregate = repository.aggregate.storage_name }
+          repository.outbox_enqueue(rows)
+        end
+
+        # `rows` nil means no outbox on this repository — react directly,
+        # the pre-outbox path.
+        def deliver(rows, events, domain, repository)
+          if rows.nil?
+            # Per event, in `emits` order — its policies, then its sagas
+            # (C10.2, docs/semantics/bluebook-semantics.md).
+            events.each do |event|
+              @policies.react(event, domain)
+              @sagas.advance(event, domain)
+            end
+            return
+          end
+
+          rows.each { |row| deliver_row(row, repository) }
+        end
+
+        # Claim, run the consumer, then settle. A failed claim means another
+        # relay already has this row.
+        def deliver_row(row, repository)
+          return false unless repository.outbox_claim(row.id)
+
+          row.status = "claimed"
+          settle_delivery(row, repository)
+        end
+
+        # Every row across every bound store, newest last.
+        def rows(status: nil)
+          stores.flat_map { |repository| repository.outbox_rows(status: status) }
+        end
+
+        # `pending` rows are always safe to redrive (never claimed yet).
+        # `claimed` rows are only surfaced — redelivering a maybe-already-run
+        # consumer needs an explicit `claimed: true`.
+        def redrive!(claimed: false)
+          stores.flat_map { |repository| redrive_store(repository, claimed) }
+        end
+
+        private
+
+        def settle_delivery(row, repository)
+          run_consumer(row)
+          repository.outbox_settle(row.id, status: "delivered")
+          row.status = "delivered"
+          true
+        rescue StandardError => e
+          settle_failed(row, repository, e)
+          false
+        end
+
+        # A DOMAIN_REFUSAL never reaches here (PolicyInterpreter and
+        # SagaInterpreter both rescue it as a recorded, undelivered
+        # reaction) — anything here is a defect in the relay's own path.
+        def settle_failed(row, repository, error)
+          repository.outbox_settle(row.id, status: "failed", error: "#{error.class}: #{error.message}")
+          row.status = "failed"
+          row.error  = "#{error.class}: #{error.message}"
+          @log << { outbox: row.delivery_id, consumer: row.consumer, delivered: false, defect: true,
+                    reason: row.error }
+        end
+
+        # The rows of one store that redrove: its pending rows first, then its claimed ones.
+        def redrive_store(repository, claimed)
+          redriven = repository.outbox_rows(status: "pending").select { |row| deliver_row(row, repository) }
+          redriven + repository.outbox_rows(status: "claimed").select { |row| redrive_claimed?(row, repository, claimed) }
+        end
+
+        def redrive_claimed?(row, repository, claimed)
+          unless claimed
+            warn_stalled(row)
+            return false
+          end
+
+          repository.outbox_settle(row.id, status: "pending")
+          row.status = "pending"
+          deliver_row(row, repository)
+        end
+
+        def warn_stalled(row)
+          warn stalled_wording(row)
+          @log << { outbox: row.delivery_id, consumer: row.consumer, kind: row.kind, stalled: true,
+                    event: row.event[:name], aggregate: row.event[:aggregate], id: row.event[:id] }
+        end
+
+        def stalled_wording(row)
+          "[hecks] outbox row #{row.delivery_id} (#{row.consumer} on #{row.event[:name]} for " \
+            "#{row.event[:aggregate]}##{row.event[:id]}) was claimed before the last crash/restart and never " \
+            "settled — its #{row.kind} may or may not have actually run. hecks does not auto-redrive a claimed " \
+            "row (the outcome is unknown, and redelivering it could double the effect); inspect it and " \
+            "redrive by hand with `runtime.outbox.redrive!(claimed: true)` once you know it is safe."
+        end
+
+        # Bluebooks, not hecksagons: a domain with no hecksagon is still
+        # bound to the default Memory adapter. An aggregate a hecksagon left
+        # unbound raises WiringError here and is skipped.
+        def stores
+          @registry.bluebooks.each_value.flat_map do |bluebook|
+            bluebook.aggregates.filter_map do |aggregate|
+              repository = @registry.repository(bluebook.name, aggregate)
+              repository if repository.outbox?
+            rescue WiringError
+              nil
+            end
+          end
+        end
+      end
+    end
+  end
+end