python-ddd-framework 0.4.0__tar.gz → 0.6.0__tar.gz

{python_ddd_framework-0.4.0 → python_ddd_framework-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-ddd-framework
-Version: 0.4.0
+Version: 0.6.0
 Summary: Modular DDD application framework with project CLI and bundled templates
 License-Expression: LicenseRef-Proprietary
 License-File: LICENSE
@@ -86,7 +86,7 @@ Runtime integrations ship in the base package; the Host explicitly enables the m
 
 The supported versions and dependencies are defined in [pyproject.toml](https://github.com/componet-architecture/python-ddd-framework/blob/main/pyproject.toml). The framework, CLI, and bundled templates share one package version.
 
-> **Version 0.4:** This release introduces capability-based composition, current service and Identity APIs, and the `backend/` consumer layout with basic/DDD module templates. Existing applications must apply the migration instructions below. Check [release status](https://github.com/componet-architecture/python-ddd-framework/blob/main/docs/status.md#当前发布) for publication and validation evidence. Use the local-wheel route below when evaluating a checkout that has not been published.
+> **Version 0.6:** This version separates Identity credential and management contracts, enforces stable aggregate event values, corrects joined Unit of Work diagnostics, and adds recoverable CLI module publication. Apply the migration instructions below; previous Identity imports have no compatibility aliases. Check [release status](https://github.com/componet-architecture/python-ddd-framework/blob/main/docs/status.md#当前发布) for publication and validation evidence. Use the local-wheel route below when evaluating a checkout that has not been published.
 
 ### 1. Install the CLI and create a project
 
@@ -194,6 +194,34 @@ pddd db status --module orders --environment production
 
 Generation supports `--dry-run` without writing files. Database commands require `--module`; aliases come from installed `python_ddd_framework.modules` entry points and must belong to the current application's module graph.
 
+### Recovering a failed module addition
+
+`add module` prints a recovery directory under the identified backend's
+`.python-ddd-framework/generation/<operation-id>/`. It retains original bytes, proposed
+startup/metadata files, a module file manifest, step records and `uv-sync.log`. The rendered
+template and any unfinished sibling copies are retained too. Open that operation's
+`RECOVERY.md` for its paths and a copyable, read-only inspection procedure.
+
+Stop other generators and editors before recovery. Compare the actual files with the
+recorded digests: continue only from the recorded original content, or restore an original
+file only while the target still matches this operation's proposed content. Review any
+other content manually. Keep generated directories and markers until you explicitly decide
+what to do with them; rerunning `add module` does not repair a partial publication.
+
+When all project files match the proposed contents but installation failed, use the
+independent sync script in that operation's `RECOVERY.md`. Run it with `python -I` as
+instructed. It clears the CLI's recorded Python/uv environment overrides before running
+`uv sync` in the identified backend, including overrides set after generation. A bare
+`uv sync --directory` still inherits environment overrides and can select another
+virtual environment. The retry preserves your shell environment and the original records.
+
+File publication and installation have separate results. An interrupted or missing step
+record requires checking the files; it does not prove that the write failed. The CLI does
+not automatically restore, move or delete the failure site, roll back the environment or
+lockfile, or guarantee a transaction across files or power-loss recovery.
+
+### Project command environment
+
 `db` and `inspect` use `--environment`, then `PYTHON_DDD_FRAMEWORK_ENVIRONMENT`, then `development`. `dev` always selects development, and `dev-init` is restricted to development infrastructure.
 
 `inspect` builds and closes the application without starting services or running migrations. Its output describes a newly composed Host, not a running process. Configuration output contains input values and their sources; it does not include Options defaults or later module contributions.
@@ -290,6 +318,17 @@ The current contracts are in [architecture](https://github.com/componet-architec
 - Replace `CacheDefinition`/`CacheDefinitions`/`CacheCatalog` with injected `DistributedCache[ValueType]`; remove cache declarations from Modules. Use `@cache_name("stable.name")` on the value type if required. Calls take keys/values directly. Configure global `caching.default_entry_options` or pass a complete `DistributedCacheEntryOptions`; omitted options use the default 20-minute sliding expiration, while an empty options object is persistent. Development Hosts explicitly set `caching.hide_errors: false`.
 - Redis cache keys and entry encoding changed; old disposable entries are not read or migrated. They expire under their old TTL. `consider_uow=True` stages writes/deletions per concrete UoW; completion failures retain the committed database fact and do not make the two resources atomic. Do not retry an entire committed business operation merely because an AFTER_COMMIT handler or cache write failed.
 
+## Aggregate event values (0.6)
+
+`AggregateRoot.raise_local_event` now checks nested field values before enqueueing. Events must be frozen dataclass instances or frozen Pydantic models whose fields follow the [aggregate event value contract](https://github.com/componet-architecture/python-ddd-framework/blob/main/docs/architecture.md#聚合事件值).
+
+- Replace mutable containers with tuples, frozensets, or explicit frozen value records. Decorating a mutable-container subclass with `frozen=True` does not make it an accepted event value. Map entity references to the IDs and values the event needs at the publishing point. A `MappingProxyType` still exposes changes to its backing dictionary and is rejected.
+- Remove private, cached, or undeclared instance state from event records. Pydantic models with `extra="allow"` are rejected. Dataclass subclasses must themselves be decorated with `frozen=True`.
+- Normalize database-driver scalar subclasses at the repository mapping boundary. For example, rebuild an asyncpg UUID as `UUID(bytes=row.id.bytes)` before passing it to a domain aggregate; the event validator accepts native `uuid.UUID` values.
+- Rejected events raise `TypeError` before altering the aggregate queue. Accepted events retain their identity; the framework does not copy or convert them. Direct `LocalEventBus.publish` and repository entity-change notifications retain their existing behavior.
+
+Redis batch calls keep serial I/O to preserve first-error, cancellation, and expiry side effects. Cache keys, entry encoding, and UoW pending-write behavior retain their existing contracts.
+
 ## Message processing (0.4)
 
 Opt in with `MessagingModule`, `MessageChannelDefinition[T]`, `MessageHandler[T]` and the
@@ -335,6 +374,31 @@ Slice 7 adds user/role management and an application-local authorization switch.
 
 See the [Identity guide](https://github.com/componet-architecture/python-ddd-framework/blob/main/docs/development.md#identity-管理与授权配置) and [validation limits](https://github.com/componet-architecture/python-ddd-framework/blob/main/docs/status.md#identity-与授权切片-7未发布). Consumer delivery is described in the layout migration below; fresh acceptance and remaining release limits are recorded on the status page.
 
+## Identity contract refactor (0.6)
+
+Version 0.6 replaces `IdentityRepository` with two independent contracts exported from `python_ddd_framework.identity`:
+
+- `IdentityCredentialStore`: `get_user` and `set_password`, including the existing concurrency version and expected password hash.
+- `IdentityManagementStore`: user/role creation, queries, edits, deletion and relationship updates. Password writes belong to the credential contract.
+
+Authentication now receives `credentials`; management receives `store` and `credentials`; administrator seeding receives `store`. Update custom providers and directly constructed or subclassed defaults to these contracts. A shared implementation can use Dishka's native registration:
+
+```python
+from dishka import AnyOf, Provider, Scope
+from python_ddd_framework.identity import IdentityCredentialStore, IdentityManagementStore
+
+provider = Provider()
+provider.provide(
+    MyIdentityStore,
+    provides=AnyOf[MyIdentityStore, IdentityCredentialStore, IdentityManagementStore],
+    scope=Scope.REQUEST,
+)
+```
+
+`MyIdentityStore` is the consumer's implementation. The built-in SQLAlchemy provider registers its existing implementation this way. Providers may also implement and register the two contracts separately. Each implementation must keep the existing transaction and credential concurrency rules.
+
+For direct submodule imports, use `identity.options`, `identity.dtos`, `identity.models`, `identity.stores`, and `identity.extensions`. `identity.contracts` owns application-service contracts and permission names. `IdentityAdminSeedContributor` is defined in `identity.seeding`, which `IdentityModule` scans. The former `IdentityRepository` export and old definition paths have no compatibility shims. This refactor changes no HTTP payload, token format, database schema or migration.
+
 ## Extension migration (0.4)
 
 - Identity exposes `DefaultAuthenticationApplicationService` and `DefaultIdentityManagementApplicationService`. Specialize these public defaults and use the existing module override registration; keep policies on the final methods. Remove imports of the former private implementations.
@@ -368,6 +432,20 @@ During `0.x`, compatible fixes use a patch release; changes requiring consumer a
 
 These notes remain the authoritative consumer migration instructions. Historical versions below refer to the former package name.
 
+#### Unit of Work participant diagnostics (0.6)
+
+An inner `begin()` that joins an existing Unit of Work now reads all transaction and cleanup facts from the owner. Completing or leaving the inner scope does not imply that the owner has committed or released its resources. Retained participant references continue to report the owner's latest outcome, including unknown commit results, saved batches and cleanup failures, while rejecting further operations after local completion or exit.
+
+Do not use a participant's `resources_released` to detect exit from the inner scope; use the context manager boundary. Public types, signatures and provider hooks retain their existing contracts. This correction is introduced in 0.6.0.
+
+#### Lifecycle shutdown migration (0.5)
+
+Version 0.5.1 changes shutdown after the published 0.4.0 baseline. Custom `RuntimeParticipant` implementations must use the new global barriers: `quiesce` → `stopping(reason)` → `close_admission` → `drain` → `stop(reason)` → Module/container cleanup. Move accepted-work draining out of resource `stop`; keep dependencies alive until all drains complete. `prepare(bool)` still selects the startup mode.
+
+Move business calls needed before resource release into the optional `HostedService.stopping(context, reason)` hook. Use its separate context for SDK/thread callbacks; the startup context stays closed. Only successfully started services receive the hook. `stop` still cleans every touched service, including partial startup failures. Each hook uses the existing `shutdown_timeout`; cancellation waits for actual cleanup and is not a total shutdown deadline.
+
+Channels that must accept these callbacks declare `stopping_owners=(ServiceType,)` and pass the current hook context with `send(value, stopping=context)` or `submit(value, stopping=context)`. The channel Module must depend on the declared service owner. The default permits no shutdown input. Capacity, receipts and per-call scope/UoW behavior remain unchanged; HTTP/WebSocket retain native transport shutdown. See the [lifecycle decision](docs/adr/ADR-033-staged-lifecycle-shutdown.md) and [usage guide](docs/development.md#hostedservice-收尾).
+
 #### Additional fixes in 0.4.0
 
 `BackgroundJobRetryPolicy.max_attempts` now counts all executions, including the first. A value of `2` permits two executions; `1` disables failure retries. The 0.3.2 PgQueuer mapping allowed one extra execution. If your application intentionally relied on that behavior, increase its configured total by one. `BackgroundJobContext.attempt` remains zero-based. No queue schema migration is required.
@@ -447,7 +525,7 @@ Do not remove durable job payload versions merely because their Python APIs were
 <details>
 <summary>For maintainers: publishing a changed version</summary>
 
-Routine code and documentation commits may retain the current version. Pushes to `main` still run CI but skip publication unless the version increased across the push; initial creation of `main` publishes its current version. Manual workflow runs validate only. A failed run may be retried, but a later same-version push does not resume publication: changed contents require another version bump. Follow [release operations](https://github.com/componet-architecture/python-ddd-framework/blob/main/docs/development.md#发布操作) for publisher setup and retry boundaries. A future version is not evidence of a completed upgrade test.
+Routine code and documentation commits may retain the current version. Pull requests to `main` run build, static checks, and short architecture/typing/release-intent checks with read-only permissions. Pushes to `main` run the full release gates, including locked, lowest-direct, and highest allowed dependency samples, but skip publication unless the version increased across the push; initial creation of `main` publishes its current version. Manual workflow runs validate only. A failed run may be retried, but a later same-version push does not resume publication: changed contents require another version bump. Follow [release operations](https://github.com/componet-architecture/python-ddd-framework/blob/main/docs/development.md#发布操作) for publisher setup and retry boundaries. Dependency samples and current API/type checks do not establish backward compatibility or a cross-version upgrade guarantee.
 
 </details>
 
@@ -463,7 +541,7 @@ The engineering guides below are maintained in Chinese in the private GitHub rep
 | Check release evidence and remaining validation limits | [Status and validation](https://github.com/componet-architecture/python-ddd-framework/blob/main/docs/status.md) |
 | Change the framework itself | [Contributor guidance](https://github.com/componet-architecture/python-ddd-framework/blob/main/AGENTS.md) and [focused reading paths](https://github.com/componet-architecture/python-ddd-framework/blob/main/docs/README.md#重构的最短阅读路径) |
 
-Generated applications include a self-contained English README, `AGENTS.md`, architecture document, and development guide for their template version. `AGENTS.md` directs Codex and other contributors to the affected guidance and module README. Each document has a distinct owner, and the application maintains them after generation; framework upgrades do not overwrite them.
+Generated applications include a self-contained English README, `AGENTS.md`, architecture document, and development guide for their template version. `AGENTS.md` guides contributors from business rules and ownership to framework capability selection and verification. The development guide maps common tasks to framework capabilities and includes commands to locate the installed version's source and bundled examples; each DDD module README records the sample business model and traces approval through its owners. The application maintains these documents after generation; framework upgrades do not overwrite them. Existing applications can use their installed package's `developer_kit/templates` as a read-only reference when updating affected guidance, preserving their own business model and decisions.
 
 ## License
 

{python_ddd_framework-0.4.0 → python_ddd_framework-0.6.0}/README.md

@@ -42,7 +42,7 @@ Runtime integrations ship in the base package; the Host explicitly enables the m
 
 The supported versions and dependencies are defined in [pyproject.toml](https://github.com/componet-architecture/python-ddd-framework/blob/main/pyproject.toml). The framework, CLI, and bundled templates share one package version.
 
-> **Version 0.4:** This release introduces capability-based composition, current service and Identity APIs, and the `backend/` consumer layout with basic/DDD module templates. Existing applications must apply the migration instructions below. Check [release status](https://github.com/componet-architecture/python-ddd-framework/blob/main/docs/status.md#当前发布) for publication and validation evidence. Use the local-wheel route below when evaluating a checkout that has not been published.
+> **Version 0.6:** This version separates Identity credential and management contracts, enforces stable aggregate event values, corrects joined Unit of Work diagnostics, and adds recoverable CLI module publication. Apply the migration instructions below; previous Identity imports have no compatibility aliases. Check [release status](https://github.com/componet-architecture/python-ddd-framework/blob/main/docs/status.md#当前发布) for publication and validation evidence. Use the local-wheel route below when evaluating a checkout that has not been published.
 
 ### 1. Install the CLI and create a project
 
@@ -150,6 +150,34 @@ pddd db status --module orders --environment production
 
 Generation supports `--dry-run` without writing files. Database commands require `--module`; aliases come from installed `python_ddd_framework.modules` entry points and must belong to the current application's module graph.
 
+### Recovering a failed module addition
+
+`add module` prints a recovery directory under the identified backend's
+`.python-ddd-framework/generation/<operation-id>/`. It retains original bytes, proposed
+startup/metadata files, a module file manifest, step records and `uv-sync.log`. The rendered
+template and any unfinished sibling copies are retained too. Open that operation's
+`RECOVERY.md` for its paths and a copyable, read-only inspection procedure.
+
+Stop other generators and editors before recovery. Compare the actual files with the
+recorded digests: continue only from the recorded original content, or restore an original
+file only while the target still matches this operation's proposed content. Review any
+other content manually. Keep generated directories and markers until you explicitly decide
+what to do with them; rerunning `add module` does not repair a partial publication.
+
+When all project files match the proposed contents but installation failed, use the
+independent sync script in that operation's `RECOVERY.md`. Run it with `python -I` as
+instructed. It clears the CLI's recorded Python/uv environment overrides before running
+`uv sync` in the identified backend, including overrides set after generation. A bare
+`uv sync --directory` still inherits environment overrides and can select another
+virtual environment. The retry preserves your shell environment and the original records.
+
+File publication and installation have separate results. An interrupted or missing step
+record requires checking the files; it does not prove that the write failed. The CLI does
+not automatically restore, move or delete the failure site, roll back the environment or
+lockfile, or guarantee a transaction across files or power-loss recovery.
+
+### Project command environment
+
 `db` and `inspect` use `--environment`, then `PYTHON_DDD_FRAMEWORK_ENVIRONMENT`, then `development`. `dev` always selects development, and `dev-init` is restricted to development infrastructure.
 
 `inspect` builds and closes the application without starting services or running migrations. Its output describes a newly composed Host, not a running process. Configuration output contains input values and their sources; it does not include Options defaults or later module contributions.
@@ -246,6 +274,17 @@ The current contracts are in [architecture](https://github.com/componet-architec
 - Replace `CacheDefinition`/`CacheDefinitions`/`CacheCatalog` with injected `DistributedCache[ValueType]`; remove cache declarations from Modules. Use `@cache_name("stable.name")` on the value type if required. Calls take keys/values directly. Configure global `caching.default_entry_options` or pass a complete `DistributedCacheEntryOptions`; omitted options use the default 20-minute sliding expiration, while an empty options object is persistent. Development Hosts explicitly set `caching.hide_errors: false`.
 - Redis cache keys and entry encoding changed; old disposable entries are not read or migrated. They expire under their old TTL. `consider_uow=True` stages writes/deletions per concrete UoW; completion failures retain the committed database fact and do not make the two resources atomic. Do not retry an entire committed business operation merely because an AFTER_COMMIT handler or cache write failed.
 
+## Aggregate event values (0.6)
+
+`AggregateRoot.raise_local_event` now checks nested field values before enqueueing. Events must be frozen dataclass instances or frozen Pydantic models whose fields follow the [aggregate event value contract](https://github.com/componet-architecture/python-ddd-framework/blob/main/docs/architecture.md#聚合事件值).
+
+- Replace mutable containers with tuples, frozensets, or explicit frozen value records. Decorating a mutable-container subclass with `frozen=True` does not make it an accepted event value. Map entity references to the IDs and values the event needs at the publishing point. A `MappingProxyType` still exposes changes to its backing dictionary and is rejected.
+- Remove private, cached, or undeclared instance state from event records. Pydantic models with `extra="allow"` are rejected. Dataclass subclasses must themselves be decorated with `frozen=True`.
+- Normalize database-driver scalar subclasses at the repository mapping boundary. For example, rebuild an asyncpg UUID as `UUID(bytes=row.id.bytes)` before passing it to a domain aggregate; the event validator accepts native `uuid.UUID` values.
+- Rejected events raise `TypeError` before altering the aggregate queue. Accepted events retain their identity; the framework does not copy or convert them. Direct `LocalEventBus.publish` and repository entity-change notifications retain their existing behavior.
+
+Redis batch calls keep serial I/O to preserve first-error, cancellation, and expiry side effects. Cache keys, entry encoding, and UoW pending-write behavior retain their existing contracts.
+
 ## Message processing (0.4)
 
 Opt in with `MessagingModule`, `MessageChannelDefinition[T]`, `MessageHandler[T]` and the
@@ -291,6 +330,31 @@ Slice 7 adds user/role management and an application-local authorization switch.
 
 See the [Identity guide](https://github.com/componet-architecture/python-ddd-framework/blob/main/docs/development.md#identity-管理与授权配置) and [validation limits](https://github.com/componet-architecture/python-ddd-framework/blob/main/docs/status.md#identity-与授权切片-7未发布). Consumer delivery is described in the layout migration below; fresh acceptance and remaining release limits are recorded on the status page.
 
+## Identity contract refactor (0.6)
+
+Version 0.6 replaces `IdentityRepository` with two independent contracts exported from `python_ddd_framework.identity`:
+
+- `IdentityCredentialStore`: `get_user` and `set_password`, including the existing concurrency version and expected password hash.
+- `IdentityManagementStore`: user/role creation, queries, edits, deletion and relationship updates. Password writes belong to the credential contract.
+
+Authentication now receives `credentials`; management receives `store` and `credentials`; administrator seeding receives `store`. Update custom providers and directly constructed or subclassed defaults to these contracts. A shared implementation can use Dishka's native registration:
+
+```python
+from dishka import AnyOf, Provider, Scope
+from python_ddd_framework.identity import IdentityCredentialStore, IdentityManagementStore
+
+provider = Provider()
+provider.provide(
+    MyIdentityStore,
+    provides=AnyOf[MyIdentityStore, IdentityCredentialStore, IdentityManagementStore],
+    scope=Scope.REQUEST,
+)
+```
+
+`MyIdentityStore` is the consumer's implementation. The built-in SQLAlchemy provider registers its existing implementation this way. Providers may also implement and register the two contracts separately. Each implementation must keep the existing transaction and credential concurrency rules.
+
+For direct submodule imports, use `identity.options`, `identity.dtos`, `identity.models`, `identity.stores`, and `identity.extensions`. `identity.contracts` owns application-service contracts and permission names. `IdentityAdminSeedContributor` is defined in `identity.seeding`, which `IdentityModule` scans. The former `IdentityRepository` export and old definition paths have no compatibility shims. This refactor changes no HTTP payload, token format, database schema or migration.
+
 ## Extension migration (0.4)
 
 - Identity exposes `DefaultAuthenticationApplicationService` and `DefaultIdentityManagementApplicationService`. Specialize these public defaults and use the existing module override registration; keep policies on the final methods. Remove imports of the former private implementations.
@@ -324,6 +388,20 @@ During `0.x`, compatible fixes use a patch release; changes requiring consumer a
 
 These notes remain the authoritative consumer migration instructions. Historical versions below refer to the former package name.
 
+#### Unit of Work participant diagnostics (0.6)
+
+An inner `begin()` that joins an existing Unit of Work now reads all transaction and cleanup facts from the owner. Completing or leaving the inner scope does not imply that the owner has committed or released its resources. Retained participant references continue to report the owner's latest outcome, including unknown commit results, saved batches and cleanup failures, while rejecting further operations after local completion or exit.
+
+Do not use a participant's `resources_released` to detect exit from the inner scope; use the context manager boundary. Public types, signatures and provider hooks retain their existing contracts. This correction is introduced in 0.6.0.
+
+#### Lifecycle shutdown migration (0.5)
+
+Version 0.5.1 changes shutdown after the published 0.4.0 baseline. Custom `RuntimeParticipant` implementations must use the new global barriers: `quiesce` → `stopping(reason)` → `close_admission` → `drain` → `stop(reason)` → Module/container cleanup. Move accepted-work draining out of resource `stop`; keep dependencies alive until all drains complete. `prepare(bool)` still selects the startup mode.
+
+Move business calls needed before resource release into the optional `HostedService.stopping(context, reason)` hook. Use its separate context for SDK/thread callbacks; the startup context stays closed. Only successfully started services receive the hook. `stop` still cleans every touched service, including partial startup failures. Each hook uses the existing `shutdown_timeout`; cancellation waits for actual cleanup and is not a total shutdown deadline.
+
+Channels that must accept these callbacks declare `stopping_owners=(ServiceType,)` and pass the current hook context with `send(value, stopping=context)` or `submit(value, stopping=context)`. The channel Module must depend on the declared service owner. The default permits no shutdown input. Capacity, receipts and per-call scope/UoW behavior remain unchanged; HTTP/WebSocket retain native transport shutdown. See the [lifecycle decision](docs/adr/ADR-033-staged-lifecycle-shutdown.md) and [usage guide](docs/development.md#hostedservice-收尾).
+
 #### Additional fixes in 0.4.0
 
 `BackgroundJobRetryPolicy.max_attempts` now counts all executions, including the first. A value of `2` permits two executions; `1` disables failure retries. The 0.3.2 PgQueuer mapping allowed one extra execution. If your application intentionally relied on that behavior, increase its configured total by one. `BackgroundJobContext.attempt` remains zero-based. No queue schema migration is required.
@@ -403,7 +481,7 @@ Do not remove durable job payload versions merely because their Python APIs were
 <details>
 <summary>For maintainers: publishing a changed version</summary>
 
-Routine code and documentation commits may retain the current version. Pushes to `main` still run CI but skip publication unless the version increased across the push; initial creation of `main` publishes its current version. Manual workflow runs validate only. A failed run may be retried, but a later same-version push does not resume publication: changed contents require another version bump. Follow [release operations](https://github.com/componet-architecture/python-ddd-framework/blob/main/docs/development.md#发布操作) for publisher setup and retry boundaries. A future version is not evidence of a completed upgrade test.
+Routine code and documentation commits may retain the current version. Pull requests to `main` run build, static checks, and short architecture/typing/release-intent checks with read-only permissions. Pushes to `main` run the full release gates, including locked, lowest-direct, and highest allowed dependency samples, but skip publication unless the version increased across the push; initial creation of `main` publishes its current version. Manual workflow runs validate only. A failed run may be retried, but a later same-version push does not resume publication: changed contents require another version bump. Follow [release operations](https://github.com/componet-architecture/python-ddd-framework/blob/main/docs/development.md#发布操作) for publisher setup and retry boundaries. Dependency samples and current API/type checks do not establish backward compatibility or a cross-version upgrade guarantee.
 
 </details>
 
@@ -419,7 +497,7 @@ The engineering guides below are maintained in Chinese in the private GitHub rep
 | Check release evidence and remaining validation limits | [Status and validation](https://github.com/componet-architecture/python-ddd-framework/blob/main/docs/status.md) |
 | Change the framework itself | [Contributor guidance](https://github.com/componet-architecture/python-ddd-framework/blob/main/AGENTS.md) and [focused reading paths](https://github.com/componet-architecture/python-ddd-framework/blob/main/docs/README.md#重构的最短阅读路径) |
 
-Generated applications include a self-contained English README, `AGENTS.md`, architecture document, and development guide for their template version. `AGENTS.md` directs Codex and other contributors to the affected guidance and module README. Each document has a distinct owner, and the application maintains them after generation; framework upgrades do not overwrite them.
+Generated applications include a self-contained English README, `AGENTS.md`, architecture document, and development guide for their template version. `AGENTS.md` guides contributors from business rules and ownership to framework capability selection and verification. The development guide maps common tasks to framework capabilities and includes commands to locate the installed version's source and bundled examples; each DDD module README records the sample business model and traces approval through its owners. The application maintains these documents after generation; framework upgrades do not overwrite them. Existing applications can use their installed package's `developer_kit/templates` as a read-only reference when updating affected guidance, preserving their own business model and decisions.
 
 ## License
 

{python_ddd_framework-0.4.0 → python_ddd_framework-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-ddd-framework"
-version = "0.4.0"
+version = "0.6.0"
 description = "Modular DDD application framework with project CLI and bundled templates"
 readme = "README.md"
 license = "LicenseRef-Proprietary"

{python_ddd_framework-0.4.0 → python_ddd_framework-0.6.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "python-ddd-framework"
-version = "0.4.0"
+version = "0.6.0"
 description = "Modular DDD application framework with project CLI and bundled templates"
 readme = "README.md"
 license = "LicenseRef-Proprietary"

{python_ddd_framework-0.4.0 → python_ddd_framework-0.6.0}/src/python_ddd_framework/application/runtime.py

@@ -3,6 +3,8 @@
 from __future__ import annotations
 
 import asyncio
+from collections.abc import Awaitable, Callable, Iterable
+from functools import partial
 from typing import Never
 from uuid import UUID
 
@@ -155,27 +157,25 @@ class Application:
 
     async def _stop_runtimes(self, reason: ShutdownReason) -> tuple[BaseException, ...]:
         failures: list[BaseException] = []
-        # 先统一关闭外部准入，再逆序排空依赖；一个能力失败不能阻止其余能力释放资源。
-        # stop 只交给触达过 start 的参与者；预启动入口已接受的资源由独立 drain 收口。
+        # 每个阶段都是全局屏障；收尾与排空完成前，不释放任何参与者的依赖资源。
+        # 用户钩子只交给触达过 start 的参与者；预启动请求仍由独立 drain 收口。
         participants = tuple(reversed(self._root.touched_runtimes))
-        for participant in participants:
-            if participant.close_admission is not None:
-                try:
-                    participant.close_admission()
-                except BaseException as error:
-                    failures.append(error)
-        for participant in participants:
-            try:
-                failures.extend(await participant.stop(reason))
-            except BaseException as error:
-                failures.append(error)
+        failures.extend(_call_shutdown_callbacks(item.quiesce for item in participants))
+        failures.extend(
+            await _await_shutdown_callbacks(
+                partial(item.stopping, reason) for item in participants if item.stopping is not None
+            )
+        )
+        failures.extend(_call_shutdown_callbacks(item.close_admission for item in participants))
+        failures.extend(
+            await _await_shutdown_callbacks(
+                item.drain for item in reversed(self._root.runtimes) if item.drain is not None
+            )
+        )
+        failures.extend(
+            await _await_shutdown_callbacks(partial(item.stop, reason) for item in participants)
+        )
         self._root.touched_runtimes.clear()
-        for participant in reversed(self._root.runtimes):
-            if participant.drain is not None:
-                try:
-                    await participant.drain()
-                except BaseException as error:
-                    failures.append(error)
         return tuple(failures)
 
     async def stop(self) -> None:
@@ -352,3 +352,30 @@ class Application:
                 if not watcher.done():
                     watcher.cancel()
             await asyncio.gather(*watchers, return_exceptions=True)
+
+
+def _call_shutdown_callbacks(
+    callbacks: Iterable[Callable[[], None] | None],
+) -> tuple[BaseException, ...]:
+    failures: list[BaseException] = []
+    for callback in callbacks:
+        if callback is not None:
+            try:
+                callback()
+            except BaseException as error:
+                failures.append(error)
+    return tuple(failures)
+
+
+async def _await_shutdown_callbacks(
+    callbacks: Iterable[Callable[[], Awaitable[tuple[BaseException, ...] | None]]],
+) -> tuple[BaseException, ...]:
+    failures: list[BaseException] = []
+    for callback in callbacks:
+        try:
+            result = await callback()
+            if result is not None:
+                failures.extend(result)
+        except BaseException as error:
+            failures.append(error)
+    return tuple(failures)

{python_ddd_framework-0.4.0 → python_ddd_framework-0.6.0}/src/python_ddd_framework/application_services/bindings.py

@@ -9,15 +9,12 @@ from typing import get_origin
 from dishka import (
     DEFAULT_COMPONENT,
     DependencyKey,
-    Provider,
     Scope,
 )
 
 from ..diagnostics import SourceLocation
 from ..modularity import ModuleRegistry
 from ..services.arbitration import (
-    _ArbitrationResult,
-    _provider_with_active_sources,
     _RegistrationDraft,
 )
 from ..services.native_graph import _NativeServiceGraph
@@ -201,64 +198,3 @@ def _validate_application_service_bindings(
                     "or private implementation binding"
                 ),
             )
-
-
-def _runtime_providers(
-    arbitration: _ArbitrationResult,
-    services: tuple[_BoundApplicationService, ...],
-) -> tuple[Provider, ...]:
-    """仅重定位 Application Service factories；其他 Dishka provider 保持原生形状。"""
-
-    related_draft_ids = frozenset(
-        draft_id for service in services for draft_id in service.related_draft_ids
-    )
-    drafts_by_entry: dict[int, list[_RegistrationDraft]] = {}
-    for draft in arbitration.drafts:
-        drafts_by_entry.setdefault(draft.entry.entry_id, []).append(draft)
-
-    providers: list[Provider] = []
-    for entry in arbitration.ordered_entries:
-        entry_drafts = drafts_by_entry[entry.entry_id]
-        active = tuple(
-            draft
-            for draft in entry_drafts
-            if draft.decision is not RegistrationDecision.BACKED_OFF
-            and id(draft) not in related_draft_ids
-        )
-        if not active:
-            continue
-        if len(active) == len(entry_drafts):
-            providers.append(entry.contribution.provider)
-        else:
-            providers.append(_provider_with_active_sources(entry.contribution.provider, active))
-
-    # default component 只发布 REQUEST proxy；ACTION implementation 统一藏入框架私有 component。
-    implementation_provider = Provider(component=_APPLICATION_SERVICE_COMPONENT)
-    for service in services:
-        winner = service.winner
-        assert winner.factory is not None
-        # internal contributor 被 override 时仍以原声明 key 调度；
-        # winner class 只是实现事实，不能改写契约 key。
-        contract = (
-            service.binding.discovery.definition.contract or service.binding.discovery.service_type
-        )
-        implementation_provider.factories.append(
-            winner.factory.replace(
-                dependencies=tuple(
-                    dependency.with_component(DEFAULT_COMPONENT)
-                    for dependency in winner.factory.dependencies
-                ),
-                kw_dependencies={
-                    name: dependency.with_component(DEFAULT_COMPONENT)
-                    for name, dependency in winner.factory.kw_dependencies.items()
-                },
-                provides=DependencyKey(contract, None),
-                when_override=None,
-                when_component=DEFAULT_COMPONENT,
-            )
-        )
-        # ServiceCatalog 的 accepted row 必须描述 relocated native binding，而非旧 default key。
-        winner.key = DependencyKey(contract, _APPLICATION_SERVICE_COMPONENT)
-    if services:
-        providers.append(implementation_provider)
-    return tuple(providers)

{python_ddd_framework-0.4.0 → python_ddd_framework-0.6.0}/src/python_ddd_framework/application_services/dispatcher.py

@@ -13,6 +13,7 @@ from dishka import AsyncContainer
 from ..invocation.dispatcher import _MethodDispatcher
 from ..invocation.execution import _InterceptorPipeline
 from ..invocation.methods import _CompiledMethod
+from ..invocation.runtime import _current_task, _InvocationRuntime
 from ..settings.provider import SettingProvider
 from .catalog import (
     _APPLICATION_SERVICE_COMPONENT,
@@ -22,7 +23,6 @@ from .contracts import ApplicationService
 from .errors import (
     CrossTaskInvocationError,
 )
-from .invocation import _current_task, _InvocationRuntime
 
 
 @dataclass(slots=True)

python_ddd_framework-0.6.0/src/python_ddd_framework/application_services/invocation.py

@@ -0,0 +1,57 @@
+"""应用服务 Contract 的 REQUEST 代理入口；准入与 scope 清理由 Invocation 拥有。"""
+
+from collections.abc import Awaitable, Callable
+from typing import cast
+
+from dishka import AsyncContainer, Scope
+
+from ..authorization import CurrentUser
+from ..invocation.runtime import _InvocationRuntime
+from ..invocation.scopes import _managed_request
+from .catalog import ApplicationServiceCatalog
+
+
+class _ScopedApplicationServiceInvoker:
+    """从 Application root 或其 SESSION 建立 REQUEST，不向 caller 暴露 resolver。"""
+
+    __slots__ = ("_catalog", "_root_container", "_runtime")
+
+    def __init__(
+        self,
+        container: AsyncContainer,
+        runtime: _InvocationRuntime,
+        catalog: ApplicationServiceCatalog,
+    ) -> None:
+        self._root_container = container
+        self._runtime = runtime
+        self._catalog = catalog
+
+    async def invoke(
+        self,
+        parent: AsyncContainer,
+        current_user: CurrentUser,
+        correlation_id: str,
+        method: Callable[..., Awaitable[object]],
+        args: tuple[object, ...],
+        kwargs: dict[str, object],
+    ) -> object:
+        self._require_owned_parent(parent)
+        service, compiled = self._catalog._resolve_method(method)
+        async with self._runtime.outer_lease():
+            caller_token = self._runtime.bind_caller(current_user, correlation_id)
+            try:
+                async with _managed_request(parent) as request_container:
+                    proxy = await request_container.get(service.registration.contract)
+                    call = cast(
+                        Callable[..., Awaitable[object]],
+                        getattr(proxy, compiled.name),
+                    )
+                    return await call(*args, **kwargs)
+            finally:
+                self._runtime.reset_caller(caller_token)
+
+    def _require_owned_parent(self, parent: AsyncContainer) -> None:
+        if parent is self._root_container:
+            return
+        if parent.scope is not Scope.SESSION or parent.parent_container is not self._root_container:
+            raise RuntimeError("scoped invocation parent is not owned by this Application")

{python_ddd_framework-0.4.0 → python_ddd_framework-0.6.0}/src/python_ddd_framework/application_services/module.py

@@ -25,15 +25,16 @@ from ..services.convention_contracts import (
     ConventionDiscoveryKind,
     _ServiceDefinition,
 )
+from ..services.relocation import _BindingRelocation
 from ..settings.module import SettingsModule
 from ..unit_of_work.module import UnitOfWorkModule
 from .bindings import (
     _bind_application_services,
-    _runtime_providers,
     _validate_application_service_bindings,
     _validate_application_service_dependencies,
 )
 from .catalog import (
+    _APPLICATION_SERVICE_COMPONENT,
     ApplicationServiceCatalog,
     _build_application_service_catalog,
     _DiscoveredApplicationService,
@@ -130,10 +131,20 @@ class ApplicationServicesModule(AppModule):
             context.modules.instance(InvocationModule).rules,
             context.modules.instance(ExtensionsModule).catalog,
         )
-        # 只重定位仲裁后的原生绑定，保留其他能力已经生成的目录 Provider。
-        for provider in context.arbitration.providers:
-            context._providers.remove(provider)
-        context._providers[0:0] = _runtime_providers(context.arbitration, bound)
+        # 能力只决定私有实现 key；来源、工厂搬迁和贡献指纹仍由 services 管理。
+        context._relocate_bindings(
+            tuple(
+                _BindingRelocation(
+                    item.winner,
+                    DependencyKey(
+                        item.binding.discovery.definition.contract
+                        or item.binding.discovery.service_type,
+                        _APPLICATION_SERVICE_COMPONENT,
+                    ),
+                )
+                for item in bound
+            )
+        )
         provider = Provider()
         provider.provide(lambda: self.catalog, provides=ApplicationServiceCatalog, scope=Scope.APP)
         provider.provide(_ApplicationServiceDispatcher, scope=Scope.REQUEST)

{python_ddd_framework-0.4.0 → python_ddd_framework-0.6.0}/src/python_ddd_framework/authorization/module.py

@@ -2,8 +2,8 @@
 
 from dishka import Provider, Scope
 
-from ..application_services.invocation import _InvocationRuntime
 from ..invocation.module import InvocationModule
+from ..invocation.runtime import _InvocationRuntime
 from ..lifecycle import ConfigureContext
 from ..modularity import AppModule
 from ..services.composition import (