From c6dfe00f7cbce237ff69aa8e687d199bc201d450 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Wed, 21 Oct 2026 21:22:24 +0200
Subject: [PATCH 01/21] docs: features batch 3 design (#557 #540 #535 #541
 #526)

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 .../2026-10-21-features-batch-3-design.md     | 70 +++++++++++++++++++
 1 file changed, 70 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-10-21-features-batch-3-design.md

diff --git a/docs/superpowers/specs/2026-10-21-features-batch-3-design.md b/docs/superpowers/specs/2026-10-21-features-batch-3-design.md
new file mode 100644
index 000000000..cd1da8b0c
--- /dev/null
+++ b/docs/superpowers/specs/2026-10-21-features-batch-3-design.md
@@ -0,0 +1,70 @@
+# Features batch 3: bulk-write audit, worker images, server-rendered head, SPA mounts, resource access
+
+Approved 2026-10-21 for #557, #540, #535 (step 1), #541, #526 with the defaults below.
+
+## #557 Audit bulk / Core / raw DML (framework/db)
+
+- `simple_module_db/bulk_audit.py`: a `do_orm_execute` listener next to `_mark_dml_written`
+  (`writes.py`). For UPDATE/DELETE on a mapped, audited table (ORM bulk or Core DML on
+  `Model.__table__`, resolved via the model registry): prefetch primary keys with the same WHERE and
+  tenant scope (`include_deleted=True`, limit cap+1), run `execute_state.invoke_statement()`, then
+  hand records to the engine's `audit_callback`.
+- ≤ cap (default 500): one record per id, action `bulk_updated` / `bulk_deleted`, `changes` = SET
+  values; > cap: one summary row, entity_id `"*"`, `{where_sql (no literals), rowcount, truncated}`.
+  INSERT: one summary row. Drop `_EXCLUDED_MIXIN_FIELDS` / `__audit_exclude_fields__`; a statement
+  touching only excluded columns is skipped. Add `heartbeat_at` to `TaskExecution`'s
+  `__audit_exclude_fields__`.
+- `execution_options(sm_audit=False)` opts out; `record_bulk_audit(session, entity_type, action,
+  ids, changes)` is the documented route for `text()` writes.
+- `audit_log` DB setting `refuse_unaudited_dml` (default off): raise on opted-out DML against an
+  audited model. No migration. An audit failure never breaks the write (callback swallows, logs).
+
+## #540 Worker images (framework/cli)
+
+- `smpy docker add-worker <name> --queues --base --apt --extras --modules` writes
+  `docker/worker-<name>.Dockerfile` (Python-only builder, no Node stage, configurable base, apt
+  packages, `uv sync --extra`) and `compose.worker-<name>.yml` (queues/includes via
+  `SM_BG_TASKS_WORKER_QUEUES` / `_INCLUDE_MODULES` and `-Q`), added to `compose.yml` through an
+  idempotent marker-guarded top-level `include:`. Strict regex validation on every input.
+- Docs: heavy deps go in a module optional extra enabled only in the worker image.
+
+## #535 Server-rendered head — step 1 (framework/inertia, hosting, ui)
+
+- `simple_module_inertia.Head` (SQLModel DTO): title, description, canonical, robots, `og: dict`,
+  `twitter: dict`, `json_ld: list[dict]`. `inertia.render(page, props, head=Head(...))`.
+- `{% inertia_head %}` renders it into `<head>` (markupsafe-escaped; JSON-LD via a safe dumps that
+  escapes `</script>`; URLs http(s) only); tags marked so the client head manager replaces them.
+  Also sent as prop `_head`; `packages/ui` `<ServerHead>` re-emits it on client visits.
+- `HostSettings.public_base_url` (DB-backed, read per request) builds canonical / `og:url` — never the
+  request `Host`. Step 2 (Node SSR sidecar) is a separate follow-up; #535 stays open.
+
+## #541 Legacy SPA mounts (core, hosting, ui)
+
+- `SpaMount(prefix, dist_dir, index="index.html", auth="required"|"public")` from a new non-hook
+  override `ModuleBase.spa_mounts()`.
+- `hosting/_spa_mount.py`: StaticFiles subclass; GET/HEAD only; missing extension-less path with
+  `Accept: text/html` → index.html (`no-cache`); missing asset → 404 (never HTML); hashed assets
+  immutable; no request-built paths. `auth="public"` registers the prefix in `PublicRouteRegistry`
+  (GET/HEAD). New SM diagnostic: a mount prefix overlapping a router prefix fails boot.
+- Client: `startSpaLinkInterception({ exclude })`; prefixes reach the client as a framework shared
+  prop `nativePrefixes` (SPA registry + `HostSettings.native_link_prefixes`).
+
+## #526 Resource-scoped access (wave 2)
+
+- Core `simple_module_core/resources.py`: `ResourcePolicy` Protocol (`filter(principal, action,
+  stmt)`, `can(principal, action, obj)`), `ResourceTypeRegistry`, hook `register_resource_types`.
+- Hosting `resource_deps.py`: `RequiresResource(policy, action, loader, permission=None)` — loads via
+  `policy.filter`; invisible → 404, visible but not allowed → 403; a token gate only with
+  `permission=`.
+- DB helper `OwnedResourcePolicy(owner_col, visibility_col=None, share_exists=None, bypass_perm=...)`
+  building `owner==uid OR visibility=='public' OR EXISTS(share)`; explicit bypass permission.
+- Optional `modules/sharing`: table `sharing_resource_share` (resource_type, resource_id,
+  subject_type, subject_id, role, granted_by, expires_at; MultiTenantMixin, AuditMixin; unique incl.
+  tenant_id; hard delete); grant/revoke validated against the registry and the owning module's
+  `can("share")`; grantees via UserDirectory; admin page; migration with branch label `sharing`.
+  Share links deferred.
+
+## Waves
+
+Wave 1 parallel: A #557, B #540, C #535 step 1, D #541 (merge C before D: both touch host
+settings). Wave 2: E #526 core+hosting, then F sharing module.

From a80aaadfffe9272c6fae54e0e33680c144552f59 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Wed, 21 Oct 2026 21:30:02 +0200
Subject: [PATCH 02/21] feat(inertia): server-rendered <head> for public pages
 (#535 step 1)

Head DTO + inertia.render(head=), escaped tags with data-inertia keys, _head prop re-emitted via Inertia serverHead, public_base_url host setting (never the request Host), both index.html templates, docs, tests.

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 CHANGELOG.md                                  |   1 +
 docs/frontend/inertia.md                      |  43 +++++
 docs/reference/env-vars.md                    |   1 +
 .../templates/host/client_app/app.tsx         |   3 +
 .../templates/host/templates/index.html       |   2 +-
 .../simple_module_hosting/_inertia_setup.py   |  10 +-
 .../simple_module_hosting/host_settings.py    |  20 +++
 .../tests/test_server_rendered_head.py        |  63 +++++++
 .../inertia/simple_module_inertia/__init__.py |   3 +
 .../inertia/simple_module_inertia/config.py   |   5 +
 .../inertia/simple_module_inertia/head.py     | 161 ++++++++++++++++++
 .../inertia/simple_module_inertia/inertia.py  |  20 ++-
 .../simple_module_inertia/templating.py       |   5 +-
 framework/inertia/tests/test_adapter_head.py  | 149 ++++++++++++++++
 host/client_app/app.tsx                       |   3 +
 host/templates/index.html                     |   2 +-
 packages/ui/src/lib/server-head.test.ts       |  19 +++
 packages/ui/src/lib/server-head.ts            |  14 ++
 18 files changed, 517 insertions(+), 7 deletions(-)
 create mode 100644 framework/hosting/tests/test_server_rendered_head.py
 create mode 100644 framework/inertia/simple_module_inertia/head.py
 create mode 100644 framework/inertia/tests/test_adapter_head.py
 create mode 100644 packages/ui/src/lib/server-head.test.ts
 create mode 100644 packages/ui/src/lib/server-head.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 94bd54379..3a7f71166 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,7 @@ All notable changes to this project are documented in this file. The format is b
 - `host/client_app` no longer re-declares `@simple-module-py/ui`'s runtime dependencies, nor `@base-ui/react`, `@radix-ui/react-slot`, `autoprefixer` or `postcss` (nothing loaded them) (#521).
 
 ### Added
+- Server-rendered `<head>` for Inertia pages (#535 step 1): `inertia.render(..., head=Head(title, description, canonical, robots, og, twitter, json_ld))` puts the tags in the first response so crawlers and link unfurlers see them without JS; they are also sent as the `_head` prop and re-emitted on client visits via Inertia's `serverHead` (`@simple-module-py/ui/lib/server-head`). URL fields are http(s)-only, JSON-LD cannot close its `<script>`. New `public_base_url` host setting (DB-backed, read per request, no restart) builds canonical / `og:url`; the request `Host` is never used. Both `index.html` templates updated. Body SSR remains open in #535.
 - Release process (#510): `release.yml` runs the whole PR suite (`pr.yml` via
   `workflow_call`) against the dispatched commit and `build` needs it, so nothing
   is built or published from a red commit. The duplicated bump + lockfile steps
diff --git a/docs/frontend/inertia.md b/docs/frontend/inertia.md
index 424d0ec9e..5d1dfeaa8 100644
--- a/docs/frontend/inertia.md
+++ b/docs/frontend/inertia.md
@@ -150,6 +150,49 @@ createInertiaApp({
 `resolvePage` lives in `host/client_app/pages.ts` (hand-written). It builds a page-key → loader map from `moduleGlobs` (the `import.meta.glob` calls in the generated `modules.generated.ts`) plus the host's own `./pages/**/*.tsx` glob, mapping a page key (e.g. `"Orders/Browse"`) to a dynamic import of the matching `.tsx` file.
 
 
+## SEO head
+
+Crawlers and link unfurlers (Slack, LinkedIn) do not run JS, so a React `<Head>` is invisible to
+them. Pass a `Head` to `inertia.render` and the first (document) response carries the tags:
+
+```python
+from simple_module_inertia import Head
+
+return await inertia.render(
+    PAGE_PUBLIC,
+    {"page": page},
+    head=Head(
+        title=page.title,
+        description=page.summary,
+        canonical=f"/p/{page.slug}",
+        og={"image": page.cover_url, "type": "article"},
+        twitter={"card": "summary_large_image"},
+        json_ld=[{"@context": "https://schema.org", "@type": "Article", "name": page.title}],
+    ),
+)
+```
+
+- `title` gets the app-name suffix, as `<Head title>` does. `og:title`, `og:description` and
+  `og:url` default from `title`, `description` and `canonical`; set them in `og` to override.
+- URL fields (`canonical`, and `og`/`twitter` keys `url`, `image`, `image:url`, `video`, `audio`)
+  must be `http(s)` or a site-relative path; anything else (`javascript:`, `data:`, `//host`) raises
+  a validation error when the `Head` is built. Text is HTML-escaped; JSON-LD is serialised so
+  `</script>` and `<!--` inside a value cannot end the element.
+- Relative URLs are joined onto the **`public_base_url`** host setting (Settings, read on every
+  request, no restart). The request `Host` is never used, because it is client-controlled. While
+  it is unset, relative canonical / image URLs are omitted rather than guessed, so set it on any
+  install that serves public pages.
+- Every tag carries a `data-inertia` key, which is how Inertia's client head manager replaces an
+  element instead of appending a duplicate. The same tags are sent as the `_head` prop and
+  `app.tsx` passes `serverHead: resolveServerHead` (`@simple-module-py/ui/lib/server-head`), so
+  client-side visits keep the head in step with no per-page code. A page that passes no `head` falls
+  back to the branded default title.
+- A custom root template needs `{% inertia_head %}` plus
+  `{% if not (inertia and inertia.has_head_title) %}<title ...>{% endif %}` around its static
+  title (the shipped `host/templates/index.html` does this).
+
+This is server-rendered **head** only; body SSR (a Node sidecar) is a separate step in #535.
+
 ## Link navigation
 
 The app is client-rendered: the root template ships `<div id="app"></div>` empty
diff --git a/docs/reference/env-vars.md b/docs/reference/env-vars.md
index ef20a05fc..a1fea7ed1 100644
--- a/docs/reference/env-vars.md
+++ b/docs/reference/env-vars.md
@@ -52,6 +52,7 @@ Which source actually wins depends on the field, because `HostSettings` is consu
 | `i18n_cookie_name` | `SM_I18N_COOKIE_NAME` | `locale` | **env at boot** | Cookie storing the selected locale. |
 | `maintenance_mode` | *(none — see below)* | `false` | **DB at request time** | Serve everyone but admins a 503. DB-backed so flipping it needs no redeploy — see [Deployment](/reference/deployment#maintenance-mode). |
 | `maintenance_message` | *(none — see below)* | `""` | **DB at request time** | Optional operator note on the maintenance page. |
+| `public_base_url` | `SM_PUBLIC_BASE_URL` | `""` | **DB at request time** | Public origin (`https://example.org`) for canonical / `og:url` in the server-rendered head. Never taken from the request `Host`. See [Inertia](/frontend/inertia#seo-head). |
 
 The split is not arbitrary. The boot instance (`Settings()`, env-derived) lands on `app.state.sm.settings` and is what configures middleware at construction — `LocaleMiddleware` captures its locale set there, and the tenancy flag decides whether `TenantMiddleware` is added at all. The DB-hydrated instance is a plain `HostSettings` on `app.state.host.settings`, which declares no `env_prefix` and so is defaults-plus-overrides; `MaintenanceMiddleware` reads that one on every request.
 
diff --git a/framework/cli/simple_module_cli/templates/host/client_app/app.tsx b/framework/cli/simple_module_cli/templates/host/client_app/app.tsx
index 5af66a8bc..661b68332 100644
--- a/framework/cli/simple_module_cli/templates/host/client_app/app.tsx
+++ b/framework/cli/simple_module_cli/templates/host/client_app/app.tsx
@@ -1,6 +1,7 @@
 import { createInertiaApp, router } from '@inertiajs/react';
 import { configureI18n, updateI18n } from '@simple-module-py/i18n';
 import { formatTitle, setTitleAppName } from '@simple-module-py/ui/lib/app-title';
+import { resolveServerHead } from '@simple-module-py/ui/lib/server-head';
 import { startSpaLinkInterception } from '@simple-module-py/ui/lib/spa-links';
 import { initTheme } from '@simple-module-py/ui/lib/theme';
 import { createRoot } from 'react-dom/client';
@@ -14,6 +15,8 @@ type I18nBlock = {
 
 createInertiaApp({
   title: (title) => formatTitle(title),
+  // Re-emits the `_head` prop (server-rendered SEO tags) on client visits.
+  serverHead: resolveServerHead,
   resolve: async (name) => {
     return await resolvePage(name);
   },
diff --git a/framework/cli/simple_module_cli/templates/host/templates/index.html b/framework/cli/simple_module_cli/templates/host/templates/index.html
index 5e17296c0..5ef0da519 100644
--- a/framework/cli/simple_module_cli/templates/host/templates/index.html
+++ b/framework/cli/simple_module_cli/templates/host/templates/index.html
@@ -7,7 +7,7 @@
        crawlers and link previews see the configured site name before React
        hydrates; Inertia's <Head> takes over per-page titles after that. #}
     {% set brand = branding_head(request) %}
-    <title data-inertia="">{{ brand.app_name }}</title>
+    {% if not (inertia and inertia.has_head_title) %}<title data-inertia="">{{ brand.app_name }}</title>{% endif %}
     {% if brand.theme_color %}<meta name="theme-color" content="{{ brand.theme_color }}" />{% endif %}
     {% if brand.favicon_url %}<link rel="icon" href="{{ brand.favicon_url }}" />{% endif %}
     <link rel="preconnect" href="https://fonts.googleapis.com" />
diff --git a/framework/hosting/simple_module_hosting/_inertia_setup.py b/framework/hosting/simple_module_hosting/_inertia_setup.py
index c1213e836..084fb6753 100644
--- a/framework/hosting/simple_module_hosting/_inertia_setup.py
+++ b/framework/hosting/simple_module_hosting/_inertia_setup.py
@@ -6,7 +6,7 @@
 from pathlib import Path
 
 from fastapi import FastAPI
-from simple_module_inertia import InertiaConfig, inertia_dependency_factory
+from simple_module_inertia import InertiaConfig, SiteInfo, inertia_dependency_factory
 from starlette.requests import Request
 
 from simple_module_hosting._favicon import default_favicon_data_uri
@@ -66,6 +66,13 @@ def branding_head(request: Request) -> dict:
     }
 
 
+def site_info(request: Request) -> SiteInfo:
+    """The public base URL (operator setting, never the request ``Host``) and app name."""
+    host = getattr(request.app.state, "host", None)
+    base_url = getattr(getattr(host, "settings", None), "public_base_url", "") or ""
+    return SiteInfo(base_url=base_url, app_name=branding_head(request)["app_name"])
+
+
 def _prod_manifest_path(project_root: Path) -> str:
     """The Vite manifest to read in production, or ``""`` when none is built."""
     candidates = [
@@ -149,6 +156,7 @@ def setup_inertia(
         entrypoint_filename=_ENTRYPOINT_FILENAME,
         root_directory=_ROOT_DIRECTORY,
         use_flash_errors=True,
+        site=site_info,
     )
     app.state.inertia_dependency = inertia_dependency_factory(inertia_config)
     return inertia_config
diff --git a/framework/hosting/simple_module_hosting/host_settings.py b/framework/hosting/simple_module_hosting/host_settings.py
index 0fdddc47b..4249ebdd8 100644
--- a/framework/hosting/simple_module_hosting/host_settings.py
+++ b/framework/hosting/simple_module_hosting/host_settings.py
@@ -108,6 +108,13 @@ class HostSettings(BaseSettings):
     i18n_supported_locales: list[str] = Field(default=["en"], json_schema_extra=_RESTART_I18N)
     i18n_cookie_name: str = Field(default="locale", json_schema_extra=_RESTART_I18N)
 
+    public_base_url: str = ""
+    """The site's public origin, e.g. ``https://example.org``, used to build the
+    canonical and ``og:url`` in the server-rendered ``<head>``. Never derived
+    from the request ``Host`` (spoofable): while blank, relative canonical /
+    image URLs are omitted rather than guessed. Read per request, so an edit
+    applies without a restart."""
+
     log_level: str = Field(default="INFO", json_schema_extra=_RESTART_LOGGING)
     log_format: Literal["json", "text"] = Field(default="json", json_schema_extra=_RESTART_LOGGING)
 
@@ -187,6 +194,19 @@ class HostSettings(BaseSettings):
     db_pool_pre_ping: bool = Field(default=True, json_schema_extra=_RESTART_DB)
     db_pool_recycle: int = Field(default=1800, json_schema_extra=_RESTART_DB)
 
+    @field_validator("public_base_url", mode="after")
+    @classmethod
+    def _check_public_base_url(cls, value: str) -> str:
+        from urllib.parse import urlsplit
+
+        value = value.strip().rstrip("/")
+        parts = urlsplit(value)
+        if value and not (parts.scheme in ("http", "https") and parts.netloc):
+            raise ValueError(
+                "public_base_url must be an http(s) origin such as https://example.org"
+            )
+        return value
+
     @field_validator("rate_limit_public", "rate_limit_authenticated", mode="after")
     @classmethod
     def _check_rate(cls, value: str) -> str:
diff --git a/framework/hosting/tests/test_server_rendered_head.py b/framework/hosting/tests/test_server_rendered_head.py
new file mode 100644
index 000000000..cd05f81de
--- /dev/null
+++ b/framework/hosting/tests/test_server_rendered_head.py
@@ -0,0 +1,63 @@
+"""#535 step 1 through the real host: template, branding title, ``public_base_url``."""
+
+from __future__ import annotations
+
+import pytest
+from pydantic import ValidationError
+from simple_module_hosting.host_settings import HostSettings
+from simple_module_hosting.inertia_deps import InertiaDep
+from simple_module_inertia import Head
+
+_PATH = "/__seo_probe"
+_BASE = "https://example.org"
+
+
+@pytest.fixture
+def probe(app):
+    @app.get(_PATH)
+    async def _probe(inertia: InertiaDep):
+        head = Head(
+            title="Probe",
+            description="desc",
+            canonical="/probe",
+            og={"image": "/i.png"},
+            json_ld=[{"@type": "WebPage", "name": "</script><script>x</script>"}],
+        )
+        return await inertia.render("Probe/Page", {}, head=head)
+
+    app.state.host.settings.public_base_url = _BASE
+    return app
+
+
+async def test_first_response_has_head_tags_without_js(probe, authenticated_client) -> None:
+    html = (await authenticated_client.get(_PATH)).text
+    assert html.count("<title") == 1
+    assert '<title data-inertia="">Probe — ' in html
+    assert 'rel="canonical" href="https://example.org/probe"' in html
+    assert 'property="og:url" content="https://example.org/probe"' in html
+    assert 'property="og:image" content="https://example.org/i.png"' in html
+    assert "</script><script>x" not in html
+
+
+async def test_forged_host_never_reaches_canonical(probe, authenticated_client) -> None:
+    html = (await authenticated_client.get(_PATH, headers={"Host": "attacker.test"})).text
+    assert "attacker.test" not in html
+    assert 'href="https://example.org/probe"' in html
+
+
+async def test_public_base_url_is_read_per_request(probe, authenticated_client) -> None:
+    probe.state.host.settings.public_base_url = "https://other.example"
+    html = (await authenticated_client.get(_PATH)).text
+    assert 'href="https://other.example/probe"' in html
+
+
+async def test_client_visit_gets_head_prop(probe, authenticated_client) -> None:
+    body = (await authenticated_client.get(_PATH, headers={"X-Inertia": "true"})).json()
+    assert any('rel="canonical"' in tag for tag in body["props"]["_head"])
+
+
+def test_public_base_url_validation() -> None:
+    assert HostSettings(public_base_url=" https://example.org/ ").public_base_url == _BASE
+    assert HostSettings(public_base_url="").public_base_url == ""
+    with pytest.raises(ValidationError):
+        HostSettings(public_base_url="javascript:alert(1)")
diff --git a/framework/inertia/simple_module_inertia/__init__.py b/framework/inertia/simple_module_inertia/__init__.py
index 8e6d1003f..18eed017e 100644
--- a/framework/inertia/simple_module_inertia/__init__.py
+++ b/framework/inertia/simple_module_inertia/__init__.py
@@ -9,6 +9,7 @@
     inertia_request_validation_exception_handler,
     inertia_version_conflict_exception_handler,
 )
+from simple_module_inertia.head import Head, SiteInfo
 from simple_module_inertia.inertia import Inertia
 from simple_module_inertia.page import PropEncodingError
 from simple_module_inertia.props import (
@@ -26,12 +27,14 @@
 from simple_module_inertia.templating import InertiaExtension
 
 __all__ = [
+    "Head",
     "Inertia",
     "InertiaConfig",
     "InertiaExtension",
     "InertiaResponse",
     "InertiaVersionConflictException",
     "PropEncodingError",
+    "SiteInfo",
     "always",
     "deep_merge",
     "defer",
diff --git a/framework/inertia/simple_module_inertia/config.py b/framework/inertia/simple_module_inertia/config.py
index 7dda14afd..97bb5d530 100644
--- a/framework/inertia/simple_module_inertia/config.py
+++ b/framework/inertia/simple_module_inertia/config.py
@@ -14,6 +14,8 @@
 
 from fastapi.templating import Jinja2Templates
 
+from simple_module_inertia.head import SiteResolver
+
 
 @dataclass
 class InertiaConfig:
@@ -33,6 +35,9 @@ class InertiaConfig:
     flash_error_key: str = "errors"
     assets_prefix: str = ""
     extra_template_context: dict[str, Any] = field(default_factory=dict)
+    site: SiteResolver | None = None
+    """Per-request ``SiteInfo`` (public base URL, app name) for server-rendered
+    ``<head>`` tags. Read on every render so an edited setting applies live."""
 
 
 def resolved_version(config: InertiaConfig) -> str:
diff --git a/framework/inertia/simple_module_inertia/head.py b/framework/inertia/simple_module_inertia/head.py
new file mode 100644
index 000000000..eabe1b104
--- /dev/null
+++ b/framework/inertia/simple_module_inertia/head.py
@@ -0,0 +1,161 @@
+"""Server-rendered ``<head>`` (#535 step 1).
+
+A view passes ``head=Head(...)`` to ``inertia.render``. The first (document)
+response renders it into ``<head>`` so crawlers and link unfurlers that do not
+run JS see the title, description, Open Graph tags, canonical and JSON-LD. The
+same tags travel as the ``_head`` prop (a list of HTML strings); Inertia v3's
+``serverHead`` option re-emits them on every client visit.
+
+Every tag carries a ``data-inertia`` key, which is how Inertia's client head
+manager recognises an element it may replace instead of appending a duplicate.
+Nothing here trusts the request ``Host``: relative URLs are joined onto
+``SiteInfo.base_url`` (the operator-set public URL), or dropped when it is unset.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import urljoin, urlsplit
+
+from jinja2.utils import htmlsafe_json_dumps
+from markupsafe import Markup, escape
+from pydantic import BaseModel, Field, field_validator, model_validator
+from starlette.requests import Request
+
+HEAD_PROP = "_head"
+TITLE_SEPARATOR = " — "
+_KEY_ATTR = "data-inertia"
+_KEY_RE = re.compile(r"^[a-z][a-z0-9_.:-]*$")
+_ROBOTS_RE = re.compile(r"^[a-z][a-z0-9, -]*$")
+_URL_KEYS = frozenset({"url", "image", "image:url", "image:secure_url", "video", "audio"})
+_OG = "og"
+_TWITTER = "twitter"
+
+
+@dataclass(frozen=True)
+class SiteInfo:
+    """Per-request site facts the head needs; supplied by the host."""
+
+    base_url: str = ""
+    app_name: str = ""
+
+
+SiteResolver = Callable[[Request], SiteInfo]
+
+
+def _is_http_url(value: str) -> bool:
+    parts = urlsplit(value)
+    return parts.scheme in ("http", "https") and bool(parts.netloc)
+
+
+def _is_site_path(value: str) -> bool:
+    return value.startswith("/") and not value.startswith("//") and "\\" not in value
+
+
+def _check_url(value: str, *, what: str) -> str:
+    value = value.strip()
+    if _is_http_url(value) or _is_site_path(value):
+        return value
+    raise ValueError(f"{what} must be an http(s) URL or a site-relative path")
+
+
+class Head(BaseModel):
+    """Head metadata for one page. URLs are http(s) only (or site-relative)."""
+
+    title: str = ""
+    description: str = ""
+    canonical: str = ""
+    robots: str = ""
+    og: dict[str, str] = Field(default_factory=dict)
+    twitter: dict[str, str] = Field(default_factory=dict)
+    json_ld: list[dict[str, Any]] = Field(default_factory=list)
+
+    @field_validator("canonical")
+    @classmethod
+    def _canonical(cls, value: str) -> str:
+        return _check_url(value, what="canonical") if value else value
+
+    @field_validator("robots")
+    @classmethod
+    def _robots(cls, value: str) -> str:
+        value = value.strip().lower()
+        if value and not _ROBOTS_RE.match(value):
+            raise ValueError("robots must be a comma-separated list of directives")
+        return value
+
+    @model_validator(mode="after")
+    def _check_maps(self) -> Head:
+        for prefix, mapping in ((_OG, self.og), (_TWITTER, self.twitter)):
+            for key, value in mapping.items():
+                if not _KEY_RE.match(key):
+                    raise ValueError(f"invalid {prefix} key {key!r}")
+                if key in _URL_KEYS:
+                    _check_url(value, what=f"{prefix}:{key}")
+        return self
+
+
+def _absolute(value: str, base_url: str) -> str | None:
+    """``value`` as an absolute URL, or ``None`` when it needs a base we lack."""
+    if _is_http_url(value):
+        return value
+    return urljoin(base_url.rstrip("/") + "/", value.lstrip("/")) if base_url else None
+
+
+def _tag(name: str, key: str, attrs: dict[str, str]) -> str:
+    parts = " ".join(f'{k}="{escape(v)}"' for k, v in {_KEY_ATTR: key, **attrs}.items())
+    return f"<{name} {parts}>"
+
+
+def _meta_tags(head: Head, base_url: str) -> list[str]:
+    tags: list[str] = []
+    if head.description:
+        tags.append(
+            _tag("meta", "sm-description", {"name": "description", "content": head.description})
+        )
+    if head.robots:
+        tags.append(_tag("meta", "sm-robots", {"name": "robots", "content": head.robots}))
+    canonical = _absolute(head.canonical, base_url) if head.canonical else None
+    if canonical:
+        tags.append(_tag("link", "sm-canonical", {"rel": "canonical", "href": canonical}))
+    og = dict(head.og)
+    if head.title:
+        og.setdefault("title", head.title)
+    if head.description:
+        og.setdefault("description", head.description)
+    if canonical:
+        og.setdefault("url", canonical)
+    for prefix, attr, mapping in ((_OG, "property", og), (_TWITTER, "name", head.twitter)):
+        for key, value in mapping.items():
+            if key in _URL_KEYS:
+                resolved = _absolute(value, base_url)
+                if resolved is None:
+                    continue
+                value = resolved
+            full = f"{prefix}:{key}"
+            tags.append(_tag("meta", f"sm-{prefix}-{key}", {attr: full, "content": value}))
+    return tags
+
+
+def head_tags(head: Head, site: SiteInfo) -> list[str]:
+    """The escaped HTML tags for ``head``, each carrying a ``data-inertia`` key."""
+    tags: list[str] = []
+    if head.title:
+        title = head.title.strip()
+        full = f"{title}{TITLE_SEPARATOR}{site.app_name}" if site.app_name else title
+        tags.append(f'<title {_KEY_ATTR}="">{escape(full)}</title>')
+    tags.extend(_meta_tags(head, site.base_url))
+    for index, doc in enumerate(head.json_ld):
+        # htmlsafe_json_dumps escapes < > & ' so ``</script>`` and ``<!--`` in a
+        # value cannot end the element or open an HTML comment.
+        body = htmlsafe_json_dumps(doc)
+        tags.append(
+            f'<script {_KEY_ATTR}="sm-jsonld-{index}" type="application/ld+json">{body}</script>'
+        )
+    return tags
+
+
+def head_markup(tags: list[str]) -> Markup:
+    return Markup("\n".join(tags))
diff --git a/framework/inertia/simple_module_inertia/inertia.py b/framework/inertia/simple_module_inertia/inertia.py
index 6d0a28144..a4c0304ea 100644
--- a/framework/inertia/simple_module_inertia/inertia.py
+++ b/framework/inertia/simple_module_inertia/inertia.py
@@ -11,6 +11,7 @@
 
 from simple_module_inertia.config import InertiaConfig, resolved_version
 from simple_module_inertia.errors import InertiaVersionConflictException
+from simple_module_inertia.head import HEAD_PROP, Head, SiteInfo, head_tags
 from simple_module_inertia.manifest import entry_assets
 from simple_module_inertia.page import build_page, encode_page
 from simple_module_inertia.request import InertiaRequest
@@ -95,7 +96,10 @@ def _pop_session(self, key: str, default: Any) -> Any:
         return session.pop(key) if key in session else default
 
     async def render(
-        self, component: str, props: dict[str, Any] | BaseModel | None = None
+        self,
+        component: str,
+        props: dict[str, Any] | BaseModel | None = None,
+        head: Head | None = None,
     ) -> InertiaResponse:
         page_props: dict[str, Any] = (
             props.model_dump() if isinstance(props, BaseModel) else dict(props or {})
@@ -108,6 +112,12 @@ async def render(
         if self._config.flash_error_key != "errors":
             page_props[self._config.flash_error_key] = errors
 
+        tags: list[str] = []
+        if head is not None:
+            site = self._config.site(self._request) if self._config.site else SiteInfo()
+            tags = head_tags(head, site)
+            page_props[HEAD_PROP] = tags
+
         resolved = await resolve_props(page_props, self._shared, component, self._req)
         page = build_page(
             component=component,
@@ -121,9 +131,11 @@ async def render(
         )
         if self._req.is_inertia:
             return json_response(page)
-        return self._render_html(page)
+        return self._render_html(page, tags, head is not None and bool(head.title))
 
-    def _render_html(self, page: dict[str, Any]) -> InertiaResponse:
+    def _render_html(
+        self, page: dict[str, Any], tags: list[str], has_title: bool
+    ) -> InertiaResponse:
         files = entry_assets(self._config)
         # encode_page yields a JSON-safe dict; htmlsafe_json_dumps serialises it
         # exactly once with HTML-safe escaping. Passing a pre-dumped string here
@@ -137,6 +149,8 @@ def _render_html(self, page: dict[str, Any]) -> InertiaResponse:
                 data=cast(str, page_json),
                 js=files.js,
                 css=files.css,
+                head_tags=tags,
+                has_head_title=has_title,
             ),
             **self._config.extra_template_context,
         }
diff --git a/framework/inertia/simple_module_inertia/templating.py b/framework/inertia/simple_module_inertia/templating.py
index 79780d3a3..9f883ef08 100644
--- a/framework/inertia/simple_module_inertia/templating.py
+++ b/framework/inertia/simple_module_inertia/templating.py
@@ -6,7 +6,7 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import Literal
 
 from jinja2 import nodes
@@ -26,6 +26,8 @@ class InertiaContext:
     data: str | None = None
     ssr_head: str | None = None
     ssr_body: str | None = None
+    head_tags: list[str] = field(default_factory=list)
+    has_head_title: bool = False
 
 
 class InertiaExtension(Extension):
@@ -49,6 +51,7 @@ def _render_inertia_head(self, context: Context) -> Markup:
                 raise ValueError("SSR is enabled but no SSR head was provided")
             fragments.append(inertia.ssr_head)
         fragments.extend(f'<link rel="stylesheet" href="{css}">' for css in inertia.css)
+        fragments.extend(inertia.head_tags)
         return Markup("\n".join(fragments))
 
     def _render_inertia_body(self, context: Context) -> Markup:
diff --git a/framework/inertia/tests/test_adapter_head.py b/framework/inertia/tests/test_adapter_head.py
new file mode 100644
index 000000000..3039d771d
--- /dev/null
+++ b/framework/inertia/tests/test_adapter_head.py
@@ -0,0 +1,149 @@
+"""Server-rendered ``<head>``: escaping, URL policy, markers, the ``_head`` prop."""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+import pytest
+from fastapi import Depends, FastAPI
+from fastapi.templating import Jinja2Templates
+from httpx import ASGITransport, AsyncClient
+from pydantic import ValidationError
+from simple_module_inertia import (
+    Head,
+    Inertia,
+    InertiaConfig,
+    SiteInfo,
+    inertia_dependency_factory,
+)
+from simple_module_inertia.head import head_tags
+from starlette.middleware.sessions import SessionMiddleware
+
+TEMPLATE = (
+    "<!doctype html><html><head>"
+    '{% if not inertia.has_head_title %}<title data-inertia="">Default</title>{% endif %}'
+    "{% inertia_head %}</head><body>{% inertia_body %}</body></html>"
+)
+BASE = "https://example.org"
+EVIL = "</script><script>alert(1)</script><!--"
+
+
+def _app(tmp_path: Path, head: Head | None, base_url: str = BASE) -> FastAPI:
+    (tmp_path / "index.html").write_text(TEMPLATE)
+    config = InertiaConfig(
+        templates=Jinja2Templates(directory=str(tmp_path)),
+        entrypoint_filename="main.tsx",
+        root_directory=".",
+        site=lambda _request: SiteInfo(base_url=base_url, app_name="Acme"),
+    )
+    dep = inertia_dependency_factory(config)
+    app = FastAPI()
+    app.add_middleware(SessionMiddleware, secret_key="test")
+
+    @app.get("/p")
+    async def page(inertia: Inertia = Depends(dep)):
+        return await inertia.render("Public/Page", {}, head=head)
+
+    return app
+
+
+def _client(app: FastAPI) -> AsyncClient:
+    return AsyncClient(transport=ASGITransport(app=app), base_url="http://evil.example")
+
+
+async def test_document_carries_title_meta_og_and_canonical(tmp_path) -> None:
+    head = Head(
+        title="Maps",
+        description='A "quoted" <b>desc</b>',
+        canonical="/maps",
+        robots="noindex, follow",
+        og={"image": "/img/a.png", "type": "website"},
+        twitter={"card": "summary"},
+    )
+    async with _client(_app(tmp_path, head)) as client:
+        html = (await client.get("/p")).text
+    assert html.count("<title") == 1
+    assert '<title data-inertia="">Maps — Acme</title>' in html
+    assert 'name="description"' in html and "&#34;quoted&#34; &lt;b&gt;" in html
+    assert 'rel="canonical" href="https://example.org/maps"' in html
+    assert 'property="og:url" content="https://example.org/maps"' in html
+    assert 'property="og:title" content="Maps"' in html
+    assert 'property="og:image" content="https://example.org/img/a.png"' in html
+    assert 'name="twitter:card" content="summary"' in html
+    assert 'name="robots" content="noindex, follow"' in html
+    assert "Default" not in html
+
+
+async def test_no_head_keeps_the_template_default_title(tmp_path) -> None:
+    async with _client(_app(tmp_path, None)) as client:
+        html = (await client.get("/p")).text
+    assert '<title data-inertia="">Default</title>' in html
+    assert "og:" not in html
+
+
+async def test_forged_host_does_not_change_canonical(tmp_path) -> None:
+    app = _app(tmp_path, Head(title="T", canonical="/maps"))
+    async with _client(app) as client:
+        html = (await client.get("/p", headers={"Host": "attacker.test"})).text
+    assert "attacker" not in html
+    assert 'href="https://example.org/maps"' in html
+
+
+async def test_relative_urls_are_dropped_without_a_base_url(tmp_path) -> None:
+    app = _app(tmp_path, Head(title="T", canonical="/maps", og={"image": "/a.png"}), base_url="")
+    async with _client(app) as client:
+        html = (await client.get("/p")).text
+    assert "canonical" not in html
+    assert "og:image" not in html and "og:url" not in html
+
+
+async def test_json_ld_cannot_break_out_of_the_script_element(tmp_path) -> None:
+    head = Head(title="T", json_ld=[{"@type": "Article", "name": EVIL}])
+    async with _client(_app(tmp_path, head)) as client:
+        html = (await client.get("/p")).text
+    block = re.search(r'<script data-inertia="sm-jsonld-0"[^>]*>(.*?)</script>', html, re.S)
+    assert block is not None
+    assert "<" not in block.group(1) and ">" not in block.group(1)
+    assert json.loads(block.group(1))["name"] == EVIL
+    assert "<script>alert(1)" not in html
+
+
+async def test_titles_and_text_are_escaped(tmp_path) -> None:
+    async with _client(_app(tmp_path, Head(title=EVIL))) as client:
+        html = (await client.get("/p")).text
+    assert "<script>alert(1)" not in html
+
+
+async def test_inertia_visit_carries_head_prop_with_replaceable_keys(tmp_path) -> None:
+    head = Head(title="Maps", description="d", canonical="/maps")
+    async with _client(_app(tmp_path, head)) as client:
+        body = (await client.get("/p", headers={"X-Inertia": "true"})).json()
+    tags = body["props"]["_head"]
+    assert any(t.startswith("<title") for t in tags)
+    assert all('data-inertia="' in t for t in tags)
+
+
+@pytest.mark.parametrize(
+    "bad",
+    [
+        {"canonical": "javascript:alert(1)"},
+        {"canonical": "//evil.example/x"},
+        {"canonical": "data:text/html,x"},
+        {"og": {"image": "javascript:alert(1)"}},
+        {"og": {"url": "ftp://x/y"}},
+        {"twitter": {"image": "data:image/png;base64,AAAA"}},
+        {"og": {'x" onload="y': "v"}},
+        {"robots": "<script>"},
+    ],
+)
+def test_non_http_urls_and_bad_keys_are_rejected(bad) -> None:
+    with pytest.raises(ValidationError):
+        Head(**bad)
+
+
+def test_head_tags_use_only_data_inertia_keyed_elements() -> None:
+    tags = head_tags(Head(title="T", description="d"), SiteInfo(app_name=""))
+    assert tags[0] == '<title data-inertia="">T</title>'
+    assert all("data-inertia" in t for t in tags)
diff --git a/host/client_app/app.tsx b/host/client_app/app.tsx
index f3f147907..db8ab3a75 100644
--- a/host/client_app/app.tsx
+++ b/host/client_app/app.tsx
@@ -2,6 +2,7 @@ import { createInertiaApp, router } from '@inertiajs/react';
 import { ErrorBoundary } from '@simple-module-py/ui/components/ErrorBoundary';
 import { OfflineBanner } from '@simple-module-py/ui/components/OfflineBanner';
 import { formatTitle, setTitleAppName } from '@simple-module-py/ui/lib/app-title';
+import { resolveServerHead } from '@simple-module-py/ui/lib/server-head';
 import { startSpaLinkInterception } from '@simple-module-py/ui/lib/spa-links';
 import { initTheme } from '@simple-module-py/ui/lib/theme';
 import { useEffect, useRef } from 'react';
@@ -16,6 +17,8 @@ import { resolvePage } from './pages';
 // the pre-hydration tab is already branded.
 createInertiaApp({
   title: (title) => formatTitle(title),
+  // Re-emits the `_head` prop (server-rendered SEO tags) on client visits.
+  serverHead: resolveServerHead,
   resolve: async (name) => {
     const page = await resolvePage(name);
     return page;
diff --git a/host/templates/index.html b/host/templates/index.html
index a8f357b5d..5fb91771a 100644
--- a/host/templates/index.html
+++ b/host/templates/index.html
@@ -36,7 +36,7 @@
        <title data-inertia=""> is *appended* instead, leaving two title elements.
        The browser then uses the first in document order, so every page showed
        the bare app name and no <Head title> ever took effect. #}
-    <title data-inertia="">{{ _brand.app_name }}</title>
+    {% if not (inertia and inertia.has_head_title) %}<title data-inertia="">{{ _brand.app_name }}</title>{% endif %}
     {% if _brand.theme_color %}<meta name="theme-color" content="{{ _brand.theme_color }}" />{% endif %}
     {% if _brand.favicon_url %}<link rel="icon" href="{{ _brand.favicon_url }}" />{% endif %}
     <link rel="preconnect" href="https://fonts.googleapis.com" />
diff --git a/packages/ui/src/lib/server-head.test.ts b/packages/ui/src/lib/server-head.test.ts
new file mode 100644
index 000000000..76412fc50
--- /dev/null
+++ b/packages/ui/src/lib/server-head.test.ts
@@ -0,0 +1,19 @@
+import { describe, expect, test } from 'vitest';
+import { resolveServerHead } from './server-head';
+
+describe('resolveServerHead', () => {
+  test('returns the _head tags', () => {
+    const tags = ['<title data-inertia="">A</title>', '<meta data-inertia="x" name="a">'];
+    expect(resolveServerHead({ props: { _head: tags } })).toEqual(tags);
+  });
+
+  test('is empty when the page sent no head', () => {
+    expect(resolveServerHead({ props: {} })).toEqual([]);
+    expect(resolveServerHead({})).toEqual([]);
+  });
+
+  test('ignores a malformed prop and non-string entries', () => {
+    expect(resolveServerHead({ props: { _head: 'nope' } })).toEqual([]);
+    expect(resolveServerHead({ props: { _head: ['<meta>', 3, null] } })).toEqual(['<meta>']);
+  });
+});
diff --git a/packages/ui/src/lib/server-head.ts b/packages/ui/src/lib/server-head.ts
new file mode 100644
index 000000000..a353d7fad
--- /dev/null
+++ b/packages/ui/src/lib/server-head.ts
@@ -0,0 +1,14 @@
+/**
+ * Inertia v3 `serverHead` resolver for the `_head` prop that a view's
+ * `inertia.render(..., head=Head(...))` sends (#535).
+ *
+ * Returning the tags lets Inertia's head manager re-emit them on every client
+ * visit, replacing the server-rendered ones by their `data-inertia` key rather
+ * than duplicating them, and drop them when the next page sends none.
+ */
+export const SERVER_HEAD_PROP = '_head';
+
+export function resolveServerHead(page: { props?: Record<string, unknown> }): string[] {
+  const tags = page.props?.[SERVER_HEAD_PROP];
+  return Array.isArray(tags) ? tags.filter((t): t is string => typeof t === 'string') : [];
+}

From 6d3885f2282df7cd883a82aeb37c7713046c3620 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Wed, 21 Oct 2026 21:30:20 +0200
Subject: [PATCH 03/21] feat(cli): smpy docker add-worker scaffolds separately
 built worker images (#540)

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 CHANGELOG.md                                  |   2 +
 docs/reference/deployment.md                  |  22 +++
 framework/cli/simple_module_cli/cli.py        |   2 +
 framework/cli/simple_module_cli/docker_cmd.py | 158 ++++++++++++++++++
 .../templates/docker/compose-worker.yml.tpl   |  12 ++
 .../templates/docker/worker.Dockerfile.tpl    |  27 +++
 .../cli/tests/test_cli_docker_workers.py      | 150 +++++++++++++++++
 7 files changed, 373 insertions(+)
 create mode 100644 framework/cli/simple_module_cli/docker_cmd.py
 create mode 100644 framework/cli/simple_module_cli/templates/docker/compose-worker.yml.tpl
 create mode 100644 framework/cli/simple_module_cli/templates/docker/worker.Dockerfile.tpl
 create mode 100644 framework/cli/tests/test_cli_docker_workers.py

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 94bd54379..21afde2e1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,8 @@ All notable changes to this project are documented in this file. The format is b
 - `host/client_app` no longer re-declares `@simple-module-py/ui`'s runtime dependencies, nor `@base-ui/react`, `@radix-ui/react-slot`, `autoprefixer` or `postcss` (nothing loaded them) (#521).
 
 ### Added
+
+- `smpy docker add-worker` generates dedicated Python worker images with validated apt packages, optional extras, queue/module routing, and idempotent Compose includes (#540).
 - Release process (#510): `release.yml` runs the whole PR suite (`pr.yml` via
   `workflow_call`) against the dispatched commit and `build` needs it, so nothing
   is built or published from a red commit. The duplicated bump + lockfile steps
diff --git a/docs/reference/deployment.md b/docs/reference/deployment.md
index c2c12b657..0741b8abf 100644
--- a/docs/reference/deployment.md
+++ b/docs/reference/deployment.md
@@ -73,6 +73,28 @@ A default (SQLite) scaffold's compose file also pins `SM_DATABASE_URL=sqlite+aio
 The reason it isn't just a URL swap: a migration history is **dialect-frozen at autogenerate time** (`sa.false()` renders as `DEFAULT 0` under SQLite, which Postgres rejects), so containers must run the same dialect the migrations were generated against. Moving an existing SQLite scaffold to Postgres means regenerating migrations against Postgres, not editing one env var.
 :::
 
+### Additional worker images
+
+Put heavy Python dependencies in a module's optional extra (for example,
+`[project.optional-dependencies]` with `gdal = ["GDAL"]`). Enable that extra
+only in a dedicated worker image so the web image stays small:
+
+```bash
+smpy docker add-worker geo --queues geo --modules geo.tasks \
+  --apt libgdal-dev --extras gdal
+```
+
+Run this in the project root with an existing `worker` service. It writes
+`docker/worker-geo.Dockerfile` and `compose.worker-geo.yml`, then adds a marked
+`include:` entry to `compose.yml` (or the scaffold's `docker-compose.yml`). The
+Python-only image installs apt packages in both build and runtime stages and
+inherits the existing worker's database, broker, volumes, and dependencies.
+Repeat `--apt` and `--extras` for additional packages and extras; `--queues`
+and `--modules` take comma-separated lists. `--base` selects a compatible
+Debian-based Python image (default `python:3.12-slim-bookworm`). The healthcheck
+pings this worker through Celery. Use `--force` to regenerate an existing
+worker's files; repeated runs never duplicate its include entry.
+
 ### Why the image has one builder stage
 
 The obvious split — a Python stage and a Node stage — **cannot work here**. The Vite build imports `modules.generated.{ts,css}`, which `gen-pages` emits by inspecting the *installed Python modules*. A Node-only stage has no venv and no entry points, so it can't generate those files and the frontend build fails for any app with module pages.
diff --git a/framework/cli/simple_module_cli/cli.py b/framework/cli/simple_module_cli/cli.py
index ccb6ba9a9..5e187a635 100644
--- a/framework/cli/simple_module_cli/cli.py
+++ b/framework/cli/simple_module_cli/cli.py
@@ -22,6 +22,7 @@
 
 from simple_module_cli.add_cmd import add_module, run_add
 from simple_module_cli.case import to_kebab_case
+from simple_module_cli.docker_cmd import docker_app
 from simple_module_cli.module_cmd import module_app
 from simple_module_cli.new import new_project
 from simple_module_cli.openapi_cmd import openapi_app
@@ -44,6 +45,7 @@
 app.command("add")(add_module)
 app.command("update")(update_modules)
 app.command("package-update")(package_update)
+app.add_typer(docker_app, name="docker")
 app.add_typer(skills_app, name="skills")
 app.add_typer(module_app, name="module")
 app.add_typer(openapi_app, name="openapi")
diff --git a/framework/cli/simple_module_cli/docker_cmd.py b/framework/cli/simple_module_cli/docker_cmd.py
new file mode 100644
index 000000000..87057f67f
--- /dev/null
+++ b/framework/cli/simple_module_cli/docker_cmd.py
@@ -0,0 +1,158 @@
+"""Additional, Python-only worker images for an existing Compose project."""
+
+import re
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from simple_module_cli.docker_assets import _read, _template_root
+
+_GROUP = "docker"
+_COMMAND = "add-worker"
+_ENCODING = "utf-8"
+_DEFAULT_BASE = "python:3.12-slim-bookworm"
+_NAME = r"[a-z][a-z0-9-]{0,40}"
+_IDENTIFIER = r"[A-Za-z_][A-Za-z0-9_]*"
+_QUEUES = rf"{_IDENTIFIER}(?:,{_IDENTIFIER})*"
+_MODULE = rf"{_IDENTIFIER}(?:\.{_IDENTIFIER})*"
+_MODULES = rf"{_MODULE}(?:,{_MODULE})*"
+_APT = r"[a-z0-9][a-z0-9+.-]*"
+_EXTRA = r"[A-Za-z_][A-Za-z0-9_-]*"
+_BASE = (
+    r"(?:[a-z0-9]+(?:[.-][a-z0-9]+)*(?::[0-9]+)?/)?"
+    r"[a-z0-9]+(?:[._-][a-z0-9]+)*(?:/[a-z0-9]+(?:[._-][a-z0-9]+)*)*"
+    r"(?::[A-Za-z0-9_][A-Za-z0-9_.-]*)?(?:@sha256:[a-f0-9]{64})?"
+)
+_COMPOSE_FILES = ("compose.yml", "docker-compose.yml")
+_WORKER = re.compile(r"^  worker:\n(?P<body>(?: {4}[^\n]*\n|\n)*)", re.MULTILINE)
+_COMMAND_BLOCK = re.compile(r"^    command:\n(?:      [^\n]*\n)*", re.MULTILINE)
+_BUILD_BLOCK = re.compile(r"^    build:\n(?:      [^\n]*\n)*", re.MULTILINE)
+_ENV_HEADER = "    environment:\n"
+_INCLUDE = re.compile(r"^include:[ \t]*(?:#[^\n]*)?$", re.MULTILINE)
+_INCLUDE_ANY = re.compile(r"^include:", re.MULTILINE)
+_MARKER = "  # smpy worker-{name}"
+_INCLUDE_ENTRY = "{marker}\n  - compose.worker-{name}.yml\n"
+_DOCKER_PATH = "docker/worker-{name}.Dockerfile"
+_COMPOSE_PATH = "compose.worker-{name}.yml"
+_DOCKER_TEMPLATE = "worker.Dockerfile.tpl"
+_COMPOSE_TEMPLATE = "compose-worker.yml.tpl"
+_APT_FLAG = " \\\n    && apt-get install -y --no-install-recommends "
+_EXTRA_FLAG = " --extra "
+_EMPTY = ""
+_NEWLINE = "\n"
+_ENV_VALUES = (
+    '      SM_BG_TASKS_WORKER_QUEUES: "{queues}"\n'
+    '      SM_BG_TASKS_WORKER_INCLUDE_MODULES: "{modules}"\n'
+)
+_BUILD_VALUES = "    build:\n      context: .\n      dockerfile: {dockerfile}\n"
+
+docker_app = typer.Typer(help="Manage Docker worker images.", no_args_is_help=True)
+
+
+def _validate(value: str, pattern: str, label: str) -> None:
+    if re.fullmatch(pattern, value) is None:
+        raise typer.BadParameter(f"Invalid {label}: {value!r}; expected {pattern}")
+
+
+def _render(template: str, values: dict[str, str]) -> str:
+    content = _read(_template_root() / template)
+    for key, value in values.items():
+        content = content.replace("{{" + key + "}}", value)
+    return content
+
+
+def _include_worker(content: str, name: str) -> str:
+    marker = _MARKER.format(name=name)
+    if marker in content.splitlines():
+        return content
+    entry = _INCLUDE_ENTRY.format(marker=marker, name=name)
+    include = _INCLUDE.search(content)
+    if include:
+        position = include.end() + 1
+        return content[:position] + entry + content[position:]
+    if _INCLUDE_ANY.search(content):
+        raise typer.BadParameter(
+            "Existing include must use a block list (include: on its own line)."
+        )
+    return "include:\n" + entry + _NEWLINE + content
+
+
+@docker_app.command(_COMMAND)
+def add_worker(
+    name: Annotated[str, typer.Argument(help="Worker image name.")],
+    queues: Annotated[str, typer.Option("--queues", help="Comma-separated queue identifiers.")],
+    base: Annotated[
+        str, typer.Option("--base", help="Python base image (must provide Python).")
+    ] = _DEFAULT_BASE,
+    apt: Annotated[
+        list[str] | None, typer.Option("--apt", help="Repeat for each apt package.")
+    ] = None,
+    extras: Annotated[
+        list[str] | None, typer.Option("--extras", help="Repeat for each uv extra.")
+    ] = None,
+    modules: Annotated[
+        str, typer.Option("--modules", help="Comma-separated Python module paths.")
+    ] = _EMPTY,
+    force: Annotated[
+        bool, typer.Option("--force", help="Replace an existing worker image.")
+    ] = False,
+) -> None:
+    """Generate a worker image and include its service in the project Compose file."""
+    _validate(name, _NAME, "name")
+    _validate(queues, _QUEUES, "queues")
+    _validate(base, _BASE, "base image")
+    if modules:
+        _validate(modules, _MODULES, "modules")
+    for package in apt or []:
+        _validate(package, _APT, "apt package")
+    for extra in extras or []:
+        _validate(extra, _EXTRA, "extra")
+
+    root = Path.cwd()
+    compose = next((root / file for file in _COMPOSE_FILES if (root / file).is_file()), None)
+    if compose is None:
+        raise typer.BadParameter("No compose.yml or docker-compose.yml in the current directory.")
+    content = _read(compose)
+    if not content.endswith(_NEWLINE):
+        content += _NEWLINE
+    dockerfile = _DOCKER_PATH.format(name=name)
+    service_file = _COMPOSE_PATH.format(name=name)
+    paths = (root / dockerfile, root / service_file)
+    service_exists = re.search(rf"^  worker-{re.escape(name)}:", content, re.MULTILINE)
+    if not force and (any(path.exists() for path in paths) or service_exists):
+        raise typer.BadParameter(
+            f"Worker {name!r} already exists; use --force to replace its files."
+        )
+    worker = _WORKER.search(content)
+    if worker is None:
+        raise typer.BadParameter(
+            "Compose must contain an existing worker service to copy its wiring."
+        )
+    body = worker.group("body")
+    if not _BUILD_BLOCK.search(body) or _ENV_HEADER not in body:
+        raise typer.BadParameter(
+            "Existing worker must have block-style build and environment mappings."
+        )
+    body = _COMMAND_BLOCK.sub(_EMPTY, body)
+    body = _BUILD_BLOCK.sub(_BUILD_VALUES.format(dockerfile=dockerfile), body)
+    body = body.replace(
+        _ENV_HEADER, _ENV_HEADER + _ENV_VALUES.format(queues=queues, modules=modules)
+    )
+    updated = _include_worker(content, name)
+    values = {
+        "NAME": name,
+        "BASE": base,
+        "APT_PACKAGES": " " + " ".join(apt) if apt else _EMPTY,
+        "APT": _APT_FLAG + " ".join(apt) if apt else _EMPTY,
+        "EXTRAS": _EMPTY.join(_EXTRA_FLAG + extra for extra in extras or []),
+        "BODY": body.rstrip(_NEWLINE) + _NEWLINE,
+        "QUEUES": queues,
+    }
+    docker_content = _render(_DOCKER_TEMPLATE, values)
+    service_content = _render(_COMPOSE_TEMPLATE, values)
+    paths[0].parent.mkdir(parents=True, exist_ok=True)
+    paths[0].write_text(docker_content, encoding=_ENCODING)
+    paths[1].write_text(service_content, encoding=_ENCODING)
+    compose.write_text(updated, encoding=_ENCODING)
+    typer.echo(f"Created {dockerfile} and {service_file}.")
diff --git a/framework/cli/simple_module_cli/templates/docker/compose-worker.yml.tpl b/framework/cli/simple_module_cli/templates/docker/compose-worker.yml.tpl
new file mode 100644
index 000000000..85fc68a94
--- /dev/null
+++ b/framework/cli/simple_module_cli/templates/docker/compose-worker.yml.tpl
@@ -0,0 +1,12 @@
+services:
+  worker-{{NAME}}:
+{{BODY}}    command:
+      - "celery"
+      - "-A"
+      - "scripts.run_worker:celery"
+      - "worker"
+      - "-l"
+      - "info"
+      - "--concurrency=4"
+      - "-Q"
+      - "{{QUEUES}}"
diff --git a/framework/cli/simple_module_cli/templates/docker/worker.Dockerfile.tpl b/framework/cli/simple_module_cli/templates/docker/worker.Dockerfile.tpl
new file mode 100644
index 000000000..7d018a49a
--- /dev/null
+++ b/framework/cli/simple_module_cli/templates/docker/worker.Dockerfile.tpl
@@ -0,0 +1,27 @@
+# syntax=docker/dockerfile:1.7
+FROM {{BASE}} AS builder
+COPY --from=ghcr.io/astral-sh/uv:python3.12-bookworm /uv /uvx /bin/
+ENV UV_LINK_MODE=copy UV_COMPILE_BYTECODE=1 PYTHONUNBUFFERED=1
+WORKDIR /app
+RUN apt-get update{{APT}} \
+    && rm -rf /var/lib/apt/lists/*
+COPY . .
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --all-packages --no-dev{{EXTRAS}}
+
+FROM {{BASE}} AS runtime
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PATH="/app/.venv/bin:$PATH"
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends curl ca-certificates{{APT_PACKAGES}} \
+    && rm -rf /var/lib/apt/lists/*
+COPY --from=builder /app /app
+RUN mkdir -p /app/data \
+    && useradd --system --uid 10001 --home /app --shell /usr/sbin/nologin app \
+    && chown -R app:app /app
+USER app
+WORKDIR /app
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
+    CMD celery -A scripts.run_worker:celery inspect ping --destination celery@${HOSTNAME} || exit 1
+CMD ["celery", "-A", "scripts.run_worker:celery", "worker", "-l", "info"]
diff --git a/framework/cli/tests/test_cli_docker_workers.py b/framework/cli/tests/test_cli_docker_workers.py
new file mode 100644
index 000000000..67e7a449f
--- /dev/null
+++ b/framework/cli/tests/test_cli_docker_workers.py
@@ -0,0 +1,150 @@
+"""Worker image generation and validation through the public CLI."""
+
+import pytest
+from simple_module_cli.cli import app
+from simple_module_cli.docker_assets import _read, _template_root
+from typer.testing import CliRunner
+
+
+@pytest.fixture
+def project(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    fragment = _read(_template_root() / "compose-tasks-postgres.yml.tpl")
+    (tmp_path / "compose.yml").write_text("services:\n" + fragment.replace("{{PG_DB}}", "demo"))
+    return tmp_path
+
+
+def invoke(*args):
+    return CliRunner().invoke(app, ["docker", "add-worker", *args])
+
+
+def test_generated_worker(project):
+    result = invoke(
+        "geo",
+        "--queues",
+        "geo,heavy",
+        "--modules",
+        "geo.tasks,other.tasks",
+        "--apt",
+        "libgdal-dev",
+        "--extras",
+        "gdal",
+        "--extras",
+        "images",
+    )
+    assert result.exit_code == 0, result.output
+    docker = (project / "docker/worker-geo.Dockerfile").read_text()
+    assert "FROM python:3.12-slim-bookworm AS builder" in docker
+    assert "FROM python:3.12-slim-bookworm AS runtime" in docker
+    assert "uv sync --all-packages --no-dev --extra gdal --extra images" in docker
+    assert docker.count("libgdal-dev") == 2
+    assert "USER app" in docker and "--uid 10001" in docker
+    assert "HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3" in docker
+    assert "inspect ping" in docker
+    assert "node" not in docker.lower() and "npm" not in docker and "{{" not in docker
+    service = (project / "compose.worker-geo.yml").read_text()
+    assert "  worker-geo:" in service
+    assert 'SM_BG_TASKS_WORKER_QUEUES: "geo,heavy"' in service
+    assert 'SM_BG_TASKS_WORKER_INCLUDE_MODULES: "geo.tasks,other.tasks"' in service
+    assert '      - "-Q"\n      - "geo,heavy"' in service
+    assert "dockerfile: docker/worker-geo.Dockerfile" in service
+    assert "postgres:\n        condition: service_healthy" in service
+    assert "@postgres:5432/demo" in service
+    assert service.count("    command:") == 1
+    assert "  beat:" not in service
+    assert "  redis:" not in service.splitlines()
+
+
+def test_rerun_force_and_multiple_workers(project):
+    assert invoke("geo", "--queues", "geo").exit_code == 0
+    before = (project / "compose.yml").read_text()
+    docker = project / "docker/worker-geo.Dockerfile"
+    docker.write_text("custom")
+    result = invoke("geo", "--queues", "geo")
+    assert result.exit_code != 0 and "--force" in result.output
+    assert docker.read_text() == "custom"
+    assert (project / "compose.yml").read_text() == before
+    assert invoke("geo", "--queues", "geo", "--force").exit_code == 0
+    assert (project / "compose.yml").read_text() == before
+    assert invoke("other", "--queues", "other").exit_code == 0
+    content = (project / "compose.yml").read_text()
+    assert content.count("include:") == 1
+    assert content.count("  - compose.worker-geo.yml") == 1
+    assert content.count("  - compose.worker-other.yml") == 1
+
+
+@pytest.mark.parametrize("option", ["--queues", "--modules", "--apt", "--extras", "--base"])
+@pytest.mark.parametrize("bad", ["foo;id", "foo\nRUN id", "foo bar", "foo$(id)", "foo`id`"])
+def test_reject_unsafe_options(project, option, bad):
+    args = ["geo", "--queues", "geo", option, bad]
+    result = invoke(*args)
+    assert result.exit_code != 0
+    assert "Invalid" in result.output
+    assert not (project / "docker").exists()
+    assert not (project / "compose.yml").read_text().startswith("include:")
+
+
+@pytest.mark.parametrize("name", ["Upper", "../geo", "x;id", "a b", "a\nb", "a" * 42])
+def test_reject_bad_names(project, name):
+    assert invoke(name, "--queues", "geo").exit_code != 0
+    assert not (project / "docker").exists()
+
+
+def test_existing_include_and_custom_base(project):
+    compose = project / "compose.yml"
+    compose.write_text("include:\n  - other.yml\n" + compose.read_text())
+    assert (
+        invoke(
+            "geo", "--queues", "geo", "--base", "registry.example:5000/team/python:3.12"
+        ).exit_code
+        == 0
+    )
+    assert compose.read_text().count("include:") == 1
+    assert "  - other.yml" in compose.read_text()
+    assert (
+        "FROM registry.example:5000/team/python:3.12"
+        in (project / "docker/worker-geo.Dockerfile").read_text()
+    )
+
+
+def test_scaffold_filename_and_sqlite(project):
+    (project / "compose.yml").unlink()
+    fragment = _read(_template_root() / "compose-tasks-sqlite.yml.tpl")
+    (project / "docker-compose.yml").write_text("services:\n" + fragment)
+    assert invoke("geo", "--queues", "geo").exit_code == 0
+    service = (project / "compose.worker-geo.yml").read_text()
+    assert "appdata:/app/data" in service
+    assert "postgres:" not in service
+    assert "include:" in (project / "docker-compose.yml").read_text()
+
+
+def test_missing_worker_does_not_write(project):
+    (project / "compose.yml").write_text("services: {}\n")
+    assert invoke("geo", "--queues", "geo").exit_code != 0
+    assert not (project / "docker").exists()
+
+
+@pytest.mark.parametrize(
+    ("option", "bad"),
+    [
+        ("--queues", "a,,b"),
+        ("--queues", "a.b"),
+        ("--modules", "a..b"),
+        ("--extras", "--dev"),
+        ("--apt", "-evil"),
+        ("--base", "python:3.12#evil"),
+    ],
+)
+def test_reject_malformed_values(project, option, bad):
+    assert invoke("geo", "--queues", "geo", option, bad).exit_code != 0
+    assert not (project / "docker").exists()
+
+
+def test_unmanaged_include_refused_before_writing(project):
+    compose = project / "compose.yml"
+    original = "include: [other.yml]\n" + compose.read_text()
+    compose.write_text(original)
+    result = invoke("geo", "--queues", "geo")
+    assert result.exit_code != 0 and "block list" in result.output
+    assert compose.read_text() == original
+    assert not (project / "docker").exists()

From bd98037962ced6337a3d87f7a58a7d8569aa7aa7 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Thu, 22 Oct 2026 09:22:23 +0200
Subject: [PATCH 04/21] =?UTF-8?q?feat(core,db,hosting):=20resource-scoped?=
 =?UTF-8?q?=20access=20=E2=80=94=20ResourcePolicy,=20OwnedResourcePolicy,?=
 =?UTF-8?q?=20RequiresResource=20(#526)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ResourcePolicy protocol (filter + can), ResourceTypeRegistry and the
register_resource_types hook (app.state.sm.resource_types);
OwnedResourcePolicy builds owner OR public(view) OR EXISTS(share) with an
explicit bypass permission, so lists and paginate() counts are filtered in
SQL; RequiresResource loads only through policy.filter: invisible -> 404,
visible but not allowed -> 403, and is a token gate only with permission=.

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 docs/.vitepress/config.ts                     |   1 +
 docs/framework/lifecycle.md                   |  14 ++
 docs/framework/resource-access.md             | 114 +++++++++++++
 framework/core/simple_module_core/__init__.py |  10 ++
 framework/core/simple_module_core/module.py   |  55 ++-----
 .../core/simple_module_core/resources.py      | 141 ++++++++++++++++
 framework/core/simple_module_core/services.py |   4 +
 .../db/simple_module_db/resource_policy.py    | 152 ++++++++++++++++++
 .../simple_module_hosting/_registrations.py   |   3 +
 .../simple_module_hosting/app_builder.py      |  10 +-
 .../simple_module_hosting/resource_deps.py    | 106 ++++++++++++
 framework/hosting/tests/_resacc_models.py     |  79 +++++++++
 framework/hosting/tests/test_resource_deps.py | 134 +++++++++++++++
 .../tests/test_resource_policy_owned.py       | 113 +++++++++++++
 .../tests/test_resource_types_wiring.py       |  31 ++++
 15 files changed, 923 insertions(+), 44 deletions(-)
 create mode 100644 docs/framework/resource-access.md
 create mode 100644 framework/core/simple_module_core/resources.py
 create mode 100644 framework/db/simple_module_db/resource_policy.py
 create mode 100644 framework/hosting/simple_module_hosting/resource_deps.py
 create mode 100644 framework/hosting/tests/_resacc_models.py
 create mode 100644 framework/hosting/tests/test_resource_deps.py
 create mode 100644 framework/hosting/tests/test_resource_policy_owned.py
 create mode 100644 framework/hosting/tests/test_resource_types_wiring.py

diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index 6cfbca30e..952d09110 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -122,6 +122,7 @@ export default defineConfig({
             { text: "Middleware pipeline", link: "/framework/middleware" },
             { text: "Settings & app.state", link: "/framework/settings" },
             { text: "Permissions", link: "/framework/permissions" },
+            { text: "Resource-scoped access", link: "/framework/resource-access" },
             { text: "Principal resolvers", link: "/framework/principal-resolvers" },
             { text: "User directory", link: "/framework/user-directory" },
             { text: "Public routes", link: "/framework/public-routes" },
diff --git a/docs/framework/lifecycle.md b/docs/framework/lifecycle.md
index a7b076dcf..cdc7c23c4 100644
--- a/docs/framework/lifecycle.md
+++ b/docs/framework/lifecycle.md
@@ -17,6 +17,7 @@ register_body_limits
 register_csp_sources
 register_design_packs
 register_audit_links
+register_resource_types
 register_exception_handlers
 register_middleware
 register_routes
@@ -293,6 +294,19 @@ def register_audit_links(self, registry: AuditLinkRegistry) -> None:
 
 A link is a route, not an authorisation: apart from `label_permission`, the registry does not check that the row still exists or that the reader may open it. A link to a deleted record lands on the target screen's own 404, and permissions are enforced by the target route as usual.
 
+## `register_resource_types(registry)`
+
+Declare a resource type whose rows carry object-level access (owner, shares,
+public), so cross-cutting code such as the `sharing` module can find its
+policy and load a row by id. See [Resource-scoped access](./resource-access.md).
+
+```python
+def register_resource_types(self, registry: ResourceTypeRegistry) -> None:
+    registry.register(
+        ResourceType(name="notes.note", policy=NOTE_POLICY, select_by_id=select_by_id(Note))
+    )
+```
+
 ## `on_startup()` / `on_shutdown()`
 
 Async lifespan hooks that run after all modules are registered.
diff --git a/docs/framework/resource-access.md b/docs/framework/resource-access.md
new file mode 100644
index 000000000..6519070be
--- /dev/null
+++ b/docs/framework/resource-access.md
@@ -0,0 +1,114 @@
+# Resource-scoped access
+
+Permissions are global `<module>.<verb>` strings: they say a principal may edit
+*notes*, not *this* note. Resource-scoped access answers the object-level
+question ("this user may see this note because they own it, it was shared with
+them, or it is public") once per resource type, so detail and list endpoints
+enforce the same rule and give the same 404/403 answers (GH #526).
+
+## The pieces
+
+| Piece | Package | Role |
+|---|---|---|
+| `ResourcePolicy` | `simple_module_core.resources` | Protocol: `filter(principal, action, stmt)` and `can(principal, action, obj)` |
+| `ResourcePrincipal` | `simple_module_core.resources` | `user_id` + the request's resolved permission set |
+| `ResourceType`, `ResourceTypeRegistry` | `simple_module_core.resources` | What `register_resource_types` declares; read at `app.state.sm.resource_types` |
+| `OwnedResourcePolicy`, `select_by_id`, `load_authorized` | `simple_module_db.resource_policy` | The stock owner / public / shared policy |
+| `RequiresResource`, `resource_principal` | `simple_module_hosting.resource_deps` | FastAPI dependencies |
+| `sharing` module (optional) | `modules/sharing` | A generic `sharing_resource_share` table, grant/revoke API, admin page |
+
+Actions are plain strings; `ACTION_VIEW`, `ACTION_EDIT`, `ACTION_DELETE` and
+`ACTION_SHARE` are provided. `view` is special: it decides 404 versus 403.
+
+## `filter` is the authority, `can` is a fast path
+
+`filter` narrows a `SELECT` to the rows the principal may act on. It is a
+`WHERE` on your own statement, so `paginate()` counts exactly the rows it lists
+and tenant / soft-delete filters still apply. `can` decides for one loaded row
+from the facts the row carries (owner, visibility, bypass permission). It may
+answer `False` where `filter` would admit the row, because a share lives in
+another table. Callers that get `False` from `can` fall back to `filter`, never
+the other way round.
+
+## Declaring a policy
+
+```python
+from simple_module_core.resources import ResourceType
+from simple_module_db.resource_policy import OwnedResourcePolicy, select_by_id
+
+NOTE_POLICY = OwnedResourcePolicy(
+    Note.owner_id,
+    bypass_perm=PERM_NOTES_MANAGE,  # required: None means nobody bypasses
+    visibility_col=Note.visibility,  # 'public' rows are viewable by anyone
+    share_exists=share_exists_for(NOTE_TYPE, Note.id),  # optional, from `sharing`
+)
+
+
+class NotesModule(ModuleBase):
+    def register_resource_types(self, registry):
+        registry.register(
+            ResourceType(name=NOTE_TYPE, policy=NOTE_POLICY, select_by_id=select_by_id(Note))
+        )
+```
+
+The predicate is `owner_col == user_id OR visibility_col == 'public' (view only)
+OR EXISTS(share granting the action)`. A principal holding `bypass_perm`, or the
+admin wildcard when a bypass permission is set, sees every row. `bypass_perm` is
+keyword-required so the escape hatch is always written down; pass `None` to say
+nobody bypasses ownership, not even an admin.
+
+`share_exists` is injected as a `(principal, action) -> EXISTS(...) | None`
+factory. The framework never imports the `sharing` module (SM009). A module can
+supply its own bespoke share table the same way.
+
+## Detail endpoints: `RequiresResource`
+
+```python
+def note_stmt(note_id: uuid.UUID):
+    return select(Note).where(Note.id == note_id)
+
+
+@router.patch("/{note_id}")
+async def edit(note: Note = Depends(RequiresResource(NOTE_POLICY, ACTION_EDIT, note_stmt))): ...
+```
+
+`loader` is an ordinary FastAPI dependency (it may take path and query
+parameters) that returns the unfiltered `SELECT`. The row is loaded only through
+`policy.filter`, never `session.get` on a raw id:
+
+- not visible (`view`) → **404**, the same answer as a missing row, so ids
+  cannot be probed;
+- visible but the action is not allowed → **403** `PermissionDenied` with
+  `permission == "resource:<action>"`.
+
+**API tokens.** `RequiresResource` counts as a permission gate for the
+[token guard](./permissions.md) only when you pass `permission=`. It then also
+enforces that permission, capped at the token's scopes, before loading. Without
+`permission=`, an API token is refused on the route like on any route that
+names no permission. The policy still applies to tokens on top of the
+permission.
+
+## List endpoints
+
+```python
+@router.get("/")
+async def list_notes(
+    who: ResourcePrincipal = Depends(resource_principal),
+    db=Depends(get_db),
+    params: PageParams = Depends(page_params),
+):
+    stmt = NOTE_POLICY.filter(who, ACTION_VIEW, select(Note).order_by(Note.created_at))
+    return await paginate(db, stmt, params)
+```
+
+A row the principal may not see never leaves the database, and the count
+matches the list.
+
+## The optional `sharing` module
+
+Install `simple_module_sharing` for a generic share table instead of a bespoke
+one. Shares are tenant-scoped, hard-deleted on revoke, and an expired share is
+ignored in SQL. Granting checks that the resource type is registered, that the
+granter passes the owning policy's `share` action, and that the grantee exists
+in the [user directory](./user-directory.md). See
+[the module page](../modules/sharing.md).
diff --git a/framework/core/simple_module_core/__init__.py b/framework/core/simple_module_core/__init__.py
index baa9f3cc2..e7d830e93 100644
--- a/framework/core/simple_module_core/__init__.py
+++ b/framework/core/simple_module_core/__init__.py
@@ -53,6 +53,12 @@
 from simple_module_core.module import ModuleBase, ModuleMeta
 from simple_module_core.permissions import PermissionRegistry
 from simple_module_core.public_routes import PublicRoute, PublicRouteRegistry
+from simple_module_core.resources import (
+    ResourcePolicy,
+    ResourcePrincipal,
+    ResourceType,
+    ResourceTypeRegistry,
+)
 from simple_module_core.services import Services
 from simple_module_core.setup_steps import SetupAction, SetupField, SetupRegistry, SetupStep
 from simple_module_core.tenancy import TENANT_ROLE_PREFIX, TenantRole, is_tenant_role, tenant_role
@@ -101,6 +107,10 @@
     "PermissionRegistry",
     "PublicRoute",
     "PublicRouteRegistry",
+    "ResourcePolicy",
+    "ResourcePrincipal",
+    "ResourceType",
+    "ResourceTypeRegistry",
     "Services",
     "SetupAction",
     "SetupField",
diff --git a/framework/core/simple_module_core/module.py b/framework/core/simple_module_core/module.py
index 1ca54c1d7..72a393ee8 100644
--- a/framework/core/simple_module_core/module.py
+++ b/framework/core/simple_module_core/module.py
@@ -22,51 +22,18 @@
     from simple_module_core.menu import MenuRegistry
     from simple_module_core.permissions import PermissionRegistry
     from simple_module_core.public_routes import PublicRouteRegistry
+    from simple_module_core.resources import ResourceTypeRegistry
     from simple_module_core.setup_steps import SetupRegistry
 
 
 class ModuleBase(ABC):
     """Base class for all modules.
 
-    Subclasses override only the methods they need.
-    Every method has a default no-op implementation.
-
-    Hook execution order during app boot:
-
-        Phase 1: Bootstrap
-          - Load framework Settings
-          - Discover & topological-sort modules
-          - Run diagnostics (dev only)
-
-        Phase 2: App creation
-          - Create FastAPI app
-          - Store framework registries + settings on app.state
-
-        Phase 3: Module settings
-          - register_settings(app)
-
-        Phase 4: Module registrations
-          - register_menu_items(registry)
-          - register_permissions(registry)
-          - register_feature_flags(registry)
-          - register_event_handlers(bus)
-          - register_invalidations(bus, app)
-          - register_health_checks(registry)
-
-        Phase 5: Database
-          - init_db() -> DatabaseState
-          - register_listeners(db_state)
-
-        Phase 6: App wiring
-          - Inertia setup
-          - register_exception_handlers(app)
-          - Middleware pipeline (register_middleware per module)
-          - register_routes(api_router, view_router)
-          - Mount health router + static files
-
-        Phase 7: Runtime (async)
-          - on_startup(app) — per module, in dependency order
-          - on_shutdown(app) — per module, reverse order
+    Subclasses override only the methods they need; every hook is a no-op by
+    default. The boot order the host calls them in is documented in
+    ``docs/framework/lifecycle.md`` (settings, then the declarative
+    registrations in ``_registrations.run_module_registrations``, then
+    database, Inertia, middleware, routes, and finally ``on_startup``).
     """
 
     meta: ModuleMeta
@@ -230,6 +197,16 @@ def register_audit_links(self, registry):
         boot, in dependency order.
         """
 
+    def register_resource_types(self, registry: ResourceTypeRegistry) -> None:
+        """Declare resource types whose rows carry object-level access (GH #526).
+
+        ``registry.register(ResourceType(name="notes.note", policy=...,
+        select_by_id=...))`` makes the type's :class:`ResourcePolicy` reachable
+        by cross-cutting code such as the ``sharing`` module. Names are dotted
+        and unique; a duplicate raises at boot. See
+        ``docs/framework/resource-access.md``.
+        """
+
     def register_middleware(self, app: FastAPI) -> None:
         """Add middleware to the application.
 
diff --git a/framework/core/simple_module_core/resources.py b/framework/core/simple_module_core/resources.py
new file mode 100644
index 000000000..bcf37f36e
--- /dev/null
+++ b/framework/core/simple_module_core/resources.py
@@ -0,0 +1,141 @@
+"""Resource-scoped access: who may see or act on *this* row (GH #526).
+
+Permissions are global ``<module>.<verb>`` strings; they say a principal may
+edit *documents*, not *this* document. A :class:`ResourcePolicy` answers the
+object-level question once per resource type, in two shapes that must agree:
+
+* :meth:`ResourcePolicy.filter` narrows a ``SELECT`` to the rows *principal*
+  may *action* — the authority. List endpoints and their counts run it, so a
+  row a principal may not see never leaves the database.
+* :meth:`ResourcePolicy.can` decides for one already-loaded row from the facts
+  it carries (owner, visibility, a bypass permission). It may say ``False``
+  where :meth:`filter` would admit the row (a share lives in another table);
+  callers then fall back to :meth:`filter`, never the other way round.
+
+The 404-vs-403 rule (``RequiresResource`` in ``simple_module_hosting``): a row
+the principal may not *view* does not exist for them (404); a row they may
+view but not *action* is a 403.
+
+Modules declare their types in ``register_resource_types`` so cross-cutting
+code (the optional ``sharing`` module) can find a type's policy and load a row
+by its string id. ``simple_module_core`` stays SQLAlchemy-free: statements are
+typed ``Any``; the stock policy lives in ``simple_module_db.resource_policy``.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+
+from simple_module_core.permissions import grants
+
+ACTION_VIEW = "view"
+"""Seeing the row at all; what decides 404 versus 403."""
+
+ACTION_EDIT = "edit"
+ACTION_DELETE = "delete"
+ACTION_SHARE = "share"
+"""Granting someone else access; the ``sharing`` module checks it on the granter."""
+
+_TYPE_NAME = re.compile(r"^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$")
+
+
+@dataclass(frozen=True)
+class ResourcePrincipal:
+    """Who is asking: a user id (``None`` for anonymous) and what they hold.
+
+    ``permissions`` is the request's resolved set (roles, grant sources, token
+    scope cap) — the same set ``RequiresPermission`` reads, so a bypass
+    permission is honoured or refused exactly as the door would.
+    """
+
+    user_id: str | None
+    permissions: frozenset[str] = frozenset()
+
+    def has(self, permission: str | None) -> bool:
+        """Whether this principal holds *permission* (wildcard included).
+
+        ``None`` or empty means "no permission configured" and answers ``False``
+        — unlike :func:`grants`, a missing bypass must never grant everything.
+        """
+        return bool(permission) and grants(self.permissions, permission or "")
+
+
+@runtime_checkable
+class ResourcePolicy(Protocol):
+    """Object-level access for one resource type. See the module docstring."""
+
+    def filter(self, principal: ResourcePrincipal, action: str, stmt: Any) -> Any:
+        """*stmt* narrowed to the rows *principal* may *action*."""
+        ...
+
+    def can(self, principal: ResourcePrincipal, action: str, obj: Any) -> bool:
+        """Whether *principal* may *action* the loaded *obj* (fast path only)."""
+        ...
+
+
+StatementForId = Callable[[str], Any]
+"""``(resource_id) -> SELECT`` of that one row, or raise ``ValueError`` for a malformed id."""
+
+
+@dataclass(frozen=True)
+class ResourceType:
+    """A resource type a module exposes to cross-cutting access code.
+
+    ``name`` is dotted and owned by the module (``"notes.note"``). ``select_by_id``
+    builds the unfiltered ``SELECT`` for one row from its string id; callers
+    always pass it through ``policy.filter`` before executing it.
+    """
+
+    name: str
+    policy: ResourcePolicy
+    select_by_id: StatementForId
+    #: Actions a share may grant on this type, beyond :data:`ACTION_VIEW`.
+    shareable_actions: tuple[str, ...] = field(default=(ACTION_VIEW, ACTION_EDIT))
+
+
+class ResourceTypeError(ValueError):
+    """A malformed or duplicate resource type declaration (raised at boot)."""
+
+
+class ResourceTypeRegistry:
+    """Resource types declared through ``register_resource_types``.
+
+    Populated once at boot and read through ``app.state.sm.resource_types``.
+    """
+
+    def __init__(self) -> None:
+        self._types: dict[str, ResourceType] = {}
+
+    def register(self, resource_type: ResourceType) -> None:
+        name = resource_type.name
+        if not _TYPE_NAME.match(name):
+            raise ResourceTypeError(f"Resource type name {name!r} must look like 'module.thing'")
+        if name in self._types:
+            raise ResourceTypeError(f"Resource type {name!r} is registered twice")
+        self._types[name] = resource_type
+
+    def get(self, name: str) -> ResourceType | None:
+        return self._types.get(name)
+
+    def all(self) -> list[ResourceType]:
+        return sorted(self._types.values(), key=lambda t: t.name)
+
+    def __contains__(self, name: object) -> bool:
+        return name in self._types
+
+
+__all__ = [
+    "ACTION_DELETE",
+    "ACTION_EDIT",
+    "ACTION_SHARE",
+    "ACTION_VIEW",
+    "ResourcePolicy",
+    "ResourcePrincipal",
+    "ResourceType",
+    "ResourceTypeError",
+    "ResourceTypeRegistry",
+    "StatementForId",
+]
diff --git a/framework/core/simple_module_core/services.py b/framework/core/simple_module_core/services.py
index d4a704439..b29c68848 100644
--- a/framework/core/simple_module_core/services.py
+++ b/framework/core/simple_module_core/services.py
@@ -18,6 +18,7 @@
 
 from simple_module_core.invalidation import InvalidationBus
 from simple_module_core.rate_limit import InProcessWindowStore, WindowStore
+from simple_module_core.resources import ResourceTypeRegistry
 from simple_module_core.tenancy import TenancyMode
 
 if TYPE_CHECKING:
@@ -113,3 +114,6 @@ class Services:
     #: lockout — counts in the same place across workers instead of opening a
     #: second Redis client. Defaulted for apps built outside ``create_app``.
     rate_limit_store: WindowStore = field(default_factory=InProcessWindowStore)
+    #: Resource types from ``register_resource_types`` (GH #526). Defaulted
+    #: for apps built outside ``create_app``.
+    resource_types: ResourceTypeRegistry = field(default_factory=ResourceTypeRegistry)
diff --git a/framework/db/simple_module_db/resource_policy.py b/framework/db/simple_module_db/resource_policy.py
new file mode 100644
index 000000000..b3b52be93
--- /dev/null
+++ b/framework/db/simple_module_db/resource_policy.py
@@ -0,0 +1,152 @@
+"""The stock :class:`~simple_module_core.resources.ResourcePolicy` (GH #526).
+
+:class:`OwnedResourcePolicy` covers the common shape — a row has an owner,
+maybe a visibility flag, maybe shares in another table — as one SQL predicate::
+
+    owner_col == :user_id
+    OR visibility_col == 'public'          -- view only
+    OR EXISTS (share for this principal)   -- from the injected factory
+
+plus an explicit bypass permission. Because it is a ``WHERE`` on the caller's
+own statement, :func:`~simple_module_db.pagination.paginate` counts exactly the
+rows it lists. Tenant and soft-delete filters still apply on top.
+
+``share_exists`` is injected (the optional ``sharing`` module provides one), so
+nothing here imports a plugin (SM009).
+"""
+
+from __future__ import annotations
+
+import contextlib
+import uuid
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
+
+from simple_module_core.resources import ACTION_VIEW, ResourcePolicy, ResourcePrincipal
+from sqlalchemy import false, inspect, or_
+
+if TYPE_CHECKING:
+    from sqlalchemy.ext.asyncio import AsyncSession
+    from sqlalchemy.sql.elements import ColumnElement
+
+PUBLIC_VISIBILITY = "public"
+
+ShareExists = Callable[[ResourcePrincipal, str], "ColumnElement[bool] | None"]
+"""``(principal, action) -> EXISTS(...)`` for shares granting *action*, or ``None``."""
+
+
+def _coerce(column: Any, value: str) -> Any:
+    """*value* (a string id) in the Python type *column* compares against."""
+    try:
+        python_type = column.type.python_type
+    except (AttributeError, NotImplementedError):
+        return value
+    if python_type is uuid.UUID:
+        return uuid.UUID(str(value))
+    if python_type is int:
+        return int(value)
+    return value
+
+
+class OwnedResourcePolicy:
+    """Owner / public / shared access, with an explicit bypass permission.
+
+    ``bypass_perm`` is keyword-required: pass the permission that sees every
+    row (``"notes.manage"``; an admin's wildcard satisfies it), or ``None`` to
+    say on purpose that nobody bypasses ownership.
+    """
+
+    def __init__(
+        self,
+        owner_col: Any,
+        *,
+        bypass_perm: str | None,
+        visibility_col: Any = None,
+        share_exists: ShareExists | None = None,
+        public_value: str = PUBLIC_VISIBILITY,
+    ) -> None:
+        self.owner_col = owner_col
+        self.visibility_col = visibility_col
+        self.share_exists = share_exists
+        self.bypass_perm = bypass_perm
+        self.public_value = public_value
+
+    def predicate(self, principal: ResourcePrincipal, action: str) -> ColumnElement[bool] | None:
+        """The ``WHERE`` clause, or ``None`` when the principal bypasses it."""
+        if principal.has(self.bypass_perm):
+            return None
+        clauses: list[Any] = []
+        if principal.user_id is not None:
+            # An id that cannot be an owner (wrong type) owns nothing.
+            with contextlib.suppress(ValueError):
+                clauses.append(self.owner_col == _coerce(self.owner_col, principal.user_id))
+            if self.share_exists is not None:
+                shared = self.share_exists(principal, action)
+                if shared is not None:
+                    clauses.append(shared)
+        if self.visibility_col is not None and action == ACTION_VIEW:
+            clauses.append(self.visibility_col == self.public_value)
+        return or_(*clauses) if clauses else false()
+
+    def filter(self, principal: ResourcePrincipal, action: str, stmt: Any) -> Any:
+        clause = self.predicate(principal, action)
+        return stmt if clause is None else stmt.where(clause)
+
+    def can(self, principal: ResourcePrincipal, action: str, obj: Any) -> bool:
+        if principal.has(self.bypass_perm):
+            return True
+        owner = getattr(obj, self.owner_col.key, None)
+        uid = principal.user_id
+        if uid is not None and owner is not None and str(owner).lower() == uid.lower():
+            return True
+        if self.visibility_col is not None and action == ACTION_VIEW:
+            return getattr(obj, self.visibility_col.key, None) == self.public_value
+        return False
+
+
+def select_by_id(model: type) -> Callable[[str], Any]:
+    """A ``StatementForId`` for a single-primary-key table model.
+
+    Raises ``ValueError`` for an id that cannot be the key's type, which
+    callers turn into "not found".
+    """
+    from sqlmodel import select
+
+    (pk,) = inspect(model).primary_key
+
+    def build(resource_id: str) -> Any:
+        return select(model).where(pk == _coerce(pk, resource_id))
+
+    return build
+
+
+async def load_authorized(
+    session: AsyncSession,
+    policy: ResourcePolicy,
+    principal: ResourcePrincipal,
+    action: str,
+    stmt: Any,
+) -> tuple[Any | None, bool]:
+    """``(row, allowed)``: the row *principal* can see, and whether *action* is allowed.
+
+    ``(None, False)`` means invisible (answer 404); ``(row, False)`` means
+    visible but not allowed (403). Loads through :meth:`filter` only — never by
+    raw id — then asks :meth:`can` and, if it says no, :meth:`filter` again for
+    *action* (a share role lives outside the row).
+    """
+    row = (await session.execute(policy.filter(principal, ACTION_VIEW, stmt))).scalars().first()
+    if row is None:
+        return None, False
+    if action == ACTION_VIEW or policy.can(principal, action, row):
+        return row, True
+    allowed = (await session.execute(policy.filter(principal, action, stmt))).scalars().first()
+    return row, allowed is not None
+
+
+__all__ = [
+    "PUBLIC_VISIBILITY",
+    "OwnedResourcePolicy",
+    "ShareExists",
+    "load_authorized",
+    "select_by_id",
+]
diff --git a/framework/hosting/simple_module_hosting/_registrations.py b/framework/hosting/simple_module_hosting/_registrations.py
index 168f1f175..1a60f84d6 100644
--- a/framework/hosting/simple_module_hosting/_registrations.py
+++ b/framework/hosting/simple_module_hosting/_registrations.py
@@ -32,6 +32,7 @@ def run_module_registrations(
     audit_link_registry,
     csp_registry,
     body_limit_registry=None,
+    resource_type_registry=None,
 ) -> None:
     """Invoke each module's registration hooks, in dependency order.
 
@@ -59,6 +60,8 @@ def run_module_registrations(
         mod.register_csp_sources(csp_registry)
         mod.register_design_packs(design_pack_registry)
         mod.register_audit_links(audit_link_registry)
+        if resource_type_registry is not None:
+            mod.register_resource_types(resource_type_registry)
 
     health_registry.set_owner("")
     setup_registry.set_owner("")
diff --git a/framework/hosting/simple_module_hosting/app_builder.py b/framework/hosting/simple_module_hosting/app_builder.py
index 943fa2828..7524e0ad6 100644
--- a/framework/hosting/simple_module_hosting/app_builder.py
+++ b/framework/hosting/simple_module_hosting/app_builder.py
@@ -17,6 +17,7 @@
 from simple_module_core.menu import MenuRegistry
 from simple_module_core.permissions import PermissionRegistry
 from simple_module_core.public_routes import PublicRouteRegistry
+from simple_module_core.resources import ResourceTypeRegistry
 from simple_module_core.services import DiagnosticsState, Services
 from simple_module_core.setup_steps import SetupRegistry
 from simple_module_db.listeners import register_listeners
@@ -110,11 +111,7 @@ def create_app(settings: Settings | None = None) -> FastAPI:
         installed_modules, settings.auth_provider, strict=not settings.is_development
     )
     modules = topological_sort(modules, strict=not settings.is_development)
-    logger.info(
-        "Loaded %d module(s): %s",
-        len(modules),
-        ", ".join(m.meta.name for m in modules),
-    )
+    logger.info("Loaded %d module(s): %s", len(modules), ", ".join(m.meta.name for m in modules))
 
     # Build the i18n registry up front so diagnostics can validate key parity
     # against host/ui locales, not just module-contributed ones.
@@ -147,6 +144,7 @@ def create_app(settings: Settings | None = None) -> FastAPI:
     register_migration_step(setup_registry)
     design_pack_registry = DesignPackRegistry()
     audit_link_registry = AuditLinkRegistry()
+    resource_type_registry = ResourceTypeRegistry()
 
     lifespan = build_lifespan(modules)
 
@@ -200,6 +198,7 @@ def create_app(settings: Settings | None = None) -> FastAPI:
         audit_link_registry=audit_link_registry,
         csp_registry=csp_registry,
         body_limit_registry=body_limit_registry,
+        resource_type_registry=resource_type_registry,
     )
     app.state.body_limits = body_limit_registry
 
@@ -292,6 +291,7 @@ def create_app(settings: Settings | None = None) -> FastAPI:
         tenancy=mode_for(settings),
         view_prefixes=view_prefixes,
         rate_limit_store=rate_limit_store,
+        resource_types=resource_type_registry,
     )
 
     return app
diff --git a/framework/hosting/simple_module_hosting/resource_deps.py b/framework/hosting/simple_module_hosting/resource_deps.py
new file mode 100644
index 000000000..ac13227c9
--- /dev/null
+++ b/framework/hosting/simple_module_hosting/resource_deps.py
@@ -0,0 +1,106 @@
+"""``RequiresResource`` — the object-level twin of ``RequiresPermission`` (GH #526).
+
+Usage::
+
+    def note_stmt(note_id: uuid.UUID):
+        return select(Note).where(Note.id == note_id)
+
+
+    @router.patch("/{note_id}")
+    async def edit(note: Note = Depends(RequiresResource(NOTE_POLICY, ACTION_EDIT, note_stmt))): ...
+
+``loader`` is an ordinary FastAPI dependency (it may take path and query
+parameters) returning the *unfiltered* ``SELECT`` for the row. The row is
+loaded only through ``policy.filter`` — never ``session.get`` on a raw id:
+
+* not visible to the principal (``view``) → **404**, the same answer as a row
+  that does not exist, so ids cannot be probed;
+* visible but *action* not allowed → **403** :class:`PermissionDenied`.
+
+API tokens: the dependency counts as a permission gate for ``token_guard``
+only when ``permission=`` is given, and then also enforces that permission
+(capped at the token's scopes) before loading. Without it a token is refused
+on the route, as on any route that names no permission.
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from typing import Any
+
+from fastapi import Depends, HTTPException, Request
+from simple_module_core.permission_denied import PermissionDenied
+from simple_module_core.resources import ResourcePolicy, ResourcePrincipal
+from simple_module_db.deps import get_db
+from simple_module_db.resource_policy import load_authorized
+
+from simple_module_hosting.permissions import RequiresPermission, ensure_resolved_permissions
+from simple_module_hosting.token_guard import GATE_PERMISSION, TOKEN_GATE_ATTR
+
+RESOURCE_PERMISSION_PREFIX = "resource:"
+"""``PermissionDenied.permission`` for an object-level refusal: ``resource:<action>``."""
+
+
+async def resource_principal(request: Request) -> ResourcePrincipal:
+    """The request's principal as a policy sees it; a dependency for list routes.
+
+    Anonymous requests get ``user_id=None`` and no permissions, so a policy
+    shows them public rows at most.
+    """
+    user = getattr(request.state, "user", None)
+    if user is None:
+        return ResourcePrincipal(user_id=None)
+    held = await ensure_resolved_permissions(request)
+    user = getattr(request.state, "user", None)  # resolution may demote a stale token
+    if user is None:
+        return ResourcePrincipal(user_id=None)
+    user_id = getattr(user, "id", None)
+    return ResourcePrincipal(
+        user_id=str(user_id) if user_id is not None else None,
+        permissions=frozenset(held),
+    )
+
+
+class RequiresResource:
+    """Load the row named by *loader* if *principal* may *action* it; see module docs."""
+
+    def __init__(
+        self,
+        policy: ResourcePolicy,
+        action: str,
+        loader: Callable[..., Any],
+        *,
+        permission: str | None = None,
+    ) -> None:
+        self.policy = policy
+        self.action = action
+        self.loader = loader
+        self.permission = permission
+        self._gate = RequiresPermission(permission) if permission else None
+        if permission:
+            setattr(self, TOKEN_GATE_ATTR, GATE_PERMISSION)
+        # FastAPI reads the instance signature: request, the caller's loader
+        # (with its own path params) and the request session.
+        kw = inspect.Parameter.KEYWORD_ONLY
+        self.__signature__ = inspect.Signature(
+            [
+                inspect.Parameter("request", kw, annotation=Request),
+                inspect.Parameter("stmt", kw, default=Depends(loader)),
+                inspect.Parameter("session", kw, default=Depends(get_db)),
+            ]
+        )
+
+    async def __call__(self, *, request: Request, stmt: Any, session: Any) -> Any:
+        if self._gate is not None:
+            await self._gate(request)
+        principal = await resource_principal(request)
+        row, allowed = await load_authorized(session, self.policy, principal, self.action, stmt)
+        if row is None:
+            raise HTTPException(status_code=404, detail="Not found")
+        if not allowed:
+            raise PermissionDenied(f"{RESOURCE_PERMISSION_PREFIX}{self.action}")
+        return row
+
+
+__all__ = ["RESOURCE_PERMISSION_PREFIX", "RequiresResource", "resource_principal"]
diff --git a/framework/hosting/tests/_resacc_models.py b/framework/hosting/tests/_resacc_models.py
new file mode 100644
index 000000000..bf59739f3
--- /dev/null
+++ b/framework/hosting/tests/_resacc_models.py
@@ -0,0 +1,79 @@
+"""Test-only tables and policy for the resource-access tests (GH #526)."""
+
+from __future__ import annotations
+
+import uuid
+
+from simple_module_core.resources import ACTION_EDIT, ACTION_VIEW, ResourcePrincipal
+from simple_module_db.resource_policy import OwnedResourcePolicy
+from sqlmodel import Field, SQLModel, exists, select
+
+BYPASS = "resacc.manage"
+OWNER = uuid.UUID("00000000-0000-0000-0000-00000000000a")
+SHARED = uuid.UUID("00000000-0000-0000-0000-00000000000b")
+STRANGER = uuid.UUID("00000000-0000-0000-0000-00000000000c")
+EDITOR = uuid.UUID("00000000-0000-0000-0000-00000000000d")
+
+
+class ResaccDoc(SQLModel, table=True):
+    __tablename__ = "resacc_test_doc"
+    __table_args__ = {"extend_existing": True}
+    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
+    owner_id: uuid.UUID
+    visibility: str = "private"
+    title: str = ""
+
+
+class ResaccShare(SQLModel, table=True):
+    __tablename__ = "resacc_test_share"
+    __table_args__ = {"extend_existing": True}
+    id: int | None = Field(default=None, primary_key=True)
+    doc_id: uuid.UUID
+    user_id: str
+    role: str = ACTION_VIEW
+
+
+_ROLES_FOR = {ACTION_VIEW: (ACTION_VIEW, ACTION_EDIT), ACTION_EDIT: (ACTION_EDIT,)}
+
+
+def share_exists(principal: ResourcePrincipal, action: str):
+    roles = _ROLES_FOR.get(action)
+    if not roles:
+        return None
+    return exists(
+        select(ResaccShare.id).where(
+            ResaccShare.doc_id == ResaccDoc.id,
+            ResaccShare.user_id == principal.user_id,
+            ResaccShare.role.in_(roles),
+        )
+    )
+
+
+POLICY = OwnedResourcePolicy(
+    ResaccDoc.owner_id,
+    bypass_perm=BYPASS,
+    visibility_col=ResaccDoc.visibility,
+    share_exists=share_exists,
+)
+
+
+async def seed(session) -> dict[str, ResaccDoc]:
+    """Private (shared view to SHARED, edit to EDITOR), public, and another owner's doc."""
+    conn = await session.connection()
+    for table in (ResaccDoc.__table__, ResaccShare.__table__):
+        await conn.run_sync(lambda c, t=table: t.create(c, checkfirst=True))
+    docs = {
+        "private": ResaccDoc(owner_id=OWNER, title="private"),
+        "public": ResaccDoc(owner_id=OWNER, visibility="public", title="public"),
+        "other": ResaccDoc(owner_id=STRANGER, title="other"),
+    }
+    session.add_all(docs.values())
+    await session.flush()
+    session.add(ResaccShare(doc_id=docs["private"].id, user_id=str(SHARED), role=ACTION_VIEW))
+    session.add(ResaccShare(doc_id=docs["private"].id, user_id=str(EDITOR), role=ACTION_EDIT))
+    await session.flush()
+    return docs
+
+
+def principal(user: uuid.UUID | None, *perms: str) -> ResourcePrincipal:
+    return ResourcePrincipal(user_id=str(user) if user else None, permissions=frozenset(perms))
diff --git a/framework/hosting/tests/test_resource_deps.py b/framework/hosting/tests/test_resource_deps.py
new file mode 100644
index 000000000..d17a4ea0a
--- /dev/null
+++ b/framework/hosting/tests/test_resource_deps.py
@@ -0,0 +1,134 @@
+"""RequiresResource over HTTP: 404 vs 403, token gating, list counts (GH #526)."""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from types import SimpleNamespace
+
+import httpx
+import pytest
+from _resacc_models import EDITOR, OWNER, POLICY, SHARED, STRANGER, ResaccDoc, seed
+from fastapi import Depends, FastAPI, Request
+from simple_module_core.resources import ACTION_EDIT, ACTION_VIEW, ResourcePrincipal
+from simple_module_db import PageParams, paginate
+from simple_module_hosting.resource_deps import RequiresResource, resource_principal
+from simple_module_hosting.token_guard import route_admits_tokens, token_route_guard
+from sqlmodel import select
+
+
+@dataclass
+class _User:
+    id: uuid.UUID
+    roles: list[str] = field(default_factory=lambda: ["user"])
+    permissions: list[str] = field(default_factory=list)
+    scopes: list[str] | None = None
+
+
+def _doc_stmt(doc_id: uuid.UUID):
+    return select(ResaccDoc).where(ResaccDoc.id == doc_id)
+
+
+def _app(db_state, user: _User | None) -> FastAPI:
+    app = FastAPI(dependencies=[Depends(token_route_guard)])
+    app.state.sm = SimpleNamespace(db=db_state, permissions=None, i18n_registry=None)
+
+    @app.get("/items")
+    async def list_docs(who: ResourcePrincipal = Depends(resource_principal)) -> dict:
+        factory = db_state.session_factory
+        async with factory() as session:
+            stmt = POLICY.filter(who, ACTION_VIEW, select(ResaccDoc).order_by(ResaccDoc.title))
+            page = await paginate(session, stmt, PageParams())
+        return {"total": page.total, "titles": [d.title for d in page.items]}
+
+    @app.get("/items/{doc_id}")
+    async def view(doc=Depends(RequiresResource(POLICY, ACTION_VIEW, _doc_stmt))) -> dict:
+        return {"title": doc.title}
+
+    @app.patch("/items/{doc_id}")
+    async def edit(doc=Depends(RequiresResource(POLICY, ACTION_EDIT, _doc_stmt))) -> dict:
+        return {"title": doc.title}
+
+    gate = RequiresResource(POLICY, ACTION_VIEW, _doc_stmt, permission="resacc.view")
+
+    @app.get("/api/items/{doc_id}")
+    async def api_view(doc=Depends(gate)) -> dict:
+        return {"title": doc.title}
+
+    @app.middleware("http")
+    async def fake_auth(request: Request, call_next):
+        request.state.user = user
+        return await call_next(request)
+
+    return app
+
+
+@pytest.fixture
+async def docs(db_state, db_session):
+    seeded = await seed(db_session)
+    await db_session.commit()
+    return {k: str(v.id) for k, v in seeded.items()}
+
+
+async def _call(app: FastAPI, method: str, path: str) -> httpx.Response:
+    transport = httpx.ASGITransport(app=app)
+    async with httpx.AsyncClient(transport=transport, base_url="http://t") as client:
+        return await client.request(method, path)
+
+
+async def test_non_shared_user_gets_404_and_row_absent_from_list(db_state, docs):
+    app = _app(db_state, _User(STRANGER))
+    assert (await _call(app, "GET", f"/items/{docs['private']}")).status_code == 404
+    listing = (await _call(app, "GET", "/items")).json()
+    assert listing == {"total": 2, "titles": ["other", "public"]}
+
+
+async def test_owner_and_shared_user_see_the_row(db_state, docs):
+    for who in (OWNER, SHARED):
+        resp = await _call(_app(db_state, _User(who)), "GET", f"/items/{docs['private']}")
+        assert resp.json() == {"title": "private"}
+    listing = (await _call(_app(db_state, _User(SHARED)), "GET", "/items")).json()
+    assert listing["total"] == 2 and "private" in listing["titles"]
+
+
+async def test_viewer_gets_403_on_edit_editor_and_owner_pass(db_state, docs):
+    path = f"/items/{docs['private']}"
+    assert (await _call(_app(db_state, _User(SHARED)), "PATCH", path)).status_code == 403
+    assert (await _call(_app(db_state, _User(EDITOR)), "PATCH", path)).status_code == 200
+    assert (await _call(_app(db_state, _User(OWNER)), "PATCH", path)).status_code == 200
+
+
+async def test_public_row_viewable_not_editable(db_state, docs):
+    app = _app(db_state, _User(STRANGER))
+    assert (await _call(app, "GET", f"/items/{docs['public']}")).status_code == 200
+    assert (await _call(app, "PATCH", f"/items/{docs['public']}")).status_code == 403
+
+
+async def test_unknown_id_is_404(db_state, docs):
+    app = _app(db_state, _User(OWNER))
+    assert (await _call(app, "GET", f"/items/{uuid.uuid4()}")).status_code == 404
+
+
+async def test_token_refused_without_permission_argument(db_state, docs):
+    token = _User(OWNER, roles=["admin"], scopes=["resacc.view"])
+    app = _app(db_state, token)
+    assert (await _call(app, "GET", f"/items/{docs['private']}")).status_code == 403
+    assert (await _call(app, "GET", f"/api/items/{docs['private']}")).status_code == 200
+
+
+async def test_token_with_permission_still_filtered_by_policy(db_state, docs):
+    token = _User(STRANGER, permissions=["resacc.view"], scopes=["resacc.view"])
+    resp = await _call(_app(db_state, token), "GET", f"/api/items/{docs['private']}")
+    assert resp.status_code == 404
+
+
+async def test_permission_argument_enforced_for_sessions(db_state, docs):
+    resp = await _call(_app(db_state, _User(OWNER)), "GET", f"/api/items/{docs['private']}")
+    assert resp.status_code == 403
+
+
+def test_only_permission_variant_counts_as_token_gate(db_state):
+    app = _app(db_state, None)
+    routes = {(r.path, tuple(r.methods)): r for r in app.routes if hasattr(r, "dependant")}
+    assert not route_admits_tokens(routes[("/items/{doc_id}", ("GET",))])
+    assert route_admits_tokens(routes[("/api/items/{doc_id}", ("GET",))])
diff --git a/framework/hosting/tests/test_resource_policy_owned.py b/framework/hosting/tests/test_resource_policy_owned.py
new file mode 100644
index 000000000..6bf500cf4
--- /dev/null
+++ b/framework/hosting/tests/test_resource_policy_owned.py
@@ -0,0 +1,113 @@
+"""OwnedResourcePolicy: owner / public / shared / bypass, lists and counts in SQL (GH #526)."""
+
+from __future__ import annotations
+
+import pytest
+from _resacc_models import (
+    BYPASS,
+    EDITOR,
+    OWNER,
+    POLICY,
+    SHARED,
+    STRANGER,
+    ResaccDoc,
+    principal,
+    seed,
+)
+from simple_module_core.resources import (
+    ACTION_EDIT,
+    ACTION_VIEW,
+    ResourceType,
+    ResourceTypeError,
+    ResourceTypeRegistry,
+)
+from simple_module_db import PageParams, paginate
+from simple_module_db.resource_policy import OwnedResourcePolicy, load_authorized, select_by_id
+from sqlmodel import select
+
+
+@pytest.fixture
+async def docs(db_session):
+    return await seed(db_session)
+
+
+async def _titles(session, who, action=ACTION_VIEW) -> list[str]:
+    stmt = POLICY.filter(who, action, select(ResaccDoc).order_by(ResaccDoc.title))
+    return [d.title for d in (await session.execute(stmt)).scalars()]
+
+
+async def test_owner_sees_own_and_public(db_session, docs):
+    assert await _titles(db_session, principal(OWNER)) == ["private", "public"]
+
+
+async def test_stranger_sees_only_public_and_own(db_session, docs):
+    assert await _titles(db_session, principal(STRANGER)) == ["other", "public"]
+
+
+async def test_shared_user_sees_shared_row(db_session, docs):
+    assert await _titles(db_session, principal(SHARED)) == ["private", "public"]
+
+
+async def test_public_is_view_only(db_session, docs):
+    assert await _titles(db_session, principal(SHARED), ACTION_EDIT) == []
+    assert await _titles(db_session, principal(EDITOR), ACTION_EDIT) == ["private"]
+
+
+async def test_anonymous_sees_public_only(db_session, docs):
+    assert await _titles(db_session, principal(None)) == ["public"]
+
+
+async def test_bypass_permission_and_wildcard_see_everything(db_session, docs):
+    assert len(await _titles(db_session, principal(STRANGER, BYPASS))) == 3
+    assert len(await _titles(db_session, principal(STRANGER, "*"))) == 3
+
+
+async def test_no_bypass_means_even_wildcard_is_filtered(db_session, docs):
+    strict = OwnedResourcePolicy(ResaccDoc.owner_id, bypass_perm=None)
+    stmt = strict.filter(principal(STRANGER, "*"), ACTION_VIEW, select(ResaccDoc))
+    assert [d.title for d in (await db_session.execute(stmt)).scalars()] == ["other"]
+
+
+async def test_paginate_count_matches_filtered_list(db_session, docs):
+    stmt = POLICY.filter(principal(STRANGER), ACTION_VIEW, select(ResaccDoc).order_by("title"))
+    page = await paginate(db_session, stmt, PageParams(per_page=1))
+    assert page.total == 2
+    assert page.pages == 2
+
+
+async def test_can_fast_path(docs):
+    doc = docs["private"]
+    assert POLICY.can(principal(OWNER), ACTION_EDIT, doc)
+    assert not POLICY.can(principal(STRANGER), ACTION_VIEW, doc)
+    assert POLICY.can(principal(STRANGER), ACTION_VIEW, docs["public"])
+    assert not POLICY.can(principal(STRANGER), ACTION_EDIT, docs["public"])
+    assert POLICY.can(principal(STRANGER, BYPASS), ACTION_EDIT, doc)
+
+
+async def test_load_authorized_404_403_and_share_role(db_session, docs):
+    by_id = select_by_id(ResaccDoc)
+    stmt = by_id(str(docs["private"].id))
+    assert await load_authorized(db_session, POLICY, principal(STRANGER), ACTION_VIEW, stmt) == (
+        None,
+        False,
+    )
+    row, allowed = await load_authorized(db_session, POLICY, principal(SHARED), ACTION_EDIT, stmt)
+    assert row is not None and not allowed
+    row, allowed = await load_authorized(db_session, POLICY, principal(EDITOR), ACTION_EDIT, stmt)
+    assert row is not None and allowed
+
+
+def test_select_by_id_rejects_malformed_ids():
+    with pytest.raises(ValueError):
+        select_by_id(ResaccDoc)("not-a-uuid")
+
+
+def test_registry_validates_names_and_duplicates():
+    registry = ResourceTypeRegistry()
+    rt = ResourceType(name="resacc.doc", policy=POLICY, select_by_id=select_by_id(ResaccDoc))
+    registry.register(rt)
+    assert registry.get("resacc.doc") is rt and "resacc.doc" in registry
+    with pytest.raises(ResourceTypeError):
+        registry.register(rt)
+    with pytest.raises(ResourceTypeError):
+        registry.register(ResourceType(name="Bad", policy=POLICY, select_by_id=rt.select_by_id))
diff --git a/framework/hosting/tests/test_resource_types_wiring.py b/framework/hosting/tests/test_resource_types_wiring.py
new file mode 100644
index 000000000..42eab727c
--- /dev/null
+++ b/framework/hosting/tests/test_resource_types_wiring.py
@@ -0,0 +1,31 @@
+"""``register_resource_types`` reaches ``app.state.sm.resource_types`` (GH #526)."""
+
+from __future__ import annotations
+
+import simple_module_hosting.app_builder as app_builder
+from _resacc_models import POLICY, ResaccDoc
+from simple_module_core.module import ModuleBase, ModuleMeta
+from simple_module_core.resources import ResourceType, ResourceTypeRegistry
+from simple_module_db.resource_policy import select_by_id
+from simple_module_hosting.app_builder import create_app
+
+
+class _ResaccModule(ModuleBase):
+    meta = ModuleMeta(name="ResaccFixture")
+
+    def register_resource_types(self, registry: ResourceTypeRegistry) -> None:
+        registry.register(
+            ResourceType(name="resacc.doc", policy=POLICY, select_by_id=select_by_id(ResaccDoc))
+        )
+
+
+def test_module_resource_type_reaches_services(monkeypatch, settings):
+    real_discover = app_builder.discover_modules
+    monkeypatch.setattr(
+        app_builder,
+        "discover_modules",
+        lambda *a, **kw: [*real_discover(*a, **kw), _ResaccModule()],
+    )
+    app = create_app(settings)
+    registered = app.state.sm.resource_types.get("resacc.doc")
+    assert registered is not None and registered.policy is POLICY

From 23fde7f96fcf6ae2f7d4ecfe6fadf520c9eb7da6 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Thu, 22 Oct 2026 09:23:44 +0200
Subject: [PATCH 05/21] feat(audit): audit bulk, Core and raw DML writes (#557)

do_orm_execute listener (simple_module_db.bulk_audit) records ORM bulk and
Core INSERT/UPDATE/DELETE on audited models through the per-engine audit
sink: ids prefetched with the statement's WHERE and tenant scope, per-row
entries up to 500, else one '*' summary. sm_audit=False opts out;
record_bulk_audit() for text() writes; audit_log setting
refuse_unaudited_dml makes the opt-out raise.

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 CHANGELOG.md                                  |  14 +
 docs/modules/audit_log.md                     |  27 +-
 framework/db/simple_module_db/__init__.py     |   3 +
 framework/db/simple_module_db/bulk_audit.py   | 280 ++++++++++++++++++
 framework/db/simple_module_db/listeners.py    |   4 +
 .../db/simple_module_db/model_registry.py     |   4 +
 framework/db/simple_module_db/query_filter.py |   5 +-
 framework/db/simple_module_db/session.py      |   4 +
 framework/db/tests/test_db_bulk_audit.py      | 199 +++++++++++++
 modules/audit_log/audit_log/constants.py      |  16 +-
 modules/audit_log/audit_log/locales/de.json   |   6 +-
 modules/audit_log/audit_log/locales/en.json   |   6 +-
 modules/audit_log/audit_log/module.py         |  21 +-
 .../pages/components/ChangesList.tsx          |   6 +-
 .../pages/components/EntriesTable.tsx         |   7 +-
 .../audit_log/pages/components/FilterBar.tsx  |  11 +-
 modules/audit_log/audit_log/services.py       |  14 +
 modules/audit_log/audit_log/settings.py       |  20 ++
 .../tests/test_audit_log_bulk_capture.py      |  61 ++++
 packages/i18n/src/generated-resources.ts      |   4 +
 packages/i18n/src/keys.generated.ts           |   4 +
 21 files changed, 698 insertions(+), 18 deletions(-)
 create mode 100644 framework/db/simple_module_db/bulk_audit.py
 create mode 100644 framework/db/tests/test_db_bulk_audit.py
 create mode 100644 modules/audit_log/audit_log/services.py
 create mode 100644 modules/audit_log/audit_log/settings.py
 create mode 100644 modules/audit_log/tests/test_audit_log_bulk_capture.py

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 94bd54379..5b04a33b6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,15 @@ All notable changes to this project are documented in this file. The format is b
 - `host/client_app` no longer re-declares `@simple-module-py/ui`'s runtime dependencies, nor `@base-ui/react`, `@radix-ui/react-slot`, `autoprefixer` or `postcss` (nothing loaded them) (#521).
 
 ### Added
+- Statement DML is audited (#557): `simple_module_db.bulk_audit` audits ORM bulk
+  `update()` / `delete()` / `insert()` and Core DML on `Model.__table__` through
+  the engine's audit sink, one `bulk_updated` / `bulk_deleted` /
+  `bulk_soft_deleted` entry per row (ids prefetched with the statement's `WHERE`
+  and tenant scope) up to 500 rows, else one `"*"` summary; `bulk_inserted` is one
+  summary per statement. `execution_options(sm_audit=False)` opts out;
+  `record_bulk_audit(session, Model, action, ids, changes)` records `text()`
+  writes; the new `audit_log` setting `refuse_unaudited_dml` (default off) makes
+  the opt-out raise `UnauditedWriteError`. No migration.
 - Release process (#510): `release.yml` runs the whole PR suite (`pr.yml` via
   `workflow_call`) against the dispatched commit and `build` needs it, so nothing
   is built or published from a red commit. The duplicated bump + lockfile steps
@@ -76,6 +85,11 @@ All notable changes to this project are documented in this file. The format is b
   it, which removes the `users` ↔ `audit_log` import cycle.
 
 ### Changed
+- **Behaviour change:** bulk and Core DML writes on audited models now produce
+  audit entries (actions `bulk_*`), in requests and Celery workers. Statements
+  that set only excluded columns (the outbox, `TaskExecution.heartbeat_at`) are
+  still not recorded. Opt a statement out with
+  `execution_options(sm_audit=False)` (#557).
 - `scripts/bump_version.py` also bumps every `modules/*/package.json`; all
   `package.json` versions are now in lockstep with the Python packages (they were
   0.1.0, keycloak 0.0.0) (#510).
diff --git a/docs/modules/audit_log.md b/docs/modules/audit_log.md
index 85fe016c7..ea21ce1f7 100644
--- a/docs/modules/audit_log.md
+++ b/docs/modules/audit_log.md
@@ -33,13 +33,28 @@ audit_log = "audit_log.capture:audit_callback"
 
 `background_tasks` binds whatever `simple_module_db.audit_sinks.discover_audit_callback()` finds to both of its worker engines — the sync engine task bodies and signal handlers use (`sync_db`) and the async engine durable outbox handlers run on (`outbox_worker`). A task's ORM writes, including `TaskExecution` lifecycle rows, are therefore audited exactly like a request's whenever `audit_log` is installed; neither package imports the other. The worker's audit rows carry no `user_id` (no request principal).
 
-### Known gaps
+### Statement DML: bulk, Core and raw writes
 
-Capture sees only what the ORM unit of work flushes. These writes are **not** audited, in requests or in workers:
+`session.execute(update(Model)...)`, its `delete()` / `insert()` siblings and Core DML on `Model.__table__` never reach a flush, so a `do_orm_execute` listener (`simple_module_db.bulk_audit`) audits them instead, through the same per-engine `audit_callback` (requests and Celery workers alike):
 
-- ORM bulk `update()` / `delete()` and Core DML run through `session.execute(...)`;
-- raw `text("UPDATE ...")` DML;
-- the outbox's own state-change bulk `UPDATE`s (claims, delivery status, fences) and the task heartbeat's `heartbeat_at` refresh.
+- **`UPDATE` / `DELETE`.** Before the statement runs, the listener reads the primary keys it will touch, with the same `WHERE` and the same tenant scope (soft-deleted rows included, as the write includes them). Up to 500 rows each get one entry (`bulk_updated`, `bulk_deleted`, or `bulk_soft_deleted` for an update setting `is_deleted = True`); `changes` holds the `SET` values as `{field, new}` (a SQL expression is stored as SQL with bind placeholders). `session.execute(update(Model), [{"id": ..., ...}, ...])` takes the ids from the rows instead.
+- **More than 500 rows.** One summary entry with `entity_id` `"*"`: the `SET` values plus `where_sql` (the `WHERE` with bind placeholders, never the literal values), `rowcount` and `truncated: true`.
+- **`INSERT`.** One `bulk_inserted` summary entry per statement (`entity_id` `"*"`, the column values, or the column names for a multi-row insert).
+- **Exclusions apply as for a flush.** `__audit_exclude__` models (the outbox, `AuditEntry` itself) are skipped; `__audit_exclude_fields__` and mixin bookkeeping columns are dropped from `changes`; a statement that sets *only* excluded columns writes no entry. So the outbox's claim / delivery `UPDATE`s and the task heartbeat's `heartbeat_at` refresh stay unaudited.
+- **Same transaction.** Entries are added to the writing session, so a rollback discards them with the write. The sink catches and logs its own failures: auditing never fails the write it describes.
+
+Opt one statement out with `.execution_options(sm_audit=False)`. The module setting **`refuse_unaudited_dml`** (default off, edited in the module-settings screen, applies without a restart) turns that opt-out into an `UnauditedWriteError` for any audited model.
+
+Raw `text("UPDATE ...")` is invisible to the listener (SQLAlchemy cannot tell which table it writes). Record it yourself in the same transaction:
+
+```python
+from simple_module_db import record_bulk_audit
+
+await session.execute(text("UPDATE orders_order SET status = 'archived' WHERE ..."))
+record_bulk_audit(session, Order, "bulk_updated", ids, {"status": "archived"})
+```
+
+`ids=None` records one `"*"` entry. The helper is a no-op on an engine with no audit sink.
 
 ### What gets recorded
 
@@ -49,6 +64,8 @@ Capture sees only what the ORM unit of work flushes. These writes are **not** au
 | `updated` | object in `session.dirty` with real column changes (empty diffs are skipped) |
 | `deleted` | object in `session.deleted` (hard delete) |
 | `soft_deleted` | a `SoftDeleteMixin` row the soft-delete listener moved into `session.new` with `is_deleted=True` |
+| `bulk_updated` / `bulk_deleted` / `bulk_soft_deleted` | statement `UPDATE` / `DELETE` (see above), one per row or one `"*"` summary |
+| `bulk_inserted` | statement `INSERT`, one `"*"` summary per statement |
 
 `changes` is a list of `{field, new}` (creates) or `{field, old, new}` (updates) entries; deletes and soft-deletes carry an empty change list. Column values are normalised to JSON-safe scalars (non-primitives are stringified).
 
diff --git a/framework/db/simple_module_db/__init__.py b/framework/db/simple_module_db/__init__.py
index 6a41984c1..3451c13ee 100644
--- a/framework/db/simple_module_db/__init__.py
+++ b/framework/db/simple_module_db/__init__.py
@@ -2,6 +2,7 @@
 
 from simple_module_db.audit import AuditRecord
 from simple_module_db.base import create_module_base
+from simple_module_db.bulk_audit import UnauditedWriteError, record_bulk_audit
 from simple_module_db.callbacks import OnCommitCallback
 from simple_module_db.deps import get_db
 from simple_module_db.extensions import UnsupportedDatabaseError, ensure_db_extensions
@@ -64,6 +65,7 @@
     "SoftDeleteMixin",
     "TSVector",
     "TenantIsolationError",
+    "UnauditedWriteError",
     "UnsupportedDatabaseError",
     "VersionedMixin",
     "all_tenants",
@@ -88,6 +90,7 @@
     "mark_written",
     "no_tenant",
     "paginate",
+    "record_bulk_audit",
     "render_item",
     "tenant_context",
     "total_pages",
diff --git a/framework/db/simple_module_db/bulk_audit.py b/framework/db/simple_module_db/bulk_audit.py
new file mode 100644
index 000000000..78adfe95b
--- /dev/null
+++ b/framework/db/simple_module_db/bulk_audit.py
@@ -0,0 +1,280 @@
+"""Audit statement DML: ORM bulk and Core ``INSERT`` / ``UPDATE`` / ``DELETE`` (#557).
+
+The unit-of-work capture in ``listeners`` sees only what a flush writes, so
+``session.execute(update(Model)...)``, its ``delete()`` sibling and Core DML on
+``Model.__table__`` used to leave no trace. :func:`audit_statement` is a
+``do_orm_execute`` hook that closes that gap for every audited model:
+
+* ``UPDATE`` / ``DELETE``: the primary keys the statement will touch are read
+  first, with the same ``WHERE`` and the same tenant scope (soft-deleted rows
+  included, as the write includes them). Up to :data:`BULK_AUDIT_ID_CAP` ids
+  produce one record each (``bulk_updated`` / ``bulk_deleted`` /
+  ``bulk_soft_deleted``, ``changes`` = the ``SET`` values); past the cap the
+  statement is recorded once, ``entity_id`` ``"*"``, with its ``WHERE`` (bind
+  placeholders, never literals) and row count.
+* ``INSERT``: one summary record per statement.
+
+Excluded columns (mixin bookkeeping, ``__audit_exclude_fields__``) are dropped
+from ``changes``, and a statement that sets only excluded columns is not
+recorded, exactly like a flush. ``execution_options(sm_audit=False)`` opts a
+statement out; with ``refuse_unaudited_dml`` on the engine policy that raises
+instead. ``text()`` writes are invisible here: record them with
+:func:`record_bulk_audit`. Auditing never fails the write it describes.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Iterable
+from typing import Any, Final
+
+from simple_module_core.correlation import correlation_id
+from sqlalchemy import inspect as sa_inspect
+from sqlalchemy import select
+from sqlalchemy.orm import ORMExecuteState, Session
+from sqlalchemy.sql.elements import BindParameter, ClauseElement
+
+from simple_module_db import model_registry as registry
+from simple_module_db.audit import AuditRecord, _excluded_fields, _serialize
+from simple_module_db.query_filter import engine_policy
+from simple_module_db.tenancy import ALL_TENANTS_OPTION
+
+logger = logging.getLogger(__name__)
+
+AUDIT_OPTION: Final = "sm_audit"
+"""``execution_options(sm_audit=False)`` skips auditing for one statement."""
+
+BULK_AUDIT_ID_CAP: Final = 500
+"""Most rows a bulk statement records one by one; past it, one summary row."""
+
+ACTION_BULK_INSERTED: Final = "bulk_inserted"
+ACTION_BULK_UPDATED: Final = "bulk_updated"
+ACTION_BULK_DELETED: Final = "bulk_deleted"
+ACTION_BULK_SOFT_DELETED: Final = "bulk_soft_deleted"
+SUMMARY_ENTITY_ID: Final = "*"
+
+_SOFT_DELETE_FLAG: Final = "is_deleted"
+_ACTIVE_KEY: Final = "_sm_bulk_audit_active"
+
+
+class UnauditedWriteError(RuntimeError):
+    """An opted-out DML statement against an audited model, in strict mode."""
+
+
+def _refuses_unaudited(policy: Any) -> bool:
+    flag = getattr(policy, "refuse_unaudited_dml", False)
+    return bool(flag() if callable(flag) else flag)
+
+
+def _target_class(execute_state: ORMExecuteState) -> type | None:
+    for mapper in execute_state.all_mappers:
+        return mapper.class_
+    table = getattr(execute_state.statement, "table", None)
+    return registry.classes_by_table.get(table) if table is not None else None
+
+
+def _column_name(key: Any) -> str:
+    if isinstance(key, str):
+        return key
+    return str(getattr(key, "key", None) or getattr(key, "name", None) or key)
+
+
+def _value(value: Any) -> Any:
+    if isinstance(value, BindParameter):
+        return _serialize(value.effective_value)
+    if isinstance(value, ClauseElement):
+        return str(value)  # an expression: SQL with bind placeholders
+    return _serialize(value)
+
+
+def _set_values(execute_state: ORMExecuteState) -> dict[str, Any]:
+    """The ``SET`` / ``VALUES`` of a single-row statement, by column name."""
+    stmt = execute_state.statement
+    pairs = getattr(stmt, "_ordered_values", None) or list(
+        (getattr(stmt, "_values", None) or {}).items()
+    )
+    values = {_column_name(k): _value(v) for k, v in pairs}
+    params = execute_state.parameters
+    if isinstance(params, dict):
+        values.update({_column_name(k): _serialize(v) for k, v in params.items()})
+    return values
+
+
+def _changes(values: dict[str, Any], excluded: frozenset[str]) -> list[dict[str, Any]]:
+    return [{"field": k, "new": v} for k, v in values.items() if k not in excluded]
+
+
+def _pk_str(values: tuple | list) -> str:
+    return str(values[0]) if len(values) == 1 else str(tuple(values))
+
+
+class _Ctx:
+    """What one audited statement records, built before it runs."""
+
+    def __init__(self, entity_type: str, action: str, changes: list[dict[str, Any]]) -> None:
+        self.entity_type = entity_type
+        self.action = action
+        self.changes = changes
+        self.user_id = _current_user()
+        self.correlation_id = correlation_id.get("") or None
+
+    def record(self, entity_id: str, changes: list[dict[str, Any]] | None = None) -> AuditRecord:
+        return AuditRecord(
+            entity_type=self.entity_type,
+            entity_id=entity_id,
+            action=self.action,
+            changes=self.changes if changes is None else changes,
+            user_id=self.user_id,
+            correlation_id=self.correlation_id,
+        )
+
+
+def _current_user() -> str | None:
+    from simple_module_db.listeners import current_user_id
+
+    return current_user_id.get()
+
+
+def _plan(execute_state: ORMExecuteState, cls: type) -> _Ctx | None:
+    """The record shape for this statement, or ``None`` when nothing is audited."""
+    name = cls.__name__
+    if execute_state.is_delete:
+        return _Ctx(name, ACTION_BULK_DELETED, [])
+    rows = execute_state.parameters
+    multi = getattr(execute_state.statement, "_multi_values", None)
+    many = isinstance(rows, list) or bool(multi)
+    if isinstance(rows, list):
+        values = dict.fromkeys(sorted({k for row in rows for k in row}))
+    elif multi:
+        first = multi[0][0]
+        values = dict.fromkeys(_column_name(k) for k in first) if isinstance(first, dict) else {}
+    else:
+        values = _set_values(execute_state)
+    if execute_state.is_update and values.get(_SOFT_DELETE_FLAG) is True:
+        return _Ctx(name, ACTION_BULK_SOFT_DELETED, [])
+    pk = {col.key for col in sa_inspect(cls).primary_key}
+    changes = _changes(values, _excluded_fields(cls) | pk)
+    if values and not changes:
+        return None  # only excluded columns: bookkeeping, like a flush
+    if many:
+        changes = [{"field": c["field"]} for c in changes]
+    action = ACTION_BULK_INSERTED if execute_state.is_insert else ACTION_BULK_UPDATED
+    return _Ctx(name, action, changes)
+
+
+def _prefetch_ids(execute_state: ORMExecuteState, cls: type, cap: int) -> list[str]:
+    """Primary keys of the rows the statement will touch, at most ``cap + 1``."""
+    stmt = execute_state.statement
+    if execute_state.all_mappers:
+        cols = [getattr(cls, col.key) for col in sa_inspect(cls).primary_key]
+    else:
+        cols = list(stmt.table.primary_key.columns)
+    query = select(*cols).limit(cap + 1)
+    if stmt.whereclause is not None:
+        query = query.where(stmt.whereclause)
+    options = {"include_deleted": True}
+    if execute_state.execution_options.get(ALL_TENANTS_OPTION):
+        options[ALL_TENANTS_OPTION] = True
+    rows = execute_state.session.execute(query.execution_options(**options)).all()
+    return [_pk_str(tuple(row)) for row in rows]
+
+
+def _bulk_by_pk_ids(execute_state: ORMExecuteState, cls: type) -> list[str] | None:
+    """``session.execute(update(Model), [{pk..., col...}, ...])``: ids from the rows."""
+    params = execute_state.parameters
+    if not (execute_state.is_update and isinstance(params, list) and params):
+        return None
+    pk = [col.key for col in sa_inspect(cls).primary_key]
+    if not all(all(k in row for k in pk) for row in params):
+        return None
+    return [_pk_str([row[k] for k in pk]) for row in params]
+
+
+def _summary(ctx: _Ctx, stmt: Any, rowcount: Any) -> AuditRecord:
+    where = getattr(stmt, "whereclause", None)
+    summary = [
+        {"field": "where_sql", "new": str(where) if where is not None else None},
+        {"field": "rowcount", "new": rowcount},
+        {"field": "truncated", "new": True},
+    ]
+    return ctx.record(SUMMARY_ENTITY_ID, [*ctx.changes, *summary])
+
+
+def audit_statement(execute_state: ORMExecuteState) -> Any:
+    """``do_orm_execute`` hook: audit statement DML on an audited model."""
+    if not (execute_state.is_insert or execute_state.is_update or execute_state.is_delete):
+        return None
+    session = execute_state.session
+    if session.info.get(_ACTIVE_KEY):
+        return None
+    cls = _target_class(execute_state)
+    if cls is None or getattr(cls, "__audit_exclude__", False) is True:
+        return None
+    policy = engine_policy(session)
+    if execute_state.execution_options.get(AUDIT_OPTION, True) is False:
+        if _refuses_unaudited(policy) and _plan(execute_state, cls) is not None:
+            raise UnauditedWriteError(
+                f"Unaudited {AUDIT_OPTION}=False write to audited model {cls.__name__}"
+            )
+        return None
+    callback = getattr(policy, "audit_callback", None)
+    if callback is None:
+        return None
+    try:
+        ctx = _plan(execute_state, cls)
+    except Exception:
+        logger.exception("Could not plan a bulk audit record for %s", cls.__name__)
+        return None
+    if ctx is None:
+        return None
+    ids = _bulk_by_pk_ids(execute_state, cls)
+    if ids is None and not execute_state.is_insert:
+        ids = _prefetch_ids(execute_state, cls, BULK_AUDIT_ID_CAP)
+    stmt = execute_state.statement
+    result = execute_state.invoke_statement()
+    params = execute_state.parameters
+    if ids is not None and len(ids) <= BULK_AUDIT_ID_CAP:
+        records = [ctx.record(i) for i in ids]
+    else:
+        rowcount = len(params) if isinstance(params, list) else getattr(result, "rowcount", None)
+        records = [_summary(ctx, stmt, rowcount)]
+    _deliver(session, callback, records)
+    return result
+
+
+def _deliver(session: Session, callback: Any, records: list[AuditRecord]) -> None:
+    if not records:
+        return
+    session.info[_ACTIVE_KEY] = True
+    try:
+        callback(session, records)
+    except Exception:
+        logger.exception("Audit sink failed for %d bulk record(s)", len(records))
+    finally:
+        session.info.pop(_ACTIVE_KEY, None)
+
+
+def record_bulk_audit(
+    session: Any,
+    entity_type: type | str,
+    action: str,
+    ids: Iterable[object] | None,
+    changes: dict[str, Any] | None = None,
+) -> None:
+    """Audit a write the listeners cannot see — a ``text("UPDATE ...")`` statement.
+
+    One record per id (``ids=None`` records one row with ``entity_id`` ``"*"``),
+    in the session's transaction: a rollback discards them with the write.
+    ``changes`` maps column name to new value. A no-op on an unaudited engine;
+    never raises because of the audit sink. Accepts an ``AsyncSession`` or its
+    sync ``Session``.
+    """
+    sync = getattr(session, "sync_session", session)
+    callback = getattr(engine_policy(sync), "audit_callback", None)
+    if callback is None:
+        return
+    name = entity_type if isinstance(entity_type, str) else entity_type.__name__
+    diff = [{"field": k, "new": _serialize(v)} for k, v in (changes or {}).items()]
+    ctx = _Ctx(name, action, diff)
+    keys = [SUMMARY_ENTITY_ID] if ids is None else [str(i) for i in ids]
+    _deliver(sync, callback, [ctx.record(k) for k in keys])
diff --git a/framework/db/simple_module_db/listeners.py b/framework/db/simple_module_db/listeners.py
index 569a98d64..599499ecc 100644
--- a/framework/db/simple_module_db/listeners.py
+++ b/framework/db/simple_module_db/listeners.py
@@ -12,6 +12,7 @@
 from sqlalchemy import inspect as sa_inspect
 from sqlalchemy.orm import Session
 
+from simple_module_db.bulk_audit import audit_statement
 from simple_module_db.flush_guard import guard_flush
 from simple_module_db.mixins import AuditMixin, SoftDeleteMixin, VersionedMixin
 from simple_module_db.query_filter import bind_engine_policy, engine_policy, filter_statements
@@ -126,6 +127,9 @@ def attach_session_listeners(session_class: type[Session]) -> None:
         ("after_flush_postexec", _after_flush_audit),
         ("do_orm_execute", _mark_dml_written),
         ("do_orm_execute", filter_statements),
+        # Last: it reads the statement after tenant scoping and guards, and
+        # runs it itself (``invoke_statement``) between prefetch and record.
+        ("do_orm_execute", audit_statement),
     ):
         event.listen(session_class, name, fn)
     setattr(session_class, _LISTENERS_ATTACHED, True)
diff --git a/framework/db/simple_module_db/model_registry.py b/framework/db/simple_module_db/model_registry.py
index 99cfefa84..eb0dad1fd 100644
--- a/framework/db/simple_module_db/model_registry.py
+++ b/framework/db/simple_module_db/model_registry.py
@@ -18,6 +18,9 @@
 soft_delete_classes: set[type] = set()
 tenant_table_names: set[str] = set()
 soft_delete_table_names: set[str] = set()
+# Mapped class per ``Table`` — resolves a Core DML target (``Model.__table__``)
+# back to its model, for bulk-write auditing (#557).
+classes_by_table: dict[Any, type] = {}
 
 # ``(is_soft_delete, is_multi_tenant)`` per class, for the hot path.
 _flags_cache: dict[type, tuple[bool, bool]] = {}
@@ -36,6 +39,7 @@ def register(cls: type) -> None:
     table = getattr(cls, "__table__", None)
     if table is None:
         return
+    classes_by_table.setdefault(table, cls)
     if issubclass(cls, MultiTenantMixin) and cls not in tenant_classes:
         tenant_classes.add(cls)
         tenant_table_names.add(table.name)
diff --git a/framework/db/simple_module_db/query_filter.py b/framework/db/simple_module_db/query_filter.py
index 8c9cc216f..948ddf9b7 100644
--- a/framework/db/simple_module_db/query_filter.py
+++ b/framework/db/simple_module_db/query_filter.py
@@ -47,7 +47,8 @@ class EngineTenancy:
     """Engine policy for an engine that has no ``DatabaseState``.
 
     ``audit_callback`` is the same sink a ``DatabaseState`` carries: writes made
-    through this engine are audited only when it is set (#498).
+    through this engine are audited only when it is set (#498);
+    ``refuse_unaudited_dml`` is the strict bulk-audit switch (#557).
     """
 
     def __init__(
@@ -56,10 +57,12 @@ def __init__(
         tenant_strict: bool,
         default_tenant_id: str = DEFAULT_TENANT_ID,
         audit_callback: Callable[..., None] | None = None,
+        refuse_unaudited_dml: bool | Callable[[], bool] = False,
     ) -> None:
         self.tenant_strict = tenant_strict
         self.default_tenant_id = default_tenant_id
         self.audit_callback = audit_callback
+        self.refuse_unaudited_dml = refuse_unaudited_dml
 
 
 def bind_engine_policy(engine: Engine, policy: Any) -> None:
diff --git a/framework/db/simple_module_db/session.py b/framework/db/simple_module_db/session.py
index 709cd31cc..bcfa200d8 100644
--- a/framework/db/simple_module_db/session.py
+++ b/framework/db/simple_module_db/session.py
@@ -39,6 +39,10 @@ class DatabaseState:
     session_factory: async_sessionmaker[RequestSession]
     sync_session_class: type[Session] = field(repr=False, default=Session)
     audit_callback: Callable | None = field(default=None, repr=False)
+    # Strict bulk auditing (#557): a bool, or a zero-arg callable read per
+    # statement so a settings save applies without a restart. When true an
+    # ``execution_options(sm_audit=False)`` write to an audited model raises.
+    refuse_unaudited_dml: bool | Callable[[], bool] = field(default=False, repr=False)
     # Fail closed: a query on a MultiTenantMixin model with no tenant context
     # raises instead of reading every tenant. The host turns this on whenever
     # it runs with ``multi_tenant``; see ``simple_module_db.tenancy``.
diff --git a/framework/db/tests/test_db_bulk_audit.py b/framework/db/tests/test_db_bulk_audit.py
new file mode 100644
index 000000000..5ca1d1095
--- /dev/null
+++ b/framework/db/tests/test_db_bulk_audit.py
@@ -0,0 +1,199 @@
+"""Statement DML is audited like a flush (#557): ORM bulk, Core DML, ``text()`` via helper."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator
+
+import pytest
+from _audit_models import (
+    AuditBase,
+    AuditTestItem,
+    ExcludedModel,
+    PartialExcludeModel,
+    SoftDeleteItem,
+)
+from _models import _TenantBase, _TenantItem
+from simple_module_db import bulk_audit, record_bulk_audit, tenant_context
+from simple_module_db.audit import AuditRecord
+from simple_module_db.listeners import register_listeners
+from simple_module_db.session import DatabaseState, init_db
+from simple_module_test.database import database_url_for_tests, init_db_kwargs, reset_schema
+from sqlalchemy import delete, func, insert, select, text, update
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import Session
+
+_URL = database_url_for_tests()
+
+
+class _Recorder:
+    def __init__(self) -> None:
+        self.records: list[AuditRecord] = []
+
+    def __call__(self, session: Session, records: list[AuditRecord]) -> None:
+        self.records.extend(records)
+
+    def summary(self) -> list[tuple[str, str, str]]:
+        return [(r.entity_type, r.action, r.entity_id) for r in self.records]
+
+
+@pytest.fixture
+async def audited() -> AsyncGenerator[tuple[DatabaseState, AsyncSession, _Recorder]]:
+    recorder = _Recorder()
+    state = init_db(_URL, **init_db_kwargs(_URL))
+    state.audit_callback = recorder
+    register_listeners(state)
+    await reset_schema(state.engine)
+    async with state.engine.begin() as conn:
+        await conn.run_sync(AuditBase.metadata.create_all)
+        await conn.run_sync(_TenantBase.metadata.create_all)
+    async with state.session_factory() as session:
+        session.add_all([AuditTestItem(name=f"n{i}", value=i) for i in range(3)])
+        await session.flush()
+        recorder.records.clear()
+        yield state, session, recorder
+    await state.engine.dispose()
+
+
+async def _ids(session: AsyncSession, where=None) -> list[str]:
+    query = select(AuditTestItem.id).order_by(AuditTestItem.id)
+    if where is not None:
+        query = query.where(where)
+    return [str(i) for i in (await session.execute(query)).scalars()]
+
+
+async def test_orm_bulk_update_records_each_row_with_set_values(audited):
+    _state, session, recorder = audited
+    expected = await _ids(session, AuditTestItem.value >= 1)
+    await session.execute(update(AuditTestItem).where(AuditTestItem.value >= 1).values(name="x"))
+    assert sorted(r.entity_id for r in recorder.records) == expected
+    assert {r.action for r in recorder.records} == {"bulk_updated"}
+    assert recorder.records[0].changes == [{"field": "name", "new": "x"}]
+
+
+async def test_orm_bulk_delete_records_each_row(audited):
+    _state, session, recorder = audited
+    expected = await _ids(session)
+    await session.execute(delete(AuditTestItem))
+    assert sorted(r.entity_id for r in recorder.records) == expected
+    assert {(r.action, tuple(r.changes)) for r in recorder.records} == {("bulk_deleted", ())}
+
+
+async def test_core_dml_on_table_is_audited(audited):
+    _state, session, recorder = audited
+    table = AuditTestItem.__table__
+    target = (await _ids(session, AuditTestItem.value == 2))[0]
+    await session.execute(update(table).where(table.c.value == 2).values(value=table.c.value + 1))
+    await session.execute(delete(table).where(table.c.value == 0))
+    actions = [(r.action, r.entity_id) for r in recorder.records]
+    assert actions[0] == ("bulk_updated", target)
+    assert recorder.records[0].changes[0]["field"] == "value"
+    assert actions[1][0] == "bulk_deleted"
+
+
+async def test_insert_statement_records_one_summary_row(audited):
+    _state, session, recorder = audited
+    rows = [{"name": "a", "value": 1}, {"name": "b", "value": 2}]
+    await session.execute(insert(AuditTestItem), rows)
+    await session.execute(insert(AuditTestItem.__table__).values(name="c", value=3))
+    assert [(r.action, r.entity_id) for r in recorder.records] == [("bulk_inserted", "*")] * 2
+    assert {"field": "rowcount", "new": 2} in recorder.records[0].changes
+    assert {"field": "name", "new": "c"} in recorder.records[1].changes
+
+
+async def test_over_the_cap_records_one_summary_without_literals(audited, monkeypatch):
+    _state, session, recorder = audited
+    monkeypatch.setattr(bulk_audit, "BULK_AUDIT_ID_CAP", 2)
+    await session.execute(update(AuditTestItem).where(AuditTestItem.value < 99).values(name="s"))
+    assert [(r.action, r.entity_id) for r in recorder.records] == [("bulk_updated", "*")]
+    changes = {c["field"]: c["new"] for c in recorder.records[0].changes}
+    assert changes["rowcount"] == 3 and changes["truncated"] is True and changes["name"] == "s"
+    assert "99" not in changes["where_sql"] and "value" in changes["where_sql"]
+
+
+async def test_excluded_columns_and_models(audited):
+    _state, session, recorder = audited
+    session.add_all([PartialExcludeModel(username="u"), ExcludedModel(name="e")])
+    await session.flush()
+    recorder.records.clear()
+    await session.execute(update(PartialExcludeModel).values(password_hash="h"))
+    await session.execute(update(ExcludedModel).values(name="z"))
+    await session.execute(update(AuditTestItem).values(updated_by="bot"))
+    assert recorder.records == []
+    await session.execute(update(PartialExcludeModel).values(username="v", password_hash="h2"))
+    assert recorder.records[0].changes == [{"field": "username", "new": "v"}]
+
+
+async def test_bulk_soft_delete_is_recorded(audited):
+    _state, session, recorder = audited
+    session.add(SoftDeleteItem(title="t"))
+    await session.flush()
+    recorder.records.clear()
+    await session.execute(update(SoftDeleteItem).values(is_deleted=True))
+    assert [r.action for r in recorder.records] == ["bulk_soft_deleted"]
+
+
+async def test_bulk_update_by_primary_key_uses_the_rows(audited):
+    _state, session, recorder = audited
+    ids = [int(i) for i in await _ids(session)]
+    await session.execute(update(AuditTestItem), [{"id": i, "name": "pk"} for i in ids[:2]])
+    assert [r.entity_id for r in recorder.records] == [str(i) for i in ids[:2]]
+    assert recorder.records[0].changes == [{"field": "name"}]
+
+
+async def test_prefetch_keeps_the_tenant_scope(audited):
+    _state, session, recorder = audited
+    for tenant in ("a", "b"):
+        with tenant_context(tenant):
+            session.add(_TenantItem(name=tenant))
+            await session.flush()
+    recorder.records.clear()
+    with tenant_context("a"):
+        await session.execute(update(_TenantItem).values(name="renamed"))
+        own = (await session.execute(select(_TenantItem.id))).scalars().all()
+    assert [r.entity_id for r in recorder.records] == [str(i) for i in own]
+
+
+async def test_opt_out_and_strict_mode(audited):
+    state, session, recorder = audited
+    opted_out = update(AuditTestItem).values(name="quiet").execution_options(sm_audit=False)
+    await session.execute(opted_out)
+    assert recorder.records == []
+    state.refuse_unaudited_dml = lambda: True
+    with pytest.raises(bulk_audit.UnauditedWriteError):
+        await session.execute(opted_out)
+    # Excluded-only writes and excluded models would not be audited anyway.
+    await session.execute(update(ExcludedModel).values(name="z").execution_options(sm_audit=False))
+
+
+async def test_sink_failure_never_breaks_the_write(audited):
+    state, session, _recorder = audited
+
+    def _boom(session: Session, records: list[AuditRecord]) -> None:
+        raise RuntimeError("sink down")
+
+    state.audit_callback = _boom
+    await session.execute(update(AuditTestItem).values(name="kept"))
+    names = (await session.execute(select(func.count()).where(AuditTestItem.name == "kept"))).one()
+    assert names[0] == 3
+
+
+async def test_record_bulk_audit_for_text_writes(audited):
+    _state, session, recorder = audited
+    await session.execute(text("UPDATE test_audit_item SET value = 7"))
+    assert recorder.records == []
+    record_bulk_audit(session, AuditTestItem, "bulk_updated", [1, 2], {"value": 7})
+    record_bulk_audit(session, "Raw", "bulk_deleted", None)
+    assert recorder.summary() == [
+        ("AuditTestItem", "bulk_updated", "1"),
+        ("AuditTestItem", "bulk_updated", "2"),
+        ("Raw", "bulk_deleted", "*"),
+    ]
+    assert recorder.records[0].changes == [{"field": "value", "new": 7}]
+
+
+async def test_unaudited_engine_records_nothing(audited):
+    state, session, recorder = audited
+    state.audit_callback = None
+    await session.execute(update(AuditTestItem).values(name="n"))
+    record_bulk_audit(session, AuditTestItem, "bulk_updated", [1])
+    assert recorder.records == []
diff --git a/modules/audit_log/audit_log/constants.py b/modules/audit_log/audit_log/constants.py
index 95511ef3c..25b0c64a4 100644
--- a/modules/audit_log/audit_log/constants.py
+++ b/modules/audit_log/audit_log/constants.py
@@ -28,7 +28,21 @@
 ACTION_UPDATED: Final = "updated"
 ACTION_DELETED: Final = "deleted"
 ACTION_SOFT_DELETED: Final = "soft_deleted"
-ALL_ACTIONS: Final = (ACTION_CREATED, ACTION_UPDATED, ACTION_DELETED, ACTION_SOFT_DELETED)
+# Statement DML (#557); the names match ``simple_module_db.bulk_audit``.
+ACTION_BULK_INSERTED: Final = "bulk_inserted"
+ACTION_BULK_UPDATED: Final = "bulk_updated"
+ACTION_BULK_DELETED: Final = "bulk_deleted"
+ACTION_BULK_SOFT_DELETED: Final = "bulk_soft_deleted"
+ALL_ACTIONS: Final = (
+    ACTION_CREATED,
+    ACTION_UPDATED,
+    ACTION_DELETED,
+    ACTION_SOFT_DELETED,
+    ACTION_BULK_INSERTED,
+    ACTION_BULK_UPDATED,
+    ACTION_BULK_DELETED,
+    ACTION_BULK_SOFT_DELETED,
+)
 
 ENTITY_TYPE_MAX_LENGTH: Final = 255
 ENTITY_ID_MAX_LENGTH: Final = 255
diff --git a/modules/audit_log/audit_log/locales/de.json b/modules/audit_log/audit_log/locales/de.json
index afcff861f..669868e82 100644
--- a/modules/audit_log/audit_log/locales/de.json
+++ b/modules/audit_log/audit_log/locales/de.json
@@ -37,7 +37,11 @@
     "created": "erstellt",
     "updated": "aktualisiert",
     "deleted": "gelöscht",
-    "soft_deleted": "archiviert"
+    "soft_deleted": "archiviert",
+    "bulk_inserted": "massenweise erstellt",
+    "bulk_updated": "massenweise geändert",
+    "bulk_deleted": "massenweise gelöscht",
+    "bulk_soft_deleted": "massenweise archiviert"
   },
   "correlation": {
     "view_related": "Zugehörige Einträge",
diff --git a/modules/audit_log/audit_log/locales/en.json b/modules/audit_log/audit_log/locales/en.json
index de8a422ae..37dde5478 100644
--- a/modules/audit_log/audit_log/locales/en.json
+++ b/modules/audit_log/audit_log/locales/en.json
@@ -37,7 +37,11 @@
     "created": "created",
     "updated": "updated",
     "deleted": "deleted",
-    "soft_deleted": "archived"
+    "soft_deleted": "archived",
+    "bulk_inserted": "bulk created",
+    "bulk_updated": "bulk updated",
+    "bulk_deleted": "bulk deleted",
+    "bulk_soft_deleted": "bulk archived"
   },
   "correlation": {
     "view_related": "Related",
diff --git a/modules/audit_log/audit_log/module.py b/modules/audit_log/audit_log/module.py
index f3cef5700..90ec1d437 100644
--- a/modules/audit_log/audit_log/module.py
+++ b/modules/audit_log/audit_log/module.py
@@ -8,6 +8,7 @@
 from fastapi import APIRouter, FastAPI
 from simple_module_core.menu import MenuItem, MenuRegistry, MenuSection
 from simple_module_core.module import ModuleBase, ModuleMeta
+from simple_module_core.module_settings import register_module_settings
 from simple_module_core.permissions import PermissionRegistry
 
 from audit_log.constants import (
@@ -19,6 +20,7 @@
     MENU_ORDER,
     MENU_URL,
     MODULE_NAME,
+    MODULE_PACKAGE,
     PERM_GROUP,
     PERM_VIEW,
     VIEW_PREFIX,
@@ -33,6 +35,14 @@ class AuditLogModule(ModuleBase):
         i18n_audience="admin",
     )
 
+    def register_settings(self, app: FastAPI) -> None:
+        from audit_log.services import AuditLogServices
+        from audit_log.settings import AuditLogSettings
+
+        register_module_settings(
+            app, MODULE_PACKAGE, AuditLogSettings, lambda s: AuditLogServices(settings=s)
+        )
+
     def register_routes(self, api_router: APIRouter, view_router: APIRouter) -> None:
         from audit_log.endpoints.api import router as api
         from audit_log.endpoints.views import router as views
@@ -70,17 +80,18 @@ async def on_startup(self, app: FastAPI) -> None:
         from audit_log.activity import AuditActivityFeed
         from audit_log.capture import audit_callback
 
-        app.state.sm.db.audit_callback = audit_callback
-        # Offer the audit trail as the app's activity feed (GH #501). Installed
-        # here, not in ``register_settings``: this module has no settings, and
-        # overriding that hook without touching ``app.state.audit_log`` raises
-        # SM012.
+        db = app.state.sm.db
+        db.audit_callback = audit_callback
+        # Read per statement, so a settings save applies without a restart (#557).
+        db.refuse_unaudited_dml = lambda: app.state.audit_log.settings.refuse_unaudited_dml
+        # Offer the audit trail as the app's activity feed (GH #501).
         set_activity_feed(app, AuditActivityFeed(app))
 
     async def on_shutdown(self, app: FastAPI) -> None:
         from simple_module_core.activity_feed import set_activity_feed
 
         app.state.sm.db.audit_callback = None
+        app.state.sm.db.refuse_unaudited_dml = False
         set_activity_feed(app, None)
 
     def locale_dirs(self) -> dict[str, Path]:
diff --git a/modules/audit_log/audit_log/pages/components/ChangesList.tsx b/modules/audit_log/audit_log/pages/components/ChangesList.tsx
index b34101c05..bc4eec310 100644
--- a/modules/audit_log/audit_log/pages/components/ChangesList.tsx
+++ b/modules/audit_log/audit_log/pages/components/ChangesList.tsx
@@ -17,6 +17,8 @@ export interface Change {
  */
 const VISIBLE_LIMIT = 2;
 
+const DELETE_ACTIONS = new Set(['deleted', 'soft_deleted', 'bulk_deleted', 'bulk_soft_deleted']);
+
 interface ChangesListProps {
   action: string;
   changes: Change[];
@@ -28,12 +30,12 @@ export function ChangesList({ action, changes }: ChangesListProps) {
 
   // A delete records no diff — every field went away with the row. Saying
   // "no changes recorded" is the honest reading; a dash reads as a bug.
-  if (action === 'deleted' || action === 'soft_deleted') {
+  if (DELETE_ACTIONS.has(action)) {
     return <span className="text-muted-foreground">{t(keys.audit_log.changes.no_changes)}</span>;
   }
   // A create sets every field at once. Listing them all would bury the rows
   // that record an actual change, which is what this column is for.
-  if (action === 'created') {
+  if (action === 'created' || action === 'bulk_inserted') {
     return (
       <span className="text-muted-foreground">
         {t(keys.audit_log.changes.fields_set, { count: changes.length })}
diff --git a/modules/audit_log/audit_log/pages/components/EntriesTable.tsx b/modules/audit_log/audit_log/pages/components/EntriesTable.tsx
index ea33b1f65..823f4c354 100644
--- a/modules/audit_log/audit_log/pages/components/EntriesTable.tsx
+++ b/modules/audit_log/audit_log/pages/components/EntriesTable.tsx
@@ -10,13 +10,14 @@ import {
 import { type Change, ChangesList } from './ChangesList';
 import { CorrelationLink } from './Correlation';
 import { ActorCell, EntityCell, type EntityRef } from './EntryCells';
+import type { ACTIONS } from './FilterBar';
 import { formatEntryTime } from './format';
 
 export interface AuditEntryRead {
   id: string;
   entity_type: string;
   entity_id: string;
-  action: 'created' | 'updated' | 'deleted' | 'soft_deleted';
+  action: (typeof ACTIONS)[number];
   changes: Change[];
   user_id: string | null;
   /** Display name resolved from user_id, or null for deleted/system actors. */
@@ -41,6 +42,10 @@ const ACTION_PILL: Record<string, string> = {
   updated: 'bg-blue-50 text-blue-700',
   deleted: 'bg-red-50 text-red-700',
   soft_deleted: 'bg-amber-50 text-amber-700',
+  bulk_inserted: 'bg-primary-600/10 text-primary-700',
+  bulk_updated: 'bg-blue-50 text-blue-700',
+  bulk_deleted: 'bg-red-50 text-red-700',
+  bulk_soft_deleted: 'bg-amber-50 text-amber-700',
 };
 const PILL = 'inline-flex rounded-full px-2.5 py-0.5 text-[11px] font-medium';
 const TH = 'sm:px-6 text-[11px] font-semibold uppercase tracking-[0.08em] text-muted-foreground';
diff --git a/modules/audit_log/audit_log/pages/components/FilterBar.tsx b/modules/audit_log/audit_log/pages/components/FilterBar.tsx
index 6716a08dc..98b959bc0 100644
--- a/modules/audit_log/audit_log/pages/components/FilterBar.tsx
+++ b/modules/audit_log/audit_log/pages/components/FilterBar.tsx
@@ -15,7 +15,16 @@ import { DateRangeField } from './DateRangeField';
 export const ALL = '__all__';
 /** Exported so other panels (the empty-state filter summary) name the same
  * set of actions instead of hand-copying it and risking drift. */
-export const ACTIONS = ['created', 'updated', 'deleted', 'soft_deleted'] as const;
+export const ACTIONS = [
+  'created',
+  'updated',
+  'deleted',
+  'soft_deleted',
+  'bulk_inserted',
+  'bulk_updated',
+  'bulk_deleted',
+  'bulk_soft_deleted',
+] as const;
 
 /** A filterable entity type: the class name the column stores, shown as the
  * table name an operator recognises. Built server-side from the registry. */
diff --git a/modules/audit_log/audit_log/services.py b/modules/audit_log/audit_log/services.py
new file mode 100644
index 000000000..88df23aca
--- /dev/null
+++ b/modules/audit_log/audit_log/services.py
@@ -0,0 +1,14 @@
+"""Module-scoped state container, stored as ``app.state.audit_log``."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from audit_log.settings import AuditLogSettings
+
+
+@dataclass
+class AuditLogServices:
+    """audit_log singletons. ``settings`` is swapped on a settings save."""
+
+    settings: AuditLogSettings
diff --git a/modules/audit_log/audit_log/settings.py b/modules/audit_log/audit_log/settings.py
new file mode 100644
index 000000000..7ac0a0931
--- /dev/null
+++ b/modules/audit_log/audit_log/settings.py
@@ -0,0 +1,20 @@
+"""audit_log settings — DB-backed via ``register_module_settings``."""
+
+from __future__ import annotations
+
+from pydantic import Field
+from pydantic_settings import SettingsConfigDict
+from simple_module_core.settings_base import DbBackedSettings
+
+
+class AuditLogSettings(DbBackedSettings):
+    """Configuration for the audit trail."""
+
+    model_config = SettingsConfigDict(extra="ignore")
+
+    refuse_unaudited_dml: bool = Field(default=False)
+    """Raise on an ``execution_options(sm_audit=False)`` write to an audited model (#557).
+
+    Off by default. On, statement DML against an audited model can no longer
+    opt out of the trail; ``text()`` writes still need ``record_bulk_audit``.
+    """
diff --git a/modules/audit_log/tests/test_audit_log_bulk_capture.py b/modules/audit_log/tests/test_audit_log_bulk_capture.py
new file mode 100644
index 000000000..4046064e0
--- /dev/null
+++ b/modules/audit_log/tests/test_audit_log_bulk_capture.py
@@ -0,0 +1,61 @@
+"""Statement DML lands in ``audit_log_audit_entry`` through the app's sink (#557)."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+import pytest
+from audit_log.models import AuditEntry
+from background_tasks.models import TaskExecution
+from simple_module_db import UnauditedWriteError, all_tenants, tenant_context
+from sqlalchemy import select, update
+
+
+async def _entries(app) -> list[AuditEntry]:
+    async with app.state.sm.db.session_factory() as session:
+        with all_tenants():
+            stmt = select(AuditEntry).where(AuditEntry.entity_type == TaskExecution.__name__)
+            return list((await session.execute(stmt)).scalars())
+
+
+@pytest.fixture
+async def task_id(app) -> str:
+    async with app.state.sm.db.session_factory() as session:
+        row = TaskExecution(task_name="demo.task")
+        session.add(row)
+        await session.commit()
+        return str(row.id)
+
+
+async def _execute(app, stmt, *, commit: bool = True) -> None:
+    async with app.state.sm.db.session_factory() as session:
+        with tenant_context("tenant-a"):
+            await session.execute(stmt)
+            if commit:
+                await session.commit()
+
+
+async def test_bulk_update_is_audited_with_the_tenant(app, task_id):
+    await _execute(app, update(TaskExecution).values(worker="w1"))
+    bulk = [e for e in await _entries(app) if e.action == "bulk_updated"]
+    assert [(e.entity_id, e.tenant_id) for e in bulk] == [(task_id, "tenant-a")]
+    assert bulk[0].changes == [{"field": "worker", "new": "w1"}]
+
+
+async def test_heartbeat_update_writes_no_entry(app, task_id):
+    await _execute(app, update(TaskExecution).values(heartbeat_at=datetime.now(UTC)))
+    assert [e.action for e in await _entries(app)] == ["created"]
+
+
+async def test_rolled_back_write_leaves_no_entry(app, task_id):
+    await _execute(app, update(TaskExecution).values(worker="w2"), commit=False)
+    assert [e.action for e in await _entries(app)] == ["created"]
+
+
+async def test_refuse_unaudited_dml_setting(app, task_id):
+    quiet = update(TaskExecution).values(worker="w3").execution_options(sm_audit=False)
+    await _execute(app, quiet)
+    app.state.audit_log.settings.refuse_unaudited_dml = True
+    with pytest.raises(UnauditedWriteError):
+        await _execute(app, quiet)
+    assert [e.action for e in await _entries(app)] == ["created"]
diff --git a/packages/i18n/src/generated-resources.ts b/packages/i18n/src/generated-resources.ts
index 774dcb122..cb536960b 100644
--- a/packages/i18n/src/generated-resources.ts
+++ b/packages/i18n/src/generated-resources.ts
@@ -79,6 +79,10 @@ export default {
     'api_tokens.toasts.revoked': '',
     'api_tokens.toasts.revoked_all_one': '',
     'api_tokens.toasts.revoked_all_other': '',
+    'audit_log.actions.bulk_deleted': '',
+    'audit_log.actions.bulk_inserted': '',
+    'audit_log.actions.bulk_soft_deleted': '',
+    'audit_log.actions.bulk_updated': '',
     'audit_log.actions.created': '',
     'audit_log.actions.deleted': '',
     'audit_log.actions.soft_deleted': '',
diff --git a/packages/i18n/src/keys.generated.ts b/packages/i18n/src/keys.generated.ts
index 2cc9bd489..8e39b76e7 100644
--- a/packages/i18n/src/keys.generated.ts
+++ b/packages/i18n/src/keys.generated.ts
@@ -112,6 +112,10 @@ export const keys = {
   },
   audit_log: {
     actions: {
+      bulk_deleted: 'audit_log.actions.bulk_deleted',
+      bulk_inserted: 'audit_log.actions.bulk_inserted',
+      bulk_soft_deleted: 'audit_log.actions.bulk_soft_deleted',
+      bulk_updated: 'audit_log.actions.bulk_updated',
       created: 'audit_log.actions.created',
       deleted: 'audit_log.actions.deleted',
       soft_deleted: 'audit_log.actions.soft_deleted',

From 9a2380ffdd3be05b363ea2463bdac4267e334292 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Thu, 22 Oct 2026 09:23:56 +0200
Subject: [PATCH 06/21] feat: legacy SPA mounts with deep-link fallback and
 scoped link interception (#541)

SpaMount + ModuleBase.spa_mounts(), SM031 overlap diagnostic, nativePrefixes
shared prop, native_link_prefixes host setting, startSpaLinkInterception({ exclude }).

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 CHANGELOG.md                                  |   1 +
 CLAUDE.md                                     |   2 +-
 docs/.vitepress/config.ts                     |   1 +
 docs/framework/spa-mounts.md                  |  66 +++++++
 docs/reference/diagnostic-codes.md            |   1 +
 framework/core/simple_module_core/__init__.py |   2 +
 .../simple_module_core/diagnostics/_module.py |   3 +
 .../diagnostics/_spa_mount.py                 |  38 ++++
 framework/core/simple_module_core/module.py   |  34 ++--
 .../core/simple_module_core/spa_mount.py      |  58 ++++++
 .../simple_module_hosting/_phase_helpers.py   |   2 +
 .../simple_module_hosting/_spa_mount.py       | 126 ++++++++++++
 .../simple_module_hosting/host_settings.py    |  13 ++
 .../simple_module_hosting/middleware.py       |   2 +
 .../hosting/tests/test_spa_mounts_541.py      | 182 ++++++++++++++++++
 host/client_app/app.tsx                       |  16 +-
 packages/ui/src/index.ts                      |   8 +-
 packages/ui/src/lib/spa-links.test.ts         |  48 ++++-
 packages/ui/src/lib/spa-links.ts              |  35 +++-
 19 files changed, 613 insertions(+), 25 deletions(-)
 create mode 100644 docs/framework/spa-mounts.md
 create mode 100644 framework/core/simple_module_core/diagnostics/_spa_mount.py
 create mode 100644 framework/core/simple_module_core/spa_mount.py
 create mode 100644 framework/hosting/simple_module_hosting/_spa_mount.py
 create mode 100644 framework/hosting/tests/test_spa_mounts_541.py

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 94bd54379..4c3a731eb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,7 @@ All notable changes to this project are documented in this file. The format is b
 - `host/client_app` no longer re-declares `@simple-module-py/ui`'s runtime dependencies, nor `@base-ui/react`, `@radix-ui/react-slot`, `autoprefixer` or `postcss` (nothing loaded them) (#521).
 
 ### Added
+- Legacy SPA mounts (#541): `ModuleBase.spa_mounts()` returns `SpaMount(prefix, dist_dir, index="index.html", auth="required"|"public")` entries served with an `index.html` deep-link fallback (extension-less paths accepting HTML only; a missing asset stays a 404; hashed assets `immutable`; GET/HEAD only). `auth="public"` exempts GET/HEAD from `AuthMiddleware`. A prefix overlapping a router, static mount or another SPA fails boot (`SM031`). The Inertia client leaves these prefixes to the browser: `startSpaLinkInterception({ exclude })` plus the framework shared prop `nativePrefixes`, which also carries the new DB-backed host setting `native_link_prefixes` (no migration).
 - Release process (#510): `release.yml` runs the whole PR suite (`pr.yml` via
   `workflow_call`) against the dispatched commit and `build` needs it, so nothing
   is built or published from a red commit. The duplicated bump + lockfile steps
diff --git a/CLAUDE.md b/CLAUDE.md
index e08533da1..e665ebb2e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -168,7 +168,7 @@ every Tailwind utility, so keep tokens in `theme.css` and rules in `styles.css`
 `register_routes(api_router, view_router)`, `register_admin_routes(admin_router)`
 (only with `ModuleMeta.admin_view_prefix`), then async `on_startup` /
 `on_shutdown` (reverse order). Non-hook overrides: `locale_dirs()`,
-`db_extensions()`, `template_dirs()`, `static_mounts()`.
+`db_extensions()`, `template_dirs()`, `static_mounts()`, `spa_mounts()`.
 
 - A module gets one view router per prefix. All-admin modules point
   `view_prefix` at `/admin/<name>`; modules with both public and admin pages set
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index 6cfbca30e..ebde23834 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -125,6 +125,7 @@ export default defineConfig({
             { text: "Principal resolvers", link: "/framework/principal-resolvers" },
             { text: "User directory", link: "/framework/user-directory" },
             { text: "Public routes", link: "/framework/public-routes" },
+            { text: "Legacy SPA mounts", link: "/framework/spa-mounts" },
             { text: "Deprecations", link: "/framework/deprecations" },
             { text: "Events", link: "/framework/events" },
             { text: "Cache invalidation", link: "/framework/invalidation" },
diff --git a/docs/framework/spa-mounts.md b/docs/framework/spa-mounts.md
new file mode 100644
index 000000000..ea726fc19
--- /dev/null
+++ b/docs/framework/spa-mounts.md
@@ -0,0 +1,66 @@
+# Legacy SPA mounts
+
+Porting a large app step by step means running its existing client-routed SPA
+next to new Inertia pages for a while. A module serves the SPA's build output
+under a prefix by overriding `ModuleBase.spa_mounts()`:
+
+```python
+from pathlib import Path
+
+from simple_module_core import ModuleBase, SpaMount
+
+
+class LegacyModule(ModuleBase):
+    def spa_mounts(self) -> list[SpaMount]:
+        return [SpaMount("/legacy", Path(__file__).parent / "dist", auth="required")]
+```
+
+`SpaMount(prefix, dist_dir, index="index.html", auth="required" | "public")`.
+A mount whose `dist_dir/index` does not exist (the SPA was not built) is skipped
+with a warning.
+
+## What is served
+
+- `GET`/`HEAD` only; other methods are refused.
+- A file that exists is served as is. Content-hashed files (`index-3f9a8c21.js`)
+  get `Cache-Control: public, max-age=31536000, immutable`.
+- A missing path **without an extension** whose request accepts `text/html`
+  (`/legacy/datasets/123`) is answered with `index.html`, `Cache-Control: no-cache`,
+  so the SPA's router takes over.
+- A missing asset (`/legacy/missing.js`) or a missing path that does not accept
+  HTML is a plain 404, never HTML.
+- No filesystem path is built from the request: lookups go through `StaticFiles`,
+  paths containing `..` are refused, and the fallback only ever serves the
+  configured index file.
+
+## Authentication
+
+`auth="required"` (the default) leaves the mount behind `AuthMiddleware`:
+an anonymous visitor is redirected to login. `auth="public"` registers the prefix
+in the [public route registry](/framework/public-routes) for `GET`/`HEAD` only.
+CSP applies as for any response; whitelist external origins the SPA needs with
+`register_csp_sources`.
+
+## Boot check
+
+A prefix that overlaps a module's route/view prefix, a `static_mounts()` prefix,
+a framework path or another SPA mount fails boot with
+[`SM031`](/reference/diagnostic-codes), in every environment.
+
+## Inertia link interception
+
+The Inertia client turns same-origin link clicks into Inertia visits
+(`startSpaLinkInterception`). Links into a legacy SPA must stay full navigations,
+so the server publishes a shared prop `nativePrefixes`: the mounted SPA prefixes
+(with a trailing slash) plus the DB-backed host setting `native_link_prefixes`
+(a list such as `["/docs/"]`, editable under Settings, read per request).
+`host/client_app/app.tsx` passes them to the interceptor:
+
+```ts
+startSpaLinkInterception({ exclude: (url) => isExcluded(url, nativePrefixes) });
+```
+
+`exclude` also accepts a prefix string or a list of prefixes. An Inertia
+`<Link>` or `router.visit()` pointing into a mount is not covered; use a plain
+`<a href>` there. Links inside the SPA are never touched, because the SPA is its
+own document without the Inertia client.
diff --git a/docs/reference/diagnostic-codes.md b/docs/reference/diagnostic-codes.md
index 1876cb814..a1ad00528 100644
--- a/docs/reference/diagnostic-codes.md
+++ b/docs/reference/diagnostic-codes.md
@@ -39,6 +39,7 @@ The framework runs a set of static checks over installed modules at app boot. Th
 | `SM028` | WARNING | A module's `tasks.py` imports `torch`, `tensorflow`, `ultralytics`, `osgeo`, `rasterio`, `cv2` or `sklearn` at module level, so every process that loads the module's tasks (web, each worker, beat) pays for it and a queue-restricted worker cannot avoid it. | Import the package inside the task function. See [background_tasks](/modules/background_tasks#running-a-worker-for-a-subset-of-modules). |
 | `SM029` | INFO | A module overrides `db_extensions()` (Postgres extensions such as `ltree`) and the configured database is SQLite, which has none. `ensure_db_extensions` raises `UnsupportedDatabaseError` when migrations run. | Point `SM_DATABASE_URL` at PostgreSQL. See [Postgres extensions and column types](/database/extensions). |
 | `SM030` | WARNING at a dev boot; ERROR in `make doctor` | A module's `depends_on` names a module that is not loaded (not installed, left out of `SM_MODULES_ENABLED`, or dropped because another auth provider was selected — `keycloak` drops `Users`). Outside development the boot raises `MissingDependencyError` listing every pair. | Install and enable the dependency, or leave the dependent module out. A relationship that is only about order belongs in `optional_depends_on`. See [Discovery](/framework/discovery#modulemeta). |
+| `SM031` | ERROR (fails boot in every environment) | A `ModuleBase.spa_mounts()` prefix overlaps a module's `route_prefix`/`view_prefix`/`admin_view_prefix`, a `static_mounts()` prefix, a framework path (`/api`, `/admin`, `/setup`, `/i18n`, `/health`, `/static`, `/modules`) or another SPA mount. The mount would shadow, or be shadowed by, that router. | Pick a prefix nothing else uses. See [Legacy SPA mounts](/framework/spa-mounts). |
 
 `SM022`/`SM023` are the two halves of the same invariant: a module's optional [`theme.css` is imported unlayered and `styles.css` into `layer(components)`](/module-authoring#styling), and CSS put in the wrong one silently does nothing (or silently wins everything).
 
diff --git a/framework/core/simple_module_core/__init__.py b/framework/core/simple_module_core/__init__.py
index baa9f3cc2..1c31a8816 100644
--- a/framework/core/simple_module_core/__init__.py
+++ b/framework/core/simple_module_core/__init__.py
@@ -55,6 +55,7 @@
 from simple_module_core.public_routes import PublicRoute, PublicRouteRegistry
 from simple_module_core.services import Services
 from simple_module_core.setup_steps import SetupAction, SetupField, SetupRegistry, SetupStep
+from simple_module_core.spa_mount import SpaMount
 from simple_module_core.tenancy import TENANT_ROLE_PREFIX, TenantRole, is_tenant_role, tenant_role
 from simple_module_core.versioning import FRAMEWORK_API_VERSION, check_framework_compatibility
 
@@ -106,6 +107,7 @@
     "SetupField",
     "SetupRegistry",
     "SetupStep",
+    "SpaMount",
     "TenantRole",
     "Translator",
     "ValidationError",
diff --git a/framework/core/simple_module_core/diagnostics/_module.py b/framework/core/simple_module_core/diagnostics/_module.py
index 972436304..95e23fe2b 100644
--- a/framework/core/simple_module_core/diagnostics/_module.py
+++ b/framework/core/simple_module_core/diagnostics/_module.py
@@ -13,6 +13,7 @@
 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
+from simple_module_core.diagnostics._spa_mount import check_spa_mount_overlaps
 from simple_module_core.diagnostics._tenancy import check_tenant_unique_keys, module_tables
 from simple_module_core.diagnostics._types import Diagnostic, DiagnosticLevel
 
@@ -33,6 +34,7 @@ def run(self, modules: list[ModuleBase]) -> list[Diagnostic]:
         diagnostics.extend(self._check_auth_provider_conflict(modules))
         diagnostics.extend(check_missing_dependencies(modules))
         diagnostics.extend(check_framework_module_coupling(modules))
+        diagnostics.extend(check_spa_mount_overlaps(modules))
         for mod in modules:
             diagnostics.extend(check_tenant_unique_keys(module_tables(mod), mod.meta.name))
 
@@ -112,6 +114,7 @@ def _check_empty_modules(self, modules: list[ModuleBase]) -> list[Diagnostic]:
                     "register_settings",
                     "template_dirs",
                     "static_mounts",
+                    "spa_mounts",
                     "locale_dirs",
                     "db_extensions",
                     "on_startup",
diff --git a/framework/core/simple_module_core/diagnostics/_spa_mount.py b/framework/core/simple_module_core/diagnostics/_spa_mount.py
new file mode 100644
index 000000000..32c34bc3a
--- /dev/null
+++ b/framework/core/simple_module_core/diagnostics/_spa_mount.py
@@ -0,0 +1,38 @@
+"""SM031: a legacy SPA mount whose prefix overlaps a router, static mount or other SPA."""
+
+from __future__ import annotations
+
+from simple_module_core.diagnostics._types import Diagnostic, DiagnosticLevel
+from simple_module_core.spa_mount import RESERVED_PREFIXES, prefixes_overlap
+
+SPA_MOUNT_OVERLAP_CODE = "SM031"
+
+
+def check_spa_mount_overlaps(modules: list) -> list[Diagnostic]:
+    """SM031: a SPA mount prefix overlaps a router prefix or another mount."""
+    owners: list[tuple[str, str]] = [(p, "framework") for p in RESERVED_PREFIXES]
+    for mod in modules:
+        for prefix in (mod.meta.route_prefix, mod.meta.view_prefix, mod.meta.admin_view_prefix):
+            if prefix:
+                owners.append((prefix, mod.meta.name))
+        owners.extend((p, mod.meta.name) for p in mod.static_mounts())
+
+    found: list[Diagnostic] = []
+    seen: list[tuple[str, str]] = []
+    for mod in modules:
+        for mount in mod.spa_mounts():
+            for prefix, owner in [*owners, *seen]:
+                if prefixes_overlap(mount.prefix, prefix):
+                    found.append(
+                        Diagnostic(
+                            level=DiagnosticLevel.ERROR,
+                            code=SPA_MOUNT_OVERLAP_CODE,
+                            message=(
+                                f"SPA mount {mount.prefix!r} overlaps {prefix!r} (owned by {owner})"
+                            ),
+                            module_name=mod.meta.name,
+                            suggestion="Pick a prefix no router, static mount or SPA uses",
+                        )
+                    )
+            seen.append((mount.prefix, mod.meta.name))
+    return found
diff --git a/framework/core/simple_module_core/module.py b/framework/core/simple_module_core/module.py
index 1ca54c1d7..a96b1f01a 100644
--- a/framework/core/simple_module_core/module.py
+++ b/framework/core/simple_module_core/module.py
@@ -23,6 +23,7 @@
     from simple_module_core.permissions import PermissionRegistry
     from simple_module_core.public_routes import PublicRouteRegistry
     from simple_module_core.setup_steps import SetupRegistry
+    from simple_module_core.spa_mount import SpaMount
 
 
 class ModuleBase(ABC):
@@ -71,13 +72,10 @@ class ModuleBase(ABC):
 
     meta: ModuleMeta
 
-    # ── Settings ─────────────────────────────────────────────
-
     def register_settings(self, app: FastAPI) -> None:
         """Load module-specific settings and store on ``app.state``.
 
-        Called before all other registration hooks. Convention:
-        store as ``app.state.<module_name_lower>_settings``.
+        Called before all other registration hooks.
         """
 
     # ── Service Registration ──────────────────────────────────
@@ -92,14 +90,10 @@ def register_routes(
     def register_admin_routes(self, admin_router: APIRouter) -> None:
         """Register admin-only view routes, mounted at ``meta.admin_view_prefix``.
 
-        Only needed by modules that serve both public and administrative
-        pages — see ``ModuleMeta.admin_view_prefix``. A module whose views are
-        all administrative should point ``view_prefix`` at ``/admin/...`` and
-        keep using ``register_routes``.
-
-        Nothing here is gated automatically: the prefix is a URL convention,
-        not a permission. Guard these routes with the same dependencies you
-        would use anywhere else.
+        Only for modules serving both public and admin pages (see
+        ``ModuleMeta.admin_view_prefix``); all-admin modules point
+        ``view_prefix`` at ``/admin/...``. Nothing is gated automatically:
+        the prefix is a URL convention, not a permission.
         """
 
     def register_menu_items(self, registry: MenuRegistry) -> None:
@@ -122,9 +116,8 @@ def register_event_handlers(self, bus: EventBus, app: FastAPI | None = None) ->
     def register_invalidations(self, bus: InvalidationBus, app: FastAPI) -> None:
         """Subscribe this module's per-process caches to their channels.
 
-        Handlers may only *forget* — drop a cache entry, clear a dict. The bus
-        carries no delivery guarantee, so a handler that wrote to the database
-        would do it an unknowable number of times::
+        Handlers may only *forget* (drop a cache entry); the bus has no
+        delivery guarantee, so a database write would repeat unpredictably::
 
             def register_invalidations(self, bus, app):
                 bus.subscribe("orders.totals", lambda inv: _TOTALS.pop(inv.key, None))
@@ -233,8 +226,7 @@ def register_audit_links(self, registry):
     def register_middleware(self, app: FastAPI) -> None:
         """Add middleware to the application.
 
-        Called after core middleware (session, security headers) positioning
-        is established but before the app starts.
+        Called after core middleware is positioned, before the app starts.
         """
 
     def register_exception_handlers(self, app: FastAPI) -> None:
@@ -261,6 +253,14 @@ def static_mounts(self) -> dict[str, Path]:
         """
         return {}
 
+    def spa_mounts(self) -> list[SpaMount]:
+        """Return legacy client-routed SPAs to serve under a URL prefix.
+
+        Served from ``dist_dir`` with an ``index.html`` deep-link fallback and
+        excluded from Inertia link interception. See ``docs/framework/spa-mounts.md``.
+        """
+        return []
+
     def locale_dirs(self) -> dict[str, Path]:
         """Return ``{namespace: directory}`` mapping for locale JSON files.
 
diff --git a/framework/core/simple_module_core/spa_mount.py b/framework/core/simple_module_core/spa_mount.py
new file mode 100644
index 000000000..6c98c9050
--- /dev/null
+++ b/framework/core/simple_module_core/spa_mount.py
@@ -0,0 +1,58 @@
+"""Legacy SPA mounts: a built client-routed app served under a URL prefix.
+
+Porting a large app step by step means running its existing SPA next to new
+Inertia pages. A module declares the SPA through
+:meth:`~simple_module_core.module.ModuleBase.spa_mounts`; the host serves its
+build output with an ``index.html`` fallback for deep links and tells the
+Inertia client to leave links into the prefix alone.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+SPA_AUTH_REQUIRED = "required"
+SPA_AUTH_PUBLIC = "public"
+_AUTH_MODES = frozenset({SPA_AUTH_REQUIRED, SPA_AUTH_PUBLIC})
+
+# Paths the framework or host owns outright; a mount here would shadow them.
+RESERVED_PREFIXES = ("/api", "/admin", "/setup", "/i18n", "/health", "/static", "/modules")
+
+
+def normalise_prefix(prefix: str) -> str:
+    """``"/legacy/"`` -> ``"/legacy"``; the root and relative paths are refused."""
+    cleaned = prefix.strip().rstrip("/")
+    if not cleaned.startswith("/") or ".." in cleaned.split("/") or " " in cleaned:
+        raise ValueError(f"SPA mount prefix {prefix!r} must be an absolute URL path like '/legacy'")
+    return cleaned
+
+
+@dataclass(frozen=True)
+class SpaMount:
+    """One legacy SPA: ``dist_dir`` served at ``prefix`` with deep-link fallback.
+
+    ``auth="required"`` leaves the mount behind ``AuthMiddleware`` (anonymous
+    visitors are sent to login); ``"public"`` exempts GET/HEAD from it.
+    """
+
+    prefix: str
+    dist_dir: Path
+    index: str = "index.html"
+    auth: str = SPA_AUTH_REQUIRED
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "prefix", normalise_prefix(self.prefix))
+        object.__setattr__(self, "dist_dir", Path(self.dist_dir))
+        if self.auth not in _AUTH_MODES:
+            raise ValueError(
+                f"SpaMount.auth must be one of {sorted(_AUTH_MODES)}, got {self.auth!r}"
+            )
+        if not self.index or "/" in self.index or ".." in self.index:
+            raise ValueError(f"SpaMount.index must be a bare file name, got {self.index!r}")
+
+
+def prefixes_overlap(a: str, b: str) -> bool:
+    """Whether one path prefix contains the other, on whole segments."""
+    a, b = a.rstrip("/"), b.rstrip("/")
+    return bool(a) and bool(b) and (a == b or a.startswith(b + "/") or b.startswith(a + "/"))
diff --git a/framework/hosting/simple_module_hosting/_phase_helpers.py b/framework/hosting/simple_module_hosting/_phase_helpers.py
index 06371f87d..06c7f66f1 100644
--- a/framework/hosting/simple_module_hosting/_phase_helpers.py
+++ b/framework/hosting/simple_module_hosting/_phase_helpers.py
@@ -35,6 +35,7 @@
 from simple_module_hosting._inertia_cache import InertiaCacheMiddleware
 from simple_module_hosting._module_routes import wire_module_routes
 from simple_module_hosting._rate_limit import RateLimitMiddleware
+from simple_module_hosting._spa_mount import mount_spa_mounts
 from simple_module_hosting.i18n_middleware import LocaleMiddleware
 from simple_module_hosting.maintenance import MaintenanceMiddleware
 from simple_module_hosting.middleware import (
@@ -271,6 +272,7 @@ def mount_module_static_dirs(app: FastAPI, modules: list) -> None:
                 StaticFiles(directory=directory_path),
                 name=f"static:{mod.meta.name}",
             )
+    mount_spa_mounts(app, modules)
 
 
 __all__ = ["wire_module_routes"]
diff --git a/framework/hosting/simple_module_hosting/_spa_mount.py b/framework/hosting/simple_module_hosting/_spa_mount.py
new file mode 100644
index 000000000..698f50a05
--- /dev/null
+++ b/framework/hosting/simple_module_hosting/_spa_mount.py
@@ -0,0 +1,126 @@
+"""Serve legacy client-routed SPAs under a URL prefix (GH #541).
+
+The mount is a ``StaticFiles`` subclass with one addition: a request for a path
+that is not a file and *looks like a page* (no extension, client accepts HTML)
+is answered with the SPA's ``index.html`` so its router can take over. A missing
+asset (``/legacy/missing.js``) stays a 404 — answering it with HTML would make
+the browser fail on a script it cannot parse and hide the real problem.
+
+Nothing here builds a filesystem path from the request except through
+``StaticFiles`` itself (which refuses traversal); the fallback serves the one
+configured index name and never the requested path.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+
+from fastapi import FastAPI
+from fastapi.staticfiles import StaticFiles
+from simple_module_core.diagnostics._spa_mount import check_spa_mount_overlaps
+from simple_module_core.spa_mount import SPA_AUTH_PUBLIC, SpaMount
+from starlette.datastructures import Headers
+from starlette.exceptions import HTTPException
+from starlette.responses import Response
+from starlette.types import Scope
+
+from simple_module_hosting.static_files import IMMUTABLE_CACHE_CONTROL
+
+logger = logging.getLogger(__name__)
+
+_NOT_FOUND = 404
+_OK = 200
+_SAFE_METHODS = ("GET", "HEAD")
+_NO_CACHE = "no-cache"
+_CACHE_CONTROL = "Cache-Control"
+# Vite/webpack content-hashed file: `index-3f9a8c21.js`, `chunk.AbC123xy.css`.
+_HASHED_FILE = re.compile(r"[-.][A-Za-z0-9_]{8,}\.[A-Za-z0-9]+$")
+_LOOKS_LIKE_FILE = re.compile(r"\.[A-Za-z0-9]+$")
+
+
+class SpaMountError(RuntimeError):
+    """A SPA mount cannot be served; raised at boot so it never half-works."""
+
+
+class SpaStaticFiles(StaticFiles):
+    """``StaticFiles`` plus the ``index.html`` deep-link fallback."""
+
+    def __init__(self, *, directory, index: str) -> None:
+        super().__init__(directory=directory)
+        self._index = index
+
+    async def get_response(self, path: str, scope: Scope) -> Response:
+        if scope["method"] not in _SAFE_METHODS:
+            raise HTTPException(status_code=405)
+        segments = path.replace("\\", "/").split("/")
+        if ".." in segments or "\x00" in path:
+            raise HTTPException(status_code=_NOT_FOUND)
+        if path in ("", ".", self._index):
+            return await self._index_response(scope)
+        try:
+            response = await super().get_response(path, scope)
+        except HTTPException as exc:
+            if exc.status_code != _NOT_FOUND or not _is_page_request(path, scope):
+                raise
+            return await self._index_response(scope)
+        if response.status_code == _OK and _HASHED_FILE.search(segments[-1]):
+            response.headers[_CACHE_CONTROL] = IMMUTABLE_CACHE_CONTROL
+        return response
+
+    async def _index_response(self, scope: Scope) -> Response:
+        response = await super().get_response(self._index, scope)
+        # The shell references hashed bundles, so it must revalidate on each visit.
+        response.headers[_CACHE_CONTROL] = _NO_CACHE
+        return response
+
+
+def _is_page_request(path: str, scope: Scope) -> bool:
+    if _LOOKS_LIKE_FILE.search(path.rsplit("/", 1)[-1]):
+        return False
+    return "text/html" in Headers(scope=scope).get("accept", "").lower()
+
+
+def mount_spa_mounts(app: FastAPI, modules: list) -> None:
+    """Mount every module's SPAs, exempt the public ones from auth, publish prefixes."""
+    problems = check_spa_mount_overlaps(modules)
+    if problems:
+        raise SpaMountError("\n".join(str(p) for p in problems))
+
+    prefixes: list[str] = []
+    registry = getattr(app.state, "public_routes", None)
+    for mod in modules:
+        for mount in mod.spa_mounts():
+            if not _mount(app, mod.meta.name, mount, registry):
+                continue
+            prefixes.append(mount.prefix)
+    app.state.spa_prefixes = tuple(prefixes)
+
+
+def _mount(app: FastAPI, module_name: str, mount: SpaMount, registry) -> bool:
+    if not (mount.dist_dir / mount.index).is_file():
+        logger.warning(
+            "Module '%s' declared SPA mount %s but %s/%s does not exist (not built?)",
+            module_name,
+            mount.prefix,
+            mount.dist_dir,
+            mount.index,
+        )
+        return False
+    app.mount(
+        mount.prefix,
+        SpaStaticFiles(directory=mount.dist_dir, index=mount.index),
+        name=f"spa:{module_name}:{mount.prefix}",
+    )
+    if mount.auth == SPA_AUTH_PUBLIC and registry is not None:
+        registry.add_exact(mount.prefix, methods=_SAFE_METHODS)
+        registry.add_prefix(f"{mount.prefix}/", methods=_SAFE_METHODS)
+    return True
+
+
+def native_prefixes(app: FastAPI) -> list[str]:
+    """Prefixes the client must not intercept: mounted SPAs + the host setting."""
+    host = getattr(app.state, "host", None)
+    configured = getattr(getattr(host, "settings", None), "native_link_prefixes", None) or []
+    spa = [f"{prefix}/" for prefix in getattr(app.state, "spa_prefixes", ())]
+    return sorted({*spa, *configured})
diff --git a/framework/hosting/simple_module_hosting/host_settings.py b/framework/hosting/simple_module_hosting/host_settings.py
index 0fdddc47b..30e8b7a66 100644
--- a/framework/hosting/simple_module_hosting/host_settings.py
+++ b/framework/hosting/simple_module_hosting/host_settings.py
@@ -159,6 +159,11 @@ class HostSettings(BaseSettings):
     ``register_public_routes`` hook, which is method-aware.
     """
 
+    native_link_prefixes: list[str] = Field(default=[], json_schema_extra={"group": "Routing"})
+    """URL prefixes whose links the Inertia client must leave to the browser
+    (a full navigation), e.g. ``["/docs/"]``. Added to the prefixes of mounted
+    legacy SPAs and sent as the ``nativePrefixes`` shared prop. Read per request."""
+
     max_request_body_bytes: int = Field(default=10 * 1024 * 1024, json_schema_extra=_RESTART_GUARD)
     """Global request-body ceiling in bytes; larger bodies get a 413 before any
     route runs. ``0`` disables the guard. Modules override it per path with
@@ -195,6 +200,14 @@ def _check_rate(cls, value: str) -> str:
         parse_rate(value)  # raises RateLimitError (a ValueError) on a typo
         return value.strip()
 
+    @field_validator("native_link_prefixes", mode="after")
+    @classmethod
+    def _check_native_prefixes(cls, value: list[str]) -> list[str]:
+        for prefix in value:
+            if not prefix.startswith("/"):
+                raise ValueError(f"native_link_prefixes entry {prefix!r} must start with '/'")
+        return [prefix.strip() for prefix in value]
+
     @field_validator("max_request_body_bytes", mode="after")
     @classmethod
     def _check_body_bytes(cls, value: int) -> int:
diff --git a/framework/hosting/simple_module_hosting/middleware.py b/framework/hosting/simple_module_hosting/middleware.py
index 9632aafd4..ecfde56cb 100644
--- a/framework/hosting/simple_module_hosting/middleware.py
+++ b/framework/hosting/simple_module_hosting/middleware.py
@@ -28,6 +28,7 @@
     CorrelationIdMiddleware,
     RequestLoggingMiddleware,
 )
+from simple_module_hosting._spa_mount import native_prefixes
 from simple_module_hosting._tenant import (
     TENANT_HEADER,
     TenantMiddleware,
@@ -266,6 +267,7 @@ async def _shared(self, request: Request, scope: Scope, user: Any, resolved: set
                 translate=build_menu_translator(request),
             ),
             "i18n": i18n_block,
+            "nativePrefixes": native_prefixes(scope["app"]),
         }
 
         # Merge module-registered shared-prop providers (e.g. branding) — read off
diff --git a/framework/hosting/tests/test_spa_mounts_541.py b/framework/hosting/tests/test_spa_mounts_541.py
new file mode 100644
index 000000000..e31756de7
--- /dev/null
+++ b/framework/hosting/tests/test_spa_mounts_541.py
@@ -0,0 +1,182 @@
+"""Legacy SPA mounts (GH #541): deep-link fallback, auth, overlap diagnostic."""
+
+from __future__ import annotations
+
+import json
+import re
+
+import pytest
+from simple_module_core import ModuleBase, ModuleMeta
+from simple_module_core.diagnostics._spa_mount import check_spa_mount_overlaps
+from simple_module_core.spa_mount import SpaMount
+from simple_module_hosting import app_builder
+
+_HTML = {"Accept": "text/html"}
+_INDEX = "<html><body>legacy spa</body></html>"
+
+
+def _module(mounts: list[SpaMount], name: str = "LegacyFake") -> ModuleBase:
+    class FakeSpaModule(ModuleBase):
+        meta = ModuleMeta(name=name)
+
+        def spa_mounts(self):
+            return mounts
+
+    return FakeSpaModule()
+
+
+@pytest.fixture
+def dist(tmp_path):
+    root = tmp_path / "dist"
+    (root / "assets").mkdir(parents=True)
+    (root / "index.html").write_text(_INDEX, encoding="utf-8")
+    (root / "assets" / "index-3f9a8c21b.js").write_text("console.log(1)", encoding="utf-8")
+    (tmp_path / "secret.txt").write_text("TOPSECRET-CONTENT", encoding="utf-8")
+    return root
+
+
+@pytest.fixture(autouse=True)
+def _mount_legacy(monkeypatch, dist, tmp_path):
+    public_dist = tmp_path / "public_dist"
+    public_dist.mkdir()
+    (public_dist / "index.html").write_text("<html>open</html>", encoding="utf-8")
+    real = app_builder.discover_modules
+
+    def fake(enabled=None, *, strict=False):
+        extra = _module(
+            [
+                SpaMount("/legacy", dist),
+                SpaMount("/openspa/", public_dist, auth="public"),
+            ]
+        )
+        return [*real(enabled=enabled, strict=strict), extra]
+
+    monkeypatch.setattr(app_builder, "discover_modules", fake)
+
+
+async def test_deep_link_serves_index(authenticated_client):
+    r = await authenticated_client.get("/legacy/a/b/c", headers=_HTML)
+    assert r.status_code == 200
+    assert "legacy spa" in r.text
+    assert r.headers["cache-control"] == "no-cache"
+
+
+async def test_root_serves_index_and_head_works(authenticated_client):
+    assert (await authenticated_client.get("/legacy/", headers=_HTML)).status_code == 200
+    assert (await authenticated_client.head("/legacy/a/b", headers=_HTML)).status_code == 200
+
+
+async def test_missing_asset_is_404_not_html(authenticated_client):
+    r = await authenticated_client.get("/legacy/missing.js", headers=_HTML)
+    assert r.status_code == 404
+    assert "legacy spa" not in r.text
+
+
+async def test_extensionless_without_html_accept_is_404(authenticated_client):
+    r = await authenticated_client.get("/legacy/a/b", headers={"Accept": "application/json"})
+    assert r.status_code == 404
+
+
+async def test_hashed_asset_is_immutable(authenticated_client):
+    r = await authenticated_client.get("/legacy/assets/index-3f9a8c21b.js")
+    assert r.status_code == 200
+    assert "immutable" in r.headers["cache-control"]
+
+
+@pytest.mark.parametrize(
+    "path",
+    [
+        "/legacy/../secret.txt",
+        "/legacy/%2e%2e/secret.txt",
+        "/legacy/..%2fsecret",
+        "/legacy/%2e%2e/x",
+    ],
+)
+async def test_traversal_is_refused(authenticated_client, path):
+    r = await authenticated_client.get(path, headers=_HTML)
+    assert "TOPSECRET-CONTENT" not in r.text
+    assert "legacy spa" not in r.text
+
+
+async def test_write_methods_refused(authenticated_client):
+    r = await authenticated_client.post("/legacy/a")
+    assert r.status_code in (404, 405)
+
+
+async def test_required_mount_redirects_anonymous_to_login(client):
+    r = await client.get("/legacy/a/b/c", headers=_HTML)
+    assert r.status_code in (302, 303, 307)
+    assert "login" in r.headers["location"]
+
+
+async def test_public_mount_is_reachable_anonymously(client):
+    r = await client.get("/openspa/x/y", headers=_HTML)
+    assert r.status_code == 200
+    assert "open" in r.text
+
+
+async def test_public_mount_post_is_still_gated(client):
+    r = await client.post("/openspa/x")
+    assert r.status_code != 200
+
+
+async def test_native_prefixes_shared_prop(client):
+    r = await client.get("/users/login", headers=_HTML)
+    found = re.search(
+        r'<script data-page="[^"]*" type="application/json">(.*?)</script>', r.text, re.DOTALL
+    )
+    assert found is not None
+    page = json.loads(found.group(1))
+    props = page["props"]
+    assert "/legacy/" in props.get("nativePrefixes", [])
+
+
+def test_overlap_with_router_prefix_is_an_error(tmp_path):
+    clash = _module([SpaMount("/api/legacy", tmp_path)], name="Clash")
+    codes = [d.code for d in check_spa_mount_overlaps([clash])]
+    assert codes == ["SM031"]
+
+
+def test_overlap_between_two_mounts_is_an_error(tmp_path):
+    a = _module([SpaMount("/legacy", tmp_path)], name="A")
+    b = _module([SpaMount("/legacy/inner", tmp_path)], name="B")
+    assert any(d.code == "SM031" for d in check_spa_mount_overlaps([a, b]))
+
+
+def test_sibling_prefix_is_not_an_overlap(tmp_path):
+    mod = _module([SpaMount("/legacy", tmp_path), SpaMount("/legacy2", tmp_path)])
+    assert check_spa_mount_overlaps([mod]) == []
+
+
+async def test_overlap_fails_boot(settings, monkeypatch, tmp_path):
+    from simple_module_hosting._spa_mount import SpaMountError
+
+    (tmp_path / "index.html").write_text("x", encoding="utf-8")
+    real = app_builder.discover_modules
+    bad = _module([SpaMount("/admin/legacy", tmp_path)], name="Bad")
+    monkeypatch.setattr(
+        app_builder,
+        "discover_modules",
+        lambda enabled=None, *, strict=False: [*real(enabled=enabled, strict=strict), bad],
+    )
+    with pytest.raises(SpaMountError, match="SM031"):
+        app_builder.create_app(settings)
+
+
+def test_invalid_prefix_and_auth_rejected(tmp_path):
+    with pytest.raises(ValueError):
+        SpaMount("legacy", tmp_path)
+    with pytest.raises(ValueError):
+        SpaMount("/legacy", tmp_path, auth="nope")
+
+
+async def test_traversal_segment_refused_by_the_mount_itself(dist):
+    from simple_module_hosting._spa_mount import SpaStaticFiles
+    from starlette.exceptions import HTTPException
+
+    files = SpaStaticFiles(directory=dist, index="index.html")
+    scope = {"method": "GET", "headers": [(b"accept", b"text/html")]}
+    for path in ("../secret", "a/../../secret", "a\\..\\secret"):
+        with pytest.raises(HTTPException) as exc:
+            await files.get_response(path, scope)
+        assert exc.value.status_code == 404
diff --git a/host/client_app/app.tsx b/host/client_app/app.tsx
index f3f147907..b362e7783 100644
--- a/host/client_app/app.tsx
+++ b/host/client_app/app.tsx
@@ -2,7 +2,11 @@ import { createInertiaApp, router } from '@inertiajs/react';
 import { ErrorBoundary } from '@simple-module-py/ui/components/ErrorBoundary';
 import { OfflineBanner } from '@simple-module-py/ui/components/OfflineBanner';
 import { formatTitle, setTitleAppName } from '@simple-module-py/ui/lib/app-title';
-import { startSpaLinkInterception } from '@simple-module-py/ui/lib/spa-links';
+import {
+  isExcluded,
+  readNativePrefixes,
+  startSpaLinkInterception,
+} from '@simple-module-py/ui/lib/spa-links';
 import { initTheme } from '@simple-module-py/ui/lib/theme';
 import { useEffect, useRef } from 'react';
 import { createRoot } from 'react-dom/client';
@@ -39,11 +43,19 @@ createInertiaApp({
         // Authored content renders author-entered URLs as plain <a href>, which
         // the browser follows with a full document load — a blank page until
         // this client-rendered app boots again. Route them through Inertia.
-        const stopLinks = startSpaLinkInterception();
+        // Legacy SPA mounts and `native_link_prefixes` stay full navigations.
+        let nativePrefixes = readNativePrefixes(props.initialPage.props);
+        const stopPrefixes = router.on('navigate', (event) => {
+          nativePrefixes = readNativePrefixes(event.detail.page.props);
+        });
+        const stopLinks = startSpaLinkInterception({
+          exclude: (url) => isExcluded(url, nativePrefixes),
+        });
         return () => {
           stopReset();
           stopI18n();
           stopLinks();
+          stopPrefixes();
         };
       }, []);
 
diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts
index 7716a407c..ad36eff72 100644
--- a/packages/ui/src/index.ts
+++ b/packages/ui/src/index.ts
@@ -37,7 +37,13 @@ export {
   relativeUntil,
   STALE_AFTER_MS,
 } from './lib/relative-time';
-export { shouldInterceptNavigation, startSpaLinkInterception } from './lib/spa-links';
+export {
+  isExcluded,
+  readNativePrefixes,
+  type SpaLinkExclude,
+  shouldInterceptNavigation,
+  startSpaLinkInterception,
+} from './lib/spa-links';
 export {
   applyTheme,
   initTheme,
diff --git a/packages/ui/src/lib/spa-links.test.ts b/packages/ui/src/lib/spa-links.test.ts
index 735501c9f..9d0cf8046 100644
--- a/packages/ui/src/lib/spa-links.test.ts
+++ b/packages/ui/src/lib/spa-links.test.ts
@@ -1,6 +1,10 @@
 import { router } from '@inertiajs/react';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { shouldInterceptNavigation, startSpaLinkInterception } from './spa-links';
+import {
+  readNativePrefixes,
+  shouldInterceptNavigation,
+  startSpaLinkInterception,
+} from './spa-links';
 
 /**
  * The rule has to be conservative in both directions. Taking over a link
@@ -182,3 +186,45 @@ describe('startSpaLinkInterception', () => {
     stop = () => undefined; // afterEach must not tear down twice
   });
 });
+
+describe('exclude', () => {
+  it('leaves an excluded prefix to the browser, deep paths included', () => {
+    const el = anchor('<a href="/legacy/a/b/c">Legacy</a>');
+    expect(shouldInterceptNavigation(el, HERE, ['/legacy/'])).toBe(false);
+    expect(shouldInterceptNavigation(el, HERE)).toBe(true);
+  });
+
+  it('does not exclude a sibling that merely shares the leading characters', () => {
+    expect(shouldInterceptNavigation(anchor('<a href="/legacy2/x">x</a>'), HERE, '/legacy/')).toBe(
+      true,
+    );
+  });
+
+  it('accepts a predicate', () => {
+    const el = anchor('<a href="/p/outputs">o</a>');
+    expect(shouldInterceptNavigation(el, HERE, (url) => url.pathname.startsWith('/p/'))).toBe(
+      false,
+    );
+  });
+
+  it('does not take over a click on an excluded link', () => {
+    window.history.pushState({}, '', '/p/who-we-are');
+    const visit = vi.spyOn(router, 'visit').mockImplementation(() => undefined);
+    const stop = startSpaLinkInterception({ exclude: ['/legacy/'] });
+    const el = anchor('<a href="/legacy/a">Legacy</a>');
+    const event = new MouseEvent('click', { bubbles: true, cancelable: true, button: 0 });
+    window.addEventListener('click', (e) => e.preventDefault(), { once: true });
+    el.dispatchEvent(event);
+    expect(visit).not.toHaveBeenCalled();
+    stop();
+    visit.mockRestore();
+  });
+});
+
+describe('readNativePrefixes', () => {
+  it('reads the shared prop and tolerates its absence', () => {
+    expect(readNativePrefixes({ nativePrefixes: ['/legacy/'] })).toEqual(['/legacy/']);
+    expect(readNativePrefixes({})).toEqual([]);
+    expect(readNativePrefixes(null)).toEqual([]);
+  });
+});
diff --git a/packages/ui/src/lib/spa-links.ts b/packages/ui/src/lib/spa-links.ts
index 36b942ef7..d6a1c0175 100644
--- a/packages/ui/src/lib/spa-links.ts
+++ b/packages/ui/src/lib/spa-links.ts
@@ -37,6 +37,30 @@ const LOOKS_LIKE_A_FILE = /\.[a-z0-9]+$/i;
  */
 const EDITOR_SURFACE = '[data-puck-preview],[data-puck-component]';
 
+/**
+ * Which URLs to leave to the browser, beyond the built-in rules. A prefix
+ * (`'/legacy/'`, matched against the pathname), a list of them, or a predicate.
+ * The server publishes the prefixes of mounted legacy SPAs and the
+ * `native_link_prefixes` host setting as the `nativePrefixes` shared prop.
+ */
+export type SpaLinkExclude = string | string[] | ((url: URL) => boolean);
+
+/** Whether *url* falls under an `exclude` rule. */
+export function isExcluded(url: URL, exclude: SpaLinkExclude | undefined): boolean {
+  if (!exclude) return false;
+  if (typeof exclude === 'function') return exclude(url);
+  const prefixes = typeof exclude === 'string' ? [exclude] : exclude;
+  return prefixes.some(
+    (prefix) => url.pathname === prefix.replace(/\/$/, '') || url.pathname.startsWith(prefix),
+  );
+}
+
+/** The `nativePrefixes` shared prop, tolerant of it being absent or malformed. */
+export function readNativePrefixes(props: unknown): string[] {
+  const value = (props as { nativePrefixes?: unknown } | null)?.nativePrefixes;
+  return Array.isArray(value) ? value.filter((p): p is string => typeof p === 'string') : [];
+}
+
 /**
  * Whether the SPA should take over this anchor, given the page it is on.
  *
@@ -49,7 +73,11 @@ const EDITOR_SURFACE = '[data-puck-preview],[data-puck-component]';
  * render turns a working download into an error modal, while missing one only
  * costs the reload this is trying to avoid.
  */
-export function shouldInterceptNavigation(anchor: HTMLAnchorElement, here: URL): boolean {
+export function shouldInterceptNavigation(
+  anchor: HTMLAnchorElement,
+  here: URL,
+  exclude?: SpaLinkExclude,
+): boolean {
   const href = anchor.getAttribute('href');
   if (!href) return false;
 
@@ -72,6 +100,7 @@ export function shouldInterceptNavigation(anchor: HTMLAnchorElement, here: URL):
   // `mailto:`, `tel:`, and anything else the browser owns outright.
   if (url.protocol !== 'http:' && url.protocol !== 'https:') return false;
   if (url.origin !== here.origin) return false;
+  if (isExcluded(url, exclude)) return false;
 
   // Same document: `#`, `#section`, or a link back to the current page. The
   // browser handles all three correctly, and `href="#"` is what a pagebuilder
@@ -105,7 +134,7 @@ function isPlainLeftClick(event: MouseEvent): boolean {
  * Returns a function that removes it again, which is what tests use; an app has
  * no reason to.
  */
-export function startSpaLinkInterception(): () => void {
+export function startSpaLinkInterception(options: { exclude?: SpaLinkExclude } = {}): () => void {
   // Set when a click is taken over, cleared when the visit comes back as a real
   // Inertia response. If it does not, the URL was not a page after all and the
   // browser should have had it — hand it back rather than showing Inertia's
@@ -136,7 +165,7 @@ export function startSpaLinkInterception(): () => void {
     if (!(anchor instanceof HTMLAnchorElement)) return;
 
     const here = new URL(window.location.href);
-    if (!shouldInterceptNavigation(anchor, here)) return;
+    if (!shouldInterceptNavigation(anchor, here, options.exclude)) return;
 
     const url = new URL(anchor.getAttribute('href') as string, here.href).href;
     event.preventDefault();

From ef29f9dd50bc7f6ad62e00bdcc202f712c5b4441 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Thu, 22 Oct 2026 09:24:18 +0200
Subject: [PATCH 07/21] fix(diagnostics): SPA mount overlap is SM032 (SM031 is
 the unguarded-API check from #534)

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 CHANGELOG.md                                                | 2 +-
 docs/framework/spa-mounts.md                                | 2 +-
 docs/reference/diagnostic-codes.md                          | 2 +-
 framework/core/simple_module_core/diagnostics/_spa_mount.py | 6 +++---
 framework/hosting/tests/test_spa_mounts_541.py              | 6 +++---
 5 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4c3a731eb..b1a9653f1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,7 +17,7 @@ All notable changes to this project are documented in this file. The format is b
 - `host/client_app` no longer re-declares `@simple-module-py/ui`'s runtime dependencies, nor `@base-ui/react`, `@radix-ui/react-slot`, `autoprefixer` or `postcss` (nothing loaded them) (#521).
 
 ### Added
-- Legacy SPA mounts (#541): `ModuleBase.spa_mounts()` returns `SpaMount(prefix, dist_dir, index="index.html", auth="required"|"public")` entries served with an `index.html` deep-link fallback (extension-less paths accepting HTML only; a missing asset stays a 404; hashed assets `immutable`; GET/HEAD only). `auth="public"` exempts GET/HEAD from `AuthMiddleware`. A prefix overlapping a router, static mount or another SPA fails boot (`SM031`). The Inertia client leaves these prefixes to the browser: `startSpaLinkInterception({ exclude })` plus the framework shared prop `nativePrefixes`, which also carries the new DB-backed host setting `native_link_prefixes` (no migration).
+- Legacy SPA mounts (#541): `ModuleBase.spa_mounts()` returns `SpaMount(prefix, dist_dir, index="index.html", auth="required"|"public")` entries served with an `index.html` deep-link fallback (extension-less paths accepting HTML only; a missing asset stays a 404; hashed assets `immutable`; GET/HEAD only). `auth="public"` exempts GET/HEAD from `AuthMiddleware`. A prefix overlapping a router, static mount or another SPA fails boot (`SM032`). The Inertia client leaves these prefixes to the browser: `startSpaLinkInterception({ exclude })` plus the framework shared prop `nativePrefixes`, which also carries the new DB-backed host setting `native_link_prefixes` (no migration).
 - Release process (#510): `release.yml` runs the whole PR suite (`pr.yml` via
   `workflow_call`) against the dispatched commit and `build` needs it, so nothing
   is built or published from a red commit. The duplicated bump + lockfile steps
diff --git a/docs/framework/spa-mounts.md b/docs/framework/spa-mounts.md
index ea726fc19..1330d3242 100644
--- a/docs/framework/spa-mounts.md
+++ b/docs/framework/spa-mounts.md
@@ -45,7 +45,7 @@ CSP applies as for any response; whitelist external origins the SPA needs with
 
 A prefix that overlaps a module's route/view prefix, a `static_mounts()` prefix,
 a framework path or another SPA mount fails boot with
-[`SM031`](/reference/diagnostic-codes), in every environment.
+[`SM032`](/reference/diagnostic-codes), in every environment.
 
 ## Inertia link interception
 
diff --git a/docs/reference/diagnostic-codes.md b/docs/reference/diagnostic-codes.md
index a1ad00528..89f155043 100644
--- a/docs/reference/diagnostic-codes.md
+++ b/docs/reference/diagnostic-codes.md
@@ -39,7 +39,7 @@ The framework runs a set of static checks over installed modules at app boot. Th
 | `SM028` | WARNING | A module's `tasks.py` imports `torch`, `tensorflow`, `ultralytics`, `osgeo`, `rasterio`, `cv2` or `sklearn` at module level, so every process that loads the module's tasks (web, each worker, beat) pays for it and a queue-restricted worker cannot avoid it. | Import the package inside the task function. See [background_tasks](/modules/background_tasks#running-a-worker-for-a-subset-of-modules). |
 | `SM029` | INFO | A module overrides `db_extensions()` (Postgres extensions such as `ltree`) and the configured database is SQLite, which has none. `ensure_db_extensions` raises `UnsupportedDatabaseError` when migrations run. | Point `SM_DATABASE_URL` at PostgreSQL. See [Postgres extensions and column types](/database/extensions). |
 | `SM030` | WARNING at a dev boot; ERROR in `make doctor` | A module's `depends_on` names a module that is not loaded (not installed, left out of `SM_MODULES_ENABLED`, or dropped because another auth provider was selected — `keycloak` drops `Users`). Outside development the boot raises `MissingDependencyError` listing every pair. | Install and enable the dependency, or leave the dependent module out. A relationship that is only about order belongs in `optional_depends_on`. See [Discovery](/framework/discovery#modulemeta). |
-| `SM031` | ERROR (fails boot in every environment) | A `ModuleBase.spa_mounts()` prefix overlaps a module's `route_prefix`/`view_prefix`/`admin_view_prefix`, a `static_mounts()` prefix, a framework path (`/api`, `/admin`, `/setup`, `/i18n`, `/health`, `/static`, `/modules`) or another SPA mount. The mount would shadow, or be shadowed by, that router. | Pick a prefix nothing else uses. See [Legacy SPA mounts](/framework/spa-mounts). |
+| `SM032` | ERROR (fails boot in every environment) | A `ModuleBase.spa_mounts()` prefix overlaps a module's `route_prefix`/`view_prefix`/`admin_view_prefix`, a `static_mounts()` prefix, a framework path (`/api`, `/admin`, `/setup`, `/i18n`, `/health`, `/static`, `/modules`) or another SPA mount. The mount would shadow, or be shadowed by, that router. | Pick a prefix nothing else uses. See [Legacy SPA mounts](/framework/spa-mounts). |
 
 `SM022`/`SM023` are the two halves of the same invariant: a module's optional [`theme.css` is imported unlayered and `styles.css` into `layer(components)`](/module-authoring#styling), and CSS put in the wrong one silently does nothing (or silently wins everything).
 
diff --git a/framework/core/simple_module_core/diagnostics/_spa_mount.py b/framework/core/simple_module_core/diagnostics/_spa_mount.py
index 32c34bc3a..8ae818cd1 100644
--- a/framework/core/simple_module_core/diagnostics/_spa_mount.py
+++ b/framework/core/simple_module_core/diagnostics/_spa_mount.py
@@ -1,15 +1,15 @@
-"""SM031: a legacy SPA mount whose prefix overlaps a router, static mount or other SPA."""
+"""SM032: a legacy SPA mount whose prefix overlaps a router, static mount or other SPA."""
 
 from __future__ import annotations
 
 from simple_module_core.diagnostics._types import Diagnostic, DiagnosticLevel
 from simple_module_core.spa_mount import RESERVED_PREFIXES, prefixes_overlap
 
-SPA_MOUNT_OVERLAP_CODE = "SM031"
+SPA_MOUNT_OVERLAP_CODE = "SM032"
 
 
 def check_spa_mount_overlaps(modules: list) -> list[Diagnostic]:
-    """SM031: a SPA mount prefix overlaps a router prefix or another mount."""
+    """SM032: a SPA mount prefix overlaps a router prefix or another mount."""
     owners: list[tuple[str, str]] = [(p, "framework") for p in RESERVED_PREFIXES]
     for mod in modules:
         for prefix in (mod.meta.route_prefix, mod.meta.view_prefix, mod.meta.admin_view_prefix):
diff --git a/framework/hosting/tests/test_spa_mounts_541.py b/framework/hosting/tests/test_spa_mounts_541.py
index e31756de7..2cb2844b9 100644
--- a/framework/hosting/tests/test_spa_mounts_541.py
+++ b/framework/hosting/tests/test_spa_mounts_541.py
@@ -134,13 +134,13 @@ async def test_native_prefixes_shared_prop(client):
 def test_overlap_with_router_prefix_is_an_error(tmp_path):
     clash = _module([SpaMount("/api/legacy", tmp_path)], name="Clash")
     codes = [d.code for d in check_spa_mount_overlaps([clash])]
-    assert codes == ["SM031"]
+    assert codes == ["SM032"]
 
 
 def test_overlap_between_two_mounts_is_an_error(tmp_path):
     a = _module([SpaMount("/legacy", tmp_path)], name="A")
     b = _module([SpaMount("/legacy/inner", tmp_path)], name="B")
-    assert any(d.code == "SM031" for d in check_spa_mount_overlaps([a, b]))
+    assert any(d.code == "SM032" for d in check_spa_mount_overlaps([a, b]))
 
 
 def test_sibling_prefix_is_not_an_overlap(tmp_path):
@@ -159,7 +159,7 @@ async def test_overlap_fails_boot(settings, monkeypatch, tmp_path):
         "discover_modules",
         lambda enabled=None, *, strict=False: [*real(enabled=enabled, strict=strict), bad],
     )
-    with pytest.raises(SpaMountError, match="SM031"):
+    with pytest.raises(SpaMountError, match="SM032"):
         app_builder.create_app(settings)
 
 

From b38734fb3ad6973d5fdf4eb413a4fa63ec0524e4 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Thu, 22 Oct 2026 09:25:00 +0200
Subject: [PATCH 08/21] fix(db): OwnedResourcePolicy.can compares owners
 exactly as filter does (#526)

can() lower-cased both sides while the SQL predicate compared the coerced
id; on a string owner column a case-variant id passed one and not the
other. Both now go through the same _coerce + ==.

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 .../db/simple_module_db/resource_policy.py    | 10 ++-
 .../tests/test_resource_policy_parity.py      | 68 +++++++++++++++++++
 2 files changed, 76 insertions(+), 2 deletions(-)
 create mode 100644 framework/hosting/tests/test_resource_policy_parity.py

diff --git a/framework/db/simple_module_db/resource_policy.py b/framework/db/simple_module_db/resource_policy.py
index b3b52be93..b6fe7c673 100644
--- a/framework/db/simple_module_db/resource_policy.py
+++ b/framework/db/simple_module_db/resource_policy.py
@@ -88,6 +88,13 @@ def predicate(self, principal: ResourcePrincipal, action: str) -> ColumnElement[
             clauses.append(self.visibility_col == self.public_value)
         return or_(*clauses) if clauses else false()
 
+    def _owns(self, owner: Any, principal: ResourcePrincipal) -> bool:
+        """The same comparison :meth:`predicate` sends to SQL, in Python."""
+        try:
+            return owner == _coerce(self.owner_col, principal.user_id or "")
+        except ValueError:
+            return False
+
     def filter(self, principal: ResourcePrincipal, action: str, stmt: Any) -> Any:
         clause = self.predicate(principal, action)
         return stmt if clause is None else stmt.where(clause)
@@ -96,8 +103,7 @@ def can(self, principal: ResourcePrincipal, action: str, obj: Any) -> bool:
         if principal.has(self.bypass_perm):
             return True
         owner = getattr(obj, self.owner_col.key, None)
-        uid = principal.user_id
-        if uid is not None and owner is not None and str(owner).lower() == uid.lower():
+        if principal.user_id is not None and owner is not None and self._owns(owner, principal):
             return True
         if self.visibility_col is not None and action == ACTION_VIEW:
             return getattr(obj, self.visibility_col.key, None) == self.public_value
diff --git a/framework/hosting/tests/test_resource_policy_parity.py b/framework/hosting/tests/test_resource_policy_parity.py
new file mode 100644
index 000000000..f8bc603a6
--- /dev/null
+++ b/framework/hosting/tests/test_resource_policy_parity.py
@@ -0,0 +1,68 @@
+"""``can`` and ``filter`` agree on case-variant owner ids (GH #526 review).
+
+A detail check that admits a row the list hides (or the reverse) is an
+authorisation differential, so both sides must compare the same way.
+"""
+
+from __future__ import annotations
+
+import uuid
+
+import pytest
+from _resacc_models import ResaccDoc
+from simple_module_core.resources import ACTION_EDIT, ResourcePrincipal
+from simple_module_db.resource_policy import OwnedResourcePolicy
+from sqlmodel import Field, SQLModel, select
+
+
+class ResaccNote(SQLModel, table=True):
+    __tablename__ = "resacc_test_note"
+    __table_args__ = {"extend_existing": True}
+    id: int | None = Field(default=None, primary_key=True)
+    owner: str
+
+
+STR_POLICY = OwnedResourcePolicy(ResaccNote.owner, bypass_perm=None)
+UUID_POLICY = OwnedResourcePolicy(ResaccDoc.owner_id, bypass_perm=None)
+
+
+async def _visible(session, policy, who, model) -> bool:
+    stmt = policy.filter(who, ACTION_EDIT, select(model))
+    return (await session.execute(stmt)).scalars().first() is not None
+
+
+@pytest.mark.parametrize("asker", ["Alice", "alice", "ALICE"])
+async def test_string_owner_case_variants_agree(db_session, asker):
+    conn = await db_session.connection()
+    await conn.run_sync(lambda c: ResaccNote.__table__.create(c, checkfirst=True))
+    note = ResaccNote(owner="Alice")
+    db_session.add(note)
+    await db_session.flush()
+    who = ResourcePrincipal(user_id=asker)
+    in_sql = await _visible(db_session, STR_POLICY, who, ResaccNote)
+    assert STR_POLICY.can(who, ACTION_EDIT, note) is in_sql
+    assert in_sql is (asker == "Alice")
+
+
+@pytest.mark.parametrize("upper", [False, True])
+async def test_uuid_owner_case_variants_agree(db_session, upper):
+    conn = await db_session.connection()
+    await conn.run_sync(lambda c: ResaccDoc.__table__.create(c, checkfirst=True))
+    owner = uuid.UUID("00000000-0000-0000-0000-0000000000ff")
+    doc = ResaccDoc(owner_id=owner)
+    db_session.add(doc)
+    await db_session.flush()
+    who = ResourcePrincipal(user_id=str(owner).upper() if upper else str(owner))
+    assert await _visible(db_session, UUID_POLICY, who, ResaccDoc)
+    assert UUID_POLICY.can(who, ACTION_EDIT, doc)
+
+
+async def test_malformed_id_owns_nothing_on_uuid_column(db_session):
+    conn = await db_session.connection()
+    await conn.run_sync(lambda c: ResaccDoc.__table__.create(c, checkfirst=True))
+    doc = ResaccDoc(owner_id=uuid.uuid4())
+    db_session.add(doc)
+    await db_session.flush()
+    who = ResourcePrincipal(user_id="not-a-uuid")
+    assert not await _visible(db_session, UUID_POLICY, who, ResaccDoc)
+    assert not UUID_POLICY.can(who, ACTION_EDIT, doc)

From ccdeae36bcaa1c2f27ea13ab4a1fcb2582f5e71b Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Thu, 22 Oct 2026 09:29:09 +0200
Subject: [PATCH 09/21] fix(spa-mounts): overlap check sees registered routes,
 scoped public exemption, private caching for gated mounts (#541)

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 .../diagnostics/_spa_mount.py                 | 12 ++-
 .../simple_module_hosting/_spa_mount.py       | 57 ++++++++++--
 .../hosting/tests/test_spa_mounts_541.py      | 91 ++++++++++++++++++-
 3 files changed, 147 insertions(+), 13 deletions(-)

diff --git a/framework/core/simple_module_core/diagnostics/_spa_mount.py b/framework/core/simple_module_core/diagnostics/_spa_mount.py
index 8ae818cd1..56ac15cb6 100644
--- a/framework/core/simple_module_core/diagnostics/_spa_mount.py
+++ b/framework/core/simple_module_core/diagnostics/_spa_mount.py
@@ -2,15 +2,23 @@
 
 from __future__ import annotations
 
+from collections.abc import Iterable
+
 from simple_module_core.diagnostics._types import Diagnostic, DiagnosticLevel
 from simple_module_core.spa_mount import RESERVED_PREFIXES, prefixes_overlap
 
 SPA_MOUNT_OVERLAP_CODE = "SM032"
 
 
-def check_spa_mount_overlaps(modules: list) -> list[Diagnostic]:
-    """SM032: a SPA mount prefix overlaps a router prefix or another mount."""
+def check_spa_mount_overlaps(modules: list, route_paths: Iterable[str] = ()) -> list[Diagnostic]:
+    """SM032: a SPA mount prefix overlaps a router prefix, a registered route or another mount.
+
+    ``route_paths`` are the paths actually registered on the app (the host
+    supplies them after wiring); meta prefixes alone miss host routes such as
+    ``/docs`` or ``/openapi.json``.
+    """
     owners: list[tuple[str, str]] = [(p, "framework") for p in RESERVED_PREFIXES]
+    owners.extend((path.split("{", 1)[0].rstrip("/"), "a registered route") for path in route_paths)
     for mod in modules:
         for prefix in (mod.meta.route_prefix, mod.meta.view_prefix, mod.meta.admin_view_prefix):
             if prefix:
diff --git a/framework/hosting/simple_module_hosting/_spa_mount.py b/framework/hosting/simple_module_hosting/_spa_mount.py
index 698f50a05..3178f3a43 100644
--- a/framework/hosting/simple_module_hosting/_spa_mount.py
+++ b/framework/hosting/simple_module_hosting/_spa_mount.py
@@ -35,7 +35,9 @@
 _NO_CACHE = "no-cache"
 _CACHE_CONTROL = "Cache-Control"
 # Vite/webpack content-hashed file: `index-3f9a8c21.js`, `chunk.AbC123xy.css`.
-_HASHED_FILE = re.compile(r"[-.][A-Za-z0-9_]{8,}\.[A-Za-z0-9]+$")
+_HASHED_FILE = re.compile(r"[-.]([A-Za-z0-9_-]{8,})\.[A-Za-z0-9]+$")
+_PRIVATE_IMMUTABLE = "private, max-age=31536000, immutable"
+_PRIVATE_NO_CACHE = "private, no-cache"
 _LOOKS_LIKE_FILE = re.compile(r"\.[A-Za-z0-9]+$")
 
 
@@ -43,12 +45,27 @@ class SpaMountError(RuntimeError):
     """A SPA mount cannot be served; raised at boot so it never half-works."""
 
 
+def looks_hashed(filename: str) -> bool:
+    """Whether *filename* carries a bundler content hash (8+ chars, a digit or mixed case)."""
+    found = _HASHED_FILE.search(filename)
+    if not found:
+        return False
+    token = found.group(1)
+    mixed = token != token.lower() and token != token.upper()
+    return any(c.isdigit() for c in token) or mixed
+
+
 class SpaStaticFiles(StaticFiles):
-    """``StaticFiles`` plus the ``index.html`` deep-link fallback."""
+    """``StaticFiles`` plus the ``index.html`` deep-link fallback.
 
-    def __init__(self, *, directory, index: str) -> None:
+    ``public`` decides shared-cache exposure: only a public mount's responses
+    may be stored by shared caches; a login-gated mount's are ``private``.
+    """
+
+    def __init__(self, *, directory, index: str, public: bool = False) -> None:
         super().__init__(directory=directory)
         self._index = index
+        self._public = public
 
     async def get_response(self, path: str, scope: Scope) -> Response:
         if scope["method"] not in _SAFE_METHODS:
@@ -64,14 +81,16 @@ async def get_response(self, path: str, scope: Scope) -> Response:
             if exc.status_code != _NOT_FOUND or not _is_page_request(path, scope):
                 raise
             return await self._index_response(scope)
-        if response.status_code == _OK and _HASHED_FILE.search(segments[-1]):
-            response.headers[_CACHE_CONTROL] = IMMUTABLE_CACHE_CONTROL
+        if response.status_code == _OK and looks_hashed(segments[-1]):
+            response.headers[_CACHE_CONTROL] = (
+                IMMUTABLE_CACHE_CONTROL if self._public else _PRIVATE_IMMUTABLE
+            )
         return response
 
     async def _index_response(self, scope: Scope) -> Response:
         response = await super().get_response(self._index, scope)
         # The shell references hashed bundles, so it must revalidate on each visit.
-        response.headers[_CACHE_CONTROL] = _NO_CACHE
+        response.headers[_CACHE_CONTROL] = _NO_CACHE if self._public else _PRIVATE_NO_CACHE
         return response
 
 
@@ -81,9 +100,24 @@ def _is_page_request(path: str, scope: Scope) -> bool:
     return "text/html" in Headers(scope=scope).get("accept", "").lower()
 
 
+def _registered_route_paths(app: FastAPI) -> list[str]:
+    """Every path registered on *app*, flattening FastAPI's lazy included routers."""
+    paths: list[str] = []
+    for route in app.routes:
+        contexts = getattr(route, "effective_route_contexts", None)
+        if contexts is None:
+            paths.append(getattr(route, "path", "") or "")
+            continue
+        for ctx in contexts():
+            starlette_route = ctx.starlette_route
+            path = getattr(starlette_route, "path", "") if starlette_route is not None else ctx.path
+            paths.append(path or "")
+    return paths
+
+
 def mount_spa_mounts(app: FastAPI, modules: list) -> None:
     """Mount every module's SPAs, exempt the public ones from auth, publish prefixes."""
-    problems = check_spa_mount_overlaps(modules)
+    problems = check_spa_mount_overlaps(modules, _registered_route_paths(app))
     if problems:
         raise SpaMountError("\n".join(str(p) for p in problems))
 
@@ -109,12 +143,15 @@ def _mount(app: FastAPI, module_name: str, mount: SpaMount, registry) -> bool:
         return False
     app.mount(
         mount.prefix,
-        SpaStaticFiles(directory=mount.dist_dir, index=mount.index),
+        SpaStaticFiles(
+            directory=mount.dist_dir, index=mount.index, public=mount.auth == SPA_AUTH_PUBLIC
+        ),
         name=f"spa:{module_name}:{mount.prefix}",
     )
     if mount.auth == SPA_AUTH_PUBLIC and registry is not None:
-        registry.add_exact(mount.prefix, methods=_SAFE_METHODS)
-        registry.add_prefix(f"{mount.prefix}/", methods=_SAFE_METHODS)
+        # Anchored to this mount's own paths. No other route can share the
+        # prefix: mount_spa_mounts refused the boot if one was registered.
+        registry.add_regex(f"{re.escape(mount.prefix)}(/.*)?$", methods=_SAFE_METHODS)
     return True
 
 
diff --git a/framework/hosting/tests/test_spa_mounts_541.py b/framework/hosting/tests/test_spa_mounts_541.py
index 2cb2844b9..9c07a5939 100644
--- a/framework/hosting/tests/test_spa_mounts_541.py
+++ b/framework/hosting/tests/test_spa_mounts_541.py
@@ -58,7 +58,7 @@ async def test_deep_link_serves_index(authenticated_client):
     r = await authenticated_client.get("/legacy/a/b/c", headers=_HTML)
     assert r.status_code == 200
     assert "legacy spa" in r.text
-    assert r.headers["cache-control"] == "no-cache"
+    assert r.headers["cache-control"] == "private, no-cache"
 
 
 async def test_root_serves_index_and_head_works(authenticated_client):
@@ -180,3 +180,92 @@ async def test_traversal_segment_refused_by_the_mount_itself(dist):
         with pytest.raises(HTTPException) as exc:
             await files.get_response(path, scope)
         assert exc.value.status_code == 404
+
+
+async def _boot_fails_with(settings, monkeypatch, tmp_path, mount, module=None):
+    from simple_module_hosting._spa_mount import SpaMountError
+
+    (tmp_path / "index.html").write_text("x", encoding="utf-8")
+    real = app_builder.discover_modules
+    extra = [_module([mount], name="Bad")]
+    if module is not None:
+        extra.append(module)
+    monkeypatch.setattr(
+        app_builder,
+        "discover_modules",
+        lambda enabled=None, *, strict=False: [*real(enabled=enabled, strict=strict), *extra],
+    )
+    with pytest.raises(SpaMountError, match="SM032"):
+        app_builder.create_app(settings)
+
+
+@pytest.mark.parametrize("prefix", ["/api/docs", "/api/redoc", "/api/openapi.json"])
+async def test_public_mount_over_framework_route_fails_boot(
+    settings, monkeypatch, tmp_path, prefix
+):
+    mount = SpaMount(prefix, tmp_path, auth="public")
+    await _boot_fails_with(settings, monkeypatch, tmp_path, mount)
+
+
+async def test_public_mount_over_registered_router_path_fails_boot(settings, monkeypatch, tmp_path):
+    class Router(ModuleBase):
+        meta = ModuleMeta(name="Pingy")
+
+        def register_routes(self, api_router, view_router):
+            view_router.get("/pingy-probe/ping")(lambda: {"ok": True})
+
+    mount = SpaMount("/pingy-probe", tmp_path, auth="public")
+    await _boot_fails_with(settings, monkeypatch, tmp_path, mount, Router())
+
+
+async def test_exemption_covers_only_the_mounts_own_paths(app):
+    registry = app.state.public_routes
+    assert registry.matches("GET", "/openspa")
+    assert registry.matches("HEAD", "/openspa/a/b")
+    assert not registry.matches("POST", "/openspa/a")
+    assert not registry.matches("GET", "/openspa2/x")
+    assert not registry.matches("GET", "/openspax")
+
+
+def test_route_paths_feed_the_overlap_check(tmp_path):
+    mod = _module([SpaMount("/thing", tmp_path)])
+    assert check_spa_mount_overlaps([mod], ["/thing/{id}"])
+    assert not check_spa_mount_overlaps([mod], ["/other/{id}", "/"])
+
+
+async def test_required_mount_responses_are_private(authenticated_client):
+    asset = await authenticated_client.get("/legacy/assets/index-3f9a8c21b.js")
+    assert asset.headers["cache-control"] == "private, max-age=31536000, immutable"
+    index = await authenticated_client.get("/legacy/x/y", headers=_HTML)
+    assert index.headers["cache-control"] == "private, no-cache"
+
+
+async def test_public_mount_hashed_asset_is_shared_cacheable(client, tmp_path):
+    from simple_module_hosting._spa_mount import SpaStaticFiles
+
+    root = tmp_path / "pub"
+    root.mkdir()
+    (root / "index.html").write_text("x", encoding="utf-8")
+    (root / "main-AbC12345.js").write_text("1", encoding="utf-8")
+    files = SpaStaticFiles(directory=root, index="index.html", public=True)
+    scope = {"method": "GET", "headers": [], "path": "/main-AbC12345.js"}
+    response = await files.get_response("main-AbC12345.js", scope)
+    assert response.headers["cache-control"] == "public, max-age=31536000, immutable"
+
+
+@pytest.mark.parametrize(
+    ("name", "hashed"),
+    [
+        ("index-3f9a8c21b.js", True),
+        ("chunk.AbCdEfGh.css", True),
+        ("main.a1b2c3d4e5f6.js", True),
+        ("jquery-ui-dialog.js", False),
+        ("some-long-name.js", False),
+        ("app.js", False),
+        ("v1.2.3.js", False),
+    ],
+)
+def test_hash_shapes(name, hashed):
+    from simple_module_hosting._spa_mount import looks_hashed
+
+    assert looks_hashed(name) is hashed

From ba7593367be041729204addc59a72a6e24c99253 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Thu, 22 Oct 2026 09:29:09 +0200
Subject: [PATCH 10/21] fix(audit): bulk audit reads real SET targets; every
 soft-delete shape recorded (#557)

Changes come from the statement's SET/VALUES targets resolved to mapped
attributes (bound values through the execute params, column-named params as
SQLAlchemy writes them); stray keys and excluded columns under Core keys no
longer leak. is_deleted written as SQL, a truthy value or in executemany rows
is bulk_soft_deleted, a falsy one bulk_restored; PK and soft-delete-flag
writes are never skipped as bookkeeping, so strict mode refuses them.

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 CHANGELOG.md                                  |  2 +-
 docs/modules/audit_log.md                     |  5 +-
 framework/db/simple_module_db/bulk_audit.py   | 62 +++---------
 .../db/simple_module_db/bulk_audit_targets.py | 91 +++++++++++++++++
 framework/db/tests/_bulk_audit_support.py     | 44 +++++++++
 framework/db/tests/conftest.py                |  8 ++
 framework/db/tests/test_db_bulk_audit.py      | 39 +-------
 .../db/tests/test_db_bulk_audit_targets.py    | 98 +++++++++++++++++++
 modules/audit_log/audit_log/constants.py      |  2 +
 modules/audit_log/audit_log/locales/de.json   |  3 +-
 modules/audit_log/audit_log/locales/en.json   |  3 +-
 .../pages/components/ChangesList.tsx          | 10 +-
 .../pages/components/EntriesTable.tsx         |  1 +
 .../audit_log/pages/components/FilterBar.tsx  |  1 +
 packages/i18n/src/generated-resources.ts      |  1 +
 packages/i18n/src/keys.generated.ts           |  1 +
 16 files changed, 279 insertions(+), 92 deletions(-)
 create mode 100644 framework/db/simple_module_db/bulk_audit_targets.py
 create mode 100644 framework/db/tests/_bulk_audit_support.py
 create mode 100644 framework/db/tests/test_db_bulk_audit_targets.py

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5b04a33b6..3753b5a0a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,7 +20,7 @@ All notable changes to this project are documented in this file. The format is b
 - Statement DML is audited (#557): `simple_module_db.bulk_audit` audits ORM bulk
   `update()` / `delete()` / `insert()` and Core DML on `Model.__table__` through
   the engine's audit sink, one `bulk_updated` / `bulk_deleted` /
-  `bulk_soft_deleted` entry per row (ids prefetched with the statement's `WHERE`
+  `bulk_soft_deleted` / `bulk_restored` entry per row (ids prefetched with the statement's `WHERE`
   and tenant scope) up to 500 rows, else one `"*"` summary; `bulk_inserted` is one
   summary per statement. `execution_options(sm_audit=False)` opts out;
   `record_bulk_audit(session, Model, action, ids, changes)` records `text()`
diff --git a/docs/modules/audit_log.md b/docs/modules/audit_log.md
index ea21ce1f7..0644153b7 100644
--- a/docs/modules/audit_log.md
+++ b/docs/modules/audit_log.md
@@ -37,9 +37,10 @@ audit_log = "audit_log.capture:audit_callback"
 
 `session.execute(update(Model)...)`, its `delete()` / `insert()` siblings and Core DML on `Model.__table__` never reach a flush, so a `do_orm_execute` listener (`simple_module_db.bulk_audit`) audits them instead, through the same per-engine `audit_callback` (requests and Celery workers alike):
 
-- **`UPDATE` / `DELETE`.** Before the statement runs, the listener reads the primary keys it will touch, with the same `WHERE` and the same tenant scope (soft-deleted rows included, as the write includes them). Up to 500 rows each get one entry (`bulk_updated`, `bulk_deleted`, or `bulk_soft_deleted` for an update setting `is_deleted = True`); `changes` holds the `SET` values as `{field, new}` (a SQL expression is stored as SQL with bind placeholders). `session.execute(update(Model), [{"id": ..., ...}, ...])` takes the ids from the rows instead.
+- **`UPDATE` / `DELETE`.** Before the statement runs, the listener reads the primary keys it will touch, with the same `WHERE` and the same tenant scope (soft-deleted rows included, as the write includes them). Up to 500 rows each get one entry (`bulk_updated`, `bulk_deleted`; an update that writes `is_deleted` is `bulk_soft_deleted` when the value is truthy or SQL such as `sa.true()`, else `bulk_restored`, in any statement shape including executemany rows); `changes` holds the `SET` values as `{field, new}` (a SQL expression is stored as SQL with bind placeholders). `session.execute(update(Model), [{"id": ..., ...}, ...])` takes the ids from the rows instead.
 - **More than 500 rows.** One summary entry with `entity_id` `"*"`: the `SET` values plus `where_sql` (the `WHERE` with bind placeholders, never the literal values), `rowcount` and `truncated: true`.
 - **`INSERT`.** One `bulk_inserted` summary entry per statement (`entity_id` `"*"`, the column values, or the column names for a multi-row insert).
+- **Only real targets count.** `changes` comes from the statement's `SET` / `VALUES` targets, each resolved to its model attribute (bound values read through the execute params). An execute-param key that names a column is written by SQLAlchemy, so it is a target too; any other param key is ignored. Primary-key and `is_deleted` writes are never treated as excluded bookkeeping.
 - **Exclusions apply as for a flush.** `__audit_exclude__` models (the outbox, `AuditEntry` itself) are skipped; `__audit_exclude_fields__` and mixin bookkeeping columns are dropped from `changes`; a statement that sets *only* excluded columns writes no entry. So the outbox's claim / delivery `UPDATE`s and the task heartbeat's `heartbeat_at` refresh stay unaudited.
 - **Same transaction.** Entries are added to the writing session, so a rollback discards them with the write. The sink catches and logs its own failures: auditing never fails the write it describes.
 
@@ -64,7 +65,7 @@ record_bulk_audit(session, Order, "bulk_updated", ids, {"status": "archived"})
 | `updated` | object in `session.dirty` with real column changes (empty diffs are skipped) |
 | `deleted` | object in `session.deleted` (hard delete) |
 | `soft_deleted` | a `SoftDeleteMixin` row the soft-delete listener moved into `session.new` with `is_deleted=True` |
-| `bulk_updated` / `bulk_deleted` / `bulk_soft_deleted` | statement `UPDATE` / `DELETE` (see above), one per row or one `"*"` summary |
+| `bulk_updated` / `bulk_deleted` / `bulk_soft_deleted` / `bulk_restored` | statement `UPDATE` / `DELETE` (see above), one per row or one `"*"` summary |
 | `bulk_inserted` | statement `INSERT`, one `"*"` summary per statement |
 
 `changes` is a list of `{field, new}` (creates) or `{field, old, new}` (updates) entries; deletes and soft-deletes carry an empty change list. Column values are normalised to JSON-safe scalars (non-primitives are stringified).
diff --git a/framework/db/simple_module_db/bulk_audit.py b/framework/db/simple_module_db/bulk_audit.py
index 78adfe95b..6411809a4 100644
--- a/framework/db/simple_module_db/bulk_audit.py
+++ b/framework/db/simple_module_db/bulk_audit.py
@@ -32,10 +32,10 @@
 from sqlalchemy import inspect as sa_inspect
 from sqlalchemy import select
 from sqlalchemy.orm import ORMExecuteState, Session
-from sqlalchemy.sql.elements import BindParameter, ClauseElement
 
 from simple_module_db import model_registry as registry
 from simple_module_db.audit import AuditRecord, _excluded_fields, _serialize
+from simple_module_db.bulk_audit_targets import _is_set, _shown, _targets
 from simple_module_db.query_filter import engine_policy
 from simple_module_db.tenancy import ALL_TENANTS_OPTION
 
@@ -51,6 +51,7 @@
 ACTION_BULK_UPDATED: Final = "bulk_updated"
 ACTION_BULK_DELETED: Final = "bulk_deleted"
 ACTION_BULK_SOFT_DELETED: Final = "bulk_soft_deleted"
+ACTION_BULK_RESTORED: Final = "bulk_restored"
 SUMMARY_ENTITY_ID: Final = "*"
 
 _SOFT_DELETE_FLAG: Final = "is_deleted"
@@ -73,37 +74,6 @@ def _target_class(execute_state: ORMExecuteState) -> type | None:
     return registry.classes_by_table.get(table) if table is not None else None
 
 
-def _column_name(key: Any) -> str:
-    if isinstance(key, str):
-        return key
-    return str(getattr(key, "key", None) or getattr(key, "name", None) or key)
-
-
-def _value(value: Any) -> Any:
-    if isinstance(value, BindParameter):
-        return _serialize(value.effective_value)
-    if isinstance(value, ClauseElement):
-        return str(value)  # an expression: SQL with bind placeholders
-    return _serialize(value)
-
-
-def _set_values(execute_state: ORMExecuteState) -> dict[str, Any]:
-    """The ``SET`` / ``VALUES`` of a single-row statement, by column name."""
-    stmt = execute_state.statement
-    pairs = getattr(stmt, "_ordered_values", None) or list(
-        (getattr(stmt, "_values", None) or {}).items()
-    )
-    values = {_column_name(k): _value(v) for k, v in pairs}
-    params = execute_state.parameters
-    if isinstance(params, dict):
-        values.update({_column_name(k): _serialize(v) for k, v in params.items()})
-    return values
-
-
-def _changes(values: dict[str, Any], excluded: frozenset[str]) -> list[dict[str, Any]]:
-    return [{"field": k, "new": v} for k, v in values.items() if k not in excluded]
-
-
 def _pk_str(values: tuple | list) -> str:
     return str(values[0]) if len(values) == 1 else str(tuple(values))
 
@@ -140,24 +110,22 @@ def _plan(execute_state: ORMExecuteState, cls: type) -> _Ctx | None:
     name = cls.__name__
     if execute_state.is_delete:
         return _Ctx(name, ACTION_BULK_DELETED, [])
-    rows = execute_state.parameters
-    multi = getattr(execute_state.statement, "_multi_values", None)
-    many = isinstance(rows, list) or bool(multi)
-    if isinstance(rows, list):
-        values = dict.fromkeys(sorted({k for row in rows for k in row}))
-    elif multi:
-        first = multi[0][0]
-        values = dict.fromkeys(_column_name(k) for k in first) if isinstance(first, dict) else {}
-    else:
-        values = _set_values(execute_state)
-    if execute_state.is_update and values.get(_SOFT_DELETE_FLAG) is True:
-        return _Ctx(name, ACTION_BULK_SOFT_DELETED, [])
+    targets, many = _targets(execute_state, cls)
+    flag = targets.pop(_SOFT_DELETE_FLAG, None)
+    if execute_state.is_update and flag is not None:
+        trashed = any(_is_set(v) for v in flag)
+        return _Ctx(name, ACTION_BULK_SOFT_DELETED if trashed else ACTION_BULK_RESTORED, [])
     pk = {col.key for col in sa_inspect(cls).primary_key}
-    changes = _changes(values, _excluded_fields(cls) | pk)
-    if values and not changes:
+    # An executemany UPDATE names rows by primary key; anywhere else a written
+    # key is a change and is never treated as bookkeeping.
+    skip = _excluded_fields(cls) | pk if many and execute_state.is_update else _excluded_fields(cls)
+    kept = {k: v for k, v in targets.items() if k not in skip}
+    if targets and not kept:
         return None  # only excluded columns: bookkeeping, like a flush
     if many:
-        changes = [{"field": c["field"]} for c in changes]
+        changes = [{"field": k} for k in kept]
+    else:
+        changes = [{"field": k, "new": _shown(v[0])} for k, v in kept.items()]
     action = ACTION_BULK_INSERTED if execute_state.is_insert else ACTION_BULK_UPDATED
     return _Ctx(name, action, changes)
 
diff --git a/framework/db/simple_module_db/bulk_audit_targets.py b/framework/db/simple_module_db/bulk_audit_targets.py
new file mode 100644
index 000000000..faec54ece
--- /dev/null
+++ b/framework/db/simple_module_db/bulk_audit_targets.py
@@ -0,0 +1,91 @@
+"""What a statement writes, by mapped attribute: the input to bulk auditing (#557).
+
+Split from ``bulk_audit``. Only the statement's own ``SET`` / ``VALUES`` targets
+count, each resolved to the model attribute it writes, so a stray key in the
+execute params, or an excluded column named by its Core key, cannot slip into
+an audit row's ``changes``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sqlalchemy import inspect as sa_inspect
+from sqlalchemy.orm import ORMExecuteState
+from sqlalchemy.sql.elements import BindParameter, ClauseElement, False_
+from sqlalchemy.sql.visitors import iterate
+
+from simple_module_db.audit import _serialize
+
+
+def _attr_names(cls: type) -> dict[str, str]:
+    """Column key and name → mapped attribute key, for every column attribute."""
+    names: dict[str, str] = {}
+    for prop in sa_inspect(cls).column_attrs:
+        for col in prop.columns:
+            names.setdefault(str(getattr(col, "key", "")), prop.key)
+            names.setdefault(str(getattr(col, "name", "")), prop.key)
+    return names
+
+
+def _attr(key: Any, names: dict[str, str]) -> str | None:
+    """The attribute a ``SET`` / ``VALUES`` target writes, or ``None`` if unmapped."""
+    raw = key if isinstance(key, str) else getattr(key, "key", None) or getattr(key, "name", None)
+    return names.get(str(raw)) if raw is not None else None
+
+
+def _resolve(value: Any, params: Any) -> Any:
+    """A bound value through the execute params; other SQL stays an expression."""
+    if isinstance(value, BindParameter):
+        if isinstance(params, dict) and value.key in params:
+            return params[value.key]
+        return value.effective_value
+    return value
+
+
+def _shown(value: Any) -> Any:
+    return str(value) if isinstance(value, ClauseElement) else _serialize(value)
+
+
+def _targets(execute_state: ORMExecuteState, cls: type) -> tuple[dict[str, list[Any]], bool]:
+    """Attribute → every value the statement writes to it, and whether it is many rows.
+
+    Every key is resolved to the mapped attribute it writes, and only mapped
+    columns count, so a stray param key never reaches ``changes`` and an
+    excluded column is excluded under its Core key too. A param whose key names
+    a column and is not one of the statement's own bind parameters is a
+    ``SET`` target exactly as SQLAlchemy reads it (it does get written), so it
+    is a target here as well; ignoring it would let a write hide behind an
+    excluded ``.values()`` entry.
+    """
+    names = _attr_names(cls)
+    stmt, params = execute_state.statement, execute_state.parameters
+    multi = getattr(stmt, "_multi_values", None)
+    pairs = getattr(stmt, "_ordered_values", None) or list(
+        (getattr(stmt, "_values", None) or {}).items()
+    )
+    if isinstance(params, list):
+        rows, many = params, True
+    elif multi:
+        rows, many = [r for r in multi[0] if isinstance(r, dict)], True
+    else:
+        row = {k: _resolve(v, params) for k, v in pairs}
+        if isinstance(params, dict):
+            tree = stmt if isinstance(stmt, ClauseElement) else None
+            bound = {e.key for e in iterate(tree) if isinstance(e, BindParameter)}
+            row.update({k: v for k, v in params.items() if k not in bound})
+        rows, many = [row], False
+    targets: dict[str, list[Any]] = {}
+    for row in rows:
+        for key, value in row.items():
+            attr = _attr(key, names)
+            if attr is not None:
+                targets.setdefault(attr, []).append(value)
+    return targets, many
+
+
+def _is_set(value: Any) -> bool:
+    """Whether a written ``is_deleted`` value trashes the row (unknown SQL counts)."""
+    if isinstance(value, False_):
+        return False
+    return True if isinstance(value, ClauseElement) else bool(value)
diff --git a/framework/db/tests/_bulk_audit_support.py b/framework/db/tests/_bulk_audit_support.py
new file mode 100644
index 000000000..5ed340243
--- /dev/null
+++ b/framework/db/tests/_bulk_audit_support.py
@@ -0,0 +1,44 @@
+"""Shared fixture for the bulk-audit tests (#557): an audited engine with a recorder sink."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator
+
+from _audit_models import AuditBase, AuditTestItem
+from _models import _TenantBase
+from simple_module_db.audit import AuditRecord
+from simple_module_db.listeners import register_listeners
+from simple_module_db.session import DatabaseState, init_db
+from simple_module_test.database import database_url_for_tests, init_db_kwargs, reset_schema
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import Session
+
+_URL = database_url_for_tests()
+
+
+class _Recorder:
+    def __init__(self) -> None:
+        self.records: list[AuditRecord] = []
+
+    def __call__(self, session: Session, records: list[AuditRecord]) -> None:
+        self.records.extend(records)
+
+    def summary(self) -> list[tuple[str, str, str]]:
+        return [(r.entity_type, r.action, r.entity_id) for r in self.records]
+
+
+async def audited_engine() -> AsyncGenerator[tuple[DatabaseState, AsyncSession, _Recorder]]:
+    recorder = _Recorder()
+    state = init_db(_URL, **init_db_kwargs(_URL))
+    state.audit_callback = recorder
+    register_listeners(state)
+    await reset_schema(state.engine)
+    async with state.engine.begin() as conn:
+        await conn.run_sync(AuditBase.metadata.create_all)
+        await conn.run_sync(_TenantBase.metadata.create_all)
+    async with state.session_factory() as session:
+        session.add_all([AuditTestItem(name=f"n{i}", value=i) for i in range(3)])
+        await session.flush()
+        recorder.records.clear()
+        yield state, session, recorder
+    await state.engine.dispose()
diff --git a/framework/db/tests/conftest.py b/framework/db/tests/conftest.py
index 5027ffae3..9fcef49ee 100644
--- a/framework/db/tests/conftest.py
+++ b/framework/db/tests/conftest.py
@@ -5,6 +5,7 @@
 from collections.abc import AsyncGenerator
 
 import pytest
+from _bulk_audit_support import audited_engine
 from _models import _tenant_session, _TenantBase
 from sqlalchemy.ext.asyncio import AsyncSession
 
@@ -28,3 +29,10 @@ async def acme_default_session() -> AsyncGenerator[AsyncSession, None]:
     """Single-tenant install with ``default_tenant="acme"``."""
     async for session in _tenant_session(_TenantBase.metadata, strict=False, default_tenant="acme"):
         yield session
+
+
+@pytest.fixture
+async def audited():
+    """``(state, session, recorder)``: an engine whose audit sink records (#557)."""
+    async for value in audited_engine():
+        yield value
diff --git a/framework/db/tests/test_db_bulk_audit.py b/framework/db/tests/test_db_bulk_audit.py
index 5ca1d1095..eeba7f7fe 100644
--- a/framework/db/tests/test_db_bulk_audit.py
+++ b/framework/db/tests/test_db_bulk_audit.py
@@ -2,57 +2,20 @@
 
 from __future__ import annotations
 
-from collections.abc import AsyncGenerator
-
 import pytest
 from _audit_models import (
-    AuditBase,
     AuditTestItem,
     ExcludedModel,
     PartialExcludeModel,
     SoftDeleteItem,
 )
-from _models import _TenantBase, _TenantItem
+from _models import _TenantItem
 from simple_module_db import bulk_audit, record_bulk_audit, tenant_context
 from simple_module_db.audit import AuditRecord
-from simple_module_db.listeners import register_listeners
-from simple_module_db.session import DatabaseState, init_db
-from simple_module_test.database import database_url_for_tests, init_db_kwargs, reset_schema
 from sqlalchemy import delete, func, insert, select, text, update
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import Session
 
-_URL = database_url_for_tests()
-
-
-class _Recorder:
-    def __init__(self) -> None:
-        self.records: list[AuditRecord] = []
-
-    def __call__(self, session: Session, records: list[AuditRecord]) -> None:
-        self.records.extend(records)
-
-    def summary(self) -> list[tuple[str, str, str]]:
-        return [(r.entity_type, r.action, r.entity_id) for r in self.records]
-
-
-@pytest.fixture
-async def audited() -> AsyncGenerator[tuple[DatabaseState, AsyncSession, _Recorder]]:
-    recorder = _Recorder()
-    state = init_db(_URL, **init_db_kwargs(_URL))
-    state.audit_callback = recorder
-    register_listeners(state)
-    await reset_schema(state.engine)
-    async with state.engine.begin() as conn:
-        await conn.run_sync(AuditBase.metadata.create_all)
-        await conn.run_sync(_TenantBase.metadata.create_all)
-    async with state.session_factory() as session:
-        session.add_all([AuditTestItem(name=f"n{i}", value=i) for i in range(3)])
-        await session.flush()
-        recorder.records.clear()
-        yield state, session, recorder
-    await state.engine.dispose()
-
 
 async def _ids(session: AsyncSession, where=None) -> list[str]:
     query = select(AuditTestItem.id).order_by(AuditTestItem.id)
diff --git a/framework/db/tests/test_db_bulk_audit_targets.py b/framework/db/tests/test_db_bulk_audit_targets.py
new file mode 100644
index 000000000..c575ee4bf
--- /dev/null
+++ b/framework/db/tests/test_db_bulk_audit_targets.py
@@ -0,0 +1,98 @@
+"""Bulk audit reads only a statement's own targets, and catches every soft-delete shape (#557).
+
+Regressions from the security review: excluded columns leaked through the
+execute params, and an ``is_deleted`` write that was not literally ``True``
+(SQL, a truthy int, an executemany row, a restore) went unrecorded and so
+also escaped ``refuse_unaudited_dml``.
+"""
+
+from __future__ import annotations
+
+import pytest
+from _audit_models import AuditTestItem, PartialExcludeModel, SoftDeleteItem
+from simple_module_db import UnauditedWriteError
+from sqlalchemy import bindparam, select, true, update
+
+
+async def _seed(session, recorder, *rows) -> list[int]:
+    session.add_all(rows)
+    await session.flush()
+    recorder.records.clear()
+    return [row.id for row in rows]
+
+
+async def test_excluded_and_stray_params_never_reach_changes(audited):
+    _state, session, recorder = audited
+    await _seed(session, recorder, PartialExcludeModel(username="u"))
+    stmt = update(PartialExcludeModel).values(username=bindparam("u"))
+    await session.execute(stmt, {"u": "v", "password_hash": "leak", "extra": "leak"})
+    assert [r.changes for r in recorder.records] == [[{"field": "username", "new": "v"}]]
+
+
+async def test_excluded_only_writes_through_params_or_core_keys_are_skipped(audited):
+    _state, session, recorder = audited
+    (pid,) = await _seed(session, recorder, PartialExcludeModel(username="u"))
+    table = PartialExcludeModel.__table__
+    await session.execute(update(table).values({table.c.password_hash: "h"}))
+    await session.execute(update(PartialExcludeModel), [{"id": pid, "password_hash": "h"}])
+    assert recorder.records == []
+
+
+async def test_a_column_param_beside_an_excluded_value_is_still_audited(audited):
+    _state, session, recorder = audited
+    await _seed(session, recorder, PartialExcludeModel(username="u"))
+    stmt = update(PartialExcludeModel).values(password_hash=bindparam("p"))
+    await session.execute(stmt, {"p": "h", "username": "hidden?"})
+    rows = (await session.execute(select(PartialExcludeModel.username))).scalars().all()
+    assert rows == ["hidden?"]  # SQLAlchemy writes it, so the trail must show it
+    assert [r.changes for r in recorder.records] == [[{"field": "username", "new": "hidden?"}]]
+
+
+@pytest.mark.parametrize(
+    ("value", "params"),
+    [(true(), None), (1, None), (bindparam("d"), {"d": True})],
+    ids=["sql-true", "truthy-int", "bound-param"],
+)
+async def test_soft_delete_shapes_are_recorded(audited, value, params):
+    _state, session, recorder = audited
+    await _seed(session, recorder, SoftDeleteItem(title="t"))
+    await session.execute(update(SoftDeleteItem).values(is_deleted=value), params)
+    assert [r.action for r in recorder.records] == ["bulk_soft_deleted"]
+
+
+async def test_executemany_soft_delete_and_restore(audited):
+    _state, session, recorder = audited
+    (sid,) = await _seed(session, recorder, SoftDeleteItem(title="t"))
+    await session.execute(update(SoftDeleteItem), [{"id": sid, "is_deleted": True}])
+    await session.execute(update(SoftDeleteItem), [{"id": sid, "is_deleted": False}])
+    await session.execute(update(SoftDeleteItem).values(is_deleted=False))
+    assert [r.action for r in recorder.records] == [
+        "bulk_soft_deleted",
+        "bulk_restored",
+        "bulk_restored",
+    ]
+
+
+async def test_primary_key_change_is_recorded(audited):
+    _state, session, recorder = audited
+    (iid,) = await _seed(session, recorder, AuditTestItem(name="pk"))
+    await session.execute(update(AuditTestItem).where(AuditTestItem.id == iid).values(id=9999))
+    assert [(r.action, r.changes) for r in recorder.records] == [
+        ("bulk_updated", [{"field": "id", "new": 9999}])
+    ]
+
+
+@pytest.mark.parametrize(
+    "stmt",
+    [
+        update(SoftDeleteItem).values(is_deleted=true()),
+        update(SoftDeleteItem).values(is_deleted=False),
+        update(AuditTestItem).values(id=9999),
+    ],
+    ids=["soft-delete", "restore", "pk-change"],
+)
+async def test_strict_mode_refuses_flag_and_pk_writes(audited, stmt):
+    state, session, _recorder = audited
+    state.refuse_unaudited_dml = True
+    with pytest.raises(UnauditedWriteError):
+        await session.execute(stmt.execution_options(sm_audit=False))
diff --git a/modules/audit_log/audit_log/constants.py b/modules/audit_log/audit_log/constants.py
index 25b0c64a4..e13229868 100644
--- a/modules/audit_log/audit_log/constants.py
+++ b/modules/audit_log/audit_log/constants.py
@@ -33,6 +33,7 @@
 ACTION_BULK_UPDATED: Final = "bulk_updated"
 ACTION_BULK_DELETED: Final = "bulk_deleted"
 ACTION_BULK_SOFT_DELETED: Final = "bulk_soft_deleted"
+ACTION_BULK_RESTORED: Final = "bulk_restored"
 ALL_ACTIONS: Final = (
     ACTION_CREATED,
     ACTION_UPDATED,
@@ -42,6 +43,7 @@
     ACTION_BULK_UPDATED,
     ACTION_BULK_DELETED,
     ACTION_BULK_SOFT_DELETED,
+    ACTION_BULK_RESTORED,
 )
 
 ENTITY_TYPE_MAX_LENGTH: Final = 255
diff --git a/modules/audit_log/audit_log/locales/de.json b/modules/audit_log/audit_log/locales/de.json
index 669868e82..c421f93ad 100644
--- a/modules/audit_log/audit_log/locales/de.json
+++ b/modules/audit_log/audit_log/locales/de.json
@@ -41,7 +41,8 @@
     "bulk_inserted": "massenweise erstellt",
     "bulk_updated": "massenweise geändert",
     "bulk_deleted": "massenweise gelöscht",
-    "bulk_soft_deleted": "massenweise archiviert"
+    "bulk_soft_deleted": "massenweise archiviert",
+    "bulk_restored": "massenweise wiederhergestellt"
   },
   "correlation": {
     "view_related": "Zugehörige Einträge",
diff --git a/modules/audit_log/audit_log/locales/en.json b/modules/audit_log/audit_log/locales/en.json
index 37dde5478..7a5878aba 100644
--- a/modules/audit_log/audit_log/locales/en.json
+++ b/modules/audit_log/audit_log/locales/en.json
@@ -41,7 +41,8 @@
     "bulk_inserted": "bulk created",
     "bulk_updated": "bulk updated",
     "bulk_deleted": "bulk deleted",
-    "bulk_soft_deleted": "bulk archived"
+    "bulk_soft_deleted": "bulk archived",
+    "bulk_restored": "bulk restored"
   },
   "correlation": {
     "view_related": "Related",
diff --git a/modules/audit_log/audit_log/pages/components/ChangesList.tsx b/modules/audit_log/audit_log/pages/components/ChangesList.tsx
index bc4eec310..5ea94835f 100644
--- a/modules/audit_log/audit_log/pages/components/ChangesList.tsx
+++ b/modules/audit_log/audit_log/pages/components/ChangesList.tsx
@@ -17,7 +17,13 @@ export interface Change {
  */
 const VISIBLE_LIMIT = 2;
 
-const DELETE_ACTIONS = new Set(['deleted', 'soft_deleted', 'bulk_deleted', 'bulk_soft_deleted']);
+const NO_DIFF_ACTIONS = new Set([
+  'deleted',
+  'soft_deleted',
+  'bulk_deleted',
+  'bulk_soft_deleted',
+  'bulk_restored',
+]);
 
 interface ChangesListProps {
   action: string;
@@ -30,7 +36,7 @@ export function ChangesList({ action, changes }: ChangesListProps) {
 
   // A delete records no diff — every field went away with the row. Saying
   // "no changes recorded" is the honest reading; a dash reads as a bug.
-  if (DELETE_ACTIONS.has(action)) {
+  if (NO_DIFF_ACTIONS.has(action)) {
     return <span className="text-muted-foreground">{t(keys.audit_log.changes.no_changes)}</span>;
   }
   // A create sets every field at once. Listing them all would bury the rows
diff --git a/modules/audit_log/audit_log/pages/components/EntriesTable.tsx b/modules/audit_log/audit_log/pages/components/EntriesTable.tsx
index 823f4c354..d86af243a 100644
--- a/modules/audit_log/audit_log/pages/components/EntriesTable.tsx
+++ b/modules/audit_log/audit_log/pages/components/EntriesTable.tsx
@@ -46,6 +46,7 @@ const ACTION_PILL: Record<string, string> = {
   bulk_updated: 'bg-blue-50 text-blue-700',
   bulk_deleted: 'bg-red-50 text-red-700',
   bulk_soft_deleted: 'bg-amber-50 text-amber-700',
+  bulk_restored: 'bg-blue-50 text-blue-700',
 };
 const PILL = 'inline-flex rounded-full px-2.5 py-0.5 text-[11px] font-medium';
 const TH = 'sm:px-6 text-[11px] font-semibold uppercase tracking-[0.08em] text-muted-foreground';
diff --git a/modules/audit_log/audit_log/pages/components/FilterBar.tsx b/modules/audit_log/audit_log/pages/components/FilterBar.tsx
index 98b959bc0..7fa3b6527 100644
--- a/modules/audit_log/audit_log/pages/components/FilterBar.tsx
+++ b/modules/audit_log/audit_log/pages/components/FilterBar.tsx
@@ -24,6 +24,7 @@ export const ACTIONS = [
   'bulk_updated',
   'bulk_deleted',
   'bulk_soft_deleted',
+  'bulk_restored',
 ] as const;
 
 /** A filterable entity type: the class name the column stores, shown as the
diff --git a/packages/i18n/src/generated-resources.ts b/packages/i18n/src/generated-resources.ts
index cb536960b..7ea8f8b4a 100644
--- a/packages/i18n/src/generated-resources.ts
+++ b/packages/i18n/src/generated-resources.ts
@@ -81,6 +81,7 @@ export default {
     'api_tokens.toasts.revoked_all_other': '',
     'audit_log.actions.bulk_deleted': '',
     'audit_log.actions.bulk_inserted': '',
+    'audit_log.actions.bulk_restored': '',
     'audit_log.actions.bulk_soft_deleted': '',
     'audit_log.actions.bulk_updated': '',
     'audit_log.actions.created': '',
diff --git a/packages/i18n/src/keys.generated.ts b/packages/i18n/src/keys.generated.ts
index 8e39b76e7..41661386f 100644
--- a/packages/i18n/src/keys.generated.ts
+++ b/packages/i18n/src/keys.generated.ts
@@ -114,6 +114,7 @@ export const keys = {
     actions: {
       bulk_deleted: 'audit_log.actions.bulk_deleted',
       bulk_inserted: 'audit_log.actions.bulk_inserted',
+      bulk_restored: 'audit_log.actions.bulk_restored',
       bulk_soft_deleted: 'audit_log.actions.bulk_soft_deleted',
       bulk_updated: 'audit_log.actions.bulk_updated',
       created: 'audit_log.actions.created',

From 22edcdb5445fb1a0bbc7e35296c5894c51b56fed Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Thu, 22 Oct 2026 09:33:26 +0200
Subject: [PATCH 11/21] fix(audit): per-row soft-delete actions; executemany
 targets union statement values (#557)

A statement writing is_deleted keeps its other columns in changes; executemany
rows get soft-delete/restore per row (distinct summaries past the cap). Each
executemany row is the statement's .values() resolved through that row plus
its column-named params, so a write cannot look excluded-only and escape
auditing or strict mode. Executemany no longer prefetches with unbound params.

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 docs/modules/audit_log.md                     |  4 +-
 framework/db/simple_module_db/bulk_audit.py   | 53 ++++++++++++-------
 .../db/simple_module_db/bulk_audit_targets.py | 47 ++++++++--------
 .../db/tests/test_db_bulk_audit_targets.py    | 51 ++++++++++++++++++
 .../pages/components/ChangesList.tsx          |  2 +-
 5 files changed, 115 insertions(+), 42 deletions(-)

diff --git a/docs/modules/audit_log.md b/docs/modules/audit_log.md
index 0644153b7..799d8ca31 100644
--- a/docs/modules/audit_log.md
+++ b/docs/modules/audit_log.md
@@ -37,10 +37,10 @@ audit_log = "audit_log.capture:audit_callback"
 
 `session.execute(update(Model)...)`, its `delete()` / `insert()` siblings and Core DML on `Model.__table__` never reach a flush, so a `do_orm_execute` listener (`simple_module_db.bulk_audit`) audits them instead, through the same per-engine `audit_callback` (requests and Celery workers alike):
 
-- **`UPDATE` / `DELETE`.** Before the statement runs, the listener reads the primary keys it will touch, with the same `WHERE` and the same tenant scope (soft-deleted rows included, as the write includes them). Up to 500 rows each get one entry (`bulk_updated`, `bulk_deleted`; an update that writes `is_deleted` is `bulk_soft_deleted` when the value is truthy or SQL such as `sa.true()`, else `bulk_restored`, in any statement shape including executemany rows); `changes` holds the `SET` values as `{field, new}` (a SQL expression is stored as SQL with bind placeholders). `session.execute(update(Model), [{"id": ..., ...}, ...])` takes the ids from the rows instead.
+- **`UPDATE` / `DELETE`.** Before the statement runs, the listener reads the primary keys it will touch, with the same `WHERE` and the same tenant scope (soft-deleted rows included, as the write includes them). Up to 500 rows each get one entry (`bulk_updated`, `bulk_deleted`; an update that writes `is_deleted` is `bulk_soft_deleted` when the value is truthy or SQL such as `sa.true()`, else `bulk_restored`, decided per row for executemany; the statement's other written columns stay in `changes`); `changes` holds the `SET` values as `{field, new}` (a SQL expression is stored as SQL with bind placeholders). `session.execute(update(Model), [{"id": ..., ...}, ...])` takes the ids from the rows instead.
 - **More than 500 rows.** One summary entry with `entity_id` `"*"`: the `SET` values plus `where_sql` (the `WHERE` with bind placeholders, never the literal values), `rowcount` and `truncated: true`.
 - **`INSERT`.** One `bulk_inserted` summary entry per statement (`entity_id` `"*"`, the column values, or the column names for a multi-row insert).
-- **Only real targets count.** `changes` comes from the statement's `SET` / `VALUES` targets, each resolved to its model attribute (bound values read through the execute params). An execute-param key that names a column is written by SQLAlchemy, so it is a target too; any other param key is ignored. Primary-key and `is_deleted` writes are never treated as excluded bookkeeping.
+- **Only real targets count.** `changes` comes from the statement's `SET` / `VALUES` targets, each resolved to its model attribute (bound values read through the execute params). An execute-param key that names a column (and is not one of the statement's bind parameters) is written by SQLAlchemy, so it is a target too, for a single dict and for every executemany row; any other param key is ignored. Primary-key and `is_deleted` writes are never treated as excluded bookkeeping.
 - **Exclusions apply as for a flush.** `__audit_exclude__` models (the outbox, `AuditEntry` itself) are skipped; `__audit_exclude_fields__` and mixin bookkeeping columns are dropped from `changes`; a statement that sets *only* excluded columns writes no entry. So the outbox's claim / delivery `UPDATE`s and the task heartbeat's `heartbeat_at` refresh stay unaudited.
 - **Same transaction.** Entries are added to the writing session, so a rollback discards them with the write. The sink catches and logs its own failures: auditing never fails the write it describes.
 
diff --git a/framework/db/simple_module_db/bulk_audit.py b/framework/db/simple_module_db/bulk_audit.py
index 6411809a4..fbfbdfd34 100644
--- a/framework/db/simple_module_db/bulk_audit.py
+++ b/framework/db/simple_module_db/bulk_audit.py
@@ -84,15 +84,21 @@ class _Ctx:
     def __init__(self, entity_type: str, action: str, changes: list[dict[str, Any]]) -> None:
         self.entity_type = entity_type
         self.action = action
+        self.row_actions = [action]
         self.changes = changes
         self.user_id = _current_user()
         self.correlation_id = correlation_id.get("") or None
 
-    def record(self, entity_id: str, changes: list[dict[str, Any]] | None = None) -> AuditRecord:
+    def record(
+        self,
+        entity_id: str,
+        changes: list[dict[str, Any]] | None = None,
+        action: str | None = None,
+    ) -> AuditRecord:
         return AuditRecord(
             entity_type=self.entity_type,
             entity_id=entity_id,
-            action=self.action,
+            action=action or self.action,
             changes=self.changes if changes is None else changes,
             user_id=self.user_id,
             correlation_id=self.correlation_id,
@@ -110,24 +116,32 @@ def _plan(execute_state: ORMExecuteState, cls: type) -> _Ctx | None:
     name = cls.__name__
     if execute_state.is_delete:
         return _Ctx(name, ACTION_BULK_DELETED, [])
-    targets, many = _targets(execute_state, cls)
-    flag = targets.pop(_SOFT_DELETE_FLAG, None)
-    if execute_state.is_update and flag is not None:
-        trashed = any(_is_set(v) for v in flag)
-        return _Ctx(name, ACTION_BULK_SOFT_DELETED if trashed else ACTION_BULK_RESTORED, [])
+    rows, many = _targets(execute_state, cls)
+    default = ACTION_BULK_INSERTED if execute_state.is_insert else ACTION_BULK_UPDATED
+    # The soft-delete flag picks a row's action; it is never a change, and
+    # never bookkeeping that lets the statement go unrecorded.
+    actions = [
+        (ACTION_BULK_SOFT_DELETED if _is_set(row[_SOFT_DELETE_FLAG]) else ACTION_BULK_RESTORED)
+        if execute_state.is_update and _SOFT_DELETE_FLAG in row
+        else default
+        for row in rows
+    ]
     pk = {col.key for col in sa_inspect(cls).primary_key}
     # An executemany UPDATE names rows by primary key; anywhere else a written
     # key is a change and is never treated as bookkeeping.
     skip = _excluded_fields(cls) | pk if many and execute_state.is_update else _excluded_fields(cls)
-    kept = {k: v for k, v in targets.items() if k not in skip}
-    if targets and not kept:
+    skip = skip | {_SOFT_DELETE_FLAG}
+    written = list(dict.fromkeys(k for row in rows for k in row))
+    kept = [k for k in written if k not in skip]
+    if written and not kept and all(a == default for a in actions):
         return None  # only excluded columns: bookkeeping, like a flush
     if many:
         changes = [{"field": k} for k in kept]
     else:
-        changes = [{"field": k, "new": _shown(v[0])} for k, v in kept.items()]
-    action = ACTION_BULK_INSERTED if execute_state.is_insert else ACTION_BULK_UPDATED
-    return _Ctx(name, action, changes)
+        changes = [{"field": k, "new": _shown(rows[0][k])} for k in kept]
+    ctx = _Ctx(name, actions[0] if actions else default, changes)
+    ctx.row_actions = actions or [default]
+    return ctx
 
 
 def _prefetch_ids(execute_state: ORMExecuteState, cls: type, cap: int) -> list[str]:
@@ -158,14 +172,14 @@ def _bulk_by_pk_ids(execute_state: ORMExecuteState, cls: type) -> list[str] | No
     return [_pk_str([row[k] for k in pk]) for row in params]
 
 
-def _summary(ctx: _Ctx, stmt: Any, rowcount: Any) -> AuditRecord:
+def _summary(ctx: _Ctx, stmt: Any, rowcount: Any, action: str) -> AuditRecord:
     where = getattr(stmt, "whereclause", None)
     summary = [
         {"field": "where_sql", "new": str(where) if where is not None else None},
         {"field": "rowcount", "new": rowcount},
         {"field": "truncated", "new": True},
     ]
-    return ctx.record(SUMMARY_ENTITY_ID, [*ctx.changes, *summary])
+    return ctx.record(SUMMARY_ENTITY_ID, [*ctx.changes, *summary], action)
 
 
 def audit_statement(execute_state: ORMExecuteState) -> Any:
@@ -195,17 +209,20 @@ def audit_statement(execute_state: ORMExecuteState) -> Any:
         return None
     if ctx is None:
         return None
+    params = execute_state.parameters
     ids = _bulk_by_pk_ids(execute_state, cls)
-    if ids is None and not execute_state.is_insert:
+    by_row = ids is not None and len(ids) == len(ctx.row_actions)
+    if ids is None and not (execute_state.is_insert or isinstance(params, list)):
         ids = _prefetch_ids(execute_state, cls, BULK_AUDIT_ID_CAP)
     stmt = execute_state.statement
     result = execute_state.invoke_statement()
-    params = execute_state.parameters
     if ids is not None and len(ids) <= BULK_AUDIT_ID_CAP:
-        records = [ctx.record(i) for i in ids]
+        acts = ctx.row_actions if by_row else [ctx.action] * len(ids)
+        records = [ctx.record(i, action=a) for i, a in zip(ids, acts, strict=True)]
     else:
         rowcount = len(params) if isinstance(params, list) else getattr(result, "rowcount", None)
-        records = [_summary(ctx, stmt, rowcount)]
+        distinct = dict.fromkeys(ctx.row_actions)
+        records = [_summary(ctx, stmt, rowcount, a) for a in distinct]
     _deliver(session, callback, records)
     return result
 
diff --git a/framework/db/simple_module_db/bulk_audit_targets.py b/framework/db/simple_module_db/bulk_audit_targets.py
index faec54ece..dd830ddbb 100644
--- a/framework/db/simple_module_db/bulk_audit_targets.py
+++ b/framework/db/simple_module_db/bulk_audit_targets.py
@@ -47,16 +47,17 @@ def _shown(value: Any) -> Any:
     return str(value) if isinstance(value, ClauseElement) else _serialize(value)
 
 
-def _targets(execute_state: ORMExecuteState, cls: type) -> tuple[dict[str, list[Any]], bool]:
-    """Attribute → every value the statement writes to it, and whether it is many rows.
+def _targets(execute_state: ORMExecuteState, cls: type) -> tuple[list[dict[str, Any]], bool]:
+    """Per written row, attribute → value; and whether the statement writes many rows.
 
     Every key is resolved to the mapped attribute it writes, and only mapped
     columns count, so a stray param key never reaches ``changes`` and an
-    excluded column is excluded under its Core key too. A param whose key names
-    a column and is not one of the statement's own bind parameters is a
-    ``SET`` target exactly as SQLAlchemy reads it (it does get written), so it
-    is a target here as well; ignoring it would let a write hide behind an
-    excluded ``.values()`` entry.
+    excluded column is excluded under its Core key too. Each row is the
+    statement's own ``.values()`` (bind parameters resolved through that row's
+    params) plus every param that names a column and is not one of the
+    statement's bind parameters: SQLAlchemy writes those as ``SET`` targets, so
+    ignoring them would let a write hide behind an excluded ``.values()`` entry.
+    The same rule holds for a single dict of params and for executemany rows.
     """
     names = _attr_names(cls)
     stmt, params = execute_state.statement, execute_state.parameters
@@ -64,24 +65,28 @@ def _targets(execute_state: ORMExecuteState, cls: type) -> tuple[dict[str, list[
     pairs = getattr(stmt, "_ordered_values", None) or list(
         (getattr(stmt, "_values", None) or {}).items()
     )
-    if isinstance(params, list):
-        rows, many = params, True
-    elif multi:
-        rows, many = [r for r in multi[0] if isinstance(r, dict)], True
+    if multi:
+        raw, many = [r for r in multi[0] if isinstance(r, dict)], True
     else:
-        row = {k: _resolve(v, params) for k, v in pairs}
-        if isinstance(params, dict):
-            tree = stmt if isinstance(stmt, ClauseElement) else None
-            bound = {e.key for e in iterate(tree) if isinstance(e, BindParameter)}
-            row.update({k: v for k, v in params.items() if k not in bound})
-        rows, many = [row], False
-    targets: dict[str, list[Any]] = {}
-    for row in rows:
+        tree = stmt if isinstance(stmt, ClauseElement) else None
+        bound = {e.key for e in iterate(tree) if isinstance(e, BindParameter)}
+        many = isinstance(params, list)
+        param_rows = params if isinstance(params, list) else [params]
+        raw = []
+        for row_params in param_rows:
+            row = {k: _resolve(v, row_params) for k, v in pairs}
+            if isinstance(row_params, dict):
+                row.update({k: v for k, v in row_params.items() if k not in bound})
+            raw.append(row)
+    rows: list[dict[str, Any]] = []
+    for row in raw:
+        mapped: dict[str, Any] = {}
         for key, value in row.items():
             attr = _attr(key, names)
             if attr is not None:
-                targets.setdefault(attr, []).append(value)
-    return targets, many
+                mapped[attr] = value
+        rows.append(mapped)
+    return rows, many
 
 
 def _is_set(value: Any) -> bool:
diff --git a/framework/db/tests/test_db_bulk_audit_targets.py b/framework/db/tests/test_db_bulk_audit_targets.py
index c575ee4bf..d3fc9e2e3 100644
--- a/framework/db/tests/test_db_bulk_audit_targets.py
+++ b/framework/db/tests/test_db_bulk_audit_targets.py
@@ -96,3 +96,54 @@ async def test_strict_mode_refuses_flag_and_pk_writes(audited, stmt):
     state.refuse_unaudited_dml = True
     with pytest.raises(UnauditedWriteError):
         await session.execute(stmt.execution_options(sm_audit=False))
+
+
+async def test_soft_delete_with_other_columns_keeps_their_changes(audited):
+    _state, session, recorder = audited
+    await _seed(session, recorder, SoftDeleteItem(title="t"))
+    await session.execute(update(SoftDeleteItem).values(is_deleted=True, title="gone"))
+    assert [(r.action, r.changes) for r in recorder.records] == [
+        ("bulk_soft_deleted", [{"field": "title", "new": "gone"}])
+    ]
+
+
+async def test_executemany_rows_that_disagree_get_their_own_actions(audited):
+    _state, session, recorder = audited
+    a, b = await _seed(session, recorder, SoftDeleteItem(title="a"), SoftDeleteItem(title="b"))
+    rows = [{"id": a, "is_deleted": True}, {"id": b, "is_deleted": False}]
+    await session.execute(update(SoftDeleteItem), rows)
+    assert [(r.entity_id, r.action) for r in recorder.records] == [
+        (str(a), "bulk_soft_deleted"),
+        (str(b), "bulk_restored"),
+    ]
+
+
+def _core_executemany(value_key: str):
+    table = PartialExcludeModel.__table__
+    stmt = update(table).where(table.c.id == bindparam("b_id"))
+    return stmt.values({value_key: bindparam("b_v")})
+
+
+async def test_executemany_unions_statement_values_and_column_params(audited):
+    _state, session, recorder = audited
+    (pid,) = await _seed(session, recorder, PartialExcludeModel(username="u"))
+    await session.execute(_core_executemany("username"), [{"b_id": pid, "b_v": "x"}])
+    hidden = [{"b_id": pid, "b_v": "h", "username": "y"}]
+    await session.execute(_core_executemany("password_hash"), hidden)
+    excluded_only = [{"b_id": pid, "b_v": "h2"}]
+    await session.execute(_core_executemany("password_hash"), excluded_only)
+    assert [(r.action, r.changes[:1]) for r in recorder.records] == [
+        ("bulk_updated", [{"field": "username"}]),
+        ("bulk_updated", [{"field": "username"}]),
+    ]
+    assert "password_hash" not in str([r.changes for r in recorder.records])
+
+
+async def test_strict_mode_sees_executemany_column_params(audited):
+    state, session, recorder = audited
+    (pid,) = await _seed(session, recorder, PartialExcludeModel(username="u"))
+    state.refuse_unaudited_dml = True
+    stmt = _core_executemany("password_hash").execution_options(sm_audit=False)
+    with pytest.raises(UnauditedWriteError):
+        await session.execute(stmt, [{"b_id": pid, "b_v": "h", "username": "y"}])
+    await session.execute(stmt, [{"b_id": pid, "b_v": "h"}])  # excluded-only: allowed
diff --git a/modules/audit_log/audit_log/pages/components/ChangesList.tsx b/modules/audit_log/audit_log/pages/components/ChangesList.tsx
index 5ea94835f..5d83c4339 100644
--- a/modules/audit_log/audit_log/pages/components/ChangesList.tsx
+++ b/modules/audit_log/audit_log/pages/components/ChangesList.tsx
@@ -36,7 +36,7 @@ export function ChangesList({ action, changes }: ChangesListProps) {
 
   // A delete records no diff — every field went away with the row. Saying
   // "no changes recorded" is the honest reading; a dash reads as a bug.
-  if (NO_DIFF_ACTIONS.has(action)) {
+  if (NO_DIFF_ACTIONS.has(action) && changes.length === 0) {
     return <span className="text-muted-foreground">{t(keys.audit_log.changes.no_changes)}</span>;
   }
   // A create sets every field at once. Listing them all would bury the rows

From cd970de3b15182554a3f29d026186a7cc998717c Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Thu, 22 Oct 2026 09:35:51 +0200
Subject: [PATCH 12/21] feat(sharing): optional generic share module for
 resource-scoped access (#526)

sharing_resource_share (tenant-scoped, audited, unique incl. tenant_id,
hard delete on revoke) with share_exists_for() for OwnedResourcePolicy;
expiry is checked in SQL. Grant/revoke/list API validates the resource
type against the registry, the granter's can("share") on the row and the
grantee via the user directory. Admin page /admin/sharing (en + de).
Migration f733c7938fd1: a new root and head labelled sharing.

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 .github/workflows/release.yml                 |   1 +
 .../f733c7938fd1_sharing_resource_share.py    |  82 +++++++++
 host/pyproject.toml                           |   2 +
 host/tests/test_migration_graph.py            |   5 +-
 modules/sharing/.gitignore                    |  17 ++
 modules/sharing/LICENSE                       |  21 +++
 modules/sharing/README.md                     |  54 ++++++
 modules/sharing/package.json                  |  18 ++
 modules/sharing/pyproject.toml                |  46 +++++
 modules/sharing/sharing/__init__.py           |   0
 modules/sharing/sharing/constants.py          |  64 +++++++
 modules/sharing/sharing/contracts/__init__.py |   5 +
 modules/sharing/sharing/contracts/schemas.py  |  36 ++++
 modules/sharing/sharing/deps.py               |  25 +++
 modules/sharing/sharing/endpoints/__init__.py |   0
 modules/sharing/sharing/endpoints/api.py      |  65 +++++++
 modules/sharing/sharing/endpoints/views.py    |  73 ++++++++
 modules/sharing/sharing/locales/de.json       |  33 ++++
 modules/sharing/sharing/locales/en.json       |  33 ++++
 modules/sharing/sharing/models.py             |  51 ++++++
 modules/sharing/sharing/module.py             |  86 ++++++++++
 modules/sharing/sharing/pages/Admin.tsx       | 101 +++++++++++
 .../sharing/pages/components/ShareTable.tsx   |  86 ++++++++++
 modules/sharing/sharing/pages/types.ts        |  14 ++
 modules/sharing/sharing/policy.py             | 109 ++++++++++++
 modules/sharing/sharing/present.py            |  41 +++++
 modules/sharing/sharing/py.typed              |   0
 modules/sharing/sharing/service.py            | 158 ++++++++++++++++++
 modules/sharing/sharing/services.py           |  22 +++
 modules/sharing/sharing/settings.py           |  17 ++
 modules/sharing/tests/_sharing_support.py     |  67 ++++++++
 modules/sharing/tests/test_sharing_http.py    | 103 ++++++++++++
 modules/sharing/tests/test_sharing_service.py | 145 ++++++++++++++++
 modules/sharing/tsconfig.json                 |  10 ++
 package-lock.json                             |  20 +++
 packages/i18n/src/generated-resources.ts      |  21 +++
 packages/i18n/src/keys.generated.ts           |  33 ++++
 pyproject.toml                                |   3 +-
 uv.lock                                       |  22 +++
 39 files changed, 1687 insertions(+), 2 deletions(-)
 create mode 100644 host/migrations/versions/f733c7938fd1_sharing_resource_share.py
 create mode 100644 modules/sharing/.gitignore
 create mode 100644 modules/sharing/LICENSE
 create mode 100644 modules/sharing/README.md
 create mode 100644 modules/sharing/package.json
 create mode 100644 modules/sharing/pyproject.toml
 create mode 100644 modules/sharing/sharing/__init__.py
 create mode 100644 modules/sharing/sharing/constants.py
 create mode 100644 modules/sharing/sharing/contracts/__init__.py
 create mode 100644 modules/sharing/sharing/contracts/schemas.py
 create mode 100644 modules/sharing/sharing/deps.py
 create mode 100644 modules/sharing/sharing/endpoints/__init__.py
 create mode 100644 modules/sharing/sharing/endpoints/api.py
 create mode 100644 modules/sharing/sharing/endpoints/views.py
 create mode 100644 modules/sharing/sharing/locales/de.json
 create mode 100644 modules/sharing/sharing/locales/en.json
 create mode 100644 modules/sharing/sharing/models.py
 create mode 100644 modules/sharing/sharing/module.py
 create mode 100644 modules/sharing/sharing/pages/Admin.tsx
 create mode 100644 modules/sharing/sharing/pages/components/ShareTable.tsx
 create mode 100644 modules/sharing/sharing/pages/types.ts
 create mode 100644 modules/sharing/sharing/policy.py
 create mode 100644 modules/sharing/sharing/present.py
 create mode 100644 modules/sharing/sharing/py.typed
 create mode 100644 modules/sharing/sharing/service.py
 create mode 100644 modules/sharing/sharing/services.py
 create mode 100644 modules/sharing/sharing/settings.py
 create mode 100644 modules/sharing/tests/_sharing_support.py
 create mode 100644 modules/sharing/tests/test_sharing_http.py
 create mode 100644 modules/sharing/tests/test_sharing_service.py
 create mode 100644 modules/sharing/tsconfig.json

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index c81fb26b7..0870f6e56 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -141,6 +141,7 @@ jobs:
           - simple_module_site_lock
           - simple_module_tenants
           - simple_module_users
+          - simple_module_sharing
     environment:
       name: pypi
       url: https://pypi.org/project/${{ matrix.package }}/
diff --git a/host/migrations/versions/f733c7938fd1_sharing_resource_share.py b/host/migrations/versions/f733c7938fd1_sharing_resource_share.py
new file mode 100644
index 000000000..9fc5fbff6
--- /dev/null
+++ b/host/migrations/versions/f733c7938fd1_sharing_resource_share.py
@@ -0,0 +1,82 @@
+"""sharing: generic resource shares (GH #526)
+
+A new root: the table references no other module, so ``downgrade sharing@base``
+removes only it.
+
+Revision ID: f733c7938fd1
+Revises:
+Create Date: 2026-10-22 09:30:44.320042
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "f733c7938fd1"
+down_revision: str | None = None
+branch_labels: str | Sequence[str] | None = ("sharing",)
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table(
+        "sharing_resource_share",
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("(CURRENT_TIMESTAMP)"),
+            nullable=False,
+        ),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("created_by", sa.String(length=255), nullable=True),
+        sa.Column("updated_by", sa.String(length=255), nullable=True),
+        sa.Column("tenant_id", sa.String(length=50), nullable=False),
+        sa.Column("id", sa.Uuid(), nullable=False),
+        sa.Column("resource_type", sa.String(length=100), nullable=False),
+        sa.Column("resource_id", sa.String(length=100), nullable=False),
+        sa.Column("subject_type", sa.String(length=16), nullable=False),
+        sa.Column("subject_id", sa.String(length=255), nullable=False),
+        sa.Column("role", sa.String(length=32), nullable=False),
+        sa.Column("granted_by", sa.String(length=255), nullable=False),
+        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=True),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_sharing_resource_share")),
+        sa.UniqueConstraint(
+            "tenant_id",
+            "resource_type",
+            "resource_id",
+            "subject_type",
+            "subject_id",
+            name="uq_sharing_resource_share_subject",
+        ),
+    )
+    op.create_index(
+        "ix_sharing_resource_share_resource",
+        "sharing_resource_share",
+        ["tenant_id", "resource_type", "resource_id"],
+        unique=False,
+    )
+    op.create_index(
+        op.f("ix_sharing_resource_share_subject_id"),
+        "sharing_resource_share",
+        ["subject_id"],
+        unique=False,
+    )
+    op.create_index(
+        op.f("ix_sharing_resource_share_tenant_id"),
+        "sharing_resource_share",
+        ["tenant_id"],
+        unique=False,
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_index(op.f("ix_sharing_resource_share_tenant_id"), table_name="sharing_resource_share")
+    op.drop_index(op.f("ix_sharing_resource_share_subject_id"), table_name="sharing_resource_share")
+    op.drop_index("ix_sharing_resource_share_resource", table_name="sharing_resource_share")
+    op.drop_table("sharing_resource_share")
+    # ### end Alembic commands ###
diff --git a/host/pyproject.toml b/host/pyproject.toml
index 0ea4952f6..c9b0c4ac7 100644
--- a/host/pyproject.toml
+++ b/host/pyproject.toml
@@ -18,6 +18,7 @@ dependencies = [
     "simple_module_tenants",
     "simple_module_api_tokens",
     "simple_module_mail",
+    "simple_module_sharing",
     "python-multipart>=0.0.6",
 ]
 
@@ -36,3 +37,4 @@ simple_module_site_lock = { workspace = true }
 simple_module_tenants = { workspace = true }
 simple_module_api_tokens = { workspace = true }
 simple_module_mail = { workspace = true }
+simple_module_sharing = { workspace = true }
diff --git a/host/tests/test_migration_graph.py b/host/tests/test_migration_graph.py
index 0fc0ae4be..8645cd859 100644
--- a/host/tests/test_migration_graph.py
+++ b/host/tests/test_migration_graph.py
@@ -44,9 +44,10 @@
     "f1a9c3d7b2e4": "tenants",
     "70786227af4c": "audit_log",
     "a7c2e91d4b58": "audit_log",
+    "f733c7938fd1": "sharing",
 }
 
-_ROOTS = {"77162e7b184b", "e36ab09c4a92"}
+_ROOTS = {"77162e7b184b", "e36ab09c4a92", "f733c7938fd1"}
 
 # head revision -> module owning the tables it creates or alters.
 _HEADS = {
@@ -54,6 +55,7 @@
     "d7b3a9e5c1f2": "mail",  # reported as ``api_tokens`` (inherited label)
     "f1a9c3d7b2e4": "tenants",
     "f6a3b9d2e8c4": "keycloak",
+    "f733c7938fd1": "sharing",
 }
 
 # Labels written in the revision files themselves.
@@ -62,6 +64,7 @@
     "51b2058d8afd": "api_tokens",
     "168a2882f443": "keycloak",
     "e36ab09c4a92": "tenants",
+    "f733c7938fd1": "sharing",
 }
 
 # Known mislabels: revisions that inherit a label from an ancestor owned by a
diff --git a/modules/sharing/.gitignore b/modules/sharing/.gitignore
new file mode 100644
index 000000000..091feecbb
--- /dev/null
+++ b/modules/sharing/.gitignore
@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+*.db
+*.sqlite3
+.env
+
+# Built frontend assets — shipped inside the wheel via force-include but
+# NOT source-controlled. Re-run `smpy module build` before `uv build` to
+# repopulate.
+*/static/dist/
+
+# smpy module verify/build cache (throwaway scaffolded host)
+.smpy/
diff --git a/modules/sharing/LICENSE b/modules/sharing/LICENSE
new file mode 100644
index 000000000..a1e1d361f
--- /dev/null
+++ b/modules/sharing/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anto Subash
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/modules/sharing/README.md b/modules/sharing/README.md
new file mode 100644
index 000000000..c3a3afebc
--- /dev/null
+++ b/modules/sharing/README.md
@@ -0,0 +1,54 @@
+# simple_module_sharing
+
+A generic share table for
+[simple_module](https://github.com/antosubash/simple_module_python) apps:
+give one user `view` or `edit` access to one row of another module, with an
+optional expiry, without that module shipping a bespoke share model. It plugs
+into the framework's resource-scoped access (`ResourcePolicy`,
+`OwnedResourcePolicy`, `RequiresResource`), so detail routes, lists and counts
+all honour a share in SQL.
+
+## Install
+
+```bash
+pip install simple_module_sharing
+```
+
+Add `simple_module_sharing` to your host's dependencies; the
+`[project.entry-points.simple_module]` entry point is discovered automatically
+at boot. Run `alembic upgrade heads` to create `sharing_resource_share`.
+
+## Usage
+
+Declare the resource type in the owning module and hand the policy a
+`share_exists` factory:
+
+```python
+from sharing.policy import share_exists_for
+
+NOTE_POLICY = OwnedResourcePolicy(
+    Note.owner_id,
+    bypass_perm=PERM_NOTES_MANAGE,
+    share_exists=share_exists_for("notes.note", Note.id),
+)
+
+
+def register_resource_types(self, registry):
+    registry.register(
+        ResourceType(name="notes.note", policy=NOTE_POLICY, select_by_id=select_by_id(Note))
+    )
+```
+
+| Route | Purpose | Permission |
+|---|---|---|
+| `POST /api/sharing/shares` | Grant or update a share | `sharing.share` + policy `can("share")` |
+| `GET /api/sharing/shares?resource_type=&resource_id=` | Shares on one row | `sharing.share` + policy `can("share")` |
+| `DELETE /api/sharing/shares/{id}` | Revoke (hard delete) | `sharing.share`; granter, grantee or `sharing.manage` |
+| `GET /admin/sharing/` | Admin list of every share in the tenant | `sharing.view` |
+
+Shares are tenant-scoped, expired shares never match, and grantees are
+validated through the user directory. See `docs/modules/sharing.md`.
+
+## License
+
+MIT
diff --git a/modules/sharing/package.json b/modules/sharing/package.json
new file mode 100644
index 000000000..5bf9c7789
--- /dev/null
+++ b/modules/sharing/package.json
@@ -0,0 +1,18 @@
+{
+  "name": "@simple-module-py/sharing",
+  "version": "0.0.37",
+  "private": true,
+  "description": "Frontend assets for the Sharing module",
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@inertiajs/react": "^3.7.0",
+    "@simple-module-py/ui": "*"
+  },
+  "devDependencies": {
+    "@simple-module-py/tsconfig": "*"
+  },
+  "dependencies": {
+    "lucide-react": "^1.43.0"
+  }
+}
diff --git a/modules/sharing/pyproject.toml b/modules/sharing/pyproject.toml
new file mode 100644
index 000000000..b5c94dfae
--- /dev/null
+++ b/modules/sharing/pyproject.toml
@@ -0,0 +1,46 @@
+[project]
+name = "simple_module_sharing"
+version = "0.0.37"
+description = "Generic resource shares (owner / shared-with-user) for simple_module resource-scoped access"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+authors = [{ name = "Anto Subash", email = "antosubash@live.com" }]
+keywords = ["simple-module", "sharing", "permissions", "access-control"]
+dependencies = [
+    "simple_module_core==0.0.37",
+    "simple_module_db==0.0.37",
+    "simple_module_hosting==0.0.37",
+    "simple_module_inertia==0.0.37",
+]
+
+[project.entry-points.simple_module]
+sharing = "sharing.module:SharingModule"
+
+[project.urls]
+Homepage = "https://github.com/antosubash/simple_module_python"
+Repository = "https://github.com/antosubash/simple_module_python"
+Issues = "https://github.com/antosubash/simple_module_python/issues"
+Changelog = "https://github.com/antosubash/simple_module_python/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+# The distribution name (simple_module_sharing) doesn't match the package
+# directory (sharing), so hatchling can't infer what to ship — without
+# this the wheel builds empty and the entry point fails to import.
+[tool.hatch.build.targets.wheel]
+packages = ["sharing"]
+
+# Ship the module-root package.json inside the wheel so the host can
+# discover JS deps via importlib.resources after a pip install.
+[tool.hatch.build.targets.wheel.force-include]
+"package.json" = "sharing/package.json"
+
+[tool.uv.sources]
+simple_module_core = { workspace = true }
+simple_module_db = { workspace = true }
+simple_module_hosting = { workspace = true }
+simple_module_inertia = { workspace = true }
diff --git a/modules/sharing/sharing/__init__.py b/modules/sharing/sharing/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/modules/sharing/sharing/constants.py b/modules/sharing/sharing/constants.py
new file mode 100644
index 000000000..75d85b4a3
--- /dev/null
+++ b/modules/sharing/sharing/constants.py
@@ -0,0 +1,64 @@
+"""Stable identifiers for the sharing module."""
+
+from __future__ import annotations
+
+from typing import Final
+
+from simple_module_core.resources import ACTION_EDIT, ACTION_VIEW
+
+MODULE_NAME: Final = "Sharing"
+MODULE_PACKAGE: Final = "sharing"
+LOCALE_NAMESPACE: Final = "sharing"
+
+PERM_GROUP: Final = "Sharing"
+PERM_SHARE: Final = "sharing.share"
+"""Use the grant/revoke API at all; the resource's own policy still decides."""
+PERM_VIEW: Final = "sharing.view"
+"""See every share in the tenant (the admin page)."""
+PERM_MANAGE: Final = "sharing.manage"
+"""Revoke any share in the tenant."""
+USER_ROLE: Final = "user"
+
+PAGE_ADMIN: Final = "Sharing/Admin"
+
+API_PREFIX: Final = "/api/sharing"
+VIEW_PREFIX: Final = "/admin/sharing"
+# Trailing slash: the index route is registered at "/" under the prefix.
+ADMIN_URL: Final = f"{VIEW_PREFIX}/"
+AUDIT_URL_TEMPLATE: Final = f"{VIEW_PREFIX}/?share={{id}}"
+
+MENU_LABEL: Final = "Sharing"
+MENU_LABEL_KEY: Final = "sharing.nav.title"
+MENU_ICON: Final = "share"
+MENU_ORDER: Final = 60
+MENU_GROUP: Final = "Access"
+MENU_GROUP_KEY: Final = "ui.nav_groups.access"
+AUDIT_LABEL: Final = "Share"
+AUDIT_LABEL_KEY: Final = "sharing.audit.share"
+
+# Prefix is load-bearing: all modules share one schema.
+TABLE_SHARE: Final = "sharing_resource_share"
+UQ_SHARE: Final = "uq_sharing_resource_share_subject"
+IX_SHARE_RESOURCE: Final = "ix_sharing_resource_share_resource"
+
+RESOURCE_TYPE_MAX: Final = 100
+RESOURCE_ID_MAX: Final = 100
+SUBJECT_TYPE_MAX: Final = 16
+SUBJECT_ID_MAX: Final = 255
+ROLE_MAX: Final = 32
+
+SUBJECT_USER: Final = "user"
+"""The only subject kind so far; the column leaves room for groups or tenants."""
+
+# A role is the action it grants plus everything it implies.
+ROLE_IMPLIES: Final[dict[str, tuple[str, ...]]] = {
+    ACTION_VIEW: (ACTION_VIEW,),
+    ACTION_EDIT: (ACTION_VIEW, ACTION_EDIT),
+}
+
+ERR_UNKNOWN_TYPE: Final = "Unknown resource type"
+ERR_NOT_FOUND: Final = "Not found"
+ERR_UNKNOWN_GRANTEE: Final = "Unknown user"
+ERR_BAD_ROLE: Final = "This role cannot be granted on this resource type"
+ERR_EXPIRED: Final = "expires_at must be in the future"
+ERR_SELF: Final = "You cannot share a resource with yourself"
diff --git a/modules/sharing/sharing/contracts/__init__.py b/modules/sharing/sharing/contracts/__init__.py
new file mode 100644
index 000000000..4eaa3dc9f
--- /dev/null
+++ b/modules/sharing/sharing/contracts/__init__.py
@@ -0,0 +1,5 @@
+"""Sharing contracts — public interface for other modules."""
+
+from sharing.contracts.schemas import ShareGrant, ShareOut
+
+__all__ = ["ShareGrant", "ShareOut"]
diff --git a/modules/sharing/sharing/contracts/schemas.py b/modules/sharing/sharing/contracts/schemas.py
new file mode 100644
index 000000000..bd0aa7a0d
--- /dev/null
+++ b/modules/sharing/sharing/contracts/schemas.py
@@ -0,0 +1,36 @@
+"""Sharing DTOs — the module's public surface."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+
+from simple_module_core.resources import ACTION_VIEW
+from sqlmodel import Field, SQLModel
+
+from sharing.constants import RESOURCE_ID_MAX, RESOURCE_TYPE_MAX, ROLE_MAX, SUBJECT_ID_MAX
+
+
+class ShareGrant(SQLModel):
+    """Grant (or update) one user's access to one resource."""
+
+    resource_type: str = Field(min_length=1, max_length=RESOURCE_TYPE_MAX)
+    resource_id: str = Field(min_length=1, max_length=RESOURCE_ID_MAX)
+    subject_id: str = Field(min_length=1, max_length=SUBJECT_ID_MAX)
+    role: str = Field(default=ACTION_VIEW, max_length=ROLE_MAX)
+    expires_at: datetime | None = None
+
+
+class ShareOut(SQLModel):
+    id: uuid.UUID
+    resource_type: str
+    resource_id: str
+    subject_type: str
+    subject_id: str
+    subject_label: str | None = None
+    role: str
+    granted_by: str
+    granted_by_label: str | None = None
+    expires_at: datetime | None = None
+    expired: bool = False
+    created_at: datetime | None = None
diff --git a/modules/sharing/sharing/deps.py b/modules/sharing/sharing/deps.py
new file mode 100644
index 000000000..3f2ef2d58
--- /dev/null
+++ b/modules/sharing/sharing/deps.py
@@ -0,0 +1,25 @@
+"""FastAPI dependencies for the sharing module."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import Depends, HTTPException, Request
+from simple_module_core.user_directory import get_user_directory
+from simple_module_db.deps import get_db
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from sharing.service import SharingError, SharingService
+
+
+async def get_sharing_service(
+    request: Request, db: AsyncSession = Depends(get_db)
+) -> SharingService:
+    return SharingService(db, request.app.state.sm.resource_types, get_user_directory(request.app))
+
+
+SharingServiceDep = Annotated[SharingService, Depends(get_sharing_service)]
+
+
+def http_error(exc: SharingError) -> HTTPException:
+    return HTTPException(status_code=exc.status_code, detail=exc.detail)
diff --git a/modules/sharing/sharing/endpoints/__init__.py b/modules/sharing/sharing/endpoints/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/modules/sharing/sharing/endpoints/api.py b/modules/sharing/sharing/endpoints/api.py
new file mode 100644
index 000000000..25d646305
--- /dev/null
+++ b/modules/sharing/sharing/endpoints/api.py
@@ -0,0 +1,65 @@
+"""REST API for shares — mounted under ``/api/sharing``.
+
+Gated on ``sharing.share`` (so an API token scoped to it may call these);
+the resource's own policy then decides per row.
+"""
+
+from __future__ import annotations
+
+import uuid
+
+from fastapi import APIRouter, Depends, Request
+from simple_module_core.resources import ResourcePrincipal
+from simple_module_core.user_directory import get_user_directory
+from simple_module_hosting.permissions import RequiresPermission
+from simple_module_hosting.resource_deps import resource_principal
+
+from sharing.constants import PERM_SHARE
+from sharing.contracts.schemas import ShareGrant, ShareOut
+from sharing.deps import SharingServiceDep, http_error
+from sharing.present import present_shares
+from sharing.service import SharingError
+
+router = APIRouter(prefix="/shares", dependencies=[Depends(RequiresPermission(PERM_SHARE))])
+
+
+@router.get("", response_model=list[ShareOut])
+async def list_shares(
+    request: Request,
+    resource_type: str,
+    resource_id: str,
+    service: SharingServiceDep,
+    who: ResourcePrincipal = Depends(resource_principal),
+) -> list[ShareOut]:
+    try:
+        shares = await service.for_resource(who, resource_type, resource_id)
+    except SharingError as exc:
+        raise http_error(exc) from None
+    return await present_shares(get_user_directory(request.app), service.db, shares)
+
+
+@router.post("", response_model=ShareOut, status_code=201)
+async def grant_share(
+    request: Request,
+    data: ShareGrant,
+    service: SharingServiceDep,
+    who: ResourcePrincipal = Depends(resource_principal),
+) -> ShareOut:
+    try:
+        share = await service.grant(who, data)
+    except SharingError as exc:
+        raise http_error(exc) from None
+    (out,) = await present_shares(get_user_directory(request.app), service.db, [share])
+    return out
+
+
+@router.delete("/{share_id}", status_code=204)
+async def revoke_share(
+    share_id: uuid.UUID,
+    service: SharingServiceDep,
+    who: ResourcePrincipal = Depends(resource_principal),
+) -> None:
+    try:
+        await service.revoke(who, share_id)
+    except SharingError as exc:
+        raise http_error(exc) from None
diff --git a/modules/sharing/sharing/endpoints/views.py b/modules/sharing/sharing/endpoints/views.py
new file mode 100644
index 000000000..25ed6e705
--- /dev/null
+++ b/modules/sharing/sharing/endpoints/views.py
@@ -0,0 +1,73 @@
+"""The admin page — mounted under ``/admin/sharing``."""
+
+from __future__ import annotations
+
+import uuid
+
+from fastapi import APIRouter, Depends, Request
+from simple_module_core.resources import ResourcePrincipal
+from simple_module_core.user_directory import get_user_directory
+from simple_module_db import TenantIsolationError, paginate
+from simple_module_hosting.inertia_deps import InertiaDep
+from simple_module_hosting.pagination import LenientPageParamsDep
+from simple_module_hosting.permissions import RequiresPermission
+from simple_module_hosting.resource_deps import resource_principal
+from simple_module_inertia import InertiaResponse
+from sqlmodel import col, select
+from starlette.responses import RedirectResponse
+
+from sharing.constants import ADMIN_URL, PAGE_ADMIN, PERM_MANAGE, PERM_VIEW
+from sharing.deps import SharingServiceDep, http_error
+from sharing.models import ResourceShare
+from sharing.present import present_shares
+from sharing.service import SharingError
+
+router = APIRouter()
+
+
+@router.get("/", response_model=None, dependencies=[Depends(RequiresPermission(PERM_VIEW))])
+async def admin_index(
+    request: Request,
+    inertia: InertiaDep,
+    service: SharingServiceDep,
+    params: LenientPageParamsDep,
+    who: ResourcePrincipal = Depends(resource_principal),
+) -> InertiaResponse:
+    stmt = select(ResourceShare).order_by(
+        col(ResourceShare.created_at).desc(), col(ResourceShare.id)
+    )
+    try:
+        page = await paginate(service.db, stmt, params)
+        shares = await present_shares(get_user_directory(request.app), service.db, page.items)
+        total, served, tenant_required = page.total, page.page, False
+    except TenantIsolationError:
+        # Strict tenancy with no active tenant: nothing to list.
+        shares, total, served, tenant_required = [], 0, 1, True
+    return await inertia.render(
+        PAGE_ADMIN,
+        {
+            "shares": [s.model_dump(mode="json") for s in shares],
+            "total": total,
+            "page": served,
+            "per_page": params.per_page,
+            "can_revoke": who.has(PERM_MANAGE),
+            "tenant_required": tenant_required,
+        },
+    )
+
+
+@router.post(
+    "/{share_id}/revoke",
+    response_model=None,
+    dependencies=[Depends(RequiresPermission(PERM_MANAGE))],
+)
+async def admin_revoke(
+    share_id: uuid.UUID,
+    service: SharingServiceDep,
+    who: ResourcePrincipal = Depends(resource_principal),
+) -> RedirectResponse:
+    try:
+        await service.revoke(who, share_id)
+    except SharingError as exc:
+        raise http_error(exc) from None
+    return RedirectResponse(ADMIN_URL, status_code=303)
diff --git a/modules/sharing/sharing/locales/de.json b/modules/sharing/sharing/locales/de.json
new file mode 100644
index 000000000..ba606ee72
--- /dev/null
+++ b/modules/sharing/sharing/locales/de.json
@@ -0,0 +1,33 @@
+{
+  "nav": {
+    "title": "Freigaben"
+  },
+  "permission_group": "Freigaben",
+  "audit": {
+    "share": "Freigabe"
+  },
+  "admin": {
+    "title": "Freigaben",
+    "description": "Wer in diesem Arbeitsbereich Zugriff auf welche Ressource erhalten hat.",
+    "tenant_required": "Wählen Sie einen Arbeitsbereich, um seine Freigaben zu sehen."
+  },
+  "list": {
+    "resource": "Ressource",
+    "subject": "Freigegeben für",
+    "role": "Rolle",
+    "granted_by": "Freigegeben von",
+    "expires": "Läuft ab",
+    "actions": "Aktionen",
+    "never": "Nie",
+    "expired": "Abgelaufen",
+    "revoke": "Widerrufen",
+    "empty_title": "Noch nichts freigegeben",
+    "empty_description": "Freigaben erscheinen hier, sobald jemand einer anderen Person Zugriff auf eine Ressource gibt."
+  },
+  "revoke": {
+    "title": "Diese Freigabe widerrufen?",
+    "description": "Die Person verliert sofort den Zugriff auf die Ressource.",
+    "confirm": "Widerrufen",
+    "cancel": "Abbrechen"
+  }
+}
diff --git a/modules/sharing/sharing/locales/en.json b/modules/sharing/sharing/locales/en.json
new file mode 100644
index 000000000..779b087c4
--- /dev/null
+++ b/modules/sharing/sharing/locales/en.json
@@ -0,0 +1,33 @@
+{
+  "nav": {
+    "title": "Sharing"
+  },
+  "permission_group": "Sharing",
+  "audit": {
+    "share": "Share"
+  },
+  "admin": {
+    "title": "Shares",
+    "description": "Who has been given access to which resource in this workspace.",
+    "tenant_required": "Select a workspace to see its shares."
+  },
+  "list": {
+    "resource": "Resource",
+    "subject": "Shared with",
+    "role": "Role",
+    "granted_by": "Granted by",
+    "expires": "Expires",
+    "actions": "Actions",
+    "never": "Never",
+    "expired": "Expired",
+    "revoke": "Revoke",
+    "empty_title": "Nothing shared yet",
+    "empty_description": "Shares appear here when someone gives another user access to a resource."
+  },
+  "revoke": {
+    "title": "Revoke this share?",
+    "description": "The user loses access to the resource immediately.",
+    "confirm": "Revoke",
+    "cancel": "Cancel"
+  }
+}
diff --git a/modules/sharing/sharing/models.py b/modules/sharing/sharing/models.py
new file mode 100644
index 000000000..9f0c4fdf6
--- /dev/null
+++ b/modules/sharing/sharing/models.py
@@ -0,0 +1,51 @@
+"""The generic share table (GH #526)."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+
+from simple_module_db.base import create_module_base
+from simple_module_db.mixins import AuditMixin, MultiTenantMixin
+from sqlalchemy import Index, UniqueConstraint
+from sqlmodel import Field
+
+from sharing.constants import (
+    IX_SHARE_RESOURCE,
+    RESOURCE_ID_MAX,
+    RESOURCE_TYPE_MAX,
+    ROLE_MAX,
+    SUBJECT_ID_MAX,
+    SUBJECT_TYPE_MAX,
+    SUBJECT_USER,
+    TABLE_SHARE,
+    UQ_SHARE,
+)
+
+Base = create_module_base("sharing")
+
+
+class ResourceShare(Base, MultiTenantMixin, AuditMixin, table=True):  # ty: ignore[unsupported-base]
+    """One subject's access to one resource.
+
+    ``resource_id`` is the canonical text of the row's key (a UUID's ``hex``,
+    an int's decimal), so the policy's ``EXISTS`` can compare it on any
+    database. Revoking deletes the row; expiry is checked in SQL.
+    """
+
+    __tablename__ = TABLE_SHARE
+    __table_args__ = (
+        UniqueConstraint(
+            "tenant_id", "resource_type", "resource_id", "subject_type", "subject_id", name=UQ_SHARE
+        ),
+        Index(IX_SHARE_RESOURCE, "tenant_id", "resource_type", "resource_id"),
+    )
+
+    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
+    resource_type: str = Field(max_length=RESOURCE_TYPE_MAX)
+    resource_id: str = Field(max_length=RESOURCE_ID_MAX)
+    subject_type: str = Field(default=SUBJECT_USER, max_length=SUBJECT_TYPE_MAX)
+    subject_id: str = Field(max_length=SUBJECT_ID_MAX, index=True)
+    role: str = Field(max_length=ROLE_MAX)
+    granted_by: str = Field(max_length=SUBJECT_ID_MAX)
+    expires_at: datetime | None = Field(default=None)
diff --git a/modules/sharing/sharing/module.py b/modules/sharing/sharing/module.py
new file mode 100644
index 000000000..3577ebf17
--- /dev/null
+++ b/modules/sharing/sharing/module.py
@@ -0,0 +1,86 @@
+"""Sharing module: a generic share table for resource-scoped access (GH #526)."""
+
+from __future__ import annotations
+
+import importlib.resources
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from simple_module_core import ModuleBase, ModuleMeta
+from simple_module_core.audit_links import AuditLink
+from simple_module_core.menu import MenuItem, MenuRegistry, MenuSection
+from simple_module_core.module_settings import register_module_settings
+from simple_module_core.tenancy import TenantRole, tenant_role
+
+from sharing import constants as c
+
+if TYPE_CHECKING:
+    from fastapi import APIRouter, FastAPI
+    from simple_module_core.audit_links import AuditLinkRegistry
+    from simple_module_core.permissions import PermissionRegistry
+
+
+class SharingModule(ModuleBase):
+    meta = ModuleMeta(
+        name=c.MODULE_NAME,
+        route_prefix=c.API_PREFIX,
+        view_prefix=c.VIEW_PREFIX,
+    )
+
+    def register_settings(self, app: FastAPI) -> None:
+        from sharing.services import SharingServices
+        from sharing.settings import SharingSettings
+
+        register_module_settings(
+            app, c.MODULE_PACKAGE, SharingSettings, lambda s: SharingServices(settings=s)
+        )
+
+    def register_routes(self, api_router: APIRouter, view_router: APIRouter) -> None:
+        from sharing.endpoints.api import router as api
+        from sharing.endpoints.views import router as views
+
+        api_router.include_router(api)
+        view_router.include_router(views)
+
+    def register_menu_items(self, registry: MenuRegistry) -> None:
+        registry.add(
+            MenuItem(
+                label=c.MENU_LABEL,
+                label_key=c.MENU_LABEL_KEY,
+                url=c.ADMIN_URL,
+                icon=c.MENU_ICON,
+                order=c.MENU_ORDER,
+                section=MenuSection.ADMIN_SIDEBAR,
+                group=c.MENU_GROUP,
+                group_key=c.MENU_GROUP_KEY,
+                permissions=[c.PERM_VIEW],
+            )
+        )
+
+    def register_permissions(self, registry: PermissionRegistry) -> None:
+        registry.add_group(
+            c.PERM_GROUP,
+            [c.PERM_SHARE, c.PERM_VIEW, c.PERM_MANAGE],
+            label_key=f"{c.LOCALE_NAMESPACE}.permission_group",
+        )
+        # Sharing what you own is an ordinary user action; the resource's
+        # policy (``can("share")``) is what actually decides.
+        registry.map_role(c.USER_ROLE, [c.PERM_SHARE])
+        for role in TenantRole:
+            registry.map_role(tenant_role(role), [c.PERM_SHARE])
+
+    def register_audit_links(self, registry: AuditLinkRegistry) -> None:
+        from sharing.models import ResourceShare
+
+        registry.register(
+            AuditLink.for_model(
+                ResourceShare,
+                url_template=c.AUDIT_URL_TEMPLATE,
+                label=c.AUDIT_LABEL,
+                label_key=c.AUDIT_LABEL_KEY,
+            )
+        )
+
+    def locale_dirs(self) -> dict[str, Path]:
+        base = Path(str(importlib.resources.files(__package__) / "locales"))
+        return {c.LOCALE_NAMESPACE: base}
diff --git a/modules/sharing/sharing/pages/Admin.tsx b/modules/sharing/sharing/pages/Admin.tsx
new file mode 100644
index 000000000..cc647c28a
--- /dev/null
+++ b/modules/sharing/sharing/pages/Admin.tsx
@@ -0,0 +1,101 @@
+import { Head, router, usePage } from '@inertiajs/react';
+import { keys, useT } from '@simple-module-py/i18n';
+import { ConfirmActionDialog } from '@simple-module-py/ui/components/ConfirmActionDialog';
+import { InlineBanner } from '@simple-module-py/ui/components/InlineBanner';
+import { PageShell } from '@simple-module-py/ui/components/PageShell';
+import { PaginationBar } from '@simple-module-py/ui/components/PaginationBar';
+import { AdminLayout } from '@simple-module-py/ui/layouts/AdminLayout';
+import { Building2, Trash2 } from 'lucide-react';
+import { useState } from 'react';
+import { ShareTable } from './components/ShareTable';
+import type { Share } from './types';
+
+interface Props {
+  shares: Share[];
+  total: number;
+  page: number;
+  per_page: number;
+  can_revoke: boolean;
+  tenant_required: boolean;
+}
+
+const BASE_URL = '/admin/sharing';
+
+/** Every share in the active tenant; admins may revoke any of them. */
+function Admin() {
+  const props = usePage<{ props: Props }>().props as unknown as Props;
+  const { t } = useT();
+  const [pending, setPending] = useState<Share | null>(null);
+  const [busy, setBusy] = useState(false);
+  // An audit-log link lands here as ?share=<id>; mark that row.
+  const highlightId =
+    typeof window === 'undefined' ? null : new URLSearchParams(window.location.search).get('share');
+
+  function goTo(page: number) {
+    router.get(`${BASE_URL}/`, { page }, { preserveScroll: true });
+  }
+
+  function confirmRevoke() {
+    if (!pending) return;
+    setBusy(true);
+    router.post(
+      `${BASE_URL}/${pending.id}/revoke`,
+      {},
+      {
+        preserveScroll: true,
+        onFinish: () => {
+          setBusy(false);
+          setPending(null);
+        },
+      },
+    );
+  }
+
+  return (
+    <>
+      <Head title={t(keys.sharing.admin.title)} />
+      <PageShell
+        title={t(keys.sharing.admin.title)}
+        description={t(keys.sharing.admin.description)}
+      >
+        {props.tenant_required ? (
+          <InlineBanner
+            icon={Building2}
+            tone="warning"
+            title={t(keys.sharing.admin.tenant_required)}
+          />
+        ) : (
+          <>
+            <ShareTable
+              shares={props.shares}
+              canRevoke={props.can_revoke}
+              highlightId={highlightId}
+              onRevoke={setPending}
+            />
+            <PaginationBar
+              page={props.page}
+              perPage={props.per_page}
+              total={props.total}
+              onPageChange={goTo}
+              hideWhenSinglePage
+            />
+          </>
+        )}
+      </PageShell>
+      <ConfirmActionDialog
+        open={pending !== null}
+        onOpenChange={(open) => !open && setPending(null)}
+        icon={Trash2}
+        title={t(keys.sharing.revoke.title)}
+        description={t(keys.sharing.revoke.description)}
+        confirmLabel={t(keys.sharing.revoke.confirm)}
+        cancelLabel={t(keys.sharing.revoke.cancel)}
+        onConfirm={confirmRevoke}
+        busy={busy}
+      />
+    </>
+  );
+}
+
+Admin.layout = [AdminLayout];
+export default Admin;
diff --git a/modules/sharing/sharing/pages/components/ShareTable.tsx b/modules/sharing/sharing/pages/components/ShareTable.tsx
new file mode 100644
index 000000000..87a86efbf
--- /dev/null
+++ b/modules/sharing/sharing/pages/components/ShareTable.tsx
@@ -0,0 +1,86 @@
+import { keys, useT } from '@simple-module-py/i18n';
+import { EmptyState } from '@simple-module-py/ui/components/EmptyState';
+import { Badge } from '@simple-module-py/ui/components/ui/badge';
+import { Button } from '@simple-module-py/ui/components/ui/button';
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@simple-module-py/ui/components/ui/table';
+import { formatDayMonthYear } from '@simple-module-py/ui/lib/date-format';
+import { Share2 } from 'lucide-react';
+import type { Share } from '../types';
+
+interface Props {
+  shares: Share[];
+  canRevoke: boolean;
+  highlightId?: string | null;
+  onRevoke: (share: Share) => void;
+}
+
+export function ShareTable({ shares, canRevoke, highlightId, onRevoke }: Props) {
+  const { t } = useT();
+  const never = t(keys.sharing.list.never);
+
+  if (shares.length === 0) {
+    return (
+      <EmptyState
+        icon={Share2}
+        title={t(keys.sharing.list.empty_title)}
+        description={t(keys.sharing.list.empty_description)}
+      />
+    );
+  }
+
+  return (
+    <div className="overflow-x-auto rounded-lg border">
+      <Table>
+        <TableHeader>
+          <TableRow>
+            <TableHead>{t(keys.sharing.list.resource)}</TableHead>
+            <TableHead>{t(keys.sharing.list.subject)}</TableHead>
+            <TableHead>{t(keys.sharing.list.role)}</TableHead>
+            <TableHead>{t(keys.sharing.list.granted_by)}</TableHead>
+            <TableHead>{t(keys.sharing.list.expires)}</TableHead>
+            {canRevoke && (
+              <TableHead className="text-right">{t(keys.sharing.list.actions)}</TableHead>
+            )}
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {shares.map((share) => (
+            <TableRow key={share.id} data-state={highlightId === share.id ? 'selected' : undefined}>
+              <TableCell>
+                <div className="font-medium">{share.resource_type}</div>
+                <code className="text-xs text-muted-foreground">{share.resource_id}</code>
+              </TableCell>
+              <TableCell>{share.subject_label ?? share.subject_id}</TableCell>
+              <TableCell>
+                <Badge variant="secondary">{share.role}</Badge>
+              </TableCell>
+              <TableCell>{share.granted_by_label ?? share.granted_by}</TableCell>
+              <TableCell>
+                {formatDayMonthYear(share.expires_at, never)}
+                {share.expired && (
+                  <Badge variant="outline" className="ml-2">
+                    {t(keys.sharing.list.expired)}
+                  </Badge>
+                )}
+              </TableCell>
+              {canRevoke && (
+                <TableCell className="text-right">
+                  <Button variant="ghost" size="sm" onClick={() => onRevoke(share)}>
+                    {t(keys.sharing.list.revoke)}
+                  </Button>
+                </TableCell>
+              )}
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+    </div>
+  );
+}
diff --git a/modules/sharing/sharing/pages/types.ts b/modules/sharing/sharing/pages/types.ts
new file mode 100644
index 000000000..a36e1d113
--- /dev/null
+++ b/modules/sharing/sharing/pages/types.ts
@@ -0,0 +1,14 @@
+export interface Share {
+  id: string;
+  resource_type: string;
+  resource_id: string;
+  subject_type: string;
+  subject_id: string;
+  subject_label: string | null;
+  role: string;
+  granted_by: string;
+  granted_by_label: string | null;
+  expires_at: string | null;
+  expired: boolean;
+  created_at: string | null;
+}
diff --git a/modules/sharing/sharing/policy.py b/modules/sharing/sharing/policy.py
new file mode 100644
index 000000000..22d45d991
--- /dev/null
+++ b/modules/sharing/sharing/policy.py
@@ -0,0 +1,109 @@
+"""Plug shares into a module's ``OwnedResourcePolicy`` (GH #526).
+
+::
+
+    from sharing.policy import share_exists_for
+
+    NOTE_POLICY = OwnedResourcePolicy(
+        Note.owner_id,
+        bypass_perm=PERM_NOTES_MANAGE,
+        share_exists=share_exists_for(NOTE_TYPE, Note.id),
+    )
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Callable
+from datetime import UTC, datetime
+from typing import Any
+
+from simple_module_core.resources import ResourcePrincipal
+from sqlalchemy import String, cast, func, inspect, or_
+from sqlmodel import exists, select
+
+from sharing.constants import ROLE_IMPLIES, SUBJECT_USER
+from sharing.models import ResourceShare
+
+
+def roles_granting(action: str) -> tuple[str, ...]:
+    """Every share role that implies *action*."""
+    return tuple(role for role, implied in ROLE_IMPLIES.items() if action in implied)
+
+
+def _is_uuid(column: Any) -> bool:
+    try:
+        return column.type.python_type is uuid.UUID
+    except (AttributeError, NotImplementedError):
+        return False
+
+
+def id_text(column: Any) -> Any:
+    """*column* rendered as the canonical text :func:`canonical_id` stores.
+
+    UUIDs become 32 lowercase hex digits on every dialect (Postgres casts with
+    hyphens, SQLite stores without), everything else its plain text.
+    """
+    text = cast(column, String)
+    if _is_uuid(column):
+        return func.replace(func.lower(text), "-", "")
+    return text
+
+
+def canonical_id(value: Any) -> str:
+    """The stored ``resource_id`` for a key value (matches :func:`id_text`)."""
+    if isinstance(value, uuid.UUID):
+        return value.hex
+    return str(value)
+
+
+def row_id(obj: Any) -> str:
+    """The canonical id of a loaded single-key row."""
+    identity = inspect(obj).identity
+    if not identity or len(identity) != 1:
+        raise ValueError("shared resources need a single-column primary key")
+    return canonical_id(identity[0])
+
+
+def active_share_clause(now: datetime | None = None) -> Any:
+    """Shares that have not expired, as of *now* (a bound value, not ``NOW()``)."""
+    moment = now or datetime.now(UTC)
+    return or_(ResourceShare.expires_at.is_(None), ResourceShare.expires_at > moment)
+
+
+def share_exists_for(
+    resource_type: str, id_col: Any
+) -> Callable[[ResourcePrincipal, str], Any | None]:
+    """A ``share_exists`` factory for ``OwnedResourcePolicy``.
+
+    Correlated on *id_col*; tenant scoping comes from the share table's
+    ``MultiTenantMixin`` filter, and expired shares never match.
+    """
+    key = id_text(id_col)
+
+    def share_exists(principal: ResourcePrincipal, action: str) -> Any | None:
+        roles = roles_granting(action)
+        if not roles or principal.user_id is None:
+            return None
+        return exists(
+            select(ResourceShare.id).where(
+                ResourceShare.resource_type == resource_type,
+                ResourceShare.resource_id == key,
+                ResourceShare.subject_type == SUBJECT_USER,
+                ResourceShare.subject_id == principal.user_id,
+                ResourceShare.role.in_(roles),
+                active_share_clause(),
+            )
+        )
+
+    return share_exists
+
+
+__all__ = [
+    "active_share_clause",
+    "canonical_id",
+    "id_text",
+    "roles_granting",
+    "row_id",
+    "share_exists_for",
+]
diff --git a/modules/sharing/sharing/present.py b/modules/sharing/sharing/present.py
new file mode 100644
index 000000000..00df21c75
--- /dev/null
+++ b/modules/sharing/sharing/present.py
@@ -0,0 +1,41 @@
+"""Turn share rows into ``ShareOut`` with user labels from the directory."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from datetime import UTC, datetime
+from typing import Any
+
+from simple_module_core.user_directory import UserDirectory, resolve_user_labels
+
+from sharing.contracts.schemas import ShareOut
+from sharing.models import ResourceShare
+
+
+def _expired(share: ResourceShare, now: datetime) -> bool:
+    if share.expires_at is None:
+        return False
+    expires = share.expires_at
+    if expires.tzinfo is None:
+        expires = expires.replace(tzinfo=UTC)
+    return expires <= now
+
+
+async def present_shares(
+    directory: UserDirectory, db: Any, shares: Sequence[ResourceShare]
+) -> list[ShareOut]:
+    """One batched directory lookup for every subject and granter on the page."""
+    ids = [s.subject_id for s in shares] + [s.granted_by for s in shares]
+    labels = await resolve_user_labels(directory, db, ids)
+    now = datetime.now(UTC)
+    return [
+        ShareOut.model_validate(
+            share,
+            update={
+                "subject_label": labels.get(share.subject_id),
+                "granted_by_label": labels.get(share.granted_by),
+                "expired": _expired(share, now),
+            },
+        )
+        for share in shares
+    ]
diff --git a/modules/sharing/sharing/py.typed b/modules/sharing/sharing/py.typed
new file mode 100644
index 000000000..e69de29bb
diff --git a/modules/sharing/sharing/service.py b/modules/sharing/sharing/service.py
new file mode 100644
index 000000000..032cdd218
--- /dev/null
+++ b/modules/sharing/sharing/service.py
@@ -0,0 +1,158 @@
+"""Grant, revoke and list shares (GH #526).
+
+Every grant is checked three ways: the resource type is registered, the
+granter passes the owning module's policy for ``share`` on that row, and the
+grantee is someone the user directory knows. Rows are tenant-scoped by
+``MultiTenantMixin``; revoking hard-deletes.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime
+from typing import Any
+
+from simple_module_core.resources import (
+    ACTION_SHARE,
+    ResourcePrincipal,
+    ResourceType,
+    ResourceTypeRegistry,
+)
+from simple_module_core.user_directory import UserDirectory
+from simple_module_db.resource_policy import load_authorized
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlmodel import select
+
+from sharing.constants import (
+    ERR_BAD_ROLE,
+    ERR_EXPIRED,
+    ERR_NOT_FOUND,
+    ERR_SELF,
+    ERR_UNKNOWN_GRANTEE,
+    ERR_UNKNOWN_TYPE,
+    PERM_MANAGE,
+    SUBJECT_USER,
+)
+from sharing.contracts.schemas import ShareGrant
+from sharing.models import ResourceShare
+from sharing.policy import row_id
+
+
+class SharingError(Exception):
+    """A refused share operation, with the HTTP status it maps to."""
+
+    def __init__(self, status_code: int, detail: str) -> None:
+        super().__init__(detail)
+        self.status_code = status_code
+        self.detail = detail
+
+
+def _aware(value: datetime) -> datetime:
+    return value if value.tzinfo is not None else value.replace(tzinfo=UTC)
+
+
+class SharingService:
+    def __init__(
+        self, db: AsyncSession, registry: ResourceTypeRegistry, directory: UserDirectory
+    ) -> None:
+        self.db = db
+        self.registry = registry
+        self.directory = directory
+
+    def _type(self, name: str) -> ResourceType:
+        resource_type = self.registry.get(name)
+        if resource_type is None:
+            raise SharingError(422, ERR_UNKNOWN_TYPE)
+        return resource_type
+
+    async def _authorize(
+        self, principal: ResourcePrincipal, resource_type: ResourceType, resource_id: str
+    ) -> Any:
+        """The resource row if *principal* may share it: 404 if invisible, 403 if not."""
+        try:
+            stmt = resource_type.select_by_id(resource_id)
+        except ValueError:
+            raise SharingError(404, ERR_NOT_FOUND) from None
+        row, allowed = await load_authorized(
+            self.db, resource_type.policy, principal, ACTION_SHARE, stmt
+        )
+        if row is None:
+            raise SharingError(404, ERR_NOT_FOUND)
+        if not allowed:
+            raise SharingError(403, ERR_NOT_FOUND)
+        return row
+
+    async def grant(self, principal: ResourcePrincipal, data: ShareGrant) -> ResourceShare:
+        resource_type = self._type(data.resource_type)
+        if data.role not in resource_type.shareable_actions:
+            raise SharingError(422, ERR_BAD_ROLE)
+        if data.expires_at is not None and _aware(data.expires_at) <= datetime.now(UTC):
+            raise SharingError(422, ERR_EXPIRED)
+        row = await self._authorize(principal, resource_type, data.resource_id)
+        found = await self.directory.get_many(self.db, [data.subject_id])
+        grantee = found.get(data.subject_id)
+        if grantee is None:
+            raise SharingError(422, ERR_UNKNOWN_GRANTEE)
+        if grantee.id == principal.user_id:
+            raise SharingError(422, ERR_SELF)
+        resource_id = row_id(row)
+        share = await self._existing(data.resource_type, resource_id, grantee.id)
+        if share is None:
+            share = ResourceShare(
+                resource_type=data.resource_type,
+                resource_id=resource_id,
+                subject_type=SUBJECT_USER,
+                subject_id=grantee.id,
+                role=data.role,
+                granted_by=principal.user_id or "",
+            )
+            self.db.add(share)
+        share.role = data.role
+        share.expires_at = data.expires_at
+        share.granted_by = principal.user_id or ""
+        await self.db.flush()
+        return share
+
+    async def _existing(self, rtype: str, rid: str, subject_id: str) -> ResourceShare | None:
+        stmt = select(ResourceShare).where(
+            ResourceShare.resource_type == rtype,
+            ResourceShare.resource_id == rid,
+            ResourceShare.subject_type == SUBJECT_USER,
+            ResourceShare.subject_id == subject_id,
+        )
+        return (await self.db.execute(stmt)).scalars().first()
+
+    async def revoke(self, principal: ResourcePrincipal, share_id: uuid.UUID) -> None:
+        """Delete a share: an admin, its grantee (leaving), or whoever may share the row."""
+        share = (
+            (await self.db.execute(select(ResourceShare).where(ResourceShare.id == share_id)))
+            .scalars()
+            .first()
+        )
+        if share is None:
+            raise SharingError(404, ERR_NOT_FOUND)
+        if not principal.has(PERM_MANAGE) and share.subject_id != principal.user_id:
+            resource_type = self.registry.get(share.resource_type)
+            if resource_type is None:
+                raise SharingError(404, ERR_NOT_FOUND)
+            await self._authorize(principal, resource_type, share.resource_id)
+        await self.db.delete(share)
+        await self.db.flush()
+
+    async def for_resource(
+        self, principal: ResourcePrincipal, rtype: str, resource_id: str
+    ) -> list[ResourceShare]:
+        """Every share on one row (expired included), for whoever may share it."""
+        row = await self._authorize(principal, self._type(rtype), resource_id)
+        stmt = (
+            select(ResourceShare)
+            .where(
+                ResourceShare.resource_type == rtype,
+                ResourceShare.resource_id == row_id(row),
+            )
+            .order_by(ResourceShare.created_at)
+        )
+        return list((await self.db.execute(stmt)).scalars())
+
+
+__all__ = ["SharingError", "SharingService"]
diff --git a/modules/sharing/sharing/services.py b/modules/sharing/sharing/services.py
new file mode 100644
index 000000000..d363c4f90
--- /dev/null
+++ b/modules/sharing/sharing/services.py
@@ -0,0 +1,22 @@
+"""Module-scoped state container.
+
+Stored as ``app.state.sharing`` by
+:meth:`SharingModule.register_settings`.
+
+Not frozen — ``on_startup`` may set fields that depend on the DB or
+other framework services. Convention: set once during boot, treat as
+read-only after.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from sharing.settings import SharingSettings
+
+
+@dataclass
+class SharingServices:
+    """Sharing module singletons."""
+
+    settings: SharingSettings
diff --git a/modules/sharing/sharing/settings.py b/modules/sharing/sharing/settings.py
new file mode 100644
index 000000000..a30e37177
--- /dev/null
+++ b/modules/sharing/sharing/settings.py
@@ -0,0 +1,17 @@
+"""Sharing module settings (DB-backed).
+
+Values come from the pydantic defaults below at boot, then get hydrated from
+the settings table by the hosting lifespan before module ``on_startup`` runs
+(``register_module_settings`` in ``module.py`` records the class).
+``DbBackedSettings`` reads no environment variables: the DB is the only
+source. Add fields here as the module grows.
+"""
+
+from __future__ import annotations
+
+from pydantic_settings import SettingsConfigDict
+from simple_module_core.settings_base import DbBackedSettings
+
+
+class SharingSettings(DbBackedSettings):
+    model_config = SettingsConfigDict(extra="ignore")
diff --git a/modules/sharing/tests/_sharing_support.py b/modules/sharing/tests/_sharing_support.py
new file mode 100644
index 000000000..c6f28d0ad
--- /dev/null
+++ b/modules/sharing/tests/_sharing_support.py
@@ -0,0 +1,67 @@
+"""A test-only resource type for the sharing tests."""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Collection
+from typing import Any
+
+from sharing.policy import share_exists_for
+from simple_module_core.resources import ResourceType, ResourceTypeRegistry
+from simple_module_core.user_directory import DirectoryUser
+from simple_module_db.resource_policy import OwnedResourcePolicy, select_by_id
+from sqlmodel import Field, SQLModel
+
+NOTE_TYPE = "sharing_test.note"
+BYPASS = "sharing_test.manage"
+
+
+class SharingTestNote(SQLModel, table=True):
+    __tablename__ = "sharing_test_note"
+    __table_args__ = {"extend_existing": True}
+    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
+    owner_id: uuid.UUID
+    title: str = ""
+
+
+NOTE_POLICY = OwnedResourcePolicy(
+    SharingTestNote.owner_id,
+    bypass_perm=BYPASS,
+    share_exists=share_exists_for(NOTE_TYPE, SharingTestNote.id),
+)
+
+
+def register_note_type(registry: ResourceTypeRegistry) -> None:
+    if NOTE_TYPE not in registry:
+        registry.register(
+            ResourceType(
+                name=NOTE_TYPE, policy=NOTE_POLICY, select_by_id=select_by_id(SharingTestNote)
+            )
+        )
+
+
+async def create_note_table(conn: Any) -> None:
+    await conn.run_sync(lambda c: SharingTestNote.__table__.create(c, checkfirst=True))
+
+
+class FakeDirectory:
+    """Knows exactly the ids it was given."""
+
+    entity_type = None
+
+    def __init__(self, *ids: str) -> None:
+        self.users = {i: DirectoryUser(id=i, email=f"{i[:6]}@example.com") for i in ids}
+
+    async def get_many(
+        self, db: Any, ids: Collection[str], *, with_roles: bool = False
+    ) -> dict[str, DirectoryUser]:
+        return {i: self.users[i] for i in ids if i in self.users}
+
+    async def search(self, db: Any, term: str | None, *, limit: int) -> list[DirectoryUser]:
+        return list(self.users.values())[:limit]
+
+    def match_ids(self, term: str) -> Any | None:
+        return None
+
+    async def stats(self, db: Any, *, active_window: Any) -> Any:
+        return None
diff --git a/modules/sharing/tests/test_sharing_http.py b/modules/sharing/tests/test_sharing_http.py
new file mode 100644
index 000000000..89e212fa4
--- /dev/null
+++ b/modules/sharing/tests/test_sharing_http.py
@@ -0,0 +1,103 @@
+"""Sharing over HTTP: grant/list/revoke API and the admin page (GH #526)."""
+
+from __future__ import annotations
+
+import uuid
+
+import pytest
+from _sharing_support import NOTE_TYPE, SharingTestNote, create_note_table, register_note_type
+from simple_module_core.tenancy import TenantRole
+from simple_module_test.tenant_client import session_client
+
+SHARES = "/api/sharing/shares"
+INERTIA = {"X-Inertia": "true", "Accept": "application/json"}
+
+
+@pytest.fixture
+async def note_app(app):
+    register_note_type(app.state.sm.resource_types)
+    async with app.state.sm.db.engine.begin() as conn:
+        await create_note_table(conn)
+    return app
+
+
+async def _note(app, owner_id: str) -> str:
+    async with app.state.sm.db.session_factory() as session:
+        note = SharingTestNote(owner_id=uuid.UUID(owner_id), title="n")
+        session.add(note)
+        await session.commit()
+        return str(note.id)
+
+
+def _body(note_id: str, subject_id: str, **kw) -> dict:
+    return {"resource_type": NOTE_TYPE, "resource_id": note_id, "subject_id": subject_id, **kw}
+
+
+async def test_owner_grants_lists_and_revokes(note_app, tenant_client):
+    async with (
+        tenant_client(TenantRole.OWNER) as owner,
+        tenant_client(TenantRole.MEMBER, tenant_id=owner.tenant_id) as friend,
+    ):
+        note_id = await _note(note_app, owner.user_id)
+        resp = await owner.client.post(SHARES, json=_body(note_id, friend.user_id))
+        assert resp.status_code == 201, resp.text
+        share = resp.json()
+        assert share["subject_label"] and share["role"] == "view"
+
+        query = {"resource_type": NOTE_TYPE, "resource_id": note_id}
+        listed = await owner.client.get(SHARES, params=query)
+        assert [s["id"] for s in listed.json()] == [share["id"]]
+        assert (await friend.client.get(SHARES, params=query)).status_code == 403
+
+        gone = await owner.client.delete(f"{SHARES}/{share['id']}")
+        assert gone.status_code == 204
+        assert (await owner.client.get(SHARES, params=query)).json() == []
+
+
+async def test_grant_refusals(note_app, tenant_client):
+    async with tenant_client(TenantRole.OWNER) as owner, tenant_client() as outsider:
+        note_id = await _note(note_app, owner.user_id)
+        refused = await outsider.client.post(SHARES, json=_body(note_id, owner.user_id))
+        assert refused.status_code == 404
+        unknown_type = {**_body(note_id, outsider.user_id), "resource_type": "nope.thing"}
+        assert (await owner.client.post(SHARES, json=unknown_type)).status_code == 422
+        ghost = _body(note_id, str(uuid.uuid4()))
+        assert (await owner.client.post(SHARES, json=ghost)).status_code == 422
+
+
+async def test_admin_page_lists_tenant_shares(note_app, tenant_client):
+    from tenants.constants import SESSION_ACTIVE_TENANT
+    from tenants.models import Membership
+    from tenants.resolver import forget
+    from users.bootstrap import create_admin
+
+    async with tenant_client(TenantRole.OWNER) as owner:
+        async with tenant_client(TenantRole.MEMBER, tenant_id=owner.tenant_id) as friend:
+            note_id = await _note(note_app, owner.user_id)
+            await owner.client.post(SHARES, json=_body(note_id, friend.user_id))
+        async with note_app.state.sm.db.session_factory() as session:
+            admin = await create_admin(
+                session, email="share-admin@example.com", password="pw-12345"
+            )
+            admin_id = str(admin.user.id)
+            session.add(
+                Membership(
+                    tenant_id=owner.tenant_id,
+                    user_id=admin_id,
+                    role=TenantRole.OWNER,
+                    email="share-admin@example.com",
+                )
+            )
+            await session.commit()
+        forget(admin_id)
+        data = {"user_id": admin_id, SESSION_ACTIVE_TENANT: owner.tenant_id}
+        async with session_client(note_app, data) as client:
+            resp = await client.get("/admin/sharing/", headers=INERTIA)
+            assert resp.status_code == 200, resp.text
+            props = resp.json()["props"]
+            assert props["total"] == 1 and props["can_revoke"] is True
+            share_id = props["shares"][0]["id"]
+            revoked = await client.post(f"/admin/sharing/{share_id}/revoke")
+            assert revoked.status_code == 303
+        # A plain tenant owner holds sharing.share but not the admin page.
+        assert (await owner.client.get("/admin/sharing/")).status_code == 403
diff --git a/modules/sharing/tests/test_sharing_service.py b/modules/sharing/tests/test_sharing_service.py
new file mode 100644
index 000000000..368fc8ff3
--- /dev/null
+++ b/modules/sharing/tests/test_sharing_service.py
@@ -0,0 +1,145 @@
+"""SharingService: grant validation, expiry, revoke, tenant isolation (GH #526)."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime, timedelta
+
+import pytest
+from _sharing_support import (
+    NOTE_POLICY,
+    NOTE_TYPE,
+    FakeDirectory,
+    SharingTestNote,
+    create_note_table,
+    register_note_type,
+)
+from sharing.contracts.schemas import ShareGrant
+from sharing.models import ResourceShare
+from sharing.service import SharingError, SharingService
+from simple_module_core.resources import (
+    ACTION_EDIT,
+    ACTION_SHARE,
+    ACTION_VIEW,
+    ResourcePrincipal,
+    ResourceTypeRegistry,
+)
+from simple_module_db.tenancy import tenant_context
+from sqlmodel import select
+
+OWNER, FRIEND, STRANGER = (str(uuid.UUID(int=n)) for n in (1, 2, 3))
+
+
+def _who(user_id: str) -> ResourcePrincipal:
+    return ResourcePrincipal(user_id=user_id)
+
+
+@pytest.fixture
+async def env(db_session):
+    await create_note_table(await db_session.connection())
+    note = SharingTestNote(owner_id=uuid.UUID(OWNER), title="n")
+    db_session.add(note)
+    await db_session.flush()
+    registry = ResourceTypeRegistry()
+    register_note_type(registry)
+    service = SharingService(db_session, registry, FakeDirectory(OWNER, FRIEND, STRANGER))
+    return service, str(note.id)
+
+
+async def _visible(session, user_id: str, action: str = ACTION_VIEW) -> list[str]:
+    stmt = NOTE_POLICY.filter(_who(user_id), action, select(SharingTestNote))
+    return [n.title for n in (await session.execute(stmt)).scalars()]
+
+
+def _grant(note_id: str, **kw) -> ShareGrant:
+    return ShareGrant(resource_type=NOTE_TYPE, resource_id=note_id, subject_id=FRIEND, **kw)
+
+
+async def _refused(coro, status: int) -> None:
+    with pytest.raises(SharingError) as info:
+        await coro
+    assert info.value.status_code == status
+
+
+async def test_grant_makes_row_visible_to_grantee_only(env):
+    service, note_id = env
+    with tenant_context("t1"):
+        assert await _visible(service.db, FRIEND) == []
+        share = await service.grant(_who(OWNER), _grant(note_id))
+        assert share.resource_id == uuid.UUID(note_id).hex
+        assert await _visible(service.db, FRIEND) == ["n"]
+        assert await _visible(service.db, FRIEND, ACTION_EDIT) == []
+        assert await _visible(service.db, STRANGER) == []
+
+
+async def test_edit_role_and_regrant_updates_in_place(env):
+    service, note_id = env
+    with tenant_context("t1"):
+        await service.grant(_who(OWNER), _grant(note_id))
+        await service.grant(_who(OWNER), _grant(note_id, role=ACTION_EDIT))
+        rows = (await service.db.execute(select(ResourceShare))).scalars().all()
+        assert [r.role for r in rows] == [ACTION_EDIT]
+        assert await _visible(service.db, FRIEND, ACTION_EDIT) == ["n"]
+
+
+async def test_expired_share_hides_the_row(env):
+    service, note_id = env
+    with tenant_context("t1"):
+        share = await service.grant(_who(OWNER), _grant(note_id))
+        share.expires_at = datetime.now(UTC) - timedelta(minutes=1)
+        await service.db.flush()
+        assert await _visible(service.db, FRIEND) == []
+
+
+async def test_share_from_another_tenant_does_not_apply(env):
+    service, note_id = env
+    with tenant_context("t1"):
+        await service.grant(_who(OWNER), _grant(note_id))
+    with tenant_context("t2"):
+        assert await _visible(service.db, FRIEND) == []
+        await _refused(service.revoke(_who(OWNER), uuid.uuid4()), 404)
+
+
+async def test_grant_validation(env):
+    service, note_id = env
+    with tenant_context("t1"):
+        bad_type = ShareGrant(resource_type="nope.thing", resource_id=note_id, subject_id=FRIEND)
+        await _refused(service.grant(_who(OWNER), bad_type), 422)
+        await _refused(service.grant(_who(STRANGER), _grant(note_id)), 404)
+        unknown = _grant(note_id).model_copy(update={"subject_id": str(uuid.uuid4())})
+        await _refused(service.grant(_who(OWNER), unknown), 422)
+        await _refused(service.grant(_who(OWNER), _grant(note_id, role=ACTION_SHARE)), 422)
+        past = datetime.now(UTC) - timedelta(days=1)
+        await _refused(service.grant(_who(OWNER), _grant(note_id, expires_at=past)), 422)
+        await _refused(service.grant(_who(OWNER), _grant("not-a-uuid")), 404)
+        to_self = _grant(note_id).model_copy(update={"subject_id": OWNER})
+        await _refused(service.grant(_who(OWNER), to_self), 422)
+
+
+async def test_viewer_may_not_reshare(env):
+    service, note_id = env
+    with tenant_context("t1"):
+        await service.grant(_who(OWNER), _grant(note_id))
+        reshare = _grant(note_id).model_copy(update={"subject_id": STRANGER})
+        await _refused(service.grant(_who(FRIEND), reshare), 403)
+
+
+async def test_revoke_hard_deletes(env):
+    service, note_id = env
+    with tenant_context("t1"):
+        share = await service.grant(_who(OWNER), _grant(note_id))
+        await _refused(service.revoke(_who(STRANGER), share.id), 404)
+        await service.revoke(_who(OWNER), share.id)
+        stmt = select(ResourceShare).execution_options(include_deleted=True)
+        assert (await service.db.execute(stmt)).scalars().all() == []
+
+
+async def test_grantee_may_leave_and_owner_lists(env):
+    service, note_id = env
+    with tenant_context("t1"):
+        share = await service.grant(_who(OWNER), _grant(note_id))
+        listed = await service.for_resource(_who(OWNER), NOTE_TYPE, note_id)
+        assert [s.id for s in listed] == [share.id]
+        await _refused(service.for_resource(_who(FRIEND), NOTE_TYPE, note_id), 403)
+        await service.revoke(_who(FRIEND), share.id)
+        assert await _visible(service.db, FRIEND) == []
diff --git a/modules/sharing/tsconfig.json b/modules/sharing/tsconfig.json
new file mode 100644
index 000000000..c4cdd63fc
--- /dev/null
+++ b/modules/sharing/tsconfig.json
@@ -0,0 +1,10 @@
+{
+  "extends": "@simple-module-py/tsconfig/base.json",
+  "compilerOptions": {
+    "paths": {
+      "@/*": ["./sharing/*"],
+      "@simple-module-py/ui/*": ["../../node_modules/@simple-module-py/ui/src/*"]
+    }
+  },
+  "include": ["sharing/**/*.ts", "sharing/**/*.tsx"]
+}
diff --git a/package-lock.json b/package-lock.json
index 59a3bde83..a16e6cb95 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -220,6 +220,22 @@
         "react-dom": "^19.0.0"
       }
     },
+    "modules/sharing": {
+      "name": "@simple-module-py/sharing",
+      "version": "0.0.37",
+      "dependencies": {
+        "lucide-react": "^1.43.0"
+      },
+      "devDependencies": {
+        "@simple-module-py/tsconfig": "*"
+      },
+      "peerDependencies": {
+        "@inertiajs/react": "^3.7.0",
+        "@simple-module-py/ui": "*",
+        "react": "^19.0.0",
+        "react-dom": "^19.0.0"
+      }
+    },
     "modules/tenants": {
       "name": "@simple-module-py/tenants",
       "version": "0.0.37",
@@ -2800,6 +2816,10 @@
       "resolved": "modules/settings",
       "link": true
     },
+    "node_modules/@simple-module-py/sharing": {
+      "resolved": "modules/sharing",
+      "link": true
+    },
     "node_modules/@simple-module-py/tenants": {
       "resolved": "modules/tenants",
       "link": true
diff --git a/packages/i18n/src/generated-resources.ts b/packages/i18n/src/generated-resources.ts
index 774dcb122..1339bb2c6 100644
--- a/packages/i18n/src/generated-resources.ts
+++ b/packages/i18n/src/generated-resources.ts
@@ -812,6 +812,27 @@ export default {
     'settings.value_types_short.int': '',
     'settings.value_types_short.json': '',
     'settings.value_types_short.string': '',
+    'sharing.admin.description': '',
+    'sharing.admin.tenant_required': '',
+    'sharing.admin.title': '',
+    'sharing.audit.share': '',
+    'sharing.list.actions': '',
+    'sharing.list.empty_description': '',
+    'sharing.list.empty_title': '',
+    'sharing.list.expired': '',
+    'sharing.list.expires': '',
+    'sharing.list.granted_by': '',
+    'sharing.list.never': '',
+    'sharing.list.resource': '',
+    'sharing.list.revoke': '',
+    'sharing.list.role': '',
+    'sharing.list.subject': '',
+    'sharing.nav.title': '',
+    'sharing.permission_group': '',
+    'sharing.revoke.cancel': '',
+    'sharing.revoke.confirm': '',
+    'sharing.revoke.description': '',
+    'sharing.revoke.title': '',
     'tenants.accept.accept_button': '',
     'tenants.accept.accepted_description': '',
     'tenants.accept.accepted_title': '',
diff --git a/packages/i18n/src/keys.generated.ts b/packages/i18n/src/keys.generated.ts
index 2cc9bd489..6cc90a32f 100644
--- a/packages/i18n/src/keys.generated.ts
+++ b/packages/i18n/src/keys.generated.ts
@@ -1055,6 +1055,39 @@ export const keys = {
       string: 'settings.value_types_short.string',
     },
   },
+  sharing: {
+    admin: {
+      description: 'sharing.admin.description',
+      tenant_required: 'sharing.admin.tenant_required',
+      title: 'sharing.admin.title',
+    },
+    audit: {
+      share: 'sharing.audit.share',
+    },
+    list: {
+      actions: 'sharing.list.actions',
+      empty_description: 'sharing.list.empty_description',
+      empty_title: 'sharing.list.empty_title',
+      expired: 'sharing.list.expired',
+      expires: 'sharing.list.expires',
+      granted_by: 'sharing.list.granted_by',
+      never: 'sharing.list.never',
+      resource: 'sharing.list.resource',
+      revoke: 'sharing.list.revoke',
+      role: 'sharing.list.role',
+      subject: 'sharing.list.subject',
+    },
+    nav: {
+      title: 'sharing.nav.title',
+    },
+    permission_group: 'sharing.permission_group',
+    revoke: {
+      cancel: 'sharing.revoke.cancel',
+      confirm: 'sharing.revoke.confirm',
+      description: 'sharing.revoke.description',
+      title: 'sharing.revoke.title',
+    },
+  },
   tenants: {
     accept: {
       accept_button: 'tenants.accept.accept_button',
diff --git a/pyproject.toml b/pyproject.toml
index 58cf2826b..dc77947e7 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -88,6 +88,7 @@ extra-paths = [
     "modules/tenants",
     "modules/api_tokens",
     "modules/mail",
+    "modules/sharing",
     "host",
     "scripts",
 ]
@@ -129,7 +130,7 @@ invalid-assignment = "ignore"
 
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
-testpaths = ["framework/cli/tests", "framework/core/tests", "framework/db/tests", "framework/hosting/tests", "framework/inertia/tests", "framework/testing/tests", "host/tests", "modules/auth/tests", "modules/dashboard/tests", "modules/users/tests", "modules/permissions/tests", "modules/background_tasks/tests", "modules/file_storage/tests", "modules/settings/tests", "modules/feature_flags/tests", "modules/keycloak/tests", "modules/audit_log/tests", "modules/branding/tests", "modules/site_lock/tests", "modules/tenants/tests", "modules/api_tokens/tests", "modules/mail/tests", "scripts/tests", "tests"]
+testpaths = ["framework/cli/tests", "framework/core/tests", "framework/db/tests", "framework/hosting/tests", "framework/inertia/tests", "framework/testing/tests", "host/tests", "modules/auth/tests", "modules/dashboard/tests", "modules/users/tests", "modules/permissions/tests", "modules/background_tasks/tests", "modules/file_storage/tests", "modules/settings/tests", "modules/feature_flags/tests", "modules/keycloak/tests", "modules/audit_log/tests", "modules/branding/tests", "modules/site_lock/tests", "modules/tenants/tests", "modules/api_tokens/tests", "modules/mail/tests", "modules/sharing/tests", "scripts/tests", "tests"]
 markers = [
     "e2e: end-to-end tests requiring a live browser",
     "perf: performance benchmarks (opt-in; run via `make bench`)",
diff --git a/uv.lock b/uv.lock
index c2ecc98f9..6f05dc8a8 100644
--- a/uv.lock
+++ b/uv.lock
@@ -27,6 +27,7 @@ members = [
     "simple-module-permissions",
     "simple-module-python",
     "simple-module-settings",
+    "simple-module-sharing",
     "simple-module-site-lock",
     "simple-module-tenants",
     "simple-module-test",
@@ -3284,6 +3285,7 @@ dependencies = [
     { name = "simple-module-mail" },
     { name = "simple-module-permissions" },
     { name = "simple-module-settings" },
+    { name = "simple-module-sharing" },
     { name = "simple-module-site-lock" },
     { name = "simple-module-tenants" },
 ]
@@ -3303,6 +3305,7 @@ requires-dist = [
     { name = "simple-module-mail", editable = "modules/mail" },
     { name = "simple-module-permissions", editable = "modules/permissions" },
     { name = "simple-module-settings", editable = "modules/settings" },
+    { name = "simple-module-sharing", editable = "modules/sharing" },
     { name = "simple-module-site-lock", editable = "modules/site_lock" },
     { name = "simple-module-tenants", editable = "modules/tenants" },
 ]
@@ -3495,6 +3498,25 @@ requires-dist = [
     { name = "typer", specifier = ">=0.12" },
 ]
 
+[[package]]
+name = "simple-module-sharing"
+version = "0.0.37"
+source = { editable = "modules/sharing" }
+dependencies = [
+    { name = "simple-module-core" },
+    { name = "simple-module-db" },
+    { name = "simple-module-hosting" },
+    { name = "simple-module-inertia" },
+]
+
+[package.metadata]
+requires-dist = [
+    { name = "simple-module-core", editable = "framework/core" },
+    { name = "simple-module-db", editable = "framework/db" },
+    { name = "simple-module-hosting", editable = "framework/hosting" },
+    { name = "simple-module-inertia", editable = "framework/inertia" },
+]
+
 [[package]]
 name = "simple-module-site-lock"
 version = "0.0.37"

From 0311ad245aad9a0d1838277d36d20fdfd4c928bf Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Thu, 22 Oct 2026 09:35:51 +0200
Subject: [PATCH 13/21] docs: resource access + sharing module pages, migration
 graph, changelog (#526)

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 CHANGELOG.md                |  2 +
 CLAUDE.md                   |  6 +--
 docs/.vitepress/config.ts   |  1 +
 docs/database/migrations.md |  4 +-
 docs/modules/index.md       |  3 +-
 docs/modules/sharing.md     | 84 +++++++++++++++++++++++++++++++++++++
 6 files changed, 95 insertions(+), 5 deletions(-)
 create mode 100644 docs/modules/sharing.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9b511f8b6..3a1fbb0a2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,8 @@ All notable changes to this project are documented in this file. The format is b
 - `host/client_app` no longer re-declares `@simple-module-py/ui`'s runtime dependencies, nor `@base-ui/react`, `@radix-ui/react-slot`, `autoprefixer` or `postcss` (nothing loaded them) (#521).
 
 ### Added
+- Resource-scoped access (#526): `simple_module_core.resources` (`ResourcePolicy` with `filter`/`can`, `ResourcePrincipal`, `ResourceType`, `ResourceTypeRegistry`) and a new `register_resource_types` hook (read at `app.state.sm.resource_types`); `simple_module_db.resource_policy.OwnedResourcePolicy` (owner OR public-for-view OR an injected `share_exists`, with a keyword-required bypass permission) so lists and `paginate()` counts are filtered in SQL; `simple_module_hosting.resource_deps.RequiresResource(policy, action, loader, permission=None)` loads rows only through the policy: invisible → 404, visible but not allowed → 403, and admits API tokens only when `permission=` is set. See `docs/framework/resource-access.md`.
+- New optional `sharing` module (`simple_module_sharing`, #526): tenant-scoped `sharing_resource_share` table (migration `f733c7938fd1`, a new root and head labelled `sharing`), `share_exists_for(...)` for `OwnedResourcePolicy`, grant/revoke/list API under `/api/sharing/shares` (validates the resource type, the granter's `share` right on the row and the grantee via the user directory; expiry checked in SQL; revoke hard-deletes) and an admin page at `/admin/sharing/` (en + de). **Release note:** register a PyPI pending publisher for `simple_module_sharing` before the next release.
 - Server-rendered `<head>` for Inertia pages (#535 step 1): `inertia.render(..., head=Head(title, description, canonical, robots, og, twitter, json_ld))` puts the tags in the first response so crawlers and link unfurlers see them without JS; they are also sent as the `_head` prop and re-emitted on client visits via Inertia's `serverHead` (`@simple-module-py/ui/lib/server-head`). URL fields are http(s)-only, JSON-LD cannot close its `<script>`. New `public_base_url` host setting (DB-backed, read per request, no restart) builds canonical / `og:url`; the request `Host` is never used. Both `index.html` templates updated. Body SSR remains open in #535.
 
 - `smpy docker add-worker` generates dedicated Python worker images with validated apt packages, optional extras, queue/module routing, and idempotent Compose includes (#540).
diff --git a/CLAUDE.md b/CLAUDE.md
index e08533da1..710a0da7f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -294,9 +294,9 @@ development and testing (`session_cookie_secure`).
 - **Migrations** live in `host/migrations/versions/`, never in module packages.
   `host/migrations/env.py` builds metadata from every installed module and runs
   `ensure_db_extensions` first. The history is **not** one linear chain: it has
-  two roots (`77162e7b184b` initial schema, `e36ab09c4a92` tenants) and four
-  heads (`audit_log`, `tenants`, `keycloak`, and the users trunk, which Alembic
-  reports as `api_tokens`). Apply with `upgrade heads` (what `make migrate`
+  three roots (`77162e7b184b` initial schema, `e36ab09c4a92` tenants,
+  `f733c7938fd1` sharing) and five heads (`audit_log`, `tenants`, `keycloak`,
+  `sharing`, and the users trunk, which Alembic reports as `api_tokens`). Apply with `upgrade heads` (what `make migrate`
   does); plain `revision --autogenerate` refuses with "Multiple heads", so name
   the branch:
 
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index 952d09110..6f22a79e8 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -194,6 +194,7 @@ export default defineConfig({
             { text: "audit_log", link: "/modules/audit_log" },
             { text: "site_lock", link: "/modules/site_lock" },
             { text: "mail", link: "/modules/mail" },
+            { text: "sharing", link: "/modules/sharing" },
             { text: "tenants", link: "/modules/tenants" },
             { text: "dashboard", link: "/modules/dashboard" },
           ],
diff --git a/docs/database/migrations.md b/docs/database/migrations.md
index 71f560fa4..89ecb2fe6 100644
--- a/docs/database/migrations.md
+++ b/docs/database/migrations.md
@@ -16,6 +16,7 @@ The history is **not** a single linear chain. It has several roots and several h
 |---|---|
 | `77162e7b184b` initial schema | the users trunk (also holds file_storage, background_tasks, api_tokens revisions) |
 | `e36ab09c4a92` tenants initial schema | tenants (`f1a9c3d7b2e4` head) |
+| `f733c7938fd1` sharing resource share | sharing (root and head) |
 
 | Head | Owning module | Label Alembic reports |
 |---|---|---|
@@ -23,6 +24,7 @@ The history is **not** a single linear chain. It has several roots and several h
 | `a7c2e91d4b58` | audit_log | `audit_log` |
 | `f1a9c3d7b2e4` | tenants | `tenants` |
 | `f6a3b9d2e8c4` | keycloak | `keycloak` |
+| `f733c7938fd1` | sharing | `sharing` |
 
 `audit_log` forks off the trunk at `41cf2c53660e`, and `keycloak` forks off the users revision `873ca2015033`.
 
@@ -30,7 +32,7 @@ A module's first migration sets `branch_labels = ("<module_name>",)`. Alembic **
 
 ### Known mislabels
 
-Only four of the revisions set `branch_labels` (`audit_log`, `api_tokens`, `keycloak`, `tenants`). The graph carries these defects; they are documented rather than rewritten, because changing labels on revisions that installed databases already applied is not worth the risk:
+Only five of the revisions set `branch_labels` (`audit_log`, `api_tokens`, `keycloak`, `tenants`, `sharing`). The graph carries these defects; they are documented rather than rewritten, because changing labels on revisions that installed databases already applied is not worth the risk:
 
 - `51b2058d8afd_api_tokens_initial` sits in the middle of the trunk, so every revision above it (file_storage, background_tasks including the outbox, and the users revisions through `c8e4f1a2b6d9`) reports the `api_tokens` label. The `api_tokens` head is therefore really a users revision.
 - `keycloak` branches off a users revision, so a Keycloak-only install still builds the users schema.
diff --git a/docs/modules/index.md b/docs/modules/index.md
index 8277fe3cb..aa6cfaee1 100644
--- a/docs/modules/index.md
+++ b/docs/modules/index.md
@@ -1,6 +1,6 @@
 # Bundled modules
 
-simple_module_python ships with fifteen first-party modules. Each is a regular Python package — same shape as a module you'd write yourself — registered through the `simple_module` entry point and discovered at boot. They are independent: install only what you need.
+simple_module_python ships with sixteen first-party modules. Each is a regular Python package — same shape as a module you'd write yourself — registered through the `simple_module` entry point and discovered at boot. They are independent: install only what you need.
 
 | Module | Depends on | What it provides |
 |---|---|---|
@@ -19,6 +19,7 @@ simple_module_python ships with fifteen first-party modules. Each is a regular P
 | [`tenants`](/modules/tenants) | `auth`, `settings` | SaaS organisations: tenants, many-to-many memberships with per-tenant roles, invitations, the membership-validated tenant resolver, and the entitlement/lifecycle seams billing plugs into. |
 | [`site_lock`](/modules/site_lock) | `settings`, `auth` | Optional site-wide shared-password gate for staging / pre-launch sites. Off by default. |
 | [`mail`](/modules/mail) | `settings` | Outgoing mail transport: SMTP (aiosmtplib) or a logging console backend, DB-backed settings, live reload, `mail.mailer` connection check. Other modules send through `simple_module_core.mail`. |
+| [`sharing`](/modules/sharing) | — | Optional generic share table for [resource-scoped access](/framework/resource-access): grant a user `view` / `edit` on one row of another module, with expiry; grant/revoke API and an admin page. |
 
 ## How modules are wired in
 
diff --git a/docs/modules/sharing.md b/docs/modules/sharing.md
new file mode 100644
index 000000000..a0dac4597
--- /dev/null
+++ b/docs/modules/sharing.md
@@ -0,0 +1,84 @@
+# sharing
+
+Optional generic share table for [resource-scoped access](/framework/resource-access).
+A module whose rows are owned by a user can let the owner share one row with
+another user (`view` or `edit`, optionally until a date) without shipping its
+own share model. Nothing depends on it: the framework only sees the
+`share_exists` factory a module passes to its `OwnedResourcePolicy`.
+
+## ModuleMeta
+
+| Field | Value |
+|---|---|
+| `name` | `Sharing` |
+| `route_prefix` | `/api/sharing` |
+| `view_prefix` | `/admin/sharing` |
+| `depends_on` | — |
+
+## Wiring a resource type
+
+```python
+from simple_module_core.resources import ResourceType
+from simple_module_db.resource_policy import OwnedResourcePolicy, select_by_id
+from sharing.policy import share_exists_for
+
+NOTE_TYPE = "notes.note"
+NOTE_POLICY = OwnedResourcePolicy(
+    Note.owner_id,
+    bypass_perm=PERM_NOTES_MANAGE,
+    share_exists=share_exists_for(NOTE_TYPE, Note.id),
+)
+
+
+class NotesModule(ModuleBase):
+    def register_resource_types(self, registry):
+        registry.register(
+            ResourceType(name=NOTE_TYPE, policy=NOTE_POLICY, select_by_id=select_by_id(Note))
+        )
+```
+
+A module that uses `sharing.policy` must list `Sharing` in `depends_on`.
+
+Roles are actions: `view` grants view; `edit` grants view and edit. A type
+limits what may be granted with `ResourceType.shareable_actions` (default
+`("view", "edit")`). Only the owner, or a holder of the policy's bypass
+permission, passes `can("share")` and may grant.
+
+## Routes
+
+| Method | Path | Permission | Notes |
+|---|---|---|---|
+| `POST` | `/api/sharing/shares` | `sharing.share` | Grant or update. 422 for an unknown type, role or grantee, or a past `expires_at`; 404 when the granter cannot see the row; 403 when they can see it but may not share it. |
+| `GET` | `/api/sharing/shares?resource_type=&resource_id=` | `sharing.share` | Every share on one row (expired included, flagged), for whoever may share it. |
+| `DELETE` | `/api/sharing/shares/{id}` | `sharing.share` | Hard delete. Allowed for whoever may share the row, the grantee (leaving the share), or `sharing.manage`. |
+| `GET` | `/admin/sharing/` | `sharing.view` | Admin page: every share in the active tenant, paginated, with user labels. |
+| `POST` | `/admin/sharing/{id}/revoke` | `sharing.manage` | Revoke from the admin page. |
+
+`sharing.share` is mapped to the `user` role and every tenant role; the row's
+policy still decides each request. API tokens need `sharing.share` in their
+scopes.
+
+## Model
+
+`sharing_resource_share` (`ResourceShare`, `MultiTenantMixin` + `AuditMixin`):
+`resource_type`, `resource_id` (canonical text: a UUID's 32-digit hex, an int's
+decimal), `subject_type` (`user`), `subject_id`, `role`, `granted_by`,
+`expires_at`. Unique on `(tenant_id, resource_type, resource_id, subject_type,
+subject_id)`, so re-granting updates the role and expiry in place. Shares are
+tenant-scoped: a share made in one tenant never applies in another. An expired
+share stays in the table (and on the admin page) but never matches the policy;
+the comparison is done in SQL against the current time. Revoking deletes the
+row.
+
+Audit entries link to `/admin/sharing/?share={id}` (`AuditLink.for_model`).
+
+## Migration
+
+`f733c7938fd1` creates the table. It is its own root and head
+(`branch_labels = ("sharing",)`), so `alembic downgrade sharing@base` drops
+only this table.
+
+## Publishing
+
+`simple_module_sharing` is a new PyPI name: register a pending publisher for it
+before the first release that includes it, or that release leg fails with 403.

From 22773413e956a0a456326c77c773d23d9752c4fb Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Thu, 22 Oct 2026 09:39:36 +0200
Subject: [PATCH 14/21] fix(audit): an INSERT is always audited; soft-delete
 flag is bookkeeping only for UPDATE (#557)

An INSERT setting only excluded columns or is_deleted was dropped as
excluded-only bookkeeping, and so also escaped refuse_unaudited_dml. Inserts
now always produce at least the summary row.

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 framework/db/simple_module_db/bulk_audit.py   |  9 +++++---
 framework/db/tests/_audit_models.py           |  9 ++++++++
 .../db/tests/test_db_bulk_audit_targets.py    | 21 +++++++++++++++++--
 3 files changed, 34 insertions(+), 5 deletions(-)

diff --git a/framework/db/simple_module_db/bulk_audit.py b/framework/db/simple_module_db/bulk_audit.py
index fbfbdfd34..30ef2e183 100644
--- a/framework/db/simple_module_db/bulk_audit.py
+++ b/framework/db/simple_module_db/bulk_audit.py
@@ -130,11 +130,14 @@ def _plan(execute_state: ORMExecuteState, cls: type) -> _Ctx | None:
     # An executemany UPDATE names rows by primary key; anywhere else a written
     # key is a change and is never treated as bookkeeping.
     skip = _excluded_fields(cls) | pk if many and execute_state.is_update else _excluded_fields(cls)
-    skip = skip | {_SOFT_DELETE_FLAG}
+    if execute_state.is_update:
+        skip = skip | {_SOFT_DELETE_FLAG}  # it picked the action above
     written = list(dict.fromkeys(k for row in rows for k in row))
     kept = [k for k in written if k not in skip]
-    if written and not kept and all(a == default for a in actions):
-        return None  # only excluded columns: bookkeeping, like a flush
+    # Only excluded columns: bookkeeping, like a flush. Never for an INSERT —
+    # new rows are always recorded, at least as the summary.
+    if execute_state.is_update and written and not kept and all(a == default for a in actions):
+        return None
     if many:
         changes = [{"field": k} for k in kept]
     else:
diff --git a/framework/db/tests/_audit_models.py b/framework/db/tests/_audit_models.py
index 5109304b8..eb718e2dd 100644
--- a/framework/db/tests/_audit_models.py
+++ b/framework/db/tests/_audit_models.py
@@ -57,3 +57,12 @@ class IntPKItem(AuditBase, AuditMixin, table=True):  # ty: ignore[unsupported-ba
     __tablename__ = "test_audit_int_pk_item"
     id: int | None = Field(default=None, primary_key=True)
     name: str = Field(max_length=100)
+
+
+class SecretSoftItem(AuditBase, SoftDeleteMixin, table=True):  # ty: ignore[unsupported-base]
+    """Every non-PK column is excluded, so an INSERT can set excluded columns only."""
+
+    __tablename__ = "test_audit_secret_soft_item"
+    __audit_exclude_fields__: ClassVar[set[str]] = {"secret"}
+    id: int | None = Field(default=None, primary_key=True)
+    secret: str = Field(default="", max_length=100)
diff --git a/framework/db/tests/test_db_bulk_audit_targets.py b/framework/db/tests/test_db_bulk_audit_targets.py
index d3fc9e2e3..260eeae4b 100644
--- a/framework/db/tests/test_db_bulk_audit_targets.py
+++ b/framework/db/tests/test_db_bulk_audit_targets.py
@@ -9,9 +9,9 @@
 from __future__ import annotations
 
 import pytest
-from _audit_models import AuditTestItem, PartialExcludeModel, SoftDeleteItem
+from _audit_models import AuditTestItem, PartialExcludeModel, SecretSoftItem, SoftDeleteItem
 from simple_module_db import UnauditedWriteError
-from sqlalchemy import bindparam, select, true, update
+from sqlalchemy import bindparam, insert, select, true, update
 
 
 async def _seed(session, recorder, *rows) -> list[int]:
@@ -147,3 +147,20 @@ async def test_strict_mode_sees_executemany_column_params(audited):
     with pytest.raises(UnauditedWriteError):
         await session.execute(stmt, [{"b_id": pid, "b_v": "h", "username": "y"}])
     await session.execute(stmt, [{"b_id": pid, "b_v": "h"}])  # excluded-only: allowed
+
+
+@pytest.mark.parametrize(
+    "values",
+    [{"is_deleted": True}, {"secret": "s"}, {"secret": "s", "deleted_by": "x"}],
+    ids=["flag-only", "excluded-only", "excluded-and-mixin"],
+)
+async def test_insert_of_excluded_columns_only_is_still_recorded(audited, values):
+    state, session, recorder = audited
+    await session.execute(insert(SecretSoftItem).values(**values))
+    assert [(r.action, r.entity_id) for r in recorder.records] == [("bulk_inserted", "*")]
+    fields = {c["field"]: c.get("new") for c in recorder.records[0].changes}
+    assert fields["rowcount"] == 1 and not {"secret", "is_deleted", "deleted_by"} & set(fields)
+    state.refuse_unaudited_dml = True
+    stmt = insert(SecretSoftItem).values(**values).execution_options(sm_audit=False)
+    with pytest.raises(UnauditedWriteError):
+        await session.execute(stmt)

From 5d1f57769527e7ca9ebcbf0fd77338083325a0e0 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Thu, 22 Oct 2026 09:44:18 +0200
Subject: [PATCH 15/21] fix(sharing): keep grantees and user labels inside the
 active tenant (#526)

On a multi-tenant app grant() now requires the grantee to be a member of
the active tenant and answers a non-member with the same 422 as an
unknown id (no cross-tenant enumeration); share listings only carry
directory labels for members. Membership is read through a new core seam,
simple_module_core.tenancy.tenant_member_ids (app.state.tenant_members,
published by tenants, using the caller's session); with no active tenant
or no membership store nobody qualifies. Single-tenant behaviour is
unchanged.

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 CHANGELOG.md                                  |  2 +-
 docs/modules/sharing.md                       | 11 +++
 framework/core/simple_module_core/tenancy.py  | 31 ++++++-
 modules/sharing/sharing/audience.py           | 44 ++++++++++
 modules/sharing/sharing/deps.py               |  8 +-
 modules/sharing/sharing/endpoints/api.py      |  8 +-
 modules/sharing/sharing/endpoints/views.py    |  4 +-
 modules/sharing/sharing/present.py            | 14 ++-
 modules/sharing/sharing/service.py            | 14 ++-
 .../tests/test_sharing_tenant_audience.py     | 87 +++++++++++++++++++
 modules/tenants/tenants/module.py             | 23 ++++-
 11 files changed, 231 insertions(+), 15 deletions(-)
 create mode 100644 modules/sharing/sharing/audience.py
 create mode 100644 modules/sharing/tests/test_sharing_tenant_audience.py

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3a1fbb0a2..633168532 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -18,7 +18,7 @@ All notable changes to this project are documented in this file. The format is b
 
 ### Added
 - Resource-scoped access (#526): `simple_module_core.resources` (`ResourcePolicy` with `filter`/`can`, `ResourcePrincipal`, `ResourceType`, `ResourceTypeRegistry`) and a new `register_resource_types` hook (read at `app.state.sm.resource_types`); `simple_module_db.resource_policy.OwnedResourcePolicy` (owner OR public-for-view OR an injected `share_exists`, with a keyword-required bypass permission) so lists and `paginate()` counts are filtered in SQL; `simple_module_hosting.resource_deps.RequiresResource(policy, action, loader, permission=None)` loads rows only through the policy: invisible → 404, visible but not allowed → 403, and admits API tokens only when `permission=` is set. See `docs/framework/resource-access.md`.
-- New optional `sharing` module (`simple_module_sharing`, #526): tenant-scoped `sharing_resource_share` table (migration `f733c7938fd1`, a new root and head labelled `sharing`), `share_exists_for(...)` for `OwnedResourcePolicy`, grant/revoke/list API under `/api/sharing/shares` (validates the resource type, the granter's `share` right on the row and the grantee via the user directory; expiry checked in SQL; revoke hard-deletes) and an admin page at `/admin/sharing/` (en + de). **Release note:** register a PyPI pending publisher for `simple_module_sharing` before the next release.
+- New optional `sharing` module (`simple_module_sharing`, #526): tenant-scoped `sharing_resource_share` table (migration `f733c7938fd1`, a new root and head labelled `sharing`), `share_exists_for(...)` for `OwnedResourcePolicy`, grant/revoke/list API under `/api/sharing/shares` (validates the resource type, the granter's `share` right on the row and the grantee via the user directory, which on a multi-tenant app must be a member of the active tenant: same error as an unknown id, and labels only for members; new core seam `simple_module_core.tenancy.tenant_member_ids` / `app.state.tenant_members`, published by `tenants`; expiry checked in SQL; revoke hard-deletes) and an admin page at `/admin/sharing/` (en + de). **Release note:** register a PyPI pending publisher for `simple_module_sharing` before the next release.
 - Server-rendered `<head>` for Inertia pages (#535 step 1): `inertia.render(..., head=Head(title, description, canonical, robots, og, twitter, json_ld))` puts the tags in the first response so crawlers and link unfurlers see them without JS; they are also sent as the `_head` prop and re-emitted on client visits via Inertia's `serverHead` (`@simple-module-py/ui/lib/server-head`). URL fields are http(s)-only, JSON-LD cannot close its `<script>`. New `public_base_url` host setting (DB-backed, read per request, no restart) builds canonical / `og:url`; the request `Host` is never used. Both `index.html` templates updated. Body SSR remains open in #535.
 
 - `smpy docker add-worker` generates dedicated Python worker images with validated apt packages, optional extras, queue/module routing, and idempotent Compose includes (#540).
diff --git a/docs/modules/sharing.md b/docs/modules/sharing.md
index a0dac4597..2846978db 100644
--- a/docs/modules/sharing.md
+++ b/docs/modules/sharing.md
@@ -58,6 +58,17 @@ permission, passes `can("share")` and may grant.
 policy still decides each request. API tokens need `sharing.share` in their
 scopes.
 
+## Tenancy
+
+On a multi-tenant app a grantee must be a member of the active tenant. A
+non-member gets the same `422 Unknown user` as an id that names nobody, so the
+API cannot be used to probe other tenants' accounts. User labels (subject and
+granter) are only filled in for members of the active tenant; anyone else is
+shown by raw id. Membership is read through
+`simple_module_core.tenancy.tenant_member_ids`, which the `tenants` module
+publishes as `app.state.tenant_members`. With no active tenant or no
+membership store, nobody qualifies. Single-tenant apps have no such check.
+
 ## Model
 
 `sharing_resource_share` (`ResourceShare`, `MultiTenantMixin` + `AuditMixin`):
diff --git a/framework/core/simple_module_core/tenancy.py b/framework/core/simple_module_core/tenancy.py
index 8320980d6..20a574d14 100644
--- a/framework/core/simple_module_core/tenancy.py
+++ b/framework/core/simple_module_core/tenancy.py
@@ -13,7 +13,7 @@
 
 from __future__ import annotations
 
-from collections.abc import Awaitable, Callable
+from collections.abc import Awaitable, Callable, Collection
 from enum import StrEnum
 from typing import Any
 
@@ -78,12 +78,41 @@ async def tenant_exists(app: Any, tenant_id: str) -> bool | None:
     return bool(await check(tenant_id))
 
 
+TenantMembers = Callable[[Any, str, Collection[str]], Awaitable[Collection[str]]]
+"""``async (db, tenant_id, user_ids) -> the subset of user_ids that are members``.
+
+``db`` is the caller's ``AsyncSession`` (typed ``Any``: core is SQLAlchemy-free),
+so the lookup joins the request's unit of work instead of opening a second one."""
+
+
+async def tenant_member_ids(
+    app: Any, db: Any, tenant_id: str, user_ids: Collection[str]
+) -> set[str] | None:
+    """Which of *user_ids* belong to *tenant_id*, or ``None`` when nobody can say.
+
+    The module that owns memberships (``tenants``) publishes
+    ``app.state.tenant_members`` (a :data:`TenantMembers`). Code that must not
+    reveal or act on accounts outside the active tenant (``sharing`` resolving
+    a grantee) asks through this without importing that module. ``None`` means
+    no membership store is installed; callers on a multi-tenant app treat it
+    as "nobody" (fail closed).
+    """
+    check: TenantMembers | None = getattr(app.state, "tenant_members", None)
+    if check is None:
+        return None
+    if not user_ids:
+        return set()
+    return set(await check(db, tenant_id, user_ids))
+
+
 __all__ = [
     "TENANT_ROLE_PREFIX",
     "TenancyMode",
     "TenantExists",
+    "TenantMembers",
     "TenantRole",
     "is_tenant_role",
     "tenant_exists",
+    "tenant_member_ids",
     "tenant_role",
 ]
diff --git a/modules/sharing/sharing/audience.py b/modules/sharing/sharing/audience.py
new file mode 100644
index 000000000..cea7e7d58
--- /dev/null
+++ b/modules/sharing/sharing/audience.py
@@ -0,0 +1,44 @@
+"""Which user ids a request may act on or name: the active tenant's members.
+
+On a multi-tenant app a grantee, and any user label shown, must belong to the
+active tenant; otherwise ``sharing`` would let a caller share with (and probe
+for) accounts in other tenants and read their directory labels. Membership is
+asked through ``simple_module_core.tenancy.tenant_member_ids`` (the
+``tenants`` module publishes it), so this module never imports ``tenants``.
+With no active tenant, or no membership store installed, nobody is in the
+audience (fail closed). A single-tenant app has no such boundary.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Collection
+from typing import Any
+
+from simple_module_core.tenancy import TenancyMode, tenant_member_ids
+from simple_module_db.tenancy import current_tenant_id
+from simple_module_hosting.tenancy import tenancy_mode
+
+
+class Audience:
+    """Filters user ids down to those the current request may see."""
+
+    def __init__(self, app: Any, db: Any) -> None:
+        self.app = app
+        self.db = db
+
+    async def visible(self, user_ids: Collection[str]) -> set[str]:
+        wanted = {uid for uid in user_ids if uid}
+        if not wanted or tenancy_mode(self.app) is not TenancyMode.MULTI:
+            return wanted
+        tenant_id = current_tenant_id.get()
+        if tenant_id is None:
+            return set()
+        members = await tenant_member_ids(self.app, self.db, tenant_id, wanted)
+        return members or set()
+
+
+class OpenAudience:
+    """Everyone is visible (single-tenant use, or tests without an app)."""
+
+    async def visible(self, user_ids: Collection[str]) -> set[str]:
+        return {uid for uid in user_ids if uid}
diff --git a/modules/sharing/sharing/deps.py b/modules/sharing/sharing/deps.py
index 3f2ef2d58..40377a14e 100644
--- a/modules/sharing/sharing/deps.py
+++ b/modules/sharing/sharing/deps.py
@@ -9,13 +9,19 @@
 from simple_module_db.deps import get_db
 from sqlalchemy.ext.asyncio import AsyncSession
 
+from sharing.audience import Audience
 from sharing.service import SharingError, SharingService
 
 
 async def get_sharing_service(
     request: Request, db: AsyncSession = Depends(get_db)
 ) -> SharingService:
-    return SharingService(db, request.app.state.sm.resource_types, get_user_directory(request.app))
+    return SharingService(
+        db,
+        request.app.state.sm.resource_types,
+        get_user_directory(request.app),
+        Audience(request.app, db),
+    )
 
 
 SharingServiceDep = Annotated[SharingService, Depends(get_sharing_service)]
diff --git a/modules/sharing/sharing/endpoints/api.py b/modules/sharing/sharing/endpoints/api.py
index 25d646305..987ad3d07 100644
--- a/modules/sharing/sharing/endpoints/api.py
+++ b/modules/sharing/sharing/endpoints/api.py
@@ -35,7 +35,9 @@ async def list_shares(
         shares = await service.for_resource(who, resource_type, resource_id)
     except SharingError as exc:
         raise http_error(exc) from None
-    return await present_shares(get_user_directory(request.app), service.db, shares)
+    return await present_shares(
+        get_user_directory(request.app), service.db, shares, service.audience
+    )
 
 
 @router.post("", response_model=ShareOut, status_code=201)
@@ -49,7 +51,9 @@ async def grant_share(
         share = await service.grant(who, data)
     except SharingError as exc:
         raise http_error(exc) from None
-    (out,) = await present_shares(get_user_directory(request.app), service.db, [share])
+    (out,) = await present_shares(
+        get_user_directory(request.app), service.db, [share], service.audience
+    )
     return out
 
 
diff --git a/modules/sharing/sharing/endpoints/views.py b/modules/sharing/sharing/endpoints/views.py
index 25ed6e705..017380a97 100644
--- a/modules/sharing/sharing/endpoints/views.py
+++ b/modules/sharing/sharing/endpoints/views.py
@@ -38,7 +38,9 @@ async def admin_index(
     )
     try:
         page = await paginate(service.db, stmt, params)
-        shares = await present_shares(get_user_directory(request.app), service.db, page.items)
+        shares = await present_shares(
+            get_user_directory(request.app), service.db, page.items, service.audience
+        )
         total, served, tenant_required = page.total, page.page, False
     except TenantIsolationError:
         # Strict tenancy with no active tenant: nothing to list.
diff --git a/modules/sharing/sharing/present.py b/modules/sharing/sharing/present.py
index 00df21c75..42a66095c 100644
--- a/modules/sharing/sharing/present.py
+++ b/modules/sharing/sharing/present.py
@@ -8,6 +8,7 @@
 
 from simple_module_core.user_directory import UserDirectory, resolve_user_labels
 
+from sharing.audience import Audience, OpenAudience
 from sharing.contracts.schemas import ShareOut
 from sharing.models import ResourceShare
 
@@ -22,11 +23,18 @@ def _expired(share: ResourceShare, now: datetime) -> bool:
 
 
 async def present_shares(
-    directory: UserDirectory, db: Any, shares: Sequence[ResourceShare]
+    directory: UserDirectory,
+    db: Any,
+    shares: Sequence[ResourceShare],
+    audience: Audience | OpenAudience,
 ) -> list[ShareOut]:
-    """One batched directory lookup for every subject and granter on the page."""
+    """One batched directory lookup for every subject and granter on the page.
+
+    Only users in the request's *audience* (the active tenant's members) are
+    named; anyone else shows as their raw id, so no label crosses tenants.
+    """
     ids = [s.subject_id for s in shares] + [s.granted_by for s in shares]
-    labels = await resolve_user_labels(directory, db, ids)
+    labels = await resolve_user_labels(directory, db, await audience.visible(ids))
     now = datetime.now(UTC)
     return [
         ShareOut.model_validate(
diff --git a/modules/sharing/sharing/service.py b/modules/sharing/sharing/service.py
index 032cdd218..12167972e 100644
--- a/modules/sharing/sharing/service.py
+++ b/modules/sharing/sharing/service.py
@@ -23,6 +23,7 @@
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlmodel import select
 
+from sharing.audience import Audience, OpenAudience
 from sharing.constants import (
     ERR_BAD_ROLE,
     ERR_EXPIRED,
@@ -53,11 +54,16 @@ def _aware(value: datetime) -> datetime:
 
 class SharingService:
     def __init__(
-        self, db: AsyncSession, registry: ResourceTypeRegistry, directory: UserDirectory
+        self,
+        db: AsyncSession,
+        registry: ResourceTypeRegistry,
+        directory: UserDirectory,
+        audience: Audience | OpenAudience | None = None,
     ) -> None:
         self.db = db
         self.registry = registry
         self.directory = directory
+        self.audience = audience or OpenAudience()
 
     def _type(self, name: str) -> ResourceType:
         resource_type = self.registry.get(name)
@@ -89,9 +95,9 @@ async def grant(self, principal: ResourcePrincipal, data: ShareGrant) -> Resourc
         if data.expires_at is not None and _aware(data.expires_at) <= datetime.now(UTC):
             raise SharingError(422, ERR_EXPIRED)
         row = await self._authorize(principal, resource_type, data.resource_id)
-        found = await self.directory.get_many(self.db, [data.subject_id])
-        grantee = found.get(data.subject_id)
-        if grantee is None:
+        grantee = (await self.directory.get_many(self.db, [data.subject_id])).get(data.subject_id)
+        # One error for "no such user" and "not in your tenant": no enumeration.
+        if grantee is None or grantee.id not in await self.audience.visible([grantee.id]):
             raise SharingError(422, ERR_UNKNOWN_GRANTEE)
         if grantee.id == principal.user_id:
             raise SharingError(422, ERR_SELF)
diff --git a/modules/sharing/tests/test_sharing_tenant_audience.py b/modules/sharing/tests/test_sharing_tenant_audience.py
new file mode 100644
index 000000000..6bbeace2e
--- /dev/null
+++ b/modules/sharing/tests/test_sharing_tenant_audience.py
@@ -0,0 +1,87 @@
+"""Grantees and user labels stay inside the active tenant (GH #526 review)."""
+
+from __future__ import annotations
+
+import uuid
+
+import pytest
+from _sharing_support import NOTE_TYPE, SharingTestNote, create_note_table, register_note_type
+from sharing.models import ResourceShare
+from simple_module_core.tenancy import TenantRole, tenant_member_ids
+from simple_module_db.tenancy import tenant_context
+
+SHARES = "/api/sharing/shares"
+
+
+@pytest.fixture
+async def note_app(app):
+    register_note_type(app.state.sm.resource_types)
+    async with app.state.sm.db.engine.begin() as conn:
+        await create_note_table(conn)
+    return app
+
+
+async def _note(app, owner_id: str) -> str:
+    async with app.state.sm.db.session_factory() as session:
+        note = SharingTestNote(owner_id=uuid.UUID(owner_id), title="n")
+        session.add(note)
+        await session.commit()
+        return str(note.id)
+
+
+def _body(note_id: str, subject_id: str) -> dict:
+    return {"resource_type": NOTE_TYPE, "resource_id": note_id, "subject_id": subject_id}
+
+
+async def test_cross_tenant_grantee_gets_the_unknown_user_error(note_app, tenant_client):
+    async with tenant_client(TenantRole.OWNER) as owner, tenant_client() as outsider:
+        note_id = await _note(note_app, owner.user_id)
+        foreign = await owner.client.post(SHARES, json=_body(note_id, outsider.user_id))
+        ghost = await owner.client.post(SHARES, json=_body(note_id, str(uuid.uuid4())))
+        assert foreign.status_code == ghost.status_code == 422
+        assert foreign.json() == ghost.json()
+
+
+async def test_same_tenant_grantee_is_accepted_and_labelled(note_app, tenant_client):
+    async with (
+        tenant_client(TenantRole.OWNER) as owner,
+        tenant_client(TenantRole.MEMBER, tenant_id=owner.tenant_id) as friend,
+    ):
+        note_id = await _note(note_app, owner.user_id)
+        resp = await owner.client.post(SHARES, json=_body(note_id, friend.user_id))
+        assert resp.status_code == 201
+        assert resp.json()["subject_label"] and resp.json()["granted_by_label"]
+
+
+async def test_labels_of_users_outside_the_tenant_are_withheld(note_app, tenant_client):
+    async with tenant_client(TenantRole.OWNER) as owner, tenant_client() as outsider:
+        note_id = await _note(note_app, owner.user_id)
+        # A share whose subject is not a member (left the tenant, or legacy data).
+        async with note_app.state.sm.db.session_factory() as session:
+            with tenant_context(owner.tenant_id):
+                session.add(
+                    ResourceShare(
+                        resource_type=NOTE_TYPE,
+                        resource_id=uuid.UUID(note_id).hex,
+                        subject_id=outsider.user_id,
+                        role="view",
+                        granted_by=owner.user_id,
+                    )
+                )
+                await session.commit()
+        listed = await owner.client.get(
+            SHARES, params={"resource_type": NOTE_TYPE, "resource_id": note_id}
+        )
+        (share,) = listed.json()
+        assert share["subject_id"] == outsider.user_id
+        assert share["subject_label"] is None
+        assert share["granted_by_label"]
+
+
+async def test_tenant_member_ids_seam(note_app, tenant_client):
+    async with tenant_client(TenantRole.OWNER) as owner, tenant_client() as outsider:
+        async with note_app.state.sm.db.session_factory() as db:
+            found = await tenant_member_ids(
+                note_app, db, owner.tenant_id, [owner.user_id, outsider.user_id]
+            )
+        assert found == {owner.user_id}
diff --git a/modules/tenants/tenants/module.py b/modules/tenants/tenants/module.py
index 8efb5ad76..d4d7bccd7 100644
--- a/modules/tenants/tenants/module.py
+++ b/modules/tenants/tenants/module.py
@@ -12,7 +12,7 @@
 import importlib.resources
 import logging
 from pathlib import Path
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 from simple_module_core.menu import MenuItem, MenuRegistry, MenuSection
 from simple_module_core.module import ModuleBase, ModuleMeta
@@ -21,11 +21,13 @@
 from tenants import constants as c
 
 if TYPE_CHECKING:
+    from collections.abc import Collection
+
     from fastapi import APIRouter, FastAPI
     from simple_module_core.events import EventBus
     from simple_module_core.invalidation import InvalidationBus
     from simple_module_core.permissions import PermissionRegistry
-    from simple_module_core.tenancy import TenantExists
+    from simple_module_core.tenancy import TenantExists, TenantMembers
 
 logger = logging.getLogger(__name__)
 
@@ -41,6 +43,22 @@ async def exists(tenant_id: str) -> bool:
     return exists
 
 
+def _tenant_members() -> TenantMembers:
+    """The ``app.state.tenant_members`` callable core's ``tenant_member_ids()`` reads."""
+    from sqlmodel import col, select
+
+    from tenants.models import Membership
+
+    async def members(db: Any, tenant_id: str, user_ids: Collection[str]) -> set[str]:
+        wanted = list(dict.fromkeys(user_ids))
+        stmt = select(Membership.user_id).where(
+            Membership.tenant_id == tenant_id, col(Membership.user_id).in_(wanted)
+        )
+        return set((await db.execute(stmt)).scalars())
+
+    return members
+
+
 class TenantsModule(ModuleBase):
     meta = ModuleMeta(
         name=c.DISPLAY_NAME,
@@ -78,6 +96,7 @@ def register_settings(self, app: FastAPI) -> None:
         )
         app.state.tenant_resolver = resolve_tenant
         app.state.tenant_exists = _tenant_exists(app)
+        app.state.tenant_members = _tenant_members()
         register_inertia_shared_provider(app, tenant_shared_props)
 
     def register_exception_handlers(self, app: FastAPI) -> None:

From 12e4870370f4990eaa47ae9796442fadd85611b8 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Thu, 22 Oct 2026 09:58:05 +0200
Subject: [PATCH 16/21] refactor(optimize): drop dead head_markup, share pk
 formatting, default resource registry; scaffold app excludes SPA mounts

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 .../templates/host/client_app/app.tsx            | 13 +++++++++++--
 .../cli/tests/test_scaffold_app_tsx_spa_links.py |  9 +++++++++
 framework/db/simple_module_db/audit.py           | 16 +++++++++-------
 framework/db/simple_module_db/bulk_audit.py      | 10 +++-------
 .../simple_module_hosting/_registrations.py      |  7 ++++---
 .../hosting/simple_module_hosting/_spa_mount.py  |  5 ++---
 .../simple_module_hosting/host_settings.py       |  5 +++--
 .../tests/test_native_link_prefixes_strip.py     | 13 +++++++++++++
 framework/inertia/simple_module_inertia/head.py  |  6 +-----
 9 files changed, 55 insertions(+), 29 deletions(-)
 create mode 100644 framework/cli/tests/test_scaffold_app_tsx_spa_links.py
 create mode 100644 framework/hosting/tests/test_native_link_prefixes_strip.py

diff --git a/framework/cli/simple_module_cli/templates/host/client_app/app.tsx b/framework/cli/simple_module_cli/templates/host/client_app/app.tsx
index 661b68332..1859fdc92 100644
--- a/framework/cli/simple_module_cli/templates/host/client_app/app.tsx
+++ b/framework/cli/simple_module_cli/templates/host/client_app/app.tsx
@@ -2,7 +2,11 @@ import { createInertiaApp, router } from '@inertiajs/react';
 import { configureI18n, updateI18n } from '@simple-module-py/i18n';
 import { formatTitle, setTitleAppName } from '@simple-module-py/ui/lib/app-title';
 import { resolveServerHead } from '@simple-module-py/ui/lib/server-head';
-import { startSpaLinkInterception } from '@simple-module-py/ui/lib/spa-links';
+import {
+  isExcluded,
+  readNativePrefixes,
+  startSpaLinkInterception,
+} from '@simple-module-py/ui/lib/spa-links';
 import { initTheme } from '@simple-module-py/ui/lib/theme';
 import { createRoot } from 'react-dom/client';
 import { resolvePage } from './pages';
@@ -50,7 +54,12 @@ createInertiaApp({
     // renders author-entered URLs as plain <a href>, which the browser would
     // follow with a full document load. This app is client-rendered, so that
     // means a blank page until the bundle boots. Route them through Inertia.
-    startSpaLinkInterception();
+    // Legacy SPA mounts and `native_link_prefixes` stay full navigations.
+    let nativePrefixes = readNativePrefixes(props.initialPage.props);
+    router.on('navigate', (event) => {
+      nativePrefixes = readNativePrefixes(event.detail.page.props);
+    });
+    startSpaLinkInterception({ exclude: (url) => isExcluded(url, nativePrefixes) });
     createRoot(el).render(<App {...props} />);
   },
   progress: {
diff --git a/framework/cli/tests/test_scaffold_app_tsx_spa_links.py b/framework/cli/tests/test_scaffold_app_tsx_spa_links.py
new file mode 100644
index 000000000..92fb37407
--- /dev/null
+++ b/framework/cli/tests/test_scaffold_app_tsx_spa_links.py
@@ -0,0 +1,9 @@
+from simple_module_cli.scaffolding import create_host
+
+
+def test_scaffolded_app_excludes_spa_mounts_from_link_interception(tmp_path):
+    dest = tmp_path / "demo"
+    create_host(dest, name="demo-host", modules=[])
+    app_tsx = (dest / "client_app" / "app.tsx").read_text(encoding="utf-8")
+    assert "readNativePrefixes" in app_tsx
+    assert "startSpaLinkInterception({ exclude" in app_tsx
diff --git a/framework/db/simple_module_db/audit.py b/framework/db/simple_module_db/audit.py
index 145f6f0e6..6f6ea8724 100644
--- a/framework/db/simple_module_db/audit.py
+++ b/framework/db/simple_module_db/audit.py
@@ -83,6 +83,13 @@ def _excluded_fields(obj: object) -> frozenset[str]:
     return _EXCLUDED_MIXIN_FIELDS | per_model
 
 
+def format_pk(values: tuple | list) -> str:
+    """One primary-key rendering for ``entity_id``: bare value, or a tuple string."""
+    if len(values) == 1:
+        return str(values[0]) if values[0] is not None else ""
+    return str(tuple(values))
+
+
 def _entity_pk_str(obj: object) -> str:
     """Return the primary-key value(s) as a string."""
     inspector = sa_inspect(obj)
@@ -90,13 +97,8 @@ def _entity_pk_str(obj: object) -> str:
     if identity is None:
         # Pre-flush: fall back to the mapper-level key attrs
         mapper = inspector.mapper
-        vals = tuple(getattr(obj, col.key) for col in mapper.primary_key)
-        if len(vals) == 1:
-            return str(vals[0]) if vals[0] is not None else ""
-        return str(vals)
-    if len(identity) == 1:
-        return str(identity[0])
-    return str(identity)
+        return format_pk([getattr(obj, col.key) for col in mapper.primary_key])
+    return format_pk(identity)
 
 
 def _column_names(obj: object) -> list[str]:
diff --git a/framework/db/simple_module_db/bulk_audit.py b/framework/db/simple_module_db/bulk_audit.py
index 30ef2e183..ce34f1b39 100644
--- a/framework/db/simple_module_db/bulk_audit.py
+++ b/framework/db/simple_module_db/bulk_audit.py
@@ -34,7 +34,7 @@
 from sqlalchemy.orm import ORMExecuteState, Session
 
 from simple_module_db import model_registry as registry
-from simple_module_db.audit import AuditRecord, _excluded_fields, _serialize
+from simple_module_db.audit import AuditRecord, _excluded_fields, _serialize, format_pk
 from simple_module_db.bulk_audit_targets import _is_set, _shown, _targets
 from simple_module_db.query_filter import engine_policy
 from simple_module_db.tenancy import ALL_TENANTS_OPTION
@@ -74,10 +74,6 @@ def _target_class(execute_state: ORMExecuteState) -> type | None:
     return registry.classes_by_table.get(table) if table is not None else None
 
 
-def _pk_str(values: tuple | list) -> str:
-    return str(values[0]) if len(values) == 1 else str(tuple(values))
-
-
 class _Ctx:
     """What one audited statement records, built before it runs."""
 
@@ -161,7 +157,7 @@ def _prefetch_ids(execute_state: ORMExecuteState, cls: type, cap: int) -> list[s
     if execute_state.execution_options.get(ALL_TENANTS_OPTION):
         options[ALL_TENANTS_OPTION] = True
     rows = execute_state.session.execute(query.execution_options(**options)).all()
-    return [_pk_str(tuple(row)) for row in rows]
+    return [format_pk(tuple(row)) for row in rows]
 
 
 def _bulk_by_pk_ids(execute_state: ORMExecuteState, cls: type) -> list[str] | None:
@@ -172,7 +168,7 @@ def _bulk_by_pk_ids(execute_state: ORMExecuteState, cls: type) -> list[str] | No
     pk = [col.key for col in sa_inspect(cls).primary_key]
     if not all(all(k in row for k in pk) for row in params):
         return None
-    return [_pk_str([row[k] for k in pk]) for row in params]
+    return [format_pk([row[k] for k in pk]) for row in params]
 
 
 def _summary(ctx: _Ctx, stmt: Any, rowcount: Any, action: str) -> AuditRecord:
diff --git a/framework/hosting/simple_module_hosting/_registrations.py b/framework/hosting/simple_module_hosting/_registrations.py
index 7855895eb..e1a38a2d9 100644
--- a/framework/hosting/simple_module_hosting/_registrations.py
+++ b/framework/hosting/simple_module_hosting/_registrations.py
@@ -15,6 +15,7 @@
 from simple_module_core.cors import CorsPolicyRegistry
 from simple_module_core.deprecation import deprecate
 from simple_module_core.rate_limit import RateLimitRegistry
+from simple_module_core.resources import ResourceTypeRegistry
 
 if TYPE_CHECKING:
     from fastapi import FastAPI
@@ -54,7 +55,7 @@ def run_module_registrations(
     audit_link_registry,
     csp_registry,
     request_registries: RequestRegistries,
-    resource_type_registry=None,
+    resource_type_registry: ResourceTypeRegistry | None = None,
 ) -> None:
     """Invoke each module's registration hooks, in dependency order.
 
@@ -64,6 +65,7 @@ def run_module_registrations(
     ``on_startup``, say — belongs to no module in this loop, and inheriting
     the last one's name would be a lie.
     """
+    resource_type_registry = resource_type_registry or ResourceTypeRegistry()
     for mod in modules:
         mod.register_menu_items(menu_registry)
         mod.register_permissions(perm_registry)
@@ -83,8 +85,7 @@ def run_module_registrations(
         mod.register_csp_sources(csp_registry)
         mod.register_design_packs(design_pack_registry)
         mod.register_audit_links(audit_link_registry)
-        if resource_type_registry is not None:
-            mod.register_resource_types(resource_type_registry)
+        mod.register_resource_types(resource_type_registry)
 
     health_registry.set_owner("")
     setup_registry.set_owner("")
diff --git a/framework/hosting/simple_module_hosting/_spa_mount.py b/framework/hosting/simple_module_hosting/_spa_mount.py
index 3178f3a43..a0cfe36a6 100644
--- a/framework/hosting/simple_module_hosting/_spa_mount.py
+++ b/framework/hosting/simple_module_hosting/_spa_mount.py
@@ -125,9 +125,8 @@ def mount_spa_mounts(app: FastAPI, modules: list) -> None:
     registry = getattr(app.state, "public_routes", None)
     for mod in modules:
         for mount in mod.spa_mounts():
-            if not _mount(app, mod.meta.name, mount, registry):
-                continue
-            prefixes.append(mount.prefix)
+            if _mount(app, mod.meta.name, mount, registry):
+                prefixes.append(mount.prefix)
     app.state.spa_prefixes = tuple(prefixes)
 
 
diff --git a/framework/hosting/simple_module_hosting/host_settings.py b/framework/hosting/simple_module_hosting/host_settings.py
index 1bcb4e5c2..3e8c62c4c 100644
--- a/framework/hosting/simple_module_hosting/host_settings.py
+++ b/framework/hosting/simple_module_hosting/host_settings.py
@@ -216,10 +216,11 @@ def _check_rate(cls, value: str) -> str:
     @field_validator("native_link_prefixes", mode="after")
     @classmethod
     def _check_native_prefixes(cls, value: list[str]) -> list[str]:
-        for prefix in value:
+        cleaned = [prefix.strip() for prefix in value]
+        for prefix in cleaned:
             if not prefix.startswith("/"):
                 raise ValueError(f"native_link_prefixes entry {prefix!r} must start with '/'")
-        return [prefix.strip() for prefix in value]
+        return cleaned
 
     @field_validator("max_request_body_bytes", mode="after")
     @classmethod
diff --git a/framework/hosting/tests/test_native_link_prefixes_strip.py b/framework/hosting/tests/test_native_link_prefixes_strip.py
new file mode 100644
index 000000000..1a21eb004
--- /dev/null
+++ b/framework/hosting/tests/test_native_link_prefixes_strip.py
@@ -0,0 +1,13 @@
+import pytest
+from pydantic import ValidationError
+from simple_module_hosting.host_settings import HostSettings
+
+
+def test_native_prefixes_are_stripped_before_validation():
+    s = HostSettings(native_link_prefixes=[" /x", "/y "])
+    assert s.native_link_prefixes == ["/x", "/y"]
+
+
+def test_native_prefix_without_slash_still_rejected():
+    with pytest.raises(ValidationError):
+        HostSettings(native_link_prefixes=["x"])
diff --git a/framework/inertia/simple_module_inertia/head.py b/framework/inertia/simple_module_inertia/head.py
index eabe1b104..9ebf9e974 100644
--- a/framework/inertia/simple_module_inertia/head.py
+++ b/framework/inertia/simple_module_inertia/head.py
@@ -21,7 +21,7 @@
 from urllib.parse import urljoin, urlsplit
 
 from jinja2.utils import htmlsafe_json_dumps
-from markupsafe import Markup, escape
+from markupsafe import escape
 from pydantic import BaseModel, Field, field_validator, model_validator
 from starlette.requests import Request
 
@@ -155,7 +155,3 @@ def head_tags(head: Head, site: SiteInfo) -> list[str]:
             f'<script {_KEY_ATTR}="sm-jsonld-{index}" type="application/ld+json">{body}</script>'
         )
     return tags
-
-
-def head_markup(tags: list[str]) -> Markup:
-    return Markup("\n".join(tags))

From b338e8cd7f873ea880ffd683f5ee087a92c4a055 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Thu, 22 Oct 2026 09:59:20 +0200
Subject: [PATCH 17/21] fix(db): forward execute params to the bulk-audit
 prefetch; audit planning fails open (#557)

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 framework/db/simple_module_db/bulk_audit.py | 33 +++++++++++++++++++--
 framework/db/tests/test_db_bulk_audit.py    | 31 ++++++++++++++++++-
 2 files changed, 60 insertions(+), 4 deletions(-)

diff --git a/framework/db/simple_module_db/bulk_audit.py b/framework/db/simple_module_db/bulk_audit.py
index ce34f1b39..1fe7cf54a 100644
--- a/framework/db/simple_module_db/bulk_audit.py
+++ b/framework/db/simple_module_db/bulk_audit.py
@@ -32,6 +32,8 @@
 from sqlalchemy import inspect as sa_inspect
 from sqlalchemy import select
 from sqlalchemy.orm import ORMExecuteState, Session
+from sqlalchemy.sql.elements import BindParameter
+from sqlalchemy.sql.visitors import iterate
 
 from simple_module_db import model_registry as registry
 from simple_module_db.audit import AuditRecord, _excluded_fields, _serialize, format_pk
@@ -143,6 +145,15 @@ def _plan(execute_state: ORMExecuteState, cls: type) -> _Ctx | None:
     return ctx
 
 
+def _where_params(stmt: Any, params: Any) -> dict[str, Any] | None:
+    """The execute params the ``WHERE`` clause binds, so the prefetch can run it."""
+    where = getattr(stmt, "whereclause", None)
+    if where is None or not isinstance(params, dict):
+        return None
+    keys = {e.key for e in iterate(where) if isinstance(e, BindParameter)}
+    return {k: v for k, v in params.items() if k in keys} or None
+
+
 def _prefetch_ids(execute_state: ORMExecuteState, cls: type, cap: int) -> list[str]:
     """Primary keys of the rows the statement will touch, at most ``cap + 1``."""
     stmt = execute_state.statement
@@ -156,7 +167,9 @@ def _prefetch_ids(execute_state: ORMExecuteState, cls: type, cap: int) -> list[s
     options = {"include_deleted": True}
     if execute_state.execution_options.get(ALL_TENANTS_OPTION):
         options[ALL_TENANTS_OPTION] = True
-    rows = execute_state.session.execute(query.execution_options(**options)).all()
+    rows = execute_state.session.execute(
+        query.execution_options(**options), _where_params(stmt, execute_state.parameters)
+    ).all()
     return [format_pk(tuple(row)) for row in rows]
 
 
@@ -181,6 +194,15 @@ def _summary(ctx: _Ctx, stmt: Any, rowcount: Any, action: str) -> AuditRecord:
     return ctx.record(SUMMARY_ENTITY_ID, [*ctx.changes, *summary], action)
 
 
+def _plans_a_record(execute_state: ORMExecuteState, cls: type) -> bool:
+    """Whether the statement would be audited; a planning failure never refuses the write."""
+    try:
+        return _plan(execute_state, cls) is not None
+    except Exception:
+        logger.exception("Could not plan a bulk audit record for %s", cls.__name__)
+        return False
+
+
 def audit_statement(execute_state: ORMExecuteState) -> Any:
     """``do_orm_execute`` hook: audit statement DML on an audited model."""
     if not (execute_state.is_insert or execute_state.is_update or execute_state.is_delete):
@@ -193,7 +215,7 @@ def audit_statement(execute_state: ORMExecuteState) -> Any:
         return None
     policy = engine_policy(session)
     if execute_state.execution_options.get(AUDIT_OPTION, True) is False:
-        if _refuses_unaudited(policy) and _plan(execute_state, cls) is not None:
+        if _refuses_unaudited(policy) and _plans_a_record(execute_state, cls):
             raise UnauditedWriteError(
                 f"Unaudited {AUDIT_OPTION}=False write to audited model {cls.__name__}"
             )
@@ -212,7 +234,12 @@ def audit_statement(execute_state: ORMExecuteState) -> Any:
     ids = _bulk_by_pk_ids(execute_state, cls)
     by_row = ids is not None and len(ids) == len(ctx.row_actions)
     if ids is None and not (execute_state.is_insert or isinstance(params, list)):
-        ids = _prefetch_ids(execute_state, cls, BULK_AUDIT_ID_CAP)
+        try:
+            ids = _prefetch_ids(execute_state, cls, BULK_AUDIT_ID_CAP)
+        except Exception:
+            # Fail open: the write goes ahead, recorded as a summary row.
+            logger.exception("Could not read the rows a bulk write touches on %s", cls.__name__)
+            ids = None
     stmt = execute_state.statement
     result = execute_state.invoke_statement()
     if ids is not None and len(ids) <= BULK_AUDIT_ID_CAP:
diff --git a/framework/db/tests/test_db_bulk_audit.py b/framework/db/tests/test_db_bulk_audit.py
index eeba7f7fe..b649c9125 100644
--- a/framework/db/tests/test_db_bulk_audit.py
+++ b/framework/db/tests/test_db_bulk_audit.py
@@ -12,7 +12,7 @@
 from _models import _TenantItem
 from simple_module_db import bulk_audit, record_bulk_audit, tenant_context
 from simple_module_db.audit import AuditRecord
-from sqlalchemy import delete, func, insert, select, text, update
+from sqlalchemy import bindparam, delete, func, insert, select, text, update
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import Session
 
@@ -160,3 +160,32 @@ async def test_unaudited_engine_records_nothing(audited):
     await session.execute(update(AuditTestItem).values(name="n"))
     record_bulk_audit(session, AuditTestItem, "bulk_updated", [1])
     assert recorder.records == []
+
+
+async def test_parameterized_update_and_delete_are_audited(audited):
+    _state, session, recorder = audited
+    target = (await _ids(session, AuditTestItem.name == "n1"))[0]
+    stmt = update(AuditTestItem).where(AuditTestItem.name == bindparam("target")).values(value=50)
+    await session.execute(stmt, {"target": "n1"})
+    assert [(r.action, r.entity_id) for r in recorder.records] == [("bulk_updated", target)]
+    recorder.records.clear()
+    gone = delete(AuditTestItem).where(AuditTestItem.name == bindparam("target"))
+    await session.execute(gone, {"target": "n2"})
+    assert [r.action for r in recorder.records] == ["bulk_deleted"]
+    assert len(recorder.records) == 1 and recorder.records[0].entity_id != "*"
+
+
+async def test_broken_prefetch_never_breaks_the_write(audited, monkeypatch):
+    _state, session, recorder = audited
+
+    def _boom(*_args, **_kwargs):
+        raise RuntimeError("prefetch broke")
+
+    monkeypatch.setattr(bulk_audit, "_prefetch_ids", _boom)
+    await session.execute(update(AuditTestItem).where(AuditTestItem.value >= 0).values(name="ok"))
+    count = (await session.execute(select(func.count()).where(AuditTestItem.name == "ok"))).one()
+    assert count[0] == 3
+    assert [r.entity_id for r in recorder.records] == ["*"]
+    monkeypatch.setattr(bulk_audit, "_plan", _boom)
+    await session.execute(update(AuditTestItem).values(name="ok2"))
+    await session.execute(update(AuditTestItem).values(name="ok3").execution_options(sm_audit=False))

From e77cb90e144ce6f5bf2d9d5cea5ccc3e0ecfc640 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Thu, 22 Oct 2026 10:01:01 +0200
Subject: [PATCH 18/21] fix(head,sharing): drop blank head titles; distinct 403
 detail for share refusals

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 framework/inertia/simple_module_inertia/head.py | 5 +++++
 framework/inertia/tests/test_adapter_head.py    | 4 ++++
 modules/sharing/sharing/constants.py            | 1 +
 modules/sharing/sharing/service.py              | 3 ++-
 4 files changed, 12 insertions(+), 1 deletion(-)

diff --git a/framework/inertia/simple_module_inertia/head.py b/framework/inertia/simple_module_inertia/head.py
index 9ebf9e974..de7cf56b6 100644
--- a/framework/inertia/simple_module_inertia/head.py
+++ b/framework/inertia/simple_module_inertia/head.py
@@ -73,6 +73,11 @@ class Head(BaseModel):
     twitter: dict[str, str] = Field(default_factory=dict)
     json_ld: list[dict[str, Any]] = Field(default_factory=list)
 
+    @field_validator("title", "description")
+    @classmethod
+    def _stripped(cls, value: str) -> str:
+        return value.strip()
+
     @field_validator("canonical")
     @classmethod
     def _canonical(cls, value: str) -> str:
diff --git a/framework/inertia/tests/test_adapter_head.py b/framework/inertia/tests/test_adapter_head.py
index 3039d771d..5662e161b 100644
--- a/framework/inertia/tests/test_adapter_head.py
+++ b/framework/inertia/tests/test_adapter_head.py
@@ -147,3 +147,7 @@ def test_head_tags_use_only_data_inertia_keyed_elements() -> None:
     tags = head_tags(Head(title="T", description="d"), SiteInfo(app_name=""))
     assert tags[0] == '<title data-inertia="">T</title>'
     assert all("data-inertia" in t for t in tags)
+
+
+def test_blank_title_is_dropped():
+    assert head_tags(Head(title="   "), SiteInfo()) == []
diff --git a/modules/sharing/sharing/constants.py b/modules/sharing/sharing/constants.py
index 75d85b4a3..5a694731a 100644
--- a/modules/sharing/sharing/constants.py
+++ b/modules/sharing/sharing/constants.py
@@ -58,6 +58,7 @@
 
 ERR_UNKNOWN_TYPE: Final = "Unknown resource type"
 ERR_NOT_FOUND: Final = "Not found"
+ERR_FORBIDDEN: Final = "You may not share this resource"
 ERR_UNKNOWN_GRANTEE: Final = "Unknown user"
 ERR_BAD_ROLE: Final = "This role cannot be granted on this resource type"
 ERR_EXPIRED: Final = "expires_at must be in the future"
diff --git a/modules/sharing/sharing/service.py b/modules/sharing/sharing/service.py
index 12167972e..676cf2fef 100644
--- a/modules/sharing/sharing/service.py
+++ b/modules/sharing/sharing/service.py
@@ -27,6 +27,7 @@
 from sharing.constants import (
     ERR_BAD_ROLE,
     ERR_EXPIRED,
+    ERR_FORBIDDEN,
     ERR_NOT_FOUND,
     ERR_SELF,
     ERR_UNKNOWN_GRANTEE,
@@ -85,7 +86,7 @@ async def _authorize(
         if row is None:
             raise SharingError(404, ERR_NOT_FOUND)
         if not allowed:
-            raise SharingError(403, ERR_NOT_FOUND)
+            raise SharingError(403, ERR_FORBIDDEN)
         return row
 
     async def grant(self, principal: ResourcePrincipal, data: ShareGrant) -> ResourceShare:

From 84a1b26208aedb50c816b3abb32b794a474bb8df Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Thu, 22 Oct 2026 10:01:05 +0200
Subject: [PATCH 19/21] style: ruff format

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 framework/db/tests/test_db_bulk_audit.py | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/framework/db/tests/test_db_bulk_audit.py b/framework/db/tests/test_db_bulk_audit.py
index b649c9125..69ed52005 100644
--- a/framework/db/tests/test_db_bulk_audit.py
+++ b/framework/db/tests/test_db_bulk_audit.py
@@ -188,4 +188,6 @@ def _boom(*_args, **_kwargs):
     assert [r.entity_id for r in recorder.records] == ["*"]
     monkeypatch.setattr(bulk_audit, "_plan", _boom)
     await session.execute(update(AuditTestItem).values(name="ok2"))
-    await session.execute(update(AuditTestItem).values(name="ok3").execution_options(sm_audit=False))
+    await session.execute(
+        update(AuditTestItem).values(name="ok3").execution_options(sm_audit=False)
+    )

From 80e57016f27dc532255c79f0826132ae8fc21847 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Thu, 22 Oct 2026 11:45:46 +0200
Subject: [PATCH 20/21] Keep _phase_helpers.py under the 300-line cap after
 merging main

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 framework/hosting/simple_module_hosting/_phase_helpers.py | 6 +-----
 1 file changed, 1 insertion(+), 5 deletions(-)

diff --git a/framework/hosting/simple_module_hosting/_phase_helpers.py b/framework/hosting/simple_module_hosting/_phase_helpers.py
index b9a4e9609..bb74c5313 100644
--- a/framework/hosting/simple_module_hosting/_phase_helpers.py
+++ b/framework/hosting/simple_module_hosting/_phase_helpers.py
@@ -274,11 +274,7 @@ def attach_public_routes(app: FastAPI, settings: Settings, registry) -> None:
 
 
 def mount_module_static_dirs(app: FastAPI, modules: list) -> None:
-    """Mount each module's declared static directories.
-
-    Modules typically expose ``/modules/<name>/static`` for pre-bundled
-    frontend assets shipped inside the wheel.
-    """
+    """Mount each module's static directories (``/modules/<name>/static``) and SPA mounts."""
     for mod in modules:
         for url_prefix, directory in mod.static_mounts().items():
             directory_path = Path(directory)

From b5868a608ed91870ec8f7c0a5c16745b24130764 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Thu, 22 Oct 2026 12:02:24 +0200
Subject: [PATCH 21/21] test(cli): read add-worker errors without terminal
 styling

CI forces Rich colour, so '--force' in the rendered usage error was split by
escape codes. Run the CLI wide and colourless and normalise the output.

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 framework/cli/tests/test_cli_docker_workers.py | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/framework/cli/tests/test_cli_docker_workers.py b/framework/cli/tests/test_cli_docker_workers.py
index 67e7a449f..917d4f1a9 100644
--- a/framework/cli/tests/test_cli_docker_workers.py
+++ b/framework/cli/tests/test_cli_docker_workers.py
@@ -1,5 +1,7 @@
 """Worker image generation and validation through the public CLI."""
 
+import re
+
 import pytest
 from simple_module_cli.cli import app
 from simple_module_cli.docker_assets import _read, _template_root
@@ -14,8 +16,18 @@ def project(tmp_path, monkeypatch):
     return tmp_path
 
 
+_ANSI = re.compile(r"\x1b\[[0-9;]*m")
+
+
 def invoke(*args):
-    return CliRunner().invoke(app, ["docker", "add-worker", *args])
+    # Wide and colourless: CI forces Rich colour, which splits option names
+    # with escape codes and wraps the error box.
+    runner = CliRunner(env={"COLUMNS": "200", "NO_COLOR": "1", "TERM": "dumb"})
+    return runner.invoke(app, ["docker", "add-worker", *args])
+
+
+def plain(output: str) -> str:
+    return " ".join(_ANSI.sub("", output).split())
 
 
 def test_generated_worker(project):
@@ -61,7 +73,7 @@ def test_rerun_force_and_multiple_workers(project):
     docker = project / "docker/worker-geo.Dockerfile"
     docker.write_text("custom")
     result = invoke("geo", "--queues", "geo")
-    assert result.exit_code != 0 and "--force" in result.output
+    assert result.exit_code != 0 and "--force" in plain(result.output)
     assert docker.read_text() == "custom"
     assert (project / "compose.yml").read_text() == before
     assert invoke("geo", "--queues", "geo", "--force").exit_code == 0