yes-core 1.3.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a7213daeb56ae07a8921c83b912e83b7f9cd81f6d93d90a4394cbe07b7c9299
-  data.tar.gz: 58379a04830d2ba08c0ca4431d4e372ee8cc67f8445621d7143c61f1dc27ab9a
+  metadata.gz: '06386ad1e1b30ddacbb4afaf392632875023650518041e3914178427039f91f5'
+  data.tar.gz: af40c3f3d98c611ce0653dfb0c0e2e2193376feb1ed0aeba69d43827fd6a09f9
 SHA512:
-  metadata.gz: f5ce8a14fb78e7c9bc1b11264e16a17f0cbdc0ef3dcbbd7175114a1c772097b67cb1226f359429a6be83900f26d0e911dd18df838aa9c9ad5a76cab5d999b889
-  data.tar.gz: 01de285d8c90f81625bdd1ff721877b87d23edad1949b1eb860ebd4fc0274c459fbbeb3080e6ecb678fa1cd0174b010b4eb4f146ff00d6e4bea4be935685bb08
+  metadata.gz: e956ac8483b7a53f13009356536c221f92dc2dd6d88f6137ca4d1e6305a7c239a2870484197469243c14dca6552983d0004b263147ad6642d94c17611415cfd6
+  data.tar.gz: 5ac3c8ea889ddf9a01efc1ac645a35c9d394736f351e1f98d9ca1dc0f5550094ded103ba424f2a8df07f24d46a082948a69e719aab3aa330d18736d0815de17a

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [2.3.0] - 2026-09-03
+- See root CHANGELOG.md for details.
+
+## [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.

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/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

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

@@ -55,6 +55,8 @@ module Yes
       #   response = executor.call(command, guard_evaluator_class)
       #
       class CommandExecutor
+        include RevisionConflictWaiting
+
         MAX_RETRIES = 10
         INLINE_RECOVERY_RETRY_THRESHOLD = 5
 
@@ -96,13 +98,15 @@ module Yes
           rescue PgEventstore::WrongExpectedRevisionError => e
             retries += 1
             clear_pending_update_state if aggregate.class.read_model_enabled?
+            raise e if retries > MAX_RETRIES
 
-            retries <= MAX_RETRIES ? retry : raise(e)
+            wait_for_read_model(e, retries)
+            retry
           rescue ConcurrentUpdateError => e
             retries += 1
             # Don't clear pending state - another process owns it
             # Sleep with exponential backoff to give the other process time to finish
-            sleep([0.01 * (2**(retries - 1)), 1.0].min) if retries <= MAX_RETRIES
+            sleep(RevisionConflictBackoff.schedule(retries)) if retries <= MAX_RETRIES
 
             # After several retries, check if pending state is stuck and attempt recovery
             # This prevents infinite retry loops when a process crashes leaving the flag set

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

@@ -17,6 +17,8 @@ module Yes
       # Only the group's own guards run here — sub-command guards are
       # bypassed by design.
       class CommandGroupExecutor
+        include RevisionConflictWaiting
+
         MAX_RETRIES = 10
         INLINE_RECOVERY_RETRY_THRESHOLD = 5
 
@@ -47,10 +49,13 @@ module Yes
           rescue PgEventstore::WrongExpectedRevisionError => e
             retries += 1
             clear_pending_update_state if aggregate.class.read_model_enabled?
-            retries <= MAX_RETRIES ? retry : raise(e)
+            raise e if retries > MAX_RETRIES
+
+            wait_for_read_model(e, retries)
+            retry
           rescue ConcurrentUpdateError => e
             retries += 1
-            sleep([0.01 * (2**(retries - 1)), 1.0].min) if retries <= MAX_RETRIES
+            sleep(RevisionConflictBackoff.schedule(retries)) if retries <= MAX_RETRIES
 
             if aggregate.class.read_model_enabled? && retries >= INLINE_RECOVERY_RETRY_THRESHOLD
               ReadModelRecoveryService.attempt_inline_recovery(read_model, aggregate: aggregate)
@@ -169,7 +174,8 @@ module Yes
           PgEventstore.client.append_to_stream(
             utils.build_stream(metadata: sub_cmd.metadata || {}),
             event,
-            options: { expected_revision: :any }
+            options: { expected_revision: :any },
+            middlewares: Middlewares.for_write
           )
         end
 

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

@@ -90,7 +90,8 @@ module Yes
           PgEventstore.client.append_to_stream(
             command_utilities.build_stream(metadata:),
             event,
-            options: { expected_revision: }
+            options: { expected_revision: },
+            middlewares: Middlewares.for_write
           ).tap { otl_record_response(_1) }
         end
 
@@ -105,16 +106,20 @@ module Yes
               name: aggregate_data[:name],
               id: aggregate_data[:id]
             )
-            expected_revision = command_utilities.stream_revision(stream)
+            stream_revision = command_utilities.stream_revision(stream)
             aggregate_revision = aggregate_data[:revision].call
-            normalized_revision = aggregate_revision == -1 ? :no_stream : aggregate_revision
-
-            next if normalized_revision == expected_revision
+            expected_revision = aggregate_revision == -1 ? :no_stream : aggregate_revision
+            next if expected_revision == stream_revision
 
+            # Same argument convention as pg_eventstore itself: `revision` is what the
+            # store holds, `expected_revision` what we held. pg_eventstore 3.0 requires
+            # `verdict:`, which selects the error's message; this branch is only reached
+            # when the two differ, which is exactly :unmatched_stream_revision.
             raise PgEventstore::WrongExpectedRevisionError.new(
-              revision: aggregate_revision,
+              revision: stream_revision,
               expected_revision:,
-              stream:
+              stream:,
+              verdict: :unmatched_stream_revision
             )
           end
         end
@@ -175,7 +180,7 @@ module Yes
             timestamp: result.created_at,
             attributes: {
               'event.type' => result.type,
-              'event.link_id' => result.link_id || '',
+              'event.link_global_position' => result.link_global_position || '',
               'global_position' => result.global_position,
               'stream' => result.stream.to_json,
               'stream.revision' => result.stream_revision,

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

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module CommandHandling
+      # Decides how long an executor waits before retrying a command after a
+      # PgEventstore::WrongExpectedRevisionError.
+      #
+      # The executors derive the expected revision from the read model's revision
+      # column. When the conflicting append came from this service, the read model
+      # was updated in the same process, so the very next attempt already sees the
+      # new revision and any wait only adds latency. When another service appended
+      # to the stream, the column only advances once this service's event listener
+      # has projected that event, typically a few hundred milliseconds later.
+      # Retrying immediately then burns every attempt inside the same half second
+      # and the command surfaces as a 500.
+      #
+      # The error carries the stream's actual revision, so for the aggregate's own
+      # stream the two cases can be told apart: retry at once while the reloaded
+      # read model has caught up, back off while it is still behind. A conflict on
+      # an external aggregate's stream (see EventPublisher#verify_external_revisions!)
+      # cannot be checked here and always backs off.
+      #
+      # Delays follow the same 10 ms doubling schedule as the ConcurrentUpdateError
+      # branch, capped per attempt and in total, with jitter so that requests which
+      # collided once do not retry in lockstep.
+      class RevisionConflictBackoff
+        # @return [Float] delay of the first waiting attempt, in seconds
+        BASE_DELAY_SECONDS = 0.01
+        # @return [Float] longest delay of a single attempt, in seconds
+        MAX_DELAY_SECONDS = 1.0
+        # @return [Float] total sleep budget across all retries of one command, in seconds
+        TOTAL_BUDGET_SECONDS = 2.0
+        # @return [Float] fraction by which a delay is randomised in both directions
+        JITTER_FRACTION = 0.25
+
+        class << self
+          # @param error [PgEventstore::WrongExpectedRevisionError] the conflict that was raised
+          # @param aggregate_id [String] id of the aggregate the executor works on; used to tell its own
+          #   stream from an external aggregate's stream
+          # @param read_model_revision [Integer, nil] the revision the read model reports after a
+          #   reload, or nil when the aggregate has no read model
+          # @param attempt [Integer] the 1-based retry attempt about to be made
+          # @return [Float] seconds to wait before retrying, 0.0 to retry immediately
+          def delay(error:, aggregate_id:, read_model_revision:, attempt:)
+            return 0.0 unless worth_waiting?(error, aggregate_id, read_model_revision)
+
+            remaining = TOTAL_BUDGET_SECONDS - waited_before(attempt)
+            return 0.0 unless remaining.positive?
+
+            jittered([schedule(attempt), remaining].min)
+          end
+
+          # The undisturbed exponential schedule, shared with the ConcurrentUpdateError retries.
+          #
+          # @param attempt [Integer] the 1-based retry attempt
+          # @return [Float] seconds
+          def schedule(attempt)
+            [BASE_DELAY_SECONDS * (2**(attempt - 1)), MAX_DELAY_SECONDS].min
+          end
+
+          private
+
+          # @return [Boolean] false only when the conflict is on the aggregate's own stream and the
+          #   read model already reports at least the stream revision the conflict was raised with
+          def worth_waiting?(error, aggregate_id, read_model_revision)
+            return true unless own_stream?(error.stream, aggregate_id)
+            return false unless read_model_revision.is_a?(Integer) && error.revision.is_a?(Integer)
+
+            read_model_revision < error.revision
+          end
+
+          # @return [Boolean] true when the stream belongs to the aggregate itself; a stream that
+          #   cannot be inspected is treated as the aggregate's own
+          def own_stream?(stream, aggregate_id)
+            return true unless stream.respond_to?(:stream_id)
+
+            stream.stream_id.to_s == aggregate_id.to_s
+          end
+
+          # @return [Float] seconds already spent sleeping before this attempt
+          def waited_before(attempt)
+            (1...attempt).sum { schedule(_1) }
+          end
+
+          # @return [Float] the delay randomised by ±JITTER_FRACTION
+          def jittered(delay)
+            delay * (1 + (JITTER_FRACTION * ((2 * rand) - 1)))
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module CommandHandling
+      # Shared by {CommandExecutor} and {CommandGroupExecutor}: the wait between two
+      # attempts after a PgEventstore::WrongExpectedRevisionError. Expects the
+      # including class to expose a private +aggregate+ reader.
+      module RevisionConflictWaiting
+        private
+
+        # Sleeps only while the read model has not yet caught up with the stream
+        # revision reported by the conflict, see {RevisionConflictBackoff}.
+        #
+        # @param error [PgEventstore::WrongExpectedRevisionError]
+        # @param attempt [Integer] the 1-based retry attempt about to be made
+        # @return [void]
+        def wait_for_read_model(error, attempt)
+          delay = RevisionConflictBackoff.delay(
+            error:, aggregate_id: aggregate.id, read_model_revision: current_read_model_revision, attempt:
+          )
+          sleep(delay) if delay.positive?
+        end
+
+        # @return [Integer, nil] the freshly reloaded read model revision; nil without a read model or
+        #   when the row disappeared underneath the retry, both of which mean "retry immediately"
+        def current_read_model_revision
+          return nil unless aggregate.class.read_model_enabled?
+
+          aggregate.reload.revision
+        rescue ActiveRecord::RecordNotFound
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -109,10 +109,15 @@ module Yes
           @commands = build_commands
         end
 
-        # @return [Hash] hash form for serialization, merging normalized payload
-        #   and reserved keys (matches legacy {Yes::Core::Commands::Group#to_h})
+        # @return [Hash] hash form for serialization — the FLAT input payload
+        #   merged with reserved keys (transaction/origin/batch_id/metadata/
+        #   command_id). This shape round-trips cleanly: calling
+        #   `self.class.new(cmd.to_h)` produces an equivalent group with the
+        #   same `payload`. Used by
+        #   {Yes::Core::ActiveJobSerializers::CommandGroupSerializer} and by
+        #   the Command API controller's `add_metadata`.
         def to_h
-          merged = normalized_payload.merge(group_attributes.to_h)
+          merged = payload.merge(group_attributes.to_h)
           transaction ? merged.merge(transaction:) : merged
         end
 

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

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

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

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

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

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

data/lib/yes/core/configuration.rb

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

data/lib/yes/core/data_decryptor.rb

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

data/lib/yes/core/data_encryptor.rb

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

data/lib/yes/core/error.rb

@@ -2,9 +2,28 @@
 
 module Yes
   module Core
+    # Base class for the gem's errors, carrying optional caller-supplied context.
+    #
+    # @example Raising with context
+    #   raise Yes::Core::Error.new('could not resolve the aggregate', extra: { id: })
+    #
+    # @example Consuming the context safely
+    #   # #extra is not guaranteed to be a Hash - type-check before merging it.
+    #   payload.merge!(error.extra) if error.extra.is_a?(Hash)
     class Error < StandardError
+      # Caller-supplied context, returned exactly as it was given.
+      #
+      # It defaults to +nil+ and is never coerced or validated, so it may be any object the
+      # caller passed. Code that treats it as a Hash must therefore type-check first: a bare
+      # +payload.merge!(error.extra)+ raises +TypeError+ both for the +nil+ default and for any
+      # other non-Hash value. That matters most inside error-reporting hooks, where such a
+      # +TypeError+ tends to be swallowed by the reporter and takes the report down with it.
+      #
+      # @return [Object, nil] whatever the caller supplied; +nil+ when nothing was
       attr_reader :extra
 
+      # @param message [String, nil] the error message
+      # @param extra [Object, nil] arbitrary context to attach; stored as given
       def initialize(message = nil, extra: nil)
         super(message)
         @extra = extra

data/lib/yes/core/failed_subscription_notifier.rb

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

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

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

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

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

data/lib/yes/core/middlewares.rb

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

data/lib/yes/core/railtie.rb

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

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

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

data/lib/yes/core/types.rb

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

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

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

data/lib/yes/core/version.rb

@@ -2,6 +2,6 @@
 
 module Yes
   module Core
-    VERSION = '1.3.0'
+    VERSION = '2.3.0'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yes-core
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 2.3.0
 platform: ruby
 authors:
 - Nico Ritsche
@@ -127,14 +127,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '3.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
@@ -224,6 +224,7 @@ files:
 - lib/yes/core/authorization/cerbos_client_provider.rb
 - lib/yes/core/authorization/command_authorizer.rb
 - lib/yes/core/authorization/command_cerbos_authorizer.rb
+- lib/yes/core/authorization/lookup_cache.rb
 - lib/yes/core/authorization/read_model_authorizer.rb
 - lib/yes/core/authorization/read_models_authorizer.rb
 - lib/yes/core/authorization/read_request_authorizer.rb
@@ -241,6 +242,8 @@ files:
 - lib/yes/core/command_handling/read_model_recovery_service.rb
 - lib/yes/core/command_handling/read_model_revision_guard.rb
 - lib/yes/core/command_handling/read_model_updater.rb
+- lib/yes/core/command_handling/revision_conflict_backoff.rb
+- lib/yes/core/command_handling/revision_conflict_waiting.rb
 - lib/yes/core/command_handling/state_updater.rb
 - lib/yes/core/commands/bus.rb
 - lib/yes/core/commands/command_group.rb
@@ -267,6 +270,7 @@ files:
 - lib/yes/core/error_messages.rb
 - lib/yes/core/event.rb
 - lib/yes/core/event_class_resolver.rb
+- lib/yes/core/failed_subscription_notifier.rb
 - lib/yes/core/generators/read_models/add_pending_update_tracking_generator.rb
 - lib/yes/core/generators/read_models/templates/add_pending_update_tracking.rb.erb
 - lib/yes/core/generators/read_models/templates/migration.rb.erb
@@ -276,6 +280,7 @@ files:
 - lib/yes/core/middlewares/encryptor.rb
 - lib/yes/core/middlewares/timestamp.rb
 - lib/yes/core/middlewares/with_indifferent_access.rb
+- lib/yes/core/middlewares/write_encryptor.rb
 - lib/yes/core/models/application_record.rb
 - lib/yes/core/open_telemetry/otl_span.rb
 - lib/yes/core/open_telemetry/trackable.rb