yes-core 1.2.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 684a9c20dfd17ba779b196a7b294b93e04bf531bcc3d31a2adc9f8a4d645b7dd
-  data.tar.gz: 43e482658ce60a8c7fe4eb5f73f3bf084169857bd06a57a01aadf5ab7cf98e76
+  metadata.gz: 4845d0466658aee907edb5bab0679603e25a9b5c088a8df067d0fbfcc060bff4
+  data.tar.gz: cca505e973fa99d5b8e4b07c44752b78b330fdc0035b45528c83139ee36a0e4b
 SHA512:
-  metadata.gz: 335785676b2baef08117225b60c3a3b170bb39b0c3fe8ffdfa2781c158944b562f53d00884f409fb0c07c15ace4b513c02bd042973da57118ec325701a258acb
-  data.tar.gz: 72bc5b16b03b00ddc6211806d2566ad5213a25e452836e1ffd09f1e89c10154e98e47edb5ac75573092b1c21ea13cc38f5f49f379f418c2e08c2532d2e498670
+  metadata.gz: '08121024f7bb36c1bb17281d772c907f4c1e9c119437caf6642c0461fcc9ce2d434c15fa6dc548ec8c6362b520b5144f8869d7054c8e9a110e33a984d757fd63'
+  data.tar.gz: b2b2bcbf061918d7876e27c6014d41adfe1ed5133163a078d09a31490219105a57f47699c5bd2d6c9d3400c12df527c13e2d0f76d64b32f1d4a2b1aaec1b4b8f

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [2.2.0] - 2026-09-01
+
+- See root CHANGELOG.md for details.
+
+## [1.4.0] - 2026-06-24
+
+- See root CHANGELOG.md for details.
+
+## [1.3.1] - 2026-06-16
+
+- See root CHANGELOG.md for details.
+
+## [1.3.0] - 2026-05-18
+
+- See root CHANGELOG.md for details.
+
 ## [1.2.0] - 2026-04-30
 
 - See root CHANGELOG.md for details.

data/README.md

@@ -2,6 +2,19 @@
 
 Core event sourcing framework providing the aggregate DSL, commands, events, read models, and supporting infrastructure for the [Yes](https://github.com/yousty/yes) framework.
 
+## Compatibility with pg_eventstore
+
+⚠️ **pg_eventstore 3.x requires yes-core >= 2.1.1.** pg_eventstore 3.0.0 generates event
+ids with `SecureRandom.uuid_v7` (it moved the default off the database's
+`gen_random_uuid()`, which always produced v4). Those ids arrive as `causation_id` /
+`correlation_id`, and `Types::UUID` accepted only v4 before 2.1.1 — so
+`TransactionDetails.new` raised `Dry::Struct::Error`, the event handler failed, and the
+subscription died once its restarts ran out.
+
+`Types::UUID` now accepts any RFC 9562 version (1-8) while still requiring a valid
+version and variant nibble.
+
+
 ## Installation
 
 Add this line to your application's Gemfile:

data/lib/yes/core/active_job_serializers/command_group_serializer.rb

@@ -3,22 +3,25 @@
 module Yes
   module Core
     module ActiveJobSerializers
-      # ActiveJob serializer for CommandGroup objects.
+      # ActiveJob serializer for {Yes::Core::Commands::Group} (legacy stateless
+      # cross-aggregate groups) and {Yes::Core::Commands::CommandGroup}
+      # (aggregate-DSL groups). Both round-trip through `to_h` / `Class.new`.
       class CommandGroupSerializer < ActiveJob::Serializers::ObjectSerializer
         # @param argument [Object] the argument to check
         # @return [Boolean] true if the argument can be serialized
         def serialize?(argument)
-          argument.is_a? Yes::Core::Commands::Group
+          argument.is_a?(Yes::Core::Commands::Group) ||
+            argument.is_a?(Yes::Core::Commands::CommandGroup)
         end
 
-        # @param command_group [Yes::Core::Commands::Group] the command group to serialize
+        # @param command_group [Yes::Core::Commands::Group, Yes::Core::Commands::CommandGroup]
         # @return [Hash] the serialized representation
         def serialize(command_group)
           super(command_group.to_h.merge(_type: command_group.class.name))
         end
 
         # @param hash [Hash] the serialized representation
-        # @return [Yes::Core::Commands::Group] the deserialized command group
+        # @return [Yes::Core::Commands::Group, Yes::Core::Commands::CommandGroup]
         def deserialize(hash)
           symbolized_hash = hash.deep_symbolize_keys
           Object.const_get(symbolized_hash[:_type]).new(symbolized_hash.except(:_aj_serialized, :_type))

data/lib/yes/core/aggregate/dsl/class_name_convention.rb

@@ -43,6 +43,14 @@ module Yes
             "#{context}::#{aggregate}::Commands::#{name.to_s.camelize}::GuardEvaluator"
           end
 
+          def command_group_class_name(name)
+            "#{context}::#{aggregate}::CommandGroups::#{name.to_s.camelize}::Command"
+          end
+
+          def command_group_guard_evaluator_class_name(name)
+            "#{context}::#{aggregate}::CommandGroups::#{name.to_s.camelize}::GuardEvaluator"
+          end
+
           def state_updater_class_name(name)
             "#{context}::#{aggregate}::Commands::#{name.to_s.camelize}::StateUpdater"
           end

data/lib/yes/core/aggregate/dsl/class_resolvers/command_group/base.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    class Aggregate
+      module Dsl
+        module ClassResolvers
+          module CommandGroup
+            # Base class for command_group-related class resolvers.
+            #
+            # Mirrors {ClassResolvers::Command::Base} but binds to
+            # {CommandGroupData} instead of {CommandData}.
+            #
+            # @abstract Subclass and implement {ClassResolvers::Base#class_type},
+            #   {ClassResolvers::Base#class_name}, and
+            #   {ClassResolvers::Base#generate_class}.
+            class Base < ClassResolvers::Base
+              # @param command_group_data [Yes::Core::Aggregate::Dsl::CommandGroupData]
+              def initialize(command_group_data)
+                @command_group_data = command_group_data
+
+                super(command_group_data.context_name, command_group_data.aggregate_name)
+              end
+
+              private
+
+              attr_reader :command_group_data
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/aggregate/dsl/class_resolvers/command_group/command.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    class Aggregate
+      module Dsl
+        module ClassResolvers
+          module CommandGroup
+            # Resolves or generates the Command class for an aggregate-DSL
+            # command group. The generated class is a {Yes::Core::Commands::CommandGroup}
+            # subclass carrying the group's identity (context, aggregate,
+            # group_name) and the ordered list of sub-command names.
+            class Command < Base
+              private
+
+              def class_type
+                :command_group
+              end
+
+              def class_name
+                command_group_data.name
+              end
+
+              def generate_class
+                group_name = command_group_data.name
+                ctx = command_group_data.context_name
+                agg = command_group_data.aggregate_name
+                sub_commands = command_group_data.sub_command_names.dup
+
+                Class.new(Yes::Core::Commands::CommandGroup).tap do |klass|
+                  klass.context = ctx
+                  klass.aggregate = agg
+                  klass.group_name = group_name
+                  klass.sub_command_names = sub_commands
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/aggregate/dsl/class_resolvers/command_group/guard_evaluator.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    class Aggregate
+      module Dsl
+        module ClassResolvers
+          module CommandGroup
+            # Resolves or generates the GuardEvaluator class for a command_group.
+            #
+            # Unlike the per-command resolver, no `:no_change` guard is
+            # auto-injected — command groups are intended to be lighter on
+            # guard checks and rely on whatever set of guards the user
+            # declares explicitly in the DSL block.
+            class GuardEvaluator < Base
+              private
+
+              def class_type
+                :command_group_guard_evaluator
+              end
+
+              def class_name
+                command_group_data.name
+              end
+
+              def generate_class
+                Class.new(Yes::Core::CommandHandling::GuardEvaluator)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/aggregate/dsl/command_group_data.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    class Aggregate
+      module Dsl
+        # Data object that holds information about a command_group definition
+        # in an aggregate.
+        #
+        # @example
+        #   CommandGroupData.new(:create_apprenticeship, MyAggregate, context: 'Companies', aggregate: 'Apprenticeship')
+        class CommandGroupData
+          attr_reader :name, :context_name, :aggregate_name, :aggregate_class
+          attr_accessor :sub_command_names, :guard_names
+
+          # @param name [Symbol] the name of the command group
+          # @param aggregate_class [Class] the aggregate class the group belongs to
+          # @param options [Hash] additional options
+          # @option options [String] :context the context name
+          # @option options [String] :aggregate the aggregate name
+          def initialize(name, aggregate_class, options = {})
+            @name = name
+            @aggregate_class = aggregate_class
+            @context_name = options[:context]
+            @aggregate_name = options[:aggregate]
+            @sub_command_names = []
+            @guard_names = []
+          end
+
+          # @param name [Symbol] sub-command name to append (preserves order)
+          # @return [void]
+          def add_sub_command(name)
+            @sub_command_names << name
+          end
+
+          # @param name [Symbol] guard name to record on this group
+          # @return [void]
+          def add_guard(name)
+            @guard_names << name
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/aggregate/dsl/command_group_definer.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    class Aggregate
+      module Dsl
+        # Factory class that creates and defines command_groups on aggregates.
+        #
+        # Mirrors {CommandDefiner}. The DSL evaluator inside accepts two
+        # methods: `command :sub_command_name` to push a sub-command symbol,
+        # and `guard(name, error_extra: …) { … }` to register a group-level
+        # guard on the generated GuardEvaluator class.
+        #
+        # @example
+        #   group_data = CommandGroupData.new(:create_apprenticeship, MyAggregate,
+        #                                     context: 'Companies', aggregate: 'Apprenticeship')
+        #   CommandGroupDefiner.new(group_data).call do
+        #     command :assign_company
+        #     command :change_name
+        #
+        #     guard(:company_assigned) { company_id.present? }
+        #   end
+        class CommandGroupDefiner
+          # Raised when an unknown sub-command name is referenced.
+          class UnknownSubCommandError < Yes::Core::Error; end
+
+          attr_reader :command_group_data
+          private :command_group_data
+
+          # @param command_group_data [CommandGroupData]
+          def initialize(command_group_data)
+            @command_group_data = command_group_data
+          end
+
+          # Generates and registers all classes/methods for the command group.
+          #
+          # @yield Block for declaring sub-commands and guards
+          # @return [void]
+          def call(&block)
+            create_and_register_guard_evaluator
+            evaluate_dsl_block(&block) if block
+            create_and_register_command
+            define_aggregate_methods
+          end
+
+          private
+
+          def create_and_register_guard_evaluator
+            @guard_evaluator_class = ClassResolvers::CommandGroup::GuardEvaluator.new(command_group_data).call
+          end
+
+          def create_and_register_command
+            ClassResolvers::CommandGroup::Command.new(command_group_data).call
+          end
+
+          def define_aggregate_methods
+            MethodDefiners::CommandGroup::CommandGroup.new(command_group_data).call
+            MethodDefiners::CommandGroup::CanCommandGroup.new(command_group_data).call
+          end
+
+          def evaluate_dsl_block(&)
+            DslEvaluator.new(command_group_data, @guard_evaluator_class).instance_eval(&)
+          end
+
+          # DSL evaluator that backs the `command_group :name do … end` block.
+          class DslEvaluator
+            attr_reader :command_group_data, :guard_evaluator_class
+
+            def initialize(command_group_data, guard_evaluator_class)
+              @command_group_data = command_group_data
+              @guard_evaluator_class = guard_evaluator_class
+            end
+
+            # Declare a sub-command. Order is preserved as execution order.
+            #
+            # @param name [Symbol] the sub-command name (must match a command
+            #   declared on the same aggregate)
+            # @return [void]
+            def command(name)
+              command_group_data.add_sub_command(name.to_sym)
+            end
+
+            # Register a group-level guard. Semantics match the per-command
+            # `guard` DSL — `:no_change` is recognized as the magic name that
+            # raises {NoChangeTransition} on failure.
+            #
+            # @param name [Symbol] the guard name
+            # @param error_extra [Hash, Proc] extra error context
+            # @yield Block returning true if the guard passes
+            # @return [void]
+            def guard(name, error_extra: {}, &)
+              command_group_data.add_guard(name)
+              guard_evaluator_class.guard(name, error_extra:, &)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/aggregate/dsl/method_definers/command_group/base.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    class Aggregate
+      module Dsl
+        module MethodDefiners
+          module CommandGroup
+            # Base class for command_group method definers.
+            class Base
+              def initialize(command_group_data)
+                @name = command_group_data.name
+                @aggregate_class = command_group_data.aggregate_class
+              end
+
+              def call
+                raise NotImplementedError, "#{self.class} must implement #call"
+              end
+
+              private
+
+              attr_reader :name, :aggregate_class
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/aggregate/dsl/method_definers/command_group/can_command_group.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    class Aggregate
+      module Dsl
+        module MethodDefiners
+          module CommandGroup
+            # Defines `aggregate.can_<group_name>?(payload = {})` and the
+            # `<group_name>_error` accessor on the aggregate class.
+            #
+            # Mirrors {MethodDefiners::Command::CanCommand} but resolves the
+            # group's GuardEvaluator class instead of a command's.
+            class CanCommandGroup < Base
+              def call
+                can_method = :"can_#{@name}?"
+                error_method = :"#{@name}_error"
+
+                aggregate_class.attr_accessor error_method
+                group_name = @name
+
+                aggregate_class.define_method(can_method) do |payload = {}|
+                  cmd = command_utilities.build_group_command(group_name, payload)
+                  guard_evaluator_class = command_utilities.fetch_guard_evaluator_class_for_group(group_name)
+
+                  Yes::Core::CommandHandling::GuardRunner.new(self).call(
+                    cmd, group_name, guard_evaluator_class, skip_guards: false
+                  ).present?
+                rescue Yes::Core::CommandHandling::GuardEvaluator::InvalidTransition,
+                       Yes::Core::CommandHandling::GuardEvaluator::NoChangeTransition,
+                       Yes::Core::Command::Invalid
+                  false
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/aggregate/dsl/method_definers/command_group/command_group.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    class Aggregate
+      module Dsl
+        module MethodDefiners
+          module CommandGroup
+            # Defines `aggregate.<group_name>(payload = nil, **options)` on the
+            # aggregate class. Mirrors {MethodDefiners::Command::Command} but
+            # delegates to {Yes::Core::CommandHandling::CommandGroupHandler}.
+            class CommandGroup < Base
+              def call
+                group_name = @name
+
+                aggregate_class.define_method(group_name) do |payload = nil, **options|
+                  payload = payload.clone if payload.is_a?(Hash)
+
+                  guards = options.delete(:guards)
+                  guards = true if guards.nil?
+                  metadata = options.delete(:metadata)
+
+                  if payload.nil? && !options.empty?
+                    payload = options
+                  elsif payload.nil?
+                    payload = {}
+                  end
+
+                  Yes::Core::CommandHandling::CommandGroupHandler.new(self).call(
+                    group_name, payload, guards:, metadata:
+                  )
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/aggregate.rb

@@ -66,6 +66,7 @@ module Yes
             if tp.self == subclass
               subclass.setup_read_model_classes if subclass.read_model_enabled?
               subclass.setup_authorizer_classes
+              subclass.validate_command_groups!
               tp.disable
             end
           end.enable
@@ -337,6 +338,55 @@ module Yes
           @commands ||= {}
         end
 
+        # Defines a command_group on the aggregate.
+        #
+        # A command_group declares a compound action that runs multiple
+        # existing aggregate commands in declaration order, atomically, with
+        # the sub-commands' guards bypassed. The group itself has its own,
+        # leaner guard set declared inside the block via `guard :name`.
+        #
+        # @param name [Symbol] the group name (also the aggregate method name)
+        # @yield Block accepting `command :sub_name` and `guard :name`
+        # @return [void]
+        #
+        # @example
+        #   command_group :create_apprenticeship do
+        #     command :assign_company
+        #     command :assign_user
+        #     command :change_name
+        #     command :publish
+        #
+        #     guard(:company_assigned) { payload.company_id.present? }
+        #   end
+        def command_group(name, &)
+          @command_groups ||= {}
+          group_data = Dsl::CommandGroupData.new(name, self, context:, aggregate:)
+          @command_groups[name] = group_data
+          Dsl::CommandGroupDefiner.new(group_data).call(&)
+        end
+
+        # @return [Hash] The command groups defined on this aggregate
+        def command_groups
+          @command_groups ||= {}
+        end
+
+        # Validates that each command_group references commands actually
+        # defined on this aggregate. Called from the end-of-class
+        # {TracePoint} hook set up in {.inherited}.
+        #
+        # @raise [Dsl::CommandGroupDefiner::UnknownSubCommandError]
+        # @return [void]
+        def validate_command_groups!
+          command_groups.each do |group_name, data|
+            unknown = data.sub_command_names - commands.keys
+            next if unknown.empty?
+
+            raise Dsl::CommandGroupDefiner::UnknownSubCommandError,
+                  "command_group :#{group_name} on #{name} references unknown commands: " \
+                  "#{unknown.join(', ')}. Define them with `command :<name>` before using them."
+          end
+        end
+
         private
 
         #

data/lib/yes/core/authorization/command_cerbos_authorizer.rb

@@ -36,7 +36,8 @@ module Yes
 
             raise_command_unauthorized_error!(decision)
           end
-          otl_trackable :call, OpenTelemetry::OtlSpan::OtlData.new(span_name: 'Cerbos Authorize Command')
+          otl_trackable :call,
+                        OpenTelemetry::OtlSpan::OtlData.new(span_name: 'Cerbos Authorize Command', track_sql: true)
 
           private
 
@@ -60,6 +61,10 @@ module Yes
             raise self::CommandNotAuthorized, msg
           end
 
+          # Loads the resource the command acts on. Commands batched into one request
+          # commonly target the same resource, so the lookup is cached for the duration
+          # of the authorization pass (see {LookupCache}).
+          #
           # @param command [Yes::Core::Command] command to authorize
           # @return [ActiveRecord::Base] resource to authorize
           # @raise [StandardError] if RESOURCE[:name] or RESOURCE[:read_model] is not defined
@@ -70,7 +75,10 @@ module Yes
               raise StandardError, message
             end
 
-            read_model(command).find_by(id: command.send("#{self::RESOURCE[:name]}_id"))
+            model = read_model(command)
+            id = command.send("#{self::RESOURCE[:name]}_id")
+
+            LookupCache.fetch([:resource, model, id]) { model.find_by(id:) }
           end
 
           # Returns the appropriate read model class for the command.
@@ -145,12 +153,19 @@ module Yes
             resource&.try(:auth_attributes)&.as_json || {}
           end
 
+          # Builds the principal data for the request. It is derived purely from the
+          # auth data, which is the same for every command of a batch, so it is built
+          # once per authorization pass (see {LookupCache}). The result is shared
+          # between commands and must not be mutated.
+          #
           # @param auth_data [Hash] authorization data
           # @return [Hash] principal data for Cerbos check_resource
           def principal_data(auth_data)
-            Yes::Core.configuration.cerbos_principal_data_builder.call(
-              auth_data.with_indifferent_access
-            )
+            data = auth_data.with_indifferent_access
+
+            LookupCache.fetch([:principal_data, data]) do
+              Yes::Core.configuration.cerbos_principal_data_builder.call(data)
+            end
           end
 
           # @param auth_data [Hash]

data/lib/yes/core/authorization/lookup_cache.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module Authorization
+      # Scoped memoization for the read-only lookups an authorization pass repeats.
+      #
+      # Authorizing a batch of commands resolves the same two things once per command:
+      # the principal data (which depends only on the request's auth data) and the
+      # authorized resource (which the commands of a batch commonly share). Both are
+      # pure reads, and a batch is authorized in full before any of its commands is
+      # executed, so no write can invalidate them while the pass is running.
+      #
+      # Caching is only active inside {.with_scope}. Outside one, {.fetch} just yields,
+      # so callers keep their uncached behaviour unless they opt in. The store lives in
+      # ActiveSupport::IsolatedExecutionState, which keeps it per thread/fiber, and
+      # {.with_scope} always clears it on the way out so nothing leaks into the next
+      # request.
+      #
+      # Cached values are shared by every {.fetch} for the same key, so callers must
+      # treat them as read-only.
+      #
+      # @example Caching the lookups of one authorization pass
+      #   LookupCache.with_scope do
+      #     commands.each { |command| authorizer_for(command).call(command, auth_data) }
+      #   end
+      class LookupCache
+        STORE_KEY = :yes_core_authorization_lookup_cache
+
+        class << self
+          # Runs the block with caching enabled, clearing the cache afterwards.
+          # A nested scope reuses the cache of the outermost one and leaves clearing
+          # to it.
+          #
+          # @yield the block to run with caching enabled
+          # @return [Object] the block's return value
+          def with_scope
+            return yield if active?
+
+            ActiveSupport::IsolatedExecutionState[STORE_KEY] = {}
+
+            begin
+              yield
+            ensure
+              ActiveSupport::IsolatedExecutionState.delete(STORE_KEY)
+            end
+          end
+
+          # Returns the value cached under key, computing it via the block on a miss.
+          # Without an open scope the block's value is returned uncached.
+          #
+          # @param key [Object] cache key
+          # @yield computes the value when it is not cached yet
+          # @return [Object] the cached or freshly computed value
+          def fetch(key)
+            return yield unless active?
+
+            store = ActiveSupport::IsolatedExecutionState[STORE_KEY]
+            return store[key] if store.key?(key)
+
+            store[key] = yield
+          end
+
+          # @return [Boolean] whether a scope is currently open
+          def active?
+            ActiveSupport::IsolatedExecutionState.key?(STORE_KEY)
+          end
+        end
+      end
+    end
+  end
+end