Core Rings Design: Entities, Ports, and Store Adapters

Date: 2026-07-29 Status: Approved (revised after adversarial review; pending implementation plan) Sub-project: 1 of 3 in the Clean Architecture redesign

Context

eventsource-py has no external users yet, which makes this the cheapest possible moment for a full store-contract redesign. The trigger was a capability mismatch: EventStore requires global-ordering methods (read_all, get_global_position) that wide-column, document, and log-structured backends cannot honestly provide. The interface already admits this inconsistently β€” read_all has a non-abstract default that raises NotImplementedError while get_global_position is @abstractmethod, and the read_stream default fabricates global_position=0.

Decisions made during brainstorming:

The redesign decomposes into three sub-projects, each with its own spec, plan, and implementation cycle:

  1. Core rings (this spec): the entities ring (domain/) + boundary ports (ports/), store contract, memory/sqlite/postgresql adapters, conformance restructure.
  2. Application layer: subscriptions, projections, migration re-architected as use cases consuming ports; catch-up consumes GlobalEventFeed.
  3. Context packaging: repositories, bus, locks, multitenancy, GDPR folded into the adapter structure; import-linter ring contracts locked down.

.claude/rules/architecture.md already encodes the target rules and governs all new and modified code during the transition.

ADR Impact

Per .claude/rules/definition-of-done.md, dispositions for every related ADR:

ADR Disposition
0001 async-first design Stands. All ports are async; the sync test faΓ§ade is test-scaffolding, not public API.
0007 event-bus delivery semantics Stands. Bus contract untouched; ports/bus.py is packaging only.
0008 mutation-testing tools Stands. This spec's mutation targets use mutmut + cosmic-ray as decided.
0009 postgresql advisory locks Stands. Locks untouched until sub-project 3.
0009 multi-instance subscription coordination Stands. Sub-project 2 concern; contract here preserves what it needs (resumable feed).
0010 uniform event bus contract Stands.
0011 handler error isolation Stands.
0012 event-type auto-derivation Stands.
0013 handler registry composition Stands.
0014 live-migration cutover semantics Amended by ADR 0019. Cutover lag criteria are defined by int position deltas across stores; opaque positions abolish cross-store position arithmetic. Sub-project 2 re-expresses lag (see Observability below); ADR 0014's Status gains an "Amended by 0019" pointer.
0015 optional-dependency extras Stands. Adapters keep per-backend extras and *_AVAILABLE flags.
0016 optional tracing no-op Stands.
0017 snapshot strategy pattern Stands. Snapshot port semantics unchanged; it relocates to ports/snapshots.py.
0018 tenant isolation model Stands. Tenancy remains a filter (read options carry tenant_id), not a stream-identity component β€” same model.

The store-contract redesign itself is architecturally significant and gets ADR 0019: clean-architecture store ports and opaque positions (docs/adrs/0019-clean-architecture-store-ports.md), written alongside this spec.

Package Architecture

Target layout (sub-project 1 builds domain/, ports/, and the three store adapters; later sub-projects fill in the rest):


src/eventsource/
  domain/            # DomainEvent, EventRegistry, domain VOs (StreamId, TenantId),
                     #   domain exceptions. Pure: stdlib + pydantic only.
  ports/             # Boundary ports + port-level VOs. Depends on domain only.
    positions.py     #   Position, ExpectedVersion
    envelopes.py     #   EventEnvelope, AppendResult, read-option VOs
    store.py         #   EventAppender, StreamReader, EventLookup,
                     #     GlobalEventFeed, CategoryQuery
    snapshots.py     #   SnapshotStore port + Snapshot VO
    repositories.py  #   Checkpoint/DLQ/Outbox ports (sub-project 3 moves impls)
    bus.py           #   Publisher/Subscriber ports, EventPublisher
  application/       # (sub-project 2) aggregates, projections, subscriptions, migration
  adapters/
    _sql/            # Shared SQL helpers: dialect machinery, int-backed Position codec
    memory/          # store.py, snapshots.py β€” all store ports, dict-backed
    sqlite/          # store.py, snapshots.py
    postgresql/      # store.py, snapshots.py
    redis/ kafka/ rabbitmq/   # (sub-project 3)
  testing/           # Conformance suites, one per port

Properties:

Compatibility Layer (transition)

The old stores/ and snapshots/ module paths keep working until sub-project 2 retypes the application layer β€” but not as re-export shims: the old and new surfaces differ in names and signatures, so re-exports cannot bridge them. They become legacy wrapper classes with their own tests, marked # TRANSITION and deleted at the end of sub-project 2:

Versioning Convention (explicit decision)

Stream versions remain a 1-based event count: an absent stream has version 0; after N appended events the version is N. This matches the current contract (get_stream_version β†’ "0 if aggregate doesn't exist"), the SQL schema's 1-based version column, and the aggregate repository's expectations. Nothing rebases. ExpectedVersion.exact(n) means "the stream currently has exactly n events"; EventEnvelope.stream_version is the version the stream reached with that event (the first event of a stream carries stream_version=1).

Value Objects

All frozen (pydantic frozen models or frozen dataclasses). Domain-owned concepts live in domain/; port payloads live in ports/.

Position (`ports/positions.py`)

The opaque global-feed token, produced only by GlobalEventFeed implementers. Guarantees:

ExpectedVersion (`ports/positions.py`)

Per-stream concurrency stays integer-based (plain int in signatures). The VO has four constructors matching the four supported modes today: ExpectedVersion.any(), ExpectedVersion.no_stream(), ExpectedVersion.stream_exists(), ExpectedVersion.exact(n). All four are implemented by all three adapters (the current stores implement all four; none is dropped). append checks it and raises OptimisticLockError on mismatch.

StreamId (`domain/`)

Replaces the stringly-typed "{aggregate_id}:{AggregateType}" convention: StreamId(aggregate_id: UUID, category: str), rendering to the wire format on demand. category is validated against [A-Za-z0-9_.-]+ in the constructor (no : β€” the wire-format delimiter). category is today's aggregate_type; CategoryQuery reads by it.

EventEnvelope (`ports/envelopes.py`)

Today's StoredEvent, renamed: the domain event plus storage metadata β€” stream_id: StreamId, stream_version: int (1-based, see Versioning), position: Position | None, stored_at: datetime. position is None when the producing adapter implements no global feed; this replaces the current fabricated global_position=0.

AppendResult (`ports/envelopes.py`)

Retyped and slimmed: AppendResult(stream: StreamId, new_version: int, position: Position | None). The current success/conflict flags and conflicted() constructor are dropped β€” conflicts raise OptimisticLockError, so a returned result always means success and the flags are dead weight. position gets the same | None honesty as the envelope.

Read-option VOs (`ports/envelopes.py`)

One options VO per read port; each port only accepts options it honors. Enumerated fields (all optional):

Tenant scoping (TenantId, a domain VO) appears in read options, not in StreamId: multitenancy is a filter, not an identity component (ADR 0018).

Store Ports (`ports/store.py`)

Five small protocols, independently implementable. No inheritance between adapters and ports β€” adapters satisfy them structurally; conformance suites are the compliance check, not a base class.

EventAppender β€” the write side


async def append(self, stream: StreamId, events: Sequence[DomainEvent],
                 expected: ExpectedVersion) -> AppendResult

Atomic per-stream append with optimistic concurrency. The one port every adapter must implement β€” it is the definition of being an event store. Contract details:

StreamReader β€” rehydration


def read_stream(self, stream: StreamId,
                options: StreamReadOptions | None = None) -> AsyncIterator[EventEnvelope]
async def get_stream_version(self, stream: StreamId) -> int   # 0 if absent

The get_events / read_stream duplication collapses into the streaming form; an eager collect() helper covers the list use-case.

EventLookup β€” idempotency probe


async def event_exists(self, event_id: UUID) -> bool

Kept as its own tiny port (not dropped: migration/router.py, migration/dual_write.py, and sync/adapter.py consume it in production). Backed by the event_id unique index on SQL; optional for backends that cannot index by event id.

GlobalEventFeed β€” the catch-up side


def read_all(self, from_position: Position | None = None,
             options: FeedReadOptions | None = None) -> AsyncIterator[EventEnvelope]
async def current_position(self) -> Position | None

from_position is a first-class argument because resumption is the point of this port. Resumption is exclusive: iteration starts strictly after from_position (matches the existing global_position > :from behavior in both SQL stores). from_position=None reads from the beginning. current_position() returns None when no resumable position exists β€” an empty store, or a backend that cannot mint a token before its first event (Mongo change streams); consumers treat None uniformly as "start from the beginning". Adapters that cannot provide a total order do not implement this protocol; the type system then prevents wiring them into catch-up subscriptions.

Delivery guarantee (no-skip): a feed must not permanently skip a committed event when resumed from any position the feed itself produced. This is a real constraint, not a truism: PostgreSQL sequences commit out of order, so a naive WHERE global_position > :from can race past a still-uncommitted lower position and lose it forever. Per adapter: memory and sqlite are trivially safe (serialized writers); the postgresql adapter must bound feed reads to a safe horizon (e.g. pg_snapshot_xmin(pg_current_snapshot())-gated reads) β€” this is new, scoped work in sub-project 1, and the one place porting is more than re-homing. The guarantee is what makes exclusive resumption sound.

CategoryQuery β€” category-indexed reads


def read_category(self, category: str,
                  options: CategoryReadOptions | None = None) -> AsyncIterator[EventEnvelope]

This is today's get_events_by_type re-homed under its true key: the current method filters by aggregate_type (= StreamId.category), ordered by timestamp, and its production consumers (migration router, dual-writer, sync adapter) all pass aggregate types. There is no per-event-type port; if a per-event-type index is ever wanted it is a new capability, designed then.

Composition

FullEventStore β€” a small Protocol composing all five ports β€” exists as a convenience annotation for SQL-grade adapters. Consumers still type-hint the narrowest port they use, per .claude/rules/architecture.md. EventPublisher moves to ports/bus.py.

Adapters

Porting is re-homing plus retyping (the one exception: the postgres safe-horizon feed, above). Per adapter:

memory, sqlite, and postgresql implement all five store ports plus snapshots. NotImplementedError is banned: an unsupported capability is an unimplemented port.

Errors

Exceptions stay centralized in domain/exceptions.py (re-exported at top level as today). New: DuplicateEventError, PositionDecodeError, PositionForeignError. Housing Position's exceptions in domain/ is a deliberate, recorded exception to the "VOs live with their owning ring" rule β€” centralized exception discovery wins. Each port docstring enumerates exactly which exceptions its methods may raise; adapters wrap internal/driver errors so only declared types escape, and conformance suites assert this on induced error paths (duplicate ids, version conflicts, malformed positions, foreign positions β€” not on the happy path, where the assertion would be vacuous).

Observability (explicit consequence)

Opaque positions abolish cross-store position arithmetic. Two current consumers break by design: migration/sync_lag_tracker.py (source-minus-target position lag) and checkpoint LagMetrics (position-delta lag). Position-delta lag is abolished; sub-project 2 must re-express lag in wall-clock terms (stored_at deltas, available on every envelope) and/or an optional count-behind capability designed then. This contract deliberately does not smuggle in a numeric-distance method to keep those metrics alive β€” that would reintroduce the int assumption everywhere. Recorded in ADR 0019 and in ADR 0014's amendment.

Testing

Conformance suites (`testing/`)

One suite per port: AppenderConformance, StreamReaderConformance, EventLookupConformance, GlobalFeedConformance, CategoryQueryConformance, SnapshotConformance. An adapter's test module inherits exactly the suites for the ports it implements. A test-only partitioned in-memory store (no GlobalEventFeed) validates the feed-less path, including position=None envelopes. New cases beyond the ported ones: tenant filtering on FeedReadOptions/CategoryReadOptions (a mutant deleting the tenant WHERE clause must die), duplicate-append raising DuplicateEventError, exclusive resumption, and β€” postgres integration only β€” a concurrent-writer no-skip test exercising the safe horizon.

Property-based tests (hypothesis, already a dev dependency)

Property suites live inside the conformance classes so every future adapter inherits them.

  1. Position laws: serialization round-trip over arbitrary payloads; ordering laws within a store; foreign-store ordering comparisons always raise while __eq__ returns False; from_str fuzzing with garbage strings raises PositionDecodeError.
  2. StreamId round-trip: render/parse round-trip; category validator fuzzing (the :-in-category corruption case is why the validator exists).
  3. Stateful model-based conformance: a hypothesis RuleBasedStateMachine drives append/read/feed operations against an adapter with a dict model as oracle β€” stream reads return exactly what was appended, in order; feed positions strictly increase; get_stream_version equals the count of appended events; ExpectedVersion.exact conflicts iff the model says so. Runs against memory in unit tests, sqlite in integration. The machine drives a new port-shaped sync faΓ§ade (scoped task β€” the existing SyncEventStoreAdapter wraps the old ABC, not the ports) because hypothesis + async interact badly.
  4. Envelope/serialization round-trip: arbitrary event payloads through the JSON encoder and back.

Mutation testing (mutmut + cosmic-ray, per ADR 0008)

The gate runs on domain/, ports/, and adapter core logic. Priority targets:

Excluded from mutation: the legacy wrapper classes and re-export modules.

Regression

The existing unit and integration suites keep passing against the legacy wrappers for the whole of sub-project 1; the wrappers get their own translation tests (sentinel mapping, envelope conversion, exception mapping, legacy int position decoding).

Out of Scope (deferred, explicitly)