planter_core/

project.rs

use std::collections::{HashMap, HashSet, VecDeque};
use std::num::NonZeroU32;

use anyhow::{Context, bail};
use bon::Builder;
use chrono::{DateTime, Utc};
use uuid::Uuid;

use crate::{
    duration::NonNegativeDuration,
    identifiable,
    money::MultiCurrencyAmount,
    resources::{Purchase, Resource},
    stakeholders::Stakeholder,
    task::Task,
};

#[derive(Debug, Default, Builder)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[builder(on(String, into))]
/// Represents a project with a name and a list of resources.
pub struct Project {
    /// The name of the project.
    name: String,
    /// The description of the project.
    description: Option<String>,
    /// The start date of the project.
    start_date: Option<DateTime<Utc>>,
    /// The end date of the project.
    end_date: Option<DateTime<Utc>>,
    /// The tasks associated with the project, in the order they were added.
    #[builder(default)]
    tasks: Vec<Task>,
    /// Successor relationships for the time-relationship DAG.
    #[builder(default)]
    succ: HashMap<Uuid, Vec<(Uuid, TimeRelationship)>>,
    /// Predecessor relationships for the time-relationship DAG.
    #[builder(default)]
    pred: HashMap<Uuid, Vec<(Uuid, TimeRelationship)>>,
    /// Subtask tree: parent -> children.
    #[builder(default)]
    children: HashMap<Uuid, Vec<Uuid>>,
    /// Subtask tree: child -> parent.
    #[builder(default)]
    parent_of: HashMap<Uuid, Uuid>,
    /// The resources the project pays for, in the order they were added. One-time purchase
    /// costs are recorded here; tasks engage them via [`Self::assign_resource`].
    #[builder(default)]
    resources: Vec<Resource>,
    /// The list of stakeholders associated with the project.
    #[builder(default)]
    stakeholders: Vec<Stakeholder>,
}

#[derive(Debug, Default, Clone, Copy)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
/// The predecessor - successor relationship between tasks.
pub enum TimeRelationship {
    /// The predecessor has to start for the successor to finish.
    StartToFinish,
    /// The predecessor has to finish for the successor to finish.
    FinishToFinish,
    #[default]
    /// The predecessor has to finish for the successor to start.
    FinishToStart,
    /// The predecessor has to start for the successor to start.
    StartToStart,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
/// The direction of a relationship update.
pub enum RelDir {
    /// Update the predecessors of a task.
    Predecessors,
    /// Update the successors of a task.
    Successors,
}

impl Project {
    /// Creates a new project with the given name.
    ///
    /// # Arguments
    ///
    /// * `name` - The name of the project.
    ///
    /// # Returns
    ///
    /// A new `Project` instance.
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::project::Project;
    ///
    /// let project = Project::new("World domination");
    /// assert_eq!(project.name(), "World domination");
    /// ```
    #[must_use]
    pub fn new(name: impl Into<String>) -> Self {
        Self {
            name: name.into(),
            ..Default::default()
        }
    }

    /// Returns the name of the project.
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::project::Project;
    ///
    /// let project = Project::new("World domination");
    /// assert_eq!(project.name(), "World domination");
    /// ```
    #[must_use]
    pub fn name(&self) -> &str {
        &self.name
    }

    /// Returns the description of the project.
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::project::Project;
    ///
    /// let project = Project::new("World domination");
    /// assert_eq!(project.description(), None);
    /// ```
    #[must_use]
    pub fn description(&self) -> Option<&str> {
        self.description.as_deref()
    }

    /// Adds a task to the project and returns its stable [`Uuid`].
    ///
    /// Adding a task whose id already exists in the project replaces it in place, without
    /// duplicating its slot in [`Self::tasks`].
    ///
    /// # Arguments
    ///
    /// * `task` - The task to add to the project.
    ///
    /// # Returns
    ///
    /// The stable [`Uuid`] assigned to the task.
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::{project::Project, task::Task};
    ///
    /// let mut project = Project::new("World domination");
    /// let id = project.add_task(Task::new("Become world leader"));
    /// assert_eq!(project.tasks().count(), 1);
    /// ```
    pub fn add_task(&mut self, task: Task) -> Uuid {
        let id = task.id();
        identifiable::upsert(&mut self.tasks, task);
        id
    }

    /// Inserts a new task as a sibling right before `sibling_id` in the task order.
    /// If the sibling has a parent, the new task becomes a child of the same parent. This only
    /// ever inserts a new task, it never moves an existing one.
    ///
    /// # Errors
    ///
    /// Returns an error if `sibling_id` doesn't exist, or if `task`'s id is already used by
    /// another task in the project.
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::{project::Project, task::Task};
    ///
    /// let mut project = Project::new("World domination");
    /// let a = project.add_task(Task::new("Build an army"));
    /// let b = project.add_task(Task::new("Train troops"));
    /// let c = project.add_sibling_before(Task::new("Gather allies"), b).unwrap();
    ///
    /// let ids: Vec<_> = project.tasks().map(|t| t.id()).collect();
    /// assert_eq!(ids, vec![a, c, b]);
    /// ```
    pub fn add_sibling_before(&mut self, task: Task, sibling_id: Uuid) -> anyhow::Result<Uuid> {
        let id = task.id();
        identifiable::insert_before(&mut self.tasks, task, sibling_id)?;
        if let Some(&parent_id) = self.parent_of.get(&sibling_id) {
            self.attach_child(parent_id, id);
        }
        Ok(id)
    }

    /// Inserts a new task as a sibling right after `sibling_id` in the task order.
    /// If the sibling has a parent, the new task becomes a child of the same parent. This only
    /// ever inserts a new task, it never moves an existing one.
    ///
    /// # Errors
    ///
    /// Returns an error if `sibling_id` doesn't exist, or if `task`'s id is already used by
    /// another task in the project.
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::{project::Project, task::Task};
    ///
    /// let mut project = Project::new("World domination");
    /// let a = project.add_task(Task::new("Build an army"));
    /// let b = project.add_task(Task::new("Train troops"));
    /// let c = project.add_sibling_after(Task::new("Gather allies"), a).unwrap();
    ///
    /// let ids: Vec<_> = project.tasks().map(|t| t.id()).collect();
    /// assert_eq!(ids, vec![a, c, b]);
    /// ```
    pub fn add_sibling_after(&mut self, task: Task, sibling_id: Uuid) -> anyhow::Result<Uuid> {
        let id = task.id();
        identifiable::insert_after(&mut self.tasks, task, sibling_id)?;
        if let Some(&parent_id) = self.parent_of.get(&sibling_id) {
            self.attach_child(parent_id, id);
        }
        Ok(id)
    }

    /// Deletes a task and all references to it from the project. Any direct
    /// subtasks of the removed task are promoted to the removed task's own
    /// parent (or to top-level, if it had none).
    ///
    /// # Arguments
    ///
    /// * `id` - The [`Uuid`] of the task to remove.
    ///
    /// # Errors
    /// Returns an error if the task doesn't exist.
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::{project::Project, task::Task};
    ///
    /// let mut project = Project::new("World domination");
    /// let id = project.add_task(Task::new("Become world leader"));
    /// assert_eq!(project.tasks().count(), 1);
    /// assert!(project.rm_task(id).is_ok());
    /// assert_eq!(project.tasks().count(), 0);
    /// ```
    pub fn rm_task(&mut self, id: Uuid) -> anyhow::Result<Task> {
        let task = identifiable::remove_by_id(&mut self.tasks, id)
            .context("Tried removing a non existing task")?;

        // Remove all time relationships involving this task.
        for (succ, _) in self.succ.remove(&id).into_iter().flatten() {
            if let Some(preds) = self.pred.get_mut(&succ) {
                preds.retain(|(p, _)| *p != id);
            }
        }
        for (pred_, _) in self.pred.remove(&id).into_iter().flatten() {
            if let Some(succs) = self.succ.get_mut(&pred_) {
                succs.retain(|(s, _)| *s != id);
            }
        }

        // Remove subtask relationships. `id`'s own parent link is dropped, and any direct
        // children of `id` are promoted to `id`'s former parent (or to top-level if it had
        // none), via the same [`Self::detach_child`]/[`Self::attach_child`] pair
        // [`Self::add_subtask`] and [`Self::remove_subtask`] use.
        let former_parent = self.detach_child(id);
        if let Some(children) = self.children.remove(&id) {
            for child in children {
                match former_parent {
                    Some(parent) => self.attach_child(parent, child),
                    None => {
                        self.parent_of.remove(&child);
                    }
                }
            }
        }

        Ok(task)
    }

    /// Gets a reference to the task with the given [`Uuid`].
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::{project::Project, task::Task};
    ///
    /// let mut project = Project::new("World domination");
    /// let id = project.add_task(Task::new("Become world leader"));
    /// assert_eq!(project.task(id).unwrap().name(), "Become world leader");
    /// ```
    #[must_use]
    pub fn task(&self, id: Uuid) -> Option<&Task> {
        identifiable::find(&self.tasks, id)
    }

    /// Internal handle used to implement the `edit_task_*` methods below and other mutations
    /// that need direct field access. Not exposed publicly: every public edit goes through a
    /// method here that knows what else (ancestor sync, and so on) needs to happen alongside it.
    fn task_mut(&mut self, id: Uuid) -> Option<&mut Task> {
        identifiable::find_mut(&mut self.tasks, id)
    }

    /// Returns the tasks of the project in insertion order.
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::{project::Project, task::Task};
    ///
    /// let mut project = Project::new("World domination");
    /// project.add_task(Task::new("Become world leader"));
    /// assert_eq!(project.tasks().count(), 1);
    /// ```
    pub fn tasks(&self) -> impl Iterator<Item = &Task> {
        self.tasks.iter()
    }

    /// Adds a relationship between tasks, where one is the predecessor and the other a successor.
    ///
    /// # Arguments
    ///
    /// * `predecessor` - The [`Uuid`] of the predecessor task.
    /// * `successor` - The [`Uuid`] of the successor task.
    /// * `kind` - The type of relationship.
    ///
    /// # Errors
    /// Returns an error if either task doesn't exist, if the relationship already exists, if
    /// the relationship would create a cycle, or if one task is a subtask ancestor/descendant
    /// of the other.
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::{project::{Project, TimeRelationship}, task::Task};
    ///
    /// let mut project = Project::new("World domination");
    /// let pred = project.add_task(Task::new("Get rich"));
    /// let succ = project.add_task(Task::new("Become world leader"));
    /// project.add_time_relationship(pred, succ, TimeRelationship::default());
    ///
    /// assert_eq!(project.successors(pred).next().unwrap().name(), "Become world leader")
    /// ```
    pub fn add_time_relationship(
        &mut self,
        predecessor: Uuid,
        successor: Uuid,
        kind: TimeRelationship,
    ) -> anyhow::Result<()> {
        if !identifiable::contains(&self.tasks, predecessor)
            || !identifiable::contains(&self.tasks, successor)
        {
            bail!("Task not found");
        }

        if self
            .succ
            .get(&predecessor)
            .map(|e| e.iter().any(|(s, _)| *s == successor))
            .unwrap_or(false)
        {
            bail!("Relationship between tasks already exists");
        }

        self.validate_edge(predecessor, successor)?;

        self.add_one_edge(predecessor, successor, kind);
        Ok(())
    }

    /// Checks that adding a predecessor -> successor edge is legal: neither task is the other's
    /// subtask ancestor/descendant, and the edge wouldn't create a cycle. Shared by
    /// [`Self::add_time_relationship`] and [`Self::update_relationships`], which both add edges
    /// one at a time and need the same guard before each.
    fn validate_edge(&self, predecessor: Uuid, successor: Uuid) -> anyhow::Result<()> {
        self.reject_ancestor_descendant_pair(predecessor, successor)?;
        if self.would_cycle(successor, predecessor) {
            bail!("A cycle was detected between tasks {predecessor} and {successor}");
        }
        Ok(())
    }

    /// Removes a relationship between tasks.
    ///
    /// # Arguments
    ///
    /// * `predecessor` - The [`Uuid`] of the predecessor task.
    /// * `successor` - The [`Uuid`] of the successor task.
    ///
    /// # Errors
    /// Returns an error if no relationship exists between the tasks.
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::{project::{Project, TimeRelationship}, task::Task};
    ///
    /// let mut project = Project::new("World domination");
    /// let pred = project.add_task(Task::new("Get rich"));
    /// let succ = project.add_task(Task::new("Become world leader"));
    /// project.add_time_relationship(pred, succ, TimeRelationship::default());
    /// project.rm_time_relationship(pred, succ).unwrap();
    ///
    /// assert_eq!(project.successors(pred).count(), 0);
    /// ```
    pub fn rm_time_relationship(
        &mut self,
        predecessor: Uuid,
        successor: Uuid,
    ) -> anyhow::Result<()> {
        let exists = self
            .succ
            .get(&predecessor)
            .map(|e| e.iter().any(|(s, _)| *s == successor))
            .unwrap_or(false);
        if !exists {
            bail!("Tried to remove a relationship that doesn't exist");
        }
        self.remove_one_edge(predecessor, successor);
        Ok(())
    }

    /// Gets the successors of a given task.
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::{project::{Project, TimeRelationship}, task::Task};
    ///
    /// let mut project = Project::new("World domination");
    /// let pred = project.add_task(Task::new("Get rich"));
    /// let succ = project.add_task(Task::new("Become world leader"));
    /// project.add_time_relationship(pred, succ, TimeRelationship::default());
    ///
    /// assert_eq!(project.successors(pred).next().unwrap().name(), "Become world leader")
    /// ```
    pub fn successors(&self, id: Uuid) -> impl Iterator<Item = &Task> {
        self.succ
            .get(&id)
            .into_iter()
            .flatten()
            .filter_map(move |(succ_id, _)| identifiable::find(&self.tasks, *succ_id))
    }

    /// Gets the [`Uuid`]s of all successors for a given task.
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::{project::{Project, TimeRelationship}, task::Task};
    ///
    /// let mut project = Project::new("World domination");
    /// let pred = project.add_task(Task::new("Get rich"));
    /// let succ = project.add_task(Task::new("Become world leader"));
    /// project.add_time_relationship(pred, succ, TimeRelationship::default());
    ///
    /// assert_eq!(project.successors_ids(pred).next().unwrap(), succ)
    /// ```
    pub fn successors_ids(&self, id: Uuid) -> impl Iterator<Item = Uuid> {
        self.succ
            .get(&id)
            .into_iter()
            .flatten()
            .map(|(succ_id, _)| *succ_id)
    }

    /// Gets the predecessors of a given task.
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::{project::{Project, TimeRelationship}, task::Task};
    ///
    /// let mut project = Project::new("World domination");
    /// let pred = project.add_task(Task::new("Get rich"));
    /// let succ = project.add_task(Task::new("Become world leader"));
    /// project.add_time_relationship(pred, succ, TimeRelationship::default());
    ///
    /// assert_eq!(project.predecessors(succ).next().unwrap().name(), "Get rich")
    /// ```
    pub fn predecessors(&self, id: Uuid) -> impl Iterator<Item = &Task> {
        self.pred
            .get(&id)
            .into_iter()
            .flatten()
            .filter_map(move |(pred_id, _)| identifiable::find(&self.tasks, *pred_id))
    }

    /// Gets the [`Uuid`]s of all predecessors for a given task.
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::{project::{Project, TimeRelationship}, task::Task};
    ///
    /// let mut project = Project::new("World domination");
    /// let pred = project.add_task(Task::new("Get rich"));
    /// let succ = project.add_task(Task::new("Become world leader"));
    /// project.add_time_relationship(pred, succ, TimeRelationship::default());
    ///
    /// assert_eq!(project.predecessors_ids(succ).next().unwrap(), pred)
    /// ```
    pub fn predecessors_ids(&self, id: Uuid) -> impl Iterator<Item = Uuid> {
        self.pred
            .get(&id)
            .into_iter()
            .flatten()
            .map(|(pred_id, _)| *pred_id)
    }

    /// Sets the predecessors or successors of a task to exactly the given set of tasks.
    ///
    /// # Arguments
    ///
    /// * `task_id` - The [`Uuid`] of the task whose relationships need updating.
    /// * `ids` - The tasks to set as predecessors or successors.
    /// * `dir` - Whether to update predecessors or successors.
    /// * `kind` - The type of time relationship.
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// * Any task doesn't exist.
    /// * The update would create a cycle.
    /// * Any id in `ids` is a subtask ancestor/descendant of `task_id`.
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::{project::{Project, RelDir, TimeRelationship}, task::Task};
    ///
    /// let mut project = Project::new("World domination");
    /// let id0 = project.add_task(Task::new("Become world leader"));
    /// let id1 = project.add_task(Task::new("Get rich"));
    /// let id2 = project.add_task(Task::new("Be evil"));
    ///
    /// project.update_relationships(id2, &[id0, id1], RelDir::Predecessors, TimeRelationship::FinishToStart).unwrap();
    /// assert_eq!(project.predecessors(id2).count(), 2);
    /// ```
    pub fn update_relationships(
        &mut self,
        task_id: Uuid,
        ids: &[Uuid],
        dir: RelDir,
        kind: TimeRelationship,
    ) -> anyhow::Result<()> {
        if !identifiable::contains(&self.tasks, task_id) {
            bail!("Task {task_id} doesn't exist");
        }
        for &id in ids {
            if !identifiable::contains(&self.tasks, id) {
                bail!("Task {id} doesn't exist");
            }
        }

        let old: HashSet<Uuid> = match dir {
            RelDir::Predecessors => self.predecessors_ids(task_id).collect(),
            RelDir::Successors => self.successors_ids(task_id).collect(),
        };
        let new: HashSet<Uuid> = ids.iter().copied().collect();

        let to_add: Vec<Uuid> = ids.iter().filter(|i| !old.contains(i)).copied().collect();
        let to_remove: Vec<Uuid> = old.iter().filter(|i| !new.contains(i)).copied().collect();

        let mut added = Vec::new();
        for &i in &to_add {
            let (pred, succ) = match dir {
                RelDir::Predecessors => (i, task_id),
                RelDir::Successors => (task_id, i),
            };
            if let Err(e) = self.validate_edge(pred, succ) {
                for &(p, s) in &added {
                    self.remove_one_edge(p, s);
                }
                return Err(e);
            }
            self.add_one_edge(pred, succ, kind);
            added.push((pred, succ));
        }

        for &i in &to_remove {
            let (pred, succ) = match dir {
                RelDir::Predecessors => (i, task_id),
                RelDir::Successors => (task_id, i),
            };
            self.remove_one_edge(pred, succ);
        }

        Ok(())
    }

    /// Moves `id` right after `after_id` in the global task order, affecting display order.
    ///
    /// # Errors
    ///
    /// Returns an error if `id` or `after_id` doesn't exist, or if they're the same task (there's
    /// nothing to move relative to).
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::{project::Project, task::Task};
    ///
    /// let mut project = Project::new("World domination");
    /// let a = project.add_task(Task::new("Build an army"));
    /// let b = project.add_task(Task::new("Train troops"));
    /// let c = project.add_task(Task::new("Gather allies"));
    /// project.move_task_after(c, a).unwrap();
    ///
    /// let ids: Vec<_> = project.tasks().map(|t| t.id()).collect();
    /// assert_eq!(ids, vec![a, c, b]);
    /// ```
    pub fn move_task_after(&mut self, id: Uuid, after_id: Uuid) -> anyhow::Result<()> {
        identifiable::move_after(&mut self.tasks, id, after_id)
    }

    /// Adds a subtask to a given task, marking the child as a component of the parent.
    /// The parent task is completed when all children are completed.
    ///
    /// # Arguments
    ///
    /// * `parent_id` - The [`Uuid`] of the parent task.
    /// * `child_id` - The [`Uuid`] of the child subtask.
    ///
    /// # Errors
    ///
    /// Returns an error if either task doesn't exist.
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::{project::Project, task::Task};
    ///
    /// let mut project = Project::new("World domination");
    /// let parent = project.add_task(Task::new("Build a house"));
    /// let child1 = project.add_task(Task::new("Lay foundations"));
    /// let child2 = project.add_task(Task::new("Build roof"));
    ///
    /// project.add_subtask(parent, child1).unwrap();
    /// project.add_subtask(parent, child2).unwrap();
    /// assert_eq!(project.subtasks(parent).count(), 2);
    /// ```
    pub fn add_subtask(&mut self, parent_id: Uuid, child_id: Uuid) -> anyhow::Result<()> {
        if !identifiable::contains(&self.tasks, parent_id)
            || !identifiable::contains(&self.tasks, child_id)
        {
            bail!("Task not found");
        }
        if parent_id == child_id {
            bail!("A task cannot be a subtask of itself");
        }
        // No-op if already a child of this parent.
        if self.parent_of.get(&child_id) == Some(&parent_id) {
            return Ok(());
        }
        // Reject if parent is already a descendant of child (cycle).
        let mut current = parent_id;
        while let Some(&ancestor) = self.parent_of.get(&current) {
            if ancestor == child_id {
                bail!("Cannot make a task a subtask of one of its own descendants");
            }
            current = ancestor;
        }
        // Remove from any existing parent first.
        self.detach_child(child_id);
        self.attach_child(parent_id, child_id);
        Ok(())
    }

    /// Removes `child_id`'s parent link, if it has one, and cleans up the former parent's
    /// children list too (dropping the entry entirely once it's empty). Returns the former
    /// parent, or `None` if `child_id` wasn't anyone's subtask.
    fn detach_child(&mut self, child_id: Uuid) -> Option<Uuid> {
        let parent = self.parent_of.remove(&child_id)?;
        if let Some(children) = self.children.get_mut(&parent) {
            children.retain(|c| *c != child_id);
            if children.is_empty() {
                self.children.remove(&parent);
            }
        }
        Some(parent)
    }

    /// Records `child_id` as a subtask of `parent_id`. Doesn't check for an existing parent
    /// link; call [`Self::detach_child`] first if `child_id` might already have one.
    fn attach_child(&mut self, parent_id: Uuid, child_id: Uuid) {
        self.children.entry(parent_id).or_default().push(child_id);
        self.parent_of.insert(child_id, parent_id);
    }

    /// Removes a subtask relationship, promoting the child back to a top-level task.
    ///
    /// # Errors
    ///
    /// Returns an error if the task is not a subtask.
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::{project::Project, task::Task};
    ///
    /// let mut project = Project::new("World domination");
    /// let army = project.add_task(Task::new("Build an army"));
    /// let supplies = project.add_task(Task::new("Gather supplies"));
    /// project.add_subtask(army, supplies).unwrap();
    /// assert!(project.task_parent(supplies).is_some());
    ///
    /// project.remove_subtask(supplies).unwrap();
    /// assert!(project.task_parent(supplies).is_none());
    /// ```
    pub fn remove_subtask(&mut self, child_id: Uuid) -> anyhow::Result<()> {
        self.detach_child(child_id)
            .context("Task is not a subtask")?;
        Ok(())
    }

    /// Returns the parent [`Uuid`] of a subtask, or `None` if the task is at root level.
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::{project::Project, task::Task};
    ///
    /// let mut project = Project::new("World domination");
    /// let army = project.add_task(Task::new("Build an army"));
    /// let supplies = project.add_task(Task::new("Gather supplies"));
    ///
    /// assert!(project.task_parent(supplies).is_none());
    ///
    /// project.add_subtask(army, supplies).unwrap();
    /// assert_eq!(project.task_parent(supplies), Some(army));
    /// ```
    pub fn task_parent(&self, child_id: Uuid) -> Option<Uuid> {
        self.parent_of.get(&child_id).copied()
    }

    /// Gets the [`Uuid`]s of all subtasks of the given task.
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::{project::Project, task::Task};
    ///
    /// let mut project = Project::new("World domination");
    /// let parent = project.add_task(Task::new("Build a house"));
    /// let child = project.add_task(Task::new("Lay foundations"));
    /// assert_eq!(project.subtasks(parent).count(), 0);
    ///
    /// project.add_subtask(parent, child).unwrap();
    /// assert_eq!(project.subtasks(parent).count(), 1);
    /// ```
    pub fn subtasks(&self, parent_id: Uuid) -> impl Iterator<Item = Uuid> + '_ {
        self.children.get(&parent_id).into_iter().flatten().copied()
    }

    /// Expands `parent_id`'s own start/finish to encompass its direct children's. Only ever
    /// expands outward, never contracts, and has no effect if no child has start/finish dates.
    /// One level only: called by [`Self::sync_ancestors`] once per ancestor, walking up to the
    /// root, so a chain of parents all end up covering their descendants' dates.
    ///
    /// # Errors
    ///
    /// Returns an error if `parent_id` doesn't exist.
    fn sync_parent_dates(&mut self, parent_id: Uuid) -> anyhow::Result<()> {
        let earliest_start = self
            .subtasks(parent_id)
            .filter_map(|child_id| self.task(child_id).and_then(|t| t.start()))
            .min();
        let latest_finish = self
            .subtasks(parent_id)
            .filter_map(|child_id| self.task(child_id).and_then(|t| t.finish()))
            .max();

        if earliest_start.is_none() && latest_finish.is_none() {
            return Ok(());
        }

        let parent = self.task_mut(parent_id).context("Parent task not found")?;
        if let Some(start) = earliest_start
            && parent.start().is_none_or(|ps| start < ps)
        {
            let _ = parent.edit_start(start);
        }
        if let Some(finish) = latest_finish
            && parent.finish().is_none_or(|pf| finish > pf)
        {
            let _ = parent.edit_finish(finish);
        }
        Ok(())
    }

    /// Rolls a task's start/finish dates up through every ancestor, from its immediate parent to
    /// the root. Called automatically by [`Self::edit_task_start`], [`Self::edit_task_finish`],
    /// and [`Self::edit_task_duration`]; a top-level task with no parent is a no-op.
    fn sync_ancestors(&mut self, task_id: Uuid) {
        let mut current = task_id;
        while let Some(parent_id) = self.task_parent(current) {
            // Infallible here: `task_parent` only ever returns ids of tasks that exist.
            let _ = self.sync_parent_dates(parent_id);
            current = parent_id;
        }
    }

    /// Sets a task's start date, then rolls the change up through every ancestor so each one's
    /// own start/finish keeps covering all of its descendants. If the task has a finish date
    /// earlier than `start`, the finish date is pulled forward to match it instead of leaving a
    /// negative duration.
    ///
    /// # Errors
    ///
    /// Returns an error if `id` doesn't exist.
    ///
    /// # Example
    ///
    /// ```
    /// use chrono::Utc;
    /// use planter_core::{project::Project, task::Task};
    ///
    /// let mut project = Project::new("World domination");
    /// let army = project.add_task(Task::new("Build an army"));
    /// let supplies = project.add_task(Task::new("Gather supplies"));
    /// project.add_subtask(army, supplies).unwrap();
    ///
    /// let now = Utc::now();
    /// project.edit_task_start(supplies, now).unwrap();
    ///
    /// // `army`'s own start followed along automatically, no separate step needed.
    /// assert_eq!(project.task(army).unwrap().start(), Some(now));
    /// ```
    pub fn edit_task_start(&mut self, id: Uuid, start: DateTime<Utc>) -> anyhow::Result<()> {
        self.task_mut(id)
            .context("Task not found")?
            .edit_start(start)?;
        self.sync_ancestors(id);
        Ok(())
    }

    /// Sets a task's finish date, then rolls the change up through every ancestor so each one's
    /// own start/finish keeps covering all of its descendants. If the task has a start date
    /// later than `finish`, the start date is pulled back to match it instead of leaving a
    /// negative duration.
    ///
    /// # Errors
    ///
    /// Returns an error if `id` doesn't exist.
    ///
    /// # Example
    ///
    /// ```
    /// use chrono::Utc;
    /// use planter_core::{project::Project, task::Task};
    ///
    /// let mut project = Project::new("World domination");
    /// let army = project.add_task(Task::new("Build an army"));
    /// let supplies = project.add_task(Task::new("Gather supplies"));
    /// project.add_subtask(army, supplies).unwrap();
    ///
    /// let now = Utc::now();
    /// project.edit_task_finish(supplies, now).unwrap();
    ///
    /// assert_eq!(project.task(army).unwrap().finish(), Some(now));
    /// ```
    pub fn edit_task_finish(&mut self, id: Uuid, finish: DateTime<Utc>) -> anyhow::Result<()> {
        self.task_mut(id)
            .context("Task not found")?
            .edit_finish(finish)?;
        self.sync_ancestors(id);
        Ok(())
    }

    /// Sets a task's duration, then rolls the change up through every ancestor so each one's
    /// own start/finish keeps covering all of its descendants.
    ///
    /// # Errors
    ///
    /// Returns an error if `id` doesn't exist.
    ///
    /// # Example
    ///
    /// ```
    /// use chrono::Duration;
    /// use planter_core::{project::Project, task::Task};
    ///
    /// let mut project = Project::new("World domination");
    /// let task_id = project.add_task(Task::new("Build an army"));
    /// project.edit_task_duration(task_id, Duration::hours(4).try_into().unwrap()).unwrap();
    /// assert!(project.task(task_id).unwrap().duration().is_some());
    /// ```
    pub fn edit_task_duration(
        &mut self,
        id: Uuid,
        duration: NonNegativeDuration,
    ) -> anyhow::Result<()> {
        self.task_mut(id)
            .context("Task not found")?
            .edit_duration(duration);
        self.sync_ancestors(id);
        Ok(())
    }

    /// Edits a task's name.
    ///
    /// # Errors
    ///
    /// Returns an error if `id` doesn't exist.
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::{project::Project, task::Task};
    ///
    /// let mut project = Project::new("World domination");
    /// let id = project.add_task(Task::new("Become world leader"));
    /// project.edit_task_name(id, "Become world's biggest loser").unwrap();
    /// assert_eq!(project.task(id).unwrap().name(), "Become world's biggest loser");
    /// ```
    pub fn edit_task_name(&mut self, id: Uuid, name: impl Into<String>) -> anyhow::Result<()> {
        self.task_mut(id).context("Task not found")?.edit_name(name);
        Ok(())
    }

    /// Edits a task's description.
    ///
    /// # Errors
    ///
    /// Returns an error if `id` doesn't exist.
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::{project::Project, task::Task};
    ///
    /// let mut project = Project::new("World domination");
    /// let id = project.add_task(Task::new("Become world leader"));
    /// project.edit_task_description(id, "Step one of the plan").unwrap();
    /// assert_eq!(project.task(id).unwrap().description(), Some("Step one of the plan"));
    /// ```
    pub fn edit_task_description(
        &mut self,
        id: Uuid,
        description: impl Into<String>,
    ) -> anyhow::Result<()> {
        self.task_mut(id)
            .context("Task not found")?
            .edit_description(description);
        Ok(())
    }

    /// Clears a task's description, setting it to `None`.
    ///
    /// # Errors
    ///
    /// Returns an error if `id` doesn't exist.
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::{project::Project, task::Task};
    ///
    /// let mut project = Project::new("World domination");
    /// let id = project.add_task(Task::new("Become world leader"));
    /// project.edit_task_description(id, "Step one of the plan").unwrap();
    ///
    /// project.clear_task_description(id).unwrap();
    /// assert!(project.task(id).unwrap().description().is_none());
    /// ```
    pub fn clear_task_description(&mut self, id: Uuid) -> anyhow::Result<()> {
        self.task_mut(id)
            .context("Task not found")?
            .clear_description();
        Ok(())
    }

    /// Toggles a task's completed status.
    ///
    /// # Errors
    ///
    /// Returns an error if `id` doesn't exist.
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::{project::Project, task::Task};
    ///
    /// let mut project = Project::new("World domination");
    /// let id = project.add_task(Task::new("Become world leader"));
    /// assert!(!project.task(id).unwrap().completed());
    ///
    /// project.toggle_task_completed(id).unwrap();
    /// assert!(project.task(id).unwrap().completed());
    /// ```
    pub fn toggle_task_completed(&mut self, id: Uuid) -> anyhow::Result<()> {
        self.task_mut(id)
            .context("Task not found")?
            .toggle_completed();
        Ok(())
    }

    /// Returns the start date of the project.
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::project::Project;
    /// use chrono::Utc;
    ///
    /// let start_date = Utc::now();
    /// let project = Project::builder().name("World domination").start_date(start_date).build();
    /// assert_eq!(project.start_date(), Some(start_date));
    /// ```
    #[must_use]
    pub const fn start_date(&self) -> Option<DateTime<Utc>> {
        self.start_date
    }

    /// Returns the end date of the project.
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::project::Project;
    /// use chrono::Utc;
    ///
    /// let mut project = Project::new("World domination");
    /// assert!(project.end_date().is_none());
    /// let end_date = Utc::now();
    /// project.set_end_date(end_date);
    /// assert_eq!(project.end_date(), Some(end_date));
    /// ```
    #[must_use]
    pub const fn end_date(&self) -> Option<DateTime<Utc>> {
        self.end_date
    }

    /// Sets the end date of the project.
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::project::Project;
    /// use chrono::Utc;
    ///
    /// let mut project = Project::new("World domination");
    /// let end_date = Utc::now();
    /// project.set_end_date(end_date);
    /// assert_eq!(project.end_date(), Some(end_date));
    /// ```
    pub const fn set_end_date(&mut self, end_date: DateTime<Utc>) {
        self.end_date = Some(end_date);
    }

    /// Adds a resource to the project's pool and returns its stable [`Uuid`]. One-time purchase
    /// costs belong on the [`Resource`] itself (via [`Resource::add_purchase`]), recorded once
    /// regardless of how many tasks engage it via [`Self::assign_resource`].
    ///
    /// Adding a resource whose id already exists in the pool replaces it in place, without
    /// duplicating its slot in [`Self::resources`].
    ///
    /// # Arguments
    ///
    /// * `resource` - The resource to add to the project.
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::{resources::Resource, project::Project};
    ///
    /// let mut project = Project::new("World domination");
    /// project.add_resource(Resource::new("Stimpack".parse().unwrap()));
    /// assert_eq!(project.resources().count(), 1);
    /// ```
    pub fn add_resource(&mut self, resource: Resource) -> Uuid {
        let id = resource.id();
        identifiable::upsert(&mut self.resources, resource);
        id
    }

    /// Get a reference to a resource in the project, by its stable [`Uuid`].
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::{resources::Resource, project::Project};
    ///
    /// let mut project = Project::new("World domination");
    /// let id = project.add_resource(Resource::new("Stimpack".parse().unwrap()));
    ///
    /// assert!(project.resource(id).is_some());
    /// ```
    #[must_use]
    pub fn resource(&self, id: Uuid) -> Option<&Resource> {
        identifiable::find(&self.resources, id)
    }

    /// Remove a resource from the project, by its stable [`Uuid`]. Any task assignments that
    /// referred to it are dropped too, so no task is left pointing at a resource that no longer
    /// exists. The returned `(task_id, quantity)` pairs record what those were, so a caller
    /// that wants to undo the removal can restore them with [`Self::assign_resource_units`].
    ///
    /// # Errors
    ///
    /// Returns an error if `id` doesn't refer to a resource in [`Self::resources`].
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::{resources::Resource, project::Project};
    ///
    /// let mut project = Project::new("World domination");
    /// let id = project.add_resource(Resource::new("Stimpack".parse().unwrap()));
    ///
    /// assert!(project.resource(id).is_some());
    /// project.rm_resource(id).unwrap();
    /// assert!(project.resource(id).is_none());
    /// assert!(project.rm_resource(id).is_err());
    /// ```
    pub fn rm_resource(&mut self, id: Uuid) -> anyhow::Result<(Resource, Vec<(Uuid, u32)>)> {
        let resource =
            identifiable::remove_by_id(&mut self.resources, id).context("Resource not found")?;
        let assignments = self
            .tasks
            .iter_mut()
            .filter_map(|task| task.unassign(id).map(|quantity| (task.id(), quantity)))
            .collect();
        Ok((resource, assignments))
    }

    /// Get a mutable reference to a resource in the project, by its stable [`Uuid`].
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::{resources::Resource, project::Project};
    ///
    /// let mut project = Project::new("World domination");
    /// let id = project.add_resource(Resource::new("Crobwar".parse().unwrap()));
    ///
    /// // Fixing a typo in a resource's title:
    /// project.resource_mut(id).unwrap().set_title("Crowbar".parse().unwrap());
    /// assert_eq!(project.resource(id).unwrap().title(), "Crowbar");
    /// ```
    #[must_use]
    pub fn resource_mut(&mut self, id: Uuid) -> Option<&mut Resource> {
        identifiable::find_mut(&mut self.resources, id)
    }

    /// Returns the list of resources in the project.
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::{resources::Resource, project::Project};
    ///
    /// let mut project = Project::new("World domination");
    /// project.add_resource(Resource::new("Crowbar".parse().unwrap()));
    /// assert_eq!(project.resources().count(), 1);
    /// ```
    pub fn resources(&self) -> impl Iterator<Item = &Resource> {
        self.resources.iter()
    }

    /// Records a [`Purchase`] against a resource in the project's pool, returning its
    /// [`Purchase::id`]. The project-level counterpart to [`Resource::add_purchase`].
    ///
    /// # Errors
    ///
    /// Returns an error if `resource_id` doesn't refer to a resource in [`Self::resources`].
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::{resources::{Purchase, Resource}, project::Project, money::{Money, Currency}};
    ///
    /// let mut project = Project::new("Build");
    /// let stimpack = project.add_resource(Resource::new("Stimpack".parse().unwrap()));
    /// project.add_purchase(
    ///     stimpack,
    ///     Purchase::builder().quantity(10).unit_price(Money::from_minor_units(400, Currency::EUR)).build(),
    /// ).unwrap();
    /// assert_eq!(project.resource(stimpack).unwrap().purchases().count(), 1);
    /// ```
    pub fn add_purchase(&mut self, resource_id: Uuid, purchase: Purchase) -> anyhow::Result<Uuid> {
        Ok(self
            .resource_mut(resource_id)
            .context("Resource not found")?
            .add_purchase(purchase))
    }

    /// Removes a resource's purchase by id, returning it. The project-level counterpart to
    /// [`Resource::rm_purchase`].
    ///
    /// # Errors
    ///
    /// Returns an error if `resource_id` doesn't refer to a resource in [`Self::resources`], or
    /// if that resource has no purchase with `purchase_id`.
    pub fn rm_purchase(
        &mut self,
        resource_id: Uuid,
        purchase_id: Uuid,
    ) -> anyhow::Result<Purchase> {
        self.resource_mut(resource_id)
            .context("Resource not found")?
            .rm_purchase(purchase_id)
            .context("Purchase not found")
    }

    /// Mutable access to one of a resource's purchases, for editing it in place. The
    /// project-level counterpart to [`Resource::purchase_mut`].
    ///
    /// # Errors
    ///
    /// Returns an error if `resource_id` doesn't refer to a resource in [`Self::resources`], or
    /// if that resource has no purchase with `purchase_id`.
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::{resources::{Purchase, Resource}, project::Project, money::{Money, Currency}};
    ///
    /// let mut project = Project::new("Build");
    /// let stimpack = project.add_resource(Resource::new("Stimpack".parse().unwrap()));
    /// let purchase = project.add_purchase(
    ///     stimpack,
    ///     Purchase::builder().quantity(10).unit_price(Money::from_minor_units(400, Currency::EUR)).build(),
    /// ).unwrap();
    /// project.purchase_mut(stimpack, purchase).unwrap().set_unit_price(Money::from_minor_units(420, Currency::EUR));
    /// assert_eq!(
    ///     project.resource(stimpack).unwrap().purchases().next().unwrap().unit_price(),
    ///     Money::from_minor_units(420, Currency::EUR),
    /// );
    /// ```
    pub fn purchase_mut(
        &mut self,
        resource_id: Uuid,
        purchase_id: Uuid,
    ) -> anyhow::Result<&mut Purchase> {
        self.resource_mut(resource_id)
            .context("Resource not found")?
            .purchase_mut(purchase_id)
            .context("Purchase not found")
    }

    /// Records that `task_id` engages one unit of `resource_id`, checking that both the task and
    /// the resource exist in the project. For more than one unit, use
    /// [`Self::assign_resource_units`].
    ///
    /// A task engages any given resource at most once: a second call for the same resource
    /// replaces the quantity.
    ///
    /// # Errors
    ///
    /// Returns an error if `task_id` doesn't refer to a task in the project, or if
    /// `resource_id` doesn't refer to a resource in [`Self::resources`].
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::{project::Project, task::Task, resources::Resource};
    ///
    /// let mut project = Project::new("World domination");
    /// let task_id = project.add_task(Task::new("Find a crowbar"));
    /// let resource_id = project.add_resource(Resource::new("Crowbar".parse().unwrap()));
    ///
    /// project.assign_resource(task_id, resource_id).unwrap();
    /// assert_eq!(project.task(task_id).unwrap().assignments().count(), 1);
    /// ```
    pub fn assign_resource(&mut self, task_id: Uuid, resource_id: Uuid) -> anyhow::Result<()> {
        self.assign_resource_units(task_id, resource_id, NonZeroU32::MIN)
    }

    /// Records that `task_id` engages `units` of `resource_id`, checking that both the task and
    /// the resource exist in the project.
    ///
    /// A task engages any given resource at most once: a second call for the same resource
    /// replaces the quantity. `units` is how many of the resource the task draws at once, e.g.
    /// 2 of a 4-person crew, or 3 units of a material. To remove an assignment, use
    /// [`Self::unassign_resource`] instead of trying to assign zero units.
    ///
    /// # Errors
    ///
    /// Returns an error if `task_id` doesn't refer to a task in the project, or if
    /// `resource_id` doesn't refer to a resource in [`Self::resources`].
    pub fn assign_resource_units(
        &mut self,
        task_id: Uuid,
        resource_id: Uuid,
        units: NonZeroU32,
    ) -> anyhow::Result<()> {
        if !identifiable::contains(&self.resources, resource_id) {
            bail!("Resource {resource_id} not found in the project's pool");
        }

        let task = self.task_mut(task_id).context("Task not found")?;
        task.assign(resource_id, units);
        Ok(())
    }

    /// Removes `task_id`'s assignment for `resource_id`, returning the quantity it engaged. The
    /// counterpart to [`Self::assign_resource`].
    ///
    /// # Errors
    ///
    /// Returns an error if `task_id` doesn't refer to a task in the project, or if the task
    /// didn't engage `resource_id`.
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::{project::Project, task::Task, resources::Resource};
    /// use std::num::NonZeroU32;
    ///
    /// let mut project = Project::new("World domination");
    /// let task_id = project.add_task(Task::new("Find a stimpack"));
    /// let resource_id = project.add_resource(Resource::new("Stimpack".parse().unwrap()));
    /// project.assign_resource_units(task_id, resource_id, NonZeroU32::new(5).unwrap()).unwrap();
    ///
    /// assert_eq!(project.unassign_resource(task_id, resource_id).unwrap(), 5);
    /// assert!(project.unassign_resource(task_id, resource_id).is_err());
    /// assert_eq!(project.task(task_id).unwrap().assignments().count(), 0);
    /// ```
    pub fn unassign_resource(&mut self, task_id: Uuid, resource_id: Uuid) -> anyhow::Result<u32> {
        self.task_mut(task_id)
            .context("Task not found")?
            .unassign(resource_id)
            .context("Resource not assigned to task")
    }

    /// Sums the project's total cost: every resource's one-time
    /// [`purchase_cost`](Resource::purchase_cost), plus, for every task, each assignment's
    /// hourly cost over the task's duration (see [`Self::task_cost`]).
    ///
    /// Each amount is priced in its resource's own currency; amounts in different currencies are
    /// kept as separate entries, never combined. Arithmetic saturates instead of overflowing.
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::{project::Project, task::Task};
    ///
    /// let mut project = Project::new("World domination");
    /// project.add_task(Task::new("Become world leader"));
    /// assert!(project.total_cost().is_empty());
    /// ```
    #[must_use]
    pub fn total_cost(&self) -> MultiCurrencyAmount {
        let purchases: MultiCurrencyAmount =
            self.resources.iter().map(Resource::purchase_cost).sum();
        let usage: MultiCurrencyAmount = self.tasks().map(|task| task.cost(&self.resources)).sum();
        purchases + usage
    }

    /// The cost of a single task: each assignment's `hourly_rate * hours * quantity`, priced in
    /// the resource's own currency and grouped into a [`MultiCurrencyAmount`]. A resource with
    /// no rate, or an assignment whose resource isn't in the project, contributes nothing.
    /// One-time purchase costs aren't counted here; those belong to the resource.
    ///
    /// # Errors
    ///
    /// Returns an error if `task_id` doesn't refer to a task in the project.
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::{project::Project, task::Task};
    ///
    /// let mut project = Project::new("World domination");
    /// let task_id = project.add_task(Task::new("Become world leader"));
    /// assert!(project.task_cost(task_id).unwrap().is_empty());
    /// ```
    pub fn task_cost(&self, task_id: Uuid) -> anyhow::Result<MultiCurrencyAmount> {
        Ok(self
            .task(task_id)
            .context("Task not found")?
            .cost(&self.resources))
    }

    /// The total a single resource has cost the project: its one-time
    /// [`purchase_cost`](Resource::purchase_cost) plus its hourly cost across every task that
    /// engages it.
    ///
    /// Summing this over every resource gives the same figure as [`Self::total_cost`].
    ///
    /// # Errors
    ///
    /// Returns an error if `resource_id` doesn't refer to a resource in [`Self::resources`].
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::{project::Project, task::Task, resources::{Purchase, Resource}, money::{Currency, Money}};
    /// use chrono::Duration;
    ///
    /// let mut project = Project::new("Build");
    /// let digger_id = project.add_resource(
    ///     Resource::new("Crowbar".parse().unwrap()).at_hourly_rate(Money::from_minor_units(30, Currency::EUR)),
    /// );
    /// project.add_purchase(
    ///     digger_id,
    ///     Purchase::builder().quantity(1).unit_price(Money::from_minor_units(1_000, Currency::EUR)).build(),
    /// ).unwrap();
    ///
    /// let task_id = project.add_task(Task::new("Dig"));
    /// project.edit_task_duration(task_id, Duration::hours(4).try_into().unwrap()).unwrap();
    /// project.assign_resource(task_id, digger_id).unwrap();
    ///
    /// // 1000 purchased + 30 * 4h used
    /// assert_eq!(
    ///     project.resource_cost(digger_id).unwrap().in_currency(Currency::EUR),
    ///     Some(Money::from_minor_units(1_120, Currency::EUR)),
    /// );
    /// ```
    pub fn resource_cost(&self, resource_id: Uuid) -> anyhow::Result<MultiCurrencyAmount> {
        let resource = self.resource(resource_id).context("Resource not found")?;
        let usage: MultiCurrencyAmount = self
            .tasks()
            .filter_map(|task| {
                let quantity = task.assignment(resource_id)?;
                resource.usage_cost(task.duration_hours(), quantity)
            })
            .sum();
        Ok(resource.purchase_cost() + usage)
    }

    /// Adds a stakeholder to the project.
    ///
    /// # Arguments
    ///
    /// * `stakeholder` - The stakeholder to add to the project.
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::{stakeholders::Stakeholder, project::Project, person::Person};
    ///
    /// let mut project = Project::new("World domination");
    /// let person = Person::new("Margherita", "Hack").unwrap();
    /// project.add_stakeholder(Stakeholder::Individual {
    ///   person,
    ///   description: None,
    /// });
    /// assert_eq!(project.stakeholders().len(), 1);
    /// ```
    pub fn add_stakeholder(&mut self, stakeholder: Stakeholder) {
        self.stakeholders.push(stakeholder);
    }

    /// Returns a reference to the list of stakeholders associated with the project.
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::{stakeholders::Stakeholder, project::Project, person::Person};
    ///
    /// let mut project = Project::new("World domination");
    /// let person = Person::new("Margherita", "Hack").unwrap();
    /// project.add_stakeholder(Stakeholder::Individual {
    ///   person,
    ///   description: None,
    /// });
    /// assert_eq!(project.stakeholders().len(), 1);
    /// ```
    #[must_use]
    pub fn stakeholders(&self) -> &[Stakeholder] {
        &self.stakeholders
    }

    /// Removes a stakeholder from the project by index.
    ///
    /// # Arguments
    ///
    /// * `index` - The index of the stakeholder to remove.
    ///
    /// # Returns
    ///
    /// The removed stakeholder, or `None` if the index is out of bounds.
    ///
    /// # Example
    ///
    /// ```
    /// use planter_core::{stakeholders::Stakeholder, project::Project, person::Person};
    ///
    /// let mut project = Project::new("World domination");
    /// let person = Person::new("Margherita", "Hack").unwrap();
    /// project.add_stakeholder(Stakeholder::Individual { person, description: None });
    /// assert_eq!(project.stakeholders().len(), 1);
    /// let removed = project.rm_stakeholder(0);
    /// assert!(removed.is_some());
    /// assert_eq!(project.stakeholders().len(), 0);
    /// ```
    #[must_use]
    pub fn rm_stakeholder(&mut self, index: usize) -> Option<Stakeholder> {
        if index < self.stakeholders.len() {
            Some(self.stakeholders.remove(index))
        } else {
            None
        }
    }

    /// Rejects adding a time relationship between `a` and `b` if one is a subtask
    /// ancestor/descendant of the other. Shared by [`Self::add_time_relationship`] and
    /// [`Self::update_relationships`] so both public entry points enforce the same invariant.
    ///
    /// # Errors
    /// Returns an error if `a` is an ancestor of `b`, or vice versa.
    fn reject_ancestor_descendant_pair(&self, a: Uuid, b: Uuid) -> anyhow::Result<()> {
        if self.is_ancestor(a, b) || self.is_ancestor(b, a) {
            bail!(
                "Cannot add a predecessor/successor relationship between an ancestor and a descendant"
            );
        }
        Ok(())
    }

    /// Returns `true` if `ancestor_id` is an ancestor of `descendant_id` in the task tree.
    fn is_ancestor(&self, ancestor_id: Uuid, descendant_id: Uuid) -> bool {
        let mut seen = HashSet::new();
        let mut current = descendant_id;
        while let Some(parent) = self.task_parent(current) {
            if !seen.insert(parent) {
                break;
            }
            if parent == ancestor_id {
                return true;
            }
            current = parent;
        }
        false
    }

    /// BFS from `from` following successors. Returns `true` if `to` is reachable.
    fn would_cycle(&self, from: Uuid, to: Uuid) -> bool {
        let mut seen = HashSet::new();
        let mut q = VecDeque::new();
        q.push_back(from);
        while let Some(v) = q.pop_front() {
            if v == to {
                return true;
            }
            if seen.insert(v)
                && let Some(succs) = self.succ.get(&v)
            {
                for (s, _) in succs {
                    q.push_back(*s);
                }
            }
        }
        false
    }

    fn add_one_edge(&mut self, pred: Uuid, succ: Uuid, kind: TimeRelationship) {
        self.succ.entry(pred).or_default().push((succ, kind));
        self.pred.entry(succ).or_default().push((pred, kind));
    }

    fn remove_one_edge(&mut self, pred: Uuid, succ: Uuid) {
        if let Some(entries) = self.succ.get_mut(&pred) {
            entries.retain(|(s, _)| *s != succ);
            if entries.is_empty() {
                self.succ.remove(&pred);
            }
        }
        if let Some(entries) = self.pred.get_mut(&succ) {
            entries.retain(|(p, _)| *p != pred);
            if entries.is_empty() {
                self.pred.remove(&succ);
            }
        }
    }
}

#[cfg(test)]
/// Utilities to test `[Project]`
pub mod test_utils {
    use proptest::{collection, prelude::*};

    use crate::task::{Task, test_utils::task_strategy};

    use super::{Project, RelDir, TimeRelationship};

    const MAX_TASKS: usize = 100;
    const MIN_TASKS: usize = 5;

    /// Generate a random amount of randomly generated `[Tasks]`.
    pub fn tasks_strategy() -> impl Strategy<Value = Vec<Task>> {
        collection::vec(task_strategy(), MIN_TASKS..MAX_TASKS)
    }

    /// Generate a random `[Project]` with a linear chain of time relationships.
    pub fn project_graph_strategy() -> impl Strategy<Value = Project> {
        (".*", tasks_strategy()).prop_map(|(n, tasks)| {
            let mut project = Project::builder().name(n).build();
            let mut ids = Vec::new();
            for task in tasks {
                ids.push(project.add_task(task));
            }

            let mut previous = None;
            for &current in &ids {
                if let Some(prev) = previous {
                    project
                        .update_relationships(
                            prev,
                            &[current],
                            RelDir::Successors,
                            TimeRelationship::FinishToStart,
                        )
                        .unwrap();
                }
                previous = Some(current);
            }
            project
        })
    }

    /// Generate a random `[Project]` with no time relationships.
    pub fn project_strategy() -> impl Strategy<Value = Project> {
        (".*", tasks_strategy()).prop_map(|(n, tasks)| {
            let mut project = Project::builder().name(n).build();
            for task in tasks {
                project.add_task(task);
            }
            project
        })
    }
}

#[cfg(test)]
mod tests {
    use proptest::prelude::*;
    use rand::{RngExt, rng};

    use chrono::Utc;
    use std::num::NonZeroU32;
    use uuid::Uuid;

    use crate::{
        money::{Currency, Money, MultiCurrencyAmount},
        person::Person,
        project::{
            Project, RelDir, TimeRelationship,
            test_utils::{project_graph_strategy, project_strategy},
        },
        resources::{Purchase, Resource},
        stakeholders::Stakeholder,
        task::Task,
    };

    /// Shorthand for a non-zero assignment quantity in tests.
    fn nz(n: u32) -> std::num::NonZeroU32 {
        std::num::NonZeroU32::new(n).unwrap()
    }

    fn task_ids(project: &Project) -> Vec<Uuid> {
        project.tasks().map(|t| t.id()).collect()
    }

    proptest! {
        #[test]
        fn update_relationships_predecessor_rejects_circular_graphs(mut project in project_graph_strategy()) {
            let ids = task_ids(&project);
            if ids.len() < 2 { return Ok(()); }
            let last = *ids.last().unwrap();
            assert!(project.update_relationships(ids[0], &[last], RelDir::Predecessors, TimeRelationship::FinishToStart).is_err());
        }

        #[test]
        fn update_relationships_rejects_circular_graphs(mut project in project_graph_strategy()) {
            let ids = task_ids(&project);
            if ids.len() < 2 { return Ok(()); }
            let last = *ids.last().unwrap();
            assert!(project.update_relationships(last, &[ids[0]], RelDir::Successors, TimeRelationship::FinishToStart).is_err());
        }

        #[test]
        fn update_relationships_rejects_non_existent_ids(mut project in project_strategy()) {
            let ids = task_ids(&project);
            if ids.is_empty() { return Ok(()); }
            let fake = Uuid::new_v4();
            assert!(project.update_relationships(ids[0], &[fake], RelDir::Predecessors, TimeRelationship::FinishToStart).is_err());
            assert!(project.update_relationships(ids[0], &[fake], RelDir::Successors, TimeRelationship::FinishToStart).is_err());
        }

        #[test]
        fn update_relationships_predecessor_removes_them_if_input_is_empty(mut project in project_strategy()) {
            let ids = task_ids(&project);
            if ids.len() < 2 { return Ok(()); }
            let mut rng = rng();
            let idx1 = rng.random_range(0..ids.len());
            let mut idx2 = idx1;
            while idx2 == idx1 {
                idx2 = rng.random_range(0..ids.len());
            }

            project.update_relationships(ids[idx1], &[ids[idx2]], RelDir::Predecessors, TimeRelationship::FinishToStart).unwrap();
            project.update_relationships(ids[idx1], &[], RelDir::Predecessors, TimeRelationship::FinishToStart).unwrap();

            assert_eq!(project.predecessors(ids[idx1]).count(), 0);
        }

        #[test]
        fn update_relationships_predecessor_removes_ids_not_present_in_input(mut project in project_strategy()) {
            let ids = task_ids(&project);
            if ids.len() < 3 { return Ok(()); }
            let mut rng = rng();
            let idx1 = rng.random_range(0..ids.len());
            let mut idx2 = idx1;
            let mut idx3 = idx1;
            while idx2 == idx1 {
                idx2 = rng.random_range(0..ids.len());
            }
            while idx3 == idx1 || idx3 == idx2 {
                idx3 = rng.random_range(0..ids.len());
            }

            project.update_relationships(ids[idx1], &[ids[idx2], ids[idx3]], RelDir::Predecessors, TimeRelationship::FinishToStart).unwrap();
            project.update_relationships(ids[idx1], &[ids[idx2]], RelDir::Predecessors, TimeRelationship::FinishToStart).unwrap();

            let mut predecessors = project.predecessors(ids[idx1]);
            assert_eq!(predecessors.next().map(|t| t.name()), project.task(ids[idx2]).map(|t| t.name()));
            assert!(predecessors.next().is_none());
        }

        #[test]
        fn update_relationships_predecessor_works(mut project in project_strategy()) {
            let ids = task_ids(&project);
            if ids.len() < 2 { return Ok(()); }
            let mut rng = rng();
            let idx1 = rng.random_range(0..ids.len());
            let mut idx2 = idx1;
            while idx2 == idx1 {
                idx2 = rng.random_range(0..ids.len());
            }

            project.update_relationships(ids[idx1], &[ids[idx2]], RelDir::Predecessors, TimeRelationship::FinishToStart).unwrap();

            assert_eq!(project.predecessors(ids[idx1]).count(), 1);
            assert_eq!(
                project.predecessors(ids[idx1]).next().map(|t| t.name()),
                project.task(ids[idx2]).map(|t| t.name())
            );
        }

        #[test]
        fn update_relationships_works(mut project in project_strategy()) {
            let ids = task_ids(&project);
            if ids.len() < 2 { return Ok(()); }
            let mut rng = rng();
            let idx1 = rng.random_range(0..ids.len());
            let mut idx2 = idx1;
            while idx2 == idx1 {
                idx2 = rng.random_range(0..ids.len());
            }

            project.update_relationships(ids[idx1], &[ids[idx2]], RelDir::Successors, TimeRelationship::FinishToStart).unwrap();

            let mut successors = project.successors(ids[idx1]);
            assert_eq!(successors.next().map(|t| t.name()), project.task(ids[idx2]).map(|t| t.name()));
            assert!(successors.next().is_none());
        }

        #[test]
        fn update_relationships_removes_them_if_input_is_empty(mut project in project_strategy()) {
            let ids = task_ids(&project);
            if ids.len() < 2 { return Ok(()); }
            let mut rng = rng();
            let idx1 = rng.random_range(0..ids.len());
            let mut idx2 = idx1;
            while idx2 == idx1 {
                idx2 = rng.random_range(0..ids.len());
            }

            project.update_relationships(ids[idx1], &[ids[idx2]], RelDir::Successors, TimeRelationship::FinishToStart).unwrap();
            project.update_relationships(ids[idx1], &[], RelDir::Successors, TimeRelationship::FinishToStart).unwrap();

            assert_eq!(project.successors(ids[idx1]).count(), 0);
        }

        #[test]
        fn update_relationships_removes_ids_not_present_in_input(mut project in project_strategy()) {
            let ids = task_ids(&project);
            if ids.len() < 3 { return Ok(()); }
            let mut rng = rng();
            let idx1 = rng.random_range(0..ids.len());
            let mut idx2 = idx1;
            let mut idx3 = idx1;
            while idx2 == idx1 {
                idx2 = rng.random_range(0..ids.len());
            }
            while idx3 == idx1 || idx3 == idx2 {
                idx3 = rng.random_range(0..ids.len());
            }

            project.update_relationships(ids[idx1], &[ids[idx2], ids[idx3]], RelDir::Successors, TimeRelationship::FinishToStart).unwrap();
            project.update_relationships(ids[idx1], &[ids[idx2]], RelDir::Successors, TimeRelationship::FinishToStart).unwrap();

            let mut successors = project.successors(ids[idx1]);
            assert_eq!(successors.next().map(|t| t.name()), project.task(ids[idx2]).map(|t| t.name()));
            assert!(successors.next().is_none());
        }
    }

    #[test]
    fn update_relationships_rolls_back_partial_additions_on_cycle() {
        let mut project = Project::new("test");
        let a = project.add_task(Task::new("A"));
        let b = project.add_task(Task::new("B"));
        let c = project.add_task(Task::new("C"));
        let d = project.add_task(Task::new("D"));

        project
            .add_time_relationship(a, b, TimeRelationship::FinishToStart)
            .unwrap();
        project
            .add_time_relationship(b, c, TimeRelationship::FinishToStart)
            .unwrap();
        project
            .add_time_relationship(c, d, TimeRelationship::FinishToStart)
            .unwrap();

        let old_preds: Vec<Uuid> = project.predecessors_ids(c).collect();
        assert_eq!(old_preds, vec![b]);

        let result = project.update_relationships(
            c,
            &[a, d],
            RelDir::Predecessors,
            TimeRelationship::FinishToStart,
        );
        assert!(result.is_err());

        let preds: Vec<Uuid> = project.predecessors_ids(c).collect();
        assert_eq!(
            preds,
            vec![b],
            "predecessors should be unchanged after rollback"
        );
        assert!(
            !project.predecessors_ids(c).any(|i| i == a),
            "partially-added edge a→c should have been rolled back"
        );
    }

    #[test]
    fn update_relationships_handles_overlap() {
        let mut project = Project::new("test");
        let a = project.add_task(Task::new("A"));
        let b = project.add_task(Task::new("B"));
        let c = project.add_task(Task::new("C"));
        let d = project.add_task(Task::new("D"));

        project
            .update_relationships(
                c,
                &[a, b],
                RelDir::Predecessors,
                TimeRelationship::FinishToStart,
            )
            .unwrap();
        let preds: Vec<Uuid> = project.predecessors_ids(c).collect();
        assert!(preds.contains(&a), "should contain a, got {preds:?}");
        assert!(preds.contains(&b), "should contain b, got {preds:?}");

        project
            .update_relationships(
                c,
                &[b, d],
                RelDir::Predecessors,
                TimeRelationship::FinishToStart,
            )
            .unwrap();
        let preds: Vec<Uuid> = project.predecessors_ids(c).collect();
        assert!(preds.contains(&b));
        assert!(preds.contains(&d));
        assert!(!preds.contains(&a));
    }

    #[test]
    fn assign_resource_rejects_unknown_task_or_resource() {
        let mut project = Project::new("test");
        let task_id = project.add_task(Task::new("Dig foundation"));
        let resource_id = project.add_resource(Resource::new("Crowbar".parse().unwrap()));

        // Unknown resource.
        assert!(project.assign_resource(task_id, Uuid::new_v4()).is_err());
        // Unknown task.
        assert!(
            project
                .assign_resource(Uuid::new_v4(), resource_id)
                .is_err()
        );
        // Both known.
        assert!(project.assign_resource(task_id, resource_id).is_ok());
        assert_eq!(project.task(task_id).unwrap().assignments().count(), 1);
    }

    #[test]
    fn task_cost_and_resource_cost_error_for_unknown_ids() {
        let project = Project::new("test");
        assert!(project.task_cost(Uuid::new_v4()).is_err());
        assert!(project.resource_cost(Uuid::new_v4()).is_err());
    }

    #[test]
    fn unassign_resource_removes_the_assignment_or_errors() {
        let mut project = Project::new("test");
        let task_id = project.add_task(Task::new("Dig"));
        let id = project.add_resource(Resource::new("Crowbar".parse().unwrap()));

        project.assign_resource_units(task_id, id, nz(3)).unwrap();

        assert_eq!(project.unassign_resource(task_id, id).unwrap(), 3);
        assert_eq!(project.task(task_id).unwrap().assignments().count(), 0);

        // Second call: task exists but no longer engages the resource.
        assert!(project.unassign_resource(task_id, id).is_err());

        // Unknown task.
        assert!(project.unassign_resource(Uuid::new_v4(), id).is_err());
    }

    #[test]
    fn assigning_a_resource_a_task_already_engages_replaces_it() {
        let mut project = Project::new("test");
        let task_id = project.add_task(Task::new("Dig"));
        let id = project.add_resource(Resource::new("Crowbar".parse().unwrap()));

        project.assign_resource_units(task_id, id, nz(2)).unwrap();
        project.assign_resource(task_id, id).unwrap();

        let assignments: Vec<_> = project.task(task_id).unwrap().assignments().collect();
        assert_eq!(assignments, vec![(id, 1)]);
    }

    #[test]
    fn rm_resource_drops_dangling_assignments() {
        let mut project = Project::new("test");
        let task_id = project.add_task(Task::new("Find a crowbar"));

        let crowbar_id = project.add_resource(Resource::new("Crowbar".parse().unwrap()));
        let stimpack_id = project.add_resource(Resource::new("Stimpack".parse().unwrap()));

        project.assign_resource(task_id, crowbar_id).unwrap();
        project.assign_resource(task_id, stimpack_id).unwrap();
        assert_eq!(project.task(task_id).unwrap().assignments().count(), 2);

        let (_, dropped_assignments) = project.rm_resource(crowbar_id).unwrap();
        assert_eq!(dropped_assignments, vec![(task_id, 1)]);

        let remaining: Vec<_> = project.task(task_id).unwrap().assignments().collect();
        assert_eq!(remaining, vec![(stimpack_id, 1)]);
    }

    #[test]
    fn rm_resource_lets_a_caller_restore_its_assignments() {
        let mut project = Project::new("test");
        let task_id = project.add_task(Task::new("Dig"));
        let crowbar_id = project.add_resource(Resource::new("Crowbar".parse().unwrap()));
        project
            .assign_resource_units(task_id, crowbar_id, nz(3))
            .unwrap();

        let (removed, dropped_assignments) = project.rm_resource(crowbar_id).unwrap();
        let restored_id = project.add_resource(removed);

        for (task_id, quantity) in dropped_assignments {
            project
                .assign_resource_units(
                    task_id,
                    restored_id,
                    std::num::NonZeroU32::new(quantity).unwrap(),
                )
                .unwrap();
        }

        assert_eq!(
            project.task(task_id).unwrap().assignment(restored_id),
            Some(3)
        );
    }

    #[test]
    fn resources_are_iterated_in_insertion_order() {
        let mut project = Project::new("test");
        let a = project.add_resource(Resource::new("Crowbar".parse().unwrap()));
        let b = project.add_resource(Resource::new("Stimpack".parse().unwrap()));
        let c = project.add_resource(Resource::new("Excavator".parse().unwrap()));

        let ids: Vec<_> = project.resources().map(Resource::id).collect();
        assert_eq!(ids, vec![a, b, c]);
    }

    #[test]
    fn add_resource_with_an_existing_id_replaces_it_in_place() {
        let mut project = Project::new("test");
        let resource = Resource::new("Crowbar".parse().unwrap());
        let id = project.add_resource(resource.clone());

        let mut updated = resource;
        updated.set_title("Renamed crowbar".parse().unwrap());
        let same_id = project.add_resource(updated);

        assert_eq!(same_id, id);
        assert_eq!(project.resources().count(), 1);
        assert_eq!(project.resource(id).unwrap().title(), "Renamed crowbar");
    }

    #[test]
    fn add_task_with_an_existing_id_replaces_it_in_place() {
        let mut project = Project::new("test");
        let task = Task::new("Dig");
        let id = project.add_task(task.clone());

        let mut updated = task;
        updated.edit_name("Dig deeper");
        let same_id = project.add_task(updated);

        assert_eq!(same_id, id);
        assert_eq!(project.tasks().count(), 1);
        assert_eq!(project.task(id).unwrap().name(), "Dig deeper");
    }

    #[test]
    fn a_resource_can_be_retitled_in_place_without_disturbing_assignments() {
        let mut project = Project::new("test");
        let task_id = project.add_task(Task::new("Find a crowbar"));
        let id = project.add_resource(Resource::new("Crobwar".parse().unwrap()));
        project.assign_resource(task_id, id).unwrap();

        project
            .resource_mut(id)
            .unwrap()
            .set_title("Crowbar".parse().unwrap());

        assert_eq!(project.resource(id).unwrap().title(), "Crowbar");
        // The assignment is untouched: it never encoded the title.
        assert_eq!(project.task(task_id).unwrap().assignments().count(), 1);
    }

    fn name_strategy() -> impl Strategy<Value = String> {
        r"[a-zA-Z0-9]{1,30}"
    }

    proptest! {
        #[test]
        fn task_add_rm_lifecycle(mut project in project_strategy()) {
            let initial_count = project.tasks().count();
            let id = project.add_task(Task::new("new task"));
            assert_eq!(project.tasks().count(), initial_count + 1);
            project.rm_task(id).unwrap();
            assert_eq!(project.tasks().count(), initial_count);
            for task in project.tasks() {
                assert_ne!(task.name(), "new task");
            }
        }

        #[test]
        fn rm_task_cleans_subtask_relationships(name in name_strategy()) {
            let mut project = Project::new(name);
            let parent = project.add_task(Task::new("parent"));
            let child = project.add_task(Task::new("child"));
            project.add_subtask(parent, child).unwrap();
            assert_eq!(project.subtasks(parent).collect::<Vec<_>>(), vec![child]);
            project.rm_task(parent).unwrap();
            assert!(project.subtasks(parent).next().is_none());
            // The removed task had no parent of its own, so its orphaned
            // child is promoted to top-level rather than left dangling.
            assert!(project.task_parent(child).is_none());
        }

        #[test]
        fn rm_task_promotes_orphaned_children_to_grandparent(name in name_strategy()) {
            let mut project = Project::new(name);
            let grandparent = project.add_task(Task::new("grandparent"));
            let parent = project.add_task(Task::new("parent"));
            let child = project.add_task(Task::new("child"));
            project.add_subtask(grandparent, parent).unwrap();
            project.add_subtask(parent, child).unwrap();

            project.rm_task(parent).unwrap();

            assert_eq!(project.task_parent(child), Some(grandparent));
            assert!(project.subtasks(grandparent).collect::<Vec<_>>().contains(&child));
        }

        #[test]
        fn resource_add_rm_lifecycle(name in name_strategy()) {
            let mut project = Project::new(name);
            assert_eq!(project.resources().count(), 0);
            let stimpack_id = project.add_resource(Resource::new("Stimpack".parse().unwrap()));
            assert_eq!(project.resources().count(), 1);
            let crowbar_id = project.add_resource(Resource::new("Crowbar".parse().unwrap()));
            assert_eq!(project.resources().count(), 2);
            let (removed, _) = project.rm_resource(stimpack_id).unwrap();
            assert_eq!(removed.title(), "Stimpack");
            assert_eq!(project.resources().count(), 1);
            assert_eq!(project.resource(crowbar_id).unwrap().title(), "Crowbar");
        }

        #[test]
        fn total_cost_is_purchases_plus_task_usage(
            rate1 in 0u64..1000, hours1 in 0i64..1000, qty in 0u32..1000, unit_price in 0u64..1000,
            rate2 in 0u64..1000, hours2 in 0i64..1000,
        ) {
            let mut project = Project::new("test");

            let intern1_id = project.add_resource(Resource::new("Intern".parse().unwrap()).at_hourly_rate(Money::from_minor_units(rate1, Currency::EUR)));
            let intern2_id = project.add_resource(Resource::new("Intern".parse().unwrap()).at_hourly_rate(Money::from_minor_units(rate2, Currency::EUR)));

            // A material's purchase cost is counted once, at the project level. A task drawing
            // on it adds nothing.
            let mut material = Resource::new("Stimpack".parse().unwrap());
            material.add_purchase(Purchase::builder().quantity(qty).unit_price(Money::from_minor_units(unit_price, Currency::EUR)).build());
            let material_id = project.add_resource(material);

            let mut task1 = Task::new("task 1");
            task1.edit_duration(chrono::Duration::hours(hours1).try_into().unwrap());
            task1.assign(intern1_id, nz(1));
            if let Some(qty) = NonZeroU32::new(qty) {
                task1.assign(material_id, qty);
            }

            let mut task2 = Task::new("task 2");
            task2.edit_duration(chrono::Duration::hours(hours2).try_into().unwrap());
            task2.assign(intern2_id, nz(1));

            project.add_task(task1);
            project.add_task(task2);

            let hours1_u64 = u64::try_from(hours1).unwrap();
            let hours2_u64 = u64::try_from(hours2).unwrap();
            let expected: MultiCurrencyAmount =
                Money::from_minor_units(rate1 * hours1_u64 + rate2 * hours2_u64 + u64::from(qty) * unit_price, Currency::EUR).into();

            assert_eq!(project.total_cost(), expected);

            // total_cost decomposes two ways, both equal to it.
            let task_ids: Vec<_> = project.tasks().map(|t| t.id()).collect();
            let resource_ids: Vec<_> = project.resources().map(|r| r.id()).collect();

            let by_task_and_purchases: MultiCurrencyAmount = task_ids
                .iter()
                .map(|&id| project.task_cost(id).unwrap())
                .chain(project.resources().map(Resource::purchase_cost))
                .sum();
            assert_eq!(by_task_and_purchases, expected);

            let by_resource: MultiCurrencyAmount = resource_ids
                .iter()
                .map(|&id| project.resource_cost(id).unwrap())
                .sum();
            assert_eq!(by_resource, expected);
        }

        #[test]
        fn total_cost_keeps_different_resource_currencies_separate(
            rate1 in 1u64..1000, hours1 in 1i64..1000,
            rate2 in 1u64..1000, hours2 in 1i64..1000,
        ) {
            let mut project = Project::new("test");

            let intern1_id = project.add_resource(Resource::new("Intern".parse().unwrap()).at_hourly_rate(Money::from_minor_units(rate1, Currency::EUR)));
            let intern2_id = project.add_resource(
                Resource::new("Intern".parse().unwrap())
                    .at_hourly_rate(Money::from_minor_units(rate2, Currency::USD)),
            );

            let mut task1 = Task::new("task 1");
            task1.edit_duration(chrono::Duration::hours(hours1).try_into().unwrap());
            task1.assign(intern1_id, nz(1));

            let mut task2 = Task::new("task 2");
            task2.edit_duration(chrono::Duration::hours(hours2).try_into().unwrap());
            task2.assign(intern2_id, nz(1));

            project.add_task(task1);
            project.add_task(task2);

            let total = project.total_cost();
            assert_eq!(total.iter().count(), 2);
            assert_eq!(total.in_currency(Currency::EUR), Some(Money::from_minor_units(rate1 * u64::try_from(hours1).unwrap(), Currency::EUR)));
            assert_eq!(
                total.in_currency(Currency::USD),
                Some(Money::from_minor_units(rate2 * u64::try_from(hours2).unwrap(), Currency::USD)),
            );
        }

        #[test]
        fn stakeholder_add_increases_count(name in name_strategy(), first in "[a-zA-Z]{1,50}", last in "[a-zA-Z]{1,50}") {
            let mut project = Project::new(name);
            let p = Person::new(&first, &last).unwrap();
            project.add_stakeholder(Stakeholder::Individual { person: p, description: None });
            assert_eq!(project.stakeholders().len(), 1);
        }

        #[test]
        fn rm_stakeholder_removes_and_returns(name in name_strategy(), first in "[a-zA-Z]{1,50}", last in "[a-zA-Z]{1,50}") {
            let mut project = Project::new(name);
            let p = Person::new(&first, &last).unwrap();
            project.add_stakeholder(Stakeholder::Individual { person: p.clone(), description: None });
            assert_eq!(project.stakeholders().len(), 1);
            let removed = project.rm_stakeholder(0);
            assert!(removed.is_some());
            assert_eq!(project.stakeholders().len(), 0);
            assert!(project.rm_stakeholder(0).is_none());
        }

        #[test]
        fn add_time_relationship_works(mut project in project_strategy()) {
            let ids = task_ids(&project);
            if ids.len() < 2 { return Ok(()); }
            let mut rng = rand::rng();
            let p = rng.random_range(0..ids.len());
            let mut s = p;
            while s == p {
                s = rng.random_range(0..ids.len());
            }

            project.add_time_relationship(ids[p], ids[s], TimeRelationship::FinishToStart).unwrap();
            let succs: Vec<_> = project.successors_ids(ids[p]).collect();
            assert!(succs.contains(&ids[s]), "successors({}) should contain {}", ids[p], ids[s]);
            let preds: Vec<_> = project.predecessors_ids(ids[s]).collect();
            assert!(preds.contains(&ids[p]), "predecessors({}) should contain {}", ids[s], ids[p]);
        }

        #[test]
        fn add_time_relationship_rejects_duplicate(mut project in project_strategy()) {
            let ids = task_ids(&project);
            if ids.len() < 2 { return Ok(()); }
            let mut rng = rand::rng();
            let p = rng.random_range(0..ids.len());
            let mut s = p;
            while s == p {
                s = rng.random_range(0..ids.len());
            }

            project.add_time_relationship(ids[p], ids[s], TimeRelationship::FinishToStart).unwrap();
            assert!(
                project.add_time_relationship(ids[p], ids[s], TimeRelationship::FinishToStart).is_err(),
                "duplicate edge should be rejected"
            );
        }

        #[test]
        fn rm_time_relationship_works(mut project in project_strategy()) {
            let ids = task_ids(&project);
            if ids.len() < 2 { return Ok(()); }
            let mut rng = rand::rng();
            let p = rng.random_range(0..ids.len());
            let mut s = p;
            while s == p {
                s = rng.random_range(0..ids.len());
            }

            project.add_time_relationship(ids[p], ids[s], TimeRelationship::FinishToStart).unwrap();
            project.rm_time_relationship(ids[p], ids[s]).unwrap();
            let succs: Vec<_> = project.successors_ids(ids[p]).collect();
            assert!(!succs.contains(&ids[s]), "successors({}) should not contain {}", ids[p], ids[s]);
        }

        #[test]
        fn add_subtask_works(mut project in project_strategy()) {
            let ids = task_ids(&project);
            if ids.len() < 2 { return Ok(()); }
            let mut rng = rand::rng();
            let p = rng.random_range(0..ids.len());
            let mut c = p;
            while c == p {
                c = rng.random_range(0..ids.len());
            }

            project.add_subtask(ids[p], ids[c]).unwrap();
            assert!(project.subtasks(ids[p]).any(|s| s == ids[c]), "subtasks({}) should contain {}", ids[p], ids[c]);
        }

        #[test]
        fn a_resource_keeps_its_id_and_purchases_across_a_retitle(res_title in name_strategy(), qty in 1u32..1000, price in 1u64..1000) {
            let mut project = Project::new("project");
            let mut resource = Resource::new(res_title.parse().unwrap());
            resource.add_purchase(
                Purchase::builder()
                    .quantity(qty)
                    .unit_price(Money::from_minor_units(price, Currency::USD))
                    .build(),
            );
            let id = project.add_resource(resource);

            let retitled = format!("{res_title} (updated)");
            project.resource_mut(id).unwrap().set_title(retitled.parse().unwrap());

            let resource = project.resource(id).unwrap();
            assert_eq!(resource.id(), id);
            assert_eq!(
                resource.purchases().next().unwrap().unit_price(),
                Money::from_minor_units(price, Currency::USD),
            );
            assert_eq!(resource.purchases().count(), 1);
            assert_eq!(resource.purchases().next().unwrap().quantity(), qty);
            assert_eq!(resource.title(), retitled);
        }

        #[test]
        fn add_subtask_rejects_invalid_ids(name in name_strategy()) {
            let mut project = Project::new(name);
            let task = project.add_task(Task::new("only task"));
            let fake = Uuid::new_v4();
            assert!(project.subtasks(fake).next().is_none());
            assert!(project.add_subtask(fake, task).is_err());
            assert!(project.add_subtask(task, fake).is_err());
        }

        #[test]
        fn rm_time_relationship_rejects_invalid_ids(mut project in project_strategy()) {
            let ids = task_ids(&project);
            if ids.is_empty() { return Ok(()); }
            let fake = Uuid::new_v4();
            assert!(project.rm_time_relationship(ids[0], fake).is_err());
            assert!(project.rm_time_relationship(fake, ids[0]).is_err());
        }

        #[test]
        fn rm_task_rejects_invalid_id(name in name_strategy()) {
            let mut project = Project::new(name);
            let fake = Uuid::new_v4();
            assert!(project.rm_task(fake).is_err());
        }

        #[test]
        fn total_cost_counts_a_personnel_resource_with_a_rate(name in name_strategy(), rate in 0u64..1000, hours in 0i64..1000) {
            let mut project = Project::new(name);
            let consultant_id = project.add_resource(
                Resource::new("Margherita Hack".parse().unwrap())
                    .with_contact(Stakeholder::individual(Person::new("Margherita", "Hack").unwrap(), None))
                    .at_hourly_rate(Money::from_minor_units(rate, Currency::EUR)),
            );

            let task_id = project.add_task(Task::new("Consult"));
            project
                .edit_task_duration(task_id, chrono::Duration::hours(hours).try_into().unwrap())
                .unwrap();
            project.assign_resource(task_id, consultant_id).unwrap();

            let expected = Money::from_minor_units(rate * u64::try_from(hours).unwrap(), Currency::EUR);
            assert_eq!(project.total_cost(), expected.into());
        }
    }

    #[test]
    fn total_cost_is_zero_for_empty_project() {
        let project = Project::new("test");
        assert!(project.total_cost().is_empty());
    }

    #[test]
    fn add_time_relationship_rejects_ancestor_descendant_pair() {
        let mut project = Project::new("test");
        let parent = project.add_task(Task::new("parent"));
        let child = project.add_task(Task::new("child"));
        project.add_subtask(parent, child).unwrap();

        assert!(
            project
                .add_time_relationship(parent, child, TimeRelationship::FinishToStart)
                .is_err(),
            "should reject a time relationship between a task and its own subtask descendant"
        );
        assert!(
            project
                .add_time_relationship(child, parent, TimeRelationship::FinishToStart)
                .is_err(),
            "should reject a time relationship between a task and its own subtask ancestor"
        );
    }

    #[test]
    fn add_time_relationship_rejects_invalid_ids() {
        let mut project = Project::new("test");
        let task = project.add_task(Task::new("task"));
        let fake = Uuid::new_v4();
        assert!(
            project
                .add_time_relationship(fake, task, TimeRelationship::FinishToStart)
                .is_err()
        );
        assert!(
            project
                .add_time_relationship(task, fake, TimeRelationship::FinishToStart)
                .is_err()
        );
    }

    #[test]
    fn add_sibling_before_rejects_an_unknown_sibling() {
        let mut project = Project::new("World domination");
        let a = project.add_task(Task::new("Build an army"));
        let fake = Uuid::new_v4();

        assert!(
            project
                .add_sibling_before(Task::new("Train troops"), fake)
                .is_err()
        );
        assert_eq!(project.tasks().map(|t| t.id()).collect::<Vec<_>>(), vec![a]);
    }

    #[test]
    fn add_sibling_before_rejects_an_id_already_in_the_project() {
        let mut project = Project::new("World domination");
        let a = project.add_task(Task::new("Build an army"));
        let existing = project.task(a).unwrap().clone();

        assert!(project.add_sibling_before(existing, a).is_err());
        assert_eq!(project.tasks().count(), 1);
    }

    #[test]
    fn add_sibling_after_rejects_an_id_already_in_the_project() {
        let mut project = Project::new("World domination");
        let a = project.add_task(Task::new("Build an army"));
        let existing = project.task(a).unwrap().clone();

        assert!(project.add_sibling_after(existing, a).is_err());
        assert_eq!(project.tasks().count(), 1);
    }

    #[test]
    fn move_task_after_rejects_nonexistent_ids() {
        let mut project = Project::new("World domination");
        let a = project.add_task(Task::new("Build an army"));
        let fake = Uuid::new_v4();

        assert!(project.move_task_after(fake, a).is_err());
        assert!(project.move_task_after(a, fake).is_err());
    }

    #[test]
    fn move_task_after_rejects_self() {
        let mut project = Project::new("World domination");
        let a = project.add_task(Task::new("Build an army"));

        assert!(project.move_task_after(a, a).is_err());
    }

    #[test]
    fn remove_subtask_rejects_non_subtask() {
        let mut project = Project::new("World domination");
        let task = project.add_task(Task::new("Do something"));
        assert!(project.remove_subtask(task).is_err());
    }

    proptest! {
        #[test]
        fn add_sibling_before_inserts_correctly(mut project in project_strategy()) {
            let ids = task_ids(&project);
            if ids.len() < 2 { return Ok(()); }
            let mut rng = rand::rng();
            let idx = rng.random_range(0..ids.len());

            let sibling_id = ids[idx];
            let new_id = project.add_sibling_before(Task::new("Minion"), sibling_id).unwrap();

            let ordered_ids: Vec<Uuid> = project.tasks().map(|t| t.id()).collect();
            let new_pos = ordered_ids.iter().position(|&id| id == new_id).unwrap();
            let sibling_pos = ordered_ids.iter().position(|&id| id == sibling_id).unwrap();
            assert_eq!(new_pos, sibling_pos - 1);
        }

        #[test]
        fn add_sibling_after_inserts_correctly(mut project in project_strategy()) {
            let ids = task_ids(&project);
            if ids.len() < 2 { return Ok(()); }
            let mut rng = rand::rng();
            let idx = rng.random_range(0..ids.len());

            let sibling_id = ids[idx];
            let new_id = project.add_sibling_after(Task::new("Minion"), sibling_id).unwrap();

            let ordered_ids: Vec<Uuid> = project.tasks().map(|t| t.id()).collect();
            let new_pos = ordered_ids.iter().position(|&id| id == new_id).unwrap();
            let sibling_pos = ordered_ids.iter().position(|&id| id == sibling_id).unwrap();
            assert_eq!(new_pos, sibling_pos + 1);
        }

        #[test]
        fn add_sibling_inherits_parent(mut project in project_strategy()) {
            let ids = task_ids(&project);
            if ids.len() < 3 { return Ok(()); }
            let mut rng = rand::rng();
            let parent_idx = rng.random_range(0..ids.len());
            let child_idx = rng.random_range(0..ids.len());
            if parent_idx == child_idx { return Ok(()); }

            project.add_subtask(ids[parent_idx], ids[child_idx]).unwrap();
            let new_id = project
                .add_sibling_before(Task::new("Minion"), ids[child_idx])
                .unwrap();

            assert_eq!(project.task_parent(new_id), Some(ids[parent_idx]));
            let children: Vec<Uuid> = project.subtasks(ids[parent_idx]).collect();
            assert!(children.contains(&new_id));
        }

        #[test]
        fn move_task_after_reorders_correctly(mut project in project_strategy()) {
            let ids = task_ids(&project);
            if ids.len() < 3 { return Ok(()); }
            let mut rng = rand::rng();
            let idx = rng.random_range(0..ids.len());
            let mut after_idx = rng.random_range(0..ids.len());
            while after_idx == idx {
                after_idx = rng.random_range(0..ids.len());
            }

            project.move_task_after(ids[idx], ids[after_idx]).unwrap();
            let new_ids: Vec<Uuid> = project.tasks().map(|t| t.id()).collect();

            let task_pos = new_ids.iter().position(|&id| id == ids[idx]).unwrap();
            let after_pos = new_ids.iter().position(|&id| id == ids[after_idx]).unwrap();
            assert_eq!(task_pos, after_pos + 1);
        }

        #[test]
        fn remove_subtask_promotes_to_top_level(mut project in project_strategy()) {
            let ids = task_ids(&project);
            if ids.len() < 2 { return Ok(()); }
            let mut rng = rand::rng();
            let parent_idx = rng.random_range(0..ids.len());
            let child_idx = rng.random_range(0..ids.len());
            if parent_idx == child_idx { return Ok(()); }

            project.add_subtask(ids[parent_idx], ids[child_idx]).unwrap();
            assert!(project.task_parent(ids[child_idx]).is_some());
            project.remove_subtask(ids[child_idx]).unwrap();

            assert!(project.task_parent(ids[child_idx]).is_none());
            assert!(project.subtasks(ids[parent_idx]).next().is_none());
        }

        #[test]
        fn editing_a_childs_dates_expands_its_ancestors(
            mut project in project_strategy(),
            start_offset in 0..1_000_000i64,
            finish_offset in 0..1_000_000i64,
        ) {
            let ids = task_ids(&project);
            if ids.len() < 3 { return Ok(()); }
            let mut rng = rand::rng();
            let parent_idx = rng.random_range(0..ids.len());
            let child1_idx = rng.random_range(0..ids.len());
            let child2_idx = rng.random_range(0..ids.len());
            if child1_idx == parent_idx || child2_idx == parent_idx || child1_idx == child2_idx {
                return Ok(());
            }

            project.add_subtask(ids[parent_idx], ids[child1_idx]).unwrap();
            project.add_subtask(ids[parent_idx], ids[child2_idx]).unwrap();

            let now = Utc::now();
            let child1_start = now - chrono::Duration::milliseconds(start_offset);
            let child2_finish = now + chrono::Duration::milliseconds(finish_offset);
            project.edit_task_start(ids[child1_idx], child1_start).unwrap();
            project.edit_task_finish(ids[child2_idx], child2_finish).unwrap();

            assert_eq!(project.task(ids[parent_idx]).unwrap().start(), Some(child1_start));
            assert_eq!(project.task(ids[parent_idx]).unwrap().finish(), Some(child2_finish));
        }
    }

    #[test]
    fn ancestor_sync_has_no_effect_when_child_has_no_dates() {
        let mut project = Project::new("World domination");
        let army = project.add_task(Task::new("Build an army"));
        let supplies = project.add_task(Task::new("Gather supplies"));
        project.add_subtask(army, supplies).unwrap();

        let now = Utc::now();
        project.edit_task_start(army, now).unwrap();

        assert_eq!(project.task(army).unwrap().start(), Some(now));
        assert!(project.task(army).unwrap().finish().is_none());
    }
}

#[cfg(all(test, feature = "serde"))]
mod serde_tests {
    use proptest::prelude::*;

    use crate::project::Project;
    use crate::project::test_utils::project_strategy;

    proptest! {
        #[test]
        fn serde_roundtrip(p in project_strategy()) {
            let json = serde_json::to_string(&p).unwrap();
            let deserialized: Project = serde_json::from_str(&json).unwrap();
            let json2 = serde_json::to_string(&deserialized).unwrap();
            let v1: serde_json::Value = serde_json::from_str(&json).unwrap();
            let v2: serde_json::Value = serde_json::from_str(&json2).unwrap();
            assert_eq!(v1, v2, "serde roundtrip must produce equivalent JSON");
        }
    }
}