Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Python agent-orchestrationaiai-agentschatopsdiscordlangchainmcpmicrosoft-teamsmulti-agentopen-sourceopenaiself-hostedslack
fix(db): bind a tenant per unit of background work, not per task (CHOO-2623)
Wojciech Wojtyniak417f922217df
diff --git a/core/switch_core/bridges/agent/protocol/service.py b/core/switch_core/bridges/agent/protocol/service.pyindex 86cfa2067..3695760eb 100644--- a/core/switch_core/bridges/agent/protocol/service.py+++ b/core/switch_core/bridges/agent/protocol/service.py@@ -72,7 +72,7 @@ from switch_core.db.models import (Tool,User,)-from switch_core.db.session_scope import tenant_session, unscoped_session+from switch_core.db.session_scope import unscoped_sessionfrom switch_core.db.stores.agent_runtime_state_store import (IDLE as RUNTIME_STATE_IDLE,)@@ -475,7 +475,12 @@ class ProtocolService:the source of truth, that guess would confirm itself forever."""token_hash = hashlib.sha256(registration_token.encode()).hexdigest()- async with self.session_factory() as session:+ # Resolving a credential is unscoped by definition — `key_hash` is one+ # of the two columns deliberately left globally unique for exactly+ # this reason — and it is the read that *produces* the tenant bound+ # below. Answering it under a tenant would make it either a tautology+ # or a false "invalid token".+ async with unscoped_session(self.session_factory) as session:key = await self.api_key_store.get_by_hash(session, token_hash)if key is None or key.type not in REGISTRATION_KEY_TYPES:raise PermissionError("Invalid registration token")@@ -1564,39 +1569,52 @@ class ProtocolService:"""# This sweep spans every tenant by nature — it is the one place that# decides whether *any* stale row anywhere needs resetting — so the- # initial read is unscoped. Each row is itself tenant-scoped- # (agent_runtime_states carries tenant_id), so the rest of the work- # for that row binds its own tenant rather than the whole sweep, and- # a row from one tenant can never leak its binding into the next.+ # initial read is unscoped. Everything done *with* a row then happens+ # inside that row's own tenant, including the emit at the end: the+ # clear event goes out to a bridge, which resolves a mention handle+ # and posts a message, and those are writes in the row's tenant like+ # any other. Closing the binding after the upsert and leaving the tail+ # outside it would put exactly the visible half of the work back on+ # whatever was ambient.async with unscoped_session(self.session_factory) as session:rows = await self.agent_runtime_state_store.get_active(session)for row in rows:if self.connections.has_session_in(row.agent_id, row.room_id):continue- async with tenant_session(self.session_factory, row.tenant_id) as session:- live = await self.agent_session_store.get_live_agent_ids(- session, [row.agent_id], row.room_id- )- if row.agent_id in live:- continue- async with tenant_session(self.session_factory, row.tenant_id) as session:- agent = await self.agent_store.get(session, row.agent_id)- room = await self.room_store.get(session, row.room_id)- if agent is None or room is None:- continue- await self.agent_runtime_state_store.upsert(- session, row.agent_id, row.room_id, RUNTIME_STATE_IDLE- )- await session.commit()- await self._emit_runtime_state(- agent_id=agent.id,- agent_name=agent.name,- matrix_room_id=room.matrix_room_id,- room_id=room.id,- state=RUNTIME_STATE_IDLE,- mention_handle=await self._mention_handle_for(agent, room.bridge_id),- thread_id=None,+ with tenant_scope(row.tenant_id):+ await self._sweep_one_runtime_state(row.agent_id, row.room_id)++ async def _sweep_one_runtime_state(self, agent_id: str, room_id: str) -> None:+ """One stale row's worth of the sweep, under its tenant.++ Split out so the binding is the whole body rather than a prefix of it:+ an early `return` here cannot accidentally leave later work outside+ the scope the way an early `continue` in the loop could.+ """+ async with self.session_factory() as session:+ live = await self.agent_session_store.get_live_agent_ids(+ session, [agent_id], room_id)+ if agent_id in live:+ return+ async with self.session_factory() as session:+ agent = await self.agent_store.get(session, agent_id)+ room = await self.room_store.get(session, room_id)+ if agent is None or room is None:+ return+ await self.agent_runtime_state_store.upsert(+ session, agent_id, room_id, RUNTIME_STATE_IDLE+ )+ await session.commit()+ await self._emit_runtime_state(+ agent_id=agent.id,+ agent_name=agent.name,+ matrix_room_id=room.matrix_room_id,+ room_id=room.id,+ state=RUNTIME_STATE_IDLE,+ mention_handle=await self._mention_handle_for(agent, room.bridge_id),+ thread_id=None,+ )async def _mention_handle_for(self, agent: Agent, bridge_id: str | Nonediff --git a/core/switch_core/bridges/agent/server_connectors/core.py b/core/switch_core/bridges/agent/server_connectors/core.pyindex 24bcb132c..7746b1855 100644--- a/core/switch_core/bridges/agent/server_connectors/core.py+++ b/core/switch_core/bridges/agent/server_connectors/core.py@@ -20,6 +20,7 @@ from switch_core.bridges.agent.server_connectors.base import (DiscoveredAgent,ServerSideConnector,)+from switch_core.tenant_context import no_tenant, tenant_scopeif TYPE_CHECKING:from switch_core.bridges.agent.protocol.service import ProtocolService@@ -78,12 +79,17 @@ class ConnectorCore:self,*,connector_id: str,+ connector_tenant_id: str,connector_type: str,connector: ServerSideConnector,registration_token: str,protocol: ProtocolService,) -> None:self._connector_id = connector_id+ # The tenant of the connector's own row. Held, never bound for the+ # life of anything: each poll and each event it produces binds it for+ # that piece of work and releases it again.+ self._connector_tenant_id = connector_tenant_idself._connector_type = connector_typeself._connector = connectorself._registration_token = registration_token@@ -133,29 +139,30 @@ class ConnectorCore:# ── internal ─────────────────────────────────────────────────────────async def _register_agent(self, agent: DiscoveredAgent) -> None:- # Runs from `start()`, which the caller wraps in the connector's own- # tenant (ServerSideConnectorLifecycleService.start_all binds it- # before starting each connector's task; an admin registering one- # over HTTP already has it bound). register_agent_with_token- # additionally binds the registration token's own tenant for the- # write itself — the same tenant either way — see its docstring.+ # Registering one agent is one unit of work for this connector's row,+ # so it binds that row's tenant here rather than inheriting anything.+ # `register_agent_with_token` additionally binds the registration+ # token's own tenant for the write itself — the same tenant either+ # way — see its docstring.try:- result = await self._protocol.register_agent_with_token(- registration_token=self._registration_token,- name=agent.name,- description=agent.description,- connector_type=f"server-side:{self._connector_type}",- integration_profile=agent.integration_profile,- tools=agent.tools,- models=agent.models,- metadata={"server_connector_id": self._connector_id},- overwrite=True,- # A server-side connector agent is a service the deployment- # offers everyone, not one person's assistant; it is owned by- # whoever holds the registration token only in the bookkeeping- # sense. Owner-only would make it answer to that account alone.- owner_only=False,- )+ with tenant_scope(self._connector_tenant_id):+ result = await self._protocol.register_agent_with_token(+ registration_token=self._registration_token,+ name=agent.name,+ description=agent.description,+ connector_type=f"server-side:{self._connector_type}",+ integration_profile=agent.integration_profile,+ tools=agent.tools,+ models=agent.models,+ metadata={"server_connector_id": self._connector_id},+ overwrite=True,+ # A server-side connector agent is a service the+ # deployment offers everyone, not one person's assistant;+ # it is owned by whoever holds the registration token only+ # in the bookkeeping sense. Owner-only would make it+ # answer to that account alone.+ owner_only=False,+ )except Exception:logger.exception("Failed to register agent %s from connector %s",@@ -178,42 +185,56 @@ class ConnectorCore:return _ProtocolReporter(self._protocol, handle)async def _poll_loop(self, handle: _AgentHandle) -> None:+ """One agent's long-poll loop.++ `no_tenant` around the loop and `tenant_scope` around each pass: the+ loop itself is a task and owns no tenant, while one poll and the+ events it returns are one unit of work for this connector's row. The+ binding is taken and released per pass, so a loop that has been+ running for days is in exactly the same state as one that just+ started.+ """logger.info("Starting poll loop for agent %s (%s)",handle.agent_name,handle.agent_id,)- while True:- try:- events = await self._protocol.poll_events(- handle.agent_id, timeout=CONNECTOR_POLL_TIMEOUT_SECONDS- )- for event in events:- payload = event.payload-- if isinstance(payload, MessagePayload):- await self._handle_message(handle, event.room_id, payload)- elif isinstance(payload, CommandPayload):- await self._handle_command(handle, event.room_id, payload)- elif isinstance(payload, TaskDelegatePayload):- await self._handle_task_delegate(handle, event.room_id, payload)- elif isinstance(payload, TaskUpdatePayload):- await self._handle_task_update(handle, event.room_id, payload)- elif isinstance(payload, TaskFinalisePayload):- await self._handle_task_finalise(handle, event.room_id, payload)- elif isinstance(payload, TaskCancelPayload):- await self._handle_task_cancel(handle, event.room_id, payload)- except asyncio.CancelledError:- logger.info("Poll loop cancelled for agent %s", handle.agent_name)- return- except Exception:- logger.exception(- "Error in poll loop for agent %s (%s)",- handle.agent_name,- handle.agent_id,- )- await asyncio.sleep(5)+ with no_tenant():+ while True:+ try:+ with tenant_scope(self._connector_tenant_id):+ await self._poll_once(handle)+ except asyncio.CancelledError:+ logger.info("Poll loop cancelled for agent %s", handle.agent_name)+ return+ except Exception:+ logger.exception(+ "Error in poll loop for agent %s (%s)",+ handle.agent_name,+ handle.agent_id,+ )+ await asyncio.sleep(5)++ async def _poll_once(self, handle: _AgentHandle) -> None:+ events = await self._protocol.poll_events(+ handle.agent_id, timeout=CONNECTOR_POLL_TIMEOUT_SECONDS+ )+ for event in events:+ payload = event.payload++ if isinstance(payload, MessagePayload):+ await self._handle_message(handle, event.room_id, payload)+ elif isinstance(payload, CommandPayload):+ await self._handle_command(handle, event.room_id, payload)+ elif isinstance(payload, TaskDelegatePayload):+ await self._handle_task_delegate(handle, event.room_id, payload)+ elif isinstance(payload, TaskUpdatePayload):+ await self._handle_task_update(handle, event.room_id, payload)+ elif isinstance(payload, TaskFinalisePayload):+ await self._handle_task_finalise(handle, event.room_id, payload)+ elif isinstance(payload, TaskCancelPayload):+ await self._handle_task_cancel(handle, event.room_id, payload)async def _handle_message(self,diff --git a/core/switch_core/bridges/agent/server_connectors/lifecycle.py b/core/switch_core/bridges/agent/server_connectors/lifecycle.pyindex 1297c99e9..8b1d804f3 100644--- a/core/switch_core/bridges/agent/server_connectors/lifecycle.py+++ b/core/switch_core/bridges/agent/server_connectors/lifecycle.py@@ -17,7 +17,6 @@ from switch_core.db.models import ApiKey, ServerConnectorfrom switch_core.db.session_scope import unscoped_sessionfrom switch_core.db.stores.api_key_store import ApiKeyStorefrom switch_core.db.stores.server_connector_store import ServerConnectorStore-from switch_core.tenant_context import tenant_scopelogger = logging.getLogger(__name__)@@ -54,17 +53,16 @@ class ServerSideConnectorLifecycleService:async def start_all(self) -> None:# Every tenant's active connectors in one pass — unscoped by nature,# same reasoning as CollaborationBridgeLifecycleService.start_all.- # Each row carries its own tenant; bind it only around starting that- # one connector, and the poll loop `start` spawns keeps it for that- # task's own life via the context asyncio.create_task snapshots.+ # Nothing is bound around `start`: it reads the connector's own row+ # and hands that row's tenant to the core, which binds it per unit of+ # work rather than once for the poll loop's life.async with unscoped_session(self._session_factory) as session:connectors = await self._connector_store.get_active(session)logger.info("Starting %d server-side connectors", len(connectors))for record in connectors:try:- with tenant_scope(record.tenant_id):- await self.start(record.id)+ await self.start(record.id)except Exception:logger.exception("Failed to start connector %s", record.id)@@ -118,7 +116,10 @@ class ServerSideConnectorLifecycleService:return recordasync def start(self, connector_id: str) -> None:- async with self._session_factory() as session:+ # Unscoped: the read that answers which tenant this connector is in,+ # reached both from boot with nothing bound and from an HTTP request+ # whose tenant is the caller's, not necessarily the connector's.+ async with unscoped_session(self._session_factory) as session:record = await self._connector_store.get(session, connector_id)if record is None:raise ValueError(f"Connector not found: {connector_id}")@@ -140,6 +141,7 @@ class ServerSideConnectorLifecycleService:core = ConnectorCore(connector_id=connector_id,+ connector_tenant_id=record.tenant_id,connector_type=record.type,connector=connector,registration_token=registration_token,diff --git a/core/switch_core/bridges/collaboration/bridge_core.py b/core/switch_core/bridges/collaboration/bridge_core.pyindex 8c8cd7c01..6a563eb6e 100644--- a/core/switch_core/bridges/collaboration/bridge_core.py+++ b/core/switch_core/bridges/collaboration/bridge_core.py@@ -30,7 +30,7 @@ from switch_core.clients.admin_messages import ADMIN_MARKER, AdminMessageTypefrom switch_core.clients.client_base import ClientBase, ClientConfigfrom switch_core.clients.mentions import mention_regex, strip_emphasisfrom switch_core.db.models import BridgeMessageMap, ExternalUser-from switch_core.db.session_scope import tenant_session+from switch_core.db.session_scope import tenant_session, unscoped_sessionfrom switch_core.db.stores.agent_store import AgentStorefrom switch_core.db.stores.bridge_message_map_store import BridgeMessageMapStorefrom switch_core.db.stores.client_store import ClientStore@@ -40,7 +40,7 @@ from switch_core.events import AgentRuntimeStateEventfrom switch_core.logging_context import log_contextfrom switch_core.provisioning import Provisioningfrom switch_core.room_service import RoomCreateConfig-from switch_core.tenant_context import tenant_scope+from switch_core.tenant_context import no_tenant, tenant_scopefrom switch_core.transport import (InboundMedia as TransportMedia,)@@ -122,6 +122,7 @@ class BridgeCore:self,*,bridge_id: str,+ bridge_tenant_id: str,bridge_type: str,bridge_display_name: str,adapter: CollaborationAdapter,@@ -139,6 +140,14 @@ class BridgeCore:max_attachment_bytes: int,) -> None:self._bridge_id = bridge_id+ # The tenant of this bridge's own row. Read once here because it is+ # immutable, but never *bound* for the life of anything: each unit of+ # work binds it at the point it acts, and room-scoped work binds the+ # room's tenant instead. The schema makes those the same value —+ # `rooms` has a composite foreign key to `collaboration_bridges` on+ # `tenant_id` — but the code does not lean on that, so a room whose+ # tenant somehow differs is still handled under its own.+ self._bridge_tenant_id = bridge_tenant_idself._bridge_type = bridge_typeself._bridge_display_name = bridge_display_nameself._adapter = adapter@@ -157,12 +166,10 @@ class BridgeCore:self._channel_to_room: dict[str, tuple[str, str]] = {}self._room_to_channel: dict[tuple[str, str], str] = {}- # Switch room id -> its tenant, populated wherever a room is looked- # up or created. A room's tenant is as immutable as its channel- # mapping, unlike this bridge's own — a bridge can in principle carry- # rooms in more than one tenant over time — so each unit of work- # binds the room it is actually for rather than one tenant cached for- # the whole bridge. See `_room_tenant`.+ # Switch room id -> its tenant. Filled by `add_room_mapping`, which is+ # the one way a room enters the channel maps at all, so a room that+ # has a channel mapping always has a tenant here — including rooms+ # created long after this bridge started. See `_room_tenant`.self._room_tenants: dict[str, str] = {}self._user_puppets: dict[str, str] = {}# External user ids whose stored name is known not to be a platform id,@@ -210,7 +217,7 @@ class BridgeCore:self, handler: Callable[[_InboundEventT], Awaitable[None]]) -> Callable[[_InboundEventT], Awaitable[None]]:"""Give each inbound platform event its own id in the logs, and bind- the tenant of the room it is for, when that room already exists.+ the tenant the event belongs to.An event fans out across room lookup, identity provisioning and thetransport, so without this the lines from two events arriving at once@@ -219,21 +226,32 @@ class BridgeCore:choke point is where the tenant is bound, so a handler needs nosession-opening call site of its own to remember it.- A channel with no room yet (auto-room-creation, still to come in the- handler) binds nothing here: which tenant a *new* room lands in is an- ambient decision, the same as any other creation, not something this- wrapper can derive from a room that does not exist.+ This is what makes the platform irrelevant. An adapter is free to+ deliver from anywhere: Mattermost's websocket runs on an OS thread and+ hands the coroutine over with `asyncio.run_coroutine_threadsafe`,+ which starts it in an *empty* context, while Slack's dispatches from a+ task that inherited whatever created it. Binding here rather than+ relying on what the handler inherits means both arrive at the same+ tenant, so which platform a message came in on stops being able to+ decide where its room lands.++ A channel with no room yet — auto-room-creation, still to come in the+ handler — binds the **bridge's** tenant. There is no room to ask, but+ there is nothing ambient about the answer either: a room this bridge+ creates belongs to the tenant that owns the bridge, and the schema+ agrees (`rooms` keys to `collaboration_bridges` on `tenant_id`)."""async def traced(event: _InboundEventT) -> None:event_id = uuid.uuid4().hex[:16]with log_context(request_id=f"{self._bridge_type}-{event_id}"):room_ids = self._channel_to_room.get(event.channel_id)- if room_ids is None:- await handler(event)- return- room_id, _ = room_ids- with tenant_scope(await self._room_tenant(room_id)):+ tenant_id = (+ self._bridge_tenant_id+ if room_ids is None+ else await self._room_tenant(room_ids[0])+ )+ with tenant_scope(tenant_id):await handler(event)return traced@@ -268,14 +286,18 @@ class BridgeCore:# ── Startup loading ──────────────────────────────────────────────────────async def _load_channel_map(self) -> None:- async with self._session_factory() as session:+ async with tenant_session(+ self._session_factory, self._bridge_tenant_id+ ) as session:rooms = await self._room_store.get_by_bridge(session, self._bridge_id)for room in rooms:- self._room_tenants[room.id] = room.tenant_idif room.external_channel_id:- key = (room.id, room.matrix_room_id)- self._channel_to_room[room.external_channel_id] = key- self._room_to_channel[key] = room.external_channel_id+ self.add_room_mapping(+ room.id,+ room.matrix_room_id,+ room.external_channel_id,+ room.tenant_id,+ )async def _room_tenant(self, room_id: str) -> str:"""The tenant `room_id` belongs to, resolved and cached.@@ -285,11 +307,19 @@ class BridgeCore:tenant, only on a given room's tenant never changing once it exists —the same invariant `_channel_to_room` already relies on for thechannel mapping.++ A miss should not happen — `add_room_mapping` fills the tenant along+ with the channel mapping, and this is only ever asked about a room+ that has one — but if it does, the read is deliberately **unscoped**.+ Asking "which tenant is this room in" while a tenant is bound would+ either confirm the guess or return nothing, and the second reads as+ "no such room" for a room that exists in another tenant. The whole+ point of resolving is that the answer is not known yet."""cached = self._room_tenants.get(room_id)if cached is not None:return cached- async with self._session_factory() as session:+ async with unscoped_session(self._session_factory) as session:room = await self._room_store.get(session, room_id)if room is None:raise ValueError(f"Room not found: {room_id}")@@ -297,7 +327,9 @@ class BridgeCore:return room.tenant_idasync def _load_existing_puppets(self) -> None:- async with self._session_factory() as session:+ async with tenant_session(+ self._session_factory, self._bridge_tenant_id+ ) as session:users = await self._external_user_store.get_by_bridge(session, self._bridge_id)@@ -327,7 +359,15 @@ class BridgeCore:A bare create_task swallows whatever the coroutine raises, so anythingescaping the per-agent handling below would vanish without trace.- Cancellation is ordinary shutdown and says so quietly."""+ Cancellation is ordinary shutdown and says so quietly.++ `no_tenant` for the same reason the bridge's own task does it: this is+ a task, and a task keeps whatever context created it. The work inside+ binds the bridge's tenant for itself."""+ with no_tenant():+ await self._run_agent_identities_unbound()++ async def _run_agent_identities_unbound(self) -> None:try:await self._create_agent_identities()except asyncio.CancelledError:@@ -342,7 +382,9 @@ class BridgeCore:)async def _create_agent_identities(self) -> None:- async with self._session_factory() as session:+ async with tenant_session(+ self._session_factory, self._bridge_tenant_id+ ) as session:agents = await self._agent_store.get_all(session)failed = 0@@ -381,7 +423,9 @@ class BridgeCore:bridge's channels. Runs on startup so capture self-heals after a restartor a notification-URL change (e.g. a rotated tunnel). A no-op foradapters that don't use expiring subscriptions."""- async with self._session_factory() as session:+ async with tenant_session(+ self._session_factory, self._bridge_tenant_id+ ) as session:rooms = await self._room_store.get_by_bridge(session, self._bridge_id)channels: list[tuple[str, str]] = []for room in rooms:@@ -401,8 +445,16 @@ class BridgeCore:know whether to override what it already has. Either field being Nonewithin a hit means the same thing one field down: the agent was givenno value, and the adapter's default stands.++ Installed on the adapter, so it is called from the adapter's own task+ with nothing bound rather than through `_traced` — hence the explicit+ bind. Agent names are unique per tenant, not globally, so an unscoped+ read here would raise `MultipleResultsFound` the day a second tenant+ has an agent of the same name."""- async with self._session_factory() as session:+ async with tenant_session(+ self._session_factory, self._bridge_tenant_id+ ) as session:agent = await self._agent_store.get_by_name(session, agent_name)if agent is None:return None@@ -827,7 +879,12 @@ class BridgeCore:"""lock = self._channel_locks.setdefault(old_id, asyncio.Lock())async with lock:- async with self._session_factory() as session:+ # Reached from the adapter's own task rather than through+ # `_traced`, so nothing is bound: this is one unit of work for one+ # bridge, and it binds that bridge's tenant to find its room.+ async with tenant_session(+ self._session_factory, self._bridge_tenant_id+ ) as session:room = await self._room_store.get_by_external_channel(session, self._bridge_id, old_id)@@ -860,10 +917,8 @@ class BridgeCore:await self._room_store.update_external_channel(session, room.id, new_id)await session.commit()- key = (room.id, room.matrix_room_id)self._channel_to_room.pop(old_id, None)- self._channel_to_room[new_id] = key- self._room_to_channel[key] = new_id+ self.add_room_mapping(room.id, room.matrix_room_id, new_id, room.tenant_id)logger.warning("Re-pointed room %s from channel %s to %s after the platform ""reissued the id",@@ -884,14 +939,15 @@ class BridgeCore:"""If a room already exists in the DB for this channel on this bridge,register it in the in-memory map and return its (room_id,matrix_room_id). Returns None if no such room exists. Idempotent."""- async with self._session_factory() as session:+ async with tenant_session(+ self._session_factory, self._bridge_tenant_id+ ) as session:room = await self._room_store.get_by_external_channel(session, self._bridge_id, channel_id)if room is None:return None- self._room_tenants[room.id] = room.tenant_id- self.add_room_mapping(room.id, room.matrix_room_id, channel_id)+ self.add_room_mapping(room.id, room.matrix_room_id, channel_id, room.tenant_id)logger.debug("Adopted existing room %s for channel %s", room.id, channel_id)return (room.id, room.matrix_room_id)@@ -967,8 +1023,7 @@ class BridgeCore:return Noneroom = result.room- self._room_tenants[room.id] = room.tenant_id- self.add_room_mapping(room.id, room.matrix_room_id, channel_id)+ self.add_room_mapping(room.id, room.matrix_room_id, channel_id, room.tenant_id)logger.info("Auto-created %s room %s for %s channel %s",channel_type,@@ -1259,61 +1314,77 @@ class BridgeCore:async def _create_puppet(self, external_user_id: str, external_username: str) -> str:+ """Mint the Matrix identity that stands in for a person on the platform.++ Bound to the **bridge's** tenant, not to whatever room the message+ that triggered it arrived in. A puppet is per-bridge and outlives that+ message: the same client is reused for every room this person speaks+ in, so a client row stamped with the first room's tenant would be+ wrong for the second — and the client task it starts must not carry+ that tenant either, which is why `ClientLifecycleService` unbinds+ before running one.+ """lock = self._puppet_locks.setdefault(external_user_id, asyncio.Lock())async with lock:- existing = self._user_puppets.get(external_user_id)- if existing is not None:- return existing-- # Defence in depth against agent/user misdetection: a- # bridged agent must never be puppeted as an external user. If the- # name collides with a registered Switch agent, refuse loudly rather- # than create a duplicate "user" identity for it.- async with self._session_factory() as session:- agent = await self._agent_store.get_by_name(session, external_username)- if agent is not None:- raise ValueError(- f"Refusing to create external-user puppet for '{external_username}'"- " on bridge "- f"{self._bridge_id}: name collides with a registered Switch agent"- " (likely a bridged agent bot misclassified as a user)"+ with tenant_scope(self._bridge_tenant_id):+ return await self._create_puppet_locked(+ external_user_id, external_username)- sanitized = re.sub(r"[^a-z0-9_-]", "-", external_username.lower()).strip(- "-"- )- # Scope to the bridge: the same username on two bridges of the same- # type (e.g. two Slack workspaces) must map to distinct Matrix users,- # since matrix_user_id is globally unique but usernames are not.- localpart = f"switch-{self._bridge_type}-{self._bridge_id}-{sanitized}"+ async def _create_puppet_locked(+ self, external_user_id: str, external_username: str+ ) -> str:+ existing = self._user_puppets.get(external_user_id)+ if existing is not None:+ return existing- client = await self._client_lifecycle.create_and_start(- client_type="user",- display_name=external_username,- localpart=localpart,- )+ # Defence in depth against agent/user misdetection: a+ # bridged agent must never be puppeted as an external user. If the+ # name collides with a registered Switch agent, refuse loudly rather+ # than create a duplicate "user" identity for it.+ async with self._session_factory() as session:+ agent = await self._agent_store.get_by_name(session, external_username)+ if agent is not None:+ raise ValueError(+ f"Refusing to create external-user puppet for '{external_username}'"+ " on bridge "+ f"{self._bridge_id}: name collides with a registered Switch agent"+ " (likely a bridged agent bot misclassified as a user)"+ )++ sanitized = re.sub(r"[^a-z0-9_-]", "-", external_username.lower()).strip("-")+ # Scope to the bridge: the same username on two bridges of the same+ # type (e.g. two Slack workspaces) must map to distinct Matrix users,+ # since matrix_user_id is globally unique but usernames are not.+ localpart = f"switch-{self._bridge_type}-{self._bridge_id}-{sanitized}"++ client = await self._client_lifecycle.create_and_start(+ client_type="user",+ display_name=external_username,+ localpart=localpart,+ )- ext_user = ExternalUser(- bridge_id=self._bridge_id,- external_user_id=external_user_id,- external_username=external_username,- client_id=client.client_id,- )- async with self._session_factory() as session:- await self._external_user_store.create(session, ext_user)- await session.commit()+ ext_user = ExternalUser(+ bridge_id=self._bridge_id,+ external_user_id=external_user_id,+ external_username=external_username,+ client_id=client.client_id,+ )+ async with self._session_factory() as session:+ await self._external_user_store.create(session, ext_user)+ await session.commit()- self._user_puppets[external_user_id] = client.client_id- self._puppet_matrix_ids.add(client.matrix_user_id)- self._adapter.prime_mention_targets({external_username: external_user_id})+ self._user_puppets[external_user_id] = client.client_id+ self._puppet_matrix_ids.add(client.matrix_user_id)+ self._adapter.prime_mention_targets({external_username: external_user_id})- logger.info(- "Created puppet %s for external user %s on bridge %s",- client.matrix_user_id,- external_user_id,- self._bridge_id,- )- return client.client_id+ logger.info(+ "Created puppet %s for external user %s on bridge %s",+ client.matrix_user_id,+ external_user_id,+ self._bridge_id,+ )+ return client.client_iddef _find_channel(self, room_id: str | None = None, matrix_room_id: str | None = None@@ -1966,14 +2037,29 @@ class BridgeCore:self._provisioning_channels.discard(external_channel_id)def add_room_mapping(- self, room_id: str, matrix_room_id: str, external_channel_id: str+ self,+ room_id: str,+ matrix_room_id: str,+ external_channel_id: str,+ tenant_id: str,) -> None:+ """Register a room↔channel mapping, and the room's tenant with it.++ The tenant is a required argument rather than something looked up+ later because every caller already has the room row in hand. Taking it+ here is what lets `_traced` bind a tenant for a room created *after*+ this bridge started without a database read on the inbound path — and,+ more to the point, without a read that would run under whatever tenant+ happened to be bound at the time.+ """key = (room_id, matrix_room_id)self._channel_to_room[external_channel_id] = keyself._room_to_channel[key] = external_channel_id+ self._room_tenants[room_id] = tenant_iddef remove_room_mapping(self, room_id: str, matrix_room_id: str) -> None:key = (room_id, matrix_room_id)channel_id = self._room_to_channel.pop(key, None)if channel_id is not None:self._channel_to_room.pop(channel_id, None)+ self._room_tenants.pop(room_id, None)diff --git a/core/switch_core/bridges/collaboration/lifecycle_service.py b/core/switch_core/bridges/collaboration/lifecycle_service.pyindex 71269a52a..59d57888f 100644--- a/core/switch_core/bridges/collaboration/lifecycle_service.py+++ b/core/switch_core/bridges/collaboration/lifecycle_service.py@@ -15,7 +15,7 @@ from switch_core.clients.bridge_client import BridgeClient, BridgeClientConfigfrom switch_core.clients.client_factory import ClientFactoryfrom switch_core.config import SwitchConfigfrom switch_core.db.models import CollaborationBridge-from switch_core.db.session_scope import unscoped_session+from switch_core.db.session_scope import tenant_session, unscoped_sessionfrom switch_core.db.stores.agent_store import AgentStorefrom switch_core.db.stores.bridge_message_map_store import BridgeMessageMapStorefrom switch_core.db.stores.client_store import ClientStore@@ -23,7 +23,7 @@ from switch_core.db.stores.collaboration_bridge_store import CollaborationBridgefrom switch_core.db.stores.external_user_store import ExternalUserStorefrom switch_core.db.stores.room_store import RoomStorefrom switch_core.provisioning import Provisioning-from switch_core.tenant_context import tenant_scope+from switch_core.tenant_context import no_tenantif TYPE_CHECKING:from switch_core.clients.client_lifecycle_service import ClientLifecycleService@@ -191,20 +191,19 @@ class CollaborationBridgeLifecycleService:async def start_all(self) -> None:# Every tenant's active bridges in one pass, so the read is unscoped- # by nature. Each row already carries its own tenant; bind that one- # only around starting it, not the whole fan-out. `start` spawns the- # bridge's long-lived task from inside this binding, and an asyncio- # task snapshots the context it was created under, so the task keeps- # this tenant for its own life without the loop needing to hold it- # open past the moment the task exists.+ # by nature. Nothing is bound around `start`: the bridge's tenant is+ # read from its own row inside `start`, and bound by each unit of work+ # that needs it. Binding here instead would only decide what the+ # long-lived task snapshots, which is exactly what must not matter —+ # `start` is also reached from an HTTP request, and a bridge cannot+ # run under whichever tenant happened to restart it.async with unscoped_session(self._session_factory) as session:bridges = await self._bridge_store.get_active(session)logger.info("Starting %d collaboration bridges", len(bridges))for bridge in bridges:try:- with tenant_scope(bridge.tenant_id):- await self.start(bridge.id)+ await self.start(bridge.id)except Exception:logger.exception("Failed to start bridge %s", bridge.id)@@ -227,7 +226,12 @@ class CollaborationBridgeLifecycleService:if wanted is None:return- async with self._session_factory() as session:+ # Deliberately across every tenant. Two tenants binding the same Slack+ # workspace, or the same Teams listen port, is precisely the collision+ # this exists to refuse — the resource is a property of the host and+ # the platform, not of a tenant — so narrowing to the caller's tenant+ # would make it miss the case it was written for.+ async with unscoped_session(self._session_factory) as session:existing = await self._bridge_store.get_all(session)for other in existing:# Guard the None case explicitly: an unflushed row has no id yet, and@@ -344,10 +348,15 @@ class CollaborationBridgeLifecycleService:return bridgeasync def start(self, bridge_id: str) -> None:- async with self._session_factory() as session:+ # Unscoped: this is the read that answers which tenant the bridge is+ # in, and it is reached both from boot (nothing bound) and from an+ # HTTP request (the caller's tenant bound, which is not necessarily+ # the bridge's). Everything below derives its tenant from this row.+ async with unscoped_session(self._session_factory) as session:bridge = await self._bridge_store.get(session, bridge_id)if bridge is None:raise ValueError(f"Bridge not found: {bridge_id}")+ tenant_id = bridge.tenant_idadapter_cls = self._adapter_registry.get(bridge.type)config_cls = self._config_registry.get(bridge.type)@@ -371,11 +380,13 @@ class CollaborationBridgeLifecycleService:typed_config = config_cls.model_validate(bridge.connection_config or {})adapter = adapter_cls(config=typed_config) # type: ignore[call-arg]adapter.set_service_url_persister(- lambda service_url: self._persist_service_url(bridge_id, service_url)+ lambda service_url: self._persist_service_url(+ bridge_id, tenant_id, service_url+ ))adapter.set_channel_team_persister(lambda channel_id, team_id: self._persist_channel_team(- bridge_id, channel_id, team_id+ bridge_id, tenant_id, channel_id, team_id))adapter.set_max_attachment_bytes(self._config.agent_media_max_bytes)@@ -394,7 +405,7 @@ class CollaborationBridgeLifecycleService:bridge_id,)- async with self._session_factory() as session:+ async with tenant_session(self._session_factory, tenant_id) as session:bridge_client_record = await self._client_store.get(session, bridge.client_id)@@ -403,6 +414,7 @@ class CollaborationBridgeLifecycleService:bridge_core = BridgeCore(bridge_id=bridge_id,+ bridge_tenant_id=tenant_id,bridge_type=bridge.type,bridge_display_name=bridge.display_name,adapter=adapter,@@ -432,7 +444,7 @@ class CollaborationBridgeLifecycleService:)task = asyncio.create_task(- self._run_bridge(bridge_id, bridge_core, bridge_client)+ self._run_bridge(bridge_id, tenant_id, bridge_core, bridge_client))self._bridges[bridge_id] = bridge_coreself._tasks[bridge_id] = task@@ -441,25 +453,32 @@ class CollaborationBridgeLifecycleService:logger.info("Started collaboration bridge %s (%s)", bridge_id, bridge.type)- async def _persist_service_url(self, bridge_id: str, service_url: str) -> None:+ async def _persist_service_url(+ self, bridge_id: str, tenant_id: str, service_url: str+ ) -> None:"""Persist an outbound serviceUrl an adapter learned from inbound traffic- so outbound survives a restart (used by the Teams adapter)."""- async with self._session_factory() as session:+ so outbound survives a restart (used by the Teams adapter).++ Called from inside the adapter's own task, which binds nothing, so the+ bridge's tenant is carried here explicitly rather than inherited."""+ async with tenant_session(self._session_factory, tenant_id) as session:await self._bridge_store.set_service_url(session, bridge_id, service_url)await session.commit()async def _persist_channel_team(- self, bridge_id: str, channel_id: str, team_id: str+ self, bridge_id: str, tenant_id: str, channel_id: str, team_id: str) -> None:"""Persist the team an adapter learned a channel belongs to, so channelcapture survives a restart (used by the Teams adapter)."""- async with self._session_factory() as session:+ async with tenant_session(self._session_factory, tenant_id) as session:await self._bridge_store.set_channel_team(session, bridge_id, channel_id, team_id)await session.commit()- async def _record_bridge_memberships(self, bridge_id: str, client_id: str) -> None:+ async def _record_bridge_memberships(+ self, bridge_id: str, tenant_id: str, client_id: str+ ) -> None:"""Make the bridge's rooms its recorded memberships before it starts.A bridge belongs in every room it carries, and that was expressed by@@ -472,7 +491,7 @@ class CollaborationBridgeLifecycleService:Run at every start rather than repaired once, because the rooms abridge carries change while it is stopped."""- async with self._session_factory() as session:+ async with tenant_session(self._session_factory, tenant_id) as session:rooms = await self._room_store.get_by_bridge(session, bridge_id)added = 0for room in rooms:@@ -492,18 +511,34 @@ class CollaborationBridgeLifecycleService:async def _run_bridge(self,bridge_id: str,+ tenant_id: str,bridge_core: BridgeCore,bridge_client: BridgeClient,) -> None:- try:- await self._record_bridge_memberships(bridge_id, bridge_client.client_id)- await bridge_core.start()- await bridge_client.start()- except Exception:- logger.exception("Bridge %s crashed", bridge_id)- self._bridges.pop(bridge_id, None)- self._tasks.pop(bridge_id, None)- self._held_resources.pop(bridge_id, None)+ """The bridge's own long-lived task.++ `no_tenant` first, because an `asyncio.Task` snapshots the contextvars+ of whoever created it — and `start` is reached from an HTTP request as+ often as from boot, so without this the bridge would spend its whole+ life acting as the operator who happened to restart it. Nothing here+ is ambient afterwards: `_record_bridge_memberships` binds the bridge's+ tenant for its own writes, `BridgeCore.start` binds it around each+ piece of bridge-level loading it does, and `bridge_client.start()` —+ which runs until shutdown — binds nothing at all, leaving each+ delivery to bind the tenant of the room it is for.+ """+ with no_tenant():+ try:+ await self._record_bridge_memberships(+ bridge_id, tenant_id, bridge_client.client_id+ )+ await bridge_core.start()+ await bridge_client.start()+ except Exception:+ logger.exception("Bridge %s crashed", bridge_id)+ self._bridges.pop(bridge_id, None)+ self._tasks.pop(bridge_id, None)+ self._held_resources.pop(bridge_id, None)async def stop(self, bridge_id: str) -> None:bridge_core = self._bridges.get(bridge_id)diff --git a/core/switch_core/clients/agent_client.py b/core/switch_core/clients/agent_client.pyindex 554c448b2..c4b22f1ee 100644--- a/core/switch_core/clients/agent_client.py+++ b/core/switch_core/clients/agent_client.py@@ -44,6 +44,7 @@ from switch_core.clients.mentions import ()from switch_core.clients.room_meta import RoomMetafrom switch_core.db.models import Agent+from switch_core.db.session_scope import unscoped_sessionfrom switch_core.db.stores.agent_session_store import AgentSessionStorefrom switch_core.db.stores.agent_store import AgentStorefrom switch_core.db.stores.collaboration_bridge_store import CollaborationBridgeStore@@ -297,7 +298,16 @@ class AgentClient(ClientBase[ClientConfig]):return self.agentasync def start(self) -> None:- async with self.session_factory() as session:+ """Resolve the agent this client is, then run.++ Unscoped, deliberately: this runs at the top of the client's own task,+ which binds nothing, and it is the lookup that says which tenant this+ client belongs to at all. `clients.id` is globally unique, so there is+ nothing for a tenant to disambiguate — while a guessed one would turn+ "this client is an agent" into "no agent found for client" and fail+ the client at boot over a row that exists.+ """+ async with unscoped_session(self.session_factory) as session:agent = await self._agent_store.get_by_client_id(session, self.client_id)if agent is None:raise RuntimeError(f"No agent found for client: {self.client_id}")diff --git a/core/switch_core/clients/client_lifecycle_service.py b/core/switch_core/clients/client_lifecycle_service.pyindex b45a1fde5..c8c57b5b0 100644--- a/core/switch_core/clients/client_lifecycle_service.py+++ b/core/switch_core/clients/client_lifecycle_service.py@@ -14,7 +14,7 @@ from switch_core.db.models import Clientfrom switch_core.db.session_scope import unscoped_sessionfrom switch_core.db.stores.client_store import ClientStorefrom switch_core.provisioning import Provisioning-from switch_core.tenant_context import tenant_scope+from switch_core.tenant_context import no_tenantlogger = logging.getLogger(__name__)@@ -57,14 +57,13 @@ class ClientLifecycleService:async def start_all(self) -> None:# Every tenant's clients in one pass at boot, so this read is- # unscoped by nature. Each row carries its own tenant; bind it only- # around starting that one client. `_start_task` spawns the client's- # own long-lived task from inside this binding, and an asyncio task- # snapshots the context it was created under, so the task keeps this- # tenant as its default for its own life — a bootstrap fallback for- # a read like AgentClient.start() resolving its own row, not a cache- # any room-scoped work relies on: PostgresTransport binds the tenant- # of the room it is actually acting on for each of those.+ # unscoped by nature. Nothing is bound around `_start_task`: a client+ # is not a single-tenant actor for the purposes of its own task. It+ # reads which rooms it is in — a lookup keyed by a globally unique+ # client id — and then works one room at a time, binding that room's+ # tenant per delivery. A boot-time binding would only decide what the+ # task snapshots, and the whole point is that nothing downstream may+ # depend on that.async with unscoped_session(self._session_factory) as session:records = await self._client_store.get_all(session)@@ -75,8 +74,7 @@ class ClientLifecycleService:client = self._client_factory.create(record)self._clients[record.id] = clientself._client_types[record.id] = record.type- with tenant_scope(record.tenant_id):- self._start_task(record.id, client)+ self._start_task(record.id, client)async def create_client(self,@@ -188,11 +186,24 @@ class ClientLifecycleService:async def _run_client(self, client_id: str, client: ClientBase[ClientConfig]) -> None:- try:- await client.start()- except Exception:- logger.exception(- "Client %s (%s) crashed", client.display_name, client.matrix_user_id- )- self._clients.pop(client_id, None)- self._tasks.pop(client_id, None)+ """A client's long-lived task, deliberately ambient-free.++ `no_tenant` because a task keeps the context of whoever created it,+ and the creators differ: boot, a gateway request that added an agent,+ or an inbound bridge message that minted a puppet mid-conversation.+ A puppet in particular is reused for every room the person it stands+ for speaks in, so the first room's tenant is exactly the value that+ must not survive into the second. Everything the client does binds+ the tenant of the room it is acting on, or — for the two lookups that+ answer *which* tenant, its own row and its room list — is unscoped on+ purpose.+ """+ with no_tenant():+ try:+ await client.start()+ except Exception:+ logger.exception(+ "Client %s (%s) crashed", client.display_name, client.matrix_user_id+ )+ self._clients.pop(client_id, None)+ self._tasks.pop(client_id, None)diff --git a/core/switch_core/db/models.py b/core/switch_core/db/models.pyindex d9a56257b..d90c99663 100644--- a/core/switch_core/db/models.py+++ b/core/switch_core/db/models.py@@ -91,14 +91,18 @@ TENANT_ZERO_ID = "00000000-0000-0000-0000-000000000000"def _tenant_id_default() -> str:"""The tenant a new scoped row lands in when nothing tells it otherwise.- Prefers the tenant bound to the current request/session context; falls- back to tenant zero only when nothing is bound. The fallback is still- load-bearing: the ~206 background call sites that open a session from the- factory directly (`docs/old/multi-tenancy-phase1-db.md`, "Setting the- tenant") bind no tenant at all today, and removing this fallback before- they are converted — and before the row-level-security policies land to- make an unscoped write fail loudly instead — would break every one of- them. Remove it once both have shipped.+ Prefers the tenant bound to the current unit of work; falls back to tenant+ zero only when nothing is bound. The fallback is still load-bearing, and+ now for a sharper reason than before: the long-lived background tasks+ deliberately bind *nothing* for their lifetime+ (`switch_core.tenant_context.no_tenant`), so a write reached from one that+ did not bind the row's tenant lands here rather than on someone else's+ tenant. That is the right failure while there is one tenant and no policy+ to raise instead. It is the wrong one the day there are two — a write that+ should have been refused becomes a write into tenant zero — so this goes+ when row-level security lands, not before, and the raw-session inventory+ in `tests/switch_core/db/test_unscoped_session_allowlist.py` is what+ tracks how much is still relying on it."""return current_tenant_id() or TENANT_ZERO_IDdiff --git a/core/switch_core/db/session_scope.py b/core/switch_core/db/session_scope.pyindex d92c8cccc..c00e679ae 100644--- a/core/switch_core/db/session_scope.py+++ b/core/switch_core/db/session_scope.py@@ -6,33 +6,41 @@ Everything in a request already gets a tenant for free: `gateway/auth.py` and`after_begin` hook (`db/tenant_session.py`) stamps it on every transactionthat session opens from then on, at any depth, with no call site to remember.-Nothing does that for the roughly 206 places that open a session from the+Nothing does that for the roughly 197 places that open a session from thefactory directly with no request behind them — the delivery loop, thecollaboration and server-connector lifecycle services, the startup seeding in`main.py`, the periodic sweeps. Each needs to say, at the point it opens asession, which of two things it is doing:- **`tenant_session`** binds a tenant for the life of one session, the same- way a request does. This is the answer for a unit of work that acts for one- room, one bridge, or one connector — a message delivery, an inbound bridge- event, a bridge's own startup, one row out of a cross-tenant sweep. Bind at- the natural unit of work: derive the tenant from whatever the work is- actually for (the room, the bridge, the connector row), not once per- long-lived object and reused, since a client or a bridge is not guaranteed- to act for only one tenant over its life.--- **`unscoped_session`** opens a session with no tenant bound at all — the- fail-open hatch inside an otherwise fail-closed design. It exists for work- that is legitimately cross-tenant: reading every row before fanning out- work per row (a sweep, a lifecycle enumeration), and startup seeding that- runs before any tenant can be said to exist. Nothing today stops a query on- a session it opens from reading across every tenant there is — that is- exactly what "unscoped" means — so its callers are pinned to an explicit- allowlist by- `tests/switch_core/db/test_unscoped_session_allowlist.py`, which fails on a- new one and says what to do about it. Reach for `tenant_session` first;- reach for this only when the work really cannot be attributed to one- tenant.+ way a request does. This is the answer for a unit of work that acts on one+ row: a message delivery, an inbound bridge event, one bridge's startup, one+ row out of a cross-tenant sweep. Derive the tenant from the row the work is+ actually for — the room, the bridge, the connector — at the point the work+ happens. Never once per long-lived object, and never once per task: see+ `tenant_context.no_tenant` for why.++- **`unscoped_session`** opens a session with **no tenant bound at all**, for+ the duration of the block, whatever the caller had bound going in. It is+ the fail-open hatch inside an otherwise fail-closed design, and it exists+ for two shapes of work:++ - reading every row before fanning out work per row — a sweep, a lifecycle+ enumeration, startup seeding that runs before any tenant exists;+ - a lookup whose whole job is to answer *which* tenant something is in, or+ that is keyed by something globally unique and spans tenants by nature:+ resolving a room from its transport id, or a client's rooms from its id.+ Inheriting a caller's tenant here is not a smaller answer, it is a wrong+ one.++ The unbinding is the point, and it is why this is not a synonym for calling+ the factory. A helper that merely *named* the intent while inheriting+ whatever was ambient would have the hook stamp the caller's tenant onto the+ transaction, and the cross-tenant read the call site asked for would+ silently be a single-tenant one. Its callers are pinned to an explicit+ allowlist by `tests/switch_core/db/test_unscoped_session_allowlist.py`,+ which fails on a new one and says what to do about it. Reach for+ `tenant_session` first.Both are thin: the tenant binding is a contextvar (`tenant_context.py`), andthe `after_begin` hook is what actually turns it into `set_config` on the@@ -48,7 +56,7 @@ from contextlib import asynccontextmanagerfrom sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker-from switch_core.tenant_context import bind_tenant_id, unbind_tenant_id+from switch_core.tenant_context import bind_tenant_id, no_tenant, unbind_tenant_id@asynccontextmanager@@ -75,12 +83,14 @@ async def unscoped_session() -> AsyncIterator[AsyncSession]:"""Open a session with no tenant bound — the fail-open hatch.- Behaves exactly like calling `session_factory()` directly today, because- that is what it is: no binding, no unbinding, nothing hidden. The point of- naming it is not to change what it does but to make every place that does- it say so, so the allowlist in- `tests/switch_core/db/test_unscoped_session_allowlist.py` has something to- pin.+ Unbinds for the duration of the block and restores the caller's binding on+ the way out, so a query issued here reads across every tenant *whether or+ not* the caller had one bound. That is the whole contract: a call site+ that says "unscoped" and then quietly ran scoped, because it was reached+ from a request or from inside a `tenant_scope`, would be the worst+ available outcome — an allowlist certifying a cross-tenant read that never+ happened."""- async with session_factory() as session:- yield session+ with no_tenant():+ async with session_factory() as session:+ yield sessiondiff --git a/core/switch_core/room_service.py b/core/switch_core/room_service.pyindex 7a0d898a3..45265d3dc 100644--- a/core/switch_core/room_service.py+++ b/core/switch_core/room_service.py@@ -540,7 +540,7 @@ class RoomService:if bridge_core and external_channel_id:bridge_core.add_room_mapping(- room.id, matrix_room_id, external_channel_id+ room.id, matrix_room_id, external_channel_id, room.tenant_id)finally:if bridge_core and external_channel_id:@@ -781,15 +781,23 @@ class RoomService:logger.info("Removed %d agents from room %s", len(agent_ids), room_id)- async def _room_tenant(self, room_id: str) -> str:- """The tenant a room belongs to, resolved fresh — never cached beside- a room id, since nothing here holds one room for longer than a call.+ async def _load_room(self, room_id: str) -> Room:+ """A room row, read with no tenant bound.++ The bootstrap read: every caller below is about to bind the tenant+ this returns, so scoping the read to a tenant would be circular — and+ worse than circular under policies, where the wrong guess turns into+ `Room not found` for a room that exists. Nothing is cached: no caller+ here holds a room for longer than the call."""- async with self._session_factory() as session:+ async with unscoped_session(self._session_factory) as session:room = await self._room_store.get(session, room_id)if room is None:raise ValueError(f"Room not found: {room_id}")- return room.tenant_id+ return room++ async def _room_tenant(self, room_id: str) -> str:+ return (await self._load_room(room_id)).tenant_idasync def update_room(self,@@ -941,7 +949,7 @@ class RoomService:if bridge_core and external_channel_id:bridge_core.add_room_mapping(- room.id, room.matrix_room_id, external_channel_id+ room.id, room.matrix_room_id, external_channel_id, room.tenant_id)await self._ensure_channel_capture(bridge_core, external_channel_id, channel_type@@ -1054,7 +1062,7 @@ class RoomService:await session.commit()new_bridge.add_room_mapping(- room_id, matrix_room_id, external_channel_id+ room_id, matrix_room_id, external_channel_id, room.tenant_id)finally:new_bridge.end_provisioning(external_channel_id)@@ -1182,10 +1190,8 @@ class RoomService:"""Invite a single running client to the room (it auto-joins) and recordits membership. Idempotent — safe to call repeatedly, e.g. on everybridged message from an external user's puppet."""- async with self._session_factory() as session:- room = await self._room_store.get(session, room_id)- if room is None:- raise ValueError(f"Room not found: {room_id}")+ room = await self._load_room(room_id)+ async with tenant_session(self._session_factory, room.tenant_id) as session:already_member = client_id in await self._room_store.get_client_ids(session, room_id)diff --git a/core/switch_core/tenant_context.py b/core/switch_core/tenant_context.pyindex fd9f63aab..a64e5a9c6 100644--- a/core/switch_core/tenant_context.py+++ b/core/switch_core/tenant_context.py@@ -15,7 +15,9 @@ decide what happens when nothing is bound — callers do, deliberately:has no tenant and must not be given one it invented.- `db/models.py`'s `TenantScoped` default treats "nothing bound" as tenantzero, because the background call sites that still write through it have- not been converted to bind one yet.+ not been converted to bind one yet — and because the long-lived tasks now+ unbind deliberately (`no_tenant` below), "nothing bound" is the ordinary+ state there rather than an accident.Neither of those fallbacks lives here. A `current_tenant_id()` that quietlysubstituted a default would make both of those call sites indistinguishable@@ -48,6 +50,16 @@ def unbind_tenant_id(token: Token[str | None]) -> None:_current_tenant_id.reset(token)+def clear_tenant_id() -> Token[str | None]:+ """Unbind whatever tenant is bound, returning a token to restore it with.++ Distinct from never having bound one only in that it can be undone. What+ the reader sees is the same: `current_tenant_id()` is `None` and the+ `after_begin` hook issues no `set_config`.+ """+ return _current_tenant_id.set(None)++@contextmanagerdef tenant_scope(tenant_id: str) -> Iterator[None]:"""Bind `tenant_id` for the duration of the block."""@@ -56,3 +68,27 @@ def tenant_scope(tenant_id: str) -> Iterator[None]:yieldfinally:unbind_tenant_id(token)+++@contextmanager+def no_tenant() -> Iterator[None]:+ """Unbind for the duration of the block, whatever was bound going in.++ Two uses, and they are the same idea from both ends:++ - a lookup that must span tenants (which tenant is this room in? which+ rooms is this client a member of?) must not inherit a caller's tenant,+ or it silently narrows to it;+ - a long-lived background task must not inherit the context of whatever+ created it. An `asyncio.Task` snapshots the contextvars of its creator,+ so a bridge restarted from an HTTP request would otherwise run its whole+ life under the requesting user's tenant. Entering this at the top of the+ task body makes the task ambient-free, so every unit of work inside it+ has to bind the tenant of the row it is acting on — and one that forgets+ reads nothing rather than reading the wrong tenant.+ """+ token = clear_tenant_id()+ try:+ yield+ finally:+ unbind_tenant_id(token)diff --git a/core/switch_core/transport/postgres.py b/core/switch_core/transport/postgres.pyindex 5734f1c63..bd00bfa6a 100644--- a/core/switch_core/transport/postgres.py+++ b/core/switch_core/transport/postgres.py@@ -42,7 +42,7 @@ from typing import TYPE_CHECKING, Anyfrom switch_core.attachments import ATTACHMENT_GROUP_KEYfrom switch_core.db.models import ClientRoom, MediaBlob, Message, MessageAttachment-from switch_core.db.session_scope import tenant_session+from switch_core.db.session_scope import tenant_session, unscoped_sessionfrom switch_core.messages.recorded_types import EPHEMERALfrom switch_core.messages.row import attachments_in, text_field, thread_root_offrom switch_core.tenant_context import tenant_scope@@ -272,15 +272,16 @@ class PostgresTransport:noticed keeps every guard downstream in play, and covers whatever elsedepended on hearing its own join."""- async with self._session_factory() as session:- room_id = await self._resolve_room(session, transport_room_id)- if room_id in self._cursors:- return- self._cursors[room_id] = (- from_seq- if from_seq is not None- else await self._message_store.head_seq(session, room_id)- )+ room_id, tenant_id = await self._resolve_room_and_tenant(transport_room_id)+ if room_id in self._cursors:+ return+ if from_seq is not None:+ self._cursors[room_id] = from_seq+ else:+ async with tenant_session(self._session_factory, tenant_id) as session:+ self._cursors[room_id] = await self._message_store.head_seq(+ session, room_id+ )self._watching[room_id] = transport_room_idself._listener.subscribe(room_id, self._on_room_advanced)self._ephemeral.subscribe(transport_room_id, self._on_ephemeral)@@ -555,8 +556,8 @@ class PostgresTransport:Scoped to the room, so an id from elsewhere cannot be read through it —the caller is resolving a thread root supplied by an agent."""- async with self._session_factory() as session:- switch_room_id = await self._resolve_room(session, room_id)+ switch_room_id, tenant_id = await self._resolve_room_and_tenant(room_id)+ async with tenant_session(self._session_factory, tenant_id) as session:rows = await self._message_store.list_by_transport_event_ids(session, switch_room_id, [event_id])@@ -629,8 +630,21 @@ class PostgresTransport:return Trueasync def joined_rooms(self) -> list[str]:- """The transport-side ids of this client's rooms."""- async with self._session_factory() as session:+ """The transport-side ids of this client's rooms.++ Unscoped, and that is the point rather than an oversight. This runs+ once, at the top of `receive_forever`, in a task that binds nothing —+ so a tenant here could only come from whatever created the task, and+ answering "which rooms is this client in" under a guessed tenant+ returns a *subset* with no error to say so. The failure would be+ silent and total: the client watches the rooms it was allowed to see+ and is simply deaf in the rest, forever, with nothing in the log.++ The key it reads by is `clients.id`, which is globally unique, so+ there is nothing for a tenant to disambiguate. Each room that comes+ back is then watched under its own tenant, resolved from its own row.+ """+ async with unscoped_session(self._session_factory) as session:rooms = await self._room_store.get_for_client(session, self.client_id)return [room.matrix_room_id for room in rooms if room.matrix_room_id]@@ -643,11 +657,13 @@ class PostgresTransport:async def _resolve_room(self, session: AsyncSession, transport_room_id: str) -> str:"""The Switch room id for `transport_room_id`, resolved and cached.- No tenant is bound on `session` yet when this runs the first time for- a room — resolving which room (and so which tenant) this is is the- thing that determines one, the same bootstrap as authenticating a- request. It caches the tenant alongside the id from the very same- row, so nothing downstream needs a second unscoped read to learn it.+ Takes the caller's session, for callers that are going on to use it.+ The read itself is tenant-agnostic in the only sense that matters:+ `rooms.matrix_room_id` is unique per tenant, not globally, so a caller+ that hands in a session bound to the wrong tenant gets "not a Switch+ room" rather than another tenant's row. `_resolve_room_and_tenant` is+ the entry point for a caller that does not yet know which tenant to+ bind, and it is the one used everywhere the answer is in doubt."""cached = self._room_ids.get(transport_room_id)if cached is not None:@@ -660,17 +676,17 @@ class PostgresTransport:return room.idasync def _resolve_room_and_tenant(self, transport_room_id: str) -> tuple[str, str]:- """Like `_resolve_room`, but for a caller about to bind the tenant it- returns rather than reuse the session that resolved it.+ """The Switch room id and tenant for a transport-side id.- Opens its own short-lived, unscoped session only on a cache miss —- the same one-time bootstrap `_resolve_room` always needed. Once- cached, resolving costs nothing: no session, no query.+ Deliberately unscoped on a cache miss: this is the lookup that decides+ *which* tenant the caller is about to bind, so inheriting one would+ make it either a tautology or a false negative. Once cached, resolving+ costs nothing: no session, no query, no round trip."""cached = self._room_ids.get(transport_room_id)if cached is not None:return cached, self._room_tenants[cached]- async with self._session_factory() as session:+ async with unscoped_session(self._session_factory) as session:room_id = await self._resolve_room(session, transport_room_id)return room_id, self._room_tenants[room_id]diff --git a/core/tests/switch_core/bridges/agent/protocol/test_sweep_runtime_states_tenant_binding.py b/core/tests/switch_core/bridges/agent/protocol/test_sweep_runtime_states_tenant_binding.pyindex f20959e24..b45e231ba 100644--- a/core/tests/switch_core/bridges/agent/protocol/test_sweep_runtime_states_tenant_binding.py+++ b/core/tests/switch_core/bridges/agent/protocol/test_sweep_runtime_states_tenant_binding.py@@ -4,10 +4,13 @@ that finds them is unscoped. Each row is itself tenant-scoped, so the rest ofthe work for that row — the liveness check and the reset — binds that row'sown tenant, one at a time, rather than the whole sweep.-This pins the two things that matter about that: each row's write is bound to-its own tenant, and a row from one tenant cannot leak its binding into the-next row's work, even when the two are processed back to back in the same-sweep.+This pins three things about that: each row's write is bound to its own+tenant; a row from one tenant cannot leak its binding into the next row's+work, even when the two are processed back to back in the same sweep; and the+*whole* of a row's work is inside its binding, the emit at the end included.+That last one is not decoration — the emit is the visible half. It resolves a+mention handle and posts to a bridge, and leaving it outside the scope would+put every write a reader actually sees back on whatever was ambient."""from __future__ import annotations@@ -156,3 +159,39 @@ async def test_sweep_binds_each_row_s_own_tenant_and_does_not_leak(row_b = await store.get(session, agent_b, room_b)assert row_a is not None and row_a.state == "idle"assert row_b is not None and row_b.state == "idle"+++async def test_the_tail_of_a_row_s_work_is_still_inside_its_binding(+ session_factory: async_sessionmaker[AsyncSession],+) -> None:+ """`_mention_handle_for` and `_emit_runtime_state` run after the upsert's+ session has closed. They are still that row's work — the handle is read+ from `external_users`, and what the emit provokes is a post into the+ room — so they must still be under the row's tenant."""+ tenant_a = f"tenant-{uuid.uuid4().hex[:8]}"+ tenant_b = f"tenant-{uuid.uuid4().hex[:8]}"+ async with session_factory() as session:+ await _make_tenant(session, tenant_a)+ await _make_tenant(session, tenant_b)+ agent_a, _ = await _make_stale_runtime_state(session, tenant_id=tenant_a)+ agent_b, _ = await _make_stale_runtime_state(session, tenant_id=tenant_b)+ await session.commit()++ service = _service(session_factory)+ emitted: dict[str, str | None] = {}+ handles: dict[str, str | None] = {}++ async def _record_emit(**kwargs: object) -> None:+ emitted[str(kwargs["agent_id"])] = current_tenant_id()++ async def _record_handle(agent: object, bridge_id: object) -> None:+ handles[str(getattr(agent, "id", agent))] = current_tenant_id()++ service._emit_runtime_state = _record_emit # type: ignore[attr-defined,method-assign]+ service._mention_handle_for = _record_handle # type: ignore[attr-defined,method-assign]++ await service.sweep_runtime_states()++ assert emitted == {agent_a: tenant_a, agent_b: tenant_b}+ assert handles == {agent_a: tenant_a, agent_b: tenant_b}+ assert current_tenant_id() is Nonediff --git a/core/tests/switch_core/bridges/collaboration/test_bridge_agent_display_names.py b/core/tests/switch_core/bridges/collaboration/test_bridge_agent_display_names.pyindex 39785e159..892df5562 100644--- a/core/tests/switch_core/bridges/collaboration/test_bridge_agent_display_names.py+++ b/core/tests/switch_core/bridges/collaboration/test_bridge_agent_display_names.py@@ -99,6 +99,7 @@ def _bridge(*agents: SimpleNamespace) -> BridgeCore:"""A BridgeCore with only the two collaborators the resolver and the echocheck touch — the rest of `__init__` needs a live Matrix stack."""bridge = BridgeCore.__new__(BridgeCore)+ bridge._bridge_tenant_id = "tenant-1"bridge._agent_store = _AgentStore({a.name: a for a in agents}) # type: ignore[assignment]bridge._session_factory = _Session # type: ignore[assignment]return bridgediff --git a/core/tests/switch_core/bridges/collaboration/test_bridge_agent_icons.py b/core/tests/switch_core/bridges/collaboration/test_bridge_agent_icons.pyindex f4c95fcf7..3a0148d9f 100644--- a/core/tests/switch_core/bridges/collaboration/test_bridge_agent_icons.py+++ b/core/tests/switch_core/bridges/collaboration/test_bridge_agent_icons.py@@ -39,6 +39,7 @@ class _AgentStore:def _bridge(agents: dict[str, SimpleNamespace]) -> BridgeCore:bridge = BridgeCore.__new__(BridgeCore)+ bridge._bridge_tenant_id = "tenant-1"bridge._agent_store = _AgentStore(agents) # type: ignore[assignment]bridge._session_factory = _Session # type: ignore[assignment]return bridgediff --git a/core/tests/switch_core/bridges/collaboration/test_bridge_channel_capture.py b/core/tests/switch_core/bridges/collaboration/test_bridge_channel_capture.pyindex 2443c6bd5..a3fcffaa3 100644--- a/core/tests/switch_core/bridges/collaboration/test_bridge_channel_capture.py+++ b/core/tests/switch_core/bridges/collaboration/test_bridge_channel_capture.py@@ -49,6 +49,7 @@ async def test_ensure_channel_captures_forwards_valid_channels() -> None:_room_store=_RoomStore(),_adapter=_Adapter(),_bridge_id="bridge-1",+ _bridge_tenant_id="tenant-1",)await BridgeCore._ensure_channel_captures(bridge)@@ -79,6 +80,7 @@ async def test_ensure_channel_captures_noop_without_channels() -> None:_room_store=_RoomStore(),_adapter=_Adapter(),_bridge_id="bridge-1",+ _bridge_tenant_id="tenant-1",)await BridgeCore._ensure_channel_captures(bridge)diff --git a/core/tests/switch_core/bridges/collaboration/test_bridge_channel_migration.py b/core/tests/switch_core/bridges/collaboration/test_bridge_channel_migration.pyindex 156104360..2634a4dfc 100644--- a/core/tests/switch_core/bridges/collaboration/test_bridge_channel_migration.py+++ b/core/tests/switch_core/bridges/collaboration/test_bridge_channel_migration.py@@ -60,6 +60,8 @@ class _Session:def _make_bridge(rooms: dict[str, SimpleNamespace]) -> BridgeCore:bridge = BridgeCore.__new__(BridgeCore)bridge._bridge_id = "bridge-1"+ bridge._bridge_tenant_id = "tenant-1"+ bridge._room_tenants = {}bridge._channel_locks = {}bridge._channel_to_room = {}bridge._room_to_channel = {}diff --git a/core/tests/switch_core/bridges/collaboration/test_bridge_duplicate_room_race.py b/core/tests/switch_core/bridges/collaboration/test_bridge_duplicate_room_race.pyindex e40cca85d..5ee8f35e0 100644--- a/core/tests/switch_core/bridges/collaboration/test_bridge_duplicate_room_race.py+++ b/core/tests/switch_core/bridges/collaboration/test_bridge_duplicate_room_race.py@@ -46,6 +46,7 @@ def _make_bridge(**overrides: Any) -> BridgeCore:bridge._room_tenants = {}bridge._channel_locks = {}bridge._bridge_id = "bridge-1"+ bridge._bridge_tenant_id = "tenant-1"bridge._bridge_display_name = "Switch"bridge._adapter = _Adapter() # type: ignore[assignment]bridge._room_service = SimpleNamespace(create_room=create_room) # type: ignore[assignment]@@ -188,6 +189,7 @@ async def test_adopt_existing_room_registers_mapping() -> None:bridge._room_to_channel = {}bridge._room_tenants = {}bridge._bridge_id = "bridge-1"+ bridge._bridge_tenant_id = "tenant-1"bridge._session_factory = _Session # type: ignore[assignment]bridge._room_store = _RoomStore() # type: ignore[assignment]diff --git a/core/tests/switch_core/bridges/collaboration/test_bridge_inbound_tenant_binding.py b/core/tests/switch_core/bridges/collaboration/test_bridge_inbound_tenant_binding.pynew file mode 100644index 000000000..099bf75a4--- /dev/null+++ b/core/tests/switch_core/bridges/collaboration/test_bridge_inbound_tenant_binding.py@@ -0,0 +1,212 @@+"""An inbound platform event acts under the tenant it belongs to (CHOO-2623).++`_traced` is the one choke point every inbound handler goes through, and it is+where the tenant is bound: the room's, when the channel already maps to one;+the bridge's, when it does not and the handler is about to create the room.++Two properties fall out of doing it there, and both are pinned below.++**A room created after the bridge started resolves like any other.** The+channel map is not only loaded at boot — `add_room_mapping` is called whenever+a room is created, adopted or moved onto a channel — so it, and not the boot+load, is what has to carry the tenant. It does, which is why the inbound path+reads no row at all.++**The platform stops mattering.** Mattermost's websocket runs on an OS thread+and hands its coroutine over with `asyncio.run_coroutine_threadsafe`, which+starts it in an *empty* context; Slack's dispatches from a task that inherited+whatever created it. Binding at the choke point rather than depending on what+the handler inherits means both land in the same tenant, so which platform a+message arrived on can no longer decide where its room goes.+"""++from __future__ import annotations++import asyncio+import uuid+from types import SimpleNamespace+from typing import Any++import pytest++from switch_core.bridges.collaboration.bridge_core import BridgeCore+from switch_core.tenant_context import current_tenant_id, tenant_scope++BRIDGE_TENANT = "tenant-bridge"+ROOM_TENANT = "tenant-room"+++class _ExplodingSessionFactory:+ """A session factory that fails if anything opens a session.++ The inbound path must resolve a tenant from what it already holds. A read+ here would not merely be slow: it would run under whatever tenant is bound+ at the time, which on this path is the question being asked.+ """++ def __call__(self) -> Any:+ raise AssertionError(+ "the inbound path opened a database session to resolve a tenant; "+ "add_room_mapping is supposed to have recorded it already"+ )+++def _bridge() -> BridgeCore:+ bridge = BridgeCore.__new__(BridgeCore)+ bridge._bridge_id = "bridge-1"+ bridge._bridge_tenant_id = BRIDGE_TENANT+ bridge._bridge_type = "mattermost"+ bridge._channel_to_room = {}+ bridge._room_to_channel = {}+ bridge._room_tenants = {}+ bridge._session_factory = _ExplodingSessionFactory() # type: ignore[assignment]+ return bridge+++def _event(channel_id: str) -> SimpleNamespace:+ return SimpleNamespace(channel_id=channel_id)+++async def test_a_room_created_after_the_bridge_started_resolves_its_tenant() -> None:+ """The defect this replaces: `add_room_mapping` filled the channel maps+ and not the tenant map, so every room created after boot missed the cache+ and fell into a database read under whatever was ambient."""+ bridge = _bridge()+ seen: list[str | None] = []++ async def _handler(event: object) -> None:+ seen.append(current_tenant_id())++ traced = bridge._traced(_handler)++ # Exactly what room creation does once the room exists (room_service),+ # long after `_load_channel_map` ran.+ bridge.add_room_mapping("room-new", "!new:test", "C-new", ROOM_TENANT)++ await traced(_event("C-new"))++ assert seen == [ROOM_TENANT]+++async def test_an_unmapped_channel_binds_the_bridges_own_tenant() -> None:+ """Auto-room-creation. There is no room to ask, but the answer is not+ ambient either: a room this bridge creates belongs to the tenant that owns+ the bridge, and the schema agrees — `rooms` keys to+ `collaboration_bridges` on `tenant_id`."""+ bridge = _bridge()+ seen: list[str | None] = []++ async def _handler(event: object) -> None:+ seen.append(current_tenant_id())++ await bridge._traced(_handler)(_event("C-unknown"))++ assert seen == [BRIDGE_TENANT]+++async def test_the_binding_does_not_outlive_the_event() -> None:+ bridge = _bridge()+ bridge.add_room_mapping("room-1", "!one:test", "C1", ROOM_TENANT)++ async def _handler(event: object) -> None:+ assert current_tenant_id() == ROOM_TENANT++ await bridge._traced(_handler)(_event("C1"))++ assert current_tenant_id() is None+++async def test_removing_a_mapping_forgets_the_tenant_with_it() -> None:+ """Otherwise the tenant map is the one part of the mapping that only ever+ grows, and a room id reused after a bridge move would resolve to a stale+ answer with nothing to correct it."""+ bridge = _bridge()+ bridge.add_room_mapping("room-1", "!one:test", "C1", ROOM_TENANT)+ bridge.remove_room_mapping("room-1", "!one:test")++ assert bridge._room_tenants == {}+++async def test_a_thread_dispatched_event_lands_in_the_same_tenant() -> None:+ """Mattermost, in miniature.++ `asyncio.run_coroutine_threadsafe` starts the coroutine in an empty+ context — nothing the bridge's task had bound reaches it. Under the model+ this replaces, that made auto-created rooms land in tenant zero on+ Mattermost and in the bridge's tenant everywhere else: a per-platform+ lottery. Both dispatch styles now agree.+ """+ bridge = _bridge()+ bridge.add_room_mapping("room-1", "!one:test", "C1", ROOM_TENANT)+ seen: list[str | None] = []++ async def _handler(event: object) -> None:+ seen.append(current_tenant_id())++ traced = bridge._traced(_handler)+ loop = asyncio.get_running_loop()++ # Dispatched the way the Mattermost adapter does it, from a thread with no+ # context of its own, and the way every other adapter does it, inline.+ await asyncio.wrap_future(+ asyncio.run_coroutine_threadsafe(traced(_event("C1")), loop)+ )+ await traced(_event("C1"))++ assert seen == [ROOM_TENANT, ROOM_TENANT]+++class TestAPuppetIsMintedInTheBridgesTenant:+ """A puppet is per-bridge and reused for every room the person it stands+ for ever speaks in, so it cannot be stamped with the tenant of whichever+ room happened to trigger it first. The rooms a bridge carries are all in+ its tenant (`rooms` keys to `collaboration_bridges` on `tenant_id`), so+ the bridge's is the only answer that holds for all of them.+ """++ async def test_the_identity_is_created_under_the_bridges_tenant(self) -> None:+ bridge = BridgeCore.__new__(BridgeCore)+ bridge._bridge_id = "bridge-1"+ bridge._bridge_tenant_id = BRIDGE_TENANT+ bridge._bridge_type = "mattermost"+ bridge._puppet_locks = {}+ bridge._user_puppets = {}+ bridge._puppet_matrix_ids = set()+ seen: list[str | None] = []++ async def _locked(external_user_id: str, external_username: str) -> str:+ seen.append(current_tenant_id())+ return "client-1"++ bridge._create_puppet_locked = _locked # type: ignore[assignment]++ # Reached from inside an inbound event for a room — the binding the+ # puppet must *not* adopt, were the two ever to differ.+ with tenant_scope(ROOM_TENANT):+ assert await bridge._create_puppet("U1", "alice") == "client-1"++ assert seen == [BRIDGE_TENANT]++ async def test_a_cached_puppet_is_returned_without_reminting(self) -> None:+ bridge = BridgeCore.__new__(BridgeCore)+ bridge._bridge_tenant_id = BRIDGE_TENANT+ bridge._puppet_locks = {}+ bridge._user_puppets = {"U1": "client-1"}++ # The cache check lives inside the locked half, so this proves the+ # split did not move it out from under the lock.+ bridge._create_puppet_locked = BridgeCore._create_puppet_locked.__get__(bridge) # type: ignore[assignment]++ assert await bridge._create_puppet("U1", "alice") == "client-1"++[email protected]("tenant", [BRIDGE_TENANT, ROOM_TENANT])+async def test_the_mapping_records_whatever_tenant_it_is_given(tenant: str) -> None:+ """`add_room_mapping` does not guess. Its caller has the room row in hand+ and passes the row's tenant, so a room whose tenant somehow differs from+ its bridge's is still handled under its own."""+ bridge = _bridge()+ room_id = f"room-{uuid.uuid4().hex[:8]}"+ bridge.add_room_mapping(room_id, f"!{room_id}:test", "C1", tenant)++ assert await bridge._room_tenant(room_id) == tenantdiff --git a/core/tests/switch_core/bridges/collaboration/test_bridge_mention_resolution.py b/core/tests/switch_core/bridges/collaboration/test_bridge_mention_resolution.pyindex 0f2ae6a9c..648c0e119 100644--- a/core/tests/switch_core/bridges/collaboration/test_bridge_mention_resolution.py+++ b/core/tests/switch_core/bridges/collaboration/test_bridge_mention_resolution.py@@ -1,5 +1,6 @@from __future__ import annotations+import functoolsfrom collections.abc import AsyncIteratorfrom contextlib import asynccontextmanagerfrom types import SimpleNamespace@@ -64,6 +65,7 @@ def _loading_bridge(adapter: SlackAdapter, users: list[SimpleNamespace]) -> Any:return SimpleNamespace(_adapter=adapter,_bridge_id=BRIDGE_ID,+ _bridge_tenant_id="tenant-1",_session_factory=_session_factory(),_external_user_store=SimpleNamespace(get_by_bridge=_get_by_bridge),_client_store=SimpleNamespace(get=_get_client),@@ -138,6 +140,7 @@ async def test_new_puppet_is_mentionable_without_waiting_for_a_restart() -> None_adapter=adapter,_bridge_id=BRIDGE_ID,_bridge_type="slack",+ _bridge_tenant_id="tenant-1",_session_factory=_session_factory(),_puppet_locks={},_user_puppets={},@@ -146,6 +149,9 @@ async def test_new_puppet_is_mentionable_without_waiting_for_a_restart() -> None_client_lifecycle=SimpleNamespace(create_and_start=_create_and_start),_external_user_store=SimpleNamespace(create=_create),)+ bridge._create_puppet_locked = functools.partial(+ BridgeCore._create_puppet_locked, bridge+ )await BridgeCore._create_puppet(bridge, "U789", "new.person")diff --git a/core/tests/switch_core/bridges/collaboration/test_bridge_no_agents_notice.py b/core/tests/switch_core/bridges/collaboration/test_bridge_no_agents_notice.pyindex 19d4f50ad..d681b37f7 100644--- a/core/tests/switch_core/bridges/collaboration/test_bridge_no_agents_notice.py+++ b/core/tests/switch_core/bridges/collaboration/test_bridge_no_agents_notice.py@@ -55,7 +55,9 @@ def _fake_bridge(*, agent_ids: list[str], slash_hint: str | None = None): # noq) -> list[str]:return agent_ids- def add_room_mapping(room_id: str, matrix_room_id: str, channel_id: str) -> None:+ def add_room_mapping(+ room_id: str, matrix_room_id: str, channel_id: str, tenant_id: str+ ) -> None:passasync def _adopt_existing_room(channel_id: str) -> tuple[str, str] | None:diff --git a/core/tests/switch_core/bridges/collaboration/test_lifecycle_remove.py b/core/tests/switch_core/bridges/collaboration/test_lifecycle_remove.pyindex b8b405ed5..517b67b37 100644--- a/core/tests/switch_core/bridges/collaboration/test_lifecycle_remove.py+++ b/core/tests/switch_core/bridges/collaboration/test_lifecycle_remove.py@@ -11,7 +11,13 @@ from switch_core.bridges.collaboration.lifecycle_service import (CollaborationBridgeLifecycleService,_bridge_client_localpart,)-from switch_core.db.models import Client, CollaborationBridge, ExternalUser, Room+from switch_core.db.models import (+ TENANT_ZERO_ID,+ Client,+ CollaborationBridge,+ ExternalUser,+ Room,+)from switch_core.db.stores.client_store import ClientStorefrom switch_core.db.stores.collaboration_bridge_store import CollaborationBridgeStorefrom switch_core.db.stores.external_user_store import ExternalUserStore@@ -246,9 +252,9 @@ async def test_a_starting_bridge_is_recorded_in_the_rooms_it_carries(elsewhere_id = await _make_bridged_room(session, bridge_id=other_bridge_id)await session.commit()- await service._record_bridge_memberships(bridge_id, client_id)+ await service._record_bridge_memberships(bridge_id, TENANT_ZERO_ID, client_id)# Again, because a bridge starts more than once.- await service._record_bridge_memberships(bridge_id, client_id)+ await service._record_bridge_memberships(bridge_id, TENANT_ZERO_ID, client_id)async with session_factory() as session:assert await RoomStore().get_client_ids(session, room_id) == [client_id]diff --git a/core/tests/switch_core/bridges/collaboration/test_lifecycle_tenant_binding.py b/core/tests/switch_core/bridges/collaboration/test_lifecycle_tenant_binding.pyindex 55ff174b9..70e204091 100644--- a/core/tests/switch_core/bridges/collaboration/test_lifecycle_tenant_binding.py+++ b/core/tests/switch_core/bridges/collaboration/test_lifecycle_tenant_binding.py@@ -1,31 +1,39 @@-"""`CollaborationBridgeLifecycleService.start_all` (CHOO-2623): starting every-bridge at boot has no request behind it, and it fans out across every-tenant's bridges in one pass — so the read that finds them has to be-unscoped, and each bridge's own tenant is what gets bound, not the whole-sweep. `start` spawns the bridge's long-lived task while that binding is-still active, so the task keeps it for its own life (an asyncio task-snapshots the context it was created under).--This does not exercise a real bridge — `start` here is stubbed to record what-tenant was bound when it was called, which is the only thing `start_all`-itself is responsible for getting right.+"""A bridge runs under its own tenant, whoever started it (CHOO-2623).++The rule these pin: **nothing is ambient.** A bridge is started from two+places — boot, with no tenant bound, and an HTTP request that edited its+config, with the *requesting operator's* tenant bound — and an `asyncio.Task`+snapshots the contextvars of whoever created it. So the tenant a bridge acts+under must never be the one that happened to be bound when its task was made.++`start` reads the bridge's own row unscoped to learn its tenant, hands that+value to the task, and the task unbinds before doing anything. Each unit of+work then binds the tenant it derived from a row: the bridge's for the+bridge's own startup, the room's for anything room-scoped. `start_all` binds+nothing at all, because there is nothing left for it to bind."""from __future__ import annotations+import asyncioimport uuid+from typing import Anyfrom unittest.mock import MagicMock+import pytest+from sqlalchemy import selectfrom sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker+from switch_core.bridges.collaboration.adapter import CollaborationAdapterfrom switch_core.bridges.collaboration.lifecycle_service import (CollaborationBridgeLifecycleService,)-from switch_core.db.models import Client, CollaborationBridge, Tenant+from switch_core.bridges.collaboration.models import BridgeConnectionConfig+from switch_core.db.models import Client, ClientRoom, CollaborationBridge, Room, Tenantfrom switch_core.db.stores.client_store import ClientStorefrom switch_core.db.stores.collaboration_bridge_store import CollaborationBridgeStorefrom switch_core.db.stores.room_store import RoomStore-from switch_core.tenant_context import current_tenant_id+from switch_core.tenant_context import current_tenant_id, tenant_scopedef _service(@@ -47,12 +55,40 @@ def _service()+class _StubAdapter(CollaborationAdapter):+ """Concrete only so `start` can build one; no platform call is made."""++ def __init__(self, *, config: Any) -> None:+ self._config = config++ async def start(self, *a: Any, **k: Any) -> Any: ...+ async def stop(self, *a: Any, **k: Any) -> Any: ...+ async def send_message(self, *a: Any, **k: Any) -> Any: ...+ async def send_typing(self, *a: Any, **k: Any) -> Any: ...+ async def update_message(self, *a: Any, **k: Any) -> Any: ...+ async def delete_message(self, *a: Any, **k: Any) -> Any: ...+ async def create_channel(self, *a: Any, **k: Any) -> Any: ...+ async def get_channel_type(self, *a: Any, **k: Any) -> Any: ...+ async def get_channel_agent_names(self, *a: Any, **k: Any) -> Any: ...+ async def add_agents_to_channel(self, *a: Any, **k: Any) -> Any: ...+ async def add_users_to_channel(self, *a: Any, **k: Any) -> Any: ...+ async def create_agent_identity(self, *a: Any, **k: Any) -> Any: ...+ async def remove_agent_identity(self, *a: Any, **k: Any) -> Any: ...+ def translate_inbound(self, *a: Any, **k: Any) -> Any: ...+ def translate_outbound(self, *a: Any, **k: Any) -> Any: ...+++class _StubConfig(BridgeConnectionConfig):+ pass++async def _make_tenant(session: AsyncSession, tenant_id: str) -> None:session.add(Tenant(id=tenant_id, slug=tenant_id, name=tenant_id))await session.flush()-async def _make_bridge(session: AsyncSession, *, tenant_id: str) -> str:+async def _make_bridge(session: AsyncSession, *, tenant_id: str) -> tuple[str, str]:+ """A bridge row and its client, in `tenant_id`. Returns (bridge, client)."""client = Client(tenant_id=tenant_id,matrix_user_id=f"@bridge-{uuid.uuid4().hex[:8]}:test",@@ -70,19 +106,22 @@ async def _make_bridge(session: AsyncSession, *, tenant_id: str) -> str:)session.add(bridge)await session.flush()- return bridge.id+ return bridge.id, client.id-async def test_start_all_binds_each_bridge_s_own_tenant_and_does_not_leak(+async def test_start_all_binds_nothing_around_starting_a_bridge(session_factory: async_sessionmaker[AsyncSession],) -> None:+ """The enumeration is unscoped and stays that way. Binding a tenant here+ would only choose what each bridge's task snapshots, which is exactly the+ dependency the design removed — `start` derives the tenant from the row."""tenant_a = f"tenant-{uuid.uuid4().hex[:8]}"tenant_b = f"tenant-{uuid.uuid4().hex[:8]}"async with session_factory() as session:await _make_tenant(session, tenant_a)await _make_tenant(session, tenant_b)- bridge_a = await _make_bridge(session, tenant_id=tenant_a)- bridge_b = await _make_bridge(session, tenant_id=tenant_b)+ bridge_a, _ = await _make_bridge(session, tenant_id=tenant_a)+ bridge_b, _ = await _make_bridge(session, tenant_id=tenant_b)await session.commit()service = _service(session_factory)@@ -93,28 +132,25 @@ async def test_start_all_binds_each_bridge_s_own_tenant_and_does_not_leak(service.start = _fake_start # type: ignore[method-assign]- # Nothing bound going in, and nothing bound coming out: start_all is- # itself reached with no request behind it.assert current_tenant_id() is Noneawait service.start_all()assert current_tenant_id() is None- assert seen == {bridge_a: tenant_a, bridge_b: tenant_b}+ assert seen == {bridge_a: None, bridge_b: None}-async def test_a_failing_bridge_still_releases_its_tenant_for_the_next_one(+async def test_a_failing_bridge_leaves_nothing_bound_for_the_next_one(session_factory: async_sessionmaker[AsyncSession],) -> None:- """start_all logs and continues past a bridge that fails to start- (bridge_core.py's own behaviour); the tenant binding must not survive- the exception either, or the next bridge in the loop inherits it."""+ """start_all logs and continues past a bridge that fails to start; that+ must not leave the loop in a different state than it began in."""tenant_a = f"tenant-{uuid.uuid4().hex[:8]}"tenant_b = f"tenant-{uuid.uuid4().hex[:8]}"async with session_factory() as session:await _make_tenant(session, tenant_a)await _make_tenant(session, tenant_b)- bridge_a = await _make_bridge(session, tenant_id=tenant_a)- bridge_b = await _make_bridge(session, tenant_id=tenant_b)+ bridge_a, _ = await _make_bridge(session, tenant_id=tenant_a)+ bridge_b, _ = await _make_bridge(session, tenant_id=tenant_b)await session.commit()service = _service(session_factory)@@ -129,5 +165,186 @@ async def test_a_failing_bridge_still_releases_its_tenant_for_the_next_one(await service.start_all()- assert seen == {bridge_a: tenant_a, bridge_b: tenant_b}+ assert seen == {bridge_a: None, bridge_b: None}assert current_tenant_id() is None+++async def test_start_hands_the_task_the_bridges_tenant_not_the_callers(+ session_factory: async_sessionmaker[AsyncSession],+) -> None:+ """The restart path (`gateway/collaborations.py` edits a connection and+ calls `restart`) reaches `start` with the requesting operator's tenant+ bound. The tenant the bridge is then run under has to come off the bridge+ row, not out of the request."""+ bridge_tenant = f"tenant-{uuid.uuid4().hex[:8]}"+ caller_tenant = f"tenant-{uuid.uuid4().hex[:8]}"+ async with session_factory() as session:+ await _make_tenant(session, bridge_tenant)+ await _make_tenant(session, caller_tenant)+ bridge_id, _ = await _make_bridge(session, tenant_id=bridge_tenant)+ await session.commit()++ service = _service(session_factory)+ service.register_adapter("mattermost", _StubAdapter, _StubConfig)+ handed: list[str] = []++ async def _fake_run(bridge_id: str, tenant_id: str, *_: object) -> None:+ handed.append(tenant_id)++ service._run_bridge = _fake_run # type: ignore[method-assign]++ with tenant_scope(caller_tenant):+ await service.start(bridge_id)+ # `start` spawns the task and returns; let it reach its first line.+ await asyncio.sleep(0)++ await service.stop(bridge_id)++ assert handed == [bridge_tenant]+++async def test_the_bridge_task_unbinds_and_then_binds_per_unit_of_work(+ session_factory: async_sessionmaker[AsyncSession],+) -> None:+ """The task body itself, created from a foreign tenant's context.++ Three things at once, because they are one rule: the membership rows the+ bridge records land in the bridge's tenant (not the creator's, which the+ composite foreign keys would reject outright); the bridge's own startup+ sees nothing bound, so anything it does has to bind for itself; and the+ client loop that runs until shutdown sees nothing bound either, leaving+ each delivery to bind the room it is for.+ """+ bridge_tenant = f"tenant-{uuid.uuid4().hex[:8]}"+ caller_tenant = f"tenant-{uuid.uuid4().hex[:8]}"+ async with session_factory() as session:+ await _make_tenant(session, bridge_tenant)+ await _make_tenant(session, caller_tenant)+ bridge_id, client_id = await _make_bridge(session, tenant_id=bridge_tenant)+ room = Room(+ tenant_id=bridge_tenant,+ matrix_room_id=f"!room-{uuid.uuid4().hex[:8]}:test",+ name="a bridged room",+ description="",+ bridge_id=bridge_id,+ external_channel_id="C1",+ )+ session.add(room)+ await session.commit()+ room_id = room.id++ service = _service(session_factory)+ seen: dict[str, str | None] = {}++ class _Core:+ async def start(self) -> None:+ seen["core"] = current_tenant_id()++ class _Client:+ client_id = ""++ async def start(self) -> None:+ seen["client"] = current_tenant_id()++ bridge_client = _Client()+ bridge_client.client_id = client_id++ leaked: list[str | None] = []+ with tenant_scope(caller_tenant):+ await service._run_bridge(+ bridge_id,+ bridge_tenant,+ _Core(), # type: ignore[arg-type]+ bridge_client, # type: ignore[arg-type]+ )+ leaked.append(current_tenant_id())++ async with session_factory() as session:+ rows = (+ (+ await session.execute(+ select(ClientRoom.tenant_id).where(ClientRoom.room_id == room_id)+ )+ )+ .scalars()+ .all()+ )++ assert rows == [bridge_tenant], (+ "the bridge recorded its membership under the tenant of whoever "+ "started it rather than its own"+ )+ assert seen == {"core": None, "client": None}+ assert leaked == [caller_tenant], (+ "the task's unbinding escaped it and cleared its creator's context"+ )+++async def test_a_host_resource_conflict_is_looked_for_across_every_tenant(+ session_factory: async_sessionmaker[AsyncSession],+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """Two tenants cannot share a Teams listen port or a Slack workspace: the+ resource belongs to the host and the platform, not to a tenant. So the+ check that refuses the second claimant has to see the first even when it+ belongs to someone else — narrowing it to the caller's tenant would make+ it miss precisely the case it exists for.++ The conflict itself is asserted, and so is the tenant bound over the read+ that finds it. Both, because today nothing filters by tenant: no policy+ has landed, so a scoped read would still return every row and the+ conflict alone would pass either way. The binding is the part that will+ decide the answer once the policies bite.+ """+ incumbent_tenant = f"tenant-{uuid.uuid4().hex[:8]}"+ newcomer_tenant = f"tenant-{uuid.uuid4().hex[:8]}"+ async with session_factory() as session:+ await _make_tenant(session, incumbent_tenant)+ await _make_tenant(session, newcomer_tenant)+ client = Client(+ tenant_id=incumbent_tenant,+ matrix_user_id=f"@bridge-{uuid.uuid4().hex[:8]}:test",+ display_name="bridge client",+ type="bridge",+ )+ session.add(client)+ await session.flush()+ session.add(+ CollaborationBridge(+ tenant_id=incumbent_tenant,+ type="teams",+ display_name="Their Teams",+ client_id=client.id,+ status="active",+ connection_config={"listen_port": 3979},+ )+ )+ await session.commit()++ class _PortHoldingAdapter(_StubAdapter):+ @staticmethod+ def exclusive_resource(config: dict[str, Any]) -> str | None:+ port = config.get("listen_port")+ return f"port:{port}" if port else None++ seen: list[str | None] = []+ original = CollaborationBridgeStore.get_all++ async def _spy(self, session): # type: ignore[no-untyped-def]+ seen.append(current_tenant_id())+ return await original(self, session)++ monkeypatch.setattr(CollaborationBridgeStore, "get_all", _spy)++ service = _service(session_factory)+ service.register_adapter("teams", _PortHoldingAdapter, _StubConfig)++ with tenant_scope(newcomer_tenant):+ with pytest.raises(ValueError, match="already uses port:3979"):+ await service._reject_resource_conflict("teams", {"listen_port": 3979})++ assert seen == [None], (+ "the conflict check read the stored bridges under the caller's "+ "tenant; under row-level security it would not have seen the "+ "incumbent and would have let both claim the port"+ )diff --git a/core/tests/switch_core/db/test_session_scope.py b/core/tests/switch_core/db/test_session_scope.pyindex d8b038d5c..dd710ae6f 100644--- a/core/tests/switch_core/db/test_session_scope.py+++ b/core/tests/switch_core/db/test_session_scope.py@@ -5,17 +5,21 @@ named ways background code may open a session with no request behind it.session, so what these tests pin is the composition — bound inside the block,released on the way out, even on an exception — rather than the bindingmechanics themselves, which `test_tenant_session_hook.py` already covers.-`unscoped_session` does nothing at all beyond calling the factory; it is-tested here for what it does *not* do — bind anything — and its callers are-pinned separately, in `test_unscoped_session_allowlist.py`.+`unscoped_session` is tested here for the one thing its name promises and its+callers depend on: that a session opened through it has no tenant set, no+matter what the caller had bound. Its callers are pinned separately, in+`test_unscoped_session_allowlist.py`."""from __future__ import annotations+import uuid+import pytest-from sqlalchemy import text+from sqlalchemy import select, textfrom sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker+from switch_core.db.models import Room, Tenantfrom switch_core.db.session_scope import tenant_session, unscoped_sessionfrom switch_core.tenant_context import current_tenant_id, tenant_scope@@ -87,18 +91,31 @@ class TestUnscopedSession:assert current_tenant_id() is Noneassert await _current_setting(session) is None- async def test_it_neither_binds_nor_clears_an_outer_tenant(+ async def test_it_unbinds_an_outer_tenant_for_the_duration(self, session_factory: async_sessionmaker[AsyncSession]) -> None:- """It is not a "no tenant" guarantee, only a "no new binding" one —- the docstring is explicit that this is not force-unscoped. A caller- already inside a bound context keeps seeing that context's tenant."""+ """The whole contract. A caller already inside a bound context — a+ request, an outer `tenant_scope`, a task that inherited one — still+ gets a session with nothing set, because otherwise "unscoped" would+ mean "scoped to whoever happened to call me" and the allowlist that+ pins these call sites would be certifying a cross-tenant read that+ never happens."""with tenant_scope(TENANT_A):async with unscoped_session(session_factory) as session:- assert current_tenant_id() == TENANT_A- assert await _current_setting(session) == TENANT_A+ assert current_tenant_id() is None+ assert await _current_setting(session) is None+ assert current_tenant_id() == TENANT_Aassert current_tenant_id() is None+ async def test_an_exception_still_restores_the_outer_tenant(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ with tenant_scope(TENANT_A):+ with pytest.raises(RuntimeError, match="boom"):+ async with unscoped_session(session_factory):+ raise RuntimeError("boom")+ assert current_tenant_id() == TENANT_A+async def test_current_tenant_id_is_unchanged_after_the_block(self, session_factory: async_sessionmaker[AsyncSession]) -> None:@@ -106,3 +123,38 @@ class TestUnscopedSession:async with unscoped_session(session_factory):passassert current_tenant_id() is None++ async def test_it_reads_rows_from_two_tenants_with_one_of_them_bound(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """What the callers actually rely on, stated in rows rather than in+ contextvars: a sweep or an enumeration reached from inside a bound+ context still sees the whole deployment.++ Today no policy filters anything, so the `set_config` assertion is+ what carries the weight — it is the value the policies will read once+ they land. Both are asserted so this test keeps meaning the same thing+ on either side of that change.+ """+ tenant_a = f"tenant-{uuid.uuid4().hex[:8]}"+ tenant_b = f"tenant-{uuid.uuid4().hex[:8]}"+ async with session_factory() as session:+ for tenant_id in (tenant_a, tenant_b):+ session.add(Tenant(id=tenant_id, slug=tenant_id, name=tenant_id))+ await session.flush()+ for tenant_id in (tenant_a, tenant_b):+ session.add(+ Room(+ tenant_id=tenant_id,+ matrix_room_id=f"!{tenant_id}:test",+ name=tenant_id,+ description="",+ )+ )+ await session.commit()++ with tenant_scope(tenant_a):+ async with unscoped_session(session_factory) as session:+ assert await _current_setting(session) is None+ rows = (await session.execute(select(Room.tenant_id))).scalars().all()+ assert {tenant_a, tenant_b} <= set(rows)diff --git a/core/tests/switch_core/db/test_unscoped_session_allowlist.py b/core/tests/switch_core/db/test_unscoped_session_allowlist.pyindex 865c94181..8f4329d0a 100644--- a/core/tests/switch_core/db/test_unscoped_session_allowlist.py+++ b/core/tests/switch_core/db/test_unscoped_session_allowlist.py@@ -1,18 +1,25 @@-"""`unscoped_session` (`db/session_scope.py`) is the fail-open hatch: a session-with no tenant bound at all, for the handful of things that are legitimately-cross-tenant — a sweep or lifecycle enumeration reading every row before-fanning out per-row work, and startup seeding that runs before any tenant can-be said to exist.--Nothing stops a query on a session it opens from reading across every tenant-there is, so its callers are the audit surface for that risk. This test pins-them to an explicit allowlist, derived from the source tree rather than-imports, so a module that only calls it conditionally or inside a string is-still caught. A new module failing here is not a bug in the test: it means-someone reached for the cross-tenant escape hatch, and either that is a-deliberate, reviewable choice — in which case add the module to-`_ALLOWED_MODULES` in the same change, saying why in the commit — or it is-not, in which case use `tenant_session` instead.+"""What may open a database session without a tenant, and who is allowed to.++Two audit surfaces, and the second is the bigger one.++**`unscoped_session`** (`db/session_scope.py`) is the declared fail-open hatch:+it unbinds for the duration of the block, so a query on it reads across every+tenant whether or not the caller had one bound. Its callers are named here.++**A raw `session_factory()` call** is the undeclared one. It inherits whatever+is ambient — the request's tenant on the request path, and *nothing at all* in+background code, since the long-lived tasks deliberately unbind (see+`tenant_context.no_tenant`). So a raw call in background code is unscoped in+fact while saying nothing about it, which is strictly worse than the hatch+that announces itself. There are ~197 of them across the modules below; that+is the number this design has to work down, and pinning the module list is how+a new one becomes a decision rather than a default.++A module failing either check is not a bug in the test. It means someone+opened a session without saying which tenant it is for, and either that is+deliberate and reviewable — add the module below, saying why in the commit —+or it is not, in which case use `tenant_session` and bind the tenant of the+row the work is acting on."""from __future__ import annotations@@ -23,29 +30,81 @@ from pathlib import Pathimport switch_core# Every module allowed to call `unscoped_session`. Keep this short: it is the-# whole list of places in the process that may read across every tenant.+# whole list of places in the process that read across every tenant on purpose._ALLOWED_MODULES = {# Startup seeding: the admin user and the agent-registration bootstrap# owner/key are created before any tenant can be said to exist."switch_core.main",# Reconciling every room's client membership at startup fans out across- # every tenant's rooms; each room's own tenant is bound for its own work.+ # every tenant's rooms; and `_load_room` is the bootstrap read that says+ # which tenant a room is in before that tenant is bound."switch_core.room_service",- # The runtime-state sweep reads every tenant's stale rows in one pass;- # each row's own tenant is bound before anything is done with it.+ # The runtime-state sweep reads every tenant's stale rows in one pass, and+ # `register_agent_with_token` resolves a credential by its globally unique+ # hash — the read that produces a tenant rather than one that uses it.+ "switch_core.bridges.agent.protocol.service",+ # Starting a bridge reads its own row to learn its tenant, from boot (with+ # nothing bound) and from a request (with the wrong one bound); and+ # `_reject_resource_conflict` must span tenants by definition, since two+ # tenants claiming one Slack workspace is the collision it exists to catch.+ "switch_core.bridges.collaboration.lifecycle_service",+ # `_room_tenant`'s fallback: which tenant is this room in, asked when the+ # answer is not already cached alongside the channel mapping.+ "switch_core.bridges.collaboration.bridge_core",+ # Same as the bridge lifecycle, for server-side connectors.+ "switch_core.bridges.agent.server_connectors.lifecycle",+ # Enumerating every tenant's clients at boot.+ "switch_core.clients.client_lifecycle_service",+ # A client's own task binds nothing, so resolving which agent it is — by+ # globally unique client id — cannot be scoped to a guess.+ "switch_core.clients.agent_client",+ # `joined_rooms` (which rooms is this client in) and `_resolve_room_and_+ # tenant` (which room, and so which tenant, is this transport id) are both+ # lookups that produce a tenant rather than consume one.+ "switch_core.transport.postgres",+}++# Every module allowed to open a session straight from the factory. Unlike the+# list above this one is not short, and is not meant to be permanent: it is an+# inventory of what has not been converted yet, plus the request-path modules+# where inheriting the authenticated request's tenant is the correct answer.+_RAW_SESSION_FACTORY_MODULES = {+ # ── Request path: the session inherits the authenticated caller's tenant,+ # bound by the auth dependency before the endpoint body runs. Correct as+ # it stands; these are not to-dos.+ "switch_core.gateway.auth",+ "switch_core.gateway.dependencies",+ "switch_core.bridges.agent.auth",+ "switch_core.bridges.agent.dependencies",+ "switch_core.bridges.agent.operations.context",+ "switch_core.bridges.agent.operations.definitions",+ "switch_core.bridges.agent.mediation",+ # ── Reached only from inside a unit of work that has already bound the+ # tenant of the row it is acting on — an inbound bridge event, a delivery,+ # a sweep row, an authenticated agent operation."switch_core.bridges.agent.protocol.service",- # Starting every collaboration bridge at boot reads every tenant's rows in- # one pass; each bridge's own tenant is bound before it is started.+ "switch_core.bridges.agent.commands",+ "switch_core.bridges.collaboration.bridge_core","switch_core.bridges.collaboration.lifecycle_service",- # Same as above, for server-side connectors."switch_core.bridges.agent.server_connectors.lifecycle",- # Same as above, for the generic client registry (agent and admin- # clients) started at boot.+ "switch_core.clients.agent_client",+ "switch_core.clients.admin_client","switch_core.clients.client_lifecycle_service",+ "switch_core.provisioning.postgres",+ "switch_core.room_service",+ "switch_core.transport.postgres",+ # ── Deployment-level startup, with no tenant to inherit and none bound.+ # Rows these write land in tenant zero via the model default. Correct+ # while one tenant exists; both need revisiting before a second.+ "switch_core.main",+ "switch_core.rooms_yaml",}_PACKAGE_ROOT = Path(switch_core.__file__).resolve().parent+# The module that defines the helpers, not a caller of them.+_DEFINITION = _PACKAGE_ROOT / "db" / "session_scope.py"+def _module_name(path: Path) -> str:relative = path.relative_to(_PACKAGE_ROOT.parent)@@ -55,41 +114,89 @@ def _module_name(path: Path) -> str:return ".".join(parts)-def _calls_unscoped_session(path: Path) -> bool:- """Whether `path` contains a call to a function literally named- `unscoped_session`, anywhere — a call, an alias, a re-export."""- tree = ast.parse(path.read_text(), filename=str(path))+def _local_names_for(tree: ast.AST, imported: str) -> set[str]:+ """Every local name `imported` is reachable under in this module.++ Its own name, plus any alias it was imported as. Without this the+ detectors match a spelling rather than a function, and one `import … as`+ walks straight past them.+ """+ names = {imported}+ for node in ast.walk(tree):+ if isinstance(node, ast.ImportFrom):+ for alias in node.names:+ if alias.name == imported and alias.asname:+ names.add(alias.asname)+ return names+++def _called_names(tree: ast.AST) -> set[str]:+ """The name of every function called anywhere, attribute access included.++ `foo()` yields "foo"; `self._session_factory()` yields "_session_factory";+ `_state["session_factory"]()` yields "session_factory". Chains collapse to+ their last element, which is what both detectors key on — a session+ factory is reached through something far more often than as a bare name,+ and the gateway reaches it through a module-level dict, which a+ name-and-attribute-only walk misses entirely.+ """+ called = set()for node in ast.walk(tree):if not isinstance(node, ast.Call):continuefunc = node.func- name = func.id if isinstance(func, ast.Name) else getattr(func, "attr", None)- if name == "unscoped_session":- return True- return False+ if isinstance(func, ast.Name):+ called.add(func.id)+ elif isinstance(func, ast.Attribute):+ called.add(func.attr)+ elif isinstance(func, ast.Subscript) and isinstance(func.slice, ast.Constant):+ if isinstance(func.slice.value, str):+ called.add(func.slice.value)+ return called-def _modules_calling_unscoped_session() -> set[str]:+def _calls_unscoped_session(path: Path) -> bool:+ """Whether `path` calls `unscoped_session`, under any local name."""+ tree = ast.parse(path.read_text(), filename=str(path))+ return bool(_called_names(tree) & _local_names_for(tree, "unscoped_session"))+++def _calls_session_factory(path: Path) -> bool:+ """Whether `path` opens a session straight from a factory.++ Matches any call whose name ends in `session_factory`, which is how every+ such call in this tree is spelled — `session_factory()`,+ `self._session_factory()`, `self.session_factory()`. `create_session_+ factory` is excluded: it builds a factory rather than opening a session.+ """+ tree = ast.parse(path.read_text(), filename=str(path))+ return any(+ name.endswith("session_factory") and name != "create_session_factory"+ for name in _called_names(tree)+ )+++def _modules_where(predicate: object) -> set[str]:found = set()for path in _PACKAGE_ROOT.rglob("*.py"):- if path.name == "session_scope.py" and path.parent.name == "db":- continue # the definition itself, not a caller- if _calls_unscoped_session(path):+ if path == _DEFINITION:+ continue+ if predicate(path): # type: ignore[operator]found.add(_module_name(path))return founddef test_only_the_allowed_modules_call_unscoped_session() -> None:- found = _modules_calling_unscoped_session()+ found = _modules_where(_calls_unscoped_session)unexpected = found - _ALLOWED_MODULESassert not unexpected, (f"{sorted(unexpected)} call unscoped_session but are not in "- "_ALLOWED_MODULES in this test. That helper is the fail-open hatch "- "for cross-tenant work (db/session_scope.py) — if this new call site "- "is genuinely cross-tenant (a sweep, an enumeration, startup "- "seeding), add its module to _ALLOWED_MODULES and say why in the "- "commit; otherwise use tenant_session and bind the tenant the work "- "is actually for."+ "_ALLOWED_MODULES in this test. That helper unbinds the tenant for "+ "the whole block (db/session_scope.py) — if this new call site is "+ "genuinely cross-tenant (a sweep, an enumeration, a lookup that "+ "answers *which* tenant something is in, startup seeding), add its "+ "module to _ALLOWED_MODULES and say why in the commit; otherwise use "+ "tenant_session and bind the tenant the work is actually for.")@@ -97,18 +204,46 @@ def test_the_allowlist_names_no_stale_module() -> None:"""The other direction: every allowed module still actually uses it,so the list stays the audit surface it claims to be rather than growingentries nobody needs."""- found = _modules_calling_unscoped_session()+ found = _modules_where(_calls_unscoped_session)stale = _ALLOWED_MODULES - foundassert not stale, f"{sorted(stale)} no longer call unscoped_session; remove them"-class TestDetectionCatchesANewCaller:- """The two tests above only prove today's tree is clean. This exercises- the detector itself against a file that is not in the real source tree- at all, so it stands on its own even if every real call site above is- later removed."""+def test_only_the_approved_modules_open_a_raw_session() -> None:+ """The surface that actually matters, and the one this design is working+ down. A raw factory call takes whatever tenant is ambient — which in+ background code, now that the long-lived tasks unbind, is none."""+ found = _modules_where(_calls_session_factory)+ unexpected = found - _RAW_SESSION_FACTORY_MODULES+ assert not unexpected, (+ f"{sorted(unexpected)} open a session straight from the factory but "+ "are not in _RAW_SESSION_FACTORY_MODULES in this test. Such a session "+ "inherits whatever tenant is bound, which in background code is "+ "nothing at all. Say which you mean: tenant_session(factory, "+ "<the row's tenant>) for work that acts on one tenant's rows, "+ "unscoped_session(factory) for work that genuinely spans them. If "+ "the call really is reached only from an authenticated request, add "+ "the module below and say so in the commit."+ )+- def test_a_plain_call_is_detected(self, tmp_path: Path) -> None:+def test_the_raw_session_list_names_no_stale_module() -> None:+ found = _modules_where(_calls_session_factory)+ stale = _RAW_SESSION_FACTORY_MODULES - found+ assert not stale, (+ f"{sorted(stale)} no longer open a raw session — remove them from "+ "_RAW_SESSION_FACTORY_MODULES. Shrinking this list is the point; "+ "leaving converted modules in it hides the progress."+ )+++class TestTheDetectorsCatchANewCaller:+ """The four tests above only prove today's tree is clean. These exercise+ the detectors against files that are not in the real source tree at all,+ so they stand on their own even if every real call site is later+ removed."""++ def test_a_plain_unscoped_call_is_detected(self, tmp_path: Path) -> None:new_caller = tmp_path / "a_new_background_job.py"new_caller.write_text("async def sweep(session_factory):\n"@@ -117,7 +252,10 @@ class TestDetectionCatchesANewCaller:)assert _calls_unscoped_session(new_caller)- def test_an_aliased_import_is_still_detected(self, tmp_path: Path) -> None:+ def test_an_aliased_import_is_detected(self, tmp_path: Path) -> None:+ """`import … as` must not walk past the check. The detector resolves+ the local name the helper was bound to rather than matching the+ spelling `unscoped_session`."""new_caller = tmp_path / "a_new_background_job.py"new_caller.write_text("from switch_core.db.session_scope import unscoped_session as us\n"@@ -125,21 +263,57 @@ class TestDetectionCatchesANewCaller:" async with us(session_factory) as session:\n"" ...\n")- assert not _calls_unscoped_session(new_caller), (- "an aliased import is a known gap: the detector matches the "- "literal name unscoped_session, not what it resolves to"- )+ assert _calls_unscoped_session(new_caller)def test_a_module_with_no_call_is_not_flagged(self, tmp_path: Path) -> None:clean = tmp_path / "an_unrelated_module.py"- clean.write_text("async def do_work(session_factory):\n ...\n")+ clean.write_text("async def do_work(session):\n ...\n")assert not _calls_unscoped_session(clean)+ assert not _calls_session_factory(clean)++ def test_a_bare_factory_call_is_detected(self, tmp_path: Path) -> None:+ new_caller = tmp_path / "a_new_background_job.py"+ new_caller.write_text(+ "async def sweep(session_factory):\n"+ " async with session_factory() as session:\n"+ " ...\n"+ )+ assert _calls_session_factory(new_caller)++ def test_a_factory_reached_through_self_is_detected(self, tmp_path: Path) -> None:+ new_caller = tmp_path / "a_new_service.py"+ new_caller.write_text(+ "class Service:\n"+ " async def run(self):\n"+ " async with self._session_factory() as session:\n"+ " ...\n"+ )+ assert _calls_session_factory(new_caller)++ def test_a_factory_reached_through_a_dict_is_detected(self, tmp_path: Path) -> None:+ """How the gateway holds its factory. Worth its own case: a walk over+ names and attributes alone reports this module as clean."""+ new_caller = tmp_path / "a_new_dependency.py"+ new_caller.write_text(+ "_state = {}\n"+ "async def get_session():\n"+ ' async with _state["session_factory"]() as session:\n'+ " yield session\n"+ )+ assert _calls_session_factory(new_caller)++ def test_building_a_factory_is_not_opening_a_session(self, tmp_path: Path) -> None:+ clean = tmp_path / "wiring.py"+ clean.write_text(+ "def wire(engine):\n return create_session_factory(engine)\n"+ )+ assert not _calls_session_factory(clean)def test_the_allowlist_check_would_fail_for_a_hypothetical_new_caller(self) -> None:"""Simulates what `test_only_the_allowed_modules_call_unscoped_session`does, against a found-set that includes a module nobody added to`_ALLOWED_MODULES` — pinning that the check actually fails ratherthan, say, silently ignoring an unknown module."""- found = _modules_calling_unscoped_session() | {"switch_core.a_new_sweep"}+ found = _modules_where(_calls_unscoped_session) | {"switch_core.a_new_sweep"}unexpected = found - _ALLOWED_MODULESassert unexpected == {"switch_core.a_new_sweep"}diff --git a/core/tests/switch_core/test_room_service_change_bridge.py b/core/tests/switch_core/test_room_service_change_bridge.pyindex f4262e501..7e077fee4 100644--- a/core/tests/switch_core/test_room_service_change_bridge.py+++ b/core/tests/switch_core/test_room_service_change_bridge.py@@ -100,7 +100,11 @@ class _FakeBridgeCore:self.adapter = _FakeAdapter(events, new_channel_id)def add_room_mapping(- self, room_id: str, matrix_room_id: str, external_channel_id: str+ self,+ room_id: str,+ matrix_room_id: str,+ external_channel_id: str,+ tenant_id: str,) -> None:self._events.append(("add_room_mapping", room_id, external_channel_id))diff --git a/core/tests/switch_core/transport/test_postgres_transport.py b/core/tests/switch_core/transport/test_postgres_transport.pyindex fb745d2c6..ea0b86e2e 100644--- a/core/tests/switch_core/transport/test_postgres_transport.py+++ b/core/tests/switch_core/transport/test_postgres_transport.py@@ -17,13 +17,14 @@ import uuidfrom collections.abc import Iteratorimport pytest+from sqlalchemy.exc import IntegrityErrorfrom sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker-from switch_core.db.models import Client, Room, Tenant+from switch_core.db.models import Client, ClientRoom, Message, Room, Tenantfrom switch_core.db.stores.media_store import MediaStorefrom switch_core.db.stores.message_store import MessageStorefrom switch_core.db.stores.room_store import RoomStore-from switch_core.tenant_context import current_tenant_id+from switch_core.tenant_context import current_tenant_id, tenant_scopefrom switch_core.transport import (InboundCustomEvent,InboundMedia,@@ -931,3 +932,239 @@ class TestDeliveryBindsTheRoomsTenant:assert all(tenant == tenant_id for tenant in seen)# Bound only for the read itself, not left dangling on the process.assert current_tenant_id() is None+++class TestATransportOwnsNoTenantOfItsOwn:+ """A transport is not a single-tenant actor, and CHOO-2623 stops it+ behaving like one.++ Its task binds nothing: `ClientLifecycleService` unbinds before running a+ client, so anything the transport does under an inherited tenant would be+ doing it under the tenant of whoever happened to create the task — boot,+ a gateway request, or the inbound bridge message that minted a puppet+ mid-conversation. Two consequences are pinned here: the lookup that says+ which rooms this client is in runs with nothing bound, and each delivery+ binds the tenant of the room it is for.+ """++ @pytest.fixture(autouse=True)+ def _cleanup(self) -> Iterator[None]:+ self._tasks: list[asyncio.Task] = []+ yield+ for task in self._tasks:+ task.cancel()++ async def test_the_room_list_is_read_with_no_tenant_bound(+ self,+ session_factory: async_sessionmaker[AsyncSession],+ monkeypatch: pytest.MonkeyPatch,+ ) -> None:+ """`joined_rooms` decides, once, what this client will ever hear. A+ tenant bound over that read narrows it to a subset with no error to+ say so — the client is simply deaf everywhere else, forever. So it+ must run unscoped even when reached from a bound context."""+ tenant_id = f"tenant-{uuid.uuid4().hex[:8]}"+ async with session_factory() as session:+ session.add(Tenant(id=tenant_id, slug=tenant_id, name=tenant_id))+ await session.flush()+ suffix = uuid.uuid4().hex[:8]+ client = Client(+ tenant_id=tenant_id,+ matrix_user_id=f"@sys-{suffix}:test",+ display_name="admin",+ type="admin",+ )+ session.add(client)+ room = Room(+ tenant_id=tenant_id,+ matrix_room_id=f"!room-{suffix}:test",+ name="a room",+ description="",+ )+ session.add(room)+ await session.flush()+ session.add(+ ClientRoom(tenant_id=tenant_id, client_id=client.id, room_id=room.id)+ )+ await session.commit()+ client_id, user_id = client.id, client.matrix_user_id+ transport_room_id = room.matrix_room_id++ seen: list[str | None] = []+ original = RoomStore.get_for_client++ async def _spy(self, session, client_id): # type: ignore[no-untyped-def]+ seen.append(current_tenant_id())+ return await original(self, session, client_id)++ monkeypatch.setattr(RoomStore, "get_for_client", _spy)++ transport = _transport(session_factory, client_id=client_id, user_id=user_id)+ # Stands in for a task that inherited a tenant it has no business+ # acting under — a bridge restart, a puppet minted mid-conversation.+ with tenant_scope("some-other-tenant"):+ rooms = await transport.joined_rooms()++ assert rooms == [transport_room_id]+ assert seen == [None], (+ "joined_rooms inherited a tenant; under row-level security it "+ "would have returned a subset of this client's rooms and gone "+ "silent in the rest"+ )++ async def test_each_room_is_delivered_under_its_own_tenant(+ self,+ session_factory: async_sessionmaker[AsyncSession],+ monkeypatch: pytest.MonkeyPatch,+ ) -> None:+ """One transport, two rooms, two tenants — the shape a reused puppet+ takes. The client whose transport this is belongs to one of the two+ tenants, and that must not decide how the other room is read.++ Membership is only recorded for the room in the transport's own+ tenant, because `client_rooms` carries composite foreign keys to both+ `clients` and `rooms` and so cannot join a client to a room in another+ tenant at all — see+ `test_the_schema_forbids_a_client_row_in_another_tenants_room`. The+ watch and the delivery do not go through membership, which is what+ makes the two-tenant case reachable here.+ """+ tenant_a = f"tenant-{uuid.uuid4().hex[:8]}"+ tenant_b = f"tenant-{uuid.uuid4().hex[:8]}"+ suffix = uuid.uuid4().hex[:8]+ async with session_factory() as session:+ for tenant_id in (tenant_a, tenant_b):+ session.add(Tenant(id=tenant_id, slug=tenant_id, name=tenant_id))+ await session.flush()+ puppet = Client(+ tenant_id=tenant_a,+ matrix_user_id=f"@puppet-{suffix}:test",+ display_name="puppet",+ type="user",+ )+ speaker_b = Client(+ tenant_id=tenant_b,+ matrix_user_id=f"@speaker-{suffix}:test",+ display_name="someone",+ type="agent",+ )+ session.add_all([puppet, speaker_b])+ room_a = Room(+ tenant_id=tenant_a,+ matrix_room_id=f"!a-{suffix}:test",+ name="room a",+ description="",+ )+ room_b = Room(+ tenant_id=tenant_b,+ matrix_room_id=f"!b-{suffix}:test",+ name="room b",+ description="",+ )+ session.add_all([room_a, room_b])+ await session.commit()+ ids = {+ room_a.id: tenant_a,+ room_b.id: tenant_b,+ }+ mxid_a, mxid_b = room_a.matrix_room_id, room_b.matrix_room_id+ room_b_id = room_b.id+ speaker_b_id, speaker_b_mxid = speaker_b.id, speaker_b.matrix_user_id+ client_id, user_id = puppet.id, puppet.matrix_user_id++ seen: dict[str, list[str | None]] = {}+ original = MessageStore.list_for_room++ async def _spy(self, session, room_id, **kwargs): # type: ignore[no-untyped-def]+ seen.setdefault(room_id, []).append(current_tenant_id())+ return await original(self, session, room_id, **kwargs)++ monkeypatch.setattr(MessageStore, "list_for_room", _spy)++ listener = _FakeListener()+ received = _Received()+ transport = _transport(+ session_factory, client_id=client_id, user_id=user_id, listener=listener+ )+ transport.register_handlers(received.handlers())+ await transport.join_room(mxid_a)+ self._tasks.append(asyncio.create_task(transport.receive_forever()))+ await _watched_room(transport)+ await transport._watch(mxid_b)++ await transport.send_message(mxid_a, "in a", sender_name="puppet")+ # Written as a client of tenant B: a message in room B carries room+ # B's tenant, and the composite key to `clients` will not let a+ # tenant-A client be its sender.+ async with session_factory() as session:+ await MessageStore().create(+ session,+ Message(+ tenant_id=tenant_b,+ room_id=room_b_id,+ transport_event_id=f"sw_{uuid.uuid4().hex}",+ sender_id=speaker_b_mxid,+ sender_client_id=speaker_b_id,+ sender_name="someone",+ event_type="m.room.message",+ msgtype="m.text",+ body="in b",+ formatted_body=None,+ thread_root_event_id=None,+ content={"body": "in b", "msgtype": "m.text"},+ ),+ [],+ )+ await session.commit()++ for room_id in ids:+ await listener.announce(room_id)++ assert {getattr(e, "body", None) for e in received.events} == {"in a", "in b"}+ assert set(seen) == set(ids), "a room was never read"+ for room_id, tenants in seen.items():+ assert tenants and all(t == ids[room_id] for t in tenants), (+ f"room {room_id} was read under {tenants}, not {ids[room_id]}"+ )+ assert current_tenant_id() is None+++async def test_the_schema_forbids_a_client_row_in_another_tenants_room(+ session_factory: async_sessionmaker[AsyncSession],+) -> None:+ """Why "one system client, a member of every tenant's rooms" is not a+ state this deployment can reach, and so not a case the transport has to+ handle: `client_rooms` keys to both `clients` and `rooms` on `tenant_id`,+ so membership cannot cross a tenant boundary. The system client is one+ row per tenant, which is what the Phase 1 design says it becomes.++ Pinned as a test rather than argued in a comment, because everything the+ transport does about its room list rests on it.+ """+ tenant_a = f"tenant-{uuid.uuid4().hex[:8]}"+ tenant_b = f"tenant-{uuid.uuid4().hex[:8]}"+ suffix = uuid.uuid4().hex[:8]+ async with session_factory() as session:+ for tenant_id in (tenant_a, tenant_b):+ session.add(Tenant(id=tenant_id, slug=tenant_id, name=tenant_id))+ await session.flush()+ client = Client(+ tenant_id=tenant_a,+ matrix_user_id=f"@sys-{suffix}:test",+ display_name="admin",+ type="admin",+ )+ session.add(client)+ room = Room(+ tenant_id=tenant_b,+ matrix_room_id=f"!b-{suffix}:test",+ name="room b",+ description="",+ )+ session.add(room)+ await session.flush()+ session.add(+ ClientRoom(tenant_id=tenant_a, client_id=client.id, room_id=room.id)+ )+ with pytest.raises(IntegrityError):+ await session.commit()diff --git a/docs/old/multi-tenancy-phase1-db.md b/docs/old/multi-tenancy-phase1-db.mdindex 3a17e9ce4..7ddd1d223 100644--- a/docs/old/multi-tenancy-phase1-db.md+++ b/docs/old/multi-tenancy-phase1-db.md@@ -16,8 +16,12 @@ when" were all split out into a later change.what was actually implemented, which differs from what it originally proposed —an event hook rather than a dependency at every call site, for reasons giventhere. **The background half of it has since been built too** — the roughly-206 session sites outside the request path now bind a tenant, described where-"Setting the tenant" talks about background work below. Read the remaining+197 session sites outside the request path now bind a tenant at each unit of+work, described where "Setting the tenant" talks about background work below.+That section also records the model that was tried first, of binding once per+long-lived task, and the four ways it leaked; it is written up rather than+deleted because the reasoning that made it look right is easy to arrive at+twice. Read the remainingsections as the design those later changes implement rather than as adescription of what is running today; "What Phase 1 does not close" says whichgaps are this migration's and which belong to the deferred work — row-level@@ -356,41 +360,105 @@ silently discarded a password change. Resolution needs the subject id, not athe session the endpoint actually commits.**Background work is not a short list, and it has since been closed.** There-were roughly 206 places that opened a session from the factory directly, with-no request behind them. They fall into three shapes, each handled differently-rather than by one helper covering all of them:--- **Acting for a room** — the delivery loop (`transport/postgres.py`), most of- `room_service.py`, the collaboration bridges' inbound and outbound handling- (`bridges/collaboration/bridge_core.py`). Each derives the tenant from the- room the unit of work is actually for — one delivery, one inbound event, one- membership change — rather than caching it, because a client or a bridge is- not guaranteed to act for only one tenant over its life. Resolving which- room (and so which tenant) a unit of work is for is itself unscoped by- necessity, the same bootstrap as resolving a principal below; each of these- files caches the answer per room id once resolved, since a room's tenant- cannot change, the same way each already cached the room's own id.-- **Acting for a bridge or connector** — `bridges/collaboration/lifecycle_service.py`- and `bridges/agent/server_connectors/lifecycle.py` bind the bridge's or- connector's own tenant once, around starting its long-lived task; the task- keeps it for its life because an `asyncio.Task` snapshots the contextvar- state it was created under.-- **Acting for the deployment** — startup seeding (`main.py`), the- runtime-state sweep (`ProtocolService.sweep_runtime_states`), and the- lifecycle enumerations that read every row before fanning out- (`start_all` on both lifecycle services above, and on- `ClientLifecycleService`). These read cross-tenant by nature; where they- then act per row, they bind that row's own tenant rather than the tenant of- the whole pass.+are roughly 197 places that open a session from the factory directly, with no+request behind them. One rule covers all of them:++> **Nothing is ambient. Every unit of background work binds the tenant of the+> row it is acting on, at the point it acts. Long-lived tasks bind nothing for+> their lifetime. A lookup that must span tenants uses a helper that genuinely+> unbinds.**++**The first attempt at this had a different rule, and it was wrong.** It said a+long-lived task "acts for exactly one bridge, so it can bind once for the+task's lifetime", and leaned on an `asyncio.Task` snapshotting the contextvars+of whoever created it. Four things went wrong, and they are one thing:++- **Who creates the task is not who owns it.** A bridge is started at boot,+ with nothing bound, *and* from an HTTP request that edited its connection+ (`gateway/collaborations.py` calls `restart`), with the requesting+ operator's tenant bound. Bind-at-creation makes the bridge spend its entire+ life acting as whoever last restarted it.+- **A long-lived object is not a single-tenant actor.** A client's transport+ reads which rooms it is in — a lookup keyed by a globally unique client id —+ and then works one room at a time. A puppet minted for one person on a+ bridge is reused for every room they ever speak in. A boot-time tenant on+ either is a value that happens to be right until it is not, with no error+ when it turns.+- **A cache that is only filled at startup is empty for everything created+ after startup.** The bridge's room→tenant map was loaded at boot and not+ written by `add_room_mapping`, so every room created later missed it and+ fell back to a database read under whatever was ambient — which on the+ inbound path is the very thing being asked.+- **Not every task inherits anything.** Mattermost's websocket runs on an OS+ thread and dispatches with `asyncio.run_coroutine_threadsafe`, which starts+ the coroutine in an *empty* context. Under bind-at-creation, an auto-created+ room landed in tenant zero on Mattermost and in the bridge's tenant+ everywhere else — the platform decided the tenant. Binding at the inbound+ choke point instead makes the platform irrelevant, which is the property+ worth having.++So what is built now is:++- **Long-lived tasks unbind first.** `CollaborationBridgeLifecycleService._run_bridge`,+ `ClientLifecycleService._run_client`, `BridgeCore._run_agent_identities` and+ the connectors' per-agent poll loop each enter `tenant_context.no_tenant()`+ as their first act. Nothing inside them can read a tenant it did not derive,+ and once the policies land, a unit of work that forgot to bind reads nothing+ rather than reading someone else's rows.+- **Each unit of work binds the row it is acting on.** A delivery binds the+ room's tenant (`transport/postgres.py`); an inbound platform event binds the+ room's, or — when the handler is about to auto-create the room — the+ bridge's, at the single choke point every handler passes through+ (`BridgeCore._traced`); a membership change binds the room's+ (`room_service.py`); a sweep row binds its own, for the *whole* of that+ row's work including the event emitted at the end+ (`ProtocolService.sweep_runtime_states`); one poll and the events it+ returns bind the connector's (`server_connectors/core.py`).+- **An object may know its tenant without binding it.** `BridgeCore` holds+ `bridge_tenant_id` and `ConnectorCore` holds `connector_tenant_id`, read+ once from the row they are the runtime for. Knowing is not binding: the+ value is bound around a piece of work and released, never held open. Rooms+ cannot disagree with their bridge in any case — `rooms` carries a composite+ foreign key to `collaboration_bridges` on `tenant_id` — but room-scoped work+ still binds the room's own tenant rather than relying on that.+- **The lookups that produce a tenant are unscoped, not scoped to a guess.**+ Which room is this transport id? Which rooms is this client in? Which agent+ is this client? Which tenant is this bridge in? Each is asked before the+ answer is known, so binding one first is either a tautology or, under+ policies, a false "not found". These use `unscoped_session`, the same as the+ credential lookups in the bootstrap section below.Two named helpers carry this: `tenant_session` (`db/session_scope.py`) binds a-given tenant and opens a session; `unscoped_session` opens one with nothing-bound at all — the fail-open hatch, named so a reader can tell at the call site-which one is meant, and used only by the "acting for the deployment" sites-above. `tests/switch_core/db/test_unscoped_session_allowlist.py` pins the-modules allowed to call it, deriving the list from the source tree rather than-from imports, so a new caller is a deliberate, reviewed act rather than an-accident.+given tenant and opens a session; `unscoped_session` **unbinds** for the+duration of the block and opens one with nothing set, restoring the caller's+binding on the way out. The unbinding is the point and was the second thing+the first attempt got wrong: a helper that only *named* the intent while+inheriting whatever was ambient has the hook stamp the caller's tenant onto+the transaction, so the cross-tenant read the call site asked for is silently+a single-tenant one — and the allowlist pinning it certifies a lie.++`tests/switch_core/db/test_unscoped_session_allowlist.py` pins two lists,+derived from the source tree rather than from imports and resolving aliased+imports rather than matching a spelling. The first is who may call+`unscoped_session`. The second is the one that matters more: **which modules+may open a session straight from the factory at all.** A raw call inherits+whatever is ambient, which in background code is now nothing — so it is+unscoped in fact while declaring nothing, strictly worse than the hatch that+announces itself. Those ~197 call sites across nineteen modules are the+inventory this design has to work down; pinning the module list makes a new+one a decision rather than a default.++**Cost, stated rather than hidden.** The hook adds one `SELECT set_config(…)`+round trip per transaction, which on the delivery path is roughly per message+once a handler writes. Measured against the test container (Postgres 16 over+a colima socket, 400 single-statement transactions per arm, two runs): mean+0.95–1.20 ms unbound against 1.30–1.41 ms bound, a delta of **0.20–0.36 ms per+transaction**. That environment's round trip is slower than a deployed one's,+so read it as an upper bound on the shape rather than a production figure —+but it is one extra round trip per transaction, and on a chatty room that is+one extra round trip per message. If it ever matters, the fix is to widen the+unit of work rather than to skip the hook: fewer, larger transactions pay it+fewer times, and skipping it is how the prior-art bugs happened.**Writes fill the column automatically.** `tenant_id` gets a Python-sidedefault reading the request's tenant, so ordinary ORM inserts need no change@@ -435,6 +503,19 @@ discovered it, so a handler's own downstream session opens (posting to abridge, gating a command) are covered too — they run in the same task, and thebinding is a contextvar, not something tied to one session object.+One thing the transport deliberately does *not* do is treat its client as+belonging to a tenant. `joined_rooms` is unscoped, because it runs once and+decides what that client will ever hear: a tenant over that read returns a+subset with no error to say so, and the client is then silently deaf in every+room it did not see, forever. The client id it reads by is globally unique, so+there is nothing for a tenant to disambiguate. (A client cannot in fact be a+member of another tenant's room — `client_rooms` carries composite foreign+keys to both `clients` and `rooms`, so the system client is one row per tenant+rather than one row in every tenant's rooms. The transport does not lean on+that; it is pinned by a test in+`tests/switch_core/transport/test_postgres_transport.py` because the shape of+the room list rests on it.)+Two exceptions to the uniform rule, in full:1. **`api_keys.key_hash` stays globally unique**, because authentication