simple-module-core 0.0.36__tar.gz → 0.0.37__tar.gz

{simple_module_core-0.0.36 → simple_module_core-0.0.37}/.gitignore

@@ -64,3 +64,4 @@ host/client_app/.playwright-cli/*
 .superpowers/
 .qa/
 .verify/
+/openapi.json

{simple_module_core-0.0.36 → simple_module_core-0.0.37}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: simple_module_core
-Version: 0.0.36
+Version: 0.0.37
 Summary: Module-system primitives for the simple_module framework — ModuleBase, discovery, diagnostics, events
 Project-URL: Homepage, https://github.com/antosubash/simple_module_python
 Project-URL: Repository, https://github.com/antosubash/simple_module_python

{simple_module_core-0.0.36 → simple_module_core-0.0.37}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simple_module_core"
-version = "0.0.36"
+version = "0.0.37"
 description = "Module-system primitives for the simple_module framework — ModuleBase, discovery, diagnostics, events"
 readme = "README.md"
 license = "MIT"

{simple_module_core-0.0.36 → simple_module_core-0.0.37}/simple_module_core/__init__.py

@@ -18,6 +18,11 @@ from simple_module_core.discovery import (
     select_auth_provider,
     topological_sort,
 )
+from simple_module_core.durable_events import (
+    DurableContext,
+    DurableDeliveryUnavailable,
+    DurableTransport,
+)
 from simple_module_core.events import Event, EventBus
 from simple_module_core.exceptions import (
     CircularDependencyError,
@@ -64,6 +69,9 @@ __all__ = [
     "DesignPack",
     "DesignPackRegistry",
     "DiagnosticLevel",
+    "DurableContext",
+    "DurableDeliveryUnavailable",
+    "DurableTransport",
     "Event",
     "EventBus",
     "FeatureFlagDefinition",

simple_module_core-0.0.37/simple_module_core/diagnostics/_db_extensions.py

@@ -0,0 +1,39 @@
+"""Database-extension diagnostics (SM029).
+
+A module that declares ``db_extensions`` needs Postgres: SQLite has no
+extensions, so ``ensure_db_extensions`` refuses to run there. SM029 says so
+up front instead of at the first ``alembic upgrade``.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from simple_module_core.diagnostics._types import Diagnostic, DiagnosticLevel
+
+if TYPE_CHECKING:
+    from simple_module_core.module import ModuleBase
+
+
+def check_db_extensions_need_postgres(mod: ModuleBase, dialect: str | None) -> list[Diagnostic]:
+    """SM029: INFO when ``mod`` declares extensions and the database is SQLite."""
+    if dialect != "sqlite":
+        return []
+    extensions = mod.db_extensions()
+    if not extensions:
+        return []
+    return [
+        Diagnostic(
+            level=DiagnosticLevel.INFO,
+            code="SM029",
+            message=(
+                f"Module declares Postgres extensions ({', '.join(extensions)}) but the "
+                "database is SQLite; migrations will refuse to run until it is Postgres"
+            ),
+            module_name=mod.meta.name,
+            suggestion="Point SM_DATABASE_URL at Postgres (see .env.example)",
+        )
+    ]
+
+
+__all__ = ["check_db_extensions_need_postgres"]

simple_module_core-0.0.37/simple_module_core/diagnostics/_heavy_task_imports.py

@@ -0,0 +1,93 @@
+"""SM028: flag a ``tasks.py`` that imports a heavy package at module level.
+
+Celery imports every installed module's ``tasks.py`` in each process that
+loads the module (the web app, every worker, beat). A top-level
+``import torch`` there makes all of them pay for it, and defeats the per-worker
+subset (``SM_BG_TASKS_WORKER_QUEUES`` / ``include_modules``), which exists so a
+light worker never imports the heavy one. Import the package inside the task
+body instead. Uses ``ast`` and never imports the module being checked.
+"""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from simple_module_core.diagnostics._types import Diagnostic, DiagnosticLevel
+
+if TYPE_CHECKING:
+    from simple_module_core.module import ModuleBase
+
+HEAVY_PACKAGES = frozenset(
+    {"torch", "tensorflow", "ultralytics", "osgeo", "rasterio", "cv2", "sklearn"}
+)
+
+
+def _heavy_roots(node: ast.stmt) -> list[str]:
+    if isinstance(node, ast.Import):
+        names = [alias.name for alias in node.names]
+    elif isinstance(node, ast.ImportFrom) and node.level == 0 and node.module:
+        names = [node.module]
+    else:
+        return []
+    return [n.split(".", 1)[0] for n in names if n.split(".", 1)[0] in HEAVY_PACKAGES]
+
+
+def _top_level_statements(body: list[ast.stmt]) -> list[ast.stmt]:
+    """Statements that run at import time, descending into ``if``/``try``/``with``.
+
+    Function and class bodies are skipped: an import there is deferred, which is
+    the fix. ``if TYPE_CHECKING:`` blocks are skipped too — never executed.
+    """
+    out: list[ast.stmt] = []
+    for node in body:
+        out.append(node)
+        if isinstance(node, ast.If):
+            test = ast.unparse(node.test)
+            if test in ("TYPE_CHECKING", "typing.TYPE_CHECKING"):
+                out.extend(_top_level_statements(node.orelse))
+                continue
+            out.extend(_top_level_statements(node.body + node.orelse))
+        elif isinstance(node, ast.Try):
+            out.extend(
+                _top_level_statements(
+                    node.body + [s for h in node.handlers for s in h.body] + node.orelse
+                )
+            )
+        elif isinstance(node, ast.With):
+            out.extend(_top_level_statements(node.body))
+    return out
+
+
+def check_heavy_task_imports(mod: ModuleBase, src_dir: Path) -> list[Diagnostic]:
+    """Warn when ``tasks.py`` imports a heavy package outside a function."""
+    tasks_py = src_dir / "tasks.py"
+    if not tasks_py.is_file():
+        return []
+    try:
+        tree = ast.parse(tasks_py.read_text(), filename=str(tasks_py))
+    except (OSError, SyntaxError):
+        return []
+
+    diags: list[Diagnostic] = []
+    for node in _top_level_statements(tree.body):
+        for root in _heavy_roots(node):
+            diags.append(
+                Diagnostic(
+                    level=DiagnosticLevel.WARNING,
+                    code="SM028",
+                    message=(
+                        f"tasks.py imports heavy package '{root}' at module level — every "
+                        "process that loads this module's tasks pays for it"
+                    ),
+                    module_name=mod.meta.name,
+                    file=f"{tasks_py}:{node.lineno}",
+                    suggestion=(
+                        f"Move `import {root}` inside the task function, so only a worker "
+                        "that actually runs the task loads it (and a queue-restricted "
+                        "worker never does)."
+                    ),
+                )
+            )
+    return diags

{simple_module_core-0.0.36 → simple_module_core-0.0.37}/simple_module_core/diagnostics/_module.py

@@ -8,6 +8,7 @@ from typing import TYPE_CHECKING
 
 from simple_module_core.diagnostics._coupling import check_framework_module_coupling
 from simple_module_core.diagnostics._css import check_module_css
+from simple_module_core.diagnostics._heavy_task_imports import check_heavy_task_imports
 from simple_module_core.diagnostics._inertia_api import check_inertia_api_calls
 from simple_module_core.diagnostics._js_workspace import check_js_workspace_files
 from simple_module_core.diagnostics._pages import check_pages, find_render_calls
@@ -42,6 +43,7 @@ class ModuleDiagnostics:
                 diagnostics.extend(check_js_workspace_files(mod, src_dir))
                 diagnostics.extend(check_inertia_api_calls(mod, src_dir))
                 diagnostics.extend(check_module_css(mod, src_dir))
+                diagnostics.extend(check_heavy_task_imports(mod, src_dir))
 
         return diagnostics
 
@@ -109,6 +111,7 @@ class ModuleDiagnostics:
                     "template_dirs",
                     "static_mounts",
                     "locale_dirs",
+                    "db_extensions",
                     "on_startup",
                     "on_shutdown",
                 )

{simple_module_core-0.0.36 → simple_module_core-0.0.37}/simple_module_core/diagnostics/_runner.py

@@ -7,6 +7,7 @@ import sys
 from pathlib import Path
 from typing import TYPE_CHECKING
 
+from simple_module_core.diagnostics._db_extensions import check_db_extensions_need_postgres
 from simple_module_core.diagnostics._expression_index import (
     check_expression_indexes_unverifiable,
     module_all_tables,
@@ -42,7 +43,8 @@ def run_diagnostics(
     :class:`I18nDiagnostics`). ``i18n_extra_sources`` lets callers include
     host/ui locale dirs that aren't owned by a ``ModuleBase``.
     ``database_dialect`` (``"sqlite"``, ``"postgresql"``...) enables SM026, which
-    flags expression indexes a SQLite database cannot verify.
+    flags expression indexes a SQLite database cannot verify, and SM029, which flags
+    modules declaring ``db_extensions`` on SQLite.
     ``i18n_unknown_overrides`` (``I18nRegistry.unknown_override_keys``) enables SM027.
     """
     diagnostics = ModuleDiagnostics().run(modules)
@@ -54,6 +56,7 @@ def run_diagnostics(
                     module_all_tables(mod), database_dialect, mod.meta.name
                 )
             )
+            diagnostics.extend(check_db_extensions_need_postgres(mod, database_dialect))
 
     if i18n_default_locale:
         from simple_module_core.diagnostics._i18n import I18nDiagnostics

simple_module_core-0.0.37/simple_module_core/durable_events.py

@@ -0,0 +1,188 @@
+"""Durable (at-least-once, cross-process) event delivery primitives.
+
+``EventBus.publish`` is in-process and forgets an event the moment the process
+dies. A *durable* subscription is delivered by a transport instead: the event is
+written to an outbox in the publisher's own transaction and a worker runs the
+handler later, retrying until it succeeds. The framework only defines the
+contract — the subscription registry, the event (de)serialisation and the
+transport protocol. ``background_tasks`` ships the transport.
+
+Handlers are called as ``await handler(event, ctx)`` where ``ctx`` is a
+:class:`DurableContext`. Delivery is at-least-once; a handler that writes only
+through ``ctx.db`` gets exactly-once *database* effects, because the transport
+commits that session in the same transaction that marks the delivery done. The
+handler must therefore not commit ``ctx.db`` itself (the ``background_tasks``
+transport refuses it), and anything it does outside ``ctx.db`` is
+at-least-once and must be idempotent.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Awaitable, Callable, Sequence
+from dataclasses import dataclass
+from functools import cache
+from typing import Any, Protocol, runtime_checkable
+
+from pydantic import TypeAdapter
+
+logger = logging.getLogger(__name__)
+
+# Width of the outbox's ``event_key`` / ``handler_name`` columns. Checked at
+# subscribe time so an over-long name fails at boot, not on a publisher's flush.
+MAX_NAME_LENGTH = 255
+
+
+class DurableDeliveryUnavailable(RuntimeError):  # noqa: N818 - name fixed by the design
+    """``publish_durable`` was called but no durable transport is installed.
+
+    Durable delivery needs an outbox and a worker; the ``background_tasks``
+    module installs both. Raised instead of silently degrading to in-process
+    delivery, which would drop the guarantee the caller asked for.
+    """
+
+
+@dataclass(frozen=True)
+class DurableContext:
+    """What a durable handler receives next to the event.
+
+    ``db`` is an ``AsyncSession`` the transport commits together with marking
+    the delivery done — write through it (flush, never commit) and the effect
+    lands exactly once.
+    ``attempt`` is 1 on the first delivery and grows on each retry.
+    """
+
+    db: Any
+    attempt: int
+
+
+type DurableHandler = Callable[[Any, DurableContext], Awaitable[None]]
+
+
+@runtime_checkable
+class DurableTransport(Protocol):
+    """Persists an event for later delivery to the named durable handlers.
+
+    ``enqueue`` must write in *db*'s transaction, so that a rollback of the
+    publisher's transaction also discards the event.
+    """
+
+    async def enqueue(self, event: Any, handler_names: Sequence[str], db: Any) -> None: ...
+
+
+@dataclass(frozen=True)
+class DurableSubscription:
+    event_type: type
+    name: str
+    handler: DurableHandler
+
+
+def event_key(event_type: type) -> str:
+    """The stable wire name of an event type (same key ``EventBus`` uses)."""
+    return f"{event_type.__module__}.{event_type.__qualname__}"
+
+
+def handler_name(handler: Callable[..., Any]) -> str:
+    """Default durable name: the handler's import path."""
+    module = getattr(handler, "__module__", None) or "unknown"
+    qualname = getattr(handler, "__qualname__", None) or repr(handler)
+    return f"{module}.{qualname}"
+
+
+@cache
+def _adapter(event_type: type) -> TypeAdapter[Any]:
+    return TypeAdapter(event_type)
+
+
+def check_serializable(event_type: type) -> None:
+    """Fail fast at subscribe time if *event_type* cannot travel as JSON.
+
+    The class itself must be decorated with ``@dataclass``: a bare subclass of
+    one inherits ``is_dataclass`` but silently drops its own annotated fields.
+    """
+    if not (isinstance(event_type, type) and "__dataclass_fields__" in vars(event_type)):
+        raise TypeError(f"Durable events must be @dataclass classes; got {event_type!r}")
+    try:
+        adapter = _adapter(event_type)
+        if not getattr(adapter, "pydantic_complete", True):
+            # An annotation pydantic could not resolve (a forward reference to
+            # a name not importable from the event's module).
+            adapter.rebuild(raise_errors=True)
+    except Exception as exc:
+        raise TypeError(
+            f"Event {event_key(event_type)} cannot be serialised for durable delivery: {exc}"
+        ) from exc
+
+
+def serialize_event(event: Any) -> dict[str, Any]:
+    """Event → JSON-compatible dict. UUID, datetime, Enum, Decimal and nested
+    dataclasses become their JSON forms."""
+    check_serializable(type(event))
+    return _adapter(type(event)).dump_python(event, mode="json")
+
+
+def deserialize_event(event_type: type, payload: dict[str, Any]) -> Any:
+    """JSON dict → an instance of *event_type* (inverse of :func:`serialize_event`)."""
+    return _adapter(event_type).validate_python(payload)
+
+
+class DurableRegistry:
+    """Durable subscriptions of one ``EventBus``, keyed by (event key, name)."""
+
+    def __init__(self) -> None:
+        self._subs: dict[str, dict[str, DurableSubscription]] = {}
+        self._types: dict[str, type] = {}
+
+    def add(self, event_type: type, handler: DurableHandler, name: str | None) -> str:
+        if not callable(handler):
+            raise TypeError("Durable handler must be callable")
+        check_serializable(event_type)
+        key = event_key(event_type)
+        resolved = name or handler_name(handler)
+        if len(resolved) > MAX_NAME_LENGTH or len(key) > MAX_NAME_LENGTH:
+            raise ValueError(
+                f"Durable names are limited to {MAX_NAME_LENGTH} characters; "
+                f"pass a shorter name= (got {resolved!r} for {key})"
+            )
+        if name is None and ("<lambda>" in resolved or "<locals>" in resolved):
+            logger.warning(
+                "Durable handler %s has an unstable default name; pass name= so "
+                "undelivered rows survive a refactor",
+                resolved,
+            )
+        by_name = self._subs.setdefault(key, {})
+        existing = by_name.get(resolved)
+        if existing is not None and existing.handler != handler:
+            raise ValueError(
+                f"Durable handler name {resolved!r} is already subscribed to {key}; "
+                "pass a distinct name="
+            )
+        by_name[resolved] = DurableSubscription(event_type, resolved, handler)
+        self._types[key] = event_type
+        return resolved
+
+    def handler_names(self, event_type: type) -> list[str]:
+        return list(self._subs.get(event_key(event_type), {}))
+
+    def lookup(self, key: str, name: str) -> DurableSubscription | None:
+        return self._subs.get(key, {}).get(name)
+
+    def event_type(self, key: str) -> type | None:
+        return self._types.get(key)
+
+    def __len__(self) -> int:
+        return sum(len(v) for v in self._subs.values())
+
+
+__all__ = [
+    "DurableContext",
+    "DurableDeliveryUnavailable",
+    "DurableHandler",
+    "DurableRegistry",
+    "DurableSubscription",
+    "DurableTransport",
+    "deserialize_event",
+    "event_key",
+    "handler_name",
+    "serialize_event",
+]

{simple_module_core-0.0.36 → simple_module_core-0.0.37}/simple_module_core/events.py

@@ -10,6 +10,13 @@ from typing import Any
 
 from pyee.asyncio import AsyncIOEventEmitter
 
+from simple_module_core.durable_events import (
+    DurableDeliveryUnavailable,
+    DurableHandler,
+    DurableRegistry,
+    DurableTransport,
+)
+
 logger = logging.getLogger(__name__)
 
 EventHandler = Callable[..., Coroutine[Any, Any, None]]
@@ -36,11 +43,17 @@ class EventBus:
 
     * ``publish``      — awaits all handlers via ``asyncio.gather`` (error-isolated).
     * ``publish_nowait`` — fire-and-forget via pyee's event-loop scheduling.
+    * ``publish_durable`` — written to an outbox in the caller's transaction and
+      delivered at-least-once by the installed :class:`DurableTransport`
+      (``background_tasks``) to handlers registered with ``subscribe_durable``.
     """
 
     def __init__(self) -> None:
         self._emitter = AsyncIOEventEmitter()
         self._emitter.on("error", self._on_emitter_error)
+        self.durable = DurableRegistry()
+        # Installed by the module that owns the outbox (background_tasks).
+        self.durable_transport: DurableTransport | None = None
 
     @staticmethod
     def _on_emitter_error(error: Exception) -> None:
@@ -89,3 +102,40 @@ class EventBus:
         handlers as tasks on the running loop.
         """
         self._emitter.emit(self._event_key(type(event)), event)
+
+    def subscribe_durable(
+        self, event_type: type[Event], handler: DurableHandler, *, name: str | None = None
+    ) -> str:
+        """Register a durable handler, called as ``await handler(event, ctx)``.
+
+        *name* defaults to the handler's import path. Delivery state is keyed by
+        it, so it must stay stable across deploys: renaming a handler strands
+        its undelivered rows (they retry as "unknown handler", then go
+        ``dead``). Returns the resolved name.
+
+        Durable subscriptions are also built in the worker, which calls
+        ``register_event_handlers(bus, None)`` — register them before any
+        ``if app is None: return``.
+        """
+        resolved = self.durable.add(event_type, handler, name)
+        logger.debug("Durable subscription %s on %s", resolved, event_type.__name__)
+        return resolved
+
+    async def publish_durable(self, event: Event, db: Any) -> None:
+        """Persist *event* for every durable handler in *db*'s transaction.
+
+        Nothing is delivered unless that transaction commits. In-process
+        ``subscribe`` handlers are **not** called; publish separately if you
+        want both. Raises :class:`DurableDeliveryUnavailable` when no transport
+        is installed (``background_tasks`` not installed or not started).
+        """
+        transport = self.durable_transport
+        if transport is None:
+            raise DurableDeliveryUnavailable(
+                f"Cannot publish {type(event).__name__} durably: no durable transport "
+                "is installed. Install and enable the background_tasks module."
+            )
+        names = self.durable.handler_names(type(event))
+        if not names:
+            return
+        await transport.enqueue(event, names, db)

{simple_module_core-0.0.36 → simple_module_core-0.0.37}/simple_module_core/module.py

@@ -234,15 +234,11 @@ class ModuleBase(ABC):
         """Add middleware to the application.
 
         Called after core middleware (session, security headers) positioning
-        is established but before the app starts.  Modules that need to
-        inject middleware (e.g. auth) override this method.
+        is established but before the app starts.
         """
 
     def register_exception_handlers(self, app: FastAPI) -> None:
-        """Register custom exception handlers on the application.
-
-        Called after framework exception handlers are set up.
-        """
+        """Register custom exception handlers (after the framework's own)."""
 
     # ── Asset contribution (templates & static files) ─────────
 
@@ -253,19 +249,15 @@ class ModuleBase(ABC):
         Jinja2 loader, so templates in ``<module>/templates/`` become resolvable
         from any module. Return an empty list (default) to contribute none.
 
-        Each path is typically computed via
-        ``importlib.resources.files(__package__) / "templates"`` so it resolves
-        correctly when the module is installed as a PyPI package.
+        Typically ``importlib.resources.files(__package__) / "templates"``.
         """
         return []
 
     def static_mounts(self) -> dict[str, Path]:
         """Return static file mounts this module contributes.
 
-        Mapping of URL prefix → filesystem directory. The host mounts each entry
-        via ``StaticFiles`` during app boot. Convention: prefix with
-        ``/modules/<name>/static`` to avoid collisions with the host's own
-        ``/static`` mount. Return an empty dict (default) to contribute none.
+        Mapping of URL prefix → directory, mounted via ``StaticFiles`` at boot.
+        Convention: prefix with ``/modules/<name>/static``. Default: none.
         """
         return {}
 
@@ -287,6 +279,14 @@ class ModuleBase(ABC):
         """
         return {}
 
+    def db_extensions(self) -> list[str]:
+        """Postgres extensions this module needs (``["ltree", "pg_trgm"]``).
+
+        Names match ``^[a-z][a-z0-9_-]*$``. ``ensure_db_extensions`` creates them
+        before migrations run; on SQLite that raises (doctor SM029 warns early).
+        """
+        return []
+
     # ── Lifecycle ─────────────────────────────────────────────
 
     async def on_startup(self, app: FastAPI) -> None:

{simple_module_core-0.0.36 → simple_module_core-0.0.37}/simple_module_core/permissions.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import logging
+import time
 from collections.abc import Awaitable, Callable, Collection, Iterable
 from dataclasses import dataclass, field
 from typing import Any
@@ -34,6 +35,21 @@ def is_admin(roles: list[str] | None) -> bool:
     return bool(roles) and ADMIN_ROLE in roles
 
 
+def is_admin_principal(user: Any) -> bool:
+    """Whether *user* may use the admin role's shortcuts — admin and not a token.
+
+    A principal carrying ``scopes`` (an ``api_tokens`` credential) is capped
+    at those scopes even when its owner is an admin, so every check that
+    admits admins on the role alone must use this rather than
+    :func:`is_admin`; otherwise an admin's ``feature_flags.view`` token would
+    still open the Doctor page. Duck-typed: ``UserContext`` lives in the auth
+    module, which framework code must not import.
+    """
+    if user is None or getattr(user, "scopes", None) is not None:
+        return False
+    return is_admin(getattr(user, "roles", None))
+
+
 def grants(held: Collection[str], required: str) -> bool:
     """Whether a principal holding *held* satisfies *required*.
 
@@ -80,7 +96,11 @@ class PermissionRegistry:
     every mutation.
     """
 
-    def __init__(self) -> None:
+    #: Seconds a failed source is answered as empty before it is called again.
+    SOURCE_RETRY_SECONDS = 30.0
+
+    def __init__(self, *, clock: Callable[[], float] = time.monotonic) -> None:
+        self._clock = clock
         self._groups: dict[str, PermissionGroup] = {}
         self._role_map: dict[str, set[str]] = {}
         # Admin-editor grants (DB-backed). Kept apart from ``_role_map`` (code
@@ -91,6 +111,8 @@ class PermissionRegistry:
         self._grant_sources: list[GrantSource] = []
         self._sources: dict[str, PermissionSourceProvider] = {}
         self._source_cache: dict[str, tuple[list[str], dict[str, str]]] = {}
+        self._source_failed_at: dict[str, float] = {}  # name → clock() of last failure
+        self._all_permissions_expires: float | None = None
 
     def _invalidate(self) -> None:
         self._all_permissions_cache = None
@@ -105,21 +127,28 @@ class PermissionRegistry:
         is **sync** and should read a module-maintained in-memory cache — the
         registry is consulted on every request. Its output is cached here until
         :meth:`invalidate_source` is called. A provider that raises is logged
-        and contributes nothing.
+        once and contributes nothing for ``SOURCE_RETRY_SECONDS``, then is
+        retried — a transient failure recovers on its own (GH #517).
         """
         self._sources[name] = provider
         self._source_cache.pop(name, None)
+        self._source_failed_at.pop(name, None)
         self._invalidate()
 
     def invalidate_source(self, name: str) -> None:
-        """Drop the cached output of source *name*; re-read on next access."""
+        """Drop the cached output (or failure) of source *name*; re-read on next access."""
         self._source_cache.pop(name, None)
+        self._source_failed_at.pop(name, None)
         self._invalidate()
 
     def _source_output(self, name: str) -> tuple[list[str], dict[str, str]]:
         cached = self._source_cache.get(name)
         if cached is not None:
             return cached
+        failed_at = self._source_failed_at.get(name)
+        if failed_at is not None and self._clock() - failed_at < self.SOURCE_RETRY_SECONDS:
+            # In the retry window: empty, uncalled, no traceback per request.
+            return [], {}
         keys: list[str] = []
         labels: dict[str, str] = {}
         try:
@@ -131,8 +160,12 @@ class PermissionRegistry:
                     keys.append(key)
                     labels[key] = label
         except Exception:
-            logger.exception("Permission source %r failed; contributing nothing", name)
-            keys, labels = [], {}
+            logger.exception("Permission source %r failed; contributing nothing until retry", name)
+            # Remembered for the retry window only: a transient failure must
+            # not hide the source until someone invalidates it.
+            self._source_failed_at[name] = self._clock()
+            return [], {}
+        self._source_failed_at.pop(name, None)
         out = (sorted(set(keys)), labels)
         self._source_cache[name] = out
         return out
@@ -161,11 +194,18 @@ class PermissionRegistry:
     @property
     def all_permissions(self) -> list[str]:
         """All registered permission strings, sorted."""
-        if self._all_permissions_cache is None:
+        expires = self._all_permissions_expires
+        if self._all_permissions_cache is None or (expires and self._clock() >= expires):
             perms: set[str] = set()
             for group in self.groups:
                 perms.update(group.permissions)
             self._all_permissions_cache = sorted(perms)
+            # A snapshot taken while a source is failing lives only until that
+            # source's retry, so a recovery shows up without an invalidation.
+            failed = self._source_failed_at.values()
+            self._all_permissions_expires = (
+                min(failed) + self.SOURCE_RETRY_SECONDS if failed else None
+            )
         return self._all_permissions_cache
 
     @property