neuroglia-python 0.6.11__tar.gz → 0.7.8__tar.gz

{neuroglia_python-0.6.11 → neuroglia_python-0.7.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: neuroglia-python
-Version: 0.6.11
+Version: 0.7.8
 Summary: Port from .NET to Python of the Neuroglia Framework
 License: Apache
 License-File: LICENSE
@@ -21,43 +21,44 @@ Provides-Extra: etcd
 Provides-Extra: eventstore
 Provides-Extra: mongodb
 Provides-Extra: redis
-Requires-Dist: annotated-types (>=0.7.0,<0.8.0)
-Requires-Dist: apscheduler (>=3.11.0,<4.0.0)
-Requires-Dist: boto3 (>=1.40.64,<2.0.0) ; extra == "aws" or extra == "all"
-Requires-Dist: classy-fastapi (>=0.6.1,<0.7.0)
-Requires-Dist: email-validator (>=2.2.0,<3.0.0)
-Requires-Dist: esdbclient (>=1.1.1,<2.0.0) ; extra == "eventstore" or extra == "all"
-Requires-Dist: etcd3-py (>=0.1.6,<0.2.0) ; extra == "etcd" or extra == "all"
-Requires-Dist: fastapi (>=0.115.5,<0.116.0)
-Requires-Dist: grpcio (>=1.68.1,<2.0.0)
-Requires-Dist: httpx (>=0.27.2,<0.28.0)
-Requires-Dist: itsdangerous (>=2.2.0,<3.0.0)
-Requires-Dist: jinja2 (>=3.1.4,<4.0.0)
-Requires-Dist: motor (>=3.6.0,<4.0.0) ; extra == "mongodb" or extra == "all"
-Requires-Dist: multipledispatch (>=1.0.0,<2.0.0)
-Requires-Dist: opentelemetry-api (>=1.28.2,<2.0.0)
-Requires-Dist: opentelemetry-exporter-otlp-proto-grpc (>=1.28.2,<2.0.0)
-Requires-Dist: opentelemetry-exporter-otlp-proto-http (>=1.28.2,<2.0.0)
-Requires-Dist: opentelemetry-exporter-prometheus (>=0.49b2,<0.50)
-Requires-Dist: opentelemetry-instrumentation (>=0.49b2,<0.50)
-Requires-Dist: opentelemetry-instrumentation-fastapi (>=0.49b2,<0.50)
-Requires-Dist: opentelemetry-instrumentation-httpx (>=0.49b2,<0.50)
-Requires-Dist: opentelemetry-instrumentation-logging (>=0.49b2,<0.50)
-Requires-Dist: opentelemetry-instrumentation-system-metrics (>=0.49b2,<0.50)
-Requires-Dist: opentelemetry-sdk (>=1.28.2,<2.0.0)
-Requires-Dist: passlib[bcrypt] (>=1.7.4,<2.0.0)
-Requires-Dist: prometheus-client (>=0.21.0,<0.22.0)
-Requires-Dist: protobuf (>=5.0,<6.0) ; extra == "etcd" or extra == "all"
-Requires-Dist: pydantic-settings (>=2.6.1,<3.0.0)
-Requires-Dist: pydantic[email] (>=2.10.3,<3.0.0)
-Requires-Dist: pyjwt (>=2.10.1,<3.0.0)
-Requires-Dist: pymongo (>=4.10.1,<5.0.0) ; extra == "mongodb" or extra == "all"
-Requires-Dist: python-dotenv (>=1.0.1,<2.0.0)
-Requires-Dist: python-multipart (>=0.0.17,<0.0.18)
-Requires-Dist: redis (>=5.2.0,<6.0.0) ; extra == "redis" or extra == "all"
-Requires-Dist: rx (>=3.2.0,<4.0.0)
-Requires-Dist: typing-extensions (>=4.12.2,<5.0.0)
-Requires-Dist: uvicorn (>=0.32.1,<0.33.0)
+Requires-Dist: annotated-types (==0.7.0)
+Requires-Dist: apscheduler (==3.11.0)
+Requires-Dist: boto3 (==1.40.64) ; extra == "aws" or extra == "all"
+Requires-Dist: classy-fastapi (==0.6.1)
+Requires-Dist: email-validator (==2.2.0)
+Requires-Dist: etcd3-py (==0.1.6) ; extra == "etcd" or extra == "all"
+Requires-Dist: fastapi (==0.115.5)
+Requires-Dist: grpcio (==1.76.0)
+Requires-Dist: h11 (==0.16.0)
+Requires-Dist: httpx (==0.27.2)
+Requires-Dist: itsdangerous (==2.2.0)
+Requires-Dist: jinja2 (==3.1.4)
+Requires-Dist: kurrentdbclient (==1.1.2) ; extra == "eventstore" or extra == "all"
+Requires-Dist: motor (==3.7.0) ; extra == "mongodb" or extra == "all"
+Requires-Dist: multipledispatch (==1.0.0)
+Requires-Dist: opentelemetry-api (==1.38.0)
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc (==1.38.0)
+Requires-Dist: opentelemetry-exporter-otlp-proto-http (==1.38.0)
+Requires-Dist: opentelemetry-exporter-prometheus (==0.59b0)
+Requires-Dist: opentelemetry-instrumentation (==0.59b0)
+Requires-Dist: opentelemetry-instrumentation-fastapi (==0.59b0)
+Requires-Dist: opentelemetry-instrumentation-httpx (==0.59b0)
+Requires-Dist: opentelemetry-instrumentation-logging (==0.59b0)
+Requires-Dist: opentelemetry-instrumentation-system-metrics (==0.59b0)
+Requires-Dist: opentelemetry-sdk (==1.38.0)
+Requires-Dist: passlib[bcrypt] (==1.7.4)
+Requires-Dist: prometheus-client (==0.21.0)
+Requires-Dist: protobuf (==6.33.1) ; extra == "etcd" or extra == "all"
+Requires-Dist: pydantic-settings (==2.6.1)
+Requires-Dist: pydantic[email] (==2.10.3)
+Requires-Dist: pyjwt (==2.10.1)
+Requires-Dist: pymongo (==4.15.4) ; extra == "mongodb" or extra == "all"
+Requires-Dist: python-dotenv (==1.0.1)
+Requires-Dist: python-multipart (==0.0.17)
+Requires-Dist: redis (==5.2.0) ; extra == "redis" or extra == "all"
+Requires-Dist: rx (==3.2.0)
+Requires-Dist: typing-extensions (==4.12.2)
+Requires-Dist: uvicorn (==0.32.1)
 Description-Content-Type: text/markdown
 
 # Neuroglia Python Framework

neuroglia_python-0.7.8/pyproject.toml

@@ -0,0 +1,97 @@
+[tool.poetry]
+name = "neuroglia-python"
+version = "0.7.8"
+description = "Port from .NET to Python of the Neuroglia Framework"
+authors = ["Charles d'Avernas <charles.davernas@neuroglia.io>", "Bruno van de Werve <bvandewe@gmail.com>"]
+license = "Apache"
+readme = "README.md"
+packages = [
+    { include = "neuroglia", from = "src" },
+]
+package-mode = true
+
+[tool.poetry.dependencies]
+python = "^3.9"
+# Core framework dependencies - always required
+annotated-types = "0.7.0"
+classy-fastapi = "0.6.1"
+fastapi = "0.115.5"
+multipledispatch = "1.0.0"
+pydantic-settings = "2.6.1"
+python-dotenv = "1.0.1"
+typing-extensions = "4.12.2"
+rx = { version = "3.2.0" }
+uvicorn = { version = "0.32.1" }
+httpx = { version = "0.27.2" }
+grpcio = { version = "1.76.0" }
+h11 = { version = "0.16.0" }  # Security fix for CVE-2025-43859
+
+# Authentication dependencies
+pyjwt = "2.10.1"
+passlib = { extras = ["bcrypt"], version = "1.7.4" }
+python-multipart = "0.0.17"
+itsdangerous = "2.2.0"
+
+# Core dependencies
+protobuf = "6.33.1"  # Pinned for compatibility with kurrentdbclient, OpenTelemetry, and etcd3-py
+apscheduler = "3.11.0"
+pydantic = {extras = ["email"], version = "2.10.3"}
+email-validator = "2.2.0"
+jinja2 = "3.1.4"
+
+# Optional dependencies - install with extras
+redis = { version = "5.2.0", optional = true }
+pymongo = { version = "4.15.4", optional = true }
+motor = { version = "3.7.0", optional = true }
+kurrentdbclient = "1.1.2"
+etcd3-py = { version = "0.1.6", optional = true }  # Maintained fork with protobuf 5.x/6.x support
+
+# OpenTelemetry dependencies - pinned versions for protobuf 6.x compatibility
+opentelemetry-api = "1.38.0"
+opentelemetry-sdk = "1.38.0"
+opentelemetry-exporter-otlp-proto-grpc = "1.38.0"
+opentelemetry-exporter-otlp-proto-http = "1.38.0"
+opentelemetry-instrumentation = "0.59b0"
+opentelemetry-instrumentation-fastapi = "0.59b0"
+opentelemetry-instrumentation-httpx = "0.59b0"
+opentelemetry-instrumentation-logging = "0.59b0"
+opentelemetry-instrumentation-system-metrics = "0.59b0"
+opentelemetry-exporter-prometheus = "0.59b0"  # Prometheus /metrics endpoint support
+prometheus-client = "0.21.0"  # Required by opentelemetry-exporter-prometheus
+boto3 = { version = "1.40.64", optional = true }
+
+[tool.poetry.extras]
+mongodb = ["pymongo", "motor"]
+eventstore = ["kurrentdbclient"]  # Formerly esdbclient
+redis = ["redis"]
+etcd = ["etcd3-py", "protobuf"]
+aws = ["boto3"]
+all = ["pymongo", "motor", "kurrentdbclient", "redis", "etcd3-py", "protobuf", "boto3"]
+
+[tool.poetry.group.dev.dependencies]
+# Development and testing dependencies
+pre-commit = "^4.0.1"
+pytest = "^8.3.3"
+pytest-asyncio = "^0.24.0"
+mypy = "^1.13.0"
+autopep8 = "^2.3.1"
+coverage = "^7.6.9"
+mypy-extensions = "^1.0.0"
+flake8 = "^7.1.1"
+isort = "^5.13.2"
+
+[tool.poetry.group.docs]
+optional = true
+
+[tool.poetry.group.docs.dependencies]
+# Documentation dependencies
+mkdocs = "^1.6.1"
+mkdocs-material = "^9.5.48"
+mkdocs-mermaid2-plugin = "^1.2.2"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.black]
+line-length = 500

{neuroglia_python-0.6.11 → neuroglia_python-0.7.8}/src/neuroglia/__init__.py

@@ -62,7 +62,7 @@ __all__ = [
 ]
 
 # Framework metadata
-__version__ = "0.6.11"
+__version__ = "0.7.8"
 __author__ = "Neuroglia Team"
 __email__ = "team@neuroglia.io"
 __license__ = "Apache"

{neuroglia_python-0.6.11 → neuroglia_python-0.7.8}/src/neuroglia/data/infrastructure/event_sourcing/__init__.py

@@ -5,23 +5,29 @@ Provides event store implementations and aggregate root support.
 """
 
 from .abstractions import (
-    EventStore,
-    EventRecord,
+    Aggregator,
     EventDescriptor,
+    EventRecord,
+    EventStore,
+    EventStoreOptions,
     StreamDescriptor,
     StreamReadDirection,
-    EventStoreOptions,
-    Aggregator
 )
 from .event_sourcing_repository import EventSourcingRepository
+from .read_model_reconciliator import (
+    ReadModelConciliationOptions,
+    ReadModelReconciliator,
+)
 
 __all__ = [
     "EventStore",
     "EventSourcingRepository",
     "EventRecord",
-    "EventDescriptor", 
+    "EventDescriptor",
     "StreamDescriptor",
     "StreamReadDirection",
     "EventStoreOptions",
     "Aggregator",
-]
+    "ReadModelConciliationOptions",
+    "ReadModelReconciliator",
+]

{neuroglia_python-0.6.11 → neuroglia_python-0.7.8}/src/neuroglia/data/infrastructure/event_sourcing/abstractions.py

@@ -8,6 +8,34 @@ from typing import Any, Optional
 from neuroglia.data.abstractions import AggregateRoot
 
 
+class DeleteMode(Enum):
+    """Specifies how deletion should be handled in event-sourced repositories."""
+
+    DISABLED = "disabled"
+    """Deletion is not allowed (default behavior). Raises NotImplementedError."""
+
+    SOFT = "soft"
+    """
+    Soft delete by calling the aggregate's deletion method.
+
+    The repository will:
+    1. Load the aggregate
+    2. Call aggregate.mark_as_deleted() or aggregate.mark_deleted()
+    3. Persist the deletion event via update_async()
+
+    The aggregate controls deletion semantics and domain events.
+    Event stream is preserved for audit and potential restoration.
+    """
+
+    HARD = "hard"
+    """
+    Physically delete the entire event stream from the event store.
+
+    WARNING: This is irreversible and removes all history for this aggregate.
+    Use for GDPR compliance (right to be forgotten) or data cleanup.
+    """
+
+
 @dataclass
 class StreamDescriptor:
     """Represents a class used to describe a stream of recorded events"""
@@ -81,11 +109,11 @@ class AckableEventRecord(EventRecord):
 
     async def ack_async(self) -> None:
         """Acks the event record"""
-        self._ack_delegate()
+        await self._ack_delegate()
 
     async def nack_async(self) -> None:
         """Nacks the event record"""
-        self._nack_delegate()
+        await self._nack_delegate()
 
 
 class StreamReadDirection(Enum):
@@ -155,11 +183,42 @@ class EventStore(ABC):
         """
         raise NotImplementedError()
 
+    @abstractmethod
+    async def delete_async(self, stream_id: str) -> None:
+        """
+        Deletes the entire event stream.
+
+        This operation is irreversible and should be used with caution.
+        Useful for GDPR compliance (right to be forgotten) or data cleanup.
+
+        Args:
+            stream_id: The identifier of the stream to delete
+
+        Raises:
+            Exception: If the stream does not exist or deletion fails
+        """
+        raise NotImplementedError()
+
 
 class Aggregator:
     def aggregate(self, events: list, aggregate_type: type):
+        """
+        Reconstitutes an aggregate from a list of domain events.
+
+        Creates a new aggregate instance using __new__() to bypass __init__,
+        then manually initializes the state and _pending_events list before
+        replaying events to rebuild the aggregate's state.
+
+        Args:
+            events: List of event records to replay
+            aggregate_type: The aggregate root class to instantiate
+
+        Returns:
+            Reconstituted aggregate with replayed state
+        """
         aggregate: AggregateRoot = object.__new__(aggregate_type)
         aggregate.state = aggregate.__orig_bases__[0].__args__[0]()
+        aggregate._pending_events = list()  # Initialize _pending_events to prevent AttributeError
         for e in events:
             aggregate.state.on(e.data)
             aggregate.state.state_version = e.data.aggregate_version

neuroglia_python-0.7.8/src/neuroglia/data/infrastructure/event_sourcing/event_sourcing_repository.py

@@ -0,0 +1,278 @@
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Generic, Optional
+
+from neuroglia.data.abstractions import DomainEvent, TAggregate, TKey
+from neuroglia.data.infrastructure.abstractions import Repository
+from neuroglia.data.infrastructure.event_sourcing.abstractions import (
+    Aggregator,
+    DeleteMode,
+    EventDescriptor,
+    EventStore,
+    StreamReadDirection,
+)
+from neuroglia.hosting.abstractions import ApplicationBuilderBase
+
+if TYPE_CHECKING:
+    from neuroglia.mediation.mediator import Mediator
+
+
+@dataclass
+class EventSourcingRepositoryOptions(Generic[TAggregate, TKey]):
+    """
+    Configuration options for EventSourcingRepository.
+
+    Attributes:
+        delete_mode: Specifies how deletion should be handled (DISABLED, SOFT, HARD)
+        soft_delete_method_name: Method name to call on aggregate for soft delete
+
+    Examples:
+        ```python
+        # Disable deletion (default)
+        options = EventSourcingRepositoryOptions[Task, str]()
+
+        # Enable soft delete
+        options = EventSourcingRepositoryOptions[Task, str](
+            delete_mode=DeleteMode.SOFT
+        )
+
+        # Enable hard delete (GDPR compliance)
+        options = EventSourcingRepositoryOptions[Task, str](
+            delete_mode=DeleteMode.HARD
+        )
+        ```
+    """
+
+    delete_mode: DeleteMode = field(default=DeleteMode.DISABLED)
+    """
+    Specifies how deletion should be handled:
+    - DISABLED: Raises NotImplementedError (default, event sourcing best practice)
+    - SOFT: Calls aggregate.mark_as_deleted() or aggregate.mark_deleted() then persists
+    - HARD: Physically deletes the event stream (use with caution)
+    """
+
+    soft_delete_method_name: str = field(default="mark_as_deleted")
+    """
+    Method name to call on aggregate for soft delete.
+    Defaults to 'mark_as_deleted'. Alternative: 'mark_deleted'.
+    Only used when delete_mode is SOFT.
+    """
+
+
+class EventSourcingRepository(Generic[TAggregate, TKey], Repository[TAggregate, TKey]):
+    """
+    Event sourcing repository implementation with configurable deletion strategies.
+
+    Supports three deletion modes:
+    - DISABLED: No deletion allowed (default, follows event sourcing best practices)
+    - SOFT: Delegates to aggregate's deletion method, preserving event history
+    - HARD: Physical stream deletion for GDPR compliance or data cleanup
+
+    Examples:
+        ```python
+        # Default configuration (deletion disabled)
+        repo = EventSourcingRepository[Task, str](eventstore, aggregator)
+
+        # With soft delete enabled
+        options = EventSourcingRepositoryOptions[Task, str](
+            delete_mode=DeleteMode.SOFT
+        )
+        repo = EventSourcingRepository[Task, str](
+            eventstore, aggregator, options=options
+        )
+
+        # With hard delete for GDPR compliance
+        options = EventSourcingRepositoryOptions[Task, str](
+            delete_mode=DeleteMode.HARD
+        )
+        repo = EventSourcingRepository[Task, str](
+            eventstore, aggregator, options=options
+        )
+        ```
+    """
+
+    def __init__(
+        self,
+        eventstore: EventStore,
+        aggregator: Aggregator,
+        mediator: Optional["Mediator"] = None,
+        options: Optional[EventSourcingRepositoryOptions[TAggregate, TKey]] = None,
+    ):
+        """Initialize a new event sourcing repository"""
+        super().__init__(mediator)  # Pass mediator to base class for event publishing
+        self._eventstore = eventstore
+        self._aggregator = aggregator
+        self._options = options or EventSourcingRepositoryOptions[TAggregate, TKey]()
+
+    _eventstore: EventStore
+    """ Gets the underlying event store """
+
+    _aggregator: Aggregator
+    """ Gets the underlying event store """
+
+    async def contains_async(self, id: TKey) -> bool:
+        return self._eventstore.contains_stream(self._build_stream_id_for(id))
+
+    async def get_async(self, id: TKey) -> Optional[TAggregate]:
+        """
+        Gets the aggregate with the specified id, if any.
+
+        Returns None if the stream does not exist.
+        """
+        stream_id = self._build_stream_id_for(id)
+        try:
+            events = await self._eventstore.read_async(stream_id, StreamReadDirection.FORWARDS, 0)
+            if not events:
+                return None
+            return self._aggregator.aggregate(events, self.__orig_class__.__args__[0])
+        except Exception:
+            # If stream doesn't exist or any other error occurs, return None
+            return None
+
+    async def _do_add_async(self, aggregate: TAggregate) -> TAggregate:
+        """Adds and persists the specified aggregate"""
+        stream_id = self._build_stream_id_for(aggregate.id())
+        events = aggregate._pending_events
+        if len(events) < 1:
+            raise Exception("No pending events to persist")
+        encoded_events = [self._encode_event(e) for e in events]
+        await self._eventstore.append_async(stream_id, encoded_events)
+        aggregate.state.state_version = events[-1].aggregate_version
+        # DON'T clear pending events here - let base class do it after publishing!
+        # aggregate.clear_pending_events()
+        return aggregate
+
+    async def _do_update_async(self, aggregate: TAggregate) -> TAggregate:
+        """Persists the changes made to the specified aggregate"""
+        stream_id = self._build_stream_id_for(aggregate.id())
+        events = aggregate._pending_events
+        if len(events) < 1:
+            raise Exception("No pending events to persist")
+        encoded_events = [self._encode_event(e) for e in events]
+        await self._eventstore.append_async(stream_id, encoded_events, aggregate.state.state_version)
+        aggregate.state.state_version = events[-1].aggregate_version
+        # DON'T clear pending events here - let base class do it after publishing!
+        # aggregate.clear_pending_events()
+        return aggregate
+
+    async def _do_remove_async(self, id: TKey) -> None:
+        """
+        Removes the aggregate root with the specified key based on configured delete mode.
+
+        Behavior depends on delete_mode configuration:
+        - DISABLED: Raises NotImplementedError (default)
+        - SOFT: Loads aggregate, calls mark_as_deleted(), persists deletion event
+        - HARD: Physically deletes the event stream (irreversible)
+
+        Args:
+            id: The identifier of the aggregate to remove
+
+        Raises:
+            NotImplementedError: When delete_mode is DISABLED
+            ValueError: When SOFT delete but aggregate lacks deletion method
+            Exception: When aggregate not found or deletion fails
+        """
+        match self._options.delete_mode:
+            case DeleteMode.DISABLED:
+                raise NotImplementedError("Deletion is disabled for this repository. " "Event sourcing repositories preserve immutable history by default. " "Configure delete_mode=DeleteMode.SOFT for soft delete " "or delete_mode=DeleteMode.HARD for physical stream deletion.")
+
+            case DeleteMode.SOFT:
+                await self._soft_delete_async(id)
+
+            case DeleteMode.HARD:
+                await self._hard_delete_async(id)
+
+    async def _soft_delete_async(self, id: TKey) -> None:
+        """
+        Soft delete by calling aggregate's deletion method.
+
+        The repository will:
+        1. Load the aggregate via get_async()
+        2. Call aggregate's deletion method (mark_as_deleted or mark_deleted)
+        3. Persist the deletion event via _do_update_async()
+
+        This preserves event history while marking the aggregate as deleted.
+        The aggregate controls deletion semantics and domain events.
+
+        Args:
+            id: The identifier of the aggregate to soft delete
+
+        Raises:
+            Exception: If aggregate not found
+            ValueError: If aggregate lacks required deletion method
+        """
+        # Load the aggregate
+        aggregate = await self.get_async(id)
+        if aggregate is None:
+            raise Exception(f"Aggregate with id '{id}' not found")
+
+        # Call the aggregate's deletion method (convention-based)
+        method_name = self._options.soft_delete_method_name
+        if hasattr(aggregate, method_name) and callable(getattr(aggregate, method_name)):
+            deletion_method = getattr(aggregate, method_name)
+            deletion_method()
+        elif hasattr(aggregate, "mark_deleted") and callable(getattr(aggregate, "mark_deleted")):
+            # Fallback to alternative method name
+            aggregate.mark_deleted()
+        else:
+            aggregate_type = type(aggregate).__name__
+            raise ValueError(f"Aggregate {aggregate_type} does not have a '{method_name}()' or 'mark_deleted()' method. " f"Soft delete requires the aggregate to implement deletion logic. " f"Add a method like: def {method_name}(self) -> None: ...")
+
+        # Persist the deletion event via update
+        await self._do_update_async(aggregate)
+
+    async def _hard_delete_async(self, id: TKey) -> None:
+        """
+        Physically delete the entire event stream from the event store.
+
+        WARNING: This is irreversible and removes all history for this aggregate.
+        Use for:
+        - GDPR compliance (right to be forgotten)
+        - Data cleanup after retention period
+        - Removing test/invalid data
+
+        Args:
+            id: The identifier of the aggregate to hard delete
+
+        Raises:
+            Exception: If stream deletion fails
+        """
+        stream_id = self._build_stream_id_for(id)
+        await self._eventstore.delete_async(stream_id)
+
+    async def _publish_domain_events(self, entity: TAggregate) -> None:
+        """
+        Override base class event publishing for event-sourced aggregates.
+
+        Event sourcing repositories DO NOT publish events directly because:
+        1. Events are already persisted to the EventStore
+        2. ReadModelReconciliator subscribes to EventStore and publishes ALL events
+        3. Publishing here would cause DOUBLE PUBLISHING (once here, once from ReadModelReconciliator)
+
+        For event-sourced aggregates:
+        - Events are persisted to EventStore by _do_add_async/_do_update_async
+        - ReadModelReconciliator.on_event_record_stream_next_async() publishes via mediator
+        - This ensures single, reliable event publishing from the source of truth (EventStore)
+
+        State-based repositories still use the base class _publish_domain_events() correctly.
+        """
+        # Do nothing - ReadModelReconciliator handles event publishing from EventStore
+
+    def _build_stream_id_for(self, aggregate_id: TKey):
+        """Builds a new stream id for the specified aggregate"""
+        aggregate_name = self.__orig_class__.__args__[0].__name__
+        return f"{aggregate_name.lower()}-{aggregate_id}"
+
+    def _encode_event(self, e: DomainEvent):
+        """Encodes a domain event into a new event descriptor"""
+        event_type = type(e).__name__.lower()
+        return EventDescriptor(event_type, e)
+
+    @staticmethod
+    def configure(builder: ApplicationBuilderBase, entity_type: type, key_type: type) -> ApplicationBuilderBase:
+        """Configures the specified application to use an event sourcing based repository implementation to manage the specified type of entity"""
+        builder.services.try_add_singleton(
+            EventSourcingRepositoryOptions[entity_type, key_type],
+            singleton=EventSourcingRepositoryOptions[entity_type, key_type](),
+        )
+        builder.services.try_add_singleton(Repository[entity_type, key_type], EventSourcingRepository[entity_type, key_type])
+        return builder