From f5f13f09611400f188d9829d3a5e756dff2e47f6 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Mon, 19 Oct 2026 13:18:48 +0200
Subject: [PATCH 01/14] docs(migrations): describe the real multi-root,
 multi-head graph and pin it with a test (#503)

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 CLAUDE.md                          |  22 +++--
 docs/database/migrations.md        |  50 +++++++++---
 host/tests/test_migration_graph.py | 127 +++++++++++++++++++++++++++++
 3 files changed, 182 insertions(+), 17 deletions(-)
 create mode 100644 host/tests/test_migration_graph.py

diff --git a/CLAUDE.md b/CLAUDE.md
index 87987f9d9..0f3077caf 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -275,19 +275,27 @@ dependency + `get_csrf_token(request)` as a view prop, echoed as `X-CSRF-Token`
   never by importing `tenants`. `docs/framework/multi-tenancy.md`.
 - **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 has **several heads** (one per
-  labelled branch), so apply with `upgrade heads` (what `make migrate` does)
-  and autogenerate against one branch, since plain `revision --autogenerate`
-  refuses with "Multiple heads":
+  `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`
+  does); plain `revision --autogenerate` refuses with "Multiple heads", so name
+  the branch:
 
   ```
   uv run --project host alembic -c host/alembic.ini revision --autogenerate \
       -m "<msg>" --head <branch_label>@head
   ```
 
-  A module's first revision sets `branch_labels = ("<module_name>",)` (older
-  modules lack it); the label is a named target, not a per-module rollback:
-  `downgrade <module>@base` walks everything beneath it.
+  Labels are inherited by every descendant and are only named targets, not
+  per-module rollbacks: `downgrade <label>@base` unwinds the label's revision,
+  everything above it and everything beneath it on that root, other modules
+  included. Known mislabels (existing files are left alone, applied databases
+  stay valid): `51b2058d8afd` puts `api_tokens` on the trunk, so users,
+  file_storage and background_tasks revisions report it, and keycloak's
+  `168a2882f443` branches off the users revision `873ca2015033`. Give an
+  unlabelled module a label on its next revision. `host/tests/test_migration_graph.py`
+  pins the roots, heads and owners; update it with any new root or head.
   `docs/database/migrations.md`.
 - Postgres extensions: override `ModuleBase.db_extensions()`; `LTree`/`TSVector`
   types are `TEXT` on SQLite; tests needing Postgres carry
diff --git a/docs/database/migrations.md b/docs/database/migrations.md
index 6eb51d3b1..71f560fa4 100644
--- a/docs/database/migrations.md
+++ b/docs/database/migrations.md
@@ -4,11 +4,41 @@ All migrations live in `host/migrations/versions/` — **not** in module package
 
 ## Why centralized?
 
-- **Dependency ordering is global.** If `invoices` depends on `orders_order.id`, their migrations must order correctly. One linear Alembic history enforces this.
+- **Dependency ordering is global.** If `invoices` depends on `orders_order.id`, their migrations must order correctly. One shared Alembic history, with `down_revision` links between modules, enforces this.
 - **Autogenerate sees everything.** `host/migrations/env.py` calls `build_module_metadata()` to union every installed module's `MetaData`. Autogenerate diffs the DB against that union and writes one migration covering all changes.
 - **Operators run one command.** `make migrate` is the only target. No "did you also run `orders/migrate`?" footgun.
 
-Each module's *first* migration sets `branch_labels = ("<module_name>",)`. The label is a named target for that revision; it does **not** isolate the module's history, because every first revision chains off the previous head. `alembic downgrade <module>@base` therefore walks the whole chain beneath it, other modules included. See [Removing one module's schema](#removing-one-modules-schema).
+## The real graph
+
+The history is **not** a single linear chain. It has several roots and several heads, and `make migrate` runs `upgrade heads` for that reason. On `main` today:
+
+| Root | Branch |
+|---|---|
+| `77162e7b184b` initial schema | the users trunk (also holds file_storage, background_tasks, api_tokens revisions) |
+| `e36ab09c4a92` tenants initial schema | tenants (`f1a9c3d7b2e4` head) |
+
+| Head | Owning module | Label Alembic reports |
+|---|---|---|
+| `c8e4f1a2b6d9` | users (login lockout) | `api_tokens` |
+| `a7c2e91d4b58` | audit_log | `audit_log` |
+| `f1a9c3d7b2e4` | tenants | `tenants` |
+| `f6a3b9d2e8c4` | keycloak | `keycloak` |
+
+`audit_log` forks off the trunk at `41cf2c53660e`, and `keycloak` forks off the users revision `873ca2015033`.
+
+A module's first migration sets `branch_labels = ("<module_name>",)`. Alembic **inherits** a label onto every descendant, so the label names a revision and everything above it, and it does not isolate the module. It is only a named target (`upgrade <label>@head`, `revision --head <label>@head`) and the source of the Doctor's `module` column, which reads the first label on each revision.
+
+### 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:
+
+- `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.
+- `users`, `file_storage`, `background_tasks`, `settings`, `permissions` and `feature_flags` have no label of their own.
+
+Guidance: give an unlabelled module a `branch_labels` on its **next** revision. Adding a label to an existing revision file is technically possible, because `alembic_version` stores revision ids and never labels, but it also relabels every descendant and changes what `<label>@head` resolves to, so treat it as a deliberate, reviewed change rather than a cleanup.
+
+`host/tests/test_migration_graph.py` pins the roots, heads, each revision's owning module and the mislabels above. Adding a root, head or revision fails it until the table is updated.
 
 ## Day-to-day workflow
 
@@ -41,12 +71,12 @@ make downgrade                                                 # back one revisi
 uv run --project host alembic -c host/alembic.ini downgrade <revision_id>   # to a specific revision
 ```
 
-Do **not** use `downgrade orders@base` to roll back just the orders module. The `branch_labels` marker names a revision, but `orders@base` resolves to the base of the linear chain that revision sits on, so it rolls back every revision beneath it, including other modules'.
+Do **not** use `downgrade orders@base` to roll back just the orders module. The label names a revision, and `orders@base` unwinds that revision, all of its descendants, and everything beneath it down to the root it sits on, including other modules'. With this graph, `downgrade api_tokens@base` would drop the whole users trunk (users, file_storage, the background_tasks outbox and the initial schema), not only the api_tokens tables.
 
 ### Removing one module's schema
 
-- If the module's revisions are the latest in the chain (nothing from another module sits above them), downgrade to the `down_revision` of the module's *first* revision: `alembic -c host/alembic.ini downgrade <that down_revision id>`.
-- Otherwise write a dedicated migration that drops the module's tables (and anything depending on them). History stays linear and other modules are untouched.
+- If the module's revisions are the latest on their branch (nothing from another module sits above them), downgrade to the `down_revision` of the module's *first* revision: `alembic -c host/alembic.ini downgrade <that down_revision id>`.
+- Otherwise write a dedicated migration that drops the module's tables (and anything depending on them). Other modules are untouched.
 
 ## First migration of a new module
 
@@ -61,7 +91,7 @@ branch_labels = ("orders",)  # ← add this
 depends_on = None
 ```
 
-The marker names the revision so you can target it (for example `alembic upgrade orders@head`); later `orders` revisions do not need it. It does not turn the module into an independent branch.
+The marker names the revision so you can target it (for example `alembic upgrade orders@head`); later `orders` revisions do not need it. It does not turn the module into an independent branch, and it is inherited by every revision stacked on top of it, so put it on the module's own first revision and not on a revision that other modules build on.
 
 ## Alembic environment setup
 
@@ -94,7 +124,7 @@ context.configure(
 
 ## Boot-time migration check
 
-On startup, the framework compares `alembic_version` to the migration head:
+On startup, the framework compares `alembic_version` to **every** head (`resolve_head_revisions` in `simple_module_hosting.migrations`; the history has several, so it never asks for a single head):
 
 - **Development:** prints a warning if the DB is behind. Result stored on `app.state.migration`.
 - **Production:** fails boot with `SM010`. Don't ship a web process that's pointed at an unmigrated DB.
@@ -116,7 +146,7 @@ The dev-mode boot log prints the offending table names. Resolution: run `make mi
 If `invoices` has an FK to `orders_order.id`:
 
 - Alembic will emit `ADD CONSTRAINT` in the invoices table's migration.
-- The migration that creates `invoices_invoice` must come **after** the one that creates `orders_order` in linear history.
+- The migration that creates `invoices_invoice` must come **after** the one that creates `orders_order` in the history (an ancestor, not a sibling branch).
 - `smpy create-module` + `make migration` handle this naturally as long as `depends_on` is correct in `ModuleMeta`.
 
 All tables share the host's single schema on both Postgres and SQLite, so a cross-module FK is just an ordinary same-schema reference (`orders_order.id ← invoices_invoice.order_id`).
@@ -149,7 +179,7 @@ revision A  ← you created
 revision B  ← teammate's branch created
 ```
 
-Both have `down_revision = <previous>`. Alembic will refuse `upgrade head` on a tree with multiple heads. Resolve by:
+Both have `down_revision = <previous>`, so the same branch now has two heads. (Heads on *different* labelled branches are expected and need no merge; `upgrade heads` applies them all.) Resolve a same-branch fork by:
 
 1. `uv run alembic heads` — list them.
 2. `uv run alembic merge -m "merge A and B" <rev-A> <rev-B>` — creates a merge revision with both as parents.
@@ -179,7 +209,7 @@ async def test_migration_up_then_down(tmp_path):
     cfg = Config("host/alembic.ini")
     cfg.set_main_option("sqlalchemy.url", db_url)
 
-    command.upgrade(cfg, "head")
+    command.upgrade(cfg, "heads")
     command.downgrade(cfg, "base")
 ```
 
diff --git a/host/tests/test_migration_graph.py b/host/tests/test_migration_graph.py
new file mode 100644
index 000000000..fe4ef0e6f
--- /dev/null
+++ b/host/tests/test_migration_graph.py
@@ -0,0 +1,127 @@
+"""Pin the shape of the Alembic revision graph (GH #503).
+
+The history is *not* one linear chain: it has several roots and heads, and
+``branch_labels`` are inherited by every descendant. Adding a root, a head or a
+revision without updating the tables below fails this test on purpose, so the
+change is made consciously and ``docs/database/migrations.md`` stays true.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+from alembic.config import Config
+from alembic.script import ScriptDirectory
+
+_HOST = Path(__file__).resolve().parents[1]
+
+# Module that owns the tables each revision creates or alters. "core" marks
+# revisions that touch several modules' tables at once.
+_OWNER: dict[str, str] = {
+    "77162e7b184b": "core",  # initial schema: background_tasks, feature_flags, file_storage, ...
+    "3bf3f9db7f7f": "users",
+    "41cf2c53660e": "users",
+    "873ca2015033": "users",
+    "92965b00f105": "users",
+    "f53464f5ac43": "users",
+    "b4c1e7d9a025": "users",
+    "c3a1d7e45f20": "users",
+    "d4e8a1b6c392": "users",
+    "b5018b617142": "users",
+    "c8e4f1a2b6d9": "users",
+    "a659221c464b": "file_storage",
+    "e5a8c1f27b94": "file_storage",
+    "c7f2d9a41e83": "file_storage",
+    "e5f2a8c1d7b3": "core",  # timezone-aware timestamps across modules
+    "b5d3f08a6e17": "background_tasks",
+    "e878882924e7": "background_tasks",
+    "51b2058d8afd": "api_tokens",
+    "168a2882f443": "keycloak",
+    "f6a3b9d2e8c4": "keycloak",
+    "e36ab09c4a92": "tenants",
+    "f1a9c3d7b2e4": "tenants",
+    "70786227af4c": "audit_log",
+    "a7c2e91d4b58": "audit_log",
+}
+
+_ROOTS = {"77162e7b184b", "e36ab09c4a92"}
+
+# head revision -> module owning the tables it creates or alters.
+_HEADS = {
+    "a7c2e91d4b58": "audit_log",
+    "c8e4f1a2b6d9": "users",  # reported as ``api_tokens`` (inherited label)
+    "f1a9c3d7b2e4": "tenants",
+    "f6a3b9d2e8c4": "keycloak",
+}
+
+# Labels written in the revision files themselves.
+_DECLARED_LABELS = {
+    "70786227af4c": "audit_log",
+    "51b2058d8afd": "api_tokens",
+    "168a2882f443": "keycloak",
+    "e36ab09c4a92": "tenants",
+}
+
+# Known mislabels: revisions that inherit a label from an ancestor owned by a
+# different module (the ``api_tokens`` label sits on the trunk). Existing
+# revision files are not edited; see docs/database/migrations.md.
+_INHERITED_MISLABELS = {
+    "a659221c464b": "api_tokens",
+    "e5a8c1f27b94": "api_tokens",
+    "e5f2a8c1d7b3": "api_tokens",
+    "c7f2d9a41e83": "api_tokens",
+    "b5d3f08a6e17": "api_tokens",
+    "e878882924e7": "api_tokens",
+    "d4e8a1b6c392": "api_tokens",
+    "c3a1d7e45f20": "api_tokens",
+    "b4c1e7d9a025": "api_tokens",
+    "f53464f5ac43": "api_tokens",
+    "92965b00f105": "api_tokens",
+    "b5018b617142": "api_tokens",
+    "c8e4f1a2b6d9": "api_tokens",
+}
+
+
+@pytest.fixture(scope="module")
+def script() -> ScriptDirectory:
+    return ScriptDirectory.from_config(Config(str(_HOST / "alembic.ini")))
+
+
+def test_every_revision_has_a_known_owner(script: ScriptDirectory) -> None:
+    revisions = {r.revision for r in script.walk_revisions()}
+    assert revisions == set(_OWNER), (
+        "revision set changed; add new revisions to _OWNER "
+        f"(new: {sorted(revisions - set(_OWNER))}, gone: {sorted(set(_OWNER) - revisions)})"
+    )
+
+
+def test_roots(script: ScriptDirectory) -> None:
+    assert set(script.get_bases()) == _ROOTS
+
+
+def test_heads_and_their_owners(script: ScriptDirectory) -> None:
+    heads = set(script.get_heads())
+    assert heads == set(_HEADS), f"heads changed: {sorted(heads)}"
+    for head, module in _HEADS.items():
+        assert _OWNER[head] == module
+
+
+def test_declared_labels_match_owning_module(script: ScriptDirectory) -> None:
+    declared = {
+        r.revision: next(iter(labels))
+        for r in script.walk_revisions()
+        if (labels := getattr(r.module, "branch_labels", None))
+    }
+    assert declared == _DECLARED_LABELS
+    for rev, label in declared.items():
+        assert _OWNER[rev] == label, f"{rev} is labelled {label!r} but owned by {_OWNER[rev]!r}"
+
+
+def test_inherited_labels_are_the_known_mislabels(script: ScriptDirectory) -> None:
+    mislabels = {}
+    for r in script.walk_revisions():
+        effective = sorted(r.branch_labels)
+        if effective and effective != [_OWNER[r.revision]]:
+            mislabels[r.revision] = effective[0]
+    assert mislabels == _INHERITED_MISLABELS

From 8be3fec87cd8291062cfff90cf212d236a838f29 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Mon, 19 Oct 2026 13:18:49 +0200
Subject: [PATCH 02/14] fix(hosting): refuse boot outside development when
 stored host settings are unreadable (#494)

A failed pre-app read used to log at DEBUG and build with defaults, so a
worker booting during a DB blip ran single-tenant (multi_tenant off) next
to strict siblings. A missing settings table (fresh install) stays quiet;
a connect/query failure now warns, and outside development raises
HostSettingsUnavailableError when the settings module is installed.

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 .../simple_module_hosting/_preapp_config.py   | 66 ++++++++++---
 framework/hosting/tests/test_preapp_config.py |  4 +-
 .../tests/test_preapp_read_failures.py        | 96 +++++++++++++++++++
 3 files changed, 153 insertions(+), 13 deletions(-)
 create mode 100644 framework/hosting/tests/test_preapp_read_failures.py

diff --git a/framework/hosting/simple_module_hosting/_preapp_config.py b/framework/hosting/simple_module_hosting/_preapp_config.py
index cf2bf5e2b..009a16f89 100644
--- a/framework/hosting/simple_module_hosting/_preapp_config.py
+++ b/framework/hosting/simple_module_hosting/_preapp_config.py
@@ -30,7 +30,8 @@
 
 from pydantic_settings import BaseSettings
 from simple_module_core.dotenv import parse_dotenv
-from sqlalchemy import text
+from simple_module_core.environments import NON_PROD_ENVIRONMENTS
+from sqlalchemy import inspect, text
 from sqlalchemy.ext.asyncio import create_async_engine
 from sqlalchemy.pool import NullPool
 
@@ -44,6 +45,17 @@
 _ENV_PREFIX = "SM_"
 
 
+class HostSettingsUnavailableError(RuntimeError):
+    """The stored host settings exist but could not be read before boot.
+
+    Raised only outside development, and only when the settings module is
+    installed. Building with defaults instead would silently drop every
+    build-time override — ``multi_tenant`` above all, so one worker that
+    booted during a DB blip would serve requests single-tenant, with no tenant
+    middleware and no strict filter, while its siblings stay isolated (#494).
+    """
+
+
 def _settings_table() -> tuple[str, str, str] | None:
     """Resolve the settings module's table name and system-scope markers.
 
@@ -87,7 +99,13 @@ def _parse(raw: str, value_type: str) -> Any:
 
 
 async def _read(database_url: str) -> dict[str, tuple[str, str]]:
-    """Select the ``host.*`` system-scoped overrides. Returns ``{}`` on failure."""
+    """Select the ``host.*`` system-scoped overrides.
+
+    Returns ``{}`` when the settings module isn't installed or its table does
+    not exist yet (a fresh install). Anything else — the connect, the
+    existence check, the select — raises, so the caller can tell an expected
+    empty result from a failure.
+    """
     info = _settings_table()
     if info is None:
         return {}
@@ -102,6 +120,12 @@ async def _read(database_url: str) -> dict[str, tuple[str, str]]:
     engine = create_async_engine(database_url, poolclass=NullPool)
     try:
         async with engine.connect() as conn:
+            # Checked rather than inferred from the select's error: "no such
+            # table" is a fresh install and must stay quiet, while a refused
+            # connection or a failing query is not, and the driver errors for
+            # the two are not reliably distinguishable across backends.
+            if not await conn.run_sync(lambda sync: inspect(sync).has_table(table)):
+                return {}
             rows = (await conn.execute(stmt, {"scope": scope, "scope_id": scope_id})).all()
     finally:
         await engine.dispose()
@@ -120,17 +144,20 @@ async def _read(database_url: str) -> dict[str, tuple[str, str]]:
     return out
 
 
-def load_host_overrides(database_url: str) -> dict[str, tuple[str, str]]:
+def load_host_overrides(
+    database_url: str, *, strict: bool = False
+) -> dict[str, tuple[str, str]]:
     """Return ``{field: (raw_value, value_type)}`` for host settings in the DB.
 
-    Returns ``{}`` for every failure mode — unreachable database, database
-    reachable but not yet migrated, table present but empty. All three are
-    ordinary states on a fresh install, and all three are exactly what the
-    setup wizard exists to repair, so none of them may fail the boot.
+    Returns ``{}`` quietly when the settings module isn't installed, or when
+    the database is reachable but not yet migrated or holds no rows. Those are
+    the ordinary states of a fresh install, and what the setup wizard repairs.
 
-    Logged at DEBUG rather than WARNING on purpose: an empty result is the
-    expected first-boot path, and warning about it would cry wolf on every
-    new install.
+    A failure to connect or to query is different: the stored overrides may
+    exist and simply be unreadable right now. That logs a WARNING and, with
+    ``strict``, raises :class:`HostSettingsUnavailableError` instead of letting
+    the caller build with defaults (#494). ``merge_host_settings`` is strict
+    outside development; one-shot tooling (``smpy openapi``) is not.
 
     Runs the async read on a private event loop in a worker thread. ``asyncio.run``
     refuses to nest inside a running loop, and ``create_app`` is called both
@@ -141,7 +168,19 @@ def load_host_overrides(database_url: str) -> dict[str, tuple[str, str]]:
         with ThreadPoolExecutor(max_workers=1) as pool:
             return pool.submit(lambda: asyncio.run(_read(database_url))).result()
     except Exception as exc:
-        logger.debug("Pre-app host settings read skipped: %s", exc)
+        if strict:
+            raise HostSettingsUnavailableError(
+                "Could not read the stored host settings before boot "
+                f"({type(exc).__name__}: {exc}). Refusing to start with defaults "
+                "outside development: build-time settings such as multi_tenant "
+                "would silently be off on this worker. Check SM_DATABASE_URL and "
+                "that the database is reachable, then restart."
+            ) from exc
+        logger.warning(
+            "Pre-app host settings read failed; building with env/defaults: %s: %s",
+            type(exc).__name__,
+            exc,
+        )
         return {}
 
 
@@ -210,7 +249,10 @@ def merge_host_settings(bootstrap: BootstrapSettings | None = None) -> Settings:
     from simple_module_hosting._secret_key import ensure_secret_key
 
     bootstrap = bootstrap or BootstrapSettings()
-    overrides = load_host_overrides(bootstrap.database_url)
+    overrides = load_host_overrides(
+        bootstrap.database_url,
+        strict=bootstrap.environment not in NON_PROD_ENVIRONMENTS,
+    )
     values = apply_host_overrides(overrides)
     # Resolved here rather than left to the field default so an install with
     # no SM_SECRET_KEY gets a generated, persisted key instead of the shipped
diff --git a/framework/hosting/tests/test_preapp_config.py b/framework/hosting/tests/test_preapp_config.py
index 47207c943..6ae897416 100644
--- a/framework/hosting/tests/test_preapp_config.py
+++ b/framework/hosting/tests/test_preapp_config.py
@@ -54,7 +54,9 @@ def test_returns_empty_when_table_missing(tmp_path: Path) -> None:
 
 
 def test_returns_empty_when_db_unreachable() -> None:
-    """A wrong host must not fail the boot — the wizard reports it instead."""
+    """Non-strict (development, tooling): a wrong host falls back to defaults.
+    Outside development ``merge_host_settings`` refuses instead — see
+    ``test_preapp_read_failures.py`` (#494)."""
     url = "postgresql+asyncpg://nobody:nobody@127.0.0.1:1/nothing"
     assert load_host_overrides(url) == {}
 
diff --git a/framework/hosting/tests/test_preapp_read_failures.py b/framework/hosting/tests/test_preapp_read_failures.py
new file mode 100644
index 000000000..6b66b6d99
--- /dev/null
+++ b/framework/hosting/tests/test_preapp_read_failures.py
@@ -0,0 +1,96 @@
+"""The pre-app host-settings read: quiet on a fresh install, loud on a failure.
+
+``multi_tenant`` is consumed while ``create_app`` builds the middleware stack,
+so a worker that boots while the database is briefly unreachable and falls
+back to defaults serves requests single-tenant — no tenant middleware, no
+strict filter — next to siblings that stayed isolated (#494). A missing table
+is the opposite case: an ordinary fresh install that must boot to show the
+setup wizard.
+"""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+from pathlib import Path
+
+import pytest
+from simple_module_hosting import _preapp_config
+from simple_module_hosting._preapp_config import (
+    HostSettingsUnavailableError,
+    load_host_overrides,
+    merge_host_settings,
+)
+from simple_module_hosting.bootstrap_settings import BootstrapSettings
+
+_LOGGER = "simple_module_hosting._preapp_config"
+_SECRET = "a-test-secret-that-is-not-the-placeholder-0000000000"
+
+
+async def _refused(_database_url: str) -> dict[str, tuple[str, str]]:
+    raise OSError("Connection refused")
+
+
+def _unmigrated(tmp_path: Path) -> str:
+    db = tmp_path / "unmigrated.db"
+    sqlite3.connect(db).close()  # file exists, no tables
+    return f"sqlite+aiosqlite:///{db}"
+
+
+def _bootstrap(url: str, environment: str) -> BootstrapSettings:
+    return BootstrapSettings(
+        _env_file=None, database_url=url, environment=environment, secret_key=_SECRET
+    )
+
+
+@pytest.mark.parametrize("environment", ["development", "production"])
+def test_missing_table_is_quiet_in_every_environment(
+    tmp_path: Path, environment: str, caplog: pytest.LogCaptureFixture
+) -> None:
+    """A fresh install must boot (to show the wizard) without crying wolf."""
+    with caplog.at_level(logging.DEBUG, logger=_LOGGER):
+        merged = merge_host_settings(_bootstrap(_unmigrated(tmp_path), environment))
+
+    assert merged.multi_tenant is False
+    assert not [r for r in caplog.records if r.name == _LOGGER and r.levelno >= logging.WARNING]
+
+
+def test_strict_read_of_missing_table_returns_empty(tmp_path: Path) -> None:
+    assert load_host_overrides(_unmigrated(tmp_path), strict=True) == {}
+
+
+def test_connection_failure_warns_in_development(
+    monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture, tmp_path: Path
+) -> None:
+    monkeypatch.setattr(_preapp_config, "_read", _refused)
+
+    with caplog.at_level(logging.WARNING, logger=_LOGGER):
+        merged = merge_host_settings(_bootstrap(_unmigrated(tmp_path), "development"))
+
+    assert merged.multi_tenant is False
+    warnings = [r for r in caplog.records if r.name == _LOGGER and r.levelno == logging.WARNING]
+    assert warnings and "OSError" in warnings[0].getMessage()
+
+
+def test_connection_failure_refuses_boot_outside_development(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    """Building with defaults would silently turn multi_tenant off on this worker."""
+    monkeypatch.setattr(_preapp_config, "_read", _refused)
+
+    with pytest.raises(HostSettingsUnavailableError, match="multi_tenant"):
+        merge_host_settings(_bootstrap(_unmigrated(tmp_path), "production"))
+
+
+def test_unreachable_postgres_refuses_boot_outside_development() -> None:
+    """The real failure, not a patched one: nothing listens on port 1."""
+    url = "postgresql+asyncpg://nobody:nobody@127.0.0.1:1/nothing"
+    with pytest.raises(HostSettingsUnavailableError):
+        merge_host_settings(_bootstrap(url, "production"))
+
+
+def test_no_settings_module_never_refuses(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Without the settings module there is nothing stored to lose."""
+    monkeypatch.setattr(_preapp_config, "_settings_table", lambda: None)
+    url = "postgresql+asyncpg://nobody:nobody@127.0.0.1:1/nothing"
+    assert load_host_overrides(url, strict=True) == {}

From 72c80435b53a3e16dc3140ba1edadc9809461d2d Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Mon, 19 Oct 2026 13:18:59 +0200
Subject: [PATCH 03/14] fix(ui): mobile sidebar drawer closes on Escape, traps
 focus, is a dialog (#554)

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 .../simple_module_hosting/ui_locales/en.json  |   1 +
 .../simple_module_hosting/ui_locales/es.json  |   1 +
 packages/i18n/src/generated-resources.ts      |   1 +
 packages/i18n/src/keys.generated.ts           |   1 +
 .../src/layouts/SidebarLayout.drawer.test.tsx | 114 ++++++++++++++++++
 packages/ui/src/layouts/SidebarLayout.tsx     |  13 +-
 packages/ui/src/layouts/useDrawerA11y.ts      |  60 +++++++++
 7 files changed, 189 insertions(+), 2 deletions(-)
 create mode 100644 packages/ui/src/layouts/SidebarLayout.drawer.test.tsx
 create mode 100644 packages/ui/src/layouts/useDrawerA11y.ts

diff --git a/framework/hosting/simple_module_hosting/ui_locales/en.json b/framework/hosting/simple_module_hosting/ui_locales/en.json
index 392843d83..bbc3b2f95 100644
--- a/framework/hosting/simple_module_hosting/ui_locales/en.json
+++ b/framework/hosting/simple_module_hosting/ui_locales/en.json
@@ -55,6 +55,7 @@
   "sidebar": {
     "open": "Open sidebar",
     "close": "Close sidebar",
+    "drawer": "Navigation menu",
     "back": "Back",
     "skip_to_content": "Skip to content"
   },
diff --git a/framework/hosting/simple_module_hosting/ui_locales/es.json b/framework/hosting/simple_module_hosting/ui_locales/es.json
index e61875b32..211dde46a 100644
--- a/framework/hosting/simple_module_hosting/ui_locales/es.json
+++ b/framework/hosting/simple_module_hosting/ui_locales/es.json
@@ -55,6 +55,7 @@
   "sidebar": {
     "open": "Abrir barra lateral",
     "close": "Cerrar barra lateral",
+    "drawer": "Menú de navegación",
     "back": "Volver",
     "skip_to_content": "Saltar al contenido"
   },
diff --git a/packages/i18n/src/generated-resources.ts b/packages/i18n/src/generated-resources.ts
index fc73f4dc9..3dac45709 100644
--- a/packages/i18n/src/generated-resources.ts
+++ b/packages/i18n/src/generated-resources.ts
@@ -1018,6 +1018,7 @@ export default {
     'ui.relative_time.years_ago_other': '',
     'ui.sidebar.back': '',
     'ui.sidebar.close': '',
+    'ui.sidebar.drawer': '',
     'ui.sidebar.open': '',
     'ui.sidebar.skip_to_content': '',
     'ui.switcher.label': '',
diff --git a/packages/i18n/src/keys.generated.ts b/packages/i18n/src/keys.generated.ts
index cd630cd81..0e46e8a4e 100644
--- a/packages/i18n/src/keys.generated.ts
+++ b/packages/i18n/src/keys.generated.ts
@@ -1299,6 +1299,7 @@ export const keys = {
     sidebar: {
       back: 'ui.sidebar.back',
       close: 'ui.sidebar.close',
+      drawer: 'ui.sidebar.drawer',
       open: 'ui.sidebar.open',
       skip_to_content: 'ui.sidebar.skip_to_content',
     },
diff --git a/packages/ui/src/layouts/SidebarLayout.drawer.test.tsx b/packages/ui/src/layouts/SidebarLayout.drawer.test.tsx
new file mode 100644
index 000000000..e9af628ec
--- /dev/null
+++ b/packages/ui/src/layouts/SidebarLayout.drawer.test.tsx
@@ -0,0 +1,114 @@
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+vi.mock('@inertiajs/react', () => ({
+  usePage: () => ({
+    url: '/admin/settings',
+    props: {
+      menus: {
+        adminSidebar: [
+          { label: 'One', url: '/admin/one' },
+          { label: 'Two', url: '/admin/two' },
+        ],
+      },
+    },
+  }),
+  Link: ({
+    href,
+    children,
+    ...rest
+  }: { href: string; children: React.ReactNode } & Record<string, unknown>) => (
+    <a href={href} {...rest}>
+      {children}
+    </a>
+  ),
+}));
+
+vi.mock('next-themes', () => ({ useTheme: () => ({ theme: 'light' }) }));
+
+vi.mock('@simple-module-py/i18n', () => {
+  const keys = new Proxy(
+    {},
+    { get: () => new Proxy({}, { get: () => new Proxy({}, { get: (_t, p) => String(p) }) }) },
+  );
+  return { useT: () => ({ t: (k: string) => k }), t: (k: string) => k, keys };
+});
+
+vi.mock('../components/AppTopbar', () => ({
+  AppTopbar: () => null,
+  activeSection: () => null,
+  findSection: () => null,
+}));
+vi.mock('../components/BrandingFooter', () => ({ BrandingFooter: () => null }));
+vi.mock('../components/BrandingHead', () => ({ BrandingHead: () => null }));
+vi.mock('../components/BrandingBanner', () => ({ BrandingBanner: () => null }));
+vi.mock('../components/DemoBanner', () => ({ DemoBanner: () => null }));
+vi.mock('../components/BrandingMark', () => ({ BrandingMark: () => null }));
+vi.mock('../components/LocaleSwitcher', () => ({
+  LocaleSwitcher: () => null,
+  useHasMultipleLocales: () => false,
+}));
+vi.mock('./SidebarUserMenu', () => ({ SidebarUserMenu: () => null }));
+vi.mock('./MobileBar', () => ({
+  MobileBar: ({ onOpen }: { onOpen: () => void }) => (
+    <button type="button" onClick={onOpen}>
+      open
+    </button>
+  ),
+}));
+
+import { AdminLayout } from './AdminLayout';
+
+function setup() {
+  render(
+    <AdminLayout>
+      <p>page</p>
+    </AdminLayout>,
+  );
+  const trigger = screen.getByRole('button', { name: 'open' });
+  trigger.focus();
+  fireEvent.click(trigger);
+  return trigger;
+}
+
+describe('SidebarLayout mobile drawer', () => {
+  it('is a plain sidebar (no dialog role) until opened', () => {
+    render(
+      <AdminLayout>
+        <p>page</p>
+      </AdminLayout>,
+    );
+    expect(screen.queryByRole('dialog')).toBeNull();
+    expect(document.querySelector('aside')?.getAttribute('aria-modal')).toBeNull();
+  });
+
+  it('opens as a labelled modal dialog and moves focus inside', () => {
+    setup();
+    const dialog = screen.getByRole('dialog');
+    expect(dialog.getAttribute('aria-modal')).toBe('true');
+    expect(dialog.getAttribute('aria-label')).toBeTruthy();
+    expect(dialog.contains(document.activeElement)).toBe(true);
+  });
+
+  it('closes on Escape and returns focus to the trigger', () => {
+    const trigger = setup();
+    fireEvent.keyDown(document.activeElement ?? document.body, { key: 'Escape' });
+    expect(screen.queryByRole('dialog')).toBeNull();
+    expect(document.activeElement).toBe(trigger);
+  });
+
+  it('traps Tab and Shift+Tab inside the open drawer', () => {
+    setup();
+    const dialog = screen.getByRole('dialog');
+    const focusables = Array.from(
+      dialog.querySelectorAll<HTMLElement>('a[href], button:not([disabled])'),
+    );
+    const first = focusables[0];
+    const last = focusables[focusables.length - 1];
+    last.focus();
+    fireEvent.keyDown(last, { key: 'Tab' });
+    expect(document.activeElement).toBe(first);
+    fireEvent.keyDown(first, { key: 'Tab', shiftKey: true });
+    expect(document.activeElement).toBe(last);
+  });
+});
diff --git a/packages/ui/src/layouts/SidebarLayout.tsx b/packages/ui/src/layouts/SidebarLayout.tsx
index 31654dbca..8fb55ee37 100644
--- a/packages/ui/src/layouts/SidebarLayout.tsx
+++ b/packages/ui/src/layouts/SidebarLayout.tsx
@@ -10,7 +10,7 @@ import {
 } from '@simple-module-py/ui/components/ui/tooltip';
 import { X } from 'lucide-react';
 import type React from 'react';
-import { useMemo, useState } from 'react';
+import { useCallback, useMemo, useRef, useState } from 'react';
 import { AppTopbar, activeSection, findSection } from '../components/AppTopbar';
 import { BrandingBanner } from '../components/BrandingBanner';
 import { BrandingFooter } from '../components/BrandingFooter';
@@ -27,6 +27,7 @@ import { AdminSectionLink } from './AdminSectionLink';
 import { MobileBar } from './MobileBar';
 import { SidebarUserMenu } from './SidebarUserMenu';
 import { DEFAULT_SIDEBAR_THEME, SIDEBAR_ICON_FOCUS, type SidebarTheme } from './sidebar-theme';
+import { useDrawerA11y } from './useDrawerA11y';
 
 // A stable reference for "no items" — `menus?.[key] ?? []` would otherwise
 // mint a fresh empty array every render, and that array flows into
@@ -89,7 +90,9 @@ function SidebarShell({ children, menuKey, theme, headerSlot, footerNavSlot }: S
   // so it keeps the primary logo.
   const darkLogoUrl = darkSurfaceLogo(branding);
   const [sidebarOpen, setSidebarOpen] = useState(false);
-  const closeSidebar = () => setSidebarOpen(false);
+  const closeSidebar = useCallback(() => setSidebarOpen(false), []);
+  const drawerRef = useRef<HTMLElement>(null);
+  useDrawerA11y(sidebarOpen, closeSidebar, drawerRef);
 
   const menuItems = menus?.[menuKey] ?? NO_ITEMS;
   // ⌘K reaches everything the viewer can open, not just the shell they are
@@ -161,6 +164,12 @@ function SidebarShell({ children, menuKey, theme, headerSlot, footerNavSlot }: S
 
         {/* Sidebar */}
         <aside
+          ref={drawerRef}
+          // Only a dialog while the phone drawer is open; otherwise it is the
+          // plain desktop sidebar.
+          {...(sidebarOpen
+            ? { role: 'dialog', 'aria-modal': true, 'aria-label': t(keys.ui.sidebar.drawer) }
+            : {})}
           className={`fixed inset-y-0 left-0 z-50 w-full sm:w-72 lg:w-64 ${theme.sidebarBg} flex flex-col border-r border-white/[0.06] transition-transform duration-200 ease-in-out lg:translate-x-0 lg:z-30 ${sidebarOpen ? 'translate-x-0' : '-translate-x-full'}`}
         >
           {/* Drawer header — ✕ then the app name, per the deck's phone frame.
diff --git a/packages/ui/src/layouts/useDrawerA11y.ts b/packages/ui/src/layouts/useDrawerA11y.ts
new file mode 100644
index 000000000..83c0d8b84
--- /dev/null
+++ b/packages/ui/src/layouts/useDrawerA11y.ts
@@ -0,0 +1,60 @@
+import { type RefObject, useEffect } from 'react';
+
+const FOCUSABLE =
+  'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
+/**
+ * Modal-dialog behaviour for the mobile sidebar drawer (WAI-ARIA dialog
+ * pattern): Escape closes it, focus moves in on open and is trapped while it is
+ * open, and focus returns to whatever opened it on close.
+ *
+ * The drawer element stays mounted (it is the static sidebar on desktop), so
+ * this is a hook rather than a Dialog primitive.
+ */
+export function useDrawerA11y(
+  open: boolean,
+  onClose: () => void,
+  drawerRef: RefObject<HTMLElement | null>,
+) {
+  useEffect(() => {
+    if (!open) return;
+    const drawer = drawerRef.current;
+    const opener = document.activeElement as HTMLElement | null;
+    const items = () => (drawer ? Array.from(drawer.querySelectorAll<HTMLElement>(FOCUSABLE)) : []);
+    items()[0]?.focus();
+
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        // A nested menu (user dropdown) owns its own Escape.
+        if (e.defaultPrevented || (e.target as HTMLElement | null)?.closest?.('[role="menu"]')) {
+          return;
+        }
+        e.preventDefault();
+        onClose();
+        return;
+      }
+      if (e.key !== 'Tab' || !drawer) return;
+      const list = items();
+      if (list.length === 0) return;
+      const first = list[0];
+      const last = list[list.length - 1];
+      const active = document.activeElement;
+      if (!drawer.contains(active)) {
+        // Focus escaped (e.g. clicked the backdrop): pull it back in.
+        e.preventDefault();
+        first.focus();
+      } else if (e.shiftKey && active === first) {
+        e.preventDefault();
+        last.focus();
+      } else if (!e.shiftKey && active === last) {
+        e.preventDefault();
+        first.focus();
+      }
+    };
+    document.addEventListener('keydown', onKeyDown);
+    return () => {
+      document.removeEventListener('keydown', onKeyDown);
+      if (opener?.isConnected) opener.focus();
+    };
+  }, [open, onClose, drawerRef]);
+}

From beabc4dacd4234d66b2c32ea05182791e95b84ed Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Mon, 19 Oct 2026 13:23:00 +0200
Subject: [PATCH 04/14] fix(hosting): drop invalid stored host settings at boot
 instead of crashing (#497)

merge_host_settings now builds Settings leniently: a stored value that
parses but fails validation (log_format='xml') falls back to its default
with a WARNING, keeping the other overrides. The parser and the lenient
loop move to simple_module_core.stored_settings, shared with
settings.hydrate (which re-exports RELATED_FIELDS_CTX). The i18n
default-locale model error now names both fields so the stored half can
be dropped. The stored secret key rides along in the overrides read, so
an established install opens one pre-app connection instead of two.

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 .../simple_module_core/stored_settings.py     | 102 ++++++++++++++++++
 .../simple_module_hosting/_preapp_config.py   |  48 +++------
 .../simple_module_hosting/_secret_key.py      |  10 +-
 .../simple_module_hosting/host_settings.py    |  16 ++-
 .../tests/test_preapp_invalid_values.py       |  81 ++++++++++++++
 modules/settings/settings/hydrate.py          |  67 +++---------
 6 files changed, 239 insertions(+), 85 deletions(-)
 create mode 100644 framework/core/simple_module_core/stored_settings.py
 create mode 100644 framework/hosting/tests/test_preapp_invalid_values.py

diff --git a/framework/core/simple_module_core/stored_settings.py b/framework/core/simple_module_core/stored_settings.py
new file mode 100644
index 000000000..c9c92aa28
--- /dev/null
+++ b/framework/core/simple_module_core/stored_settings.py
@@ -0,0 +1,102 @@
+"""Decode stored setting values and build a settings class from them leniently.
+
+Shared by the two places that turn ``settings_setting`` rows into a settings
+object: the hosting layer's pre-app read (``_preapp_config``), which runs
+before any module is importable as a plugin, and the settings module's
+hydrator (``settings.hydrate``). It lives in the framework because the
+framework may not import a plugin (SM009), while a plugin may import the
+framework — so one copy here keeps the two parsers from drifting.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+from pydantic import ValidationError
+from pydantic_core import ErrorDetails
+from pydantic_settings import BaseSettings
+
+__all__ = [
+    "RELATED_FIELDS_CTX",
+    "construct_leniently",
+    "parse_stored_value",
+]
+
+logger = logging.getLogger(__name__)
+
+#: ``ctx`` key on a validation error listing the *other* fields a cross-field
+#: rule depends on; raise it with ``PydanticCustomError(type, msg, {key: [...]})``.
+#: Lenient construction drops those when the reported field is not stored.
+RELATED_FIELDS_CTX = "related_fields"
+
+_TRUE = frozenset({"1", "true", "yes", "on"})
+
+
+def parse_stored_value(raw: str, value_type: str) -> Any:
+    """Decode a stored value according to its ``value_type`` label.
+
+    The five labels (``string | bool | int | float | json``) are a stable
+    stored format. Raises ``ValueError`` (``JSONDecodeError`` is one) on a
+    value that does not decode.
+    """
+    if value_type == "bool":
+        return raw.lower() in _TRUE
+    if value_type == "int":
+        return int(raw)
+    if value_type == "float":
+        return float(raw)
+    if value_type == "json":
+        return json.loads(raw)
+    return raw
+
+
+def construct_leniently[T: BaseSettings](
+    cls: type[T],
+    stored: dict[str, Any],
+    *,
+    fixed: dict[str, Any] | None = None,
+    level: int = logging.WARNING,
+) -> T:
+    """``cls(**fixed, **stored)``, dropping each stored field that fails validation.
+
+    For boot paths: a row written before a ``Literal`` or range narrowed must
+    not take every worker down, nor discard the class's other, valid stored
+    values. Each dropped field is logged at ``level`` by name and error type —
+    never the message, which may echo the value (a secret) — and falls back to
+    env/default. ``fixed`` values (not from the store) are never dropped; an
+    error that names no stored field re-raises.
+    """
+    fixed = fixed or {}
+    try:
+        return cls(**fixed, **stored)
+    except ValidationError as exc:
+        culprits = {name: err["type"] for err in exc.errors() for name in _culprits(err, stored)}
+        if not culprits:
+            raise
+        for name in sorted(culprits):
+            logger.log(
+                level,
+                "Ignoring stored value for %s.%s: it no longer validates (%s)",
+                cls.__name__,
+                name,
+                culprits[name],
+            )
+        kept = {k: v for k, v in stored.items() if k not in culprits}
+        return cls(**fixed, **kept)
+
+
+def _culprits(error: ErrorDetails, stored: dict[str, Any]) -> list[str]:
+    """The stored keys to drop so that ``error`` goes away.
+
+    The field the error is reported on, when its value came from the store.
+    Otherwise — that field is env-pinned, defaulted, or the error is
+    model-level — the stored fields the validator names under
+    ``ctx[RELATED_FIELDS_CTX]`` (#548).
+    """
+    loc = str(error["loc"][0]) if error["loc"] else None
+    if loc in stored:
+        return [loc]
+    related = (error.get("ctx") or {}).get(RELATED_FIELDS_CTX, ())
+    return [name for name in related if name in stored]
diff --git a/framework/hosting/simple_module_hosting/_preapp_config.py b/framework/hosting/simple_module_hosting/_preapp_config.py
index 009a16f89..cc18d63b9 100644
--- a/framework/hosting/simple_module_hosting/_preapp_config.py
+++ b/framework/hosting/simple_module_hosting/_preapp_config.py
@@ -22,7 +22,6 @@
 from __future__ import annotations
 
 import asyncio
-import json
 import logging
 import os
 from concurrent.futures import ThreadPoolExecutor
@@ -31,6 +30,7 @@
 from pydantic_settings import BaseSettings
 from simple_module_core.dotenv import parse_dotenv
 from simple_module_core.environments import NON_PROD_ENVIRONMENTS
+from simple_module_core.stored_settings import construct_leniently, parse_stored_value
 from sqlalchemy import inspect, text
 from sqlalchemy.ext.asyncio import create_async_engine
 from sqlalchemy.pool import NullPool
@@ -78,26 +78,6 @@ def _settings_table() -> tuple[str, str, str] | None:
         return None
 
 
-def _parse(raw: str, value_type: str) -> Any:
-    """Decode a stored value according to its ``value_type`` label.
-
-    Deliberately a local reimplementation of ``settings.hydrate._parse``
-    rather than an import of it: this runs before the app exists, and the
-    framework should not depend on a plugin being importable to read its own
-    boot configuration. The five labels are a stable stored format, not an
-    internal detail.
-    """
-    if value_type == "bool":
-        return raw.lower() in ("1", "true", "yes", "on")
-    if value_type == "int":
-        return int(raw)
-    if value_type == "float":
-        return float(raw)
-    if value_type == "json":
-        return json.loads(raw)
-    return raw
-
-
 async def _read(database_url: str) -> dict[str, tuple[str, str]]:
     """Select the ``host.*`` system-scoped overrides.
 
@@ -144,9 +124,7 @@ async def _read(database_url: str) -> dict[str, tuple[str, str]]:
     return out
 
 
-def load_host_overrides(
-    database_url: str, *, strict: bool = False
-) -> dict[str, tuple[str, str]]:
+def load_host_overrides(database_url: str, *, strict: bool = False) -> dict[str, tuple[str, str]]:
     """Return ``{field: (raw_value, value_type)}`` for host settings in the DB.
 
     Returns ``{}`` quietly when the settings module isn't installed, or when
@@ -232,8 +210,8 @@ def apply_host_overrides(
         if _env_var_for(field) in env:
             continue
         try:
-            values[field] = _parse(raw, value_type)
-        except (ValueError, json.JSONDecodeError):
+            values[field] = parse_stored_value(raw, value_type)
+        except ValueError:  # JSONDecodeError included
             # A single unparseable row must not take down the boot; the field
             # falls back to its default and the admin UI still shows the row.
             logger.warning("Ignoring unparseable host setting %r (%s)", field, value_type)
@@ -246,24 +224,32 @@ def merge_host_settings(bootstrap: BootstrapSettings | None = None) -> Settings:
     ``bootstrap`` is read from env first because it carries ``database_url``,
     which is the one value that cannot come from the database.
     """
-    from simple_module_hosting._secret_key import ensure_secret_key
+    from simple_module_hosting._secret_key import SECRET_KEY_FIELD, ensure_secret_key
 
     bootstrap = bootstrap or BootstrapSettings()
     overrides = load_host_overrides(
         bootstrap.database_url,
         strict=bootstrap.environment not in NON_PROD_ENVIRONMENTS,
     )
-    values = apply_host_overrides(overrides)
+    stored = apply_host_overrides(overrides)
     # Resolved here rather than left to the field default so an install with
     # no SM_SECRET_KEY gets a generated, persisted key instead of the shipped
     # placeholder. Passing the explicitly-set value through keeps env winning.
-    values["secret_key"] = ensure_secret_key(
+    # The stored key rode along in the read above (it is a ``host.*`` row), so
+    # an established install opens no second connection for it.
+    stored_key = overrides.get(SECRET_KEY_FIELD, (None, None))[0]
+    secret_key = ensure_secret_key(
         bootstrap.database_url,
         env_value=bootstrap.secret_key if "secret_key" in bootstrap.model_fields_set else None,
+        stored=stored_key,
     )
     # database_url is passed explicitly: BootstrapSettings.__init__ resolves
     # relative sqlite paths against the discovered project root, and
     # reconstructing Settings from env alone would redo that resolution
     # against whatever the cwd happens to be.
-    values["database_url"] = bootstrap.database_url
-    return Settings(**values)
+    fixed = {"secret_key": secret_key, "database_url": bootstrap.database_url}
+    # Lenient, like the lifespan hydration: a stored value that parses but no
+    # longer validates (a Literal narrowed in an upgrade) falls back to its
+    # default with a WARNING instead of taking down every worker — and with
+    # them the admin UI that could fix the row (#497).
+    return construct_leniently(Settings, stored, fixed=fixed)
diff --git a/framework/hosting/simple_module_hosting/_secret_key.py b/framework/hosting/simple_module_hosting/_secret_key.py
index b85a3f396..18cfb900b 100644
--- a/framework/hosting/simple_module_hosting/_secret_key.py
+++ b/framework/hosting/simple_module_hosting/_secret_key.py
@@ -122,7 +122,9 @@ async def _ensure(database_url: str) -> str | None:
         await engine.dispose()
 
 
-def ensure_secret_key(database_url: str, *, env_value: str | None = None) -> str:
+def ensure_secret_key(
+    database_url: str, *, env_value: str | None = None, stored: str | None = None
+) -> str:
     """Return the key to sign sessions with, generating one if needed.
 
     Falls back to an ephemeral generated key when the database cannot be
@@ -130,11 +132,17 @@ def ensure_secret_key(database_url: str, *, env_value: str | None = None) -> str
     build the app at all, and an app that refuses to start cannot show the
     setup wizard that fixes the database. Sessions won't survive a restart in
     that state, which is why it warns.
+
+    ``stored`` is the value the caller already read from the settings table,
+    if any; a non-empty one is returned without touching the database again.
     """
     if env_value is None:
         env_value = os.environ.get(ENV_SECRET_KEY)
     if env_value:
         return env_value
+    # Already read by the caller's pre-app select: skip the extra round trip.
+    if stored:
+        return stored
 
     try:
         with ThreadPoolExecutor(max_workers=1) as pool:
diff --git a/framework/hosting/simple_module_hosting/host_settings.py b/framework/hosting/simple_module_hosting/host_settings.py
index 143a4b2a7..e7684898f 100644
--- a/framework/hosting/simple_module_hosting/host_settings.py
+++ b/framework/hosting/simple_module_hosting/host_settings.py
@@ -16,8 +16,10 @@
 from typing import Literal
 
 from pydantic import Field, field_validator, model_validator
+from pydantic_core import PydanticCustomError
 from pydantic_settings import BaseSettings, SettingsConfigDict
 from simple_module_core.discovery import DEFAULT_AUTH_PROVIDER
+from simple_module_core.stored_settings import RELATED_FIELDS_CTX
 
 # Marks a field the running process cannot pick up without a restart, so the
 # admin UI can say so rather than letting the edit look like it took effect.
@@ -221,8 +223,16 @@ def _check_default_tenant(cls, value: str) -> str:
     @model_validator(mode="after")
     def _check_default_locale_supported(self) -> HostSettings:
         if self.i18n_default_locale not in self.i18n_supported_locales:
-            raise ValueError(
-                f"i18n_default_locale '{self.i18n_default_locale}' is not in "
-                f"i18n_supported_locales {self.i18n_supported_locales}"
+            # Model-level, so the error has no field location: the context
+            # names both halves, letting lenient boot hydration drop whichever
+            # one came from the DB instead of refusing to boot (#497).
+            raise PydanticCustomError(
+                "default_locale_unsupported",
+                "i18n_default_locale '{default}' is not in i18n_supported_locales {supported}",
+                {
+                    "default": self.i18n_default_locale,
+                    "supported": self.i18n_supported_locales,
+                    RELATED_FIELDS_CTX: ["i18n_default_locale", "i18n_supported_locales"],
+                },
             )
         return self
diff --git a/framework/hosting/tests/test_preapp_invalid_values.py b/framework/hosting/tests/test_preapp_invalid_values.py
new file mode 100644
index 000000000..bf421a815
--- /dev/null
+++ b/framework/hosting/tests/test_preapp_invalid_values.py
@@ -0,0 +1,81 @@
+"""A stored host setting that parses but no longer validates must not stop boot.
+
+Before #497 ``merge_host_settings`` called ``Settings(**values)`` unguarded, so
+one stale row — a ``Literal`` narrowed in an upgrade, say — took down every
+worker, and with them the admin UI that could fix the row.
+"""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+from pathlib import Path
+
+import pytest
+from simple_module_hosting import _secret_key
+from simple_module_hosting._preapp_config import merge_host_settings
+from simple_module_hosting.bootstrap_settings import BootstrapSettings
+
+_LOGGER = "simple_module_core.stored_settings"
+
+
+def _seed(db_path: Path, rows: list[tuple[str, str, str]]) -> str:
+    conn = sqlite3.connect(db_path)
+    conn.execute(
+        "CREATE TABLE settings_setting (id INTEGER PRIMARY KEY, scope TEXT NOT NULL, "
+        "scope_id TEXT NOT NULL, key TEXT NOT NULL, value TEXT NOT NULL, "
+        "value_type TEXT NOT NULL, UNIQUE (scope, scope_id, key))"
+    )
+    conn.executemany(
+        "INSERT INTO settings_setting (scope, scope_id, key, value, value_type) "
+        "VALUES ('system', '', ?, ?, ?)",
+        rows,
+    )
+    conn.commit()
+    conn.close()
+    return f"sqlite+aiosqlite:///{db_path}"
+
+
+@pytest.fixture(autouse=True)
+def _clean_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    for name in ("SM_LOG_FORMAT", "SM_TENANT_HEADER", "SM_SECRET_KEY", "SM_I18N_DEFAULT_LOCALE"):
+        monkeypatch.delenv(name, raising=False)
+
+
+def test_invalid_literal_boots_with_default_and_warns(
+    tmp_path: Path, caplog: pytest.LogCaptureFixture
+) -> None:
+    url = _seed(
+        tmp_path / "xml.db",
+        [("host.log_format", "xml", "string"), ("host.tenant_header", "X-T", "string")],
+    )
+    with caplog.at_level(logging.WARNING, logger=_LOGGER):
+        merged = merge_host_settings(BootstrapSettings(_env_file=None, database_url=url))
+
+    assert merged.log_format == "json"
+    assert merged.tenant_header == "X-T", "the valid sibling override must survive"
+    warned = [r.getMessage() for r in caplog.records if r.levelno == logging.WARNING]
+    assert any("log_format" in m for m in warned)
+    assert not any("xml" in m for m in warned), "never echo the stored value"
+
+
+def test_model_level_error_drops_the_stored_half(tmp_path: Path) -> None:
+    """``i18n_default_locale`` outside the supported list is a model error with
+    no field location; the related-fields context names what to drop."""
+    url = _seed(tmp_path / "locale.db", [("host.i18n_default_locale", "fr", "string")])
+    merged = merge_host_settings(BootstrapSettings(_env_file=None, database_url=url))
+    assert merged.i18n_default_locale == "en"
+
+
+def test_stored_secret_key_needs_no_second_connection(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """The key is a ``host.*`` row, so the overrides read already carries it."""
+    url = _seed(tmp_path / "key.db", [("host.secret_key", "k" * 64, "string")])
+
+    async def _no_second_trip(_url: str) -> str:
+        raise AssertionError("ensure_secret_key reopened the database")
+
+    monkeypatch.setattr(_secret_key, "_ensure", _no_second_trip)
+    merged = merge_host_settings(BootstrapSettings(_env_file=None, database_url=url))
+    assert merged.secret_key == "k" * 64
diff --git a/modules/settings/settings/hydrate.py b/modules/settings/settings/hydrate.py
index 539616cb7..9835ce420 100644
--- a/modules/settings/settings/hydrate.py
+++ b/modules/settings/settings/hydrate.py
@@ -9,13 +9,11 @@
 
 from __future__ import annotations
 
-import json
 import logging
 import types
 from typing import Union, get_args, get_origin
 
-from pydantic import BaseModel, ValidationError
-from pydantic_core import ErrorDetails
+from pydantic import BaseModel
 from pydantic_settings import (
     BaseSettings,
     DotEnvSettingsSource,
@@ -23,6 +21,11 @@
     InitSettingsSource,
     SecretsSettingsSource,
 )
+from simple_module_core.stored_settings import (
+    RELATED_FIELDS_CTX,
+    construct_leniently,
+)
+from simple_module_core.stored_settings import parse_stored_value as _parse
 from sqlalchemy.orm import Session
 
 from settings.store import SettingsStore, get_overrides_sync
@@ -31,10 +34,16 @@
 
 _SCALAR_TYPES = {bool: "bool", int: "int", float: "float"}
 
-#: ``ctx`` key on a validation error listing the *other* fields a cross-field
-#: rule depends on; raise it with ``PydanticCustomError(type, msg, {key: [...]})``.
-#: Lenient hydration drops those when the reported field is not from the DB.
-RELATED_FIELDS_CTX = "related_fields"
+# Re-exported: modules raise cross-field errors with it (``background_tasks``).
+__all__ = [
+    "RELATED_FIELDS_CTX",
+    "build_settings",
+    "env_supplied_fields",
+    "hydrate_settings",
+    "hydrate_settings_sync",
+    "input_type_for_field",
+    "value_type_for_field",
+]
 
 
 def value_type_for_field(cls: type[BaseSettings], field_name: str) -> str:
@@ -83,18 +92,6 @@ def input_type_for_field(cls: type[BaseSettings], field_name: str) -> tuple[str,
     return "json", nullable
 
 
-def _parse(raw: str, value_type: str):
-    if value_type == "bool":
-        return raw.lower() in ("1", "true", "yes", "on")
-    if value_type == "int":
-        return int(raw)
-    if value_type == "float":
-        return float(raw)
-    if value_type == "json":
-        return json.loads(raw)
-    return raw
-
-
 def env_supplied_fields(cls: type[BaseSettings]) -> frozenset[str]:
     """Fields the class's own non-init sources (env, ``.env``, secrets) answer.
 
@@ -170,37 +167,7 @@ def build_settings[T: BaseSettings](
             )
     if not lenient:
         return cls(**parsed)
-    try:
-        return cls(**parsed)
-    except ValidationError as exc:
-        culprits = {name: err["type"] for err in exc.errors() for name in _culprits(err, parsed)}
-        if not culprits:
-            raise
-        for name in sorted(culprits):
-            logger.error(
-                "Ignoring stored value for %s.%s: it no longer validates (%s)",
-                cls.__name__,
-                name,
-                # error *type* only: a validator's message may echo the value (a secret)
-                culprits[name],
-            )
-        return cls(**{k: v for k, v in parsed.items() if k not in culprits})
-
-
-def _culprits(error: ErrorDetails, parsed: dict[str, object]) -> list[str]:
-    """The stored keys to drop so that ``error`` goes away.
-
-    The field the error is reported on, when its value came from the DB.
-    Otherwise — that field is env-pinned or defaulted — the stored fields the
-    validator names under ``ctx[RELATED_FIELDS_CTX]``: a cross-field rule
-    reported on one field (so the editor shows it there) whose other half came
-    from the DB, which is the only half lenient hydration can drop (#548).
-    """
-    loc = str(error["loc"][0]) if error["loc"] else None
-    if loc in parsed:
-        return [loc]
-    related = (error.get("ctx") or {}).get(RELATED_FIELDS_CTX, ())
-    return [name for name in related if name in parsed]
+    return construct_leniently(cls, parsed, level=logging.ERROR)
 
 
 async def hydrate_settings[T: BaseSettings](

From 9d232213a21861c1f99fd0ebaeb3b048eff4eac1 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Mon, 19 Oct 2026 13:24:30 +0200
Subject: [PATCH 05/14] fix(hosting): mark build-time host settings
 requires_restart (#499)

multi_tenant, tenant_header, default_tenant, i18n_*, auth_provider,
auth_public_paths, trusted_proxy, log_level and log_format are consumed
while create_app (or host/main.py) builds the app, so an admin-UI edit
only lands after a restart. They now carry the restart marker, which the
settings editor turns into a 'Requires restart' hint. A test builds the
app on a recording Settings and asserts the marked set equals the set
create_app reads, in both directions.

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 .../simple_module_hosting/host_settings.py    | 32 +++++---
 .../tests/test_build_time_settings_marked.py  | 75 +++++++++++++++++++
 .../settings/tests-js/RestartHint.test.tsx    | 57 ++++++++++++++
 .../tests/test_settings_host_restart_flags.py | 22 ++++++
 4 files changed, 175 insertions(+), 11 deletions(-)
 create mode 100644 framework/hosting/tests/test_build_time_settings_marked.py
 create mode 100644 modules/settings/tests-js/RestartHint.test.tsx
 create mode 100644 modules/settings/tests/test_settings_host_restart_flags.py

diff --git a/framework/hosting/simple_module_hosting/host_settings.py b/framework/hosting/simple_module_hosting/host_settings.py
index e7684898f..69080688c 100644
--- a/framework/hosting/simple_module_hosting/host_settings.py
+++ b/framework/hosting/simple_module_hosting/host_settings.py
@@ -30,6 +30,16 @@
 
 _RESTART_API = {"requires_restart": True, "group": "API"}
 
+# Consumed while create_app builds the tenant middleware, the strict tenant
+# filter, the i18n registry and LocaleMiddleware, the auth provider and the
+# public-route registry, the proxy middleware and logging — none of which the
+# lifespan hydration can rebuild (#499). test_build_time_settings_marked keeps
+# this in step with what create_app actually reads.
+_RESTART_TENANCY = {"requires_restart": True, "group": "Tenancy"}
+_RESTART_I18N = {"requires_restart": True, "group": "Localization"}
+_RESTART_AUTH = {"requires_restart": True, "group": "Authentication"}
+_RESTART_LOGGING = {"requires_restart": True, "group": "Logging"}
+
 
 def _default_api_version() -> str:
     """The host project's version, else ``0.0.0``.
@@ -74,9 +84,9 @@ class HostSettings(BaseSettings):
     # that has nothing to do with this app.
     model_config = SettingsConfigDict(env_prefix="SM_", extra="ignore")
 
-    multi_tenant: bool = False
-    tenant_header: str = ""
-    default_tenant: str = ""
+    multi_tenant: bool = Field(default=False, json_schema_extra=_RESTART_TENANCY)
+    tenant_header: str = Field(default="", json_schema_extra=_RESTART_TENANCY)
+    default_tenant: str = Field(default="", json_schema_extra=_RESTART_TENANCY)
     """Single-tenant hosts (``multi_tenant`` off): the tenant every request acts
     as, so a module's ``MultiTenantMixin`` tables work without a tenant
     resolver. Ignored when ``multi_tenant`` is on — a multi-tenant install
@@ -93,12 +103,12 @@ class HostSettings(BaseSettings):
     """Optional operator note shown on the maintenance page. Empty = use the
     generic translated copy."""
 
-    i18n_default_locale: str = "en"
-    i18n_supported_locales: list[str] = ["en"]
-    i18n_cookie_name: str = "locale"
+    i18n_default_locale: str = Field(default="en", json_schema_extra=_RESTART_I18N)
+    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)
 
-    log_level: str = "INFO"
-    log_format: Literal["json", "text"] = "json"
+    log_level: str = Field(default="INFO", json_schema_extra=_RESTART_LOGGING)
+    log_format: Literal["json", "text"] = Field(default="json", json_schema_extra=_RESTART_LOGGING)
 
     # Trust the X-Forwarded-* headers from a fronting reverse proxy. Unset by
     # default (no proxy trusted). Set to ``*`` to trust any peer (correct when
@@ -114,9 +124,9 @@ class HostSettings(BaseSettings):
     # url, e.g. OAuth's callback_url and the locale cookie's `secure` flag —
     # left unset behind such a proxy, an OAuth redirect_uri ships as http://
     # and most providers reject it.
-    trusted_proxy: str | None = None
+    trusted_proxy: str | None = Field(default=None, json_schema_extra=_RESTART_GUARD)
 
-    auth_provider: str = DEFAULT_AUTH_PROVIDER
+    auth_provider: str = Field(default=DEFAULT_AUTH_PROVIDER, json_schema_extra=_RESTART_AUTH)
     """Which auth provider module to activate.
 
     ``users`` and ``keycloak`` both provide authentication and only one may be
@@ -128,7 +138,7 @@ class HostSettings(BaseSettings):
     the process restarted with a matching env var.
     """
 
-    auth_public_paths: list[str] = []
+    auth_public_paths: list[str] = Field(default=[], json_schema_extra=_RESTART_AUTH)
     """Host-level anonymous-access path prefixes.
 
     An escape hatch for exposing a route without a session when no module owns
diff --git a/framework/hosting/tests/test_build_time_settings_marked.py b/framework/hosting/tests/test_build_time_settings_marked.py
new file mode 100644
index 000000000..d18e84ab2
--- /dev/null
+++ b/framework/hosting/tests/test_build_time_settings_marked.py
@@ -0,0 +1,75 @@
+"""Every HostSettings field ``create_app`` consumes is marked ``requires_restart``.
+
+The module list, the i18n registry, the DB engine and the middleware stack are
+all built from settings before the lifespan exists, so an admin-UI edit to one
+of those fields changes nothing until the process restarts (#499). The marker
+is what makes the settings editor say so.
+
+Rather than a hand-kept list, this builds the app on a ``Settings`` that
+records every field read during ``create_app`` — so a new build-time read
+without the marker fails here. It runs twice, because some reads sit behind a
+branch (``default_tenant`` only matters when ``multi_tenant`` is off). And the
+reverse direction: a marked field that nothing reads at build time is a stale
+marker that tells operators to restart for no reason.
+"""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar
+
+import pytest
+from simple_module_hosting.app_builder import create_app
+from simple_module_hosting.host_settings import HostSettings
+from simple_module_hosting.settings import Settings
+
+# Consumed at build time outside create_app: host/main.py hands them to
+# setup_logging once, before create_app runs.
+_READ_BY_HOST_ENTRYPOINT = frozenset({"log_level", "log_format"})
+
+
+class _RecordingSettings(Settings):
+    reads: ClassVar[set[str]] = set()
+
+    def __getattribute__(self, name: str) -> Any:
+        if name in HostSettings.model_fields:
+            _RecordingSettings.reads.add(name)
+        return super().__getattribute__(name)
+
+
+def _build_reads(base: Settings, **changes: Any) -> set[str]:
+    data = base.model_dump() | changes
+    recording = _RecordingSettings.model_construct(**data)
+    _RecordingSettings.reads = set()
+    create_app(recording)  # build only — the lifespan never starts
+    return set(_RecordingSettings.reads)
+
+
+def _marked() -> set[str]:
+    out = set()
+    for name, info in HostSettings.model_fields.items():
+        extra = info.json_schema_extra
+        if isinstance(extra, dict) and extra.get("requires_restart") is True:
+            out.add(name)
+    return out
+
+
+@pytest.fixture
+def build_time_fields(settings: Settings) -> set[str]:
+    reads = _build_reads(settings)
+    reads |= _build_reads(settings, multi_tenant=False, default_tenant="acme")
+    return reads | _READ_BY_HOST_ENTRYPOINT
+
+
+def test_every_build_time_field_is_marked(build_time_fields: set[str]) -> None:
+    missing = sorted(build_time_fields - _marked())
+    assert not missing, f"read by create_app but not marked requires_restart: {missing}"
+
+
+def test_every_marked_field_is_read_at_build_time(build_time_fields: set[str]) -> None:
+    stale = sorted(_marked() - build_time_fields)
+    assert not stale, f"marked requires_restart but create_app never reads them: {stale}"
+
+
+def test_runtime_fields_stay_unmarked() -> None:
+    """Maintenance mode flips live — that is the point of storing it in the DB."""
+    assert not ({"maintenance_mode", "maintenance_message"} & _marked())
diff --git a/modules/settings/tests-js/RestartHint.test.tsx b/modules/settings/tests-js/RestartHint.test.tsx
new file mode 100644
index 000000000..57e0cec58
--- /dev/null
+++ b/modules/settings/tests-js/RestartHint.test.tsx
@@ -0,0 +1,57 @@
+import '@testing-library/jest-dom/vitest';
+import { configureI18n } from '@simple-module-py/i18n';
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, test, vi } from 'vitest';
+
+configureI18n({
+  locale: 'en',
+  messages: {
+    'settings.modules_form.save': 'Save',
+    'settings.modules_form.requires_restart': 'Requires restart',
+    'settings.modules.heading_suffix': 'settings',
+  },
+});
+
+vi.mock('@inertiajs/react', () => ({ router: { reload: vi.fn() } }));
+
+import type { FieldMeta } from '../settings/pages/components/FieldInput';
+import { ModuleForm } from '../settings/pages/components/ModuleForm';
+
+// Build-time host settings (#499): an edit only applies after a restart, and
+// the editor has to say so once the operator changes the value.
+const tenantHeader: FieldMeta = {
+  name: 'tenant_header',
+  type: 'string',
+  value: '',
+  default: '',
+  description: '',
+  is_secret: false,
+  requires_restart: true,
+  group: 'Tenancy',
+  env_var: 'SM_TENANT_HEADER',
+  env_set: false,
+  env_readable: false,
+  db_override: false,
+  choices: null,
+};
+
+describe('restart hint', () => {
+  test('appears on a requires_restart field once it is edited', () => {
+    render(
+      <ModuleForm
+        module={{
+          module_name: 'Host',
+          package: 'host',
+          env_prefix: 'SM_',
+          class_name: 'HostSettings',
+          fields: [tenantHeader],
+        }}
+      />,
+    );
+    expect(screen.queryByText('Requires restart')).not.toBeInTheDocument();
+
+    fireEvent.change(screen.getByLabelText('tenant_header'), { target: { value: 'X-Tenant' } });
+
+    expect(screen.getByText('Requires restart')).toBeVisible();
+  });
+});
diff --git a/modules/settings/tests/test_settings_host_restart_flags.py b/modules/settings/tests/test_settings_host_restart_flags.py
new file mode 100644
index 000000000..272f511b4
--- /dev/null
+++ b/modules/settings/tests/test_settings_host_restart_flags.py
@@ -0,0 +1,22 @@
+"""The settings editor receives the restart marker on build-time host fields (#499)."""
+
+from __future__ import annotations
+
+import pytest
+from settings._module_settings import _build_view
+from simple_module_hosting.host_settings import HostSettings
+
+
+@pytest.mark.parametrize(
+    "field",
+    ["multi_tenant", "tenant_header", "i18n_default_locale", "auth_provider", "log_format"],
+)
+def test_host_view_flags_build_time_field(field: str) -> None:
+    view = _build_view("Host", "host", HostSettings())
+    by_name = {f.name: f for f in view.fields}
+    assert by_name[field].requires_restart is True
+
+
+def test_host_view_leaves_runtime_field_unflagged() -> None:
+    view = _build_view("Host", "host", HostSettings())
+    assert {f.name: f for f in view.fields}["maintenance_mode"].requires_restart is False

From d1b430e62b88bcb15806bb5769e870236fb98c87 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Mon, 19 Oct 2026 13:25:56 +0200
Subject: [PATCH 06/14] fix(hosting): mark the session cookie Secure outside
 development (#495)

New HostSettings.session_cookie_secure (SM_SESSION_COOKIE_SECURE, restart
to apply). Unset means Secure everywhere but development/testing, which
keep working over http://localhost; SessionMiddleware now gets
https_only. Deployment docs cover TLS terminators (leave it on, set
SM_TRUSTED_PROXY) and plain-HTTP installs (set it false).

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 docs/reference/deployment.md                  | 15 +++-
 docs/reference/env-vars.md                    |  1 +
 .../simple_module_hosting/_phase_helpers.py   | 18 ++++-
 .../simple_module_hosting/host_settings.py    | 13 +++
 .../tests/test_session_cookie_secure.py       | 81 +++++++++++++++++++
 5 files changed, 125 insertions(+), 3 deletions(-)
 create mode 100644 framework/hosting/tests/test_session_cookie_secure.py

diff --git a/docs/reference/deployment.md b/docs/reference/deployment.md
index 068ebcb83..00f4cb4ff 100644
--- a/docs/reference/deployment.md
+++ b/docs/reference/deployment.md
@@ -14,7 +14,7 @@ Before serving traffic:
 - [ ] App boot in a non-development `SM_ENVIRONMENT` starts clean. Module discovery runs strict (missing/invalid `meta` and entry-point failures raise), and the migration check (SM010) aborts boot — so a successful start covers those. The full page/locale/auth-provider diagnostic suite only runs in development, so do a clean dev boot before shipping (see [diagnostic codes](/reference/diagnostic-codes)).
 - [ ] Admin bootstrap complete — an admin user exists and can log in.
 - [ ] Reverse proxy forwards `X-Forwarded-Proto`/`X-Forwarded-For`; configured with `--proxy-headers`.
-- [ ] HTTPS in front of the app (the session cookie is `HttpOnly`/`SameSite=Lax` but not `Secure` by default — terminate TLS at the proxy).
+- [ ] HTTPS in front of the app. Outside `development`/`testing` the session cookie is `Secure`, so a browser reaching the app over plain HTTP never sends it back and sign-in fails (see [Session cookie](#session-cookie)). Behind a TLS terminator, set `SM_TRUSTED_PROXY` too.
 - [ ] Log destination configured (`SM_LOG_FORMAT=json` + log shipping).
 
 ## Build
@@ -140,7 +140,18 @@ Not built in. The framework doesn't expose Prometheus metrics out of the box. If
 
 ## Session cookie
 
-`SessionMiddleware` uses `SM_SECRET_KEY` for signing. Starlette's defaults apply: `HttpOnly` + `SameSite=Lax`, but **not** `Secure` (the framework adds the middleware with only `secret_key`, so the cookie isn't restricted to HTTPS — rely on your TLS-terminating proxy). Rotate the secret by:
+`SessionMiddleware` uses `SM_SECRET_KEY` for signing. The cookie is `HttpOnly` + `SameSite=Lax`, and `Secure` everywhere except `SM_ENVIRONMENT=development`/`testing`, so it never travels over plain HTTP — not even on the first request before HSTS is cached. CSRF defence rests on `SameSite=Lax`, which is why this matters.
+
+The flag is the `session_cookie_secure` host setting (`SM_SESSION_COOKIE_SECURE`, or the settings editor; restart to apply). Unset means "on outside development/testing":
+
+| Deployment | What to set |
+|---|---|
+| TLS terminated at a reverse proxy, app speaks plain HTTP to the proxy | Leave it unset. The browser sees HTTPS, which is all `Secure` needs. Set `SM_TRUSTED_PROXY` so the app also sees `https` as the scheme (OAuth callback urls, the locale cookie's `secure` flag, request logs). |
+| HTTPS end to end | Leave it unset. |
+| Browsers reach the app over plain HTTP on purpose (an internal network with no TLS) | `SM_SESSION_COOKIE_SECURE=false` — otherwise the browser drops the cookie and every sign-in bounces back to the login page. |
+| Local development (`make dev`, e2e) over `http://localhost` | Nothing: development and testing default to off. |
+
+Rotate the secret by:
 
 1. Deploying with a new `SM_SECRET_KEY`.
 2. Expected behavior: existing sessions become invalid. Users sign back in.
diff --git a/docs/reference/env-vars.md b/docs/reference/env-vars.md
index eaa038ce6..711520218 100644
--- a/docs/reference/env-vars.md
+++ b/docs/reference/env-vars.md
@@ -20,6 +20,7 @@ This is the full reference. See [Configuration](/guide/configuration) for a narr
 | `SM_PROJECT_ROOT` | unset | Overrides project-root discovery: where the `.env` is looked up and what relative sqlite paths resolve against. Normally unnecessary — settings walk up from the cwd (stopping at repo boundaries and `$HOME`) to find the `.env` on their own. |
 | `SM_AUTH_PUBLIC_PATHS` | `[]` | JSON array of host-level anonymous-access path prefixes. Escape hatch for exposing a route without a session when no module owns it; modules should prefer the method-aware `register_public_routes` hook. |
 | `SM_TRUSTED_PROXY` | unset | Comma-separated proxy IPs / CIDRs whose `X-Forwarded-*` headers are trusted, or `*` to trust any peer (correct when the container is only reachable through one proxy). Setting it installs uvicorn's `ProxyHeadersMiddleware` outermost, so request logs record the real client IP and `request.url.scheme` reflects `X-Forwarded-Proto`. **Recommended behind a TLS-terminating proxy**, where otherwise every request in the logs is attributed to the proxy's own address rather than the visitor's. It is no longer needed for Inertia: the page url is root-relative, so `pushState` can't see a cross-scheme url whatever the proxy sends (it used to throw a `SecurityError` on every page — GH #223). It is still needed for anything that builds an absolute url from `request.url.scheme`/`request.url_for(...)` — notably OAuth/OIDC's callback url and the locale cookie's `secure` flag — left unset behind such a proxy, an OAuth `redirect_uri` ships as `http://…` and most providers reject it. Forwarded headers are never trusted by default. |
+| `SM_SESSION_COOKIE_SECURE` | unset | Mark the session cookie `Secure`. Unset means on everywhere except `SM_ENVIRONMENT=development`/`testing`. Set `false` only for an install that serves browsers plain HTTP on purpose; behind a TLS terminator leave it unset and set `SM_TRUSTED_PROXY`. Restart to apply. |
 
 ## DB connection pool
 
diff --git a/framework/hosting/simple_module_hosting/_phase_helpers.py b/framework/hosting/simple_module_hosting/_phase_helpers.py
index fad84f834..d8e7a48c3 100644
--- a/framework/hosting/simple_module_hosting/_phase_helpers.py
+++ b/framework/hosting/simple_module_hosting/_phase_helpers.py
@@ -14,6 +14,7 @@
 from fastapi import FastAPI
 from fastapi.exceptions import RequestValidationError
 from fastapi.staticfiles import StaticFiles
+from simple_module_core.environments import NON_PROD_ENVIRONMENTS
 from simple_module_core.exceptions import NotFoundError
 from simple_module_db import CommitBeforeResponseMiddleware
 from simple_module_inertia import (
@@ -98,6 +99,17 @@ def build_csp(settings: Settings, csp_registry: CspSourceRegistry) -> str:
     return csp_registry.extend_policy(base)
 
 
+def session_cookie_is_secure(settings: Settings) -> bool:
+    """Whether the session cookie carries ``Secure`` (#495).
+
+    ``session_cookie_secure`` wins when set; unset, the cookie is ``Secure``
+    everywhere but the non-prod environments, which run over plain HTTP.
+    """
+    if settings.session_cookie_secure is not None:
+        return settings.session_cookie_secure
+    return settings.environment not in NON_PROD_ENVIRONMENTS
+
+
 def install_middleware(
     app: FastAPI,
     settings: Settings,
@@ -167,7 +179,11 @@ def install_middleware(
         app.add_middleware(TenantMiddleware, fixed=settings.default_tenant)
     for mod in modules:
         mod.register_middleware(app)
-    app.add_middleware(SessionMiddleware, secret_key=settings.secret_key)
+    app.add_middleware(
+        SessionMiddleware,
+        secret_key=settings.secret_key,
+        https_only=session_cookie_is_secure(settings),
+    )
     # In dev, relax CSP so the browser can fetch @vite/client, main.tsx, and
     # the HMR WebSocket from the Vite origin (build_csp picks the variant).
     # HSTS is suppressed in dev because it runs over plain HTTP on loopback.
diff --git a/framework/hosting/simple_module_hosting/host_settings.py b/framework/hosting/simple_module_hosting/host_settings.py
index 69080688c..2a8723d73 100644
--- a/framework/hosting/simple_module_hosting/host_settings.py
+++ b/framework/hosting/simple_module_hosting/host_settings.py
@@ -126,6 +126,19 @@ class HostSettings(BaseSettings):
     # and most providers reject it.
     trusted_proxy: str | None = Field(default=None, json_schema_extra=_RESTART_GUARD)
 
+    session_cookie_secure: bool | None = Field(
+        default=None, json_schema_extra={"requires_restart": True, "group": "Security"}
+    )
+    """Mark the session cookie ``Secure`` (sent over HTTPS only).
+
+    Unset (the default) means on outside development and testing, off in
+    them, so ``make dev`` keeps working over plain ``http://localhost``. Behind
+    a TLS-terminating proxy leave it on: the browser sees HTTPS, which is all
+    the flag needs. Only an install that serves browsers plain HTTP on purpose
+    should turn it off — otherwise the cookie is never sent back and sign-in
+    silently fails. See ``session_cookie_is_secure``.
+    """
+
     auth_provider: str = Field(default=DEFAULT_AUTH_PROVIDER, json_schema_extra=_RESTART_AUTH)
     """Which auth provider module to activate.
 
diff --git a/framework/hosting/tests/test_session_cookie_secure.py b/framework/hosting/tests/test_session_cookie_secure.py
new file mode 100644
index 000000000..661863bd0
--- /dev/null
+++ b/framework/hosting/tests/test_session_cookie_secure.py
@@ -0,0 +1,81 @@
+"""The session cookie is ``Secure`` outside development (#495).
+
+CSRF defence rests on ``SameSite=Lax`` alone, so a session cookie that can
+travel over plain HTTP — the first request before HSTS is cached, a
+misconfigured proxy — undermines it. Development and testing run on
+``http://localhost`` and keep the cookie usable there.
+"""
+
+from __future__ import annotations
+
+import httpx
+import pytest
+from fastapi import Request
+from simple_module_hosting._phase_helpers import session_cookie_is_secure
+from simple_module_hosting.settings import Settings
+from simple_module_test.database import database_url_for_tests
+
+_PROBE = "/__session_probe"
+
+
+def _settings(**overrides: object) -> Settings:
+    return Settings(
+        database_url=database_url_for_tests(),
+        environment="testing",
+        secret_key="test-secret-key",
+        auth_provider="users",
+        **overrides,
+    )
+
+
+@pytest.mark.parametrize(
+    ("environment", "explicit", "expected"),
+    [
+        ("production", None, True),
+        ("staging", None, True),
+        ("development", None, False),
+        ("testing", None, False),
+        ("production", False, False),  # plain-HTTP install opting out
+        ("development", True, True),
+    ],
+)
+def test_secure_resolution(environment: str, explicit: bool | None, expected: bool) -> None:
+    settings = Settings.model_construct(environment=environment, session_cookie_secure=explicit)
+    assert session_cookie_is_secure(settings) is expected
+
+
+async def _session_set_cookie(app) -> str:
+    async def probe(request: Request) -> dict[str, bool]:
+        request.session["probe"] = True
+        return {"ok": True}
+
+    app.add_api_route(_PROBE, probe)
+    app.state.public_routes.add_exact(_PROBE)
+    transport = httpx.ASGITransport(app=app)
+    async with httpx.AsyncClient(transport=transport, base_url="http://test") as client:
+        resp = await client.get(_PROBE)
+    assert resp.status_code == 200, resp.text
+    cookies = [c for c in resp.headers.get_list("set-cookie") if c.startswith("session=")]
+    assert cookies, resp.headers
+    return cookies[0].lower()
+
+
+class TestSecureCookieOn:
+    @pytest.fixture
+    def settings(self) -> Settings:
+        return _settings(session_cookie_secure=True)
+
+    async def test_set_cookie_is_secure(self, app) -> None:
+        cookie = await _session_set_cookie(app)
+        assert "; secure" in cookie
+        assert "httponly" in cookie and "samesite=lax" in cookie
+
+
+class TestSecureCookieDefaultInTesting:
+    @pytest.fixture
+    def settings(self) -> Settings:
+        return _settings()
+
+    async def test_set_cookie_is_not_secure_over_local_http(self, app) -> None:
+        cookie = await _session_set_cookie(app)
+        assert "; secure" not in cookie

From a77948ac403b95176221ae1e659895bb74261542 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Mon, 19 Oct 2026 13:34:37 +0200
Subject: [PATCH 07/14] fix(db): bind the audit sink per engine and audit
 Celery task writes (#498)

The audit callback lived in a module-level DatabaseState global that only
create_app set, so worker writes were never audited and the last app built
in a process won.

- listeners read audit_callback from the policy bound to the flushing
  session's engine (DatabaseState / EngineTenancy), like tenancy does.
- EngineTenancy gains audit_callback; simple_module_db.audit_sinks discovers
  sinks from the new "simple_module.audit_sinks" entry point, which audit_log
  publishes. background_tasks binds it to both worker engines (sync_db and
  the outbox worker) without importing audit_log.
- correlation_id ContextVar moves to simple_module_core.correlation
  (re-exported by simple_module_hosting.logging): db no longer imports hosting.
- Docs: worker capture and known gaps (bulk/Core DML, text() DML, outbox
  bulk UPDATEs).

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 docs/modules/audit_log.md                     |  23 ++-
 .../core/simple_module_core/correlation.py    |  12 ++
 framework/db/simple_module_db/audit_sinks.py  |  59 ++++++++
 framework/db/simple_module_db/listeners.py    |  37 ++---
 framework/db/simple_module_db/query_filter.py |  22 ++-
 framework/db/tests/test_audit_per_engine.py   | 134 ++++++++++++++++++
 .../hosting/simple_module_hosting/logging.py  |   4 +-
 modules/audit_log/pyproject.toml              |   5 +
 .../background_tasks/sync_db.py               |  13 +-
 modules/background_tasks/tests/conftest.py    |  12 ++
 .../tests/test_bg_worker_audit.py             | 129 +++++++++++++++++
 .../tests/test_file_storage_upload_tasks.py   |   2 +
 12 files changed, 425 insertions(+), 27 deletions(-)
 create mode 100644 framework/core/simple_module_core/correlation.py
 create mode 100644 framework/db/simple_module_db/audit_sinks.py
 create mode 100644 framework/db/tests/test_audit_per_engine.py
 create mode 100644 modules/background_tasks/tests/test_bg_worker_audit.py

diff --git a/docs/modules/audit_log.md b/docs/modules/audit_log.md
index 94e39a6a4..0e93bf72c 100644
--- a/docs/modules/audit_log.md
+++ b/docs/modules/audit_log.md
@@ -13,14 +13,33 @@ Automatic field-level audit trail for every SQLModel entity in the app. Each cre
 
 ## How capture works
 
-The module doesn't observe changes itself — the DB layer does. On `on_startup` it sets `app.state.sm.db.audit_callback = audit_callback`; on `on_shutdown` it clears it. While that callback is set, the framework's session listeners run a **two-phase capture**:
+The module doesn't observe changes itself — the DB layer does. On `on_startup` it sets `app.state.sm.db.audit_callback = audit_callback`; on `on_shutdown` it clears it. The callback is read from the policy bound to the flushing session's **engine** (`DatabaseState` for an app, `EngineTenancy` for a bare engine), never from a process global, so two apps in one process each audit through their own sink and shutting one down leaves the other capturing. While that callback is set, the framework's session listeners run a **two-phase capture**:
 
 1. **Phase 1 — `before_flush`.** `snapshot_changes()` walks `session.new` / `session.dirty` / `session.deleted` and records a diff *while SQLAlchemy attribute history is still intact* (it gets wiped after flush). For new rows the diff holds an object reference, not an id, because a DB-assigned PK (e.g. an integer `AUTOINCREMENT` / `SERIAL` id) isn't populated yet. The pending list is stashed on `session.info`.
 2. **Phase 2 — `after_flush_postexec`.** Once INSERTs have executed and PKs are populated on the live objects, `finalize_records()` resolves the now-stable `entity_id` and hands the records to the module's `audit_callback`, which turns each into an `AuditEntry` row.
 
 The two-phase split is why integer-PK entities record the real id instead of an empty string. `AuditEntry` itself sets `__audit_exclude__ = True`, so writing audit rows doesn't recursively produce more audit rows.
 
-The `user_id` comes from the `current_user_id` ContextVar that `AuthMiddleware` sets per request; the `correlation_id` comes from the request-logging correlation-id ContextVar when the hosting layer is present (both are `None` outside a request, e.g. CLI / background writes).
+The `user_id` comes from the `current_user_id` ContextVar that `AuthMiddleware` sets per request; the `correlation_id` comes from `simple_module_core.correlation.correlation_id` (re-exported as `simple_module_hosting.logging.correlation_id`), which the request-logging middleware sets (both are `None` outside a request unless the caller sets them).
+
+### Writes made by Celery tasks
+
+A worker never runs `create_app`, so it has no `app.state.sm.db` for `on_startup` to set. The module also publishes its callback as an entry point:
+
+```toml
+[project.entry-points."simple_module.audit_sinks"]
+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
+
+Capture sees only what the ORM unit of work flushes. These writes are **not** audited, in requests or in workers:
+
+- 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.
 
 ### What gets recorded
 
diff --git a/framework/core/simple_module_core/correlation.py b/framework/core/simple_module_core/correlation.py
new file mode 100644
index 000000000..1bcd0c273
--- /dev/null
+++ b/framework/core/simple_module_core/correlation.py
@@ -0,0 +1,12 @@
+"""The request/task correlation id, shared by every layer.
+
+Lives in core rather than ``simple_module_hosting.logging`` (which re-exports
+it) so the db layer can stamp audit records with it without importing the
+hosting package (#498).
+"""
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+
+correlation_id: ContextVar[str] = ContextVar("correlation_id", default="")
diff --git a/framework/db/simple_module_db/audit_sinks.py b/framework/db/simple_module_db/audit_sinks.py
new file mode 100644
index 000000000..6bcd973df
--- /dev/null
+++ b/framework/db/simple_module_db/audit_sinks.py
@@ -0,0 +1,59 @@
+"""Audit sinks published through the ``simple_module.audit_sinks`` entry point.
+
+A web process gets its audit sink from the module that owns it (``audit_log``
+sets ``DatabaseState.audit_callback`` on startup). A process that never builds
+the app — the Celery worker — has no ``DatabaseState`` to read, so it asks
+the installed distributions instead: a module that stores audit records
+declares::
+
+    [project.entry-points."simple_module.audit_sinks"]
+    audit_log = "audit_log.capture:audit_callback"
+
+and the worker binds the result to its engine with
+``EngineTenancy(audit_callback=...)``. Neither side imports the other (#498).
+"""
+
+from __future__ import annotations
+
+import functools
+import logging
+from collections.abc import Callable
+from importlib.metadata import entry_points
+
+from sqlalchemy.orm import Session
+
+from simple_module_db.audit import AuditRecord
+
+AUDIT_SINK_ENTRY_POINT_GROUP = "simple_module.audit_sinks"
+
+AuditCallback = Callable[[Session, list[AuditRecord]], None]
+
+logger = logging.getLogger(__name__)
+
+
+@functools.cache
+def discover_audit_callback() -> AuditCallback | None:
+    """The installed audit sinks as one callback, or ``None`` if there are none.
+
+    Cached: the installed distributions do not change while a process runs
+    (``discover_audit_callback.cache_clear()`` in tests). A sink that fails to
+    import is logged and skipped: auditing is lost for that sink, but the
+    worker still boots and runs its tasks.
+    """
+    sinks: list[AuditCallback] = []
+    found = entry_points(group=AUDIT_SINK_ENTRY_POINT_GROUP)
+    for ep in sorted(found, key=lambda e: e.name):
+        try:
+            sinks.append(ep.load())
+        except Exception:
+            logger.exception("Could not load audit sink %r (%s)", ep.name, ep.value)
+    if not sinks:
+        return None
+    if len(sinks) == 1:
+        return sinks[0]
+
+    def _fan_out(session: Session, records: list[AuditRecord]) -> None:
+        for sink in sinks:
+            sink(session, records)
+
+    return _fan_out
diff --git a/framework/db/simple_module_db/listeners.py b/framework/db/simple_module_db/listeners.py
index b328c642f..569a98d64 100644
--- a/framework/db/simple_module_db/listeners.py
+++ b/framework/db/simple_module_db/listeners.py
@@ -3,16 +3,18 @@
 from __future__ import annotations
 
 import logging
+from collections.abc import Callable
 from contextvars import ContextVar
 from datetime import UTC, datetime
 
+from simple_module_core.correlation import correlation_id
 from sqlalchemy import event
 from sqlalchemy import inspect as sa_inspect
 from sqlalchemy.orm import Session
 
 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, filter_statements
+from simple_module_db.query_filter import bind_engine_policy, engine_policy, filter_statements
 from simple_module_db.session import DatabaseState
 from simple_module_db.writes import (
     _HARD_DELETE_KEY,
@@ -54,8 +56,6 @@
 _EVENT_ENTITY_SOFT_DELETED = "db.entity.soft_deleted"
 _EVENT_ENTITY_DELETED = "db.entity.deleted"
 
-_db_state: DatabaseState | None = None
-
 # DB operation strings used in log extra dicts
 _OP_CREATE = "create"
 _OP_UPDATE = "update"
@@ -94,9 +94,9 @@ def register_listeners(db_state: DatabaseState) -> None:
         logger.debug("Listeners already registered, skipping")
         return
 
-    global _db_state
-    _db_state = db_state
-    # Strict mode is read from db_state at query time, per engine.
+    # Strict mode and the audit sink are read from db_state at flush/query
+    # time, per engine — never from a process global, so two apps in one
+    # process cannot see each other's audit callback (#498).
     bind_engine_policy(db_state.engine.sync_engine, db_state)
     attach_session_listeners(db_state.sync_session_class)
     db_state._listeners_registered = True
@@ -107,7 +107,8 @@ def attach_session_listeners(session_class: type[Session]) -> None:
     """Attach the entity listeners to a session class; idempotent.
 
     For a process with no ``DatabaseState`` (the Celery worker's sync engine),
-    call this and ``bind_engine_policy(engine, EngineTenancy(...))``.
+    call this and ``bind_engine_policy(engine, EngineTenancy(...))``; pass
+    ``audit_callback`` there to audit that engine's writes.
 
     Idempotence is a marker in the ``__dict__`` of the class or a base, not
     ``event.contains``: SQLAlchemy keys its event registry on ``id(target)``,
@@ -211,22 +212,21 @@ def _before_flush_listener(
     # Audit phase 1: snapshot diffs while attribute history is still available.
     # entity_id resolution is deferred to after_flush_postexec because
     # DB-assigned integer PKs aren't populated until the INSERT executes.
-    if _db_state is not None and _db_state.audit_callback is not None:
+    if _audit_callback(session) is not None:
         from simple_module_db.audit import snapshot_changes
 
-        correlation_id_val: str | None = None
-        try:
-            from simple_module_hosting.logging import correlation_id as _cid_var
-
-            correlation_id_val = _cid_var.get("") or None
-        except ImportError:
-            pass
-
+        correlation_id_val = correlation_id.get("") or None
         pending = snapshot_changes(session, user_id, correlation_id_val)
         if pending:
             session.info[_AUDIT_PENDING_KEY] = pending
 
 
+def _audit_callback(session: Session) -> Callable[[Session, list], None] | None:
+    """The audit sink bound to this session's engine (``DatabaseState`` or
+    ``EngineTenancy``), or ``None`` when that engine is not audited."""
+    return getattr(engine_policy(session), "audit_callback", None)
+
+
 def _after_flush_audit(session: Session, flush_context: object) -> None:
     """Phase 2: finalize audit records now that DB-assigned PKs are populated.
 
@@ -236,7 +236,8 @@ def _after_flush_audit(session: Session, flush_context: object) -> None:
     autoflush). The recursion guard relies on AuditEntry having
     ``__audit_exclude__ = True`` so its own flush produces no pending records.
     """
-    if _db_state is None or _db_state.audit_callback is None:
+    callback = _audit_callback(session)
+    if callback is None:
         return
     pending = session.info.pop(_AUDIT_PENDING_KEY, None)
     if not pending:
@@ -245,4 +246,4 @@ def _after_flush_audit(session: Session, flush_context: object) -> None:
 
     records = finalize_records(pending)
     if records:
-        _db_state.audit_callback(session, records)
+        callback(session, records)
diff --git a/framework/db/simple_module_db/query_filter.py b/framework/db/simple_module_db/query_filter.py
index 8efdd0b34..f50e3774a 100644
--- a/framework/db/simple_module_db/query_filter.py
+++ b/framework/db/simple_module_db/query_filter.py
@@ -11,6 +11,7 @@
 
 from __future__ import annotations
 
+from collections.abc import Callable
 from typing import Any
 from weakref import WeakKeyDictionary
 
@@ -43,11 +44,22 @@
 
 
 class EngineTenancy:
-    """Tenancy policy for an engine that has no ``DatabaseState``."""
+    """Engine policy for an engine that has no ``DatabaseState``.
 
-    def __init__(self, *, tenant_strict: bool, default_tenant_id: str = DEFAULT_TENANT_ID) -> None:
+    ``audit_callback`` is the same sink a ``DatabaseState`` carries: writes made
+    through this engine are audited only when it is set (#498).
+    """
+
+    def __init__(
+        self,
+        *,
+        tenant_strict: bool,
+        default_tenant_id: str = DEFAULT_TENANT_ID,
+        audit_callback: Callable[..., None] | None = None,
+    ) -> None:
         self.tenant_strict = tenant_strict
         self.default_tenant_id = default_tenant_id
+        self.audit_callback = audit_callback
 
 
 def bind_engine_policy(engine: Engine, policy: Any) -> None:
@@ -55,11 +67,15 @@ def bind_engine_policy(engine: Engine, policy: Any) -> None:
     _engine_policy[engine] = policy
 
 
-def _policy(session: Session) -> Any:
+def engine_policy(session: Session) -> Any:
+    """The policy bound to this session's engine, or ``None``."""
     bind = session.bind
     return _engine_policy.get(bind) if isinstance(bind, Engine) else None
 
 
+_policy = engine_policy
+
+
 def strict_configured(session: Session) -> bool:
     policy = _policy(session)
     return bool(policy is not None and policy.tenant_strict)
diff --git a/framework/db/tests/test_audit_per_engine.py b/framework/db/tests/test_audit_per_engine.py
new file mode 100644
index 000000000..a9ce000d4
--- /dev/null
+++ b/framework/db/tests/test_audit_per_engine.py
@@ -0,0 +1,134 @@
+"""The audit sink is bound per engine, never process-wide (#498).
+
+``create_app`` builds one ``DatabaseState`` per app; ``register_listeners``
+binds it to that app's engine. Two apps in one process (tests, a CLI next to
+an app) must each audit through their own sink, and a bare sync engine (the
+Celery worker's) is audited only when its ``EngineTenancy`` names a sink.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator
+
+import pytest
+from _audit_models import AuditBase, AuditTestItem
+from simple_module_core.correlation import correlation_id
+from simple_module_db.audit import AuditRecord
+from simple_module_db.listeners import attach_session_listeners, register_listeners
+from simple_module_db.query_filter import EngineTenancy, bind_engine_policy
+from simple_module_db.session import DatabaseState, init_db
+from sqlalchemy import create_engine
+from sqlalchemy.orm import Session, sessionmaker
+
+
+class _Recorder:
+    def __init__(self) -> None:
+        self.records: list[AuditRecord] = []
+
+    def __call__(self, session: Session, records: list[AuditRecord]) -> None:
+        self.records.extend(records)
+
+
+async def _state(callback: _Recorder | None) -> DatabaseState:
+    state = init_db("sqlite+aiosqlite:///:memory:")
+    state.audit_callback = callback
+    register_listeners(state)
+    async with state.engine.begin() as conn:
+        await conn.run_sync(AuditBase.metadata.create_all)
+    return state
+
+
+async def _write(state: DatabaseState, name: str) -> None:
+    async with state.session_factory() as session:
+        session.add(AuditTestItem(name=name))
+        await session.commit()
+
+
+@pytest.fixture
+async def two_apps() -> AsyncGenerator[tuple[DatabaseState, DatabaseState, _Recorder]]:
+    """App A audits; app B (built second, so the old global's winner) does not."""
+    recorder = _Recorder()
+    a = await _state(recorder)
+    b = await _state(None)
+    try:
+        yield a, b, recorder
+    finally:
+        await a.engine.dispose()
+        await b.engine.dispose()
+
+
+async def test_a_later_app_without_auditing_does_not_switch_off_the_first(two_apps):
+    a, _b, recorder = two_apps
+    await _write(a, "from-a")
+    assert [(r.entity_type, r.action) for r in recorder.records] == [("AuditTestItem", "created")]
+
+
+async def test_the_unaudited_app_does_not_reach_the_other_apps_sink(two_apps):
+    _a, b, recorder = two_apps
+    await _write(b, "from-b")
+    assert recorder.records == []
+
+
+async def test_shutting_down_one_apps_audit_leaves_the_other_alone(two_apps):
+    a, b, recorder = two_apps
+    b.audit_callback = None  # what audit_log's on_shutdown does to its app
+    await _write(a, "still-audited")
+    assert len(recorder.records) == 1
+
+
+async def test_two_audited_apps_keep_their_own_sinks():
+    first, second = _Recorder(), _Recorder()
+    a, b = await _state(first), await _state(second)
+    try:
+        await _write(a, "a1")
+        await _write(b, "b1")
+        await _write(b, "b2")
+    finally:
+        await a.engine.dispose()
+        await b.engine.dispose()
+    assert (len(first.records), len(second.records)) == (1, 2)
+
+
+class _BareSession(Session):
+    """A worker-style session class with no ``DatabaseState`` behind it."""
+
+
+def _bare_factory(callback: _Recorder | None) -> sessionmaker[Session]:
+    engine = create_engine("sqlite://")
+    AuditBase.metadata.create_all(engine)
+    attach_session_listeners(_BareSession)
+    bind_engine_policy(engine, EngineTenancy(tenant_strict=False, audit_callback=callback))
+    return sessionmaker(bind=engine, class_=_BareSession)
+
+
+def test_a_bare_engine_is_audited_through_its_engine_tenancy():
+    recorder = _Recorder()
+    factory = _bare_factory(recorder)
+    token = correlation_id.set("job-42")
+    try:
+        with factory() as session:
+            session.add(AuditTestItem(name="worker"))
+            session.commit()
+    finally:
+        correlation_id.reset(token)
+    [record] = recorder.records
+    assert (record.entity_type, record.action, record.correlation_id) == (
+        "AuditTestItem",
+        "created",
+        "job-42",
+    )
+
+
+def test_a_bare_engine_without_a_sink_is_not_audited():
+    recorder = _Recorder()
+    _bare_factory(recorder)  # a sibling engine that *is* audited
+    with _bare_factory(None)() as session:
+        session.add(AuditTestItem(name="quiet"))
+        session.commit()
+    assert recorder.records == []
+
+
+def test_hosting_reexports_the_core_correlation_id():
+    from simple_module_hosting.logging import correlation_id as hosting_cid
+
+    assert hosting_cid is correlation_id
diff --git a/framework/hosting/simple_module_hosting/logging.py b/framework/hosting/simple_module_hosting/logging.py
index 8485687f4..a48b9f6c4 100644
--- a/framework/hosting/simple_module_hosting/logging.py
+++ b/framework/hosting/simple_module_hosting/logging.py
@@ -5,10 +5,10 @@
 import json
 import logging
 import sys
-from contextvars import ContextVar
 from datetime import UTC, datetime
 
-correlation_id: ContextVar[str] = ContextVar("correlation_id", default="")
+# Defined in core so the db layer can read it without importing hosting.
+from simple_module_core.correlation import correlation_id
 
 
 class _CorrelationIdFilter(logging.Filter):
diff --git a/modules/audit_log/pyproject.toml b/modules/audit_log/pyproject.toml
index 61293f8f5..cd542cb1c 100644
--- a/modules/audit_log/pyproject.toml
+++ b/modules/audit_log/pyproject.toml
@@ -33,6 +33,11 @@ dependencies = [
 [project.entry-points.simple_module]
 audit_log = "audit_log.module:AuditLogModule"
 
+# Read by processes that never build the app (the Celery worker), so their
+# writes are audited too (#498). See ``simple_module_db.audit_sinks``.
+[project.entry-points."simple_module.audit_sinks"]
+audit_log = "audit_log.capture:audit_callback"
+
 [project.urls]
 Homepage = "https://github.com/antosubash/simple_module_python"
 Repository = "https://github.com/antosubash/simple_module_python"
diff --git a/modules/background_tasks/background_tasks/sync_db.py b/modules/background_tasks/background_tasks/sync_db.py
index 76056ea79..05865445e 100644
--- a/modules/background_tasks/background_tasks/sync_db.py
+++ b/modules/background_tasks/background_tasks/sync_db.py
@@ -20,6 +20,7 @@
 
 from celery.signals import worker_process_init
 from simple_module_db import DEFAULT_TENANT_ID
+from simple_module_db.audit_sinks import discover_audit_callback
 from simple_module_db.listeners import attach_session_listeners
 from simple_module_db.query_filter import EngineTenancy, bind_engine_policy
 from sqlalchemy import create_engine
@@ -121,9 +122,17 @@ def async_database_url() -> str:
 
 
 def engine_tenancy() -> EngineTenancy:
-    """The tenancy policy worker engines run with (mirrors the host's)."""
+    """The policy worker engines run with (mirrors the host's).
+
+    Includes the installed audit sink, so a task's writes are audited exactly
+    as a request's are when ``audit_log`` is installed (#498). It comes from
+    the ``simple_module.audit_sinks`` entry point, not an import: this module
+    does not depend on ``audit_log``.
+    """
     return EngineTenancy(
-        tenant_strict=_tenant_strict, default_tenant_id=_default_tenant or DEFAULT_TENANT_ID
+        tenant_strict=_tenant_strict,
+        default_tenant_id=_default_tenant or DEFAULT_TENANT_ID,
+        audit_callback=discover_audit_callback(),
     )
 
 
diff --git a/modules/background_tasks/tests/conftest.py b/modules/background_tasks/tests/conftest.py
index 27ab94c50..4316528d9 100644
--- a/modules/background_tasks/tests/conftest.py
+++ b/modules/background_tasks/tests/conftest.py
@@ -15,6 +15,18 @@
 from sqlalchemy import select
 
 
+@pytest.fixture(autouse=True)
+def _no_worker_audit_sink(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Build worker engines without the installed audit sink (#498).
+
+    ``audit_log`` is installed in this workspace, so a worker engine would
+    write an ``AuditEntry`` for every ``TaskExecution`` — into the bare
+    per-test databases here, which have no audit table. The worker-audit
+    suite puts the real discovery back.
+    """
+    monkeypatch.setattr(sync_db, "discover_audit_callback", lambda: None)
+
+
 @pytest.fixture
 async def _stub_celery(app) -> None:
     """Replace the real Celery instance with a MagicMock.
diff --git a/modules/background_tasks/tests/test_bg_worker_audit.py b/modules/background_tasks/tests/test_bg_worker_audit.py
new file mode 100644
index 000000000..6d14248e3
--- /dev/null
+++ b/modules/background_tasks/tests/test_bg_worker_audit.py
@@ -0,0 +1,129 @@
+"""A Celery task's writes are audited like a request's (#498).
+
+The worker never runs ``create_app``, so no ``DatabaseState`` carries the
+audit sink there. ``sync_db`` binds the installed sink (the
+``simple_module.audit_sinks`` entry point ``audit_log`` publishes) to its own
+engine instead.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+import pytest
+from background_tasks import sync_db
+from celery import Celery
+from simple_module_db import create_module_base
+from simple_module_db.audit_sinks import discover_audit_callback
+from sqlalchemy import create_engine, select
+from sqlmodel import Field
+
+audit_models = pytest.importorskip("audit_log.models")
+AuditEntry = audit_models.AuditEntry
+
+_Base = create_module_base("bgaudit")
+
+
+class BgAuditWidget(_Base, table=True):  # ty: ignore[unsupported-base]
+    __tablename__ = "bgaudit_widget"
+    id: int | None = Field(default=None, primary_key=True)
+    name: str = Field(max_length=50)
+
+
+@pytest.fixture
+def worker_db(tmp_path, monkeypatch: pytest.MonkeyPatch) -> Iterator[str]:
+    # The conftest strips the sink from worker engines; this suite wants it.
+    monkeypatch.setattr(sync_db, "discover_audit_callback", discover_audit_callback)
+    url = f"sqlite:///{tmp_path}/worker_audit.db"
+    engine = create_engine(url)
+    _Base.metadata.create_all(engine)
+    AuditEntry.metadata.create_all(engine)
+    engine.dispose()
+    sync_db.set_database_url(url)
+    yield url
+    sync_db.dispose_sync_engine()
+
+
+@pytest.fixture
+def eager_celery() -> Celery:
+    celery = Celery("bg_worker_audit")
+    celery.conf.update(task_always_eager=True, task_eager_propagates=True)
+    return celery
+
+
+def _audit_rows() -> list[tuple[str, str, str]]:
+    with sync_db.sync_session() as s:
+        rows = s.execute(select(AuditEntry.entity_type, AuditEntry.entity_id, AuditEntry.action))
+        return [tuple(r) for r in rows]
+
+
+def test_the_audit_log_publishes_its_sink() -> None:
+    from audit_log.capture import audit_callback
+
+    assert discover_audit_callback() is audit_callback
+
+
+def test_an_eager_task_write_produces_an_audit_row(worker_db, eager_celery) -> None:
+    @eager_celery.task(name="bgaudit.create_widget")
+    def create_widget(name: str) -> int | None:
+        with sync_db.sync_session() as s:
+            widget = BgAuditWidget(name=name)
+            s.add(widget)
+            s.flush()
+            return widget.id
+
+    widget_id = create_widget.delay("gear").get()
+
+    assert _audit_rows() == [("BgAuditWidget", str(widget_id), "created")]
+
+
+def test_updates_and_deletes_in_a_task_are_audited(worker_db, eager_celery) -> None:
+    with sync_db.sync_session() as s:
+        widget = BgAuditWidget(name="old")
+        s.add(widget)
+    widget_id = widget.id
+
+    @eager_celery.task(name="bgaudit.rename_then_delete")
+    def rename_then_delete(pk: int) -> None:
+        with sync_db.sync_session() as s:
+            row = s.get(BgAuditWidget, pk)
+            row.name = "new"
+        with sync_db.sync_session() as s:
+            s.delete(s.get(BgAuditWidget, pk))
+
+    rename_then_delete.delay(widget_id).get()
+
+    rows = _audit_rows()
+    assert {entity for entity, _, _ in rows} == {"BgAuditWidget"}
+    assert sorted(action for _, _, action in rows) == ["created", "deleted", "updated"]
+
+
+def test_without_a_sink_the_worker_writes_no_audit_rows(worker_db, monkeypatch) -> None:
+    monkeypatch.setattr(sync_db, "discover_audit_callback", lambda: None)
+    sync_db.dispose_sync_engine()
+    sync_db.set_database_url(worker_db)
+
+    with sync_db.sync_session() as s:
+        s.add(BgAuditWidget(name="quiet"))
+
+    assert _audit_rows() == []
+
+
+def test_a_durable_handlers_write_on_the_outbox_engine_is_audited(worker_db) -> None:
+    """The outbox worker builds its own async engine; it carries the sink too."""
+    from background_tasks.outbox_loop import run_on_worker_loop, stop_worker_loop
+    from background_tasks.outbox_worker import worker_session_factory
+
+    factory = worker_session_factory()
+
+    async def _handler_write() -> None:
+        async with factory() as session:
+            session.add(BgAuditWidget(name="durable"))
+            await session.commit()
+
+    try:
+        run_on_worker_loop(_handler_write)
+    finally:
+        stop_worker_loop()
+
+    assert [(e, a) for e, _, a in _audit_rows()] == [("BgAuditWidget", "created")]
diff --git a/modules/file_storage/tests/test_file_storage_upload_tasks.py b/modules/file_storage/tests/test_file_storage_upload_tasks.py
index 409c6f3e5..55f17dd7b 100644
--- a/modules/file_storage/tests/test_file_storage_upload_tasks.py
+++ b/modules/file_storage/tests/test_file_storage_upload_tasks.py
@@ -30,6 +30,8 @@ def worker(tmp_path, monkeypatch):
     engine = create_engine(url)
     Base.metadata.create_all(engine)
     engine.dispose()
+    # This bare DB has no audit table; keep the installed audit sink off (#498).
+    monkeypatch.setattr(sync_db, "discover_audit_callback", lambda: None)
     sync_db.set_database_url(url)
     backend = FilesystemBackend(root=tmp_path / "objects")
     settings = FileStorageSettings()

From 44799eeff94c4daca3c2913b8e21b76e31f06a1d Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Mon, 19 Oct 2026 13:30:24 +0200
Subject: [PATCH 08/14] fix(hosting): close remaining fail-open boot-config
 paths

Follow-up to #494/#497 from review:
- Stored booleans parse strictly; an unknown token ('tru') is dropped with
  a warning instead of reading as False.
- Only a missing settings package means 'not installed'; any other import
  error is a pre-app read failure (strict outside development).
- SM_SECRET_KEY resolution falls back to an ephemeral key only on a
  confirmed fresh install (no settings table); outside development a
  failed lookup/save or no settings module refuses boot. A blank stored
  key is repaired atomically instead of forcing an ephemeral key forever.
- A failed module hydrate rolls the shared session back so later modules
  still read (Postgres aborted-transaction poisoning) and keeps that
  module's current settings.
- A raising required setup step counts as first run only when the DB has
  no migration history.

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 .../simple_module_core/stored_settings.py     |  13 +-
 .../simple_module_hosting/_hydrate_step.py    |  19 +-
 .../simple_module_hosting/_lifespan.py        |  22 +-
 .../simple_module_hosting/_preapp_config.py   |  32 +--
 .../simple_module_hosting/_secret_key.py      |  91 ++++++--
 .../tests/test_boot_config_hardening.py       | 197 ++++++++++++++++++
 6 files changed, 329 insertions(+), 45 deletions(-)
 create mode 100644 framework/hosting/tests/test_boot_config_hardening.py

diff --git a/framework/core/simple_module_core/stored_settings.py b/framework/core/simple_module_core/stored_settings.py
index c9c92aa28..f3e228a29 100644
--- a/framework/core/simple_module_core/stored_settings.py
+++ b/framework/core/simple_module_core/stored_settings.py
@@ -32,6 +32,7 @@
 RELATED_FIELDS_CTX = "related_fields"
 
 _TRUE = frozenset({"1", "true", "yes", "on"})
+_FALSE = frozenset({"0", "false", "no", "off"})
 
 
 def parse_stored_value(raw: str, value_type: str) -> Any:
@@ -39,10 +40,18 @@ def parse_stored_value(raw: str, value_type: str) -> Any:
 
     The five labels (``string | bool | int | float | json``) are a stable
     stored format. Raises ``ValueError`` (``JSONDecodeError`` is one) on a
-    value that does not decode.
+    value that does not decode — a boolean token included. Anything but a
+    known true/false spelling used to read as ``False``, so a typo such as
+    ``"tru"`` switched ``multi_tenant`` or ``maintenance_mode`` off with no
+    trace; now the boot paths drop the row and warn instead.
     """
     if value_type == "bool":
-        return raw.lower() in _TRUE
+        token = raw.strip().lower()
+        if token in _TRUE:
+            return True
+        if token in _FALSE:
+            return False
+        raise ValueError("not a boolean token")
     if value_type == "int":
         return int(raw)
     if value_type == "float":
diff --git a/framework/hosting/simple_module_hosting/_hydrate_step.py b/framework/hosting/simple_module_hosting/_hydrate_step.py
index 50a6b1049..e07f9527d 100644
--- a/framework/hosting/simple_module_hosting/_hydrate_step.py
+++ b/framework/hosting/simple_module_hosting/_hydrate_step.py
@@ -18,8 +18,19 @@
 _MODULE_PACKAGE = "settings"
 
 
-async def hydrate_all(app: FastAPI, store: Any) -> None:
-    """Resolve every registered module's settings from the DB."""
+async def hydrate_all(app: FastAPI, store: Any, session: Any = None) -> None:
+    """Resolve every registered module's settings from the DB.
+
+    ``hydrate_settings`` is already lenient per field: a stored value that no
+    longer validates is dropped and the module keeps its other overrides. What
+    still raises here is a failed *read*, or a cross-field rule that names no
+    stored field (declare ``RELATED_FIELDS_CTX`` to make it droppable); that
+    module keeps the settings object it had and the loop carries on.
+
+    ``session`` is the one ``store`` reads through. A failed query leaves a
+    Postgres transaction aborted, and every later module's read on the same
+    session would then fail too, so it is rolled back before moving on.
+    """
     settings_services = getattr(app.state, _MODULE_PACKAGE, None)
     if settings_services is None:
         return
@@ -30,7 +41,9 @@ async def hydrate_all(app: FastAPI, store: Any) -> None:
         try:
             hydrated = await hydrate_settings(cls, store, package, lenient=True)
         except Exception:
-            logger.exception("Hydrating %s failed; falling back to defaults", package)
+            logger.exception("Hydrating %s failed; keeping its current settings", package)
+            if session is not None:
+                await session.rollback()
             continue
         services = getattr(app.state, package, None)
         if services is None:
diff --git a/framework/hosting/simple_module_hosting/_lifespan.py b/framework/hosting/simple_module_hosting/_lifespan.py
index f86b0ea81..53abeb88d 100644
--- a/framework/hosting/simple_module_hosting/_lifespan.py
+++ b/framework/hosting/simple_module_hosting/_lifespan.py
@@ -50,7 +50,7 @@ async def hydrate_settings_from_db(app: FastAPI) -> None:
     store_cls = importlib.import_module("settings.store").SettingsStore
 
     async with app.state.sm.db.session_factory() as session:
-        await hydrate_all(app, store_cls(service_cls(session)))
+        await hydrate_all(app, store_cls(service_cls(session)), session)
 
 
 async def _is_first_run(app: FastAPI) -> bool:
@@ -85,8 +85,13 @@ async def _is_first_run(app: FastAPI) -> bool:
     administrator check is a query against a table migrations create — so it
     raises too, and swallowing that would make every step but the schema
     look satisfied, exactly the "is setup complete" trap this function
-    exists to avoid. Here, a required step raising while the schema is
-    behind counts as pending: it is itself evidence the install is new.
+    exists to avoid. A required step raising counts as pending only with
+    positive evidence the install is new: the database has never been
+    migrated at all (no ``alembic_version``). On a database with migration
+    history the same exception is far more likely a transient error on an
+    established install, and treating that as first run would serve the
+    unauthenticated migration endpoint on a live system — so boot fails
+    instead, with the "behind head" error.
     """
     registry = getattr(app.state.sm, "setup_registry", None)
     if not registry:
@@ -97,7 +102,16 @@ async def _is_first_run(app: FastAPI) -> bool:
         try:
             done = await step.is_complete(app)
         except Exception:
-            return True
+            migration = getattr(app.state, "migration", None) or {}
+            never_migrated = migration.get("current_revision") is None
+            if not never_migrated:
+                logger.warning(
+                    "Setup step %s failed on a database with migration history; "
+                    "not treating this install as new",
+                    step.id,
+                    exc_info=True,
+                )
+            return never_migrated
         if not done:
             return True
     return False
diff --git a/framework/hosting/simple_module_hosting/_preapp_config.py b/framework/hosting/simple_module_hosting/_preapp_config.py
index cc18d63b9..997289d10 100644
--- a/framework/hosting/simple_module_hosting/_preapp_config.py
+++ b/framework/hosting/simple_module_hosting/_preapp_config.py
@@ -64,18 +64,25 @@ def _settings_table() -> tuple[str, str, str] | None:
     check is AST-based and forbids ``framework/*`` from naming a plugin
     package. Returns ``None`` when the settings module isn't installed, which
     makes the whole pre-app read a no-op rather than an error.
+
+    Only a *missing* package means "not installed". Any other failure — the
+    package is there but raises on import, or lacks a constant — propagates:
+    swallowing it would let a broken install boot on defaults as though it
+    had never stored anything (#494).
     """
-    try:
-        import importlib
+    import importlib
 
+    try:
         constants = importlib.import_module("settings.constants")
-        return (
-            constants.TABLE_SETTING,
-            constants.SCOPE_SYSTEM,
-            constants.SYSTEM_SCOPE_ID,
-        )
-    except Exception:
-        return None
+    except ModuleNotFoundError as exc:
+        if exc.name in ("settings", "settings.constants"):
+            return None
+        raise
+    return (
+        constants.TABLE_SETTING,
+        constants.SCOPE_SYSTEM,
+        constants.SYSTEM_SCOPE_ID,
+    )
 
 
 async def _read(database_url: str) -> dict[str, tuple[str, str]]:
@@ -227,10 +234,8 @@ def merge_host_settings(bootstrap: BootstrapSettings | None = None) -> Settings:
     from simple_module_hosting._secret_key import SECRET_KEY_FIELD, ensure_secret_key
 
     bootstrap = bootstrap or BootstrapSettings()
-    overrides = load_host_overrides(
-        bootstrap.database_url,
-        strict=bootstrap.environment not in NON_PROD_ENVIRONMENTS,
-    )
+    strict = bootstrap.environment not in NON_PROD_ENVIRONMENTS
+    overrides = load_host_overrides(bootstrap.database_url, strict=strict)
     stored = apply_host_overrides(overrides)
     # Resolved here rather than left to the field default so an install with
     # no SM_SECRET_KEY gets a generated, persisted key instead of the shipped
@@ -242,6 +247,7 @@ def merge_host_settings(bootstrap: BootstrapSettings | None = None) -> Settings:
         bootstrap.database_url,
         env_value=bootstrap.secret_key if "secret_key" in bootstrap.model_fields_set else None,
         stored=stored_key,
+        strict=strict,
     )
     # database_url is passed explicitly: BootstrapSettings.__init__ resolves
     # relative sqlite paths against the discovered project root, and
diff --git a/framework/hosting/simple_module_hosting/_secret_key.py b/framework/hosting/simple_module_hosting/_secret_key.py
index 18cfb900b..363af9c64 100644
--- a/framework/hosting/simple_module_hosting/_secret_key.py
+++ b/framework/hosting/simple_module_hosting/_secret_key.py
@@ -19,7 +19,7 @@
 import secrets
 from concurrent.futures import ThreadPoolExecutor
 
-from sqlalchemy import text
+from sqlalchemy import inspect, text
 from sqlalchemy.exc import IntegrityError
 from sqlalchemy.ext.asyncio import create_async_engine
 from sqlalchemy.pool import NullPool
@@ -74,7 +74,20 @@ async def _fetch(conn, table: str, scope: str, scope_id: str) -> str | None:
     return row[0] if row else None
 
 
+class SecretKeyUnavailableError(RuntimeError):
+    """No key could be resolved and an ephemeral one is not safe here.
+
+    Every worker would generate its own, so each would reject the sessions
+    the others sign — users bounced to the login page at random (#494).
+    """
+
+
 async def _ensure(database_url: str) -> str | None:
+    """Return the stored key, storing a generated one first if needed.
+
+    ``None`` means one thing only: the settings table does not exist yet, i.e.
+    a confirmed fresh install. Every other failure raises.
+    """
     info = _settings_table()
     if info is None:
         return None
@@ -83,6 +96,8 @@ async def _ensure(database_url: str) -> str | None:
     engine = create_async_engine(database_url, poolclass=NullPool)
     try:
         async with engine.connect() as conn:
+            if not await conn.run_sync(lambda sync: inspect(sync).has_table(table)):
+                return None
             existing = await _fetch(conn, table, scope, scope_id)
             if existing:
                 return existing
@@ -101,37 +116,57 @@ async def _ensure(database_url: str) -> str | None:
         # contextlib.suppress is a sync context manager and does not implement
         # the async protocol, so `async with engine.begin(), suppress(...)`
         # raises TypeError at runtime.
+        params = {"scope": scope, "scope_id": scope_id, "key": _KEY, "value": _generate()}
         async with engine.begin() as conn:
-            with contextlib.suppress(IntegrityError):
+            if existing == "":
+                # A blank row would otherwise defeat the insert forever and
+                # leave every boot on an ephemeral key. Repair it in place; the
+                # ``value = ''`` guard lets exactly one concurrent worker win.
                 await conn.execute(
                     text(  # table name is a module constant, never user input
-                        f"INSERT INTO {table} (scope, scope_id, key, value, value_type) "
-                        "VALUES (:scope, :scope_id, :key, :value, 'string')"
+                        f"UPDATE {table} SET value = :value WHERE scope = :scope "
+                        "AND scope_id = :scope_id AND key = :key AND value = ''"
                     ),
-                    {
-                        "scope": scope,
-                        "scope_id": scope_id,
-                        "key": _KEY,
-                        "value": _generate(),
-                    },
+                    params,
                 )
+            else:
+                with contextlib.suppress(IntegrityError):
+                    await conn.execute(
+                        text(  # table name is a module constant, never user input
+                            f"INSERT INTO {table} (scope, scope_id, key, value, value_type) "
+                            "VALUES (:scope, :scope_id, :key, :value, 'string')"
+                        ),
+                        params,
+                    )
 
         async with engine.connect() as conn:
-            return await _fetch(conn, table, scope, scope_id)
+            stored = await _fetch(conn, table, scope, scope_id)
     finally:
         await engine.dispose()
+    if not stored:
+        raise RuntimeError("the stored secret key is still missing after writing it")
+    return stored
 
 
 def ensure_secret_key(
-    database_url: str, *, env_value: str | None = None, stored: str | None = None
+    database_url: str,
+    *,
+    env_value: str | None = None,
+    stored: str | None = None,
+    strict: bool = False,
 ) -> str:
     """Return the key to sign sessions with, generating one if needed.
 
-    Falls back to an ephemeral generated key when the database cannot be
-    reached or has not been migrated. That is deliberate: a key is needed to
-    build the app at all, and an app that refuses to start cannot show the
-    setup wizard that fixes the database. Sessions won't survive a restart in
-    that state, which is why it warns.
+    An ephemeral generated key is the fallback only on a confirmed fresh
+    install — the settings table does not exist yet. That is deliberate: a
+    key is needed to build the app at all, and an app that refuses to start
+    cannot show the setup wizard that migrates the database. Sessions won't
+    survive a restart in that state, which is why it warns.
+
+    Anywhere else an ephemeral key means each worker signs with its own and
+    rejects its siblings' sessions. So with ``strict`` (outside development) a
+    failed lookup or save, or no settings module to store the key in, raises
+    :class:`SecretKeyUnavailableError`; without it, it warns and falls back.
 
     ``stored`` is the value the caller already read from the settings table,
     if any; a non-empty one is returned without touching the database again.
@@ -145,14 +180,24 @@ def ensure_secret_key(
         return stored
 
     try:
+        if _settings_table() is None:
+            raise RuntimeError(
+                "the settings module is not installed, so there is nowhere to store it"
+            )
         with ThreadPoolExecutor(max_workers=1) as pool:
-            stored = pool.submit(lambda: asyncio.run(_ensure(database_url))).result()
+            resolved = pool.submit(lambda: asyncio.run(_ensure(database_url))).result()
     except Exception as exc:
-        stored = None
-        logger.debug("Secret key lookup failed: %s", exc)
-
-    if stored:
-        return stored
+        if strict:
+            raise SecretKeyUnavailableError(
+                f"SM_SECRET_KEY is unset and no stored key could be read or saved ({exc}). "
+                "Each worker would sign sessions with its own ephemeral key. Set "
+                "SM_SECRET_KEY, or fix database access, then restart."
+            ) from exc
+        logger.warning("Secret key lookup failed (%s: %s)", type(exc).__name__, exc)
+        resolved = None
+
+    if resolved:
+        return resolved
 
     logger.warning(
         "No SM_SECRET_KEY set and the key could not be stored (database "
diff --git a/framework/hosting/tests/test_boot_config_hardening.py b/framework/hosting/tests/test_boot_config_hardening.py
new file mode 100644
index 000000000..7b5cca682
--- /dev/null
+++ b/framework/hosting/tests/test_boot_config_hardening.py
@@ -0,0 +1,197 @@
+"""Boot-config paths that used to fail open or crash (follow-up to #494/#497).
+
+Each case here once turned an error into a silent default on an established
+install: a typo'd boolean read as ``False``, a broken settings import read as
+"not installed", a failed key lookup minted a per-worker key, a failed module
+hydrate poisoned the session for every later module, and a raising setup
+check reopened the setup wizard on a live system.
+"""
+
+from __future__ import annotations
+
+import importlib
+import logging
+import sqlite3
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+from pydantic_settings import BaseSettings
+from simple_module_core.setup_steps import SetupRegistry, SetupStep
+from simple_module_core.stored_settings import parse_stored_value
+from simple_module_hosting import _secret_key
+from simple_module_hosting._hydrate_step import hydrate_all
+from simple_module_hosting._lifespan import _is_first_run
+from simple_module_hosting._preapp_config import (
+    HostSettingsUnavailableError,
+    apply_host_overrides,
+    load_host_overrides,
+)
+from simple_module_hosting._secret_key import SecretKeyUnavailableError, ensure_secret_key
+from simple_module_hosting.setup_gate import STEP_MIGRATIONS
+
+
+def _settings_db(db_path: Path, rows: list[tuple[str, str]]) -> str:
+    conn = sqlite3.connect(db_path)
+    conn.execute(
+        "CREATE TABLE settings_setting (id INTEGER PRIMARY KEY, scope TEXT NOT NULL, "
+        "scope_id TEXT NOT NULL, key TEXT NOT NULL, value TEXT NOT NULL, "
+        "value_type TEXT NOT NULL, UNIQUE (scope, scope_id, key))"
+    )
+    conn.executemany(
+        "INSERT INTO settings_setting (scope, scope_id, key, value, value_type) "
+        "VALUES ('system', '', ?, ?, 'string')",
+        rows,
+    )
+    conn.commit()
+    conn.close()
+    return f"sqlite+aiosqlite:///{db_path}"
+
+
+@pytest.fixture(autouse=True)
+def _no_env_key(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("SM_SECRET_KEY", raising=False)
+
+
+# ── 1. Booleans parse strictly ─────────────────────────────
+
+
+@pytest.mark.parametrize(("raw", "expected"), [("True", True), (" off ", False), ("0", False)])
+def test_known_bool_tokens(raw: str, expected: bool) -> None:
+    assert parse_stored_value(raw, "bool") is expected
+
+
+def test_typo_bool_is_dropped_not_coerced_to_false(caplog: pytest.LogCaptureFixture) -> None:
+    with caplog.at_level(logging.WARNING):
+        out = apply_host_overrides({"multi_tenant": ("tru", "bool")}, environ={})
+    assert "multi_tenant" not in out
+    assert "multi_tenant" in caplog.text
+
+
+# ── 2. A broken settings import is a failure, not "not installed" ──
+
+
+def test_settings_import_error_is_a_read_failure(monkeypatch: pytest.MonkeyPatch) -> None:
+    real = importlib.import_module
+
+    def broken(name: str, *args, **kwargs):
+        if name == "settings.constants":
+            raise ImportError("circular import in settings")
+        return real(name, *args, **kwargs)
+
+    monkeypatch.setattr(importlib, "import_module", broken)
+    with pytest.raises(HostSettingsUnavailableError):
+        load_host_overrides("sqlite+aiosqlite:///:memory:", strict=True)
+
+
+# ── 3. Ephemeral secret keys only on a confirmed fresh install ──
+
+
+async def _lookup_fails(_url: str) -> str:
+    raise OSError("Connection refused")
+
+
+def test_key_lookup_failure_refuses_boot_when_strict(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(_secret_key, "_ensure", _lookup_fails)
+    with pytest.raises(SecretKeyUnavailableError):
+        ensure_secret_key("sqlite+aiosqlite:///:memory:", strict=True)
+
+
+def test_key_lookup_failure_falls_back_in_development(
+    monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
+) -> None:
+    monkeypatch.setattr(_secret_key, "_ensure", _lookup_fails)
+    with caplog.at_level(logging.WARNING):
+        assert ensure_secret_key("sqlite+aiosqlite:///:memory:")
+    assert "OSError" in caplog.text
+
+
+def test_fresh_install_may_use_an_ephemeral_key_when_strict(tmp_path: Path) -> None:
+    db = tmp_path / "fresh.db"
+    sqlite3.connect(db).close()  # no tables: never migrated
+    assert ensure_secret_key(f"sqlite+aiosqlite:///{db}", strict=True)
+
+
+def test_no_settings_module_refuses_when_strict(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(_secret_key, "_settings_table", lambda: None)
+    with pytest.raises(SecretKeyUnavailableError, match="SM_SECRET_KEY"):
+        ensure_secret_key("sqlite+aiosqlite:///:memory:", strict=True)
+
+
+def test_blank_stored_key_is_repaired_once(tmp_path: Path) -> None:
+    """A blank row used to defeat the insert forever: an ephemeral key per boot."""
+    db = tmp_path / "blank.db"
+    url = _settings_db(db, [("host.secret_key", "")])
+
+    key = ensure_secret_key(url, stored="", strict=True)
+
+    assert key
+    stored = sqlite3.connect(db).execute(
+        "SELECT value FROM settings_setting WHERE key = 'host.secret_key'"
+    )
+    assert stored.fetchone()[0] == key
+    assert ensure_secret_key(url, strict=True) == key, "a second boot reads the same key"
+
+
+# ── 4. One module's failed hydrate does not poison the rest ──
+
+
+class _A(BaseSettings):
+    flag: bool = False
+
+
+class _B(BaseSettings):
+    flag: bool = False
+
+
+async def test_failed_hydrate_rolls_back_and_continues() -> None:
+    class _Store:
+        async def get_overrides(self, package: str) -> dict[str, tuple[str, str]]:
+            if package == "a":
+                raise OSError("current transaction is aborted")
+            return {"flag": ("true", "bool")}
+
+    registry = SimpleNamespace(items=lambda: [("a", _A), ("b", _B)])
+    a_before = _A()
+    state = SimpleNamespace(
+        settings=SimpleNamespace(module_registry=registry),
+        a=SimpleNamespace(settings=a_before),
+        b=SimpleNamespace(settings=_B()),
+    )
+    session = SimpleNamespace(rollback=AsyncMock())
+
+    await hydrate_all(SimpleNamespace(state=state), _Store(), session)
+
+    session.rollback.assert_awaited_once()
+    assert state.a.settings is a_before, "a failed read keeps what the module had"
+    assert state.b.settings.flag is True
+
+
+# ── 5. A raising setup check needs evidence of a new install ──
+
+
+def _raising_registry() -> SetupRegistry:
+    async def done(_app) -> bool:
+        return False
+
+    async def boom(_app) -> bool:
+        raise RuntimeError("connection reset")
+
+    registry = SetupRegistry()
+    registry.add(SetupStep(id=STEP_MIGRATIONS, title="m", is_complete=done))
+    registry.add(SetupStep(id="users.administrator", title="admin", is_complete=boom))
+    return registry
+
+
+@pytest.mark.parametrize(("current_revision", "first_run"), [(None, True), ("abc123", False)])
+async def test_raising_step_counts_as_first_run_only_without_history(
+    current_revision: str | None, first_run: bool
+) -> None:
+    app = SimpleNamespace(
+        state=SimpleNamespace(
+            sm=SimpleNamespace(setup_registry=_raising_registry()),
+            migration={"current_revision": current_revision},
+        )
+    )
+    assert await _is_first_run(app) is first_run

From 27288bbd30946f893b89b3696b126ff068863813 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Mon, 19 Oct 2026 13:36:31 +0200
Subject: [PATCH 09/14] docs(claude-md): boot-config failure modes and Secure
 session cookie (#494, #497, #499, #495)

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 CLAUDE.md | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 0f3077caf..a83630649 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -234,7 +234,8 @@ by `InertiaLayoutDataMiddleware`; `auth.user` is null unless
 **CSRF.** Baseline is `SameSite=Lax` on the Starlette session cookie; raw
 `fetch()` in pages needs no token. Defence in depth: `RequiresCsrf` router
 dependency + `get_csrf_token(request)` as a view prop, echoed as `X-CSRF-Token`
-(`simple_module_hosting.csrf`).
+(`simple_module_hosting.csrf`). The session cookie is `Secure` outside
+development and testing (`session_cookie_secure`).
 
 ## Database
 
@@ -324,6 +325,12 @@ dependency + `get_csrf_token(request)` as a view prop, echoed as `X-CSRF-Token`
   lifespan opens the DB, so a `HostSettings` field read at build time needs
   that pre-read. `SM_SECRET_KEY` is optional: unset generates and stores a key
   atomically; an explicit value wins and is never copied into the DB.
+  A pre-app read failure is not a fresh install: outside development it
+  refuses to boot (`HostSettingsUnavailableError`/`SecretKeyUnavailableError`);
+  only a missing settings table falls back to defaults and an ephemeral key.
+  Stored values parse through `simple_module_core.stored_settings`; an invalid
+  row is dropped with a WARNING. Every `HostSettings` field `create_app` reads
+  is marked restart-required (`test_build_time_settings_marked.py`).
   Module settings are a `DbBackedSettings` subclass (constructor + DB, no env
   source) registered in `register_settings` through
   `settings.registration.register_module_settings(app, package, SettingsCls,

From f645363bbd5f80267f0a67fb2b9b5f2cf966ca7c Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Mon, 19 Oct 2026 14:01:13 +0200
Subject: [PATCH 10/14] fix(db): scope Core joins, subqueries, CTEs and
 compound selects by tenant (#506)

A pure Core outer join over Model.__table__ got no tenant or soft-delete
criteria in ON or WHERE, so aggregates counted other tenants' rows. A Codex
review found the same gap for other Core shapes: table aliases, subqueries,
CTEs, scalar subqueries, union/intersect/except members, the extra FROM of
an UPDATE/DELETE, INSERT ... FROM SELECT sources, and exists() over a join
or inside an ON clause.

- core_scope: one walk detects a plain (non-ORM) reference to a scoped
  table; only then is the statement cloned once and every SELECT in it,
  innermost first, gets predicates for the tables it reads. UPDATE/DELETE
  get predicates for the tables their WHERE joins in. Replaces
  subquery_guard.
- _core_joins: a LEFT join's nullable side gets its predicates in ON; a
  FULL join gets both sides' predicates in ON plus WHERE (pred OR pk IS
  NULL) per side, which gives the same result as filtering both inputs
  first. Nested joins, aliases and select().outerjoin(table, on) are
  covered.
- Strict mode with no tenant still raises TenantIsolationError for every
  Core reference; include_deleted / all_tenants are honoured.
- Remove the strict xfail; add tests for every shape (SQLite + Postgres).
- Docs: list what is covered, and that text() and soft-delete on DML are
  out of scope by design.

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 docs/framework-conventions.md                 |   6 +-
 docs/framework/multi-tenancy.md               |  40 ++++-
 framework/db/simple_module_db/_core_joins.py  | 153 ++++++++++++++++
 framework/db/simple_module_db/_outer_joins.py |   2 +-
 framework/db/simple_module_db/core_scope.py   | 168 ++++++++++++++++++
 framework/db/simple_module_db/query_filter.py | 131 +++++++-------
 .../db/simple_module_db/subquery_guard.py     |  49 -----
 framework/db/tests/_core_scope_models.py      |  95 ++++++++++
 framework/db/tests/test_db_core_join_scope.py | 137 ++++++++++++++
 .../db/tests/test_db_core_nested_scope.py     | 136 ++++++++++++++
 .../db/tests/test_query_filter_outer_joins.py |  12 +-
 11 files changed, 796 insertions(+), 133 deletions(-)
 create mode 100644 framework/db/simple_module_db/_core_joins.py
 create mode 100644 framework/db/simple_module_db/core_scope.py
 delete mode 100644 framework/db/simple_module_db/subquery_guard.py
 create mode 100644 framework/db/tests/_core_scope_models.py
 create mode 100644 framework/db/tests/test_db_core_join_scope.py
 create mode 100644 framework/db/tests/test_db_core_nested_scope.py

diff --git a/docs/framework-conventions.md b/docs/framework-conventions.md
index 267ac84fd..8f0688752 100644
--- a/docs/framework-conventions.md
+++ b/docs/framework-conventions.md
@@ -284,7 +284,9 @@ not get the row torn out from under them.
 The soft-delete and tenant filters are attached by a `do_orm_execute` listener
 (`simple_module_db.query_filter`). Loader criteria go on for *every* registered
 soft-deletable / tenant-scoped model, not only the entities a statement names,
-and top-level Core tables get an explicit `WHERE`. All of these are filtered:
+and Core tables — at any depth, including outer joins (predicates in `ON`),
+subqueries, CTEs and unions (GH #506) — get explicit predicates. All of these
+are filtered:
 
 ```python
 select(Model)  # entity select
@@ -294,6 +296,8 @@ select(func.count()).select_from(select(Model).subquery())
 select(func.count()).select_from(Model.__table__)  # pure Core
 select(A).outerjoin(B)  # B filtered in the ON clause
 select(func.count()).select_from(A.__table__.join(B.__table__, ...))  # Core inner join
+select(func.count()).select_from(A.__table__.outerjoin(B.__table__, ...))  # B in ON
+union(select(A.__table__.c.id), select(A.__table__.c.id))  # Core, nested
 ```
 
 Before GH #332 only the first two were — the rest returned trashed rows, and on
diff --git a/docs/framework/multi-tenancy.md b/docs/framework/multi-tenancy.md
index b0becb680..5840a5d09 100644
--- a/docs/framework/multi-tenancy.md
+++ b/docs/framework/multi-tenancy.md
@@ -37,15 +37,37 @@ statement names, so all of these are scoped (#332):
 - subqueries: `select(Doc.id).where(...).exists()`, a bare Core
   `exists().where(Doc.x == ...)`, `in_(select(Doc.x))`, scalar subqueries;
 - counts: `select(func.count()).select_from(Doc)`, counts over a subquery;
-- Core statements on `Doc.__table__` at the top level — `select`, `update`,
-  `delete` get `WHERE tenant_id = …` (and `is_deleted IS false` on reads),
-  `insert` is stamped.
-
-With no tenant under strict mode, a statement that *names* a tenant model or
-table — or reads one through a bare Core `exists()` — raises; an indirect ORM
-reference (a join, a subquery) matches nothing. The one-time cost is a scan of
-the WHERE/column clauses for `exists()` (about 10 µs per statement), skipped
-when no tenant-scoped or soft-deletable model is installed.
+- Core statements on `Doc.__table__` (or `Doc.__table__.alias()`) at any
+  depth (#506): the top-level `select`, `update` and `delete` target get
+  `WHERE tenant_id = …` (and `is_deleted IS false` on reads), `insert` is
+  stamped, and so is every other Core reference — a subquery, a CTE, a
+  scalar or `exists()` subquery (also inside a join's `ON`), each member of a
+  `union` / `intersect` / `except`, a table an `update()`/`delete()` joins in
+  through its `WHERE`, and the `select` behind `insert().from_select()`;
+- Core **joins**: an outer join's nullable side gets its predicates in the
+  `ON` clause, so `tag.outerjoin(link, …)` keeps tags without links and never
+  counts another tenant's links. A `full=True` join puts both sides'
+  predicates in `ON` and adds `WHERE (pred OR <side's primary key> IS NULL)`
+  per side, which is the same result as filtering both inputs first. The
+  `select(...).outerjoin(Doc.__table__, onclause)` form is scoped the same
+  way; without an explicit `onclause` the predicate falls back to `WHERE`
+  (over-filters — the outer join behaves as inner — but never leaks).
+
+With no tenant under strict mode, a statement that *names* a tenant model, or
+reads a tenant table through Core anywhere in it, raises; an indirect ORM
+reference (a join, a subquery) matches nothing. The cost is one walk of the
+statement looking for a plain (non-ORM) reference to a scoped table (about
+20–40 µs for a typical ORM select); only a statement that has one is cloned
+and rewritten. Both are skipped when no tenant-scoped or soft-deletable model
+is installed.
+
+Not covered, by design:
+
+- raw SQL — `text("SELECT … FROM docs_doc")` is opaque to the filter; scope it
+  yourself;
+- soft-delete on an `update()`/`delete()` (its target *or* any table it reads):
+  writes may touch trashed rows — that is how restore and purge work. Tenant
+  scoping still applies to them.
 
 ### One session, one tenant
 
diff --git a/framework/db/simple_module_db/_core_joins.py b/framework/db/simple_module_db/_core_joins.py
new file mode 100644
index 000000000..b91870481
--- /dev/null
+++ b/framework/db/simple_module_db/_core_joins.py
@@ -0,0 +1,153 @@
+"""Tenant / soft-delete criteria for Core joins over ``Model.__table__`` (#506).
+
+ORM joins get their criteria from ``with_loader_criteria``, which renders into
+each join's ``ON``. A Core join — ``tag.outerjoin(link, ...)`` in
+``select_from``, or ``select(...).outerjoin(link, ...)`` on a raw table — has
+no loader criteria, and a ``WHERE`` on its nullable side would turn the outer
+join into an inner one. So this module rewrites the joins themselves:
+
+* a LEFT join's nullable (right) side gets its predicates in ``ON``, which
+  filters it exactly;
+* a FULL join preserves both sides, and ``ON`` never removes a preserved row,
+  so both sides' predicates go in ``ON`` *and* each side owes
+  ``pred OR <side padded>`` (its primary key ``IS NULL``) to whatever encloses
+  the join — that drops another tenant's (or a trashed) row coming back
+  unmatched while keeping the NULL padding the join adds;
+* an INNER join's sides, and a LEFT join's preserved side, owe their
+  predicates to the enclosing join's ``ON`` — or, at the top, to ``WHERE``.
+
+The FULL-join form is exact, not merely safe: a row survives only if every
+side that is present passed its own predicates, which is what pre-filtering
+both inputs would give, without wrapping the tables in subqueries (which
+would break every column reference to them).
+
+Every plain leaf inside a join is reported back, so the caller does not also
+``WHERE``-filter it through the columns clause. ORM-annotated leaves are left
+to their loader criteria. ``core_scope`` calls this for each SELECT in a
+statement, nested ones included.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from sqlalchemy import and_, or_
+from sqlalchemy.sql.selectable import Alias, FromGrouping, Join, Select, TableClause
+
+Predicates = Callable[[Any], list[Any]]
+
+
+def is_plain_leaf(node: Any) -> bool:
+    """A Core table or alias of one — not an ORM-annotated occurrence."""
+    if "parententity" in getattr(node, "_annotations", {}):
+        return False
+    base = node
+    while isinstance(base, Alias):
+        base = base.element
+    return isinstance(base, TableClause)
+
+
+def _padded(leaf: Any) -> Any | None:
+    """``leaf``'s row is the NULL padding of an outer join: its primary key is NULL."""
+    pk = list(leaf.primary_key)
+    return and_(*(c.is_(None) for c in pk)) if pk else None
+
+
+class _Scoper:
+    def __init__(self, predicates_for: Predicates) -> None:
+        self.predicates_for = predicates_for
+        self.covered: list[Any] = []
+
+    def scope(self, node: Any) -> tuple[Any, list[Any]]:
+        """``node`` with its joins scoped, and the predicates its rows still owe."""
+        if isinstance(node, Join):
+            return self._join(node)
+        if isinstance(node, FromGrouping):  # a join nested as another join's side
+            inner, owed = self.scope(node.element)
+            return (node if inner is node.element else FromGrouping(inner)), owed
+        if not is_plain_leaf(node):
+            return node, []
+        preds = self.predicates_for(node)
+        if preds:
+            self.covered.append(node)
+        return node, [(node, preds)] if preds else []
+
+    def _join(self, node: Join) -> tuple[Any, list[Any]]:
+        left, owed_left = self.scope(node.left)
+        right, owed_right = self.scope(node.right)
+        if not node.isouter:
+            on, owed = [], owed_left + owed_right
+        elif node.full:
+            on, owed = owed_left + owed_right, [_or_padded(o) for o in owed_left + owed_right]
+        else:
+            on, owed = owed_right, owed_left
+        if not on and left is node.left and right is node.right:
+            return node, owed
+        onclause = and_(node.onclause, *_flatten(on)) if on else node.onclause
+        return Join(left, right, onclause, isouter=node.isouter, full=node.full), owed
+
+
+def _or_padded(owed: tuple[Any, list[Any]]) -> tuple[Any, list[Any]]:
+    leaf, preds = owed
+    padded = _padded(leaf)
+    # No primary key to tell padding apart: keep the plain predicates, which
+    # over-filter (drop the padded rows) but never leak.
+    return (leaf, preds) if padded is None else (leaf, [or_(and_(*preds), padded)])
+
+
+def _flatten(owed: list[tuple[Any, list[Any]]]) -> list[Any]:
+    return [p for _leaf, preds in owed for p in preds]
+
+
+class JoinScope:
+    """What scoping one SELECT's joins produced, for the caller to install."""
+
+    def __init__(self, from_obj: tuple, setup_joins: tuple, where: list, covered: list) -> None:
+        self.from_obj = from_obj
+        self.setup_joins = setup_joins
+        self.where = where
+        self.covered = covered
+
+
+def scope_joins(stmt: Select, predicates_for: Predicates) -> JoinScope:
+    """Scope ``stmt``'s Core joins: its ``FROM`` joins and ``.join()`` steps.
+
+    ``covered`` lists every plain leaf filtered here — in ``ON`` or through
+    ``where`` — which must not get another ``WHERE`` predicate from the
+    caller: on a nullable side it would make the outer join inner.
+    ``predicates_for`` raises under strict mode with no tenant bound, so a
+    Core join fails closed like everything else.
+    """
+    scoper = _Scoper(predicates_for)
+    where: list[Any] = []
+    froms: list[Any] = []
+    for from_obj in stmt._from_obj:
+        if isinstance(from_obj, Join):
+            from_obj, owed = scoper.scope(from_obj)
+            where.extend(_flatten(owed))
+        froms.append(from_obj)
+    joins = [_scope_setup_join(entry, scoper, where) for entry in stmt._setup_joins]
+    return JoinScope(tuple(froms), tuple(joins), where, scoper.covered)
+
+
+def _scope_setup_join(entry: tuple, scoper: _Scoper, where: list[Any]) -> tuple:
+    """One ``select(...).join(target, onclause)`` step over a Core target.
+
+    The left side is the FROM built so far, already filtered by its own
+    predicates; only the target is scoped here. Without an explicit
+    ``onclause`` there is no ``ON`` to extend, so an outer target's
+    predicates fall back to ``WHERE`` (over-filters, never leaks).
+    """
+    target, onclause, from_, flags = entry
+    target, owed = scoper.scope(target)
+    outer = bool(flags.get("isouter")) or bool(flags.get("full"))
+    if not owed:
+        return (target, onclause, from_, flags)
+    if not outer or onclause is None:
+        where.extend(_flatten(owed))
+        return (target, onclause, from_, flags)
+    onclause = and_(onclause, *_flatten(owed))
+    if flags.get("full"):
+        where.extend(_flatten([_or_padded(o) for o in owed]))
+    return (target, onclause, from_, flags)
diff --git a/framework/db/simple_module_db/_outer_joins.py b/framework/db/simple_module_db/_outer_joins.py
index bfc870bd2..ab0018c93 100644
--- a/framework/db/simple_module_db/_outer_joins.py
+++ b/framework/db/simple_module_db/_outer_joins.py
@@ -2,7 +2,7 @@
 
 ``select(Parent, func.count(Child.id)).outerjoin(Child, ...)``: the column
 wrapped in ``func.count`` strips the ORM annotation, so ``columns_clause_froms``
-lists a bare ``Table child``. ``_plain_tables`` took that for a Core
+lists a bare ``Table child``. ``core_scope`` would take that for a Core
 ``Model.__table__`` reference and added ``WHERE child.tenant_id = :t``, which
 is false for every row the outer join padded with NULLs — the LEFT JOIN became
 an inner one and parents without children vanished.
diff --git a/framework/db/simple_module_db/core_scope.py b/framework/db/simple_module_db/core_scope.py
new file mode 100644
index 000000000..a372a72ac
--- /dev/null
+++ b/framework/db/simple_module_db/core_scope.py
@@ -0,0 +1,168 @@
+"""Tenant / soft-delete predicates for Core references, at every depth (#332, #506).
+
+ORM entities are scoped by ``with_loader_criteria``. A plain ``Model.__table__``
+(or ``table.alias()``) is not, wherever it sits: the top-level SELECT, a
+join, a subquery, a CTE, a scalar or ``exists()`` subquery (also one inside
+a join's ``ON``), a member of a UNION / INTERSECT / EXCEPT, the extra FROM
+of an UPDATE / DELETE, or the SELECT feeding an ``INSERT ... FROM SELECT``.
+
+One cheap walk decides whether the statement holds any such reference; ORM
+statements usually do not and are returned untouched. Otherwise the
+statement is cloned once (``cloned_traverse``, a single clone map, so a
+correlated subquery keeps pointing at the same outer FROM) and every SELECT
+in it, innermost first, gets:
+
+* its Core joins scoped (``_core_joins``: ``ON`` for nullable sides);
+* ``WHERE`` predicates for every other plain table it reads — from its
+  columns, its FROM list and its ``WHERE`` clause.
+
+An UPDATE / DELETE gets ``WHERE`` predicates for the tables its ``WHERE``
+joins in; its target is scoped by the caller. Under strict mode with no
+tenant bound, ``predicates_for`` raises: every Core reference fails closed.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sqlalchemy.sql import visitors
+from sqlalchemy.sql.selectable import Alias, Join, Select, TableClause
+from sqlalchemy.sql.visitors import HasTraverseInternals
+
+from simple_module_db._core_joins import Predicates, is_plain_leaf, scope_joins
+from simple_module_db._outer_joins import is_excluded, orm_outer_join_tables
+
+
+def _base_name(from_obj: Any) -> str | None:
+    while isinstance(from_obj, Alias):
+        from_obj = from_obj.element
+    return getattr(from_obj, "name", None)
+
+
+def _is_orm(el: Any) -> bool:
+    return "parententity" in getattr(el, "_annotations", {})
+
+
+def _orm_less(stmt: Any) -> bool:
+    """A SELECT naming no ORM entity in its columns, FROM list or joins.
+
+    Loader criteria have nothing to attach to there — ``exists().where(
+    Doc.x == ...)`` — so the tables its ``WHERE`` reads must be scoped like
+    Core ones. In an ORM select those tables are the entities' own.
+    """
+    targets = [entry[0] for entry in stmt._setup_joins]
+    return not any(_is_orm(el) for el in (*stmt._raw_columns, *stmt._from_obj, *targets))
+
+
+def _froms_read(stmt: Any) -> list[Any]:
+    """The FROMs a SELECT reads besides its joins, and the extra FROMs of a DML."""
+    if not isinstance(stmt, Select):
+        target = stmt.table._deannotate()
+        return [f for f in _where_froms(stmt) if f is not target]
+    froms = [*stmt.columns_clause_froms, *(f for f in stmt._from_obj if not isinstance(f, Join))]
+    return [*froms, *_where_froms(stmt)] if _orm_less(stmt) else froms
+
+
+def _references_plain(stmt: Any, names: set[str]) -> bool:
+    """Whether ``stmt`` reads a scoped table outside the ORM's annotations.
+
+    ORM-annotated elements are not descended into: their tables are the
+    loader criteria's business, and every ORM column leads to a plain table.
+    """
+    stack = [stmt]
+    while stack:
+        el = stack.pop()
+        if _is_orm(el):
+            continue
+        target = el if isinstance(el, (TableClause, Alias)) else getattr(el, "table", None)
+        if (
+            isinstance(target, (TableClause, Alias))
+            and is_plain_leaf(target)
+            and _base_name(target) in names
+        ):
+            return True
+        stack.extend(_children(el))
+    return False
+
+
+def _children(el: Any) -> list[Any]:
+    # ``Select.get_children`` adds every FROM it derives from the columns and
+    # WHERE, deannotated, so every ORM statement would look Core. Its declared
+    # internals plus the FROMs ``_froms_read`` would scope are what counts.
+    if isinstance(el, Select):
+        omit = ("_correlate", "_correlate_except")
+        return [*HasTraverseInternals.get_children(el, omit_attrs=omit), *_froms_read(el)]
+    if el.__visit_name__ in ("update", "delete"):
+        return [*el.get_children(), *_froms_read(el)]
+    return list(el.get_children())
+
+
+def _executable_options(stmt: Any) -> list[Any]:
+    """ORM options anywhere in ``stmt``: shared as they are, never cloned."""
+    return [o for el in visitors.iterate(stmt) for o in getattr(el, "_with_options", ())]
+
+
+def _same_from(a: Any, b: Any) -> bool:
+    """One FROM occurrence: the same object, or clones of one (an alias the traversal
+    copied while a column still points at the original — SQL renders them as one)."""
+    return a is b or not a._cloned_set.isdisjoint(b._cloned_set)
+
+
+def _where_froms(stmt: Any) -> list[Any]:
+    return [f for crit in stmt._where_criteria for f in crit._from_objects]
+
+
+def _add_where(stmt: Any, preds: list[Any]) -> None:
+    if preds:  # ``stmt`` is this traversal's own clone: mutating it is safe
+        stmt._where_criteria = (*stmt._where_criteria, *preds)
+
+
+class _Visitor:
+    def __init__(self, predicates_for: Predicates, orm_covered: Any) -> None:
+        self.predicates_for = predicates_for
+        self.orm_covered = orm_covered
+
+    def _preds(self, candidates: list[Any], skip: list[Any]) -> list[Any]:
+        preds: list[Any] = []
+        seen: list[Any] = list(skip)
+        for from_obj in candidates:
+            if not is_plain_leaf(from_obj) or any(_same_from(from_obj, s) for s in seen):
+                continue
+            seen.append(from_obj)
+            preds.extend(self.predicates_for(from_obj))
+        return preds
+
+    def select(self, stmt: Any) -> None:
+        joined = scope_joins(stmt, self.predicates_for)
+        if joined.covered:
+            stmt._from_obj, stmt._setup_joins = joined.from_obj, joined.setup_joins
+        # A bare table an ORM entity LEFT-joins in is filtered by that
+        # join's ON; a WHERE on it would make the join inner (#417).
+        outer = orm_outer_join_tables(stmt, self.orm_covered) if self.orm_covered else []
+        candidates = [f for f in _froms_read(stmt) if not (outer and is_excluded(f, outer))]
+        _add_where(stmt, [*joined.where, *self._preds(candidates, joined.covered)])
+
+    def dml(self, stmt: Any) -> None:
+        """The tables an UPDATE / DELETE joins in through its ``WHERE``."""
+        _add_where(stmt, self._preds(_froms_read(stmt), []))
+
+
+def scope_core(
+    stmt: Any, predicates_for: Predicates, names: set[str], orm_covered: Any = None
+) -> Any:
+    """Return ``stmt`` with every plain scoped table filtered, or ``stmt`` itself.
+
+    ``names`` are the scoped table names. ``orm_covered`` are the classes the
+    caller gives loader criteria (for the #417 exclusion), or ``None``.
+    """
+    if not names or not _references_plain(stmt, names):
+        return stmt
+    visitor = _Visitor(predicates_for, orm_covered)
+    return visitors.cloned_traverse(
+        stmt,
+        {"stop_on": _executable_options(stmt)},
+        {"select": visitor.select, "update": visitor.dml, "delete": visitor.dml},
+    )
+
+
+__all__ = ["scope_core"]
diff --git a/framework/db/simple_module_db/query_filter.py b/framework/db/simple_module_db/query_filter.py
index 8efdd0b34..65b0ac77a 100644
--- a/framework/db/simple_module_db/query_filter.py
+++ b/framework/db/simple_module_db/query_filter.py
@@ -1,12 +1,13 @@
 """``do_orm_execute`` filter: soft-delete and tenant scoping on every ORM statement.
 
-Scope (#332). Tenant and soft-delete criteria are attached for *every*
+Scope (#332, #506). Tenant and soft-delete criteria are attached for *every*
 tenant-scoped / soft-deletable model, not only the entities a statement
 names, so a table reached through a join target, an ORM ``exists()`` /
 ``in_()`` / scalar subquery or ``select(func.count()).select_from(Model)`` is
-filtered too. A Core statement on ``Model.__table__`` at the top level
-(select / update / delete) gets explicit predicates, and a bare Core
-``exists().where(...)`` has its inner SELECT rewritten (``subquery_guard``).
+filtered too. Core references to ``Model.__table__`` (or an alias of it) get
+explicit predicates at any depth — joins, subqueries, CTEs, compound
+selects, the extra FROM of an UPDATE / DELETE, an INSERT's SELECT source —
+see ``core_scope``.
 """
 
 from __future__ import annotations
@@ -16,12 +17,11 @@
 
 from sqlalchemy.engine import Engine
 from sqlalchemy.orm import ORMExecuteState, Session, with_loader_criteria
-from sqlalchemy.sql.selectable import Alias, Join
+from sqlalchemy.sql.selectable import Alias
 
 from simple_module_db import model_registry as registry
-from simple_module_db._outer_joins import is_excluded, orm_outer_join_tables
+from simple_module_db.core_scope import scope_core
 from simple_module_db.insert_guard import assigned_tenant_ids, guard_insert
-from simple_module_db.subquery_guard import scope_exists_subqueries
 from simple_module_db.tenancy import (
     ALL_TENANTS_OPTION,
     DEFAULT_TENANT_ID,
@@ -95,6 +95,7 @@ def filter_statements(execute_state: ORMExecuteState) -> Any:
     """
     if execute_state.is_insert:
         session = execute_state.session
+        _scope_insert_source(execute_state)
         return guard_insert(
             execute_state,
             strict=strict_configured(session),
@@ -121,31 +122,63 @@ def filter_statements(execute_state: ORMExecuteState) -> Any:
     for mapper in execute_state.all_mappers:
         if registry.flags(mapper.class_)[1]:
             named.append(mapper.class_)
+    execute_state.statement = scope_core(
+        execute_state.statement,
+        _subquery_predicates(skip_soft_delete, skip_tenant, tenant_id, strict),
+        _scoped_names(skip_soft_delete, skip_tenant),
+        _orm_covered(skip_soft_delete, skip_tenant, tenant_id),
+    )
     if not skip_soft_delete:
-        options.extend(_soft_delete_criteria(execute_state))
+        options.extend(
+            with_loader_criteria(c, c.is_deleted.is_(False), include_aliases=True)
+            for c in registry.soft_delete_classes
+        )
     if not skip_tenant:
         options.extend(_tenant_criteria(execute_state, named, tenant_id, strict))
-    if registry.tenant_classes or registry.soft_delete_classes:
-        execute_state.statement = scope_exists_subqueries(
-            execute_state.statement,
-            _subquery_predicates(skip_soft_delete, skip_tenant, tenant_id, strict),
-        )
 
     if options:
         execute_state.statement = execute_state.statement.options(*options)
     return None
 
 
-def _soft_delete_criteria(execute_state: ORMExecuteState) -> list[Any]:
-    plain = _plain_tables(
-        execute_state, registry.soft_delete_table_names, registry.soft_delete_classes
+def _scope_insert_source(execute_state: ORMExecuteState) -> None:
+    """``insert(...).from_select(..., select(t...))``: the source reads like any SELECT."""
+    if getattr(execute_state.statement, "select", None) is None:
+        return
+    options = execute_state.execution_options
+    skip_soft_delete = options.get("include_deleted", False)
+    skip_tenant = options.get(ALL_TENANTS_OPTION, False) or is_all_tenants()
+    tenant_id = current_tenant_id.get()
+    strict = strict_configured(execute_state.session)
+    execute_state.statement = scope_core(
+        execute_state.statement,
+        _subquery_predicates(skip_soft_delete, skip_tenant, tenant_id, strict),
+        _scoped_names(skip_soft_delete, skip_tenant),
     )
-    for table in plain:
-        execute_state.statement = execute_state.statement.where(table.c.is_deleted.is_(False))
-    return [
-        with_loader_criteria(c, c.is_deleted.is_(False), include_aliases=True)
-        for c in registry.soft_delete_classes
-    ]
+
+
+def _scoped_names(skip_soft_delete: bool, skip_tenant: bool) -> set[str]:
+    names: set[str] = set()
+    if not skip_soft_delete:
+        names |= registry.soft_delete_table_names
+    if not skip_tenant:
+        names |= registry.tenant_table_names
+    return names
+
+
+def _orm_covered(skip_soft_delete: bool, skip_tenant: bool, tenant_id: str | None) -> set[type]:
+    """Classes whose every predicate the loader criteria put in a join's ``ON`` (#417).
+
+    Strict mode without a tenant gives no tenant ``ON`` predicate worth the
+    name, so a tenant class is covered only once a tenant is bound: a bare
+    reference to it keeps refusing.
+    """
+    covered = set(registry.soft_delete_classes) if not skip_soft_delete else set()
+    if skip_tenant or tenant_id is not None:
+        covered |= registry.tenant_classes
+    else:
+        covered -= registry.tenant_classes
+    return covered
 
 
 def _subquery_predicates(
@@ -171,56 +204,22 @@ def predicates_for(from_obj: Any) -> list[Any]:
     return predicates_for
 
 
-def _plain_tables(
-    execute_state: ORMExecuteState, names: set[str], covered: set[type] | None = None
-) -> list[Any]:
-    """Tables a statement uses as plain Core tables (``Model.__table__``).
-
-    Only the top level: the FROM list of a select (including the sides of a
-    join), the target of an update/delete. ORM-annotated occurrences are
-    covered by loader criteria.
+def _dml_target(execute_state: ORMExecuteState, names: set[str]) -> list[Any]:
+    """The target of a Core UPDATE / DELETE on ``Model.__table__``, if scoped.
 
-    ``covered`` names the classes the caller gives loader criteria. A bare
-    columns-clause table that one of them outer-joins in (``func.count(
-    Child.id)`` strips the annotation) is that join's own ``FROM``, already
-    filtered in ``ON``; a ``WHERE`` on it would make the join inner (#417).
-    """
-    stmt = execute_state.statement
-    if not execute_state.is_select:
-        froms = [getattr(stmt, "table", None)]
-        return [f for f in _where_able(froms) if registry.is_plain_table(f, names)]
-    columns = getattr(stmt, "columns_clause_froms", ())
-    outer = orm_outer_join_tables(stmt, covered) if covered else []
-    columns = [f for f in columns if not (outer and is_excluded(f, outer))]
-    froms = [*columns, *getattr(stmt, "_from_obj", ())]
-    return [f for f in _where_able(froms) if registry.is_plain_table(f, names)]
-
-
-def _where_able(froms: list[Any]) -> list[Any]:
-    """Expand joins into the sides a ``WHERE`` can filter without changing them.
-
-    Both sides of an INNER join qualify. Of an OUTER join only the preserved
-    (left) side does: a ``WHERE`` on the nullable side would drop the very rows
-    the outer join was written to keep, turning it into an inner join.
+    Every other Core reference — in a SELECT, or joined in by an UPDATE /
+    DELETE — is scoped by ``core_scope``.
     """
-    out: list[Any] = []
-    for f in froms:
-        if isinstance(f, Join):
-            sides = [f.left] if f.isouter else [f.left, f.right]
-            if not getattr(f, "full", False):
-                out.extend(_where_able(sides))
-        else:
-            out.append(f)
-    return out
+    if execute_state.is_select:
+        return []
+    target = getattr(execute_state.statement, "table", None)
+    return [target] if registry.is_plain_table(target, names) else []
 
 
 def _tenant_criteria(
     execute_state: ORMExecuteState, named: list[type], tenant_id: str | None, strict: bool
 ) -> list[Any]:
-    # The ON-covered exclusion only applies once a tenant is bound: strict mode
-    # without one still refuses a table it would otherwise have WHERE-filtered.
-    covered = registry.tenant_classes if tenant_id is not None else None
-    core = _plain_tables(execute_state, registry.tenant_table_names, covered)
+    core = _dml_target(execute_state, registry.tenant_table_names)
     op = (
         "SELECT" if execute_state.is_select else ("UPDATE" if execute_state.is_update else "DELETE")
     )
@@ -245,6 +244,6 @@ def _tenant_criteria(
 
 def _refuse_tenant_move(execute_state: ORMExecuteState) -> None:
     named = any(registry.flags(m.class_)[1] for m in execute_state.all_mappers)
-    core = _plain_tables(execute_state, registry.tenant_table_names)
+    core = _dml_target(execute_state, registry.tenant_table_names)
     if (named or core) and assigned_tenant_ids(execute_state):
         raise TenantIsolationError("Cannot change tenant_id of existing rows")
diff --git a/framework/db/simple_module_db/subquery_guard.py b/framework/db/simple_module_db/subquery_guard.py
deleted file mode 100644
index 65355ec70..000000000
--- a/framework/db/simple_module_db/subquery_guard.py
+++ /dev/null
@@ -1,49 +0,0 @@
-"""Scope a bare Core ``exists().where(...)`` — the one shape loader criteria miss.
-
-``select(Model.id).where(...).exists()`` is ORM-compiled and gets the tenant
-and soft-delete criteria like any other statement. ``exists().where(Model.x
-== ...)`` is not: its inner SELECT has no entity in its columns, so SQLAlchemy
-never applies loader criteria to it (#332).
-
-The check is cheap and runs on every filtered statement: a walk of the WHERE,
-column and HAVING clauses looking for an ``Exists``. Only when one is found is
-the statement rewritten — every nested SELECT reading a tenant or soft-delete
-table gains the matching predicates. Duplicates of loader criteria are
-harmless.
-"""
-
-from __future__ import annotations
-
-from collections.abc import Callable
-from typing import Any
-
-from sqlalchemy.sql import visitors
-from sqlalchemy.sql.selectable import Exists, Select
-
-Predicates = Callable[[Any], list[Any]]
-
-
-def _has_exists(stmt: Any) -> bool:
-    roots = [
-        *getattr(stmt, "_where_criteria", ()),
-        *getattr(stmt, "_raw_columns", ()),
-        *getattr(stmt, "_having_criteria", ()),
-    ]
-    return any(isinstance(el, Exists) for root in roots for el in visitors.iterate(root))
-
-
-def scope_exists_subqueries(stmt: Any, predicates_for: Predicates) -> Any:
-    """Return ``stmt`` with nested SELECTs scoped, or ``stmt`` unchanged."""
-    if not _has_exists(stmt):
-        return stmt
-
-    def replace(element: Any) -> Any:
-        if element is stmt or not isinstance(element, Select):
-            return None
-        preds = [p for from_obj in element.get_final_froms() for p in predicates_for(from_obj)]
-        return element.where(*preds) if preds else None
-
-    return visitors.replacement_traverse(stmt, {}, replace)
-
-
-__all__ = ["scope_exists_subqueries"]
diff --git a/framework/db/tests/_core_scope_models.py b/framework/db/tests/_core_scope_models.py
new file mode 100644
index 000000000..eb51f3b6a
--- /dev/null
+++ b/framework/db/tests/_core_scope_models.py
@@ -0,0 +1,95 @@
+"""Models and seed data for the Core-statement scoping tests (#506).
+
+Tenant A owns tags ``used`` (id 1) and ``unused`` (id 2) and one link to
+``used``. Tenant B owns ``b-tag`` (id 3) and three links aimed at A's
+``used`` tag — the leak probe: any shape that lets them through counts 4
+links for ``used`` instead of 1. ``_Soft`` has a live and a trashed row
+for ``used``; ``_Plain`` (no mixins) has ids 1 and 3.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator
+
+import pytest
+from simple_module_db.base import create_module_base
+from simple_module_db.listeners import register_listeners
+from simple_module_db.mixins import MultiTenantMixin, SoftDeleteMixin
+from simple_module_db.query_filter import EngineTenancy, bind_engine_policy
+from simple_module_db.session import init_db
+from simple_module_db.tenancy import current_tenant_id, tenant_context
+from simple_module_test.database import database_url_for_tests, init_db_kwargs, reset_schema
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlmodel import Field
+
+_URL = database_url_for_tests()
+_Base = create_module_base("cscope")
+
+
+class Tag(_Base, MultiTenantMixin, table=True):  # type: ignore[call-arg]  # ty: ignore[unsupported-base]
+    __tablename__ = "cscope_tag"
+    id: int | None = Field(default=None, primary_key=True)
+    name: str = Field(default="", max_length=100)
+
+
+class Link(_Base, MultiTenantMixin, table=True):  # type: ignore[call-arg]  # ty: ignore[unsupported-base]
+    __tablename__ = "cscope_link"
+    id: int | None = Field(default=None, primary_key=True)
+    tag_id: int | None = None
+    article_id: int = 0
+
+
+class Soft(_Base, SoftDeleteMixin, table=True):  # type: ignore[call-arg]  # ty: ignore[unsupported-base]
+    __tablename__ = "cscope_soft"
+    id: int | None = Field(default=None, primary_key=True)
+    tag_id: int | None = None
+
+
+class Plain(_Base, table=True):  # type: ignore[call-arg]  # ty: ignore[unsupported-base]
+    __tablename__ = "cscope_plain"
+    id: int | None = Field(default=None, primary_key=True)
+    name: str = Field(default="", max_length=100)
+
+
+tag, link, soft, plain = Tag.__table__, Link.__table__, Soft.__table__, Plain.__table__
+
+
+async def _seed(session: AsyncSession) -> None:
+    session.add_all([Plain(id=1, name="p1"), Plain(id=3, name="p3")])
+    with tenant_context("A"):
+        session.add_all([Tag(id=1, name="used"), Tag(id=2, name="unused")])
+        session.add(Link(id=1, tag_id=1, article_id=1))
+        session.add_all([Soft(id=1, tag_id=1), Soft(id=2, tag_id=1, is_deleted=True)])
+        await session.flush()
+    with tenant_context("B"):
+        session.add(Tag(id=3, name="b-tag"))
+        session.add_all([Link(id=n, tag_id=1, article_id=n) for n in (7, 8, 9)])
+        await session.flush()
+    await session.commit()
+
+
+@pytest.fixture
+async def seeded() -> AsyncGenerator[AsyncSession, None]:
+    """A session acting as tenant A over the seeded rows."""
+    state = init_db(_URL, **init_db_kwargs(_URL))
+    try:
+        register_listeners(state)
+        await reset_schema(state.engine)
+        async with state.engine.begin() as conn:
+            await conn.run_sync(_Base.metadata.create_all)
+        async with state.session_factory() as session:
+            await _seed(session)
+        async with state.session_factory() as session:
+            token = current_tenant_id.set("A")
+            try:
+                yield session
+            finally:
+                current_tenant_id.reset(token)
+    finally:
+        await state.engine.dispose()
+
+
+def make_strict(session: AsyncSession) -> None:
+    """Strict isolation with no tenant bound: every Core reference must refuse."""
+    bind_engine_policy(session.bind.sync_engine, EngineTenancy(tenant_strict=True))
+    current_tenant_id.set(None)
diff --git a/framework/db/tests/test_db_core_join_scope.py b/framework/db/tests/test_db_core_join_scope.py
new file mode 100644
index 000000000..cf04c04a0
--- /dev/null
+++ b/framework/db/tests/test_db_core_join_scope.py
@@ -0,0 +1,137 @@
+"""Core joins over ``Model.__table__`` are tenant / soft-delete scoped (#506).
+
+An outer join's nullable side must be filtered without turning the join
+inner: ``unused`` (no links in tenant A) must survive, and tenant B's three
+links to ``used`` must never be counted.
+"""
+
+from __future__ import annotations
+
+import pytest
+from _core_scope_models import link, make_strict, plain, seeded, soft, tag
+from simple_module_db.tenancy import TenantIsolationError
+from sqlalchemy import func, select
+
+__all__ = ["seeded"]
+
+
+async def _rows(session, stmt, **options):
+    if options:
+        stmt = stmt.execution_options(**options)
+    return sorted((await session.execute(stmt)).all(), key=repr)
+
+
+def _link_counts(right=None, *, on=None):
+    right = link if right is None else right
+    on = right.c.tag_id == tag.c.id if on is None else on
+    return (
+        select(tag.c.name, func.count(right.c.id))
+        .select_from(tag.outerjoin(right, on))
+        .group_by(tag.c.name)
+    )
+
+
+async def test_left_join_count_star_keeps_parent_and_isolates(seeded):
+    stmt = (
+        select(tag.c.name, func.count())
+        .select_from(tag.outerjoin(link, link.c.tag_id == tag.c.id))
+        .group_by(tag.c.name)
+    )
+    assert dict(await _rows(seeded, stmt)) == {"used": 1, "unused": 1}
+
+
+async def test_left_join_column_count(seeded):
+    assert dict(await _rows(seeded, _link_counts())) == {"used": 1, "unused": 0}
+
+
+async def test_left_join_selected_child_column_stays_outer(seeded):
+    stmt = select(tag.c.name, link.c.article_id).select_from(
+        tag.outerjoin(link, link.c.tag_id == tag.c.id)
+    )
+    assert await _rows(seeded, stmt) == [("unused", None), ("used", 1)]
+
+
+async def test_aliased_right_table(seeded):
+    alias = link.alias("l2")
+    assert dict(await _rows(seeded, _link_counts(alias))) == {"used": 1, "unused": 0}
+
+
+async def test_soft_deleted_right_row(seeded):
+    on = soft.c.tag_id == tag.c.id
+    assert dict(await _rows(seeded, _link_counts(soft, on=on))) == {"used": 1, "unused": 0}
+
+
+async def test_include_deleted_is_honoured(seeded):
+    stmt = _link_counts(soft, on=soft.c.tag_id == tag.c.id)
+    assert dict(await _rows(seeded, stmt, include_deleted=True)) == {"used": 2, "unused": 0}
+
+
+async def test_all_tenants_is_honoured(seeded):
+    rows = dict(await _rows(seeded, _link_counts(), all_tenants=True))
+    assert rows == {"used": 4, "unused": 0, "b-tag": 0}
+
+
+async def test_inner_join(seeded):
+    stmt = (
+        select(tag.c.name, func.count())
+        .select_from(tag.join(link, link.c.tag_id == tag.c.id))
+        .group_by(tag.c.name)
+    )
+    assert dict(await _rows(seeded, stmt)) == {"used": 1}
+
+
+async def test_full_join_both_sides_scoped(seeded):
+    stmt = select(tag.c.name, link.c.article_id).select_from(
+        tag.outerjoin(link, link.c.tag_id == tag.c.id, full=True)
+    )
+    assert await _rows(seeded, stmt) == [("unused", None), ("used", 1)]
+
+
+async def test_full_join_unscoped_left(seeded):
+    stmt = select(plain.c.name, link.c.article_id).select_from(
+        plain.outerjoin(link, link.c.tag_id == plain.c.id, full=True)
+    )
+    assert await _rows(seeded, stmt) == [("p1", 1), ("p3", None)]
+
+
+async def test_join_chain(seeded):
+    stmt = select(tag.c.name, link.c.article_id, soft.c.id).select_from(
+        tag.outerjoin(link, link.c.tag_id == tag.c.id).outerjoin(soft, soft.c.tag_id == tag.c.id)
+    )
+    assert await _rows(seeded, stmt) == [("unused", None, None), ("used", 1, 1)]
+
+
+async def test_nested_join_as_nullable_side(seeded):
+    inner = link.join(soft, soft.c.tag_id == link.c.tag_id)
+    stmt = select(tag.c.name, link.c.article_id, soft.c.id).select_from(
+        tag.outerjoin(inner, link.c.tag_id == tag.c.id)
+    )
+    assert await _rows(seeded, stmt) == [("unused", None, None), ("used", 1, 1)]
+
+
+async def test_select_outerjoin_method_on_core_table(seeded):
+    """``select(...).outerjoin(link, ...)`` records a setup join, not a ``Join``."""
+    stmt = (
+        select(tag.c.name, func.count())
+        .select_from(tag)
+        .outerjoin(link, link.c.tag_id == tag.c.id)
+        .group_by(tag.c.name)
+    )
+    assert dict(await _rows(seeded, stmt)) == {"used": 1, "unused": 1}
+
+
+async def test_select_full_outerjoin_method_on_core_table(seeded):
+    stmt = select(plain.c.name, link.c.article_id).outerjoin_from(
+        plain, link, link.c.tag_id == plain.c.id, full=True
+    )
+    assert await _rows(seeded, stmt) == [("p1", 1), ("p3", None)]
+
+
+@pytest.mark.parametrize("full", [False, True])
+async def test_strict_without_tenant_refuses_a_core_join(seeded, full):
+    make_strict(seeded)
+    stmt = select(plain.c.name, link.c.article_id).select_from(
+        plain.outerjoin(link, link.c.tag_id == plain.c.id, full=full)
+    )
+    with pytest.raises(TenantIsolationError):
+        await seeded.execute(stmt)
diff --git a/framework/db/tests/test_db_core_nested_scope.py b/framework/db/tests/test_db_core_nested_scope.py
new file mode 100644
index 000000000..994a55356
--- /dev/null
+++ b/framework/db/tests/test_db_core_nested_scope.py
@@ -0,0 +1,136 @@
+"""Core references below the top level are tenant / soft-delete scoped (#506).
+
+Aliases, subqueries, CTEs, scalar subqueries, compound selects, the extra
+FROM of an UPDATE / DELETE, an INSERT ... SELECT source and ``exists()``
+over a join or inside an ``ON`` clause. Tenant A sees one link (id 1);
+tenant B's links (7, 8, 9) must never surface.
+"""
+
+from __future__ import annotations
+
+import pytest
+from _core_scope_models import link, make_strict, plain, seeded, soft, tag
+from simple_module_db.tenancy import TenantIsolationError
+from simple_module_test.database import database_is_postgres
+from sqlalchemy import (
+    and_,
+    delete,
+    except_,
+    exists,
+    func,
+    insert,
+    intersect,
+    literal,
+    select,
+    union,
+    union_all,
+    update,
+)
+
+__all__ = ["seeded"]
+
+
+def _link_ids():
+    return select(link.c.id)
+
+
+SHAPES = {
+    "alias": (lambda: select(link.alias("a").c.id), [(1,)]),
+    "alias count": (lambda: select(func.count()).select_from(tag.alias("a")), [(2,)]),
+    "subquery": (lambda: select(select(link).subquery().c.id), [(1,)]),
+    "cte": (lambda: select(select(link).cte("c").c.id), [(1,)]),
+    "count of cte": (
+        lambda: select(func.count()).select_from(select(soft.c.id).cte("sc")),
+        [(1,)],
+    ),
+    "scalar subquery": (
+        lambda: select(select(func.count()).select_from(link).scalar_subquery()),
+        [(1,)],
+    ),
+    "correlated scalar": (
+        lambda: select(
+            tag.c.name,
+            select(func.count()).where(link.c.tag_id == tag.c.id).scalar_subquery(),
+        ),
+        [("unused", 0), ("used", 1)],
+    ),
+    "where-only from": (lambda: select(func.count()).where(link.c.tag_id == 1), [(1,)]),
+    "union": (lambda: union(_link_ids(), _link_ids()), [(1,)]),
+    "union_all": (lambda: union_all(_link_ids(), _link_ids()), [(1,), (1,)]),
+    "intersect": (lambda: intersect(_link_ids(), _link_ids()), [(1,)]),
+    "except": (lambda: except_(_link_ids(), select(link.c.id).where(link.c.id == 0)), [(1,)]),
+    "exists over join": (
+        lambda: select(plain.c.name).where(
+            exists(
+                select(link.c.id)
+                .select_from(link.join(tag, tag.c.id == link.c.tag_id))
+                .where(link.c.article_id == 7)
+            )
+        ),
+        [],
+    ),
+    "exists in ON": (
+        lambda: select(plain.c.name).select_from(
+            plain.join(
+                tag,
+                and_(
+                    tag.c.id == plain.c.id,
+                    exists().where(link.c.tag_id == tag.c.id, link.c.article_id == 7),
+                ),
+            )
+        ),
+        [],
+    ),
+    # Codex: not leaks before #506 either — kept as regressions.
+    "core inner join": (
+        lambda: select(link.c.id).select_from(link.join(tag, tag.c.id == link.c.tag_id)),
+        [(1,)],
+    ),
+    "single-table exists": (
+        lambda: select(plain.c.name).where(exists().where(link.c.article_id == 7)),
+        [],
+    ),
+}
+
+
+@pytest.mark.parametrize("shape", list(SHAPES))
+async def test_shape_never_sees_other_tenants(seeded, shape):
+    build, expected = SHAPES[shape]
+    assert sorted((await seeded.execute(build())).all(), key=repr) == expected
+
+
+@pytest.mark.parametrize("shape", ["alias", "subquery", "cte", "union", "exists over join"])
+async def test_strict_without_tenant_refuses(seeded, shape):
+    make_strict(seeded)
+    with pytest.raises(TenantIsolationError):
+        await seeded.execute(SHAPES[shape][0]())
+
+
+async def test_all_tenants_option_reaches_nested_selects(seeded):
+    stmt = select(select(link).subquery().c.id).execution_options(all_tenants=True)
+    assert len((await seeded.execute(stmt)).all()) == 4
+
+
+async def test_update_from_another_tenants_row_matches_nothing(seeded):
+    stmt = (
+        update(plain).where(plain.c.id == tag.c.id, tag.c.name == "b-tag").values(name="hijacked")
+    )
+    assert (await seeded.execute(stmt)).rowcount == 0
+
+
+async def test_delete_through_subquery_matches_nothing(seeded):
+    stmt = delete(plain).where(plain.c.id.in_(select(tag.c.id).where(tag.c.name == "b-tag")))
+    assert (await seeded.execute(stmt)).rowcount == 0
+
+
+@pytest.mark.skipif(not database_is_postgres(), reason="DELETE ... USING needs Postgres")
+async def test_delete_using_another_tenants_row_matches_nothing(seeded):
+    stmt = delete(plain).where(plain.c.id == tag.c.id, tag.c.name == "b-tag")
+    assert (await seeded.execute(stmt)).rowcount == 0
+
+
+async def test_insert_from_select_copies_only_own_rows(seeded):
+    source = select((link.c.id + 100).label("id"), literal("copy").label("name"))
+    await seeded.execute(insert(plain).from_select(["id", "name"], source))
+    copied = select(plain.c.id).where(plain.c.id >= 100)
+    assert (await seeded.execute(copied)).all() == [(101,)]
diff --git a/framework/db/tests/test_query_filter_outer_joins.py b/framework/db/tests/test_query_filter_outer_joins.py
index 035880a78..85e75c88a 100644
--- a/framework/db/tests/test_query_filter_outer_joins.py
+++ b/framework/db/tests/test_query_filter_outer_joins.py
@@ -151,7 +151,7 @@ async def test_inner_join_still_filters_the_child(seeded):
 
 
 async def test_raw_table_outer_join_stays_filtered(seeded):
-    """A Core table target gets no ON criteria, so it keeps the WHERE predicate (no leak)."""
+    """A Core table target gets its predicate in ON (#506): the join stays outer, no leak."""
     link = _TagLink.__table__
     stmt = (
         select(_Tag.name, func.count(link.c.article_id))
@@ -159,8 +159,7 @@ async def test_raw_table_outer_join_stays_filtered(seeded):
         .outerjoin(link, link.c.tag_id == _Tag.id)
         .group_by(_Tag.name)
     )
-    rows = dict((await seeded.execute(stmt)).all())
-    assert rows.get("used") == 1  # never 4 (tenant B's links)
+    assert dict((await seeded.execute(stmt)).all()) == {"used": 1, "unused": 0}
 
 
 async def test_raw_column_of_orm_outer_target_never_sees_other_tenants(seeded):
@@ -189,12 +188,11 @@ async def test_soft_deleted_outer_child_keeps_the_parent(seeded):
     assert dict((await seeded.execute(stmt)).all()) == {"used": 1, "unused": 0}
 
 
-@pytest.mark.xfail(strict=True, reason="pre-existing: Core outer join right side unfiltered")
 async def test_core_outer_join_right_side_is_tenant_filtered(seeded):
-    """A pure Core ``tag.outerjoin(link)`` gets no ``ON`` criteria and no ``WHERE``.
+    """A pure Core ``tag.outerjoin(link)`` gets the link's predicate in ``ON`` (#506).
 
-    ``_where_able`` keeps the nullable side out of ``WHERE`` (correctly), but
-    nothing else filters a Core table, so ``count(*)`` counts tenant B's links.
+    A ``WHERE`` on the nullable side would drop ``unused``; nothing at all
+    would let ``count(*)`` count tenant B's links.
     """
     tag, link = _Tag.__table__, _TagLink.__table__
     stmt = (

From 09b1630290940bcaf6a52dc5774b0699e5b2ed2b Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Mon, 19 Oct 2026 14:01:50 +0200
Subject: [PATCH 11/14] docs: changelog for #494 #495 #497 #498 #499 #503 #506
 #554

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 CHANGELOG.md | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0cc8b5a5b..1e1299f54 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,24 @@ All notable changes to this project are documented in this file. The format is b
 ## [Unreleased]
 
 ### Changed
+- **Behaviour change (#494):** a pre-app settings read that fails (connection,
+  query, import error) is no longer treated as a fresh install. Outside
+  development and testing the host and the Celery worker refuse to boot with
+  `HostSettingsUnavailableError` instead of building with defaults (which
+  silently disabled `multi_tenant`). Only a missing settings table falls back
+  quietly. Likewise the secret key: an ephemeral key is used only before the
+  settings table exists; otherwise boot fails with `SecretKeyUnavailableError`,
+  and a blank stored key is replaced atomically.
+- **Behaviour change (#495):** the session cookie is `Secure` outside
+  development and testing. New `HostSettings.session_cookie_secure`
+  (`SM_SESSION_COOKIE_SECURE`); set `SM_TRUSTED_PROXY` behind a TLS terminator,
+  and `false` only for installs that serve browsers plain HTTP on purpose.
+- **Behaviour change (#498):** with `audit_log` installed, writes made in Celery
+  tasks and durable outbox handlers are audited (including `TaskExecution`
+  status changes). The audit callback is bound per engine instead of a
+  process-global, through the new `simple_module.audit_sinks` entry-point
+  group. Worker tests that build a database without the audit table need the
+  sink off (see `background_tasks/tests/conftest.py`).
 - **Behaviour change (#530):** password-login lockout now holds across workers,
   source IPs and restarts. `users.login_lockout_account_failures` (new, default
   10) failures for one account within `login_rate_limit_window_seconds`, from
@@ -348,6 +366,12 @@ All notable changes to this project are documented in this file. The format is b
   *complete* verdict now keeps answering while one refresh runs.
 
 ### Security
+- Tenant and soft-delete filters now cover Core statements that used to leak
+  other tenants' or deleted rows (#506): outer and FULL joins over
+  `Model.__table__`, table aliases, subqueries, CTEs, scalar/correlated
+  subqueries, `exists()` over joins or in ON clauses, `union`/`intersect`/
+  `except`, tables joined into UPDATE/DELETE, and `insert().from_select()`
+  sources. Raw `text()` SQL remains unfiltered by design.
 - `smpy new` no longer writes generated secrets into the committed
   `.env.example` (#441). `SM_SECRET_KEY` and the users token secrets go to a
   gitignored `.env` (created if absent; an existing one only gains missing
@@ -364,6 +388,18 @@ All notable changes to this project are documented in this file. The format is b
   `tenants` resolver it selects among the user's own memberships.
 
 ### Fixed
+- A stored host setting that parses but fails validation (or an unrecognised
+  boolean like `"tru"`) is dropped with a WARNING instead of crashing boot or
+  reading as false (#497); one failing module settings read no longer resets
+  that module or poisons the others' reads.
+- Every `HostSettings` field `create_app` reads is marked restart-required, so
+  the settings editor says so (#499).
+- An established install whose setup check raises no longer drops into the
+  first-run wizard.
+- The admin mobile sidebar drawer closes on Escape, traps focus and is a
+  labelled dialog while open (#554).
+- Docs describe the real migration graph (two roots, four heads, inherited
+  labels), pinned by a test (#503).
 - `file_storage` browse page: a caller without `file_storage.manage` sees their
   own usage and no tenant quota, instead of the tenant-wide total; the
   authenticated download now carries the same sandbox CSP as public serving.

From 85592da70b1e6692e913a5d2f95631cf410782e6 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Mon, 19 Oct 2026 14:13:40 +0200
Subject: [PATCH 12/14] =?UTF-8?q?refactor(optimize):=20duplication=20?=
 =?UTF-8?q?=E2=80=94=20share=20tenancy=20alias=20helpers,=20hosting=20sett?=
 =?UTF-8?q?ings-db=20seeder,=20db=20test=20session=20builder?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- _base_name/_is_orm move to _core_joins; is_plain_leaf and predicates_for use them
  (is_plain_leaf keeps its own Alias loop: it needs the base element, not its name)
- query_filter calls engine_policy directly (drop _policy alias)
- framework/hosting/tests/_hosting_settings_db.py: one settings_setting seeder,
  unmigrated-DB helper and connection-refused coroutine
- db tests: _tenant_session takes metadata + optional seed, lives in _models.py;
  seeded builds on it; _rows shared from _core_scope_models
- host_settings: _RESTART_SECURITY constant

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 framework/db/simple_module_db/_core_joins.py  | 12 ++++-
 framework/db/simple_module_db/core_scope.py   | 18 +++----
 framework/db/simple_module_db/query_filter.py | 14 ++---
 framework/db/tests/_core_scope_models.py      | 33 +++++-------
 framework/db/tests/_models.py                 | 39 ++++++++++++++
 framework/db/tests/conftest.py                | 32 ++----------
 framework/db/tests/test_db_core_join_scope.py |  8 +--
 .../db/tests/test_db_core_nested_scope.py     |  4 +-
 .../simple_module_hosting/host_settings.py    |  5 +-
 .../hosting/tests/_hosting_settings_db.py     | 51 +++++++++++++++++++
 .../tests/test_boot_config_hardening.py       | 33 +++---------
 framework/hosting/tests/test_preapp_config.py | 32 ++----------
 .../tests/test_preapp_invalid_values.py       | 19 +------
 .../tests/test_preapp_read_failures.py        | 13 +----
 .../tests/test_secret_key_bootstrap.py        | 25 ++-------
 15 files changed, 149 insertions(+), 189 deletions(-)
 create mode 100644 framework/hosting/tests/_hosting_settings_db.py

diff --git a/framework/db/simple_module_db/_core_joins.py b/framework/db/simple_module_db/_core_joins.py
index b91870481..0802a84f1 100644
--- a/framework/db/simple_module_db/_core_joins.py
+++ b/framework/db/simple_module_db/_core_joins.py
@@ -38,9 +38,19 @@
 Predicates = Callable[[Any], list[Any]]
 
 
+def _base_name(from_obj: Any) -> str | None:
+    while isinstance(from_obj, Alias):  # ``table.alias().alias()`` nests
+        from_obj = from_obj.element
+    return getattr(from_obj, "name", None)
+
+
+def _is_orm(el: Any) -> bool:
+    return "parententity" in getattr(el, "_annotations", {})
+
+
 def is_plain_leaf(node: Any) -> bool:
     """A Core table or alias of one — not an ORM-annotated occurrence."""
-    if "parententity" in getattr(node, "_annotations", {}):
+    if _is_orm(node):
         return False
     base = node
     while isinstance(base, Alias):
diff --git a/framework/db/simple_module_db/core_scope.py b/framework/db/simple_module_db/core_scope.py
index a372a72ac..795a90557 100644
--- a/framework/db/simple_module_db/core_scope.py
+++ b/framework/db/simple_module_db/core_scope.py
@@ -29,20 +29,16 @@
 from sqlalchemy.sql.selectable import Alias, Join, Select, TableClause
 from sqlalchemy.sql.visitors import HasTraverseInternals
 
-from simple_module_db._core_joins import Predicates, is_plain_leaf, scope_joins
+from simple_module_db._core_joins import (
+    Predicates,
+    _base_name,
+    _is_orm,
+    is_plain_leaf,
+    scope_joins,
+)
 from simple_module_db._outer_joins import is_excluded, orm_outer_join_tables
 
 
-def _base_name(from_obj: Any) -> str | None:
-    while isinstance(from_obj, Alias):
-        from_obj = from_obj.element
-    return getattr(from_obj, "name", None)
-
-
-def _is_orm(el: Any) -> bool:
-    return "parententity" in getattr(el, "_annotations", {})
-
-
 def _orm_less(stmt: Any) -> bool:
     """A SELECT naming no ORM entity in its columns, FROM list or joins.
 
diff --git a/framework/db/simple_module_db/query_filter.py b/framework/db/simple_module_db/query_filter.py
index 3094bee17..8c9cc216f 100644
--- a/framework/db/simple_module_db/query_filter.py
+++ b/framework/db/simple_module_db/query_filter.py
@@ -18,9 +18,9 @@
 
 from sqlalchemy.engine import Engine
 from sqlalchemy.orm import ORMExecuteState, Session, with_loader_criteria
-from sqlalchemy.sql.selectable import Alias
 
 from simple_module_db import model_registry as registry
+from simple_module_db._core_joins import _base_name
 from simple_module_db.core_scope import scope_core
 from simple_module_db.insert_guard import assigned_tenant_ids, guard_insert
 from simple_module_db.tenancy import (
@@ -73,11 +73,8 @@ def engine_policy(session: Session) -> Any:
     return _engine_policy.get(bind) if isinstance(bind, Engine) else None
 
 
-_policy = engine_policy
-
-
 def strict_configured(session: Session) -> bool:
-    policy = _policy(session)
+    policy = engine_policy(session)
     return bool(policy is not None and policy.tenant_strict)
 
 
@@ -87,7 +84,7 @@ def fallback_tenant_id(session: Session) -> str:
     The install's ``default_tenant`` when the host set one (published as
     ``DatabaseState.default_tenant_id``), else :data:`DEFAULT_TENANT_ID`.
     """
-    policy = _policy(session)
+    policy = engine_policy(session)
     return getattr(policy, "default_tenant_id", None) or DEFAULT_TENANT_ID
 
 
@@ -203,10 +200,7 @@ def _subquery_predicates(
     def predicates_for(from_obj: Any) -> list[Any]:
         # ``aliased(Model)`` / ``table.alias()`` is named after the alias, not
         # the table: resolve to the underlying table, filter on the alias.
-        base = from_obj
-        while isinstance(base, Alias):  # ``table.alias().alias()`` nests
-            base = base.element
-        name = getattr(base, "name", None)
+        name = _base_name(from_obj)
         preds = []
         if not skip_soft_delete and name in registry.soft_delete_table_names:
             preds.append(from_obj.c.is_deleted.is_(False))
diff --git a/framework/db/tests/_core_scope_models.py b/framework/db/tests/_core_scope_models.py
index eb51f3b6a..a7a11b2e3 100644
--- a/framework/db/tests/_core_scope_models.py
+++ b/framework/db/tests/_core_scope_models.py
@@ -12,17 +12,14 @@
 from collections.abc import AsyncGenerator
 
 import pytest
+from _models import _tenant_session
 from simple_module_db.base import create_module_base
-from simple_module_db.listeners import register_listeners
 from simple_module_db.mixins import MultiTenantMixin, SoftDeleteMixin
 from simple_module_db.query_filter import EngineTenancy, bind_engine_policy
-from simple_module_db.session import init_db
 from simple_module_db.tenancy import current_tenant_id, tenant_context
-from simple_module_test.database import database_url_for_tests, init_db_kwargs, reset_schema
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlmodel import Field
 
-_URL = database_url_for_tests()
 _Base = create_module_base("cscope")
 
 
@@ -71,22 +68,18 @@ async def _seed(session: AsyncSession) -> None:
 @pytest.fixture
 async def seeded() -> AsyncGenerator[AsyncSession, None]:
     """A session acting as tenant A over the seeded rows."""
-    state = init_db(_URL, **init_db_kwargs(_URL))
-    try:
-        register_listeners(state)
-        await reset_schema(state.engine)
-        async with state.engine.begin() as conn:
-            await conn.run_sync(_Base.metadata.create_all)
-        async with state.session_factory() as session:
-            await _seed(session)
-        async with state.session_factory() as session:
-            token = current_tenant_id.set("A")
-            try:
-                yield session
-            finally:
-                current_tenant_id.reset(token)
-    finally:
-        await state.engine.dispose()
+    async for session in _tenant_session(_Base.metadata, strict=False, seed=_seed):
+        token = current_tenant_id.set("A")
+        try:
+            yield session
+        finally:
+            current_tenant_id.reset(token)
+
+
+async def _rows(session, stmt, **options):
+    if options:
+        stmt = stmt.execution_options(**options)
+    return sorted((await session.execute(stmt)).all(), key=repr)
 
 
 def make_strict(session: AsyncSession) -> None:
diff --git a/framework/db/tests/_models.py b/framework/db/tests/_models.py
index b1447928a..9a89c8222 100644
--- a/framework/db/tests/_models.py
+++ b/framework/db/tests/_models.py
@@ -8,10 +8,19 @@
 
 from __future__ import annotations
 
+from collections.abc import AsyncGenerator, Awaitable, Callable
+
 from simple_module_db.base import create_module_base
+from simple_module_db.listeners import register_listeners
 from simple_module_db.mixins import MultiTenantMixin, SoftDeleteMixin
+from simple_module_db.session import init_db
+from simple_module_test.database import database_url_for_tests, init_db_kwargs, reset_schema
+from sqlalchemy import MetaData
+from sqlalchemy.ext.asyncio import AsyncSession
 from sqlmodel import Field
 
+_URL = database_url_for_tests()
+
 _TenantBase = create_module_base("mt_test")
 
 
@@ -38,3 +47,33 @@ class _TxnThing(_TxnBase, table=True):  # ty: ignore[unsupported-base]
     __tablename__ = "txn_test_thing"
     id: int | None = Field(default=None, primary_key=True)
     name: str = Field(max_length=100)
+
+
+async def _tenant_session(
+    metadata: MetaData,
+    *,
+    strict: bool,
+    default_tenant: str | None = None,
+    seed: Callable[[AsyncSession], Awaitable[None]] | None = None,
+) -> AsyncGenerator[AsyncSession, None]:
+    """A session over ``metadata``'s tables with tenant listeners registered.
+
+    ``seed`` runs in its own session first, so the yielded one starts clean.
+    """
+    db_state = init_db(_URL, **init_db_kwargs(_URL))
+    db_state.tenant_strict = strict
+    if default_tenant:
+        db_state.default_tenant_id = default_tenant
+    try:
+        register_listeners(db_state)
+        await reset_schema(db_state.engine)
+        async with db_state.engine.begin() as conn:
+            await conn.run_sync(metadata.create_all)
+        if seed is not None:
+            async with db_state.session_factory() as session:
+                await seed(session)
+        async with db_state.session_factory() as session:
+            yield session
+    finally:
+        db_state.tenant_strict = False
+        await db_state.engine.dispose()
diff --git a/framework/db/tests/conftest.py b/framework/db/tests/conftest.py
index 55191436c..5027ffae3 100644
--- a/framework/db/tests/conftest.py
+++ b/framework/db/tests/conftest.py
@@ -5,50 +5,26 @@
 from collections.abc import AsyncGenerator
 
 import pytest
-from _models import _TenantBase
-from simple_module_db.listeners import register_listeners
-from simple_module_db.session import init_db
-from simple_module_test.database import database_url_for_tests, init_db_kwargs, reset_schema
+from _models import _tenant_session, _TenantBase
 from sqlalchemy.ext.asyncio import AsyncSession
 
-_URL = database_url_for_tests()
-
-
-async def _tenant_session(
-    *, strict: bool, default_tenant: str | None = None
-) -> AsyncGenerator[AsyncSession, None]:
-    db_state = init_db(_URL, **init_db_kwargs(_URL))
-    db_state.tenant_strict = strict
-    if default_tenant:
-        db_state.default_tenant_id = default_tenant
-    try:
-        register_listeners(db_state)
-        await reset_schema(db_state.engine)
-        async with db_state.engine.begin() as conn:
-            await conn.run_sync(_TenantBase.metadata.create_all)
-        async with db_state.session_factory() as session:
-            yield session
-    finally:
-        db_state.tenant_strict = False
-        await db_state.engine.dispose()
-
 
 @pytest.fixture
 async def tenant_session() -> AsyncGenerator[AsyncSession, None]:
     """Session backed by in-memory SQLite with tenant listeners registered."""
-    async for session in _tenant_session(strict=False):
+    async for session in _tenant_session(_TenantBase.metadata, strict=False):
         yield session
 
 
 @pytest.fixture
 async def strict_session() -> AsyncGenerator[AsyncSession, None]:
     """Like ``tenant_session``, with fail-closed isolation (``multi_tenant`` on)."""
-    async for session in _tenant_session(strict=True):
+    async for session in _tenant_session(_TenantBase.metadata, strict=True):
         yield session
 
 
 @pytest.fixture
 async def acme_default_session() -> AsyncGenerator[AsyncSession, None]:
     """Single-tenant install with ``default_tenant="acme"``."""
-    async for session in _tenant_session(strict=False, default_tenant="acme"):
+    async for session in _tenant_session(_TenantBase.metadata, strict=False, default_tenant="acme"):
         yield session
diff --git a/framework/db/tests/test_db_core_join_scope.py b/framework/db/tests/test_db_core_join_scope.py
index cf04c04a0..9712045a5 100644
--- a/framework/db/tests/test_db_core_join_scope.py
+++ b/framework/db/tests/test_db_core_join_scope.py
@@ -8,19 +8,13 @@
 from __future__ import annotations
 
 import pytest
-from _core_scope_models import link, make_strict, plain, seeded, soft, tag
+from _core_scope_models import _rows, link, make_strict, plain, seeded, soft, tag
 from simple_module_db.tenancy import TenantIsolationError
 from sqlalchemy import func, select
 
 __all__ = ["seeded"]
 
 
-async def _rows(session, stmt, **options):
-    if options:
-        stmt = stmt.execution_options(**options)
-    return sorted((await session.execute(stmt)).all(), key=repr)
-
-
 def _link_counts(right=None, *, on=None):
     right = link if right is None else right
     on = right.c.tag_id == tag.c.id if on is None else on
diff --git a/framework/db/tests/test_db_core_nested_scope.py b/framework/db/tests/test_db_core_nested_scope.py
index 994a55356..2f24cc429 100644
--- a/framework/db/tests/test_db_core_nested_scope.py
+++ b/framework/db/tests/test_db_core_nested_scope.py
@@ -9,7 +9,7 @@
 from __future__ import annotations
 
 import pytest
-from _core_scope_models import link, make_strict, plain, seeded, soft, tag
+from _core_scope_models import _rows, link, make_strict, plain, seeded, soft, tag
 from simple_module_db.tenancy import TenantIsolationError
 from simple_module_test.database import database_is_postgres
 from sqlalchemy import (
@@ -96,7 +96,7 @@ def _link_ids():
 @pytest.mark.parametrize("shape", list(SHAPES))
 async def test_shape_never_sees_other_tenants(seeded, shape):
     build, expected = SHAPES[shape]
-    assert sorted((await seeded.execute(build())).all(), key=repr) == expected
+    assert await _rows(seeded, build()) == expected
 
 
 @pytest.mark.parametrize("shape", ["alias", "subquery", "cte", "union", "exists over join"])
diff --git a/framework/hosting/simple_module_hosting/host_settings.py b/framework/hosting/simple_module_hosting/host_settings.py
index 2a8723d73..0fdddc47b 100644
--- a/framework/hosting/simple_module_hosting/host_settings.py
+++ b/framework/hosting/simple_module_hosting/host_settings.py
@@ -39,6 +39,7 @@
 _RESTART_I18N = {"requires_restart": True, "group": "Localization"}
 _RESTART_AUTH = {"requires_restart": True, "group": "Authentication"}
 _RESTART_LOGGING = {"requires_restart": True, "group": "Logging"}
+_RESTART_SECURITY = {"requires_restart": True, "group": "Security"}
 
 
 def _default_api_version() -> str:
@@ -126,9 +127,7 @@ class HostSettings(BaseSettings):
     # and most providers reject it.
     trusted_proxy: str | None = Field(default=None, json_schema_extra=_RESTART_GUARD)
 
-    session_cookie_secure: bool | None = Field(
-        default=None, json_schema_extra={"requires_restart": True, "group": "Security"}
-    )
+    session_cookie_secure: bool | None = Field(default=None, json_schema_extra=_RESTART_SECURITY)
     """Mark the session cookie ``Secure`` (sent over HTTPS only).
 
     Unset (the default) means on outside development and testing, off in
diff --git a/framework/hosting/tests/_hosting_settings_db.py b/framework/hosting/tests/_hosting_settings_db.py
new file mode 100644
index 000000000..1b69ca4e5
--- /dev/null
+++ b/framework/hosting/tests/_hosting_settings_db.py
@@ -0,0 +1,51 @@
+"""Shared sqlite fixtures for the pre-app settings / secret-key tests.
+
+A hand-built ``settings_setting`` table stands in for the migrated one, so the
+pre-app read can be exercised without booting the app or running Alembic.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+from typing import NoReturn
+
+_CREATE = (
+    "CREATE TABLE settings_setting (id INTEGER PRIMARY KEY, scope TEXT NOT NULL, "
+    "scope_id TEXT NOT NULL, key TEXT NOT NULL, value TEXT NOT NULL, "
+    "value_type TEXT NOT NULL, UNIQUE (scope, scope_id, key))"
+)
+
+
+def seed_settings_db(
+    db_path: Path, rows: list[tuple[str, ...]], value_type: str | None = None
+) -> str:
+    """Create the settings table, insert system-scope rows, return its URL.
+
+    Rows are ``(key, value, value_type)``, or ``(key, value)`` when
+    ``value_type`` is given for all of them.
+    """
+    if value_type is not None:
+        rows = [(*row, value_type) for row in rows]
+    conn = sqlite3.connect(db_path)
+    conn.execute(_CREATE)
+    conn.executemany(
+        "INSERT INTO settings_setting (scope, scope_id, key, value, value_type) "
+        "VALUES ('system', '', ?, ?, ?)",
+        rows,
+    )
+    conn.commit()
+    conn.close()
+    return f"sqlite+aiosqlite:///{db_path}"
+
+
+def unmigrated_db_url(tmp_path: Path, name: str = "unmigrated.db") -> str:
+    """A database file that exists but has no tables: never migrated."""
+    db = tmp_path / name
+    sqlite3.connect(db).close()
+    return f"sqlite+aiosqlite:///{db}"
+
+
+async def connection_refused(*_args: object) -> NoReturn:
+    """Stands in for a database read that cannot reach the server."""
+    raise OSError("Connection refused")
diff --git a/framework/hosting/tests/test_boot_config_hardening.py b/framework/hosting/tests/test_boot_config_hardening.py
index 7b5cca682..2d2ce829b 100644
--- a/framework/hosting/tests/test_boot_config_hardening.py
+++ b/framework/hosting/tests/test_boot_config_hardening.py
@@ -17,6 +17,7 @@
 from unittest.mock import AsyncMock
 
 import pytest
+from _hosting_settings_db import connection_refused, seed_settings_db, unmigrated_db_url
 from pydantic_settings import BaseSettings
 from simple_module_core.setup_steps import SetupRegistry, SetupStep
 from simple_module_core.stored_settings import parse_stored_value
@@ -32,23 +33,6 @@
 from simple_module_hosting.setup_gate import STEP_MIGRATIONS
 
 
-def _settings_db(db_path: Path, rows: list[tuple[str, str]]) -> str:
-    conn = sqlite3.connect(db_path)
-    conn.execute(
-        "CREATE TABLE settings_setting (id INTEGER PRIMARY KEY, scope TEXT NOT NULL, "
-        "scope_id TEXT NOT NULL, key TEXT NOT NULL, value TEXT NOT NULL, "
-        "value_type TEXT NOT NULL, UNIQUE (scope, scope_id, key))"
-    )
-    conn.executemany(
-        "INSERT INTO settings_setting (scope, scope_id, key, value, value_type) "
-        "VALUES ('system', '', ?, ?, 'string')",
-        rows,
-    )
-    conn.commit()
-    conn.close()
-    return f"sqlite+aiosqlite:///{db_path}"
-
-
 @pytest.fixture(autouse=True)
 def _no_env_key(monkeypatch: pytest.MonkeyPatch) -> None:
     monkeypatch.delenv("SM_SECRET_KEY", raising=False)
@@ -88,12 +72,8 @@ def broken(name: str, *args, **kwargs):
 # ── 3. Ephemeral secret keys only on a confirmed fresh install ──
 
 
-async def _lookup_fails(_url: str) -> str:
-    raise OSError("Connection refused")
-
-
 def test_key_lookup_failure_refuses_boot_when_strict(monkeypatch: pytest.MonkeyPatch) -> None:
-    monkeypatch.setattr(_secret_key, "_ensure", _lookup_fails)
+    monkeypatch.setattr(_secret_key, "_ensure", connection_refused)
     with pytest.raises(SecretKeyUnavailableError):
         ensure_secret_key("sqlite+aiosqlite:///:memory:", strict=True)
 
@@ -101,16 +81,15 @@ def test_key_lookup_failure_refuses_boot_when_strict(monkeypatch: pytest.MonkeyP
 def test_key_lookup_failure_falls_back_in_development(
     monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
 ) -> None:
-    monkeypatch.setattr(_secret_key, "_ensure", _lookup_fails)
+    monkeypatch.setattr(_secret_key, "_ensure", connection_refused)
     with caplog.at_level(logging.WARNING):
         assert ensure_secret_key("sqlite+aiosqlite:///:memory:")
     assert "OSError" in caplog.text
 
 
 def test_fresh_install_may_use_an_ephemeral_key_when_strict(tmp_path: Path) -> None:
-    db = tmp_path / "fresh.db"
-    sqlite3.connect(db).close()  # no tables: never migrated
-    assert ensure_secret_key(f"sqlite+aiosqlite:///{db}", strict=True)
+    url = unmigrated_db_url(tmp_path, "fresh.db")
+    assert ensure_secret_key(url, strict=True)
 
 
 def test_no_settings_module_refuses_when_strict(monkeypatch: pytest.MonkeyPatch) -> None:
@@ -122,7 +101,7 @@ def test_no_settings_module_refuses_when_strict(monkeypatch: pytest.MonkeyPatch)
 def test_blank_stored_key_is_repaired_once(tmp_path: Path) -> None:
     """A blank row used to defeat the insert forever: an ephemeral key per boot."""
     db = tmp_path / "blank.db"
-    url = _settings_db(db, [("host.secret_key", "")])
+    url = seed_settings_db(db, [("host.secret_key", "")], value_type="string")
 
     key = ensure_secret_key(url, stored="", strict=True)
 
diff --git a/framework/hosting/tests/test_preapp_config.py b/framework/hosting/tests/test_preapp_config.py
index 6ae897416..95cbb42ae 100644
--- a/framework/hosting/tests/test_preapp_config.py
+++ b/framework/hosting/tests/test_preapp_config.py
@@ -9,10 +9,11 @@
 
 from __future__ import annotations
 
-import sqlite3
 from pathlib import Path
 
 import pytest
+from _hosting_settings_db import seed_settings_db as _seed
+from _hosting_settings_db import unmigrated_db_url
 from simple_module_hosting._preapp_config import (
     apply_host_overrides,
     load_host_overrides,
@@ -20,37 +21,10 @@
 )
 from simple_module_hosting.bootstrap_settings import BootstrapSettings
 
-_CREATE = """
-CREATE TABLE settings_setting (
-    id INTEGER PRIMARY KEY,
-    scope TEXT NOT NULL,
-    scope_id TEXT NOT NULL,
-    key TEXT NOT NULL,
-    value TEXT NOT NULL,
-    value_type TEXT NOT NULL
-)
-"""
-
-
-def _seed(db_path: Path, rows: list[tuple[str, str, str]]) -> str:
-    """Create the settings table and insert ``(key, value, value_type)`` rows."""
-    conn = sqlite3.connect(db_path)
-    conn.execute(_CREATE)
-    conn.executemany(
-        "INSERT INTO settings_setting (scope, scope_id, key, value, value_type) "
-        "VALUES ('system', '', ?, ?, ?)",
-        rows,
-    )
-    conn.commit()
-    conn.close()
-    return f"sqlite+aiosqlite:///{db_path}"
-
 
 def test_returns_empty_when_table_missing(tmp_path: Path) -> None:
     """An unmigrated DB falls back to defaults instead of raising."""
-    db = tmp_path / "unmigrated.db"
-    sqlite3.connect(db).close()  # file exists, no tables
-    assert load_host_overrides(f"sqlite+aiosqlite:///{db}") == {}
+    assert load_host_overrides(unmigrated_db_url(tmp_path)) == {}
 
 
 def test_returns_empty_when_db_unreachable() -> None:
diff --git a/framework/hosting/tests/test_preapp_invalid_values.py b/framework/hosting/tests/test_preapp_invalid_values.py
index bf421a815..c8d13cbd5 100644
--- a/framework/hosting/tests/test_preapp_invalid_values.py
+++ b/framework/hosting/tests/test_preapp_invalid_values.py
@@ -8,10 +8,10 @@
 from __future__ import annotations
 
 import logging
-import sqlite3
 from pathlib import Path
 
 import pytest
+from _hosting_settings_db import seed_settings_db as _seed
 from simple_module_hosting import _secret_key
 from simple_module_hosting._preapp_config import merge_host_settings
 from simple_module_hosting.bootstrap_settings import BootstrapSettings
@@ -19,23 +19,6 @@
 _LOGGER = "simple_module_core.stored_settings"
 
 
-def _seed(db_path: Path, rows: list[tuple[str, str, str]]) -> str:
-    conn = sqlite3.connect(db_path)
-    conn.execute(
-        "CREATE TABLE settings_setting (id INTEGER PRIMARY KEY, scope TEXT NOT NULL, "
-        "scope_id TEXT NOT NULL, key TEXT NOT NULL, value TEXT NOT NULL, "
-        "value_type TEXT NOT NULL, UNIQUE (scope, scope_id, key))"
-    )
-    conn.executemany(
-        "INSERT INTO settings_setting (scope, scope_id, key, value, value_type) "
-        "VALUES ('system', '', ?, ?, ?)",
-        rows,
-    )
-    conn.commit()
-    conn.close()
-    return f"sqlite+aiosqlite:///{db_path}"
-
-
 @pytest.fixture(autouse=True)
 def _clean_env(monkeypatch: pytest.MonkeyPatch) -> None:
     for name in ("SM_LOG_FORMAT", "SM_TENANT_HEADER", "SM_SECRET_KEY", "SM_I18N_DEFAULT_LOCALE"):
diff --git a/framework/hosting/tests/test_preapp_read_failures.py b/framework/hosting/tests/test_preapp_read_failures.py
index 6b66b6d99..db880c6b5 100644
--- a/framework/hosting/tests/test_preapp_read_failures.py
+++ b/framework/hosting/tests/test_preapp_read_failures.py
@@ -11,10 +11,11 @@
 from __future__ import annotations
 
 import logging
-import sqlite3
 from pathlib import Path
 
 import pytest
+from _hosting_settings_db import connection_refused as _refused
+from _hosting_settings_db import unmigrated_db_url as _unmigrated
 from simple_module_hosting import _preapp_config
 from simple_module_hosting._preapp_config import (
     HostSettingsUnavailableError,
@@ -27,16 +28,6 @@
 _SECRET = "a-test-secret-that-is-not-the-placeholder-0000000000"
 
 
-async def _refused(_database_url: str) -> dict[str, tuple[str, str]]:
-    raise OSError("Connection refused")
-
-
-def _unmigrated(tmp_path: Path) -> str:
-    db = tmp_path / "unmigrated.db"
-    sqlite3.connect(db).close()  # file exists, no tables
-    return f"sqlite+aiosqlite:///{db}"
-
-
 def _bootstrap(url: str, environment: str) -> BootstrapSettings:
     return BootstrapSettings(
         _env_file=None, database_url=url, environment=environment, secret_key=_SECRET
diff --git a/framework/hosting/tests/test_secret_key_bootstrap.py b/framework/hosting/tests/test_secret_key_bootstrap.py
index be2b9eb2c..4166a5e86 100644
--- a/framework/hosting/tests/test_secret_key_bootstrap.py
+++ b/framework/hosting/tests/test_secret_key_bootstrap.py
@@ -9,34 +9,17 @@
 
 from __future__ import annotations
 
-import sqlite3
 from concurrent.futures import ThreadPoolExecutor
 from pathlib import Path
 
 import pytest
+from _hosting_settings_db import seed_settings_db, unmigrated_db_url
 from simple_module_hosting._secret_key import ensure_secret_key
 
-_CREATE = """
-CREATE TABLE settings_setting (
-    id INTEGER PRIMARY KEY,
-    scope TEXT NOT NULL,
-    scope_id TEXT NOT NULL,
-    key TEXT NOT NULL,
-    value TEXT NOT NULL,
-    value_type TEXT NOT NULL,
-    UNIQUE (scope, scope_id, key)
-)
-"""
-
 
 @pytest.fixture
 def fresh_db_url(tmp_path: Path) -> str:
-    db = tmp_path / "secret.db"
-    conn = sqlite3.connect(db)
-    conn.execute(_CREATE)
-    conn.commit()
-    conn.close()
-    return f"sqlite+aiosqlite:///{db}"
+    return seed_settings_db(tmp_path / "secret.db", [])
 
 
 @pytest.fixture(autouse=True)
@@ -88,6 +71,4 @@ def test_unreachable_db_still_returns_a_key() -> None:
 
 
 def test_unmigrated_db_still_returns_a_key(tmp_path: Path) -> None:
-    db = tmp_path / "unmigrated.db"
-    sqlite3.connect(db).close()
-    assert len(ensure_secret_key(f"sqlite+aiosqlite:///{db}")) >= 40
+    assert len(ensure_secret_key(unmigrated_db_url(tmp_path))) >= 40

From b25cb29822b736b93674a127ed4bd593e1e98961 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Mon, 19 Oct 2026 14:16:00 +0200
Subject: [PATCH 13/14] =?UTF-8?q?refactor(optimize):=20over-engineering=20?=
 =?UTF-8?q?=E2=80=94=20drop=20parse=5Fstored=5Fvalue=20alias=20and=20resta?=
 =?UTF-8?q?ted=20correlation=20comment?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

SidebarLayout plain-props rewrite skipped: Biome's a11y rule rejects a static
aria-modal on <aside> without a static dialog role.

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 framework/hosting/simple_module_hosting/logging.py | 1 -
 modules/settings/settings/hydrate.py               | 4 ++--
 2 files changed, 2 insertions(+), 3 deletions(-)

diff --git a/framework/hosting/simple_module_hosting/logging.py b/framework/hosting/simple_module_hosting/logging.py
index a48b9f6c4..a6d3163df 100644
--- a/framework/hosting/simple_module_hosting/logging.py
+++ b/framework/hosting/simple_module_hosting/logging.py
@@ -7,7 +7,6 @@
 import sys
 from datetime import UTC, datetime
 
-# Defined in core so the db layer can read it without importing hosting.
 from simple_module_core.correlation import correlation_id
 
 
diff --git a/modules/settings/settings/hydrate.py b/modules/settings/settings/hydrate.py
index 9835ce420..afd39acb6 100644
--- a/modules/settings/settings/hydrate.py
+++ b/modules/settings/settings/hydrate.py
@@ -24,8 +24,8 @@
 from simple_module_core.stored_settings import (
     RELATED_FIELDS_CTX,
     construct_leniently,
+    parse_stored_value,
 )
-from simple_module_core.stored_settings import parse_stored_value as _parse
 from sqlalchemy.orm import Session
 
 from settings.store import SettingsStore, get_overrides_sync
@@ -158,7 +158,7 @@ def build_settings[T: BaseSettings](
         if field_name not in cls.model_fields or field_name in from_env:
             continue
         try:
-            parsed[field_name] = _parse(raw, vtype)
+            parsed[field_name] = parse_stored_value(raw, vtype)
         except ValueError:
             if not lenient:
                 raise

From 00d2782c80d20a481003788d653f716c6a17ec50 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Mon, 19 Oct 2026 14:46:15 +0200
Subject: [PATCH 14/14] fix: address code review findings (round 1, pass 1)

- openapi export builds settings with merge_host_settings(strict=False), so an
  unreachable database no longer fails a one-shot export.
- construct_leniently retries until no stored culprit remains (multi-pass), so
  a cross-field rule that only trips once the first bad value is dropped is
  handled too.
- #495: warn once per process (WARNING, naming SM_TRUSTED_PROXY and
  SM_SESSION_COOKIE_SECURE) when a request reaches the app over plain http for
  a non-loopback host while the session cookie is Secure; symptom documented
  in docs/reference/deployment.md.
- #506: a FULL .outerjoin(..., full=True) step now keeps its left side: the
  plain tables of the FROM built so far get (pred OR pk IS NULL) in that
  step's ON and in WHERE instead of a plain WHERE that made it a RIGHT join.
  A step without an explicit ON uses the onclause SQLAlchemy infers (also for
  LEFT steps, which no longer collapse to inner). Tested on SQLite and
  Postgres; docs/framework/multi-tenancy.md lists the shapes that still
  over-filter.
- #498: OutboxMessage sets __audit_exclude__; TaskExecution excludes
  heartbeat_at, queued_at, started_at, finished_at and retries, so updates
  touching only those write no audit row while creation and status changes
  are still audited. Docs and CHANGELOG updated.
- useDrawerA11y closes the drawer (releasing the focus trap and aria-modal)
  when the viewport crosses the lg breakpoint, and the trap skips focusables
  that are not rendered, [hidden] or [inert].

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 CHANGELOG.md                                  |   4 +-
 docs/framework/multi-tenancy.md               |  10 +-
 docs/modules/audit_log.md                     |   2 +
 docs/reference/deployment.md                  |   2 +
 .../cli/simple_module_cli/openapi_cmd.py      |   3 +-
 .../simple_module_core/stored_settings.py     |  35 ++---
 framework/db/simple_module_db/_core_joins.py  | 122 ++++++++++++++----
 framework/db/simple_module_db/core_scope.py   |   9 +-
 .../db/tests/test_db_core_full_setup_join.py  | 122 ++++++++++++++++++
 .../_insecure_transport.py                    |  66 ++++++++++
 .../simple_module_hosting/_preapp_config.py   |  12 +-
 .../hosting/simple_module_hosting/session.py  |   4 +
 .../tests/test_insecure_transport_warning.py  |  86 ++++++++++++
 .../tests/test_merge_host_settings_strict.py  |  52 ++++++++
 .../background_tasks/models.py                |  15 ++-
 .../tests/test_bg_worker_audit_bookkeeping.py |  96 ++++++++++++++
 .../src/layouts/SidebarLayout.drawer.test.tsx |  10 +-
 .../ui/src/layouts/useDrawerA11y.test.tsx     | 102 +++++++++++++++
 packages/ui/src/layouts/useDrawerA11y.ts      |  29 ++++-
 19 files changed, 725 insertions(+), 56 deletions(-)
 create mode 100644 framework/db/tests/test_db_core_full_setup_join.py
 create mode 100644 framework/hosting/simple_module_hosting/_insecure_transport.py
 create mode 100644 framework/hosting/tests/test_insecure_transport_warning.py
 create mode 100644 framework/hosting/tests/test_merge_host_settings_strict.py
 create mode 100644 modules/background_tasks/tests/test_bg_worker_audit_bookkeeping.py
 create mode 100644 packages/ui/src/layouts/useDrawerA11y.test.tsx

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1e1299f54..fa1b1ac6f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -26,7 +26,9 @@ All notable changes to this project are documented in this file. The format is b
   and `false` only for installs that serve browsers plain HTTP on purpose.
 - **Behaviour change (#498):** with `audit_log` installed, writes made in Celery
   tasks and durable outbox handlers are audited (including `TaskExecution`
-  status changes). The audit callback is bound per engine instead of a
+  creation and status changes; its heartbeat, timestamps and retry counter are
+  excluded, so a heartbeat-only update writes no audit row, and the
+  `OutboxMessage` delivery bookkeeping is not audited at all). The audit callback is bound per engine instead of a
   process-global, through the new `simple_module.audit_sinks` entry-point
   group. Worker tests that build a database without the audit table need the
   sink off (see `background_tasks/tests/conftest.py`).
diff --git a/docs/framework/multi-tenancy.md b/docs/framework/multi-tenancy.md
index 5840a5d09..814ca116d 100644
--- a/docs/framework/multi-tenancy.md
+++ b/docs/framework/multi-tenancy.md
@@ -50,8 +50,14 @@ statement names, so all of these are scoped (#332):
   predicates in `ON` and adds `WHERE (pred OR <side's primary key> IS NULL)`
   per side, which is the same result as filtering both inputs first. The
   `select(...).outerjoin(Doc.__table__, onclause)` form is scoped the same
-  way; without an explicit `onclause` the predicate falls back to `WHERE`
-  (over-filters — the outer join behaves as inner — but never leaks).
+  way. A `full=True` step there also preserves the FROM built so far: the
+  plain tables on its left side get `(pred OR <pk> IS NULL)` in that step's
+  `ON` and in `WHERE`, so rows padded on the left survive instead of the
+  join collapsing into a RIGHT join. Without an explicit `onclause` the one
+  SQLAlchemy infers from the foreign keys is used. Two shapes still
+  over-filter (never leak): an ORM entity on a FULL step's left side, whose
+  loader criteria sit in `WHERE`, and a table with no primary key, whose
+  padding cannot be told apart from a real row.
 
 With no tenant under strict mode, a statement that *names* a tenant model, or
 reads a tenant table through Core anywhere in it, raises; an indirect ORM
diff --git a/docs/modules/audit_log.md b/docs/modules/audit_log.md
index 0e93bf72c..339a36cd5 100644
--- a/docs/modules/audit_log.md
+++ b/docs/modules/audit_log.md
@@ -79,6 +79,8 @@ class Cache(Base, table=True):
     __audit_exclude__ = True
 ```
 
+An update whose changed columns are *all* excluded writes no audit row at all, so excluding a model's volatile columns is how to audit its meaningful transitions without one row per heartbeat. `background_tasks` does both: `OutboxMessage` (delivery bookkeeping) sets `__audit_exclude__ = True`, and `TaskExecution` excludes `heartbeat_at`, `queued_at`, `started_at`, `finished_at` and `retries`, so its creation and status changes are audited while the writes in between are not. This applies to request-path and Celery-worker writes alike.
+
 Primary-key columns and the bookkeeping fields injected by `AuditMixin` (`created_at`, `updated_at`, `created_by`, `updated_by`) and `SoftDeleteMixin` (`is_deleted`, `deleted_at`, `deleted_by`) are excluded from diffs automatically.
 
 ## Routes
diff --git a/docs/reference/deployment.md b/docs/reference/deployment.md
index 00f4cb4ff..c2c12b657 100644
--- a/docs/reference/deployment.md
+++ b/docs/reference/deployment.md
@@ -151,6 +151,8 @@ The flag is the `session_cookie_secure` host setting (`SM_SESSION_COOKIE_SECURE`
 | Browsers reach the app over plain HTTP on purpose (an internal network with no TLS) | `SM_SESSION_COOKIE_SECURE=false` — otherwise the browser drops the cookie and every sign-in bounces back to the login page. |
 | Local development (`make dev`, e2e) over `http://localhost` | Nothing: development and testing default to off. |
 
+**Symptom of a mismatch:** sign-in "succeeds" but every page bounces back to the login screen, and nothing fails in the request logs. The browser received a `Secure` cookie over `http://` and never sends it back. To make this visible, the app logs one `WARNING` per process (logger `simple_module_hosting.session`) the first time a request reaches it over `http` for a non-loopback host while the cookie is `Secure`. The warning names both fixes: `SM_TRUSTED_PROXY` if a TLS proxy sits in front and the app is not trusting its `X-Forwarded-Proto`, or `SM_SESSION_COOKIE_SECURE=false` if browsers really do use plain HTTP. `localhost`, `*.localhost` and loopback IPs never trigger it, because browsers keep `Secure` cookies on those.
+
 Rotate the secret by:
 
 1. Deploying with a new `SM_SECRET_KEY`.
diff --git a/framework/cli/simple_module_cli/openapi_cmd.py b/framework/cli/simple_module_cli/openapi_cmd.py
index 757b6a75b..ecadfe702 100644
--- a/framework/cli/simple_module_cli/openapi_cmd.py
+++ b/framework/cli/simple_module_cli/openapi_cmd.py
@@ -71,7 +71,8 @@ def export(
             "empty); using environment and defaults for api_title / api_version.",
             err=True,
         )
-    settings = merge_host_settings()
+    # Never serves requests: an unreachable database must not fail the export.
+    settings = merge_host_settings(strict=False)
     schema = create_app(settings).openapi()
     if module:
         schema = _filter_modules(schema, module)
diff --git a/framework/core/simple_module_core/stored_settings.py b/framework/core/simple_module_core/stored_settings.py
index f3e228a29..4f0b16839 100644
--- a/framework/core/simple_module_core/stored_settings.py
+++ b/framework/core/simple_module_core/stored_settings.py
@@ -78,22 +78,25 @@ def construct_leniently[T: BaseSettings](
     error that names no stored field re-raises.
     """
     fixed = fixed or {}
-    try:
-        return cls(**fixed, **stored)
-    except ValidationError as exc:
-        culprits = {name: err["type"] for err in exc.errors() for name in _culprits(err, stored)}
-        if not culprits:
-            raise
-        for name in sorted(culprits):
-            logger.log(
-                level,
-                "Ignoring stored value for %s.%s: it no longer validates (%s)",
-                cls.__name__,
-                name,
-                culprits[name],
-            )
-        kept = {k: v for k, v in stored.items() if k not in culprits}
-        return cls(**fixed, **kept)
+    kept = dict(stored)
+    while True:
+        try:
+            return cls(**fixed, **kept)
+        except ValidationError as exc:
+            culprits = {name: err["type"] for err in exc.errors() for name in _culprits(err, kept)}
+            if not culprits:
+                raise
+            for name in sorted(culprits):
+                logger.log(
+                    level,
+                    "Ignoring stored value for %s.%s: it no longer validates (%s)",
+                    cls.__name__,
+                    name,
+                    culprits[name],
+                )
+            # Each pass removes at least one stored field, so this ends; a second
+            # pass catches a rule that only fails once the first culprit is gone.
+            kept = {k: v for k, v in kept.items() if k not in culprits}
 
 
 def _culprits(error: ErrorDetails, stored: dict[str, Any]) -> list[str]:
diff --git a/framework/db/simple_module_db/_core_joins.py b/framework/db/simple_module_db/_core_joins.py
index 0802a84f1..bca54d94c 100644
--- a/framework/db/simple_module_db/_core_joins.py
+++ b/framework/db/simple_module_db/_core_joins.py
@@ -32,7 +32,7 @@
 from collections.abc import Callable
 from typing import Any
 
-from sqlalchemy import and_, or_
+from sqlalchemy import and_, exc, or_
 from sqlalchemy.sql.selectable import Alias, FromGrouping, Join, Select, TableClause
 
 Predicates = Callable[[Any], list[Any]]
@@ -98,16 +98,19 @@ def _join(self, node: Join) -> tuple[Any, list[Any]]:
         return Join(left, right, onclause, isouter=node.isouter, full=node.full), owed
 
 
-def _or_padded(owed: tuple[Any, list[Any]]) -> tuple[Any, list[Any]]:
+def _or_padded(owed: tuple) -> tuple:
+    """``owed`` as ``pred OR <leaf padded>``: tagged with a third item so it is padded once."""
+    if len(owed) == 3:
+        return owed
     leaf, preds = owed
     padded = _padded(leaf)
     # No primary key to tell padding apart: keep the plain predicates, which
     # over-filter (drop the padded rows) but never leak.
-    return (leaf, preds) if padded is None else (leaf, [or_(and_(*preds), padded)])
+    return (leaf, preds) if padded is None else (leaf, [or_(and_(*preds), padded)], True)
 
 
-def _flatten(owed: list[tuple[Any, list[Any]]]) -> list[Any]:
-    return [p for _leaf, preds in owed for p in preds]
+def _flatten(owed: list[tuple]) -> list[Any]:
+    return [p for _leaf, preds, *_ in owed for p in preds]
 
 
 class JoinScope:
@@ -128,36 +131,109 @@ def scope_joins(stmt: Select, predicates_for: Predicates) -> JoinScope:
     caller: on a nullable side it would make the outer join inner.
     ``predicates_for`` raises under strict mode with no tenant bound, so a
     Core join fails closed like everything else.
+
+    Once any ``.join()`` step is FULL, every ``WHERE`` predicate owed here
+    takes the padded form ``pred OR <pk> IS NULL``. That is never a leak —
+    a primary key is NULL only on a row an outer join padded, which carries
+    nothing of that table — and it is what keeps the FULL join's left side
+    from being filtered down to a RIGHT join.
     """
     scoper = _Scoper(predicates_for)
-    where: list[Any] = []
+    owed: list[tuple] = []
     froms: list[Any] = []
     for from_obj in stmt._from_obj:
         if isinstance(from_obj, Join):
-            from_obj, owed = scoper.scope(from_obj)
-            where.extend(_flatten(owed))
+            from_obj, more = scoper.scope(from_obj)
+            owed.extend(more)
         froms.append(from_obj)
-    joins = [_scope_setup_join(entry, scoper, where) for entry in stmt._setup_joins]
-    return JoinScope(tuple(froms), tuple(joins), where, scoper.covered)
+    joins = [_scope_setup_join(stmt, i, scoper, owed) for i in range(len(stmt._setup_joins))]
+    if any(entry[3].get("full") for entry in stmt._setup_joins):
+        owed = [_or_padded(o) for o in owed]
+    return JoinScope(tuple(froms), tuple(joins), _flatten(owed), scoper.covered)
 
 
-def _scope_setup_join(entry: tuple, scoper: _Scoper, where: list[Any]) -> tuple:
+def _scope_setup_join(stmt: Select, index: int, scoper: _Scoper, owed: list[tuple]) -> tuple:
     """One ``select(...).join(target, onclause)`` step over a Core target.
 
-    The left side is the FROM built so far, already filtered by its own
-    predicates; only the target is scoped here. Without an explicit
-    ``onclause`` there is no ``ON`` to extend, so an outer target's
-    predicates fall back to ``WHERE`` (over-filters, never leaks).
+    The target is scoped like a ``Join``'s right side. A FULL step also
+    preserves its left side — the FROM built so far — so that side's plain
+    leaves get their (padded) predicates in this ``ON`` and owe the padded
+    form to ``WHERE``. Without an explicit ``onclause`` the one SQLAlchemy
+    infers is used; if it cannot be resolved, predicates fall back to plain
+    ``WHERE`` (over-filters, never leaks).
     """
+    entry = stmt._setup_joins[index]
     target, onclause, from_, flags = entry
-    target, owed = scoper.scope(target)
-    outer = bool(flags.get("isouter")) or bool(flags.get("full"))
-    if not owed:
+    full = bool(flags.get("full"))
+    outer = full or bool(flags.get("isouter"))
+    target, target_owed = scoper.scope(target)
+    resolved = None
+    if full or (outer and onclause is None and target_owed):
+        resolved = _resolved_join(stmt, index)
+    left_owed = _left_owed(resolved.left, scoper, owed) if full and resolved is not None else []
+    if not target_owed and not left_owed:
         return (target, onclause, from_, flags)
+    if onclause is None and resolved is not None:
+        onclause = resolved.onclause
     if not outer or onclause is None:
-        where.extend(_flatten(owed))
+        owed.extend(target_owed)
         return (target, onclause, from_, flags)
-    onclause = and_(onclause, *_flatten(owed))
-    if flags.get("full"):
-        where.extend(_flatten([_or_padded(o) for o in owed]))
-    return (target, onclause, from_, flags)
+    on = [*target_owed, *(_or_padded(o) for o in left_owed)]
+    if full:
+        owed.extend(target_owed)
+    return (target, and_(onclause, *_flatten(on)), from_, flags)
+
+
+def _resolved_join(stmt: Select, index: int) -> Join | None:
+    """The ``Join`` SQLAlchemy builds for setup join ``index``: its left side and ``ON``."""
+    target = stmt._setup_joins[index][0]
+    probe = stmt._generate()
+    probe._setup_joins = stmt._setup_joins[: index + 1]
+    try:
+        froms = probe.get_final_froms()
+    except exc.SQLAlchemyError:
+        return None
+    stack = list(froms)
+    while stack:
+        node = stack.pop()
+        if isinstance(node, FromGrouping):
+            stack.append(node.element)
+        elif isinstance(node, Join):
+            if node.right is target or getattr(node.right, "element", None) is target:
+                return node
+            stack.extend((node.left, node.right))
+    return None
+
+
+def _left_owed(left: Any, scoper: _Scoper, owed: list[tuple]) -> list[tuple]:
+    """What the plain leaves preserved on a FULL step's left side owe.
+
+    A leaf already filtered in an earlier outer join's ``ON`` owes nothing;
+    one already owing ``WHERE`` predicates is reported as is; one nobody has
+    scoped yet (a columns-clause FROM) is scoped here and joins ``owed``.
+    """
+    found: list[tuple] = []
+    stack = [left]
+    while stack:
+        node = stack.pop()
+        if isinstance(node, FromGrouping):
+            stack.append(node.element)
+        elif isinstance(node, Join):
+            stack.extend((node.left, node.right))
+        elif is_plain_leaf(node):
+            mine = [o for o in owed if same_from(o[0], node)]
+            if mine:
+                found.extend(mine)
+            elif not any(same_from(node, c) for c in scoper.covered):
+                preds = scoper.predicates_for(node)
+                if preds:
+                    scoper.covered.append(node)
+                    owed.append((node, preds))
+                    found.append((node, preds))
+    return found
+
+
+def same_from(a: Any, b: Any) -> bool:
+    """One FROM occurrence: the same object, or clones of one (an alias the traversal
+    copied while a column still points at the original — SQL renders them as one)."""
+    return a is b or not a._cloned_set.isdisjoint(b._cloned_set)
diff --git a/framework/db/simple_module_db/core_scope.py b/framework/db/simple_module_db/core_scope.py
index 795a90557..a927df09e 100644
--- a/framework/db/simple_module_db/core_scope.py
+++ b/framework/db/simple_module_db/core_scope.py
@@ -34,6 +34,7 @@
     _base_name,
     _is_orm,
     is_plain_leaf,
+    same_from,
     scope_joins,
 )
 from simple_module_db._outer_joins import is_excluded, orm_outer_join_tables
@@ -98,12 +99,6 @@ def _executable_options(stmt: Any) -> list[Any]:
     return [o for el in visitors.iterate(stmt) for o in getattr(el, "_with_options", ())]
 
 
-def _same_from(a: Any, b: Any) -> bool:
-    """One FROM occurrence: the same object, or clones of one (an alias the traversal
-    copied while a column still points at the original — SQL renders them as one)."""
-    return a is b or not a._cloned_set.isdisjoint(b._cloned_set)
-
-
 def _where_froms(stmt: Any) -> list[Any]:
     return [f for crit in stmt._where_criteria for f in crit._from_objects]
 
@@ -122,7 +117,7 @@ def _preds(self, candidates: list[Any], skip: list[Any]) -> list[Any]:
         preds: list[Any] = []
         seen: list[Any] = list(skip)
         for from_obj in candidates:
-            if not is_plain_leaf(from_obj) or any(_same_from(from_obj, s) for s in seen):
+            if not is_plain_leaf(from_obj) or any(same_from(from_obj, s) for s in seen):
                 continue
             seen.append(from_obj)
             preds.extend(self.predicates_for(from_obj))
diff --git a/framework/db/tests/test_db_core_full_setup_join.py b/framework/db/tests/test_db_core_full_setup_join.py
new file mode 100644
index 000000000..3b9c77051
--- /dev/null
+++ b/framework/db/tests/test_db_core_full_setup_join.py
@@ -0,0 +1,122 @@
+"""FULL ``.outerjoin(..., full=True)`` steps keep both sides (#506 review).
+
+A FULL join preserves its left side too, so that side's tenant predicate
+cannot sit in a plain ``WHERE``: it would drop the rows the join pads on
+the left and turn the FULL join into a RIGHT one. The expected rows are
+what filtering both inputs to tenant A first would give; tenant B's rows
+must never appear, matched or not.
+
+Tenant A: parents ``a1`` (1), ``a2`` (2); children 1 → ``a1`` and 2 →
+nothing. Tenant B: parent ``b`` (3) and child 3 → ``a1`` (the leak probe),
+child 4 → ``b``. Child 5 (tenant A) → ``b``: matched only across tenants,
+so it must come back unmatched.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator
+
+import pytest
+from _models import _tenant_session
+from simple_module_db.base import create_module_base
+from simple_module_db.mixins import MultiTenantMixin
+from simple_module_db.query_filter import EngineTenancy, bind_engine_policy
+from simple_module_db.tenancy import TenantIsolationError, current_tenant_id, tenant_context
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlmodel import Field
+
+_Base = create_module_base("cfull")
+
+
+class Parent(_Base, MultiTenantMixin, table=True):  # type: ignore[call-arg]  # ty: ignore[unsupported-base]
+    __tablename__ = "cfull_parent"
+    id: int | None = Field(default=None, primary_key=True)
+    name: str = Field(default="", max_length=50)
+
+
+class Child(_Base, MultiTenantMixin, table=True):  # type: ignore[call-arg]  # ty: ignore[unsupported-base]
+    __tablename__ = "cfull_child"
+    id: int | None = Field(default=None, primary_key=True)
+    parent_id: int | None = Field(default=None, foreign_key="cfull_parent.id")
+
+
+parent, child = Parent.__table__, Child.__table__
+_ON = child.c.parent_id == parent.c.id
+_FULL = [("a1", 1), ("a2", None), (None, 2), (None, 5)]
+
+
+async def _seed(session: AsyncSession) -> None:
+    with tenant_context("A"):
+        session.add_all([Parent(id=1, name="a1"), Parent(id=2, name="a2")])
+        await session.flush()
+    with tenant_context("B"):
+        session.add(Parent(id=3, name="b"))
+        await session.flush()
+        session.add_all([Child(id=3, parent_id=1), Child(id=4, parent_id=3)])
+        await session.flush()
+    with tenant_context("A"):
+        session.add_all([Child(id=1, parent_id=1), Child(id=2), Child(id=5, parent_id=3)])
+        await session.flush()
+    await session.commit()
+
+
+@pytest.fixture
+async def as_a() -> AsyncGenerator[AsyncSession, None]:
+    async for session in _tenant_session(_Base.metadata, strict=False, seed=_seed):
+        token = current_tenant_id.set("A")
+        try:
+            yield session
+        finally:
+            current_tenant_id.reset(token)
+
+
+async def _rows(session: AsyncSession, stmt) -> list[tuple]:
+    return sorted((tuple(r) for r in (await session.execute(stmt)).all()), key=repr)
+
+
+_COLS = (parent.c.name, child.c.id)
+
+
+async def test_full_step_from_columns_clause_keeps_left_padding(as_a):
+    stmt = select(*_COLS).outerjoin(child, _ON, full=True)
+    assert await _rows(as_a, stmt) == sorted(_FULL, key=repr)
+
+
+async def test_full_step_after_select_from(as_a):
+    stmt = select(*_COLS).select_from(parent).outerjoin(child, _ON, full=True)
+    assert await _rows(as_a, stmt) == sorted(_FULL, key=repr)
+
+
+async def test_full_step_without_onclause_uses_inferred_on(as_a):
+    stmt = select(*_COLS).select_from(parent).outerjoin(child, full=True)
+    assert await _rows(as_a, stmt) == sorted(_FULL, key=repr)
+
+
+async def test_full_step_after_inner_step(as_a):
+    other = parent.alias("p2")
+    stmt = (
+        select(*_COLS)
+        .select_from(parent)
+        .join(other, other.c.id == parent.c.id)
+        .outerjoin(child, _ON, full=True)
+    )
+    assert await _rows(as_a, stmt) == sorted(_FULL, key=repr)
+
+
+async def test_left_step_without_onclause_stays_outer(as_a):
+    stmt = select(*_COLS).select_from(parent).outerjoin(child)
+    assert await _rows(as_a, stmt) == [("a1", 1), ("a2", None)]
+
+
+async def test_all_tenants_sees_every_row(as_a):
+    stmt = select(*_COLS).outerjoin(child, _ON, full=True).execution_options(all_tenants=True)
+    rows = await _rows(as_a, stmt)
+    assert ("a1", 3) in rows and ("b", 4) in rows and ("b", 5) in rows
+
+
+async def test_strict_without_tenant_refuses(as_a):
+    bind_engine_policy(as_a.bind.sync_engine, EngineTenancy(tenant_strict=True))
+    current_tenant_id.set(None)
+    with pytest.raises(TenantIsolationError):
+        await as_a.execute(select(*_COLS).outerjoin(child, _ON, full=True))
diff --git a/framework/hosting/simple_module_hosting/_insecure_transport.py b/framework/hosting/simple_module_hosting/_insecure_transport.py
new file mode 100644
index 000000000..361fc3ff3
--- /dev/null
+++ b/framework/hosting/simple_module_hosting/_insecure_transport.py
@@ -0,0 +1,66 @@
+"""Warn once when a ``Secure`` session cookie is served over plain HTTP (#495).
+
+Outside development the session cookie is ``Secure``. A browser that reaches
+the app over ``http://`` on a real hostname never sends it back, so sign-in
+bounces to the login page with nothing in the logs. This names the two
+settings that fix it, once per process.
+
+Loopback hosts are exempt: browsers treat ``http://localhost`` as a secure
+context and keep ``Secure`` cookies there. The check runs after
+``ProxyHeaders``, so an install with ``SM_TRUSTED_PROXY`` set sees the
+forwarded ``https`` scheme and never warns.
+"""
+
+from __future__ import annotations
+
+import logging
+from ipaddress import ip_address
+
+from starlette.types import Scope
+
+logger = logging.getLogger("simple_module_hosting.session")
+
+_warned = False
+
+
+def warn_if_plain_http(scope: Scope) -> None:
+    """Log one WARNING per process for an ``http`` request to a non-loopback host."""
+    global _warned
+    if _warned or scope.get("scheme") != "http":
+        return
+    host = _host(scope)
+    if host is None or _is_loopback(host):
+        return
+    _warned = True
+    logger.warning(
+        "Request for %r arrived over plain HTTP, but the session cookie is Secure: "
+        "browsers will not send it back and sign-in will fail. Behind a TLS-terminating "
+        "proxy set SM_TRUSTED_PROXY so the forwarded https scheme is trusted; to serve "
+        "browsers over plain HTTP on purpose set SM_SESSION_COOKIE_SECURE=false.",
+        host,
+    )
+
+
+def _host(scope: Scope) -> str | None:
+    for key, value in scope.get("headers") or ():
+        if key == b"host":
+            raw = value.decode("latin-1").strip().lower()
+            if raw.startswith("["):  # [::1]:8000
+                return raw[1 : raw.find("]")] if "]" in raw else None
+            return raw.rsplit(":", 1)[0] if raw.count(":") == 1 else raw
+    server = scope.get("server")
+    return str(server[0]).lower() if server else None
+
+
+def _is_loopback(host: str) -> bool:
+    if host == "localhost" or host.endswith(".localhost"):
+        return True
+    try:
+        return ip_address(host).is_loopback
+    except ValueError:
+        return False
+
+
+def _reset_for_tests() -> None:
+    global _warned
+    _warned = False
diff --git a/framework/hosting/simple_module_hosting/_preapp_config.py b/framework/hosting/simple_module_hosting/_preapp_config.py
index 997289d10..7eb5dfc80 100644
--- a/framework/hosting/simple_module_hosting/_preapp_config.py
+++ b/framework/hosting/simple_module_hosting/_preapp_config.py
@@ -225,16 +225,24 @@ def apply_host_overrides(
     return values
 
 
-def merge_host_settings(bootstrap: BootstrapSettings | None = None) -> Settings:
+def merge_host_settings(
+    bootstrap: BootstrapSettings | None = None, *, strict: bool | None = None
+) -> Settings:
     """Build the ``Settings`` create_app runs on, with DB overrides applied.
 
     ``bootstrap`` is read from env first because it carries ``database_url``,
     which is the one value that cannot come from the database.
+
+    ``strict`` (default: on outside development and testing) refuses to build
+    on defaults / an ephemeral key when the stored settings cannot be read.
+    One-shot tooling that never serves requests (``smpy openapi export``)
+    passes ``strict=False``.
     """
     from simple_module_hosting._secret_key import SECRET_KEY_FIELD, ensure_secret_key
 
     bootstrap = bootstrap or BootstrapSettings()
-    strict = bootstrap.environment not in NON_PROD_ENVIRONMENTS
+    if strict is None:
+        strict = bootstrap.environment not in NON_PROD_ENVIRONMENTS
     overrides = load_host_overrides(bootstrap.database_url, strict=strict)
     stored = apply_host_overrides(overrides)
     # Resolved here rather than left to the field default so an install with
diff --git a/framework/hosting/simple_module_hosting/session.py b/framework/hosting/simple_module_hosting/session.py
index 00e91f32e..afddc1e63 100644
--- a/framework/hosting/simple_module_hosting/session.py
+++ b/framework/hosting/simple_module_hosting/session.py
@@ -32,6 +32,7 @@
 from starlette.middleware.sessions import SessionMiddleware as _StarletteSessionMiddleware
 from starlette.types import ASGIApp, Message, Receive, Scope, Send
 
+from simple_module_hosting._insecure_transport import warn_if_plain_http
 from simple_module_hosting._tenant import merge_vary
 
 SESSION_SIGNATURE_MAX_AGE = 30 * 24 * 60 * 60
@@ -102,11 +103,14 @@ def __init__(self, app: ASGIApp, secret_key: Any, **kwargs: Any) -> None:
                 "with SESSION_REMEMBER_KEY, or per response with SESSION_COOKIE_MAX_AGE_KEY."
             )
         super().__init__(app, secret_key, max_age=SESSION_SIGNATURE_MAX_AGE, **kwargs)
+        self._secure = bool(kwargs.get("https_only"))
 
     async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
         if scope["type"] not in ("http", "websocket"):
             await self.app(scope, receive, send)
             return
+        if self._secure:
+            warn_if_plain_http(scope)
 
         async def send_with_cookie_window(message: Message) -> None:
             if message["type"] == "http.response.start":
diff --git a/framework/hosting/tests/test_insecure_transport_warning.py b/framework/hosting/tests/test_insecure_transport_warning.py
new file mode 100644
index 000000000..0013e2fee
--- /dev/null
+++ b/framework/hosting/tests/test_insecure_transport_warning.py
@@ -0,0 +1,86 @@
+"""A ``Secure`` session cookie served over plain HTTP warns once (#495)."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Iterator
+
+import httpx
+import pytest
+from simple_module_hosting import _insecure_transport
+from simple_module_hosting._insecure_transport import warn_if_plain_http
+from simple_module_hosting.session import SessionMiddleware
+from starlette.applications import Starlette
+from starlette.requests import Request
+from starlette.responses import PlainTextResponse
+from starlette.routing import Route
+
+_LOGGER = "simple_module_hosting.session"
+
+
+@pytest.fixture(autouse=True)
+def _fresh_flag() -> Iterator[None]:
+    _insecure_transport._reset_for_tests()
+    yield
+    _insecure_transport._reset_for_tests()
+
+
+def _scope(scheme: str, host: str) -> dict:
+    return {"type": "http", "scheme": scheme, "headers": [(b"host", host.encode())]}
+
+
+def _warnings(caplog: pytest.LogCaptureFixture) -> list[logging.LogRecord]:
+    return [r for r in caplog.records if r.name == _LOGGER and r.levelno == logging.WARNING]
+
+
+def test_plain_http_to_real_host_warns_once_naming_both_settings(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    with caplog.at_level(logging.WARNING, logger=_LOGGER):
+        warn_if_plain_http(_scope("http", "app.example.com:8000"))
+        warn_if_plain_http(_scope("http", "other.example.com"))
+    records = _warnings(caplog)
+    assert len(records) == 1
+    message = records[0].getMessage()
+    assert "SM_TRUSTED_PROXY" in message
+    assert "SM_SESSION_COOKIE_SECURE" in message
+
+
+@pytest.mark.parametrize(
+    ("scheme", "host"),
+    [
+        ("https", "app.example.com"),
+        ("http", "localhost:8000"),
+        ("http", "app.localhost"),
+        ("http", "127.0.0.1:8000"),
+        ("http", "[::1]:8000"),
+    ],
+)
+def test_https_or_loopback_does_not_warn(
+    caplog: pytest.LogCaptureFixture, scheme: str, host: str
+) -> None:
+    with caplog.at_level(logging.WARNING, logger=_LOGGER):
+        warn_if_plain_http(_scope(scheme, host))
+    assert not _warnings(caplog)
+    assert _insecure_transport._warned is False
+
+
+def _app(*, https_only: bool) -> Starlette:
+    async def home(request: Request) -> PlainTextResponse:
+        return PlainTextResponse("ok")
+
+    app = Starlette(routes=[Route("/", home)])
+    app.add_middleware(SessionMiddleware, secret_key="k", https_only=https_only)
+    return app
+
+
+@pytest.mark.parametrize(("https_only", "expected"), [(True, 1), (False, 0)])
+async def test_session_middleware_warns_only_when_cookie_is_secure(
+    caplog: pytest.LogCaptureFixture, https_only: bool, expected: int
+) -> None:
+    transport = httpx.ASGITransport(app=_app(https_only=https_only))
+    with caplog.at_level(logging.WARNING, logger=_LOGGER):
+        async with httpx.AsyncClient(transport=transport, base_url="http://app.example.com") as c:
+            assert (await c.get("/")).status_code == 200
+            assert (await c.get("/")).status_code == 200
+    assert len(_warnings(caplog)) == expected
diff --git a/framework/hosting/tests/test_merge_host_settings_strict.py b/framework/hosting/tests/test_merge_host_settings_strict.py
new file mode 100644
index 000000000..3f5a43320
--- /dev/null
+++ b/framework/hosting/tests/test_merge_host_settings_strict.py
@@ -0,0 +1,52 @@
+"""``merge_host_settings(strict=False)`` and multi-pass lenient construction."""
+
+from __future__ import annotations
+
+import pytest
+from pydantic import model_validator
+from pydantic_core import PydanticCustomError
+from pydantic_settings import BaseSettings
+from simple_module_core.stored_settings import RELATED_FIELDS_CTX, construct_leniently
+from simple_module_hosting._preapp_config import HostSettingsUnavailableError, merge_host_settings
+from simple_module_hosting.bootstrap_settings import BootstrapSettings
+
+
+@pytest.fixture(autouse=True)
+def _no_env_key(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("SM_SECRET_KEY", raising=False)
+
+
+def test_strict_false_builds_on_defaults_in_production_when_db_is_unreachable() -> None:
+    bootstrap = BootstrapSettings(
+        environment="production", database_url="postgresql+asyncpg://u:p@127.0.0.1:1/none"
+    )
+    with pytest.raises(HostSettingsUnavailableError):
+        merge_host_settings(bootstrap)
+    settings = merge_host_settings(bootstrap, strict=False)
+    assert settings.secret_key
+
+
+def test_openapi_export_does_not_ask_for_strict_boot() -> None:
+    import inspect
+
+    from simple_module_cli import openapi_cmd
+
+    assert "strict=False" in inspect.getsource(openapi_cmd.export)
+
+
+class _Pair(BaseSettings):
+    a: int = 1
+    b: int = 1
+
+    @model_validator(mode="after")
+    def _check(self) -> _Pair:
+        if self.b > self.a:
+            raise PydanticCustomError("pair", "b must not exceed a", {RELATED_FIELDS_CTX: ["b"]})
+        return self
+
+
+def test_lenient_construction_retries_until_valid() -> None:
+    # ``a`` is invalid (type), and once it is dropped (a=1) the stored b=5
+    # trips the cross-field rule too; the second pass drops it as well.
+    built = construct_leniently(_Pair, {"a": "x", "b": 5})
+    assert (built.a, built.b) == (1, 1)
diff --git a/modules/background_tasks/background_tasks/models.py b/modules/background_tasks/background_tasks/models.py
index 31caa3690..d5d0b80a6 100644
--- a/modules/background_tasks/background_tasks/models.py
+++ b/modules/background_tasks/background_tasks/models.py
@@ -4,7 +4,7 @@
 
 import uuid
 from datetime import datetime
-from typing import Any
+from typing import Any, ClassVar
 
 from simple_module_db.base import create_module_base
 from simple_module_db.mixins import AuditMixin
@@ -36,6 +36,16 @@ class TaskExecution(Base, AuditMixin, table=True):  # ty: ignore[unsupported-bas
     """
 
     __tablename__ = TABLE_TASK_EXECUTION
+    # Audited for creation and status changes (#498), but not for the fields
+    # every signal and heartbeat rewrites: an update touching only these
+    # produces no audit row, which keeps a worker from doubling its writes.
+    __audit_exclude_fields__: ClassVar[set[str]] = {
+        "heartbeat_at",
+        "started_at",
+        "finished_at",
+        "queued_at",
+        "retries",
+    }
 
     id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
 
@@ -121,6 +131,9 @@ class OutboxMessage(Base, table=True):  # ty: ignore[unsupported-base]
     """
 
     __tablename__ = TABLE_OUTBOX
+    # Pure delivery bookkeeping: every claim, retry and delivery rewrites the
+    # row, and the event it carries is audited where it was published (#498).
+    __audit_exclude__ = True
 
     id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
     event_key: str = Field(max_length=OUTBOX_KEY_MAX_LENGTH)
diff --git a/modules/background_tasks/tests/test_bg_worker_audit_bookkeeping.py b/modules/background_tasks/tests/test_bg_worker_audit_bookkeeping.py
new file mode 100644
index 000000000..63b80437e
--- /dev/null
+++ b/modules/background_tasks/tests/test_bg_worker_audit_bookkeeping.py
@@ -0,0 +1,96 @@
+"""Worker bookkeeping is not audited row-for-row (#498 write amplification).
+
+``OutboxMessage`` is delivery plumbing and opts out entirely.
+``TaskExecution`` keeps its creation and status changes in the audit log,
+but an update that touches only its volatile fields (heartbeat, timestamps,
+retry counter) writes no audit row.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+import pytest
+from background_tasks import sync_db
+from background_tasks._signal_support import now_utc
+from background_tasks.constants import TaskStatus
+from background_tasks.models import Base, OutboxMessage, TaskExecution
+from simple_module_db.audit_sinks import discover_audit_callback
+from sqlalchemy import create_engine, select
+
+audit_models = pytest.importorskip("audit_log.models")
+AuditEntry = audit_models.AuditEntry
+
+
+@pytest.fixture
+def worker_db(tmp_path, monkeypatch: pytest.MonkeyPatch) -> Iterator[None]:
+    monkeypatch.setattr(sync_db, "discover_audit_callback", discover_audit_callback)
+    url = f"sqlite:///{tmp_path}/worker_bookkeeping.db"
+    engine = create_engine(url)
+    Base.metadata.create_all(engine)
+    AuditEntry.metadata.create_all(engine)
+    engine.dispose()
+    sync_db.set_database_url(url)
+    yield
+    sync_db.dispose_sync_engine()
+
+
+def _audit() -> list[tuple[str, str, list]]:
+    with sync_db.sync_session() as s:
+        rows = s.execute(select(AuditEntry.entity_type, AuditEntry.action, AuditEntry.changes))
+        # Ids are random UUIDs: order by action, which is all these tests need.
+        return sorted((tuple(r) for r in rows), key=lambda r: r[1])
+
+
+def _create_execution() -> object:
+    with sync_db.sync_session() as s:
+        row = TaskExecution(task_name="t", celery_task_id="c1", queued_at=now_utc())
+        s.add(row)
+    return row.id
+
+
+def test_execution_creation_is_audited_without_volatile_fields(worker_db) -> None:
+    _create_execution()
+    [(entity, action, changes)] = _audit()
+    assert (entity, action) == ("TaskExecution", "created")
+    fields = {c["field"] for c in changes}
+    assert "status" in fields
+    assert not fields & {"heartbeat_at", "started_at", "finished_at", "queued_at", "retries"}
+
+
+def test_volatile_only_updates_write_no_audit_row(worker_db) -> None:
+    pk = _create_execution()
+    with sync_db.sync_session() as s:
+        row = s.get(TaskExecution, pk)
+        row.heartbeat_at = now_utc()
+        row.started_at = now_utc()
+        row.retries = 2
+    assert [a for _, a, _ in _audit()] == ["created"]
+
+
+def test_terminal_status_is_audited(worker_db) -> None:
+    pk = _create_execution()
+    with sync_db.sync_session() as s:
+        row = s.get(TaskExecution, pk)
+        row.status = TaskStatus.SUCCESS
+        row.finished_at = now_utc()
+        row.heartbeat_at = now_utc()
+    entity, action, changes = _audit()[-1]
+    assert (entity, action) == ("TaskExecution", "updated")
+    assert [c["field"] for c in changes] == ["status"]
+    assert changes[0]["new"] == TaskStatus.SUCCESS.value
+
+
+def test_outbox_messages_are_never_audited(worker_db) -> None:
+    with sync_db.sync_session() as s:
+        msg = OutboxMessage(
+            event_key="e", handler_name="h", next_attempt_at=now_utc(), created_at=now_utc()
+        )
+        s.add(msg)
+    with sync_db.sync_session() as s:
+        row = s.get(OutboxMessage, msg.id)
+        row.attempts = 1
+        row.last_error = "boom"
+    with sync_db.sync_session() as s:
+        s.delete(s.get(OutboxMessage, msg.id))
+    assert _audit() == []
diff --git a/packages/ui/src/layouts/SidebarLayout.drawer.test.tsx b/packages/ui/src/layouts/SidebarLayout.drawer.test.tsx
index e9af628ec..11473d2b9 100644
--- a/packages/ui/src/layouts/SidebarLayout.drawer.test.tsx
+++ b/packages/ui/src/layouts/SidebarLayout.drawer.test.tsx
@@ -1,5 +1,5 @@
 import { fireEvent, render, screen } from '@testing-library/react';
-import { describe, expect, it, vi } from 'vitest';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 vi.mock('@inertiajs/react', () => ({
   usePage: () => ({
@@ -72,6 +72,14 @@ function setup() {
 }
 
 describe('SidebarLayout mobile drawer', () => {
+  // jsdom lays nothing out, so every element would read as invisible to the
+  // trap's visibility filter.
+  beforeEach(() => {
+    vi.spyOn(HTMLElement.prototype, 'getClientRects').mockReturnValue([
+      {},
+    ] as unknown as DOMRectList);
+  });
+
   it('is a plain sidebar (no dialog role) until opened', () => {
     render(
       <AdminLayout>
diff --git a/packages/ui/src/layouts/useDrawerA11y.test.tsx b/packages/ui/src/layouts/useDrawerA11y.test.tsx
new file mode 100644
index 000000000..4bbffa4a7
--- /dev/null
+++ b/packages/ui/src/layouts/useDrawerA11y.test.tsx
@@ -0,0 +1,102 @@
+import { act, fireEvent, render, screen } from '@testing-library/react';
+import { useCallback, useRef, useState } from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { DESKTOP_SIDEBAR_QUERY, useDrawerA11y } from './useDrawerA11y';
+
+type Listener = (e: MediaQueryListEvent) => void;
+
+/** A controllable `matchMedia` for the desktop query: jsdom ships none. */
+function installMatchMedia() {
+  const listeners = new Set<Listener>();
+  const mql = {
+    matches: false,
+    media: DESKTOP_SIDEBAR_QUERY,
+    addEventListener: (_: string, fn: Listener) => listeners.add(fn),
+    removeEventListener: (_: string, fn: Listener) => listeners.delete(fn),
+  };
+  window.matchMedia = vi.fn(() => mql as unknown as MediaQueryList);
+  return {
+    listeners,
+    toDesktop() {
+      mql.matches = true;
+      for (const fn of [...listeners]) fn({ matches: true } as MediaQueryListEvent);
+    },
+  };
+}
+
+function Drawer({ children }: { children?: React.ReactNode }) {
+  const [open, setOpen] = useState(true);
+  const close = useCallback(() => setOpen(false), []);
+  const ref = useRef<HTMLElement>(null);
+  useDrawerA11y(open, close, ref);
+  return (
+    <aside ref={ref} data-testid="drawer" data-open={open}>
+      {children ?? (
+        <>
+          <button type="button">first</button>
+          <button type="button">last</button>
+        </>
+      )}
+    </aside>
+  );
+}
+
+describe('useDrawerA11y', () => {
+  const realMatchMedia = window.matchMedia;
+
+  beforeEach(() => {
+    // jsdom lays nothing out; an element styled `display: none` stands in for
+    // one hidden by CSS (a `lg:hidden` control).
+    vi.spyOn(HTMLElement.prototype, 'getClientRects').mockImplementation(function (
+      this: HTMLElement,
+    ) {
+      return (this.style.display === 'none' ? [] : [{}]) as unknown as DOMRectList;
+    });
+  });
+
+  afterEach(() => {
+    window.matchMedia = realMatchMedia;
+    vi.restoreAllMocks();
+  });
+
+  it('closes, releasing the trap, when the viewport crosses to desktop', () => {
+    const media = installMatchMedia();
+    render(<Drawer />);
+    const drawer = screen.getByTestId('drawer');
+    expect(drawer.dataset.open).toBe('true');
+    expect(media.listeners.size).toBe(1);
+
+    act(() => media.toDesktop());
+
+    expect(drawer.dataset.open).toBe('false');
+    expect(media.listeners.size).toBe(0);
+    const last = screen.getByRole('button', { name: 'last' });
+    last.focus();
+    fireEvent.keyDown(last, { key: 'Tab' });
+    expect(document.activeElement).toBe(last);
+  });
+
+  it('skips focusable elements that are not rendered', () => {
+    installMatchMedia();
+    render(
+      <Drawer>
+        <button type="button" style={{ display: 'none' }}>
+          css-hidden
+        </button>
+        <button type="button">visible</button>
+        <div hidden>
+          <button type="button">attr-hidden</button>
+        </div>
+        <div inert>
+          <button type="button">inert</button>
+        </div>
+      </Drawer>,
+    );
+    const visible = screen.getByRole('button', { name: 'visible' });
+    expect(document.activeElement).toBe(visible);
+    fireEvent.keyDown(visible, { key: 'Tab' });
+    expect(document.activeElement).toBe(visible);
+    fireEvent.keyDown(visible, { key: 'Tab', shiftKey: true });
+    expect(document.activeElement).toBe(visible);
+  });
+});
diff --git a/packages/ui/src/layouts/useDrawerA11y.ts b/packages/ui/src/layouts/useDrawerA11y.ts
index 83c0d8b84..1fdd068b4 100644
--- a/packages/ui/src/layouts/useDrawerA11y.ts
+++ b/packages/ui/src/layouts/useDrawerA11y.ts
@@ -3,13 +3,26 @@ import { type RefObject, useEffect } from 'react';
 const FOCUSABLE =
   'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
 
+/**
+ * Tailwind's `lg` breakpoint, where SidebarLayout docks the sidebar
+ * (`lg:translate-x-0`) and the drawer stops being a modal.
+ */
+export const DESKTOP_SIDEBAR_QUERY = '(min-width: 64rem)';
+
+/** Rendered and reachable: `lg:hidden` items and `[hidden]`/`[inert]` subtrees are not. */
+function isFocusable(el: HTMLElement): boolean {
+  return !el.closest('[hidden], [inert]') && el.getClientRects().length > 0;
+}
+
 /**
  * Modal-dialog behaviour for the mobile sidebar drawer (WAI-ARIA dialog
  * pattern): Escape closes it, focus moves in on open and is trapped while it is
  * open, and focus returns to whatever opened it on close.
  *
  * The drawer element stays mounted (it is the static sidebar on desktop), so
- * this is a hook rather than a Dialog primitive.
+ * this is a hook rather than a Dialog primitive. Crossing to the desktop
+ * breakpoint closes the drawer, which releases the trap and drops the dialog
+ * semantics the layout keys on `open`.
  */
 export function useDrawerA11y(
   open: boolean,
@@ -18,9 +31,20 @@ export function useDrawerA11y(
 ) {
   useEffect(() => {
     if (!open) return;
+    const desktop =
+      typeof window.matchMedia === 'function' ? window.matchMedia(DESKTOP_SIDEBAR_QUERY) : null;
+    if (desktop?.matches) {
+      onClose();
+      return;
+    }
+    const onBreakpoint = (e: MediaQueryListEvent) => {
+      if (e.matches) onClose();
+    };
+    desktop?.addEventListener('change', onBreakpoint);
     const drawer = drawerRef.current;
     const opener = document.activeElement as HTMLElement | null;
-    const items = () => (drawer ? Array.from(drawer.querySelectorAll<HTMLElement>(FOCUSABLE)) : []);
+    const items = () =>
+      drawer ? Array.from(drawer.querySelectorAll<HTMLElement>(FOCUSABLE)).filter(isFocusable) : [];
     items()[0]?.focus();
 
     const onKeyDown = (e: KeyboardEvent) => {
@@ -53,6 +77,7 @@ export function useDrawerA11y(
     };
     document.addEventListener('keydown', onKeyDown);
     return () => {
+      desktop?.removeEventListener('change', onBreakpoint);
       document.removeEventListener('keydown', onKeyDown);
       if (opener?.isConnected) opener.focus();
     };