yes-core 1.1.0 → 1.3.0

data/lib/yes/core/command_handling/command_group_executor.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module CommandHandling
+      # Low-level executor for command groups.
+      #
+      # Mirrors {CommandExecutor}, with two key differences:
+      #
+      # 1. Sub-command events publish inside a single
+      #    `PgEventstore.client.multiple` block, so either all events commit
+      #    atomically or none do.
+      # 2. Read-model updates run AFTER the eventstore commit succeeds, in
+      #    declaration order, so a rolled-back transaction never leaves the
+      #    read model ahead of the stream.
+      #
+      # Only the group's own guards run here — sub-command guards are
+      # bypassed by design.
+      class CommandGroupExecutor
+        MAX_RETRIES = 10
+        INLINE_RECOVERY_RETRY_THRESHOLD = 5
+
+        # @param aggregate [Yes::Core::Aggregate]
+        def initialize(aggregate)
+          @aggregate = aggregate
+          @read_model = aggregate.read_model if aggregate.class.read_model_enabled?
+        end
+
+        # @param cmd [Yes::Core::Commands::CommandGroup]
+        # @param group_name [Symbol]
+        # @param guard_evaluator_class [Class]
+        # @param skip_guards [Boolean]
+        # @return [Yes::Core::Commands::CommandGroupResponse]
+        def call(cmd, group_name, guard_evaluator_class, skip_guards: false)
+          retries = 0
+
+          begin
+            evaluator = GuardRunner.new(aggregate).call(cmd, group_name, guard_evaluator_class, skip_guards:)
+            external_aggregates = evaluator&.accessed_external_aggregates || []
+
+            set_pending_update_state if aggregate.class.read_model_enabled?
+
+            events = publish_events(cmd, external_aggregates)
+            apply_read_model_updates(cmd, events) if aggregate.class.read_model_enabled?
+
+            Yes::Core::Commands::CommandGroupResponse.new(cmd:, events:)
+          rescue PgEventstore::WrongExpectedRevisionError => e
+            retries += 1
+            clear_pending_update_state if aggregate.class.read_model_enabled?
+            retries <= MAX_RETRIES ? retry : raise(e)
+          rescue ConcurrentUpdateError => e
+            retries += 1
+            sleep([0.01 * (2**(retries - 1)), 1.0].min) if retries <= MAX_RETRIES
+
+            if aggregate.class.read_model_enabled? && retries >= INLINE_RECOVERY_RETRY_THRESHOLD
+              ReadModelRecoveryService.attempt_inline_recovery(read_model, aggregate: aggregate)
+              read_model.reload
+            end
+
+            retries <= MAX_RETRIES ? retry : raise(e)
+          rescue GuardEvaluator::InvalidTransition,
+                 GuardEvaluator::NoChangeTransition,
+                 Yes::Core::Command::Invalid => e
+            clear_pending_update_state if aggregate.class.read_model_enabled?
+            Yes::Core::Commands::CommandGroupResponse.new(cmd:, error: e)
+          end
+        end
+
+        private
+
+        attr_reader :aggregate, :read_model
+
+        # Publishes each sub-command's event inside a single eventstore
+        # transaction. If publishing fails partway through, the whole
+        # transaction rolls back via PgEventstore::Commands::Multiple.
+        #
+        # The FIRST sub-event goes through {EventPublisher}, which performs
+        # two concurrency checks that bring group flow up to parity with the
+        # per-command flow:
+        #
+        #   1. **Own-stream optimistic locking** — `expected_revision` is
+        #      derived from `read_model.revision` (or the latest stream
+        #      revision when read models are disabled), so a concurrent
+        #      writer that committed to the same stream between guard
+        #      evaluation and publish raises `WrongExpectedRevisionError`,
+        #      which the outer rescue retries and re-runs guards against the
+        #      fresh state.
+        #   2. **External-aggregate revision verification** —
+        #      `verify_external_revisions!` checks every aggregate that the
+        #      group's guard block touched (tracked by
+        #      {AggregateTracker} via {GuardEvaluator}#method_missing and
+        #      {PayloadProxy}#resolve_aggregate). A drifted external stream
+        #      raises `WrongExpectedRevisionError`, same retry path.
+        #
+        # SUBSEQUENT sub-events go through the direct append path with
+        # `expected_revision: :any`. They don't need their own optimistic
+        # check because:
+        #   - they're inside the same `multiple` block / PG transaction at
+        #     serializable isolation,
+        #   - any concurrent writer that committed during this transaction
+        #     would have failed step 1 above (or surfaced as
+        #     `PG::TRSerializationFailure`, which pg_eventstore retries
+        #     transparently for the whole block),
+        #   - their stream revisions chain naturally onto the first append
+        #     because each `Append` reads `stream_revision` fresh inside the
+        #     same transaction and sees the previous appends.
+        #
+        # We assign `published` from inside the block so pg_eventstore's
+        # internal retry on `MissingPartitions` / serialization failures
+        # doesn't accumulate duplicate event entries across retries.
+        #
+        # Pending-state cleanup is handled exclusively by the outer rescue
+        # chain in {#call} so that `ConcurrentUpdateError`'s "another process
+        # owns it" semantics are preserved.
+        #
+        # @param cmd [Yes::Core::Commands::CommandGroup]
+        # @param external_aggregates [Array<Hash>] aggregates accessed during
+        #   guard evaluation; verified against their current stream revisions
+        #   at publish time
+        # @return [Array<PgEventstore::Event>]
+        def publish_events(cmd, external_aggregates)
+          published = nil
+          PgEventstore.client.multiple do
+            published = cmd.commands.each_with_index.map do |sub_cmd, index|
+              if index.zero?
+                publish_first_sub_event(sub_cmd, external_aggregates)
+              else
+                publish_subsequent_sub_event(sub_cmd)
+              end
+            end
+          end
+          published
+        end
+
+        # Publishes the first sub-event via {EventPublisher}, getting both
+        # own-stream optimistic locking and external-aggregate revision
+        # verification for free.
+        #
+        # @param sub_cmd [Yes::Core::Command]
+        # @param external_aggregates [Array<Hash>]
+        # @return [PgEventstore::Event]
+        def publish_first_sub_event(sub_cmd, external_aggregates)
+          EventPublisher.new(
+            command: sub_cmd,
+            aggregate_data: EventPublisher::AggregateEventPublicationData.from_aggregate(aggregate),
+            accessed_external_aggregates: external_aggregates
+          ).call
+        end
+
+        # Publishes a subsequent (2nd+) sub-event with `expected_revision: :any`.
+        # Atomicity and revision sequencing are guaranteed by the surrounding
+        # `multiple` block — see {#publish_events} docstring for details.
+        #
+        # @param sub_cmd [Yes::Core::Command]
+        # @return [PgEventstore::Event]
+        def publish_subsequent_sub_event(sub_cmd)
+          utils = Utils::CommandUtils.new(
+            context: aggregate.class.context,
+            aggregate: aggregate.class.aggregate,
+            aggregate_id: aggregate.id
+          )
+          sub_command_name = sub_cmd.class.name.split('::')[-2].underscore.to_sym
+          event = utils.build_event(
+            command_name: sub_command_name,
+            payload: sub_cmd.payload,
+            metadata: sub_event_metadata(sub_cmd)
+          )
+
+          PgEventstore.client.append_to_stream(
+            utils.build_stream(metadata: sub_cmd.metadata || {}),
+            event,
+            options: { expected_revision: :any }
+          )
+        end
+
+        def sub_event_metadata(sub_cmd)
+          meta = {}
+          meta['origin'] = sub_cmd.origin if sub_cmd.origin.present?
+          meta['batch_id'] = sub_cmd.batch_id if sub_cmd.batch_id.present?
+          meta['yes-dsl'] = true
+          meta.merge!(sub_cmd.metadata) if sub_cmd.metadata.present?
+          meta.merge!(sub_cmd.transaction.for_eventstore_metadata) if sub_cmd.transaction
+          meta.deep_transform_keys(&:to_s)
+        end
+
+        # Applies read-model updates for each (sub_cmd, event) pair in
+        # declaration order, so each sub-command's state-updater sees the
+        # state produced by the previous one.
+        #
+        # Intentionally NOT wrapped in an outer `ActiveRecord::Base.transaction`:
+        # if the third sub-command's read-model update raises after the first
+        # two succeed, the read model is left half-applied while the
+        # eventstore stream is fully committed. This matches today's behaviour
+        # for single commands (where any read-model failure after the event
+        # publishes leaves the read model behind the stream) and is healed by
+        # the standard event-replay/recovery path. An outer AR transaction
+        # could be added as a follow-up if partial application becomes a
+        # concrete problem in practice.
+        #
+        # @param cmd [Yes::Core::Commands::CommandGroup]
+        # @param events [Array<PgEventstore::Event>]
+        # @return [void]
+        def apply_read_model_updates(cmd, events)
+          cmd.commands.zip(events, cmd.class.sub_command_names).each do |sub_cmd, event, sub_name|
+            ReadModelUpdater.new(aggregate).call(event, sub_cmd.payload, sub_name)
+          end
+        end
+
+        # @see CommandExecutor#set_pending_update_state
+        def set_pending_update_state
+          return unless read_model
+
+          begin
+            ActiveRecord::Base.transaction(requires_new: true) do
+              read_model.update_column(:pending_update_since, Time.current)
+            end
+          rescue ActiveRecord::StatementInvalid => e
+            raise e unless e.message.include?('Concurrent pending update not allowed')
+
+            raise ConcurrentUpdateError.new(
+              aggregate_class: aggregate.class,
+              aggregate_id: read_model.id,
+              original_error: e
+            )
+          end
+        end
+
+        def clear_pending_update_state
+          return unless read_model
+
+          read_model.update_column(:pending_update_since, nil)
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/command_handling/command_group_handler.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module CommandHandling
+      # High-level orchestrator for executing a {Yes::Core::Commands::CommandGroup}.
+      #
+      # Mirrors {CommandHandler} but produces a
+      # {Yes::Core::Commands::CommandGroupResponse} carrying the array of
+      # published events. Group-level guards run; sub-command guards are
+      # bypassed (the executor publishes each sub-command's event directly).
+      #
+      # @example
+      #   handler = CommandGroupHandler.new(aggregate)
+      #   response = handler.call(:create_apprenticeship, {
+      #     company_id:, user_id:, name:, description:
+      #   })
+      class CommandGroupHandler
+        include Yes::Core::OpenTelemetry::Trackable
+
+        # @param aggregate [Yes::Core::Aggregate]
+        def initialize(aggregate)
+          @aggregate = aggregate
+          @command_utilities = aggregate.send(:command_utilities)
+          @read_model = aggregate.read_model if aggregate.class.read_model_enabled?
+        end
+
+        # Executes a command group and updates the aggregate's read model.
+        #
+        # @param group_name [Symbol] the command group name
+        # @param payload [Hash] flat / partially-nested input payload
+        # @param guards [Boolean] whether to evaluate the group's guards
+        # @param metadata [Hash, nil] optional metadata to merge into each event
+        # @return [Yes::Core::Commands::CommandGroupResponse]
+        def call(group_name, payload, guards: true, metadata: nil)
+          prepared = prepare_payload(payload, metadata)
+          cmd = command_utilities.build_group_command(group_name, prepared)
+          guard_evaluator_class = command_utilities.fetch_guard_evaluator_class_for_group(group_name)
+
+          ReadModelRecoveryService.check_and_recover_with_retries(read_model, aggregate:) if aggregate.class.read_model_enabled?
+
+          CommandGroupExecutor.new(aggregate).
+            call(cmd, group_name, guard_evaluator_class, skip_guards: !guards)
+        end
+        otl_trackable :call,
+                      Yes::Core::OpenTelemetry::OtlSpan::OtlData.new(span_name: 'Execute command group')
+
+        private
+
+        attr_reader :aggregate, :command_utilities, :read_model
+
+        # Prepares the payload before constructing the group command.
+        # Mirrors the metadata-injection logic in {CommandHandler#prepare_payload}.
+        #
+        # @param payload [Hash]
+        # @param metadata [Hash, nil]
+        # @return [Hash]
+        def prepare_payload(payload, metadata)
+          payload = payload.is_a?(Hash) ? payload.dup : {}
+
+          add_console_origin(payload)
+          add_draft_metadata(payload) if aggregate.draft?
+          add_custom_metadata(payload, metadata)
+
+          payload
+        end
+
+        def add_console_origin(payload)
+          return if payload[:origin].present?
+
+          console_origin = Utils::CallerUtils.console_origin
+          payload[:origin] = console_origin if console_origin
+        end
+
+        def add_draft_metadata(payload)
+          payload[:metadata] ||= {}
+          payload[:metadata][:draft] = true
+        end
+
+        def add_custom_metadata(payload, metadata)
+          return if metadata.blank?
+
+          payload[:metadata] ||= {}
+          payload[:metadata].merge!(metadata)
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/command_handling/guard_evaluator.rb

@@ -52,6 +52,7 @@ module Yes
         # @raise [InvalidTransition] When a guard fails with an invalid transition
         # @raise [NoChangeTransition] When a guard fails with a no change transition
         def call
+          check_not_removed!
           self.class.guards.each do |name, guard_data|
             evaluate_guard(name, error_extra: guard_data[:error_extra], block: guard_data[:block])
           end
@@ -64,6 +65,28 @@ module Yes
 
         attr_reader :raw_payload, :raw_metadata, :payload, :aggregate, :aggregate_tracker, :command_name
 
+        # Pre-check that fires before any registered guard. Blocks every command on a removable
+        # aggregate once `removed_at` (or the configured attr) has been set, except where the
+        # command opts out via `skip_default_guards: %i[not_removed]`.
+        #
+        # The check runs ahead of the user-defined guards (including the auto-injected `:no_change`)
+        # so post-remove mutations consistently surface "X has been removed" instead of misleading
+        # downstream errors like "X does not change".
+        #
+        # @return [void]
+        # @raise [InvalidTransition] When the aggregate has been removed and the command is not opted out.
+        def check_not_removed!
+          config = aggregate.class.respond_to?(:removable_config) ? aggregate.class.removable_config : nil
+          return unless config && config[:not_removed_guards]
+
+          command_data = aggregate.class.commands[command_name]
+          return if command_data&.skip_default_guards&.include?(:not_removed)
+
+          return if aggregate.public_send(config[:attr_name]).blank?
+
+          raise InvalidTransition, error_message(:not_removed)
+        end
+
         # Evaluates a single guard and raises appropriate error if it fails
         #
         # @param name [Symbol] The name of the guard

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

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module Commands
+      # Base class for aggregate-DSL command groups.
+      #
+      # A {CommandGroup} represents a compound, transactional action declared
+      # inside an aggregate via the `command_group :name do … end` macro. It
+      # references its sub-commands by symbol (not by class constant) so
+      # declaration order in the aggregate body does not matter — resolution
+      # happens lazily against the Yes configuration registry.
+      #
+      # The legacy {Yes::Core::Commands::Group} is intentionally untouched and
+      # continues to serve the stateless command flow.
+      class CommandGroup
+        # Reuse the legacy Group's reserved-key Attributes struct — the shape
+        # is identical for both group flavours.
+        Attributes = Yes::Core::Commands::Group::Attributes
+
+        class << self
+          # @return [String] the group's owning context, e.g. "Companies"
+          attr_accessor :context
+
+          # @return [String] the group's owning aggregate, e.g. "Apprenticeship"
+          attr_accessor :aggregate
+
+          # @return [Symbol] the group's name as defined by `command_group :name`
+          attr_accessor :group_name
+
+          # @return [Array<Symbol>] ordered list of sub-command names referenced
+          #   by the group; execution order matches this list
+          attr_writer :sub_command_names
+
+          def sub_command_names
+            @sub_command_names ||= []
+          end
+
+          # @return [Symbol] the own context as a snake-cased symbol
+          def own_context
+            context.to_s.underscore.to_sym
+          end
+
+          # @return [Symbol] the own subject (aggregate name) as a snake-cased symbol
+          def own_subject
+            aggregate.to_s.underscore.to_sym
+          end
+
+          # Resolves the sub-command classes lazily so declaration order in the
+          # aggregate body does not matter.
+          #
+          # @return [Array<Class>] sub-command classes in declaration order
+          def sub_command_classes
+            sub_command_names.map do |name|
+              Yes::Core.configuration.aggregate_class(context, aggregate, name, :command) ||
+                raise(ArgumentError, "Sub-command '#{name}' is not defined on #{context}::#{aggregate}")
+            end
+          end
+
+          # @return [Array<Symbol>] unique contexts of all sub-commands
+          def command_contexts
+            sub_command_classes.map { |c| c.name.split('::').first.underscore.to_sym }.uniq
+          end
+
+          # @return [Array<Symbol>] subjects in the own context
+          def own_context_subjects
+            sub_command_classes.
+              select { |c| c.name.split('::').first.underscore.to_sym == own_context }.
+              map    { |c| c.name.split('::')[1].underscore.to_sym }.
+              uniq
+          end
+        end
+
+        # @return [Hash] the flat input payload (reserved keys stripped). This
+        #   is what guard blocks see via `payload.<attr>` through PayloadProxy.
+        attr_reader :payload
+
+        # @return [Hash] the payload normalized into per-context/per-subject
+        #   buckets. Used internally to construct sub-command instances and
+        #   exposed so callers can introspect the group's per-sub-command shape.
+        attr_reader :normalized_payload
+
+        # @return [Attributes] the reserved-key attributes of the group
+        attr_reader :group_attributes
+
+        # @return [Array<Yes::Core::Command>] sub-command instances in execution order
+        attr_reader :commands
+
+        delegate :transaction, :origin, :batch_id, :metadata, :command_id, to: :group_attributes
+
+        # @return [String, nil] the aggregate ID derived from the first sub-command
+        def aggregate_id
+          commands.first&.aggregate_id
+        end
+
+        # @param params [Hash] flat / partially-nested input payload, optionally
+        #   carrying reserved keys (transaction, origin, batch_id, metadata,
+        #   command_id, es_encrypted)
+        def initialize(params)
+          @group_attributes = Attributes.new(params.slice(*Yes::Core::Command::RESERVED_KEYS))
+          @payload = params.except(*Yes::Core::Command::RESERVED_KEYS).symbolize_keys
+          @normalized_payload = GroupPayloadNormalizer.call(
+            params,
+            command_contexts: self.class.command_contexts,
+            own_context_subjects: self.class.own_context_subjects,
+            own_context: self.class.own_context,
+            own_subject: self.class.own_subject
+          )
+          @commands = build_commands
+        end
+
+        # @return [Hash] hash form for serialization, merging normalized payload
+        #   and reserved keys (matches legacy {Yes::Core::Commands::Group#to_h})
+        def to_h
+          merged = normalized_payload.merge(group_attributes.to_h)
+          transaction ? merged.merge(transaction:) : merged
+        end
+
+        private
+
+        # @return [Array<Yes::Core::Command>] sub-command instances populated with
+        #   the matching payload subset and the propagated reserved keys
+        def build_commands
+          self.class.sub_command_classes.map do |klass|
+            sub_context = klass.name.split('::').first.underscore.to_sym
+            sub_subject = klass.name.split('::')[1].underscore.to_sym
+            subject_payload = normalized_payload.dig(sub_context, sub_subject) || {}
+            attribute_payload = subject_payload.slice(*klass.attribute_names)
+            klass.new(attribute_payload.merge(propagated_reserved_keys))
+          end
+        end
+
+        # @return [Hash] reserved keys (excluding command_id) shared with each
+        #   sub-command; command_id is intentionally omitted so each sub-command
+        #   gets its own auto-generated ID via {Yes::Core::Command}'s default
+        def propagated_reserved_keys
+          {
+            transaction: transaction,
+            origin: origin,
+            batch_id: batch_id,
+            metadata: metadata
+          }.compact
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module Commands
+      # Response returned by {Yes::Core::CommandHandling::CommandGroupHandler}.
+      #
+      # Mirrors the surface of {Yes::Core::Commands::Response} (success?,
+      # error_details, type, to_notification) but carries an array of
+      # published events instead of a single one — one per sub-command in the
+      # group.
+      class CommandGroupResponse < Dry::Struct
+        attribute :cmd, Yes::Core::Types.Instance(Yes::Core::Commands::CommandGroup)
+        attribute :events,
+                  Yes::Core::Types::Array.of(
+                    Yes::Core::Types.Instance(PgEventstore::Event)
+                  ).default([].freeze)
+        attribute? :error,
+                   Yes::Core::Types.Instance(Yes::Core::CommandHandling::GuardEvaluator::TransitionError).
+                     optional
+
+        delegate :transaction, :batch_id, :payload, :metadata, to: :cmd
+
+        # @return [Boolean] true when no error is attached
+        def success?
+          error.blank?
+        end
+
+        # @return [Hash] structured error info, or empty when successful
+        def error_details
+          return {} unless error
+
+          {
+            message: error.message,
+            type: error.message&.underscore&.tr(' ', '_'),
+            extra: (error.extra if error.respond_to?(:extra) && error.extra.present?)
+          }.compact
+        end
+
+        # @return [String] the response type tag
+        def type
+          success? ? 'command_success' : 'command_error'
+        end
+
+        # @return [Hash] notification-shaped hash for downstream consumers
+        def to_notification
+          error_payload = success? ? {} : { error_details: }
+          {
+            type:,
+            batch_id:,
+            payload:,
+            metadata:,
+            command: cmd.class.name,
+            id: cmd.command_id,
+            transaction: transaction.to_h
+          }.merge(error_payload)
+        end
+
+        # @return [Hash] JSON-friendly representation
+        def as_json(*)
+          to_notification.as_json
+        end
+      end
+    end
+  end
+end

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

@@ -116,18 +116,13 @@ module Yes
         # @param params [Hash] the input parameters
         # @return [Hash] the normalized payloads
         def normalized_payloads(params)
-          params.without(RESERVED_KEYS).each_with_object({}) do |(key, value), norm_payloads|
-            if key.in?(self.class.command_contexts)
-              norm_payloads[key] = value
-            elsif key.in?(self.class.own_context_subjects)
-              norm_payloads[self.class.own_context] ||= {}
-              norm_payloads[self.class.own_context][key] = value
-            else
-              norm_payloads[self.class.own_context] ||= {}
-              norm_payloads[self.class.own_context][self.class.own_subject] ||= {}
-              norm_payloads[self.class.own_context][self.class.own_subject][key] = value
-            end
-          end
+          GroupPayloadNormalizer.call(
+            params,
+            command_contexts: self.class.command_contexts,
+            own_context_subjects: self.class.own_context_subjects,
+            own_context: self.class.own_context,
+            own_subject: self.class.own_subject
+          )
         end
       end
     end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module Commands
+      # Normalizes a flat or partially-nested input hash into the per-context /
+      # per-subject shape expected by a command group's sub-commands.
+      #
+      # Supports three input forms simultaneously:
+      #   * keys that match a command context are passed through verbatim,
+      #   * keys that match a subject of the own context are nested one level
+      #     under the own context,
+      #   * any other key is nested two levels under
+      #     <own_context>.<own_subject>.
+      #
+      # This is the shared payload-shaping primitive for
+      # {Yes::Core::Commands::Group} (legacy stateless flow) and
+      # {Yes::Core::Commands::CommandGroup} (aggregate-DSL flow).
+      module GroupPayloadNormalizer
+        # @param params [Hash] the raw input hash, including reserved keys
+        # @param command_contexts [Array<Symbol>] unique contexts of all
+        #   commands in the group
+        # @param own_context_subjects [Array<Symbol>] subjects in the group's
+        #   own context
+        # @param own_context [Symbol] the group's own context
+        # @param own_subject [Symbol] the group's own subject
+        # @return [Hash] the normalized payload (reserved keys stripped)
+        def self.call(params, command_contexts:, own_context_subjects:, own_context:, own_subject:)
+          params.without(*Yes::Core::Command::RESERVED_KEYS).each_with_object({}) do |(key, value), out|
+            if command_contexts.include?(key)
+              out[key] = value
+            elsif own_context_subjects.include?(key)
+              out[own_context] ||= {}
+              out[own_context][key] = value
+            else
+              out[own_context] ||= {}
+              out[own_context][own_subject] ||= {}
+              out[own_context][own_subject][key] = value
+            end
+          end
+        end
+      end
+    end
+  end
+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