specx-add-infrastructure-adapter

name	specx-add-infrastructure-adapter
description	Add technical infrastructure adapters for specx core scopes. Use when implementing SQLAlchemy repositories and Alembic-backed persistence, Redis stores, HTTP/network clients, file or queue adapters, unit-of-work implementations, gateway implementations for external APIs or SDKs such as OpenAI, or explicit `diwire` bindings for core scope repository and gateway ports.

specx Add Infrastructure Adapter

Use this skill whenever code talks to external systems. Read references/adapter.md before writing adapters.

Workflow

1. Define or reuse a repository under repositories/ for owned persistence. Repository ports inherit BaseRepository and mark required methods with @abstractmethod.
2. Define or reuse a gateway under gateways/ for outbound business capabilities to external systems such as OpenAI, payments, email, queues, or external HTTP APIs. Gateway ports inherit BaseGateway, mark required methods with @abstractmethod, declare external effects, and do not return entities.
3. Put concrete implementations under core/<scope>/infrastructure/<technology>/.
4. Inject external clients, session factories, Redis clients, SDK clients, or project-owned client factories. Do not hide client construction inside business methods. Generated HTTP adapters use httpx2, imported from the httpx2 namespace; do not generate new legacy httpx imports.
5. A bounded short-lived client factory may stay beside its scope adapter. Put every app-owned pooled client factory or wrapper under top-level infrastructure/<technology>/, even with only one current consumer.
6. Give long-lived app-owned infrastructure resources an explicit async close() method; FastAPI lifecycle owns calling it on shutdown.
7. Keep technical query/request code in infrastructure.
8. Repositories may return entities. Gateways must not return entities; return DTOs, primitives, enums, or explicit result objects. Do not return ORM models or SDK response objects to core.
9. Translate low-level exceptions into core exceptions only when callers need to handle them. Catch narrow driver or SDK exceptions, preserve the cause, and never expose raw provider messages, SQL, parameters, bodies, or URLs.
10. For transactional persistence, implement an active UnitOfWork and a UnitOfWorkManager; register the manager, not repositories, active UoWs, or UoW providers for use-case injection.
11. Register adapter bindings in private _register_dependencies(...) inside ioc/container.py. Register every technical resource once at its owner boundary and close that same app-scoped instance from lifecycle.
12. Add focused integration tests only when the adapter has meaningful project-owned behavior to protect; do not add generic CRUD or upstream library tests just because an adapter file exists.
13. For SQLAlchemy adapters, add or update Alembic migrations with $specx-sqlalchemy-migrations.

Logging is top-level runtime infrastructure, not a core-scope adapter. Put stdlib logging setup in infrastructure/logging/configurator.py with a LoggingConfigurator that inherits BaseConfigurator; do not create gateway ports or injected logger bindings for it.

For /readyz, implement required dependency checks as core/health gateway adapters, for example core/health/infrastructure/sqlalchemy/readiness_check_gateway.py, and bind them to ReadinessCheckGateway in ioc/container.py. Bound every dependency check with a short application timeout and return only a non-sensitive core status.

Code Style

Use blank lines as logical separators in all code. Keep related statements together, but separate independent setup, action, assertion, response, branch, and transformation groups so long blocks stay readable.

References

• references/adapter.md - adapter layout, port binding, SQLAlchemy/UoW, Redis, HTTP client, migration, and test patterns.