yes 0.0.1 → 2.2.0

data/README.md

@@ -0,0 +1,2282 @@
+# Yes
+
+Yes is a framework for building event-sourced systems, originally developed to power Switzerland's leading apprenticeship platform [yousty.ch](https://www.yousty.ch/de-CH) and its younger sibling [professional.ch](https://www.professional.ch/). It is designed to be used within Rails applications and relies on [PgEventstore](https://github.com/yousty/pg_eventstore) for event storage, which provides a robust PostgreSQL-based event store implementation.
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Naming Conventions](#naming-conventions)
+- [Aggregate DSL](#aggregate-dsl)
+  - [attribute](#attribute)
+  - [command](#command)
+  - [Attribute Details](#attribute-details)
+  - [Command Details](#command-details)
+  - [Guards](#guards)
+  - [Command Groups](#command-groups)
+  - [Read Models](#read-models)
+  - [Parent Aggregates](#parent-aggregates)
+  - [Primary Context](#primary-context)
+  - [Removable](#removable)
+  - [Draftable](#draftable)
+- [Authorization](#authorization)
+  - [Auth Adapter](#auth-adapter)
+  - [Aggregate Authorization](#aggregate-authorization)
+  - [Command Authorization](#command-authorization)
+  - [Cerbos Authorization](#cerbos-authorization)
+- [Command API](#command-api)
+  - [Command API Installation](#command-api-installation)
+  - [Request Format](#request-format)
+  - [Command Class Resolution](#command-class-resolution)
+  - [Processing Pipeline](#processing-pipeline)
+  - [Using Commands Without the DSL](#using-commands-without-the-dsl)
+  - [Real-Time Command Notifications](#real-time-command-notifications)
+- [Read API](#read-api)
+  - [Read API Installation](#read-api-installation)
+  - [Basic Queries](#basic-queries)
+  - [Advanced Queries](#advanced-queries)
+  - [Filters](#filters)
+  - [Read API Authorization](#read-api-authorization)
+  - [Serializers](#serializers)
+- [Event Processing](#event-processing)
+  - [Subscriptions](#subscriptions)
+  - [Process Managers](#process-managers)
+- [Configuration Reference](#configuration-reference)
+- [Testing](#testing)
+  - [Aggregate Test DSL](#aggregate-test-dsl)
+  - [DSL Methods](#dsl-methods)
+  - [Command Group Test DSL](#command-group-test-dsl)
+  - [Event Helpers](#event-helpers)
+  - [Aggregate Matchers](#aggregate-matchers)
+- [Development](#development)
+  - [Example Usage](#example-usage)
+  - [Testing the APIs](#testing-the-apis)
+  - [Running Specs](#running-specs)
+  - [Gem Installation and Release](#gem-installation-and-release)
+- [Contributing](#contributing)
+
+## Quick Start
+
+### Installation
+
+Add this line to your application's Gemfile to pull in the whole framework (`yes-core`, `yes-auth`, `yes-command-api`, `yes-read-api`):
+
+```ruby
+gem 'yes'
+```
+
+Or depend on individual sub-gems if you only need parts of the framework:
+
+```ruby
+gem 'yes-core'        # aggregate DSL, events, read models
+gem 'yes-auth'        # authorization principals + Cerbos integration
+gem 'yes-command-api' # HTTP command endpoint
+gem 'yes-read-api'    # HTTP read endpoints
+```
+
+Then execute:
+```bash
+bundle install
+```
+
+> **Note on the gem name:** versions `0.0.x` of `yes` on RubyGems were an unrelated project (a small CLI). Starting with `1.x` the gem name belongs to this framework. If you previously had `gem 'yes'` in a Gemfile and want the old project, pin to `'< 1.0'`.
+
+### Basic Usage
+
+At the core of Yes is the `Yes::Core::Aggregate` class, which provides a DSL for defining event-sourced aggregates:
+
+```ruby
+module Users
+  module User
+    class Aggregate < Yes::Core::Aggregate
+      # Link to a parent aggregate — generates an `assign_company` command
+      # and a `company_id` attribute automatically
+      parent :company
+
+      # `change` commands are the most common — use the `:change` shortcut
+      command :change, :name # the type defaults to :string
+      command :change, :email, :email
+
+      attribute :email_confirmed, :boolean
+
+      # A custom command: its own payload, guard, and state update
+      command :confirm_email do
+        payload token: :string
+
+        guard :token_valid do
+          EmailConfirmationService.valid?(payload.token, id)
+        end
+
+        update_state do
+          email_confirmed { true }
+        end
+      end
+    end
+  end
+end
+
+# Usage
+user = Users::User::Aggregate.new
+user.assign_company(company_id: "123e4567-e89b-12d3-a456-426614174000")
+user.change_name("John Doe")
+user.confirm_email(token: "abc123")
+```
+
+See [Command shortcuts](#command-shortcuts) for the full list of shortcut forms (`:change`, `:enable`/`:disable`, `:activate`, `:publish`, …).
+
+## Naming Conventions
+
+When defining an aggregate, use the following namespacing pattern:
+`<Context>::<AggregateName>::Aggregate`
+
+For example: `Users::User::Aggregate` or `Companies::Company::Aggregate`
+
+## Aggregate DSL
+
+### `attribute`
+
+The `attribute` method defines properties of your aggregate:
+
+```ruby
+module Users
+  module User
+    class Aggregate < Yes::Core::Aggregate
+      # Plain attributes — accessors only, no change command
+      attribute :name, :string
+      attribute :email, :email
+      attribute :company_id, :uuid
+    end
+  end
+end
+```
+
+Plain `attribute` declarations define accessors on the aggregate and columns on the read model. They do **not** generate a change command.
+
+To generate a change command along with the attribute, use the [`command :change` shortcut](#change-command-with-attribute):
+
+```ruby
+command :change, :age, :integer
+command :change, :bio, :string
+```
+
+### `command`
+
+The `command` method defines custom operations on your aggregate:
+
+```ruby
+module Companies
+  module Company
+    class Aggregate < Yes::Core::Aggregate
+      # Define attributes that will be updated by the command
+      attribute :user_ids, :uuids
+
+      command :assign_user do
+        # Define payload attributes
+        payload user_id: :uuid
+
+        guard :user_not_already_assigned do
+          !user_ids.include?(payload.user_id)
+        end
+
+        # Custom state update logic
+        update_state do
+          user_ids { (user_ids || []) + [payload.user_id] }
+        end
+      end
+    end
+  end
+end
+```
+
+### Attribute Details
+
+Attributes are the core properties of your aggregates.
+
+#### Available Types
+
+The attribute system supports various types:
+- `:string` - Text values
+- `:email` - Email addresses with validation
+- `:uuid` - UUID values
+- `:integer` - Numeric values
+- `:boolean` - True/false values
+- `:date` - Date values
+- `:uuids` - Arrays of UUIDs
+
+For the complete list, see [yes-core/lib/yes/core/type_lookup.rb](yes-core/lib/yes/core/type_lookup.rb)
+
+#### Custom Types
+
+You can register application-specific types using the type registry:
+
+```ruby
+# config/initializers/yes_types.rb
+Yes::Core::Types.register(:subscription_type, Yes::Core::Types::String.enum('premium', 'basic'))
+Yes::Core::Types.register(:team_role, Yes::Core::Types::String.enum('lead', 'member'))
+Yes::Core::Types.register(:training_year, Yes::Core::Types::Coercible::Integer.constrained(gteq: 1, lteq: 4))
+```
+
+Registered types can then be used in aggregate definitions:
+
+```ruby
+attribute :role, :team_role
+# or, to also generate a change command:
+command :change, :role, :team_role
+```
+
+#### Attribute Commands
+
+When you generate a change command for an attribute (via the [`command :change` shortcut](#change-command-with-attribute), or the legacy `attribute ..., command: true` option), Yes generates:
+
+##### `change_<attribute>` Method
+
+Changes the attribute's value through an event:
+
+```ruby
+user.change_age(30)
+user.change_bio("Software developer")
+```
+
+You can also pass parameters as a hash:
+
+```ruby
+user.change_age(age: 30)
+```
+
+##### `can_change_<attribute>?` Method
+
+Validates a potential change without applying it:
+
+```ruby
+# Valid change
+if user.can_change_email?("user@example.com")
+  user.change_email("user@example.com")
+end
+
+# Invalid change
+user.can_change_email?("invalid-email") # => false
+user.email_change_error # Contains the error message
+```
+
+### Command Details
+
+Commands define operations that can be performed on your aggregate.
+
+#### Command Configuration Options
+
+##### Payload
+
+Define the input data for your command:
+
+```ruby
+command :register_apprenticeship do
+  payload title: :string,
+          start_date: :date,
+          location_id: :uuid
+end
+```
+
+Make sure the payload keys are all defined as attributes on the aggregate if you don't supply an `update_state` block.
+
+**Optional and Nullable Attributes**
+
+You can mark payload attributes as optional (key can be omitted) or nullable (value can be nil) using hash syntax:
+
+```ruby
+command :update_profile do
+  # Optional key - attribute can be omitted from payload
+  payload phone: { type: :string, optional: true },
+          # Nullable value - attribute must be present but can be nil
+          max_travel_time: { type: :integer, nullable: true },
+          # Both optional key and nullable value
+          email: { type: :email, optional: true, nullable: true }
+end
+```
+
+- `optional: true` - The key can be omitted from the command payload (for commands) or event data (for events)
+- `nullable: true` - The value can be `nil` (wraps the type with `.maybe` for commands, uses `.maybe()` for events)
+
+**Note**: For commands, nullable attributes are automatically unwrapped from `Dry::Monads::Maybe::Some/None` when accessing `command.payload` to ensure compatibility with event creation.
+
+##### Guards
+
+Add validation rules with guards:
+
+```ruby
+command :publish do
+  guard :all_required_fields_present do
+    title.present? && description.present?
+  end
+
+  guard :not_already_published do
+    !published
+  end
+end
+```
+
+##### Custom Event Names
+
+Customize the generated event name:
+
+```ruby
+command :publish do
+  event :apprenticeship_published
+end
+```
+
+When no custom event name is provided, *Yes* automatically generates an event name based on the command name. Currently, only standard command prefixes are supported. If you use a command that doesn't start with a supported prefix, you must specify the event name explicitly. For a list of supported prefixes, see [lib/yes/core/utils/event_name_resolver.rb](yes-core/lib/yes/core/utils/event_name_resolver.rb).
+
+##### Encrypting Event Payload Attributes
+
+Yes supports encrypting sensitive data in events. You can mark payload attributes for encryption using three approaches:
+
+**1. Inline Encryption Declaration (Recommended for mixed payloads)**
+
+```ruby
+command :update_contact_info do
+  payload email: { type: :email, encrypt: true },
+          phone: { type: :phone, encrypt: true },
+          address: :string  # not encrypted
+end
+```
+
+**2. Separate `encrypt` Method (Recommended for multiple encrypted fields)**
+
+```ruby
+command :update_sensitive_data do
+  payload ssn: :string, email: :email, phone: :phone
+  encrypt :ssn, :email, :phone
+end
+```
+
+**3. Command Shortcut with `encrypt` Option**
+
+```ruby
+# For simple attribute commands
+command :change, :ssn, :string, encrypt: true
+```
+
+**Important Notes:**
+- Encryption applies to the event payload stored in the event store, not to the aggregate state or read models
+- Encrypted attributes are tracked in the generated event class via an `encryption_schema` class method
+- You can combine inline and separate encryption declarations in the same command
+- The encryption key is automatically derived from the aggregate ID
+
+###### Required Setup: Key Repository
+
+Encryption is performed by a PgEventstore middleware that delegates the actual key management and cryptography to a `key_repository` object you provide. *Yes* does not ship a concrete implementation — you plug in any object that satisfies the interface below.
+
+Register the middlewares:
+
+```ruby
+PgEventstore.configure do |config|
+  Yes::Core::Middlewares.register_encryptor(key_repository, config:)
+end
+```
+
+This registers two middlewares against your repository: `:encryptor`, which decrypts events as they are read, and `:write_encryptor`, which encrypts identically but does not decrypt. pg_eventstore runs `#deserialize` on the event returned by `#append_to_stream` too, and nothing on the write path reads that event's data — so *Yes* appends with `middlewares: Yes::Core::Middlewares.for_write`, and your `key_repository` is never asked to decrypt a payload that is about to be discarded. Always register through `register_encryptor`: registering `:encryptor` alone silently costs a key lookup and a decrypt on every encrypted write.
+
+One consequence worth knowing: **the event returned by a command is encrypted**. Read the event back when you need its plaintext.
+
+The `key_repository` must respond to the following methods, each returning a [`Dry::Monads::Result`](https://dry-rb.org/gems/dry-monads/) (or any object responding to `success?`, `failure?`, and `value!`):
+
+| Method | Purpose | Returns (on success) |
+| --- | --- | --- |
+| `find(key_id)` | Look up an existing key by its identifier (the aggregate ID). | A key object responding to `attributes[:iv]`. |
+| `create(key_id)` | Create a new key for the given identifier. Called when `find` returns a failure. | A key object responding to `attributes[:iv]`. |
+| `encrypt(key:, message:)` | Encrypt the serialized JSON of the attributes marked for encryption. | An object responding to `attributes[:message]` containing the ciphertext. |
+| `decrypt(key:, message:)` | Decrypt a previously encrypted payload. | An object responding to `attributes[:message]` containing the plaintext JSON. |
+
+This interface intentionally decouples *Yes* from any specific key management or crypto backend. You can back it with AWS KMS, HashiCorp Vault, libsodium, ActiveRecord::Encryption, or any other solution that fits your deployment.
+
+For a minimal reference implementation used in the test suite (Base64 + in-memory store, not production-ready), see [`yes-core/spec/support/dummy_repository.rb`](yes-core/spec/support/dummy_repository.rb).
+
+##### Custom State Updates
+
+Define exactly how state should change:
+
+```ruby
+command :add_tag do
+  payload tag: :string
+
+  update_state do
+    tags { (tags || []) + [payload.tag] }
+  end
+end
+```
+
+You can also use the `update_state` method to update multiple attributes at once:
+
+```ruby
+update_state do
+  name { payload.name }
+  email { payload.email }
+end
+```
+
+Make sure the attributes updated in the `update_state` block are all defined on the aggregate.
+
+For commands whose work is side-effect-only (e.g. writing to a related ActiveRecord model) and does not assign to any aggregate attribute, use `update_state custom: true` — see [Side-Effect State Updates](#3-side-effect-state-updates-update_state-custom-true).
+
+#### State Update Behavior
+
+Commands update the aggregate state in one of two ways:
+
+##### 1. Automatic State Updates (Without `update_state` Block)
+
+If you don't define an `update_state` block, the command will automatically update the aggregate's attributes based on the payload:
+
+```ruby
+module Companies
+  module Company
+    class Aggregate < Yes::Core::Aggregate
+      # Define attributes that match the payload keys
+      attribute :name, :string
+      attribute :description, :string
+
+      command :update_details do
+        # Payload keys must match attribute names
+        payload name: :string,
+                description: :string
+        # No update_state block needed - automatic update
+      end
+    end
+  end
+end
+
+company = Companies::Company::Aggregate.new
+company.update_details(name: "Acme Inc", description: "Manufacturing company")
+# Both name and description attributes will be updated automatically
+```
+
+**Important**: When not using an `update_state` block:
+- All payload keys must be defined as attributes on the aggregate
+- The system will validate this and raise an error if there's a mismatch
+- The attribute values will be updated directly from the payload values
+
+##### 2. Custom State Updates (With `update_state` Block)
+
+When you define an `update_state` block, you have complete control over how attributes are updated:
+
+```ruby
+module Articles
+  module Article
+    class Aggregate < Yes::Core::Aggregate
+      attribute :title, :string
+      attribute :tags, :array
+      attribute :status, :string
+
+      command :publish do
+        payload title: :string
+
+        update_state do
+          # You can reference payload values
+          title { payload.title }
+          # Or set static values
+          status { "published" }
+          # Or combine existing data with payload
+          tags { (tags || []) + ["published"] }
+        end
+      end
+    end
+  end
+end
+```
+
+**Important**: When using an `update_state` block:
+- Payload keys don't need to match attribute names
+- However, all attributes updated in the block must be defined on the aggregate
+- The system will validate this and raise an error if an undefined attribute is updated
+- You have full control over transformation logic
+
+##### 3. Side-Effect State Updates (`update_state custom: true`)
+
+Sometimes a command needs to perform work that cannot be expressed as attribute assignments on the aggregate — for example, creating or updating related ActiveRecord records, writing to an associated read model, or otherwise producing side effects outside the aggregate itself. In those cases, pass `custom: true` to `update_state`:
+
+```ruby
+command :assign_ambassador do
+  payload team_member_id: :uuid
+
+  update_state custom: true do
+    attrs = { team_member_id: payload.team_member_id, apprenticeship_id: id }
+    ApprenticeshipTeamMemberAssociation.find_or_create_by(attrs).update(removed_at: nil)
+  end
+end
+```
+
+The `custom: true` flag changes how Yes treats the block:
+
+- The block analyzer is skipped, so Yes does not scan it for attribute assignments like `name { payload.name }`.
+- No aggregate attributes are recorded as updated by this command.
+- You are responsible for performing whatever side effects the command needs — Yes will not validate or track what happens inside.
+
+This also works with the [`command :change` shortcut](#change-command-with-attribute) when you want to override the default attribute assignment with custom side-effect logic:
+
+```ruby
+command :change, :status do # `:string` is the default type, so it can be omitted
+  update_state custom: true do
+    StatusRecord.find_or_create_by(aggregate_id: id).update(status: payload.status)
+  end
+end
+```
+
+Prefer regular `update_state` blocks whenever the change can be expressed as attribute updates on the aggregate — reach for `custom: true` only when side effects outside the aggregate are genuinely required.
+
+#### Generated Command Methods
+
+For each command, Yes generates:
+
+##### Command Method
+
+Executes the command:
+
+```ruby
+company.assign_user(user_id: "123e4567-e89b-12d3-a456-426614174000")
+```
+
+##### Can Command Method
+
+Validates if the command would succeed:
+
+```ruby
+if company.can_assign_user?(user_id: "123e4567-e89b-12d3-a456-426614174000")
+  company.assign_user(user_id: "123e4567-e89b-12d3-a456-426614174000")
+else
+  puts company.assign_user_error
+end
+```
+
+#### Command shortcuts
+
+For the most frequently used cases *Yes* DSL allows to use shortcuts in `command` definitions.
+
+##### Change command with attribute
+
+```ruby
+command :change, :age, :integer, localized: true
+```
+
+is expanded to
+
+```ruby
+  attribute :age, :integer, localized: true
+  command :change_age do
+    payload age: :integer, locale: :locale
+    guard(:no_change) { value_changed?(send(attribute_name), payload.send(attribute_name)) }
+  end
+```
+
+The type defaults to `:string`, so for string attributes it can be omitted:
+
+```ruby
+command :change, :name # equivalent to `command :change, :name, :string`
+```
+
+You can overwrite the default no change guard by providing a custom one:
+
+```ruby
+command :change, :age, :integer do
+  payload fantastic_new_age: :integer
+  guard(:no_change) { age != payload.fantastic_new_age }
+end
+```
+
+##### Boolean attribute command
+
+`:enable` and `:activate` command names are triggering this shortcut.
+
+```ruby
+command :activate, :dropout, attribute: :dropout_enabled
+```
+
+is expanded to
+
+```ruby
+  attribute :dropout_enabled, :boolean
+  command :activate_dropout do
+    guard(:no_change) { !dropout_enabled }
+    update_state { dropout_enabled { true } }
+  end
+```
+
+##### Toggle commands
+
+```ruby
+command [:enable, :disable], :dropout
+```
+
+is expanded to
+
+```ruby
+  attribute :dropout, :boolean
+  command :enable_dropout do
+    guard(:no_change) { !dropout }
+    update_state { dropout { true } }
+  end
+
+  command :disable_dropout do
+    guard(:no_change) { dropout }
+    update_state { dropout { false } }
+  end
+```
+
+##### Publish command
+
+```ruby
+command :publish
+```
+
+is expanded to
+
+```ruby
+  attribute :published, :boolean
+  command :publish do
+    guard(:no_change) { !published }
+    update_state { published { true } }
+  end
+```
+
+### Guards
+
+Guards are powerful validation mechanisms that enforce business rules by controlling when commands and attribute changes are permitted to execute. They act as gatekeepers that ensure all operations maintain the integrity of your domain logic.
+
+#### Default Guards
+
+Both commands and attributes automatically include a `:no_change` guard that ensures the aggregate's state would actually change when applying the command. For commands, this default guard is only active when there is no `update_state` block present in the command definition.
+
+#### Adding Guards to Attribute Change Commands
+
+When defining an attribute with a change command, you can add guards to implement validation by passing a block to the `command :change` shortcut:
+
+```ruby
+command :change, :email, :email do
+  guard :check_email_domain do
+    payload.email.end_with?('@example.com')
+  end
+end
+```
+
+#### Adding Guards to Commands
+
+Similarly, you can add guards to commands to control when they can execute:
+
+```ruby
+command :publish do
+  guard :all_required_fields_present do
+    title.present? && description.present?
+  end
+
+  guard :not_already_published do
+    !published
+  end
+end
+```
+
+Inside any guard block you can access:
+- `payload` - The command payload with access to both data and metadata
+- Any aggregate attribute directly by name
+
+##### Accessing Metadata in Guards
+
+The payload object in guards provides access to command metadata alongside the regular payload data. This metadata can contain useful contextual information like user information, or tracking data.
+
+You can access metadata in two ways:
+
+```ruby
+command :update_status do
+  payload status: :string
+
+  guard :valid_response do
+    # Method-style access
+    payload.metadata.response_id.present?
+
+    # Hash-style access
+    payload.metadata[:response_id].present?
+  end
+
+  guard :authorized_user do
+    # If a metadata key doesn't exist, nil is returned
+    payload.metadata.user_role == 'admin' # returns nil if user_role is not in metadata
+  end
+end
+```
+
+This allows guards to make decisions based on both the command's data payload and any additional contextual metadata that was provided when the command was issued.
+
+#### Guard Error Types
+
+Guards have two distinct behaviors based on their name:
+
+- Guards named `:no_change` trigger a **no-change transition** error when they fail. This indicates that the operation would not modify the aggregate's state.
+- All other guard names trigger an **invalid transition** error when they fail. This indicates that the operation is not allowed in the current state.
+
+```ruby
+command :update_profile do
+  payload bio: :string
+
+  # Will trigger a no-change transition error if bio hasn't changed
+  guard :no_change do
+    payload.bio != bio
+  end
+
+  # Will trigger an invalid transition error if bio contains prohibited words
+  guard :appropriate_content do
+    !payload.bio.include?("prohibited content")
+  end
+end
+```
+
+#### Custom Error Messages
+
+You can provide custom localized error messages for guards using I18n translation files:
+
+```yaml
+# config/locales/en.yml
+en:
+  aggregates:
+    test: # context
+      apprenticeship: # aggregate
+        commands:
+          change_location: # command
+            guards:
+              location_published: # guard
+                error: "Location is not published"
+              company_matches:
+                error: "Location company does not match apprenticeship company"
+```
+
+This allows you to define human-readable error messages that can be easily translated to different languages. These messages will be used instead of the default error messages when a guard fails.
+
+### Command Groups
+
+A `command_group` is a compound action that runs several existing aggregate commands as a single atomic unit. It's useful when multiple commands are always executed together and the per-command guards would be redundant or too restrictive for the compound flow.
+
+```ruby
+module Companies
+  module Apprenticeship
+    class Aggregate < Yes::Core::Aggregate
+      attribute :name, :string, command: true
+      attribute :description, :string, command: true
+      parent :company
+      parent :user
+      draftable
+      command :publish
+
+      command_group :create_apprenticeship do
+        command :assign_company
+        command :assign_user
+        command :change_name
+        command :change_description
+        command :publish
+
+        guard(:company_assigned) { payload.company_id.present? }
+        guard(:user_assigned)    { payload.user_id.present? }
+      end
+    end
+  end
+end
+
+aggregate.create_apprenticeship(
+  company_id:, user_id:, name:, description:
+)
+# => Yes::Core::Commands::CommandGroupResponse(cmd:, events: [...], error: nil)
+```
+
+**How it works:**
+
+- `command :sub_name` inside the block lists existing aggregate commands by symbol. Order is preserved as execution order.
+- `guard(:name) { … }` declares group-level guards using the same DSL as per-command guards. They run against the aggregate's current state at invocation time.
+- Sub-command symbols are resolved lazily — declare the group before or after the individual commands, the framework checks consistency at the end of the class body.
+- When invoked, the group:
+  1. Evaluates only the group's guards (sub-command guards are fully skipped).
+  2. Publishes one event per sub-command, in declaration order, inside a single `PgEventstore.client.multiple` transaction at serializable isolation — either all events commit or none do.
+  3. Updates the read model after the eventstore commit, in declaration order, so each sub-command's state-updater sees the cumulative state from the previous ones.
+- The first sub-event uses `expected_revision` + external-aggregate revision verification (same optimistic-concurrency machinery as the per-command flow), so a concurrent writer that committed between guard evaluation and publish raises `WrongExpectedRevisionError` and the executor retries with fresh guard evaluation.
+- Subsequent sub-events within the transaction use `expected_revision: :any` — atomicity and sequencing are guaranteed by the surrounding `multiple` block.
+
+**Payload model:**
+
+`command_group` accepts a flat hash (most common, single-aggregate case), subject-nested form, or context-nested form — same three-form normalization as the legacy `Yes::Core::Commands::Group`. The flat form distributes attributes to each sub-command by name match:
+
+```ruby
+# Flat — recommended for single-aggregate groups
+aggregate.create_apprenticeship(
+  company_id: '...', user_id: '...', name: 'Acme', description: 'Best'
+)
+```
+
+Each sub-command receives the subset of keys it declares as payload attributes. The aggregate's `<aggregate>_id` is injected automatically.
+
+**`can_<group_name>?`:**
+
+For every `command_group`, the aggregate also gets a predicate that runs the group's guards without publishing events:
+
+```ruby
+aggregate.can_create_apprenticeship?(company_id:, user_id:, name:, description:)
+# => true / false
+```
+
+**Response shape:**
+
+```ruby
+response = aggregate.create_apprenticeship(payload)
+response.success?  # => true / false
+response.events    # => Array<PgEventstore::Event> in declaration order
+response.error     # => the GuardEvaluator::TransitionError if any (nil on success)
+response.cmd       # => the CommandGroup instance
+```
+
+**Generated artifacts:**
+
+A `command_group :foo` macro on `Context::Aggregate` generates:
+
+- `Context::Aggregate::CommandGroups::Foo::Command` — a `Yes::Core::Commands::CommandGroup` subclass
+- `Context::Aggregate::CommandGroups::Foo::GuardEvaluator` — a `Yes::Core::CommandHandling::GuardEvaluator` subclass holding the group's guards
+- `Aggregate#foo(payload, guards:, metadata:)` — the invocation method
+- `Aggregate#can_foo?(payload)` — the predicate
+- `Aggregate#foo_error` accessor — mirrors the per-command error accessor pattern
+
+The legacy stateless `Yes::Core::Commands::Group` / `Yes::Core::Commands::Stateless::GroupHandler` are untouched and continue to serve cross-aggregate use cases declared outside the aggregate DSL.
+
+**Invoking via the Command API:** command groups are dispatchable over HTTP exactly like regular commands. POST to `/v1/commands` with the standard request shape — `command` is the group name (camelized), `data` is the flat payload (same as the Ruby invocation form):
+
+```json
+{
+  "commands": [
+    {
+      "context": "Companies",
+      "subject": "Apprenticeship",
+      "command": "CreateApprenticeship",
+      "data": {
+        "company_id": "...",
+        "user_id": "...",
+        "name": "Acme Apprenticeship",
+        "description": "Software dev role"
+      }
+    }
+  ]
+}
+```
+
+The Deserializer resolves the group's `Command` class via the registered `Context::Aggregate::CommandGroups::<Name>::Command` namespace. Authorization and validation run per-sub-command (each sub-command's existing `Authorizer` and `Validator` are invoked, exactly like the legacy stateless `Group` flow), and the group dispatches as a single atomic unit through the bus.
+
+### Read Models
+
+Each aggregate automatically gets a corresponding read model (ActiveRecord model) that persists its current state. This is how you access attribute values from an aggregate.
+
+```ruby
+user = Users::User::Aggregate.new
+user.change_name("Jane Doe")
+user.name # => "Jane Doe" (reads from the read model)
+```
+
+#### Default Naming
+
+By default, the read model's name is derived from the aggregate's context and name:
+
+```ruby
+# For Users::User::Aggregate
+# The read model class will be UsersUser
+# And the database table will be users_users
+```
+
+#### Customizing Read Models
+
+You can customize the read model name and visibility using the `read_model` method:
+
+```ruby
+module Users
+  module User
+    class Aggregate < Yes::Core::Aggregate
+      # Use a custom read model name
+      read_model 'custom_user', public: false
+
+      command :change, :email, :email
+      attribute :name, :string
+    end
+  end
+end
+```
+
+In this example:
+- The read model class will be `CustomUser` instead of `UsersUser`
+- The database table will be `custom_users`
+- `public: false` means this read model won't be accessible via the read API
+
+#### Read Model Schema Generator
+
+When you add or remove aggregates or attributes, you need to update your database schema. Yes provides a Rails generator for this:
+
+```shell
+rails generate yes:core:read_models:update
+```
+
+This will:
+1. Find all aggregates in your application
+2. Create migration files that update read model tables to match your aggregate definitions
+3. Add, modify, or remove columns as needed
+
+Example generated migration:
+
+```ruby
+class UpdateReadModels < ActiveRecord::Migration[7.1]
+  def change
+    create_table :users do |t|
+      t.string :name
+      t.string :email
+      t.integer :age
+      t.integer :revision, null: false, default: -1
+      t.timestamps
+    end
+
+    add_column :companies, :name, :string
+    remove_column :companies, :old_field
+  end
+end
+```
+
+##### Type Mapping
+
+Attribute types are mapped to database column types as follows:
+- `:string`, `:email`, `:url` → `:string`
+- `:integer` → `:integer`
+- `:uuid` → `:uuid`
+- `:boolean` → `:boolean`
+- `:hash` → `:jsonb`
+- `:aggregate` → `:uuid` (stored as `<attribute_name>_id`)
+
+#### Pending Update Tracking Generator
+
+To ensure read model consistency and enable recovery from failures during event processing, Yes provides a generator that adds pending update tracking to your read models:
+
+```shell
+rails generate yes:core:read_models:add_pending_update_tracking
+```
+
+This generator creates a migration that:
+1. Adds a `pending_update_since` column to all read model tables
+2. Creates indexes to efficiently track and recover stale pending updates
+3. Automatically handles PostgreSQL's 63-character index name limit by truncating long names
+
+##### What It Does
+
+The pending update tracking system helps prevent read models from getting stuck in an inconsistent state by:
+- Marking read models as "pending" before event publication
+- Clearing the pending state after successful updates
+- Allowing automatic recovery of stale pending states (default timeout: 5 minutes)
+
+##### Generated Migration Example
+
+```ruby
+class AddPendingUpdateTrackingToReadModels < ActiveRecord::Migration[7.1]
+  def up
+    read_model_tables = Yes::Core.configuration.all_read_model_table_names
+
+    read_model_tables.each do |table_name|
+      next unless ActiveRecord::Base.connection.table_exists?(table_name)
+
+      add_column table_name, :pending_update_since, :datetime
+
+      # Unique index to prevent concurrent updates to same aggregate
+      add_index table_name, :id,
+                unique: true,
+                where: 'pending_update_since IS NOT NULL',
+                name: truncate_index_name("idx_#{table_name}_one_pending_per_aggregate")
+
+      # Index for efficient recovery queries
+      add_index table_name, :pending_update_since,
+                where: 'pending_update_since IS NOT NULL',
+                name: truncate_index_name("idx_#{table_name}_pending_recovery")
+    end
+  end
+end
+```
+
+##### Recovery Job
+
+You can schedule a background job to automatically recover stale pending updates:
+
+```ruby
+# app/jobs/read_model_recovery_job.rb
+class ReadModelRecoveryJob < ApplicationJob
+  def perform
+    Yes::Core::Jobs::ReadModelRecoveryJob.new.perform
+  end
+end
+
+# Schedule it to run periodically (e.g., every 5 minutes)
+# In your scheduler (whenever, sidekiq-cron, etc.):
+ReadModelRecoveryJob.perform_later
+```
+
+##### Manual Recovery
+
+You can also manually trigger recovery for specific read models:
+
+```ruby
+# Recover a specific read model instance
+read_model = UserReadModel.find(id)
+Yes::Core::CommandHandling::ReadModelRecoveryService.recover(read_model)
+
+# Recover all stale pending updates (older than 5 minutes by default)
+Yes::Core::CommandHandling::ReadModelRecoveryService.recover_all_stale
+```
+
+### Parent Aggregates
+
+Link aggregates in a hierarchy:
+
+```ruby
+module Companies
+  module Location
+    class Aggregate < Yes::Core::Aggregate
+      parent :company
+
+      command :change, :name, :string
+      command :change, :address, :string
+    end
+  end
+end
+```
+
+The parent method defines an assign command with its attribute by default.
+For the above example it will be `assign_company` with `company_id` attribute.
+
+#### command option
+
+Set parent command option to false to skip defining assign command:
+
+```ruby
+parent :company, command: false
+```
+
+### Primary Context
+
+Specify the main context:
+
+```ruby
+module Users
+  module User
+    class Aggregate < Yes::Core::Aggregate
+      primary_context :users
+
+      command :change, :name, :string
+    end
+  end
+end
+```
+
+### Removable
+
+Define a default removal behavior for an aggregate:
+
+```ruby
+module Users
+  module User
+    class Aggregate < Yes::Core::Aggregate
+      removable
+    end
+  end
+end
+```
+
+It defines a `remove` command which works with the `removed_at` attribute by default and
+applies a default removal behavior.
+
+The `removable` method accepts a custom name for an attribute which will also be used for
+the removal behavior. You can see an example below.
+
+```ruby
+module Users
+  module User
+    class Aggregate < Yes::Core::Aggregate
+      removable(attr_name: :deleted_at)
+    end
+  end
+end
+```
+
+You can also define additional guards or custom behavior:
+
+```ruby
+module Users
+  module User
+    class Aggregate < Yes::Core::Aggregate
+      removable do
+        guard(:published) { published? }
+      end
+    end
+  end
+end
+```
+
+#### Auto-injected `:not_removed` guard
+
+Calling `removable` does more than define the `remove` command: by default it also auto-blocks
+every other command on the aggregate while the removal attribute is set. The check fires
+*before* any registered guard (including the auto-injected `:no_change`), so post-remove
+mutations consistently raise `Yes::Core::CommandHandling::GuardEvaluator::InvalidTransition`
+with the i18n message under
+`aggregates.<context>.<aggregate>.commands.<command>.guards.not_removed.error`.
+
+```ruby
+module Users
+  module User
+    class Aggregate < Yes::Core::Aggregate
+      removable
+
+      command :change, :name, :string
+    end
+  end
+end
+
+agg = Users::User::Aggregate.new
+agg.change_name(name: 'Alice') # => success
+agg.remove
+agg.change_name(name: 'Bob')   # => blocked: InvalidTransition (:not_removed)
+```
+
+The `:remove` command itself is exempt — it remains gated only by its existing `:no_change`
+guard, so calling `remove` twice still raises `NoChangeTransition` as before.
+
+The check is order-independent: `removable` may be declared before or after the other
+commands on the aggregate.
+
+##### Opting out at the aggregate level
+
+Pass `not_removed_guards: false` to disable the auto-block for the entire aggregate (commands
+will continue to fire normally after `remove`):
+
+```ruby
+module Users
+  module User
+    class Aggregate < Yes::Core::Aggregate
+      removable(not_removed_guards: false)
+
+      command :change, :name, :string
+    end
+  end
+end
+```
+
+##### Opting out per command
+
+Pass `skip_default_guards: %i[not_removed]` to a single `command` or `parent` to exempt just
+that command:
+
+```ruby
+module Users
+  module User
+    class Aggregate < Yes::Core::Aggregate
+      removable
+
+      # Bypass the auto-block for this one command.
+      command :restore, skip_default_guards: %i[not_removed] do
+        guard(:no_change) { removed_at.present? }
+        update_state { removed_at { nil } }
+      end
+
+      parent :tenant, skip_default_guards: %i[not_removed]
+    end
+  end
+end
+```
+
+### Draftable
+
+The `draftable` feature allows aggregates to be created and modified in a draft state before being published. This is useful when you want to prepare changes without immediately making them live.
+
+```ruby
+module Articles
+  module Article
+    class Aggregate < Yes::Core::Aggregate
+      # Makes aggregate draftable by connecting it to a draft aggregate for managing the draft state.
+      # The draft aggregate has to exist already. The default draft aggregate is <CurrentAggregateContext>::<CurrentAggregateName>Draft.
+      # Also configures a changes read model (defaults to "<read_model>_change")
+      draftable
+
+      # Draftable with custom parameters
+      # draftable draft_aggregate: { context: 'ArticleDrafts', aggregate: 'ArticleDraft' }, changes_read_model: :article_change
+
+      command :change, :title, :string
+      command :change, :content, :string
+    end
+  end
+end
+```
+
+#### Method Parameters
+
+The `draftable` method accepts two optional parameters:
+
+- `draft_aggregate`: A hash containing the draft aggregate configuration
+  - `context`: The context name for the draft version (defaults to the same context as the main aggregate)
+  - `aggregate`: The aggregate name for the draft version (defaults to the main aggregate name with "Draft" suffix)
+- `changes_read_model`: The name for the changes read model (defaults to the main read model name with "_change" appended)
+
+#### Example Usage
+
+```ruby
+# Use all defaults
+draftable
+
+# Custom context only
+draftable draft_aggregate: { context: 'DraftContext' }
+
+# Custom aggregate name only
+draftable draft_aggregate: { aggregate: 'MyDraft' }
+
+# Both context and aggregate
+draftable draft_aggregate: { context: 'DraftContext', aggregate: 'MyDraft' }
+
+# Custom changes read model only
+draftable changes_read_model: :custom_changes
+
+# All custom parameters
+draftable draft_aggregate: { context: 'DraftContext', aggregate: 'MyDraft' }, changes_read_model: :my_changes
+```
+
+When `changes_read_model` is not specified, it defaults to using the main read model name with "_change" appended (e.g., if the read model is "article", the changes read model becomes "article_change").
+
+## Authorization
+
+### Auth Adapter
+
+Both the [Command API](#command-api) and [Read API](#read-api) delegate authentication to a configurable adapter. Configure it in an initializer:
+
+```ruby
+# config/initializers/yes.rb
+Yes::Core.configure do |config|
+  config.auth_adapter = MyAuthAdapter.new
+end
+```
+
+The adapter must implement three methods:
+
+| Method | Purpose | Called by |
+|--------|---------|----------|
+| `authenticate(request)` | Verify the JWT token and return an auth data hash. Raise a `Yes::Core::AuthenticationError` subclass on failure. | Both API controllers (before every request) |
+| `verify_token(token)` | Decode a raw JWT token string. Return an object responding to `.token` that returns `[decoded_payload_hash]`. | MessageBus user identification |
+| `error_classes` | Return an array of exception classes that represent authentication failures. | Command API controller (to rescue and render 401) |
+
+#### How It Works
+
+1. On every request, the controller calls `adapter.authenticate(request)`.
+2. The returned hash is stored as `auth_data` and passed to command authorizers, read request authorizers, and read model authorizers throughout the request lifecycle.
+3. The hash must include at minimum an `:identity_id` key, which is used for command metadata, MessageBus channel defaults, and authorization.
+
+#### Example Implementation
+
+```ruby
+class MyAuthAdapter
+  AuthError = Class.new(Yes::Core::AuthenticationError)
+
+  # @param request [ActionDispatch::Request]
+  # @raise [AuthError] if the token is missing or invalid
+  # @return [Hash] auth data passed to authorizers as auth_data
+  def authenticate(request)
+    token = request.headers['Authorization']&.delete_prefix('Bearer ')
+    raise AuthError, 'Token missing' unless token
+
+    payload = JWT.decode(token, public_key, true, algorithm: 'RS256').first
+    { identity_id: payload['sub'], host: request.host }.merge(payload.symbolize_keys)
+  end
+
+  # @param token [String] raw JWT token (extracted from Authorization header)
+  # @return [OpenStruct] object with .token returning [decoded_payload_hash]
+  def verify_token(token)
+    decoded = JWT.decode(token, public_key, true, algorithm: 'RS256')
+    OpenStruct.new(token: decoded)
+  end
+
+  # @return [Array<Class>] exception classes the controller rescues as 401
+  def error_classes
+    [AuthError, JWT::DecodeError]
+  end
+
+  private
+
+  def public_key
+    OpenSSL::PKey::RSA.new(ENV.fetch('JWT_PUBLIC_KEY'))
+  end
+end
+```
+
+### Aggregate Authorization
+
+To make aggregates available via the command API, you must define an authorization scheme at the aggregate level. This controls who can execute commands on the aggregate.
+
+#### Simple Authorization
+
+The simplest authorization simply allows all commands to be executed:
+
+```ruby
+module Users
+  module User
+    class Aggregate < Yes::Core::Aggregate
+      # Allow all commands
+      authorize do
+        true
+      end
+
+      command :change, :name, :string
+    end
+  end
+end
+```
+
+Inside the `authorize` block, you can access:
+- `command` - The command being executed
+- `auth_data` - The decoded data from the JWT authentication token
+
+This allows for custom authorization logic:
+
+```ruby
+authorize do
+  # Only allow commands if the authenticated identity matches the user
+  command.user_id == auth_data[:identity_id]
+end
+```
+
+### Command Authorization
+
+Commands can define per-command authorization that extends or overrides the [aggregate-level authorizer](#aggregate-authorization).
+
+```ruby
+# First define an aggregate level authorizer
+class Aggregate < Yes::Core::Aggregate
+  authorize do
+    # Base level authorization logic
+    auth_data[:identity_id].present?
+  end
+
+  # Then add command-specific refinements
+  command :publish do
+    payload user_id: :uuid
+
+    # Command-specific authorization logic
+    authorize do
+      # Has access to the command and auth_data
+      command.user_id == auth_data[:user_id]
+    end
+  end
+end
+```
+
+When an aggregate has declared `authorize` at the class level, commands can define their own
+authorization logic that inherits from the aggregate-level authorizer. Each command with an
+`authorize` block automatically receives its own `Authorizer` subclass that inherits from
+the aggregate-level authorizer.
+
+Command authorizers are registered in the configuration and can be retrieved with:
+
+```ruby
+Yes::Core.configuration.aggregate_class('Context', 'Aggregate', :publish, :authorizer)
+```
+
+### Cerbos Authorization
+
+For more complex authorization needs, Yes integrates with [Cerbos](https://www.cerbos.dev/), a powerful authorization engine:
+
+```ruby
+module Users
+  module User
+    class Aggregate < Yes::Core::Aggregate
+      authorize cerbos: true
+
+      command :change, :name, :string
+    end
+  end
+end
+```
+
+When using Cerbos, you can specify additional parameters:
+
+- `read_model_class` - The class used to load the read model for authorization checks (defaults to the aggregate's read model)
+- `resource_name` - The resource name used in Cerbos policies (defaults to the underscored aggregate name)
+
+```ruby
+module Companies
+  module CompanySettings
+    class Aggregate < Yes::Core::Aggregate
+      # Custom read model and resource name
+      authorize cerbos: true,
+                read_model_class: CustomCompanySettings,
+                resource_name: 'company_settings'
+
+      command :change, :name, :string
+    end
+  end
+end
+```
+
+When using custom read models with Cerbos, the model must implement an `auth_attributes` method that returns a hash of attributes for authorization:
+
+```ruby
+class CustomCompanySettings < ApplicationRecord
+  def auth_attributes
+    { company_id: company_id || '' }
+  end
+end
+```
+
+These attributes are passed to Cerbos for making authorization decisions based on your policies.
+
+#### Customizing Cerbos Integration
+
+For advanced use cases, you can customize how Yes interacts with Cerbos by overriding the `resource_attributes` and `cerbos_payload` methods in your authorization block. Currently, this customization is only available within command-level authorization blocks, not at the aggregate level:
+
+```ruby
+module Universe
+  module Star
+    class Aggregate < Yes::Core::Aggregate
+      # Base aggregate-level Cerbos authorization
+      authorize cerbos: true
+
+      command :change, :name, :string
+
+      # Command with customized Cerbos integration
+      command :update_details do
+        payload details: :string
+
+        # Command-level authorization with custom Cerbos integration
+        authorize do
+          # Override resource attributes sent to Cerbos
+          resource_attributes { { owner_id: 'test-user-id' } }
+
+          # Override the entire Cerbos payload
+          cerbos_payload { { principal: auth_data, resource_id: 'test-id' } }
+        end
+      end
+    end
+  end
+end
+```
+
+Inside the `resource_attributes` block, you can access:
+- `command` - The command being executed
+- `resource` - The read model instance for the aggregate
+
+Inside the `cerbos_payload` block, you can access:
+- `command` - The command being executed
+- `resource` - The read model instance for the aggregate
+- `auth_data` - The decoded data from the JWT authentication token
+
+These blocks allow you to precisely control what data is sent to Cerbos for authorization decisions on a per-command basis.
+
+## Command API
+
+The Command API (`yes-command-api`) provides an HTTP endpoint for executing commands as JSON batches. It is a standalone Rails engine that does **not** depend on the aggregate DSL — it works with any command class that follows one of the supported naming conventions.
+
+### Command API Installation
+
+Add the gem and mount the engine:
+
+```ruby
+# Gemfile
+gem 'yes-command-api'
+```
+
+```ruby
+# config/routes.rb
+mount Yes::Command::Api::Engine => '/v1/commands'
+```
+
+### Request Format
+
+Send a `POST` request with a JSON body containing a `commands` array:
+
+```json
+{
+  "commands": [
+    {
+      "context": "Users",
+      "subject": "User",
+      "command": "ChangeName",
+      "data": {
+        "user_id": "47330036-7246-40b4-a3c7-7038df508774",
+        "name": "Jane Doe"
+      },
+      "metadata": {}
+    }
+  ],
+  "channel": "my-notifications"
+}
+```
+
+Each command requires `context`, `subject`, `command`, and `data`. The optional `channel` parameter controls which MessageBus channel receives notifications (defaults to the authenticated user's `identity_id`).
+
+Set `async=true` or `async=false` as a query parameter to override the default processing mode (`Yes::Core.configuration.process_commands_inline`).
+
+### Command Class Resolution
+
+The deserializer resolves command classes by trying three naming conventions in order:
+
+| Priority | Convention | Class pattern | Typical use |
+|----------|-----------|---------------|-------------|
+| 1 | Command Group | `CommandGroups::<Command>::Command` | Composed commands |
+| 2 | V2 | `<Context>::<Subject>::Commands::<Command>::Command` | DSL-generated commands |
+| 3 | V1 | `<Context>::Commands::<Subject>::<Command>` | Manually created commands |
+
+The first matching constant wins. This means you can use the API with DSL-generated commands, manually created commands, or both.
+
+### Processing Pipeline
+
+When a request arrives, it passes through these stages:
+
+1. **Authentication** — the [auth adapter](#auth-adapter) verifies the JWT token
+2. **Params validation** — checks that each command hash contains `context`, `subject`, `command`, and `data`
+3. **Deserialization** — resolves class names and instantiates command objects
+4. **Expansion** — flattens command groups into individual commands
+5. **Authorization** — each command's authorizer is looked up and called with `auth_data`
+6. **Validation** — optional per-command validators are called
+7. **Command bus** — commands are dispatched (inline or via ActiveJob)
+
+### Using Commands Without the DSL
+
+You can create command classes manually and use them with the Command API. A complete command requires four parts: a **command**, a **handler**, an **event**, and an **authorizer**. The file structure follows a convention:
+
+```
+app/contexts/
+  billing/
+    invoice/
+      commands/
+        authorizer.rb            # shared base authorizer (optional)
+        create/
+          command.rb             # command definition
+          handler.rb             # command handler
+          authorizer.rb          # per-command authorizer
+      events/
+        created.rb               # event definition
+```
+
+#### Command
+
+Defines the payload attributes and identifies the aggregate:
+
+```ruby
+# app/contexts/billing/invoice/commands/create/command.rb
+module Billing
+  module Invoice
+    module Commands
+      module Create
+        class Command < Yes::Core::Command
+          attribute :invoice_id, Yes::Core::Types::UUID
+          attribute :amount, Yes::Core::Types::Integer
+          attribute :currency, Yes::Core::Types::String
+
+          alias aggregate_id invoice_id
+        end
+      end
+    end
+  end
+end
+```
+
+#### Handler
+
+Processes the command and publishes the event. The handler inherits from `Yes::Core::Commands::Stateless::Handler` and declares which event to emit:
+
+```ruby
+# app/contexts/billing/invoice/commands/create/handler.rb
+module Billing
+  module Invoice
+    module Commands
+      module Create
+        class Handler < Yes::Core::Commands::Stateless::Handler
+          self.event_name = 'Created'
+
+          def call
+            # Add guard logic here, e.g.:
+            # no_change_transition('Already exists') if already_exists?
+
+            super # publishes the event
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+#### Event
+
+Defines the event schema for validation when writing to the event store:
+
+```ruby
+# app/contexts/billing/invoice/events/created.rb
+module Billing
+  module Invoice
+    module Events
+      class Created < Yes::Core::Event
+        def schema
+          Dry::Schema.Params do
+            required(:invoice_id).value(Yes::Core::Types::UUID)
+            required(:amount).value(:integer)
+            required(:currency).value(:string)
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+#### Authorizer
+
+Controls who can execute the command. You can define a shared base authorizer for the aggregate and inherit from it:
+
+```ruby
+# app/contexts/billing/invoice/commands/authorizer.rb
+module Billing
+  module Invoice
+    module Commands
+      class Authorizer < Yes::Core::Authorization::CommandAuthorizer
+        def self.call(_command, auth_data)
+          raise CommandNotAuthorized, 'Not allowed' unless auth_data[:identity_id].present?
+        end
+      end
+    end
+  end
+end
+
+# app/contexts/billing/invoice/commands/create/authorizer.rb
+module Billing
+  module Invoice
+    module Commands
+      module Create
+        class Authorizer < Billing::Invoice::Commands::Authorizer
+          # Inherits base authorization; add command-specific checks here
+        end
+      end
+    end
+  end
+end
+```
+
+This command can then be executed via the API:
+
+```json
+{
+  "context": "Billing",
+  "subject": "Invoice",
+  "command": "Create",
+  "data": {
+    "invoice_id": "550e8400-e29b-41d4-a716-446655440000",
+    "amount": 10000,
+    "currency": "CHF"
+  }
+}
+```
+
+### Real-Time Command Notifications
+
+For performance and reliability, WebSocket-based notifications are the preferred way to inform frontends about command execution status. The Command API ships with two built-in notifiers and supports custom implementations.
+
+Notifiers are configured globally and broadcast three event types per command batch:
+
+| Event | When | Payload includes |
+|-------|------|-----------------|
+| `batch_started` | Before processing begins | `batch_id`, commands list |
+| Per-command response | After each command completes | Command result or error |
+| `batch_finished` | After all commands complete | `batch_id`, failed commands (if any) |
+
+#### Configuration
+
+Register one or more notifier classes in the initializer:
+
+```ruby
+Yes::Core.configure do |config|
+  config.command_notifier_classes = [
+    Yes::Command::Api::Commands::Notifiers::ActionCable,
+    Yes::Command::Api::Commands::Notifiers::MessageBus
+  ]
+end
+```
+
+The `channel` parameter from the API request (or the authenticated user's `identity_id` as fallback) is passed to each notifier, so clients only receive notifications for their own commands.
+
+#### ActionCable Notifier
+
+Broadcasts notifications via `ActionCable.server.broadcast`. This is well suited for use with a dedicated WebSocket gateway service that connects to the same Redis backend:
+
+```ruby
+config.command_notifier_classes = [Yes::Command::Api::Commands::Notifiers::ActionCable]
+```
+
+The frontend subscribes to the channel and receives JSON messages:
+
+```json
+{ "type": "batch_started", "batch_id": "abc-123", "published_at": 1711540800, "commands": [...] }
+{ "type": "batch_finished", "batch_id": "abc-123", "published_at": 1711540801, "failed_commands": [] }
+```
+
+#### MessageBus Notifier
+
+Uses the [MessageBus](https://github.com/discourse/message_bus) gem for long-polling or WebSocket delivery. Messages are scoped to the authenticated user via `user_ids`:
+
+```ruby
+config.command_notifier_classes = [Yes::Command::Api::Commands::Notifiers::MessageBus]
+```
+
+The auth adapter's `verify_token` method is used by MessageBus to identify subscribers by their `identity_id`.
+
+#### Custom Notifiers
+
+You can implement your own notifier by subclassing `Yes::Core::Commands::Notifier`:
+
+```ruby
+class SlackNotifier < Yes::Core::Commands::Notifier
+  def notify_batch_started(batch_id, transaction = nil, commands = nil)
+    # ...
+  end
+
+  def notify_batch_finished(batch_id, transaction = nil, responses = nil)
+    # ...
+  end
+
+  def notify_command_response(cmd_response)
+    # ...
+  end
+end
+```
+
+## Read API
+
+The Read API (`yes-read-api`) provides an HTTP endpoint for querying read models with filtering, pagination, and authorization. Like the Command API, it is a standalone Rails engine that does **not** depend on the aggregate DSL — it works with any ActiveRecord model that has a matching serializer.
+
+### Read API Installation
+
+Add the gem and mount the engine:
+
+```ruby
+# Gemfile
+gem 'yes-read-api'
+```
+
+```ruby
+# config/routes.rb
+mount Yes::Read::Api::Engine => '/queries'
+```
+
+### Basic Queries
+
+Send a `GET` request with the read model name as the path and optional query parameters:
+
+```
+GET /queries/users?filters[ids]=1,2,3&order[name]=asc&page[number]=1&page[size]=20&include=company
+```
+
+- `filters[<key>]` — filter by attribute (handled by the model's filter class)
+- `order[<key>]` — sort direction (`asc` or `desc`)
+- `page[number]` and `page[size]` — pagination
+- `include` — comma-separated list of associations to include in the response
+
+### Advanced Queries
+
+Send a `POST` request for complex filtering with AND/OR logic:
+
+```json
+{
+  "model": "users",
+  "filter_definition": {
+    "type": "filter_set",
+    "logical_operator": "and",
+    "filters": [
+      {
+        "type": "filter",
+        "attribute": "name",
+        "operator": "is",
+        "value": "Jane"
+      },
+      {
+        "type": "filter",
+        "attribute": "status",
+        "operator": "is_not",
+        "value": "archived"
+      }
+    ]
+  },
+  "order": { "name": "asc" },
+  "page": { "number": 1, "size": 20 }
+}
+```
+
+### Filters
+
+Filters are optional per-model classes that define available filter scopes. If no custom filter exists, the base `Yes::Core::ReadModel::Filter` is used.
+
+```ruby
+module ReadModels
+  module User
+    class Filter < Yes::Core::ReadModel::Filter
+      has_scope :name do |_controller, scope, value|
+        scope.where(name: value)
+      end
+
+      has_scope :ids do |_controller, scope, value|
+        scope.where(id: value.split(','))
+      end
+
+      private
+
+      def read_model_class
+        ::UserReadModel
+      end
+    end
+  end
+end
+```
+
+### Read API Authorization
+
+The Read API enforces two levels of authorization:
+
+1. **Request authorizer** — controls whether a user can query a given model at all. Looked up as `ReadModels::<Model>::RequestAuthorizer`.
+
+```ruby
+module ReadModels
+  module User
+    class RequestAuthorizer
+      def self.call(filter_options, auth_data)
+        unless auth_data[:identity_id].present?
+          raise Yes::Core::Authorization::ReadRequestAuthorizer::NotAuthorized, 'Not allowed'
+        end
+      end
+    end
+  end
+end
+```
+
+2. **Read model authorizer** — filters returned records based on what the user can access. Configured via `Yes::Core::Authorization::ReadModelsAuthorizer`.
+
+### Serializers
+
+Each read model requires a serializer class following the convention `ReadModels::<Model>::Serializers::<Model>`. The serializer receives `auth_data` and filter options, allowing it to customize the response based on the authenticated user.
+
+## Event Processing
+
+### Subscriptions
+
+Yes wraps [PgEventstore](https://github.com/yousty/pg_eventstore) subscriptions for processing events in real-time.
+
+#### Setting Up Subscriptions
+
+```ruby
+# lib/tasks/eventstore.rb
+subscriptions = Yes::Core::Subscriptions.new
+
+subscriptions.subscribe_to_all(
+  MyReadModel::Builder.new,
+  { event_types: ['MyContext::SomethingHappened', 'MyContext::SomethingElseHappened'] }
+)
+
+subscriptions.start
+```
+
+Start subscriptions via the PgEventstore CLI:
+
+```shell
+bundle exec pg-eventstore subscriptions start -r ./lib/tasks/eventstore.rb
+```
+
+#### Heartbeat
+
+Configure a heartbeat URL for monitoring subscription health:
+
+```ruby
+Yes::Core.configure do |config|
+  config.subscriptions_heartbeat_url = ENV['SUBSCRIPTIONS_HEARTBEAT_URL']
+  config.subscriptions_heartbeat_interval = 30 # seconds
+end
+```
+
+### Process Managers
+
+Process managers coordinate commands across services via HTTP.
+
+#### ServiceClient
+
+Sends commands to another service's command API:
+
+```ruby
+client = Yes::Core::ProcessManagers::ServiceClient.new('media')
+# Resolves to MEDIA_SERVICE_URL env var or http://media-cluster-ip-service:3000
+
+client.call(access_token: token, commands_data: [...], channel: '/notifications')
+```
+
+#### CommandRunner
+
+Base class for process managers that publish commands to external services:
+
+```ruby
+class MyProcessManager < Yes::Core::ProcessManagers::CommandRunner
+  def call(event)
+    publish(
+      client_id: ENV['MY_CLIENT_ID'],
+      client_secret: ENV['MY_CLIENT_SECRET'],
+      commands_data: build_commands(event)
+    )
+  end
+end
+```
+
+#### State
+
+Reconstructs entity state from events for use in process managers:
+
+```ruby
+class UserState < Yes::Core::ProcessManagers::State
+  RELEVANT_EVENTS = ['Auth::UserCreated', 'Auth::UserNameChanged'].freeze
+
+  attr_reader :name
+
+  private
+
+  def stream
+    PgEventstore::Stream.new(context: 'Auth', stream_name: 'User', stream_id: @id)
+  end
+
+  def required_attributes
+    [:name]
+  end
+
+  def apply_user_name_changed(event)
+    @name = event.data['name']
+  end
+end
+
+state = UserState.load(user_id)
+state.valid? # true if all required_attributes are present
+```
+
+## Configuration Reference
+
+```ruby
+Yes::Core.configure do |config|
+  # Command processing
+  config.process_commands_inline = true          # Process commands synchronously (default: true)
+  config.command_notifier_classes = []            # Array of notifier classes for command batch notifications
+
+  # Authentication
+  config.auth_adapter = nil                      # Auth adapter instance (required for command/read APIs)
+
+  # Cerbos Authorization
+  config.cerbos_url = ENV['CERBOS_URL']          # Cerbos server URL (default from env var)
+  config.cerbos_principal_data_builder = -> {}    # Lambda to build Cerbos principal data for commands
+  config.cerbos_read_principal_data_builder = nil # Lambda for read requests (falls back to above)
+  config.cerbos_commands_authorizer_include_metadata = false
+  config.cerbos_read_authorizer_include_metadata = false
+  config.cerbos_read_authorizer_actions = %w[read]
+  config.cerbos_read_authorizer_resource_id_prefix = 'read-'
+  config.cerbos_read_authorizer_principal_anonymous_id = 'anonymous'
+  config.super_admin_check = ->(_auth_data) { false }
+
+  # Subscriptions
+  config.subscriptions_heartbeat_url = nil       # URL to ping for subscription health monitoring
+  config.subscriptions_heartbeat_interval = 30   # Heartbeat interval in seconds
+
+  # Observability
+  config.otl_tracer = nil                        # OpenTelemetry tracer instance
+  config.logger = Rails.logger                   # Logger instance
+
+  # Error reporting
+  config.error_reporter = nil                    # Callable for error reporting (e.g. Sentry)
+end
+```
+
+## Testing
+
+yes-core ships with a test DSL for writing concise aggregate command specs. Add to your `spec_helper.rb` or `rails_helper.rb`:
+
+```ruby
+require 'yes/core/test_support'
+
+RSpec.configure do |config|
+  config.include Yes::Core::TestSupport::EventHelpers
+end
+```
+
+### Aggregate Test DSL
+
+Specs with `type: :aggregate` automatically get the command test DSL:
+
+```ruby
+RSpec.describe MyContext::Order::Aggregate, type: :aggregate do
+  it { is_expected.to have_cerbos_authorizer.with_read_model_class(Order) }
+  it { is_expected.to have_read_model_class(Order) }
+  it { is_expected.to have_parent('customer').with_context('CustomerManagement') }
+
+  command 'confirm' do
+    let(:command_data) { { confirmed_at: Time.current } }
+    let(:success_attributes) { { confirmed: true } }
+
+    # Tests successful execution, state change, and event publishing
+    success
+
+    # Tests with custom setup
+    success 'when order was previously cancelled' do
+      setup do
+        aggregate.confirm
+        aggregate.cancel
+      end
+    end
+
+    # Tests that guard raises InvalidTransition
+    invalid 'order has been removed' do
+      setup { aggregate.remove }
+    end
+
+    # Executes command twice — second time should raise NoChangeTransition
+    no_change
+  end
+end
+```
+
+The `command` block automatically defines:
+- `aggregate` — a new instance of the described class
+- `subject` — executes the command with `command_data`
+- `expected_event_type` — derived from context, aggregate, and command name
+- `success_attributes` — defaults to `command_data` (override as needed)
+
+### DSL Methods
+
+| Method | Description |
+|--------|-------------|
+| `command 'name'` | Defines a command test block with aggregate, subject, and default lets |
+| `success` | Asserts command changes state and publishes expected event |
+| `invalid 'reason'` | Asserts command raises `InvalidTransition` error |
+| `no_change` | Asserts duplicate command raises `NoChangeTransition` error |
+| `setup { ... }` | Alias for `before` — sets up aggregate state before assertions |
+
+For draft commands, pass `draft: true`:
+
+```ruby
+command 'change_name', draft: true do
+  let(:command_data) { { name: 'New Name' } }
+  success
+end
+```
+
+### Command Group Test DSL
+
+Command groups have a parallel set of helpers — `command_group`, `success_group`, `invalid_group`, `no_change_group` — that mirror the per-command DSL but produce assertions about the `CommandGroupResponse` (multiple events, cumulative read-model state).
+
+```ruby
+RSpec.describe Companies::Apprenticeship::Aggregate, type: :aggregate do
+  command_group 'create_apprenticeship' do
+    let(:command_data) do
+      {
+        company_id: SecureRandom.uuid,
+        user_id:    SecureRandom.uuid,
+        name:       'Acme Apprenticeship',
+        description: 'Software dev role'
+      }
+    end
+
+    let(:success_attributes) do
+      { name: 'Acme Apprenticeship', description: 'Software dev role' }
+    end
+
+    # Asserts: response is success, all sub-events publish in declaration order,
+    # read model reflects the cumulative state.
+    success_group
+
+    # Asserts: response is failure, error is InvalidTransition, events array is empty.
+    invalid_group 'company_id is missing' do
+      let(:command_data) { super().merge(company_id: nil) }
+    end
+
+    # Asserts: NoChangeTransition when running the group twice.
+    no_change_group
+  end
+end
+```
+
+The `command_group` block automatically defines:
+- `aggregate` — a new instance of the described class
+- `subject` — executes the group with `command_data`
+- `expected_event_types` — array of expected event types in declaration order, derived from each sub-command's `event_name` and the aggregate's context/name (with draft prefix handling)
+- `success_attributes` — defaults to `command_data` (override as needed)
+
+| Method | Description |
+|--------|-------------|
+| `command_group 'name'` | Defines a command_group test block with aggregate, subject, and default lets |
+| `success_group` | Asserts the group publishes all expected events and read model reflects cumulative state |
+| `invalid_group 'reason'` | Asserts the group's guard fails with `InvalidTransition` and no events publish |
+| `no_change_group` | Asserts a duplicate group invocation raises `NoChangeTransition` |
+| `setup { ... }` | Alias for `before` — works inside `command_group` too |
+
+For draftable aggregates, pass `draft: true` exactly like the per-command form:
+
+```ruby
+command_group 'create_apprenticeship', draft: true do
+  let(:command_data) { { ... } }
+  success_group
+end
+```
+
+### Event Helpers
+
+Available via `Yes::Core::TestSupport::EventHelpers`:
+
+```ruby
+# Append events from other contexts for cross-aggregate setup
+given_events do
+  [{ context: 'Shipping', aggregate: 'Shipment', event: 'Dispatched', data: { shipment_id: id } }]
+end
+
+# Low-level event operations
+append_event(stream, event)
+append_and_reload_event(stream, event)
+read_events(stream)  # returns [] if stream not found
+```
+
+### Aggregate Matchers
+
+```ruby
+# Check authorizer configuration
+it { is_expected.to have_authorizer }
+it { is_expected.to have_cerbos_authorizer }
+it { is_expected.to have_cerbos_authorizer.with_read_model_class(Order) }
+it { is_expected.to have_cerbos_authorizer.with_resource_name('order') }
+
+# Check read model
+it { is_expected.to have_read_model_class(Order) }
+
+# Check parent aggregates
+it { is_expected.to have_parent('company') }
+it { is_expected.to have_parent('company').with_context('CompanyManagement') }
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies.
+
+Start PG EventStore using Docker:
+
+```shell
+docker compose up
+```
+
+Setup databases:
+
+```shell
+./bin/setup_db
+```
+
+Enter a development console (from a gem's `spec/dummy` directory):
+
+```shell
+bundle exec rails c
+```
+
+### Example Usage
+
+```ruby
+user = Test::User::Aggregate.new
+user.change_name(name: "John Doe")
+user.name # => "John Doe"
+TestUser.last.name # => "John Doe"
+```
+
+### Testing the APIs
+
+The dummy app includes mounted command and read APIs for testing. Start the server from one of the gem dummy apps:
+
+```shell
+cd yes-core/spec/dummy
+bundle exec rails s
+```
+
+#### Authentication
+
+The dummy app uses a simple Base64-encoded auth adapter for development. Generate a token:
+
+```ruby
+require 'base64'
+user_id = "47330036-7246-40b4-a3c7-7038df508774"
+token = Base64.strict_encode64({ identity_id: user_id, user_id: user_id }.to_json)
+```
+
+Or from the command line:
+
+```shell
+TOKEN=$(echo -n '{"identity_id":"47330036-7246-40b4-a3c7-7038df508774","user_id":"47330036-7246-40b4-a3c7-7038df508774"}' | base64)
+```
+
+#### Testing Command API
+
+Execute a command with curl:
+
+```shell
+curl --location 'http://127.0.0.1:3000/commands' \
+--header 'Content-Type: application/json' \
+--header "Authorization: Bearer $TOKEN" \
+--data '{
+  "commands": [{
+    "subject": "User",
+    "context": "Test",
+    "command": "ChangeName",
+    "data": {
+      "user_id": "47330036-7246-40b4-a3c7-7038df508774",
+      "name": "Judydoody Doodle"
+    }
+  }],
+  "channel": "test-notifications"
+}'
+```
+
+#### Testing Read API
+
+Query the read models:
+
+```shell
+curl --location 'http://127.0.0.1:3000/queries/test_users' \
+--header 'Content-Type: application/json' \
+--header "Authorization: Bearer $TOKEN"
+```
+
+### Running Specs
+
+Each gem has its own test suite that runs in isolation with its own bundle context.
+
+Run specs for a single gem:
+
+```shell
+rake yes_core:spec
+rake yes_command_api:spec
+rake yes_read_api:spec
+```
+
+Run specs for all gems:
+
+```shell
+rake spec
+```
+
+You can also run specs directly from within a gem directory:
+
+```shell
+cd yes-core && bundle exec rspec spec
+```
+
+### Gem Installation
+
+Install the gem locally:
+
+```shell
+bundle exec rake install
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/yousty/yes. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for a list of changes.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).