docs: document account-level export scoping and add cross-applet test

Author: sricharan-varanasi

src/apps/audit/crud.py

@@ -54,6 +54,13 @@ async def search_applet_events(
         page: int = 1,
         limit: int = DEFAULT_PAGE_SIZE,
     ) -> tuple[list[AuditLogSchema], int]:
+        """Events for an applet's audit export.
+
+        Returns the applet's own events plus account-level events
+        (``ACCOUNT_LEVEL_EXPORT_ACTIONS``) for its manager-class users. Membership
+        is resolved at query time against current roles, so an account event stops
+        appearing once the user loses their role on the applet.
+        """
         # Users with a manager-class role on this applet. Their account-level events
         # (login/logout/MFA/...) are surfaced in the export even though those events
         # carry no applet id; respondents are intentionally excluded.

src/apps/audit/db/schemas.py

@@ -10,6 +10,10 @@ class AuditLogSchema(Base):
     Append-only. A few columns are denormalized from the ECS document for
     filtering/sorting; the full event is kept in ``payload`` as the same
     dotted-alias JSON that is produced by ``AuditEvent.model_dump(mode="json")``.
+
+    Note: for failed logins the denormalized ``user_id`` is resolved from the
+    attempted email at persist time and may therefore be set even though
+    ``payload["user.id"]`` stays ``null`` (see ``tasks._resolve_actor_from_email``).
     """
 
     __tablename__ = "audit_logs"

src/apps/audit/tests/test_query_service.py

@@ -158,6 +158,25 @@ async def test_mixes_applet_and_account_events(session: AsyncSession, tom: User,
     assert [e.event_id for e in events] == [account_event.event_id, applet_event.event_id]
 
 
+async def test_account_event_isolated_across_applets(
+    session: AsyncSession,
+    tom: User,
+    lucy: User,
+    applet_one_lucy_manager: AppletFull,
+    applet_two: AppletFull,
+):
+    """An account event surfaces only in exports of applets the user is privileged
+    on. lucy manages applet_one but has no role on applet_two, so her login must
+    not leak into applet_two's export."""
+    await _seed(session, _make_account_event(user_id=lucy.id, timestamp=datetime.datetime(2026, 5, 1, 10, 0, 0)))
+
+    _, total_one = await AuditQueryService(session).search_applet_events(applet_one_lucy_manager.id)
+    _, total_two = await AuditQueryService(session).search_applet_events(applet_two.id)
+
+    assert total_one == 1
+    assert total_two == 0
+
+
 async def test_save_is_idempotent_on_event_id(session: AsyncSession):
     applet_id = uuid.uuid4()
     event = _make_event(applet_id, timestamp=datetime.datetime(2026, 5, 1, 10, 0, 0))