python-ddd-framework 0.5.1__tar.gz → 0.7.0__tar.gz

{python_ddd_framework-0.5.1 → python_ddd_framework-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-ddd-framework
-Version: 0.5.1
+Version: 0.7.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.5:** This version introduces staged lifecycle shutdown, a temporary `HostedService.stopping` context, and explicit message-channel admission during stopping. Existing applications must apply the lifecycle migration instructions below; applications upgrading from before 0.4 must also apply the earlier capability and consumer-layout migrations. 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
 
@@ -127,28 +127,33 @@ pddd add module conversions --template basic
 
 `dev-init` starts or reuses local PostgreSQL and Redis using `backend/app.development.yaml`. It preserves existing data; database migration and seeding are separate steps.
 
-`add module orders` generates an order-management example and registers it with the Host. The example includes an aggregate, service contracts, application services, persistence, HTTP endpoints, module tests, and a module README describing its actual behavior and boundaries.
+`add module orders` generates a DDD skeleton named `orders` and registers its Application, SQLAlchemy, and HttpApi Modules with the Host. It retains all responsibility directories, package markers, lifecycle hooks, ORM Base, model discovery, migration registration, and a module README. It creates no business entities, services, tables, endpoints, tasks, or test cases. Add them from confirmed requirements. The former order implementation is available as a separate [order-management example](examples/order_management/README.md), outside the runtime wheel.
 
 `ddd` is the default six-layer template. `basic` generates only a Module, a synchronous Protocol service, its transient implementation, and an English README. It has no database/Redis requirement or implicit HTTP/interception. Both templates support `--dry-run` and refuse existing targets.
 
 ### 3. Initialize the database
 
-Apply the provider migrations selected by the generated Host, then generate the business module's first migration:
+Apply the provider migrations selected by the generated Host:
 
 ```sh
 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
+```
+
+An empty DDD skeleton retains model and migration registration but has no business tables or revisions. Add actual models before generating a business revision; migration commands still use the configured database. For a module named `orders`:
+
+```sh
 pddd db revision --module orders
 ```
 
-Review the generated revision in `backend/src/modules/orders/sqlalchemy/migrations/` before applying it. Then upgrade and seed:
+Review the generated revision in `backend/src/modules/orders/sqlalchemy/migrations/` before applying it. Run seed only after declaring the intended contributors:
 
 ```sh
 pddd db upgrade --module orders
 pddd db status --module orders
-pddd db seed --module identity
 pddd db seed --module orders
 ```
 
@@ -162,7 +167,7 @@ pddd dev
 
 Open **http://127.0.0.1:8000/docs**. Use the generated `identity.seed_admin_username` and `identity.seed_admin_password` in `backend/app.development.yaml` to call `/api/auth/login`, then enter the returned access token in Swagger's **Authorize** dialog.
 
-With the `orders` module installed, you can create and query orders at `/api/orders`, approve an order at `/api/orders/{id}/approve`, and enqueue approval at `/api/orders/{id}/queue-approval`. Swagger shows the request schemas and all available operations. The example also includes file transfer and an authenticated WebSocket endpoint at `/ws/orders`.
+The empty `orders` skeleton contributes no business routes. The independent [order-management example](examples/order_management/README.md) supplies `/api/orders`, approval and queued approval, file transfer, and an authenticated WebSocket at `/ws/orders`; use its initializer when you want to explore those capabilities.
 
 The default business API prefix is `/api`. Liveness and readiness are exposed at `/health/live` and `/health/ready`; readiness describes application lifecycle state, not continuous database or Redis health.
 
@@ -194,6 +199,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.
@@ -267,6 +300,22 @@ The image uses `python -m host.main` without development reload. Runtime install
 
 <a id="版本与升级"></a>
 
+### DDD skeleton generation (0.7)
+
+New `ddd` modules contain the full responsibility directories and necessary composition, with no preset business code or tests. `basic` is unchanged. This affects subsequent generation only: upgrades do not delete or rewrite existing consumers' order code. Keep existing business contracts and data under their application owners. The former order implementation and its existing domain test now live in [the independent example](examples/order_management/README.md); its initializer uses the official CLI, requires a new destination, and is not bundled in the runtime wheel. No CLI parameter or dependency has been added.
+
+<a id="streaming-and-access-migration-07-unreleased"></a>
+
+## Streaming and access migration (0.7)
+
+- Move `fastapi_realtime.authentication_refresh_seconds` to `fastapi_access.authentication_refresh_seconds`. The shared `FastApiAccessOptions` applies to managed HTTP streams and WebSocket connections; its default is 60 seconds and minimum is 1. The old realtime field is rejected.
+- HTTP endpoints on `HttpRouter` can directly yield synchronous or asynchronous values using native FastAPI SSE, JSONL, or `StreamingResponse`. Keep checks required before the response starts in preparation dependencies or Filters. Authorization precedes binding; function dependencies, commit, and business resource cleanup finish before sending. The framework does not read the first item during preparation. Application services keep their existing return contract and may return a native streaming Response.
+- Register subscriptions acquired during preparation with a native request-scoped yield dependency. An unstarted generator's `finally` cannot release those subscriptions. Database work in preparation or during iteration must use an independent short service call or UoW and finish before yielding data. Generator cleanup that awaits must shield its own `finally`, without holding a cancellation scope across `yield`.
+- Streams with authorization declarations automatically recheck identity and endpoint permissions, including while idle or blocked on a slow client. Anonymous declarations retain their meaning. WebSocket `invoke` continues to authorize each service call separately. Failed checks terminate the transport; after `http.response.start`, no replacement JSON response is sent.
+- `run_host(..., timeout_graceful_shutdown=10)` passes a non-negative integer to Uvicorn. When that period expires, cancellation is requested and framework drain still waits for actual resource release. Direct Uvicorn consumers must configure its native timeout themselves. A synchronous generator's running `next()` must eventually return; a timeout does not abandon its thread.
+
+Runnable examples: [HTTP generators](docs/development.md#http-生成器与持续访问). Verification and limitations: [0.7.0 status](docs/status.md#070-通用生成器与持续访问未发布).
+
 ## Capability module migration (0.4)
 
 Capability composition now uses the same `AppModule` model as customer modules. Existing applications must migrate their declarations together; there is no compatibility path.
@@ -290,6 +339,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 +395,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 +453,12 @@ 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.
@@ -382,7 +473,7 @@ Channels that must accept these callbacks declare `stopping_owners=(ServiceType,
 
 The developer-kit dependency constrains `binaryornot` to `0.5.x`, because `0.6.0` can classify bundled templates containing Chinese comments as binary and skip rendering them. Re-resolve the developer-kit environment when installing 0.4.0. Updating the dependency does not replace existing generated application code.
 
-The new `DomainService` marker uses existing constructor injection and transient REQUEST lifetime. It does not create transactions or expose HTTP endpoints. Newly generated modules place approval policy in `domain/services/order_approval_service.py`; existing projects can adopt that example explicitly after upgrading. The application checks existence and the submitted version before the domain policy; a stale or missing order therefore takes precedence over a disabled approval setting when both inputs are invalid. Domain rules, schema, and installation files are not automatically rewritten.
+The new `DomainService` marker uses existing constructor injection and transient REQUEST lifetime. It does not create transactions or expose HTTP endpoints. The independent order example places approval policy in `domain/services/order_approval_service.py`; existing projects can adopt it explicitly after upgrading. The example application checks existence and the submitted version before the domain policy; a stale or missing order therefore takes precedence over a disabled approval setting when both inputs are invalid. Domain rules, schema, and installation files are not automatically rewritten.
 
 <a id="框架更名迁移未发布"></a>
 
@@ -455,7 +546,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>
 
@@ -471,7 +562,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. They require an owner/layer/directory/API check before implementation and a review of the seven design principles, DDD boundaries, and actual verification before delivery. The development guide provides CLI entry points, installed-artifact/source comparison, capability recipes, and a complete native HTTP generator example; architecture owns streaming/access boundaries, and the generated README owns configuration migration and shutdown operations. These instructions do not imply an automated architecture gate. Each DDD module README records the empty skeleton and guides the first authorized use case; the independent order example owns its own business documentation and acceptance source. The application maintains these documents after generation; upgrades do not overwrite them. Existing applications can use their installed package's `developer_kit/templates` as a read-only reference while preserving application rules and decisions. A user-provided framework checkout is also read-only; matching version numbers alone do not prove it matches the consumed artifact.
 
 ## License
 

{python_ddd_framework-0.5.1 → python_ddd_framework-0.7.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.5:** This version introduces staged lifecycle shutdown, a temporary `HostedService.stopping` context, and explicit message-channel admission during stopping. Existing applications must apply the lifecycle migration instructions below; applications upgrading from before 0.4 must also apply the earlier capability and consumer-layout migrations. 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
 
@@ -83,28 +83,33 @@ pddd add module conversions --template basic
 
 `dev-init` starts or reuses local PostgreSQL and Redis using `backend/app.development.yaml`. It preserves existing data; database migration and seeding are separate steps.
 
-`add module orders` generates an order-management example and registers it with the Host. The example includes an aggregate, service contracts, application services, persistence, HTTP endpoints, module tests, and a module README describing its actual behavior and boundaries.
+`add module orders` generates a DDD skeleton named `orders` and registers its Application, SQLAlchemy, and HttpApi Modules with the Host. It retains all responsibility directories, package markers, lifecycle hooks, ORM Base, model discovery, migration registration, and a module README. It creates no business entities, services, tables, endpoints, tasks, or test cases. Add them from confirmed requirements. The former order implementation is available as a separate [order-management example](examples/order_management/README.md), outside the runtime wheel.
 
 `ddd` is the default six-layer template. `basic` generates only a Module, a synchronous Protocol service, its transient implementation, and an English README. It has no database/Redis requirement or implicit HTTP/interception. Both templates support `--dry-run` and refuse existing targets.
 
 ### 3. Initialize the database
 
-Apply the provider migrations selected by the generated Host, then generate the business module's first migration:
+Apply the provider migrations selected by the generated Host:
 
 ```sh
 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
+```
+
+An empty DDD skeleton retains model and migration registration but has no business tables or revisions. Add actual models before generating a business revision; migration commands still use the configured database. For a module named `orders`:
+
+```sh
 pddd db revision --module orders
 ```
 
-Review the generated revision in `backend/src/modules/orders/sqlalchemy/migrations/` before applying it. Then upgrade and seed:
+Review the generated revision in `backend/src/modules/orders/sqlalchemy/migrations/` before applying it. Run seed only after declaring the intended contributors:
 
 ```sh
 pddd db upgrade --module orders
 pddd db status --module orders
-pddd db seed --module identity
 pddd db seed --module orders
 ```
 
@@ -118,7 +123,7 @@ pddd dev
 
 Open **http://127.0.0.1:8000/docs**. Use the generated `identity.seed_admin_username` and `identity.seed_admin_password` in `backend/app.development.yaml` to call `/api/auth/login`, then enter the returned access token in Swagger's **Authorize** dialog.
 
-With the `orders` module installed, you can create and query orders at `/api/orders`, approve an order at `/api/orders/{id}/approve`, and enqueue approval at `/api/orders/{id}/queue-approval`. Swagger shows the request schemas and all available operations. The example also includes file transfer and an authenticated WebSocket endpoint at `/ws/orders`.
+The empty `orders` skeleton contributes no business routes. The independent [order-management example](examples/order_management/README.md) supplies `/api/orders`, approval and queued approval, file transfer, and an authenticated WebSocket at `/ws/orders`; use its initializer when you want to explore those capabilities.
 
 The default business API prefix is `/api`. Liveness and readiness are exposed at `/health/live` and `/health/ready`; readiness describes application lifecycle state, not continuous database or Redis health.
 
@@ -150,6 +155,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.
@@ -223,6 +256,22 @@ The image uses `python -m host.main` without development reload. Runtime install
 
 <a id="版本与升级"></a>
 
+### DDD skeleton generation (0.7)
+
+New `ddd` modules contain the full responsibility directories and necessary composition, with no preset business code or tests. `basic` is unchanged. This affects subsequent generation only: upgrades do not delete or rewrite existing consumers' order code. Keep existing business contracts and data under their application owners. The former order implementation and its existing domain test now live in [the independent example](examples/order_management/README.md); its initializer uses the official CLI, requires a new destination, and is not bundled in the runtime wheel. No CLI parameter or dependency has been added.
+
+<a id="streaming-and-access-migration-07-unreleased"></a>
+
+## Streaming and access migration (0.7)
+
+- Move `fastapi_realtime.authentication_refresh_seconds` to `fastapi_access.authentication_refresh_seconds`. The shared `FastApiAccessOptions` applies to managed HTTP streams and WebSocket connections; its default is 60 seconds and minimum is 1. The old realtime field is rejected.
+- HTTP endpoints on `HttpRouter` can directly yield synchronous or asynchronous values using native FastAPI SSE, JSONL, or `StreamingResponse`. Keep checks required before the response starts in preparation dependencies or Filters. Authorization precedes binding; function dependencies, commit, and business resource cleanup finish before sending. The framework does not read the first item during preparation. Application services keep their existing return contract and may return a native streaming Response.
+- Register subscriptions acquired during preparation with a native request-scoped yield dependency. An unstarted generator's `finally` cannot release those subscriptions. Database work in preparation or during iteration must use an independent short service call or UoW and finish before yielding data. Generator cleanup that awaits must shield its own `finally`, without holding a cancellation scope across `yield`.
+- Streams with authorization declarations automatically recheck identity and endpoint permissions, including while idle or blocked on a slow client. Anonymous declarations retain their meaning. WebSocket `invoke` continues to authorize each service call separately. Failed checks terminate the transport; after `http.response.start`, no replacement JSON response is sent.
+- `run_host(..., timeout_graceful_shutdown=10)` passes a non-negative integer to Uvicorn. When that period expires, cancellation is requested and framework drain still waits for actual resource release. Direct Uvicorn consumers must configure its native timeout themselves. A synchronous generator's running `next()` must eventually return; a timeout does not abandon its thread.
+
+Runnable examples: [HTTP generators](docs/development.md#http-生成器与持续访问). Verification and limitations: [0.7.0 status](docs/status.md#070-通用生成器与持续访问未发布).
+
 ## Capability module migration (0.4)
 
 Capability composition now uses the same `AppModule` model as customer modules. Existing applications must migrate their declarations together; there is no compatibility path.
@@ -246,6 +295,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 +351,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 +409,12 @@ 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.
@@ -338,7 +429,7 @@ Channels that must accept these callbacks declare `stopping_owners=(ServiceType,
 
 The developer-kit dependency constrains `binaryornot` to `0.5.x`, because `0.6.0` can classify bundled templates containing Chinese comments as binary and skip rendering them. Re-resolve the developer-kit environment when installing 0.4.0. Updating the dependency does not replace existing generated application code.
 
-The new `DomainService` marker uses existing constructor injection and transient REQUEST lifetime. It does not create transactions or expose HTTP endpoints. Newly generated modules place approval policy in `domain/services/order_approval_service.py`; existing projects can adopt that example explicitly after upgrading. The application checks existence and the submitted version before the domain policy; a stale or missing order therefore takes precedence over a disabled approval setting when both inputs are invalid. Domain rules, schema, and installation files are not automatically rewritten.
+The new `DomainService` marker uses existing constructor injection and transient REQUEST lifetime. It does not create transactions or expose HTTP endpoints. The independent order example places approval policy in `domain/services/order_approval_service.py`; existing projects can adopt it explicitly after upgrading. The example application checks existence and the submitted version before the domain policy; a stale or missing order therefore takes precedence over a disabled approval setting when both inputs are invalid. Domain rules, schema, and installation files are not automatically rewritten.
 
 <a id="框架更名迁移未发布"></a>
 
@@ -411,7 +502,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>
 
@@ -427,7 +518,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. They require an owner/layer/directory/API check before implementation and a review of the seven design principles, DDD boundaries, and actual verification before delivery. The development guide provides CLI entry points, installed-artifact/source comparison, capability recipes, and a complete native HTTP generator example; architecture owns streaming/access boundaries, and the generated README owns configuration migration and shutdown operations. These instructions do not imply an automated architecture gate. Each DDD module README records the empty skeleton and guides the first authorized use case; the independent order example owns its own business documentation and acceptance source. The application maintains these documents after generation; upgrades do not overwrite them. Existing applications can use their installed package's `developer_kit/templates` as a read-only reference while preserving application rules and decisions. A user-provided framework checkout is also read-only; matching version numbers alone do not prove it matches the consumed artifact.
 
 ## License
 

{python_ddd_framework-0.5.1 → python_ddd_framework-0.7.0}/pyproject.toml

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

{python_ddd_framework-0.5.1 → python_ddd_framework-0.7.0}/pyproject.toml.orig

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

{python_ddd_framework-0.5.1 → python_ddd_framework-0.7.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.5.1 → python_ddd_framework-0.7.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.7.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")