Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
//! Ports (traits) the import domain depends on.
use super::models::{
AdoptedRun, ImportEntity, ImportKind, ImportRun, ImportSource, ImportSourceBinding,
ImportStatus, ImportTargetKey, ImportTargetKind, ImportTargetReservation, Initiator, NotionJob,
ReviewedRun, RunStatus, ScanCounts, SlackConversationId, SlackConversationPage,
SlackMemberPage, SlackUserPage, SlackWorkspaceId, TeamClaim, WrittenObject,
};
use agent_session::domain::model::AgentSessionId;
use agent_session::domain::notifications::PendingNotification;
use import_notion::domain::model::{NotionId, NotionPage};
use macro_user_id::user_id::MacroUserIdStr;
use std::collections::HashMap;
use std::time::Duration;
use thiserror::Error;
use uuid::Uuid;
/// Errors surfaced by the import service and repository.
#[derive(Debug, Error)]
pub enum ImportError {
/// Connected issue tracker read failed.
#[error(transparent)]
Tracker(#[from] import_tracker::domain::model::TrackerError),
/// AI work was refused or usage validation is temporarily unavailable.
#[error(transparent)]
Admission(#[from] ai_billing::AiAdmissionError),
/// This source does not support user-triggered discovery.
#[error("manual discovery is not supported for {source}", source = .0.as_ref())]
UnsupportedDiscovery(ImportSource),
/// Database failure.
#[error("database error: {0}")]
Db(rootcause::Report),
/// Metadata failed to (de)serialize.
#[error("invalid import metadata: {0}")]
Metadata(#[from] serde_json::Error),
/// An unidentified archive requires explicit administrator confirmation.
#[error("source identity requires administrator confirmation")]
SourceConfirmationRequired,
/// The team is already bound to a different Slack workspace.
#[error("source workspace does not match the team's binding")]
SourceMismatch,
/// Historical mappings or target shape/provenance are incompatible. No target IDs are exposed.
#[error("conflicting import target mapping")]
TargetConflict,
/// Completion must follow a committed reservation for exactly this UUID.
#[error("import target is not reserved")]
TargetNotReserved,
/// Notion could not be read.
#[error(transparent)]
Notion(#[from] import_notion::domain::ports::NotionError),
/// The user has not connected Notion, or turned it off.
#[error("Notion is not connected")]
NotionNotConnected,
/// The user is on a team and has not said who should see what a Notion
/// import writes.
#[error("who should see the Notion import was not chosen")]
NotionSharingRequired,
/// The import is not in a state that allows this; the message says why.
#[error("{0}")]
NotReady(&'static str),
/// Anything else.
#[error(transparent)]
Other(#[from] anyhow::Error),
}
/// Result alias for import operations.
pub type Result<T> = std::result::Result<T, ImportError>;
/// Errors reading a live Slack workspace.
#[derive(Debug, Error)]
pub enum SlackSourceError {
/// The user has no Slack connector.
#[error("Slack is not connected")]
NotConnected,
/// The connector lacks a required capability.
#[error("Slack connector capability unavailable: {0}")]
ToolsUnavailable(&'static str),
/// Slack temporarily refused reads due to rate limiting.
#[error("Slack rate limit exceeded")]
RateLimited {
/// Provider-supplied delay before retrying, when available.
retry_after: Option<Duration>,
},
/// The connection lacks a required Slack permission scope.
#[error("missing Slack scope: {0}")]
MissingScope(String),
/// Any other source failure.
#[error(transparent)]
Other(#[from] anyhow::Error),
}
/// Opens live Slack workspace sessions for import discovery and membership reads.
pub trait SlackWorkspaceSource: Send + Sync + 'static {
/// Workspace reader scoped to one discovery or one import batch.
type Session: SlackWorkspaceSession;
/// Open a session scoped to one discovery or one import batch.
/// Returns [`SlackSourceError::NotConnected`] when the user has no Slack
/// connector, or [`SlackSourceError::ToolsUnavailable`] when the connector
/// lacks a needed capability.
fn open(
&self,
user: &MacroUserIdStr<'static>,
) -> impl Future<Output = std::result::Result<Self::Session, SlackSourceError>> + Send;
}
/// Paginated workspace reads scoped to one discovery or one import batch.
/// Pass `None` to read the first page, then the returned continuation cursor.
pub trait SlackWorkspaceSession: Send + Sync {
/// List conversations visible to the connected user.
fn list_conversations(
&self,
cursor: Option<&str>,
) -> impl Future<Output = std::result::Result<SlackConversationPage, SlackSourceError>> + Send;
/// List the members of one Slack conversation.
fn conversation_members(
&self,
conversation: &SlackConversationId,
cursor: Option<&str>,
) -> impl Future<Output = std::result::Result<SlackMemberPage, SlackSourceError>> + Send;
/// List the workspace user directory.
fn list_users(
&self,
cursor: Option<&str>,
) -> impl Future<Output = std::result::Result<SlackUserPage, SlackSourceError>> + Send;
}
/// Persistence for the import ledger and discovery runs.
///
/// Status writes are compare-and-swaps that report whether they happened, so
/// concurrent discovery jobs, import jobs, and user actions interleave without
/// clobbering each other.
pub trait ImportRepo: Send + Sync + 'static {
/// The user's own row for `(source, foreign_id)`, regardless of status.
fn get_own_by_foreign_id(
&self,
user: &MacroUserIdStr<'static>,
source: ImportSource,
foreign_id: &str,
) -> impl Future<Output = Result<Option<ImportEntity>>> + Send;
/// A teammate's `imported` row for `(source, foreign_id)` shared with the
/// user's team, if any.
fn find_team_imported(
&self,
user: &MacroUserIdStr<'static>,
source: ImportSource,
foreign_id: &str,
) -> impl Future<Output = Result<Option<ImportEntity>>> + Send;
/// Upsert a `staged` row. Inserts, or refreshes the metadata of an
/// existing `staged` row. Returns `None` when the user's row exists in a
/// non-staged status (imported / importing / discarded) — the caller
/// decides what that means.
fn upsert_staged(
&self,
user: &MacroUserIdStr<'static>,
source: ImportSource,
kind: ImportKind,
initiator: Initiator,
foreign_id: &str,
metadata: &serde_json::Value,
) -> impl Future<Output = Result<Option<ImportEntity>>> + Send;
/// Upsert an `imported` row (used when an agent already created the
/// entity, e.g. from chat). Overwrites any non-imported own row; an
/// already-imported row is left untouched (first mapping wins). Returns
/// the row as stored.
#[allow(clippy::too_many_arguments)]
fn upsert_imported(
&self,
user: &MacroUserIdStr<'static>,
source: ImportSource,
kind: ImportKind,
initiator: Initiator,
foreign_id: &str,
metadata: &serde_json::Value,
entity_id: &str,
entity_type: &str,
team_id: Option<Uuid>,
) -> impl Future<Output = Result<ImportEntity>> + Send;
/// The user's own row by ledger id.
fn get(
&self,
user: &MacroUserIdStr<'static>,
id: Uuid,
) -> impl Future<Output = Result<Option<ImportEntity>>> + Send;
/// Visible rows for the user: their own, plus teammates' team-imported
/// rows (deduplicated against the user's own rows by `(source,
/// foreign_id)`, own row winning). Newest first.
fn list(
&self,
user: &MacroUserIdStr<'static>,
source: Option<ImportSource>,
status: Option<ImportStatus>,
) -> impl Future<Output = Result<Vec<ImportEntity>>> + Send;
/// CAS the user's own `staged` rows in `ids` to `importing`. Returns the
/// rows that flipped (missing / non-staged ids are skipped, not errors).
fn mark_importing(
&self,
user: &MacroUserIdStr<'static>,
ids: &[Uuid],
) -> impl Future<Output = Result<Vec<ImportEntity>>> + Send;
/// CAS one `importing` row to `imported` with the entity it became,
/// recording `team_id` when given (a row's team claim is kept
/// otherwise). Rows waiting on it ([`NotionPlanRepo::wait_on`]) link to
/// the same entity.
fn mark_imported(
&self,
user: &MacroUserIdStr<'static>,
id: Uuid,
entity_id: &str,
entity_type: &str,
team_id: Option<Uuid>,
) -> impl Future<Output = Result<Option<ImportEntity>>> + Send;
/// CAS one `importing` row back to `staged`, recording the failure and
/// dropping its team claim. Rows waiting on it go back to `staged` too.
fn mark_import_failed(
&self,
user: &MacroUserIdStr<'static>,
id: Uuid,
error: &str,
) -> impl Future<Output = Result<bool>> + Send;
/// Bump `updated_at` on the user's still-`importing` rows in `ids` — the
/// running batch's heartbeat, proving a live process still owns them.
fn touch_importing(
&self,
user: &MacroUserIdStr<'static>,
ids: &[Uuid],
) -> impl Future<Output = Result<u64>> + Send;
/// CAS the user's `importing` rows whose heartbeat stopped more than
/// `older_than_secs` ago back to `staged`. Import jobs are in-process
/// tasks: a crash or restart mid-job orphans its rows, and nothing else
/// can move them again. Notion workspace plan rows are left to the
/// adopting process ([`NotionRunRepo`]). Returns how many were reaped.
fn fail_stale_importing(
&self,
user: &MacroUserIdStr<'static>,
older_than_secs: i64,
) -> impl Future<Output = Result<u64>> + Send;
/// CAS one of the user's own `staged` rows to `discarded`. Returns
/// whether it happened.
fn discard(
&self,
user: &MacroUserIdStr<'static>,
id: Uuid,
) -> impl Future<Output = Result<bool>> + Send;
/// The user's team, when they are on one.
fn user_team_id(
&self,
user: &MacroUserIdStr<'static>,
) -> impl Future<Output = Result<Option<Uuid>>> + Send;
/// IDs of the team's members. Macro user IDs encode emails, so this is
/// the roster the import domain matches Slack emails against.
fn team_members(
&self,
team_id: Uuid,
) -> impl Future<Output = Result<Vec<MacroUserIdStr<'static>>>> + Send;
/// All discovery runs for the user.
fn list_runs(
&self,
user: &MacroUserIdStr<'static>,
) -> impl Future<Output = Result<Vec<ImportRun>>> + Send;
/// CAS a discovery run to `running`. Wins when no run exists or the
/// existing status is in `from`. Returns whether this call won.
fn start_run(
&self,
user: &MacroUserIdStr<'static>,
source: ImportSource,
from: &[RunStatus],
) -> impl Future<Output = Result<bool>> + Send;
/// CAS the user's runs stuck in `running` (or the legacy `importing`) for
/// more than `older_than_secs` to `failed`. Discovery is an in-process
/// task: a crash or deploy mid-run leaves the row behind, and the UI
/// cannot start a new run while one looks active. Notion runs are adopted
/// instead ([`NotionRunRepo`]). Returns how many were reaped.
fn fail_stale_runs(
&self,
user: &MacroUserIdStr<'static>,
older_than_secs: i64,
) -> impl Future<Output = Result<u64>> + Send;
/// CAS the `running` run for `source` to `to` (ready/failed), recording
/// `error` when there is one. Returns whether it happened.
fn finish_run(
&self,
user: &MacroUserIdStr<'static>,
source: ImportSource,
to: RunStatus,
error: Option<&str>,
) -> impl Future<Output = Result<bool>> + Send;
}
/// Narrow canonical Slack ledger persistence shared by archive and onboarding.
///
/// Callers authorize the explicit team before invoking this port. Target access,
/// exact DM membership, and administrator authorization remain domain-service
/// responsibilities: a reservation is provenance, not an access grant.
/// Each operation commits and releases its connection before returning.
pub trait CanonicalImportRepo: Send + Sync + 'static {
/// Read the durable binding; `None` means the team is not yet bound.
fn source_binding(
&self,
team_id: Uuid,
) -> impl Future<Output = Result<Option<ImportSourceBinding>>> + Send;
/// Bind once, reject known mismatches, and retain the first unknown-source
/// confirmation timestamp. Every unidentified archive requires confirmation,
/// even when a known binding exists. A later known identity may resolve a
/// previously confirmed-unknown binding but never replace a known identity.
fn bind_source(
&self,
team_id: Uuid,
workspace_id: Option<&SlackWorkspaceId>,
confirmed_unknown: bool,
) -> impl Future<Output = Result<ImportSourceBinding>> + Send;
/// Reserve one stable UUID, considering BOTH own imported rows (even after a
/// team change) and rows explicitly shared with this team. Reject ambiguous,
/// cross-team, non-channel or incompatible mappings rather than choosing one.
/// `existing_channel_id` is an optional already-authorized target to claim
/// (e.g. an exact-pair DM); it must agree with every historical mapping and
/// cannot replace a committed pending UUID. Without it, allocate UUIDv7.
/// Private/DM historical targets require either this explicit authorization
/// or an earlier ready reservation in this namespace.
fn reserve_target(
&self,
user: &MacroUserIdStr<'static>,
key: &ImportTargetKey,
kind: ImportTargetKind,
existing_channel_id: Option<Uuid>,
) -> impl Future<Output = Result<ImportTargetReservation>> + Send;
/// Complete exactly the reserved UUID after idempotent channel creation.
/// Revalidate target type/team and preserve the first mapping. Private/DM
/// provenance is stored ONLY in the reservation, never a team-visible ledger
/// row. Team ledger rows may be published separately through `ImportRepo`.
fn complete_target(
&self,
key: &ImportTargetKey,
channel_id: Uuid,
kind: ImportTargetKind,
) -> impl Future<Output = Result<ImportTargetReservation>> + Send;
}
/// Side-effect-free canonical reads, separate from reservation and legacy listings.
pub trait ImportTargetReader: Send + Sync + 'static {
/// Exact IDs in an explicit bound namespace. At most 500 IDs per call; returns
/// one outcome per input, in order. Unknown-source confirmation is not domain
/// evidence. Never creates reservations, locks rows, or grants read access.
fn lookup_targets(
&self,
team: Uuid,
binding: &ImportSourceBinding,
channels: &[super::models::SlackConversationId],
) -> impl Future<Output = Result<Vec<super::models::ImportTargetLookup>>> + Send;
}
/// System properties to set on an imported task, already normalized to
/// Macro's vocabulary by the import service (the creator applies them
/// best-effort — a property that fails to apply never fails the import).
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct ImportedTaskProperties {
/// Macro status display label (`Not Started` … `Canceled`).
pub status: Option<String>,
/// Macro priority display label (`Low` … `Urgent`).
pub priority: Option<String>,
/// Due date as an ISO date (`YYYY-MM-DD`).
pub due_date: Option<String>,
/// Assignee email, resolved against the user's team roster.
pub assignee_email: Option<String>,
}
/// When a source page was created and last edited, so its copy sorts by
/// when it was written there rather than by when it was copied in.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct SourceDates {
/// When the page was created.
pub created: chrono::DateTime<chrono::Utc>,
/// When the page was last edited.
pub last_edited: chrono::DateTime<chrono::Utc>,
}
impl From<&NotionPage> for SourceDates {
fn from(page: &NotionPage) -> Self {
Self {
created: page.created,
last_edited: page.last_edited,
}
}
}
/// Properties recovered from a Notion page and attached to the imported
/// Macro document. The creator applies these best-effort after the document
/// exists, so unsupported or invalid values never prevent the body import.
#[derive(
Debug, Clone, Default, PartialEq, serde::Serialize, serde::Deserialize, schemars::JsonSchema,
)]
#[serde(rename_all = "camelCase")]
pub struct ImportedDocumentProperties {
/// Ordinary Notion database properties.
#[serde(default)]
pub values: Vec<ImportedDocumentProperty>,
/// Notion tag/label values, mapped onto Macro's personal tag set.
#[serde(default)]
pub tags: Vec<String>,
}
/// One named property recovered from a Notion database page.
#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize, schemars::JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct ImportedDocumentProperty {
/// Property display name.
pub name: String,
/// Typed property value.
pub value: ImportedDocumentPropertyValue,
}
/// Portable property values that have direct Macro property equivalents.
#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize, schemars::JsonSchema)]
#[serde(rename_all = "snake_case", tag = "type")]
pub enum ImportedDocumentPropertyValue {
/// Boolean value.
Boolean {
/// Imported value.
value: bool,
},
/// Date or date-time value, encoded as ISO-8601.
Date {
/// Imported value.
value: String,
},
/// Numeric value.
Number {
/// Imported value.
value: f64,
},
/// Plain text value.
String {
/// Imported value.
value: String,
},
/// One or more select labels.
Select {
/// Imported option labels.
values: Vec<String>,
/// Whether the source property accepts multiple options.
multi: bool,
},
/// One or more URLs.
Link {
/// Imported URLs.
urls: Vec<String>,
/// Whether the source property accepts multiple links.
multi: bool,
},
}
/// What a Notion page's references point to in Macro, so the page converts
/// with live mentions instead of links back to Notion.
#[derive(Debug, Clone, Default, PartialEq)]
pub struct NotionLinks {
/// Notion page → the Macro document it becomes.
pub pages: HashMap<NotionId, NotionPageLink>,
/// Notion person → the Macro user they are.
pub users: HashMap<NotionId, NotionUserLink>,
}
/// The Macro document a Notion page becomes.
#[derive(Debug, Clone, PartialEq)]
pub struct NotionPageLink {
/// The document id, minted before the document exists.
pub document_id: Uuid,
/// Its name.
pub name: String,
}
/// The Macro user a Notion person is.
#[derive(Debug, Clone, PartialEq)]
pub struct NotionUserLink {
/// The Macro user id.
pub user_id: MacroUserIdStr<'static>,
/// Their email, lowercase.
pub email: String,
}
/// Creates the Macro entities imports become. Implemented by the host
/// service against its real document/channel services; the fixed
/// source → entity-type mapping is enforced by the import service, which
/// only ever calls the creator matching the row's source.
pub trait EntityCreator: Send + Sync + 'static {
/// Create a task document, applying `properties` best-effort once the
/// task exists. Returns the new entity id.
fn create_task(
&self,
user: &MacroUserIdStr<'static>,
name: &str,
markdown: &str,
properties: &ImportedTaskProperties,
) -> impl Future<Output = anyhow::Result<String>> + Send;
/// Create a document from a Notion page in Notion's enhanced markdown,
/// its references resolved through `links`. Returns the new entity id.
fn create_notion_document(
&self,
user: &MacroUserIdStr<'static>,
name: &str,
notion_markdown: &str,
links: &NotionLinks,
properties: &ImportedDocumentProperties,
) -> impl Future<Output = anyhow::Result<String>> + Send;
/// Ensure the reserved Slack Team channel, using its canonical UUID and
/// normalized source identity. Reuse must preserve existing settings and
/// memberships and must not replay first-creation effects. Participant emails
/// are matched against the team roster best-effort on initial creation only.
/// Returns the persisted channel ID, never a discarded creation candidate.
fn create_channel(
&self,
user: &MacroUserIdStr<'static>,
name: &str,
target: &ImportTargetReservation,
participant_emails: &[String],
) -> impl Future<Output = anyhow::Result<Uuid>> + Send;
}
/// A database a workspace import just created, with the starter table and its
/// title column, which the import reuses for the first data source.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct NewDatabase {
/// The new database.
pub database_id: Uuid,
/// The table every new database starts with.
pub table: models_databases::TableId,
/// That table's title column.
pub title_column: models_databases::ColumnId,
}
/// Something a workspace import shares with the user's team.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SharedEntity {
/// A folder, and everything in it.
Folder(Uuid),
/// A document.
Document(Uuid),
/// A database, with its rows.
Database(Uuid),
}
/// A team member a Notion person can be matched to, by email.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TeamMember {
/// The member's Macro user id.
pub user_id: MacroUserIdStr<'static>,
/// Their email, lowercase.
pub email: String,
}
/// Creates the Macro side of a workspace import: folders mirroring the
/// source's tree, documents and tasks inside them, and databases.
///
/// Every entity is created as `user`, through the same services the app
/// uses, so permissions, search and sync behave as for anything the user
/// made by hand.
pub trait WorkspaceWriter: Send + Sync + 'static {
/// Idempotently create a Macro project (initiative) with the ledger's
/// stable id and the approved visibility, using attributed creation.
fn create_tracker_project(
&self,
user: &MacroUserIdStr<'static>,
id: Uuid,
name: &str,
markdown: &str,
shared: bool,
) -> impl Future<Output = anyhow::Result<Uuid>> + Send;
/// Idempotently create a task from ordinary markdown, applying normalized
/// task properties and approved visibility. Never uses Notion conversion.
fn create_tracker_task(
&self,
user: &MacroUserIdStr<'static>,
id: Uuid,
name: &str,
markdown: &str,
properties: &ImportedTaskProperties,
shared: bool,
) -> impl Future<Output = anyhow::Result<String>> + Send;
/// Apply project, parent/subtask relationships and labels after all tasks
/// exist. Safe to repeat; never points at a failed or excluded row.
fn link_tracker_task(
&self,
user: &MacroUserIdStr<'static>,
id: Uuid,
relations: &TrackerTaskRelations,
) -> impl Future<Output = anyhow::Result<()>> + Send;
/// Create a folder, inside `parent` when given, dated by what is written
/// into it rather than by when it was made. Returns the folder id.
fn create_folder(
&self,
user: &MacroUserIdStr<'static>,
name: &str,
parent: Option<Uuid>,
) -> impl Future<Output = anyhow::Result<Uuid>> + Send;
/// Whether `folder` still exists and `user` can create inside it.
fn folder_exists(
&self,
user: &MacroUserIdStr<'static>,
folder: Uuid,
) -> impl Future<Output = anyhow::Result<bool>> + Send;
/// Create document `id` from a Notion page (Notion's enhanced markdown,
/// references resolved through `links`) inside `folder` when given,
/// applying `properties` best-effort and keeping the page's `dates` when
/// known. Returns the document id. Safe to repeat: when document `id`
/// exists already (an interrupted earlier attempt), it is left as it is
/// and its id returned.
#[allow(clippy::too_many_arguments)]
fn create_document(
&self,
user: &MacroUserIdStr<'static>,
id: Uuid,
name: &str,
notion_markdown: &str,
links: &NotionLinks,
properties: &ImportedDocumentProperties,
folder: Option<Uuid>,
dates: Option<SourceDates>,
) -> impl Future<Output = anyhow::Result<String>> + Send;
/// Create task `id` from a Notion page (as for [`Self::create_document`],
/// and as safe to repeat) inside `folder` when given, applying
/// `properties` best-effort and keeping the page's `dates`. Returns the
/// task id.
#[expect(
clippy::too_many_arguments,
reason = "a task carries its id, content, links, properties, folder and dates"
)]
fn create_task(
&self,
user: &MacroUserIdStr<'static>,
id: Uuid,
name: &str,
notion_markdown: &str,
links: &NotionLinks,
properties: &ImportedTaskProperties,
folder: Option<Uuid>,
dates: Option<SourceDates>,
) -> impl Future<Output = anyhow::Result<String>> + Send;
/// Create an empty database named `name`.
fn create_database(
&self,
user: &MacroUserIdStr<'static>,
name: &str,
) -> impl Future<Output = anyhow::Result<NewDatabase>> + Send;
/// Apply `ops` to a database `user` created, in one transaction. Ops may
/// refer to ids minted earlier in the same batch.
fn apply_database_ops(
&self,
user: &MacroUserIdStr<'static>,
database_id: Uuid,
ops: Vec<models_databases::DatabaseOp>,
) -> impl Future<Output = anyhow::Result<Vec<models_databases::OpResult>>> + Send;
/// Share `entity`, which `user` owns, with `user`'s team at edit level.
/// Sharing a folder reaches everything inside it, folders included.
/// Safe to repeat.
fn share_with_team(
&self,
user: &MacroUserIdStr<'static>,
entity: SharedEntity,
) -> impl Future<Output = anyhow::Result<()>> + Send;
/// The members of `user`'s team (including `user`), for matching Notion
/// people by email. Empty when the user has no team.
fn team_members(
&self,
user: &MacroUserIdStr<'static>,
) -> impl Future<Output = anyhow::Result<Vec<TeamMember>>> + Send;
}
/// Stable task/project relationships resolved from a reviewed tracker plan.
#[derive(Debug, Clone, Default)]
pub struct TrackerTaskRelations {
/// Macro project (initiative) containing this task.
pub project: Option<Uuid>,
/// Macro parent task, if it was imported successfully.
pub parent: Option<Uuid>,
/// Source labels, mapped to personal tags.
pub labels: Vec<String>,
}
/// One object of a workspace import plan, ready to stage.
#[derive(Debug, Clone, PartialEq)]
pub struct PlanRow {
/// What the object is.
pub kind: ImportKind,
/// The object's id in the source.
pub foreign_id: String,
/// The `foreign_id` of the plan row it sits under, if any.
pub parent_foreign_id: Option<String>,
/// The row's metadata, already capped.
pub metadata: serde_json::Value,
}
/// Ledger operations a workspace import needs beyond single-row staging.
pub trait NotionPlanRepo: Send + Sync + 'static {
/// Replace `user`'s current plan for `source`: drop the staged rows of the
/// previous plan, then stage `rows` in order (parents before children),
/// linking each to its parent row and to the review the `running` run
/// records, if one presents it already. Objects already importing or
/// imported keep their rows. Returns the rows now staged.
fn replace_plan(
&self,
user: &MacroUserIdStr<'static>,
source: ImportSource,
rows: &[PlanRow],
) -> impl Future<Output = Result<Vec<ImportEntity>>> + Send;
/// Rewrite the metadata of the user's staged plan rows for `rows`'
/// objects (by `foreign_id`), as the decision model answers for them.
/// Rows no longer staged are left alone. Returns how many changed.
fn update_plan_rows(
&self,
user: &MacroUserIdStr<'static>,
source: ImportSource,
rows: &[PlanRow],
) -> impl Future<Output = Result<u64>> + Send;
/// Teammates' rows for the Notion objects `foreign_ids` that hold the
/// user's team's claim (`importing` or `imported`, shared with the team).
fn team_copies(
&self,
user: &MacroUserIdStr<'static>,
foreign_ids: &[String],
) -> impl Future<Output = Result<Vec<ImportEntity>>> + Send;
/// Record the sharing the user chose on their staged plan rows: `shared`
/// become shared with the team, `personal` not. Returns how many changed.
fn set_plan_sharing(
&self,
user: &MacroUserIdStr<'static>,
shared: &[Uuid],
personal: &[Uuid],
) -> impl Future<Output = Result<u64>> + Send;
/// CAS the user's own `staged` rows in `ids` to `importing`, claiming
/// each of `shared` for `team_id` unless a teammate holds the team's
/// claim on the same object. The team's partial unique index makes the
/// claim exclusive, so two teammates writing the same object at once
/// cannot both hold it. Returns the rows that moved, with the claims
/// taken.
fn claim_importing(
&self,
user: &MacroUserIdStr<'static>,
ids: &[Uuid],
shared: &[Uuid],
team_id: Option<Uuid>,
) -> impl Future<Output = Result<Vec<ImportEntity>>> + Send;
/// Who writes the object of the user's `importing` row `import_id` for
/// `team_id`. With `claim` set the row takes the claim when nobody holds
/// it, or when its holder's import stopped (no live lease on a writing
/// run); otherwise it writes a copy of its own.
fn claim_team_object(
&self,
user: &MacroUserIdStr<'static>,
import_id: Uuid,
team_id: Uuid,
claim: bool,
) -> impl Future<Output = Result<TeamClaim>> + Send;
/// Make the user's `importing` row `import_id` wait on the teammate's row
/// `holder`, which links it once `holder` is imported. Returns `false`
/// (and changes nothing) when `holder` is no longer being written.
fn wait_on(
&self,
user: &MacroUserIdStr<'static>,
import_id: Uuid,
holder: Uuid,
) -> impl Future<Output = Result<bool>> + Send;
/// Tie the current plan to `review_id`, presented in `session_id`: its
/// staged rows, and the run while it is still planning (`running`), so
/// rows staged later are tied too. The first review presenting a plan
/// keeps its session, which hears when the plan is ready and when its
/// write ends. Returns how many rows it tied.
fn attach_review(
&self,
user: &MacroUserIdStr<'static>,
source: ImportSource,
review_id: Uuid,
session_id: AgentSessionId,
) -> impl Future<Output = Result<u64>> + Send;
/// Move `user`'s run for `source` to `to` when it is in one of `from`,
/// dropping any lease on it. Returns whether the run moved.
fn transition_run(
&self,
user: &MacroUserIdStr<'static>,
source: ImportSource,
from: &[RunStatus],
to: RunStatus,
error: Option<&str>,
) -> impl Future<Output = Result<bool>> + Send;
/// Record what `user`'s `running` run for `source` has found so far.
/// Returns whether the run was still running.
fn record_scan(
&self,
user: &MacroUserIdStr<'static>,
source: ImportSource,
scanned: ScanCounts,
) -> impl Future<Output = Result<bool>> + Send;
}
/// Who holds the user's Notion run, so an import outlives the process running
/// it.
///
/// The process planning or writing holds a lease on the run and renews it
/// while it works. Once a lease lapses (a crash or a deploy) any process may
/// adopt the run and resume the job recorded on it.
pub trait NotionRunRepo: Send + Sync + 'static {
/// Scope leases, team claims and root folders to one workspace source.
fn for_source(&self, source: ImportSource) -> Self
where
Self: Sized;
/// Take the user's Notion run for `owner` until `lease` from now and
/// record `job` on it. Only a run that just started (`running` or
/// `importing`, held by nobody) can be taken. Returns whether it was.
fn take_run(
&self,
user: &MacroUserIdStr<'static>,
owner: Uuid,
lease: Duration,
job: &NotionJob,
) -> impl Future<Output = Result<bool>> + Send;
/// Extend `owner`'s lease on the user's Notion run to `lease` from now.
/// Returns `false` once the run stopped or another process holds it.
fn renew_lease(
&self,
user: &MacroUserIdStr<'static>,
owner: Uuid,
lease: Duration,
) -> impl Future<Output = Result<bool>> + Send;
/// Give up `owner`'s lease, so another process adopts the run at once.
/// Returns whether `owner` held it.
fn release_lease(
&self,
user: &MacroUserIdStr<'static>,
owner: Uuid,
) -> impl Future<Output = Result<bool>> + Send;
/// Adopt up to `limit` Notion runs (only `user`'s, when given) still
/// planning or writing whose lease lapsed, or which nobody leased and
/// nobody touched for `stale_after` (runs started by code that predates
/// leases). Each is held for `owner` until `lease` from now. Runs another
/// process is adopting at the same moment are skipped.
fn adopt_stalled_runs(
&self,
user: Option<&MacroUserIdStr<'static>>,
owner: Uuid,
lease: Duration,
stale_after: Duration,
limit: u16,
) -> impl Future<Output = Result<Vec<AdoptedRun>>> + Send;
/// Move the user's Notion run to `to` with `error` when it is in one of
/// `from`, dropping any lease on it; a run cancelled meanwhile stays
/// `dismissed` with its own error. In the same transaction, produce the
/// system event `event` makes of the moved run, so the session presenting
/// its review hears of the change exactly when it happens. Returns the
/// moved run, or `None` when it was in none of `from`.
fn transition_reviewed_run<Event>(
&self,
user: &MacroUserIdStr<'static>,
from: &[RunStatus],
to: RunStatus,
error: Option<&str>,
event: Event,
) -> impl Future<Output = Result<Option<ReviewedRun>>> + Send
where
Event: FnOnce(&ReviewedRun) -> Option<PendingNotification> + Send;
/// The user's "Notion" folder, once an import has made one.
fn root_folder(
&self,
user: &MacroUserIdStr<'static>,
) -> impl Future<Output = Result<Option<Uuid>>> + Send;
/// Record `folder` as the user's "Notion" folder.
fn set_root_folder(
&self,
user: &MacroUserIdStr<'static>,
folder: Uuid,
) -> impl Future<Output = Result<()>> + Send;
/// Send the user's workspace plan rows still `importing` back to staged
/// with `reason`, unless a write is running for them or they wait on a
/// teammate's row still being written. Rows waiting on a teammate's row
/// that stopped go back too. Returns how many moved.
fn settle_importing(
&self,
user: &MacroUserIdStr<'static>,
reason: &str,
) -> impl Future<Output = Result<u64>> + Send;
}
/// What workspace writes created for each ledger row, recorded as they go so
/// a resumed write reuses it instead of creating it again.
pub trait WrittenObjects: Send + Sync + 'static {
/// Everything recorded for the user's ledger rows `import_ids`.
fn written(
&self,
user: &MacroUserIdStr<'static>,
import_ids: &[Uuid],
) -> impl Future<Output = Result<Vec<WrittenObject>>> + Send;
/// Record `objects` for the user's ledger rows. An object already
/// recorded under the same row, kind and Notion object keeps its earlier
/// id. Returns what is recorded for each of `objects` afterwards.
fn record_written(
&self,
user: &MacroUserIdStr<'static>,
objects: &[WrittenObject],
) -> impl Future<Output = Result<Vec<WrittenObject>>> + Send;
}