tix-tracker 0.11.0

//! The single owner of project behaviour (mission
//! `first-class-projects-01M3BYBW`, WP02).
//!
//! Everything about a project lives here: identity and resolution, the registry
//! lifecycle (create / edit / delete / list), derived membership and the index
//! that makes a project filter a bucket lookup, the association mutations, and
//! missing-reference diagnosis. Surfaces call this rather than re-deriving,
//! because a second identity resolver or a stored membership index is exactly
//! the divergence the mission's charter escalates (C-006, NFR-001).
//!
//! ## What this module deliberately does not do
//!
//! - **It touches no files.** It takes an in-memory [`Config`] and an in-memory
//!   issue set, and returns values. Storage owns the write; this module owns the
//!   rule. The whole surface is therefore testable with no `Store` and no
//!   `tempfile` (T010 step 4).
//! - **It does not know about the issue model.** [`ProjectNode`] is the minimum
//!   an issue must expose — its number, title, status, and its `projects` id
//!   list — and WP03 implements it for [`crate::model::Issue`] in `src/model.rs`
//!   (this mission's WP03 owns that file), exactly as the hierarchy service's
//!   `HierarchyNode` is implemented there. WP02 is forbidden from touching
//!   `src/model.rs`, so the service is defined against the shape WP03 provides.
//! - **It never mutates or returns a whole `Issue`.** [`associate`] and
//!   [`dissociate`] return a [`ProjectChange`]: the resulting association list
//!   plus the History event to append. Storage applies it. That is the boundary
//!   that keeps this module model-free.
//! - **It stores no membership.** A project's members are derived by inverting
//!   the issues' association lists, never persisted (data-model §4, C-003).
//! - **It does not compute progress or health.** `ProjectProgress` and
//!   `ProjectHealth` are WP04's, added to this module additively; the single
//!   `health` operation the contract names lands there (contract §2).
//!
//! ## The index is built once per read
//!
//! [`ProjectIndex`] is the derived view over one snapshot. It is built once
//! ([`ProjectIndex::build`]) and every read — [`ProjectIndex::membership`],
//! [`ProjectIndex::resolve`], [`ProjectIndex::missing`] — reads that one value
//! rather than rebuilding. The contract's free operations each build exactly one
//! index per call, so a filter is a bucket lookup rather than a scan (NFR-001).
//!
//! ## Ordering is deterministic
//!
//! Members are ordered by issue number, projects by declaration order, and
//! missing references by `(issue number, project id)`, so repeated reads of the
//! same snapshot are identical (contract §6).

use std::collections::{HashMap, HashSet};
use std::fmt;

use indexmap::IndexMap;

use crate::config::{Config, ProjectConfiguration, ProjectId};
use crate::error::TixError;
use crate::planning::Progress;

/// The frontmatter key carrying an issue's project associations.
///
/// WP03's field is `projects` (data-model §6); named once here so a second
/// spelling has no home.
pub const PROJECTS_KEY: &str = "projects";

/// The lint diagnostic kind for an association that no longer resolves.
///
/// Distinct from [`ProjectDiagnosticKind::UnknownProject`]: the latter is a
/// *refusal* of a request naming a project, while this is a finding about a
/// stored reference (contract `cli-surface.md` §5).
pub const MISSING_REFERENCE_KIND: &str = "missing_project_reference";

/// The minimum an issue must expose for project derivation.
///
/// WP03 implements this for [`crate::model::Issue`]. Keeping it a trait is what
/// lets this module be written and tested without `src/model.rs`, which WP03
/// owns.
pub trait ProjectNode {
    /// The issue's number, which is its identity within one snapshot.
    fn number(&self) -> u32;
    /// The issue's title, used only for the derived display label.
    fn title(&self) -> &str;
    /// The issue's raw status.
    fn status(&self) -> &str;
    /// The stored project ids, in the order the file carries them.
    fn project_ids(&self) -> &[String];
}

// ---------------------------------------------------------------------------
// T006 — the Project view, resolution, and lifecycle
// ---------------------------------------------------------------------------

/// A project issue number, as the derived structures key it.
///
/// A newtype rather than a bare `u32` so a membership list cannot be confused
/// with any other number list, exactly as the contract spells it (`IssueKey`).
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct IssueKey(u32);

impl IssueKey {
    /// Wrap an issue number.
    #[must_use]
    pub fn new(number: u32) -> Self {
        Self(number)
    }

    /// The wrapped number.
    #[must_use]
    pub fn number(self) -> u32 {
        self.0
    }
}

impl fmt::Display for IssueKey {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "#{}", self.0)
    }
}

impl From<u32> for IssueKey {
    fn from(number: u32) -> Self {
        Self(number)
    }
}

impl From<IssueKey> for u32 {
    fn from(key: IssueKey) -> Self {
        key.0
    }
}

/// One member of a project, with its derived display label.
///
/// The label is computed on read and **never stored**: a stored title goes stale
/// the moment the issue is retitled (data-model §4).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct MemberRef {
    /// The member issue's number.
    pub issue: IssueKey,
    /// `#<number> <title>`, from the shared renderer in `hierarchy`.
    pub display: String,
}

/// The service-side view of a project (data-model §2).
///
/// Combines the registry record with the derived members. Registry-only
/// operations ([`create_project`], [`edit_project`]) return it with an **empty**
/// member list — there is no issue set to derive from — while index-backed
/// operations ([`resolve`], [`list_projects`]) fill it.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Project {
    /// The stable registry key; the identity that survives a rename (C-002).
    pub id: ProjectId,
    /// The mutable display label; never the identity.
    pub name: String,
    /// Optional long-form context.
    pub description: Option<String>,
    /// Optional project status (free-form; not a board column).
    pub status: Option<String>,
    /// Optional lead identity string.
    pub lead: Option<String>,
    /// Optional start date (`YYYY-MM-DD`).
    pub start_date: Option<String>,
    /// Optional due date (`YYYY-MM-DD`).
    pub due_date: Option<String>,
    /// Derived members, ordered by issue number. Never stored.
    pub members: Vec<MemberRef>,
    /// `members.len()`, carried because listings ask for it constantly.
    pub member_count: usize,
}

impl Project {
    /// Project a registry record into the service view.
    fn from_configuration(
        id: ProjectId,
        record: &ProjectConfiguration,
        members: Vec<MemberRef>,
    ) -> Self {
        Self {
            id,
            name: record.name.clone(),
            description: record.description.clone(),
            status: record.status.clone(),
            lead: record.lead.clone(),
            start_date: record.start_date.clone(),
            due_date: record.due_date.clone(),
            member_count: members.len(),
            members,
        }
    }
}

/// The shared display form for a project: `Platform hardening (p-3f9a2c)`.
///
/// One function, because the contract requires every listing to show the id
/// beside the name, and a second formatting site is how two surfaces end up
/// disagreeing about what a project is called.
#[must_use]
pub fn project_display(id: &ProjectId, name: &str) -> String {
    format!("{name} ({id})")
}

/// The clearly labelled bucket for an issue in **no** project.
pub const NO_PROJECT_BUCKET: &str = "(no project)";

/// The single bucket for an issue in **several** projects.
///
/// One bucket rather than a duplicate per project: an issue would otherwise become
/// several rows, and a listing's cursor, hit-testing and per-column counts are all
/// index-into-one-list arithmetic — a card that appeared twice would need a second
/// identity no surface has (`ProjectPartition` on the board records the same
/// decision).
pub const MULTIPLE_PROJECTS_BUCKET: &str = "(multiple projects)";

/// The group-section label for one issue's **resolved** project memberships.
///
/// The one home of the bucket rule, so the board partition, `tix list --group
/// project` and `tix status --group project` cannot label one bucket three ways:
/// none is the clearly labelled [`NO_PROJECT_BUCKET`], one is the project **id**
/// (the id is what selects a project, so a reader can act on the header), and
/// several collapse to [`MULTIPLE_PROJECTS_BUCKET`].
///
/// `projects` holds **resolved** ids in registry declaration order, as
/// [`ProjectIndex::resolved_memberships`] returns them; an association the registry
/// does not hold is not a project here either and is diagnosed by `tix lint`
/// instead.
#[must_use]
pub fn project_bucket_label(projects: &[String]) -> String {
    match projects {
        [] => NO_PROJECT_BUCKET.to_string(),
        [only] => only.clone(),
        _ => MULTIPLE_PROJECTS_BUCKET.to_string(),
    }
}

/// The derived members of a project (data-model §4).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ProjectMembership {
    /// The project the members belong to.
    pub project_id: ProjectId,
    /// Members ordered by issue number.
    pub members: Vec<MemberRef>,
    /// `members.len()`.
    pub member_count: usize,
}

/// A stored association whose project is not in the registry (data-model §3).
///
/// The reference is **reported, never dropped**: the issue keeps its id so the
/// reference can be repaired (C-005). Ordered deterministically by
/// `(issue number, project id)`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct MissingProjectReference {
    /// The issue holding the reference.
    pub issue: IssueKey,
    /// The issue's derived display label, so lint can name it without a lookup.
    pub issue_display: String,
    /// The id exactly as stored, retained for repair. May not even be a valid
    /// [`ProjectId`] shape, which is itself a reason it does not resolve.
    pub project_id: String,
    /// Human-readable text, produced by [`missing_reference_reason`].
    pub reason: String,
}

/// The diagnostic kinds `contracts/project-service.md` §1 names, spelled exactly.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ProjectDiagnosticKind {
    /// A project reference names neither a stored id nor a stored name.
    UnknownProject,
    /// An issue selector names no issue in the snapshot.
    UnknownIssue,
    /// The start/due dates are malformed or inverted.
    InvalidDates,
    /// The name is blank, padded, or already in use.
    DuplicateName,
}

impl ProjectDiagnosticKind {
    /// The canonical snake_case spelling a surface prints.
    #[must_use]
    pub fn as_str(self) -> &'static str {
        match self {
            ProjectDiagnosticKind::UnknownProject => "unknown_project",
            ProjectDiagnosticKind::UnknownIssue => "unknown_issue",
            ProjectDiagnosticKind::InvalidDates => "invalid_dates",
            ProjectDiagnosticKind::DuplicateName => "duplicate_name",
        }
    }
}

impl fmt::Display for ProjectDiagnosticKind {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(self.as_str())
    }
}

/// The single wording for an unresolvable project reference.
#[must_use]
pub fn unknown_project_reason(reference: &str) -> String {
    format!("no project matches `{reference}`; a project is selected by its stable id or by name")
}

/// The single wording for an issue selector that names no issue.
pub fn unknown_issue_reason(selector: impl fmt::Display) -> String {
    format!("issue `{selector}` is not in this store")
}

/// The single wording for a project date refusal.
///
/// Wraps the shared [`crate::model::validate_issue_dates`] message so the date
/// *rule* keeps its one owner and only the wording lives here.
#[must_use]
pub fn invalid_dates_reason(detail: &str) -> String {
    format!("project dates are invalid: {detail}")
}

/// The single wording for a project name refusal.
///
/// One helper for the [`ProjectDiagnosticKind::DuplicateName`] kind: a blank or
/// padded name is as unusable for selection as a duplicate, and both are the
/// same remedy — give the project a distinct, plainly written name.
#[must_use]
pub fn duplicate_name_reason(name: &str) -> String {
    if name.trim().is_empty() {
        "a project name must not be blank".to_string()
    } else if name.trim() != name {
        format!("project name `{name}` has leading or trailing whitespace")
    } else {
        format!("project name `{name}` is already in use; project names must be unique")
    }
}

/// The single wording for an association that no longer resolves.
#[must_use]
pub fn missing_reference_reason(issue: u32, project_id: &str) -> String {
    format!(
        "issue #{issue} references project `{project_id}`, which is not in the registry \
         (the reference is kept so it can be repaired)"
    )
}

/// The single wording for an association change's `## History` detail line.
///
/// One renderer, in the service, for every writer, so the CLI, the TUI and MCP
/// cannot word the same change differently.
#[must_use]
pub fn association_detail(project_id: &str, associated: bool) -> String {
    if associated {
        format!("project `{project_id}` associated")
    } else {
        format!("project `{project_id}` dissociated")
    }
}

/// Why a project operation was refused.
///
/// The variants map one-to-one onto [`ProjectDiagnosticKind`], so a surface can
/// print the named kind without a second classification step.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ProjectError {
    /// A project reference did not resolve.
    UnknownProject {
        /// The reference exactly as the caller wrote it.
        reference: String,
    },
    /// An issue selector named no issue in the snapshot.
    UnknownIssue {
        /// The selector exactly as the caller wrote it.
        selector: u32,
    },
    /// The start/due dates are malformed or inverted.
    InvalidDates {
        /// The shared date rule's message.
        detail: String,
    },
    /// The name is blank, padded, or already in use.
    DuplicateName {
        /// The name as supplied.
        name: String,
    },
}

impl ProjectError {
    /// The named diagnostic kind this refusal reports.
    #[must_use]
    pub fn kind(&self) -> ProjectDiagnosticKind {
        match self {
            ProjectError::UnknownProject { .. } => ProjectDiagnosticKind::UnknownProject,
            ProjectError::UnknownIssue { .. } => ProjectDiagnosticKind::UnknownIssue,
            ProjectError::InvalidDates { .. } => ProjectDiagnosticKind::InvalidDates,
            ProjectError::DuplicateName { .. } => ProjectDiagnosticKind::DuplicateName,
        }
    }

    /// The single wording for this refusal, via the kind's helper.
    #[must_use]
    pub fn message(&self) -> String {
        match self {
            ProjectError::UnknownProject { reference } => unknown_project_reason(reference),
            ProjectError::UnknownIssue { selector } => unknown_issue_reason(selector),
            ProjectError::InvalidDates { detail } => invalid_dates_reason(detail),
            ProjectError::DuplicateName { name } => duplicate_name_reason(name),
        }
    }
}

impl fmt::Display for ProjectError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}: {}", self.kind(), self.message())
    }
}

impl std::error::Error for ProjectError {}

/// A project refusal becomes user input error, so `?` works at the call site.
///
/// The payload is a single-line diagnostic (`<kind>: <message>`), so it takes the
/// crate's existing `invalid input:` prefix without doubling it — the same
/// boundary every other selector/validation refusal crosses (cli-surface §6).
impl From<ProjectError> for TixError {
    fn from(err: ProjectError) -> TixError {
        TixError::InvalidInput(err.to_string())
    }
}

/// The spec for a new project.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct NewProject {
    /// Required display label.
    pub name: String,
    /// Optional long-form context.
    pub description: Option<String>,
    /// Optional project status.
    pub status: Option<String>,
    /// Optional lead identity string.
    pub lead: Option<String>,
    /// Optional start date.
    pub start_date: Option<String>,
    /// Optional due date.
    pub due_date: Option<String>,
}

/// One field edit: leave it, clear it, or set it.
///
/// A three-state patch rather than `Option<Option<T>>` because "unchanged" and
/// "clear" must be distinguishable at the call site, and an `Option` nests into a
/// shape a reader has to count parentheses to understand.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub enum Patch<T> {
    /// Leave the field as it is.
    #[default]
    Unchanged,
    /// Remove the value.
    Clear,
    /// Replace the value.
    Set(T),
}

impl<T> Patch<T> {
    /// Whether this patch leaves the field alone.
    #[must_use]
    pub fn is_unchanged(&self) -> bool {
        matches!(self, Patch::Unchanged)
    }
}

/// The fields of a project edit.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct ProjectEdit {
    /// The display label. A rename is a label change only (C-002, SC-005).
    pub name: Patch<String>,
    /// Long-form context.
    pub description: Patch<String>,
    /// Project status.
    pub status: Patch<String>,
    /// Lead identity string.
    pub lead: Patch<String>,
    /// Start date.
    pub start_date: Patch<String>,
    /// Due date.
    pub due_date: Patch<String>,
}

/// The impact report of a project deletion (contract §1).
///
/// It **reports**; it does not delete. The affected issues keep their
/// associations, which then read as missing references (C-004, C-005), so this
/// type carries them for the caller's notice rather than a cascade.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ProjectDeletion {
    /// The id that was removed from the registry. Never handed out again.
    pub id: ProjectId,
    /// The name the record carried, for the notice.
    pub name: String,
    /// The issues that still reference the deleted project, by issue number.
    pub affected: Vec<MemberRef>,
}

/// Normalize an optional text field: a written-but-empty value is absent.
///
/// WP01 refuses a present-but-blank key, so collapsing it here is what keeps a
/// record this service writes loadable. Non-blank values are kept verbatim.
fn normalize_optional(value: Option<String>) -> Option<String> {
    value.filter(|v| !v.trim().is_empty())
}

/// Validate a requested display name against the registry.
///
/// Mirrors [`crate::config`]'s rule (`validate_projects`): non-blank, no padding,
/// and unique case-folded and trimmed, since a user does not tell `Platform` from
/// `platform`. WP01 owns the loader's copy; this is the write-path half, and the
/// two are pinned to the same rule by `create_project_refuses_a_duplicate_name`.
fn validate_name(
    config: &Config,
    name: &str,
    exclude: Option<&ProjectId>,
) -> Result<(), ProjectError> {
    if name.trim().is_empty() || name.trim() != name {
        return Err(ProjectError::DuplicateName {
            name: name.to_string(),
        });
    }
    let normalized = name.to_lowercase();
    let clash = config.projects.iter().any(|(raw, record)| {
        let is_self = exclude.is_some_and(|id| raw.as_str() == id.as_str());
        !is_self && record.name.to_lowercase() == normalized
    });
    if clash {
        return Err(ProjectError::DuplicateName {
            name: name.to_string(),
        });
    }
    Ok(())
}

/// Validate the pair through the shared date rule (WP01 uses the same helper).
fn validate_dates(start: Option<&str>, due: Option<&str>) -> Result<(), ProjectError> {
    crate::model::validate_issue_dates(start, due).map_err(|err| ProjectError::InvalidDates {
        detail: err.to_string(),
    })
}

/// Resolve a project id from a reference: **id first**, then a name convenience.
///
/// Resolution is by the stable id (C-002). A name is accepted because a human
/// selects projects by name; it resolves to the same project, and WP01's
/// uniqueness rule guarantees it is unambiguous. An id that also happens to look
/// like another project's name wins, which is what "id first" means.
pub fn resolve_project_id(config: &Config, reference: &str) -> Result<ProjectId, ProjectError> {
    if let Ok(id) = ProjectId::new(reference) {
        if config.projects.contains_key(id.as_str()) {
            return Ok(id);
        }
    }
    let normalized = reference.trim().to_lowercase();
    if let Some((raw, _)) = config
        .projects
        .iter()
        .find(|(_, record)| record.name.to_lowercase() == normalized)
    {
        return ProjectId::new(raw).map_err(|_| ProjectError::UnknownProject {
            reference: reference.to_string(),
        });
    }
    Err(ProjectError::UnknownProject {
        reference: reference.to_string(),
    })
}

/// Create a project, allocating a fresh stable id (FR-001).
///
/// Validates the name and dates first, so a refusal yields no registry change.
/// The record is inserted into the in-memory [`Config`]; the caller persists it
/// with `Config::save`, so the atomic write path has exactly one owner.
pub fn create_project(config: &mut Config, new: &NewProject) -> Result<Project, ProjectError> {
    validate_name(config, &new.name, None)?;
    validate_dates(new.start_date.as_deref(), new.due_date.as_deref())?;
    let id = config.allocate_project_id();
    let record = ProjectConfiguration {
        name: new.name.clone(),
        description: normalize_optional(new.description.clone()),
        status: normalize_optional(new.status.clone()),
        lead: normalize_optional(new.lead.clone()),
        start_date: new.start_date.clone(),
        due_date: new.due_date.clone(),
    };
    config.projects.insert(id.to_string(), record.clone());
    Ok(Project::from_configuration(id, &record, Vec::new()))
}

/// Edit a project's fields by reference.
///
/// A name change is a **label change only**: the registry key is untouched, so
/// every association and derived figure stays intact (C-002, SC-005). The
/// returned view carries no members — an edit has no issue set to derive from.
pub fn edit_project(
    config: &mut Config,
    reference: &str,
    edit: &ProjectEdit,
) -> Result<Project, ProjectError> {
    let id = resolve_project_id(config, reference)?;
    let mut updated =
        config
            .projects
            .get(id.as_str())
            .cloned()
            .ok_or_else(|| ProjectError::UnknownProject {
                reference: reference.to_string(),
            })?;

    match &edit.name {
        Patch::Unchanged => {}
        Patch::Clear => {
            return Err(ProjectError::DuplicateName {
                name: String::new(),
            });
        }
        Patch::Set(name) => {
            validate_name(config, name, Some(&id))?;
            updated.name.clone_from(name);
        }
    }
    apply_optional(&edit.description, &mut updated.description);
    apply_optional(&edit.status, &mut updated.status);
    apply_optional(&edit.lead, &mut updated.lead);
    apply_date(&edit.start_date, &mut updated.start_date);
    apply_date(&edit.due_date, &mut updated.due_date);

    validate_dates(updated.start_date.as_deref(), updated.due_date.as_deref())?;

    if let Some(record) = config.projects.get_mut(id.as_str()) {
        *record = updated.clone();
    }
    Ok(Project::from_configuration(id, &updated, Vec::new()))
}

/// Apply an optional-text patch.
fn apply_optional(patch: &Patch<String>, slot: &mut Option<String>) {
    match patch {
        Patch::Unchanged => {}
        Patch::Clear => *slot = None,
        Patch::Set(value) => *slot = normalize_optional(Some(value.clone())),
    }
}

/// Apply a date patch.
fn apply_date(patch: &Patch<String>, slot: &mut Option<String>) {
    match patch {
        Patch::Unchanged => {}
        Patch::Clear => *slot = None,
        Patch::Set(value) => *slot = Some(value.clone()),
    }
}

/// Remove a project from the registry, reporting the issues that reference it.
///
/// Removes the registry entry **only**. Every issue keeps its association, which
/// then reads as a missing reference so the user can repair it (C-004, C-005).
/// The id is never reused (WP01's allocation carries that guarantee).
pub fn delete_project<N: ProjectNode>(
    config: &mut Config,
    reference: &str,
    issues: &[N],
) -> Result<ProjectDeletion, ProjectError> {
    let id = resolve_project_id(config, reference)?;
    let record =
        config
            .projects
            .get(id.as_str())
            .cloned()
            .ok_or_else(|| ProjectError::UnknownProject {
                reference: reference.to_string(),
            })?;
    let affected = ProjectIndex::build(config, issues)
        .project(&id)
        .map(|project| project.members.clone())
        .unwrap_or_default();
    config.projects.shift_remove(id.as_str());
    Ok(ProjectDeletion {
        id,
        name: record.name,
        affected,
    })
}

// ---------------------------------------------------------------------------
// T007 — the derived index and membership
// ---------------------------------------------------------------------------

/// The derived project view over one snapshot of issues and the registry.
///
/// Built once and read many times. The bucket map is the NFR-001 index; the
/// project map is `IndexMap` so declaration order is the display order; the
/// label/status maps carry what a member listing needs. Nothing here is stored.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ProjectIndex {
    /// Projects in declaration order, each carrying its derived members.
    projects: IndexMap<ProjectId, Project>,
    /// The reverse index: project -> member issue keys, ascending.
    buckets: HashMap<ProjectId, Vec<IssueKey>>,
    /// Associations whose project does not resolve, deterministically ordered.
    missing: Vec<MissingProjectReference>,
    /// Issue number -> display label, for member listings.
    labels: HashMap<IssueKey, String>,
    /// Issue number -> status, for the deriving surfaces.
    statuses: HashMap<IssueKey, String>,
}

impl ProjectIndex {
    /// Build the index in **one pass** over the issue set.
    ///
    /// An association whose project does not resolve is kept in [`Self::missing`]
    /// rather than dropped: a silently absent reference is the failure C-005
    /// forbids, and [`validate_references`] reports exactly this set.
    pub fn build<N: ProjectNode>(config: &Config, issues: &[N]) -> Self {
        // Ids the registry actually holds. A key that is not a valid ProjectId
        // shape cannot be referenced, so it is skipped rather than panicking.
        let known: HashMap<String, ProjectId> = config
            .projects
            .keys()
            .filter_map(|raw| ProjectId::new(raw).ok().map(|id| (raw.clone(), id)))
            .collect();

        let mut labels: HashMap<IssueKey, String> = HashMap::new();
        let mut statuses: HashMap<IssueKey, String> = HashMap::new();
        let mut buckets: HashMap<ProjectId, Vec<IssueKey>> = HashMap::new();
        let mut missing: Vec<MissingProjectReference> = Vec::new();

        for issue in issues {
            let key = IssueKey::new(issue.number());
            let display = crate::hierarchy::display_label(issue.number(), issue.title());
            labels.insert(key, display.clone());
            statuses.insert(key, issue.status().to_string());

            // A duplicated id on one issue is one association, so it is reported
            // once and bucketed once (T009 step 5).
            let mut seen: HashSet<&str> = HashSet::new();
            for raw in issue.project_ids() {
                if !seen.insert(raw.as_str()) {
                    continue;
                }
                match known.get(raw.as_str()) {
                    Some(id) => buckets.entry(id.clone()).or_default().push(key),
                    None => missing.push(MissingProjectReference {
                        issue: key,
                        issue_display: display.clone(),
                        project_id: raw.clone(),
                        reason: missing_reference_reason(issue.number(), raw),
                    }),
                }
            }
        }

        for members in buckets.values_mut() {
            members.sort_unstable();
        }
        // (issue number, id): the ordering the contract pins for lint stability.
        missing.sort_by(|a, b| {
            a.issue
                .cmp(&b.issue)
                .then_with(|| a.project_id.cmp(&b.project_id))
        });

        let mut projects: IndexMap<ProjectId, Project> = IndexMap::new();
        for (raw, record) in &config.projects {
            let Ok(id) = ProjectId::new(raw) else {
                continue;
            };
            let members: Vec<MemberRef> = buckets
                .get(&id)
                .map(|keys| {
                    keys.iter()
                        .map(|key| MemberRef {
                            issue: *key,
                            display: labels.get(key).cloned().unwrap_or_else(|| key.to_string()),
                        })
                        .collect()
                })
                .unwrap_or_default();
            projects.insert(id.clone(), Project::from_configuration(id, record, members));
        }

        Self {
            projects,
            buckets,
            missing,
            labels,
            statuses,
        }
    }

    /// The reverse index, as the contract spells it.
    #[must_use]
    pub fn buckets(&self) -> &HashMap<ProjectId, Vec<IssueKey>> {
        &self.buckets
    }

    /// The member keys of one project.
    ///
    /// `None` **only** for a project the registry does not hold. A known project
    /// with no members returns an empty slice, so "not a project" and "a project
    /// with no members yet" stay distinguishable to a caller.
    #[must_use]
    pub fn bucket(&self, id: &ProjectId) -> Option<&[IssueKey]> {
        if !self.projects.contains_key(id) {
            return None;
        }
        Some(self.buckets.get(id).map_or(&[][..], Vec::as_slice))
    }

    /// Projects in declaration order.
    #[must_use]
    pub fn projects(&self) -> Vec<&Project> {
        self.projects.values().collect()
    }

    /// One project by id.
    #[must_use]
    pub fn project(&self, id: &ProjectId) -> Option<&Project> {
        self.projects.get(id)
    }

    /// The issue display label the index recorded.
    #[must_use]
    pub fn label(&self, key: IssueKey) -> Option<&str> {
        self.labels.get(&key).map(String::as_str)
    }

    /// An issue's status, as the index recorded it.
    #[must_use]
    pub fn status_of(&self, key: IssueKey) -> Option<&str> {
        self.statuses.get(&key).map(String::as_str)
    }

    /// The diagnosed associations of this snapshot.
    #[must_use]
    pub fn missing(&self) -> &[MissingProjectReference] {
        &self.missing
    }

    /// Resolve a project by id (first) or by name.
    pub fn resolve(&self, reference: &str) -> Result<&Project, ProjectError> {
        if let Ok(id) = ProjectId::new(reference) {
            if let Some(project) = self.projects.get(&id) {
                return Ok(project);
            }
        }
        let normalized = reference.trim().to_lowercase();
        self.projects
            .values()
            .find(|project| project.name.to_lowercase() == normalized)
            .ok_or_else(|| ProjectError::UnknownProject {
                reference: reference.to_string(),
            })
    }

    /// The ordered membership of a project.
    pub fn membership(&self, reference: &str) -> Result<ProjectMembership, ProjectError> {
        let project = self.resolve(reference)?;
        Ok(ProjectMembership {
            project_id: project.id.clone(),
            members: project.members.clone(),
            member_count: project.member_count,
        })
    }

    /// Every issue's **resolved** project ids, in registry declaration order.
    ///
    /// The reverse of [`Self::buckets`]: issue number -> the ids of the projects
    /// that hold it. Derived from the same buckets, so a grouping surface cannot
    /// disagree with [`Self::membership`] about who is a member; an association the
    /// registry does not hold appears in no bucket and therefore in no entry here
    /// (it is diagnosed by [`validate_references`] instead — the chosen asymmetry
    /// `tix search`'s `project_matches` documents).
    ///
    /// Declaration order is the display order, so [`project_bucket_label`] over an
    /// entry is the same label the board's `ProjectPartition` produces.
    #[must_use]
    pub fn resolved_memberships(&self) -> HashMap<u32, Vec<String>> {
        let mut out: HashMap<u32, Vec<String>> = HashMap::new();
        for project in self.projects.values() {
            if let Some(members) = self.buckets.get(&project.id) {
                for member in members {
                    out.entry(member.number())
                        .or_default()
                        .push(project.id.to_string());
                }
            }
        }
        out
    }

    /// Consume the index into its reverse map (the contract's return shape).
    #[must_use]
    pub fn into_buckets(self) -> HashMap<ProjectId, Vec<IssueKey>> {
        self.buckets
    }

    /// Consume the index into its missing-reference list.
    #[must_use]
    pub fn into_missing(self) -> Vec<MissingProjectReference> {
        self.missing
    }

    /// Consume the index into its declaration-ordered project list.
    #[must_use]
    pub fn into_projects(self) -> Vec<Project> {
        self.projects.into_values().collect()
    }
}

/// Build the reverse index once for one read (`HashMap<ProjectId, Vec<IssueKey>>`).
///
/// A project filter is then a bucket lookup rather than a scan (NFR-001).
#[must_use]
pub fn membership_index<N: ProjectNode>(
    config: &Config,
    issues: &[N],
) -> HashMap<ProjectId, Vec<IssueKey>> {
    ProjectIndex::build(config, issues).into_buckets()
}

/// The ordered membership of a project, by id or name.
pub fn membership<N: ProjectNode>(
    config: &Config,
    issues: &[N],
    reference: &str,
) -> Result<ProjectMembership, ProjectError> {
    ProjectIndex::build(config, issues).membership(reference)
}

/// The projects in declaration order, with derived member counts.
///
/// Never errors: an empty registry is an empty list, and a registry with no
/// issues is a list with zero members.
#[must_use]
pub fn list_projects<N: ProjectNode>(config: &Config, issues: &[N]) -> Vec<Project> {
    ProjectIndex::build(config, issues).into_projects()
}

/// Resolve a project by id (first) or by name.
pub fn resolve<N: ProjectNode>(
    config: &Config,
    issues: &[N],
    reference: &str,
) -> Result<Project, ProjectError> {
    ProjectIndex::build(config, issues)
        .resolve(reference)
        .cloned()
}

// ---------------------------------------------------------------------------
// T008 — association mutations, with History events
// ---------------------------------------------------------------------------

/// The two association mutations, as the `## History` section records them.
///
/// Declared here rather than in `model::HistoryEventKind` because WP02 may not
/// edit `src/model.rs`; WP03 maps these onto that enum, exactly as the hierarchy
/// mission's `ParentEventKind` is mapped.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ProjectEventKind {
    /// An issue gained an association.
    ProjectAssociated,
    /// An issue lost an association.
    ProjectDissociated,
}

impl ProjectEventKind {
    /// The canonical snake_case spelling the History section will carry.
    #[must_use]
    pub fn as_str(self) -> &'static str {
        match self {
            ProjectEventKind::ProjectAssociated => "project_associated",
            ProjectEventKind::ProjectDissociated => "project_dissociated",
        }
    }
}

/// One association mutation, ready for storage to append to `## History`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ProjectEvent {
    /// Which of the two mutations this is.
    pub kind: ProjectEventKind,
    /// The project id exactly as recorded. A `String`, not a [`ProjectId`],
    /// because a dissociate may remove a stored id that is not a valid shape.
    pub project_id: String,
    /// The rendered detail line, from [`association_detail`].
    pub detail: String,
}

/// The outcome of an association mutation: the resulting list plus the event.
///
/// The service produces the event and **does not write**; storage applies the
/// list and appends the event, so the atomicity rule lives in one place. It never
/// returns a whole `Issue`, which is what keeps this module model-free.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ProjectChange {
    /// The issue whose associations changed.
    pub issue: IssueKey,
    /// The association list after the change, first-seen order preserved.
    pub project_ids: Vec<String>,
    /// The event to append, or `None` when the mutation was a no-op.
    ///
    /// `None` for associating an already-present project or dissociating an
    /// absent one: neither is a change, and recording one would put an entry in
    /// the audit trail for nothing.
    pub event: Option<ProjectEvent>,
}

/// The per-issue outcome of a bulk association (contract §1).
///
/// One entry per selector, each carrying its own success or refusal, so one
/// rejection is observable beside the rest rather than aborting them (FR-002).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct BulkProjectOutcome {
    /// The selector this entry answers.
    pub selector: u32,
    /// The change or the refusal for that selector.
    pub outcome: Result<ProjectChange, ProjectError>,
}

/// Find an issue in the snapshot by its number.
fn find_issue<N: ProjectNode>(issues: &[N], selector: u32) -> Result<&N, ProjectError> {
    issues
        .iter()
        .find(|issue| issue.number() == selector)
        .ok_or(ProjectError::UnknownIssue { selector })
}

/// Produce the association change for a **resolved** project id.
fn associate_resolved<N: ProjectNode>(
    issues: &[N],
    selector: u32,
    id: &ProjectId,
) -> Result<ProjectChange, ProjectError> {
    let issue = find_issue(issues, selector)?;
    let current = issue.project_ids();
    let key = IssueKey::new(selector);
    if current.iter().any(|stored| stored == id.as_str()) {
        return Ok(ProjectChange {
            issue: key,
            project_ids: current.to_vec(),
            event: None,
        });
    }
    let mut next = current.to_vec();
    next.push(id.to_string());
    Ok(ProjectChange {
        issue: key,
        project_ids: next,
        event: Some(ProjectEvent {
            kind: ProjectEventKind::ProjectAssociated,
            project_id: id.to_string(),
            detail: association_detail(id.as_str(), true),
        }),
    })
}

/// Associate an issue with a project, producing the change and its History event.
///
/// Idempotent: an already-present association changes nothing and yields **no**
/// event (contract §3). Refuses an unknown project or an unknown issue; a refusal
/// produces no change and no event.
pub fn associate<N: ProjectNode>(
    config: &Config,
    issues: &[N],
    issue_selector: u32,
    project_reference: &str,
) -> Result<ProjectChange, ProjectError> {
    let id = resolve_project_id(config, project_reference)?;
    associate_resolved(issues, issue_selector, &id)
}

/// Remove an issue's association with a project.
///
/// Drops only the association: it never deletes or modifies the issue (C-004).
/// Dissociating an absent association is an idempotent no-op with no event. The
/// project is **not** required to exist — removing a stale reference is the
/// repair path C-005 promises — so the only refusal is an unknown issue.
///
/// `project_id` is compared against the stored list **verbatim**: unlike
/// [`associate`], a project *name* is not resolved here. That is deliberate, not
/// an oversight — the stored entries are ids, and a caller must resolve a name to
/// an id first (via [`resolve_project_id`]). A name therefore matches nothing and
/// is an inert no-op, which is what keeps the repair path working for an id that
/// is no longer a valid [`ProjectId`] shape or no longer in the registry.
pub fn dissociate<N: ProjectNode>(
    issues: &[N],
    issue_selector: u32,
    project_id: &str,
) -> Result<ProjectChange, ProjectError> {
    let issue = find_issue(issues, issue_selector)?;
    let current = issue.project_ids();
    let key = IssueKey::new(issue_selector);
    if !current.iter().any(|stored| stored == project_id) {
        return Ok(ProjectChange {
            issue: key,
            project_ids: current.to_vec(),
            event: None,
        });
    }
    let next: Vec<String> = current
        .iter()
        .filter(|stored| stored.as_str() != project_id)
        .cloned()
        .collect();
    Ok(ProjectChange {
        issue: key,
        project_ids: next,
        event: Some(ProjectEvent {
            kind: ProjectEventKind::ProjectDissociated,
            project_id: project_id.to_string(),
            detail: association_detail(project_id, false),
        }),
    })
}

/// Associate each selector independently, reporting every outcome.
///
/// One rejection must not abort the rest (contract §3): the returned vector has
/// one entry per selector, in selector order, and an unknown project refuses each
/// entry rather than the whole call.
#[must_use]
pub fn bulk_associate<N: ProjectNode>(
    config: &Config,
    issues: &[N],
    project_reference: &str,
    issue_selectors: &[u32],
) -> Vec<BulkProjectOutcome> {
    let resolved = resolve_project_id(config, project_reference);
    issue_selectors
        .iter()
        .map(|&selector| {
            let outcome = match &resolved {
                Ok(id) => associate_resolved(issues, selector, id),
                Err(err) => Err(err.clone()),
            };
            BulkProjectOutcome { selector, outcome }
        })
        .collect()
}

// ---------------------------------------------------------------------------
// T009 — missing-reference diagnosis
// ---------------------------------------------------------------------------

/// Every association in the snapshot whose project is not in the registry.
///
/// **Never errors** — lint consumes the list directly — and performs one pass
/// over the issue set rather than one lookup per project. Each missing
/// association is reported once, ordered by `(issue number, project id)` so lint
/// output is stable (C-005, contract §4).
#[must_use]
pub fn validate_references<N: ProjectNode>(
    config: &Config,
    issues: &[N],
) -> Vec<MissingProjectReference> {
    ProjectIndex::build(config, issues).into_missing()
}

// ---------------------------------------------------------------------------
// T015/T016 — project progress and health: the one computation (FR-003, C-006)
// ---------------------------------------------------------------------------
//
// Out-of-map rationale (WP04): `src/projects.rs` is the single owner of project
// computation, so project progress and health belong here. Putting the figures in
// a surface would create the second implementation C-006 prohibits — this module
// is where the one implementation must live, and the addition below is additive:
// it introduces new items and a second `impl ProjectIndex` block, and edits none
// of WP02's existing code.

/// The one per-issue fact project health reads beyond [`ProjectNode`].
///
/// `ProjectNode` is WP02's minimal shape and deliberately does not grow a member
/// for a later work package: WP03 implements it for [`crate::model::Issue`] in
/// `src/model.rs`, which WP04 may not edit, so a required method added there would
/// not compile. This trait is the adapter instead — implemented for
/// [`crate::model::Issue`] in the WP04 surface (`src/commands/view.rs`) — which
/// keeps this module free of the issue model, exactly as its module contract
/// promises.
pub trait HealthNode: ProjectNode {
    /// The issue's assignee, `None` when unset. A blank value counts as unset;
    /// [`assigned_keys`] is where that rule lives.
    fn assignee(&self) -> Option<&str>;
}

/// The members of a snapshot that carry an assignee.
///
/// The single home of the "unassigned" rule (data-model §5): an **absent** assignee
/// or one that is **blank after trimming** counts as unassigned. Returned as a set
/// of issue numbers and consumed by [`ProjectIndex::health`], the same shape as the
/// consumed overdue and blocked reads, so the *count* is computed in exactly one
/// place (C-006) while the rule itself also has exactly one home.
#[must_use]
pub fn assigned_keys<N: HealthNode>(issues: &[N]) -> HashSet<u32> {
    issues
        .iter()
        .filter(|issue| {
            issue
                .assignee()
                .is_some_and(|assignee| !assignee.trim().is_empty())
        })
        .map(ProjectNode::number)
        .collect()
}

/// A project's completion progress (data-model §5, FR-003).
///
/// Mirrors the hierarchy rollup ([`crate::hierarchy::ParentRollup`]): the counts
/// spelled out for a listing, plus the typed [`Progress`] value so CLI, TUI and MCP
/// results can be compared **by value** (NFR-003). [`Progress`] is the planner's,
/// reused rather than reinvented (research R3).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ProjectProgress {
    /// Members in the board's **configured** completion column.
    pub done: usize,
    /// Members.
    pub total: usize,
    /// The typed completion value, reused from the planner.
    pub progress: Progress,
}

/// A project's health counters (data-model §5, FR-003).
///
/// Every figure is **consumed** from an existing derived read, never recomputed
/// here: `overdue` from the planning overdue read and `blocked` from the
/// relationship graph's `blocked_state` (research R4).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ProjectHealth {
    /// Members past their due date and not done.
    pub overdue: usize,
    /// Members with an open blocker.
    pub blocked: usize,
    /// Members with no assignee (absent or blank after trimming).
    pub unassigned: usize,
    /// The project's members' associations that no longer resolve (C-005).
    pub missing_references: Vec<MissingProjectReference>,
}

/// The typed value the `health` operation returns (contract §1).
///
/// One value, carrying the project's identity, its progress, and its health, so a
/// CLI, TUI or MCP surface renders it rather than re-deriving any figure (C-006).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ProjectHealthReport {
    /// The project the figures describe.
    pub project_id: ProjectId,
    /// The project's display label, so a surface needs no second lookup.
    pub name: String,
    /// Completion figures.
    pub progress: ProjectProgress,
    /// The health counters.
    pub health: ProjectHealth,
}

impl ProjectIndex {
    /// Progress and health for one project (contract §1, FR-003).
    ///
    /// Reads the members from the index's bucket, so a project's figures are a
    /// bucket lookup rather than a scan of the issue set (contract §4).
    ///
    /// `assigned`, `overdue`, and `blocked` are the **consumed** derived facts,
    /// keyed by issue number and each produced by its owner: [`assigned_keys`], the
    /// planning overdue read, and the relationship graph's `blocked_state`. Project
    /// health counts them and never recomputes them. Completion resolves through the
    /// board's configured completion column via the service resolution, never a
    /// literal `"done"`.
    ///
    /// A **done** issue is never counted as overdue, matching the planner's own
    /// overdue rule: the passed set is normally already filtered, and the guard keeps
    /// the invariant true for any caller that passes a raw set.
    pub fn health<S: std::hash::BuildHasher>(
        &self,
        config: &Config,
        reference: &str,
        assigned: &HashSet<u32, S>,
        overdue: &HashSet<u32, S>,
        blocked: &HashSet<u32, S>,
    ) -> Result<ProjectHealthReport, ProjectError> {
        let project = self.resolve(reference)?;
        let (_, resolution) = crate::workflow::active_resolution(config);
        let members = self.bucket(&project.id).unwrap_or(&[]);
        let mut done = 0usize;
        let mut overdue_count = 0usize;
        let mut blocked_count = 0usize;
        let mut unassigned = 0usize;
        for key in members {
            let number = key.number();
            let complete = self
                .status_of(*key)
                .and_then(|status| resolution.resolve(status))
                .is_some_and(crate::workflow::WorkflowCategory::is_complete);
            if complete {
                done += 1;
            }
            if !complete && overdue.contains(&number) {
                overdue_count += 1;
            }
            if blocked.contains(&number) {
                blocked_count += 1;
            }
            if !assigned.contains(&number) {
                unassigned += 1;
            }
        }
        let total = members.len();
        // The project's members' dangling associations, in the index's deterministic
        // order (`missing` is sorted by `(issue number, project id)`). An association
        // whose project does not resolve cannot belong to any bucket, so the
        // references reported here are the members' *other* broken references —
        // surfaced wherever health is shown (C-005).
        let member_keys: HashSet<IssueKey> = members.iter().copied().collect();
        let missing_references: Vec<MissingProjectReference> = self
            .missing
            .iter()
            .filter(|missing| member_keys.contains(&missing.issue))
            .cloned()
            .collect();
        Ok(ProjectHealthReport {
            project_id: project.id.clone(),
            name: project.name.clone(),
            progress: ProjectProgress {
                done,
                total,
                progress: Progress { done, total },
            },
            health: ProjectHealth {
                overdue: overdue_count,
                blocked: blocked_count,
                unassigned,
                missing_references,
            },
        })
    }
}

/// Progress and health for a project, in one index build (contract §1).
///
/// The free form of [`ProjectIndex::health`], for a caller that needs exactly one
/// project. A caller that needs several builds one [`ProjectIndex`] and calls
/// [`ProjectIndex::health`] on it, so the snapshot is indexed once (contract §4).
pub fn health<N: HealthNode, S: std::hash::BuildHasher>(
    config: &Config,
    issues: &[N],
    reference: &str,
    assigned: &HashSet<u32, S>,
    overdue: &HashSet<u32, S>,
    blocked: &HashSet<u32, S>,
) -> Result<ProjectHealthReport, ProjectError> {
    ProjectIndex::build(config, issues).health(config, reference, assigned, overdue, blocked)
}

#[cfg(test)]
mod tests {
    #[allow(clippy::wildcard_imports)]
    use super::*;

    /// An in-memory stand-in for the shape WP03 will expose on `Issue`.
    ///
    /// The inline suite is deliberately filesystem-free (T010 step 4): every
    /// test below builds a [`Config`] and a `Vec<Node>` by hand, with no `Store`
    /// and no `tempdir`.
    #[derive(Debug, Clone, PartialEq, Eq)]
    struct Node {
        number: u32,
        title: String,
        status: String,
        projects: Vec<String>,
        assignee: Option<String>,
    }

    impl Node {
        fn new(number: u32, title: &str) -> Self {
            Self {
                number,
                title: title.to_string(),
                status: "todo".to_string(),
                projects: Vec::new(),
                assignee: None,
            }
        }

        fn with(mut self, ids: &[&str]) -> Self {
            self.projects = ids.iter().map(|id| (*id).to_string()).collect();
            self
        }

        fn in_column(mut self, status: &str) -> Self {
            self.status = status.to_string();
            self
        }

        fn assigned_to(mut self, assignee: &str) -> Self {
            self.assignee = Some(assignee.to_string());
            self
        }
    }

    impl ProjectNode for Node {
        fn number(&self) -> u32 {
            self.number
        }
        fn title(&self) -> &str {
            &self.title
        }
        fn status(&self) -> &str {
            &self.status
        }
        fn project_ids(&self) -> &[String] {
            &self.projects
        }
    }

    impl HealthNode for Node {
        fn assignee(&self) -> Option<&str> {
            self.assignee.as_deref()
        }
    }

    /// A registry holding `(id, name)` pairs in declaration order.
    fn registry(entries: &[(&str, &str)]) -> Config {
        let mut config = Config::default();
        for (id, name) in entries {
            config.projects.insert(
                (*id).to_string(),
                ProjectConfiguration {
                    name: (*name).to_string(),
                    ..ProjectConfiguration::default()
                },
            );
        }
        config
    }

    fn ids(change: &ProjectChange) -> Vec<&str> {
        change.project_ids.iter().map(String::as_str).collect()
    }

    /// A set of issue numbers, as the consumed health inputs are keyed.
    fn set(numbers: &[u32]) -> HashSet<u32> {
        numbers.iter().copied().collect()
    }

    /// A config whose default board completes on a **custom** column, so a literal
    /// `"done"` comparison cannot pass the tests that use it.
    fn custom_completion(columns: &[&str], done_column: &str, map: &[(&str, &str)]) -> Config {
        let mut config = Config::default();
        config.kanban.configurations.insert(
            "default".to_string(),
            crate::config::BoardConfiguration {
                columns: columns.iter().map(|c| (*c).to_string()).collect(),
                done_column: Some(done_column.to_string()),
                category_map: map
                    .iter()
                    .map(|(column, key)| ((*column).to_string(), (*key).to_string()))
                    .collect(),
                ..Default::default()
            },
        );
        config
    }

    // --- T006: create / edit / delete / list / resolve -----------------------

    #[test]
    fn create_project_allocates_a_stable_id() {
        let mut config = Config::default();
        let project = create_project(
            &mut config,
            &NewProject {
                name: "Platform hardening".into(),
                description: Some("reduce risk".into()),
                ..NewProject::default()
            },
        )
        .unwrap();

        assert!(project.id.as_str().starts_with("p-"));
        assert_eq!(project.name, "Platform hardening");
        assert_eq!(project.member_count, 0);
        assert!(config.projects.contains_key(project.id.as_str()));
        // The id is the key, the name is stored inside the record.
        assert_eq!(
            config.projects[project.id.as_str()].name,
            "Platform hardening"
        );
    }

    #[test]
    fn create_project_refuses_a_duplicate_name_case_folded() {
        let mut config = registry(&[("p-aaaa", "Platform")]);
        let err = create_project(
            &mut config,
            &NewProject {
                name: "platform".into(),
                ..NewProject::default()
            },
        )
        .unwrap_err();
        assert_eq!(err.kind(), ProjectDiagnosticKind::DuplicateName);
        assert_eq!(config.projects.len(), 1, "a refusal writes nothing");
    }

    #[test]
    fn create_project_refuses_inverted_dates() {
        let mut config = Config::default();
        let err = create_project(
            &mut config,
            &NewProject {
                name: "Bad dates".into(),
                start_date: Some("2026-12-01".into()),
                due_date: Some("2026-01-01".into()),
                ..NewProject::default()
            },
        )
        .unwrap_err();
        assert_eq!(err.kind(), ProjectDiagnosticKind::InvalidDates);
        assert!(config.projects.is_empty());
    }

    #[test]
    fn rename_changes_the_label_only() {
        let mut config = registry(&[("p-3f9a2c", "Platform hardening")]);
        let issues = vec![Node::new(1, "One").with(&["p-3f9a2c"])];

        let edited = edit_project(
            &mut config,
            "p-3f9a2c",
            &ProjectEdit {
                name: Patch::Set("Platform".into()),
                ..ProjectEdit::default()
            },
        )
        .unwrap();

        // The key is untouched, so the association resolves exactly as before.
        assert!(config.projects.contains_key("p-3f9a2c"));
        assert_eq!(edited.id.as_str(), "p-3f9a2c");
        assert_eq!(edited.name, "Platform");
        let membership = membership(&config, &issues, "p-3f9a2c").unwrap();
        assert_eq!(membership.member_count, 1);
    }

    #[test]
    fn edit_project_clears_an_optional_field() {
        let mut config = registry(&[("p-aaaa", "One")]);
        config.projects["p-aaaa"].lead = Some("Alice".into());
        let edited = edit_project(
            &mut config,
            "p-aaaa",
            &ProjectEdit {
                lead: Patch::Clear,
                ..ProjectEdit::default()
            },
        )
        .unwrap();
        assert_eq!(edited.lead, None);
        assert_eq!(config.projects["p-aaaa"].lead, None);
    }

    #[test]
    fn edit_project_refuses_an_unknown_reference() {
        let mut config = registry(&[("p-aaaa", "One")]);
        let err = edit_project(
            &mut config,
            "does-not-exist",
            &ProjectEdit {
                name: Patch::Set("X".into()),
                ..ProjectEdit::default()
            },
        )
        .unwrap_err();
        assert_eq!(err.kind(), ProjectDiagnosticKind::UnknownProject);
    }

    #[test]
    fn delete_reports_affected_issues_and_keeps_them() {
        let mut config = registry(&[("p-aaaa", "One")]);
        let issues = vec![
            Node::new(2, "Two").with(&["p-aaaa"]),
            Node::new(7, "Seven").with(&["p-aaaa"]),
        ];

        let impact = delete_project(&mut config, "One", &issues).unwrap();

        assert_eq!(impact.id.as_str(), "p-aaaa");
        assert_eq!(impact.name, "One");
        assert_eq!(
            impact
                .affected
                .iter()
                .map(|m| m.issue.number())
                .collect::<Vec<_>>(),
            vec![2, 7],
            "affected issues are ordered by issue number"
        );
        // The registry entry is gone; the issues keep their references.
        assert!(config.projects.is_empty());
        assert_eq!(issues[0].projects, vec!["p-aaaa".to_string()]);
        // And the retained references are now diagnosable.
        assert_eq!(validate_references(&config, &issues).len(), 2);
    }

    #[test]
    fn successive_create_draws_after_a_delete_are_distinct() {
        // Honest scope: this pins only that two successive `ProjectId::generate`
        // draws differ. It cannot observe *non-reuse of the deleted id* — a
        // fresh 2^64-space draw repeating one would fail here with probability
        // ~2^-64, and would fail anyway. Deleted-id non-reuse is WP01's
        // guarantee, carried by the id shape plus the stored-id redraw; the
        // rationale is recorded on `ProjectId::generate` and `allocate_project_id`.
        let mut config = Config::default();
        let first = create_project(
            &mut config,
            &NewProject {
                name: "One".into(),
                ..NewProject::default()
            },
        )
        .unwrap();
        delete_project(&mut config, first.id.as_str(), &[] as &[Node]).unwrap();
        let second = create_project(
            &mut config,
            &NewProject {
                name: "One".into(),
                ..NewProject::default()
            },
        )
        .unwrap();
        assert_ne!(first.id, second.id, "two draws must be distinct");
    }

    #[test]
    fn resolve_by_id_and_by_name_agree() {
        let config = registry(&[("p-aaaa", "Platform"), ("p-bbbb", "Docs")]);
        let issues = vec![Node::new(1, "One").with(&["p-bbbb"])];
        let by_id = resolve(&config, &issues, "p-bbbb").unwrap();
        let by_name = resolve(&config, &issues, "Docs").unwrap();
        assert_eq!(by_id, by_name);
        assert_eq!(by_id.member_count, 1);
    }

    #[test]
    fn id_resolution_takes_precedence_over_a_name_lookalike() {
        let mut config = registry(&[("p-aaaa", "Platform"), ("Docs", "Docs refresh")]);
        // `Docs` is a valid id shape *and* another project's name.
        config.projects["Docs"].name = "Docs refresh".into();
        let resolved = resolve_project_id(&config, "Docs").unwrap();
        assert_eq!(resolved.as_str(), "Docs", "the id is matched first");
    }

    #[test]
    fn unknown_id_and_unknown_name_are_refused() {
        let config = registry(&[("p-aaaa", "Platform")]);
        for reference in ["p-missing", "No such name"] {
            let err = resolve_project_id(&config, reference).unwrap_err();
            assert_eq!(err.kind(), ProjectDiagnosticKind::UnknownProject);
            assert!(err.message().contains(reference));
        }
    }

    #[test]
    fn list_projects_is_declaration_ordered_with_member_counts() {
        let config = registry(&[("p-zeta", "Zeta"), ("p-alpha", "Alpha")]);
        let issues = vec![
            Node::new(3, "Three").with(&["p-alpha"]),
            Node::new(1, "One").with(&["p-zeta", "p-alpha"]),
        ];
        let projects = list_projects(&config, &issues);
        assert_eq!(
            projects.iter().map(|p| p.name.as_str()).collect::<Vec<_>>(),
            ["Zeta", "Alpha"],
            "declaration order is the display order"
        );
        assert_eq!(projects[0].member_count, 1);
        assert_eq!(projects[1].member_count, 2);
    }

    #[test]
    fn list_projects_never_errors_on_an_empty_registry() {
        let config = Config::default();
        assert_eq!(
            list_projects(&config, &[] as &[Node]),
            [] as [crate::projects::Project; 0]
        );
    }

    #[test]
    fn project_display_shows_the_id_beside_the_name() {
        let id = ProjectId::new("p-3f9a2c").unwrap();
        assert_eq!(project_display(&id, "Platform"), "Platform (p-3f9a2c)");
    }

    // --- T007: the derived index and membership ------------------------------

    #[test]
    fn an_issue_may_belong_to_several_projects() {
        let config = registry(&[("p-aaaa", "One"), ("p-bbbb", "Two")]);
        let issues = vec![Node::new(1, "Shared").with(&["p-aaaa", "p-bbbb"])];
        assert_eq!(
            membership(&config, &issues, "p-aaaa").unwrap().member_count,
            1
        );
        assert_eq!(
            membership(&config, &issues, "p-bbbb").unwrap().member_count,
            1
        );
    }

    #[test]
    fn an_unassociated_issue_is_in_no_bucket() {
        let config = registry(&[("p-aaaa", "One")]);
        let issues = vec![Node::new(1, "None"), Node::new(2, "One").with(&["p-aaaa"])];
        let index = ProjectIndex::build(&config, &issues);
        let id = ProjectId::new("p-aaaa").unwrap();
        assert_eq!(index.bucket(&id).unwrap(), [IssueKey::new(2)]);
    }

    #[test]
    fn bucket_is_none_only_for_an_unknown_project() {
        // "A project with no members yet" and "not a project" must differ: a
        // caller asking for an empty project should not read it as a typo.
        let config = registry(&[("p-aaaa", "One"), ("p-bbbb", "Two")]);
        let issues = vec![Node::new(1, "One").with(&["p-aaaa"])];
        let index = ProjectIndex::build(&config, &issues);

        let known_empty = ProjectId::new("p-bbbb").unwrap();
        assert_eq!(index.bucket(&known_empty), Some(&[][..]));

        let unknown = ProjectId::new("p-missing").unwrap();
        assert_eq!(index.bucket(&unknown), None);
    }

    #[test]
    fn membership_order_is_stable_across_repeated_builds() {
        let config = registry(&[("p-aaaa", "One")]);
        // Fed out of number order, to prove the index sorts rather than assumes.
        let issues = vec![
            Node::new(9, "Nine").with(&["p-aaaa"]),
            Node::new(2, "Two").with(&["p-aaaa"]),
            Node::new(5, "Five").with(&["p-aaaa"]),
        ];
        let first = membership(&config, &issues, "p-aaaa").unwrap();
        let second = membership(&config, &issues, "p-aaaa").unwrap();
        assert_eq!(first, second);
        assert_eq!(
            first
                .members
                .iter()
                .map(|m| m.issue.number())
                .collect::<Vec<_>>(),
            vec![2, 5, 9]
        );
        assert_eq!(first.members[0].display, "#2 Two");
    }

    #[test]
    fn the_free_operations_agree_with_one_built_index() {
        // Observable form of "build once per read": the free contract operations
        // each build one index, and their results must equal the one index built
        // here. A disagreement is a second derivation; two reads of a pure
        // accessor proving equal would have proved nothing.
        let config = registry(&[("p-aaaa", "One"), ("p-bbbb", "Two")]);
        let issues = vec![
            Node::new(1, "One").with(&["p-aaaa", "p-bbbb"]),
            Node::new(2, "Two").with(&["p-aaaa"]),
        ];
        let index = ProjectIndex::build(&config, &issues);

        assert_eq!(membership_index(&config, &issues), *index.buckets());
        assert_eq!(
            membership(&config, &issues, "p-aaaa").unwrap(),
            index.membership("p-aaaa").unwrap()
        );
        assert_eq!(
            validate_references(&config, &issues),
            index.missing().to_vec()
        );
        assert_eq!(
            list_projects(&config, &issues),
            index
                .projects()
                .into_iter()
                .cloned()
                .collect::<Vec<Project>>()
        );
    }

    #[test]
    fn associate_leaves_the_registry_record_unchanged() {
        // Membership is derived, never stored (T007 step 3, review 2). The
        // structural equality alone is guaranteed by the shape (a record has no
        // member field), so the observable form is added: the *serialized*
        // registry — what would land in `tix.toml` — carries no member key, and
        // the change is the only place the members appear.
        let config = registry(&[("p-aaaa", "One")]);
        let before = config.projects["p-aaaa"].clone();
        let issues = vec![Node::new(1, "One")];
        let change = associate(&config, &issues, 1, "p-aaaa").unwrap();

        assert_eq!(config.projects["p-aaaa"], before);
        assert_eq!(
            config.projects.len(),
            1,
            "a project record carries no member list"
        );
        assert_eq!(change.project_ids, vec!["p-aaaa".to_string()]);

        let serialized = toml::to_string(&config).expect("the registry serializes");
        assert!(
            !serialized.contains("member"),
            "no member/members key may reach disk: {serialized}"
        );
    }

    // --- T008: association mutations -----------------------------------------

    #[test]
    fn associate_produces_the_list_and_one_event() {
        let config = registry(&[("p-aaaa", "One")]);
        let issues = vec![Node::new(1, "One")];
        let change = associate(&config, &issues, 1, "p-aaaa").unwrap();
        assert_eq!(ids(&change), ["p-aaaa"]);
        let event = change.event.expect("an accepted change is audited");
        assert_eq!(event.kind, ProjectEventKind::ProjectAssociated);
        assert_eq!(event.project_id, "p-aaaa");
        assert_eq!(event.detail, "project `p-aaaa` associated");
    }

    #[test]
    fn re_association_is_idempotent_and_emits_no_event() {
        let config = registry(&[("p-aaaa", "One")]);
        let issues = vec![Node::new(1, "One").with(&["p-aaaa"])];
        let change = associate(&config, &issues, 1, "p-aaaa").unwrap();
        assert_eq!(ids(&change), ["p-aaaa"], "no duplicate entry");
        assert!(change.event.is_none(), "a no-op is not an audit entry");
    }

    #[test]
    fn associating_an_unknown_project_or_issue_is_refused() {
        let config = registry(&[("p-aaaa", "One")]);
        let issues = vec![Node::new(1, "One")];
        let err = associate(&config, &issues, 1, "p-nope").unwrap_err();
        assert_eq!(err.kind(), ProjectDiagnosticKind::UnknownProject);
        let err = associate(&config, &issues, 99, "p-aaaa").unwrap_err();
        assert_eq!(err.kind(), ProjectDiagnosticKind::UnknownIssue);
        assert!(err.message().contains("99"));
    }

    #[test]
    fn dissociate_keeps_the_issue_intact() {
        let issues = vec![Node::new(1, "One").with(&["p-aaaa", "p-bbbb"])];
        let change = dissociate(&issues, 1, "p-aaaa").unwrap();
        assert_eq!(ids(&change), ["p-bbbb"], "only the one association drops");
        let event = change.event.unwrap();
        assert_eq!(event.kind, ProjectEventKind::ProjectDissociated);
        assert_eq!(event.detail, "project `p-aaaa` dissociated");
        // The node itself is untouched: the service returns a change, it does not
        // mutate or delete the issue (C-004).
        assert_eq!(issues[0].projects, vec!["p-aaaa", "p-bbbb"]);
    }

    #[test]
    fn dissociating_an_absent_association_is_a_noop() {
        let issues = vec![Node::new(1, "One").with(&["p-aaaa"])];
        let change = dissociate(&issues, 1, "p-bbbb").unwrap();
        assert_eq!(ids(&change), ["p-aaaa"]);
        assert!(change.event.is_none());
    }

    #[test]
    fn dissociate_does_not_resolve_a_project_name() {
        // Documented behaviour: `dissociate` compares the stored list verbatim, so
        // a name is an inert no-op. Callers resolve a name to an id first; this
        // keeps a stale/malformed id removable without a registry lookup.
        let issues = vec![Node::new(1, "One").with(&["p-aaaa"])];
        let change = dissociate(&issues, 1, "One").unwrap();
        assert_eq!(ids(&change), ["p-aaaa"], "a name must not match the id");
        assert!(change.event.is_none(), "and it is not an audit entry");
    }

    #[test]
    fn dissociate_removes_a_stale_reference_without_a_project() {
        // The repair path C-005 promises: no registry lookup, only the issue.
        let issues = vec![Node::new(1, "One").with(&["p-deleted"])];
        let change = dissociate(&issues, 1, "p-deleted").unwrap();
        assert_eq!(change.project_ids, [] as [std::string::String; 0]);
        assert!(change.event.is_some());
    }

    #[test]
    fn dissociate_refuses_an_unknown_issue() {
        let issues = vec![Node::new(1, "One")];
        let err = dissociate(&issues, 42, "p-aaaa").unwrap_err();
        assert_eq!(err.kind(), ProjectDiagnosticKind::UnknownIssue);
    }

    #[test]
    fn bulk_associate_reports_each_issue_independently() {
        let config = registry(&[("p-aaaa", "One")]);
        let issues = vec![Node::new(1, "One"), Node::new(2, "Two")];
        let outcomes = bulk_associate(&config, &issues, "p-aaaa", &[1, 99, 2]);

        assert_eq!(outcomes.len(), 3, "one entry per selector");
        assert_eq!(outcomes[0].selector, 1);
        assert!(outcomes[0].outcome.is_ok());
        assert_eq!(
            outcomes[1].outcome.as_ref().unwrap_err().kind(),
            ProjectDiagnosticKind::UnknownIssue,
            "the bad selector is reported, not fatal"
        );
        assert!(
            outcomes[2].outcome.is_ok(),
            "the good selectors after a bad one still process"
        );
        // Exactly one event per accepted change, none per rejected one.
        let events: usize = outcomes
            .iter()
            .filter_map(|o| o.outcome.as_ref().ok())
            .filter(|change| change.event.is_some())
            .count();
        assert_eq!(events, 2);
    }

    #[test]
    fn bulk_associate_reports_an_unknown_project_per_selector() {
        let config = registry(&[("p-aaaa", "One")]);
        let issues = vec![Node::new(1, "One"), Node::new(2, "Two")];
        let outcomes = bulk_associate(&config, &issues, "p-nope", &[1, 2]);
        assert!(outcomes.iter().all(|o| {
            o.outcome.as_ref().unwrap_err().kind() == ProjectDiagnosticKind::UnknownProject
        }));
    }

    // --- T009: missing-reference diagnosis -----------------------------------

    #[test]
    fn a_missing_reference_names_the_issue_and_the_id() {
        let config = registry(&[("p-aaaa", "One")]);
        let issues = vec![Node::new(4, "Four").with(&["p-aaaa", "p-gone"])];
        let missing = validate_references(&config, &issues);
        assert_eq!(missing.len(), 1);
        assert_eq!(missing[0].issue.number(), 4);
        assert_eq!(missing[0].issue_display, "#4 Four");
        assert_eq!(missing[0].project_id, "p-gone");
        assert!(missing[0].reason.contains("#4"));
        assert!(missing[0].reason.contains("p-gone"));
    }

    #[test]
    fn a_resolvable_set_reports_no_missing_references() {
        let config = registry(&[("p-aaaa", "One")]);
        let issues = vec![Node::new(1, "One").with(&["p-aaaa"])];
        assert_eq!(
            validate_references(&config, &issues),
            [] as [crate::projects::MissingProjectReference; 0]
        );
    }

    #[test]
    fn a_duplicated_missing_id_is_reported_once() {
        let config = Config::default();
        let issues = vec![Node::new(1, "One").with(&["p-gone", "p-gone"])];
        assert_eq!(validate_references(&config, &issues).len(), 1);
    }

    #[test]
    fn a_malformed_id_is_a_missing_reference_not_a_panic() {
        let config = Config::default();
        let issues = vec![Node::new(1, "One").with(&["not a valid id"])];
        let missing = validate_references(&config, &issues);
        assert_eq!(missing.len(), 1);
        assert_eq!(missing[0].project_id, "not a valid id");
    }

    #[test]
    fn validate_references_is_deterministic() {
        let config = registry(&[("p-aaaa", "One")]);
        let issues = vec![
            Node::new(3, "Three").with(&["p-z", "p-a"]),
            Node::new(1, "One").with(&["p-m"]),
        ];
        let first = validate_references(&config, &issues);
        let second = validate_references(&config, &issues);
        assert_eq!(first, second);
        assert_eq!(
            first
                .iter()
                .map(|m| (m.issue.number(), m.project_id.as_str()))
                .collect::<Vec<_>>(),
            vec![(1, "p-m"), (3, "p-a"), (3, "p-z")],
            "ordered by (issue number, id)"
        );
    }

    #[test]
    fn a_missing_reference_is_accounted_for_in_the_index() {
        // It must not silently vanish from the index's accounting (T007 step 5).
        let config = Config::default();
        let issues = vec![Node::new(1, "One").with(&["p-gone"])];
        let index = ProjectIndex::build(&config, &issues);
        assert!(index.buckets().is_empty());
        assert_eq!(index.missing().len(), 1);
    }

    // --- T010: operations on in-memory values --------------------------------

    #[test]
    fn the_operations_run_on_in_memory_values() {
        // This pins that the operations run on values built here, not that the
        // module is filesystem-free — a test cannot observe the absence of an
        // `std::fs` call. The filesystem-free property is a documented,
        // inspection-checked claim on the module (no `Store`, no `std::fs`, no
        // `tempfile`), which is what keeps this suite free of a `tempdir`.
        let mut config = Config::default();
        let created = create_project(
            &mut config,
            &NewProject {
                name: "In memory".into(),
                ..NewProject::default()
            },
        )
        .unwrap();
        let issues = vec![Node::new(1, "One")];
        let change = associate(&config, &issues, 1, created.id.as_str()).unwrap();
        assert_eq!(change.project_ids, vec![created.id.to_string()]);
        assert_eq!(list_projects(&config, &issues).len(), 1);
        assert_eq!(
            validate_references(&config, &issues),
            [] as [crate::projects::MissingProjectReference; 0]
        );
    }

    // --- T015/T016: the one progress and health computation ------------------

    #[test]
    fn t015_a_project_with_four_members_and_one_complete_reports_one_of_four() {
        let config = registry(&[("p-aaaa", "One")]);
        let issues = vec![
            Node::new(1, "Done").in_column("done").with(&["p-aaaa"]),
            Node::new(2, "Two").with(&["p-aaaa"]),
            Node::new(3, "Three").with(&["p-aaaa"]),
            Node::new(4, "Four").with(&["p-aaaa"]),
        ];
        let assigned = assigned_keys(&issues);
        let report = health(&config, &issues, "p-aaaa", &assigned, &set(&[]), &set(&[])).unwrap();
        assert_eq!(report.progress.done, 1);
        assert_eq!(report.progress.total, 4);
        assert_eq!(
            report.progress.progress,
            Progress { done: 1, total: 4 },
            "the typed planner value is reused, not restated"
        );
        assert_eq!(report.project_id.as_str(), "p-aaaa");
        assert_eq!(report.name, "One");
    }

    #[test]
    fn t015_an_empty_project_reports_zeros() {
        let config = registry(&[("p-aaaa", "One")]);
        let report =
            health::<Node, _>(&config, &[], "p-aaaa", &set(&[]), &set(&[]), &set(&[])).unwrap();
        assert_eq!(report.progress.progress, Progress { done: 0, total: 0 });
        assert_eq!(report.health.overdue, 0);
        assert_eq!(report.health.blocked, 0);
        assert_eq!(report.health.unassigned, 0);
        assert_eq!(
            report.health.missing_references,
            [] as [crate::projects::MissingProjectReference; 0]
        );
    }

    #[test]
    fn t015_completion_resolves_from_the_configured_column_not_a_literal() {
        // The board completes on `shipped` and has no `done` column at all, so a
        // literal `"done"` comparison cannot pass this: `done` is not even a
        // configured column, and an issue there resolves to no category.
        let mut config = custom_completion(
            &["triage", "wip", "shipped"],
            "shipped",
            &[
                ("triage", "unstarted"),
                ("wip", "active"),
                ("shipped", "completed"),
            ],
        );
        config.projects.insert(
            "p-aaaa".to_string(),
            ProjectConfiguration {
                name: "One".to_string(),
                ..ProjectConfiguration::default()
            },
        );
        let issues = vec![
            Node::new(1, "Shipped")
                .in_column("shipped")
                .with(&["p-aaaa"]),
            Node::new(2, "Literal done")
                .in_column("done")
                .with(&["p-aaaa"]),
        ];
        let report = health(&config, &issues, "p-aaaa", &set(&[]), &set(&[]), &set(&[])).unwrap();
        assert_eq!(
            report.progress.done, 1,
            "only the configured completion column counts"
        );
        assert_eq!(report.progress.total, 2);
    }

    #[test]
    fn t016_health_counts_the_known_fixture_exactly() {
        let config = registry(&[("p-aaaa", "One")]);
        let issues = vec![
            Node::new(1, "Complete")
                .in_column("done")
                .assigned_to("alice")
                .with(&["p-aaaa"]),
            Node::new(2, "Overdue")
                .assigned_to("bob")
                .with(&["p-aaaa", "p-gone"]),
            Node::new(3, "Blocked")
                .assigned_to("carol")
                .with(&["p-aaaa"]),
            Node::new(4, "Unassigned").with(&["p-aaaa"]),
        ];
        let assigned = assigned_keys(&issues);
        // #1 is complete **and** in the overdue set: a done issue is not overdue.
        let report = health(
            &config,
            &issues,
            "p-aaaa",
            &assigned,
            &set(&[1, 2]),
            &set(&[3]),
        )
        .unwrap();
        assert_eq!(report.progress.done, 1);
        assert_eq!(report.progress.total, 4);
        assert_eq!(report.health.overdue, 1, "a done issue is not overdue");
        assert_eq!(report.health.blocked, 1);
        assert_eq!(report.health.unassigned, 1);
        assert_eq!(report.health.missing_references.len(), 1);
        let missing = &report.health.missing_references[0];
        assert_eq!(missing.issue.number(), 2);
        assert_eq!(missing.project_id, "p-gone");
        assert_ne!(missing.reason, "");
    }

    #[test]
    fn t016_a_done_member_is_never_overdue() {
        let config = registry(&[("p-aaaa", "One")]);
        let issues = vec![
            Node::new(1, "Done").in_column("done").with(&["p-aaaa"]),
            Node::new(2, "Open").with(&["p-aaaa"]),
        ];
        let report = health(
            &config,
            &issues,
            "p-aaaa",
            &set(&[1, 2]),
            &set(&[1, 2]),
            &set(&[]),
        )
        .unwrap();
        assert_eq!(
            report.health.overdue, 1,
            "only the open overdue member counts"
        );
    }

    #[test]
    fn t016_a_blank_assignee_counts_as_unassigned() {
        let config = registry(&[("p-aaaa", "One")]);
        let issues = vec![
            Node::new(1, "Absent").with(&["p-aaaa"]),
            Node::new(2, "Blank").assigned_to("   ").with(&["p-aaaa"]),
            Node::new(3, "Assigned")
                .assigned_to("alice")
                .with(&["p-aaaa"]),
        ];
        let assigned = assigned_keys(&issues);
        assert_eq!(assigned, set(&[3]), "absent and blank are both unassigned");
        let report = health(&config, &issues, "p-aaaa", &assigned, &set(&[]), &set(&[])).unwrap();
        assert_eq!(report.health.unassigned, 2);
    }

    #[test]
    fn t016_a_resolvable_member_set_reports_no_missing_references() {
        let config = registry(&[("p-aaaa", "One")]);
        let issues = vec![Node::new(1, "One").with(&["p-aaaa"])];
        let report = health(&config, &issues, "p-aaaa", &set(&[1]), &set(&[]), &set(&[])).unwrap();
        assert_eq!(
            report.health.missing_references,
            [] as [crate::projects::MissingProjectReference; 0]
        );
    }

    #[test]
    fn t016_health_refuses_an_unknown_project() {
        let config = registry(&[("p-aaaa", "One")]);
        let err =
            health::<Node, _>(&config, &[], "p-nope", &set(&[]), &set(&[]), &set(&[])).unwrap_err();
        assert_eq!(err.kind(), ProjectDiagnosticKind::UnknownProject);
    }

    // --- T019: determinism and the single-implementation guard ---------------

    #[test]
    fn t019_c006_the_health_read_is_deterministic_and_correct() {
        // Non-vacuous by construction: the fixture's figures are spelled out, so a
        // stub returning a constant fails the correctness half, and the repeated
        // reads are compared, so a non-deterministic read fails the other half.
        let config = registry(&[("p-aaaa", "One")]);
        let issues = vec![
            Node::new(1, "Complete")
                .in_column("done")
                .assigned_to("alice")
                .with(&["p-aaaa"]),
            Node::new(2, "Overdue").assigned_to("bob").with(&["p-aaaa"]),
            Node::new(3, "Blocked")
                .assigned_to("carol")
                .with(&["p-aaaa"]),
            Node::new(4, "Unassigned").with(&["p-aaaa"]),
        ];
        let assigned = assigned_keys(&issues);
        let first = health(
            &config,
            &issues,
            "p-aaaa",
            &assigned,
            &set(&[2]),
            &set(&[3]),
        )
        .unwrap();
        assert_eq!(
            first.progress,
            ProjectProgress {
                done: 1,
                total: 4,
                progress: Progress { done: 1, total: 4 },
            }
        );
        assert_eq!(first.health.overdue, 1);
        assert_eq!(first.health.blocked, 1);
        assert_eq!(first.health.unassigned, 1);
        for _ in 0..3 {
            let again = health(
                &config,
                &issues,
                "p-aaaa",
                &assigned,
                &set(&[2]),
                &set(&[3]),
            )
            .unwrap();
            assert_eq!(again, first, "repeated reads of one snapshot are identical");
        }
    }

    #[test]
    fn t019_c006_a_noop_association_change_leaves_the_figures_unchanged() {
        // A no-op mutation must not move a figure. The returned list is **applied**
        // back into the snapshot before the second read — not merely re-read from
        // the original slice — so the assertion can actually fail: it observes the
        // round trip through `dissociate`'s output, not a second read of the same
        // input. (Re-reading the unchanged input would hold for any deterministic
        // implementation and would prove nothing.)
        let config = registry(&[("p-aaaa", "One")]);
        let issues = vec![
            Node::new(1, "Complete").in_column("done").with(&["p-aaaa"]),
            Node::new(2, "Open").with(&["p-aaaa"]),
        ];
        let assigned = assigned_keys(&issues);
        let before = health(&config, &issues, "p-aaaa", &assigned, &set(&[2]), &set(&[])).unwrap();

        let change = dissociate(&issues, 1, "p-bbbb").unwrap();
        assert_eq!(ids(&change), ["p-aaaa"], "the list is unchanged");
        assert!(change.event.is_none(), "no event is emitted");

        let mut applied = issues.clone();
        applied[0].projects = change.project_ids.clone();
        let assigned_after = assigned_keys(&applied);
        let after = health(
            &config,
            &applied,
            "p-aaaa",
            &assigned_after,
            &set(&[2]),
            &set(&[]),
        )
        .unwrap();
        assert_eq!(
            before, after,
            "applying the no-op leaves the figures unchanged"
        );
    }
}