qx-eventstore 0.2.0__tar.gz

qx_eventstore-0.2.0/.gitignore

@@ -0,0 +1,56 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+eggs/
+.eggs/
+sdist/
+wheels/
+*.egg-link
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# uv
+.uv/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Type checking
+.mypy_cache/
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Docker
+*.env.local
+
+# Dist artifacts
+dist/
+
+# VS Code extension build artifacts
+extensions/vscode/node_modules/
+extensions/vscode/dist/
+extensions/vscode/*.vsix

qx_eventstore-0.2.0/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.4
+Name: qx-eventstore
+Version: 0.2.0
+Summary: Qx event store: event-sourced aggregates with Postgres-backed event log and snapshots
+Author: Qx Engineering
+License: MIT
+Requires-Python: >=3.14
+Requires-Dist: qx-core
+Requires-Dist: qx-db
+Description-Content-Type: text/markdown
+
+# qx-eventstore
+
+Event-sourced aggregates for the Qx framework. Aggregates are persisted as an immutable event
+stream in Postgres, with optional periodic snapshots for efficient replay.
+
+## Usage
+
+```python
+from dataclasses import dataclass, field
+from qx.eventstore import EventSourcedAggregate, EventStore, include_eventstore_tables
+
+class MoneyDeposited(DomainEvent):
+    event_name = "account.money_deposited"
+    amount: int
+
+@dataclass
+class Account(EventSourcedAggregate[str]):
+    balance: int = field(default=0)
+
+    def deposit(self, amount: int) -> None:
+        self.record_event(MoneyDeposited(amount=amount))
+
+    def apply_moneydeposited(self, ev: MoneyDeposited) -> None:
+        self.balance += ev.amount
+```

qx_eventstore-0.2.0/README.md

@@ -0,0 +1,25 @@
+# qx-eventstore
+
+Event-sourced aggregates for the Qx framework. Aggregates are persisted as an immutable event
+stream in Postgres, with optional periodic snapshots for efficient replay.
+
+## Usage
+
+```python
+from dataclasses import dataclass, field
+from qx.eventstore import EventSourcedAggregate, EventStore, include_eventstore_tables
+
+class MoneyDeposited(DomainEvent):
+    event_name = "account.money_deposited"
+    amount: int
+
+@dataclass
+class Account(EventSourcedAggregate[str]):
+    balance: int = field(default=0)
+
+    def deposit(self, amount: int) -> None:
+        self.record_event(MoneyDeposited(amount=amount))
+
+    def apply_moneydeposited(self, ev: MoneyDeposited) -> None:
+        self.balance += ev.amount
+```

qx_eventstore-0.2.0/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "qx-eventstore"
+version = "0.2.0"
+description = "Qx event store: event-sourced aggregates with Postgres-backed event log and snapshots"
+readme = "README.md"
+requires-python = ">=3.14"
+license = { text = "MIT" }
+authors = [{ name = "Qx Engineering" }]
+dependencies = [
+    "qx-core",
+    "qx-db",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/qx"]

qx_eventstore-0.2.0/src/qx/eventstore/__init__.py

@@ -0,0 +1,17 @@
+"""qx-eventstore: event-sourced aggregates with Postgres-backed event log."""
+
+from qx.eventstore.aggregate import EventSourcedAggregate
+from qx.eventstore.store import EventStore
+from qx.eventstore.table import (
+    AGGREGATE_EVENTS_TABLE_NAME,
+    AGGREGATE_SNAPSHOTS_TABLE_NAME,
+    include_eventstore_tables,
+)
+
+__all__ = [
+    "AGGREGATE_EVENTS_TABLE_NAME",
+    "AGGREGATE_SNAPSHOTS_TABLE_NAME",
+    "EventSourcedAggregate",
+    "EventStore",
+    "include_eventstore_tables",
+]

qx_eventstore-0.2.0/src/qx/eventstore/aggregate.py

@@ -0,0 +1,91 @@
+"""EventSourcedAggregate — base class for event-sourced aggregates."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, TypeVar
+
+if TYPE_CHECKING:
+    from qx.core.domain.events import DomainEvent
+
+__all__ = ["EventSourcedAggregate"]
+
+TId = TypeVar("TId")
+
+_APPLY_PREFIX = "apply_"
+
+
+@dataclass
+class EventSourcedAggregate[TId]:
+    """Base class for aggregates persisted as an event stream.
+
+    Subclass and implement ``apply_<EventClassName>`` methods — they are the
+    *only* state mutators. Command methods call ``record_event`` which buffers
+    the event and immediately applies it::
+
+        class Account(EventSourcedAggregate[Identifier]):
+            balance: int = field(default=0)
+
+            def deposit(self, amount: int) -> None:
+                self.record_event(MoneyDeposited(amount=amount))
+
+            def apply_money_deposited(self, ev: MoneyDeposited) -> None:
+                self.balance += ev.amount
+
+    The repository loads the event stream, calls ``_replay`` to restore
+    state, then drains pending events on save.
+    """
+
+    id: TId
+    version: int = field(default=0, compare=False)
+    _pending_events: list[DomainEvent] = field(
+        default_factory=list, repr=False, compare=False, init=False
+    )
+
+    def record_event(self, event: DomainEvent) -> None:
+        """Buffer an event and apply it immediately to update local state."""
+        self._pending_events.append(event)
+        self._apply(event)
+
+    def pull_events(self) -> list[DomainEvent]:
+        """Drain and return pending events. Called by the repository at save time."""
+        events = list(self._pending_events)
+        self._pending_events.clear()
+        return events
+
+    @property
+    def has_pending_events(self) -> bool:
+        return bool(self._pending_events)
+
+    def _apply(self, event: DomainEvent) -> None:
+        """Dispatch to the appropriate apply_* method if it exists."""
+        method_name = f"{_APPLY_PREFIX}{type(event).__name__.lower()}"
+        handler = getattr(self, method_name, None)
+        if handler is not None:
+            handler(event)
+
+    def _replay(self, events: list[DomainEvent], *, version: int) -> None:
+        """Restore state by replaying a sequence of persisted events.
+
+        Called by the repository after loading the event stream. Does NOT
+        buffer events into ``_pending_events``; they are already persisted.
+        """
+        for event in events:
+            self._apply(event)
+        self.version = version
+
+    @classmethod
+    def _from_events(
+        cls,
+        id: TId,
+        events: list[DomainEvent],
+        *,
+        version: int,
+    ) -> Any:
+        """Reconstruct an instance from its full event history."""
+        instance: EventSourcedAggregate[TId] = object.__new__(cls)
+        instance.id = id
+        instance.version = 0
+        instance._pending_events = []
+        instance._replay(events, version=version)
+        return instance

qx_eventstore-0.2.0/src/qx/eventstore/store.py

@@ -0,0 +1,230 @@
+"""EventStore — append and replay aggregate event streams."""
+
+from __future__ import annotations
+
+import dataclasses
+import importlib
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any
+from uuid import uuid4
+
+from qx.core import ConflictError, Result
+from sqlalchemy import select
+from sqlalchemy.dialects.postgresql import insert as pg_insert
+
+if TYPE_CHECKING:
+    from qx.core.domain.events import DomainEvent
+    from qx.eventstore.aggregate import EventSourcedAggregate
+    from sqlalchemy import Table
+    from sqlalchemy.ext.asyncio import AsyncSession
+
+__all__ = ["EventStore"]
+
+
+class EventStore:
+    """Postgres-backed event log for event-sourced aggregates.
+
+    Append events in a single call; load them back for replay. Optionally
+    reads/writes snapshots to avoid full-stream replay on large aggregates.
+
+    Usage::
+
+        store = EventStore(session, events_table, snapshots_table)
+
+        # append events after handling a command
+        await store.append(account, aggregate_type="accounts.Account")
+
+        # load and replay
+        account = await store.load(
+            Account,
+            aggregate_id=str(account_id),
+            aggregate_type="accounts.Account",
+        )
+    """
+
+    def __init__(
+        self,
+        session: AsyncSession,
+        events_table: Table,
+        snapshots_table: Table,
+        *,
+        snapshot_every: int = 50,
+    ) -> None:
+        self._session = session
+        self._events = events_table
+        self._snapshots = snapshots_table
+        self._snapshot_every = snapshot_every
+
+    async def append(
+        self,
+        aggregate: EventSourcedAggregate[Any],
+        *,
+        aggregate_type: str,
+        tenant_id: str | None = None,
+    ) -> Result[int]:
+        """Drain pending events from ``aggregate`` and append them to the log.
+
+        Returns the new version (last sequence number written).
+        Raises on optimistic concurrency conflict (duplicate sequence).
+        """
+        events = aggregate.pull_events()
+        if not events:
+            return Result.success(aggregate.version)
+
+        base_seq = aggregate.version
+        now = datetime.now(UTC)
+        rows = []
+        for i, event in enumerate(events, start=1):
+            rows.append(
+                {
+                    "id": uuid4(),
+                    "aggregate_type": aggregate_type,
+                    "aggregate_id": str(aggregate.id),
+                    "sequence": base_seq + i,
+                    "event_type": f"{type(event).__module__}.{type(event).__qualname__}",
+                    "event_name": event.event_name,
+                    "payload": event.model_dump(mode="json"),
+                    "occurred_at": now,
+                    "tenant_id": tenant_id,
+                }
+            )
+
+        try:
+            await self._session.execute(self._events.insert(), rows)
+        except Exception as exc:
+            if "unique" in str(exc).lower():
+                return Result.failure(
+                    ConflictError(
+                        code="eventstore.version_conflict",
+                        message=f"{aggregate_type}:{aggregate.id} was modified concurrently",
+                    )
+                )
+            raise
+
+        new_version = base_seq + len(events)
+        aggregate.version = new_version
+
+        if new_version % self._snapshot_every == 0:
+            await self._save_snapshot(aggregate, aggregate_type=aggregate_type, tenant_id=tenant_id)
+
+        return Result.success(new_version)
+
+    async def load(
+        self,
+        cls: type[EventSourcedAggregate[Any]],
+        *,
+        aggregate_id: str,
+        aggregate_type: str,
+    ) -> Result[EventSourcedAggregate[Any] | None]:
+        """Load an aggregate by replaying its event stream.
+
+        If a snapshot exists, replay only events after the snapshot version.
+        Returns ``None`` if no events (and no snapshot) exist for this id.
+        """
+        snapshot_state: dict[str, Any] | None = None
+        snapshot_version = 0
+
+        snap_row = await self._session.execute(
+            select(self._snapshots).where(
+                self._snapshots.c.aggregate_type == aggregate_type,
+                self._snapshots.c.aggregate_id == aggregate_id,
+            )
+        )
+        snap = snap_row.mappings().first()
+        if snap is not None:
+            snapshot_state = dict(snap["state"]) if isinstance(snap["state"], dict) else {}
+            snapshot_version = int(snap["version"])
+
+        rows = await self._session.execute(
+            select(self._events)
+            .where(
+                self._events.c.aggregate_type == aggregate_type,
+                self._events.c.aggregate_id == aggregate_id,
+                self._events.c.sequence > snapshot_version,
+            )
+            .order_by(self._events.c.sequence)
+        )
+        event_rows = list(rows.mappings())
+
+        if snapshot_state is None and not event_rows:
+            return Result.success(None)
+
+        events = [self._deserialize_event(dict(r)) for r in event_rows]
+        final_version = int(event_rows[-1]["sequence"]) if event_rows else snapshot_version
+
+        if snapshot_state is not None:
+            aggregate = _restore_from_snapshot(cls, aggregate_id, snapshot_state, snapshot_version)
+            aggregate._replay(events, version=final_version)
+        else:
+            aggregate = cls._from_events(aggregate_id, events, version=final_version)
+
+        return Result.success(aggregate)
+
+    async def _save_snapshot(
+        self,
+        aggregate: EventSourcedAggregate[Any],
+        *,
+        aggregate_type: str,
+        tenant_id: str | None,
+    ) -> None:
+        """Upsert a snapshot row for the current aggregate state."""
+        state = _serialize_aggregate(aggregate)
+        now = datetime.now(UTC)
+        stmt = (
+            pg_insert(self._snapshots)
+            .values(
+                id=uuid4(),
+                aggregate_type=aggregate_type,
+                aggregate_id=str(aggregate.id),
+                state=state,
+                version=aggregate.version,
+                taken_at=now,
+                tenant_id=tenant_id,
+            )
+            .on_conflict_do_update(
+                index_elements=["aggregate_type", "aggregate_id"],
+                set_={"state": state, "version": aggregate.version, "taken_at": now},
+            )
+        )
+        await self._session.execute(stmt)
+
+    @staticmethod
+    def _deserialize_event(row: dict[str, Any]) -> DomainEvent:
+        """Reconstruct a DomainEvent from a stored event row."""
+        event_type_path: str = row["event_type"]
+        module_path, _, class_name = event_type_path.rpartition(".")
+        module = importlib.import_module(module_path)
+        event_cls = getattr(module, class_name)
+        return event_cls.model_validate(row["payload"])  # type: ignore[no-any-return]
+
+
+def _serialize_aggregate(aggregate: EventSourcedAggregate[Any]) -> dict[str, Any]:
+    """Best-effort dict serialization for snapshot state."""
+    if dataclasses.is_dataclass(aggregate):
+        return {k: v for k, v in dataclasses.asdict(aggregate).items() if not k.startswith("_")}
+    return {}
+
+
+def _restore_from_snapshot(
+    cls: type[EventSourcedAggregate[Any]],
+    aggregate_id: str,
+    state: dict[str, Any],
+    version: int,
+) -> EventSourcedAggregate[Any]:
+    """Build a partial aggregate from snapshot state (before replaying tail events)."""
+    instance: EventSourcedAggregate[Any] = object.__new__(cls)
+    for f in dataclasses.fields(instance):
+        if f.name.startswith("_"):
+            continue
+        if f.name == "id":
+            object.__setattr__(instance, "id", aggregate_id)
+        elif f.name == "version":
+            object.__setattr__(instance, "version", version)
+        elif f.name in state:
+            object.__setattr__(instance, f.name, state[f.name])
+        elif f.default is not dataclasses.MISSING:
+            object.__setattr__(instance, f.name, f.default)
+        elif f.default_factory is not dataclasses.MISSING:
+            object.__setattr__(instance, f.name, f.default_factory())
+    object.__setattr__(instance, "_pending_events", [])
+    return instance

qx_eventstore-0.2.0/src/qx/eventstore/table.py

@@ -0,0 +1,107 @@
+"""SQLAlchemy table definitions for the event store."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from sqlalchemy import Column, DateTime, Index, Integer, String, Table, text
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.dialects.postgresql import UUID as PG_UUID
+
+if TYPE_CHECKING:
+    from sqlalchemy import MetaData
+
+__all__ = [
+    "AGGREGATE_EVENTS_TABLE_NAME",
+    "AGGREGATE_SNAPSHOTS_TABLE_NAME",
+    "include_eventstore_tables",
+]
+
+AGGREGATE_EVENTS_TABLE_NAME = "qx_aggregate_events"
+AGGREGATE_SNAPSHOTS_TABLE_NAME = "qx_aggregate_snapshots"
+
+
+def include_eventstore_tables(metadata: MetaData) -> tuple[Table, Table]:
+    """Add event-store tables to ``metadata`` and return ``(events, snapshots)``.
+
+    Call once at startup alongside your aggregate tables::
+
+        metadata = make_metadata()
+        include_outbox_table(metadata)
+        events_table, snapshots_table = include_eventstore_tables(metadata)
+
+    Schema — events
+    ---------------
+    id              UUID PK
+    aggregate_type  string  — fully-qualified aggregate class name
+    aggregate_id    string  — aggregate identifier (stringified)
+    sequence        int     — monotonic per-aggregate sequence number (1-based)
+    event_type      string  — fully-qualified event class name
+    event_name      string  — stable human-readable name (e.g. "account.money_deposited")
+    payload         JSONB   — serialised event body
+    occurred_at     timestamptz
+    tenant_id       string | NULL
+
+    Schema — snapshots
+    ------------------
+    id              UUID PK
+    aggregate_type  string
+    aggregate_id    string  — unique per (aggregate_type, aggregate_id)
+    state           JSONB   — serialised aggregate state at ``version``
+    version         int     — sequence number of the last event baked in
+    taken_at        timestamptz
+    tenant_id       string | NULL
+    """
+    events = Table(
+        AGGREGATE_EVENTS_TABLE_NAME,
+        metadata,
+        Column("id", PG_UUID(as_uuid=True), primary_key=True),
+        Column("aggregate_type", String(255), nullable=False),
+        Column("aggregate_id", String(255), nullable=False),
+        Column("sequence", Integer, nullable=False),
+        Column("event_type", String(255), nullable=False),
+        Column("event_name", String(255), nullable=False),
+        Column("payload", JSONB, nullable=False, server_default="{}"),
+        Column(
+            "occurred_at",
+            DateTime(timezone=True),
+            nullable=False,
+            server_default=text("now()"),
+        ),
+        Column("tenant_id", String(255), nullable=True),
+        Index(
+            f"ix_{AGGREGATE_EVENTS_TABLE_NAME}_aggregate",
+            "aggregate_type",
+            "aggregate_id",
+            "sequence",
+            unique=True,
+        ),
+        Index(f"ix_{AGGREGATE_EVENTS_TABLE_NAME}_event_name", "event_name"),
+        extend_existing=True,
+    )
+
+    snapshots = Table(
+        AGGREGATE_SNAPSHOTS_TABLE_NAME,
+        metadata,
+        Column("id", PG_UUID(as_uuid=True), primary_key=True),
+        Column("aggregate_type", String(255), nullable=False),
+        Column("aggregate_id", String(255), nullable=False),
+        Column("state", JSONB, nullable=False, server_default="{}"),
+        Column("version", Integer, nullable=False),
+        Column(
+            "taken_at",
+            DateTime(timezone=True),
+            nullable=False,
+            server_default=text("now()"),
+        ),
+        Column("tenant_id", String(255), nullable=True),
+        Index(
+            f"ix_{AGGREGATE_SNAPSHOTS_TABLE_NAME}_aggregate",
+            "aggregate_type",
+            "aggregate_id",
+            unique=True,
+        ),
+        extend_existing=True,
+    )
+
+    return events, snapshots

qx_eventstore-0.2.0/tests/test_eventstore_unit.py

@@ -0,0 +1,276 @@
+"""EventStore unit tests — no database required."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import ClassVar
+from unittest.mock import AsyncMock, MagicMock, patch
+from uuid import uuid4
+
+from qx.core import DomainEvent
+from qx.eventstore import EventSourcedAggregate, EventStore
+from qx.eventstore.table import include_eventstore_tables
+from sqlalchemy import MetaData
+
+# ---- Domain fixtures ----
+
+
+class MoneyDeposited(DomainEvent):
+    event_name: ClassVar[str] = "account.money_deposited"
+    amount: int
+
+
+class MoneyWithdrawn(DomainEvent):
+    event_name: ClassVar[str] = "account.money_withdrawn"
+    amount: int
+
+
+@dataclass
+class BankAccount(EventSourcedAggregate[str]):
+    balance: int = field(default=0)
+
+    def deposit(self, amount: int) -> None:
+        self.record_event(MoneyDeposited(amount=amount))
+
+    def withdraw(self, amount: int) -> None:
+        self.record_event(MoneyWithdrawn(amount=amount))
+
+    def apply_moneydeposited(self, ev: MoneyDeposited) -> None:
+        self.balance += ev.amount
+
+    def apply_moneywithdrawn(self, ev: MoneyWithdrawn) -> None:
+        self.balance -= ev.amount
+
+
+# ---- EventSourcedAggregate ----
+
+
+def test_record_event_buffers_and_applies() -> None:
+    account = BankAccount(id="acc-1")
+    account.deposit(100)
+
+    assert account.balance == 100
+    assert account.has_pending_events
+    assert len(account._pending_events) == 1
+
+
+def test_pull_events_drains_buffer() -> None:
+    account = BankAccount(id="acc-1")
+    account.deposit(50)
+    account.withdraw(20)
+
+    events = account.pull_events()
+
+    assert len(events) == 2
+    assert not account.has_pending_events
+
+
+def test_replay_restores_state() -> None:
+    account = BankAccount(id="acc-1")
+    events = [MoneyDeposited(amount=100), MoneyWithdrawn(amount=30)]
+
+    account._replay(events, version=2)
+
+    assert account.balance == 70
+    assert account.version == 2
+    assert not account.has_pending_events
+
+
+def test_from_events_constructs_aggregate() -> None:
+    events = [MoneyDeposited(amount=200), MoneyWithdrawn(amount=50)]
+    account = BankAccount._from_events("acc-1", events, version=2)
+
+    assert account.balance == 150
+    assert account.version == 2
+    assert not account.has_pending_events
+
+
+def test_unknown_event_type_is_ignored() -> None:
+    class OtherEvent(DomainEvent):
+        event_name: ClassVar[str] = "other"
+
+    account = BankAccount(id="acc-1")
+    account._replay([OtherEvent()], version=1)
+    assert account.balance == 0  # no handler, no crash
+
+
+# ---- EventStore.append ----
+
+
+async def test_append_writes_rows_for_each_event() -> None:
+    session = AsyncMock()
+    store = _make_store(session)
+    account = BankAccount(id="acc-1")
+    account.deposit(100)
+    account.withdraw(40)
+
+    result = await store.append(account, aggregate_type="test.BankAccount")
+
+    assert result.is_success
+    assert result.value == 2
+    assert account.version == 2
+    assert not account.has_pending_events
+    session.execute.assert_awaited_once()
+    rows = session.execute.call_args[0][1]
+    assert len(rows) == 2
+    assert rows[0]["sequence"] == 1
+    assert rows[1]["sequence"] == 2
+
+
+async def test_append_noop_when_no_pending_events() -> None:
+    session = AsyncMock()
+    store = _make_store(session)
+    account = BankAccount(id="acc-1")
+
+    result = await store.append(account, aggregate_type="test.BankAccount")
+
+    assert result.is_success
+    assert result.value == 0
+    session.execute.assert_not_awaited()
+
+
+async def test_append_uses_base_version_as_sequence_offset() -> None:
+    session = AsyncMock()
+    store = _make_store(session)
+    account = BankAccount(id="acc-1")
+    account.version = 5
+    account.deposit(10)
+
+    await store.append(account, aggregate_type="test.BankAccount")
+
+    rows = session.execute.call_args[0][1]
+    assert rows[0]["sequence"] == 6
+
+
+async def test_append_triggers_snapshot_at_threshold() -> None:
+    session = AsyncMock()
+    store = _make_store(session, snapshot_every=3)
+    account = BankAccount(id="acc-1")
+    account.version = 2
+    account.deposit(10)  # sequence 3 — threshold hit
+
+    with patch.object(store, "_save_snapshot", new=AsyncMock()) as mock_snap:
+        await store.append(account, aggregate_type="test.BankAccount")
+
+    mock_snap.assert_awaited_once()
+
+
+async def test_append_no_snapshot_below_threshold() -> None:
+    session = AsyncMock()
+    store = _make_store(session, snapshot_every=10)
+    account = BankAccount(id="acc-1")
+    account.deposit(10)
+
+    with patch.object(store, "_save_snapshot", new=AsyncMock()) as mock_snap:
+        await store.append(account, aggregate_type="test.BankAccount")
+
+    mock_snap.assert_not_awaited()
+
+
+# ---- EventStore.load ----
+
+
+async def test_load_returns_none_when_no_events_no_snapshot() -> None:
+    session = _session_with_rows(snap_row=None, event_rows=[])
+    store = _make_store(session)
+
+    result = await store.load(BankAccount, aggregate_id="acc-1", aggregate_type="test.BankAccount")
+
+    assert result.is_success
+    assert result.value is None
+
+
+async def test_load_replays_events_without_snapshot() -> None:
+    event_rows = [
+        _event_row(seq=1, event_cls=MoneyDeposited, payload={"amount": 100}),
+        _event_row(seq=2, event_cls=MoneyWithdrawn, payload={"amount": 30}),
+    ]
+    session = _session_with_rows(snap_row=None, event_rows=event_rows)
+    store = _make_store(session)
+
+    result = await store.load(BankAccount, aggregate_id="acc-1", aggregate_type="test.BankAccount")
+
+    assert result.is_success
+    account = result.value
+    assert account is not None
+    assert account.balance == 70
+    assert account.version == 2
+
+
+async def test_load_uses_snapshot_and_tail_events() -> None:
+    snap = {"id": "snap-uuid", "state": {"balance": 80, "id": "acc-1"}, "version": 5}
+    event_rows = [_event_row(seq=6, event_cls=MoneyDeposited, payload={"amount": 20})]
+    session = _session_with_rows(snap_row=snap, event_rows=event_rows)
+    store = _make_store(session)
+
+    result = await store.load(BankAccount, aggregate_id="acc-1", aggregate_type="test.BankAccount")
+
+    assert result.is_success
+    account = result.value
+    assert account is not None
+    assert account.balance == 100  # 80 from snapshot + 20 from tail
+    assert account.version == 6
+
+
+async def test_load_with_snapshot_and_no_tail_events() -> None:
+    snap = {"id": "snap-uuid", "state": {"balance": 50, "id": "acc-1"}, "version": 10}
+    session = _session_with_rows(snap_row=snap, event_rows=[])
+    store = _make_store(session)
+
+    result = await store.load(BankAccount, aggregate_id="acc-1", aggregate_type="test.BankAccount")
+
+    assert result.is_success
+    account = result.value
+    assert account is not None
+    assert account.balance == 50
+    assert account.version == 10
+
+
+# ---- Helpers ----
+
+
+def _make_real_tables() -> tuple:
+    return include_eventstore_tables(MetaData())
+
+
+def _make_store(session: AsyncMock, *, snapshot_every: int = 50) -> EventStore:
+    events_table, snapshots_table = _make_real_tables()
+    return EventStore(session, events_table, snapshots_table, snapshot_every=snapshot_every)
+
+
+def _event_row(*, seq: int, event_cls: type, payload: dict) -> dict:
+    full_type = f"{event_cls.__module__}.{event_cls.__qualname__}"
+    return {
+        "id": uuid4(),
+        "aggregate_type": "test.BankAccount",
+        "aggregate_id": "acc-1",
+        "sequence": seq,
+        "event_type": full_type,
+        "event_name": event_cls.event_name,
+        "payload": payload,
+    }
+
+
+def _session_with_rows(
+    *,
+    snap_row: dict | None,
+    event_rows: list[dict],
+) -> AsyncMock:
+    """Build a mock AsyncSession that returns snap_row then event_rows on execute calls."""
+    session = AsyncMock()
+
+    def _mapping_result(row: dict | None) -> MagicMock:
+        result = MagicMock()
+        result.mappings.return_value.first.return_value = row
+        return result
+
+    def _mapping_list(rows: list[dict]) -> MagicMock:
+        result = MagicMock()
+        result.mappings.return_value.__iter__ = MagicMock(return_value=iter(rows))
+        return result
+
+    session.execute.side_effect = [
+        _mapping_result(snap_row),
+        _mapping_list(event_rows),
+    ]
+    return session