Aggregates Application Ring Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Move the aggregates vertical into the domain/ and application/ rings, dissolve AggregateSnapshotManager into policy + scheduler + single-construction-path collaborators, and delete the transition/deprecation cruft this makes obsolete.

Architecture: AggregateRoot/DeclarativeAggregate move to the entities ring (domain/aggregate.py). A new use-case ring package application/aggregates/ holds the slimmed AggregateRepository and its snapshotting collaborators (SnapshotPolicy, SnapshotScheduler, take_snapshot, read_valid_snapshot). Snapshot/SnapshotStore physically relocate to ports/snapshots.py; snapshot exceptions consolidate into exceptions.py; the aggregates/ and snapshots/ packages are deleted with no aliases (unreleased software).

Tech Stack: Python 3.13, pydantic v2, pytest + pytest-asyncio + hypothesis, mypy strict, ruff, import-linter, mutmut.

Spec: docs/superpowers/specs/2026-07-30-aggregates-application-ring-design.md

Global Constraints


Task 1: Move AggregateRoot/DeclarativeAggregate to `domain/aggregate.py`

Files:

Interfaces:


git mv src/eventsource/aggregates/base.py src/eventsource/domain/aggregate.py

"""Entities ring. Pure: stdlib + pydantic only.

TRANSITION: DomainEvent/EventRegistry still live in eventsource.events and
count as this ring until sub-project 3 moves them.
"""

from eventsource.domain.aggregate import AggregateRoot, DeclarativeAggregate
from eventsource.domain.stream_id import CATEGORY_PATTERN, StreamId

__all__ = ["CATEGORY_PATTERN", "AggregateRoot", "DeclarativeAggregate", "StreamId"]

Replace from eventsource.aggregates.base import ... with from eventsource.domain.aggregate import ... in: src/eventsource/__init__.py, aggregates/__init__.py, aggregates/repository.py, aggregates/snapshot_manager.py (TYPE_CHECKING block), snapshots/strategies.py (TYPE_CHECKING block), testing/bdd.py, multitenancy/repository.py. Verify none remain:


grep -rn "aggregates.base\|aggregates import base" src/ --include="*.py"

Expected: no matches.


git mv tests/unit/test_aggregate_root.py tests/unit/domain/test_aggregate_root.py
git mv tests/unit/aggregates/test_aggregate_snapshot_methods.py tests/unit/domain/
git mv tests/unit/aggregates/test_create_event.py tests/unit/domain/
git mv tests/unit/aggregates/test_deferred_state.py tests/unit/domain/
grep -rln "eventsource.aggregates.base" tests/ | xargs sed -i 's/eventsource\.aggregates\.base/eventsource.domain.aggregate/g'

Run: uv run pytest tests/unit/domain/ tests/unit/aggregates/ tests/unit/test_aggregate_repository.py tests/unit/test_additional_coverage.py tests/unit/testing/ -q Expected: all pass. Run: uv run mypy src/eventsource/ --config-file=pyproject.toml Expected: clean.


git add -A && git commit -m "refactor: move aggregate root into domain ring"

Task 2: Create `application/aggregates/snapshotting.py` (TDD)

Files:

Interfaces:

tests/unit/application/aggregates/test_snapshotting.py (use tests/fixtures/aggregates.py aggregate fixtures where a real aggregate is needed; otherwise a minimal local DeclarativeAggregate):


"""Tests for application.aggregates.snapshotting collaborators."""

import asyncio
from datetime import UTC, datetime
from uuid import uuid4

import pytest

from eventsource.adapters.memory.snapshots import InMemorySnapshotStore
from eventsource.application.aggregates.snapshotting import (
    BackgroundScheduler,
    EveryNEvents,
    ImmediateScheduler,
    Never,
    SnapshotPolicy,
    SnapshotScheduler,
    read_valid_snapshot,
    take_snapshot,
)
from eventsource.ports.snapshots import Snapshot
from tests.fixtures.aggregates import OrderAggregate  # adjust name to the actual fixture class


class TestEveryNEvents:
    def test_true_on_threshold_boundary(self, order_at_version_100):
        assert EveryNEvents(100).should_snapshot(order_at_version_100, 1) is True

    def test_false_off_boundary(self, order_at_version_101):
        assert EveryNEvents(100).should_snapshot(order_at_version_101, 1) is False

    def test_false_at_version_zero(self, fresh_order):
        assert EveryNEvents(1).should_snapshot(fresh_order, 0) is False

    def test_rejects_nonpositive_n(self):
        with pytest.raises(ValueError):
            EveryNEvents(0)
        with pytest.raises(ValueError):
            EveryNEvents(-5)

    def test_satisfies_policy_protocol(self):
        assert isinstance(EveryNEvents(10), SnapshotPolicy)


class TestNever:
    def test_always_false(self, order_at_version_100):
        assert Never().should_snapshot(order_at_version_100, 10_000) is False

    def test_satisfies_policy_protocol(self):
        assert isinstance(Never(), SnapshotPolicy)


class TestTakeSnapshot:
    async def test_writes_snapshot_with_aggregate_state(self, order_at_version_3):
        store = InMemorySnapshotStore()
        snap = await take_snapshot(order_at_version_3, "Order", store)
        assert snap.version == order_at_version_3.version
        assert snap.aggregate_id == order_at_version_3.aggregate_id
        assert snap.schema_version == getattr(type(order_at_version_3), "schema_version", 1)
        stored = await store.get_snapshot(snap.aggregate_id, "Order")
        assert stored == snap

    async def test_store_errors_propagate(self, order_at_version_3, failing_store):
        with pytest.raises(RuntimeError):
            await take_snapshot(order_at_version_3, "Order", failing_store)


class TestReadValidSnapshot:
    async def test_returns_snapshot_when_schema_matches(self, order_at_version_3):
        store = InMemorySnapshotStore()
        snap = await take_snapshot(order_at_version_3, "Order", store)
        got = await read_valid_snapshot(store, snap.aggregate_id, "Order", type(order_at_version_3))
        assert got == snap

    async def test_returns_none_when_missing(self):
        store = InMemorySnapshotStore()
        assert await read_valid_snapshot(store, uuid4(), "Order", OrderAggregate) is None

    async def test_returns_none_on_schema_mismatch(self):
        store = InMemorySnapshotStore()
        await store.save_snapshot(Snapshot(
            aggregate_id=(aid := uuid4()), aggregate_type="Order", version=5,
            state={}, schema_version=999, created_at=datetime.now(UTC),
        ))
        assert await read_valid_snapshot(store, aid, "Order", OrderAggregate) is None

    async def test_returns_none_on_store_error(self, failing_store):
        assert await read_valid_snapshot(failing_store, uuid4(), "Order", OrderAggregate) is None


class TestImmediateScheduler:
    async def test_awaits_write_and_returns_snapshot(self, order_at_version_3):
        store = InMemorySnapshotStore()
        sched = ImmediateScheduler()
        snap = await sched.schedule(
            take_snapshot(order_at_version_3, "Order", store),
            aggregate_type="Order", aggregate_id=order_at_version_3.aggregate_id,
        )
        assert snap is not None
        assert await store.get_snapshot(snap.aggregate_id, "Order") == snap

    async def test_swallows_write_failure_returns_none(self, order_at_version_3, failing_store, caplog):
        sched = ImmediateScheduler()
        result = await sched.schedule(
            take_snapshot(order_at_version_3, "Order", failing_store),
            aggregate_type="Order", aggregate_id=order_at_version_3.aggregate_id,
        )
        assert result is None
        assert "Failed to create snapshot" in caplog.text

    async def test_uniform_pending_surface(self):
        sched = ImmediateScheduler()
        assert sched.pending_count == 0
        assert await sched.await_pending() == 0
        assert isinstance(sched, SnapshotScheduler)


class TestBackgroundScheduler:
    async def test_schedules_and_completes(self, order_at_version_3):
        store = InMemorySnapshotStore()
        sched = BackgroundScheduler()
        result = await sched.schedule(
            take_snapshot(order_at_version_3, "Order", store),
            aggregate_type="Order", aggregate_id=order_at_version_3.aggregate_id,
        )
        assert result is None  # deferred
        await sched.await_pending()
        assert await store.get_snapshot(order_at_version_3.aggregate_id, "Order") is not None

    async def test_swallows_background_failure(self, order_at_version_3, failing_store, caplog):
        sched = BackgroundScheduler()
        await sched.schedule(
            take_snapshot(order_at_version_3, "Order", failing_store),
            aggregate_type="Order", aggregate_id=order_at_version_3.aggregate_id,
        )
        await sched.await_pending()
        assert "Background snapshot creation failed" in caplog.text

    async def test_satisfies_scheduler_protocol(self):
        assert isinstance(BackgroundScheduler(), SnapshotScheduler)

Add module-level fixtures in the same file: failing_store (an InMemorySnapshotStore subclass whose save_snapshot/get_snapshot raise RuntimeError("store down")), and fresh_order / order_at_version_3 / order_at_version_100 / order_at_version_101 built by applying N events to the fixture aggregate from tests/fixtures/aggregates.py (read that file first and reuse its event/aggregate classes; if it lacks a convenient one, define a minimal DeclarativeAggregate + one DomainEvent subclass locally in the test module).

Run: uv run pytest tests/unit/application/ -q Expected: FAIL β€” ModuleNotFoundError: eventsource.application.

src/eventsource/application/__init__.py:


"""Use-case ring: application services composing domain objects with ports."""

src/eventsource/application/aggregates/__init__.py:


"""Aggregate use cases: repository and snapshotting collaborators."""

from eventsource.application.aggregates.snapshotting import (
    BackgroundScheduler,
    EveryNEvents,
    ImmediateScheduler,
    Never,
    SnapshotPolicy,
    SnapshotScheduler,
    read_valid_snapshot,
    take_snapshot,
)

__all__ = [
    "BackgroundScheduler",
    "EveryNEvents",
    "ImmediateScheduler",
    "Never",
    "SnapshotPolicy",
    "SnapshotScheduler",
    "read_valid_snapshot",
    "take_snapshot",
]

(AggregateRepository is added to this __init__ in Task 3.)

src/eventsource/application/aggregates/snapshotting.py:


"""Snapshotting collaborators for the aggregate repository.

Snapshots are disposable optimizations, never the source of truth (ADR 0021,
superseding ADR 0017): every automatic-path failure degrades to full event
replay instead of raising. Four collaborators replace the former
AggregateSnapshotManager:

- SnapshotPolicy (EveryNEvents / Never): *when* to snapshot β€” pure predicate.
- SnapshotScheduler (ImmediateScheduler / BackgroundScheduler): *how* the
  write executes β€” sync-and-swallow or fire-and-forget with a join point.
- take_snapshot(): the single spelling of snapshot construction. Errors
  propagate; degradation is the scheduler's job, so the manual path
  (AggregateRepository.create_snapshot) stays strict.
- read_valid_snapshot(): load-path fetch + schema validation; all failure
  modes collapse to None.
"""

import logging
from collections.abc import Coroutine
from dataclasses import dataclass
from datetime import UTC, datetime
from typing import Any, Protocol, runtime_checkable
from uuid import UUID

from eventsource._internal.background_tasks import BackgroundTaskManager
from eventsource.domain.aggregate import AggregateRoot
from eventsource.ports.snapshots import Snapshot, SnapshotStore

logger = logging.getLogger(__name__)


@runtime_checkable
class SnapshotPolicy(Protocol):
    """Decides *when* a snapshot should be taken. Pure and synchronous."""

    def should_snapshot(
        self, aggregate: AggregateRoot[Any], events_since_snapshot: int
    ) -> bool: ...


@dataclass(frozen=True)
class EveryNEvents:
    """Snapshot at deterministic version boundaries: version % n == 0.

    Keyed off the aggregate version (not events_since_snapshot) so that two
    processes saving the same aggregate agree on where boundaries fall. A
    save jumping the version across a boundary without landing on it takes
    no snapshot β€” acceptable, snapshots are an optimization.
    """

    n: int

    def __post_init__(self) -> None:
        if self.n <= 0:
            raise ValueError(f"EveryNEvents requires n >= 1, got {self.n}")

    def should_snapshot(
        self, aggregate: AggregateRoot[Any], events_since_snapshot: int
    ) -> bool:
        return aggregate.version > 0 and aggregate.version % self.n == 0


@dataclass(frozen=True)
class Never:
    """Manual mode: automatic snapshotting disabled."""

    def should_snapshot(
        self, aggregate: AggregateRoot[Any], events_since_snapshot: int
    ) -> bool:
        return False


async def take_snapshot(
    aggregate: AggregateRoot[Any], aggregate_type: str, store: SnapshotStore
) -> Snapshot:
    """Build and persist a snapshot of the aggregate. The single spelling
    of snapshot construction. Errors propagate to the caller."""
    schema_version = getattr(type(aggregate), "schema_version", 1)
    snapshot = Snapshot(
        aggregate_id=aggregate.aggregate_id,
        aggregate_type=aggregate_type,
        version=aggregate.version,
        state=aggregate._serialize_state(),
        schema_version=schema_version,
        created_at=datetime.now(UTC),
    )
    await store.save_snapshot(snapshot)
    logger.info(
        "Created snapshot for %s/%s at version %d (schema_version=%d)",
        aggregate_type,
        aggregate.aggregate_id,
        snapshot.version,
        schema_version,
    )
    return snapshot


async def read_valid_snapshot(
    store: SnapshotStore,
    aggregate_id: UUID,
    aggregate_type: str,
    aggregate_factory: type[AggregateRoot[Any]],
) -> Snapshot | None:
    """Fetch and validate a snapshot for the load path.

    Store error, missing snapshot, and schema mismatch all collapse to
    None: the repository falls back to full event replay."""
    try:
        snapshot = await store.get_snapshot(aggregate_id, aggregate_type)
    except Exception as e:
        logger.warning(
            "Error loading snapshot for %s/%s: %s. Falling back to event replay.",
            aggregate_type,
            aggregate_id,
            e,
        )
        return None
    if snapshot is None:
        return None
    expected = getattr(aggregate_factory, "schema_version", 1)
    if snapshot.schema_version != expected:
        logger.info(
            "Snapshot schema version mismatch for %s/%s: "
            "snapshot has v%d, aggregate expects v%d. "
            "Falling back to full event replay.",
            aggregate_type,
            aggregate_id,
            snapshot.schema_version,
            expected,
        )
        return None
    logger.debug(
        "Loaded valid snapshot for %s/%s at version %d",
        aggregate_type,
        aggregate_id,
        snapshot.version,
    )
    return snapshot


@runtime_checkable
class SnapshotScheduler(Protocol):
    """Decides *how* a snapshot write executes: inline or in background.

    Every implementation carries the full surface β€” pending_count/
    await_pending are 0/0 for schedulers with nothing in flight β€” so no
    caller ever needs to sniff the concrete type."""

    async def schedule(
        self,
        write: Coroutine[Any, Any, Snapshot],
        *,
        aggregate_type: str,
        aggregate_id: UUID,
    ) -> Snapshot | None: ...

    @property
    def pending_count(self) -> int: ...

    async def await_pending(self) -> int: ...


class ImmediateScheduler:
    """Awaits the write inline; failures are logged and swallowed so a
    snapshot problem never fails a save whose events already committed."""

    async def schedule(
        self,
        write: Coroutine[Any, Any, Snapshot],
        *,
        aggregate_type: str,
        aggregate_id: UUID,
    ) -> Snapshot | None:
        try:
            return await write
        except Exception as e:
            logger.warning(
                "Failed to create snapshot for %s/%s: %s",
                aggregate_type,
                aggregate_id,
                e,
                exc_info=True,
            )
            return None

    @property
    def pending_count(self) -> int:
        return 0

    async def await_pending(self) -> int:
        return 0


class BackgroundScheduler:
    """Fire-and-forget via BackgroundTaskManager; await_pending() is the
    join point for tests and graceful shutdown."""

    def __init__(self) -> None:
        self._tasks = BackgroundTaskManager()

    async def schedule(
        self,
        write: Coroutine[Any, Any, Snapshot],
        *,
        aggregate_type: str,
        aggregate_id: UUID,
    ) -> Snapshot | None:
        self._tasks.submit(self._guarded(write, aggregate_type, aggregate_id))
        return None

    async def _guarded(
        self,
        write: Coroutine[Any, Any, Snapshot],
        aggregate_type: str,
        aggregate_id: UUID,
    ) -> None:
        try:
            await write
            logger.debug(
                "Background snapshot created for %s/%s", aggregate_type, aggregate_id
            )
        except Exception as e:
            logger.warning(
                "Background snapshot creation failed for %s/%s: %s",
                aggregate_type,
                aggregate_id,
                e,
                exc_info=True,
            )

    @property
    def pending_count(self) -> int:
        return self._tasks.pending_count

    async def await_pending(self) -> int:
        return await self._tasks.await_all()


__all__ = [
    "BackgroundScheduler",
    "EveryNEvents",
    "ImmediateScheduler",
    "Never",
    "SnapshotPolicy",
    "SnapshotScheduler",
    "read_valid_snapshot",
    "take_snapshot",
]

Check eventsource._internal.background_tasks.BackgroundTaskManager for the exact names of submit/pending_count/await_all before writing β€” match whatever it actually exposes.

Run: uv run pytest tests/unit/application/ -q Expected: PASS. Run: uv run mypy src/eventsource/application/ --config-file=pyproject.toml Expected: clean.


git add -A && git commit -m "feat: add snapshotting policy and scheduler collaborators in application ring"

Task 3: Move AggregateRepository; dissolve manager and strategies; delete `aggregates/`

Files:

Interfaces:


git mv src/eventsource/aggregates/repository.py src/eventsource/application/aggregates/repository.py

In the moved file, replace the imports of AggregateSnapshotManager and snapshots.strategies with:


from eventsource.application.aggregates.snapshotting import (
    BackgroundScheduler,
    EveryNEvents,
    ImmediateScheduler,
    Never,
    SnapshotPolicy,
    SnapshotScheduler,
    read_valid_snapshot,
    take_snapshot,
)

and change the Snapshot/SnapshotStore TYPE_CHECKING import to from eventsource.ports.snapshots import Snapshot, SnapshotStore.

Replace the snapshot-wiring block at the end of __init__ (the create_snapshot_strategy/AggregateSnapshotManager section) with:


        # Snapshot configuration (exposed via public properties)
        self._snapshot_store = snapshot_store
        self._snapshot_threshold = snapshot_threshold
        self._snapshot_mode = snapshot_mode

        if (snapshot_policy is not None or snapshot_scheduler is not None) and (
            snapshot_threshold is not None or snapshot_mode != "sync"
        ):
            raise ValueError(
                "Pass either snapshot_mode/snapshot_threshold or "
                "snapshot_policy/snapshot_scheduler, not both."
            )
        if snapshot_policy is not None:
            self._snapshot_policy: SnapshotPolicy = snapshot_policy
        elif snapshot_mode != "manual" and snapshot_threshold is not None:
            self._snapshot_policy = EveryNEvents(snapshot_threshold)
        else:
            self._snapshot_policy = Never()
        if snapshot_scheduler is not None:
            self._snapshot_scheduler: SnapshotScheduler = snapshot_scheduler
        elif snapshot_mode == "background":
            self._snapshot_scheduler = BackgroundScheduler()
        else:
            self._snapshot_scheduler = ImmediateScheduler()

New constructor params (typed): snapshot_policy: SnapshotPolicy | None = None, snapshot_scheduler: SnapshotScheduler | None = None, documented in the docstring alongside the existing mode knobs.

In load(), replace the self._snapshot_manager.load_valid_snapshot(...) call with:


            if self._snapshot_store is not None:
                snapshot = await read_valid_snapshot(
                    self._snapshot_store,
                    aggregate_id,
                    self._aggregate_type,
                    self._aggregate_factory,
                )

In save(), replace the maybe_create_snapshot block with:


                if self._snapshot_store is not None and self._snapshot_policy.should_snapshot(
                    aggregate, len(uncommitted_events)
                ):
                    with self._tracer.span(
                        "eventsource.repository.snapshot",
                        {
                            ATTR_AGGREGATE_ID: str(aggregate.aggregate_id),
                            ATTR_AGGREGATE_TYPE: self._aggregate_type,
                            ATTR_VERSION: aggregate.version,
                        },
                    ):
                        await self._snapshot_scheduler.schedule(
                            take_snapshot(aggregate, self._aggregate_type, self._snapshot_store),
                            aggregate_type=self._aggregate_type,
                            aggregate_id=aggregate.aggregate_id,
                        )

In create_snapshot(), replace the manager guard/delegation: guard becomes if self._snapshot_store is None: raise RuntimeError(...) (same message), body becomes return await take_snapshot(aggregate, self._aggregate_type, self._snapshot_store) inside the existing span. await_pending_snapshots() returns await self._snapshot_scheduler.await_pending(); pending_snapshot_count returns self._snapshot_scheduler.pending_count (no None guards needed β€” schedulers always exist).

Note: the eventsource.snapshot_manager. span names disappear; repository spans (eventsource.repository.) are the surviving trace surface. tests/unit/application/aggregates/test_repository_tracing.py may assert on manager span names β€” update those assertions to the repository span names; this is the one sanctioned assertion change, flag it in the commit message.


git rm src/eventsource/aggregates/__init__.py src/eventsource/aggregates/snapshot_manager.py src/eventsource/snapshots/strategies.py
git mv src/eventsource/aggregates/README.md src/eventsource/application/aggregates/README.md

Update the README's paths/examples to the new module locations and remove manager/strategy references. Add AggregateRepository, TAggregate to application/aggregates/__init__.py imports and __all__. Update src/eventsource/__init__.py: from eventsource.application.aggregates.repository import AggregateRepository (public __all__ unchanged). Update multitenancy/repository.py import. Verify:


grep -rn "eventsource.aggregates\|snapshot_manager\|snapshots.strategies\|SnapshotStrategy\|create_snapshot_strategy" src/ --include="*.py"

Expected: no matches.


git mv tests/unit/aggregates/test_repository_snapshot.py tests/unit/application/aggregates/
git mv tests/unit/aggregates/test_repository_tracing.py tests/unit/application/aggregates/
git mv tests/unit/aggregates/test_aggregate_type_inference.py tests/unit/application/aggregates/
git mv tests/unit/test_aggregate_repository.py tests/unit/application/aggregates/test_repository.py
git rm tests/unit/aggregates/__init__.py

test_repository_snapshot.py imports ThresholdSnapshotStrategy (5 sites) and NoSnapshotStrategy (1 site): rewrite those tests against the new surface β€” ThresholdSnapshotStrategy(threshold=N) usages become EveryNEvents(N) passed as snapshot_policy= (or plain snapshot_threshold=N where the test targets the mode-string path), NoSnapshotStrategy() becomes snapshot_mode="manual". Keep every assertion's substance; only the construction changes. Update eventsource.aggregates.repository imports throughout tests and tests/integration/observability/test_tracing_integration.py.

Run: uv run pytest tests/unit/application/ tests/unit/domain/ tests/unit/multitenancy/ tests/unit/test_public_api.py -q Expected: PASS. Run: uv run mypy src/eventsource/ --config-file=pyproject.toml Expected: clean.


git add -A && git commit -m "refactor: dissolve snapshot manager into repository-composed policy and scheduler"

Task 4: Dissolve the `snapshots/` package into ports, exceptions, and adapters

Files:

Interfaces:

Replace src/eventsource/ports/snapshots.py with the full contents of snapshots/interface.py (docstring adjusted: this is the snapshot port owned by the inner rings; contract unchanged β€” SnapshotStore stays an ABC in this slice, contract redesign is out of scope). Keep __all__ = ["Snapshot", "SnapshotStore"].

Append the four snapshot exception classes from snapshots/exceptions.py to src/eventsource/exceptions.py verbatim (keep docstrings), and add them to its __all__. If snapshots/exceptions.py defines SQLiteNotAvailableError, note it actually lives in adapters/sqlite/snapshots.py β€” check before assuming; only the four Snapshot* classes move.


git rm -r src/eventsource/snapshots/
grep -rln "eventsource.snapshots" src/ tests/ --include="*.py"

Re-point each hit:

In src/eventsource/__init__.py, the from eventsource.snapshots import (...) block becomes:


from eventsource.adapters.memory.snapshots import InMemorySnapshotStore
from eventsource.exceptions import (
    SnapshotDeserializationError,
    SnapshotError,
    SnapshotNotFoundError,
    SnapshotSchemaVersionError,
)
from eventsource.ports.snapshots import Snapshot, SnapshotStore

(top-level __all__ unchanged). The circular-import hazard documented in the old snapshots/__init__.py dies with the alias: ports.snapshots no longer imports from snapshots/, so no lazy __getattr__ is needed anywhere.

Inspect tests/unit/ports/ and tests/unit/adapters/ layouts, then move: test_snapshot.py + test_snapshot_store_interface.py β†’ tests/unit/ports/; test_in_memory_snapshot_store.py, test_postgresql_snapshot_store.py, test_sqlite_snapshot_store.py, test_snapshot_store_tracing.py β†’ tests/unit/adapters/ (mirroring existing adapter test naming); test_snapshot_exceptions.py β†’ tests/unit/test_exceptions_snapshots.py or merge into an existing exceptions test module if one exists. Delete tests/unit/snapshots/ including test_snapshots_module.py tests that only assert the transition package's lazy-export mechanics; port over any residual value (e.g. public-name coverage) into tests/unit/test_public_api.py if not already covered there.

Run: uv run pytest tests/unit/ports/ tests/unit/adapters/ tests/unit/application/ tests/unit/test_public_api.py tests/unit/bench/ -q Expected: PASS. Run: uv run mypy src/eventsource/ --config-file=pyproject.toml Expected: clean.


git add -A && git commit -m "refactor: dissolve snapshots package into ports, exceptions, and adapter imports"

Task 5: Remove 0.8.0-scheduled deprecation shims

Files:

Interfaces:

Remove the code blocks listed above. For bus/memory.py, first read publish() and the class body: if _published_events is written but now never read, remove the list, the lock, and the append. Keep warnings imports only if still used elsewhere in each file.


grep -rn "published_events\|clear_published_events\|record_reconnection\|record_rebalance" tests/ --include="*.py"

Decision rule: a test whose purpose is "the deprecated API warns/works" is deleted; a test using the deprecated API as scaffolding keeps its real assertions and switches to RecordingEventBus (import from eventsource.testing; read its class to get construction right).

Run: uv run pytest tests/unit/bus/ tests/unit/test_kafka_event_bus.py tests/unit/repositories/ tests/unit/serialization/ -q Expected: PASS. Run: uv run mypy src/eventsource/ --config-file=pyproject.toml Expected: clean.


git add -A && git commit -m "refactor: remove deprecation shims scheduled for 0.8.0"

Task 6: Property-based tests (hypothesis)

Files:

Interfaces:

tests/unit/application/aggregates/test_snapshotting_properties.py:


"""Property-based tests for snapshotting collaborators."""

from datetime import UTC, datetime
from types import SimpleNamespace
from uuid import uuid4

import pytest
from hypothesis import given
from hypothesis import strategies as st

from eventsource.adapters.memory.snapshots import InMemorySnapshotStore
from eventsource.application.aggregates.snapshotting import (
    EveryNEvents,
    Never,
    read_valid_snapshot,
)
from eventsource.ports.snapshots import Snapshot


def fake_aggregate(version: int):
    """Policies only read .version β€” a stub keeps these tests pure."""
    return SimpleNamespace(version=version, aggregate_id=uuid4())


@given(version=st.integers(min_value=0, max_value=10_000), n=st.integers(min_value=1, max_value=500))
def test_every_n_events_matches_boundary_predicate(version: int, n: int):
    expected = version > 0 and version % n == 0
    assert EveryNEvents(n).should_snapshot(fake_aggregate(version), 1) is expected


@given(version=st.integers(min_value=0, max_value=10_000), since=st.integers(min_value=0, max_value=10_000))
def test_never_is_never(version: int, since: int):
    assert Never().should_snapshot(fake_aggregate(version), since) is False


@given(n=st.integers(max_value=0))
def test_every_n_events_rejects_nonpositive(n: int):
    with pytest.raises(ValueError):
        EveryNEvents(n)


class VersionedFactory:
    schema_version = 3


@given(stored_schema=st.integers(min_value=1, max_value=10))
@pytest.mark.asyncio
async def test_read_valid_snapshot_iff_schema_matches(stored_schema: int):
    store = InMemorySnapshotStore()
    aid = uuid4()
    await store.save_snapshot(Snapshot(
        aggregate_id=aid, aggregate_type="Thing", version=7,
        state={"x": 1}, schema_version=stored_schema, created_at=datetime.now(UTC),
    ))
    result = await read_valid_snapshot(store, aid, "Thing", VersionedFactory)  # type: ignore[arg-type]
    if stored_schema == VersionedFactory.schema_version:
        assert result is not None and result.schema_version == stored_schema
    else:
        assert result is None

NOTE β€” hypothesis + async: this repo hit hypothesis/async interaction issues before (see MEMORY: event-bus contract work). Check how tests/unit/bus/test_serialization_properties.py and tests/unit/multitenancy/test_context_properties.py drive async code under @given and copy that exact pattern (they may run coroutines via asyncio.run inside a sync test instead of pytest.mark.asyncio). Match the house style; do not invent a new one.

tests/unit/domain/test_aggregate_memento_properties.py β€” define a small DeclarativeAggregate with a pydantic state model having name: str, count: int, tags: list[str]; hypothesis-generate state values; drive the aggregate to that state via an event or by constructing state directly, then:


@given(name=st.text(max_size=50), count=st.integers(), tags=st.lists(st.text(max_size=10), max_size=5))
def test_serialize_restore_round_trip(name: str, count: int, tags: list[str]):
    agg = ThingAggregate(uuid4())
    agg._state = ThingState(name=name, count=count, tags=tags)  # use the real state-setting path found in domain/aggregate.py
    agg._version = 7
    dumped = agg._serialize_state()
    restored = ThingAggregate(agg.aggregate_id)
    restored._restore_from_snapshot(dumped, 7)
    assert restored.state == agg.state
    assert restored.version == 7

Read domain/aggregate.py first for the real attribute names (_state/_version are guesses β€” use whatever _restore_from_snapshot actually sets and the public accessors actually read; if state can't be assigned directly, apply a single event carrying the generated values instead).

Run: uv run pytest tests/unit/application/aggregates/test_snapshotting_properties.py tests/unit/domain/test_aggregate_memento_properties.py -q Expected: PASS.


git add -A && git commit -m "test: property-based coverage for snapshot policy, schema validation, and memento round-trip"

Task 7: Mutation-testing and import-linter configuration

Files:

Interfaces: none (config only).

In [tool.mutmut] only_mutate, the core-rings block already lists src/eventsource/domain, src/eventsource/ports, src/eventsource/adapters. Add:


    "src/eventsource/application",

In pytest_add_cli_args_test_selection, add:


    "tests/unit/application/",
    "tests/unit/domain/",
    "tests/unit/ports/",

(dedupe if already present).

Read the full [tool.importlinter] section first. Then:

  1. Any contract naming a deleted module (eventsource.aggregates., eventsource.snapshots.) is re-pointed to the new location (eventsource.domain.aggregate, eventsource.application.aggregates.*, eventsource.ports.snapshots) β€” e.g. the "Tier 0 must not import sqlalchemy" contract's eventsource.aggregates.base entry becomes eventsource.domain.aggregate.
  2. Add a layers contract for the new ring if one doesn't already cover it:

[[tool.importlinter.contracts]]
name = "Application ring must not import adapters"
type = "forbidden"
source_modules = ["eventsource.application"]
forbidden_modules = ["eventsource.adapters", "eventsource.bus", "eventsource.repositories", "eventsource.locks"]

Note eventsource.stores is deliberately NOT forbidden yet β€” the repository still consumes stores.interface.EventStore (transition port, per spec Out of Scope).

Run: uv run lint-imports Expected: all contracts pass. Run: uv run mutmut run --help > /dev/null && python -c "import tomllib; tomllib.load(open('pyproject.toml','rb'))" Expected: exit 0 (config parses; do NOT run a mutation campaign β€” that's an offline orchestrator activity).


git add pyproject.toml && git commit -m "chore: extend mutmut and import-linter coverage to application ring"

Task 8: ADR 0021, ADR-0017 supersession, and documentation sweep

Files:

Interfaces: none (docs only).

docs/adrs/0021-snapshot-policy-scheduler-composition.md, following the house ADR structure visible in ADR-0017 (title, Status, Context, Decision, Rationale, Consequences, Alternatives Considered, References). Content requirements β€” cover exactly these decisions:

In ADR-0017, change only the Status section: keep the existing text and prepend Superseded by ADR 0021. Historical record of the strategy-pattern design it replaced. Add 0021 to docs/adrs/index.md following its format.


grep -rln "snapshot_manager\|AggregateSnapshotManager\|SnapshotStrategy\|create_snapshot_strategy\|eventsource.aggregates\|eventsource.snapshots" docs/ CLAUDE.md .claude/rules/ --include="*.md"

Fix every hit: import paths to new locations, strategy examples to policy/scheduler examples (ThresholdSnapshotStrategy(threshold=100) β†’ snapshot_threshold=100 or snapshot_policy=EveryNEvents(100); BackgroundSnapshotStrategy β†’ snapshot_mode="background" or snapshot_scheduler=BackgroundScheduler()). Update CLAUDE.md's Project Structure block and .claude/rules/architecture.md transition lists as described in Files. Do not touch docs/superpowers/specs/ history or ADR bodies other than 0017's Status.

Run: uv run pytest tests/unit/test_public_api.py -q (public API doc-name assertions) Expected: PASS.


git add -A && git commit -m "docs: adr 0021 snapshot composition, supersede adr 0017, migrate docs to ring layout"

Self-Review Notes