tix/

epics.rs

//! The single owner of epic behaviour (mission `epics-work-items-01M3BYW4`,
//! WP02 — `contracts/epic-service.md`).
//!
//! Everything about an epic lives here: identity and resolution, the registry
//! lifecycle (create / edit / delete / list), the derived hierarchy with its
//! dedicated iterative cycle walk, reference diagnosis across all five kinds,
//! derived membership and the index that makes an epic filter a bucket lookup,
//! and — in exactly one place — the epic rollup (completion, child counts,
//! weight, blocked work). A second identity resolver, a second membership index,
//! a second progress implementation, a second relationship mechanism, or a
//! second milestone/cycle store is the divergence the mission's charter
//! escalates (C-002, C-008).
//!
//! ## What this module deliberately does not do
//!
//! - **It performs no file I/O** — no `Store`, no `std::fs`, no `tempfile`. It
//!   takes an in-memory [`Config`] and an in-memory issue set and returns values;
//!   the write path is storage's (WP03) and this module owns the rule. Every
//!   operation is therefore testable with no repository at all (T012 step 4).
//!   [`ReferenceTargets::from_planner`] is the one optional adapter that consumes
//!   another owner's filesystem-backed lookup; the sets it produces are plain
//!   in-memory values, and a caller can supply them directly instead.
//! - **It does not know about the issue model.** [`EpicNode`] is the minimum an
//!   issue must expose — its number, title, status, and its `epics` id list — and
//!   WP03 implements it for [`crate::model::Issue`], exactly as the project
//!   service's `ProjectNode` and the hierarchy service's `HierarchyNode` are
//!   implemented there. WP02 is forbidden from touching `src/model.rs`, so the
//!   service is defined against the shape WP03 provides. Because the trait has
//!   **no label accessor**, membership is structurally incapable of telling a
//!   `task`-labelled issue from any other — that is the C-001 guard, not a
//!   convention.
//! - **It never mutates or returns a whole `Issue`.** [`reference_epic`] and
//!   [`dereference_epic`] return an [`EpicChange`]: the resulting reference list
//!   plus the History event to append. Storage applies it. That boundary is what
//!   keeps this module model-free.
//! - **It stores no membership.** An epic's members are derived by inverting the
//!   issues' reference lists and are never persisted (data-model §4, C-002). The
//!   registry record carries no member list at all.
//! - **It does not recompute blocked state.** [`EpicIndex::rollup`] consumes
//!   source issue 169's derived [`RelationshipGraph::blocked_state`] and reuses
//!   its `reason` text verbatim (research R4). Re-deriving blocked work here
//!   would create a second owner for state another Mission owns.
//! - **It does not reimplement milestone or cycle lookup.** [`ReferenceTargets`]
//!   consumes `Planner::milestone_names()`, `Planner::cycle_names()` and
//!   `Planner::cycle()` (`src/planning.rs`) through
//!   [`ReferenceTargets::from_planner`]; no second store is introduced (research
//!   R2). Project references are checked against the project registry itself,
//!   never by reversing this module's index (research R6).
//! - **It does not share the issue-parent cycle walk.** An epic chain and an
//!   issue-parent chain are different semantics (C-002); the walk below *follows
//!   the same shape* as `crate::hierarchy`'s and is dedicated to epics.
//!
//! ## The index is built once per read
//!
//! [`EpicIndex`] is the derived view over one snapshot. It is built once
//! ([`EpicIndex::build`]) and every read — [`EpicIndex::membership`],
//! [`EpicIndex::resolve`], [`EpicIndex::hierarchy`], [`EpicIndex::rollup`],
//! [`EpicIndex::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 and a rollup never re-scans the issue set (NFR-001).
//!
//! ## Ordering is deterministic
//!
//! Members are ordered by issue number, epics by declaration order, child lists
//! by declaration order, ancestors root-first, and diagnostics by
//! `(holder, kind, target)`, so repeated reads of the same snapshot are
//! identical (contract §8).

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

use indexmap::IndexMap;

use crate::config::{Config, EpicConfiguration, EpicId, ProjectId};
use crate::cycle_store::DEFAULT_CYCLE_NAME;
use crate::error::{Result, TixError};
use crate::planning::{Planner, Progress};
use crate::relationships::RelationshipGraph;

pub use crate::projects::{IssueKey, MemberRef, Patch};

/// The frontmatter key carrying an issue's epic references.
///
/// WP03's field is `epics` (contracts/epic-registry.md §3); named once here so a
/// second spelling has no home.
pub const EPICS_KEY: &str = "epics";

/// The minimum an issue must expose for epic 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. There is deliberately **no** label accessor: C-001 requires a
/// `task`-labelled issue to be an ordinary member, and a trait that cannot see
/// labels cannot make it anything else.
pub trait EpicNode {
    /// 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, compared against the board's completion column.
    fn status(&self) -> &str;
    /// The stored epic ids, in the order the file carries them.
    fn epic_ids(&self) -> &[String];
}

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

/// A derived reference to another epic, with its display label.
///
/// The label is computed on read and **never stored**: a stored name goes stale
/// the moment the epic is renamed (data-model §2).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct EpicRef {
    /// The referenced epic's stable id.
    pub id: EpicId,
    /// The epic's display label at read time.
    pub name: String,
    /// `Name (e-id)`, from [`epic_display`].
    pub display: String,
}

impl EpicRef {
    /// Build a reference, deriving the label from the name.
    #[must_use]
    pub fn new(id: &EpicId, name: &str) -> Self {
        Self {
            id: id.clone(),
            name: name.to_string(),
            display: epic_display(id, name),
        }
    }
}

/// The service-side view of an epic (data-model §2).
///
/// Combines the registry record with the derived members and children.
/// Registry-only operations ([`create_epic`], [`edit_epic`]) return it with an
/// **empty** member list — there is no issue set to derive from — while
/// index-backed operations ([`EpicIndex::resolve`], [`list_epics`]) fill it.
/// Nothing here is stored.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Epic {
    /// The stable registry key; the identity that survives a rename (C-003).
    pub id: EpicId,
    /// The mutable display label; never the identity.
    pub name: String,
    /// Optional long-form context.
    pub description: Option<String>,
    /// Optional epic status (free-form; not a board column, not a category).
    pub status: Option<String>,
    /// Optional owner identity string.
    pub owner: Option<String>,
    /// Optional start date (`YYYY-MM-DD`).
    pub start_date: Option<String>,
    /// Optional due date (`YYYY-MM-DD`).
    pub due_date: Option<String>,
    /// Optional positive relative size, used by the epic rollup.
    pub weight: Option<i64>,
    /// The recorded parent epic **id**, exactly as stored. Retained even when it
    /// no longer resolves, so the reference can be repaired (contract §3.4).
    pub parent: Option<String>,
    /// Project **ids** this epic concerns, verbatim (FR-002).
    pub projects: Vec<String>,
    /// The recorded milestone **name**, verbatim (FR-002).
    pub milestone: Option<String>,
    /// The recorded cycle **name**, verbatim (FR-002).
    pub cycle: 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,
    /// Derived child epics, in registry declaration order. Never stored.
    pub children: Vec<EpicRef>,
    /// `children.len()`.
    pub child_count: usize,
}

impl Epic {
    /// Project a registry record into the service view.
    fn from_configuration(
        id: EpicId,
        record: &EpicConfiguration,
        members: Vec<MemberRef>,
        children: Vec<EpicRef>,
    ) -> Self {
        Self {
            id,
            name: record.name.clone(),
            description: record.description.clone(),
            status: record.status.clone(),
            owner: record.owner.clone(),
            start_date: record.start_date.clone(),
            due_date: record.due_date.clone(),
            weight: record.weight,
            parent: record.parent.clone(),
            projects: record.projects.clone(),
            milestone: record.milestone.clone(),
            cycle: record.cycle.clone(),
            member_count: members.len(),
            members,
            child_count: children.len(),
            children,
        }
    }
}

/// The shared display form for an epic: `Harden the sync path (e-7c4a91)`.
///
/// One function, because every listing must show the id beside the name and a
/// second formatting site is how two surfaces end up disagreeing about what an
/// epic is called.
#[must_use]
pub fn epic_display(id: &EpicId, name: &str) -> String {
    format!("{name} ({id})")
}

/// The diagnostic kinds the epic service names, spelled exactly.
///
/// The variants map one-to-one onto [`EpicError`], so a surface prints the named
/// kind without a second classification step (contract `cli-surface.md` §4).
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum EpicDiagnosticKind {
    /// A name is blank, padded, or already in use.
    DuplicateName,
    /// An epic reference names no stored epic.
    UnknownEpic,
    /// An issue selector names no issue in the snapshot.
    UnknownIssue,
    /// The start/due dates are malformed or inverted.
    InvalidDates,
    /// The weight is not a positive relative size.
    InvalidWeight,
    /// A reference field's value is not a well-formed id.
    InvalidReference,
    /// The proposed parent is the epic itself.
    SelfParent,
    /// The proposed parent chain would close a cycle.
    Cycle,
}

impl EpicDiagnosticKind {
    /// The canonical snake_case spelling a surface prints.
    #[must_use]
    pub fn as_str(self) -> &'static str {
        match self {
            EpicDiagnosticKind::DuplicateName => "duplicate_name",
            EpicDiagnosticKind::UnknownEpic => "unknown_epic",
            EpicDiagnosticKind::UnknownIssue => "unknown_issue",
            EpicDiagnosticKind::InvalidDates => "invalid_dates",
            EpicDiagnosticKind::InvalidWeight => "invalid_weight",
            EpicDiagnosticKind::InvalidReference => "invalid_reference",
            EpicDiagnosticKind::SelfParent => "self_parent",
            EpicDiagnosticKind::Cycle => "cycle",
        }
    }
}

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

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

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

/// The single wording for an epic 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!("epic dates are invalid: {detail}")
}

/// The single wording for an epic weight refusal.
#[must_use]
pub fn invalid_weight_reason(value: i64) -> String {
    format!("epic weight must be a positive integer; got {value}")
}

/// The single wording for a reference field whose value is not a well-formed id.
///
/// The write-path half of WP01's load-time shape check: an epic references a
/// project **by id**, so a value that is not one has to be refused rather than
/// stored, or the registry would no longer load. A *dangling* but well-formed id
/// is a different thing and is stored, then diagnosed (C-005).
#[must_use]
pub fn invalid_reference_reason(field: &str, value: &str) -> String {
    format!(
        "`epics.<id>.{field}` entry `{value}` is not a well-formed id; \
         an epic references the target by its stable id"
    )
}

/// The single wording for an epic name refusal.
#[must_use]
pub fn duplicate_name_reason(name: &str) -> String {
    if name.trim().is_empty() {
        "an epic name must not be blank".to_string()
    } else if name.trim() != name {
        format!("epic name `{name}` has leading or trailing whitespace")
    } else {
        format!("epic name `{name}` is already in use; epic names must be unique")
    }
}

/// The single wording for a self-parent refusal.
#[must_use]
pub fn self_parent_reason(epic: &EpicId) -> String {
    format!("epic `{epic}` cannot be its own parent")
}

/// The single wording for a cycle refusal, naming the offending path.
#[must_use]
pub fn cycle_reason(epic: &EpicId, path: &[EpicId]) -> String {
    let rendered: Vec<&str> = path.iter().map(EpicId::as_str).collect();
    format!(
        "parent would close an epic cycle: `{epic}` -> {}",
        rendered.join(" -> ")
    )
}

/// The single wording for an unresolved parent epic (contract §3.4).
#[must_use]
pub fn unresolved_parent_reason(epic: &EpicId, recorded_parent: &str) -> String {
    format!(
        "epic `{epic}` records parent `{recorded_parent}`, which no longer exists \
         (the reference is kept so it can be repaired)"
    )
}

/// The single wording for a reference 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 reference_detail(epic_id: &str, referenced: bool) -> String {
    if referenced {
        format!("epic `{epic_id}` referenced")
    } else {
        format!("epic `{epic_id}` dereferenced")
    }
}

/// Why an epic operation was refused.
///
/// The variants map one-to-one onto [`EpicDiagnosticKind`] and carry the
/// contract's names (`contracts/epic-service.md` §1).
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum EpicError {
    /// An epic reference did not resolve.
    UnknownEpic {
        /// 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 name is blank, padded, or already in use.
    DuplicateName {
        /// The name as supplied.
        name: String,
    },
    /// The start/due dates are malformed or inverted.
    InvalidDates {
        /// The shared date rule's message.
        detail: String,
    },
    /// The weight is not a positive relative size.
    InvalidWeight {
        /// The value as supplied.
        value: i64,
    },
    /// A reference field's value is not a well-formed id.
    InvalidReference {
        /// The record field the value belongs to, e.g. `projects`.
        field: &'static str,
        /// The value as supplied.
        value: String,
    },
    /// The proposed parent is the epic itself.
    SelfParent {
        /// The epic that would parent itself.
        epic: EpicId,
    },
    /// The proposed parent chain would close a cycle.
    Cycle {
        /// The epic whose proposed parent closes the loop.
        epic: EpicId,
        /// The offending path, from the epic back to itself.
        path: Vec<EpicId>,
    },
}

impl EpicError {
    /// The named diagnostic kind this refusal reports.
    #[must_use]
    pub fn kind(&self) -> EpicDiagnosticKind {
        match self {
            EpicError::UnknownEpic { .. } => EpicDiagnosticKind::UnknownEpic,
            EpicError::UnknownIssue { .. } => EpicDiagnosticKind::UnknownIssue,
            EpicError::DuplicateName { .. } => EpicDiagnosticKind::DuplicateName,
            EpicError::InvalidDates { .. } => EpicDiagnosticKind::InvalidDates,
            EpicError::InvalidWeight { .. } => EpicDiagnosticKind::InvalidWeight,
            EpicError::InvalidReference { .. } => EpicDiagnosticKind::InvalidReference,
            EpicError::SelfParent { .. } => EpicDiagnosticKind::SelfParent,
            EpicError::Cycle { .. } => EpicDiagnosticKind::Cycle,
        }
    }

    /// The single wording for this refusal, via the kind's helper.
    #[must_use]
    pub fn message(&self) -> String {
        match self {
            EpicError::UnknownEpic { reference } => unknown_epic_reason(reference),
            EpicError::UnknownIssue { selector } => unknown_issue_reason(selector),
            EpicError::DuplicateName { name } => duplicate_name_reason(name),
            EpicError::InvalidDates { detail } => invalid_dates_reason(detail),
            EpicError::InvalidWeight { value } => invalid_weight_reason(*value),
            EpicError::InvalidReference { field, value } => invalid_reference_reason(field, value),
            EpicError::SelfParent { epic } => self_parent_reason(epic),
            EpicError::Cycle { epic, path } => cycle_reason(epic, path),
        }
    }
}

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

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

/// An epic 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<EpicError> for TixError {
    fn from(err: EpicError) -> TixError {
        TixError::InvalidInput(err.to_string())
    }
}

/// The spec for a new epic (contract §1: name plus optional metadata).
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct NewEpic {
    /// Required display label.
    pub name: String,
    /// Optional long-form context.
    pub description: Option<String>,
    /// Optional epic status.
    pub status: Option<String>,
    /// Optional owner identity string.
    pub owner: Option<String>,
    /// Optional start date.
    pub start_date: Option<String>,
    /// Optional due date.
    pub due_date: Option<String>,
    /// Optional positive relative size.
    pub weight: Option<i64>,
    /// Project **ids** this epic concerns (FR-002). Shape is checked; existence is
    /// diagnosed rather than refused, so a dangling reference is repairable.
    pub projects: Vec<String>,
    /// Optional milestone name (the existing name-keyed reference).
    pub milestone: Option<String>,
    /// Optional cycle name (the existing name-keyed reference).
    pub cycle: Option<String>,
}

/// The fields of an epic edit.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct EpicEdit {
    /// The display label. A rename is a label change only (C-003, NFR-002).
    pub name: Patch<String>,
    /// Long-form context.
    pub description: Patch<String>,
    /// Epic status.
    pub status: Patch<String>,
    /// Owner identity string.
    pub owner: Patch<String>,
    /// Start date.
    pub start_date: Patch<String>,
    /// Due date.
    pub due_date: Patch<String>,
    /// Weight.
    pub weight: Patch<i64>,
    /// The parent epic reference: `Set` resolves to the parent's id and is
    /// validated against the epic chain, `Clear` detaches the epic.
    pub parent: Patch<String>,
    /// Project **ids** this epic concerns. Each entry is shape-validated and never
    /// resolved, so a dangling-but-well-formed id is stored for repair (C-005).
    pub projects: Patch<Vec<String>>,
    /// Milestone name; `Clear` removes the reference.
    pub milestone: Patch<String>,
    /// Cycle name; `Clear` removes the reference.
    pub cycle: Patch<String>,
}

/// The impact report of an epic deletion (contract §1).
///
/// It **reports**; it does not delete. The affected issues keep their references
/// (which then read as missing references, C-005) and the child epics keep their
/// recorded parent (which then reads as unresolved, contract §3.4), so this type
/// carries them for the caller's notice rather than a cascade (C-006).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct EpicDeletion {
    /// The id that was removed from the registry. Never handed out again.
    pub id: EpicId,
    /// The name the record carried, for the notice.
    pub name: String,
    /// The issues that still reference the deleted epic, ordered by number.
    pub affected: Vec<MemberRef>,
    /// The epics that recorded it as their parent, in declaration order.
    pub child_epics: Vec<EpicRef>,
}

/// 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_epics`): non-blank, no padding,
/// and unique case-folded, since a user does not tell `Platform` from `platform`.
/// WP01 owns the loader's copy; this is the write-path half, pinned to the same
/// rule by `t006_create_epic_refuses_a_duplicate_name`.
fn validate_name(
    registry: &IndexMap<String, EpicConfiguration>,
    name: &str,
    exclude: Option<&EpicId>,
) -> Result<(), EpicError> {
    if name.trim().is_empty() || name.trim() != name {
        return Err(EpicError::DuplicateName {
            name: name.to_string(),
        });
    }
    let normalized = name.to_lowercase();
    let clash = registry.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(EpicError::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<(), EpicError> {
    crate::model::validate_issue_dates(start, due).map_err(|err| EpicError::InvalidDates {
        detail: err.to_string(),
    })
}

/// Validate a project-id list: shape only, never resolution.
///
/// Each entry must be a well-formed [`ProjectId`], because that is what a
/// registry must hold to load. A well-formed id the project registry does not
/// hold is **kept** — it is the diagnosable dangling reference C-005 promises —
/// and an exact duplicate collapses to one reference, as a repeated issue-side id
/// does. The caller's order is preserved.
fn validate_project_ids(list: &[String]) -> Result<Vec<String>, EpicError> {
    let mut out: Vec<String> = Vec::new();
    for entry in list {
        let id = ProjectId::new(entry).map_err(|_| EpicError::InvalidReference {
            field: "projects",
            value: entry.clone(),
        })?;
        if !out.iter().any(|stored| stored == id.as_str()) {
            out.push(id.to_string());
        }
    }
    Ok(out)
}

/// Validate a weight: a positive relative size, or nothing.
fn validate_weight(weight: i64) -> Result<(), EpicError> {
    if weight > 0 {
        return Ok(());
    }
    Err(EpicError::InvalidWeight { value: weight })
}

/// Resolve an epic id from a reference: **id first**, then a name convenience.
///
/// Resolution is by the stable id (C-003). A name is accepted because a human
/// selects epics by name; it resolves to the same epic, and WP01's uniqueness
/// rule guarantees it is unambiguous. An id that also happens to look like
/// another epic's name wins, which is what "id first" means.
pub fn resolve_epic_id(
    registry: &IndexMap<String, EpicConfiguration>,
    reference: &str,
) -> Result<EpicId, EpicError> {
    if let Ok(id) = EpicId::new(reference) {
        if registry.contains_key(id.as_str()) {
            return Ok(id);
        }
    }
    let normalized = reference.trim().to_lowercase();
    if let Some((raw, _)) = registry
        .iter()
        .find(|(_, record)| record.name.to_lowercase() == normalized)
    {
        return EpicId::new(raw).map_err(|_| EpicError::UnknownEpic {
            reference: reference.to_string(),
        });
    }
    Err(EpicError::UnknownEpic {
        reference: reference.to_string(),
    })
}

/// The id a **dereference** should match for `reference` (WP09 item B).
///
/// One owner for the resolve-or-keep-verbatim classification the repair path
/// needs: a reference that names a live epic resolves to its stable id, and
/// anything else — a stale id, a malformed one, or a name-shaped string the
/// registry no longer holds — is passed through **verbatim** so
/// `tix epic remove` can still drop it (C-005). A second spelling of this rule
/// would let one surface refuse a removal another surface performs.
///
/// The callers are `commands::epic::dereference_from_epic`,
/// `commands::epic::plan_edit_epics`, and MCP's `epic_dissociate_issues`, so the
/// three cannot drift.
#[must_use]
pub(crate) fn dereference_needle(
    registry: &IndexMap<String, EpicConfiguration>,
    reference: &str,
) -> String {
    resolve_epic_id(registry, reference).map_or_else(|_| reference.to_string(), |id| id.to_string())
}

/// The epics that record `id` as their parent, in declaration order.
fn recorded_children(registry: &IndexMap<String, EpicConfiguration>, id: &EpicId) -> Vec<EpicRef> {
    registry
        .iter()
        .filter(|(_, record)| record.parent.as_deref() == Some(id.as_str()))
        .filter_map(|(raw, record)| {
            EpicId::new(raw)
                .ok()
                .map(|child| EpicRef::new(&child, &record.name))
        })
        .collect()
}

/// Create an epic, allocating a fresh stable id (FR-001).
///
/// Validates the name, the dates, and the weight first, so a refusal yields no
/// registry change (contract §4). 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. The returned view carries no members or children —
/// a create has no issue set to derive from.
pub fn create_epic(config: &mut Config, new: &NewEpic) -> Result<Epic, EpicError> {
    validate_name(&config.epics, &new.name, None)?;
    validate_dates(new.start_date.as_deref(), new.due_date.as_deref())?;
    if let Some(weight) = new.weight {
        validate_weight(weight)?;
    }
    let projects = validate_project_ids(&new.projects)?;
    let id = config.allocate_epic_id();
    let record = EpicConfiguration {
        name: new.name.clone(),
        description: normalize_optional(new.description.clone()),
        status: normalize_optional(new.status.clone()),
        owner: normalize_optional(new.owner.clone()),
        start_date: new.start_date.clone(),
        due_date: new.due_date.clone(),
        weight: new.weight,
        projects,
        milestone: normalize_optional(new.milestone.clone()),
        cycle: normalize_optional(new.cycle.clone()),
        ..EpicConfiguration::default()
    };
    config.epics.insert(id.to_string(), record.clone());
    Ok(Epic::from_configuration(
        id,
        &record,
        Vec::new(),
        Vec::new(),
    ))
}

/// Edit an epic's fields by reference.
///
/// A name change is a **label change only**: the registry key is untouched, so
/// every member reference and derived figure stays intact (C-003, NFR-002). A
/// proposed parent is validated — self-parent and cycle — **before** any write,
/// so a rejection leaves the registry byte-unchanged (contract §3, §4). The
/// returned view carries no members — an edit has no issue set to derive from.
pub fn edit_epic(config: &mut Config, reference: &str, edit: &EpicEdit) -> Result<Epic, EpicError> {
    let id = resolve_epic_id(&config.epics, reference)?;
    let mut updated =
        config
            .epics
            .get(id.as_str())
            .cloned()
            .ok_or_else(|| EpicError::UnknownEpic {
                reference: reference.to_string(),
            })?;

    // --- validation first: nothing below this block runs on a refusal --------
    match &edit.name {
        Patch::Unchanged => {}
        Patch::Clear => {
            return Err(EpicError::DuplicateName {
                name: String::new(),
            });
        }
        Patch::Set(name) => {
            validate_name(&config.epics, name, Some(&id))?;
        }
    }
    if let Patch::Set(weight) = &edit.weight {
        validate_weight(*weight)?;
    }
    let proposed_parent = match &edit.parent {
        Patch::Unchanged => None,
        Patch::Clear => Some(None),
        Patch::Set(parent) => Some(Some(validate_epic_parent(&config.epics, &id, parent)?)),
    };
    let proposed_projects = match &edit.projects {
        Patch::Unchanged => None,
        Patch::Clear => Some(Vec::new()),
        Patch::Set(list) => Some(validate_project_ids(list)?),
    };

    // --- apply --------------------------------------------------------------
    if let Patch::Set(name) = &edit.name {
        updated.name.clone_from(name);
    }
    apply_optional(&edit.description, &mut updated.description);
    apply_optional(&edit.status, &mut updated.status);
    apply_optional(&edit.owner, &mut updated.owner);
    apply_date(&edit.start_date, &mut updated.start_date);
    apply_date(&edit.due_date, &mut updated.due_date);
    if let Patch::Set(weight) = &edit.weight {
        updated.weight = Some(*weight);
    }
    if let Patch::Clear = &edit.weight {
        updated.weight = None;
    }
    if let Some(parent) = proposed_parent {
        updated.parent = parent.map(|id| id.to_string());
    }
    if let Some(projects) = proposed_projects {
        updated.projects = projects;
    }
    apply_optional(&edit.milestone, &mut updated.milestone);
    apply_optional(&edit.cycle, &mut updated.cycle);

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

    if let Some(record) = config.epics.get_mut(id.as_str()) {
        *record = updated.clone();
    }
    Ok(Epic::from_configuration(
        id,
        &updated,
        Vec::new(),
        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 an epic from the registry, reporting what referenced it.
///
/// Removes the registry entry **only**. Every member issue keeps its `epics`
/// entry (which then reads as a missing reference) and every child epic keeps its
/// recorded parent (which then reads as unresolved), so both can be repaired
/// rather than being silently rebound (C-005, C-006). The id is never reused
/// (WP01's allocation carries that guarantee).
pub fn delete_epic<N: EpicNode>(
    config: &mut Config,
    reference: &str,
    issues: &[N],
) -> Result<EpicDeletion, EpicError> {
    let id = resolve_epic_id(&config.epics, reference)?;
    let record = config
        .epics
        .get(id.as_str())
        .cloned()
        .ok_or_else(|| EpicError::UnknownEpic {
            reference: reference.to_string(),
        })?;
    let affected = EpicIndex::build(config, issues)
        .epic(&id)
        .map(|epic| epic.members.clone())
        .unwrap_or_default();
    let child_epics = recorded_children(&config.epics, &id);
    config.epics.shift_remove(id.as_str());
    Ok(EpicDeletion {
        id,
        name: record.name,
        affected,
        child_epics,
    })
}

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

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

/// The derived epic view over one snapshot of issues and the registry.
///
/// Built once and read many times. The bucket map is the NFR-001 index; the epic
/// map is an `IndexMap` so declaration order is the display order; the label and
/// status maps carry what a member listing and the completion read need. Nothing
/// here is stored.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct EpicIndex {
    /// Epics in declaration order, each carrying its derived members and children.
    epics: IndexMap<EpicId, Epic>,
    /// The reverse index: epic -> member issue keys, ascending.
    buckets: HashMap<EpicId, Vec<IssueKey>>,
    /// Recorded parent per epic, id-typed and only for resolvable ids.
    parents: HashMap<EpicId, EpicId>,
    /// Child epics per epic, in declaration order.
    children: HashMap<EpicId, Vec<EpicId>>,
    /// References whose epic does not resolve, deterministically ordered.
    missing: Vec<EpicReferenceResolution>,
    /// Issue number -> display label, for member listings.
    labels: HashMap<IssueKey, String>,
    /// Issue number -> status, for the completion read.
    statuses: HashMap<IssueKey, String>,
}

impl EpicIndex {
    /// Build the index in **one pass** over the issue set.
    ///
    /// Membership comes from each issue's `epics` list, never from the registry.
    /// A reference whose epic does not resolve is kept in [`Self::missing`] rather
    /// than dropped: a silently absent reference is the failure C-005 forbids, and
    /// [`resolve_references`] reports exactly this set.
    pub fn build<N: EpicNode>(config: &Config, issues: &[N]) -> Self {
        Self::build_from_registry(&config.epics, issues)
    }

    /// [`Self::build`] against a bare registry, for callers that hold only the
    /// `[epics.<id>]` table (the contract's `registry + issue set` operations).
    pub fn build_from_registry<N: EpicNode>(
        registry: &IndexMap<String, EpicConfiguration>,
        issues: &[N],
    ) -> Self {
        let known: HashSet<String> = registry.keys().cloned().collect();

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

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

            // A duplicated id on one issue is one reference: reported once,
            // bucketed once (T007 step 7).
            let mut seen: HashSet<&str> = HashSet::new();
            for raw in issue.epic_ids() {
                if !seen.insert(raw.as_str()) {
                    continue;
                }
                let holder = ReferenceHolder::Issue(key);
                match EpicId::new(raw) {
                    Ok(id) if known.contains(id.as_str()) => {
                        buckets.entry(id).or_default().push(key);
                    }
                    Ok(_) => missing.push(EpicReferenceResolution {
                        holder: holder.clone(),
                        target_kind: EpicReferenceKind::Epic,
                        target: raw.clone(),
                        reason: missing_epic_reason(&holder, raw),
                    }),
                    Err(_) => missing.push(EpicReferenceResolution {
                        holder,
                        target_kind: EpicReferenceKind::Issue,
                        target: raw.clone(),
                        reason: malformed_epic_reason(issue.number(), raw),
                    }),
                }
            }
        }

        for members in buckets.values_mut() {
            members.sort_unstable();
        }

        // The hierarchy, derived from the registry's `parent` fields. A parent id
        // that is not a valid [`EpicId`] shape is retained in the view's `parent`
        // (for repair) but cannot enter the typed parent map.
        let mut children: HashMap<EpicId, Vec<EpicId>> = HashMap::new();
        let mut ordered: Vec<(EpicId, EpicConfiguration)> = Vec::new();
        let parents: HashMap<EpicId, EpicId> = resolved_parents(registry);
        for (raw, record) in registry {
            let Ok(id) = EpicId::new(raw) else {
                continue;
            };
            if let Some(parent) = parents.get(&id) {
                children.entry(parent.clone()).or_default().push(id.clone());
            }
            ordered.push((id, record.clone()));
        }

        let mut epics: IndexMap<EpicId, Epic> = IndexMap::new();
        for (id, record) in ordered {
            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();
            let kid_refs: Vec<EpicRef> = children
                .get(&id)
                .map(|ids| {
                    ids.iter()
                        .filter_map(|child| {
                            registry
                                .get(child.as_str())
                                .map(|record| EpicRef::new(child, &record.name))
                        })
                        .collect()
                })
                .unwrap_or_default();
            epics.insert(
                id.clone(),
                Epic::from_configuration(id, &record, members, kid_refs),
            );
        }

        missing.sort_by(reference_order);

        Self {
            epics,
            buckets,
            parents,
            children,
            missing,
            labels,
            statuses,
        }
    }

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

    /// Issue number -> its resolved epic ids, in registry declaration order (WP09
    /// item C).
    ///
    /// The **inverse** of [`Self::buckets`], and the one owner of it: the board's
    /// epic partition, `tix list --group epic`/`--sort epic`, and
    /// `tix status --group epic` all read this rather than re-reading the issues'
    /// `epics` lists, so a filter and a partition cannot disagree about who is a
    /// member. A stored reference the registry does not hold is **not** a member and
    /// therefore contributes no id (the repair path is the filter's raw-string
    /// match, deliberately — see [`crate::search::StructuredFilter::epic_matches`]).
    #[must_use]
    pub fn memberships_by_issue(&self) -> HashMap<u32, Vec<String>> {
        let order: HashMap<&str, usize> = self
            .epics
            .keys()
            .enumerate()
            .map(|(position, id)| (id.as_str(), position))
            .collect();
        let mut memberships: HashMap<u32, Vec<String>> = HashMap::new();
        for (id, keys) in &self.buckets {
            for key in keys {
                memberships
                    .entry(key.number())
                    .or_default()
                    .push(id.to_string());
            }
        }
        // Declaration order within each issue, so the rank and the bucket label are
        // deterministic whatever order the bucket map iterated in.
        for ids in memberships.values_mut() {
            ids.sort_by_key(|id| order.get(id.as_str()).copied().unwrap_or(usize::MAX));
        }
        memberships
    }

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

    /// Epics in declaration order.
    #[must_use]
    pub fn epics(&self) -> Vec<&Epic> {
        self.epics.values().collect()
    }

    /// One epic by id.
    #[must_use]
    pub fn epic(&self, id: &EpicId) -> Option<&Epic> {
        self.epics.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 **issue-held** references of this snapshot.
    ///
    /// Epic-held references are diagnosed per epic by [`Self::missing_for`],
    /// because they live on the record rather than in the issue set.
    #[must_use]
    pub fn missing(&self) -> &[EpicReferenceResolution] {
        &self.missing
    }

    /// Resolve an epic by id (first) or by name.
    pub fn resolve(&self, reference: &str) -> Result<&Epic, EpicError> {
        if let Ok(id) = EpicId::new(reference) {
            if let Some(epic) = self.epics.get(&id) {
                return Ok(epic);
            }
        }
        let normalized = reference.trim().to_lowercase();
        self.epics
            .values()
            .find(|epic| epic.name.to_lowercase() == normalized)
            .ok_or_else(|| EpicError::UnknownEpic {
                reference: reference.to_string(),
            })
    }

    /// The ordered membership of an epic.
    pub fn membership(&self, reference: &str) -> Result<EpicMembership, EpicError> {
        let epic = self.resolve(reference)?;
        Ok(EpicMembership {
            epic_id: epic.id.clone(),
            members: epic.members.clone(),
            member_count: epic.member_count,
        })
    }

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

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

    /// Consume the index into its declaration-ordered epic list.
    #[must_use]
    pub fn into_epics(self) -> Vec<Epic> {
        self.epics.into_values().collect()
    }
}

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

/// Issue number -> its resolved epic ids, in declaration order (WP09 item C).
///
/// [`EpicIndex::memberships_by_issue`] over one snapshot, for the callers — the
/// board's partition, `tix list --group epic`/`--sort epic`, and
/// `tix status --group epic` — that need the inverse membership without holding
/// the index.
#[must_use]
pub fn memberships_by_issue<N: EpicNode>(
    config: &Config,
    issues: &[N],
) -> HashMap<u32, Vec<String>> {
    EpicIndex::build(config, issues).memberships_by_issue()
}

/// The ordered membership of an epic, by id or name.
pub fn membership<N: EpicNode>(
    config: &Config,
    issues: &[N],
    reference: &str,
) -> Result<EpicMembership, EpicError> {
    EpicIndex::build(config, issues).membership(reference)
}

/// The epics in declaration order, with derived member and child 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_epics<N: EpicNode>(config: &Config, issues: &[N]) -> Vec<Epic> {
    EpicIndex::build(config, issues).into_epics()
}

/// Resolve an epic by id (first) or by name.
pub fn resolve<N: EpicNode>(
    config: &Config,
    issues: &[N],
    reference: &str,
) -> Result<Epic, EpicError> {
    EpicIndex::build(config, issues).resolve(reference).cloned()
}

// ---------------------------------------------------------------------------
// T008 — the dedicated iterative epic-chain walk and hierarchy navigation
// ---------------------------------------------------------------------------

/// The diagnosed state of an epic whose recorded parent no longer exists
/// (data-model §5, contract §3.4).
///
/// The epic's record is **not** modified when its parent is deleted: the
/// reference survives so it can be repaired. Any cascade would be an escalation
/// trigger.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct UnresolvedEpicParent {
    /// The epic holding the reference.
    pub epic: EpicId,
    /// The reference exactly as stored, retained for repair.
    pub recorded_parent: String,
    /// Human-readable text, reused verbatim by lint, the CLI, the TUI and MCP.
    pub reason: String,
}

/// The derived hierarchy view for one epic (data-model §5).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct EpicHierarchy {
    /// The epic the view is about.
    pub epic: EpicId,
    /// The recorded parent id, exactly as stored; retained even when unresolved.
    pub recorded_parent: Option<String>,
    /// The resolved parent, `None` when there is none or it does not resolve.
    pub parent: Option<EpicRef>,
    /// Direct children, in registry declaration order.
    pub children: Vec<EpicRef>,
    /// `children.len()`.
    pub child_count: usize,
    /// Ancestors, root-first.
    pub ancestors: Vec<EpicRef>,
    /// Distance from the root: the number of resolved ancestors walked.
    pub depth: usize,
    /// Present when the recorded parent no longer exists.
    pub unresolved: Option<UnresolvedEpicParent>,
}

/// The chain that closes a cycle if `epic` were pointed at `parent`, or `None`.
///
/// **Iterative**, from `parent` upward through the recorded parents. Because each
/// epic has at most one parent the hierarchy is a *functional* graph, so this is
/// the only walk needed — there is no branching to explore. Recursion would
/// overflow the stack on a 10,000-deep chain (NFR-001), so the loop carries its
/// own `visited` set and terminates on the first repeat or the root.
///
/// Only a repeat of **the proposed epic** closes a cycle. A walk that merely
/// *enters* a stored cycle the epic is not part of must not be reported as one:
/// attaching an unrelated epic under a cyclic subtree is a legitimate edit, and
/// the pre-existing loop is [`validate_epic_chains`]'s to report. Reporting it
/// here would refuse valid edits and emit a spurious `cycle` for every acyclic
/// epic whose chain happens to run into the loop.
fn epic_cycle_path(
    parents: &HashMap<EpicId, EpicId>,
    epic: &EpicId,
    parent: &EpicId,
) -> Option<Vec<EpicId>> {
    let mut path = vec![epic.clone()];
    let mut visited: HashSet<EpicId> = HashSet::new();
    visited.insert(epic.clone());
    let mut current = parent.clone();
    loop {
        if current == *epic {
            // The proposed edge closes the loop, and `path` is the cycle itself:
            // the epic, then the chain from the proposed parent back to it.
            return Some(path);
        }
        if !visited.insert(current.clone()) {
            // A pre-existing loop that does not contain `epic`, so the proposed
            // edge closes nothing. `validate_epic_chains` reports that loop.
            return None;
        }
        path.push(current.clone());
        {
            let next = parents.get(&current)?;
            current = next.clone()
        }
    }
}

/// The resolvable parent edges of a registry: epic id -> recorded parent id.
///
/// The one home of "which edges exist", shared by the derived index and by the
/// chain validation so the two cannot drift. A parent that is not a well-formed
/// id, or that the registry does not hold, is **not** an edge: it is the
/// unresolved state [`EpicHierarchy::unresolved`] surfaces and
/// [`EpicIndex::missing_for`] diagnoses.
fn resolved_parents(registry: &IndexMap<String, EpicConfiguration>) -> HashMap<EpicId, EpicId> {
    let known: HashSet<String> = registry.keys().cloned().collect();
    let mut parents: HashMap<EpicId, EpicId> = HashMap::new();
    for (raw, record) in registry {
        let Ok(id) = EpicId::new(raw) else {
            continue;
        };
        if let Some(parent) = record
            .parent
            .as_deref()
            .and_then(|p| EpicId::new(p).ok())
            .filter(|p| known.contains(p.as_str()))
        {
            parents.insert(id, parent);
        }
    }
    parents
}

/// Validate a proposed parent for `epic`, returning the resolved parent id.
///
/// The two rules of contract §3 apply, and both run **before any write**:
///
/// 1. `epic == parent` is always a self-parent;
/// 2. a proposed parent chain that would close a cycle is refused, with the
///    offending path in the diagnostic.
///
/// The walk is the dedicated **epic chain** walk, not the issue-parent walk from
/// source issue 170's Mission (C-002); it follows the same shape and the same
/// single-owner rule, and it is iterative so a 10,000-node chain cannot overflow
/// the stack (NFR-001).
pub fn validate_epic_parent(
    registry: &IndexMap<String, EpicConfiguration>,
    epic: &EpicId,
    parent_reference: &str,
) -> Result<EpicId, EpicError> {
    let parent = resolve_epic_id(registry, parent_reference)?;
    if &parent == epic {
        return Err(EpicError::SelfParent { epic: epic.clone() });
    }
    if let Some(path) = epic_cycle_path(&resolved_parents(registry), epic, &parent) {
        return Err(EpicError::Cycle {
            epic: epic.clone(),
            path,
        });
    }
    Ok(parent)
}

/// Every stored epic-chain defect in the registry, deterministically ordered.
///
/// **Never** returns an error — lint consumes the list directly — and performs one
/// pass over the registry. Reports each self-parent and each stored cycle once,
/// named by the epic whose parent edge closes it.
#[must_use]
pub fn validate_epic_chains(registry: &IndexMap<String, EpicConfiguration>) -> Vec<EpicError> {
    let parents = resolved_parents(registry);
    let mut out: Vec<EpicError> = Vec::new();
    let mut ids: Vec<EpicId> = registry
        .keys()
        .filter_map(|raw| EpicId::new(raw).ok())
        .collect();
    ids.sort();

    // A self-parent is one defect, not two: its chain is trivially cyclic, so it
    // is reported here and seeded into `seen` to keep the cycle sweep off it.
    let mut seen: HashSet<EpicId> = HashSet::new();
    for id in &ids {
        if parents.get(id) == Some(id) {
            seen.insert(id.clone());
            out.push(EpicError::SelfParent { epic: id.clone() });
        }
    }
    for id in &ids {
        if seen.contains(id) {
            continue;
        }
        let Some(parent) = parents.get(id) else {
            continue;
        };
        if let Some(path) = epic_cycle_path(&parents, id, parent) {
            for node in &path {
                seen.insert(node.clone());
            }
            out.push(EpicError::Cycle {
                epic: id.clone(),
                path,
            });
        }
    }
    out.sort_by(|a, b| {
        a.kind()
            .cmp(&b.kind())
            .then_with(|| chain_epic(a).cmp(&chain_epic(b)))
    });
    out
}

/// The epic a chain diagnostic is about, for deterministic ordering.
fn chain_epic(err: &EpicError) -> Option<&EpicId> {
    match err {
        EpicError::SelfParent { epic } | EpicError::Cycle { epic, .. } => Some(epic),
        _ => None,
    }
}

impl EpicIndex {
    /// The derived hierarchy of one epic (contract §1, data-model §5).
    ///
    /// Reads the pre-built parent and child maps, so navigation is a lookup
    /// rather than a scan. `ancestors` is root-first and `depth` is the number of
    /// resolved ancestors walked; a **recorded parent that no longer exists** is
    /// surfaced as [`EpicHierarchy::unresolved`] rather than dropped (C-005,
    /// contract §3.4).
    pub fn hierarchy(&self, reference: &str) -> Result<EpicHierarchy, EpicError> {
        let epic = self.resolve(reference)?;
        let id = epic.id.clone();

        let parent = self.parents.get(&id).and_then(|parent| self.ref_of(parent));
        let mut ancestors: Vec<EpicRef> = Vec::new();
        let mut visited: HashSet<EpicId> = HashSet::new();
        visited.insert(id.clone());
        let mut current = self.parents.get(&id).cloned();
        while let Some(node) = current {
            if !visited.insert(node.clone()) {
                // A stored cycle: stop rather than loop. `validate_epic_chains`
                // reports it; navigation stays total.
                break;
            }
            if let Some(reference) = self.ref_of(&node) {
                ancestors.push(reference);
            }
            current = self.parents.get(&node).cloned();
        }
        ancestors.reverse();

        let children: Vec<EpicRef> = self
            .children
            .get(&id)
            .map(|ids| ids.iter().filter_map(|child| self.ref_of(child)).collect())
            .unwrap_or_default();

        let unresolved = epic.parent.as_deref().and_then(|recorded| {
            let resolves = self
                .parents
                .get(&id)
                .is_some_and(|p| p.as_str() == recorded);
            if resolves {
                return None;
            }
            Some(UnresolvedEpicParent {
                epic: id.clone(),
                recorded_parent: recorded.to_string(),
                reason: unresolved_parent_reason(&id, recorded),
            })
        });

        Ok(EpicHierarchy {
            epic: id,
            recorded_parent: epic.parent.clone(),
            parent,
            child_count: children.len(),
            children,
            depth: ancestors.len(),
            ancestors,
            unresolved,
        })
    }

    /// A derived reference to an epic the index knows, by id.
    fn ref_of(&self, id: &EpicId) -> Option<EpicRef> {
        self.epics.get(id).map(|epic| EpicRef::new(id, &epic.name))
    }
}

/// The ordered hierarchy of an epic, by id or name.
pub fn hierarchy<N: EpicNode>(
    config: &Config,
    issues: &[N],
    reference: &str,
) -> Result<EpicHierarchy, EpicError> {
    EpicIndex::build(config, issues).hierarchy(reference)
}

// ---------------------------------------------------------------------------
// T009 — reference diagnosis across all five kinds
// ---------------------------------------------------------------------------

/// Which kind of reference failed (contract §1, data-model §7).
///
/// The variants are the five kinds `resolve_references` diagnoses. `Epic` is a
/// recorded **epic id** that the registry does not hold — from an epic's `parent`
/// or from an issue's `epics` entry. `Issue` is an issue's `epics` entry that is
/// not a well-formed epic id at all (a blank, padded, or name-shaped entry): the
/// entry names no epic, so the `Epic` kind — which names a missing id — cannot
/// express it. `Project`, `Milestone` and `Cycle` are an epic record's own
/// reference fields.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum EpicReferenceKind {
    /// A recorded epic id the registry does not hold.
    Epic,
    /// An epic's project id the project registry does not hold.
    Project,
    /// An issue-side `epics` entry that is not a well-formed epic id.
    Issue,
    /// An epic's milestone name the milestone registry does not hold.
    Milestone,
    /// An epic's cycle name the cycle registry does not hold.
    Cycle,
}

impl EpicReferenceKind {
    /// The canonical snake_case spelling a surface prints.
    #[must_use]
    pub fn as_str(self) -> &'static str {
        match self {
            EpicReferenceKind::Epic => "epic",
            EpicReferenceKind::Project => "project",
            EpicReferenceKind::Issue => "issue",
            EpicReferenceKind::Milestone => "milestone",
            EpicReferenceKind::Cycle => "cycle",
        }
    }

    /// The `tix lint` diagnostic kind for a missing reference of this kind
    /// (contract `cli-surface.md` §4).
    #[must_use]
    pub fn diagnostic_kind(self) -> &'static str {
        match self {
            EpicReferenceKind::Epic => "missing_epic_reference",
            EpicReferenceKind::Project => "missing_project_reference",
            EpicReferenceKind::Issue => "missing_issue_reference",
            EpicReferenceKind::Milestone => "missing_milestone_reference",
            EpicReferenceKind::Cycle => "missing_cycle_reference",
        }
    }
}

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

/// The entity that holds a failing reference (data-model §7's holder).
///
/// A reference lives either on an epic record or in an issue's `epics` list, and
/// a diagnostic that did not say which would make the user edit the wrong file.
/// One enum rather than a second diagnostic type, because a second type for one
/// direction is the second resolver C-002 forbids.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum ReferenceHolder {
    /// An epic-held reference, by epic id.
    Epic(EpicId),
    /// An issue-held reference, by issue number.
    Issue(IssueKey),
}

impl fmt::Display for ReferenceHolder {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            ReferenceHolder::Epic(id) => write!(f, "epic `{id}`"),
            ReferenceHolder::Issue(key) => write!(f, "issue {key}"),
        }
    }
}

/// The diagnosed outcome for a reference that does not resolve (data-model §7).
///
/// The diagnostic names the **failing reference**, never merely that something is
/// missing, so `tix lint` can point at the field to repair.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct EpicReferenceResolution {
    /// The entity holding the reference field.
    pub holder: ReferenceHolder,
    /// Which kind of reference failed.
    pub target_kind: EpicReferenceKind,
    /// The reference exactly as recorded, retained for repair.
    pub target: String,
    /// Human-readable text, reused verbatim by lint, the CLI, the TUI and MCP.
    pub reason: String,
}

/// The single wording for a recorded epic id that does not resolve.
#[must_use]
pub fn missing_epic_reason(holder: &ReferenceHolder, target: &str) -> String {
    format!(
        "{holder} records epic reference `{target}`, which is not in the registry \
         (the reference is kept so it can be repaired)"
    )
}

/// The single wording for an issue-side entry that names no epic at all.
#[must_use]
pub fn malformed_epic_reason(issue: u32, raw: &str) -> String {
    format!(
        "issue #{issue} records epic reference `{raw}`, which is not a well-formed epic id \
         (ids are recorded, never names; the entry is kept so it can be repaired)"
    )
}

/// The single wording for an epic's project reference that does not resolve.
#[must_use]
pub fn missing_project_reason(epic: &EpicId, target: &str) -> String {
    format!(
        "epic `{epic}` references project `{target}`, which is not in the project registry \
         (the reference is kept so it can be repaired)"
    )
}

/// The single wording for an epic's milestone reference that does not resolve.
#[must_use]
pub fn missing_milestone_reason(epic: &EpicId, target: &str) -> String {
    format!(
        "epic `{epic}` references milestone `{target}`, which is not in the milestone registry \
         (the reference is kept so it can be repaired)"
    )
}

/// The single wording for an epic's cycle reference that does not resolve.
#[must_use]
pub fn missing_cycle_reason(epic: &EpicId, target: &str) -> String {
    format!(
        "epic `{epic}` references cycle `{target}`, which is not in the cycle registry \
         (the reference is kept so it can be repaired)"
    )
}

/// The ordering every diagnostic list uses: holder, then kind, then target.
fn reference_order(a: &EpicReferenceResolution, b: &EpicReferenceResolution) -> std::cmp::Ordering {
    a.holder
        .cmp(&b.holder)
        .then_with(|| a.target_kind.cmp(&b.target_kind))
        .then_with(|| a.target.cmp(&b.target))
}

/// The resolvable targets of one snapshot, consumed from their owners.
///
/// This module performs no file I/O: the sets are plain in-memory collections, so
/// a caller with a fixture — a unit test, or a surface that already resolved them
/// — builds one directly. [`ReferenceTargets::from_planner`] is the optional
/// production adapter: it consumes the **existing** lookups, including
/// `Planner::milestone_names()`, which is filesystem-backed, plus
/// `Planner::cycle_names()` and the implicit `Default` cycle `Planner::cycle()`
/// answers for, and the project registry for project ids. No second milestone or
/// cycle store exists (research R2).
///
/// Each set is a `HashSet`, so a lookup is a hash probe rather than a scan: with
/// `E` epics and `p` references each, `resolve_references` stays one pass over the
/// issues plus one pass over the registry (contract §7, NFR-001).
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct ReferenceTargets {
    /// Project ids the project registry holds, as the registry keys them.
    pub projects: HashSet<String>,
    /// Milestone names the milestone registry holds.
    pub milestones: HashSet<String>,
    /// Cycle names the cycle registry answers for.
    pub cycles: HashSet<String>,
}

impl ReferenceTargets {
    /// Consume the existing planning lookups for one [`Planner`].
    ///
    /// This is the production adapter: milestones come from
    /// [`Planner::milestone_names`] and cycles from [`Planner::cycle_names`] plus
    /// the implicit `Default` cycle [`Planner::cycle`] answers for even when no
    /// file holds it. Both sets are built once here, so the diagnosis below is a
    /// probe per reference rather than a scan per reference.
    pub fn from_planner(planner: &Planner) -> Result<Self> {
        let mut cycles: HashSet<String> = planner.cycle_names().into_iter().collect();
        if planner.cycle(DEFAULT_CYCLE_NAME).is_some() {
            cycles.insert(DEFAULT_CYCLE_NAME.to_string());
        }
        Ok(Self {
            projects: planner.config().projects.keys().cloned().collect(),
            milestones: planner.milestone_names()?.into_iter().collect(),
            cycles,
        })
    }

    /// Whether the project registry holds `id`.
    #[must_use]
    pub fn project_known(&self, id: &str) -> bool {
        self.projects.contains(id)
    }

    /// Whether the milestone registry holds `name`.
    #[must_use]
    pub fn milestone_known(&self, name: &str) -> bool {
        self.milestones.contains(name)
    }

    /// Whether the cycle registry answers for `name`.
    #[must_use]
    pub fn cycle_known(&self, name: &str) -> bool {
        self.cycles.contains(name)
    }
}

/// Every reference in the snapshot that does not resolve (contract §1, §5).
///
/// **Never** returns an error — lint consumes the list directly — and performs one
/// pass over the issue set (the index build) plus one pass over the registry
/// rather than one lookup per reference (contract §7). Each failing reference is
/// reported once, naming the holder, the kind, and the recorded target, ordered by
/// `(holder, kind, target)` so lint output is stable (C-005, contract §8).
///
/// `targets` carries what the owners resolved: the project registry, and the
/// milestone and cycle names from the `Planner` lookups (contract §2). The service
/// stores none of them.
#[must_use]
pub fn resolve_references<N: EpicNode>(
    registry: &IndexMap<String, EpicConfiguration>,
    issues: &[N],
    targets: &ReferenceTargets,
) -> Vec<EpicReferenceResolution> {
    let index = EpicIndex::build_from_registry(registry, issues);
    let mut out: Vec<EpicReferenceResolution> = index.missing().to_vec();
    for epic in index.epics() {
        out.extend(index.missing_for(&epic.id, targets));
    }
    out.sort_by(reference_order);
    out
}

impl EpicIndex {
    /// This epic's **unresolvable** references, deterministically ordered.
    ///
    /// The epic-held half of [`resolve_references`]: the recorded parent (when it
    /// no longer resolves), the project ids absent from the project registry, and
    /// the milestone and cycle names absent from the planner's lookups. Turns the
    /// epic's own fields, not the issue set, so it is a constant-time read.
    #[must_use]
    pub fn missing_for(
        &self,
        id: &EpicId,
        targets: &ReferenceTargets,
    ) -> Vec<EpicReferenceResolution> {
        let Some(epic) = self.epics.get(id) else {
            return Vec::new();
        };
        let holder = ReferenceHolder::Epic(id.clone());
        let mut out: Vec<EpicReferenceResolution> = Vec::new();

        if let Some(recorded) = epic.parent.as_deref() {
            let resolves = self.parents.get(id).is_some_and(|p| p.as_str() == recorded);
            if !resolves {
                out.push(EpicReferenceResolution {
                    holder: holder.clone(),
                    target_kind: EpicReferenceKind::Epic,
                    target: recorded.to_string(),
                    reason: missing_epic_reason(&holder, recorded),
                });
            }
        }
        for project in &epic.projects {
            if !targets.project_known(project) {
                out.push(EpicReferenceResolution {
                    holder: holder.clone(),
                    target_kind: EpicReferenceKind::Project,
                    target: project.clone(),
                    reason: missing_project_reason(id, project),
                });
            }
        }
        if let Some(milestone) = epic.milestone.as_deref() {
            if !targets.milestone_known(milestone) {
                out.push(EpicReferenceResolution {
                    holder: holder.clone(),
                    target_kind: EpicReferenceKind::Milestone,
                    target: milestone.to_string(),
                    reason: missing_milestone_reason(id, milestone),
                });
            }
        }
        if let Some(cycle) = epic.cycle.as_deref() {
            if !targets.cycle_known(cycle) {
                out.push(EpicReferenceResolution {
                    holder: holder.clone(),
                    target_kind: EpicReferenceKind::Cycle,
                    target: cycle.to_string(),
                    reason: missing_cycle_reason(id, cycle),
                });
            }
        }
        out.sort_by(reference_order);
        out
    }
}

// ---------------------------------------------------------------------------
// T010/T011 — the typed rollup: the one progress computation (FR-003, C-008)
// ---------------------------------------------------------------------------

/// One member holding an open blocker, with the owner's reason text verbatim.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct BlockedMember {
    /// The blocked member's number.
    pub issue: IssueKey,
    /// `#<number> <title>`, from the shared renderer in `hierarchy`.
    pub display: String,
    /// The reason text [`RelationshipGraph::blocked_state`] produced.
    pub reason: String,
}

/// An epic's completion progress (data-model §6, 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 EpicProgress {
    /// 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,
}

/// The weight-aware figure of an epic (data-model §6).
///
/// **A member with no weight is excluded rather than counted as zero** — the
/// shape WP01 settled and `data-model.md` §6 records. The weighted population is
/// the epic's **child epics**, each contributing its own `weight`; a child counts
/// as done when it has at least one member and every one of them is complete. A
/// child with no weight, like a member issue (issues carry no weight — research
/// R3), contributes nothing and is counted in `unweighted_children` so the
/// exclusion is visible rather than silent. `own_weight` reports the epic's own
/// weight, which is what a **parent** epic's figure consumes; this epic's own
/// figure never includes it, so no number is counted twice.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct WeightedProgress {
    /// This epic's own weight, `None` when unset.
    pub own_weight: Option<i64>,
    /// Children that carry a weight and therefore contribute.
    pub weighted_children: usize,
    /// Children excluded because they carry no weight.
    pub unweighted_children: usize,
    /// `Σ` weights of the weighted children that are complete.
    pub done_weight: i64,
    /// `Σ` weights of the weighted children — the weighted population.
    pub total_weight: i64,
    /// `done_weight` as a floored integer percentage of `total_weight`;
    /// `None` when the weighted population is empty, so "no weight to report"
    /// stays distinguishable from "0% done".
    pub percent: Option<u32>,
}

/// The typed value the `rollup` operation returns (contract §1, data-model §6).
///
/// One value, carrying the epic's identity, its completion, its child count, its
/// weight-aware figure, its blocked members, and its unresolvable references, so a
/// CLI, TUI or MCP surface renders it rather than re-deriving any figure (C-008).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct EpicRollup {
    /// The epic the figures describe.
    pub epic_id: EpicId,
    /// The epic's display label, so a surface needs no second lookup.
    pub name: String,
    /// Completion figures, computed once here.
    pub progress: EpicProgress,
    /// Child epics, from the derived hierarchy. Never a stored count.
    pub child_count: usize,
    /// The weight-aware figure.
    pub weighted_progress: WeightedProgress,
    /// Members with an open blocker that are not done.
    pub blocked: usize,
    /// Those members, carrying the blocker owner's reason text verbatim.
    pub blocked_members: Vec<BlockedMember>,
    /// This epic's references that no longer resolve (C-005).
    pub missing_references: Vec<EpicReferenceResolution>,
}

impl EpicIndex {
    /// Progress, child count, weight, and blocked work for one epic
    /// (contract §1, FR-003, C-008).
    ///
    /// This is the **only** place an epic's figures are computed: every surface
    /// renders this value rather than formatting its own figure.
    ///
    /// - Completion reads the board's **configured** completion column through
    ///   the workflow service ([`crate::workflow::active_resolution`]), never a
    ///   literal `"done"`.
    /// - Membership is the pre-built bucket, so the figures are a bucket lookup
    ///   rather than a scan (contract §7).
    /// - `blocked` is **consumed** from source issue 169's derived read: the
    ///   graph's [`RelationshipGraph::blocked_state`] decides, and its `reason`
    ///   text is carried through verbatim. Nothing here re-derives blocked work
    ///   (research R4), and a **done** member is never counted as blocked.
    /// - `missing_references` is this epic's own unresolvable references, so an
    ///   unresolved reference is visible wherever progress is shown (C-005).
    pub fn rollup(
        &self,
        config: &Config,
        reference: &str,
        targets: &ReferenceTargets,
        graph: &RelationshipGraph<'_>,
    ) -> Result<EpicRollup, EpicError> {
        let epic = self.resolve(reference)?;
        let id = epic.id.clone();
        let (_, resolution) = crate::workflow::active_resolution(config);

        let members = self.bucket(&id).unwrap_or(&[]);
        let done_board: HashSet<IssueKey> = members
            .iter()
            .filter(|key| {
                self.status_of(**key)
                    .and_then(|status| resolution.resolve(status))
                    .is_some_and(crate::workflow::WorkflowCategory::is_complete)
            })
            .copied()
            .collect();
        let done = done_board.len();
        let total = members.len();

        let blocked_members: Vec<BlockedMember> = self
            .blocked_members(&id, graph)
            .into_iter()
            .filter(|member| !done_board.contains(&member.issue))
            .collect();

        Ok(EpicRollup {
            name: epic.name.clone(),
            progress: EpicProgress {
                done,
                total,
                progress: Progress { done, total },
            },
            child_count: epic.child_count,
            weighted_progress: self.weighted_progress(config, &id, &resolution),
            blocked: blocked_members.len(),
            blocked_members,
            missing_references: self.missing_for(&id, targets),
            epic_id: id,
        })
    }

    /// The epic's members with an open blocker, consuming the owner's derived read.
    ///
    /// The predicate is [`RelationshipGraph::blocked_state`]'s and so is the
    /// `reason` text: this function only shapes the owner's answer, it never
    /// re-derives it (research R4). Ordered by issue number.
    #[must_use]
    pub fn blocked_members(
        &self,
        id: &EpicId,
        graph: &RelationshipGraph<'_>,
    ) -> Vec<BlockedMember> {
        let Some(members) = self.buckets.get(id) else {
            return Vec::new();
        };
        let mut out: Vec<BlockedMember> = members
            .iter()
            .filter_map(|key| {
                let state = graph.blocked_state(key.number());
                if !state.is_blocked {
                    return None;
                }
                Some(BlockedMember {
                    issue: *key,
                    display: self
                        .label(*key)
                        .map(str::to_string)
                        .unwrap_or_else(|| key.to_string()),
                    reason: state.reason,
                })
            })
            .collect();
        out.sort_by_key(|member| member.issue);
        out
    }

    /// The weight-aware figure for one epic (data-model §6).
    ///
    /// `resolution` is the active board's category seam, resolved once by the
    /// caller, so a child's completion is judged by the same rule as the epic's
    /// own completion rather than by a second lookup per child.
    fn weighted_progress(
        &self,
        config: &Config,
        id: &EpicId,
        resolution: &crate::workflow::CategoryResolution,
    ) -> WeightedProgress {
        let own_weight = config.epics.get(id.as_str()).and_then(|r| r.weight);
        let Some(children) = self.children.get(id) else {
            return WeightedProgress {
                own_weight,
                weighted_children: 0,
                unweighted_children: 0,
                done_weight: 0,
                total_weight: 0,
                percent: None,
            };
        };
        let mut weighted = 0usize;
        let mut unweighted = 0usize;
        let mut done_weight = 0i64;
        let mut total_weight = 0i64;
        for child in children {
            let Some(weight) = config.epics.get(child.as_str()).and_then(|r| r.weight) else {
                unweighted += 1;
                continue;
            };
            weighted += 1;
            total_weight += weight;
            if self.child_is_complete(child, resolution) {
                done_weight += weight;
            }
        }
        let percent = if total_weight > 0 {
            let done = u32::try_from(done_weight.max(0)).unwrap_or(u32::MAX);
            let total = u32::try_from(total_weight.max(0)).unwrap_or(u32::MAX);
            Some(done.saturating_mul(100) / total.max(1))
        } else {
            None
        };
        WeightedProgress {
            own_weight,
            weighted_children: weighted,
            unweighted_children: unweighted,
            done_weight,
            total_weight,
            percent,
        }
    }

    /// Whether a child epic has members and all of them are complete.
    fn child_is_complete(
        &self,
        child: &EpicId,
        resolution: &crate::workflow::CategoryResolution,
    ) -> bool {
        let Some(members) = self.buckets.get(child) else {
            return false;
        };
        if members.is_empty() {
            return false;
        }
        members.iter().all(|key| {
            self.status_of(*key)
                .and_then(|status| resolution.resolve(status))
                .is_some_and(crate::workflow::WorkflowCategory::is_complete)
        })
    }
}

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

/// The two reference 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 project
/// and hierarchy missions' kinds are mapped.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum EpicEventKind {
    /// An issue gained an epic reference.
    EpicReferenced,
    /// An issue lost an epic reference.
    EpicDereferenced,
}

impl EpicEventKind {
    /// The canonical snake_case spelling the History section will carry.
    #[must_use]
    pub fn as_str(self) -> &'static str {
        match self {
            EpicEventKind::EpicReferenced => "epic_referenced",
            EpicEventKind::EpicDereferenced => "epic_dereferenced",
        }
    }
}

/// One reference mutation, ready for storage to append to `## History`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct EpicEvent {
    /// Which of the two mutations this is.
    pub kind: EpicEventKind,
    /// The epic id exactly as recorded. A `String`, not an [`EpicId`], because a
    /// dereference may remove a stored id that is not a valid shape.
    pub epic_id: String,
    /// The rendered detail line, from [`reference_detail`].
    pub detail: String,
}

/// The outcome of a reference 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 (contract §4).
/// It never returns a whole `Issue`, which is what keeps this module model-free.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct EpicChange {
    /// The issue whose references changed.
    pub issue: IssueKey,
    /// The reference list after the change, first-seen order preserved.
    pub epic_ids: Vec<String>,
    /// The event to append, or `None` when the mutation was a no-op.
    ///
    /// `None` for referencing an already-present epic or dereferencing an absent
    /// one: neither is a change, and recording one would put an entry in the audit
    /// trail for nothing (contract §5).
    pub event: Option<EpicEvent>,
}

/// The per-issue outcome of a bulk reference (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 (contract
/// §5).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct BulkEpicOutcome {
    /// The selector this entry answers.
    pub selector: u32,
    /// The change or the refusal for that selector.
    pub outcome: Result<EpicChange, EpicError>,
}

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

/// Produce the reference change for a **resolved** epic id.
fn reference_resolved<N: EpicNode>(
    issues: &[N],
    selector: u32,
    id: &EpicId,
) -> Result<EpicChange, EpicError> {
    let issue = find_issue(issues, selector)?;
    let current = issue.epic_ids();
    let key = IssueKey::new(selector);
    if current.iter().any(|stored| stored == id.as_str()) {
        return Ok(EpicChange {
            issue: key,
            epic_ids: current.to_vec(),
            event: None,
        });
    }
    let mut next = current.to_vec();
    next.push(id.to_string());
    Ok(EpicChange {
        issue: key,
        epic_ids: next,
        event: Some(EpicEvent {
            kind: EpicEventKind::EpicReferenced,
            epic_id: id.to_string(),
            detail: reference_detail(id.as_str(), true),
        }),
    })
}

/// Reference an epic from an issue, producing the change and its History event.
///
/// Idempotent: an already-present reference changes nothing and yields **no**
/// event (contract §5). Refuses an unknown epic or an unknown issue; a refusal
/// produces no change and no event.
pub fn reference_epic<N: EpicNode>(
    config: &Config,
    issues: &[N],
    issue_selector: u32,
    epic_reference: &str,
) -> Result<EpicChange, EpicError> {
    let id = resolve_epic_id(&config.epics, epic_reference)?;
    reference_resolved(issues, issue_selector, &id)
}

/// Remove an issue's reference to an epic.
///
/// Drops only the reference: it never deletes or modifies the issue (C-006).
/// Dereferencing an absent reference is an idempotent no-op with no event. The
/// epic is **not** required to exist — removing a stale reference is the repair
/// path C-005 promises — so the only refusal is an unknown issue.
///
/// `epic_id` is compared against the stored list **verbatim**: unlike
/// [`reference_epic`], an epic *name* is not resolved here. That is deliberate —
/// the stored entries are ids, and a caller must resolve a name to an id first
/// (via [`resolve_epic_id`]). A name therefore matches nothing and is an inert
/// no-op, which keeps the repair path working for an id that is no longer a valid
/// [`EpicId`] shape or no longer in the registry.
pub fn dereference_epic<N: EpicNode>(
    issues: &[N],
    issue_selector: u32,
    epic_id: &str,
) -> Result<EpicChange, EpicError> {
    let issue = find_issue(issues, issue_selector)?;
    let current = issue.epic_ids();
    let key = IssueKey::new(issue_selector);
    if !current.iter().any(|stored| stored == epic_id) {
        return Ok(EpicChange {
            issue: key,
            epic_ids: current.to_vec(),
            event: None,
        });
    }
    let next: Vec<String> = current
        .iter()
        .filter(|stored| stored.as_str() != epic_id)
        .cloned()
        .collect();
    Ok(EpicChange {
        issue: key,
        epic_ids: next,
        event: Some(EpicEvent {
            kind: EpicEventKind::EpicDereferenced,
            epic_id: epic_id.to_string(),
            detail: reference_detail(epic_id, false),
        }),
    })
}

/// Reference each selector independently, reporting every outcome.
///
/// One rejection must not abort the rest (contract §5): the returned vector has
/// one entry per selector, in selector order, and an unknown epic refuses each
/// entry rather than the whole call.
#[must_use]
pub fn bulk_reference<N: EpicNode>(
    config: &Config,
    issues: &[N],
    epic_reference: &str,
    issue_selectors: &[u32],
) -> Vec<BulkEpicOutcome> {
    let resolved = resolve_epic_id(&config.epics, epic_reference);
    issue_selectors
        .iter()
        .map(|&selector| {
            let outcome = match &resolved {
                Ok(id) => reference_resolved(issues, selector, id),
                Err(err) => Err(err.clone()),
            };
            BulkEpicOutcome { selector, outcome }
        })
        .collect()
}

/// The ordered rollup of an epic, by id or name (contract §1).
pub fn rollup<N: EpicNode>(
    config: &Config,
    issues: &[N],
    reference: &str,
    targets: &ReferenceTargets,
    graph: &RelationshipGraph<'_>,
) -> Result<EpicRollup, EpicError> {
    EpicIndex::build(config, issues).rollup(config, reference, targets, graph)
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::relationships::{IssueView, RelationKind, Relationship};
    use std::path::PathBuf;

    /// An in-memory stand-in for the shape WP03 exposes on `Issue`.
    ///
    /// The inline suite is deliberately filesystem-free (T012 step 4): every test
    /// below builds a [`Config`] and a `Vec<Node>` by hand, with no `Store` and no
    /// `tempdir`. `labels` is carried so a `task`-labelled fixture is a real
    /// fixture, but it is **not** part of [`EpicNode`] — see
    /// `t007_a_task_labelled_issue_is_a_member_like_any_other`.
    #[derive(Debug, Clone, PartialEq, Eq)]
    struct Node {
        number: u32,
        title: String,
        status: String,
        epics: Vec<String>,
        labels: Vec<String>,
    }

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

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

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

        fn labelled(mut self, label: &str) -> Self {
            self.labels.push(label.to_string());
            self
        }
    }

    impl EpicNode for Node {
        fn number(&self) -> u32 {
            self.number
        }
        fn title(&self) -> &str {
            &self.title
        }
        fn status(&self) -> &str {
            &self.status
        }
        fn epic_ids(&self) -> &[String] {
            &self.epics
        }
    }

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

    /// A registry record with a parent and/or a weight.
    fn record(name: &str, parent: Option<&str>, weight: Option<i64>) -> EpicConfiguration {
        EpicConfiguration {
            name: name.to_string(),
            parent: parent.map(str::to_string),
            weight,
            ..EpicConfiguration::default()
        }
    }

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

    /// The bare registry a contract operation takes (`registry + issue set`).
    fn epics(config: &Config) -> &IndexMap<String, EpicConfiguration> {
        &config.epics
    }

    /// Targets resolved from an in-memory fixture: the accepted names of each kind.
    fn targets(projects: &[&str], milestones: &[&str], cycles: &[&str]) -> ReferenceTargets {
        ReferenceTargets {
            projects: projects.iter().map(|id| (*id).to_string()).collect(),
            milestones: milestones.iter().map(|m| (*m).to_string()).collect(),
            cycles: cycles.iter().map(|c| (*c).to_string()).collect(),
        }
    }

    /// An empty issue set, typed so a call can infer `EpicNode`.
    fn no_issues() -> Vec<Node> {
        Vec::new()
    }

    /// A snapshot owning everything a [`RelationshipGraph`] borrows.
    ///
    /// A graph borrows its issue views, which borrow the titles and the typed
    /// edges, so the fixture owns all three and the caller keeps `views` beside
    /// the graph. Edges are the source issue 169's shape, so `blocked` is the
    /// owner's derived read and never a set this module invented (research R4).
    struct Blocking {
        issues: Vec<Node>,
        edges: Vec<Vec<Relationship>>,
    }

    impl Blocking {
        /// A snapshot with `blocks` edges `(blocker, blocked)`.
        fn new(issues: Vec<Node>, blocks: &[(u32, u32)]) -> Self {
            let edges = issues
                .iter()
                .map(|issue| {
                    blocks
                        .iter()
                        .filter(|(blocker, _)| *blocker == issue.number)
                        .map(|(blocker, blocked)| {
                            Relationship::new(*blocker, *blocked, RelationKind::Blocks, "blocked")
                        })
                        .collect()
                })
                .collect();
            Self { issues, edges }
        }

        /// Issue views borrowing this fixture; keep them alive beside the graph.
        fn views(&self) -> Vec<IssueView<'_>> {
            self.issues
                .iter()
                .zip(self.edges.iter())
                .map(|(issue, edges)| {
                    IssueView::new(issue.number, &issue.title, &issue.status, edges.as_slice())
                })
                .collect()
        }
    }

    /// A board whose completion column is a **custom** name, 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 t006_create_epic_allocates_a_stable_id_and_the_metadata() {
        let mut config = Config::default();
        let new = NewEpic {
            name: "Harden the sync path".to_string(),
            description: Some("Reduce operational risk.".to_string()),
            status: Some("active".to_string()),
            owner: Some("Alice <alice@example.com>".to_string()),
            start_date: Some("2026-09-01".to_string()),
            due_date: Some("2026-12-31".to_string()),
            weight: Some(5),
            ..NewEpic::default()
        };
        let epic = create_epic(&mut config, &new).unwrap();
        assert!(epic.id.as_str().starts_with("e-"), "{}", epic.id);
        assert_eq!(epic.name, "Harden the sync path");
        assert_eq!(epic.weight, Some(5));
        assert_eq!(epic.member_count, 0);
        assert_eq!(epic.members, [] as [crate::projects::MemberRef; 0]);
        assert_eq!(epic.children, [] as [crate::epics::EpicRef; 0]);
        // The record is the registry's, keyed by the stable id.
        assert!(config.epics.contains_key(epic.id.as_str()));
        // A second create never hands out the same id.
        let second = create_epic(&mut config, &new).unwrap_err();
        assert_eq!(second.kind(), EpicDiagnosticKind::DuplicateName);
        let other = NewEpic {
            name: "Other".to_string(),
            ..NewEpic::default()
        };
        assert_ne!(create_epic(&mut config, &other).unwrap().id, epic.id);
    }

    #[test]
    fn t006_create_epic_refuses_a_duplicate_name_and_bad_metadata() {
        let mut config = registry(&[("e-aaaa", "Platform")]);
        let cases = [
            (
                NewEpic {
                    name: "platform".to_string(),
                    ..NewEpic::default()
                },
                "duplicate_name",
            ),
            (
                NewEpic {
                    name: " padded".to_string(),
                    ..NewEpic::default()
                },
                "duplicate_name",
            ),
            (
                NewEpic {
                    name: String::new(),
                    ..NewEpic::default()
                },
                "duplicate_name",
            ),
            (
                NewEpic {
                    name: "Dates".to_string(),
                    start_date: Some("2026-12-31".to_string()),
                    due_date: Some("2026-01-01".to_string()),
                    ..NewEpic::default()
                },
                "invalid_dates",
            ),
            (
                NewEpic {
                    name: "Heavy".to_string(),
                    weight: Some(0),
                    ..NewEpic::default()
                },
                "invalid_weight",
            ),
        ];
        for (new, kind) in cases {
            let err = create_epic(&mut config, &new).unwrap_err();
            assert_eq!(err.kind().as_str(), kind, "{err}");
        }
        // Nothing was inserted by any refusal: only the seeded epic remains.
        assert_eq!(config.epics.len(), 1);
    }

    #[test]
    fn t006_a_rename_changes_the_label_only() {
        let mut config = registry(&[("e-aaaa", "Platform"), ("e-bbbb", "Child")]);
        config
            .epics
            .insert("e-bbbb".to_string(), record("Child", Some("e-aaaa"), None));
        let issues = vec![Node::new(1, "Member").with(&["e-aaaa"])];
        let before = config.epics["e-aaaa"].clone();

        let edit = EpicEdit {
            name: Patch::Set("Platform hardening".to_string()),
            ..EpicEdit::default()
        };
        let edited = edit_epic(&mut config, "e-aaaa", &edit).unwrap();
        assert_eq!(edited.name, "Platform hardening");
        assert_eq!(edited.id.as_str(), "e-aaaa", "a rename never re-keys");

        // Every reference and derived figure is intact under the new label.
        assert_eq!(config.epics["e-aaaa"].name, "Platform hardening");
        assert_eq!(config.epics["e-aaaa"].description, before.description);
        let index = EpicIndex::build(&config, &issues);
        assert_eq!(index.membership("e-aaaa").unwrap().member_count, 1);
        assert_eq!(
            index.hierarchy("e-bbbb").unwrap().parent.unwrap().name,
            "Platform hardening"
        );
        assert_eq!(
            index.resolve("Platform hardening").unwrap().id.as_str(),
            "e-aaaa"
        );
    }

    #[test]
    fn t006_delete_reports_affected_issues_and_child_epics_and_keeps_them() {
        let mut config = registry(&[("e-aaaa", "Platform")]);
        config
            .epics
            .insert("e-bbbb".to_string(), record("Child", Some("e-aaaa"), None));
        let issues = vec![
            Node::new(1, "Member one").with(&["e-aaaa"]),
            Node::new(2, "Member two").with(&["e-aaaa", "e-bbbb"]),
        ];

        let deletion = delete_epic(&mut config, "e-aaaa", &issues).unwrap();
        assert_eq!(deletion.id.as_str(), "e-aaaa");
        assert_eq!(deletion.name, "Platform");
        assert_eq!(
            deletion
                .affected
                .iter()
                .map(|m| m.issue.number())
                .collect::<Vec<_>>(),
            vec![1, 2]
        );
        assert_eq!(deletion.affected[0].display, "#1 Member one");
        assert_eq!(
            deletion
                .child_epics
                .iter()
                .map(|e| e.id.as_str())
                .collect::<Vec<_>>(),
            vec!["e-bbbb"]
        );
        // The registry entry went; nothing else did (C-006).
        assert!(!config.epics.contains_key("e-aaaa"));
        assert!(config.epics.contains_key("e-bbbb"));
        assert_eq!(config.epics["e-bbbb"].parent.as_deref(), Some("e-aaaa"));
        assert_eq!(issues.len(), 2, "no issue is deleted");
        // The retained references are diagnosable, not silently rebound.
        let index = EpicIndex::build(&config, &issues);
        assert!(
            index
                .missing()
                .iter()
                .all(|m| m.target_kind == EpicReferenceKind::Epic)
        );
        assert_eq!(index.missing().len(), 2);
        assert_eq!(
            index
                .hierarchy("e-bbbb")
                .unwrap()
                .unresolved
                .unwrap()
                .recorded_parent,
            "e-aaaa"
        );
        // The id is never handed out again.
        let fresh = create_epic(
            &mut config,
            &NewEpic {
                name: "Fresh".to_string(),
                ..NewEpic::default()
            },
        )
        .unwrap();
        assert_ne!(fresh.id.as_str(), "e-aaaa");
    }

    #[test]
    fn t006_resolution_by_id_and_by_name_agree() {
        let config = registry(&[("e-aaaa", "Platform"), ("e-bbbb", "Sync")]);
        let index = EpicIndex::build(&config, &no_issues());
        assert_eq!(index.resolve("e-aaaa").unwrap().name, "Platform");
        assert_eq!(index.resolve("Platform").unwrap().id.as_str(), "e-aaaa");
        assert_eq!(
            index.resolve("Platform").unwrap(),
            index.resolve("e-aaaa").unwrap()
        );
        // The name convenience is case-folded and trimmed, like the project one.
        assert_eq!(index.resolve("  sync ").unwrap().id.as_str(), "e-bbbb");
    }

    #[test]
    fn t006_an_unknown_id_and_an_unknown_name_agree_on_unknown_epic() {
        let config = registry(&[("e-aaaa", "Platform")]);
        let index = EpicIndex::build(&config, &no_issues());
        for reference in ["e-zzzz", "Nowhere"] {
            let err = index.resolve(reference).unwrap_err();
            assert_eq!(err.kind(), EpicDiagnosticKind::UnknownEpic, "{err}");
            assert_eq!(err.kind().as_str(), "unknown_epic");
            assert!(err.message().contains(reference));
        }
    }

    #[test]
    fn t006_list_epics_is_declaration_ordered_with_derived_counts() {
        let mut config = registry(&[("e-bbbb", "Second"), ("e-aaaa", "First")]);
        config
            .epics
            .insert("e-cccc".to_string(), record("Child", Some("e-aaaa"), None));
        // Declaration order, not sorted: moving `e-aaaa` after `e-cccc` proves it.
        config.epics.shift_remove("e-aaaa");
        config.epics.insert(
            "e-aaaa".to_string(),
            EpicConfiguration {
                name: "First".to_string(),
                ..Default::default()
            },
        );
        let issues = vec![
            Node::new(1, "One").with(&["e-aaaa"]),
            Node::new(2, "Two").with(&["e-aaaa"]),
        ];
        let listed = list_epics(&config, &issues);
        assert_eq!(
            listed.iter().map(|e| e.id.as_str()).collect::<Vec<_>>(),
            vec!["e-bbbb", "e-cccc", "e-aaaa"]
        );
        let first = &listed[2];
        assert_eq!(first.member_count, 2);
        assert_eq!(first.child_count, 1);
        assert_eq!(first.children[0].id.as_str(), "e-cccc");
        assert_eq!(first.children[0].display, "Child (e-cccc)");
        // An empty registry is an empty list, never an error.
        assert_eq!(
            list_epics(&Config::default(), &no_issues()),
            [] as [crate::epics::Epic; 0]
        );
    }

    #[test]
    fn t006_an_invalid_weight_is_refused_on_edit_and_a_valid_one_is_kept() {
        let mut config = registry(&[("e-aaaa", "Platform")]);
        let bad = EpicEdit {
            weight: Patch::Set(0),
            ..EpicEdit::default()
        };
        let err = edit_epic(&mut config, "e-aaaa", &bad).unwrap_err();
        assert_eq!(err.kind().as_str(), "invalid_weight");
        assert_eq!(
            config.epics["e-aaaa"].weight, None,
            "a refusal writes nothing"
        );
        let good = EpicEdit {
            weight: Patch::Set(8),
            ..EpicEdit::default()
        };
        assert_eq!(
            edit_epic(&mut config, "e-aaaa", &good).unwrap().weight,
            Some(8)
        );
        let cleared = EpicEdit {
            weight: Patch::Clear,
            ..EpicEdit::default()
        };
        assert_eq!(
            edit_epic(&mut config, "e-aaaa", &cleared).unwrap().weight,
            None
        );
    }

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

    #[test]
    fn t007_membership_is_ordered_by_issue_number_and_stable_across_rebuilds() {
        let config = registry(&[("e-aaaa", "Platform"), ("e-bbbb", "Sync")]);
        let issues = vec![
            Node::new(9, "Nine").with(&["e-aaaa"]),
            Node::new(3, "Three").with(&["e-aaaa", "e-bbbb"]),
            Node::new(7, "Seven").with(&["e-aaaa", "e-aaaa"]),
        ];
        let index = EpicIndex::build(&config, &issues);
        let membership = index.membership("e-aaaa").unwrap();
        assert_eq!(
            membership
                .members
                .iter()
                .map(|m| m.issue.number())
                .collect::<Vec<_>>(),
            vec![3, 7, 9]
        );
        assert_eq!(membership.member_count, 3);
        assert_eq!(membership.members[0].display, "#3 Three");
        assert_eq!(index.membership("e-bbbb").unwrap().member_count, 1);
        // A duplicate id on one issue is one reference, not two.
        assert_eq!(
            index.bucket(&EpicId::new("e-aaaa").unwrap()).unwrap().len(),
            3
        );
        // Two builds of the same snapshot are equal, so nothing is order-dependent.
        assert_eq!(index, EpicIndex::build(&config, &issues));
    }

    #[test]
    fn t007_two_epics_sharing_an_issue_both_hold_it_and_an_unreferenced_issue_is_in_none() {
        let config = registry(&[("e-aaaa", "Platform"), ("e-bbbb", "Sync")]);
        let issues = vec![
            Node::new(1, "Shared").with(&["e-aaaa", "e-bbbb"]),
            Node::new(2, "Lonely"),
        ];
        let buckets = membership_index(&config, &issues);
        assert_eq!(
            buckets[&EpicId::new("e-aaaa").unwrap()],
            vec![IssueKey::new(1)]
        );
        assert_eq!(
            buckets[&EpicId::new("e-bbbb").unwrap()],
            vec![IssueKey::new(1)]
        );
        assert!(!buckets.values().flatten().any(|key| key.number() == 2));
        // A known epic with no members is an empty bucket, not a missing one.
        let config = registry(&[("e-cccc", "Empty")]);
        let buckets = membership_index(&config, &no_issues());
        assert_eq!(buckets.get(&EpicId::new("e-cccc").unwrap()), None);
        let index = EpicIndex::build(&config, &no_issues());
        assert_eq!(index.bucket(&EpicId::new("e-cccc").unwrap()), Some(&[][..]));
        assert!(index.bucket(&EpicId::new("e-zzzz").unwrap()).is_none());
    }

    #[test]
    fn t007_a_missing_epic_reference_is_accounted_for_rather_than_dropped() {
        let config = registry(&[("e-aaaa", "Platform")]);
        let issues = vec![Node::new(4, "Dangling").with(&["e-gone", "e-aaaa"])];
        let index = EpicIndex::build(&config, &issues);
        // The resolvable reference still buckets the issue.
        assert_eq!(
            index.bucket(&EpicId::new("e-aaaa").unwrap()).unwrap().len(),
            1
        );
        // The unresolvable one is reported, never silently absent.
        assert_eq!(index.missing().len(), 1);
        let missing = &index.missing()[0];
        assert_eq!(missing.target_kind, EpicReferenceKind::Epic);
        assert_eq!(missing.target, "e-gone");
        assert_eq!(missing.holder, ReferenceHolder::Issue(IssueKey::new(4)));
        assert_eq!(missing.holder.to_string(), "issue #4");
        assert!(missing.reason.contains("e-gone"));
    }

    #[test]
    fn t007_no_member_list_is_stored_and_a_reference_change_leaves_the_record_alone() {
        let config = registry(&[("e-aaaa", "Platform")]);
        let issues = vec![
            Node::new(1, "Member").with(&["e-aaaa"]),
            Node::new(2, "Second"),
        ];
        let record_before = config.epics["e-aaaa"].clone();
        let change = reference_epic(&config, &issues, 2, "e-aaaa").unwrap();
        assert_eq!(ids(&change), vec!["e-aaaa"]);
        // The change is on the **issue**, and the registry record is untouched:
        // an epic record has no member list to carry (data-model §4, C-002).
        assert_eq!(config.epics["e-aaaa"], record_before);
        let serialized = toml::to_string(&config.epics["e-aaaa"]).unwrap();
        assert!(!serialized.contains("members"), "{serialized}");
        assert!(!serialized.contains("issues"), "{serialized}");
    }

    #[test]
    fn t007_a_task_labelled_issue_is_a_member_like_any_other() {
        // The fixture really carries a `task` label …
        let task = Node::new(1, "A task").with(&["e-aaaa"]).labelled("task");
        let ordinary = Node::new(2, "An issue").with(&["e-aaaa"]);
        assert_eq!(task.labels, vec!["task".to_string()]);

        let config = registry(&[("e-aaaa", "Platform")]);
        let issues = vec![task, ordinary];
        let index = EpicIndex::build(&config, &issues);
        let members = index.membership("e-aaaa").unwrap();
        // … and membership is exactly the same shape for it (C-001).
        assert_eq!(
            members
                .members
                .iter()
                .map(|m| m.issue.number())
                .collect::<Vec<_>>(),
            vec![1, 2]
        );
        // `EpicNode` has no label accessor, so no task structure can exist: the
        // only bucket map is the epic one (one entry, one epic).
        assert_eq!(index.buckets().len(), 1);
        // And a task-labelled issue rides the ordinary reference path: referencing
        // the plain issue and dereferencing the task are the same operations with
        // the same shapes.
        let added = reference_epic(&config, &issues, 2, "e-aaaa").unwrap();
        assert!(added.event.is_none(), "it already carries the reference");
        assert_eq!(ids(&added), vec!["e-aaaa"]);
        let changed = dereference_epic(&issues, 1, "e-aaaa").unwrap();
        assert_eq!(ids(&changed), [] as [&str; 0]);
        assert_eq!(changed.event.unwrap().kind, EpicEventKind::EpicDereferenced);
    }

    // --- T008: the dedicated iterative walk and hierarchy --------------------

    #[test]
    fn t008_a_three_deep_chain_reports_ancestors_children_and_depth() {
        let mut config = registry(&[("e-root", "Root")]);
        config
            .epics
            .insert("e-mid".to_string(), record("Mid", Some("e-root"), None));
        config
            .epics
            .insert("e-leaf".to_string(), record("Leaf", Some("e-mid"), None));

        let index = EpicIndex::build(&config, &no_issues());
        let leaf = index.hierarchy("e-leaf").unwrap();
        assert_eq!(leaf.parent.unwrap().id.as_str(), "e-mid");
        assert_eq!(leaf.recorded_parent.as_deref(), Some("e-mid"));
        assert_eq!(leaf.depth, 2);
        assert_eq!(
            leaf.ancestors
                .iter()
                .map(|a| a.id.as_str())
                .collect::<Vec<_>>(),
            vec!["e-root", "e-mid"],
            "ancestors are root-first"
        );
        assert!(leaf.children.is_empty() && leaf.child_count == 0);
        assert!(leaf.unresolved.is_none());

        let root = index.hierarchy("e-root").unwrap();
        assert!(root.parent.is_none() && root.ancestors.is_empty() && root.depth == 0);
        assert_eq!(
            root.children
                .iter()
                .map(|c| c.id.as_str())
                .collect::<Vec<_>>(),
            vec!["e-mid"]
        );
        assert_eq!(root.children[0].display, "Mid (e-mid)");
    }

    #[test]
    fn t008_a_self_parent_is_rejected_before_any_write() {
        let mut config = registry(&[("e-aaaa", "Platform"), ("e-bbbb", "Other")]);
        let before = config.clone();
        let edit = EpicEdit {
            parent: Patch::Set("e-aaaa".to_string()),
            ..EpicEdit::default()
        };
        let err = edit_epic(&mut config, "e-aaaa", &edit).unwrap_err();
        assert_eq!(err.kind(), EpicDiagnosticKind::SelfParent);
        assert_eq!(err.kind().as_str(), "self_parent");
        assert_eq!(
            config, before,
            "a refusal leaves the registry byte-unchanged"
        );
        // By name too: the name resolves to the same epic, so it is the same refusal.
        let by_name = EpicEdit {
            parent: Patch::Set("Platform".to_string()),
            ..EpicEdit::default()
        };
        assert_eq!(
            edit_epic(&mut config, "e-aaaa", &by_name)
                .unwrap_err()
                .kind(),
            EpicDiagnosticKind::SelfParent
        );
        assert_eq!(config, before);
    }

    #[test]
    fn t008_a_cycle_closing_parent_is_rejected_with_the_path() {
        let mut config = registry(&[("e-aaaa", "A")]);
        config
            .epics
            .insert("e-bbbb".to_string(), record("B", Some("e-aaaa"), None));
        config
            .epics
            .insert("e-cccc".to_string(), record("C", Some("e-bbbb"), None));
        let before = config.epics.clone();

        // `e-aaaa -> e-cccc` closes a-aaaa -> c-cccc -> b-bbbb -> a-aaaa.
        let edit = EpicEdit {
            parent: Patch::Set("e-cccc".to_string()),
            ..EpicEdit::default()
        };
        let err = edit_epic(&mut config, "e-aaaa", &edit).unwrap_err();
        let EpicError::Cycle { path, .. } = &err else {
            panic!("expected a cycle refusal, got {err}");
        };
        assert_eq!(
            path.iter().map(EpicId::as_str).collect::<Vec<_>>(),
            vec!["e-aaaa", "e-cccc", "e-bbbb"]
        );
        assert!(err.message().contains("e-cccc"));
        assert_eq!(config.epics, before, "SC-005: nothing was written");
        assert!(config.epics["e-aaaa"].parent.is_none());
    }

    #[test]
    fn t008_a_ten_thousand_node_chain_walks_without_overflow() {
        // NFR-001's scale: a recursive walk overflows the stack here, an
        // iterative one is 10,000 loop turns.
        const N: usize = 10_000;
        let mut registry: IndexMap<String, EpicConfiguration> = IndexMap::new();
        registry.insert("e-00000".to_string(), record("Root", None, None));
        for n in 1..N {
            let parent = format!("e-{:05}", n - 1);
            registry.insert(format!("e-{n:05}"), record("Node", Some(&parent), None));
        }

        // Closing the chain is refused, with the whole path reported.
        let root = EpicId::new("e-00000").unwrap();
        let deepest = format!("e-{:05}", N - 1);
        let err = validate_epic_parent(&registry, &root, &deepest).unwrap_err();
        let EpicError::Cycle { path, .. } = &err else {
            panic!("expected a cycle refusal, got {err}");
        };
        assert_eq!(path.len(), N);
        assert_eq!(path[0].as_str(), "e-00000");
        assert_eq!(path[1].as_str(), deepest);

        // And a walk that does **not** close stays accepted at the same depth.
        let fresh = EpicId::new("e-new").unwrap();
        assert_eq!(
            validate_epic_parent(&registry, &fresh, &deepest)
                .unwrap()
                .as_str(),
            deepest
        );

        // The navigation walk is iterative too: the leaf's depth is N - 1.
        let config = Config {
            epics: registry,
            ..Config::default()
        };
        let index = EpicIndex::build(&config, &no_issues());
        assert_eq!(index.hierarchy(&deepest).unwrap().depth, N - 1);
    }

    #[test]
    fn t008_a_parent_naming_a_deleted_epic_is_unresolved_not_dropped() {
        let mut config = registry(&[("e-aaaa", "Gone")]);
        config
            .epics
            .insert("e-bbbb".to_string(), record("Child", Some("e-aaaa"), None));
        config.epics.shift_remove("e-aaaa");

        let index = EpicIndex::build(&config, &no_issues());
        let hierarchy = index.hierarchy("e-bbbb").unwrap();
        assert!(hierarchy.parent.is_none(), "it does not resolve");
        assert_eq!(hierarchy.recorded_parent.as_deref(), Some("e-aaaa"));
        let unresolved = hierarchy.unresolved.unwrap();
        assert_eq!(unresolved.epic.as_str(), "e-bbbb");
        assert_eq!(unresolved.recorded_parent, "e-aaaa");
        assert!(unresolved.reason.contains("e-aaaa"));
        assert!(unresolved.reason.contains("e-bbbb"));
        // The reference is retained on the record so it can be repaired.
        assert_eq!(config.epics["e-bbbb"].parent.as_deref(), Some("e-aaaa"));
        // A repair clears it.
        let edit = EpicEdit {
            parent: Patch::Clear,
            ..EpicEdit::default()
        };
        let mut config = config;
        edit_epic(&mut config, "e-bbbb", &edit).unwrap();
        assert!(config.epics["e-bbbb"].parent.is_none());
    }

    #[test]
    fn t008_entering_a_stored_cycle_is_not_closing_one() {
        // A stored cycle `e-aaaa -> e-bbbb -> e-aaaa` that survives load, plus two
        // acyclic epics whose chains merely run into it.
        let mut registry: IndexMap<String, EpicConfiguration> = IndexMap::new();
        registry.insert("e-aaaa".to_string(), record("A", Some("e-bbbb"), None));
        registry.insert("e-bbbb".to_string(), record("B", Some("e-aaaa"), None));
        registry.insert("e-cccc".to_string(), record("C", Some("e-aaaa"), None));
        registry.insert("e-dddd".to_string(), record("D", None, None));

        // Attaching an unrelated epic under the cyclic subtree closes nothing:
        // neither the epic being edited nor its chain is part of the loop.
        let c = EpicId::new("e-cccc").unwrap();
        assert_eq!(
            validate_epic_parent(&registry, &c, "e-aaaa")
                .unwrap()
                .as_str(),
            "e-aaaa"
        );
        let fresh = EpicId::new("e-new1").unwrap();
        assert_eq!(
            validate_epic_parent(&registry, &fresh, "e-bbbb")
                .unwrap()
                .as_str(),
            "e-bbbb"
        );

        // … and the chain sweep reports the pre-existing loop exactly once, not
        // once per epic that runs into it.
        let defects = validate_epic_chains(&registry);
        assert_eq!(defects.len(), 1, "{defects:#?}");
        assert_eq!(defects[0].kind(), EpicDiagnosticKind::Cycle);
        assert_eq!(chain_epic(&defects[0]).unwrap().as_str(), "e-aaaa");

        // A proposal that *does* close a loop still refuses, with the path.
        let err = validate_epic_parent(&registry, &c, "e-cccc").unwrap_err();
        assert_eq!(err.kind(), EpicDiagnosticKind::SelfParent);
        let closes = validate_epic_parent(&registry, &EpicId::new("e-dddd").unwrap(), "e-aaaa");
        assert_eq!(closes.unwrap().as_str(), "e-aaaa");
    }

    #[test]
    fn t008_a_stored_self_parent_is_reported_once() {
        let mut registry: IndexMap<String, EpicConfiguration> = IndexMap::new();
        registry.insert("e-aaaa".to_string(), record("A", Some("e-aaaa"), None));
        registry.insert("e-bbbb".to_string(), record("B", None, None));
        let defects = validate_epic_chains(&registry);
        assert_eq!(defects.len(), 1, "one defect, not two: {defects:#?}");
        assert_eq!(defects[0].kind(), EpicDiagnosticKind::SelfParent);
        assert_eq!(chain_epic(&defects[0]).unwrap().as_str(), "e-aaaa");
    }

    #[test]
    fn t006_the_reference_fields_are_writable_through_the_service() {
        let mut config = registry(&[("e-aaaa", "Platform")]);
        let created = create_epic(
            &mut config,
            &NewEpic {
                name: "Full".to_string(),
                projects: vec!["p-ok1".to_string()],
                milestone: Some("2026-Q4".to_string()),
                cycle: Some("October 2026".to_string()),
                ..NewEpic::default()
            },
        )
        .unwrap();
        assert_eq!(created.parent, None);
        assert_eq!(config.epics[created.id.as_str()].projects, vec!["p-ok1"]);
        assert_eq!(
            config.epics[created.id.as_str()].milestone.as_deref(),
            Some("2026-Q4")
        );

        // `Set` writes, a dangling-but-well-formed id is kept (not refused) and is
        // then diagnosed, and `Clear` removes the reference.
        let edit = EpicEdit {
            projects: Patch::Set(vec!["p-gone".to_string(), "p-gone".to_string()]),
            milestone: Patch::Set("Nowhere".to_string()),
            cycle: Patch::Clear,
            ..EpicEdit::default()
        };
        let edited = edit_epic(&mut config, "e-aaaa", &edit).unwrap();
        assert_eq!(edited.projects, vec!["p-gone"]);
        assert_eq!(edited.milestone.as_deref(), Some("Nowhere"));
        assert_eq!(edited.cycle, None);
        let record = &config.epics["e-aaaa"];
        assert_eq!(
            record.projects,
            vec!["p-gone"],
            "a duplicate collapses to one"
        );
        assert_eq!(record.milestone.as_deref(), Some("Nowhere"));
        assert_eq!(record.cycle, None);

        let found = resolve_references(epics(&config), &no_issues(), &ReferenceTargets::default());
        let kinds_of = |epic: &EpicId| -> Vec<EpicReferenceKind> {
            found
                .iter()
                .filter(|f| f.holder == ReferenceHolder::Epic(epic.clone()))
                .map(|f| f.target_kind)
                .collect()
        };
        // The epic the service just edited carries the dangling project and
        // milestone, and no cycle (it was cleared).
        assert_eq!(
            kinds_of(&EpicId::new("e-aaaa").unwrap()),
            vec![EpicReferenceKind::Project, EpicReferenceKind::Milestone]
        );
        // The created epic carries all three reference kinds it was given.
        assert_eq!(
            kinds_of(&created.id),
            vec![
                EpicReferenceKind::Project,
                EpicReferenceKind::Milestone,
                EpicReferenceKind::Cycle
            ]
        );
    }

    #[test]
    fn t006_a_malformed_project_id_is_refused_before_any_write() {
        let mut config = registry(&[("e-aaaa", "Platform")]);
        let before = config.clone();
        let bad_edit = EpicEdit {
            projects: Patch::Set(vec!["Not A Project".to_string()]),
            ..EpicEdit::default()
        };
        let err = edit_epic(&mut config, "e-aaaa", &bad_edit).unwrap_err();
        assert_eq!(err.kind(), EpicDiagnosticKind::InvalidReference);
        assert_eq!(err.kind().as_str(), "invalid_reference");
        assert!(err.message().contains("Not A Project"));
        assert_eq!(config, before, "a refusal writes nothing");

        let bad_create = create_epic(
            &mut config,
            &NewEpic {
                name: "Bad refs".to_string(),
                projects: vec!["  p-ok1".to_string()],
                ..NewEpic::default()
            },
        );
        assert_eq!(
            bad_create.unwrap_err().kind(),
            EpicDiagnosticKind::InvalidReference
        );
        assert_eq!(config, before);
    }

    #[test]
    fn t008_a_stored_cycle_is_reported_by_the_chain_validation() {
        let mut config = registry(&[("e-aaaa", "A")]);
        config
            .epics
            .insert("e-bbbb".to_string(), record("B", Some("e-aaaa"), None));
        // Force a stored cycle behind the write path's back.
        config
            .epics
            .insert("e-aaaa".to_string(), record("A", Some("e-bbbb"), None));
        let defects = validate_epic_chains(epics(&config));
        assert_eq!(defects.len(), 1);
        assert_eq!(defects[0].kind(), EpicDiagnosticKind::Cycle);
        // Navigation stays total on a stored cycle rather than looping.
        let index = EpicIndex::build(&config, &no_issues());
        assert_eq!(index.hierarchy("e-aaaa").unwrap().depth, 1);
    }

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

    #[test]
    fn t009_each_missing_reference_kind_reports_exactly_one_named_entry() {
        let mut config = registry(&[("e-aaaa", "Platform")]);
        config.epics.insert(
            "e-bbbb".to_string(),
            EpicConfiguration {
                name: "Broken".to_string(),
                parent: Some("e-aaaa".to_string()),
                projects: vec!["p-gone".to_string()],
                milestone: Some("2026-Q4".to_string()),
                cycle: Some("October 2026".to_string()),
                ..EpicConfiguration::default()
            },
        );
        let issues = vec![
            Node::new(1, "Dangling").with(&["e-missing"]),
            Node::new(2, "Malformed").with(&["Not An Id"]),
        ];
        let targets = targets(&[], &[], &[]);
        let found = resolve_references(epics(&config), &issues, &targets);

        assert_eq!(found.len(), 5, "{found:#?}");
        for kind in [
            EpicReferenceKind::Epic,
            EpicReferenceKind::Project,
            EpicReferenceKind::Issue,
            EpicReferenceKind::Milestone,
            EpicReferenceKind::Cycle,
        ] {
            let matching: Vec<&EpicReferenceResolution> =
                found.iter().filter(|f| f.target_kind == kind).collect();
            assert_eq!(matching.len(), 1, "{kind} must be diagnosed once");
            let record = matching[0];
            assert!(!record.target.is_empty() || kind == EpicReferenceKind::Issue);
            assert_ne!(record.reason, "");
            assert!(record.reason.contains(&record.target) || record.target.is_empty());
            assert_eq!(
                kind.diagnostic_kind(),
                format!("missing_{}_reference", kind.as_str())
            );
        }
        // The recorded target is what the user must repair, verbatim.
        let by_kind = |kind: EpicReferenceKind| {
            found
                .iter()
                .find(|f| f.target_kind == kind)
                .unwrap()
                .clone()
        };
        let epic_ref = by_kind(EpicReferenceKind::Epic);
        assert_eq!(epic_ref.target, "e-missing");
        assert_eq!(epic_ref.holder, ReferenceHolder::Issue(IssueKey::new(1)));
        assert_eq!(epic_ref.holder.to_string(), "issue #1");
        assert_eq!(by_kind(EpicReferenceKind::Project).target, "p-gone");
        assert_eq!(by_kind(EpicReferenceKind::Milestone).target, "2026-Q4");
        assert_eq!(by_kind(EpicReferenceKind::Cycle).target, "October 2026");
        assert_eq!(by_kind(EpicReferenceKind::Issue).target, "Not An Id");
        assert_eq!(
            by_kind(EpicReferenceKind::Issue).holder,
            ReferenceHolder::Issue(IssueKey::new(2))
        );
    }

    #[test]
    fn t009_a_clean_snapshot_reports_nothing_and_a_resolvable_one_does_too() {
        let mut config = registry(&[("e-aaaa", "Platform")]);
        config.epics.insert(
            "e-bbbb".to_string(),
            EpicConfiguration {
                name: "Complete".to_string(),
                parent: Some("e-aaaa".to_string()),
                projects: vec!["p-aaaa".to_string()],
                milestone: Some("2026-Q4".to_string()),
                cycle: Some("October 2026".to_string()),
                ..EpicConfiguration::default()
            },
        );
        let issues = vec![Node::new(1, "Member").with(&["e-aaaa"])];
        let targets = targets(&["p-aaaa"], &["2026-Q4"], &["October 2026"]);
        assert_eq!(
            resolve_references(epics(&config), &issues, &targets),
            [] as [crate::epics::EpicReferenceResolution; 0]
        );
        // … and an epic with no reference fields is clean too.
        assert_eq!(
            resolve_references(
                epics(&registry(&[("e-aaaa", "Bare")])),
                &no_issues(),
                &targets
            ),
            [] as [crate::epics::EpicReferenceResolution; 0]
        );
    }

    #[test]
    fn t009_two_runs_over_the_same_input_are_equal_and_ordered() {
        let mut config = registry(&[("e-bbbb", "B")]);
        config
            .epics
            .insert("e-aaaa".to_string(), record("A", Some("e-gone"), None));
        config
            .epics
            .insert("e-cccc".to_string(), record("C", Some("e-gone"), None));
        let issues = vec![
            Node::new(5, "Five").with(&["e-x1"]),
            Node::new(2, "Two").with(&["e-x2"]),
        ];
        let first = resolve_references(epics(&config), &issues, &ReferenceTargets::default());
        let second = resolve_references(epics(&config), &issues, &ReferenceTargets::default());
        assert_eq!(first, second);
        // (holder, kind, target): the two issues first, then the two epics in order.
        assert_eq!(
            first
                .iter()
                .map(|f| (f.holder.to_string(), f.target.clone()))
                .collect::<Vec<_>>(),
            vec![
                ("epic `e-aaaa`".to_string(), "e-gone".to_string()),
                ("epic `e-cccc`".to_string(), "e-gone".to_string()),
                ("issue #2".to_string(), "e-x2".to_string()),
                ("issue #5".to_string(), "e-x1".to_string()),
            ]
        );
        assert!(
            first
                .windows(2)
                .all(|w| reference_order(&w[0], &w[1]) != std::cmp::Ordering::Greater)
        );
    }

    #[test]
    fn t009_targets_come_from_the_planner_lookups_not_a_second_store() {
        // No filesystem: a `Planner` built from an in-memory config answers the
        // cycle half of the targets from the same `[cycles]` registry the config
        // holds, including the implicit `Default`, and the milestone half from the
        // milestone registry (empty here because the tempdir's dir does not exist).
        let mut config = Config::default();
        config.cycles.insert(
            "October 2026".to_string(),
            crate::config::PlanningCycle::default(),
        );
        let planner = Planner::from_config(config, PathBuf::from("."));
        let resolved = ReferenceTargets::from_planner(&planner).unwrap();
        assert!(resolved.cycle_known("October 2026"));
        assert!(resolved.cycle_known(DEFAULT_CYCLE_NAME));
        assert!(!resolved.cycle_known("Nowhere"));
        assert!(!resolved.milestone_known("2026-Q4"));
    }

    // --- T010/T011: the rollup ------------------------------------------------

    #[test]
    fn t010_three_members_one_complete_report_done_one_of_three() {
        let config = registry(&[("e-aaaa", "Platform")]);
        let fixture = Blocking::new(
            vec![
                Node::new(1, "Complete").in_column("done").with(&["e-aaaa"]),
                Node::new(2, "Open").with(&["e-aaaa"]),
                Node::new(3, "Also open").with(&["e-aaaa"]),
            ],
            &[],
        );
        let views = fixture.views();
        let graph = RelationshipGraph::new(&views, "done");
        let figures = rollup(
            &config,
            &fixture.issues,
            "e-aaaa",
            &ReferenceTargets::default(),
            &graph,
        )
        .unwrap();
        assert_eq!(figures.progress.done, 1);
        assert_eq!(figures.progress.total, 3);
        assert_eq!(figures.progress.progress, Progress { done: 1, total: 3 });
        assert_eq!(figures.child_count, 0);
        assert_eq!(figures.blocked, 0);
        assert_eq!(figures.weighted_progress.total_weight, 0);
        assert_eq!(figures.weighted_progress.percent, None);
    }

    #[test]
    fn t010_an_epic_with_no_members_reports_zeros() {
        let config = registry(&[("e-aaaa", "Platform")]);
        let fixture = Blocking::new(no_issues(), &[]);
        let views = fixture.views();
        let graph = RelationshipGraph::new(&views, "done");
        let figures = rollup(
            &config,
            &fixture.issues,
            "e-aaaa",
            &ReferenceTargets::default(),
            &graph,
        )
        .unwrap();
        assert_eq!(figures.progress.progress, Progress { done: 0, total: 0 });
        assert_eq!(figures.child_count, 0);
        assert_eq!(figures.blocked, 0);
        assert_eq!(
            figures.blocked_members,
            [] as [crate::epics::BlockedMember; 0]
        );
        assert_eq!(
            figures.missing_references,
            [] as [crate::epics::EpicReferenceResolution; 0]
        );
    }

    #[test]
    fn t010_completion_resolves_from_the_configured_column_not_a_literal() {
        // The board completes on `shipped` and has no `done` column at all.
        let mut config = custom_completion(
            &["triage", "wip", "shipped"],
            "shipped",
            &[
                ("triage", "unstarted"),
                ("wip", "active"),
                ("shipped", "completed"),
            ],
        );
        config.epics.insert(
            "e-aaaa".to_string(),
            EpicConfiguration {
                name: "Platform".to_string(),
                ..EpicConfiguration::default()
            },
        );
        let issues = vec![
            Node::new(1, "Shipped")
                .in_column("shipped")
                .with(&["e-aaaa"]),
            Node::new(2, "Literal done")
                .in_column("done")
                .with(&["e-aaaa"]),
        ];
        let fixture = Blocking::new(issues, &[]);
        let views = fixture.views();
        let graph = RelationshipGraph::new(&views, "done");
        let figures = rollup(
            &config,
            &fixture.issues,
            "e-aaaa",
            &ReferenceTargets::default(),
            &graph,
        )
        .unwrap();
        assert_eq!(
            figures.progress.done, 1,
            "only the configured column counts"
        );
        assert_eq!(figures.progress.total, 2);
    }

    #[test]
    fn t011_the_known_fixture_counts_every_figure() {
        // Three members (one complete, one blocked), one child epic with a weight.
        let mut config = registry(&[("e-parent", "Parent"), ("e-child", "Child")]);
        config.epics.insert(
            "e-parent".to_string(),
            EpicConfiguration {
                name: "Parent".to_string(),
                weight: Some(5),
                ..EpicConfiguration::default()
            },
        );
        config.epics.insert(
            "e-child".to_string(),
            EpicConfiguration {
                name: "Child".to_string(),
                parent: Some("e-parent".to_string()),
                weight: Some(3),
                projects: vec!["p-gone".to_string()],
                ..EpicConfiguration::default()
            },
        );
        let issues = vec![
            Node::new(1, "Complete")
                .in_column("done")
                .with(&["e-parent"]),
            Node::new(2, "Blocked").with(&["e-parent"]),
            Node::new(3, "Open").with(&["e-parent"]),
            // The child's only member is complete, so the child is complete.
            Node::new(4, "Child member")
                .in_column("done")
                .with(&["e-child"]),
        ];
        let fixture = Blocking::new(issues, &[(3, 2)]);
        let views = fixture.views();
        let graph = RelationshipGraph::new(&views, "done");
        let figures = rollup(
            &config,
            &fixture.issues,
            "e-parent",
            &ReferenceTargets::default(),
            &graph,
        )
        .unwrap();

        assert_eq!(figures.epic_id.as_str(), "e-parent");
        assert_eq!(figures.name, "Parent");
        assert_eq!(figures.progress.done, 1);
        assert_eq!(figures.progress.total, 3);
        assert_eq!(figures.child_count, 1);
        assert_eq!(figures.blocked, 1);
        assert_eq!(figures.blocked_members.len(), 1);
        assert_eq!(figures.blocked_members[0].issue.number(), 2);
        assert_ne!(figures.blocked_members[0].reason, "");
        let weighted = &figures.weighted_progress;
        assert_eq!(weighted.own_weight, Some(5));
        assert_eq!(weighted.weighted_children, 1);
        assert_eq!(weighted.unweighted_children, 0);
        assert_eq!(weighted.total_weight, 3);
        assert_eq!(weighted.done_weight, 3);
        assert_eq!(weighted.percent, Some(100));
        // The parent has no dangling reference of its own …
        assert_eq!(
            figures.missing_references,
            [] as [crate::epics::EpicReferenceResolution; 0]
        );
        // … and the child's dangling project reference is visible on the child's
        // own rollup, which reads the same single computation.
        let child = rollup(
            &config,
            &fixture.issues,
            "e-child",
            &ReferenceTargets::default(),
            &graph,
        )
        .unwrap();
        assert_eq!(child.progress.progress, Progress { done: 1, total: 1 });
        assert_eq!(child.child_count, 0);
        assert_eq!(
            child
                .missing_references
                .iter()
                .map(|f| f.target_kind)
                .collect::<Vec<_>>(),
            vec![EpicReferenceKind::Project]
        );
        // The parent's own weight is what a parent consumes; the child reports its
        // own, and neither counts the other's twice.
        assert_eq!(child.weighted_progress.own_weight, Some(3));
        // Repeated reads of the same snapshot are equal (NFR-003).
        assert_eq!(
            figures,
            rollup(
                &config,
                &fixture.issues,
                "e-parent",
                &ReferenceTargets::default(),
                &graph
            )
            .unwrap()
        );
    }

    #[test]
    fn t011_weighted_progress_excludes_an_unweighted_child() {
        let mut config = registry(&[("e-parent", "Parent")]);
        config.epics.insert(
            "e-light".to_string(),
            record("Light", Some("e-parent"), None),
        );
        config.epics.insert(
            "e-heavy".to_string(),
            record("Heavy", Some("e-parent"), Some(10)),
        );
        let fixture = Blocking::new(vec![], &[]);
        let views = fixture.views();
        let graph = RelationshipGraph::new(&views, "done");
        let figures = rollup(
            &config,
            &fixture.issues,
            "e-parent",
            &ReferenceTargets::default(),
            &graph,
        )
        .unwrap();
        let weighted = &figures.weighted_progress;
        assert_eq!(
            weighted.weighted_children, 1,
            "the unweighted child is excluded"
        );
        assert_eq!(weighted.unweighted_children, 1);
        assert_eq!(weighted.total_weight, 10, "not 10 + 0");
        assert_eq!(
            weighted.done_weight, 0,
            "a child with no members is not complete"
        );
        assert_eq!(weighted.percent, Some(0));
    }

    #[test]
    fn t011_a_done_member_is_never_counted_as_blocked() {
        let config = registry(&[("e-aaaa", "Platform")]);
        let issues = vec![
            Node::new(1, "Done but claimed blocked")
                .in_column("done")
                .with(&["e-aaaa"]),
            Node::new(2, "Genuinely blocked").with(&["e-aaaa"]),
            Node::new(3, "An open blocker"),
        ];
        // The owner's read says #1 is blocked (its blocker is open) — the rollup
        // still must not count it, because it is complete.
        let fixture = Blocking::new(issues, &[(1, 1), (3, 1), (3, 2)]);
        let views = fixture.views();
        let graph = RelationshipGraph::new(&views, "done");
        let figures = rollup(
            &config,
            &fixture.issues,
            "e-aaaa",
            &ReferenceTargets::default(),
            &graph,
        )
        .unwrap();
        assert_eq!(figures.progress.done, 1);
        assert_eq!(figures.blocked, 1);
        assert_eq!(figures.blocked_members[0].issue.number(), 2);
    }

    #[test]
    fn t011_the_blocked_read_is_consumed_from_the_relationship_graph() {
        let config = registry(&[("e-aaaa", "Platform")]);
        let fixture = Blocking::new(
            vec![
                Node::new(1, "Blocked").with(&["e-aaaa"]),
                Node::new(2, "Blocker"),
            ],
            &[(2, 1)],
        );
        let views = fixture.views();
        let graph = RelationshipGraph::new(&views, "done");
        let index = EpicIndex::build(&config, &fixture.issues);
        let blocked = index.blocked_members(&EpicId::new("e-aaaa").unwrap(), &graph);
        assert_eq!(blocked.len(), 1);
        // The reason is the relationship service's own text, not a second wording.
        let owner = graph.blocked_state(1);
        assert!(owner.is_blocked);
        assert_eq!(blocked[0].reason, owner.reason);
    }

    #[test]
    fn t011_missing_references_are_visible_on_the_rollup() {
        let mut config = registry(&[("e-aaaa", "Platform")]);
        config.epics.insert(
            "e-aaaa".to_string(),
            EpicConfiguration {
                name: "Platform".to_string(),
                parent: Some("e-gone".to_string()),
                milestone: Some("Nowhere".to_string()),
                ..EpicConfiguration::default()
            },
        );
        let fixture = Blocking::new(vec![], &[]);
        let views = fixture.views();
        let graph = RelationshipGraph::new(&views, "done");
        let figures = rollup(
            &config,
            &fixture.issues,
            "e-aaaa",
            &ReferenceTargets::default(),
            &graph,
        )
        .unwrap();
        assert_eq!(
            figures
                .missing_references
                .iter()
                .map(|f| f.target_kind)
                .collect::<Vec<_>>(),
            vec![EpicReferenceKind::Epic, EpicReferenceKind::Milestone]
        );
    }

    // --- T009/T012: bulk reference and the deterministic event ----------------

    #[test]
    fn t012_reference_is_idempotent_and_each_accepted_change_has_one_event() {
        let config = registry(&[("e-aaaa", "Platform")]);
        let issues = vec![
            Node::new(1, "Member").with(&["e-aaaa"]),
            Node::new(2, "Second"),
        ];

        let noop = reference_epic(&config, &issues, 1, "e-aaaa").unwrap();
        assert!(
            noop.event.is_none(),
            "an already-present reference changes nothing"
        );
        assert_eq!(ids(&noop), vec!["e-aaaa"]);

        let added = reference_epic(&config, &issues, 2, "e-aaaa").unwrap();
        assert_eq!(ids(&added), vec!["e-aaaa"]);
        let event = added.event.unwrap();
        assert_eq!(event.kind, EpicEventKind::EpicReferenced);
        assert_eq!(event.kind.as_str(), "epic_referenced");
        assert_eq!(event.detail, "epic `e-aaaa` referenced");

        let removed = dereference_epic(&issues, 1, "e-aaaa").unwrap();
        assert_eq!(ids(&removed), [] as [&str; 0]);
        let event = removed.event.clone().unwrap();
        assert_eq!(event.kind.as_str(), "epic_dereferenced");
        assert_eq!(event.detail, "epic `e-aaaa` dereferenced");

        // Dereferencing an absent reference is an inert no-op with no event, and
        // it need not resolve: removing a stale reference is the repair path.
        let absent = dereference_epic(&issues, 2, "e-aaaa").unwrap();
        assert!(absent.event.is_none());
        assert_eq!(ids(&absent), [] as [&str; 0]);
        let stale = dereference_epic(&issues, 1, "e-gone").unwrap();
        assert!(stale.event.is_none());
        assert_eq!(ids(&stale), vec!["e-aaaa"]);
        // A name is not resolved here — stored entries are ids.
        assert!(
            dereference_epic(&issues, 1, "Platform")
                .unwrap()
                .event
                .is_none()
        );
    }

    #[test]
    fn t012_bulk_reference_reports_each_selector_independently() {
        let config = registry(&[("e-aaaa", "Platform")]);
        let issues = vec![
            Node::new(1, "One").with(&["e-aaaa"]),
            Node::new(2, "Two"),
            Node::new(3, "Three"),
        ];
        let outcomes = bulk_reference(&config, &issues, "e-aaaa", &[1, 2, 99, 3]);
        assert_eq!(outcomes.len(), 4);
        assert_eq!(
            outcomes.iter().map(|o| o.selector).collect::<Vec<_>>(),
            vec![1, 2, 99, 3]
        );
        assert!(outcomes[0].outcome.as_ref().unwrap().event.is_none());
        assert!(outcomes[1].outcome.as_ref().unwrap().event.is_some());
        // The unknown issue refuses **its** entry only; the rest still succeed.
        assert_eq!(
            outcomes[2].outcome.as_ref().unwrap_err().kind(),
            EpicDiagnosticKind::UnknownIssue
        );
        assert!(outcomes[3].outcome.as_ref().unwrap().event.is_some());

        // An unknown epic refuses every entry rather than aborting the call.
        let all = bulk_reference(&config, &issues, "e-zzzz", &[1, 2]);
        assert_eq!(all.len(), 2);
        assert!(
            all.iter()
                .all(|o| o.outcome.as_ref().unwrap_err().kind() == EpicDiagnosticKind::UnknownEpic)
        );
    }

    #[test]
    fn t012_reference_epic_refuses_an_unknown_issue() {
        let config = registry(&[("e-aaaa", "Platform")]);
        let err = reference_epic(&config, &no_issues(), 7, "e-aaaa").unwrap_err();
        assert_eq!(err.kind(), EpicDiagnosticKind::UnknownIssue);
        assert!(err.message().contains('7'));
    }

    #[test]
    fn t012_every_operation_in_the_contract_is_reachable() {
        // A compile-time inventory of contract §1: each name below is called, so a
        // rename or a removal fails this test rather than drifting silently.
        let mut config = registry(&[("e-aaaa", "Platform")]);
        config.epics.insert(
            "e-bbbb".to_string(),
            record("Child", Some("e-aaaa"), Some(2)),
        );
        let issues = vec![Node::new(1, "Member").in_column("done").with(&["e-aaaa"])];
        let fixture = Blocking::new(issues.clone(), &[]);
        let views = fixture.views();
        let graph = RelationshipGraph::new(&views, "done");

        let _ = create_epic(
            &mut config,
            &NewEpic {
                name: "Created".to_string(),
                ..NewEpic::default()
            },
        )
        .unwrap();
        let _ = edit_epic(
            &mut config,
            "e-bbbb",
            &EpicEdit {
                status: Patch::Set("active".to_string()),
                projects: Patch::Set(vec!["p-ok1".to_string()]),
                milestone: Patch::Set("2026-Q4".to_string()),
                cycle: Patch::Set("October 2026".to_string()),
                ..EpicEdit::default()
            },
        )
        .unwrap();
        let _ = list_epics(&config, &issues);
        let _ = resolve(&config, &issues, "e-aaaa").unwrap();
        let _ = membership_index(&config, &issues);
        let _ = membership(&config, &issues, "e-aaaa").unwrap();
        let _ = hierarchy(&config, &issues, "e-aaaa").unwrap();
        let _ = reference_epic(&config, &issues, 1, "e-bbbb").unwrap();
        let _ = dereference_epic(&issues, 1, "e-aaaa").unwrap();
        let _ = bulk_reference(&config, &issues, "e-aaaa", &[1]);
        let _ = resolve_references(epics(&config), &issues, &ReferenceTargets::default());
        let _ = rollup(
            &config,
            &fixture.issues,
            "e-aaaa",
            &ReferenceTargets::default(),
            &graph,
        )
        .unwrap();
        let deletion = delete_epic(&mut config, "e-bbbb", &issues).unwrap();
        assert_eq!(deletion.name, "Child");

        // The refusal wording and kinds are the contract's, verbatim.
        assert_eq!(EpicDiagnosticKind::DuplicateName.as_str(), "duplicate_name");
        assert_eq!(EpicDiagnosticKind::UnknownEpic.as_str(), "unknown_epic");
        assert_eq!(EpicDiagnosticKind::UnknownIssue.as_str(), "unknown_issue");
        assert_eq!(EpicDiagnosticKind::InvalidDates.as_str(), "invalid_dates");
        assert_eq!(EpicDiagnosticKind::InvalidWeight.as_str(), "invalid_weight");
        assert_eq!(
            EpicDiagnosticKind::InvalidReference.as_str(),
            "invalid_reference"
        );
        assert_eq!(EpicDiagnosticKind::SelfParent.as_str(), "self_parent");
        assert_eq!(EpicDiagnosticKind::Cycle.as_str(), "cycle");
        assert_eq!(EPICS_KEY, "epics");
        assert_eq!(
            epic_display(&EpicId::new("e-aaaa").unwrap(), "Platform"),
            "Platform (e-aaaa)"
        );
    }

    #[test]
    fn t012_the_module_is_filesystem_free() {
        // One test that proves the whole surface needs no `Store` and no
        // `tempfile`: everything below is built from `Config::default()` and
        // `Vec<Node>` and no path is ever touched. It mirrors the contract's
        // "registry + issue set" operations exactly.
        let mut config = Config::default();
        let created = create_epic(
            &mut config,
            &NewEpic {
                name: "An epic".to_string(),
                weight: Some(1),
                ..NewEpic::default()
            },
        )
        .unwrap();
        let fixture = Blocking::new(
            vec![Node::new(1, "Member").with(&[created.id.as_str()])],
            &[],
        );
        let views = fixture.views();
        let graph = RelationshipGraph::new(&views, "done");
        let figures = rollup(
            &config,
            &fixture.issues,
            created.id.as_str(),
            &ReferenceTargets::default(),
            &graph,
        )
        .unwrap();
        assert_eq!(figures.progress.total, 1);
        assert_eq!(
            resolve_references(
                epics(&config),
                &fixture.issues,
                &ReferenceTargets::default()
            ),
            [] as [crate::epics::EpicReferenceResolution; 0]
        );
    }
}