Legacy Store Retirement β€” Slice (d): Deletion, Public-API Swap, Docs

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: End the legacy store surface. Port the one legacy feature the adapters lack (outbox_enabled + _write_to_outbox), retire EventStoreConformanceSuite after a case-by-case gap check, rename MemoryEventStore β†’ InMemoryEventStore, delete src/eventsource/stores/ entirely, rewrite the top-level __init__.py store section so eventsource exports exactly one blessed set of store names, and sweep the contracts, ADRs, and docs. After this slice the string eventsource.stores does not appear in any executable file in the repository.

Architecture: The five segregated ports in ports/store.py and the three adapters under adapters/ become the only store surface. The names the legacy ABC owned at top level (InMemoryEventStore, PostgreSQLEventStore, SQLiteEventStore, ExpectedVersion, ReadDirection, AppendResult) rebind to their ports/adapter counterparts in a single edit, and the deliberate dual-export comment block at __init__.py:24-38 β€” which existed only to keep two referents apart β€” is deleted along with the second referent. EventPublisher keeps its home in ports/bus.py; the stores/interface.py re-export dies with the module. ADR 0025 stops being a placeholder and records every behavior delta the four slices made visible.

Tech Stack: Python 3.13, pydantic v2, sqlalchemy 2 (adapters only), asyncpg, aiosqlite, pytest + pytest-asyncio + hypothesis, mypy strict, ruff, import-linter, mutmut.

Spec: docs/superpowers/specs/2026-07-31-legacy-store-retirement-design.md (slice (d): Β§3 testing/conformance.py, Β§4 in full, Β§5.1, Β§5.2, Β§5.3, Β§6 slice (d), Β§7 slice (d), Β§8, Β§9)

Sibling slices: 2026-07-31-store-retirement-a-leaf-consumers.md, -b-subscriptions.md and -c-migration.md have ALL LANDED. Verified against the tree at HEAD: the only remaining importers of eventsource.stores in src/ are __init__.py (5 import statements), testing/conformance.py (1), and stores/'s own internals; bench/ and examples/ have none; two adapter module docstrings mention the legacy module by name in prose. Every runtime consumer β€” aggregates, sync, harness, subscriptions, migration, bench β€” is already on the ports. Do not redo any of it.

Global Constraints

`` Co-Authored-By: Claude Fable 5 ``

Deletion ordering: why the rename, the `__init__` swap, and the `stores/` deletion are one task

Three constraints interlock, and no ordering of them produces an intermediate state that is both green and shim-free.

  1. The rename cannot precede the deletion. InMemoryEventStore is a live top-level export today, bound to stores.in_memory.InMemoryEventStore. Renaming adapters.memory.MemoryEventStore to InMemoryEventStore before the legacy class is gone gives one name two referents in one namespace β€” exactly the collision the dual-export comment block was written to avoid. Spec Β§4.1 calls this out and requires simultaneity.
  2. The __init__ swap cannot precede the deletion. Rebinding InMemoryEventStore/PostgreSQLEventStore/SQLiteEventStore/ExpectedVersion/ReadDirection/AppendResult to the ports and adapters while stores/ still exists would leave ~10 legacy test modules β€” which import those names from eventsource and assert legacy behavior β€” failing on the next collection. And tests/unit/test_public_api.py::TestCollisionDecisions asserts, positively, that each of those six names is the legacy class; it goes red the instant the binding moves.
  3. The deletion cannot precede the swap. __init__.py is a runtime importer of five stores modules. Deleting stores/ first makes import eventsource an ImportError β€” nothing collects, no test runs, the commit cannot pass pre-commit.

So the swap, the rename, the stores/ deletion, the legacy-test deletion, and the test_public_api.py rewrite are one commit (Task 4). Everything that can be lifted out of that commit has been: the outbox port (Task 1) and the conformance retirement (Task 2) are additive and land first; the surviving test modules that merely touch the legacy surface are pre-migrated onto the adapters in Task 3, where they are green both before and after; and the ADR and docs, which reference nothing at import time, land after in Task 5.

Two smaller orderings inside that:

Behavior deltas this slice makes visible

Spec decisions, not implementation choices. Repeated in the task that first encounters each.

Delta Legacy Ports Who feels it
TypeConverter field-name guessing string values inside untyped dict[str, Any] event fields rewritten to UUID/datetime by _id/_at suffix heuristics untyped dict fields round-trip as plain JSON types Task 4: stores/_type_converter.py and its 333-line suite die; CHANGELOG calls it out loudly (Task 5)
stored_at on the in-memory store fabricated as event.occurred_at real datetime.now(UTC) Task 3: any surviving assertion of stored_at == occurred_at is wrong and is rewritten, not relaxed
Store spans inmemory_event_store. / postgresql_event_store. / sqlite_event_store.* adapters emit none (ADR 0016 amendment) Task 4: the three tests/unit/stores/test_*_tracing.py suites are deleted, not retargeted
Category read filters/orders on event.occurred_at, exclusive > filters/orders on stored_at, inclusive >=, position tie-break Task 3: timestamp-suite cases that assert the exclusive boundary die; Β§5.2
BACKWARD feed reads, feed timestamp filters expressible via ReadOptions no ports equivalent; capability dropped Task 4: the BACKWARD cases in tests/stores/test_read_all_tenant_filter.py die with the file
Cross-type get_events(aggregate_type=None) expressible no port; dropped (spec Β§2) already gone in slice (c); Task 5 records it in ADR 0025
Duplicate event_id in-memory/postgresql silently skip DuplicateEventError Task 5: ADR 0025 + CHANGELOG
AppendResult.position position of the last appended event position of the first Task 5: ADR 0025 + CHANGELOG
Empty append batch AppendResult.successful(expected_version) ValueError Task 5: CHANGELOG
Empty store get_global_position() returns 0 current_position() returns None Task 5: CHANGELOG
OptimisticLockError.expected_version int, carrying the -1/0/-2 sentinels unchanged β€” deliberately still int (spec Β§1.7) Task 5: ADR 0025 records the deliberate non-change

Task 1: Port the outbox write onto the PostgreSQL adapter

Files:

Interfaces:


class PostgreSQLEventStore:
    def __init__(self, engine: AsyncEngine, event_registry: EventRegistry | None = None, *,
                 store_id: str | None = None, create_schema: bool = False,
                 outbox_enabled: bool = False) -> None: ...
    @property
    def outbox_enabled(self) -> bool: ...

Why this is a real feature and not legacy cruft (spec Β§4.4). Same-transaction outbox writes are the entire point of the transactional outbox pattern: the event row and the outbox row commit or roll back together. The legacy PostgreSQLEventStore is the only outbox writer in the tree. Deleting it without a replacement would silently downgrade the pattern to a two-phase write with no atomicity, which is a correctness regression disguised as a refactor. The wider outbox ring-migration (protocol split, move to ports/+adapters/) is explicitly out of scope (spec Β§10) β€” only the write path moves.

Read src/eventsource/stores/postgresql.py:417-459 (_write_to_outbox) in full, and the append_events block that calls it β€” specifically where in the transaction the call sits relative to the event INSERT and the session.commit(). Read src/eventsource/adapters/postgresql/store.py:241-330 (append) alongside it.

Two things must be true of the port and must be confirmed by reading, not assumed:

Note the two call-site differences you must bridge: the legacy method takes aggregate_type: str explicitly, where the adapter has stream.category; and the legacy store uses json.dumps from the stdlib where the adapter has json_dumps from eventsource.serialization. Use the adapter's json_dumps for consistency with the rest of the module only if it produces byte-compatible output for this payload β€” check serialization/ before switching, and if there is any doubt, use stdlib json.dumps exactly as the legacy store does and say so in a comment. The reader's expectations win over module-local consistency.

Create tests/unit/adapters/test_postgresql_outbox.py. The existing unit coverage for this adapter mocks sqlalchemy sessions β€” read tests/unit/test_postgresql_event_store.py:100-140 (the legacy fixtures, which still exist at this point and are the closest working model) and tests/unit/adapters/ for the house style, and follow whichever the adapter's own tests already use.

Cases:

Run: uv run pytest tests/unit/adapters/test_postgresql_outbox.py -q β€” Expected: FAIL (TypeError: unexpected keyword argument 'outbox_enabled').

Add outbox_enabled: bool = False as a keyword-only constructor parameter, store it, expose the read-only property, and add _write_to_outbox ported per Step 1. Call it inside append's existing async with self._session_factory() as session: block, per event, after that event's INSERT ... RETURNING global_position and before await session.commit().

Docstring the parameter with the guarantee it provides ("the outbox row and the event row commit in the same transaction") and the pointer that the outbox reader lives in eventsource.repositories.outbox. Do not add tracing (ADR 0016 amendment: the adapters carry no store spans).


grep -rn "outbox" src/eventsource/adapters/postgresql/store.py

Expected: the constructor parameter, the property, _write_to_outbox, its call site, and docstring prose β€” nothing else.


grep -rn "pytest.mark.skip" tests/integration/e2e/test_full_flow.py

Expected: no matches referencing the outbox.

Run: uv run pytest tests/unit/adapters/ -q β€” Expected: PASS. Run: uv run mypy src/eventsource/ --config-file=pyproject.toml β€” Expected: clean. Run: uv run ruff check src/eventsource/adapters/ tests/unit/adapters/ tests/integration/ β€” Expected: clean. Run: uv run lint-imports β€” Expected: clean.

The integration suites require Docker and are the orchestrator's to run; do not start services.


git add src/eventsource/adapters/postgresql/store.py tests/unit/adapters/test_postgresql_outbox.py \
        tests/integration/conftest.py tests/integration/e2e/test_full_flow.py \
        tests/integration/repositories/test_outbox.py
git commit -m "feat: same-transaction outbox writes on the postgresql adapter"

Record in the commit body: that the outbox row and event row share one session and one commit, the payload shape reproduced verbatim for the existing reader, and that the e2e test skipped since slice (a) is now live.


Task 2: Retire `EventStoreConformanceSuite` after a case-by-case gap check

Files:

Interfaces:

Spec Β§5.3 requires the gap check before the deletion, case by case. conformance_ports/ is the richer per-port successor (78 cases across six suites plus a hypothesis StoreStateMachine), but "richer overall" is not "covers each of these eight". Do the comparison honestly; a lost assertion is a lost guarantee for every third-party adapter author.

The legacy suite has exactly eight store cases (src/eventsource/testing/conformance.py, lines 91-351). Read each one's body, then read the candidate successor's body, and record a verdict for each in the commit body. The plan author's reading is below β€” verify it, do not trust it; where you disagree, your reading of the code wins and you say so in the commit body.

Legacy case Candidate successor Author's reading
test_append_and_get_roundtrip (:91) StreamReaderConformance::test_read_returns_exactly_appended_events_in_order (stream_reader.py:31) covered
test_stream_isolation (:130) β€” gap candidate. No ports case appends to two distinct streams and asserts each read returns only its own. CategoryQueryConformance::test_only_named_category_returned is category isolation, not stream isolation.
test_optimistic_locking (:171) AppenderConformance::test_exact_append_mismatched_version_conflicts (appender.py:104) covered
test_empty_stream (:207) StreamReaderConformance::test_get_stream_version_of_absent_stream_is_zero (stream_reader.py:98) partial. The version half is covered; whether reading an absent stream yields zero envelopes rather than raising may not be. Check.
test_event_metadata_preserved (:230) β€” gap candidate, and the one spec Β§5.3 names by name. Assert at envelope level: event_id, event_type, aggregate_id, aggregate_version, occurred_at, tenant_id survive a round-trip unchanged, plus envelope.stream_version and envelope.stream_id.
test_event_exists_idempotency (:260) EventLookupConformance (event_lookup.py:32,39,44) covered
test_expected_version_any (:288) AppenderConformance::test_any_append_to_{fresh,existing}_stream_succeeds (appender.py:62,69) covered
test_global_position_tracking (:320) GlobalFeedConformance::test_full_read_returns_all_events_in_position_order + test_current_position_equals_last_envelope_position (feed.py:32,94) covered

For each case Step 1 confirms as a gap, add it to the appropriate conformance_ports/ suite β€” test_stream_isolation and the absent-stream read to StreamReaderConformance, metadata preservation to StreamReaderConformance (it is a stream-read assertion about envelope contents). Match the surrounding style exactly: the suites take a store: _AppenderReader fixture and use the _fixtures.py helpers; read two neighbouring cases before writing.

Do not port a case Step 1 found covered "for completeness" β€” a duplicated assertion in a suite every adapter runs is pure cost.

Run: uv run pytest tests/unit/adapters/ -q before adding (baseline PASS) and after (still PASS, with more cases collected). The memory/sqlite adapter conformance runners under tests/unit/adapters/ pick up new suite cases automatically; confirm the collected count rose by exactly the number you added.

If a newly added case fails on an adapter, stop and report. That is a genuine adapter bug the legacy suite was catching and the ports suites were not β€” which is precisely what this gap check exists to find, and it is not an implementer's call to fix silently.


grep -rn "EventStoreConformanceSuite" src/ tests/ bench/ examples/

Expected: no matches. (docs/ still has matches in guides/validate-custom-backend.md, api/index.md, api/testing.md, tutorials/08-testing.md, core-surface.md β€” those are Task 5's.)


grep -rn "eventsource.stores" src/eventsource/testing/

Expected: no matches.

Run: uv run pytest tests/unit/test_conformance.py tests/unit/adapters/ -q β€” Expected: PASS. Run: uv run mypy src/eventsource/ --config-file=pyproject.toml β€” Expected: clean. Run: uv run ruff check src/eventsource/testing/ tests/unit/ β€” Expected: clean. Run: uv run lint-imports β€” Expected: clean. (eventsource.testing.conformance stays listed in the Tier-0 forbidden contract and stays Tier 0 β€” it now imports strictly fewer modules.)


git add src/eventsource/testing/conformance.py src/eventsource/testing/__init__.py \
        src/eventsource/testing/conformance_ports/ tests/unit/test_conformance.py
git commit -m "refactor: retire the abc event store conformance suite"

Record in the commit body: the eight-case verdict table from Step 1, which gaps were real, and where each ported assertion now lives.


Task 3: Pre-migrate the surviving legacy-touching test modules

Files:

Interfaces:

Why this task exists. These four modules are green against the legacy surface today and must be green against the adapters tomorrow; nothing about them requires the deletion to have happened. Lifting them out of Task 4 removes roughly a thousand lines of unrelated churn from the one commit that cannot be split, and it lets their behavior deltas (stored_at, category-read boundaries) be reviewed on their own.


grep -n "stores\|InMemoryEventStore\|PostgreSQLEventStore\|SQLiteEventStore\|StoredEvent\|ReadOptions\|EventStream\|append_events\|get_events\|get_global_position\|ExpectedVersion\|validate_timestamp" \
  tests/unit/test_edge_cases.py tests/unit/test_additional_coverage.py tests/unit/test_timestamp_types.py tests/conftest.py

Record the hit list. Classify each hit as RETARGET (constructor/fixture swap), REWRITE (asserts on legacy types or legacy boundary semantics), or DELETE (tests a construct that dies β€” the legacy dataclasses StoredEvent/EventStream/ReadOptions, the validate_timestamp helper, TypeConverter). Spec Β§7 slice (d) marks all four modules REWRITE with a DELETE subset; the classification per case is yours to make from the code.

Per spec Β§5.2: stores/_compat.py::validate_timestamp dies with its importers, so cases exercising the helper directly are deleted. Cases asserting store-level timestamp behavior are checked against CategoryQueryConformance (which has test_from_timestamp_honored, test_from_timestamp_is_inclusive, test_ordered_by_stored_at) β€” if the assertion is already covered there, delete it; if it is a genuinely uncovered store behavior, retarget it onto MemoryEventStore and note in the commit body why it is not conformance material.

The category-read boundary flips here: legacy filtered on event.occurred_at exclusive (>), the port filters on stored_at inclusive (>=) with position tie-break. A case asserting the exclusive boundary is asserting behavior that no longer exists β€” delete it or invert it deliberately; do not "fix" it by nudging a timestamp until it passes.

Drop the legacy-dataclass cases (StoredEvent, EventStream, ReadOptions, legacy AppendResult/ExpectedVersion construction). Retarget the rest onto MemoryEventStore β€” MemoryEventStore, not InMemoryEventStore; the rename is Task 4's, and using the future name here would not import.

Translate call sites per spec Β§1: append_events(id, type, events, n) β†’ append(StreamId(aggregate_id=id, category=type), events, ExpectedVersion...) mapping the sentinel by name (stores/legacy.py::_expected_from_int is the executable reference and still exists at this point); get_events(...) β†’ [e async for e in store.read_stream(...)] or collect(...); EventStream.version β†’ get_stream_version(stream); StoredEvent.global_position/.stream_position β†’ EventEnvelope.position/.stream_version.

Watch for the stored_at delta: the legacy in-memory store fabricated stored_at=event.occurred_at; the memory adapter stamps a real datetime.now(UTC). An assertion of equality between the two is now false and must be rewritten to assert what it actually meant (usually ordering or presence), not deleted silently.

That line is from eventsource.stores.sqlite import SQLiteEventStore inside a fixture. Retarget it to from eventsource.adapters.sqlite import SQLiteEventStore and adjust the construction: the adapter takes (database, event_registry=None, *, store_id=None, wal_mode=True, busy_timeout=5000) and lazily connects and applies schema on first use β€” delete any initialize() / async with ceremony the fixture performs, and keep close() on teardown (the adapter has one). Read the fixture body and its consumers before changing it; if a consumer depends on is_connected / database / wal_mode / busy_timeout properties the adapter does not have, report rather than inventing them.

The root in_memory_store fixture (:305) already yields MemoryEventStore β€” slice (a) did that. Do not touch it.


grep -rn "eventsource.stores" tests/ --include='*.py' | grep -v "tests/unit/test_in_memory_event_store.py\|tests/unit/test_event_store_interface.py\|tests/unit/test_postgresql_event_store.py\|tests/stores/\|tests/unit/stores/\|tests/unit/test_eventstore_global_position.py\|tests/unit/test_public_api.py"

Expected: no matches. Everything still referencing the legacy surface is a file Task 4 deletes or rewrites.

Run: uv run pytest tests/unit/test_edge_cases.py tests/unit/test_additional_coverage.py tests/unit/test_timestamp_types.py -q β€” Expected: PASS. Run: uv run pytest tests/unit/ -q -x --co β€” Expected: collection succeeds (nothing else broke). Run: uv run ruff check tests/ β€” Expected: clean. Run: uv run lint-imports β€” Expected: clean.


git add tests/unit/test_edge_cases.py tests/unit/test_additional_coverage.py \
        tests/unit/test_timestamp_types.py tests/conftest.py
git commit -m "test: move the surviving legacy-surface test modules onto the adapters"

Record in the commit body: the DELETE/RETARGET/REWRITE counts, which timestamp cases were dropped as conformance-covered, and every stored_at assertion that changed meaning.


Task 4: The deletion β€” rename, public-API swap, `stores/` removed

Why this task is one commit. See "Deletion ordering" in the Global Constraints. In short: the rename needs the legacy class gone, the swap needs the legacy tests gone, and the deletion needs the swap done. Tasks 1-3 removed everything that could be removed from this commit; what remains is irreducible. The steps are ordered so an implementer can work outside-in, and the orchestrator may dispatch Steps 1-4 and Steps 5-8 as separate work units against the same uncommitted tree β€” but there is exactly one commit at the end.

Files:

Interfaces:

Category Names
Ports EventAppender, StreamReader, EventLookup, GlobalEventFeed, CategoryQuery, FullEventStore, AggregateStore, collect
Value objects EventEnvelope, AppendResult, Position, ExpectedVersion, ReadDirection, StreamReadOptions, FeedReadOptions, CategoryReadOptions β€” all the ports definitions, now bound at top level
Store adapters InMemoryEventStore (renamed), SQLiteEventStore, PostgreSQLEventStore (the adapter classes), IntPositionCodec, ASYNCPG_AVAILABLE, AIOSQLITE_AVAILABLE, SQLITE_AVAILABLE
Sync SyncEventStoreAdapter (already retyped in slice (a))
Exceptions unchanged

Names that die from eventsource and everywhere (spec Β§4.2): EventStore, EventStream, StoredEvent, ReadOptions, LegacyStoreAdapter, TypeConverter, DefaultTypeConverter, DEFAULT_UUID_FIELDS, DEFAULT_STRING_ID_FIELDS, the legacy ExpectedVersion / ReadDirection / AppendResult classes, the legacy InMemoryEventStore / PostgreSQLEventStore / SQLiteEventStore classes, MemoryEventStore (renamed, not removed), and the eventsource.stores import path itself. EventPublisher survives β€” it keeps its home in ports/bus.py; only the stores/interface.py re-export dies.


grep -rln "MemoryEventStore" src/ tests/ bench/ examples/ | sort

Record the list. It includes files where the match is the legacy InMemoryEventStore (a substring of the same string) β€” separate the two before editing. A blind sed s/MemoryEventStore/InMemoryEventStore/ would turn InMemoryEventStore into InInMemoryEventStore; the safe form is a word-boundary-anchored replacement of MemoryEventStore that does not match when preceded by In, applied only to files whose legacy references are being deleted in this same commit anyway.

Note the four src/ sites that are not simple imports: adapters/memory/store.py (the class definition and its docstring), adapters/memory/__init__.py (import + __all__), testing/harness.py (6 references incl. two -> MemoryEventStore return annotations and prose at :46), application/aggregates/repository.py (2, in docstrings), testing/partitioned_memory.py (1), __init__.py (4).

This file is the acceptance test for spec Β§4 and it flips wholesale. It currently asserts, positively, that six top-level names are the legacy classes (TestCollisionDecisions, lines ~64-126). After the swap:


class TestBlessedStoreSurface:
    """Spec Β§4.1: one referent per name. The ports and adapters own them all."""

    def test_top_level_expected_version_is_the_port_vo(self) -> None:
        from eventsource.ports import ExpectedVersion
        assert eventsource.ExpectedVersion is ExpectedVersion

    def test_top_level_in_memory_event_store_is_the_memory_adapter(self) -> None:
        from eventsource.adapters.memory.store import InMemoryEventStore
        assert eventsource.InMemoryEventStore is InMemoryEventStore

β€” and the same shape for ReadDirection, AppendResult, SQLiteEventStore, PostgreSQLEventStore.


DEAD_NAMES = [
    "EventStore", "EventStream", "StoredEvent", "ReadOptions", "LegacyStoreAdapter",
    "TypeConverter", "DefaultTypeConverter", "DEFAULT_UUID_FIELDS",
    "DEFAULT_STRING_ID_FIELDS", "MemoryEventStore",
]

def test_dead_names_are_gone_from_the_public_api() -> None:
    for name in DEAD_NAMES:
        assert not hasattr(eventsource, name), f"eventsource.{name} should not exist"
        assert name not in eventsource.__all__

Run: uv run pytest tests/unit/test_public_api.py -q β€” Expected: FAIL.

Rename the class in src/eventsource/adapters/memory/store.py and update its docstring; update adapters/memory/__init__.py (import and __all__); then apply the rename across every site from Step 1 except the files being deleted in Step 5 (do not spend edits on doomed files). Rationale for the name, for the commit body: every sibling memory adapter is InMemory (InMemorySnapshotStore, InMemoryCheckpointRepository, InMemoryDLQRepository, InMemoryEventBus, InMemoryTestHarness); a lone Memory would be permanent public-API inconsistency.

Do not add an alias. Do not keep MemoryEventStore importable from anywhere.

In src/eventsource/__init__.py:


git rm -r src/eventsource/stores/
git rm tests/unit/test_event_store_interface.py tests/unit/test_in_memory_event_store.py \
       tests/unit/test_postgresql_event_store.py tests/unit/test_eventstore_global_position.py
git rm -r tests/stores/ tests/unit/stores/

Before running these, confirm with git status --porcelain that no other agent has uncommitted work under those paths. If any file there is modified, stop and report rather than deleting someone's work.

Spec Β§7 slice (d) justifies each deletion: test_read_all_tenant_filter.py's tenant-filter cases are already in GlobalFeedConformance::test_tenant_filter_honored, and its BACKWARD-feed cases die with a capability that has no ports equivalent and no runtime consumer; the three test_*_tracing.py suites assert store spans the adapters deliberately do not emit (ADR 0016 amendment); test_type_converter.py dies with the field-name-guessing it tests (Β§5.1).

In pyproject.toml, in the Tier 0 modules must not import sqlalchemy contract's source_modules, delete the two rows whose modules no longer exist: "eventsource.stores.interface" and "eventsource.stores.in_memory". Change nothing else β€” the independence contract was already swapped to eventsource.adapters.* in an earlier slice (verified at HEAD), and [tool.mutmut] has no stores/ entry (verified), so neither needs an edit here.

Concurrency caveat: other agents edit pyproject.toml. Locate the contract by its name = "Tier 0 modules must not import sqlalchemy" line, not by line number, and re-read the file immediately before editing.


grep -rn "eventsource\.stores\|from eventsource import.*LegacyStoreAdapter\|LegacyStoreAdapter\|StoredEvent\|EventStream\|ReadOptions\|TypeConverter\|DEFAULT_UUID_FIELDS\|DEFAULT_STRING_ID_FIELDS\|validate_timestamp" \
  src/ tests/ bench/ examples/ pyproject.toml

Expected: zero matches. Any hit is either a file that should have been deleted or a consumer nobody retargeted.


grep -rn "\bMemoryEventStore\b" src/ tests/ bench/ examples/ | grep -v "InMemoryEventStore"

Expected: zero matches.


grep -rn "append_events\|get_events_by_type\|get_global_position\|\.stream_position\|\.global_position" src/ tests/ bench/ examples/

Expected: zero matches in src/. In tests/, the only acceptable hits are SQL column names (global_position is still the PostgreSQL/SQLite column the IntPositionCodec mints from, and the frozen legacy checkpoint column) β€” inspect every hit and confirm it is a column reference, not a method call.


grep -rn "eventsource.stores\|EventStore\b" src/eventsource/adapters/postgresql/store.py src/eventsource/adapters/sqlite/store.py

Expected: only the class names PostgreSQLEventStore / SQLiteEventStore themselves. The two module docstrings currently say "Ported from eventsource.stores.postgresql.PostgreSQLEventStore (untouched -- that module remains the legacy EventStore ABC implementation)" (postgresql/store.py:3-4) and the same for sqlite (sqlite/store.py:3). That statement is now false. Rewrite both to describe what the module is, without referencing a module that does not exist.

Two more one-liner docstring sweeps folded in here (accumulated carry-forwards, both stale prose left by slice (c)):

Run: uv run pytest tests/unit/test_public_api.py -q β€” Expected: PASS. Run: uv run python -c "import eventsource; print(len(eventsource.__all__))" β€” Expected: imports cleanly. Run: uv run python -c "import eventsource.stores" β€” Expected: ModuleNotFoundError. Run: uv run pytest tests/unit/ -q β€” Expected: PASS. (This task is the one exception to "targeted tests only": the unit suite is the only thing that proves the deletion did not orphan a consumer, and no narrower selection covers it. Do not run integration or make check β€” those stay the orchestrator's.) Run: uv run mypy src/eventsource/ --config-file=pyproject.toml β€” Expected: clean. Run: uv run ruff check src/ tests/ bench/ β€” Expected: clean. Run: uv run lint-imports β€” Expected: clean.


git add -u src/eventsource/stores/ tests/stores/ tests/unit/stores/
git add src/eventsource/__init__.py src/eventsource/adapters/ src/eventsource/testing/ \
        src/eventsource/application/ src/eventsource/migration/router.py \
        src/eventsource/migration/dual_write.py pyproject.toml tests/
git status --porcelain

Review that git status output line by line before committing β€” this is the largest commit of the retirement and a stray file from another agent must not ride along.


git commit -m "refactor: delete the legacy store surface and swap the public api"

Record in the commit body: the deleted line count (~4,536 src + ~5,700 test), the rename, the six rebound names, the EventPublisher survival, the two removed Tier-0 contract rows, and the confirmation that import eventsource.stores now raises.


Task 5: ADR 0025, contracts documentation, docs sweep, changelog

Files:

Interfaces:

docs/adrs/0025-legacy-store-retirement.md exists with Status: Proposed and a Context section. Change the Status to Accepted and write the Decision and Consequences. Follow the house shape β€” read 0019-clean-architecture-store-ports.md and 0024-projection-persistence-ports.md first; both are recent, complete, and by the same hand this record should sound like. Do not rewrite the existing Context; ADR bodies are immutable records and that paragraph was written by an earlier slice.

Per spec Β§9, the Decision must record all of:

  1. Retirement of the EventStore ABC surface with no shims and no back-compat aliases (unreleased software; the standing rule).
  2. The by-name sentinel mapping (ANY/NO_STREAM/STREAM_EXISTS β†’ .any_()/.no_stream()/.stream_exists()), never by numeric coincidence.
  3. Drop of cross-type get_events(aggregate_type=None). Rejected alternative, named and not built: a narrow StreamDiscovery.find_streams(aggregate_id) -> list[StreamId] port.
  4. AppendResult.position is the first appended event's position, where legacy global_position was the last.
  5. Duplicate-append raises DuplicateEventError where legacy in-memory/postgresql silently skipped.
  6. Category reads filter and order on storage time, inclusive, with position tie-break β€” where legacy used the event's own occurred_at, exclusive. Naive datetimes are rejected rather than silently compared.
  7. TypeConverter removal: typed pydantic sub-models over field-name guessing inside untyped dict[str, Any] fields.
  8. Store-span removal (amends ADR 0016); a ports-level tracing decorator is backlogged, not promised.
  9. SubscriptionPositions Position retype (amends ADR 0024).
  10. Count-behind lag (completes 0019's amendment of 0014).
  11. OptimisticLockError keeps its int expected_version field, deliberately β€” retyping a widely-caught exception to carry the VO is churn with no consumer demand, and the sentinel constants are an adapter-internal message-formatting detail.
  12. MemoryEventStore β†’ InMemoryEventStore, for sibling-naming consistency.
  13. Outbox write support ported onto the PostgreSQL adapter (Task 1), so the same-transaction guarantee survives the deletion of its only previous writer.

Two more that the slice (c) plan's self-review surfaced and that spec Β§9 does not list β€” include them, and note in the commit body that they are additions to the spec's enumeration:

  1. Nearest-position lookup became a binary search. find_nearest_source_position was ORDER BY source_position DESC LIMIT 1 over a BIGINT. Opaque tokens cannot be ordered in SQL (Position.to_str() is JSON; its lexicographic order is not position order), so the lookup became a binary search over the surrogate id with the comparison in Python, resting on a documented monotonicity precondition. Rejected alternative: load all mappings and scan (correct, unbounded memory).
  2. The legacy BIGINT position columns are frozen, not dropped. projection_checkpoints.global_position, migration_position_mappings.source_position/.target_position, and tenant_migrations.last_source_position/.last_target_position are neither written nor read by the library after slice (c). They stay in the schema: dropping a column is destructive, schemas/checkpoints.sql is under the Do Not Modify rule, and the additive-fragment mechanism exists to add. They die with their own schema revision, not this one.

The ADR needs an ADR Impact table per .claude/rules/definition-of-done.md. Reproduce the spec's Β§"ADR Impact" table (0001 stands, 0014 stands as amended by 0019, 0015 stands, 0016 amended, 0018 stands, 0019 amended, 0021 stands, 0024 amended), rendered as this record's own impact statement rather than copied verbatim as prose.

Per the definition-of-done rule, the Status pointers are part of the work, not follow-up. Add to each Status section β€” do not touch any Decision:

Update docs/adrs/index.md: the 0025 bullet currently ends "Proposed (full decision and consequences filled in by slice (d))". Rewrite it as a complete entry in the style of its neighbours β€” one dense sentence naming what it decides, its amendment relationships, and "Complete." Also update the 0016, 0019, and 0024 bullets to carry their new "Amended by ADR 0025" notes, matching how the file already marks amendments (e.g. the 0015 bullet's "Amended by ADR 0024").


grep -rn "eventsource\.stores\|EventStore\b\|StoredEvent\|EventStream\|ReadOptions\|append_events\|get_events_by_type\|get_global_position\|LegacyStoreAdapter\|TypeConverter\|MemoryEventStore\|EventStoreConformanceSuite" docs/ examples/ README.md CLAUDE.md

Work the hit list. Skip docs/superpowers/ entirely β€” specs and plans are dated records of what was decided when, and rewriting them destroys the audit trail. Everything else:

Add a comment to src/eventsource/migrations/additive/checkpoints_position_token.sql recording that projection_checkpoints.global_position is frozen β€” neither written nor read by the library after slice (b) β€” and that it is deliberately not dropped (destructive; schemas/checkpoints.sql is under the Do Not Modify rule; it dies with its own schema revision). Match the comment style already in that file and in additive/migration_position_tokens.sql, which carries the equivalent note for the migration tables.

This is a comment only. Do not add a DROP COLUMN. Do not touch anything under schemas/ or templates/.

CHANGELOG.md [Unreleased] already carries per-slice entries from (a)-(c). Add slice (d)'s, and β€” because this is the slice where the surface actually changes for a user β€” a Removed section that names every Β§4.2 name explicitly. Three existing entries must also be corrected, because they describe a state that no longer holds:

Since [Unreleased] has not shipped, edit these in place to describe the end state rather than layering a correction on top β€” and say in the commit body that you did.

Call the behavior deltas out loudly (spec Β§9): the TypeConverter removal (Β§5.1), first-vs-last AppendResult.position (Β§1.1), duplicate-append raising (Β§1.1), the category-read stored_at/inclusive change (Β§1.3), the stored_at fabrication fix (Β§1.6), the empty-batch ValueError, current_position() returning None on an empty store, and the loss of BACKWARD feed reads and feed timestamp filters. A user upgrading past this line needs each of them.


grep -rn "eventsource\.stores\|LegacyStoreAdapter\|StoredEvent\|EventStream\b\|ReadOptions\|DefaultTypeConverter\|EventStoreConformanceSuite\|MemoryEventStore" \
  src/ tests/ bench/ examples/ docs/ CLAUDE.md README.md pyproject.toml | grep -v "docs/superpowers/" | grep -v "InMemoryEventStore"

Expected: zero matches. This is the acceptance for the whole slice.


grep -rn "append_events\|get_events_by_type\|get_global_position" docs/ examples/ README.md CLAUDE.md | grep -v "docs/superpowers/"

Expected: zero matches.


git status --porcelain src/eventsource/migrations/

Expected: exactly one modified file, additive/checkpoints_position_token.sql. If any schemas/ or templates/ file shows as modified, revert it and report.

Run: uv run ruff check examples/ β€” Expected: clean. Run: uv run pytest tests/unit/test_public_api.py -q β€” Expected: PASS (docs changes must not move the surface). Run: uv run lint-imports β€” Expected: clean.


git add docs/ CLAUDE.md CHANGELOG.md examples/ \
        src/eventsource/adapters/README.md \
        src/eventsource/migrations/additive/checkpoints_position_token.sql
git commit -m "docs: adr 0025 and the store retirement documentation sweep"

Record in the commit body: the two Decision items added beyond spec Β§9's enumeration (the binary-search lookup and the frozen BIGINT columns), which ADR Status pointers were added versus already present, the three corrected changelog entries, and any doc page rewritten wholesale rather than patched.


Slice Completion Criteria

The orchestrator runs these; implementers do not.

Plan Self-Review

Spec Gaps and Contradictions Found (report, do not silently deviate)

  1. Β§8's contract diff is already applied. The spec presents the independence-contract swap from eventsource.stores. to eventsource.adapters. as slice (d) work ("latest with (d)"); at HEAD pyproject.toml already lists the three adapter packages. An earlier slice took it, as Β§8 permitted. Task 4 Step 6 is therefore reduced to deleting the two Tier-0 source_modules rows. Likewise Β§8's claim that eventsource.sync.adapter and eventsource.testing.sync_facade should be added as "free hardening" is already done. No deviation β€” the work is simply smaller than the spec anticipated.
  2. Β§7 slice (d) lists tests/unit/test_conformance.py (123) under DELETE with the note "keep its EventBusConformanceSuite half". Those instructions are in tension: a deleted file has no half. Read as "trim to the bus half", which is what Task 2 Step 3 does. If the bus half turns out to duplicate an existing bus conformance module, the implementer reports rather than deciding to delete.
  3. The spec's Β§7 slice (d) line counts have drifted, and one file is misfiled. Verified at HEAD: test_in_memory_event_store.py is 1157 (spec: 1157 βœ“), test_event_store_interface.py 706 βœ“, test_postgresql_event_store.py 1473 βœ“, test_sqlite_event_store.py 1214 βœ“, test_read_all_tenant_filter.py 437 βœ“, test_legacy_adapter.py 269 βœ“, test_type_converter.py 333 βœ“, test_eventstore_global_position.py 299 βœ“, test_conformance.py 123 βœ“, test_public_api.py 126 (spec: 125), test_edge_cases.py 621 βœ“, test_additional_coverage.py 495 βœ“, test_timestamp_types.py 228 βœ“. The tracing suites the spec lists as "593/445/538" are test_memory_tracing.py 593, test_sqlite_tracing.py 445, test_postgresql_tracing.py 538 β€” the spec's ordering of the last two is transposed against its own {memory,sqlite,postgresql} label. Cosmetic; recorded so a reviewer counting lines is not surprised. Also: src/eventsource/stores/sqlite.py is 1102 lines, not the 1098 in spec Β§6's deletion table.
  4. Β§4.3 does not address that SQLITE_AVAILABLE's current definition is entangled with the outbox import. The spec says the outbox guard at __init__.py:225 is "untouched (outbox slice's problem)" and separately that the sqlite store's try/except becomes a plain import. But today it is one try/except covering both, and it is what defines SQLITE_AVAILABLE. Untangling it is unavoidable, and Task 4 Step 4 spells out the resulting shape: the flag comes from adapters.sqlite, the store import becomes unconditional, and the outbox import keeps a guard of its own. The outbox repository is still untouched β€” only the statement that used to define the flag changes.
  5. Spec Β§9's ADR 0025 enumeration omits two decisions the slices actually made. The binary-search nearest-position lookup (slice (c) Task 2, flagged in that plan's own gap list as "deserv[ing] a line in ADR 0025") and the frozen-not-dropped legacy BIGINT position columns are both architecturally significant and neither appears in Β§9's list. Task 5 Step 1 adds them as items 14 and 15 and instructs the implementer to say so in the commit body.
  6. Β§3's testing/conformance.py paragraph and Β§5.3 disagree on rigor. Β§3 says the ABC suite "is retired in the final slice" flatly; Β§5.3 conditions the retirement on a gap check for two named cases (test_event_metadata_preserved, test_append_and_get_roundtrip). Task 2 follows Β§5.3 and widens it to all eight cases, because a two-case check over an eight-case suite is not a gap check. The plan author's own reading (recorded in Task 2 Step 1's table) finds two-and-a-half likely gaps, including test_stream_isolation, which Β§5.3 does not name at all β€” so the narrow check would have missed one.
  7. Neither the spec nor any slice plan assigns the two stale adapter module docstrings. adapters/postgresql/store.py:3-4 and adapters/sqlite/store.py:3 both assert that the legacy module "remains" / is "untouched" β€” statements that Task 4 makes false in the same commit that deletes their subject. Folded into Task 4 Step 7 alongside the two carry-forward one-liners in migration/router.py and migration/dual_write.py.