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.

27.7 KB
Raw Blame
//! Webhook event ingestion: broker events in, matching queue messages out.
//!
//! `WebhookEventIngestionService` is the inbound port driven by broker
//! consumers (see `crate::inbound::kafka_consumer`). It is intentionally
//! separate from `WebhookService`, which is the CRUD surface for webhook
//! creation and edits.

#[cfg(feature = "stream")]
pub(crate) mod stream;
#[cfg(test)]
mod test;

use crate::domain::{
    events::WebhookTopicEvent,
    models::{NormalizedWebhookEvent, WebhookEventQueueMessage},
    ports::{WebhookEventEnqueuer, WebhookRepo, WebhookWorkspaceResolver},
};
use agent_session::domain::events::{AgentSessionLifecycleEvent, AgentSessionLifecycleEventName};
use agent_trigger::domain::broker_events::AgentTriggerTopicEvent;
use call::domain::notification_events::CallNotificationEvent;
use channels::domain::broker_events::ChannelTopicEvent;
use chrono::Utc;
use documents::domain::events::DocumentTopicEvent;
use entity_access::domain::models::{AccessError, EntityType};
use entity_access::domain::ports::EntityAccessService;
use futures::future::join_all;
use macro_event_broker::Event;
use macro_user_id::user_id::MacroUserIdStr;
use messages::domain::models::MessageParent;
use messages::outbound::broker::MessageTopicEvent;
use std::future::Future;
use std::sync::Arc;
use tracing::Instrument as _;
use uuid::Uuid;

const DOCUMENT_ENTITY_TYPE: &str = "document";
const CHANNEL_ENTITY_TYPE: &str = "channel";
const CALL_ENTITY_TYPE: &str = "call";
const WEBHOOK_ENTITY_TYPE: &str = "webhook";
const AGENT_SESSION_ENTITY_TYPE: &str = "agent_session";

/// Webhook event ingestion error.
#[derive(Debug, thiserror::Error)]
pub enum WebhookEventIngestionError {
    /// Failed to resolve the users with access to the event's entity.
    #[error(transparent)]
    EntityAccess(#[from] AccessError),
    /// The event's entity identifier violates the broker contract.
    #[error("invalid {entity_type} entity id: {entity_id}")]
    InvalidEntityId {
        /// Contract entity type.
        entity_type: &'static str,
        /// Invalid entity identifier.
        entity_id: String,
    },
    /// A private call notification has no explicit recipient.
    #[error("private call notification has no recipient")]
    MissingCallRecipient,
    /// The broker envelope could not be represented by the queue contract.
    #[error("failed to serialize broker envelope: {0}")]
    Serialization(#[from] serde_json::Error),
    /// Failed to resolve personal and team webhook workspaces.
    #[error("failed to resolve webhook workspaces: {0}")]
    WorkspaceResolution(#[source] anyhow::Error),
    /// Failed to find active webhooks matching the event.
    #[error("failed to match active webhooks: {0}")]
    Repository(#[source] anyhow::Error),
    /// Failed to enqueue at least one matched webhook event.
    #[error("failed to enqueue webhook event: {0}")]
    Enqueue(#[source] anyhow::Error),
}

impl WebhookEventIngestionError {
    /// Whether retrying the same event could plausibly succeed.
    ///
    /// Access resolution classifies failures at the database boundary:
    /// [`AccessError::Unavailable`] is a connection-level or retryable
    /// Postgres failure, while [`AccessError::Internal`] is a bug or bad
    /// data that retrying cannot fix. Invalid broker contracts are
    /// permanent and can be safely skipped.
    pub fn is_transient(&self) -> bool {
        matches!(
            self,
            Self::EntityAccess(AccessError::Unavailable(_))
                | Self::WorkspaceResolution(_)
                | Self::Repository(_)
                | Self::Enqueue(_)
        )
    }
}

/// Inbound port for ingesting broker events for webhook delivery.
///
/// One method per subscribed topic; each takes the decoded event envelope so
/// implementations retain the `event_id` and complete original payload.
pub trait WebhookEventIngestionService: Clone + Send + Sync + 'static {
    /// Ingest one `macro.documents` event envelope.
    fn ingest_document_event(
        &self,
        event: Event<DocumentTopicEvent>,
    ) -> impl Future<Output = Result<(), WebhookEventIngestionError>> + Send;

    /// Ingest one `macro.channels` event envelope.
    fn ingest_channel_event(
        &self,
        event: Event<ChannelTopicEvent>,
    ) -> impl Future<Output = Result<(), WebhookEventIngestionError>> + Send;

    /// Ingest one access-checked call notification.
    fn ingest_call_notification_event(
        &self,
        event: Event<CallNotificationEvent>,
    ) -> impl Future<Output = Result<(), WebhookEventIngestionError>> + Send;

    /// Ingest one `macro.messages` event envelope.
    fn ingest_message_event(
        &self,
        event: Event<MessageTopicEvent>,
    ) -> impl Future<Output = Result<(), WebhookEventIngestionError>> + Send;

    /// Ingest one `macro.webhooks` event envelope.
    fn ingest_webhook_event(
        &self,
        event: Event<WebhookTopicEvent>,
    ) -> impl Future<Output = Result<(), WebhookEventIngestionError>> + Send;

    /// Ingest one `macro.agent_sessions` event envelope.
    fn ingest_agent_trigger_event(
        &self,
        event: Event<AgentTriggerTopicEvent>,
    ) -> impl Future<Output = Result<(), WebhookEventIngestionError>> + Send;

    /// Ingest one `macro.agent_session_lifecycle` event envelope.
    fn ingest_agent_session_lifecycle_event(
        &self,
        event: Event<AgentSessionLifecycleEvent>,
    ) -> impl Future<Output = Result<(), WebhookEventIngestionError>> + Send;
}

/// Webhook event ingestion service implementation.
#[derive(Clone)]
pub struct WebhookEventIngestionServiceImpl<A, R, Q> {
    entity_access_service: Arc<A>,
    repository: R,
    enqueuer: Q,
}

impl<A, R, Q> WebhookEventIngestionServiceImpl<A, R, Q> {
    /// Create a webhook event ingestion service.
    pub fn new(entity_access_service: Arc<A>, repository: R, enqueuer: Q) -> Self {
        Self {
            entity_access_service,
            repository,
            enqueuer,
        }
    }
}

impl<A, R, Q> WebhookEventIngestionServiceImpl<A, R, Q>
where
    A: EntityAccessService,
    R: WebhookRepo + WebhookWorkspaceResolver,
    Q: WebhookEventEnqueuer,
{
    /// Resolve the users that currently have access to an entity.
    #[tracing::instrument(skip(self), err)]
    pub async fn users_with_access(
        &self,
        entity_id: &str,
        entity_type: EntityType,
    ) -> Result<Vec<MacroUserIdStr<'static>>, WebhookEventIngestionError> {
        self.entity_access_service
            .get_users_by_entity(entity_id, entity_type)
            .await
            .map_err(WebhookEventIngestionError::EntityAccess)
    }

    #[tracing::instrument(
        skip_all,
        fields(
            event_id = %event.event_id,
            event_name = %event.event_name,
            entity_type = %event.entity_type,
            entity_id = %event.entity_id,
            accessor_count = tracing::field::Empty,
            workspace_count = tracing::field::Empty,
        ),
        err
    )]
    async fn resolve_entity_access_and_enqueue(
        &self,
        event: NormalizedWebhookEvent,
        entity_type: EntityType,
    ) -> Result<(), WebhookEventIngestionError> {
        let accessors = self
            .users_with_access(&event.entity_id, entity_type)
            .await?;
        tracing::Span::current().record("accessor_count", accessors.len());

        let workspace_ids = self
            .repository
            .resolve_workspace_ids(accessors)
            .await
            .map_err(|error| WebhookEventIngestionError::WorkspaceResolution(error.into()))?;
        tracing::Span::current().record("workspace_count", workspace_ids.len());

        self.match_and_enqueue(event, workspace_ids).await
    }

    #[tracing::instrument(
        skip_all,
        fields(
            event_id = %event.event_id,
            event_name = %event.event_name,
            entity_type = %event.entity_type,
            entity_id = %event.entity_id,
            workspace_count = workspace_ids.len(),
            match_count = tracing::field::Empty,
        ),
        err
    )]
    async fn match_and_enqueue(
        &self,
        event: NormalizedWebhookEvent,
        workspace_ids: Vec<String>,
    ) -> Result<(), WebhookEventIngestionError> {
        let webhooks = self
            .repository
            .list_active_webhooks_matching_event(
                workspace_ids,
                event.event_name.clone(),
                event.entity_id.clone(),
            )
            .await
            .map_err(|error| WebhookEventIngestionError::Repository(error.into()))?;
        tracing::Span::current().record("match_count", webhooks.len());
        self.enqueue_all(webhooks, event).await
    }

    async fn enqueue_all(
        &self,
        webhooks: Vec<crate::domain::models::Webhook>,
        event: NormalizedWebhookEvent,
    ) -> Result<(), WebhookEventIngestionError> {
        let enqueue_results = join_all(webhooks.into_iter().map(|webhook| {
            let enqueuer = self.enqueuer.clone();
            let webhook_id = webhook.id;
            let message = WebhookEventQueueMessage::new(webhook_id.clone(), event.clone());
            async move {
                enqueuer
                    .enqueue(message)
                    .instrument(tracing::info_span!("enqueue_webhook_event", %webhook_id))
                    .await
                    .map_err(Into::into)
            }
        }))
        .await;

        for result in enqueue_results {
            result.map_err(WebhookEventIngestionError::Enqueue)?;
        }

        Ok(())
    }
}

pub(crate) fn normalized_document_event(
    event: &Event<DocumentTopicEvent>,
) -> Result<Option<NormalizedWebhookEvent>, WebhookEventIngestionError> {
    let (event_name, entity_id) = match &event.event {
        DocumentTopicEvent::Created(metadata) => ("document.created", &metadata.document_id),
        DocumentTopicEvent::Updated(metadata) => ("document.updated", &metadata.document_id),
        DocumentTopicEvent::Deleted(metadata) => ("document.deleted", &metadata.document_id),
        DocumentTopicEvent::Copied(metadata) => ("document.copied", &metadata.document_id),
        DocumentTopicEvent::Interaction(metadata) => {
            ("document.interaction", &metadata.document_id)
        }
        DocumentTopicEvent::ContentUploaded(_)
        | DocumentTopicEvent::SyncContentUpdated(_)
        | DocumentTopicEvent::Purged(_) => return Ok(None),
    };

    if Uuid::parse_str(entity_id).is_err() {
        return Err(WebhookEventIngestionError::InvalidEntityId {
            entity_type: DOCUMENT_ENTITY_TYPE,
            entity_id: entity_id.clone(),
        });
    }

    let broker_envelope = serde_json::to_value(event)?;
    Ok(Some(normalized_event(
        event.event_id,
        event.schema_version,
        event_name,
        DOCUMENT_ENTITY_TYPE,
        entity_id,
        broker_envelope,
    )))
}

/// Normalize a call event and remove its private routing field before delivery.
pub(crate) fn normalized_call_notification_event(
    event: &Event<CallNotificationEvent>,
) -> Result<(NormalizedWebhookEvent, Option<String>), WebhookEventIngestionError> {
    let metadata = event.event.metadata();
    let recipient = match &event.event {
        CallNotificationEvent::Ringing(_)
        | CallNotificationEvent::Answered(_)
        | CallNotificationEvent::Declined(_)
        | CallNotificationEvent::Invited(_) => Some(
            metadata
                .recipient_user_id
                .clone()
                .filter(|id| !id.is_empty())
                .ok_or(WebhookEventIngestionError::MissingCallRecipient)?,
        ),
        _ => None,
    };
    let mut broker_envelope = serde_json::to_value(event)?;
    if let Some(metadata) = broker_envelope
        .get_mut("metadata")
        .and_then(serde_json::Value::as_object_mut)
    {
        metadata.remove("recipient_user_id");
    }
    let call_id = metadata.call_id.to_string();
    Ok((
        normalized_event(
            event.event_id,
            event.schema_version,
            event.event.name(),
            CALL_ENTITY_TYPE,
            &call_id,
            broker_envelope,
        ),
        recipient,
    ))
}

pub(crate) fn normalized_channel_event(
    event: &Event<ChannelTopicEvent>,
) -> Result<NormalizedWebhookEvent, WebhookEventIngestionError> {
    let (event_name, channel_id) = match &event.event {
        ChannelTopicEvent::Created(metadata) => ("channel.created", metadata.channel_id),
        ChannelTopicEvent::Updated(metadata) => ("channel.updated", metadata.channel_id),
        ChannelTopicEvent::PictureChanged(metadata) => {
            ("channel.picture_changed", metadata.channel_id)
        }
        ChannelTopicEvent::Deleted(metadata) => ("channel.deleted", metadata.channel_id),
        ChannelTopicEvent::ParticipantAdded(metadata) => {
            ("channel.participant_added", metadata.channel_id)
        }
        ChannelTopicEvent::ParticipantRemoved(metadata) => {
            ("channel.participant_removed", metadata.channel_id)
        }
        ChannelTopicEvent::AccessRequested(metadata) => {
            ("channel.access_requested", metadata.channel_id)
        }
    };
    let entity_id = channel_id.to_string();

    let broker_envelope = serde_json::to_value(event)?;
    Ok(normalized_event(
        event.event_id,
        event.schema_version,
        event_name,
        CHANNEL_ENTITY_TYPE,
        &entity_id,
        broker_envelope,
    ))
}

/// Normalize one message fact.
///
/// The entity is the message's parent, so access and `ids` filtering are by
/// the channel or document that owns the conversation, and the parent travels
/// in the payload for consumers to route on.
pub(crate) fn normalized_message_event(
    event: &Event<MessageTopicEvent>,
) -> Result<(NormalizedWebhookEvent, EntityType), WebhookEventIngestionError> {
    let (event_name, parent) = match &event.event {
        MessageTopicEvent::Posted(metadata) => ("message.posted", &metadata.parent),
        MessageTopicEvent::Patched(metadata) => ("message.patched", &metadata.parent),
        MessageTopicEvent::Deleted(metadata) => ("message.deleted", &metadata.parent),
        MessageTopicEvent::Mentioned(metadata) => ("message.mentioned", &metadata.parent),
        MessageTopicEvent::AttachmentCreated(metadata) => {
            ("message.attachment_created", &metadata.parent)
        }
        MessageTopicEvent::AttachmentRemoved(metadata) => {
            ("message.attachment_removed", &metadata.parent)
        }
    };
    let entity_id = parent.entity_id();

    let broker_envelope = serde_json::to_value(event)?;
    Ok((
        normalized_event(
            event.event_id,
            event.schema_version,
            event_name,
            parent.entity_type(),
            &entity_id,
            broker_envelope,
        ),
        parent.access_entity_type(),
    ))
}

pub(crate) fn normalized_webhook_event(
    event: &Event<WebhookTopicEvent>,
) -> Result<(NormalizedWebhookEvent, String), WebhookEventIngestionError> {
    let (event_name, webhook_id, workspace_id) = match &event.event {
        WebhookTopicEvent::Created(metadata) => (
            "webhook.created",
            &metadata.webhook_id,
            &metadata.workspace_id,
        ),
        WebhookTopicEvent::Updated(metadata) => (
            "webhook.updated",
            &metadata.webhook_id,
            &metadata.workspace_id,
        ),
        WebhookTopicEvent::Deleted(metadata) => (
            "webhook.deleted",
            &metadata.webhook_id,
            &metadata.workspace_id,
        ),
        WebhookTopicEvent::Validated(metadata) => (
            "webhook.validated",
            &metadata.webhook_id,
            &metadata.workspace_id,
        ),
    };

    if webhook_id.is_empty() || !webhook_id.starts_with("wh_") {
        return Err(WebhookEventIngestionError::InvalidEntityId {
            entity_type: WEBHOOK_ENTITY_TYPE,
            entity_id: webhook_id.clone(),
        });
    }

    let broker_envelope = serde_json::to_value(event)?;
    let normalized = normalized_event(
        event.event_id,
        event.schema_version,
        event_name,
        WEBHOOK_ENTITY_TYPE,
        webhook_id,
        broker_envelope,
    );
    Ok((normalized, workspace_id.clone()))
}

fn normalized_event(
    event_id: Uuid,
    schema_version: u8,
    event_name: &str,
    entity_type: &str,
    entity_id: &str,
    broker_envelope: serde_json::Value,
) -> NormalizedWebhookEvent {
    NormalizedWebhookEvent {
        event_id: event_id.to_string(),
        schema_version,
        event_name: event_name.to_string(),
        entity_type: entity_type.to_string(),
        entity_id: entity_id.to_string(),
        ordering_key: entity_id.to_string(),
        occurred_at: Utc::now(),
        broker_envelope,
    }
}

/// Whose access decides who may see one trigger event.
///
/// Not the bot the event names: that is what a subscriber filters on, and a
/// bot is not an entity anyone holds access to.
pub(crate) enum TriggerAudience {
    /// Whoever currently holds access to an entity.
    Entity {
        entity_id: String,
        entity_type: EntityType,
    },
    /// Named people, when nothing was posted anywhere to hold access to.
    People(Vec<MacroUserIdStr<'static>>),
}

impl TriggerAudience {
    /// Whoever may currently read the conversation's parent.
    fn parent(parent: &MessageParent) -> Self {
        Self::Entity {
            entity_id: parent.entity_id(),
            entity_type: parent.access_entity_type(),
        }
    }

    /// The one person who asked for a session from the composer: nothing was
    /// posted, so nobody else's access is in question. Their runtime, or
    /// their team's, is who serves it.
    fn requester(owner: &str) -> Result<Self, WebhookEventIngestionError> {
        let owner = MacroUserIdStr::try_from(owner.to_owned()).map_err(|_| {
            WebhookEventIngestionError::InvalidEntityId {
                entity_type: "user",
                entity_id: owner.to_owned(),
            }
        })?;
        Ok(Self::People(vec![owner]))
    }
}

/// Normalize one agent-trigger event.
///
/// The entity - and the ordering key, mirroring the broker's partitioning -
/// is the bot: a subscriber consumes a bot's whole trigger stream, in order.
/// Returned alongside is whose access gates it, which differs by shape.
///
/// Every message trigger includes parent content, so delivery rechecks access to
/// that parent, including follow-ups to a session with independently shared access.
pub(crate) fn normalized_agent_trigger_event(
    event: &Event<AgentTriggerTopicEvent>,
) -> Result<(NormalizedWebhookEvent, TriggerAudience), WebhookEventIngestionError> {
    use agent_trigger::domain::broker_events::AgentTriggerEventName;

    let (bot_id, audience) = match &event.event {
        AgentTriggerTopicEvent::New(
            agent_trigger::domain::broker_events::NewAgentSessionEvent::AssignedToTask(assigned),
        ) => Some((assigned.bot_id, TriggerAudience::parent(&assigned.parent))),
        AgentTriggerTopicEvent::New(new) => match (new.mention(), new.requested()) {
            (Some(mention), _) => Some((
                mention.bot_id,
                TriggerAudience::parent(&mention.message.parent),
            )),
            (None, Some(requested)) => Some((
                requested.bot_id,
                TriggerAudience::requester(&requested.owner)?,
            )),
            (None, None) => None,
        },
        AgentTriggerTopicEvent::Existing(existing) => existing.session_message().map(|message| {
            (
                message.bot_id,
                TriggerAudience::parent(&message.message.parent),
            )
        }),
    }
    // Both trigger enums are non-exhaustive on purpose; an unknown shape
    // has no bot to route to. Permanent, so the consumer skips it.
    .ok_or_else(|| WebhookEventIngestionError::InvalidEntityId {
        entity_type: "bot",
        entity_id: "unrecognized agent-trigger event shape".to_owned(),
    })?;
    let event_name: &'static str = AgentTriggerEventName::from(&event.event).into();
    let broker_envelope = serde_json::to_value(event)?;
    let bot_id = bot_id.to_string();
    Ok((
        normalized_event(
            event.event_id,
            event.schema_version,
            event_name,
            "bot",
            &bot_id,
            broker_envelope,
        ),
        audience,
    ))
}

/// Normalize one agent-session lifecycle event.
///
/// Unlike a trigger, whose entity is the bot, a lifecycle stream is about one
/// session: the entity and the ordering key are the session, mirroring the
/// broker's partition key, and the session's own grants - its owner and the
/// channel it came from - decide who may see it.
pub(crate) fn normalized_agent_session_lifecycle_event(
    event: &Event<AgentSessionLifecycleEvent>,
) -> Result<NormalizedWebhookEvent, WebhookEventIngestionError> {
    let event_name: &'static str = AgentSessionLifecycleEventName::from(&event.event).into();
    let broker_envelope = serde_json::to_value(event)?;
    let session_id = event.event.session_id().to_string();
    Ok(normalized_event(
        event.event_id,
        event.schema_version,
        event_name,
        AGENT_SESSION_ENTITY_TYPE,
        &session_id,
        broker_envelope,
    ))
}

/// Whose access gates one lifecycle event.
///
/// A live session carries its own grants. A deleted one does not: its access
/// rows go with the row, so asking who may see the session answers nobody.
/// The event itself still knows who the session belonged to, and that is the
/// audience the last fact about it is delivered to.
pub(crate) enum LifecycleAudience {
    /// Everyone with access to the session.
    Session,
    /// The session is gone: its owner, plus the channel or document it was
    /// opened from.
    Departed {
        owner: MacroUserIdStr<'static>,
        origin_parent: Option<MessageParent>,
    },
}

pub(crate) fn lifecycle_audience(event: &AgentSessionLifecycleEvent) -> LifecycleAudience {
    match event {
        AgentSessionLifecycleEvent::Deleted(deleted) => LifecycleAudience::Departed {
            owner: deleted.identity.owner_id.clone(),
            origin_parent: deleted
                .identity
                .origin
                .as_ref()
                .map(|origin| origin.parent.clone()),
        },
        AgentSessionLifecycleEvent::Opened(_)
        | AgentSessionLifecycleEvent::TurnStarted(_)
        | AgentSessionLifecycleEvent::TurnEnded(_)
        | AgentSessionLifecycleEvent::CommandRejected(_)
        | AgentSessionLifecycleEvent::Settled(_)
        | AgentSessionLifecycleEvent::WaitingForInput(_)
        | AgentSessionLifecycleEvent::InputReceived(_)
        | AgentSessionLifecycleEvent::Mentioned(_)
        | AgentSessionLifecycleEvent::Stopped(_)
        | AgentSessionLifecycleEvent::Renamed(_) => LifecycleAudience::Session,
    }
}

impl<A, R, Q> WebhookEventIngestionService for WebhookEventIngestionServiceImpl<A, R, Q>
where
    A: EntityAccessService,
    R: WebhookRepo + WebhookWorkspaceResolver,
    Q: WebhookEventEnqueuer,
{
    #[tracing::instrument(skip(self, event), fields(event_id = %event.event_id), err)]
    async fn ingest_document_event(
        &self,
        event: Event<DocumentTopicEvent>,
    ) -> Result<(), WebhookEventIngestionError> {
        let Some(event) = normalized_document_event(&event)? else {
            return Ok(());
        };
        self.resolve_entity_access_and_enqueue(event, EntityType::Document)
            .await
    }

    #[tracing::instrument(skip(self, event), fields(event_id = %event.event_id), err)]
    async fn ingest_channel_event(
        &self,
        event: Event<ChannelTopicEvent>,
    ) -> Result<(), WebhookEventIngestionError> {
        let event = normalized_channel_event(&event)?;
        self.resolve_entity_access_and_enqueue(event, EntityType::Channel)
            .await
    }

    #[tracing::instrument(skip(self, event), fields(event_id = %event.event_id), err)]
    async fn ingest_call_notification_event(
        &self,
        event: Event<CallNotificationEvent>,
    ) -> Result<(), WebhookEventIngestionError> {
        let (normalized, recipient) = normalized_call_notification_event(&event)?;
        match recipient {
            Some(recipient) => {
                // The recipient is the grant for a private notification.
                // In particular, an invitation precedes call entity access.
                self.match_and_enqueue(normalized, vec![recipient]).await
            }
            None => {
                let accessors = self
                    .users_with_access(&normalized.entity_id, EntityType::Call)
                    .await?;
                let workspace_ids = self
                    .repository
                    .resolve_workspace_ids(accessors)
                    .await
                    .map_err(|error| {
                        WebhookEventIngestionError::WorkspaceResolution(error.into())
                    })?;
                self.match_and_enqueue(normalized, workspace_ids).await
            }
        }
    }

    #[tracing::instrument(skip(self, event), fields(event_id = %event.event_id), err)]
    async fn ingest_message_event(
        &self,
        event: Event<MessageTopicEvent>,
    ) -> Result<(), WebhookEventIngestionError> {
        let (event, entity_type) = normalized_message_event(&event)?;
        self.resolve_entity_access_and_enqueue(event, entity_type)
            .await
    }

    #[tracing::instrument(skip(self, event), fields(event_id = %event.event_id), err)]
    async fn ingest_webhook_event(
        &self,
        event: Event<WebhookTopicEvent>,
    ) -> Result<(), WebhookEventIngestionError> {
        let (event, workspace_id) = normalized_webhook_event(&event)?;
        self.match_and_enqueue(event, vec![workspace_id]).await
    }

    #[tracing::instrument(skip(self, event), fields(event_id = %event.event_id), err)]
    async fn ingest_agent_trigger_event(
        &self,
        event: Event<AgentTriggerTopicEvent>,
    ) -> Result<(), WebhookEventIngestionError> {
        let (event, audience) = normalized_agent_trigger_event(&event)?;
        let accessors = match audience {
            TriggerAudience::Entity {
                entity_id,
                entity_type,
            } => self.users_with_access(&entity_id, entity_type).await?,
            TriggerAudience::People(people) => people,
        };
        let workspace_ids = self
            .repository
            .resolve_workspace_ids(accessors)
            .await
            .map_err(|error| WebhookEventIngestionError::WorkspaceResolution(error.into()))?;
        self.match_and_enqueue(event, workspace_ids).await
    }

    #[tracing::instrument(skip(self, event), fields(event_id = %event.event_id), err)]
    async fn ingest_agent_session_lifecycle_event(
        &self,
        event: Event<AgentSessionLifecycleEvent>,
    ) -> Result<(), WebhookEventIngestionError> {
        let normalized = normalized_agent_session_lifecycle_event(&event)?;
        match lifecycle_audience(&event.event) {
            LifecycleAudience::Session => {
                self.resolve_entity_access_and_enqueue(normalized, EntityType::AgentSession)
                    .await
            }
            LifecycleAudience::Departed {
                owner,
                origin_parent,
            } => {
                let mut accessors = vec![owner];
                if let Some(parent) = origin_parent {
                    accessors.extend(
                        self.users_with_access(&parent.entity_id(), parent.access_entity_type())
                            .await?,
                    );
                }
                let workspace_ids = self
                    .repository
                    .resolve_workspace_ids(accessors)
                    .await
                    .map_err(|error| {
                        WebhookEventIngestionError::WorkspaceResolution(error.into())
                    })?;
                self.match_and_enqueue(normalized, workspace_ids).await
            }
        }
    }
}