PEP 695 Type-Parameter Syntax Migration 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: Convert the library's 15 remaining pre-PEP-695 generic declarations to Python 3.13 native type-parameter syntax, then remove the three staged ruff ignores (UP046, UP047, UP040) that PR #104 left behind.

Architecture: PEP 695 scopes type parameters to the declaration that uses them, replacing module-level TypeVar objects. Each conversion is local: class Foo(Generic[T]) → class Foo[T], def f(x: T) -> T → def fT -> T, X: TypeAlias = ... → type X = .... Bounds move inline (TypeVar("T", bound=B) → [T: B]); PEP 696 defaults move inline too (TypeVar("T", default=object) → [T = object], native in 3.13).

The one non-mechanical consequence: TState is not a private helper — it is exported from eventsource.__all__, eventsource.domain.__all__, the lazy-import map, and documented on docs/api/types.md. Once AggregateRoot and DeciderAggregate scope their own parameters, no library code references it. This plan deletes it rather than leaving an exported TypeVar the library itself no longer uses. That is a breaking change, taken under the pre-1.0 NO-SHIMS policy, and it is the reason this wave carries an ADR.

Tech Stack: Python 3.13, pydantic v2, pytest, uv, ruff, import-linter, mypy strict.

Global Constraints

Conversion Inventory

All 15 sites, grouped by the task that owns them:

Task File Site Rule
1 domain/aggregate.py:41 AggregateRoot(Generic[TState], ABC) UP046
1 domain/decider.py:22 DeciderAggregate(AggregateRoot[TState], Generic[TState, TCommand]) UP046
1 domain/event_registry.py:272,284 register_event overloads UP047
1 domain/types.py:21 TState — deleted, see Task 1 —
2 application/aggregates/repository.py:47 AggregateRepository UP046
2 application/aggregates/tenant_repository.py:28 TenantAwareRepository UP046
2 application/projections/base.py:61 TenantFilter type alias UP040
2 application/subscriptions/retry.py:256 retry_async UP047
3 adapters/memory/readmodels.py:33 InMemoryReadModelRepository UP046
3 adapters/postgresql/readmodels.py:38 PostgreSQLReadModelRepository UP046
3 adapters/sql/readmodel_projection.py:36 ReadModelProjection UP046
3 adapters/sqlite/readmodels.py:51 SQLiteReadModelRepository UP046
4 testing/builder.py:29 EventBuilder UP046
4 testing/bdd.py:158 then_event_published UP047
4 bench/adapters/base.py:16 BenchAdapter UP046

Not in scope: ports/readmodels/repository.py:20 declares TModel for a Protocol; domain/decorators.py:23 declares F bound to Callable; neither is flagged by ruff and neither is touched. Variance: no TypeVar in this repo declares covariant= or contravariant=, so there is no explicit variance to preserve. mypy infers variance for PEP 695 parameters; mypy --strict passing is the acceptance signal.


Task 1: Convert the domain ring and retire `TState`

Files:

Interfaces:

class AggregateRoot(Generic[TState], ABC) → class AggregateRootTState: BaseModel. Remove the TState import from domain.types. Leave TEvent at module scope — create_event uses it and is not in this task's inventory; convert it only if ruff still flags it after your change.

class DeciderAggregate(AggregateRoot[TState], Generic[TState, TCommand]) → class DeciderAggregateTState: BaseModel, TCommand = object. Delete the module-level TCommand = TypeVar("TCommand", default=object) and the now-unused TState re-import from aggregate.

Verify the default survives — add to tests/unit/domain/test_decider.py (or the nearest existing decider test module) a test that subscripts both arities and asserts construction works:


def test_decider_aggregate_accepts_one_and_two_parameter_subscripts() -> None:
    """The PEP 696 default on TCommand keeps the single-parameter form valid."""
    assert DeciderAggregate[CounterState] is not None
    assert DeciderAggregate[CounterState, int] is not None

Both overloads at lines 272 and 284 take type parameters. The module-level TEvent (line 52) stays only if another declaration still uses it — check with grep -n TEvent src/eventsource/domain/event_registry.py after converting, and delete it if orphaned.

Remove the definition, then remove it from:

If domain/types.py is left with no TypeVar usage, drop the TypeVar and BaseModel imports too.

This is the step that prior waves kept missing. Run it and act on every hit — do not defer to the final review:


grep -rn "TState" --include='*.py' --include='*.md' src tests bench docs

docs/api/types.md documents TState as public API; docs/api/index.md, docs/core-surface.md, docs/architecture.md, and several tutorials/guides reference it. Update prose to describe the inline [TState: BaseModel] form instead. If docs/api/types.md autodocs the symbol via a mkdocstrings ::: directive, that directive must be removed or the strict docs build fails — verify with uv run mkdocs build --strict before committing. Do not update docs/superpowers/plans/ or docs/superpowers/specs/: those are historical records of prior waves.


uv run pytest tests/unit/domain/ -q
uv run ruff check src tests && uv run mypy src/eventsource/ && uv run lint-imports
uv run mkdocs build --strict

Commit: refactor: convert domain ring to pep 695 type parameters


Task 2: Convert the application ring

Files:

Interfaces:

Both declare an identical TAggregate = TypeVar("TAggregate", bound="AggregateRoot[Any]"). The bound is a string forward reference; inline it as [TAggregate: AggregateRoot[Any]]. PEP 695 bounds are lazily evaluated, so the quotes are no longer needed — but only drop them if AggregateRoot is actually imported at runtime in that module (check for a TYPE_CHECKING guard; if the import is guarded, keep the bound as a string).

TenantFilter: TypeAlias = ... → type TenantFilter = .... Note that type aliases are lazily evaluated and are not valid in runtime positions such as isinstance — grep for TenantFilter across src and tests and confirm every use is annotation-only before converting.

def retry_asyncT. Delete the module-level T = TypeVar("T") if orphaned.


uv run pytest tests/unit/application/ -q
uv run ruff check src tests && uv run mypy src/eventsource/ && uv run lint-imports

Commit: refactor: convert application ring to pep 695 type parameters


Task 3: Convert the adapters ring

Files:

Interfaces:

Each declares a local TModel with a bound (ReadModel in three, _BaseReadModel in sqlite). Inline each as [TModel: ReadModel] / [TModel: _BaseReadModel] and delete the module-level declaration.

These classes implement the ReadModelRepository protocol from ports. Converting the concrete class's parameter does not change its protocol conformance — but mypy is the check, so run it before assuming.


uv run pytest tests/unit/adapters/ -q
uv run ruff check src tests && uv run mypy src/eventsource/ && uv run lint-imports

Commit: refactor: convert adapters ring to pep 695 type parameters


Task 4: Convert the testing helpers and the benchmark harness

Files:

Interfaces:

bdd.py declares two TypeVars (TAggregate, TEvent) at module scope but only then_event_published is flagged. Convert that function, then check whether TAggregate and TEvent still have other users in the module — delete only what is orphaned.

EventBuilder is a plain generic class (not a pydantic model), so class EventBuilder[TEvent: DomainEvent]: is a direct swap.

BenchAdapter(Generic[T]) → BenchAdapter[T]. bench/ is linted (known-first-party includes it) but not covered by the test suite; verify with uv run ruff check bench && uv run mypy bench if the repo's mypy config includes bench — if it does not, ruff plus an import smoke check is sufficient.


uv run pytest tests/unit/testing/ -q
uv run python -c "import bench.adapters.base"
uv run ruff check src tests bench && uv run mypy src/eventsource/

Commit: refactor: convert testing helpers and bench harness to pep 695 type parameters


Task 5: Drop the staged ruff ignores and record the decision

Files:

Interfaces:

Delete the four-line staging comment and the UP046 / UP047 / UP040 entries from [tool.ruff.lint] ignore in pyproject.toml. E501 stays. Then:


uv run ruff check src tests bench

This must be clean. If any violation remains, it is a site Tasks 1-4 missed — fix it here rather than re-adding the ignore.

Follow the format of docs/adrs/0044-*.md. It must record:

Add the pointer row to docs/adrs/index.md, matching the existing table's column layout exactly.

Add to the Unreleased section. The TState removal goes under a Breaking heading (create it if the section lacks one), phrased for a consumer: what broke, and the one-line fix.


uv run mkdocs build --strict
make check

Commit: docs: adr 0045 and changelog for pep 695 migration


Definition of Done