Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

57.1 KB
Raw Blame
#[cfg(feature = "ports")]
pub(crate) mod contact_listing;
pub mod grouping;
/// Numeric property and timestamp sort positions.
pub mod sort;
pub use sort::{DynamicSort, DynamicSortValue};

#[cfg(feature = "ports")]
mod exclusions;

#[cfg(all(test, feature = "ports"))]
mod test;

use crm::domain::auth::CrmTeamReceipt;
use crm::domain::companies_repo::{CrmCompanyListSort, CrmCompanySoupCursor};
use email::domain::models::PreviewView;
use entity_access::domain::models::MemberTeamRole;
use foreign_entity::domain::models::SourceId;
use frecency::domain::models::{AggregateFrecency, FrecencyQueryErr};
use github_pull_requests::domain::models::GithubPullRequestError;
use item_filters::{
    EntityFilters,
    ast::{EntityFilterAst, ExpandErr},
};
use macro_user_id::user_id::MacroUserIdStr;
use model_entity::{Entity, EntityType};
use models_grouping::GroupingConfig;
use models_pagination::{
    CursorWithValAndFilter, Frecency, NotifiedAt, Query, SimpleSortMethod, TouchedByMe,
};
use models_soup::SoupProperty;
use models_soup::item::SoupItem;
use non_empty::IsEmpty;
use serde::{Deserialize, Serialize};
use thiserror::Error;
use uuid::Uuid;

// Only the service's sub-request builders below use these.
#[cfg(feature = "ports")]
use {
    call::domain::models::GetCallRecordsRequest,
    channels::domain::models::{GetChannelsRequest, GetThreadReplyRowsRequest},
    email::domain::models::GetEmailsRequest,
    entity_access::domain::models::EntityAccessReceipt,
    filter_ast::Expr,
    foreign_entity::domain::ports::ForeignEntityListQuery,
    item_filters::ast::{
        LiteralTree,
        calendar_event::CalendarEventLiteral,
        call::CallLiteral,
        crm_company::CrmCompanyLiteral,
        email::EmailLiteral,
        github_pull_request::GithubPullRequestLiteral,
        properties::{
            PropertiesLiteral, PropertyEntityType, properties_filter_can_apply_to,
            properties_filter_matches_propertyless,
        },
    },
    models_pagination::Cursor,
    recursion::CollapsibleExt,
    std::sync::Arc,
};

/// Direction the merged Soup page is ordered in.
///
/// Deliberately Soup's own type rather than one borrowed from the paginator:
/// `Paginator` already exposes `sort_asc`/`sort_desc`, so this only has to name
/// the choice, and doing it here keeps the shared pagination crate untouched.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum SoupSortDirection {
    /// Smallest sort value first — oldest, or soonest for a future timestamp.
    Asc,
    /// Largest sort value first.
    #[default]
    Desc,
}

/// Controls whether soup items should include expanded nested data.
#[derive(Debug, Clone, Copy)]
pub enum SoupType {
    /// Return fully expanded soup items.
    Expanded,
    /// Return compact soup items without expanded nested data.
    UnExpanded,
}

/// the parameters required for a [SimpleSortMethod]
#[cfg(feature = "ports")]
#[cfg_attr(
    not(any(feature = "outbound", test)),
    expect(
        dead_code,
        reason = "only the outbound Postgres repository and tests read it"
    )
)]
#[derive(Debug, Clone)]
pub struct SimpleSortRequest<'a> {
    /// the limit of the number of items to return
    pub(crate) limit: u16,
    /// the [Query] the client passes (if any)
    pub(crate) cursor: SimpleSortQuery,
    /// the id of the user
    pub(crate) user_id: MacroUserIdStr<'a>,
}

pub use grouping::query::GroupedSortRequest;

#[cfg(feature = "ports")]
#[cfg_attr(
    not(any(feature = "outbound", test)),
    expect(
        dead_code,
        reason = "only the outbound Postgres repository and tests read it"
    )
)]
#[derive(Debug, Clone)]
pub(crate) enum SimpleSortQuery {
    /// we dont have anything to filter out
    NoFilter(Query<Uuid, SimpleSortMethod, ()>),
    /// we filter out items that DO have a [Frecency] record
    FilterFrecency(Query<Uuid, SimpleSortMethod, Frecency>),
    /// we filter out items based on the input [EntityFilterAst]
    ItemsFilter(Query<Uuid, SimpleSortMethod, EntityFilterAst>),
    /// we filter out items based on the input [EntityFilterAst] IN ADDITION to ANY items that DO have a [Frecency] score
    ItemsAndFrecencyFilter(Query<Uuid, SimpleSortMethod, (Frecency, EntityFilterAst)>),
    /// Property sorting through the same dynamic source query.
    Property(Query<Uuid, DynamicSort, EntityFilterAst>),
}

#[cfg(feature = "ports")]
impl SimpleSortQuery {
    pub(crate) fn from_entity_cursor(
        cursor: Query<Uuid, SimpleSortMethod, Option<EntityFilterAst>>,
    ) -> Self {
        match cursor {
            Query::Sort(s, Some(f)) => SimpleSortQuery::ItemsFilter(Query::Sort(s, f)),
            Query::Sort(s, None) => SimpleSortQuery::NoFilter(Query::Sort(s, ())),
            Query::Cursor(Cursor {
                id,
                limit,
                val,
                filter: Some(filter),
            }) => SimpleSortQuery::ItemsFilter(Query::Cursor(Cursor {
                id,
                limit,
                val,
                filter,
            })),
            Query::Cursor(Cursor {
                id,
                limit,
                val,
                filter: None,
            }) => SimpleSortQuery::NoFilter(Query::Cursor(Cursor {
                id,
                limit,
                val,
                filter: (),
            })),
        }
    }
}

#[cfg(any(feature = "outbound", all(test, feature = "ports")))]
impl SimpleSortQuery {
    pub(crate) fn sort_method(&self) -> &SimpleSortMethod {
        match self {
            SimpleSortQuery::NoFilter(query) => query.sort_method(),
            SimpleSortQuery::FilterFrecency(query) => query.sort_method(),
            SimpleSortQuery::ItemsFilter(query) => query.sort_method(),
            SimpleSortQuery::ItemsAndFrecencyFilter(query) => query.sort_method(),
            SimpleSortQuery::Property(_) => &SimpleSortMethod::UpdatedAt,
        }
    }
}

/// Parameters for fetching soup items by an explicit ordered entity list.
#[derive(Debug, Clone)]
pub struct AdvancedSortParams<'a> {
    /// Entities to fetch and preserve in the requested order.
    pub entities: &'a [Entity<'a>],
    /// User whose accessible soup items should be fetched.
    pub user_id: MacroUserIdStr<'a>,
}

/// Cursor or initial-sort query for a soup request.
#[derive(Debug)]
pub enum SoupQuery<T> {
    /// Query sorted by a simple timestamp-based method.
    Simple(SimpleQueryInner<T>),
    /// Query sorted by frecency.
    Frecency(FrecencyQueryInner<T>),
    /// Query filtered and sorted by the user's own latest mutation per
    /// entity (the activity log's touched-by-me surface).
    Touched(TouchedQueryInner<T>),
    /// Query filtered and sorted by the user's latest notification per
    /// entity (the inbox's notified-at surface).
    Notified(NotifiedQueryInner<T>),
    /// Numeric property ordering through the dynamic SQL query.
    Property(Query<Uuid, DynamicSort, T>),
}

impl<T> SoupQuery<T> {
    pub(crate) fn map<F, U>(self, f: F) -> SoupQuery<U>
    where
        F: FnOnce(T) -> U,
    {
        match self {
            SoupQuery::Simple(SimpleQueryInner(i)) => {
                SoupQuery::Simple(SimpleQueryInner(i.map_filter(f)))
            }
            SoupQuery::Frecency(FrecencyQueryInner(i)) => {
                SoupQuery::Frecency(FrecencyQueryInner(i.map_filter(f)))
            }
            SoupQuery::Touched(TouchedQueryInner(i)) => {
                SoupQuery::Touched(TouchedQueryInner(i.map_filter(f)))
            }
            SoupQuery::Notified(NotifiedQueryInner(i)) => {
                SoupQuery::Notified(NotifiedQueryInner(i.map_filter(f)))
            }
            SoupQuery::Property(query) => SoupQuery::Property(query.map_filter(f)),
        }
    }
}

/// the inner private type for [SoupQuery::Simple]
#[derive(Debug)]
pub struct SimpleQueryInner<T>(pub(crate) Query<Uuid, SimpleSortMethod, T>);

/// the inner private type for [SoupQuery::Frecency]
#[derive(Debug)]
pub struct FrecencyQueryInner<T>(pub(crate) Query<Uuid, Frecency, T>);

/// the inner private type for [SoupQuery::Touched]
///
/// The id is a [String] rather than a [Uuid]: touched cursors key into the
/// activity log's TEXT `entity_id` column, and the raw string must survive
/// the cursor round-trip byte-for-byte (see
/// [`TouchedPagePosition::entity_id`]).
#[derive(Debug)]
pub struct TouchedQueryInner<T>(pub(crate) Query<String, TouchedByMe, T>);

/// the inner private type for [SoupQuery::Notified]
///
/// The id is a [String] for the same reason as [`TouchedQueryInner`]: the
/// keyset compares it byte-for-byte against `notification.event_item_id`,
/// an unconstrained TEXT column.
#[derive(Debug)]
pub struct NotifiedQueryInner<T>(pub(crate) Query<String, NotifiedAt, T>);

impl<T> SoupQuery<T> {
    /// create a new instance of a [SimpleSortMethod] with [T] this is used to
    /// construct the initial page request. To paginate an existing cursor see [Self::new_cursor_simple]
    pub fn new_sort_simple(method: SimpleSortMethod, filters: T) -> Self {
        SoupQuery::Simple(SimpleQueryInner(models_pagination::Query::Sort(
            method, filters,
        )))
    }

    /// create a new instance of a [Frecency] with [T] this is used to
    /// construct the initial page request. To paginate an existing cursor see [Self::new_cursor_frecency]
    pub fn new_sort_frecency(method: Frecency, filters: T) -> Self {
        SoupQuery::Frecency(FrecencyQueryInner(models_pagination::Query::Sort(
            method, filters,
        )))
    }

    /// create a new instance of a [SimpleSortMethod] with an existing cursor on [T].
    /// This is used to continue paginating on an existing cursor.
    /// To create a new initial page see [Self::new_sort_simple]
    pub fn new_cursor_simple(cursor: CursorWithValAndFilter<Uuid, SimpleSortMethod, T>) -> Self {
        SoupQuery::Simple(SimpleQueryInner(models_pagination::Query::Cursor(cursor)))
    }

    /// create a new instance of a [Frecency] with an existing cursor on [T].
    /// This is used to continue paginating on an existing cursor.
    /// To create a new initial page see [Self::new_sort_simple]
    pub fn new_cursor_frecency(cursor: CursorWithValAndFilter<Uuid, Frecency, T>) -> Self {
        SoupQuery::Frecency(FrecencyQueryInner(models_pagination::Query::Cursor(cursor)))
    }

    /// create a new instance of a [TouchedByMe] query with [T]. This is used
    /// to construct the initial page request. To paginate an existing cursor
    /// see [Self::new_cursor_touched]
    pub fn new_sort_touched(filters: T) -> Self {
        SoupQuery::Touched(TouchedQueryInner(models_pagination::Query::Sort(
            TouchedByMe,
            filters,
        )))
    }

    /// create a new instance of a [TouchedByMe] query with an existing cursor
    /// on [T]. This is used to continue paginating on an existing cursor.
    /// To create a new initial page see [Self::new_sort_touched]
    pub fn new_cursor_touched(cursor: CursorWithValAndFilter<String, TouchedByMe, T>) -> Self {
        SoupQuery::Touched(TouchedQueryInner(models_pagination::Query::Cursor(cursor)))
    }

    /// create a new instance of a [NotifiedAt] query with [T]. This is used
    /// to construct the initial page request. To paginate an existing cursor
    /// see [Self::new_cursor_notified]
    pub fn new_sort_notified(filters: T) -> Self {
        SoupQuery::Notified(NotifiedQueryInner(models_pagination::Query::Sort(
            NotifiedAt, filters,
        )))
    }

    /// create a new instance of a [NotifiedAt] query with an existing cursor
    /// on [T]. This is used to continue paginating on an existing cursor.
    /// To create a new initial page see [Self::new_sort_notified]
    pub fn new_cursor_notified(cursor: CursorWithValAndFilter<String, NotifiedAt, T>) -> Self {
        SoupQuery::Notified(NotifiedQueryInner(models_pagination::Query::Cursor(cursor)))
    }

    /// Returns the filter payload embedded in this query.
    pub fn filter(&self) -> &T {
        match self {
            SoupQuery::Simple(SimpleQueryInner(query)) => query.filter(),
            SoupQuery::Frecency(FrecencyQueryInner(query)) => query.filter(),
            SoupQuery::Touched(TouchedQueryInner(query)) => query.filter(),
            SoupQuery::Notified(NotifiedQueryInner(query)) => query.filter(),
            SoupQuery::Property(query) => query.filter(),
        }
    }
}

impl SoupQuery<EntityFilters> {
    /// Converts high-level entity filters into an AST-backed soup query.
    pub fn into_ast(self) -> Result<SoupQuery<Option<EntityFilterAst>>, ExpandErr> {
        match self {
            SoupQuery::Simple(SimpleQueryInner(query)) => Ok(SoupQuery::Simple(SimpleQueryInner(
                query.try_map_filter(EntityFilterAst::new_from_filters)?,
            ))),
            SoupQuery::Frecency(FrecencyQueryInner(query)) => Ok(SoupQuery::Frecency(
                FrecencyQueryInner(query.try_map_filter(EntityFilterAst::new_from_filters)?),
            )),
            SoupQuery::Touched(TouchedQueryInner(query)) => Ok(SoupQuery::Touched(
                TouchedQueryInner(query.try_map_filter(EntityFilterAst::new_from_filters)?),
            )),
            SoupQuery::Notified(NotifiedQueryInner(query)) => Ok(SoupQuery::Notified(
                NotifiedQueryInner(query.try_map_filter(EntityFilterAst::new_from_filters)?),
            )),
            SoupQuery::Property(query) => Ok(SoupQuery::Property(
                query.try_map_filter(EntityFilterAst::new_from_filters)?,
            )),
        }
    }
}

/// Request to fetch a page of soup items for a user.
#[derive(Debug)]
pub struct SoupRequest<T> {
    /// Whether to return expanded or unexpanded soup items.
    pub soup_type: SoupType,
    /// Maximum number of items to return.
    pub limit: u16,
    /// Initial query or pagination cursor to execute.
    pub cursor: SoupQuery<T>,
    /// Direction the merged page is ordered in. Defaults to descending, which
    /// is the default feed ordering.
    ///
    /// One choice per request: the paginator sorts the whole merged page, so
    /// this cannot differ per entity type within a single feed. It is a
    /// sibling of the cursor rather than part of it because clients re-send
    /// the request params on every page, which keeps the cursor format alone.
    ///
    /// Only the [`SoupQuery::Simple`] branch honours this. Frecency pages come
    /// back ordered by relevance score and never have the merged sort applied,
    /// so there is no ascending frecency order to produce — the REST adapter
    /// rejects that combination rather than letting it read as supported, and
    /// the GraphQL adapter cannot express frecency at all.
    pub sort_direction: SoupSortDirection,
    /// User whose soup should be queried.
    pub user: MacroUserIdStr<'static>,
    /// Email preview view used when hydrating email soup items.
    pub email_preview_view: PreviewView,
    /// Every inbox the caller can read (own + delegated via macro_user_links).
    /// Empty when the caller has no inboxes — `build_email_request` returns
    /// `None` so the email branch is skipped, unless the request is CRM-scoped.
    pub link_ids: Vec<Uuid>,
}

/// A filter input that can be converted without constructing a query.
pub trait IntoSoupFilterAst {
    /// Convert filters into the authoritative entity AST.
    fn into_filter_ast(self) -> Result<Option<EntityFilterAst>, ExpandErr>;
}

impl IntoSoupFilterAst for EntityFilters {
    fn into_filter_ast(self) -> Result<Option<EntityFilterAst>, ExpandErr> {
        EntityFilterAst::new_from_filters(self)
    }
}

impl IntoSoupFilterAst for EntityFilterAst {
    fn into_filter_ast(self) -> Result<Option<EntityFilterAst>, ExpandErr> {
        Ok(if self.is_empty() { None } else { Some(self) })
    }
}

/// trait which defines a type which can be fallibly converted into a SoupRequest with ast
pub trait IntoSoupReqAst {
    /// perform the conversion
    fn into_ast(self) -> Result<SoupRequest<Option<EntityFilterAst>>, ExpandErr>;
}

impl IntoSoupReqAst for SoupRequest<EntityFilters> {
    fn into_ast(self) -> Result<SoupRequest<Option<EntityFilterAst>>, ExpandErr> {
        let SoupRequest {
            soup_type,
            limit,
            cursor,
            sort_direction,
            user,
            email_preview_view,
            link_ids,
        } = self;

        Ok(SoupRequest {
            soup_type,
            limit,
            cursor: cursor.into_ast()?,
            sort_direction,
            user,
            email_preview_view,
            link_ids,
        })
    }
}

impl IntoSoupReqAst for SoupRequest<EntityFilterAst> {
    fn into_ast(self) -> Result<SoupRequest<Option<EntityFilterAst>>, ExpandErr> {
        let SoupRequest {
            soup_type,
            limit,
            cursor,
            sort_direction,
            user,
            email_preview_view,
            link_ids,
        } = self;

        Ok(SoupRequest {
            soup_type,
            limit,
            cursor: cursor.map(|f| if f.is_empty() { None } else { Some(f) }),
            sort_direction,
            user,
            email_preview_view,
            link_ids,
        })
    }
}

#[cfg(feature = "ports")]
impl<T> SoupRequest<T> {
    /// returns a reference to the filters to pass to the paginator
    /// this is used to prevent passing back the full ast on each server request
    pub(crate) fn filters(&self) -> &T {
        self.cursor.filter()
    }
}

#[cfg(feature = "ports")]
impl SoupRequest<Option<EntityFilterAst>> {
    /// take the parts of the [SoupRequest] that are only relevant to email
    /// and move them into a [GetEmailsRequest] if it is possible to create one.
    ///
    /// `team_receipt` is forwarded onto the email request so the query
    /// layer can verify and use it when the email filter carries a CRM
    /// scope tag (`EntityFilterAst::email_filter::crm_scope`).
    pub(crate) fn build_email_request(
        &self,
        team_receipt: Option<EntityAccessReceipt<MemberTeamRole>>,
    ) -> Option<GetEmailsRequest> {
        let entity_ast = self.entity_ast();
        let crm_scope = entity_ast.and_then(|a| a.email_filter.crm_scope.clone());

        // A CRM scope reads teammates' threads, which email authorizes against
        // the scope, so a viewer without a mailbox of their own still sees them.
        if self.link_ids.is_empty() && crm_scope.is_none() {
            return None;
        }
        // CRM-scoped requests must still reach email's authorization precheck,
        // even when their id filter cannot match any threads.
        if crm_scope.is_none() && exclusions::email(entity_ast) {
            return None;
        }

        // A properties filter that cannot match threads makes the email
        // branch empty, so the sub-request is skipped. Otherwise it is ANDed
        // into the email tree so the query returns exactly matching threads.
        let properties_filter = entity_ast.and_then(|a| a.properties_filter.as_deref());
        if let Some(propf) = properties_filter
            && !properties_filter_can_apply_to(propf, &[PropertyEntityType::Thread])
        {
            return None;
        }

        Some(GetEmailsRequest {
            view: self.email_preview_view.clone(),
            link_ids: self.link_ids.clone(),
            macro_id: self.user.clone(),
            limit: Some(self.limit as u32),
            query: match &self.cursor {
                SoupQuery::Property(_) => return None,
                SoupQuery::Simple(SimpleQueryInner(Query::Sort(t, f))) => Some(Query::Sort(
                    *t,
                    with_properties_filter(
                        f.as_ref().and_then(|f| f.email_filter.tree.clone()),
                        properties_filter,
                    ),
                )),
                SoupQuery::Simple(SimpleQueryInner(Query::Cursor(CursorWithValAndFilter {
                    id,
                    limit,
                    val,
                    filter,
                }))) => Some(Query::Cursor(CursorWithValAndFilter {
                    id: *id,
                    limit: *limit,
                    val: val.clone(),
                    filter: with_properties_filter(
                        filter.as_ref().and_then(|f| f.email_filter.tree.clone()),
                        properties_filter,
                    ),
                })),
                // we don't yet have sort by frecency implemented for emails yet
                SoupQuery::Frecency(_) => None,
                // touched-by-me hydrates emails by thread id, not via this leg
                SoupQuery::Touched(_) => None,
                // notified-at hydrates its email candidates through this leg
                // with the request's own tree, so the view and every email
                // literal keep applying: the handler ANDs the thread ids in.
                SoupQuery::Notified(NotifiedQueryInner(query)) => Some(Query::Sort(
                    SimpleSortMethod::UpdatedAt,
                    with_properties_filter(
                        query
                            .filter()
                            .as_ref()
                            .and_then(|f| f.email_filter.tree.clone()),
                        properties_filter,
                    ),
                )),
            }?,
            include_frecency: false,
            team_receipt,
            crm_scope,
        })
    }

    /// The request's entity filter ast, regardless of cursor position.
    pub(crate) fn entity_ast(&self) -> Option<&EntityFilterAst> {
        match &self.cursor {
            SoupQuery::Property(query) => query.filter().as_ref(),
            SoupQuery::Simple(SimpleQueryInner(Query::Sort(_, f))) => f.as_ref(),
            SoupQuery::Simple(SimpleQueryInner(Query::Cursor(CursorWithValAndFilter {
                filter,
                ..
            }))) => filter.as_ref(),
            SoupQuery::Frecency(_) => None,
            SoupQuery::Touched(TouchedQueryInner(query)) => query.filter().as_ref(),
            SoupQuery::Notified(NotifiedQueryInner(query)) => query.filter().as_ref(),
        }
    }

    /// True when an active properties filter can never match an entity with
    /// no property rows. Property-less sub-requests (channels, channel
    /// threads, calls, CRM companies, foreign entities) are skipped so pages
    /// only contain rows the filter applies to.
    fn properties_filter_blocks_propertyless(&self) -> bool {
        self.entity_ast()
            .and_then(|a| a.properties_filter.as_deref())
            .is_some_and(|p| !properties_filter_matches_propertyless(p))
    }

    pub(crate) fn build_call_request(&self) -> Option<GetCallRecordsRequest> {
        if exclusions::call(self.entity_ast()) {
            return None;
        }
        // A def-less tag filter (entity_type None on every literal) applies to
        // calls, which carry tags; it is folded into the call filter below and
        // rendered as a `properties.values` EXISTS by the call query. Any other
        // active properties filter can't match a call, so the leg is skipped by
        // the propertyless check.
        let properties_filter = self
            .entity_ast()
            .and_then(|a| a.properties_filter.as_deref())
            .filter(|p| properties_filter_can_apply_to(p, &[]));
        if properties_filter.is_none() && self.properties_filter_blocks_propertyless() {
            return None;
        }
        Some(GetCallRecordsRequest {
            user_id: self.user.clone(),
            limit: self.limit as u32,
            query: match &self.cursor {
                SoupQuery::Property(_) => return None,
                SoupQuery::Simple(SimpleQueryInner(Query::Sort(t, f))) => Some(Query::Sort(
                    *t,
                    with_call_properties_filter(
                        f.as_ref().and_then(|f| f.call_filter.clone()),
                        properties_filter,
                    ),
                )),
                SoupQuery::Simple(SimpleQueryInner(Query::Cursor(CursorWithValAndFilter {
                    id,
                    limit,
                    val,
                    filter,
                }))) => Some(Query::Cursor(CursorWithValAndFilter {
                    id: *id,
                    limit: *limit,
                    val: val.clone(),
                    filter: with_call_properties_filter(
                        filter.as_ref().and_then(|f| f.call_filter.clone()),
                        properties_filter,
                    ),
                })),
                // query by frecency not yet implemented for call records
                SoupQuery::Frecency(_) => None,
                // call records carry no activity of their own (calls land on
                // the channel), so the touched feed never includes them
                SoupQuery::Touched(_) => None,
                // call notifications are not rolled into the notified feed
                SoupQuery::Notified(_) => None,
            }?,
        })
    }

    /// Returns `None` (skipping the CRM sub-request) for no-team users,
    /// Frecency cursors, or a malformed team-receipt uuid.
    pub(crate) fn build_crm_company_request(
        &self,
        team_receipt: &Option<EntityAccessReceipt<MemberTeamRole>>,
    ) -> Option<GetCrmCompaniesRequest> {
        if self.properties_filter_blocks_propertyless() {
            return None;
        }
        let receipt = team_receipt.as_ref()?;
        // Re-wrap the verified team receipt as the CRM capability token the
        // service now requires; a malformed receipt skips the sub-request.
        let access = CrmTeamReceipt::from_team_receipt(receipt.clone())
            .inspect_err(|e| {
                tracing::warn!(
                    error=?e,
                    "team_receipt is not a valid CRM team receipt; skipping crm_company sub-request"
                );
            })
            .ok()?;

        // Follow-up pages carry a keyset cursor (sort_ts + id of the
        // previous page's last row); the first page has none. Without
        // this the CRM sub-query always returned offset 0, so every
        // page re-served the same top companies.
        let (sort_method, filter_ast, cursor): (
            SimpleSortMethod,
            Option<&EntityFilterAst>,
            Option<CrmCompanySoupCursor>,
        ) = match &self.cursor {
            SoupQuery::Property(_) => return None,
            SoupQuery::Simple(SimpleQueryInner(Query::Sort(t, f))) => (*t, f.as_ref(), None),
            SoupQuery::Simple(SimpleQueryInner(Query::Cursor(CursorWithValAndFilter {
                id,
                val,
                filter,
                ..
            }))) => (
                val.sort_type,
                filter.as_ref(),
                Some(CrmCompanySoupCursor {
                    last_sort_ts: val.last_val,
                    last_id: *id,
                }),
            ),
            SoupQuery::Frecency(_) => return None,
            // CRM has no mutation activity (deferred from touched-by-me)
            SoupQuery::Touched(_) => return None,
            // CRM companies receive no notifications
            SoupQuery::Notified(_) => return None,
        };

        let sort = match sort_method {
            SimpleSortMethod::CreatedAt => CrmCompanyListSort::CreatedAt,
            SimpleSortMethod::UpdatedAt => CrmCompanyListSort::UpdatedAt,
            SimpleSortMethod::ViewedAt => CrmCompanyListSort::ViewedAt,
            SimpleSortMethod::ViewedUpdated => CrmCompanyListSort::ViewedUpdated,
        };

        let mut extract = CrmCompanyFilterExtract::default();
        if let Some(tree) = filter_ast.and_then(|a| a.crm_company_filter.as_ref())
            && !extract_crm_company_filter(tree, &mut extract)
        {
            // Fail closed: unsupported AST shape would widen the result
            // set. Skip the CRM sub-request rather than over-include.
            return None;
        }

        Some(GetCrmCompaniesRequest {
            access,
            user_id: self.user.clone(),
            company_ids: extract.ids,
            hidden: extract.hidden,
            sort,
            cursor,
            // Match the soup paginator's bounds so the CRM layer doesn't
            // overfetch on an oversized client limit.
            limit: self.limit.clamp(20, 500) as i64,
        })
    }

    pub(crate) fn build_comms_request(&self) -> Option<GetChannelsRequest> {
        if self.properties_filter_blocks_propertyless() || exclusions::channel(self.entity_ast()) {
            return None;
        }
        Some(GetChannelsRequest {
            macro_id: self.user.clone(),
            limit: Some(self.limit as u32),
            include_frecency: false,
            query: match &self.cursor {
                SoupQuery::Property(_) => return None,
                SoupQuery::Simple(SimpleQueryInner(Query::Sort(t, f))) => Some(Query::Sort(
                    *t,
                    f.as_ref().and_then(|f| f.channel_filter.clone()),
                )),
                SoupQuery::Simple(SimpleQueryInner(Query::Cursor(CursorWithValAndFilter {
                    id,
                    limit,
                    val,
                    filter,
                }))) => Some(Query::Cursor(CursorWithValAndFilter {
                    id: *id,
                    limit: *limit,
                    val: val.clone(),
                    filter: filter.as_ref().and_then(|f| f.channel_filter.clone()),
                })),
                // query by frecency not yet implemented for channels
                SoupQuery::Frecency(_) => None,
                // touched-by-me hydrates channels by id, not via this leg
                SoupQuery::Touched(_) => None,
                // notified-at hydrates its channel candidates through this
                // leg with the request's own tree; the handler ANDs the ids in
                SoupQuery::Notified(NotifiedQueryInner(query)) => Some(Query::Sort(
                    SimpleSortMethod::UpdatedAt,
                    query
                        .filter()
                        .as_ref()
                        .and_then(|f| f.channel_filter.clone()),
                )),
            }?,
        })
    }

    pub(crate) fn build_comms_thread_request(&self) -> Option<GetThreadReplyRowsRequest> {
        if self.properties_filter_blocks_propertyless()
            || exclusions::channel_thread(self.entity_ast())
        {
            return None;
        }
        let query = match &self.cursor {
            SoupQuery::Property(_) => return None,
            SoupQuery::Simple(SimpleQueryInner(Query::Sort(t, f))) => Some(Query::Sort(
                *t,
                f.as_ref().and_then(|f| f.channel_thread_filter.clone()),
            )),
            SoupQuery::Simple(SimpleQueryInner(Query::Cursor(CursorWithValAndFilter {
                id,
                limit,
                val,
                filter,
            }))) => Some(Query::Cursor(CursorWithValAndFilter {
                id: *id,
                limit: *limit,
                val: val.clone(),
                filter: filter
                    .as_ref()
                    .and_then(|f| f.channel_thread_filter.clone()),
            })),
            // query by frecency not yet implemented for channel threads
            SoupQuery::Frecency(_) => None,
            // channel-thread rows carry no activity (messages attribute to
            // the channel), so the touched feed never includes them
            SoupQuery::Touched(_) => None,
            // notified-at hydrates thread-scoped channel notifications through
            // this leg with the request's own tree; the handler ANDs the
            // thread ids in
            SoupQuery::Notified(NotifiedQueryInner(query)) => Some(Query::Sort(
                SimpleSortMethod::UpdatedAt,
                query
                    .filter()
                    .as_ref()
                    .and_then(|f| f.channel_thread_filter.clone()),
            )),
        }?;

        Some(GetThreadReplyRowsRequest {
            macro_id: self.user.clone(),
            limit: Some(self.limit as u32),
            query,
        })
    }

    pub(crate) fn build_foreign_entity_query(&self) -> Option<ForeignEntityListQuery> {
        if self.properties_filter_blocks_propertyless()
            || exclusions::foreign_entity(self.entity_ast())
        {
            return None;
        }
        match &self.cursor {
            SoupQuery::Property(_) => None,
            SoupQuery::Simple(SimpleQueryInner(Query::Sort(t, f))) => Some(Query::Sort(
                *t,
                f.as_ref()
                    .and_then(|filter| filter.foreign_entity_filter.clone()),
            )),
            SoupQuery::Simple(SimpleQueryInner(Query::Cursor(CursorWithValAndFilter {
                id,
                limit,
                val,
                filter,
            }))) => Some(Query::Cursor(CursorWithValAndFilter {
                id: *id,
                limit: *limit,
                val: val.clone(),
                filter: filter
                    .as_ref()
                    .and_then(|filter| filter.foreign_entity_filter.clone()),
            })),
            // query by frecency is not implemented for foreign entities
            SoupQuery::Frecency(_) => None,
            // foreign entities record no activity, so the touched feed never
            // includes them
            SoupQuery::Touched(_) => None,
            // notified-at hydrates its foreign-entity candidates through this
            // leg with the request's own tree; the handler ANDs the ids in
            SoupQuery::Notified(NotifiedQueryInner(query)) => Some(Query::Sort(
                SimpleSortMethod::UpdatedAt,
                query
                    .filter()
                    .as_ref()
                    .and_then(|filter| filter.foreign_entity_filter.clone()),
            )),
        }
    }

    /// The request's GitHub pull request filter, which narrows its foreign entity leg.
    pub(crate) fn build_github_pull_request_filter(&self) -> LiteralTree<GithubPullRequestLiteral> {
        self.entity_ast()
            .and_then(|ast| ast.github_pull_request_filter.clone())
    }

    pub(crate) fn build_foreign_entity_source_ids(
        &self,
        team_receipt: Option<&EntityAccessReceipt<MemberTeamRole>>,
    ) -> Vec<SourceId> {
        let mut source_ids = vec![SourceId::user(self.user.as_ref())];

        if let Some(receipt) = team_receipt {
            source_ids.push(SourceId::new(receipt.entity().entity_id.clone(), "team"));
        }

        source_ids
    }
}

/// Keyset position for a touched-by-me page: the touch timestamp and entity
/// id of the previous page's last row.
///
/// The id stays the raw stored string (never round-tripped through [`Uuid`]):
/// the SQL keyset compares it byte-for-byte against the `entity_id` TEXT
/// column, so any canonicalization would shift the page boundary.
#[derive(Debug, Clone)]
pub struct TouchedPagePosition {
    /// The last entity's latest-mutation timestamp.
    pub occurred_at: chrono::DateTime<chrono::Utc>,
    /// The last entity's id — the global tiebreaker when two entities share
    /// a touch timestamp.
    pub entity_id: String,
}

/// Parameters for one page of touched-by-me candidates.
#[derive(Debug)]
pub struct TouchedSoupRequest<'a> {
    /// User whose touches are listed; also the access-check subject.
    pub user_id: MacroUserIdStr<'a>,
    /// Maximum entities to return.
    pub limit: u16,
    /// Resume after this position; `None` for the first page.
    pub after: Option<TouchedPagePosition>,
    /// Entity filters folded into the candidate query.
    pub filter: Option<&'a EntityFilterAst>,
    /// Every inbox the caller can read; gates email-thread candidates.
    pub link_ids: &'a [Uuid],
}

/// One touched entity: what it is and when the user last mutated it.
#[derive(Debug, Clone)]
pub struct TouchedEntity {
    /// The touched entity.
    pub entity: Entity<'static>,
    /// The user's latest mutation of it.
    pub touched_at: chrono::DateTime<chrono::Utc>,
}

/// Keyset position for a notified-at page: the notification timestamp and
/// event item id of the previous page's last candidate.
///
/// Like [`TouchedPagePosition`], the id stays the raw stored string: the SQL
/// keyset compares it byte-for-byte against `notification.event_item_id`.
#[derive(Debug, Clone)]
pub struct NotifiedPagePosition {
    /// When the last candidate's latest notification was created for the user.
    pub notified_at: chrono::DateTime<chrono::Utc>,
    /// The last candidate's event item id — the tiebreaker when two
    /// candidates share a notification timestamp.
    pub entity_id: String,
}

/// Parameters for one page of notified-at candidates.
#[derive(Debug)]
pub struct NotifiedSoupRequest<'a> {
    /// User whose notifications are listed; also the access-check subject.
    pub user_id: MacroUserIdStr<'a>,
    /// Maximum candidates to return.
    pub limit: u16,
    /// Resume after this position; `None` for the first page.
    pub after: Option<NotifiedPagePosition>,
    /// Entity filters folded into the candidate query where soup owns the
    /// fold (documents, chats, projects, calendar events, properties).
    pub filter: Option<&'a EntityFilterAst>,
    /// Every inbox the caller can read; gates email-thread candidates.
    pub link_ids: &'a [Uuid],
    /// Sources (the caller and their team) whose stored foreign entities the
    /// caller may see; gates foreign-entity candidates.
    pub foreign_entity_sources: &'a [SourceId],
    /// Entity types whose candidates the domain can hydrate for this request.
    /// Types outside this set are never returned, whatever the notifications
    /// table holds.
    pub hydratable: NotifiedHydratableTypes,
}

/// Which domain-hydrated entity types a notified-at request can surface.
///
/// The repository gates documents, chats, projects and calendar events on
/// the filter tree itself; these four are hydrated through other domains'
/// legs, so whether that leg is active for the request is decided by the
/// service and passed down here.
#[derive(Debug, Clone, Copy, Default)]
pub struct NotifiedHydratableTypes {
    /// The channel leg is active.
    pub channels: bool,
    /// The channel-thread leg is active. Thread-scoped channel notifications
    /// (mentions and replies, which name their thread root as the secondary
    /// event item) surface as thread rows, the way the client attributes them.
    pub channel_threads: bool,
    /// The email leg is active.
    pub email_threads: bool,
    /// The foreign-entity leg is active.
    pub foreign_entities: bool,
}

/// One notified entity: what it is and when the user was last notified.
#[derive(Debug, Clone)]
pub struct NotifiedEntity {
    /// The entity the notification is about.
    pub entity: Entity<'static>,
    /// When the user's latest notification about it was created.
    pub notified_at: chrono::DateTime<chrono::Utc>,
}

/// How the attention candidate query keys the notifications that place its
/// candidates.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum AttentionKeying {
    /// A channel notification naming a thread root (`secondary_event_item`
    /// of type `channel_message`) keys to a `channel_message` candidate on
    /// it, like the notified-at feed; others key to their own entity.
    ThreadScoped,
    /// Every notification keys to the entity it is filed under.
    FiledEntity,
}

/// Keyset position for an attention feed page: the sort time and entity id
/// of the last candidate the previous page walked.
///
/// Like [`NotifiedPagePosition`], the id stays the raw stored string.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct AttentionPagePosition {
    /// The last candidate's sort time: the later of its attention and
    /// own-work timestamps.
    pub sort_at: chrono::DateTime<chrono::Utc>,
    /// The last candidate's entity id — the tiebreaker on equal sort times.
    pub entity_id: String,
}

/// Parameters for one page of attention feed candidates.
#[derive(Debug)]
pub struct AttentionCandidateRequest<'a> {
    /// User whose feed is listed; also the access-check subject.
    pub user_id: MacroUserIdStr<'a>,
    /// Maximum candidates to return.
    pub limit: u16,
    /// Whether the viewer's own work admits candidates besides attention.
    pub own_work: bool,
    /// How notifications key to candidates.
    pub keying: AttentionKeying,
    /// Resume after this position; `None` for the first page.
    pub after: Option<AttentionPagePosition>,
    /// Entity types the caller asked for. Narrowed further by the filter
    /// and by which hydration legs are active.
    pub types: &'a [EntityType],
    /// Entity filters folded into the candidate gates where soup owns the
    /// fold, exactly as for the notified-at feed.
    pub filter: Option<&'a EntityFilterAst>,
    /// Every inbox the caller can read; gates email-thread candidates.
    pub link_ids: &'a [Uuid],
    /// Sources whose stored foreign entities the caller may see.
    pub foreign_entity_sources: &'a [SourceId],
    /// Entity types whose candidates the domain can hydrate for this request.
    pub hydratable: NotifiedHydratableTypes,
    /// Whether CRM company and contact candidates can be hydrated: the viewer
    /// has a CRM team receipt.
    pub crm: bool,
    /// Restrict the feed to these candidate keys, for recomputing known items.
    pub only: Option<&'a [Entity<'static>]>,
}

/// One attention feed candidate and the timestamps of its two reasons.
///
/// Each candidate carries the reason that places it in the feed: its
/// `sort_at` is the later of the two timestamps, and exactly one of the
/// candidate query's two streams emits it.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct AttentionCandidate {
    /// The candidate's entity; channel-thread candidates are keyed on their
    /// thread root as a `channel_message`, like the notified-at feed.
    pub entity: Entity<'static>,
    /// The newest pending (unseen or seen) notification keyed to the
    /// candidate. An own-work candidate omits attention older than the page's
    /// oldest own work, which the query does not read and which cannot move it.
    pub attention_at: Option<chrono::DateTime<chrono::Utc>>,
    /// The viewer's latest own (non-view) activity on the candidate. Always
    /// `None` in attention mode.
    pub touched_at: Option<chrono::DateTime<chrono::Utc>>,
    /// Where the candidate sits in the feed.
    pub sort_at: chrono::DateTime<chrono::Utc>,
}

/// Request for one page of a hydrated attention feed: Home's work feed or
/// the notifications inbox.
#[derive(Debug, Clone)]
pub struct AttentionSoupRequest {
    /// User whose feed is listed.
    pub user: MacroUserIdStr<'static>,
    /// Every inbox the caller can read.
    pub link_ids: Vec<Uuid>,
    /// Maximum items to return.
    pub limit: u16,
    /// Whether the viewer's own work admits items besides attention.
    pub own_work: bool,
    /// How notifications key to candidates.
    pub keying: AttentionKeying,
    /// Entity types to include.
    pub types: Vec<EntityType>,
    /// Membership filters, folded into the candidate gates and applied in
    /// full by each domain's hydration leg.
    pub filter: EntityFilterAst,
    /// Resume after this position; `None` for the first page.
    pub after: Option<AttentionPagePosition>,
    /// Restrict the feed to these candidate keys, for recomputing known items.
    pub only: Option<Vec<Entity<'static>>>,
}

/// One hydrated attention feed item and its reason timestamps.
#[derive(Debug)]
pub struct AttentionSoupItem {
    /// The authorized Soup item with its server facts.
    pub hydration: SoupProjectionHydration,
    /// See [`AttentionCandidate::attention_at`].
    pub attention_at: Option<chrono::DateTime<chrono::Utc>>,
    /// See [`AttentionCandidate::touched_at`].
    pub touched_at: Option<chrono::DateTime<chrono::Utc>>,
    /// See [`AttentionCandidate::sort_at`].
    pub sort_at: chrono::DateTime<chrono::Utc>,
}

/// One page of a hydrated attention feed.
#[derive(Debug)]
pub struct AttentionSoupPage {
    /// The page's items, newest first.
    pub items: Vec<AttentionSoupItem>,
    /// Where the next page starts; `None` once the feed is exhausted.
    pub next: Option<AttentionPagePosition>,
}

/// Whether the notified-at candidate query can fold this calendar filter.
///
/// Only id and notification-state literals have a soup-owned fold; the rest
/// (status, time bounds, attendee, organizer) live in the calendar leg's
/// query builder, which the candidate query cannot reach. Rejecting up front
/// beats silently returning a feed with those events unfiltered.
#[cfg(feature = "ports")]
pub(crate) fn calendar_filter_supported_by_notified(
    tree: Option<&Expr<CalendarEventLiteral>>,
) -> bool {
    tree.is_none_or(|expr| {
        expr.collapse_frames(|frame| match frame {
            filter_ast::ExprFrame::And(a, b) | filter_ast::ExprFrame::Or(a, b) => a && b,
            filter_ast::ExprFrame::Not(a) => a,
            filter_ast::ExprFrame::Literal(
                CalendarEventLiteral::Id(_) | CalendarEventLiteral::NotificationState(_),
            ) => true,
            filter_ast::ExprFrame::Literal(_) => false,
        })
    })
}

/// ANDs a properties filter into the email filter tree as thread-level
/// [EmailLiteral::Property] conditions, so the email query returns exactly
/// the threads that satisfy it.
#[cfg(feature = "ports")]
fn with_properties_filter(
    tree: Option<Arc<Expr<EmailLiteral>>>,
    properties_filter: Option<&Expr<PropertiesLiteral>>,
) -> Option<Arc<Expr<EmailLiteral>>> {
    let Some(propf) = properties_filter else {
        return tree;
    };
    let mapped = map_properties_to_email(propf);
    Some(Arc::new(match tree {
        Some(tree) => Expr::and((*tree).clone(), mapped),
        None => mapped,
    }))
}

#[cfg(feature = "ports")]
fn map_properties_to_email(expr: &Expr<PropertiesLiteral>) -> Expr<EmailLiteral> {
    match expr {
        Expr::And(a, b) => Expr::and(map_properties_to_email(a), map_properties_to_email(b)),
        Expr::Or(a, b) => Expr::or(map_properties_to_email(a), map_properties_to_email(b)),
        Expr::Not(a) => Expr::Not(Box::new(map_properties_to_email(a))),
        Expr::Literal(lit) => Expr::Literal(EmailLiteral::Property(lit.clone())),
    }
}

/// ANDs a properties filter (mapped to [CallLiteral::Property] conditions) into
/// the call filter tree, so the call query returns exactly the calls that also
/// satisfy the tag filter.
#[cfg(feature = "ports")]
fn with_call_properties_filter(
    tree: Option<Arc<Expr<CallLiteral>>>,
    properties_filter: Option<&Expr<PropertiesLiteral>>,
) -> Option<Arc<Expr<CallLiteral>>> {
    let Some(propf) = properties_filter else {
        return tree;
    };
    let mapped = map_properties_to_call(propf);
    Some(Arc::new(match tree {
        Some(tree) => Expr::and((*tree).clone(), mapped),
        None => mapped,
    }))
}

#[cfg(feature = "ports")]
fn map_properties_to_call(expr: &Expr<PropertiesLiteral>) -> Expr<CallLiteral> {
    match expr {
        Expr::And(a, b) => Expr::and(map_properties_to_call(a), map_properties_to_call(b)),
        Expr::Or(a, b) => Expr::or(map_properties_to_call(a), map_properties_to_call(b)),
        Expr::Not(a) => Expr::Not(Box::new(map_properties_to_call(a))),
        Expr::Literal(lit) => Expr::Literal(CallLiteral::Property(lit.clone())),
    }
}

/// An entity whose Companies or Contacts property names a CRM record.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CrmPropertyEdge {
    /// The entity type the property row is stored under.
    pub entity_type: models_properties::EntityType,
    /// The entity id the property row is stored under.
    pub entity_id: String,
}

/// Parameters for fetching CRM companies to fold into the soup feed.
#[derive(Debug)]
pub struct GetCrmCompaniesRequest {
    /// Capability token for the team whose CRM companies to list. The
    /// service derives the team id from it.
    pub access: CrmTeamReceipt<MemberTeamRole>,
    /// Requesting user — used to scope the per-user `UserHistory` join
    /// behind the `Viewed*` sort variants. Always populated; the soup
    /// request always has a user.
    pub user_id: MacroUserIdStr<'static>,
    /// Filter to specific company ids. Empty = all of the team's
    /// companies matching `hidden` (subject to the killswitch).
    pub company_ids: Vec<Uuid>,
    /// Optional `crm_companies.hidden` filter. `None` = visible only
    /// (default); `Some(false)` = visible only (explicit); `Some(true)`
    /// = hidden only. The admin/owner role check is enforced by the CRM
    /// service from `access` when this request is executed.
    pub hidden: Option<bool>,
    /// Which timestamp column to sort by.
    pub sort: CrmCompanyListSort,
    /// Keyset cursor to seek past the previous page (`None` = first page).
    pub cursor: Option<CrmCompanySoupCursor>,
    /// Upper bound on rows returned — the soup paginator re-slices.
    pub limit: i64,
}

/// Outcome of walking a `CrmCompanyLiteral` AST: the ids and the
/// optional `hidden` constraint pulled out of the tree.
#[cfg(feature = "ports")]
#[derive(Debug, Default)]
pub(crate) struct CrmCompanyFilterExtract {
    pub ids: Vec<Uuid>,
    pub hidden: Option<bool>,
}

/// Walks a `CrmCompanyLiteral` AST collecting `Id(uuid)` literals into
/// `out.ids` and a single `Hidden(bool)` constraint into `out.hidden`.
/// Returns `false` (fail closed) when:
///   - `Not(_)` appears (would invert set semantics),
///   - two `Hidden(_)` literals conflict (e.g. `Hidden(true) AND Hidden(false)`),
///   - an `Or(_, _)` branch mixes ids and a hidden literal (would change
///     set semantics in ways the simple extractor can't represent).
#[cfg(feature = "ports")]
fn extract_crm_company_filter(
    expr: &Expr<CrmCompanyLiteral>,
    out: &mut CrmCompanyFilterExtract,
) -> bool {
    match expr {
        Expr::Literal(CrmCompanyLiteral::Id(id)) => {
            out.ids.push(*id);
            true
        }
        Expr::Literal(CrmCompanyLiteral::Hidden(b)) => match out.hidden {
            Some(prev) if prev != *b => false,
            _ => {
                out.hidden = Some(*b);
                true
            }
        },
        // `And` of arbitrary sub-trees: each side contributes independently
        // (e.g. id-OR AND Hidden).
        Expr::And(a, b) => extract_crm_company_filter(a, out) && extract_crm_company_filter(b, out),
        // `Or` is only safe over ids — mixing a Hidden literal under an Or
        // would change semantics ("these ids OR all hidden") that the flat
        // extract can't represent.
        Expr::Or(a, b) => or_is_ids_only(a, out) && or_is_ids_only(b, out),
        Expr::Not(_) => false,
    }
}

/// Helper for [`extract_crm_company_filter`]: an `Or` branch must be a
/// pure id sub-tree (nested `Or` of `Id` literals) — any `Hidden`, `And`,
/// or `Not` inside fails closed.
#[cfg(feature = "ports")]
fn or_is_ids_only(expr: &Expr<CrmCompanyLiteral>, out: &mut CrmCompanyFilterExtract) -> bool {
    match expr {
        Expr::Literal(CrmCompanyLiteral::Id(id)) => {
            out.ids.push(*id);
            true
        }
        Expr::Or(a, b) => or_is_ids_only(a, out) && or_is_ids_only(b, out),
        _ => false,
    }
}

/// Authoritative document facts that are unavailable as direct Soup fields.
///
/// This value is internal hydration state. It is deliberately separate from
/// public Soup entity models so relation-backed facts do not become business
/// fields on [`models_soup::document::SoupDocument`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SoupDocumentServerFacts {
    /// Whether `document_email` contains a row for the document.
    pub is_email_attachment: bool,
    /// Whether the document is important to the requesting viewer.
    ///
    /// Non-task documents are important. Tasks are important when the viewer
    /// appears in the authoritative Assignees system property.
    pub is_important: bool,
    /// Complete authoritative Status select-option IDs for a task.
    ///
    /// Non-task documents and tasks without a Status value carry an empty set.
    pub status_option_ids: Vec<uuid::Uuid>,
}

/// An authorized Soup item and any server-only facts read by the same
/// hydration operation.
///
/// `document_server_facts` is populated only when authoritative document
/// relation state was loaded. Projects, chats, unsupported entities, and
/// unenriched hydration paths leave it empty because they have no supplement
/// to emit.
#[derive(Debug, Clone)]
pub struct SoupProjectionHydration<Item = SoupItem<()>> {
    /// Authorized Soup item returned to the caller.
    pub item: Item,
    /// Relation-backed document facts unavailable in direct Soup fields.
    pub document_server_facts: Option<SoupDocumentServerFacts>,
    /// Signed property key produced by the same query; null for missing values.
    pub sort_key: Option<f64>,
}

impl<Item> SoupProjectionHydration<Item> {
    /// Map the hydrated item while preserving its authoritative server facts.
    pub fn map<F, Mapped>(self, map: F) -> SoupProjectionHydration<Mapped>
    where
        F: FnOnce(Item) -> Mapped,
    {
        SoupProjectionHydration {
            item: map(self.item),
            document_server_facts: self.document_server_facts,
            sort_key: self.sort_key,
        }
    }
}

/// A Soup result with both optional enrichments represented in one model.
///
/// Service methods decide which fields to populate. An unfetched enrichment
/// remains empty without changing the response model.
#[derive(Debug, Clone)]
#[non_exhaustive]
pub struct EnrichedSoupItem {
    /// The Soup item with its property projection.
    pub item: SoupItem<SoupPropertiesField>,
    /// The aggregate frecency score, when requested and available.
    pub frecency_score: Option<AggregateFrecency>,
    /// The caller's latest own mutation of this entity, populated only when
    /// the page was ordered by `touched_by_me`. Clients sort and optimistic-
    /// reorder the touched feed on this value.
    pub touched_at: Option<chrono::DateTime<chrono::Utc>>,
    /// When the caller was last notified about this entity, populated only
    /// when the page was ordered by `notified_at`. Clients sort and bucket
    /// the notified feed on this value.
    pub notified_at: Option<chrono::DateTime<chrono::Utc>>,
}

impl From<SoupItem<SoupPropertiesField>> for EnrichedSoupItem {
    /// An item enriched with its properties alone, as
    /// [`SoupService::get_user_soup_with_properties`](super::ports::SoupService::get_user_soup_with_properties)
    /// answers it.
    fn from(item: SoupItem<SoupPropertiesField>) -> Self {
        Self {
            item,
            frecency_score: None,
            touched_at: None,
            notified_at: None,
        }
    }
}

/// A soup request with optional grouping configuration.
#[derive(Debug)]
pub struct GroupedSoupRequest<T> {
    /// Base soup request parameters
    pub base: SoupRequest<T>,
    /// Optional grouping configuration
    pub grouping: Option<GroupingConfig>,
}

/// Errors returned while building or executing soup queries.
#[derive(Debug, Error)]
pub enum SoupErr {
    /// Frecency query failed.
    #[error(transparent)]
    FrecencyErr(#[from] FrecencyQueryErr),
    /// Soup repository query failed.
    #[error(transparent)]
    SoupDbErr(#[from] anyhow::Error),
    /// Email preview lookup failed.
    #[error(transparent)]
    EmailErr(#[from] email::domain::models::EmailErr),
    /// Channel or communication lookup failed.
    #[error("A comms error has occured, see logs for more details")]
    CommsErr,
    /// Call record lookup failed.
    #[error("A call error has occurred, see logs for more details")]
    CallErr,
    /// CRM lookup failed.
    #[error("A CRM error has occurred, see logs for more details")]
    CrmErr,
    /// A touched-by-me query carried a filter kind this mode cannot
    /// evaluate (the fold lives in another domain's query builder).
    /// Rejecting beats silently returning a feed with that type missing.
    #[error("sort_method=touched_by_me does not support {0} filters")]
    TouchedUnsupportedFilter(&'static str),
    /// A notified-at query carried a filter kind this mode cannot evaluate
    /// (the fold lives in another domain's query builder).
    #[error("sort_method=notified_at does not support {0} filters")]
    NotifiedUnsupportedFilter(&'static str),
    /// The filter requested CRM-scoped data but the caller has no
    /// qualifying team membership.
    #[error("CRM-scoped queries require team membership")]
    CrmTeamRequired,
    /// The filter requested hidden CRM companies but the caller's team
    /// role is below admin/owner.
    #[error("Querying hidden CRM companies requires admin/owner team role")]
    CrmAdminRequired,
    /// The filter is restricted to a CRM record the caller cannot see.
    #[error("CRM record not found")]
    CrmRecordNotFound,
    /// GitHub pull request listing failed.
    #[error(transparent)]
    GithubPullRequestErr(#[from] GithubPullRequestError),
    /// Entity filter AST expansion failed.
    #[error(transparent)]
    AstErr(#[from] ExpandErr),
}

/// Property fields that can be flattened into property-bearing Soup items.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[cfg_attr(feature = "axum", derive(utoipa::ToSchema))]
pub struct SoupPropertiesField {
    /// Properties attached to the entity.
    pub properties: Vec<SoupProperty>,
}

/// A Soup item with entity properties attached.
pub type SoupItemWithProperties = SoupItem<SoupPropertiesField>;

impl SoupPropertiesField {
    /// Creates an extra field containing the supplied properties.
    pub fn new(properties: Vec<SoupProperty>) -> Self {
        Self { properties }
    }
}