varco-core 0.0.1__tar.gz

varco_core-0.0.1/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: varco-core
+Version: 0.0.1
+Summary: Core domain abstractions for varco (models, mapper, meta, query)
+Author: edoardo.scarpaci
+Author-email: edoardo.scarpaci@gmail.com
+Requires-Python: >=3.12
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: PyJWT (>=2.8,<3.0)
+Requires-Dist: cryptography (>=41.0)
+Requires-Dist: lark (>=1.1)
+Requires-Dist: providify (>=0.1.4a3)
+Requires-Dist: pydantic (>=2.12.5,<3.0.0)
+Description-Content-Type: text/markdown
+
+# varco-core
+
+Backend-agnostic domain model and service layer for **varco**.
+
+Provides the pure-Python building blocks that all backend packages depend on — no ORM imports at the core layer.
+
+## What lives here
+
+| Module | Purpose |
+|---|---|
+| `model.py` | `DomainModel`, `AuditedDomainModel`, `VersionedDomainModel`, `SoftDeleteMixin`, `TenantMixin` and derived classes |
+| `meta.py` | `FieldHint`, `ForeignKey`, `PrimaryKey`, `PKStrategy`, constraints, `pk_field()` |
+| `mapper.py` | `AbstractMapper` — bidirectional ORM ↔ domain translation |
+| `repository.py` | `AsyncRepository` ABC — CRUD + `exists()` + `stream_by_query()` |
+| `uow.py` | `AsyncUnitOfWork` ABC |
+| `registry.py` | `DomainModelRegistry` + `@register` decorator |
+| `providers.py` | `RepositoryProvider` ABC |
+| `assembler.py` | `AbstractDTOAssembler[D, C, R, U]` |
+| `service/base.py` | `AsyncService`, `IUoWProvider` |
+| `service/tenant.py` | `TenantAwareService`, `TenantUoWProvider`, `tenant_context` |
+| `service/soft_delete.py` | `SoftDeleteService` |
+| `service/types.py` | `Assembler` alias, `ServiceProtocol` |
+| `auth/` | `AbstractAuthorizer`, `Action`, `AuthContext`, `ResourceGrant` |
+| `auth/helpers.py` | `GrantBasedAuthorizer`, `OwnershipAuthorizer`, `RoleBasedAuthorizer` |
+| `exception/codes.py` | `FastrestErrorCodes` enum, `ErrorCode` |
+| `exception/http.py` | `ErrorMessage`, `error_message_for`, `register_error_code` |
+| `tracing.py` | `correlation_context`, `current_correlation_id`, `CorrelationIdFilter` |
+| `query/` | `QueryBuilder`, `QueryParams`, `QueryParser`, AST visitors |
+
+## Install
+
+```bash
+pip install varco-core
+```
+
+## Quick start
+
+```python
+from __future__ import annotations
+from typing import Annotated
+from varco_core import AuditedDomainModel
+from varco_core.meta import FieldHint, PrimaryKey, PKStrategy, pk_field
+
+class Post(AuditedDomainModel):
+    pk: Annotated[int, PrimaryKey(PKStrategy.INT_AUTO)] = pk_field()
+    title: Annotated[str, FieldHint(max_length=200)]
+    body: str
+    published: bool = False
+```
+
+Install `varco-sa` or `varco-beanie` for a concrete backend, then wire a service:
+
+```python
+from varco_core import AsyncService, IUoWProvider
+from varco_core.assembler import AbstractDTOAssembler
+from varco_core.auth import AbstractAuthorizer
+from providify import Inject, Singleton
+
+@Singleton
+class PostService(AsyncService[Post, int, CreatePostDTO, PostReadDTO, UpdatePostDTO]):
+    def __init__(
+        self,
+        uow_provider: Inject[IUoWProvider],
+        authorizer:   Inject[AbstractAuthorizer],
+        assembler:    Inject[AbstractDTOAssembler[Post, CreatePostDTO, PostReadDTO, UpdatePostDTO]],
+    ) -> None:
+        super().__init__(uow_provider=uow_provider, authorizer=authorizer, assembler=assembler)
+
+    def _get_repo(self, uow): return uow.posts
+```
+
+See the [root README](../README.md) for the full documentation.
+

varco_core-0.0.1/README.md

@@ -0,0 +1,72 @@
+# varco-core
+
+Backend-agnostic domain model and service layer for **varco**.
+
+Provides the pure-Python building blocks that all backend packages depend on — no ORM imports at the core layer.
+
+## What lives here
+
+| Module | Purpose |
+|---|---|
+| `model.py` | `DomainModel`, `AuditedDomainModel`, `VersionedDomainModel`, `SoftDeleteMixin`, `TenantMixin` and derived classes |
+| `meta.py` | `FieldHint`, `ForeignKey`, `PrimaryKey`, `PKStrategy`, constraints, `pk_field()` |
+| `mapper.py` | `AbstractMapper` — bidirectional ORM ↔ domain translation |
+| `repository.py` | `AsyncRepository` ABC — CRUD + `exists()` + `stream_by_query()` |
+| `uow.py` | `AsyncUnitOfWork` ABC |
+| `registry.py` | `DomainModelRegistry` + `@register` decorator |
+| `providers.py` | `RepositoryProvider` ABC |
+| `assembler.py` | `AbstractDTOAssembler[D, C, R, U]` |
+| `service/base.py` | `AsyncService`, `IUoWProvider` |
+| `service/tenant.py` | `TenantAwareService`, `TenantUoWProvider`, `tenant_context` |
+| `service/soft_delete.py` | `SoftDeleteService` |
+| `service/types.py` | `Assembler` alias, `ServiceProtocol` |
+| `auth/` | `AbstractAuthorizer`, `Action`, `AuthContext`, `ResourceGrant` |
+| `auth/helpers.py` | `GrantBasedAuthorizer`, `OwnershipAuthorizer`, `RoleBasedAuthorizer` |
+| `exception/codes.py` | `FastrestErrorCodes` enum, `ErrorCode` |
+| `exception/http.py` | `ErrorMessage`, `error_message_for`, `register_error_code` |
+| `tracing.py` | `correlation_context`, `current_correlation_id`, `CorrelationIdFilter` |
+| `query/` | `QueryBuilder`, `QueryParams`, `QueryParser`, AST visitors |
+
+## Install
+
+```bash
+pip install varco-core
+```
+
+## Quick start
+
+```python
+from __future__ import annotations
+from typing import Annotated
+from varco_core import AuditedDomainModel
+from varco_core.meta import FieldHint, PrimaryKey, PKStrategy, pk_field
+
+class Post(AuditedDomainModel):
+    pk: Annotated[int, PrimaryKey(PKStrategy.INT_AUTO)] = pk_field()
+    title: Annotated[str, FieldHint(max_length=200)]
+    body: str
+    published: bool = False
+```
+
+Install `varco-sa` or `varco-beanie` for a concrete backend, then wire a service:
+
+```python
+from varco_core import AsyncService, IUoWProvider
+from varco_core.assembler import AbstractDTOAssembler
+from varco_core.auth import AbstractAuthorizer
+from providify import Inject, Singleton
+
+@Singleton
+class PostService(AsyncService[Post, int, CreatePostDTO, PostReadDTO, UpdatePostDTO]):
+    def __init__(
+        self,
+        uow_provider: Inject[IUoWProvider],
+        authorizer:   Inject[AbstractAuthorizer],
+        assembler:    Inject[AbstractDTOAssembler[Post, CreatePostDTO, PostReadDTO, UpdatePostDTO]],
+    ) -> None:
+        super().__init__(uow_provider=uow_provider, authorizer=authorizer, assembler=assembler)
+
+    def _get_repo(self, uow): return uow.posts
+```
+
+See the [root README](../README.md) for the full documentation.

varco_core-0.0.1/pyproject.toml

@@ -0,0 +1,30 @@
+[tool.poetry]
+name        = "varco-core"
+version     = "0.0.1"
+description = "Core domain abstractions for varco (models, mapper, meta, query)"
+authors     = ["edoardo.scarpaci <edoardo.scarpaci@gmail.com>"]
+readme      = "README.md"
+packages    = [{include = "varco_core"}]
+
+[tool.poetry.dependencies]
+python   = ">=3.12"
+pydantic = ">=2.12.5,<3.0.0"
+providify = ">=0.1.4a3"
+# lark is used by QueryParser — runtime dependency, not dev-only
+lark     = ">=1.1"
+# PyJWT is used by varco_core.jwt for encoding/decoding JWT tokens
+PyJWT         = ">=2.8,<3.0"
+# cryptography is used by varco_core.jwk for RSA/EC key operations
+cryptography  = ">=41.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest       = ">=8.0"
+pytest-asyncio = ">=0.24"
+
+[build-system]
+requires      = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths    = ["tests"]

varco_core-0.0.1/varco_core/__init__.py

@@ -0,0 +1,263 @@
+"""
+varco_core
+=============
+Backend-agnostic domain model and query layer.
+
+All stable public symbols are importable directly from ``varco_core``::
+
+    # Domain
+    from varco_core import DomainModel, AuditedDomainModel, cast_raw, register
+    from varco_core import TenantDomainModel, TenantAuditedDomainModel
+    from varco_core import AbstractMapper, AsyncRepository, AsyncUnitOfWork
+    from varco_core import DomainModelRegistry, RepositoryProvider
+
+    # Metadata
+    from varco_core.meta import (
+        FieldHint, ForeignKey, PrimaryKey, PKStrategy,
+        UniqueConstraint, CheckConstraint, pk_field,
+    )
+
+    # Query system
+    from varco_core import QueryBuilder, QueryParams, QueryParser
+    from varco_core import SortField, SortOrder, Operation
+
+    # DTOs (API layer)
+    from varco_core import CreateDTO, ReadDTO, UpdateDTO, UpdateOperation
+
+Sub-package layout
+------------------
+    varco_core/
+    ├── model.py          — DomainModel, cast_raw
+    ├── meta.py           — FieldHint, ForeignKey, PKStrategy, constraints
+    ├── mapper.py         — AbstractMapper (bidirectional ORM ↔ domain)
+    ├── registry.py       — DomainModelRegistry, @register decorator
+    ├── repository.py     — AsyncRepository ABC (CRUD + query)
+    ├── providers.py      — RepositoryProvider ABC + autodiscover
+    ├── uow.py            — AsyncUnitOfWork ABC
+    ├── dto.py            — CreateDTO, ReadDTO, UpdateDTO, UpdateOperation
+    └── query/
+        ├── type.py       — AST node types
+        ├── builder.py    — Fluent QueryBuilder
+        ├── params.py     — QueryParams value object
+        ├── parser.py     — QueryParser (string → AST via Lark)
+        ├── transformer.py— Lark transformer
+        ├── grammar.lark  — Query grammar
+        ├── visitor/      — ASTVisitor, optimizer, type coercion, SA compiler
+        └── applicator/   — QueryApplicator ABC + SA implementation
+"""
+
+from __future__ import annotations
+
+# ── Domain layer ───────────────────────────────────────────────────────────────
+from varco_core.exception.repository import StaleEntityError
+from varco_core.mapper import AbstractMapper
+from varco_core.migrator import DomainMigrator, MigrationError
+from varco_core.model import (
+    AuditedDomainModel,
+    DomainModel,
+    SoftDeleteAuditedDomainModel,
+    SoftDeleteDomainModel,
+    SoftDeleteMixin,
+    TenantAuditedDomainModel,
+    TenantDomainModel,
+    TenantMixin,
+    TenantVersionedDomainModel,
+    VersionedDomainModel,
+    cast_raw,
+)
+from varco_core.providers import RepositoryProvider
+from varco_core.registry import DomainModelRegistry, register
+from varco_core.repository import AsyncRepository
+from varco_core.uow import AsyncUnitOfWork
+
+# ── DTO layer ──────────────────────────────────────────────────────────────────
+from varco_core.dto import (
+    CreateDTO,
+    ReadDTO,
+    TCreateDTO,
+    TReadDTO,
+    TUpdateDTO,
+    UpdateDTO,
+    UpdateOperation,
+)
+from varco_core.dto.factory import DTOSet, generate_dtos
+from varco_core.dto.pagination import (
+    PageCursor,
+    PagedReadDTO,
+    SortCursorField,
+    paged_response,
+)
+
+# ── Query system ───────────────────────────────────────────────────────────────
+from varco_core.query.builder import QueryBuilder
+from varco_core.query.params import QueryParams
+from varco_core.query.parser import QueryParser
+from varco_core.query.type import Operation, SortField, SortOrder
+
+# ── Multi-tenancy ───────────────────────────────────────────────────────────────
+from varco_core.service.tenant import (
+    TenantAwareService,
+    TenantUoWProvider,
+    current_tenant,
+    tenant_context,
+)
+
+# ── Soft delete ─────────────────────────────────────────────────────────────────
+from varco_core.service.soft_delete import SoftDeleteService
+
+# ── Service type aliases and protocols ──────────────────────────────────────────
+from varco_core.service.types import Assembler, ServiceProtocol
+
+# ── Tracing / correlation ID ────────────────────────────────────────────────────
+from varco_core.tracing import (
+    CorrelationIdFilter,
+    correlation_context,
+    current_correlation_id,
+    generate_correlation_id,
+)
+
+# ── Auth helpers ─────────────────────────────────────────────────────────────────
+from varco_core.auth.helpers import (
+    GrantBasedAuthorizer,
+    OwnershipAuthorizer,
+    RoleBasedAuthorizer,
+)
+
+# ── Error codes and HTTP error mapping ──────────────────────────────────────────
+from varco_core.exception.codes import ErrorCode, FastrestErrorCodes
+from varco_core.exception.http import (
+    AnyErrorCode,
+    ErrorMessage,
+    error_code_for,
+    error_message_for,
+    register_error_code,
+)
+
+# ── JWT layer ──────────────────────────────────────────────────────────────────
+from varco_core.jwt import (
+    SYSTEM_ISSUER,
+    JsonWebToken,
+    JwtBuilder,
+    JwtParser,
+    JwtUtil,
+)
+
+# ── JWK layer ──────────────────────────────────────────────────────────────────
+from varco_core.jwk import (
+    JsonWebKey,
+    JsonWebKeySet,
+    JwkBuilder,
+)
+
+# ── Authority layer ─────────────────────────────────────────────────────────────
+from varco_core.authority import (
+    AuthorizationConfig,
+    AuthorityError,
+    AuthoritySource,
+    IssuerNotFoundError,
+    JwtAuthority,
+    KeyLoadError,
+    MultiKeyAuthority,
+    TrustedIssuerEntry,
+    TrustedIssuerRegistry,
+    UnknownKidError,
+)
+
+__all__ = [
+    # ── Domain base ────────────────────────────────────────────────────────────
+    "DomainModel",
+    "AuditedDomainModel",
+    "VersionedDomainModel",
+    "TenantMixin",
+    "TenantDomainModel",
+    "TenantAuditedDomainModel",
+    "TenantVersionedDomainModel",
+    "cast_raw",
+    # ── Soft delete domain mixins ───────────────────────────────────────────────
+    "SoftDeleteMixin",
+    "SoftDeleteDomainModel",
+    "SoftDeleteAuditedDomainModel",
+    # ── Migration ──────────────────────────────────────────────────────────────
+    "DomainMigrator",
+    "MigrationError",
+    "StaleEntityError",
+    # ── Abstraction layer ──────────────────────────────────────────────────────
+    "AbstractMapper",
+    "AsyncRepository",
+    "AsyncUnitOfWork",
+    # ── Registration ───────────────────────────────────────────────────────────
+    "DomainModelRegistry",
+    "register",
+    # ── Provider ABC ───────────────────────────────────────────────────────────
+    "RepositoryProvider",
+    # ── DTO layer ──────────────────────────────────────────────────────────────
+    "CreateDTO",
+    "ReadDTO",
+    "UpdateDTO",
+    "UpdateOperation",
+    "TCreateDTO",
+    "TReadDTO",
+    "TUpdateDTO",
+    "DTOSet",
+    "generate_dtos",
+    # ── Pagination ──────────────────────────────────────────────────────────────
+    "SortCursorField",
+    "PageCursor",
+    "PagedReadDTO",
+    "paged_response",
+    # ── Query system ───────────────────────────────────────────────────────────
+    "QueryBuilder",
+    "QueryParams",
+    "QueryParser",
+    "SortField",
+    "SortOrder",
+    "Operation",
+    # ── Multi-tenancy ───────────────────────────────────────────────────────────
+    "TenantAwareService",
+    "TenantUoWProvider",
+    "current_tenant",
+    "tenant_context",
+    # ── Soft delete service ─────────────────────────────────────────────────────
+    "SoftDeleteService",
+    # ── Service type aliases ────────────────────────────────────────────────────
+    "Assembler",
+    "ServiceProtocol",
+    # ── Tracing ─────────────────────────────────────────────────────────────────
+    "CorrelationIdFilter",
+    "correlation_context",
+    "current_correlation_id",
+    "generate_correlation_id",
+    # ── Auth helpers ─────────────────────────────────────────────────────────────
+    "GrantBasedAuthorizer",
+    "OwnershipAuthorizer",
+    "RoleBasedAuthorizer",
+    # ── Error codes and HTTP error mapping ───────────────────────────────────────
+    "AnyErrorCode",
+    "ErrorCode",
+    "FastrestErrorCodes",
+    "ErrorMessage",
+    "error_code_for",
+    "error_message_for",
+    "register_error_code",
+    # ── JWT layer ───────────────────────────────────────────────────────────────
+    "SYSTEM_ISSUER",
+    "JsonWebToken",
+    "JwtBuilder",
+    "JwtParser",
+    "JwtUtil",
+    # ── JWK layer ───────────────────────────────────────────────────────────────
+    "JsonWebKey",
+    "JsonWebKeySet",
+    "JwkBuilder",
+    # ── Authority layer ─────────────────────────────────────────────────────────
+    "JwtAuthority",
+    "MultiKeyAuthority",
+    "TrustedIssuerRegistry",
+    "TrustedIssuerEntry",
+    "AuthoritySource",
+    "AuthorizationConfig",
+    "AuthorityError",
+    "UnknownKidError",
+    "IssuerNotFoundError",
+    "KeyLoadError",
+]

varco_core-0.0.1/varco_core/assembler.py

@@ -0,0 +1,219 @@
+"""
+varco_core.assembler
+========================
+Abstract DTO assembler — translates between domain entities and DTOs.
+
+The assembler is the **only** layer responsible for:
+
+- Mapping a ``CreateDTO`` → fresh ``DomainModel`` (INSERT path).
+- Mapping a persisted ``DomainModel`` → ``ReadDTO`` (response path).
+- Applying an ``UpdateDTO`` to an existing entity → updated entity (UPDATE path).
+
+DESIGN: one combined assembler over three separate classes
+    ✅ All three mappings concern the same (D, C, R, U) quartet — they are
+       inherently cohesive and always deployed together for a given entity.
+    ✅ One DI binding per entity type instead of three — simpler container.
+    ✅ Consistent with the existing ``AbstractMapper[D, O]`` pattern in
+       this codebase (one class handles both translation directions).
+    ❌ ``to_read_dto`` cannot be extracted for reuse in a read-only context
+       (e.g. a search service) without referencing the full assembler.
+       If that use case arises, extract a separate ``AbstractReadAssembler``
+       at that point — don't pre-optimise now.
+
+DESIGN: assembler is a separate injectable class, not methods on the service
+    ✅ Service stays focused on orchestration and authorization — no field-
+       level mapping code inside the service.
+    ✅ Assembler can be injected via ``Inject[AbstractDTOAssembler]`` and
+       swapped in tests without touching the service.
+    ✅ Same assembler can be reused across multiple consumers (REST handler,
+       CLI, background job) without duplicating mapping logic.
+    ❌ One extra class per entity — justified by the clear SRP benefit.
+
+Type parameters::
+
+    D — DomainModel subclass (e.g. ``Post``)
+    C — CreateDTO subclass  (e.g. ``CreatePostDTO``)
+    R — ReadDTO subclass    (e.g. ``PostReadDTO``)
+    U — UpdateDTO subclass  (e.g. ``UpdatePostDTO``)
+
+Usage::
+
+    class PostAssembler(AbstractDTOAssembler[Post, CreatePostDTO, PostReadDTO, UpdatePostDTO]):
+
+        def to_domain(self, dto: CreatePostDTO) -> Post:
+            return Post(title=dto.title, body=dto.body)
+
+        def to_read_dto(self, entity: Post) -> PostReadDTO:
+            return PostReadDTO(
+                id=str(entity.pk),
+                title=entity.title,
+                body=entity.body,
+                created_at=entity.created_at,
+                updated_at=entity.updated_at,
+            )
+
+        def apply_update(self, entity: Post, dto: UpdatePostDTO) -> Post:
+            from dataclasses import replace
+            return replace(
+                entity,
+                title=dto.title if dto.title is not None else entity.title,
+                body=dto.body   if dto.body  is not None else entity.body,
+            )
+
+Thread safety:  ✅ Implementations must be stateless — safe to share as singleton.
+Async safety:   ✅ All methods are synchronous — no I/O or awaiting.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Generic, TypeVar
+
+from varco_core.dto import CreateDTO, ReadDTO, UpdateDTO
+from varco_core.model import DomainModel
+
+D = TypeVar("D", bound=DomainModel)
+C = TypeVar("C", bound=CreateDTO)
+R = TypeVar("R", bound=ReadDTO)
+U = TypeVar("U", bound=UpdateDTO)
+
+
+class AbstractDTOAssembler(ABC, Generic[D, C, R, U]):
+    """
+    Abstract DTO assembler for a single entity/DTO quartet (D, C, R, U).
+
+    Concrete subclasses implement three translation methods that cover the
+    full CRUD lifecycle for one entity type:
+
+    - ``to_domain``    — ``CreateDTO`` → fresh ``DomainModel`` (INSERT)
+    - ``to_read_dto``  — persisted ``DomainModel`` → ``ReadDTO`` (response)
+    - ``apply_update`` — ``UpdateDTO`` applied to an existing entity (UPDATE)
+
+    Thread safety:  ✅ Implementations must be stateless — safe to share as
+                       a singleton across requests and coroutines.
+    Async safety:   ✅ All methods are synchronous (pure transformations,
+                       no I/O).
+
+    Edge cases:
+        - ``to_domain`` must return an *unpersisted* entity
+          (``entity._raw_orm is None``) — the repository INSERT path
+          detects ``_raw_orm is None`` to distinguish INSERT from UPDATE.
+        - ``apply_update`` must return a *new* entity — never mutate the
+          input.  ``dataclasses.replace(entity, ...)`` copies ``_raw_orm``
+          automatically (it is a dataclass field) so the repository still
+          treats the result as an UPDATE.
+        - ``to_read_dto`` is only called on *persisted* entities — ``pk``,
+          ``created_at``, and ``updated_at`` are always populated.
+    """
+
+    @abstractmethod
+    def to_domain(self, dto: C) -> D:
+        """
+        Map a ``CreateDTO`` to a fresh, unpersisted domain entity.
+
+        The returned entity must have ``_raw_orm is None`` so that
+        ``repo.save()`` performs an INSERT rather than an UPDATE.
+
+        Args:
+            dto: Validated ``CreateDTO`` payload from the HTTP adapter.
+
+        Returns:
+            A new, unpersisted ``DomainModel`` instance ready for
+            ``repo.save()``.
+
+        Raises:
+            ServiceValidationError: Business rule violated by ``dto`` that
+                                    Pydantic could not catch (e.g. a value
+                                    that conflicts with a domain invariant).
+
+        Edge cases:
+            - Do NOT call ``repo.save()`` here — the service handles persistence.
+            - Set entity default values here (e.g. ``is_active=True``),
+              not in the DTO — keeps the DTO focused on the API contract.
+            - Auto-generated fields (``pk``, ``created_at``, ``updated_at``)
+              must NOT be set here — the mapper / repository manages them.
+
+        Example::
+
+            def to_domain(self, dto: CreatePostDTO) -> Post:
+                return Post(title=dto.title, body=dto.body, is_published=False)
+        """
+
+    @abstractmethod
+    def to_read_dto(self, entity: D) -> R:
+        """
+        Map a persisted domain entity to a ``ReadDTO``.
+
+        Called after every ``save()``, ``find_by_id()``, or
+        ``find_by_query()`` to produce the value returned to the caller.
+
+        Args:
+            entity: A persisted ``DomainModel`` (``entity.is_persisted()``
+                    is ``True`` — ``pk``, ``created_at``, ``updated_at``
+                    are all populated).
+
+        Returns:
+            A fully populated ``ReadDTO`` instance.
+
+        Edge cases:
+            - ``entity.pk`` may be any type (``UUID``, ``int``, ``str``).
+              Always cast to ``str`` for ``ReadDTO.id``.
+            - ``entity.created_at`` / ``entity.updated_at`` are ``None``
+              on entities that do not extend ``AuditedDomainModel`` — handle
+              gracefully if your ``ReadDTO`` declares these as required fields.
+
+        Example::
+
+            def to_read_dto(self, entity: Post) -> PostReadDTO:
+                return PostReadDTO(
+                    id=str(entity.pk),
+                    title=entity.title,
+                    body=entity.body,
+                    created_at=entity.created_at,
+                    updated_at=entity.updated_at,
+                )
+        """
+
+    @abstractmethod
+    def apply_update(self, entity: D, dto: U) -> D:
+        """
+        Apply ``dto`` to ``entity`` and return the updated entity.
+
+        Must return a **new** entity — never mutate ``entity`` in place.
+        Use ``dataclasses.replace(entity, field=value)`` to produce a copy
+        that preserves ``_raw_orm`` (inherited automatically from ``entity``
+        because it is a dataclass field) so the repository performs an
+        UPDATE rather than an INSERT.
+
+        Args:
+            entity: The current, persisted state of the entity before the
+                    update is applied.
+            dto:    The ``UpdateDTO`` describing what fields to change.
+
+        Returns:
+            A new ``DomainModel`` instance with the update applied.
+            ``_raw_orm`` must be inherited from ``entity``.
+
+        Raises:
+            ServiceValidationError: Business rule violated by the combination
+                                    of the current entity state and the dto
+                                    values (e.g. invalid state transition).
+            ServiceConflictError:   The requested change is not allowed in
+                                    the current entity state.
+
+        Edge cases:
+            - Fields set to ``None`` in ``dto`` conventionally mean
+              "no change" — check each field before replacing.
+            - Honour ``dto.op`` (REPLACE / EXTEND / REMOVE / MERGE) for
+              collection and dict fields where partial updates are supported.
+
+        Example::
+
+            def apply_update(self, entity: Post, dto: UpdatePostDTO) -> Post:
+                from dataclasses import replace
+                return replace(
+                    entity,
+                    title=dto.title if dto.title is not None else entity.title,
+                    body=dto.body   if dto.body  is not None else entity.body,
+                )
+        """