stapel-forms 0.6.3__py3-none-any.whl

stapel_forms/CONFIG.MD

@@ -0,0 +1,81 @@
+# CONFIG.MD — stapel-forms
+
+Config registry for **stapel-forms** (`static-scaffold-and-config.md` §2).
+One row per configuration key the module reads, its **source** (`env` = the
+process environment / the `STAPEL_FORMS` settings dict), what it is for,
+whether it is required, and its default.
+
+All keys are read through `forms_settings`
+(`stapel_forms.conf.AppSettings`, namespace `STAPEL_FORMS`).
+Resolution order per key: `settings.STAPEL_FORMS` dict → a flat Django
+setting of the same name → environment variable → the default below.
+There are no `import_strings` keys in this module.
+
+## stapel-forms
+
+### Schema surface (source: env)
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| FIELD_KINDS | env | allowlist of stapel-attributes kinds a form schema may use. A kind registered in the attributes registry but absent here cannot be asked on a public URL. Kinds implying binary payloads are absent by construction — there is no anonymous attachment path (check `stapel_forms.E001` refuses kinds nothing answers for; `E002` refuses an empty list). | no | the ten builtins: string, int, float, bool, select, date, header, hex_color, hierarchical_select, convertible_unit |
+| MAX_FIELDS_PER_FORM | env | ceiling on fields in a published version; also bounds the CSV column count. | no | 64 |
+
+### Abuse ladder (source: env)
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| MAX_SUBMISSION_BYTES | env | `Content-Length` gate applied BEFORE the JSON parse; over it is 413 `error.413.forms_body_too_large`. 0 disables. | no | 65536 |
+| MAX_SUBMISSIONS_PER_FORM | env | per-form row cap bounding what one leaked public link can cost; past it the submit answers 409 `error.409.forms_submission_cap`. 0 disables. | no | 10000 |
+| MAX_OPEN_FORMS_PER_WORKSPACE | env | ceiling on simultaneously open forms in one workspace. 0 disables. | no | 100 |
+| SUBMIT_THROTTLE | env | DRF scoped rate for the anonymous submit, per client IP (netintel-resolved, never raw XFF). A library cannot own `DEFAULT_THROTTLE_RATES`, so the rate lives here. `None` disables — a conscious act. | no | 20/h |
+| PUBLIC_SCHEMA_THROTTLE | env | same, for the anonymous schema fetch — the enumeration backstop. `None` disables. | no | 120/h |
+| ALLOW_UNCAPTCHAED_PUBLIC | env | the confession switch. Off: a deployment with an open public form and no `STAPEL_CAPTCHA["SECRET"]` gets `stapel_forms.W001`. On: the warning is silenced because the host says the refusal is deliberate. | no | False |
+
+### Respondent privacy (source: env)
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| STORE_CLIENT_META | env | persist the respondent's IP and user-agent on each submission. Off: nothing needs them on disk — throttling and netintel classification work off the live request and the cache. On: that data falls under the same retention clock as the answers. | no | False |
+| RETENTION_DAYS | env | how long a response lives before the purge destroys it. A per-form `settings.retention_days` may only SHORTEN this; lengthening past the ceiling requires raising it here, so one form cannot rewrite the deployment's promise. `None` keeps answers forever — an explicit host decision. | no | 365 |
+| PURGE_SCHEDULE | env | crontab kwargs for the retention beat entry (`get_forms_beat_schedule()`). Cadence is configuration, not a literal. | no | {"hour": 4, "minute": 40} |
+
+### Notifications (source: env)
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| NOTIFY_COOLDOWN_SECONDS | env | minimum gap between auto-notify letters for one form; submissions inside the window fold into the next letter as a count. Keyed on the form, not the caller — the protected resource is the owner's inbox. Admin-initiated resend is deliberately NOT subject to it. 0 notifies every time. | no | 600 |
+
+### Versioning (source: env)
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| ACCEPT_PREVIOUS_VERSION_SECONDS | env | grace window during which a submit naming the previous version is still accepted after a publish. 0 (strict) refuses it wholesale with 409 `error.409.forms_version_superseded`, so the renderer refetches and tells the respondent rather than half-validating against a schema they never saw. | no | 0 |
+
+### Response review (source: env)
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| MAX_PAGE_SIZE | env | service-side cap on `?limit=` for the keyset response listing. | no | 100 |
+| EXPORT_PAGE_SIZE | env | rows per CSV export request; the continuation cursor comes back in the `X-Forms-Next-Before` header rather than materializing the whole table. | no | 1000 |
+
+## Keys this module READS from other namespaces
+
+| Key | Owner | Why it matters here |
+|-----|-------|---------------------|
+| STAPEL_CAPTCHA["SECRET"] | stapel-core | with no backend configured the captcha verifier is a no-op and every bot that finds a public link is accepted; `stapel_forms.W001` says so. |
+| STAPEL_WORKSPACES["ROLES"] | stapel-workspaces | grants `forms.*` to roles. Without a grant every admin request denies; only `owner` has `*` by default. An entry REPLACES a whole role — there is no deep merge. The four grantable strings, what each one means and exactly which operations it opens are published in `docs/capabilities.json` under `capabilities[]` (and per operation as `x-stapel-capability` in `docs/schema.json`), derived from the gate that enforces them — see MODULE.md §4. Do not transcribe them into a host-side constant: read `stapel_forms.authz.capability_for(action)` or the artifact. |
+| STAPEL_GDPR["DATA_OWNERS"] | stapel-gdpr | must include `"forms"`, or the erasure closure never completes (`gdpr.E002`; `stapel_forms.W003` warns from this side). |
+| STAPEL_NOTIFICATIONS["TYPES"] | stapel-notifications | the host-side bridge for `forms.submission_received` / `forms.submission_resend` until the upstream `NOTIFICATION_ROUTING` entries land. See MODULE.md §9. |
+| CELERY_BEAT_SCHEDULE | the host | must contain an entry whose `task` is `stapel_forms.tasks.purge_expired_submissions`, or retention never runs (`stapel_forms.W002`). |
+| DATA_PLANE_APPS | the host | isolation-tier hosts list `forms`. No schema impact. |
+
+## Per-form settings (not deployment config)
+
+`Form.settings` is a JSON blob on the row, edited over the API, not a Django
+setting. Recognized keys:
+
+| Key | Purpose |
+|-----|---------|
+| notify_emails | `[str]` — email destinations for the auto-notify and resend. |
+| notify_telegram_chat_ids | `[str]` — telegram chat destinations (no account behind them; stapel-core 0.31 `telegram_chat_id`). |
+| retention_days | `int` — shortens this form's retention below `RETENTION_DAYS`. Lengthening past the module ceiling is refused with `error.400.forms_invalid_retention`. |

stapel_forms/__init__.py

@@ -0,0 +1,31 @@
+"""stapel-forms — admin-defined forms, anonymous submissions, response review.
+
+Public API (lazily exported, PEP 562 — importing this package never pulls
+in Django or requires configured settings):
+
+- ``forms_settings`` — resolved app settings (``stapel_forms.conf``).
+"""
+
+__all__ = [
+    "forms_settings",
+]
+
+# name -> submodule that defines it. Resolution is deferred until first
+# attribute access so that `import stapel_forms` stays Django-free.
+_LAZY_EXPORTS = {
+    "forms_settings": ".conf",
+}
+
+
+def __getattr__(name):
+    if name in _LAZY_EXPORTS:
+        from importlib import import_module
+
+        value = getattr(import_module(_LAZY_EXPORTS[name], __name__), name)
+        globals()[name] = value  # cache for subsequent lookups
+        return value
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    return sorted(set(globals()) | set(__all__))

stapel_forms/_capabilities.py

@@ -0,0 +1,216 @@
+"""stapel-forms capabilities.json emitter — thin shim over stapel_tools.capabilities.
+
+Two different things wear the word "capability" in this repo and the file
+this module writes carries both, so the distinction is worth stating once:
+
+* an **axis** is a configuration switch that changes what the PRODUCT may
+  do (may a form ask for a colour, are respondent IPs kept). The generic
+  mechanism in ``stapel_tools.capabilities`` derives those from
+  ``conf.DEFAULTS``;
+* a **workspace capability** is a permission string — ``forms.view``,
+  ``forms.responses.manage`` — that says who may drive an endpoint. Those
+  are what a host grants in ``STAPEL_WORKSPACES["ROLES"]`` and what a UI
+  gates a control on.
+
+Until 0.3.0 this artifact projected only the first kind, so
+``forms.responses.manage`` existed in ``authz.py``, was enforced on two
+endpoints, and appeared in NO machine-readable artifact this module ships.
+A frontend could therefore not tell whether the responses surface should be
+offered at all, and its only options were to show it to everyone or to hide
+it from everyone. The ``capabilities`` section below closes that.
+
+Why it is derived from ``docs/schema.json`` rather than restated here: the
+capability lands in the schema as ``x-stapel-capability``, written by
+``views.CapabilityAwareAutoSchema`` off the very attribute
+``views.gated(...)`` stamps on the handler and ``views._access_error``
+reads to authorize the request. One decorator, one attribute, and both the
+projection and the enforcement hang off it — a capability cannot be
+published for an operation that will not actually be gated on it, because
+there is no second place to type the string.
+"""
+from pathlib import Path
+
+# The stable-JSON pinning of the contract pipeline. Imported rather than
+# re-implemented: a second formatter here would make `make contract-check`
+# fail on whitespace the day stapel-tools changes its pinning.
+from stapel_tools.capabilities import (
+    _stable_json,
+    axis_group_rules,
+    emit_capabilities,
+)
+
+_HTTP_METHODS = ("get", "put", "post", "delete", "options", "head", "patch", "trace")
+
+
+def _capability_section(out: Path, meta: dict, enforced: tuple) -> list:
+    """Build the ``capabilities`` section: derived operations, curated prose.
+
+    Mirrors the shape of an ``axes`` entry on purpose (``key`` +
+    ``gates.operations`` + ``curated``), so a reader who knows one knows the
+    other and a consumer walks both with the same code.
+
+    Every direction of drift is a loud emission error:
+
+    * a capability the module enforces with no curated entry, or a curated
+      entry for a capability nothing enforces — the same missing/extra check
+      the axes already get;
+    * a capability that ``authz`` enforces but no operation projects. That
+      one is the real prize: it means a permission string is grantable and
+      documented while no endpoint asks for it, which is precisely the
+      "answers yes, endpoint answers 403" shape inverted.
+    """
+    import json
+
+    schema = json.loads((out / "schema.json").read_text())
+
+    operations: dict[str, list[str]] = {cap: [] for cap in enforced}
+    for path_item in schema.get("paths", {}).values():
+        for method, op in path_item.items():
+            if method not in _HTTP_METHODS:
+                continue
+            capability = op.get("x-stapel-capability")
+            if capability is None:
+                continue
+            if capability not in operations:
+                raise SystemExit(
+                    f"capabilities: schema.json projects {capability!r} on "
+                    f"{op.get('operationId')!r}, but stapel_forms.authz does not "
+                    "enforce it — the contract and the gate disagree."
+                )
+            operations[capability].append(op["operationId"])
+
+    ungated = sorted(cap for cap, ops in operations.items() if not ops)
+    if ungated:
+        raise SystemExit(
+            f"capabilities: {ungated} are enforced by stapel_forms.authz but no "
+            "operation in schema.json projects them — either an admin handler "
+            "lost its @gated(...) declaration, or the action is dead and must "
+            "leave ACTION_CAPABILITIES."
+        )
+
+    curated = meta.get("capabilities", {})
+    missing = [c for c in enforced if c not in curated]
+    extra = [c for c in curated if c not in operations]
+    if missing or extra:
+        raise SystemExit(
+            "capabilities: curated meta out of sync with the enforced capability "
+            f"set — missing from capabilities.meta.json: {missing or 'none'}; "
+            f"stale in capabilities.meta.json: {extra or 'none'}."
+        )
+
+    section = []
+    for capability in enforced:
+        entry = curated[capability]
+        for field in ("summary", "business_label"):
+            if not entry.get(field):
+                raise SystemExit(
+                    f"capabilities: capability {capability!r} lacks a non-empty "
+                    f"{field!r} in docs/capabilities.meta.json"
+                )
+        gates = {"operations": sorted(operations[capability])}
+        # Same optional `behavior` field an axis entry carries: what a
+        # consumer must know about the gate beyond which routes it opens.
+        # Here it is the one thing this capability CANNOT tell a client —
+        # see the note in docs/capabilities.meta.json.
+        if entry.get("behavior"):
+            gates["behavior"] = entry["behavior"]
+        section.append(
+            {
+                "key": capability,
+                "gates": gates,
+                "curated": {
+                    "summary": entry["summary"],
+                    "business_label": entry["business_label"],
+                },
+            }
+        )
+    return section
+
+
+def main(argv=None):
+    import argparse
+    import json
+    import sys
+
+    parser = argparse.ArgumentParser(
+        prog="stapel-forms-capabilities",
+        description="Emit docs/capabilities.json (fourth contract artifact): "
+        "config axes from conf.py DEFAULTS + the urls.py gate registry, and the "
+        "workspace capability projection derived from schema.json.",
+    )
+    parser.add_argument(
+        "--out",
+        default="docs",
+        help="Output directory; must already contain schema.json (default: docs).",
+    )
+    args = parser.parse_args(argv)
+
+    from stapel_forms._codegen import _configure
+
+    _configure()
+    from stapel_forms.authz import CAPABILITIES
+    from stapel_forms.conf import DEFAULTS
+    from stapel_forms.urls_v1 import GATE_REGISTRY
+
+    repo = Path(__file__).resolve().parent
+    out = Path(args.out)
+
+    # The CTO-facing axes are the ones that change what the PRODUCT is
+    # allowed to do, not how fast it runs: which field kinds a form may
+    # use, whether respondent IPs are stored, how long answers are kept,
+    # and whether public forms may run without a captcha. Throttle rates,
+    # page sizes, cooldown seconds and the caps are tuning — they bound
+    # abuse, they do not change the deal with the respondent.
+    axes = {
+        "FIELD_KINDS",
+        "STORE_CLIENT_META",
+        "RETENTION_DAYS",
+        "ALLOW_UNCAPTCHAED_PUBLIC",
+        "ACCEPT_PREVIOUS_VERSION_SECONDS",
+    }
+    doc = emit_capabilities(
+        out,
+        repo=repo,
+        canonical_prefix="/forms/api/v1",
+        defaults=DEFAULTS,
+        registry=GATE_REGISTRY,
+        is_axis=lambda k: k in axes,
+        axis_group=axis_group_rules(
+            exact={
+                "FIELD_KINDS": "forms.schema",
+                "STORE_CLIENT_META": "forms.privacy",
+                "RETENTION_DAYS": "forms.privacy",
+                "ALLOW_UNCAPTCHAED_PUBLIC": "forms.public",
+                "ACCEPT_PREVIOUS_VERSION_SECONDS": "forms.public",
+            }
+        ),
+    )
+
+    meta = json.loads((repo / "docs" / "capabilities.meta.json").read_text())
+    section = _capability_section(out, meta, CAPABILITIES)
+
+    # Rebuild in a fixed key order — `capabilities` sits next to `axes`
+    # because the two answer the paired questions "what may this deployment
+    # do" and "who in it may do it".
+    ordered = {}
+    for key, value in doc.items():
+        ordered[key] = value
+        if key == "axes":
+            ordered["capabilities"] = section
+    (out / "capabilities.json").write_text(_stable_json(ordered))
+
+    gated = sum(1 for a in ordered["axes"] if a["gates"]["operations"])
+    print(
+        f"{ordered['module']} capabilities: {len(ordered['axes'])} axes ({gated} "
+        f"gating operations), {len(section)} workspace capabilities over "
+        f"{sum(len(c['gates']['operations']) for c in section)} gated operations, "
+        f"{len(ordered.get('surface') or [])} surface entries, "
+        f"{ordered['operations_total']} operations total → "
+        f"{args.out}/capabilities.json",
+        file=sys.stderr,
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

stapel_forms/_codegen.py

@@ -0,0 +1,117 @@
+"""stapel-forms contract-emission harness (contract-pipeline.md §2-3).
+
+Emits the module's own contract triad into ``docs/`` from a single-module
+``{forms + core}`` Django instance mounted at the canonical ``/forms/api/v1``
+prefix:
+
+  docs/schema.json   drf-spectacular OpenAPI, this module only, canonical prefix
+  docs/flows.json    generate_flow_docs machine artifact
+  docs/errors.json   generate_error_keys registry (the per-module etalon)
+
+stapel-forms is not mounted in stapel-example-monolith, so there is no
+aggregate slice to diff against for byte-identity — validation is
+standalone (determinism + closure + canonical prefix), see
+``tests/test_contract.py``.
+
+Usage:
+    python -m stapel_forms._codegen --out docs        # `make contract`
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+
+def _configure() -> None:
+    """Configure + boot the single-module Django instance for emission."""
+    # `python -m` prepends cwd to sys.path; strip the repo root the way a
+    # flat-layout conftest does, so `import forms`-shaped collisions cannot
+    # shadow anything.
+    repo_root = os.path.dirname(os.path.abspath(__file__))
+    sys.path[:] = [p for p in sys.path if os.path.abspath(p or os.getcwd()) != repo_root]
+
+    from django.conf import settings
+
+    if not settings.configured:
+        from stapel_forms._codegen_settings import settings_kwargs
+
+        settings.configure(
+            **settings_kwargs(root_urlconf="stapel_forms.codegen_urls", contract=True)
+        )
+
+    import django
+
+    django.setup()
+
+    # drf-spectacular froze its settings singleton at import time (before
+    # configure() ran), so it is on drf defaults. The one knob to force is
+    # SCHEMA_PATH_PREFIX: left None, drf derives the operationId prefix
+    # from the common path of all endpoints — "/" across a multi-module
+    # aggregate but "/forms/api" in a single-module harness, which would
+    # strip it to bare anonymous names. Pin it to the aggregate convention.
+    from drf_spectacular.settings import spectacular_settings
+
+    from stapel_forms._codegen_settings import CODEGEN_SCHEMA_PATH_PREFIX
+
+    spectacular_settings.SCHEMA_PATH_PREFIX = CODEGEN_SCHEMA_PATH_PREFIX
+
+    # A real all-modules deployment registers drf-spectacular's JWT-cookie
+    # security-scheme extension as a side effect of its dev-only Swagger
+    # URLs. A single-module harness has no co-mounted sibling to trigger
+    # it, so without this the protected endpoints would emit without their
+    # `security` entry.
+    from stapel_core.django.openapi.swagger import _register_jwt_auth_extension
+
+    _register_jwt_auth_extension()
+
+
+def _require_python_312() -> None:
+    """Abort emission if not running the pinned 3.12 interpreter.
+
+    drf-spectacular renders component descriptions (``Optional[X]`` vs
+    ``X | None``) differently across Python minor versions, so emitting on
+    anything but the CI/monolith pin produces false diffs against the
+    committed docs/*.json.
+    """
+    if sys.version_info[:2] != (3, 12):
+        got = f"{sys.version_info.major}.{sys.version_info.minor}"
+        raise SystemExit(
+            f"stapel-forms contract emission ABORTED: running Python {got}, "
+            "but contracts must be emitted on Python 3.12 (the CI/monolith pin). "
+            "Re-run under a 3.12 interpreter."
+        )
+
+
+def main(argv: list[str] | None = None) -> int:
+    _require_python_312()
+
+    parser = argparse.ArgumentParser(
+        prog="stapel-forms-contract",
+        description="Emit this module's contract triad (schema.json + flows.json "
+        "+ errors.json) into --out, canonical /forms/api/v1 prefix.",
+    )
+    parser.add_argument("--out", default="docs", help="Output directory (default: docs).")
+    args = parser.parse_args(argv)
+
+    _configure()
+
+    from stapel_tools.codegen import emit_errors, emit_flows, emit_schema
+
+    out = Path(args.out)
+    out.mkdir(parents=True, exist_ok=True)
+    paths = emit_schema(out / "schema.json")
+    flows = emit_flows(out / "flows.json")
+    errors = emit_errors(out / "errors.json")
+
+    print(
+        f"stapel-forms contract: {paths} paths, {flows} flows, {errors} error keys "
+        f"-> {out}/",
+        file=sys.stderr,
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

stapel_forms/_codegen_settings.py

@@ -0,0 +1,165 @@
+"""Single-module Django settings for stapel-forms.
+
+One ``settings.configure(...)`` block serves three callers, which is the
+point: the test suite, the contract-emission harness and the capabilities
+emitter cannot drift apart if there is nothing to drift.
+
+  - ``conftest.py`` — the bare test mount (``stapel_forms.tests.urls``);
+  - ``_codegen.py`` / ``make contract`` — the CANONICAL mount
+    (``stapel_forms.codegen_urls`` → ``forms/``; the module's own
+    ``urls.py`` bakes the ``api/v1`` segment in, so the full public prefix
+    is ``/forms/api/v1``), plus drf-spectacular and the production
+    ``REST_FRAMEWORK`` block so the emitted schema matches what a real
+    deployment serves;
+  - ``_capabilities.py``, which reuses ``_codegen._configure``.
+
+``SPECTACULAR_SETTINGS`` is deliberately not set: drf-spectacular builds
+its settings singleton at import time, before a ``configure()``-based
+harness can populate it, so the emitter runs on drf defaults — the state
+every other pair-backend's harness emits under. The one knob that must
+still be forced, ``SCHEMA_PATH_PREFIX``, is patched on the singleton
+directly by the harness.
+"""
+from __future__ import annotations
+
+
+def _attributes_static_dir() -> str:
+    """The static/ directory inside the installed stapel-attributes."""
+    import pathlib
+
+    import stapel_attributes
+
+    return str(pathlib.Path(stapel_attributes.__file__).resolve().parent / "static")
+
+
+def settings_kwargs(
+    *,
+    root_urlconf: str = "stapel_forms.tests.urls",
+    contract: bool = False,
+) -> dict:
+    """The ``settings.configure(**kwargs)`` for a single-module forms instance."""
+    if contract:
+        # Mirror stapel_core.django.settings.REST_FRAMEWORK exactly (the
+        # config a real deployment emits under). Inlined, not imported, to
+        # dodge the import-time settings read.
+        rest_framework = {
+            "DEFAULT_AUTHENTICATION_CLASSES": [
+                "stapel_core.django.jwt.authentication.JWTCookieAuthentication",
+            ],
+            "DEFAULT_PERMISSION_CLASSES": [
+                "stapel_core.django.api.permissions.IsServiceRequest",
+                "stapel_core.django.api.permissions.IsSuperUser",
+            ],
+            "DEFAULT_RENDERER_CLASSES": [
+                "rest_framework.renderers.JSONRenderer",
+                "rest_framework.renderers.BrowsableAPIRenderer",
+            ],
+            "DEFAULT_SCHEMA_CLASS": "stapel_core.django.openapi.schemas.PermissionAwareAutoSchema",
+            "EXCEPTION_HANDLER": "stapel_core.django.api.errors.stapel_exception_handler",
+        }
+    else:
+        rest_framework = None
+
+    kwargs = dict(
+        SECRET_KEY="test-secret-key-not-for-production",
+        INSTALLED_APPS=[
+            "django.contrib.contenttypes",
+            "django.contrib.auth",
+            "django.contrib.sessions",
+            "django.contrib.admin",
+            "django.contrib.staticfiles",
+            "django.contrib.messages",
+            "stapel_core.django.apps.CommonDjangoConfig",
+            "stapel_core.django.users",
+            "rest_framework",
+            "drf_spectacular",
+            "stapel_forms",
+        ],
+        AUTH_USER_MODEL="users.User",
+        DATABASES={
+            "default": {
+                "ENGINE": "django.db.backends.sqlite3",
+                "NAME": ":memory:",
+            }
+        },
+        DEFAULT_AUTO_FIELD="django.db.models.BigAutoField",
+        USE_TZ=True,
+        STATIC_URL="/static/",
+        # stapel-attributes is an EMBEDDED library, not a Django app, so
+        # `AppDirectoriesFinder` never walks it and its shipped admin bundle
+        # — the builder's per-kind config editor — is invisible to
+        # staticfiles unless the directory is named. This is the remedy
+        # `stapel_forms.W004` tells a host to apply, applied here so the
+        # module's own harness is a correctly configured deployment rather
+        # than one that quietly demonstrates the defect.
+        STATICFILES_DIRS=[_attributes_static_dir()],
+        ROOT_URLCONF=root_urlconf,
+        # The admin surface (0.6.0) is a tested surface, so the harness has
+        # to be able to render it: templates, the session/message/auth
+        # middleware chain the admin requires, and the mandate backend that
+        # turns `@access.sensitive` into a real refusal rather than a
+        # docstring. `MandateBackend` first and `AuditedModelBackend`
+        # second mirrors the fleet's production chain — without the second
+        # entry `authenticate()` has no backend and even login fails.
+        TEMPLATES=[
+            {
+                "BACKEND": "django.template.backends.django.DjangoTemplates",
+                "APP_DIRS": True,
+                "OPTIONS": {
+                    "context_processors": [
+                        "django.template.context_processors.request",
+                        "django.contrib.auth.context_processors.auth",
+                        "django.contrib.messages.context_processors.messages",
+                    ],
+                },
+            },
+        ],
+        MIDDLEWARE=[
+            "django.contrib.sessions.middleware.SessionMiddleware",
+            "django.middleware.common.CommonMiddleware",
+            "django.contrib.auth.middleware.AuthenticationMiddleware",
+            "django.contrib.messages.middleware.MessageMiddleware",
+        ],
+        # `AuditedModelBackend` FIRST because it is the only one of the two
+        # that can carry a session: `MandateBackend` is an
+        # `AuthorizationOnlyBackend` with no `get_user`, so a `force_login`
+        # (or a real login) that binds to it loses the user on the next
+        # request and every admin page silently redirects to the login
+        # screen — a test suite that would then "pass" by asserting against
+        # an empty body. Order does not weaken the mandate: Django ORs
+        # `has_perm` across the chain, so clearance still grants.
+        AUTHENTICATION_BACKENDS=[
+            "stapel_core.access.backend.AuditedModelBackend",
+            "stapel_core.access.backend.MandateBackend",
+        ],
+        CACHES={
+            "default": {
+                "BACKEND": "django.core.cache.backends.locmem.LocMemCache",
+            }
+        },
+        # Synchronous in-process comm with schema validation ON, so the
+        # committed contracts in schemas/ are enforced by the tests.
+        STAPEL_BUS_BACKEND="stapel_core.bus.backends.memory.MemoryBus",
+        STAPEL_COMM={
+            "OUTBOX_ENABLED": False,
+            "ACTION_TRANSPORT": "inprocess",
+            "VALIDATE_SCHEMAS": True,
+            # An emit outside a transaction is a bug here, not a warning:
+            # the outbox canon is what makes "the row exists" and "the fact
+            # was announced" one decision.
+            "EMIT_OUTSIDE_ATOMIC": "error",
+        },
+        MIGRATION_MODULES={
+            "users": None,
+        },
+    )
+    if rest_framework is not None:
+        kwargs["REST_FRAMEWORK"] = rest_framework
+    return kwargs
+
+
+# The multi-module common path prefix drf-spectacular auto-detects when
+# every pair-backend's schema is emitted inside an all-modules aggregate.
+# Forced on the singleton by the harness so a single-module instance
+# derives the same operationIds.
+CODEGEN_SCHEMA_PATH_PREFIX = "/"