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.

34.9 KB
Raw Blame
//! Pure data model for the import pipeline: sources, statuses, per-source
//! metadata shapes, and foreign-id normalization. Everything here is
//! side-effect free.

use chrono::{DateTime, Utc};
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use utoipa::ToSchema;
use uuid::Uuid;

mod notion_run;
mod notion_sharing;
pub use notion_run::{
    AdoptedRun, NotionJob, ReviewedRun, RunReview, TEAMMATE_STOPPED, TeamClaim, WrittenKind,
    WrittenObject,
};

pub use notion_sharing::{
    NotionAlreadyImported, NotionImporter, NotionSharing, NotionWriteChoices,
};

#[cfg(test)]
mod test;

/// External systems items can be imported from.
#[derive(
    Debug,
    Clone,
    Copy,
    PartialEq,
    Eq,
    Hash,
    Serialize,
    Deserialize,
    JsonSchema,
    ToSchema,
    strum::EnumString,
    strum::AsRefStr,
    strum::EnumIter,
)]
#[serde(rename_all = "snake_case")]
#[strum(serialize_all = "snake_case")]
pub enum ImportSource {
    /// Linear issues, imported as Macro tasks.
    Linear,
    /// Jira Cloud issues and projects.
    Jira,
    /// Notion pages, imported as Macro markdown documents.
    Notion,
    /// Slack channels, recreated as Macro channels.
    Slack,
}

impl ImportSource {
    /// Display name of the connected provider.
    pub fn label(self) -> &'static str {
        match self {
            Self::Linear => "Linear",
            Self::Jira => "Jira",
            Self::Notion => "Notion",
            Self::Slack => "Slack",
        }
    }

    /// All import sources.
    pub fn all() -> [ImportSource; 4] {
        [
            ImportSource::Linear,
            ImportSource::Jira,
            ImportSource::Notion,
            ImportSource::Slack,
        ]
    }

    /// The Pipedream app slugs backing this source's connector, in preference order.
    pub fn pipedream_app_slugs(self) -> &'static [&'static str] {
        match self {
            ImportSource::Linear => &["linear"],
            ImportSource::Jira => &["jira"],
            ImportSource::Notion => &["notion"],
            // Keep the canonical fallback from docs/runbooks/slack-live-channel-import.md
            // until live verification supports switching to `slack_v2`.
            ImportSource::Slack => &["slack", "slack_v2"],
        }
    }

    /// This source's connector on both MCP stacks.
    pub fn connector_ref(self) -> mcp_select::ConnectorRef<'static> {
        mcp_select::ConnectorRef {
            pipedream_app_slugs: self.pipedream_app_slugs(),
            native_server_url: self.mcp_server_url(),
        }
    }

    /// The MCP server URL backing this source's connector.
    pub fn mcp_server_url(self) -> &'static str {
        match self {
            ImportSource::Linear => "https://mcp.linear.app/mcp",
            ImportSource::Jira => "https://mcp.atlassian.com/v1/mcp",
            ImportSource::Notion => "https://mcp.notion.com/mcp",
            ImportSource::Slack => "https://mcp.slack.com/mcp",
        }
    }

    /// The kind of item this source's current import paths stage: Linear
    /// issues, Notion pages, and Slack channels.
    pub fn default_kind(self) -> ImportKind {
        match self {
            ImportSource::Linear => ImportKind::Issue,
            ImportSource::Jira => ImportKind::JiraIssue,
            ImportSource::Notion => ImportKind::Page,
            ImportSource::Slack => ImportKind::Channel,
        }
    }

    /// The Macro entity type items from this source become. The mapping is
    /// fixed — importers have latitude on content, never on shape.
    pub fn entity_type(self) -> &'static str {
        match self {
            ImportSource::Linear | ImportSource::Jira => "task",
            ImportSource::Notion => "md",
            ImportSource::Slack => "channel",
        }
    }

    /// Normalize a raw foreign id for this source: trimmed, with
    /// source-specific canonicalization (Notion URLs collapse to the 32-hex
    /// page id, Slack names keep a single leading `#`). `None` when the raw
    /// id is empty.
    pub fn normalize_foreign_id(self, raw: &str) -> Option<String> {
        let raw = raw.trim();
        if raw.is_empty() {
            return None;
        }
        Some(match self {
            ImportSource::Linear | ImportSource::Jira => raw.to_string(),
            // Page ids survive renames; URLs don't. Accept either and store
            // the id whenever one is present.
            ImportSource::Notion => notion_page_id(raw).unwrap_or_else(|| raw.to_string()),
            ImportSource::Slack => {
                // Slack channel ids (`C0123ABCD…`) pass through; a bare or
                // `#`-prefixed name normalizes to `#name`.
                if raw.starts_with('C')
                    && raw.len() >= 9
                    && raw.chars().all(|c| c.is_ascii_alphanumeric())
                {
                    raw.to_string()
                } else {
                    format!("#{}", raw.trim_start_matches('#'))
                }
            }
        })
    }
}

/// What an imported item is in its source system. Each source has its own
/// kinds; a Notion database and a Notion page, or a Linear project and a
/// Linear issue, are tracked and deduplicated separately.
#[derive(
    Debug,
    Clone,
    Copy,
    PartialEq,
    Eq,
    Serialize,
    Deserialize,
    JsonSchema,
    specta::Type,
    ToSchema,
    strum::EnumString,
    strum::AsRefStr,
)]
#[serde(rename_all = "snake_case")]
#[strum(serialize_all = "snake_case")]
pub enum ImportKind {
    /// A Linear issue.
    Issue,
    /// A Linear project.
    Project,
    /// A Linear document.
    Document,
    /// A Notion page.
    Page,
    /// A Notion database.
    Database,
    /// One data source (table) of a Notion database.
    DataSource,
    /// One row of a Notion data source.
    Row,
    /// A Jira issue.
    JiraIssue,
    /// A Jira project.
    JiraProject,
    /// A Jira epic grouping.
    JiraEpic,
    /// A Slack channel.
    Channel,
}

impl ImportKind {
    /// The source this kind of item comes from.
    pub fn source(self) -> ImportSource {
        match self {
            ImportKind::Issue | ImportKind::Project | ImportKind::Document => ImportSource::Linear,
            ImportKind::Page | ImportKind::Database | ImportKind::DataSource | ImportKind::Row => {
                ImportSource::Notion
            }
            ImportKind::JiraIssue | ImportKind::JiraProject | ImportKind::JiraEpic => {
                ImportSource::Jira
            }
            ImportKind::Channel => ImportSource::Slack,
        }
    }
}

/// Lifecycle of one import entity.
#[derive(
    Debug,
    Clone,
    Copy,
    PartialEq,
    Eq,
    Serialize,
    Deserialize,
    JsonSchema,
    ToSchema,
    strum::EnumString,
    strum::AsRefStr,
)]
#[serde(rename_all = "snake_case")]
#[strum(serialize_all = "snake_case")]
pub enum ImportStatus {
    /// Discovered and offered, not yet accepted.
    Staged,
    /// Accepted; an import job is copying it in.
    Importing,
    /// A Macro entity exists for it (`entity_id`/`entity_type` are set).
    Imported,
    /// The user declined it. Remembered so later discovery doesn't re-stage it.
    Discarded,
}

/// Where an import entity was first staged from. Provenance only — never a
/// visibility filter.
#[derive(
    Debug,
    Clone,
    Copy,
    PartialEq,
    Eq,
    Serialize,
    Deserialize,
    JsonSchema,
    ToSchema,
    strum::EnumString,
    strum::AsRefStr,
)]
#[serde(rename_all = "snake_case")]
#[strum(serialize_all = "snake_case")]
pub enum Initiator {
    /// Legacy: staged by the removed onboarding gather. No longer written.
    Onboarding,
    /// Staged by an AI chat session.
    Chat,
    /// Imported from an administrator-uploaded archive.
    Archive,
    /// Staged by the user from Settings (the pick-channels flow).
    Manual,
}

/// Lifecycle of a discovery run (one per user × source).
#[derive(
    Debug,
    Clone,
    Copy,
    PartialEq,
    Eq,
    Serialize,
    Deserialize,
    ToSchema,
    JsonSchema,
    specta::Type,
    strum::EnumString,
    strum::AsRefStr,
)]
#[serde(rename_all = "snake_case")]
#[strum(serialize_all = "snake_case")]
pub enum RunStatus {
    /// Slack discovery is staging candidates, or a Notion workspace import is
    /// being planned.
    Running,
    /// Discovery or planning finished; staged rows (if any) are ready.
    Ready,
    /// An approved Notion workspace import plan is being written.
    Importing,
    /// A Notion workspace import finished writing; `error` notes objects
    /// that could not be imported.
    Completed,
    /// Discovery, planning or writing failed; `error` has details. Retryable.
    Failed,
    /// A Notion workspace import was cancelled. Older rows may hold it from
    /// the removed onboarding import, where it meant a dismissed section.
    Dismissed,
}

/// A stable Slack conversation ID, never a legacy channel name.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct SlackConversationId(String);

impl SlackConversationId {
    /// Validate the source ID without trimming or name normalization.
    pub fn new(value: &str) -> Option<Self> {
        valid_slack_id(value, b"CGD").then(|| Self(value.to_owned()))
    }

    /// The exact source identifier.
    pub fn as_str(&self) -> &str {
        &self.0
    }
}

/// A stable Slack user ID.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct SlackUserId(String);

impl SlackUserId {
    /// Validate the source ID without trimming or name normalization.
    pub fn new(value: &str) -> Option<Self> {
        valid_slack_id(value, b"UW").then(|| Self(value.to_owned()))
    }

    /// The exact source identifier.
    pub fn as_str(&self) -> &str {
        &self.0
    }
}

/// The kind of conversation reported by Slack.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum SlackConversationKind {
    /// A public workspace channel.
    PublicChannel,
    /// An invite-only workspace channel.
    PrivateChannel,
    /// A one-to-one direct message.
    DirectMessage,
    /// A multi-person direct message.
    GroupDirectMessage,
}

/// A conversation read from a live Slack workspace.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SlackConversation {
    /// Stable source identity.
    pub id: SlackConversationId,
    /// Conversation name.
    pub name: String,
    /// Source conversation kind, independent of the Macro target kind.
    pub kind: SlackConversationKind,
    /// Whether Slack has archived this conversation.
    pub archived: bool,
    /// Member count reported by Slack, when available.
    pub member_count: Option<u64>,
    /// Conversation purpose, when set.
    pub purpose: Option<String>,
}

/// One page of live Slack conversations.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SlackConversationPage {
    /// Conversations on this page.
    pub conversations: Vec<SlackConversation>,
    /// Opaque continuation cursor; `None` means the final page.
    pub next_cursor: Option<String>,
}

/// One page of a live Slack conversation's members.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SlackMemberPage {
    /// Slack user IDs on this page.
    pub members: Vec<SlackUserId>,
    /// Opaque continuation cursor; `None` means the final page.
    pub next_cursor: Option<String>,
}

/// A user read from a live Slack workspace.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SlackUser {
    /// Stable source identity.
    pub id: SlackUserId,
    /// Display name reported by Slack.
    pub display_name: String,
    /// Email, when the workspace exposes it.
    pub email: Option<String>,
    /// Whether this user is a bot.
    pub is_bot: bool,
    /// Whether this user has been deactivated.
    pub deleted: bool,
}

/// One page of live Slack users.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SlackUserPage {
    /// Users on this page.
    pub users: Vec<SlackUser>,
    /// Opaque continuation cursor; `None` means the final page.
    pub next_cursor: Option<String>,
}

/// A stable Slack workspace ID.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SlackWorkspaceId(String);

impl SlackWorkspaceId {
    /// Validate a Slack workspace ID.
    pub fn new(value: &str) -> Option<Self> {
        valid_slack_id(value, b"T").then(|| Self(value.to_owned()))
    }

    /// The exact source identifier.
    pub fn as_str(&self) -> &str {
        &self.0
    }
}

fn valid_slack_id(value: &str, prefixes: &[u8]) -> bool {
    (2..=64).contains(&value.len())
        && prefixes.contains(&value.as_bytes()[0])
        && value
            .bytes()
            .all(|byte| byte.is_ascii_uppercase() || byte.is_ascii_digit())
}

/// Durable single-workspace binding for a Macro team. Absence of this row means unbound.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ImportSourceBinding {
    /// Known workspace, if the source supplied identity.
    pub workspace_id: Option<SlackWorkspaceId>,
    /// First explicit administrator confirmation of an unidentified archive.
    pub confirmed_unknown_at: Option<DateTime<Utc>>,
}

/// Explicit canonical namespace. This API supports only the Slack source in v1;
/// it never derives the team from the requesting user's current membership.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ImportTargetKey {
    /// Team that owns the source namespace, including private/DM provenance.
    pub team_id: Uuid,
    /// Stable source identity, not a name-only onboarding identifier.
    pub foreign_id: SlackConversationId,
}

/// Allowed target shapes. Slack public channels become Team, never Public.
#[derive(Debug, Clone, Copy, PartialEq, Eq, strum::AsRefStr)]
#[strum(serialize_all = "snake_case")]
pub enum ImportTargetKind {
    /// Shared with exactly the explicitly supplied team.
    Team,
    /// Private channel or group DM; team provenance lives only in the reservation.
    Private,
    /// Two-person DM; pair validation/authorization belongs to the channel service.
    DirectMessage,
}

/// A committed reservation survives crashes before channel creation.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ImportTargetReservation {
    /// Canonical source namespace.
    pub key: ImportTargetKey,
    /// Stable UUID to pass to idempotent channel creation, or an existing claimed target.
    pub channel_id: Uuid,
    /// Whether channel creation has been durably completed.
    pub ready: bool,
}

/// Maximum exact source IDs per canonical read; validated IDs bound input bytes
/// to 32 KiB, below the archive database batch byte ceiling.
pub const MAX_TARGET_LOOKUP: usize = 500;

/// Read-only canonical mapping state. Pending candidates are deliberately hidden.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ImportTargetLookup {
    /// No unambiguous, compatible target exists.
    Missing,
    /// Creation has not durably completed.
    Pending,
    /// Existing compatible channel; provenance is not a read-access grant.
    Ready {
        /// Canonical channel identity.
        channel_id: Uuid,
        /// Persisted channel kind.
        kind: ImportTargetKind,
        /// Persisted name, disclose only after authorization.
        name: String,
    },
}

// ---------------------------------------------------------------------------
// Per-source metadata
// ---------------------------------------------------------------------------

/// Caps applied to metadata text at the tool write boundary, so a chatty
/// agent can't bloat rows.
const MAX_TEXT: usize = 300;
/// Cap for long-form text (issue descriptions).
const MAX_LONG_TEXT: usize = 4_000;
/// Cap for summaries and purposes.
const MAX_SUMMARY: usize = 600;
/// Cap on matched Slack participants, bounded by Macro team size, not channel size.
const MAX_PARTICIPANTS: usize = 100;

/// Truncate to a character boundary at most `max` bytes in.
fn truncated(s: String, max: usize) -> String {
    if s.len() <= max {
        return s;
    }
    let mut end = max;
    while end > 0 && !s.is_char_boundary(end) {
        end -= 1;
    }
    let mut s = s;
    s.truncate(end);
    s
}

fn truncate_opt(s: Option<String>, max: usize) -> Option<String> {
    s.map(|s| truncated(s, max))
        .filter(|s| !s.trim().is_empty())
}

/// Metadata for one staged Linear issue.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema, ToSchema)]
pub struct LinearIssueMeta {
    /// Linear's human identifier (e.g. `ENG-142`).
    pub identifier: Option<String>,
    /// Issue title.
    pub title: String,
    /// Short markdown description.
    pub description: Option<String>,
    /// Workflow status name (e.g. `In Progress`).
    pub status: Option<String>,
    /// Priority label (e.g. `Urgent`).
    pub priority: Option<String>,
    /// Assignee display name as Linear reports it.
    pub assignee: Option<String>,
    /// Assignee email, when Linear exposes it.
    pub assignee_email: Option<String>,
    /// Due date as an ISO date (`YYYY-MM-DD`), when set.
    #[serde(default)]
    pub due_date: Option<String>,
    /// Deep link back to the issue in Linear.
    pub url: Option<String>,
}

impl LinearIssueMeta {
    fn capped(self) -> Self {
        Self {
            identifier: truncate_opt(self.identifier, MAX_TEXT),
            title: truncated(self.title, MAX_TEXT),
            description: truncate_opt(self.description, MAX_LONG_TEXT),
            status: truncate_opt(self.status, MAX_TEXT),
            priority: truncate_opt(self.priority, MAX_TEXT),
            assignee: truncate_opt(self.assignee, MAX_TEXT),
            assignee_email: truncate_opt(self.assignee_email, MAX_TEXT),
            due_date: truncate_opt(self.due_date, MAX_TEXT),
            url: truncate_opt(self.url, MAX_TEXT),
        }
    }
}

/// Metadata for one staged Notion page. Deliberately has NO content field:
/// page bodies are fetched at import time, for accepted pages only.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema, ToSchema)]
pub struct NotionDocMeta {
    /// Page title.
    pub title: String,
    /// Deep link back to the page in Notion.
    pub url: Option<String>,
    /// One-line summary of what the page contains.
    pub summary: Option<String>,
    /// Where this object sits in a workspace import plan; absent for pages
    /// staged one at a time. Written by the workspace import, never by a
    /// model, so it is left out of the tool schema.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    #[schemars(skip)]
    pub plan: Option<NotionPlanItem>,
}

impl NotionDocMeta {
    /// Metadata for one object of a workspace import plan, capped like
    /// everything else the ledger stores.
    pub fn for_plan(title: String, url: String, plan: NotionPlanItem) -> Self {
        Self {
            title,
            url: Some(url),
            summary: None,
            plan: Some(plan),
        }
        .capped()
    }

    fn capped(self) -> Self {
        Self {
            title: truncated(self.title, MAX_TEXT),
            url: truncate_opt(self.url, MAX_TEXT),
            summary: truncate_opt(self.summary, MAX_SUMMARY),
            plan: self.plan.map(NotionPlanItem::capped),
        }
    }
}

/// What a workspace import does with one Notion object.
#[derive(
    Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema, ToSchema, strum::Display,
)]
#[serde(rename_all = "snake_case")]
#[strum(serialize_all = "snake_case")]
pub enum NotionDecision {
    /// Bring it over as it is: a page becomes a document, a data source a
    /// database.
    Copy,
    /// A data source that is really a task list: its rows become Macro tasks.
    Tasks,
    /// Leave it in Notion.
    Skip,
    /// Needs judgment the import cannot make; the agent handles it by hand.
    Hand,
}

/// Which Notion columns hold a task list's task fields, by property name.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema, ToSchema)]
#[serde(rename_all = "camelCase")]
pub struct NotionTaskFields {
    /// The status column.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub status: Option<String>,
    /// The priority column.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub priority: Option<String>,
    /// The due date column.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub due: Option<String>,
    /// The assignee column.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub assignee: Option<String>,
}

/// One object's place in a workspace import plan.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema, ToSchema)]
#[serde(rename_all = "camelCase")]
pub struct NotionPlanItem {
    /// What the import does with it; absent while planning has staged the
    /// object but the decision model has not answered for it yet.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub decision: Option<NotionDecision>,
    /// Why, in a short sentence, when the decision model gave one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub reason: Option<String>,
    /// Titles of the pages above it, outermost first.
    #[serde(default)]
    pub path: Vec<String>,
    /// For a data source: rows counted while planning.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub rows: Option<u32>,
    /// For a data source: the titles of a few of its rows.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub sample_titles: Vec<String>,
    /// For a task list: which columns hold the task fields.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub task_fields: Option<NotionTaskFields>,
    /// Whether what it becomes is shared with the user's team.
    #[serde(default)]
    pub shared: bool,
    /// Why it is (or is not) shared, when the decision model chose or the
    /// import could not share it.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub shared_reason: Option<String>,
    /// Whether the user may change `shared`: false for users without a team.
    #[serde(default)]
    pub shareable: bool,
    /// A teammate's copy shared with the team, which this object links to
    /// instead of being imported again.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub already_imported: Option<NotionAlreadyImported>,
}

impl NotionPlanItem {
    fn capped(self) -> Self {
        Self {
            reason: truncate_opt(self.reason, MAX_SUMMARY),
            shared_reason: truncate_opt(self.shared_reason, MAX_SUMMARY),
            already_imported: self.already_imported.map(|copy| NotionAlreadyImported {
                by: truncated(copy.by, MAX_TEXT),
                ..copy
            }),
            path: self
                .path
                .into_iter()
                .take(MAX_PLAN_DEPTH)
                .map(|title| truncated(title, MAX_TEXT))
                .collect(),
            sample_titles: self
                .sample_titles
                .into_iter()
                .take(MAX_SAMPLE_TITLES)
                .map(|title| truncated(title, MAX_TEXT))
                .collect(),
            ..self
        }
    }
}

/// Row titles a plan item keeps for a data source.
const MAX_SAMPLE_TITLES: usize = 5;

/// Deepest ancestor path a plan item records.
const MAX_PLAN_DEPTH: usize = 12;

/// A person active in a staged Slack channel.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema, ToSchema)]
pub struct SlackParticipant {
    /// Display name or Slack handle.
    pub name: String,
    /// Email, when the workspace exposes it.
    pub email: Option<String>,
}

/// Metadata for one staged Slack channel.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema, ToSchema)]
pub struct SlackChannelMeta {
    /// Channel name without the leading `#`.
    pub name: String,
    /// Slack's channel id (e.g. `C0123456789`), stable across renames.
    pub channel_id: Option<String>,
    /// The channel's purpose/topic, when set.
    pub purpose: Option<String>,
    /// Slack members matched to the Macro team roster when discovery resolved membership.
    #[serde(default)]
    pub participants: Vec<SlackParticipant>,
    /// Total human members in the Slack channel.
    #[serde(default)]
    pub member_count: Option<u64>,
    /// Whether Slack has archived this channel.
    #[serde(default)]
    pub archived: bool,
    /// Whether `participants` reflects a live membership read.
    #[serde(default)]
    pub members_resolved: bool,
}

impl SlackChannelMeta {
    fn capped(self) -> Self {
        Self {
            name: truncated(self.name, MAX_TEXT),
            channel_id: truncate_opt(self.channel_id, MAX_TEXT),
            purpose: truncate_opt(self.purpose, MAX_SUMMARY),
            participants: self
                .participants
                .into_iter()
                .take(MAX_PARTICIPANTS)
                .map(|p| SlackParticipant {
                    name: truncated(p.name, MAX_TEXT),
                    email: truncate_opt(p.email, MAX_TEXT),
                })
                .collect(),
            member_count: self.member_count,
            archived: self.archived,
            members_resolved: self.members_resolved,
        }
    }
}

/// Validate raw metadata against `source`'s shape and re-serialize it with
/// caps applied. Unknown fields are dropped; missing required fields error.
pub fn validate_metadata(
    source: ImportSource,
    metadata: serde_json::Value,
) -> Result<serde_json::Value, serde_json::Error> {
    match source {
        ImportSource::Linear | ImportSource::Jira => {
            serde_json::to_value(serde_json::from_value::<LinearIssueMeta>(metadata)?.capped())
        }
        ImportSource::Notion => {
            serde_json::to_value(serde_json::from_value::<NotionDocMeta>(metadata)?.capped())
        }
        ImportSource::Slack => {
            serde_json::to_value(serde_json::from_value::<SlackChannelMeta>(metadata)?.capped())
        }
    }
}

/// A human label for an entity, pulled from its metadata (for logs, agent
/// prompts, and tool responses).
pub fn metadata_label(source: ImportSource, metadata: &serde_json::Value) -> String {
    let field = match source {
        ImportSource::Linear | ImportSource::Jira | ImportSource::Notion => "title",
        ImportSource::Slack => "name",
    };
    metadata
        .get(field)
        .and_then(|v| v.as_str())
        .map(str::trim)
        .filter(|label| !label.is_empty())
        .unwrap_or("(unnamed)")
        .to_string()
}

/// Extract the Notion page id from a page URL: the trailing 32-hex token
/// (with or without UUID dashes), normalized to undashed lowercase.
fn notion_page_id(url: &str) -> Option<String> {
    let path = url.split(['?', '#']).next().unwrap_or(url);
    let segment = path.trim_end_matches('/').rsplit('/').next()?;
    let is_hex = |s: &str| !s.is_empty() && s.chars().all(|c| c.is_ascii_hexdigit());

    // Undashed form: the whole segment, or the slug's last `-` token
    // (`Page-Title-<32hex>`).
    let tail = segment.rsplit('-').next().unwrap_or(segment);
    if tail.len() == 32 && is_hex(tail) {
        return Some(tail.to_lowercase());
    }

    // Dashed UUID form at the end of the segment (`…-8-4-4-4-12`).
    let candidate = segment.get(segment.len().checked_sub(36)?..)?;
    let dashes_ok = [8, 13, 18, 23]
        .iter()
        .all(|&i| candidate.as_bytes().get(i) == Some(&b'-'));
    let undashed: String = candidate.chars().filter(|c| *c != '-').collect();
    (dashes_ok && undashed.len() == 32 && is_hex(&undashed)).then(|| undashed.to_lowercase())
}

// ---------------------------------------------------------------------------
// Rows and aggregates
// ---------------------------------------------------------------------------

/// One row of the import ledger.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, ToSchema)]
pub struct ImportEntity {
    /// Ledger row id.
    pub id: Uuid,
    /// The user who staged/imported it. Team-imported rows from teammates
    /// are visible with their owner's id, so clients can say "created by a
    /// teammate".
    pub user_id: String,
    /// The team the created entity was shared with, when it was.
    pub team_id: Option<Uuid>,
    /// The external system the item comes from.
    pub source: ImportSource,
    /// What the item is in its source system.
    pub kind: ImportKind,
    /// Stable id in the source system (see
    /// [`ImportSource::normalize_foreign_id`]).
    pub foreign_id: String,
    /// The import row this item was imported under (a subpage's parent page,
    /// a row's database), when it was imported as part of a tree.
    pub parent_id: Option<Uuid>,
    /// The agent session review that approved importing this item, when it
    /// came from one.
    pub review_id: Option<Uuid>,
    /// Where the row is in its lifecycle.
    pub status: ImportStatus,
    /// Where it was first staged from.
    pub initiator: Initiator,
    /// Per-source metadata (shape depends on `source`; see
    /// [`LinearIssueMeta`], [`NotionDocMeta`], [`SlackChannelMeta`]).
    pub metadata: serde_json::Value,
    /// The Macro entity it became, once imported.
    pub entity_id: Option<String>,
    /// The Macro entity type (`task` | `md` | `channel`), once imported.
    pub entity_type: Option<String>,
    /// Failure detail from the last import attempt, when one failed.
    pub last_error: Option<String>,
    /// The teammate's row this one waits on: that teammate is writing the
    /// same object for the team, and this row links to their copy once it
    /// is imported.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub waiting_on: Option<Uuid>,
    /// When the row was first staged.
    pub created_at: DateTime<Utc>,
    /// When the row last changed.
    pub updated_at: DateTime<Utc>,
}

/// Discovery-run state for one user × source.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, ToSchema)]
pub struct ImportRun {
    /// The source this run discovered from.
    pub source: ImportSource,
    /// Where the run is in its lifecycle.
    pub status: RunStatus,
    /// Discovery failure detail, when the run failed.
    pub error: Option<String>,
    /// When the run state last changed.
    pub updated_at: DateTime<Utc>,
    /// What the run has found in the source so far, while it is `running`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub scanned: Option<ScanCounts>,
    /// The review presenting the run's plan, once one does. A Notion plan is
    /// presented while it is still `running`; rows staged after that take it.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub review_id: Option<Uuid>,
}

/// What a planning run has found in the source so far.
#[derive(
    Debug,
    Clone,
    Copy,
    Default,
    PartialEq,
    Eq,
    Serialize,
    Deserialize,
    JsonSchema,
    specta::Type,
    ToSchema,
)]
#[serde(rename_all = "camelCase")]
pub struct ScanCounts {
    /// Pages found.
    pub pages: u32,
    /// Data sources (database tables) found.
    pub data_sources: u32,
}

/// The full import aggregate for a user: discovery runs plus visible ledger
/// rows (their own, and teammates' team-imported rows).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, ToSchema)]
pub struct ImportState {
    /// Discovery runs, one per source that ever ran discovery.
    pub runs: Vec<ImportRun>,
    /// Visible import entities, newest first.
    pub entities: Vec<ImportEntity>,
}

/// One object a workspace import report calls out.
#[derive(
    Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema, specta::Type, ToSchema,
)]
#[serde(rename_all = "camelCase")]
pub struct NotionReportItem {
    /// The ledger row.
    pub import_id: Uuid,
    /// The object's title.
    pub title: String,
    /// What the object is.
    pub kind: ImportKind,
    /// Its Notion URL.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub url: Option<String>,
    /// Why it is called out: the decision model's reason, or the failure.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub reason: Option<String>,
}

/// Where a Notion workspace import stands.
#[derive(
    Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema, specta::Type, ToSchema,
)]
#[serde(rename_all = "camelCase")]
pub struct NotionImportReport {
    /// Provider items skipped because they were unreadable, or optional features unavailable.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub warnings: Vec<String>,
    /// Tracker issues in the plan.
    #[serde(default)]
    pub issues: u32,
    /// Tracker groups written as Macro projects.
    #[serde(default)]
    pub projects: u32,
    /// The run's state: `running` while planning, `ready` once a plan is
    /// staged, `importing` while writing, `completed`, `failed`, or
    /// `dismissed` when cancelled. Absent before the first run.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub status: Option<RunStatus>,
    /// Why the run failed, when it did.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub error: Option<String>,
    /// What planning has found in Notion so far, while it is `running`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub scanned: Option<ScanCounts>,
    /// Pages in the plan.
    pub pages: u32,
    /// Data sources (database tables) in the plan.
    pub data_sources: u32,
    /// Plan objects the decision model has not answered for yet, while
    /// planning is still `running`.
    #[serde(default)]
    pub deciding: u32,
    /// Whether the user is on a team. Without one, everything the import
    /// writes stays visible only to them.
    #[serde(default)]
    pub on_team: bool,
    /// Objects to copy as they are.
    pub copy: u32,
    /// Data sources whose rows become tasks.
    pub tasks: u32,
    /// Objects left in Notion.
    pub skip: u32,
    /// Objects that need handling by hand.
    pub hand: u32,
    /// Pages written as documents.
    pub documents: u32,
    /// Data sources written as databases.
    pub databases: u32,
    /// Rows those databases hold, every one counted while planning.
    pub database_rows: u32,
    /// Tasks the task lists become, one per row.
    pub task_rows: u32,
    /// Plan objects already imported.
    pub imported: u32,
    /// Plan objects still waiting to be written.
    pub waiting: u32,
    /// Plan objects being written now.
    pub writing: u32,
    /// Plan objects waiting for a teammate who is writing the same object
    /// for the team; they link to the teammate's copy once it is written.
    #[serde(default)]
    pub waiting_on_teammates: u32,
    /// Written plan objects shared with the user's team.
    #[serde(default)]
    pub shared_with_team: u32,
    /// Plan objects a teammate already imported and shared with the team;
    /// they link to that copy and are not counted as copies.
    #[serde(default)]
    pub already_in_macro: u32,
    /// Who imported the objects already in Macro, most first.
    #[serde(default)]
    pub already_imported_by: Vec<NotionImporter>,
    /// The review the plan is tied to, once presented.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub review_id: Option<Uuid>,
    /// Objects that need handling by hand, with reasons.
    #[serde(default)]
    pub hand_items: Vec<NotionReportItem>,
    /// Objects that failed to import, with the failure.
    #[serde(default)]
    pub failures: Vec<NotionReportItem>,
}