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
feat(resources): per-principal reference type resolution and CRUD
raullopez-sandboxab4fecefada2
diff --git a/core/switch_core/authz.py b/core/switch_core/authz.pyindex 9de86f664..9c65903f8 100644--- a/core/switch_core/authz.py+++ b/core/switch_core/authz.py@@ -13,8 +13,9 @@ Model:- Owned entities carry a nullable owner plus independent `read_visibility`and `write_visibility` ("public" | "private").-The rule is uniform across References, Documents, Packages, and Rooms — the-only difference between them lives in their *default* visibility, not here.+The rule is uniform across References, ReferenceTypes, Documents, Packages, and+Rooms — the only difference between them lives in their *default* visibility,+not here.This module is deliberately pure (no DB, no I/O) so it is trivially testableand so a future relationship-based backend can replace `can` without touching@@ -47,8 +48,8 @@ class Principal:class Authorizable(Protocol):"""Structural interface for any entity `can` arbitrates over.- Satisfied by the Reference, Document, Package, and Room ORM models — no- base class required. Declared as read-only properties so that a model+ Satisfied by the Reference, ReferenceType, Document, Package, and Room ORM+ models — no base class required. Declared as read-only properties so a modelwith a non-nullable ``owner_id: str`` still satisfies ``str | None``(mutable Protocol attributes would be invariant)."""diff --git a/core/switch_core/bridges/agent/protocol/service.py b/core/switch_core/bridges/agent/protocol/service.pyindex b29d75e09..d079eb3a0 100644--- a/core/switch_core/bridges/agent/protocol/service.py+++ b/core/switch_core/bridges/agent/protocol/service.py@@ -2688,7 +2688,7 @@ class ProtocolService:owner (anonymous agents cannot own resources)."""async with self.session_factory() as session:- _agent, owner_id, _is_admin = await self._resolve_acting_identity(+ _agent, owner_id, is_admin = await self._resolve_acting_identity(session, agent_id)if owner_id is None:@@ -2698,6 +2698,7 @@ class ProtocolService:ref = await self.resource_service.create_reference(session,owner_id=owner_id,+ is_admin=is_admin,read_visibility=read_visibility,write_visibility=write_visibility,type=type,diff --git a/core/switch_core/bridges/resource/service.py b/core/switch_core/bridges/resource/service.pyindex cb51f6983..6f8bf676a 100644--- a/core/switch_core/bridges/resource/service.py+++ b/core/switch_core/bridges/resource/service.py@@ -1,24 +1,68 @@from __future__ import annotations-from typing import Any+import logging+import re+from dataclasses import dataclass+from typing import Any, Literalfrom sqlalchemy import selectfrom sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker-from switch_core.authz import Principal, can, require, validate_visibility_pair+from switch_core.authz import (+ Principal,+ can,+ can_manage,+ require,+ validate_visibility_pair,+)from switch_core.bridges.resource.events import ResourceLoadEntryfrom switch_core.bridges.resource.registry import (- serialize_used_types,+ BUILTIN_REFERENCE_TYPES,+ ReferenceTypeSpec,+ is_builtin_type,validate_reference_value,)-from switch_core.db.models import Document, Package, Reference, Room, RoomGroup+from switch_core.db.models import (+ Document,+ Package,+ Reference,+ ReferenceType,+ Room,+ RoomGroup,+)from 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 RoomLinkStore+logger = logging.getLogger(__name__)+ROOM_DOCUMENT_MAX_CONTENT_BYTES = 1_048_576+REFERENCE_TYPE_SLUG_PATTERN = re.compile(r"^[a-z][a-z0-9_]{1,62}$")+++@dataclass(frozen=True)+class ReferenceTypeView:+ """One entry of the resolution list — a type a principal may pick.++ Built-ins report ``owner_id=None``. Visibility is deliberately absent: the+ picker needs the owner label and the built-in marker, and nothing else.+ """++ spec: ReferenceTypeSpec+ owner_id: str | None+ is_builtin: bool+++@dataclass(frozen=True)+class ReferenceTypeRow:+ """One entry of the management list — a database row the principal manages."""++ row: ReferenceType+ shadowed_by_builtin: bool+class ResourceService:"""Business logic for References, Documents, and Packages.@@ -33,12 +77,14 @@ class ResourceService:self,*,reference_store: ReferenceStore,+ reference_type_store: ReferenceTypeStore,document_store: DocumentStore,package_store: PackageStore,room_link_store: RoomLinkStore,session_factory: async_sessionmaker[AsyncSession],) -> None:self._references = reference_store+ self._reference_types = reference_type_storeself._documents = document_storeself._packages = package_storeself._room_links = room_link_store@@ -68,6 +114,243 @@ class ResourceService:"created_by_agent_id": doc.created_by_agent_id,}+ # ── Reference types ───────────────────────────────────────────────────++ @staticmethod+ def _row_to_spec(row: ReferenceType) -> ReferenceTypeSpec:+ return ReferenceTypeSpec(+ type=row.type,+ display_name=row.display_name,+ instructions=row.instructions,+ value_hint=row.value_hint,+ )++ async def _resolve_specs(+ self, session: AsyncSession, slugs: set[str]+ ) -> dict[str, tuple[ReferenceTypeSpec, Literal["builtin", "user"]]]:+ """Resolve ``slugs`` to their specs, built-in winning any collision.++ Unresolvable slugs are simply absent from the result; the two public+ resolvers below differ in what they do about that. No visibility filter+ — see decision 3: a reference already in a room carries its type's+ metadata to every agent there.+ """+ resolved: dict[str, tuple[ReferenceTypeSpec, Literal["builtin", "user"]]] = {}+ for row in await self._reference_types.get_many(session, sorted(slugs)):+ resolved[row.type] = (self._row_to_spec(row), "user")+ for slug in slugs:+ builtin = BUILTIN_REFERENCE_TYPES.get(slug)+ if builtin is not None:+ resolved[slug] = (builtin, "builtin")+ return resolved++ async def list_reference_types_for_principal(+ self, session: AsyncSession, *, user_id: str | None, is_admin: bool+ ) -> list[ReferenceTypeView]:+ """The resolution list: every built-in plus every row the principal may+ read, one entry per slug, a built-in winning a collision."""+ rows = (+ await self._reference_types.list_all(session)+ if is_admin+ else await self._reference_types.list_for_user(session, user_id)+ )+ views: dict[str, ReferenceTypeView] = {+ row.type: ReferenceTypeView(+ spec=self._row_to_spec(row), owner_id=row.owner_id, is_builtin=False+ )+ for row in rows+ }+ for slug, spec in BUILTIN_REFERENCE_TYPES.items():+ views[slug] = ReferenceTypeView(spec=spec, owner_id=None, is_builtin=True)+ return [views[slug] for slug in sorted(views)]++ async def list_owned_reference_types(+ self, session: AsyncSession, *, user_id: str, is_admin: bool+ ) -> list[ReferenceTypeRow]:+ """The management list: database rows only, never built-ins.++ A principal manages the rows it owns; an admin manages every row, per+ ``can_manage``. A row shadowed by a built-in stays here, and stays+ editable and deletable, flagged rather than hidden.+ """+ rows = (+ await self._reference_types.list_all(session)+ if is_admin+ else await self._reference_types.list_for_user(session, user_id)+ )+ principal = Principal(user_id, is_admin)+ return [+ ReferenceTypeRow(row=row, shadowed_by_builtin=is_builtin_type(row.type))+ for row in sorted(rows, key=lambda r: r.type)+ if can_manage(principal, row.owner_id)+ ]++ async def resolve_display_names(+ self, session: AsyncSession, slugs: set[str]+ ) -> dict[str, str]:+ """Slug → display name, with unresolvable slugs omitted so the caller+ can map a miss to ``None``."""+ resolved = await self._resolve_specs(session, slugs)+ return {slug: spec.display_name for slug, (spec, _) in resolved.items()}++ async def resolve_types_for_payload(+ self, session: AsyncSession, slugs: set[str]+ ) -> dict[str, dict[str, Any]]:+ """Slug → agent-facing type entry, for the on-connect payload.++ An unresolvable slug is present and flagged ``missing`` rather than+ dropped: an agent holding a reference of that type must be told its+ instructions are absent instead of silently receiving none.+ """+ resolved = await self._resolve_specs(session, slugs)+ payload: dict[str, dict[str, Any]] = {}+ for slug in sorted(slugs):+ entry = resolved.get(slug)+ if entry is None:+ logger.error(+ "Reference type '%s' is not registered on this instance; "+ "references of that type are served without instructions",+ slug,+ )+ payload[slug] = {+ "type": slug,+ "display_name": slug,+ "instructions": (+ f"The reference type '{slug}' is not registered on this "+ "Switch instance, so no instructions are available for it. "+ "Say so rather than guessing at how to use the reference."+ ),+ "origin": "unknown",+ "missing": True,+ }+ continue+ spec, origin = entry+ payload[slug] = spec.to_public_dict(origin=origin)+ return payload++ async def resolve_type_for_principal(+ self, session: AsyncSession, type_: str, *, user_id: str | None, is_admin: bool+ ) -> ReferenceTypeSpec:+ """Resolve the type a principal is picking, raising if it cannot.++ A type the principal cannot read is *unknown*, not forbidden, and the+ error enumerates only the slugs the principal can already see —+ otherwise it is an oracle for other users' private type names.+ """+ views = await self.list_reference_types_for_principal(+ session, user_id=user_id, is_admin=is_admin+ )+ by_slug = {view.spec.type: view.spec for view in views}+ spec = by_slug.get(type_)+ if spec is None:+ raise ValueError(+ f"Unknown reference type '{type_}'. Known: {sorted(by_slug)}"+ )+ return spec++ async def create_reference_type(+ self,+ session: AsyncSession,+ *,+ owner_id: str,+ type: str,+ display_name: str,+ instructions: str,+ value_hint: str,+ read_visibility: str,+ write_visibility: str,+ ) -> ReferenceType:+ if REFERENCE_TYPE_SLUG_PATTERN.fullmatch(type) is None:+ raise ValueError(+ f"Invalid reference type '{type}': must match "+ "^[a-z][a-z0-9_]{1,62}$ (lowercase letters, digits and "+ "underscores, starting with a letter, 2-63 characters)"+ )+ if is_builtin_type(type):+ raise ValueError(f"'{type}' is a built-in reference type")+ validate_visibility_pair(read_visibility, write_visibility)+ reference_type = ReferenceType(+ type=type,+ owner_id=owner_id,+ read_visibility=read_visibility,+ write_visibility=write_visibility,+ display_name=display_name,+ instructions=instructions,+ value_hint=value_hint,+ )+ return await self._reference_types.create(session, reference_type)++ async def update_reference_type(+ self,+ session: AsyncSession,+ type_: str,+ *,+ user_id: str,+ is_admin: bool,+ display_name: str | None = None,+ instructions: str | None = None,+ value_hint: str | None = None,+ read_visibility: str | None = None,+ write_visibility: str | None = None,+ ) -> ReferenceType:+ reference_type = await self._reference_types.get(session, type_)+ if reference_type is None:+ raise ValueError(f"Reference type not found: {type_}")+ require(Principal(user_id, is_admin), "write", reference_type)+ validate_visibility_pair(+ read_visibility+ if read_visibility is not None+ else reference_type.read_visibility,+ write_visibility+ if write_visibility is not None+ else reference_type.write_visibility,+ )+ return await self._reference_types.update_fields(+ session,+ type_,+ display_name=display_name,+ instructions=instructions,+ value_hint=value_hint,+ read_visibility=read_visibility,+ write_visibility=write_visibility,+ )++ async def delete_reference_type(+ self,+ session: AsyncSession,+ type_: str,+ *,+ user_id: str,+ is_admin: bool,+ ) -> None:+ reference_type = await self._reference_types.get(session, type_)+ if reference_type is None:+ raise ValueError(f"Reference type not found: {type_}")+ require(Principal(user_id, is_admin), "delete", reference_type)+ in_use = await self._reference_types.count_references_of_type(session, type_)+ if in_use:+ raise ValueError(+ f"Reference type '{type_}' is used by {in_use} reference(s) "+ "and cannot be deleted"+ )+ await self._reference_types.delete(session, type_)++ async def log_builtin_shadowing(self, session: AsyncSession) -> None:+ """Report every stored type a built-in shadows.++ The built-in wins resolution, so such a row's references silently start+ serving different instructions — a semantic change that must be visible+ to an operator.+ """+ for row in await self._reference_types.list_all(session):+ if is_builtin_type(row.type):+ logger.error(+ "Reference type '%s' (owner %s) is shadowed by a built-in of "+ "the same slug; the built-in's instructions are served instead",+ row.type,+ row.owner_id,+ )+# ── On-connect / list helpers ─────────────────────────────────────────async def list_room_resources(@@ -116,7 +399,7 @@ class ResourceService:]return {- "reference_types": serialize_used_types(all_types),+ "reference_types": await self.resolve_types_for_payload(session, all_types),"references": [self._reference_to_payload(r) for r in refs],"documents": [self._document_metadata(d) for d in docs],"packages": package_payloads,@@ -158,6 +441,7 @@ class ResourceService:session: AsyncSession,*,owner_id: str,+ is_admin: bool,read_visibility: str,write_visibility: str,type: str,@@ -166,7 +450,10 @@ class ResourceService:instructions: str,value: dict[str, Any],) -> Reference:- normalised_value = validate_reference_value(type, value)+ await self.resolve_type_for_principal(+ session, type, user_id=owner_id, is_admin=is_admin+ )+ normalised_value = validate_reference_value(value)validate_visibility_pair(read_visibility, write_visibility)ref = Reference(owner_id=owner_id,@@ -224,7 +511,7 @@ class ResourceService:write_visibility if write_visibility is not None else ref.write_visibility,)normalised_value = (- validate_reference_value(ref.type, value) if value is not None else None+ validate_reference_value(value) if value is not None else None)return await self._references.update_fields(session,diff --git a/core/switch_core/gateway/references.py b/core/switch_core/gateway/references.pyindex a48ac7e1b..db44b90a6 100644--- a/core/switch_core/gateway/references.py+++ b/core/switch_core/gateway/references.py@@ -130,6 +130,7 @@ async def create_reference(ref = await resource_service.create_reference(session,owner_id=user.id,+ is_admin=user.role == "admin",read_visibility=req.read_visibility,write_visibility=req.write_visibility,type=req.type,diff --git a/core/switch_core/main.py b/core/switch_core/main.pyindex 93488daac..db33568c3 100644--- a/core/switch_core/main.py+++ b/core/switch_core/main.py@@ -75,6 +75,7 @@ from switch_core.db.stores.document_store import DocumentStorefrom switch_core.db.stores.external_user_store import ExternalUserStorefrom 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_group_store import RoomGroupStorefrom switch_core.db.stores.room_link_store import RoomLinkStorefrom switch_core.db.stores.room_role_store import RoomRoleStore@@ -203,6 +204,7 @@ async def run() -> None:user_store = UserStore()api_key_store = ApiKeyStore()reference_store = ReferenceStore()+ reference_type_store = ReferenceTypeStore()document_store = DocumentStore()package_store = PackageStore()room_link_store = RoomLinkStore()@@ -224,6 +226,7 @@ async def run() -> None:# ── Resource service ─────────────────────────────────────────────────────resource_service = ResourceService(reference_store=reference_store,+ reference_type_store=reference_type_store,document_store=document_store,package_store=package_store,room_link_store=room_link_store,diff --git a/core/switch_core/rooms_yaml.py b/core/switch_core/rooms_yaml.pyindex c11a4294d..09fc0a76d 100644--- a/core/switch_core/rooms_yaml.py+++ b/core/switch_core/rooms_yaml.py@@ -297,6 +297,7 @@ class RoomYamlService:ref = await self._resources.create_reference(session,owner_id=user_id,+ is_admin=is_admin,read_visibility=entry.read_visibility,write_visibility=entry.write_visibility,type=entry.type,diff --git a/core/tests/integration/conftest.py b/core/tests/integration/conftest.pyindex 34b031928..61e6b1c1e 100644--- a/core/tests/integration/conftest.py+++ b/core/tests/integration/conftest.py@@ -68,6 +68,7 @@ from switch_core.db.stores.document_store import DocumentStorefrom switch_core.db.stores.external_user_store import ExternalUserStorefrom 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_role_store import RoomRoleStorefrom switch_core.db.stores.room_store import RoomStore@@ -145,6 +146,7 @@ class SessionEnv:external_user_store: ExternalUserStoreapi_key_store: ApiKeyStorereference_store: ReferenceStore+ reference_type_store: ReferenceTypeStoredocument_store: DocumentStorepackage_store: PackageStoreroom_link_store: RoomLinkStore@@ -392,6 +394,7 @@ async def session_env(switch_stack: StackInfo) -> AsyncIterator[SessionEnv]:external_user_store=ExternalUserStore(),api_key_store=ApiKeyStore(),reference_store=ReferenceStore(),+ reference_type_store=ReferenceTypeStore(),document_store=DocumentStore(),package_store=PackageStore(),room_link_store=RoomLinkStore(),@@ -439,6 +442,7 @@ async def harness(session_env: SessionEnv) -> AsyncIterator[Harness]:resource_service = ResourceService(reference_store=session_env.reference_store,+ reference_type_store=session_env.reference_type_store,document_store=session_env.document_store,package_store=session_env.package_store,room_link_store=session_env.room_link_store,diff --git a/core/tests/switch_core/bridges/resource/test_reference_types_service.py b/core/tests/switch_core/bridges/resource/test_reference_types_service.pynew file mode 100644index 000000000..92e6995cf--- /dev/null+++ b/core/tests/switch_core/bridges/resource/test_reference_types_service.py@@ -0,0 +1,698 @@+from __future__ import annotations++import logging++import pytest+import pytest_asyncio+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker++from switch_core.bridges.resource.service import ResourceService+from switch_core.db.models import Reference, ReferenceType, Room, User+from switch_core.db.stores.document_store import DocumentStore+from switch_core.db.stores.package_store import PackageStore+from switch_core.db.stores.reference_store import ReferenceStore+from switch_core.db.stores.reference_type_store import ReferenceTypeStore+from switch_core.db.stores.room_link_store import RoomLinkStore++SERVICE_LOGGER = "switch_core.bridges.resource.service"+++def service(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(),+ session_factory=session_factory,+ )+++async def _make_user(session: AsyncSession, name: str) -> User:+ user = User(name=name, email=f"{name}@example.invalid", role="user")+ session.add(user)+ await session.flush()+ return user+++@pytest_asyncio.fixture+async def users(+ session_factory: async_sessionmaker[AsyncSession],+) -> dict[str, str]:+ """Two ordinary users and one admin, by role name → id."""+ async with session_factory() as session:+ alice = await _make_user(session, "alice")+ bob = await _make_user(session, "bob")+ root = User(name="root", email="[email protected]", role="admin")+ session.add(root)+ await session.flush()+ ids = {"alice": alice.id, "bob": bob.id, "admin": root.id}+ await session.commit()+ return ids+++async def _shadow_github(session: AsyncSession, owner_id: str) -> ReferenceType:+ """Write a row whose slug a built-in already owns.++ ``create_reference_type`` refuses this, so it can only arise the way+ decision 5 describes: a future release adding a built-in over a slug a user+ already holds. The store is the honest way to reach that state.+ """+ return await ReferenceTypeStore().create(+ session,+ ReferenceType(+ type="github",+ owner_id=owner_id,+ read_visibility="public",+ write_visibility="private",+ display_name="Not GitHub",+ instructions="Shadow instructions.",+ value_hint="Shadow hint.",+ ),+ )+++async def _make_room(session: AsyncSession, name: str) -> Room:+ room = Room(+ matrix_room_id=f"!{name}:example.invalid",+ name=name,+ description="",+ )+ session.add(room)+ await session.flush()+ return room+++class TestResolution:+ async def test_builtin_wins_a_slug_collision(+ self,+ service: ResourceService,+ session_factory: async_sessionmaker[AsyncSession],+ users: dict[str, str],+ ) -> None:+ async with session_factory() as session:+ await _shadow_github(session, users["alice"])+ await session.commit()++ async with session_factory() as session:+ payload = await service.resolve_types_for_payload(session, {"github"})+ assert payload["github"]["display_name"] == "GitHub"+ assert payload["github"]["origin"] == "builtin"+ assert "Shadow instructions." not in payload["github"]["instructions"]++ views = await service.list_reference_types_for_principal(+ session, user_id=users["alice"], is_admin=False+ )+ github = [v for v in views if v.spec.type == "github"]+ assert len(github) == 1+ assert github[0].is_builtin is True+ assert github[0].owner_id is None++ async def test_log_builtin_shadowing_reports_the_row(+ self,+ service: ResourceService,+ session_factory: async_sessionmaker[AsyncSession],+ users: dict[str, str],+ caplog: pytest.LogCaptureFixture,+ ) -> None:+ async with session_factory() as session:+ await _shadow_github(session, users["alice"])+ await session.commit()++ with caplog.at_level(logging.ERROR, logger=SERVICE_LOGGER):+ async with session_factory() as session:+ await service.log_builtin_shadowing(session)++ records = [r for r in caplog.records if r.levelno == logging.ERROR]+ assert len(records) == 1+ assert "github" in records[0].getMessage()+ assert users["alice"] in records[0].getMessage()++ async def test_shadowed_row_stays_manageable(+ self,+ service: ResourceService,+ session_factory: async_sessionmaker[AsyncSession],+ users: dict[str, str],+ ) -> None:+ async with session_factory() as session:+ await _shadow_github(session, users["alice"])+ await session.commit()++ async with session_factory() as session:+ owned = await service.list_owned_reference_types(+ session, user_id=users["alice"], is_admin=False+ )+ assert [(r.row.type, r.shadowed_by_builtin) for r in owned] == [+ ("github", True)+ ]++ updated = await service.update_reference_type(+ session,+ "github",+ user_id=users["alice"],+ is_admin=False,+ display_name="Renamed",+ )+ assert updated.display_name == "Renamed"++ await service.delete_reference_type(+ session, "github", user_id=users["alice"], is_admin=False+ )+ await session.commit()++ async with session_factory() as session:+ assert (+ await service.list_owned_reference_types(+ session, user_id=users["alice"], is_admin=False+ )+ == []+ )++ async def test_unreadable_type_is_unknown_and_leaks_no_slugs(+ self,+ service: ResourceService,+ session_factory: async_sessionmaker[AsyncSession],+ users: dict[str, str],+ ) -> None:+ async with session_factory() as session:+ await service.create_reference_type(+ session,+ owner_id=users["alice"],+ type="alice_private",+ display_name="Alice private",+ instructions="i",+ value_hint="h",+ read_visibility="private",+ write_visibility="private",+ )+ await service.create_reference_type(+ session,+ owner_id=users["bob"],+ type="bob_public",+ display_name="Bob public",+ instructions="i",+ value_hint="h",+ read_visibility="public",+ write_visibility="private",+ )+ await session.commit()++ async with session_factory() as session:+ with pytest.raises(ValueError) as excinfo:+ await service.resolve_type_for_principal(+ session, "alice_private", user_id=users["bob"], is_admin=False+ )+ message = str(excinfo.value)+ assert "Unknown reference type 'alice_private'" in message+ assert "bob_public" in message+ # The private slug appears once — named because the caller asked for it,+ # never as part of the enumeration of what exists.+ assert message.count("alice_private") == 1++ async def test_admin_resolves_another_users_private_type(+ self,+ service: ResourceService,+ session_factory: async_sessionmaker[AsyncSession],+ users: dict[str, str],+ ) -> None:+ async with session_factory() as session:+ await service.create_reference_type(+ session,+ owner_id=users["alice"],+ type="alice_private",+ display_name="Alice private",+ instructions="i",+ value_hint="h",+ read_visibility="private",+ write_visibility="private",+ )+ await session.commit()++ async with session_factory() as session:+ spec = await service.resolve_type_for_principal(+ session, "alice_private", user_id=users["admin"], is_admin=True+ )+ assert spec.display_name == "Alice private"++ async def test_ownerless_principal_sees_builtins_and_public_rows_only(+ self,+ service: ResourceService,+ session_factory: async_sessionmaker[AsyncSession],+ users: dict[str, str],+ ) -> None:+ async with session_factory() as session:+ await service.create_reference_type(+ session,+ owner_id=users["alice"],+ type="alice_private",+ display_name="Alice private",+ instructions="i",+ value_hint="h",+ read_visibility="private",+ write_visibility="private",+ )+ await service.create_reference_type(+ session,+ owner_id=users["alice"],+ type="alice_public",+ display_name="Alice public",+ instructions="i",+ value_hint="h",+ read_visibility="public",+ write_visibility="private",+ )+ await session.commit()++ async with session_factory() as session:+ views = await service.list_reference_types_for_principal(+ session, user_id=None, is_admin=False+ )+ slugs = {v.spec.type for v in views}+ assert "alice_public" in slugs+ assert "alice_private" not in slugs+ assert {"google_drive", "confluence", "github", "jira"} <= slugs+++class TestUnresolvableSlugs:+ async def test_resolve_display_names_omits_a_miss(+ self,+ service: ResourceService,+ session_factory: async_sessionmaker[AsyncSession],+ ) -> None:+ async with session_factory() as session:+ names = await service.resolve_display_names(+ session, {"jira", "never_registered"}+ )+ assert names == {"jira": "Jira"}++ async def test_resolve_types_for_payload_flags_a_miss_and_logs(+ self,+ service: ResourceService,+ session_factory: async_sessionmaker[AsyncSession],+ caplog: pytest.LogCaptureFixture,+ ) -> None:+ with caplog.at_level(logging.ERROR, logger=SERVICE_LOGGER):+ async with session_factory() as session:+ payload = await service.resolve_types_for_payload(+ session, {"jira", "never_registered"}+ )++ assert payload["jira"].get("missing") is None+ entry = payload["never_registered"]+ assert entry["missing"] is True+ assert entry["origin"] == "unknown"+ assert entry["display_name"] == "never_registered"+ assert "never_registered" in entry["instructions"]++ errors = [r for r in caplog.records if r.levelno == logging.ERROR]+ assert len(errors) == 1+ assert "never_registered" in errors[0].getMessage()++ async def test_room_payload_flags_an_unregistered_type(+ self,+ service: ResourceService,+ session_factory: async_sessionmaker[AsyncSession],+ users: dict[str, str],+ ) -> None:+ """A reference whose slug resolves to nothing is delivered flagged, not+ dropped: the schema permits the state (``references.type`` has no FK)."""+ references = ReferenceStore()+ async with session_factory() as session:+ room = await _make_room(session, "orphan-type")+ ref = await references.create(+ session,+ Reference(+ owner_id=users["alice"],+ read_visibility="private",+ write_visibility="private",+ type="never_registered",+ name="Orphan",+ description="",+ instructions="",+ value={"urls": ["https://example.invalid/x"]},+ ),+ )+ await references.attach_to_room(session, room.id, ref.id)+ await session.commit()+ room_id = room.id++ async with session_factory() as session:+ payload = await service.list_room_resources(session, room_id)+ assert payload["reference_types"]["never_registered"]["missing"] is True+++class TestPrivateTypeStillReachesAgents:+ async def test_room_payload_carries_a_private_types_instructions(+ self,+ service: ResourceService,+ session_factory: async_sessionmaker[AsyncSession],+ users: dict[str, str],+ ) -> None:+ """Decision 3: ``read_visibility`` gates who may *pick* and *enumerate* a+ type, never delivery of its metadata for a reference already attached to+ a room. The attachment is the grant. Withholding the instructions would+ ship an agent a reference it cannot act on while looking healthy — the+ silent-degradation tier CLAUDE.md forbids. Do not "fix" this into a+ visibility filter.+ """+ async with session_factory() as session:+ await service.create_reference_type(+ session,+ owner_id=users["alice"],+ type="alice_private",+ display_name="Alice Private Type",+ instructions="Fetch it with the internal tool.",+ value_hint="h",+ read_visibility="private",+ write_visibility="private",+ )+ room = await _make_room(session, "shared")+ ref = await service.create_reference(+ session,+ owner_id=users["alice"],+ is_admin=False,+ read_visibility="private",+ write_visibility="private",+ type="alice_private",+ name="Alice ref",+ description="",+ instructions="",+ value={"urls": ["https://example.invalid/doc"]},+ )+ await service.attach_reference_to_room(+ session, room.id, ref.id, user_id=users["alice"]+ )+ await session.commit()+ room_id = room.id++ async with session_factory() as session:+ payload = await service.list_room_resources(session, room_id)++ entry = payload["reference_types"]["alice_private"]+ assert entry["display_name"] == "Alice Private Type"+ assert entry["instructions"] == "Fetch it with the internal tool."+ assert entry["origin"] == "user"+ assert entry.get("missing") is None++ # And the type stays unpickable by anyone else.+ async with session_factory() as session:+ with pytest.raises(ValueError, match="Unknown reference type"):+ await service.resolve_type_for_principal(+ session, "alice_private", user_id=users["bob"], is_admin=False+ )+++class TestCreateReferenceType:+ async def test_non_admin_may_create_a_public_read_type(+ self,+ service: ResourceService,+ session_factory: async_sessionmaker[AsyncSession],+ users: dict[str, str],+ ) -> None:+ """Decision 4: any authenticated user may create a type with the full+ read/write visibility pair, exactly like a Reference. There is no admin+ gate on ``read_visibility="public"``; the only pair rule is the existing+ write-implies-read invariant in ``authz.validate_visibility_pair``.++ The mitigation for user-authored, agent-facing instructions is+ disclosure (owner and built-in marker travel on the picker payload), not+ restriction. An admin gate is the opt-in tightening named under Risks in+ the implementation plan — reversing this behaviour means changing this+ test, deliberately.+ """+ async with session_factory() as session:+ created = await service.create_reference_type(+ session,+ owner_id=users["alice"],+ type="notion",+ display_name="Notion",+ instructions="Open the linked Notion pages.",+ value_hint="Paste Notion page links.",+ read_visibility="public",+ write_visibility="private",+ )+ await session.commit()++ assert created.type == "notion"+ assert created.read_visibility == "public"+ assert created.owner_id == users["alice"]++ # The one pair rule that does apply, for the same non-admin principal.+ async with session_factory() as session:+ with pytest.raises(ValueError, match="write_visibility=public"):+ await service.create_reference_type(+ session,+ owner_id=users["alice"],+ type="linear",+ display_name="Linear",+ instructions="i",+ value_hint="h",+ read_visibility="private",+ write_visibility="public",+ )++ async def test_builtin_slug_is_refused(+ self,+ service: ResourceService,+ session_factory: async_sessionmaker[AsyncSession],+ users: dict[str, str],+ ) -> None:+ async with session_factory() as session:+ with pytest.raises(ValueError, match="built-in reference type"):+ await service.create_reference_type(+ session,+ owner_id=users["alice"],+ type="jira",+ display_name="My Jira",+ instructions="i",+ value_hint="h",+ read_visibility="private",+ write_visibility="private",+ )++ @pytest.mark.parametrize(+ "slug",+ ["Notion", "n", "9lives", "my-type", "my type", "my_type!", "", "a" * 64],+ )+ async def test_invalid_slug_is_rejected_not_normalised(+ self,+ service: ResourceService,+ session_factory: async_sessionmaker[AsyncSession],+ users: dict[str, str],+ slug: str,+ ) -> None:+ async with session_factory() as session:+ with pytest.raises(ValueError, match="Invalid reference type"):+ await service.create_reference_type(+ session,+ owner_id=users["alice"],+ type=slug,+ display_name="X",+ instructions="i",+ value_hint="h",+ read_visibility="private",+ write_visibility="private",+ )++ async def test_duplicate_slug_is_refused(+ self,+ service: ResourceService,+ session_factory: async_sessionmaker[AsyncSession],+ users: dict[str, str],+ ) -> None:+ async with session_factory() as session:+ await service.create_reference_type(+ session,+ owner_id=users["alice"],+ type="notion",+ display_name="Notion",+ instructions="i",+ value_hint="h",+ read_visibility="public",+ write_visibility="private",+ )+ await session.commit()++ async with session_factory() as session:+ with pytest.raises(ValueError, match="already exists"):+ await service.create_reference_type(+ session,+ owner_id=users["bob"],+ type="notion",+ display_name="Bob's Notion",+ instructions="i",+ value_hint="h",+ read_visibility="private",+ write_visibility="private",+ )+++class TestUpdateAndDeleteReferenceType:+ async def test_non_owner_cannot_update_or_delete(+ self,+ service: ResourceService,+ session_factory: async_sessionmaker[AsyncSession],+ users: dict[str, str],+ ) -> None:+ async with session_factory() as session:+ await service.create_reference_type(+ session,+ owner_id=users["alice"],+ type="notion",+ display_name="Notion",+ instructions="i",+ value_hint="h",+ read_visibility="public",+ write_visibility="private",+ )+ await session.commit()++ async with session_factory() as session:+ with pytest.raises(PermissionError):+ await service.update_reference_type(+ session,+ "notion",+ user_id=users["bob"],+ is_admin=False,+ display_name="Hijacked",+ )+ with pytest.raises(PermissionError):+ await service.delete_reference_type(+ session, "notion", user_id=users["bob"], is_admin=False+ )++ async def test_update_rejects_a_writable_but_unreadable_result(+ self,+ service: ResourceService,+ session_factory: async_sessionmaker[AsyncSession],+ users: dict[str, str],+ ) -> None:+ async with session_factory() as session:+ await service.create_reference_type(+ session,+ owner_id=users["alice"],+ type="notion",+ display_name="Notion",+ instructions="i",+ value_hint="h",+ read_visibility="public",+ write_visibility="public",+ )+ await session.commit()++ async with session_factory() as session:+ with pytest.raises(ValueError, match="write_visibility=public"):+ await service.update_reference_type(+ session,+ "notion",+ user_id=users["alice"],+ is_admin=False,+ read_visibility="private",+ )++ async def test_delete_is_refused_while_references_exist(+ self,+ service: ResourceService,+ session_factory: async_sessionmaker[AsyncSession],+ users: dict[str, str],+ ) -> None:+ async with session_factory() as session:+ await service.create_reference_type(+ session,+ owner_id=users["alice"],+ type="notion",+ display_name="Notion",+ instructions="i",+ value_hint="h",+ read_visibility="private",+ write_visibility="private",+ )+ await service.create_reference(+ session,+ owner_id=users["alice"],+ is_admin=False,+ read_visibility="private",+ write_visibility="private",+ type="notion",+ name="A page",+ description="",+ instructions="",+ value={"urls": ["https://example.invalid/page"]},+ )+ await session.commit()++ async with session_factory() as session:+ with pytest.raises(ValueError, match="used by 1 reference"):+ await service.delete_reference_type(+ session, "notion", user_id=users["alice"], is_admin=False+ )++ async def test_missing_type_raises(+ self,+ service: ResourceService,+ session_factory: async_sessionmaker[AsyncSession],+ users: dict[str, str],+ ) -> None:+ async with session_factory() as session:+ with pytest.raises(ValueError, match="Reference type not found"):+ await service.delete_reference_type(+ session, "never_registered", user_id=users["alice"], is_admin=False+ )+++class TestCreateReferenceResolvesItsType:+ async def test_unknown_type_is_refused(+ self,+ service: ResourceService,+ session_factory: async_sessionmaker[AsyncSession],+ users: dict[str, str],+ ) -> None:+ async with session_factory() as session:+ with pytest.raises(ValueError, match="Unknown reference type"):+ await service.create_reference(+ session,+ owner_id=users["alice"],+ is_admin=False,+ read_visibility="private",+ write_visibility="private",+ type="never_registered",+ name="X",+ description="",+ instructions="",+ value={"urls": ["https://example.invalid/x"]},+ )++ async def test_another_users_private_type_is_refused(+ self,+ service: ResourceService,+ session_factory: async_sessionmaker[AsyncSession],+ users: dict[str, str],+ ) -> None:+ async with session_factory() as session:+ await service.create_reference_type(+ session,+ owner_id=users["alice"],+ type="alice_private",+ display_name="Alice private",+ instructions="i",+ value_hint="h",+ read_visibility="private",+ write_visibility="private",+ )+ await session.commit()++ async with session_factory() as session:+ with pytest.raises(ValueError, match="Unknown reference type"):+ await service.create_reference(+ session,+ owner_id=users["bob"],+ is_admin=False,+ read_visibility="private",+ write_visibility="private",+ type="alice_private",+ name="X",+ description="",+ instructions="",+ value={"urls": ["https://example.invalid/x"]},+ )diff --git a/core/tests/switch_core/gateway/test_room_write_authz.py b/core/tests/switch_core/gateway/test_room_write_authz.pyindex 5710efbbe..1b352078d 100644--- a/core/tests/switch_core/gateway/test_room_write_authz.py+++ b/core/tests/switch_core/gateway/test_room_write_authz.py@@ -19,6 +19,7 @@ from switch_core.db.models import Reference, Room, Userfrom 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@@ -35,6 +36,7 @@ def _resource_service() -> 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/test_rooms_yaml.py b/core/tests/switch_core/test_rooms_yaml.pyindex c6827c0fb..eb1a15215 100644--- a/core/tests/switch_core/test_rooms_yaml.py+++ b/core/tests/switch_core/test_rooms_yaml.py@@ -37,6 +37,7 @@ from switch_core.db.stores.document_store import DocumentStorefrom switch_core.db.stores.external_user_store import ExternalUserStorefrom 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_role_store import RoomRoleStorefrom switch_core.db.stores.room_store import RoomStore@@ -141,6 +142,7 @@ async def env(session_factory: async_sessionmaker[AsyncSession]):"""Seed a user + two agents, and wire up the YAML service."""resource_service = ResourceService(reference_store=ReferenceStore(),+ reference_type_store=ReferenceTypeStore(),document_store=DocumentStore(),package_store=PackageStore(),room_link_store=RoomLinkStore(),@@ -326,6 +328,7 @@ async def test_provision_attach_reference_by_name(env):ref = await env["resource_service"].create_reference(session,owner_id=env["user_id"],+ is_admin=False,read_visibility="private",write_visibility="private",type="confluence",@@ -373,6 +376,7 @@ async def test_provision_ambiguous_reference_name_fails(env):await env["resource_service"].create_reference(session,owner_id=env["user_id"],+ is_admin=False,read_visibility="private",write_visibility="private",type="github",diff --git a/docs/old/ARCHITECTURE.md b/docs/old/ARCHITECTURE.mdindex 420a6a441..a92454067 100644--- a/docs/old/ARCHITECTURE.md+++ b/docs/old/ARCHITECTURE.md@@ -134,6 +134,10 @@ The relational schema is defined in- **Reference** / **Document** / **Package** — the attachable resource library(external pointers, internal docs, and bundles), each with independentread/write visibility.+- **ReferenceType** — a user-defined external reference type (slug, display+ name, agent-facing instructions, value hint) with its own read/write+ visibility. Four built-in types (Google Drive, Confluence, GitHub, Jira) ship+ in code rather than as rows and win any slug collision.- **CollaborationBridge** — configured external chat bridges.- **ServerConnector** — a Switch-hosted connector driving an external agent host(e.g. OpenCode) from the server, rather than the agent connecting in.@@ -358,10 +362,10 @@ Auth-bypass path prefixes for the Bearer middleware are enumerated in[`core/switch_core/authz.py`](../core/switch_core/authz.py). The subject isalways a **user** principal; an agent-initiated request resolves to theagent's owner and inherits exactly that owner's permissions. `role == "admin"`- is a global bypass. Owned entities (Rooms, References, Documents, Packages)- carry independent `read_visibility` and `write_visibility` (`public` /- `private`); the rule is uniform across them and only their *default*- visibility differs. `authz` has no I/O, so it is trivially testable and call+ is a global bypass. Owned entities (Rooms, References, ReferenceTypes,+ Documents, Packages) carry independent `read_visibility` and+ `write_visibility` (`public` / `private`); the rule is uniform across them and+ only their *default* visibility differs. `authz` has no I/O, so it is trivially testable and callsites route through it (`require(...)`).- **Room scoping** — an agent only receives events for, and can only act in,rooms it is a member of. Cross-room resource access is validated server-side