feat(N1): Scope-Registry via Contract — workspace_scopes() Deklarationen + /scope-definitions Endpoint (#365)

- workspace_scopes() Contract-Hook (document_placeholders-Muster): Plugins deklarieren Scope-Dimensionen inkl. Wertequellen
- Deklarationen: contacts (Ordner/Typen/Saved-View), dms (Ordner/Datei-Typen), mail (Postfächer), calendar (Kalender/Standard-Ansicht)
- Pydantic fail-closed (schemas/workspace.py): ScopeOption, ScopeValueSource (nur interne /api/v1-Pfade, SSRF-sicher), WorkspaceScopeDimension, WorkspaceModuleScopes
- Aggregator workspace_scope_service.py: discovered-Plugins, ARCH-014-safe, Crash-sicher, ungültige Deklarationen verworfen
- GET /api/v1/workspaces/scope-definitions (workspaces:configure_modules) vor /{workspace_id} registriert
- Security-Invariante: Scope = reine UND-Einschränkung (Workspace ∧ RLS ∧ ABAC ∧ Permissions)
- Tests: 18/18 neu (TDD rot→grün), Regression 17/17, Checker 0 Verstöße, Ruff clean
- Doku: api-documentation.md Workspaces-Sektion, PROGRESS.md Phase N1

app/services/workspace_scope_service.py

@@ -0,0 +1,83 @@
+"""Workspace-Scope-Registry aggregation (Phase N1, Roadmap Phase N).
+
+Plugins declare the scope dimensions their modules support via the contract
+hook ``workspace_scopes()`` — same aggregation pattern as
+``document_placeholders()`` (#359 philosophy): the module owns its domain,
+the generic consumer stays module-agnostic.
+
+The N2 workspace editor renders filter UI from these definitions; scope
+VALUES are stored per workspace in ``workspace_modules.config`` (JSONB).
+N3 list filtering applies them as pure AND-restrictions.
+
+Security-Invariante (Phase N): a workspace can never GRANT visibility —
+effective visibility is always Workspace-Scope ∧ RLS ∧ ABAC ∧ Permissions.
+Without an active workspace there is no filter (backward compatible).
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from pydantic import ValidationError
+
+from app.schemas.workspace import WorkspaceModuleScopes
+
+logger = logging.getLogger(__name__)
+
+
+def _parse_contribution(plugin_name: str, contribution: Any) -> WorkspaceModuleScopes | None:
+    """Validate a single raw contribution; ``None`` when invalid (fail-closed).
+
+    Every declaration must pass the Pydantic schema — invalid dimensions
+    (e.g. a multiselect without options AND value_source) are dropped with a
+    warning instead of breaking the editor endpoint.
+    """
+    if not isinstance(contribution, dict):
+        return None
+    try:
+        return WorkspaceModuleScopes.model_validate(contribution)
+    except ValidationError as exc:
+        logger.warning(
+            "Invalid workspace_scopes contribution from plugin '%s': %s",
+            plugin_name,
+            exc,
+        )
+        return None
+
+
+def get_scope_definitions() -> dict[str, list[dict[str, Any]]]:
+    """Aggregate ``workspace_scopes()`` contributions from all discovered plugins.
+
+    Returns ``module_key -> [dimension, ...]`` for the N2 editor. Contracts
+    of explicitly deactivated plugins stay gone (ARCH-014 unregister marker);
+    never-loaded contracts lazy-load on first access (document_placeholders
+    precedent). A plugin crash while declaring scopes never fails the
+    endpoint — its contribution is simply skipped.
+    """
+    from app.plugins.builtins.contracts import get_contract_registry
+    from app.plugins.registry import get_registry
+
+    modules: dict[str, list[dict[str, Any]]] = {}
+    for plugin_name in get_registry().list_discovered():
+        contract = get_contract_registry().get_contract(plugin_name)
+        if contract is None:
+            continue
+        fn = getattr(contract, "workspace_scopes", None)
+        if fn is None:
+            continue
+        try:
+            contributions = fn() or []
+        except Exception:  # noqa: BLE001
+            logger.exception(
+                "workspace_scopes() raised for plugin '%s' — skipping", plugin_name
+            )
+            continue
+        for contribution in contributions:
+            parsed = _parse_contribution(plugin_name, contribution)
+            if parsed is None:
+                continue
+            modules.setdefault(parsed.module_key, []).extend(
+                dimension.model_dump() for dimension in parsed.dimensions
+            )
+    return modules