yes-core 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c43247d2dbf4c79fac0069c1fb4887a9fba4b38f845736b67dbb9ee2f213e96f
-  data.tar.gz: f78fa82e84433fb209a0e0dc5258ee7569e1993af11436112c590c7094f73b9c
+  metadata.gz: 684a9c20dfd17ba779b196a7b294b93e04bf531bcc3d31a2adc9f8a4d645b7dd
+  data.tar.gz: 43e482658ce60a8c7fe4eb5f73f3bf084169857bd06a57a01aadf5ab7cf98e76
 SHA512:
-  metadata.gz: 1c82e17ddceef537ce4f473577e318032b71c46c090ae70b44ea0264e29ad28b6eedef7115db1aafba3f1878a238a7269d533eb0b06ba07de17422b5e2ce9d70
-  data.tar.gz: 1ed596dba1c9b64292a3a517f823163fb2d1e36261b35fc96812be85abd919ab6b4d537da353114f45f799e0d33a47edd313d0731ec35c014d7cabd86ea8b396
+  metadata.gz: 335785676b2baef08117225b60c3a3b170bb39b0c3fe8ffdfa2781c158944b562f53d00884f409fb0c07c15ace4b513c02bd042973da57118ec325701a258acb
+  data.tar.gz: 72bc5b16b03b00ddc6211806d2566ad5213a25e452836e1ffd09f1e89c10154e98e47edb5ac75573092b1c21ea13cc38f5f49f379f418c2e08c2532d2e498670

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [1.2.0] - 2026-04-30
+
+- See root CHANGELOG.md for details.
+
+## [1.1.0] - 2026-04-28
+
+- See root CHANGELOG.md for details.
+
 ## [1.0.0] - 2026-03-21
 
 - Initial open-source release (see root CHANGELOG.md for details)

data/lib/yes/core/aggregate/draftable.rb

@@ -15,6 +15,7 @@ module Yes
         included do
           class << self
             attr_accessor :_draft_context, :_draft_aggregate, :_changes_read_model_name,
+                          :_changes_read_model_explicit,
                           :_draft_foreign_key, :_is_draftable, :_changes_read_model_public
           end
         end
@@ -52,7 +53,8 @@ module Yes
             self._draft_context = draft_config[:context] || context
             self._draft_aggregate = draft_config[:aggregate] || "#{aggregate}Draft"
 
-            self._changes_read_model_name = if changes_read_model
+            self._changes_read_model_explicit = changes_read_model.present?
+            self._changes_read_model_name = if changes_read_model.present?
                                               changes_read_model.to_s
                                             else
                                               "#{read_model_name}_change"

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

@@ -12,7 +12,7 @@ module Yes
         class CommandData
           attr_reader :name, :context_name, :aggregate_name, :aggregate_class
           attr_accessor :event_name, :payload_attributes, :update_state_block, :guard_names, :authorizer_block,
-                        :encrypted_attributes
+                        :encrypted_attributes, :skip_default_guards
 
           # @param name [Symbol] The name of the command
           # @param aggregate_class [Class] The aggregate class this command belongs to
@@ -21,6 +21,7 @@ module Yes
           # @option options [String] :aggregate The aggregate name
           # @option options [String] :event_name The event name for the command
           # @option options [Hash] :payload_attributes The payload attributes for the command
+          # @option options [Array<Symbol>] :skip_default_guards Default guards (e.g. :not_removed) that should not be auto-applied
           def initialize(name, aggregate_class, options = {})
             @name = name
             @aggregate_class = aggregate_class
@@ -38,6 +39,9 @@ module Yes
 
             # Track encrypted attributes for event schema generation
             @encrypted_attributes = []
+
+            # Default guards to opt out of (e.g. :not_removed for the :remove command itself)
+            @skip_default_guards = options.delete(:skip_default_guards) || []
           end
 
           # Add a guard name to the list of guards

data/lib/yes/core/aggregate.rb

@@ -76,8 +76,15 @@ module Yes
         #
         # @param name [Symbol] The name of the parent.
         # @param options [Hash] Options for configuring the parent.
+        # @option options [Boolean] :command (true) When false, skips defining the `assign_<name>` command.
+        # @option options [Array<Symbol>] :skip_default_guards ([]) Default guards (e.g. `:not_removed`)
+        #   that should not be auto-applied to the generated `assign_<name>` command. See
+        #   {.removable} for context on the `:not_removed` auto-block.
         # @yield Block for defining guards and other attribute configurations.
         # @return [void]
+        #
+        # @example Skip the auto-injected :not_removed guard on a parent's assign command
+        #   parent :tenant, skip_default_guards: %i[not_removed]
         def parent(name, **options, &)
           parent_aggregates[name] = options
 
@@ -85,7 +92,9 @@ module Yes
 
           return unless options.fetch(:command, true)
 
-          command :"assign_#{name}" do
+          skip_default_guards = options[:skip_default_guards] || []
+
+          command :"assign_#{name}", skip_default_guards: do
             payload "#{name}_id": :uuid
 
             guard(:no_change) { public_send(:"#{name}_id") != payload.public_send(:"#{name}_id") }
@@ -103,7 +112,26 @@ module Yes
 
         # Defines a default removal behavior for the aggregate.
         #
+        # In addition to defining the `:remove` command, `removable` records aggregate-level
+        # configuration that the {Yes::Core::CommandHandling::GuardEvaluator} reads at runtime
+        # to **auto-block every other command on the aggregate** while the removal attribute is
+        # set. The auto-block fires before any registered guard (including the auto-injected
+        # `:no_change`), so post-remove mutations consistently raise
+        # `GuardEvaluator::InvalidTransition` with the i18n message under
+        # `aggregates.<context>.<aggregate>.commands.<command>.guards.not_removed.error`.
+        # The `:remove` command itself is exempt and remains gated only by `:no_change`.
+        #
+        # The auto-block is order-independent: `removable` may be declared before or after the
+        # other commands on the aggregate.
+        #
+        # `attr_name` must correspond to an attribute readable on the aggregate (the macro
+        # auto-defines it as `:datetime` when missing).
+        #
         # @param attr_name [Symbol] the attribute name to use for marking removal
+        # @param not_removed_guards [Boolean] when true (default), every non-`:remove` command on
+        #   the aggregate auto-blocks while `attr_name` is set. Pass `false` to disable the
+        #   auto-block aggregate-wide; individual commands can still opt in by defining their
+        #   own `guard(:not_removed)`.
         # @yield Block for defining additional guards and other removal configurations
         # @return [void]
         #
@@ -124,16 +152,30 @@ module Yes
         #     removable(attr_name: :deleted_at)
         #   end
         #
-        def removable(attr_name: :removed_at, &)
+        # @example Disable the :not_removed auto-block aggregate-wide
+        #   class UserAggregate < Yes::Core::Aggregate
+        #     removable(not_removed_guards: false)
+        #   end
+        #
+        def removable(attr_name: :removed_at, not_removed_guards: true, &)
           attribute attr_name, :datetime unless attributes.key?(attr_name)
+          @removable_config = { attr_name:, not_removed_guards: }
 
-          command :remove do
+          command :remove, skip_default_guards: %i[not_removed] do
             guard(:no_change) { !public_send(attr_name) }
             update_state { method(attr_name).call { Time.current } }
             instance_eval(&) if block_given?
           end
         end
 
+        # Returns the removable configuration for the aggregate, or nil if {.removable} was
+        # never called.
+        #
+        # @return [Hash{Symbol => Object}, nil] hash with two keys when set:
+        #   * `:attr_name` [Symbol] — the attribute that marks removal (default `:removed_at`).
+        #   * `:not_removed_guards` [Boolean] — whether the auto-block is enabled.
+        attr_reader :removable_config
+
         # Sets the primary context for the aggregate.
         #
         # @param context [String] The primary context to set.
@@ -239,12 +281,24 @@ module Yes
         # @example Define publish command an published attribute
         #   command :publish
         #
-        def command(*args, **, &)
-          return handle_command_shortcut(*args, **, &) unless Dsl::CommandShortcutExpander.base_case?(*args, **, &)
+        # @example Skip the auto-injected :not_removed guard for a single command
+        #   command :restore, skip_default_guards: %i[not_removed] do
+        #     guard(:no_change) { removed_at.present? }
+        #     update_state { removed_at { nil } }
+        #   end
+        #
+        # All overloads accept a `skip_default_guards:` keyword argument carrying an array of
+        # default-guard symbols (currently only `:not_removed` — see {.removable}) that should
+        # not be auto-applied to the command. Defaults to `[]`.
+        #
+        def command(*args, **kwargs, &)
+          skip_default_guards = kwargs.delete(:skip_default_guards) || []
+          base_case = Dsl::CommandShortcutExpander.base_case?(*args, **kwargs, &)
+          return handle_command_shortcut(*args, skip_default_guards:, **kwargs, &) unless base_case
 
           name = args.first
           @commands ||= {}
-          command_data = Dsl::CommandData.new(name, self, { context:, aggregate: })
+          command_data = Dsl::CommandData.new(name, self, { context:, aggregate:, skip_default_guards: })
           @commands[name] = command_data
 
           Dsl::CommandDefiner.new(command_data).call(&)
@@ -295,8 +349,8 @@ module Yes
         #
         # @return [void]
         #
-        def handle_command_shortcut(...)
-          expanded = Dsl::CommandShortcutExpander.new(...).call
+        def handle_command_shortcut(*, skip_default_guards: [], **, &)
+          expanded = Dsl::CommandShortcutExpander.new(*, **, &).call
 
           expanded.attributes.each do |specification|
             next if attributes.key?(specification.name)
@@ -305,7 +359,7 @@ module Yes
           end
 
           expanded.commands.each do |specification|
-            command(specification.name, &specification.block)
+            command(specification.name, skip_default_guards:, &specification.block)
           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/middlewares.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module Middlewares
+      class << self
+        # Returns middleware keys excluding the specified one.
+        #
+        # @param middleware_name [Symbol] the middleware key to exclude
+        # @return [Array<Symbol>] remaining middleware keys
+        def without(middleware_name)
+          PgEventstore.config.middlewares.except(middleware_name).keys
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module TestSupport
+      module Aggregate
+        # DSL for writing concise aggregate command specs.
+        #
+        # Provides `command`, `success`, `invalid`, `no_change`, and `setup` methods
+        # that generate RSpec describe/context blocks with appropriate shared examples.
+        #
+        # @example
+        #   RSpec.describe MyContext::MyAggregate::Aggregate, type: :aggregate do
+        #     command 'do_something' do
+        #       let(:command_data) { { name: 'test' } }
+        #       let(:success_attributes) { { name: 'test' } }
+        #
+        #       success
+        #       invalid 'when precondition not met'
+        #       no_change
+        #     end
+        #   end
+        module CommandTestDsl
+          # Defines a test block for a command
+          #
+          # @param command_name [String, Symbol] the name of the command to test
+          # @param options [Array<Hash>] additional options (e.g., `draft: true`, VCR cassettes)
+          # @yield block for configuring test cases with success/invalid/no_change
+          def command(command_name, *options, &block)
+            describe command_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(command, command_data, guards: !draft) }
+
+              let(:command) { command_name.to_sym }
+              let(:aggregate_class) { aggregate.class }
+              let(:command_data_with_id) do
+                { "#{aggregate_class.aggregate.underscore}_id" => aggregate.id }.merge(command_data)
+              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}"
+              end
+              let(:expected_event_data) { command_data_with_id }
+              let(:expected_event_metadata) { nil }
+              let(:success_attributes) { command_data.without(:locale) } unless method_defined?(:success_attributes)
+
+              class_eval(&block) if block_given?
+            end
+          end
+
+          # Defines a test case for a successful command execution
+          #
+          # @param description [String] optional description
+          # @param options [Hash] additional options (e.g., VCR cassettes)
+          # @yield optional block for additional setup or custom assertions
+          def success(description = 'when successfully executing command', options = {}, &block)
+            context description, options do
+              instance_eval(&block) if block_given?
+
+              it_behaves_like 'successful command'
+            end
+          end
+
+          # Defines a test case for a command that causes no state change
+          #
+          # @param description [String] optional description
+          # @param options [Hash] additional options
+          # @yield optional block for additional setup
+          def no_change(description = 'when command causes no change', options = {}, &block)
+            context description.to_s, options do
+              instance_eval(&block) if block_given?
+
+              before { aggregate.public_send(command, command_data) }
+
+              it_behaves_like 'no change transition'
+            end
+          end
+
+          # Defines a test case for an invalid transition
+          #
+          # @param description [String] description of the invalid scenario
+          # @param options [Hash] additional options
+          # @yield optional block for additional setup
+          def invalid(description, options = {}, &block)
+            context "when #{description}", options do
+              instance_eval(&block) if block_given?
+
+              it_behaves_like 'invalid transition'
+            end
+          end
+
+          # Alias for `before` — used for readable aggregate setup within command blocks
+          #
+          # @yield block for setup actions
+          def setup(&)
+            before(&)
+          end
+        end
+      end
+    end
+  end
+end
+
+if defined?(RSpec)
+  RSpec.configure do |config|
+    config.extend Yes::Core::TestSupport::Aggregate::CommandTestDsl, type: :aggregate
+  end
+end

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

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+RSpec::Matchers.define :have_authorizer do
+  match do |actual|
+    actual&.authorizer_class&.< Yes::Core::Authorization::CommandAuthorizer
+  end
+
+  description do
+    'have an authorizer'
+  end
+end
+
+RSpec::Matchers.define :have_read_model_class do |read_model_class|
+  match do |aggregate|
+    aggregate.read_model_class == read_model_class
+  end
+
+  failure_message do |aggregate|
+    "expected #{aggregate} to have read model class #{read_model_class}" \
+      "\n  actual read model class is #{aggregate.read_model_class}"
+  end
+end
+
+RSpec::Matchers.define :have_cerbos_authorizer do
+  match do |aggregate|
+    next false unless aggregate.authorizer_class&.< Yes::Core::Authorization::CommandCerbosAuthorizer
+
+    next false if @read_model_class && aggregate.authorizer_options&.read_model_class != @read_model_class
+
+    next false if @resource_name && aggregate.authorizer_options&.resource_name != @resource_name
+
+    true
+  end
+
+  chain :with_read_model_class do |read_model_class|
+    @read_model_class = read_model_class
+  end
+
+  chain :with_resource_name do |resource_name|
+    @resource_name = resource_name
+  end
+
+  description do
+    msg = 'have a Cerbos authorizer'
+    msg += " with read model class #{@read_model_class}" if @read_model_class
+    msg += " with resource name #{@resource_name}" if @resource_name
+    msg
+  end
+
+  failure_message do |aggregate|
+    msg = "expected #{aggregate} to have a Cerbos authorizer"
+    msg += "\n  with read model class #{@read_model_class}" if @read_model_class
+    msg += "\n  with resource name #{@resource_name}" if @resource_name
+    msg += "\n    actual read model class is #{aggregate.authorizer_options&.read_model_class}" if @read_model_class
+    msg += "\n    actual resource name is #{aggregate.authorizer_options&.resource_name}" if @resource_name
+    msg
+  end
+end
+
+RSpec::Matchers.define :have_parent do |parent_name|
+  match do |aggregate|
+    @parent = aggregate.parent_aggregates.with_indifferent_access[parent_name]
+
+    return false unless @parent
+
+    return true unless @context
+
+    @parent[:context] == @context
+  end
+
+  chain :with_context do |context|
+    @context = context
+  end
+
+  failure_message do |aggregate|
+    msg = "expected #{aggregate} to have parent #{parent_name}"
+    msg += "\n  with context #{@context}" if @context
+    msg += "\n  actual context is #{@parent[:context].presence || aggregate.context}" if @parent && @context
+    msg
+  end
+end

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

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+RSpec.shared_context 'with given events' do
+  before do
+    given_events.each do |event_data|
+      event = event_instance(event_data)
+      stream = event_stream(event_data)
+      append_event(stream, event)
+    end
+  end
+end
+
+RSpec.shared_examples 'successful command' do
+  let(:event) { aggregate.events.map(&:last).last }
+  let(:expected_event_metadata) { nil }
+
+  it 'correctly changes the aggregate state' do
+    if success_attributes.any?
+      expect { subject }.to change {
+        aggregate.read_model.attributes.to_h.symbolize_keys.slice(*success_attributes.keys)
+      }.to(success_attributes)
+    end
+  end
+
+  it 'publishes expected event' do
+    subject
+    aggregate_failures do
+      expect(event.type).to eq(expected_event_type)
+      expect(event.data).to eq(expected_event_data.deep_stringify_keys)
+      expect(event.metadata).to include(expected_event_metadata.deep_stringify_keys) if expected_event_metadata
+    end
+  end
+end
+
+RSpec.shared_examples 'invalid transition' do
+  it 'raises InvalidTransition error' do
+    expect(subject.error).to be_a(Yes::Core::CommandHandling::GuardEvaluator::InvalidTransition)
+  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
+
+  it 'does not publish event' do
+    expect { subject }.not_to(
+      change do
+        aggregate.events.map(&:flatten).flatten.count
+      rescue PgEventstore::StreamNotFoundError
+        nil
+      end
+    )
+  end
+end
+
+RSpec.shared_examples 'no change transition' do
+  it 'raises NoChangeTransition error' do
+    expect(subject.error).to be_a(Yes::Core::CommandHandling::GuardEvaluator::NoChangeTransition)
+  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
+
+  it 'does not publish event' do
+    expect { subject }.not_to(
+      change do
+        aggregate.events.map(&:flatten).flatten.count
+      rescue PgEventstore::StreamNotFoundError
+        nil
+      end
+    )
+  end
+end

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

@@ -4,16 +4,33 @@ module Yes
   module Core
     module TestSupport
       # Helpers for working with PgEventstore events in tests.
+      #
+      # @example Include in RSpec
+      #   RSpec.configure do |config|
+      #     config.include Yes::Core::TestSupport::EventHelpers
+      #   end
       module EventHelpers
+        # Appends an event to a stream
+        #
+        # @param stream [PgEventstore::Stream]
+        # @param event [Yes::Core::Event]
+        # @return [void]
+        def append_event(stream, event)
+          PgEventstore.client.append_to_stream(stream, event)
+        end
+
+        # Appends an event to a stream and reloads it
+        #
         # @param stream [PgEventstore::Stream]
         # @param event [Yes::Core::Event]
         # @return [Yes::Core::Event]
         def append_and_reload_event(stream, event)
-          PgEventstore.client.append_to_stream(stream, event)
+          append_event(stream, event)
           PgEventstore.client.read(stream, options: { max_count: 1, direction: :desc }).first
         end
 
         # Reads eventstore and returns events from the stream or an empty array if stream does not exist
+        #
         # @param stream [PgEventstore::Stream]
         # @return [Array<Yes::Core::Event>]
         def safe_read(stream)
@@ -21,6 +38,61 @@ module Yes
         rescue PgEventstore::StreamNotFoundError
           []
         end
+
+        alias read_events safe_read
+
+        # Creates events from a block and appends them to the eventstore
+        #
+        # @yield block that returns an array of event attribute hashes
+        # @yieldreturn [Array<Hash>] each hash should have :context, :aggregate, :event, :data keys
+        # @return [void]
+        #
+        # @example
+        #   given_events do
+        #     [{ context: 'MyContext', aggregate: 'MyAggregate', event: 'Created', data: { id: '123' } }]
+        #   end
+        def given_events(&)
+          events_data = yield
+          events_data.each do |event_data|
+            event = event_instance(event_data)
+            stream = event_stream(event_data)
+            append_event(stream, event)
+          end
+        end
+
+        # Builds a Yes::Core::Event from a hash of event attributes
+        #
+        # @param event_attrs [Hash] event attributes with :context, :aggregate, :event, :data keys
+        # @return [Yes::Core::Event]
+        def event_instance(event_attrs)
+          Yes::Core::Event.new(
+            type: event_type(event_attrs),
+            data: (event_attrs[:data] || {}).with_indifferent_access
+          )
+        end
+
+        # Builds a PgEventstore::Stream from event attributes
+        #
+        # @param event_attrs [Hash] event attributes with :context, :aggregate, :data keys
+        # @return [PgEventstore::Stream]
+        def event_stream(event_attrs)
+          return event_attrs[:stream] if event_attrs[:stream]
+
+          PgEventstore::Stream.new(
+            context: event_attrs[:context],
+            stream_name: event_attrs[:aggregate],
+            stream_id: event_attrs[:data].first.last
+          )
+        end
+
+        # Constructs an event type string from event attributes
+        #
+        # @param event_attrs [Hash] event attributes with :context, :aggregate/:subject, :event keys
+        # @return [String]
+        def event_type(event_attrs)
+          aggregate_or_subject = event_attrs[:aggregate] || event_attrs[:subject]
+          "#{event_attrs[:context]}::#{aggregate_or_subject}#{event_attrs[:event]}"
+        end
       end
     end
   end

data/lib/yes/core/test_support.rb

@@ -3,3 +3,6 @@
 require_relative 'test_support/event_helpers'
 require_relative 'test_support/jwt_helpers'
 require_relative 'test_support/test_helper'
+require_relative 'test_support/aggregate/command_test_dsl'
+require_relative 'test_support/aggregate/shared_examples'
+require_relative 'test_support/aggregate/matchers'

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

@@ -3,14 +3,20 @@
 module Yes
   module Core
     module Utils
-      # Provides convenient shortcuts for accessing aggregate classes in Rails console
-      # @example
-      #   # Instead of: ApprenticeshipPresentation::Apprenticeship::Aggregate.new(id)
-      #   # Use: AP::Appr.new(id)
+      # Provides convenient shortcuts for accessing aggregate classes in Rails console.
+      # @example Multi-capital subjects use capitals-only abbreviations
+      #   # Instead of: ApprenticeshipPresentation::ContactInfo::Aggregate.new(id)
+      #   # Use: AP::CI.new(id)
+      # @example Single-capital subjects keep the full name
+      #   # Instead of: TaskFlow::Board::Aggregate.new(id)
+      #   # Use: TF::Board.new(id)
       class AggregateShortcuts
         class << self
-          # Load aggregate shortcuts in Rails console
-          # Creates module aliases and constants for convenient access
+          # Load aggregate shortcuts in Rails console.
+          # Creates fresh shortcut modules (e.g. TF) and assigns aggregate classes
+          # as constants on them. Shortcut modules are NOT aliases of the real
+          # context modules, so shortcut constants cannot collide with the
+          # aggregates' own namespace modules.
           def load!
             return unless Yes::Core.configuration.aggregate_shortcuts
 
@@ -32,26 +38,35 @@ module Yes
             results
           end
 
-          # Display shortcuts in a formatted table
+          # Display shortcuts in a formatted table.
+          #
+          # Writes directly to STDOUT (via Kernel#puts) rather than the Rails logger
+          # so the output is readable in any environment — Rails consoles in
+          # production typically configure structured / JSON loggers that would
+          # otherwise wrap each line in a JSON envelope.
+          #
           # @param filter [String, nil] Optional filter
+          # rubocop:disable Rails/Output
           def display(filter = nil)
             shortcuts = list(filter)
 
             if shortcuts.empty?
-              Rails.logger.debug { "No shortcuts found#{" for '#{filter}'" if filter}." }
+              puts "No shortcuts found#{" for '#{filter}'" if filter}."
               return
             end
 
             max_shortcut_length = shortcuts.keys.map(&:length).max
+            separator = '=' * (max_shortcut_length + 70)
 
-            Rails.logger.debug "\nAvailable Aggregate Shortcuts:"
-            Rails.logger.debug '=' * (max_shortcut_length + 70)
+            puts "\nAvailable Aggregate Shortcuts:"
+            puts separator
             shortcuts.sort.each do |shortcut, full_path|
-              Rails.logger.debug "#{shortcut.ljust(max_shortcut_length)} → #{full_path}"
+              puts "#{shortcut.ljust(max_shortcut_length)} → #{full_path}"
             end
-            Rails.logger.debug '=' * (max_shortcut_length + 70)
-            Rails.logger.debug { "\nUsage: #{shortcuts.keys.first}.new(id)" } if shortcuts.any?
+            puts separator
+            puts "\nUsage: #{shortcuts.keys.first}.new(id)"
           end
+          # rubocop:enable Rails/Output
 
           private
 
@@ -102,19 +117,22 @@ module Yes
               context_abbr = abbreviate_context(agg[:context])
               subject_abbr = abbreviate_subject(agg[:subject])
 
-              # Create context module alias if not exists
+              # Build (or reuse) a fresh container module for the context shortcut.
+              # We deliberately do NOT alias the real context module: doing so would
+              # mean shortcut constants (e.g. TF::Board) collide with the real
+              # namespace modules of the aggregates themselves (TaskFlow::Board).
               unless context_modules[context_abbr]
                 if Object.const_defined?(context_abbr)
                   Rails.logger.warn("Shortcut conflict: #{context_abbr} already defined, skipping #{agg[:context]}")
                   next
                 end
 
-                context_module = agg[:context].constantize
-                Object.const_set(context_abbr, context_module)
-                context_modules[context_abbr] = context_module
+                shortcut_module = Module.new
+                Object.const_set(context_abbr, shortcut_module)
+                context_modules[context_abbr] = shortcut_module
               end
 
-              # Create subject constant within context module
+              # Create subject constant within the shortcut container.
               context_mod = context_modules[context_abbr]
               if context_mod.const_defined?(subject_abbr)
                 Rails.logger.warn("Shortcut conflict: #{context_abbr}::#{subject_abbr} already defined")
@@ -140,12 +158,15 @@ module Yes
           def abbreviate_subject(subject)
             return @subject_overrides[subject] if @subject_overrides[subject]
 
-            # First try capital letters
+            # Multi-capital CamelCase names get a capitals-only abbreviation
+            # (ContactInfo → CI). Single-capital names (Task, Board, Location)
+            # use the full subject name to avoid awkward truncations like
+            # "Boar" or shortcut collisions when the truncation matches the
+            # subject's own namespace module (e.g. TaskFlow::Task).
             capitals = subject.scan(/[A-Z]/).join
             return capitals if capitals.length > 1
 
-            # Otherwise use first 4 characters
-            subject[0..3]
+            subject
           end
 
           def define_helper_method

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

@@ -68,7 +68,7 @@ module Yes
         def build_event(command_name:, payload:, metadata: {})
           event_class = Yes::Core.configuration.event_classes_for_command(context, aggregate, command_name).first
           event_class.new(
-            type: "#{context}::#{aggregate_name_with_draft_suffix(aggregate, metadata)}#{event_class.name.demodulize}",
+            type: "#{context}::#{aggregate_name_with_draft_suffix(aggregate, metadata, context:)}#{event_class.name.demodulize}",
             data: payload,
             metadata:
           )
@@ -83,7 +83,7 @@ module Yes
         def build_stream(context: @context, name: @aggregate, id: @aggregate_id, metadata: {})
           PgEventstore::Stream.new(
             context:,
-            stream_name: aggregate_name_with_draft_suffix(name, metadata),
+            stream_name: aggregate_name_with_draft_suffix(name, metadata, context:),
             stream_id: id
           )
         end
@@ -209,16 +209,33 @@ module Yes
           payload.merge(locale: I18n.locale.to_s)
         end
 
-        # Builds the aggregate name with the draft suffix
+        # Builds the aggregate name with the draft suffix.
+        #
+        # When the aggregate class is configured with `draftable changes_read_model:` (explicitly),
+        # the camelized changes_read_model is used as the stream / event-type prefix so the DSL
+        # config decides where draft events land. This lets an aggregate share an edit-template
+        # stream with a sibling (e.g. `Recruiter` writes to `UserEditTemplate` via
+        # `changes_read_model: :user_edit_template`).
+        #
+        # For non-draftable aggregates, and for draftable aggregates that rely on the default
+        # `<read_model>_change` changes_read_model name, the legacy hard-coded `<Aggregate>Draft`
+        # / `<Aggregate>EditTemplate` suffix is used.
         #
         # @param aggregate_name [String] The name of the aggregate
         # @param metadata [Hash] The command metadata
-        # @return [String] The stream name
-        def aggregate_name_with_draft_suffix(aggregate_name, metadata = {})
-          return "#{aggregate_name}Draft" if metadata&.dig(:draft)
-          return "#{aggregate_name}EditTemplate" if metadata&.dig(:edit_template_command)
-
-          aggregate_name
+        # @param context [String] The aggregate's context (defaults to @context)
+        # @return [String] The stream / event-type name component
+        def aggregate_name_with_draft_suffix(aggregate_name, metadata = {}, context: @context)
+          return aggregate_name unless metadata&.dig(:draft) || metadata&.dig(:edit_template_command)
+
+          klass = "#{context}::#{aggregate_name}::Aggregate".safe_constantize
+          if klass.respond_to?(:_changes_read_model_explicit) && klass._changes_read_model_explicit
+            klass.changes_read_model_name.camelize
+          elsif metadata&.dig(:edit_template_command)
+            "#{aggregate_name}EditTemplate"
+          else
+            "#{aggregate_name}Draft"
+          end
         end
       end
     end

data/lib/yes/core/version.rb

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

data/lib/yes/core.rb

@@ -19,6 +19,7 @@ module Yes
           loader.push_dir(File.expand_path('..', __dir__))
           loader.ignore("#{__dir__}/core/version.rb")
           loader.ignore("#{__dir__}/core/test_support")
+          loader.ignore("#{__dir__}/core/test_support.rb")
           loader.collapse("#{__dir__}/core/models")
           loader.setup
           loader

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yes-core
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Nico Ritsche
@@ -259,6 +259,7 @@ files:
 - lib/yes/core/generators/read_models/templates/migration.rb.erb
 - lib/yes/core/generators/read_models/update_generator.rb
 - lib/yes/core/jobs/read_model_recovery_job.rb
+- lib/yes/core/middlewares.rb
 - lib/yes/core/middlewares/encryptor.rb
 - lib/yes/core/middlewares/timestamp.rb
 - lib/yes/core/middlewares/with_indifferent_access.rb
@@ -281,6 +282,9 @@ files:
 - lib/yes/core/serializer.rb
 - lib/yes/core/subscriptions.rb
 - lib/yes/core/test_support.rb
+- lib/yes/core/test_support/aggregate/command_test_dsl.rb
+- lib/yes/core/test_support/aggregate/matchers.rb
+- lib/yes/core/test_support/aggregate/shared_examples.rb
 - lib/yes/core/test_support/event_helpers.rb
 - lib/yes/core/test_support/jwt_helpers.rb
 - lib/yes/core/test_support/subscriptions_helper.rb