python-ddd-framework 0.3.2__py3-none-any.whl → 0.4.0__py3-none-any.whl

python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/docs/development.md

@@ -9,14 +9,45 @@ Use this guide with the project's [architecture](architecture.md) and [working r
 From the application root:
 
 ```sh
-uv run pddd add module orders --dry-run
-uv run pddd add module orders
+pddd add module orders --dry-run
+pddd add module orders --template ddd
+pddd add module conversions --template basic
 ```
 
-The CLI generates `src/modules/orders/`, registers its application/persistence/HTTP modules in the Host, updates standard package metadata, and synchronizes dependencies. It also creates the module's README. Existing module directories are not overwritten. Repeat with another valid lowercase name when a separate business owner is needed.
+The CLI generates `backend/src/modules/orders/`, registers its application/persistence/HTTP modules in the Host, updates standard package metadata, and synchronizes dependencies. It also creates the module's README. Existing module directories are not overwritten. Repeat with another valid lowercase name when a separate business owner is needed.
+
+The default is `ddd`. `basic` instead wires one ordinary Module and its alias, with a synchronous `ConversionService` Protocol and `DefaultConversionService(ConversionService, TransientDependency)`. Each REQUEST resolution creates an instance. Its only files are package markers, `module.py`, the contract, implementation, and README; no providers, Domain, database, migration, seed, HTTP, or background resources are generated. A consuming Module declares a dependency and injects the interface. The basic README shows formal replacement through `post_configure`. Invalid template names are rejected before writes; both templates support dry-run and refuse overwrite.
 
 Read the generated module README before replacing the order example with your domain. The examples below assume an `orders` module; substitute your actual package and contract names. The application remains usable as a pure Host before adding a module.
 
+## Module layout and coding rules
+
+For `basic`, keep public interfaces in `contracts/` and implementations in `services/`, with the Module in `module.py`. All seven lifecycle hooks remain explicit; empty hooks use `pass`. Its synchronous conversion is unmarked, without automatic interception or HTTP. For `ddd`, read the module README and choose the owning layer and directory below, and inspect direct callers. Propose a standards change before adding a responsibility category or reversing a dependency.
+
+| Layer | Required responsibility directories |
+| --- | --- |
+| `domain_shared` | `constants`, `enums`, `errors`, `permissions`, `messages`, `value_objects` |
+| `domain` | `entities`, `value_objects`, `services`, `repositories`, `events`, `settings`, `seeding` |
+| `application_contracts` | `services`, `integration_services`, `inputs`, `views` |
+| `application` | `services`, `integration_services`, `background_jobs`, `background_workers`, `hosted_services`, `event_handlers`, `interceptors`, `caching`, `options`, `setting_handlers` |
+| `sqlalchemy` | `models`, `repositories`, `migrations` |
+| `http_api` | `routers`, `filters`, `websockets`, `models` |
+
+- Use specific `snake_case` file names such as `order_query_service.py` or `order_changed_handler.py`. Do not combine unrelated responsibilities into `orders.py` or `tasks.py`.
+- Give each independent service, handler, task, and lifecycle owner its own file. Group parts of one capability, such as `background_jobs/order_approval/payload.py` and `handler.py`, in a capability directory. Closely related small immutable values, enums, and exceptions may share a file; line count and class count are not splitting rules.
+- `module.py` declares dependencies, registrations, and lifecycle hooks. `__init__.py` marks a package; it owns no business code, metadata state, or compatibility re-exports. The ORM metadata owner lives in `sqlalchemy/models/base.py`.
+- User query, management, approval, and item operations belong in separate `services`. Internal reporting contracts and implementations go in their respective `integration_services`. Thread/SDK lifecycle owners go in `hosted_services`. Inputs and output projections go in `inputs` and `views`; transport-only models go in `http_api/models`.
+- Shared immutable values such as `Money` belong in `domain_shared/value_objects`; domain-only values such as `OrderTitle` belong in `domain/value_objects`. Both public DTOs and domain objects may reuse a shared value without Contracts depending on Domain. Keep a single definition owner. The generated Money example does not add monetary fields to the sample HTTP contract.
+- Preserve framework typing and native extension points. Use classes for identity, state, lifecycle, or real variation; keep stateless algorithms private to their capability. Avoid `common`, `utils`, `helpers`, aggregate facades, speculative interfaces, and old-path aliases. Explain key invariants and failure paths with concise Chinese source comments.
+
+The `ddd` template supplies directories and executable examples for supported standard capabilities even when the business does not use them yet. Migrations remain generated from real models. This exception is limited to CLI templates and generated projects; it does not authorize speculative framework layers.
+
+All Host and six-layer Modules explicitly define seven hooks with framework context types. `pre_configure` contributes PreOptions, `configure` registers services and Options, and `post_configure` completes Options or overrides existing registrations. The async `pre_initialize`, `initialize`, and `post_initialize` hooks prepare, initialize, and finish resources. Async `shutdown` waits for cleanup. Empty phases use `pass`; configuration phases do not start I/O, threads, or tasks. Do not manually start framework-managed background components in these hooks.
+
+Worker classes default to `enabled=False`; enabling one requires an explicit code decision. To opt into the hosted example, import `OrderIntegrationService` from `application/hosted_services/order_integration_service.py` in `application/module.py` and declare `hosted_services = HostedServices((OrderIntegrationService,))`. To enable the scheduled example, import `STATISTICS_SCHEDULE` from `application/background_jobs/order_statistics/schedule.py` and declare `background_job_schedules = BackgroundSchedules((STATISTICS_SCHEDULE,))`. Choose the background execution profile/modes in Host configuration. A discovered Job handler alone does not enable periodic enqueue.
+
+When splitting services, update Python contracts/imports directly and retain existing HTTP paths, verbs, status codes, response shapes, permissions, and operation IDs using `ApplicationServiceRouteOverride`. Preserve commit-before-event handling, cache removal before notification, transactional enqueue, idempotent Job handling, and awaited resource cleanup.
+
 ## Services and permissions
 
 1. Define shared business values and permission names in `domain_shared/`.
@@ -33,9 +64,11 @@ from uuid import uuid4
 from python_ddd_framework.authorization import authorize
 from python_ddd_framework.fastapi import http
 
-from ..application_contracts.orders import CreateOrder, OrderView
-from ..domain.orders import Order, OrderTitle
-from ..domain_shared.definitions import ORDERS_WRITE
+from ...application_contracts.inputs.create_order import CreateOrder
+from ...application_contracts.views.order_view import OrderView
+from ...domain.entities.order import Order
+from ...domain.value_objects.order_title import OrderTitle
+from ...domain_shared.permissions.order_permissions import ORDERS_WRITE
 
 # Method inside the generated ApplicationService implementation:
 @authorize(ORDERS_WRITE)
@@ -48,10 +81,34 @@ async def create(self, command: CreateOrder) -> OrderView:
 
 Reuse the existing permission definition provider when adding a permission. A new permission definition does not replace the application's grant policy. Do not grant end-user permissions to background components to repair an incorrectly chosen service boundary.
 
-In DI-managed code, inject the public contract and call `await service.method(...)`. Outside DI, use `await application.invoke(ServiceContract.method, ...)`; it is anonymous by default. Trusted Host/test callers can supply a validated identity through `invoke_as`. Use `application.call` for ordinary async callables that need DI. Do not resolve or instantiate the private service implementation yourself.
+In DI-managed code, inject the public contract and call `await service.method(...)`. Outside DI, use `await invoke(application, ServiceContract.method, ...)`; it is anonymous by default. Trusted Host/test callers can supply a validated identity through `invoke_as`. Import `invoke`, `invoke_as`, `call`, and `call_as` from `python_ddd_framework`. Use `call(application, function, ...)` for ordinary async callables that need DI. Do not resolve or instantiate the private service implementation yourself.
 
 For ordinary services, use the module's existing registration methods or native Dishka providers. Repository, application-service, and hosted-service scopes are fixed by the framework. Do not add a wrapper or custom container around those roles.
 
+Ordinary DI services can use `@unit_of_work`, `@authorize`, or inherit `ValidationEnabled` without becoming ApplicationServices. The owning Module must depend directly or transitively on UnitOfWorkModule, AuthorizationModule, or InvocationModule respectively. Preserve native scope/cache registration. Marked methods must be async instance methods; a class-wide declaration cannot cover synchronous, static, class, or async-generator methods. Unmarked synchronous members keep their original signatures and results. Call injected services directly; use `call` / `call_as` to inject them for an external caller. Manual construction and self-calls do not re-enter interception.
+
+The generated Domain `OrderApprovalService` explicitly enables validation and remains transient. Its caller still owns saving and transaction completion. Interceptor match functions receive the shared `ServiceMethod`; plain services and ApplicationServices share the same invocation stages, while ApplicationServices retain their REQUEST-to-ACTION proxy and explicit HTTP exposure rules.
+
+## Extend reusable modules
+
+Use the existing `post_configure` override registration with a reason and a direct dependency on the target owner. Identity offers `DefaultAuthenticationApplicationService` and `DefaultIdentityManagementApplicationService` for specialization. Keep the public contract signature and policies on the final method; calling `super` does not re-enter interception.
+
+For Identity fields, define an `ExtensionProperties` Pydantic class in `application_contracts/inputs` or `views`, then contribute `ModelExtensions((ModelExtension(IDENTITY_USER_EXTENSION, YourProperties),))` from a Module depending on `IdentityModule` and `ExtensionsModule`. Defaults, validators, and types belong to that class. HTTP input/output remains `extra_properties: {...}`; undeclared fields are rejected. Read typed values with `view.extra_properties.read(YourProperties)`. Nested DTOs and native generic containers share the effective schema. Property types, including aliases, must be closed; nested models and dataclasses must reject unknown fields.
+
+Optional independent columns belong in the consumer persistence Module: contribute `SqlAlchemyModelExtension` instead of `ModelExtension`, and pass `ExtensionColumn(YourProperties.model_fields["field_name"], lambda: Column(...))` for each mapped field. Import these SQL types from `python_ddd_framework.sqlalchemy`; do not import a provider into DTO code. Add `SqlAlchemyExtensionMigrations` with your local migrations package, branch, and exact base revision dependencies. Register the Module's CLI alias in `backend/pyproject.toml`. Upgrade the base owner first, generate and review your extension revision, then upgrade that alias. Identity's JSON container is introduced by `identity_0003`. Required properties on existing data need explicit backfill migrations.
+
+## Identity management
+
+Inject `IdentityManagementApplicationService` from `python_ddd_framework.identity`. User and role queries take `PagedResultRequestDto` and return `PagedResult` with `items` and `total_count`. The standard HTTP lists are `GET /api/identity/users` and `GET /api/identity/roles`, with `skip_count` and `max_result_count` query parameters. The configured API prefix applies normally; use OpenAPI for the current routes and DTOs.
+
+Read the owner's `concurrency_version` and include it in edits, activation, deletion, password commands, and whole-set relationship changes. Relationship updates return the resulting version. A 409 requires rereading and resolving the conflicting edit. Do not substitute a newer version automatically. `permission_version` is internal authorization cache state. User edits preserve extension values by sending `extra_properties`; creation, editing, and paged output use the same extension declaration.
+
+`PUT /api/auth/password` requires a real signed-in user, `old_password`, `new_password`, and the version returned by `/api/auth/me`. Administrators use `PUT /api/identity/users/{user_id}/password` with `new_password` and the user's version. Deactivation uses `/active`; user roles and role permissions use `/roles` and `/permissions` for GET/PUT. DELETE takes a JSON body containing `concurrency_version`. Password changes, deactivation, and deletion invalidate the user's existing sessions after commit. Sign in again after changing a password.
+
+Apply `pddd db upgrade --module identity` before running code that needs `identity_0004` (user/role edit versions). Do not change published revisions or author migrations in the framework installation. This does not transfer ownership of your extension columns or indexes to Identity.
+
+The Host can set `authorization.always_allow: true` to bypass login/permission authorization on managed service calls, including nested calls. It does not create a user identity or accept an invalid token. Input validation, transactions, password checks, and authenticated realtime connections remain active. Keep the permission declarations; setting the option back to false restores authorization. `IdentityOptions` owns access/refresh lifetimes and lockout controls in the `identity` section; duration values accept Pydantic duration strings such as `PT15M`.
+
 ## Options and settings
 
 Startup configuration belongs in a `BaseOptions` type and is bound by the owning module:
@@ -73,7 +130,7 @@ class ApprovalPolicy:
         return self._options.value.allow_background_approval
 ```
 
-This demonstrates the existing Options declaration and injection pattern; extend the generated types rather than defining a second `OrdersOptions`. Register any new ordinary service in the owning module. Configure the generated option in `app.development.yaml`:
+This demonstrates the existing Options declaration and injection pattern; extend the generated types rather than defining a second `OrdersOptions`. Register any new ordinary service in the owning module. Configure the generated option in `backend/app.development.yaml`:
 
 ```yaml
 orders:
@@ -82,18 +139,20 @@ orders:
 
 The corresponding environment key is `PDDD_ORDERS__ALLOW_BACKGROUND_APPROVAL`. `PDDD_HTTP__API_PREFIX` changes the business API prefix. `{{ cookiecutter.host_environment_variable }}` selects the Host environment and is separate from business configuration. Values that affect composition require the framework's pre-configuration phase; do not read unbound Options during construction.
 
-Use runtime settings when a value must be changed while the application is running. Add definitions through a scanned `SettingDefinitionProvider`, read them through `SettingProvider`, and use `SettingManager` or the management API for conditional updates/reset with the queried version token. Application services can use `self.setting_provider` during managed invocation, not during construction. The sample's approval setting is defined in `domain/settings.py`.
+Use runtime settings when a value must be changed while the application is running. Add definitions through a scanned `SettingDefinitionProvider`, read them through `SettingProvider`, and use `SettingManager` or the management API for conditional updates/reset with the queried version token. Application services can use `self.setting_provider` during managed invocation, not during construction. The sample's approval setting is defined in `domain/settings/approval_settings.py`.
 
 Inspect configuration sources and service registrations with:
 
 ```sh
-uv run pddd inspect --environment development
+pddd inspect --environment development
 ```
 
 This composes and closes a new Application without starting it. Output contains redacted configuration inputs, not running-process state or the final Options values after defaults and module contributions. Mark secrets through the framework's existing secret types/metadata; do not log configuration objects or credentials.
 
 ## Persistence and migrations
 
+Use `find` for optional entities and `get` for required entities. Standard list/count/page operations share one native SQLAlchemy query and stable primary-key tie breaking; pass explicit loader options for details. `auto_save=True` flushes, while the owning UoW controls commit. Custom `save` methods keep explicit aggregate/row mapping and pass the appropriate entity event to `operation`.
+
 The generated repository interface inherits `RepositoryContract, Protocol`. Its SQLAlchemy implementation nominally implements that contract under `sqlalchemy/repositories/`, which the persistence module scans. Keep Sessions and ORM types inside this layer.
 
 Map aggregates and rows explicitly within `SqlAlchemySessionProvider.operation`. Pass `aggregate=order` when staging an aggregate write, keep the optimistic version checks, and let that boundary collect the aggregate's events. Avoid collecting the same events again in the service.
@@ -103,18 +162,18 @@ Place model files in `sqlalchemy/models/` and inherit the package's Base. `SqlAl
 After the initial provider setup in the [README](../README.md#initialize-the-database):
 
 ```sh
-uv run pddd db revision --module orders
+pddd db revision --module orders
 ```
 
 Review the revision, especially renames, data backfills, external revision dependencies, and destructive operations. Autogeneration does not decide whole-table deletion or another owner's migration for you. Then run:
 
 ```sh
-uv run pddd db upgrade --module orders
-uv run pddd db status --module orders
-uv run pddd db seed --module orders
+pddd db upgrade --module orders
+pddd db status --module orders
+pddd db seed --module orders
 ```
 
-Upgrade prerequisites explicitly. Do not modify already applied revisions or write migrations into the installed framework package. Seed contributors run in independent transactions and should be idempotent; seeding a business module does not seed identity on its behalf.
+Upgrade prerequisites explicitly. Do not modify already applied revisions or write migrations into the installed framework package. Domain Modules with `DataSeedContributor` depend on `DataSeedingModule`; contributors are ordinary DI classes and do not use `@application_service`. Seed contributors run in independent transactions and should be idempotent; seeding a business module does not seed identity on its behalf.
 
 Managed application-service calls provide the normal unit-of-work boundary. Open an explicit short unit of work only when the operation requires it, inside a managed invocation, and complete it explicitly. Never hold it across a device call, long-running task, external network wait, or streamed response. A child task or thread cannot reuse the parent's Session.
 
@@ -124,6 +183,8 @@ For shared databases, configure installation-specific Alembic version table loca
 
 Raise domain events on the aggregate. Put typed handlers in a scanned package and select the required `LocalEventPhase` with `@local_event_handler`. Use DOMAIN for transactional rules and AFTER_COMMIT for work such as the sample's cache invalidation and online notifications. Post-commit failures cannot undo a committed order; local events are not a durable message bus.
 
+Inject `DistributedCache[OrderCacheItem]` and call `get`, `set`, `remove`, or their batch variants with keys directly. Cache item classes in `application/caching/` own stable `@cache_name` metadata. Omitted entry options use global defaults (20-minute sliding expiration); an explicit `DistributedCacheEntryOptions` replaces the entire object. `get_or_add` uses an async factory; cache access error hiding does not hide factory/type errors or cancellation. Development configuration explicitly disables `caching.hide_errors`. Use `consider_uow=True` when a cache mutation must wait for successful UoW completion; handle post-commit failure as committed database work.
+
 Jobs inherit `BackgroundJobHandler[Payload]`, declare their durable name/version/current/timeout on the class, and are discovered by module scanning. The generated `ApprovalJob` and `ApprovalPayload` show an idempotent business handler. Enqueue by type from a managed invocation, using the same configured database connection for transactional enqueue:
 
 ```python
@@ -131,37 +192,87 @@ from uuid import UUID
 
 from python_ddd_framework.background_jobs import BackgroundJobEnqueuer
 
-from modules.orders.application.tasks import ApprovalJob, ApprovalPayload
+from modules.orders.application.background_jobs.order_approval.handler import ApprovalJob
+from modules.orders.application.background_jobs.order_approval.payload import ApprovalPayload
 
 async def queue_approval(jobs: BackgroundJobEnqueuer, order_id: UUID) -> str:
     return await jobs.enqueue(ApprovalJob, ApprovalPayload(order_id=order_id))
 ```
 
-Keep persisted payload versions until their queued jobs are drained or explicitly migrated. A job's external side effects must tolerate repeat execution.
+Keep persisted payload versions until their queued jobs are drained or explicitly migrated. A job's external side effects must tolerate repeat execution. A schedule takes a Job type (or a registered function's definition), a typed payload and cron: `BackgroundJobSchedule(name="orders.statistics", cron="0 * * * *", job=OrderStatisticsJob, payload=StatisticsPayload())`. The generated statistics schedule shows this declaration. Register it explicitly with `BackgroundSchedules`; task identity and serialization come from the Application's Job catalog, while PgQueuer owns scheduling.
 
-Workers implement `BackgroundWorker.run_iteration` and are registered in `Module.background_workers`; their period, timeout, and enabled state live on the class. Both generated workers are disabled. Change a worker's code declaration deliberately before expecting it to run; configuration and management endpoints cannot enable a code-disabled worker.
+Workers implement `BackgroundWorker.run_iteration` and are registered with `background_workers = BackgroundWorkers((WorkerType,))`; their period, timeout, and enabled state live on the class. Both generated workers are disabled. Change a worker's code declaration deliberately before expecting it to run; configuration and management endpoints cannot enable a code-disabled worker.
 
 Background execution Options use catalog names to select `host`, `shared`, or `exclusive` placement. Only worker configuration accepts `enabled`; job configuration does not. Management start/stop is asynchronous: query status after a request. Stopping a job processor preserves its queued data.
 
-Use the existing `DistributedLock` provider for explicit business leases. If acquisition returns false, skip or report the operation as appropriate. Preserve cancellation and cleanup on lease loss. Use database concurrency and idempotency for their separate guarantees.
+Use the existing `DistributedLock` provider for explicit business leases. `locks.acquire(key, wait_timeout=timedelta(0))` tries without waiting; omit the argument or pass `None` for configured waiting, or pass a positive timedelta for this acquisition only. If acquisition returns false, skip or report the operation as appropriate. Preserve cancellation and cleanup on lease loss. Use database concurrency and idempotency for their separate guarantees.
 
-A `HostedService` manages a long-lived SDK or thread through async `start`/`stop`, including actual thread termination. Register it explicitly in `Module.hosted_services`; the generated integration example is not registered by default. External threads submit through the hosted-service context, and the component owns runtime failures and recovery.
+A `HostedService` manages a long-lived SDK or thread through async `start`/`stop`, including actual thread termination. Register it with `hosted_services = HostedServices((ServiceType,))`; the generated integration example is not registered by default. External threads submit through the hosted-service context, and the component owns runtime failures and recovery.
 
 ## HTTP, files, and real-time communication
 
-The Host passes `http.api_prefix` to `FastApiAdapter`, defaulting to `/api`. The generated HTTP module exposes its application contracts; special method behavior uses `http` decorators on implementations. Check `/docs` after route changes. Keep method paths relative to their service; module overrides do not repeat the global prefix.
+The Host passes `http.api_prefix` to `FastApiAdapter`, defaulting to `/api`. The generated HTTP module exposes its application contracts; `exposes_application_services` also contributes their formal Module dependency. Conventional methods are exposed automatically, `remote_service(is_enabled=False)` excludes methods, and overrides retain deliberate route identities. A plain Pydantic GET query DTO binds through native FastAPI Query metadata; explicit Query/Body/Header/Depends takes precedence. Declare Body explicitly for a GET body, and use native explicit input design for complex shapes. Check `/docs` after route changes. Keep method paths relative to their service; module overrides do not repeat the global prefix.
 
 For explicit business routes, use `HttpRouter(use_api_prefix=True, ...)` and inject public service contracts. Independent endpoints such as WebSocket and health routes retain separate paths. Native FastAPI parameter and response types remain supported.
 
 Use `UploadFile`, `File`, and `Form` for uploads and native response types for downloads/streams. Keep byte limits enforced while reading. Release database work before sending a stream, pass detached data to the producer, and protect asynchronous cleanup in its `finally` block; never carry the previous business Session across yields.
 
-The example WebSocket accepts authenticated clients, sends an initial snapshot, and handles `{}` as a refresh request. Invocations recheck identity and permissions. Non-loopback deployments require WSS; query-token authentication requires an explicit Origin policy. Sample notifications stay within the Host process and do not promise replay or delivery acknowledgment.
+The example WebSocket accepts authenticated clients, sends an initial snapshot, and handles `{}` as a refresh request. `OrderChangedMessage` and `OrderSnapshotMessage` in `domain_shared/messages/order_messages.py` own versioned `message_type` values and Pydantic payload schemas. Send an instance through `publisher.send_to_user(user_id, message)` or `connection.send(message)`; explicitly map domain events and query results to that schema. The envelope retains its ID, UTC time and correlation, and reports only local queue acceptance. Invocations recheck identity and permissions. Non-loopback deployments require WSS; query-token authentication requires an explicit Origin policy. Sample notifications stay within the Host process and do not promise replay or delivery acknowledgment.
+
+`SettingManager.update(definition, value, expected_version=version)` pairs `SettingDefinition[T]` with `value: T`; read the version before update/reset. Reset follows current defaults while retaining a new version token, and saving remains separate from component refresh. A business error may carry `BusinessError(DEFINITION, data=PublicData(...))`, where PublicData is a Pydantic model of intentionally public fields. HTTP omits data when absent; do not put raw exception text, SQL or secrets in the public DTO.
 
 Use `logging.getLogger(__name__)` for application logs. Configure logging in the Host's YAML, keep credentials and payloads out of messages, and enable existing tracing export only when its destination is configured. Avoid process-global logging/tracing setup in a business module.
 
+## In-process messages
+
+Generated modules include `domain_shared/messages/order_observation.py` and
+`application/hosted_services/order_observation_handler.py` as an optional external integration
+example. Existing callbacks remain direct calls. In that module's `application/module.py`,
+import the two types and `observation_identity`, add `MessagingModule` to `dependencies`, then
+add this declaration and binding:
+
+```python
+from python_ddd_framework import MessageChannelDefinition, MessagingModule
+
+# On the Application Module class:
+observations = MessageChannelDefinition(
+    OrderObservation, OrderObservationHandler, capacity=16, snapshot_key=observation_identity
+)
+# In configure(context), using the existing Scope import:
+context.services.add_scoped(OrderObservationHandler, scope=Scope.ACTION)
+```
+
+Inject `MessageChannel[OrderObservation]` into the producer. `await channel.send(value)` returns
+`MessageReceipt`; `await receipt.wait()` returns `MessageOutcome` with a `MessageState`.
+
+```python
+from python_ddd_framework import MessageChannel, MessageState
+
+async def observe(channel: MessageChannel[OrderObservation]) -> None:
+    receipt = await channel.send(OrderObservation(source="inventory", count=3))
+    outcome = await receipt.wait()
+    if outcome.state is not MessageState.COMPLETED:
+        raise RuntimeError(f"Observation ended as {outcome.state.value}")
+```
+
+COMPLETED includes handler and scope cleanup, SUPERSEDED marks a replaced pending snapshot,
+ABORTED means never executed, and CANCELLED does not imply rollback. FAILED retains the
+exception and cleanup chain. Receipt completion does not claim commit or external acknowledgement.
+Cancelling a receipt wait does not retract accepted work.
+
+Capacity covers queued and executing messages. Async send rejects immediately when full and
+creates no waiting tasks. An external SDK thread can use `channel.submit(value)` with at most
+another capacity pending bridge submissions; its Future returns the acceptance receipt.
+Future cancellation can race with acceptance. Handle `MessageRejectedError` for full/closed/failed
+channels and `HostedServiceInvocationRejectedError` for bridge rejection. Never pass Session,
+UoW, scope or concurrently mutable payloads between tasks/threads. Host configuration
+`messaging.shutdown_timeout` requests cancellation after the deadline; shutdown still waits for
+resource exit and reports timeout. Restart requires a new Application. Commands, results and
+events requiring individual processing must not declare a coalescing key.
+
 ## Verification
 
-Run commands from the application root. Read fixtures first: Host tests use disposable PostgreSQL and Redis containers, so Docker must be available.
+Run native uv/test/build commands from `backend/`. Installed `pddd` commands locate the backend from the application root or any descendant, including nested foreign Python projects. Read fixtures first: Host tests use disposable PostgreSQL and Redis containers, so Docker must be available.
 
 ```sh
 # After adding an orders module: its domain tests do not need Docker.

python_ddd_framework/distributed_lock/contracts.py

@@ -1,13 +1,16 @@
 """锁的业务使用与错误边界；provider 不进入稳定契约。"""
 
 from contextlib import AbstractAsyncContextManager
+from datetime import timedelta
 from typing import Protocol
 
 from ..errors.base import FrameworkError
 
 
 class DistributedLock(Protocol):
-    def acquire(self, key: str, /) -> AbstractAsyncContextManager[bool]:
+    def acquire(
+        self, key: str, *, wait_timeout: timedelta | None = None
+    ) -> AbstractAsyncContextManager[bool]:
         """进入后返回是否取得锁；持有者必须配合取消并在退出上下文前完成清理。"""
         ...
 

python_ddd_framework/domain/__init__.py

@@ -3,10 +3,12 @@
 from .aggregates import AggregateRoot
 from .entities import Entity
 from .errors import OptimisticConcurrencyError
+from .services import DomainService
 from .value_objects import ValueObject
 
 __all__ = (
     "AggregateRoot",
+    "DomainService",
     "Entity",
     "OptimisticConcurrencyError",
     "ValueObject",

python_ddd_framework/domain/services.py

@@ -0,0 +1,11 @@
+"""领域服务的约定身份；实例生命周期复用现有 DI。"""
+
+from ..services.convention_contracts import TransientDependency
+
+
+class DomainService(TransientDependency):
+    """无缓存的 REQUEST 领域服务，通过构造函数声明依赖。
+
+    只承载不适合放进单个实体的领域规则。标记本身不创建事务、
+    不生成应用服务代理或 HTTP API；事务仍由调用方拥有。
+    """

python_ddd_framework/errors/business.py

@@ -6,6 +6,7 @@ from dataclasses import dataclass
 
 from pydantic import BaseModel
 
+from ..validation.models import _revalidate_model
 from .base import FrameworkError
 
 
@@ -40,7 +41,11 @@ class BusinessErrorField:
 
 class BusinessError(FrameworkError):
     def __init__(
-        self, definition: BusinessErrorDefinition, *, fields: tuple[BusinessErrorField, ...] = ()
+        self,
+        definition: BusinessErrorDefinition,
+        *,
+        fields: tuple[BusinessErrorField, ...] = (),
+        data: BaseModel | None = None,
     ) -> None:
         if not isinstance(definition, BusinessErrorDefinition):
             raise TypeError("business error requires a static definition")
@@ -50,4 +55,8 @@ class BusinessError(FrameworkError):
             raise TypeError("business error fields must be an immutable tuple")
         self.definition = definition
         self.fields = fields
+        if data is not None and not isinstance(data, BaseModel):
+            raise TypeError("business error data must be a typed Pydantic model")
+        # 只接受业务显式选取的公开 DTO；复制并重验，排除构造绕过及调用者后续修改。
+        self.data = _revalidate_model(type(data), data) if data is not None else None
         super().__init__(definition.code)

python_ddd_framework/errors/lifecycle.py

@@ -9,10 +9,8 @@ from .base import FrameworkError
 
 if TYPE_CHECKING:
     from ..diagnostics import LifecyclePhase, LifecycleStage, SourceLocation
-    from ..hosted_services.errors import HostedServiceLifecycleError
     from ..lifecycle import ApplicationState
     from ..modularity import ModuleKey
-    from .services import ContainerCleanupError
 
 
 class InvalidApplicationStateError(FrameworkError):
@@ -97,20 +95,6 @@ class LifecycleInvocationError(FrameworkError):
         )
 
 
-class _BackgroundExecutionStartFailure(FrameworkError):
-    """保留原始 background start failure，同时不伪造 Module lifecycle 位置。"""
-
-    failure_id = None
-    stage = None
-    dependency_path: tuple[ModuleKey, ...] = ()
-
-    def __init__(self, *, original_error: BaseException) -> None:
-        self.original_error = original_error
-        self.__cause__ = original_error
-        self.__suppress_context__ = True
-        super().__init__(f"Background execution start failed with {type(original_error).__name__}")
-
-
 class ApplicationRuntimeError(FrameworkError):
     """运行期基础设施 fatal fact；不携带第三方异常正文或原始 cause。"""
 
@@ -126,27 +110,15 @@ class ApplicationStartError(FrameworkError):
     def __init__(
         self,
         *,
-        primary: (
-            LifecycleInvocationError
-            | _BackgroundExecutionStartFailure
-            | HostedServiceLifecycleError
-        ),
-        cleanup_failures: tuple[
-            LifecycleInvocationError
-            | ContainerCleanupError
-            | _BackgroundExecutionStartFailure
-            | HostedServiceLifecycleError,
-            ...,
-        ],
+        primary: BaseException,
+        cleanup_failures: tuple[BaseException, ...],
     ) -> None:
         self.primary = primary
         self.cleanup_failures = cleanup_failures
         if isinstance(primary, LifecycleInvocationError):
             location = f"{primary.module}/{primary.stage.value}"
-        elif isinstance(primary, _BackgroundExecutionStartFailure):
-            location = "background-execution"
         else:
-            location = f"hosted-service:{primary.service}/{primary.operation}"
+            location = type(primary).__qualname__
         super().__init__(
             f"Application start failed at {location}; cleanup failures: {len(cleanup_failures)}"
         )

python_ddd_framework/events/__init__.py

@@ -1,7 +1,7 @@
 from .aggregate import AggregateEventCollector
 from .catalog import LocalEventCatalog, LocalEventSubscription
 from .contracts import LocalEventPhase, local_event_handler
-from .contribution import EventContributor
+from .entities import EntityChangedEvent, EntityCreatedEvent, EntityDeletedEvent, EntityUpdatedEvent
 from .errors import (
     EventContributionError,
     EventCycleError,
@@ -12,8 +12,11 @@ from .runtime import LocalEventBus
 
 __all__ = (
     "AggregateEventCollector",
+    "EntityChangedEvent",
+    "EntityCreatedEvent",
+    "EntityDeletedEvent",
+    "EntityUpdatedEvent",
     "EventContributionError",
-    "EventContributor",
     "EventCycleError",
     "LocalEventBus",
     "LocalEventCatalog",

python_ddd_framework/events/aggregate.py

@@ -7,6 +7,7 @@ from typing import TypeVar
 from ..domain import AggregateRoot
 from ..unit_of_work.contracts import UnitOfWork
 from .runtime import LocalEventBus
+from .unit_of_work import _local_event_queue
 
 _TId = TypeVar("_TId")
 
@@ -31,9 +32,8 @@ def _collect_aggregate_events(
     work: UnitOfWork, aggregate: AggregateRoot[_TId]
 ) -> tuple[object, ...]:
     # 两个公开入口先验证事务 owner；收集不触发 flush，也不恢复已释放事件或自动重放。
-    assert work._event_queue is not None
+    queue = _local_event_queue(work)
     released = aggregate.release_local_events()
     for event in released:
-        work._event_queue.publish_domain(event)
-        work._event_queue.publish_after_commit(event)
+        queue.enqueue(event)
     return released

python_ddd_framework/events/catalog.py

@@ -5,7 +5,6 @@ from __future__ import annotations
 import inspect
 from collections.abc import Awaitable, Callable, Mapping
 from dataclasses import dataclass
-from types import MappingProxyType
 from typing import TYPE_CHECKING
 
 from dishka import BaseScope, Scope
@@ -32,18 +31,10 @@ class LocalEventSubscription:
 
 
 class LocalEventCatalog:
-    __slots__ = ("_by_phase_and_type", "_subscriptions")
+    __slots__ = ("_subscriptions",)
 
     def __init__(self, subscriptions: tuple[LocalEventSubscription, ...]) -> None:
-        grouped: dict[tuple[LocalEventPhase, type[object]], list[LocalEventSubscription]] = {}
-        for subscription in subscriptions:
-            grouped.setdefault((subscription.phase, subscription.event_type), []).append(
-                subscription
-            )
         self._subscriptions = subscriptions
-        self._by_phase_and_type: Mapping[
-            tuple[LocalEventPhase, type[object]], tuple[LocalEventSubscription, ...]
-        ] = MappingProxyType({key: tuple(values) for key, values in grouped.items()})
 
     @property
     def subscriptions(self) -> tuple[LocalEventSubscription, ...]:
@@ -54,7 +45,17 @@ class LocalEventCatalog:
         event_type: type[object],
         phase: LocalEventPhase,
     ) -> tuple[LocalEventSubscription, ...]:
-        return self._by_phase_and_type.get((phase, event_type), ())
+        matched: list[LocalEventSubscription] = []
+        seen: set[object] = set()
+        for subscription in self._subscriptions:
+            if (
+                subscription.phase is phase
+                and issubclass(event_type, subscription.event_type)
+                and subscription.handler_type not in seen
+            ):
+                matched.append(subscription)
+                seen.add(subscription.handler_type)
+        return tuple(matched)
 
 
 def _build_event_catalog(

python_ddd_framework/events/contracts.py

@@ -6,6 +6,7 @@ from dataclasses import dataclass
 from enum import Enum
 from typing import TypeVar
 
+from ..modularity import ModuleDeclaration, ModuleDependency, ModuleRef
 from .errors import EventContributionError
 
 
@@ -19,9 +20,13 @@ _THandler = TypeVar("_THandler")
 
 
 @dataclass(frozen=True, slots=True)
-class _LocalEventHandlerDefinition:
+class _LocalEventHandlerDefinition(ModuleDeclaration):
     phase: LocalEventPhase
 
+    @property
+    def required_module(self) -> ModuleDependency:
+        return ModuleRef("python_ddd_framework.events.module:LocalEventsModule")
+
 
 def local_event_handler(*, phase: LocalEventPhase) -> Callable[[type[_THandler]], type[_THandler]]:
     """只保存 class-local phase；事件类型在 Application build 由 handle 注解解释。"""

python_ddd_framework/events/contribution.py

@@ -6,8 +6,7 @@ import inspect
 from collections.abc import Awaitable, Callable
 from dataclasses import dataclass
 
-from ..diagnostics import LifecycleStage, SourceLocation
-from ..diagnostics.source import caller_source
+from ..diagnostics import SourceLocation
 from ..modularity import ModuleDescriptor, ModuleKey
 from .contracts import LocalEventPhase
 from .errors import EventContributionError
@@ -25,48 +24,6 @@ class _EventContribution:
     automatic: bool = False
 
 
-class EventContributor:
-    """只在当前 Module.configure 有效，避免 runtime 或 global subscription mutation。"""
-
-    __slots__ = ("_active", "_descriptor", "_registry", "_stage")
-
-    def __init__(
-        self,
-        registry: EventContributionRegistry,
-        *,
-        descriptor: ModuleDescriptor,
-        stage: LifecycleStage,
-    ) -> None:
-        self._registry = registry
-        self._descriptor = descriptor
-        self._stage = stage
-        self._active = True
-
-    def subscribe(
-        self,
-        event_type: type[object],
-        handler_type: type[object] | Callable[..., Awaitable[None]],
-        phase: LocalEventPhase,
-        *,
-        reason: str,
-    ) -> None:
-        if not self._active:
-            raise EventContributionError(
-                reason=f"event contributor is closed for {self._stage.value}"
-            )
-        self._registry.add(
-            event_type=event_type,
-            handler_type=handler_type,
-            phase=phase,
-            descriptor=self._descriptor,
-            source=caller_source(str(self._descriptor.key), depth=2),
-            reason=reason,
-        )
-
-    def _close(self) -> None:
-        self._active = False
-
-
 class EventContributionRegistry:
     """Application-owned append-only subscription state，freeze 后只读。"""
 
@@ -77,14 +34,6 @@ class EventContributionRegistry:
         self._counts: dict[ModuleKey, int] = {}
         self._frozen = False
 
-    def contributor(
-        self,
-        *,
-        descriptor: ModuleDescriptor,
-        stage: LifecycleStage,
-    ) -> EventContributor:
-        return EventContributor(self, descriptor=descriptor, stage=stage)
-
     def add(
         self,
         *,

python_ddd_framework/events/entities.py

@@ -0,0 +1,23 @@
+"""仓储暂存事实与聚合业务事件分离；不推断领域事件或 ORM 关系。"""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class EntityChangedEvent:
+    entity: object
+
+
+@dataclass(frozen=True, slots=True)
+class EntityCreatedEvent(EntityChangedEvent):
+    pass
+
+
+@dataclass(frozen=True, slots=True)
+class EntityUpdatedEvent(EntityChangedEvent):
+    pass
+
+
+@dataclass(frozen=True, slots=True)
+class EntityDeletedEvent(EntityChangedEvent):
+    pass