sincpro-framework 3.7.0__tar.gz → 3.7.2__tar.gz

{sincpro_framework-3.7.0 → sincpro_framework-3.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sincpro-framework
-Version: 3.7.0
+Version: 3.7.2
 Summary: Sincpro framework to use DDD, Clean architecture, Hexagonal architecture
 License: MIT
 License-File: LICENSE.md
@@ -12,12 +12,14 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Provides-Extra: duckdb
 Provides-Extra: mcp
 Provides-Extra: opentelemetry
 Provides-Extra: rpc
 Provides-Extra: sentry
 Provides-Extra: sqlalchemy
 Requires-Dist: dependency-injector (>=4.49.1,<5.0.0)
+Requires-Dist: duckdb-engine (>=0.17.0,<0.18.0) ; extra == "duckdb"
 Requires-Dist: fastmcp (>=3.0,<4) ; extra == "mcp"
 Requires-Dist: opentelemetry-api (>=1.20) ; extra == "opentelemetry"
 Requires-Dist: opentelemetry-exporter-otlp-proto-grpc (>=1.20) ; extra == "opentelemetry"
@@ -27,7 +29,7 @@ Requires-Dist: pydantic (>=2.13.5,<3.0.0)
 Requires-Dist: pyyaml (>=6.0.1)
 Requires-Dist: sentry-sdk (>=2.0) ; extra == "sentry"
 Requires-Dist: sincpro-log (>=1.2.1,<2.0.0)
-Requires-Dist: sqlalchemy (>=2.0) ; extra == "sqlalchemy"
+Requires-Dist: sqlalchemy (>=2.0) ; extra == "sqlalchemy" or extra == "duckdb"
 Requires-Dist: starlette (>=1.0) ; extra == "rpc"
 Requires-Dist: uvicorn (>=0.35) ; extra == "rpc"
 Description-Content-Type: text/markdown

{sincpro_framework-3.7.0 → sincpro_framework-3.7.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "sincpro-framework"
-version = "3.7.0"
+version = "3.7.2"
 description = "Sincpro framework to use DDD, Clean architecture, Hexagonal architecture"
 authors = ["Gutierrez Andres <andru1236@gmail.com>"]
 readme = "README.md"
@@ -27,6 +27,7 @@ fastmcp = {version = ">=3.0,<4", optional = true}
 starlette = {version = ">=1.0", optional = true}
 uvicorn = {version = ">=0.35", optional = true}
 sqlalchemy = {version = ">=2.0", optional = true}
+duckdb-engine = {version = "^0.17.0", optional = true}
 
 [tool.poetry.extras]
 opentelemetry = [
@@ -39,6 +40,7 @@ sentry = ["sentry-sdk"]
 mcp = ["fastmcp"]
 rpc = ["starlette", "uvicorn"]
 sqlalchemy = ["sqlalchemy"]
+duckdb = ["sqlalchemy", "duckdb-engine"]
 
 [tool.poetry.group.dev.dependencies]
 isort = "^9.0.1"

{sincpro_framework-3.7.0 → sincpro_framework-3.7.2}/sincpro_framework/bus.py

@@ -22,27 +22,28 @@ class FeatureBus(Bus):
         logger_bus: Logger = logger,  # type: ignore[assignment]
         observability: Optional[Observability] = None,
     ):
-        self.feature_registry: Dict[str, Feature] = dict()
+        self.feature_registry: Dict[type, Feature] = dict()
         self.handle_error: Optional[Callable] = None
         self.logger: Logger = logger_bus or logger  # type: ignore[assignment]
         self.observability = observability or Observability()
 
     def register_feature(self, dto: Type[DataTransferObject], feature: Feature) -> bool:
         """Register a feature to the bus"""
-        if dto.__name__ in self.feature_registry:
+        if dto in self.feature_registry:
             raise DTOAlreadyRegistered(
                 f"Data transfer object {dto.__name__} is already registered"
             )
 
         self.logger.info(f"Registering feature [{dto.__name__}]")
-        self.feature_registry[dto.__name__] = feature
+        self.feature_registry[dto] = feature
         return True
 
     def execute(  # type: ignore[override]
         self, dto: TypeDTO, return_type: Type[TypeDTOResponse] | None = None
     ) -> TypeDTOResponse | None:
         """Execute a feature, and handle error if exists error handler"""
-        dto_name = dto.__class__.__name__
+        dto_type = dto.__class__
+        dto_name = dto_type.__name__
 
         with self.observability.span(dto_name, "feature") as span:
             if is_logger_in_debug() or self.log_after_execution:
@@ -50,7 +51,7 @@ class FeatureBus(Bus):
             self.logger.debug(f"{dto_name}({dto})")
 
             try:
-                response = self.feature_registry[dto.__class__.__name__].execute(dto)
+                response = self.feature_registry[dto_type].execute(dto)
                 if response:
                     self.logger.debug(
                         f"Feature response {response.__class__.__name__}({response})",
@@ -74,7 +75,7 @@ class ApplicationServiceBus(Bus):
         logger_bus: Logger = logger,  # type: ignore[assignment]
         observability: Optional[Observability] = None,
     ):
-        self.app_service_registry: Dict[str, ApplicationService] = dict()
+        self.app_service_registry: Dict[type, ApplicationService] = dict()
         self.handle_error: Optional[Callable] = None
         self.logger = logger_bus or logger
         self.observability = observability or Observability()
@@ -85,20 +86,21 @@ class ApplicationServiceBus(Bus):
         """Register an application service to the bus
         This method is not used directly, the decorator inject_app_service_to_bus is used
         """
-        if dto.__name__ in self.app_service_registry:
+        if dto in self.app_service_registry:
             raise DTOAlreadyRegistered(
                 f"Data transfer object {dto.__name__} is already registered"
             )
 
         self.logger.info(f"Registering application service [{dto.__name__}]")
-        self.app_service_registry[dto.__name__] = app_service
+        self.app_service_registry[dto] = app_service
         return True
 
     def execute(  # type: ignore[override]
         self, dto: TypeDTO, return_type: Type[TypeDTOResponse] | None = None
     ) -> TypeDTOResponse | None:
         """Execute an application service, and handle error if exists error handler"""
-        dto_name = dto.__class__.__name__
+        dto_type = dto.__class__
+        dto_name = dto_type.__name__
 
         with self.observability.span(dto_name, "application_service") as span:
             if is_logger_in_debug() or self.log_after_execution:
@@ -106,7 +108,7 @@ class ApplicationServiceBus(Bus):
             self.logger.debug(f"{dto_name}({dto})")
 
             try:
-                response = self.app_service_registry[dto.__class__.__name__].execute(dto)
+                response = self.app_service_registry[dto_type].execute(dto)
                 if response:
                     self.logger.debug(
                         f"Application service response {response.__class__.__name__}({response})"
@@ -153,11 +155,12 @@ class FrameworkBus(Bus):
 
         intersection_dtos = registered_features.intersection(registered_app_services)
         if intersection_dtos:
+            intersection_names = {dto.__name__ for dto in intersection_dtos}
             self.logger.error(
-                f"Features and app services have the same name: {registered_features.intersection(registered_app_services)}",
+                f"Features and app services have the same DTO: {intersection_names}",
             )
             raise DTOAlreadyRegistered(
-                f"Data transfer object {intersection_dtos} is present in application services and features, Change "
+                f"Data transfer object {intersection_names} is present in application services and features, Change "
                 f"the name of the feature or create another framework instance to handle in doupled wat"
             )
 
@@ -170,21 +173,22 @@ class FrameworkBus(Bus):
         if the DTO is present in the app service bus
         otherwise will execute the DTO in the feature bus
         """
-        dto_name = dto.__class__.__name__
+        dto_type = dto.__class__
+        dto_name = dto_type.__name__
         try:
             if (
-                dto_name in self.app_service_bus.app_service_registry
-                and dto_name in self.feature_bus.feature_registry
+                dto_type in self.app_service_bus.app_service_registry
+                and dto_type in self.feature_bus.feature_registry
             ):
                 raise DTOAlreadyRegistered(
                     f"Data transfer object {dto_name} is present in application services and features, Change the "
                     f"name of the feature or create another framework instance to handle in doupled wat"
                 )
-            if dto_name in self.feature_bus.feature_registry:
+            if dto_type in self.feature_bus.feature_registry:
                 response = self.feature_bus.execute(dto)
                 return response
 
-            if dto_name in self.app_service_bus.app_service_registry:
+            if dto_type in self.app_service_bus.app_service_registry:
                 response = self.app_service_bus.execute(dto)
                 return response
 

{sincpro_framework-3.7.0 → sincpro_framework-3.7.2}/sincpro_framework/bus.pyi

@@ -21,7 +21,7 @@ class FeatureBus(Bus):
     """
 
     log_after_execution: bool
-    feature_registry: Dict[str, Feature]
+    feature_registry: Dict[type, Feature]
     handle_error: Optional[Callable[..., Any]]
     logger: LoggerProxy
     observability: Observability
@@ -52,7 +52,7 @@ class ApplicationServiceBus(Bus):
     """
 
     log_after_execution: bool
-    app_service_registry: Dict[str, ApplicationService]
+    app_service_registry: Dict[type, ApplicationService]
     handle_error: Optional[Callable[..., Any]]
     logger: LoggerProxy
     observability: Observability

{sincpro_framework-3.7.0 → sincpro_framework-3.7.2}/sincpro_framework/ddd/__init__.py

@@ -21,8 +21,8 @@ from sincpro_framework.ddd.criteria import (
     Specification,
 )
 from sincpro_framework.ddd.entity import (
-    Archivable,
-    Audited,
+    ArchivableMixin,
+    AuditedMixin,
     Entity,
     Translated,
     new_entity_id,
@@ -30,7 +30,7 @@ from sincpro_framework.ddd.entity import (
 )
 from sincpro_framework.ddd.entity_collection import Changes, Count, Dropped, EntityCollection
 from sincpro_framework.ddd.evaluate import matches
-from sincpro_framework.ddd.events import DomainEvent
+from sincpro_framework.ddd.events import DomainEvent, EventStatus, TrackableMixin
 from sincpro_framework.ddd.exceptions import (
     ContractViolation,
     DomainError,
@@ -48,8 +48,8 @@ from sincpro_framework.ddd.repository import Repository
 from sincpro_framework.ddd.value_object import ValueObject
 
 __all__ = [
-    "Archivable",
-    "Audited",
+    "ArchivableMixin",
+    "AuditedMixin",
     "Bucket",
     "BusResolver",
     "EntityCollection",
@@ -63,6 +63,7 @@ __all__ = [
     "Dropped",
     "DuplicateAggregate",
     "Entity",
+    "EventStatus",
     "FieldMeta",
     "FieldType",
     "InvalidCriteria",
@@ -84,6 +85,7 @@ __all__ = [
     "Specification",
     "RelationNotResolved",
     "StaleAggregate",
+    "TrackableMixin",
     "Translated",
     "ValueObject",
     "matches",

{sincpro_framework-3.7.0 → sincpro_framework-3.7.2}/sincpro_framework/ddd/criteria.py

@@ -15,7 +15,7 @@ from decimal import Decimal
 from enum import StrEnum
 from typing import Any, Union, cast
 
-from pydantic import Field, JsonValue, RootModel, field_validator
+from pydantic import Field, JsonValue, RootModel, field_validator, model_validator
 
 from sincpro_framework.ddd.exceptions import InvalidCriteria
 from sincpro_framework.ddd.pagination import Cursor, Pagination
@@ -209,47 +209,93 @@ def parse_order(raw: str) -> tuple[Sort, ...]:
     )
 
 
-FOLD_FUNCTIONS: tuple[str, ...] = ("sum", "avg", "min", "max", "count")
-"""The aggregates a fold may ask for. A closed list, because the name reaches SQL: anything
-outside it is refused before a statement exists."""
+MEASURE_FUNCTIONS: tuple[str, ...] = (
+    "sum",
+    "avg",
+    "min",
+    "max",
+    "count",
+    "count_distinct",
+    "percentile",
+)
+"""The five functions a measure may ask for. A closed list, because the name reaches SQL:
+anything outside it is refused before a statement exists. Adding one is a change here, not a
+string a caller can invent."""
+
 
+class Measure(DataTransferObject):
+    """One number a group answers: a function over a field, under a name the caller chose.
 
-class Fold(DataTransferObject):
-    """One number folded out of a bucket's rows.
+        in      {"function": "sum", "field": "row_count"}
+        out     Measure(function='sum', field='row_count')       → sum(row_count) AS <name>
 
-        in      ["sum", "row_count"]
-        out     Fold(function='sum', field='row_count')       → sum(row_count) AS <name>
+    **Named parts and not `"sum:row_count"`**, so nobody has to split a string in whatever
+    language is reading this — the same reason a condition travels as `{field, operator,
+    value}`. The pair `["sum", "row_count"]` is read as well, because writing one by hand in
+    Python is a pair; what a caller sends over a wire is the object.
 
-    A pair and not `"sum:row_count"`, so nobody has to split a string — the same reason a
-    condition is written as a triple.
+    It is called a measure and not an aggregate on purpose: in this codebase an *aggregate* is
+    the DDD root — what `Meta.aggregate` names — and two meanings for one word in the same
+    sentence is how a reader loses an afternoon.
     """
 
     function: str
     field: str
 
+    argument: float | None = None
+    """What the function needs besides a column, when it needs anything.
+
+    Only `percentile` does: the fraction it cuts at, `0.5` for the median and `0.95` for a P95.
+    Every other measure refuses one rather than ignoring it, because a number that is quietly
+    dropped is a report that is quietly wrong."""
+
     @field_validator("function")
     @classmethod
     def _one_of_the_known_aggregates(cls, function: str) -> str:
-        if function not in FOLD_FUNCTIONS:
+        if function not in MEASURE_FUNCTIONS:
             raise InvalidCriteria(
-                f"'{function}' is not a fold; use one of {', '.join(FOLD_FUNCTIONS)}"
+                f"'{function}' is not a measure; use one of {', '.join(MEASURE_FUNCTIONS)}"
             )
         return function
 
+    @model_validator(mode="after")
+    def _the_argument_belongs_to_the_function(self) -> "Measure":
+        """`percentile` needs its fraction; nothing else takes one.
+
+        >>> Measure(function="percentile", field="debit", argument=0.95)
+        Measure(function='percentile', field='debit', argument=0.95)
+        >>> Measure(function="sum", field="debit", argument=0.95)
+        InvalidCriteria: 'sum' takes no argument
+        """
+        if self.function == "percentile":
+            if self.argument is None or not 0 < self.argument < 1:
+                raise InvalidCriteria(
+                    "a percentile is cut at a fraction between 0 and 1, e.g. 0.5 for the "
+                    f"median; got {self.argument!r}"
+                )
+        elif self.argument is not None:
+            raise InvalidCriteria(f"'{self.function}' takes no argument")
+        return self
+
     @classmethod
-    def read(cls, written: Any) -> "Fold":
-        """A fold as it comes in JSON: the pair, and nothing else.
+    def read(cls, written: Any) -> "Measure":
+        """A measure as it comes in: the object on the wire, or the pair written by hand.
 
-        >>> Fold.read(["sum", "row_count"])
-        Fold(function='sum', field='row_count')
+        >>> Measure.read({"function": "sum", "field": "row_count"})
+        Measure(function='sum', field='row_count')
+        >>> Measure.read(["sum", "row_count"])
+        Measure(function='sum', field='row_count')
         """
-        if isinstance(written, Fold):
+        if isinstance(written, Measure):
             return written
         if isinstance(written, dict):
             return cls(**written)
-        if not isinstance(written, list) or len(written) != 2 or not all(written):
+        # A tuple as much as a list: a pair written in Python is `("sum", "row_count")` and
+        # the same pair read from JSON is a list. They mean the same measure.
+        if not isinstance(written, (list, tuple)) or len(written) != 2 or not all(written):
             raise InvalidCriteria(
-                f"a fold is written [function, field], e.g. ['sum', 'row_count']; got {written!r}"
+                "a measure is written {'function': …, 'field': …}, or as the pair "
+                f"['sum', 'row_count']; got {written!r}"
             )
         return cls(function=written[0], field=written[1])
 
@@ -283,7 +329,7 @@ class Level(DataTransferObject):
 class Grouping(DataTransferObject):
     """How a result set is split: the levels, and the numbers folded out of every group.
 
-        in      {"by": ["produced_by", "registered_at:month"], "totals": {"filas": ["sum", "row_count"]}}
+        in      {"by": ["produced_by", "registered_at:month"], "measures": {"filas": ["sum", "row_count"]}}
         out     every level `by` names, each group counted and folded, carrying how to open it
 
     All the levels named are answered, one statement each: grouping by three fields is three
@@ -292,18 +338,24 @@ class Grouping(DataTransferObject):
     has to know how deep the whole tree is.
     """
 
-    by: tuple[Level, ...] = ()
-    totals: dict[str, Fold] = {}
+    group_by: tuple[Level, ...] = ()
+    """The levels the set is split by, one statement each."""
+
+    measures: dict[str, Measure] = {}
+    """The numbers every group answers, each under a name the caller chose."""
+
+    where_measures: Expression | None = None
+    """A filter over what the groups measured, not over the rows: `count > 10`, `debit > 1000`.
 
-    having: Expression | None = None
-    """A filter over what the groups fold, not over the rows: `count > 10`, `debit > 1000`.
-    The names it may use are the ones in `totals` plus `count`; `where` filters the rows that
-    make the groups, `having` filters the groups the rows made."""
+    The names it may use are the ones in `measures` plus `count`. `where` filters the rows that
+    make the groups; this filters the groups those rows made — which is why it is not called
+    `where`: it reads measures, not fields."""
 
     order: tuple[Sort, ...] = ()
-    """How the groups of each level come back: by the level's own field, by a name in `totals`
+    """How the groups of each level come back: by the level's own field, by a name in `measures`
     or by `count`. Empty means by the level's field, ascending, which is how a list of groups
-    reads when nobody asked for anything else."""
+    reads when nobody asked for anything else. It orders the GROUPS; `Criteria.order` orders
+    the rows, and with a page asked for it decides which rows each group shows first."""
 
     pagination: Pagination | None = None
     """How many groups of the FIRST level come back, and from where. `None`, the default, is
@@ -317,7 +369,7 @@ class Grouping(DataTransferObject):
     def paged(self) -> bool:
         """Whether only some of the groups were asked for.
 
-        >>> Grouping(by=(Level(field="a"),)).paged
+        >>> Grouping(group_by=(Level(field="a"),)).paged
         False
         """
         return self.pagination is not None
@@ -329,14 +381,14 @@ class Grouping(DataTransferObject):
         >>> Grouping().asked
         False
         """
-        return bool(self.by)
+        return bool(self.group_by)
 
 
 class Bucket(DataTransferObject):
     """One group: what its rows share, how many there are, and how to see them.
 
         out     Bucket(field='produced_by', value=None, count=187,
-                       totals={'filas': 4012933}, criteria=Criteria(where=…))
+                       measures={'filas': 4012933}, criteria=Criteria(where=…))
 
     `criteria` is the whole point. It is this reading plus «and this bucket's value», so
     opening the group is `self.repository.search(Dataset, bucket.criteria)` and nothing else — no client
@@ -356,7 +408,7 @@ class Bucket(DataTransferObject):
     field: str
     value: Any
     count: int
-    totals: dict[str, Any] = {}
+    measures: dict[str, Any] = {}
     criteria: "Criteria"
     ids: list[Any] = []
     """The identities of this group's first page, in the criteria's order; empty unless the
@@ -371,7 +423,7 @@ class PivotCell(DataTransferObject):
     """One cell of a pivot: what its rows share on both axes, how many there are, and the
     numbers folded out of them.
 
-        out     PivotCell(row=['SAL'], column=['2026-01'], count=412, totals={'debit': …})
+        out     PivotCell(row=['SAL'], column=['2026-01'], count=412, measures={'debit': …})
 
     A margin is a cell with one axis empty: `column=[]` is the whole row, `row=[]` the whole
     column, and both empty is the grand total.
@@ -380,14 +432,14 @@ class PivotCell(DataTransferObject):
     row: list[Any] = []
     column: list[Any] = []
     count: int = 0
-    totals: dict[str, Any] = {}
+    measures: dict[str, Any] = {}
 
 
 class Pivot(DataTransferObject):
     """A table of groups crossed by groups: rows down one axis, columns across the other, a
     folded cell where they meet.
 
-        in      rows=[journal_id], columns=[posted_at:month], totals={'debit': sum debit}
+        in      rows=[journal_id], columns=[posted_at:month], measures={'debit': sum debit}
         out     Pivot(rows=[['SAL'], ['PUR']], columns=[['2026-01'], ['2026-02']], cells=[…])
 
     `rows` and `columns` are every key that appeared, in order, so a client renders the grid
@@ -544,21 +596,22 @@ class Criteria(DataTransferObject):
     @field_validator("grouping", mode="before")
     @classmethod
     def _reads_the_grouping(cls, value: Any) -> Any:
-        """The levels and the folds of the object, each to its type.
+        """The levels and the measures of the object, each to its type.
 
-        in      {"by": [{"field": "produced_by"}], "totals": {"filas": ["sum", "row_count"]}}
-        out     Grouping(by=(Level(produced_by),), totals={'filas': Fold(sum, row_count)})
+        in      {"by": [{"field": "produced_by"}], "measures": {"filas": ["sum", "row_count"]}}
+        out     Grouping(by=(Level(produced_by),), measures={'filas': Measure(sum, row_count)})
         """
         if isinstance(value, dict):
             value = dict(value)
-            if "by" in value:
-                value["by"] = tuple(Level.read(one) for one in value["by"])
-            if "totals" in value:
-                value["totals"] = {
-                    name: Fold.read(fold) for name, fold in (value["totals"] or {}).items()
+            if "group_by" in value:
+                value["group_by"] = tuple(Level.read(one) for one in value["group_by"])
+            if "measures" in value:
+                value["measures"] = {
+                    name: Measure.read(measure)
+                    for name, measure in (value["measures"] or {}).items()
                 }
-            if "having" in value:
-                value["having"] = expression_from(value["having"])
+            if "where_measures" in value:
+                value["where_measures"] = expression_from(value["where_measures"])
             if isinstance(value.get("order"), str):
                 value["order"] = parse_order(value["order"])
         return value

{sincpro_framework-3.7.0 → sincpro_framework-3.7.2}/sincpro_framework/ddd/entity.py

@@ -26,13 +26,17 @@ Python 3.12 and 3.13 have no `uuid.uuid7`; `uuid7()` below is RFC 9562 by hand a
 the standard library where it exists.
 """
 
+import dataclasses
 import os
 import threading
 import time
 import uuid
 from dataclasses import dataclass, field
 from datetime import UTC, datetime
-from typing import TYPE_CHECKING, NotRequired, TypedDict
+from functools import lru_cache
+from typing import TYPE_CHECKING, Any, NotRequired, TypedDict
+
+from pydantic import TypeAdapter
 
 if TYPE_CHECKING:
     from sincpro_framework.ddd.events import DomainEvent
@@ -40,6 +44,11 @@ if TYPE_CHECKING:
 RECORDED = "_recorded_events"
 
 
+@lru_cache(maxsize=None)
+def json_serializer(cls: type) -> TypeAdapter:
+    return TypeAdapter(cls)
+
+
 _MINTING = threading.Lock()
 _last_millisecond = 0
 _counter = 0
@@ -90,11 +99,11 @@ def utc_now() -> datetime:
 
 
 @dataclass(kw_only=True)
-class Audited:
+class AuditedMixin:
     """Who wrote the record, beside when: a mixin an aggregate opts into.
 
         @dataclass
-        class Invoice(Audited, Entity):
+        class Invoice(AuditedMixin, Entity):
             number: str
 
     Nobody writes these two. The adapter stamps them on every flush from the actor the
@@ -110,11 +119,11 @@ class Audited:
 
 
 @dataclass(kw_only=True)
-class Archivable:
+class ArchivableMixin:
     """Put away rather than deleted: a mixin an aggregate opts into.
 
         @dataclass
-        class Account(Archivable, Entity):
+        class Account(ArchivableMixin, Entity):
             code: str
 
         repository.remove(account)          →  archived_at stamped, the row stays
@@ -222,12 +231,11 @@ class Entity:
         announce facts a rollback then undoes.
         """
         recorded: list[DomainEvent] = self.__dict__.setdefault(RECORDED, [])
-        stamped = event.model_copy(
-            update={
-                "aggregate_type": event.aggregate_type or type(self).__name__,
-                "aggregate_id": event.aggregate_id or self.id,
-                "sequence": len(recorded),
-            }
+        stamped = dataclasses.replace(
+            event,
+            entity_type=event.entity_type or type(self).__name__,
+            entity_id=event.entity_id or self.id,
+            sequence=len(recorded),
         )
         recorded.append(stamped)
         return stamped
@@ -242,3 +250,29 @@ class Entity:
         """
         recorded = self.__dict__.pop(RECORDED, [])
         return list(recorded)
+
+    def as_json(self) -> str:
+        """This entity as JSON text.
+
+        >>> Note(title="x").as_json()
+        '{"id":"...","created_at":"...","title":"x"}'
+        """
+        return json_serializer(type(self)).dump_json(self).decode()
+
+    @classmethod
+    def from_json(cls, data: "str | dict[str, Any]") -> "Any":
+        """Rebuilds an instance from JSON text or an already-parsed dict — either is
+        accepted, so a caller that already has the dict (a DB row, another service's
+        response) never has to round-trip it through a string first.
+
+        >>> Note.from_json('{"title": "x"}')
+        Note(title='x')
+        >>> Note.from_json({"title": "x"})
+        Note(title='x')
+        """
+        adapter = json_serializer(cls)
+        return (
+            adapter.validate_json(data)
+            if isinstance(data, str)
+            else adapter.validate_python(data)
+        )

{sincpro_framework-3.7.0 → sincpro_framework-3.7.2}/sincpro_framework/ddd/entity_collection.py

@@ -275,13 +275,13 @@ class EntityCollection[T]:
         """The values an aggregation is about, once it is established that it may answer.
 
         complete   EntityCollection([a(2), b(3)]) → [2, 3]
-        partial    a page of 20 out of 8412 → ContractViolation, naming `self.repository.totals(...)`
+        partial    a page of 20 out of 8412 → ContractViolation, naming `self.repository.measures(...)`
         """
         if self.is_partial:
             raise ContractViolation(
                 f"{name} would answer about {len(self.items)} records out of "
                 f"{self.count or 'more'}; ask the engine instead, which folds the whole "
-                f"result set: self.repository.totals(<aggregate>, criteria, total='sum:<field>')"
+                f"result set: self.repository.measures(<aggregate>, criteria, total=('sum', '<field>'))"
             )
         return [selector(record) for record in self.items]
 
@@ -543,7 +543,7 @@ class EntityCollection[T]:
 
         in      EntityCollection([a(2), b(3)]) complete, lambda x: x.size
         out     5
-        but     a page of 20 out of 8412 raises: ask `self.repository.totals(...)` instead
+        but     a page of 20 out of 8412 raises: ask `self.repository.measures(...)` instead
         """
         return sum(self._fold("sum_by", selector))