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

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/sqlalchemy/repositories/order_repository.py.jinja

@@ -0,0 +1,79 @@
+"""仓储参与当前 UoW，成功暂存后由 operation 收集聚合事件。"""
+
+from uuid import UUID
+
+from modules.{{ cookiecutter.module_name }}.domain.entities.order import Order
+from modules.{{ cookiecutter.module_name }}.domain.repositories.order_repository import OrderRepository
+from modules.{{ cookiecutter.module_name }}.domain.value_objects.order_title import OrderTitle
+from modules.{{ cookiecutter.module_name }}.domain_shared.enums.order_status import OrderStatus
+from modules.{{ cookiecutter.module_name }}.sqlalchemy.models.order_model import OrderRow
+
+from python_ddd_framework import (
+    OptimisticConcurrencyError, ResourceNotFoundError, EntityCreatedEvent, EntityUpdatedEvent,
+)
+from python_ddd_framework.sqlalchemy import SqlAlchemyRepository, SqlAlchemySessionProvider
+
+
+class _OrderRows(SqlAlchemyRepository[OrderRow, UUID]):
+    def _default_sorting(self) -> str:
+        return "created_at"
+
+
+class SqlAlchemyOrderRepository(OrderRepository):
+    def __init__(self, provider: SqlAlchemySessionProvider) -> None:
+        self._provider = provider
+        self._rows = _OrderRows(provider, OrderRow)
+
+    async def find(self, id: UUID, include_details: bool = True) -> Order | None:
+        # 持久化扩展：这里查询本模块的表，再通过显式映射重建聚合；业务判断留给聚合/应用服务。
+        async with self._provider.operation("get"):
+            row = await self._rows.find(id, include_details)
+            return None if row is None else _order(row)
+
+    async def get(self, id: UUID, include_details: bool = True) -> Order:
+        order = await self.find(id, include_details)
+        if order is None:
+            raise ResourceNotFoundError("Order not found")
+        return order
+
+    async def get_list(self, include_details: bool = False) -> list[Order]:
+        async with self._provider.operation("get_list"):
+            return [_order(row) for row in await self._rows.get_list(include_details)]
+
+    async def get_count(self) -> int:
+        return await self._rows.get_count()
+
+    async def get_paged_list(self, skip_count: int, max_result_count: int,
+                             sorting: str | None = None, include_details: bool = False) -> list[Order]:
+        async with self._provider.operation("get_paged_list"):
+            rows = await self._rows.get_paged_list(
+                skip_count, max_result_count, sorting, include_details
+            )
+            return [_order(row) for row in rows]
+
+    async def save(self, order: Order) -> None:
+        # 持久化扩展：把自己的聚合字段/子实体映射到 ORM；下面的版本核对和事件收集边界要保留。
+        # 这里只暂存改动，不自行 commit，避免绕开调用者的工作单元。
+        async with self._provider.operation(
+            "save", aggregate=order,
+            entity_event=EntityCreatedEvent(order) if order.version == 0 else EntityUpdatedEvent(order),
+        ):
+            session = await self._provider.get_session()
+            row = await session.get(OrderRow, order.id)
+            if row is None:
+                if order.version:
+                    raise OptimisticConcurrencyError
+                row = OrderRow(id=order.id)
+                session.add(row)
+            elif row.version != order.version:
+                raise OptimisticConcurrencyError
+            order.stage_next_version(order.version)
+            # 新增持久字段的赋值写在这里，同时修改模型、下方读取映射并生成迁移。
+            row.title, row.status, row.version = order.title, order.status.value, order.version
+
+
+def _order(row: OrderRow) -> Order:
+    # 映射扩展：在这里把数据库字段恢复成领域实体/值对象，不调用会再次产生创建事件的工厂。
+    return Order(
+        row.id, OrderTitle(value=row.title), status=OrderStatus(row.status), version=row.version
+    )

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/tests/__init__.py.jinja

@@ -0,0 +1 @@
+"""所属能力的实现或契约。"""

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/tests/test_domain.py.jinja

@@ -3,10 +3,11 @@
 from uuid import uuid4
 
 import pytest
-from python_ddd_framework.errors import BusinessError
+from modules.{{ cookiecutter.module_name }}.domain.entities.order import Order
+from modules.{{ cookiecutter.module_name }}.domain.value_objects.order_title import OrderTitle
+from modules.{{ cookiecutter.module_name }}.domain_shared.enums.order_status import OrderStatus
 
-from modules.{{ cookiecutter.module_name }}.domain.orders import Order, OrderTitle
-from modules.{{ cookiecutter.module_name }}.domain_shared.definitions import OrderStatus
+from python_ddd_framework.errors import BusinessError
 
 
 def test_order_approval_rejects_repeat():

python_ddd_framework/developer_kit/templates/project/cookiecutter.json

@@ -1,6 +1,6 @@
 {
   "project_name": "application", "package_name": "application", "class_prefix": "Application",
-  "framework_version": "", "framework_source": "", "python_version": "", "build_version": "",
+  "framework_version": "", "framework_source": "", "python_version": "", "requires_python": "", "build_version": "",
   "database_password": "", "admin_password": "", "jwt_key": "",
   "host_environment_variable": ""
 }

python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/AGENTS.md

@@ -6,8 +6,10 @@ These instructions apply to this application and its business modules. Follow th
 
 1. Check the branch, worktree, requested outcome, and existing changes before editing. Analysis and review requests are read-only unless implementation is requested.
 2. Use [README](README.md) for setup and commands, [architecture](docs/architecture.md) for ownership and dependencies, and the relevant section of [development](docs/development.md) for framework usage.
-3. Before changing a business module, read its `src/modules/<name>/README.md`, then inspect the affected source and direct callers. Expand the investigation only when those facts reveal another affected boundary.
-4. Read versions and dependencies from `pyproject.toml`, exact resolutions from `uv.lock`, and commands from `uv run pddd --help`. Verify behavior against the installed framework version when the application documentation is insufficient.
+3. First identify the layer and responsibility directory in the [module layout rules](docs/development.md#module-layout-and-coding-rules). Before changing a business module, read its `backend/src/modules/<name>/README.md`, then inspect the affected source and direct callers. Expand the investigation only when those facts reveal another affected boundary.
+4. Read versions and dependencies from `backend/pyproject.toml`, exact resolutions from `backend/uv.lock`, and commands from `pddd --help`. Verify behavior against the installed framework version when the application documentation is insufficient.
+
+Python code, metadata, configuration, environment, and deployment files belong under `backend/`. Root `scripts/` contains consumer-owned scripts. Run installed `pddd` commands from any directory in the application; run native uv/build/test and Docker commands from `backend/`.
 
 ## Preserve ownership and contracts
 
@@ -18,15 +20,26 @@ These instructions apply to this application and its business modules. Follow th
 - Resolve conflicting requirements, documented contracts, and implementation before changing the affected boundary. Describe the conflict to the user; do not rewrite documentation to justify an unapproved design.
 - Confirm changes to dependencies, public contracts, persistent data, external protocols, or deployment infrastructure when they extend beyond the requested task. Internal simplification does not authorize breaking consumers or stored data.
 
+Use the documented responsibility directories for every new capability. Propose a standards change before adding a responsibility category or changing dependency direction. The `ddd` template intentionally generates all supported example capabilities, even before use; this exception applies to DDD templates and generated projects, not speculative framework runtime layers. The `basic` template generates only package markers, `module.py`, `contracts/conversion_service.py`, `services/default_conversion_service.py`, and its README. It uses ordinary transient DI, without Domain, persistence, HTTP, interception, or empty layers. Keep `module.py` limited to dependencies, registration, and lifecycle hooks, and keep package `__init__.py` free of business code and compatibility exports.
+
 ## Use the framework safely
 
-- Invoke application services through their injected public contracts or the application's public invocation methods. Manual construction and self-calls do not create a new managed invocation.
+- Extend only explicitly opened targets. Keep typed properties in application contracts, optional SQL mappings and local extension revisions in persistence, and reuse the same declaration for validation, OpenAPI, and storage. Never mutate shared DTO/ORM classes or duplicate the base table/Schema owner; extension migrations declare Alembic prerequisites explicitly.
+
+- Invoke application services through their injected public contracts or the framework functions `invoke(application, ...)` / `call(application, ...)`. Manual construction and self-calls do not create a new managed invocation.
+- Ordinary DI services opt into interception with `@unit_of_work`, `@authorize`, or `ValidationEnabled`; declare the corresponding capability dependency on their owning Module. Keep marked methods async instance methods and preserve native scope/cache. These declarations do not add HTTP exposure or require ApplicationService inheritance.
 - Keep transactions short. Never carry a Session, unit of work, or request scope into an ordinary child task, external thread, network wait, or streamed response.
 - Keep aggregate rules and optimistic concurrency checks intact. Use repository operations to stage changes and collect events; do not publish the same aggregate events twice.
 - Review generated migrations. Do not edit applied revisions, bypass migration guards, or treat Host startup as migration or seeding.
 - Keep background side effects idempotent. Local events and WebSocket messages do not provide durable distributed delivery; distributed locks do not replace database concurrency or idempotency.
 - Validate external inputs, propagate meaningful failures, and preserve cancellation and cleanup. Add defaults, retries, or fallbacks only for an identified requirement.
 - Use typed public APIs and native framework extension points. Keep dynamic data narrowing at external boundaries; do not use `Any`, unchecked casts, or broad exception handlers to hide contract mistakes.
+- Keep Job identity in its definition and realtime names/schemas in typed message classes under `domain_shared/messages`; callers provide typed values. Explicit public error data belongs to a Pydantic DTO selected by the business. Preserve existing wire names and fields when changing these schemas; queue acceptance is not delivery acknowledgment.
+
+For in-process messages, read the [message example](docs/development.md#in-process-messages).
+Business modules own message values and coalescing identities. Only replaceable snapshots may
+coalesce. Acceptance, processing, commit and external acknowledgement are separate facts.
+Use the framework channel and hosted bridge; preserve capacity and actual cleanup guarantees.
 
 ## Verify and maintain
 

python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/README.md

@@ -8,20 +8,20 @@ A modular Python application generated with Python DDD Framework {{ cookiecutter
 | [Architecture](docs/architecture.md) | Ownership, dependency direction, transaction boundaries, and lifecycle guarantees. |
 | [Development guide](docs/development.md) | Recipes for services, permissions, persistence, configuration, events, and background work. |
 
-Each generated business module also has its own README under `src/modules/<name>/`. This README owns application setup and operations.
+Each generated business module also has its own README under `backend/src/modules/<name>/`. This README owns application setup and operations.
 
 ## Prerequisites
 
-Use the Python version declared by this project's metadata, uv, and a running Docker installation with Compose. `pddd new` has already synchronized dependencies. On an existing checkout, run `uv sync --locked`.
+Python metadata, `.python-version`, `uv.lock`, `.venv`, source, tests, YAML, Compose files, and the Dockerfile belong in `backend/`. Root `scripts/` belongs to application-owned development scripts. Use uv and the Python version declared under `backend/`; Docker with Compose is required for the generated Host's providers. Normal creation synchronizes dependencies. With `pddd new <name> --python <major.minor[.patch]> --no-sync`, creation writes files only, even if that interpreter is absent. Run `uv sync --project backend` afterwards; uv selects or downloads the requested Python. On later checkouts, use `uv sync --project backend --locked`.
 
-Run project commands from this directory with `uv run pddd` so they use the project's framework version. Use `uv run pddd` or a subcommand's `--help` to see available commands and options.
+Run `pddd` project commands from the application root, `backend/`, or any child directory. Host entry points identify the owning backend; unrelated nested Python projects do not redirect the command. The CLI uses that backend's existing environment and framework version. Synchronize explicitly before the first project command. Inside `backend/`, `uv run pddd` is also available; from other locations use the installed `pddd` launcher. Use `pddd` or a subcommand's `--help` to see available commands and options.
 
 ## Prepare local development
 
-Review `app.development.yaml`, then start the local infrastructure:
+Review `backend/app.development.yaml`, then start the local infrastructure:
 
 ```sh
-uv run pddd dev-init
+pddd dev-init
 ```
 
 This starts or reuses PostgreSQL and Redis from the Host's development configuration and preserves data. It does not start the application, migrate, seed, or create an `.env` file. The bundled Compose setup requires local URLs with explicit ports; its Redis service does not configure authentication or TLS.
@@ -29,46 +29,51 @@ This starts or reuses PostgreSQL and Redis from the Host's development configura
 To add the example business module:
 
 ```sh
-uv run pddd add module orders
+pddd add module orders --template ddd
+pddd add module conversions --template basic
 ```
 
-Read `src/modules/orders/README.md` before changing the sample. The project is also usable as a pure Host without this step.
+Read `backend/src/modules/orders/README.md` before changing the sample. The project is also usable as a pure Host without this step.
 
 ## Initialize the database
 
 Apply the migrations for the providers selected by the generated Host:
 
 ```sh
-uv run pddd db upgrade --module identity
-uv run pddd db upgrade --module settings
-uv run pddd db upgrade --module auditing
-uv run pddd db upgrade --module background_jobs
-uv run pddd db seed --module identity
+pddd db upgrade --module identity
+pddd db upgrade --module settings
+pddd db upgrade --module auditing
+pddd db upgrade --module background_jobs
+pddd db seed --module identity
 ```
 
 If you added `orders`, generate its first revision:
 
 ```sh
-uv run pddd db revision --module orders
+pddd db revision --module orders
 ```
 
-Review the generated file in `src/modules/orders/sqlalchemy/migrations/`, then apply and seed it:
+Review the generated file in `backend/src/modules/orders/sqlalchemy/migrations/`, then apply and seed it:
 
 ```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
 ```
 
 All database operations select an explicit module. Upgrade prerequisite owners explicitly; commands do not migrate unrelated modules. Host startup does not migrate or seed. Database commands do not start workers or hosted services. See [persistence and migrations](docs/development.md#persistence-and-migrations) before changing models or existing data.
 
 ## Run and inspect
 
+To add fields to an explicitly extensible module such as Identity, follow [Extend reusable modules](docs/development.md#extend-reusable-modules). Upgrade the base owner before generating your customer module's extension revision. Keep all new revisions in this project's extension module; framework installation files are not an authoring destination.
+
 ```sh
-uv run pddd dev
+pddd dev
 ```
 
-Open **http://127.0.0.1:8000/docs**. Call `/api/auth/login` using the generated `identity.seed_admin_username` and `identity.seed_admin_password` from `app.development.yaml`, then enter the access token in **Authorize**. Local credentials must not be reused for production.
+Open **http://127.0.0.1:8000/docs**. Call `/api/auth/login` using the generated `identity.seed_admin_username` and `identity.seed_admin_password` from `backend/app.development.yaml`, then enter the access token in **Authorize**. Local credentials must not be reused for production.
+
+Identity includes paged user/role management, password operations, and version-protected assignments. Before using it, apply the framework's Identity migrations; preserve the returned `concurrency_version` in updates. See [Identity management](docs/development.md#identity-management) for API usage, session invalidation, and Host authorization options.
 
 With the `orders` example installed, `/api/orders` supports create/query, `/api/orders/{id}/approve` approves an order, and `/api/orders/{id}/queue-approval` enqueues approval. Read the module README for its rules and OpenAPI for request schemas. A stale version produces a conflict response.
 
@@ -77,7 +82,7 @@ With the `orders` example installed, `/api/orders` supports create/query, `/api/
 To inspect module composition, service registrations, and redacted configuration inputs:
 
 ```sh
-uv run pddd inspect --environment development
+pddd inspect --environment development
 ```
 
 Inspection composes and closes a new Application without starting it. It does not query an existing process, and its input snapshot is not the final Options view. Configuration, workers, jobs, real-time communication, and logging are covered in the [development guide](docs/development.md).
@@ -85,6 +90,7 @@ Inspection composes and closes a new Application without starting it. It does no
 ## Test and package
 
 ```sh
+cd backend
 uv run pytest
 uv build --no-sources
 ```
@@ -93,7 +99,7 @@ The application tests include real Host infrastructure and require Docker. Modul
 
 ## Deploy
 
-The deployment supplies `app.production.yaml`, following the development file's key structure with independent database, Redis, JWT, and administrator credentials. Set the production logging environment and format. Keep the file out of Git and the image; production Compose mounts it read-only at `/app/app.production.yaml` for both web and migration services.
+Run Docker and Compose commands from `backend/`. The deployment supplies `backend/app.production.yaml`, following the development file's key structure with independent database, Redis, JWT, and administrator credentials. Set the production logging environment and format. Keep the file out of Git and the image; production Compose mounts it read-only at `/app/app.production.yaml` for both web and migration services.
 
 Build an image, validate it, and set `APP_IMAGE` to its immutable digest. In PowerShell, run the following for each required module, replacing the module alias and digest:
 
@@ -118,9 +124,10 @@ The base framework dependency includes runtime capabilities. Production does not
 
 Read the target framework release's migration instructions. Pin `python-ddd-framework` in runtime dependencies and `python-ddd-framework[developer-kit]` in the development group to the same target version. Preserve the application's own dependencies and source overrides.
 
-For a first move from a local wheel or old Git source to PyPI, remove only the framework entry in `[tool.uv.sources]`; retain other dependencies and vendor files. Then run:
+For a first move from a local wheel or old Git source to PyPI, remove only the framework entry in `[tool.uv.sources]`; retain other dependencies and vendor files. From the application root, run:
 
 ```sh
+cd backend
 uv lock --upgrade-package python-ddd-framework
 uv sync --locked
 uv run pytest

python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/{app.development.yaml.jinja → backend/app.development.yaml.jinja}

@@ -16,6 +16,8 @@ identity:
 redis:
   url: redis://127.0.0.1:6379/0
   key_prefix: "{{ cookiecutter.project_name }}"
+caching:
+  hide_errors: false
 logging:
   application: "{{ cookiecutter.project_name }}"
   environment: development

python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/{pyproject.toml.jinja → backend/pyproject.toml.jinja}

@@ -1,7 +1,7 @@
 [project]
 name = "{{ cookiecutter.project_name }}"
 version = "0.1.0"
-requires-python = "=={{ cookiecutter.python_version }}"
+requires-python = "{{ cookiecutter.requires_python }}"
 dependencies = ["python-ddd-framework=={{ cookiecutter.framework_version }}"]
 
 [project.entry-points."python_ddd_framework.hosts"]

python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/{src → backend/src}/host/main.py.jinja

@@ -17,6 +17,7 @@ from .module import {{ cookiecutter.class_prefix }}HostModule
 def create_application(
     *, environment: str | None = None, cli_args: tuple[str, ...] = ()
 ) -> Application:
+    # Host 扩展：在这里选择环境、配置来源和根模块；业务规则与用例实现放在各业务模块中。
     environment = environment or os.environ.get(ENVIRONMENT_VARIABLE, "development")
     return ApplicationBuilder(
         {{ cookiecutter.class_prefix }}HostModule,
@@ -28,6 +29,7 @@ def create_application(
 
 
 def create_web() -> FastAPI:
+    # HTTP 组装扩展：在这里设置站点信息和 Host middleware，并在 install 前完成需要的配置。
     application = create_application()
     # 全局 middleware 使用原生 Starlette 实现，在 adapter.install 前完成配置。
     adapter = FastApiAdapter(

python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/{src → backend/src}/host/module.py.jinja

@@ -1,7 +1,16 @@
 """Host 只选择 provider 与组合 Module，不拥有业务规则。"""
 
-from dishka.integrations.fastapi import FastapiProvider
-from python_ddd_framework import AppModule, ConfigureContext
+
+from python_ddd_framework import (
+    AppModule,
+    ConfigureContext,
+    InitializeContext,
+    PostConfigureContext,
+    PostInitializeContext,
+    PreConfigureContext,
+    PreInitializeContext,
+    ShutdownContext,
+)
 from python_ddd_framework.auditing.sqlalchemy import SqlAlchemyAuditingModule
 from python_ddd_framework.background_jobs.pgqueuer import PgQueuerBackgroundJobsModule
 from python_ddd_framework.fastapi.background import BackgroundManagementHttpApiModule
@@ -13,6 +22,7 @@ from python_ddd_framework.observability.tracing import TracingModule
 from python_ddd_framework.redis import RedisDistributedLockModule, RedisModule
 from python_ddd_framework.redis.notifications import RedisNotificationsModule
 from python_ddd_framework.settings.notifications import SettingsNotificationsModule
+from python_ddd_framework.settings.refresh_module import SettingsRefreshModule
 from python_ddd_framework.settings.sqlalchemy import SqlAlchemyRuntimeSettingsModule
 
 
@@ -27,11 +37,38 @@ class {{ cookiecutter.class_prefix }}HostModule(AppModule):
         RedisDistributedLockModule,
         RedisNotificationsModule,
         SettingsNotificationsModule,
+        SettingsRefreshModule,
         PgQueuerBackgroundJobsModule,
         BackgroundManagementHttpApiModule,
         StructuredLoggingModule,
         TracingModule,
     )
 
+    def pre_configure(self, context: PreConfigureContext) -> None:
+        # 贡献影响后续注册的 PreOptions；此阶段不启动资源。
+        pass
+
     def configure(self, context: ConfigureContext) -> None:
-        context.services.contribute(FastapiProvider(), reason="Native HTTP request context")
+        # Host 组装扩展：在这里接入运行环境所需的 provider/服务配置；模块依赖声明在上方 dependencies。
+        # 新业务写进模块的应用服务和领域对象，不在 configure 中执行数据库操作或启动长期任务。
+        pass
+
+    def post_configure(self, context: PostConfigureContext) -> None:
+        # 读取已冻结 PreOptions，补充 Options 或覆盖已有服务注册。
+        pass
+
+    async def pre_initialize(self, context: PreInitializeContext) -> None:
+        # 异步初始化前置条件；依赖模块在同一阶段先完成。
+        pass
+
+    async def initialize(self, context: InitializeContext) -> None:
+        # 初始化本模块资源；不手工启动框架管理的 Worker 或 HostedService。
+        pass
+
+    async def post_initialize(self, context: PostInitializeContext) -> None:
+        # 完成初始化收尾；应用此时尚未对外就绪。
+        pass
+
+    async def shutdown(self, context: ShutdownContext) -> None:
+        # 逆依赖关闭本模块拥有的资源；返回前等待清理结束。
+        pass

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

@@ -10,18 +10,20 @@ The initial project is a Host without business modules. `pddd add module <name>`
 
 | Owner | Responsibility |
 | --- | --- |
-| `src/host/main.py` | Application and FastAPI factories, configuration inputs, middleware assembly, and the server entry point. |
-| `src/host/module.py` | Explicit module dependencies and provider selection for this deployment. |
-| `src/modules/<name>/` | A business capability, its public contracts, implementation, persistence, transport, and tests. |
-| `app.development.yaml` | Local environment inputs and generated development credentials. |
+| `backend/src/host/main.py` | Application and FastAPI factories, configuration inputs, middleware assembly, and the server entry point. |
+| `backend/src/host/module.py` | Explicit module dependencies and provider selection for this deployment. |
+| `backend/src/modules/<name>/` | A business capability, its public contracts, implementation, persistence, transport, and tests. |
+| `backend/app.development.yaml` | Local environment inputs and generated development credentials. |
 | Deployment configuration | Production connections, secrets, environment configuration, and image selection. |
-| `pyproject.toml` and `uv.lock` | Package dependencies, entry points, Python requirements, and resolved versions. |
+| `backend/pyproject.toml` and `backend/uv.lock` | Package dependencies, entry points, Python requirements, and resolved versions. |
 
-The Host initially selects PostgreSQL persistence, identity, auditing, Redis capabilities, settings, background jobs, and observability integrations. Read its dependency declarations or run `uv run pddd inspect` for the actual composition. Installing a framework dependency does not enable a module or start its resources.
+The Host initially selects PostgreSQL persistence, identity, auditing, Redis capabilities, settings, background jobs, and observability integrations. Read its dependency declarations or run `pddd inspect` for the actual composition. Installing a framework dependency does not enable a module or start its resources.
 
 ## Business-module boundaries
 
-Each generated module uses the following dependency direction:
+A `basic` module has `contracts/` and `services/`: implementation depends on the public Protocol; a consuming Module declares its dependency and injects the service. Ordinary transient DI retains native REQUEST scope and has no implicit application-service interception or HTTP exposure. It requires no database or Redis provider.
+
+A `ddd` module uses the following dependency direction:
 
 ```text
 application -> domain -> domain_shared
@@ -34,7 +36,7 @@ Host composes application, sqlalchemy, and http_api modules.
 
 | Layer | Owns | Keep outside this layer |
 | --- | --- | --- |
-| `domain_shared` | Shared values, error definitions, permission names, and business constants. | Host configuration, persistence, and transport behavior. |
+| `domain_shared` | Shared values, typed message schemas, error definitions, permission names, and business constants. | Host configuration, persistence, and transport behavior. |
 | `domain` | Aggregates, state transitions, events, repository contracts, setting definitions, and seed contributors. | ORM models, HTTP requests, and concrete infrastructure providers. |
 | `application_contracts` | Input/output DTOs and public service Protocols. | Service policies, implementation details, and ORM types. |
 | `application` | Use cases, authorization policies, event handlers, typed job handlers, workers, and integration behavior. | Database mappings and Host-specific provider selection. |
@@ -43,19 +45,39 @@ Host composes application, sqlalchemy, and http_api modules.
 
 The application layer depends on domain and application contracts. The HTTP layer consumes contracts; it does not import the application implementation. The persistence layer implements domain repository contracts. Framework types and selected native Python libraries remain available where appropriate to these responsibilities.
 
+HTTP exposure contributes the ContractsModule dependency to the normal graph. Typed realtime messages own their versioned names and payload fields in the shared layer; application handlers and HTTP sockets map business events/results explicitly. Message schemas do not import application DTOs, and the framework owns only the envelope and process-local delivery queue. Job schedules reference their registered Job type/definition and typed payload instead of duplicating persistent task identity.
+
+Immutable values shared by domain objects and public DTOs belong in `domain_shared/value_objects`; values used only inside Domain belong in `domain/value_objects`. Contracts must not depend on Domain to reuse a value. Keep one definition owner.
+
 Cross-module access uses public service contracts and explicit Module dependencies. A module owns its own data and migrations. Shared database deployment does not authorize another module to query its tables. Keep internal collaboration contracts separate from end-user service contracts where the caller and authorization semantics differ; `IntegrationService` requires its own contract and is not exposed over HTTP.
 
+The [development guide](development.md#module-layout-and-coding-rules) owns the complete directory and naming rules. Query, management, approval, and optional item operations have separate user-facing contracts. Internal reporting belongs to a separate integration contract and implementation. HTTP keeps its existing paths and operation identities through public route overrides when Python services move.
+
+Business Modules explicitly depend on the framework capabilities they use. Domain seed contributors depend on `DataSeedingModule`, permission definitions on `AuthorizationModule`, application services on `ApplicationServicesModule`, and HTTP declarations on `FastApiModule`. Host provider selection does not repair a missing business-module dependency. Capability definitions use typed module declarations; their catalogs and runtime state belong to each Application. Every Host and six-layer Module explicitly declares the seven framework hooks. Synchronous configuration phases only compose the application; asynchronous initialization phases follow dependency-first barriers, and shutdown closes resources in reverse dependency order. Empty hooks use `pass`. Generating a complete example does not enable its workers, hosted services, or schedules.
+
 ## Calls, scopes, and transactions
 
 A managed service call passes through authorization, validation, ACTION scope, unit-of-work handling, and the final implementation. HTTP and direct service invocation share this pipeline. Inject the public service contract; do not construct implementations to bypass it. A self-call is an ordinary Python call and does not re-enter the pipeline.
 
 Dishka owns service lifetimes. Repository implementations use cached REQUEST scope, application-service implementations use cached ACTION scope, and hosted services use cached APP scope. A unit of work independently owns its transaction and Session; REQUEST and ACTION scopes are not themselves transactions.
 
-Default read/write transaction behavior follows framework method/HTTP conventions and explicit policies. For a manually opened unit of work inside a managed invocation, call `complete()` before exiting. A flush is not a commit. Keep sessions local to the owning invocation and avoid transactions across external I/O or long waits.
+Default read/write transaction behavior follows framework method/HTTP conventions and explicit policies. Manual `begin()` creates and owns missing execution scopes, or reuses a valid existing context. Call `complete()` before exiting; a new transaction never rewrites the ACTION context cache. A flush is not a commit. Keep sessions local to the owning invocation and avoid transactions across external I/O or long waits.
 
 Repositories map aggregates and ORM models explicitly. Their `SqlAlchemySessionProvider.operation(..., aggregate=...)` boundary stages version changes and collects aggregate events once. Database optimistic concurrency still protects competing writes; do not replace it with a cache or a distributed lock.
 
-Local transactional events run in this order: DOMAIN handlers, flush/version checks, database commit, then AFTER_COMMIT handlers. A post-commit failure does not roll back committed data. Local events provide neither distributed delivery nor crash recovery.
+Local transactional events run in this order: DOMAIN handlers, flush/version checks, database commit, then AFTER_COMMIT handlers. Outside a UoW, `await events.publish(message)` dispatches immediately and does not claim a transaction was committed. Nontransactional UoWs reject explicit and automatic events before repository writes. A post-commit failure does not roll back committed data. Local events provide neither distributed delivery nor crash recovery.
+
+Typed caches inject `DistributedCache[Item]` and take keys/values directly. The value type owns its cache name; the Host owns the Redis prefix and global defaults. Entry options replace the whole default object. `consider_uow=True` stages changes in the concrete UoW and applies them after successful completion; rollback discards them. Redis and PostgreSQL do not share an atomic commit.
+
+## Extension ownership
+
+Identity owns core user/role fields, edit versions, and their base migrations. `concurrency_version` protects edits and relationship replacements; `permission_version` only tracks permission state. Password changes, deactivation, and deletion revoke sessions in the same transaction. Login and refresh coordinate through the user's transaction lock; refresh families retain their own lock-before-row mutation order. Consumer modules own only their declared extension columns/indexes and project-local revisions.
+
+Authorization options belong to this Application. The Host may enable `always_allow` for shared authorization checks, but authentication and real-user business requirements remain separate. The setting does not change token validation, input validation, transaction ownership, or business rules. User creation, editing, and paged results share the same application-local extension models and JSON/column mappings.
+
+Reusable modules explicitly open `ExtensionTarget` values through `ExtensionPoints`; ordinary application models need no extension registry. A customer Module depends on the target owner and contributes typed `ExtensionProperties` through `ModelExtensions`. Effective Pydantic models belong to this Application and supply validation, serialization, and OpenAPI before service methods compile, including ordinary nested DTOs, recursive fields, and native generic containers. HTTP values stay inside `extra_properties`; explicit Query/Header/Body metadata remains on the final implementation's effective signature.
+
+The persistence Module may reference those same Pydantic fields in `SqlAlchemyModelExtension` using native Column factories. Effective mapper/registry/metadata are Application-local and shared by runtime and migrations. The original module owns its table, Schema, JSON container, and core concurrency columns; the customer extension owns only its declared columns/indexes and local revisions with explicit Alembic `depends_on`. Ownership constrains both object filters and generated operations, including inline create-table columns and table comments. Current extension heads satisfy current dependencies; historical revisions keep their original dependencies. Module dependencies do not imply database prerequisites. Never patch shared framework models or author revisions in installed packages.
 
 ## Configuration and lifecycle
 
@@ -63,6 +85,14 @@ The Host selects the environment through `{{ cookiecutter.host_environment_varia
 
 Modules bind typed `BaseOptions` models with `context.configure(...)`; services inject `Options[T]`. Startup options and mutable runtime settings have separate purposes. `SettingProvider` reads settings; conditional management updates use the current version token.
 
+`MessagingModule` owns bounded in-process channels and their lifecycle. Each message type has
+one declared channel and a cached ACTION Handler binding. Consumption creates a fresh
+REQUEST/ACTION through the hosted bridge; idle receive holds no transaction. Closing admission
+still permits previously accepted work through one-use reservations. Failure/deadline handling
+waits for handler/UoW/finalizer exit. Only pending replaceable snapshots may coalesce. Messages
+are independent of local events, durable Jobs and WebSocket delivery; see
+[usage](development.md#in-process-messages).
+
 An Application owns its runtime state, DI container, connections, and background execution. Module definitions can be shared; mutable runtime state cannot. No global application registry or service locator is required.
 
 Module initialization precedes selected hosted services and background execution. Shutdown waits for real cleanup. The Host does not migrate or seed the database. `dev-init` prepares local infrastructure, while explicit `db` commands own migration and seed operations.