sqlphilosophy 0.1.6__tar.gz → 0.1.9__tar.gz

{sqlphilosophy-0.1.6/src/sqlphilosophy.egg-info → sqlphilosophy-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlphilosophy
-Version: 0.1.6
+Version: 0.1.9
 Summary: Portable SQLAlchemy repository kit: sync and async CRUD, statement builders, sort/pagination, and SQL helpers.
 Author-email: Josh Martin <denverprogrammer@gmail.com>
 License-Expression: MIT
@@ -31,7 +31,7 @@ Requires-Dist: aiosqlite>=0.20; extra == "dev"
 Requires-Dist: greenlet>=3.0; extra == "dev"
 Requires-Dist: build>=1.2; extra == "dev"
 Requires-Dist: twine>=5; extra == "dev"
-Requires-Dist: flake8>=7; extra == "dev"
+Requires-Dist: ruff>=0.15; extra == "dev"
 Requires-Dist: mypy>=1.11; extra == "dev"
 Requires-Dist: bandit>=1.7; extra == "dev"
 Requires-Dist: types-greenlet>=3.0; extra == "dev"
@@ -45,22 +45,34 @@ Portable SQLAlchemy repository kit: sync and async CRUD, fluent statement builde
 |---|---|
 | **PyPI** | [`sqlphilosophy`](https://pypi.org/project/sqlphilosophy/) |
 | **GitHub** | [SignalSafeSoftware/sqlphilosophy](https://github.com/SignalSafeSoftware/sqlphilosophy) |
-| **Import** | `sqlphilosophy` (explicit submodules — no root re-exports) |
+| **Import** | `sqlphilosophy` (`__version__` only) — use explicit submodules for APIs |
 | **Python** | 3.12+ |
 | **License** | MIT — see [LICENSE](./LICENSE) |
 
+## Documentation
+
+| Resource | Description |
+|----------|-------------|
+| [Repository guide](./docs/repository-guide.md) | Entry point: overview, transaction model, links to usage pages |
+| [Usage examples](./docs/usage/) | Focused sync/async code examples by feature area |
+| [Strongly typed repositories](./docs/usage/strongly-typed-repositories.md) | Typed subclasses, factories, protocols, and service patterns |
+| [Before/after SQLAlchemy](./docs/usage/before-after-sqlalchemy.md) | Migration examples: direct SQLAlchemy vs repository-centered code |
+| [Feature matrix](./docs/feature-matrix.md) | Full sync/async capability map |
+| [Typed repository (sync)](./docs/examples/typed_repository_sync.py) | Runnable factory + domain repo example |
+| [Typed repository (async)](./docs/examples/typed_repository_async.py) | Async counterpart |
+
 ## What this package does
 
 - **Repository pattern** for a single mapped model (`BaseRepository`, `AsyncBaseRepository`).
 - **Fluent query builders** with pagination/sort (`StatementQueryBuilder`, `ListQuery`, `SortConfig`).
-- **SQL helpers** for row mapping, partial updates, filters, and developer-defined raw SQL fragments.
+- **SQL helpers** for row mapping, partial updates, and developer-defined fragments via **`sqlphilosophy.trusted_sql`**.
 - **Optional audit listeners** and timestamp mixins.
 
 ## What this package does not do
 
 - Migrations, schema design, or connection pooling configuration.
 - Authorization, multi-tenant isolation, or query sandboxing.
-- Automatic commits for normal CRUD — see [Transaction ownership](#transaction-ownership) below.
+- Automatic commits for normal CRUD — see [Transaction ownership](#transaction-ownership).
 
 ## Install
 
@@ -76,7 +88,7 @@ pip install sqlphilosophy[async]
 
 Requires Python 3.12+ and SQLAlchemy 2.x.
 
-## Full example (sync model + session)
+## Quick start (sync)
 
 ```python
 from sqlalchemy import String, create_engine
@@ -102,105 +114,53 @@ SessionLocal = sessionmaker(bind=engine, expire_on_commit=False)
 
 with SessionLocal() as session:
     repo = BaseRepository(Widget, session)
-    widget = repo.create(name="alpha")  # stages + flush; does not commit
+    repo.create(name="alpha")  # stages + flush; does not commit
     session.commit()
 
-    page = repo.statement().fetch_page(ListQuery.from_page(page=1, size=20))
-    assert page.total >= 1
+    rows, total = repo.statement().fetch_page(ListQuery.from_page(page=1, size=20))
+    assert total >= 1
 ```
 
-**Async:** swap `Session` → `AsyncSession`, `BaseRepository` → `AsyncBaseRepository` from `sqlphilosophy.aio.repository`, and `await` repository methods.
+**Async:** use `AsyncSession`, `AsyncBaseRepository` from `sqlphilosophy.aio.repository`, and `await` on repository/builder terminals. See the [repository guide](./docs/repository-guide.md).
 
 ## Package layout
 
 | Module | Contents |
 |--------|----------|
-| `sqlphilosophy.types` | Portable typing aliases (`RowMapping`, `PrimaryKey`, `SqlFilter`, …) |
-| `sqlphilosophy.sql` | Row mapping helpers, partial updates, Core table helpers, filter builders |
-| `sqlphilosophy.sorting` | `ListQuery`, `SortConfig`, `SortSpec`, pagination/sort resolution |
-| `sqlphilosophy.sync` | Sync `BaseRepository`, `StatementQueryBuilder`, `RepositoryFactory` protocol |
-| `sqlphilosophy.aio` | Async `AsyncBaseRepository`, `AsyncStatementQueryBuilder`, `AsyncRepositoryFactory` |
-| `sqlphilosophy.audit` | Optional SQLAlchemy audit listeners and timestamp mixins |
-
-## Sync usage
-
-```python
-from sqlalchemy.orm import Session
-
-from sqlphilosophy.sorting import ListQuery, SortConfig, SortSpec
-from sqlphilosophy.sql import partial_update_model, row_int
-from sqlphilosophy.sync.protocols import RepositoryFactory
-from sqlphilosophy.sync.repository import BaseRepository
-from sqlphilosophy.sync.query import SqlAlchemyStatementBuilder
-
-repo = BaseRepository(User, session)
-rows = repo.statement().where(User.active.is_(True)).mappings().all()
-
-repo = BaseRepository(User, session, factory)
-page = repo.statement().fetch_page(ListQuery.from_page(page=1, size=20))
-other = repo.for_repo(OrderRepository)
-```
-
-## Async usage
-
-```python
-from sqlalchemy.ext.asyncio import AsyncSession
-
-from sqlphilosophy.aio.repository import AsyncBaseRepository
-
-repo = AsyncBaseRepository(User, session)
-rows = await repo.statement().where(User.active.is_(True)).mappings().all()
-```
+| `sqlphilosophy` | `__version__` only |
+| `sqlphilosophy.types` | Portable typing aliases |
+| `sqlphilosophy.sql` | Row mapping, partial updates, Core helpers (re-exports `trusted_sql`) |
+| `sqlphilosophy.trusted_sql` | Developer-trusted SQL fragments — see [SECURITY.md](./SECURITY.md) |
+| `sqlphilosophy.sorting` | `ListQuery`, `SortConfig`, `SortSpec` |
+| `sqlphilosophy.sync` / `sqlphilosophy.aio` | Repositories, query builders, factory protocols |
+| `sqlphilosophy.audit` | Optional listeners and timestamp mixins |
 
 ## Transaction ownership
 
-- **`create` / `update` / `delete` helpers** on repositories call `session.flush()` but **do not commit** unless documented otherwise.
-- **`delete_all()`** executes a bulk delete and **does not commit** — the caller owns `session.commit()` / `rollback()` for the work unit.
-- **`batched_purge_ids(...)`** deletes matching rows in batches and **commits after each batch** — treat it as a destructive, application-level operation you must authorize first.
-- Your application owns **`session.commit()` / `rollback()`** for normal request/work-unit boundaries.
+- **`create` / `add` / `update_partial` / `remove` / `delete_*` / `update_where`** — flush or execute DML; **caller commits**.
+- **`delete_all()`** — bulk delete; **does not commit**.
+- **`batched_purge_ids(..., batch_size=...)`** — deletes in batches and **commits after each batch**; requires **`batch_size >= 1`**. Authorize in application code first.
 
 ## Raw SQL trust boundaries
 
-The following must be **developer-defined** and must **never** be built from end-user input:
-
-- Raw SQL fragments passed to SQL helper functions
-- Literal column names, table names, and `ORDER BY` expressions
-- Sort field allowlists wired into query builders
-
-**User-supplied values must use bind parameters** (SQLAlchemy bound values), not string concatenation into SQL text or identifiers. See [SECURITY.md](./SECURITY.md).
-
-## Destructive helpers
+Identifiers and SQL fragments (table/column names, `ORDER BY` text, sort allowlists) must be **developer-defined**, never built from end-user input. User **values** use bind parameters.
 
-- **`delete_all()`** — removes all rows for the repository model (sync and async variants). Does **not** commit; caller must commit or roll back.
-- **`batched_purge_ids(...)`** — deletes matching rows in batches and commits each batch.
-
-Call only after your application has authorized the operation. These helpers assume the caller understands the data loss impact.
-
-## Audit mixins
-
-```python
-from sqlphilosophy.audit.context import audit_context
-from sqlphilosophy.audit.listener import configure_audit_listeners
-from sqlphilosophy.audit.model import TimestampModel
-
-configure_audit_listeners()
-
-with audit_context(actor_id=42):
-    session.add(MyModel(name="example"))
-    session.flush()
-    session.commit()
-```
-
-Audit listeners record changes; they do **not** enforce access control.
+Import trusted helpers from **`sqlphilosophy.trusted_sql`** (`sql_table`, `col_eq`, `col_icontains`, `col_range`, `literal_order_expr`, …). The same names are re-exported from `sqlphilosophy.sql`. Details: [SECURITY.md](./SECURITY.md) and the [repository guide](./docs/repository-guide.md).
 
 ## Development
 
-This repo uses [uv](https://docs.astral.sh/uv/):
+This repo uses [uv](https://docs.astral.sh/uv/) and [Ruff](https://docs.astral.sh/ruff/):
 
 ```bash
 uv sync --extra dev
 uv run pytest
-uv run flake8 .
+uv run ruff check src tests docs/examples
+uv run ruff format src tests docs/examples
+
+# Optional: validate runnable docs examples (SQLite in-memory; CI runs these in smoke-package)
+uv run --extra dev python docs/examples/typed_repository_sync.py
+uv run --extra dev python docs/examples/typed_repository_async.py
+
 uv run python -m build
 ```
 

sqlphilosophy-0.1.9/README.md

@@ -0,0 +1,138 @@
+# sqlphilosophy
+
+Portable SQLAlchemy repository kit: sync and async CRUD, fluent statement builders, sort/pagination, Core SQL helpers, and optional audit listeners.
+
+| | |
+|---|---|
+| **PyPI** | [`sqlphilosophy`](https://pypi.org/project/sqlphilosophy/) |
+| **GitHub** | [SignalSafeSoftware/sqlphilosophy](https://github.com/SignalSafeSoftware/sqlphilosophy) |
+| **Import** | `sqlphilosophy` (`__version__` only) — use explicit submodules for APIs |
+| **Python** | 3.12+ |
+| **License** | MIT — see [LICENSE](./LICENSE) |
+
+## Documentation
+
+| Resource | Description |
+|----------|-------------|
+| [Repository guide](./docs/repository-guide.md) | Entry point: overview, transaction model, links to usage pages |
+| [Usage examples](./docs/usage/) | Focused sync/async code examples by feature area |
+| [Strongly typed repositories](./docs/usage/strongly-typed-repositories.md) | Typed subclasses, factories, protocols, and service patterns |
+| [Before/after SQLAlchemy](./docs/usage/before-after-sqlalchemy.md) | Migration examples: direct SQLAlchemy vs repository-centered code |
+| [Feature matrix](./docs/feature-matrix.md) | Full sync/async capability map |
+| [Typed repository (sync)](./docs/examples/typed_repository_sync.py) | Runnable factory + domain repo example |
+| [Typed repository (async)](./docs/examples/typed_repository_async.py) | Async counterpart |
+
+## What this package does
+
+- **Repository pattern** for a single mapped model (`BaseRepository`, `AsyncBaseRepository`).
+- **Fluent query builders** with pagination/sort (`StatementQueryBuilder`, `ListQuery`, `SortConfig`).
+- **SQL helpers** for row mapping, partial updates, and developer-defined fragments via **`sqlphilosophy.trusted_sql`**.
+- **Optional audit listeners** and timestamp mixins.
+
+## What this package does not do
+
+- Migrations, schema design, or connection pooling configuration.
+- Authorization, multi-tenant isolation, or query sandboxing.
+- Automatic commits for normal CRUD — see [Transaction ownership](#transaction-ownership).
+
+## Install
+
+```bash
+pip install sqlphilosophy
+```
+
+Async ORM (`AsyncSession`) also needs greenlet:
+
+```bash
+pip install sqlphilosophy[async]
+```
+
+Requires Python 3.12+ and SQLAlchemy 2.x.
+
+## Quick start (sync)
+
+```python
+from sqlalchemy import String, create_engine
+from sqlalchemy.orm import DeclarativeBase, Mapped, Session, mapped_column, sessionmaker
+
+from sqlphilosophy.sorting import ListQuery
+from sqlphilosophy.sync.repository import BaseRepository
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class Widget(Base):
+    __tablename__ = "widget"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    name: Mapped[str] = mapped_column(String(64))
+
+
+engine = create_engine("sqlite:///:memory:", future=True)
+Base.metadata.create_all(engine)
+SessionLocal = sessionmaker(bind=engine, expire_on_commit=False)
+
+with SessionLocal() as session:
+    repo = BaseRepository(Widget, session)
+    repo.create(name="alpha")  # stages + flush; does not commit
+    session.commit()
+
+    rows, total = repo.statement().fetch_page(ListQuery.from_page(page=1, size=20))
+    assert total >= 1
+```
+
+**Async:** use `AsyncSession`, `AsyncBaseRepository` from `sqlphilosophy.aio.repository`, and `await` on repository/builder terminals. See the [repository guide](./docs/repository-guide.md).
+
+## Package layout
+
+| Module | Contents |
+|--------|----------|
+| `sqlphilosophy` | `__version__` only |
+| `sqlphilosophy.types` | Portable typing aliases |
+| `sqlphilosophy.sql` | Row mapping, partial updates, Core helpers (re-exports `trusted_sql`) |
+| `sqlphilosophy.trusted_sql` | Developer-trusted SQL fragments — see [SECURITY.md](./SECURITY.md) |
+| `sqlphilosophy.sorting` | `ListQuery`, `SortConfig`, `SortSpec` |
+| `sqlphilosophy.sync` / `sqlphilosophy.aio` | Repositories, query builders, factory protocols |
+| `sqlphilosophy.audit` | Optional listeners and timestamp mixins |
+
+## Transaction ownership
+
+- **`create` / `add` / `update_partial` / `remove` / `delete_*` / `update_where`** — flush or execute DML; **caller commits**.
+- **`delete_all()`** — bulk delete; **does not commit**.
+- **`batched_purge_ids(..., batch_size=...)`** — deletes in batches and **commits after each batch**; requires **`batch_size >= 1`**. Authorize in application code first.
+
+## Raw SQL trust boundaries
+
+Identifiers and SQL fragments (table/column names, `ORDER BY` text, sort allowlists) must be **developer-defined**, never built from end-user input. User **values** use bind parameters.
+
+Import trusted helpers from **`sqlphilosophy.trusted_sql`** (`sql_table`, `col_eq`, `col_icontains`, `col_range`, `literal_order_expr`, …). The same names are re-exported from `sqlphilosophy.sql`. Details: [SECURITY.md](./SECURITY.md) and the [repository guide](./docs/repository-guide.md).
+
+## Development
+
+This repo uses [uv](https://docs.astral.sh/uv/) and [Ruff](https://docs.astral.sh/ruff/):
+
+```bash
+uv sync --extra dev
+uv run pytest
+uv run ruff check src tests docs/examples
+uv run ruff format src tests docs/examples
+
+# Optional: validate runnable docs examples (SQLite in-memory; CI runs these in smoke-package)
+uv run --extra dev python docs/examples/typed_repository_sync.py
+uv run --extra dev python docs/examples/typed_repository_async.py
+
+uv run python -m build
+```
+
+## Security
+
+See [SECURITY.md](./SECURITY.md) for vulnerability reporting and SQL trust boundaries.
+
+## Releasing
+
+See [RELEASING.md](./RELEASING.md) for GitHub + PyPI trusted publishing. See [CHANGELOG.md](./CHANGELOG.md).
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

{sqlphilosophy-0.1.6 → sqlphilosophy-0.1.9}/pyproject.toml

@@ -39,7 +39,7 @@ dev = [
     "greenlet>=3.0",
     "build>=1.2",
     "twine>=5",
-    "flake8>=7",
+    "ruff>=0.15",
     "mypy>=1.11",
     "bandit>=1.7",
     "types-greenlet>=3.0",
@@ -83,5 +83,31 @@ python_version = "3.12"
 plugins = ["sqlalchemy.ext.mypy.plugin"]
 warn_unused_ignores = true
 
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+src = ["src", "tests", "docs/examples"]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "W",
+    "I",
+    "B",
+    "UP",
+    "SIM",
+    "PT",
+    "RUF",
+]
+ignore = [
+    "E203",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = [
+    "PT011",
+]
+
 [tool.uv]
 package = true

sqlphilosophy-0.1.9/src/sqlphilosophy/VERSION

@@ -0,0 +1 @@
+0.1.9

sqlphilosophy-0.1.9/src/sqlphilosophy/__init__.py

@@ -0,0 +1,18 @@
+"""SQLAlchemy repository kit — sync/async CRUD, query builders, sort, and SQL helpers."""
+
+from __future__ import annotations
+
+from importlib import metadata
+from pathlib import Path
+
+__all__ = ["__version__"]
+
+
+def _load_version() -> str:
+    try:
+        return metadata.version("sqlphilosophy")
+    except metadata.PackageNotFoundError:
+        return (Path(__file__).resolve().parent / "VERSION").read_text(encoding="utf-8").strip()
+
+
+__version__ = _load_version()

sqlphilosophy-0.1.9/src/sqlphilosophy/_repository_shared.py

@@ -0,0 +1,114 @@
+"""Internal helpers shared by sync and async repository implementations."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Any, Literal, cast
+
+from sqlalchemy import func
+from sqlalchemy.orm import DeclarativeBase
+
+from sqlphilosophy.audit.model import AuditMixin
+from sqlphilosophy.types import PrimaryKey, RowMapping, RowValue, SqlFilter
+
+
+def require_batch_size(batch_size: int) -> None:
+    """Validate batch size for destructive batched repository operations."""
+    if batch_size < 1:
+        raise ValueError("batch_size must be >= 1")
+
+
+def require_single_column_primary_key(model: type[DeclarativeBase], mapper: Any) -> Any:
+    """Return the sole primary-key column or raise when the mapper is invalid."""
+    pk_cols = mapper.primary_key
+    if len(pk_cols) != 1:
+        raise TypeError(f"{model.__name__} must have a single-column primary key")
+    return pk_cols[0]
+
+
+def require_page_and_limit(*, page: int, limit: int | None) -> None:
+    """Validate repository pagination inputs."""
+    if page < 1:
+        raise ValueError("page must be >= 1")
+    if limit is not None and limit < 1:
+        raise ValueError("limit must be >= 1")
+
+
+def require_mappings_page_limits(*, limit: int, offset: int) -> None:
+    """Validate limit/offset for mapping page fetches."""
+    if limit < 0:
+        raise ValueError("limit must be >= 0")
+    if offset < 0:
+        raise ValueError("offset must be >= 0")
+
+
+def filter_writable_updates(fields: RowMapping, writable: frozenset[str]) -> RowMapping:
+    """Keep only keys allowed by ``writable``."""
+    return {k: v for k, v in fields.items() if k in writable}
+
+
+def lookup_not_found_message(model: type[DeclarativeBase], obj_id: PrimaryKey) -> str:
+    """Message for ``LookupError`` when a primary-key fetch misses."""
+    return f"{model.__name__} matching id={obj_id!r} not found"
+
+
+def extract_primary_keys(rows: Sequence[RowMapping], pk_key: str) -> list[PrimaryKey]:
+    """Collect primary-key values from statement mapping rows."""
+    return [cast(PrimaryKey, row[pk_key]) for row in rows]
+
+
+@dataclass(frozen=True)
+class PartialUpdatePlan:
+    """Prepared partial-update action for sync or async execution."""
+
+    action: Literal["skip", "audit", "core"]
+    updates: RowMapping | None = None
+
+    def updates_for(self, action: Literal["audit", "core"]) -> RowMapping:
+        """Return the updates payload for an audit or core plan."""
+        if self.action != action:
+            raise RuntimeError(f"partial update plan action mismatch: expected {action!r}, got {self.action!r}")
+        if self.updates is None:
+            raise RuntimeError(f"partial update plan {action!r} is missing updates payload")
+        return self.updates
+
+
+def plan_partial_update(
+    model: type[DeclarativeBase],
+    fields: RowMapping,
+    writable: frozenset[str],
+    *,
+    touch_updated_on: bool = False,
+    extra_values: RowMapping | None = None,
+) -> PartialUpdatePlan:
+    """Prepare audit ORM, core UPDATE, or no-op partial update payloads."""
+    if issubclass(model, AuditMixin):
+        audit_updates = filter_writable_updates(fields, writable)
+        if extra_values:
+            audit_updates = {**audit_updates, **extra_values}
+        if not audit_updates:
+            return PartialUpdatePlan("skip")
+        return PartialUpdatePlan("audit", audit_updates)
+
+    core_updates = filter_writable_updates(fields, writable)
+    if extra_values:
+        core_updates = {**core_updates, **extra_values}
+    if not core_updates:
+        return PartialUpdatePlan("skip")
+    if touch_updated_on:
+        core_updates = cast(
+            RowMapping,
+            {**dict(core_updates), "updated_on": cast(RowValue, func.now())},
+        )
+    return PartialUpdatePlan("core", core_updates)
+
+
+def criteria_delete_allowed(criteria: Sequence[SqlFilter]) -> bool:
+    """True when ``delete_where`` should run a lookup before deleting."""
+    return bool(criteria)
+
+
+def bulk_update_allowed(values: RowMapping) -> bool:
+    """True when ``update_where`` has values to apply."""
+    return bool(values)

sqlphilosophy-0.1.9/src/sqlphilosophy/aio/protocols.py

@@ -0,0 +1,106 @@
+"""Portable async repository factory and repository protocols (no Phobos or app imports)."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Any, Protocol, TypeVar
+
+if TYPE_CHECKING:
+    from sqlphilosophy.aio.repository import AsyncBaseRepository
+
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import DeclarativeBase
+
+from sqlphilosophy.aio.query import AsyncStatementQueryBuilder
+from sqlphilosophy.types import IdList, PrimaryKey, RowMapping, RowValue, SqlFilter
+
+T = TypeVar("T", bound=DeclarativeBase)
+R = TypeVar("R", bound="AsyncBaseRepository[Any, Any]")
+
+
+class AsyncBaseRepositoryProtocol[T: DeclarativeBase, U: AsyncRepositoryFactory | None](
+    Protocol,
+):
+    """Generic read/write surface shared by sqlphilosophy ``AsyncBaseRepository[T]``."""
+
+    model: type[T]
+    _session: AsyncSession
+    _factory: U | None
+
+    async def get(self, obj_id: PrimaryKey, load_relations: Any = None) -> T: ...
+
+    async def get_by_id(self, obj_id: PrimaryKey, load_relations: Any = None) -> T | None: ...
+
+    async def get_many(self, ids: Sequence[PrimaryKey], load_relations: Any = None) -> Sequence[T]: ...
+
+    async def first(self, load_relations: Any = None, **filters: RowValue) -> T | None: ...
+
+    async def filter(
+        self,
+        *,
+        page: int = 1,
+        limit: int | None = None,
+        load_relations: Any = None,
+        **filters: RowValue,
+    ) -> Sequence[T]: ...
+
+    async def get_all(
+        self,
+        *,
+        page: int = 1,
+        limit: int | None = None,
+        load_relations: Any = None,
+    ) -> Sequence[T]: ...
+
+    async def count(self, **filters: RowValue) -> int: ...
+
+    async def exists(self, obj_id: PrimaryKey) -> bool: ...
+
+    async def exists_where(self, **filters: RowValue) -> bool: ...
+
+    def statement(self) -> AsyncStatementQueryBuilder[T]: ...
+
+    async def create(self, **fields: object) -> T: ...
+
+    async def add(self, obj: T) -> T: ...
+
+    async def get_or_create(self, *, defaults: RowMapping | None = None, **lookup: RowValue) -> tuple[T, bool]: ...
+
+    async def remove(self, obj_id: PrimaryKey) -> bool: ...
+
+    async def delete_many(self, ids: IdList) -> int: ...
+
+    async def delete_where(self, *, criteria: Sequence[SqlFilter], params: RowMapping | None = None) -> int: ...
+
+    async def update_partial(
+        self,
+        obj_id: PrimaryKey,
+        fields: RowMapping,
+        writable: frozenset[str],
+        *,
+        touch_updated_on: bool = False,
+    ) -> int: ...
+
+    async def update_where(
+        self,
+        *,
+        criteria: Sequence[SqlFilter],
+        values: RowMapping,
+        params: RowMapping | None = None,
+    ) -> int: ...
+
+
+class AsyncRepositoryFactory(Protocol):
+    """Session-scoped factory for async statement builders and entity repositories."""
+
+    def create_statement(self, model: type[T]) -> AsyncStatementQueryBuilder[T]:
+        """Return a fluent async read builder for ``model``."""
+        ...
+
+    def get_repository(self, repo_class: type[R]) -> R:
+        """Return a cached typed entity repository."""
+        ...
+
+    def repository(self, model: type[T]) -> AsyncBaseRepositoryProtocol[T, AsyncRepositoryFactory | None]:
+        """Return generic CRUD helpers for ``model`` (``AsyncBaseRepository`` in Phobos)."""
+        ...