stapel-docs 0.1.0__py3-none-any.whl

stapel_docs/CONFIG.MD

@@ -0,0 +1,65 @@
+# CONFIG.MD — stapel-docs
+
+Config registry for **stapel-docs** (`static-scaffold-and-config.md` §2).
+One row per configuration key the module reads, its **source** (`env` = the
+process environment / the `STAPEL_DOCS` settings dict), what it is for,
+whether it is required, and its default.
+
+All keys are read through `docs_settings`
+(`stapel_docs.conf.AppSettings`, namespace `STAPEL_DOCS`).
+Resolution order per key: `settings.STAPEL_DOCS` dict → a flat Django
+setting of the same name → environment variable → the default below.
+`STORAGE` is resolved with `import_string` (dotted path). `SHARING` is one
+nested dict key; its sub-keys are listed as `SHARING.<KEY>` rows below.
+
+## stapel-docs
+
+### Storage seam & presigned URLs (source: env)
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| STORAGE | env | dotted path to a DocsStorage implementation (REPLACE) — every byte of document content I/O goes through it. | no | stapel_docs.storage.DjangoStorageBackend |
+| STORAGE_PREFIX | env | object-key prefix: `{STORAGE_PREFIX}/{workspace_id}/{document_id}/…`. | no | docs |
+| UPLOAD_URL_EXPIRES_SECONDS | env | presigned PUT URL lifetime (upload tickets). | no | 900 |
+| DOWNLOAD_URL_EXPIRES_SECONDS | env | presigned GET URL lifetime (downloads). | no | 3600 |
+
+### S3Backend (extra `[s3]`; read only when STORAGE points at it) (source: env)
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| S3_ENDPOINT_URL | env | S3/MinIO endpoint URL (None = AWS default). | no | None |
+| S3_PUBLIC_URL | env | public base URL substituted into presigned URLs (split-horizon deployments). | no | None |
+| S3_ACCESS_KEY | env | access key id. | no | None |
+| S3_SECRET_KEY | env | secret access key. | no | None |
+| S3_REGION | env | bucket region. | no | us-east-1 |
+| S3_BUCKET | env | bucket name. | no | stapel-docs |
+| S3_CONNECT_TIMEOUT | env | botocore connect timeout (seconds) — tight on purpose; a fast failure beats a spinner. | no | 5 |
+| S3_READ_TIMEOUT | env | botocore read timeout (seconds). | no | 15 |
+| S3_MAX_ATTEMPTS | env | botocore retry ceiling. | no | 2 |
+
+### Registries & seams (source: env)
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| DOC_TYPES | env | document-type registry overlay merged OVER the txt/md/csv/file builtins ({slug: dotted-path to DocTypeSpec \| None removes}). | no | {} |
+| EXPORTERS | env | export-format registry overlay merged OVER the built-in pdf ({format: dotted-path \| None removes}). | no | {} |
+| INGEST | env | event-driven ingest ({action_name: dotted-path mapper payload → create_document kwargs}); broken entries raise ImproperlyConfigured at wiring. | no | {} |
+
+### Journal / revisions / tree / trash (source: env)
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| REPLAY_WINDOW | env | journal rows with seq ≤ snapshot_seq − window are compacted away (chat-pattern replay window). | no | 500 |
+| AUTO_REVISION_INTERVAL_SECONDS | env | a snapshot save mints an `auto` Revision when the newest revision is older than this (0 = revision on every save). | no | 300 |
+| FOLDER_MAX_DEPTH | env | folder tree depth ceiling (create/move/ingest-path all enforce it). | no | 10 |
+| TRASH_RETENTION_DAYS | env | soft-deleted items become purgeable by `docs_purge_expired` after this many days; purge is irreversible. | no | 30 |
+
+### Sharing axis (closed defaults; v1 system-check guards E010-E014) (source: env)
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| SHARING.MODES | env | additional grant sources over the immutable workspace baseline (subset of whitelist \| link). v1 implements neither — non-empty is a system-check ERROR. | no | [] |
+| SHARING.RESOLVERS | env | {ref_kind: dotted-path} whitelist subject-reference resolvers — real-but-empty seam; entries are import-validated at check time (E014). | no | {} |
+| SHARING.LINK.ANONYMOUS | env | anonymous link redemption. True in v1 = system-check ERROR (E012). | no | false |
+| SHARING.LINK.MAX_LEVEL | env | ceiling for minted link level. Above `view` in v1 = system-check ERROR (E013); `manage` is never grantable by any share source. | no | view |
+| SHARING.LINK.TTL_DAYS | env | link TTL; None (perpetual) only ever by explicit host choice. | no | 30 |

stapel_docs/__init__.py

@@ -0,0 +1,31 @@
+"""stapel-docs — Documents: storage, revisions and per-type editors for the Stapel framework.
+
+Public API (lazily exported, PEP 562 — importing this package never pulls
+in Django or requires configured settings):
+
+- ``docs_settings`` — resolved app settings (``stapel_docs.conf``).
+"""
+
+__all__ = [
+    "docs_settings",
+]
+
+# name -> submodule that defines it. Resolution is deferred until first
+# attribute access so that `import stapel_docs` stays Django-free.
+_LAZY_EXPORTS = {
+    "docs_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_docs/_capabilities.py

@@ -0,0 +1,39 @@
+"""stapel-docs capabilities.json emitter — thin shim over stapel_tools.capabilities."""
+from pathlib import Path
+
+from stapel_tools.capabilities import axis_group_rules, run_capabilities_cli
+
+
+def main(argv=None):
+    from stapel_docs._codegen import _configure
+
+    _configure()
+    from stapel_docs.conf import DEFAULTS
+    from stapel_docs.urls_v1 import GATE_REGISTRY
+
+    # SHARING is the one CTO-facing axis: does the product grant access
+    # beyond the immutable workspace baseline (MODES / LINK.* — closed by
+    # default, v1 system checks E010-E013 refuse opening it before the
+    # mechanism exists). The emitter expresses axes as top-level DEFAULTS
+    # keys only, so the nested MODES/LINK.* knobs surface as ONE composite
+    # SHARING axis (derived kind "enum", default = the closed dict) rather
+    # than per-key axes — honest within the mechanism, detailed in the
+    # curated summary. STORAGE/DOC_TYPES/EXPORTERS/INGEST/SHARING RESOLVERS
+    # are extension seams (curated in docs/capabilities.meta.json);
+    # timeouts, URL lifetimes, REPLAY_WINDOW, AUTO_REVISION_INTERVAL,
+    # FOLDER_MAX_DEPTH, TRASH_RETENTION_DAYS and the S3_* block are tuning
+    # — neither axes nor extension points.
+    return run_capabilities_cli(
+        argv,
+        repo=Path(__file__).resolve().parent,
+        canonical_prefix="/docs/api/v1",
+        defaults=DEFAULTS,
+        registry=GATE_REGISTRY,
+        is_axis=lambda k: k == "SHARING",
+        axis_group=axis_group_rules(exact={"SHARING": "docs.sharing"}),
+        prog="stapel-docs-capabilities",
+    )
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

stapel_docs/_codegen.py

@@ -0,0 +1,143 @@
+"""stapel-docs contract-emission harness (contract-pipeline.md §2-3).
+
+Emits the module's own contract triad into ``docs/`` from a single-module
+``{docs + core}`` Django instance mounted at the canonical ``/docs/api/v1``
+prefix:
+
+  docs/schema.json   drf-spectacular OpenAPI, this module only, canonical prefix
+  docs/flows.json    generate_flow_docs machine artifact — empty here, this
+                     module has no ``@flow_step`` annotations
+  docs/errors.json   generate_error_keys registry (the per-module etalon)
+
+Copied from stapel-recordings' adaptation of the stapel-auth reference
+implementation; the *mechanism* is stapel_tools.codegen (unchanged, shared),
+this file is the thin per-module *config* that wires the module's settings +
+canonical mount into it.
+
+Like recordings, stapel-docs is **not mounted in stapel-example-monolith**
+(grep-confirmed: no route for it in ``svc-app/core/urls.py``), so there is no
+monolith aggregate slice to diff this artifact against for byte-identity.
+Validation is standalone instead — see ``tests/test_contract.py``.
+
+Usage:
+    python -m stapel_docs._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 same way
+    # a flat-layout conftest does (defensively — docs has no colliding
+    # subpackage today, but the guard costs nothing and keeps the harness
+    # identical in shape to auth/profiles/recordings).
+    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_docs._codegen_settings import settings_kwargs
+
+        settings.configure(
+            **settings_kwargs(root_urlconf="stapel_docs.codegen_urls", contract=True)
+        )
+
+    import django
+
+    django.setup()
+
+    # drf-spectacular froze its settings singleton at import time (before this
+    # harness ran configure()), so it is on drf defaults — the same state
+    # every other pair-backend's harness emits under. 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
+    # (operationIds keep the mount segment, docs_api_*), but "/docs/api" in a
+    # single-module harness (which would strip it to bare anonymous names).
+    # Pin it to the aggregate convention so the operationIds match every other
+    # module's harness; SCHEMA_PATH_PREFIX_TRIM stays False (default) so the
+    # path *keys* keep /docs/api/v1/ on both sides.
+    from drf_spectacular.settings import spectacular_settings
+
+    from stapel_docs._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 own dev-only Swagger
+    # URLs (DJANGO_ENV=local) — a *global* registration on drf-spectacular's
+    # extension registry, not tied to any one module's urls.py. stapel-docs
+    # has no co-mounted sibling to trigger it (the profiles finding —
+    # contract-pipeline.md brief), so without registering it explicitly here,
+    # docs' protected endpoints (every view is
+    # ``permission_classes = [IsNotAnonymousUser]``) would emit without their
+    # `security: [{"JWTCookieAuth": []}]` 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's rendering of component descriptions (``Optional[X]`` vs
+    ``X | None``) depends on the Python **minor** version — contracts emitted
+    on anything other than 3.12 (the CI/monolith pin) produce false diffs
+    against the committed docs/*.json. Emission must never proceed on the
+    wrong minor.
+    """
+    if sys.version_info[:2] != (3, 12):
+        got = f"{sys.version_info.major}.{sys.version_info.minor}"
+        raise SystemExit(
+            f"stapel-docs contract emission ABORTED: running Python {got}, "
+            "but contracts must be emitted on Python 3.12 (the CI/monolith "
+            "pin). drf-spectacular renders component descriptions "
+            "(Optional[X] vs X | None) differently across Python minor "
+            "versions, so emitting on any other minor produces false diffs "
+            "against the committed docs/*.json. Re-run under a 3.12 "
+            "interpreter."
+        )
+
+
+def main(argv: list[str] | None = None) -> int:
+    _require_python_312()
+
+    parser = argparse.ArgumentParser(
+        prog="stapel-docs-contract",
+        description="Emit this module's contract triad (schema.json + flows.json "
+        "+ errors.json) into --out, canonical /docs/api/v1 prefix.",
+    )
+    parser.add_argument(
+        "--out",
+        default="docs",
+        help="Output directory for the triad (default: docs).",
+    )
+    args = parser.parse_args(argv)
+
+    _configure()
+
+    # Reuse the shared mechanism's byte-stable emitters (contract-pipeline.md §2:
+    # "the single-module harness already exists").
+    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-docs contract: {paths} paths, {flows} flows, {errors} error keys "
+        f"→ {out}/",
+        file=sys.stderr,
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

stapel_docs/_codegen_settings.py

@@ -0,0 +1,132 @@
+"""Single-module Django settings for stapel-docs's contract harness.
+
+The ``settings.configure(...)`` block for:
+
+  - the contract-emission harness (``_codegen.py`` / ``make contract``) —
+    mounts docs on its *canonical* public prefix
+    (``stapel_docs.codegen_urls`` → ``docs/`` — the module's own ``urls.py``
+    bakes the ``api/v1`` segment in, so the full canonical prefix is
+    ``/docs/api/v1``) and enables drf-spectacular, so the emitted
+    ``schema.json`` / ``flows.json`` paths match the module's documented
+    mount recipe (``urls.py``: ``path("docs/", include("stapel_docs.urls"))``)
+    (contract-pipeline.md §2); and
+  - the capabilities emitter (``_capabilities.py``), which reuses
+    ``_codegen._configure``.
+
+Shape copied from stapel-recordings' harness (itself from the stapel-auth
+etalon via stapel-profiles). One deliberate deviation from the recordings
+mold: ``conftest.py`` keeps its historical inline ``settings.configure``
+block instead of importing :func:`settings_kwargs` — the conftest belongs to
+the test workstream, and folding it in here is its call. Until then this
+file MIRRORS the conftest config (INSTALLED_APPS / comm / migrations) with
+only the contract-required additions:
+
+  - ``stapel_core.django.apps.CommonDjangoConfig`` + ``drf_spectacular`` —
+    the conftest predates contract emission and carries neither;
+    ``CommonDjangoConfig`` supplies the ``generate_flow_docs`` /
+    ``generate_error_keys`` management commands the codegen harness calls;
+  - ``contract=True`` swaps in the *production* ``REST_FRAMEWORK`` (the
+    canonical stapel-core config, inlined as plain dotted paths — importing
+    it would trip the same chicken-and-egg as spectacular). This matters for
+    byte-identity: a real deployment emits with
+    ``DEFAULT_SCHEMA_CLASS=PermissionAwareAutoSchema`` and the real
+    permission/renderer classes, and DRF caches ``REST_FRAMEWORK`` on first
+    access, so it must be right at ``configure()`` time.
+
+``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 same
+state every other pair-backend's harness emits under. The one knob that
+still must be forced, ``SCHEMA_PATH_PREFIX``, is patched on the singleton
+directly by the harness (see ``_codegen._configure``).
+"""
+from __future__ import annotations
+
+
+def settings_kwargs(
+    *,
+    root_urlconf: str = "stapel_docs.tests.urls",
+    contract: bool = False,
+) -> dict:
+    """Return the ``settings.configure(**kwargs)`` for a single-module docs
+    instance. ``root_urlconf`` selects the mount: bare
+    (``stapel_docs.tests.urls``) mirrors the test layout, canonical-prefix
+    (``stapel_docs.codegen_urls`` → ``docs/``) is what contract emission
+    uses."""
+    if contract:
+        # Mirror stapel_core.django.settings.REST_FRAMEWORK exactly (the
+        # config a real deployment emits under; auth/profiles/recordings
+        # inline the same block). 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.messages",
+            "stapel_core.django.apps.CommonDjangoConfig",
+            "stapel_core.django.users",
+            "rest_framework",
+            "drf_spectacular",
+            "stapel_docs",
+        ],
+        AUTH_USER_MODEL="users.User",
+        DATABASES={
+            "default": {
+                "ENGINE": "django.db.backends.sqlite3",
+                "NAME": ":memory:",
+            }
+        },
+        DEFAULT_AUTO_FIELD="django.db.models.BigAutoField",
+        USE_TZ=True,
+        ROOT_URLCONF=root_urlconf,
+        CACHES={
+            "default": {
+                "BACKEND": "django.core.cache.backends.locmem.LocMemCache",
+            }
+        },
+        # Same comm shape as the conftest: synchronous in-process comm with
+        # schema validation ON. Schema emission never executes an action or
+        # Function, so this only needs to be present, not exercised.
+        STAPEL_BUS_BACKEND="stapel_core.bus.backends.memory.MemoryBus",
+        STAPEL_COMM={
+            "OUTBOX_ENABLED": False,
+            "ACTION_TRANSPORT": "inprocess",
+            "VALIDATE_SCHEMAS": True,
+        },
+        MIGRATION_MODULES={
+            "users": None,
+            "docs": 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 drf-spectacular settings singleton by the harness so a single-module
+# instance derives the same operationIds (see _codegen._configure). Uniform
+# across all pair-backends (contract-pipeline.md §2).
+CODEGEN_SCHEMA_PATH_PREFIX = "/"

stapel_docs/actions.py

@@ -0,0 +1,100 @@
+"""Action subscriptions of stapel-docs.
+
+Handlers are idempotent-minded (delivery is at-least-once — outbox retries,
+broker redelivery). Transport is chosen by ``STAPEL_COMM`` (in-process in a
+monolith, bus consumer in microservices); the handler code is identical.
+
+Two consumers live here:
+
+- ``user.deleted`` → the GDPR provider's erasure (anonymize authorship,
+  never destroy surviving workspace content — storage-verdict §3);
+- the INGEST seam (design §2/§6): ``STAPEL_DOCS["INGEST"]`` maps
+  ``{action_name: dotted-path mapper}`` so a host gets event-driven ingest
+  without writing a subscriber. Docs never learns a foreign event schema —
+  the mapper (host code) turns the payload into ``create_document`` kwargs.
+"""
+import logging
+from typing import Callable
+
+from django.core.exceptions import ImproperlyConfigured
+from stapel_core.comm import on_action, subscribe_action
+
+logger = logging.getLogger(__name__)
+
+
+@on_action("user.deleted")
+def handle_user_deleted(event):
+    """Erase a user's docs slice (GDPR Art. 17). Anonymize semantics: the
+    provider nulls authorship and keeps documents (idempotent — a nulled
+    row nulls to itself on redelivery)."""
+    from .gdpr import DocsGDPRProvider
+
+    user_id = event.payload.get("user_id")
+    if not user_id:
+        logger.error("user.deleted event without user_id: %s", event.event_id)
+        return
+    DocsGDPRProvider().delete(user_id)
+    logger.info("docs authorship anonymized for deleted user %s", user_id)
+
+
+# ─── INGEST seam ─────────────────────────────────────────────────────
+
+#: action name -> resolved mapper. Rebuilt atomically by :func:`wire_ingest`;
+#: the single dispatcher below reads it at delivery time, so re-wiring
+#: (tests, settings overlays) never stacks duplicate subscriptions.
+_INGEST_MAPPERS: dict[str, Callable[[dict], dict]] = {}
+
+
+def wire_ingest() -> None:
+    """Resolve ``STAPEL_DOCS["INGEST"]`` and subscribe the dispatcher.
+
+    Called from ``apps.py:ready()``; tests re-call it after overriding
+    settings. Configured-but-broken must not be silent (system-check
+    failure genre): an unimportable or non-callable mapper raises
+    :class:`ImproperlyConfigured` instead of a log-and-skip.
+    """
+    from django.utils.module_loading import import_string
+
+    from .conf import docs_settings
+
+    resolved: dict[str, Callable[[dict], dict]] = {}
+    for action_name, dotted in (docs_settings.INGEST or {}).items():
+        try:
+            mapper = import_string(dotted)
+        except ImportError as exc:
+            raise ImproperlyConfigured(
+                f"STAPEL_DOCS['INGEST'][{action_name!r}] = {dotted!r} cannot be imported"
+            ) from exc
+        if not callable(mapper):
+            raise ImproperlyConfigured(
+                f"STAPEL_DOCS['INGEST'][{action_name!r}] = {dotted!r} is not callable"
+            )
+        resolved[action_name] = mapper
+
+    _INGEST_MAPPERS.clear()
+    _INGEST_MAPPERS.update(resolved)
+    for action_name in resolved:
+        # subscribe() dedups an identical handler — re-wiring is safe.
+        subscribe_action(action_name, _handle_ingest)
+
+
+def _handle_ingest(event):
+    """Route a configured host action into a document.
+
+    Delivery is at-least-once; create is not naturally idempotent, so
+    dedup (e.g. an idempotency key in metadata) is the mapper/host's call —
+    same contract as any bus consumer creating rows.
+    """
+    mapper = _INGEST_MAPPERS.get(event.event_type)
+    if mapper is None:
+        # Stale subscription: a re-wire dropped this action (there is no
+        # unsubscribe in the registry) — inert by design.
+        return
+    kwargs = mapper(event.payload)
+
+    from . import services  # lazy: mirror functions.py
+
+    services.create_document(**kwargs)
+
+
+__all__ = ["handle_user_deleted", "wire_ingest"]

stapel_docs/admin.py

@@ -0,0 +1,53 @@
+"""Admin for stapel-docs.
+
+Read-only across the board: every row here is workspace content or write
+machinery with no staff add/change/delete workflow — mutations go through
+the API (where authorize() and the outbox emits live), never the admin.
+"""
+from django.contrib import admin
+
+from .models import Document, DocumentUpdate, Folder, Revision, UploadSession
+
+
+class _ReadOnlyAdmin(admin.ModelAdmin):
+    def has_add_permission(self, request):
+        return False
+
+    def has_change_permission(self, request, obj=None):
+        return False
+
+    def has_delete_permission(self, request, obj=None):
+        return False
+
+
+@admin.register(Folder)
+class FolderAdmin(_ReadOnlyAdmin):
+    list_display = ("id", "name", "workspace_id", "parent", "deleted_at", "created_at")
+    search_fields = ("id", "name", "workspace_id")
+
+
+@admin.register(Document)
+class DocumentAdmin(_ReadOnlyAdmin):
+    list_display = (
+        "id", "title", "type", "workspace_id", "head_seq", "size_bytes",
+        "deleted_at", "created_at",
+    )
+    list_filter = ("type",)
+    search_fields = ("id", "title", "workspace_id")
+
+
+@admin.register(DocumentUpdate)
+class DocumentUpdateAdmin(_ReadOnlyAdmin):
+    list_display = ("id", "document", "seq", "author_id", "created_at")
+
+
+@admin.register(Revision)
+class RevisionAdmin(_ReadOnlyAdmin):
+    list_display = ("id", "document", "seq", "kind", "name", "size_bytes", "created_at")
+    list_filter = ("kind",)
+
+
+@admin.register(UploadSession)
+class UploadSessionAdmin(_ReadOnlyAdmin):
+    list_display = ("id", "title", "workspace_id", "state", "size_bytes", "created_at")
+    list_filter = ("state",)

stapel_docs/apps.py

@@ -0,0 +1,30 @@
+from django.apps import AppConfig
+
+
+class DocsConfig(AppConfig):
+    name = "stapel_docs"
+    label = "docs"
+    verbose_name = "Documents: storage, revisions and per-type editors"
+    default_auto_field = "django.db.models.BigAutoField"
+
+    def ready(self):
+        # Import-time side effects: comm functions/actions, system checks,
+        # error-key registration. Keep each in its own module.
+        from . import checks  # noqa: F401
+        from . import errors  # noqa: F401
+        from . import functions  # noqa: F401
+
+        # Action subscriptions (in-process in a monolith, bus consumer in
+        # microservices — same code, transport chosen by STAPEL_COMM):
+        # user.deleted consumer + the INGEST seam.
+        from . import actions
+
+        actions.wire_ingest()
+
+        # GDPR provider registration (monolith mode).
+        from stapel_core.gdpr import gdpr_registry
+
+        from .gdpr import DocsGDPRProvider
+
+        if DocsGDPRProvider().section not in gdpr_registry.sections:
+            gdpr_registry.register(DocsGDPRProvider())