You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tooling.apache.org by ar...@apache.org on 2026/10/20 11:38:18 UTC

(tooling-trusted-releases) 03/04: #299 - Throw informative errors on use of detached objects or modified with a session closed without commit. Add static checking for nested sessions or models passed as arguments.

This is an automated email from the ASF dual-hosted git repository.

alitheg pushed a commit to branch arm
in repository https://gitbox.apache.org/repos/asf/tooling-trusted-releases.git

commit 95856b1f5a77abc6cf86a8604d61a5c0a1c525ba
Author: Alastair McFarlane <ar...@apache.org>
AuthorDate: Tue Oct 20 12:24:26 2026 +0100

    #299 - Throw informative errors on use of detached objects or modified with a session closed without commit. Add static checking for nested sessions or models passed as arguments.
---
 .pre-commit-config.yaml                   |   8 ++
 atr/admin/__init__.py                     |   6 +-
 atr/db/__init__.py                        |  69 ++++++++++
 atr/db/interaction.py                     |   8 +-
 atr/get/committees.py                     |   2 +-
 atr/get/root.py                           |   2 +-
 atr/get/test.py                           |   3 +-
 atr/post/projects.py                      |  60 ++++-----
 atr/post/vote.py                          |   4 +-
 atr/post/voting.py                        |   2 -
 atr/sessions.py                           |  14 +-
 atr/storage/writers/vote.py               |  25 ++--
 docker-compose.yml                        |   2 +-
 scripts/lint/check_session_boundaries.py  | 205 ++++++++++++++++++++++++++++++
 tests/unit/test_session_guards.py         | 171 +++++++++++++++++++++++++
 tests/unit/test_sessions.py               |  14 +-
 tests/unit/test_svn_publish_start_vote.py |   2 +-
 tests/unit/test_vote_serials.py           |   5 +-
 18 files changed, 529 insertions(+), 73 deletions(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 09750291..a3a9d6d6 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -185,6 +185,14 @@ repos:
       pass_filenames: false
       always_run: true
 
+    - id: check-session-boundaries
+      name: check session boundaries
+      description: Check that db.session() is not nested inside storage contexts and that writers take keys, not ORM objects
+      entry: uv run --frozen python scripts/lint/check_session_boundaries.py
+      language: system
+      pass_filenames: false
+      always_run: true
+
     - id: check-when-dependencies-updated
       name: check when dependencies were updated
       description: Verify that dependencies were updated within the configured timeframe, for ASVS 15.1.1
diff --git a/atr/admin/__init__.py b/atr/admin/__init__.py
index 2bcbf091..dcdd7495 100644
--- a/atr/admin/__init__.py
+++ b/atr/admin/__init__.py
@@ -1862,9 +1862,9 @@ async def toggle_view_post(
 
     Toggle between admin and user views.
     """
-    session.session.downgrade_admin_to_user = not session.session.downgrade_admin_to_user
-    await asfquart.APP.sessions.save(session.session, {"downgrade_admin_to_user"})
-    quart.g.is_session_downgraded = session.session.downgrade_admin_to_user
+    downgraded = not session.session.downgrade_admin_to_user
+    await asfquart.APP.sessions.save(session.session, {"downgrade_admin_to_user": downgraded})
+    quart.g.is_session_downgraded = downgraded
 
     message = "Viewing as regular user" if session.session.downgrade_admin_to_user else "Viewing as admin"
     await quart.flash(message, "success")
diff --git a/atr/db/__init__.py b/atr/db/__init__.py
index abdcb2b9..98430105 100644
--- a/atr/db/__init__.py
+++ b/atr/db/__init__.py
@@ -29,6 +29,7 @@ import sqlalchemy.dialects.sqlite
 import sqlalchemy.event as event
 import sqlalchemy.ext.asyncio
 import sqlalchemy.orm as orm
+import sqlalchemy.orm.attributes as attributes
 import sqlalchemy.sql
 import sqlmodel
 import sqlmodel.sql.expression as expression
@@ -51,6 +52,7 @@ if TYPE_CHECKING:
 global_log_query: bool = False
 _global_atr_engine: sqlalchemy.ext.asyncio.AsyncEngine | None = None
 _global_atr_sessionmaker: sqlalchemy.ext.asyncio.async_sessionmaker | None = None
+_global_detached_guard_installed: bool = False
 
 
 T = TypeVar("T")
@@ -84,6 +86,14 @@ NOT_SET: Final[NotSet] = NotSet()
 type Opt[T] = T | NotSet
 
 
+class DetachedMutationError(RuntimeError):
+    pass
+
+
+class UnflushedChangesError(RuntimeError):
+    pass
+
+
 class Query[T]:
     def __init__(self, session: Session, query: expression.SelectOfScalar[T]):
         self.query = query
@@ -163,6 +173,16 @@ class Session(sqlalchemy.ext.asyncio.AsyncSession):
         if explicit_value_passed_by_sessionmaker is not None:
             self.log_queries = explicit_value_passed_by_sessionmaker
 
+    # This is __aexit__ and not close() because the async close runs in a shielded task
+    # which cannot see an exception that is propagating out of the block
+    async def __aexit__(self, type_: Any, value: Any, traceback: Any) -> None:
+        sync = self.sync_session
+        pending = [o for o in sync.dirty if sync.is_modified(o)] + list(sync.new) + list(sync.deleted)
+        await super().__aexit__(type_, value, traceback)
+        if pending and (type_ is None):
+            names = ", ".join(sorted({type(o).__name__ for o in pending}))
+            raise UnflushedChangesError(f"Session closed with uncommitted changes to: {names}")
+
     # TODO: Need to type all of these arguments correctly
 
     async def begin_immediate(self) -> None:
@@ -1337,6 +1357,7 @@ def init_database(app: base.QuartApp) -> None:
         _global_atr_sessionmaker = sqlalchemy.ext.asyncio.async_sessionmaker(
             bind=engine, class_=Session, expire_on_commit=False
         )
+        install_detached_mutation_guard()
 
         # Run any pending migrations on startup
         log.info("Applying database migrations via init_database...")
@@ -1380,6 +1401,22 @@ async def init_database_for_worker() -> None:
     _global_atr_sessionmaker = sqlalchemy.ext.asyncio.async_sessionmaker(
         bind=engine, class_=Session, expire_on_commit=False
     )
+    install_detached_mutation_guard()
+
+
+def install_detached_mutation_guard() -> None:
+    global _global_detached_guard_installed
+    if _global_detached_guard_installed:
+        return
+    for mapper in sqlmodel.SQLModel._sa_registry.mappers:
+        for prop in mapper.attrs:
+            instrumented = getattr(mapper.class_, prop.key)
+            if instrumented.impl.collection:
+                event.listen(instrumented, "append", _collection_guard(prop.key))
+                event.listen(instrumented, "remove", _collection_guard(prop.key))
+            else:
+                event.listen(instrumented, "set", _scalar_guard(prop.key))
+    _global_detached_guard_installed = True
 
 
 def is_defined[T](v: T | NotSet) -> TypeGuard[T]:
@@ -1495,9 +1532,41 @@ def session_function[**P, R](
     return wrapper
 
 
+def set_committed_value(instance: object, key: str, value: object) -> None:
+    """Populate an attribute as if loaded, without marking the instance dirty or firing events."""
+    attributes.set_committed_value(instance, key, value)
+
+
 async def shutdown_database() -> None:
     if _global_atr_engine:
         log.info("Closing database")
         await _global_atr_engine.dispose()
     else:
         log.info("No database to close")
+
+
+def _check_detached(target: object, attr_key: str, initiator: attributes.AttributeEventToken) -> None:
+    if not attributes.instance_state(target).detached:
+        return
+    # Setting a back-populated relationship fires the other side first, so we name
+    # the attribute the caller wrote, which the initiator records
+    origin = f"{initiator.impl.class_.__name__}.{initiator.impl.key}"
+    touched = f"{type(target).__name__}.{attr_key}"
+    where = origin if (origin == touched) else f"{origin} (via {touched})"
+    raise DetachedMutationError(
+        f"{where} was set on a detached instance - its session has closed, so this write would be silently discarded"
+    )
+
+
+def _collection_guard(attr_key: str) -> Callable[[object, object, attributes.AttributeEventToken], None]:
+    def guard(target: object, value: object, initiator: attributes.AttributeEventToken) -> None:
+        _check_detached(target, attr_key, initiator)
+
+    return guard
+
+
+def _scalar_guard(attr_key: str) -> Callable[[object, object, object, attributes.AttributeEventToken], None]:
+    def guard(target: object, value: object, old_value: object, initiator: attributes.AttributeEventToken) -> None:
+        _check_detached(target, attr_key, initiator)
+
+    return guard
diff --git a/atr/db/interaction.py b/atr/db/interaction.py
index 68b8c347..21f6dbb3 100644
--- a/atr/db/interaction.py
+++ b/atr/db/interaction.py
@@ -145,7 +145,7 @@ async def all_releases(project: sql.Project) -> list[sql.Release]:
             results.append(release)
 
     for release in results:
-        release.project = project
+        db.set_committed_value(release, "project", project)
 
     try:
         # This rejects any non PEP 440 versions
@@ -945,8 +945,8 @@ async def releases_by_phase(project: sql.Project, phase: sql.ReleasePhase) -> li
             results.append(release)
 
     for release in results:
-        # Don't need to eager load and lose it when the session closes
-        release.project = project
+        # The caller already has the project, so stitch it on as loaded state rather than eager loading
+        db.set_committed_value(release, "project", project)
     return results
 
 
@@ -1193,7 +1193,7 @@ async def user_topnav(
     for project in user_projects:
         active_releases = releases_by_project.get(project.key, [])
         for release in active_releases:
-            release.project = project
+            db.set_committed_value(release, "project", project)
         if not user.can_view_embargoed_release(project.committee, asf_uid, is_member=is_member):
             active_releases = [r for r in active_releases if (not r.is_embargoed)]
         if active_releases:
diff --git a/atr/get/committees.py b/atr/get/committees.py
index dc3c141e..1c8a5c7d 100644
--- a/atr/get/committees.py
+++ b/atr/get/committees.py
@@ -102,7 +102,7 @@ async def view(session: web.Committer, _committees: Literal["committees"], name:
 
     project_list = list(committee.projects)
     for project in project_list:
-        project.committee = committee
+        db.set_committed_value(project, "committee", committee)
     project_list.sort(key=lambda p: interaction.project_order_key(p, latest_releases.get(str(p.key))))
     signing_keys = sorted(
         committee.signing_certificates,
diff --git a/atr/get/root.py b/atr/get/root.py
index 30598df8..40ad9e09 100644
--- a/atr/get/root.py
+++ b/atr/get/root.py
@@ -117,7 +117,7 @@ async def index(_session: web.Public, _root: Literal[""]) -> quart_response.Resp
         for project in user_projects:
             active_releases = releases_by_project.get(project.key, [])
             for release in active_releases:
-                release.project = project
+                db.set_committed_value(release, "project", project)
             if not user.can_view_embargoed_release(project.committee, uid, is_member=session_data.is_member):
                 active_releases = [r for r in active_releases if (not r.is_embargoed)]
             all_projects.append(
diff --git a/atr/get/test.py b/atr/get/test.py
index 95ccd7f5..1967b3a5 100644
--- a/atr/get/test.py
+++ b/atr/get/test.py
@@ -236,8 +236,7 @@ async def test_recheck_session(
     if not isinstance(existing, sql.UserSession):
         raise base.ASFQuartException("No session to recheck", errorcode=400)
 
-    existing.last_account_check = 0
-    await asfquart.APP.sessions.save(existing, {"last_account_check"})
+    await asfquart.APP.sessions.save(existing, {"last_account_check": 0})
     return await web.redirect(root.index)
 
 
diff --git a/atr/post/projects.py b/atr/post/projects.py
index f51f6b7f..5c4391aa 100644
--- a/atr/post/projects.py
+++ b/atr/post/projects.py
@@ -600,42 +600,42 @@ async def _request_approval(
             get.projects.projects, error="CAP approval is not configured. Please contact an administrator."
         )
 
+    async with db.session() as data:
+        project = await data.project(key=str(project_key), _committee=True, _releases=True).get()
+        if (project is None) or (project.committee is None):
+            return await session.redirect(get.projects.projects, error=f"Project '{project_key}' not found.")
+        if project.committee.is_podling:
+            return await session.redirect(
+                get.projects.projects,
+                error=(
+                    "CAP approval voting is not available for podlings. Archival or deletion of a podling is an"
+                    " Incubator PMC decision."
+                ),
+            )
+        committee_key = project.committee.key
+        display_name = project.display_name
+        active_siblings = len(
+            await data.project(committee_key=committee_key, status=sql.ProjectStatus.ACTIVE, _committee=False).all()
+        )
+        eligibility_error = _action_eligibility_error(project, action, active_siblings)
+        if eligibility_error is not None:
+            return await session.redirect(get.projects.projects, error=eligibility_error)
+        existing = await data.approval_request(
+            project_key=str(project_key),
+            status_in=[sql.ApprovalStatus.PENDING, sql.ApprovalStatus.APPROVED],
+        ).get()
+        if existing is not None:
+            return await session.redirect(
+                get.projects.projects,
+                error=f"A CAP approval request to {existing.action.value} this project is already in progress.",
+            )
+
     async with storage.write(session) as write:
         try:
             wacm = await _write_as_committee_member(write, session, project_key)
         except storage.AccessError as e:
             return await session.redirect(get.projects.projects, error=f"Error requesting {action.value} approval: {e}")
 
-        async with db.session() as data:
-            project = await data.project(key=str(project_key), _committee=True, _releases=True).get()
-            if (project is None) or (project.committee is None):
-                return await session.redirect(get.projects.projects, error=f"Project '{project_key}' not found.")
-            if project.committee.is_podling:
-                return await session.redirect(
-                    get.projects.projects,
-                    error=(
-                        "CAP approval voting is not available for podlings. Archival or deletion of a podling is an"
-                        " Incubator PMC decision."
-                    ),
-                )
-            committee_key = project.committee.key
-            display_name = project.display_name
-            active_siblings = len(
-                await data.project(committee_key=committee_key, status=sql.ProjectStatus.ACTIVE, _committee=False).all()
-            )
-            eligibility_error = _action_eligibility_error(project, action, active_siblings)
-            if eligibility_error is not None:
-                return await session.redirect(get.projects.projects, error=eligibility_error)
-            existing = await data.approval_request(
-                project_key=str(project_key),
-                status_in=[sql.ApprovalStatus.PENDING, sql.ApprovalStatus.APPROVED],
-            ).get()
-            if existing is not None:
-                return await session.redirect(
-                    get.projects.projects,
-                    error=f"A CAP approval request to {existing.action.value} this project is already in progress.",
-                )
-
         closes_at = datetime.datetime.now(datetime.UTC) + datetime.timedelta(
             minutes=constants.CAP_VOTE_DURATION_MINUTES
         )
diff --git a/atr/post/vote.py b/atr/post/vote.py
index 71adfcf1..ffb7e56e 100644
--- a/atr/post/vote.py
+++ b/atr/post/vote.py
@@ -98,7 +98,9 @@ async def selected_post(  # noqa: C901
 
     async with storage.write(session) as write:
         wafc = write.as_foundation_committer()
-        email_to, error_message = await wafc.vote.send_user_vote(release, vote, comment, session.fullname, is_binding)
+        email_to, error_message = await wafc.vote.send_user_vote(
+            project_key, version_key, vote, comment, session.fullname, is_binding
+        )
 
     if error_message:
         await quart.flash(error_message, "error")
diff --git a/atr/post/voting.py b/atr/post/voting.py
index 554d2982..9c128b1a 100644
--- a/atr/post/voting.py
+++ b/atr/post/voting.py
@@ -211,7 +211,6 @@ async def selected(  # noqa: C901
                     subject,
                     start_voting_form.body,
                     session.fullname,
-                    release=release,
                     promote=True,
                     permitted_recipients=permitted_recipients,
                     email_cc=start_voting_form.email_cc,
@@ -334,7 +333,6 @@ async def _start_expedited(
                 subject,
                 start_voting_form.body,
                 session.fullname,
-                release=release,
                 promote=True,
                 expected_vote_mode=sql.VoteMode.TRUSTED,
                 expected_revision=start_voting_form.rendered_revision,
diff --git a/atr/sessions.py b/atr/sessions.py
index afab6627..215d8a51 100644
--- a/atr/sessions.py
+++ b/atr/sessions.py
@@ -57,8 +57,7 @@ async def account_check(session: sql.UserSession, current_time: float) -> None:
         await deleted_or_banned(uid)
         raise base.ASFQuartException("Account is disabled", errorcode=401)
 
-    session.last_account_check = current_time
-    await asfquart.APP.sessions.save(session, {"last_account_check"})
+    await asfquart.APP.sessions.save(session, {"last_account_check": current_time})
 
 
 async def deleted_or_banned(uid: str) -> None:
@@ -244,17 +243,20 @@ class Store:
                 await data.commit()
         return count
 
-    async def save(self, user_session: sql.UserSession, fields: set[MutableSessionField]) -> None:
-        if not fields.issubset(_MUTABLE_SESSION_FIELDS):
+    async def save(self, user_session: sql.UserSession, values: dict[MutableSessionField, float | bool | None]) -> None:
+        if not set(values).issubset(_MUTABLE_SESSION_FIELDS):
             raise ValueError("Invalid fields")
+        # The caller's copy is detached, cached on quart.g for the request, so update it as loaded state
+        for field, value in values.items():
+            db.set_committed_value(user_session, field, value)
         async with db.session() as data:
             statement = sqlmodel.select(sql.UserSession).where(sql.UserSession.sid_hash == user_session.sid_hash)
             result = await data.execute(statement)
             existing = result.scalar_one_or_none()
             if existing is None:
                 return
-            for field in fields:
-                setattr(existing, field, getattr(user_session, field))
+            for field, value in values.items():
+                setattr(existing, field, value)
             await data.commit()
 
     async def validate(self, hsid: str) -> sql.UserSession | None:
diff --git a/atr/storage/writers/vote.py b/atr/storage/writers/vote.py
index 0841a587..d37538ed 100644
--- a/atr/storage/writers/vote.py
+++ b/atr/storage/writers/vote.py
@@ -211,12 +211,19 @@ class FoundationCommitter(GeneralPublic):
 
     async def send_user_vote(
         self,
-        release: sql.Release,
+        project_key: safe.ProjectKey,
+        version_key: safe.VersionKey,
         vote: str,
         comment: str,
         fullname: str,
         is_binding: bool = False,
     ) -> tuple[list[str], str]:
+        release = await self.__data.release(
+            project_key=str(project_key),
+            version=str(version_key),
+            _project=True,
+            _committee=True,
+        ).demand(storage.AccessError("Release not found", status=404))
         storage.ensure_project_active(release.project)
         # Get the email thread
         latest_vote_task = await interaction.release_current_vote_task(release)
@@ -334,7 +341,6 @@ class ReleaseManager(CommitteeParticipant):
         subject: str,
         body_data: str,
         asf_fullname: str,
-        release: sql.Release | None = None,
         promote: bool = True,
         permitted_recipients: list[str] | None = None,
         email_cc: list[str] | None = None,
@@ -349,13 +355,12 @@ class ReleaseManager(CommitteeParticipant):
         download_path_suffix: safe.RelPath | None = None,
         acknowledged_concerns: frozenset[str] = frozenset(),
     ) -> sql.Task:
-        if release is None:
-            release = await self.__data.release(
-                project_key=str(project_key),
-                version=str(version_key),
-                _project=True,
-                _committee=True,
-            ).demand(storage.AccessError("Release not found", status=404))
+        release = await self.__data.release(
+            project_key=str(project_key),
+            version=str(version_key),
+            _project=True,
+            _committee=True,
+        ).demand(storage.AccessError("Release not found", status=404))
         storage.ensure_project_active(release.project)
         if release.expedited and (release.committee is not None) and release.committee.is_podling:
             raise storage.AccessError("Expedited releases are not available for podling projects", status=400)
@@ -815,7 +820,6 @@ class ReleaseManager(CommitteeParticipant):
                     vote_duration_choice=vote_duration,
                     subject=subject_data,
                     body_data=body_data,
-                    release=release,
                     promote=False,
                     expected_revision=release.safe_latest_revision_number,
                     automatic_resolve_when_finished=automatic_resolve_when_finished,
@@ -1148,7 +1152,6 @@ class ReleaseManager(CommitteeParticipant):
                     vote_duration_choice=vote_duration,
                     subject=subject_data,
                     body_data=body_data,
-                    release=release,
                     promote=False,
                     expected_revision=release.safe_latest_revision_number,
                     automatic_resolve_when_finished=automatic_resolve_when_finished,
diff --git a/docker-compose.yml b/docker-compose.yml
index 42d1659c..a46f23f2 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -14,7 +14,7 @@ services:
     networks:
       - atr-network
     volumes:
-      - ./state:/opt/atr/state
+      - ./state2:/opt/atr/state
       - ./atr:/opt/atr/atr
       - ./start-dev.sh:/opt/atr/start-atr.sh
     ports:
diff --git a/scripts/lint/check_session_boundaries.py b/scripts/lint/check_session_boundaries.py
new file mode 100755
index 00000000..2d636da8
--- /dev/null
+++ b/scripts/lint/check_session_boundaries.py
@@ -0,0 +1,205 @@
+#!/usr/bin/env python3
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""Check session-context boundaries (issue #299).
+
+Two rules are checked:
+
+1. `async with db.session()` does not appear inside `async with storage.write*(...)`
+   or `async with storage.read*(...)`. The outer `storage.write/read` already
+   provides a session, and a separate inner session risks producing ORM objects
+   that outlive the inner block.
+
+2. Public methods in `atr/storage/writers/*.py` do not take `sql.X` table-model
+   types as parameters. Writers take `safe.X` keys and load the ORM object in their
+   own session. This applies only to names defined as
+   `class X(sqlmodel.SQLModel, table=True)` in `atr/models/sql.py`, so enums and
+   other value types in `sql` are fine. Return annotations are not checked.
+
+   `Callable[...]` subscripts are treated as opaque, as the callback pattern
+   hands ORM objects to a callback whose lifetime is bounded by the framework's
+   own session.
+
+With no arguments the whole of `atr/` is scanned, otherwise only the given paths.
+"""
+
+import ast
+import pathlib
+import sys
+from typing import Final
+
+_DEFAULT_PATH: Final = pathlib.Path(__file__).parent.parent.parent / "atr"
+_SQL_MODELS_PATH: Final = pathlib.Path(__file__).parent.parent.parent / "atr" / "models" / "sql.py"
+_WRITERS_DIR_FRAGMENT: Final = "atr/storage/writers/"
+_CALLABLE_NAMES: Final = frozenset({"Callable", "typing.Callable", "collections.abc.Callable"})
+
+
+def main() -> None:
+    sys.exit(_run(sys.argv[1:]))
+
+
+def _annotation_references_table_model(annotation: ast.AST | None, table_models: frozenset[str]) -> bool:
+    if annotation is None:
+        return False
+    if isinstance(annotation, ast.Subscript) and _is_callable(annotation.value):
+        return False
+    if isinstance(annotation, (ast.Name, ast.Attribute)):
+        name = _name(annotation)
+        if name and any((name == f"sql.{model}") or name.endswith(f".sql.{model}") for model in table_models):
+            return True
+    for child in ast.iter_child_nodes(annotation):
+        if _annotation_references_table_model(child, table_models):
+            return True
+    return False
+
+
+def _check_file(path: pathlib.Path, table_models: frozenset[str]) -> list[str]:
+    tree = ast.parse(path.read_text(), filename=str(path))
+    errors: list[str] = []
+    _check_session_nesting(path, tree, False, errors)
+    if _is_writer_module(path):
+        errors.extend(_check_writer_signatures(path, tree, table_models))
+    return errors
+
+
+def _check_session_nesting(path: pathlib.Path, node: ast.AST, in_storage: bool, errors: list[str]) -> None:
+    if isinstance(node, ast.AsyncWith):
+        opens_storage = any(_is_storage_context_call(item.context_expr) for item in node.items)
+        opens_db_session = any(_is_db_session_call(item.context_expr) for item in node.items)
+        if in_storage and opens_db_session:
+            errors.append(f"{path}:{node.lineno}: db.session() opened inside storage.write/read context")
+        next_in_storage = in_storage or opens_storage
+        for child in ast.iter_child_nodes(node):
+            _check_session_nesting(path, child, next_in_storage, errors)
+        return
+    for child in ast.iter_child_nodes(node):
+        _check_session_nesting(path, child, in_storage, errors)
+
+
+def _check_signature(
+    path: pathlib.Path,
+    cls: ast.ClassDef,
+    func: ast.FunctionDef | ast.AsyncFunctionDef,
+    table_models: frozenset[str],
+) -> list[str]:
+    errors: list[str] = []
+    for arg in (*func.args.posonlyargs, *func.args.args, *func.args.kwonlyargs):
+        if _annotation_references_table_model(arg.annotation, table_models):
+            errors.append(
+                f"{path}:{arg.lineno}: {cls.name}.{func.name} parameter '{arg.arg}' has sql.* table-model type"
+            )
+    return errors
+
+
+def _check_writer_signatures(path: pathlib.Path, tree: ast.AST, table_models: frozenset[str]) -> list[str]:
+    errors: list[str] = []
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.ClassDef):
+            continue
+        for member in node.body:
+            if not isinstance(member, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                continue
+            if member.name.startswith("_"):
+                continue
+            errors.extend(_check_signature(path, node, member, table_models))
+    return errors
+
+
+def _files(argv: list[str]) -> list[pathlib.Path]:
+    if not argv:
+        return _python_files(_DEFAULT_PATH)
+    paths: list[pathlib.Path] = []
+    for arg in argv:
+        path = pathlib.Path(arg)
+        if path.is_dir():
+            paths.extend(_python_files(path))
+        else:
+            paths.append(path)
+    return paths
+
+
+def _is_callable(value: ast.expr) -> bool:
+    name = _name(value)
+    return (name is not None) and (name in _CALLABLE_NAMES)
+
+
+def _is_db_session_call(value: ast.expr) -> bool:
+    return isinstance(value, ast.Call) and (_name(value.func) == "db.session")
+
+
+def _is_storage_context_call(value: ast.expr) -> bool:
+    if not isinstance(value, ast.Call):
+        return False
+    name = _name(value.func)
+    if name is None:
+        return False
+    if not name.startswith("storage."):
+        return False
+    method = name.removeprefix("storage.")
+    return method.startswith("write") or method.startswith("read")
+
+
+def _is_table_model(node: ast.ClassDef) -> bool:
+    if "sqlmodel.SQLModel" not in {_name(base) for base in node.bases}:
+        return False
+    for keyword in node.keywords:
+        if (keyword.arg == "table") and isinstance(keyword.value, ast.Constant) and (keyword.value.value is True):
+            return True
+    return False
+
+
+def _is_writer_module(path: pathlib.Path) -> bool:
+    return _WRITERS_DIR_FRAGMENT in str(path).replace("\\", "/")
+
+
+def _name(value: ast.expr) -> str | None:
+    if isinstance(value, ast.Name):
+        return value.id
+    if isinstance(value, ast.Attribute):
+        parent = _name(value.value)
+        if parent is None:
+            return value.attr
+        return f"{parent}.{value.attr}"
+    return None
+
+
+def _python_files(directory: pathlib.Path) -> list[pathlib.Path]:
+    return sorted(directory.rglob("*.py"))
+
+
+def _run(argv: list[str]) -> int:
+    table_models = _table_model_names()
+    errors: list[str] = []
+    for path in _files(argv):
+        errors.extend(_check_file(path, table_models))
+    for error in errors:
+        print(error, file=sys.stderr)
+    return 1 if errors else 0
+
+
+def _table_model_names() -> frozenset[str]:
+    tree = ast.parse(_SQL_MODELS_PATH.read_text(), filename=str(_SQL_MODELS_PATH))
+    result: set[str] = set()
+    for node in tree.body:
+        if isinstance(node, ast.ClassDef) and _is_table_model(node):
+            result.add(node.name)
+    return frozenset(result)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/tests/unit/test_session_guards.py b/tests/unit/test_session_guards.py
new file mode 100644
index 00000000..10971911
--- /dev/null
+++ b/tests/unit/test_session_guards.py
@@ -0,0 +1,171 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+import datetime
+from collections.abc import AsyncIterator
+
+import pytest
+import sqlalchemy
+import sqlalchemy.ext.asyncio
+import sqlalchemy.pool
+import sqlmodel
+
+import atr.db as db
+import atr.models.sql as sql
+
+type Maker = sqlalchemy.ext.asyncio.async_sessionmaker[db.Session]
+
+
+@pytest.fixture
+async def maker() -> AsyncIterator[Maker]:
+    db.install_detached_mutation_guard()
+    engine = sqlalchemy.ext.asyncio.create_async_engine(
+        "sqlite+aiosqlite:///:memory:",
+        connect_args={"check_same_thread": False},
+        poolclass=sqlalchemy.pool.StaticPool,
+    )
+    async with engine.begin() as conn:
+        await conn.run_sync(sqlmodel.SQLModel.metadata.create_all)
+    sessionmaker = sqlalchemy.ext.asyncio.async_sessionmaker(bind=engine, class_=db.Session, expire_on_commit=False)
+    async with sessionmaker() as data:
+        data.add(sql.Committee(key="tooling", name="Tooling"))
+        project = sql.Project(key="tooling-atr", name="Apache Tooling ATR", committee_key="tooling")
+        data.add(project)
+        await data.commit()
+        data.add(sql.ReleasePolicy(project=project, min_hours=24))
+        data.add(_release("0.1.0"))
+        await data.commit()
+    yield sessionmaker
+    await engine.dispose()
+
+
+async def test_aexit_keeps_exception_from_block(maker: Maker) -> None:
+    with pytest.raises(ValueError, match="boom"):
+        async with maker() as data:
+            project = await _project(data)
+            project.description = "changed"
+            raise ValueError("boom")
+
+
+async def test_aexit_raises_for_uncommitted_change(maker: Maker) -> None:
+    with pytest.raises(db.UnflushedChangesError, match="Project"):
+        async with maker() as data:
+            project = await _project(data)
+            project.description = "first"
+            await data.commit()
+            project.description = "second"
+    async with maker() as data:
+        assert (await _project(data)).description == "first"
+
+
+async def test_aexit_allows_explicit_rollback(maker: Maker) -> None:
+    async with maker() as data:
+        project = await _project(data)
+        project.description = "changed"
+        await data.rollback()
+
+
+async def test_aexit_allows_no_op_assignment(maker: Maker) -> None:
+    async with maker() as data:
+        project = await _project(data)
+        project.description = project.description
+
+
+async def test_aexit_allows_read_only_block(maker: Maker) -> None:
+    async with maker() as data:
+        await _project(data)
+
+
+async def test_detached_mutation_names_written_attribute(maker: Maker) -> None:
+    async with maker() as data:
+        project = await _project(data)
+    with pytest.raises(db.DetachedMutationError, match=r"Project.description"):
+        project.description = "changed"
+
+
+async def test_detached_mutation_raises_across_sessions(maker: Maker) -> None:
+    async with maker() as data:
+        project = await data.project(key="tooling-atr", _release_policy=True).demand(RuntimeError("no project"))
+    async with maker() as writer_data:
+        with pytest.raises(db.DetachedMutationError, match=r"ReleasePolicy.min_hours"):
+            project.release_policy.min_hours = 72
+        await writer_data.commit()
+    async with maker() as data:
+        project = await data.project(key="tooling-atr", _release_policy=True).demand(RuntimeError("no project"))
+        assert project.release_policy.min_hours == 24
+
+
+async def test_detached_mutation_names_origin_of_backref_write(maker: Maker) -> None:
+    async with maker() as data:
+        project = await _project(data)
+        release = await data.release(project_key="tooling-atr", version="0.1.0").demand(RuntimeError("no release"))
+    with pytest.raises(db.DetachedMutationError, match=r"Release.project"):
+        release.project = project
+
+
+async def test_merge_then_mutate_lands(maker: Maker) -> None:
+    async with maker() as data:
+        project = await _project(data)
+    async with maker() as data:
+        merged = await data.merge(project)
+        merged.description = "merged"
+        await data.commit()
+    async with maker() as data:
+        assert (await _project(data)).description == "merged"
+
+
+async def test_mutate_after_commit_inside_block_lands(maker: Maker) -> None:
+    async with maker() as data:
+        project = await _project(data)
+        await data.commit()
+        project.description = "after commit"
+        await data.commit()
+    async with maker() as data:
+        assert (await _project(data)).description == "after commit"
+
+
+async def test_set_committed_value_does_not_dirty_detached_instance(maker: Maker) -> None:
+    async with maker() as data:
+        project = await _project(data)
+        release = await data.release(project_key="tooling-atr", version="0.1.0").demand(RuntimeError("no release"))
+    db.set_committed_value(release, "project", project)
+    assert release.project is project
+    assert not sqlalchemy.inspect(release).modified
+
+
+async def test_transient_construct_and_commit_works(maker: Maker) -> None:
+    async with maker() as data:
+        release = _release("0.2.0")
+        release.phase = sql.ReleasePhase.RELEASE_CANDIDATE
+        data.add(release)
+        await data.commit()
+    async with maker() as data:
+        stored = await data.release(project_key="tooling-atr", version="0.2.0").demand(RuntimeError("no release"))
+        assert stored.phase == sql.ReleasePhase.RELEASE_CANDIDATE
+
+
+async def _project(data: db.Session) -> sql.Project:
+    return await data.project(key="tooling-atr").demand(RuntimeError("no project"))
+
+
+def _release(version: str) -> sql.Release:
+    return sql.Release(
+        project_key="tooling-atr",
+        version=version,
+        phase=sql.ReleasePhase.RELEASE_CANDIDATE_DRAFT,
+        created=datetime.datetime.now(datetime.UTC),
+    )
diff --git a/tests/unit/test_sessions.py b/tests/unit/test_sessions.py
index b4b6e85d..745ce691 100644
--- a/tests/unit/test_sessions.py
+++ b/tests/unit/test_sessions.py
@@ -74,8 +74,7 @@ async def test_account_check_fails_open_when_ldap_unavailable(monkeypatch):
     await sessions.account_check(user_session, 123.0)
 
     deleted.assert_not_awaited()
-    save.assert_awaited_once()
-    assert user_session.last_account_check == 123.0
+    save.assert_awaited_once_with(user_session, {"last_account_check": 123.0})
 
 
 async def test_account_check_revokes_user_when_admin_check_unavailable(monkeypatch):
@@ -104,8 +103,7 @@ async def test_account_check_saves_timestamp_when_active(monkeypatch):
 
     await sessions.account_check(user_session, 123.0)
 
-    save.assert_awaited_once()
-    assert user_session.last_account_check == 123.0
+    save.assert_awaited_once_with(user_session, {"last_account_check": 123.0})
 
 
 async def test_create_logs_auth_success(store, monkeypatch):
@@ -205,7 +203,7 @@ async def test_destroy_then_save_does_not_resurrect(store):
     assert user_session is not None
 
     await store.destroy(hsid)
-    await store.save(user_session, {"last_account_check"})
+    await store.save(user_session, {"last_account_check": 12345.0})
     assert await store.validate(hsid) is None
 
 
@@ -280,14 +278,14 @@ async def test_revoke_by_uid_removes_all_sessions(store):
     assert await store.validate(hsid3) is not None
 
 
-async def test_save_persists_mutations(store):
+async def test_save_persists_values(store):
     hsid = _hsid()
     await store.create(hsid, _session_data())
     user_session = await store.validate(hsid)
     assert user_session is not None
 
-    user_session.last_account_check = 12345.0
-    await store.save(user_session, {"last_account_check"})
+    await store.save(user_session, {"last_account_check": 12345.0})
+    assert user_session.last_account_check == 12345.0
 
     reloaded = await store.validate(hsid)
     assert reloaded is not None
diff --git a/tests/unit/test_svn_publish_start_vote.py b/tests/unit/test_svn_publish_start_vote.py
index a8a36cb0..5bdb7586 100644
--- a/tests/unit/test_svn_publish_start_vote.py
+++ b/tests/unit/test_svn_publish_start_vote.py
@@ -168,6 +168,7 @@ async def test_start_rejects_automatic_publish_for_expedited(monkeypatch) -> Non
         expedited=True,
         podling_thread_id=None,
     )
+    data.release = mock.MagicMock(return_value=SimpleNamespace(demand=mock.AsyncMock(return_value=release)))
     data.project = mock.MagicMock(
         return_value=SimpleNamespace(get=mock.AsyncMock(return_value=SimpleNamespace(committee=committee)))
     )
@@ -191,7 +192,6 @@ async def test_start_rejects_automatic_publish_for_expedited(monkeypatch) -> Non
             "[VOTE] Release example 1.0",
             "Please vote.",
             "Alice",
-            release=release,
             promote=True,
             automatic_publish_when_resolved=True,
         )
diff --git a/tests/unit/test_vote_serials.py b/tests/unit/test_vote_serials.py
index 5d83afb2..1bba5094 100644
--- a/tests/unit/test_vote_serials.py
+++ b/tests/unit/test_vote_serials.py
@@ -474,7 +474,6 @@ async def test_podling_second_round_rolls_back_with_task_creation(sqlite_session
                     vote_duration_choice=72,
                     subject="[VOTE] Release",
                     body_data="Please vote",
-                    release=release_model,
                     promote=False,
                 )
                 assert task.task_args["vote_seq"] == 2
@@ -658,7 +657,9 @@ async def test_vote_email_labels_reflect_membership(
             is_binding, _committee = await user.is_binding_for_release(
                 release_model.project.committee, "chair", vote_round, caller_data=data
             )
-            result = await writer.send_user_vote(release_model, "+1", "", "Voter", is_binding)
+            result = await writer.send_user_vote(
+                safe.ProjectKey("project"), safe.VersionKey("1.0.0"), "+1", "", "Voter", is_binding
+            )
 
         assert result == (["dev@project.apache.org"], "")
         message_task = (


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@tooling.apache.org
For additional commands, e-mail: commits-help@tooling.apache.org