tix/

relationships.rs

//! Typed relationship domain service.
//!
//! This module is the **single owner** of every relationship semantic in
//! `tix`: the closed relation vocabulary, stable relationship identity, the
//! canonical direction convention, adjacency, and all graph validation
//! (self-link, missing target, conflicting edge, cycle). The CLI, TUI, MCP,
//! `tix lint`, the move guard, and the sync adapters all call into here —
//! none of them re-derives direction handling, cycle detection, or blocked
//! state locally. That is what makes CLI/TUI/MCP parity structural rather
//! than a convention (charter: "share domain/application logic where
//! practical").
//!
//! # Canonical direction convention
//!
//! There is exactly one convention, and it is stated here rather than only in
//! a test:
//!
//! - `blocks` is authored from the **blocking** issue to the **blocked** issue
//!   and is the **only authoritative stored form** of a blocking relationship.
//! - `blocked_by` is the explicit inverse **input spelling** of that same
//!   edge. [`normalize`] rewrites it into the canonical `blocks` edge, so a
//!   `blocked_by` value is never persisted and a pair is never stored twice:
//!   `A --blocked_by--> B` and `B --blocks--> A` are the same edge.
//! - `duplicates` and `related` are authored source → target and never produce
//!   a mirrored edge. `related` is the only non-directional kind.
//!
//! A **reciprocal** blocking pair (`A blocks B` *and* `B blocks A`) is a
//! two-edge directed cycle and is therefore rejected by the cycle rule. There
//! is no accept-and-normalize path for it.
//!
//! # Closed vocabulary
//!
//! Exactly four kinds ship: `blocks`, `blocked_by`, `duplicates`, `related`
//! (decision `01M3BXC5P4MK0BYECA3K1B9Z82`). The set is **compiled in** — this
//! module adds no `tix.toml` relation-type configuration key, and an unknown
//! kind is a validation error, never a free-form string and never a coerced
//! default.
//!
//! # Blocked-state resolution predicate
//!
//! [`RelationshipGraph::blocked_state`] is the only place "is this blocker
//! still open?" is answered. An inbound `blocks` edge from blocker `X` to
//! issue `Y` counts **iff** `X` resolves to an existing issue **and** `X`'s
//! status is not the board's configured `done_column`. A dangling edge whose
//! blocker no longer exists is reported as `missing_target` by validation but
//! is **excluded** here, so invalid data can never permanently freeze an
//! issue. Completion is resolved from configuration, never by matching the
//! literal string `done`; workflow *category* semantics are out of scope
//! (source issue #183).
//!
//! # Breaking replacement
//!
//! The retired `links:` frontmatter key is a **validation result**
//! ([`DiagnosticKind::RetiredLinksKey`]), never a parse fallback. Nothing in
//! this module reads legacy link values as typed data (C-001).
//!
//! # Complexity
//!
//! [`RelationshipGraph::validate_snapshot`] is a single `O(V + E)` pass and
//! never returns `Err` — it yields a [`RelationshipValidationResult`] so
//! `tix lint` can call it directly. Cycle detection and blocked-state
//! derivation share one adjacency build, so a surface that shows both does not
//! pay twice (NFR-001). Traversal is iterative throughout: a 10,000-node chain
//! must not overflow the stack.
//!
//! # Scope of this module
//!
//! This is the domain layer only. Of the operations in
//! `contracts/relationship-service.md` §1, it owns the *computation* half:
//!
//! | Contract operation | Provided here | Supplied by |
//! |---|---|---|
//! | `validate_snapshot` | yes | — |
//! | `dependency_chain` | yes | — |
//! | `blocked_state` | yes | — |
//! | `list_relations` | yes, as `relationships_for` / `blocks` / `blocked_by` / `duplicates_of` / `related_to` | — |
//! | "are these the same relationship?" | yes, as `find_canonical` | — |
//! | `create_relation` | validation + lookup only: `validate_create`, `find_canonical`, `normalize` | write path: WP02 `Store`, WP03 CLI |
//! | `edit_relation` | validation only: `validate_edit` | write path: WP02 `Store`, WP03 CLI |
//! | `remove_relation` | lookup only: `find_relationship` | write path: WP02 `Store`, WP03 CLI |
//!
//! Nothing here reads or writes a file, so the write half cannot be added
//! without the storage seam. `validate_*` returns a verdict; persisting it is
//! the caller's job, and it must not write anything at all when the verdict is
//! blocking (contract §4).

use std::collections::{HashMap, HashSet, VecDeque};
use std::fmt;
use std::str::FromStr;

use serde::{Deserialize, Serialize};

use crate::id::{AliasIndex, IdentityNode, IssueRef, canonical_ref};

// ---------------------------------------------------------------------------
// T001 — the closed vocabulary and the typed edge
// ---------------------------------------------------------------------------

/// The closed vocabulary of typed relations.
///
/// Exactly four kinds ship in this mission (decision
/// `01M3BXC5P4MK0BYECA3K1B9Z82`). The set is compiled in — there is no
/// configuration key — and an unknown kind is rejected rather than coerced.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum RelationKind {
    /// The source issue blocks the target issue. The canonical stored form of
    /// a blocking relationship.
    Blocks,
    /// The source issue is blocked by the target issue. An **input spelling
    /// only**: it normalizes into the equivalent [`RelationKind::Blocks`] edge
    /// and is never persisted.
    BlockedBy,
    /// The source issue duplicates the target issue. No blocked-state effect.
    Duplicates,
    /// Explicit non-directional association. Stored once, never mirrored, and
    /// the only non-directional kind.
    Related,
}

impl RelationKind {
    /// Every kind in the closed vocabulary, in canonical spell order.
    pub const ALL: [RelationKind; 4] = [
        RelationKind::Blocks,
        RelationKind::BlockedBy,
        RelationKind::Duplicates,
        RelationKind::Related,
    ];

    /// The canonical lowercase spelling used in files and CLI output.
    pub fn as_str(self) -> &'static str {
        match self {
            RelationKind::Blocks => "blocks",
            RelationKind::BlockedBy => "blocked_by",
            RelationKind::Duplicates => "duplicates",
            RelationKind::Related => "related",
        }
    }

    /// Whether the kind has a direction. False only for [`RelationKind::Related`].
    pub fn is_directional(self) -> bool {
        !matches!(self, RelationKind::Related)
    }

    /// The kind that describes the same edge seen from the other endpoint.
    ///
    /// `Blocks` ↔ `BlockedBy`; `Duplicates` and `Related` have no inverse
    /// because neither mirrors.
    pub fn inverse(self) -> Option<Self> {
        match self {
            RelationKind::Blocks => Some(RelationKind::BlockedBy),
            RelationKind::BlockedBy => Some(RelationKind::Blocks),
            RelationKind::Duplicates | RelationKind::Related => None,
        }
    }

    /// The kind this one normalizes to for storage, plus whether the
    /// endpoints must be swapped to reach it.
    ///
    /// `blocked_by` is the only kind that swaps: `A blocked_by B` is stored as
    /// `B blocks A`.
    fn canonical(self) -> (Self, bool) {
        match self {
            RelationKind::BlockedBy => (RelationKind::Blocks, true),
            other => (other, false),
        }
    }
}

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

impl FromStr for RelationKind {
    type Err = Diagnostic;

    /// Parse a canonical kind spelling, rejecting anything outside the closed
    /// vocabulary with an [`DiagnosticKind::UnknownKind`] diagnostic. An
    /// unknown kind is never coerced to `related`.
    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s {
            "blocks" => Ok(RelationKind::Blocks),
            "blocked_by" => Ok(RelationKind::BlockedBy),
            "duplicates" => Ok(RelationKind::Duplicates),
            "related" => Ok(RelationKind::Related),
            other => Err(Diagnostic::unknown_kind(
                "kind",
                format!(
                    "unknown relation kind `{other}`; expected one of blocks, blocked_by, duplicates, related"
                ),
            )),
        }
    }
}

/// A stable relationship identifier (`rel_` + 26 Crockford base32 characters,
/// ULID-shaped: a 48-bit millisecond timestamp followed by 80 random bits).
///
/// The id is generated once at creation and survives retargeting, renaming,
/// and export/import, so it is persisted rather than regenerated.
pub type RelationshipId = String;

/// A single typed edge between two issues.
///
/// Field names and invariants come from `data-model.md` §2. The `from`/`to`
/// fields are issue numbers ([`crate::model::Issue::number`], never reused).
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct Relationship {
    /// Stable identifier; survives retarget, rename, export, and import.
    #[serde(default)]
    pub id: RelationshipId,
    /// The issue that declares the edge.
    pub from: IssueRef,
    /// The issue the edge points at.
    pub to: IssueRef,
    /// The relation kind. A persisted edge never carries
    /// [`RelationKind::BlockedBy`] — it is normalized to
    /// [`RelationKind::Blocks`] before storage.
    pub kind: RelationKind,
    /// Human-readable display name, e.g. `blocks #42 Fix flaky test`.
    /// Recomputed from the target title by [`Relationship::refresh_display`];
    /// omitted from the serialized form while empty.
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub display: String,
}

impl Relationship {
    /// Build a relationship with a freshly generated stable id and the
    /// canonical display name for `target_title`.
    pub fn new(
        from: impl Into<IssueRef>,
        to: impl Into<IssueRef>,
        kind: RelationKind,
        target_title: &str,
    ) -> Self {
        let canonical = CanonicalEdge::new(from, to, kind);
        let target_display = canonical
            .to
            .as_number()
            .map_or_else(|| canonical.to.to_string(), |number| number.to_string());
        Self {
            id: generate_relationship_id(),
            from: canonical.from,
            to: canonical.to,
            kind: canonical.kind,
            display: display_name_text(canonical.kind, &target_display, target_title),
        }
    }

    /// Rebuild [`Relationship::display`] from the current kind and the target
    /// issue's title, leaving the stable id untouched.
    pub fn refresh_display(&mut self, target_title: &str) {
        let target_display = self
            .to
            .as_number()
            .map_or_else(|| self.to.to_string(), |number| number.to_string());
        self.display = display_name_text(self.kind, &target_display, target_title);
    }

    /// Refresh the display using the target's human alias.
    pub fn refresh_display_for(&mut self, target_number: u32, target_title: &str) {
        self.display = display_name(self.kind, target_number, target_title);
    }

    /// The canonical form of this edge: the direction convention applied, so a
    /// `blocked_by` edge comes back with swapped endpoints and kind `blocks`,
    /// and a `related` edge comes back in `(min, max)` order.
    pub fn canonical(&self) -> CanonicalEdge {
        CanonicalEdge::new(self.from, self.to, self.kind)
    }
}

/// Whether landing on an edge that already exists is an error, or the
/// idempotent no-op that `data-model.md` §2 requires of a re-applied edit.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum Duplicate {
    /// Re-asserting an edge that already exists is fine. This is the `create`
    /// path: running `tix link A B --type blocks` twice must not fail.
    Allowed,
    /// Landing on a triple another relationship already occupies is an error,
    /// because the edit would leave two stored edges for one relationship.
    /// This is the `edit` path.
    Rejected,
}

/// The human-readable display name for an edge, e.g. `blocks #42 Fix flaky test`.
pub fn display_name(kind: RelationKind, target: u32, target_title: &str) -> String {
    display_name_text(kind, &target.to_string(), target_title)
}

fn display_name_text(kind: RelationKind, target: &str, target_title: &str) -> String {
    let target = if crate::id::is_issue_id(target) {
        target.to_string()
    } else {
        format!("#{target}")
    };
    if target_title.trim().is_empty() {
        format!("{} {target}", kind.as_str())
    } else {
        format!("{} {target} {}", kind.as_str(), target_title.trim())
    }
}

// ---------------------------------------------------------------------------
// T002 — canonical direction convention and inverse normalization
// ---------------------------------------------------------------------------

/// An edge in canonical form: the direction convention already applied.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct CanonicalEdge {
    /// The blocking side for a blocking edge; the source otherwise.
    pub from: IssueRef,
    /// The blocked side for a blocking edge; the target otherwise.
    pub to: IssueRef,
    /// Always [`RelationKind::Blocks`] for a blocking edge, never
    /// [`RelationKind::BlockedBy`].
    pub kind: RelationKind,
}

impl CanonicalEdge {
    /// Apply the direction convention to an authored edge.
    ///
    /// Two kinds need their endpoints rearranged, for different reasons:
    ///
    /// - [`RelationKind::BlockedBy`] **swaps**. It is the inverse spelling of
    ///   a blocking edge, so `A blocked_by B` is stored as `B blocks A`.
    /// - [`RelationKind::Related`] is **order-normalized** to `(min, max)`. It
    ///   is the only non-directional kind, so the endpoint order carries no
    ///   meaning; fixing it makes `1 related 2` and `2 related 1` the same
    ///   stored edge, which is what `data-model.md` §1 requires ("stored
    ///   once; no mirrored edge"). The visible consequence is that an edge
    ///   authored as `2 related 1` displays as `related #1 …`; the orientation
    ///   was arbitrary, so this is a canonical choice, not a loss.
    ///
    /// [`RelationKind::Duplicates`] is directional and is deliberately **not**
    /// reordered — "2 duplicates 1" is not the same claim as "1 duplicates 2".
    pub fn new(from: impl Into<IssueRef>, to: impl Into<IssueRef>, kind: RelationKind) -> Self {
        let from = from.into();
        let to = to.into();
        let (kind, swap) = kind.canonical();
        // Both rearrangements end in a swap; they differ only in *when* they
        // apply. `blocked_by` always swaps, `related` swaps only when that puts
        // the pair in (min, max) order.
        if swap || (!kind.is_directional() && from.key() > to.key()) {
            Self {
                from: to,
                to: from,
                kind,
            }
        } else {
            Self { from, to, kind }
        }
    }

    /// Whether both endpoints resolve to the same issue.
    pub fn is_self_link(self) -> bool {
        self.from == self.to
    }
}

/// Apply the canonical direction convention to an authored edge.
///
/// `A --blocked_by--> B` and `B --blocks--> A` both normalize to the same
/// canonical edge, which is why a pair can never be stored twice.
pub fn normalize(
    from: impl Into<IssueRef>,
    to: impl Into<IssueRef>,
    kind: RelationKind,
) -> CanonicalEdge {
    CanonicalEdge::new(from, to, kind)
}

/// Normalize a batch of authored edges into a deduplicated, deterministically
/// ordered canonical set.
///
/// This is the property that makes `(from, to, kind)` uniqueness testable: two
/// spellings of the same edge collapse to one entry, and the output is sorted
/// so repeated calls on the same input are byte-identical.
pub fn normalize_all<F, T, I>(authored: I) -> Vec<CanonicalEdge>
where
    F: Into<IssueRef>,
    T: Into<IssueRef>,
    I: IntoIterator<Item = (F, T, RelationKind)>,
{
    let mut seen: HashSet<CanonicalEdge> = HashSet::new();
    for (from, to, kind) in authored {
        seen.insert(CanonicalEdge::new(from, to, kind));
    }
    let mut edges: Vec<CanonicalEdge> = seen.into_iter().collect();
    edges.sort_unstable();
    edges
}

// ---------------------------------------------------------------------------
// T004 — diagnostics and the validation result
// ---------------------------------------------------------------------------

/// The closed set of relationship validation diagnostics.
///
/// The names are authoritative and come from
/// `contracts/relationship-service.md` §3.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum DiagnosticKind {
    /// `from == to`; always rejected.
    SelfLink,
    /// A selector resolved to no issue.
    MissingTarget,
    /// A numeric alias resolved to more than one issue.
    AmbiguousTarget,
    /// More than one issue claims the same canonical id.
    DuplicateIdentity,
    /// A stored edge contradicts the canonical direction for the same pair.
    ConflictingEdge,
    /// An edge would close a directed cycle.
    Cycle,
    /// A relation kind outside the closed vocabulary.
    UnknownKind,
    /// An edit or remove named a relationship id that does not exist.
    UnknownRelation,
    /// Legacy `links:` frontmatter key is still present.
    RetiredLinksKey,
}

impl DiagnosticKind {
    /// The canonical snake_case name used in CLI, TUI, and MCP output.
    pub fn as_str(self) -> &'static str {
        match self {
            DiagnosticKind::SelfLink => "self_link",
            DiagnosticKind::MissingTarget => "missing_target",
            DiagnosticKind::AmbiguousTarget => "ambiguous_target",
            DiagnosticKind::DuplicateIdentity => "duplicate_identity",
            DiagnosticKind::ConflictingEdge => "conflicting_edge",
            DiagnosticKind::Cycle => "cycle",
            DiagnosticKind::UnknownKind => "unknown_kind",
            DiagnosticKind::UnknownRelation => "unknown_relation",
            DiagnosticKind::RetiredLinksKey => "retired_links_key",
        }
    }
}

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

/// One field-aware relationship diagnostic.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Diagnostic {
    /// Which rule failed.
    pub kind: DiagnosticKind,
    /// The offending field or selector, e.g. `to`, `kind`, or `links`.
    pub field: String,
    /// Human-readable explanation, safe to print in CLI output, the TUI, and
    /// lint.
    pub message: String,
    /// The issue this diagnostic is **about**, when there is exactly one.
    ///
    /// Added for WP06 T025. `tix lint` has to attribute a diagnostic to a *file*,
    /// and a file is found by issue number — so without this the only route is to
    /// read the number back out of `message`, and the message is prose whose shape
    /// is not a contract. It already is not one: `self_link` opens with `#1 while
    /// `missing_target` opens with `issue #1`, and `conflicting_edge` names two
    /// issues. A consumer that assumed either shape would work until the wording
    /// changed, and would then attribute findings to the wrong file.
    ///
    /// `None` where the diagnostic is genuinely not about one issue.
    ///
    /// Which is not the same as "not a kind that has a subject". An
    /// [`DiagnosticKind::UnknownKind`] naming a bare selector and an
    /// [`DiagnosticKind::UnknownRelation`] naming a relationship id are always
    /// `None` — but [`DiagnosticKind::ConflictingEdge`] and
    /// [`DiagnosticKind::Cycle`] are `Some` when they come from
    /// [`RelationshipGraph::validate_snapshot`] and `None` when they come from
    /// [`RelationshipGraph::validate_authored`], which builds them with
    /// [`Diagnostic::new`].
    ///
    /// That asymmetry is recorded rather than papered over, because the field
    /// exists to be a contract and a doc claiming more than the code does is worse
    /// than no doc. Only `validate_snapshot` reaches lint, so nothing observable
    /// depends on the untagged half today; if a caller starts reading `issue` on a
    /// write-path diagnostic, that is the moment to tag those three sites.
    pub issue: Option<u32>,
    /// The exact source file when a number alias is not sufficient to identify it.
    ///
    /// Duplicate human numbers make issue-number attribution ambiguous. Carrying
    /// the filename keeps lint pointed at the file that actually holds the bad
    /// endpoint rather than whichever duplicate happened to win a map lookup.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub source_file: Option<String>,
}

impl Diagnostic {
    /// Build a diagnostic of any kind.
    pub fn new(kind: DiagnosticKind, field: impl Into<String>, message: impl Into<String>) -> Self {
        Self {
            kind,
            field: field.into(),
            message: message.into(),
            issue: None,
            source_file: None,
        }
    }

    /// A diagnostic that is about one specific issue — the form lint needs, since
    /// it has to name the file.
    pub fn about(
        issue: u32,
        kind: DiagnosticKind,
        field: impl Into<String>,
        message: impl Into<String>,
    ) -> Self {
        Self {
            kind,
            field: field.into(),
            message: message.into(),
            issue: Some(issue),
            source_file: None,
        }
    }

    /// Attribute this diagnostic to its exact source file.
    #[must_use]
    pub fn with_source_file(mut self, filename: impl Into<String>) -> Self {
        self.source_file = Some(filename.into());
        self
    }

    /// A [`DiagnosticKind::SelfLink`] for the given issue.
    pub fn self_link(issue: u32) -> Self {
        Self::about(
            issue,
            DiagnosticKind::SelfLink,
            "to",
            format!("#{issue} cannot block itself: a self-link is not a valid relationship"),
        )
    }

    /// A [`DiagnosticKind::MissingTarget`] for an unresolvable selector.
    pub fn missing_target(issue: u32, selector: impl fmt::Display) -> Self {
        Self::about(
            issue,
            DiagnosticKind::MissingTarget,
            "to",
            format!("issue #{issue} references `{selector}`, which resolves to no issue"),
        )
    }

    /// A [`DiagnosticKind::UnknownKind`] for a kind outside the vocabulary.
    pub fn unknown_kind(field: impl Into<String>, message: impl Into<String>) -> Self {
        Self::new(DiagnosticKind::UnknownKind, field, message)
    }

    /// A [`DiagnosticKind::UnknownRelation`] for a relationship id with no match.
    pub fn unknown_relation(id: &str) -> Self {
        Self::new(
            DiagnosticKind::UnknownRelation,
            "id",
            format!("no relationship with id `{id}`"),
        )
    }
}

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

fn alias_diagnostic(
    issue: u32,
    filename: &str,
    field: &str,
    reference: IssueRef,
    error: &crate::id::AliasError,
) -> Diagnostic {
    let (kind, message) = match error {
        crate::id::AliasError::Missing(_) => (
            DiagnosticKind::MissingTarget,
            format!("{field} `{reference}` resolves to no issue"),
        ),
        crate::id::AliasError::Ambiguous { candidates, .. } => (
            DiagnosticKind::AmbiguousTarget,
            format!(
                "{field} `{reference}` is ambiguous: {}",
                candidates
                    .iter()
                    .map(ToString::to_string)
                    .collect::<Vec<_>>()
                    .join(", ")
            ),
        ),
        crate::id::AliasError::DuplicateId { .. } => (
            DiagnosticKind::DuplicateIdentity,
            format!("{field} `{reference}` shares a canonical id with another issue"),
        ),
    };
    Diagnostic::about(issue, kind, field, message).with_source_file(filename)
}

fn duplicate_identity_diagnostics(aliases: &AliasIndex) -> Vec<Diagnostic> {
    aliases
        .duplicate_records()
        .iter()
        .map(|record| {
            let files = aliases
                .duplicate_id_files()
                .get(&record.id)
                .map(|files| files.join(", "))
                .unwrap_or_default();
            Diagnostic::about(
                record.number,
                DiagnosticKind::DuplicateIdentity,
                "id",
                format!(
                    "canonical id `{}` is claimed by {files}; ids must be unique",
                    record.id
                ),
            )
            .with_source_file(&record.filename)
        })
        .collect()
}

/// The per-field diagnostic set returned by every validation call.
///
/// It is a **value**, never an `Err`: `tix lint` needs a value even when
/// nothing is wrong, and a read-only sweep must not fail fast (FR-001, C-004).
#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
pub struct RelationshipValidationResult {
    /// Every diagnostic found, in a deterministic order.
    pub errors: Vec<Diagnostic>,
}

impl RelationshipValidationResult {
    /// A result carrying no diagnostics.
    pub fn clean() -> Self {
        Self::default()
    }

    /// A result carrying one diagnostic.
    pub fn with(diagnostic: Diagnostic) -> Self {
        Self {
            errors: vec![diagnostic],
        }
    }

    /// Whether no rule failed.
    pub fn is_clean(&self) -> bool {
        self.errors.is_empty()
    }

    /// Whether a mutation must be rejected.
    ///
    /// Every diagnostic kind is blocking for a write: a partial or
    /// reinterpreted edge is worse than a refused one, and a legacy `links:`
    /// key must never be silently dropped by a rewrite (C-001, SC-005).
    pub fn blocking(&self) -> bool {
        !self.errors.is_empty()
    }

    /// Whether any diagnostic of `kind` was reported.
    pub fn has(&self, kind: DiagnosticKind) -> bool {
        self.errors.iter().any(|d| d.kind == kind)
    }

    /// Fold `other` into this result, keeping the combined order deterministic.
    pub fn merge(&mut self, other: Self) {
        self.errors.extend(other.errors);
    }

    /// Sort diagnostics by `(kind, field, message)` so repeated sweeps over the
    /// same snapshot are byte-comparable across surfaces.
    pub fn sort_diagnostics(&mut self) {
        self.errors
            .sort_by(|a, b| (a.kind, &a.field, &a.message).cmp(&(b.kind, &b.field, &b.message)));
    }
}

// ---------------------------------------------------------------------------
// T003 — the in-memory graph
// ---------------------------------------------------------------------------

/// The minimal projection of an issue that the relationship service needs.
///
/// This is deliberately *not* [`crate::model::Issue`]: the issue model gains
/// its typed relationship field in a later work package, and keeping the
/// service on a narrow view means the graph stays filesystem-free and
/// testable with a plain in-memory list.
#[derive(Debug, Clone, Copy)]
pub struct IssueView<'a> {
    /// The canonical id, when this issue has one.
    pub id: Option<&'a str>,
    /// The store-relative filename, used as an input alias.
    pub filename: &'a str,
    /// The stable issue number (`Issue::number`, never reused).
    pub number: u32,
    /// The issue title, used to build display names.
    pub title: &'a str,
    /// The board column the issue sits in, compared against `done_column`.
    pub status: &'a str,
    /// The issue's stored relationships, in authored file order.
    pub relationships: &'a [Relationship],
    /// Whether the source frontmatter still carries a legacy `links:` key.
    /// The key is reported as a validation result and never read as typed data
    /// (C-001); this flag is how the storage layer signals it.
    pub has_retired_links_key: bool,
    /// The issue's decomposition parent, as an issue number.
    ///
    /// Present on the relationship service's view so the **hierarchy** service
    /// ([`crate::hierarchy`]) reads the same in-memory projection rather than a
    /// parallel one built by each caller. Two projections of one issue type is how
    /// two services end up disagreeing about the same snapshot — the divergence
    /// `contracts/surface-parity.md` §3 exists to prevent.
    ///
    /// Not read by the relationship graph. A parent is a decomposition and a
    /// `blocks` edge is a scheduling dependency; they are separate fields and are
    /// never combined (C-007).
    pub parent: Option<IssueRef>,
}

impl<'a> IssueView<'a> {
    /// Build an issue view without the retired-key flag.
    pub fn new(
        number: u32,
        title: &'a str,
        status: &'a str,
        relationships: &'a [Relationship],
    ) -> Self {
        Self {
            id: None,
            filename: "",
            number,
            title,
            status,
            relationships,
            has_retired_links_key: false,
            parent: None,
        }
    }

    /// Add the canonical identity and filename used by graph alias resolution.
    pub fn with_identity(mut self, id: Option<&'a str>, filename: &'a str) -> Self {
        self.id = id.map(|id| id.trim()).filter(|id| !id.is_empty());
        self.filename = filename;
        self
    }

    /// Build an issue view, flagging a legacy `links:` key.
    pub fn with_retired_links_key(mut self, flagged: bool) -> Self {
        self.has_retired_links_key = flagged;
        self
    }

    /// Build an issue view carrying a decomposition parent.
    pub fn with_parent(mut self, parent: Option<IssueRef>) -> Self {
        self.parent = parent;
        self
    }

    /// The canonical graph reference for this issue.
    #[must_use]
    pub fn graph_ref(&self) -> IssueRef {
        canonical_ref(self)
    }
}

// ---------------------------------------------------------------------------
// The hierarchy service reads the same view (WP01's `HierarchyNode`).
// ---------------------------------------------------------------------------

impl crate::hierarchy::HierarchyNode for IssueView<'_> {
    fn number(&self) -> u32 {
        self.number
    }
    fn title(&self) -> &str {
        self.title
    }
    fn status(&self) -> &str {
        self.status
    }
    fn canonical_id(&self) -> Option<&str> {
        self.id
    }
    fn filename(&self) -> Option<&str> {
        Some(self.filename)
    }
    fn parent_ref(&self) -> Option<&IssueRef> {
        self.parent.as_ref()
    }
    fn parent_number(&self) -> Option<u32> {
        self.parent.as_ref().and_then(IssueRef::as_number)
    }
}

impl IdentityNode for IssueView<'_> {
    fn canonical_id(&self) -> Option<&str> {
        self.id
    }

    fn issue_number(&self) -> u32 {
        self.number
    }

    fn issue_filename(&self) -> &str {
        self.filename
    }

    fn issue_title(&self) -> &str {
        self.title
    }
}

/// One node of a dependency chain.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ChainNode {
    /// The issue number.
    pub number: u32,
    /// The issue title at read time.
    pub title: String,
}

impl ChainNode {
    /// Build a chain node.
    pub fn new(number: u32, title: impl Into<String>) -> Self {
        Self {
            number,
            title: title.into(),
        }
    }
}

/// The transitive blocker chain of an issue (`data-model.md` §3).
#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
pub struct DependencyChain {
    /// The issue the chain was requested for.
    pub root: u32,
    /// Ordered node sequences from the root upward toward its blockers.
    pub paths: Vec<Vec<ChainNode>>,
    /// Set when the traversal bound was reached, so display can say so rather
    /// than silently truncating.
    pub truncated: bool,
}

impl DependencyChain {
    /// The distinct issues in the chain, in first-seen order.
    pub fn nodes(&self) -> Vec<&ChainNode> {
        let mut seen = HashSet::new();
        self.paths
            .iter()
            .flatten()
            .filter(|n| seen.insert(n.number))
            .collect()
    }
}

/// The derived blocked condition surfaced by every surface (`data-model.md` §4).
#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
pub struct BlockedState {
    /// At least one open inbound `blocks` edge exists.
    pub is_blocked: bool,
    /// The open blockers, ordered by issue number.
    pub blockers: Vec<ChainNode>,
    /// The human-readable explanation reused verbatim by the move warning and
    /// by detail rendering.
    pub reason: String,
}

/// How many nodes a single chain traversal will visit before setting
/// [`DependencyChain::truncated`]. A defensive display guard, not a graph bound.
///
/// Public because a surface that reports truncation has to name the bound it
/// hit, and a literal copy of this number in a printer is a number that drifts
/// the moment this one changes (WP03's `tix chain` truncation note).
pub const MAX_CHAIN_NODES: usize = 1_000;

/// The in-memory relationship graph: one adjacency build, every derived read.
///
/// The struct is built once per read from an in-memory issue set — no
/// filesystem access — and answers `relationships_for`, `blocks`,
/// `blocked_by`, `duplicates_of`, `related_to`, `dependency_chain`,
/// `blocked_state`, and `validate_snapshot` from the same indices.
#[derive(Debug)]
pub struct RelationshipGraph<'a> {
    issues: HashMap<IssueRef, IssueView<'a>>,
    aliases: AliasIndex,
    alias_diagnostics: Vec<Diagnostic>,
    refs_by_number: HashMap<u32, Vec<IssueRef>>,
    numbers_by_ref: HashMap<IssueRef, u32>,
    issues_by_number: Vec<u32>,
    /// Stored relationships, sorted by `(kind, target, from)`; every accessor
    /// slices this order so output is byte-comparable across surfaces.
    edges: Vec<Relationship>,
    by_id: HashMap<RelationshipId, usize>,
    /// Relationship id -> exact file that stores the row.
    edge_owners: HashMap<RelationshipId, String>,
    /// Indices into `edges` for every edge touching an issue, ascending.
    by_issue: HashMap<IssueRef, Vec<usize>>,
    /// `blocks` adjacency only. `duplicates` and `related` never appear.
    blocks_out: HashMap<IssueRef, Vec<IssueRef>>,
    blocks_in: HashMap<IssueRef, Vec<IssueRef>>,
    blocks_out_numbers: HashMap<u32, Vec<u32>>,
    blocks_in_numbers: HashMap<u32, Vec<u32>>,
    done_column: String,
    /// How many times [`RelationshipGraph::validate_snapshot`] has run on this
    /// graph.
    ///
    /// Instrumentation, and the **only** honest witness for NFR-001's "one pass".
    /// A timing ratio detects a change in the scaling *exponent* — quadratic vs
    /// linear — so it cannot see a second pass, which doubles both measurements and
    /// leaves their ratio untouched. Adding a redundant `validate_cycles()` call to
    /// `validate_snapshot` kept the entire suite green until this counter existed.
    ///
    /// An atomic so the graph stays `Sync`; the cost is one relaxed increment per
    /// call, not per edge, so it does not affect the measurement it exists to
    /// support.
    validation_passes: std::sync::atomic::AtomicUsize,
}

impl Clone for RelationshipGraph<'_> {
    /// A copy starts its own count. Cloning a graph is building a *new* one, so
    /// inheriting the source's pass count would make the instrument lie.
    fn clone(&self) -> Self {
        Self {
            issues: self.issues.clone(),
            aliases: self.aliases.clone(),
            alias_diagnostics: self.alias_diagnostics.clone(),
            refs_by_number: self.refs_by_number.clone(),
            numbers_by_ref: self.numbers_by_ref.clone(),
            issues_by_number: self.issues_by_number.clone(),
            edges: self.edges.clone(),
            by_id: self.by_id.clone(),
            edge_owners: self.edge_owners.clone(),
            by_issue: self.by_issue.clone(),
            blocks_out: self.blocks_out.clone(),
            blocks_in: self.blocks_in.clone(),
            blocks_out_numbers: self.blocks_out_numbers.clone(),
            blocks_in_numbers: self.blocks_in_numbers.clone(),
            done_column: self.done_column.clone(),
            validation_passes: std::sync::atomic::AtomicUsize::new(0),
        }
    }
}

impl<'a> RelationshipGraph<'a> {
    /// How many validation passes this graph has run. See
    /// [`RelationshipGraph::validation_passes`] for why this exists.
    pub fn validation_passes(&self) -> usize {
        self.validation_passes
            .load(std::sync::atomic::Ordering::Relaxed)
    }

    /// Build the graph from an in-memory issue set.
    ///
    /// `done_column` is the board's configured completion column, used by the
    /// resolution predicate in [`RelationshipGraph::blocked_state`]. Pass the
    /// configured value (`BoardConfiguration::effective_done_column`), never a
    /// hard-coded `"done"`.
    ///
    /// An empty `done_column` is accepted and means *no column marks
    /// completion*, so nothing is treated as done. `Config` validation keeps
    /// `columns` non-empty in practice, but a caller that passes `""` must not
    /// silently get "an empty status counts as completed".
    pub fn new(issues: &[IssueView<'a>], done_column: &str) -> Self {
        let mut issues_by_number: Vec<u32> = issues.iter().map(|i| i.number).collect();
        issues_by_number.sort_unstable();
        let mut refs_by_number: HashMap<u32, Vec<IssueRef>> = HashMap::new();
        let mut numbers_by_ref = HashMap::new();
        let mut by_ref = HashMap::new();
        for view in issues {
            let reference = view.graph_ref();
            refs_by_number
                .entry(view.number)
                .or_default()
                .push(reference);
            numbers_by_ref.insert(reference, view.number);
            by_ref.insert(reference, *view);
        }

        let aliases = AliasIndex::build(issues);
        let mut graph = Self {
            issues: by_ref,
            aliases,
            alias_diagnostics: Vec::new(),
            refs_by_number,
            numbers_by_ref,
            issues_by_number,
            edges: Vec::new(),
            by_id: HashMap::new(),
            edge_owners: HashMap::new(),
            by_issue: HashMap::new(),
            blocks_out: HashMap::new(),
            blocks_in: HashMap::new(),
            blocks_out_numbers: HashMap::new(),
            blocks_in_numbers: HashMap::new(),
            done_column: done_column.to_string(),
            validation_passes: std::sync::atomic::AtomicUsize::new(0),
        };
        graph.rebuild_edges();
        graph
    }

    fn reference_for_number(&self, number: u32) -> Option<IssueRef> {
        match self.refs_by_number.get(&number)?.as_slice() {
            [one] => Some(*one),
            _ => None,
        }
    }

    fn number_for_reference(&self, reference: IssueRef) -> Option<u32> {
        self.numbers_by_ref.get(&reference).copied()
    }

    /// Pair orientation used only for the "one kind per pair" rule.
    ///
    /// Canonical storage of `related` is ordered by issue id. People still think
    /// of a non-directional pair in number order, so conflict detection uses that
    /// orientation: `3 blocks 1` and `1 related 3` are not one directed pair,
    /// while `1 blocks 2` and `1 related 2` still conflict. Canonical ids remain
    /// the endpoint identity throughout; unequal numbers are not assumed unique.
    fn conflict_key(&self, edge: CanonicalEdge) -> (IssueRef, IssueRef) {
        if edge.kind != RelationKind::Related || edge.from == edge.to {
            return (edge.from, edge.to);
        }
        let from_number = self.number_for_reference(edge.from);
        let to_number = self.number_for_reference(edge.to);
        if from_number.is_some_and(|from| to_number.is_some_and(|to| from > to)) {
            (edge.to, edge.from)
        } else {
            (edge.from, edge.to)
        }
    }

    /// Re-derive the edge set and every index from the issue views.
    ///
    /// Stored edges are normalized on ingest, so a hand-edited file that
    /// persisted the `blocked_by` spelling still contributes the correct
    /// `blocks` adjacency instead of silently dropping out of blocked state.
    ///
    /// A relationship's own `from` is authoritative. It is deliberately *not*
    /// overwritten with the owning issue's number: an edge authored as
    /// `A blocked_by B` legitimately points at `A` from `B`'s side, so forcing
    /// the owner would silently rewrite a normalized edge into a self-link.
    fn rebuild_edges(&mut self) {
        let mut edges: Vec<Relationship> = Vec::new();
        self.alias_diagnostics = duplicate_identity_diagnostics(&self.aliases);
        self.edge_owners.clear();
        let mut references: Vec<IssueRef> = self.issues.keys().copied().collect();
        references.sort_unstable();
        for reference in references {
            let view = self.issues[&reference];
            for rel in view.relationships {
                let mut stored = rel.clone();
                self.edge_owners
                    .insert(stored.id.clone(), view.filename.to_string());
                let owner = self.number_for_reference(reference).unwrap_or_default();
                stored.from = match self.aliases.resolve(&stored.from) {
                    Ok(resolved) => resolved,
                    Err(error) => {
                        if !matches!(&error, crate::id::AliasError::Missing(_)) {
                            self.alias_diagnostics.push(alias_diagnostic(
                                owner,
                                view.filename,
                                "relationships.from",
                                stored.from,
                                &error,
                            ));
                        }
                        stored.from
                    }
                };
                stored.to = match self.aliases.resolve(&stored.to) {
                    Ok(resolved) => resolved,
                    Err(error) => {
                        if !matches!(&error, crate::id::AliasError::Missing(_)) {
                            self.alias_diagnostics.push(alias_diagnostic(
                                owner,
                                view.filename,
                                "relationships.to",
                                stored.to,
                                &error,
                            ));
                        }
                        stored.to
                    }
                };
                let canonical = stored.canonical();
                stored.from = canonical.from;
                stored.to = canonical.to;
                stored.kind = canonical.kind;
                // Refresh the display from the target's *current* title. The
                // persisted string is a cache of a title that may since have
                // been renamed, and every surface renders this field, so a
                // stale value would be user-visible (review R1). A dangling
                // edge keeps its persisted display, since there is no title to
                // rebuild it from.
                if let Some(target) = self.issues.get(&stored.to) {
                    let target_number = self.number_for_reference(stored.to).unwrap_or_default();
                    stored.refresh_display_for(target_number, target.title);
                }
                edges.push(stored);
            }
        }

        // Deterministic order: (kind, target, from). Sorting here means every
        // index built below inherits it, so no accessor has to sort again.
        edges.sort_by(|a, b| (a.kind, a.to, a.from, &a.id).cmp(&(b.kind, b.to, b.from, &b.id)));

        self.by_id = edges
            .iter()
            .enumerate()
            .map(|(i, e)| (e.id.clone(), i))
            .collect();
        self.by_issue = HashMap::new();
        self.blocks_out = HashMap::new();
        self.blocks_in = HashMap::new();
        self.blocks_out_numbers = HashMap::new();
        self.blocks_in_numbers = HashMap::new();

        for (i, edge) in edges.iter().enumerate() {
            // Register each edge once per *distinct* endpoint. A self-link has
            // one endpoint, so pushing both would report it twice and make
            // `relationships_for(..).len()` disagree with `edge_count()`
            // (review R2).
            self.by_issue.entry(edge.from).or_default().push(i);
            if edge.to != edge.from {
                self.by_issue.entry(edge.to).or_default().push(i);
            }
            // A self-link is invalid data, reported by `validate_snapshot` as
            // `self_link`. It stays visible through `relationships_for` so the
            // user can find and fix it, but it is kept out of the graph
            // adjacency: it is not a real edge, and admitting it would make an
            // issue its own blocker (review R3).
            if edge.kind == RelationKind::Blocks && edge.from != edge.to {
                self.blocks_out.entry(edge.from).or_default().push(edge.to);
                self.blocks_in.entry(edge.to).or_default().push(edge.from);
            }
        }

        // Redundant rows are *kept* in `edges` so no stored relationship id
        // silently stops resolving, but the adjacency is a set and must not
        // repeat a neighbour. A hand-edited file can hold two spellings of one
        // association (normalization makes them the same canonical triple);
        // dropping a row here would destroy an id the user still holds, and
        // `validate_edit` on it would report a bare `unknown_relation`
        // indistinguishable from a typo (review round 3, finding A). The
        // redundancy is collapsed on the read side instead — see
        // `related_to` — where it costs the user nothing.
        for adjacency in [&mut self.blocks_out, &mut self.blocks_in] {
            for targets in adjacency.values_mut() {
                targets.sort_unstable();
                targets.dedup();
            }
        }

        for (from, targets) in &self.blocks_out {
            let Some(from_number) = self.number_for_reference(*from) else {
                continue;
            };
            let numbers: Vec<u32> = targets
                .iter()
                .filter_map(|target| self.number_for_reference(*target))
                .collect();
            self.blocks_out_numbers.insert(from_number, numbers);
        }
        for (to, sources) in &self.blocks_in {
            let Some(to_number) = self.number_for_reference(*to) else {
                continue;
            };
            let numbers: Vec<u32> = sources
                .iter()
                .filter_map(|source| self.number_for_reference(*source))
                .collect();
            self.blocks_in_numbers.insert(to_number, numbers);
        }

        self.edges = edges;
    }

    /// The configured completion column used by the resolution predicate.
    pub fn done_column(&self) -> &str {
        &self.done_column
    }

    /// How many issues are in the graph.
    pub fn issue_count(&self) -> usize {
        self.issues_by_number.len()
    }

    /// How many records the one alias index owns.
    #[must_use]
    pub fn identity_index_size(&self) -> usize {
        self.aliases.len()
    }

    /// How many issue records the single alias-index pass examined.
    #[must_use]
    pub fn identity_nodes_scanned(&self) -> usize {
        self.aliases.scanned_nodes()
    }

    /// How many stored edges are in the graph.
    pub fn edge_count(&self) -> usize {
        self.edges.len()
    }

    /// The issue numbers, ascending.
    pub fn issue_numbers(&self) -> &[u32] {
        &self.issues_by_number
    }

    /// Whether `number` resolves to an issue in the graph.
    pub fn has_issue(&self, number: u32) -> bool {
        self.reference_for_number(number).is_some()
    }

    /// The stored relationship with this stable id, if any.
    pub fn find_relationship(&self, id: &str) -> Option<&Relationship> {
        self.by_id.get(id).map(|i| &self.edges[*i])
    }

    /// The stored relationship for this canonical `(from, to, kind)`, if any.
    ///
    /// **This is the service's answer to "are these the same relationship?"**
    /// A write path must use it rather than comparing endpoints itself, because
    /// the comparison is domain logic and getting it wrong silently breaks
    /// idempotency. `tix link 1 2 --type blocked_by` and `tix link 2 1
    /// --type blocks` name one edge; a caller comparing the *authored*
    /// endpoints would see two and append a second row.
    ///
    /// `from`, `to` and `kind` are the **authored** values. Canonicalization
    /// happens here, so the caller cannot get the direction convention wrong:
    ///
    /// - `blocked_by` is normalized to the equivalent `blocks` edge with the
    ///   endpoints swapped;
    /// - `related` is order-normalized, so either orientation finds the row.
    ///
    /// When redundant rows exist for one canonical triple — a hand-edited file
    /// can hold two spellings of one association — the lowest-id row is
    /// returned, so the answer is stable across builds.
    pub fn find_canonical(&self, from: u32, to: u32, kind: RelationKind) -> Option<&Relationship> {
        let from = self.reference_for_number(from)?;
        let to = self.reference_for_number(to)?;
        let canonical = CanonicalEdge::new(from, to, kind);
        // Scoped to the canonical source's edge list rather than the whole edge
        // set: the matching row always has `from == canonical.from`, so this is
        // a short list and stays cheap on the write path.
        self.by_issue
            .get(&canonical.from)?
            .iter()
            .map(|i| &self.edges[*i])
            .find(|edge| edge.canonical() == canonical)
    }

    /// Every stored relationship, in deterministic order.
    pub fn all_relationships(&self) -> &[Relationship] {
        &self.edges
    }

    /// Every relationship touching `number` from either endpoint, in
    /// deterministic `(kind, target)` order.
    ///
    /// An unknown issue yields an empty vector rather than an error; callers
    /// that need an `unknown_issue` signal check
    /// [`RelationshipGraph::has_issue`].
    pub fn relationships_for(&self, number: u32) -> Vec<&Relationship> {
        match self
            .reference_for_number(number)
            .and_then(|reference| self.by_issue.get(&reference))
        {
            Some(indices) => indices.iter().map(|i| &self.edges[*i]).collect(),
            None => Vec::new(),
        }
    }

    /// Relationships authored by `number` with the given kind.
    pub fn relationships_of_kind(&self, number: u32, kind: RelationKind) -> Vec<&Relationship> {
        self.relationships_for(number)
            .into_iter()
            .filter(|r| r.kind == kind)
            .collect()
    }

    /// Issues `number` blocks, ascending.
    pub fn blocks(&self, number: u32) -> &[u32] {
        self.blocks_out_numbers
            .get(&number)
            .map(Vec::as_slice)
            .unwrap_or(&[])
    }

    /// Issues blocking `number`, ascending.
    ///
    /// This is the raw inbound adjacency. It is **not** the open-blocker set —
    /// use [`RelationshipGraph::blocked_state`] for that, which applies the
    /// resolution predicate.
    pub fn blocked_by(&self, number: u32) -> &[u32] {
        self.blocks_in_numbers
            .get(&number)
            .map(Vec::as_slice)
            .unwrap_or(&[])
    }

    /// Issues duplicated *by* `number`, ascending.
    ///
    /// `duplicates` is **directional** (`data-model.md` section 1), so this is
    /// deliberately one-directional: it reports the targets of the edges
    /// `number` declares and ignores edges that merely point *at* `number`. On
    /// a stored `2 duplicates 1` edge the answer is therefore empty — the claim
    /// is "2 duplicates 1", not "1 duplicates 2". Reading `r.to` over every
    /// edge touching the subject instead reports the subject itself (P4).
    pub fn duplicates_of(&self, number: u32) -> Vec<u32> {
        let mut targets: Vec<u32> = self
            .relationships_of_kind(number, RelationKind::Duplicates)
            .into_iter()
            .filter(|edge| {
                self.reference_for_number(number)
                    .is_some_and(|reference| edge.from == reference)
            })
            .filter_map(|edge| self.number_for_reference(edge.to))
            .collect();
        targets.sort_unstable();
        targets
    }

    /// Issues associated with `number` by a `related` edge, ascending.
    ///
    /// `related` is the one **non-directional** kind, so both endpoints are
    /// equivalent. `relationships_for` returns edges from both sides, so the
    /// other side of each edge is projected explicitly — reading `r.to`
    /// directly reports the subject itself for an edge authored from the far
    /// side (P3).
    ///
    /// Redundant rows collapse *here* rather than in the stored edge set: two
    /// spellings of one association are one relationship to the user, and
    /// discarding a row at build time would silently invalidate an id the user
    /// still holds (round 3, finding A).
    pub fn related_to(&self, number: u32) -> Vec<u32> {
        let Some(reference) = self.reference_for_number(number) else {
            return Vec::new();
        };
        let mut others: Vec<u32> = self
            .relationships_of_kind(number, RelationKind::Related)
            .into_iter()
            .filter_map(|edge| {
                let other = if edge.from == reference {
                    edge.to
                } else {
                    edge.from
                };
                self.number_for_reference(other)
            })
            .collect();
        others.sort_unstable();
        others.dedup();
        others
    }

    // -----------------------------------------------------------------------
    // T005 — derived reads
    // -----------------------------------------------------------------------

    /// The open blockers of `number`, per the resolution predicate.
    ///
    /// An inbound `blocks` edge counts **iff** the blocker is a *different*
    /// existing issue and its status is not the configured `done_column`. A
    /// dangling edge is excluded here (validation reports it as
    /// `missing_target`) so invalid data cannot permanently freeze an issue.
    pub fn open_blockers(&self, number: u32) -> Vec<ChainNode> {
        self.blocked_by(number)
            .iter()
            .filter(|blocker| self.is_open_blocker(number, **blocker))
            .map(|blocker| self.chain_node(*blocker))
            .collect()
    }

    /// The single resolution predicate, and the whole of it.
    ///
    /// `contracts/relationship-service.md` §7 makes this function the sole
    /// owner of the rule, so every precondition is stated here rather than
    /// delegated to the adjacency build. Three things are not an open blocker:
    ///
    /// 1. a missing blocker — invalid data, diagnosed as `missing_target`;
    /// 2. a blocker in the board's configured `done_column` — it is finished;
    /// 3. the subject itself — an issue is never blocked by itself.
    ///
    /// On (3): `rebuild_edges` already keeps self-links out of the adjacency,
    /// so that branch is **unreachable today** and is covered by no passing
    /// test. It is retained deliberately rather than as a second live layer —
    /// a safety rule that states its own preconditions stays correct if the
    /// build step is ever changed, and the cost is one comparison. The test
    /// `the_blocked_adjacency_never_contains_the_subject` pins the invariant
    /// that makes it unreachable, so a regression there fails a test rather
    /// than silently leaning on this branch.
    fn is_open_blocker(&self, subject: u32, blocker: u32) -> bool {
        if blocker == subject {
            return false;
        }
        let Some(blocker_reference) = self.reference_for_number(blocker) else {
            return false;
        };
        let Some(blocker) = self.issues.get(&blocker_reference) else {
            return false;
        };
        // An unconfigured completion column must fail *closed*: with no
        // `done_column` no column means "finished", so nothing is completed
        // and every real blocker keeps blocking. Comparing the status against
        // an empty string instead would treat a blocker with an empty status
        // as done, which is the dangerous direction for a guard that gates a
        // confirmation prompt.
        self.done_column.is_empty() || blocker.status != self.done_column
    }

    /// The derived blocked state for `number`.
    ///
    /// `reason` is the text the move warning and the detail view both display,
    /// so the two surfaces cannot drift.
    pub fn blocked_state(&self, number: u32) -> BlockedState {
        let blockers = self.open_blockers(number);
        let is_blocked = !blockers.is_empty();
        BlockedState {
            is_blocked,
            reason: if is_blocked {
                blocked_reason(&blockers)
            } else {
                String::new()
            },
            blockers,
        }
    }

    /// The transitive dependency chain of `root`, walking **outbound** `blocks`
    /// edges: the issues this one blocks, and what they block in turn.
    ///
    /// Direction note: `data-model.md` §9 specifies the chain is derived "from
    /// outbound `blocks` edges", so this follows `blocks_out` and answers "what
    /// does this issue hold up?". The opposite question — "what blocks this
    /// issue?" — is what the move guard needs, and is answered by
    /// [`RelationshipGraph::open_blockers`] over the inbound adjacency.
    ///
    /// The traversal is iterative and marks visited nodes, so a hand-edited
    /// cyclic file terminates instead of hanging the TUI.
    pub fn dependency_chain(&self, root: u32) -> DependencyChain {
        let mut chain = DependencyChain {
            root,
            paths: Vec::new(),
            truncated: false,
        };
        if !self.has_issue(root) {
            return chain;
        }

        let mut visited_nodes = 1usize;
        let mut path = vec![self.chain_node(root)];
        self.walk_downstream(root, &mut path, &mut chain.paths, &mut visited_nodes);
        chain.truncated = visited_nodes >= MAX_CHAIN_NODES;
        chain
    }

    /// Iterative outbound walk, pushing one path per leaf of the closure.
    fn walk_downstream(
        &self,
        node: u32,
        path: &mut Vec<ChainNode>,
        paths: &mut Vec<Vec<ChainNode>>,
        visited_nodes: &mut usize,
    ) {
        let downstream = self.blocks(node);
        if downstream.is_empty() {
            return;
        }
        // Deduplicate: the same node reached through two paths must not fork
        // the walk twice.
        let mut unique: Vec<u32> = Vec::new();
        for target in downstream {
            if !unique.contains(target) {
                unique.push(*target);
            }
        }
        for target in unique {
            if *visited_nodes >= MAX_CHAIN_NODES {
                return;
            }
            *visited_nodes += 1;
            if path.iter().any(|n| n.number == target) {
                // Defensive only: write-time cycle rejection makes this
                // unreachable for a well-formed graph.
                continue;
            }
            path.push(self.chain_node(target));
            if self.blocks(target).is_empty() {
                paths.push(path.clone());
            } else {
                self.walk_downstream(target, path, paths, visited_nodes);
                path.pop();
            }
        }
    }

    /// A chain node for `number`, falling back to an empty title for an edge
    /// endpoint that no longer resolves.
    fn chain_node(&self, number: u32) -> ChainNode {
        match self
            .reference_for_number(number)
            .and_then(|reference| self.issues.get(&reference))
        {
            Some(issue) => ChainNode::new(number, issue.title),
            None => ChainNode::new(number, String::new()),
        }
    }

    // -----------------------------------------------------------------------
    // T004 — validation
    // -----------------------------------------------------------------------

    /// Sweep every stored edge and every issue, reporting every problem.
    ///
    /// A single `O(V + E)` pass, **never** an `Err`: `tix lint` consumes the
    /// returned value. Cycle detection reuses the `blocks` adjacency built at
    /// construction, so it is not a second scan.
    pub fn validate_snapshot(&self) -> RelationshipValidationResult {
        let mut result = RelationshipValidationResult::clean();
        result.errors.extend(self.alias_diagnostics.clone());

        let mut references: Vec<IssueRef> = self.issues.keys().copied().collect();
        references.sort_unstable();
        for reference in references {
            let view = self.issues[&reference];
            let number = self.number_for_reference(reference).unwrap_or_default();
            // The wording names the **command** and the **flag**, not just the
            // kind vocabulary.
            //
            // An earlier version said "record the relationships as typed edges
            // (`blocks`, `blocked_by`, `duplicates`, or `related`)" — which reads
            // as though those four names were frontmatter *keys*. They are
            // `--type` values; the real field is `relationships:`, holding objects.
            // A user who obeyed that message literally would write `blocks: [2]`
            // at the top level, and then hit the worse bug underneath: the model
            // carries no unknown keys, so `tix lint` would certify the file and the
            // next unrelated `tix edit` would delete the key without a word.
            //
            // So the advice is the command that actually does it, and the
            // vocabulary is explicitly the argument's value. The README's
            // conversion section already said this; the diagnostic and the docs
            // disagreed, and the diagnostic is the one a user in the middle of a
            // problem will read.
            if view.has_retired_links_key {
                result.errors.push(Diagnostic::about(
                    number,
                    DiagnosticKind::RetiredLinksKey,
                    "links",
                    format!(
                        "#{number} still carries the retired `links:` key, which the typed \
                         model no longer reads \u{2014} remove the key, then recreate each \
                         relationship with `tix link <from> <to> --type <kind>` (or the \
                         `link_issue` tool), where `<kind>` is one of `blocks`, \
                         `blocked_by`, `duplicates`, or `related`"
                    ),
                ));
            }
        }

        // Per-edge rules. Each edge is examined once so an implied second
        // report for the same problem cannot appear.
        let mut pair_kind: HashMap<(IssueRef, IssueRef), RelationKind> = HashMap::new();
        for edge in &self.edges {
            if edge.from == edge.to {
                result.errors.push(
                    Diagnostic::self_link(self.number_for_reference(edge.from).unwrap_or_default())
                        .with_source_file(
                            self.edge_owners.get(&edge.id).cloned().unwrap_or_default(),
                        ),
                );
                continue;
            }
            if !self.issues.contains_key(&edge.to) {
                result.errors.push(
                    Diagnostic::missing_target(
                        self.number_for_reference(edge.from).unwrap_or_default(),
                        edge.to,
                    )
                    .with_source_file(self.edge_owners.get(&edge.id).cloned().unwrap_or_default()),
                );
                continue;
            }
            // One authoritative kind per ordered pair: two different kinds for
            // the same pair is a conflict, an identical repeat is idempotent.
            let key = self.conflict_key(edge.canonical());
            match pair_kind.get(&key) {
                Some(existing) if *existing != edge.kind => {
                    // Attributed to `from`: that is the issue whose relationship
                    // set carries the conflict, and therefore the file lint names.
                    result.errors.push(
                        Diagnostic::about(
                            self.number_for_reference(edge.from).unwrap_or_default(),
                            DiagnosticKind::ConflictingEdge,
                            "kind",
                            format!(
                                "#{from} → #{to} is already `{existing}`; refusing to store it as `{}` as well",
                                edge.kind.as_str(),
                                from = edge.from,
                                to = edge.to
                            ),
                        )
                        .with_source_file(
                            self.edge_owners.get(&edge.id).cloned().unwrap_or_default(),
                        ),
                    );
                }
                Some(_) => {}
                None => {
                    pair_kind.insert(key, edge.kind);
                }
            }
        }

        result.merge(self.validate_cycles());
        result.sort_diagnostics();
        result
    }

    /// Validate a proposed relationship creation.
    ///
    /// Runs every per-edge rule plus the cycle check, so the caller gets one
    /// blocking verdict before touching any file (SC-005).
    pub fn validate_create(
        &self,
        from: u32,
        to: u32,
        kind: RelationKind,
    ) -> RelationshipValidationResult {
        let Some(from) = self.reference_for_number(from) else {
            let mut result = RelationshipValidationResult::clean();
            result
                .errors
                .push(Diagnostic::missing_target(0, to.to_string()));
            return result;
        };
        let Some(to) = self.reference_for_number(to) else {
            let mut result = RelationshipValidationResult::clean();
            result.errors.push(Diagnostic::missing_target(
                self.number_for_reference(from).unwrap_or_default(),
                "missing",
            ));
            return result;
        };
        self.validate_authored_ref(from, to, kind, None, Duplicate::Allowed)
    }

    /// Canonical-reference form of [`Self::validate_create`].
    pub fn validate_create_ref(
        &self,
        from: IssueRef,
        to: IssueRef,
        kind: RelationKind,
    ) -> RelationshipValidationResult {
        self.validate_authored_ref(from, to, kind, None, Duplicate::Allowed)
    }

    /// [`RelationshipGraph::validate_create`], with the ability to ignore one
    /// already-stored relationship and to say whether landing on an edge that
    /// already exists is an error.
    ///
    /// `exclude` is the id of the relationship being edited. An edge never
    /// conflicts with itself, so the edited record must not be counted while
    /// looking for a different kind on the same pair — but every *other*
    /// pre-existing edge on that pair still must. Filtering the finished result
    /// instead of excluding by id would also swallow a conflict that was
    /// already true of the stored data (review R4).
    fn validate_authored_ref(
        &self,
        from: IssueRef,
        to: IssueRef,
        kind: RelationKind,
        exclude: Option<&str>,
        duplicate: Duplicate,
    ) -> RelationshipValidationResult {
        let mut result = RelationshipValidationResult::clean();
        let canonical = CanonicalEdge::new(from, to, kind);
        let from_number = self.number_for_reference(from).unwrap_or_default();
        let to_number = self.number_for_reference(to).unwrap_or_default();

        if !self.issues.contains_key(&from) {
            result
                .errors
                .push(Diagnostic::missing_target(to_number, from));
        }
        if canonical.is_self_link() {
            result.errors.push(Diagnostic::self_link(from_number));
        } else if !self.issues.contains_key(&to) {
            result
                .errors
                .push(Diagnostic::missing_target(from_number, to));
        }

        if let Some(existing) = self
            .by_issue
            .get(&from)
            .into_iter()
            .flatten()
            .map(|index| &self.edges[*index])
            .find(|r| {
                let c = r.canonical();
                self.conflict_key(c) == self.conflict_key(canonical)
                    && c.kind != canonical.kind
                    && exclude != Some(r.id.as_str())
            })
        {
            result.errors.push(Diagnostic::new(
                DiagnosticKind::ConflictingEdge,
                "kind",
                format!(
                    "#{} → #{} is already `{}`; refusing to store it as `{}` as well",
                    from_number,
                    to_number,
                    existing.kind.as_str(),
                    canonical.kind.as_str()
                ),
            ));
        }

        if let Some(cycle) = self.cycle_if_added(canonical) {
            result.errors.push(cycle);
        }

        // Landing on a triple another relationship already occupies would give
        // two stored edges for one relationship, breaking the
        // `(from, to, kind)` uniqueness invariant (data-model §2). Only an edit
        // treats this as an error: a *create* that re-asserts an edge that
        // already exists is the idempotent no-op §2 requires, whereas an edit
        // would silently collapse two distinct relationship ids into one
        // (review P2).
        if duplicate == Duplicate::Rejected {
            if let Some(clash) = self
                .by_issue
                .get(&from)
                .into_iter()
                .flatten()
                .map(|index| &self.edges[*index])
                .find(|r| r.canonical() == canonical && exclude != Some(r.id.as_str()))
            {
                result.errors.push(Diagnostic::new(
                    DiagnosticKind::ConflictingEdge,
                    "kind",
                    format!(
                        "#{from_number} already has a `{}` relationship to #{} (`{}`); this edit would store a second one — drop the existing edge or pick a different kind",
                        canonical.kind.as_str(),
                        to_number,
                        clash.id
                    ),
                ));
            }
        }

        result.sort_diagnostics();
        result
    }

    /// Validate a proposed edit of an existing relationship.
    ///
    /// An edit naming its own current target and kind is the identity, not a
    /// duplicate — and nothing else is forgiven. The edit must still agree with
    /// the graph as it already stands, so `validate_edit` never returns a
    /// cleaner verdict than `validate_snapshot` for the same stored data.
    pub fn validate_edit(
        &self,
        id: &str,
        new_to: Option<u32>,
        new_kind: Option<RelationKind>,
    ) -> RelationshipValidationResult {
        let Some(existing) = self.find_relationship(id) else {
            let mut result = RelationshipValidationResult::clean();
            result.errors.push(Diagnostic::unknown_relation(id));
            return result;
        };

        let from = existing.from;
        let to = new_to
            .and_then(|number| self.reference_for_number(number))
            .unwrap_or(existing.to);
        let kind = new_kind.unwrap_or(existing.kind);
        self.validate_authored_ref(from, to, kind, Some(id), Duplicate::Rejected)
    }

    /// Detect every cycle in the `blocks` adjacency.
    ///
    /// Kahn's algorithm peels the acyclic part in `O(V + E)`; the residue is
    /// the set of nodes on, or downstream of, a cycle. One iterative
    /// three-colour DFS over that residue then names each distinct cycle, so
    /// the whole sweep stays `O(V + E)` rather than re-walking per node
    /// (NFR-001).
    fn validate_cycles(&self) -> RelationshipValidationResult {
        let mut result = RelationshipValidationResult::clean();
        for path in self.cycles() {
            // A cycle names every issue on it, so there is no single subject. The
            // **first** node stands in, because lint needs one file to hang the
            // finding on and the first node is the one whose relationship set a
            // reader has to edit to break the cycle. The message still names the
            // whole path, so the finding is not misleading about its scope.
            result.errors.push(Diagnostic::about(
                path[0],
                DiagnosticKind::Cycle,
                "to",
                format!("cycle: {}", render_cycle(&path)),
            ));
        }
        result
    }

    /// Every distinct cycle in the `blocks` adjacency, each reported once.
    ///
    /// Iterative throughout: a 10,000-node chain must not overflow the stack.
    fn cycles(&self) -> Vec<Vec<u32>> {
        // Counted **here**, at the traversal, rather than at
        // `validate_snapshot`'s entry. A count at the entry witnesses how many
        // times the operation was *called*; this witnesses how many times the
        // blocks adjacency was actually *walked*, which is what "one pass" means.
        // A redundant `let _ = self.validate_cycles();` inside `validate_snapshot`
        // leaves an entry count at 1 and doubles this one — and that redundant call
        // kept the entire suite green until this counter existed.
        self.validation_passes
            .fetch_add(1, std::sync::atomic::Ordering::Relaxed);
        let residue = self.cyclic_residue();
        if residue.is_empty() {
            return Vec::new();
        }

        const WHITE: u8 = 0;
        const GREY: u8 = 1;
        const BLACK: u8 = 2;

        let mut color: HashMap<u32, u8> = HashMap::new();
        let mut cycles: Vec<Vec<u32>> = Vec::new();
        let mut reported: HashSet<Vec<u32>> = HashSet::new();
        let mut path: Vec<u32> = Vec::new();
        let mut position: HashMap<u32, usize> = HashMap::new();
        let mut work: Vec<(u32, usize)> = Vec::new();

        for start in &self.issues_by_number {
            let start = *start;
            if !residue.contains(&start) || color.get(&start) == Some(&BLACK) {
                continue;
            }
            color.insert(start, GREY);
            position.insert(start, path.len());
            path.push(start);
            work.push((start, 0));

            while let Some(top) = work.last_mut() {
                let (node, cursor) = (top.0, top.1);
                let downstream = self.blocks(node);
                if cursor < downstream.len() {
                    top.1 += 1;
                    let next = downstream[cursor];
                    if !residue.contains(&next) {
                        continue;
                    }
                    match color.get(&next).copied().unwrap_or(WHITE) {
                        GREY => {
                            // Back edge: the cycle is the grey span on the path.
                            if let Some(start_at) = position.get(&next) {
                                let cycle = path[*start_at..].to_vec();
                                if reported.insert(cycle_key(&cycle)) {
                                    cycles.push(cycle);
                                }
                            }
                        }
                        WHITE => {
                            color.insert(next, GREY);
                            position.insert(next, path.len());
                            path.push(next);
                            work.push((next, 0));
                        }
                        _ => {}
                    }
                } else {
                    color.insert(node, BLACK);
                    position.remove(&node);
                    path.pop();
                    work.pop();
                }
            }
        }
        cycles
    }

    /// The nodes Kahn's algorithm cannot free: those on, or downstream of, a
    /// directed cycle. Empty means the graph is acyclic.
    fn cyclic_residue(&self) -> HashSet<u32> {
        let mut indegree: HashMap<u32, usize> =
            self.issues_by_number.iter().map(|n| (*n, 0usize)).collect();
        for edge in &self.edges {
            if edge.kind != RelationKind::Blocks || edge.from == edge.to {
                continue;
            }
            if !self.issues.contains_key(&edge.from) || !self.issues.contains_key(&edge.to) {
                continue;
            }
            let (Some(from), Some(to)) = (
                self.number_for_reference(edge.from),
                self.number_for_reference(edge.to),
            ) else {
                continue;
            };
            if indegree.contains_key(&from) {
                *indegree.entry(to).or_default() += 1;
            }
        }

        let mut queue: VecDeque<u32> = indegree
            .iter()
            .filter(|(_, degree)| **degree == 0)
            .map(|(node, _)| *node)
            .collect();
        while let Some(node) = queue.pop_front() {
            // Self-links never reach the adjacency (see `rebuild_edges`), and
            // the degree is only decremented while positive, so a node is
            // enqueued exactly once and the peel terminates.
            for next in self.blocks(node) {
                if let Some(degree) = indegree.get_mut(next) {
                    if *degree > 0 {
                        *degree -= 1;
                        if *degree == 0 {
                            queue.push_back(*next);
                        }
                    }
                }
            }
        }

        indegree
            .into_iter()
            .filter(|(_, degree)| *degree > 0)
            .map(|(node, _)| node)
            .collect()
    }

    /// The `cycle` diagnostic an added edge would produce, if any.
    ///
    /// `from -> to` closes a cycle exactly when `to` already reaches `from`.
    /// The walk is iterative, so a 10,000-node chain is safe.
    fn cycle_if_added(&self, edge: CanonicalEdge) -> Option<Diagnostic> {
        if edge.is_self_link() {
            return Some(Diagnostic::self_link(
                self.number_for_reference(edge.from).unwrap_or_default(),
            ));
        }
        // Only `blocks` can close a cycle. The reachability search below walks the
        // `blocks` adjacency, so running it for `related` or `duplicates` asks a
        // question about an edge that is not in that graph at all -- and answers
        // it wrongly, because the search finds a `blocks` path between the two
        // endpoints and reports a cycle for an edge that closes none.
        //
        // `data-model.md` §1 gives `duplicates` "no blocked-state effect", and
        // `contracts/relationship-service.md` §3.3 scopes the rule to "a **new
        // edge** that would close a directed cycle". Neither `related` nor
        // `duplicates` participates in the dependency graph, so neither can close
        // one.
        //
        // The cost of getting this wrong is not only a spurious rejection: with
        // `2 blocks 0` stored, re-kinding that edge to `related` is *refused*,
        // and the only route to a `related` edge between those two issues became
        // the destructive path in `Store::edit_relation`.
        if edge.kind != RelationKind::Blocks {
            return None;
        }
        if !self.issues.contains_key(&edge.to) {
            return None;
        }
        let path = self.shortest_path(edge.to, edge.from)?;
        let mut full = Vec::with_capacity(path.len() + 1);
        full.push(edge.from);
        full.extend(path);
        let numbers: Vec<u32> = full
            .iter()
            .map(|reference| self.number_for_reference(*reference).unwrap_or_default())
            .collect();
        Some(Diagnostic::new(
            DiagnosticKind::Cycle,
            "to",
            format!("cycle: {}", render_cycle(&numbers)),
        ))
    }

    /// An iterative breadth-first search from `start` to `goal`, returning the
    /// node sequence inclusive of both ends.
    fn shortest_path(&self, start: IssueRef, goal: IssueRef) -> Option<Vec<IssueRef>> {
        if start == goal {
            return Some(vec![start]);
        }
        let mut previous: HashMap<IssueRef, IssueRef> = HashMap::new();
        let mut seen: HashSet<IssueRef> = HashSet::new();
        let mut queue: std::collections::VecDeque<IssueRef> = std::collections::VecDeque::new();
        seen.insert(start);
        queue.push_back(start);
        while let Some(node) = queue.pop_front() {
            for next in self.blocks_out.get(&node).map(Vec::as_slice).unwrap_or(&[]) {
                if !seen.insert(*next) {
                    continue;
                }
                previous.insert(*next, node);
                if *next == goal {
                    let mut path = vec![goal];
                    let mut cursor = goal;
                    while let Some(step) = previous.get(&cursor) {
                        path.push(*step);
                        cursor = *step;
                    }
                    path.reverse();
                    return Some(path);
                }
                queue.push_back(*next);
            }
        }
        None
    }
}

/// The move-warning / detail-view text for a non-empty blocker set.
///
/// Derived from [`BlockedState::blockers`] so every surface shows the same
/// string (parity contract §3).
pub fn blocked_reason(blockers: &[ChainNode]) -> String {
    if blockers.len() == 1 {
        let node = &blockers[0];
        return format!("Blocked by #{} {}", node.number, node.title)
            .trim_end()
            .to_string();
    }
    let list = blockers
        .iter()
        .map(|n| format!("#{} {}", n.number, n.title).trim_end().to_string())
        .collect::<Vec<_>>()
        .join(", ");
    format!("Blocked by {} issues: {list}", blockers.len())
}

fn render_cycle(path: &[u32]) -> String {
    let rendered = path
        .iter()
        .map(u32::to_string)
        .collect::<Vec<_>>()
        .join(" -> ");
    format!("{rendered} -> #{}", path[0])
}

fn cycle_key(path: &[u32]) -> Vec<u32> {
    // Canonical rotation so the same cycle is reported once regardless of
    // which node the walk happened to start from.
    let Some(min_position) = path
        .iter()
        .enumerate()
        .min_by_key(|(_, n)| **n)
        .map(|(i, _)| i)
    else {
        return path.to_vec();
    };
    let mut rotated = path[min_position..].to_vec();
    rotated.extend_from_slice(&path[..min_position]);
    rotated
}

// ---------------------------------------------------------------------------
// Stable identifier generation (T001)
// ---------------------------------------------------------------------------

/// Generate a stable relationship identifier.
///
/// The format is `rel_` followed by 26 Crockford base32 characters: a 48-bit
/// millisecond timestamp followed by 80 pseudo-random bits. It is ULID-shaped
/// so ids sort by creation time and stay stable across retarget, rename, and
/// export/import.
///
/// Randomness comes from the OS-seeded hasher state plus a process-local
/// counter, so the crate keeps **zero new dependencies** (C-001).
pub fn generate_relationship_id() -> RelationshipId {
    use std::hash::{BuildHasher, Hasher};
    use std::sync::atomic::{AtomicU64, Ordering};
    use std::time::{SystemTime, UNIX_EPOCH};

    static COUNTER: AtomicU64 = AtomicU64::new(0);

    let millis = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map(|d| d.as_millis())
        .unwrap_or(0);
    let counter = COUNTER.fetch_add(1, Ordering::Relaxed);
    let mut hasher = std::collections::hash_map::RandomState::new().build_hasher();
    hasher.write_u128(millis);
    hasher.write_u64(counter);
    let entropy = hasher.finish();
    // 80 bits: 64 from the hasher, 16 more from a second pass over the counter.
    let mut second = std::collections::hash_map::RandomState::new().build_hasher();
    second.write_u64(entropy);
    second.write_u64(counter.wrapping_mul(0x9E37_79B9_7F4A_7C15));
    let high = second.finish() & 0xFFFF;

    let value = (millis << 80u32) | (u128::from(entropy) << 16) | u128::from(high);
    // The Crockford encoder is shared with the issue-id generator (`crate::id`),
    // so the crate has one base32 implementation rather than two.
    format!("rel_{}", crate::id::crockford(value, 26))
}

// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------

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

    // -- test fixtures -----------------------------------------------------

    /// An owned issue, so tests can build borrowed [`IssueView`]s from a
    /// stable backing allocation.
    #[derive(Clone)]
    struct Owned {
        id: Option<String>,
        filename: String,
        number: u32,
        title: String,
        status: String,
        relationships: Vec<Relationship>,
        retired: bool,
    }

    impl Owned {
        fn new(number: u32, title: &str, status: &str) -> Self {
            Self {
                id: None,
                filename: format!("{number}.md"),
                number,
                title: title.to_string(),
                status: status.to_string(),
                relationships: Vec::new(),
                retired: false,
            }
        }

        fn with_id(mut self, id: &str) -> Self {
            self.id = Some(id.to_string());
            self.filename = format!("{id}.md");
            self
        }

        /// Consuming builder: this issue blocks `to`.
        fn blocking(mut self, to: u32, title: &str) -> Self {
            self.relationships.push(Relationship::new(
                self.number,
                to,
                RelationKind::Blocks,
                title,
            ));
            self
        }

        /// In-place builder, for loops that build many edges on one issue.
        fn push_block(&mut self, to: u32, title: &str) {
            self.relationships.push(Relationship::new(
                self.number,
                to,
                RelationKind::Blocks,
                title,
            ));
        }

        /// This issue is `related` to `to`.
        fn with_related(self, to: u32, title: &str) -> Self {
            let mut this = self;
            this.relationships.push(Relationship::new(
                this.number,
                to,
                RelationKind::Related,
                title,
            ));
            this
        }

        fn with_retired_links_key(mut self) -> Self {
            self.retired = true;
            self
        }

        fn view(&self) -> IssueView<'_> {
            IssueView::new(self.number, &self.title, &self.status, &self.relationships)
                .with_identity(self.id.as_deref(), &self.filename)
                .with_retired_links_key(self.retired)
        }
    }

    fn graph_of<'x>(owned: &'x [Owned], done_column: &str) -> RelationshipGraph<'x> {
        let views: Vec<IssueView<'x>> = owned.iter().map(Owned::view).collect();
        RelationshipGraph::new(&views, done_column)
    }

    // -- T001: vocabulary --------------------------------------------------

    #[test]
    fn relation_kind_has_exactly_four_variants_with_canonical_spellings() {
        let spellings: Vec<&str> = RelationKind::ALL.iter().map(|k| k.as_str()).collect();
        assert_eq!(spellings, ["blocks", "blocked_by", "duplicates", "related"]);
    }

    #[test]
    fn is_directional_is_false_only_for_related() {
        for kind in RelationKind::ALL {
            assert_eq!(
                kind.is_directional(),
                kind != RelationKind::Related,
                "{kind} directionality"
            );
        }
    }

    #[test]
    fn inverse_truth_table_matches_the_contract() {
        assert_eq!(
            RelationKind::Blocks.inverse(),
            Some(RelationKind::BlockedBy)
        );
        assert_eq!(
            RelationKind::BlockedBy.inverse(),
            Some(RelationKind::Blocks)
        );
        assert_eq!(RelationKind::Duplicates.inverse(), None);
        assert_eq!(RelationKind::Related.inverse(), None);
    }

    #[test]
    fn from_str_parses_every_canonical_spelling() {
        for kind in RelationKind::ALL {
            assert_eq!(kind.as_str().parse::<RelationKind>().unwrap(), kind);
        }
    }

    #[test]
    fn unknown_kind_is_rejected_and_never_coerced_to_related() {
        let err = "depends_on".parse::<RelationKind>().unwrap_err();
        assert_eq!(err.kind, DiagnosticKind::UnknownKind);
        assert!(err.message.contains("depends_on"));
        assert!(err.message.contains("blocks"));
    }

    #[test]
    fn relationship_serde_round_trip_is_stable() {
        let rel = Relationship::new(42, 51, RelationKind::Blocks, "Refactor store");
        let yaml = serde_yaml::to_string(&rel).unwrap();
        let parsed: Relationship = serde_yaml::from_str(&yaml).unwrap();
        assert_eq!(rel, parsed);
        assert_eq!(serde_yaml::to_string(&parsed).unwrap(), yaml);
    }

    #[test]
    fn relationship_parses_with_display_omitted() {
        let yaml = "id: rel_1\nfrom: 1\nto: 2\nkind: blocks\n";
        let rel: Relationship = serde_yaml::from_str(yaml).unwrap();
        assert_eq!(rel.display, "");
        // An empty display is omitted rather than written as `display: ""`.
        assert!(!serde_yaml::to_string(&rel).unwrap().contains("display"));
    }

    #[test]
    fn display_name_combines_kind_number_and_title() {
        assert_eq!(
            display_name(RelationKind::Blocks, 42, "Fix flaky test"),
            "blocks #42 Fix flaky test"
        );
        assert_eq!(
            display_name(RelationKind::Related, 7, "   "),
            "related #7",
            "a blank title must not leave a trailing space"
        );
    }

    #[test]
    fn stable_ids_are_unique_across_a_batch_and_prefixed() {
        let mut seen = std::collections::HashSet::new();
        for _ in 0..2_000 {
            let id = generate_relationship_id();
            assert!(id.starts_with("rel_"), "unexpected id shape: {id}");
            assert_eq!(id.len(), "rel_".len() + 26, "unexpected id length: {id}");
            assert!(
                id["rel_".len()..]
                    .bytes()
                    .all(|b| crate::id::CROCKFORD.contains(&b)),
                "non-Crockford character in {id}"
            );
            assert!(seen.insert(id), "duplicate relationship id generated");
        }
    }

    // -- T002: direction convention ----------------------------------------

    #[test]
    fn both_spellings_of_a_blocking_pair_normalize_to_one_canonical_edge() {
        let forward = normalize(1, 2, RelationKind::Blocks);
        let inverse = normalize(1, 2, RelationKind::BlockedBy);
        assert_eq!(
            forward,
            CanonicalEdge {
                from: IssueRef::Number(1),
                to: IssueRef::Number(2),
                kind: RelationKind::Blocks
            }
        );
        assert_eq!(
            inverse,
            CanonicalEdge {
                from: IssueRef::Number(2),
                to: IssueRef::Number(1),
                kind: RelationKind::Blocks
            },
            "blocked_by must swap the endpoints into the canonical blocks form"
        );
        assert_eq!(
            forward.to, inverse.from,
            "the two spellings are the same edge"
        );
    }

    #[test]
    fn a_persisted_blocking_edge_never_carries_the_blocked_by_kind() {
        let stored = Relationship::new(1, 2, RelationKind::BlockedBy, "T");
        assert_eq!(stored.kind, RelationKind::Blocks);
        assert_eq!(
            (stored.from.as_number(), stored.to.as_number()),
            (Some(2), Some(1))
        );
    }

    #[test]
    fn normalize_all_deduplicates_both_spellings_and_is_idempotent() {
        // "1 blocks 2" and "2 is blocked by 1" are one edge.
        let authored = [
            (1, 2, RelationKind::Blocks),
            (2, 1, RelationKind::BlockedBy),
            (3, 4, RelationKind::Related),
        ];
        let once = normalize_all(authored);
        assert_eq!(once.len(), 2, "the two spellings collapse to one edge");
        assert_eq!(
            once,
            normalize_all(authored),
            "normalization is deterministic"
        );
        assert_eq!(
            once,
            normalize_all(
                once.iter()
                    .map(|e| (e.from, e.to, e.kind))
                    .collect::<Vec<_>>()
            )
        );
    }

    #[test]
    fn related_and_duplicates_never_swap_endpoints() {
        for kind in [RelationKind::Related, RelationKind::Duplicates] {
            let edge = normalize(1, 2, kind);
            assert_eq!(
                (edge.from.as_number(), edge.to.as_number(), edge.kind),
                (Some(1), Some(2), kind)
            );
        }
    }

    #[test]
    fn a_reciprocal_blocking_pair_is_rejected_as_a_cycle() {
        let a = Owned::new(1, "A", "todo").blocking(2, "B");
        let b = Owned::new(2, "B", "todo").blocking(1, "A");
        let owned = vec![a, b];
        let graph = graph_of(&owned, "done");

        let result = graph.validate_snapshot();
        assert!(
            result.has(DiagnosticKind::Cycle),
            "expected a cycle diagnostic: {result:?}"
        );
        assert!(result.blocking(), "a reciprocal pair must be blocking");
    }

    #[test]
    fn a_conflicting_kind_for_the_same_pair_is_reported() {
        let a = Owned::new(1, "A", "todo").blocking(2, "B");
        let mut a = a;
        a.relationships
            .push(Relationship::new(1, 2, RelationKind::Related, "B"));
        let owned = vec![a, Owned::new(2, "B", "todo")];
        let result = graph_of(&owned, "done").validate_snapshot();
        assert!(
            result.has(DiagnosticKind::ConflictingEdge),
            "expected conflicting_edge: {result:?}"
        );
    }

    // -- T003: graph build and ordering ------------------------------------

    #[test]
    fn edges_are_returned_from_both_endpoints() {
        let a = Owned::new(1, "A", "todo").blocking(2, "B");
        let owned = vec![a, Owned::new(2, "B", "todo")];
        let graph = graph_of(&owned, "done");
        assert_eq!(graph.relationships_for(1).len(), 1);
        assert_eq!(
            graph.relationships_for(2).len(),
            1,
            "the target sees the edge too"
        );
    }

    #[test]
    fn ordering_is_stable_across_repeated_builds() {
        let a = Owned::new(1, "A", "todo")
            .blocking(4, "D")
            .blocking(2, "B")
            .blocking(3, "C");
        let owned = vec![
            a,
            Owned::new(2, "B", "todo"),
            Owned::new(3, "C", "todo"),
            Owned::new(4, "D", "todo"),
        ];
        let first: Vec<(RelationKind, u32)> = graph_of(&owned, "done")
            .relationships_for(1)
            .iter()
            .map(|r| (r.kind, r.to.as_number().unwrap_or_default()))
            .collect();
        let second: Vec<(RelationKind, u32)> = graph_of(&owned, "done")
            .relationships_for(1)
            .iter()
            .map(|r| (r.kind, r.to.as_number().unwrap_or_default()))
            .collect();
        assert_eq!(first, second, "repeated builds must be byte-comparable");
        assert_eq!(
            first,
            vec![
                (RelationKind::Blocks, 2),
                (RelationKind::Blocks, 3),
                (RelationKind::Blocks, 4)
            ],
            "edges are ordered by (kind, target)"
        );
    }

    #[test]
    fn related_and_duplicates_never_enter_blocked_adjacency() {
        let mut a = Owned::new(1, "A", "todo");
        a.relationships
            .push(Relationship::new(1, 2, RelationKind::Related, "B"));
        a.relationships
            .push(Relationship::new(1, 3, RelationKind::Duplicates, "C"));
        let owned = vec![a, Owned::new(2, "B", "todo"), Owned::new(3, "C", "todo")];
        let graph = graph_of(&owned, "done");
        assert!(
            graph.blocks(1).is_empty(),
            "related/duplicates are not blockers"
        );
        assert_eq!(graph.blocked_by(2), [] as [u32; 0]);
        assert_eq!(graph.blocked_by(3), [] as [u32; 0]);
        assert_eq!(graph.duplicates_of(1), vec![3]);
        assert_eq!(graph.related_to(1), vec![2]);
    }

    #[test]
    fn an_issue_with_no_edges_yields_empty_results_not_an_error() {
        let owned = vec![Owned::new(1, "A", "todo")];
        let graph = graph_of(&owned, "done");
        assert_eq!(
            graph.relationships_for(1),
            [] as [&crate::relationships::Relationship; 0]
        );
        assert_eq!(graph.blocks(1), [] as [u32; 0]);
        assert_eq!(graph.blocked_by(1), [] as [u32; 0]);
        assert_eq!(
            graph.open_blockers(1),
            [] as [crate::relationships::ChainNode; 0]
        );
        assert!(graph.dependencies_are_empty_for_unknown_issue());
    }

    impl RelationshipGraph<'_> {
        /// Small readability helper for the empty-result test.
        fn dependencies_are_empty_for_unknown_issue(&self) -> bool {
            self.dependency_chain(9_999).paths.is_empty()
        }
    }

    // -- T004: validation --------------------------------------------------

    #[test]
    fn an_empty_snapshot_validates_clean() {
        let owned = vec![Owned::new(1, "A", "todo")];
        let result = graph_of(&owned, "done").validate_snapshot();
        assert!(result.is_clean(), "unexpected diagnostics: {result:?}");
        assert!(!result.blocking());
    }

    #[test]
    fn self_link_create_is_rejected() {
        let owned = vec![Owned::new(1, "A", "todo")];
        let result = graph_of(&owned, "done").validate_create(1, 1, RelationKind::Blocks);
        assert!(result.has(DiagnosticKind::SelfLink), "{result:?}");
        assert!(result.blocking());
    }

    #[test]
    fn missing_target_create_is_rejected() {
        let owned = vec![Owned::new(1, "A", "todo")];
        let result = graph_of(&owned, "done").validate_create(1, 99, RelationKind::Blocks);
        assert!(result.has(DiagnosticKind::MissingTarget), "{result:?}");
    }

    #[test]
    fn validate_create_accepts_both_spellings_of_the_same_pair() {
        let owned = vec![Owned::new(1, "A", "todo"), Owned::new(2, "B", "todo")];
        let graph = graph_of(&owned, "done");
        assert!(graph.validate_create(1, 2, RelationKind::Blocks).is_clean());
        assert!(
            graph
                .validate_create(1, 2, RelationKind::BlockedBy)
                .is_clean(),
            "the inverse spelling is the same edge, not a conflict"
        );
    }

    #[test]
    fn editing_an_unknown_relationship_id_is_reported() {
        let owned = vec![Owned::new(1, "A", "todo")];
        let result = graph_of(&owned, "done").validate_edit("rel_missing", None, None);
        assert!(result.has(DiagnosticKind::UnknownRelation), "{result:?}");
    }

    #[test]
    fn a_retired_links_key_is_reported_and_never_read_as_typed_data() {
        let owned = vec![
            Owned::new(1, "A", "todo").with_retired_links_key(),
            Owned::new(2, "B", "todo"),
        ];
        let result = graph_of(&owned, "done").validate_snapshot();
        assert!(result.has(DiagnosticKind::RetiredLinksKey), "{result:?}");
        assert_eq!(
            result
                .errors
                .iter()
                .find(|d| d.kind == DiagnosticKind::RetiredLinksKey)
                .map(|d| d.field.as_str()),
            Some("links")
        );
    }

    #[test]
    fn a_snapshot_with_three_distinct_problems_reports_exactly_three_diagnostics() {
        let mut self_linked = Owned::new(1, "A", "todo");
        self_linked
            .relationships
            .push(Relationship::new(3, 3, RelationKind::Blocks, "C"));
        let mut dangling = Owned::new(2, "B", "todo");
        dangling
            .relationships
            .push(Relationship::new(2, 404, RelationKind::Blocks, "gone"));
        let owned = vec![
            self_linked,
            dangling,
            Owned::new(3, "C", "todo").with_retired_links_key(),
        ];
        let result = graph_of(&owned, "done").validate_snapshot();
        assert_eq!(
            result.errors.len(),
            3,
            "expected no duplicate or implied reports: {result:?}"
        );
    }

    // -- T005: cycles, chains, blocked state -------------------------------

    #[test]
    fn a_three_chain_returns_the_ordered_path() {
        let a = Owned::new(1, "A", "todo").blocking(2, "B");
        let b = Owned::new(2, "B", "todo").blocking(3, "C");
        let owned = vec![a, b, Owned::new(3, "C", "todo")];
        let chain = graph_of(&owned, "done").dependency_chain(1);
        assert_eq!(chain.root, 1);
        assert_eq!(chain.paths.len(), 1);
        assert_eq!(
            chain.paths[0].iter().map(|n| n.number).collect::<Vec<_>>(),
            vec![1, 2, 3],
            "the chain walks upstream from the root toward its blockers"
        );
        assert!(!chain.truncated);
    }

    #[test]
    fn a_cycle_closing_edge_is_rejected() {
        let a = Owned::new(1, "A", "todo").blocking(2, "B");
        let b = Owned::new(2, "B", "todo").blocking(3, "C");
        let owned = vec![a, b, Owned::new(3, "C", "todo")];
        let result = graph_of(&owned, "done").validate_create(3, 1, RelationKind::Blocks);
        assert!(result.has(DiagnosticKind::Cycle), "{result:?}");
        assert!(result.blocking());
    }

    #[test]
    fn blocked_state_is_true_only_for_an_open_inbound_blocks_edge() {
        let a = Owned::new(1, "A", "todo").blocking(2, "B");
        let owned = vec![a, Owned::new(2, "B", "todo")];
        let graph = graph_of(&owned, "done");

        let state = graph.blocked_state(2);
        assert!(state.is_blocked);
        assert_eq!(
            state.blockers.iter().map(|n| n.number).collect::<Vec<_>>(),
            vec![1]
        );
        assert!(
            state.reason.contains("#1"),
            "the reason names the blocker: {}",
            state.reason
        );

        assert!(
            !graph.blocked_state(1).is_blocked,
            "the blocker is not itself blocked"
        );
    }

    #[test]
    fn moving_the_blocker_into_the_configured_done_column_clears_blocked_state() {
        let a = Owned::new(1, "A", "todo").blocking(2, "B");
        let owned = vec![a, Owned::new(2, "B", "todo")];
        // A board whose completion column is "shipped", not "done".
        let graph = graph_of(&owned, "shipped");
        assert!(
            graph.blocked_state(2).is_blocked,
            "A is not in the shipped column yet"
        );

        let mut moved = owned.clone();
        moved[0].status = "shipped".to_string();
        let after = graph_of(&moved, "shipped");
        assert!(
            !after.blocked_state(2).is_blocked,
            "a blocker in the configured done_column stops blocking"
        );
    }

    #[test]
    fn a_blocker_in_a_non_completion_column_keeps_blocking() {
        let a = Owned::new(1, "A", "in review").blocking(2, "B");
        let owned = vec![a, Owned::new(2, "B", "todo")];
        let graph = graph_of(&owned, "shipped");
        assert!(graph.blocked_state(2).is_blocked);
        assert_ne!(graph.blocked_state(2).reason, "");
    }

    #[test]
    fn a_dangling_edge_is_diagnosed_but_does_not_freeze_the_issue() {
        // Edge 1 -> 404 where 404 does not exist: validation reports it, but the
        // blocked-state derivation must exclude it.
        let mut blocker = Owned::new(1, "A", "todo");
        blocker
            .relationships
            .push(Relationship::new(1, 404, RelationKind::Blocks, "gone"));
        let owned = vec![blocker, Owned::new(2, "B", "todo")];
        let graph = graph_of(&owned, "done");

        let result = graph.validate_snapshot();
        assert!(
            result.has(DiagnosticKind::MissingTarget),
            "the dangling edge is still reported: {result:?}"
        );
        assert!(
            !graph.blocked_state(2).is_blocked,
            "invalid data must not permanently freeze an issue"
        );
    }

    #[test]
    fn a_hand_edited_cyclic_file_terminates_instead_of_hanging() {
        // Write-time rejection makes this unreachable, but a hand-edited file
        // must not hang the TUI.
        let a = Owned::new(1, "A", "todo").blocking(2, "B");
        let b = Owned::new(2, "B", "todo").blocking(1, "A");
        let owned = vec![a, b];
        let graph = graph_of(&owned, "done");

        assert!(graph.validate_snapshot().has(DiagnosticKind::Cycle));
        let chain = graph.dependency_chain(1);
        assert!(
            chain.paths.iter().all(|p| p.len() <= owned.len()),
            "the visited-set guard must bound every path"
        );
    }

    // -- NFR-001: linear single pass ---------------------------------------

    #[test]
    fn a_ten_thousand_edge_graph_validates_in_one_pass() {
        const ISSUES: u32 = 2_000;
        const PER_ISSUE: u32 = 6;
        // Forward-only edges (lower index blocks higher) keep the graph acyclic,
        // so a clean verdict is the correct expectation.
        let mut owned: Vec<Owned> = (0..ISSUES)
            .map(|n| Owned::new(n + 1, &format!("Issue {n}"), "todo"))
            .collect();
        for n in 0..ISSUES {
            for k in 1..=PER_ISSUE {
                let target = n + k;
                if target < ISSUES {
                    owned[n as usize].push_block(target + 1, "Target");
                }
            }
        }
        let graph = graph_of(&owned, "done");
        assert!(
            graph.edge_count() >= 10_000,
            "expected a 10,000-edge graph, built {}",
            graph.edge_count()
        );

        // Measure structure (pass completed, correct result) rather than a
        // wall-clock bound so the suite does not go flaky on shared CI hardware.
        let result = graph.validate_snapshot();
        assert!(
            result.is_clean(),
            "a well-formed graph validates clean: {result:?}"
        );
        assert_eq!(graph.issue_count(), ISSUES as usize);
        assert_eq!(
            graph.identity_index_size(),
            ISSUES as usize,
            "one project-wide alias index covers the whole graph"
        );
        assert!(graph.blocked_state(2).is_blocked);
    }

    #[test]
    fn a_ten_thousand_issue_graph_scans_identity_once_regardless_of_endpoint_count() {
        const ISSUES: u32 = 10_000;
        let mut owned: Vec<Owned> = (0..ISSUES)
            .map(|index| {
                Owned::new(index + 1, &format!("Issue {index}"), "todo")
                    .with_id(&format!("A{index:07}"))
            })
            .collect();
        for index in 0..(ISSUES - 1) {
            owned[index as usize].push_block(index + 2, "Next");
        }

        let graph = graph_of(&owned, "done");
        assert_eq!(graph.edge_count(), ISSUES as usize - 1);
        assert_eq!(graph.identity_index_size(), ISSUES as usize);
        assert_eq!(
            graph.identity_nodes_scanned(),
            ISSUES as usize,
            "one index pass must cover every node, not one scan per edge endpoint"
        );
    }

    #[test]
    fn canonical_graph_reports_ambiguous_numbers_and_duplicate_ids_without_dropping_data() {
        let mut source = Owned::new(1, "Source", "todo").with_id("A1B2C3D4");
        source.relationships.push(Relationship {
            id: "rel_ambiguous".to_string(),
            from: IssueRef::Number(1),
            to: IssueRef::Number(7),
            kind: RelationKind::Related,
            display: String::new(),
        });
        let owned = vec![
            source,
            Owned::new(7, "First seven", "todo").with_id("B1B2C3D4"),
            Owned::new(7, "Second seven", "todo").with_id("C1B2C3D4"),
        ];
        let result = graph_of(&owned, "done").validate_snapshot();
        assert!(
            result.has(DiagnosticKind::AmbiguousTarget),
            "numeric aliases with two matches are diagnosed: {result:?}"
        );

        let duplicate = vec![
            Owned::new(1, "A", "todo").with_id("A1B2C3D4"),
            Owned::new(2, "B", "todo").with_id("A1B2C3D4"),
        ];
        let result = graph_of(&duplicate, "done").validate_snapshot();
        assert!(
            result.has(DiagnosticKind::DuplicateIdentity),
            "duplicate canonical ids are diagnosed: {result:?}"
        );
    }

    #[test]
    fn a_ten_thousand_node_chain_does_not_overflow_the_stack() {
        const DEPTH: u32 = 10_000;
        let mut owned: Vec<Owned> = (0..DEPTH)
            .map(|n| Owned::new(n + 1, &format!("Node {n}"), "todo"))
            .collect();
        for n in 0..DEPTH - 1 {
            owned[n as usize].push_block(n + 2, "Next");
        }
        let graph = graph_of(&owned, "done");
        // Iterative traversal: a recursive DFS would blow the stack here.
        assert!(graph.validate_snapshot().is_clean());
        let chain = graph.dependency_chain(1);
        assert!(chain.truncated, "the defensive node bound engages");
        assert!(
            graph
                .cycle_if_added(CanonicalEdge {
                    from: IssueRef::Number(DEPTH),
                    to: IssueRef::Number(1),
                    kind: RelationKind::Blocks
                })
                .is_some()
        );
    }

    // -- review round 4 regression -----------------------------------------

    #[test]
    fn d1_inverse_spellings_find_the_same_row() {
        // Stored: 1 blocks 2.
        let owned = vec![
            Owned::new(1, "A", "todo").blocking(2, "B"),
            Owned::new(2, "B", "todo"),
        ];
        let graph = graph_of(&owned, "done");
        let forward = graph
            .find_canonical(1, 2, RelationKind::Blocks)
            .map(|r| r.id.clone());
        let inverse = graph
            .find_canonical(2, 1, RelationKind::BlockedBy)
            .map(|r| r.id.clone());
        assert!(forward.is_some(), "the stored edge must be found");
        assert_eq!(
            forward, inverse,
            "1 blocks 2 and 2 blocked_by 1 name one relationship"
        );
        assert_ne!(
            forward,
            graph
                .find_canonical(1, 2, RelationKind::BlockedBy)
                .map(|r| r.id.clone()),
            "1 blocked_by 2 is the inverse of the stored edge, so it must not match"
        );
    }

    #[test]
    fn d1_related_is_found_from_either_orientation() {
        let mut two = Owned::new(2, "B", "todo");
        two.relationships
            .push(Relationship::new(2, 1, RelationKind::Related, "A"));
        let owned = vec![Owned::new(1, "A", "todo"), two];
        let graph = graph_of(&owned, "done");
        let a = graph
            .find_canonical(1, 2, RelationKind::Related)
            .map(|r| r.id.clone());
        let b = graph
            .find_canonical(2, 1, RelationKind::Related)
            .map(|r| r.id.clone());
        assert!(a.is_some(), "related is order-normalized, so it is found");
        assert_eq!(a, b);
    }

    #[test]
    fn d1_a_self_link_or_unrelated_pair_does_not_match() {
        let owned = vec![
            Owned::new(1, "A", "todo").blocking(2, "B"),
            Owned::new(2, "B", "todo"),
            Owned::new(3, "C", "todo"),
        ];
        let graph = graph_of(&owned, "done");
        assert!(graph.find_canonical(1, 1, RelationKind::Blocks).is_none());
        assert!(graph.find_canonical(1, 3, RelationKind::Blocks).is_none());
        assert!(graph.find_canonical(3, 1, RelationKind::Blocks).is_none());
        assert!(graph.find_canonical(1, 2, RelationKind::Related).is_none());
        assert!(
            graph.find_canonical(1, 2, RelationKind::Blocks).is_some(),
            "the real edge still resolves"
        );
    }

    #[test]
    fn d1_redundant_rows_resolve_to_the_same_row_every_time() {
        let one = Owned::new(1, "A", "todo").with_related(2, "B");
        let two = Owned::new(2, "B", "todo").with_related(1, "A");
        let owned = vec![one, two];
        let first = graph_of(&owned, "done")
            .find_canonical(1, 2, RelationKind::Related)
            .map(|r| r.id.clone());
        let second = graph_of(&owned, "done")
            .find_canonical(1, 2, RelationKind::Related)
            .map(|r| r.id.clone());
        assert!(first.is_some());
        assert_eq!(first, second, "the answer must be stable, not arbitrary");
    }

    #[test]
    fn d1_an_unknown_pair_returns_none() {
        let owned = vec![Owned::new(1, "A", "todo")];
        let graph = graph_of(&owned, "done");
        assert!(graph.find_canonical(1, 404, RelationKind::Blocks).is_none());
        assert!(graph.find_canonical(404, 1, RelationKind::Blocks).is_none());
    }

    // -- review round 2 regressions ---------------------------------------

    #[test]
    fn p1_related_reads_as_one_association_across_orientations() {
        // `related` is the only non-directional kind, so both authorings are
        // the same association. Normalization collapses them to one canonical
        // triple and the read side shows one entry.
        let one = Owned::new(1, "A", "todo").with_related(2, "B");
        let two = Owned::new(2, "B", "todo").with_related(1, "A");
        let owned = vec![one, two];
        let graph = graph_of(&owned, "done");
        assert_eq!(graph.related_to(1), vec![2], "one association, not two");
        assert_eq!(graph.related_to(2), vec![1]);
        assert_eq!(
            normalize_all([(1, 2, RelationKind::Related), (2, 1, RelationKind::Related),]).len(),
            1,
            "both authorings normalize to one canonical edge"
        );
    }

    // -- review round 3 regressions ---------------------------------------

    #[test]
    fn a3_no_stored_relationship_id_silently_stops_resolving() {
        // Two stored spellings of one association. Both ids must keep working:
        // the file is human-editable, so the user still holds both, and a
        // dropped row would make one of them a bare `unknown_relation`.
        let one = Owned::new(1, "A", "todo").with_related(2, "B");
        let two = Owned::new(2, "B", "todo").with_related(1, "A");
        let owned = vec![one, two];
        let graph = graph_of(&owned, "done");
        let ids: Vec<String> = graph
            .all_relationships()
            .iter()
            .filter(|r| r.kind == RelationKind::Related)
            .map(|r| r.id.clone())
            .collect();
        assert_eq!(ids.len(), 2, "both stored rows are retained");
        for id in &ids {
            assert!(
                graph.find_relationship(id).is_some(),
                "stored id {id} must still resolve"
            );
            assert!(
                !graph
                    .validate_edit(id, None, None)
                    .has(DiagnosticKind::UnknownRelation),
                "editing by a stored id must not report it unknown"
            );
        }
    }

    #[test]
    fn a3_the_blocked_adjacency_does_not_repeat_a_neighbour() {
        // Redundant rows are kept as rows, but the adjacency is a set.
        let mut one = Owned::new(1, "A", "todo");
        for _ in 0..3 {
            one.push_block(2, "B");
        }
        let owned = vec![one, Owned::new(2, "B", "todo")];
        let graph = graph_of(&owned, "done");
        assert_eq!(graph.blocks(1), &[2], "no repeated neighbour");
        assert_eq!(graph.blocked_by(2), &[1], "no repeated blocker");
        assert_eq!(
            graph.blocked_state(2).blockers.len(),
            1,
            "one blocker is reported once, not once per stored row"
        );
    }

    #[test]
    fn c_an_unconfigured_done_column_fails_closed() {
        // With no `done_column`, no column means "finished", so a blocker with
        // an empty status must still block rather than read as completed.
        let mut one = Owned::new(1, "A", "");
        one.push_block(2, "B");
        let owned = vec![one, Owned::new(2, "B", "todo")];
        let graph = graph_of(&owned, "");
        assert!(
            graph.blocked_state(2).is_blocked,
            "an unconfigured completion column must not mark anything done"
        );
    }

    #[test]
    fn p1_duplicates_orientation_is_preserved() {
        // `duplicates` is directional: these are two distinct claims.
        assert_eq!(
            normalize_all([
                (1, 2, RelationKind::Duplicates),
                (2, 1, RelationKind::Duplicates),
            ])
            .len(),
            2
        );
    }

    #[test]
    fn p2_an_edit_cannot_land_on_a_triple_another_edge_occupies() {
        let mut a = Owned::new(1, "A", "todo");
        a.push_block(2, "B");
        a.relationships
            .push(Relationship::new(1, 2, RelationKind::Related, "B"));
        let owned = vec![a, Owned::new(2, "B", "todo")];
        let graph = graph_of(&owned, "done");
        let blocks_id = graph
            .relationships_for(1)
            .iter()
            .find(|r| r.kind == RelationKind::Blocks)
            .expect("a blocks edge")
            .id
            .clone();

        let res = graph.validate_edit(&blocks_id, None, Some(RelationKind::Related));
        assert!(
            res.has(DiagnosticKind::ConflictingEdge),
            "re-kinding onto an occupied triple must be rejected: {res:?}"
        );
        assert!(
            res.errors
                .iter()
                .any(|d| d.message.contains("would store a second one")),
            "the message must name the duplicate case: {res:?}"
        );
    }

    #[test]
    fn p2_creating_an_edge_that_already_exists_stays_idempotent() {
        // The create path must NOT reject a re-assertion: `tix link` run twice
        // has to be a no-op, not a failure (data-model §2).
        let a = Owned::new(1, "A", "todo").blocking(2, "B");
        let owned = vec![a, Owned::new(2, "B", "todo")];
        let graph = graph_of(&owned, "done");
        assert!(
            graph.validate_create(1, 2, RelationKind::Blocks).is_clean(),
            "re-asserting an existing edge is the idempotent path"
        );
    }

    #[test]
    fn p3_p4_the_other_endpoint_is_returned_in_both_orientations() {
        // Edges authored from the far side, which is the case round 1 missed.
        let mut two = Owned::new(2, "B", "todo");
        two.relationships
            .push(Relationship::new(2, 1, RelationKind::Related, "A"));
        two.relationships
            .push(Relationship::new(2, 1, RelationKind::Duplicates, "A"));
        let owned = vec![Owned::new(1, "A", "todo"), two];
        let graph = graph_of(&owned, "done");

        // `related` is non-directional: both endpoints see each other.
        assert_eq!(graph.related_to(1), vec![2], "never the subject itself");
        assert_eq!(graph.related_to(2), vec![1]);
        // `duplicates` is directional, so a far-side edge contributes nothing.
        assert!(
            graph.duplicates_of(1).is_empty(),
            "a directional edge pointing at #1 does not mean #1 duplicates it: {:?}",
            graph.duplicates_of(1)
        );
        assert_eq!(graph.duplicates_of(2), vec![1]);
    }

    #[test]
    fn p5_the_blocked_adjacency_never_contains_the_subject() {
        // This is the invariant that makes the `blocker != subject` branch in
        // the resolution predicate unreachable. If a future change breaks it,
        // this fails rather than the branch silently carrying the load.
        let mut a = Owned::new(1, "A", "todo");
        a.relationships
            .push(Relationship::new(1, 1, RelationKind::Blocks, "A"));
        a.push_block(2, "B");
        let owned = vec![a, Owned::new(2, "B", "todo")];
        let graph = graph_of(&owned, "done");
        for number in [1, 2] {
            assert!(
                !graph.blocked_by(number).contains(&number),
                "issue #{number} must never appear in its own inbound blocks adjacency"
            );
        }
    }

    // -- review round 1 regressions ---------------------------------------

    #[test]
    fn r1_display_is_refreshed_when_the_target_is_renamed() {
        // The edge was created while #2 was titled "Old title".
        let a = Owned::new(1, "A", "todo").blocking(2, "Old title");
        let owned = vec![a, Owned::new(2, "New title", "todo")];
        let graph = graph_of(&owned, "done");
        assert_eq!(
            graph.relationships_for(1)[0].display,
            "blocks #2 New title",
            "a persisted display must not outlive the title it was built from"
        );
    }

    #[test]
    fn r1_a_dangling_edge_keeps_its_persisted_display() {
        // No target, so there is no title to rebuild the label from.
        let mut a = Owned::new(1, "A", "todo");
        a.relationships
            .push(Relationship::new(1, 404, RelationKind::Blocks, "gone"));
        let owned = vec![a];
        assert_eq!(
            graph_of(&owned, "done").relationships_for(1)[0].display,
            "blocks #404 gone"
        );
    }

    #[test]
    fn r2_a_self_link_is_reported_once_not_twice() {
        let mut a = Owned::new(1, "A", "todo");
        a.relationships
            .push(Relationship::new(1, 1, RelationKind::Blocks, "A"));
        let owned = vec![a];
        let graph = graph_of(&owned, "done");
        assert_eq!(graph.edge_count(), 1);
        assert_eq!(
            graph.relationships_for(1).len(),
            1,
            "a self-link has one endpoint, so it must be registered once"
        );
    }

    #[test]
    fn r3_an_issue_is_never_blocked_by_itself() {
        let mut a = Owned::new(1, "A", "todo");
        a.relationships
            .push(Relationship::new(1, 1, RelationKind::Blocks, "A"));
        let owned = vec![a];
        let graph = graph_of(&owned, "done");

        // Still visible as invalid data...
        assert!(graph.validate_snapshot().has(DiagnosticKind::SelfLink));
        // ...but never as a real edge, so it cannot make #1 its own blocker.
        assert_eq!(graph.blocks(1), [] as [u32; 0]);
        let state = graph.blocked_state(1);
        assert!(!state.is_blocked, "an issue must not block itself");
        assert_eq!(state.reason, "");
    }

    #[test]
    fn r4_validate_edit_does_not_hide_a_pre_existing_conflict() {
        // #1 -> #2 blocks, plus #1 -> #2 related: the data is already corrupt.
        let mut a = Owned::new(1, "A", "todo");
        a.push_block(2, "B");
        a.relationships
            .push(Relationship::new(1, 2, RelationKind::Related, "B"));
        let owned = vec![a, Owned::new(2, "B", "todo")];
        let graph = graph_of(&owned, "done");
        let blocks_id = graph
            .relationships_for(1)
            .iter()
            .find(|r| r.kind == RelationKind::Blocks)
            .expect("a blocks edge")
            .id
            .clone();

        assert!(
            graph
                .validate_snapshot()
                .has(DiagnosticKind::ConflictingEdge)
        );
        let edit = graph.validate_edit(&blocks_id, None, None);
        assert!(
            edit.has(DiagnosticKind::ConflictingEdge),
            "editing an unrelated field must not return a clean verdict on corrupt data: {edit:?}"
        );
    }

    #[test]
    fn r4_an_edit_does_not_conflict_with_itself() {
        let a = Owned::new(1, "A", "todo").blocking(2, "B");
        let owned = vec![a, Owned::new(2, "B", "todo"), Owned::new(3, "C", "todo")];
        let graph = graph_of(&owned, "done");
        let id = graph.relationships_for(1)[0].id.clone();

        assert!(
            graph.validate_edit(&id, None, None).is_clean(),
            "an edge never conflicts with itself"
        );
        assert!(
            graph.validate_edit(&id, Some(3), None).is_clean(),
            "retargeting to an unrelated issue is not a conflict"
        );
    }

    // -- diagnostics --------------------------------------------------------

    #[test]
    fn every_contract_diagnostic_kind_exists_with_its_exact_name() {
        let names: Vec<&str> = [
            DiagnosticKind::SelfLink,
            DiagnosticKind::MissingTarget,
            DiagnosticKind::ConflictingEdge,
            DiagnosticKind::Cycle,
            DiagnosticKind::UnknownKind,
            DiagnosticKind::UnknownRelation,
            DiagnosticKind::RetiredLinksKey,
        ]
        .iter()
        .map(|k| k.as_str())
        .collect();
        assert_eq!(
            names,
            [
                "self_link",
                "missing_target",
                "conflicting_edge",
                "cycle",
                "unknown_kind",
                "unknown_relation",
                "retired_links_key"
            ]
        );
    }

    #[test]
    fn validate_snapshot_never_returns_an_err() {
        // The signature itself is the assertion: there is no Result to unwrap.
        let owned = vec![Owned::new(1, "A", "todo").with_retired_links_key()];
        let result: RelationshipValidationResult = graph_of(&owned, "done").validate_snapshot();
        assert!(result.blocking());
    }

    #[test]
    fn diagnostics_sort_deterministically() {
        let mut a = RelationshipValidationResult::with(Diagnostic::self_link(1));
        a.merge(RelationshipValidationResult::with(
            Diagnostic::unknown_relation("rel_x"),
        ));
        let mut b = a.clone();
        b.sort_diagnostics();
        a.sort_diagnostics();
        assert_eq!(a, b);
    }

    #[test]
    fn blocked_reason_is_shared_by_every_surface() {
        let single = vec![ChainNode::new(1, "A")];
        assert_eq!(blocked_reason(&single), "Blocked by #1 A");
        let many = vec![ChainNode::new(1, "A"), ChainNode::new(2, "B")];
        assert_eq!(blocked_reason(&many), "Blocked by 2 issues: #1 A, #2 B");
    }

    #[test]
    fn cycle_paths_are_reported_once_regardless_of_starting_node() {
        let a = Owned::new(1, "A", "todo").blocking(2, "B");
        let b = Owned::new(2, "B", "todo").blocking(3, "C");
        let c = Owned::new(3, "C", "todo").blocking(1, "A");
        let owned = vec![a, b, c];
        let result = graph_of(&owned, "done").validate_snapshot();
        let cycles: Vec<&Diagnostic> = result
            .errors
            .iter()
            .filter(|d| d.kind == DiagnosticKind::Cycle)
            .collect();
        assert_eq!(
            cycles.len(),
            1,
            "one distinct cycle, one diagnostic: {result:?}"
        );
    }

    #[test]
    fn hand_edited_blocked_by_persisted_edges_still_block() {
        // A hand-edited file that persisted the `blocked_by` spelling must not
        // silently drop out of blocked state. `from: 1, to: 2, blocked_by` is
        // "1 is blocked by 2", so it normalizes to 2 blocking 1.
        let mut owner = Owned::new(2, "B", "todo");
        owner.relationships.push(Relationship {
            id: "rel_hand".to_string(),
            from: IssueRef::Number(1),
            to: IssueRef::Number(2),
            kind: RelationKind::BlockedBy,
            display: String::new(),
        });
        let owned = vec![Owned::new(1, "A", "todo"), owner];
        let graph = graph_of(&owned, "done");
        assert!(
            graph.blocked_state(1).is_blocked,
            "the normalized adjacency must still carry the edge"
        );
        assert_eq!(graph.blocks(2), &[1], "stored in canonical blocks form");
    }
}