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
Replace matrix with simple postgres + LISTEN / NOTIFY, keep matrix to the side (#363)
Louis Amaudruz3affb6539214
diff --git a/console/apps/switch-console-desktop/src/main/core/managed-switch-server/resources/standalone-docker-compose.pinned.yml b/console/apps/switch-console-desktop/src/main/core/managed-switch-server/resources/standalone-docker-compose.pinned.ymlindex f61363a00..e67ba9c6d 100644--- a/console/apps/switch-console-desktop/src/main/core/managed-switch-server/resources/standalone-docker-compose.pinned.yml+++ b/console/apps/switch-console-desktop/src/main/core/managed-switch-server/resources/standalone-docker-compose.pinned.yml@@ -17,7 +17,7 @@# docker compose -f standalone-docker-compose.yml -f standalone-docker-compose.build.yml up## Profiles keep optional services opt-in:-# (core, no profile) postgres, tuwunel, switch — always started+# (core, no profile) postgres, tuwunel, backfill, switch — always started# collab init-db, mattermost, setup — Mattermost bridge + seeder# gateway gateway — operator dashboard# Select them with `--profile collab --profile gateway` or COMPOSE_PROFILES.@@ -149,6 +149,54 @@ services:init-db:condition: service_completed_successfully+ # One-shot: reconstructs each room's history from the homeserver into the+ # message log, then exits. switch waits for it to finish, so the copy is+ # never racing the server that will serve it.+ #+ # It always exits 0, so a backfill that fails delays the stack rather than+ # keeping it down. The trade is deliberate and it is a real one: a failure+ # here is only visible in this service's log, and the stack above it will+ # look healthy while missing history. Backfill is idempotent, so re-running+ # it after fixing the cause costs nothing.+ #+ # It runs alembic first for ordering, not as a second migration owner: the+ # rows it writes need the schema, and switch (which normally migrates on+ # boot) is waiting on this. The upgrade is the same idempotent one.+ #+ # Rooms already walked to their start are skipped, so this is cheap on every+ # boot after the first. Nothing to walk at all is success too — a fresh+ # stack has no rooms and no admin client.+ backfill:+ image: ${SWITCH_REGISTRY:-ghcr.io}/${SWITCH_IMAGE_NAMESPACE:-sandbox-quantum}/switch-core:${SWITCH_VERSION:?required, set it in .env, there is no default}+ restart: "no"+ environment:+ DB_HOST: postgres+ DB_PORT: "5432"+ DB_USER: ${DB_USER}+ DB_PASSWORD: ${DB_PASSWORD}+ DB_NAME: ${DB_NAME}+ MATRIX_SERVER: http://tuwunel:8008+ MATRIX_SERVER_NAME: localhost+ MATRIX_ADMIN_USER: ${MATRIX_ADMIN_USER}+ MATRIX_ADMIN_PASSWORD: ${MATRIX_ADMIN_PASSWORD}+ MATRIX_REGISTRATION_SHARED_SECRET: ${MATRIX_REGISTRATION_SHARED_SECRET}+ AGENT_REGISTRATION_TOKEN: ${AGENT_REGISTRATION_TOKEN}+ JWT_SECRET_KEY: ${JWT_SECRET_KEY}+ GATEWAY_ADMIN_EMAIL: ${GATEWAY_ADMIN_EMAIL}+ GATEWAY_ADMIN_PASSWORD: ${GATEWAY_ADMIN_PASSWORD}+ entrypoint: >+ sh -c "+ alembic upgrade head &&+ python -m switch_core.cli.backfill --allow-empty ||+ echo 'backfill did not complete; starting anyway. Room history from+ before this release may be missing until it is re-run.' >&2+ "+ depends_on:+ postgres:+ condition: service_healthy+ tuwunel:+ condition: service_started+switch:image: ${SWITCH_REGISTRY:-ghcr.io}/${SWITCH_IMAGE_NAMESPACE:-sandbox-quantum}/switch-core:${SWITCH_VERSION:?required, set it in .env, there is no default}ports:@@ -175,6 +223,8 @@ services:condition: service_healthytuwunel:condition: service_started+ backfill:+ condition: service_completed_successfullygateway:image: ${SWITCH_REGISTRY:-ghcr.io}/${SWITCH_IMAGE_NAMESPACE:-sandbox-quantum}/gateway:${SWITCH_VERSION:?required, set it in .env, there is no default}diff --git a/core/switch_core/bridges/agent/api/handlers.py b/core/switch_core/bridges/agent/api/handlers.pyindex 0df3ad946..d0e7d84a1 100644--- a/core/switch_core/bridges/agent/api/handlers.py+++ b/core/switch_core/bridges/agent/api/handlers.py@@ -101,8 +101,6 @@ logger = logging.getLogger(__name__)router = APIRouter()-MEDIATION_TIMEOUT_SECONDS = 10.0-def parse_timestamp_ms(iso: str) -> int:dt = datetime.fromisoformat(iso)@@ -1277,8 +1275,6 @@ async def pre_tool_call(req.room_id,req.tool_name,req.arguments,- req.request_id,- MEDIATION_TIMEOUT_SECONDS,)except ValueError as e:raise HTTPException(status_code=404, detail=str(e)) from e@@ -1304,8 +1300,6 @@ async def pre_llm_request(req.room_id,req.model,req.messages,- req.request_id,- MEDIATION_TIMEOUT_SECONDS,)except ValueError as e:raise HTTPException(status_code=404, detail=str(e)) from e@@ -1331,8 +1325,6 @@ async def post_tool_result(req.room_id,req.tool_name,req.result,- req.request_id,- MEDIATION_TIMEOUT_SECONDS,)except ValueError as e:raise HTTPException(status_code=404, detail=str(e)) from e@@ -1358,8 +1350,6 @@ async def post_llm_response(req.room_id,req.model,req.response,- req.request_id,- MEDIATION_TIMEOUT_SECONDS,)except ValueError as e:raise HTTPException(status_code=404, detail=str(e)) from ediff --git a/core/switch_core/bridges/agent/app.py b/core/switch_core/bridges/agent/app.pyindex e744bbf93..ba60a27e9 100644--- a/core/switch_core/bridges/agent/app.py+++ b/core/switch_core/bridges/agent/app.py@@ -17,12 +17,10 @@ from switch_core.bridges.agent.mcp import create_mcp_appfrom switch_core.bridges.agent.protocol.connections import ConnectionRegistryfrom switch_core.bridges.agent.protocol.event_buffer import EventBufferfrom switch_core.bridges.agent.protocol.service import ProtocolService-from switch_core.bridges.agent.request_tracker import RequestTrackerfrom switch_core.bridges.collaboration.lifecycle_service import (CollaborationBridgeLifecycleService,)from switch_core.bridges.resource.service import ResourceService-from switch_core.bridges.resource.tracker import ResourceRequestTrackerfrom switch_core.clients.client_lifecycle_service import ClientLifecycleServicefrom switch_core.config import SwitchConfigfrom switch_core.db.stores.agent_session_store import AgentSessionStore@@ -47,8 +45,6 @@ def create_agent_bridge_app(collab_lifecycle: CollaborationBridgeLifecycleService,event_buffer: EventBuffer,task_store: TaskStore,- request_tracker: RequestTracker,- resource_request_tracker: ResourceRequestTracker,resource_service: ResourceService,api_key_store: ApiKeyStore,external_user_store: ExternalUserStore,@@ -82,8 +78,6 @@ def create_agent_bridge_app(event_buffer=event_buffer,connections=connections,task_store=task_store,- request_tracker=request_tracker,- resource_request_tracker=resource_request_tracker,resource_service=resource_service,api_key_store=api_key_store,api_key_cache=api_key_cache,@@ -103,8 +97,6 @@ def create_agent_bridge_app(event_buffer=event_buffer,connections=connections,task_store=task_store,- request_tracker=request_tracker,- resource_request_tracker=resource_request_tracker,resource_service=resource_service,api_key_store=api_key_store,api_key_cache=api_key_cache,diff --git a/core/switch_core/bridges/agent/commands.py b/core/switch_core/bridges/agent/commands.pyindex 2d4235718..65cbba170 100644--- a/core/switch_core/bridges/agent/commands.py+++ b/core/switch_core/bridges/agent/commands.py@@ -6,8 +6,6 @@ from collections.abc import Awaitable, Callablefrom dataclasses import dataclass, fieldfrom typing import TYPE_CHECKING, Literal, cast-from nio import MatrixRoom-from switch_core.agent_display_name import agent_label, agent_label_with_identifierfrom switch_core.aliases import (AliasError,@@ -24,6 +22,7 @@ from switch_core.clients.mentions import mention_tokens as _mention_tokensfrom switch_core.db.stores.agent_runtime_state_store import AgentRuntimeStateStorefrom switch_core.events import CommandEventfrom switch_core.gateway.known_agents import known_agent_for+from switch_core.transport import RoomRefif TYPE_CHECKING:from switch_core.clients.admin_client import AdminClient@@ -45,9 +44,7 @@ AGENT_GREETINGS = ["Hi there! Just @{name} me when you're ready.",]-CommandHandler = Callable[- ["AgentClient", MatrixRoom, CommandEvent, bool], Awaitable[None]-]+CommandHandler = Callable[["AgentClient", RoomRef, CommandEvent, bool], Awaitable[None]]# (client, args, room_id) -> whether THIS agent is addressed by the command.# Targeting is a per-command policy (see Command.addressed) rather than a fixed# rule in on_command, so a command like `run-cmd` can interpret its args its@@ -58,7 +55,7 @@ CommandTargeting = Callable[["AgentClient", str, str], Awaitable[bool]]# system message when the command is misused (bad/missing target) and does# nothing when usage is valid; it never executes the command itself.CommandAdminCheck = Callable[- ["AdminClient", MatrixRoom, CommandEvent, "RoomMeta"], Awaitable[None]+ ["AdminClient", RoomRef, CommandEvent, "RoomMeta"], Awaitable[None]]@@ -129,7 +126,7 @@ async def _first_token_is_me(client: AgentClient, first: str, room_id: str) -> basync def _check_control_target(- host: AdminClient, room: MatrixRoom, event: CommandEvent, meta: RoomMeta+ host: AdminClient, room: RoomRef, event: CommandEvent, meta: RoomMeta) -> None:"""Admin-side usage feedback for a target-required control command.@@ -238,7 +235,7 @@ class Command:async def _reply(client: AgentClient | AdminClient,- room: MatrixRoom,+ room: RoomRef,event: CommandEvent,body: str,*,@@ -261,7 +258,7 @@ async def _reply(async def _cmd_help(- client: AgentClient, room: MatrixRoom, event: CommandEvent, _is_direct: bool+ client: AgentClient, room: RoomRef, event: CommandEvent, _is_direct: bool) -> None:lines = ["**Available commands:**"]for cmd in COMMANDS:@@ -273,7 +270,7 @@ async def _cmd_help(async def _dispatch_control_command(client: AgentClient,- room: MatrixRoom,+ room: RoomRef,event: CommandEvent,command: str,*,@@ -367,7 +364,7 @@ async def _dispatch_control_command(async def _cmd_reset(- client: AgentClient, room: MatrixRoom, event: CommandEvent, _is_direct: bool+ client: AgentClient, room: RoomRef, event: CommandEvent, _is_direct: bool) -> None:await _dispatch_control_command(client,@@ -388,7 +385,7 @@ async def _cmd_reset(async def _cmd_compact(- client: AgentClient, room: MatrixRoom, event: CommandEvent, _is_direct: bool+ client: AgentClient, room: RoomRef, event: CommandEvent, _is_direct: bool) -> None:await _dispatch_control_command(client,@@ -408,7 +405,7 @@ async def _cmd_compact(async def _cmd_interrupt(- client: AgentClient, room: MatrixRoom, event: CommandEvent, _is_direct: bool+ client: AgentClient, room: RoomRef, event: CommandEvent, _is_direct: bool) -> None:await _dispatch_control_command(client,@@ -429,7 +426,7 @@ async def _cmd_interrupt(async def _cmd_list_room_agents(client: AgentClient,- room: MatrixRoom,+ room: RoomRef,event: CommandEvent,_is_direct: bool,) -> None:@@ -457,7 +454,7 @@ async def _cmd_list_room_agents(async def _cmd_list_aliases(client: AgentClient,- room: MatrixRoom,+ room: RoomRef,event: CommandEvent,_is_direct: bool,) -> None:@@ -489,7 +486,7 @@ async def _cmd_list_aliases(async def _cmd_set_alias(client: AgentClient,- room: MatrixRoom,+ room: RoomRef,event: CommandEvent,_is_direct: bool,) -> None:@@ -559,7 +556,7 @@ async def _cmd_set_alias(async def _cmd_remove_alias(client: AgentClient,- room: MatrixRoom,+ room: RoomRef,event: CommandEvent,_is_direct: bool,) -> None:@@ -611,7 +608,7 @@ async def _cmd_remove_alias(async def _cmd_invite(client: AgentClient,- room: MatrixRoom,+ room: RoomRef,event: CommandEvent,_is_direct: bool,) -> None:@@ -730,7 +727,7 @@ def _format_status_lines(async def _cmd_status(client: AgentClient,- room: MatrixRoom,+ room: RoomRef,event: CommandEvent,_is_direct: bool,) -> None:@@ -772,7 +769,7 @@ async def _cmd_status(async def _cmd_roles(client: AgentClient,- room: MatrixRoom,+ room: RoomRef,event: CommandEvent,_is_direct: bool,) -> None:@@ -810,7 +807,7 @@ async def _cmd_roles(async def _cmd_list_documents(client: AgentClient,- room: MatrixRoom,+ room: RoomRef,event: CommandEvent,_is_direct: bool,) -> None:@@ -856,7 +853,7 @@ async def _cmd_list_documents(async def _cmd_list_references(client: AgentClient,- room: MatrixRoom,+ room: RoomRef,event: CommandEvent,_is_direct: bool,) -> None:@@ -892,7 +889,7 @@ async def _cmd_list_references(async def _cmd_room_url(client: AgentClient,- room: MatrixRoom,+ room: RoomRef,event: CommandEvent,_is_direct: bool,) -> None:@@ -919,7 +916,7 @@ async def _cmd_room_url(async def _cmd_list_all_agents(client: AgentClient,- room: MatrixRoom,+ room: RoomRef,event: CommandEvent,_is_direct: bool,) -> None:@@ -951,7 +948,7 @@ def _role_arg(args: str) -> str | None:async def _cmd_run_cmd(client: AgentClient,- room: MatrixRoom,+ room: RoomRef,event: CommandEvent,_is_direct: bool,) -> None:@@ -1012,7 +1009,7 @@ async def _cmd_run_cmd(async def _cmd_agents_greet(client: AgentClient,- room: MatrixRoom,+ room: RoomRef,event: CommandEvent,is_direct: bool,) -> None:@@ -1219,7 +1216,7 @@ COMMANDS_BY_NAME: dict[str, Command] = {cmd.name: cmd for cmd in COMMANDS}async def dispatch_command(- client: AgentClient, room: MatrixRoom, event: CommandEvent, is_direct: bool+ client: AgentClient, room: RoomRef, event: CommandEvent, is_direct: bool) -> bool:"""Runs a command.@@ -1244,7 +1241,7 @@ async def dispatch_command(async def dispatch_admin_command(- host: AdminClient, room: MatrixRoom, event: CommandEvent+ host: AdminClient, room: RoomRef, event: CommandEvent) -> None:"""Run an admin-owned command on the admin client.diff --git a/core/switch_core/bridges/agent/dependencies.py b/core/switch_core/bridges/agent/dependencies.pyindex 1c5aedc0a..2a11d36c1 100644--- a/core/switch_core/bridges/agent/dependencies.py+++ b/core/switch_core/bridges/agent/dependencies.py@@ -9,12 +9,10 @@ from switch_core.bridges.agent.api_key_cache import ApiKeyCachefrom switch_core.bridges.agent.protocol.connections import ConnectionRegistryfrom switch_core.bridges.agent.protocol.event_buffer import EventBufferfrom switch_core.bridges.agent.protocol.service import ProtocolService-from switch_core.bridges.agent.request_tracker import RequestTrackerfrom switch_core.bridges.collaboration.lifecycle_service import (CollaborationBridgeLifecycleService,)from switch_core.bridges.resource.service import ResourceService-from switch_core.bridges.resource.tracker import ResourceRequestTrackerfrom switch_core.clients.client_lifecycle_service import ClientLifecycleServicefrom switch_core.config import SwitchConfigfrom switch_core.db.stores.agent_session_store import AgentSessionStore@@ -40,8 +38,6 @@ def init_dependencies(event_buffer: EventBuffer,connections: ConnectionRegistry,task_store: TaskStore,- request_tracker: RequestTracker,- resource_request_tracker: ResourceRequestTracker,resource_service: ResourceService,api_key_store: ApiKeyStore,api_key_cache: ApiKeyCache,@@ -59,8 +55,6 @@ def init_dependencies(_state["event_buffer"] = event_buffer_state["connections"] = connections_state["task_store"] = task_store- _state["request_tracker"] = request_tracker- _state["resource_request_tracker"] = resource_request_tracker_state["resource_service"] = resource_service_state["api_key_store"] = api_key_store_state["api_key_cache"] = api_key_cache@@ -79,8 +73,6 @@ def init_dependencies(event_buffer=event_buffer,connections=connections,task_store=task_store,- request_tracker=request_tracker,- resource_request_tracker=resource_request_tracker,resource_service=resource_service,api_key_store=api_key_store,api_key_cache=api_key_cache,@@ -120,14 +112,6 @@ def get_task_store() -> TaskStore:return _state["task_store"] # type: ignore[no-any-return]-def get_request_tracker() -> RequestTracker:- return _state["request_tracker"] # type: ignore[no-any-return]---def get_resource_request_tracker() -> ResourceRequestTracker:- return _state["resource_request_tracker"] # type: ignore[no-any-return]--def get_resource_service() -> ResourceService:return _state["resource_service"] # type: ignore[no-any-return]diff --git a/core/switch_core/bridges/agent/mediation.py b/core/switch_core/bridges/agent/mediation.pynew file mode 100644index 000000000..485b3692d--- /dev/null+++ b/core/switch_core/bridges/agent/mediation.py@@ -0,0 +1,71 @@+"""Whether an agent may use the tool or model it is about to use.++Two checks, both a lookup against what the agent has attached. They used to be+reached by posting a Matrix event into a room and waiting up to ten seconds for+an answer that was computed in the same process — see the commit that moved+them here for why that was not doing anything a function call does not.++Post-invocation mediation is not here, because there is nothing to decide: the+`post_tool_result` and `post_llm_response` hooks exist as places to inspect+what came back, and today they inspect nothing. Adding a check to them means+adding it here.+"""++from __future__ import annotations++from typing import TYPE_CHECKING, NamedTuple++if TYPE_CHECKING:+ from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker++ from switch_core.db.stores.agent_store import AgentStore++# What a caller gets back. `proceed` is the only verdict that lets the call+# happen; anything else carries a reason, because a refusal a user cannot act+# on is barely better than a crash.+PROCEED = "proceed"+BLOCKED = "blocked"+++class Verdict(NamedTuple):+ verdict: str+ reason: str | None++ @staticmethod+ def proceed() -> Verdict:+ return Verdict(PROCEED, None)++ @staticmethod+ def blocked(reason: str) -> Verdict:+ return Verdict(BLOCKED, reason)+++class MediationService:+ """Decides pre-invocation mediation from what the agent has attached."""++ def __init__(+ self,+ *,+ session_factory: async_sessionmaker[AsyncSession],+ agent_store: AgentStore,+ ) -> None:+ self._session_factory = session_factory+ self._agent_store = agent_store++ async def tool_access(self, agent_id: str, tool_name: str) -> Verdict:+ async with self._session_factory() as session:+ tools = await self._agent_store.get_tools(session, agent_id)+ if any(tool.name == tool_name for tool in tools):+ return Verdict.proceed()+ return Verdict.blocked(+ f"Agent {agent_id} does not have tool '{tool_name}' attached"+ )++ async def model_access(self, agent_id: str, model_name: str) -> Verdict:+ async with self._session_factory() as session:+ models = await self._agent_store.get_models(session, agent_id)+ if any(model.name == model_name for model in models):+ return Verdict.proceed()+ return Verdict.blocked(+ f"Agent {agent_id} does not have model '{model_name}' attached"+ )diff --git a/core/switch_core/bridges/agent/operations/definitions.py b/core/switch_core/bridges/agent/operations/definitions.pyindex 399a1913c..5fa5e72b1 100644--- a/core/switch_core/bridges/agent/operations/definitions.py+++ b/core/switch_core/bridges/agent/operations/definitions.py@@ -402,22 +402,14 @@ async def load_internal_documents(ids: list[str]) -> list[dict[str, Any]]:the requested ids. Raises an error if any id is not attached to thecurrent room.- The load goes through the Switch resource manager as a Matrix event- round-trip, mirroring how tool and LLM mediation works."""- import uuid-agent_id = get_agent_id()room_id = await require_connected_room()protocol = get_protocol()- await protocol.require_room_member(agent_id, room_id)- request_id = str(uuid.uuid4())return await protocol.request_document_load(agent_id=agent_id,room_id=room_id,document_ids=ids,- request_id=request_id,- timeout=30.0,)@@ -446,17 +438,13 @@ async def create_room_document(content: Full text content (max 1 MiB).Returns:- ``{"document_id": "..."}`` once the resource manager confirms creation.+ ``{"document_id": "..."}``."""- import uuid-if len(content.encode("utf-8")) > _ROOM_DOCUMENT_MAX_CONTENT_BYTES:raise ValueError(f"content exceeds {_ROOM_DOCUMENT_MAX_CONTENT_BYTES} bytes")agent_id = get_agent_id()room_id = await require_connected_room()protocol = get_protocol()- await protocol.require_room_member(agent_id, room_id)- request_id = str(uuid.uuid4())document_id = await protocol.request_room_document_create(agent_id=agent_id,room_id=room_id,@@ -464,8 +452,6 @@ async def create_room_document(description=description,instructions=instructions,content=content,- request_id=request_id,- timeout=30.0,)return {"document_id": document_id}@@ -483,8 +469,6 @@ async def update_room_document(Only the agent that created the document can update it. Pass only thefields you want to change; omit (or set to None) the others."""- import uuid-if (content is not Noneand len(content.encode("utf-8")) > _ROOM_DOCUMENT_MAX_CONTENT_BYTES@@ -493,8 +477,6 @@ async def update_room_document(agent_id = get_agent_id()room_id = await require_connected_room()protocol = get_protocol()- await protocol.require_room_member(agent_id, room_id)- request_id = str(uuid.uuid4())await protocol.request_room_document_update(agent_id=agent_id,room_id=room_id,@@ -503,8 +485,6 @@ async def update_room_document(description=description,instructions=instructions,content=content,- request_id=request_id,- timeout=30.0,)return {"document_id": document_id, "status": "ok"}@@ -516,19 +496,13 @@ async def delete_room_document(document_id: str) -> dict[str, str]:Only the agent that created the document can delete it via MCP. Userscan also delete from the room UI as an admin escape hatch."""- import uuid-agent_id = get_agent_id()room_id = await require_connected_room()protocol = get_protocol()- await protocol.require_room_member(agent_id, room_id)- request_id = str(uuid.uuid4())await protocol.request_room_document_delete(agent_id=agent_id,room_id=room_id,document_id=document_id,- request_id=request_id,- timeout=30.0,)return {"document_id": document_id, "status": "ok"}@@ -565,9 +539,8 @@ async def read_context(`limit`, or page backwards with `before`, before concluding you have thefull picture. `oldest_timestamp` marks where to resume, but it is epochmilliseconds while `before` is parsed as ISO-8601: convert it rather than- passing it straight back. `truncated` is deliberately conservative: a read- that ends exactly on `limit` reports truncated even if nothing older- exists.+ passing it straight back. `truncated` is exact: a read that ends exactly on+ `limit` with nothing older behind it reports False.`attachments` is a (usually empty) list of files on the message, each{"filename", "mimetype", "size", "mxc", "msgtype"}. Any file type candiff --git a/core/switch_core/bridges/agent/protocol/service.py b/core/switch_core/bridges/agent/protocol/service.pyindex 8b168cf18..3bde439c8 100644--- a/core/switch_core/bridges/agent/protocol/service.py+++ b/core/switch_core/bridges/agent/protocol/service.py@@ -8,16 +8,7 @@ import uuidfrom collections.abc import Sequencefrom datetime import UTC, datetimefrom typing import TYPE_CHECKING, Any-from urllib.parse import quote--from nio import (- DownloadError,- RoomContextError,- RoomGetEventError,- RoomMemberEvent,- RoomMessageMedia,- RoomMessagesError,-)+from sqlalchemy import func, selectfrom switch_core.addressing import (@@ -29,8 +20,10 @@ from switch_core.addressing import (from switch_core.agent_display_name import normalise_display_namefrom switch_core.agent_icon import normalise_icon_url, validate_icon_urlfrom switch_core.aliases import check_alias_collisions, validate_alias_format+from switch_core.attachments import parse_attachment_groupfrom switch_core.authz import Action, Principal, require, require_managefrom switch_core.bridges.agent.api_key_cache import ApiKeyCache+from switch_core.bridges.agent.mediation import MediationServicefrom switch_core.bridges.agent.protocol.agent_detail import (apply_agent_options,assemble_agent_detail,@@ -58,13 +51,13 @@ from switch_core.bridges.agent.protocol.types import (ToolCallReport,ToolSpec,)-from switch_core.bridges.agent.request_tracker import RequestTrackerfrom switch_core.bridges.resource.service import ResourceService-from switch_core.bridges.resource.tracker import ResourceRequestTrackerfrom switch_core.crypto import encrypt_tokenfrom switch_core.db.models import (Agent,ApiKey,+ Message,+ MessageAttachment,Model,Reference,RoleLease,@@ -81,6 +74,7 @@ from switch_core.db.stores.agent_runtime_state_store import (from switch_core.db.stores.agent_runtime_state_store import (AgentRuntimeStateStore,)+from switch_core.db.stores.message_store import MessageStorefrom switch_core.db.stores.room_group_store import RoomGroupStorefrom switch_core.db.stores.room_role_store import RoomRoleStorefrom switch_core.db.stores.user_store import UserStore@@ -91,6 +85,10 @@ from switch_core.events import (from switch_core.events import (ToolCallReport as MatrixToolCallReport,)+from switch_core.messages.recorded_types import MEMBERSHIP_EVENT_TYPE+from switch_core.transport import (+ TransportError,+)if TYPE_CHECKING:from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker@@ -119,17 +117,82 @@ logger = logging.getLogger(__name__)# trailing newline, which would let an identifier carry a line break._VALID_NAME_RE = re.compile(r"\A[a-z0-9][a-z0-9._-]*\Z")-# History pagination. The homeserver caps a /messages page regardless of what-# we ask for, and state events consume it without ever reaching the caller, so-# one page is never a reliable window. The page cap bounds a single read_context-# call; hitting it is reported as `truncated` rather than passed off as the-# whole story.-HISTORY_PAGE_SIZE = 100-HISTORY_MAX_PAGES = 20-# Pages spent walking back to a `before` window, budgeted separately from the-# pages spent reading inside it. Only used when the homeserver cannot answer-# timestamp_to_event; a scan is the slow path, so it gets room to succeed.-HISTORY_MAX_SEEK_PAGES = 100+# A hard ceiling on one read_context call, whatever limit the caller asks for.+# History comes from a single indexed query now, so the only thing this guards+# is the size of the response.+HISTORY_MAX_LIMIT = 500++# The post-invocation hooks answer in a different vocabulary from the+# pre-invocation ones: `ok` / `blocked` / `redacted` rather than `proceed` /+# `blocked`. Nothing currently returns anything but this.+POST_INVOCATION_OK = "ok"+++def _epoch_ms(when: Any) -> int | None:+ """A stored timestamp as epoch milliseconds, which is what agents read."""+ if not isinstance(when, datetime):+ return None+ return int(when.timestamp() * 1000)+++def _from_epoch_ms(when: int | None) -> datetime | None:+ if when is None:+ return None+ return datetime.fromtimestamp(when / 1000, tz=UTC)+++def _coalesce_attachment_groups(+ rows: list[Message], attachments: dict[str, list[MessageAttachment]]+) -> tuple[list[Message], dict[str, list[MessageAttachment]]]:+ """Put a multi-file message back together.++ A message carrying several files is sent as one event per file sharing a+ group marker, because the bus has no event that holds more than one. Each+ of those events is recorded on its own row, so history has to reassemble+ them the same way a live receiver does — otherwise a two-file post reads+ back as two posts, the second captioned with a filename.++ The lowest index present leads: it carries the caption and the id the+ sender was handed, and it stays the lead when a later part is missing. A+ group split by the window edge is coalesced from the parts inside it, so a+ page can return fewer entries than rows it read.+ """+ members: dict[str, list[tuple[int, Message]]] = {}+ for row in rows:+ group = parse_attachment_group(row.content or {})+ if group is not None:+ members.setdefault(group[0], []).append((group[1], row))+ if not members:+ return rows, attachments++ merged = dict(attachments)+ absorbed: set[str] = set()+ for parts in members.values():+ parts.sort(key=lambda part: part[0])+ lead = parts[0][1]+ merged[lead.id] = [+ attachment for _, row in parts for attachment in attachments.get(row.id, [])+ ]+ absorbed.update(row.id for _, row in parts[1:])+ return [row for row in rows if row.id not in absorbed], merged+++def _elided_root(root_id: str) -> dict[str, Any]:+ """A stand-in for a thread root with no recorded row.++ Dropping the thread would lose its replies as well, so the root is named+ and marked elided instead — visibly incomplete rather than quietly absent.+ """+ logger.warning("No recorded thread root %s; returning an elided stub", root_id)+ return {+ "id": root_id,+ "kind": "message",+ "sender": None,+ "sender_name": None,+ "body": None,+ "timestamp": None,+ "elided": True,+ }class AgentExistsError(Exception):@@ -161,8 +224,6 @@ class ProtocolService:event_buffer: EventBuffer,connections: ConnectionRegistry,task_store: TaskStore,- request_tracker: RequestTracker,- resource_request_tracker: ResourceRequestTracker,resource_service: ResourceService,api_key_store: ApiKeyStore,api_key_cache: ApiKeyCache,@@ -176,6 +237,7 @@ class ProtocolService:self.agent_runtime_state_store = AgentRuntimeStateStore()self.room_role_store = RoomRoleStore()self.room_group_store = RoomGroupStore()+ self.message_store = MessageStore()self.user_store = UserStore()self.room_store = room_storeself.room_service = room_service@@ -188,9 +250,10 @@ class ProtocolService:# connection set in two.self.connections = connectionsself.task_store = task_store- self.request_tracker = request_tracker- self.resource_request_tracker = resource_request_trackerself.resource_service = resource_service+ self.mediation = MediationService(+ session_factory=session_factory, agent_store=agent_store+ )self.api_key_store = api_key_store# Shared with the bearer-auth middleware for the same reason as# `connections`: a key this service rotates must stop authenticating@@ -911,17 +974,13 @@ class ProtocolService:root. If the event does not exist in the room we fail loud rather thanpost into a non-existent thread."""- if client.nio_client is None:+ if client.transport is None:raise ValueError("Agent client not connected to Matrix")- resp = await client.nio_client.room_get_event(matrix_room_id, thread_id)- if isinstance(resp, RoomGetEventError):+ event = await client.transport.get_event(matrix_room_id, thread_id)+ if event is None:raise ValueError(f"thread_id not found in room: {thread_id}")- relates = resp.event.source.get("content", {}).get("m.relates_to") or {}- if relates.get("rel_type") == "m.thread":- root = relates.get("event_id")- if root:- return str(root)- return thread_id+ root = getattr(event, "thread_root_id", None)+ return str(root) if root else thread_idasync def send_message(self,@@ -1415,12 +1474,12 @@ class ProtocolService:anchor_event_id: str | None = None,) -> None:client = self.client_lifecycle.get_by_agent_id(agent_id)- if client is None or client.nio_client is None:+ if client is None or client.transport is None:logger.debug("No live client for agent %s; skipping runtime-state emit", agent_id)return- await client.nio_client.room_send(+ await client.send_event(matrix_room_id,"com.switch.agent.runtime_state",{@@ -1513,85 +1572,49 @@ class ProtocolService:return here[0] if here else None@staticmethod- def _message_dict(event: Any) -> dict[str, Any]:- """Build the agent-facing message dict from a nio event."""- content = event.source.get("content", {}) if hasattr(event, "source") else {}- sender_name = content.get("sender_name")- if not sender_name:- sender_name = event.sender- body = getattr(event, "body", None)-- attachments: list[dict[str, Any]] = []- if isinstance(event, RoomMessageMedia):- info = content.get("info", {}) or {}- attachments.append(- {- "filename": content.get("filename") or body,- "mimetype": str(info.get("mimetype", "")),- "size": int(info.get("size", 0) or 0),- "mxc": str(event.url),- "msgtype": str(content.get("msgtype", "")),- }- )-- return {- "id": event.event_id,- "kind": "message",- "sender": event.sender,- "sender_name": sender_name,- "body": body,- "timestamp": getattr(event, "server_timestamp", None),- "attachments": attachments,- }-- @staticmethod- def _join_dict(event: RoomMemberEvent) -> dict[str, Any] | None:- """Build a timeline entry for someone joining the room.+ def _timeline_entry(+ message: Message, attachments: list[MessageAttachment]+ ) -> dict[str, Any]:+ """Build the agent-facing entry for a recorded row.- Only a transition *into* join counts: a display-name change or avatar- update is also an m.room.member event with membership "join", and- replaying those as arrivals would be a lie.+ An arrival is stored with no body — how it reads is this function's to+ decide, not the writer's — so the sentence is composed here and can be+ changed without rewriting history."""- if event.membership != "join" or event.prev_membership == "join":- return None- content = event.content or {}- name = content.get("displayname") or event.state_key+ name = message.sender_name or message.sender_matrix_id+ if message.event_type == MEMBERSHIP_EVENT_TYPE:+ return {+ "id": message.transport_event_id,+ "kind": "room_join",+ "sender": message.sender_matrix_id,+ "sender_name": name,+ "body": f"{name} joined the room",+ "timestamp": _epoch_ms(message.sent_at),+ "attachments": [],+ }return {- "id": event.event_id,- "kind": "room_join",- "sender": event.state_key,+ "id": message.transport_event_id,+ "kind": "message",+ "sender": message.sender_matrix_id,"sender_name": name,- "body": f"{name} joined the room",- "timestamp": getattr(event, "server_timestamp", None),- "attachments": [],+ "body": message.body,+ "timestamp": _epoch_ms(message.sent_at),+ "attachments": [+ {+ "filename": attachment.filename,+ "mimetype": attachment.mimetype or "",+ "size": attachment.size or 0,+ "mxc": attachment.uri,+ "msgtype": message.msgtype,+ }+ for attachment in attachments+ ],}- def _timeline_entry(self, event: Any) -> dict[str, Any] | None:- """Map a nio timeline event to an agent-facing entry, or None to skip.-- Messages and joins are the timeline; every other state event (leaves,- topic changes, power levels) is noise an agent cannot act on.- """- if isinstance(event, RoomMemberEvent):- return self._join_dict(event)- if getattr(event, "body", None):- return self._message_dict(event)- return None-@staticmethod- def _thread_root_id(event: Any) -> str:- """Return the thread root id for an event.-- A message that carries an m.thread relation belongs to that root;- anything else is its own root (a top-level message).- """- if hasattr(event, "source"):- relates = event.source.get("content", {}).get("m.relates_to") or {}- if relates.get("rel_type") == "m.thread":- root = relates.get("event_id")- if root:- return str(root)- return str(event.event_id)+ def _thread_root_id(message: Message) -> str:+ """A threaded reply belongs to its root; anything else is its own root."""+ return message.thread_root_event_id or message.transport_event_idasync def read_context(self,@@ -1617,229 +1640,87 @@ class ProtocolService:said and "room_join" for an arrival. Top-level entries are roots withan empty replies list; replies are ordered oldest-first within athread. A root that falls outside the fetched window but has a reply- inside it is fetched on demand; if it cannot be fetched it is returned- as an elided stub so the reply is not lost.+ inside it is fetched alongside; if no record of it exists it is+ returned as an elided stub so the reply is not lost.`truncated` is True when older history exists that this call did not- reach — the caller asked for more than it got. It is deliberately- conservative: a window that ends exactly on `limit` reports truncated- even if nothing older happens to exist. A short history must never be- mistaken for a complete one.+ return. It is exact: the query asks for one row more than the caller+ wanted, and the presence of that row is the answer."""- room = await self.require_room_member(agent_id, room_id)- client = self.client_lifecycle.get_by_agent_id(agent_id)- if client is None:- raise ValueError("Agent client not running")- if client.nio_client is None:- raise ValueError("Agent client not connected to Matrix")-- # Walk backwards page by page until the window is satisfied. A single- # page is not enough: the homeserver caps its size, and state events- # that never reach the caller still consume it.- #- # Reaching a `before` window and reading inside it are budgeted- # separately. Matrix has no timestamp cursor, so a `before` deep in a- # busy room can only be reached by paging over everything newer — and- # if those pages came out of the read budget, a far-enough-back window- # would return empty no matter how small a `limit` the caller asked- # for. Seeking is the cost of getting there, not part of the answer.- groups: dict[str, dict[str, Any]] = {}- collected = 0- oldest_ts: int | None = None- read_pages = 0- seek_pages = 0- exhausted = False+ await self.require_room_member(agent_id, room_id)+ limit = max(1, min(limit, HISTORY_MAX_LIMIT))- start: str | None = None- if before_ms is not None:- start = await self._seek_before_token(- client, room.matrix_room_id, before_ms+ async with self.session_factory() as session:+ # One more than asked for. Whether that row exists is precisely the+ # question `truncated` answers, so there is nothing to estimate and+ # no reason to be conservative about it.+ rows = await self.message_store.list_timeline(+ session,+ room_id,+ limit=limit + 1,+ since=_from_epoch_ms(since_ms),+ before=_from_epoch_ms(before_ms),+ )+ truncated = len(rows) > limit+ rows = rows[:limit]++ # Replies whose root is older than the window. Reading them costs+ # one more query for the whole page rather than one per thread.+ in_window = {row.transport_event_id for row in rows}+ orphan_roots = {+ row.thread_root_event_id+ for row in rows+ if row.thread_root_event_id+ and row.thread_root_event_id not in in_window+ }+ roots = await self.message_store.list_by_transport_event_ids(+ session, room_id, orphan_roots+ )+ attachments = await self.message_store.attachments_for(+ session, [row.id for row in rows + roots])- while collected < limit and read_pages < HISTORY_MAX_PAGES:- if seek_pages >= HISTORY_MAX_SEEK_PAGES:- logger.warning(- "read_context gave up seeking back to %s in %s after "- "%d pages; the window was never reached",- before_ms,- room.matrix_room_id,- seek_pages,- )- break- resp = await client.nio_client.room_messages(- room.matrix_room_id, start=start, limit=HISTORY_PAGE_SIZE- )- if isinstance(resp, RoomMessagesError):- raise ValueError(f"Failed to fetch room history: {resp.message}")-- chunk = list(resp.chunk)- end = getattr(resp, "end", None)- # A page that contributes nothing because everything on it is- # newer than `before` is a seek, not a read.- reached_window = before_ms is None or any(- getattr(e, "server_timestamp", None) is not None- and getattr(e, "server_timestamp") < before_ms- for e in chunk- )- if reached_window:- read_pages += 1- else:- seek_pages += 1-- for event in chunk:- ts = getattr(event, "server_timestamp", None)- # Newer than the window: keep walking back towards it.- if before_ms is not None and ts is not None and ts >= before_ms:- continue- # Older than the window: pagination runs newest-first, so- # everything beyond this point is older too.- if since_ms is not None and ts is not None and ts < since_ms:- exhausted = True- break-- entry = self._timeline_entry(event)- if entry is None:- continue+ rows, attachments = _coalesce_attachment_groups(rows, attachments)- root_id = self._thread_root_id(event)- group = groups.setdefault(- root_id, {"root": None, "replies": [], "latest": 0}- )- if entry["id"] == root_id:- group["root"] = entry- else:- group["replies"].append(entry)- if ts is not None and ts > group["latest"]:- group["latest"] = ts- if ts is not None and (oldest_ts is None or ts < oldest_ts):- oldest_ts = ts-- collected += 1- if collected >= limit:- break+ entries = {+ row.transport_event_id: self._timeline_entry(+ row, attachments.get(row.id, [])+ )+ for row in rows + roots+ }- if exhausted:- break- # No continuation token, or the server stopped moving: this is the- # start of the room.- if not end or end == start:- exhausted = True- break- start = end+ groups: dict[str, dict[str, Any]] = {}+ oldest_ts: int | None = None+ for row in rows:+ entry = entries[row.transport_event_id]+ root_id = self._thread_root_id(row)+ group = groups.setdefault(+ root_id, {"root": None, "replies": [], "latest": 0}+ )+ if entry["id"] == root_id:+ group["root"] = entry+ else:+ group["replies"].append(entry)+ ts = entry["timestamp"]+ if ts is not None:+ group["latest"] = max(group["latest"], ts)+ oldest_ts = ts if oldest_ts is None else min(oldest_ts, ts)- # Resolve roots that fall outside the fetched window (orphan replies).for root_id, group in groups.items():if group["root"] is None:- group["root"] = await self._fetch_root(- client, room.matrix_room_id, root_id- )+ group["root"] = entries.get(root_id) or _elided_root(root_id)- ordered = sorted(groups.values(), key=lambda g: g["latest"])threads: list[dict[str, Any]] = []- for group in ordered:- group["replies"].reverse() # chunk was newest-first → oldest-first+ for group in sorted(groups.values(), key=lambda g: g["latest"]):+ group["replies"].reverse() # rows came newest-firstthreads.append({"root": group["root"], "replies": group["replies"]})- if not exhausted:- logger.warning(- "read_context truncated in %s: %d entries over %d read pages "- "(%d spent seeking), older history not reached",- room.matrix_room_id,- collected,- read_pages,- seek_pages,- )-return {"threads": threads,- "truncated": not exhausted,+ "truncated": truncated,"oldest_timestamp": oldest_ts,}- async def _seek_before_token(- self, client: ClientBase[Any], matrix_room_id: str, before_ms: int- ) -> str | None:- """Get a pagination token positioned at `before_ms`, if the server can.-- `/messages` takes a token, not a timestamp, so reaching a `before` deep- in a busy room otherwise means paging over everything newer just to- arrive. `timestamp_to_event` (Matrix 1.6) jumps straight there.-- Returns None when the homeserver cannot answer — the caller then walks- back the slow way. A failure here costs speed, not correctness, so it- is logged and swallowed rather than raised.- """- nio_client = client.nio_client- if nio_client is None:- return None- path = (- f"/_matrix/client/v1/rooms/{quote(matrix_room_id, safe='')}"- f"/timestamp_to_event?ts={before_ms}&dir=b"- )- try:- resp = await nio_client.send(- "GET",- path,- headers={"Authorization": f"Bearer {nio_client.access_token}"},- )- if resp.status != 200:- logger.info(- "timestamp_to_event unavailable in %s (HTTP %d); "- "falling back to scanning back to the window",- matrix_room_id,- resp.status,- )- return None- event_id = (await resp.json()).get("event_id")- except Exception:- logger.warning(- "timestamp_to_event failed in %s; falling back to scanning",- matrix_room_id,- exc_info=True,- )- return None- if not event_id:- return None-- context = await nio_client.room_context(matrix_room_id, event_id, limit=1)- if isinstance(context, RoomContextError):- logger.info(- "Could not anchor pagination at %s in %s; scanning instead",- event_id,- matrix_room_id,- )- return None- start_token = context.start- return str(start_token) if start_token else None-- async def _fetch_root(- self, client: ClientBase[Any], matrix_room_id: str, root_id: str- ) -> dict[str, Any]:- """Fetch a thread-root event that fell outside the read window.-- Failure is degraded-but-functional: we return an elided stub (keeping- the replies attached to a known id) rather than dropping the thread.- """- if client.nio_client is None:- raise ValueError("Agent client not connected to Matrix")- resp = await client.nio_client.room_get_event(matrix_room_id, root_id)- if isinstance(resp, RoomGetEventError):- logger.warning(- "Could not fetch thread root %s in %s; returning elided stub",- root_id,- matrix_room_id,- )- return {- "id": root_id,- "kind": "message",- "sender": None,- "sender_name": None,- "body": None,- "timestamp": None,- "elided": True,- }- return self._message_dict(resp.event)-async def download_media(self, agent_id: str, room_id: str, mxc: str) -> tuple[bytes, str, str | None]:@@ -1852,13 +1733,14 @@ class ProtocolService:client = self.client_lifecycle.get_by_agent_id(agent_id)if client is None:raise ValueError("Agent client not running")- if client.nio_client is None:+ if client.transport is None:raise ValueError("Agent client not connected to Matrix")- resp = await client.nio_client.download(mxc=mxc)- if isinstance(resp, DownloadError):- raise ValueError(f"Failed to download media {mxc}: {resp.message}")- return resp.body, resp.content_type, resp.filename+ try:+ resp = await client.transport.download_media(mxc)+ except TransportError as exc:+ raise ValueError(f"Failed to download media {mxc}: {exc}") from exc+ return resp.body, resp.content_type or "", resp.filename# ── Events ───────────────────────────────────────────────────────────────@@ -1921,7 +1803,7 @@ class ProtocolService:client = self.client_lifecycle.get_by_agent_id(agent_id)if client is None:raise ValueError("Agent client not running")- if client.nio_client is None:+ if client.transport is None:raise ValueError("Agent client not connected to Matrix")for event in events:@@ -1934,7 +1816,7 @@ class ProtocolService:duration_ms=event.duration_ms,cost=event.cost,)- await client.nio_client.room_send(+ await client.send_event(room.matrix_room_id,"com.switch.report.tool_call",tool_event.model_dump(exclude_none=True),@@ -1949,7 +1831,7 @@ class ProtocolService:duration_ms=event.duration_ms,cost=event.cost,)- await client.nio_client.room_send(+ await client.send_event(room.matrix_room_id,"com.switch.report.llm_call",llm_event.model_dump(exclude_none=True),@@ -2008,8 +1890,8 @@ class ProtocolService:task_id = task.idclient = self.client_lifecycle.get_by_agent_id(requester_id)- if client and client.nio_client:- await client.nio_client.room_send(+ if client and client.transport:+ await client.send_event(room.matrix_room_id,"com.switch.task.delegate",{@@ -2043,8 +1925,8 @@ class ProtocolService:await session.commit()client = self.client_lifecycle.get_by_agent_id(agent_id)- if client and client.nio_client:- await client.nio_client.room_send(+ if client and client.transport:+ await client.send_event(room.matrix_room_id,"com.switch.task.accept",{@@ -2076,8 +1958,8 @@ class ProtocolService:await session.commit()client = self.client_lifecycle.get_by_agent_id(agent_id)- if client and client.nio_client:- await client.nio_client.room_send(+ if client and client.transport:+ await client.send_event(room.matrix_room_id,"com.switch.task.update",{@@ -2110,8 +1992,8 @@ class ProtocolService:await session.commit()client = self.client_lifecycle.get_by_agent_id(agent_id)- if client and client.nio_client:- await client.nio_client.room_send(+ if client and client.transport:+ await client.send_event(room.matrix_room_id,"com.switch.task.finalise",{@@ -2140,8 +2022,8 @@ class ProtocolService:await session.commit()client = self.client_lifecycle.get_by_agent_id(agent_id)- if client and client.nio_client:- await client.nio_client.room_send(+ if client and client.transport:+ await client.send_event(room.matrix_room_id,"com.switch.task.cancel",{@@ -3454,41 +3336,16 @@ class ProtocolService:room_id: str,tool_name: str,arguments: dict[str, Any],- request_id: str,- timeout: float,) -> dict[str, Any]:- """Request mediation before tool call. Returns verdict and reason."""- import asyncio-- room = await self.require_room_member(agent_id, room_id)- client = self.client_lifecycle.get_by_agent_id(agent_id)- if client is None:- raise ValueError("Agent client not running")- if client.nio_client is None:- raise ValueError("Agent client not connected")+ """Whether this agent may call this tool. Verdict and reason.- future = self.request_tracker.register(- request_id, agent_id, room.matrix_room_id- )- await client.nio_client.room_send(- room.matrix_room_id,- "com.switch.mediation.tool_request",- {- "request_id": request_id,- "agent_id": agent_id,- "tool_id": tool_name,- "args": arguments,- "status": "pending",- },- )-- try:- result = await asyncio.wait_for(future, timeout=timeout)- except TimeoutError:- self.request_tracker.cancel(request_id)- raise ValueError("Mediation verdict timed out")-- return {"verdict": result.verdict, "reason": result.reason}+ `arguments` is not inspected. It is accepted because a mediation+ decision that looks at what is being passed is the obvious next thing+ to want, and because the hook already sends it.+ """+ await self.require_room_member(agent_id, room_id)+ verdict = await self.mediation.tool_access(agent_id, tool_name)+ return {"verdict": verdict.verdict, "reason": verdict.reason}async def pre_llm_request(self,@@ -3496,41 +3353,14 @@ class ProtocolService:room_id: str,model: str,messages: list[dict[str, Any]],- request_id: str,- timeout: float,) -> dict[str, Any]:- """Request mediation before LLM request. Returns verdict and reason."""- import asyncio-- room = await self.require_room_member(agent_id, room_id)- client = self.client_lifecycle.get_by_agent_id(agent_id)- if client is None:- raise ValueError("Agent client not running")- if client.nio_client is None:- raise ValueError("Agent client not connected")+ """Whether this agent may call this model. Verdict and reason.- future = self.request_tracker.register(- request_id, agent_id, room.matrix_room_id- )- await client.nio_client.room_send(- room.matrix_room_id,- "com.switch.mediation.llm_request",- {- "request_id": request_id,- "agent_id": agent_id,- "model_id": model,- "messages": messages,- "status": "pending",- },- )-- try:- result = await asyncio.wait_for(future, timeout=timeout)- except TimeoutError:- self.request_tracker.cancel(request_id)- raise ValueError("Mediation verdict timed out")-- return {"verdict": result.verdict, "reason": result.reason}+ `messages` is not inspected, for the same reason `arguments` is not.+ """+ await self.require_room_member(agent_id, room_id)+ verdict = await self.mediation.model_access(agent_id, model)+ return {"verdict": verdict.verdict, "reason": verdict.reason}async def post_tool_result(self,@@ -3538,42 +3368,19 @@ class ProtocolService:room_id: str,tool_name: str,result: Any,- request_id: str,- timeout: float,) -> dict[str, Any]:- """Request mediation after tool result. Returns verdict."""- import asyncio+ """The hook point after a tool returns. Nothing is decided here yet.- room = await self.require_room_member(agent_id, room_id)- rm_clients = self.client_lifecycle.get_by_type("resource_manager")- if not rm_clients:- raise ValueError("Resource manager client not running")- rm = rm_clients[0]- if rm.nio_client is None:- raise ValueError("Resource manager client not connected")-- future = self.request_tracker.register(- request_id, agent_id, room.matrix_room_id- )- await rm.nio_client.room_send(- room.matrix_room_id,- "com.switch.mediation.tool_result",- {- "request_id": request_id,- "agent_id": agent_id,- "tool_id": tool_name,- "result": result,- "status": "ok",- },- )-- try:- med_result = await asyncio.wait_for(future, timeout=timeout)- except TimeoutError:- self.request_tracker.cancel(request_id)- raise ValueError("Mediation verdict timed out")+ It has always returned `ok` unconditionally — the verdict used to be+ the literal string this method itself put on the wire and then read+ back off it. Kept as the place a post-invocation check would go, and+ as the membership check the caller is entitled to fail on.- return {"verdict": med_result.verdict}+ Note the vocabulary differs from the pre-invocation hooks: these+ answer `ok` / `blocked` / `redacted`, not `proceed` / `blocked`.+ """+ await self.require_room_member(agent_id, room_id)+ return {"verdict": POST_INVOCATION_OK}async def list_room_resources(self, room_id: str) -> dict[str, Any]:"""Return the {reference_types, references, documents} payload for a@@ -3584,49 +3391,23 @@ class ProtocolService:async def request_document_load(self,+ *,agent_id: str,room_id: str,document_ids: list[str],- request_id: str,- timeout: float,) -> list[dict[str, Any]]:- """Dispatch a com.switch.resource.load_request as the agent and await- the resource manager's response. Raises on error / timeout."""- import asyncio+ """Load documents attached to this room.- room = await self.require_room_member(agent_id, room_id)- client = self.client_lifecycle.get_by_agent_id(agent_id)- if client is None:- raise ValueError("Agent client not running")- if client.nio_client is None:- raise ValueError("Agent client not connected")-- future = self.resource_request_tracker.register(- request_id, agent_id, room.matrix_room_id- )- await client.nio_client.room_send(- room.matrix_room_id,- "com.switch.resource.load_request",- {- "request_id": request_id,- "agent_id": agent_id,- "document_ids": document_ids,- },- )-- from switch_core.bridges.resource.events import ResourceLoadResponse-- try:- response = await asyncio.wait_for(future, timeout=timeout)- except TimeoutError:- self.resource_request_tracker.cancel(request_id)- raise ValueError("Resource load timed out") from None-- if not isinstance(response, ResourceLoadResponse):- raise ValueError(f"Unexpected response type: {type(response).__name__}")- if response.status != "ok":- raise ValueError(response.error or "Resource manager returned an error")- return [d.model_dump(mode="json") for d in response.documents]+ The service checks each id is attached here, which is what stops a+ document being read across a room boundary. Membership is checked+ first, so an agent that is not in the room never reaches it.+ """+ await self.require_room_member(agent_id, room_id)+ async with self.session_factory() as session:+ entries = await self.resource_service.load_documents(+ session, room_id, document_ids+ )+ return [entry.model_dump(mode="json") for entry in entries]async def request_room_document_create(self,@@ -3637,51 +3418,29 @@ class ProtocolService:description: str,instructions: str,content: str,- request_id: str,- timeout: float,) -> str:- import asyncio-room = await self.require_room_member(agent_id, room_id)- client = self.client_lifecycle.get_by_agent_id(agent_id)- if client is None or client.nio_client is None:- raise ValueError("Agent client not connected")-- future = self.resource_request_tracker.register(- request_id, agent_id, room.matrix_room_id- )- await client.nio_client.room_send(- room.matrix_room_id,- "com.switch.resource.room_document_create_request",- {- "request_id": request_id,- "agent_id": agent_id,- "name": name,- "description": description,- "instructions": instructions,- "content": content,- },- )-- from switch_core.bridges.resource.events import RoomDocumentCreateResponse+ async with self.session_factory() as session:+ agent = await self.agent_store.get(session, agent_id)+ document = await self.resource_service.create_room_document(+ session,+ room_id=room_id,+ agent_id=agent_id,+ owner_id=agent.owner_id if agent is not None else None,+ name=name,+ description=description,+ instructions=instructions,+ content=content,+ )+ document_id, document_name = document.id, document.name+ await session.commit()- try:- response = await asyncio.wait_for(future, timeout=timeout)- except TimeoutError:- self.resource_request_tracker.cancel(request_id)- raise ValueError("Room document create timed out") from None-- if not isinstance(response, RoomDocumentCreateResponse):- raise ValueError(f"Unexpected response type: {type(response).__name__}")- if response.status != "ok" or response.document_id is None:- raise ValueError(response.error or "Resource manager returned an error")-- await self._post_agent_notice(- client,+ await self._announce_document(+ agent_id,room.matrix_room_id,- f"📄 created room document “{response.document_name or name}”.",+ f"\U0001f4c4 created room document \u201c{document_name}\u201d.",)- return response.document_id+ return document_idasync def request_room_document_update(self,@@ -3693,50 +3452,26 @@ class ProtocolService:description: str | None,instructions: str | None,content: str | None,- request_id: str,- timeout: float,) -> None:- import asyncio-room = await self.require_room_member(agent_id, room_id)- client = self.client_lifecycle.get_by_agent_id(agent_id)- if client is None or client.nio_client is None:- raise ValueError("Agent client not connected")-- future = self.resource_request_tracker.register(- request_id, agent_id, room.matrix_room_id- )- await client.nio_client.room_send(- room.matrix_room_id,- "com.switch.resource.room_document_update_request",- {- "request_id": request_id,- "agent_id": agent_id,- "document_id": document_id,- "name": name,- "description": description,- "instructions": instructions,- "content": content,- },- )-- from switch_core.bridges.resource.events import RoomDocumentUpdateResponse+ async with self.session_factory() as session:+ document = await self.resource_service.update_room_document(+ session,+ room_id=room_id,+ agent_id=agent_id,+ document_id=document_id,+ name=name,+ description=description,+ instructions=instructions,+ content=content,+ )+ document_name = document.name+ await session.commit()- try:- response = await asyncio.wait_for(future, timeout=timeout)- except TimeoutError:- self.resource_request_tracker.cancel(request_id)- raise ValueError("Room document update timed out") from None-- if not isinstance(response, RoomDocumentUpdateResponse):- raise ValueError(f"Unexpected response type: {type(response).__name__}")- if response.status != "ok":- raise ValueError(response.error or "Resource manager returned an error")-- await self._post_agent_notice(- client,+ await self._announce_document(+ agent_id,room.matrix_room_id,- f"📄 updated room document “{response.document_name or document_id}”.",+ f"\U0001f4c4 updated room document \u201c{document_name}\u201d.",)async def request_room_document_delete(@@ -3745,47 +3480,49 @@ class ProtocolService:agent_id: str,room_id: str,document_id: str,- request_id: str,- timeout: float,) -> None:- import asyncio-room = await self.require_room_member(agent_id, room_id)- client = self.client_lifecycle.get_by_agent_id(agent_id)- if client is None or client.nio_client is None:- raise ValueError("Agent client not connected")+ async with self.session_factory() as session:+ # Read the name before deleting it: the notice says what went, and+ # after the delete there is nothing left to ask.+ document = await self.resource_service.get_room_scoped_document(+ session, room_id, document_id+ )+ document_name = document.name+ await self.resource_service.delete_room_document(+ session,+ room_id=room_id,+ agent_id=agent_id,+ document_id=document_id,+ )+ await session.commit()- future = self.resource_request_tracker.register(- request_id, agent_id, room.matrix_room_id- )- await client.nio_client.room_send(+ await self._announce_document(+ agent_id,room.matrix_room_id,- "com.switch.resource.room_document_delete_request",- {- "request_id": request_id,- "agent_id": agent_id,- "document_id": document_id,- },+ f"\U0001f5d1 deleted room document \u201c{document_name}\u201d.",)- from switch_core.bridges.resource.events import RoomDocumentDeleteResponse+ async def _announce_document(+ self, agent_id: str, matrix_room_id: str, body: str+ ) -> None:+ """Say in the room what the agent just did to a document.- try:- response = await asyncio.wait_for(future, timeout=timeout)- except TimeoutError:- self.resource_request_tracker.cancel(request_id)- raise ValueError("Room document delete timed out") from None-- if not isinstance(response, RoomDocumentDeleteResponse):- raise ValueError(f"Unexpected response type: {type(response).__name__}")- if response.status != "ok":- raise ValueError(response.error or "Resource manager returned an error")-- await self._post_agent_notice(- client,- room.matrix_room_id,- f"🗑 deleted room document “{response.document_name or document_id}”.",- )+ Best-effort, and deliberately after the commit: the change has already+ happened, and failing to narrate it must neither undo it nor fail the+ call that made it. A missing client is worth a line in the log — the+ room is now out of step with the database and nobody in it was told.+ """+ client = self.client_lifecycle.get_by_agent_id(agent_id)+ if client is None or client.transport is None:+ logger.warning(+ "Agent %s has no connected client, so its document change in "+ "%s was not announced in the room",+ agent_id,+ matrix_room_id,+ )+ return+ await self._post_agent_notice(client, matrix_room_id, body)async def post_llm_response(self,@@ -3793,39 +3530,11 @@ class ProtocolService:room_id: str,model: str,response: Any,- request_id: str,- timeout: float,) -> dict[str, Any]:- """Request mediation after LLM response. Returns verdict."""- import asyncio+ """The hook point after a model answers. Nothing is decided here yet.- room = await self.require_room_member(agent_id, room_id)- rm_clients = self.client_lifecycle.get_by_type("resource_manager")- if not rm_clients:- raise ValueError("Resource manager client not running")- rm = rm_clients[0]- if rm.nio_client is None:- raise ValueError("Resource manager client not connected")-- future = self.request_tracker.register(- request_id, agent_id, room.matrix_room_id- )- await rm.nio_client.room_send(- room.matrix_room_id,- "com.switch.mediation.llm_response",- {- "request_id": request_id,- "agent_id": agent_id,- "model_id": model,- "response": response,- "status": "ok",- },- )-- try:- med_result = await asyncio.wait_for(future, timeout=timeout)- except TimeoutError:- self.request_tracker.cancel(request_id)- raise ValueError("Mediation verdict timed out")-- return {"verdict": med_result.verdict}+ The counterpart to `post_tool_result`, and unconditional for the same+ reason.+ """+ await self.require_room_member(agent_id, room_id)+ return {"verdict": POST_INVOCATION_OK}diff --git a/core/switch_core/bridges/agent/request_tracker.py b/core/switch_core/bridges/agent/request_tracker.pydeleted file mode 100644index 807415010..000000000--- a/core/switch_core/bridges/agent/request_tracker.py+++ /dev/null@@ -1,40 +0,0 @@-from __future__ import annotations--import asyncio-import logging--from switch_core.events import MediationResult--logger = logging.getLogger(__name__)---class RequestTracker:- def __init__(self) -> None:- self._pending: dict[str, tuple[str, str, asyncio.Future[MediationResult]]] = {}-- def register(- self, request_id: str, agent_id: str, room_id: str- ) -> asyncio.Future[MediationResult]:- loop = asyncio.get_running_loop()- future: asyncio.Future[MediationResult] = loop.create_future()- self._pending[request_id] = (agent_id, room_id, future)- return future-- def resolve(self, request_id: str, result: MediationResult) -> None:- entry = self._pending.pop(request_id, None)- if entry is None:- logger.warning("Verdict for unknown request_id: %s", request_id)- return- _, _, future = entry- if not future.done():- future.set_result(result)-- def cancel(self, request_id: str) -> None:- entry = self._pending.pop(request_id, None)- if entry is not None:- _, _, future = entry- if not future.done():- future.cancel()-- def is_pending(self, request_id: str) -> bool:- return request_id in self._pendingdiff --git a/core/switch_core/bridges/collaboration/bridge_core.py b/core/switch_core/bridges/collaboration/bridge_core.pyindex 7165ffff9..f857ef94d 100644--- a/core/switch_core/bridges/collaboration/bridge_core.py+++ b/core/switch_core/bridges/collaboration/bridge_core.py@@ -7,13 +7,6 @@ import uuidfrom dataclasses import dataclass, fieldfrom typing import TYPE_CHECKING, Any-from nio import (- DownloadError,- MatrixRoom,- RoomMessageMedia,- RoomMessageText,- RoomSendError,-)from sqlalchemy.exc import IntegrityErrorfrom sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker@@ -42,8 +35,18 @@ from switch_core.db.stores.client_store import ClientStorefrom switch_core.db.stores.external_user_store import ExternalUserStorefrom switch_core.db.stores.room_store import RoomStorefrom switch_core.events import AgentRuntimeStateEvent-from switch_core.matrix_admin import MatrixAdmin+from switch_core.provisioning import Provisioningfrom switch_core.room_service import RoomCreateConfig+from switch_core.transport import (+ InboundMedia as TransportMedia,+)+from switch_core.transport import (+ InboundMessage as TransportMessage,+)+from switch_core.transport import (+ RoomRef,+ TransportError,+)if TYPE_CHECKING:from switch_core.clients.client_lifecycle_service import ClientLifecycleService@@ -116,7 +119,7 @@ class BridgeCore:client_store: ClientStore,room_service: RoomService,client_lifecycle: ClientLifecycleService,- matrix_admin: MatrixAdmin,+ matrix_admin: Provisioning,session_factory: async_sessionmaker[AsyncSession],matrix_server_name: str,bridge_client_matrix_user_id: str,@@ -657,16 +660,16 @@ class BridgeCore:"event_id": existing_matrix_root,}- resp = await puppet.client.room_send(- matrix_room_id, "com.switch.command", content- )-- if isinstance(resp, RoomSendError):+ try:+ event_id = await puppet.send_event(+ matrix_room_id, "com.switch.command", content+ )+ except TransportError as exc:logger.error("Failed to bridge command %s into %s: %s",cmd.command,matrix_room_id,- resp.message,+ exc,)return@@ -678,15 +681,15 @@ class BridgeCore:# Anchor in memory before the DB write: the write awaits a query that# yields the loop, and a fast reply (e.g. !help) relayed in that gap# would miss the row and land at the channel root. Popped on commit.- self._prerecord_message_map(resp.event_id, thread_root_post)+ self._prerecord_message_map(event_id, thread_root_post)try:await self._record_message_map(external_channel_id=cmd.channel_id,- matrix_event_id=resp.event_id,+ matrix_event_id=event_id,external_post_id=thread_root_post,)finally:- self._pending_message_maps.pop(resp.event_id, None)+ self._pending_message_maps.pop(event_id, None)async def _handle_agent_joined_channel(self, join: InboundAgentJoin) -> None:lock = self._channel_locks.setdefault(join.channel_id, asyncio.Lock())@@ -1250,7 +1253,7 @@ class BridgeCore:# ── Outbound (room → platform) ──────────────────────────────────────────async def handle_outbound_message(- self, room: MatrixRoom, event: RoomMessageText+ self, room: RoomRef, event: TransportMessage) -> None:logger.debug("[BRIDGE-OUT] matrix event from=%s room=%s body=%s",@@ -1270,9 +1273,9 @@ class BridgeCore:logger.debug("[BRIDGE-OUT] no channel mapping for room %s", room.room_id)return- event_content = event.source.get("content", {}) or {}+ event_content = event.contentadmin_marker = event_content.get(ADMIN_MARKER)- sender_name = event_content.get("sender_name")+ sender_name = event.sender_name# An admin/system message renders natively per bridge (admin_message)# rather than on behalf of its Matrix sender, so it needs no sender_name.if sender_name is None and admin_marker is None:@@ -1351,8 +1354,8 @@ class BridgeCore:async def handle_outbound_media(self,- room: MatrixRoom,- event: RoomMessageMedia,+ room: RoomRef,+ event: TransportMedia,client: ClientBase[Any],) -> None:"""Relay a Matrix media event (an agent-sent image/file) out to the@@ -1386,8 +1389,8 @@ class BridgeCore:logger.debug("[BRIDGE-OUT] no channel mapping for room %s", room.room_id)return- event_content = event.source.get("content", {}) or {}- sender_name = event_content.get("sender_name")+ event_content = event.content+ sender_name = event.sender_nameif sender_name is None:logger.error("No sender_name in media event from %s — skipping outbound",@@ -1414,7 +1417,7 @@ class BridgeCore:)message_ref: str | None- data = await self._download_matrix_media(client, event.url, filename)+ data = await self._download_matrix_media(client, event.uri, filename)if data is None or len(data) > self._max_attachment_bytes:if data is not None:logger.warning(@@ -1570,18 +1573,17 @@ class BridgeCore:if not mxc:logger.error("[BRIDGE-OUT] media event for %s has no mxc URI", filename)return None- if client.nio_client is None:+ if client.transport is None:logger.error("[BRIDGE-OUT] bridge client not connected; cannot fetch %s", mxc)return None- resp = await client.nio_client.download(mxc=mxc)- if isinstance(resp, DownloadError):- logger.error(- "[BRIDGE-OUT] failed to download media %s: %s", mxc, resp.message- )+ try:+ resp = await client.transport.download_media(mxc)+ except TransportError as exc:+ logger.error("[BRIDGE-OUT] failed to download media %s: %s", mxc, exc)return None- return resp.body # type: ignore[no-any-return]+ return resp.bodyasync def handle_outbound_typing(self, room_id: str, agent_name: str, is_typing: bool@@ -1594,7 +1596,7 @@ class BridgeCore:await self._adapter.send_typing(channel_id, agent_name, is_typing)async def handle_agent_runtime_state(- self, room: MatrixRoom, event: AgentRuntimeStateEvent+ self, room: RoomRef, event: AgentRuntimeStateEvent) -> None:"""Resolve the channel and let the adapter surface the runtime state.diff --git a/core/switch_core/bridges/collaboration/lifecycle_service.py b/core/switch_core/bridges/collaboration/lifecycle_service.pyindex 83c9871ad..ab9b8bdc9 100644--- a/core/switch_core/bridges/collaboration/lifecycle_service.py+++ b/core/switch_core/bridges/collaboration/lifecycle_service.py@@ -12,6 +12,7 @@ from switch_core.bridges.collaboration.adapter import CollaborationAdapterfrom switch_core.bridges.collaboration.bridge_core import BridgeCorefrom switch_core.bridges.collaboration.models import BridgeConnectionConfigfrom switch_core.clients.bridge_client import BridgeClient, BridgeClientConfig+from switch_core.clients.client_factory import ClientFactoryfrom switch_core.config import SwitchConfigfrom switch_core.db.models import CollaborationBridgefrom switch_core.db.stores.agent_store import AgentStore@@ -20,7 +21,7 @@ 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 ExternalUserStorefrom switch_core.db.stores.room_store import RoomStore-from switch_core.matrix_admin import MatrixAdmin+from switch_core.provisioning import Provisioningif TYPE_CHECKING:from switch_core.clients.client_lifecycle_service import ClientLifecycleService@@ -60,9 +61,10 @@ class CollaborationBridgeLifecycleService:client_store: ClientStore,client_lifecycle: ClientLifecycleService,room_service: RoomService,- matrix_admin: MatrixAdmin,+ matrix_admin: Provisioning,session_factory: async_sessionmaker[AsyncSession],config: SwitchConfig,+ client_factory: ClientFactory,) -> None:self._bridge_store = bridge_storeself._external_user_store = external_user_store@@ -75,6 +77,7 @@ class CollaborationBridgeLifecycleService:self._matrix_admin = matrix_adminself._session_factory = session_factoryself._config = config+ self._client_factory = client_factoryself._adapter_registry: dict[str, type[CollaborationAdapter]] = {}self._config_registry: dict[str, type[BridgeConnectionConfig]] = {}@@ -417,8 +420,12 @@ class CollaborationBridgeLifecycleService:session_factory=self._session_factory,client_store=self._client_store,config=BridgeClientConfig(bridge_id=bridge_id),- device_id=bridge_client_record.device_id,- access_token=bridge_client_record.access_token,+ transport_factory=self._client_factory.transport_for,+ message_recorder=self._client_factory.recorder(),+ session_state={+ "access_token": bridge_client_record.access_token,+ "device_id": bridge_client_record.device_id,+ },next_batch_token=bridge_client_record.next_batch_token,)@@ -450,6 +457,36 @@ class CollaborationBridgeLifecycleService:)await session.commit()+ async def _record_bridge_memberships(self, bridge_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+ inviting its client and letting the homeserver hold the membership —+ so nothing wrote it down. Once `client_rooms` became what a client+ reads its rooms from, a bridge that had never been re-invited was in+ none of them: it still received from the platform, because inbound+ posts into a room by id, and relayed nothing back out.++ Run at every start rather than repaired once, because the rooms a+ bridge carries change while it is stopped.+ """+ async with self._session_factory() as session:+ rooms = await self._room_store.get_by_bridge(session, bridge_id)+ added = 0+ for room in rooms:+ members = await self._room_store.get_client_ids(session, room.id)+ if client_id in members:+ continue+ await self._room_store.add_client(session, client_id, room.id)+ added += 1+ await session.commit()+ if added:+ logger.info(+ "Recorded bridge %s as a member of %d room(s) it carries",+ bridge_id,+ added,+ )+async def _run_bridge(self,bridge_id: str,@@ -457,6 +494,7 @@ class CollaborationBridgeLifecycleService: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:diff --git a/core/switch_core/bridges/resource/__init__.py b/core/switch_core/bridges/resource/__init__.pyindex 8eefc24e7..e09607e4f 100644--- a/core/switch_core/bridges/resource/__init__.py+++ b/core/switch_core/bridges/resource/__init__.py@@ -1,8 +1,4 @@-from switch_core.bridges.resource.events import (- ResourceLoadEntry,- ResourceLoadRequest,- ResourceLoadResponse,-)+from switch_core.bridges.resource.events import ResourceLoadEntryfrom switch_core.bridges.resource.registry import (BUILTIN_REFERENCE_TYPES,ReferenceTypeSpec,@@ -11,16 +7,12 @@ from switch_core.bridges.resource.registry import (validate_reference_value,)from switch_core.bridges.resource.service import ResourceService-from switch_core.bridges.resource.tracker import ResourceRequestTracker__all__ = ["BUILTIN_REFERENCE_TYPES","ReferenceTypeSpec","ReferenceValue","ResourceLoadEntry",- "ResourceLoadRequest",- "ResourceLoadResponse",- "ResourceRequestTracker","ResourceService","is_builtin_type","validate_reference_value",diff --git a/core/switch_core/bridges/resource/events.py b/core/switch_core/bridges/resource/events.pyindex 3d2a43904..0706c962f 100644--- a/core/switch_core/bridges/resource/events.py+++ b/core/switch_core/bridges/resource/events.py@@ -8,70 +8,3 @@ class ResourceLoadEntry(SwitchEvent):name: strdescription: strcontent: str---class ResourceLoadRequest(SwitchEvent):- request_id: str- agent_id: str- document_ids: list[str]---class ResourceLoadResponse(SwitchEvent):- request_id: str- agent_id: str- status: str # "ok" | "error"- documents: list[ResourceLoadEntry] = []- error: str | None = None---# ── Room-scoped document mutations (agent-created via MCP) ────────────────---class RoomDocumentCreateRequest(SwitchEvent):- request_id: str- agent_id: str- name: str- description: str- instructions: str- content: str---class RoomDocumentCreateResponse(SwitchEvent):- request_id: str- agent_id: str- status: str # "ok" | "error"- document_id: str | None = None- document_name: str | None = None- error: str | None = None---class RoomDocumentUpdateRequest(SwitchEvent):- request_id: str- agent_id: str- document_id: str- name: str | None = None- description: str | None = None- instructions: str | None = None- content: str | None = None---class RoomDocumentUpdateResponse(SwitchEvent):- request_id: str- agent_id: str- status: str- document_name: str | None = None- error: str | None = None---class RoomDocumentDeleteRequest(SwitchEvent):- request_id: str- agent_id: str- document_id: str---class RoomDocumentDeleteResponse(SwitchEvent):- request_id: str- agent_id: str- status: str- document_name: str | None = None- error: str | None = Nonediff --git a/core/switch_core/bridges/resource/tracker.py b/core/switch_core/bridges/resource/tracker.pydeleted file mode 100644index 0361ab7a2..000000000--- a/core/switch_core/bridges/resource/tracker.py+++ /dev/null@@ -1,55 +0,0 @@-from __future__ import annotations--import asyncio-import logging--from switch_core.bridges.resource.events import (- ResourceLoadResponse,- RoomDocumentCreateResponse,- RoomDocumentDeleteResponse,- RoomDocumentUpdateResponse,-)--logger = logging.getLogger(__name__)--ResourceResponse = (- ResourceLoadResponse- | RoomDocumentCreateResponse- | RoomDocumentUpdateResponse- | RoomDocumentDeleteResponse-)---class ResourceRequestTracker:- """Tracks in-flight resource round-trips (loads + room-document mutations).- Mirrors RequestTracker for the mediation flow."""-- def __init__(self) -> None:- self._pending: dict[str, tuple[str, str, asyncio.Future[ResourceResponse]]] = {}-- def register(- self, request_id: str, agent_id: str, room_id: str- ) -> asyncio.Future[ResourceResponse]:- loop = asyncio.get_running_loop()- future: asyncio.Future[ResourceResponse] = loop.create_future()- self._pending[request_id] = (agent_id, room_id, future)- return future-- def resolve(self, request_id: str, response: ResourceResponse) -> None:- entry = self._pending.pop(request_id, None)- if entry is None:- logger.warning("Resource response for unknown request_id: %s", request_id)- return- _, _, future = entry- if not future.done():- future.set_result(response)-- def cancel(self, request_id: str) -> None:- entry = self._pending.pop(request_id, None)- if entry is not None:- _, _, future = entry- if not future.done():- future.cancel()-- def is_pending(self, request_id: str) -> bool:- return request_id in self._pendingdiff --git a/core/switch_core/cli/__init__.py b/core/switch_core/cli/__init__.pynew file mode 100644index 000000000..ecf3a7887--- /dev/null+++ b/core/switch_core/cli/__init__.py@@ -0,0 +1,8 @@+"""Operator commands that ship inside the image.++These live in the package rather than under `scripts/` because the deployed+image contains only `switch_core` — a script outside it cannot be run by a+Kubernetes Job or a Compose service, which is where the migration commands+have to run. They reach the homeserver and the database directly, so they are+invoked deliberately, never on every release.+"""diff --git a/core/switch_core/cli/backfill.py b/core/switch_core/cli/backfill.pynew file mode 100644index 000000000..b7fc13d31--- /dev/null+++ b/core/switch_core/cli/backfill.py@@ -0,0 +1,191 @@+"""Reconstruct room history from the message bus into the message log.++Rows exist from the moment the recorder was deployed. Everything older is on+the homeserver and nowhere else, which stopped being harmless when the read+path moved to Postgres: those messages are now invisible to every agent rather+than merely unqueried.++This walks each room to its start and writes the messages that have no row.+Reconstructed rows are numbered below zero, so they order correctly against+the live log without disturbing it, and no delivery cursor moves — nobody is+sent last March's messages tonight.++Safe to re-run. `transport_event_id` is unique and each page commits on its+own, so a walk that fails halfway leaves what it finished and picks up from+there.++Run it against a real deployment. Start with `--dry-run` on one room.++Usage:+ just backfill-messages --dry-run+ just backfill-messages --room <switch-room-uuid>+ just backfill-messages++In a deployment it is the same command inside the image:+ python -m switch_core.cli.backfill --dry-run+"""++from __future__ import annotations++import argparse+import asyncio+import sys++from sqlalchemy import select++from switch_core.config import SwitchConfig+from switch_core.db.engine import create_engine_from_config, create_session_factory+from switch_core.db.models import Room+from switch_core.db.stores.client_store import ClientStore+from switch_core.db.stores.message_store import MessageStore+from switch_core.messages import backfill_room+from switch_core.transport.matrix import MatrixTransport++# The admin client is a member of every room by design, which is what makes it+# the one identity that can read every room's history.+READER_CLIENT_TYPE = "admin"+++def _parse_args() -> argparse.Namespace:+ parser = argparse.ArgumentParser(description=__doc__)+ parser.add_argument(+ "--room",+ help="A single Switch room id. Defaults to every non-archived room.",+ )+ parser.add_argument(+ "--dry-run",+ action="store_true",+ help=(+ "Read the history and report what would be written, without "+ "writing it. Start here."+ ),+ )+ parser.add_argument(+ "--force",+ action="store_true",+ help=(+ "Walk rooms that have already been backfilled to their start. "+ "Without it they are skipped: the walk always starts from the "+ "newest message, so re-reading a finished room costs its whole "+ "history in pages to learn there is nothing to write."+ ),+ )+ parser.add_argument(+ "--allow-empty",+ action="store_true",+ help=(+ "Treat 'nothing to walk' as success. For unattended runs — a "+ "first boot has no admin client and no rooms yet, and a stack "+ "that refuses to start over an empty database is worse than one "+ "with nothing to backfill."+ ),+ )+ return parser.parse_args()+++class _ReadOnlyStore(MessageStore):+ """Counts what a real run would write, and writes nothing.++ A dry run has to walk exactly as far as a real one and make exactly the+ same decisions, so it shares everything but the insert.+ """++ async def create_historical(self, session, message, attachments): # type: ignore[no-untyped-def]+ return message++ async def mark_history_backfilled(self, session, room_id): # type: ignore[no-untyped-def]+ """A room a dry run walked has not been backfilled.++ Marking it would make the walk that wrote nothing look like the one+ that did, and the real run afterwards would find no rooms left to do.+ """+ return None+++async def _run(args: argparse.Namespace) -> int:+ config = SwitchConfig()+ engine = create_engine_from_config(config)+ session_factory = create_session_factory(engine)++ async with session_factory() as session:+ readers = await ClientStore().get_by_type(session, READER_CLIENT_TYPE)+ if not readers:+ print(+ f"No {READER_CLIENT_TYPE} client exists, so no identity can read "+ "every room. Start switch-core once to provision it.",+ file=sys.stderr,+ )+ return 0 if args.allow_empty else 2+ reader = readers[0]+ query = select(Room).where(Room.archived_at.is_(None))+ if args.room:+ query = query.where(Room.id == args.room)+ if not args.force:+ query = query.where(Room.history_backfilled_at.is_(None))+ rooms = list((await session.execute(query)).scalars().all())++ if not rooms:+ print(+ "No rooms to backfill — every room has already been walked to its "+ "start, or there are none. Use --force to walk them again.",+ file=sys.stderr,+ )+ return 0 if args.allow_empty else 2++ transport = MatrixTransport(+ server_url=config.matrix_server,+ user_id=reader.matrix_user_id,+ password=reader.password,+ device_id=reader.device_id,+ access_token=reader.access_token,+ )+ await transport.connect()+ joined = set(await transport.joined_rooms())++ store: MessageStore = _ReadOnlyStore() if args.dry_run else MessageStore()+ written = 0+ incomplete = 0+ unreadable: list[str] = []+ try:+ for room in rooms:+ if room.matrix_room_id not in joined:+ # A room nobody can read is not a room with no history, and+ # reporting it as done would be the one answer that misleads.+ unreadable.append(f"{room.name} ({room.matrix_room_id})")+ continue+ report = await backfill_room(transport, session_factory, room, store=store)+ print(report.summary())+ written += report.written+ incomplete += 1 if report.incomplete else 0+ finally:+ await transport.close()+ await engine.dispose()++ if unreadable:+ print(+ f"\n{len(unreadable)} room(s) the {READER_CLIENT_TYPE} client is not "+ "in, so they were not backfilled:",+ file=sys.stderr,+ )+ for where in unreadable:+ print(f" {where}", file=sys.stderr)++ verb = "would be written" if args.dry_run else "written"+ print(+ f"\n{len(rooms) - len(unreadable)} room(s) walked, {written} message(s) {verb}."+ )+ if incomplete:+ print(+ f"{incomplete} room(s) hit the page limit and are only partially "+ "reconstructed. Re-run to continue.",+ file=sys.stderr,+ )+ return 1 if (unreadable or incomplete) else 0+++def main() -> int:+ return asyncio.run(_run(_parse_args()))+++if __name__ == "__main__":+ raise SystemExit(main())diff --git a/core/switch_core/cli/reconcile.py b/core/switch_core/cli/reconcile.pynew file mode 100644index 000000000..22a991f13--- /dev/null+++ b/core/switch_core/cli/reconcile.py@@ -0,0 +1,173 @@+"""Check that the recorded messages agree with what the message bus holds.++Every message is written to Postgres alongside the send, but the write happens+after delivery and cannot fail it — so a database problem leaves a row missing+for a message that really was sent. This walks a room's history on the bus,+compares it against the recorded rows, and reports the difference.++Run it against a real deployment before moving any read path onto those rows.+Unit tests cannot answer this question: the thing being checked is whether two+records of the same live traffic agree.++Only the window in which recording was active is compared — from the oldest+recorded message in each room, or from `--since`. Messages older than that are+legitimately absent and are not reported as drift.++Exits non-zero when any room disagrees, so it can gate a deployment.++Usage:+ just reconcile-messages+ just reconcile-messages --room <switch-room-uuid>+ just reconcile-messages --since 2026-09-01T00:00:00+00:00+ just reconcile-messages --verbose++In a deployment it is the same command inside the image:+ python -m switch_core.cli.reconcile --verbose+"""++from __future__ import annotations++import argparse+import asyncio+import sys+from datetime import datetime++from sqlalchemy import select++from switch_core.config import SwitchConfig+from switch_core.db.engine import create_engine_from_config, create_session_factory+from switch_core.db.models import Room+from switch_core.db.stores.client_store import ClientStore+from switch_core.messages import RoomReconciliation, reconcile_room+from switch_core.transport.matrix import MatrixTransport++# The admin client is a member of every room by design, which is what makes it+# the one identity that can read every room's history.+READER_CLIENT_TYPE = "admin"+++def _parse_args() -> argparse.Namespace:+ parser = argparse.ArgumentParser(description=__doc__)+ parser.add_argument(+ "--room",+ help="A single Switch room id. Defaults to every non-archived room.",+ )+ parser.add_argument(+ "--since",+ help=(+ "ISO-8601 instant to compare from, overriding the per-room "+ "recorded-from cutoff. Anything older is not reported as missing."+ ),+ )+ parser.add_argument(+ "--verbose",+ action="store_true",+ help="List every differing event rather than only the counts.",+ )+ return parser.parse_args()+++def _report(reconciliation: RoomReconciliation, *, verbose: bool) -> None:+ print(reconciliation.summary())+ if reconciliation.ignored_by_type:+ counts = ", ".join(+ f"{name}={count}"+ for name, count in sorted(reconciliation.ignored_by_type.items())+ )+ print(f" not sends, so not compared: {counts}")+ if reconciliation.unverifiable_by_type:+ counts = ", ".join(+ f"{name}={count}"+ for name, count in sorted(reconciliation.unverifiable_by_type.items())+ )+ print(f" rows the bus walk cannot check: {counts}")+ if not reconciliation.anchored:+ print(+ " the oldest recorded event was not found on the bus, so the "+ "start of the window is approximate"+ )+ if not verbose:+ return+ for event_id in reconciliation.missing_rows:+ print(f" missing row: {event_id}")+ for event_id in reconciliation.unsent_rows:+ print(f" recorded but not on the bus: {event_id}")+ for mismatch in reconciliation.mismatches:+ print(f" {mismatch.describe()}")+++async def _run(args: argparse.Namespace) -> int:+ since = datetime.fromisoformat(args.since) if args.since else None++ config = SwitchConfig()+ engine = create_engine_from_config(config)+ session_factory = create_session_factory(engine)++ async with session_factory() as session:+ readers = await ClientStore().get_by_type(session, READER_CLIENT_TYPE)+ if not readers:+ print(+ f"No {READER_CLIENT_TYPE} client exists, so no identity can read "+ "every room. Start switch-core once to provision it.",+ file=sys.stderr,+ )+ return 2+ reader = readers[0]+ query = select(Room).where(Room.archived_at.is_(None))+ if args.room:+ query = query.where(Room.id == args.room)+ rooms = list((await session.execute(query)).scalars().all())++ if not rooms:+ print("No rooms to check.", file=sys.stderr)+ return 2++ transport = MatrixTransport(+ server_url=config.matrix_server,+ user_id=reader.matrix_user_id,+ password=reader.password,+ device_id=reader.device_id,+ access_token=reader.access_token,+ )+ await transport.connect()+ joined = set(await transport.joined_rooms())++ drifted = 0+ unreadable: list[str] = []+ try:+ for room in rooms:+ if room.matrix_room_id not in joined:+ # Reporting a room nobody can read as clean would be the worst+ # possible answer, so it is named and counted as a failure.+ unreadable.append(f"{room.name} ({room.matrix_room_id})")+ continue+ async with session_factory() as session:+ reconciliation = await reconcile_room(+ transport, session, room, since=since+ )+ _report(reconciliation, verbose=args.verbose)+ if not reconciliation.clean:+ drifted += 1+ finally:+ await transport.close()+ await engine.dispose()++ if unreadable:+ print(+ f"\n{len(unreadable)} room(s) the {READER_CLIENT_TYPE} client is not "+ "in, so they were not checked:",+ file=sys.stderr,+ )+ for where in unreadable:+ print(f" {where}", file=sys.stderr)++ print(f"\n{len(rooms) - len(unreadable)} room(s) checked, {drifted} with drift.")+ return 1 if (drifted or unreadable) else 0+++def main() -> int:+ return asyncio.run(_run(_parse_args()))+++if __name__ == "__main__":+ raise SystemExit(main())diff --git a/core/switch_core/clients/admin_client.py b/core/switch_core/clients/admin_client.pyindex 6d460b923..5b2c6dba6 100644--- a/core/switch_core/clients/admin_client.py+++ b/core/switch_core/clients/admin_client.py@@ -1,9 +1,7 @@from __future__ import annotationsimport logging-from typing import TYPE_CHECKING, Any, Literal--from nio import MatrixRoom, RoomMessage, RoomMessageText+from typing import TYPE_CHECKING, Literal, Unpackfrom switch_core.agent_display_name import agent_label_with_identifierfrom switch_core.bridges.agent.commands import dispatch_admin_command@@ -13,7 +11,11 @@ from switch_core.clients.admin_messages import (AdminMessageType,admin_extra_content,)-from switch_core.clients.client_base import ClientBase, ClientConfig+from switch_core.clients.client_base import (+ ClientBase,+ ClientBaseKwargs,+ ClientConfig,+)from switch_core.clients.mentions import (mention_regex,strip_emphasis,@@ -27,6 +29,7 @@ from switch_core.db.stores.reference_store import ReferenceStorefrom switch_core.db.stores.room_role_store import RoomRoleStorefrom switch_core.db.stores.room_store import RoomStorefrom switch_core.events import CommandEvent+from switch_core.transport import InboundMessage, RoomRefif TYPE_CHECKING:from switch_core.room_service import RoomService@@ -61,7 +64,7 @@ class AdminClient(ClientBase[ClientConfig]):agent_session_store: AgentSessionStore,room_service: RoomService,frontend_base_url: str | None,- **kwargs: Any,+ **kwargs: Unpack[ClientBaseKwargs[ClientConfig]],) -> None:super().__init__(**kwargs)self._agent_store = agent_store@@ -80,8 +83,8 @@ class AdminClient(ClientBase[ClientConfig]):# ── Event hooks ───────────────────────────────────────────────────────────- async def on_message(self, room: MatrixRoom, event: RoomMessageText) -> None:- content = event.source.get("content", {}) or {}+ async def on_message(self, room: RoomRef, event: InboundMessage) -> None:+ content = event.content# Never react to admin/system messages — including our own notices —# so the rail can't loop on itself.if ADMIN_MARKER in content:@@ -94,16 +97,13 @@ class AdminClient(ClientBase[ClientConfig]):if meta is None:return- thread_id: str | None = None- relates = content.get("m.relates_to") or {}- if relates.get("rel_type") == "m.thread":- thread_id = relates.get("event_id")+ thread_id = event.thread_root_idthread_root = thread_id if thread_id is not None else event.event_idawait self._warn_unreachable_roles(room, event, meta.room_id, thread_root)await self._warn_absent_agents(room, event, meta.room_id, thread_root)- async def on_command(self, room: MatrixRoom, event: CommandEvent) -> None:+ async def on_command(self, room: RoomRef, event: CommandEvent) -> None:await dispatch_admin_command(self, room, event)async def reply_command(@@ -128,8 +128,8 @@ class AdminClient(ClientBase[ClientConfig]):async def _warn_unreachable_roles(self,- room: MatrixRoom,- event: RoomMessage,+ room: RoomRef,+ event: InboundMessage,room_id: str,thread_id: str | None,) -> None:@@ -170,8 +170,8 @@ class AdminClient(ClientBase[ClientConfig]):async def _warn_absent_agents(self,- room: MatrixRoom,- event: RoomMessage,+ room: RoomRef,+ event: InboundMessage,room_id: str,thread_id: str | None,) -> None:@@ -244,7 +244,7 @@ class AdminClient(ClientBase[ClientConfig]):extra_content=admin_extra_content(message_type),)- def _sender_handle(self, event: RoomMessage) -> str:+ def _sender_handle(self, event: InboundMessage) -> str:"""The @-handle to tag the message sender with.Prefers the bridge-provided `sender_name` (the external username, which@@ -252,7 +252,7 @@ class AdminClient(ClientBase[ClientConfig]):Mattermost); falls back to the mxid localpart for a native Matrix user(paired with `mentions=[event.sender]` so Matrix renders a pill)."""- content = event.source.get("content", {}) or {}+ content = event.contentname = content.get("sender_name")if name:return str(name)diff --git a/core/switch_core/clients/agent_client.py b/core/switch_core/clients/agent_client.pyindex 92439c734..554c448b2 100644--- a/core/switch_core/clients/agent_client.py+++ b/core/switch_core/clients/agent_client.py@@ -5,18 +5,8 @@ import loggingimport randomimport refrom dataclasses import dataclass, field-from typing import Literal, NamedTuple--from nio import (- MatrixRoom,- RoomMemberEvent,- RoomMessage,- RoomMessageMedia,- RoomMessageText,-)-from sqlalchemy.ext.asyncio import AsyncSession+from typing import TYPE_CHECKING, Literal, NamedTuple, Unpack-from switch_core.addressing import SenderKind, can_address, parse_policyfrom switch_core.attachments import parse_attachment_groupfrom switch_core.bridges.agent.commands import (AGENT_GREETINGS,@@ -38,16 +28,11 @@ from switch_core.bridges.agent.protocol.types import (TaskFinalisePayload,TaskUpdatePayload,)-from switch_core.bridges.agent.request_tracker import RequestTracker-from switch_core.bridges.resource.events import (- ResourceLoadResponse,- RoomDocumentCreateResponse,- RoomDocumentDeleteResponse,- RoomDocumentUpdateResponse,+from switch_core.clients.client_base import (+ ClientBase,+ ClientBaseKwargs,+ ClientConfig,)-from switch_core.bridges.resource.tracker import ResourceRequestTracker-from switch_core.clients.admin_messages import ADMIN_MARKER-from switch_core.clients.client_base import ClientBase, ClientConfigfrom switch_core.clients.mentions import (NAME_CHAR as _NAME_CHAR,)@@ -67,11 +52,15 @@ from switch_core.db.stores.external_user_store import ExternalUserStorefrom switch_core.db.stores.reference_store import ReferenceStorefrom switch_core.db.stores.room_role_store import RoomRoleStorefrom switch_core.db.stores.room_store import RoomStore+from switch_core.delivery.addressing import (+ ADDRESSING_DENIED_MESSAGE,+ ADDRESSING_UNCLAIMED_MESSAGE,+ AddressingDecision,+ AddressingResolver,+ IncomingMessage,+)from switch_core.events import (CommandEvent,- MediationLlmResponse,- MediationResult,- MediationToolResult,TaskAccept,TaskCancel,TaskDelegate,@@ -79,6 +68,15 @@ from switch_core.events import (TaskUpdate,)from switch_core.gateway.known_agents import known_agent_for+from switch_core.transport import (+ InboundMedia,+ InboundMembership,+ InboundMessage,+ RoomRef,+)++if TYPE_CHECKING:+ from sqlalchemy.ext.asyncio import AsyncSessionlogger = logging.getLogger(__name__)@@ -113,7 +111,7 @@ class _PendingAttachmentGroup:# The index-0 event, kept so a group that has to be flushed incomplete is# still anchored on its canonical first part (message_id / timestamp /# sender) rather than on whichever part happened to arrive last.- first_event: RoomMessageMedia | None = None+ first_event: InboundMedia | None = None_UNAVAILABLE_MESSAGES = {@@ -191,45 +189,11 @@ def _offline_owner_message(return f"{opening} {terminal}\n\n```\n{cmd}\n```"-# Posted (once, guarded by AUTO_REPLY_FLAG) when a sender tags this agent but-# the agent's scoped addressing policy does not permit that sender to address-# it here. The message is demoted to unaddressed room chatter; this reply is-# the sender's only feedback that the attempt was rejected.-_ADDRESSING_DENIED_MESSAGE = (- "You're not permitted to direct messages to me in this room — my operator "- "has restricted who can address me here."-)---# The same refusal, for the case worth telling apart: the agent answers only to-# its owner, and the sender's chat account is not linked to any Switch user, so-# it cannot be recognised as the owner even if it is. Without this the owner-# gets refused by their own agent with no idea why.-_ADDRESSING_UNCLAIMED_MESSAGE = (- "I only take instructions from my owner, and this chat account isn't "- "linked to a Switch user yet — so I can't tell whether that's you. If it "- "is, link this account to your Switch user in Switch Console and try again."-)---class _SenderPrincipal(NamedTuple):- """Who a Matrix sender turned out to be, in the terms a policy is written- in. `user_ids` and `owner_user_id` are the two ways a symbolic subject- resolves, and are mutually exclusive: a human has claimants, an agent has- an owner."""-- kind: SenderKind- id: str- user_ids: list[str]- owner_user_id: str | None---class _AddressingDecision(NamedTuple):- """The outcome of checking a sender against an agent's addressing policy,- carrying the wording to reply with so the caller need not re-derive why."""-- allowed: bool- refusal: str+# The refusal wording lives with the decision that produces it. Kept under+# these names because they are how the rest of the package and its tests refer+# to them.+_ADDRESSING_DENIED_MESSAGE = ADDRESSING_DENIED_MESSAGE+_ADDRESSING_UNCLAIMED_MESSAGE = ADDRESSING_UNCLAIMED_MESSAGEclass _GateOutcome(NamedTuple):@@ -272,13 +236,11 @@ class AgentClient(ClientBase[ClientConfig]):agent_session_store: AgentSessionStore,room_role_store: RoomRoleStore,external_user_store: ExternalUserStore,- request_tracker: RequestTracker,- resource_request_tracker: ResourceRequestTracker,connections: ConnectionRegistry,frontend_base_url: str | None,- **kwargs: object,+ **kwargs: Unpack[ClientBaseKwargs[ClientConfig]],) -> None:- super().__init__(**kwargs) # type: ignore[arg-type]+ super().__init__(**kwargs)self._event_buffer = event_bufferself._agent_store = agent_storeself._room_store = room_store@@ -288,13 +250,21 @@ class AgentClient(ClientBase[ClientConfig]):self._agent_session_store = agent_session_storeself._room_role_store = room_role_storeself._external_user_store = external_user_store- self._request_tracker = request_tracker- self._resource_request_tracker = resource_request_trackerself._connections = connectionsself._frontend_base_url = (frontend_base_url.rstrip("/") if frontend_base_url else None)self._agent: Agent | None = None+ # Addressing is decided from stores, not from this client, so the same+ # rules can decide for a message read out of the log.+ self._addressing = AddressingResolver(+ room_store=room_store,+ room_role_store=room_role_store,+ client_store=self.client_store,+ agent_store=agent_store,+ external_user_store=external_user_store,+ live_agent_ids=connections.live_agent_ids,+ )self._room_meta: dict[str, RoomMeta | None] = {}# In-flight multi-attachment groups, by group id, with their safety-net# timers. Both are cleared when a group completes or times out, so a@@ -336,7 +306,7 @@ class AgentClient(ClientBase[ClientConfig]):# ── Event hooks ───────────────────────────────────────────────────────────- async def on_self_join(self, room: MatrixRoom, event: RoomMemberEvent) -> None:+ async def on_self_join(self, room: RoomRef, event: InboundMembership) -> None:is_direct = await self._is_direct_room(room.room_id)name = self.agent.name# The per-agent self-join greeting can be switched off per bridge@@ -357,7 +327,29 @@ class AgentClient(ClientBase[ClientConfig]):greeting = random.choice(AGENT_GREETINGS).format(name=name)await self.send_message(room.room_id, greeting, format="markdown")- async def on_member_event(self, room: MatrixRoom, event: RoomMemberEvent) -> None:+ async def _member_name(+ self, session: AsyncSession, event: InboundMembership+ ) -> str:+ """What to call the member who just arrived.++ The name Switch knows them by, not the one on the membership event: a+ profile is set from whatever the source platform calls someone, so+ taking it makes the same person read one way when they arrive and+ another way when they speak — and the log, which records the Switch+ name, disagree with what was delivered live.+ """+ client = await self.client_store.get_by_matrix_user_id(session, event.state_key)+ if client is not None:+ return client.display_name+ fallback = event.display_name or event.state_key.split(":")[0].lstrip("@")+ logger.warning(+ "No Switch client owns %s; naming the arrival %r from the membership event",+ event.state_key,+ fallback,+ )+ return fallback++ async def on_member_event(self, room: RoomRef, event: InboundMembership) -> None:# Only forward genuine joins. A membership-preserving update (e.g. a# display-name or avatar change) re-fires m.room.member with# membership == "join" and prev_membership == "join" — exclude those, and@@ -369,9 +361,6 @@ class AgentClient(ClientBase[ClientConfig]):meta = await self._resolve_room_meta(room.room_id)if meta is None:return- member_name = event.content.get("displayname") or event.state_key.split(":")[- 0- ].lstrip("@")# `listening` tells each connector whether THIS receiving agent is# configured to react to join events in this room. The event is always# delivered; the connector decides whether to surface it.@@ -379,6 +368,7 @@ class AgentClient(ClientBase[ClientConfig]):listening = await self._room_store.get_receives_join_events(session, meta.room_id, self.agent.id)+ member_name = await self._member_name(session, event)self._event_buffer.enqueue(self.agent.id,meta.room_id,@@ -390,21 +380,18 @@ class AgentClient(ClientBase[ClientConfig]):payload=RoomJoinPayload(member=event.state_key,member_name=member_name,- timestamp=event.server_timestamp,+ timestamp=event.timestamp,listening=listening,),),)- async def on_message(self, room: MatrixRoom, event: RoomMessageText) -> None:+ async def on_message(self, room: RoomRef, event: InboundMessage) -> None:meta = await self._resolve_room_meta(room.room_id)if meta is None:return- thread_id: str | None = None- relates = event.source.get("content", {}).get("m.relates_to") or {}- if relates.get("rel_type") == "m.thread":- thread_id = relates.get("event_id")+ thread_id = event.thread_root_idreply_thread_root = thread_id if thread_id is not None else event.event_id@@ -459,7 +446,7 @@ class AgentClient(ClientBase[ClientConfig]):text = event.body- sender_name = event.source.get("content", {}).get("sender_name")+ sender_name = event.sender_nameif not sender_name:sender_name = event.senderlogger.error(@@ -478,7 +465,7 @@ class AgentClient(ClientBase[ClientConfig]):sender_name=sender_name,message_id=event.event_id,body=text,- timestamp=event.server_timestamp,+ timestamp=event.timestamp,thread_id=thread_id,),)@@ -490,26 +477,24 @@ class AgentClient(ClientBase[ClientConfig]):agent_event,)- async def on_media(self, room: MatrixRoom, event: RoomMessageMedia) -> None:+ async def on_media(self, room: RoomRef, event: InboundMedia) -> None:meta = await self._resolve_room_meta(room.room_id)if meta is None:returnis_addressed = await self._addressed(event, meta)- content = event.source.get("content", {})- info = content.get("info", {}) or {}+ content = event.content# With a caption, body is the caption text and the real filename lives in# `filename`; without one, body is the filename itself.- filename = content.get("filename") or event.bodyattachment = AttachmentRef(- filename=filename,- mimetype=str(info.get("mimetype", "")),- size=int(info.get("size", 0) or 0),- mxc=str(event.url),- msgtype=str(content.get("msgtype", "")),+ filename=event.filename or event.body,+ mimetype=event.mimetype or "",+ size=event.size or 0,+ mxc=event.uri,+ msgtype=event.msgtype,)- sender_name = content.get("sender_name")+ sender_name = event.sender_nameif not sender_name:sender_name = event.senderlogger.error(@@ -518,10 +503,7 @@ class AgentClient(ClientBase[ClientConfig]):)# Mirror on_message: surface the thread this media belongs to (if any).- thread_id: str | None = None- relates = content.get("m.relates_to") or {}- if relates.get("rel_type") == "m.thread":- thread_id = relates.get("event_id")+ thread_id = event.thread_root_id# Several files posted as one message arrive as separate Matrix events# sharing a group marker (Matrix has no multi-attachment event). Hold@@ -574,8 +556,8 @@ class AgentClient(ClientBase[ClientConfig]):def _schedule_attachment_group_flush(self,group_id: str,- room: MatrixRoom,- event: RoomMessageMedia,+ room: RoomRef,+ event: InboundMedia,meta: RoomMeta,sender_name: str,thread_id: str | None,@@ -610,8 +592,8 @@ class AgentClient(ClientBase[ClientConfig]):async def _flush_incomplete_attachment_group(self,group_id: str,- room: MatrixRoom,- event: RoomMessageMedia,+ room: RoomRef,+ event: InboundMedia,meta: RoomMeta,sender_name: str,thread_id: str | None,@@ -650,8 +632,8 @@ class AgentClient(ClientBase[ClientConfig]):async def _emit_media(self,- room: MatrixRoom,- event: RoomMessageMedia,+ room: RoomRef,+ event: InboundMedia,meta: RoomMeta,is_addressed: bool,sender_name: str,@@ -681,7 +663,7 @@ class AgentClient(ClientBase[ClientConfig]):sender_name=sender_name,message_id=event.event_id,body=body,- timestamp=event.server_timestamp,+ timestamp=event.timestamp,thread_id=thread_id,attachments=attachments,),@@ -694,7 +676,7 @@ class AgentClient(ClientBase[ClientConfig]):agent_event,)- async def on_command(self, room: MatrixRoom, event: CommandEvent) -> None:+ async def on_command(self, room: RoomRef, event: CommandEvent) -> None:meta = await self._resolve_room_meta(room.room_id)if meta is None:return@@ -751,7 +733,7 @@ class AgentClient(ClientBase[ClientConfig]):return await self._text_tags_my_role(session, args, room_id)async def _gate_command(- self, room: MatrixRoom, event: CommandEvent, meta: RoomMeta+ self, room: RoomRef, event: CommandEvent, meta: RoomMeta) -> bool:"""Apply the addressing policy to a command aimed at this agent.@@ -794,7 +776,7 @@ class AgentClient(ClientBase[ClientConfig]):# ── Command handling ──────────────────────────────────────────────────────- async def _handle_command(self, room: MatrixRoom, event: CommandEvent) -> bool:+ async def _handle_command(self, room: RoomRef, event: CommandEvent) -> bool:is_direct = await self._is_direct_room(room.room_id)return await dispatch_command(self, room, event, is_direct)@@ -1067,7 +1049,7 @@ class AgentClient(ClientBase[ClientConfig]):# ── Task event forwarding ────────────────────────────────────────────────- async def on_task_delegate(self, room: MatrixRoom, event: TaskDelegate) -> None:+ async def on_task_delegate(self, room: RoomRef, event: TaskDelegate) -> None:if event.performer_agent_id != self.agent.id:returnawait self.send_message(room.room_id, "Working on it.", format="markdown")@@ -1092,7 +1074,7 @@ class AgentClient(ClientBase[ClientConfig]):),)- async def on_task_accept(self, room: MatrixRoom, event: TaskAccept) -> None:+ async def on_task_accept(self, room: RoomRef, event: TaskAccept) -> None:if event.requester_agent_id != self.agent.id:returnmeta = await self._resolve_room_meta(room.room_id)@@ -1114,7 +1096,7 @@ class AgentClient(ClientBase[ClientConfig]):),)- async def on_task_update(self, room: MatrixRoom, event: TaskUpdate) -> None:+ async def on_task_update(self, room: RoomRef, event: TaskUpdate) -> None:if event.requester_agent_id != self.agent.id:returnmeta = await self._resolve_room_meta(room.room_id)@@ -1137,7 +1119,7 @@ class AgentClient(ClientBase[ClientConfig]):),)- async def on_task_finalise(self, room: MatrixRoom, event: TaskFinalise) -> None:+ async def on_task_finalise(self, room: RoomRef, event: TaskFinalise) -> None:if event.requester_agent_id != self.agent.id:returnmeta = await self._resolve_room_meta(room.room_id)@@ -1160,7 +1142,7 @@ class AgentClient(ClientBase[ClientConfig]):),)- async def on_task_cancel(self, room: MatrixRoom, event: TaskCancel) -> None:+ async def on_task_cancel(self, room: RoomRef, event: TaskCancel) -> None:if event.performer_agent_id != self.agent.id:returnmeta = await self._resolve_room_meta(room.room_id)@@ -1183,56 +1165,20 @@ class AgentClient(ClientBase[ClientConfig]):),)- # ── Post-invocation mediation ──────────────────────────────────────────────-- async def on_mediation_tool_result(- self, room: MatrixRoom, event: MediationToolResult- ) -> None:- if event.agent_id != self.agent.id:- return- result = MediationResult(verdict=event.status)- self._request_tracker.resolve(event.request_id, result)-- async def on_mediation_llm_response(- self, room: MatrixRoom, event: MediationLlmResponse- ) -> None:- if event.agent_id != self.agent.id:- return- result = MediationResult(verdict=event.status)- self._request_tracker.resolve(event.request_id, result)-- async def on_resource_load_response(- self, room: MatrixRoom, event: ResourceLoadResponse- ) -> None:- if event.agent_id != self.agent.id:- return- self._resource_request_tracker.resolve(event.request_id, event)-- async def on_room_document_create_response(- self, room: MatrixRoom, event: RoomDocumentCreateResponse- ) -> None:- if event.agent_id != self.agent.id:- return- self._resource_request_tracker.resolve(event.request_id, event)-- async def on_room_document_update_response(- self, room: MatrixRoom, event: RoomDocumentUpdateResponse- ) -> None:- if event.agent_id != self.agent.id:- return- self._resource_request_tracker.resolve(event.request_id, event)-- async def on_room_document_delete_response(- self, room: MatrixRoom, event: RoomDocumentDeleteResponse- ) -> None:- if event.agent_id != self.agent.id:- return- self._resource_request_tracker.resolve(event.request_id, event)-# ── Mention detection ─────────────────────────────────────────────────────+ @staticmethod+ def _as_incoming(event: InboundMessage) -> IncomingMessage:+ """The parts of a bus event that addressing is decided from."""+ return IncomingMessage(+ sender=event.sender,+ body=getattr(event, "body", "") or "",+ formatted_body=getattr(event, "formatted_body", None),+ content=event.content,+ )+def _addressed_without_lookup(- self, event: RoomMessage, meta: RoomMeta+ self, event: InboundMessage, meta: RoomMeta) -> bool | None:"""The addressing answer that needs no database read, or None when theroom's aliases and role leases have to be consulted.@@ -1241,17 +1187,14 @@ class AgentClient(ClientBase[ClientConfig]):chatter carries no `@` and is answered here, and a room fans everymessage out to all of its agent clients at once."""- if ADMIN_MARKER in (event.source.get("content") or {}):- return False- if meta.channel_type == "direct":- return True- if self._is_mentioned(event):- return True- if "@" not in (getattr(event, "body", "") or ""):- return False- return None+ return self._addressing.addressed_without_lookup(+ agent=self.agent,+ agent_matrix_id=self.matrix_user_id,+ channel_type=meta.channel_type,+ message=self._as_incoming(event),+ )- async def _addressed(self, event: RoomMessage, meta: RoomMeta) -> bool:+ async def _addressed(self, event: InboundMessage, meta: RoomMeta) -> bool:"""`_compute_addressed`, in a session of its own when it needs one."""decided = self._addressed_without_lookup(event, meta)if decided is not None:@@ -1260,144 +1203,36 @@ class AgentClient(ClientBase[ClientConfig]):return await self._compute_addressed(session, event, meta)async def _compute_addressed(- self, session: AsyncSession, event: RoomMessage, meta: RoomMeta+ self, session: AsyncSession, event: InboundMessage, meta: RoomMeta) -> bool:- """Whether this message addresses this agent (expects a response).-- Direct rooms always address. Otherwise the agent is addressed by an- `@name` mention OR by an `@<role>` tag for a room-role it currently- holds (see `_is_mentioned_via_role`).-- **A system message never addresses anyone**, whatever the room type.- Switch's own notices — a command's answer, "Added X to this room", the- guidance shown when someone tags the app itself — are output, not a- request for a reply. Two ways they were read as one: in a direct room- every message addresses the agent, so running `/list-agents` in a 1:1- chat had the agent start a session to respond to its own roster; and in- any room, a notice that lists the agents present writes each `@name`,- which tagged every one of them. The marker exists to say "generated by- Switch"; this is it being honoured.- """- decided = self._addressed_without_lookup(event, meta)- if decided is not None:- return decided- if await self._is_mentioned_via_alias(session, event, meta.room_id):- return True- return await self._is_mentioned_via_role(session, event, meta.room_id)-- async def _resolve_sender_principal(- self, session: AsyncSession, matrix_user_id: str- ) -> _SenderPrincipal | None:- """Resolve a Matrix sender to an addressing principal.-- Maps the sender's mxid to its Client, then to either an Agent (an- agent-to-agent attempt) or an ExternalUser (a human on a bridge).- Returns ``None`` when the sender has no such record — an- unresolvable identity that a restricted agent should not trust.-- The two symbolic subjects resolve from different fields, and only one- applies to any given sender: ``user_ids`` are the Switch users who have- claimed a human's platform account (empty for an agent — an agent is- never its owner, even its owner's own), and ``owner_user_id`` is who- owns an agent sender (None for a human).- """- client = await self.client_store.get_by_matrix_user_id(session, matrix_user_id)- if client is None:- return None- agent = await self._agent_store.get_by_client_id(session, client.id)- if agent is not None:- return _SenderPrincipal("agent", agent.id, [], agent.owner_id)- external_user = await self._external_user_store.get_by_client_id(- session, client.id+ return await self._addressing.addresses(+ session,+ agent=self.agent,+ agent_matrix_id=self.matrix_user_id,+ room_id=meta.room_id,+ channel_type=meta.channel_type,+ message=self._as_incoming(event),)- if external_user is not None:- claimants = await self._external_user_store.claimant_ids(- session, external_user.id- )- return _SenderPrincipal("user", external_user.id, claimants, None)- return Noneasync def _addressing_allowed(self, session: AsyncSession, agent: Agent, matrix_sender: str, room_id: str- ) -> _AddressingDecision:+ ) -> AddressingDecision:"""Whether `matrix_sender` may address this agent in `room_id`, per theagent's scoped addressing policy.- An agent with no policy is open to anyone, so this returns allowed- without a DB round-trip. With a policy set it is deny-by-default: an- unresolvable sender is rejected (fail-closed). A denial carries the- wording to send back, which differs when the sender looks like someone- whose platform identity simply has not been claimed yet.+ `agent` is the freshly-read row rather than the cached snapshot: the+ policy is the thing being enforced, and enforcing a stale copy of it is+ the one way this check can be wrong in the dangerous direction."""- policy = parse_policy(agent.addressing_policy)- if policy.is_open():- return _AddressingDecision(allowed=True, refusal="")- principal = await self._resolve_sender_principal(session, matrix_sender)- room = await self._room_store.get(session, room_id)- if principal is None:- logger.warning(- "Addressing denied for %s: unresolvable sender %s in room %s",- self.agent.name,- matrix_sender,- room_id,- )- return _AddressingDecision(- allowed=False, refusal=_ADDRESSING_DENIED_MESSAGE- )- sender_kind, sender_id, sender_user_ids = (- principal.kind,- principal.id,- principal.user_ids,- )- group_id = room.group_id if room is not None else None- allowed = can_address(- policy,- room_id=room_id,- group_id=group_id,- sender_kind=sender_kind,- sender_id=sender_id,- sender_user_ids=sender_user_ids,- sender_owner_user_id=principal.owner_user_id,- owner_user_id=agent.owner_id,- )- if allowed:- return _AddressingDecision(allowed=True, refusal="")- unclaimed = (- sender_kind == "user"- and not sender_user_ids- and policy.requires_owner_identity()- )- if unclaimed:- logger.warning(- "Addressing denied for %s: sender %s in room %s has not been "- "claimed by any Switch user, so an owner-scoped rule cannot "- "match them — the owner may need to link this identity",- self.agent.name,- sender_id,- room_id,- )- else:- logger.warning(- "Addressing denied for %s: %s %s not permitted in room %s",- self.agent.name,- sender_kind,- sender_id,- room_id,- )- return _AddressingDecision(- allowed=False,- refusal=(- _ADDRESSING_UNCLAIMED_MESSAGE- if unclaimed- else _ADDRESSING_DENIED_MESSAGE- ),+ return await self._addressing.permitted(+ session, agent=agent, room_id=room_id, sender=matrix_sender)async def _gate_addressed(self,session: AsyncSession,agent: Agent,- event: RoomMessage,+ event: InboundMessage,meta: RoomMeta,) -> _GateOutcome:"""Apply the scoped addressing policy to a message that tags this agent.@@ -1418,13 +1253,13 @@ class AgentClient(ClientBase[ClientConfig]):return _GateOutcome(addressed=False, refusal=decision.refusal)@staticmethod- def _triggered_by_auto_reply(event: RoomMessage) -> bool:- return bool(event.source.get("content", {}).get(AUTO_REPLY_FLAG))+ def _triggered_by_auto_reply(event: InboundMessage) -> bool:+ return bool(event.content.get(AUTO_REPLY_FLAG))async def _post_auto_reply(self,matrix_room_id: str,- event: RoomMessage,+ event: InboundMessage,msg: str,thread_root_id: str | None,) -> None:@@ -1449,65 +1284,24 @@ class AgentClient(ClientBase[ClientConfig]):async def _text_tags_my_alias(self, session: AsyncSession, text: str, room_id: str) -> bool:- """True when `text` `@`-tags this agent's room alias at a token boundary.-- The alias is looked up live (like a role lease) so a change takes effect- on the next message without any per-client cache to invalidate.- """- if "@" not in text:- return False- alias = await self._room_store.get_alias(session, room_id, self.agent.id)- if not alias:- return False- return _mention_regex(alias).search(text) is not None-- async def _is_mentioned_via_alias(- self, session: AsyncSession, event: RoomMessage, room_id: str- ) -> bool:- """True when the message body tags this agent's room alias.-- A room alias addresses the agent exactly like its real name, so an- `@<alias>` mention routes here just as `@<name>` does.- """- return await self._text_tags_my_alias(- session, getattr(event, "body", "") or "", room_id+ return await self._addressing.mentions_alias(+ session,+ agent=self.agent,+ room_id=room_id,+ message=IncomingMessage(sender="", body=text),)async def _text_tags_my_role(self, session: AsyncSession, text: str, room_id: str) -> bool:- """True when `text` `@`-tags a room-role this agent LIVE-holds.-- Only a live lease counts, so "held" means the same thing here as in- `!roles` and the moderator warning: a stale lease (session gone, role- auto-released → shown free) does NOT route here — the moderator flags- it as unassigned instead. A holder whose session merely hopped to- another room still matches, because that lease is kept alive by the- renewal loop. The moderator holds no role, so this is a no-op for it.- """- if "@" not in text:- return False- role_name = await self._room_role_store.agent_room_role(- session, room_id, self.agent.id, self._connections.live_agent_ids()- )- if not role_name:- return False- return _mention_regex(role_name).search(_strip_emphasis(text)) is not None-- async def _is_mentioned_via_role(- self, session: AsyncSession, event: RoomMessage, room_id: str- ) -> bool:- """True when the message body tags a room-role this agent holds.-- Tagging `@<role>` addresses whichever agent holds that role, so an- interchangeable agent can be reached by responsibility rather than by- name.- """- return await self._text_tags_my_role(- session, getattr(event, "body", "") or "", room_id+ return await self._addressing.mentions_role(+ session,+ agent=self.agent,+ room_id=room_id,+ message=IncomingMessage(sender="", body=text),)- def _sender_handle(self, event: RoomMessage) -> str:+ def _sender_handle(self, event: InboundMessage) -> str:"""The @-handle to tag the message sender with.Prefers the bridge-provided `sender_name` (the external username, which@@ -1515,21 +1309,17 @@ class AgentClient(ClientBase[ClientConfig]):Mattermost); falls back to the mxid localpart for a native Matrix user(paired with `mentions=[event.sender]` so Matrix renders a pill)."""- content = event.source.get("content", {}) or {}+ content = event.contentname = content.get("sender_name")if name:return str(name)return str(event.sender).split(":")[0].lstrip("@")- def _is_mentioned(self, event: RoomMessage) -> bool:- # Media events (RoomMessageImage/File) have no formatted_body; fall back- # to a plain-text mention scan on the body (the caption, for media).- formatted_body = getattr(event, "formatted_body", None)- if formatted_body is not None and self.matrix_user_id in formatted_body:- return True- return (- _mention_regex(self.agent.name).search(_strip_emphasis(event.body))- is not None+ def _is_mentioned(self, event: InboundMessage) -> bool:+ return self._addressing.mentions_name(+ agent=self.agent,+ agent_matrix_id=self.matrix_user_id,+ message=self._as_incoming(event),)def _strip_mention(self, text: str) -> str:diff --git a/core/switch_core/clients/bridge_client.py b/core/switch_core/clients/bridge_client.pyindex ab860bd45..6713a6c3b 100644--- a/core/switch_core/clients/bridge_client.py+++ b/core/switch_core/clients/bridge_client.py@@ -1,12 +1,15 @@from __future__ import annotationsimport logging-from typing import TYPE_CHECKING, Any+from typing import TYPE_CHECKING, Unpack-from nio import MatrixRoom, RoomMessageMedia, RoomMessageText--from switch_core.clients.client_base import ClientBase, ClientConfig+from switch_core.clients.client_base import (+ ClientBase,+ ClientBaseKwargs,+ ClientConfig,+)from switch_core.events import AgentRuntimeStateEvent+from switch_core.transport import InboundMedia, InboundMessage, RoomRefif TYPE_CHECKING:from switch_core.bridges.collaboration.bridge_core import BridgeCore@@ -21,11 +24,16 @@ class BridgeClientConfig(ClientConfig):class BridgeClient(ClientBase[BridgeClientConfig]):config_class = BridgeClientConfig- def __init__(self, *, bridge_core: BridgeCore, **kwargs: Any) -> None:+ def __init__(+ self,+ *,+ bridge_core: BridgeCore,+ **kwargs: Unpack[ClientBaseKwargs[BridgeClientConfig]],+ ) -> None:super().__init__(**kwargs)self._bridge_core = bridge_core- async def on_message(self, room: MatrixRoom, event: RoomMessageText) -> None:+ async def on_message(self, room: RoomRef, event: InboundMessage) -> None:logger.debug("[BRIDGE-CLIENT] on_message room=%s sender=%s",room.room_id,@@ -33,7 +41,7 @@ class BridgeClient(ClientBase[BridgeClientConfig]):)await self._bridge_core.handle_outbound_message(room, event)- async def on_media(self, room: MatrixRoom, event: RoomMessageMedia) -> None:+ async def on_media(self, room: RoomRef, event: InboundMedia) -> None:logger.debug("[BRIDGE-CLIENT] on_media room=%s sender=%s",room.room_id,@@ -42,6 +50,6 @@ class BridgeClient(ClientBase[BridgeClientConfig]):await self._bridge_core.handle_outbound_media(room, event, self)async def on_agent_runtime_state(- self, room: MatrixRoom, event: AgentRuntimeStateEvent+ self, room: RoomRef, event: AgentRuntimeStateEvent) -> None:await self._bridge_core.handle_agent_runtime_state(room, event)diff --git a/core/switch_core/clients/client_base.py b/core/switch_core/clients/client_base.pyindex f17569b0c..c82212844 100644--- a/core/switch_core/clients/client_base.py+++ b/core/switch_core/clients/client_base.py@@ -1,56 +1,19 @@from __future__ import annotationsimport asyncio-import ioimport loggingimport randomimport time-from typing import Literal--import markdown-from nio import (- AsyncClient,- InviteMemberEvent,- JoinedRoomsError,- LoginError,- MatrixRoom,- ProfileSetDisplayNameError,- ReactionEvent,- RoomMemberEvent,- RoomMessageMedia,- RoomMessageText,- RoomSendError,- RoomTypingError,- SyncError,- SyncResponse,- UnknownEvent,- UploadError,-)+from typing import TYPE_CHECKING, Literal, NotRequired, TypedDict+from pydantic import BaseModelfrom sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker-from switch_core.attachments import ATTACHMENT_GROUP_KEY-from switch_core.bridges.resource.events import (- ResourceLoadRequest,- ResourceLoadResponse,- RoomDocumentCreateRequest,- RoomDocumentCreateResponse,- RoomDocumentDeleteRequest,- RoomDocumentDeleteResponse,- RoomDocumentUpdateRequest,- RoomDocumentUpdateResponse,-)from switch_core.db.stores.client_store import ClientStorefrom switch_core.events import (AgentRuntimeStateEvent,CommandEvent,LlmCallReport,- MediationLlmRequest,- MediationLlmResponse,- MediationToolRequest,- MediationToolResult,- PermissionRequest,- PermissionResponse,SwitchEvent,TaskAccept,TaskCancel,@@ -59,6 +22,22 @@ from switch_core.events import (TaskUpdate,ToolCallReport,)+from switch_core.messages.recording import MessageRecording+from switch_core.transport import (+ InboundCustomEvent,+ InboundEvent,+ InboundMedia,+ InboundMembership,+ InboundMessage,+ MessageTransport,+ RoomRef,+ SendResult,+ TransportError,+ TransportHandlers,+)++if TYPE_CHECKING:+ from collections.abc import Callablelogger = logging.getLogger(__name__)@@ -79,23 +58,37 @@ SYNC_BACKOFF_BASE = 1.0SYNC_BACKOFF_CAP = 60.0-def _carries_durable_events(response: SyncResponse) -> bool:- """Whether a sync response holds anything a restart would need to replay.+class ClientConfig(BaseModel):+ pass+++class ClientBaseKwargs[ConfigT: ClientConfig](TypedDict):+ """What every `ClientBase` subclass must forward to `ClientBase`.- Timeline events, room state and invites are dispatched to handlers, so the- cursor must move past them durably. Presence, typing, receipts and account- data are not — they only advance the token.- """- if response.rooms.invite or response.to_device_events:- return True- return any(- room.timeline.events or room.state- for room in (*response.rooms.join.values(), *response.rooms.leave.values())- )+ Subclasses take their own arguments and pass the rest through. Spelled as+ `**kwargs: Any`, that pass-through is invisible to the type checker on both+ sides: the subclass cannot be told it is missing something, and a caller+ cannot be told it is passing something that no longer exists. A stale+ `device_id=` type-checked clean that way and took all four collaboration+ bridges down at startup — the credential had moved into `session_state`+ and nothing said so until the process refused to start.+ Declaring the shape here and unpacking it restores both checks without+ making every subclass restate eleven parameters.+ """-class ClientConfig(BaseModel):- pass+ client_id: str+ matrix_user_id: str+ display_name: str+ password: str+ server_url: str+ session_factory: async_sessionmaker[AsyncSession]+ client_store: ClientStore+ config: ConfigT+ transport_factory: Callable[[ClientBase[ConfigT]], MessageTransport]+ session_state: dict[str, str | None]+ message_recorder: MessageRecording+ next_batch_token: NotRequired[str | None]class ClientBase[ConfigT: ClientConfig]:@@ -112,8 +105,9 @@ class ClientBase[ConfigT: ClientConfig]:session_factory: async_sessionmaker[AsyncSession],client_store: ClientStore,config: ConfigT,- device_id: str | None = None,- access_token: str | None = None,+ transport_factory: Callable[[ClientBase[ConfigT]], MessageTransport],+ session_state: dict[str, str | None],+ message_recorder: MessageRecording,next_batch_token: str | None = None,) -> None:self.client_id = client_id@@ -124,12 +118,15 @@ class ClientBase[ConfigT: ClientConfig]:self.session_factory = session_factoryself.client_store = client_storeself.config = config+ self.message_recorder = message_recorder- self.device_id = device_id- self.access_token = access_token+ # Credentials the transport owns. Stored and handed back unread, so+ # what authentication needs is the transport's business alone.+ self.session_state = session_stateself.next_batch_token = next_batch_token- self.nio_client: AsyncClient | None = None+ self._transport_factory = transport_factory+ self.transport: MessageTransport | None = Noneself.room_join_times: dict[str, int] = {}self._room_joined_events: dict[str, asyncio.Event] = {}# Rooms this client has already announced its arrival in. Distinct from@@ -153,17 +150,13 @@ class ClientBase[ConfigT: ClientConfig]:await self._ready.wait()async def set_display_name(self, display_name: str) -> None:- """Change the name this client shows under in Matrix.+ """Change the name this client shows under.The user id is an address and stays put; this is the label roomsrender. Used to correct a puppet filed under a platform id before theplatform would say who the person was."""- resp = await self.client.set_displayname(display_name)- if isinstance(resp, ProfileSetDisplayNameError):- raise RuntimeError(- f"Could not set the display name of {self.matrix_user_id}: {resp}"- )+ await self._transport.set_display_name(display_name)self.display_name = display_namedef _joined_event(self, room_id: str) -> asyncio.Event:@@ -178,15 +171,7 @@ class ClientBase[ConfigT: ClientConfig]:self._joined_event(room_id).set()async def _is_joined_on_server(self, room_id: str) -> bool:- resp = await self.client.joined_rooms()- if isinstance(resp, JoinedRoomsError):- logger.error(- "Failed to list joined rooms for %s: %s",- self.matrix_user_id,- resp.message,- )- return False- return room_id in resp.rooms+ return room_id in await self._transport.joined_rooms()async def wait_joined(self, room_id: str, timeout: float) -> bool:"""Block until this client is a member of `room_id`, up to `timeout`@@ -214,12 +199,12 @@ class ClientBase[ConfigT: ClientConfig]:return True@property- def client(self) -> AsyncClient:- if self.nio_client is None:+ def _transport(self) -> MessageTransport:+ if self.transport is None:raise RuntimeError(f"Client {self.matrix_user_id} is not connected — call start() first")- return self.nio_client+ return self.transport# ── Lifecycle ──────────────────────────────────────────────────────────────@@ -234,9 +219,7 @@ class ClientBase[ConfigT: ClientConfig]:retries = 0while self._running:try:- await self.client.sync_forever(- timeout=30000, since=self.next_batch_token- )+ await self._transport.receive_forever(since=self.next_batch_token)retries = 0except Exception:if not self._running:@@ -264,20 +247,22 @@ class ClientBase[ConfigT: ClientConfig]:self._running = Falseawait self._persist_state(force=True)await self.teardown()- if self.nio_client:- await self.nio_client.close()+ if self.transport is not None:+ await self.transport.close()def setup(self) -> None:- self.client.add_event_callback(self._handle_message, RoomMessageText)- # RoomMessageMedia is the base of RoomMessageImage / RoomMessageFile, so- # one callback covers every media msgtype.- self.client.add_event_callback(self._handle_media, RoomMessageMedia)- self.client.add_event_callback(self._handle_reaction, ReactionEvent)- self.client.add_event_callback(self._handle_member_event, RoomMemberEvent)- self.client.add_event_callback(self._handle_custom_event, UnknownEvent)- self.client.add_event_callback(self._handle_invite, InviteMemberEvent) # type: ignore[arg-type]- self.client.add_response_callback(self._handle_sync, SyncResponse)- self.client.add_response_callback(self._handle_sync_error, SyncError)+ self._transport.register_handlers(+ TransportHandlers(+ on_message=self._handle_message,+ on_media=self._handle_media,+ on_reaction=self._handle_reaction,+ on_member_event=self._handle_member_event,+ on_custom_event=self._handle_custom_event,+ on_invite=self._handle_invite,+ on_sync=self._handle_sync,+ on_sync_error=self._handle_sync_error,+ )+ )async def teardown(self) -> None:pass@@ -285,32 +270,22 @@ class ClientBase[ConfigT: ClientConfig]:# ── Authentication ─────────────────────────────────────────────────────────async def _create_client(self) -> None:- self.nio_client = AsyncClient(self.server_url, self.matrix_user_id)-- if self.access_token and self.device_id:- self.client.access_token = self.access_token- self.client.device_id = self.device_id- logger.info(- "Client %s restored session from stored token", self.matrix_user_id- )- elif self.password:- resp = await self.client.login(self.password)- if isinstance(resp, LoginError):- raise RuntimeError(- f"Login failed for {self.matrix_user_id}: {resp.message}"- )- self.device_id = resp.device_id- self.access_token = self.client.access_token+ before = dict(self.session_state)+ self.transport = self._transport_factory(self)+ await self.transport.connect()+ self._absorb_session_state()+ if self.session_state != before:await self._persist_state(force=True)- logger.info("Client %s authenticated via password", self.matrix_user_id)- else:- raise RuntimeError(f"No credentials available for {self.matrix_user_id}")self._ready.set()+ def _absorb_session_state(self) -> None:+ """Take back whatever the transport wants persisted, without reading it."""+ self.session_state = dict(self._transport.session_state)+# ── Internal event handlers (filtering + dispatch to hooks) ────────────────- async def _handle_message(self, room: MatrixRoom, event: RoomMessageText) -> None:+ async def _handle_message(self, room: RoomRef, event: InboundMessage) -> None:if self._should_ignore(room, event):returntry:@@ -320,7 +295,7 @@ class ClientBase[ConfigT: ClientConfig]:"Error in on_message for %s in %s", self.matrix_user_id, room.room_id)- async def _handle_media(self, room: MatrixRoom, event: RoomMessageMedia) -> None:+ async def _handle_media(self, room: RoomRef, event: InboundMedia) -> None:if self._should_ignore(room, event):returntry:@@ -330,7 +305,7 @@ class ClientBase[ConfigT: ClientConfig]:"Error in on_media for %s in %s", self.matrix_user_id, room.room_id)- async def _handle_reaction(self, room: MatrixRoom, event: ReactionEvent) -> None:+ async def _handle_reaction(self, room: RoomRef, event: InboundEvent) -> None:if self._should_ignore(room, event):returntry:@@ -341,11 +316,21 @@ class ClientBase[ConfigT: ClientConfig]:)async def _handle_member_event(- self, room: MatrixRoom, event: RoomMemberEvent+ self, room: RoomRef, event: InboundMembership) -> None:if event.state_key == self.matrix_user_id:if event.membership == "join":- self._mark_joined(room.room_id, event.server_timestamp)+ self._mark_joined(room.room_id, event.timestamp)+ if event.prev_membership != "join":+ # Recorded on the arrival itself rather than under the+ # announcement guards below: the log wants every arrival,+ # including ones too old to be worth announcing.+ await self.message_recorder.record_join(+ transport_room_id=room.room_id,+ event=event,+ client_id=self.client_id,+ member_name=self.display_name,+ )# A membership-preserving update (display name, avatar) re-fires# m.room.member with membership == "join"; only a transition into# membership is an arrival. Joins predating this process are not@@ -353,7 +338,7 @@ class ClientBase[ConfigT: ClientConfig]:# the same join does not announce it twice.if (event.prev_membership != "join"- and event.server_timestamp >= self._startup_ts+ and event.timestamp >= self._startup_tsand room.room_id not in self._self_join_dispatched):self._self_join_dispatched.add(room.room_id)@@ -380,7 +365,7 @@ class ClientBase[ConfigT: ClientConfig]:room.room_id,)- async def _handle_invite(self, room: MatrixRoom, event: InviteMemberEvent) -> None:+ async def _handle_invite(self, room: RoomRef, event: InboundMembership) -> None:try:await self.on_invite(room, event)except Exception:@@ -390,22 +375,6 @@ class ClientBase[ConfigT: ClientConfig]:_EVENT_DISPATCH: dict[str, tuple[type[SwitchEvent], str]] = {"com.switch.command": (CommandEvent, "on_command"),- "com.switch.mediation.tool_request": (- MediationToolRequest,- "on_mediation_tool_request",- ),- "com.switch.mediation.llm_request": (- MediationLlmRequest,- "on_mediation_llm_request",- ),- "com.switch.mediation.tool_result": (- MediationToolResult,- "on_mediation_tool_result",- ),- "com.switch.mediation.llm_response": (- MediationLlmResponse,- "on_mediation_llm_response",- ),"com.switch.report.tool_call": (ToolCallReport, "on_tool_call_report"),"com.switch.report.llm_call": (LlmCallReport, "on_llm_call_report"),"com.switch.task.delegate": (TaskDelegate, "on_task_delegate"),@@ -417,61 +386,26 @@ class ClientBase[ConfigT: ClientConfig]:AgentRuntimeStateEvent,"on_agent_runtime_state",),- "com.switch.permission.request": (PermissionRequest, "on_permission_request"),- "com.switch.permission.response": (- PermissionResponse,- "on_permission_response",- ),- "com.switch.resource.load_request": (- ResourceLoadRequest,- "on_resource_load_request",- ),- "com.switch.resource.load_response": (- ResourceLoadResponse,- "on_resource_load_response",- ),- "com.switch.resource.room_document_create_request": (- RoomDocumentCreateRequest,- "on_room_document_create_request",- ),- "com.switch.resource.room_document_create_response": (- RoomDocumentCreateResponse,- "on_room_document_create_response",- ),- "com.switch.resource.room_document_update_request": (- RoomDocumentUpdateRequest,- "on_room_document_update_request",- ),- "com.switch.resource.room_document_update_response": (- RoomDocumentUpdateResponse,- "on_room_document_update_response",- ),- "com.switch.resource.room_document_delete_request": (- RoomDocumentDeleteRequest,- "on_room_document_delete_request",- ),- "com.switch.resource.room_document_delete_response": (- RoomDocumentDeleteResponse,- "on_room_document_delete_response",- ),}- async def _handle_custom_event(self, room: MatrixRoom, event: UnknownEvent) -> None:+ async def _handle_custom_event(+ self, room: RoomRef, event: InboundCustomEvent+ ) -> None:if self._should_ignore(room, event):return- entry = self._EVENT_DISPATCH.get(event.type)+ entry = self._EVENT_DISPATCH.get(event.event_type)if entry is None:- if event.type.startswith("com.switch.observe."):+ if event.event_type.startswith("com.switch.observe."):logger.warning("Observe event %s not yet supported in %s",- event.type,+ event.event_type,room.room_id,)else:logger.error("Unhandled custom event type %s in %s",- event.type,+ event.event_type,room.room_id,)return@@ -479,10 +413,12 @@ class ClientBase[ConfigT: ClientConfig]:event_class, method_name = entrytry:typed_event = event_class(- **event.source.get("content", {}),+ **event.content,)except Exception:- logger.exception("Failed to parse %s event in %s", event.type, room.room_id)+ logger.exception(+ "Failed to parse %s event in %s", event.event_type, room.room_id+ )return# Command results reply into the command's thread. When the command was@@ -491,174 +427,99 @@ class ClientBase[ConfigT: ClientConfig]:# Otherwise the command itself roots the thread — use its own event id.# The id is not part of the event content, so inject it here.if isinstance(typed_event, CommandEvent):- relates = event.source.get("content", {}).get("m.relates_to") or {}- if relates.get("rel_type") == "m.thread":- typed_event.thread_id = relates.get("event_id")- else:- typed_event.thread_id = event.event_id+ typed_event.thread_id = event.thread_root_id or event.event_idtry:await getattr(self, method_name)(room, typed_event)except Exception:- logger.exception("Error in handler for %s in %s", event.type, room.room_id)+ logger.exception(+ "Error in handler for %s in %s", event.event_type, room.room_id+ )- async def _handle_sync(self, response: SyncResponse) -> None:- if not response.next_batch or response.next_batch == self.next_batch_token:+ async def _handle_sync(self, next_batch: str, durable: bool) -> None:+ if not next_batch or next_batch == self.next_batch_token:return- self.next_batch_token = response.next_batch- if _carries_durable_events(response):+ self.next_batch_token = next_batch+ if durable:await self._persist_state()returnself._sync_state_dirty = Trueif (time.monotonic() - self._last_sync_persist) >= SYNC_STATE_MAX_STALENESS:await self._persist_state(force=True)- async def _handle_sync_error(self, response: SyncError) -> None:- logger.error("Sync error for %s: %s", self.matrix_user_id, response.message)+ async def _handle_sync_error(self, message: str) -> None:+ logger.error("Sync error for %s: %s", self.matrix_user_id, message)if self.password:logger.info("Attempting re-login for %s", self.matrix_user_id)- resp = await self.client.login(self.password)- if isinstance(resp, LoginError):- logger.error(- "Re-login failed for %s: %s", self.matrix_user_id, resp.message- )+ try:+ await self._transport.relogin()+ except TransportError as exc:+ logger.error("%s", exc)+ return+ self._absorb_session_state()# ── Filtering ──────────────────────────────────────────────────────────────- def _should_ignore(self, room: MatrixRoom, event: object) -> bool:- sender = getattr(event, "sender", None)- if sender == self.matrix_user_id:+ def _should_ignore(self, room: RoomRef, event: InboundEvent) -> bool:+ if event.sender == self.matrix_user_id:return True- server_ts = getattr(event, "server_timestamp", None)- if server_ts is not None:+ if event.timestamp:join_time = self.room_join_times.get(room.room_id, self._startup_ts)- if server_ts < join_time:+ if event.timestamp < join_time:return Truereturn False# ── Event hooks (subclasses override) ──────────────────────────────────────- async def on_message(self, room: MatrixRoom, event: RoomMessageText) -> None:+ async def on_message(self, room: RoomRef, event: InboundMessage) -> None:pass- async def on_media(self, room: MatrixRoom, event: RoomMessageMedia) -> None:+ async def on_media(self, room: RoomRef, event: InboundMedia) -> None:pass- async def on_reaction(self, room: MatrixRoom, event: ReactionEvent) -> None:+ async def on_reaction(self, room: RoomRef, event: InboundEvent) -> None:pass- async def on_self_join(self, room: MatrixRoom, event: RoomMemberEvent) -> None:+ async def on_self_join(self, room: RoomRef, event: InboundMembership) -> None:pass- async def on_member_event(self, room: MatrixRoom, event: RoomMemberEvent) -> None:+ async def on_member_event(self, room: RoomRef, event: InboundMembership) -> None:pass- async def on_invite(self, room: MatrixRoom, event: InviteMemberEvent) -> None:+ async def on_invite(self, room: RoomRef, event: InboundMembership) -> None:logger.info("Client %s auto-accepting invite to %s", self.matrix_user_id, room.room_id)await self.join_room(room.room_id)- async def on_command(self, room: MatrixRoom, event: CommandEvent) -> None:- pass-- async def on_mediation_tool_request(- self, room: MatrixRoom, event: MediationToolRequest- ) -> None:- pass-- async def on_mediation_llm_request(- self, room: MatrixRoom, event: MediationLlmRequest- ) -> None:- pass-- async def on_mediation_tool_result(- self, room: MatrixRoom, event: MediationToolResult- ) -> None:- pass-- async def on_mediation_llm_response(- self, room: MatrixRoom, event: MediationLlmResponse- ) -> None:+ async def on_command(self, room: RoomRef, event: CommandEvent) -> None:pass- async def on_tool_call_report(- self, room: MatrixRoom, event: ToolCallReport- ) -> None:+ async def on_tool_call_report(self, room: RoomRef, event: ToolCallReport) -> None:pass- async def on_llm_call_report(self, room: MatrixRoom, event: LlmCallReport) -> None:+ async def on_llm_call_report(self, room: RoomRef, event: LlmCallReport) -> None:pass- async def on_task_delegate(self, room: MatrixRoom, event: TaskDelegate) -> None:+ async def on_task_delegate(self, room: RoomRef, event: TaskDelegate) -> None:pass- async def on_task_accept(self, room: MatrixRoom, event: TaskAccept) -> None:+ async def on_task_accept(self, room: RoomRef, event: TaskAccept) -> None:pass- async def on_task_update(self, room: MatrixRoom, event: TaskUpdate) -> None:+ async def on_task_update(self, room: RoomRef, event: TaskUpdate) -> None:pass- async def on_task_finalise(self, room: MatrixRoom, event: TaskFinalise) -> None:+ async def on_task_finalise(self, room: RoomRef, event: TaskFinalise) -> None:pass- async def on_task_cancel(self, room: MatrixRoom, event: TaskCancel) -> None:+ async def on_task_cancel(self, room: RoomRef, event: TaskCancel) -> None:passasync def on_agent_runtime_state(- self, room: MatrixRoom, event: AgentRuntimeStateEvent- ) -> None:- pass-- async def on_permission_request(- self, room: MatrixRoom, event: PermissionRequest- ) -> None:- pass-- async def on_permission_response(- self, room: MatrixRoom, event: PermissionResponse- ) -> None:- pass-- async def on_resource_load_request(- self, room: MatrixRoom, event: ResourceLoadRequest- ) -> None:- pass-- async def on_room_document_create_request(- self, room: MatrixRoom, event: RoomDocumentCreateRequest- ) -> None:- pass-- async def on_room_document_create_response(- self, room: MatrixRoom, event: RoomDocumentCreateResponse- ) -> None:- pass-- async def on_room_document_update_request(- self, room: MatrixRoom, event: RoomDocumentUpdateRequest- ) -> None:- pass-- async def on_room_document_update_response(- self, room: MatrixRoom, event: RoomDocumentUpdateResponse- ) -> None:- pass-- async def on_room_document_delete_request(- self, room: MatrixRoom, event: RoomDocumentDeleteRequest- ) -> None:- pass-- async def on_room_document_delete_response(- self, room: MatrixRoom, event: RoomDocumentDeleteResponse- ) -> None:- pass-- async def on_resource_load_response(- self, room: MatrixRoom, event: ResourceLoadResponse+ self, room: RoomRef, event: AgentRuntimeStateEvent) -> None:pass@@ -674,61 +535,43 @@ class ClientBase[ConfigT: ClientConfig]:thread_root_id: str | None = None,extra_content: dict[str, object] | None = None,) -> str | None:- content: dict[str, object] = {- "msgtype": "m.text",- "body": body,- "sender_name": self.display_name,- }- # Caller-supplied content fields (e.g. a `com.switch.*` marker) are- # merged in. They ride on the plain m.room.message — the body still- # renders normally; the extra keys are metadata other clients can read.- if extra_content:- content.update(extra_content)-- if format == "markdown":- html = markdown.markdown(body)- if mentions:- for user_id in mentions:- local = user_id.split(":")[0].lstrip("@")- pill = f'<a href="https://matrix.to/#/{user_id}">{local}</a>'- html = html.replace(f"@{local}", pill)- content["format"] = "org.matrix.custom.html"- content["formatted_body"] = html-- # Threaded reply: relate this message to the thread root via a pure- # m.thread relation (no m.in_reply_to fallback). The root id must be an- # actual thread root — callers normalise mid-thread ids upstream.- if thread_root_id is not None:- content["m.relates_to"] = {- "rel_type": "m.thread",- "event_id": thread_root_id,- }-- resp = await self.client.room_send(room_id, "m.room.message", content)-- if isinstance(resp, RoomSendError):- logger.error("Failed to send message to %s: %s", room_id, resp.message)+ try:+ result = await self._transport.send_message(+ room_id,+ body,+ sender_name=self.display_name,+ format=format,+ mentions=mentions,+ thread_root_id=thread_root_id,+ extra_content=extra_content,+ )+ except TransportError as exc:+ logger.error("Failed to send message to %s: %s", room_id, exc)return None+ await self._record(room_id, result)+ return result.event_id- return resp.event_id # type: ignore[no-any-return]+ async def send_event(+ self, room_id: str, event_type: str, content: dict[str, object]+ ) -> str:+ """Send a custom event, e.g. one of the `com.switch.*` types.++ Raises rather than returning None: unlike a chat message, these events+ carry protocol state, and a caller that proceeds as though one was+ delivered when it was not corrupts whatever it was coordinating.+ """+ result = await self._transport.send_event(room_id, event_type, content)+ await self._record(room_id, result)+ return result.event_idasync def upload_media(self, data: bytes, content_type: str, filename: str) -> str:- """Upload bytes to the Matrix media repository and return the mxc URI.+ """Upload bytes to the media store and return the URI referencing them.Raises on failure — a media upload that silently returns None wouldproduce a broken event referencing nothing."""- resp, _ = await self.client.upload(- data_provider=io.BytesIO(data),- content_type=content_type,- filename=filename,- filesize=len(data),- )- if isinstance(resp, UploadError):- raise RuntimeError(- f"Failed to upload media '{filename}' to Matrix: {resp.message}"- )- return resp.content_uri # type: ignore[no-any-return]+ result = await self._transport.upload_media(data, content_type, filename)+ return result.uriasync def send_media(self,@@ -757,53 +600,43 @@ class ClientBase[ConfigT: ClientConfig]:receivers coalesce back into one logical message. Absent the field, anevent is simply a group of one."""- content: dict[str, object] = {- "msgtype": msgtype,- "body": caption if caption else filename,- "url": mxc,- "info": {"mimetype": mimetype, "size": size},- "sender_name": self.display_name,- }- if caption:- content["filename"] = filename- if group is not None:- content[ATTACHMENT_GROUP_KEY] = group- if thread_root_id is not None:- content["m.relates_to"] = {- "rel_type": "m.thread",- "event_id": thread_root_id,- }-- resp = await self.client.room_send(room_id, "m.room.message", content)-- if isinstance(resp, RoomSendError):- logger.error("Failed to send media to %s: %s", room_id, resp.message)+ try:+ result = await self._transport.send_media(+ room_id,+ mxc,+ filename,+ mimetype,+ size,+ sender_name=self.display_name,+ msgtype=msgtype,+ caption=caption,+ thread_root_id=thread_root_id,+ group=group,+ )+ except TransportError as exc:+ logger.error("Failed to send media to %s: %s", room_id, exc)return None-- return resp.event_id # type: ignore[no-any-return]+ await self._record(room_id, result)+ return result.event_id++ async def _record(self, room_id: str, result: SendResult) -> None:+ await self.message_recorder.record(+ transport_room_id=room_id,+ result=result,+ sender_matrix_id=self.matrix_user_id,+ sender_client_id=self.client_id,+ sender_name=self.display_name,+ )async def set_typing(self, room_id: str, is_typing: bool) -> None:- logger.debug(- "Setting typing %s in room %s for matrix user %s",- is_typing,- room_id,- self.matrix_user_id,- )- resp = await self.client.room_typing(room_id, is_typing)- if isinstance(resp, RoomTypingError):- logger.error("Failed to set typing in %s: %s", room_id, resp.message)+ await self._transport.set_typing(room_id, is_typing)# ── Room operations ────────────────────────────────────────────────────────async def join_room(self, room_id: str) -> None:- resp = await self.client.join(room_id)- if hasattr(resp, "room_id"):+ if await self._transport.join_room(room_id):self._mark_joined(room_id, int(time.time() * 1000))logger.info("Client %s joined %s", self.matrix_user_id, room_id)- else:- logger.error(- "Client %s failed to join %s: %s", self.matrix_user_id, room_id, resp- )# ── State persistence ──────────────────────────────────────────────────────@@ -818,9 +651,8 @@ class ClientBase[ConfigT: ClientConfig]:await self.client_store.update_state(session,self.client_id,- access_token=self.access_token,- device_id=self.device_id,next_batch_token=self.next_batch_token,+ **self.session_state,)await session.commit()self._last_sync_persist = nowdiff --git a/core/switch_core/clients/client_factory.py b/core/switch_core/clients/client_factory.pyindex eee10bc33..37c2b6fef 100644--- a/core/switch_core/clients/client_factory.py+++ b/core/switch_core/clients/client_factory.py@@ -1,6 +1,7 @@from __future__ import annotationsimport logging+from typing import Anyfrom sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker@@ -8,10 +9,40 @@ from switch_core.clients.client_base import ClientBase, ClientConfigfrom switch_core.config import SwitchConfigfrom switch_core.db.models import Clientfrom switch_core.db.stores.client_store import ClientStore+from switch_core.db.stores.media_store import MediaStore+from switch_core.db.stores.message_store import MessageStore+from switch_core.db.stores.room_store import RoomStore+from switch_core.messages import MessageRecorder+from switch_core.messages.notify import MessageListener+from switch_core.messages.recording import MessageRecording, NoRecording+from switch_core.transport import MessageTransport+from switch_core.transport.ephemeral import EphemeralBus+from switch_core.transport.invites import InviteBus+from switch_core.transport.matrix import MatrixTransport+from switch_core.transport.postgres import PostgresTransportlogger = logging.getLogger(__name__)+def matrix_transport_for(client: ClientBase[Any]) -> MessageTransport:+ """Build the transport a client runs on.++ Choosing the implementation is the factory's job, so a client never names+ one.++ The config type is `Any` because nothing here reads the config: a factory+ that works for every client would otherwise have to be re-typed for each+ subclass, since `ClientBase` is invariant in it.+ """+ return MatrixTransport(+ server_url=client.server_url,+ user_id=client.matrix_user_id,+ password=client.password,+ device_id=client.session_state.get("device_id"),+ access_token=client.session_state.get("access_token"),+ )++class ClientFactory:def __init__(self,@@ -19,10 +50,24 @@ class ClientFactory:client_store: ClientStore,session_factory: async_sessionmaker[AsyncSession],config: SwitchConfig,+ message_recorder: MessageRecorder,+ room_store: RoomStore,+ message_store: MessageStore,+ media_store: MediaStore,+ listener: MessageListener,+ invites: InviteBus,+ ephemeral: EphemeralBus,) -> None:self._client_store = client_storeself._session_factory = session_factoryself._config = config+ self._message_recorder = message_recorder+ self._room_store = room_store+ self._message_store = message_store+ self._media_store = media_store+ self._listener = listener+ self._invites = invites+ self._ephemeral = ephemeralself._registry: dict[str, tuple[type[ClientBase[ClientConfig]], dict[str, object]]] = {}@@ -50,8 +95,50 @@ class ClientFactory:session_factory=self._session_factory,client_store=self._client_store,config=config,- device_id=record.device_id,- access_token=record.access_token,+ transport_factory=self.transport_for,+ message_recorder=self.recorder(),+ session_state={+ "access_token": record.access_token,+ "device_id": record.device_id,+ },next_batch_token=record.next_batch_token,**extra_kwargs,)++ def transport_for(self, client: ClientBase[Any]) -> MessageTransport:+ """The transport every client in the process runs on.++ Public because not every client is built by `create`: a collaboration+ bridge's client is constructed by its own lifecycle service, which+ carries per-bridge state the registry cannot hold. It still has to make+ the same choice, and a caller that named an implementation directly+ would put its clients on a different bus from everyone else's — agents+ talking in rows while bridges talk to a homeserver, each side healthy+ and neither reaching the other.+ """+ if self._config.message_transport == "matrix":+ return matrix_transport_for(client)+ return PostgresTransport(+ user_id=client.matrix_user_id,+ client_id=client.client_id,+ display_name=client.display_name,+ session_factory=self._session_factory,+ room_store=self._room_store,+ message_store=self._message_store,+ media_store=self._media_store,+ listener=self._listener,+ invites=self._invites,+ ephemeral=self._ephemeral,+ )++ def recorder(self) -> MessageRecording:+ """The recorder that goes with the transport.++ Paired here rather than configured separately: a transport that stores+ what it carries needs no recorder, and one that does not needs one.+ Splitting the decision would let a deployment pick both and write every+ message twice.+ """+ if self._config.message_transport == "matrix":+ return self._message_recorder+ return NoRecording()diff --git a/core/switch_core/clients/client_lifecycle_service.py b/core/switch_core/clients/client_lifecycle_service.pyindex cd7f674b3..a76b8ba74 100644--- a/core/switch_core/clients/client_lifecycle_service.py+++ b/core/switch_core/clients/client_lifecycle_service.py@@ -12,7 +12,7 @@ from switch_core.clients.client_factory import ClientFactoryfrom switch_core.config import SwitchConfigfrom switch_core.db.models import Clientfrom switch_core.db.stores.client_store import ClientStore-from switch_core.matrix_admin import MatrixAdmin+from switch_core.provisioning import Provisioninglogger = logging.getLogger(__name__)@@ -21,7 +21,7 @@ class ClientLifecycleService:def __init__(self,*,- matrix_admin: MatrixAdmin,+ matrix_admin: Provisioning,client_store: ClientStore,client_factory: ClientFactory,session_factory: async_sessionmaker[AsyncSession],diff --git a/core/switch_core/clients/resource_manager_client.py b/core/switch_core/clients/resource_manager_client.pydeleted file mode 100644index 3da9067b8..000000000--- a/core/switch_core/clients/resource_manager_client.py+++ /dev/null@@ -1,295 +0,0 @@-from __future__ import annotations--import logging-from typing import Any--from nio import MatrixRoom--from switch_core.bridges.agent.request_tracker import RequestTracker-from switch_core.bridges.resource.events import (- ResourceLoadRequest,- ResourceLoadResponse,- RoomDocumentCreateRequest,- RoomDocumentCreateResponse,- RoomDocumentDeleteRequest,- RoomDocumentDeleteResponse,- RoomDocumentUpdateRequest,- RoomDocumentUpdateResponse,-)-from switch_core.bridges.resource.service import ResourceService-from switch_core.clients.client_base import ClientBase, ClientConfig-from switch_core.db.stores.agent_store import AgentStore-from switch_core.db.stores.room_store import RoomStore-from switch_core.events import (- MediationLlmRequest,- MediationResult,- MediationToolRequest,-)--logger = logging.getLogger(__name__)---class ResourceManagerClient(ClientBase[ClientConfig]):- def __init__(- self,- *,- agent_store: AgentStore,- room_store: RoomStore,- resource_service: ResourceService,- request_tracker: RequestTracker,- **kwargs: Any,- ) -> None:- super().__init__(**kwargs)- self._agent_store = agent_store- self._room_store = room_store- self._resource_service = resource_service- self._request_tracker = request_tracker-- async def on_mediation_tool_request(- self, room: MatrixRoom, event: MediationToolRequest- ) -> None:- verdict, reason = await self._check_tool_access(event.agent_id, event.tool_id)- result = MediationResult(verdict=verdict, reason=reason)- self._request_tracker.resolve(event.request_id, result)-- async def on_mediation_llm_request(- self, room: MatrixRoom, event: MediationLlmRequest- ) -> None:- verdict, reason = await self._check_model_access(event.agent_id, event.model_id)- result = MediationResult(verdict=verdict, reason=reason)- self._request_tracker.resolve(event.request_id, result)-- async def on_resource_load_request(- self, room: MatrixRoom, event: ResourceLoadRequest- ) -> None:- """Fetch the requested documents and reply with a load_response.-- The agent's membership in the room is implicit (the request was sent- in this room) and the service validates that each requested doc is- actually attached here — preventing cross-room access.- """- response: ResourceLoadResponse- if self.nio_client is None:- logger.error(- "Resource manager not connected; cannot send load response %s",- event.request_id,- )- return- try:- async with self.session_factory() as session:- switch_room = await self._room_store.get_by_matrix_room_id(- session, room.room_id- )- if switch_room is None:- raise ValueError(- f"No Switch room maps to matrix room {room.room_id}"- )- entries = await self._resource_service.load_documents(- session, switch_room.id, event.document_ids- )- response = ResourceLoadResponse(- request_id=event.request_id,- agent_id=event.agent_id,- status="ok",- documents=entries,- )- except Exception as exc:- logger.exception(- "Failed to load documents for request %s", event.request_id- )- response = ResourceLoadResponse(- request_id=event.request_id,- agent_id=event.agent_id,- status="error",- error=str(exc),- )-- await self.nio_client.room_send(- room.room_id,- "com.switch.resource.load_response",- response.model_dump(mode="json"),- )-- async def on_room_document_create_request(- self, room: MatrixRoom, event: RoomDocumentCreateRequest- ) -> None:- if self.nio_client is None:- logger.error(- "Resource manager not connected; cannot reply to %s", event.request_id- )- return- response: RoomDocumentCreateResponse- try:- async with self.session_factory() as session:- switch_room = await self._room_store.get_by_matrix_room_id(- session, room.room_id- )- if switch_room is None:- raise ValueError(- f"No Switch room maps to matrix room {room.room_id}"- )- agent = await self._agent_store.get(session, event.agent_id)- doc = await self._resource_service.create_room_document(- session,- room_id=switch_room.id,- agent_id=event.agent_id,- owner_id=agent.owner_id if agent is not None else None,- name=event.name,- description=event.description,- instructions=event.instructions,- content=event.content,- )- await session.commit()- response = RoomDocumentCreateResponse(- request_id=event.request_id,- agent_id=event.agent_id,- status="ok",- document_id=doc.id,- document_name=doc.name,- )- except Exception as exc:- logger.exception(- "Failed to create room document for request %s", event.request_id- )- response = RoomDocumentCreateResponse(- request_id=event.request_id,- agent_id=event.agent_id,- status="error",- error=str(exc),- )-- await self.nio_client.room_send(- room.room_id,- "com.switch.resource.room_document_create_response",- response.model_dump(mode="json"),- )-- async def on_room_document_update_request(- self, room: MatrixRoom, event: RoomDocumentUpdateRequest- ) -> None:- if self.nio_client is None:- logger.error(- "Resource manager not connected; cannot reply to %s", event.request_id- )- return- response: RoomDocumentUpdateResponse- try:- async with self.session_factory() as session:- switch_room = await self._room_store.get_by_matrix_room_id(- session, room.room_id- )- if switch_room is None:- raise ValueError(- f"No Switch room maps to matrix room {room.room_id}"- )- doc = await self._resource_service.update_room_document(- session,- room_id=switch_room.id,- agent_id=event.agent_id,- document_id=event.document_id,- name=event.name,- description=event.description,- instructions=event.instructions,- content=event.content,- )- await session.commit()- response = RoomDocumentUpdateResponse(- request_id=event.request_id,- agent_id=event.agent_id,- status="ok",- document_name=doc.name,- )- except Exception as exc:- logger.exception(- "Failed to update room document for request %s", event.request_id- )- response = RoomDocumentUpdateResponse(- request_id=event.request_id,- agent_id=event.agent_id,- status="error",- error=str(exc),- )-- await self.nio_client.room_send(- room.room_id,- "com.switch.resource.room_document_update_response",- response.model_dump(mode="json"),- )-- async def on_room_document_delete_request(- self, room: MatrixRoom, event: RoomDocumentDeleteRequest- ) -> None:- if self.nio_client is None:- logger.error(- "Resource manager not connected; cannot reply to %s", event.request_id- )- return- response: RoomDocumentDeleteResponse- deleted_name: str | None = None- try:- async with self.session_factory() as session:- switch_room = await self._room_store.get_by_matrix_room_id(- session, room.room_id- )- if switch_room is None:- raise ValueError(- f"No Switch room maps to matrix room {room.room_id}"- )- doc = await self._resource_service.get_room_scoped_document(- session, switch_room.id, event.document_id- )- deleted_name = doc.name- await self._resource_service.delete_room_document(- session,- room_id=switch_room.id,- agent_id=event.agent_id,- document_id=event.document_id,- )- await session.commit()- response = RoomDocumentDeleteResponse(- request_id=event.request_id,- agent_id=event.agent_id,- status="ok",- document_name=deleted_name,- )- except Exception as exc:- logger.exception(- "Failed to delete room document for request %s", event.request_id- )- response = RoomDocumentDeleteResponse(- request_id=event.request_id,- agent_id=event.agent_id,- status="error",- error=str(exc),- )-- await self.nio_client.room_send(- room.room_id,- "com.switch.resource.room_document_delete_response",- response.model_dump(mode="json"),- )-- async def _check_tool_access(- self, agent_id: str, tool_name: str- ) -> tuple[str, str | None]:- async with self.session_factory() as session:- tools = await self._agent_store.get_tools(session, agent_id)-- if any(t.name == tool_name for t in tools):- return "proceed", None-- return "blocked", f"Agent {agent_id} does not have tool '{tool_name}' attached"-- async def _check_model_access(- self, agent_id: str, model_name: str- ) -> tuple[str, str | None]:- async with self.session_factory() as session:- models = await self._agent_store.get_models(session, agent_id)-- if any(m.name == model_name for m in models):- return "proceed", None-- return (- "blocked",- f"Agent {agent_id} does not have model '{model_name}' attached",- )diff --git a/core/switch_core/config.py b/core/switch_core/config.pyindex 1709ffe53..9fd8fa840 100644--- a/core/switch_core/config.py+++ b/core/switch_core/config.py@@ -1,4 +1,5 @@import re+from typing import Literalfrom urllib.parse import urlsplitfrom pydantic import model_validator@@ -17,6 +18,13 @@ class SwitchConfig(BaseSettings):db_password: strdb_name: str+ # Which transport carries messages: "matrix" for the homeserver,+ # "postgres" for the message table. The choice pairs a transport with a+ # provisioning implementation and a recorder, so it is one setting rather+ # than three. Defaults to matrix, so an existing deployment is unchanged+ # until it is asked to move.+ message_transport: Literal["matrix", "postgres"] = "matrix"+matrix_server: strmatrix_server_name: strmatrix_admin_user: strdiff --git a/core/switch_core/db/engine.py b/core/switch_core/db/engine.pyindex aeb425a9a..053c4a9bc 100644--- a/core/switch_core/db/engine.py+++ b/core/switch_core/db/engine.py@@ -4,6 +4,7 @@ from sqlalchemy.ext.asyncio import (async_sessionmaker,create_async_engine,)+from sqlalchemy.pool import NullPoolfrom switch_core.config import SwitchConfig@@ -46,5 +47,21 @@ def create_engine_from_config(return create_async_engine(config.database_url, **defaults)+def create_unpooled_engine(config: SwitchConfig) -> AsyncEngine:+ """An engine for a connection that is held rather than borrowed.++ A `LISTEN` lives on one connection for the process's life. Every pool+ setting is either meaningless for that or actively harmful — recycling+ would drop the subscription, and the silence afterwards is indistinguishable+ from a quiet room — so it takes the connection arguments and none of the+ pooling.+ """+ return create_async_engine(+ config.database_url,+ poolclass=NullPool,+ connect_args=app_connect_args(config),+ )++def create_session_factory(engine: AsyncEngine) -> async_sessionmaker[AsyncSession]:return async_sessionmaker(bind=engine, expire_on_commit=False)diff --git a/core/switch_core/db/models.py b/core/switch_core/db/models.pyindex 6798bfe95..19b157c2e 100644--- a/core/switch_core/db/models.py+++ b/core/switch_core/db/models.py@@ -1,15 +1,20 @@import uuidfrom sqlalchemy import (+ DDL,+ BigInteger,Boolean,CheckConstraint,Column,DateTime,ForeignKey,Index,+ Integer,+ LargeBinary,Table,Text,UniqueConstraint,+ event,func,text,)@@ -17,6 +22,11 @@ from sqlalchemy.dialects.postgresql import JSONBfrom sqlalchemy.orm import Mapped, mapped_columnfrom switch_core.db.base import Base+from switch_core.db.notify_ddl import (+ CREATE_NOTIFY_FUNCTION,+ CREATE_NOTIFY_TRIGGER,+ DROP_NOTIFY_TRIGGER,+)def _uuid() -> str:@@ -95,6 +105,7 @@ class ClientRoom(Base):class Agent(Base):__tablename__ = "agents"+ __table_args__ = (Index("ix_agents_parent_agent_id", "parent_agent_id"),)id: Mapped[str] = mapped_column(Text, primary_key=True, default=_uuid)name: Mapped[str] = mapped_column(Text, unique=True, nullable=False)@@ -294,6 +305,14 @@ class Room(Base):archived_at: Mapped[str | None] = mapped_column(DateTime(timezone=True), nullable=True)+ # Set when this room's history has been walked to its start and written+ # into the message log. Null means never completed — including a walk that+ # stopped at the page limit, which leaves the room partly reconstructed.+ # The walk always starts from the newest message, so without this a re-run+ # reads every page of every room again to discover it has nothing to do.+ history_backfilled_at: Mapped[str | None] = mapped_column(+ DateTime(timezone=True), nullable=True+ )# ── Room Groups ─────────────────────────────────────────────────────────────────@@ -612,6 +631,7 @@ class ExternalUserClaim(Base):"""__tablename__ = "external_user_claims"+ __table_args__ = (Index("ix_external_user_claims_user_id", "user_id"),)external_user_id: Mapped[str] = mapped_column(Text,@@ -657,6 +677,8 @@ class AgentSession(Base):text("coalesce(room_id, '')"),unique=True,),+ Index("ix_agent_sessions_agent_room", "agent_id", "room_id"),+ Index("ix_agent_sessions_transport_session_id", "transport_session_id"),)id: Mapped[str] = mapped_column(Text, primary_key=True, default=_uuid)@@ -854,3 +876,183 @@ class FeatureFlag(Base):onupdate=func.now(),nullable=False,)+++# ── Messages ─────────────────────────────────────────────────────────────────+++class Message(Base):+ """A message as it was sent into a room.++ Written alongside the send to the message bus, which remains the source of+ truth for history until the read path moves here. Rows are therefore a+ parallel record, not yet an authoritative one: a write that fails after a+ successful send leaves a gap, by design, so that a database problem cannot+ make messaging less reliable.++ Every participant in a room is a Switch-owned client, so recording each+ send captures the whole room exactly once — including messages a human+ originates on a bridged platform, which enter through that user's puppet.++ `content` is the full event body as sent. The columns beside it are+ denormalised out of it for querying; for a custom `com.switch.*` event+ they are mostly null and `content` carries everything.+ """++ __tablename__ = "messages"+ __table_args__ = (+ UniqueConstraint("room_id", "seq", name="uq_messages_room_seq"),+ # `seq` orders the room and is what the read path pages on; `sent_at`+ # is what a caller asking for a time window filters by, so it needs an+ # index of its own rather than a scan back along seq.+ Index("ix_messages_room_sent_at", "room_id", "sent_at"),+ Index(+ "ix_messages_thread_root",+ "room_id",+ "thread_root_event_id",+ postgresql_where=text("thread_root_event_id IS NOT NULL"),+ ),+ )++ id: Mapped[str] = mapped_column(Text, primary_key=True, default=_uuid)+ # Position within the room, from 1, and the cursor the read path pages on.+ # Assigned by MessageStore.create under a per-room lock rather than by a+ # sequence: a sequence hands out numbers when a statement runs, not when it+ # commits, so a row can commit after one with a higher number and a reader+ # paging on `seq > n` would step straight over it. See the store for the+ # argument in full.+ seq: Mapped[int] = mapped_column(BigInteger, nullable=False)+ room_id: Mapped[str] = mapped_column(+ Text, ForeignKey("rooms.id", ondelete="CASCADE"), nullable=False+ )+ transport_event_id: Mapped[str] = mapped_column(Text, unique=True, nullable=False)+ sender_matrix_id: Mapped[str] = mapped_column(Text, nullable=False)+ sender_client_id: Mapped[str | None] = mapped_column(+ Text, ForeignKey("clients.id", ondelete="SET NULL"), nullable=True+ )+ sender_name: Mapped[str | None] = mapped_column(Text, nullable=True)+ event_type: Mapped[str] = mapped_column(Text, nullable=False)+ msgtype: Mapped[str | None] = mapped_column(Text, nullable=True)+ body: Mapped[str | None] = mapped_column(Text, nullable=True)+ formatted_body: Mapped[str | None] = mapped_column(Text, nullable=True)+ thread_root_event_id: Mapped[str | None] = mapped_column(Text, nullable=True)+ content: Mapped[dict] = mapped_column(JSONB, nullable=False)+ sent_at: Mapped[str] = mapped_column(+ DateTime(timezone=True), server_default=func.now(), nullable=False+ )+++class MessageAttachment(Base):+ """A file carried by a message.++ One row per file, so a multi-file send is several rows against one message+ in the order they were sent.+ """++ __tablename__ = "message_attachments"+ __table_args__ = (Index("ix_message_attachments_message", "message_id"),)++ id: Mapped[str] = mapped_column(Text, primary_key=True, default=_uuid)+ message_id: Mapped[str] = mapped_column(+ Text, ForeignKey("messages.id", ondelete="CASCADE"), nullable=False+ )+ position: Mapped[int] = mapped_column(Integer, nullable=False)+ uri: Mapped[str] = mapped_column(Text, nullable=False)+ filename: Mapped[str | None] = mapped_column(Text, nullable=True)+ mimetype: Mapped[str | None] = mapped_column(Text, nullable=True)+ size: Mapped[int | None] = mapped_column(BigInteger, nullable=True)+ created_at: Mapped[str] = mapped_column(+ DateTime(timezone=True), server_default=func.now(), nullable=False+ )+++class DeliveryCursor(Base):+ """How far one agent has been delivered in one room.++ The cursor it replaces lived in memory in the event buffer, so a restart+ resumed from wherever that buffer happened to be rather than from what the+ agent had actually been given. Persisting it makes "what has this agent+ seen" outlive the process, which is what lets delivery be driven from the+ table instead of from a live connection.++ `last_seq` is a position in the room, not a count: `seq` is a per-room+ total order, so "everything up to n" is unambiguous and re-reading from it+ is idempotent. It is only ever advanced, never rewound — a cursor that+ could go backwards would redeliver, and a redelivered message is+ indistinguishable to a reader from a new one.+ """++ __tablename__ = "delivery_cursors"+ __table_args__ = (+ UniqueConstraint("agent_id", "room_id", name="uq_delivery_cursors_agent_room"),+ )++ id: Mapped[str] = mapped_column(Text, primary_key=True, default=_uuid)+ agent_id: Mapped[str] = mapped_column(+ Text, ForeignKey("agents.id", ondelete="CASCADE"), nullable=False+ )+ room_id: Mapped[str] = mapped_column(+ Text, ForeignKey("rooms.id", ondelete="CASCADE"), nullable=False+ )+ last_seq: Mapped[int] = mapped_column(BigInteger, nullable=False, default=0)+ updated_at: Mapped[str] = mapped_column(+ DateTime(timezone=True),+ server_default=func.now(),+ onupdate=func.now(),+ nullable=False,+ )+++class MediaBlob(Base):+ """The bytes behind an attachment.++ Media used to live in the homeserver's own store, reached by an opaque+ handle that travelled on the message. The handle is still opaque and still+ travels on the message; only what is behind it changed. Callers must not+ parse `uri` — it is a key, and the store behind it is free to become object+ storage without the protocol noticing.++ `bytea` rather than a large object: attachments are capped+ (`agent_media_max_bytes`, 20MB by default) and are written and read whole,+ which is exactly what TOAST handles well and what large objects add+ lifecycle problems to. A blob that would not fit is rejected at the edge,+ loudly, as it already is.++ Rows are not reference-counted against the attachments pointing at them.+ Deleting a room deletes its messages; the bytes it referenced are then+ unreferenced and a later sweep can find them by that. Cascading from the+ attachment instead would delete the bytes of a file that two messages+ quote.+ """++ __tablename__ = "media_blobs"++ id: Mapped[str] = mapped_column(Text, primary_key=True, default=_uuid)+ uri: Mapped[str] = mapped_column(Text, unique=True, nullable=False)+ content_type: Mapped[str | None] = mapped_column(Text, nullable=True)+ filename: Mapped[str | None] = mapped_column(Text, nullable=True)+ size: Mapped[int] = mapped_column(BigInteger, nullable=False)+ data: Mapped[bytes] = mapped_column(LargeBinary, nullable=False)+ created_at: Mapped[str] = mapped_column(+ DateTime(timezone=True), server_default=func.now(), nullable=False+ )+++# `create_all` builds the schema for tests; the trigger has to come with it or+# the delivery tests would exercise a table that announces nothing. Real+# databases get the same DDL from a migration.+event.listen(+ Message.__table__,+ "after_create",+ DDL(CREATE_NOTIFY_FUNCTION).execute_if(dialect="postgresql"),+)+event.listen(+ Message.__table__,+ "after_create",+ DDL(CREATE_NOTIFY_TRIGGER).execute_if(dialect="postgresql"),+)+event.listen(+ Message.__table__,+ "before_drop",+ DDL(DROP_NOTIFY_TRIGGER).execute_if(dialect="postgresql"),+)diff --git a/core/switch_core/db/notify_ddl.py b/core/switch_core/db/notify_ddl.pynew file mode 100644index 000000000..268efba32--- /dev/null+++ b/core/switch_core/db/notify_ddl.py@@ -0,0 +1,72 @@+"""The database side of message delivery: a trigger that announces new rows.++Delivery used to be the message bus pushing an event at a long-lived sync+connection. It becomes the table announcing its own inserts, and a listener+reading the rows back.++**The notification is a hint, never the payload.** It carries a room, a+position and a row id, and a consumer reads the row itself. That is what makes+a lost notification cost latency instead of data: a consumer that keeps a+position can always ask what it has not seen, and one that never hears+anything is behind rather than wrong. Putting the message in the payload would+make the queue authoritative, and Postgres's notification queue is neither+durable nor replayable.++**It is a trigger rather than a call in the writer** so that it cannot be+forgotten. Anything that inserts a row — the recorder today, a backfill+tomorrow, a human with psql — announces it, and the announcement commits with+the row or not at all. `NOTIFY` is only delivered on commit, so a listener+never learns about a row it could not then read.++One channel carries every room, and listeners filter. A channel per room would+save wakeups, but each one needs a `LISTEN` issued before the first row it+should catch, which is a race the consumer has to close by reading the table+anyway — so the correctness machinery is identical and the subscription churn+is pure cost. See `switch_core/messages/notify.py` for the in-process fan-out+that replaces it.++The migration that installs this on a real database carries its own verbatim+copy: a migration is frozen at the moment it was written and must not change+meaning because this file did. The copy here is what `create_all` builds, so+tests exercise the same trigger the server runs.+"""++from __future__ import annotations++# Deliberately not per-room. See the module docstring.+MESSAGE_CHANNEL = "switch_message"++NOTIFY_FUNCTION_NAME = "switch_notify_message"+NOTIFY_TRIGGER_NAME = "messages_notify"++CREATE_NOTIFY_FUNCTION = f"""+CREATE OR REPLACE FUNCTION {NOTIFY_FUNCTION_NAME}() RETURNS trigger AS $$+BEGIN+ -- Reconstructed history is numbered below zero and is not news. A backfill+ -- inserts thousands of rows nobody is waiting for, and announcing them+ -- would wake every subscriber in the room to read nothing, because their+ -- cursors are above these positions by construction.+ IF NEW.seq <= 0 THEN+ RETURN NULL;+ END IF;+ PERFORM pg_notify(+ '{MESSAGE_CHANNEL}',+ json_build_object(+ 'room_id', NEW.room_id,+ 'seq', NEW.seq,+ 'id', NEW.id+ )::text+ );+ RETURN NULL;+END;+$$ LANGUAGE plpgsql+"""++CREATE_NOTIFY_TRIGGER = f"""+CREATE TRIGGER {NOTIFY_TRIGGER_NAME}+ AFTER INSERT ON messages+ FOR EACH ROW EXECUTE FUNCTION {NOTIFY_FUNCTION_NAME}()+"""++DROP_NOTIFY_TRIGGER = f"DROP TRIGGER IF EXISTS {NOTIFY_TRIGGER_NAME} ON messages"+DROP_NOTIFY_FUNCTION = f"DROP FUNCTION IF EXISTS {NOTIFY_FUNCTION_NAME}()"diff --git a/core/switch_core/db/stores/__init__.py b/core/switch_core/db/stores/__init__.pyindex 7d23337ff..ede68f314 100644--- a/core/switch_core/db/stores/__init__.py+++ b/core/switch_core/db/stores/__init__.py@@ -5,6 +5,7 @@ from switch_core.db.stores.client_store import ClientStorefrom switch_core.db.stores.collaboration_bridge_store import CollaborationBridgeStorefrom switch_core.db.stores.document_store import DocumentStorefrom switch_core.db.stores.external_user_store import ExternalUserStore+from switch_core.db.stores.message_store import MessageStorefrom switch_core.db.stores.reference_store import ReferenceStorefrom switch_core.db.stores.reference_type_store import ReferenceTypeStorefrom switch_core.db.stores.room_group_store import RoomGroupStore@@ -22,6 +23,7 @@ __all__ = ["CollaborationBridgeStore","DocumentStore","ExternalUserStore",+ "MessageStore","ReferenceStore","ReferenceTypeStore","RoomGroupStore",diff --git a/core/switch_core/db/stores/delivery_cursor_store.py b/core/switch_core/db/stores/delivery_cursor_store.pynew file mode 100644index 000000000..5506bb06e--- /dev/null+++ b/core/switch_core/db/stores/delivery_cursor_store.py@@ -0,0 +1,76 @@+"""Where each agent has been delivered to in each room."""++from __future__ import annotations++from typing import TYPE_CHECKING++from sqlalchemy import func, select+from sqlalchemy.dialects.postgresql import insert++from switch_core.db.models import DeliveryCursor++if TYPE_CHECKING:+ from collections.abc import Collection++ from sqlalchemy.ext.asyncio import AsyncSession+++class DeliveryCursorStore:+ async def position(self, session: AsyncSession, agent_id: str, room_id: str) -> int:+ """How far this agent has been delivered, 0 if it never has.++ Zero rather than None because `seq` starts at 1: an agent with no+ cursor is behind the room's first message, which is the same statement+ the number already makes.+ """+ result = await session.execute(+ select(DeliveryCursor.last_seq).where(+ DeliveryCursor.agent_id == agent_id,+ DeliveryCursor.room_id == room_id,+ )+ )+ return result.scalar_one_or_none() or 0++ async def positions_in(+ self, session: AsyncSession, room_id: str, agent_ids: Collection[str]+ ) -> dict[str, int]:+ """Several agents' positions in one room, for dispatching a room once.++ Agents with no cursor are absent from the map rather than present at 0,+ so a caller can tell "never delivered" from "delivered nothing".+ """+ if not agent_ids:+ return {}+ result = await session.execute(+ select(DeliveryCursor.agent_id, DeliveryCursor.last_seq).where(+ DeliveryCursor.room_id == room_id,+ DeliveryCursor.agent_id.in_(list(agent_ids)),+ )+ )+ return {agent_id: last_seq for agent_id, last_seq in result.all()}++ async def advance(+ self, session: AsyncSession, agent_id: str, room_id: str, seq: int+ ) -> None:+ """Move the cursor forward to `seq`, never backward.++ `GREATEST` rather than an assignment because two deliveries for the+ same agent can finish out of order — a retry after a slow read, two+ workers on the same room — and the later write must not undo the+ further one. Rewinding a cursor redelivers, and a redelivered message+ is indistinguishable from a new one to whoever reads it.+ """+ statement = insert(DeliveryCursor).values(+ agent_id=agent_id, room_id=room_id, last_seq=seq+ )+ await session.execute(+ statement.on_conflict_do_update(+ constraint="uq_delivery_cursors_agent_room",+ set_={+ "last_seq": func.greatest(+ DeliveryCursor.last_seq, statement.excluded.last_seq+ ),+ "updated_at": func.now(),+ },+ )+ )diff --git a/core/switch_core/db/stores/media_store.py b/core/switch_core/db/stores/media_store.pynew file mode 100644index 000000000..409d91d88--- /dev/null+++ b/core/switch_core/db/stores/media_store.py@@ -0,0 +1,15 @@+from sqlalchemy import select+from sqlalchemy.ext.asyncio import AsyncSession++from switch_core.db.models import MediaBlob+++class MediaStore:+ async def put(self, session: AsyncSession, blob: MediaBlob) -> MediaBlob:+ session.add(blob)+ await session.flush()+ return blob++ async def get(self, session: AsyncSession, uri: str) -> MediaBlob | None:+ result = await session.execute(select(MediaBlob).where(MediaBlob.uri == uri))+ return result.scalar_one_or_none()diff --git a/core/switch_core/db/stores/message_store.py b/core/switch_core/db/stores/message_store.pynew file mode 100644index 000000000..dbb21bdbf--- /dev/null+++ b/core/switch_core/db/stores/message_store.py@@ -0,0 +1,262 @@+from collections.abc import Collection+from datetime import UTC, datetime++from sqlalchemy import func, select, text+from sqlalchemy.ext.asyncio import AsyncSession++from switch_core.db.models import Message, MessageAttachment, Room+++class MessageStore:+ async def create(+ self,+ session: AsyncSession,+ message: Message,+ attachments: list[MessageAttachment],+ ) -> Message:+ """Persist a message and its files as one unit.++ Attachments are numbered by their order in the list, which is the order+ they were sent in.++ The caller must not have set `seq`; this assigns it.+ """+ message.seq = await self._next_seq(session, message.room_id)+ session.add(message)+ await session.flush()+ for position, attachment in enumerate(attachments):+ attachment.message_id = message.id+ attachment.position = position+ session.add(attachment)+ await session.flush()+ return message++ async def mark_history_backfilled(+ self, session: AsyncSession, room_id: str+ ) -> None:+ """Record that this room's history has been walked to its start.++ A write of the backfill's own progress, so it lives beside the writes+ of its output: a dry run replaces this store wholesale, and anything+ that reaches the database from outside it is a write a dry run does+ not know to withhold.+ """+ room = await session.get(Room, room_id)+ if room is None:+ return+ room.history_backfilled_at = datetime.now(UTC) # type: ignore[assignment]+ await session.flush()++ async def create_historical(+ self,+ session: AsyncSession,+ message: Message,+ attachments: list[MessageAttachment],+ ) -> Message:+ """Persist a message that predates recording, numbered below zero.++ Reconstructed history cannot take positions above the live log: `seq`+ orders the room, and giving a message from last month a number above+ one from this morning would put it at the top of every read. It cannot+ take positions among the live rows either — they are taken, and+ renumbering to make room would move every cursor that points at them.++ So it counts down from zero. Ordering by `seq` still walks the room in+ the order it happened, `(room_id, seq)` stays unique, and the sign+ carries a fact worth being able to read off a row: **positive is what+ Switch recorded as it happened, negative is what was reconstructed+ afterwards.**++ The sign is load-bearing for delivery, not just descriptive. A cursor+ starts at 0, so backfilling a year of history delivers none of it —+ which is the only sane answer, since nobody wants last March's+ messages pushed at them tonight.++ The caller must not have set `seq`; this assigns it. `sent_at` is the+ caller's to set, and must be when the message was *sent* rather than+ when this row was written, or the reconstructed history lands in the+ wrong place in every time window.+ """+ message.seq = await self._previous_seq(session, message.room_id)+ session.add(message)+ await session.flush()+ for position, attachment in enumerate(attachments):+ attachment.message_id = message.id+ attachment.position = position+ session.add(attachment)+ await session.flush()+ return message++ async def _previous_seq(self, session: AsyncSession, room_id: str) -> int:+ """The next position below the room's oldest, at most -1.++ Same lock as `_next_seq`, for the same reason and against the same+ contenders: two backfills of one room must not pick the same number,+ and the uniqueness constraint would otherwise be the thing that noticed.+ """+ await session.execute(+ text("SELECT pg_advisory_xact_lock(hashtext(:room_id))"),+ {"room_id": room_id},+ )+ result = await session.execute(+ select(func.coalesce(func.min(Message.seq), 0)).where(+ Message.room_id == room_id+ )+ )+ return min(int(result.scalar_one()), 0) - 1++ async def _next_seq(self, session: AsyncSession, room_id: str) -> int:+ """The next position in this room, allocated in commit order.++ A database sequence — `Identity`, `SERIAL`, `nextval` — is the obvious+ way to number rows and the wrong one here. It hands out a number when+ the INSERT runs, not when the transaction commits, and it does so+ outside transaction control so the number is never given back. Two+ concurrent senders therefore take 7 and 8, and if 8 commits first a+ reader paging on `seq > n` can advance its cursor past 8 while 7 is+ still in flight. When 7 lands it is behind the cursor and is never+ read again: a message that was delivered, recorded, and silently+ skipped. Rare, unreproducible, and invisible — the worst shape of bug+ this table could have.++ So the number is allocated under a lock held to commit. Writers to the+ same room serialise, which makes `seq` order and commit order the same+ order, which is the only property a cursor actually needs. The lock is+ an advisory one keyed on the room: it takes no row lock, so it cannot+ deadlock against anything that updates the room itself, and Postgres+ releases it at commit or rollback whatever happens. Two rooms whose+ ids collide in the hash serialise against each other needlessly and+ are otherwise unaffected.++ The cost is per-room serialisation of a single INSERT on a path that+ has already returned to the caller — the send completed before+ recording began. Rooms do not contend with each other.+ """+ await session.execute(+ text("SELECT pg_advisory_xact_lock(hashtext(:room_id))"),+ {"room_id": room_id},+ )+ result = await session.execute(+ select(func.coalesce(func.max(Message.seq), 0)).where(+ Message.room_id == room_id+ )+ )+ return int(result.scalar_one()) + 1++ async def head_seq(self, session: AsyncSession, room_id: str) -> int:+ """The room's current position, or 0 when nothing has been sent.++ What a subscriber starts from when it wants everything after now+ rather than everything. Reconstructed history is numbered below zero,+ so an empty live log answers 0 whatever has been backfilled into it.+ """+ result = await session.execute(+ select(func.coalesce(func.max(Message.seq), 0)).where(+ Message.room_id == room_id+ )+ )+ return max(int(result.scalar_one()), 0)++ async def get_by_transport_event_id(+ self, session: AsyncSession, transport_event_id: str+ ) -> Message | None:+ result = await session.execute(+ select(Message).where(Message.transport_event_id == transport_event_id)+ )+ return result.scalar_one_or_none()++ async def list_for_room(+ self, session: AsyncSession, room_id: str, *, after_seq: int, limit: int+ ) -> list[Message]:+ """Oldest first, from just after `after_seq`. Pass 0 to start.++ Paging on `seq` rather than a timestamp keeps the cursor exact: within+ a room it is a total order with no ties, and `create` assigns it in+ commit order, so no row can be skipped or repeated between pages.++ This is also what a delivery cursor reads: it must see the room in the+ order it happened, and must be able to stop part-way and resume from+ the last row it handled. `after_seq` is exclusive, so re-reading with+ the same cursor delivers nothing twice. Passing 0 also skips+ reconstructed history, which is numbered below zero — a backfill is+ not something to deliver.+ """+ result = await session.execute(+ select(Message)+ .where(Message.room_id == room_id, Message.seq > after_seq)+ .order_by(Message.seq)+ .limit(limit)+ )+ return list(result.scalars().all())++ async def list_timeline(+ self,+ session: AsyncSession,+ room_id: str,+ *,+ limit: int,+ since: datetime | None,+ before: datetime | None,+ ) -> list[Message]:+ """The newest `limit` rows in the window, newest first.++ The window is half-open: `since` is included, `before` is not. Ordering+ is by `seq` rather than `sent_at` — within a room `seq` is a total order+ with no ties, whereas two rows can share a timestamp — so a caller that+ asks for the newest N gets the same N every time.+ """+ query = select(Message).where(Message.room_id == room_id)+ if since is not None:+ query = query.where(Message.sent_at >= since)+ if before is not None:+ query = query.where(Message.sent_at < before)+ result = await session.execute(query.order_by(Message.seq.desc()).limit(limit))+ return list(result.scalars().all())++ async def list_by_transport_event_ids(+ self, session: AsyncSession, room_id: str, event_ids: Collection[str]+ ) -> list[Message]:+ """Rows for specific transport event ids within one room.++ Scoped to the room so an id from elsewhere cannot be read through it.+ """+ if not event_ids:+ return []+ result = await session.execute(+ select(Message).where(+ Message.room_id == room_id,+ Message.transport_event_id.in_(list(event_ids)),+ )+ )+ return list(result.scalars().all())++ async def attachments_for(+ self, session: AsyncSession, message_ids: Collection[str]+ ) -> dict[str, list[MessageAttachment]]:+ """Attachments for several messages at once, keyed by message id.++ One query for the whole page: fetching per message would put the N+1+ back that moving the read path here is meant to remove. Messages with+ no files are simply absent from the map.+ """+ if not message_ids:+ return {}+ result = await session.execute(+ select(MessageAttachment)+ .where(MessageAttachment.message_id.in_(list(message_ids)))+ .order_by(MessageAttachment.message_id, MessageAttachment.position)+ )+ by_message: dict[str, list[MessageAttachment]] = {}+ for attachment in result.scalars().all():+ by_message.setdefault(attachment.message_id, []).append(attachment)+ return by_message++ async def get_attachments(+ self, session: AsyncSession, message_id: str+ ) -> list[MessageAttachment]:+ result = await session.execute(+ select(MessageAttachment)+ .where(MessageAttachment.message_id == message_id)+ .order_by(MessageAttachment.position)+ )+ return list(result.scalars().all())diff --git a/core/switch_core/db/stores/room_store.py b/core/switch_core/db/stores/room_store.pyindex a0b45854b..49f441c4f 100644--- a/core/switch_core/db/stores/room_store.py+++ b/core/switch_core/db/stores/room_store.py@@ -2,6 +2,7 @@ from datetime import UTC, datetimefrom sqlalchemy import delete, insert, or_, select, updatefrom sqlalchemy import func as sa_func+from sqlalchemy.dialects.postgresql import insert as pg_insertfrom sqlalchemy.ext.asyncio import AsyncSessionfrom switch_core.db.models import (@@ -283,7 +284,28 @@ class RoomStore:async def add_client(self, session: AsyncSession, client_id: str, room_id: str) -> None:- session.add(ClientRoom(client_id=client_id, room_id=room_id))+ """Record a membership, tolerating one that is already there.++ Membership has more than one writer. Over Matrix it effectively had+ one: an invitation was accepted later, over sync, long after the+ inviting transaction had committed, so `room_service` was the only+ thing writing this table. On the Postgres transport the invitation is+ the join — synchronous and in-process — so the joining client writes+ the row and the inviting caller then writes it again.++ A plain insert made that second write an IntegrityError that rolled+ the caller's whole transaction back, leaving an agent a member of the+ room but not one of its agents: receiving messages while+ `!list-agents` reported nobody. The conflict is a correct outcome+ rather than a failure — the membership exists, which is what the+ caller asked for — and this also closes the check-then-insert race+ between two concurrent invitations.+ """+ await session.execute(+ pg_insert(ClientRoom)+ .values(client_id=client_id, room_id=room_id)+ .on_conflict_do_nothing(index_elements=["client_id", "room_id"])+ )await session.flush()async def remove_client(@@ -297,6 +319,20 @@ class RoomStore:)await session.flush()+ async def get_for_client(self, session: AsyncSession, client_id: str) -> list[Room]:+ """The rooms a client is a member of.++ The mirror of `get_client_ids`, and what a client asks for when it+ wants to know where it belongs — over Matrix that question went to the+ homeserver, which answered from the same memberships this table holds.+ """+ result = await session.execute(+ select(Room)+ .join(ClientRoom, ClientRoom.room_id == Room.id)+ .where(ClientRoom.client_id == client_id)+ )+ return list(result.scalars().all())+async def get_client_ids(self, session: AsyncSession, room_id: str) -> list[str]:result = await session.execute(select(ClientRoom.client_id).where(ClientRoom.room_id == room_id)diff --git a/core/switch_core/delivery/__init__.py b/core/switch_core/delivery/__init__.pynew file mode 100644index 000000000..83803f729--- /dev/null+++ b/core/switch_core/delivery/__init__.py@@ -0,0 +1,14 @@+"""Working out who a message is for, independently of how it arrived.++Everything here takes a message as data — a sender, a body, a content dict —+rather than a transport event, so the same rules apply whether the message came+off the bus or was read back out of the message log.+"""++from switch_core.delivery.addressing import (+ AddressingDecision,+ AddressingResolver,+ IncomingMessage,+)++__all__ = ["AddressingDecision", "AddressingResolver", "IncomingMessage"]diff --git a/core/switch_core/delivery/addressing.py b/core/switch_core/delivery/addressing.pynew file mode 100644index 000000000..279225f2e--- /dev/null+++ b/core/switch_core/delivery/addressing.py@@ -0,0 +1,360 @@+"""Whether a message addresses a given agent, and whether it is allowed to.++Two separate questions, deliberately kept apart:++- **Addressed** is about intent. Did this message ask this agent for something+ — by name, by the alias it goes under in this room, by a role it holds, or+ by being the only other party in a direct chat?+- **Permitted** is about authority. An agent may carry a scoped addressing+ policy saying who is allowed to ask it for things at all.++A message can be addressed and not permitted, and the caller demotes it to+ordinary room chatter when so. Nothing here sends anything; deciding is all it+does, and the refusal wording travels back with the decision so the caller does+not have to re-derive why.++This used to live on `AgentClient`, where every answer was reached through a+live Matrix client. It takes a message as data instead — a sender, a body, a+content dict — so the same rules decide for a message read out of the log as+for one that arrived on the bus. That equivalence is the point: two code paths+answering "is this for me?" differently would be a security bug waiting for a+rewrite to expose it.+"""++from __future__ import annotations++import logging+from dataclasses import dataclass, field+from typing import TYPE_CHECKING, NamedTuple++from switch_core.addressing import SenderKind, can_address, parse_policy+from switch_core.clients.admin_messages import ADMIN_MARKER+from switch_core.clients.mentions import mention_regex, strip_emphasis++if TYPE_CHECKING:+ from collections.abc import Callable++ from sqlalchemy.ext.asyncio import AsyncSession++ from switch_core.db.models import Agent+ from switch_core.db.stores.agent_store import AgentStore+ from switch_core.db.stores.client_store import ClientStore+ from switch_core.db.stores.external_user_store import ExternalUserStore+ from switch_core.db.stores.room_role_store import RoomRoleStore+ from switch_core.db.stores.room_store import RoomStore++logger = logging.getLogger(__name__)++# Posted (once, guarded by an auto-reply flag) when a sender tags an agent but+# the agent's scoped addressing policy does not permit that sender to address+# it there. The message is demoted to unaddressed room chatter; this reply is+# the sender's only feedback that the attempt was rejected.+ADDRESSING_DENIED_MESSAGE = (+ "You're not permitted to direct messages to me in this room — my operator "+ "has restricted who can address me here."+)+++# The same refusal, for the case worth telling apart: the agent answers only to+# its owner, and the sender's chat account is not linked to any Switch user, so+# it cannot be recognised as the owner even if it is. Without this the owner+# gets refused by their own agent with no idea why.+ADDRESSING_UNCLAIMED_MESSAGE = (+ "I only take instructions from my owner, and this chat account isn't "+ "linked to a Switch user yet — so I can't tell whether that's you. If it "+ "is, link this account to your Switch user in Switch Console and try again."+)+++@dataclass(frozen=True)+class IncomingMessage:+ """What addressing needs to know about a message, and nothing else.++ `formatted_body` is where a Matrix client puts a rendered mention pill,+ which is the one addressing signal that has no plain-text equivalent. It is+ absent on media events and on anything read back from the log that never+ had one, so it is never the only thing consulted.+ """++ sender: str+ body: str+ formatted_body: str | None = None+ content: dict = field(default_factory=dict)+++class AddressingDecision(NamedTuple):+ """Whether a sender may address an agent, and what to say if not."""++ allowed: bool+ refusal: str+++class SenderPrincipal(NamedTuple):+ """Who a sender turned out to be, in the terms a policy is written in.++ `user_ids` and `owner_user_id` are the two ways a symbolic subject+ resolves, and are mutually exclusive: a human has claimants, an agent has+ an owner.+ """++ kind: SenderKind+ id: str+ user_ids: list[str]+ owner_user_id: str | None+++class AddressingResolver:+ """Answers "is this for that agent, and may it be?" from stores alone."""++ def __init__(+ self,+ *,+ room_store: RoomStore,+ room_role_store: RoomRoleStore,+ client_store: ClientStore,+ agent_store: AgentStore,+ external_user_store: ExternalUserStore,+ live_agent_ids: Callable[[], set[str]],+ ) -> None:+ self._room_store = room_store+ self._room_role_store = room_role_store+ self._client_store = client_store+ self._agent_store = agent_store+ self._external_user_store = external_user_store+ # A callable rather than a set: a role only routes while its holder's+ # session is live, and that changes between one message and the next.+ self._live_agent_ids = live_agent_ids++ # ── Addressed ─────────────────────────────────────────────────────────────++ def addressed_without_lookup(+ self,+ *,+ agent: Agent,+ agent_matrix_id: str,+ channel_type: str | None,+ message: IncomingMessage,+ ) -> bool | None:+ """The addressing answer that needs no database read, or None when the+ room's aliases and role leases have to be consulted.++ Callers use it to decide whether to take a pool slot at all: most room+ chatter carries no `@` and is answered here, and a room fans every+ message out to all of its agent clients at once.+ """+ if ADMIN_MARKER in message.content:+ return False+ if channel_type == "direct":+ return True+ if self.mentions_name(+ agent=agent, agent_matrix_id=agent_matrix_id, message=message+ ):+ return True+ if "@" not in message.body:+ return False+ return None++ async def addresses(+ self,+ session: AsyncSession,+ *,+ agent: Agent,+ agent_matrix_id: str,+ room_id: str,+ channel_type: str | None,+ message: IncomingMessage,+ ) -> bool:+ """Whether this message asks this agent for something.++ **A system message never addresses anyone**, whatever the room type.+ Switch's own notices — a command's answer, "Added X to this room", the+ guidance shown when someone tags the app itself — are output, not a+ request for a reply. Two ways they were read as one: in a direct room+ every message addresses the agent, so running `/list-agents` in a 1:1+ chat had the agent start a session to respond to its own roster; and in+ any room, a notice that lists the agents present writes each `@name`,+ which tagged every one of them. The marker exists to say "generated by+ Switch"; this is it being honoured.+ """+ decided = self.addressed_without_lookup(+ agent=agent,+ agent_matrix_id=agent_matrix_id,+ channel_type=channel_type,+ message=message,+ )+ if decided is not None:+ return decided+ if await self.mentions_alias(+ session, agent=agent, room_id=room_id, message=message+ ):+ return True+ return await self.mentions_role(+ session, agent=agent, room_id=room_id, message=message+ )++ def mentions_name(+ self, *, agent: Agent, agent_matrix_id: str, message: IncomingMessage+ ) -> bool:+ """An `@name` at a token boundary, or a rendered mention pill.++ The pill is checked first because it is unambiguous. The plain-text+ scan is what catches everything else — media captions carry no+ formatted body, and neither does a bridged message.+ """+ if message.formatted_body and agent_matrix_id in message.formatted_body:+ return True+ return (+ mention_regex(agent.name).search(strip_emphasis(message.body)) is not None+ )++ async def mentions_alias(+ self,+ session: AsyncSession,+ *,+ agent: Agent,+ room_id: str,+ message: IncomingMessage,+ ) -> bool:+ """An `@alias` for the name this agent goes under in this room.++ A room alias addresses the agent exactly like its real name. Looked up+ live, so a change takes effect on the next message with no per-client+ cache to invalidate.+ """+ if "@" not in message.body:+ return False+ alias = await self._room_store.get_alias(session, room_id, agent.id)+ if not alias:+ return False+ return mention_regex(alias).search(message.body) is not None++ async def mentions_role(+ self,+ session: AsyncSession,+ *,+ agent: Agent,+ room_id: str,+ message: IncomingMessage,+ ) -> bool:+ """An `@role` for a room-role this agent LIVE-holds.++ Tagging a role reaches whoever is doing that job, so an interchangeable+ agent can be addressed by responsibility rather than by name. Only a+ live lease counts, which makes "held" mean the same thing here as in+ `!roles`: a stale lease — session gone, role auto-released, shown free+ — does not route here. A holder whose session merely hopped to another+ room still matches, because the renewal loop keeps that lease alive.+ """+ if "@" not in message.body:+ return False+ role_name = await self._room_role_store.agent_room_role(+ session, room_id, agent.id, self._live_agent_ids()+ )+ if not role_name:+ return False+ return mention_regex(role_name).search(strip_emphasis(message.body)) is not None++ # ── Permitted ─────────────────────────────────────────────────────────────++ async def permitted(+ self, session: AsyncSession, *, agent: Agent, room_id: str, sender: str+ ) -> AddressingDecision:+ """Whether `sender` may address this agent in this room.++ An agent with no policy is open to anyone, so this answers without a+ database round-trip. With a policy set it is deny-by-default: a sender+ that resolves to nothing is refused rather than given the benefit of+ the doubt, because an identity nobody can name is exactly what a+ restricted agent is restricted against.+ """+ policy = parse_policy(agent.addressing_policy)+ if policy.is_open():+ return AddressingDecision(allowed=True, refusal="")++ principal = await self.resolve_sender(session, sender)+ room = await self._room_store.get(session, room_id)++ if principal is None:+ logger.warning(+ "Addressing denied for %s: unresolvable sender %s in room %s",+ agent.name,+ sender,+ room_id,+ )+ return AddressingDecision(allowed=False, refusal=ADDRESSING_DENIED_MESSAGE)++ allowed = can_address(+ policy,+ room_id=room_id,+ group_id=room.group_id if room is not None else None,+ sender_kind=principal.kind,+ sender_id=principal.id,+ sender_user_ids=principal.user_ids,+ sender_owner_user_id=principal.owner_user_id,+ owner_user_id=agent.owner_id,+ )+ if allowed:+ return AddressingDecision(allowed=True, refusal="")++ # An owner-scoped rule cannot match a human nobody has claimed, so the+ # refusal says what to fix rather than implying a decision was made.+ unclaimed = (+ principal.kind == "user"+ and not principal.user_ids+ and policy.requires_owner_identity()+ )+ if unclaimed:+ logger.warning(+ "Addressing denied for %s: sender %s in room %s has not been "+ "claimed by any Switch user, so an owner-scoped rule cannot "+ "match them — the owner may need to link this identity",+ agent.name,+ principal.id,+ room_id,+ )+ else:+ logger.warning(+ "Addressing denied for %s: %s %s not permitted in room %s",+ agent.name,+ principal.kind,+ principal.id,+ room_id,+ )+ return AddressingDecision(+ allowed=False,+ refusal=(+ ADDRESSING_UNCLAIMED_MESSAGE if unclaimed else ADDRESSING_DENIED_MESSAGE+ ),+ )++ async def resolve_sender(+ self, session: AsyncSession, matrix_user_id: str+ ) -> SenderPrincipal | None:+ """Map a sender's mxid to the principal a policy is written about.++ Every participant is a Switch client, so the mxid resolves to a Client+ and from there to either an Agent (an agent-to-agent attempt) or an+ ExternalUser (a human on a bridge). None means neither, which a+ restricted agent should not trust.++ The two symbolic subjects come from different fields and only one+ applies to any sender: `user_ids` are the Switch users who have claimed+ a human's platform account — empty for an agent, which is never its own+ owner — and `owner_user_id` is who owns an agent sender, None for a+ human.+ """+ client = await self._client_store.get_by_matrix_user_id(session, matrix_user_id)+ if client is None:+ return None+ agent = await self._agent_store.get_by_client_id(session, client.id)+ if agent is not None:+ return SenderPrincipal("agent", agent.id, [], agent.owner_id)+ external_user = await self._external_user_store.get_by_client_id(+ session, client.id+ )+ if external_user is not None:+ claimants = await self._external_user_store.claimant_ids(+ session, external_user.id+ )+ return SenderPrincipal("user", external_user.id, claimants, None)+ return Nonediff --git a/core/switch_core/events.py b/core/switch_core/events.pyindex dcd46ac9d..b5fa1835f 100644--- a/core/switch_core/events.py+++ b/core/switch_core/events.py@@ -3,11 +3,6 @@ from __future__ import annotationsfrom pydantic import BaseModel, ConfigDict-class MediationResult(BaseModel):- verdict: str- reason: str | None = None--class SwitchEvent(BaseModel):model_config = ConfigDict(extra="allow")@@ -30,48 +25,6 @@ class CommandEvent(SwitchEvent):thread_id: str | None = None-# ── Mediation (pre-invocation) ────────────────────────────────────────────────---class MediationToolRequest(SwitchEvent):- request_id: str- agent_id: str- tool_id: str- args: dict[str, object]- task_id: str | None = None- status: str---class MediationLlmRequest(SwitchEvent):- request_id: str- agent_id: str- model_id: str- messages: list[dict[str, object]]- task_id: str | None = None- status: str---# ── Mediation (post-invocation) ───────────────────────────────────────────────---class MediationToolResult(SwitchEvent):- request_id: str- agent_id: str- tool_id: str- result: object- task_id: str | None = None- status: str---class MediationLlmResponse(SwitchEvent):- request_id: str- agent_id: str- model_id: str- response: object- task_id: str | None = None- status: str--# ── Event reporting ───────────────────────────────────────────────────────────@@ -164,19 +117,3 @@ class AgentRuntimeStateEvent(SwitchEvent):# the agent really has. Unchanged between reports (e.g. the periodic# activity refresh) means the indicator stays where it is.anchor_event_id: str | None = None---# ── Permission ────────────────────────────────────────────────────────────────---class PermissionRequest(SwitchEvent):- request_id: str- agent_id: str- action: str- details: dict[str, object] | None = None---class PermissionResponse(SwitchEvent):- request_id: str- approved: bool- responder_id: strdiff --git a/core/switch_core/main.py b/core/switch_core/main.pyindex 5da5e89a7..0f07aaa7a 100644--- a/core/switch_core/main.py+++ b/core/switch_core/main.py@@ -22,7 +22,6 @@ from switch_core.bridges.agent.protocol.connections import ()from switch_core.bridges.agent.protocol.event_buffer import EventBufferfrom switch_core.bridges.agent.protocol.service import ProtocolService-from switch_core.bridges.agent.request_tracker import RequestTrackerfrom switch_core.bridges.agent.server_connectors.lifecycle import (ServerSideConnectorLifecycleService,)@@ -54,16 +53,18 @@ from switch_core.bridges.collaboration.telegram.adapter import (TelegramConnectionConfig,)from switch_core.bridges.resource.service import ResourceService-from switch_core.bridges.resource.tracker import ResourceRequestTrackerfrom switch_core.clients.admin_client import AdminClientfrom switch_core.clients.agent_client import AgentClientfrom switch_core.clients.client_base import ClientBasefrom switch_core.clients.client_factory import ClientFactoryfrom switch_core.clients.client_lifecycle_service import ClientLifecycleService-from switch_core.clients.resource_manager_client import ResourceManagerClientfrom switch_core.config import SwitchConfigfrom switch_core.crypto import encrypt_token-from switch_core.db.engine import create_engine_from_config, create_session_factory+from switch_core.db.engine import (+ create_engine_from_config,+ create_session_factory,+ create_unpooled_engine,+)from switch_core.db.models import ApiKey, Userfrom switch_core.db.stores.agent_session_store import AgentSessionStorefrom switch_core.db.stores.agent_store import AgentStore@@ -73,6 +74,8 @@ from switch_core.db.stores.client_store import ClientStorefrom switch_core.db.stores.collaboration_bridge_store import CollaborationBridgeStorefrom switch_core.db.stores.document_store import DocumentStorefrom switch_core.db.stores.external_user_store import ExternalUserStore+from switch_core.db.stores.media_store import MediaStore+from switch_core.db.stores.message_store import MessageStorefrom switch_core.db.stores.package_store import PackageStorefrom switch_core.db.stores.reference_store import ReferenceStorefrom switch_core.db.stores.reference_type_store import ReferenceTypeStore@@ -90,7 +93,13 @@ from switch_core.matrix_admin import (ensure_admin_exists,wait_for_homeserver,)+from switch_core.messages import MessageRecorder+from switch_core.messages.notify import MessageListener+from switch_core.provisioning import Provisioning+from switch_core.provisioning.postgres import PostgresProvisioningfrom switch_core.room_service import RoomService+from switch_core.transport.ephemeral import EphemeralBus+from switch_core.transport.invites import InviteBusfrom switch_core.version import switch_core_versionlogger = logging.getLogger(__name__)@@ -176,21 +185,15 @@ async def run() -> None:# ── Database ─────────────────────────────────────────────────────────────engine = create_engine_from_config(config)session_factory = create_session_factory(engine)+ # Its connection is held rather than borrowed, so it builds its own outside+ # the pool. Nothing subscribes yet; it starts with the server so that the+ # subscription exists before the first consumer needs it.+ message_listener = MessageListener(lambda: create_unpooled_engine(config))- # ── Matrix homeserver admin ──────────────────────────────────────────────- await wait_for_homeserver(config.matrix_server)- await ensure_admin_exists(- server_url=config.matrix_server,- username=config.matrix_admin_user,- password=config.matrix_admin_password,- shared_secret=config.matrix_registration_shared_secret,- )- matrix_admin = await MatrixAdmin.create(- server_url=config.matrix_server,- admin_user=config.matrix_admin_user,- admin_password=config.matrix_admin_password,- shared_secret=config.matrix_registration_shared_secret,- )+ # Invitations for the Postgres transport, which has no durable one of its+ # own. Built unconditionally: it is a dict until something registers.+ invites = InviteBus()+ ephemeral = EphemeralBus()# ── Stores ───────────────────────────────────────────────────────────────agent_store = AgentStore()@@ -210,6 +213,13 @@ async def run() -> None:room_link_store = RoomLinkStore()room_group_store = RoomGroupStore()room_role_store = RoomRoleStore()+ message_store = MessageStore()+ media_store = MediaStore()+ message_recorder = MessageRecorder(+ session_factory=session_factory,+ room_store=room_store,+ message_store=message_store,+ )# ── Seed admin user + registration key ──────────────────────────────────await _seed_admin_user(session_factory, user_store, config)@@ -219,8 +229,6 @@ async def run() -> None:# ── Event queue + request trackers ───────────────────────────────────────event_buffer = EventBuffer()- request_tracker = RequestTracker()- resource_request_tracker = ResourceRequestTracker()connector_store = ServerConnectorStore()# ── Resource service ─────────────────────────────────────────────────────@@ -235,6 +243,38 @@ async def run() -> None:async with session_factory() as session:await resource_service.log_builtin_shadowing(session)+ # ── Provisioning ─────────────────────────────────────────────────────────+ # The homeserver is only contacted when it is the transport. Reaching it+ # unconditionally would keep a Postgres deployment waiting on, and failing+ # to start without, a service it does not use.+ matrix_admin: Provisioning+ if config.message_transport == "matrix":+ await wait_for_homeserver(config.matrix_server)+ await ensure_admin_exists(+ server_url=config.matrix_server,+ username=config.matrix_admin_user,+ password=config.matrix_admin_password,+ shared_secret=config.matrix_registration_shared_secret,+ )+ matrix_admin = await MatrixAdmin.create(+ server_url=config.matrix_server,+ admin_user=config.matrix_admin_user,+ admin_password=config.matrix_admin_password,+ shared_secret=config.matrix_registration_shared_secret,+ )+ else:+ logger.warning(+ "Running on the Postgres transport: no homeserver is contacted, "+ "and media uploaded before the switch cannot be served"+ )+ matrix_admin = PostgresProvisioning(+ session_factory=session_factory,+ room_store=room_store,+ client_store=client_store,+ message_store=message_store,+ invites=invites,+ )+# One connection registry for the process. Created here rather than inside# the agent bridge because the Matrix agent clients are wired first and read# presence from it — an agent is reachable if it has a live connection OR a@@ -246,6 +286,13 @@ async def run() -> None:client_store=client_store,session_factory=session_factory,config=config,+ message_recorder=message_recorder,+ room_store=room_store,+ message_store=message_store,+ media_store=media_store,+ listener=message_listener,+ invites=invites,+ ephemeral=ephemeral,)client_factory.register("agent",@@ -259,19 +306,9 @@ async def run() -> None:agent_session_store=agent_session_store,room_role_store=room_role_store,external_user_store=external_user_store,- request_tracker=request_tracker,- resource_request_tracker=resource_request_tracker,connections=connections,frontend_base_url=config.frontend_base_url,)- client_factory.register(- "resource_manager",- ResourceManagerClient,- agent_store=agent_store,- room_store=room_store,- resource_service=resource_service,- request_tracker=request_tracker,- )client_factory.register("user", ClientBase)client_factory.register("bridge", ClientBase)@@ -297,6 +334,7 @@ async def run() -> None:matrix_admin=matrix_admin,session_factory=session_factory,config=config,+ client_factory=client_factory,)# ── Room service ─────────────────────────────────────────────────────────@@ -339,8 +377,6 @@ async def run() -> None:collab_lifecycle=collab_lifecycle,event_buffer=event_buffer,task_store=task_store,- request_tracker=request_tracker,- resource_request_tracker=resource_request_tracker,resource_service=resource_service,api_key_store=api_key_store,external_user_store=external_user_store,@@ -403,7 +439,6 @@ async def run() -> None:agent_bridge_app.mount("/gateway", gateway_app)# ── Ensure system clients exist ─────────────────────────────────────────- await client_lifecycle.ensure_system_client("resource_manager")await client_lifecycle.ensure_system_client("admin")# ── Lifespan: start server-side connectors once HTTP is serving ────────@@ -417,11 +452,13 @@ async def run() -> None:connection_sweep_task = asyncio.create_task(_connection_sweep_loop(protocol))+ await message_listener.start()try:yieldfinally:sweep_task.cancel()connection_sweep_task.cancel()+ await message_listener.stop()agent_bridge_app.router.lifespan_context = lifespan # type: ignore[assignment]@@ -529,7 +566,7 @@ async def _shutdown(client_lifecycle: ClientLifecycleService,collab_lifecycle: CollaborationBridgeLifecycleService,connector_lifecycle: ServerSideConnectorLifecycleService,- matrix_admin: MatrixAdmin,+ matrix_admin: Provisioning,) -> None:logger.info("Shutting down...")server.should_exit = Truediff --git a/core/switch_core/messages/__init__.py b/core/switch_core/messages/__init__.pynew file mode 100644index 000000000..31b8b41b1--- /dev/null+++ b/core/switch_core/messages/__init__.py@@ -0,0 +1,19 @@+from switch_core.messages.backfill import BackfillReport, backfill_room+from switch_core.messages.reconcile import (+ Mismatch,+ RoomReconciliation,+ reconcile_room,+)+from switch_core.messages.recorded_types import NOT_RECORDED, should_record+from switch_core.messages.recorder import MessageRecorder++__all__ = [+ "NOT_RECORDED",+ "BackfillReport",+ "MessageRecorder",+ "Mismatch",+ "RoomReconciliation",+ "backfill_room",+ "reconcile_room",+ "should_record",+]diff --git a/core/switch_core/messages/backfill.py b/core/switch_core/messages/backfill.pynew file mode 100644index 000000000..d401756c0--- /dev/null+++ b/core/switch_core/messages/backfill.py@@ -0,0 +1,286 @@+"""Reconstructs a room's history from the bus into the message log.++Recording began when the recorder was deployed. Everything a room said before+that is on the message bus and nowhere else — which did not matter while the+read path went to the bus too, and matters a great deal now that it does not.+On the first deployment to record and then read, that was 731 of 739 bridged+messages: still on the homeserver, invisible to every agent.++This walks a room backwards and writes the messages it finds that have no row.++**Reconstructed rows are numbered below zero.** `seq` orders the room, so a+message from last month cannot take a number above one from this morning, and+it cannot take a number among the live rows either — those are taken, and+renumbering to make room would move every cursor pointing at them. Counting+down from zero keeps the order right, keeps `(room_id, seq)` unique, and makes+the sign say something worth being able to read off a row: positive was+recorded as it happened, negative was reconstructed afterwards. Delivery+cursors start at 0, so none of this is pushed at anybody.++**It is idempotent, and that is not incidental.** A backfill over a busy room+is long, and the useful thing to do with a walk that failed halfway is to run+it again. `transport_event_id` is unique, so every row this would write is+either absent or already correct; the walk checks before writing and the+constraint is the backstop.++**What it does not reconstruct.** Only what the log is scoped to keep — see+`recorded_types` — so bus traffic that was never part of the conversation+stays out, exactly as it does going forward. Arrivals are reconstructed:+membership is on the bus and the timeline reads wrong without them. Sender+display names come from the event where the bus carried one and are otherwise+null, which is what the read path already tolerates.+"""++from __future__ import annotations++import logging+from dataclasses import dataclass, field+from datetime import UTC, datetime+from typing import TYPE_CHECKING++from switch_core.db.models import Message, MessageAttachment+from switch_core.db.stores.message_store import MessageStore+from switch_core.messages.recorded_types import MEMBERSHIP_EVENT_TYPE, should_record+from switch_core.transport import (+ InboundCustomEvent,+ InboundEvent,+ InboundMedia,+ InboundMembership,+ InboundMessage,+)++if TYPE_CHECKING:+ from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker++ from switch_core.db.models import Room+ from switch_core.transport import MessageTransport++logger = logging.getLogger(__name__)++# One page of backwards history, matching the reconciliation walk so a backfill+# puts no unusual shape of load on the homeserver.+PAGE_SIZE = 100++# A stop for a walk that would otherwise never end. Reached only if the+# homeserver keeps handing out pages with a cursor that advances forever; a+# room that ends returns no next token and stops on its own.+MAX_PAGES = 10_000+++@dataclass+class BackfillReport:+ room_id: str+ matrix_room_id: str+ room_name: str+ pages_read: int = 0+ seen: int = 0+ written: int = 0+ already_present: int = 0+ skipped_by_type: dict[str, int] = field(default_factory=dict)+ # True when the walk stopped because it ran out of pages rather than+ # because the room ended. The room is then partially reconstructed, and+ # saying so matters more than the count does.+ incomplete: bool = False++ def summary(self) -> str:+ line = (+ f"{self.room_name} ({self.matrix_room_id}): {self.written} written, "+ f"{self.already_present} already recorded, {self.seen} seen "+ f"over {self.pages_read} pages"+ )+ if self.skipped_by_type:+ counts = ", ".join(+ f"{name}={count}"+ for name, count in sorted(self.skipped_by_type.items())+ )+ line += f"; not part of the log: {counts}"+ if self.incomplete:+ line += "; INCOMPLETE — hit the page limit before the room ended"+ return line+++async def _mark_backfilled(+ session_factory: async_sessionmaker[AsyncSession],+ room: Room,+ store: MessageStore,+) -> None:+ """Record that this room has been walked to its start.++ Through the store, so a dry run withholds it along with everything else it+ withholds. Marking a room that a dry run only pretended to write would+ leave the real run with nothing to do and no way to say so.++ Only on a clean finish, too. A walk that stopped at the page limit leaves+ the room partly reconstructed, and calling that done would strand the rest+ of its history the next time round.+ """+ async with session_factory() as session:+ await store.mark_history_backfilled(session, room.id)+ await session.commit()+++async def backfill_room(+ transport: MessageTransport,+ session_factory: async_sessionmaker[AsyncSession],+ room: Room,+ *,+ store: MessageStore,+) -> BackfillReport:+ """Walk one room to its start, writing every message with no row.++ The transport must already be connected and a member of the room.++ Each page is its own transaction. A walk that fails partway therefore+ leaves the pages it finished written rather than rolling back an hour of+ work, and re-running picks up where it stopped — which is the behaviour+ that makes a long backfill practical rather than something to be afraid of.+ """+ report = BackfillReport(+ room_id=room.id,+ matrix_room_id=room.matrix_room_id,+ room_name=room.name,+ )+ start: str | None = None+ while report.pages_read < MAX_PAGES:+ page = await transport.read_history(+ room.matrix_room_id, start=start, limit=PAGE_SIZE+ )+ report.pages_read += 1++ # Newest first, which is how history comes back, and the direction the+ # numbering has to run: each row written takes the next position below+ # the last, so walking from the newest unrecorded message towards the+ # room's start leaves the oldest message with the lowest number. Any+ # other order would number the room backwards.+ for raw in page.events:+ await _consider(raw, session_factory, room, store, report)++ end = page.next_token+ if not end or end == start:+ await _mark_backfilled(session_factory, room, store)+ return report+ start = end++ report.incomplete = True+ logger.warning(+ "Backfill of %s stopped at the %d page limit; the room is only "+ "partially reconstructed",+ room.matrix_room_id,+ MAX_PAGES,+ )+ return report+++async def _consider(+ raw: object,+ session_factory: async_sessionmaker[AsyncSession],+ room: Room,+ store: MessageStore,+ report: BackfillReport,+) -> None:+ """Write one bus event as a message row, if it belongs in the log."""+ if not isinstance(raw, InboundEvent):+ report.skipped_by_type["unrecognised"] = (+ report.skipped_by_type.get("unrecognised", 0) + 1+ )+ return++ event_type = _event_type(raw)+ if event_type is None or not should_record(event_type):+ name = event_type or type(raw).__name__+ report.skipped_by_type[name] = report.skipped_by_type.get(name, 0) + 1+ return++ report.seen += 1+ async with session_factory() as session:+ existing = await store.get_by_transport_event_id(session, raw.event_id)+ if existing is not None:+ report.already_present += 1+ return+ message, attachments = _row_for(raw, room.id, event_type)+ await store.create_historical(session, message, attachments)+ await session.commit()+ report.written += 1+++def _event_type(raw: InboundEvent) -> str | None:+ """The log's name for this event, or None if it has no place in the log."""+ if isinstance(raw, InboundMembership):+ # Only an arrival. A leave is not part of the timeline the log keeps,+ # and recording one would put a row in history with nothing to say.+ return MEMBERSHIP_EVENT_TYPE if raw.membership == "join" else None+ if isinstance(raw, InboundCustomEvent):+ return raw.event_type+ if isinstance(raw, InboundMessage):+ return "m.room.message"+ return None+++def _row_for(+ raw: InboundEvent, room_id: str, event_type: str+) -> tuple[Message, list[MessageAttachment]]:+ """Build the row and its files from a bus event.++ `sender_client_id` is left null. It is the Switch client that did the+ sending, and the bus records an mxid rather than a client id; resolving it+ would be a lookup per row for a column nothing reads. `sender_name` comes+ from the event where the bus carried one.+ """+ content = dict(raw.content)+ message = Message(+ room_id=room_id,+ transport_event_id=raw.event_id,+ sender_matrix_id=raw.sender,+ sender_client_id=None,+ sender_name=_sender_name(raw, content),+ event_type=event_type,+ msgtype=getattr(raw, "msgtype", None),+ body=_body(raw),+ formatted_body=content.get("formatted_body"),+ thread_root_event_id=getattr(raw, "thread_root_id", None),+ content=content,+ sent_at=datetime.fromtimestamp(raw.timestamp / 1000, tz=UTC),+ )+ return message, _attachments(raw, content)+++def _sender_name(raw: InboundEvent, content: dict) -> str | None:+ if isinstance(raw, InboundMembership):+ return raw.display_name+ name = content.get("sender_name")+ return str(name) if name else None+++def _body(raw: InboundEvent) -> str | None:+ # An arrival carries no body: how it reads is the reader's to phrase, and+ # a rendered sentence in the log would freeze today's wording into every+ # row ever written. Matches what the live recorder does.+ if isinstance(raw, InboundMembership):+ return None+ return getattr(raw, "body", None)+++def _attachments(raw: InboundEvent, content: dict) -> list[MessageAttachment]:+ """The files on this event, which on the bus is at most one.++ Matrix has no multi-attachment event, so a send of several files is+ several events sharing a group key. Reconstructing them as one row would+ mean holding a page's worth of parts and guessing which belong together;+ they are written as they were sent instead, and the group key survives in+ `content` for anyone who wants to coalesce them later.+ """+ if not isinstance(raw, InboundMedia):+ return []+ info = content.get("info") or {}+ size = info.get("size") if isinstance(info, dict) else None+ return [+ MessageAttachment(+ uri=raw.uri,+ filename=content.get("filename") or raw.body,+ mimetype=info.get("mimetype") if isinstance(info, dict) else None,+ size=int(size) if isinstance(size, int) else None,+ )+ ]+++__all__ = ["BackfillReport", "backfill_room"]diff --git a/core/switch_core/messages/notify.py b/core/switch_core/messages/notify.pynew file mode 100644index 000000000..f72fd5a68--- /dev/null+++ b/core/switch_core/messages/notify.py@@ -0,0 +1,260 @@+"""Listens for new-message announcements and wakes whoever cares.++The database announces every insert into `messages` (see+`switch_core/db/notify_ddl.py`). This is the other half: one long-lived+connection holding a `LISTEN`, and an in-process fan-out to the consumers that+asked about a room.++**A wake-up is not a delivery.** A subscriber is told that a room has advanced+to at least some position, never what was said. It then reads the rows it has+not seen. Everything awkward about the notification queue — not durable, not+replayable, delivered at most once, and only to connections that happened to+be listening — stops mattering under that rule, because the worst a lost+announcement can do is delay a read that a later announcement will trigger+anyway.++Two consequences are load-bearing:++- **Announcements coalesce.** Only the highest position per room is kept while+ a subscriber is busy. Ten rows arriving during one handler run produce one+ wake-up, and the handler reads all ten, because the handler works from its+ own cursor rather than from what it was handed. That is also why there is no+ backpressure to apply and no queue to overflow.+- **Reconnecting wakes every room.** A dropped connection misses+ announcements outright, and nothing will ever replay them. So the listener+ treats a reconnect as "everything may have moved" and wakes all subscribers,+ which closes the gap without anyone having to detect it.++The connection is deliberately not taken from the application pool. It is held+for the process's life, never returns, and the pool's recycling and+`idle_in_transaction_session_timeout` would both be actively wrong for it.+"""++from __future__ import annotations++import asyncio+import contextlib+import json+import logging+from collections.abc import Awaitable, Callable+from dataclasses import dataclass+from typing import TYPE_CHECKING, Any++from switch_core.db.notify_ddl import MESSAGE_CHANNEL++if TYPE_CHECKING:+ from sqlalchemy.ext.asyncio import AsyncEngine++logger = logging.getLogger(__name__)++# How often the listening connection is proved still alive. A half-open socket+# reports nothing and delivers nothing, which is the failure this exists to+# catch: without it the process looks connected and silently stops receiving.+HEARTBEAT_SECONDS = 20.0++# Backoff for a listener that cannot connect. Capped low: the whole system's+# delivery latency is behind this, so a long sleep is a long outage.+RECONNECT_BACKOFF_BASE = 1.0+RECONNECT_BACKOFF_CAP = 15.0++RoomWaker = Callable[[str], Awaitable[None]]+EngineFactory = Callable[[], "AsyncEngine"]+++@dataclass(frozen=True)+class Announcement:+ """What the trigger said: a room moved, and how far.++ `seq` is a lower bound on where the room now is, not a row to fetch. By the+ time a subscriber runs there may be later rows, and after a coalesce there+ certainly are.+ """++ room_id: str+ seq: int+ message_id: str++ @staticmethod+ def parse(payload: str) -> Announcement | None:+ """Read one notification payload, or None if it is not one of ours.++ A payload that cannot be understood is dropped with a warning rather+ than raised: this runs inside the connection's read loop, and a bad+ message from somewhere else on the channel must not take delivery down+ for every room.+ """+ try:+ data = json.loads(payload)+ return Announcement(+ room_id=str(data["room_id"]),+ seq=int(data["seq"]),+ message_id=str(data["id"]),+ )+ except (ValueError, TypeError, KeyError):+ logger.warning(+ "Ignoring an unreadable message announcement: %r", payload[:200]+ )+ return None+++class MessageListener:+ """Holds the `LISTEN` and fans announcements out to room subscribers."""++ def __init__(self, engine_factory: EngineFactory) -> None:+ # A factory rather than an engine: reconnecting builds a fresh one, so+ # a connection that failed leaves nothing of itself behind.+ self._engine_factory = engine_factory+ self._subscribers: dict[str, set[RoomWaker]] = {}+ # Room → the highest position announced but not yet handed on. This is+ # the coalescing buffer; see the module docstring.+ self._pending: dict[str, int] = {}+ self._has_pending = asyncio.Event()+ self._tasks: list[asyncio.Task[None]] = []+ self._running = False+ # Set once the connection is up and every subscriber has been woken,+ # so a caller can wait for delivery to be live rather than guess.+ self.connected = asyncio.Event()++ # ── Subscription ──────────────────────────────────────────────────────────++ def subscribe(self, room_id: str, waker: RoomWaker) -> None:+ """Ask to be woken when `room_id` advances.++ The waker is called with the room id and nothing else, because what it+ should do about it is read the rows after its own cursor. It is woken+ once on subscribing too: a subscriber that starts mid-stream is behind+ by definition, and making it read immediately is cheaper than making+ every caller remember to.+ """+ self._subscribers.setdefault(room_id, set()).add(waker)+ self._mark(room_id, 0)++ def unsubscribe(self, room_id: str, waker: RoomWaker) -> None:+ wakers = self._subscribers.get(room_id)+ if wakers is None:+ return+ wakers.discard(waker)+ if not wakers:+ del self._subscribers[room_id]++ # ── Lifecycle ─────────────────────────────────────────────────────────────++ async def start(self) -> None:+ if self._running:+ raise RuntimeError("MessageListener is already started")+ self._running = True+ self._tasks = [+ asyncio.create_task(self._listen_forever(), name="message-listener"),+ asyncio.create_task(self._fan_out_forever(), name="message-fan-out"),+ ]++ async def stop(self) -> None:+ self._running = False+ for task in self._tasks:+ task.cancel()+ for task in self._tasks:+ with contextlib.suppress(asyncio.CancelledError):+ await task+ self._tasks = []+ self.connected.clear()++ # ── The listening connection ──────────────────────────────────────────────++ async def _listen_forever(self) -> None:+ attempt = 0+ while self._running:+ try:+ await self._listen_once()+ attempt = 0+ except asyncio.CancelledError:+ raise+ except Exception:+ attempt += 1+ delay = min(+ RECONNECT_BACKOFF_BASE * 2 ** (attempt - 1), RECONNECT_BACKOFF_CAP+ )+ logger.error(+ "Message listener lost its connection; retrying in %.1fs",+ delay,+ exc_info=True,+ )+ self.connected.clear()+ await asyncio.sleep(delay)++ async def _listen_once(self) -> None:+ engine = self._engine_factory()+ try:+ async with engine.connect() as connection:+ raw = await connection.get_raw_connection()+ driver = raw.driver_connection+ if driver is None:+ raise RuntimeError(+ "No driver connection behind the message listener; "+ "LISTEN needs asyncpg directly"+ )+ await driver.add_listener(MESSAGE_CHANNEL, self._on_notify)+ try:+ # Whatever happened while there was no connection was not+ # queued anywhere, so assume every room moved.+ self._wake_everything()+ self.connected.set()+ await self._hold_open(driver)+ finally:+ self.connected.clear()+ with contextlib.suppress(Exception):+ await driver.remove_listener(MESSAGE_CHANNEL, self._on_notify)+ finally:+ await engine.dispose()++ async def _hold_open(self, driver: Any) -> None:+ """Keep the connection until it fails, proving it alive as we go."""+ while self._running:+ await asyncio.sleep(HEARTBEAT_SECONDS)+ await driver.execute("SELECT 1")++ def _on_notify(+ self, _connection: Any, _pid: int, _channel: str, payload: str+ ) -> None:+ """asyncpg's callback. Runs in the connection's read loop.++ It does nothing but record a position, so a slow subscriber can never+ stall the connection that every other room's delivery depends on.+ """+ announcement = Announcement.parse(payload)+ if announcement is not None:+ self._mark(announcement.room_id, announcement.seq)++ # ── Fan-out ───────────────────────────────────────────────────────────────++ def _mark(self, room_id: str, seq: int) -> None:+ self._pending[room_id] = max(self._pending.get(room_id, 0), seq)+ self._has_pending.set()++ def _wake_everything(self) -> None:+ for room_id in self._subscribers:+ self._mark(room_id, 0)++ async def _fan_out_forever(self) -> None:+ while self._running:+ await self._has_pending.wait()+ self._has_pending.clear()+ rooms = list(self._pending)+ self._pending.clear()+ for room_id in rooms:+ await self._wake_room(room_id)++ async def _wake_room(self, room_id: str) -> None:+ for waker in list(self._subscribers.get(room_id, ())):+ try:+ await waker(room_id)+ except asyncio.CancelledError:+ raise+ except Exception:+ # One subscriber's failure is not the other subscribers' or the+ # other rooms' problem; this is the delivery loop, and it has to+ # survive whatever a handler does.+ logger.error(+ "A subscriber failed handling new messages in room %s",+ room_id,+ exc_info=True,+ )diff --git a/core/switch_core/messages/reconcile.py b/core/switch_core/messages/reconcile.pynew file mode 100644index 000000000..cf1af75f2--- /dev/null+++ b/core/switch_core/messages/reconcile.py@@ -0,0 +1,446 @@+"""Compares what the message bus holds for a room against what was recorded.++Recording happens after a send is accepted and cannot fail it, so a database+problem leaves a row missing for a message that really was delivered. That is+a deliberate trade, and this is how the cost of it is measured: before the+read path moves onto these rows, the two records have to be shown to agree on+a real room, not on fakes.++**Only the window where recording was active is compared.** Rows exist from+the moment the recorder was deployed; every message older than that is+legitimately absent, and reporting a room's entire back-catalogue as missing+would bury the one row that actually went astray. The window therefore starts+at the oldest recorded message unless the caller names an earlier point, and+every report says which window it covered.++**The window's floor is an event id, not a moment.** A row's `sent_at` is when+it was written, and writing happens after the send is accepted, so the bus+event for the very first recorded message is always a little older than the+row that describes it. A timestamp cutoff therefore excludes that event from+the bus side while including its row on the recorded side, and the oldest+message in every room reports as drift for as long as the room exists. Paging+back to the oldest row's own event id instead makes the boundary exact and+takes both clocks out of it. The timestamp survives only as a backstop, so a+room whose anchor event is gone from the bus terminates instead of walking to+the beginning of time — and says so rather than reporting the difference as+drift it cannot explain.++Events the bus replays that a send never produced — membership changes and+the like — are counted by type rather than dropped, so a category nobody+thought about shows up as unclassified instead of as agreement. Custom event+types the recorder deliberately does not keep are counted the same way, under+their own type name: they are absent by design, and calling that drift would+make the report worthless.++**Both sides apply that filter, not just the bus side.** A row of a type the+bus walk discards has nothing to be compared against, so measuring it against+an empty set reports it as recorded-but-never-sent every run, forever. Rows+for types written before they were denied are the case that remains; they are+counted under `unverifiable_by_type` — disclosed as outside the check rather+than quietly dropped from it.++**Arrivals are compared too**, from the point the log has one. Recording a+join is the newest write path there is, and leaving it out made the least+proven part of the system the one part nothing checked. Its window is its own:+every room was joined long before arrivals were recorded, so a join older than+the oldest recorded arrival cannot have a row and is counted rather than+reported. After that point a join without a row is drift like any other.+"""++from __future__ import annotations++from dataclasses import dataclass, field+from datetime import datetime, timedelta+from typing import TYPE_CHECKING, cast++from sqlalchemy import select++from switch_core.db.models import Message+from switch_core.messages.recorded_types import MEMBERSHIP_EVENT_TYPE, should_record+from switch_core.transport import (+ InboundCustomEvent,+ InboundEvent,+ InboundMedia,+ InboundMembership,+ InboundMessage,+)++if TYPE_CHECKING:+ from sqlalchemy.ext.asyncio import AsyncSession++ from switch_core.db.models import Room+ from switch_core.transport import MessageTransport++# One page of backwards history. Matches the size the read path already uses,+# so a reconciliation walk puts no unusual shape of load on the homeserver.+PAGE_SIZE = 100++# How far past the window the walk may go looking for the anchor event before+# giving up. Only reached when the anchor is not on the bus at all; generous+# because the cost of overshooting is a few extra pages, and the cost of+# stopping early is a report that cannot tell drift from a short walk.+ANCHOR_SEARCH_SLACK = timedelta(hours=1)+++@dataclass(frozen=True)+class Mismatch:+ """One field that disagrees between the bus and the recorded row."""++ event_id: str+ field_name: str+ on_the_bus: object+ recorded: object++ def describe(self) -> str:+ return (+ f"{self.event_id} {self.field_name}: "+ f"bus={self.on_the_bus!r} recorded={self.recorded!r}"+ )+++@dataclass(frozen=True)+class RoomReconciliation:+ room_id: str+ matrix_room_id: str+ room_name: str+ # The window compared. None means the room had no recorded messages at+ # all, so there was nothing to compare rather than nothing wrong.+ since: datetime | None+ compared: int = 0+ agreed: int = 0+ missing_rows: list[str] = field(default_factory=list)+ unsent_rows: list[str] = field(default_factory=list)+ mismatches: list[Mismatch] = field(default_factory=list)+ ignored_by_type: dict[str, int] = field(default_factory=dict)+ # Rows of a type the bus walk does not collect, so nothing could be+ # compared against them. Not drift, but not checked either.+ unverifiable_by_type: dict[str, int] = field(default_factory=dict)+ # Whether the walk reached the oldest recorded row's own event. False means+ # the boundary fell back to a timestamp, so the edge of the window is+ # approximate and a difference there may be an artefact of the walk.+ anchored: bool = True++ @property+ def compared_nothing(self) -> bool:+ return self.since is None++ @property+ def clean(self) -> bool:+ return not (self.missing_rows or self.unsent_rows or self.mismatches)++ def summary(self) -> str:+ where = f"{self.room_name} ({self.matrix_room_id})"+ if self.since is None:+ return f"{where}: no recorded messages, nothing to compare"+ verdict = "clean" if self.clean else "DRIFT"+ line = (+ f"{where}: {verdict} — {self.agreed}/{self.compared} agreed, "+ f"{len(self.missing_rows)} missing, {len(self.unsent_rows)} unsent, "+ f"{len(self.mismatches)} mismatched (since {self.since.isoformat()})"+ )+ if self.unverifiable_by_type:+ skipped = sum(self.unverifiable_by_type.values())+ line += f"; {skipped} rows not checkable against the bus"+ if not self.anchored:+ line += "; WINDOW UNANCHORED — oldest recorded event not found on the bus"+ return line+++async def reconcile_room(+ transport: MessageTransport,+ session: AsyncSession,+ room: Room,+ *,+ since: datetime | None = None,+) -> RoomReconciliation:+ """Compare one room. `since` overrides the recorded-from cutoff.++ The transport must already be connected and a member of the room.+ """+ anchor = await _oldest_recorded(session, room.id)+ # `Message.sent_at` is a timestamptz the models annotate as `str` — the+ # established convention across every model in this package.+ recorded_from = cast("datetime | None", anchor.sent_at) if anchor else None+ window_start = since or recorded_from+ if window_start is None:+ return RoomReconciliation(+ room_id=room.id,+ matrix_room_id=room.matrix_room_id,+ room_name=room.name,+ since=None,+ )++ # An explicit `since` is the caller overriding the boundary, so the anchor+ # only applies when the window is the recorded one.+ anchor_event_id = anchor.transport_event_id if anchor and since is None else None+ oldest_join = await _oldest_recorded_join(session, room.id)+ on_the_bus, ignored, anchored = await _read_back_to(+ transport,+ room.matrix_room_id,+ anchor_event_id=anchor_event_id,+ floor_ms=_to_ms(window_start - ANCHOR_SEARCH_SLACK),+ window_start_ms=_to_ms(window_start),+ joins_from_ms=_joins_from_ms(oldest_join),+ join_anchor_id=oldest_join.transport_event_id if oldest_join else None,+ )+ recorded = await _recorded_since(session, room.id, window_start)++ agreed = 0+ missing_rows: list[str] = []+ mismatches: list[Mismatch] = []+ for event_id, event in on_the_bus.items():+ row = recorded.get(event_id)+ if row is None:+ missing_rows.append(event_id)+ continue+ found = _compare(event_id, event, row)+ if found:+ mismatches.extend(found)+ else:+ agreed += 1++ unsent_rows: list[str] = []+ unverifiable: dict[str, int] = {}+ for event_id, row in recorded.items():+ if event_id in on_the_bus:+ continue+ if _comparable(row):+ unsent_rows.append(event_id)+ else:+ unverifiable[row.event_type] = unverifiable.get(row.event_type, 0) + 1++ return RoomReconciliation(+ room_id=room.id,+ matrix_room_id=room.matrix_room_id,+ room_name=room.name,+ since=window_start,+ compared=len(on_the_bus),+ agreed=agreed,+ missing_rows=missing_rows,+ unsent_rows=unsent_rows,+ mismatches=mismatches,+ ignored_by_type=ignored,+ unverifiable_by_type=unverifiable,+ anchored=anchored,+ )+++def _comparable(row: Message) -> bool:+ """Whether the bus walk would have collected this row's event.++ A row written before its type was denied has a bus event the walk now+ discards; measuring it against the collected set says "recorded, never+ sent" every single run.+ """+ return should_record(row.event_type)+++def _joins_from_ms(oldest_join: Message | None) -> int | None:+ """The point from which a bus arrival is expected to have a row.++ None means the log holds no arrival for this room, so every join on the+ bus predates the path that records them and none can be compared.++ The bound is the oldest recorded arrival's `sent_at`, which is fractionally+ later than its own bus event — so that one event is admitted by event id+ instead, the same way the window's anchor is.+ """+ if oldest_join is None:+ return None+ return _to_ms(cast("datetime", oldest_join.sent_at))+++def _to_ms(moment: datetime) -> int:+ return int(moment.timestamp() * 1000)+++async def _oldest_recorded_join(session: AsyncSession, room_id: str) -> Message | None:+ """The first arrival the log holds for this room, which bounds join checking."""+ result = await session.execute(+ select(Message)+ .where(Message.room_id == room_id, Message.event_type == MEMBERSHIP_EVENT_TYPE)+ .order_by(Message.seq)+ .limit(1)+ )+ return result.scalars().first()+++async def _oldest_recorded(session: AsyncSession, room_id: str) -> Message | None:+ """The row recording began with, which anchors the window.++ Ordered by `seq` rather than `sent_at`: within a room `seq` is a total+ order with no ties, so "the first row" is a fact rather than whichever of+ two equal timestamps the planner returned first.+ """+ result = await session.execute(+ select(Message).where(Message.room_id == room_id).order_by(Message.seq).limit(1)+ )+ return result.scalars().first()+++async def _recorded_since(+ session: AsyncSession, room_id: str, since: datetime+) -> dict[str, Message]:+ result = await session.execute(+ select(Message)+ .where(Message.room_id == room_id, Message.sent_at >= since)+ .order_by(Message.seq)+ )+ return {row.transport_event_id: row for row in result.scalars().all()}+++async def _read_back_to(+ transport: MessageTransport,+ matrix_room_id: str,+ *,+ anchor_event_id: str | None,+ floor_ms: int,+ window_start_ms: int,+ joins_from_ms: int | None,+ join_anchor_id: str | None,+) -> tuple[dict[str, InboundEvent], dict[str, int], bool]:+ """Page backwards until the window is covered.++ Stops on `anchor_event_id` — the oldest recorded row's own event — which+ puts the boundary on an identity rather than on two clocks that disagree+ by however long a write takes. `floor_ms` only ends a walk that never+ finds it, and the third return value says which of the two happened.++ Unbounded within those limits on purpose, unlike the read path: a+ reconciliation that gave up after a page budget would report the events it+ never looked at as agreeing, which is the one answer it must never give.+ """+ events: dict[str, InboundEvent] = {}+ ignored: dict[str, int] = {}+ start: str | None = None+ anchored = False+ done = False+ while not done:+ page = await transport.read_history(+ matrix_room_id, start=start, limit=PAGE_SIZE+ )+ for raw in page.events:+ if not isinstance(raw, InboundEvent):+ ignored["unrecognised"] = ignored.get("unrecognised", 0) + 1+ continue+ # History comes back newest first, so reaching either limit is the+ # end of the walk rather than an event to skip past.+ if raw.timestamp < floor_ms:+ done = True+ break+ is_anchor = raw.event_id == anchor_event_id+ # The anchor is the one event admitted from before the window: its+ # row's `sent_at` is by construction later than it.+ if raw.timestamp >= window_start_ms or is_anchor:+ _classify(raw, events, ignored, joins_from_ms, join_anchor_id)+ elif anchor_event_id is None:+ done = True+ break+ if is_anchor:+ anchored = True+ done = True+ break+ if done:+ break+ end = page.next_token+ if not end or end == start:+ break+ start = end+ return events, ignored, anchored or anchor_event_id is None+++def _classify(+ raw: InboundEvent,+ events: dict[str, InboundEvent],+ ignored: dict[str, int],+ joins_from_ms: int | None,+ join_anchor_id: str | None,+) -> None:+ """Sort one bus event into the comparison set or the ignored tally."""+ if isinstance(raw, InboundCustomEvent) and not should_record(raw.event_type):+ ignored[raw.event_type] = ignored.get(raw.event_type, 0) + 1+ elif isinstance(raw, InboundMessage | InboundCustomEvent):+ events[raw.event_id] = raw+ elif isinstance(raw, InboundMembership):+ _classify_membership(raw, events, ignored, joins_from_ms, join_anchor_id)+ else:+ name = type(raw).__name__+ ignored[name] = ignored.get(name, 0) + 1+++def _classify_membership(+ raw: InboundMembership,+ events: dict[str, InboundEvent],+ ignored: dict[str, int],+ joins_from_ms: int | None,+ join_anchor_id: str | None,+) -> None:+ """An arrival is comparable; anything else membership does is not.++ Only a transition into membership is recorded, so an invite, a leave and a+ profile change re-firing as a join all belong in the tally. So does a join+ from before the log held any arrival at all.+ """+ arrived = raw.membership == "join" and raw.prev_membership != "join"+ in_log_window = joins_from_ms is not None and (+ raw.timestamp >= joins_from_ms or raw.event_id == join_anchor_id+ )+ if arrived and in_log_window:+ events[raw.event_id] = raw+ return+ label = (+ f"{MEMBERSHIP_EVENT_TYPE} (before arrivals were recorded)"+ if arrived+ else MEMBERSHIP_EVENT_TYPE+ )+ ignored[label] = ignored.get(label, 0) + 1+++def _compare(event_id: str, event: InboundEvent, row: Message) -> list[Mismatch]:+ """Compare the fields a reader will depend on once the read path moves.++ Not the whole content dict: the bus is free to hand back an event+ annotated with fields it added itself, and reporting those as drift would+ train everyone to ignore the report.+ """+ if isinstance(event, InboundMembership):+ # The row is about the member who arrived, which is `state_key`; the+ # sender of a membership event can be whoever admitted them.+ return _mismatches(+ event_id,+ [+ ("member", event.state_key, row.sender_matrix_id),+ ("event_type", MEMBERSHIP_EVENT_TYPE, row.event_type),+ ],+ )++ expected: list[tuple[str, object, object]] = [+ ("sender", event.sender, row.sender_matrix_id),+ ]+ if isinstance(event, InboundCustomEvent):+ expected.append(("event_type", event.event_type, row.event_type))+ expected.append(("thread_root", event.thread_root_id, row.thread_root_event_id))+ elif isinstance(event, InboundMessage):+ expected.append(("event_type", "m.room.message", row.event_type))+ expected.append(("body", event.body, row.body))+ expected.append(("msgtype", event.msgtype, row.msgtype))+ expected.append(("thread_root", event.thread_root_id, row.thread_root_event_id))+ if isinstance(event, InboundMedia):+ expected.append(("uri", event.uri, row.content.get("url")))++ return _mismatches(event_id, expected)+++def _mismatches(+ event_id: str, expected: list[tuple[str, object, object]]+) -> list[Mismatch]:+ return [+ Mismatch(+ event_id=event_id,+ field_name=name,+ on_the_bus=on_the_bus,+ recorded=recorded,+ )+ for name, on_the_bus, recorded in expected+ if on_the_bus != recorded+ ]diff --git a/core/switch_core/messages/recorded_types.py b/core/switch_core/messages/recorded_types.pynew file mode 100644index 000000000..0ab7bffd5--- /dev/null+++ b/core/switch_core/messages/recorded_types.py@@ -0,0 +1,82 @@+"""Which sent events belong in the message log.++The log and the bus are two different things. The bus carries everything a+running system says to itself — a typing indicator, an RPC request, a task+transition. The log is the conversation: what a person reading the room later+would expect to find there. Only the second belongs in `messages`.++This is a denylist rather than an allowlist on purpose. A type nobody+classified is recorded, which costs a row; an allowlist would drop it, and a+missing message the read path never knows to look for is the worse failure by+far. `test_recorded_types.py` walks the dispatch table and fails on anything+unclassified, so the denylist stays honest without the log going quiet.+"""++from __future__ import annotations++# An arrival. Not a send, so it never reaches `should_record` — the recorder+# has its own entry point for it — but the read path needs the name to tell an+# arrival from something someone said.+MEMBERSHIP_EVENT_TYPE = "m.room.member"++# Ephemeral: presence-like state, superseded by the next one, null body.+EPHEMERAL = frozenset({"com.switch.agent.runtime_state"})++# Already durable in the `tasks` table, which is the record readers query.+PERSISTED_ELSEWHERE = frozenset(+ {+ "com.switch.task.delegate",+ "com.switch.task.accept",+ "com.switch.task.update",+ "com.switch.task.finalise",+ "com.switch.task.cancel",+ }+)++# Measurements of a run, not utterances in a room. If these are worth keeping+# they want a table shaped for querying them, not the conversation log.+TELEMETRY = frozenset({"com.switch.report.tool_call", "com.switch.report.llm_call"})++# Types no code sends any more. The bus keeps its history forever, so events of+# a retired type stay readable long after the last line that could produce one+# was deleted — and anything walking that history has to be able to say what+# they were. Without this, deleting a type turns every historical event of it+# into an unclassified event that should have been recorded, which reconcile+# reports as a missing row for good.+#+# APPEND ONLY. A name leaves this set only if the type is revived, in which+# case it belongs in one of the categories above instead.+RETIRED = frozenset(+ {+ # Deleted with the RPC round trips, which were switch-core talking to+ # itself over the bus.+ "com.switch.mediation.tool_request",+ "com.switch.mediation.tool_result",+ "com.switch.mediation.llm_request",+ "com.switch.mediation.llm_response",+ "com.switch.resource.load_request",+ "com.switch.resource.load_response",+ "com.switch.resource.room_document_create_request",+ "com.switch.resource.room_document_create_response",+ "com.switch.resource.room_document_update_request",+ "com.switch.resource.room_document_update_response",+ "com.switch.resource.room_document_delete_request",+ "com.switch.resource.room_document_delete_response",+ # Deleted as dead since the initial import.+ "com.switch.permission.request",+ "com.switch.permission.response",+ }+)++NOT_RECORDED = EPHEMERAL | PERSISTED_ELSEWHERE | TELEMETRY | RETIRED++# The observe prefix is reserved and unimplemented; no type under it exists to+# name individually yet.+NOT_RECORDED_PREFIXES = ("com.switch.observe.",)+++def should_record(event_type: str) -> bool:+ """Whether an event of this type belongs in the message log."""+ if event_type in NOT_RECORDED:+ return False+ return not event_type.startswith(NOT_RECORDED_PREFIXES)diff --git a/core/switch_core/messages/recorder.py b/core/switch_core/messages/recorder.pynew file mode 100644index 000000000..892d89ce1--- /dev/null+++ b/core/switch_core/messages/recorder.py@@ -0,0 +1,214 @@+"""Records into Postgres what was sent over the transport.++The transport remains the source of truth for history; these rows are a+parallel record that a later change reads from instead. Recording happens+after the send has been accepted, so the database never delays or blocks+delivery.++That ordering has a consequence worth stating rather than hiding: a failure+here leaves a row missing for a message that was really delivered. The+alternative — failing the send because the database is unhappy — would make+messaging less reliable than it is today, which is not a trade this step is+willing to make. Failures are logged at error, never swallowed silently, and+reconciling the two records is part of moving the read path over.++What gets a row is decided in `recorded_types`: the conversation, not every+event that crosses the bus.++Arrivals are the exception to "record what you send". A join is not a send, but+it is part of the timeline a reader expects — history shows who appeared and+when. It is recorded by the arriving client about itself, which keeps the+one-row-per-event property the send path gets for free: exactly one Switch+client owns each participant, so exactly one of them records the arrival.+"""++from __future__ import annotations++import logging+from typing import TYPE_CHECKING++from switch_core.db.models import Message+from switch_core.db.stores.message_store import MessageStore+from switch_core.db.stores.room_store import RoomStore+from switch_core.messages.recorded_types import MEMBERSHIP_EVENT_TYPE, should_record+from switch_core.messages.row import attachments_in, text_field, thread_root_of++if TYPE_CHECKING:+ from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker++ from switch_core.transport import InboundMembership, SendResult++logger = logging.getLogger(__name__)+++class MessageRecorder:+ def __init__(+ self,+ *,+ session_factory: async_sessionmaker[AsyncSession],+ room_store: RoomStore,+ message_store: MessageStore,+ ) -> None:+ self._session_factory = session_factory+ self._room_store = room_store+ self._message_store = message_store+ # A room's transport id never changes, so this only ever grows and+ # never goes stale.+ self._room_ids: dict[str, str] = {}++ async def record(+ self,+ *,+ transport_room_id: str,+ result: SendResult,+ sender_matrix_id: str,+ sender_client_id: str,+ sender_name: str,+ ) -> None:+ if not should_record(result.event_type):+ return+ try:+ await self._record(+ transport_room_id=transport_room_id,+ result=result,+ sender_matrix_id=sender_matrix_id,+ sender_client_id=sender_client_id,+ sender_name=sender_name,+ )+ except Exception:+ logger.error(+ "Delivered %s to %s but failed to record it as %s",+ result.event_type,+ transport_room_id,+ result.event_id,+ exc_info=True,+ )++ async def record_join(+ self,+ *,+ transport_room_id: str,+ event: InboundMembership,+ client_id: str,+ member_name: str,+ ) -> None:+ """Record an arrival, called by the client that arrived.++ `member_name` is the arriving client's own name rather than the+ display name on the membership event: the profile behind that name is+ set from whatever the source platform calls the member, so taking it+ would make the same participant read one way when they arrive and+ another way when they speak.++ Like `record`, a failure here leaves a gap rather than disturbing+ anything: nothing about a join depends on it having been written.+ """+ try:+ await self._record_join(+ transport_room_id=transport_room_id,+ event=event,+ client_id=client_id,+ member_name=member_name,+ )+ except Exception:+ logger.error(+ "Joined %s but failed to record the arrival as %s",+ transport_room_id,+ event.event_id,+ exc_info=True,+ )++ async def _record_join(+ self,+ *,+ transport_room_id: str,+ event: InboundMembership,+ client_id: str,+ member_name: str,+ ) -> None:+ async with self._session_factory() as session:+ room_id = await self._resolve_room(session, transport_room_id)+ if room_id is None:+ logger.warning(+ "Not recording %s: %s is not a Switch room",+ event.event_id,+ transport_room_id,+ )+ return++ # A join can be observed twice — a redelivered sync, a restart that+ # re-reads the same member event — and the second one is not a+ # second arrival. The unique constraint on `transport_event_id` is+ # the backstop; this keeps the ordinary case off the error log.+ existing = await self._message_store.get_by_transport_event_id(+ session, event.event_id+ )+ if existing is not None:+ return++ # No body: what an arrival reads as is the reader's to phrase, and+ # a rendered sentence in the log would freeze today's wording into+ # every row ever written.+ message = Message(+ room_id=room_id,+ transport_event_id=event.event_id,+ sender_matrix_id=event.state_key,+ sender_client_id=client_id,+ sender_name=member_name,+ event_type=MEMBERSHIP_EVENT_TYPE,+ msgtype=None,+ body=None,+ formatted_body=None,+ thread_root_event_id=None,+ content=dict(event.content),+ )+ await self._message_store.create(session, message, [])+ await session.commit()++ async def _record(+ self,+ *,+ transport_room_id: str,+ result: SendResult,+ sender_matrix_id: str,+ sender_client_id: str,+ sender_name: str,+ ) -> None:+ async with self._session_factory() as session:+ room_id = await self._resolve_room(session, transport_room_id)+ if room_id is None:+ logger.warning(+ "Not recording %s: %s is not a Switch room",+ result.event_id,+ transport_room_id,+ )+ return++ content = result.content+ message = Message(+ room_id=room_id,+ transport_event_id=result.event_id,+ sender_matrix_id=sender_matrix_id,+ sender_client_id=sender_client_id,+ sender_name=sender_name,+ event_type=result.event_type,+ msgtype=text_field(content.get("msgtype")),+ body=text_field(content.get("body")),+ formatted_body=text_field(content.get("formatted_body")),+ thread_root_event_id=thread_root_of(content),+ content=content,+ )+ await self._message_store.create(session, message, attachments_in(content))+ await session.commit()++ async def _resolve_room(+ self, session: AsyncSession, transport_room_id: str+ ) -> str | None:+ cached = self._room_ids.get(transport_room_id)+ if cached is not None:+ return cached+ room = await self._room_store.get_by_matrix_room_id(session, transport_room_id)+ if room is None:+ return None+ self._room_ids[transport_room_id] = room.id+ return room.iddiff --git a/core/switch_core/messages/recording.py b/core/switch_core/messages/recording.pynew file mode 100644index 000000000..508f86faa--- /dev/null+++ b/core/switch_core/messages/recording.py@@ -0,0 +1,75 @@+"""Whether a client has to write down what it sent.++Recording exists because the bus was the delivery and the table was a copy.+When the table *is* the delivery there is nothing to copy, and a client that+recorded anyway would write every message twice.++So which recorder a client gets is chosen with its transport, by the same+factory, and the pairing is the invariant: a transport that stores what it+carries takes `NoRecording`, and one that does not takes `MessageRecorder`.+Getting the pair wrong is visible immediately — duplicate rows one way, a+silent log the other — which is the argument for making it one decision in one+place rather than a flag each side reads.+"""++from __future__ import annotations++from typing import TYPE_CHECKING, Protocol, runtime_checkable++if TYPE_CHECKING:+ from switch_core.transport import InboundMembership, SendResult+++@runtime_checkable+class MessageRecording(Protocol):+ """Writes the message log, or knows that something else already did."""++ async def record(+ self,+ *,+ transport_room_id: str,+ result: SendResult,+ sender_matrix_id: str,+ sender_client_id: str,+ sender_name: str,+ ) -> None: ...++ async def record_join(+ self,+ *,+ transport_room_id: str,+ event: InboundMembership,+ client_id: str,+ member_name: str,+ ) -> None: ...+++class NoRecording:+ """For a transport whose own write is the record.++ Not a disabled feature: the rows still exist, and are still exactly one per+ event. They are written by the transport, in the same transaction that+ accepted the send, which is stronger than what this replaces — the+ recorder ran after delivery and could leave a gap.+ """++ async def record(+ self,+ *,+ transport_room_id: str,+ result: SendResult,+ sender_matrix_id: str,+ sender_client_id: str,+ sender_name: str,+ ) -> None:+ return None++ async def record_join(+ self,+ *,+ transport_room_id: str,+ event: InboundMembership,+ client_id: str,+ member_name: str,+ ) -> None:+ return Nonediff --git a/core/switch_core/messages/row.py b/core/switch_core/messages/row.pynew file mode 100644index 000000000..4252a9d9d--- /dev/null+++ b/core/switch_core/messages/row.py@@ -0,0 +1,48 @@+"""How an event's content becomes the columns beside it.++`messages` keeps the whole event in `content` and denormalises a few fields out+of it for querying. Which fields, and how they are read out, is one rule — the+writer and anything reconstructing a row from history have to agree on it, or+the same event stored twice would be two different rows.+"""++from __future__ import annotations++from switch_core.db.models import MessageAttachment+++def text_field(value: object) -> str | None:+ return value if isinstance(value, str) else None+++def thread_root_of(content: dict[str, object]) -> str | None:+ relation = content.get("m.relates_to")+ if not isinstance(relation, dict) or relation.get("rel_type") != "m.thread":+ return None+ return text_field(relation.get("event_id"))+++def attachments_in(content: dict[str, object]) -> list[MessageAttachment]:+ """A media event carries exactly one file.++ A message with several files is sent as one event per file sharing a group+ id, so each of those events records a single attachment. The column exists+ as a list because reassembling the group is the reader's job, not the+ writer's.+ """+ uri = text_field(content.get("url"))+ if uri is None:+ return []+ info = content.get("info")+ info = info if isinstance(info, dict) else {}+ size = info.get("size")+ return [+ MessageAttachment(+ uri=uri,+ filename=text_field(content.get("filename"))+ or text_field(content.get("body")),+ mimetype=text_field(info.get("mimetype")),+ size=size if isinstance(size, int) else None,+ position=0,+ )+ ]diff --git a/core/switch_core/migrations/versions/a1d7f3c95b60_media_blobs.py b/core/switch_core/migrations/versions/a1d7f3c95b60_media_blobs.pynew file mode 100644index 000000000..def43b269--- /dev/null+++ b/core/switch_core/migrations/versions/a1d7f3c95b60_media_blobs.py@@ -0,0 +1,39 @@+"""media blobs++Where an attachment's bytes live once the homeserver is not there to hold+them. Nothing reads this table until the Postgres transport is the one in use,+so applying it early is free and keeps the flip to a restart.++Revision ID: a1d7f3c95b60+Revises: f4c2a8e6d193+"""++import sqlalchemy as sa+from alembic import op++revision = "a1d7f3c95b60"+down_revision = "f4c2a8e6d193"+branch_labels = None+depends_on = None+++def upgrade() -> None:+ op.create_table(+ "media_blobs",+ sa.Column("id", sa.Text(), primary_key=True),+ sa.Column("uri", sa.Text(), nullable=False, unique=True),+ sa.Column("content_type", sa.Text(), nullable=True),+ sa.Column("filename", sa.Text(), nullable=True),+ sa.Column("size", sa.BigInteger(), nullable=False),+ sa.Column("data", sa.LargeBinary(), nullable=False),+ sa.Column(+ "created_at",+ sa.DateTime(timezone=True),+ server_default=sa.func.now(),+ nullable=False,+ ),+ )+++def downgrade() -> None:+ op.drop_table("media_blobs")diff --git a/core/switch_core/migrations/versions/a3f7c91b8e24_messages_and_attachments.py b/core/switch_core/migrations/versions/a3f7c91b8e24_messages_and_attachments.pynew file mode 100644index 000000000..bbcc4d53c--- /dev/null+++ b/core/switch_core/migrations/versions/a3f7c91b8e24_messages_and_attachments.py@@ -0,0 +1,100 @@+"""messages and message attachments++A parallel record of every message sent into a room, written alongside the+send. Nothing reads these tables yet; the read path moves onto them in a+later change.++Revision ID: a3f7c91b8e24+Revises: c81f4a06d2b7+Create Date: 2026-09-03 21:00:00.000000++"""++from collections.abc import Sequence++import sqlalchemy as sa+from alembic import op+from sqlalchemy.dialects.postgresql import JSONB++revision: str = "a3f7c91b8e24"+down_revision: str | None = "c81f4a06d2b7"+branch_labels: str | Sequence[str] | None = None+depends_on: str | Sequence[str] | None = None+++def upgrade() -> None:+ op.create_table(+ "messages",+ sa.Column("id", sa.Text(), primary_key=True, nullable=False),+ sa.Column(+ "seq",+ sa.BigInteger(),+ sa.Identity(always=True),+ unique=True,+ nullable=False,+ ),+ sa.Column(+ "room_id",+ sa.Text(),+ sa.ForeignKey("rooms.id", ondelete="CASCADE"),+ nullable=False,+ ),+ sa.Column("transport_event_id", sa.Text(), unique=True, nullable=False),+ sa.Column("sender_matrix_id", sa.Text(), nullable=False),+ sa.Column(+ "sender_client_id",+ sa.Text(),+ sa.ForeignKey("clients.id", ondelete="SET NULL"),+ nullable=True,+ ),+ sa.Column("sender_name", sa.Text(), nullable=True),+ sa.Column("event_type", sa.Text(), nullable=False),+ sa.Column("msgtype", sa.Text(), nullable=True),+ sa.Column("body", sa.Text(), nullable=True),+ sa.Column("formatted_body", sa.Text(), nullable=True),+ sa.Column("thread_root_event_id", sa.Text(), nullable=True),+ sa.Column("content", JSONB(), nullable=False),+ sa.Column(+ "sent_at",+ sa.DateTime(timezone=True),+ server_default=sa.func.now(),+ nullable=False,+ ),+ )+ op.create_index("ix_messages_room_seq", "messages", ["room_id", "seq"])+ op.create_index(+ "ix_messages_thread_root",+ "messages",+ ["room_id", "thread_root_event_id"],+ postgresql_where=sa.text("thread_root_event_id IS NOT NULL"),+ )++ op.create_table(+ "message_attachments",+ sa.Column("id", sa.Text(), primary_key=True, nullable=False),+ sa.Column(+ "message_id",+ sa.Text(),+ sa.ForeignKey("messages.id", ondelete="CASCADE"),+ nullable=False,+ ),+ sa.Column("position", sa.Integer(), nullable=False),+ sa.Column("uri", sa.Text(), nullable=False),+ sa.Column("filename", sa.Text(), nullable=True),+ sa.Column("mimetype", sa.Text(), nullable=True),+ sa.Column("size", sa.BigInteger(), nullable=True),+ sa.Column(+ "created_at",+ sa.DateTime(timezone=True),+ server_default=sa.func.now(),+ nullable=False,+ ),+ )+ op.create_index(+ "ix_message_attachments_message", "message_attachments", ["message_id"]+ )+++def downgrade() -> None:+ op.drop_table("message_attachments")+ op.drop_table("messages")diff --git a/core/switch_core/migrations/versions/b5d2e08c17af_message_seq_per_room.py b/core/switch_core/migrations/versions/b5d2e08c17af_message_seq_per_room.pynew file mode 100644index 000000000..0fdae387c--- /dev/null+++ b/core/switch_core/migrations/versions/b5d2e08c17af_message_seq_per_room.py@@ -0,0 +1,79 @@+"""number messages per room, in commit order++`seq` was a global identity column. A sequence allocates when a statement+runs, not when it commits, so a row could commit behind one with a higher+number and a cursor paging on `seq > n` would step over it permanently. The+column is now assigned per room by the store under an advisory lock, which+makes sequence order and commit order the same order.++Existing rows are renumbered by their old global order, which preserves the+order they were written in.++Revision ID: b5d2e08c17af+Revises: a3f7c91b8e24+Create Date: 2026-09-03 23:30:00.000000++"""++from collections.abc import Sequence++import sqlalchemy as sa+from alembic import op++revision: str = "b5d2e08c17af"+down_revision: str | None = "a3f7c91b8e24"+branch_labels: str | Sequence[str] | None = None+depends_on: str | Sequence[str] | None = None+++def upgrade() -> None:+ # The identity has to go before the values can be rewritten: an+ # `always` identity rejects a plain UPDATE.+ op.execute("ALTER TABLE messages ALTER COLUMN seq DROP IDENTITY IF EXISTS")+ op.drop_constraint("messages_seq_key", "messages", type_="unique")+ op.drop_index("ix_messages_room_seq", table_name="messages")+ op.execute(+ """+ UPDATE messages AS m+ SET seq = renumbered.position+ FROM (+ SELECT id, row_number() OVER (PARTITION BY room_id ORDER BY seq)+ AS position+ FROM messages+ ) AS renumbered+ WHERE m.id = renumbered.id+ """+ )+ op.create_unique_constraint("uq_messages_room_seq", "messages", ["room_id", "seq"])+++def downgrade() -> None:+ op.drop_constraint("uq_messages_room_seq", "messages", type_="unique")+ # Per-room numbers collide across rooms, so a global identity cannot be+ # restored over them. Renumber globally by the order rows were sent in.+ op.execute(+ """+ UPDATE messages AS m+ SET seq = renumbered.position+ FROM (+ SELECT id, row_number() OVER (ORDER BY sent_at, room_id, seq)+ AS position+ FROM messages+ ) AS renumbered+ WHERE m.id = renumbered.id+ """+ )+ op.create_index("ix_messages_room_seq", "messages", ["room_id", "seq"])+ op.create_unique_constraint("messages_seq_key", "messages", ["seq"])+ op.execute(+ "ALTER TABLE messages ALTER COLUMN seq "+ "ADD GENERATED ALWAYS AS IDENTITY (START WITH 1)"+ )+ op.execute(+ sa.text(+ "SELECT setval("+ " pg_get_serial_sequence('messages', 'seq'),"+ " coalesce((SELECT max(seq) FROM messages), 1)"+ ")"+ )+ )diff --git a/core/switch_core/migrations/versions/b6d1f04ae932_rooms_history_backfilled_at.py b/core/switch_core/migrations/versions/b6d1f04ae932_rooms_history_backfilled_at.pynew file mode 100644index 000000000..16e00001c--- /dev/null+++ b/core/switch_core/migrations/versions/b6d1f04ae932_rooms_history_backfilled_at.py@@ -0,0 +1,36 @@+"""record when a room's history has been reconstructed++Revision ID: b6d1f04ae932+Revises: a1d7f3c95b60++The backfill always walks from a room's newest message towards its start, so+it cannot tell from the rows alone that it has already finished — a second run+reads every page of every room again to discover it has nothing to write. On a+deployment where the backfill runs unattended at startup, that is the whole+history re-read on every boot.++Null means never completed, which deliberately includes a walk that stopped at+the page limit: that room is only partly reconstructed, and treating it as done+would strand the rest.+"""++from collections.abc import Sequence++import sqlalchemy as sa+from alembic import op++revision: str = "b6d1f04ae932"+down_revision: str | Sequence[str] | None = "a1d7f3c95b60"+branch_labels: str | Sequence[str] | None = None+depends_on: str | Sequence[str] | None = None+++def upgrade() -> None:+ op.add_column(+ "rooms",+ sa.Column("history_backfilled_at", sa.DateTime(timezone=True), nullable=True),+ )+++def downgrade() -> None:+ op.drop_column("rooms", "history_backfilled_at")diff --git a/core/switch_core/migrations/versions/c71a4f9d2b83_message_sent_at_index.py b/core/switch_core/migrations/versions/c71a4f9d2b83_message_sent_at_index.pynew file mode 100644index 000000000..e2d718132--- /dev/null+++ b/core/switch_core/migrations/versions/c71a4f9d2b83_message_sent_at_index.py@@ -0,0 +1,28 @@+"""index messages by room and sent_at++The read path filters history by time window and orders it by `seq`. `seq`+already has an index through the room uniqueness constraint; `sent_at` had+none, so a windowed read had to scan the room.++Revision ID: c71a4f9d2b83+Revises: b5d2e08c17af+Create Date: 2026-09-03 00:00:00.000000++"""++from collections.abc import Sequence++from alembic import op++revision: str = "c71a4f9d2b83"+down_revision: str | None = "b5d2e08c17af"+branch_labels: str | Sequence[str] | None = None+depends_on: str | Sequence[str] | None = None+++def upgrade() -> None:+ op.create_index("ix_messages_room_sent_at", "messages", ["room_id", "sent_at"])+++def downgrade() -> None:+ op.drop_index("ix_messages_room_sent_at", table_name="messages")diff --git a/core/switch_core/migrations/versions/d4e17b90c3a5_message_notify_and_cursors.py b/core/switch_core/migrations/versions/d4e17b90c3a5_message_notify_and_cursors.pynew file mode 100644index 000000000..7260b7121--- /dev/null+++ b/core/switch_core/migrations/versions/d4e17b90c3a5_message_notify_and_cursors.py@@ -0,0 +1,83 @@+"""announce new messages, and remember how far each agent has been delivered++The trigger makes an insert into `messages` announce itself on commit, so+delivery can be driven by the table rather than by a live bus connection. The+payload is a hint — room, position, row id — and consumers read the row, which+is what keeps a lost notification a latency problem rather than a data one.++`delivery_cursors` persists what the event buffer held in memory, so an agent's+position outlives the process that was serving it.++The DDL below is a verbatim copy of `switch_core/db/notify_ddl.py` as it stood+when this migration was written. It is copied rather than imported on purpose:+a migration is a record of a change that already happened, and importing the+live module would make an old migration mean something new.++Revision ID: d4e17b90c3a5+Revises: c71a4f9d2b83+Create Date: 2026-09-03 00:00:00.000000++"""++from collections.abc import Sequence++import sqlalchemy as sa+from alembic import op++revision: str = "d4e17b90c3a5"+down_revision: str | None = "c71a4f9d2b83"+branch_labels: str | Sequence[str] | None = None+depends_on: str | Sequence[str] | None = None++CREATE_NOTIFY_FUNCTION = """+CREATE OR REPLACE FUNCTION switch_notify_message() RETURNS trigger AS $$+BEGIN+ PERFORM pg_notify(+ 'switch_message',+ json_build_object(+ 'room_id', NEW.room_id,+ 'seq', NEW.seq,+ 'id', NEW.id+ )::text+ );+ RETURN NULL;+END;+$$ LANGUAGE plpgsql+"""++CREATE_NOTIFY_TRIGGER = """+CREATE TRIGGER messages_notify+ AFTER INSERT ON messages+ FOR EACH ROW EXECUTE FUNCTION switch_notify_message()+"""+++def upgrade() -> None:+ op.execute(CREATE_NOTIFY_FUNCTION)+ op.execute(CREATE_NOTIFY_TRIGGER)++ op.create_table(+ "delivery_cursors",+ sa.Column("id", sa.Text(), nullable=False),+ sa.Column("agent_id", sa.Text(), nullable=False),+ sa.Column("room_id", sa.Text(), nullable=False),+ sa.Column("last_seq", sa.BigInteger(), nullable=False),+ sa.Column(+ "updated_at",+ sa.DateTime(timezone=True),+ server_default=sa.text("now()"),+ nullable=False,+ ),+ sa.ForeignKeyConstraint(["agent_id"], ["agents.id"], ondelete="CASCADE"),+ sa.ForeignKeyConstraint(["room_id"], ["rooms.id"], ondelete="CASCADE"),+ sa.PrimaryKeyConstraint("id"),+ sa.UniqueConstraint(+ "agent_id", "room_id", name="uq_delivery_cursors_agent_room"+ ),+ )+++def downgrade() -> None:+ op.drop_table("delivery_cursors")+ op.execute("DROP TRIGGER IF EXISTS messages_notify ON messages")+ op.execute("DROP FUNCTION IF EXISTS switch_notify_message()")diff --git a/core/switch_core/migrations/versions/e83c5a17f4d2_backfill_seq_and_cursors.py b/core/switch_core/migrations/versions/e83c5a17f4d2_backfill_seq_and_cursors.pynew file mode 100644index 000000000..1e7594499--- /dev/null+++ b/core/switch_core/migrations/versions/e83c5a17f4d2_backfill_seq_and_cursors.py@@ -0,0 +1,66 @@+"""do not announce reconstructed history++Backfilled messages are numbered below zero — positive is what Switch recorded+as it happened, negative is what was reconstructed from the bus afterwards.+Announcing them would wake every subscriber in the room to read nothing, since+a delivery cursor starts at 0 and is above these positions by construction.++Replaces the trigger function in place; the trigger itself is unchanged.++Revision ID: e83c5a17f4d2+Revises: d4e17b90c3a5+Create Date: 2026-09-03 00:00:00.000000++"""++from collections.abc import Sequence++from alembic import op++revision: str = "e83c5a17f4d2"+down_revision: str | None = "d4e17b90c3a5"+branch_labels: str | Sequence[str] | None = None+depends_on: str | Sequence[str] | None = None++WITH_BACKFILL_GUARD = """+CREATE OR REPLACE FUNCTION switch_notify_message() RETURNS trigger AS $$+BEGIN+ IF NEW.seq <= 0 THEN+ RETURN NULL;+ END IF;+ PERFORM pg_notify(+ 'switch_message',+ json_build_object(+ 'room_id', NEW.room_id,+ 'seq', NEW.seq,+ 'id', NEW.id+ )::text+ );+ RETURN NULL;+END;+$$ LANGUAGE plpgsql+"""++WITHOUT_BACKFILL_GUARD = """+CREATE OR REPLACE FUNCTION switch_notify_message() RETURNS trigger AS $$+BEGIN+ PERFORM pg_notify(+ 'switch_message',+ json_build_object(+ 'room_id', NEW.room_id,+ 'seq', NEW.seq,+ 'id', NEW.id+ )::text+ );+ RETURN NULL;+END;+$$ LANGUAGE plpgsql+"""+++def upgrade() -> None:+ op.execute(WITH_BACKFILL_GUARD)+++def downgrade() -> None:+ op.execute(WITHOUT_BACKFILL_GUARD)diff --git a/core/switch_core/migrations/versions/f4c2a8e6d193_drop_resource_manager_client.py b/core/switch_core/migrations/versions/f4c2a8e6d193_drop_resource_manager_client.pynew file mode 100644index 000000000..6e8ed8486--- /dev/null+++ b/core/switch_core/migrations/versions/f4c2a8e6d193_drop_resource_manager_client.py@@ -0,0 +1,42 @@+"""remove the resource manager client record++The resource manager stopped being a Matrix client when the four resource+operations became direct calls on `resource_service`. Nothing registers the+type any more, so a leftover row makes `ClientFactory.create` raise+`Unknown client type: 'resource_manager'` and takes the whole startup with it.++The Matrix account itself is left alone: this migration owns the Switch+database, not the homeserver, and an account nobody logs into costs nothing.++Revision ID: f4c2a8e6d193+Revises: e83c5a17f4d2+Create Date: 2026-09-04 00:00:00.000000++"""++from collections.abc import Sequence++from alembic import op++revision: str = "f4c2a8e6d193"+down_revision: str | None = "e83c5a17f4d2"+branch_labels: str | Sequence[str] | None = None+depends_on: str | Sequence[str] | None = None+++def upgrade() -> None:+ op.execute(+ """+ DELETE FROM client_rooms+ WHERE client_id IN (SELECT id FROM clients WHERE type = 'resource_manager')+ """+ )+ op.execute("DELETE FROM clients WHERE type = 'resource_manager'")+++def downgrade() -> None:+ """Not reversible.++ The row carried a Matrix password and access token that are not recoverable+ from anything left behind, and no code path reads the type any more.+ """diff --git a/core/switch_core/provisioning/__init__.py b/core/switch_core/provisioning/__init__.pynew file mode 100644index 000000000..c1ad6a7a8--- /dev/null+++ b/core/switch_core/provisioning/__init__.py@@ -0,0 +1,8 @@+"""Provisioning for Switch: accounts, rooms and membership.++`Provisioning` (in `port`) is the contract; implementations live beside it.+"""++from switch_core.provisioning.port import Provisioning++__all__ = ["Provisioning"]diff --git a/core/switch_core/provisioning/port.py b/core/switch_core/provisioning/port.pynew file mode 100644index 000000000..75d4162a6--- /dev/null+++ b/core/switch_core/provisioning/port.py@@ -0,0 +1,69 @@+"""The provisioning port: accounts, rooms and membership.++`MessageTransport` covers what a participant does once it exists. This covers+bringing participants and rooms into existence in the first place — the second+and last thing switch-core asks a homeserver for. The two are separate ports+because they are used by different callers at different times: the transport by+every client for the life of the process, this once per account, room or+membership change, by room provisioning and the client/bridge lifecycles.++The contract is derived from the call sites, not from the endpoints behind it:+create an account, create a room, add and remove a member, discard a room, and+check a password. `verify_login` is the odd one — it exists so a cutover can+tell an empty target server from one that already has accounts under the same+names — and it is the operation most likely to have no counterpart in a future+implementation.++Membership is expressed as invite/kick because that is what the operations+mean, not because of how a homeserver spells them. An implementation that can+simply write a row is free to do so; `invite_to_room` promises the user ends up+in the room, and callers already rely on that rather than on an invitation+being separately accepted.++Both operations are idempotent by contract: inviting a member who is already+in, or kicking one who is already out, is success and not an error. Every other+failure raises.+"""++from __future__ import annotations++from typing import Protocol, runtime_checkable+++@runtime_checkable+class Provisioning(Protocol):+ """Creates the accounts and rooms the transport then talks over."""++ async def register_user(+ self,+ user_id: str,+ password: str,+ display_name: str | None = None,+ is_admin: bool = False,+ ) -> None:+ """Create an account, or do nothing if it already exists."""+ ...++ async def verify_login(self, user_id: str, password: str) -> bool:+ """Whether `password` authenticates `user_id`."""+ ...++ async def create_room(self, name: str, topic: str) -> str:+ """Create a room and return its transport-side id."""+ ...++ async def invite_to_room(self, room_id: str, user_id: str) -> None:+ """Put a user in a room. Already a member is success."""+ ...++ async def kick_user(self, room_id: str, user_id: str) -> None:+ """Take a user out of a room. Already out is success."""+ ...++ async def delete_room(self, room_id: str) -> None:+ """Discard a room. Callers remove the other members first."""+ ...++ async def close(self) -> None:+ """Release whatever the implementation holds open."""+ ...diff --git a/core/switch_core/provisioning/postgres.py b/core/switch_core/provisioning/postgres.pynew file mode 100644index 000000000..880b98098--- /dev/null+++ b/core/switch_core/provisioning/postgres.py@@ -0,0 +1,183 @@+"""Provisioning without a homeserver: every operation is a row.++What the Matrix implementation did over HTTP, this does against the same+database Switch already keeps the answer in. Two of the six turn out to be+almost nothing, and that is the finding rather than a shortcut:++- **An account is the `clients` row.** `register_user` created a homeserver+ account so that a row Switch was about to write would have something to+ authenticate as. There is no second system to register with now, so there is+ nothing to do — the caller writes the row immediately afterwards, and that+ row is the account.+- **A password is a Switch password.** `verify_login` asked the homeserver+ whether a password worked; it asks the `clients` table instead. Its one+ caller is a cutover check for a target server that already has accounts,+ which no longer has a homeserver to be true of.++The other four are writes:++- **A room** gets an id minted here and stored by the caller, exactly as the+ homeserver's `room_id` was.+- **Membership** is a `client_rooms` row plus the arrival that explains it.+ Over Matrix an invitation was a durable event a client picked up whenever it+ next synced; here a live client is woken through the invite bus and joins+ itself, which is what keeps its transport watching the room. When nobody is+ live the membership is written directly, because a client that is not+ running has nothing to wake and will find the room when it starts.+- **Removal** deletes the membership. No leave event is written: a departure+ is not something a reader of the room needs explained, and the timeline the+ log serves is what was said.+- **Discarding a room** is left to the caller's own delete, which cascades.+ Nothing here has a second copy to clean up.+"""++from __future__ import annotations++import logging+import uuid+from typing import TYPE_CHECKING++from switch_core.db.models import ClientRoom, Message++if TYPE_CHECKING:+ from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker++ from switch_core.db.stores.client_store import ClientStore+ from switch_core.db.stores.message_store import MessageStore+ from switch_core.db.stores.room_store import RoomStore+ from switch_core.transport.invites import InviteBus++logger = logging.getLogger(__name__)++MEMBERSHIP_EVENT_TYPE = "m.room.member"+++class ProvisioningError(RuntimeError):+ """A provisioning operation could not be carried out."""+++def new_room_id() -> str:+ """A room's transport-side id.++ Stored in the column that held the homeserver's, and opaque in the same+ way: the prefix is for a human reading a row during the window where both+ kinds exist, and no code may branch on it.+ """+ return f"sw_room_{uuid.uuid4().hex}"+++class PostgresProvisioning:+ """Accounts, rooms and membership as rows in Switch's own database."""++ def __init__(+ self,+ *,+ session_factory: async_sessionmaker[AsyncSession],+ room_store: RoomStore,+ client_store: ClientStore,+ message_store: MessageStore,+ invites: InviteBus,+ ) -> None:+ self._session_factory = session_factory+ self._room_store = room_store+ self._client_store = client_store+ self._message_store = message_store+ self._invites = invites++ async def register_user(+ self,+ user_id: str,+ password: str,+ display_name: str | None = None,+ is_admin: bool = False,+ ) -> None:+ """Nothing to register: the caller's `clients` row is the account."""++ async def verify_login(self, user_id: str, password: str) -> bool:+ async with self._session_factory() as session:+ client = await self._client_store.get_by_matrix_user_id(session, user_id)+ return client is not None and client.password == password++ async def create_room(self, name: str, topic: str) -> str:+ """Mint the id the caller will store on its own room row.++ No row is written here. The room is the caller's to create, and+ writing a second record of it would be a second thing to keep in step.+ """+ return new_room_id()++ async def invite_to_room(self, room_id: str, user_id: str) -> None:+ """Put a user in a room, waking them if they are running.++ A live client joins itself, which is what leaves its transport+ watching the room. Already a member is success, per the port.++ The wake-up is rung even when the membership is already recorded, and+ that is deliberate. A row is no longer proof that a running client is+ subscribed to the room — something else may have written it, and there+ is a window at startup where a client is running but not yet on the+ bus. Returning early on the row would make that state permanent, since+ every later invitation would find the same row and stop. Membership is+ what has to be exactly-once; a wake-up is cheap and idempotent.+ """+ async with self._session_factory() as session:+ switch_room_id, client_id, display_name = await self._resolve(+ session, room_id, user_id+ )+ existing = await session.get(+ ClientRoom, {"client_id": client_id, "room_id": switch_room_id}+ )++ if await self._invites.invite(user_id, room_id):+ return+ if existing is not None:+ return++ async with self._session_factory() as session:+ await self._room_store.add_client(session, client_id, switch_room_id)+ arrival = Message(+ room_id=switch_room_id,+ transport_event_id=f"sw_{uuid.uuid4().hex}",+ sender_matrix_id=user_id,+ sender_client_id=client_id,+ sender_name=display_name,+ event_type=MEMBERSHIP_EVENT_TYPE,+ msgtype=None,+ body=None,+ formatted_body=None,+ thread_root_event_id=None,+ content={"membership": "join", "displayname": display_name},+ )+ await self._message_store.create(session, arrival, [])+ await session.commit()++ async def kick_user(self, room_id: str, user_id: str) -> None:+ """Remove a membership. Already out is success, per the port."""+ async with self._session_factory() as session:+ switch_room_id, client_id, _ = await self._resolve(+ session, room_id, user_id+ )+ await self._room_store.remove_client(session, client_id, switch_room_id)+ await session.commit()++ async def delete_room(self, room_id: str) -> None:+ """Nothing of its own to discard.++ The caller deletes the room, and its messages and memberships go with+ it. The Matrix implementation had a second copy of the room to abandon;+ this has none.+ """++ async def close(self) -> None:+ """Nothing held open."""++ async def _resolve(+ self, session: AsyncSession, transport_room_id: str, user_id: str+ ) -> tuple[str, str, str]:+ room = await self._room_store.get_by_matrix_room_id(session, transport_room_id)+ if room is None:+ raise ProvisioningError(f"{transport_room_id} is not a Switch room")+ client = await self._client_store.get_by_matrix_user_id(session, user_id)+ if client is None:+ raise ProvisioningError(f"{user_id} is not a Switch client")+ return room.id, client.id, client.display_namediff --git a/core/switch_core/room_service.py b/core/switch_core/room_service.pyindex 770c15e7f..952b6a780 100644--- a/core/switch_core/room_service.py+++ b/core/switch_core/room_service.py@@ -33,7 +33,7 @@ from switch_core.db.models import Room, RoomGroup, RoomRolefrom switch_core.db.stores.agent_store import AgentStorefrom switch_core.db.stores.collaboration_bridge_store import CollaborationBridgeStorefrom switch_core.db.stores.room_store import RoomStore-from switch_core.matrix_admin import MatrixAdmin+from switch_core.provisioning import Provisioningif TYPE_CHECKING:from switch_core.bridges.collaboration.bridge_core import BridgeCore@@ -43,7 +43,7 @@ if TYPE_CHECKING:logger = logging.getLogger(__name__)-SYSTEM_CLIENT_TYPES = ("resource_manager", "observe", "admin")+SYSTEM_CLIENT_TYPES = ("observe", "admin")class LinkedRoomSpec(BaseModel):@@ -127,7 +127,7 @@ class RoomService:def __init__(self,*,- matrix_admin: MatrixAdmin,+ matrix_admin: Provisioning,room_store: RoomStore,agent_store: AgentStore,client_lifecycle: ClientLifecycleService,diff --git a/core/switch_core/transport/__init__.py b/core/switch_core/transport/__init__.pynew file mode 100644index 000000000..8e1a370af--- /dev/null+++ b/core/switch_core/transport/__init__.py@@ -0,0 +1,52 @@+"""Message transport for Switch.++`MessageTransport` (in `port`) is the contract; implementations live beside it.+Only modules inside this package may import a transport library — everything+else talks to the port and the neutral types in `types`.+"""++from switch_core.transport.port import (+ Handler,+ MessageTransport,+ SyncErrorHandler,+ SyncHandler,+ TransportHandlers,+)+from switch_core.transport.types import (+ DownloadResult,+ HistoryPage,+ InboundCustomEvent,+ InboundEvent,+ InboundMedia,+ InboundMembership,+ InboundMessage,+ MessageFormat,+ NotConnectedError,+ RoomRef,+ SeekDirection,+ SendResult,+ TransportError,+ UploadResult,+)++__all__ = [+ "DownloadResult",+ "Handler",+ "HistoryPage",+ "InboundCustomEvent",+ "InboundEvent",+ "InboundMedia",+ "InboundMembership",+ "InboundMessage",+ "MessageFormat",+ "MessageTransport",+ "NotConnectedError",+ "RoomRef",+ "SeekDirection",+ "SendResult",+ "SyncErrorHandler",+ "SyncHandler",+ "TransportError",+ "TransportHandlers",+ "UploadResult",+]diff --git a/core/switch_core/transport/content.py b/core/switch_core/transport/content.pynew file mode 100644index 000000000..615096eba--- /dev/null+++ b/core/switch_core/transport/content.py@@ -0,0 +1,107 @@+"""The event bodies Switch sends, assembled once for every transport.++A message's content dict is not Matrix's — it is Switch's own shape, which the+collaboration bridges, the agent read path and the message log all read. Only+the delivery of it is a transport's business. Two transports assembling it+separately would drift, and the drift would show up as a bridge that renders a+caption on one deployment and a filename on another.++The shapes keep their `m.`-prefixed keys. They are what is in every row already+written and what three shipped connectors read; renaming them is a protocol+change, and it is not this module's to make.+"""++from __future__ import annotations++import markdown++from switch_core.attachments import ATTACHMENT_GROUP_KEY+from switch_core.transport.types import MessageFormat+++def thread_relation(thread_root_id: str) -> dict[str, object]:+ """A pure `m.thread` relation, with no `m.in_reply_to` fallback.++ The root id must already be an actual thread root; mid-thread ids are+ normalised upstream.+ """+ return {"rel_type": "m.thread", "event_id": thread_root_id}+++def message_content(+ body: str,+ *,+ sender_name: str,+ format: MessageFormat = "text",+ mentions: list[str] | None = None,+ thread_root_id: str | None = None,+ extra_content: dict[str, object] | None = None,+) -> dict[str, object]:+ content: dict[str, object] = {+ "msgtype": "m.text",+ "body": body,+ "sender_name": sender_name,+ }+ # Caller-supplied content fields (e.g. a `com.switch.*` marker) are merged+ # in. They ride on the plain message — the body still renders normally; the+ # extra keys are metadata other clients can read.+ if extra_content:+ content.update(extra_content)++ if format == "markdown":+ content["format"] = "org.matrix.custom.html"+ content["formatted_body"] = _rendered(body, mentions)++ if thread_root_id is not None:+ content["m.relates_to"] = thread_relation(thread_root_id)++ return content+++def media_content(+ uri: str,+ filename: str,+ mimetype: str,+ size: int,+ *,+ sender_name: str,+ msgtype: str,+ caption: str | None = None,+ thread_root_id: str | None = None,+ group: dict[str, object] | None = None,+) -> dict[str, object]:+ # When a caption is given it becomes the event body, with the real filename+ # carried separately per the rich-media-caption convention.+ content: dict[str, object] = {+ "msgtype": msgtype,+ "body": caption if caption else filename,+ "url": uri,+ "info": {"mimetype": mimetype, "size": size},+ "sender_name": sender_name,+ }+ if caption:+ content["filename"] = filename+ if group is not None:+ content[ATTACHMENT_GROUP_KEY] = group+ if thread_root_id is not None:+ content["m.relates_to"] = thread_relation(thread_root_id)+ return content+++def _rendered(body: str, mentions: list[str] | None) -> str:+ """Markdown as HTML, with each mentioned id turned into a link.++ The link target is a matrix.to URL because that is what a Matrix client+ renders as a mention pill, and it is the one addressing signal with no+ plain-text equivalent — `AddressingResolver.mentions_name` looks for the+ id inside the rendered body. A transport with no pill convention of its own+ still wants the id there for exactly that reason, so the form is shared+ rather than being made Matrix-only.+ """+ html: str = markdown.markdown(body)+ for user_id in mentions or ():+ local = user_id.split(":")[0].lstrip("@")+ html = html.replace(+ f"@{local}", f'<a href="https://matrix.to/#/{user_id}">{local}</a>'+ )+ return htmldiff --git a/core/switch_core/transport/ephemeral.py b/core/switch_core/transport/ephemeral.pynew file mode 100644index 000000000..76dfeb494--- /dev/null+++ b/core/switch_core/transport/ephemeral.py@@ -0,0 +1,70 @@+"""How presence reaches the clients watching a room.++Some events are announced and never stored: runtime state today, typing if it+ever returns. Their next value replaces them, so a row in `messages` would put+something in the room's ordering that no reader is ever shown, and a delivery+cursor would faithfully replay a status that stopped being true minutes ago.+The message log is deliberately not their home.++But a Postgres transport delivers by reading rows, so dropping the write also+dropped the delivery: runtime state was captured in `agent_runtime_states` and+reached nobody, which is why an agent going busy stopped showing up on a+bridged channel.++This is the delivery, without the storage: an in-process fan-out to the+transports watching that room, carrying the event itself rather than a+position — the opposite of the notify listener, and correct for the opposite+reason. A position is right when the value is durable and the reader can go and+fetch it. Presence has nowhere to fetch from, so the announcement has to be the+value, and a missed one costs a briefly stale indicator rather than data.++**It is in-process, the same limitation `InviteBus` documents**, and it should+be lifted at the same time and in the same way. A second replica needs a+cross-process signal for both; until switch-core can run more than one, this is+no worse than the Matrix sessions it replaces.+"""++from __future__ import annotations++import asyncio+import logging+from collections.abc import Awaitable, Callable++from switch_core.transport.types import InboundCustomEvent++logger = logging.getLogger(__name__)++EphemeralHandler = Callable[[InboundCustomEvent], Awaitable[None]]+++class EphemeralBus:+ """Routes an unstored room event to whoever is watching that room."""++ def __init__(self) -> None:+ self._handlers: dict[str, set[EphemeralHandler]] = {}++ def subscribe(self, transport_room_id: str, handler: EphemeralHandler) -> None:+ self._handlers.setdefault(transport_room_id, set()).add(handler)++ def unsubscribe(self, transport_room_id: str, handler: EphemeralHandler) -> None:+ self._handlers.get(transport_room_id, set()).discard(handler)++ async def publish(self, transport_room_id: str, event: InboundCustomEvent) -> None:+ """Hand the event to every watcher, and let none of them stop another.++ A handler that raises is logged rather than propagated: this is+ presence, and failing the send of a status update because one listener+ mishandled it would turn a cosmetic problem into a real one.+ """+ for handler in list(self._handlers.get(transport_room_id, ())):+ try:+ await handler(event)+ except asyncio.CancelledError:+ raise+ except Exception:+ logger.error(+ "A watcher failed handling %s in room %s",+ event.event_type,+ transport_room_id,+ exc_info=True,+ )diff --git a/core/switch_core/transport/invites.py b/core/switch_core/transport/invites.pynew file mode 100644index 000000000..14a94c601--- /dev/null+++ b/core/switch_core/transport/invites.py@@ -0,0 +1,57 @@+"""How a client is told it has been added to a room.++Over Matrix this was an event: the admin invited a user, the user's sync loop+saw the invitation and `ClientBase.on_invite` joined. Nothing else had to know+the order things happened in, because the invitation was durable and the client+picked it up whenever it next synced.++A Postgres transport watches the rooms it knew about when it started, so a+membership written underneath it would be a room it never reads — a client+sitting in a room in silence, which is precisely the failure this stack keeps+refusing to ship. This is the missing signal, in the shape the clients already+handle: an invitation, delivered to a live client, auto-accepted by the same+code path as before.++**It is in-process, and that is a real limitation.** A client running in+another replica of switch-core would not hear it. That is the same constraint+Matrix sync sessions imposed and the reason switch-core is single-replica+today; lifting it is its own step, and until then this is no worse than what it+replaces. When nobody is listening for a user the caller writes the membership+itself, so the room is still joined the next time that client starts — the+invitation is a wake-up, never the record.+"""++from __future__ import annotations++import logging+from collections.abc import Awaitable, Callable++logger = logging.getLogger(__name__)++InviteHandler = Callable[[str], Awaitable[None]]+++class InviteBus:+ """Routes an invitation to the live transport for a user, if there is one."""++ def __init__(self) -> None:+ self._handlers: dict[str, InviteHandler] = {}++ def register(self, user_id: str, handler: InviteHandler) -> None:+ self._handlers[user_id] = handler++ def unregister(self, user_id: str) -> None:+ self._handlers.pop(user_id, None)++ async def invite(self, user_id: str, transport_room_id: str) -> bool:+ """Tell `user_id` it is in `transport_room_id`.++ Returns whether anyone was listening. False is not an error — a client+ that is not running has nothing to wake — but the caller then owns+ writing the membership, so the answer must not be ignored.+ """+ handler = self._handlers.get(user_id)+ if handler is None:+ return False+ await handler(transport_room_id)+ return Truediff --git a/core/switch_core/transport/matrix.py b/core/switch_core/transport/matrix.pynew file mode 100644index 000000000..082672222--- /dev/null+++ b/core/switch_core/transport/matrix.py@@ -0,0 +1,459 @@+"""Matrix implementation of `MessageTransport`.++This is the only module in Switch that may import matrix-nio. Everything+Matrix-shaped lives here: content dicts, `m.relates_to` threading, mxc URIs,+pagination tokens and the sync loop.+"""++from __future__ import annotations++import io+import logging+from dataclasses import dataclass+from typing import Any++from nio import (+ AsyncClient,+ DownloadError,+ InviteMemberEvent,+ JoinedRoomsError,+ LoginError,+ ProfileSetDisplayNameError,+ ReactionEvent,+ RoomGetEventError,+ RoomMemberEvent,+ RoomMessageMedia,+ RoomMessagesError,+ RoomMessageText,+ RoomSendError,+ RoomTypingError,+ SyncError,+ SyncResponse,+ UnknownEvent,+ UploadError,+)++from switch_core.attachments import ATTACHMENT_GROUP_KEY+from switch_core.transport.content import media_content, message_content+from switch_core.transport.port import TransportHandlers+from switch_core.transport.types import (+ DownloadResult,+ HistoryPage,+ InboundCustomEvent,+ InboundEvent,+ InboundMedia,+ InboundMembership,+ InboundMessage,+ MessageFormat,+ NotConnectedError,+ RoomRef,+ SendResult,+ TransportError,+ UploadResult,+)++logger = logging.getLogger(__name__)++SYNC_TIMEOUT_MS = 30000+++@dataclass(frozen=True)+class _RoomIdOnly:+ """Stands in for a room object when only the id is known.++ History and single-event fetches return events without the room they came+ from, but the converters only ever read the id.+ """++ room_id: str+++def _content(event: Any) -> dict[str, object]:+ source = getattr(event, "source", None) or {}+ content = source.get("content") or {}+ return dict(content)+++def _thread_root_of(content: dict[str, object], event_id: str) -> str | None:+ """The thread this event belongs to, or None when it is top level.++ Matrix threads are flat: an event either relates to a root or is one.+ """+ relates = content.get("m.relates_to") or {}+ if isinstance(relates, dict) and relates.get("rel_type") == "m.thread":+ root = relates.get("event_id")+ return str(root) if root else None+ return None+++def to_room_ref(room: Any) -> RoomRef:+ return RoomRef(room_id=room.room_id)+++def to_inbound_message(room: Any, event: Any) -> InboundMessage:+ content = _content(event)+ return InboundMessage(+ room_id=room.room_id,+ event_id=event.event_id,+ sender=event.sender,+ timestamp=event.server_timestamp,+ content=content,+ body=getattr(event, "body", "") or "",+ sender_name=content.get("sender_name"), # type: ignore[arg-type]+ formatted_body=getattr(event, "formatted_body", None),+ msgtype=str(content.get("msgtype") or "m.text"),+ thread_root_id=_thread_root_of(content, event.event_id),+ )+++def to_inbound_media(room: Any, event: Any) -> InboundMedia:+ content = _content(event)+ info = content.get("info") or {}+ if not isinstance(info, dict):+ info = {}+ return InboundMedia(+ room_id=room.room_id,+ event_id=event.event_id,+ sender=event.sender,+ timestamp=event.server_timestamp,+ content=content,+ body=getattr(event, "body", "") or "",+ sender_name=content.get("sender_name"), # type: ignore[arg-type]+ uri=str(getattr(event, "url", "") or ""),+ filename=content.get("filename") or getattr(event, "body", None), # type: ignore[arg-type]+ mimetype=info.get("mimetype"),+ size=info.get("size"),+ msgtype=str(content.get("msgtype") or "m.file"),+ thread_root_id=_thread_root_of(content, event.event_id),+ group=content.get(ATTACHMENT_GROUP_KEY), # type: ignore[arg-type]+ )+++def to_inbound_membership(room: Any, event: Any) -> InboundMembership:+ content = _content(event)+ return InboundMembership(+ room_id=room.room_id,+ event_id=getattr(event, "event_id", ""),+ sender=getattr(event, "sender", ""),+ timestamp=getattr(event, "server_timestamp", 0),+ content=content,+ state_key=getattr(event, "state_key", ""),+ membership=getattr(event, "membership", ""),+ prev_membership=getattr(event, "prev_membership", None),+ display_name=content.get("displayname"), # type: ignore[arg-type]+ )+++def to_inbound_custom(room: Any, event: Any) -> InboundCustomEvent:+ content = _content(event)+ return InboundCustomEvent(+ room_id=room.room_id,+ event_id=event.event_id,+ sender=event.sender,+ timestamp=getattr(event, "server_timestamp", 0),+ content=content,+ event_type=event.type,+ thread_root_id=_thread_root_of(content, event.event_id),+ )+++def to_inbound(room: Any, event: Any) -> InboundEvent:+ """Convert a timeline event to the DTO matching its kind."""+ if isinstance(event, RoomMessageMedia):+ return to_inbound_media(room, event)+ if isinstance(event, RoomMessageText):+ return to_inbound_message(room, event)+ if isinstance(event, RoomMemberEvent):+ return to_inbound_membership(room, event)+ if isinstance(event, UnknownEvent):+ return to_inbound_custom(room, event)+ return to_inbound_event(room, event)+++def to_inbound_event(room: Any, event: Any) -> InboundEvent:+ return InboundEvent(+ room_id=room.room_id,+ event_id=getattr(event, "event_id", ""),+ sender=getattr(event, "sender", ""),+ timestamp=getattr(event, "server_timestamp", 0),+ content=_content(event),+ )+++def _carries_durable_events(response: SyncResponse) -> bool:+ """Whether a sync response holds anything a restart would need to replay.++ Timeline events, room state and invites are dispatched to handlers, so the+ cursor must move past them durably. Presence, typing, receipts and account+ data are not — they only advance the token.+ """+ if response.rooms.invite or response.to_device_events:+ return True+ return any(+ room.timeline.events or room.state+ for room in (*response.rooms.join.values(), *response.rooms.leave.values())+ )+++class MatrixTransport:+ """Carries Switch messages over a Matrix homeserver."""++ def __init__(+ self,+ *,+ server_url: str,+ user_id: str,+ password: str,+ device_id: str | None = None,+ access_token: str | None = None,+ client: AsyncClient | None = None,+ ) -> None:+ self.server_url = server_url+ self.user_id = user_id+ self.password = password+ self.device_id = device_id+ self.access_token = access_token+ self._client: AsyncClient | None = client+ self._handlers = TransportHandlers()++ # ── Session ───────────────────────────────────────────────────────────────++ @property+ def raw_client(self) -> AsyncClient:+ """The underlying nio client.++ An escape hatch for call sites not yet expressed on the port. New code+ must use the port; this exists so the migration can proceed in steps.+ """+ if self._client is None:+ raise NotConnectedError(+ f"Transport for {self.user_id} is not connected — call connect() first"+ )+ return self._client++ @property+ def session_state(self) -> dict[str, str | None]:+ return {"access_token": self.access_token, "device_id": self.device_id}++ async def connect(self) -> None:+ if self._client is None:+ self._client = AsyncClient(self.server_url, self.user_id)++ if self.access_token and self.device_id:+ self._client.access_token = self.access_token+ self._client.device_id = self.device_id+ logger.info("Transport %s restored session from stored token", self.user_id)+ return++ if not self.password:+ raise TransportError(f"No credentials available for {self.user_id}")++ resp = await self._client.login(self.password)+ if isinstance(resp, LoginError):+ raise TransportError(f"Login failed for {self.user_id}: {resp.message}")+ self.device_id = resp.device_id+ self.access_token = self._client.access_token+ logger.info("Transport %s authenticated via password", self.user_id)++ async def close(self) -> None:+ if self._client is not None:+ await self._client.close()++ async def relogin(self) -> None:+ """Re-authenticate an existing connection after a session failure."""+ if not self.password:+ return+ resp = await self.raw_client.login(self.password)+ if isinstance(resp, LoginError):+ raise TransportError(f"Re-login failed for {self.user_id}: {resp.message}")+ self.device_id = resp.device_id+ self.access_token = self.raw_client.access_token++ def register_handlers(self, handlers: TransportHandlers) -> None:+ self._handlers = handlers+ client = self.raw_client++ def bind(handler: Any, convert: Any, kind: Any) -> None:+ if handler is None:+ return++ async def _cb(room: Any, event: Any) -> None:+ await handler(to_room_ref(room), convert(room, event))++ client.add_event_callback(_cb, kind)++ bind(handlers.on_message, to_inbound_message, RoomMessageText)+ # RoomMessageMedia is the base of RoomMessageImage / RoomMessageFile, so+ # one callback covers every media msgtype.+ bind(handlers.on_media, to_inbound_media, RoomMessageMedia)+ bind(handlers.on_reaction, to_inbound_event, ReactionEvent)+ bind(handlers.on_member_event, to_inbound_membership, RoomMemberEvent)+ bind(handlers.on_custom_event, to_inbound_custom, UnknownEvent)+ bind(handlers.on_invite, to_inbound_membership, InviteMemberEvent)++ if handlers.on_sync is not None:+ on_sync = handlers.on_sync++ async def _sync_cb(response: SyncResponse) -> None:+ await on_sync(response.next_batch, _carries_durable_events(response))++ client.add_response_callback(_sync_cb, SyncResponse) # type: ignore[arg-type]++ if handlers.on_sync_error is not None:+ on_sync_error = handlers.on_sync_error++ async def _sync_error_cb(response: SyncError) -> None:+ await on_sync_error(response.message)++ client.add_response_callback(_sync_error_cb, SyncError) # type: ignore[arg-type]++ async def receive_forever(self, *, since: str | None) -> None:+ await self.raw_client.sync_forever(timeout=SYNC_TIMEOUT_MS, since=since)++ # ── Outbound ──────────────────────────────────────────────────────────────++ async def send_message(+ self,+ room_id: str,+ body: str,+ *,+ sender_name: str,+ format: MessageFormat = "text",+ mentions: list[str] | None = None,+ thread_root_id: str | None = None,+ extra_content: dict[str, object] | None = None,+ ) -> SendResult:+ content = message_content(+ body,+ sender_name=sender_name,+ format=format,+ mentions=mentions,+ thread_root_id=thread_root_id,+ extra_content=extra_content,+ )+ return await self._room_send(room_id, "m.room.message", content)++ async def send_event(+ self,+ room_id: str,+ event_type: str,+ content: dict[str, object],+ ) -> SendResult:+ return await self._room_send(room_id, event_type, content)++ async def send_media(+ self,+ room_id: str,+ uri: str,+ filename: str,+ mimetype: str,+ size: int,+ *,+ sender_name: str,+ msgtype: str,+ caption: str | None = None,+ thread_root_id: str | None = None,+ group: dict[str, object] | None = None,+ ) -> SendResult:+ content = media_content(+ uri,+ filename,+ mimetype,+ size,+ sender_name=sender_name,+ msgtype=msgtype,+ caption=caption,+ thread_root_id=thread_root_id,+ group=group,+ )+ return await self._room_send(room_id, "m.room.message", content)++ async def _room_send(+ self, room_id: str, event_type: str, content: dict[str, object]+ ) -> SendResult:+ resp = await self.raw_client.room_send(room_id, event_type, content)+ if isinstance(resp, RoomSendError):+ raise TransportError(+ f"Failed to send {event_type} to {room_id}: {resp.message}"+ )+ return SendResult(+ event_id=resp.event_id, event_type=event_type, content=content+ )++ async def upload_media(+ self, data: bytes, content_type: str, filename: str+ ) -> UploadResult:+ resp, _ = await self.raw_client.upload(+ data_provider=io.BytesIO(data),+ content_type=content_type,+ filename=filename,+ filesize=len(data),+ )+ if isinstance(resp, UploadError):+ raise TransportError(+ f"Failed to upload media '{filename}' to Matrix: {resp.message}"+ )+ return UploadResult(uri=resp.content_uri)++ async def download_media(self, uri: str) -> DownloadResult:+ resp = await self.raw_client.download(mxc=uri)+ if isinstance(resp, DownloadError):+ raise TransportError(f"Failed to download {uri}: {resp.message}")+ return DownloadResult(+ body=resp.body,+ content_type=getattr(resp, "content_type", None),+ filename=getattr(resp, "filename", None),+ )++ async def set_typing(self, room_id: str, is_typing: bool) -> None:+ logger.debug(+ "Setting typing %s in room %s for %s", is_typing, room_id, self.user_id+ )+ resp = await self.raw_client.room_typing(room_id, is_typing)+ if isinstance(resp, RoomTypingError):+ logger.error("Failed to set typing in %s: %s", room_id, resp.message)++ # ── History ───────────────────────────────────────────────────────────────++ async def get_event(self, room_id: str, event_id: str) -> InboundEvent | None:+ resp = await self.raw_client.room_get_event(room_id, event_id)+ if isinstance(resp, RoomGetEventError):+ return None+ return to_inbound(_RoomIdOnly(room_id), resp.event)++ async def read_history(+ self, room_id: str, *, start: str | None, limit: int+ ) -> HistoryPage:+ resp = await self.raw_client.room_messages(room_id, start=start, limit=limit)+ if isinstance(resp, RoomMessagesError):+ raise TransportError(f"Failed to read history in {room_id}: {resp.message}")+ room = _RoomIdOnly(room_id)+ return HistoryPage(+ events=[to_inbound(room, event) for event in resp.chunk],+ next_token=resp.end,+ )++ # ── Rooms ─────────────────────────────────────────────────────────────────++ async def join_room(self, room_id: str) -> bool:+ resp = await self.raw_client.join(room_id)+ if hasattr(resp, "room_id"):+ return True+ logger.error("Transport %s failed to join %s: %s", self.user_id, room_id, resp)+ return False++ async def joined_rooms(self) -> list[str]:+ resp = await self.raw_client.joined_rooms()+ if isinstance(resp, JoinedRoomsError):+ logger.error(+ "Failed to list joined rooms for %s: %s", self.user_id, resp.message+ )+ return []+ return list(resp.rooms)++ async def set_display_name(self, display_name: str) -> None:+ resp = await self.raw_client.set_displayname(display_name)+ if isinstance(resp, ProfileSetDisplayNameError):+ raise TransportError(+ f"Could not set the display name of {self.user_id}: {resp}"+ )diff --git a/core/switch_core/transport/port.py b/core/switch_core/transport/port.pynew file mode 100644index 000000000..cd4e866be--- /dev/null+++ b/core/switch_core/transport/port.py@@ -0,0 +1,177 @@+"""The message-transport port.++`MessageTransport` is the whole contract between Switch and whatever carries+its messages. Implementations live beside this module; nothing outside the+`switch_core.transport` package may import a transport library directly.++The contract is deliberately narrow and derived from what callers actually do:+send a message, send a typed event, move media, read history back, and receive+events. Operations raise `TransportError` on failure instead of returning an+error object.+"""++from __future__ import annotations++from collections.abc import Awaitable, Callable+from dataclasses import dataclass+from typing import Any, Protocol, runtime_checkable++from switch_core.transport.types import (+ DownloadResult,+ HistoryPage,+ MessageFormat,+ SendResult,+ UploadResult,+)++Handler = Callable[[Any, Any], Awaitable[None]]+# (cursor, durable). `durable` says whether the batch carried anything a+# restart would have to replay, so the client can decide how urgently to+# persist the cursor. The transport decides it: only it can see what the batch+# held, and saying so as a bool keeps its event classes out of the client.+SyncHandler = Callable[[str, bool], Awaitable[None]]+SyncErrorHandler = Callable[[str], Awaitable[None]]+++@dataclass+class TransportHandlers:+ """Inbound callbacks a client registers with its transport.++ Each is optional so a client only pays for the events it cares about. The+ transport decides how to bind them; the client never names an event class.+ """++ on_message: Handler | None = None+ on_media: Handler | None = None+ on_reaction: Handler | None = None+ on_member_event: Handler | None = None+ on_custom_event: Handler | None = None+ on_invite: Handler | None = None+ on_sync: SyncHandler | None = None+ on_sync_error: SyncErrorHandler | None = None+++@runtime_checkable+class MessageTransport(Protocol):+ """Carries messages between Switch and its participants."""++ # ── Session ───────────────────────────────────────────────────────────────++ @property+ def session_state(self) -> dict[str, str | None]:+ """Opaque credentials to persist so a restart can resume.++ The shape is transport-defined; callers store and hand it back+ unread.+ """+ ...++ async def connect(self) -> None:+ """Authenticate, restoring a stored session when one is available."""+ ...++ async def close(self) -> None:+ """Release the connection. Safe to call when never connected."""+ ...++ async def relogin(self) -> None:+ """Re-authenticate after the session was rejected mid-stream."""+ ...++ def register_handlers(self, handlers: TransportHandlers) -> None:+ """Bind inbound callbacks. Call before `receive_forever`."""+ ...++ async def receive_forever(self, *, since: str | None) -> None:+ """Deliver inbound events to the registered handlers until closed.++ `since` resumes from a cursor previously reported to `on_sync`.+ """+ ...++ # ── Outbound ──────────────────────────────────────────────────────────────++ async def send_message(+ self,+ room_id: str,+ body: str,+ *,+ sender_name: str,+ format: MessageFormat = "text",+ mentions: list[str] | None = None,+ thread_root_id: str | None = None,+ extra_content: dict[str, object] | None = None,+ ) -> SendResult:+ """Post a text message. Raises `TransportError` if it is not accepted."""+ ...++ async def send_event(+ self,+ room_id: str,+ event_type: str,+ content: dict[str, object],+ ) -> SendResult:+ """Post a typed non-message event, e.g. a `com.switch.*` payload."""+ ...++ async def send_media(+ self,+ room_id: str,+ uri: str,+ filename: str,+ mimetype: str,+ size: int,+ *,+ sender_name: str,+ msgtype: str,+ caption: str | None = None,+ thread_root_id: str | None = None,+ group: dict[str, object] | None = None,+ ) -> SendResult:+ """Post an event pointing at an already-uploaded `uri`.++ `group` marks this as one part of a multi-attachment message —+ `{"id": ..., "index": i, "total": n}` — for transports that cannot+ carry several files on one event.+ """+ ...++ async def upload_media(+ self, data: bytes, content_type: str, filename: str+ ) -> UploadResult:+ """Store bytes and return the handle to reference them by."""+ ...++ async def download_media(self, uri: str) -> DownloadResult:+ """Retrieve bytes for a handle returned by `upload_media`."""+ ...++ async def set_typing(self, room_id: str, is_typing: bool) -> None:+ """Signal composing state. Best-effort: never raises."""+ ...++ # ── History ───────────────────────────────────────────────────────────────++ async def get_event(self, room_id: str, event_id: str) -> Any | None:+ """Fetch one event by id, or None when it cannot be retrieved."""+ ...++ async def read_history(+ self, room_id: str, *, start: str | None, limit: int+ ) -> HistoryPage:+ """Read one page of history backwards from `start`."""+ ...++ # ── Rooms ─────────────────────────────────────────────────────────────────++ async def join_room(self, room_id: str) -> bool:+ """Join a room. Returns whether the join was accepted."""+ ...++ async def joined_rooms(self) -> list[str]:+ """Rooms this connection is currently a member of."""+ ...++ async def set_display_name(self, display_name: str) -> None:+ """Change the name this connection shows under."""+ ...diff --git a/core/switch_core/transport/postgres.py b/core/switch_core/transport/postgres.pynew file mode 100644index 000000000..10313f6c3--- /dev/null+++ b/core/switch_core/transport/postgres.py@@ -0,0 +1,739 @@+"""Postgres implementation of `MessageTransport`.++The homeserver's remaining job is to carry an event from the client that sent+it to the clients that should see it, and to remember it in between. A table+does all three, and Switch already writes that table: every send is recorded+into `messages` today, beside the send, so the rows exist and have been+verified against the bus.++This turns that parallel record into the thing itself. **The write is the+send.** There is no second store to agree with, which is why the reconciler+this stack built has no work left once the flip happens — it exists to compare+two records of the same event, and there is only one.++Three consequences worth stating up front:++- **A send now fails when the database does.** The recorder deliberately could+ not fail a send, because a row was a nice-to-have next to a delivered+ message. Here the row *is* the delivery, so there is nothing left to protect:+ a write that fails is a message that was not sent, and the caller must hear+ about it.+- **Every durable event gets a row, not only the conversation.** The bus+ carried commands and task events too, and they have to reach their handlers.+ `recorded_types` therefore stops meaning "what is written" and starts meaning+ "what a reader is shown" — a projection applied on the way out. The one+ category with no row is the genuinely ephemeral: presence-like state whose+ next value replaces it, which is announced and never stored.+- **Ids are opaque, and these are not `$event` ids.** Nothing in Switch parses+ one; the columns holding them are already named `transport_event_id`.++History is the one method left unimplemented, and deliberately: the read path+already queries these rows directly, and the only callers left are the walkers+that exist to compare a bus against them.+"""++from __future__ import annotations++import asyncio+import logging+import uuid+from datetime import UTC, datetime+from typing import TYPE_CHECKING, Any++from switch_core.attachments import ATTACHMENT_GROUP_KEY+from switch_core.db.models import ClientRoom, MediaBlob, Message, MessageAttachment+from switch_core.messages.recorded_types import EPHEMERAL+from switch_core.messages.row import attachments_in, text_field, thread_root_of+from switch_core.transport.content import media_content, message_content+from switch_core.transport.ephemeral import EphemeralBus+from switch_core.transport.invites import InviteBus+from switch_core.transport.port import Handler, TransportHandlers+from switch_core.transport.types import (+ DownloadResult,+ HistoryPage,+ InboundCustomEvent,+ InboundEvent,+ InboundMedia,+ InboundMembership,+ InboundMessage,+ MessageFormat,+ RoomRef,+ SendResult,+ TransportError,+ UploadResult,+)++if TYPE_CHECKING:+ from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker++ from switch_core.db.stores.media_store import MediaStore+ from switch_core.db.stores.message_store import MessageStore+ from switch_core.db.stores.room_store import RoomStore+ from switch_core.messages.notify import MessageListener++logger = logging.getLogger(__name__)++# How many rows one wake-up reads at a time. A page rather than everything+# outstanding, so a room that moved a long way while a handler was busy is+# delivered in bounded steps instead of one unbounded read.+_DELIVERY_PAGE = 200++MEMBERSHIP_EVENT_TYPE = "m.room.member"+++def new_event_id() -> str:+ """A fresh event id.++ Prefixed so that a row's origin is readable at a glance during the window+ where a room holds both these and ids minted by the old bus. The prefix is+ decoration for humans — no code may branch on it.+ """+ return f"sw_{uuid.uuid4().hex}"+++class PostgresTransport:+ """Carries a room's events in the `messages` table.++ One instance per client, as with the Matrix transport: it sends as that+ client and, once receiving lands, delivers to that client's handlers.+ """++ def __init__(+ self,+ *,+ user_id: str,+ client_id: str,+ display_name: str,+ session_factory: async_sessionmaker[AsyncSession],+ room_store: RoomStore,+ message_store: MessageStore,+ media_store: MediaStore,+ listener: MessageListener,+ invites: InviteBus,+ ephemeral: EphemeralBus,+ ) -> None:+ self.user_id = user_id+ self.client_id = client_id+ self.display_name = display_name+ self._session_factory = session_factory+ self._room_store = room_store+ self._message_store = message_store+ self._media_store = media_store+ self._listener = listener+ self._invites = invites+ self._ephemeral = ephemeral+ self._handlers = TransportHandlers()+ # Per-room delivery position, and the transport-side id to hand back+ # to a handler. Both are keyed by the Switch room id, which is what+ # the listener announces.+ self._cursors: dict[str, int] = {}+ self._watching: dict[str, str] = {}+ self._receiving = False+ self._closed = asyncio.Event()+ # Rooms this client has been told moved but has not read yet, and the+ # signal its delivery loop waits on. A set because a room that moved+ # twice while the loop was busy is still one read.+ self._pending: set[str] = set()+ self._wake = asyncio.Event()+ self._delivering = False+ # A room's transport id never changes, so this only grows and never+ # goes stale.+ self._room_ids: dict[str, str] = {}++ # ── Session ───────────────────────────────────────────────────────────────++ @property+ def session_state(self) -> dict[str, str | None]:+ """Nothing to resume.++ The Matrix transport persisted an access token and a device id because+ logging in again cost a round trip and a new device. Here the client's+ identity is a row it already owns, so there is no credential to carry+ across a restart. The empty dict is the honest answer, and callers+ store it unread.+ """+ return {}++ async def connect(self) -> None:+ """Nothing to authenticate: the caller already knows who it is."""++ async def close(self) -> None:+ """Stop receiving. Sessions are borrowed per operation, so that is all+ there is to release."""+ self._closed.set()++ async def relogin(self) -> None:+ """Never called: there is no session to be rejected."""++ def register_handlers(self, handlers: TransportHandlers) -> None:+ self._handlers = handlers++ async def receive_forever(self, *, since: str | None) -> None:+ """Deliver every row written to this client's rooms from now on.++ `since` is ignored, and that is the behaviour to keep rather than an+ omission. A Matrix client resumed from its stored sync token and then+ threw away everything older than the process (`ClientBase._should_ignore`),+ so what was actually delivered on a restart was "whatever happened+ while I was up". Starting each room at its current head says the same+ thing without the cursor that lied about it. What an agent missed+ while it was away is a delivery-cursor question, and delivery cursors+ are a layer above this one.+ """+ rooms = await self.joined_rooms()+ if not rooms:+ logger.error(+ "Client %s is receiving but is a member of no room: it will "+ "hear nothing until something adds it to one. Under Matrix "+ "membership lived on the homeserver; here it is the "+ "client_rooms table, so a client whose rows were never "+ "written is silent rather than broken",+ self.user_id,+ )+ delivery = asyncio.create_task(self._deliver_forever())+ for transport_room_id in rooms:+ await self._watch(transport_room_id)+ self._receiving = True+ self._invites.register(self.user_id, self._on_invited)+ try:+ await self._closed.wait()+ finally:+ self._receiving = False+ self._invites.unregister(self.user_id)+ self._unwatch_all()+ delivery.cancel()++ async def _deliver_forever(self) -> None:+ """This client's own delivery loop: its rooms, one at a time.++ The listener fans out to every subscriber from a single task, so+ anything a waker awaits is awaited by every other client's delivery+ too — and a waker awaits its handler, which for a bridge is an HTTP+ call to Slack that can sit in a rate limit for seconds. Doing the work+ here instead means a stalled bridge stalls itself.++ Serial within the client, deliberately. Two concurrent runs for one+ room would both read the same cursor and deliver the same rows twice,+ and a redelivered message is indistinguishable to a reader from a new+ one. Overlapping wake-ups collapse into one more pass instead, which+ also bounds this client to one outstanding read.+ """+ while True:+ await self._wake.wait()+ self._wake.clear()+ rooms = list(self._pending)+ self._pending.clear()+ self._delivering = True+ try:+ for room_id in rooms:+ try:+ await self._drain_room(room_id)+ except asyncio.CancelledError:+ raise+ except Exception:+ # One room's failure is not the other rooms' problem,+ # and this loop is the only delivery this client has.+ logger.error(+ "Delivery failed for client %s in room %s",+ self.user_id,+ room_id,+ exc_info=True,+ )+ finally:+ self._delivering = False++ async def _on_invited(self, transport_room_id: str) -> None:+ """Someone added this client to a room while it was running.++ Handed to `on_invite` rather than joined here, because auto-accepting+ is the client's decision and it already has one — the same one it made+ when the invitation arrived over sync.+ """+ handler = self._handlers.on_invite+ if handler is None:+ return+ await handler(+ RoomRef(room_id=transport_room_id),+ InboundMembership(+ room_id=transport_room_id,+ event_id=new_event_id(),+ sender=self.user_id,+ timestamp=_now_ms(),+ state_key=self.user_id,+ membership="invite",+ display_name=self.display_name,+ ),+ )++ async def _watch(+ self, transport_room_id: str, *, from_seq: int | None = None+ ) -> None:+ """Start delivering a room, from its head or from a given position.++ `from_seq` exists so a client can hear its own arrival. Over Matrix a+ join came back down the joining client's own connection — the+ homeserver turned it into an event and delivered it to everyone,+ including the person it was about — and code downstream learned it had+ joined by being told. Writing the row and then watching from the head+ steps over the client's own footprint: the room hears the arrival and+ the arriving client does not.++ Restoring the loop-back rather than dispatching the one handler that+ noticed keeps every guard downstream in play, and covers whatever else+ depended 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)+ )+ self._watching[room_id] = transport_room_id+ self._listener.subscribe(room_id, self._on_room_advanced)+ self._ephemeral.subscribe(transport_room_id, self._on_ephemeral)+ if from_seq is not None:+ # The announcement for anything already written went out before+ # this subscription existed, so nothing will wake the loop for it.+ self._pending.add(room_id)+ self._wake.set()++ def _unwatch_all(self) -> None:+ for room_id, transport_room_id in self._watching.items():+ self._listener.unsubscribe(room_id, self._on_room_advanced)+ self._ephemeral.unsubscribe(transport_room_id, self._on_ephemeral)+ self._watching.clear()+ self._cursors.clear()++ async def _on_ephemeral(self, event: InboundCustomEvent) -> None:+ """An unstored event in a room this client watches.++ It arrives already assembled, unlike a row: there is nothing to read+ back, which is the whole difference between announcing a position and+ announcing a value.+ """+ handler = self._handlers.on_custom_event+ if handler is None:+ return+ await handler(RoomRef(room_id=event.room_id), event)++ async def _on_room_advanced(self, room_id: str) -> None:+ """The listener's waker: note the room and return.++ It must not deliver. The listener fans out from one task, so time+ spent here is time no other client in the process is being delivered+ to.+ """+ if room_id not in self._watching:+ return+ self._pending.add(room_id)+ self._wake.set()++ async def _drain_room(self, room_id: str) -> None:+ """Read what this client has not seen in one room, and hand it over.++ Driven by this client's own loop, which promises only that the room+ moved — and never that it moved once. The+ cursor is this transport's own, so a coalesced announcement, a+ duplicate, or a wake-up after a reconnect all reduce to the same+ thing: read from where I was, and advance.++ The cursor advances per row rather than at the end, so a handler that+ raises does not cost the rows already delivered — the failure belongs+ to one event, and redelivering its neighbours would be worse than+ dropping it.+ """+ transport_room_id = self._watching.get(room_id)+ if transport_room_id is None:+ return+ while True:+ async with self._session_factory() as session:+ rows = await self._message_store.list_for_room(+ session,+ room_id,+ after_seq=self._cursors[room_id],+ limit=_DELIVERY_PAGE,+ )+ attachments = await self._message_store.attachments_for(+ session, [row.id for row in rows]+ )+ if not rows:+ return+ for row in rows:+ self._cursors[room_id] = row.seq+ await self._deliver(transport_room_id, row, attachments.get(row.id, []))+ if len(rows) < _DELIVERY_PAGE:+ return++ async def _deliver(+ self,+ transport_room_id: str,+ row: Message,+ attachments: list[MessageAttachment],+ ) -> None:+ room = RoomRef(room_id=transport_room_id)+ event = to_inbound(row, attachments, transport_room_id=transport_room_id)+ handler = self._handler_for(event)+ if handler is None:+ return+ await handler(room, event)++ def _handler_for(self, event: InboundEvent) -> Handler | None:+ if isinstance(event, InboundMedia):+ return self._handlers.on_media+ if isinstance(event, InboundMembership):+ return self._handlers.on_member_event+ if isinstance(event, InboundCustomEvent):+ return self._handlers.on_custom_event+ return self._handlers.on_message++ # ── Outbound ──────────────────────────────────────────────────────────────++ async def send_message(+ self,+ room_id: str,+ body: str,+ *,+ sender_name: str,+ format: MessageFormat = "text",+ mentions: list[str] | None = None,+ thread_root_id: str | None = None,+ extra_content: dict[str, object] | None = None,+ ) -> SendResult:+ content = message_content(+ body,+ sender_name=sender_name,+ format=format,+ mentions=mentions,+ thread_root_id=thread_root_id,+ extra_content=extra_content,+ )+ return await self._send(room_id, "m.room.message", content, sender_name)++ async def send_event(+ self,+ room_id: str,+ event_type: str,+ content: dict[str, object],+ ) -> SendResult:+ return await self._send(room_id, event_type, content, self.display_name)++ async def send_media(+ self,+ room_id: str,+ uri: str,+ filename: str,+ mimetype: str,+ size: int,+ *,+ sender_name: str,+ msgtype: str,+ caption: str | None = None,+ thread_root_id: str | None = None,+ group: dict[str, object] | None = None,+ ) -> SendResult:+ content = media_content(+ uri,+ filename,+ mimetype,+ size,+ sender_name=sender_name,+ msgtype=msgtype,+ caption=caption,+ thread_root_id=thread_root_id,+ group=group,+ )+ return await self._send(room_id, "m.room.message", content, sender_name)++ async def _send(+ self,+ transport_room_id: str,+ event_type: str,+ content: dict[str, object],+ sender_name: str,+ ) -> SendResult:+ """Write the event, which is what sending it means here.++ The commit is the acceptance: the trigger on `messages` announces the+ row as part of it, so no subscriber can be woken for a row that a later+ rollback removes.+ """+ result = SendResult(+ event_id=new_event_id(), event_type=event_type, content=content+ )+ if event_type in EPHEMERAL:+ # Presence-like state, replaced by its own next value. Storing it+ # would put a row in the room's order for something no reader is+ # ever shown, so it is delivered live instead of written: the+ # announcement carries the value, because there is nowhere for a+ # reader to go and fetch it.+ await self._ephemeral.publish(+ transport_room_id,+ InboundCustomEvent(+ room_id=transport_room_id,+ event_id=result.event_id,+ sender=self.user_id,+ timestamp=_now_ms(),+ content=content,+ event_type=event_type,+ ),+ )+ return result++ async with self._session_factory() as session:+ room_id = await self._resolve_room(session, transport_room_id)+ message = Message(+ room_id=room_id,+ transport_event_id=result.event_id,+ sender_matrix_id=self.user_id,+ sender_client_id=self.client_id,+ sender_name=sender_name,+ event_type=event_type,+ msgtype=text_field(content.get("msgtype")),+ body=text_field(content.get("body")),+ formatted_body=text_field(content.get("formatted_body")),+ thread_root_event_id=thread_root_of(content),+ content=content,+ )+ await self._message_store.create(session, message, attachments_in(content))+ await session.commit()+ return result++ async def set_typing(self, room_id: str, is_typing: bool) -> None:+ """Not carried. Composing state is presence, and nothing consumes it."""++ async def upload_media(+ self, data: bytes, content_type: str, filename: str+ ) -> UploadResult:+ """Store the bytes and return the handle the message will carry.++ The handle is a key and nothing more. Callers already treat it as+ opaque — it crosses the agent protocol as `mxc` and comes back as a+ query parameter — so what is behind it can become object storage later+ without the protocol noticing.+ """+ uri = f"switch-media://{uuid.uuid4().hex}"+ async with self._session_factory() as session:+ await self._media_store.put(+ session,+ MediaBlob(+ uri=uri,+ content_type=content_type,+ filename=filename,+ size=len(data),+ data=data,+ ),+ )+ await session.commit()+ return UploadResult(uri=uri)++ async def download_media(self, uri: str) -> DownloadResult:+ """The bytes for a handle.++ A handle with nothing behind it raises rather than returning empty+ bytes: an attachment the sender was told had been stored and a reader+ gets back as a zero-byte file is the worst of the available answers.+ """+ async with self._session_factory() as session:+ blob = await self._media_store.get(session, uri)+ if blob is None:+ raise TransportError(f"No media stored under {uri}")+ return DownloadResult(+ body=blob.data,+ content_type=blob.content_type,+ filename=blob.filename,+ )++ # ── History ───────────────────────────────────────────────────────────────++ async def get_event(self, room_id: str, event_id: str) -> Any | None:+ """One event by id, or None.++ 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)+ rows = await self._message_store.list_by_transport_event_ids(+ session, switch_room_id, [event_id]+ )+ return rows[0] if rows else None++ async def read_history(+ self, room_id: str, *, start: str | None, limit: int+ ) -> HistoryPage:+ raise NotImplementedError(+ "PostgresTransport does not serve history: the read path already "+ "queries `messages` directly, and the history walkers that use "+ "this method exist to compare the bus against those same rows."+ )++ # ── Rooms ─────────────────────────────────────────────────────────────────++ async def join_room(self, room_id: str) -> bool:+ """Membership is a row, and so is the arrival that announces it.++ Over Matrix these were one thing: the homeserver turned a join into an+ `m.room.member` event every other member saw, and Switch recorded that+ event separately so history could explain who appeared. Here the write+ does both jobs at once, which removes the case the recorder had to+ guard against — an arrival that happened but was never written.++ Returns True for an existing membership as well as a new one: the+ caller asked to be in the room, and it is.++ Watching is decided separately from the row, and that split is the+ point. Membership and subscription used to be one fact — the+ homeserver's join *was* what a sync loop delivered — but a row can now+ be written by something other than this client, and a client that+ returned early on finding one would be a member of a room it never+ reads, with no later join able to repair it. So the row is written+ once and the subscription is taken whenever it is missing.+ """+ async with self._session_factory() as session:+ switch_room_id = await self._resolve_room(session, room_id)+ existing = await session.get(+ ClientRoom, {"client_id": self.client_id, "room_id": switch_room_id}+ )+ if existing is not None:+ if self._receiving:+ await self._watch(room_id)+ return True+ await self._room_store.add_client(session, self.client_id, switch_room_id)+ arrival = Message(+ room_id=switch_room_id,+ transport_event_id=new_event_id(),+ sender_matrix_id=self.user_id,+ sender_client_id=self.client_id,+ sender_name=self.display_name,+ event_type=MEMBERSHIP_EVENT_TYPE,+ msgtype=None,+ body=None,+ formatted_body=None,+ thread_root_event_id=None,+ # No rendered sentence: how an arrival reads is the reader's to+ # phrase, and freezing today's wording into every row is not+ # something a later change can take back.+ content={"membership": "join", "displayname": self.display_name},+ )+ await self._message_store.create(session, arrival, [])+ await session.commit()+ arrival_seq = arrival.seq+ if self._receiving:+ # From just before the arrival, so this client reads its own join+ # the way every other member does.+ await self._watch(room_id, from_seq=arrival_seq - 1)+ return True++ async def joined_rooms(self) -> list[str]:+ """The transport-side ids of this client's rooms."""+ async with 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]++ async def set_display_name(self, display_name: str) -> None:+ """Held on the client row, which is where every reader already looks."""+ self.display_name = display_name++ # ── Internals ─────────────────────────────────────────────────────────────++ async def _resolve_room(self, session: AsyncSession, transport_room_id: str) -> str:+ cached = self._room_ids.get(transport_room_id)+ if cached is not None:+ return cached+ room = await self._room_store.get_by_matrix_room_id(session, transport_room_id)+ if room is None:+ raise TransportError(f"{transport_room_id} is not a Switch room")+ self._room_ids[transport_room_id] = room.id+ return room.id+++def to_inbound(+ row: Message,+ attachments: list[MessageAttachment],+ *,+ transport_room_id: str,+) -> InboundEvent:+ """One stored row as the event a handler expects.++ Which of the four inbound shapes a row becomes is read off the row itself,+ the same way the Matrix transport reads it off the event class: an+ arrival, a file, a `com.switch.*` payload, or a message. The row keeps the+ whole content dict, so nothing is reconstructed here that was not sent.+ """+ content = dict(row.content)+ room_id = transport_room_id+ event_id = row.transport_event_id+ sender = row.sender_matrix_id+ timestamp = _epoch_ms(row.sent_at)++ if row.event_type == MEMBERSHIP_EVENT_TYPE:+ return InboundMembership(+ room_id=room_id,+ event_id=event_id,+ sender=sender,+ timestamp=timestamp,+ content=content,+ state_key=row.sender_matrix_id,+ membership=text_field(content.get("membership")) or "join",+ # Only an arrival is ever written, so there is no previous state+ # to read back — and a row that carries one is honoured rather+ # than second-guessed.+ prev_membership=text_field(content.get("prev_membership")),+ display_name=row.sender_name,+ )++ if row.event_type != "m.room.message":+ return InboundCustomEvent(+ room_id=room_id,+ event_id=event_id,+ sender=sender,+ timestamp=timestamp,+ content=content,+ event_type=row.event_type,+ thread_root_id=row.thread_root_event_id,+ )++ if not attachments:+ return InboundMessage(+ room_id=room_id,+ event_id=event_id,+ sender=sender,+ timestamp=timestamp,+ content=content,+ body=row.body or "",+ sender_name=row.sender_name,+ formatted_body=row.formatted_body,+ msgtype=row.msgtype or "m.text",+ thread_root_id=row.thread_root_event_id,+ )++ file = attachments[0]+ group = content.get(ATTACHMENT_GROUP_KEY)+ return InboundMedia(+ room_id=room_id,+ event_id=event_id,+ sender=sender,+ timestamp=timestamp,+ content=content,+ body=row.body or "",+ sender_name=row.sender_name,+ formatted_body=row.formatted_body,+ msgtype=row.msgtype or "m.file",+ thread_root_id=row.thread_root_event_id,+ uri=file.uri,+ filename=file.filename,+ mimetype=file.mimetype,+ size=file.size,+ group=group if isinstance(group, dict) else None,+ )+++def _now_ms() -> int:+ return int(datetime.now(UTC).timestamp() * 1000)+++def _epoch_ms(sent_at: Any) -> int:+ return int(sent_at.timestamp() * 1000)diff --git a/core/switch_core/transport/types.py b/core/switch_core/transport/types.pynew file mode 100644index 000000000..1e934f332--- /dev/null+++ b/core/switch_core/transport/types.py@@ -0,0 +1,150 @@+"""Transport-neutral types crossing the message-transport boundary.++Nothing here names Matrix. Identifiers are opaque strings: an `event_id` is+whatever the transport calls a message handle, and `uri` is whatever it calls+an uploaded blob. Callers must not parse either.+"""++from __future__ import annotations++from dataclasses import dataclass, field+from typing import Literal++MessageFormat = Literal["text", "markdown"]+SeekDirection = Literal["forward", "backward"]+++class TransportError(RuntimeError):+ """A transport operation failed.++ Operations raise this rather than returning an error object, so a caller+ cannot proceed on a failure it forgot to check.+ """+++class NotConnectedError(TransportError):+ """An operation was attempted before the transport was connected."""+++# ── Outbound results ──────────────────────────────────────────────────────────+++@dataclass(frozen=True)+class SendResult:+ """A message or event accepted by the transport.++ `event_type` and `content` are what was actually put on the wire, which+ the transport assembles and the caller therefore does not otherwise see.+ Reporting them back means a caller recording what it sent transcribes the+ transport's own dict rather than reconstructing it and drifting from it.+ """++ event_id: str+ event_type: str+ content: dict[str, object] = field(default_factory=dict)+++@dataclass(frozen=True)+class UploadResult:+ """A blob accepted by the transport's media store."""++ uri: str+++@dataclass(frozen=True)+class DownloadResult:+ """Bytes retrieved for a media URI."""++ body: bytes+ content_type: str | None = None+ filename: str | None = None+++# ── Inbound events ────────────────────────────────────────────────────────────+++@dataclass(frozen=True)+class RoomRef:+ """The room an inbound event arrived in.++ Consumers only ever needed the id; this exists so handler signatures do not+ have to name a transport's room object.+ """++ room_id: str+++@dataclass(frozen=True)+class InboundEvent:+ """Fields common to every inbound event."""++ room_id: str+ event_id: str+ sender: str+ timestamp: int+ content: dict[str, object] = field(default_factory=dict)+++@dataclass(frozen=True)+class InboundMessage(InboundEvent):+ """A text message.++ `content` is retained deliberately: `com.switch.*` markers ride on ordinary+ messages, and hiding them behind named fields would mean a new field for+ every marker.+ """++ body: str = ""+ sender_name: str | None = None+ formatted_body: str | None = None+ msgtype: str = "m.text"+ thread_root_id: str | None = None+++@dataclass(frozen=True)+class InboundMedia(InboundMessage):+ """An attachment. `uri` is the handle to pass back to `download_media`.++ A media event is a message that happens to carry a file, so code that only+ cares about sender, body or thread can treat the two alike.+ """++ uri: str = ""+ filename: str | None = None+ mimetype: str | None = None+ size: int | None = None+ group: dict[str, object] | None = None+++@dataclass(frozen=True)+class InboundMembership(InboundEvent):+ """A membership change.++ `state_key` names the member the change is about, which is not the same as+ `sender` — one member can change another's membership.+ """++ state_key: str = ""+ membership: str = ""+ prev_membership: str | None = None+ display_name: str | None = None+++@dataclass(frozen=True)+class InboundCustomEvent(InboundEvent):+ """A non-message event carrying a `com.switch.*` payload in `content`."""++ event_type: str = ""+ thread_root_id: str | None = None+++@dataclass(frozen=True)+class HistoryPage:+ """One page of backwards history.++ `next_token` is an opaque cursor for the following page, or None when the+ transport reports no more history.+ """++ events: list[object]+ next_token: str | Nonediff --git a/core/tests/integration/conftest.py b/core/tests/integration/conftest.pyindex cc0be4289..9e2099852 100644--- a/core/tests/integration/conftest.py+++ b/core/tests/integration/conftest.py@@ -49,16 +49,18 @@ from switch_core.bridges.agent.protocol.types import (RegistrationResult,TaskProtocolConfig,)-from switch_core.bridges.agent.request_tracker import RequestTrackerfrom switch_core.bridges.resource.service import ResourceService-from switch_core.bridges.resource.tracker import ResourceRequestTrackerfrom switch_core.clients.agent_client import AgentClientfrom switch_core.clients.client_base import ClientBasefrom switch_core.clients.client_factory import ClientFactoryfrom switch_core.clients.client_lifecycle_service import ClientLifecycleServicefrom switch_core.config import SwitchConfigfrom switch_core.db.base import Base-from switch_core.db.engine import create_engine_from_config, create_session_factory+from switch_core.db.engine import (+ create_engine_from_config,+ create_session_factory,+ create_unpooled_engine,+)from switch_core.db.models import Userfrom switch_core.db.stores.agent_session_store import AgentSessionStorefrom switch_core.db.stores.agent_store import AgentStore@@ -67,6 +69,8 @@ from switch_core.db.stores.client_store import ClientStorefrom switch_core.db.stores.collaboration_bridge_store import CollaborationBridgeStorefrom switch_core.db.stores.document_store import DocumentStorefrom switch_core.db.stores.external_user_store import ExternalUserStore+from switch_core.db.stores.media_store import MediaStore+from switch_core.db.stores.message_store import MessageStorefrom switch_core.db.stores.package_store import PackageStorefrom switch_core.db.stores.reference_store import ReferenceStorefrom switch_core.db.stores.reference_type_store import ReferenceTypeStore@@ -80,7 +84,11 @@ from switch_core.matrix_admin import (ensure_admin_exists,wait_for_homeserver,)+from switch_core.messages import MessageRecorder+from switch_core.messages.notify import MessageListenerfrom switch_core.room_service import RoomService+from switch_core.transport.ephemeral import EphemeralBus+from switch_core.transport.invites import InviteBus# ── Mirrors deploy/local/docker-compose.yml — keep in sync ──────────────────────POSTGRES_IMAGE = "postgres:16-alpine"@@ -437,8 +445,6 @@ async def harness(session_env: SessionEnv) -> AsyncIterator[Harness]:# events and client registrations never leak across tests.event_buffer = EventBuffer()connections = ConnectionRegistry()- request_tracker = RequestTracker()- resource_request_tracker = ResourceRequestTracker()collab_lifecycle = _NoBridges()resource_service = ResourceService(@@ -454,6 +460,17 @@ async def harness(session_env: SessionEnv) -> AsyncIterator[Harness]:client_store=session_env.client_store,session_factory=session_factory,config=config,+ message_recorder=MessageRecorder(+ session_factory=session_factory,+ room_store=session_env.room_store,+ message_store=MessageStore(),+ ),+ room_store=session_env.room_store,+ message_store=MessageStore(),+ media_store=MediaStore(),+ listener=MessageListener(lambda: create_unpooled_engine(config)),+ invites=InviteBus(),+ ephemeral=EphemeralBus(),)client_factory.register("agent",@@ -467,8 +484,6 @@ async def harness(session_env: SessionEnv) -> AsyncIterator[Harness]:agent_session_store=session_env.agent_session_store,room_role_store=session_env.room_role_store,external_user_store=session_env.external_user_store,- request_tracker=request_tracker,- resource_request_tracker=resource_request_tracker,connections=connections,frontend_base_url=config.frontend_base_url,)@@ -503,8 +518,6 @@ async def harness(session_env: SessionEnv) -> AsyncIterator[Harness]:collab_lifecycle=collab_lifecycle, # type: ignore[arg-type]event_buffer=event_buffer,task_store=session_env.task_store,- request_tracker=request_tracker,- resource_request_tracker=resource_request_tracker,resource_service=resource_service,api_key_store=session_env.api_key_store,api_key_cache=ApiKeyCache(diff --git a/core/tests/switch_core/bridges/agent/protocol/test_read_context.py b/core/tests/switch_core/bridges/agent/protocol/test_read_context.pynew file mode 100644index 000000000..76064c5a8--- /dev/null+++ b/core/tests/switch_core/bridges/agent/protocol/test_read_context.py@@ -0,0 +1,593 @@+"""read_context, now that history comes from the message log.++The homeserver page-walk is gone, and with it the seek budget, the read budget+and the per-thread root refetch. What replaces them is a single windowed query,+so these tests write rows and read them back rather than feeding pages to a+fake transport.++Two behaviours are worth naming because they changed rather than moved:+`truncated` is exact — the query asks for one row more than the caller wanted+and reports whether it exists — and an arrival is stored with no body, so the+sentence a reader sees is composed here and can be reworded without rewriting+history.+"""++from __future__ import annotations++import uuid+from datetime import UTC, datetime, timedelta+from types import SimpleNamespace++from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker++from switch_core.attachments import ATTACHMENT_GROUP_KEY+from switch_core.bridges.agent.protocol.connections import ConnectionRegistry+from switch_core.bridges.agent.protocol.service import ProtocolService+from switch_core.db.models import Client, Message, MessageAttachment, Room+from switch_core.db.stores.message_store import MessageStore++BASE = datetime(2026, 1, 1, 12, 0, tzinfo=UTC)+++def _at(seconds: int) -> datetime:+ return BASE + timedelta(seconds=seconds)+++def _ms(seconds: int) -> int:+ return int(_at(seconds).timestamp() * 1000)+++async def _make_room(session: AsyncSession) -> tuple[str, str]:+ """Insert the Room and Client a recorded row depends on."""+ suffix = uuid.uuid4().hex[:8]+ client = Client(+ matrix_user_id=f"@agent-{suffix}:test",+ display_name="agent one",+ type="agent",+ password="x",+ )+ session.add(client)+ await session.flush()+ room = Room(+ matrix_room_id=f"!room-{suffix}:test",+ name="a room",+ description="",+ )+ session.add(room)+ await session.flush()+ return room.id, client.id+++async def _write(+ session: AsyncSession,+ room_id: str,+ client_id: str,+ event_id: str,+ *,+ body: str | None = "hello",+ at: int = 0,+ sender: str = "@alice:s",+ sender_name: str | None = "Alice",+ thread_root: str | None = None,+ event_type: str = "m.room.message",+ msgtype: str | None = "m.text",+ attachments: list[MessageAttachment] | None = None,+ content: dict[str, object] | None = None,+) -> Message:+ message = Message(+ room_id=room_id,+ transport_event_id=event_id,+ sender_matrix_id=sender,+ sender_client_id=client_id,+ sender_name=sender_name,+ event_type=event_type,+ msgtype=msgtype,+ body=body,+ formatted_body=None,+ thread_root_event_id=thread_root,+ content=content if content is not None else ({"body": body} if body else {}),+ sent_at=_at(at),+ )+ return await MessageStore().create(session, message, attachments or [])+++def _service(session_factory: async_sessionmaker[AsyncSession]) -> ProtocolService:+ async def _require(agent_id: str, room_id: str):+ return SimpleNamespace(id=room_id)++ svc = object.__new__(ProtocolService)+ svc.connections = ConnectionRegistry()+ svc.session_factory = session_factory+ svc.message_store = MessageStore()+ svc.require_room_member = _require # type: ignore[assignment]+ return svc+++class TestEntries:+ async def test_a_message_is_its_own_thread(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ room_id, client_id = await _make_room(session)+ await _write(session, room_id, client_id, "$txt", body="hello")+ await session.commit()++ result = await _service(session_factory).read_context("agent-1", room_id)++ assert len(result["threads"]) == 1+ root = result["threads"][0]["root"]+ assert root["id"] == "$txt"+ assert root["kind"] == "message"+ assert root["body"] == "hello"+ assert root["sender"] == "@alice:s"+ assert root["sender_name"] == "Alice"+ assert root["timestamp"] == _ms(0)+ assert root["attachments"] == []++ async def test_a_file_comes_back_with_the_message(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ room_id, client_id = await _make_room(session)+ await _write(+ session,+ room_id,+ client_id,+ "$img",+ body="what's this?",+ msgtype="m.image",+ attachments=[+ MessageAttachment(+ uri="mxc://s/abc",+ filename="cat.png",+ mimetype="image/png",+ size=1234,+ position=0,+ )+ ],+ )+ await session.commit()++ result = await _service(session_factory).read_context("agent-1", room_id)++ assert result["threads"][0]["root"]["attachments"] == [+ {+ "filename": "cat.png",+ "mimetype": "image/png",+ "size": 1234,+ "mxc": "mxc://s/abc",+ "msgtype": "m.image",+ }+ ]++ async def test_several_files_come_back_on_one_message(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """In the order they were sent, which is what `position` records."""+ async with session_factory() as session:+ room_id, client_id = await _make_room(session)+ await _write(+ session,+ room_id,+ client_id,+ "$multi",+ body="two files",+ msgtype="m.file",+ attachments=[+ MessageAttachment(uri="mxc://s/one", filename="one.pdf"),+ MessageAttachment(uri="mxc://s/two", filename="two.pdf"),+ ],+ )+ await session.commit()++ result = await _service(session_factory).read_context("agent-1", room_id)++ names = [a["filename"] for a in result["threads"][0]["root"]["attachments"]]+ assert names == ["one.pdf", "two.pdf"]++ async def test_a_multi_file_message_is_reassembled_from_its_parts(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """The bus has no event that carries two files, so a two-file message+ is two events sharing a group marker and two rows. History has to put+ them back together the way a live receiver does — otherwise it reads as+ two messages, the second captioned with a filename."""+ async with session_factory() as session:+ room_id, client_id = await _make_room(session)+ for index, (event_id, body, name) in enumerate(+ [("$part0", "two files", "one.pdf"), ("$part1", "two.pdf", "two.pdf")]+ ):+ await _write(+ session,+ room_id,+ client_id,+ event_id,+ body=body,+ at=index,+ msgtype="m.file",+ attachments=[+ MessageAttachment(uri=f"mxc://s/{name}", filename=name)+ ],+ content={+ "body": body,+ ATTACHMENT_GROUP_KEY: {"id": "g1", "index": index, "total": 2},+ },+ )+ await session.commit()++ result = await _service(session_factory).read_context("agent-1", room_id)++ assert len(result["threads"]) == 1+ root = result["threads"][0]["root"]+ assert root["id"] == "$part0"+ assert root["body"] == "two files"+ assert [a["filename"] for a in root["attachments"]] == ["one.pdf", "two.pdf"]++ async def test_a_group_cut_off_by_the_window_returns_what_is_there(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """A page ending mid-group shows the parts it read rather than dropping+ them: the lowest index present leads."""+ async with session_factory() as session:+ room_id, client_id = await _make_room(session)+ await _write(+ session,+ room_id,+ client_id,+ "$part1",+ body="two.pdf",+ at=1,+ msgtype="m.file",+ attachments=[MessageAttachment(uri="mxc://s/two", filename="two.pdf")],+ content={+ "body": "two.pdf",+ ATTACHMENT_GROUP_KEY: {"id": "g1", "index": 1, "total": 2},+ },+ )+ await session.commit()++ result = await _service(session_factory).read_context("agent-1", room_id)++ root = result["threads"][0]["root"]+ assert root["id"] == "$part1"+ assert [a["filename"] for a in root["attachments"]] == ["two.pdf"]++ async def test_an_arrival_is_labelled_and_phrased_on_read(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """The row holds no sentence; this is where one is composed."""+ async with session_factory() as session:+ room_id, client_id = await _make_room(session)+ await _write(+ session,+ room_id,+ client_id,+ "$join",+ body=None,+ msgtype=None,+ event_type="m.room.member",+ sender="@bob:s",+ sender_name="Bob",+ )+ await session.commit()++ result = await _service(session_factory).read_context("agent-1", room_id)++ root = result["threads"][0]["root"]+ assert root["kind"] == "room_join"+ assert root["body"] == "Bob joined the room"+ assert root["sender"] == "@bob:s"++ async def test_an_unnamed_sender_falls_back_to_their_address(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ room_id, client_id = await _make_room(session)+ await _write(+ session, room_id, client_id, "$anon", sender_name=None, sender="@x:s"+ )+ await session.commit()++ result = await _service(session_factory).read_context("agent-1", room_id)++ assert result["threads"][0]["root"]["sender_name"] == "@x:s"+++class TestTruncation:+ """`truncated` is now exact rather than conservative.++ The old walk could not tell "the page cap stopped me" from "the room ended+ there", so it reported truncated whenever it ended on the limit. One extra+ row answers the question outright.+ """++ async def test_a_room_shorter_than_the_limit_is_not_truncated(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ room_id, client_id = await _make_room(session)+ for n in range(3):+ await _write(session, room_id, client_id, f"$m{n}", at=n)+ await session.commit()++ result = await _service(session_factory).read_context(+ "agent-1", room_id, limit=10+ )++ assert result["truncated"] is False+ assert len(result["threads"]) == 3++ async def test_a_room_exactly_the_limit_is_not_truncated(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """The case the old walk had to guess at, and always guessed wrong."""+ async with session_factory() as session:+ room_id, client_id = await _make_room(session)+ for n in range(3):+ await _write(session, room_id, client_id, f"$m{n}", at=n)+ await session.commit()++ result = await _service(session_factory).read_context(+ "agent-1", room_id, limit=3+ )++ assert result["truncated"] is False+ assert len(result["threads"]) == 3++ async def test_older_history_beyond_the_limit_is_reported(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ room_id, client_id = await _make_room(session)+ for n in range(5):+ await _write(session, room_id, client_id, f"$m{n}", at=n)+ await session.commit()++ result = await _service(session_factory).read_context(+ "agent-1", room_id, limit=3+ )++ assert result["truncated"] is True+ assert len(result["threads"]) == 3++ async def test_the_newest_entries_are_the_ones_kept(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ room_id, client_id = await _make_room(session)+ for n in range(5):+ await _write(session, room_id, client_id, f"$m{n}", at=n)+ await session.commit()++ result = await _service(session_factory).read_context(+ "agent-1", room_id, limit=2+ )++ assert [t["root"]["id"] for t in result["threads"]] == ["$m3", "$m4"]+ assert result["oldest_timestamp"] == _ms(3)++ async def test_an_empty_room_reads_as_empty_not_truncated(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ room_id, _ = await _make_room(session)+ await session.commit()++ result = await _service(session_factory).read_context("agent-1", room_id)++ assert result == {+ "threads": [],+ "truncated": False,+ "oldest_timestamp": None,+ }+++class TestWindowing:+ async def test_before_excludes_the_boundary(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ room_id, client_id = await _make_room(session)+ for n in range(4):+ await _write(session, room_id, client_id, f"$m{n}", at=n)+ await session.commit()++ result = await _service(session_factory).read_context(+ "agent-1", room_id, before_ms=_ms(2)+ )++ assert [t["root"]["id"] for t in result["threads"]] == ["$m0", "$m1"]++ async def test_since_includes_the_boundary(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ room_id, client_id = await _make_room(session)+ for n in range(4):+ await _write(session, room_id, client_id, f"$m{n}", at=n)+ await session.commit()++ result = await _service(session_factory).read_context(+ "agent-1", room_id, since_ms=_ms(2)+ )++ assert [t["root"]["id"] for t in result["threads"]] == ["$m2", "$m3"]++ async def test_a_window_far_from_the_present_costs_one_query(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """The old path had to page over everything newer to arrive here, and+ gave up loudly when the seek budget ran out."""+ async with session_factory() as session:+ room_id, client_id = await _make_room(session)+ for n in range(200):+ await _write(session, room_id, client_id, f"$m{n}", at=n)+ await session.commit()++ result = await _service(session_factory).read_context(+ "agent-1", room_id, limit=2, since_ms=_ms(3), before_ms=_ms(6)+ )++ assert [t["root"]["id"] for t in result["threads"]] == ["$m4", "$m5"]+ assert result["truncated"] is True++ async def test_other_rooms_are_not_visible(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ room_id, client_id = await _make_room(session)+ other_id, other_client = await _make_room(session)+ await _write(session, room_id, client_id, "$mine")+ await _write(session, other_id, other_client, "$theirs")+ await session.commit()++ result = await _service(session_factory).read_context("agent-1", room_id)++ assert [t["root"]["id"] for t in result["threads"]] == ["$mine"]+++class TestThreads:+ async def test_replies_group_under_their_root_oldest_first(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ room_id, client_id = await _make_room(session)+ await _write(session, room_id, client_id, "$root", body="q", at=0)+ await _write(+ session, room_id, client_id, "$r1", body="a", at=1, thread_root="$root"+ )+ await _write(+ session, room_id, client_id, "$r2", body="b", at=2, thread_root="$root"+ )+ await session.commit()++ result = await _service(session_factory).read_context("agent-1", room_id)++ assert len(result["threads"]) == 1+ thread = result["threads"][0]+ assert thread["root"]["id"] == "$root"+ assert [r["id"] for r in thread["replies"]] == ["$r1", "$r2"]++ async def test_threads_are_ordered_by_latest_activity(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """Freshest last, so the tail of the list is what just happened."""+ async with session_factory() as session:+ room_id, client_id = await _make_room(session)+ await _write(session, room_id, client_id, "$a", at=0)+ await _write(session, room_id, client_id, "$b", at=1)+ await _write(session, room_id, client_id, "$a1", at=5, thread_root="$a")+ await session.commit()++ result = await _service(session_factory).read_context("agent-1", room_id)++ assert [t["root"]["id"] for t in result["threads"]] == ["$b", "$a"]++ async def test_a_root_older_than_the_window_is_still_returned(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """A reply whose root fell outside the window keeps its root, fetched+ for the whole page at once rather than one query per thread."""+ async with session_factory() as session:+ room_id, client_id = await _make_room(session)+ await _write(session, room_id, client_id, "$root", body="q", at=0)+ for n in range(3):+ await _write(session, room_id, client_id, f"$noise{n}", at=n + 1)+ await _write(+ session,+ room_id,+ client_id,+ "$late",+ body="a",+ at=9,+ thread_root="$root",+ )+ await session.commit()++ result = await _service(session_factory).read_context(+ "agent-1", room_id, limit=2+ )++ threads = {t["root"]["id"]: t for t in result["threads"]}+ assert "$root" in threads+ assert threads["$root"]["root"]["body"] == "q"+ assert [r["id"] for r in threads["$root"]["replies"]] == ["$late"]++ async def test_a_root_with_no_recorded_row_is_elided_not_dropped(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """Losing the root must not take the replies with it."""+ async with session_factory() as session:+ room_id, client_id = await _make_room(session)+ await _write(+ session,+ room_id,+ client_id,+ "$orphan",+ body="a",+ thread_root="$vanished",+ )+ await session.commit()++ result = await _service(session_factory).read_context("agent-1", room_id)++ assert len(result["threads"]) == 1+ thread = result["threads"][0]+ assert thread["root"] == {+ "id": "$vanished",+ "kind": "message",+ "sender": None,+ "sender_name": None,+ "body": None,+ "timestamp": None,+ "elided": True,+ }+ assert [r["id"] for r in thread["replies"]] == ["$orphan"]++ async def test_a_root_in_another_room_is_not_borrowed(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """Resolving roots is scoped to the room, so an id cannot be read+ across a room boundary by claiming it as a thread parent."""+ async with session_factory() as session:+ room_id, client_id = await _make_room(session)+ other_id, other_client = await _make_room(session)+ await _write(session, other_id, other_client, "$elsewhere", body="secret")+ await _write(+ session, room_id, client_id, "$reply", thread_root="$elsewhere"+ )+ await session.commit()++ result = await _service(session_factory).read_context("agent-1", room_id)++ assert result["threads"][0]["root"]["elided"] is True+++class TestLimits:+ async def test_an_absurd_limit_is_clamped(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ room_id, client_id = await _make_room(session)+ await _write(session, room_id, client_id, "$m")+ await session.commit()++ result = await _service(session_factory).read_context(+ "agent-1", room_id, limit=10_000+ )++ assert len(result["threads"]) == 1++ async def test_a_nonsense_limit_still_returns_something(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ room_id, client_id = await _make_room(session)+ await _write(session, room_id, client_id, "$m")+ await session.commit()++ result = await _service(session_factory).read_context(+ "agent-1", room_id, limit=0+ )++ assert len(result["threads"]) == 1diff --git a/core/tests/switch_core/bridges/agent/protocol/test_read_context_attachments.py b/core/tests/switch_core/bridges/agent/protocol/test_read_context_attachments.pydeleted file mode 100644index 07a1575a4..000000000--- a/core/tests/switch_core/bridges/agent/protocol/test_read_context_attachments.py+++ /dev/null@@ -1,93 +0,0 @@-from __future__ import annotations--from types import SimpleNamespace--import nio--from switch_core.bridges.agent.protocol.connections import ConnectionRegistry-from switch_core.bridges.agent.protocol.service import ProtocolService---def _image_event() -> nio.RoomMessageImage:- return nio.RoomMessageImage.from_dict(- {- "type": "m.room.message",- "event_id": "$img",- "sender": "@alice:s",- "origin_server_ts": 1700000000000,- "content": {- "msgtype": "m.image",- "body": "what's this?",- "filename": "cat.png",- "url": "mxc://s/abc",- "info": {"mimetype": "image/png", "size": 1234},- "sender_name": "Alice",- },- }- )---def _text_event() -> nio.RoomMessageText:- return nio.RoomMessageText.from_dict(- {- "type": "m.room.message",- "event_id": "$txt",- "sender": "@bob:s",- "origin_server_ts": 1700000001000,- "content": {"msgtype": "m.text", "body": "hello", "sender_name": "Bob"},- }- )---def _build_service(chunk: list[object]) -> ProtocolService:- async def _room_messages(matrix_room_id: str, start: str | None, limit: int):- # No continuation token: this page is the start of the room.- return SimpleNamespace(chunk=chunk, end=None)-- fake_client = SimpleNamespace(- nio_client=SimpleNamespace(room_messages=_room_messages)- )-- async def _require(agent_id: str, room_id: str):- return SimpleNamespace(matrix_room_id="!room")-- svc = object.__new__(ProtocolService)- # Presence unions the heartbeat rows with the live connections- # (CHOO-1857); an empty registry means "rows only".- svc.connections = ConnectionRegistry()- svc.require_room_member = _require # type: ignore[assignment]- svc.client_lifecycle = SimpleNamespace( # type: ignore[assignment]- get_by_agent_id=lambda agent_id: fake_client- )- return svc---async def test_image_event_carries_attachment() -> None:- svc = _build_service([_image_event()])-- # read_context returns thread groups; a standalone message is its own root.- groups = (await svc.read_context("agent-1", "room-1"))["threads"]-- assert len(groups) == 1- root = groups[0]["root"]- assert root["body"] == "what's this?"- assert root["attachments"] == [- {- "filename": "cat.png",- "mimetype": "image/png",- "size": 1234,- "mxc": "mxc://s/abc",- "msgtype": "m.image",- }- ]---async def test_text_event_has_empty_attachments() -> None:- svc = _build_service([_text_event()])-- groups = (await svc.read_context("agent-1", "room-1"))["threads"]-- assert len(groups) == 1- root = groups[0]["root"]- assert root["body"] == "hello"- assert root["attachments"] == []diff --git a/core/tests/switch_core/bridges/agent/protocol/test_read_context_pagination.py b/core/tests/switch_core/bridges/agent/protocol/test_read_context_pagination.pydeleted file mode 100644index b2e29979b..000000000--- a/core/tests/switch_core/bridges/agent/protocol/test_read_context_pagination.py+++ /dev/null@@ -1,268 +0,0 @@-"""read_context must page the homeserver, not read one page and stop.--The bug this covers (CHOO-2034): a single /messages call returned whatever-fitted in one server-capped page, state events ate into that page, and `since`-/ `before` were applied as filters over it — so `before` could never reach-older history and a truncated read was indistinguishable from a complete one.-"""--from __future__ import annotations--from types import SimpleNamespace-from typing import Any--import nio--from switch_core.bridges.agent.protocol import service-from switch_core.bridges.agent.protocol.connections import ConnectionRegistry-from switch_core.bridges.agent.protocol.service import ProtocolService---def _msg(event_id: str, ts: int, body: str = "hi") -> SimpleNamespace:- return SimpleNamespace(- event_id=event_id,- sender="@u:s",- server_timestamp=ts,- body=body,- source={"content": {"sender_name": "U"}},- )---def _join(event_id: str, ts: int, user: str, displayname: str) -> nio.RoomMemberEvent:- return nio.RoomMemberEvent.from_dict(- {- "type": "m.room.member",- "event_id": event_id,- "sender": user,- "state_key": user,- "origin_server_ts": ts,- "content": {"membership": "join", "displayname": displayname},- }- )---def _rename(event_id: str, ts: int, user: str, displayname: str) -> nio.RoomMemberEvent:- """A display-name change: membership join, but they were already here."""- return nio.RoomMemberEvent.from_dict(- {- "type": "m.room.member",- "event_id": event_id,- "sender": user,- "state_key": user,- "origin_server_ts": ts,- "content": {"membership": "join", "displayname": displayname},- "unsigned": {"prev_content": {"membership": "join"}},- }- )---class _PagedNio:- """Homeserver stand-in that hands out history one page at a time.-- `seek_to` mimics a server that answers timestamp_to_event: the page index- the token lands on. None means the server cannot answer, so the caller has- to scan back instead.- """-- access_token = "tok"-- def __init__(self, pages: list[list[Any]], seek_to: int | None = None) -> None:- self._pages = pages- self._seek_to = seek_to- self.requested_starts: list[str | None] = []-- async def room_messages(- self, room_id: str, start: str | None = None, limit: int = 0- ) -> SimpleNamespace:- self.requested_starts.append(start)- index = 0 if start is None else int(start)- if index >= len(self._pages):- return SimpleNamespace(chunk=[], end=None)- is_last = index == len(self._pages) - 1- return SimpleNamespace(- chunk=self._pages[index],- end=None if is_last else str(index + 1),- )-- async def send(self, method: str, path: str, headers: Any = None) -> Any:- if self._seek_to is None:- return SimpleNamespace(status=404)-- async def _json() -> dict[str, str]:- return {"event_id": "$anchor"}-- return SimpleNamespace(status=200, json=_json)-- async def room_context(self, room_id: str, event_id: str, limit: int = 1) -> Any:- return SimpleNamespace(start=str(self._seek_to))-- async def room_get_event(self, room_id: str, event_id: str) -> Any:- return object.__new__(nio.RoomGetEventError)---def _service(nio_client: _PagedNio) -> ProtocolService:- svc = object.__new__(ProtocolService)- svc.connections = ConnectionRegistry()-- async def _require(agent_id: str, room_id: str) -> SimpleNamespace:- return SimpleNamespace(matrix_room_id="!room:s")-- svc.require_room_member = _require # type: ignore[assignment]- svc.client_lifecycle = SimpleNamespace( # type: ignore[assignment]- get_by_agent_id=lambda agent_id: SimpleNamespace(nio_client=nio_client)- )- return svc---def _roots(result: dict[str, Any]) -> list[str]:- return [g["root"]["id"] for g in result["threads"]]---class TestPagination:- async def test_follows_continuation_token_across_pages(self) -> None:- # Three pages of one message each — the old code saw only the first.- nio_client = _PagedNio(- [[_msg("e3", 300)], [_msg("e2", 200)], [_msg("e1", 100)]]- )- svc = _service(nio_client)-- result = await svc.read_context("agent", "room", limit=10)-- assert sorted(_roots(result)) == ["e1", "e2", "e3"]- assert nio_client.requested_starts == [None, "1", "2"]-- async def test_state_events_do_not_consume_the_message_budget(self) -> None:- # A page full of events that reach nobody must not end the read.- noise = [- SimpleNamespace(- event_id=f"$n{i}",- sender="@s:s",- server_timestamp=500 - i,- body=None,- source={"content": {}},- )- for i in range(20)- ]- nio_client = _PagedNio([noise, [_msg("e1", 100)]])- svc = _service(nio_client)-- result = await svc.read_context("agent", "room", limit=5)-- assert _roots(result) == ["e1"]-- async def test_stops_at_limit_and_reports_truncated(self) -> None:- nio_client = _PagedNio([[_msg("e3", 300), _msg("e2", 200)], [_msg("e1", 100)]])- svc = _service(nio_client)-- result = await svc.read_context("agent", "room", limit=2)-- assert sorted(_roots(result)) == ["e2", "e3"]- assert result["truncated"] is True- assert result["oldest_timestamp"] == 200-- async def test_reaching_room_start_is_not_truncated(self) -> None:- nio_client = _PagedNio([[_msg("e2", 200)], [_msg("e1", 100)]])- svc = _service(nio_client)-- result = await svc.read_context("agent", "room", limit=50)-- assert result["truncated"] is False- assert result["oldest_timestamp"] == 100---class TestWindowing:- async def test_before_pages_backwards_instead_of_filtering(self) -> None:- # Everything older than the cutoff lives on later pages. The old code- # filtered page one, found nothing, and returned empty.- nio_client = _PagedNio(- [- [_msg("new2", 900), _msg("new1", 800)],- [_msg("old2", 200), _msg("old1", 100)],- ]- )- svc = _service(nio_client)-- result = await svc.read_context("agent", "room", limit=10, before_ms=500)-- assert sorted(_roots(result)) == ["old1", "old2"]-- async def test_seeking_to_the_window_does_not_spend_the_read_budget(self) -> None:- # The bug Louis hit: reaching a `before` deep in a busy room meant- # paging over everything newer, and those pages came out of the same- # budget as the read — so a far-enough-back window returned nothing at- # all, and raising `limit` could not help because `limit` never- # governed the walk.- newer = [- [_msg(f"n{p}{i}", 10_000 - p * 100 - i) for i in range(50)]- for p in range(service.HISTORY_MAX_PAGES + 5)- ]- pages = [*newer, [_msg("wanted", 100)]]- svc = _service(_PagedNio(pages))-- result = await svc.read_context("agent", "room", limit=10, before_ms=500)-- assert _roots(result) == ["wanted"]-- async def test_gives_up_loudly_rather_than_scanning_forever(self) -> None:- endless = [[_msg(f"n{p}", 10_000 - p)] for p in range(200)]- svc = _service(_PagedNio(endless))-- result = await svc.read_context("agent", "room", limit=10, before_ms=500)-- # Nothing was reachable, and the caller is told so rather than being- # handed an empty list that looks like "the room is empty".- assert result["threads"] == []- assert result["truncated"] is True-- async def test_uses_the_server_timestamp_anchor_when_offered(self) -> None:- pages = [- [_msg("new", 9_000)],- [_msg("old", 100)],- ]- nio_client = _PagedNio(pages, seek_to=1)- svc = _service(nio_client)-- result = await svc.read_context("agent", "room", limit=10, before_ms=500)-- assert _roots(result) == ["old"]- # Jumped straight to the window instead of paging over page 0.- assert nio_client.requested_starts == ["1"]-- async def test_since_stops_the_walk_once_the_window_is_covered(self) -> None:- nio_client = _PagedNio([[_msg("e2", 900)], [_msg("e1", 100)]])- svc = _service(nio_client)-- result = await svc.read_context("agent", "room", limit=50, since_ms=500)-- assert _roots(result) == ["e2"]- # The window was fully covered — this is not a truncated read.- assert result["truncated"] is False---class TestJoins:- async def test_join_appears_in_the_timeline(self) -> None:- nio_client = _PagedNio([[_join("$j", 100, "@alice:s", "Alice")]])- svc = _service(nio_client)-- result = await svc.read_context("agent", "room", limit=10)-- entry = result["threads"][0]["root"]- assert entry["kind"] == "room_join"- assert entry["body"] == "Alice joined the room"- assert entry["sender"] == "@alice:s"-- async def test_display_name_change_is_not_an_arrival(self) -> None:- nio_client = _PagedNio([[_rename("$r", 100, "@alice:s", "Alice II")]])- svc = _service(nio_client)-- result = await svc.read_context("agent", "room", limit=10)-- assert result["threads"] == []-- async def test_messages_are_labelled_as_messages(self) -> None:- nio_client = _PagedNio([[_msg("e1", 100)]])- svc = _service(nio_client)-- result = await svc.read_context("agent", "room", limit=10)-- assert result["threads"][0]["root"]["kind"] == "message"diff --git a/core/tests/switch_core/bridges/agent/protocol/test_threads.py b/core/tests/switch_core/bridges/agent/protocol/test_threads.pyindex f5ebef013..1d5641098 100644--- a/core/tests/switch_core/bridges/agent/protocol/test_threads.py+++ b/core/tests/switch_core/bridges/agent/protocol/test_threads.py@@ -1,13 +1,13 @@from __future__ import annotationsfrom types import SimpleNamespace-from typing import Anyimport pytest-from nio import RoomGetEventErrorfrom switch_core.bridges.agent.protocol.connections import ConnectionRegistryfrom switch_core.bridges.agent.protocol.service import ProtocolService+from switch_core.transport import HistoryPage, InboundMessage+from tests.switch_core.transport.fake import FakeTransportdef _ev(@@ -17,44 +17,21 @@ def _ev(*,thread_root: str | None = None,sender: str = "@u:server",-) -> SimpleNamespace:- content: dict[str, Any] = {"sender_name": "U"}- if thread_root is not None:- content["m.relates_to"] = {"rel_type": "m.thread", "event_id": thread_root}- return SimpleNamespace(+) -> InboundMessage:+ return InboundMessage(+ room_id="!matrix:server",event_id=event_id,sender=sender,- server_timestamp=ts,+ timestamp=ts,+ content={"sender_name": "U"},body=body,- source={"content": content},+ sender_name="U",+ thread_root_id=thread_root,)-class _FakeNio:- """Minimal nio AsyncClient stand-in for read paths."""-- def __init__(- self,- chunk: list[SimpleNamespace] | None = None,- events: dict[str, SimpleNamespace] | None = None,- ) -> None:- self._chunk = chunk or []- self._events = events or {}-- async def room_messages(- self, room_id: str, start: str | None = None, limit: int = 0- ) -> SimpleNamespace:- return SimpleNamespace(chunk=self._chunk, end=None)-- async def room_get_event(self, room_id: str, event_id: str) -> Any:- ev = self._events.get(event_id)- if ev is None:- return object.__new__(RoomGetEventError)- return SimpleNamespace(event=ev)---def _service_with_client(nio: _FakeNio) -> ProtocolService:- client = SimpleNamespace(nio_client=nio)+def _service_with_transport(transport: FakeTransport) -> ProtocolService:+ client = SimpleNamespace(transport=transport)svc = object.__new__(ProtocolService)# Presence unions the heartbeat rows with the live connections# (CHOO-1857); an empty registry means "rows only".@@ -70,10 +47,21 @@ def _service_with_client(nio: _FakeNio) -> ProtocolService:return svc+def _transport(+ chunk: list[InboundMessage] | None = None,+ events: dict[str, InboundMessage] | None = None,+) -> FakeTransport:+ # No continuation token: the single page is the start of the room.+ transport = FakeTransport(+ history=HistoryPage(events=list(chunk or []), next_token=None)+ )+ transport.events_by_id = dict(events or {})+ return transport++class TestResolveThreadRoot:async def test_passthrough_for_root(self) -> None:- nio = _FakeNio(events={"e1": _ev("e1", "root", 100)})- svc = _service_with_client(nio)+ svc = _service_with_transport(_transport(events={"e1": _ev("e1", "root", 100)}))client = svc.client_lifecycle.get_by_agent_id("a")root = await svc._resolve_thread_root(client, "!m:s", "e1")@@ -81,8 +69,9 @@ class TestResolveThreadRoot:assert root == "e1"async def test_normalizes_mid_thread_reply_to_root(self) -> None:- nio = _FakeNio(events={"e2": _ev("e2", "reply", 200, thread_root="e1")})- svc = _service_with_client(nio)+ svc = _service_with_transport(+ _transport(events={"e2": _ev("e2", "reply", 200, thread_root="e1")})+ )client = svc.client_lifecycle.get_by_agent_id("a")root = await svc._resolve_thread_root(client, "!m:s", "e2")@@ -90,54 +79,12 @@ class TestResolveThreadRoot:assert root == "e1"async def test_raises_when_event_missing(self) -> None:- nio = _FakeNio(events={})- svc = _service_with_client(nio)+ svc = _service_with_transport(_transport(events={}))client = svc.client_lifecycle.get_by_agent_id("a")with pytest.raises(ValueError, match="thread_id not found"):await svc._resolve_thread_root(client, "!m:s", "nope")-class TestReadContextThreads:- async def test_groups_threads_ordered_by_latest_activity(self) -> None:- # chunk is newest-first, as the homeserver returns it.- chunk = [- _ev("e2", "reply to e1", 200, thread_root="e1"),- _ev("e3", "later top-level", 150),- _ev("e1", "root", 100),- ]- svc = _service_with_client(_FakeNio(chunk=chunk))-- result = (await svc.read_context("agent", "room"))["threads"]-- # Two threads: e3 (latest 150) then e1 (latest 200) — most-active last.- assert [g["root"]["id"] for g in result] == ["e3", "e1"]- assert result[0]["replies"] == []- assert [m["id"] for m in result[1]["replies"]] == ["e2"]- # Each message exposes its id.- assert result[1]["root"]["id"] == "e1"-- async def test_fetches_orphan_root_outside_window(self) -> None:- chunk = [_ev("e9", "reply", 200, thread_root="e1")]- events = {"e1": _ev("e1", "old root", 100)}- svc = _service_with_client(_FakeNio(chunk=chunk, events=events))-- result = (await svc.read_context("agent", "room"))["threads"]-- assert len(result) == 1- assert result[0]["root"]["id"] == "e1"- assert result[0]["root"]["body"] == "old root"- assert "elided" not in result[0]["root"]- assert [m["id"] for m in result[0]["replies"]] == ["e9"]-- async def test_orphan_root_elided_when_fetch_fails(self) -> None:- chunk = [_ev("e9", "reply", 200, thread_root="e1")]- svc = _service_with_client(_FakeNio(chunk=chunk, events={}))-- result = (await svc.read_context("agent", "room"))["threads"]-- assert len(result) == 1- assert result[0]["root"]["id"] == "e1"- assert result[0]["root"]["elided"] is True- assert result[0]["root"]["body"] is None- assert [m["id"] for m in result[0]["replies"]] == ["e9"]+# Thread grouping in read_context is covered by test_read_context.py, which+# reads the message log rather than a transport.diff --git a/core/tests/switch_core/bridges/agent/test_command_result_threading.py b/core/tests/switch_core/bridges/agent/test_command_result_threading.pyindex 107335a65..bcfce72aa 100644--- a/core/tests/switch_core/bridges/agent/test_command_result_threading.py+++ b/core/tests/switch_core/bridges/agent/test_command_result_threading.py@@ -5,6 +5,7 @@ from types import SimpleNamespacefrom switch_core.bridges.agent.commands import _cmd_help, _replyfrom switch_core.clients.client_base import ClientBasefrom switch_core.events import CommandEvent+from switch_core.transport import InboundCustomEvent, RoomRefclass _Recorder:@@ -36,7 +37,7 @@ class TestReplyThreading:async def test_threads_under_command_thread_id(self) -> None:send = _Recorder()client = SimpleNamespace(reply_command=send)- await _reply(client, SimpleNamespace(room_id="!m"), _event("$cmd-root"), "hi")+ await _reply(client, RoomRef("!m"), _event("$cmd-root"), "hi")assert len(send.calls) == 1assert send.calls[0]["thread_root_id"] == "$cmd-root"@@ -47,7 +48,7 @@ class TestReplyThreading:async def test_top_level_when_no_thread_id(self) -> None:send = _Recorder()client = SimpleNamespace(reply_command=send)- await _reply(client, SimpleNamespace(room_id="!m"), _event(None), "hi")+ await _reply(client, RoomRef("!m"), _event(None), "hi")assert len(send.calls) == 1assert send.calls[0]["thread_root_id"] is None@@ -60,9 +61,7 @@ class TestHandlerThreads:async def test_help_result_is_threaded(self) -> None:send = _Recorder()client = SimpleNamespace(reply_command=send)- await _cmd_help(- client, SimpleNamespace(room_id="!m"), _event("$cmd-root"), True- )+ await _cmd_help(client, RoomRef("!m"), _event("$cmd-root"), True)assert len(send.calls) == 1assert send.calls[0]["thread_root_id"] == "$cmd-root"@@ -74,7 +73,9 @@ class TestDispatchPopulatesThreadId:root at dispatch (it is not part of the event content)."""@staticmethod- async def _dispatch(content: dict[str, object], event_id: str) -> CommandEvent:+ async def _dispatch(+ content: dict[str, object], event_id: str, thread_root_id: str | None = None+ ) -> CommandEvent:captured: list[CommandEvent] = []async def _on_command(_room: object, event: CommandEvent) -> None:@@ -85,19 +86,21 @@ class TestDispatchPopulatesThreadId:_EVENT_DISPATCH=ClientBase._EVENT_DISPATCH,on_command=_on_command,)- unknown = SimpleNamespace(- type="com.switch.command",+ custom = InboundCustomEvent(+ room_id="!m",event_id=event_id,- source={"content": content},- )- await ClientBase._handle_custom_event(- fake_self, SimpleNamespace(room_id="!m"), unknown+ sender="@u:s",+ timestamp=1700000000000,+ content=content,+ event_type="com.switch.command",+ thread_root_id=thread_root_id,)+ await ClientBase._handle_custom_event(fake_self, RoomRef("!m"), custom)assert len(captured) == 1return captured[0]async def test_top_level_command_gets_its_own_event_id(self) -> None:- # No m.thread relation → the command roots its own thread.+ # No thread relation → the command roots its own thread.event = await self._dispatch({"command": "status", "args": "", "user_id": "u1", "user_name": "louisa"},"$the-command-event",@@ -119,5 +122,6 @@ class TestDispatchPopulatesThreadId:},},"$the-command-event",+ thread_root_id="$matrix-thread-root",)assert event.thread_id == "$matrix-thread-root"diff --git a/core/tests/switch_core/bridges/agent/test_mediation.py b/core/tests/switch_core/bridges/agent/test_mediation.pynew file mode 100644index 000000000..18ddda078--- /dev/null+++ b/core/tests/switch_core/bridges/agent/test_mediation.py@@ -0,0 +1,142 @@+"""Pre-invocation mediation says yes to what an agent has and no to the rest.++There was no test for this at all while it ran over Matrix — the round trip+made it awkward to exercise, which is its own argument. Against a direct call+it is four cases.+"""++from __future__ import annotations++import uuid++from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker++from switch_core.bridges.agent.mediation import BLOCKED, PROCEED, MediationService+from switch_core.db.models import Agent, ApiKey, Client, Model, Tool, User+from switch_core.db.stores.agent_store import AgentStore+++async def _agent(session: AsyncSession) -> Agent:+ name = f"agent-{uuid.uuid4().hex[:8]}"+ user = User(name=name, email=f"{name}@test", role="user", password_hash="x")+ session.add(user)+ await session.flush()+ api_key = ApiKey(+ user_id=user.id,+ key_hash=f"hash-{name}",+ encrypted_key="enc",+ label=name,+ type="agent",+ )+ client = Client(+ matrix_user_id=f"@{name}:test", display_name=name, type="agent", password="x"+ )+ session.add_all([api_key, client])+ await session.flush()+ agent = Agent(+ name=name,+ description="",+ agent_type="always_on",+ connector_type="claude_code",+ integration_profile={"connection_model": "always_on"},+ client_id=client.id,+ api_key_id=api_key.id,+ )+ session.add(agent)+ await session.flush()+ return agent+++def _service(session_factory: async_sessionmaker[AsyncSession]) -> MediationService:+ return MediationService(session_factory=session_factory, agent_store=AgentStore())+++class TestToolAccess:+ async def test_an_attached_tool_proceeds(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ agent = await _agent(session)+ session.add(Tool(name="grep", description="", agent_id=agent.id))+ await session.commit()+ agent_id = agent.id++ verdict = await _service(session_factory).tool_access(agent_id, "grep")++ assert verdict.verdict == PROCEED+ assert verdict.reason is None++ async def test_a_tool_the_agent_does_not_have_is_blocked_with_a_reason(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """A refusal a user cannot act on is barely better than a crash, so+ the reason names both the agent and the tool."""+ async with session_factory() as session:+ agent = await _agent(session)+ session.add(Tool(name="grep", description="", agent_id=agent.id))+ await session.commit()+ agent_id = agent.id++ verdict = await _service(session_factory).tool_access(agent_id, "rm")++ assert verdict.verdict == BLOCKED+ assert verdict.reason is not None+ assert "rm" in verdict.reason+ assert agent_id in verdict.reason++ async def test_an_agent_with_no_tools_is_blocked(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ agent = await _agent(session)+ await session.commit()+ agent_id = agent.id++ verdict = await _service(session_factory).tool_access(agent_id, "grep")++ assert verdict.verdict == BLOCKED++ async def test_another_agent_s_tool_does_not_count(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """Tools are per agent. A name existing somewhere in the table is not+ the question being asked."""+ async with session_factory() as session:+ mine = await _agent(session)+ theirs = await _agent(session)+ session.add(Tool(name="grep", description="", agent_id=theirs.id))+ await session.commit()+ agent_id = mine.id++ verdict = await _service(session_factory).tool_access(agent_id, "grep")++ assert verdict.verdict == BLOCKED+++class TestModelAccess:+ async def test_an_attached_model_proceeds(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ agent = await _agent(session)+ session.add(Model(name="a-model", description="", agent_id=agent.id))+ await session.commit()+ agent_id = agent.id++ verdict = await _service(session_factory).model_access(agent_id, "a-model")++ assert verdict.verdict == PROCEED++ async def test_a_model_the_agent_does_not_have_is_blocked_with_a_reason(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ agent = await _agent(session)+ await session.commit()+ agent_id = agent.id++ verdict = await _service(session_factory).model_access(agent_id, "a-model")++ assert verdict.verdict == BLOCKED+ assert verdict.reason is not None+ assert "a-model" in verdict.reasondiff --git a/core/tests/switch_core/bridges/collaboration/test_bridge_outbound_admin_rendering.py b/core/tests/switch_core/bridges/collaboration/test_bridge_outbound_admin_rendering.pyindex 5ecacc150..1ffa1a677 100644--- a/core/tests/switch_core/bridges/collaboration/test_bridge_outbound_admin_rendering.py+++ b/core/tests/switch_core/bridges/collaboration/test_bridge_outbound_admin_rendering.py@@ -12,10 +12,10 @@ relay path at the time, so nothing caught it.from __future__ import annotations-from types import SimpleNamespacefrom typing import Anyfrom switch_core.bridges.collaboration.bridge_core import ADMIN_MARKER, BridgeCore+from switch_core.transport import InboundMessage, RoomRefBODY = "**Agents in this room:**\n- **scout** — Claude Code"@@ -84,17 +84,18 @@ async def _none(*_args: Any, **_kwargs: Any) -> None:return None-def _event(*, admin: bool) -> Any:+def _event(*, admin: bool) -> InboundMessage:content: dict[str, Any] = {}if admin:content[ADMIN_MARKER] = {"type": "command_result"}- else:- content["sender_name"] = "scout"- return SimpleNamespace(+ return InboundMessage(+ room_id="!r:switch.local",+ event_id="$e1",sender="@someone:switch.local",+ timestamp=1700000000000,+ content=content,body=BODY,- event_id="$e1",- source={"content": content},+ sender_name=None if admin else "scout",)@@ -102,7 +103,7 @@ async def test_an_admin_event_reaches_the_adapter_unrendered() -> None:adapter = _RecordingAdapter()await _bridge(adapter).handle_outbound_message(- SimpleNamespace(room_id="!r:switch.local"), _event(admin=True)+ RoomRef("!r:switch.local"), _event(admin=True))# Handed on as written, for admin_message to render once.@@ -116,7 +117,7 @@ async def test_an_admin_event_is_not_rendered_twice() -> None:adapter = _RecordingAdapter()await _bridge(adapter).handle_outbound_message(- SimpleNamespace(room_id="!r:switch.local"), _event(admin=True)+ RoomRef("!r:switch.local"), _event(admin=True))rendered = adapter.translate_outbound(adapter.admin_calls[0])@@ -130,7 +131,7 @@ async def test_an_agent_message_is_still_rendered_by_the_relay() -> None:adapter = _RecordingAdapter()await _bridge(adapter).handle_outbound_message(- SimpleNamespace(room_id="!r:switch.local"), _event(admin=False)+ RoomRef("!r:switch.local"), _event(admin=False))assert adapter.admin_calls == []diff --git a/core/tests/switch_core/bridges/collaboration/test_bridge_outbound_media.py b/core/tests/switch_core/bridges/collaboration/test_bridge_outbound_media.pyindex 8747c032f..aa23f0190 100644--- a/core/tests/switch_core/bridges/collaboration/test_bridge_outbound_media.py+++ b/core/tests/switch_core/bridges/collaboration/test_bridge_outbound_media.py@@ -4,10 +4,13 @@ import asynciofrom types import SimpleNamespacefrom typing import Any-import nio-from nio import DownloadError-from switch_core.bridges.collaboration.bridge_core import BridgeCore+from switch_core.transport import (+ DownloadResult,+ InboundMedia,+ RoomRef,+ TransportError,+)def _media_event(@@ -21,7 +24,7 @@ def _media_event(group: dict[str, Any] | None = None,mimetype: str = "image/png",event_id: str = "$media-event",-) -> nio.RoomMessageMedia:+) -> InboundMedia:content: dict[str, Any] = {"msgtype": msgtype,"body": body,@@ -36,15 +39,21 @@ def _media_event(content["sender_name"] = sender_nameif thread_root is not None:content["m.relates_to"] = {"rel_type": "m.thread", "event_id": thread_root}- cls = nio.RoomMessageImage if msgtype == "m.image" else nio.RoomMessageFile- return cls.from_dict(- {- "type": "m.room.message",- "event_id": event_id,- "sender": sender,- "origin_server_ts": 1700000000000,- "content": content,- }+ return InboundMedia(+ room_id="!room:s",+ event_id=event_id,+ sender=sender,+ timestamp=1700000000000,+ content=content,+ body=body,+ sender_name=sender_name,+ msgtype=msgtype,+ uri="mxc://s/abc",+ filename=filename or body,+ mimetype=mimetype,+ size=5,+ thread_root_id=thread_root,+ group=group,)@@ -111,7 +120,7 @@ class _FakeAdapter:def _fake_bridge(*,- download: object = SimpleNamespace(body=b"bytes"),+ download: DownloadResult | TransportError = DownloadResult(body=b"bytes"),matrix_to_external: dict[str, str] | None = None,max_bytes: int = 1024,) -> SimpleNamespace:@@ -155,15 +164,19 @@ def _fake_bridge(BridgeCore._flush_incomplete_outbound_group.__get__(ns))- async def _nio_download(mxc: str):+ async def _download_media(uri: str) -> DownloadResult:+ if isinstance(download, TransportError):+ raise downloadreturn download- ns.client = SimpleNamespace(nio_client=SimpleNamespace(download=_nio_download))+ ns.client = SimpleNamespace(+ transport=SimpleNamespace(download_media=_download_media)+ )return ns-def _room() -> SimpleNamespace:- return SimpleNamespace(room_id="!room:s")+def _room() -> RoomRef:+ return RoomRef("!room:s")async def test_image_relays_via_send_attachment_and_records_map() -> None:@@ -264,7 +277,7 @@ async def test_non_image_file_relays_natively() -> None:async def test_download_failure_posts_disclosed_fallback() -> None:- bridge = _fake_bridge(download=DownloadError("boom"))+ bridge = _fake_bridge(download=TransportError("boom"))await BridgeCore.handle_outbound_media(bridge, _room(), _media_event(), bridge.client@@ -276,7 +289,7 @@ async def test_download_failure_posts_disclosed_fallback() -> None:async def test_oversize_media_posts_disclosed_fallback() -> None:- bridge = _fake_bridge(download=SimpleNamespace(body=b"too big"), max_bytes=3)+ bridge = _fake_bridge(download=DownloadResult(body=b"too big"), max_bytes=3)await BridgeCore.handle_outbound_media(bridge, _room(), _media_event(), bridge.clientdiff --git a/core/tests/switch_core/bridges/collaboration/test_bridge_type_registry.py b/core/tests/switch_core/bridges/collaboration/test_bridge_type_registry.pyindex c5db36072..34fafc77f 100644--- a/core/tests/switch_core/bridges/collaboration/test_bridge_type_registry.py+++ b/core/tests/switch_core/bridges/collaboration/test_bridge_type_registry.py@@ -47,6 +47,7 @@ def _service() -> CollaborationBridgeLifecycleService:matrix_admin=None, # type: ignore[arg-type]session_factory=None, # type: ignore[arg-type]config=None, # type: ignore[arg-type]+ client_factory=None, # type: ignore[arg-type])diff --git a/core/tests/switch_core/bridges/collaboration/test_command_thread_mapping.py b/core/tests/switch_core/bridges/collaboration/test_command_thread_mapping.pyindex 422fc4f8a..209f6fb49 100644--- a/core/tests/switch_core/bridges/collaboration/test_command_thread_mapping.py+++ b/core/tests/switch_core/bridges/collaboration/test_command_thread_mapping.py@@ -2,10 +2,9 @@ from __future__ import annotationsfrom types import MethodType, SimpleNamespace-from nio import RoomSendError-from switch_core.bridges.collaboration.bridge_core import BridgeCorefrom switch_core.bridges.collaboration.models import InboundCommand+from switch_core.transport import SendResult, TransportErrordef _cmd(@@ -28,7 +27,7 @@ def _cmd(def _fake_bridge(- room_send_result: object,+ send_result: SendResult | TransportError,*,external_to_matrix: dict[str, str] | None = None,translate_inbound: object = None,@@ -48,13 +47,16 @@ def _fake_bridge(pending[matrix_event_id] = external_post_idasync def _ensure_user_in_matrix_room(**_kw: object) -> SimpleNamespace:- async def _room_send(_room_id: str, _type: str, content: dict) -> object:+ async def _send_event(_room_id: str, _type: str, content: dict) -> str:sent_content.append(content)- return room_send_result+ if isinstance(send_result, TransportError):+ raise send_result+ return send_result.event_idreturn SimpleNamespace(matrix_user_id="@puppet:switch.local",- client=SimpleNamespace(room_send=_room_send),+ client_id="puppet-1",+ send_event=_send_event,)async def _matrix_event_for_external_post(external_post_id: str) -> str | None:@@ -80,7 +82,11 @@ def _fake_bridge(class TestCommandThreadMapping:async def test_top_level_command_maps_to_its_own_post(self) -> None:# No root_id: the command starts its own thread, rooted at its post.- bridge = _fake_bridge(SimpleNamespace(event_id="$cmd-event"))+ bridge = _fake_bridge(+ SendResult(+ event_id="$cmd-event", event_type="com.switch.command", content={}+ )+ )await BridgeCore._handle_inbound_command(bridge, _cmd(message_ref="mm-post-1"))assert bridge.recorded == [@@ -98,7 +104,9 @@ class TestCommandThreadMapping:# command event relates to the existing Matrix root, and we do NOT remap# the (already-mapped) root post.bridge = _fake_bridge(- SimpleNamespace(event_id="$cmd-event"),+ SendResult(+ event_id="$cmd-event", event_type="com.switch.command", content={}+ ),external_to_matrix={"mm-root": "$matrix-root"},)await BridgeCore._handle_inbound_command(@@ -114,7 +122,11 @@ class TestCommandThreadMapping:async def test_in_thread_command_maps_root_when_unbridged(self) -> None:# Thread root not yet bridged: map the command event to the thread root# (a valid Mattermost root post), NOT to the mid-thread command post.- bridge = _fake_bridge(SimpleNamespace(event_id="$cmd-event"))+ bridge = _fake_bridge(+ SendResult(+ event_id="$cmd-event", event_type="com.switch.command", content={}+ )+ )await BridgeCore._handle_inbound_command(bridge, _cmd(message_ref="mm-reply", root_id="mm-root"))@@ -130,13 +142,17 @@ class TestCommandThreadMapping:async def test_no_mapping_without_external_post_ref(self) -> None:# Native (non-bridged) command: no external post to thread under.- bridge = _fake_bridge(SimpleNamespace(event_id="$cmd-event"))+ bridge = _fake_bridge(+ SendResult(+ event_id="$cmd-event", event_type="com.switch.command", content={}+ )+ )await BridgeCore._handle_inbound_command(bridge, _cmd(message_ref=None))assert bridge.recorded == []async def test_no_mapping_when_send_fails(self) -> None:- err = RoomSendError("boom")+ err = TransportError("boom")bridge = _fake_bridge(err)await BridgeCore._handle_inbound_command(bridge, _cmd(message_ref="mm-post-1"))@@ -192,12 +208,12 @@ class TestCommandResultThreadingRace:resolved: dict[str, str | None] = {}async def _ensure_user_in_matrix_room(**_kw: object) -> SimpleNamespace:- async def _room_send(_room_id: str, _type: str, _content: dict) -> object:- return SimpleNamespace(event_id="$cmd-event")+ async def _send_event(_room_id: str, _type: str, _content: dict) -> str:+ return "$cmd-event"return SimpleNamespace(matrix_user_id="@puppet:switch.local",- client=SimpleNamespace(room_send=_room_send),+ send_event=_send_event,)async def _matrix_event_for_external_post(_post: 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 33d0a8e29..cb4ed3342 100644--- a/core/tests/switch_core/bridges/collaboration/test_lifecycle_remove.py+++ b/core/tests/switch_core/bridges/collaboration/test_lifecycle_remove.py@@ -50,6 +50,7 @@ def _service(matrix_admin=MagicMock(),session_factory=session_factory,config=MagicMock(),+ client_factory=MagicMock(),)@@ -225,3 +226,31 @@ class TestTheBridgeClientName:localpart = _bridge_client_localpart("slack", "Ops & Eng (US)")assert re.fullmatch(r"[a-z0-9._=/-]+", localpart)+++async def test_a_starting_bridge_is_recorded_in_the_rooms_it_carries(+ session_factory: async_sessionmaker[AsyncSession],+) -> None:+ """Membership is a row now, and nothing had ever written the bridge's.++ Its rooms were expressed by inviting it and letting the homeserver+ remember; once a client reads its rooms from `client_rooms`, a bridge with+ no rows is in none of them and relays nothing outward — while still+ receiving, because inbound posts into a room by id.+ """+ service = _service(session_factory)+ async with session_factory() as session:+ bridge_id, client_id = await _make_bridge(session)+ room_id = await _make_bridged_room(session, bridge_id=bridge_id)+ other_bridge_id, _ = await _make_bridge(session)+ elsewhere_id = await _make_bridged_room(session, bridge_id=other_bridge_id)+ await session.commit()++ await service._record_bridge_memberships(bridge_id, client_id)+ # Again, because a bridge starts more than once.+ await service._record_bridge_memberships(bridge_id, client_id)++ async with session_factory() as session:+ assert await RoomStore().get_client_ids(session, room_id) == [client_id]+ assert await RoomStore().get_client_ids(session, elsewhere_id) == []diff --git a/core/tests/switch_core/bridges/collaboration/test_teams_zero_config.py b/core/tests/switch_core/bridges/collaboration/test_teams_zero_config.pyindex 130918879..120d18096 100644--- a/core/tests/switch_core/bridges/collaboration/test_teams_zero_config.py+++ b/core/tests/switch_core/bridges/collaboration/test_teams_zero_config.py@@ -318,6 +318,7 @@ def _lifecycle() -> CollaborationBridgeLifecycleService:matrix_admin=MagicMock(),session_factory=MagicMock(),config=MagicMock(),+ client_factory=MagicMock(),)service.register_adapter("recording", _RecordingAdapter, _RecordingConfig)return service@@ -397,6 +398,7 @@ def _service_with_existing(existing: list[Any]) -> CollaborationBridgeLifecycleSmatrix_admin=MagicMock(),session_factory=MagicMock(return_value=session),config=MagicMock(),+ client_factory=MagicMock(),)service.register_adapter("teams", TeamsAdapter, TeamsConnectionConfig)return service@@ -552,6 +554,7 @@ async def test_concurrent_registration_cannot_take_the_same_port_twice(matrix_admin=MagicMock(),session_factory=MagicMock(return_value=session),config=MagicMock(),+ client_factory=MagicMock(),)service.register_adapter("teams", TeamsAdapter, TeamsConnectionConfig)monkeypatch.setattr(@@ -616,6 +619,7 @@ async def test_start_refuses_a_second_bridge_already_holding_the_port() -> None:matrix_admin=MagicMock(),session_factory=MagicMock(return_value=session),config=MagicMock(),+ client_factory=MagicMock(),)service.register_adapter("teams", TeamsAdapter, TeamsConnectionConfig)# A bridge already running and holding the port.diff --git a/core/tests/switch_core/clients/test_addressing_enforcement.py b/core/tests/switch_core/clients/test_addressing_enforcement.pyindex c7e6081d6..6d67e1df6 100644--- a/core/tests/switch_core/clients/test_addressing_enforcement.py+++ b/core/tests/switch_core/clients/test_addressing_enforcement.py@@ -3,14 +3,23 @@ from __future__ import annotationsfrom contextlib import asynccontextmanagerfrom types import SimpleNamespace-from switch_core.clients.agent_client import (- _ADDRESSING_DENIED_MESSAGE,- _ADDRESSING_UNCLAIMED_MESSAGE,- AUTO_REPLY_FLAG,- AgentClient,- _AddressingDecision,- _SenderPrincipal,+from switch_core.clients.agent_client import AUTO_REPLY_FLAG, AgentClient+from switch_core.delivery.addressing import (+ ADDRESSING_DENIED_MESSAGE as _ADDRESSING_DENIED_MESSAGE,)+from switch_core.delivery.addressing import (+ ADDRESSING_UNCLAIMED_MESSAGE as _ADDRESSING_UNCLAIMED_MESSAGE,+)+from switch_core.delivery.addressing import (+ AddressingDecision as _AddressingDecision,+)+from switch_core.delivery.addressing import (+ AddressingResolver,+)+from switch_core.delivery.addressing import (+ SenderPrincipal as _SenderPrincipal,+)+from switch_core.transport import InboundMessage, RoomRef@asynccontextmanager@@ -22,17 +31,18 @@ def _meta(room_id: str = "room-1") -> SimpleNamespace:return SimpleNamespace(room_id=room_id)-def _event(- sender: str = "@u:switch.local", auto_reply: bool = False-) -> SimpleNamespace:+def _event(sender: str = "@u:switch.local", auto_reply: bool = False) -> InboundMessage:content: dict = {"sender_name": "human"}if auto_reply:content[AUTO_REPLY_FLAG] = True- return SimpleNamespace(+ return InboundMessage(+ room_id="!matrix:switch.local",+ event_id="$evt",sender=sender,+ timestamp=1700000000000,+ content=content,body="@fixer help",- source={"content": content},- event_id="$evt",+ sender_name="human",)@@ -54,7 +64,7 @@ class TestResolveSenderPrincipal:return list(claimants)return SimpleNamespace(- client_store=SimpleNamespace(get_by_matrix_user_id=_get_by_mxid),+ _client_store=SimpleNamespace(get_by_matrix_user_id=_get_by_mxid),_agent_store=SimpleNamespace(get_by_client_id=_agent_by_client),_external_user_store=SimpleNamespace(get_by_client_id=_ext_by_client, claimant_ids=_claimant_ids@@ -69,7 +79,7 @@ class TestResolveSenderPrincipal:agent=SimpleNamespace(id="agent-7", owner_id="user-1"),external_user=None,)- result = await AgentClient._resolve_sender_principal(+ result = await AddressingResolver.resolve_sender(client, object(), "@a:switch.local")assert result == ("agent", "agent-7", [], "user-1")@@ -81,7 +91,7 @@ class TestResolveSenderPrincipal:external_user=SimpleNamespace(id="ext-3"),claimants=["user-1"],)- result = await AgentClient._resolve_sender_principal(+ result = await AddressingResolver.resolve_sender(client, object(), "@u:switch.local")assert result == ("user", "ext-3", ["user-1"], None)@@ -95,7 +105,7 @@ class TestResolveSenderPrincipal:external_user=SimpleNamespace(id="ext-3"),claimants=["user-1", "user-2"],)- result = await AgentClient._resolve_sender_principal(+ result = await AddressingResolver.resolve_sender(client, object(), "@u:switch.local")assert result == ("user", "ext-3", ["user-1", "user-2"], None)@@ -107,14 +117,14 @@ class TestResolveSenderPrincipal:agent=None,external_user=SimpleNamespace(id="ext-3"),)- result = await AgentClient._resolve_sender_principal(+ result = await AddressingResolver.resolve_sender(client, object(), "@u:switch.local")assert result == ("user", "ext-3", [], None)async def test_unknown_client_is_none(self) -> None:client = self._client(client=None, agent=None, external_user=None)- result = await AgentClient._resolve_sender_principal(+ result = await AddressingResolver.resolve_sender(client, object(), "@ghost:switch.local")assert result is None@@ -125,7 +135,7 @@ class TestResolveSenderPrincipal:client = self._client(client=SimpleNamespace(id="c1"), agent=None, external_user=None)- result = await AgentClient._resolve_sender_principal(+ result = await AddressingResolver.resolve_sender(client, object(), "@system:switch.local")assert result is None@@ -139,9 +149,9 @@ def _allowed_client(group_id: str | None = None,owner_id: str | None = None,) -> SimpleNamespace:- """Fake client for _addressing_allowed: the agent carries `policy` and is- owned by `owner_id`, the sender resolves to `principal` (kind, id,- claimants) owned by `sender_owner_id`, and the room has `group_id`."""+ """Fake resolver for `permitted`: the agent carries `policy` and is owned+ by `owner_id`, the sender resolves to `principal` (kind, id, claimants)+ owned by `sender_owner_id`, and the room has `group_id`."""agent = SimpleNamespace(name="fixer", addressing_policy=policy, owner_id=owner_id)@@ -156,15 +166,16 @@ def _allowed_client(return SimpleNamespace(agent=agent,- session_factory=_session_factory,- _resolve_sender_principal=_resolve,+ resolve_sender=_resolve,_room_store=SimpleNamespace(get=_get_room),)async def _decide(client: SimpleNamespace, room_id: str = "room-1"): # type: ignore[no-untyped-def]- return await AgentClient._addressing_allowed(- client, None, client.agent, "@u:switch.local", room_id+ # No session is opened here: the resolver reads through the one it is+ # handed, so `permitted` never takes a pool slot of its own.+ return await AddressingResolver.permitted(+ client, object(), agent=client.agent, room_id=room_id, sender="@u:switch.local")@@ -385,8 +396,8 @@ def _gate_client(*, allowed: bool, refusal: str = _ADDRESSING_DENIED_MESSAGE):return client-def _room() -> SimpleNamespace:- return SimpleNamespace(room_id="!matrix:switch.local")+def _room() -> RoomRef:+ return RoomRef(room_id="!matrix:switch.local")async def _gate(client: SimpleNamespace, event: SimpleNamespace): # type: ignore[no-untyped-def]diff --git a/core/tests/switch_core/clients/test_admin_client.py b/core/tests/switch_core/clients/test_admin_client.pyindex 2f0017bfe..a4768b004 100644--- a/core/tests/switch_core/clients/test_admin_client.py+++ b/core/tests/switch_core/clients/test_admin_client.py@@ -8,6 +8,7 @@ from switch_core.bridges.agent.commands import dispatch_admin_commandfrom switch_core.clients.admin_client import AdminClientfrom switch_core.clients.admin_messages import ADMIN_MARKER, AdminMessageTypefrom switch_core.events import CommandEvent+from switch_core.transport import InboundMessage, RoomRef# Matches a live `@<handle>` mention token (same char class Switch re-parses)._MENTION = re.compile(r"@[A-Za-z0-9._-]+")@@ -30,18 +31,22 @@ def _no_connections() -> SimpleNamespace:)-def _event(body: str, sender_name: str = "alice") -> SimpleNamespace:+def _event(body: str, sender_name: str = "alice") -> InboundMessage:"""A room message as the admin client sees it: body + sender + thebridge-provided sender_name in content (used to tag the asker)."""- return SimpleNamespace(- body=body,+ return InboundMessage(+ room_id="!matrix:switch.local",+ event_id="$evt",sender=f"@{sender_name}:switch.local",- source={"content": {"sender_name": sender_name}},+ timestamp=1700000000000,+ content={"sender_name": sender_name},+ body=body,+ sender_name=sender_name,)-def _room() -> SimpleNamespace:- return SimpleNamespace(room_id="!matrix:switch.local")+def _room() -> RoomRef:+ return RoomRef(room_id="!matrix:switch.local")def _admin_client(diff --git a/core/tests/switch_core/clients/test_agent_client_attachment_groups.py b/core/tests/switch_core/clients/test_agent_client_attachment_groups.pyindex 4ef41d558..4abea2ce2 100644--- a/core/tests/switch_core/clients/test_agent_client_attachment_groups.py+++ b/core/tests/switch_core/clients/test_agent_client_attachment_groups.py@@ -5,11 +5,10 @@ from contextlib import asynccontextmanagerfrom types import SimpleNamespacefrom typing import Any-import nio-import switch_core.clients.agent_client as acfrom switch_core.clients.agent_client import AgentClient, _GateOutcomefrom switch_core.clients.room_meta import RoomMeta+from switch_core.transport import InboundMedia, RoomRefdef _media_event(@@ -20,7 +19,7 @@ def _media_event(msgtype: str = "m.image",group: dict[str, Any] | None = None,event_id: str = "$evt",-) -> nio.RoomMessageMedia:+) -> InboundMedia:content: dict[str, Any] = {"msgtype": msgtype,"body": body,@@ -32,15 +31,20 @@ def _media_event(content["filename"] = filenameif group is not None:content["com.switch.attachment_group"] = group- cls = nio.RoomMessageImage if msgtype == "m.image" else nio.RoomMessageFile- return cls.from_dict(- {- "type": "m.room.message",- "event_id": event_id,- "sender": "@alice:s",- "origin_server_ts": 1700000000000,- "content": content,- }+ return InboundMedia(+ room_id="!room:s",+ event_id=event_id,+ sender="@alice:s",+ timestamp=1700000000000,+ content=content,+ body=body,+ sender_name="alice",+ msgtype=msgtype,+ uri="mxc://s/abc",+ filename=filename,+ mimetype=mimetype,+ size=5,+ group=group,)@@ -104,8 +108,8 @@ def _fake_client() -> SimpleNamespace:return ns-def _room() -> SimpleNamespace:- return SimpleNamespace(room_id="!room:s")+def _room() -> RoomRef:+ return RoomRef(room_id="!room:s")async def test_grouped_media_coalesces_into_one_event() -> None:diff --git a/core/tests/switch_core/clients/test_agent_client_pool_checkouts.py b/core/tests/switch_core/clients/test_agent_client_pool_checkouts.pyindex b8cee49ae..c51dfcb67 100644--- a/core/tests/switch_core/clients/test_agent_client_pool_checkouts.py+++ b/core/tests/switch_core/clients/test_agent_client_pool_checkouts.py@@ -29,6 +29,8 @@ from switch_core.db.stores.client_store import ClientStorefrom switch_core.db.stores.external_user_store import ExternalUserStorefrom switch_core.db.stores.room_role_store import RoomRoleStorefrom switch_core.db.stores.room_store import RoomStore+from switch_core.delivery.addressing import AddressingResolver+from switch_core.transport import InboundMessage, RoomRefMATRIX_ROOM_ID = "!r:test"@@ -126,6 +128,14 @@ def _client(client._agent_session_store = AgentSessionStore()client._external_user_store = ExternalUserStore()client._connections = ConnectionRegistry()+ client._addressing = AddressingResolver(+ room_store=client._room_store,+ room_role_store=client._room_role_store,+ client_store=client.client_store,+ agent_store=client._agent_store,+ external_user_store=client._external_user_store,+ live_agent_ids=client._connections.live_agent_ids,+ )client._frontend_base_url = Noneclient._room_meta = {MATRIX_ROOM_ID: RoomMeta(@@ -150,19 +160,20 @@ def _client(return client-def _message(body: str, sender: str = "@switch-slack-louisa:test") -> Any:- return SimpleNamespace(- body=body,- formatted_body=None,- sender=sender,+def _message(body: str, sender: str = "@switch-slack-louisa:test") -> InboundMessage:+ return InboundMessage(+ room_id=MATRIX_ROOM_ID,event_id="$trigger",- server_timestamp=0,- source={"content": {"body": body, "sender_name": "louisa"}},+ sender=sender,+ timestamp=0,+ content={"body": body, "sender_name": "louisa"},+ body=body,+ sender_name="louisa",)-def _room() -> Any:- return SimpleNamespace(room_id=MATRIX_ROOM_ID)+def _room() -> RoomRef:+ return RoomRef(room_id=MATRIX_ROOM_ID)class TestInboundMessageCheckouts:diff --git a/core/tests/switch_core/clients/test_client_construction.py b/core/tests/switch_core/clients/test_client_construction.pynew file mode 100644index 000000000..2f6cd5f46--- /dev/null+++ b/core/tests/switch_core/clients/test_client_construction.py@@ -0,0 +1,180 @@+"""Every client subclass must be constructible through the real signature.++Three subclasses take `**kwargs: Any` and forward to `ClientBase`, which+hides the constructor from the type checker: a keyword `ClientBase` no+longer accepts type-checks clean and fails at runtime, when the client+starts. That is how a `device_id` left behind by the transport port took+down all four collaboration bridges while mypy stayed green.++These tests call the constructors the way production does.+"""++from __future__ import annotations++import ast+import inspect+import pathlib+from typing import Any++import pytest++from switch_core.clients.admin_client import AdminClient+from switch_core.clients.bridge_client import BridgeClient, BridgeClientConfig+from switch_core.clients.client_base import ClientBase, ClientConfig+from switch_core.clients.client_factory import matrix_transport_for+from switch_core.clients.user_client import UserClient+from tests.switch_core.transport.fake import FakeMessageRecorder+++def _base_kwargs() -> dict[str, Any]:+ return {+ "client_id": "client-1",+ "matrix_user_id": "@switch-agent-1:switch.local",+ "display_name": "agent-one",+ "password": "pw",+ "server_url": "https://matrix.example",+ "session_factory": object(),+ "client_store": object(),+ "transport_factory": matrix_transport_for,+ "session_state": {"access_token": None, "device_id": None},+ "next_batch_token": None,+ "message_recorder": FakeMessageRecorder(),+ }+++def test_client_base_takes_what_the_factory_passes() -> None:+ client = ClientBase(config=ClientConfig(), **_base_kwargs())++ assert client.client_id == "client-1"+ # Credentials are held opaquely, not unpacked into named attributes.+ assert client.session_state == {"access_token": None, "device_id": None}+++def test_bridge_client_construction_matches_its_lifecycle_call_site() -> None:+ client = BridgeClient(+ bridge_core=object(), # type: ignore[arg-type]+ config=BridgeClientConfig(bridge_id="bridge-1"),+ **_base_kwargs(),+ )++ assert client.config.bridge_id == "bridge-1"++[email protected]("cls", [UserClient, AdminClient])+def test_every_registered_client_type_constructs(cls: type) -> None:+ base = _base_kwargs()+ # Collaborators the factory injects as extra kwargs differ per class, so+ # stub whatever each one declares rather than naming them here.+ collaborators: dict[str, Any] = {}+ for name, param in inspect.signature(cls.__init__).parameters.items():+ if (+ param.kind is not inspect.Parameter.KEYWORD_ONLY+ or param.default is not inspect.Parameter.empty+ or name in base+ or name == "config"+ ):+ continue+ # A plain object() stands in for a collaborator, but a few are strings+ # the constructor manipulates on the way in.+ collaborators[name] = "" if "str" in str(param.annotation) else object()++ client = cls(config=cls.config_class(), **base, **collaborators)++ assert isinstance(client, ClientBase)+++def test_no_client_holds_matrix_credentials_directly() -> None:+ """The transport owns them; a client that reads them is a Matrix client."""+ client = ClientBase(config=ClientConfig(), **_base_kwargs())++ assert not hasattr(client, "access_token")+ assert not hasattr(client, "device_id")+++def test_no_call_site_passes_transport_credentials_to_a_client() -> None:+ """Catch the caller, which the constructor tests above cannot.++ `**kwargs: Any` means a call site passing `device_id=` type-checks and+ then fails when the client starts. Constructing a client correctly in a+ test proves nothing about the places that construct it wrongly, so scan+ for the argument itself.+ """+ package = pathlib.Path(__file__).resolve().parents[3] / "switch_core"+ retired = {"device_id", "access_token"}+ offenders: list[str] = []++ for path in package.rglob("*.py"):+ tree = ast.parse(path.read_text(), filename=str(path))+ for node in ast.walk(tree):+ if not isinstance(node, ast.Call):+ continue+ func = node.func+ name = getattr(func, "id", None) or getattr(func, "attr", "")+ if not name.endswith("Client"):+ continue+ passed = {kw.arg for kw in node.keywords if kw.arg}+ for arg in sorted(passed & retired):+ offenders.append(f"{path.relative_to(package)}: {name}({arg}=...)")++ assert offenders == [], (+ "clients take an opaque `session_state`, not individual credentials; "+ f"these call sites still pass them: {offenders}"+ )+++def test_only_the_factory_names_a_transport_implementation() -> None:+ """A client's bus is one decision, made in one place.++ The collaboration bridges named `matrix_transport_for` directly, so the+ transport setting reached every agent and no bridge: agents talked in rows,+ bridges talked to the homeserver, and neither side saw the other or logged+ anything. Nothing failed — messages simply stopped crossing.++ That is invisible in review, so scan for the cause instead. Any module that+ can reach an implementation can pick the wrong one.++ Guarded per module rather than per symbol: an implementation's module is+ private, so one added later is covered the day it lands instead of the day+ someone remembers to extend a list of names, and putting a module in+ `allowed` is a deliberate act a reviewer sees.+ """+ package = pathlib.Path(__file__).resolve().parents[3] / "switch_core"+ private = {"switch_core.transport.matrix", "switch_core.transport.postgres"}+ allowed = {+ "clients/client_factory.py",+ "transport/matrix.py",+ "transport/postgres.py",+ # The migration commands are the exception the rule is not about. They+ # exist to read the homeserver — that is the whole job — and they must+ # do it whatever transport the running server is on, which is how a+ # backfill can still be run after the flip. A client picking its own+ # bus is the bug; a one-off command naming the bus it is migrating+ # away from is the point.+ "cli/backfill.py",+ "cli/reconcile.py",+ }+ offenders: list[str] = []++ for path in package.rglob("*.py"):+ relative = path.relative_to(package).as_posix()+ if relative in allowed:+ continue+ tree = ast.parse(path.read_text(), filename=str(path))+ for node in ast.walk(tree):+ imported: list[str] = []+ if isinstance(node, ast.Import):+ imported = [alias.name for alias in node.names]+ elif isinstance(node, ast.ImportFrom) and node.module and not node.level:+ # `from switch_core.transport import postgres` reaches the same+ # module by importing its name from the package.+ imported = [node.module] + [+ f"{node.module}.{alias.name}" for alias in node.names+ ]+ for name in imported:+ if name in private:+ offenders.append(f"{relative}: {name}")++ assert offenders == [], (+ "ask ClientFactory.transport_for for a transport rather than reaching "+ f"for one; these modules choose for themselves: {offenders}"+ )diff --git a/core/tests/switch_core/clients/test_client_factory_transport_choice.py b/core/tests/switch_core/clients/test_client_factory_transport_choice.pynew file mode 100644index 000000000..6fdf238f4--- /dev/null+++ b/core/tests/switch_core/clients/test_client_factory_transport_choice.py@@ -0,0 +1,101 @@+"""One setting picks the transport, and the recorder that goes with it.++The pairing is the thing worth a test. A transport that stores what it carries+paired with a recorder that also writes would double every row; the other way+round would leave the log empty. Both are silent until someone reads the table,+which is why the decision is made in one place and checked here.+"""++from __future__ import annotations++from typing import Any++import pytest+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker++from switch_core.clients.client_base import ClientBase+from switch_core.clients.client_factory import ClientFactory+from switch_core.config import SwitchConfig+from switch_core.db.models import Client+from switch_core.db.stores.client_store import ClientStore+from switch_core.db.stores.media_store import MediaStore+from switch_core.db.stores.message_store import MessageStore+from switch_core.db.stores.room_store import RoomStore+from switch_core.messages import MessageRecorder+from switch_core.messages.notify import MessageListener+from switch_core.messages.recording import NoRecording+from switch_core.transport.ephemeral import EphemeralBus+from switch_core.transport.invites import InviteBus+from switch_core.transport.matrix import MatrixTransport+from switch_core.transport.postgres import PostgresTransport+++def _factory(+ session_factory: async_sessionmaker[AsyncSession], transport: str+) -> ClientFactory:+ config = SwitchConfig(+ db_host="db",+ db_port="5432",+ db_user="postgres",+ db_password="pw",+ db_name="switch",+ matrix_server="http://nowhere",+ matrix_server_name="switch.local",+ matrix_admin_user="admin",+ matrix_admin_password="pw",+ matrix_registration_shared_secret="secret",+ agent_registration_token="token",+ jwt_secret_key="jwt",+ gateway_admin_email="[email protected]",+ gateway_admin_password="pw",+ message_transport=transport, # type: ignore[arg-type]+ )+ recorder = MessageRecorder(+ session_factory=session_factory,+ room_store=RoomStore(),+ message_store=MessageStore(),+ )+ factory = ClientFactory(+ client_store=ClientStore(),+ session_factory=session_factory,+ config=config,+ message_recorder=recorder,+ room_store=RoomStore(),+ message_store=MessageStore(),+ media_store=MediaStore(),+ listener=MessageListener(lambda: None), # type: ignore[arg-type,return-value]+ invites=InviteBus(),+ ephemeral=EphemeralBus(),+ )+ factory.register("user", ClientBase)+ return factory+++def _record() -> Client:+ return Client(+ id="client-1",+ matrix_user_id="@someone:test",+ display_name="someone",+ type="user",+ password="x",+ )+++ ("setting", "transport_class", "records_separately"),+ [+ ("matrix", MatrixTransport, True),+ ("postgres", PostgresTransport, False),+ ],+)+def test_the_setting_picks_both_halves(+ session_factory: async_sessionmaker[AsyncSession],+ setting: str,+ transport_class: type,+ records_separately: bool,+) -> None:+ client: Any = _factory(session_factory, setting).create(_record())++ assert isinstance(client._transport_factory(client), transport_class)+ assert isinstance(client.message_recorder, MessageRecorder) is records_separately+ assert isinstance(client.message_recorder, NoRecording) is not records_separatelydiff --git a/core/tests/switch_core/clients/test_mention_routing.py b/core/tests/switch_core/clients/test_mention_routing.pyindex c30b36c61..2d13fa418 100644--- a/core/tests/switch_core/clients/test_mention_routing.py+++ b/core/tests/switch_core/clients/test_mention_routing.py@@ -8,6 +8,10 @@ from switch_core.clients.agent_client import (AgentClient,_role_elsewhere_message,)+from switch_core.delivery.addressing import (+ AddressingResolver,+ IncomingMessage,+)@asynccontextmanager@@ -32,21 +36,49 @@ def _no_connections() -> SimpleNamespace:)-def _event(body: str, formatted_body: str | None = None) -> SimpleNamespace:- return SimpleNamespace(body=body, formatted_body=formatted_body)+def _event(body: str, formatted_body: str | None = None) -> IncomingMessage:+ return IncomingMessage(sender="@u:test", body=body, formatted_body=formatted_body)+++def _resolver(**attrs: object) -> SimpleNamespace:+ """A resolver-shaped double with the named checks wired to the real ones.++ Each check reads only the stores it needs, so a double carrying just those+ is enough to run the real logic against.+ """+ resolver = SimpleNamespace(**attrs)+ for name in ("mentions_name", "mentions_alias", "mentions_role"):+ setattr(+ resolver,+ name,+ (+ lambda method: (+ lambda *a, **kw: getattr(AddressingResolver, method)(+ resolver, *a, **kw+ )+ )+ )(name),+ )+ return resolverdef _client(name: str) -> SimpleNamespace:- # Enough surface for the unbound _is_mentioned: an agent with a name and a- # matrix_user_id for the formatted_body branch.+ """An AgentClient-shaped double: an agent, an mxid, and a resolver."""return SimpleNamespace(agent=SimpleNamespace(name=name),matrix_user_id=f"@switch-agent-{name}:switch.local",+ _addressing=_resolver(),+ _as_incoming=AgentClient._as_incoming,)def _is_mentioned(name: str, body: str) -> bool:- return AgentClient._is_mentioned(_client(name), _event(body))+ return AddressingResolver.mentions_name(+ _resolver(),+ agent=SimpleNamespace(name=name), # type: ignore[arg-type]+ agent_matrix_id=f"@switch-agent-{name}:switch.local",+ message=_event(body),+ )async def _command_addresses(name: str, args: str) -> bool:@@ -127,12 +159,14 @@ class TestMediaEventWithoutFormattedBody:def test_media_caption_mention_matches(self) -> None:client = _client("cc-bug-fixing")# A media event surfaces only `body` (the caption) — no formatted_body.- media_event = SimpleNamespace(body="@cc-bug-fixing look at this")+ media_event = SimpleNamespace(+ body="@cc-bug-fixing look at this", content={}, sender="@u:test"+ )assert AgentClient._is_mentioned(client, media_event) is Truedef test_media_without_mention_not_addressed(self) -> None:client = _client("cc-bug-fixing")- media_event = SimpleNamespace(body="cat.png")+ media_event = SimpleNamespace(body="cat.png", content={}, sender="@u:test")assert AgentClient._is_mentioned(client, media_event) is False@@ -162,9 +196,10 @@ def _role_client(agent_name: str, held_role: str | None) -> SimpleNamespace:return SimpleNamespace(agent=SimpleNamespace(id="agent-1", name=agent_name),- session_factory=_session_factory,- _connections=_no_connections(),- _room_role_store=SimpleNamespace(agent_room_role=_agent_room_role),+ _addressing=_resolver(+ _room_role_store=SimpleNamespace(agent_room_role=_agent_room_role),+ _live_agent_ids=_no_connections().live_agent_ids,+ ),)@@ -231,9 +266,9 @@ def _alias_client(agent_name: str, alias_by_room: dict[str, str]) -> SimpleNamesreturn SimpleNamespace(agent=SimpleNamespace(id="agent-1", name=agent_name),- session_factory=_session_factory,- _connections=_no_connections(),- _room_store=SimpleNamespace(get_alias=_get_alias),+ _addressing=_resolver(+ _room_store=SimpleNamespace(get_alias=_get_alias),+ ),)diff --git a/core/tests/switch_core/clients/test_no_session_reply_threading.py b/core/tests/switch_core/clients/test_no_session_reply_threading.pyindex 63abfc56b..e07f91a94 100644--- a/core/tests/switch_core/clients/test_no_session_reply_threading.py+++ b/core/tests/switch_core/clients/test_no_session_reply_threading.py@@ -11,6 +11,7 @@ from switch_core.clients.agent_client import (AgentClient,_GateOutcome,)+from switch_core.transport import InboundMessage, RoomRef@asynccontextmanager@@ -92,25 +93,26 @@ def _fake_self(return ns-def _event(thread_id: str | None, *, is_auto_reply: bool = False) -> SimpleNamespace:+def _event(thread_id: str | None, *, is_auto_reply: bool = False) -> InboundMessage:content: dict[str, object] = {"sender_name": "louisa"}- if thread_id is not None:- content["m.relates_to"] = {"rel_type": "m.thread", "event_id": thread_id}if is_auto_reply:content[AUTO_REPLY_FLAG] = True- return SimpleNamespace(- body="@cc-bug-fixing can you help",- sender="@switch-mattermost-louisa:switch.local",+ return InboundMessage(+ room_id="!matrix:server",event_id="$trigger",- server_timestamp=0,- source={"content": content},+ sender="@switch-mattermost-louisa:switch.local",+ timestamp=0,+ content=content,+ body="@cc-bug-fixing can you help",+ sender_name="louisa",+ thread_root_id=thread_id,)@pytest.mark.asyncioasync def test_no_session_reply_threads_under_triggering_mention() -> None:send_message = _Recorder()- room = SimpleNamespace(room_id="!matrix:server")+ room = RoomRef(room_id="!matrix:server")await AgentClient.on_message(_fake_self(send_message), room, _event(thread_id="$thread-root"))@@ -132,7 +134,7 @@ async def test_no_session_reply_not_triggered_by_another_auto_reply() -> None:# must not ping-pong. A message already flagged as an auto-reply gets no# reply, so the loop can never form.send_message = _Recorder()- room = SimpleNamespace(room_id="!matrix:server")+ room = RoomRef(room_id="!matrix:server")await AgentClient.on_message(_fake_self(send_message),room,@@ -148,7 +150,7 @@ async def test_no_session_reply_does_not_double_tag_the_asker() -> None:# configured operator). When that's the same person as the asker, we must# tag them once, not "@louisa @louisa".send_message = _Recorder()- room = SimpleNamespace(room_id="!matrix:server")+ room = RoomRef(room_id="!matrix:server")await AgentClient.on_message(_fake_self(send_message, unavailable_reply="@louisa\n\nmy operator should run …"@@ -168,7 +170,7 @@ async def test_no_session_reply_tags_distinct_asker_and_operator() -> None:# When the reply's embedded mention is a DIFFERENT person (the operator),# both the asker and that operator are tagged.send_message = _Recorder()- room = SimpleNamespace(room_id="!matrix:server")+ room = RoomRef(room_id="!matrix:server")await AgentClient.on_message(_fake_self(send_message, unavailable_reply="@operator\n\nmy operator should run …"@@ -200,7 +202,7 @@ class TestStartingSessionNoticeGoesWhereItWasAsked:@pytest.mark.asyncioasync def test_asked_at_the_root_it_answers_at_the_root(self) -> None:send_message = _Recorder()- room = SimpleNamespace(room_id="!matrix:server")+ room = RoomRef(room_id="!matrix:server")await AgentClient.on_message(_fake_self(send_message, unavailable_reply=_STARTING_SESSION_MESSAGE),@@ -217,7 +219,7 @@ class TestStartingSessionNoticeGoesWhereItWasAsked:# The other half of the rule — replying at the root here would strand# the notice away from the conversation it belongs to.send_message = _Recorder()- room = SimpleNamespace(room_id="!matrix:server")+ room = RoomRef(room_id="!matrix:server")await AgentClient.on_message(_fake_self(send_message, unavailable_reply=_STARTING_SESSION_MESSAGE),@@ -241,7 +243,7 @@ class TestTerminalReplyThreadsOffTheTrigger:@pytest.mark.asyncioasync def test_asked_at_the_root_it_opens_a_thread_on_the_trigger(self) -> None:send_message = _Recorder()- room = SimpleNamespace(room_id="!matrix:server")+ room = RoomRef(room_id="!matrix:server")await AgentClient.on_message(_fake_self(send_message), room, _event(thread_id=None)@@ -255,7 +257,7 @@ class TestTerminalReplyThreadsOffTheTrigger:# Already in a thread: the trigger's thread root IS that thread, so it# lands there rather than starting a nested one.send_message = _Recorder()- room = SimpleNamespace(room_id="!matrix:server")+ room = RoomRef(room_id="!matrix:server")await AgentClient.on_message(_fake_self(send_message), room, _event(thread_id="$thread-root")diff --git a/core/tests/switch_core/clients/test_room_join_events.py b/core/tests/switch_core/clients/test_room_join_events.pyindex 7585c8f73..a927dd61f 100644--- a/core/tests/switch_core/clients/test_room_join_events.py+++ b/core/tests/switch_core/clients/test_room_join_events.py@@ -5,6 +5,7 @@ from types import SimpleNamespacefrom switch_core.bridges.agent.protocol.types import AgentEvent, RoomJoinPayloadfrom switch_core.clients.agent_client import AgentClient, RoomMeta+from switch_core.transport import InboundMembership, RoomRefclass _FakeQueue:@@ -15,6 +16,19 @@ class _FakeQueue:self.enqueued.append((agent_id, room_id, event))+class _FakeClientStore:+ """Resolves a matrix id to the Switch client that owns it, or nothing."""++ def __init__(self, names: dict[str, str]) -> None:+ self._names = names++ async def get_by_matrix_user_id(+ self, _session: object, matrix_user_id: str+ ) -> object | None:+ name = self._names.get(matrix_user_id)+ return SimpleNamespace(display_name=name) if name else None++class _FakeRoomStore:def __init__(self, receives: bool) -> None:self._receives = receives@@ -25,7 +39,12 @@ class _FakeRoomStore:return self._receives-def _client(meta: RoomMeta | None = None, *, receives: bool = True) -> SimpleNamespace:+def _client(+ meta: RoomMeta | None = None,+ *,+ receives: bool = True,+ known: dict[str, str] | None = None,+) -> SimpleNamespace:"""A minimal fake `self` for the unbound AgentClient.on_member_event.Stubs the event queue, agent identity, room-meta resolution, and the room@@ -47,13 +66,21 @@ def _client(meta: RoomMeta | None = None, *, receives: bool = True) -> SimpleNamasync def _session_factory():yield SimpleNamespace()- return SimpleNamespace(+ stub = SimpleNamespace(_event_buffer=_FakeQueue(),agent=SimpleNamespace(id="agent-1"),_resolve_room_meta=_resolve_room_meta,_room_store=_FakeRoomStore(receives),+ client_store=_FakeClientStore(+ {"@alice:switch.local": "Alice"} if known is None else known+ ),session_factory=_session_factory,)+ # Bound, so the handler resolves the name through the real implementation.+ stub._member_name = lambda session, event: AgentClient._member_name(+ stub, session, event+ )+ return stubdef _member_event(@@ -62,23 +89,26 @@ def _member_event(prev_membership: str | None = "leave",state_key: str = "@alice:switch.local",displayname: str | None = "Alice",- server_timestamp: int = 123,-) -> SimpleNamespace:+ timestamp: int = 123,+) -> InboundMembership:content: dict[str, object] = {}if displayname is not None:content["displayname"] = displayname- return SimpleNamespace(+ return InboundMembership(+ room_id="!matrix:switch.local",+ event_id="$member",+ sender=state_key,+ timestamp=timestamp,+ content=content,+ state_key=state_key,membership=membership,prev_membership=prev_membership,- state_key=state_key,- content=content,- server_timestamp=server_timestamp,+ display_name=displayname,)-async def _run(client: SimpleNamespace, event: SimpleNamespace) -> None:- room = SimpleNamespace(room_id="!matrix:switch.local")- await AgentClient.on_member_event(client, room, event)+async def _run(client: SimpleNamespace, event: InboundMembership) -> None:+ await AgentClient.on_member_event(client, RoomRef("!matrix:switch.local"), event)class TestRoomJoinEnqueue:@@ -110,11 +140,22 @@ class TestRoomJoinEnqueue:_, _, event = client._event_buffer.enqueued[0]assert event.payload.listening is False- async def test_missing_displayname_falls_back_to_localpart(self) -> None:- client = _client()+ async def test_the_member_is_named_the_way_switch_knows_them(self) -> None:+ """A profile carries the source platform's spelling of a name; the log+ records the Switch one. Delivering the profile name would make live+ events and history disagree about the same person."""+ client = _client(known={"@alice:switch.local": "alice"})+ await _run(client, _member_event(displayname="Alice \U0001f495"))++ _, _, event = client._event_buffer.enqueued[0]+ assert event.payload.member_name == "alice"++ async def test_a_member_no_switch_client_owns_falls_back_to_the_event(+ self,+ ) -> None:+ client = _client(known={})await _run(- client,- _member_event(displayname=None, state_key="@bob:switch.local"),+ client, _member_event(displayname=None, state_key="@bob:switch.local"))assert len(client._event_buffer.enqueued) == 1diff --git a/core/tests/switch_core/clients/test_self_join_dispatch.py b/core/tests/switch_core/clients/test_self_join_dispatch.pyindex d09d923ca..cf308a12d 100644--- a/core/tests/switch_core/clients/test_self_join_dispatch.py+++ b/core/tests/switch_core/clients/test_self_join_dispatch.py@@ -9,25 +9,41 @@ greeting unreachable on every room an agent is invited to, which is all of them.from __future__ import annotations-from types import SimpleNamespace-import pytestfrom switch_core.clients.client_base import ClientBase+from switch_core.transport import InboundMembership, RoomRefMATRIX_ROOM_ID = "!matrix:switch.local"SELF = "@switch-agent-1:switch.local"+class _Recorder:+ """Stands in for MessageRecorder, collecting the arrivals written."""++ def __init__(self) -> None:+ self.joins: list[str] = []+ self.names: list[str] = []++ async def record_join(+ self, *, transport_room_id, event, client_id, member_name+ ) -> None:+ self.joins.append(event.event_id)+ self.names.append(member_name)++class _Client(ClientBase):def __init__(self) -> None:self.matrix_user_id = SELF+ self.client_id = "client-1"+ self.display_name = "client one"self.room_join_times = {}self._room_joined_events = {}self._self_join_dispatched = set()self._startup_ts = 1000self.self_joins: list[str] = []self.member_events: list[str] = []+ self.message_recorder = _Recorder()async def on_self_join(self, room, event) -> None:self.self_joins.append(room.room_id)@@ -36,8 +52,8 @@ class _Client(ClientBase):self.member_events.append(event.state_key)-def _room() -> SimpleNamespace:- return SimpleNamespace(room_id=MATRIX_ROOM_ID)+def _room() -> RoomRef:+ return RoomRef(room_id=MATRIX_ROOM_ID)def _member_event(@@ -45,15 +61,16 @@ def _member_event(state_key: str = SELF,membership: str = "join",prev_membership: str | None = "invite",- server_timestamp: int = 2000,-) -> SimpleNamespace:- return SimpleNamespace(+ timestamp: int = 2000,+) -> InboundMembership:+ return InboundMembership(+ room_id=MATRIX_ROOM_ID,+ event_id="$member",+ sender=state_key,+ timestamp=timestamp,state_key=state_key,membership=membership,prev_membership=prev_membership,- server_timestamp=server_timestamp,- sender=state_key,- content={},)@@ -85,7 +102,7 @@ async def test_profile_update_is_not_an_arrival() -> None:client = _Client()await client._handle_member_event(- _room(), _member_event(prev_membership="join", server_timestamp=3000)+ _room(), _member_event(prev_membership="join", timestamp=3000))assert client.self_joins == []@@ -95,7 +112,7 @@ async def test_profile_update_is_not_an_arrival() -> None:async def test_join_predating_this_process_is_not_announced() -> None:client = _Client()- await client._handle_member_event(_room(), _member_event(server_timestamp=500))+ await client._handle_member_event(_room(), _member_event(timestamp=500))assert client.self_joins == []@@ -107,12 +124,10 @@ async def test_rejoining_after_leaving_is_a_fresh_arrival() -> None:await client._handle_member_event(_room(), _member_event())await client._handle_member_event(_room(),- _member_event(- membership="leave", prev_membership="join", server_timestamp=3000- ),+ _member_event(membership="leave", prev_membership="join", timestamp=3000),)await client._handle_member_event(- _room(), _member_event(prev_membership="leave", server_timestamp=4000)+ _room(), _member_event(prev_membership="leave", timestamp=4000))assert client.self_joins == [MATRIX_ROOM_ID, MATRIX_ROOM_ID]@@ -127,3 +142,41 @@ async def test_another_member_joining_is_not_a_self_join() -> None:assert client.self_joins == []assert client.member_events == [other]+++async def test_an_arrival_is_logged_even_when_it_is_not_announced() -> None:+ """Announcing and logging answer different questions.++ A join older than this process is nobody's news, so it is not announced.+ It is still how that participant got into the room, so it is still history.+ """+ client = _Client()++ await client._handle_member_event(_room(), _member_event(timestamp=500))++ assert client.self_joins == []+ assert client.message_recorder.joins == ["$member"]+++async def test_a_profile_update_is_not_logged_as_an_arrival() -> None:+ client = _Client()++ await client._handle_member_event(+ _room(), _member_event(prev_membership="join", timestamp=3000)+ )++ assert client.message_recorder.joins == []+++async def test_another_member_arriving_is_not_this_client_to_log() -> None:+ """Each client logs its own arrival, which is what makes it one row."""+ client = _Client()++ await client._handle_member_event(+ _room(), _member_event(state_key="@switch-agent-2:switch.local")+ )++ assert client.message_recorder.joins == []diff --git a/core/tests/switch_core/clients/test_send_media.py b/core/tests/switch_core/clients/test_send_media.pyindex dbb3a8122..5381be148 100644--- a/core/tests/switch_core/clients/test_send_media.py+++ b/core/tests/switch_core/clients/test_send_media.py@@ -1,66 +1,51 @@from __future__ import annotationsimport pytest-from nio import UploadErrorfrom switch_core.clients.client_base import ClientBase+from switch_core.transport import TransportError, UploadResult+from tests.switch_core.transport.fake import FakeMessageRecorder, FakeTransport-class _FakeSendResp:- def __init__(self, event_id: str) -> None:- self.event_id = event_id+class _FailingUploadTransport(FakeTransport):+ """Upload is the one media call that must not degrade to a None result."""+ async def upload_media(+ self, data: bytes, content_type: str, filename: str+ ) -> UploadResult:+ raise TransportError(f"Failed to upload media '{filename}'")-class _FakeUploadResp:- def __init__(self, content_uri: str) -> None:- self.content_uri = content_uri--class _FakeNio:- def __init__(self, *, upload_result: object) -> None:- self._upload_result = upload_result- self.room_send_calls: list[tuple[str, str, dict]] = []- self.upload_calls: list[dict] = []-- async def room_send(self, room_id: str, msgtype: str, content: dict):- self.room_send_calls.append((room_id, msgtype, content))- return _FakeSendResp("$evt")-- async def upload(self, **kwargs): # noqa: ANN003- self.upload_calls.append(kwargs)- return self._upload_result, None---def _client(nio: _FakeNio) -> ClientBase:+def _client(transport: FakeTransport) -> ClientBase:client = object.__new__(ClientBase)- client.nio_client = nio # type: ignore[attr-defined]+ client.transport = transport # type: ignore[attr-defined]client.display_name = "Alice" # type: ignore[attr-defined]+ client.matrix_user_id = "@alice:switch.local" # type: ignore[attr-defined]+ client.client_id = "client-1" # type: ignore[attr-defined]+ client.message_recorder = FakeMessageRecorder() # type: ignore[assignment]return clientasync def test_upload_media_returns_content_uri() -> None:- nio = _FakeNio(upload_result=_FakeUploadResp("mxc://s/abc"))- client = _client(nio)+ transport = FakeTransport(upload_uri="mxc://s/abc")+ client = _client(transport)mxc = await client.upload_media(b"bytes", "image/png", "cat.png")assert mxc == "mxc://s/abc"- assert nio.upload_calls[0]["content_type"] == "image/png"- assert nio.upload_calls[0]["filename"] == "cat.png"- assert nio.upload_calls[0]["filesize"] == 5+ assert transport.uploads == [(b"bytes", "image/png", "cat.png")]async def test_upload_media_raises_on_error() -> None:- nio = _FakeNio(upload_result=UploadError("nope"))- client = _client(nio)+ client = _client(_FailingUploadTransport())- with pytest.raises(RuntimeError, match="Failed to upload media"):+ with pytest.raises(TransportError, match="Failed to upload media"):await client.upload_media(b"bytes", "image/png", "cat.png")-async def test_send_media_with_caption_sets_body_and_filename() -> None:- nio = _FakeNio(upload_result=_FakeUploadResp("mxc://s/abc"))- client = _client(nio)+async def test_send_media_with_caption_passes_caption_and_filename_through() -> None:+ transport = FakeTransport()+ client = _client(transport)event_id = await client.send_media("!room",@@ -72,26 +57,38 @@ async def test_send_media_with_caption_sets_body_and_filename() -> None:caption="look at this",)- assert event_id == "$evt"- _, msgtype, content = nio.room_send_calls[0]- assert msgtype == "m.room.message"- assert content["msgtype"] == "m.image"- # Caption convention: body is the caption, filename carried separately.- assert content["body"] == "look at this"- assert content["filename"] == "cat.png"- assert content["url"] == "mxc://s/abc"- assert content["info"] == {"mimetype": "image/png", "size": 1234}- assert content["sender_name"] == "Alice"+ assert event_id == "$fake1"+ sent = transport.sent_media[0]+ assert sent["room_id"] == "!room"+ assert sent["msgtype"] == "m.image"+ # Caption convention: the caption travels beside the real filename, so the+ # transport can put one in `body` and carry the other separately.+ assert sent["caption"] == "look at this"+ assert sent["filename"] == "cat.png"+ assert sent["uri"] == "mxc://s/abc"+ assert sent["mimetype"] == "image/png"+ assert sent["size"] == 1234+ assert sent["sender_name"] == "Alice"-async def test_send_media_without_caption_uses_filename_as_body() -> None:- nio = _FakeNio(upload_result=_FakeUploadResp("mxc://s/abc"))- client = _client(nio)+async def test_send_media_without_caption_sends_no_caption() -> None:+ transport = FakeTransport()+ client = _client(transport)await client.send_media("!room", "mxc://s/abc", "cat.png", "image/png", 1234, msgtype="m.image")- _, _, content = nio.room_send_calls[0]- assert content["body"] == "cat.png"- assert "filename" not in content+ sent = transport.sent_media[0]+ assert sent["caption"] is None+ assert sent["filename"] == "cat.png"+++async def test_send_media_returns_none_when_the_transport_rejects_it() -> None:+ client = _client(FakeTransport(fail_send="nope"))++ result = await client.send_media(+ "!room", "mxc://s/abc", "cat.png", "image/png", 1234, msgtype="m.image"+ )++ assert result is Nonediff --git a/core/tests/switch_core/clients/test_send_recording.py b/core/tests/switch_core/clients/test_send_recording.pynew file mode 100644index 000000000..90ac04366--- /dev/null+++ b/core/tests/switch_core/clients/test_send_recording.py@@ -0,0 +1,136 @@+"""A client records every kind of send, and records nothing it did not send.++The recorder is only as good as the set of sends that reach it. Messages,+media and custom events each take a different route out of `ClientBase`, so+each is checked here rather than trusting that instrumenting one instrumented+the others.++The negative cases carry as much weight. A row for a message the transport+rejected would be a record of something that never happened, which is worse+than no record at all.+"""++from __future__ import annotations++import pytest++from switch_core.clients.client_base import ClientBase, ClientConfig+from switch_core.transport import TransportError+from tests.switch_core.transport.fake import FakeMessageRecorder, FakeTransport+++def _client(+ transport: FakeTransport,+) -> tuple[ClientBase[ClientConfig], FakeMessageRecorder]:+ recorder = FakeMessageRecorder()+ client: ClientBase[ClientConfig] = object.__new__(ClientBase)+ client.transport = transport+ client.message_recorder = recorder+ client.matrix_user_id = "@agent:test"+ client.client_id = "client-1"+ client.display_name = "agent one"+ return client, recorder+++class TestEverySendIsRecorded:+ async def test_a_message(self) -> None:+ transport = FakeTransport()+ client, recorder = _client(transport)++ event_id = await client.send_message("!room:test", "hello")++ assert len(recorder.recorded) == 1+ recorded = recorder.recorded[0]+ assert recorded["transport_room_id"] == "!room:test"+ assert recorded["result"].event_id == event_id+ assert recorded["result"].content["body"] == "hello"+ assert recorded["sender_matrix_id"] == "@agent:test"+ assert recorded["sender_client_id"] == "client-1"+ assert recorded["sender_name"] == "agent one"++ async def test_a_custom_event(self) -> None:+ transport = FakeTransport()+ client, recorder = _client(transport)++ event_id = await client.send_event(+ "!room:test", "com.switch.command", {"command": "reset"}+ )++ assert len(recorder.recorded) == 1+ result = recorder.recorded[0]["result"]+ assert result.event_id == event_id+ assert result.event_type == "com.switch.command"+ assert result.content == {"command": "reset"}++ async def test_media(self) -> None:+ transport = FakeTransport()+ client, recorder = _client(transport)++ event_id = await client.send_media(+ "!room:test",+ "mxc://test/abc",+ "chart.png",+ "image/png",+ 4096,+ msgtype="m.image",+ )++ assert len(recorder.recorded) == 1+ result = recorder.recorded[0]["result"]+ assert result.event_id == event_id+ assert result.content["url"] == "mxc://test/abc"++ async def test_what_is_recorded_is_what_the_transport_sent(self) -> None:+ """The recorder is handed the transport's own content dict.++ Reconstructing it at the client would drift from the transport the+ first time the wire format changed, and nothing would notice.+ """+ transport = FakeTransport()+ client, recorder = _client(transport)++ await client.send_message(+ "!room:test", "**bold**", format="markdown", thread_root_id="$root"+ )++ content = recorder.recorded[0]["result"].content+ assert content["m.relates_to"] == {+ "rel_type": "m.thread",+ "event_id": "$root",+ }+++class TestNothingIsRecordedForASendThatFailed:+ async def test_a_failed_message(self) -> None:+ transport = FakeTransport(fail_send="homeserver said no")+ client, recorder = _client(transport)++ assert await client.send_message("!room:test", "hello") is None+ assert recorder.recorded == []++ async def test_a_failed_media_send(self) -> None:+ transport = FakeTransport(fail_send="homeserver said no")+ client, recorder = _client(transport)++ result = await client.send_media(+ "!room:test",+ "mxc://test/abc",+ "chart.png",+ "image/png",+ 4096,+ msgtype="m.image",+ )++ assert result is None+ assert recorder.recorded == []++ async def test_a_failed_custom_event_raises_and_records_nothing(self) -> None:+ """Unlike a chat message, a custom event carries protocol state, so the+ caller is told rather than left to assume it landed."""+ transport = FakeTransport(fail_send="homeserver said no")+ client, recorder = _client(transport)++ with pytest.raises(TransportError):+ await client.send_event("!room:test", "com.switch.command", {})++ assert recorder.recorded == []diff --git a/core/tests/switch_core/clients/test_sync_cursor_persistence.py b/core/tests/switch_core/clients/test_sync_cursor_persistence.pyindex 4691e5ec5..0d4fe4743 100644--- a/core/tests/switch_core/clients/test_sync_cursor_persistence.py+++ b/core/tests/switch_core/clients/test_sync_cursor_persistence.py@@ -8,6 +8,11 @@ pool on an otherwise idle instance.Two properties fix that and are asserted here: an idle sync does not earn awrite at all, and the clients that do write are spread out rather than aligned.++Whether a given batch counted as idle is the transport's judgement, not this+one's — it is the only thing that can see what the batch held, and it says so+as the `durable` flag these tests pass in. What that flag is derived from is+covered in `tests/switch_core/transport/test_sync_durability.py`."""from __future__ import annotations@@ -15,15 +20,6 @@ from __future__ import annotationsimport timeimport pytest-from nio import (- DeviceList,- DeviceOneTimeKeyCount,- InviteInfo,- RoomInfo,- Rooms,- SyncResponse,- Timeline,-)from switch_core.clients.client_base import (SYNC_STATE_INTERVAL,@@ -31,6 +27,7 @@ from switch_core.clients.client_base import (SYNC_STATE_MAX_STALENESS,ClientBase,)+from tests.switch_core.transport.fake import FakeMessageRecorderROOM = "!room:switch.local"@@ -57,8 +54,6 @@ class _Store:session: object,client_id: str,*,- access_token: str | None,- device_id: str | None,next_batch_token: str | None,) -> None:self.writes.append(next_batch_token)@@ -81,6 +76,9 @@ class _Client(ClientBase):session_factory=_Session, # type: ignore[arg-type]client_store=_Store(), # type: ignore[arg-type]config=ClientBase.config_class(),+ transport_factory=lambda client: object(), # type: ignore[arg-type,return-value]+ session_state={},+ message_recorder=FakeMessageRecorder(),next_batch_token="s0",)# Pin the jittered interval so the throttle assertions are deterministic.@@ -92,39 +90,6 @@ class _Client(ClientBase):return store.writes-def _sync(- next_batch: str,- *,- timeline: list[object] | None = None,- state: list[object] | None = None,- ephemeral: list[object] | None = None,- invite: bool = False,- to_device: list[object] | None = None,-) -> SyncResponse:- join = {- ROOM: RoomInfo(- timeline=Timeline(- events=list(timeline or []), limited=False, prev_batch=None- ),- state=list(state or []),- ephemeral=list(ephemeral or []),- account_data=[],- )- }- return SyncResponse(- next_batch=next_batch,- rooms=Rooms(- invite={ROOM: InviteInfo(invite_state=[])} if invite else {},- join=join,- leave={},- ),- device_key_count=DeviceOneTimeKeyCount(curve25519=None, signed_curve25519=None),- device_list=DeviceList(changed=[], left=[]),- to_device_events=list(to_device or []),- presence_events=[],- )--@pytest.mark.asyncioasync def test_idle_sync_advances_the_cursor_without_writing() -> None:"""The overnight case: nothing happened, so nothing is worth persisting.@@ -136,7 +101,7 @@ async def test_idle_sync_advances_the_cursor_without_writing() -> None:client._last_sync_persist = time.monotonic() - 10 * SYNC_STATE_INTERVALfor i in range(1, 6):- await client._handle_sync(_sync(f"s{i}"))+ await client._handle_sync(f"s{i}", False)assert client.writes == []# The cursor still moved, so the next sync does not refetch.@@ -145,34 +110,24 @@ async def test_idle_sync_advances_the_cursor_without_writing() -> None:@pytest.mark.asyncio-async def test_ephemeral_only_sync_does_not_earn_a_write() -> None:+async def test_a_batch_the_transport_called_idle_does_not_earn_a_write() -> None:"""Typing notices and read receipts advance the token and mean nothing."""client = _Client()client._last_sync_persist = time.monotonic() - 10 * SYNC_STATE_INTERVAL- await client._handle_sync(_sync("s1", ephemeral=[object()]))+ await client._handle_sync("s1", False)assert client.writes == []assert client.next_batch_token == "s1"@pytest.mark.asyncio- "kwargs",- [- {"timeline": [object()]},- {"state": [object()]},- {"invite": True},- {"to_device": [object()]},- ],- ids=["timeline", "state", "invite", "to_device"],-)-async def test_durable_events_are_persisted(kwargs: dict[str, object]) -> None:+async def test_durable_events_are_persisted() -> None:"""Anything a restart would replay to a handler must move the cursor."""client = _Client()client._last_sync_persist = time.monotonic() - 10 * SYNC_STATE_INTERVAL- await client._handle_sync(_sync("s1", **kwargs)) # type: ignore[arg-type]+ await client._handle_sync("s1", True)assert client.writes == ["s1"]@@ -183,11 +138,11 @@ async def test_a_stale_cursor_is_flushed_even_while_idle() -> None:client = _Client()client._last_sync_persist = time.monotonic() - (SYNC_STATE_MAX_STALENESS - 1)- await client._handle_sync(_sync("s1"))+ await client._handle_sync("s1", False)assert client.writes == []client._last_sync_persist = time.monotonic() - (SYNC_STATE_MAX_STALENESS + 1)- await client._handle_sync(_sync("s2"))+ await client._handle_sync("s2", False)assert client.writes == ["s2"]assert client._sync_state_dirty is False@@ -199,9 +154,9 @@ async def test_busy_clients_are_still_throttled() -> None:client = _Client()client._last_sync_persist = time.monotonic() - 10 * SYNC_STATE_INTERVAL- await client._handle_sync(_sync("s1", timeline=[object()]))- await client._handle_sync(_sync("s2", timeline=[object()]))- await client._handle_sync(_sync("s3", timeline=[object()]))+ await client._handle_sync("s1", True)+ await client._handle_sync("s2", True)+ await client._handle_sync("s3", True)assert client.writes == ["s1"]assert client.next_batch_token == "s3"@@ -212,7 +167,7 @@ async def test_an_unchanged_cursor_is_ignored() -> None:client = _Client()client._last_sync_persist = time.monotonic() - 10 * SYNC_STATE_INTERVAL- await client._handle_sync(_sync("s0", timeline=[object()]))+ await client._handle_sync("s0", True)assert client.writes == []@@ -229,6 +184,9 @@ def _real_clients(count: int) -> list[ClientBase]:session_factory=None, # type: ignore[arg-type]client_store=None, # type: ignore[arg-type]config=ClientBase.config_class(),+ transport_factory=lambda client: object(), # type: ignore[arg-type,return-value]+ session_state={},+ message_recorder=FakeMessageRecorder(),)for i in range(count)]diff --git a/core/tests/switch_core/clients/test_system_message_never_addresses.py b/core/tests/switch_core/clients/test_system_message_never_addresses.pyindex 6eec62196..ae02e66a5 100644--- a/core/tests/switch_core/clients/test_system_message_never_addresses.py+++ b/core/tests/switch_core/clients/test_system_message_never_addresses.py@@ -23,17 +23,21 @@ import pytestfrom switch_core.clients.admin_messages import ADMIN_MARKER, admin_extra_contentfrom switch_core.clients.agent_client import AgentClientfrom switch_core.clients.room_meta import RoomMeta+from switch_core.delivery.addressing import AddressingResolver+from switch_core.transport import InboundMessage-def _event(body: str, *, admin: bool = False) -> SimpleNamespace:+def _event(body: str, *, admin: bool = False) -> InboundMessage:content: dict = {"body": body}if admin:content.update(admin_extra_content(None))- return SimpleNamespace(- body=body,- formatted_body=None,+ return InboundMessage(+ room_id="!room:server",+ event_id="$evt",sender="@switch-admin:switch.local",- source={"content": content},+ timestamp=1,+ content=content,+ body=body,)@@ -42,7 +46,12 @@ def _meta(channel_type: str) -> RoomMeta:def _client(name: str = "flintai-sdk.ts") -> SimpleNamespace:- client = SimpleNamespace(+ """A resolver with the two store-backed checks stubbed out.++ Only the name mention is left live: alias and role routing have their own+ tests, and what these pin is that the marker beats all three.+ """+ resolver = SimpleNamespace(agent=SimpleNamespace(name=name),matrix_user_id=f"@switch-agent-{name}:switch.local",)@@ -50,17 +59,31 @@ def _client(name: str = "flintai-sdk.ts") -> SimpleNamespace:async def _no(*_a: object, **_k: object) -> bool:return False- client._is_mentioned = lambda event: AgentClient._is_mentioned(client, event)- client._addressed_without_lookup = lambda event, meta: (- AgentClient._addressed_without_lookup(client, event, meta)+ resolver.mentions_name = lambda **kw: AddressingResolver.mentions_name(+ resolver, **kw+ )+ resolver.addressed_without_lookup = lambda **kw: (+ AddressingResolver.addressed_without_lookup(resolver, **kw)+ )+ resolver.mentions_alias = _no+ resolver.mentions_role = _no+ return resolver+++async def _addressed(+ resolver: SimpleNamespace, event: InboundMessage, meta: RoomMeta+) -> bool:+ # `object()` stands in for the session the caller owns: the marker and the+ # name mention are answered before any store is consulted.+ return await AddressingResolver.addresses(+ resolver,+ object(),+ agent=resolver.agent,+ agent_matrix_id=resolver.matrix_user_id,+ room_id=meta.room_id,+ channel_type=meta.channel_type,+ message=AgentClient._as_incoming(event),)- client._is_mentioned_via_alias = _no- client._is_mentioned_via_role = _no- return client---async def _addressed(client: SimpleNamespace, event: object, meta: RoomMeta) -> bool:- return await AgentClient._compute_addressed(client, None, event, meta)@pytest.mark.asyncio@@ -103,7 +126,7 @@ async def test_the_marker_alone_is_enough_whatever_type_it_carries() -> None:from switch_core.clients.admin_messages import AdminMessageTypeevent = _event("Added flintai-sdk.ts to this room.")- event.source["content"].update(admin_extra_content(AdminMessageType.COMMAND_RESULT))- assert ADMIN_MARKER in event.source["content"]+ event.content.update(admin_extra_content(AdminMessageType.COMMAND_RESULT))+ assert ADMIN_MARKER in event.contentassert await _addressed(_client(), event, _meta("direct")) is Falsediff --git a/core/tests/switch_core/clients/test_wait_joined_existing_membership.py b/core/tests/switch_core/clients/test_wait_joined_existing_membership.pyindex 0f970e225..6ff386e4b 100644--- a/core/tests/switch_core/clients/test_wait_joined_existing_membership.py+++ b/core/tests/switch_core/clients/test_wait_joined_existing_membership.py@@ -1,32 +1,31 @@from __future__ import annotationsimport asyncio-from types import SimpleNamespaceimport pytest-from nio import JoinedRoomsErrorfrom switch_core.clients.client_base import ClientBase+from tests.switch_core.transport.fake import FakeTransportMATRIX_ROOM_ID = "!matrix:switch.local"-class _FakeNioClient:- def __init__(self, rooms: list[str] | None) -> None:- self._rooms = rooms+class _CountingTransport(FakeTransport):+ """Counts membership lookups so the caching assertions stay meaningful."""++ def __init__(self, joined: list[str]) -> None:+ super().__init__(joined=joined)self.calls = 0- async def joined_rooms(self) -> object:+ async def joined_rooms(self) -> list[str]:self.calls += 1- if self._rooms is None:- return JoinedRoomsError(message="boom")- return SimpleNamespace(rooms=list(self._rooms))+ return await super().joined_rooms()-def _client(nio_client: _FakeNioClient) -> ClientBase:+def _client(transport: FakeTransport) -> ClientBase:client = ClientBase.__new__(ClientBase)client.matrix_user_id = "@ext_alice:switch.local"- client.nio_client = nio_client+ client.transport = transportclient.room_join_times = {}client._room_joined_events = {}client._startup_ts = 1000@@ -37,23 +36,22 @@ async def test_wait_joined_accepts_membership_that_predates_this_process() -> No"""A puppet joined in an earlier run replays no member event: the clientresumes from a stored next_batch token, and re-inviting an existing memberis a no-op. Waiting on sync alone times out and the message is dropped."""- nio_client = _FakeNioClient([MATRIX_ROOM_ID])- client = _client(nio_client)+ transport = _CountingTransport([MATRIX_ROOM_ID])+ client = _client(transport)assert await client.wait_joined(MATRIX_ROOM_ID, 0.05) is True- assert nio_client.calls == 1+ assert transport.calls == 1# The join predates startup, so it must not shift the ignore cutoff forward# and suppress events already in flight.assert client.room_join_times[MATRIX_ROOM_ID] == client._startup_ts# Membership is cached — no second round trip.assert await client.wait_joined(MATRIX_ROOM_ID, 0.05) is True- assert nio_client.calls == 1+ assert transport.calls == 1async def test_wait_joined_still_waits_for_a_pending_join() -> None:- nio_client = _FakeNioClient([])- client = _client(nio_client)+ client = _client(_CountingTransport([]))async def join_late() -> None:await asyncio.sleep(0.01)@@ -65,16 +63,20 @@ async def test_wait_joined_still_waits_for_a_pending_join() -> None:async def test_wait_joined_times_out_when_the_join_never_lands() -> None:- client = _client(_FakeNioClient([]))+ client = _client(_CountingTransport([]))assert await client.wait_joined(MATRIX_ROOM_ID, 0.05) is False-async def test_wait_joined_falls_back_to_waiting_when_the_lookup_fails() -> None:- nio_client = _FakeNioClient(None)- client = _client(nio_client)+async def test_wait_joined_falls_back_to_waiting_when_the_lookup_reports_nothing() -> (+ None+):+ """A failed membership lookup degrades to "no rooms" at the transport, so+ the client must wait rather than record a join it never observed."""+ transport = _CountingTransport([])+ client = _client(transport)assert await client.wait_joined(MATRIX_ROOM_ID, 0.05) is False- assert nio_client.calls == 1+ assert transport.calls == 1assert MATRIX_ROOM_ID not in client.room_join_timesdiff --git a/core/tests/switch_core/db/stores/test_delivery_cursor_store.py b/core/tests/switch_core/db/stores/test_delivery_cursor_store.pynew file mode 100644index 000000000..9736f7352--- /dev/null+++ b/core/tests/switch_core/db/stores/test_delivery_cursor_store.py@@ -0,0 +1,146 @@+"""A delivery cursor moves forward and only forward."""++from __future__ import annotations++import uuid++from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker++from switch_core.db.models import Agent, ApiKey, Client, Room, User+from switch_core.db.stores.delivery_cursor_store import DeliveryCursorStore+++async def _agent(session: AsyncSession) -> Agent:+ """Minimal User → ApiKey → Client → Agent chain."""+ name = f"agent-{uuid.uuid4().hex[:8]}"+ user = User(name=name, email=f"{name}@test", role="user", password_hash="x")+ session.add(user)+ await session.flush()+ api_key = ApiKey(+ user_id=user.id,+ key_hash=f"hash-{name}",+ encrypted_key="enc",+ label=name,+ type="agent",+ )+ client = Client(+ matrix_user_id=f"@{name}:test", display_name=name, type="agent", password="x"+ )+ session.add_all([api_key, client])+ await session.flush()+ agent = Agent(+ name=name,+ description="",+ agent_type="always_on",+ connector_type="claude_code",+ integration_profile={"connection_model": "always_on"},+ client_id=client.id,+ api_key_id=api_key.id,+ )+ session.add(agent)+ await session.flush()+ return agent+++async def _make_agent_and_room(session: AsyncSession) -> tuple[str, str]:+ room = Room(+ matrix_room_id=f"!room-{uuid.uuid4().hex[:8]}:test",+ name="a room",+ description="",+ )+ session.add(room)+ agent = await _agent(session)+ await session.flush()+ return agent.id, room.id+++class TestPosition:+ async def test_an_agent_that_was_never_delivered_is_at_zero(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """Zero, not an error: `seq` starts at 1, so zero already says+ "behind everything"."""+ async with session_factory() as session:+ agent_id, room_id = await _make_agent_and_room(session)+ await session.commit()++ store = DeliveryCursorStore()+ assert await store.position(session, agent_id, room_id) == 0++ async def test_a_cursor_reads_back_where_it_was_left(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ agent_id, room_id = await _make_agent_and_room(session)+ store = DeliveryCursorStore()+ await store.advance(session, agent_id, room_id, 7)+ await session.commit()++ assert await store.position(session, agent_id, room_id) == 7++ async def test_positions_omit_agents_that_have_none(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """Absent rather than zero, so a caller can tell an agent that has+ never been delivered from one sitting at the start."""+ async with session_factory() as session:+ first, room_id = await _make_agent_and_room(session)+ second = await _agent(session)+ session.add(second)+ await session.flush()++ store = DeliveryCursorStore()+ await store.advance(session, first, room_id, 3)+ await session.commit()++ positions = await store.positions_in(session, room_id, [first, second.id])++ assert positions == {first: 3}+++class TestAdvancing:+ async def test_advancing_twice_keeps_the_further_position(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ agent_id, room_id = await _make_agent_and_room(session)+ store = DeliveryCursorStore()+ await store.advance(session, agent_id, room_id, 4)+ await store.advance(session, agent_id, room_id, 9)+ await session.commit()++ assert await store.position(session, agent_id, room_id) == 9++ async def test_a_late_write_cannot_rewind_the_cursor(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """Two deliveries can finish out of order. The later write must not+ undo the further one, because rewinding redelivers and a redelivered+ message is indistinguishable from a new one."""+ async with session_factory() as session:+ agent_id, room_id = await _make_agent_and_room(session)+ store = DeliveryCursorStore()+ await store.advance(session, agent_id, room_id, 9)+ await store.advance(session, agent_id, room_id, 4)+ await session.commit()++ assert await store.position(session, agent_id, room_id) == 9++ async def test_cursors_in_different_rooms_are_independent(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ agent_id, first_room = await _make_agent_and_room(session)+ second_room = Room(+ matrix_room_id=f"!room-{uuid.uuid4().hex[:8]}:test",+ name="another room",+ description="",+ )+ session.add(second_room)+ await session.flush()++ store = DeliveryCursorStore()+ await store.advance(session, agent_id, first_room, 5)+ await session.commit()++ assert await store.position(session, agent_id, second_room.id) == 0diff --git a/core/tests/switch_core/db/stores/test_message_store.py b/core/tests/switch_core/db/stores/test_message_store.pynew file mode 100644index 000000000..3e1507b35--- /dev/null+++ b/core/tests/switch_core/db/stores/test_message_store.py@@ -0,0 +1,458 @@+"""`MessageStore` against real Postgres.++Catches the mistakes a mock or SQLite cannot: an attachment order that only+holds by accident of insertion, a `seq` that is not a gap-free total order to+page on, a `transport_event_id` that admits a duplicate, and FK actions+(`ON DELETE CASCADE` / `SET NULL`) that are declared but not enforced.+"""++from __future__ import annotations++import asyncio+import uuid++import pytest+from sqlalchemy import delete+from sqlalchemy.exc import IntegrityError+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker++from switch_core.db.models import Client, Message, MessageAttachment, Room+from switch_core.db.stores.message_store import MessageStore+++async def _make_room(session: AsyncSession, name: str) -> Room:+ room = Room(+ matrix_room_id=f"!{name}-{uuid.uuid4().hex[:8]}:test",+ name=name,+ description=f"{name} desc",+ )+ session.add(room)+ await session.flush()+ return room+++async def _make_client(session: AsyncSession, name: str) -> Client:+ client = Client(+ matrix_user_id=f"@{name}-{uuid.uuid4().hex[:8]}:test",+ display_name=name,+ type="agent",+ password="x",+ )+ session.add(client)+ await session.flush()+ return client+++def _message(room_id: str, event_id: str, **overrides: object) -> Message:+ fields: dict[str, object] = {+ "room_id": room_id,+ "transport_event_id": event_id,+ "sender_matrix_id": "@sender:test",+ "event_type": "m.room.message",+ "msgtype": "m.text",+ "body": f"body of {event_id}",+ "content": {"msgtype": "m.text", "body": f"body of {event_id}"},+ }+ fields.update(overrides)+ return Message(**fields)+++class TestCreate:+ async def test_create_and_read_back_by_transport_event_id(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ store = MessageStore()+ async with session_factory() as session:+ room = await _make_room(session, "alpha")+ await store.create(session, _message(room.id, "$evt1"), [])+ await session.commit()++ found = await store.get_by_transport_event_id(session, "$evt1")++ assert found is not None+ assert found.room_id == room.id+ assert found.body == "body of $evt1"+ assert found.content == {"msgtype": "m.text", "body": "body of $evt1"}+ assert found.sent_at is not None++ async def test_miss_returns_none(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ store = MessageStore()+ async with session_factory() as session:+ assert await store.get_by_transport_event_id(session, "$nope") is None++ async def test_duplicate_transport_event_id_rejected(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """The same send recorded twice must not produce two rows."""+ store = MessageStore()+ async with session_factory() as session:+ room = await _make_room(session, "alpha")+ await store.create(session, _message(room.id, "$dup"), [])+ await session.commit()++ with pytest.raises(IntegrityError):+ await store.create(session, _message(room.id, "$dup"), [])+++class TestAttachments:+ async def test_attachments_numbered_and_returned_in_send_order(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ store = MessageStore()+ async with session_factory() as session:+ room = await _make_room(session, "alpha")+ message = await store.create(+ session,+ _message(room.id, "$files"),+ [+ MessageAttachment(uri="mxc://a", filename="a.txt"),+ MessageAttachment(uri="mxc://b", filename="b.txt"),+ MessageAttachment(uri="mxc://c", filename="c.txt"),+ ],+ )+ await session.commit()++ attachments = await store.get_attachments(session, message.id)++ assert [a.position for a in attachments] == [0, 1, 2]+ assert [a.filename for a in attachments] == ["a.txt", "b.txt", "c.txt"]++ async def test_get_attachments_orders_by_position_not_insertion(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """Rows written out of order still read back in send order."""+ store = MessageStore()+ async with session_factory() as session:+ room = await _make_room(session, "alpha")+ message = await store.create(session, _message(room.id, "$files"), [])+ await session.commit()++ for position, name in ((2, "c.txt"), (0, "a.txt"), (1, "b.txt")):+ session.add(+ MessageAttachment(+ message_id=message.id,+ position=position,+ uri=f"mxc://{name}",+ filename=name,+ )+ )+ await session.commit()++ attachments = await store.get_attachments(session, message.id)++ assert [a.filename for a in attachments] == ["a.txt", "b.txt", "c.txt"]++ async def test_attachments_scoped_to_their_message(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ store = MessageStore()+ async with session_factory() as session:+ room = await _make_room(session, "alpha")+ first = await store.create(+ session,+ _message(room.id, "$one"),+ [MessageAttachment(uri="mxc://a", filename="a.txt")],+ )+ second = await store.create(+ session,+ _message(room.id, "$two"),+ [MessageAttachment(uri="mxc://b", filename="b.txt")],+ )+ await session.commit()++ assert [+ a.filename for a in await store.get_attachments(session, first.id)+ ] == ["a.txt"]+ assert [+ a.filename for a in await store.get_attachments(session, second.id)+ ] == ["b.txt"]+++class TestSeq:+ async def test_seq_is_database_assigned_and_strictly_increasing(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ store = MessageStore()+ async with session_factory() as session:+ room = await _make_room(session, "alpha")+ messages = [+ await store.create(session, _message(room.id, f"$evt{i}"), [])+ for i in range(5)+ ]+ await session.commit()+ seqs = [m.seq for m in messages]++ assert all(seq is not None for seq in seqs)+ assert seqs == sorted(seqs)+ assert len(set(seqs)) == len(seqs)++ async def test_the_store_owns_seq_not_the_caller(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """A caller that picked its own number could hand a reader a value it+ has already paged past."""+ store = MessageStore()+ async with session_factory() as session:+ room = await _make_room(session, "alpha")+ created = await store.create(+ session, _message(room.id, "$forced", seq=999), []+ )+ await session.commit()++ assert created.seq == 1++ async def test_seq_starts_at_one_in_every_room(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """Numbering is per room, so one busy room does not push another+ room's first message to a large number."""+ store = MessageStore()+ async with session_factory() as session:+ room_a = await _make_room(session, "alpha")+ room_b = await _make_room(session, "beta")+ a1 = await store.create(session, _message(room_a.id, "$a1"), [])+ a2 = await store.create(session, _message(room_a.id, "$a2"), [])+ b1 = await store.create(session, _message(room_b.id, "$b1"), [])+ await session.commit()++ assert (a1.seq, a2.seq, b1.seq) == (1, 2, 1)++ async def test_two_rooms_may_hold_the_same_seq(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """The uniqueness that matters is per room. A global constraint would+ reject this, and it is not a conflict."""+ store = MessageStore()+ async with session_factory() as session:+ room_a = await _make_room(session, "alpha")+ room_b = await _make_room(session, "beta")+ await store.create(session, _message(room_a.id, "$a1"), [])+ await store.create(session, _message(room_b.id, "$b1"), [])+ await session.commit()++ async def test_a_room_cannot_hold_the_same_seq_twice(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """The constraint is what makes the cursor trustworthy, so prove it is+ really on the table rather than only in the store's arithmetic."""+ store = MessageStore()+ async with session_factory() as session:+ room = await _make_room(session, "alpha")+ await store.create(session, _message(room.id, "$a1"), [])+ await session.commit()+ room_id = room.id++ async with session_factory() as session:+ duplicate = _message(room_id, "$a2", seq=1)+ session.add(duplicate)+ with pytest.raises(IntegrityError):+ await session.commit()+++class TestSeqUnderConcurrency:+ """The reason `seq` is not an identity column.++ A sequence allocates when the INSERT runs, so two concurrent writers take+ their numbers immediately and may commit in the other order — leaving a+ row visible only *behind* a cursor that has already moved past it. These+ tests hold one transaction open and watch what the other one does, which+ is the only way to tell the two designs apart.+ """++ async def test_a_second_writer_to_the_same_room_waits(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ store = MessageStore()+ async with session_factory() as session:+ room = await _make_room(session, "alpha")+ await session.commit()+ room_id = room.id++ async with session_factory() as holder:+ first = await store.create(holder, _message(room_id, "$first"), [])+ assert first.seq == 1++ async with session_factory() as waiter:+ blocked = asyncio.ensure_future(+ store.create(waiter, _message(room_id, "$second"), [])+ )+ with pytest.raises(TimeoutError):+ await asyncio.wait_for(asyncio.shield(blocked), timeout=0.5)++ # Releasing the lock is what lets the second writer number+ # itself, and it can only do so after the first is committed.+ await holder.commit()+ second = await blocked+ await waiter.commit()++ assert second.seq == 2++ async def test_writers_to_different_rooms_do_not_wait(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """Serialising every room against every other one would make this a+ global write lock, which is not the trade being made."""+ store = MessageStore()+ async with session_factory() as session:+ room_a = await _make_room(session, "alpha")+ room_b = await _make_room(session, "beta")+ await session.commit()+ room_a_id, room_b_id = room_a.id, room_b.id++ async with session_factory() as holder, session_factory() as other:+ await store.create(holder, _message(room_a_id, "$a1"), [])+ created = await asyncio.wait_for(+ store.create(other, _message(room_b_id, "$b1"), []), timeout=5+ )+ await other.commit()+ await holder.commit()++ assert created.seq == 1+++class TestListForRoom:+ async def test_pages_on_after_seq_without_gap_or_repeat(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ store = MessageStore()+ async with session_factory() as session:+ room = await _make_room(session, "alpha")+ for i in range(10):+ await store.create(session, _message(room.id, f"$evt{i}"), [])+ await session.commit()++ first_page = await store.list_for_room(+ session, room.id, after_seq=0, limit=4+ )+ second_page = await store.list_for_room(+ session, room.id, after_seq=first_page[-1].seq, limit=4+ )+ third_page = await store.list_for_room(+ session, room.id, after_seq=second_page[-1].seq, limit=4+ )+ past_the_end = await store.list_for_room(+ session, room.id, after_seq=third_page[-1].seq, limit=4+ )++ assert [m.transport_event_id for m in first_page] == [+ f"$evt{i}" for i in range(4)+ ]+ assert [m.transport_event_id for m in second_page] == [+ f"$evt{i}" for i in range(4, 8)+ ]+ assert [m.transport_event_id for m in third_page] == ["$evt8", "$evt9"]+ assert past_the_end == []++ seen = [m.seq for m in first_page + second_page + third_page]+ assert seen == sorted(seen)+ assert len(set(seen)) == 10++ async def test_scoped_to_one_room(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ store = MessageStore()+ async with session_factory() as session:+ room_a = await _make_room(session, "alpha")+ room_b = await _make_room(session, "beta")+ for i in range(3):+ await store.create(session, _message(room_a.id, f"$a{i}"), [])+ await store.create(session, _message(room_b.id, f"$b{i}"), [])+ await session.commit()++ in_a = await store.list_for_room(session, room_a.id, after_seq=0, limit=50)+ in_b = await store.list_for_room(session, room_b.id, after_seq=0, limit=50)++ assert [m.transport_event_id for m in in_a] == ["$a0", "$a1", "$a2"]+ assert [m.transport_event_id for m in in_b] == ["$b0", "$b1", "$b2"]++ async def test_after_seq_from_another_room_does_not_skip_rows(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """`seq` is global, so a cursor is only meaningful within its own room;+ rows interleaved from another room must not consume the page."""+ store = MessageStore()+ async with session_factory() as session:+ room_a = await _make_room(session, "alpha")+ room_b = await _make_room(session, "beta")+ await store.create(session, _message(room_a.id, "$a0"), [])+ for i in range(5):+ await store.create(session, _message(room_b.id, f"$b{i}"), [])+ await store.create(session, _message(room_a.id, "$a1"), [])+ await session.commit()++ page = await store.list_for_room(session, room_a.id, after_seq=0, limit=1)+ following = await store.list_for_room(+ session, room_a.id, after_seq=page[-1].seq, limit=10+ )++ assert [m.transport_event_id for m in page] == ["$a0"]+ assert [m.transport_event_id for m in following] == ["$a1"]+++class TestForeignKeyBehaviour:+ async def test_deleting_the_room_cascades_its_messages(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ store = MessageStore()+ async with session_factory() as session:+ room = await _make_room(session, "alpha")+ keeper = await _make_room(session, "beta")+ await store.create(session, _message(room.id, "$gone"), [])+ await store.create(session, _message(keeper.id, "$kept"), [])+ await session.commit()++ await session.execute(delete(Room).where(Room.id == room.id))+ await session.commit()++ assert await store.get_by_transport_event_id(session, "$gone") is None+ assert await store.get_by_transport_event_id(session, "$kept") is not None++ async def test_deleting_the_message_cascades_its_attachments(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ store = MessageStore()+ async with session_factory() as session:+ room = await _make_room(session, "alpha")+ message = await store.create(+ session,+ _message(room.id, "$files"),+ [+ MessageAttachment(uri="mxc://a", filename="a.txt"),+ MessageAttachment(uri="mxc://b", filename="b.txt"),+ ],+ )+ await session.commit()+ message_id = message.id++ await session.execute(delete(Message).where(Message.id == message_id))+ await session.commit()++ assert await store.get_attachments(session, message_id) == []++ async def test_deleting_the_sender_client_nulls_the_reference(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """History outlives the client that wrote it: the row stays, the link+ goes."""+ store = MessageStore()+ async with session_factory() as session:+ room = await _make_room(session, "alpha")+ client = await _make_client(session, "writer")+ await store.create(+ session,+ _message(room.id, "$byclient", sender_client_id=client.id),+ [],+ )+ await session.commit()++ await session.execute(delete(Client).where(Client.id == client.id))+ await session.commit()+ session.expire_all()++ found = await store.get_by_transport_event_id(session, "$byclient")++ assert found is not None+ assert found.sender_client_id is None+ assert found.sender_matrix_id == "@sender:test"diff --git a/core/tests/switch_core/db/stores/test_room_membership_write.py b/core/tests/switch_core/db/stores/test_room_membership_write.pynew file mode 100644index 000000000..669edf94e--- /dev/null+++ b/core/tests/switch_core/db/stores/test_room_membership_write.py@@ -0,0 +1,81 @@+"""Recording a membership twice is success, not a failed transaction.++Over Matrix an invitation was accepted later, over sync, so `room_service` was+effectively the only writer of `client_rooms`. On the Postgres transport the+invitation *is* the join: the client writes the row synchronously, and the+inviting caller then writes it again in a transaction that also creates the+room's agents. A plain insert turned that into an IntegrityError, rolled the+whole thing back, and left an agent a client member of a room but not one of+its agents — receiving messages while `!list-agents` reported nobody.+"""++from __future__ import annotations++import uuid++from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker++from switch_core.db.models import Client, Room+from switch_core.db.stores.room_store import RoomStore+++async def _client_and_room(session: AsyncSession) -> tuple[str, str]:+ client = Client(+ matrix_user_id=f"@someone-{uuid.uuid4().hex[:8]}:test",+ display_name="someone",+ type="agent",+ password="x",+ )+ room = Room(+ matrix_room_id=f"!{uuid.uuid4().hex[:8]}:test",+ name="a room",+ description="",+ )+ session.add_all([client, room])+ await session.flush()+ return client.id, room.id+++class TestAddClient:+ async def test_recording_the_same_membership_twice_succeeds(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ client_id, room_id = await _client_and_room(session)+ await session.commit()++ async with session_factory() as session:+ await RoomStore().add_client(session, client_id, room_id)+ await session.commit()++ async with session_factory() as session:+ await RoomStore().add_client(session, client_id, room_id)+ # Whatever else the caller is doing in this transaction has to+ # survive: the second write is the case that broke /invite-agent.+ await session.commit()++ async with session_factory() as session:+ assert await RoomStore().get_client_ids(session, room_id) == [client_id]++ async def test_a_second_write_does_not_poison_the_caller_s_transaction(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """The failure that mattered was not the duplicate — it was the work+ alongside it being rolled back."""+ async with session_factory() as session:+ client_id, room_id = await _client_and_room(session)+ await RoomStore().add_client(session, client_id, room_id)+ await session.commit()++ async with session_factory() as session:+ await RoomStore().add_client(session, client_id, room_id)+ await RoomStore().add_agents(session, room_id, [])+ room = await RoomStore().get(session, room_id)+ assert room is not None+ room.description = "written alongside the duplicate"+ await session.commit()++ async with session_factory() as session:+ room = await RoomStore().get(session, room_id)+ assert room is not None+ assert room.description == "written alongside the duplicate"diff --git a/core/tests/switch_core/gateway/test_room_resource_read_authz.py b/core/tests/switch_core/gateway/test_room_resource_read_authz.pyindex 3614f7273..fd9dbce9b 100644--- a/core/tests/switch_core/gateway/test_room_resource_read_authz.py+++ b/core/tests/switch_core/gateway/test_room_resource_read_authz.py@@ -19,6 +19,7 @@ from switch_core.db.stores.agent_store import AgentStorefrom switch_core.db.stores.document_store import DocumentStorefrom switch_core.db.stores.package_store import PackageStorefrom switch_core.db.stores.reference_store import ReferenceStore+from switch_core.db.stores.reference_type_store import ReferenceTypeStorefrom switch_core.db.stores.room_link_store import RoomLinkStorefrom switch_core.db.stores.room_store import RoomStorefrom switch_core.db.stores.user_store import UserStore@@ -38,6 +39,7 @@ _AGENT_STORE = AgentStore()def _svc(session_factory: async_sessionmaker[AsyncSession]) -> ResourceService:return ResourceService(reference_store=ReferenceStore(),+ reference_type_store=ReferenceTypeStore(),document_store=DocumentStore(),package_store=PackageStore(),room_link_store=RoomLinkStore(),diff --git a/core/tests/switch_core/messages/__init__.py b/core/tests/switch_core/messages/__init__.pynew file mode 100644index 000000000..e69de29bbdiff --git a/core/tests/switch_core/messages/test_backfill.py b/core/tests/switch_core/messages/test_backfill.pynew file mode 100644index 000000000..9da30a4d8--- /dev/null+++ b/core/tests/switch_core/messages/test_backfill.py@@ -0,0 +1,455 @@+"""Reconstructed history lands in the right order, below the live log.++The two properties that matter most are the ones a careless implementation+gets wrong in ways nobody notices for weeks: the numbering must run the same+way time does, and running the walk twice must not double the room.+"""++from __future__ import annotations++import uuid+from datetime import UTC, datetime, timedelta++from sqlalchemy import select+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker++from switch_core.cli.backfill import _ReadOnlyStore+from switch_core.db.models import Message, Room+from switch_core.db.stores.message_store import MessageStore+from switch_core.messages import backfill_room+from switch_core.transport import (+ HistoryPage,+ InboundCustomEvent,+ InboundMedia,+ InboundMembership,+ InboundMessage,+)++BASE = datetime(2026, 1, 1, 12, 0, tzinfo=UTC)+++class PagingTransport:+ """Replays fixed pages of backwards history, newest first."""++ def __init__(self, pages: list[HistoryPage]) -> None:+ self._pages = pages+ self.reads = 0++ async def read_history(+ self, room_id: str, *, start: str | None, limit: int+ ) -> HistoryPage:+ page = self._pages[min(self.reads, len(self._pages) - 1)]+ self.reads += 1+ return page+++def _at(seconds: int) -> datetime:+ return BASE + timedelta(seconds=seconds)+++def _ms(seconds: int) -> int:+ return int(_at(seconds).timestamp() * 1000)+++def _event(event_id: str, at: int, body: str = "hello", **overrides: object): # type: ignore[no-untyped-def]+ fields: dict[str, object] = {+ "room_id": "!room:test",+ "event_id": event_id,+ "sender": "@a:test",+ "timestamp": _ms(at),+ "content": {"body": body, "sender_name": "Alice"},+ "body": body,+ "msgtype": "m.text",+ }+ fields.update(overrides)+ return InboundMessage(**fields) # type: ignore[arg-type]+++async def _make_room(session: AsyncSession) -> Room:+ room = Room(+ matrix_room_id=f"!room-{uuid.uuid4().hex[:8]}:test",+ name="a room",+ description="",+ )+ session.add(room)+ await session.commit()+ return room+++async def _rows(+ session_factory: async_sessionmaker[AsyncSession], room_id: str+) -> list[Message]:+ async with session_factory() as session:+ result = await session.execute(+ select(Message).where(Message.room_id == room_id).order_by(Message.seq)+ )+ return list(result.scalars().all())+++class TestNumbering:+ async def test_history_is_numbered_below_the_live_log(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """A message from before recording must not outrank one from after it.++ Ordering is by `seq`, so a positive number on reconstructed history+ would put last month at the top of every read.+ """+ store = MessageStore()+ async with session_factory() as session:+ room = await _make_room(session)+ live = Message(+ room_id=room.id,+ transport_event_id="$live",+ sender_matrix_id="@a:test",+ event_type="m.room.message",+ msgtype="m.text",+ body="today",+ content={},+ sent_at=_at(100),+ )+ await store.create(session, live, [])+ await session.commit()++ transport = PagingTransport(+ [HistoryPage(events=[_event("$old", 10, "yesterday")], next_token=None)]+ )+ async with session_factory() as session:+ room = await session.get(Room, room.id) # type: ignore[assignment]+ await backfill_room(transport, session_factory, room, store=store)++ rows = await _rows(session_factory, room.id)+ assert [(r.seq, r.body) for r in rows] == [(-1, "yesterday"), (1, "today")]++ async def test_the_oldest_message_gets_the_lowest_number(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """Numbering has to run the same way time does, across pages as well as+ within them — a walk that numbered per page would interleave."""+ store = MessageStore()+ async with session_factory() as session:+ room = await _make_room(session)++ transport = PagingTransport(+ [+ HistoryPage(+ events=[_event("$d", 40, "d"), _event("$c", 30, "c")],+ next_token="t1",+ ),+ HistoryPage(+ events=[_event("$b", 20, "b"), _event("$a", 10, "a")],+ next_token=None,+ ),+ ]+ )+ async with session_factory() as session:+ room = await session.get(Room, room.id) # type: ignore[assignment]+ await backfill_room(transport, session_factory, room, store=store)++ rows = await _rows(session_factory, room.id)+ assert [r.body for r in rows] == ["a", "b", "c", "d"]+ assert [r.seq for r in rows] == [-4, -3, -2, -1]++ async def test_the_timestamp_is_when_it_was_sent_not_when_it_was_written(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """The read path filters on `sent_at`. Stamping the backfill's own+ clock would pile a year of history onto tonight."""+ store = MessageStore()+ async with session_factory() as session:+ room = await _make_room(session)++ transport = PagingTransport(+ [HistoryPage(events=[_event("$a", 10)], next_token=None)]+ )+ async with session_factory() as session:+ room = await session.get(Room, room.id) # type: ignore[assignment]+ await backfill_room(transport, session_factory, room, store=store)++ rows = await _rows(session_factory, room.id)+ assert rows[0].sent_at == _at(10)+++class TestCompletionMark:+ """A room is marked done only by a walk that really wrote it.++ The mark is what stops a re-run re-reading every page of every room. It is+ also what a dry run must not leave behind: the documented first step is a+ dry run, and if that marked every room, the real run afterwards would find+ nothing to do and say so as though the work were finished.+ """++ async def test_a_completed_walk_marks_the_room(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ room = await _make_room(session)++ transport = PagingTransport(+ [HistoryPage(events=[_event("$a", 10, "a")], next_token=None)]+ )+ async with session_factory() as session:+ room = await session.get(Room, room.id) # type: ignore[assignment]+ await backfill_room(transport, session_factory, room, store=MessageStore())++ async with session_factory() as session:+ written = await session.get(Room, room.id)+ assert written is not None+ assert written.history_backfilled_at is not None++ async def test_a_dry_run_marks_nothing(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """Otherwise the dry run disables the real one, silently."""+ async with session_factory() as session:+ room = await _make_room(session)++ transport = PagingTransport(+ [HistoryPage(events=[_event("$a", 10, "a")], next_token=None)]+ )+ async with session_factory() as session:+ room = await session.get(Room, room.id) # type: ignore[assignment]+ report = await backfill_room(+ transport, session_factory, room, store=_ReadOnlyStore()+ )++ assert report.written == 1+ async with session_factory() as session:+ untouched = await session.get(Room, room.id)+ assert untouched is not None+ assert untouched.history_backfilled_at is None+ assert await _rows(session_factory, room.id) == []+++class TestIdempotence:+ async def test_running_it_twice_writes_nothing_the_second_time(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """A long walk that fails halfway should be safe to just run again."""+ store = MessageStore()+ async with session_factory() as session:+ room = await _make_room(session)++ def _transport() -> PagingTransport:+ return PagingTransport(+ [+ HistoryPage(+ events=[_event("$b", 20, "b"), _event("$a", 10, "a")],+ next_token=None,+ )+ ]+ )++ async with session_factory() as session:+ room = await session.get(Room, room.id) # type: ignore[assignment]+ first = await backfill_room(+ _transport(), session_factory, room, store=store+ )+ second = await backfill_room(+ _transport(), session_factory, room, store=store+ )++ assert (first.written, first.already_present) == (2, 0)+ assert (second.written, second.already_present) == (0, 2)+ assert len(await _rows(session_factory, room.id)) == 2++ async def test_a_message_already_recorded_live_is_left_alone(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """The walk overlaps the recorded window by design — it starts at the+ newest message on the bus, not at the oldest row."""+ store = MessageStore()+ async with session_factory() as session:+ room = await _make_room(session)+ live = Message(+ room_id=room.id,+ transport_event_id="$b",+ sender_matrix_id="@a:test",+ event_type="m.room.message",+ msgtype="m.text",+ body="b",+ content={},+ sent_at=_at(20),+ )+ await store.create(session, live, [])+ await session.commit()++ transport = PagingTransport(+ [+ HistoryPage(+ events=[_event("$b", 20, "b"), _event("$a", 10, "a")],+ next_token=None,+ )+ ]+ )+ async with session_factory() as session:+ room = await session.get(Room, room.id) # type: ignore[assignment]+ report = await backfill_room(transport, session_factory, room, store=store)++ assert (report.written, report.already_present) == (1, 1)+ rows = await _rows(session_factory, room.id)+ assert [(r.seq, r.body) for r in rows] == [(-1, "a"), (1, "b")]+++class TestWhatBelongsInTheLog:+ async def test_bus_traffic_the_log_does_not_keep_is_skipped(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """The same scoping as the live recorder, or the backfill would put+ back exactly what scoping the log took out."""+ store = MessageStore()+ async with session_factory() as session:+ room = await _make_room(session)++ transport = PagingTransport(+ [+ HistoryPage(+ events=[+ _event("$msg", 20),+ InboundCustomEvent(+ room_id="!room:test",+ event_id="$state",+ sender="@a:test",+ timestamp=_ms(10),+ content={"state": "busy"},+ event_type="com.switch.agent.runtime_state",+ ),+ ],+ next_token=None,+ )+ ]+ )+ async with session_factory() as session:+ room = await session.get(Room, room.id) # type: ignore[assignment]+ report = await backfill_room(transport, session_factory, room, store=store)++ assert report.written == 1+ assert report.skipped_by_type == {"com.switch.agent.runtime_state": 1}++ async def test_an_arrival_is_reconstructed_with_no_body(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """The timeline reads wrong without arrivals, and the sentence stays+ the reader's to phrase — same as the live path."""+ store = MessageStore()+ async with session_factory() as session:+ room = await _make_room(session)++ transport = PagingTransport(+ [+ HistoryPage(+ events=[+ InboundMembership(+ room_id="!room:test",+ event_id="$join",+ sender="@bob:test",+ timestamp=_ms(10),+ state_key="@bob:test",+ membership="join",+ display_name="Bob",+ )+ ],+ next_token=None,+ )+ ]+ )+ async with session_factory() as session:+ room = await session.get(Room, room.id) # type: ignore[assignment]+ await backfill_room(transport, session_factory, room, store=store)++ rows = await _rows(session_factory, room.id)+ assert rows[0].event_type == "m.room.member"+ assert rows[0].body is None+ assert rows[0].sender_name == "Bob"++ async def test_a_departure_is_not_history_worth_keeping(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ store = MessageStore()+ async with session_factory() as session:+ room = await _make_room(session)++ transport = PagingTransport(+ [+ HistoryPage(+ events=[+ InboundMembership(+ room_id="!room:test",+ event_id="$leave",+ sender="@bob:test",+ timestamp=_ms(10),+ state_key="@bob:test",+ membership="leave",+ )+ ],+ next_token=None,+ )+ ]+ )+ async with session_factory() as session:+ room = await session.get(Room, room.id) # type: ignore[assignment]+ report = await backfill_room(transport, session_factory, room, store=store)++ assert report.written == 0+ assert await _rows(session_factory, room.id) == []++ async def test_a_file_comes_back_with_its_attachment_row(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ store = MessageStore()+ async with session_factory() as session:+ room = await _make_room(session)++ transport = PagingTransport(+ [+ HistoryPage(+ events=[+ InboundMedia(+ room_id="!room:test",+ event_id="$img",+ sender="@a:test",+ timestamp=_ms(10),+ content={+ "info": {"mimetype": "image/png", "size": 42},+ "body": "chart.png",+ },+ body="chart.png",+ msgtype="m.image",+ uri="mxc://s/abc",+ )+ ],+ next_token=None,+ )+ ]+ )+ async with session_factory() as session:+ room = await session.get(Room, room.id) # type: ignore[assignment]+ await backfill_room(transport, session_factory, room, store=store)++ rows = await _rows(session_factory, room.id)+ async with session_factory() as session:+ attachments = await store.attachments_for(session, [rows[0].id])+ [attachment] = attachments[rows[0].id]+ assert (attachment.uri, attachment.filename) == ("mxc://s/abc", "chart.png")+ assert (attachment.mimetype, attachment.size) == ("image/png", 42)+++class TestStopping:+ async def test_a_cursor_that_does_not_advance_stops_the_walk(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """A homeserver that keeps returning the token it was given would+ otherwise walk forever."""+ store = MessageStore()+ async with session_factory() as session:+ room = await _make_room(session)++ transport = PagingTransport(+ [HistoryPage(events=[_event("$a", 10)], next_token="stuck")]+ )+ async with session_factory() as session:+ room = await session.get(Room, room.id) # type: ignore[assignment]+ report = await backfill_room(transport, session_factory, room, store=store)++ assert transport.reads == 2+ assert report.written == 1diff --git a/core/tests/switch_core/messages/test_message_recorder.py b/core/tests/switch_core/messages/test_message_recorder.pynew file mode 100644index 000000000..82027dd5d--- /dev/null+++ b/core/tests/switch_core/messages/test_message_recorder.py@@ -0,0 +1,623 @@+"""What the recorder writes for a send, and what it does when it cannot.++The recorder reads the content dict the transport reports back rather than+being told separately what was sent, so these tests feed it the shapes the+Matrix transport really produces — a plain message, a markdown one, a threaded+reply, a media event, a custom `com.switch.*` event — and check what lands.++The failure tests matter as much as the success ones. Recording runs after+delivery and must never turn a delivered message into a raised exception at+the caller.+"""++from __future__ import annotations++import logging+import uuid++import pytest+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker++from switch_core.db.models import Client, Room+from switch_core.db.stores.message_store import MessageStore+from switch_core.db.stores.room_store import RoomStore+from switch_core.messages import MessageRecorder+from switch_core.transport import InboundMembership, SendResult+++async def _make_room(session: AsyncSession) -> tuple[str, str, str]:+ """Insert the Room and Client a recorded message depends on.++ Returns (room uuid, matrix room id, client id).+ """+ suffix = uuid.uuid4().hex[:8]+ client = Client(+ matrix_user_id=f"@agent-{suffix}:test",+ display_name="agent one",+ type="agent",+ password="x",+ )+ session.add(client)+ await session.flush()+ room = Room(+ matrix_room_id=f"!room-{suffix}:test",+ name="a room",+ description="",+ )+ session.add(room)+ await session.flush()+ return room.id, room.matrix_room_id, client.id+++def _recorder(session_factory: async_sessionmaker[AsyncSession]) -> MessageRecorder:+ return MessageRecorder(+ session_factory=session_factory,+ room_store=RoomStore(),+ message_store=MessageStore(),+ )+++async def _record(+ session_factory: async_sessionmaker[AsyncSession],+ matrix_room_id: str,+ client_id: str,+ result: SendResult,+) -> None:+ await _recorder(session_factory).record(+ transport_room_id=matrix_room_id,+ result=result,+ sender_matrix_id="@agent:test",+ sender_client_id=client_id,+ sender_name="agent one",+ )+++class TestRecordsWhatWasSent:+ async def test_a_plain_message(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ room_id, matrix_room_id, client_id = await _make_room(session)+ await session.commit()++ await _record(+ session_factory,+ matrix_room_id,+ client_id,+ SendResult(+ event_id="$evt1",+ event_type="m.room.message",+ content={+ "msgtype": "m.text",+ "body": "hello",+ "sender_name": "agent one",+ },+ ),+ )++ async with session_factory() as session:+ message = await MessageStore().get_by_transport_event_id(session, "$evt1")++ assert message is not None+ assert message.room_id == room_id+ assert message.body == "hello"+ assert message.msgtype == "m.text"+ assert message.event_type == "m.room.message"+ assert message.sender_client_id == client_id+ assert message.sender_matrix_id == "@agent:test"+ assert message.thread_root_event_id is None+ # The whole event body is kept, not just the columns beside it.+ assert message.content["sender_name"] == "agent one"++ async def test_a_markdown_message_keeps_the_rendered_html(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ _, matrix_room_id, client_id = await _make_room(session)+ await session.commit()++ await _record(+ session_factory,+ matrix_room_id,+ client_id,+ SendResult(+ event_id="$evt2",+ event_type="m.room.message",+ content={+ "msgtype": "m.text",+ "body": "**bold**",+ "format": "org.matrix.custom.html",+ "formatted_body": "<p><strong>bold</strong></p>",+ },+ ),+ )++ async with session_factory() as session:+ message = await MessageStore().get_by_transport_event_id(session, "$evt2")++ assert message is not None+ assert message.formatted_body == "<p><strong>bold</strong></p>"++ async def test_a_threaded_reply_records_its_root(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ _, matrix_room_id, client_id = await _make_room(session)+ await session.commit()++ await _record(+ session_factory,+ matrix_room_id,+ client_id,+ SendResult(+ event_id="$evt3",+ event_type="m.room.message",+ content={+ "msgtype": "m.text",+ "body": "in thread",+ "m.relates_to": {+ "rel_type": "m.thread",+ "event_id": "$root",+ },+ },+ ),+ )++ async with session_factory() as session:+ message = await MessageStore().get_by_transport_event_id(session, "$evt3")++ assert message is not None+ assert message.thread_root_event_id == "$root"++ async def test_a_non_thread_relation_is_not_read_as_a_thread(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """An edit or a reaction relates to an event without being in a thread."""+ async with session_factory() as session:+ _, matrix_room_id, client_id = await _make_room(session)+ await session.commit()++ await _record(+ session_factory,+ matrix_room_id,+ client_id,+ SendResult(+ event_id="$evt4",+ event_type="m.room.message",+ content={+ "msgtype": "m.text",+ "body": "an edit",+ "m.relates_to": {+ "rel_type": "m.replace",+ "event_id": "$original",+ },+ },+ ),+ )++ async with session_factory() as session:+ message = await MessageStore().get_by_transport_event_id(session, "$evt4")++ assert message is not None+ assert message.thread_root_event_id is None++ async def test_a_media_event_records_its_file(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ _, matrix_room_id, client_id = await _make_room(session)+ await session.commit()++ await _record(+ session_factory,+ matrix_room_id,+ client_id,+ SendResult(+ event_id="$evt5",+ event_type="m.room.message",+ content={+ "msgtype": "m.image",+ "body": "a caption",+ "filename": "chart.png",+ "url": "mxc://test/abc",+ "info": {"mimetype": "image/png", "size": 4096},+ },+ ),+ )++ async with session_factory() as session:+ store = MessageStore()+ message = await store.get_by_transport_event_id(session, "$evt5")+ assert message is not None+ attachments = await store.get_attachments(session, message.id)++ assert len(attachments) == 1+ assert attachments[0].uri == "mxc://test/abc"+ # The caption is the body; the real filename is carried separately.+ assert attachments[0].filename == "chart.png"+ assert attachments[0].mimetype == "image/png"+ assert attachments[0].size == 4096++ async def test_an_uncaptioned_file_falls_back_to_the_body_for_its_name(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """Without a caption the transport puts the filename in `body` and+ sends no `filename` field at all."""+ async with session_factory() as session:+ _, matrix_room_id, client_id = await _make_room(session)+ await session.commit()++ await _record(+ session_factory,+ matrix_room_id,+ client_id,+ SendResult(+ event_id="$evt6",+ event_type="m.room.message",+ content={+ "msgtype": "m.file",+ "body": "report.csv",+ "url": "mxc://test/def",+ "info": {"mimetype": "text/csv", "size": 12},+ },+ ),+ )++ async with session_factory() as session:+ store = MessageStore()+ message = await store.get_by_transport_event_id(session, "$evt6")+ assert message is not None+ attachments = await store.get_attachments(session, message.id)++ assert [a.filename for a in attachments] == ["report.csv"]++ async def test_a_custom_event_records_its_whole_content(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """A `com.switch.*` event has no body or msgtype — the payload is all+ there is, so losing it would lose the event."""+ async with session_factory() as session:+ _, matrix_room_id, client_id = await _make_room(session)+ await session.commit()++ await _record(+ session_factory,+ matrix_room_id,+ client_id,+ SendResult(+ event_id="$evt7",+ event_type="com.switch.command",+ content={"command": "reset", "args": ["--hard"], "request_id": "r1"},+ ),+ )++ async with session_factory() as session:+ store = MessageStore()+ message = await store.get_by_transport_event_id(session, "$evt7")+ assert message is not None+ attachments = await store.get_attachments(session, message.id)++ assert message.event_type == "com.switch.command"+ assert message.body is None+ assert message.msgtype is None+ assert message.content == {+ "command": "reset",+ "args": ["--hard"],+ "request_id": "r1",+ }+ assert attachments == []++ async def test_bus_traffic_is_not_recorded_at_all(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """The log is the conversation. A runtime-state ping is not part of it,+ and it is the highest-volume thing on the bus."""+ async with session_factory() as session:+ _, matrix_room_id, client_id = await _make_room(session)+ await session.commit()++ await _record(+ session_factory,+ matrix_room_id,+ client_id,+ SendResult(+ event_id="$evt8",+ event_type="com.switch.agent.runtime_state",+ content={"state": "busy"},+ ),+ )++ async with session_factory() as session:+ found = await MessageStore().get_by_transport_event_id(session, "$evt8")++ assert found is None+++class TestFailingToRecordNeverReachesTheCaller:+ async def test_an_unknown_room_is_warned_about_not_raised(+ self,+ session_factory: async_sessionmaker[AsyncSession],+ caplog: pytest.LogCaptureFixture,+ ) -> None:+ """Not every room a client sends to is a Switch room."""+ with caplog.at_level(logging.WARNING):+ await _record(+ session_factory,+ "!nobody-knows-this:test",+ None, # type: ignore[arg-type]+ SendResult(+ event_id="$evt8",+ event_type="m.room.message",+ content={"body": "hi"},+ ),+ )++ assert "not a Switch room" in caplog.text++ async with session_factory() as session:+ assert (+ await MessageStore().get_by_transport_event_id(session, "$evt8") is None+ )++ async def test_a_database_failure_is_logged_at_error_and_swallowed(+ self,+ session_factory: async_sessionmaker[AsyncSession],+ caplog: pytest.LogCaptureFixture,+ ) -> None:+ """The message was delivered. Raising here would tell the caller a+ successful send failed, which is worse than a missing row."""+ async with session_factory() as session:+ _, matrix_room_id, client_id = await _make_room(session)+ await session.commit()++ recorder = _recorder(session_factory)+ result = SendResult(+ event_id="$evt9",+ event_type="m.room.message",+ content={"msgtype": "m.text", "body": "once"},+ )+ await recorder.record(+ transport_room_id=matrix_room_id,+ result=result,+ sender_matrix_id="@agent:test",+ sender_client_id=client_id,+ sender_name="agent one",+ )++ # The same event id a second time violates the unique constraint, which+ # is a stand-in for any database failure after a successful send.+ with caplog.at_level(logging.ERROR):+ await recorder.record(+ transport_room_id=matrix_room_id,+ result=result,+ sender_matrix_id="@agent:test",+ sender_client_id=client_id,+ sender_name="agent one",+ )++ assert "failed to record" in caplog.text+ assert "$evt9" in caplog.text+++class TestRoomResolution:+ async def test_the_room_lookup_is_cached_across_sends(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """A send is on the hot path, so the room id is resolved once."""+ async with session_factory() as session:+ room_id, matrix_room_id, client_id = await _make_room(session)+ await session.commit()++ lookups = 0+ real_lookup = RoomStore.get_by_matrix_room_id++ async def counting_lookup(+ self: RoomStore, session: AsyncSession, matrix_room_id: str+ ) -> Room | None:+ nonlocal lookups+ lookups += 1+ return await real_lookup(self, session, matrix_room_id)++ room_store = RoomStore()+ room_store.get_by_matrix_room_id = counting_lookup.__get__(room_store) # type: ignore[method-assign]+ recorder = MessageRecorder(+ session_factory=session_factory,+ room_store=room_store,+ message_store=MessageStore(),+ )++ for n in range(3):+ await recorder.record(+ transport_room_id=matrix_room_id,+ result=SendResult(+ event_id=f"$cached{n}",+ event_type="m.room.message",+ content={"body": "x"},+ ),+ sender_matrix_id="@agent:test",+ sender_client_id=client_id,+ sender_name="agent one",+ )++ assert lookups == 1++ async with session_factory() as session:+ for n in range(3):+ message = await MessageStore().get_by_transport_event_id(+ session, f"$cached{n}"+ )+ assert message is not None+ assert message.room_id == room_id+++class TestRecordsArrivals:+ """A join is not a send, so it comes in by its own door.++ It is recorded by the client that arrived, about itself. Exactly one Switch+ client owns each participant, so that gives one row per arrival for the+ same reason recording sends does.+ """++ async def test_an_arrival_is_recorded(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ room_id, matrix_room_id, client_id = await _make_room(session)+ await session.commit()++ await _recorder(session_factory).record_join(+ transport_room_id=matrix_room_id,+ event=InboundMembership(+ room_id=matrix_room_id,+ event_id="$join1",+ sender="@agent:test",+ timestamp=1000,+ content={"membership": "join", "displayname": "agent one"},+ state_key="@agent:test",+ membership="join",+ prev_membership="invite",+ display_name="agent one",+ ),+ client_id=client_id,+ member_name="agent one",+ )++ async with session_factory() as session:+ message = await MessageStore().get_by_transport_event_id(session, "$join1")+ assert message is not None+ assert message.room_id == room_id+ assert message.event_type == "m.room.member"+ assert message.sender_matrix_id == "@agent:test"+ assert message.sender_name == "agent one"+ assert message.content["membership"] == "join"++ async def test_the_arrival_is_named_the_way_the_member_speaks(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """The membership event's display name comes from the profile, which is+ set from whatever the source platform calls the member. Recording it+ would make one participant read two ways in the same history."""+ async with session_factory() as session:+ _, matrix_room_id, client_id = await _make_room(session)+ await session.commit()++ await _recorder(session_factory).record_join(+ transport_room_id=matrix_room_id,+ event=InboundMembership(+ room_id=matrix_room_id,+ event_id="$join5",+ sender="@agent:test",+ timestamp=1000,+ state_key="@agent:test",+ membership="join",+ display_name="agent one on the platform",+ ),+ client_id=client_id,+ member_name="agent one",+ )++ async with session_factory() as session:+ message = await MessageStore().get_by_transport_event_id(session, "$join5")+ assert message is not None+ assert message.sender_name == "agent one"++ async def test_the_row_carries_no_rendered_sentence(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """How an arrival reads is the reader's to phrase. Writing "x joined+ the room" into the log would freeze today's wording into every row."""+ async with session_factory() as session:+ _, matrix_room_id, client_id = await _make_room(session)+ await session.commit()++ await _recorder(session_factory).record_join(+ transport_room_id=matrix_room_id,+ event=InboundMembership(+ room_id=matrix_room_id,+ event_id="$join2",+ sender="@agent:test",+ timestamp=1000,+ state_key="@agent:test",+ membership="join",+ display_name="agent one",+ ),+ client_id=client_id,+ member_name="agent one",+ )++ async with session_factory() as session:+ message = await MessageStore().get_by_transport_event_id(session, "$join2")+ assert message is not None+ assert message.body is None+ assert message.msgtype is None++ async def test_seeing_the_same_join_twice_records_it_once(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """A redelivered sync is not a second arrival."""+ async with session_factory() as session:+ room_id, matrix_room_id, client_id = await _make_room(session)+ await session.commit()++ event = InboundMembership(+ room_id=matrix_room_id,+ event_id="$join3",+ sender="@agent:test",+ timestamp=1000,+ state_key="@agent:test",+ membership="join",+ display_name="agent one",+ )+ recorder = _recorder(session_factory)+ await recorder.record_join(+ transport_room_id=matrix_room_id,+ event=event,+ client_id=client_id,+ member_name="agent one",+ )+ await recorder.record_join(+ transport_room_id=matrix_room_id,+ event=event,+ client_id=client_id,+ member_name="agent one",+ )++ async with session_factory() as session:+ rows = await MessageStore().list_for_room(+ session, room_id, after_seq=0, limit=10+ )+ assert [row.transport_event_id for row in rows] == ["$join3"]++ async def test_a_failure_to_record_does_not_escape(+ self,+ session_factory: async_sessionmaker[AsyncSession],+ caplog: pytest.LogCaptureFixture,+ ) -> None:+ """Nothing about being in a room depends on the row having landed."""+ async with session_factory() as session:+ _, matrix_room_id, client_id = await _make_room(session)+ await session.commit()++ recorder = _recorder(session_factory)++ async def boom(*args: object, **kwargs: object) -> None:+ raise RuntimeError("database is unhappy")++ recorder._message_store.create = boom # type: ignore[method-assign]++ with caplog.at_level(logging.ERROR):+ await recorder.record_join(+ transport_room_id=matrix_room_id,+ event=InboundMembership(+ room_id=matrix_room_id,+ event_id="$join4",+ sender="@agent:test",+ timestamp=1000,+ state_key="@agent:test",+ membership="join",+ ),+ client_id=client_id,+ member_name="agent one",+ )++ assert "failed to record the arrival" in caplog.textdiff --git a/core/tests/switch_core/messages/test_notify.py b/core/tests/switch_core/messages/test_notify.pynew file mode 100644index 000000000..4f3fde479--- /dev/null+++ b/core/tests/switch_core/messages/test_notify.py@@ -0,0 +1,222 @@+"""New rows announce themselves, and the listener wakes whoever asked.++These run against real PostgreSQL because the thing under test is a trigger and+a `LISTEN`. Neither has a meaningful stand-in: a fake would prove the fan-out+works and say nothing about whether the database ever speaks.+"""++from __future__ import annotations++import asyncio+import uuid+from typing import TYPE_CHECKING++import pytest+from sqlalchemy.ext.asyncio import create_async_engine+from sqlalchemy.pool import NullPool++from switch_core.db.models import Message, Room+from switch_core.messages.notify import Announcement, MessageListener++if TYPE_CHECKING:+ from collections.abc import AsyncIterator++ from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker++# Long enough that a slow container does not fail the test, short enough that a+# genuine hang does not hold the suite up.+DELIVERY_TIMEOUT = 10.0+++class Woken:+ """Records which rooms were woken, and lets a test wait for one."""++ def __init__(self) -> None:+ self.rooms: list[str] = []+ self._anything = asyncio.Event()++ async def __call__(self, room_id: str) -> None:+ self.rooms.append(room_id)+ self._anything.set()++ async def wait(self) -> None:+ await asyncio.wait_for(self._anything.wait(), DELIVERY_TIMEOUT)+ self._anything.clear()+++async def listener(postgres_url: str) -> AsyncIterator[MessageListener]:+ listener = MessageListener(+ lambda: create_async_engine(postgres_url, poolclass=NullPool)+ )+ await listener.start()+ try:+ await asyncio.wait_for(listener.connected.wait(), DELIVERY_TIMEOUT)+ yield listener+ finally:+ await listener.stop()+++async def _make_room(session: AsyncSession) -> str:+ room = Room(+ matrix_room_id=f"!room-{uuid.uuid4().hex[:8]}:test",+ name="a room",+ description="",+ )+ session.add(room)+ await session.flush()+ return room.id+++async def _write(session: AsyncSession, room_id: str, seq: int) -> None:+ session.add(+ Message(+ seq=seq,+ room_id=room_id,+ transport_event_id=f"$e{uuid.uuid4().hex[:8]}",+ sender_matrix_id="@a:test",+ event_type="m.room.message",+ msgtype="m.text",+ body="hello",+ content={"body": "hello"},+ )+ )+ await session.commit()+++class TestParsingAnnouncements:+ def test_a_payload_becomes_an_announcement(self) -> None:+ announcement = Announcement.parse('{"room_id": "r1", "seq": 4, "id": "m1"}')+ assert announcement == Announcement(room_id="r1", seq=4, message_id="m1")++ @pytest.mark.parametrize(+ "payload", ["not json", "{}", '{"room_id": "r1", "seq": "no"}', "[]"]+ )+ def test_an_unreadable_payload_is_dropped_not_raised(self, payload: str) -> None:+ """This runs inside the connection's read loop. Raising there would+ take delivery down for every room over one bad message."""+ assert Announcement.parse(payload) is None+++class TestDelivery:+ async def test_writing_a_message_wakes_a_subscriber(+ self,+ listener: MessageListener,+ session_factory: async_sessionmaker[AsyncSession],+ ) -> None:+ async with session_factory() as session:+ room_id = await _make_room(session)+ await session.commit()++ woken = Woken()+ listener.subscribe(room_id, woken)+ await woken.wait() # subscribing wakes once by design+ woken.rooms.clear()++ async with session_factory() as session:+ await _write(session, room_id, 1)++ await woken.wait()+ assert woken.rooms == [room_id]++ async def test_a_room_nobody_subscribed_to_wakes_nobody(+ self,+ listener: MessageListener,+ session_factory: async_sessionmaker[AsyncSession],+ ) -> None:+ async with session_factory() as session:+ mine = await _make_room(session)+ theirs = await _make_room(session)+ await session.commit()++ woken = Woken()+ listener.subscribe(mine, woken)+ await woken.wait()+ woken.rooms.clear()++ async with session_factory() as session:+ await _write(session, theirs, 1)+ await _write(session, mine, 1)++ await woken.wait()+ assert woken.rooms == [mine]++ async def test_a_burst_coalesces_into_one_wake_up(+ self,+ listener: MessageListener,+ session_factory: async_sessionmaker[AsyncSession],+ ) -> None:+ """The wake-up says a room moved, not what was said, so several rows+ arriving together are one thing to react to. The subscriber reads from+ its own cursor and sees all of them either way."""+ async with session_factory() as session:+ room_id = await _make_room(session)+ await session.commit()++ blocked = asyncio.Event()+ released = asyncio.Event()+ calls = 0++ async def slow(_room_id: str) -> None:+ nonlocal calls+ calls += 1+ blocked.set()+ await released.wait()++ listener.subscribe(room_id, slow)+ await asyncio.wait_for(blocked.wait(), DELIVERY_TIMEOUT)++ async with session_factory() as session:+ for seq in range(1, 6):+ await _write(session, room_id, seq)++ # Let the announcements land while the subscriber is still held.+ await asyncio.sleep(0.5)+ released.set()+ await asyncio.sleep(0.5)++ assert calls == 2, "the subscribe wake-up, then one for the whole burst"++ async def test_reconstructed_history_is_not_announced(+ self,+ listener: MessageListener,+ session_factory: async_sessionmaker[AsyncSession],+ ) -> None:+ """A backfill writes thousands of rows numbered below zero. Nobody is+ waiting for them — every cursor is above those positions by+ construction — so waking the room to read nothing is pure noise."""+ async with session_factory() as session:+ room_id = await _make_room(session)+ await session.commit()++ woken = Woken()+ listener.subscribe(room_id, woken)+ await woken.wait()+ woken.rooms.clear()++ async with session_factory() as session:+ await _write(session, room_id, -1)++ await asyncio.sleep(0.5)+ assert woken.rooms == []++ async def test_unsubscribing_stops_the_wake_ups(+ self,+ listener: MessageListener,+ session_factory: async_sessionmaker[AsyncSession],+ ) -> None:+ async with session_factory() as session:+ room_id = await _make_room(session)+ await session.commit()++ woken = Woken()+ listener.subscribe(room_id, woken)+ await woken.wait()+ listener.unsubscribe(room_id, woken)+ woken.rooms.clear()++ async with session_factory() as session:+ await _write(session, room_id, 1)++ await asyncio.sleep(0.5)+ assert woken.rooms == []diff --git a/core/tests/switch_core/messages/test_reconcile.py b/core/tests/switch_core/messages/test_reconcile.pynew file mode 100644index 000000000..a93a8c46b--- /dev/null+++ b/core/tests/switch_core/messages/test_reconcile.py@@ -0,0 +1,792 @@+"""Reconciliation reports the differences it is supposed to, and no others.++The whole value of this check is that its verdict can be trusted. So the tests+that matter most are the ones proving it does not cry drift over things that+are legitimately different — history predating the recorder, membership+changes that were never arrivals, arrivals predating the path that records+them — and the one proving it does not report a room it could not fully read+as clean.+"""++from __future__ import annotations++import uuid+from datetime import UTC, datetime, timedelta+from itertools import count++from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker++from switch_core.db.models import Message, Room+from switch_core.messages import reconcile_room+from switch_core.transport import (+ HistoryPage,+ InboundCustomEvent,+ InboundMedia,+ InboundMembership,+ InboundMessage,+)+++class PagingTransport:+ """Replays fixed pages of backwards history, newest first."""++ def __init__(self, pages: list[HistoryPage]) -> None:+ self._pages = pages+ self.reads = 0++ async def read_history(+ self, room_id: str, *, start: str | None, limit: int+ ) -> HistoryPage:+ page = self._pages[self.reads]+ self.reads += 1+ return page+++def _ms(moment: datetime) -> int:+ return int(moment.timestamp() * 1000)+++async def _make_room(session: AsyncSession) -> Room:+ room = Room(+ matrix_room_id=f"!room-{uuid.uuid4().hex[:8]}:test",+ name="a room",+ description="",+ )+ session.add(room)+ await session.flush()+ return room+++_seq = count(1)+++def _row(+ room_id: str, event_id: str, sent_at: datetime, **overrides: object+) -> Message:+ """`seq` is assigned by MessageStore.create; these rows bypass it, so the+ helper numbers them. Reconciliation matches on event id and never reads+ `seq`, so only distinctness matters here."""+ fields: dict[str, object] = {+ "seq": next(_seq),+ "room_id": room_id,+ "transport_event_id": event_id,+ "sender_matrix_id": "@agent:test",+ "sender_name": "agent one",+ "event_type": "m.room.message",+ "msgtype": "m.text",+ "body": "hello",+ "content": {"msgtype": "m.text", "body": "hello"},+ "sent_at": sent_at,+ }+ fields.update(overrides)+ return Message(**fields)+++def _join_row(room_id: str, event_id: str, sent_at: datetime) -> Message:+ return _row(+ room_id,+ event_id,+ sent_at,+ event_type="m.room.member",+ msgtype=None,+ body=None,+ content={"membership": "join"},+ )+++def _join_event(event_id: str, at: datetime, **overrides: object) -> InboundMembership:+ fields: dict[str, object] = {+ "room_id": "!room:test",+ "event_id": event_id,+ "sender": "@agent:test",+ "timestamp": _ms(at),+ "content": {"membership": "join"},+ "state_key": "@agent:test",+ "membership": "join",+ "prev_membership": "invite",+ }+ fields.update(overrides)+ return InboundMembership(**fields) # type: ignore[arg-type]+++def _event(event_id: str, at: datetime, **overrides: object) -> InboundMessage:+ fields: dict[str, object] = {+ "room_id": "!room:test",+ "event_id": event_id,+ "sender": "@agent:test",+ "timestamp": _ms(at),+ "content": {},+ "body": "hello",+ "msgtype": "m.text",+ }+ fields.update(overrides)+ return InboundMessage(**fields) # type: ignore[arg-type]+++class TestAgreement:+ async def test_a_room_whose_records_match_is_clean(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ now = datetime.now(UTC)+ async with session_factory() as session:+ room = await _make_room(session)+ session.add(_row(room.id, "$a", now))+ session.add(_row(room.id, "$b", now + timedelta(seconds=1)))+ await session.commit()+ room_id = room.id++ transport = PagingTransport(+ [+ HistoryPage(+ events=[+ _event("$b", now + timedelta(seconds=1)),+ _event("$a", now),+ ],+ next_token=None,+ )+ ]+ )++ async with session_factory() as session:+ room = await session.get(Room, room_id) # type: ignore[assignment]+ report = await reconcile_room(transport, session, room) # type: ignore[arg-type]++ assert report.clean+ assert report.compared == 2+ assert report.agreed == 2++ async def test_history_older_than_the_recorder_is_not_reported_missing(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """The room existed before recording started. Reporting its whole+ back-catalogue as drift would bury the row that really went astray."""+ now = datetime.now(UTC)+ recording_began = now - timedelta(minutes=5)+ async with session_factory() as session:+ room = await _make_room(session)+ session.add(_row(room.id, "$new", recording_began))+ await session.commit()+ room_id = room.id++ transport = PagingTransport(+ [+ HistoryPage(+ events=[+ _event("$new", recording_began),+ _event("$ancient", now - timedelta(days=30)),+ _event("$older-still", now - timedelta(days=60)),+ ],+ next_token=None,+ )+ ]+ )++ async with session_factory() as session:+ room = await session.get(Room, room_id) # type: ignore[assignment]+ report = await reconcile_room(transport, session, room) # type: ignore[arg-type]++ assert report.clean+ assert report.compared == 1+ assert report.missing_rows == []++ async def test_events_that_were_never_sends_are_counted_not_flagged(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ now = datetime.now(UTC)+ async with session_factory() as session:+ room = await _make_room(session)+ session.add(_row(room.id, "$a", now))+ await session.commit()+ room_id = room.id++ transport = PagingTransport(+ [+ HistoryPage(+ events=[+ InboundMembership(+ room_id="!room:test",+ event_id="$join",+ sender="@someone:test",+ timestamp=_ms(now + timedelta(seconds=1)),+ state_key="@someone:test",+ membership="join",+ ),+ _event("$a", now),+ ],+ next_token=None,+ )+ ]+ )++ async with session_factory() as session:+ room = await session.get(Room, room_id) # type: ignore[assignment]+ report = await reconcile_room(transport, session, room) # type: ignore[arg-type]++ assert report.clean+ assert report.ignored_by_type == {+ "m.room.member (before arrivals were recorded)": 1+ }++ async def test_a_room_with_nothing_recorded_reports_that_plainly(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """Not the same as agreeing, and not the same as total drift."""+ async with session_factory() as session:+ room = await _make_room(session)+ await session.commit()+ room_id = room.id++ transport = PagingTransport([])++ async with session_factory() as session:+ room = await session.get(Room, room_id) # type: ignore[assignment]+ report = await reconcile_room(transport, session, room) # type: ignore[arg-type]++ assert report.compared_nothing+ assert transport.reads == 0+ assert "nothing to compare" in report.summary()+++class TestTheWindowBoundary:+ """The oldest recorded message is the one most likely to be misjudged.++ Its row is written after its send is accepted, so the row's `sent_at` is+ always a little later than the event's own timestamp. A window that began+ at the row would exclude the event that produced it, and every room would+ report its first message as drift for as long as it existed.+ """++ async def test_the_first_recorded_message_is_not_reported_as_drift(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ sent = datetime.now(UTC)+ recorded_at = sent + timedelta(milliseconds=40)+ async with session_factory() as session:+ room = await _make_room(session)+ session.add(_row(room.id, "$first", recorded_at))+ await session.commit()+ room_id = room.id++ transport = PagingTransport(+ [HistoryPage(events=[_event("$first", sent)], next_token=None)]+ )++ async with session_factory() as session:+ room = await session.get(Room, room_id) # type: ignore[assignment]+ report = await reconcile_room(transport, session, room) # type: ignore[arg-type]++ assert report.clean+ assert report.agreed == 1+ assert report.anchored++ async def test_history_before_the_anchor_is_still_left_alone(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """Admitting the anchor from before the window must not admit its+ neighbours: the walk stops at it, it does not step over it."""+ sent = datetime.now(UTC)+ async with session_factory() as session:+ room = await _make_room(session)+ session.add(_row(room.id, "$first", sent + timedelta(milliseconds=40)))+ await session.commit()+ room_id = room.id++ transport = PagingTransport(+ [+ HistoryPage(+ events=[+ _event("$first", sent),+ _event("$older", sent - timedelta(seconds=1)),+ ],+ next_token=None,+ )+ ]+ )++ async with session_factory() as session:+ room = await session.get(Room, room_id) # type: ignore[assignment]+ report = await reconcile_room(transport, session, room) # type: ignore[arg-type]++ assert report.clean+ assert report.missing_rows == []++ async def test_an_anchor_the_bus_has_lost_is_declared_not_hidden(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ now = datetime.now(UTC)+ async with session_factory() as session:+ room = await _make_room(session)+ session.add(_row(room.id, "$gone", now))+ await session.commit()+ room_id = room.id++ transport = PagingTransport(+ [HistoryPage(events=[_event("$other", now)], next_token=None)]+ )++ async with session_factory() as session:+ room = await session.get(Room, room_id) # type: ignore[assignment]+ report = await reconcile_room(transport, session, room) # type: ignore[arg-type]++ assert not report.anchored+ assert "WINDOW UNANCHORED" in report.summary()+++class TestArrivalsAndRowsWithNothingToCompareAgainst:+ """Arrivals are compared from the point the log holds one; the categories+ the bus walk still discards have no counterpart by construction, and+ calling those "recorded but never sent" would report the same rows as+ drift on every run."""++ async def test_an_arrival_the_bus_agrees_with_is_checked_not_skipped(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """Recording arrivals is the newest write path there is, so leaving it+ out of the check made the least proven part the unchecked part."""+ now = datetime.now(UTC)+ async with session_factory() as session:+ room = await _make_room(session)+ session.add(_row(room.id, "$a", now))+ session.add(_join_row(room.id, "$join", now + timedelta(seconds=2)))+ await session.commit()+ room_id = room.id++ transport = PagingTransport(+ [+ HistoryPage(+ events=[+ _join_event("$join", now + timedelta(seconds=1)),+ _event("$a", now),+ ],+ next_token=None,+ )+ ]+ )++ async with session_factory() as session:+ room = await session.get(Room, room_id) # type: ignore[assignment]+ report = await reconcile_room(transport, session, room) # type: ignore[arg-type]++ assert report.clean+ assert report.compared == 2+ assert report.agreed == 2+ assert report.unverifiable_by_type == {}++ async def test_an_arrival_the_log_missed_is_drift(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ now = datetime.now(UTC)+ async with session_factory() as session:+ room = await _make_room(session)+ session.add(_row(room.id, "$a", now))+ session.add(_join_row(room.id, "$join", now + timedelta(seconds=2)))+ await session.commit()+ room_id = room.id++ transport = PagingTransport(+ [+ HistoryPage(+ events=[+ _join_event("$later", now + timedelta(seconds=3)),+ _join_event("$join", now + timedelta(seconds=1)),+ _event("$a", now),+ ],+ next_token=None,+ )+ ]+ )++ async with session_factory() as session:+ room = await session.get(Room, room_id) # type: ignore[assignment]+ report = await reconcile_room(transport, session, room) # type: ignore[arg-type]++ assert report.missing_rows == ["$later"]++ async def test_an_arrival_older_than_the_log_is_counted_not_reported(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """Every room was joined long before arrivals were recorded, so a join+ from before the log's first one cannot have a row."""+ now = datetime.now(UTC)+ async with session_factory() as session:+ room = await _make_room(session)+ session.add(_row(room.id, "$a", now))+ session.add(_join_row(room.id, "$join", now + timedelta(seconds=3)))+ await session.commit()+ room_id = room.id++ transport = PagingTransport(+ [+ HistoryPage(+ events=[+ _join_event("$join", now + timedelta(seconds=2)),+ _join_event("$ancient", now + timedelta(seconds=1)),+ _event("$a", now),+ ],+ next_token=None,+ )+ ]+ )++ async with session_factory() as session:+ room = await session.get(Room, room_id) # type: ignore[assignment]+ report = await reconcile_room(transport, session, room) # type: ignore[arg-type]++ assert report.clean+ assert report.ignored_by_type == {+ "m.room.member (before arrivals were recorded)": 1+ }++ async def test_a_leave_is_never_compared(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ now = datetime.now(UTC)+ async with session_factory() as session:+ room = await _make_room(session)+ session.add(_row(room.id, "$a", now))+ session.add(_join_row(room.id, "$join", now + timedelta(seconds=2)))+ await session.commit()+ room_id = room.id++ transport = PagingTransport(+ [+ HistoryPage(+ events=[+ _join_event(+ "$leave",+ now + timedelta(seconds=3),+ membership="leave",+ prev_membership="join",+ ),+ _join_event("$join", now + timedelta(seconds=1)),+ _event("$a", now),+ ],+ next_token=None,+ )+ ]+ )++ async with session_factory() as session:+ room = await session.get(Room, room_id) # type: ignore[assignment]+ report = await reconcile_room(transport, session, room) # type: ignore[arg-type]++ assert report.clean+ assert report.ignored_by_type == {"m.room.member": 1}++ async def test_a_row_written_before_its_type_was_denied_is_not_drift(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """These exist on real deployments: the recorder kept every type before+ the log was scoped, and those rows outlive the change."""+ now = datetime.now(UTC)+ async with session_factory() as session:+ room = await _make_room(session)+ session.add(_row(room.id, "$a", now))+ session.add(+ _row(+ room.id,+ "$legacy",+ now + timedelta(seconds=1),+ event_type="com.switch.agent.runtime_state",+ msgtype=None,+ body=None,+ content={"state": "busy"},+ )+ )+ await session.commit()+ room_id = room.id++ transport = PagingTransport(+ [HistoryPage(events=[_event("$a", now)], next_token=None)]+ )++ async with session_factory() as session:+ room = await session.get(Room, room_id) # type: ignore[assignment]+ report = await reconcile_room(transport, session, room) # type: ignore[arg-type]++ assert report.clean+ assert report.unverifiable_by_type == {"com.switch.agent.runtime_state": 1}+++class TestDrift:+ async def test_a_delivered_message_with_no_row_is_reported(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """The failure mode recording was designed to tolerate: the send+ succeeded and the write after it did not."""+ now = datetime.now(UTC)+ async with session_factory() as session:+ room = await _make_room(session)+ session.add(_row(room.id, "$a", now))+ await session.commit()+ room_id = room.id++ transport = PagingTransport(+ [+ HistoryPage(+ events=[+ _event("$lost", now + timedelta(seconds=1)),+ _event("$a", now),+ ],+ next_token=None,+ )+ ]+ )++ async with session_factory() as session:+ room = await session.get(Room, room_id) # type: ignore[assignment]+ report = await reconcile_room(transport, session, room) # type: ignore[arg-type]++ assert not report.clean+ assert report.missing_rows == ["$lost"]+ assert "DRIFT" in report.summary()++ async def test_a_row_the_bus_does_not_have_is_reported(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ now = datetime.now(UTC)+ async with session_factory() as session:+ room = await _make_room(session)+ session.add(_row(room.id, "$a", now))+ session.add(_row(room.id, "$phantom", now))+ await session.commit()+ room_id = room.id++ transport = PagingTransport(+ [HistoryPage(events=[_event("$a", now)], next_token=None)]+ )++ async with session_factory() as session:+ room = await session.get(Room, room_id) # type: ignore[assignment]+ report = await reconcile_room(transport, session, room) # type: ignore[arg-type]++ assert report.unsent_rows == ["$phantom"]++ async def test_a_field_that_disagrees_is_named(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ now = datetime.now(UTC)+ async with session_factory() as session:+ room = await _make_room(session)+ session.add(_row(room.id, "$a", now, body="what was recorded"))+ await session.commit()+ room_id = room.id++ transport = PagingTransport(+ [+ HistoryPage(+ events=[_event("$a", now, body="what the bus holds")],+ next_token=None,+ )+ ]+ )++ async with session_factory() as session:+ room = await session.get(Room, room_id) # type: ignore[assignment]+ report = await reconcile_room(transport, session, room) # type: ignore[arg-type]++ assert [m.field_name for m in report.mismatches] == ["body"]+ assert "what the bus holds" in report.mismatches[0].describe()+ assert report.agreed == 0++ async def test_a_custom_event_is_compared_on_its_type(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ now = datetime.now(UTC)+ async with session_factory() as session:+ room = await _make_room(session)+ session.add(+ _row(+ room.id,+ "$cmd",+ now,+ event_type="com.switch.command",+ msgtype=None,+ body=None,+ content={"command": "reset"},+ )+ )+ await session.commit()+ room_id = room.id++ transport = PagingTransport(+ [+ HistoryPage(+ events=[+ InboundCustomEvent(+ room_id="!room:test",+ event_id="$cmd",+ sender="@agent:test",+ timestamp=_ms(now),+ content={"command": "reset"},+ event_type="com.switch.command",+ )+ ],+ next_token=None,+ )+ ]+ )++ async with session_factory() as session:+ room = await session.get(Room, room_id) # type: ignore[assignment]+ report = await reconcile_room(transport, session, room) # type: ignore[arg-type]++ assert report.clean+ assert report.agreed == 1++ async def test_a_media_event_is_compared_on_its_uri(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ now = datetime.now(UTC)+ async with session_factory() as session:+ room = await _make_room(session)+ session.add(+ _row(+ room.id,+ "$img",+ now,+ msgtype="m.image",+ body="chart.png",+ content={+ "msgtype": "m.image",+ "body": "chart.png",+ "url": "mxc://a",+ },+ )+ )+ await session.commit()+ room_id = room.id++ transport = PagingTransport(+ [+ HistoryPage(+ events=[+ InboundMedia(+ room_id="!room:test",+ event_id="$img",+ sender="@agent:test",+ timestamp=_ms(now),+ content={},+ body="chart.png",+ msgtype="m.image",+ uri="mxc://somewhere-else",+ )+ ],+ next_token=None,+ )+ ]+ )++ async with session_factory() as session:+ room = await session.get(Room, room_id) # type: ignore[assignment]+ report = await reconcile_room(transport, session, room) # type: ignore[arg-type]++ assert [m.field_name for m in report.mismatches] == ["uri"]++ async def test_an_event_the_recorder_does_not_keep_is_counted_not_reported(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """Bus traffic is absent by design. Reporting it as a missing row would+ drown the one row that really went astray."""+ now = datetime.now(UTC)+ async with session_factory() as session:+ room = await _make_room(session)+ session.add(_row(room.id, "$msg", now))+ await session.commit()+ room_id = room.id++ transport = PagingTransport(+ [+ HistoryPage(+ events=[+ InboundCustomEvent(+ room_id="!room:test",+ event_id="$state",+ sender="@agent:test",+ timestamp=_ms(now + timedelta(seconds=1)),+ content={"state": "busy"},+ event_type="com.switch.agent.runtime_state",+ ),+ _event("$msg", now),+ ],+ next_token=None,+ )+ ]+ )++ async with session_factory() as session:+ room = await session.get(Room, room_id) # type: ignore[assignment]+ report = await reconcile_room(transport, session, room) # type: ignore[arg-type]++ assert report.clean+ assert report.compared == 1+ assert report.ignored_by_type == {"com.switch.agent.runtime_state": 1}+++class TestPaging:+ async def test_it_keeps_paging_until_the_window_is_covered(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """The read path gives up after a page budget. This must not: an event+ it never looked at would otherwise be reported as agreeing."""+ now = datetime.now(UTC)+ async with session_factory() as session:+ room = await _make_room(session)+ # Oldest first, so `seq` runs the same way the recorder assigns it:+ # the anchor is the room's first message, not its last.+ for n in (2, 1, 0):+ session.add(_row(room.id, f"$p{n}", now - timedelta(minutes=n)))+ await session.commit()+ room_id = room.id++ transport = PagingTransport(+ [+ HistoryPage(events=[_event("$p0", now)], next_token="t1"),+ HistoryPage(+ events=[_event("$p1", now - timedelta(minutes=1))],+ next_token="t2",+ ),+ HistoryPage(+ events=[_event("$p2", now - timedelta(minutes=2))],+ next_token=None,+ ),+ ]+ )++ async with session_factory() as session:+ room = await session.get(Room, room_id) # type: ignore[assignment]+ report = await reconcile_room(transport, session, room) # type: ignore[arg-type]++ assert transport.reads == 3+ assert report.compared == 3+ assert report.clean++ async def test_it_stops_at_a_token_that_does_not_advance(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """A server that returns the cursor it was given would otherwise loop+ forever.++ The anchor is deliberately absent from the bus, since a walk that finds+ it stops there and never reaches a second page.+ """+ now = datetime.now(UTC)+ async with session_factory() as session:+ room = await _make_room(session)+ session.add(_row(room.id, "$vanished", now))+ await session.commit()+ room_id = room.id++ transport = PagingTransport(+ [+ HistoryPage(events=[], next_token="stuck"),+ HistoryPage(events=[], next_token="stuck"),+ ]+ )++ async with session_factory() as session:+ room = await session.get(Room, room_id) # type: ignore[assignment]+ report = await reconcile_room(transport, session, room) # type: ignore[arg-type]++ assert transport.reads == 2+ assert not report.anchoreddiff --git a/core/tests/switch_core/messages/test_recorded_types.py b/core/tests/switch_core/messages/test_recorded_types.pynew file mode 100644index 000000000..a4de15364--- /dev/null+++ b/core/tests/switch_core/messages/test_recorded_types.py@@ -0,0 +1,75 @@+"""The classification has to keep up with the dispatch table.++A custom event type added to `ClientBase._EVENT_DISPATCH` without a decision+here is recorded by default, which is the safe direction but not a decision.+These tests make the omission visible instead of letting it ride.+"""++from switch_core.clients.client_base import ClientBase+from switch_core.messages.recorded_types import (+ EPHEMERAL,+ NOT_RECORDED,+ PERSISTED_ELSEWHERE,+ RETIRED,+ TELEMETRY,+ should_record,+)++# The one custom type that is part of the conversation: a person typing+# `!invite-agent` into a room.+RECORDED_CUSTOM_TYPES = frozenset({"com.switch.command"})+++def test_every_dispatched_type_is_classified():+ dispatched = set(ClientBase._EVENT_DISPATCH)+ unclassified = dispatched - NOT_RECORDED - RECORDED_CUSTOM_TYPES+ assert not unclassified, (+ "These custom event types are neither recorded nor denied. Decide "+ "which they are in switch_core/messages/recorded_types.py: "+ f"{sorted(unclassified)}"+ )+++def test_classification_names_no_type_that_is_never_dispatched():+ dispatched = set(ClientBase._EVENT_DISPATCH)+ stale = (NOT_RECORDED | RECORDED_CUSTOM_TYPES) - dispatched - RETIRED+ assert not stale, f"Classified but no longer dispatched: {sorted(stale)}"+++def test_retired_types_are_the_ones_nothing_dispatches():+ """The set exists for types the code no longer has. A name that is back in+ the dispatch table is a live type and belongs in a live bucket."""+ revived = RETIRED & set(ClientBase._EVENT_DISPATCH)+ assert not revived, f"Retired but dispatched again: {sorted(revived)}"+++def test_a_retired_type_is_still_classified():+ """History outlives the code that wrote it: an event of a deleted type is+ still on the bus, and a walk over that history has to know what it was."""+ assert not should_record("com.switch.mediation.tool_result")+++def test_the_buckets_do_not_overlap():+ buckets = [EPHEMERAL, PERSISTED_ELSEWHERE, TELEMETRY, RETIRED]+ total = sum(len(bucket) for bucket in buckets)+ assert total == len(NOT_RECORDED)+++def test_conversation_is_recorded():+ assert should_record("m.room.message")+ assert should_record("com.switch.command")+++def test_bus_traffic_is_not_recorded():+ assert not should_record("com.switch.agent.runtime_state")+ assert not should_record("com.switch.task.delegate")+ assert not should_record("com.switch.report.llm_call")+++def test_the_unimplemented_observe_prefix_is_not_recorded():+ assert not should_record("com.switch.observe.anything")+++def test_an_unknown_type_is_recorded_rather_than_dropped():+ """The denylist fails towards keeping too much, never towards silence."""+ assert should_record("com.switch.something.nobody.has.written.yet")diff --git a/core/tests/switch_core/provisioning/__init__.py b/core/tests/switch_core/provisioning/__init__.pynew file mode 100644index 000000000..e69de29bbdiff --git a/core/tests/switch_core/provisioning/test_postgres_provisioning.py b/core/tests/switch_core/provisioning/test_postgres_provisioning.pynew file mode 100644index 000000000..99eb40ff6--- /dev/null+++ b/core/tests/switch_core/provisioning/test_postgres_provisioning.py@@ -0,0 +1,261 @@+"""Provisioning against the database, where every operation is a row.++Against a real PostgreSQL, because what is being tested is what the tables end+up holding — a membership, an arrival, and the absence of either.+"""++from __future__ import annotations++import uuid++import pytest+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker++from switch_core.db.models import Client, ClientRoom, Room+from switch_core.db.stores.client_store import ClientStore+from switch_core.db.stores.message_store import MessageStore+from switch_core.db.stores.room_store import RoomStore+from switch_core.provisioning.postgres import (+ MEMBERSHIP_EVENT_TYPE,+ PostgresProvisioning,+ ProvisioningError,+ new_room_id,+)+from switch_core.transport.invites import InviteBus+++async def _client(session: AsyncSession, name: str = "someone") -> Client:+ client = Client(+ matrix_user_id=f"@{name}-{uuid.uuid4().hex[:8]}:test",+ display_name=name,+ type="agent",+ password=str(uuid.uuid4()),+ )+ session.add(client)+ await session.flush()+ return client+++async def _room(session: AsyncSession) -> Room:+ room = Room(matrix_room_id=new_room_id(), name="a room", description="")+ session.add(room)+ await session.flush()+ return room+++def _provisioning(+ session_factory: async_sessionmaker[AsyncSession],+ invites: InviteBus | None = None,+) -> PostgresProvisioning:+ return PostgresProvisioning(+ session_factory=session_factory,+ room_store=RoomStore(),+ client_store=ClientStore(),+ message_store=MessageStore(),+ invites=invites or InviteBus(),+ )+++class TestAccounts:+ async def test_registering_writes_nothing(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """The caller's `clients` row is the account; there is no second+ system to create one in."""+ await _provisioning(session_factory).register_user("@a:test", "secret")++ async with session_factory() as session:+ assert await ClientStore().get_by_matrix_user_id(session, "@a:test") is None++ async def test_a_password_is_checked_against_the_client_row(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ client = await _client(session)+ await session.commit()+ user_id, password = client.matrix_user_id, client.password++ provisioning = _provisioning(session_factory)+ assert await provisioning.verify_login(user_id, password) is True+ assert await provisioning.verify_login(user_id, "wrong") is False+ assert await provisioning.verify_login("@nobody:test", password) is False+++class TestRooms:+ async def test_creating_a_room_mints_an_id_and_writes_no_row(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """The room is the caller's to create. A second record of it here+ would be a second thing to keep in step."""+ provisioning = _provisioning(session_factory)++ first = await provisioning.create_room("a", "b")+ second = await provisioning.create_room("a", "b")++ assert first != second+ async with session_factory() as session:+ assert await RoomStore().get_by_matrix_room_id(session, first) is None+++class TestMembership:+ async def test_a_member_who_is_not_running_is_written_in_directly(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ room = await _room(session)+ client = await _client(session, "nova")+ await session.commit()+ room_id, transport_room_id = room.id, room.matrix_room_id+ client_id, user_id = client.id, client.matrix_user_id++ await _provisioning(session_factory).invite_to_room(transport_room_id, user_id)++ async with session_factory() as session:+ membership = await session.get(+ ClientRoom, {"client_id": client_id, "room_id": room_id}+ )+ rows = await MessageStore().list_for_room(+ session, room_id, after_seq=0, limit=10+ )++ assert membership is not None+ # The arrival explains the membership, and carries no rendered+ # sentence: how it reads is the reader's to phrase.+ assert [row.event_type for row in rows] == [MEMBERSHIP_EVENT_TYPE]+ assert rows[0].sender_matrix_id == user_id+ assert rows[0].sender_name == "nova"+ assert rows[0].body is None++ async def test_a_running_member_is_woken_and_joins_itself(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """Waking the client is what leaves its transport watching the room.+ Writing the membership underneath it would put it in a room it never+ reads."""+ async with session_factory() as session:+ room = await _room(session)+ client = await _client(session)+ await session.commit()+ room_id, transport_room_id = room.id, room.matrix_room_id+ client_id, user_id = client.id, client.matrix_user_id++ woken: list[str] = []++ async def _handler(invited_to: str) -> None:+ woken.append(invited_to)++ invites = InviteBus()+ invites.register(user_id, _handler)+ await _provisioning(session_factory, invites).invite_to_room(+ transport_room_id, user_id+ )++ assert woken == [transport_room_id]+ async with session_factory() as session:+ membership = await session.get(+ ClientRoom, {"client_id": client_id, "room_id": room_id}+ )+ # Left to the client, which joins itself in response.+ assert membership is None++ async def test_inviting_a_member_who_is_already_in_does_nothing(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ room = await _room(session)+ client = await _client(session)+ await session.commit()+ transport_room_id, user_id = room.matrix_room_id, client.matrix_user_id+ room_id, client_id = room.id, client.id++ provisioning = _provisioning(session_factory)+ await provisioning.invite_to_room(transport_room_id, user_id)+ await provisioning.invite_to_room(transport_room_id, user_id)++ async with session_factory() as session:+ rows = await MessageStore().list_for_room(+ session, room_id, after_seq=0, limit=10+ )+ membership = await session.get(+ ClientRoom, {"client_id": client_id, "room_id": room_id}+ )++ assert membership is not None+ assert len(rows) == 1++ async def test_removing_a_member_takes_the_membership_away(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ room = await _room(session)+ client = await _client(session)+ await session.commit()+ transport_room_id, user_id = room.matrix_room_id, client.matrix_user_id+ room_id, client_id = room.id, client.id++ provisioning = _provisioning(session_factory)+ await provisioning.invite_to_room(transport_room_id, user_id)+ await provisioning.kick_user(transport_room_id, user_id)++ async with session_factory() as session:+ membership = await session.get(+ ClientRoom, {"client_id": client_id, "room_id": room_id}+ )+ assert membership is None++ async def test_removing_a_member_who_is_already_out_is_success(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ room = await _room(session)+ client = await _client(session)+ await session.commit()+ transport_room_id, user_id = room.matrix_room_id, client.matrix_user_id++ await _provisioning(session_factory).kick_user(transport_room_id, user_id)++ async def test_a_room_or_member_switch_does_not_know_is_an_error(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ room = await _room(session)+ await session.commit()+ transport_room_id = room.matrix_room_id++ provisioning = _provisioning(session_factory)+ with pytest.raises(ProvisioningError):+ await provisioning.invite_to_room("sw_room_nowhere", "@a:test")+ with pytest.raises(ProvisioningError):+ await provisioning.invite_to_room(transport_room_id, "@nobody:test")++ async def test_a_recorded_member_is_still_woken(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """A row is not proof that a running client is watching the room.++ Something else may have written it, and there is a window at startup+ where a client is running but not yet on the bus. Returning early on+ the row would make a deaf membership permanent: every later+ invitation would find the same row and stop.+ """+ async with session_factory() as session:+ room = await _room(session)+ client = await _client(session)+ await session.commit()+ transport_room_id, user_id = room.matrix_room_id, client.matrix_user_id++ woken: list[str] = []++ async def _handler(invited_to: str) -> None:+ woken.append(invited_to)++ provisioning = _provisioning(session_factory)+ await provisioning.invite_to_room(transport_room_id, user_id)++ invites = InviteBus()+ invites.register(user_id, _handler)+ await _provisioning(session_factory, invites).invite_to_room(+ transport_room_id, user_id+ )++ assert woken == [transport_room_id]diff --git a/core/tests/switch_core/test_migration_parity.py b/core/tests/switch_core/test_migration_parity.pynew file mode 100644index 000000000..8f7579777--- /dev/null+++ b/core/tests/switch_core/test_migration_parity.py@@ -0,0 +1,106 @@+"""The migrations build the schema the models describe.++Every other test provisions its schema with `Base.metadata.create_all`, so a+model can gain a column, an index or a constraint that no migration ever+applies and the whole suite still passes — the drift only shows up on a real+deployment, where the table is the one Alembic built. This test replays the+chain into an empty database and asks Alembic's autogenerate comparison+whether anything is still missing.+"""++from __future__ import annotations++from pathlib import Path+from typing import Any++import pytest+from alembic.autogenerate import compare_metadata+from alembic.config import Config+from alembic.migration import MigrationContext+from alembic.runtime.environment import EnvironmentContext+from alembic.script import ScriptDirectory+from sqlalchemy import Connection, text+from sqlalchemy.ext.asyncio import create_async_engine++import switch_core.db.models # noqa: F401 — registers every table on Base.metadata+from switch_core.db.base import Base++_CORE = Path(__file__).resolve().parents[2]+_PARITY_DB = "migration_parity"+++def _script_directory(config: Config) -> ScriptDirectory:+ config.set_main_option("script_location", str(_CORE / "switch_core" / "migrations"))+ return ScriptDirectory.from_config(config)+++def _upgrade_to_head(connection: Connection) -> None:+ """Replay the chain on an explicit connection.++ Driven through `EnvironmentContext` rather than `alembic.command.upgrade`+ so the repo's `env.py` — which builds its own engine from `SwitchConfig`+ and would point at the deployment database — is never loaded.+ """+ config = Config(str(_CORE / "alembic.ini"))+ script = _script_directory(config)++ def do_upgrade(revision: str, context: Any) -> Any:+ return script._upgrade_revs("head", revision)++ with EnvironmentContext(config, script, fn=do_upgrade) as environment:+ environment.configure(connection=connection, target_metadata=Base.metadata)+ with environment.begin_transaction():+ environment.run_migrations()+++def _diff(connection: Connection) -> list[Any]:+ context = MigrationContext.configure(connection)+ return list(compare_metadata(context, Base.metadata))+++def _is_real_drift(entry: Any) -> bool:+ """Filter the one comparison Alembic cannot make faithfully.++ A server default is compared as rendered SQL text, and Postgres echoes+ `func.now()` back as `now()` while the model still holds the SQLAlchemy+ construct, so every `server_default` column reports as modified whether or+ not the migration matches. Nothing else is filtered: a missing table,+ column, index, constraint or nullability change is real drift.+ """+ return not (isinstance(entry, tuple) and entry[0] == "modify_default")+++async def migrated_url(postgres_url: str) -> Any:+ """An empty database, separate from the create_all one the store tests use."""+ admin = create_async_engine(postgres_url, isolation_level="AUTOCOMMIT")+ async with admin.connect() as connection:+ await connection.execute(text(f'DROP DATABASE IF EXISTS "{_PARITY_DB}"'))+ await connection.execute(text(f'CREATE DATABASE "{_PARITY_DB}"'))+ await admin.dispose()++ base, _, _ = postgres_url.rpartition("/")+ try:+ yield f"{base}/{_PARITY_DB}"+ finally:+ admin = create_async_engine(postgres_url, isolation_level="AUTOCOMMIT")+ async with admin.connect() as connection:+ await connection.execute(text(f'DROP DATABASE IF EXISTS "{_PARITY_DB}"'))+ await admin.dispose()+++async def test_migrations_match_the_models(migrated_url: str) -> None:+ engine = create_async_engine(migrated_url)+ try:+ async with engine.begin() as connection:+ await connection.run_sync(_upgrade_to_head)+ async with engine.connect() as connection:+ diff = await connection.run_sync(_diff)+ finally:+ await engine.dispose()++ drift = [entry for entry in diff if _is_real_drift(entry)]+ assert not drift, (+ "the migrations and the models disagree; autogenerate would emit:\n"+ + "\n".join(f" {entry}" for entry in drift)+ )diff --git a/core/tests/switch_core/test_provisioning_port.py b/core/tests/switch_core/test_provisioning_port.pynew file mode 100644index 000000000..f223eb8e6--- /dev/null+++ b/core/tests/switch_core/test_provisioning_port.py@@ -0,0 +1,58 @@+"""Every provisioning implementation must satisfy the port.++Structural conformance is not checked anywhere else: neither implementation+names the Protocol, and every caller annotates the port, so a signature+drifting apart from the contract would type-check on both sides and only fail+at the call. This is the same guard `test_no_nio_outside_transport.py` gives the+transport port, in the shape a Protocol allows.+"""++from __future__ import annotations++import inspect++import pytest++from switch_core.matrix_admin import MatrixAdmin+from switch_core.provisioning import Provisioning+from switch_core.provisioning.postgres import PostgresProvisioning++[email protected]("implementation", [MatrixAdmin, PostgresProvisioning])+def test_it_is_a_provisioning_implementation(implementation: type) -> None:+ assert isinstance(implementation.__new__(implementation), Provisioning), (+ f"{implementation.__name__} no longer satisfies Provisioning"+ )+++def test_every_port_operation_has_a_matching_signature() -> None:+ """`isinstance` on a Protocol checks names only, not what they take.++ A parameter renamed or dropped on one side is exactly the drift this port+ exists to prevent, and it is invisible to the check above.+ """+ for name in (+ "register_user",+ "verify_login",+ "create_room",+ "invite_to_room",+ "kick_user",+ "delete_room",+ "close",+ ):+ expected = _rendered(getattr(Provisioning, name))+ for implementation in (MatrixAdmin, PostgresProvisioning):+ actual = _rendered(getattr(implementation, name))+ assert actual == expected, (+ f"{implementation.__name__}.{name} does not match the port"+ )+++def _rendered(func: object) -> str:+ """A signature as text, with the quotes deferred annotations add removed.++ The port defers its annotations and `matrix_admin` does not, so the two+ render the same types differently — `'str'` against `str` — while meaning+ the same thing. Comparing the text without quotes compares the contract.+ """+ return str(inspect.signature(func)).replace("'", "")diff --git a/core/tests/switch_core/transport/fake.py b/core/tests/switch_core/transport/fake.pynew file mode 100644index 000000000..760699a70--- /dev/null+++ b/core/tests/switch_core/transport/fake.py@@ -0,0 +1,245 @@+"""A `MessageTransport` double for tests that need a client without a server.++Every test that used to attach a fake nio client attaches one of these+instead, so the thing under test talks to the port rather than to Matrix.+"""++from __future__ import annotations++from typing import Any++from switch_core.attachments import ATTACHMENT_GROUP_KEY+from switch_core.transport import (+ DownloadResult,+ HistoryPage,+ InboundEvent,+ MessageFormat,+ SendResult,+ TransportError,+ TransportHandlers,+ UploadResult,+)+++class FakeMessageRecorder:+ """A `MessageRecorder` double for tests that send without a database."""++ def __init__(self) -> None:+ self.recorded: list[dict[str, Any]] = []++ async def record(+ self,+ *,+ transport_room_id: str,+ result: SendResult,+ sender_matrix_id: str,+ sender_client_id: str,+ sender_name: str,+ ) -> None:+ self.recorded.append(+ {+ "transport_room_id": transport_room_id,+ "result": result,+ "sender_matrix_id": sender_matrix_id,+ "sender_client_id": sender_client_id,+ "sender_name": sender_name,+ }+ )+++class FakeTransport:+ """Records what was sent and replays what it was primed with."""++ def __init__(+ self,+ *,+ joined: list[str] | None = None,+ upload_uri: str = "mxc://fake/abc",+ history: HistoryPage | None = None,+ download: DownloadResult | None = None,+ fail_send: str | None = None,+ ) -> None:+ self._joined = joined if joined is not None else []+ self._upload_uri = upload_uri+ self._history = history or HistoryPage(events=[], next_token=None)+ self._download = download or DownloadResult(body=b"", content_type="text/plain")+ self._fail_send = fail_send++ self.sent_messages: list[dict[str, Any]] = []+ self.sent_events: list[tuple[str, str, dict[str, object]]] = []+ self.sent_media: list[dict[str, Any]] = []+ self.uploads: list[tuple[bytes, str, str]] = []+ self.typing: list[tuple[str, bool]] = []+ self.joins: list[str] = []+ self.display_names: list[str] = []+ self.handlers = TransportHandlers()+ self.connected = False+ self.closed = False+ self.events_by_id: dict[str, InboundEvent] = {}+ self.next_event_id = 0++ # ── Session ───────────────────────────────────────────────────────────────++ @property+ def session_state(self) -> dict[str, str | None]:+ return {"access_token": "fake-token", "device_id": "FAKEDEVICE"}++ async def connect(self) -> None:+ self.connected = True++ async def close(self) -> None:+ self.closed = True++ async def relogin(self) -> None:+ self.connected = True++ def register_handlers(self, handlers: TransportHandlers) -> None:+ self.handlers = handlers++ async def receive_forever(self, *, since: str | None) -> None:+ return None++ # ── Outbound ──────────────────────────────────────────────────────────────++ def _next_id(self) -> str:+ self.next_event_id += 1+ return f"$fake{self.next_event_id}"++ async def send_message(+ self,+ room_id: str,+ body: str,+ *,+ sender_name: str,+ format: MessageFormat = "text",+ mentions: list[str] | None = None,+ thread_root_id: str | None = None,+ extra_content: dict[str, object] | None = None,+ ) -> SendResult:+ if self._fail_send:+ raise TransportError(self._fail_send)+ self.sent_messages.append(+ {+ "room_id": room_id,+ "body": body,+ "sender_name": sender_name,+ "format": format,+ "mentions": mentions,+ "thread_root_id": thread_root_id,+ "extra_content": extra_content,+ }+ )+ content: dict[str, object] = {+ "msgtype": "m.text",+ "body": body,+ "sender_name": sender_name,+ }+ if extra_content:+ content.update(extra_content)+ if thread_root_id is not None:+ content["m.relates_to"] = {+ "rel_type": "m.thread",+ "event_id": thread_root_id,+ }+ return SendResult(+ event_id=self._next_id(),+ event_type="m.room.message",+ content=content,+ )++ async def send_event(+ self, room_id: str, event_type: str, content: dict[str, object]+ ) -> SendResult:+ if self._fail_send:+ raise TransportError(self._fail_send)+ self.sent_events.append((room_id, event_type, content))+ return SendResult(+ event_id=self._next_id(), event_type=event_type, content=content+ )++ async def send_media(+ self,+ room_id: str,+ uri: str,+ filename: str,+ mimetype: str,+ size: int,+ *,+ sender_name: str,+ msgtype: str,+ caption: str | None = None,+ thread_root_id: str | None = None,+ group: dict[str, object] | None = None,+ ) -> SendResult:+ if self._fail_send:+ raise TransportError(self._fail_send)+ self.sent_media.append(+ {+ "room_id": room_id,+ "uri": uri,+ "filename": filename,+ "mimetype": mimetype,+ "size": size,+ "sender_name": sender_name,+ "msgtype": msgtype,+ "caption": caption,+ "thread_root_id": thread_root_id,+ "group": group,+ }+ )+ content: dict[str, object] = {+ "msgtype": msgtype,+ "body": caption if caption else filename,+ "url": uri,+ "info": {"mimetype": mimetype, "size": size},+ "sender_name": sender_name,+ }+ if caption:+ content["filename"] = filename+ if group is not None:+ content[ATTACHMENT_GROUP_KEY] = group+ if thread_root_id is not None:+ content["m.relates_to"] = {+ "rel_type": "m.thread",+ "event_id": thread_root_id,+ }+ return SendResult(+ event_id=self._next_id(),+ event_type="m.room.message",+ content=content,+ )++ async def upload_media(+ self, data: bytes, content_type: str, filename: str+ ) -> UploadResult:+ self.uploads.append((data, content_type, filename))+ return UploadResult(uri=self._upload_uri)++ async def download_media(self, uri: str) -> DownloadResult:+ return self._download++ async def set_typing(self, room_id: str, is_typing: bool) -> None:+ self.typing.append((room_id, is_typing))++ # ── History ───────────────────────────────────────────────────────────────++ async def get_event(self, room_id: str, event_id: str) -> InboundEvent | None:+ return self.events_by_id.get(event_id)++ async def read_history(+ self, room_id: str, *, start: str | None, limit: int+ ) -> HistoryPage:+ return self._history++ # ── Rooms ─────────────────────────────────────────────────────────────────++ async def join_room(self, room_id: str) -> bool:+ self.joins.append(room_id)+ self._joined.append(room_id)+ return True++ async def joined_rooms(self) -> list[str]:+ return list(self._joined)++ async def set_display_name(self, display_name: str) -> None:+ self.display_names.append(display_name)diff --git a/core/tests/switch_core/transport/test_matrix_transport.py b/core/tests/switch_core/transport/test_matrix_transport.pynew file mode 100644index 000000000..01e0bb6e2--- /dev/null+++ b/core/tests/switch_core/transport/test_matrix_transport.py@@ -0,0 +1,224 @@+from types import SimpleNamespace+from typing import Any++import pytest+from nio import RoomMessagesError, RoomSendError++from switch_core.attachments import ATTACHMENT_GROUP_KEY+from switch_core.transport import (+ MessageTransport,+ TransportError,+ TransportHandlers,+)+from switch_core.transport.matrix import MatrixTransport+++class _FakeNio:+ def __init__(self, *, send_result: Any = None, upload_result: Any = None) -> None:+ self._send_result = send_result or SimpleNamespace(event_id="$evt")+ self._upload_result = upload_result+ self.room_send_calls: list[tuple[str, str, dict]] = []+ self.typing_calls: list[tuple[str, bool]] = []+ self.callbacks: list[tuple[Any, Any]] = []+ self.response_callbacks: list[tuple[Any, Any]] = []+ self.access_token = "tok"++ async def room_send(self, room_id: str, event_type: str, content: dict) -> Any:+ self.room_send_calls.append((room_id, event_type, content))+ return self._send_result++ async def upload(self, **kwargs: Any) -> tuple[Any, None]:+ return self._upload_result, None++ async def room_typing(self, room_id: str, is_typing: bool) -> Any:+ self.typing_calls.append((room_id, is_typing))+ return SimpleNamespace()++ async def joined_rooms(self) -> Any:+ return SimpleNamespace(rooms=["!a:s"])++ async def join(self, room_id: str) -> Any:+ return SimpleNamespace(room_id=room_id)++ async def room_messages(self, room_id: str, start: str | None, limit: int) -> Any:+ return SimpleNamespace(chunk=["e1", "e2"], end="tok-2")++ def add_event_callback(self, cb: Any, kind: Any) -> None:+ self.callbacks.append((cb, kind))++ def add_response_callback(self, cb: Any, kind: Any) -> None:+ self.response_callbacks.append((cb, kind))+++def _transport(nio: _FakeNio) -> MatrixTransport:+ return MatrixTransport(+ server_url="https://s",+ user_id="@a:s",+ password="pw",+ client=nio,+ )+++def test_matrix_transport_satisfies_the_port() -> None:+ assert isinstance(_transport(_FakeNio()), MessageTransport)+++async def test_send_message_returns_a_neutral_result() -> None:+ nio = _FakeNio()++ result = await _transport(nio).send_message("!r:s", "hi", sender_name="Alice")++ assert result.event_id == "$evt"+ room_id, event_type, content = nio.room_send_calls[0]+ assert (room_id, event_type) == ("!r:s", "m.room.message")+ assert content["body"] == "hi"+ assert content["sender_name"] == "Alice"+++async def test_send_message_threads_via_a_pure_thread_relation() -> None:+ nio = _FakeNio()++ await _transport(nio).send_message(+ "!r:s", "hi", sender_name="Alice", thread_root_id="$root"+ )++ _, _, content = nio.room_send_calls[0]+ assert content["m.relates_to"] == {"rel_type": "m.thread", "event_id": "$root"}+++async def test_send_message_raises_rather_than_returning_an_error() -> None:+ nio = _FakeNio(send_result=object.__new__(RoomSendError))+ nio._send_result.message = "nope" # type: ignore[attr-defined]++ with pytest.raises(TransportError, match="nope"):+ await _transport(nio).send_message("!r:s", "hi", sender_name="Alice")+++async def test_send_media_with_a_caption_keeps_the_filename_separate() -> None:+ # The rich-media-caption convention: body carries the caption, and the real+ # filename rides alongside so it is not lost.+ nio = _FakeNio()++ await _transport(nio).send_media(+ "!r:s",+ "mxc://s/abc",+ "cat.png",+ "image/png",+ 5,+ sender_name="Alice",+ msgtype="m.image",+ caption="look at this",+ )++ _, _, content = nio.room_send_calls[0]+ assert content["body"] == "look at this"+ assert content["filename"] == "cat.png"+ assert content["url"] == "mxc://s/abc"+ assert content["info"] == {"mimetype": "image/png", "size": 5}+++async def test_send_media_without_a_caption_uses_the_filename_as_body() -> None:+ nio = _FakeNio()++ await _transport(nio).send_media(+ "!r:s",+ "mxc://s/abc",+ "cat.png",+ "image/png",+ 5,+ sender_name="Alice",+ msgtype="m.image",+ )++ _, _, content = nio.room_send_calls[0]+ assert content["body"] == "cat.png"+ # No caption means nothing to disambiguate, so no separate filename key.+ assert "filename" not in content+++async def test_send_media_marks_a_multi_file_group() -> None:+ # Matrix has no multi-attachment event, so N files share a group id that+ # receivers coalesce back into one message.+ nio = _FakeNio()+ group = {"id": "g1", "index": 0, "total": 2}++ await _transport(nio).send_media(+ "!r:s",+ "mxc://s/abc",+ "cat.png",+ "image/png",+ 5,+ sender_name="Alice",+ msgtype="m.image",+ group=group,+ )++ _, _, content = nio.room_send_calls[0]+ assert content[ATTACHMENT_GROUP_KEY] == group+++async def test_send_event_carries_the_type_through() -> None:+ nio = _FakeNio()++ await _transport(nio).send_event("!r:s", "com.switch.task.accept", {"task_id": "t"})++ assert nio.room_send_calls[0][1] == "com.switch.task.accept"+++async def test_read_history_returns_neutral_events_and_its_cursor() -> None:+ nio = _FakeNio()++ async def _chunk(*args: Any, **kwargs: Any) -> Any:+ return SimpleNamespace(+ chunk=[+ SimpleNamespace(+ event_id="$1",+ sender="@a:s",+ server_timestamp=7,+ body="hello",+ source={"content": {"body": "hello"}},+ )+ ],+ end="tok-2",+ )++ nio.room_messages = _chunk # type: ignore[assignment]++ page = await _transport(nio).read_history("!r:s", start=None, limit=10)++ assert page.next_token == "tok-2"+ assert [e.event_id for e in page.events] == ["$1"]+ # History arrives already converted, so callers never see a nio type.+ assert page.events[0].room_id == "!r:s"+ assert page.events[0].timestamp == 7+++async def test_read_history_raises_on_failure() -> None:+ nio = _FakeNio()+ err = object.__new__(RoomMessagesError)+ err.message = "boom" # type: ignore[attr-defined]++ async def _fail(*args: Any, **kwargs: Any) -> Any:+ return err++ nio.room_messages = _fail # type: ignore[assignment]++ with pytest.raises(TransportError, match="boom"):+ await _transport(nio).read_history("!r:s", start=None, limit=10)+++def test_register_handlers_binds_only_what_was_supplied() -> None:+ nio = _FakeNio()++ _transport(nio).register_handlers(TransportHandlers(on_message=lambda r, e: None)) # type: ignore[arg-type]++ assert len(nio.callbacks) == 1+ assert nio.response_callbacks == []+++async def test_typing_is_best_effort() -> None:+ nio = _FakeNio()++ await _transport(nio).set_typing("!r:s", True)++ assert nio.typing_calls == [("!r:s", True)]diff --git a/core/tests/switch_core/transport/test_no_nio_outside_transport.py b/core/tests/switch_core/transport/test_no_nio_outside_transport.pynew file mode 100644index 000000000..efc10f439--- /dev/null+++ b/core/tests/switch_core/transport/test_no_nio_outside_transport.py@@ -0,0 +1,57 @@+"""The seam only holds if something enforces it.++Matrix may be imported in exactly one place. Without this check the port+erodes the first time someone reaches for a nio type in a hurry, and the+erosion is invisible until the homeserver is being replaced.+"""++import ast+import pathlib++PACKAGE = pathlib.Path(__file__).resolve().parents[3] / "switch_core"+ALLOWED = {PACKAGE / "transport" / "matrix.py"}+++def _imports_nio(path: pathlib.Path) -> bool:+ tree = ast.parse(path.read_text(), filename=str(path))+ for node in ast.walk(tree):+ if isinstance(node, ast.Import):+ if any(a.name == "nio" or a.name.startswith("nio.") for a in node.names):+ return True+ elif isinstance(node, ast.ImportFrom):+ module = node.module or ""+ if module == "nio" or module.startswith("nio."):+ return True+ return False+++def test_only_the_matrix_transport_imports_nio() -> None:+ offenders = sorted(+ str(path.relative_to(PACKAGE))+ for path in PACKAGE.rglob("*.py")+ if path not in ALLOWED and _imports_nio(path)+ )++ assert offenders == [], (+ "matrix-nio may only be imported by switch_core/transport/matrix.py; "+ f"these modules import it directly: {offenders}. "+ "Add what you need to MessageTransport instead."+ )+++def test_the_guard_can_actually_see_an_import(tmp_path: pathlib.Path) -> None:+ offender = tmp_path / "offender.py"+ offender.write_text("from nio import AsyncClient\n")++ assert _imports_nio(offender)+++def test_no_module_reaches_for_a_raw_client() -> None:+ """`nio_client` was the escape hatch during the port. It is gone."""+ offenders = sorted(+ str(path.relative_to(PACKAGE))+ for path in PACKAGE.rglob("*.py")+ if "nio_client" in path.read_text()+ )++ assert offenders == []diff --git a/core/tests/switch_core/transport/test_postgres_transport.py b/core/tests/switch_core/transport/test_postgres_transport.pynew file mode 100644index 000000000..f05de0c16--- /dev/null+++ b/core/tests/switch_core/transport/test_postgres_transport.py@@ -0,0 +1,862 @@+"""Sending and receiving over Postgres.++These run against a real database because the whole point of the transport is+what the table ends up holding — the seq allocation, the denormalised columns+and the attachment row are the behaviour, not an implementation detail behind+it.++What is deliberately not implemented is tested too: a transport that quietly+returns nothing would look like a working deployment with a silent room, which+is the one failure this codebase refuses to ship.+"""++from __future__ import annotations++import asyncio+import uuid+from collections.abc import Iterator++import pytest+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker++from switch_core.db.models import Client, Room+from switch_core.db.stores.media_store import MediaStore+from switch_core.db.stores.message_store import MessageStore+from switch_core.db.stores.room_store import RoomStore+from switch_core.transport import (+ InboundCustomEvent,+ InboundMedia,+ InboundMembership,+ InboundMessage,+ MessageTransport,+ TransportError,+ TransportHandlers,+)+from switch_core.transport.ephemeral import EphemeralBus+from switch_core.transport.invites import InviteBus+from switch_core.transport.postgres import PostgresTransport+++async def _make_room(session: AsyncSession) -> tuple[str, str, str, str]:+ """Insert the Room and Client a send depends on.++ Returns (room uuid, transport room id, client id, client mxid).+ """+ suffix = uuid.uuid4().hex[:8]+ client = Client(+ matrix_user_id=f"@agent-{suffix}:test",+ display_name="agent one",+ type="agent",+ password="x",+ )+ session.add(client)+ await session.flush()+ room = Room(matrix_room_id=f"!room-{suffix}:test", name="a room", description="")+ session.add(room)+ await session.flush()+ return room.id, room.matrix_room_id, client.id, client.matrix_user_id+++async def _watched_room(transport: PostgresTransport) -> str:+ """Wait until the transport is watching a room, and name it.++ `receive_forever` resolves memberships against the database before it+ subscribes, so a test that sends immediately after starting it would race+ the subscription rather than test anything.+ """+ for _ in range(200):+ if transport._watching:+ return next(iter(transport._watching))+ await asyncio.sleep(0.01)+ raise AssertionError("the transport never started watching a room")+++async def _settled(transport: PostgresTransport) -> None:+ """Wait until a transport has nothing left to read."""+ for _ in range(500):+ if not transport._pending and not transport._delivering:+ return+ await asyncio.sleep(0.005)+ raise AssertionError("the transport never finished delivering")+++class _FakeListener:+ """Stands in for the notify listener, so a test can say "the room moved".++ The real listener is a trigger and a LISTEN, covered by its own tests+ against a live database. What matters here is what the transport does when+ it is woken, which is a question about cursors and conversion.+ """++ def __init__(self) -> None:+ self.wakers: dict[str, set] = {}++ def subscribe(self, room_id: str, waker) -> None:+ self.wakers.setdefault(room_id, set()).add(waker)++ def unsubscribe(self, room_id: str, waker) -> None:+ self.wakers.get(room_id, set()).discard(waker)++ async def announce(self, room_id: str) -> None:+ """Say the room moved, and wait for the reading it provokes.++ A waker only notes the room now — each transport reads on its own+ loop, so that a client whose handler is slow cannot hold up anyone+ else's delivery. Waiting for those loops to go idle is what makes a+ test assert on what was delivered rather than on the timing.+ """+ woken = []+ for waker in list(self.wakers.get(room_id, ())):+ await waker(room_id)+ woken.append(waker.__self__)+ for transport in woken:+ await _settled(transport)+++class _Received:+ """Collects what the transport handed to each handler."""++ def __init__(self) -> None:+ self.events: list[object] = []++ def handlers(self) -> TransportHandlers:+ return TransportHandlers(+ on_message=self._take,+ on_media=self._take,+ on_member_event=self._take,+ on_custom_event=self._take,+ )++ async def _take(self, _room, event) -> None:+ self.events.append(event)+++def _transport(+ session_factory: async_sessionmaker[AsyncSession],+ *,+ client_id: str,+ user_id: str,+ listener: _FakeListener | None = None,+ ephemeral: EphemeralBus | None = None,+) -> PostgresTransport:+ return PostgresTransport(+ user_id=user_id,+ client_id=client_id,+ display_name="agent one",+ session_factory=session_factory,+ room_store=RoomStore(),+ message_store=MessageStore(),+ media_store=MediaStore(),+ listener=listener or _FakeListener(),+ invites=InviteBus(),+ ephemeral=ephemeral or EphemeralBus(),+ )+++class TestConformsToThePort:+ def test_it_is_a_message_transport(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ transport = _transport(session_factory, client_id="c", user_id="@a:test")+ assert isinstance(transport, MessageTransport)+++class TestSending:+ async def test_a_message_becomes_a_row(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ room_id, transport_room_id, client_id, user_id = await _make_room(session)+ await session.commit()++ transport = _transport(session_factory, client_id=client_id, user_id=user_id)+ result = await transport.send_message(+ transport_room_id, "hello", sender_name="agent one"+ )++ async with session_factory() as session:+ message = await MessageStore().get_by_transport_event_id(+ session, result.event_id+ )++ assert message is not None+ assert message.room_id == room_id+ assert message.body == "hello"+ assert message.msgtype == "m.text"+ assert message.event_type == "m.room.message"+ assert message.sender_client_id == client_id+ assert message.sender_matrix_id == user_id+ # The id the caller got back is the row's, so a caller that quotes it+ # in a reply or a thread is naming something that exists.+ assert message.transport_event_id == result.event_id+ assert result.content["body"] == "hello"++ async def test_the_room_orders_its_sends(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ _, transport_room_id, client_id, user_id = await _make_room(session)+ await session.commit()++ transport = _transport(session_factory, client_id=client_id, user_id=user_id)+ first = await transport.send_message(+ transport_room_id, "one", sender_name="agent one"+ )+ second = await transport.send_message(+ transport_room_id, "two", sender_name="agent one"+ )++ async with session_factory() as session:+ store = MessageStore()+ a = await store.get_by_transport_event_id(session, first.event_id)+ b = await store.get_by_transport_event_id(session, second.event_id)++ assert a is not None and b is not None+ assert b.seq > a.seq++ async def test_a_threaded_reply_records_its_root(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ _, transport_room_id, client_id, user_id = await _make_room(session)+ await session.commit()++ transport = _transport(session_factory, client_id=client_id, user_id=user_id)+ result = await transport.send_message(+ transport_room_id,+ "in the thread",+ sender_name="agent one",+ thread_root_id="root-1",+ )++ async with session_factory() as session:+ message = await MessageStore().get_by_transport_event_id(+ session, result.event_id+ )++ assert message is not None+ assert message.thread_root_event_id == "root-1"++ async def test_media_records_the_file_beside_the_message(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ _, transport_room_id, client_id, user_id = await _make_room(session)+ await session.commit()++ transport = _transport(session_factory, client_id=client_id, user_id=user_id)+ result = await transport.send_media(+ transport_room_id,+ "blob://1",+ "report.pdf",+ "application/pdf",+ 2048,+ sender_name="agent one",+ msgtype="m.file",+ caption="the report",+ )++ async with session_factory() as session:+ store = MessageStore()+ message = await store.get_by_transport_event_id(session, result.event_id)+ assert message is not None+ attachments = await store.get_attachments(session, message.id)++ # The caption is the body, per the rich-media-caption convention, and+ # the real filename travels on the attachment.+ assert message.body == "the report"+ assert len(attachments) == 1+ assert attachments[0].uri == "blob://1"+ assert attachments[0].filename == "report.pdf"+ assert attachments[0].mimetype == "application/pdf"+ assert attachments[0].size == 2048++ async def test_a_custom_event_is_stored_whole(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """A task event is not conversation, but it still has to reach its+ handler, and here the row is the only way it can."""+ async with session_factory() as session:+ _, transport_room_id, client_id, user_id = await _make_room(session)+ await session.commit()++ transport = _transport(session_factory, client_id=client_id, user_id=user_id)+ result = await transport.send_event(+ transport_room_id, "com.switch.task.accept", {"task_id": "t-1"}+ )++ async with session_factory() as session:+ message = await MessageStore().get_by_transport_event_id(+ session, result.event_id+ )++ assert message is not None+ assert message.event_type == "com.switch.task.accept"+ assert message.content == {"task_id": "t-1"}+ assert message.body is None++ async def test_ephemeral_state_is_announced_and_not_stored(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """Presence has no history worth keeping: the next value replaces it,+ and a row would put it in the room's order for nobody to read."""+ async with session_factory() as session:+ _, transport_room_id, client_id, user_id = await _make_room(session)+ await session.commit()++ transport = _transport(session_factory, client_id=client_id, user_id=user_id)+ result = await transport.send_event(+ transport_room_id, "com.switch.agent.runtime_state", {"state": "working"}+ )++ async with session_factory() as session:+ message = await MessageStore().get_by_transport_event_id(+ session, result.event_id+ )++ assert message is None+ assert result.event_id++ async def test_sending_to_a_room_switch_does_not_know_fails(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ transport = _transport(session_factory, client_id="c", user_id="@a:test")+ with pytest.raises(TransportError):+ await transport.send_message(+ "!nowhere:test", "hello", sender_name="agent one"+ )+++class TestRooms:+ async def test_joining_is_a_membership_row_and_is_idempotent(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ _, transport_room_id, client_id, user_id = await _make_room(session)+ await session.commit()++ transport = _transport(session_factory, client_id=client_id, user_id=user_id)+ assert await transport.join_room(transport_room_id) is True+ assert await transport.join_room(transport_room_id) is True+ assert await transport.joined_rooms() == [transport_room_id]++ async def test_a_client_in_no_rooms_is_in_no_rooms(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ _, _, client_id, user_id = await _make_room(session)+ await session.commit()++ transport = _transport(session_factory, client_id=client_id, user_id=user_id)+ assert await transport.joined_rooms() == []+++class TestMedia:+ async def test_bytes_go_in_and_come_back(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ transport = _transport(session_factory, client_id="c", user_id="@a:test")++ uploaded = await transport.upload_media(b"file contents", "text/plain", "a.txt")+ downloaded = await transport.download_media(uploaded.uri)++ assert downloaded.body == b"file contents"+ assert downloaded.content_type == "text/plain"+ assert downloaded.filename == "a.txt"++ async def test_two_uploads_of_the_same_bytes_are_two_handles(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """Deduplicating would make one sender's delete another's data loss."""+ transport = _transport(session_factory, client_id="c", user_id="@a:test")++ first = await transport.upload_media(b"same", "text/plain", "a.txt")+ second = await transport.upload_media(b"same", "text/plain", "a.txt")++ assert first.uri != second.uri++ async def test_a_handle_with_nothing_behind_it_raises(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """An empty file is a worse answer than an error: the reader cannot+ tell it apart from a file that was genuinely empty."""+ transport = _transport(session_factory, client_id="c", user_id="@a:test")++ with pytest.raises(TransportError):+ await transport.download_media("switch-media://nothing")+++class TestWhatIsNotBuiltYet:+ async def test_history_refuses_rather_than_answering_from_the_wrong_place(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """The read path queries these rows directly; the only callers of this+ method are the walkers that compare a bus against them."""+ transport = _transport(session_factory, client_id="c", user_id="@a:test")+ with pytest.raises(NotImplementedError):+ await transport.read_history("!r:test", start=None, limit=10)+++class TestReceiving:+ """What a woken transport hands to its handlers.++ Delivery is driven by the announcement the database makes on every insert;+ a fake listener stands in for it so these tests are about the cursor and+ the conversion rather than about the trigger, which has its own.+ """++ async def _receiving(+ self,+ session_factory: async_sessionmaker[AsyncSession],+ ) -> tuple[PostgresTransport, _FakeListener, _Received, str, str]:+ async with session_factory() as session:+ _, transport_room_id, client_id, user_id = await _make_room(session)+ await session.commit()++ 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(transport_room_id)+ task = asyncio.create_task(transport.receive_forever(since=None))+ self._tasks.append((task, transport))+ await _watched_room(transport)+ return transport, listener, received, transport_room_id, user_id++ @pytest.fixture(autouse=True)+ def _cleanup(self) -> Iterator[None]:+ self._tasks: list[tuple[asyncio.Task, PostgresTransport]] = []+ yield+ for task, _ in self._tasks:+ task.cancel()++ async def test_a_message_arrives_as_a_message(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ transport, listener, received, room, _ = await self._receiving(session_factory)++ sent = await transport.send_message(room, "hello", sender_name="agent one")+ await listener.announce(await _watched_room(transport))++ assert len(received.events) == 1+ event = received.events[0]+ assert isinstance(event, InboundMessage)+ assert event.event_id == sent.event_id+ assert event.body == "hello"+ # The room a handler is given is the transport-side id it knows, not+ # the internal one the listener announces.+ assert event.room_id == room++ async def test_the_cursor_starts_at_the_head_and_does_not_repeat(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """A restart is not a replay.++ Everything before this transport started receiving is already someone+ else's problem — a delivery cursor's — and redelivering it would be+ indistinguishable to a reader from it being said again.+ """+ async with session_factory() as session:+ _, room, client_id, user_id = await _make_room(session)+ await session.commit()++ listener = _FakeListener()+ writer = _transport(session_factory, client_id=client_id, user_id=user_id)+ await writer.send_message(room, "said before anyone listened", sender_name="a")++ received = _Received()+ reader = _transport(+ session_factory, client_id=client_id, user_id=user_id, listener=listener+ )+ reader.register_handlers(received.handlers())+ await reader.join_room(room)+ task = asyncio.create_task(reader.receive_forever(since=None))+ self._tasks.append((task, reader))+ switch_room_id = await _watched_room(reader)+ await listener.announce(switch_room_id)+ assert received.events == []++ await writer.send_message(room, "said after", sender_name="a")+ await listener.announce(switch_room_id)+ await listener.announce(switch_room_id)++ bodies = [event.body for event in received.events]+ assert bodies == ["said after"]++ async def test_a_file_arrives_as_media(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ transport, listener, received, room, _ = await self._receiving(session_factory)++ await transport.send_media(+ room,+ "blob://7",+ "notes.txt",+ "text/plain",+ 12,+ sender_name="agent one",+ msgtype="m.file",+ )+ await listener.announce(await _watched_room(transport))++ event = received.events[0]+ assert isinstance(event, InboundMedia)+ assert event.uri == "blob://7"+ assert event.filename == "notes.txt"+ assert event.mimetype == "text/plain"+ assert event.size == 12++ async def test_a_custom_event_arrives_as_one(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ transport, listener, received, room, _ = await self._receiving(session_factory)++ await transport.send_event(room, "com.switch.command", {"command": "roles"})+ await listener.announce(await _watched_room(transport))++ event = received.events[0]+ assert isinstance(event, InboundCustomEvent)+ assert event.event_type == "com.switch.command"+ assert event.content == {"command": "roles"}++ async def test_an_arrival_is_delivered_to_the_members_watching(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """Joining writes the arrival, so the room learns about it the same way+ it learns about anything else: a row it has not read yet."""+ transport, listener, received, room, _ = await self._receiving(session_factory)++ async with session_factory() as session:+ newcomer = Client(+ matrix_user_id=f"@later-{uuid.uuid4().hex[:8]}:test",+ display_name="the newcomer",+ type="agent",+ password="x",+ )+ session.add(newcomer)+ await session.commit()+ newcomer_id, newcomer_mxid = newcomer.id, newcomer.matrix_user_id++ joiner = _transport(+ session_factory, client_id=newcomer_id, user_id=newcomer_mxid+ )+ joiner.display_name = "the newcomer"+ await joiner.join_room(room)+ await listener.announce(await _watched_room(transport))++ event = received.events[0]+ assert isinstance(event, InboundMembership)+ assert event.state_key == newcomer_mxid+ assert event.membership == "join"+ assert event.display_name == "the newcomer"+++class TestPresence:+ """Events that are announced and never stored still have to arrive.++ Dropping the row dropped the delivery with it: runtime state was recorded+ in its own table and reached nobody, so an agent going busy stopped showing+ up on a bridged channel. The value travels on the announcement, because+ there is no row for a reader to go and fetch.+ """++ @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_presence_reaches_the_other_clients_watching_the_room(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ _, room, client_id, user_id = await _make_room(session)+ await session.commit()++ ephemeral = EphemeralBus()+ received = _Received()+ watcher = _transport(+ session_factory, client_id=client_id, user_id=user_id, ephemeral=ephemeral+ )+ watcher.register_handlers(received.handlers())+ await watcher.join_room(room)+ self._tasks.append(asyncio.create_task(watcher.receive_forever(since=None)))+ await _watched_room(watcher)++ sender = _transport(+ session_factory, client_id=client_id, user_id=user_id, ephemeral=ephemeral+ )+ await sender.send_event(+ room, "com.switch.agent.runtime_state", {"state": "working"}+ )++ assert len(received.events) == 1+ event = received.events[0]+ assert isinstance(event, InboundCustomEvent)+ assert event.event_type == "com.switch.agent.runtime_state"+ assert event.content == {"state": "working"}+ # The room a handler is given is the transport-side id, as for a row.+ assert event.room_id == room++ async def test_presence_in_another_room_is_not_delivered(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ _, room, client_id, user_id = await _make_room(session)+ _, elsewhere, other_client_id, other_user_id = await _make_room(session)+ await session.commit()++ ephemeral = EphemeralBus()+ received = _Received()+ watcher = _transport(+ session_factory, client_id=client_id, user_id=user_id, ephemeral=ephemeral+ )+ watcher.register_handlers(received.handlers())+ await watcher.join_room(room)+ self._tasks.append(asyncio.create_task(watcher.receive_forever(since=None)))+ await _watched_room(watcher)++ sender = _transport(+ session_factory,+ client_id=other_client_id,+ user_id=other_user_id,+ ephemeral=ephemeral,+ )+ await sender.send_event(+ elsewhere, "com.switch.agent.runtime_state", {"state": "idle"}+ )++ assert received.events == []++ async def test_a_client_that_stopped_receiving_is_no_longer_told(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """Presence is delivered live, so a closed client must leave the bus —+ otherwise it holds a handler for a room nobody is reading."""+ async with session_factory() as session:+ _, room, client_id, user_id = await _make_room(session)+ await session.commit()++ ephemeral = EphemeralBus()+ received = _Received()+ watcher = _transport(+ session_factory, client_id=client_id, user_id=user_id, ephemeral=ephemeral+ )+ watcher.register_handlers(received.handlers())+ await watcher.join_room(room)+ task = asyncio.create_task(watcher.receive_forever(since=None))+ self._tasks.append(task)+ await _watched_room(watcher)+ await watcher.close()+ await task++ await watcher.send_event(+ room, "com.switch.agent.runtime_state", {"state": "idle"}+ )++ assert received.events == []+++class TestOneClientCannotStallAnother:+ """The listener fans out to every subscriber from a single task.++ So whatever a waker awaits, every other client in the process waits for+ too — and a handler can be a bridge posting to Slack, which is a network+ call that sits in a rate limit for seconds. Under Matrix each client had+ its own sync loop and got this isolation for free; here it is built.+ """++ @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_being_woken_does_not_deliver_on_the_caller_s_time(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ _, room, client_id, user_id = await _make_room(session)+ await session.commit()++ 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(room)+ self._tasks.append(asyncio.create_task(transport.receive_forever(since=None)))+ switch_room_id = await _watched_room(transport)++ await transport.send_message(room, "hello", sender_name="agent one")+ # The waker itself, rather than the fake's announce, which waits for+ # the reading it provokes.+ await transport._on_room_advanced(switch_room_id)++ assert received.events == []+ assert transport._pending == {switch_room_id}++ await _settled(transport)+ assert [event.body for event in received.events] == ["hello"]++ async def test_rooms_that_moved_while_it_was_busy_are_read_once(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """Coalescing is what keeps the loop serial without falling behind:+ a room announced three times is still one read, and running those+ concurrently would deliver the same rows three times."""+ async with session_factory() as session:+ _, room, client_id, user_id = await _make_room(session)+ await session.commit()++ 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(room)+ self._tasks.append(asyncio.create_task(transport.receive_forever(since=None)))+ switch_room_id = await _watched_room(transport)++ await transport.send_message(room, "hello", sender_name="agent one")+ await transport._on_room_advanced(switch_room_id)+ await transport._on_room_advanced(switch_room_id)+ await transport._on_room_advanced(switch_room_id)+ await _settled(transport)++ assert [event.body for event in received.events] == ["hello"]+++class TestJoiningARoomAlreadyRecorded:+ """Membership and subscription are two facts now.++ The homeserver's join *was* what a sync loop delivered, so one implied the+ other. A `client_rooms` row can be written by something other than this+ client, and a join that returned early on finding one would leave a+ running client a member of a room it never reads.+ """++ @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_it_starts_watching_and_writes_no_second_arrival(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ switch_room_id, room, client_id, user_id = await _make_room(session)+ elsewhere_id, elsewhere, _, _ = await _make_room(session)+ await session.commit()++ 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(room)+ self._tasks.append(asyncio.create_task(transport.receive_forever(since=None)))+ await _watched_room(transport)++ # Somebody else records the membership — what a moderation invite does+ # when nothing is listening for this client.+ async with session_factory() as session:+ await RoomStore().add_client(session, client_id, elsewhere_id)+ await session.commit()++ assert await transport.join_room(elsewhere) is True+ # Joining again must not announce a second arrival to the room.+ assert await transport.join_room(elsewhere) is True++ assert elsewhere_id in transport._watching+ async with session_factory() as session:+ rows = await MessageStore().list_for_room(+ session, elsewhere_id, after_seq=0, limit=10+ )+ assert rows == []+++class TestHearingYourOwnArrival:+ """A client learns it joined by being told, as it always did.++ The homeserver turned a join into an event and delivered it to everyone —+ including the client it was about, down its own connection — and code+ downstream (the greeting an agent posts on entering a room) fired on+ receiving it. Writing the row and then watching from the head steps over+ it: the room hears the arrival and the arriving client does not.+ """++ @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_joining_while_receiving_delivers_the_join_to_itself(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ _, room, client_id, user_id = await _make_room(session)+ _, later, _, _ = await _make_room(session)+ await session.commit()++ 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(room)+ self._tasks.append(asyncio.create_task(transport.receive_forever(since=None)))+ await _watched_room(transport)++ await transport.join_room(later)+ await _settled(transport)++ assert len(received.events) == 1+ event = received.events[0]+ assert isinstance(event, InboundMembership)+ assert event.state_key == user_id+ assert event.membership == "join"+ assert event.room_id == later++ async def test_it_hears_the_join_once(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """The cursor starts just below the arrival, not at the room's start:+ a client joining a room with history must not be handed all of it."""+ async with session_factory() as session:+ _, room, client_id, user_id = await _make_room(session)+ _, later, other_id, other_user = await _make_room(session)+ await session.commit()++ talker = _transport(session_factory, client_id=other_id, user_id=other_user)+ await talker.join_room(later)+ await talker.send_message(later, "said before anyone joined", sender_name="a")++ 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(room)+ self._tasks.append(asyncio.create_task(transport.receive_forever(since=None)))+ await _watched_room(transport)++ await transport.join_room(later)+ await _settled(transport)+ await _settled(transport)++ kinds = [type(event) for event in received.events]+ assert kinds == [InboundMembership]diff --git a/core/tests/switch_core/transport/test_sync_durability.py b/core/tests/switch_core/transport/test_sync_durability.pynew file mode 100644index 000000000..bb19bc519--- /dev/null+++ b/core/tests/switch_core/transport/test_sync_durability.py@@ -0,0 +1,85 @@+"""What counts as a batch worth persisting the cursor for.++The judgement has to live here rather than in the client: only the transport+sees what a sync response held, and the port hands the client a bool so a nio+response class never reaches it. The client's side of the bargain — the+throttle, the staleness flush, the per-client jitter — is covered in+`tests/switch_core/clients/test_sync_cursor_persistence.py`.++Timeline events, room state and invites are dispatched to handlers, so a+restart must not skip them. Presence, typing and receipts are not: resuming+from the older cursor replays the same nothing.+"""++from __future__ import annotations++import pytest+from nio import (+ DeviceList,+ DeviceOneTimeKeyCount,+ InviteInfo,+ RoomInfo,+ Rooms,+ SyncResponse,+ Timeline,+)++from switch_core.transport.matrix import _carries_durable_events++ROOM = "!room:switch.local"+++def _sync(+ next_batch: str = "s1",+ *,+ timeline: list[object] | None = None,+ state: list[object] | None = None,+ ephemeral: list[object] | None = None,+ invite: bool = False,+ to_device: list[object] | None = None,+) -> SyncResponse:+ join = {+ ROOM: RoomInfo(+ timeline=Timeline(+ events=list(timeline or []), limited=False, prev_batch=None+ ),+ state=list(state or []),+ ephemeral=list(ephemeral or []),+ account_data=[],+ )+ }+ return SyncResponse(+ next_batch=next_batch,+ rooms=Rooms(+ invite={ROOM: InviteInfo(invite_state=[])} if invite else {},+ join=join,+ leave={},+ ),+ device_key_count=DeviceOneTimeKeyCount(curve25519=None, signed_curve25519=None),+ device_list=DeviceList(changed=[], left=[]),+ to_device_events=list(to_device or []),+ presence_events=[],+ )+++ "kwargs",+ [+ {"timeline": [object()]},+ {"state": [object()]},+ {"invite": True},+ {"to_device": [object()]},+ ],+ ids=["timeline", "state", "invite", "to_device"],+)+def test_anything_a_restart_would_replay_is_durable(kwargs: dict[str, object]) -> None:+ assert _carries_durable_events(_sync(**kwargs)) is True # type: ignore[arg-type]+++def test_an_empty_batch_is_not() -> None:+ assert _carries_durable_events(_sync()) is False+++def test_ephemeral_only_is_not() -> None:+ """Typing notices and read receipts move the token and mean nothing."""+ assert _carries_durable_events(_sync(ephemeral=[object()])) is Falsediff --git a/deploy/local/standalone-docker-compose.yml b/deploy/local/standalone-docker-compose.ymlindex 43f1ca0a3..bf1ec8243 100644--- a/deploy/local/standalone-docker-compose.yml+++ b/deploy/local/standalone-docker-compose.yml@@ -10,7 +10,7 @@# docker compose -f standalone-docker-compose.yml -f standalone-docker-compose.build.yml up## Profiles keep optional services opt-in:-# (core, no profile) postgres, tuwunel, switch — always started+# (core, no profile) postgres, tuwunel, backfill, switch — always started# collab init-db, mattermost, setup — Mattermost bridge + seeder# gateway gateway — operator dashboard# Select them with `--profile collab --profile gateway` or COMPOSE_PROFILES.@@ -142,6 +142,54 @@ services:init-db:condition: service_completed_successfully+ # One-shot: reconstructs each room's history from the homeserver into the+ # message log, then exits. switch waits for it to finish, so the copy is+ # never racing the server that will serve it.+ #+ # It always exits 0, so a backfill that fails delays the stack rather than+ # keeping it down. The trade is deliberate and it is a real one: a failure+ # here is only visible in this service's log, and the stack above it will+ # look healthy while missing history. Backfill is idempotent, so re-running+ # it after fixing the cause costs nothing.+ #+ # It runs alembic first for ordering, not as a second migration owner: the+ # rows it writes need the schema, and switch (which normally migrates on+ # boot) is waiting on this. The upgrade is the same idempotent one.+ #+ # Rooms already walked to their start are skipped, so this is cheap on every+ # boot after the first. Nothing to walk at all is success too — a fresh+ # stack has no rooms and no admin client.+ backfill:+ image: ${SWITCH_REGISTRY:-ghcr.io}/${SWITCH_IMAGE_NAMESPACE:-sandbox-quantum}/switch-core:${SWITCH_VERSION:?required, set it in .env, there is no default}+ restart: "no"+ environment:+ DB_HOST: postgres+ DB_PORT: "5432"+ DB_USER: ${DB_USER}+ DB_PASSWORD: ${DB_PASSWORD}+ DB_NAME: ${DB_NAME}+ MATRIX_SERVER: http://tuwunel:8008+ MATRIX_SERVER_NAME: localhost+ MATRIX_ADMIN_USER: ${MATRIX_ADMIN_USER}+ MATRIX_ADMIN_PASSWORD: ${MATRIX_ADMIN_PASSWORD}+ MATRIX_REGISTRATION_SHARED_SECRET: ${MATRIX_REGISTRATION_SHARED_SECRET}+ AGENT_REGISTRATION_TOKEN: ${AGENT_REGISTRATION_TOKEN}+ JWT_SECRET_KEY: ${JWT_SECRET_KEY}+ GATEWAY_ADMIN_EMAIL: ${GATEWAY_ADMIN_EMAIL}+ GATEWAY_ADMIN_PASSWORD: ${GATEWAY_ADMIN_PASSWORD}+ entrypoint: >+ sh -c "+ alembic upgrade head &&+ python -m switch_core.cli.backfill --allow-empty ||+ echo 'backfill did not complete; starting anyway. Room history from+ before this release may be missing until it is re-run.' >&2+ "+ depends_on:+ postgres:+ condition: service_healthy+ tuwunel:+ condition: service_started+switch:image: ${SWITCH_REGISTRY:-ghcr.io}/${SWITCH_IMAGE_NAMESPACE:-sandbox-quantum}/switch-core:${SWITCH_VERSION:?required, set it in .env, there is no default}ports:@@ -168,6 +216,8 @@ services:condition: service_healthytuwunel:condition: service_started+ backfill:+ condition: service_completed_successfullygateway:image: ${SWITCH_REGISTRY:-ghcr.io}/${SWITCH_IMAGE_NAMESPACE:-sandbox-quantum}/gateway:${SWITCH_VERSION:?required, set it in .env, there is no default}diff --git a/deploy/remote/helm/switch/templates/switch-core/backfill-job.yaml b/deploy/remote/helm/switch/templates/switch-core/backfill-job.yamlnew file mode 100644index 000000000..8c3015852--- /dev/null+++ b/deploy/remote/helm/switch/templates/switch-core/backfill-job.yaml@@ -0,0 +1,58 @@+{{- if .Values.switchCore.backfill.enabled }}+# Reconstructs each room's history from the homeserver into the message log.+#+# Off by default and deliberately not part of a normal release: it is a one-off+# for the move onto the Postgres transport, and as a routine hook it would+# re-walk every room's entire history on every upgrade.+#+# It reads the homeserver, so it can only run while Tuwunel is still deployed —+# and it is the last thing that needs it. Run it with `dryRun: true` first and+# read the log before letting it write.+#+# Ordered after the migrate hook (weight 10 vs 0): it writes into `messages`,+# which alembic has to have created.+apiVersion: batch/v1+kind: Job+metadata:+ name: {{ include "switch.fullname" . }}-backfill+ labels:+ {{- include "switch.labels" . | nindent 4 }}+ {{- include "switch.selectorLabels" (dict "Release" .Release "component" "backfill") | nindent 4 }}+ annotations:+ "helm.sh/hook": post-upgrade+ "helm.sh/hook-weight": "10"+ "helm.sh/hook-delete-policy": before-hook-creation+spec:+ # Backfill is idempotent — a unique transport_event_id and a commit per page,+ # so a retry resumes rather than duplicates.+ backoffLimit: 3+ template:+ metadata:+ labels:+ {{- include "switch.labels" . | nindent 8 }}+ {{- include "switch.selectorLabels" (dict "Release" .Release "component" "backfill") | nindent 8 }}+ spec:+ {{- if .Values.global.imagePullSecrets }}+ {{- include "switch.imagePullSecrets" . | nindent 6 }}+ {{- end }}+ restartPolicy: OnFailure+ initContainers:+ {{- include "switch.waitFor" (dict "name" "postgres" "host" (include "switch.postgresHost" .) "port" (include "switch.postgresPort" .)) | nindent 8 }}+ {{- include "switch.waitFor" (dict "name" "tuwunel" "host" (include "switch.tuwunelHost" .) "port" .Values.tuwunel.service.port) | nindent 8 }}+ containers:+ - name: backfill+ image: {{ include "switch.image" (dict "global" .Values.global "image" .Values.switchCore.image) }}+ imagePullPolicy: {{ .Values.switchCore.imagePullPolicy }}+ command:+ - python+ - -m+ - switch_core.cli.backfill+ {{- if .Values.switchCore.backfill.dryRun }}+ - --dry-run+ {{- end }}+ {{- if .Values.switchCore.backfill.allowEmpty }}+ - --allow-empty+ {{- end }}+ env:+ {{- include "switch.coreEnv" . | nindent 12 }}+{{- end }}diff --git a/deploy/remote/helm/switch/templates/switch-core/reconcile-job.yaml b/deploy/remote/helm/switch/templates/switch-core/reconcile-job.yamlnew file mode 100644index 000000000..7c8feb5c9--- /dev/null+++ b/deploy/remote/helm/switch/templates/switch-core/reconcile-job.yaml@@ -0,0 +1,43 @@+{{- if .Values.switchCore.reconcile.enabled }}+# Compares the recorded messages against what the homeserver holds, and exits+# non-zero on drift. The check to run after a backfill and before flipping the+# transport, because afterwards there is only one record and nothing to compare+# it against.+#+# Off by default, for the same reason as the backfill job: this is a step in a+# migration, not part of a release.+apiVersion: batch/v1+kind: Job+metadata:+ name: {{ include "switch.fullname" . }}-reconcile+ labels:+ {{- include "switch.labels" . | nindent 4 }}+ {{- include "switch.selectorLabels" (dict "Release" .Release "component" "reconcile") | nindent 4 }}+ annotations:+ "helm.sh/hook": post-upgrade+ "helm.sh/hook-weight": "20"+ "helm.sh/hook-delete-policy": before-hook-creation+spec:+ # Read-only, so a retry costs time and nothing else.+ backoffLimit: 1+ template:+ metadata:+ labels:+ {{- include "switch.labels" . | nindent 8 }}+ {{- include "switch.selectorLabels" (dict "Release" .Release "component" "reconcile") | nindent 8 }}+ spec:+ {{- if .Values.global.imagePullSecrets }}+ {{- include "switch.imagePullSecrets" . | nindent 6 }}+ {{- end }}+ restartPolicy: Never+ initContainers:+ {{- include "switch.waitFor" (dict "name" "postgres" "host" (include "switch.postgresHost" .) "port" (include "switch.postgresPort" .)) | nindent 8 }}+ {{- include "switch.waitFor" (dict "name" "tuwunel" "host" (include "switch.tuwunelHost" .) "port" .Values.tuwunel.service.port) | nindent 8 }}+ containers:+ - name: reconcile+ image: {{ include "switch.image" (dict "global" .Values.global "image" .Values.switchCore.image) }}+ imagePullPolicy: {{ .Values.switchCore.imagePullPolicy }}+ command: ["python", "-m", "switch_core.cli.reconcile", "--verbose"]+ env:+ {{- include "switch.coreEnv" . | nindent 12 }}+{{- end }}diff --git a/deploy/remote/helm/switch/values.yaml b/deploy/remote/helm/switch/values.yamlindex 7a813469a..518fce663 100644--- a/deploy/remote/helm/switch/values.yaml+++ b/deploy/remote/helm/switch/values.yaml@@ -208,6 +208,26 @@ switchCore:# idempotent. Disable only if you run migrations out-of-band.migrations:preUpgradeJob: true+ # One-off migration steps for the move onto the Postgres message store. Both+ # read the homeserver, so they only work while Tuwunel is still deployed, and+ # both are off by default: they belong to one release, not to every release.+ #+ # 1. enable backfill with dryRun: true, upgrade, read the Job's log+ # 2. set dryRun: false, upgrade again+ # 3. enable reconcile, upgrade, confirm it exits clean+ # 4. set MESSAGE_TRANSPORT=postgres+ # 5. turn both back off+ #+ # Backfill is idempotent and its rows are numbered below the live sequence,+ # so it can be re-run and nobody is redelivered old history.+ backfill:+ enabled: false+ dryRun: true+ # Exit 0 when there is no history to walk. For an install with no rooms+ # yet, where a failed Job would be reporting an empty database as a fault.+ allowEmpty: false+ reconcile:+ enabled: falseresources:requests:memory: "512Mi"diff --git a/justfile b/justfileindex 9b3f537f3..2fa7cf126 100644--- a/justfile+++ b/justfile@@ -101,6 +101,24 @@ migrate:uv run --project core alembic -c core/alembic.ini upgrade head+# ── Check the recorded messages against the message bus ───────────────────────+# Messages are written to Postgres after the send is accepted, so a database+# problem leaves a row missing for a message that was really delivered. This+# walks each room's history and reports the difference. Exits non-zero on drift.+# Needs a real deployment — the question it answers cannot be asked of fakes.+# just reconcile-messages --room <id> --since <iso8601> --verbose+reconcile-messages *args:+ uv run --project core python -m switch_core.cli.reconcile {{ args }}++# ── Reconstruct room history from the bus into the message log ────────────────+# Rows exist only from when the recorder was deployed; everything older is on+# the homeserver and invisible to agents now that reads come from Postgres.+# This walks each room to its start and writes what is missing, numbered below+# the live log so nothing is redelivered. Safe to re-run. Start with --dry-run.+# just backfill-messages --dry-run --room <id>+backfill-messages *args:+ uv run --project core python -m switch_core.cli.backfill {{ args }}+# ── Generate a new alembic migration ──────────────────────────────────────────migration msg:uv run --project core alembic -c core/alembic.ini revision --autogenerate -m "{{ msg }}"