Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

feat(resources): per-principal reference type resolution and CRUD

raullopez-sandboxab4fecefada2
diff --git a/core/switch_core/authz.py b/core/switch_core/authz.py
index 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 testable
and 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 model
with 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.py
index 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.py
index 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, Literal
from sqlalchemy import select
from 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 ResourceLoadEntry
from 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 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
+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_store
self._documents = document_store
self._packages = package_store
self._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.py
index 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.py
index 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 DocumentStore
from switch_core.db.stores.external_user_store import ExternalUserStore
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_group_store import RoomGroupStore
from switch_core.db.stores.room_link_store import RoomLinkStore
from 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.py
index 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.py
index 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 DocumentStore
from switch_core.db.stores.external_user_store import ExternalUserStore
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
from switch_core.db.stores.room_role_store import RoomRoleStore
from switch_core.db.stores.room_store import RoomStore
@@ -145,6 +146,7 @@ class 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
@@ -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.py
new file mode 100644
index 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.py
index 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, 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
from switch_core.db.stores.room_store import RoomStore
from 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.py
index 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 DocumentStore
from switch_core.db.stores.external_user_store import ExternalUserStore
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
from switch_core.db.stores.room_role_store import RoomRoleStore
from 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.md
index 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 independent
read/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 is
always a **user** principal; an agent-initiated request resolves to the
agent'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 call
sites 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