yes-core 1.3.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a7213daeb56ae07a8921c83b912e83b7f9cd81f6d93d90a4394cbe07b7c9299
-  data.tar.gz: 58379a04830d2ba08c0ca4431d4e372ee8cc67f8445621d7143c61f1dc27ab9a
+  metadata.gz: 4845d0466658aee907edb5bab0679603e25a9b5c088a8df067d0fbfcc060bff4
+  data.tar.gz: cca505e973fa99d5b8e4b07c44752b78b330fdc0035b45528c83139ee36a0e4b
 SHA512:
-  metadata.gz: f5ce8a14fb78e7c9bc1b11264e16a17f0cbdc0ef3dcbbd7175114a1c772097b67cb1226f359429a6be83900f26d0e911dd18df838aa9c9ad5a76cab5d999b889
-  data.tar.gz: 01de285d8c90f81625bdd1ff721877b87d23edad1949b1eb860ebd4fc0274c459fbbeb3080e6ecb678fa1cd0174b010b4eb4f146ff00d6e4bea4be935685bb08
+  metadata.gz: '08121024f7bb36c1bb17281d772c907f4c1e9c119437caf6642c0461fcc9ce2d434c15fa6dc548ec8c6362b520b5144f8869d7054c8e9a110e33a984d757fd63'
+  data.tar.gz: b2b2bcbf061918d7876e27c6014d41adfe1ed5133163a078d09a31490219105a57f47699c5bd2d6c9d3400c12df527c13e2d0f76d64b32f1d4a2b1aaec1b4b8f

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 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.

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_group_executor.rb

@@ -169,7 +169,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
 
@@ -111,10 +112,14 @@ module Yes
 
             next if normalized_revision == expected_revision
 
+            # pg_eventstore 3.0 requires `verdict:`, which selects the error's
+            # message. This branch is only reached when the revision we hold
+            # differs from the store's, which is exactly :unmatched_stream_revision.
             raise PgEventstore::WrongExpectedRevisionError.new(
               revision: aggregate_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/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)
@@ -198,7 +199,12 @@ module Yes
           # @param expected_revision [Integer]
           # @param stream [PgEventstore::Stream]
           def revision_error!(revision, expected_revision, stream)
-            PgEventstore::WrongExpectedRevisionError.new(revision:, expected_revision:, stream:).tap do |error|
+            # pg_eventstore 3.0 requires `verdict:`, which selects the error's
+            # message. verify_revisions! only calls this when the two revisions
+            # differ, which is exactly :unmatched_stream_revision.
+            PgEventstore::WrongExpectedRevisionError.new(
+              revision:, expected_revision:, stream:, verdict: :unmatched_stream_revision
+            ).tap do |error|
               self.class.current_span&.status = ::OpenTelemetry::Trace::Status.error('Wrong expected revision')
               self.class.current_span&.add_attributes(
                 {
@@ -277,7 +283,7 @@ module Yes
               timestamp: result.created_at,
               attributes: {
                 'event.type' => result.type,
-                'event.link_id' => result.link_id || '',
+                'event.link_global_position' => result.link_global_position || '',
                 'global_position' => result.global_position,
                 'stream' => result.stream.to_json,
                 'stream.revision' => result.stream_revision,

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

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

data/lib/yes/core/configuration.rb

@@ -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/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.2.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.2.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
@@ -267,6 +268,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 +278,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