Core Rings (Clean Architecture Sub-project 1) 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: Build the entities ring (domain/) and boundary ports (ports/) with opaque positions and five segregated store ports, port the memory/sqlite/postgresql backends as adapters, and keep the entire existing suite green through a legacy compatibility layer.
Architecture: Clean Architecture rings per docs/adrs/0019-clean-architecture-store-ports.md and spec docs/superpowers/specs/2026-07-29-core-rings-design.md. Ports are structural Protocols; adapters satisfy them without inheritance; conformance suites (including hypothesis property suites) are the compliance check. Old stores/ surface survives via a LegacyStoreAdapter wrapper until sub-project 2.
Tech Stack: Python 3.11+, pydantic v2, sqlalchemy async (aiosqlite/asyncpg), pytest + pytest-asyncio, hypothesis, mutmut + cosmic-ray.
Global Constraints
domain/andports/import only stdlib + pydantic (+ each other, inward only). No sqlalchemy, no driver imports, no imports fromadapters/,stores/,repositories/.- Migration SQL files under
src/eventsource/migrations/are untouched. Same schema, same queries (exception: the postgres feed query gains a safe-horizon predicate using thexminsystem column β no DDL). - Stream versions are 1-based event counts; absent stream = version 0. No Β±1 translation anywhere.
NotImplementedErrornever appears in an adapter. Unsupported capability = unimplemented port.- Feed resumption is exclusive (
> from_position); the feed must never permanently skip a committed event (no-skip guarantee). - Existing unit + integration suites must pass unmodified at every task boundary from Task 11 on; before that, they pass because nothing they import has changed.
- All code passes
uv run ruff check,uv run ruff format --check,uv run mypy src/eventsource/ --config-file=pyproject.toml(strict). - Commits follow
.claude/rules/commits.md(type: lowercase description). - Run only targeted tests inside tasks (
uv run pytest); the orchestrator runs-v make checkat the end. - New public names export from
eventsource/__init__.pywith__all__entries; the canonicalExpectedVersionat top level is the new VO (legacy int-constants class stays reachable only aseventsource.stores.interface.ExpectedVersion).
Task 1: StreamId value object (`domain/`)
Files:
- Create:
src/eventsource/domain/__init__.py - Create:
src/eventsource/domain/stream_id.py - Test:
tests/unit/domain/test_stream_id.py(create dir with__init__.pyif the suite convention requires none, matchtests/unit/existing style)
Interfaces:
- Produces:
StreamId(aggregate_id: UUID, category: str)frozen;StreamId.render() -> str("{aggregate_id}:{category}");StreamId.parse(raw: str) -> StreamId;CATEGORY_PATTERN = re.compile(r"^[A-Za-z0-9_.-]+$"); invalid category raisesValueError. - [ ] Step 1: Write the failing tests
# tests/unit/domain/test_stream_id.py
import re
from uuid import uuid4
import pytest
from hypothesis import given
from hypothesis import strategies as st
from eventsource.domain import StreamId
CATEGORY_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_.-"
class TestStreamId:
def test_render_matches_legacy_wire_format(self) -> None:
aid = uuid4()
assert StreamId(aggregate_id=aid, category="Order").render() == f"{aid}:Order"
def test_parse_round_trip(self) -> None:
sid = StreamId(aggregate_id=uuid4(), category="Order.v2")
assert StreamId.parse(sid.render()) == sid
def test_category_with_colon_rejected(self) -> None:
with pytest.raises(ValueError):
StreamId(aggregate_id=uuid4(), category="Order:evil")
def test_empty_category_rejected(self) -> None:
with pytest.raises(ValueError):
StreamId(aggregate_id=uuid4(), category="")
def test_frozen(self) -> None:
sid = StreamId(aggregate_id=uuid4(), category="Order")
with pytest.raises(Exception):
sid.category = "Other" # type: ignore[misc]
@given(category=st.text(alphabet=CATEGORY_ALPHABET, min_size=1, max_size=64))
def test_valid_categories_round_trip(self, category: str) -> None:
sid = StreamId(aggregate_id=uuid4(), category=category)
assert StreamId.parse(sid.render()) == sid
@given(category=st.text(min_size=1, max_size=64))
def test_fuzzed_categories_never_corrupt_wire_format(self, category: str) -> None:
try:
sid = StreamId(aggregate_id=uuid4(), category=category)
except ValueError:
return # rejected is fine; corrupted is not
assert StreamId.parse(sid.render()) == sid
- [ ] Step 2: Run tests, verify failure
Run: uv run pytest tests/unit/domain/test_stream_id.py -v Expected: FAIL / collection error β eventsource.domain does not exist.
- [ ] Step 3: Implement
# src/eventsource/domain/stream_id.py
"""Stream identity value object."""
import re
from dataclasses import dataclass
from uuid import UUID
CATEGORY_PATTERN = re.compile(r"^[A-Za-z0-9_.-]+$")
@dataclass(frozen=True, slots=True)
class StreamId:
"""Identity of an event stream: aggregate id + category.
``category`` is today's aggregate type. The rendered wire format is
``"{aggregate_id}:{category}"`` β the delimiter is why ``:`` is banned
from categories.
"""
aggregate_id: UUID
category: str
def __post_init__(self) -> None:
if not CATEGORY_PATTERN.match(self.category):
raise ValueError(
f"invalid stream category {self.category!r}: "
"must match [A-Za-z0-9_.-]+"
)
def render(self) -> str:
return f"{self.aggregate_id}:{self.category}"
@classmethod
def parse(cls, raw: str) -> "StreamId":
aggregate_id, sep, category = raw.partition(":")
if not sep:
raise ValueError(f"not a stream id: {raw!r}")
return cls(aggregate_id=UUID(aggregate_id), category=category)
# src/eventsource/domain/__init__.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.stream_id import CATEGORY_PATTERN, StreamId
__all__ = ["CATEGORY_PATTERN", "StreamId"]
- [ ] Step 4: Run tests, verify pass
Run: uv run pytest tests/unit/domain/test_stream_id.py -v Expected: PASS (all).
- [ ] Step 5: Commit
git add src/eventsource/domain tests/unit/domain
git commit -m "feat: add streamid value object in domain ring"
Task 2: Position value object and exceptions (`ports/positions.py`)
Files:
- Create:
src/eventsource/ports/__init__.py(exports grow over Tasks 2-5) - Create:
src/eventsource/ports/positions.py - Modify:
src/eventsource/exceptions.py(append three exceptions) - Test:
tests/unit/ports/test_position.py
Interfaces:
- Produces:
Position(store_id: str, key: tuple[int | str, ...])frozen; totally ordered within astore_id;to_str() -> str;Position.from_str(raw: str) -> Position.- Ordering across store_ids raises
PositionForeignError;__eq__across store_ids returnsFalse(never raises). PositionDecodeError(EventSourceError),PositionForeignError(EventSourceError),DuplicateEventError(EventSourceError)ineventsource.exceptions(check the actual base class name inexceptions.pyβ use the same base every other exception uses).- Serialization format: compact JSON
{"s": store_id, "k": [β internal detail, but the tests pin round-trip, not the format.]} - [ ] Step 1: Write the failing tests
# tests/unit/ports/test_position.py
import pytest
from hypothesis import given
from hypothesis import strategies as st
from eventsource.exceptions import PositionDecodeError, PositionForeignError
from eventsource.ports import Position
keys = st.lists(
st.one_of(st.integers(min_value=0, max_value=2**62), st.text(max_size=32)),
min_size=1,
max_size=3,
).map(tuple)
class TestPositionOrdering:
def test_same_store_orders_by_key(self) -> None:
assert Position("pg:a", (1,)) < Position("pg:a", (2,))
def test_foreign_store_ordering_raises(self) -> None:
with pytest.raises(PositionForeignError):
_ = Position("pg:a", (1,)) < Position("pg:b", (1,))
def test_foreign_store_equality_is_false_not_error(self) -> None:
assert Position("pg:a", (1,)) != Position("pg:b", (1,))
def test_equality_with_none_and_other_types(self) -> None:
assert Position("pg:a", (1,)) != None # noqa: E711
assert Position("pg:a", (1,)) != 1
assert Position("pg:a", (1,)) in {Position("pg:a", (1,))}
@given(a=keys, b=keys, c=keys)
def test_ordering_laws_within_store(self, a, b, c) -> None:
pa, pb, pc = (Position("s", k) for k in (a, b, c))
assert (pa < pb) == (not (pb < pa or pa == pb)) # trichotomy-ish
if pa < pb and pb < pc:
assert pa < pc # transitivity
class TestPositionSerialization:
@given(store_id=st.text(min_size=1, max_size=32), key=keys)
def test_round_trip(self, store_id: str, key) -> None:
p = Position(store_id, key)
assert Position.from_str(p.to_str()) == p
@given(garbage=st.text(max_size=64))
def test_from_str_garbage_raises_decode_error(self, garbage: str) -> None:
try:
p = Position.from_str(garbage)
except PositionDecodeError:
return
# If it decoded, it must round-trip (accidentally-valid JSON is ok)
assert Position.from_str(p.to_str()) == p
def test_bare_int_is_not_valid_here(self) -> None:
# Legacy bare-int checkpoints are decoded by the SQL codec (Task 6),
# never by Position.from_str itself (no store_id to attach).
with pytest.raises(PositionDecodeError):
Position.from_str("12345")
- [ ] Step 2: Run tests, verify failure
Run: uv run pytest tests/unit/ports/test_position.py -v Expected: FAIL β eventsource.ports does not exist.
- [ ] Step 3: Implement
First append to src/eventsource/exceptions.py (match the module's existing base-class and docstring style β read it first):
class DuplicateEventError(EventSourceError):
"""An event with this event_id already exists in the store."""
class PositionDecodeError(EventSourceError):
"""A persisted position string could not be decoded."""
class PositionForeignError(EventSourceError):
"""Positions from different stores were compared for order."""
# src/eventsource/ports/positions.py
"""Position and ExpectedVersion value objects for the store ports."""
import json
from dataclasses import dataclass
from typing import Any
from eventsource.exceptions import PositionDecodeError, PositionForeignError
@dataclass(frozen=True, slots=True)
class Position:
"""Opaque, ordered, serializable global-feed position token.
Totally ordered within one store; ordering across stores raises
PositionForeignError; equality across stores is False. Consumers
compare and persist β never arithmetic.
"""
store_id: str
key: tuple[int | str, ...]
def _check_comparable(self, other: "Position") -> None:
if self.store_id != other.store_id:
raise PositionForeignError(
f"cannot order positions from {self.store_id!r} "
f"and {other.store_id!r}"
)
def __lt__(self, other: object) -> bool:
if not isinstance(other, Position):
return NotImplemented
self._check_comparable(other)
return self.key < other.key
def __le__(self, other: object) -> bool:
if not isinstance(other, Position):
return NotImplemented
self._check_comparable(other)
return self.key <= other.key
def __gt__(self, other: object) -> bool:
if not isinstance(other, Position):
return NotImplemented
self._check_comparable(other)
return self.key > other.key
def __ge__(self, other: object) -> bool:
if not isinstance(other, Position):
return NotImplemented
self._check_comparable(other)
return self.key >= other.key
def to_str(self) -> str:
return json.dumps(
{"s": self.store_id, "k": list(self.key)}, separators=(",", ":")
)
@classmethod
def from_str(cls, raw: str) -> "Position":
try:
data: Any = json.loads(raw)
store_id = data["s"]
key = data["k"]
if not isinstance(store_id, str) or not isinstance(key, list):
raise TypeError
if not all(isinstance(e, (int, str)) and not isinstance(e, bool) for e in key):
raise TypeError
except (json.JSONDecodeError, TypeError, KeyError) as exc:
raise PositionDecodeError(f"not a position: {raw!r}") from exc
return cls(store_id=store_id, key=tuple(key))
Note: @dataclass(frozen=True) generates __eq__ comparing (store_id, key) β foreign stores compare unequal without raising, which is exactly the contract. Do not pass order=True (it would generate raising-free ordering); the explicit dunders above are the point.
# src/eventsource/ports/__init__.py
"""Boundary ports (Clean Architecture output ports). Depends on domain only."""
from eventsource.ports.positions import Position
__all__ = ["Position"]
- [ ] Step 4: Run tests, verify pass
Run: uv run pytest tests/unit/ports/test_position.py -v Expected: PASS.
- [ ] Step 5: Commit
git add src/eventsource/ports src/eventsource/exceptions.py tests/unit/ports
git commit -m "feat: add opaque position value object and port exceptions"
Task 3: ExpectedVersion value object
Files:
- Modify:
src/eventsource/ports/positions.py(append),src/eventsource/ports/__init__.py - Test:
tests/unit/ports/test_expected_version.py
Interfaces:
- Produces:
ExpectedVersionfrozen VO with constructorsany_(),no_stream(),stream_exists(),exact(n: int); readablekind: strin{"any","no_stream","stream_exists","exact"}andversion: int | None(set only forexact).exact(n)requiresn >= 0elseValueError. NB: the constructor isany_(trailing underscore βanyshadows the builtin; adapters and the legacy wrapper must use this exact name). - [ ] Step 1: Write the failing tests
# tests/unit/ports/test_expected_version.py
import pytest
from eventsource.ports import ExpectedVersion
class TestExpectedVersion:
def test_four_modes(self) -> None:
assert ExpectedVersion.any_().kind == "any"
assert ExpectedVersion.no_stream().kind == "no_stream"
assert ExpectedVersion.stream_exists().kind == "stream_exists"
ev = ExpectedVersion.exact(3)
assert (ev.kind, ev.version) == ("exact", 3)
def test_exact_negative_rejected(self) -> None:
with pytest.raises(ValueError):
ExpectedVersion.exact(-1)
def test_equality(self) -> None:
assert ExpectedVersion.exact(2) == ExpectedVersion.exact(2)
assert ExpectedVersion.any_() != ExpectedVersion.no_stream()
def test_frozen(self) -> None:
with pytest.raises(Exception):
ExpectedVersion.any_().kind = "exact" # type: ignore[misc]
- [ ] Step 2: Run, verify failure β
uv run pytest tests/unit/ports/test_expected_version.py -vβ ImportError. - [ ] Step 3: Implement (append to
positions.py; export fromports/__init__.py)
@dataclass(frozen=True, slots=True)
class ExpectedVersion:
"""Optimistic-concurrency expectation for append.
Versions are 1-based event counts; an absent stream has version 0.
``exact(n)`` means "the stream currently has exactly n events".
"""
kind: str
version: int | None = None
@classmethod
def any_(cls) -> "ExpectedVersion":
return cls(kind="any")
@classmethod
def no_stream(cls) -> "ExpectedVersion":
return cls(kind="no_stream")
@classmethod
def stream_exists(cls) -> "ExpectedVersion":
return cls(kind="stream_exists")
@classmethod
def exact(cls, version: int) -> "ExpectedVersion":
if version < 0:
raise ValueError(f"exact version must be >= 0, got {version}")
return cls(kind="exact", version=version)
- [ ] Step 4: Run, verify pass.
- [ ] Step 5: Commit β
git commit -m "feat: add expectedversion value object"
Task 4: Envelope and read-option value objects (`ports/envelopes.py`)
Files:
- Create:
src/eventsource/ports/envelopes.py - Modify:
src/eventsource/ports/__init__.py - Test:
tests/unit/ports/test_envelopes.py
Interfaces:
- Produces (all frozen dataclasses, slots):
ReadDirectionβ reuse by importing the existing enum:from eventsource.stores.interface import ReadDirection? No β that would point ports at an adapter-ring module. DefineReadDirection(Enum): FORWARD, BACKWARDhere; Task 13's wrapper maps the old enum to this one by name.EventEnvelope(event: DomainEvent, stream_id: StreamId, stream_version: int, position: Position | None, stored_at: datetime)AppendResult(stream: StreamId, new_version: int, position: Position | None)StreamReadOptions(direction: ReadDirection = FORWARD, from_version: int | None = None, to_version: int | None = None, limit: int | None = None)FeedReadOptions(tenant_id: UUID | None = None, limit: int | None = None)CategoryReadOptions(tenant_id: UUID | None = None, from_timestamp: datetime | None = None, limit: int | None = None)- Consumes:
StreamId(Task 1),Position(Task 2),DomainEvent(existing,eventsource.events.baseβ import asfrom eventsource.events import DomainEventmatching current internal style). - [ ] Step 1: Write the failing tests
# tests/unit/ports/test_envelopes.py
from datetime import UTC, datetime
from uuid import uuid4
import pytest
from eventsource.domain import StreamId
from eventsource.events import DomainEvent
from eventsource.ports import (
AppendResult,
EventEnvelope,
FeedReadOptions,
Position,
ReadDirection,
StreamReadOptions,
)
class ThingHappened(DomainEvent):
pass
def make_envelope(position: Position | None) -> EventEnvelope:
return EventEnvelope(
event=ThingHappened(aggregate_id=uuid4()),
stream_id=StreamId(aggregate_id=uuid4(), category="Thing"),
stream_version=1,
position=position,
stored_at=datetime.now(UTC),
)
class TestEnvelopes:
def test_position_may_be_none_for_feedless_stores(self) -> None:
assert make_envelope(None).position is None
def test_envelope_frozen(self) -> None:
env = make_envelope(None)
with pytest.raises(Exception):
env.stream_version = 2 # type: ignore[misc]
def test_append_result_has_no_conflict_flags(self) -> None:
result = AppendResult(
stream=StreamId(aggregate_id=uuid4(), category="Thing"),
new_version=1,
position=None,
)
assert not hasattr(result, "success")
assert not hasattr(result, "conflict")
def test_option_defaults(self) -> None:
assert StreamReadOptions().direction is ReadDirection.FORWARD
assert FeedReadOptions().tenant_id is None
- [ ] Step 2: Run, verify failure.
- [ ] Step 3: Implement
envelopes.pyexactly per the Interfaces block above (frozen slotted dataclasses,ReadDirection(Enum)withFORWARD = "forward"/BACKWARD = "backward"), export all names fromports/__init__.py.ThingHappenedin the test relies onDomainEvent's existing defaults β checkeventsource/events/base.pyfor required fields (aggregate_idis required;event_typeauto-derives) and adjust the test event construction to the actual minimal constructor if it differs. - [ ] Step 4: Run, verify pass. Also run
uv run mypy src/eventsource/ports/ --config-file=pyproject.tomlβ clean. - [ ] Step 5: Commit β
git commit -m "feat: add envelope, appendresult and read-option value objects"
Task 5: The five store port protocols (`ports/store.py`) + snapshot/bus port re-homes
Files:
- Create:
src/eventsource/ports/store.py - Create:
src/eventsource/ports/snapshots.py(re-home:from eventsource.snapshots.interface import Snapshot, SnapshotStorere-exported β the snapshot contract is unchanged by the spec, so ports/snapshots.py is an alias module until sub-project 3 physically moves it; add# TRANSITIONmarker) - Create:
src/eventsource/ports/bus.py(re-homeEventPublisherthe same way: re-export fromeventsource.stores.interfacewith# TRANSITION) - Modify:
src/eventsource/ports/__init__.py - Test:
tests/unit/ports/test_store_ports.py
Interfaces:
- Produces (all
typing.Protocol, all methods async or returningAsyncIterator):
class EventAppender(Protocol):
max_append_batch: int | None
async def append(self, stream: StreamId, events: Sequence[DomainEvent],
expected: ExpectedVersion) -> AppendResult: ...
class StreamReader(Protocol):
def read_stream(self, stream: StreamId,
options: StreamReadOptions | None = None) -> AsyncIterator[EventEnvelope]: ...
async def get_stream_version(self, stream: StreamId) -> int: ...
class EventLookup(Protocol):
async def event_exists(self, event_id: UUID) -> bool: ...
class GlobalEventFeed(Protocol):
def read_all(self, from_position: Position | None = None,
options: FeedReadOptions | None = None) -> AsyncIterator[EventEnvelope]: ...
async def current_position(self) -> Position | None: ...
class CategoryQuery(Protocol):
def read_category(self, category: str,
options: CategoryReadOptions | None = None) -> AsyncIterator[EventEnvelope]: ...
class FullEventStore(EventAppender, StreamReader, EventLookup,
GlobalEventFeed, CategoryQuery, Protocol): ...
- Also produces:
async def collect(it: AsyncIterator[EventEnvelope]) -> list[EventEnvelope]helper inports/store.py. - None of the five is
@runtime_checkableinitially β add it only when a consumer needs isinstance (rules file). - [ ] Step 1: Write the failing test β structural conformance is checked by assigning a minimal stub to each protocol-typed variable; mypy is the real gate, the runtime test just imports and exercises
collect:
# tests/unit/ports/test_store_ports.py
import pytest
from eventsource.ports import collect
from eventsource.ports.store import (
CategoryQuery,
EventAppender,
EventLookup,
FullEventStore,
GlobalEventFeed,
StreamReader,
)
async def _agen(items):
for item in items:
yield item
@pytest.mark.asyncio
async def test_collect_drains_iterator() -> None:
assert await collect(_agen([1, 2, 3])) == [1, 2, 3]
def test_ports_are_importable_and_distinct() -> None:
ports = {EventAppender, StreamReader, EventLookup, GlobalEventFeed, CategoryQuery}
assert len(ports) == 5
assert issubclass(FullEventStore, EventAppender)
(Match the project's asyncio test style β check whether existing tests use @pytest.mark.asyncio or asyncio_mode=auto in pyproject, and follow it.)
- [ ] Step 2: Run, verify failure.
- [ ] Step 3: Implement
store.pywith the exact signatures above pluscollect; create the two# TRANSITIONre-home modules; export everything fromports/__init__.py. - [ ] Step 4: Run test +
uv run mypy src/eventsource/ports/β pass, clean. - [ ] Step 5: Verify ring purity β
grep -rn "sqlalchemy\|asyncpg\|aiosqlite" src/eventsource/ports/ src/eventsource/domain/must return nothing (the two TRANSITION re-homes import fromstores.interface/snapshots.interfacewhich are sqlalchemy-free interface modules β verify that withpython -c "import ast, sys; ..."or simplygrep -n "import" src/eventsource/snapshots/interface.py). - [ ] Step 6: Commit β
git commit -m "feat: add five store port protocols"
Task 6: SQL position codec + `_sql` helper package (`adapters/_sql/`)
Files:
- Create:
src/eventsource/adapters/__init__.py(empty docstring module) - Create:
src/eventsource/adapters/_sql/__init__.py - Create:
src/eventsource/adapters/_sql/positions.py - Create:
src/eventsource/adapters/_sql/dialect.pyβ move the full contents ofsrc/eventsource/repositories/_dialect.pyhere; rewritesrc/eventsource/repositories/_dialect.pyas# TRANSITIONre-export (from eventsource.adapters._sql.dialect import * # noqa: F401,F403plus explicit__all__matching the original) - Test:
tests/unit/adapters/test_sql_position_codec.py
Interfaces:
- Produces:
IntPositionCodec(store_id: str)withencode(value: int) -> Position(Position(store_id, (value,))),decode(raw: str) -> Positionaccepting (a)Position.to_stroutput with matching store_id β foreign store_id raisesPositionForeignError; (b) legacy bare-int strings ("12345") βPosition(store_id, (12345,)); anything else raisesPositionDecodeError.value_of(position: Position) -> int(foreign store raisesPositionForeignError; non-int key raisesPositionDecodeError). - Consumes:
Position, exceptions (Task 2). - [ ] Step 1: Failing tests
# tests/unit/adapters/test_sql_position_codec.py
import pytest
from eventsource.adapters._sql.positions import IntPositionCodec
from eventsource.exceptions import PositionDecodeError, PositionForeignError
from eventsource.ports import Position
class TestIntPositionCodec:
def test_encode_decode_round_trip(self) -> None:
codec = IntPositionCodec(store_id="pg:main")
pos = codec.encode(42)
assert codec.decode(pos.to_str()) == pos
assert codec.value_of(pos) == 42
def test_legacy_bare_int_checkpoint_decodes(self) -> None:
codec = IntPositionCodec(store_id="pg:main")
assert codec.decode("12345") == Position("pg:main", (12345,))
def test_foreign_store_decode_raises(self) -> None:
codec = IntPositionCodec(store_id="pg:main")
foreign = Position("sqlite:other", (1,)).to_str()
with pytest.raises(PositionForeignError):
codec.decode(foreign)
def test_garbage_raises_decode_error(self) -> None:
with pytest.raises(PositionDecodeError):
IntPositionCodec(store_id="pg:main").decode("not-a-position")
def test_dialect_reexport_intact(self) -> None:
from eventsource.repositories._dialect import Dialect # old path
from eventsource.adapters._sql.dialect import Dialect as NewDialect
assert Dialect is NewDialect
- [ ] Step 2: Run, verify failure.
- [ ] Step 3: Implement
# src/eventsource/adapters/_sql/positions.py
"""Int-backed position codec shared by the SQL-family adapters."""
from dataclasses import dataclass
from eventsource.exceptions import PositionDecodeError, PositionForeignError
from eventsource.ports import Position
@dataclass(frozen=True, slots=True)
class IntPositionCodec:
store_id: str
def encode(self, value: int) -> Position:
return Position(store_id=self.store_id, key=(value,))
def decode(self, raw: str) -> Position:
if raw.isdigit(): # legacy bare-int checkpoint value
return self.encode(int(raw))
position = Position.from_str(raw)
if position.store_id != self.store_id:
raise PositionForeignError(
f"position belongs to {position.store_id!r}, "
f"this store is {self.store_id!r}"
)
return position
def value_of(self, position: Position) -> int:
if position.store_id != self.store_id:
raise PositionForeignError(
f"position belongs to {position.store_id!r}, "
f"this store is {self.store_id!r}"
)
if len(position.key) != 1 or not isinstance(position.key[0], int):
raise PositionDecodeError(f"not an int-backed position: {position!r}")
return position.key[0]
Move _dialect.py content verbatim (git mv preferred, then create the re-export at the old path).
- [ ] Step 4: Run new tests AND the existing repository tests (
uv run pytest tests/unit/ -k "dialect or checkpoint or dlq or outbox" -v) β all pass (the re-export must be perfectly transparent). - [ ] Step 5: Commit β
git commit -m "feat: add sql position codec and re-home dialect helpers"
Task 7: Memory adapter (`adapters/memory/store.py`)
Files:
- Create:
src/eventsource/adapters/memory/__init__.py,src/eventsource/adapters/memory/store.py - Test:
tests/unit/adapters/test_memory_store.py(direct tests only β conformance suites arrive Task 8/9 and take over)
Interfaces:
- Produces:
MemoryEventStore(store_id: str = "memory")implementing all five ports. Constructor takes optionalevent_registrylike the currentInMemoryEventStore(mirror its signature). Internals:_events: list[EventEnvelope](global order = list order, position = 1-based list index viaIntPositionCodec),_streams: dict[str, list[int]](render()ed StreamId β indexes),_event_ids: set[UUID],asyncio.Lockserializing appends.max_append_batch = None. - Port source:
src/eventsource/stores/in_memory.pyβ reuse its expected-version dispatch logic, retyped. Mapping: - old
append_events(aggregate_id, aggregate_type, events, expected_version:int)βappend(stream, events, expected); sentinel ints βExpectedVersionkinds (-1/ANYβany_,0... check actual constants instores/interface.py:ANY,NO_STREAM,STREAM_EXISTSvalues β map by name, not number). - old
get_eventsβcollect(read_stream(...)) - old
event_existsβevent_exists - old
read_all(options)βread_all(from_position, options)with exclusive resumption - old
get_events_by_type(aggregate_type, ...)βread_category(category, ...) - old
get_global_positionβcurrent_position(Nonewhen empty) - Key contract points the tests below pin: duplicate event_id β
DuplicateEventError(whole batch rejected, atomically); empty batch βValueError; version = 1-based count; conflict βOptimisticLockError(existing exception β reuse it). - [ ] Step 1: Failing tests (representative core; conformance suites deepen coverage next task)
# tests/unit/adapters/test_memory_store.py
from uuid import uuid4
import pytest
from eventsource.adapters.memory import MemoryEventStore
from eventsource.domain import StreamId
from eventsource.events import DomainEvent
from eventsource.exceptions import DuplicateEventError, OptimisticLockError
from eventsource.ports import ExpectedVersion, collect
class ThingHappened(DomainEvent):
pass
def sid() -> StreamId:
return StreamId(aggregate_id=uuid4(), category="Thing")
@pytest.fixture
def store() -> MemoryEventStore:
return MemoryEventStore()
class TestAppend:
async def test_append_returns_one_based_version(self, store) -> None:
stream = sid()
result = await store.append(
stream, [ThingHappened(aggregate_id=stream.aggregate_id)],
ExpectedVersion.no_stream(),
)
assert result.new_version == 1
assert await store.get_stream_version(stream) == 1
async def test_absent_stream_version_zero(self, store) -> None:
assert await store.get_stream_version(sid()) == 0
async def test_exact_conflict_raises(self, store) -> None:
stream = sid()
await store.append(stream, [ThingHappened(aggregate_id=stream.aggregate_id)],
ExpectedVersion.no_stream())
with pytest.raises(OptimisticLockError):
await store.append(stream, [ThingHappened(aggregate_id=stream.aggregate_id)],
ExpectedVersion.exact(0))
async def test_duplicate_event_id_rejected_atomically(self, store) -> None:
stream = sid()
event = ThingHappened(aggregate_id=stream.aggregate_id)
await store.append(stream, [event], ExpectedVersion.no_stream())
fresh = ThingHappened(aggregate_id=stream.aggregate_id)
with pytest.raises(DuplicateEventError):
await store.append(stream, [fresh, event], ExpectedVersion.exact(1))
assert await store.get_stream_version(stream) == 1 # atomic: fresh not written
async def test_empty_batch_rejected(self, store) -> None:
with pytest.raises(ValueError):
await store.append(sid(), [], ExpectedVersion.any_())
class TestFeed:
async def test_exclusive_resumption(self, store) -> None:
stream = sid()
await store.append(stream,
[ThingHappened(aggregate_id=stream.aggregate_id) for _ in range(3)],
ExpectedVersion.no_stream())
first_two = [env async for env in store.read_all()][:2]
resumed = [env async for env in store.read_all(from_position=first_two[-1].position)]
assert len(resumed) == 1
async def test_current_position_none_when_empty(self, store) -> None:
assert await store.current_position() is None
- [ ] Step 2: Run, verify failure.
- [ ] Step 3: Implement
MemoryEventStoreper the Interfaces mapping. The expected-version check, written once here and reused as the reference for both SQL adapters:
def _check_expected(self, current: int, expected: ExpectedVersion, stream: StreamId) -> None:
if expected.kind == "any":
return
if expected.kind == "no_stream" and current != 0:
raise OptimisticLockError(...) # mirror the fields the existing exception carries
if expected.kind == "stream_exists" and current == 0:
raise OptimisticLockError(...)
if expected.kind == "exact" and current != expected.version:
raise OptimisticLockError(...)
(Open src/eventsource/exceptions.py for OptimisticLockError's actual constructor β it carries aggregate/expected/actual fields today; populate them faithfully, aggregate_id=stream.aggregate_id.)
- [ ] Step 4: Run, verify pass. mypy clean on
src/eventsource/adapters/. - [ ] Step 5: Commit β
git commit -m "feat: add memory event store adapter on the new ports"
Task 8: Conformance package β Appender, StreamReader, EventLookup suites
Files:
- Create:
src/eventsource/testing/conformance_ports/__init__.py,appender.py,stream_reader.py,event_lookup.py(testing/conformance.pyβ the legacy EventStore/EventBus suites β stays untouched; the new package sits beside it and replaces it in sub-project 3.) - Test:
tests/unit/adapters/test_memory_conformance.py
Interfaces:
- Produces:
AppenderConformance,StreamReaderConformance,EventLookupConformanceβ ABC test mixins in the style of the existingEventStoreConformanceSuite(readsrc/eventsource/testing/conformance.py:34-56for the fixture convention and copy it: an abstractstorefixture returning the adapter under test). Each suite's cases (write real test methods for every bullet): - Appender: 1-based versions; absent=0 is reader's job but
no_streamappend to fresh stream succeeds; each of the fourExpectedVersionmodes accepted/conflicting per contract;DuplicateEventErroron duplicate id, atomically; empty batchValueError;AppendResult.positionnon-None here (these adapters implement the feed) and strictly increasing across appends. - StreamReader: read returns exactly appended events in order;
from_version/to_version/limit/BACKWARDhonored; envelopes carry correctstream_versionsequence 1..N. - EventLookup: exists after append; not before; unknown UUID False.
- Consumes: everything from Tasks 1-7.
- [ ] Step 1: Write
tests/unit/adapters/test_memory_conformance.pyfirst (the failing consumer):
from collections.abc import AsyncIterator
import pytest
from eventsource.adapters.memory import MemoryEventStore
from eventsource.testing.conformance_ports import (
AppenderConformance,
EventLookupConformance,
StreamReaderConformance,
)
class TestMemoryAppender(AppenderConformance):
@pytest.fixture
async def store(self) -> AsyncIterator[MemoryEventStore]:
yield MemoryEventStore()
class TestMemoryStreamReader(StreamReaderConformance):
@pytest.fixture
async def store(self) -> AsyncIterator[MemoryEventStore]:
yield MemoryEventStore()
class TestMemoryEventLookup(EventLookupConformance):
@pytest.fixture
async def store(self) -> AsyncIterator[MemoryEventStore]:
yield MemoryEventStore()
- [ ] Step 2: Run, verify failure (package missing).
- [ ] Step 3: Implement the three suites. Every case listed in Interfaces gets a real test method β no "etc". Suites define their own tiny
DomainEventsubclass and stream factory (module-level, like the existing conformance module does). Keep suites sqlalchemy-free (they will be part of the Tier 0 surface eventually β import only fromeventsource.ports,eventsource.domain,eventsource.events,eventsource.exceptions, pytest). - [ ] Step 4: Run, verify all conformance cases pass against memory.
- [ ] Step 5: Commit β
git commit -m "test: add appender, streamreader and eventlookup conformance suites"
Task 9: Conformance β GlobalFeed + CategoryQuery suites, feed-less partitioned store
Files:
- Create:
src/eventsource/testing/conformance_ports/feed.py,category.py - Create:
src/eventsource/testing/partitioned_memory.pyβPartitionedMemoryStore: implements Appender/StreamReader/EventLookup/CategoryQuery but not GlobalEventFeed; internally a dict of per-stream lists with no global order; envelopes carryposition=None. ~80 lines, reuses_check_expectedlogic pattern from Task 7 (copy it β do not import from the adapter; testing must not depend on a specific adapter). - Modify:
tests/unit/adapters/test_memory_conformance.py(add feed + category suite subclasses forMemoryEventStore) - Test:
tests/unit/testing/test_partitioned_store.py
Interfaces:
- Produces:
GlobalFeedConformancecases: full read in position order; exclusive resumption (resume from position of event k yields exactly events k+1..N);from_position=None= from start; positions strictly increase;current_position()None when empty / equals last envelope's position otherwise; tenant filter honored whenFeedReadOptions(tenant_id=...)(events for other tenants excluded β constructTenantDomainEvents; readsrc/eventsource/multitenancyfor the event type to use); resumed-from-persisted-string round-trip (Position.from_str(p.to_str())resumes identically).CategoryQueryConformancecases: only the named category returned;from_timestampfilter; tenant filter; stored_at ordering.PartitionedMemoryStoredirect tests: envelopes haveposition=None; it does not exposeread_all/current_positionattributes (assert not hasattr(...)).- [ ] Step 1: Failing consumers first (extend memory conformance module + partitioned store test), Step 2: verify failure, Step 3: implement suites + partitioned store, Step 4: verify pass, Step 5: commit
test: add feed and category conformance suites with feed-less proving store. Same TDD rhythm as Task 8; every case in Interfaces becomes a real method.
Task 10: Hypothesis stateful machine + sync faΓ§ade
Files:
- Create:
src/eventsource/testing/sync_facade.pyβSyncStoreFacade(store, loop_factory=asyncio.new_event_loop): sync wrappersappend,read_stream(returns list),get_stream_version,read_all(returns list),current_position,event_exists, each driving the async store via a private event loop (mirror the pattern insrc/eventsource/sync/adapter.pyβ read it; reuse its loop-management approach, but target the ports, not the old ABC). - Create:
src/eventsource/testing/conformance_ports/stateful.pyβStoreStateMachine(RuleBasedStateMachine)base with an abstractmake_store()hook. - Test:
tests/unit/adapters/test_memory_stateful.py
Interfaces:
- Produces:
StoreStateMachinerules (real code in the plan-executor's implementation, signatures here): append_new_stream(n_events)β appends to a fresh stream withno_stream(); model records list.append_existing(stream_index, n_events)β appends withexact(model_version); model appends.append_stale(stream_index)β appends withexact(model_version - 1)when version β₯ 1; expectsOptimisticLockError; model unchanged.check_stream(stream_index)β invariant: store stream == model list (event ids, order); version == len.check_feed()β invariant: feed event ids == flattened model in feed order; positions strictly increase.- Machine bounds: max 8 streams, max 5 events/step (keep runs fast; hypothesis profile
max_examples=25for CI β set viasettingson the concrete class).
# tests/unit/adapters/test_memory_stateful.py
from hypothesis import settings
from eventsource.adapters.memory import MemoryEventStore
from eventsource.testing.conformance_ports.stateful import StoreStateMachine
from eventsource.testing.sync_facade import SyncStoreFacade
class MemoryStateMachine(StoreStateMachine):
def make_store(self) -> SyncStoreFacade:
return SyncStoreFacade(MemoryEventStore())
TestMemoryStateful = MemoryStateMachine.TestCase
TestMemoryStateful.settings = settings(max_examples=25, deadline=None)
- [ ] Steps: failing test β implement faΓ§ade β implement machine β pass β commit
test: add hypothesis stateful conformance machine with sync facade. Watch for the known gotcha (project memory): pytest-randomly reseeds hypothesis β if flakiness appears, pinderandomize=Truein the settings rather than fighting the seed.
Additionally (same task, spec Testing Β§property 4): tests/unit/serialization/test_event_round_trip_property.py β a hypothesis test generating events with arbitrary payload field values (st.dictionaries of json-safe scalars applied to a test DomainEvent subclass with a payload: dict[str, Any] field), asserting registry-mediated serializeβdeserialize round-trip equality via the existing EventSourceJSONEncoder path (read src/eventsource/serialization/ for the canonical encode/decode entry points and use those, not raw json).
Task 11: SQLite adapter
Files:
- Create:
src/eventsource/adapters/sqlite/__init__.py,src/eventsource/adapters/sqlite/store.py - Test:
tests/unit/adapters/test_sqlite_conformance.py(sqlite tests run without Docker β mirror whichever marker/fixture patterntests/currently uses for the sqlite store; find it withgrep -rn "sqlite" tests/unit tests/integration -land follow it)
Interfaces:
- Produces:
SQLiteEventStoreimplementing all five ports +max_append_batch = None,store_iddefaulting to the database path (f"sqlite:{path}"). Port ofsrc/eventsource/stores/sqlite.py(~same SQL, same tables) with the Task 7 mapping table applied; positions minted viaIntPositionCodec;DuplicateEventErrorraised by catching the unique-violationIntegrityErroronevent_id(sqlite reports it ine.args[0]β match on the constraint, mirroring how the current sqlite store detects version conflicts); optional-dependency guard (AIOSQLITE_AVAILABLE) preserved exactly as the current module does it. - No safe-horizon work: sqlite writers are serialized (single-writer WAL) β trivially no-skip. Add a code comment stating that constraint.
- Conformance test module subclasses ALL suites incl. stateful (sqlite variant) and feed/category.
- [ ] Steps: conformance test module first (fails: module missing) β port the store β all suites pass β
uv run pytest tests/ -k sqlite -v(old suite still green β untouched paths) β commitfeat: add sqlite event store adapter on the new ports.
Task 12: PostgreSQL adapter with safe-horizon feed
Files:
- Create:
src/eventsource/adapters/postgresql/__init__.py,src/eventsource/adapters/postgresql/store.py - Test:
tests/integration/adapters/test_postgresql_conformance.py(markerpostgres, Docker services perdocker-compose.test.ymlβ copy the engine/session fixture pattern from the existing postgres store integration tests,grep -rn "postgres" tests/integration -l) - Test:
tests/integration/adapters/test_postgresql_no_skip.py
Interfaces:
- Produces:
PostgreSQLEventStoreimplementing all five ports;store_iddefaultf"pg:{database}"(derive from the engine URL; must be stable across restarts β never random). Port ofsrc/eventsource/stores/postgresql.pyper the Task 7 mapping.DuplicateEventErrorfrom theevent_idunique violation (distinguish from the(aggregate_id, aggregate_type, version)conflict constraint by constraint name in theIntegrityErrorβ the current module already parses that error forOptimisticLockError; extend the same parsing). - Safe-horizon feed β the one genuinely new query.
read_alluses:
SELECT ... FROM events
WHERE global_position > :from_position
AND xmin::text::bigint < pg_snapshot_xmin(pg_current_snapshot())::text::bigint
ORDER BY global_position ASC
LIMIT :limit
Rationale comment to include verbatim: rows whose inserting transaction is not yet definitely-committed (xmin β₯ snapshot xmin) are deferred to a later poll β the sequence commits out of order, and reading past a still-uncommitted lower position would skip it forever once the reader resumes from higher up. Uses the xmin system column: no DDL, schema untouched. Caveat: epoch comparison is not wraparound-proof in the ancient-xid regime; acceptable for now, revisit if a xid8 column is ever added.
current_position()must apply the same horizon (SELECT max(global_position) FROM events WHERE xmin... < ...), else a checkpoint could be minted beyond the horizon and skip on resume.
No-skip integration test (the mutation-killer for the horizon predicate):
# tests/integration/adapters/test_postgresql_no_skip.py (marker: postgres)
# Two concurrent writers: writer A begins a transaction, inserts (acquiring
# global_position N), and parks pre-commit on an asyncio.Event; writer B then
# inserts and commits (position N+1). Reader reads the feed: must NOT see N+1
# while N is uncommitted (horizon holds it back). Release A, commit; reader
# resumes from its checkpoint: sees N then N+1. Assert no event lost, order
# by position. Drive writer A with a raw asyncpg/sqlalchemy connection held
# open across an explicit begin(); park with anyio/asyncio primitives, and
# put a hard timeout (asyncio.wait_for, 10s) around the whole test.
Write this as a real test β the comment above is the specification of its choreography; every step in it becomes code.
- [ ] Steps: conformance module + no-skip test first (fail) β port store + horizon β
docker compose -f docker-compose.test.yml up -dβuv run pytest tests/integration/adapters -m postgres -vpass β existing postgres suite still green (uv run pytest tests/ -m postgres -v) β commitfeat: add postgresql adapter with safe-horizon global feed.
Task 13: Legacy compatibility wrapper (`stores/legacy.py`)
Files:
- Create:
src/eventsource/stores/legacy.pyβLegacyStoreAdapter(EventStore)(the old ABC) wrapping anyFullEventStore. - Modify:
src/eventsource/stores/__init__.pyβ construct the three legacy store classes as thin subclasses that build the new adapter and wrap it:InMemoryEventStore,SQLiteEventStore,PostgreSQLEventStorekeep their existing constructor signatures and behavior by delegating toLegacyStoreAdapter(MemoryEventStore(...))etc. Only if their existing test suites pass unmodified this way; where a legacy test reaches into implementation internals (e.g. private attributes), keep the original class untouched instead and note it for sub-project 2 β the wrapper is still exercised by the conformance suite below. - Test:
tests/unit/stores/test_legacy_adapter.py
Interfaces:
- Consumes: everything.
- Produces:
LegacyStoreAdaptertranslating per the spec's Compatibility Layer section: append_events(aggregate_id, aggregate_type, events, expected_version:int)βappend(StreamId(aggregate_id, aggregate_type), events, _expected_from_int(expected_version))where_expected_from_intmaps the old class constants by name (ExpectedVersion.ANY β any_(),NO_STREAM β no_stream(),STREAM_EXISTS β stream_exists(),n >= 0 β exact(n)), and reconstructs the oldAppendResultshape (success=True, new_version, global_position=codec.value_of(position) if position else 0, conflict=False); anOptimisticLockErroris re-raised (the old stores raise too β verify againststores/in_memory.pybehavior and mirror it exactly; if any path returnedconflicted()results instead, mirror that path).get_eventsβ collectedread_streamrebuilt intoEventStream(old VO);StoredEventfields fromEventEnvelope(global_position=0whenposition is Noneβ the old fabrication, preserved only inside the legacy surface).event_existsβevent_exists;get_stream_versionβ identity;get_events_by_type(aggregate_type, ...)βread_category;read_all(options)βread_all(from_position=codec.encode(options.from_position) ...)mapping old int options;get_global_positionβcodec.value_of(await current_position())or 0 when None.- Old
ReadDirectionenum values map to new by.name. - The wrapper's own tests pin: every sentinel mapping; envelopeβstoredevent conversion both ways; exception passthrough; int position round-trip through the codec including
get_global_positionon an empty store == 0. - [ ] Steps: failing wrapper tests β implement β pass β run the full existing unit suite
uv run pytest tests/unit -x -q(must be green β this is the task's real gate) β commitfeat: add legacy store adapter preserving the old eventstore surface.
Task 14: Snapshot adapters, top-level exports, gate wiring
Files:
- Create:
src/eventsource/adapters/memory/snapshots.py,adapters/sqlite/snapshots.py,adapters/postgresql/snapshots.pyβ re-home the three snapshot stores (git mvcontents fromsnapshots/in_memory.py,snapshots/sqlite.py,snapshots/postgresql.py; old modules become# TRANSITIONre-exports; contract unchanged, so existing snapshot tests are the gate). - Create:
src/eventsource/testing/conformance_ports/snapshots.pyβSnapshotConformance(save/get-latest/delete round-trip; version filtering; per the unchangedSnapshotStoreinterface β port the relevant cases from any existing snapshot tests into suite form) + wire into the three adapters' conformance test modules. - Modify:
src/eventsource/__init__.pyβ exportStreamId,Position,ExpectedVersion(the VO),EventEnvelope,AppendResult,StreamReadOptions,FeedReadOptions,CategoryReadOptions,ReadDirection(new one), the five protocols,FullEventStore,MemoryEventStore,SQLiteEventStore+PostgreSQLEventStore(adapter classes, under those names only if no collision with legacy exports β otherwise export aseventsource.adapters.sqlite.SQLiteEventStorepath-only and note it),DuplicateEventError,PositionDecodeError,PositionForeignError. Update__all__. Do not remove any existing export. - Modify:
pyproject.tomlβ addsrc/eventsource/domain,src/eventsource/ports,src/eventsource/adaptersto the mutmut/cosmic-ray paths (find the existing tool config blocks and extendpaths_to_mutate/module lists in the same style); excludestores/legacy.pyand all# TRANSITIONre-export modules. - Modify:
CHANGELOG.md(top, unreleased section, matching existing entry style): new ports/VO surface added, old surface preserved via legacy wrapper, feed no-skip guarantee on postgres. - Test:
tests/unit/test_public_api.pyβ if a public-API test exists, extend it; otherwise add one asserting every name above imports fromeventsourceand appears in__all__. - [ ] Steps: failing export test β wire exports β snapshot re-home with existing snapshot tests green β conformance suite added and green for all three adapters β
uv run ruff check src/ tests/ && uv run mypy src/eventsource/ --config-file=pyproject.tomlclean β commitfeat: export core rings surface and wire snapshot adapters.
Final Gate (orchestrator, not a task)
make checkβ full CI parity (lint, mypy, import-linter, bandit/pip-audit, unit suite).docker compose -f docker-compose.test.yml up -d && uv run pytest tests/integration -vβ integration green.- Mutation spot-run on the new modules (
uv run mutmut run --paths-to-mutate src/eventsource/ports/positions.pyor the cosmic-ray equivalent per ADR 0008) β priority targets from the spec: resumption>, horizon predicate,ExpectedVersiondispatch,Position.__lt__, tenantWHERE. - Verify ring purity:
grep -rn "sqlalchemy\|asyncpg\|aiosqlite\|redis\|aiokafka\|aio_pika" src/eventsource/ports src/eventsource/domainβ empty.