yes-core 1.2.0 → 2.2.0

data/lib/yes/core/commands/processor.rb

@@ -79,14 +79,13 @@ module Yes
         end
 
         # Executes a single command on its aggregate
-        # @param cmd [Command] the command to execute
-        # @return [Response] response from executing the command
+        # @param cmd [Command, Yes::Core::Commands::CommandGroup] the command to execute
+        # @return [Response, Yes::Core::Commands::CommandGroupResponse] response from executing the command
         def run_command(cmd)
           command_helper = Yes::Core::Commands::Helper.new(cmd)
           draft = draft?(cmd)
           aggregate = aggregate_class(cmd).new(cmd.aggregate_id, draft:)
           I18n.with_locale(command_helper.command_locale) do
-            # Pass payload as first argument, guards as option
             aggregate.public_send(command_helper.command_name, cmd.to_h, guards: !draft)
           end
         end
@@ -103,21 +102,43 @@ module Yes
         end
 
         # Checks if a guard evaluator exists for the given command
-        # @param cmd [Command] The command to check
+        #
+        # Aggregate-DSL command groups register their guard evaluator under a
+        # dedicated registry type, so they are resolved through a different
+        # configuration lookup than single commands.
+        #
+        # @param cmd [Command, Yes::Core::Commands::CommandGroup] The command to check
         # @return [Boolean] true if a guard evaluator exists
         # @raise [UnregisteredCommand] if no guard evaluator is found for the command
         def guard_evaluator_exists?(cmd)
           command_helper = Yes::Core::Commands::Helper.new(cmd)
 
-          klass = Yes::Core.configuration.guard_evaluator_class(command_helper.command_context,
-                                                                command_helper.subject,
-                                                                command_helper.command_name)
+          klass = guard_evaluator_class_for(cmd, command_helper)
 
           raise UnregisteredCommand, "Unregistered command: #{cmd.class}" unless klass
 
           true
         end
 
+        # Resolves the guard evaluator class for a command, dispatching to the
+        # command-group registry for {Yes::Core::Commands::CommandGroup} and to
+        # the single-command registry otherwise.
+        #
+        # @param cmd [Command, Yes::Core::Commands::CommandGroup] The command
+        # @param command_helper [Yes::Core::Commands::Helper] helper for the command
+        # @return [Class, nil] the registered guard evaluator class or nil
+        def guard_evaluator_class_for(cmd, command_helper)
+          if cmd.is_a?(Yes::Core::Commands::CommandGroup)
+            Yes::Core.configuration.command_group_guard_evaluator_class(command_helper.command_context,
+                                                                        command_helper.subject,
+                                                                        command_helper.command_name)
+          else
+            Yes::Core.configuration.guard_evaluator_class(command_helper.command_context,
+                                                          command_helper.subject,
+                                                          command_helper.command_name)
+          end
+        end
+
         # Ensures handlers exist for all commands
         # @param commands [Array<Command>] The commands to check
         # @return [Boolean] true if handlers exist for all commands

data/lib/yes/core/commands/stateless/handler.rb

@@ -118,7 +118,8 @@ module Yes
             PgEventstore.client.append_to_stream(
               stream,
               event,
-              options: { expected_revision: subject_stream_revision }
+              options: { expected_revision: subject_stream_revision },
+              middlewares: Middlewares.for_write
             ).tap { otl_record_response(_1) }
           end
           otl_trackable :publish_event, OpenTelemetry::OtlSpan::OtlData.new(span_name: 'Publish Event', span_kind: :producer)
@@ -198,7 +199,12 @@ module Yes
           # @param expected_revision [Integer]
           # @param stream [PgEventstore::Stream]
           def revision_error!(revision, expected_revision, stream)
-            PgEventstore::WrongExpectedRevisionError.new(revision:, expected_revision:, stream:).tap do |error|
+            # pg_eventstore 3.0 requires `verdict:`, which selects the error's
+            # message. verify_revisions! only calls this when the two revisions
+            # differ, which is exactly :unmatched_stream_revision.
+            PgEventstore::WrongExpectedRevisionError.new(
+              revision:, expected_revision:, stream:, verdict: :unmatched_stream_revision
+            ).tap do |error|
               self.class.current_span&.status = ::OpenTelemetry::Trace::Status.error('Wrong expected revision')
               self.class.current_span&.add_attributes(
                 {
@@ -277,7 +283,7 @@ module Yes
               timestamp: result.created_at,
               attributes: {
                 'event.type' => result.type,
-                'event.link_id' => result.link_id || '',
+                'event.link_global_position' => result.link_global_position || '',
                 'global_position' => result.global_position,
                 'stream' => result.stream.to_json,
                 'stream.revision' => result.stream_revision,

data/lib/yes/core/commands/stateless/handler_helpers.rb

@@ -287,7 +287,7 @@ module Yes
           # @return [Enumerator]
           def load_events(stream, options: {}, skip_decryption: true)
             options = { direction: 'Backwards' }.merge(options)
-            middlewares = Middlewares.without(:encryptor) if skip_decryption
+            middlewares = Middlewares.without(Middlewares::ENCRYPTOR) if skip_decryption
             PgEventstore.client.read_paginated(stream, options:, middlewares:)
           end
 

data/lib/yes/core/configuration.rb

@@ -200,6 +200,28 @@ module Yes
         register_aggregate_class(context_name, aggregate_name, command_name, :guard_evaluator, klass)
       end
 
+      # Register a command_group command class for a specific aggregate
+      # @param context_name [Symbol, String] The context for the aggregate
+      # @param aggregate_name [Symbol, String] The name of the aggregate
+      # @param group_name [Symbol, String] The name of the command group
+      # @param klass [Class] The generated CommandGroup subclass
+      # @example
+      #   register_command_group_class(:companies, :apprenticeship, :create_apprenticeship, klass)
+      def register_command_group_class(context_name, aggregate_name, group_name, klass)
+        register_aggregate_class(context_name, aggregate_name, group_name, :command_group, klass)
+      end
+
+      # Register a command_group guard evaluator class for a specific aggregate
+      # @param context_name [Symbol, String] The context for the aggregate
+      # @param aggregate_name [Symbol, String] The name of the aggregate
+      # @param group_name [Symbol, String] The name of the command group
+      # @param klass [Class] The generated GuardEvaluator subclass
+      # @example
+      #   register_command_group_guard_evaluator_class(:companies, :apprenticeship, :create_apprenticeship, klass)
+      def register_command_group_guard_evaluator_class(context_name, aggregate_name, group_name, klass)
+        register_aggregate_class(context_name, aggregate_name, group_name, :command_group_guard_evaluator, klass)
+      end
+
       # Register an aggregate authorizer class for a specific aggregate
       # @param context_name [Symbol, String] The context for the aggregate
       # @param aggregate_name [Symbol, String] The name of the aggregate
@@ -309,6 +331,23 @@ module Yes
         aggregate_class(context_name, aggregate_name, command_name.to_s.underscore.to_sym, :guard_evaluator)
       end
 
+      # Retrieve a guard evaluator class for a specific command group.
+      #
+      # Aggregate-DSL command groups register their guard evaluator under the
+      # dedicated `:command_group_guard_evaluator` type (see
+      # {#register_command_group_guard_evaluator_class}), not `:guard_evaluator`,
+      # so a group cannot be resolved through {#guard_evaluator_class}.
+      #
+      # @param context_name [Symbol, String] The context for the aggregate
+      # @param aggregate_name [Symbol, String] The name of the aggregate
+      # @param group_name [Symbol, String] The name of the command group
+      # @return [Class, nil] The registered guard evaluator class or nil if not found
+      # @example
+      #   evaluator = command_group_guard_evaluator_class(:companies, :apprenticeship, :create_apprenticeship)
+      def command_group_guard_evaluator_class(context_name, aggregate_name, group_name)
+        aggregate_class(context_name, aggregate_name, group_name.to_s.underscore.to_sym, :command_group_guard_evaluator)
+      end
+
       # List all registered classes across all aggregates and contexts
       # @return [Hash] A complete hash of all registered classes
       # @example

data/lib/yes/core/data_decryptor.rb

@@ -40,13 +40,13 @@ module Yes
       def decrypt_attributes(key:, data:, attributes: {}) # rubocop:disable Lint/UnusedMethodArgument
         return data unless key
 
-        res = key_repository.decrypt(key:, message: data['es_encrypted'])
+        res = key_repository.decrypt(key:, message: data[DataEncryptor::CIPHERTEXT_KEY])
         return data if res.failure?
 
         decrypted_text = res.value!
         decrypted = JSON.parse(decrypted_text.attributes[:message]).transform_keys(&:to_s)
         decrypted.each { |k, value| data[k] = value if data.key?(k) }
-        data.delete('es_encrypted')
+        data.delete(DataEncryptor::CIPHERTEXT_KEY)
         data
       end
 

data/lib/yes/core/data_encryptor.rb

@@ -10,6 +10,10 @@ module Yes
     #   encryptor.encrypted_data
     #   encryptor.encryption_metadata
     class DataEncryptor
+      # Data key holding the ciphertext of all encrypted attributes. Its presence means the data is
+      # currently encrypted: it is written here and removed by {DataDecryptor}.
+      CIPHERTEXT_KEY = 'es_encrypted'
+
       # @return [Hash] the encrypted data
       attr_reader :encrypted_data
 
@@ -51,8 +55,8 @@ module Yes
       def encrypt_attributes(key:, data:, attributes:)
         text = JSON.generate(data.select { |hash_key, _value| attributes.include?(hash_key.to_s) })
         encrypted = key_repository.encrypt(key:, message: text).value!
-        attributes.each { |att| data[att.to_s] = 'es_encrypted' if data.key?(att.to_s) }
-        data['es_encrypted'] = encrypted.attributes[:message]
+        attributes.each { |att| data[att.to_s] = CIPHERTEXT_KEY if data.key?(att.to_s) }
+        data[CIPHERTEXT_KEY] = encrypted.attributes[:message]
         data
       end
     end

data/lib/yes/core/failed_subscription_notifier.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    # Reports a permanently dead pg_eventstore subscription to Sentry.
+    #
+    # pg_eventstore calls its +failed_subscription_notifier+ exactly once, when a
+    # subscription exhausts its restarts and stays dead — it is the gem's only
+    # death signal, and without it that death is silent. Per-failure
+    # errors are only recorded on the subscription row, never raised into Sentry.
+    class FailedSubscriptionNotifier
+      # @param subscription [PgEventstore::Subscription]
+      # @param error [StandardError]
+      # @return [void]
+      def call(subscription, error)
+        Sentry.with_scope do |scope|
+          scope.set_tags(failed_subscription_notifier: true) # used in Sentry Alerts
+
+          Sentry.capture_exception(
+            error,
+            # a death report must never be swallowed by Sentry's excluded_exceptions
+            hint: { ignore_exclusions: true },
+            extra: { id: subscription.id, set: subscription.set, name: subscription.name }
+          )
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/middlewares/encryptor.rb

@@ -5,9 +5,12 @@ module Yes
     module Middlewares
       # PgEventstore middleware for encrypting/decrypting event data.
       #
+      # Register it through {Middlewares.register_encryptor} rather than by hand, so its write-only
+      # counterpart ({WriteEncryptor}) is always registered alongside it.
+      #
       # @example
       #   PgEventstore.configure do |config|
-      #     config.middlewares[:encryptor] = Yes::Core::Middlewares::Encryptor.new(key_repository)
+      #     Yes::Core::Middlewares.register_encryptor(key_repository, config:)
       #   end
       class Encryptor
         include PgEventstore::Middleware
@@ -24,6 +27,11 @@ module Yes
         # @return [PgEventstore::Event]
         def serialize(event)
           return event unless event.class.respond_to?(:encryption_schema)
+          # Idempotence guard. With {WriteEncryptor} registered, the DEFAULT middleware list holds two
+          # serialize-capable encryptors, so an append that omits `middlewares:` would encrypt twice. The
+          # second pass would encrypt the sentinels written by the first and overwrite the real ciphertext,
+          # which cannot be recovered. It also guards re-appending an event that was read at rest.
+          return event if event.data[DataEncryptor::CIPHERTEXT_KEY].present?
 
           encryptor = DataEncryptor.new(
             data: event.data, schema: event.class.encryption_schema, repository: key_repository

data/lib/yes/core/middlewares/write_encryptor.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module Middlewares
+      # Encrypts on the way in exactly like {Encryptor}, but does not decrypt on the way out.
+      #
+      # pg_eventstore 3.0 runs every registered middleware's #deserialize on the events returned by
+      # #append_to_stream, not only on the ones returned by reads. Nothing on the write path reads `data` off
+      # that returned event, so decrypting it costs two uncached HTTP calls to the encryptor service (a key
+      # lookup and a decrypt) per encrypted event, for a payload that is immediately discarded.
+      #
+      # #serialize is inherited rather than reimplemented on purpose: encryption at rest must never differ
+      # between the read and the write variant.
+      #
+      # Registered alongside {Encryptor} by {Middlewares.register_encryptor} and selected by
+      # {Middlewares.for_write}. The read path keeps using {Encryptor}, unchanged.
+      #
+      # @example
+      #   PgEventstore.client.append_to_stream(stream, event, middlewares: Yes::Core::Middlewares.for_write)
+      class WriteEncryptor < Encryptor
+        # Deliberately does nothing: the caller does not read the returned event's data.
+        #
+        # Returns the event rather than nil. pg_eventstore itself ignores the return value, but middlewares
+        # are also invoked directly in places that use it.
+        #
+        # @param event [PgEventstore::Event]
+        # @return [PgEventstore::Event]
+        def deserialize(event)
+          event
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/middlewares.rb

@@ -3,9 +3,54 @@
 module Yes
   module Core
     module Middlewares
+      # Config key of the encryptor used on read paths: encrypts on #serialize, decrypts on #deserialize.
+      ENCRYPTOR = :encryptor
+      # Config key of the encryptor used on write paths: encrypts on #serialize, no-op on #deserialize.
+      WRITE_ENCRYPTOR = :write_encryptor
+
       class << self
+        # Registers both encryptor middlewares against the same key repository.
+        #
+        # Always use this instead of assigning config.middlewares[:encryptor] by hand: registering the
+        # decrypting encryptor without its write-only twin silently doubles the encryptor round trips every
+        # encrypted append performs (see {WriteEncryptor}).
+        #
+        # Mutates the given config in place rather than opening its own PgEventstore.configure block, because
+        # PgEventstore.configure takes a non-reentrant mutex - nesting one inside another deadlocks.
+        #
+        # @param key_repository [#find, #create, #encrypt, #decrypt]
+        # @param config [PgEventstore::Config] the config yielded by PgEventstore.configure
+        # @return [void]
+        def register_encryptor(key_repository, config: PgEventstore.config)
+          config.middlewares[ENCRYPTOR] = Encryptor.new(key_repository)
+          config.middlewares[WRITE_ENCRYPTOR] = WriteEncryptor.new(key_repository)
+        end
+
+        # Middleware keys to pass to #append_to_stream: every configured middleware, with the decrypting
+        # encryptor swapped for the write-only one.
+        #
+        # Derived from the live config, never hard-coded. PgEventstore::Client resolves a passed list with
+        # `config.middlewares.slice(*list)`, which silently drops names that are not registered - so a literal
+        # list would resolve to one with NO encryptor at all against a config that registered it under a
+        # different key, and would write plaintext at rest undetectably. Deriving the list makes that
+        # impossible, and picks up any middleware added later for free.
+        #
+        # Falls back to the full list when {WRITE_ENCRYPTOR} is not registered. That is correct, just as slow
+        # as before - unlike a hard-coded list, which would drop encryption altogether.
+        #
+        # @return [Array<Symbol>]
+        def for_write
+          keys = PgEventstore.config.middlewares.keys
+          return keys unless keys.include?(WRITE_ENCRYPTOR)
+
+          keys - [ENCRYPTOR]
+        end
+
         # Returns middleware keys excluding the specified one.
         #
+        # Note that excluding {ENCRYPTOR} still yields a list containing {WRITE_ENCRYPTOR}, whose #deserialize
+        # is a no-op - so `without(:encryptor)` keeps meaning "read the data as it is stored".
+        #
         # @param middleware_name [Symbol] the middleware key to exclude
         # @return [Array<Symbol>] remaining middleware keys
         def without(middleware_name)

data/lib/yes/core/railtie.rb

@@ -16,6 +16,11 @@ module Yes
             with_indifferent_access: Yes::Core::Middlewares::WithIndifferentAccess.new,
             timestamp: Yes::Core::Middlewares::Timestamp.new
           }
+
+          # pg_eventstore's only death signal — without it a subscription that
+          # exhausts its restarts dies silently: per-failure errors are only recorded
+          # on the subscription row, never raised.
+          config.failed_subscription_notifier = FailedSubscriptionNotifier.new if defined?(Sentry)
         end
       end
 
@@ -49,6 +54,21 @@ module Yes
         PgEventstore.logger ||= Rails.logger if ENV['PG_ES_LOGGING'] == 'true'
       end
 
+      # The one misconfiguration Middlewares.for_write cannot fix by itself: a decrypting encryptor registered
+      # without its write-only twin. for_write then falls back to the full list, so writes stay CORRECT - they
+      # just keep paying an encryptor key lookup and decrypt per encrypted event, for data nobody reads.
+      # Warned about once at boot rather than on every append.
+      config.after_initialize do
+        middlewares = PgEventstore.config.middlewares
+        next unless middlewares.key?(Yes::Core::Middlewares::ENCRYPTOR)
+        next if middlewares.key?(Yes::Core::Middlewares::WRITE_ENCRYPTOR)
+
+        Rails.logger.warn(
+          'PgEventstore middleware :encryptor is registered without :write_encryptor, so append_to_stream ' \
+          'decrypts every event it returns. Register both with Yes::Core::Middlewares.register_encryptor.'
+        )
+      end
+
       # Load aggregate shortcuts when Rails console starts
       console do
         Yes::Core::Utils::AggregateShortcuts.load!

data/lib/yes/core/test_support/aggregate/command_test_dsl.rb

@@ -21,6 +21,28 @@ module Yes
         #     end
         #   end
         module CommandTestDsl
+          # Returns the event-type aggregate prefix that the runtime publishes
+          # for a given aggregate and draft flag. Mirrors
+          # `CommandUtils#aggregate_name_with_draft_suffix` so DSL-generated
+          # `expected_event_type` values match the runtime-published event
+          # types — including the case where `draftable changes_read_model:`
+          # was set explicitly, which makes the camelized read-model name the
+          # event-type prefix instead of the generic `<Aggregate>Draft`.
+          #
+          # @param aggregate_class [Class] The aggregate class under test
+          # @param draft [Boolean] Whether the test exercises a draft command
+          # @return [String] The event-type aggregate prefix
+          def self.expected_event_prefix(aggregate_class, draft:)
+            return aggregate_class.aggregate unless draft
+
+            if aggregate_class.respond_to?(:_changes_read_model_explicit) &&
+               aggregate_class._changes_read_model_explicit
+              aggregate_class.changes_read_model_name.camelize
+            else
+              "#{aggregate_class.aggregate}Draft"
+            end
+          end
+
           # Defines a test block for a command
           #
           # @param command_name [String, Symbol] the name of the command to test
@@ -41,8 +63,8 @@ module Yes
               end
               let(:command_data) { {} }
               let(:expected_event_type) do
-                "#{aggregate_class.context}::#{aggregate_class.aggregate}" \
-                  "#{'Draft' if draft}#{aggregate_class.commands[command].event_name.to_s.classify}"
+                prefix = CommandTestDsl.expected_event_prefix(aggregate_class, draft:)
+                "#{aggregate_class.context}::#{prefix}#{aggregate_class.commands[command].event_name.to_s.classify}"
               end
               let(:expected_event_data) { command_data_with_id }
               let(:expected_event_metadata) { nil }
@@ -99,6 +121,59 @@ module Yes
           def setup(&)
             before(&)
           end
+
+          # Defines a test block for a command group, mirroring {.command}.
+          #
+          # @param group_name [String, Symbol] the command_group name
+          # @param options [Array<Hash>] additional options (e.g., `draft: true`)
+          # @yield block for configuring test cases (success, invalid, no_change)
+          def command_group(group_name, *options, &block)
+            describe group_name.to_s, *options do
+              let(:draft) { options.first&.dig(:draft) }
+              let(:aggregate) { described_class.new(draft:) } unless method_defined?(:aggregate)
+
+              subject { aggregate.public_send(group, command_data) }
+
+              let(:group) { group_name.to_sym }
+              let(:aggregate_class) { aggregate.class }
+              let(:command_data) { {} }
+              let(:expected_event_types) do
+                prefix = CommandTestDsl.expected_event_prefix(aggregate_class, draft:)
+                aggregate_class.command_groups[group].sub_command_names.map do |sub_name|
+                  sub_event_name = aggregate_class.commands[sub_name].event_name.to_s.classify
+                  "#{aggregate_class.context}::#{prefix}#{sub_event_name}"
+                end
+              end
+              let(:success_attributes) { command_data.without(:locale) } unless method_defined?(:success_attributes)
+
+              class_eval(&block) if block_given?
+            end
+          end
+
+          # Defines a successful test for a command group.
+          def success_group(description = 'when successfully executing command group', options = {}, &block)
+            context description, options do
+              instance_eval(&block) if block_given?
+              it_behaves_like 'successful command group'
+            end
+          end
+
+          # Defines an invalid-transition test for a command group.
+          def invalid_group(description, options = {}, &block)
+            context "when #{description}", options do
+              instance_eval(&block) if block_given?
+              it_behaves_like 'invalid command group transition'
+            end
+          end
+
+          # Defines a no-change test for a command group.
+          def no_change_group(description = 'when command group causes no change', options = {}, &block)
+            context description.to_s, options do
+              instance_eval(&block) if block_given?
+              before { aggregate.public_send(group, command_data) }
+              it_behaves_like 'no change command group transition'
+            end
+          end
         end
       end
     end

data/lib/yes/core/test_support/aggregate/shared_examples.rb

@@ -75,3 +75,48 @@ RSpec.shared_examples 'no change transition' do
     )
   end
 end
+
+RSpec.shared_examples 'successful command group' do
+  it 'returns a successful CommandGroupResponse' do
+    expect(subject).to be_a(Yes::Core::Commands::CommandGroupResponse)
+    expect(subject).to be_success
+  end
+
+  it 'publishes one event per sub-command in declaration order' do
+    expect(subject.events.map(&:type)).to eq(expected_event_types)
+  end
+
+  it 'reflects the cumulative state on the read model' do
+    if success_attributes.any?
+      expect { subject }.to change {
+        aggregate.read_model.reload.attributes.to_h.symbolize_keys.slice(*success_attributes.keys)
+      }.to(success_attributes)
+    end
+  end
+end
+
+RSpec.shared_examples 'invalid command group transition' do
+  it 'returns an InvalidTransition error and no events' do
+    aggregate_failures do
+      expect(subject).not_to be_success
+      expect(subject.error).to be_a(Yes::Core::CommandHandling::GuardEvaluator::InvalidTransition)
+      expect(subject.events).to be_empty
+    end
+  end
+
+  it 'does not change the aggregate state' do
+    success_attributes.each_key do |attribute|
+      expect { subject }.not_to(change { aggregate.public_send(attribute) })
+    end
+  end
+end
+
+RSpec.shared_examples 'no change command group transition' do
+  it 'returns a NoChangeTransition error and no events' do
+    aggregate_failures do
+      expect(subject).not_to be_success
+      expect(subject.error).to be_a(Yes::Core::CommandHandling::GuardEvaluator::NoChangeTransition)
+      expect(subject.events).to be_empty
+    end
+  end
+end

data/lib/yes/core/test_support/event_helpers.rb

@@ -16,7 +16,7 @@ module Yes
         # @param event [Yes::Core::Event]
         # @return [void]
         def append_event(stream, event)
-          PgEventstore.client.append_to_stream(stream, event)
+          PgEventstore.client.append_to_stream(stream, event, middlewares: Yes::Core::Middlewares.for_write)
         end
 
         # Appends an event to a stream and reloads it

data/lib/yes/core/types.rb

@@ -20,7 +20,14 @@ module Yes
 
       EMPTY_STRING = /\A\s*\z/
 
-      UUID_REGEXP_BASE = /[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}/
+      # Version nibble is [1-8], not a hard-coded 4. pg_eventstore 3.0.0 moved event-id
+      # generation off the database's gen_random_uuid() (always v4) to
+      # SecureRandom.uuid_v7, and those ids reach us as causation_id / correlation_id.
+      # A v4-only pattern makes TransactionDetails raise Dry::Struct::Error, which fails
+      # the event handler and kills the subscription once its restarts run out.
+      #
+      # Still a real constraint, per RFC 9562: version 1-8 and variant nibble 8/9/a/b.
+      UUID_REGEXP_BASE = /[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}/
       UUID_REGEXP = /\A#{UUID_REGEXP_BASE}\z/i
 
       DATE_TIME_REGEXP = /\A\d{4}-\d{1,2}-\d{1,2} ([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?\z/i

data/lib/yes/core/utils/command_utils.rb

@@ -51,6 +51,27 @@ module Yes
           fetch_class(name, :guard_evaluator)
         end
 
+        # Builds a command_group instance for a given group name and flat payload.
+        # The aggregate_id is injected automatically.
+        #
+        # @param group_name [Symbol] The command group name
+        # @param payload [Hash] The flat / partially-nested input payload
+        # @return [Yes::Core::Commands::CommandGroup] The instantiated group command
+        # @raise [RuntimeError] If the command_group class cannot be found
+        def build_group_command(group_name, payload)
+          group_class = fetch_class(group_name, :command_group)
+          group_class.new("#{aggregate.underscore}_id": aggregate_id, **payload)
+        end
+
+        # Fetches the guard evaluator class for a given command group name.
+        #
+        # @param group_name [Symbol] The command group name
+        # @return [Class] The guard evaluator class
+        # @raise [RuntimeError] If the guard evaluator class cannot be found
+        def fetch_guard_evaluator_class_for_group(group_name)
+          fetch_class(group_name, :command_group_guard_evaluator)
+        end
+
         # Fetches the state updater class for a given command name
         #
         # @param name [Symbol] The command name

data/lib/yes/core/utils/hash_utils.rb

@@ -22,7 +22,8 @@ module Yes
             dupl
           end
 
-          # Returns a hash with the keys flattened
+          # Returns a hash with the keys flattened. Scalar, nested-hash and
+          # array values all honour the `prefix` consistently.
           #
           # @param obj [Hash, Array] the object to flatten
           # @param prefix [String] the key to use as a prefix for the keys in the hash
@@ -32,6 +33,10 @@ module Yes
           # @example
           #   HashUtils.deep_flatten_hash({ name: 'A', otl_contexts: { root: { attr: 10, available: true } } })
           #    => {"name"=>"A", "otl_contexts.root.attr"=>10, "otl_contexts.root.available"=>true}
+          #
+          # @example with a prefix (arrays included)
+          #   HashUtils.deep_flatten_hash({ id: 1, tags: [{ k: 'v' }] }, 'span')
+          #    => {"span.id"=>1, "span.tags"=>[{"k"=>"v"}]}
           def deep_flatten_hash(obj, prefix = nil, memo = {})
             case obj
             when Hash
@@ -42,7 +47,7 @@ module Yes
                 in String | Symbol, Hash
                   deep_flatten_hash(value, prefix ? "#{prefix}.#{key}" : key.to_s, memo)
                 in String | Symbol, Array
-                  memo[key.to_s] = deep_flatten_hash(value)
+                  memo[prefix ? "#{prefix}.#{key}" : key.to_s] = deep_flatten_hash(value)
                 in Array, _
                   memo[deep_flatten_hash(key)] = deep_flatten_hash(value)
                 else

data/lib/yes/core/version.rb

@@ -2,6 +2,6 @@
 
 module Yes
   module Core
-    VERSION = '1.2.0'
+    VERSION = '2.2.0'
   end
 end