Structure Slice A β€” 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: Close the last three ring-placement entries left over from the clean-architecture campaign. locks/ becomes ports/locks.py + adapters/{postgresql,memory}/locks.py behind a DistributedLock Protocol; the nine-module readmodels/ package splits into ports/readmodels/ (four pure modules) and five adapter modules under adapters/{memory,postgresql,sqlite,sql}/; engine.py moves to adapters/_sql/engine.py. Two new conformance suites (DistributedLockConformance, ReadModelRepositoryConformance) replace triplicated per-backend assertions. After this slice, src/eventsource/ has no top-level non-ring sqlalchemy module, src/eventsource/locks/ and src/eventsource/readmodels/ each contain exactly one file (a deprecation shim), and eventsource.__all__ is byte-identical to what it is today.

Architecture: Three independent ring migrations following the pattern set by ADRs 0019/0021/0024/0025/0026 β€” small composed Protocols in ports/, backend-colocated implementations in adapters/, conformance suites in testing/conformance_ports/ that import only ports and never an adapter. Two packages whose import path is documented public API (eventsource.locks, eventsource.readmodels) get module-level __getattr__ + __dir__ deprecation shims scheduled for removal in 0.8.0, matching the bus/ decomposition precedent. engine.py has no such obligation β€” its public name is eventsource.create_async_engine β€” so it is deleted outright. One ADR (0029) records all of it, amending ADR 0023.

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

Spec: docs/superpowers/specs/2026-07-31-structure-slice-a-design.md (in full). Read the section named in each task before starting it. The spec's move tables (Β§2.5) and Protocol shapes (Β§1.3) are verbatim requirements, not sketches.

Baseline: authored against the tree at commit 8e9ccd4. All line numbers below were read from that tree, not inferred. If a line number does not match what you find, re-read the file and proceed on the code, not the number β€” but if the code differs, stop and report.

Global Constraints

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

Dependency order


A1 ──▢ A2          (locks: port+memory, then postgres+shim+consumers)
A3 ──▢ A4 ──▢ A5   (readmodels: port, then adapters+shim, then conformance)
A6                 (engine, independent)
A1..A6 ──▢ A7      (docs, ADR, CHANGELOG, import-linter contract, backlog)

A1, A3, A6 are the three roots and may run in parallel. A2 and A4 may not run concurrently with each other (shared pyproject.toml and adapters/*/__init__.py edits).

Integration tests

A2 and A5 have @pytest.mark.postgres bindings. Bring PostgreSQL up once:


docker compose -f docker-compose.test.yml up -d

and run with timeout 300 uv run pytest tests/integration/... -m postgres -v. If Docker is unavailable, complete the unit steps, run the integration steps as far as they go, and report the gap explicitly rather than claiming the acceptance criteria met.


Task A1: `ports/locks.py`, the in-memory adapter, and `DistributedLockConformance`

Spec Β§1.1–1.4, Β§1.5 first bullet. Chain root, no dependencies. Creates the lock port and its test-scoped adapter; PostgreSQLLockManager does not move until A2, so eventsource.locks keeps working unchanged throughout this task.

Files:

Interfaces:

def migration_lock_key(tenant_id: UUID, operation: str = "migration") -> str: ...

class DistributedLock(Protocol): def acquire( self, key: str, *, timeout: float | None = None, retry_interval: float = 0.1 ) -> AbstractAsyncContextManager[LockInfo]: ... async def try_acquire(self, key: str) -> LockInfo | None: ... async def release(self, key: str) -> None: ... async def is_held(self, key: str) -> bool: ...

class LockRegistry(Protocol): async def release_all(self) -> int: ... @property def held_lock_count(self) -> int: ...

class LockManager(DistributedLock, LockRegistry, Protocol): ... `` A2 annotates migration/cutover.py and migration/coordinator.py with DistributedLock (the narrow port), imports LockInfo/migration_lock_key from here, and makes PostgreSQLLockManager satisfy LockManager` without declaring it.

Create tests/unit/adapters/test_memory_locks_conformance.py:


"""Conformance tests for InMemoryLockManager against the DistributedLock port suite."""

from collections.abc import AsyncIterator

import pytest

from eventsource.adapters.memory import InMemoryLockManager
from eventsource.testing.conformance_ports import DistributedLockConformance


class TestMemoryLockManager(DistributedLockConformance):
    @pytest.fixture
    async def store(self) -> AsyncIterator[InMemoryLockManager]:
        manager = InMemoryLockManager(holder_id="conformance")
        yield manager
        await manager.release_all()

    async def test_lock_ids_are_stable_for_a_key(self, store: InMemoryLockManager) -> None:
        first = await store.try_acquire("stable")
        assert first is not None
        await store.release("stable")
        second = await store.try_acquire("stable")
        assert second is not None
        assert first.lock_id == second.lock_id

Run: timeout 120 uv run pytest tests/unit/adapters/test_memory_locks_conformance.py -q

Expected: FAIL at collection β€” ModuleNotFoundError: No module named 'eventsource.adapters.memory.locks' (raised from eventsource.adapters.memory's __init__), or ImportError: cannot import name 'InMemoryLockManager' if you happen to have created the module first. Either symptom is the red; an assertion failure is not.

LockInfo and migration_lock_key move verbatim from src/eventsource/locks/postgresql.py:40-55 and :507-525 β€” same field order, same defaults, same docstrings. Do not reformat them.


"""Distributed lock port.

Pure boundary interface: stdlib, typing, dataclasses, datetime, uuid only.
No sqlalchemy, no observability, no implementation code.

The contract splits along its two real consumer groups (ISP, ADR 0019):
`migration/cutover.py` and `migration/coordinator.py` acquire and release
individual locks (`DistributedLock`), while bulk lifecycle over everything
one manager holds (`LockRegistry`) is a shutdown-and-introspection concern
for whoever owns the manager.

Scope of the promise (ADR 0029, amending ADR 0023): these protocols describe
the *shape of the dependency* -- mutual exclusion among callers sharing one
manager instance, plus the error contract. They do **not** promise
cross-process exclusion, release on crash, or fairness. Those are
PostgreSQL-specific guarantees documented on
`eventsource.adapters.postgresql.locks.PostgreSQLLockManager` and pinned only
by its integration tests.
"""

from contextlib import AbstractAsyncContextManager
from dataclasses import dataclass
from datetime import datetime
from typing import Protocol
from uuid import UUID


@dataclass(frozen=True)
class LockInfo:
    """
    Information about an acquired lock.

    Attributes:
        key: The string key used to identify the lock
        lock_id: The numeric PostgreSQL lock ID (derived from key hash)
        acquired_at: When the lock was acquired
        holder_id: Optional identifier for the lock holder (for debugging)
    """

    key: str
    lock_id: int
    acquired_at: datetime
    holder_id: str | None = None


class DistributedLock(Protocol):
    """Acquire/release mutual exclusion on a string key."""

    def acquire(
        self,
        key: str,
        *,
        timeout: float | None = None,
        retry_interval: float = 0.1,
    ) -> AbstractAsyncContextManager[LockInfo]:
        """Acquire `key`, releasing it when the returned context exits.

        Declared as a plain method returning an async context manager rather
        than as `async def ... -> AsyncIterator[LockInfo]`: implementations
        decorate their `acquire` with `@asynccontextmanager`, whose runtime
        type is exactly `AbstractAsyncContextManager`, and the async-generator
        spelling would fail to type against it.

        Raises:
            LockAcquisitionError: if the lock cannot be acquired within `timeout`.
        """
        ...

    async def try_acquire(self, key: str) -> LockInfo | None:
        """Acquire `key` without blocking; `None` if it is already held.

        The caller owns the release.
        """
        ...

    async def release(self, key: str) -> None:
        """Release a lock previously taken with `try_acquire`.

        Raises:
            LockNotHeldError: if this manager does not hold `key`.
        """
        ...

    async def is_held(self, key: str) -> bool:
        """Is `key` currently held by this manager?"""
        ...


class LockRegistry(Protocol):
    """Bulk lifecycle over everything one manager instance holds."""

    async def release_all(self) -> int:
        """Release every held lock; returns the number released."""
        ...

    @property
    def held_lock_count(self) -> int:
        """Number of locks currently held by this manager."""
        ...


class LockManager(DistributedLock, LockRegistry, Protocol):
    """Composed convenience protocol: both capabilities in one object."""


def migration_lock_key(tenant_id: UUID, operation: str = "migration") -> str:
    """
    Create a lock key for migration operations.

    Provides a consistent naming convention for migration-related locks.

    Args:
        tenant_id: Tenant UUID
        operation: Operation type (migration, cutover, etc.)

    Returns:
        Lock key string in format "{operation}:{tenant_id}"

    Example:
        >>> key = migration_lock_key(tenant_id, "cutover")
        >>> async with lock_manager.acquire(key):
        ...     await perform_cutover()
    """
    return f"{operation}:{tenant_id}"


__all__ = [
    "DistributedLock",
    "LockInfo",
    "LockManager",
    "LockRegistry",
    "migration_lock_key",
]

None of the three protocols is @runtime_checkable β€” no consumer does isinstance, matching ports/store.py's policy. (ports/checkpoints.py is runtime-checkable; that is not the precedent to copy here.)

In src/eventsource/ports/__init__.py, add the import block in alphabetical position (after the eventsource.ports.envelopes block at line 17-24, before eventsource.ports.outbox at line 25):


from eventsource.ports.locks import (
    DistributedLock,
    LockInfo,
    LockManager,
    LockRegistry,
    migration_lock_key,
)

and append to __all__, after the "ProjectionFailureCount", entry that currently closes it:


    # Lock port
    "DistributedLock",
    "LockInfo",
    "LockManager",
    "LockRegistry",
    "migration_lock_key",

Do not touch src/eventsource/__init__.py: no lock name becomes a top-level export (spec Β§1.1 β€” docs/api/locks.md:189 says so deliberately, and A7 keeps that statement true).

Stdlib only β€” asyncio, dataclasses (via the port's LockInfo), datetime, hashlib, contextlib. It must import no sqlalchemy and no observability; the Tier-0 contract entry added in Step 7 enforces the first.

_key_to_lock_id is copied from PostgreSQLLockManager._key_to_lock_id (locks/postgresql.py:154-176) so LockInfo.lock_id has the same value for the same key across both adapters β€” that parity is what the binding's test_lock_ids_are_stable_for_a_key exercises.


"""In-process lock manager implementing the DistributedLock port.

**This is a test double, not a distributed lock.** It excludes only
coroutines running in one asyncio event loop in one process. It offers no
cross-process or cross-connection exclusion, no release on crash (a killed
process takes its lock table with it), and no fairness or FIFO ordering
among waiters. Use it in unit tests that need a `DistributedLock` and
nothing more; use
`eventsource.adapters.postgresql.locks.PostgreSQLLockManager` anywhere two
processes must coordinate. See ADR 0029 and ADR 0023.
"""

from __future__ import annotations

import asyncio
import hashlib
from collections.abc import AsyncIterator
from contextlib import asynccontextmanager
from datetime import UTC, datetime

from eventsource.locks.postgresql import LockAcquisitionError, LockNotHeldError
from eventsource.ports.locks import LockInfo


class InMemoryLockManager:
    """Single-process `LockManager` backed by a dict and an `asyncio.Condition`."""

    def __init__(self, *, holder_id: str | None = None) -> None:
        self._holder_id = holder_id
        self._held: dict[str, LockInfo] = {}
        self._condition = asyncio.Condition()

    @staticmethod
    def _key_to_lock_id(key: str) -> int:
        """63-bit lock id for `key`, identical to the PostgreSQL adapter's."""
        hash_bytes = hashlib.sha256(key.encode()).digest()
        return int.from_bytes(hash_bytes[:8], byteorder="big") & 0x7FFFFFFFFFFFFFFF

    def _make_info(self, key: str) -> LockInfo:
        return LockInfo(
            key=key,
            lock_id=self._key_to_lock_id(key),
            acquired_at=datetime.now(UTC),
            holder_id=self._holder_id,
        )

    @asynccontextmanager
    async def acquire(
        self,
        key: str,
        *,
        timeout: float | None = None,
        retry_interval: float = 0.1,
    ) -> AsyncIterator[LockInfo]:
        """Acquire `key`, releasing it on context exit.

        `retry_interval` is accepted for port compatibility and ignored: this
        implementation waits on a condition variable rather than polling.
        """
        info = await self._acquire(key, timeout)
        try:
            yield info
        finally:
            await self._release(key)

    async def _acquire(self, key: str, timeout: float | None) -> LockInfo:
        async def wait_and_take() -> LockInfo:
            async with self._condition:
                await self._condition.wait_for(lambda: key not in self._held)
                info = self._make_info(key)
                self._held[key] = info
                return info

        if timeout is None:
            return await wait_and_take()
        try:
            return await asyncio.wait_for(wait_and_take(), timeout)
        except TimeoutError as exc:
            raise LockAcquisitionError(
                key=key,
                reason=f"Timeout after {timeout}s",
                timeout=timeout,
            ) from exc

    async def _release(self, key: str) -> None:
        async with self._condition:
            self._held.pop(key, None)
            self._condition.notify_all()

    async def try_acquire(self, key: str) -> LockInfo | None:
        async with self._condition:
            if key in self._held:
                return None
            info = self._make_info(key)
            self._held[key] = info
            return info

    async def release(self, key: str) -> None:
        async with self._condition:
            if key not in self._held:
                raise LockNotHeldError(key)
            del self._held[key]
            self._condition.notify_all()

    async def is_held(self, key: str) -> bool:
        async with self._condition:
            return key in self._held

    async def release_all(self) -> int:
        async with self._condition:
            released = len(self._held)
            self._held.clear()
            self._condition.notify_all()
            return released

    @property
    def held_lock_count(self) -> int:
        return len(self._held)


__all__ = ["InMemoryLockManager"]

Note the temporary import on line from eventsource.locks.postgresql import LockAcquisitionError, LockNotHeldError. A2 replaces it with from eventsource.exceptions import LockAcquisitionError, LockNotHeldError. It is correct for A1 (that is where the classes are at 8e9ccd4) and A2's step list retargets it explicitly. It does not make this module sqlalchemy-dependent for import-linter purposes β€” eventsource.locks.postgresql imports sqlalchemy, so the Tier-0 contract entry added in Step 7 would fail. Therefore in A1 the entry is not yet added; see Step 7's exact instruction.

In src/eventsource/adapters/memory/__init__.py, add the import in alphabetical position (after dlq, before outbox) and the __all__ entry (after "InMemoryEventStore", before "InMemoryOutboxRepository"):


from eventsource.adapters.memory.locks import InMemoryLockManager

    "InMemoryLockManager",

Also extend the module docstring's port list: """In-process memory adapters implementing the store, snapshot, checkpoint, DLQ, outbox, and lock ports."""

src/eventsource/testing/conformance_ports/locks.py. Nine cases, exactly the intersection both backends honestly meet (spec Β§1.4). The module docstring must state what the suite deliberately does not pin.


"""Conformance suite for the `DistributedLock` port.

Subclass and provide a `store` fixture yielding a fresh lock manager.

Pins only the intersection every backend honestly meets: exclusion among
callers of one manager instance, the context-manager release contract, and
the two error types. **Deliberately not pinned here** -- cross-process or
cross-connection exclusion, release on crash, fairness/FIFO ordering among
waiters, and the numeric value of `LockInfo.lock_id`. Those are
PostgreSQL-specific and stay in
`tests/integration/locks/test_postgresql_locks_integration.py`.
"""

from abc import ABC, abstractmethod

import pytest

from eventsource.exceptions import LockAcquisitionError, LockNotHeldError
from eventsource.ports.locks import LockManager


class DistributedLockConformance(ABC):
    """Conformance suite for `DistributedLock` + `LockRegistry` implementations."""

    @abstractmethod
    @pytest.fixture
    def store(self) -> object:
        """Yield a fresh manager implementing `LockManager`."""
        raise NotImplementedError

    async def test_acquire_yields_info_for_the_requested_key(self, store: LockManager) -> None:
        async with store.acquire("alpha") as info:
            assert info.key == "alpha"

    async def test_is_held_inside_and_outside_the_block(self, store: LockManager) -> None:
        async with store.acquire("alpha"):
            assert await store.is_held("alpha") is True
        assert await store.is_held("alpha") is False

    async def test_acquire_releases_on_exception_and_propagates_it(
        self, store: LockManager
    ) -> None:
        sentinel = RuntimeError("boom")
        with pytest.raises(RuntimeError) as caught:
            async with store.acquire("alpha"):
                raise sentinel
        assert caught.value is sentinel
        assert await store.is_held("alpha") is False

    async def test_try_acquire_succeeds_on_free_key_and_fails_on_held(
        self, store: LockManager
    ) -> None:
        first = await store.try_acquire("alpha")
        assert first is not None
        assert first.key == "alpha"
        assert await store.try_acquire("alpha") is None

    async def test_release_makes_the_key_acquirable_again(self, store: LockManager) -> None:
        assert await store.try_acquire("alpha") is not None
        await store.release("alpha")
        assert await store.try_acquire("alpha") is not None

    async def test_release_of_a_never_held_key_raises(self, store: LockManager) -> None:
        with pytest.raises(LockNotHeldError):
            await store.release("never-held")

    async def test_acquire_with_timeout_on_a_held_key_raises(self, store: LockManager) -> None:
        assert await store.try_acquire("alpha") is not None
        with pytest.raises(LockAcquisitionError) as caught:
            async with store.acquire("alpha", timeout=0.05):
                pass  # pragma: no cover - acquisition must fail
        assert caught.value.timeout == 0.05

    async def test_different_keys_are_independent(self, store: LockManager) -> None:
        async with store.acquire("alpha"):
            async with store.acquire("beta") as beta:
                assert beta.key == "beta"
            assert await store.is_held("alpha") is True

    async def test_release_all_returns_the_count_and_empties_the_registry(
        self, store: LockManager
    ) -> None:
        assert await store.try_acquire("alpha") is not None
        assert await store.try_acquire("beta") is not None
        assert store.held_lock_count == 2
        assert await store.release_all() == 2
        assert store.held_lock_count == 0


__all__ = ["DistributedLockConformance"]

from eventsource.exceptions import LockAcquisitionError, LockNotHeldError is deliberate and forward-looking: those classes do not live there until A2. This suite therefore does not import successfully until A2 lands β€” which is fine for the port but not for A1's green gate. In A1, import them from eventsource.locks instead (from eventsource.locks import LockAcquisitionError, LockNotHeldError), and A2 retargets this line to eventsource.exceptions as an explicit step. Note that eventsource.locks is not a permitted suite import under the house convention, so this is a knowingly-temporary two-task deviation, closed by A2 β€” record it as such in the A1 report.

In src/eventsource/testing/conformance_ports/__init__.py: add the import (alphabetically, after feed, before outbox), add "DistributedLockConformance" to __all__, and add it to the docstring's suite list at line 10-14.


from eventsource.testing.conformance_ports.locks import DistributedLockConformance

Do not add eventsource.adapters.memory.locks to pyproject.toml's Tier-0 source_modules in this task. While the memory adapter still imports eventsource.locks.postgresql (Step 4's temporary import), that entry would make lint-imports fail. A2 adds the entry in the same step that retargets the import. This is the one deviation from "each task carries its own contract delta" and it is forced by the ordering; the A1 report must say so.


timeout 120 uv run pytest tests/unit/adapters/test_memory_locks_conformance.py -q
uv run ruff check src/eventsource tests --fix && uv run ruff format src/eventsource tests
uv run mypy src/eventsource/ --config-file=pyproject.toml
uv run lint-imports
make check

All green. Then:


git add src/eventsource/ports/locks.py \
        src/eventsource/adapters/memory/locks.py \
        src/eventsource/testing/conformance_ports/locks.py \
        tests/unit/adapters/test_memory_locks_conformance.py \
        src/eventsource/adapters/memory/__init__.py \
        src/eventsource/testing/conformance_ports/__init__.py \
        src/eventsource/ports/__init__.py
git commit -m "feat: add distributed lock port and in-memory adapter

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"

Acceptance: DistributedLockConformance passes against InMemoryLockManager; eventsource.ports.locks imports with sqlalchemy absent from sys.modules; eventsource.locks still exports all five legacy names unchanged; eventsource.__all__ unchanged; make check green.


Task A2: move `PostgreSQLLockManager`, rehome the lock exceptions, install the `locks/` shim

Spec Β§1.3 (target layout + the exceptions ruling), Β§1.5 second and third bullets, Β§1.6. Depends on A1.

Serialization constraint: this task edits pyproject.toml's Tier-0 source_modules list and src/eventsource/adapters/postgresql/__init__.py. Task A4 edits the same pyproject.toml block and the sibling adapters/{memory,sqlite,postgresql}/__init__.py files. A2 and A4 must not run concurrently.

Files:

Interfaces:

Create tests/unit/test_locks_shim.py:


"""The `eventsource.locks` deprecation shim resolves every legacy name."""

import warnings

import pytest

MOVED = {
    "LockInfo": "eventsource.ports.locks",
    "migration_lock_key": "eventsource.ports.locks",
    "LockAcquisitionError": "eventsource.exceptions",
    "LockNotHeldError": "eventsource.exceptions",
    "PostgreSQLLockManager": "eventsource.adapters.postgresql.locks",
}


@pytest.mark.parametrize(("name", "new_path"), sorted(MOVED.items()))
def test_legacy_name_resolves_with_a_deprecation_warning(name: str, new_path: str) -> None:
    import eventsource.locks as shim

    with pytest.warns(DeprecationWarning, match=new_path):
        attribute = getattr(shim, name)
    assert attribute is not None


def test_dir_lists_every_moved_name() -> None:
    import eventsource.locks as shim

    assert set(MOVED) <= set(dir(shim))


def test_unknown_attribute_raises_attribute_error() -> None:
    import eventsource.locks as shim

    with pytest.raises(AttributeError):
        shim.NotAThing  # noqa: B018


def test_lock_exceptions_are_eventsource_errors() -> None:
    from eventsource.exceptions import (
        EventSourceError,
        LockAcquisitionError,
        LockNotHeldError,
    )

    assert issubclass(LockAcquisitionError, EventSourceError)
    assert issubclass(LockNotHeldError, EventSourceError)


def test_importing_the_shim_emits_no_warning_by_itself() -> None:
    import importlib

    with warnings.catch_warnings():
        warnings.simplefilter("error", DeprecationWarning)
        importlib.import_module("eventsource.locks")

Run: timeout 120 uv run pytest tests/unit/test_locks_shim.py -q

Expected: FAIL. test_legacy_name_resolves_with_a_deprecation_warning fails with Failed: DID NOT WARN (the current __init__.py re-exports eagerly), and test_lock_exceptions_are_eventsource_errors fails with ImportError: cannot import name 'LockAcquisitionError' from 'eventsource.exceptions'.

Create tests/integration/locks/test_postgresql_locks_conformance.py:


"""Conformance tests for PostgreSQLLockManager against the DistributedLock port suite."""

from __future__ import annotations

from collections.abc import AsyncIterator
from typing import TYPE_CHECKING

import pytest
import pytest_asyncio

from eventsource.adapters.postgresql.locks import PostgreSQLLockManager
from eventsource.testing.conformance_ports import DistributedLockConformance

if TYPE_CHECKING:
    from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker

pytestmark = [pytest.mark.integration, pytest.mark.postgres]


class TestPostgreSQLLockManager(DistributedLockConformance):
    @pytest_asyncio.fixture
    async def store(
        self, postgres_session_factory: async_sessionmaker[AsyncSession]
    ) -> AsyncIterator[PostgreSQLLockManager]:
        manager = PostgreSQLLockManager(
            postgres_session_factory,
            holder_id="conformance",
            enable_tracing=False,
        )
        yield manager
        await manager.release_all()

Run: timeout 120 uv run pytest tests/integration/locks/test_postgresql_locks_conformance.py -q

Expected: FAIL at collection β€” ModuleNotFoundError: No module named 'eventsource.adapters.postgresql.locks'.

Append to src/eventsource/exceptions.py, after the last existing class, the two classes moved from locks/postgresql.py:58-90 β€” bodies verbatim, base class changed from Exception to EventSourceError:


class LockAcquisitionError(EventSourceError):
    """
    Raised when a lock cannot be acquired.

    Attributes:
        key: The lock key that could not be acquired
        reason: Description of why acquisition failed
        timeout: The timeout value if timeout was the cause
    """

    def __init__(
        self,
        key: str,
        reason: str,
        timeout: float | None = None,
    ):
        self.key = key
        self.reason = reason
        self.timeout = timeout
        super().__init__(f"Failed to acquire lock '{key}': {reason}")


class LockNotHeldError(EventSourceError):
    """
    Raised when attempting to release a lock not held.

    Attributes:
        key: The lock key that was not held
    """

    def __init__(self, key: str):
        self.key = key
        super().__init__(f"Lock '{key}' is not held by this session")

If exceptions.py has an __all__, add both names to it in the existing order convention; check before assuming (at 8e9ccd4 it does not, and in that case add nothing).

This is the slice's one semantic change. It widens only: every existing except LockAcquisitionError and except Exception still catches, and the newly-catching except EventSourceError catches nothing lock-related today.


git mv src/eventsource/locks/postgresql.py src/eventsource/adapters/postgresql/locks.py

Then edit src/eventsource/adapters/postgresql/locks.py:

  1. Delete the LockInfo dataclass (old lines 40-55), both exception classes (old lines 58-90), and the migration_lock_key function (old lines 507-525). They now live in eventsource.ports.locks and eventsource.exceptions.
  2. Replace the import block. Old: ```python from collections.abc import AsyncIterator from contextlib import asynccontextmanager from dataclasses import dataclass from datetime import UTC, datetime from typing import TYPE_CHECKING from uuid import UUID

from sqlalchemy import text from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker

from eventsource.observability import Tracer, create_tracer

if TYPE_CHECKING: pass `` New: ``python from collections.abc import AsyncIterator from contextlib import asynccontextmanager from datetime import UTC, datetime

from sqlalchemy import text from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker

from eventsource.exceptions import LockAcquisitionError, LockNotHeldError from eventsource.observability import Tracer, create_tracer from eventsource.ports.locks import LockInfo `` (dataclass, UUID, and the empty TYPE_CHECKING block go with the code that used them. hashlib, asyncio, logging` stay.)

  1. Extend the module docstring's first paragraph with one sentence naming the port it implements and the guarantees that are its own, not the port's:

Implements eventsource.ports.locks.LockManager. The cross-process exclusion, release-on-connection-loss, and PostgreSQL-fairness guarantees documented below are this adapter's, not the port's -- see ADR 0029.

  1. Add __all__ = ["PostgreSQLLockManager"] at the end.

Change nothing else. The class body, the 63-bit key hashing, the per-lock AsyncSession, the poll loop, and every tracing attribute stay byte-identical. git diff -M should show this as a rename plus the deletions and import rewrite above, and nothing more.

In src/eventsource/adapters/postgresql/__init__.py, add the import first alphabetically (before outbox) and "PostgreSQLLockManager" to __all__ between "PostgreSQLEventStore" and "PostgreSQLOutboxRepository":


from eventsource.adapters.postgresql.locks import PostgreSQLLockManager

Update the docstring: """PostgreSQL adapter implementing the store, snapshot, outbox, and lock ports."""

In src/eventsource/adapters/memory/locks.py, replace:


from eventsource.locks.postgresql import LockAcquisitionError, LockNotHeldError

with:


from eventsource.exceptions import LockAcquisitionError, LockNotHeldError

In src/eventsource/testing/conformance_ports/locks.py, replace from eventsource.locks import LockAcquisitionError, LockNotHeldError with from eventsource.exceptions import LockAcquisitionError, LockNotHeldError (the form already written in A1's Step 6 code block).

Then in pyproject.toml, in the "Tier 0 modules must not import sqlalchemy" contract's source_modules, add after "eventsource.adapters.memory.outbox",:


    "eventsource.adapters.memory.locks",

(The eventsource.adapters.memory.readmodels entry that spec Β§4.3 pairs with this one belongs to A4 β€” do not add it here; the module does not exist yet and lint-imports will fail on a missing source module.)

Replace the entire contents of src/eventsource/locks/__init__.py:


"""Deprecated import path for the distributed-lock subsystem.

Every name below still resolves, each with a `DeprecationWarning` naming its
new home. This package is removed in 0.8.0.

- `LockInfo`, `migration_lock_key` -> `eventsource.ports.locks`
- `LockAcquisitionError`, `LockNotHeldError` -> `eventsource.exceptions`
- `PostgreSQLLockManager` -> `eventsource.adapters.postgresql.locks`

Resolution is lazy: importing this module pulls in neither sqlalchemy nor
the PostgreSQL adapter until a name that needs them is actually read.
"""

import importlib
import warnings

_MOVED = {
    "LockInfo": "eventsource.ports.locks",
    "migration_lock_key": "eventsource.ports.locks",
    "LockAcquisitionError": "eventsource.exceptions",
    "LockNotHeldError": "eventsource.exceptions",
    "PostgreSQLLockManager": "eventsource.adapters.postgresql.locks",
}

__all__ = [
    "LockAcquisitionError",
    "LockInfo",
    "LockNotHeldError",
    "PostgreSQLLockManager",
    "migration_lock_key",
]


def __getattr__(name: str) -> object:
    try:
        module_name = _MOVED[name]
    except KeyError:
        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from None
    warnings.warn(
        f"eventsource.locks.{name} is deprecated; "
        f"import it from {module_name} instead. "
        f"eventsource.locks is removed in 0.8.0.",
        DeprecationWarning,
        stacklevel=2,
    )
    return getattr(importlib.import_module(module_name), name)


def __dir__() -> list[str]:
    return sorted(__all__)

__dir__ is not optional β€” the snapshots migration shipped a lazy __getattr__ without it and broke introspection.

src/eventsource/migration/cutover.py:

src/eventsource/migration/coordinator.py:

grep -rn "eventsource.locks" src/ must now match only src/eventsource/locks/__init__.py.

tests/locks/test_postgresql_locks.py line 15 and tests/integration/locks/test_postgresql_locks_integration.py line 20 both read from eventsource.locks import (...). Replace each with the three-source form:


from eventsource.adapters.postgresql.locks import PostgreSQLLockManager
from eventsource.exceptions import LockAcquisitionError, LockNotHeldError
from eventsource.ports.locks import LockInfo, migration_lock_key

taking only the names each file actually imports (check its current import list; the integration file imports four names, not five). Nothing else in either file changes β€” that is the behavior-preservation evidence for the move, and the A2 reviewer checks exactly this with git diff tests/locks/test_postgresql_locks.py.


timeout 120 uv run pytest tests/unit/test_locks_shim.py tests/locks/ tests/unit/adapters/test_memory_locks_conformance.py -q
timeout 300 uv run pytest tests/integration/locks/ -m postgres -q   # needs Docker
uv run ruff check src/eventsource tests --fix && uv run ruff format src/eventsource tests
uv run mypy src/eventsource/ --config-file=pyproject.toml
uv run lint-imports
make check

Confirm the acceptance greps before committing:


grep -rn "eventsource\.locks" src/          # only src/eventsource/locks/__init__.py
test ! -e src/eventsource/locks/postgresql.py && echo "deleted"
git diff --stat tests/locks/test_postgresql_locks.py   # 1 file, small

git add src/eventsource/adapters/postgresql/locks.py src/eventsource/locks/__init__.py \
        src/eventsource/exceptions.py src/eventsource/adapters/postgresql/__init__.py \
        src/eventsource/adapters/memory/locks.py \
        src/eventsource/testing/conformance_ports/locks.py \
        src/eventsource/migration/cutover.py src/eventsource/migration/coordinator.py \
        tests/unit/test_locks_shim.py \
        tests/integration/locks/test_postgresql_locks_conformance.py \
        tests/locks/test_postgresql_locks.py \
        tests/integration/locks/test_postgresql_locks_integration.py \
        pyproject.toml
git add -u src/eventsource/locks/
git commit -m "refactor: move postgresql lock manager to adapters ring

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"

Acceptance (spec Β§1.6): grep -rn "eventsource.locks" src/ matches only the shim; src/eventsource/locks/postgresql.py gone; DistributedLockConformance green against both adapters; migration consumers annotate DistributedLock; eventsource.adapters.memory.locks passes the Tier-0 contract; all five legacy names import with a DeprecationWarning; tests/locks/test_postgresql_locks.py passes with only import lines changed; make check green.


Task A3: create `ports/readmodels/`, retarget the rest of `readmodels/` onto it

Spec Β§2.1–2.2, Β§2.4, Β§2.5 (first four rows), Β§2.7 first bullet. Chain root, no dependencies. This task moves only the four pure modules. readmodels/ keeps working identically from outside β€” schema, in_memory, postgresql, sqlite, projection and __init__ stay put and simply import from the new port.

Files:

Interfaces:

Create tests/unit/ports/test_readmodels_port_surface.py (create tests/unit/ports/__init__.py if the directory does not exist):


"""`eventsource.ports.readmodels` is importable without sqlalchemy."""

import subprocess
import sys


def test_public_names_import_from_the_port() -> None:
    from eventsource.ports.readmodels import (
        Filter,
        OptimisticLockError,
        Query,
        ReadModel,
        ReadModelError,
        ReadModelNotFoundError,
        ReadModelRepository,
        ReadModelRepositoryProtocol,
    )

    assert ReadModelRepositoryProtocol is ReadModelRepository
    assert issubclass(OptimisticLockError, ReadModelError)
    assert issubclass(ReadModelNotFoundError, ReadModelError)
    assert hasattr(ReadModel, "table_name")
    assert hasattr(Query, "with_filter")
    assert hasattr(Filter, "eq")


def test_no_submodule_pulls_in_sqlalchemy() -> None:
    """Import every port submodule in a fresh interpreter and assert sqlalchemy stayed out.

    A subprocess rather than an in-process check: by the time this test runs,
    another test module has almost certainly imported an adapter, so
    `sys.modules` in this process says nothing.
    """
    program = (
        "import sys\n"
        "import eventsource.ports.readmodels\n"
        "import eventsource.ports.readmodels.model\n"
        "import eventsource.ports.readmodels.query\n"
        "import eventsource.ports.readmodels.repository\n"
        "import eventsource.ports.readmodels.exceptions\n"
        "assert 'sqlalchemy' not in sys.modules, sorted(\n"
        "    m for m in sys.modules if m.startswith('sqlalchemy')\n"
        ")\n"
    )
    result = subprocess.run(
        [sys.executable, "-c", program], capture_output=True, text=True, check=False
    )
    assert result.returncode == 0, result.stderr

Run: timeout 120 uv run pytest tests/unit/ports/test_readmodels_port_surface.py -q

Expected: FAIL β€” ModuleNotFoundError: No module named 'eventsource.ports.readmodels' in both tests.


mkdir -p src/eventsource/ports/readmodels
git mv src/eventsource/readmodels/base.py       src/eventsource/ports/readmodels/model.py
git mv src/eventsource/readmodels/query.py      src/eventsource/ports/readmodels/query.py
git mv src/eventsource/readmodels/repository.py src/eventsource/ports/readmodels/repository.py
git mv src/eventsource/readmodels/exceptions.py src/eventsource/ports/readmodels/exceptions.py

Bodies are unchanged. Only two import rewrites exist in the whole set, both in repository.py:


from eventsource.readmodels.base import ReadModel

β†’


from eventsource.ports.readmodels.model import ReadModel

and inside its if TYPE_CHECKING: block:


    from eventsource.readmodels.query import Query

β†’


    from eventsource.ports.readmodels.query import Query

model.py (pydantic + stdlib), query.py (stdlib only), and exceptions.py (stdlib only) have no intra-package imports and need no edit at all. Note that model.py keeps the module name base nowhere: if its docstring or any docstring example says "readmodels.base", update the prose. Do not rename the ReadModel class.

Create src/eventsource/ports/readmodels/__init__.py:


"""Read-model port: the pure contract half of read-model persistence.

A subpackage rather than a flat `ports/readmodels.py` (ADR 0029): four
genuinely distinct pure artifacts -- a user-subclassable pydantic base, a
query specification language, a 15-method repository Protocol, and an
exception family -- that users import for four different reasons.
`eventsource.ports.readmodels` is the import path users see either way.

The adapter half lives under `eventsource.adapters.{memory,postgresql,
sqlite,sql}`.

Note: `OptimisticLockError` here is the read-model one
(`model_id`, `expected_version`, `actual_version`), a `ReadModelError`
subclass. It is a **different class** from
`eventsource.exceptions.OptimisticLockError`, which is raised on event
append and derives from `EventSourceError`. Neither catches the other. See
ADR 0029's recorded exception and the backlog item that resolves the name
collision.
"""

from eventsource.ports.readmodels.exceptions import (
    OptimisticLockError,
    ReadModelError,
    ReadModelNotFoundError,
)
from eventsource.ports.readmodels.model import ReadModel
from eventsource.ports.readmodels.query import Filter, Query
from eventsource.ports.readmodels.repository import (
    ReadModelRepository,
    ReadModelRepositoryProtocol,
)

__all__ = [
    "Filter",
    "OptimisticLockError",
    "Query",
    "ReadModel",
    "ReadModelError",
    "ReadModelNotFoundError",
    "ReadModelRepository",
    "ReadModelRepositoryProtocol",
]

Do not add these names to src/eventsource/ports/__init__.py. ports/__init__.py re-exports flat port modules; ports.readmodels is its own namespace, and adding eight more names to the flat ports surface is a public-API addition this slice does not make. (A7's CHANGELOG Added entry names eventsource.ports.readmodels, the package β€” not new eventsource.ports.* names.)

Each of these is a pure import rewrite; no other line changes.

src/eventsource/readmodels/schema.py line 41:


from eventsource.readmodels.base import ReadModel

β†’ from eventsource.ports.readmodels.model import ReadModel

src/eventsource/readmodels/in_memory.py lines 22-24:


from eventsource.readmodels.base import ReadModel
from eventsource.readmodels.exceptions import OptimisticLockError, ReadModelNotFoundError
from eventsource.readmodels.query import Filter, Query

β†’


from eventsource.ports.readmodels.exceptions import (
    OptimisticLockError,
    ReadModelNotFoundError,
)
from eventsource.ports.readmodels.model import ReadModel
from eventsource.ports.readmodels.query import Filter, Query

(these sort before the eventsource.observability block, so move them above it)

src/eventsource/readmodels/postgresql.py lines 27-29: same three-line rewrite as in_memory.py.

src/eventsource/readmodels/sqlite.py lines 33-34 and line 43:


from eventsource.readmodels.exceptions import OptimisticLockError, ReadModelNotFoundError
from eventsource.readmodels.query import Filter, Query

β†’ eventsource.ports.readmodels.{exceptions,query}, and the mid-file


from eventsource.readmodels.base import ReadModel as _BaseReadModel

β†’ from eventsource.ports.readmodels.model import ReadModel as _BaseReadModel. Leave the unusual mid-file placement and the _BaseReadModel alias exactly where they are β€” this task changes import targets, not import hygiene.

src/eventsource/readmodels/projection.py line 23 and the TYPE_CHECKING import at line 28:


from eventsource.readmodels.base import ReadModel

β†’ from eventsource.ports.readmodels.model import ReadModel


    from eventsource.readmodels.repository import ReadModelRepository

β†’ from eventsource.ports.readmodels.repository import ReadModelRepository

src/eventsource/readmodels/__init__.py stays an eager re-export package in this task (it becomes the shim in A4). Rewrite only its import block (lines 67-85), leaving the docstring and __all__ untouched:


from eventsource.ports.readmodels.exceptions import (
    OptimisticLockError,
    ReadModelError,
    ReadModelNotFoundError,
)
from eventsource.ports.readmodels.model import ReadModel
from eventsource.ports.readmodels.query import Filter, Query
from eventsource.ports.readmodels.repository import ReadModelRepository
from eventsource.readmodels.in_memory import InMemoryReadModelRepository
from eventsource.readmodels.postgresql import PostgreSQLReadModelRepository
from eventsource.readmodels.projection import ReadModelProjection
from eventsource.readmodels.schema import (
    POSTGRESQL_TYPE_MAP,
    SQLITE_TYPE_MAP,
    generate_full_schema,
    generate_indexes,
    generate_schema,
)
from eventsource.readmodels.sqlite import SQLiteReadModelRepository

All sixteen __all__ names still resolve from eventsource.readmodels. Nothing outside the package sees a difference.

In pyproject.toml's "Tier 0 modules must not import sqlalchemy" contract, delete these six lines:


    "eventsource.readmodels.base",
    "eventsource.readmodels.query",
    "eventsource.readmodels.schema",
    "eventsource.readmodels.repository",
    "eventsource.readmodels.in_memory",
    "eventsource.readmodels.exceptions",

Add nothing in their place. "eventsource.ports" is already in source_modules as a whole package, so ports/readmodels/ is covered on arrival β€” that is the guard that replaces four of the six. readmodels.schema and readmodels.in_memory are covered again in A4 (as adapters.sql.readmodel_schema β€” see the note below β€” and adapters.memory.readmodels).

readmodel_schema deliberately loses its Tier-0 guard when A4 moves it to adapters/sql/ (spec Β§2.3): the guard asserted the wrong property about a module that emits dialect-specific DDL. A7 adds the explanatory comment for that in the contract block; do not write it here, and do not add eventsource.adapters.sql.readmodel_schema to source_modules.

Serialization note: A4 edits this same contract block (adding eventsource.adapters.memory.readmodels), as does A2 (adding eventsource.adapters.memory.locks). A3 is a chain root and runs before both, so it has no conflict β€” but do not batch A3 and A4 into one agent run.


timeout 120 uv run pytest tests/unit/ports/test_readmodels_port_surface.py tests/unit/readmodels/ -q
uv run ruff check src/eventsource tests --fix && uv run ruff format src/eventsource tests
uv run mypy src/eventsource/ --config-file=pyproject.toml
uv run lint-imports
make check

tests/unit/readmodels/ must pass unmodified unless a test imports a private module path (eventsource.readmodels.base etc.). Check with grep -rn "readmodels\.\(base\|query\|repository\|exceptions\)" tests/ and retarget only what that finds.


git add src/eventsource/ports/readmodels/ src/eventsource/readmodels/ \
        tests/unit/ports/ pyproject.toml
git add -u src/eventsource/readmodels/
git commit -m "refactor: extract read model port into ports/readmodels

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"

Acceptance: eventsource.ports.readmodels and all four submodules import with sqlalchemy absent from sys.modules in a fresh interpreter; eventsource.readmodels still exports all sixteen names; eventsource.__all__ unchanged; make check green.


Task A4: move the five read-model adapters and install the `readmodels/` shim

Spec Β§2.3, Β§2.5 (last five rows + shim), Β§2.7 second bullet, Β§2.8. Depends on A3.

Serialization constraint: this task edits pyproject.toml's Tier-0 source_modules list and src/eventsource/adapters/{memory,postgresql,sqlite,sql}/__init__.py. Task A2 edits the same pyproject.toml block and adapters/{memory,postgresql}/__init__.py. A2 and A4 must not run concurrently.

Files:

Interfaces:

Create tests/unit/test_readmodels_shim.py:


"""The `eventsource.readmodels` deprecation shim resolves every legacy name."""

import warnings

import pytest

MOVED = {
    "ReadModel": "eventsource.ports.readmodels.model",
    "ReadModelRepository": "eventsource.ports.readmodels.repository",
    "Query": "eventsource.ports.readmodels.query",
    "Filter": "eventsource.ports.readmodels.query",
    "ReadModelError": "eventsource.ports.readmodels.exceptions",
    "OptimisticLockError": "eventsource.ports.readmodels.exceptions",
    "ReadModelNotFoundError": "eventsource.ports.readmodels.exceptions",
    "InMemoryReadModelRepository": "eventsource.adapters.memory.readmodels",
    "PostgreSQLReadModelRepository": "eventsource.adapters.postgresql.readmodels",
    "SQLiteReadModelRepository": "eventsource.adapters.sqlite.readmodels",
    "ReadModelProjection": "eventsource.adapters.sql.readmodel_projection",
    "generate_schema": "eventsource.adapters.sql.readmodel_schema",
    "generate_indexes": "eventsource.adapters.sql.readmodel_schema",
    "generate_full_schema": "eventsource.adapters.sql.readmodel_schema",
    "POSTGRESQL_TYPE_MAP": "eventsource.adapters.sql.readmodel_schema",
    "SQLITE_TYPE_MAP": "eventsource.adapters.sql.readmodel_schema",
}


def test_every_legacy_name_is_covered() -> None:
    import eventsource.readmodels as shim

    assert set(shim.__all__) == set(MOVED)


@pytest.mark.parametrize(("name", "new_path"), sorted(MOVED.items()))
def test_legacy_name_resolves_with_a_deprecation_warning(name: str, new_path: str) -> None:
    import eventsource.readmodels as shim

    with pytest.warns(DeprecationWarning, match=new_path):
        assert getattr(shim, name) is not None


def test_dir_lists_every_moved_name() -> None:
    import eventsource.readmodels as shim

    assert set(MOVED) <= set(dir(shim))


def test_unknown_attribute_raises_attribute_error() -> None:
    import eventsource.readmodels as shim

    with pytest.raises(AttributeError):
        shim.NotAThing  # noqa: B018


def test_top_level_projection_comes_from_the_sql_adapter() -> None:
    import eventsource
    from eventsource.adapters.sql.readmodel_projection import ReadModelProjection

    assert eventsource.ReadModelProjection is ReadModelProjection


def test_importing_the_shim_emits_no_warning_by_itself() -> None:
    import importlib

    with warnings.catch_warnings():
        warnings.simplefilter("error", DeprecationWarning)
        importlib.import_module("eventsource.readmodels")

Run: timeout 120 uv run pytest tests/unit/test_readmodels_shim.py -q

Expected: FAIL β€” DID NOT WARN on the parametrized cases (the package re-exports eagerly after A3) and ModuleNotFoundError: No module named 'eventsource.adapters.sql.readmodel_projection' on the top-level test.


git mv src/eventsource/readmodels/in_memory.py  src/eventsource/adapters/memory/readmodels.py
git mv src/eventsource/readmodels/postgresql.py src/eventsource/adapters/postgresql/readmodels.py
git mv src/eventsource/readmodels/sqlite.py     src/eventsource/adapters/sqlite/readmodels.py
git mv src/eventsource/readmodels/schema.py     src/eventsource/adapters/sql/readmodel_schema.py
git mv src/eventsource/readmodels/projection.py src/eventsource/adapters/sql/readmodel_projection.py

No body changes. After A3 these modules already import from eventsource.ports.readmodels.*, so the only edits are:

Keep them lazy (# Import here to avoid circular imports stays): adapters/sql/ importing adapters/postgresql/ and adapters/sqlite/ at module scope would violate the "Infrastructure backends must not import each other" contract in spirit and add two eager sqlalchemy/aiosqlite chains. Verify lint-imports after this step specifically.

git diff -M --stat for this step should show five pure renames plus the small edits above. The A4 reviewer checks exactly that.

src/eventsource/adapters/memory/__init__.py β€” import after locks (alphabetical), "InMemoryReadModelRepository" into __all__ after "InMemoryOutboxRepository"; docstring gains "read model":


from eventsource.adapters.memory.readmodels import InMemoryReadModelRepository

src/eventsource/adapters/postgresql/__init__.py β€” import after outbox, "PostgreSQLReadModelRepository" after "PostgreSQLOutboxRepository":


from eventsource.adapters.postgresql.readmodels import PostgreSQLReadModelRepository

src/eventsource/adapters/sqlite/__init__.py β€” import after outbox, "SQLiteReadModelRepository" after "SQLiteOutboxRepository":


from eventsource.adapters.sqlite.readmodels import SQLiteReadModelRepository

src/eventsource/adapters/sql/__init__.py β€” both new modules, with __all__ re-sorted:


from eventsource.adapters.sql.checkpoints import SQLCheckpointRepository
from eventsource.adapters.sql.dlq import SQLDLQRepository
from eventsource.adapters.sql.projection import DatabaseProjection
from eventsource.adapters.sql.readmodel_projection import ReadModelProjection
from eventsource.adapters.sql.readmodel_schema import (
    POSTGRESQL_TYPE_MAP,
    SQLITE_TYPE_MAP,
    generate_full_schema,
    generate_indexes,
    generate_schema,
)

__all__ = [
    "POSTGRESQL_TYPE_MAP",
    "SQLITE_TYPE_MAP",
    "DatabaseProjection",
    "ReadModelProjection",
    "SQLCheckpointRepository",
    "SQLDLQRepository",
    "generate_full_schema",
    "generate_indexes",
    "generate_schema",
]

src/eventsource/__init__.py line 199:


from eventsource.readmodels import ReadModelProjection

β†’


from eventsource.adapters.sql.readmodel_projection import ReadModelProjection

The comment on line 198 (# ReadModel Projections (Phase 3)) stays. __all__ line 327 is untouched. eventsource.__all__ must be byte-identical to its pre-slice value β€” verify before committing:


git show 8e9ccd4:src/eventsource/__init__.py | grep -n '^__all__' -A 400 > "$CLAUDE_JOB_DIR/tmp/all_before.txt"
grep -n '^__all__' -A 400 src/eventsource/__init__.py > "$CLAUDE_JOB_DIR/tmp/all_after.txt"
diff "$CLAUDE_JOB_DIR/tmp/all_before.txt" "$CLAUDE_JOB_DIR/tmp/all_after.txt" && echo IDENTICAL

Replace the entire contents of src/eventsource/readmodels/__init__.py. Keep the existing module docstring's usage example but update its import line to from eventsource.ports.readmodels import ... / from eventsource.adapters.memory.readmodels import ... so the example is not itself deprecated advice; then append the deprecation notice and the mechanism:


"""Deprecated import path for read-model persistence.

Every name below still resolves, each with a `DeprecationWarning` naming its
new home. This package is removed in 0.8.0.

- `ReadModel`, `Query`, `Filter`, `ReadModelRepository`, `ReadModelError`,
  `OptimisticLockError`, `ReadModelNotFoundError`
  -> `eventsource.ports.readmodels`
- `InMemoryReadModelRepository` -> `eventsource.adapters.memory.readmodels`
- `PostgreSQLReadModelRepository` -> `eventsource.adapters.postgresql.readmodels`
- `SQLiteReadModelRepository` -> `eventsource.adapters.sqlite.readmodels`
- `ReadModelProjection` -> `eventsource.adapters.sql.readmodel_projection`
- `generate_schema`, `generate_indexes`, `generate_full_schema`,
  `POSTGRESQL_TYPE_MAP`, `SQLITE_TYPE_MAP`
  -> `eventsource.adapters.sql.readmodel_schema`

Resolution is lazy: importing this module pulls in no sqlalchemy and no
aiosqlite until a name that needs them is actually read.

Example:
    >>> from uuid import uuid4
    >>> from decimal import Decimal
    >>> from eventsource.ports.readmodels import ReadModel, Query, Filter
    >>> from eventsource.adapters.memory.readmodels import (
    ...     InMemoryReadModelRepository,
    ... )
    >>>
    >>> class OrderSummary(ReadModel):
    ...     order_number: str
    ...     status: str
    ...     total_amount: Decimal
    ...
    >>> repo = InMemoryReadModelRepository(OrderSummary)
    >>> shipped = await repo.find(Query(filters=[Filter.eq("status", "shipped")]))
"""

import importlib
import warnings

_MOVED = {
    "ReadModel": "eventsource.ports.readmodels.model",
    "ReadModelRepository": "eventsource.ports.readmodels.repository",
    "Query": "eventsource.ports.readmodels.query",
    "Filter": "eventsource.ports.readmodels.query",
    "ReadModelError": "eventsource.ports.readmodels.exceptions",
    "OptimisticLockError": "eventsource.ports.readmodels.exceptions",
    "ReadModelNotFoundError": "eventsource.ports.readmodels.exceptions",
    "InMemoryReadModelRepository": "eventsource.adapters.memory.readmodels",
    "PostgreSQLReadModelRepository": "eventsource.adapters.postgresql.readmodels",
    "SQLiteReadModelRepository": "eventsource.adapters.sqlite.readmodels",
    "ReadModelProjection": "eventsource.adapters.sql.readmodel_projection",
    "generate_schema": "eventsource.adapters.sql.readmodel_schema",
    "generate_indexes": "eventsource.adapters.sql.readmodel_schema",
    "generate_full_schema": "eventsource.adapters.sql.readmodel_schema",
    "POSTGRESQL_TYPE_MAP": "eventsource.adapters.sql.readmodel_schema",
    "SQLITE_TYPE_MAP": "eventsource.adapters.sql.readmodel_schema",
}

__all__ = [
    # Base class
    "ReadModel",
    # Protocol
    "ReadModelRepository",
    # Projection integration
    "ReadModelProjection",
    # Query building
    "Query",
    "Filter",
    # Exceptions
    "ReadModelError",
    "OptimisticLockError",
    "ReadModelNotFoundError",
    # In-memory implementation
    "InMemoryReadModelRepository",
    # PostgreSQL implementation
    "PostgreSQLReadModelRepository",
    # SQLite implementation
    "SQLiteReadModelRepository",
    # Schema generation
    "generate_schema",
    "generate_indexes",
    "generate_full_schema",
    "POSTGRESQL_TYPE_MAP",
    "SQLITE_TYPE_MAP",
]


def __getattr__(name: str) -> object:
    try:
        module_name = _MOVED[name]
    except KeyError:
        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from None
    warnings.warn(
        f"eventsource.readmodels.{name} is deprecated; "
        f"import it from {module_name} instead. "
        f"eventsource.readmodels is removed in 0.8.0.",
        DeprecationWarning,
        stacklevel=2,
    )
    return getattr(importlib.import_module(module_name), name)


def __dir__() -> list[str]:
    return sorted(__all__)

__all__ keeps its exact sixteen entries in their exact order and with their existing comments β€” the shim test asserts set equality against _MOVED, and A7's docs reference this list.

The spec is explicit that this file is retargeted, not deleted: it becomes the shim's export-completeness test. Rewrite it so each import goes through the new paths and one case asserts the shim still covers everything:


"""Read-model public surface: new port/adapter paths, plus shim completeness."""

import pytest


def test_port_and_adapter_paths_export_the_public_names() -> None:
    from eventsource.adapters.memory.readmodels import InMemoryReadModelRepository
    from eventsource.ports.readmodels import (
        Filter,
        Query,
        ReadModel,
        ReadModelRepository,
    )

    assert hasattr(ReadModel, "table_name")
    assert hasattr(ReadModel, "field_names")
    assert hasattr(ReadModel, "custom_field_names")
    assert hasattr(ReadModel, "is_deleted")

    assert hasattr(ReadModelRepository, "get")
    assert hasattr(ReadModelRepository, "save")
    assert hasattr(ReadModelRepository, "find")

    q = Query()
    assert hasattr(q, "filters")
    assert hasattr(q, "order_by")
    assert hasattr(q, "limit")

    assert hasattr(Filter, "eq")
    assert hasattr(Filter, "ne")
    assert hasattr(Filter, "gt")
    assert hasattr(Filter, "in_")

    assert hasattr(InMemoryReadModelRepository, "model_class")


def test_legacy_package_still_covers_all_sixteen_names() -> None:
    import eventsource.readmodels

    assert len(eventsource.readmodels.__all__) == 16
    for name in eventsource.readmodels.__all__:
        with pytest.warns(DeprecationWarning):
            assert getattr(eventsource.readmodels, name) is not None

Other files under tests/unit/readmodels/ that import from eventsource.readmodels will now emit DeprecationWarnings. If the project's pytest config turns warnings into errors, retarget those imports onto the new paths in this step β€” check pyproject.toml's [tool.pytest.ini_options] filterwarnings first, and report which files you touched.

In pyproject.toml, add to the "Tier 0 modules must not import sqlalchemy" source_modules, immediately after "eventsource.adapters.memory.locks", (added by A2):


    "eventsource.adapters.memory.readmodels",

If A2 has not yet run, place it after "eventsource.adapters.memory.outbox", instead and let the merge resolve. Nothing else in [tool.importlinter] changes here.


timeout 120 uv run pytest tests/unit/test_readmodels_shim.py tests/unit/readmodels/ -q
timeout 300 uv run pytest tests/integration/readmodels/ -m postgres -q   # needs Docker
uv run ruff check src/eventsource tests --fix && uv run ruff format src/eventsource tests
uv run mypy src/eventsource/ --config-file=pyproject.toml
uv run lint-imports
make check

Acceptance greps:


ls src/eventsource/readmodels/            # exactly: __init__.py
grep -rn "eventsource\.readmodels" src/   # only src/eventsource/readmodels/__init__.py
git diff -M --stat HEAD~0 -- src/eventsource/adapters/  # renames, not rewrites

git add src/eventsource/adapters/ src/eventsource/readmodels/ src/eventsource/__init__.py \
        tests/unit/test_readmodels_shim.py tests/unit/readmodels/ pyproject.toml
git add -u src/eventsource/readmodels/
git commit -m "refactor: move read model adapters into the adapters ring

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"

Acceptance (spec Β§2.8): src/eventsource/readmodels/ contains only __init__.py, which imports no sqlalchemy at module scope; grep -rn "eventsource.readmodels" src/ matches only the shim; eventsource.__all__ byte-identical; the 16 sql_connection call sites now sit under adapters/; make check green; tests/integration/readmodels/ green with Docker up.


Task A5: `ReadModelRepositoryConformance` and de-duplication of the per-backend suites

Spec Β§2.6, Β§2.7 third bullet. Depends on A4.

Files:

Interfaces:

tests/unit/adapters/test_memory_readmodels_conformance.py:


"""Conformance tests for InMemoryReadModelRepository against the port suite."""

from collections.abc import AsyncIterator

import pytest

from eventsource.adapters.memory.readmodels import InMemoryReadModelRepository
from eventsource.testing.conformance_ports import ReadModelRepositoryConformance
from eventsource.testing.conformance_ports._fixtures import ConformanceReadModel


class TestMemoryReadModelRepository(ReadModelRepositoryConformance):
    @pytest.fixture
    async def store(self) -> AsyncIterator[InMemoryReadModelRepository[ConformanceReadModel]]:
        yield InMemoryReadModelRepository(ConformanceReadModel, enable_tracing=False)

tests/unit/adapters/test_sqlite_readmodels_conformance.py:


"""Conformance tests for SQLiteReadModelRepository against the port suite."""

from collections.abc import AsyncIterator

import aiosqlite
import pytest

from eventsource.adapters.sql.readmodel_schema import generate_schema
from eventsource.adapters.sqlite.readmodels import SQLiteReadModelRepository
from eventsource.testing.conformance_ports import ReadModelRepositoryConformance
from eventsource.testing.conformance_ports._fixtures import ConformanceReadModel

pytestmark = pytest.mark.sqlite


class TestSQLiteReadModelRepository(ReadModelRepositoryConformance):
    @pytest.fixture
    async def store(self) -> AsyncIterator[SQLiteReadModelRepository[ConformanceReadModel]]:
        async with aiosqlite.connect(":memory:") as conn:
            await conn.executescript(generate_schema(ConformanceReadModel, dialect="sqlite"))
            await conn.commit()
            yield SQLiteReadModelRepository(conn, ConformanceReadModel, enable_tracing=False)

tests/integration/readmodels/test_postgresql_readmodels_conformance.py:


"""Conformance tests for PostgreSQLReadModelRepository against the port suite."""

from __future__ import annotations

from collections.abc import AsyncIterator
from typing import TYPE_CHECKING

import pytest
import pytest_asyncio
from sqlalchemy import text

from eventsource.adapters.postgresql.readmodels import PostgreSQLReadModelRepository
from eventsource.adapters.sql.readmodel_schema import generate_schema
from eventsource.testing.conformance_ports import ReadModelRepositoryConformance
from eventsource.testing.conformance_ports._fixtures import ConformanceReadModel

if TYPE_CHECKING:
    from sqlalchemy.ext.asyncio import AsyncEngine

pytestmark = [pytest.mark.integration, pytest.mark.postgres]


class TestPostgreSQLReadModelRepository(ReadModelRepositoryConformance):
    @pytest_asyncio.fixture
    async def store(
        self, postgres_engine: AsyncEngine
    ) -> AsyncIterator[PostgreSQLReadModelRepository[ConformanceReadModel]]:
        table = ConformanceReadModel.table_name()
        async with postgres_engine.begin() as conn:
            await conn.execute(text(f"DROP TABLE IF EXISTS {table}"))
            for statement in generate_schema(
                ConformanceReadModel, dialect="postgresql"
            ).split(";"):
                if statement.strip():
                    await conn.execute(text(statement))
        yield PostgreSQLReadModelRepository(
            postgres_engine, ConformanceReadModel, enable_tracing=False
        )
        async with postgres_engine.begin() as conn:
            await conn.execute(text(f"DROP TABLE IF EXISTS {table}"))

Before writing the PostgreSQL binding, read tests/integration/readmodels/conftest.py and use whatever engine fixture it actually provides (it may be named other than postgres_engine, and it may already have a schema-provisioning helper worth reusing). Match the local conventions; the shape above is the contract, not the fixture names.

Also read generate_schema's signature at src/eventsource/adapters/sql/readmodel_schema.py:74 before writing these β€” confirm the keyword is dialect and whether it returns one statement or several, and adjust the provisioning lines accordingly.

Run: timeout 120 uv run pytest tests/unit/adapters/test_memory_readmodels_conformance.py tests/unit/adapters/test_sqlite_readmodels_conformance.py -q

Expected: FAIL at collection β€” ImportError: cannot import name 'ReadModelRepositoryConformance' from 'eventsource.testing.conformance_ports'.

Append to src/eventsource/testing/conformance_ports/_fixtures.py, and extend its module docstring's import list to name eventsource.ports.readmodels:


class ConformanceReadModel(ReadModel):
    """Minimal read model used by `ReadModelRepositoryConformance`.

    Two custom fields only: one text, one integer -- enough to exercise
    filtering, ordering, and update-visibility without depending on any
    dialect's handling of decimals, JSON, or dates.
    """

    name: str = "conformance"
    count: int = 0

with from eventsource.ports.readmodels import ReadModel added to the imports. This keeps the module sqlalchemy-free.

src/eventsource/testing/conformance_ports/readmodels.py. One method per case group from spec Β§2.6; imports limited to eventsource.ports.readmodels, the _fixtures model, pytest and stdlib. No adapter import, no generate_schema import, no dialect knowledge.


"""Conformance suite for the `ReadModelRepository` port.

Subclass and provide a `store` fixture yielding a repository already bound
to `ConformanceReadModel` with its table provisioned -- bindings own
provisioning so this module stays adapter-free and dialect-free.

**Not pinned here**, deliberately: the ordering of `get_many` results (the
Protocol does not guarantee one), the resolution of `updated_at`, and any
dialect-specific type coercion. Those stay in the per-backend test modules.
"""

import asyncio
from abc import ABC, abstractmethod
from uuid import uuid4

import pytest

from eventsource.ports.readmodels import (
    Filter,
    OptimisticLockError,
    Query,
    ReadModelNotFoundError,
    ReadModelRepository,
)
from eventsource.testing.conformance_ports._fixtures import ConformanceReadModel

Repo = ReadModelRepository[ConformanceReadModel]


def _model(name: str = "conformance", count: int = 0) -> ConformanceReadModel:
    return ConformanceReadModel(id=uuid4(), name=name, count=count)


class ReadModelRepositoryConformance(ABC):
    """Conformance suite for `ReadModelRepository` implementations."""

    @abstractmethod
    @pytest.fixture
    def store(self) -> object:
        """Yield a repository bound to `ConformanceReadModel`, table provisioned."""
        raise NotImplementedError

    async def test_save_then_get_round_trips(self, store: Repo) -> None:
        model = _model(name="alpha", count=3)
        await store.save(model)
        loaded = await store.get(model.id)
        assert loaded is not None
        assert loaded.id == model.id
        assert loaded.name == "alpha"
        assert loaded.count == 3

    async def test_get_of_an_absent_id_returns_none(self, store: Repo) -> None:
        assert await store.get(uuid4()) is None

    async def test_save_upserts_and_advances_updated_at(self, store: Repo) -> None:
        model = _model(name="before")
        await store.save(model)
        first = await store.get(model.id)
        assert first is not None

        await asyncio.sleep(0.01)
        first.name = "after"
        await store.save(first)

        second = await store.get(model.id)
        assert second is not None
        assert second.name == "after"
        assert second.updated_at >= first.updated_at
        assert await store.count() == 1

    async def test_get_many_skips_missing_ids(self, store: Repo) -> None:
        present = _model(name="present")
        await store.save(present)
        found = await store.get_many([present.id, uuid4()])
        assert [m.id for m in found] == [present.id]

    async def test_save_many_persists_every_model(self, store: Repo) -> None:
        models = [_model(name=f"m{i}", count=i) for i in range(3)]
        await store.save_many(models)
        for model in models:
            assert await store.get(model.id) is not None

    async def test_exists_reflects_presence(self, store: Repo) -> None:
        model = _model()
        assert await store.exists(model.id) is False
        await store.save(model)
        assert await store.exists(model.id) is True

    async def test_delete_returns_whether_a_row_was_removed(self, store: Repo) -> None:
        model = _model()
        await store.save(model)
        assert await store.delete(model.id) is True
        assert await store.get(model.id) is None
        assert await store.delete(model.id) is False

    async def test_soft_delete_hides_from_get_but_not_from_get_deleted(
        self, store: Repo
    ) -> None:
        model = _model()
        await store.save(model)
        assert await store.soft_delete(model.id) is True
        assert await store.get(model.id) is None
        recovered = await store.get_deleted(model.id)
        assert recovered is not None
        assert recovered.id == model.id

    async def test_restore_makes_a_soft_deleted_model_visible_again(
        self, store: Repo
    ) -> None:
        model = _model()
        await store.save(model)
        await store.soft_delete(model.id)
        assert await store.restore(model.id) is True
        assert await store.get(model.id) is not None

    async def test_find_deleted_returns_only_soft_deleted_models(self, store: Repo) -> None:
        live = _model(name="live")
        gone = _model(name="gone")
        await store.save_many([live, gone])
        await store.soft_delete(gone.id)
        assert [m.id for m in await store.find_deleted()] == [gone.id]

    async def test_find_filters_on_equality(self, store: Repo) -> None:
        alpha = _model(name="alpha")
        beta = _model(name="beta")
        await store.save_many([alpha, beta])
        found = await store.find(Query(filters=[Filter.eq("name", "alpha")]))
        assert [m.id for m in found] == [alpha.id]

    async def test_find_orders_and_limits(self, store: Repo) -> None:
        await store.save_many([_model(name=f"m{i}", count=i) for i in range(3)])
        found = await store.find(
            Query(order_by="count", order_direction="desc", limit=2)
        )
        assert [m.count for m in found] == [2, 1]

    async def test_find_excludes_soft_deleted_models(self, store: Repo) -> None:
        live = _model(name="live")
        gone = _model(name="gone")
        await store.save_many([live, gone])
        await store.soft_delete(gone.id)
        assert [m.id for m in await store.find()] == [live.id]

    async def test_count_with_and_without_filters(self, store: Repo) -> None:
        await store.save_many([_model(name="alpha"), _model(name="beta")])
        assert await store.count() == 2
        assert await store.count(Query(filters=[Filter.eq("name", "alpha")])) == 1

    async def test_truncate_returns_the_count_and_empties_the_table(
        self, store: Repo
    ) -> None:
        live = _model(name="live")
        gone = _model(name="gone")
        await store.save_many([live, gone])
        await store.soft_delete(gone.id)
        assert await store.truncate() == 2
        assert await store.count() == 0
        assert await store.get_deleted(gone.id) is None

    async def test_save_with_version_check_increments_version(self, store: Repo) -> None:
        model = _model()
        await store.save(model)
        loaded = await store.get(model.id)
        assert loaded is not None
        before = loaded.version
        loaded.name = "bumped"
        await store.save_with_version_check(loaded)
        after = await store.get(model.id)
        assert after is not None
        assert after.version == before + 1

    async def test_save_with_version_check_rejects_a_stale_version(
        self, store: Repo
    ) -> None:
        model = _model()
        await store.save(model)
        first = await store.get(model.id)
        second = await store.get(model.id)
        assert first is not None and second is not None

        first.name = "winner"
        await store.save_with_version_check(first)

        second.name = "loser"
        with pytest.raises(OptimisticLockError):
            await store.save_with_version_check(second)

    async def test_save_with_version_check_rejects_an_absent_model(
        self, store: Repo
    ) -> None:
        with pytest.raises(ReadModelNotFoundError):
            await store.save_with_version_check(_model())


__all__ = ["ReadModelRepositoryConformance"]

Before finalizing, read the three adapters' actual semantics for truncate (does its return count include soft-deleted rows?), save_with_version_check (does it bump version itself or expect the caller to?), and ReadModel.version's default. The spec's Β§2.6 list is the required coverage; the exact assertions must match what all three adapters honestly do today, since this is a pure structural slice and no adapter behavior changes here. If two adapters genuinely disagree on a case, that is a finding, not a thing to weaken the suite around β€” report it and drop the case rather than writing an assertion that hides the divergence.

In src/eventsource/testing/conformance_ports/__init__.py: import (alphabetically, after outbox, before snapshots), add "ReadModelRepositoryConformance" to __all__, and add it to the docstring's suite list.


from eventsource.testing.conformance_ports.readmodels import ReadModelRepositoryConformance

Delete from tests/unit/readmodels/test_in_memory.py, test_postgresql.py, and test_sqlite.py only the cases the suite now covers. Keep everything backend-specific: SQLite TEXT/JSON coercion, PostgreSQL JSONB behavior, connection/engine handling, __repr__, model_class, clear() (memory-only), tracing assertions.

Working method β€” for each candidate deletion, name the suite method that covers it. Write that mapping into the commit message body as a deleted -> covered by list. The A5 reviewer's stated focus is exactly this: that the deleted cases are genuinely covered and not merely dropped. If you cannot name a covering suite method for a case, keep the case.

test_soft_delete.py and test_optimistic_locking.py are cross-cutting files that assert the same semantics across backends; the suite now covers their core. Reduce them the same way β€” by named mapping β€” or leave them entirely if the mapping is not clean. Both outcomes are acceptable; a silent deletion is not.


timeout 120 uv run pytest tests/unit/adapters/test_memory_readmodels_conformance.py \
    tests/unit/adapters/test_sqlite_readmodels_conformance.py tests/unit/readmodels/ -q
timeout 300 uv run pytest tests/integration/readmodels/ -m postgres -q   # needs Docker
uv run ruff check src/eventsource tests --fix && uv run ruff format src/eventsource tests
uv run mypy src/eventsource/ --config-file=pyproject.toml
uv run lint-imports
make check

Confirm the suite is adapter-free before committing:


grep -n "adapters" src/eventsource/testing/conformance_ports/readmodels.py   # no output

git add src/eventsource/testing/conformance_ports/ tests/unit/adapters/ \
        tests/integration/readmodels/ tests/unit/readmodels/
git commit -m "test: add read model repository conformance suite

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"

Acceptance (spec Β§2.8): ReadModelRepositoryConformance passes against all three adapters; the suite file imports no adapter; coverage does not drop for the three repository modules; make check green.


Task A6: move `engine.py` to `adapters/_sql/engine.py`

Spec Β§3 in full. Chain root, independent of A1–A5 and A7-blocking only.

Files:

Interfaces:

Append to tests/unit/test_engine.py:


def test_module_lives_under_sql_adapters():
    """`create_async_engine` is adapter-ring content (ADR 0029).

    It constructs a SQLAlchemy AsyncEngine and registers dialect-specific
    driver listeners, so it belongs under `adapters/`. `_sql/` rather than
    `sql/` because `adapters/_sql/__init__.py` is import-free while
    `adapters/sql/__init__.py` eagerly imports three modules, one of which
    reaches into `application/projections/` -- the front-door import chain
    must not widen while relocating the module that chain names.
    """
    assert create_async_engine.__module__ == "eventsource.adapters._sql.engine"

Run: timeout 120 uv run pytest tests/unit/test_engine.py -q -k module_lives

Expected: FAIL β€” AssertionError: assert 'eventsource.engine' == 'eventsource.adapters._sql.engine'.

(This is a pure relocation with no behavioral deficiency to write a failing test against, so the red test pins the ruling itself.)


git mv src/eventsource/engine.py src/eventsource/adapters/_sql/engine.py

No code edits. The only change to the file is one sentence appended to the module docstring, after the "See https://docs.sqlalchemy.org/..." line:


Why ``adapters/_sql/`` and not ``adapters/sql/``: ``adapters/_sql/__init__.py``
is import-free, while ``adapters/sql/__init__.py`` eagerly imports
``checkpoints``, ``dlq``, and ``projection``, and ``projection`` reaches into
``application/projections/``. Placing a leaf engine factory there would drag
the application projection ring into the front-door import chain that
``docs/core-surface.md``'s finding 12 exists to narrow. The public name is and
remains ``eventsource.create_async_engine``; the module path was never the
advertised surface. See ADR 0029.

SQLITE_PRAGMAS, the three module-level helpers, _configure_sqlite, create_async_engine, and __all__ are untouched.

src/eventsource/__init__.py line 103:


from eventsource.engine import create_async_engine

β†’


from eventsource.adapters._sql.engine import create_async_engine

The comment on line 102 stays. __all__ line 234 is untouched.

Do not add anything to src/eventsource/adapters/_sql/__init__.py.

The A6 reviewer's stated focus is that all four were updated, not just pyproject.toml.

  1. pyproject.toml line 204, in [tool.mutmut] only_mutate: "src/eventsource/engine.py", β†’ "src/eventsource/adapters/_sql/engine.py",
  2. cosmic-ray/engine.toml line 20: module-path = "src/eventsource/engine.py" β†’ module-path = "src/eventsource/adapters/_sql/engine.py" Its test-command already points at tests/unit/test_engine.py, which does not move β€” leave it. The header comment at line 5 says "the shape of engine.py's @event.listens_for listeners"; that prose is still accurate, leave it.
  3. scripts/_mutmut_configure.py line 24, in MODULES: ``python "engine": ("src/eventsource/adapters/_sql/engine.py", "tests/unit/test_engine.py"), ` The selector key "engine" is kept. Do not touch the dialect, checkpoint, and json entries β€” three of them name src/eventsource/repositories/...`, a package deleted in an earlier slice, and repairing that is out of scope. Note it in your report.
  4. scripts/mutation.sh line 9, a usage comment: # scripts/mutation.sh engine # just src/eventsource/engine.py β†’ ... # just src/eventsource/adapters/_sql/engine.py Lines 24 and 48 (VALID=(engine dialect json checkpoint dlq all) and the for m in engine dialect json loop) contain selector names, not paths β€” the spec names them as needing a path update; they do not have one. Leave both unchanged and flag the discrepancy in your report.

Verify the selector still resolves:


uv run python scripts/_mutmut_configure.py engine && grep -n "only_mutate" -A 3 pyproject.toml
git checkout pyproject.toml   # _mutmut_configure rewrites in place; restore, then re-apply step 4.1

Better: do this check on a copy under $CLAUDE_JOB_DIR/tmp rather than mutating the shared pyproject.toml.

tests/unit/test_engine.py β€” two lines:

Nothing else in tests/unit/test_engine.py changes other than Step 1's appended test. That is the behavior-preservation evidence for the move.

Every other importer takes the docs-recommended path, from eventsource import create_async_engine:

(The spec says "five adapter/repository test modules"; the actual count at 8e9ccd4 is six besides conftest.py and test_engine.py. Use the list above.)


timeout 120 uv run pytest tests/unit/test_engine.py -q
timeout 120 uv run pytest tests/unit/adapters/ tests/unit/ -q
uv run ruff check src/eventsource tests --fix && uv run ruff format src/eventsource tests
uv run mypy src/eventsource/ --config-file=pyproject.toml
uv run lint-imports
make check

Acceptance greps:


test ! -e src/eventsource/engine.py && echo "deleted"
grep -rn "eventsource\.engine\|eventsource/engine\.py" src/ tests/ scripts/ pyproject.toml cosmic-ray/
# expected: no output. (docs/ still matches ADR 0008's historical note, by design.)
git diff --stat tests/unit/test_engine.py   # small: 2 import lines + 1 appended test

git add src/eventsource/adapters/_sql/engine.py src/eventsource/__init__.py \
        pyproject.toml cosmic-ray/engine.toml scripts/_mutmut_configure.py scripts/mutation.sh \
        tests/unit/test_engine.py tests/conftest.py tests/unit/adapters/ \
        tests/integration/repositories/test_dlq.py \
        docs/development/mutation-testing.md docs/core-surface.md \
        docs/adrs/0008-mutation-testing-tool-selection.md
git add -u src/eventsource/
git commit -m "refactor: move engine factory to adapters/_sql

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"

Acceptance (spec Β§3.6): src/eventsource/engine.py gone; the grep above empty except ADR 0008's historical note; eventsource.create_async_engine behaves identically and tests/unit/test_engine.py passes with only its import lines changed; scripts/mutation.sh engine resolves against the new path; make check green.


Task A7: ADR 0029, CHANGELOG, the new import-linter contract, and the documentation sweep

Spec Β§4 in full, plus Β§2.4's follow-up backlog item and Β§3.5's lazy-__init__ note. Depends on A1–A6. This task writes no source code and moves no module.

Files:

Interfaces: none produced or consumed. This task documents the six that preceded it.

docs/adrs/0029-locks-readmodels-and-engine-rings.md. Match the house ADR format β€” read docs/adrs/0026-*.md for the current shape (Status / Context / Decision / Consequences / Alternatives Considered) before writing. Required content, per spec Β§4.1:

Then: add the 0029 row to docs/adrs/index.md (match the surrounding rows' format), and add an "Amended by ADR 0029" pointer to ADR 0023's Status section. Do not rewrite ADR 0023's Decision β€” ADR bodies are immutable records.

Read the existing "Projection persistence re-homed" and "Outbox ring migration" entries first and match their shape exactly (each is a paragraph plus a from→to table plus the statement that top-level eventsource imports are unaffected).

Added:

Changed:

Deprecated:

There is no Removed section for this slice: deleting src/eventsource/engine.py removes no public name and is covered under Changed.

Add to pyproject.toml, after the existing "Application ring must not import adapters" contract:


[[tool.importlinter.contracts]]
name = "Ports must not import adapters, application, or bus"
type = "forbidden"
source_modules = ["eventsource.ports"]
forbidden_modules = [
    "eventsource.adapters",
    "eventsource.application",
    "eventsource.bus",
    "eventsource.migration",
]

Rationale to record in the trailing comment block: slice A created the first port with a sibling that moved to adapters/ (ports/readmodels/ and adapters/sql/readmodel_schema.py), and an accidental from eventsource.adapters.sql.readmodel_schema import generate_schema inside ports/readmodels/model.py would be a real regression the existing sqlalchemy-only contract cannot catch β€” readmodel_schema.py imports no sqlalchemy.

Two comments to add, matching the style of the existing explanatory block at the end of the [tool.importlinter] section:

  1. On the Tier-0 contract: eventsource.readmodels.schema lost its "must not import sqlalchemy" guard by design when it became eventsource.adapters.sql.readmodel_schema (ADR 0029 Β§2.3) β€” the guard asserted the wrong property about a module that emits dialect-specific DDL. The guard was not silently dropped.
  2. On "Application ring must not import adapters": the eventsource.locks entry in forbidden_modules stays correct while the shim exists β€” the shim resolves to adapters β€” and is deleted when the shim is removed in 0.8.0.

"Infrastructure backends must not import each other" needs no change: it names the adapters.postgresql / adapters.sqlite / adapters.memory packages, so the new locks.py and readmodels.py modules inside them are covered automatically.

Run uv run lint-imports after this step. If the new contract fails, a port is importing outward and that is a real finding β€” report it, do not weaken the contract.

Rewrite the import-path sections at :16, :133, :154-168, :189, :197, :210, and every code sample, onto eventsource.ports.locks / eventsource.adapters.postgresql.locks / eventsource.exceptions. Two constraints:

Mention the eventsource.locks deprecation and the 0.8.0 removal inline.

docs/architecture.md, docs/guides/distributed-locks.md, docs/guides/live-migration.md, docs/guides/error-handling.md, docs/explanation/schema-design.md, docs/development/testing.md, docs/index.md β€” import-path sweep. docs/guides/error-handling.md also needs the EventSourceError rebasing noted if it documents the lock exceptions' hierarchy.

Gate:


grep -rn "eventsource\.locks\|eventsource\.readmodels\|eventsource\.engine" docs/

must return only: the ADRs (historical), the migration/deprecation notes, and docs/superpowers/ (specs and plans, which are historical records β€” do not edit them).

mkdocs.yml nav: no new pages are added by this slice, so nav is unchanged. Still run the nav-completeness check β€” a strict build does not catch omissions:


uv run mkdocs build --strict

uv run lint-imports
uv run mkdocs build --strict
make check

Coverage check of spec Β§1–§4 before committing β€” for each requirement, name the task that landed it. Anything unmapped is a gap: report it rather than absorbing it into A7.


git add docs/adrs/ CHANGELOG.md pyproject.toml docs/core-surface.md docs/api/ \
        docs/architecture.md docs/guides/ docs/explanation/schema-design.md \
        docs/development/testing.md docs/index.md BACKLOG.md
git commit -m "docs: adr 0029 and documentation for structure slice a

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"

Acceptance: ADR 0029 exists and is indexed; ADR 0023 carries an "Amended by" pointer; CHANGELOG has the four sections above with the exception rebasing called out separately; the new import-linter contract passes; the docs grep gate is clean; mkdocs build --strict succeeds; make check green.


Reviewer focus per task (spec Β§5)

Task What the reviewer checks first
A1 The suite file imports no adapter; InMemoryLockManager's docstring leads with what it does not guarantee; the two knowingly-temporary imports are reported, not hidden
A2 git diff tests/locks/test_postgresql_locks.py shows only import lines changed; the exception rebasing is widening-only; the shim defines __dir__
A3 ports/readmodels/ imports no sqlalchemy in a fresh interpreter; eventsource.readmodels still exports all sixteen names
A4 git diff -M --stat shows pure renames β€” no moved module body changed apart from imports; eventsource.__all__ byte-identical; the two lazy imports in readmodel_projection.py stayed lazy
A5 The deleted per-backend cases are genuinely covered by the suite and not merely dropped β€” check the deleted -> covered by mapping in the commit message
A6 All four mutation-config locations updated (pyproject.toml, cosmic-ray/engine.toml, scripts/_mutmut_configure.py, scripts/mutation.sh), not just pyproject.toml
A7 Every Β§1–§4 spec requirement maps to a landed task; ADR 0023's Decision was not retro-edited; the two recorded exceptions are labeled as exceptions