From 7c29c8c4ec18235a40d8c6c544b57b4d049e257c Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Mon, 5 Oct 2026 13:18:22 +0200
Subject: [PATCH 1/6] feat(core): runtime menu providers and permission sources
 (#340, #334)

MenuRegistry.add_provider / remove; PermissionRegistry.add_source /
invalidate_source, surfaced in all_permissions, groups and the role editor.

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 CLAUDE.md                                     |  2 +
 docs/framework-conventions.md                 |  2 +
 docs/framework/permissions.md                 | 11 +++
 framework/core/simple_module_core/menu.py     | 71 +++++++++++++-
 .../core/simple_module_core/permissions.py    | 73 +++++++++++++-
 .../core/tests/test_permission_sources.py     | 51 ++++++++++
 .../simple_module_hosting/middleware.py       |  3 +-
 .../tests/test_menu_providers_wiring.py       | 95 +++++++++++++++++++
 .../permissions/contracts/schemas.py          |  2 +
 modules/permissions/permissions/service.py    |  3 +-
 .../tests/test_permissions_runtime_sources.py | 58 +++++++++++
 11 files changed, 362 insertions(+), 9 deletions(-)
 create mode 100644 framework/core/tests/test_permission_sources.py
 create mode 100644 framework/hosting/tests/test_menu_providers_wiring.py
 create mode 100644 modules/permissions/tests/test_permissions_runtime_sources.py

diff --git a/CLAUDE.md b/CLAUDE.md
index e34086f9..860e467e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -77,6 +77,8 @@ hence `SM022`/`SM023`. See `docs/module-authoring.md` § Styling.
 **Lifecycle hooks** (in `framework/core/simple_module_core/module.py`) — all no-op by default; subclasses override as needed:
 `register_settings` → `register_menu_items` / `register_permissions` / `register_feature_flags` / `register_event_handlers` / `register_invalidations` / `register_health_checks` / `register_public_routes` / `register_csp_sources` / `register_setup_steps` → `register_exception_handlers` → `register_middleware` → `register_routes(api_router, view_router)` / `register_admin_routes(admin_router)` → async `on_startup` / `on_shutdown` (reverse order). `register_admin_routes` is only for modules that serve **both** public and admin pages: a module gets exactly one router per `view_prefix`, which `users` cannot express (sign-in at `/users/login`, management at `/admin/users`). Setting `ModuleMeta.admin_view_prefix` mounts a second view router there. A module whose views are *all* administrative just points `view_prefix` at `/admin/<name>` and keeps using `register_routes`. The prefix is a URL convention, not a permission — guard these routes exactly as you would any other. `register_csp_sources(registry)` lets a module whitelist external asset origins (`registry.add("style-src", "https://rsms.me")`) — fetch directives only, validated at boot. `register_public_routes(registry)` lets a module exempt anonymous/read-only routes (STAC/OGC, webhooks) from `AuthMiddleware`; rules are method-aware (`registry.add_regex(r"…/tilejson$", methods={"GET"})`), so a GET read route can be public while sibling POST/PATCH mutations under the same prefix stay gated. See [docs/framework/public-routes.md](docs/framework/public-routes.md). `register_setup_steps(registry)` lets a module declare what a usable install still needs; while any required step is incomplete `SetupMiddleware` serves the first-run wizard at `/setup` instead of the app. A module that registers nothing never gates — that is how `keycloak` opts out, since its local users table is legitimately empty forever and a host-level superuser count would lock those installs out permanently. `register_invalidations(bus, app)` subscribes a module's **per-process caches** to `InvalidationBus`, so another worker's write drops this worker's entry instead of leaving it stale for its whole TTL; handlers may only *forget*, since there is no delivery guarantee. Publishing takes no hook — `await request.app.state.sm.invalidation.publish(channel, key=...)` from a `db.on_commit` callback. Cross-process delivery needs a transport, which `background_tasks` installs on its Redis connection (`SM_BG_TASKS_BROADCAST_INVALIDATIONS`); with none the bus is in-process and every cache still needs its TTL as a floor. See [docs/framework/invalidation.md](docs/framework/invalidation.md).
 
+`MenuRegistry.add_provider(fn)` (from `register_menu_items`) contributes per-request menu items evaluated in `InertiaLayoutDataMiddleware` after auth/tenant resolution, and `PermissionRegistry.add_source(name, provider)` (from `register_permissions`) contributes runtime-defined permissions from a sync in-memory cache, refreshed with `invalidate_source(name)`; see [docs/framework/permissions.md](docs/framework/permissions.md).
+
 **Middleware pipeline** (Starlette `add_middleware` is LIFO — last added runs first). Execution order on a request:
 `(ProxyHeaders, if SM_TRUSTED_PROXY) → CorrelationId → RequestLogging → GZip → SecurityHeaders → Session → <module middleware> → Tenant (opt-in) → Locale → InertiaLayoutData → InertiaCache → Setup → Maintenance → CommitBeforeResponse → app`. `InertiaCache` answers for `InertiaLayoutData` merging per-user `auth`/`menus` into every payload: a response to an `X-Inertia` request is forced to `private, no-store` with its ETag dropped, and both representations of a URL gain `Vary: X-Inertia` — so no cache can store the JSON payload or hand it back for a page request. A module wanting its public page content cached should set `Cache-Control` and an ETag on the *document*; that path is left alone. `GZip` compresses any response over 500 bytes, including the `/static` mount — the built CSS is ~139 KB raw versus ~21 KB gzipped, and uncompressed assets dominated cold page load. `ProxyHeaders` (uvicorn's `ProxyHeadersMiddleware`) is installed only when `SM_TRUSTED_PROXY` is set, sitting outermost so the `X-Forwarded-*`-corrected scheme/client IP reach everything downstream (request logs). Inertia does not depend on it: the page url is rewritten to the root-relative form the protocol specifies (`_inertia_url.py`), so no scheme travels in the payload to disagree with the document's — the cross-scheme `pushState` `SecurityError` of GH #223 cannot recur on an install that never set the variable. When two modules add middleware at the same dependency tier, the module that sorts **later** wraps outermost. Use `depends_on` to express relative order — don't rely on names. `Maintenance` serves a 503 page to everyone but admins while `maintenance_mode` is set on `HostSettings`; it sits inside `InertiaCache` because its 503 is an Inertia payload produced by short-circuiting, and outside the cache guard that payload would ship storable. `Setup` runs just before it, for the same cache reason and because an install that was never set up has nothing meaningful to put into maintenance.
 
diff --git a/docs/framework-conventions.md b/docs/framework-conventions.md
index 6b0dfef5..cc8c7b4f 100644
--- a/docs/framework-conventions.md
+++ b/docs/framework-conventions.md
@@ -358,6 +358,8 @@ way.
 
   Sidebar items can also set `group="<Label>"` on the `MenuItem` to render under a group header. The frontend clusters consecutive items with the same group label and prints the label as a section heading; the group's position is set by the lowest-`order` item that joins it. Built-in groups are `Content`, `Administration`, and `System`. Items with no `group` (the default) render flat — Dashboard intentionally stays ungrouped above the headed groups.
 
+  **Dynamic menus.** Items that depend on the request (per-tenant entries, resources admins create at runtime) come from a provider registered in `register_menu_items`: `registry.add_provider(fn)`, where `fn(request)` returns an iterable of `MenuItem` (sync or async). Providers run per request inside `InertiaLayoutDataMiddleware`, after auth and `request.state.tenant_id` are resolved, and their items are role/permission-filtered, translated, sorted and grouped like static ones. A provider that raises is logged and contributes nothing. `registry.remove(predicate)` drops static items.
+
   **Translating menu labels.** Set `label_key` (and `group_key`) alongside `label`/`group` to name a catalog entry:
 
   ```python
diff --git a/docs/framework/permissions.md b/docs/framework/permissions.md
index 6ac63e64..8a078416 100644
--- a/docs/framework/permissions.md
+++ b/docs/framework/permissions.md
@@ -73,6 +73,17 @@ Host apps customize this by:
 
 The framework ships only `admin: ["*"]`. The wildcard grants every declared permission.
 
+## Runtime permission sources
+
+`register_permissions` runs before the database is open, so it cannot declare permissions for resources admins create later (per-record-type keys such as `records.product.edit`). Register a **source** instead:
+
+```python
+def register_permissions(self, registry: PermissionRegistry) -> None:
+    registry.add_source("records", lambda: [("records.product.edit", "Edit products")])
+```
+
+The provider is **sync** and must read a module-maintained in-memory cache, because the registry is consulted on every request. It returns permission keys or `(key, label)` pairs. Its output is cached by the registry; call `registry.invalidate_source("records")` when the underlying resources change. Source permissions appear in `all_permissions`, in the role editor under the source's group name (labels ship in `PermissionGroupOut.labels`), in admin's implicit all-permissions, and are enforced by `RequiresPermission`. They are grantable and persisted like any other key. A source that raises is logged and contributes nothing.
+
 ## User resolution
 
 For each request, `AuthMiddleware` resolves the authenticated user onto `request.state.user` as a `UserContext` (from `auth.contracts.schemas`):
diff --git a/framework/core/simple_module_core/menu.py b/framework/core/simple_module_core/menu.py
index 6ada393b..85312282 100644
--- a/framework/core/simple_module_core/menu.py
+++ b/framework/core/simple_module_core/menu.py
@@ -2,10 +2,17 @@
 
 from __future__ import annotations
 
-from collections.abc import Callable
+import inspect
+import logging
+from collections.abc import Awaitable, Callable, Iterable
 from dataclasses import dataclass, field
 from enum import StrEnum
-from typing import Literal
+from typing import TYPE_CHECKING, Literal
+
+if TYPE_CHECKING:
+    from starlette.requests import Request
+
+logger = logging.getLogger(__name__)
 
 MenuItemMethod = Literal["get", "post"]
 
@@ -67,12 +74,17 @@ class MenuItem:
     is set by the lowest-ordered item that belongs to it."""
 
 
+MenuProvider = Callable[["Request"], "Awaitable[Iterable[MenuItem]] | Iterable[MenuItem]"]
+"""Per-request source of menu items; sync or async."""
+
+
 class MenuRegistry:
     """Collects menu items from all modules and filters them per-request."""
 
     def __init__(self) -> None:
         self._items: list[MenuItem] = []
         self._sorted: list[MenuItem] | None = None
+        self._providers: list[MenuProvider] = []
 
     def _invalidate(self) -> None:
         self._sorted = None
@@ -85,12 +97,61 @@ def add_many(self, items: list[MenuItem]) -> None:
         self._items.extend(items)
         self._invalidate()
 
+    def remove(self, predicate: Callable[[MenuItem], bool]) -> int:
+        """Drop static items for which *predicate* is true; return how many."""
+        kept = [i for i in self._items if not predicate(i)]
+        removed = len(self._items) - len(kept)
+        self._items = kept
+        self._invalidate()
+        return removed
+
+    def add_provider(self, provider: MenuProvider) -> None:
+        """Register a per-request provider of extra menu items.
+
+        Evaluated inside ``InertiaLayoutDataMiddleware`` (auth and
+        ``request.state.tenant_id`` already resolved) and then filtered,
+        translated, ordered and grouped like static items. A provider that
+        raises is logged and contributes nothing.
+        """
+        self._providers.append(provider)
+
+    async def collect_provider_items(self, request: Request) -> list[MenuItem]:
+        items: list[MenuItem] = []
+        for provider in self._providers:
+            try:
+                result = provider(request)
+                if inspect.isawaitable(result):
+                    result = await result
+                items.extend(result)
+            except Exception:
+                logger.exception("Menu provider %r failed; contributing nothing", provider)
+        return items
+
     @property
     def all_items(self) -> list[MenuItem]:
         if self._sorted is None:
             self._sorted = sorted(self._items, key=lambda i: i.order)
         return self._sorted
 
+    async def get_for_request(
+        self,
+        request: Request,
+        *,
+        is_authenticated: bool,
+        roles: list[str] | None = None,
+        permissions: list[str] | None = None,
+        translate: Callable[[str], str] | None = None,
+    ) -> dict[str, list[dict]]:
+        """:meth:`get_for_user` over static items plus this request's provider items."""
+        extra = await self.collect_provider_items(request) if self._providers else []
+        return self.get_for_user(
+            is_authenticated=is_authenticated,
+            roles=roles,
+            permissions=permissions,
+            translate=translate,
+            extra_items=extra,
+        )
+
     def get_for_user(
         self,
         *,
@@ -98,6 +159,7 @@ def get_for_user(
         roles: list[str] | None = None,
         permissions: list[str] | None = None,
         translate: Callable[[str], str] | None = None,
+        extra_items: Iterable[MenuItem] = (),
     ) -> dict[str, list[dict]]:
         """Return menu items grouped by section, filtered by auth/roles/permissions.
 
@@ -124,7 +186,10 @@ def render(key: str, fallback: str) -> str:
             translated = translate(key)
             return fallback if translated == key else translated
 
-        for item in self.all_items:
+        items = self.all_items
+        if extra := list(extra_items):
+            items = sorted([*items, *extra], key=lambda i: i.order)
+        for item in items:
             if item.requires_auth and not is_authenticated:
                 continue
             if item.roles and not any(r in item.roles for r in roles):
diff --git a/framework/core/simple_module_core/permissions.py b/framework/core/simple_module_core/permissions.py
index d79fdab8..e8f2b351 100644
--- a/framework/core/simple_module_core/permissions.py
+++ b/framework/core/simple_module_core/permissions.py
@@ -2,9 +2,15 @@
 
 from __future__ import annotations
 
-from collections.abc import Collection
+import logging
+from collections.abc import Callable, Collection, Iterable
 from dataclasses import dataclass, field
 
+logger = logging.getLogger(__name__)
+
+PermissionSourceProvider = Callable[[], "Iterable[str] | Iterable[tuple[str, str]]"]
+"""Sync callable returning permission keys, or ``(key, label)`` pairs."""
+
 WILDCARD = "*"
 
 ADMIN_ROLE = "admin"
@@ -66,11 +72,61 @@ def __init__(self) -> None:
         self._role_map: dict[str, set[str]] = {}
         self._all_permissions_cache: list[str] | None = None
         self._role_map_cache: dict[str, list[str]] | None = None
+        self._sources: dict[str, PermissionSourceProvider] = {}
+        self._source_cache: dict[str, tuple[list[str], dict[str, str]]] = {}
 
     def _invalidate(self) -> None:
         self._all_permissions_cache = None
         self._role_map_cache = None
 
+    # ── Runtime sources ────────────────────────────────────────
+
+    def add_source(self, name: str, provider: PermissionSourceProvider) -> None:
+        """Register a runtime permission source under group *name*.
+
+        For modules whose protected resources are created after boot. *provider*
+        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.
+        """
+        self._sources[name] = provider
+        self._source_cache.pop(name, None)
+        self._invalidate()
+
+    def invalidate_source(self, name: str) -> None:
+        """Drop the cached output of source *name*; re-read on next access."""
+        self._source_cache.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
+        keys: list[str] = []
+        labels: dict[str, str] = {}
+        try:
+            for entry in self._sources[name]():
+                if isinstance(entry, str):
+                    keys.append(entry)
+                else:
+                    key, label = entry
+                    keys.append(key)
+                    labels[key] = label
+        except Exception:
+            logger.exception("Permission source %r failed; contributing nothing", name)
+            keys, labels = [], {}
+        out = (sorted(set(keys)), labels)
+        self._source_cache[name] = out
+        return out
+
+    def source_labels(self) -> dict[str, str]:
+        """Human labels supplied by sources, keyed by permission string."""
+        labels: dict[str, str] = {}
+        for name in self._sources:
+            labels.update(self._source_output(name)[1])
+        return labels
+
     def add_group(self, name: str, permissions: list[str]) -> None:
         """Register a group of related permissions."""
         if name in self._groups:
@@ -93,17 +149,26 @@ def all_permissions(self) -> list[str]:
         """All registered permission strings, sorted."""
         if self._all_permissions_cache is None:
             perms: set[str] = set()
-            for group in self._groups.values():
+            for group in self.groups:
                 perms.update(group.permissions)
             self._all_permissions_cache = sorted(perms)
         return self._all_permissions_cache
 
     @property
     def groups(self) -> list[PermissionGroup]:
-        return list(self._groups.values())
+        """Static groups plus one group per source (merged by name)."""
+        merged = {
+            n: PermissionGroup(name=n, permissions=list(g.permissions))
+            for n, g in self._groups.items()
+        }
+        for name in self._sources:
+            keys = self._source_output(name)[0]
+            group = merged.setdefault(name, PermissionGroup(name=name))
+            group.permissions.extend(k for k in keys if k not in group.permissions)
+        return list(merged.values())
 
     def has(self, permission: str) -> bool:
-        return any(permission in g.permissions for g in self._groups.values())
+        return permission in self.all_permissions
 
     def map_role(self, role: str, permissions: list[str]) -> None:
         """Register a role→permission mapping.
diff --git a/framework/core/tests/test_permission_sources.py b/framework/core/tests/test_permission_sources.py
new file mode 100644
index 00000000..8f751a9c
--- /dev/null
+++ b/framework/core/tests/test_permission_sources.py
@@ -0,0 +1,51 @@
+"""Runtime permission sources on PermissionRegistry (GH #334)."""
+
+from __future__ import annotations
+
+import logging
+
+from simple_module_core.permissions import PermissionRegistry
+
+
+def test_source_permissions_in_all_permissions_and_groups() -> None:
+    reg = PermissionRegistry()
+    reg.add_group("users", ["users.view"])
+    reg.add_source("records", lambda: ["records.product.edit", ("records.faq.edit", "Edit FAQ")])
+
+    assert "records.product.edit" in reg.all_permissions
+    assert reg.has("records.faq.edit")
+    group = next(g for g in reg.groups if g.name == "records")
+    assert sorted(group.permissions) == ["records.faq.edit", "records.product.edit"]
+    assert reg.source_labels() == {"records.faq.edit": "Edit FAQ"}
+
+
+def test_invalidate_source_refreshes() -> None:
+    reg = PermissionRegistry()
+    types = ["a"]
+    reg.add_source("records", lambda: [f"records.{t}.edit" for t in types])
+    assert reg.all_permissions == ["records.a.edit"]
+
+    types.append("b")
+    assert reg.all_permissions == ["records.a.edit"]  # cached
+    reg.invalidate_source("records")
+    assert reg.all_permissions == ["records.a.edit", "records.b.edit"]
+
+
+def test_failing_source_is_isolated(caplog) -> None:
+    reg = PermissionRegistry()
+    reg.add_group("users", ["users.view"])
+
+    def boom() -> list[str]:
+        raise RuntimeError("nope")
+
+    reg.add_source("bad", boom)
+    reg.add_source("good", lambda: ["good.x"])
+    with caplog.at_level(logging.ERROR):
+        assert reg.all_permissions == ["good.x", "users.view"]
+    assert any("bad" in r.getMessage() for r in caplog.records)
+
+
+def test_admin_implicit_all_includes_sources() -> None:
+    reg = PermissionRegistry()
+    reg.add_source("records", lambda: ["records.product.edit"])
+    assert "records.product.edit" in reg.get_permissions_for_roles(["admin"])
diff --git a/framework/hosting/simple_module_hosting/middleware.py b/framework/hosting/simple_module_hosting/middleware.py
index 91fdbd24..ceb77e1e 100644
--- a/framework/hosting/simple_module_hosting/middleware.py
+++ b/framework/hosting/simple_module_hosting/middleware.py
@@ -221,7 +221,8 @@ async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
                 "isAuthenticated": is_authenticated,
                 "permissions": frontend_permissions,
             },
-            "menus": self.menu_registry.get_for_user(
+            "menus": await self.menu_registry.get_for_request(
+                request,
                 is_authenticated=is_authenticated,
                 roles=roles,
                 # Already expanded above (wildcards resolved), which is exactly
diff --git a/framework/hosting/tests/test_menu_providers_wiring.py b/framework/hosting/tests/test_menu_providers_wiring.py
new file mode 100644
index 00000000..b9adf52e
--- /dev/null
+++ b/framework/hosting/tests/test_menu_providers_wiring.py
@@ -0,0 +1,95 @@
+"""Per-request menu providers through InertiaLayoutDataMiddleware (GH #340)."""
+
+from __future__ import annotations
+
+import logging
+from types import SimpleNamespace
+
+from fastapi import FastAPI
+from simple_module_core.menu import MenuItem, MenuRegistry
+from simple_module_core.permissions import PermissionRegistry
+from simple_module_hosting.middleware import InertiaLayoutDataMiddleware
+from starlette.middleware.sessions import SessionMiddleware
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+from starlette.testclient import TestClient
+
+
+def _build(menu: MenuRegistry) -> TestClient:
+    app = FastAPI()
+
+    @app.get("/shared")
+    def shared(request: Request) -> JSONResponse:
+        return JSONResponse(request.state.inertia_shared["menus"])
+
+    app.add_middleware(
+        InertiaLayoutDataMiddleware, menu_registry=menu, permission_registry=PermissionRegistry()
+    )
+
+    @app.middleware("http")
+    async def fake_auth(request: Request, call_next):
+        role = request.headers.get("x-role")
+        if role:
+            request.state.user = SimpleNamespace(roles=[role])
+        request.state.tenant_id = request.headers.get("x-tenant", "")
+        return await call_next(request)
+
+    app.add_middleware(SessionMiddleware, secret_key="s")
+    return TestClient(app)
+
+
+def _labels(body: dict, section: str = "sidebar") -> list[str]:
+    return [i["label"] for i in body[section]]
+
+
+def test_async_provider_sees_tenant_and_is_per_request() -> None:
+    menu = MenuRegistry()
+    menu.add(MenuItem(label="Static", url="/s", order=10))
+
+    async def provider(request: Request) -> list[MenuItem]:
+        return [MenuItem(label=f"T-{request.state.tenant_id}", url="/t", order=5)]
+
+    menu.add_provider(provider)
+    client = _build(menu)
+    a = client.get("/shared", headers={"x-role": "user", "x-tenant": "a"}).json()
+    b = client.get("/shared", headers={"x-role": "user", "x-tenant": "b"}).json()
+    assert _labels(a) == ["T-a", "Static"]  # merged and sorted by order
+    assert _labels(b) == ["T-b", "Static"]
+
+
+def test_sync_provider_and_role_filtering() -> None:
+    menu = MenuRegistry()
+    menu.add_provider(
+        lambda _r: [MenuItem(label="Admins", url="/a", roles=["admin"]), MenuItem("All", "/x")]
+    )
+    client = _build(menu)
+    assert _labels(client.get("/shared", headers={"x-role": "user"}).json()) == ["All"]
+    assert sorted(_labels(client.get("/shared", headers={"x-role": "admin"}).json())) == [
+        "Admins",
+        "All",
+    ]
+    assert _labels(client.get("/shared").json()) == []  # anonymous: requires_auth
+
+
+def test_failing_provider_is_isolated(caplog) -> None:
+    menu = MenuRegistry()
+    menu.add(MenuItem(label="Static", url="/s"))
+
+    async def boom(_r: Request) -> list[MenuItem]:
+        raise RuntimeError("x")
+
+    menu.add_provider(boom)
+    menu.add_provider(lambda _r: [MenuItem(label="Ok", url="/ok", order=-1)])
+    with caplog.at_level(logging.ERROR):
+        resp = _build(menu).get("/shared", headers={"x-role": "user"})
+    assert resp.status_code == 200
+    assert _labels(resp.json()) == ["Ok", "Static"]
+    assert any("Menu provider" in r.getMessage() for r in caplog.records)
+
+
+def test_remove_static_items_invalidates_cache() -> None:
+    menu = MenuRegistry()
+    menu.add_many([MenuItem(label="A", url="/a"), MenuItem(label="B", url="/b")])
+    assert [i.label for i in menu.all_items] == ["A", "B"]
+    assert menu.remove(lambda i: i.label == "A") == 1
+    assert [i.label for i in menu.all_items] == ["B"]
diff --git a/modules/permissions/permissions/contracts/schemas.py b/modules/permissions/permissions/contracts/schemas.py
index fb390b1a..e4880552 100644
--- a/modules/permissions/permissions/contracts/schemas.py
+++ b/modules/permissions/permissions/contracts/schemas.py
@@ -13,6 +13,8 @@ class PermissionGroupOut(SQLModel):
 
     name: str
     permissions: list[str]
+    labels: dict[str, str] = Field(default_factory=dict)
+    """Human labels for keys a runtime permission source supplied one for."""
 
 
 class RoleOut(SQLModel):
diff --git a/modules/permissions/permissions/service.py b/modules/permissions/permissions/service.py
index f5290fc4..39605a22 100644
--- a/modules/permissions/permissions/service.py
+++ b/modules/permissions/permissions/service.py
@@ -42,8 +42,9 @@ def __init__(self, db: AsyncSession, registry: PermissionRegistry) -> None:
     # ── Registry read-outs ─────────────────────────────────────
 
     def list_registered_groups(self) -> list[PermissionGroupOut]:
+        labels = self.registry.source_labels()
         return [
-            PermissionGroupOut(name=g.name, permissions=sorted(g.permissions))
+            PermissionGroupOut(name=g.name, permissions=sorted(g.permissions), labels=labels)
             for g in self.registry.groups
         ]
 
diff --git a/modules/permissions/tests/test_permissions_runtime_sources.py b/modules/permissions/tests/test_permissions_runtime_sources.py
new file mode 100644
index 00000000..2eaacf87
--- /dev/null
+++ b/modules/permissions/tests/test_permissions_runtime_sources.py
@@ -0,0 +1,58 @@
+"""Runtime permission sources reach the role editor and are grantable/enforced (GH #334)."""
+
+from __future__ import annotations
+
+import httpx
+from fastapi import FastAPI
+
+
+async def test_source_permission_listed_grantable_and_invalidated(
+    authenticated_client: httpx.AsyncClient, app: FastAPI
+):
+    from users.constants import USER_ROLE_ID, USER_ROLE_NAME
+    from users.models import Role
+
+    registry = app.state.sm.permissions
+    types = ["product"]
+    registry.add_source("records", lambda: [(f"records.{t}.edit", f"Edit {t}") for t in types])
+
+    async with app.state.sm.db.session_factory() as db:
+        if await db.get(Role, USER_ROLE_ID) is None:
+            db.add(Role(id=USER_ROLE_ID, name=USER_ROLE_NAME, description="Standard user"))
+            await db.commit()
+
+    groups = (await authenticated_client.get("/api/permissions/")).json()
+    records = next(g for g in groups if g["name"] == "records")
+    assert records["permissions"] == ["records.product.edit"]
+    assert records["labels"] == {"records.product.edit": "Edit product"}
+
+    put = await authenticated_client.put(
+        f"/api/permissions/roles/{USER_ROLE_ID}", json={"permissions": ["records.product.edit"]}
+    )
+    assert put.status_code == 200
+    assert put.json()["permissions"] == ["records.product.edit"]
+    assert "records.product.edit" in registry.role_map[USER_ROLE_NAME]
+
+    # A new runtime resource becomes grantable after invalidate_source.
+    types.append("faq")
+    registry.invalidate_source("records")
+    groups = (await authenticated_client.get("/api/permissions/")).json()
+    records = next(g for g in groups if g["name"] == "records")
+    assert "records.faq.edit" in records["permissions"]
+
+
+async def test_source_permission_enforced_by_requires_permission(app: FastAPI):
+    from simple_module_hosting.permissions import resolved_permissions_for
+    from starlette.requests import Request
+
+    registry = app.state.sm.permissions
+    registry.add_source("records", lambda: ["records.product.edit"])
+    registry.map_role("editor", ["records.product.edit"])
+
+    scope = {"type": "http", "app": app, "headers": [], "state": {}}
+    request = Request(scope)
+    request.state.user = type("U", (), {"roles": ["editor"]})()
+    assert "records.product.edit" in resolved_permissions_for(request)
+
+    # Admin's implicit grant covers source permissions.
+    assert "records.product.edit" in registry.get_permissions_for_roles(["admin"])

From d288750ade2053bf4c4b42c2e80fa691ee9aba90 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Mon, 5 Oct 2026 13:51:10 +0200
Subject: [PATCH 2/6] feat(permissions): scope source labels per group and
 render them in RoleEdit

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 .../core/simple_module_core/permissions.py    |  9 +++-----
 .../core/tests/test_permission_sources.py     |  3 ++-
 .../pages/components/RoleGroupCard.tsx        |  3 ++-
 .../pages/components/permission-groups.ts     |  2 ++
 modules/permissions/permissions/service.py    | 11 +++++-----
 .../permissions/tests-js/RoleEdit.test.tsx    | 22 +++++++++++++++++++
 .../tests/test_permissions_runtime_sources.py |  2 ++
 7 files changed, 39 insertions(+), 13 deletions(-)

diff --git a/framework/core/simple_module_core/permissions.py b/framework/core/simple_module_core/permissions.py
index e8f2b351..1f348d01 100644
--- a/framework/core/simple_module_core/permissions.py
+++ b/framework/core/simple_module_core/permissions.py
@@ -120,12 +120,9 @@ def _source_output(self, name: str) -> tuple[list[str], dict[str, str]]:
         self._source_cache[name] = out
         return out
 
-    def source_labels(self) -> dict[str, str]:
-        """Human labels supplied by sources, keyed by permission string."""
-        labels: dict[str, str] = {}
-        for name in self._sources:
-            labels.update(self._source_output(name)[1])
-        return labels
+    def source_labels(self, name: str) -> dict[str, str]:
+        """Human labels supplied by source *name*, keyed by permission string."""
+        return dict(self._source_output(name)[1]) if name in self._sources else {}
 
     def add_group(self, name: str, permissions: list[str]) -> None:
         """Register a group of related permissions."""
diff --git a/framework/core/tests/test_permission_sources.py b/framework/core/tests/test_permission_sources.py
index 8f751a9c..ec2d9ff1 100644
--- a/framework/core/tests/test_permission_sources.py
+++ b/framework/core/tests/test_permission_sources.py
@@ -16,7 +16,8 @@ def test_source_permissions_in_all_permissions_and_groups() -> None:
     assert reg.has("records.faq.edit")
     group = next(g for g in reg.groups if g.name == "records")
     assert sorted(group.permissions) == ["records.faq.edit", "records.product.edit"]
-    assert reg.source_labels() == {"records.faq.edit": "Edit FAQ"}
+    assert reg.source_labels("records") == {"records.faq.edit": "Edit FAQ"}
+    assert reg.source_labels("users") == {}
 
 
 def test_invalidate_source_refreshes() -> None:
diff --git a/modules/permissions/permissions/pages/components/RoleGroupCard.tsx b/modules/permissions/permissions/pages/components/RoleGroupCard.tsx
index 0ef30283..63032c41 100644
--- a/modules/permissions/permissions/pages/components/RoleGroupCard.tsx
+++ b/modules/permissions/permissions/pages/components/RoleGroupCard.tsx
@@ -71,11 +71,12 @@ export function RoleGroupCard({ group, permissions, assigned, onToggle, onToggle
                 onCheckedChange={(checked) => onToggle(key, checked === true)}
               />
               <code
+                title={group.labels?.[key] ? key : undefined}
                 className={`min-w-0 truncate font-mono text-[12px] ${
                   on ? 'text-foreground' : 'text-muted-foreground'
                 }`}
               >
-                {key}
+                {group.labels?.[key] ?? key}
               </code>
             </label>
           );
diff --git a/modules/permissions/permissions/pages/components/permission-groups.ts b/modules/permissions/permissions/pages/components/permission-groups.ts
index 3398aefa..deaf082b 100644
--- a/modules/permissions/permissions/pages/components/permission-groups.ts
+++ b/modules/permissions/permissions/pages/components/permission-groups.ts
@@ -9,6 +9,8 @@
 export interface PermissionGroup {
   name: string;
   permissions: string[];
+  /** Human labels a runtime permission source supplied, keyed by permission. */
+  labels?: Record<string, string>;
 }
 
 /** A module, narrowed to the rows the current filters keep. */
diff --git a/modules/permissions/permissions/service.py b/modules/permissions/permissions/service.py
index 39605a22..e9f0bc62 100644
--- a/modules/permissions/permissions/service.py
+++ b/modules/permissions/permissions/service.py
@@ -42,9 +42,12 @@ def __init__(self, db: AsyncSession, registry: PermissionRegistry) -> None:
     # ── Registry read-outs ─────────────────────────────────────
 
     def list_registered_groups(self) -> list[PermissionGroupOut]:
-        labels = self.registry.source_labels()
         return [
-            PermissionGroupOut(name=g.name, permissions=sorted(g.permissions), labels=labels)
+            PermissionGroupOut(
+                name=g.name,
+                permissions=sorted(g.permissions),
+                labels=self.registry.source_labels(g.name),
+            )
             for g in self.registry.groups
         ]
 
@@ -112,9 +115,7 @@ async def set_role_permissions(
             for key in wanted - existing
         )
         await self.db.flush()
-
-        # `map_role` is additive — reset the role entry so removals take effect
-        # without a restart. No public replace API on PermissionRegistry yet.
+        # `map_role` is additive — reset the entry so removals apply without a restart.
         self.registry._role_map.pop(role.name, None)
         self.registry.map_role(role.name, sorted(wanted))
 
diff --git a/modules/permissions/tests-js/RoleEdit.test.tsx b/modules/permissions/tests-js/RoleEdit.test.tsx
index 6dd46f68..8bf73d29 100644
--- a/modules/permissions/tests-js/RoleEdit.test.tsx
+++ b/modules/permissions/tests-js/RoleEdit.test.tsx
@@ -85,6 +85,28 @@ const keyRow = (permissionKey: string) =>
 const filterBox = () => screen.getByPlaceholderText('Filter modules or permissions…');
 
 describe('RoleEdit', () => {
+  test('shows a source-supplied label for a permission, falling back to the key', () => {
+    render(
+      <RoleEdit
+        role={{ id: 'r1', name: 'editor', description: null }}
+        assigned={[]}
+        groups={[
+          {
+            name: 'records',
+            permissions: ['records.faq.edit', 'records.product.edit'],
+            labels: { 'records.product.edit': 'Edit products' },
+          },
+        ]}
+      />,
+    );
+
+    expect(screen.getByText('Edit products', { selector: 'code' })).toHaveAttribute(
+      'title',
+      'records.product.edit',
+    );
+    expect(screen.getByText('records.faq.edit', { selector: 'code' })).toBeVisible();
+  });
+
   test('renders the deck header, actions and granted summary', () => {
     renderPage();
 
diff --git a/modules/permissions/tests/test_permissions_runtime_sources.py b/modules/permissions/tests/test_permissions_runtime_sources.py
index 2eaacf87..a00362bb 100644
--- a/modules/permissions/tests/test_permissions_runtime_sources.py
+++ b/modules/permissions/tests/test_permissions_runtime_sources.py
@@ -25,6 +25,8 @@ async def test_source_permission_listed_grantable_and_invalidated(
     records = next(g for g in groups if g["name"] == "records")
     assert records["permissions"] == ["records.product.edit"]
     assert records["labels"] == {"records.product.edit": "Edit product"}
+    # Labels stay inside their own group: static groups carry none.
+    assert all(g["labels"] == {} for g in groups if g["name"] != "records")
 
     put = await authenticated_client.put(
         f"/api/permissions/roles/{USER_ROLE_ID}", json={"permissions": ["records.product.edit"]}

From d103ee89c56216b8c07927283566b9ed89b488ae Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Tue, 6 Oct 2026 16:49:36 +0200
Subject: [PATCH 3/6] refactor(optimize): hoist role label, restore why-comment

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 .../permissions/pages/components/RoleGroupCard.tsx           | 5 +++--
 modules/permissions/permissions/service.py                   | 1 +
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/modules/permissions/permissions/pages/components/RoleGroupCard.tsx b/modules/permissions/permissions/pages/components/RoleGroupCard.tsx
index 63032c41..7555da57 100644
--- a/modules/permissions/permissions/pages/components/RoleGroupCard.tsx
+++ b/modules/permissions/permissions/pages/components/RoleGroupCard.tsx
@@ -57,6 +57,7 @@ export function RoleGroupCard({ group, permissions, assigned, onToggle, onToggle
       <div className="grid sm:grid-cols-2">
         {permissions.map((key, index) => {
           const on = assigned.has(key);
+          const label = group.labels?.[key];
           return (
             <label
               key={key}
@@ -71,12 +72,12 @@ export function RoleGroupCard({ group, permissions, assigned, onToggle, onToggle
                 onCheckedChange={(checked) => onToggle(key, checked === true)}
               />
               <code
-                title={group.labels?.[key] ? key : undefined}
+                title={label ? key : undefined}
                 className={`min-w-0 truncate font-mono text-[12px] ${
                   on ? 'text-foreground' : 'text-muted-foreground'
                 }`}
               >
-                {group.labels?.[key] ?? key}
+                {label ?? key}
               </code>
             </label>
           );
diff --git a/modules/permissions/permissions/service.py b/modules/permissions/permissions/service.py
index e9f0bc62..5f4ba46c 100644
--- a/modules/permissions/permissions/service.py
+++ b/modules/permissions/permissions/service.py
@@ -116,6 +116,7 @@ async def set_role_permissions(
         )
         await self.db.flush()
         # `map_role` is additive — reset the entry so removals apply without a restart.
+        # No public replace API on PermissionRegistry yet.
         self.registry._role_map.pop(role.name, None)
         self.registry.map_role(role.name, sorted(wanted))
 

From fb5a073fee4665714d8b425b8f1b308aafa4bf2d Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Tue, 6 Oct 2026 17:10:04 +0200
Subject: [PATCH 4/6] fix: address code review findings (round 1, pass 1)

Materialise provider output before extending, show source labels in the user
grants editor and role search, keep stored grants of currently unregistered
source keys when saving a role or user.

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 framework/core/simple_module_core/menu.py     |  3 ++-
 .../pages/components/GrantsGroupCard.tsx      |  1 +
 .../pages/components/PermissionRow.tsx        |  6 ++++-
 .../pages/components/permission-groups.ts     |  5 +++-
 modules/permissions/permissions/service.py    |  6 +++--
 .../tests/test_permissions_runtime_sources.py | 26 +++++++++++++++++++
 6 files changed, 42 insertions(+), 5 deletions(-)

diff --git a/framework/core/simple_module_core/menu.py b/framework/core/simple_module_core/menu.py
index 85312282..5a6ac85b 100644
--- a/framework/core/simple_module_core/menu.py
+++ b/framework/core/simple_module_core/menu.py
@@ -122,7 +122,8 @@ async def collect_provider_items(self, request: Request) -> list[MenuItem]:
                 result = provider(request)
                 if inspect.isawaitable(result):
                     result = await result
-                items.extend(result)
+                # Materialise first: a generator failing midway must add nothing.
+                items.extend(list(result))
             except Exception:
                 logger.exception("Menu provider %r failed; contributing nothing", provider)
         return items
diff --git a/modules/permissions/permissions/pages/components/GrantsGroupCard.tsx b/modules/permissions/permissions/pages/components/GrantsGroupCard.tsx
index b62e46dd..0deea2a0 100644
--- a/modules/permissions/permissions/pages/components/GrantsGroupCard.tsx
+++ b/modules/permissions/permissions/pages/components/GrantsGroupCard.tsx
@@ -46,6 +46,7 @@ export function GrantsGroupCard({
           <PermissionRow
             key={key}
             permissionKey={key}
+            label={group.labels?.[key]}
             direct={direct.has(key)}
             viaRoles={inheritedBy[key] ?? []}
             onToggle={onToggle}
diff --git a/modules/permissions/permissions/pages/components/PermissionRow.tsx b/modules/permissions/permissions/pages/components/PermissionRow.tsx
index d9f514a7..2c54bcd7 100644
--- a/modules/permissions/permissions/pages/components/PermissionRow.tsx
+++ b/modules/permissions/permissions/pages/components/PermissionRow.tsx
@@ -4,6 +4,8 @@ import { Switch } from '@simple-module-py/ui/components/ui/switch';
 
 interface Props {
   permissionKey: string;
+  /** Human label from a runtime permission source; the key shows when absent. */
+  label?: string;
   /** Granted directly to this user — the only thing the switch controls. */
   direct: boolean;
   /** Roles granting this key, empty when none do. */
@@ -22,6 +24,7 @@ interface Props {
  */
 export function PermissionRow({
   permissionKey,
+  label,
   direct,
   viaRoles,
   onToggle,
@@ -52,11 +55,12 @@ export function PermissionRow({
           the right — `settings.create`, `settings.delete` — so cutting the end
           off removes the half that tells them apart. */}
       <code
+        title={label ? permissionKey : undefined}
         className={`min-w-0 flex-1 break-all font-mono text-[12px] sm:truncate ${
           effective ? 'text-foreground' : 'text-muted-foreground'
         }`}
       >
-        {permissionKey}
+        {label ?? permissionKey}
       </code>
 
       {direct && (
diff --git a/modules/permissions/permissions/pages/components/permission-groups.ts b/modules/permissions/permissions/pages/components/permission-groups.ts
index deaf082b..83261a3f 100644
--- a/modules/permissions/permissions/pages/components/permission-groups.ts
+++ b/modules/permissions/permissions/pages/components/permission-groups.ts
@@ -70,7 +70,10 @@ export function filterGroups(
     if (!moduleMatches && !matchKeys) continue;
     const permissions = group.permissions.filter(
       (key) =>
-        (moduleMatches || key.toLowerCase().includes(needle)) && (keepKey ? keepKey(key) : true),
+        (moduleMatches ||
+          key.toLowerCase().includes(needle) ||
+          (group.labels?.[key] ?? '').toLowerCase().includes(needle)) &&
+        (keepKey ? keepKey(key) : true),
     );
     if (permissions.length > 0) result.push({ group, permissions });
   }
diff --git a/modules/permissions/permissions/service.py b/modules/permissions/permissions/service.py
index 5f4ba46c..1802efda 100644
--- a/modules/permissions/permissions/service.py
+++ b/modules/permissions/permissions/service.py
@@ -101,7 +101,9 @@ async def set_role_permissions(
 
         wanted = {k for k in keys if k in self._registered_keys()}
         existing = set(await self._get_role_keys(role.name))
-        to_remove = existing - wanted
+        # Unregistered keys (e.g. a runtime source that is empty right now) are left
+        # alone: pruning them would silently drop grants that return with the source.
+        to_remove = (existing - wanted) & self._registered_keys()
 
         if to_remove:
             await self.db.execute(
@@ -192,7 +194,7 @@ async def set_user_permissions(
 
         wanted = {k for k in keys if k in self._registered_keys()}
         existing = set(await self.get_user_direct_keys(user.id))
-        to_remove = existing - wanted
+        to_remove = (existing - wanted) & self._registered_keys()
 
         if to_remove:
             await self.db.execute(
diff --git a/modules/permissions/tests/test_permissions_runtime_sources.py b/modules/permissions/tests/test_permissions_runtime_sources.py
index a00362bb..30e9a4bb 100644
--- a/modules/permissions/tests/test_permissions_runtime_sources.py
+++ b/modules/permissions/tests/test_permissions_runtime_sources.py
@@ -58,3 +58,29 @@ async def test_source_permission_enforced_by_requires_permission(app: FastAPI):
 
     # Admin's implicit grant covers source permissions.
     assert "records.product.edit" in registry.get_permissions_for_roles(["admin"])
+
+
+async def test_saving_role_keeps_grants_of_currently_unregistered_source_keys(
+    authenticated_client: httpx.AsyncClient, app: FastAPI
+):
+    from permissions.service import PermissionService
+    from users.constants import USER_ROLE_ID, USER_ROLE_NAME
+    from users.models import Role
+
+    registry = app.state.sm.permissions
+    registry.add_source("records", lambda: ["records.product.edit"])
+    async with app.state.sm.db.session_factory() as db:
+        if await db.get(Role, USER_ROLE_ID) is None:
+            db.add(Role(id=USER_ROLE_ID, name=USER_ROLE_NAME, description="Standard user"))
+            await db.commit()
+    url = f"/api/permissions/roles/{USER_ROLE_ID}"
+    await authenticated_client.put(url, json={"permissions": ["records.product.edit"]})
+
+    # The source goes empty (e.g. restart before its cache warms); an unrelated save
+    # must not prune the stored grant.
+    registry.add_source("records", lambda: [])
+    await authenticated_client.put(url, json={"permissions": []})
+
+    async with app.state.sm.db.session_factory() as db:
+        keys = await PermissionService(db, registry)._get_role_keys(USER_ROLE_NAME)
+    assert keys == ["records.product.edit"]

From 4d9f3aa84e8891075166dfe4f2e03cee4579e311 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Tue, 6 Oct 2026 17:21:10 +0200
Subject: [PATCH 5/6] fix: always show the permission key beside a source
 label; keep in-memory grants

Anti-spoofing for runtime permission-source labels: the key is always rendered,
the label is plain, trimmed, capped text, and switches are named with the key.
Role saves also keep currently-unregistered stored grants in the in-memory map.

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 .../pages/components/PermissionLabel.tsx      | 25 +++++++++
 .../pages/components/PermissionRow.tsx        | 15 +++--
 .../pages/components/RoleGroupCard.tsx        | 18 +++---
 .../pages/components/permission-groups.ts     | 18 ++++++
 modules/permissions/permissions/service.py    |  4 +-
 .../tests-js/PermissionRow.test.tsx           | 56 +++++++++++++++++++
 .../permissions/tests-js/RoleEdit.test.tsx    | 36 ++++++++++--
 7 files changed, 150 insertions(+), 22 deletions(-)
 create mode 100644 modules/permissions/permissions/pages/components/PermissionLabel.tsx
 create mode 100644 modules/permissions/tests-js/PermissionRow.test.tsx

diff --git a/modules/permissions/permissions/pages/components/PermissionLabel.tsx b/modules/permissions/permissions/pages/components/PermissionLabel.tsx
new file mode 100644
index 00000000..65509da4
--- /dev/null
+++ b/modules/permissions/permissions/pages/components/PermissionLabel.tsx
@@ -0,0 +1,25 @@
+import { cleanLabel } from './permission-groups';
+
+interface Props {
+  permissionKey: string;
+  /** Free text from a runtime permission source — rendered as plain text only. */
+  label?: string;
+  dimmed?: boolean;
+  className?: string;
+}
+
+/**
+ * A permission's identity. The key is always visible: a source-supplied label is
+ * secondary text above it, never a replacement, so a label cannot make one
+ * permission look like another.
+ */
+export function PermissionLabel({ permissionKey, label, dimmed = false, className = '' }: Props) {
+  const text = cleanLabel(label);
+  const tone = dimmed ? 'text-muted-foreground' : 'text-foreground';
+  return (
+    <span className={`flex min-w-0 flex-col ${className}`}>
+      {text && <span className={`break-words text-[13px] ${tone}`}>{text}</span>}
+      <code className={`break-all font-mono text-[12px] ${tone}`}>{permissionKey}</code>
+    </span>
+  );
+}
diff --git a/modules/permissions/permissions/pages/components/PermissionRow.tsx b/modules/permissions/permissions/pages/components/PermissionRow.tsx
index 2c54bcd7..ac33b393 100644
--- a/modules/permissions/permissions/pages/components/PermissionRow.tsx
+++ b/modules/permissions/permissions/pages/components/PermissionRow.tsx
@@ -1,6 +1,7 @@
 import { keys, useT } from '@simple-module-py/i18n';
 import { Badge } from '@simple-module-py/ui/components/ui/badge';
 import { Switch } from '@simple-module-py/ui/components/ui/switch';
+import { PermissionLabel } from './PermissionLabel';
 
 interface Props {
   permissionKey: string;
@@ -54,14 +55,12 @@ export function PermissionRow({
       {/* Wrapping beats truncating on a phone: a permission key is read from
           the right — `settings.create`, `settings.delete` — so cutting the end
           off removes the half that tells them apart. */}
-      <code
-        title={label ? permissionKey : undefined}
-        className={`min-w-0 flex-1 break-all font-mono text-[12px] sm:truncate ${
-          effective ? 'text-foreground' : 'text-muted-foreground'
-        }`}
-      >
-        {label ?? permissionKey}
-      </code>
+      <PermissionLabel
+        permissionKey={permissionKey}
+        label={label}
+        dimmed={!effective}
+        className="flex-1"
+      />
 
       {direct && (
         <Badge className="shrink-0 border-0 bg-primary-600/10 px-2 py-0 text-[11px] font-medium text-primary-700">
diff --git a/modules/permissions/permissions/pages/components/RoleGroupCard.tsx b/modules/permissions/permissions/pages/components/RoleGroupCard.tsx
index 7555da57..492efac5 100644
--- a/modules/permissions/permissions/pages/components/RoleGroupCard.tsx
+++ b/modules/permissions/permissions/pages/components/RoleGroupCard.tsx
@@ -4,7 +4,13 @@ import { Checkbox } from '@simple-module-py/ui/components/ui/checkbox';
 import { Switch } from '@simple-module-py/ui/components/ui/switch';
 import { Minus } from 'lucide-react';
 import { GroupHeading } from './GroupHeading';
-import { lastRowStart, type PermissionGroup } from './permission-groups';
+import { PermissionLabel } from './PermissionLabel';
+import {
+  cleanLabel,
+  lastRowStart,
+  type PermissionGroup,
+  permissionAriaLabel,
+} from './permission-groups';
 
 interface Props {
   /** The whole module: the header counts and its checkbox speak for all of it. */
@@ -70,15 +76,9 @@ export function RoleGroupCard({ group, permissions, assigned, onToggle, onToggle
                 id={`perm-${key}`}
                 checked={on}
                 onCheckedChange={(checked) => onToggle(key, checked === true)}
+                aria-label={permissionAriaLabel(key, cleanLabel(label))}
               />
-              <code
-                title={label ? key : undefined}
-                className={`min-w-0 truncate font-mono text-[12px] ${
-                  on ? 'text-foreground' : 'text-muted-foreground'
-                }`}
-              >
-                {label ?? key}
-              </code>
+              <PermissionLabel permissionKey={key} label={label} dimmed={!on} />
             </label>
           );
         })}
diff --git a/modules/permissions/permissions/pages/components/permission-groups.ts b/modules/permissions/permissions/pages/components/permission-groups.ts
index 83261a3f..be42d0c4 100644
--- a/modules/permissions/permissions/pages/components/permission-groups.ts
+++ b/modules/permissions/permissions/pages/components/permission-groups.ts
@@ -80,6 +80,24 @@ export function filterGroups(
   return result;
 }
 
+const MAX_LABEL_LENGTH = 80;
+
+/**
+ * A source-supplied label, made safe to show beside a key: trimmed, capped, and
+ * undefined when nothing is left. The key is always rendered too, so a label can
+ * never stand in for the permission it describes.
+ */
+export function cleanLabel(raw: string | undefined): string | undefined {
+  const trimmed = raw?.trim();
+  if (!trimmed) return undefined;
+  return trimmed.length > MAX_LABEL_LENGTH ? `${trimmed.slice(0, MAX_LABEL_LENGTH)}…` : trimmed;
+}
+
+/** Accessible name for a permission control: the key is always part of it. */
+export function permissionAriaLabel(key: string, label: string | undefined): string {
+  return label ? `${label} (${key})` : key;
+}
+
 /**
  * Index at which the last row of a two-column grid starts, so every earlier
  * row gets a bottom border and the last one does not.
diff --git a/modules/permissions/permissions/service.py b/modules/permissions/permissions/service.py
index 1802efda..b8229b84 100644
--- a/modules/permissions/permissions/service.py
+++ b/modules/permissions/permissions/service.py
@@ -120,7 +120,9 @@ async def set_role_permissions(
         # `map_role` is additive — reset the entry so removals apply without a restart.
         # No public replace API on PermissionRegistry yet.
         self.registry._role_map.pop(role.name, None)
-        self.registry.map_role(role.name, sorted(wanted))
+        # Keep unregistered-but-stored grants in memory too, so they are live again
+        # the moment their source repopulates.
+        self.registry.map_role(role.name, sorted(wanted | (existing - self._registered_keys())))
 
         return RolePermissionsOut(role=role, permissions=sorted(wanted))
 
diff --git a/modules/permissions/tests-js/PermissionRow.test.tsx b/modules/permissions/tests-js/PermissionRow.test.tsx
new file mode 100644
index 00000000..10c14292
--- /dev/null
+++ b/modules/permissions/tests-js/PermissionRow.test.tsx
@@ -0,0 +1,56 @@
+import '@testing-library/jest-dom/vitest';
+import { configureI18n } from '@simple-module-py/i18n';
+import { render, screen } from '@testing-library/react';
+import { describe, expect, test, vi } from 'vitest';
+import { PermissionRow } from '../permissions/pages/components/PermissionRow';
+
+class ResizeObserverStub {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+}
+vi.stubGlobal('ResizeObserver', ResizeObserverStub);
+
+configureI18n({
+  locale: 'en',
+  messages: {
+    'permissions.user_edit.direct_toggle_label': 'Grant {key} directly to this user',
+    'permissions.user_edit.direct_badge': 'direct',
+  },
+});
+
+describe('PermissionRow', () => {
+  test('shows the key beside a source label and names the switch after the key', () => {
+    render(
+      <PermissionRow
+        permissionKey="records.admin.delete"
+        label="Harmless read access"
+        direct={false}
+        viaRoles={[]}
+        onToggle={() => {}}
+      />,
+    );
+
+    expect(screen.getByText('Harmless read access')).toBeVisible();
+    expect(screen.getByText('records.admin.delete', { selector: 'code' })).toBeVisible();
+    expect(
+      screen.getByRole('switch', { name: 'Grant records.admin.delete directly to this user' }),
+    ).toBeVisible();
+  });
+
+  test('ignores a blank label and shows only the key', () => {
+    render(
+      <PermissionRow
+        permissionKey="records.faq.edit"
+        label="   "
+        direct={false}
+        viaRoles={[]}
+        onToggle={() => {}}
+      />,
+    );
+
+    const code = screen.getByText('records.faq.edit', { selector: 'code' });
+    expect(code).toBeVisible();
+    expect(code.parentElement?.children).toHaveLength(1);
+  });
+});
diff --git a/modules/permissions/tests-js/RoleEdit.test.tsx b/modules/permissions/tests-js/RoleEdit.test.tsx
index 8bf73d29..10f48c27 100644
--- a/modules/permissions/tests-js/RoleEdit.test.tsx
+++ b/modules/permissions/tests-js/RoleEdit.test.tsx
@@ -100,11 +100,39 @@ describe('RoleEdit', () => {
       />,
     );
 
-    expect(screen.getByText('Edit products', { selector: 'code' })).toHaveAttribute(
-      'title',
-      'records.product.edit',
-    );
+    // The label is secondary text; the real key is always shown beside it.
+    expect(screen.getByText('Edit products')).toBeVisible();
+    expect(screen.getByText('records.product.edit', { selector: 'code' })).toBeVisible();
     expect(screen.getByText('records.faq.edit', { selector: 'code' })).toBeVisible();
+    expect(
+      screen.getByRole('switch', { name: 'Edit products (records.product.edit)' }),
+    ).toBeVisible();
+  });
+
+  test('a label never replaces its key, renders as text, and is length-capped', () => {
+    const spoof = 'x'.repeat(200);
+    render(
+      <RoleEdit
+        role={{ id: 'r1', name: 'editor', description: null }}
+        assigned={[]}
+        groups={[
+          {
+            name: 'records',
+            permissions: ['records.admin.delete', 'records.faq.edit'],
+            labels: {
+              'records.admin.delete': '<b>View faq</b> records.faq.edit',
+              'records.faq.edit': spoof,
+            },
+          },
+        ]}
+      />,
+    );
+
+    expect(screen.getByText('records.admin.delete', { selector: 'code' })).toBeVisible();
+    // Markup in a label is shown literally, never interpreted.
+    expect(screen.getByText('<b>View faq</b> records.faq.edit')).toBeVisible();
+    expect(screen.queryByText(spoof)).toBeNull();
+    expect(screen.getByText(`${'x'.repeat(80)}…`)).toBeVisible();
   });
 
   test('renders the deck header, actions and granted summary', () => {

From a5a2008b70bdfe65367ddf0eeb2dd783ad266c99 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Tue, 6 Oct 2026 18:07:41 +0200
Subject: [PATCH 6/6] chore: keep permissions service under the 300-line cap,
 lint fix

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 modules/permissions/permissions/service.py    | 25 ++++++++-----------
 .../tests/test_permissions_runtime_sources.py |  2 +-
 2 files changed, 11 insertions(+), 16 deletions(-)

diff --git a/modules/permissions/permissions/service.py b/modules/permissions/permissions/service.py
index b8229b84..4b101610 100644
--- a/modules/permissions/permissions/service.py
+++ b/modules/permissions/permissions/service.py
@@ -5,6 +5,7 @@
 import uuid
 from typing import TYPE_CHECKING
 
+from simple_module_core.permissions import WILDCARD
 from simple_module_db import LIKE_ESCAPE_CHAR, like_contains_pattern
 from sqlalchemy import delete, func, select
 from sqlalchemy.ext.asyncio import AsyncSession
@@ -99,11 +100,10 @@ async def set_role_permissions(
         if role is None:
             return None
 
-        wanted = {k for k in keys if k in self._registered_keys()}
+        registered = self._registered_keys()
+        wanted = {k for k in keys if k in registered}
         existing = set(await self._get_role_keys(role.name))
-        # Unregistered keys (e.g. a runtime source that is empty right now) are left
-        # alone: pruning them would silently drop grants that return with the source.
-        to_remove = (existing - wanted) & self._registered_keys()
+        to_remove = (existing - wanted) & registered  # unregistered grants are never pruned
 
         if to_remove:
             await self.db.execute(
@@ -117,12 +117,10 @@ async def set_role_permissions(
             for key in wanted - existing
         )
         await self.db.flush()
-        # `map_role` is additive — reset the entry so removals apply without a restart.
-        # No public replace API on PermissionRegistry yet.
+        # `map_role` is additive — reset the role entry so removals take effect without a
+        # restart (no public replace API yet); unregistered grants stay mapped.
         self.registry._role_map.pop(role.name, None)
-        # Keep unregistered-but-stored grants in memory too, so they are live again
-        # the moment their source repopulates.
-        self.registry.map_role(role.name, sorted(wanted | (existing - self._registered_keys())))
+        self.registry.map_role(role.name, sorted(wanted | (existing - registered)))
 
         return RolePermissionsOut(role=role, permissions=sorted(wanted))
 
@@ -194,9 +192,10 @@ async def set_user_permissions(
         if user is None:
             return None
 
-        wanted = {k for k in keys if k in self._registered_keys()}
+        registered = self._registered_keys()
+        wanted = {k for k in keys if k in registered}
         existing = set(await self.get_user_direct_keys(user.id))
-        to_remove = (existing - wanted) & self._registered_keys()
+        to_remove = (existing - wanted) & registered
 
         if to_remove:
             await self.db.execute(
@@ -225,8 +224,6 @@ async def set_user_permissions(
 
     def _resolve_role_permissions(self, role_names: list[str]) -> set[str]:
         """Resolve role names to their permission keys via the registry."""
-        from simple_module_core.permissions import WILDCARD
-
         role_map = self.registry.role_map
         resolved: set[str] = set()
         for name in role_names:
@@ -243,8 +240,6 @@ def _resolve_role_sources(self, role_names: list[str]) -> dict[str, list[str]]:
         know *which* role to edit. Two roles can grant the same key, so the
         value is a list.
         """
-        from simple_module_core.permissions import WILDCARD
-
         role_map = self.registry.role_map
         sources: dict[str, list[str]] = {}
         for name in sorted(role_names):
diff --git a/modules/permissions/tests/test_permissions_runtime_sources.py b/modules/permissions/tests/test_permissions_runtime_sources.py
index 30e9a4bb..f8cd049a 100644
--- a/modules/permissions/tests/test_permissions_runtime_sources.py
+++ b/modules/permissions/tests/test_permissions_runtime_sources.py
@@ -78,7 +78,7 @@ async def test_saving_role_keeps_grants_of_currently_unregistered_source_keys(
 
     # The source goes empty (e.g. restart before its cache warms); an unrelated save
     # must not prune the stored grant.
-    registry.add_source("records", lambda: [])
+    registry.add_source("records", list)
     await authenticated_client.put(url, json={"permissions": []})
 
     async with app.state.sm.db.session_factory() as db: