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

python_ddd_framework/developer_kit/publication.py

@@ -0,0 +1,442 @@
+"""一次模块生成的发布现场；记录事实并指导手动恢复，不自动补偿。"""
+
+from __future__ import annotations
+
+import hashlib
+import importlib.metadata as metadata
+import json
+import shutil
+import subprocess
+import sys
+import tempfile
+from collections.abc import Iterator
+from contextlib import contextmanager
+from dataclasses import dataclass
+from pathlib import Path
+from types import TracebackType
+from typing import Literal
+from uuid import uuid4
+
+from filelock import FileLock, Timeout
+
+from ..cli.errors import CommandError
+from ..cli.project import _PROJECT_ENVIRONMENT_OVERRIDES, project_environment
+
+
+def _digest(content: bytes) -> str:
+    return hashlib.sha256(content).hexdigest()
+
+
+def _content(path: Path) -> bytes | None:
+    if path.is_symlink() or path.is_junction():
+        raise CommandError(f"Refusing linked publication target: {path}")
+    return path.read_bytes() if path.exists() else None
+
+
+def _tree(root: Path) -> dict[str, str]:
+    if root.is_symlink() or root.is_junction() or not root.is_dir():
+        raise CommandError(f"Expected an ordinary module directory: {root}")
+    result: dict[str, str] = {}
+    directories = [root]
+    # iterdir 的读取错误必须传播；不能把无法枚举的目录当作已完整核对的空目录。
+    while directories:
+        for path in sorted(directories.pop().iterdir()):
+            if path.is_symlink() or path.is_junction():
+                raise CommandError(f"Unexpected link in module directory: {path}")
+            if path.is_dir():
+                result[path.relative_to(root).as_posix()] = "directory"
+                directories.append(path)
+            else:
+                result[path.relative_to(root).as_posix()] = _digest(path.read_bytes())
+    return result
+
+
+@dataclass(frozen=True)
+class _FileChange:
+    name: str
+    target: Path
+    original: bytes | None
+    proposed: bytes
+    pending: Path
+
+
+class _ModulePublication:
+    def __init__(self, root: Path, package: str, template: Literal["basic", "ddd"]) -> None:
+        self.root = root.resolve()
+        self.operation_id = uuid4().hex
+        self.recovery_root = self.root / ".python-ddd-framework" / "generation"
+        self.recovery = self.recovery_root / self.operation_id
+        self.rendering = Path(tempfile.gettempdir()) / f"pddd-add-{self.operation_id}"
+        self.destination = self.root / "src" / "modules" / package
+        self.pending = self.destination.with_name(f".pddd-{self.operation_id}")
+        self.template = template
+        self._lock = FileLock(
+            self.recovery_root.parent / "generation.lock",
+            timeout=0,
+            fallback_to_soft=False,
+            preserve_lock_file=True,
+        )
+        self._changes: tuple[_FileChange, ...] = ()
+        self._module_files: dict[str, str] = {}
+        self._current_step = "prepare"
+
+    def __enter__(self) -> _ModulePublication:
+        try:
+            self._lock.acquire()
+        except Timeout as error:
+            raise CommandError(
+                f"Another module generation owns {self.root}; inspect {self.recovery_root}"
+            ) from error
+        try:
+            print(f"Module recovery files: {self.recovery}", flush=True)
+            self.recovery.mkdir(parents=True)
+            self._write_json(
+                "operation.json",
+                {
+                    "operation_id": self.operation_id,
+                    "project_root": str(self.root),
+                    "distribution": "python-ddd-framework",
+                    "version": metadata.version("python-ddd-framework"),
+                    "template": self.template,
+                    "rendering": str(self.rendering),
+                    "destination": str(self.destination),
+                    "pending_module": str(self.pending),
+                },
+            )
+            self.recovery.joinpath("RECOVERY.md").write_text(
+                _RECOVERY.replace("<RECOVERY_PATH>", repr(self.recovery.as_posix())),
+                encoding="utf-8",
+            )
+        except BaseException:
+            self._lock.release()
+            print(f"Preparation failed; retained files: {self.recovery}", file=sys.stderr)
+            raise
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        try:
+            if exc is not None:
+                self._report_failure(exc)
+        finally:
+            self._lock.release()
+
+    def _write_json(self, name: str, value: object) -> None:
+        # 计划只写一次；写入失败留下原片段，不能带着不完整计划开始发布。
+        with self.recovery.joinpath(name).open("x", encoding="utf-8") as stream:
+            json.dump(value, stream, ensure_ascii=True, indent=2)
+            stream.write("\n")
+
+    def _record(self, step: str, state: str, *, returncode: int | None = None) -> None:
+        with self.recovery.joinpath("steps.jsonl").open("a", encoding="utf-8") as stream:
+            stream.write(json.dumps({"step": step, "state": state, "returncode": returncode}))
+            stream.write("\n")
+
+    @contextmanager
+    def step(self, name: str) -> Iterator[None]:
+        self._current_step = name
+        self._record(name, "started")
+        yield
+        self._record(name, "completed")
+
+    def prepare(self, staged: Path, changes: tuple[tuple[str, Path, bytes, bytes], ...]) -> None:
+        modules = self.destination.parent
+        if modules.is_symlink() or modules.is_junction():
+            raise CommandError(f"Refusing linked modules directory: {modules}")
+        marker = modules / "__init__.py"
+        marker_original = _content(marker)
+        marker_change = (
+            (("package_marker", marker, marker_original, marker_original or b""),)
+            if all(path != marker for _, path, _, _ in changes)
+            else ()
+        )
+        self._changes = tuple(
+            _FileChange(
+                name,
+                path,
+                original,
+                proposed,
+                path.with_name(f".pddd-{self.operation_id}-{name}"),
+            )
+            for name, path, original, proposed in (
+                *marker_change,
+                *changes,
+            )
+        )
+        self._module_files = _tree(staged)
+        originals = self.recovery / "original"
+        proposed = self.recovery / "proposed"
+        originals.mkdir()
+        proposed.mkdir()
+        files: list[dict[str, object]] = []
+        for change in self._changes:
+            original = originals / change.name
+            generated = proposed / change.name
+            if change.original is not None:
+                original.write_bytes(change.original)
+            generated.write_bytes(change.proposed)
+            files.append(
+                {
+                    "step": change.name,
+                    "target": str(change.target),
+                    "pending": str(change.pending),
+                    "original": str(original) if change.original is not None else None,
+                    "original_sha256": (
+                        _digest(change.original) if change.original is not None else None
+                    ),
+                    "proposed": str(generated),
+                    "proposed_sha256": _digest(change.proposed),
+                }
+            )
+        self._write_json(
+            "plan.json",
+            {
+                "module_source": str(staged),
+                "module_target": str(self.destination),
+                "module_pending": str(self.pending),
+                "module_files": self._module_files,
+                "modules_directory": str(modules),
+                "modules_directory_existed": modules.exists(),
+                "files": files,
+                "publish_order": ["module", *(change.name for change in self._changes)],
+                "sync_command": ["uv", "sync", "--directory", str(self.root)],
+                # 保存完整策略，重试前才出现的覆盖也必须清理；不保存环境变量值。
+                "sync_environment_unset": _PROJECT_ENVIRONMENT_OVERRIDES,
+                "sync_log": str(self.recovery / "uv-sync.log"),
+            },
+        )
+        self._check_originals()
+
+    def _check_originals(self) -> None:
+        modules = self.destination.parent
+        if modules.is_symlink() or modules.is_junction():
+            raise CommandError(f"Modules directory changed to a link: {modules}")
+        if self.destination.exists() or self.destination.is_symlink():
+            raise CommandError(f"Module destination already exists: {self.destination}")
+        for change in self._changes:
+            if _content(change.target) != change.original:
+                raise CommandError(f"Content changed during generation: {change.target}")
+
+    def publish(self, staged: Path) -> None:
+        with self.step("local_copy"):
+            self._check_originals()
+            self.destination.parent.mkdir(exist_ok=True)
+            shutil.copytree(staged, self.pending)
+            for change in self._changes:
+                # 包标记用独占创建；原有文件的待发布副本与目标处于同一文件系统。
+                if change.name == "package_marker":
+                    continue
+                with change.pending.open("xb") as stream:
+                    stream.write(change.proposed)
+                shutil.copymode(change.target, change.pending)
+            if _tree(self.pending) != self._module_files:
+                raise CommandError(f"Incomplete module copy: {self.pending}")
+        with self.step("module"):
+            self._check_originals()
+            self.pending.rename(self.destination)
+        for change in self._changes:
+            with self.step(change.name):
+                if _content(change.target) != change.original:
+                    raise CommandError(f"Content changed during generation: {change.target}")
+                if change.name == "package_marker":
+                    if change.original is None:
+                        with change.target.open("xb") as stream:
+                            stream.write(change.proposed)
+                else:
+                    if _content(change.pending) != change.proposed:
+                        raise CommandError(f"Pending content changed: {change.pending}")
+                    change.pending.replace(change.target)
+        with self.step("files_published"):
+            if self.file_states() != dict.fromkeys(
+                ("module", *(change.name for change in self._changes)), "published"
+            ):
+                raise CommandError("Published files no longer match the generation plan")
+
+    def sync(self) -> None:
+        command = ["uv", "sync", "--directory", str(self.root)]
+        self._current_step = "sync"
+        self._record("sync", "started")
+        with self.recovery.joinpath("uv-sync.log").open("xb") as log:
+            result = subprocess.run(
+                command,
+                cwd=self.root,
+                env=project_environment(),
+                stdout=log,
+                stderr=subprocess.STDOUT,
+                check=False,
+            )
+        self._record(
+            "sync",
+            "completed" if result.returncode == 0 else "failed",
+            returncode=result.returncode,
+        )
+        result.check_returncode()
+
+    def file_states(self) -> dict[str, str]:
+        """日志可能停在写后记录之前，诊断必须重新读取磁盘内容。"""
+        if not self._changes:
+            return {"publication": "not_started"}
+        states: dict[str, str] = {}
+        try:
+            self.destination.lstat()
+        except FileNotFoundError:
+            states["module"] = "not_published"
+        except OSError:
+            states["module"] = "unknown/conflict"
+        else:
+            try:
+                states["module"] = (
+                    "published"
+                    if _tree(self.destination) == self._module_files
+                    else "unknown/conflict"
+                )
+            except (OSError, CommandError):
+                states["module"] = "unknown/conflict"
+        for change in self._changes:
+            try:
+                content = _content(change.target)
+                states[change.name] = (
+                    "published"
+                    if content == change.proposed
+                    else "not_published"
+                    if content == change.original
+                    else "unknown/conflict"
+                )
+            except (OSError, CommandError):
+                states[change.name] = "unknown/conflict"
+        return states
+
+    def _report_failure(self, error: BaseException) -> None:
+        try:
+            self._record(
+                self._current_step,
+                "interrupted" if isinstance(error, KeyboardInterrupt) else "failed",
+            )
+        except OSError as record_error:
+            print(
+                f"Could not record failure ({type(record_error).__name__}); inspect disk contents.",
+                file=sys.stderr,
+            )
+        print(
+            f"Module generation stopped at {self._current_step}; "
+            f"disk state: {self.file_states()}.\n"
+            f"All remaining files are retained. Review {self.recovery / 'RECOVERY.md'}; "
+            f"rendering: {self.rendering}.\n"
+            "After confirming all published contents, use the isolated uv sync retry "
+            "in RECOVERY.md.",
+            file=sys.stderr,
+            flush=True,
+        )
+
+
+_RECOVERY = """# Manual module recovery
+
+Keep this directory and every path recorded in operation.json / plan.json.
+No rollback or cleanup was performed. Stop other generators, editors and uv processes
+before inspecting or changing the project. The generator lock does not lock editors.
+
+## Inspect first
+
+operation.json identifies the backend, CLI/template version and rendering location.
+plan.json records exact original/proposed copies, SHA-256 digests, module directory
+entries, pending paths, prior directory/marker existence and publication order.
+It also records the sync command and the environment overrides to clear for that command.
+steps.jsonl records intent before each action and completion afterwards; a missing or
+partial final line does not prove the action failed. uv-sync.log contains install output.
+A complete plan is required before publication. If plan.json is missing or unreadable,
+stop recovery and inspect retained copies and actual targets; do not infer that nothing
+was written. Retain any partial preparation files.
+
+Save this read-only inspection outside the project, then run `python -I <inspection-file>`
+with Python 3.12 or newer:
+
+```python
+import hashlib, json
+from pathlib import Path
+recovery = Path(<RECOVERY_PATH>)
+plan = json.loads((recovery / "plan.json").read_text(encoding="utf-8"))
+for item in plan["files"]:
+    path = Path(item["target"])
+    linked = path.is_symlink() or path.is_junction()
+    actual = None
+    if path.is_file() and not linked:
+        actual = hashlib.sha256(path.read_bytes()).hexdigest()
+    state = "UNKNOWN - inspect before editing"
+    if not linked and (path.is_file() or not path.exists()):
+        if actual == item["proposed_sha256"]:
+            state = "published"
+        elif actual == item["original_sha256"]:
+            state = "original"
+    print(item["step"], path, state, "actual:", actual)
+module = Path(plan["module_target"])
+actual = {}
+directories = [module] if module.is_dir() else []
+while directories:
+    for path in directories.pop().iterdir():
+        if path.is_symlink() or path.is_junction():
+            value = "UNKNOWN LINK"
+        elif path.is_dir():
+            value = "directory"
+            directories.append(path)
+        else:
+            value = hashlib.sha256(path.read_bytes()).hexdigest()
+        actual[path.relative_to(module).as_posix()] = value
+print("module missing:", not module.exists())
+print("module root is linked:", module.is_symlink() or module.is_junction())
+for key in actual.keys() | plan["module_files"].keys():
+    if actual.get(key) != plan["module_files"].get(key):
+        print("module difference:", key)
+print("Inspect all links and unknown files manually; never overwrite them.")
+```
+
+## Choose and perform each step manually
+
+1. Compare the complete module tree (including extra files, directories and links)
+   with module_files and module_source. A matching target is already published.
+   If absent, review the complete staged copy before manually copying to that absent
+   target. Stop on partial content, any link, extra file or differing digest.
+2. Inspect files in publish_order: package_marker, startup, metadata. An unchanged
+   original marker is retained. Create a missing marker only when recorded as absent.
+   For startup / metadata, continue only while target equals original_sha256; use
+   the proposed copy named in plan.json. For a manual rollback, restore the original
+   copy only while target equals proposed_sha256. Verify the copy's digest as well.
+   Prepare a complete sibling file, recheck the target, then replace that one file.
+   Any different content is a conflict: review the diff and decide what to keep.
+3. Leave generated modules, markers, pending files and recovery directories in place.
+   Removing or moving any path is a separate explicit decision. Do not rerun add module
+   to repair a partially published operation or overwrite an existing destination.
+4. Once every target matches the proposed contents, use the isolated sync retry below.
+   A missing success record means installation is unconfirmed. uv may already have
+   changed uv.lock or the environment; neither is automatically rolled back.
+
+Single-file replacement is not a transaction across files. External edits can race
+with checks; this record does not promise power-loss durability or automatic recovery.
+
+## Retry installation independently
+
+Save this script outside the project, then run `python -I <retry-file>` with Python 3.12
+or newer. It runs only uv sync in the recorded backend. The -I option isolates Python
+from external Python settings; the script clears the same overrides as the CLI from
+the child environment, including overrides added after generation. The current shell
+environment is preserved. No framework import or working backend environment is needed.
+Check the process exit status and output; the original operation records remain unchanged.
+
+```python
+import json, os, subprocess
+from pathlib import Path
+recovery = Path(<RECOVERY_PATH>)
+operation = json.loads((recovery / "operation.json").read_text(encoding="utf-8"))
+plan = json.loads((recovery / "plan.json").read_text(encoding="utf-8"))
+environment = dict(os.environ)
+for key in plan["sync_environment_unset"]:
+    environment.pop(key, None)
+result = subprocess.run(
+    plan["sync_command"], cwd=operation["project_root"], env=environment, check=False
+)
+raise SystemExit(result.returncode)
+```
+"""

python_ddd_framework/developer_kit/templates/module/cookiecutter.json

@@ -1 +1 @@
-{"module_name": "orders", "class_prefix": "Orders", "http_service_path": "/orders", "http_operation_prefix": "orders_"}
+{"module_name": "capability", "class_prefix": "Capability"}

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/README.md

@@ -1,63 +1,53 @@
 # {{ cookiecutter.class_prefix }} module
 
-This module owns the generated order example. Adapt its business rules from confirmed requirements. The Host explicitly selects its Application, SQLAlchemy, and HttpApi Modules and infrastructure providers.
+This is a DDD module skeleton. It has no business rules, entities, DTOs, services, endpoints, database tables, seed data, background tasks, or test cases. The Host selects its Application, SQLAlchemy, and HttpApi Modules; infrastructure providers remain Host-owned.
 
-[Project setup](../../../../README.md) · [Working rules](../../../../AGENTS.md) · [Architecture](../../../../docs/architecture.md) · [Directory and coding rules](../../../../docs/development.md#module-layout-and-coding-rules)
+[Project setup](../../../../README.md) · [Working rules](../../../../AGENTS.md) · [Architecture](../../../../docs/architecture.md) · [Design checks](../../../../docs/development.md#design-and-delivery-checks) · [Directory rules](../../../../docs/development.md#module-layout-and-coding-rules)
 
-## Owners and entry points
+## Record the business responsibility
 
-| Capability | Entry |
+Before implementation, record the confirmed capability, caller, business language, public contracts, and data owner here. For each invariant, identify its aggregate or service owner, business operation, and a concrete rejection example. Record consistency, concurrency, idempotency, failure-after-commit, and collaboration decisions when relevant. Unresolved questions remain explicit; directory names and documentation recipes do not authorize business rules.
+
+Keep this README current with the implementation and its actual verification. A small correction may reference existing conclusions rather than creating another design document.
+
+## Layers and initial wiring
+
+| Layer | Responsibility and current state |
 | --- | --- |
-| Shared constraints, permissions, errors, messages | [Shared layer](domain_shared/module.py), [constants](domain_shared/constants/order_constants.py), [permissions](domain_shared/permissions/order_permission_provider.py) |
-| Aggregate, value, domain policy | [Order](domain/entities/order.py), [title](domain/value_objects/order_title.py), [approval policy](domain/services/order_approval_service.py) |
-| Shared immutable value example | [Money](domain_shared/value_objects/money.py), reusable by Domain and public DTOs; no new sample HTTP fields |
-| Repository contract and settings | [Repository](domain/repositories/order_repository.py), [approval setting](domain/settings/approval_settings.py) |
-| User contracts and use cases | [Query contract](application_contracts/services/order_query_service.py), [management](application/services/order_management_service.py), [approval](application/services/order_approval_service.py) |
-| Internal reporting | [Contract](application_contracts/integration_services/order_reporting_service.py), [implementation](application/integration_services/order_reporting_service.py) |
-| Background and lifecycle | [Approval Job](application/background_jobs/order_approval/handler.py), [statistics schedule](application/background_jobs/order_statistics/schedule.py), [maintenance Worker](application/background_workers/order_maintenance_worker.py), [HostedService](application/hosted_services/order_integration_service.py) |
-| Events, interception, settings refresh | [After-commit handler](application/event_handlers/order_changed_handler.py), [interceptor](application/interceptors/order_timing_interceptor.py), [observer](application/setting_handlers/approval_setting_observer.py) |
-| Persistence | [Model](sqlalchemy/models/order_model.py), [repository](sqlalchemy/repositories/order_repository.py), [registration](sqlalchemy/module.py) |
-| Transport | [HTTP exposure](http_api/module.py), [file router](http_api/routers/order_files.py), [WebSocket](http_api/websockets/order_socket.py) |
-
-## Behavior and enablement
-
-- 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. 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.
-
-## Optional in-process observations
-
-The external integration example includes a pure-value [snapshot](domain_shared/messages/order_observation.py)
-and a [Handler](application/hosted_services/order_observation_handler.py). It is not enabled by
-default and does not replace existing callbacks. Follow the project's development guide to add
-MessagingModule, declare the typed channel and register the ACTION Handler. Only pending
-snapshots may coalesce; acceptance, completion, commit and external acknowledgement differ.
+| `domain_shared` | Shared contract values, constants, errors, permissions, and messages. No business declarations or framework capability dependencies yet. |
+| `domain` | Aggregates, domain services, repository contracts, events, settings, and seed contributors. Depends on DomainShared; it contains no business implementation. |
+| `application_contracts` | Public service Protocols and input/output DTOs. Depends on DomainShared; contracts do not depend on Domain or implementations. |
+| `application` | Use-case orchestration and handlers. Depends on Domain and ApplicationContracts; its package is scanned but has no services or task declarations. |
+| `sqlalchemy` | Persistence implementations and owned migrations. Depends on Domain and SqlAlchemyPersistenceModule; it retains its Base, model discovery, repository scanning, and migration registration. |
+| `http_api` | Transport declarations. Depends on FastApiModule and exposes this module's contracts; empty contracts produce no business endpoints. |
 
-## Persistence and verification
+All responsibility directories and package markers are retained for navigation. Add implementations only for authorized requirements; do not fill them with placeholder interfaces or services. `module.py` owns dependencies, registration, and the seven lifecycle hooks. Empty hooks use `pass`; package markers contain no business or compatibility exports. `tests/` initially contains only its package marker.
+
+## Implement the first use case
 
-This module's ordinary models do not automatically become extension targets. To publish a reusable extension point, declare `ExtensionPoints` with explicit DTO/entity targets and use `ExtensibleModel` for those DTOs. Customer modules contribute typed `ExtensionProperties`; SQL column mappings reference the same fields and belong to their persistence Module. The base module keeps table/Schema/core ownership, while customer extension revisions declare native Alembic `depends_on` and include only their declared columns/indexes. Effective DTO and mapper state belong to each Application.
+1. Identify **owner -> layer -> directory -> verified framework API**, following the project design checks. Add shared values only when they are actually shared.
+2. Model aggregate transitions and invariants in Domain. Define domain-facing repositories without ORM or Session types. Add public DTOs and service Protocols in ApplicationContracts, then implement the authorized use case in Application.
+3. Declare the framework capability dependencies where used: for example, ApplicationServicesModule for application services, AuthorizationModule for permission definitions, or DataSeedingModule for seed contributors. The Host's provider choices do not repair missing module dependencies.
+4. Implement persistence under `sqlalchemy/models` and `sqlalchemy/repositories`. The existing [Base](sqlalchemy/models/base.py) and [registration](sqlalchemy/module.py) own this module's metadata and migration branch. Business models, tables, and schema decisions must come from requirements.
+5. Conventional HTTP exposure can discover the new public service contracts. Add manual routers only where the transport requires them; keep use-case rules out of HTTP. Register workers, jobs, hosted services, schedules, or event handlers explicitly when required.
+6. Update this responsibility record and run the smallest relevant existing checks. New tests and infrastructure validation require the task's authorization; neither an empty test directory nor successful composition proves business correctness.
 
-From the application root, generate and review a revision, then apply and seed explicitly:
+## Persistence and verification
+
+An empty skeleton retains model and migration registration but has no business tables or revisions. Migration commands still use the configured database; an empty registered Base is different from a module with no model registration. Add actual models before generating a business revision, and review it before applying:
 
 ```sh
 pddd db revision --module {{ cookiecutter.module_name }}
 pddd db upgrade --module {{ cookiecutter.module_name }}
 pddd db status --module {{ cookiecutter.module_name }}
-pddd db seed --module {{ cookiecutter.module_name }}
-cd backend
-uv run pytest src/modules/{{ cookiecutter.module_name }}/tests
 ```
 
-Keep applied migrations immutable. The domain test covers repeat-approval rejection; it does not prove infrastructure, HTTP, background, or deployment behavior. Host tests cover generic health and identity. Update the owning contracts, implementation, documentation, and existing verification when adapting the example. Every Module supplies all seven lifecycle hooks; keep empty stages as `pass`.
-
-## Data and events
+Run `pddd db seed --module {{ cookiecutter.module_name }}` only after declaring the intended contributors and preparing their database. Keep applied revisions immutable and upgrade prerequisites explicitly. Host startup never migrates or seeds.
 
-`OrderRepository.find` returns an optional aggregate; `get` requires one. List/count/page methods keep explicit ORM mapping and stable ordering. Business `save` participates in the caller's UoW and records entity and aggregate events once. Nontransactional UoWs reject event-producing writes before staging. The framework repository's `auto_save` flushes without committing an outer UoW.
+Run installed `pddd` commands from any application directory. Run native tools from `backend/`:
 
-Inject `DistributedCache[OrderCacheItem]` (or the statistics item), using keys directly. Item classes in `application/caching/` own stable names. Global defaults and explicit entry options are complete alternatives. Use `consider_uow=True` for writes/deletions that should apply after a successful commit. `await events.publish(message)` dispatches immediately without a UoW and follows DOMAIN/AFTER_COMMIT stages inside a transaction; post-commit errors do not undo saved data.
+```sh
+uv build --no-sources
+```
 
-This is the `ddd` template (the default), with all six layers and supported examples. Use `--template basic` for an ordinary in-process service. This module lives under `backend/src/modules/`; native uv/test/build commands run from `backend/`, while installed `pddd` project commands locate the owning backend from any application directory.
+After authorized test cases exist, run `uv run pytest src/modules/{{ cookiecutter.module_name }}/tests`. The empty skeleton has no tests to pass. Host tests cover generic health and identity and require their configured infrastructure; see the project verification guide. Module tests are excluded from production wheels and service discovery. The `basic` template remains available for an ordinary in-process service without DDD layers.