feat: add pyfly.domain DDD primitives + OrderService sample (v26.05.02) (#8)

Adds the DDD building blocks that mirror fireflyframework-starter-domain
(Java) and FireflyFramework.Starter.Domain (.NET), plus a complete
OrderService sample that exercises every primitive end-to-end.

pyfly.domain (new module, zero runtime dependencies)

- Entity[TID]: identity-based equality, transient/persisted distinction,
  (type, id) hashing.
- ValueObject: marker base for @DataClass(frozen=True) records with
  structural equality, immutability, replace() helper.
- AggregateRoot[TID]: extends Entity[TID] with a pending_events buffer
  (raise_event / pending_events / clear_events). Distinct from the
  event-sourced pyfly.eventsourcing.AggregateRoot; both coexist.
- DomainEvent: frozen-dataclass base with auto-assigned UUID event_id,
  UTC occurred_at, and event_type defaulted to the subclass name.
- Specification[T]: composable in-memory predicate with & / | / ~
  combinators and a Specification.of(callable) factory.
- DomainRepository[A, TID]: runtime-checkable collection-like protocol
  (add, find, remove, next_id).
- DomainException, BusinessRuleViolation (DOMAIN_RULE_VIOLATION),
  AggregateNotFound (DOMAIN_AGGREGATE_NOT_FOUND): extend
  pyfly.kernel.BusinessException so the existing RFC 7807 mappers
  translate them automatically.
- pyfly.starters.domain re-exports every primitive alongside
  enable_domain_stack so a single import line is enough for a
  domain-tier service.

OrderService sample (samples/order_service/)

Mirrors the layered split used by Java domain microservices in
firefly-oss and the .NET FireflyFramework.Samples.OrdersService:

  interfaces/    DTOs + enums (PlaceOrderRequest, OrderDto, OrderStatus)
  models/        Order aggregate root + repository (port + InMemory adapter)
  core/          Commands, queries, handlers, mapper, ConfirmOrderSaga
  web/           @rest_controller for /api/v1/orders
  sdk/           Typed httpx-based client
  app.py         @pyfly_application + @enable_domain_stack

Order is a real AggregateRoot[str] with state-machine invariants
enforced by BusinessRuleViolation. PlaceOrderHandler creates and
persists the aggregate and publishes its pending events.
ConfirmOrderSaga walks the order through PLACED ->
INVENTORY_RESERVED -> PAID -> SHIPPED with full compensation via
three stub external services (InventoryService, PaymentService,
ShippingService). 13/13 end-to-end tests pass against the real CQRS
bus and saga engine -- no mocks.

Fixed: async saga and TCC step support

@saga_step / @try_method / @confirm_method / @cancel_method used to
wrap the target with a synchronous functools.wraps adapter that masked
inspect.iscoroutinefunction. The engine therefore called async def
steps without await and the actual coroutine never ran. The wrappers
were no-ops; metadata is now attached directly to the original
function. Regression test pinned in
tests/transactional/saga/test_async_steps.py.

Versioning

- pyproject.toml: 26.5.1 -> 26.5.2
- pyfly.__version__: 26.05.01 -> 26.05.02
- install.sh PYFLY_VERSION: 26.05.01 -> 26.05.02
- README badge, install URLs, "Current" section, Modules count (38 -> 39)
- ROADMAP marks Phase 4 DDD as complete; Backoffice and Utils planned
- CHANGELOG.md adds v26.05.02 entry
- New module guide docs/modules/domain.md

42 new tests (35 domain + 1 async-saga regression + 13 sample). All
existing tests still pass (1279 in the impacted slices).

Co-authored-by: Andrés Contreras Guillén <ancongui@Andress-MacBook-Pro.local>

Author: ancongui

CHANGELOG.md

@@ -6,6 +6,92 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## v26.05.02 (2026-05-08)
+
+### Added — `pyfly.domain` DDD building blocks
+
+A new pure-Python module that mirrors `fireflyframework-starter-domain`
+(Java) and `FireflyFramework.Starter.Domain` (.NET). Zero runtime
+dependencies — just standard-library Python — so it imports from any
+layer of the application.
+
+- **`pyfly.domain.Entity[TID]`** — base class with identity-based
+  equality, transient-vs-persisted distinction, and `(type, id)` hashing.
+- **`pyfly.domain.ValueObject`** — marker base for `@dataclass(frozen=True)`
+  records with structural equality, immutability, and a uniform
+  `replace(...)` helper.
+- **`pyfly.domain.AggregateRoot[TID]`** — extends `Entity[TID]` with a
+  `pending_events` buffer plus `raise_event` / `pending_events` /
+  `clear_events`. Distinct from the event-sourced
+  `pyfly.eventsourcing.AggregateRoot`; both coexist.
+- **`pyfly.domain.DomainEvent`** — frozen-dataclass base that
+  auto-assigns a UUID `event_id` and UTC `occurred_at` timestamp; the
+  `event_type` property defaults to the subclass name.
+- **`pyfly.domain.Specification[T]`** — composable in-memory predicate
+  with `&` / `|` / `~` combinators and a `Specification.of(callable)`
+  factory.
+- **`pyfly.domain.DomainRepository[A, TID]`** — runtime-checkable
+  collection-like protocol (`add`, `find`, `remove`, `next_id`).
+- **`pyfly.domain.DomainException`** + **`BusinessRuleViolation`**
+  (`code="DOMAIN_RULE_VIOLATION"`) + **`AggregateNotFound`**
+  (`code="DOMAIN_AGGREGATE_NOT_FOUND"`) — extend
+  `pyfly.kernel.BusinessException` so existing RFC 7807 mappers,
+  filters, and `@controller_advice` handlers translate them
+  automatically.
+- **`pyfly.starters.domain`** now re-exports every primitive above
+  alongside `enable_domain_stack`, so a single import line is enough
+  for a domain-tier service.
+
+### Added — OrderService sample
+
+`samples/order_service/` is a complete, runnable DDD microservice that
+mirrors the layered split used by Java domain services in
+[`firefly-oss`](https://github.com/firefly-oss) and the .NET
+`FireflyFramework.Samples.OrdersService`:
+
+```
+samples/order_service/
+├── interfaces/         DTOs + enums (PlaceOrderRequest, OrderDto, OrderStatus)
+├── models/             Order aggregate root + repository (port + in-memory adapter)
+├── core/               Commands, queries, handlers, mapper, ConfirmOrderSaga
+├── web/                @rest_controller exposing /api/v1/orders
+├── sdk/                Typed httpx-based client
+└── app.py              @pyfly_application + @enable_domain_stack
+```
+
+`Order` is a real `AggregateRoot[str]` with state-machine invariants
+enforced by `BusinessRuleViolation`. `PlaceOrderHandler` creates and
+persists the aggregate and publishes its pending events.
+`ConfirmOrderSaga` walks the order through
+`PLACED → INVENTORY_RESERVED → PAID → SHIPPED` with full compensation
+via three stub external services (`InventoryService`, `PaymentService`,
+`ShippingService`). 13/13 end-to-end tests pass against the real CQRS
+bus and saga engine — no mocks.
+
+### Fixed — async saga and TCC step support
+
+The `@saga_step`, `@try_method`, `@confirm_method`, and `@cancel_method`
+decorators used to wrap the target function with a synchronous
+`functools.wraps` adapter. That made `inspect.iscoroutinefunction`
+return `False` for `async def` steps, so the engine called them
+without `await` and the actual coroutine never ran. The wrappers were
+no-ops (they just forwarded args to the original); they have been
+removed and the metadata is now attached directly to the original
+function. Regression test added at
+`tests/transactional/saga/test_async_steps.py`.
+
+### Documentation
+
+- New module guide [`docs/modules/domain.md`](docs/modules/domain.md)
+  with end-to-end examples for every primitive.
+- README adds a "Domain — DDD Building Blocks" section to the
+  Featured Patterns and a row to the Modules table; module count
+  updated from 38 to 39.
+- ROADMAP marks Phase 4 DDD as complete; Backoffice and Utils remain
+  planned.
+
+---
+
 ## v26.05.01 (2026-05-07)
 
 ### CalVer migration

README.md

@@ -11,7 +11,7 @@
   <a href="https://github.com/fireflyframework"><img src="https://img.shields.io/badge/Firefly_Framework-official-ff6600?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0id2hpdGUiIGQ9Ik0xMiAyQzYuNDggMiAyIDYuNDggMiAxMnM0LjQ4IDEwIDEwIDEwIDEwLTQuNDggMTAtMTBTMTcuNTIgMiAxMiAyeiIvPjwvc3ZnPg==" alt="Firefly Framework"></a>
   <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.12%2B-blue?logo=python&logoColor=white" alt="Python 3.12+"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-green" alt="License: Apache 2.0"></a>
-  <a href="#"><img src="https://img.shields.io/badge/version-26.05.01-brightgreen" alt="Version: 26.05.01"></a>
+  <a href="#"><img src="https://img.shields.io/badge/version-26.05.02-brightgreen" alt="Version: 26.05.02"></a>
   <a href="#"><img src="https://img.shields.io/badge/type--checked-mypy%20strict-blue?logo=python&logoColor=white" alt="Type Checked: mypy strict"></a>
   <a href="#"><img src="https://img.shields.io/badge/code%20style-ruff-purple?logo=ruff&logoColor=white" alt="Code Style: Ruff"></a>
   <a href="#"><img src="https://img.shields.io/badge/async-first-brightgreen" alt="Async First"></a>
@@ -732,6 +732,68 @@ class StripePayment(PaymentMethod):
 
 The plugin manager resolves the dependency graph, loads plugins in order, and registers extensions with the DI container. See [docs/modules/plugins.md](docs/modules/plugins.md).
 
+### Domain — DDD Building Blocks
+
+`pyfly.domain` ships the foundational types every domain-driven design codebase ends up reinventing — `Entity`, `ValueObject`, `AggregateRoot`, `DomainEvent`, `Specification`, `DomainRepository`, and domain-flavoured exceptions. The module is **pure standard-library Python** with zero runtime dependencies.
+
+```python
+from dataclasses import dataclass
+from pyfly.domain import AggregateRoot, BusinessRuleViolation, DomainEvent, ValueObject
+
+@dataclass(frozen=True, slots=True)
+class Money(ValueObject):
+    amount: int
+    currency: str
+
+@dataclass(frozen=True)
+class OrderShipped(DomainEvent):
+    order_id: str = ""
+    tracking_number: str = ""
+
+class Order(AggregateRoot[str]):
+    def __init__(self, id: str, total: Money) -> None:
+        super().__init__(id)
+        self.total = total
+        self.status = "placed"
+
+    def ship(self, tracking_number: str) -> None:
+        if self.status == "shipped":
+            raise BusinessRuleViolation("order-already-shipped")
+        self.status = "shipped"
+        assert self.id is not None
+        self.raise_event(OrderShipped(order_id=self.id, tracking_number=tracking_number))
+
+# Application service:
+order = Order("o-1", Money(100, "EUR"))
+order.ship("trk-42")
+
+events = order.clear_events()      # drained by the repository
+# repository.save(order); for e in events: bus.publish(e)
+```
+
+For domain-tier microservices, the **`@enable_domain_stack`** starter activates CQRS, the transactional engine (saga/workflow/TCC), event sourcing, the rule engine, and the relational data layer in a single decorator — mirroring `fireflyframework-starter-domain` (Java) and `AddFireflyDomain` (.NET):
+
+```python
+from pyfly.core import pyfly_application
+from pyfly.starters.domain import enable_domain_stack
+
+@enable_domain_stack
+@pyfly_application(name="my-service", scan_packages=["my_service"])
+class Application:
+    pass
+```
+
+The full DDD primitives are also re-exported from `pyfly.starters.domain` so a single import line is enough:
+
+```python
+from pyfly.starters.domain import (
+    AggregateRoot, BusinessRuleViolation, DomainEvent, DomainRepository,
+    Entity, Specification, ValueObject, enable_domain_stack,
+)
+```
+
+See **[`samples/order_service/`](samples/order_service/README.md)** for an end-to-end DDD microservice that uses every primitive: layered split (interfaces / models / core / web / sdk), a real `Order` aggregate that protects its invariants, CQRS handlers, and a `ConfirmOrderSaga` that walks the order through `PLACED → INVENTORY_RESERVED → PAID → SHIPPED` with full compensation. See [docs/modules/domain.md](docs/modules/domain.md).
+
 ---
 
 ## Installation
@@ -742,13 +804,13 @@ The plugin manager resolves the dependency graph, loads plugins in order, and re
 
 ```bash
 # Install the latest release (uv)
-uv add "pyfly @ https://github.com/fireflyframework/fireflyframework-pyfly/releases/latest/download/pyfly-26.5.1-py3-none-any.whl"
+uv add "pyfly @ https://github.com/fireflyframework/fireflyframework-pyfly/releases/latest/download/pyfly-26.5.2-py3-none-any.whl"
 
 # Install with specific extras
-uv add "pyfly[web,data-relational,cache] @ https://github.com/fireflyframework/fireflyframework-pyfly/releases/latest/download/pyfly-26.5.1-py3-none-any.whl"
+uv add "pyfly[web,data-relational,cache] @ https://github.com/fireflyframework/fireflyframework-pyfly/releases/latest/download/pyfly-26.5.2-py3-none-any.whl"
 
 # Or with pip
-pip install "pyfly @ https://github.com/fireflyframework/fireflyframework-pyfly/releases/latest/download/pyfly-26.5.1-py3-none-any.whl"
+pip install "pyfly @ https://github.com/fireflyframework/fireflyframework-pyfly/releases/latest/download/pyfly-26.5.2-py3-none-any.whl"
 ```
 
 ### One-Line Install (CLI + Framework)
@@ -925,7 +987,7 @@ See the full [CLI Reference](docs/cli.md) for details.
 
 ## Modules
 
-PyFly ships with **38 fully-implemented modules** organized into five layers — covering everything from HTTP routing and database access to distributed transactions, event sourcing, identity, content management, and observability:
+PyFly ships with **39 fully-implemented modules** organized into five layers — covering everything from HTTP routing and database access to distributed transactions, event sourcing, identity, content management, observability, and DDD building blocks:
 
 ### Foundation Layer
 
@@ -964,6 +1026,7 @@ PyFly ships with **38 fully-implemented modules** organized into five layers —
 | **Shell** | CLI commands, interactive REPL, runners | Spring Shell |
 | **Transactional** | Saga + Workflow + TCC orchestration: signal-driven, DAG, compensation, multi-backend persistence, DLQ, recovery | `fireflyframework-orchestration` |
 | **Event Sourcing** | AggregateRoot, EventStore, snapshots, transactional outbox, projections, upcasting | `fireflyframework-eventsourcing` |
+| **Domain (DDD)** | `Entity`, `ValueObject`, `AggregateRoot`, `DomainEvent`, `Specification`, `DomainRepository`, `BusinessRuleViolation` | `fireflyframework-starter-domain` |
 | **Plugins** | `@plugin` / `@extension_point` / `@extension`, dependency-ordered lifecycle | `fireflyframework-plugins` |
 | **Rule Engine** | YAML DSL, AST evaluator, batch evaluation, rule-set repository | `fireflyframework-rule-engine` |
 | **Config Server** | Spring Cloud Config Server analogue + client | `fireflyframework-config-server` |
@@ -1017,6 +1080,7 @@ Browse all guides in the [Module Guides Index](docs/modules/README.md):
 - [Custom Actuator Endpoints](docs/modules/custom-actuator-endpoints.md) — Build your own actuator endpoints
 - [Transactional Engine](docs/modules/transactional.md) — Saga, Workflow, and TCC distributed transaction patterns
 - [Event Sourcing](docs/modules/eventsourcing.md) — Aggregates, event store, snapshots, outbox, projections
+- [Domain (DDD primitives)](docs/modules/domain.md) — Entity, ValueObject, AggregateRoot, DomainEvent, Specification, DomainRepository, exceptions
 - [Plugins](docs/modules/plugins.md) — Plugin SPI, extension points, lifecycle
 - [Rule Engine](docs/modules/rule-engine.md) — YAML DSL, AST evaluator, batch evaluation
 - [Callbacks (outbound)](docs/modules/callbacks.md) — Dispatch domain events to external HTTP endpoints
@@ -1045,7 +1109,7 @@ See **[ROADMAP.md](ROADMAP.md)** for the full roadmap toward feature parity with
 | **Phase 1** | Core Distributed Patterns | Saga/TCC, Workflow, Event Sourcing | Complete (v26.05.01) |
 | **Phase 2** | Business Logic | Rule Engine, Plugins | Complete (v26.05.01) |
 | **Phase 3** | Enterprise Integrations | Notifications, IDP, ECM, Webhooks, Callbacks, Config Server | Complete (v26.05.01) |
-| **Phase 4** | Administrative | Backoffice, Utils, DDD starters | Planned |
+| **Phase 4** | Administrative & DDD | Backoffice, Utils, ~~DDD starters~~ (done in v26.05.02) | DDD complete; backoffice / utils planned |
 
 **v26.05.01** closes the parity gap with the Java Firefly Framework: the transactional engine has been rewritten from scratch (Saga + Workflow + TCC), nine new modules have been added (Event Sourcing, Callbacks, Webhooks, Notifications, IDP, ECM, Plugins, Rule Engine, Config Server), 12 third-party adapters were added, four new client protocols (SOAP/gRPC/GraphQL/WebSocket) were introduced, and the validation library now ships 16 domain validators. The framework is feature-complete for production microservice workloads.
 
@@ -1071,7 +1135,13 @@ The git tag and human-readable display use the leading-zero form (`v26.05.01`);
 
 See **[CHANGELOG.md](CHANGELOG.md)** for detailed release notes.
 
-**Current:** `v26.05.01` (2026-05-07) — Full Java framework parity. Highlights:
+**Current:** `v26.05.02` (2026-05-08) — DDD primitives + OrderService sample + async-saga fix:
+
+- **`pyfly.domain`** — pure-Python DDD building blocks: `Entity`, `ValueObject`, `AggregateRoot`, `DomainEvent`, `Specification` (with `&` / `|` / `~` combinators), `DomainRepository` protocol, `DomainException` / `BusinessRuleViolation` / `AggregateNotFound`. Mirrors `fireflyframework-starter-domain` (Java) and `FireflyFramework.Starter.Domain` (.NET).
+- **OrderService sample** — `samples/order_service/` is a complete DDD-flavoured microservice with the same layered split (interfaces / models / core / web / sdk) used by the firefly-oss Java services and the .NET OrdersService sample. Includes a real `Order` aggregate, CQRS handlers, and a `ConfirmOrderSaga` that walks the order through `PLACED → INVENTORY_RESERVED → PAID → SHIPPED` with full compensation. 13/13 tests pass end-to-end.
+- **Async-saga fix** — `@saga_step` / `@try_method` / `@confirm_method` / `@cancel_method` no longer wrap the function with a sync adapter that masked `inspect.iscoroutinefunction`. `async def` saga and TCC steps are now correctly awaited by the engine. Regression test pinned in `tests/transactional/saga/test_async_steps.py`.
+
+**Previous:** `v26.05.01` (2026-05-07) — Full Java framework parity:
 
 - **Transactional engine rewrite** — `pyfly.transactional` now ships Saga + Workflow + TCC patterns on a shared core (DAG topology, retries with jitter, backpressure, idempotency, DLQ, recovery, REST controllers, health indicators)
 - **Nine new modules** — `eventsourcing`, `callbacks`, `webhooks`, `notifications`, `idp`, `ecm`, `plugins`, `rule_engine`, `config_server`

ROADMAP.md

@@ -4,11 +4,11 @@ PyFly's roadmap is driven by achieving feature parity with the full [Firefly Fra
 
 ---
 
-## Current State (v26.05.01)
+## Current State (v26.05.02)
 
-PyFly ships with **38 fully-implemented modules** covering the foundation, application, infrastructure, integration, and cross-cutting layers — including the rewritten transactional engine (Saga + Workflow + TCC), Event Sourcing, IDP, ECM, Notifications, Webhooks, Callbacks, Plugins, Rule Engine, and Config Server. See the [Changelog](CHANGELOG.md) for full details on what's included.
+PyFly ships with **39 fully-implemented modules** covering the foundation, application, infrastructure, integration, and cross-cutting layers — including the rewritten transactional engine (Saga + Workflow + TCC), Event Sourcing, IDP, ECM, Notifications, Webhooks, Callbacks, Plugins, Rule Engine, Config Server, and the new **`pyfly.domain` DDD primitives** (`v26.05.02`). See the [Changelog](CHANGELOG.md) for full details on what's included.
 
-Phases 1, 2, and 3 of the original roadmap have all landed in `v26.05.01`. Phase 4 is the remaining set.
+Phases 1, 2, and 3 of the original roadmap landed in `v26.05.01`. The **DDD starters** portion of Phase 4 landed in `v26.05.02`. Backoffice and Utils remain planned.
 
 ---
 
@@ -46,13 +46,13 @@ Phases 1, 2, and 3 of the original roadmap have all landed in `v26.05.01`. Phase
 
 ---
 
-## Phase 4 — Administrative & Infrastructure 🔄 **Planned**
+## Phase 4 — Administrative & DDD 🔄 **Partially complete (DDD done in v26.05.02)**
 
-| Module | Description | Java Source |
-|--------|-------------|-------------|
-| **Backoffice** | Admin/backoffice layer with impersonation and enhanced audit | [`fireflyframework-backoffice`](https://github.com/fireflyframework/fireflyframework-backoffice) |
-| **Domain (DDD starters)** | DDD building blocks — base entities, value objects, aggregate roots, domain events | [`fireflyframework-starter-domain`](https://github.com/fireflyframework/fireflyframework-starter-domain) |
-| **Utils** | Shared utility library — template rendering, filtering, common helpers | [`fireflyframework-utils`](https://github.com/fireflyframework/fireflyframework-utils) |
+| Module | Description | Java Source | Status |
+|--------|-------------|-------------|--------|
+| **Domain (DDD starters)** | `Entity[TID]`, `ValueObject`, `AggregateRoot[TID]`, `DomainEvent`, `Specification`, `DomainRepository`, `BusinessRuleViolation`, `AggregateNotFound`, plus the `enable_domain_stack` decorator. Pure-Python primitives with zero runtime dependencies. Includes a complete OrderService sample under `samples/order_service/`. | [`fireflyframework-starter-domain`](https://github.com/fireflyframework/fireflyframework-starter-domain) | Done in v26.05.02 |
+| **Backoffice** | Admin/backoffice layer with impersonation and enhanced audit | [`fireflyframework-backoffice`](https://github.com/fireflyframework/fireflyframework-backoffice) | Planned |
+| **Utils** | Shared utility library — template rendering, filtering, common helpers | [`fireflyframework-utils`](https://github.com/fireflyframework/fireflyframework-utils) | Planned |
 
 ---
 

docs/modules/README.md

@@ -105,6 +105,7 @@ Coordinate multi-step operations across services with automatic compensation and
 |-------|-------------------|
 | [Transactional Engine](transactional.md) | Saga (`@saga`, `@saga_step`), Workflow (`@workflow`, `@workflow_step`, `@wait_for_signal`, `@wait_for_timer`, `@child_workflow`), TCC (`@tcc`, `@tcc_participant`, `@try_method`, `@confirm_method`, `@cancel_method`), parameter injection (`Input`, `FromStep`, `Header`, `Variable`), 5 compensation policies, DAG execution, persistence (in-memory / Redis / SQLAlchemy / cache), recovery, dead-letter queue, scheduling, REST endpoints |
 | [Event Sourcing](eventsourcing.md) | `AggregateRoot`, `EventStore` (in-memory + SQLAlchemy), `SnapshotStore`, `TransactionalOutbox`, `Projection` / `ProjectionRunner`, `EventUpcaster`, `EventSourcedRepository` |
+| [Domain (DDD primitives)](domain.md) | `Entity[TID]`, `ValueObject`, `AggregateRoot[TID]`, `DomainEvent`, `Specification` (in-memory predicate), `DomainRepository` protocol, `DomainException` / `BusinessRuleViolation` / `AggregateNotFound`, `enable_domain_stack` |
 
 ---