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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-ddd-framework
-Version: 0.4.0
+Version: 0.5.1
 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.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.
 
 ### 1. Install the CLI and create a project
 
@@ -368,6 +368,14 @@ 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.
 
+#### 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.

{python_ddd_framework-0.4.0 → python_ddd_framework-0.5.1}/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.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.
 
 ### 1. Install the CLI and create a project
 
@@ -324,6 +324,14 @@ 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.
 
+#### 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.

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

@@ -1,6 +1,6 @@
 [project]
 name = "python-ddd-framework"
-version = "0.4.0"
+version = "0.5.1"
 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.5.1}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "python-ddd-framework"
-version = "0.4.0"
+version = "0.5.1"
 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.5.1}/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.5.1}/src/python_ddd_framework/application_services/invocation.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import asyncio
 import logging
+import threading
 from collections.abc import AsyncIterator, Awaitable, Callable, Iterator
 from contextlib import asynccontextmanager, contextmanager
 from contextvars import ContextVar, Token
@@ -70,20 +71,31 @@ class _InvocationReservation:
     executing: bool = False
 
 
+@dataclass(eq=False, frozen=True, slots=True)
+class _StoppingPermission:
+    """单 Application、服务 owner 与单次收尾钩子的准入身份，不携带业务 scope。"""
+
+    runtime: _InvocationRuntime
+    owner: type[object]
+
+
 class _InvocationRuntime:
     """每个 Application 独占 admission 与 ContextVar，禁止进程级 current app。"""
 
     __slots__ = (
         "_active",
+        "_admission_lock",
         "_ambient",
         "_application_id",
         "_authenticating",
         "_call_scope",
         "_caller",
-        "_condition",
+        "_changed",
         "_http_method",
         "_is_accepting",
         "_lease",
+        "_loop",
+        "_permissions",
         "_reservations",
         "_state_getter",
         "tracer",
@@ -116,7 +128,10 @@ class _InvocationRuntime:
             f"python_ddd_framework_invocation_lease_{application_id}",
             default=None,
         )
-        self._condition = asyncio.Condition()
+        self._admission_lock = threading.RLock()
+        self._changed = asyncio.Event()
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._permissions: set[_StoppingPermission] = set()
         self._is_accepting = False
         self._active = 0
         self._reservations: set[_InvocationReservation] = set()
@@ -166,6 +181,7 @@ class _InvocationRuntime:
         return self._application_id
 
     def start_accepting(self) -> None:
+        self._loop = asyncio.get_running_loop()
         self._is_accepting = True
 
     def runtime_participant(self) -> RuntimeParticipant:
@@ -173,27 +189,67 @@ class _InvocationRuntime:
             self.start_accepting()
 
         async def stop(reason: ShutdownReason) -> tuple[BaseException, ...]:
-            self._is_accepting = False
+            self.close_admission()
             return ()
 
-        # 未 start 的 COMPOSED HTTP 也可持有许可；所有消费者停止后、容器关闭前统一排空。
-        return RuntimeParticipant(start=start, stop=stop, drain=self.stop_accepting_and_wait)
+        return RuntimeParticipant(
+            start=start,
+            stop=stop,
+            quiesce=self.quiesce,
+            close_admission=self.close_admission,
+            drain=self.stop_accepting_and_wait,
+        )
 
-    async def stop_accepting_and_wait(self) -> None:
-        async with self._condition:
+    def quiesce(self) -> None:
+        with self._admission_lock:
             self._is_accepting = False
-            await self._condition.wait_for(lambda: self._active == 0)
 
-    def reserve(self) -> _InvocationReservation:
-        # 与 loop 上的接受/关闭无 await 地线性化；等待执行不打开 REQUEST/ACTION。
-        self.require_accepting_work()
-        reservation = _InvocationReservation(self)
-        self._reservations.add(reservation)
-        self._active += 1
-        return reservation
+    def close_admission(self) -> None:
+        with self._admission_lock:
+            self._is_accepting = False
+            self._permissions.clear()
+
+    def grant_stopping(self, owner: type[object]) -> _StoppingPermission:
+        with self._admission_lock:
+            if self._state_getter() not in (
+                ApplicationState.STOPPING,
+                ApplicationState.ROLLING_BACK,
+            ):
+                raise ApplicationInvocationRejectedError(reason="Not in the stopping phase")
+            permission = _StoppingPermission(self, owner)
+            self._permissions.add(permission)
+            return permission
+
+    def revoke_stopping(self, permission: _StoppingPermission) -> None:
+        with self._admission_lock:
+            self._permissions.discard(permission)
+
+    def require_stopping(self, permission: _StoppingPermission) -> None:
+        with self._admission_lock:
+            if permission.runtime is not self or permission not in self._permissions:
+                raise ApplicationInvocationRejectedError(reason="Invalid stopping permission")
+
+    async def stop_accepting_and_wait(self) -> None:
+        self.close_admission()
+        while True:
+            self._changed.clear()
+            with self._admission_lock:
+                if self._active == 0 and not self._reservations:
+                    return
+            await self._changed.wait()
+
+    def reserve(self, permission: _StoppingPermission | None = None) -> _InvocationReservation:
+        # SDK thread 与权限撤销在同一锁下线性化；已接受许可独立于钩子权限的寿命。
+        with self._admission_lock:
+            if permission is None:
+                self.require_accepting_work()
+            else:
+                self.require_stopping(permission)
+            reservation = _InvocationReservation(self)
+            self._reservations.add(reservation)
+            return reservation
 
     def require_accepting_work(self) -> None:
-        _current_task()
         if not self._is_accepting or self._state_getter() not in (
             ApplicationState.STARTING,
             ApplicationState.RUNNING,
@@ -201,13 +257,20 @@ class _InvocationRuntime:
             raise ApplicationInvocationRejectedError(reason="Application is not accepting work")
 
     async def discard(self, reservation: _InvocationReservation) -> None:
-        if reservation.runtime is not self or reservation not in self._reservations:
-            raise ApplicationInvocationRejectedError(reason="Invalid or released reservation")
-        async with self._condition:
+        self.release_reservation(reservation)
+
+    def release_reservation(self, reservation: _InvocationReservation) -> None:
+        with self._admission_lock:
+            if reservation.runtime is not self or reservation not in self._reservations:
+                raise ApplicationInvocationRejectedError(reason="Invalid or released reservation")
             self._reservations.remove(reservation)
-            self._active -= 1
-            if self._active == 0:
-                self._condition.notify_all()
+        if self._loop is not None and not self._loop.is_closed():
+            try:
+                self._loop.call_soon_threadsafe(self._changed.set)
+            except RuntimeError:
+                # 外部 submit 可能在 loop 关闭竞争中退回许可；此时已无 loop 排空等待者。
+                if not self._loop.is_closed():
+                    raise
 
     @asynccontextmanager
     async def reserved_lease(self, reservation: _InvocationReservation) -> AsyncIterator[None]:
@@ -246,7 +309,7 @@ class _InvocationRuntime:
             yield
             return
 
-        async with self._condition:
+        with self._admission_lock:
             state = self._state_getter()
             # HostedService.start 可调用业务入口，但全部后台启动成功前 readiness 仍为 false。
             allows_invocation = self._is_accepting and state in (
@@ -266,11 +329,11 @@ class _InvocationRuntime:
             yield
         finally:
             self._lease.reset(token)
-            async with self._condition:
+            with self._admission_lock:
                 assert self._active > 0
                 self._active -= 1
                 if self._active == 0:
-                    self._condition.notify_all()
+                    self._changed.set()
 
     def current(self) -> _InvocationState | None:
         return self._ambient.get()

{python_ddd_framework-0.4.0 → python_ddd_framework-0.5.1}/src/python_ddd_framework/background_execution/local.py

@@ -30,12 +30,19 @@ class _LocalTask:
         self.operation: asyncio.Task[None] | None = None
         self._failed = failed
         self._monitor: asyncio.Task[None] | None = None
+        self._quiescing = False
+        self._claiming_stopped = False
 
     async def start(self) -> None:
+        self._claiming_stopped = False
         self.state = BackgroundTaskState.STARTING
         if self.execution is None:
             raise RuntimeError("Task execution provider is unavailable")
         await self.execution.start()
+        if self._quiescing:
+            # start 可能与关闭重叠；完成后再次请求停止，不能重新打开领取。
+            self._claiming_stopped = False
+            self._stop_claiming()
         self.state = BackgroundTaskState.RUNNING
         if self.execution.wait_for_failure is not None:
             self._monitor = asyncio.create_task(
@@ -82,6 +89,9 @@ class _LocalTask:
     async def _operate(self, start: bool) -> None:
         try:
             if start:
+                if self._quiescing:
+                    self.state = BackgroundTaskState.STOPPED
+                    return
                 await self.start()
             else:
                 await self._drain()
@@ -91,6 +101,15 @@ class _LocalTask:
             self.state = BackgroundTaskState.FAILED
             # 失败转为 Application-owned 状态供查询；task 不留下未观察异常。
 
+    def quiesce(self) -> None:
+        self._quiescing = True
+        self._stop_claiming()
+
+    def _stop_claiming(self) -> None:
+        if self.execution is not None and not self._claiming_stopped:
+            self._claiming_stopped = True
+            self.execution.stop_claiming()
+
     async def shutdown(self) -> None:
         if self.operation is not None:
             await self.operation
@@ -112,7 +131,7 @@ class _LocalTask:
         execution = self.execution
         if execution is None:
             return
-        execution.stop_claiming()
+        self._stop_claiming()
         draining = asyncio.ensure_future(execution.wait())
         _, pending = await asyncio.wait((draining,), timeout=self.deadline)
         if pending:

{python_ddd_framework-0.4.0 → python_ddd_framework-0.5.1}/src/python_ddd_framework/background_execution/processes.py

@@ -60,6 +60,7 @@ class _ProcessSlot:
         self._exited = asyncio.Event()
         self._exited.set()
         self._stopping = False
+        self._shutdown_request: asyncio.Task[None] | None = None
         self._restart_count = 0
         self._wanted: set[str] = set()
         self._serial = 0
@@ -307,14 +308,23 @@ class _ProcessSlot:
                 if not self._stopping and self._wanted and self._process is None:
                     self._spawn()
 
-    async def shutdown(self) -> None:
+    def quiesce(self) -> None:
         self._stopping = True
         self._set_enabled_state(BackgroundTaskState.STOPPING)
+        if self._shutdown_request is None:
+            self._shutdown_request = asyncio.create_task(self._request_shutdown())
+
+    async def _request_shutdown(self) -> None:
         if self._process is not None and self._process.is_alive():
             try:
                 await self._send((_Message.SHUTDOWN,))
             except (EOFError, OSError):
                 pass
+
+    async def shutdown(self) -> None:
+        self.quiesce()
+        assert self._shutdown_request is not None
+        await self._shutdown_request
         if self._monitor is not None:
             await self._monitor
         if self._operations:

{python_ddd_framework-0.4.0 → python_ddd_framework-0.5.1}/src/python_ddd_framework/background_workers/runtime.py

@@ -46,7 +46,6 @@ class _BackgroundCoordinator:
                 raise _BackgroundExecutionStartFailure(original_error=error) from error
 
         async def stop(reason: ShutdownReason) -> tuple[BaseException, ...]:
-            await self.stop()
             return ()
 
         async def wait() -> ApplicationRuntimeError:
@@ -62,6 +61,8 @@ class _BackgroundCoordinator:
             prepare=prepare,
             start=start,
             stop=stop,
+            quiesce=self.quiesce,
+            drain=self.stop,
             failure=lambda: wait() if self.has_runtime_failure_source else None,
         )
 
@@ -242,6 +243,14 @@ class _BackgroundCoordinator:
             return slot.request(key, start)
         return self._tasks[key].request(start)
 
+    def quiesce(self) -> None:
+        self._started = False
+        for key, task in self._tasks.items():
+            if key in self._local:
+                task.quiesce()
+        for slot in self._slots.values():
+            slot.quiesce()
+
     async def stop(self) -> None:
         # 即使启动前的预占或 Module 初始化失败，也必须释放已取得的位置。
         operations = [task.shutdown() for key, task in self._tasks.items() if key in self._local]

{python_ddd_framework-0.4.0 → python_ddd_framework-0.5.1}/src/python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/README.md

@@ -23,7 +23,8 @@ This module owns the generated order example. Adapt its business rules from conf
 
 - Query, management, and approval use separate `{{ cookiecutter.class_prefix }}QueryApplicationService`, `{{ cookiecutter.class_prefix }}ManagementApplicationService`, and `{{ cookiecutter.class_prefix }}ApprovalApplicationService` contracts. The exposure decorator contributes the ContractsModule dependency; overrides retain the sample's deliberate paths and operation IDs. Other conventional methods are automatic, with plain GET Pydantic DTOs bound as query parameters unless explicitly declared otherwise. Reporting uses `OrderReportingService` internally without end-user permissions or HTTP exposure.
 - The aggregate owns pending-to-approved transitions. The domain service reads the approval setting; the caller owns version checks, transaction, and save. Repository writes collect events; AFTER_COMMIT removes the cache before online notification. Notification failure cannot undo a committed write.
-- The approval Job participates in transactional enqueue and ignores missing/already-approved orders. The statistics schedule refers to its Job type and typed payload; the Job definition owns persisted name/version/schema. Generated Workers are code-disabled; HostedService and periodic schedule require explicit Module registration as described in the project development guide. The hosted owner waits for its thread to exit. Settings refresh and timing interception reuse framework extensions.
+- The approval Job participates in transactional enqueue and ignores missing/already-approved orders. The statistics schedule refers to its Job type and typed payload; the Job definition owns persisted name/version/schema. Generated Workers are code-disabled; HostedService and periodic schedule require explicit Module registration as described in the project development guide. Settings refresh and timing interception reuse framework extensions.
+- The hosted example uses `stopping` for an independent business call and an SDK thread callback with the temporary context, then `stop` joins the actual thread after accepted work drains. Startup contexts stay closed during shutdown. To keep message input during this phase, declare this service in the channel's `stopping_owners`, depend on its Module owner, and pass `stopping=context`; no channel opts in by default.
 - File upload/download/stream and `/ws/{{ cookiecutter.module_name }}` call public contracts. Typed messages in [order_messages](domain_shared/messages/order_messages.py) own their versioned names and payload schemas; handlers and the socket explicitly map business values. Sending reports local queue acceptance, with no offline replay, cross-process backplane or client acknowledgment.
 
 Startup [Options](application/options/order_options.py) bind to the `{{ cookiecutter.module_name }}` YAML section; `allow_background_approval` defaults to true. Runtime approval settings and seed contributors belong to Domain. Its Module declares `SettingsModule` and `DataSeedingModule`; contributors are independent DI services, not ApplicationServices. The Domain [OrderApprovalService](domain/services/order_approval_service.py) opts into `ValidationEnabled` through the transitive InvocationModule dependency, retains its transient lifetime, and leaves saving and transaction completion to its caller. Capability dependencies and typed declarations are owned by each Module, while Host selects providers. Change declarations at their owners rather than copying names into another registry.

{python_ddd_framework-0.4.0 → python_ddd_framework-0.5.1}/src/python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application/hosted_services/order_integration_service.py.jinja

@@ -4,10 +4,6 @@ import asyncio
 import logging
 from threading import Event, Thread
 
-from modules.{{ cookiecutter.module_name }}.application_contracts.integration_services.order_reporting_service import (
-    OrderReportingService,
-)
-
 from python_ddd_framework import (
     HostedService,
     HostedServiceContext,
@@ -15,6 +11,10 @@ from python_ddd_framework import (
     ShutdownReason,
 )
 
+from modules.{{ cookiecutter.module_name }}.application_contracts.integration_services.order_reporting_service import (
+    OrderReportingService,
+)
+
 
 async def observe_integration(reporting: OrderReportingService) -> None:
     count = await reporting.get_count()
@@ -24,6 +24,10 @@ async def observe_integration(reporting: OrderReportingService) -> None:
 class OrderIntegrationService(HostedService):
     def __init__(self) -> None:
         self._stop = Event()
+        self._prepare = Event()
+        self._callback_done = Event()
+        self._stopping_context: HostedServiceContext | None = None
+        self._callback_error: BaseException | None = None
         self._thread: Thread | None = None
 
     async def start(self, context: HostedServiceContext) -> None:
@@ -34,13 +38,33 @@ class OrderIntegrationService(HostedService):
     def _receive(self, context: HostedServiceContext) -> None:
         # submit_call 只能来自外部线程；Future.result 等待同一正式 invocation 完成。
         try:
-            context.submit_call(observe_integration).result()
-        except HostedServiceInvocationRejectedError:
-            return  # Application 关闭已撤销调用许可。
+            try:
+                context.submit_call(observe_integration).result()
+            except HostedServiceInvocationRejectedError:
+                pass  # 普通准入可能已经关闭；收尾只使用 stopping 新提供的 context。
+            self._prepare.wait()
+            stopping = self._stopping_context
+            if stopping is not None:
+                stopping.submit_call(observe_integration).result()
+        except BaseException as error:  # noqa: BLE001 -- 线程故障转交 stopping 重新抛出。
+            self._callback_error = error
+        finally:
+            self._callback_done.set()
         self._stop.wait()
 
+    async def stopping(self, context: HostedServiceContext, reason: ShutdownReason) -> None:
+        # 独立业务调用完成后再等 SDK 回调，不跨线程传 scope，也不跨等待持有事务。
+        await context.call(observe_integration)
+        self._stopping_context = context
+        self._prepare.set()
+        await asyncio.to_thread(self._callback_done.wait)
+        if self._callback_error is not None:
+            raise RuntimeError("External integration callback failed") from self._callback_error
+
     async def stop(self, reason: ShutdownReason) -> None:
+        # start 部分失败时 stopping 不会执行；仍须唤醒并等待实际线程退出。
         self._stop.set()
+        self._prepare.set()
         if self._thread is not None:
             await asyncio.to_thread(self._thread.join)
             self._thread = None

{python_ddd_framework-0.4.0 → python_ddd_framework-0.5.1}/src/python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/AGENTS.md

@@ -41,6 +41,13 @@ Business modules own message values and coalescing identities. Only replaceable
 coalesce. Acceptance, processing, commit and external acknowledgement are separate facts.
 Use the framework channel and hosted bridge; preserve capacity and actual cleanup guarantees.
 
+For SDK shutdown, initiate business cleanup in `HostedService.stopping(context, reason)` and
+release resources in `stop(reason)`. Pass the separate stopping context only to this phase's
+callbacks; startup contexts never gain shutdown permissions. Channels opt in with declared
+`stopping_owners` and `send/submit(..., stopping=context)`. Keep the channel Module dependent on
+the service owner, and drain accepted work before releasing resources. See the hosted-service
+and message examples in the project development guide.
+
 ## Verify and maintain
 
 - Preserve unrelated changes. Do not edit the installed framework, generated dependency files by hand, or another repository to make an application change pass.

{python_ddd_framework-0.4.0 → python_ddd_framework-0.5.1}/src/python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/docs/architecture.md

@@ -102,8 +102,9 @@ Module initialization precedes selected hosted services and background execution
 - Durable jobs use typed, versioned payloads and the PostgreSQL provider. Transactional enqueue must use the same configured connection as the surrounding unit of work. External side effects remain the job's idempotency responsibility.
 - Periodic workers are explicitly registered. Generated example workers are disabled in their class declarations; configuration cannot enable a code-disabled worker.
 - Execution modes are `host`, `shared`, and `exclusive`. Spawned processes compose their own Application; they do not inherit a live Session or container.
-- A `HostedService` owns long-lived SDKs or threads, their failures, recovery, and actual shutdown. It is opt-in; background-process instances need explicit selection. External threads use its supported submission methods.
+- A `HostedService` owns long-lived SDKs or threads, their failures, recovery, and actual shutdown. It is opt-in; background-process instances need explicit selection. Shutdown has global barriers: close ordinary admission, await `stopping`, close remaining admission, drain accepted work, then release resources in `stop` before Module/container cleanup. Only successfully started services prepare; all touched services clean up. External callbacks use the separate, temporary stopping context, never an upgraded startup context.
 - Redis business locks are leases. Preserve cancellation and cleanup when ownership is lost; a lease is not a transaction, fencing guarantee, or exactly-once guarantee.
+- In-process channels preserve SDK input during stopping only for declared `stopping_owners` and a current hook context passed to `send/submit`. The channel Module depends on the service owner. Admission permissions are Application-local and temporary; accepted work retains its reservation until execution or a reported non-execution outcome, with unchanged capacity and per-message scopes.
 - WebSocket delivery targets currently connected clients. The generated sample has no cross-process backplane, offline replay, or delivery acknowledgment. HTTP streaming must release business transactions before network transmission and clean up producers on disconnect.
 - Liveness and readiness report lifecycle state, not continuous infrastructure availability. Trace export is disabled in the generated development configuration until explicitly configured.
 

{python_ddd_framework-0.4.0 → python_ddd_framework-0.5.1}/src/python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/docs/development.md

@@ -207,7 +207,9 @@ Background execution Options use catalog names to select `host`, `shared`, or `e
 
 Use the existing `DistributedLock` provider for explicit business leases. `locks.acquire(key, wait_timeout=timedelta(0))` tries without waiting; omit the argument or pass `None` for configured waiting, or pass a positive timedelta for this acquisition only. If acquisition returns false, skip or report the operation as appropriate. Preserve cancellation and cleanup on lease loss. Use database concurrency and idempotency for their separate guarantees.
 
-A `HostedService` manages a long-lived SDK or thread through async `start`/`stop`, including actual thread termination. Register it with `hosted_services = HostedServices((ServiceType,))`; the generated integration example is not registered by default. External threads submit through the hosted-service context, and the component owns runtime failures and recovery.
+A `HostedService` starts its SDK/thread in `start(context)`, initiates business cleanup and waits for callbacks in optional `stopping(context, reason)`, then releases resources and joins threads in `stop(reason)`. Register it with `hosted_services = HostedServices((ServiceType,))`; the generated integration example is not registered by default. It demonstrates an independent `context.call` and a thread callback using `context.submit_call(...).result()`. Each call creates its own scope; never pass a Session or scope to the thread or hold a transaction while waiting for the SDK.
+
+The stopping context is separate from the startup context, which stays closed to new work. Its permission ends when the hook returns, fails, or receives a timeout cancellation request; accepted work still drains before resource stop. Only successfully started services receive `stopping`, while every touched service must tolerate `stop` after partial startup. Each hook uses `hosted_service.shutdown_timeout`, requests cancellation on expiry, and waits for actual cleanup; it is not a total shutdown deadline. HTTP/WebSocket use native transport shutdown.
 
 ## HTTP, files, and real-time communication
 
@@ -270,6 +272,14 @@ UoW, scope or concurrently mutable payloads between tasks/threads. Host configur
 resource exit and reports timeout. Restart requires a new Application. Commands, results and
 events requiring individual processing must not declare a coalescing key.
 
+To accept SDK messages during a hosted service's stopping hook, declare
+`MessageChannelDefinition(T, Handler, stopping_owners=(ServiceType,))` and make the channel
+Module depend on the service's owner Module. Send with `await channel.send(value, stopping=context)`
+or `channel.submit(value, stopping=context)` using that hook's current context. The default empty
+tuple keeps input closed. Ordinary, expired, undeclared-owner and foreign-Application contexts
+are rejected. Already accepted messages still drain before resource stop; the permission changes
+neither capacity nor handler validation, authorization, scope/UoW or receipt semantics.
+
 ## Verification
 
 Run native uv/test/build commands from `backend/`. Installed `pddd` commands locate the backend from the application root or any descendant, including nested foreign Python projects. Read fixtures first: Host tests use disposable PostgreSQL and Redis containers, so Docker must be available.