polyc-query 2026.9.0

//! The catalog-scope selector for a query session.
//!
//! Mint a session, then filter server-side: catalog scoping (not row
//! rewriting) registers only the `CatalogProvider`/`SchemaProvider` covering
//! the partitions a session's participation set already authorizes.
//! [`QueryScope`] is that
//! selector — the value a caller passes to
//! [`crate::engine::QueryEngine::build`] to say which partitions a session's
//! catalog may register; building and holding the `SessionContext` itself is
//! [`QueryEngine`](crate::engine::QueryEngine)'s job, not this module's.

/// Which partitions a query session's catalog may register.
///
/// Sealed: [`crate::authority::QueryAuthority::scope_for`]
/// is the only place a [`QueryScope`] value is derived, from an already-verified
/// [`crate::authority::Principal`] — never a caller-supplied value from outside
/// this crate.
/// `Debug` reports the shape and the conversation count. A conversation id
/// names a real person's conversation, so the ids never reach a log line
/// through this type.
#[derive(Clone, PartialEq, Eq)]
pub(crate) enum QueryScope {
    /// A maintainer/operator session — fleet-wide, gated on
    /// `Permissions.admin`.
    Fleet,
    /// An end-user or conversation-scoped session, bounded to the given
    /// `conv-{id}` partitions — sourced from `PersonaStore::participations`,
    /// never a client-supplied predicate.
    Conversations(Vec<String>),
}

impl std::fmt::Debug for QueryScope {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Fleet => formatter.write_str("Fleet"),
            Self::Conversations(conversations) => formatter
                .debug_struct("Conversations")
                .field("count", &conversations.len())
                .finish(),
        }
    }
}