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.

18.1 KB
Raw Blame
//! Service trait for properties.
//!
//! Access control is represented in the method types: every entity-scoped
//! method takes a [`ViewReceipt`] or [`EditReceipt`] proving the caller's
//! access, and owner-scoped methods take the caller's identity plus their
//! team-membership receipt. User-facing callers mint receipts through the
//! entity access service at the inbound edge; internal (machine) callers mint
//! via [`EntityAccessReceipt::dangerously_assert_internal_user`], which makes
//! unchecked paths explicit and greppable.

use std::collections::HashMap;

use entity_access::domain::models::{EntityAccessReceipt, MemberTeamRole};
use macro_user_id::user_id::MacroUserIdStr;
use models_properties::EntityType;
use models_properties::api::requests::SetPropertyValue;
use models_properties::api::{
    AddPropertyOptionRequest, CreatePropertyDefinitionRequest, UpdatePropertyOptionRequest,
};
use models_properties::service::entity_property_with_definition::EntityPropertyWithDefinition;
use models_properties::service::property_change_source::PropertyChangeSource;
use models_properties::service::property_definition::PropertyDefinition;
use models_properties::service::property_definition_with_options::PropertyDefinitionWithOptions;
use models_properties::service::property_option::PropertyOption;
use models_properties::service::property_value::PropertyValue;
use system_properties::SystemPropertyKey;
use uuid::Uuid;

use super::error::PropertiesErr;
use super::model::{
    EditReceipt, EntityOptionUpdateOutcome, EntityPropertyInfo, EntityPropertyOptionSelection,
    EntityPropertyOptionUpdate, PropertyOptionReplacePlan, PropertyTargetKey, TagScope, TagSet,
    ViewReceipt,
};

/// The caller's team-membership proof, used to scope definition/option/tag
/// operations to the team the caller actually belongs to.
pub type TeamReceipt = EntityAccessReceipt<MemberTeamRole>;

/// The team id a team receipt proves membership of, if any.
pub fn team_id_from_receipt(team: Option<&TeamReceipt>) -> Option<Uuid> {
    team.and_then(|receipt| Uuid::parse_str(&receipt.entity().entity_id).ok())
}

/// Service trait for property operations.
pub trait PropertiesService: Send + Sync + 'static {
    /// Get all properties attached to an entity, with definitions, values, and
    /// options. Tag properties are restricted to the viewer's own and their
    /// teams' definitions (the viewer being the receipt's authenticated user).
    fn get_entity_properties(
        &self,
        access: &ViewReceipt,
    ) -> impl Future<Output = Result<Vec<EntityPropertyInfo>, PropertiesErr>> + Send;

    /// Get the tag sets visible to a caller — their personal set plus their
    /// teams' sets — with options attached.
    fn list_caller_tag_sets(
        &self,
        user_id: &str,
    ) -> impl Future<Output = Result<Vec<PropertyDefinitionWithOptions>, PropertiesErr>> + Send;

    /// Get a property value for an entity by property definition ID.
    /// Returns `None` if the property is not attached to the entity.
    fn get_property_value(
        &self,
        access: &ViewReceipt,
        property_definition_id: Uuid,
    ) -> impl Future<Output = Result<Option<PropertyValue>, PropertiesErr>> + Send;

    /// Get a system property value for an entity.
    /// Returns `None` if the property is not attached to the entity.
    fn get_system_property_value(
        &self,
        access: &ViewReceipt,
        property_key: SystemPropertyKey,
    ) -> impl Future<Output = Result<Option<PropertyValue>, PropertiesErr>> + Send;

    /// Set or update a property value for an entity, or attach a property without a value.
    /// Returns the canonical property assignment, definition, and persisted value.
    /// Validates property options if the value contains select options.
    /// Linking Parent Task / Subtasks additionally requires edit access to the
    /// referenced tasks.
    fn set_entity_property(
        &self,
        access: &EditReceipt,
        property_definition_id: Uuid,
        value: Option<SetPropertyValue>,
    ) -> impl Future<Output = Result<EntityPropertyWithDefinition, PropertiesErr>> + Send;

    /// [`Self::set_entity_property`] that records the outside event behind the
    /// change on the published `entity_property.updated`.
    fn set_entity_property_with_source(
        &self,
        access: &EditReceipt,
        property_definition_id: Uuid,
        value: Option<SetPropertyValue>,
        source: Option<PropertyChangeSource>,
    ) -> impl Future<Output = Result<EntityPropertyWithDefinition, PropertiesErr>> + Send;

    /// Append the project's agent assignees to a newly added task, preserving
    /// existing assignees and concurrent edits. Both capabilities must belong
    /// to the same actor. Publishes assignment changes with the task's attribution.
    /// The caller verifies the task's current project membership.
    /// Documents that are no longer tasks are ignored.
    fn inherit_project_agent_assignees(
        &self,
        project: &ViewReceipt,
        task: &EditReceipt,
    ) -> impl Future<Output = Result<(), PropertiesErr>> + Send;

    /// Add one option to a multi-select entity property value atomically.
    /// Attaches the property if needed and dedupes. Validates the option belongs
    /// to the (multi-select) property. Prefer this over `set_entity_property`
    /// for add/remove of a single option: it composes with concurrent changes
    /// instead of clobbering them.
    fn add_entity_property_option(
        &self,
        access: &EditReceipt,
        property_definition_id: Uuid,
        option_id: Uuid,
    ) -> impl Future<Output = Result<(), PropertiesErr>> + Send;

    /// Remove one option from a multi-select entity property value atomically.
    /// A no-op if absent.
    fn remove_entity_property_option(
        &self,
        access: &EditReceipt,
        property_definition_id: Uuid,
        option_id: Uuid,
    ) -> impl Future<Output = Result<(), PropertiesErr>> + Send;

    /// Get a single property definition by ID, readable by the caller (their own,
    /// their team's, or a system property). Returns [`PropertiesErr::NotFound`] if
    /// the definition doesn't exist or isn't visible to the caller.
    fn get_property_definition(
        &self,
        property_definition_id: Uuid,
        user_id: &MacroUserIdStr<'_>,
        team: Option<&TeamReceipt>,
    ) -> impl Future<Output = Result<PropertyDefinition, PropertiesErr>> + Send;

    /// Apply a complete tag-picker selection across one or more of an entity's
    /// multi-select properties in a single transaction, returning each
    /// property's final option ids for cache reconciliation.
    ///
    /// Each property change is a delta (options to add / remove) so the whole
    /// selection composes with concurrent edits under a per-row lock rather than
    /// clobbering them. Validates that every added option belongs to its
    /// (multi-select) property before any write; the persistence is
    /// all-or-nothing, so a failure on any property rolls back the whole batch.
    fn bulk_update_entity_property_options(
        &self,
        access: &EditReceipt,
        updates: Vec<EntityPropertyOptionUpdate>,
    ) -> impl Future<Output = Result<Vec<EntityPropertyOptionSelection>, PropertiesErr>> + Send;

    /// Apply one shared option delta to several entities at once, returning a
    /// per-entity outcome aligned to `access` (same length and order).
    ///
    /// The shared delta (`add_option_ids` / `remove_option_ids` on one
    /// multi-select `property_definition_id`) is validated once up front; a bad
    /// property or option fails the whole call. Each entity is then updated in
    /// its own transaction, so the batch is best-effort: an entity whose type
    /// does not accept the property, or whose write fails, is reported as
    /// [`EntityOptionUpdateOutcome::Failed`] without aborting the rest. Callers
    /// mint one [`EditReceipt`] per entity at the edge and pass only the
    /// entities the caller may edit; entities the caller cannot edit are handled
    /// there, not here.
    fn bulk_update_entities_property_options(
        &self,
        access: &[EditReceipt],
        property_definition_id: Uuid,
        add_option_ids: Vec<Uuid>,
        remove_option_ids: Vec<Uuid>,
    ) -> impl Future<Output = Result<Vec<EntityOptionUpdateOutcome>, PropertiesErr>> + Send;

    /// List property definitions owned by the given team and/or user, sorted by
    /// display name. Set `include_system` to true to also include system properties.
    /// When `for_entity_type` is provided, definitions that cannot be attached to
    /// that entity type are excluded.
    fn list_property_definitions(
        &self,
        team: Option<&TeamReceipt>,
        user_id: Option<&MacroUserIdStr<'_>>,
        include_system: bool,
        for_entity_type: Option<EntityType>,
    ) -> impl Future<Output = Result<Vec<PropertyDefinition>, PropertiesErr>> + Send;

    /// Same as [`Self::list_property_definitions`], but including each definition's
    /// select options.
    fn list_property_definitions_with_options(
        &self,
        team: Option<&TeamReceipt>,
        user_id: Option<&MacroUserIdStr<'_>>,
        include_system: bool,
        for_entity_type: Option<EntityType>,
    ) -> impl Future<Output = Result<Vec<PropertyDefinitionWithOptions>, PropertiesErr>> + Send;

    /// Create a property definition owned by the caller (their user property,
    /// or their team's when the request has team scope). Fails with
    /// [`PropertiesErr::TeamMembershipRequired`] for team scope without a team.
    /// Validates the request and creates any select options atomically.
    fn create_property_definition(
        &self,
        user_id: &MacroUserIdStr<'_>,
        team: Option<&TeamReceipt>,
        request: &CreatePropertyDefinitionRequest,
    ) -> impl Future<Output = Result<PropertyDefinition, PropertiesErr>> + Send;

    /// Delete a property definition owned by the caller.
    ///
    /// Fails with [`PropertiesErr::NotFound`] if the definition doesn't exist or
    /// isn't owned by the caller (their user property or a property of their team),
    /// and with [`PropertiesErr::SystemPropertyNotModifiable`] for system properties.
    fn delete_property_definition(
        &self,
        property_definition_id: Uuid,
        user_id: &MacroUserIdStr<'_>,
        team: Option<&TeamReceipt>,
    ) -> impl Future<Output = Result<(), PropertiesErr>> + Send;

    /// Get all options for a property definition readable by the caller (for dropdowns).
    fn get_property_options(
        &self,
        property_definition_id: Uuid,
        user_id: &MacroUserIdStr<'_>,
        team: Option<&TeamReceipt>,
    ) -> impl Future<Output = Result<Vec<PropertyOption>, PropertiesErr>> + Send;

    /// Batch options for requested definitions readable by the caller.
    /// Missing or inaccessible definitions are omitted, including their options.
    fn get_property_options_batch(
        &self,
        property_definition_ids: &[Uuid],
        user_id: &MacroUserIdStr<'_>,
        team: Option<&TeamReceipt>,
    ) -> impl Future<Output = Result<HashMap<Uuid, Vec<PropertyOption>>, PropertiesErr>> + Send;

    /// Add a new option to a select property owned by the caller.
    /// Validates the request against the property's data type, including the
    /// tag color rules.
    fn add_property_option(
        &self,
        user_id: &MacroUserIdStr<'_>,
        team: Option<&TeamReceipt>,
        property_definition_id: Uuid,
        request: &AddPropertyOptionRequest,
    ) -> impl Future<Output = Result<PropertyOption, PropertiesErr>> + Send;

    /// Get or create an option by exact value on a property owned by the caller.
    /// Preserves existing option metadata and tolerates concurrent creation.
    fn get_or_create_property_option(
        &self,
        user_id: &MacroUserIdStr<'_>,
        team: Option<&TeamReceipt>,
        property_definition_id: Uuid,
        request: &AddPropertyOptionRequest,
    ) -> impl Future<Output = Result<PropertyOption, PropertiesErr>> + Send;

    /// Update a property option in place (rename / recolor / reorder) on a
    /// property owned by the caller. The option id is preserved, so the change
    /// is reflected on every entity that references it.
    fn update_property_option(
        &self,
        user_id: &MacroUserIdStr<'_>,
        team: Option<&TeamReceipt>,
        property_definition_id: Uuid,
        option_id: Uuid,
        request: &UpdatePropertyOptionRequest,
    ) -> impl Future<Output = Result<PropertyOption, PropertiesErr>> + Send;

    /// Apply a whole-set option change on a `SelectString` property owned by
    /// the caller, in one transaction. Fails with
    /// [`PropertiesErr::OptionNotFound`] when a deleted or rewritten option is
    /// not on the definition and [`PropertiesErr::DuplicateOptionValue`] when
    /// two options would share a value; neither partially applies.
    fn replace_property_options(
        &self,
        user_id: &MacroUserIdStr<'_>,
        team: Option<&TeamReceipt>,
        property_definition_id: Uuid,
        plan: PropertyOptionReplacePlan,
    ) -> impl Future<Output = Result<Vec<PropertyOption>, PropertiesErr>> + Send;

    /// Delete a property option on a property owned by the caller, stripping
    /// its id from every entity value that references it.
    fn delete_property_option(
        &self,
        user_id: &MacroUserIdStr<'_>,
        team: Option<&TeamReceipt>,
        property_definition_id: Uuid,
        option_id: Uuid,
    ) -> impl Future<Output = Result<(), PropertiesErr>> + Send;

    /// List the caller's tag sets: their personal set, plus their team's set
    /// when on a team. Pure read - a scope with no provisioned definition yet
    /// returns an empty set.
    fn list_tag_sets(
        &self,
        user_id: &MacroUserIdStr<'_>,
        team: Option<&TeamReceipt>,
    ) -> impl Future<Output = Result<Vec<TagSet>, PropertiesErr>> + Send;

    /// Provision (get-or-create) the caller's tag set for the scope and return
    /// it. Fails with [`PropertiesErr::TeamMembershipRequired`] for team scope
    /// without a team.
    fn ensure_tag_set(
        &self,
        user_id: &MacroUserIdStr<'_>,
        team: Option<&TeamReceipt>,
        scope: TagScope,
    ) -> impl Future<Output = Result<TagSet, PropertiesErr>> + Send;

    /// Share one of the caller's personal labels with their team by moving it
    /// into the team tag set, provisioning that set if the team has none yet.
    ///
    /// The option id survives the move, so every entity already carrying the
    /// label keeps resolving to it. Fails with
    /// [`PropertiesErr::ConflictingTeamLabel`] when the team already has a label
    /// of that name (trimmed, case-insensitive), carrying that label so the
    /// caller can offer [`Self::merge_tag_option`] instead. Requires the option
    /// to be a label in the caller's own tag set and the caller to be on a team.
    fn promote_tag_option(
        &self,
        user_id: &MacroUserIdStr<'_>,
        team: Option<&TeamReceipt>,
        option_id: Uuid,
    ) -> impl Future<Output = Result<PropertyOption, PropertiesErr>> + Send;

    /// Replace one of the caller's personal labels with an existing team label:
    /// every entity carrying the personal label is retagged with the team label
    /// (deduped if it already has both), then the personal label is deleted.
    ///
    /// The team label's name and color win. Requires the source option to be a
    /// label in the caller's own tag set and the target to be a label in their
    /// team's tag set.
    fn merge_tag_option(
        &self,
        user_id: &MacroUserIdStr<'_>,
        team: Option<&TeamReceipt>,
        option_id: Uuid,
        target_option_id: Uuid,
    ) -> impl Future<Output = Result<PropertyOption, PropertiesErr>> + Send;

    /// Get an entity's stored properties with definitions, values, and options,
    /// sorted by display name. Personal tag properties of other users are
    /// filtered out. Does not include computed metadata properties
    /// (see [`Self::get_entity_metadata_properties`]).
    fn get_entity_properties_with_definitions(
        &self,
        access: &ViewReceipt,
    ) -> impl Future<Output = Result<Vec<EntityPropertyWithDefinition>, PropertiesErr>> + Send;

    /// Get an entity's read-only metadata properties, computed on-the-fly from
    /// the entity itself (name, owner, timestamps, ...).
    /// Returns `None` when the entity doesn't exist (or the id is malformed);
    /// entity types without metadata yield `Some(vec![])`.
    fn get_entity_metadata_properties(
        &self,
        access: &ViewReceipt,
    ) -> impl Future<Output = Result<Option<Vec<EntityPropertyWithDefinition>>, PropertiesErr>> + Send;

    /// Get properties for multiple entities, keyed by entity id and type.
    /// An empty `property_ids` fetches all properties for the given entities;
    /// otherwise only the requested definitions are returned. Personal tag
    /// properties of other users are filtered out per receipt.
    fn get_bulk_entity_properties(
        &self,
        access: &[ViewReceipt],
        property_ids: Vec<Uuid>,
    ) -> impl Future<
        Output = Result<
            HashMap<PropertyTargetKey, Vec<EntityPropertyWithDefinition>>,
            PropertiesErr,
        >,
    > + Send;

    /// Delete all properties attached to an entity.
    fn delete_entity_properties(
        &self,
        access: &EditReceipt,
    ) -> impl Future<Output = Result<(), PropertiesErr>> + Send;

    /// Look up an entity property by its ID, returning the entity it is
    /// attached to so the caller can mint an edit receipt for
    /// [`Self::delete_entity_property`]. Returns `None` if it doesn't exist.
    fn lookup_entity_property(
        &self,
        entity_property_id: Uuid,
    ) -> impl Future<Output = Result<Option<PropertyTargetKey>, PropertiesErr>> + Send;

    /// Delete a single entity property by its ID. The receipt must be for the
    /// entity the property is attached to. Fails when the property doesn't
    /// exist, is required for the entity type, or the receipt is for a
    /// different entity.
    fn delete_entity_property(
        &self,
        access: &EditReceipt,
        entity_property_id: Uuid,
    ) -> impl Future<Output = Result<(), PropertiesErr>> + Send;
}