python-ddd-framework 0.6.0__py3-none-any.whl → 0.7.0__py3-none-any.whl

python_ddd_framework/fastapi/streaming.py

@@ -0,0 +1,95 @@
+"""生成器端点的原生 Depends 准备与发送交接；协议编码仍由 FastAPI 完成。"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import AsyncIterable, AsyncIterator, Callable, Iterable
+from functools import update_wrapper
+from typing import Annotated, Any
+
+from dishka.integrations.fastapi import inject
+from fastapi import Depends
+from starlette.concurrency import iterate_in_threadpool
+from starlette.responses import Response
+
+from ..unit_of_work import UnitOfWorkManager
+from .action import _HttpActionOwner
+from .transfer import _manage_source
+
+
+class _PreparedStream:
+    """保存准备阶段移交的源；原生 producer 取得发送许可后才允许读取正文。"""
+
+    def __init__(self, owner: _HttpActionOwner, result: object) -> None:
+        self._owner = owner
+        self._result = result
+        _manage_source(owner.request, result)
+
+    async def iterate(self) -> AsyncIterator[object]:
+        owner = self._owner
+        # SSE 在函数退出栈完成前启动原生 producer；不预读首项，也不携带准备期事务。
+        await owner.prepared.wait()
+        if isinstance(self._result, Response):
+            return
+        await owner.sending.wait()
+        manager = await owner.container.get(UnitOfWorkManager)
+        initial_user, correlation = owner.request.state.python_ddd_framework_identity
+        access = getattr(owner.request.state, "python_ddd_framework_access", None)
+        if isinstance(self._result, AsyncIterable):
+            iterator = aiter(self._result)
+        elif isinstance(self._result, Iterable):
+            iterator = iterate_in_threadpool(self._result)
+        else:
+            raise TypeError("a streaming action must produce an iterable or Response")
+        while True:
+            # ContextVar token 不跨 yield；每次读取单独取得可信发送许可，
+            # 避免原生包装器延迟 finalization 时在不同 task 恢复准备上下文。
+            with (
+                manager._detached_work(),
+                owner.runtime.detached_execution(owner.container),
+            ):
+                # SSE producer 的复验也可能执行短 UoW，必须先交接该 task 的调用许可。
+                with owner.runtime.trusted_http_task(
+                    owner.container, initial_user, correlation, owner.request.method
+                ):
+                    user = await access.check() if access is not None else initial_user
+                # 检查可能刷新身份；正文的短调用使用检查后的快照，不能沿用准备期身份。
+                with owner.runtime.trusted_http_task(
+                    owner.container, user, correlation, owner.request.method
+                ):
+                    try:
+                        item = await anext(iterator)
+                    except StopAsyncIteration:
+                        return
+            yield item
+
+
+def _stream_endpoint(
+    prepare: Callable[..., Any], signature: inspect.Signature
+) -> Callable[..., Any]:
+    """准备交给原生 Depends，外层仍暴露生成器供 FastAPI 选择编码与传输路径。"""
+    # Depends 必须看到真实 coroutine，不能沿 __wrapped__ 把准备函数误当 yield dependency。
+    del prepare.__wrapped__  # type: ignore[attr-defined]
+    prepare.__signature__ = inspect.signature(prepare).replace(  # type: ignore[attr-defined]
+        return_annotation=_PreparedStream
+    )
+    prepare.__annotations__["return"] = _PreparedStream
+    dependency = inject(prepare)
+
+    async def stream(_prepared: _PreparedStream) -> AsyncIterator[object]:
+        async for item in _prepared.iterate():
+            yield item
+
+    update_wrapper(stream, prepare)
+    delattr(stream, "__wrapped__")
+    parameter = inspect.Parameter(
+        "_prepared",
+        inspect.Parameter.KEYWORD_ONLY,
+        annotation=Annotated[_PreparedStream, Depends(dependency)],
+    )
+    stream.__signature__ = signature.replace(parameters=(parameter,))  # type: ignore[attr-defined]
+    stream.__annotations__ = {
+        "_prepared": parameter.annotation,
+        "return": signature.return_annotation,
+    }
+    return stream

python_ddd_framework/fastapi/transfer.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import asyncio
 import inspect
-from collections.abc import Awaitable, Callable
+from collections.abc import AsyncIterable, AsyncIterator, Awaitable, Callable, Iterable
 from contextlib import AsyncExitStack
 
 from anyio import CancelScope
@@ -12,9 +12,10 @@ from starlette.concurrency import iterate_in_threadpool, run_in_threadpool
 from starlette.datastructures import FormData, UploadFile
 from starlette.requests import ClientDisconnect, Request
 from starlette.responses import StreamingResponse
-from starlette.types import Send
+from starlette.types import Message, Send
 
 from ..invocation.runtime import _InvocationRuntime
+from .access import _AccessRefresh
 
 
 async def _close_form(form: FormData) -> None:
@@ -28,6 +29,7 @@ async def _close_form(form: FormData) -> None:
 
 def _manage_stream(request: Request, response: object) -> None:
     if not isinstance(response, StreamingResponse):
+        _manage_source(request, response)
         return
     if isinstance(getattr(response.stream_response, "__self__", None), _StreamLifetime):
         return
@@ -51,10 +53,84 @@ def _manage_stream(request: Request, response: object) -> None:
         response.body_iterator = iterator
         close = getattr(iterator, "aclose", None)
     lifetime = _StreamLifetime(request, response.stream_response, close)
+    if lifetime._access is not None:
+        response.body_iterator = lifetime.read(response.body_iterator)
     response.stream_response = lifetime.send  # type: ignore[method-assign]
     request.scope["fastapi_middleware_astack"].push_async_callback(lifetime.close)
 
 
+def _manage_source(request: Request, source: object) -> None:
+    if not isinstance(source, (AsyncIterable, Iterable)):
+        return
+    sources: dict[int, _SourceLifetime] | None = getattr(
+        request.state, "python_ddd_framework_stream_sources", None
+    )
+    if sources is None:
+        sources = {}
+        request.state.python_ddd_framework_stream_sources = sources
+    if id(source) in sources:
+        return
+    close = getattr(source, "aclose", None)
+    sync_close = getattr(source, "close", None)
+    if close is None and sync_close is None:
+        return
+    lifetime = _SourceLifetime(request, source, close, sync_close)
+    sources[id(source)] = lifetime
+    # 源在准备依赖执行后、原生 SSE task group 建立前登记：退出时先 join producer，
+    # 再关源，最后才释放先登记的订阅依赖。不能把源留到订阅退出后的 middleware 栈。
+    request.scope["fastapi_inner_astack"].push_async_callback(lifetime.close)
+
+
+class _SourceLifetime:
+    """在迭代退出后强持有唯一关闭任务，等待源清理真正完成。"""
+
+    def __init__(
+        self,
+        request: Request,
+        source: object,
+        close: Callable[[], Awaitable[None]] | None,
+        sync_close: Callable[[], None] | None,
+    ) -> None:
+        self._request = request
+        self.source = source
+        self._close = close
+        self._sync_close = sync_close
+        self._task: asyncio.Task[None] | None = None
+
+    async def _run(self) -> None:
+        container = self._request.state.dishka_container
+        runtime = await container.get(_InvocationRuntime)
+        user, correlation = self._request.state.python_ddd_framework_identity
+        with (
+            CancelScope(shield=True),
+            runtime.trusted_http_task(container, user, correlation, self._request.method),
+        ):
+            if self._close is not None:
+                await self._close()
+            elif self._sync_close is not None:
+                await run_in_threadpool(self._sync_close)
+
+    async def close(self) -> None:
+        if self._task is None:
+            self._task = asyncio.create_task(self._run())
+        # 重复取消只记下待传播的异常，不打断同一个清理任务或提前释放 REQUEST。
+        primary: asyncio.CancelledError | None = None
+        with CancelScope(shield=True):
+            while not self._task.done():
+                try:
+                    await asyncio.wait((self._task,))
+                except asyncio.CancelledError as error:
+                    primary = primary or error
+            try:
+                self._task.result()
+            except BaseException as error:
+                if primary is not None:
+                    raise error from primary
+                raise
+        if primary is not None:
+            raise primary
+
+
 class _StreamLifetime:
     """producer 串行拥有迭代与关闭；请求监督它结束后才允许 REQUEST/stop 退出。"""
 
@@ -67,6 +143,12 @@ class _StreamLifetime:
         self._request = request
         self._send = send
         self._close = close
+        self._access: _AccessRefresh | None = getattr(
+            request.state, "python_ddd_framework_access", None
+        )
+        self._ready: asyncio.Event | None = getattr(
+            request.state, "python_ddd_framework_stream_ready", None
+        )
 
     async def close(self) -> None:
         # 先取走回调，避免 producer finally 与请求退出栈重复关闭同一资源。
@@ -76,6 +158,24 @@ class _StreamLifetime:
             with CancelScope(shield=True):
                 await close()
 
+    async def read(
+        self, source: AsyncIterable[str | bytes | memoryview]
+    ) -> AsyncIterator[str | bytes | memoryview]:
+        assert self._access is not None
+        container = self._request.state.dishka_container
+        runtime = await container.get(_InvocationRuntime)
+        _, correlation = self._request.state.python_ddd_framework_identity
+        iterator = aiter(source)
+        while True:
+            user = await self._access.check()
+            # 原生 Response 的正文短调用也使用最新快照；DI 已注入的不可变值不原地修改。
+            with runtime.trusted_http_task(container, user, correlation, self._request.method):
+                try:
+                    item = await anext(iterator)
+                except StopAsyncIteration:
+                    return
+            yield item
+
     async def send(self, send: Send) -> None:
         # scope 可在 producer 启动前取消，但只能由 producer 自己进入/退出。
         cancel_scope = CancelScope()
@@ -111,6 +211,7 @@ class _StreamLifetime:
             raise
 
     async def _run(self, send: Send, cancel_scope: CancelScope) -> None:
+        """在所属 task 的可信许可内完成首检、发送和关闭，并等待后台复验退出。"""
         container = self._request.state.dishka_container
         runtime = await container.get(_InvocationRuntime)
         user, correlation = self._request.state.python_ddd_framework_identity
@@ -120,9 +221,43 @@ class _StreamLifetime:
             CancelScope(shield=True),
             runtime.trusted_http_task(container, user, correlation, self._request.method),
         ):
+            watchdog: asyncio.Task[None] | None = None
+
+            async def protected_send(message: Message) -> None:
+                if self._access is not None:
+                    await self._access.check()
+                await send(message)
+                if message["type"] == "http.response.start" and self._ready is not None:
+                    self._ready.set()
+
             try:
                 with cancel_scope:
-                    await self._send(send)
+                    # ASGI <2.4 的 Starlette 会在子 task 调用 send；首次复验也必须在
+                    # 当前受监督入口取得许可后执行，且仍先于实际 response.start。
+                    if self._access is not None:
+                        await self._access.check(force=True)
+                        watchdog = asyncio.create_task(self._watch_access(cancel_scope))
+                    await self._send(protected_send)
+                if self._access is not None and self._access.failure is not None:
+                    raise self._access.failure
             finally:
+                if watchdog is not None:
+                    watchdog.cancel()
+                    await asyncio.gather(watchdog, return_exceptions=True)
                 # 发送/next 已退出才能串行关闭；生成器内部 finally 的 await 由其自己 shield。
                 await self.close()
+
+    async def _watch_access(self, cancel_scope: CancelScope) -> None:
+        assert self._access is not None
+        container = self._request.state.dishka_container
+        runtime = await container.get(_InvocationRuntime)
+        user, correlation = self._request.state.python_ddd_framework_identity
+        try:
+            # create_task 只复制上下文；复验的短调用仍须由传输 owner 明确交接许可。
+            with runtime.trusted_http_task(container, user, correlation, self._request.method):
+                while True:
+                    await asyncio.sleep(self._access.delay)
+                    await self._access.check()
+        except Exception as error:
+            self._request.state.python_ddd_framework_transfer_failure = error
+            cancel_scope.cancel()

python_ddd_framework/invocation/dispatcher.py

@@ -19,13 +19,8 @@ from ..application_services.errors import (
 )
 from ..auditing import ApplicationServiceAuditRecord, AuditSink
 from ..auditing.control import AuditingControl, AuditingOptions
-from ..authorization import AuthorizationOptions, PermissionChecker
+from ..authorization.checking import _check_authorization
 from ..authorization.contracts import _AuthorizationRequirement
-from ..authorization.errors import (
-    PermissionCheckerUnavailableError,
-    PermissionDeniedError,
-    UnauthenticatedError,
-)
 from ..invocation.arguments import _validate_arguments
 from ..invocation.execution import _InterceptorPipeline
 from ..invocation.interceptors import InterceptionStage
@@ -271,21 +266,4 @@ class _MethodDispatcher:
             )
 
     async def _authorize(self, requirement: _AuthorizationRequirement) -> None:
-        if requirement.allows_anonymous or not requirement.requires_authenticated_user:
-            return
-        # 所有受管理入口共用此阶段；放行不改变认证器或 CurrentUser。
-        options = await self._container.get(Options[AuthorizationOptions])
-        if options.value.always_allow:
-            return
-        current_user = self._runtime.current_user()
-        if not current_user.is_authenticated:
-            raise UnauthenticatedError
-        if not requirement.permissions:
-            return
-        try:
-            checker = await self._container.get(PermissionChecker)
-        except NoFactoryError:
-            raise PermissionCheckerUnavailableError from None
-        for permission in requirement.permissions:
-            if not await checker.is_granted(current_user, permission):
-                raise PermissionDeniedError(permission=str(permission))
+        await _check_authorization(self._container, self._runtime.current_user, requirement)

python_ddd_framework/invocation/scopes.py

@@ -11,9 +11,11 @@ from .contracts import ApplicationInvocationContext
 
 
 @asynccontextmanager
-async def _managed_request(parent: AsyncContainer) -> AsyncIterator[AsyncContainer]:
-    """排空入口自己创建的 REQUEST；不推断业务事务是否已经提交。"""
-    request = parent(scope=Scope.REQUEST)
+async def _managed_request(
+    parent: AsyncContainer, *, context: dict[type[object], object] | None = None
+) -> AsyncIterator[AsyncContainer]:
+    """显式传入原生 scope 输入并排空独立 REQUEST；不复制父容器缓存或推断事务结果。"""
+    request = parent(context=context, scope=Scope.REQUEST)
     primary: BaseException | None = None
     try:
         yield request

python_ddd_framework/observability/formatting.py

@@ -17,6 +17,7 @@ _DIAGNOSTIC_FIELDS = (
     "audit_contract",
     "audit_method",
     "audit_route_template",
+    "access_exception_type",
 )
 _HTTP_DIAGNOSTIC_LOGGERS = ("httpx", "httpcore", "uvicorn.access")
 

python_ddd_framework/unit_of_work/manager.py

@@ -3,8 +3,8 @@
 from __future__ import annotations
 
 import asyncio
-from collections.abc import AsyncIterator, Callable
-from contextlib import AsyncExitStack, asynccontextmanager
+from collections.abc import AsyncIterator, Callable, Iterator
+from contextlib import AsyncExitStack, asynccontextmanager, contextmanager
 from contextvars import ContextVar
 from functools import partial
 from typing import TYPE_CHECKING
@@ -61,6 +61,15 @@ class UnitOfWorkManager:
             raise RuntimeError("operation requires a transactional UnitOfWork")
         return work
 
+    @contextmanager
+    def _detached_work(self) -> Iterator[None]:
+        """受监督的阶段交接不继承旧事务；普通子任务仍使用 current 的 task guard。"""
+        token = self._ambient.set(None)
+        try:
+            yield
+        finally:
+            self._ambient.reset(token)
+
     def _resolve_options(
         self, connection_name: str | None, declaration: UnitOfWorkDeclaration, method_name: str
     ) -> _ResolvedUnitOfWorkOptions:

{python_ddd_framework-0.6.0.dist-info → python_ddd_framework-0.7.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-ddd-framework
-Version: 0.6.0
+Version: 0.7.0
 Summary: Modular DDD application framework with project CLI and bundled templates
 License-Expression: LicenseRef-Proprietary
 License-File: LICENSE
@@ -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.
 
@@ -295,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.
@@ -452,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>
 
@@ -541,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` guides contributors from business rules and ownership to framework capability selection and verification. The development guide maps common tasks to framework capabilities and includes commands to locate the installed version's source and bundled examples; each DDD module README records the sample business model and traces approval through its owners. The application maintains these documents after generation; framework upgrades do not overwrite them. Existing applications can use their installed package's `developer_kit/templates` as a read-only reference when updating affected guidance, preserving their own business model and decisions.
+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