adam_rs/

sheet.rs

//! The [`Sheet`] owns and manages a property model constraint graph.
//!
//! All cells and relationships are created through the sheet and are
//! destroyed when the sheet is dropped.
//!
//! Queries borrow declarations or describe a completed propagation; they do not
//! propagate implicitly. This graph combines a conditional relationship, a fixed
//! writer, a live source filter and a requirement.
//!
//! ```
//! use adam_rs::{CellKind, Filter, MatchExpr, Method, Requirement, Sheet};
//! use std::any::TypeId;
//! let mut sheet = Sheet::default();
//! let mode = sheet.add_source(true);
//! let limit = sheet.add_source(100_i32);
//! let a = sheet.add_cell(7_i32);
//! let b = sheet.add_cell(0_i32);
//! let out = sheet.add_cell(0_i32);
//! sheet.add_filter(a, Filter::range(TypeId::of::<i32>(), vec![limit],
//!     vec![TypeId::of::<i32>()],
//!     |v, args| Ok(Box::new((*v.downcast_ref::<i32>().unwrap())
//!         .clamp(0, *args[0].downcast_ref::<i32>().unwrap()))),
//!     |args| Some((Box::new(0_i32), Box::new(*args[0].downcast_ref::<i32>()?)))))?;
//! let rel = sheet.add_relationship(vec![Method::from_fn_1_1(a, b, |v: &i32| Ok(*v))])?;
//! let conditional = sheet.add_conditional(MatchExpr::cell(mode),
//!     vec![(vec![true], vec![rel])], vec![])?;
//! sheet.add_out(Method::from_fn_1_1(b, out, |v: &i32| Ok(*v)), vec![])?;
//! let check = sheet.add_requirement(b, Requirement::from_fn_1(b, |v: &i32| Ok(*v >= 0)))?;
//! sheet.validate()?;
//! sheet.write(a, 9_i32)?;
//! sheet.propagate()?;
//! assert_eq!(*sheet.read::<i32>(out)?, 9);
//! assert_eq!(*sheet.source::<i32>(a)?, 9);
//! assert_eq!(sheet.cell_type_id(a), Some(TypeId::of::<i32>()));
//! assert_eq!(sheet.cell_kind(out), Some(CellKind::Out));
//! assert_eq!(sheet.cells().count(), 5);
//! assert_eq!(sheet.relationships().count(), 2);
//! assert_eq!(sheet.cell_adj(b).unwrap().len(), 2);
//! assert_eq!(sheet.relationship_adj(rel), Some([a, b].as_slice()));
//! assert_eq!(sheet.method_inputs(rel, 0), Some([a].as_slice()));
//! assert_eq!(sheet.method_outputs(rel, 0), Some([b].as_slice()));
//! assert_eq!(sheet.selected_method(rel), Some(0));
//! assert!(sheet.is_source(a));
//! assert!(sheet.is_forced(b));
//! assert!(sheet.forced_cells().any(|id| id == b));
//! assert!(sheet.is_relationship_forced(rel));
//! assert!(sheet.forced_relationships().any(|id| id == rel));
//! assert_eq!(sheet.conditionals().collect::<Vec<_>>(), [conditional]);
//! assert_eq!(sheet.out_cells().collect::<Vec<_>>(), [out]);
//! assert_eq!(sheet.conditional_match_cells(conditional), Some([mode].as_slice()));
//! assert_eq!(sheet.conditional_branch_count(conditional), Some(1));
//! assert_eq!(sheet.conditional_branch_relationships(conditional, 0), Some([rel].as_slice()));
//! assert_eq!(sheet.conditional_default_relationships(conditional), Some([].as_slice()));
//! assert_eq!(sheet.conditional_active_branch(conditional)?, Some(0));
//! assert_eq!(sheet.filter_args(a), Some([limit].as_slice()));
//! assert_eq!(sheet.filter_dependents(limit), [a]);
//! assert!(matches!(sheet.filter_kind(a), Some(adam_rs::FilterKind::Range { .. })));
//! assert_eq!(sheet.filter_range::<i32>(a), Some((0, 100)));
//! assert!(sheet.filter_violation(a).is_none());
//! assert_eq!(sheet.filter_violated_cells().count(), 0);
//! assert!(sheet.filter_violation_cells().is_empty());
//! assert_eq!(sheet.cell_requirements(b), Some([check].as_slice()));
//! assert_eq!(sheet.requirement_cell(check), Some(b));
//! assert_eq!(sheet.requirement_inputs(check), Some([b].as_slice()));
//! assert!(sheet.cell_requirements_valid(b));
//! assert_eq!(sheet.violated_requirements(b).count(), 0);
//! assert!(sheet.contributing_cells(b).contains(&limit));
//! assert!(sheet.requirement_contributing_cells(check).contains(&a));
//! assert!(sheet.requirement_relevant_cells().contains(&a));
//! assert!(sheet.requirement_violation_cells().is_empty());
//! assert!(sheet.changed().any(|id| id == out));
//! sheet.clear_changed();
//! assert_eq!(sheet.changed().count(), 0);
//! # Ok::<(), adam_rs::Error>(())
//! ```
//!
//! # Forced, self-referencing, and reversible outcomes
//!
//! A cell has three distinct outcomes when a relationship determines it:
//!
//! - **Conditionally forced.** The forcing relationship supplies the effective
//!   value, [`Sheet::read`] reports it, and the cell's [`Sheet::source`]
//!   aspiration is unchanged. The cell keeps the priority it had when forcing
//!   began, and an explicit write while forced replaces that priority with the
//!   write's recency. When the last forcing cause ends, the retained aspiration
//!   and priority compete in the first plan that can use the cell, so no
//!   additional edit is needed.
//! - **Self-referencing.** A method that reads and writes the same cell seeds
//!   from its aspiration and honors that edit's priority. Forcing and release
//!   do not erase either.
//! - **Ordinary reversible.** A losing cell receives the winner's value as its
//!   new aspiration with a derived priority. It does not revive an earlier
//!   value when the relationship later deactivates, and forcing a cell that
//!   was already derived retains that derived value and priority.
//!
//! ```
//! use adam_rs::{MatchExpr, Method, Sheet};
//! let mut sheet = Sheet::default();
//! let mode = sheet.add_cell(0_i32);
//! let input = sheet.add_cell(30_i32);
//! let a = sheet.add_cell(1_i32);
//! let b = sheet.add_cell(2_i32);
//! let force = sheet.add_relationship(vec![Method::from_fn_1_1(input, a, |v: &i32| Ok(*v))])?;
//! let reversible = sheet.add_relationship(vec![
//!     Method::from_fn_1_1(a, b, |v: &i32| Ok(*v)),
//!     Method::from_fn_1_1(b, a, |v: &i32| Ok(*v)),
//! ])?;
//! sheet.add_conditional(
//!     MatchExpr::cell(mode),
//!     vec![(vec![1_i32], vec![force]), (vec![2_i32], vec![reversible])],
//!     vec![],
//! )?;
//! sheet.write(b, 22_i32)?;
//! sheet.write(a, 11_i32)?;
//! sheet.write(mode, 1_i32)?;
//! sheet.propagate()?;
//! assert!(sheet.is_forced(a));
//! assert_eq!((*sheet.read::<i32>(a)?, *sheet.source::<i32>(a)?), (30, 11));
//!
//! // Releasing `a` keeps its newer edit, so `a` wins the reversible relationship.
//! sheet.write(mode, 2_i32)?;
//! sheet.propagate()?;
//! assert!(sheet.is_source(a));
//! assert_eq!(*sheet.read::<i32>(b)?, 11);
//! # Ok::<(), adam_rs::Error>(())
//! ```

use std::any::{Any, TypeId};
use std::collections::{HashMap, HashSet};
use std::rc::Rc;

use slotmap::SlotMap;

use crate::{
    cell::{CellData, CellId, CellKind},
    conditional::{Branch, ConditionalData, ConditionalId, MatchExpr, MatchSource},
    error::{Error, ErrorSite},
    filter::{Filter, FilterKind, FilterViolation},
    planner::{Plan, PlanStep, SeedSignatures, SeedSource, Seeds},
    relationship::{Method, RelationshipData, RelationshipId},
    requirement::{Requirement, RequirementData, RequirementId},
};

mod cached;
mod dependency;
mod prerequisites;

#[cfg(test)]
use cached::ReuseStats;
use cached::{CachedPlan, PreparedPlan};

/// Owns a complete property model constraint graph.
///
/// Create cells with [`Sheet::add_cell`], define multi-way constraints with
/// [`Sheet::add_relationship`], write input values with [`Sheet::write`],
/// then call [`Sheet::propagate`] to update derived cells. Propagation automatically
/// reuses eligible prepared plans or plans again when necessary.
///
/// After a mutating operation returns an error, the sheet's state is unspecified.
/// Do not inspect or reuse it; discard it and rebuild from host-owned inputs.
///
/// # Example
///
/// ```rust
/// use adam_rs::{Sheet, Method};
///
/// let mut sheet = Sheet::new();
/// let a = sheet.add_cell(0_i32);
/// let b = sheet.add_cell(0_i32);
/// sheet.add_relationship(vec![Method::from_fn_1_1(a, b, |x: &i32| Ok(*x * 2))]).unwrap();
/// sheet.write(a, 3_i32).unwrap();
/// assert_eq!(*sheet.read::<i32>(a).unwrap(), 3);
/// ```
pub struct Sheet {
    pub(crate) cells: SlotMap<CellId, CellData>,
    pub(crate) relationships: SlotMap<RelationshipId, RelationshipData>,
    pub(crate) changed_cells: Vec<CellId>,
    /// Monotonic counter incremented by both `add_cell` and `write`; cells added
    /// later and cells written later have strictly higher strength, making the
    /// default method-selection direction deterministic.
    next_strength: u64,
    /// The prepared snapshot from the last successful `propagate()` call, retained so the
    /// display-only accessors ([`Sheet::is_source`], [`Sheet::selected_method`],
    /// [`Sheet::is_forced`]) can report which method the planner picked for each
    /// relationship without re-planning.
    last_plan: Option<Rc<PreparedPlan>>,
    /// Number of cells with a priority retained through conditional forcing.
    remembered_strength_count: usize,
    /// Eligible prepared unconditional plan, independent of the display snapshot.
    pre_plan_cache: Option<CachedPlan>,
    /// Eligible prepared final active plan, independent of the unconditional plan.
    main_plan_cache: Option<CachedPlan>,
    /// Ordered method signatures retained until the graph structure changes.
    seed_signatures: Option<Rc<SeedSignatures>>,
    /// Counts actual preparation and reuse-validation work for this sheet only.
    #[cfg(test)]
    reuse_stats: ReuseStats,
    /// All conditionals registered on this sheet.
    pub(crate) conditionals: SlotMap<ConditionalId, ConditionalData>,
    /// Union of all RelationshipIds assigned to any conditional branch or default.
    /// Used to exclude them from the unconditional active set.
    pub(crate) conditional_relationships: HashSet<RelationshipId>,
    /// All requirements registered on this sheet, across all cells.
    requirements: SlotMap<RequirementId, RequirementData>,
    /// Requirements that evaluated `false` as of the last `propagate()` call, grouped
    /// by cell. Sparse: a cell with no entry had all its requirements hold.
    last_requirement_violations: HashMap<CellId, Vec<RequirementId>>,
    /// Filter violations recorded against a derived value as of the last `propagate()`
    /// call.
    last_filter_violations: HashMap<CellId, FilterViolation>,
    /// Reverse index of `filter_args`: for each cell, the live cells whose filter
    /// references it as one of its dynamic arguments. Built incrementally in
    /// `add_filter`; cells and filters are never removed once added, so this needs no
    /// invalidation, matching every other per-cell set/map `Sheet` already maintains
    /// for its own lifetime.
    filter_dependents: HashMap<CellId, Vec<CellId>>,
    /// Whether static guard independence has been validated for the current structure.
    guard_independent: bool,
}

/// A conditional's evaluated match value: borrowed (existing cell, no allocation) or owned
/// (freshly computed by a [`MatchExpr`] function).
enum MatchValue<'a> {
    Ref(&'a dyn Any),
    Owned(Box<dyn Any>),
}

impl MatchValue<'_> {
    /// Returns the contained value as a type-erased reference, regardless of variant.
    fn as_dyn(&self) -> &dyn Any {
        match self {
            MatchValue::Ref(r) => *r,
            MatchValue::Owned(b) => b.as_ref(),
        }
    }
}

/// Provenance needed to decide whether a staged guard-cone step can be reused.
///
/// Reuse is intentionally conservative: a step is reusable only when the final plan selects the
/// same method, producer path, source/derived classification, and seed inputs. A mismatch returns
/// `Error::Conflict` rather than guessing a compatible assignment or reusing stale values.
#[derive(Clone, PartialEq, Eq)]
struct StepProvenance {
    input_producers: Vec<Option<PlanStep>>,
    seed_inputs: Vec<CellId>,
    source_producer: Option<PlanStep>,
    output_classes: Vec<(CellId, OutputClassification)>,
}

/// Whether a selected step writes a cell's staged value as source or derived.
#[derive(Clone, Copy, PartialEq, Eq)]
enum OutputClassification {
    /// The write replaces the staged source value.
    Source,
    /// The write shadows the staged source value.
    Derived,
}

/// Selected producer paths for every step and output in one execution plan.
#[derive(Default)]
struct PlanProvenance {
    steps: HashMap<PlanStep, StepProvenance>,
    output_producers: HashMap<CellId, PlanStep>,
}

/// Transactional propagation state whose writes remain private until commit.
///
/// Staged derived values override staged sources, which override live sources.
/// Each replaced source receives a fresh version; absent sources have version zero.
/// `changed` contains each written cell exactly once and has the same members as
/// `changed_set`. Dropping an uncommitted stage discards every owned result.
#[derive(Default)]
struct PropagationStage {
    sources: HashMap<CellId, Box<dyn Any>>,
    /// Version of each staged source value; an absent cell reads its live source (version 0).
    source_versions: HashMap<CellId, u64>,
    last_source_version: u64,
    derived: HashMap<CellId, Box<dyn Any>>,
    executed_methods: HashSet<(RelationshipId, usize)>,
    executed_filters: HashSet<CellId>,
    step_provenance: HashMap<PlanStep, StepProvenance>,
    changed: Vec<CellId>,
    changed_set: HashSet<CellId>,
}

impl PropagationStage {
    /// Returns the staged effective value for `id`, ignoring any live sheet `derived`.
    fn effective<'a>(&'a self, cells: &'a SlotMap<CellId, CellData>, id: CellId) -> &'a dyn Any {
        self.derived
            .get(&id)
            .map(|value| value.as_ref())
            .or_else(|| self.sources.get(&id).map(|value| value.as_ref()))
            .unwrap_or_else(|| cells[id].source.as_ref())
    }

    /// Returns the staged source value for `id`, ignoring any live sheet `derived`.
    fn source<'a>(&'a self, cells: &'a SlotMap<CellId, CellData>, id: CellId) -> &'a dyn Any {
        self.sources
            .get(&id)
            .map(|value| value.as_ref())
            .unwrap_or_else(|| cells[id].source.as_ref())
    }

    /// Returns the staged source value for `id` with a version identifying that value.
    ///
    /// - Postcondition: two calls return equal versions only if no staged source write or
    ///   reclassification changed `id`'s source value between them.
    fn seed_source<'a>(
        &'a self,
        cells: &'a SlotMap<CellId, CellData>,
        id: CellId,
    ) -> SeedSource<'a> {
        SeedSource {
            value: self.source(cells, id),
            version: self.source_versions.get(&id).copied().unwrap_or(0),
        }
    }

    /// Records a new staged source value for `id` under a fresh version.
    fn insert_source(&mut self, id: CellId, value: Box<dyn Any>) {
        self.last_source_version += 1;
        self.source_versions.insert(id, self.last_source_version);
        self.sources.insert(id, value);
    }

    /// Shadows the source for derived writes or replaces it for ordinary writes.
    fn write(&mut self, id: CellId, value: Box<dyn Any>, shadow: bool) {
        if shadow {
            self.derived.insert(id, value);
        } else {
            self.insert_source(id, value);
            self.derived.remove(&id);
        }
        if self.changed_set.insert(id) {
            self.changed.push(id);
        }
    }

    /// Reclassifies an existing staged output for the general plan's shadowing rule.
    ///
    /// - Precondition: `id` has a staged source or derived value.
    fn reclassify(&mut self, id: CellId, shadow: bool) {
        if shadow {
            if let Some(value) = self.sources.remove(&id) {
                self.source_versions.remove(&id);
                self.derived.insert(id, value);
            }
        } else if let Some(value) = self.derived.remove(&id) {
            self.insert_source(id, value);
        }
    }
}

impl Sheet {
    /// Creates an empty sheet with no cells or relationships.
    ///
    /// # Examples
    /// See [`Sheet`]'s example.
    pub fn new() -> Self {
        Sheet {
            cells: SlotMap::with_key(),
            relationships: SlotMap::with_key(),
            changed_cells: Vec::new(),
            next_strength: 0,
            last_plan: None,
            remembered_strength_count: 0,
            pre_plan_cache: None,
            main_plan_cache: None,
            seed_signatures: None,
            #[cfg(test)]
            reuse_stats: ReuseStats::default(),
            conditionals: SlotMap::with_key(),
            conditional_relationships: HashSet::new(),
            requirements: SlotMap::with_key(),
            last_requirement_violations: HashMap::new(),
            last_filter_violations: HashMap::new(),
            filter_dependents: HashMap::new(),
            guard_independent: true,
        }
    }

    /// Registers a cell with an initial value and returns a stable handle.
    ///
    /// The cell's `TypeId` is fixed at creation time; subsequent `write` and
    /// `read` calls that use a different type will return `Error::TypeMismatch`.
    ///
    /// Each call increments the sheet's internal strength counter and sets bit 63
    /// of the result. This partitions the strength space: written/added cells always
    /// have higher strength than derived cells, ensuring stability across conditional
    /// branch switches.
    ///
    /// - Complexity: Amortized O(1), plus O(A) when invalidation releases the final
    ///   owners of prepared artifacts of total size A.
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn add_cell<T: Any + PartialEq + 'static>(&mut self, value: T) -> CellId {
        self.invalidate_prepared_plans();
        self.next_strength += 1;
        let strength = self.next_strength | (1u64 << 63);
        self.cells.insert(CellData {
            source: Box::new(value),
            derived: None,
            type_id: TypeId::of::<T>(),
            strength,
            remembered_strength: None,
            changed: false,
            adj: Vec::new(),
            eq_fn: |a, b| a.downcast_ref::<T>() == b.downcast_ref::<T>(),
            filter: None,
            kind: CellKind::Cell,
            requirements: Vec::new(),
        })
    }

    /// Registers a cell that can never be claimed as any method's output — always a
    /// planner source, forever.
    ///
    /// - Complexity: Amortized O(1), plus O(A) when invalidation releases the final
    ///   owners of prepared artifacts of total size A.
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn add_source<T: Any + PartialEq + 'static>(&mut self, value: T) -> CellId {
        let id = self.add_cell(value);
        self.cells[id].kind = CellKind::Source;
        id
    }

    /// Returns the fixed concrete type of a live cell, or `None` for an invalid ID.
    ///
    /// # Examples
    ///
    /// ```
    /// use std::any::TypeId;
    /// use adam_rs::{CellId, Sheet};
    /// let mut sheet = Sheet::new();
    /// let cell = sheet.add_cell(7i32);
    /// assert_eq!(sheet.cell_type_id(cell), Some(TypeId::of::<i32>()));
    /// assert_eq!(sheet.cell_type_id(CellId::default()), None);
    /// ```
    pub fn cell_type_id(&self, id: CellId) -> Option<TypeId> {
        self.cells.get(id).map(|cell| cell.type_id)
    }

    /// Returns `id`'s fixed cell kind.
    ///
    /// Returns `None` if `id` is not a live cell in this sheet.
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn cell_kind(&self, id: CellId) -> Option<CellKind> {
        self.cells.get(id).map(|c| c.kind)
    }

    /// Registers a relationship defined by a non-empty list of methods.
    ///
    /// All methods are validated: their declared `TypeId`s must match the
    /// registered cells, and each method must have at least one output. A method
    /// with no inputs is explicitly allowed: it defines a fixed point (a constant,
    /// independent of every other cell) rather than a derivation.
    /// On success the `RelationshipId` is added to each adjacent cell's adjacency list.
    ///
    /// A cell that appears in both a method's inputs and its outputs is a self-referencing
    /// cell and is explicitly allowed.
    ///
    /// # Errors
    ///
    /// - `Error::InvalidMethod` — `methods` is empty, or a method has no outputs.
    /// - `Error::MismatchedMethodCells` — some method's `inputs ∪ outputs` differs
    ///   from another method's in the same relationship.
    /// - `Error::InvalidMethodOutputs` — a method's own `outputs` list names a cell
    ///   more than once, or two methods in the same relationship have identical or
    ///   nested `outputs` sets. Overlapping non-nested output sets are allowed.
    /// - `Error::InvalidId` — a `CellId` in any method is not found in this sheet.
    /// - `Error::TypeMismatch` — a method's declared `TypeId` does not match the
    ///   cell's registered `TypeId`.
    /// - `Error::InvalidCellKind` — a method's output cell is `Source`- or `Out`-kind.
    ///
    /// Guard independence is checked by [`Sheet::validate`] and by [`Sheet::propagate`],
    /// not by this mutator.
    ///
    /// - Complexity: O(m² × c) where m is the total number of methods and c is the
    ///   maximum number of cells per method, due to pairwise output-set comparison,
    ///   plus O(A) when invalidation releases the final owners of prepared artifacts
    ///   of total size A.
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn add_relationship(&mut self, methods: Vec<Method>) -> Result<RelationshipId, Error> {
        if methods.is_empty() {
            return Err(Error::InvalidMethod { sites: vec![] });
        }

        for (idx, method) in methods.iter().enumerate() {
            if method.outputs.is_empty() {
                return Err(Error::InvalidMethod {
                    sites: vec![ErrorSite::MethodIndex(idx)],
                });
            }

            // declared type counts must match cell-id counts
            if method.inputs.len() != method.input_types.len()
                || method.outputs.len() != method.output_types.len()
            {
                return Err(Error::InvalidMethod {
                    sites: vec![ErrorSite::MethodIndex(idx)],
                });
            }

            for (&cell_id, &declared) in method.inputs.iter().zip(method.input_types.iter()) {
                let cell = self.cells.get(cell_id).ok_or(Error::InvalidId)?;
                if cell.type_id != declared {
                    return Err(Error::TypeMismatch {
                        expected: cell.type_id,
                        found: declared,
                        sites: vec![ErrorSite::MethodIndex(idx)],
                    });
                }
            }

            for (&cell_id, &declared) in method.outputs.iter().zip(method.output_types.iter()) {
                let cell = self.cells.get(cell_id).ok_or(Error::InvalidId)?;
                if cell.kind != CellKind::Cell {
                    return Err(Error::InvalidCellKind {
                        sites: vec![ErrorSite::MethodIndex(idx), ErrorSite::Cell(cell_id)],
                    });
                }
                if cell.type_id != declared {
                    return Err(Error::TypeMismatch {
                        expected: cell.type_id,
                        found: declared,
                        sites: vec![ErrorSite::MethodIndex(idx)],
                    });
                }
            }
        }

        // Every method in a relationship must reference the same set of cells: the
        // union of a method's inputs and outputs (as a set) must be identical across
        // all methods. A relationship models a fixed set of related cells; methods
        // differ only in which subset of that set they treat as outputs (using the
        // "ignore an input" pattern), not in which cells they reference at all.
        let cell_sets: Vec<HashSet<CellId>> = methods
            .iter()
            .map(|m| m.inputs.iter().chain(m.outputs.iter()).copied().collect())
            .collect();
        if let Some(rel_idx) = cell_sets[1..].iter().position(|set| set != &cell_sets[0]) {
            let diverging = rel_idx + 1;
            let mut sites = vec![ErrorSite::MethodIndex(diverging), ErrorSite::MethodIndex(0)];
            // Symmetric difference of the two cell sets, in a stable order.
            for &c in cell_sets[diverging].symmetric_difference(&cell_sets[0]) {
                sites.push(ErrorSite::Cell(c));
            }
            return Err(Error::MismatchedMethodCells { sites });
        }

        // A method's own outputs must be duplicate-free, and no two methods in a
        // relationship may claim identical or nested output sets: the planner's
        // matching stage treats a method's pure-output set as an indivisible claim,
        // so nested claims would make that claim ambiguous while still allowing
        // overlapping non-nested sets.
        let mut seen_output_sets: Vec<(usize, HashSet<CellId>, &[CellId])> =
            Vec::with_capacity(methods.len());
        for (idx, method) in methods.iter().enumerate() {
            let output_set: HashSet<CellId> = method.outputs.iter().copied().collect();
            if output_set.len() != method.outputs.len() {
                // A cell repeated within this method's own outputs. Report each
                // distinct repeated cell once, no matter how many times it repeats.
                let mut sites = vec![ErrorSite::MethodIndex(idx)];
                let mut seen = HashSet::new();
                let mut reported = HashSet::new();
                for &o in &method.outputs {
                    if !seen.insert(o) && reported.insert(o) {
                        sites.push(ErrorSite::Cell(o));
                    }
                }
                return Err(Error::InvalidMethodOutputs { sites });
            }
            for (earlier, earlier_set, earlier_outputs) in &seen_output_sets {
                if output_set == *earlier_set
                    || (output_set.len() < earlier_set.len() && output_set.is_subset(earlier_set))
                    || (earlier_set.len() < output_set.len() && earlier_set.is_subset(&output_set))
                {
                    let mut sites = vec![
                        ErrorSite::MethodIndex(idx),
                        ErrorSite::MethodIndex(*earlier),
                    ];
                    let offending_outputs: &[CellId] = if output_set.len() <= earlier_set.len() {
                        &method.outputs
                    } else {
                        earlier_outputs
                    };
                    for &o in offending_outputs {
                        sites.push(ErrorSite::Cell(o));
                    }
                    return Err(Error::InvalidMethodOutputs { sites });
                }
            }
            seen_output_sets.push((idx, output_set, &method.outputs));
        }

        // Collect the union of all adjacent cells in insertion order, deduplicated.
        let mut adj: Vec<CellId> = Vec::new();
        let mut seen: std::collections::HashSet<CellId> = std::collections::HashSet::new();
        for method in &methods {
            for &cell_id in method.inputs.iter().chain(method.outputs.iter()) {
                if seen.insert(cell_id) {
                    adj.push(cell_id);
                }
            }
        }

        self.invalidate_prepared_plans();
        let rel_id = self.relationships.insert(RelationshipData { methods, adj });

        for &cell_id in &self.relationships[rel_id].adj {
            if let Some(cell) = self.cells.get_mut(cell_id)
                && !cell.adj.contains(&rel_id)
            {
                cell.adj.push(rel_id);
            }
        }

        self.guard_independent = false;
        Ok(rel_id)
    }

    /// Registers a conditional that activates relationships based on the value of a match
    /// subject: either a single existing cell, or a [`MatchExpr`] computed from multiple
    /// input cells.
    ///
    /// Each element of `branches` is `(keys, relationships)`: when the match subject's
    /// value equals any key in `keys`, the branch's `relationships` are added to the active
    /// set for `propagate`. Branches are evaluated in definition order; first match wins.
    /// `default` holds relationships activated when no branch matches; pass an empty `Vec`
    /// for no default.
    ///
    /// # Errors
    ///
    /// - `Error::InvalidId` — the match subject references a cell not in this sheet.
    /// - `Error::TypeMismatch` — (expression match subject only) an input cell's registered
    ///   type doesn't match the expression's declared type for that input.
    /// - `Error::InvalidConditional` — the match subject's output type does not match `T`;
    ///   a referenced relationship does not exist; a relationship already appears in
    ///   another conditional branch; or a branch has no keys.
    /// - `Error::InvalidCellKind` — a referenced relationship is a fixed `Out` writer.
    ///
    /// Guard independence is checked by [`Sheet::validate`] and by [`Sheet::propagate`],
    /// not by this mutator.
    ///
    /// - Complexity: O(I + K + E) time and O(K + R) space for match inputs I,
    ///   branch keys K, referenced relationships R and their total method-output
    ///   edges E, plus O(A) when invalidation releases final prepared artifacts of size A.
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn add_conditional<T: Any + PartialEq + 'static>(
        &mut self,
        source: MatchExpr,
        branches: Vec<(Vec<T>, Vec<RelationshipId>)>,
        default: Vec<RelationshipId>,
    ) -> Result<ConditionalId, Error> {
        match &source.0 {
            MatchSource::Cell(cell) => {
                let cell_data = self.cells.get(*cell).ok_or(Error::InvalidId)?;
                if cell_data.type_id != TypeId::of::<T>() {
                    return Err(Error::InvalidConditional {
                        sites: vec![ErrorSite::Cell(*cell)],
                    });
                }
            }
            MatchSource::Expr(expr) => {
                if expr.output_type != TypeId::of::<T>() {
                    return Err(Error::InvalidConditional { sites: vec![] });
                }
                for (&cell_id, &declared) in expr.inputs.iter().zip(expr.input_types.iter()) {
                    let cell_data = self.cells.get(cell_id).ok_or(Error::InvalidId)?;
                    if cell_data.type_id != declared {
                        return Err(Error::TypeMismatch {
                            expected: cell_data.type_id,
                            found: declared,
                            sites: vec![],
                        });
                    }
                }
            }
        };

        // Collect and validate all relationship IDs (branches + default).
        let all_rels: Vec<RelationshipId> = branches
            .iter()
            .flat_map(|(_, rels)| rels.iter().copied())
            .chain(default.iter().copied())
            .collect();

        for &rel_id in &all_rels {
            let relationship = self
                .relationships
                .get(rel_id)
                .ok_or(Error::InvalidConditional { sites: vec![] })?;
            if let Some(output) = relationship
                .methods
                .iter()
                .flat_map(|method| &method.outputs)
                .find(|&&id| self.cells[id].kind == CellKind::Out)
            {
                return Err(Error::InvalidCellKind {
                    sites: vec![ErrorSite::Relationship(rel_id), ErrorSite::Cell(*output)],
                });
            }
            if self.conditional_relationships.contains(&rel_id) {
                return Err(Error::InvalidConditional {
                    sites: vec![ErrorSite::Relationship(rel_id)],
                });
            }
        }

        // Validate branch keys are non-empty.
        for (keys, _) in &branches {
            if keys.is_empty() {
                return Err(Error::InvalidConditional { sites: vec![] });
            }
        }

        // Check for duplicate relationship IDs within this call.
        let mut seen: HashSet<RelationshipId> = HashSet::new();
        for &rel_id in &all_rels {
            if !seen.insert(rel_id) {
                return Err(Error::InvalidConditional {
                    sites: vec![ErrorSite::Relationship(rel_id)],
                });
            }
        }

        // Type-erase branch keys.
        let typed_branches: Vec<Branch> = branches
            .into_iter()
            .map(|(keys, relationships)| Branch {
                keys: keys
                    .into_iter()
                    .map(|k| Box::new(k) as Box<dyn Any>)
                    .collect(),
                relationships,
            })
            .collect();

        // Record all relationships as conditional so they are excluded from the
        // unconditional active set in propagate().
        self.invalidate_prepared_plans();
        for &rel_id in &all_rels {
            self.conditional_relationships.insert(rel_id);
        }

        let id = self.conditionals.insert(ConditionalData {
            source: source.0,
            branches: typed_branches,
            default,
        });

        self.guard_independent = false;
        Ok(id)
    }

    /// Returns `true` if `id` is already claimed as some existing method's output —
    /// i.e. it cannot legally become an `out` cell's writer target, since that would
    /// leave two producers claiming the same cell.
    ///
    /// - Complexity: O(E) for all registered method-output edges E.
    fn cell_has_prior_use(&self, id: CellId) -> bool {
        self.relationships
            .values()
            .any(|rel| rel.methods.iter().any(|m| m.outputs.contains(&id)))
    }

    /// Attaches a requirement to `cell` and returns its stable ID.
    ///
    /// `requirement.inputs` may be any cells in the sheet, not only `cell` itself.
    /// The predicate runs during propagation, so callers can report false results
    /// separately from propagation failures.
    ///
    /// # Errors
    ///
    /// - `Error::InvalidId` — `cell`, or one of `requirement`'s input cells, is not a
    ///   live cell in this sheet.
    /// - `Error::TypeMismatch` — an input's declared type does not match its cell's
    ///   registered type.
    /// - `Error::InvalidRequirement` — the input signature is invalid.
    ///
    /// - Complexity: O(k) where k is `requirement`'s input count, plus O(A) when
    ///   invalidation releases the final owners of prepared artifacts of total size A.
    ///
    /// # Examples
    ///
    /// ```
    /// use adam_rs::{Requirement, Sheet};
    /// let mut sheet = Sheet::new();
    /// let cell = sheet.add_cell(1_i32);
    /// let id = sheet.add_requirement(cell, Requirement::from_fn_1(cell, |x: &i32| Ok(*x > 0)))?;
    /// assert_eq!(sheet.cell_requirements(cell), Some([id].as_slice()));
    /// # Ok::<(), adam_rs::Error>(())
    /// ```
    pub fn add_requirement(
        &mut self,
        cell: CellId,
        requirement: Requirement,
    ) -> Result<RequirementId, Error> {
        self.cells.get(cell).ok_or(Error::InvalidId)?;
        if requirement.inputs.len() != requirement.input_types.len() {
            return Err(Error::InvalidRequirement);
        }
        for (&input_id, &declared) in requirement
            .inputs
            .iter()
            .zip(requirement.input_types.iter())
        {
            let input_cell = self.cells.get(input_id).ok_or(Error::InvalidId)?;
            if input_cell.type_id != declared {
                return Err(Error::TypeMismatch {
                    expected: input_cell.type_id,
                    found: declared,
                    sites: vec![],
                });
            }
        }

        self.invalidate_prepared_plans();
        let rid = self.requirements.insert(RequirementData {
            cell,
            inputs: requirement.inputs,
            function: requirement.function,
        });
        self.cells[cell].requirements.push(rid);
        Ok(rid)
    }

    /// Registers `writer` as the sole producer of its one output cell, which becomes
    /// an `out` cell: always derived by `writer`, never `write()`-able, but otherwise
    /// an ordinary, freely-referenceable cell. `requirements` are attached to that
    /// cell one at a time, in order, via [`Sheet::add_requirement`].
    ///
    /// # Errors
    ///
    /// - `Error::InvalidOutput` — `writer` does not have exactly one output cell.
    /// - `Error::InvalidCellKind` — the writer's output cell is already `Source` or
    ///   `Out` kind, or already claimed as some existing method's output.
    /// - Any error [`Sheet::add_relationship`] or [`Sheet::add_requirement`] can
    ///   return.
    ///
    /// - Postcondition: not atomic — if `add_requirement` fails partway through
    ///   `requirements`, the output cell is left `Out`-kind, `writer` is already
    ///   registered as its producer, and every requirement before the failing one is
    ///   already attached; none of this is rolled back on error.
    ///
    /// - Complexity: O(k + i + m²×c) where k is the number of requirements and i is
    ///   their total input count, plus the
    ///   cost of `add_relationship` for `writer` alone (m = 1 method, c = cells in
    ///   that method), plus O(A) when invalidation releases the final owners of
    ///   prepared artifacts of total size A.
    ///
    /// # Examples
    ///
    /// ```
    /// use adam_rs::{Method, Requirement, Sheet};
    /// let mut sheet = Sheet::new();
    /// let input = sheet.add_cell(1_i32);
    /// let output = sheet.add_cell(0_i32);
    /// let id = sheet.add_out(
    ///     Method::from_fn_1_1(input, output, |x: &i32| Ok(*x)),
    ///     vec![Requirement::from_fn_1(output, |x: &i32| Ok(*x > 0))],
    /// )?;
    /// assert_eq!(id, output);
    /// sheet.propagate()?;
    /// assert!(sheet.cell_requirements_valid(output));
    /// # Ok::<(), adam_rs::Error>(())
    /// ```
    pub fn add_out(
        &mut self,
        writer: Method,
        requirements: Vec<Requirement>,
    ) -> Result<CellId, Error> {
        let out_cell = writer
            .outputs
            .first()
            .copied()
            .ok_or(Error::InvalidOutput)?;
        self.add_out_writer(writer)?;
        for requirement in requirements {
            self.add_requirement(out_cell, requirement)?;
        }
        Ok(out_cell)
    }

    /// Registers the sole output writer and returns its native relationship identity.
    ///
    /// Reports the same writer validation errors as [`Self::add_out`].
    /// - Complexity: O(r × e + i) for prior relationships r, edges e and writer inputs i.
    pub(crate) fn add_out_writer(&mut self, writer: Method) -> Result<RelationshipId, Error> {
        if writer.outputs.len() != 1 {
            return Err(Error::InvalidOutput);
        }
        let out_cell = writer.outputs[0];

        let kind = self.cells.get(out_cell).ok_or(Error::InvalidId)?.kind;
        if kind != CellKind::Cell || self.cell_has_prior_use(out_cell) {
            return Err(Error::InvalidCellKind { sites: vec![] });
        }

        let relationship = self.add_relationship(vec![writer])?;
        self.cells[out_cell].kind = CellKind::Out;
        Ok(relationship)
    }

    /// Attaches `filter` to `cell`.
    ///
    /// Never evaluates `filter`'s function — attaching a filter is not a fresh
    /// external input, so it never changes `cell`'s current effective value. The next
    /// full [`Sheet::propagate`] call conforms `cell` via the planner's
    /// `PlanStep::FilterReclamp` step; until then, `read()` reflects whatever `cell`
    /// held before this call.
    ///
    /// # Errors
    ///
    /// - `Error::InvalidId` — `cell`, or one of `filter`'s argument cells, is not a
    ///   live cell in this sheet.
    /// - `Error::InvalidFilter` — `cell` already has a filter, `filter`'s own value
    ///   type does not match `cell`'s registered type, or `filter`'s argument list
    ///   names `cell` itself.
    /// - `Error::TypeMismatch` — an argument cell's registered type does not match the
    ///   type `filter` declared for it.
    ///
    /// Guard independence is checked by [`Sheet::validate`] and by [`Sheet::propagate`],
    /// not by this mutator.
    ///
    /// - Complexity: O(a) where a is the number of filter argument cells, plus O(A)
    ///   when invalidation releases the final owners of prepared artifacts of total
    ///   size A.
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn add_filter(&mut self, cell: CellId, filter: Filter) -> Result<(), Error> {
        let cell_type = self.cells.get(cell).ok_or(Error::InvalidId)?.type_id;
        if self.cells[cell].filter.is_some() {
            return Err(Error::InvalidFilter);
        }
        if filter.0.value_type != cell_type {
            return Err(Error::InvalidFilter);
        }
        if filter.0.args.contains(&cell) {
            return Err(Error::InvalidFilter);
        }
        for (&arg_id, &declared) in filter.0.args.iter().zip(filter.0.arg_types.iter()) {
            let arg_cell = self.cells.get(arg_id).ok_or(Error::InvalidId)?;
            if arg_cell.type_id != declared {
                return Err(Error::TypeMismatch {
                    expected: arg_cell.type_id,
                    found: declared,
                    sites: vec![],
                });
            }
        }

        self.invalidate_prepared_plans();
        for &arg in &filter.0.args {
            self.filter_dependents.entry(arg).or_default().push(cell);
        }
        self.cells[cell].filter = Some(filter.0);
        self.guard_independent = false;
        Ok(())
    }

    /// Returns the argument cells of `id`'s filter, in declaration order.
    ///
    /// Returns `None` if `id` is not a live cell in this sheet, or has no filter.
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn filter_args(&self, id: CellId) -> Option<&[CellId]> {
        self.cells
            .get(id)?
            .filter
            .as_ref()
            .map(|f| f.args.as_slice())
    }

    /// Returns the live cells whose filter references `id` as one of its dynamic
    /// arguments — the reverse of a filter's own argument list ([`Sheet::filter_args`]).
    ///
    /// - Postcondition: empty if no live cell's filter references `id`.
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn filter_dependents(&self, id: CellId) -> &[CellId] {
        self.filter_dependents
            .get(&id)
            .map(Vec::as_slice)
            .unwrap_or(&[])
    }

    /// Returns the kind of validation/derivation `id`'s filter performs, if it has one.
    ///
    /// Returns `None` if `id` is not a live cell in this sheet, or has no filter.
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn filter_kind(&self, id: CellId) -> Option<&FilterKind> {
        self.cells.get(id)?.filter.as_ref().map(|f| &f.kind)
    }

    /// Returns `id`'s filter's current `(lo, hi)` bounds, if it has a [`FilterKind::Range`]
    /// filter.
    ///
    /// Resolves the filter's argument cells' current effective values via the same path
    /// [`Sheet::add_filter`] already uses, then calls the filter's `bounds` function.
    ///
    /// Returns `None` if `id` is not a live cell in this sheet, has no filter, its filter's
    /// kind isn't [`FilterKind::Range`], its bounds have a different type from `T`,
    /// or the range expression fails to evaluate against
    /// the filter's current argument values (e.g. a fallible arithmetic op in a range
    /// endpoint) — the same degraded-to-`None` outcome as any other reason no live bounds
    /// are available right now.
    ///
    /// - Complexity: O(a) where a is the number of the filter's argument cells.
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn filter_range<T: Any>(&self, id: CellId) -> Option<(T, T)> {
        let filter = self.cells.get(id)?.filter.as_ref()?;
        let FilterKind::Range { bounds } = &filter.kind else {
            return None;
        };
        let args: Vec<&dyn Any> = filter
            .args
            .iter()
            .map(|&a| self.cells[a].effective())
            .collect();
        let (lo, hi) = bounds(&args)?;
        Some((*lo.downcast::<T>().ok()?, *hi.downcast::<T>().ok()?))
    }

    /// Returns the filter violation recorded for `id` as of the last full
    /// `propagate()` call, if any.
    ///
    /// - Postcondition: `None` if `id` has no filter, `id`'s filter's last-checked
    ///   value held, or no full `propagate()` has run since `id` was last a plain
    ///   external write.
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn filter_violation(&self, id: CellId) -> Option<&FilterViolation> {
        self.last_filter_violations.get(&id)
    }

    /// Iterates cells whose filter is currently violated, as of the last full
    /// `propagate()` call.
    ///
    /// - Complexity: O(n) where n is the number of currently-violated filters.
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn filter_violated_cells(&self) -> impl Iterator<Item = CellId> + '_ {
        self.last_filter_violations.keys().copied()
    }

    /// Returns the set of root cells currently determining a violated filter's own
    /// value or any of its argument values, as of the last full `propagate()` call —
    /// the same "which upstream cells caused this" query
    /// `requirement_contributing_cells`/`requirement_violation_cells` already provide
    /// for `Requirement`.
    ///
    /// - Postcondition: empty if no filter is currently violated.
    /// - Complexity: O(sum of `contributing_cells` cost over every violated filter and
    ///   its argument cells).
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn filter_violation_cells(&self) -> HashSet<CellId> {
        let mut result = HashSet::new();
        for cell_id in self.filter_violated_cells() {
            result.extend(self.contributing_cells(cell_id));
            if let Some(args) = self.filter_args(cell_id) {
                for &arg in args {
                    result.extend(self.contributing_cells(arg));
                }
            }
        }
        result
    }

    /// Returns the requirements attached to `id`, in attachment order.
    ///
    /// Returns `None` if `id` is not a live cell in this sheet.
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn cell_requirements(&self, id: CellId) -> Option<&[RequirementId]> {
        self.cells.get(id).map(|c| c.requirements.as_slice())
    }

    /// Returns the cell requirement `id` is attached to.
    ///
    /// Returns `None` if `id` is not a live requirement in this sheet.
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn requirement_cell(&self, id: RequirementId) -> Option<CellId> {
        self.requirements.get(id).map(|c| c.cell)
    }

    /// Returns the cells requirement `id` reads.
    ///
    /// Returns `None` if `id` is not a live requirement in this sheet.
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn requirement_inputs(&self, id: RequirementId) -> Option<&[CellId]> {
        self.requirements.get(id).map(|c| c.inputs.as_slice())
    }

    /// Returns `true` if every requirement on `id` held as of the last `propagate()`
    /// call.
    ///
    /// Returns `false` if no propagation has run yet. Also returns `true` for an
    /// `id` that is not a live cell in this sheet, since no requirement can have
    /// failed for a cell that doesn't exist.
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn cell_requirements_valid(&self, id: CellId) -> bool {
        if self.last_plan.is_none() {
            return false;
        }
        !self.last_requirement_violations.contains_key(&id)
    }

    /// Iterates the requirements on `id` that evaluated to `false` as of the last
    /// `propagate()` call.
    ///
    /// - Postcondition: empty if `id`'s requirements all held, `id` is not a live
    ///   cell in this sheet, or no propagation has run yet.
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn violated_requirements(&self, id: CellId) -> impl Iterator<Item = RequirementId> + '_ {
        self.last_requirement_violations
            .get(&id)
            .into_iter()
            .flatten()
            .copied()
    }

    /// Returns the set of root cells that could determine `id`'s value for *some* choice of
    /// cell strengths, as of the last `propagate()` call.
    ///
    /// A cell is a root candidate for `current` whenever some *active* relationship
    /// adjacent to `current` has a method producing it — not just the one method the
    /// current strengths happen to have selected: a different strength ordering could pick
    /// a different method of that same relationship, making any of its other cells the
    /// source instead. So every method (of every active relationship touching `current`)
    /// with `current` among its outputs contributes its inputs to the walk, not only the
    /// currently-selected one. A cell outside [`Sheet::is_forced`]'s pure-output
    /// classification contributes its own stored aspiration. This includes a
    /// self-referencing input even when a mandatory writer prevents the cell from
    /// remaining unclaimed: its seed can still depend on that aspiration.
    ///
    /// Every visited cell is also checked against every conditional in the sheet: if any of
    /// that conditional's branches (or its default) has a method whose outputs include the
    /// visited cell, the conditional's match cell is added as a contributor too, and is
    /// itself traced recursively. This covers both an active producer that happens to
    /// belong to a conditional branch, and a cell with *no* active producer specifically
    /// because the branch that would define it isn't the one currently selected (that
    /// absence is itself a fact controlled by the match cell, not an indication that the
    /// match cell is irrelevant).
    ///
    /// A cell that can remain a source also contributes its dynamic filter arguments:
    /// the filter determines its effective value. Filters on outputs claimed in every
    /// acyclic assignment, including self-referencing outputs, only diagnose values
    /// and do not add value dependencies.
    ///
    /// Eligibility searches use the candidate's complete input/output relationship
    /// component within the last successful active set. That completed assignment
    /// witnesses feasibility of the independent components. Registered methods are
    /// never replaced or removed, so writes, appended structure and failed
    /// propagation preserve this witness; newly registered relationships stay outside
    /// these assignment searches until successful propagation publishes another
    /// active set. Filter arguments and potential conditional contributors still
    /// come from the current registered graph.
    ///
    /// - Postcondition: returns `{id}` if no propagation has run yet, or if `id` is not
    ///   forced and no active or conditional relationship or dynamic filter could produce it.
    ///
    /// - Complexity: O(N · (R·M·K² + B·M·K)) where N is the number of cells reachable from `id`
    ///   (including conditional match cells), R is the number of relationships adjacent to
    ///   a visited cell, M is the maximum number of methods per relationship, K is
    ///   the maximum input/output count per method, and B is the
    ///   total number of branch/default relationships across all conditionals, plus the
    ///   number of traversed filter argument edges. Each visited non-forced filtered
    ///   cell with dynamic arguments that is not currently a source adds at most one
    ///   exact eligibility search after expected linear traversal of that candidate's
    ///   component adjacency (including inactive adjacency entries). Each search takes
    ///   expected O(T + U · (1 + A · K²)) time, where T is relationship storage slots
    ///   scanned, A is active relationships in that component, and U counts that
    ///   search's recursive calls and examined method candidates. U is bounded by
    ///   O(1 + M + … + M^A), including partial checks when M = 1; disconnected
    ///   components do not multiply its search tree. Debug builds add O(G) validation
    ///   during each component discovery, where G is prepared active relationships.
    ///   Traversal storage is O(N + E) for visited cells and queued dependency edges E,
    ///   plus visited component cells/relationships and O(1 + A · (1 + K)) auxiliary
    ///   storage for one eligibility search. Repeated queries do not cache searches.
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn contributing_cells(&self, id: CellId) -> HashSet<CellId> {
        if self.last_plan.is_none() {
            return HashSet::from([id]);
        }
        let mut result = HashSet::new();
        let mut visited: HashSet<CellId> = HashSet::new();
        let mut stack = vec![id];
        while let Some(current) = stack.pop() {
            if !visited.insert(current) {
                continue;
            }

            for match_cell in self.conditionals_potentially_producing(current) {
                stack.push(match_cell);
            }

            if !self.is_forced(current) {
                result.insert(current);
                if let Some(prepared) = &self.last_plan
                    && let Some(args) = self.filter_args(current)
                    && !args.is_empty()
                    && (self.is_source(current) || {
                        let component = crate::planner::active_relationship_component(
                            &self.cells,
                            &self.relationships,
                            &prepared.active,
                            current,
                        );
                        crate::planner::can_be_source(&self.relationships, &component, current)
                    })
                {
                    stack.extend(args.iter().copied());
                }
            }

            let Some(cell) = self.cells.get(current) else {
                continue;
            };
            for &rel_id in &cell.adj {
                if !self.is_relationship_active(rel_id) {
                    continue;
                }
                for method in &self.relationships[rel_id].methods {
                    if !method.outputs.contains(&current) {
                        continue;
                    }
                    for &input in &method.inputs {
                        if method.outputs.contains(&input) {
                            result.insert(input);
                        } else {
                            stack.push(input);
                        }
                    }
                }
            }
        }
        result
    }

    /// Returns `true` if `rel_id` was part of the active relationship set for the last
    /// successful `propagate()` call — an unconditional relationship is always active; a conditional
    /// branch/default relationship is active only while its conditional currently selects
    /// it.
    ///
    /// Returns `false` if no propagation has run yet.
    fn is_relationship_active(&self, rel_id: RelationshipId) -> bool {
        self.last_plan
            .as_ref()
            .is_some_and(|plan| plan.active.contains(&rel_id))
    }

    /// Returns the match cells of every conditional with at least one branch (or default)
    /// relationship that touches `cell` (as an input or output of any of its methods) —
    /// every conditional whose branch choice currently determines, or could determine,
    /// `cell`'s value or whether it has an active producer at all.
    ///
    /// - Complexity: O(B) where B is the total number of branch/default relationships
    ///   across all conditionals.
    fn conditionals_potentially_producing(&self, cell: CellId) -> Vec<CellId> {
        self.conditionals
            .values()
            .filter(|cond| {
                cond.branches
                    .iter()
                    .flat_map(|branch| branch.relationships.iter())
                    .chain(cond.default.iter())
                    .any(|&rel_id| self.relationships[rel_id].adj.contains(&cell))
            })
            .flat_map(|cond| cond.match_cells().iter().copied())
            .collect()
    }

    /// Returns the union of [`Sheet::contributing_cells`] over requirement `id`'s own
    /// declared inputs.
    ///
    /// Returns an empty set if `id` is not a live requirement in this sheet.
    ///
    /// - Complexity: The sum of [`Self::contributing_cells`] costs over the requirement's
    ///   inputs, with O(N) space for their union of N root cells.
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn requirement_contributing_cells(&self, id: RequirementId) -> HashSet<CellId> {
        let Some(requirement) = self.requirements.get(id) else {
            return HashSet::new();
        };
        requirement
            .inputs
            .iter()
            .flat_map(|&input| self.contributing_cells(input))
            .collect()
    }

    /// Returns the union of `contributing_cells` over every cell with at least one
    /// requirement — the set of cells currently determining at least one
    /// requirement-checked value, as of the last `propagate()` call.
    ///
    /// - Postcondition: empty if no cell in the sheet has any requirements.
    /// - Complexity: O(sum of `contributing_cells` cost over every cell with
    ///   requirements).
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn requirement_relevant_cells(&self) -> HashSet<CellId> {
        self.cells
            .iter()
            .filter(|(_, c)| !c.requirements.is_empty())
            .flat_map(|(id, _)| self.contributing_cells(id))
            .collect()
    }

    /// Returns the union of `requirement_contributing_cells` over every requirement
    /// that evaluated `false` as of the last `propagate()` call, across every cell
    /// in the sheet.
    ///
    /// - Postcondition: empty if no requirement anywhere in the sheet currently
    ///   fails.
    /// - Complexity: O(sum of `requirement_contributing_cells` cost over every
    ///   violated requirement).
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn requirement_violation_cells(&self) -> HashSet<CellId> {
        self.cells
            .keys()
            .flat_map(|id| self.violated_requirements(id))
            .flat_map(|rid| self.requirement_contributing_cells(rid))
            .collect()
    }

    /// Writes a value to a cell, incrementing the cell's write-recency strength.
    ///
    /// Each successful `write` increments a global monotonic counter and assigns
    /// the new value to `cell.strength`, so the most-recently-written cell always
    /// has the highest strength.
    ///
    /// - Postcondition: any pending derived override is cleared, so the written value is immediately visible via `read()`.
    /// - Complexity: Expected O(1) validation and phase-membership work, plus O(A)
    ///   when a claimed-cell write releases the final owners of prepared artifacts
    ///   of total size A, excluding destruction of replaced values.
    ///
    /// # Errors
    ///
    /// - `Error::InvalidId` — `id` is not a cell in this sheet.
    /// - `Error::TypeMismatch` — `T` does not match the cell's registered `TypeId`.
    /// - `Error::InvalidCellKind` — `id` is `Out`-kind.
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn write<T: Any + 'static>(&mut self, id: CellId, value: T) -> Result<(), Error> {
        if self.cells.get(id).is_some_and(|c| c.kind == CellKind::Out) {
            return Err(Error::InvalidCellKind { sites: vec![] });
        }
        let cell_type = self.cells.get(id).ok_or(Error::InvalidId)?.type_id;
        if cell_type != TypeId::of::<T>() {
            return Err(Error::TypeMismatch {
                expected: cell_type,
                found: TypeId::of::<T>(),
                sites: vec![],
            });
        }

        self.invalidate_after_write(id);
        self.last_filter_violations.remove(&id);
        self.next_strength += 1;
        let cell = &mut self.cells[id];
        cell.strength = self.next_strength | (1u64 << 63);
        if cell.remembered_strength.is_some() {
            cell.remembered_strength = Some(cell.strength);
        }
        cell.source = Box::new(value);
        cell.derived = None;
        Ok(())
    }

    /// Returns a shared reference to the cell's effective current value: its derived
    /// override if one exists, otherwise its source (last written) value.
    ///
    /// # Errors
    ///
    /// - `Error::InvalidId` — `id` is not a cell in this sheet.
    /// - `Error::TypeMismatch` — `T` does not match the cell's registered `TypeId`.
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn read<T: Any + 'static>(&self, id: CellId) -> Result<&T, Error> {
        let cell = self.cells.get(id).ok_or(Error::InvalidId)?;
        if cell.type_id != TypeId::of::<T>() {
            return Err(Error::TypeMismatch {
                expected: cell.type_id,
                found: TypeId::of::<T>(),
                sites: vec![],
            });
        }
        Ok(cell
            .effective()
            .downcast_ref::<T>()
            .expect("type checked above"))
    }

    /// Returns the raw `source` slot: the last value written via `write()`/`add_cell`,
    /// ignoring any `derived` override produced by a self-referencing method or a
    /// conditionally forced relationship. For an ordinary (unshadowed) derived cell,
    /// `propagate()` writes straight into this same slot, so `source()` agrees with
    /// `read()`; the two diverge only for cells currently shadowed.
    ///
    /// # Errors
    ///
    /// - `Error::InvalidId` — `id` is not a cell in this sheet.
    /// - `Error::TypeMismatch` — `T` does not match the cell's registered `TypeId`.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use adam_rs::Sheet;
    ///
    /// let mut sheet = Sheet::new();
    /// let a = sheet.add_cell(3_i32);
    /// sheet.write(a, 8_i32).unwrap();
    /// assert_eq!(*sheet.source::<i32>(a).unwrap(), 8);
    /// ```
    pub fn source<T: Any + 'static>(&self, id: CellId) -> Result<&T, Error> {
        let cell = self.cells.get(id).ok_or(Error::InvalidId)?;
        if cell.type_id != TypeId::of::<T>() {
            return Err(Error::TypeMismatch {
                expected: cell.type_id,
                found: TypeId::of::<T>(),
                sites: vec![],
            });
        }
        Ok(cell.source.downcast_ref::<T>().expect("type checked above"))
    }

    /// Iterates over cells updated during the most recent successful `propagate()` call.
    ///
    /// This includes cells written by selected methods and cells that reverted to their
    /// source values because the relationship that had been shadowing them (self-referencing
    /// or conditionally forced) is no longer producing them this round (Phase 5), even though
    /// no method wrote to them this round. It does not attempt to compare old/new values for
    /// equality.
    ///
    /// - Complexity: O(n) where n is the number of changed cells.
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn changed(&self) -> impl Iterator<Item = CellId> + '_ {
        self.changed_cells.iter().copied()
    }

    /// Clears the changed-cell set and resets each cell's `changed` flag.
    ///
    /// Call after processing the results of `propagate()`.
    ///
    /// - Complexity: O(n) where n is the number of changed cells.
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn clear_changed(&mut self) {
        for id in std::mem::take(&mut self.changed_cells) {
            if let Some(cell) = self.cells.get_mut(id) {
                cell.changed = false;
            }
        }
    }

    /// Validates static guard independence for the current sheet structure.
    ///
    /// A filter's argument cells and a conditional's match cells must not depend on any
    /// cell governed by that filter or conditional in the static dependency graph. A
    /// successful call records the current structure as validated.
    ///
    /// # Errors
    ///
    /// - `Error::DependencyCycle` — a guard edge lies on a cycle in the static
    ///   dependency graph.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use adam_rs::{Filter, Method, Sheet};
    ///
    /// let mut sheet = Sheet::new();
    /// let limit = sheet.add_cell(10_i32);
    /// let value = sheet.add_cell(5_i32);
    /// let copy = sheet.add_cell(0_i32);
    /// sheet
    ///     .add_relationship(vec![Method::from_fn_1_1(value, copy, |x: &i32| Ok(*x))])
    ///     .unwrap();
    /// sheet
    ///     .add_filter(value, Filter::from_fn_1(limit, |v: &i32, hi: &i32| Ok((*v).min(*hi))))
    ///     .unwrap();
    /// sheet.validate().unwrap();
    /// ```
    ///
    /// - Complexity: O(1) when no structural mutation has happened since the last
    ///   successful validation; otherwise O(V + E), where V is the number of cells and
    ///   E is the number of static method and guard edges.
    pub fn validate(&mut self) -> Result<(), Error> {
        if self.guard_independent {
            return Ok(());
        }
        if let Some(path) = self.guard_violation() {
            return Err(Error::DependencyCycle {
                sites: path.into_sites(),
            });
        }
        self.guard_independent = true;
        Ok(())
    }

    /// Iterates all live cell IDs in the sheet.
    ///
    /// - Complexity: O(n) where n is the number of cells.
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn cells(&self) -> impl Iterator<Item = CellId> + '_ {
        self.cells.keys()
    }

    /// Iterates all live relationship IDs in the sheet.
    ///
    /// - Complexity: O(n) where n is the number of relationships.
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn relationships(&self) -> impl Iterator<Item = RelationshipId> + '_ {
        self.relationships.keys()
    }

    /// Returns the relationships adjacent to `id`.
    ///
    /// Returns `None` if `id` is not a live cell in this sheet.
    ///
    /// - Complexity: O(1).
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn cell_adj(&self, id: CellId) -> Option<&[RelationshipId]> {
        self.cells.get(id).map(|c| c.adj.as_slice())
    }

    /// Returns the cells adjacent to `id` (union across all methods).
    ///
    /// Returns `None` if `id` is not a live relationship in this sheet.
    ///
    /// - Complexity: O(1).
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn relationship_adj(&self, id: RelationshipId) -> Option<&[CellId]> {
        self.relationships.get(id).map(|r| r.adj.as_slice())
    }

    /// Evaluates conditional `cond`'s current live match value.
    ///
    /// # Errors
    ///
    /// - `Error::MethodFailed` — the match subject is a [`MatchExpr`] whose function
    ///   returned an error; its site identifies the executing conditional.
    ///
    /// - Complexity: O(I) time and space for expression inputs I, plus callback cost.
    fn evaluate_match_source(
        &self,
        id: ConditionalId,
        cond: &ConditionalData,
    ) -> Result<MatchValue<'_>, Error> {
        match &cond.source {
            MatchSource::Cell(id) => Ok(MatchValue::Ref(self.cells[*id].effective())),
            MatchSource::Expr(expr) => {
                let args: Vec<&dyn Any> = expr
                    .inputs
                    .iter()
                    .map(|&id| self.cells[id].effective())
                    .collect();
                let value = (expr.function)(&args).map_err(|error| Error::MethodFailed {
                    error,
                    sites: vec![ErrorSite::Conditional(id)],
                })?;
                Ok(MatchValue::Owned(value))
            }
        }
    }

    /// Evaluates conditional `cond` against staged propagation state.
    ///
    /// Uses `stage`'s writes first, then falls back to each cell's `source` value,
    /// matching the state visible after Phase 0 excludes old derived overrides and any
    /// pre-plan steps already staged.
    ///
    /// # Errors
    ///
    /// - `Error::MethodFailed` — the match subject is a [`MatchExpr`] whose function
    ///   returned an error; its site identifies the executing conditional.
    ///
    /// - Complexity: O(I) time and space for expression inputs I, plus callback cost.
    fn evaluate_match_source_staged<'a>(
        &'a self,
        id: ConditionalId,
        cond: &ConditionalData,
        stage: &'a PropagationStage,
    ) -> Result<MatchValue<'a>, Error> {
        match &cond.source {
            MatchSource::Cell(id) => Ok(MatchValue::Ref(stage.effective(&self.cells, *id))),
            MatchSource::Expr(expr) => {
                let args: Vec<&dyn Any> = expr
                    .inputs
                    .iter()
                    .map(|&id| stage.effective(&self.cells, id))
                    .collect();
                let value = (expr.function)(&args).map_err(|error| Error::MethodFailed {
                    error,
                    sites: vec![ErrorSite::Conditional(id)],
                })?;
                Ok(MatchValue::Owned(value))
            }
        }
    }

    /// Returns the equality function used to compare `cond`'s match value against branch
    /// keys: the match cell's own `eq_fn` for a plain match subject, or the expression's
    /// captured `eq_fn` for a computed one.
    fn match_eq_fn(&self, cond: &ConditionalData) -> fn(&dyn Any, &dyn Any) -> bool {
        match &cond.source {
            MatchSource::Cell(id) => self.cells[*id].eq_fn,
            MatchSource::Expr(expr) => expr.eq_fn,
        }
    }

    /// Builds the active relationship set against staged propagation state.
    ///
    /// Every conditional reads `stage`'s writes first and otherwise falls back to cell
    /// `source` values rather than any live
    /// `derived` override already present on the sheet.
    ///
    /// # Errors
    ///
    /// - `Error::MethodFailed` — an expression-sourced conditional's function returned an
    ///   error.
    fn build_active_set_staged(
        &self,
        stage: &PropagationStage,
    ) -> Result<HashSet<RelationshipId>, Error> {
        let mut active: HashSet<RelationshipId> = self
            .relationships
            .keys()
            .filter(|id| !self.conditional_relationships.contains(id))
            .collect();

        for (id, cond) in &self.conditionals {
            let value = self.evaluate_match_source_staged(id, cond, stage)?;
            let value_ref = value.as_dyn();
            let eq_fn = self.match_eq_fn(cond);

            let mut matched = false;
            for branch in &cond.branches {
                if branch.keys.iter().any(|key| eq_fn(value_ref, key.as_ref())) {
                    for &rel_id in &branch.relationships {
                        active.insert(rel_id);
                    }
                    matched = true;
                    break;
                }
            }
            if !matched {
                for &rel_id in &cond.default {
                    active.insert(rel_id);
                }
            }
        }

        Ok(active)
    }

    /// Records the actual dependency producers and write classifications for `plan`.
    ///
    /// - Complexity: expected O(V + E), where V is the number of selected steps and E is
    ///   the number of method inputs, outputs, and filter arguments.
    fn plan_provenance(&self, plan: &Plan) -> PlanProvenance {
        let mut provenance = PlanProvenance::default();
        let mut effective_producers = HashMap::new();
        let mut source_producers = HashMap::new();

        for &step in &plan.execution_order {
            let step_provenance = match step {
                PlanStep::Method(rel_id, method_index) => {
                    let method = &self.relationships[rel_id].methods[method_index];
                    let method_inputs: HashSet<CellId> = method.inputs.iter().copied().collect();
                    let method_outputs: HashSet<CellId> = method.outputs.iter().copied().collect();
                    let mut input_producers = Vec::with_capacity(method.inputs.len());
                    let mut seed_inputs = Vec::new();
                    for &input in &method.inputs {
                        if method_outputs.contains(&input) {
                            seed_inputs.push(input);
                            input_producers.push(None);
                        } else {
                            input_producers.push(effective_producers.get(&input).copied());
                        }
                    }
                    let output_classes: Vec<_> = method
                        .outputs
                        .iter()
                        .map(|&output| {
                            (
                                output,
                                if method_inputs.contains(&output)
                                    || plan.forced_outputs.contains(&output)
                                {
                                    OutputClassification::Derived
                                } else {
                                    OutputClassification::Source
                                },
                            )
                        })
                        .collect();
                    for &(output, classification) in &output_classes {
                        effective_producers.insert(output, step);
                        if classification == OutputClassification::Source {
                            source_producers.insert(output, step);
                        }
                    }
                    StepProvenance {
                        input_producers,
                        seed_inputs,
                        source_producer: None,
                        output_classes,
                    }
                }
                PlanStep::FilterReclamp(cell) => {
                    let filter = self.cells[cell]
                        .filter
                        .as_ref()
                        .expect("plan() only emits FilterReclamp for a filtered cell");
                    let input_producers = filter
                        .args
                        .iter()
                        .map(|input| effective_producers.get(input).copied())
                        .collect();
                    let step_provenance = StepProvenance {
                        input_producers,
                        seed_inputs: Vec::new(),
                        source_producer: source_producers.get(&cell).copied(),
                        output_classes: vec![(cell, OutputClassification::Derived)],
                    };
                    effective_producers.insert(cell, step);
                    step_provenance
                }
            };
            provenance.steps.insert(step, step_provenance);
        }
        provenance.output_producers = effective_producers;
        provenance
    }

    /// Checks that a staged prerequisite step has identical selected producer paths in both plans.
    ///
    /// - Postcondition: `true` implies the selected method/filter, its input producers,
    ///   seed inputs, source producer, and output classifications all match.
    /// - Complexity: O(I + O) for the step's input and output provenance lengths.
    fn prerequisite_step_is_compatible(
        &self,
        pre_plan: &PlanProvenance,
        final_plan: &PlanProvenance,
        step: PlanStep,
        stage: &PropagationStage,
    ) -> bool {
        let Some(staged) = stage.step_provenance.get(&step) else {
            return false;
        };
        pre_plan.steps.get(&step) == Some(staged) && final_plan.steps.get(&step) == Some(staged)
    }

    /// Returns concrete cells and relationships implicated by a staged-step mismatch.
    ///
    /// - Complexity: O(K) sites for the step's cells and producer edges.
    fn conflict_sites_for_step(
        &self,
        step: PlanStep,
        pre_plan: &PlanProvenance,
        final_plan: &PlanProvenance,
    ) -> Vec<ErrorSite> {
        let mut sites = Vec::new();
        let mut seen_sites = HashSet::new();
        let mut add_site = |site| {
            if seen_sites.insert(site) {
                sites.push(site);
            }
        };
        let mut cells = Vec::new();

        match step {
            PlanStep::Method(rel_id, method_index) => {
                add_site(ErrorSite::Relationship(rel_id));
                add_site(ErrorSite::Method(rel_id, method_index));
                let method = &self.relationships[rel_id].methods[method_index];
                cells.extend(method.inputs.iter().copied());
                cells.extend(method.outputs.iter().copied());
            }
            PlanStep::FilterReclamp(cell) => {
                cells.push(cell);
                if let Some(filter) = &self.cells[cell].filter {
                    cells.extend(filter.args.iter().copied());
                }
            }
        }

        for provenance in [pre_plan.steps.get(&step), final_plan.steps.get(&step)]
            .into_iter()
            .flatten()
        {
            for producer in provenance
                .input_producers
                .iter()
                .copied()
                .flatten()
                .chain(provenance.source_producer)
            {
                Self::add_step_relationship_site(producer, &mut add_site);
            }
        }
        for cell in cells {
            add_site(ErrorSite::Cell(cell));
            for plan in [pre_plan, final_plan] {
                if let Some(&producer) = plan.output_producers.get(&cell) {
                    Self::add_step_relationship_site(producer, &mut add_site);
                }
            }
        }
        sites
    }

    /// Adds the relationship site associated with a selected method producer.
    fn add_step_relationship_site(step: PlanStep, add_site: &mut impl FnMut(ErrorSite)) {
        match step {
            PlanStep::Method(rel_id, _) => add_site(ErrorSite::Relationship(rel_id)),
            PlanStep::FilterReclamp(cell) => add_site(ErrorSite::Cell(cell)),
        }
    }

    /// Executes `execution_order` once into transactional staged state.
    ///
    /// A method or filter step already evaluated by the conditional pre-plan reuses
    /// its staged result when the general plan contains the same compatible step.
    /// This is an internal optimization, not a callback invocation guarantee.
    /// Filter failures remain non-fatal and leave the staged cell untouched.
    ///
    /// - Precondition: each step belongs to this graph and has matching plan provenance.
    /// - Complexity: O(s × k²) structural work for s steps with at most k input/output
    ///   cells, plus callback costs and storage for staged output values.
    ///
    /// # Errors
    ///
    /// - `Error::MethodFailed` — a `PlanStep::Method` step's function returned an error,
    ///   or the method produced a different number of outputs than declared.
    /// - `Error::TypeMismatch` — a `PlanStep::Method` step's output runtime type does
    ///   not match the cell's registered type.
    fn execute_plan_staged(
        &self,
        execution_order: &[PlanStep],
        seeds: &Seeds,
        forced_outputs: &HashSet<CellId>,
        plan_provenance: &PlanProvenance,
        stage: &mut PropagationStage,
        filter_violations: &mut Vec<(CellId, FilterViolation)>,
    ) -> Result<(), Error> {
        for step in execution_order {
            match *step {
                PlanStep::Method(rel_id, method_idx) => {
                    if stage.executed_methods.contains(&(rel_id, method_idx)) {
                        let method = &self.relationships[rel_id].methods[method_idx];
                        for &output in &method.outputs {
                            stage.reclassify(
                                output,
                                method.inputs.contains(&output) || forced_outputs.contains(&output),
                            );
                        }
                        continue;
                    }
                    let method = &self.relationships[rel_id].methods[method_idx];
                    let outputs = {
                        let inputs: Vec<&dyn Any> = method
                            .inputs
                            .iter()
                            .map(|&id| {
                                if method.outputs.contains(&id) {
                                    seeds
                                        .get(&id)
                                        .map(|value| value.as_ref())
                                        .unwrap_or_else(|| stage.source(&self.cells, id))
                                } else {
                                    stage.effective(&self.cells, id)
                                }
                            })
                            .collect();
                        (method.function)(&inputs).map_err(|error| Error::MethodFailed {
                            error,
                            sites: vec![ErrorSite::Method(rel_id, method_idx)],
                        })?
                    };

                    if outputs.len() != method.outputs.len() {
                        return Err(Error::MethodFailed {
                            error: anyhow::anyhow!(
                                "method produced {} outputs but relationship expects {}",
                                outputs.len(),
                                method.outputs.len()
                            ),
                            sites: vec![ErrorSite::Method(rel_id, method_idx)],
                        });
                    }

                    for (&cell_id, new_value) in method.outputs.iter().zip(outputs) {
                        let found = new_value.as_ref().type_id();
                        let cell = &self.cells[cell_id];
                        if found != cell.type_id {
                            return Err(Error::TypeMismatch {
                                expected: cell.type_id,
                                found,
                                sites: vec![ErrorSite::Method(rel_id, method_idx)],
                            });
                        }
                        stage.write(
                            cell_id,
                            new_value,
                            method.inputs.contains(&cell_id) || forced_outputs.contains(&cell_id),
                        );
                    }
                    stage.executed_methods.insert((rel_id, method_idx));
                    stage
                        .step_provenance
                        .insert(*step, plan_provenance.steps[step].clone());
                }
                PlanStep::FilterReclamp(id) => {
                    if stage.executed_filters.contains(&id) {
                        continue;
                    }
                    let filter = self.cells[id]
                        .filter
                        .as_ref()
                        .expect("plan() only emits FilterReclamp for a filtered cell");
                    let args: Vec<&dyn Any> = filter
                        .args
                        .iter()
                        .map(|&a| stage.effective(&self.cells, a))
                        .collect();
                    let current = stage.source(&self.cells, id);
                    match (filter.function)(current, &args) {
                        Ok(v) if v.as_ref().type_id() == self.cells[id].type_id => {
                            stage.write(id, v, true);
                        }
                        Ok(_) => filter_violations.push((
                            id,
                            FilterViolation::Failed(anyhow::anyhow!(
                                "filter returned a value of a different type than the cell"
                            )),
                        )),
                        Err(error) => {
                            filter_violations.push((id, FilterViolation::Failed(error)));
                        }
                    }
                    stage.executed_filters.insert(id);
                    stage
                        .step_provenance
                        .insert(*step, plan_provenance.steps[step].clone());
                }
            }
        }
        Ok(())
    }

    /// Assigns derived-cell strengths after executing a selected plan.
    ///
    /// Walks `execution_order` and assigns a decrementing counter (starting at
    /// `0x7FFF_FFFF_FFFF_FFFF`) to each output cell of each selected method, in
    /// execution order. Cells evaluated first receive the highest derived strength.
    /// Source cells (not the output of any selected method) are not modified.
    ///
    /// A cell claimed *self-referencingly* (its claiming method reads the cell as one of
    /// its own inputs) keeps a live explicit strength rather than being demoted: such a
    /// method computes the cell from its own `source` aspiration (see
    /// [`crate::planner::evaluate_seeds`]), so an explicit `write()` to that cell is still
    /// the authority behind the value and must keep outranking never-written cells in
    /// later rounds. Demoting it would discard the edit the next time the cell is
    /// re-seeded.
    ///
    /// - Complexity: O(R·K²) where R is the number of entries and K is the maximum
    ///   inputs or outputs per method.
    /// - Postcondition: returns whether any cell's strength actually changed.
    fn post_process_strengths(&mut self, execution_order: &[PlanStep]) -> bool {
        let mut changed = false;
        let mut derived_strength = u64::MAX >> 1; // 0x7FFF_FFFF_FFFF_FFFF
        let mut seen: std::collections::HashSet<CellId> = std::collections::HashSet::new();
        for step in execution_order {
            let PlanStep::Method(rel_id, method_idx) = step else {
                continue;
            };
            if let Some(rel) = self.relationships.get(*rel_id)
                && let Some(method) = rel.methods.get(*method_idx)
            {
                for &output in &method.outputs {
                    let self_referencing = method.inputs.contains(&output);
                    if seen.insert(output)
                        && let Some(cell) = self.cells.get_mut(output)
                    {
                        if self_referencing && cell.has_explicit_strength() {
                            continue;
                        }
                        changed |= cell.strength != derived_strength;
                        cell.strength = derived_strength;
                        derived_strength = derived_strength.saturating_sub(1);
                    }
                }
            }
        }
        changed
    }

    /// Publishes a fully validated propagation stage and returns previously derived cells.
    ///
    /// Clears every old derived override, applies staged source and derived writes, and
    /// records each staged output in [`Sheet::changed`]. No callback is evaluated here.
    ///
    /// - Complexity: O(cells).
    fn commit_stage(&mut self, stage: PropagationStage) -> Vec<CellId> {
        let previously_derived: Vec<CellId> = self
            .cells
            .iter()
            .filter(|(_, cell)| cell.derived.is_some())
            .map(|(id, _)| id)
            .collect();
        for (_, cell) in self.cells.iter_mut() {
            cell.derived = None;
        }
        for (id, value) in stage.sources {
            self.cells[id].source = value;
        }
        for (id, value) in stage.derived {
            self.cells[id].derived = Some(value);
        }
        for id in stage.changed {
            let cell = &mut self.cells[id];
            if !cell.changed {
                cell.changed = true;
                self.changed_cells.push(id);
            }
        }
        previously_derived
    }

    /// Updates the sheet using eligible prepared plans or newly selected methods.
    ///
    /// Validates static guard independence before mutating state, then clears the
    /// changed-cell set from the previous `propagate()` call before staged planning.
    /// After propagation, call [`Sheet::changed`] to inspect which cells were updated,
    /// and [`Sheet::clear_changed`] when done.
    ///
    /// Method, filter, conditional-expression, and requirement callbacks must be
    /// purely functional. There is no guarantee that any callback executes, or when
    /// or how often it executes; results may be reused or recomputed while preserving
    /// cell values and diagnostics. The phases below describe the current algorithm,
    /// not a callback invocation contract.
    ///
    /// Retains at most one prepared unconditional plan and one prepared main plan,
    /// each with its own released sources and active relationships. Successful writes
    /// to released sources preserve that phase's eligibility; writes to claimed cells
    /// (including self-referencing claimants) discard it. Filter reclamps do not claim
    /// released sources. Actual structural mutations discard both entries.
    /// Prepared plans retain structural seed recipes, not values from earlier calls.
    ///
    /// **Phase 0 — Staging:** propagation starts from each cell's source value, excluding
    /// every derived override from the previous round, but does not mutate live cells.
    ///
    /// **Phase 1 — Pre-plan:** when conditionals exist, an eligible prepared unconditional
    /// plan is obtained or a new one is prepared. Its selected guard-prerequisite cone
    /// executes so derived guard values are current before branch evaluation.
    /// Unrelated filters remain deferred until the final active plan, after the relationships
    /// that produce their arguments.
    ///
    /// **Phase 2 — Conditional evaluation:** each conditional's match cell value is
    /// read and compared against branch keys; the active relationship set is built.
    ///
    /// **Phase 3 — General plan:** an eligible prepared main plan is obtained for the active
    /// set, or the Adam algorithm selects and prepares a new one. Seed-cycle
    /// validation and method execution consume staged Phase 1 values. A callback already
    /// evaluated in Phase 1 is reused only when the final plan preserves its selected
    /// method, input producers, and output classification. A mismatched plan returns a
    /// conservative conflict rather than committing stale values. This
    /// boundary may reject a sheet even when another assignment could have avoided the mismatch;
    /// propagation reports the implicated sites instead of attempting that alternate assignment.
    /// A Phase 1 seed callback is likewise reused only when every input reads the same staged
    /// source version, recursive seed result, or accumulated value; otherwise propagation
    /// returns a conflict instead of reusing a stale seed.
    ///
    /// **Phase 4 — Commit and strength post-processing:** after planning, seed
    /// validation, and staged method execution all succeed, staged writes are published
    /// atomically. Derived cells then receive low-order strengths in evaluation order,
    /// enforcing the stability invariant. A cell claimed self-referencingly keeps any
    /// live explicit strength instead, since its own written value is still the authority
    /// behind the result.
    ///
    /// **Phase 5 — Reversion change-tracking:** a cell whose derived override existed
    /// before this round but wasn't reclaimed by any method this round has effectively
    /// reverted to its source value (e.g. its forcing conditional went inactive); it is
    /// marked changed even though no method wrote to it this round.
    ///
    /// **Phase 6 — Requirement evaluation:** every registered requirement is evaluated
    /// against current cell values, rebuilding `last_requirement_violations` from
    /// scratch, so [`Sheet::cell_requirements_valid`] and [`Sheet::violated_requirements`]
    /// reflect this round.
    ///
    /// Filter failures remain diagnostics rather than propagation errors, and diagnostic
    /// results use current values.
    ///
    /// - Complexity: on a cache miss, prerequisite-cone indexing, traversal, and producer
    ///   preparation take O(V + E) per selected plan, distinct from assignment matching.
    ///   Cache hits omit this preparation, assignment matching, global strength sorting,
    ///   and complete seed-elimination replay. Active-set comparison takes expected O(R)
    ///   for R active relationships; a pending strength certificate takes O(C) for C cells.
    ///   Current strength gates and local sibling sorts still run (O(S log S) comparisons
    ///   for S siblings, with structural signature comparison costs). Fresh staged
    ///   execution, seed evaluation, commit, and diagnostics retain their costs.
    ///   Discarding final owners of prepared artifacts of total size A can take O(A).
    ///
    /// # Errors
    ///
    /// - `Error::DependencyCycle` — a filter or conditional guard edge lies on a cycle in
    ///   the static dependency graph.
    /// - `Error::Conflict` — no valid method assignment exists, or a pre-executed guard
    ///   prerequisite is incompatible with the final selected plan.
    /// - `Error::SeedCycle` — sibling seed dependencies form a non-self cycle.
    /// - `Error::MethodFailed` — a method's function returned an error, a method
    ///   produced the wrong number of outputs, or a requirement's function returned
    ///   an error. A requirement error includes its governed cell as an error site.
    /// - `Error::TypeMismatch` — a method output's runtime type does not match the
    ///   cell's registered type.
    pub fn propagate(&mut self) -> Result<(), Error> {
        let mut pre = self.pre_plan_cache.take();
        let mut main = self.main_plan_cache.take();
        let result = self.propagate_with_caches(&mut pre, &mut main);
        if result.is_ok() {
            self.pre_plan_cache = pre;
            self.main_plan_cache = main;
        }
        result
    }

    /// Returns the index of the method selected for `rel` in the last successful propagation.
    ///
    /// Returns `None` if no propagation has run yet, `rel` is not in the cached plan,
    /// or `rel` was added after the last `propagate()` call.
    ///
    /// - Complexity: O(S) worst-case time for S completed execution steps; O(1) space.
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn selected_method(&self, rel: RelationshipId) -> Option<usize> {
        self.last_plan
            .as_ref()?
            .plan
            .execution_order
            .iter()
            .find_map(|step| match step {
                PlanStep::Method(r, idx) if *r == rel => Some(*idx),
                _ => None,
            })
    }

    /// Returns the input cells of method `idx` in relationship `rel`.
    ///
    /// Returns `None` if `rel` is not a live relationship or `idx` is out of bounds.
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn method_inputs(&self, rel: RelationshipId, idx: usize) -> Option<&[CellId]> {
        self.relationships
            .get(rel)?
            .methods
            .get(idx)
            .map(|m| m.inputs.as_slice())
    }

    /// Returns the output cells of method `idx` in relationship `rel`.
    ///
    /// Returns `None` if `rel` is not a live relationship or `idx` is out of bounds.
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn method_outputs(&self, rel: RelationshipId, idx: usize) -> Option<&[CellId]> {
        self.relationships
            .get(rel)?
            .methods
            .get(idx)
            .map(|m| m.outputs.as_slice())
    }

    /// Returns `true` if `id` was not written by any selected method in the last successful propagation.
    ///
    /// Returns `false` if no propagation has succeeded yet. This display query does not
    /// determine prepared-plan eligibility.
    ///
    /// Cells absent from the completed plan, including newly added cells, return `true`.
    ///
    /// - Complexity: Expected O(1).
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn is_source(&self, id: CellId) -> bool {
        let Some(plan) = &self.last_plan else {
            return false;
        };
        !plan.certificate.contains_cell(id) || plan.certificate.is_released(id)
    }

    /// Iterates snapshot sources contributing to `results` in the last successful plan.
    ///
    /// An empty `results` slice selects the entire sheet: unclaimed cells and outputs
    /// read by their own selected method. Otherwise, selects only those sources in
    /// the requested cells' selected producer paths, including conforming filter
    /// arguments and conditional selectors governing those paths. Unselected methods'
    /// inputs and diagnostic-only filter arguments do not contribute.
    ///
    /// Each source appears once, in unspecified order, even when results repeat or
    /// share dependencies. Pure derived outputs and `Out` cells are excluded.
    /// Returns an empty iterator before any successful propagation. Like
    /// [`Self::is_source`], classification describes the last successful plan;
    /// newly added non-`Out` cells count as unclaimed.
    ///
    /// To capture a settled result, iterate after successful propagation and before
    /// further edits, reading effective values with [`Self::read`], not the
    /// aspirations returned by [`Self::source`]. Clients own baseline comparison,
    /// relevance filtering, stable cell identity, and typed serialization.
    ///
    /// Replay writes all captured values in any order as one batch before
    /// propagation. For a settled solution satisfying its relationships and filters,
    /// a compatible graph with matching uncaptured inputs reproduces the requested
    /// effective values (or all values when `results` is empty). Relationship methods
    /// must preserve an already-satisfied assignment, and self-referencing methods
    /// and filters must be idempotent;
    /// these caller contracts make the solution a fixed point even if replay
    /// selects different methods. No strengths or write history need to be captured.
    /// A snapshot does not preserve original aspirations, priority history,
    /// diagnostics, or behavior under subsequent edits, including spring-back.
    ///
    /// - Precondition: every result is a live cell belonging to this sheet.
    /// - Complexity: empty results take O(C + S + Σ(I × O)) traversal time and O(1)
    ///   auxiliary space, for C cells, S selected steps, and each selected method's
    ///   I inputs and O outputs. Nonempty results add expected O(N + V + E + V × G)
    ///   time and O(N + V + E) auxiliary space, for N requested results, V reachable
    ///   value/producer pairs, E their dependency edges, and G the total size of the
    ///   registered conditional graph. Does not copy cell values.
    ///
    /// # Examples
    ///
    /// ```
    /// use adam_rs::Sheet;
    /// let mut sheet = Sheet::new();
    /// let width = sheet.add_source(10_i32);
    /// sheet.add_source(false);
    /// sheet.propagate()?;
    /// assert_eq!(sheet.source_cells(&[]).count(), 2);
    /// let capture = sheet.source_cells(&[width])
    ///     .map(|id| Ok((id, *sheet.read::<i32>(id)?)))
    ///     .collect::<Result<Vec<_>, adam_rs::Error>>()?;
    /// assert_eq!(capture, [(width, 10)]);
    /// // Use host-defined names or schema keys, not live CellIds, for persistence.
    /// # Ok::<(), adam_rs::Error>(())
    /// ```
    pub fn source_cells(&self, results: &[CellId]) -> impl Iterator<Item = CellId> + use<'_> {
        debug_assert!(results.iter().all(|id| self.cells.contains_key(*id)));
        let contributors = (!results.is_empty()).then(|| self.capture_contributors(results));
        let unclaimed = self.cells.keys().filter(|&id| self.is_source(id));
        let self_referencing = self
            .last_plan
            .iter()
            .flat_map(|prepared| &prepared.plan.execution_order)
            .filter_map(|step| match *step {
                PlanStep::Method(id, index) => Some(&self.relationships[id].methods[index]),
                PlanStep::FilterReclamp(_) => None,
            })
            .flat_map(|method| {
                method
                    .outputs
                    .iter()
                    .copied()
                    .filter(|id| method.inputs.contains(id))
            });
        unclaimed.chain(self_referencing).filter(move |&id| {
            self.cells[id].kind != CellKind::Out
                && contributors
                    .as_ref()
                    .is_none_or(|cells| cells.contains(&id))
        })
    }

    /// Returns the source leaves of `results`' selected value and control dependencies.
    ///
    /// Producer identities distinguish a filter's incoming source from its effective
    /// output. Self-referencing inputs terminate at their captured effective value,
    /// rather than introducing a cycle or following alternative seed methods.
    ///
    /// - Precondition: every result is a live cell belonging to this sheet.
    /// - Complexity: expected O(N + V + E + V × G) time and O(N + V + E) space,
    ///   for N results, V reachable value/producer pairs, E dependency edges, and
    ///   G the total size of the registered conditional graph.
    fn capture_contributors(&self, results: &[CellId]) -> HashSet<CellId> {
        let Some(prepared) = &self.last_plan else {
            return HashSet::new();
        };
        let provenance = &prepared.provenance;
        let current_value = |cell| (cell, provenance.output_producers.get(&cell).copied());
        let mut pending: Vec<_> = results.iter().copied().map(current_value).collect();
        let mut visited = HashSet::new();
        let mut contributors = HashSet::new();

        while let Some((cell, producer)) = pending.pop() {
            if !visited.insert((cell, producer)) {
                continue;
            }
            pending.extend(
                self.conditionals
                    .values()
                    .filter(|conditional| {
                        conditional
                            .branches
                            .iter()
                            .flat_map(|branch| branch.relationships.iter())
                            .chain(conditional.default.iter())
                            .any(|&relationship| {
                                matches!(
                                    producer,
                                    Some(PlanStep::Method(selected, _)) if selected == relationship
                                ) || (!prepared.active.contains(&relationship)
                                    && self.relationships[relationship]
                                        .methods
                                        .iter()
                                        .any(|method| method.outputs.contains(&cell)))
                            })
                    })
                    .flat_map(|conditional| conditional.match_cells().iter().copied())
                    .map(current_value),
            );
            let Some(step) = producer else {
                contributors.insert(cell);
                continue;
            };
            let step_provenance = &provenance.steps[&step];
            let inputs = match step {
                PlanStep::Method(relationship, index) => {
                    &self.relationships[relationship].methods[index].inputs
                }
                PlanStep::FilterReclamp(filtered) => {
                    pending.push((filtered, step_provenance.source_producer));
                    &self.cells[filtered]
                        .filter
                        .as_ref()
                        .expect("planned filter reclamps have an attached filter")
                        .args
                }
            };
            pending.extend(
                inputs
                    .iter()
                    .copied()
                    .zip(step_provenance.input_producers.iter().copied()),
            );
        }
        contributors
    }

    /// Returns whether `id` belongs to the last successful plan's forced pure-output set.
    ///
    /// The planner intersects pure outputs across viable methods and eliminates
    /// alternatives that conflict with another relationship's forced outputs until
    /// the classification stabilizes. A forced pure output's producer does not read
    /// that cell as a self-referencing input.
    ///
    /// A conditionally forced cell retains its pre-forcing priority and source
    /// aspiration for release; see [the forcing outcomes](crate::sheet#forced-self-referencing-and-reversible-outcomes).
    ///
    /// This does not decide whether some assignment can leave the cell unclaimed.
    /// A mandatory self-referencing writer claims its output exclusively but remains
    /// outside this classification; its editable source aspiration can affect its seed.
    ///
    /// Returns `false` if no propagation has run yet.
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn is_forced(&self, id: CellId) -> bool {
        self.last_plan
            .as_ref()
            .is_some_and(|prepared| prepared.plan.forced_outputs.contains(&id))
    }

    /// Iterates cells that are forced (see [`Sheet::is_forced`]) as of the last
    /// successful `propagate()` call.
    ///
    /// - Complexity: O(n) where n is the number of forced cells.
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn forced_cells(&self) -> impl Iterator<Item = CellId> + '_ {
        self.last_plan
            .iter()
            .flat_map(|prepared| prepared.plan.forced_outputs.iter().copied())
    }

    /// Returns `true` if `id` had exactly one viable method as of the last successful
    /// `propagate()` call — the planner has no alternative method to choose for this
    /// relationship, regardless of cell strength.
    ///
    /// Returns `false` if no propagation has run yet.
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn is_relationship_forced(&self, id: RelationshipId) -> bool {
        self.last_plan
            .as_ref()
            .is_some_and(|prepared| prepared.plan.forced_relationships.contains(&id))
    }

    /// Iterates relationships that are forced (see [`Sheet::is_relationship_forced`])
    /// as of the last successful `propagate()` call.
    ///
    /// - Complexity: O(n) where n is the number of forced relationships.
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn forced_relationships(&self) -> impl Iterator<Item = RelationshipId> + '_ {
        self.last_plan
            .iter()
            .flat_map(|prepared| prepared.plan.forced_relationships.iter().copied())
    }

    /// Iterates all live conditional IDs in the sheet.
    ///
    /// - Complexity: O(n) where n is the number of conditionals.
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn conditionals(&self) -> impl Iterator<Item = ConditionalId> + '_ {
        self.conditionals.keys()
    }

    /// Iterates all live `Out`-kind cells in the sheet.
    ///
    /// - Complexity: O(n) where n is the number of cells.
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn out_cells(&self) -> impl Iterator<Item = CellId> + '_ {
        self.cells
            .iter()
            .filter(|(_, c)| c.kind == CellKind::Out)
            .map(|(id, _)| id)
    }

    /// Returns the match cells for conditional `id`: a single cell for a plain match
    /// subject, or every input of a [`MatchExpr`] match subject.
    ///
    /// Returns `None` if `id` is not a live conditional in this sheet.
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn conditional_match_cells(&self, id: ConditionalId) -> Option<&[CellId]> {
        self.conditionals.get(id).map(|c| c.match_cells())
    }

    /// Returns the number of named branches in conditional `id`.
    ///
    /// Returns `None` if `id` is not a live conditional in this sheet.
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn conditional_branch_count(&self, id: ConditionalId) -> Option<usize> {
        self.conditionals.get(id).map(|c| c.branches.len())
    }

    /// Returns the relationship IDs for branch `branch` of conditional `id`.
    ///
    /// Returns `None` if `id` is not a live conditional, or `branch` is out of bounds.
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn conditional_branch_relationships(
        &self,
        id: ConditionalId,
        branch: usize,
    ) -> Option<&[RelationshipId]> {
        self.conditionals
            .get(id)?
            .branches
            .get(branch)
            .map(|b| b.relationships.as_slice())
    }

    /// Returns the default relationship IDs for conditional `id`.
    ///
    /// These relationships are active when no named branch key matches the match cell.
    /// Returns `None` if `id` is not a live conditional in this sheet.
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn conditional_default_relationships(
        &self,
        id: ConditionalId,
    ) -> Option<&[RelationshipId]> {
        self.conditionals.get(id).map(|c| c.default.as_slice())
    }

    /// Returns the index of the currently matching branch for conditional `id`.
    ///
    /// Evaluates branch keys against the match subject's current value in definition
    /// order; returns the index of the first matching branch. Returns `Ok(None)` if no
    /// branch key matches (the default branch is active) or if `id` is not a live
    /// conditional.
    ///
    /// # Errors
    ///
    /// - `Error::MethodFailed` — `id` is a live, expression-sourced conditional whose
    ///   function returned an error. The original cause and `ErrorSite::Conditional(id)`
    ///   identify the failing execution.
    ///
    /// - Complexity: O(B·K) where B = branches, K = keys per branch.
    ///
    /// # Examples
    /// See the [graph example](crate::sheet).
    pub fn conditional_active_branch(&self, id: ConditionalId) -> Result<Option<usize>, Error> {
        let Some(cond) = self.conditionals.get(id) else {
            return Ok(None);
        };
        let value = self.evaluate_match_source(id, cond)?;
        let value_ref = value.as_dyn();
        let eq_fn = self.match_eq_fn(cond);
        Ok(cond
            .branches
            .iter()
            .enumerate()
            .find(|(_, branch)| branch.keys.iter().any(|key| eq_fn(value_ref, key.as_ref())))
            .map(|(i, _)| i))
    }
}

impl Default for Sheet {
    /// Returns `Sheet::new()`.
    fn default() -> Self {
        Self::new()
    }
}

#[cfg(test)]
mod tests {
    use crate::{
        CellKind, ConditionalId, Error, MatchExpr, Method, Requirement, Sheet,
        cell::CellId,
        error::ErrorSite,
        filter::{Filter, FilterKind, FilterViolation},
        planner::{PlanStep, Seeds},
        relationship::RelationshipId,
    };
    use std::any::{Any, TypeId};
    use std::collections::{HashMap, HashSet};

    /// Starts an empty default sheet and reports registered concrete identities.
    #[test]
    fn default_and_type_id_obey_empty_and_registration_contracts() {
        let mut sheet = Sheet::default();
        assert_eq!(sheet.cells().count(), 0);
        assert_eq!(sheet.relationships().count(), 0);
        assert_eq!(sheet.conditionals().count(), 0);
        assert_eq!(sheet.changed().count(), 0);
        assert_eq!(sheet.cell_type_id(CellId::default()), None);
        let cell = sheet.add_cell(String::new());
        assert_eq!(sheet.cell_type_id(cell), Some(TypeId::of::<String>()));
    }

    /// Rebuilds a fresh sheet after a staged type error.
    #[test]
    fn late_output_type_failure_requires_rebuilding_the_sheet() {
        let make_sheet = |source_value| {
            let mut sheet = Sheet::new();
            let source = sheet.add_cell(source_value);
            let a = sheet.add_cell(0_i32);
            let b = sheet.add_cell(0_i32);
            sheet
                .add_relationship(vec![Method::new(
                    vec![source],
                    vec![a, b],
                    vec![TypeId::of::<i32>()],
                    vec![TypeId::of::<i32>(); 2],
                    |args| {
                        let value = *args[0].downcast_ref::<i32>().unwrap();
                        let last: Box<dyn Any> = if value < 0 {
                            Box::new(false)
                        } else {
                            Box::new(value)
                        };
                        Ok(vec![Box::new(value), last])
                    },
                )])
                .unwrap();
            (sheet, source, a, b)
        };

        let (mut sheet, source, _, _) = make_sheet(5_i32);
        sheet.propagate().unwrap();
        sheet.write(source, -9_i32).unwrap();
        assert!(matches!(sheet.propagate(), Err(Error::TypeMismatch { .. })));
        drop(sheet);

        let (mut rebuilt, _, a, b) = make_sheet(12_i32);
        rebuilt.propagate().unwrap();
        assert_eq!(*rebuilt.read::<i32>(a).unwrap(), 12);
        assert_eq!(*rebuilt.read::<i32>(b).unwrap(), 12);
    }

    #[test]
    /// Checks the ordinary kind assigned to a new editable cell.
    fn add_cell_has_cell_kind() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        assert_eq!(sheet.cell_kind(a), Some(CellKind::Cell));
    }

    #[test]
    /// Checks the source-only kind assigned to a new source.
    fn add_source_has_source_kind() {
        let mut sheet = Sheet::new();
        let a = sheet.add_source(0_i32);
        assert_eq!(sheet.cell_kind(a), Some(CellKind::Source));
    }

    #[test]
    /// Checks absence of kind metadata for an unknown cell.
    fn cell_kind_returns_none_for_invalid_id() {
        let mut sheet = Sheet::new();
        sheet.add_cell(0_i32); // occupies slotmap index 0 in `sheet`
        let mut other = Sheet::new();
        other.add_cell(0_i32); // index 0 in `other`
        let bogus = other.add_cell(0_i32); // index 1 in `other` -- out of range for `sheet`,
        // which only ever allocated index 0, so this is
        // guaranteed invalid regardless of generation
        // (a same-index key from a second fresh SlotMap
        // would otherwise collide with `sheet`'s own key)
        assert_eq!(sheet.cell_kind(bogus), None);
    }

    #[test]
    /// Checks that a later plain staged write replaces an earlier derived override.
    fn execute_plan_staged_clears_a_stale_override_on_a_later_plain_write() {
        let mut sheet = Sheet::new();
        let x = sheet.add_cell(8_i32);
        let y = sheet.add_cell(2_i32);
        let z = sheet.add_cell(10_i32);
        let self_ref = sheet
            .add_relationship(vec![
                Method::from_fn_2_1([x, y], x, |a: &i32, b: &i32| Ok((*a).min(*b))),
                Method::from_fn_2_1([x, y], y, |a: &i32, b: &i32| Ok((*a).max(*b))),
            ])
            .unwrap();
        let plain = sheet
            .add_relationship(vec![Method::from_fn_1_1(z, x, |v: &i32| {
                v.checked_add(1).ok_or_else(|| anyhow::anyhow!("overflow"))
            })])
            .unwrap();

        let no_seeds: Seeds = HashMap::new();
        let no_forced: HashSet<CellId> = HashSet::new();
        let mut stage = super::PropagationStage::default();
        let mut plan = crate::planner::plan(
            &sheet.cells,
            &sheet.relationships,
            &HashSet::from([self_ref]),
        )
        .unwrap();
        plan.execution_order = vec![PlanStep::Method(self_ref, 0)];
        plan.forced_outputs.clear();
        let provenance = sheet.plan_provenance(&plan);
        sheet
            .execute_plan_staged(
                &[PlanStep::Method(self_ref, 0)],
                &no_seeds,
                &no_forced,
                &provenance,
                &mut stage,
                &mut Vec::new(),
            )
            .unwrap();
        assert_eq!(
            stage.effective(&sheet.cells, x).downcast_ref::<i32>(),
            Some(&2)
        );
        assert_eq!(*sheet.read::<i32>(x).unwrap(), 8);

        sheet.write(z, 41_i32).unwrap();
        let mut plan =
            crate::planner::plan(&sheet.cells, &sheet.relationships, &HashSet::from([plain]))
                .unwrap();
        plan.forced_outputs.clear();
        let provenance = sheet.plan_provenance(&plan);
        sheet
            .execute_plan_staged(
                &[PlanStep::Method(plain, 0)],
                &no_seeds,
                &no_forced,
                &provenance,
                &mut stage,
                &mut Vec::new(),
            )
            .unwrap();
        assert_eq!(
            stage.effective(&sheet.cells, x).downcast_ref::<i32>(),
            Some(&42)
        );
        sheet.commit_stage(stage);
        assert_eq!(*sheet.read::<i32>(x).unwrap(), 42);
    }

    #[test]
    /// Checks rejection of an unknown conditional match cell.
    fn add_conditional_returns_error_for_invalid_cell() {
        let mut sheet = Sheet::new();
        let result = sheet.add_conditional(
            MatchExpr::cell(CellId::default()),
            vec![(vec![0_i32], vec![])],
            vec![],
        );
        assert!(matches!(result, Err(Error::InvalidId)));
    }

    #[test]
    /// Checks rejection of branch keys with the wrong match type.
    fn add_conditional_returns_invalid_conditional_for_type_mismatch() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        // Branch keys are f64 but cell holds i32.
        let result =
            sheet.add_conditional(MatchExpr::cell(a), vec![(vec![0.0_f64], vec![])], vec![]);
        assert!(matches!(result, Err(Error::InvalidConditional { .. })));
    }

    #[test]
    /// Checks rejection of an unknown conditional relationship.
    fn add_conditional_returns_invalid_conditional_for_missing_relationship() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let result = sheet.add_conditional(
            MatchExpr::cell(a),
            vec![(vec![0_i32], vec![RelationshipId::default()])],
            vec![],
        );
        assert!(matches!(result, Err(Error::InvalidConditional { .. })));
    }

    #[test]
    /// Checks the match-cell site in a conditional dependency-cycle error.
    fn dependency_cycle_from_a_conditional_names_the_match_cell() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(0_i32);
        // Relationship has two methods and involves `a` (the match cell).
        let rel = sheet
            .add_relationship(vec![
                Method::from_fn_1_1(a, b, |x: &i32| Ok(*x)),
                Method::from_fn_1_1(b, a, |x: &i32| Ok(*x)),
            ])
            .unwrap();
        sheet
            .add_conditional(MatchExpr::cell(a), vec![(vec![0_i32], vec![rel])], vec![])
            .unwrap();
        let err = sheet.validate().unwrap_err();
        assert!(matches!(err, Error::DependencyCycle { .. }));
        assert!(err.sites().contains(&ErrorSite::Cell(a)));
    }

    #[test]
    /// Checks rejection of a branch that can derive an upstream match dependency.
    fn add_conditional_returns_error_when_branch_rel_writes_a_cell_upstream_of_match_cell() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(0_i32);
        let p = sheet.add_cell(0_i32);
        // Unconditional: a → p  (a contributes to match cell p).
        sheet
            .add_relationship(vec![Method::from_fn_1_1(a, p, |x: &i32| Ok(*x))])
            .unwrap();
        // Branch relationship has two methods and involves `a`, which feeds p.
        let rel = sheet
            .add_relationship(vec![
                Method::from_fn_1_1(a, b, |x: &i32| Ok(*x)),
                Method::from_fn_1_1(b, a, |x: &i32| Ok(*x)),
            ])
            .unwrap();
        sheet
            .add_conditional(MatchExpr::cell(p), vec![(vec![0_i32], vec![rel])], vec![])
            .unwrap();
        assert!(matches!(
            sheet.validate(),
            Err(Error::DependencyCycle { .. })
        ));
    }

    #[test]
    /// Checks guard independence for every computed-match input.
    fn add_conditional_returns_error_when_branch_rel_writes_a_cell_upstream_of_either_expr_input() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(0_i32);
        let p = sheet.add_cell(0_i32);
        let q = sheet.add_cell(0_i32);
        // Unconditional: a → q  (a contributes to expr input q).
        sheet
            .add_relationship(vec![Method::from_fn_1_1(a, q, |x: &i32| Ok(*x))])
            .unwrap();
        // Branch relationship has two methods and involves `a`, which feeds q, one of the
        // match expression's two inputs (p, q).
        let rel = sheet
            .add_relationship(vec![
                Method::from_fn_1_1(a, b, |x: &i32| Ok(*x)),
                Method::from_fn_1_1(b, a, |x: &i32| Ok(*x)),
            ])
            .unwrap();
        let expr = MatchExpr::from_fn_2([p, q], |x: &i32, y: &i32| Ok(*x + *y));
        sheet
            .add_conditional(expr, vec![(vec![0_i32], vec![rel])], vec![])
            .unwrap();
        assert!(matches!(
            sheet.validate(),
            Err(Error::DependencyCycle { .. })
        ));
    }

    #[test]
    /// Checks branch selection from a computed two-input subject.
    fn add_conditional_activates_branch_from_two_cell_expression() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(false);
        let b = sheet.add_cell(false);
        let x = sheet.add_cell(0_i32);
        let y = sheet.add_cell(0_i32);
        let rel_true = sheet
            .add_relationship(vec![Method::from_fn_1_1(x, y, |v: &i32| Ok(*v))])
            .unwrap();
        let expr = MatchExpr::from_fn_2([a, b], |p: &bool, q: &bool| Ok(*p && *q));
        let cid = sheet
            .add_conditional(expr, vec![(vec![true], vec![rel_true])], vec![])
            .unwrap();

        sheet.write(a, true).unwrap();
        sheet.write(b, false).unwrap();
        assert_eq!(sheet.conditional_active_branch(cid).unwrap(), None);

        sheet.write(b, true).unwrap();
        assert_eq!(sheet.conditional_active_branch(cid).unwrap(), Some(0));
        assert_eq!(sheet.conditional_match_cells(cid).unwrap(), &[a, b]);
    }

    #[test]
    /// Checks rejection of keys incompatible with the computed subject's output type.
    fn add_conditional_returns_invalid_conditional_for_expr_output_type_mismatch() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(0_i32);
        // Expression computes an i32, but branch keys below are f64.
        let expr = MatchExpr::from_fn_2([a, b], |x: &i32, y: &i32| Ok(x + y));
        let result = sheet.add_conditional::<f64>(expr, vec![(vec![0.0], vec![])], vec![]);
        assert!(matches!(result, Err(Error::InvalidConditional { .. })));
    }

    #[test]
    /// Checks rejection of an unknown computed-subject input.
    fn add_conditional_returns_invalid_id_for_bad_expr_input_cell() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let expr = MatchExpr::from_fn_2([a, CellId::default()], |x: &i32, y: &i32| Ok(x + y));
        let result = sheet.add_conditional::<i32>(expr, vec![], vec![]);
        assert!(matches!(result, Err(Error::InvalidId)));
    }

    #[test]
    /// Checks propagation of a computed subject's callback failure.
    fn propagate_surfaces_method_failed_from_a_failing_match_expression() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let expr = MatchExpr::from_fn_1(a, |_x: &i32| -> Result<i32, anyhow::Error> {
            Err(anyhow::anyhow!("boom"))
        });
        sheet
            .add_conditional::<i32>(expr, vec![(vec![0], vec![])], vec![])
            .unwrap();
        let result = sheet.propagate();
        assert!(matches!(result, Err(Error::MethodFailed { .. })));
    }

    #[test]
    /// Checks acceptance of multi-method branches independent of the match cell.
    fn add_conditional_allows_multi_method_rel_not_involving_match_cell() {
        let mut sheet = Sheet::new();
        let mode = sheet.add_cell(0_i32);
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(0_i32);
        // Relationship has two methods but does not involve `mode` (the match cell).
        // Branch relationships whose outputs do not reach the match cell may have any
        // number of methods.
        let rel = sheet
            .add_relationship(vec![
                Method::from_fn_1_1(a, b, |x: &i32| Ok(*x)),
                Method::from_fn_1_1(b, a, |x: &i32| Ok(*x)),
            ])
            .unwrap();
        let result = sheet.add_conditional(
            MatchExpr::cell(mode),
            vec![(vec![0_i32], vec![rel])],
            vec![],
        );
        assert!(result.is_ok());
    }

    #[test]
    /// Checks rejection of an explicit branch without keys.
    fn add_conditional_returns_invalid_conditional_for_empty_branch_keys() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(0_i32);
        let rel = sheet
            .add_relationship(vec![Method::from_fn_1_1(a, b, |x: &i32| Ok(*x))])
            .unwrap();
        // Empty key list is invalid.
        let result =
            sheet.add_conditional::<i32>(MatchExpr::cell(a), vec![(vec![], vec![rel])], vec![]);
        assert!(matches!(result, Err(Error::InvalidConditional { .. })));
    }

    #[test]
    /// Checks duplicate conditional ownership rejection and its relationship site.
    fn invalid_conditional_duplicate_relationship_names_that_relationship() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(0_i32);
        let dup_rel = sheet
            .add_relationship(vec![Method::from_fn_1_1(a, b, |x: &i32| Ok(*x))])
            .unwrap();
        // Add dup_rel to the first conditional.
        sheet
            .add_conditional(
                MatchExpr::cell(a),
                vec![(vec![0_i32], vec![dup_rel])],
                vec![],
            )
            .unwrap();
        // Try to add the same relationship to a second conditional.
        let result = sheet.add_conditional(
            MatchExpr::cell(a),
            vec![(vec![1_i32], vec![dup_rel])],
            vec![],
        );
        let err = result.unwrap_err();
        assert!(matches!(err, Error::InvalidConditional { .. }));
        assert!(err.sites().contains(&ErrorSite::Relationship(dup_rel)));
    }

    #[test]
    /// Checks registration and lookup of a valid conditional identity.
    fn add_conditional_returns_id_for_valid_input() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(0_i32);
        let rel = sheet
            .add_relationship(vec![Method::from_fn_1_1(a, b, |x: &i32| Ok(*x))])
            .unwrap();
        let cid = sheet
            .add_conditional(MatchExpr::cell(a), vec![(vec![0_i32], vec![rel])], vec![])
            .unwrap();
        assert_eq!(sheet.conditionals().collect::<Vec<_>>(), vec![cid]);
        assert_eq!(sheet.conditional_match_cells(cid), Some([a].as_slice()));
    }

    #[test]
    /// Checks distinct identities for separate cell declarations.
    fn add_cell_returns_distinct_ids() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(1_i32);
        let b = sheet.add_cell(2_i32);
        assert_ne!(a, b);
    }

    #[test]
    /// Checks rejection of external writes to fixed Out cells.
    fn write_returns_invalid_cell_kind_for_an_output_cell() {
        let mut sheet = Sheet::new();
        let writer_input = sheet.add_cell(1_i32);
        let out_cell = sheet.add_cell(0_i32);
        let out = sheet
            .add_out(
                Method::from_fn_1_1(writer_input, out_cell, |x: &i32| Ok(*x)),
                vec![],
            )
            .unwrap();
        assert!(matches!(
            sheet.write(out, 5_i32),
            Err(Error::InvalidCellKind { .. })
        ));
    }

    #[test]
    /// Checks rejection of method outputs targeting source-only cells.
    fn add_relationship_returns_invalid_cell_kind_when_a_source_cell_is_an_output() {
        let mut sheet = Sheet::new();
        let a = sheet.add_source(0_i32);
        let b = sheet.add_cell(0_i32);
        let result = sheet.add_relationship(vec![Method::from_fn_1_1(b, a, |x: &i32| Ok(*x))]);
        assert!(matches!(result, Err(Error::InvalidCellKind { .. })));
        assert_eq!(
            result.unwrap_err().sites().first().copied(),
            Some(ErrorSite::MethodIndex(0))
        );
    }

    #[test]
    /// Checks method and cell sites for a rejected source-only output.
    fn invalid_cell_kind_names_the_method_and_the_source_output_cell() {
        let mut sheet = Sheet::new();
        let s = sheet.add_source(0_i32); // Source-kind cell
        // A Source-kind output is rejected.
        let err = sheet
            .add_relationship(vec![Method::from_fn_1_1(s, s, |x: &i32| Ok(*x))])
            .unwrap_err();
        let sites = err.sites();
        assert_eq!(sites[0], ErrorSite::MethodIndex(0));
        assert!(sites[1..].contains(&ErrorSite::Cell(s)));
    }

    #[test]
    /// Checks acceptance of source-only cells as method inputs.
    fn add_relationship_allows_a_source_cell_as_an_input() {
        let mut sheet = Sheet::new();
        let a = sheet.add_source(5_i32);
        let b = sheet.add_cell(0_i32);
        let result = sheet.add_relationship(vec![Method::from_fn_1_1(a, b, |x: &i32| Ok(*x))]);
        assert!(result.is_ok());
    }

    #[test]
    /// Checks external editing of source-only cells.
    fn write_succeeds_on_a_source_cell() {
        let mut sheet = Sheet::new();
        let a = sheet.add_source(0_i32);
        assert!(sheet.write(a, 5_i32).is_ok());
    }

    #[test]
    /// Checks immediate reads of a successfully written value.
    fn write_read_roundtrip() {
        let mut sheet = Sheet::new();
        let id = sheet.add_cell(42_i32);
        sheet.write(id, 99_i32).unwrap();
        assert_eq!(*sheet.read::<i32>(id).unwrap(), 99);
    }

    #[test]
    /// Checks typed-write rejection for an incompatible value.
    fn write_wrong_type_returns_type_mismatch() {
        let mut sheet = Sheet::new();
        let id = sheet.add_cell(0_i32);
        assert!(matches!(
            sheet.write(id, 1.0_f64),
            Err(Error::TypeMismatch { .. })
        ));
    }

    #[test]
    /// Checks typed-read rejection for an incompatible requested type.
    fn read_wrong_type_returns_type_mismatch() {
        let mut sheet = Sheet::new();
        let id = sheet.add_cell(0_i32);
        assert!(matches!(
            sheet.read::<f64>(id),
            Err(Error::TypeMismatch { .. })
        ));
    }

    #[test]
    /// Checks source/effective agreement without a derived override.
    fn source_matches_read_for_a_plain_unshadowed_cell() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(3_i32);
        assert_eq!(*sheet.source::<i32>(a).unwrap(), 3);
        assert_eq!(*sheet.read::<i32>(a).unwrap(), 3);

        sheet.write(a, 8_i32).unwrap();
        assert_eq!(*sheet.source::<i32>(a).unwrap(), 8);
        assert_eq!(*sheet.read::<i32>(a).unwrap(), 8);
    }

    #[test]
    /// Checks source lookup rejection for an unknown cell.
    fn source_returns_invalid_id_for_unknown_cell() {
        let sheet = Sheet::new();
        assert!(matches!(
            sheet.source::<i32>(CellId::default()),
            Err(Error::InvalidId)
        ));
    }

    #[test]
    /// Checks source lookup rejection for an incompatible requested type.
    fn source_wrong_type_returns_type_mismatch() {
        let mut sheet = Sheet::new();
        let id = sheet.add_cell(0_i32);
        assert!(matches!(
            sheet.source::<f64>(id),
            Err(Error::TypeMismatch { .. })
        ));
    }

    #[test]
    /// Checks rejection of a relationship without methods.
    fn add_relationship_empty_methods_returns_invalid_method() {
        let mut sheet = Sheet::new();
        let result = sheet.add_relationship(vec![]);
        assert!(matches!(result, Err(Error::InvalidMethod { .. })));
        assert!(result.unwrap_err().sites().is_empty());
    }

    #[test]
    /// Checks rejection of a method signature inconsistent with registered cell types.
    fn add_relationship_type_mismatch_returns_error() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(0_i32);
        // Method declares f64 input but cell holds i32.
        let method = Method::from_fn_1_1(a, b, |x: &f64| Ok(*x * 2.0));
        let result = sheet.add_relationship(vec![method]);
        assert!(matches!(result, Err(Error::TypeMismatch { .. })));
        assert_eq!(
            result.unwrap_err().sites().first().copied(),
            Some(ErrorSite::MethodIndex(0))
        );
    }

    #[test]
    /// Checks the producing method's site for a runtime output-type mismatch.
    fn execute_plan_type_mismatch_reports_the_method_that_produced_it() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(false); // bool cell
        // Declares an i32 output (matching nothing about `b`'s actual bool type at
        // add_relationship time -- add_relationship validates output_types against the cell,
        // so declare bool here to pass that check, then lie about it at runtime below).
        let method = Method::new(
            vec![a],
            vec![b],
            vec![TypeId::of::<i32>()],
            vec![TypeId::of::<bool>()],
            |args| {
                let x = *args[0].downcast_ref::<i32>().unwrap();
                // Lies: returns an i32 though output_types declared bool, reproducing the
                // execute_plan runtime type-mismatch path (add_relationship can't catch this --
                // it only checks the declared TypeId, not what the closure actually returns).
                Ok(vec![Box::new(x) as Box<dyn std::any::Any>])
            },
        );
        let rel_id = sheet.add_relationship(vec![method]).unwrap();
        let result = sheet.propagate();
        assert!(matches!(result, Err(Error::TypeMismatch { .. })));
        assert_eq!(
            result.unwrap_err().sites().first().copied(),
            Some(ErrorSite::Method(rel_id, 0))
        );
    }

    #[test]
    /// Checks the producing method's site for a callback failure.
    fn execute_plan_method_failed_reports_the_method_that_produced_it() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(0_i32);
        let method = Method::from_fn_1_1(a, b, |_: &i32| -> Result<i32, anyhow::Error> {
            Err(anyhow::anyhow!("boom"))
        });
        let rel_id = sheet.add_relationship(vec![method]).unwrap();
        let result = sheet.propagate();
        assert!(matches!(result, Err(Error::MethodFailed { .. })));
        assert_eq!(
            result.unwrap_err().sites().first().copied(),
            Some(ErrorSite::Method(rel_id, 0))
        );
    }

    #[test]
    /// Checks evaluation of a constant-producing zero-input method.
    fn add_relationship_zero_input_method_defines_a_fixed_point() {
        // A method with no inputs is a valid degenerate case: it always produces the
        // same value, independent of every other cell in the sheet.
        let mut sheet = Sheet::new();
        let b = sheet.add_cell(0_i32);
        let method = Method::new(vec![], vec![b], vec![], vec![TypeId::of::<i32>()], |_| {
            Ok(vec![Box::new(42_i32)])
        });
        let rel = sheet.add_relationship(vec![method]).unwrap();
        sheet.propagate().unwrap();
        assert_eq!(*sheet.read::<i32>(b).unwrap(), 42);
        assert!(sheet.is_forced(b));
        assert!(sheet.is_relationship_forced(rel));
    }

    #[test]
    /// Checks rejection of a method without outputs.
    fn add_relationship_empty_outputs_returns_invalid_method() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let method = Method::new(
            vec![a],
            vec![], // no outputs
            vec![TypeId::of::<i32>()],
            vec![],
            |_| Ok(vec![]),
        );
        let result = sheet.add_relationship(vec![method]);
        assert!(matches!(result, Err(Error::InvalidMethod { .. })));
        assert_eq!(
            result.unwrap_err().sites().first().copied(),
            Some(ErrorSite::MethodIndex(0))
        );
    }

    #[test]
    /// Checks acceptance of distinct output alternatives sharing one complete cell set.
    fn add_relationship_consistent_cell_sets_across_methods_succeeds() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(0_i32);
        let c = sheet.add_cell(0_i32);
        // Triangle relationship: every method references {a, b, c}.
        let result = sheet.add_relationship(vec![
            Method::from_fn_2_1([a, b], c, |x: &i32, y: &i32| Ok(x + y)),
            Method::from_fn_2_1([a, c], b, |x: &i32, y: &i32| Ok(y - x)),
            Method::from_fn_2_1([b, c], a, |x: &i32, y: &i32| Ok(y - x)),
        ]);
        assert!(result.is_ok());
    }

    #[test]
    /// Checks rejection of alternatives with different complete cell sets.
    fn add_relationship_inconsistent_cell_sets_across_methods_returns_mismatched_method_cells() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(0_i32);
        let c = sheet.add_cell(0_i32);
        // Method 0 references {a, b}; method 1 references {b, c} -- inconsistent.
        let result = sheet.add_relationship(vec![
            Method::from_fn_1_1(a, b, |v: &i32| Ok(*v)),
            Method::from_fn_1_1(b, c, |v: &i32| Ok(*v)),
        ]);
        assert!(matches!(result, Err(Error::MismatchedMethodCells { .. })));
        assert_eq!(
            result.unwrap_err().sites().first().copied(),
            Some(ErrorSite::MethodIndex(1))
        );
    }

    #[test]
    /// Checks rejection of alternatives with identical output sets.
    fn add_relationship_duplicate_output_set_across_methods_returns_invalid_method_outputs() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(0_i32);
        // Both methods reference {a, b} (so the cell-set-consistency check passes) but
        // both output {b} from different inputs -- their output sets are identical,
        // which must be rejected.
        let result = sheet.add_relationship(vec![
            Method::from_fn_2_1([a, b], b, |x: &i32, _y: &i32| Ok(*x)),
            Method::from_fn_2_1([a, b], b, |_x: &i32, y: &i32| Ok(*y)),
        ]);
        assert!(matches!(result, Err(Error::InvalidMethodOutputs { .. })));
        assert_eq!(
            result.unwrap_err().sites().first().copied(),
            Some(ErrorSite::MethodIndex(1))
        );
    }

    #[test]
    /// Checks rejection of strictly nested alternative output sets.
    fn add_relationship_rejects_strictly_nested_method_outputs() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(0_i32);
        let c = sheet.add_cell(0_i32);
        // Both methods span {a, b, c}; one outputs {b}, the other outputs {b, c}.
        let result = sheet.add_relationship(vec![
            Method::from_fn_2_1([a, c], b, |x: &i32, y: &i32| Ok(x + y)),
            Method::new(
                vec![a],
                vec![b, c],
                vec![std::any::TypeId::of::<i32>()],
                vec![std::any::TypeId::of::<i32>(), std::any::TypeId::of::<i32>()],
                |args| {
                    let x = *args[0].downcast_ref::<i32>().unwrap();
                    Ok(vec![Box::new(x), Box::new(x)])
                },
            ),
        ]);
        let err = result.unwrap_err();
        assert!(matches!(err, Error::InvalidMethodOutputs { .. }));
        let sites = err.sites();
        assert_eq!(sites[0], ErrorSite::MethodIndex(1));
        assert_eq!(sites[1], ErrorSite::MethodIndex(0));
        assert_eq!(sites[2..], [ErrorSite::Cell(b)]);
    }

    #[test]
    /// Checks acceptance of overlapping output alternatives without nesting.
    fn add_relationship_accepts_overlapping_non_nested_method_outputs() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(0_i32);
        let c = sheet.add_cell(0_i32);
        // Both methods span {a, b, c}; outputs overlap at b but neither set nests the other.
        let result = sheet.add_relationship(vec![
            Method::new(
                vec![a, c],
                vec![a, b],
                vec![std::any::TypeId::of::<i32>(), std::any::TypeId::of::<i32>()],
                vec![std::any::TypeId::of::<i32>(), std::any::TypeId::of::<i32>()],
                |args| {
                    let x = *args[0].downcast_ref::<i32>().unwrap();
                    let y = *args[1].downcast_ref::<i32>().unwrap();
                    Ok(vec![Box::new(x), Box::new(y)])
                },
            ),
            Method::new(
                vec![a, b],
                vec![b, c],
                vec![std::any::TypeId::of::<i32>(), std::any::TypeId::of::<i32>()],
                vec![std::any::TypeId::of::<i32>(), std::any::TypeId::of::<i32>()],
                |args| {
                    let x = *args[0].downcast_ref::<i32>().unwrap();
                    let y = *args[1].downcast_ref::<i32>().unwrap();
                    Ok(vec![Box::new(y), Box::new(x)])
                },
            ),
        ]);
        assert!(result.is_ok());
    }

    #[test]
    /// Checks distinct identities for separate relationship declarations.
    fn add_relationship_returns_distinct_ids() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(0_i32);
        let r1 = sheet
            .add_relationship(vec![Method::from_fn_1_1(a, b, |x: &i32| Ok(*x))])
            .unwrap();
        let c = sheet.add_cell(0_i32);
        let r2 = sheet
            .add_relationship(vec![Method::from_fn_1_1(b, c, |x: &i32| Ok(*x))])
            .unwrap();
        assert_ne!(r1, r2);
    }

    #[test]
    /// Checks rejection of inconsistent positional cell sets.
    fn add_relationship_mismatched_cells_returns_error() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(0_i32);
        let c = sheet.add_cell(0_i32);
        let d = sheet.add_cell(0_i32);
        // Method 0 spans {a, b}; Method 1 spans {c, d} — mismatched cell sets.
        let result = sheet.add_relationship(vec![
            Method::from_fn_1_1(a, b, |x: &i32| Ok(*x)),
            Method::from_fn_1_1(c, d, |x: &i32| Ok(*x)),
        ]);
        assert!(matches!(result, Err(Error::MismatchedMethodCells { .. })));
        assert_eq!(
            result.unwrap_err().sites().first().copied(),
            Some(ErrorSite::MethodIndex(1))
        );
    }

    #[test]
    /// Checks rejection of duplicate alternative output sets.
    fn add_relationship_duplicate_output_sets_across_methods_returns_error() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(0_i32);
        let c = sheet.add_cell(0_i32);
        // Both methods span {a, b, c} and both output {c} — identical output sets.
        let result = sheet.add_relationship(vec![
            Method::from_fn_2_1([a, b], c, |x: &i32, y: &i32| Ok(*x + *y)),
            Method::from_fn_2_1([a, b], c, |x: &i32, y: &i32| Ok(*x - *y)),
        ]);
        assert!(matches!(result, Err(Error::InvalidMethodOutputs { .. })));
        assert_eq!(
            result.unwrap_err().sites().first().copied(),
            Some(ErrorSite::MethodIndex(1))
        );
    }

    #[test]
    /// Checks rejection of a repeated output identity within one method.
    fn add_relationship_duplicate_cell_within_own_outputs_returns_error() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(0_i32);
        // The method's own outputs list names `b` twice.
        let method = Method::new(
            vec![a],
            vec![b, b],
            vec![TypeId::of::<i32>()],
            vec![TypeId::of::<i32>(), TypeId::of::<i32>()],
            |args| {
                let x = args[0].downcast_ref::<i32>().unwrap();
                Ok(vec![Box::new(*x), Box::new(*x)])
            },
        );
        let result = sheet.add_relationship(vec![method]);
        assert!(matches!(result, Err(Error::InvalidMethodOutputs { .. })));
        assert_eq!(
            result.unwrap_err().sites().first().copied(),
            Some(ErrorSite::MethodIndex(0))
        );
    }

    #[test]
    /// Checks both method sites and the differing cell in a cell-set mismatch.
    fn mismatched_method_cells_names_both_methods_and_the_differing_cell() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(0_i32);
        let c = sheet.add_cell(0_i32);
        // method 0 references {a,b}; method 1 references {a,c}: c (and b) diverge.
        let err = sheet
            .add_relationship(vec![
                Method::from_fn_1_1(a, b, |x: &i32| Ok(*x)),
                Method::from_fn_1_1(a, c, |x: &i32| Ok(*x)),
            ])
            .unwrap_err();
        let sites = err.sites();
        assert_eq!(sites[0], ErrorSite::MethodIndex(1));
        assert_eq!(sites[1], ErrorSite::MethodIndex(0));
        assert!(sites[2..].contains(&ErrorSite::Cell(c)));
    }

    #[test]
    /// Checks both method sites and the shared cell in a duplicate-output error.
    fn duplicate_output_set_across_methods_names_both_methods_and_the_shared_cell() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(0_i32);
        // both methods reference {a,b} and both output b.
        let err = sheet
            .add_relationship(vec![
                Method::from_fn_1_1(a, b, |x: &i32| Ok(*x)),
                Method::from_fn_1_1(a, b, |x: &i32| Ok(*x + 1)),
            ])
            .unwrap_err();
        let sites = err.sites();
        assert_eq!(sites[0], ErrorSite::MethodIndex(1));
        assert_eq!(sites[1], ErrorSite::MethodIndex(0));
        assert!(sites[2..].contains(&ErrorSite::Cell(b)));
    }

    #[test]
    /// Checks the method and repeated-cell sites for duplicate positional outputs.
    fn duplicate_cell_within_own_outputs_names_the_method_and_the_repeated_cell() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(0_i32);
        let i32_ty = std::any::TypeId::of::<i32>();
        // one method whose outputs name b twice.
        let err = sheet
            .add_relationship(vec![Method::new(
                vec![a],
                vec![b, b],
                vec![i32_ty],
                vec![i32_ty, i32_ty],
                |args| {
                    let v = *args[0].downcast_ref::<i32>().unwrap();
                    Ok(vec![Box::new(v), Box::new(v)])
                },
            )])
            .unwrap_err();
        let sites = err.sites();
        assert_eq!(sites[0], ErrorSite::MethodIndex(0));
        assert!(sites[1..].contains(&ErrorSite::Cell(b)));
    }

    #[test]
    /// Checks deduplication of diagnostic cell sites for repeated outputs.
    fn duplicate_cell_repeated_three_times_reports_cell_once() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(0_i32);
        let i32_ty = std::any::TypeId::of::<i32>();
        // one method whose outputs name b three times.
        let err = sheet
            .add_relationship(vec![Method::new(
                vec![a],
                vec![b, b, b],
                vec![i32_ty],
                vec![i32_ty, i32_ty, i32_ty],
                |args| {
                    let v = *args[0].downcast_ref::<i32>().unwrap();
                    Ok(vec![Box::new(v), Box::new(v), Box::new(v)])
                },
            )])
            .unwrap_err();
        let sites = err.sites();
        assert_eq!(sites[0], ErrorSite::MethodIndex(0));
        let cell_sites: Vec<_> = sites[1..]
            .iter()
            .filter(|&&s| s == ErrorSite::Cell(b))
            .collect();
        assert_eq!(
            cell_sites.len(),
            1,
            "expected exactly one Cell(b) site for a triple repeat, got {sites:?}"
        );
    }

    #[test]
    /// Checks an empty changed set before propagation.
    fn changed_is_empty_before_propagate() {
        let sheet = Sheet::new();
        assert_eq!(sheet.changed().count(), 0);
    }

    #[test]
    /// Checks changed membership for committed method outputs.
    fn changed_after_propagate_contains_method_outputs() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(0_i32);
        sheet
            .add_relationship(vec![Method::from_fn_1_1(a, b, |x: &i32| Ok(*x * 2))])
            .unwrap();
        sheet.write(a, 3_i32).unwrap();
        sheet.propagate().unwrap();
        let changed: Vec<_> = sheet.changed().collect();
        assert_eq!(changed, vec![b]);
    }

    #[test]
    /// Checks explicit clearing of changed membership.
    fn clear_changed_empties_changed_set() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(0_i32);
        sheet
            .add_relationship(vec![Method::from_fn_1_1(a, b, |x: &i32| Ok(*x * 2))])
            .unwrap();
        sheet.write(a, 3_i32).unwrap();
        sheet.propagate().unwrap();
        sheet.clear_changed();
        assert_eq!(sheet.changed().count(), 0);
    }

    #[test]
    /// Checks replacement of previous changed membership after reversing method direction.
    fn propagate_clears_previous_changed_set() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(0_i32);
        sheet
            .add_relationship(vec![
                Method::from_fn_1_1(a, b, |x: &i32| Ok(*x)),
                Method::from_fn_1_1(b, a, |x: &i32| Ok(*x)),
            ])
            .unwrap();
        sheet.write(a, 3_i32).unwrap();
        sheet.propagate().unwrap();
        assert_eq!(sheet.changed().collect::<Vec<_>>(), vec![b]);
        sheet.write(b, 5_i32).unwrap();
        sheet.propagate().unwrap();
        let changed: Vec<_> = sheet.changed().collect();
        assert_eq!(changed, vec![a]);
    }

    #[test]
    /// Checks enumeration of every live cell identity.
    fn cells_returns_all_cell_ids() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(0_i32);
        let ids: Vec<_> = sheet.cells().collect();
        assert!(ids.contains(&a));
        assert!(ids.contains(&b));
        assert_eq!(ids.len(), 2);
    }

    #[test]
    /// Checks empty cell enumeration on a new sheet.
    fn cells_returns_empty_for_empty_sheet() {
        let sheet = Sheet::new();
        assert_eq!(sheet.cells().count(), 0);
    }

    #[test]
    /// Checks enumeration of every live relationship identity.
    fn relationships_returns_all_relationship_ids() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(0_i32);
        let r = sheet
            .add_relationship(vec![Method::from_fn_1_1(a, b, |x: &i32| Ok(*x))])
            .unwrap();
        let ids: Vec<_> = sheet.relationships().collect();
        assert_eq!(ids, vec![r]);
    }

    #[test]
    /// Checks empty relationship enumeration on a new sheet.
    fn relationships_returns_empty_for_empty_sheet() {
        let sheet = Sheet::new();
        assert_eq!(sheet.relationships().count(), 0);
    }

    #[test]
    /// Checks a cell's adjacent relationship identities.
    fn cell_adj_returns_adjacent_relationships() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(0_i32);
        let r = sheet
            .add_relationship(vec![Method::from_fn_1_1(a, b, |x: &i32| Ok(*x))])
            .unwrap();
        assert!(sheet.cell_adj(a).unwrap().contains(&r));
        assert!(sheet.cell_adj(b).unwrap().contains(&r));
    }

    #[test]
    /// Checks absent adjacency for an unknown cell.
    fn cell_adj_returns_none_for_invalid_id() {
        let sheet = Sheet::new();
        assert!(sheet.cell_adj(CellId::default()).is_none());
    }

    #[test]
    /// Checks a relationship's complete adjacent cell set.
    fn relationship_adj_returns_adjacent_cells() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(0_i32);
        let r = sheet
            .add_relationship(vec![Method::from_fn_1_1(a, b, |x: &i32| Ok(*x))])
            .unwrap();
        let adj = sheet.relationship_adj(r).unwrap();
        assert!(adj.contains(&a));
        assert!(adj.contains(&b));
    }

    #[test]
    /// Checks absent adjacency for an unknown relationship.
    fn relationship_adj_returns_none_for_invalid_id() {
        let sheet = Sheet::new();
        assert!(sheet.relationship_adj(RelationshipId::default()).is_none());
    }

    #[test]
    /// Checks absence of a selected method before propagation.
    fn selected_method_returns_none_before_propagate() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(0_i32);
        let rel = sheet
            .add_relationship(vec![Method::from_fn_1_1(a, b, |x: &i32| Ok(*x))])
            .unwrap();
        assert!(sheet.selected_method(rel).is_none());
    }

    #[test]
    /// Checks the completed plan's selected method index.
    fn selected_method_returns_index_after_propagate() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(0_i32);
        let rel = sheet
            .add_relationship(vec![Method::from_fn_1_1(a, b, |x: &i32| Ok(*x))])
            .unwrap();
        // Write to `a` so it has the highest strength and becomes the source,
        // making the a → b method eligible.
        sheet.write(a, 0_i32).unwrap();
        sheet.propagate().unwrap();
        assert_eq!(sheet.selected_method(rel), Some(0));
    }

    #[test]
    /// Checks positional input lookup for a live method.
    fn method_inputs_returns_inputs_for_valid_method() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(0_i32);
        let rel = sheet
            .add_relationship(vec![Method::from_fn_1_1(a, b, |x: &i32| Ok(*x))])
            .unwrap();
        assert_eq!(sheet.method_inputs(rel, 0), Some([a].as_slice()));
    }

    #[test]
    /// Checks positional output lookup for a live method.
    fn method_outputs_returns_outputs_for_valid_method() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(0_i32);
        let rel = sheet
            .add_relationship(vec![Method::from_fn_1_1(a, b, |x: &i32| Ok(*x))])
            .unwrap();
        assert_eq!(sheet.method_outputs(rel, 0), Some([b].as_slice()));
    }

    #[test]
    /// Checks absent input metadata for an invalid method index.
    fn method_inputs_returns_none_for_out_of_bounds_idx() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(0_i32);
        let rel = sheet
            .add_relationship(vec![Method::from_fn_1_1(a, b, |x: &i32| Ok(*x))])
            .unwrap();
        assert!(sheet.method_inputs(rel, 99).is_none());
    }

    #[test]
    /// Checks absent output metadata for an invalid method index.
    fn method_outputs_returns_none_for_out_of_bounds_idx() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(0_i32);
        let rel = sheet
            .add_relationship(vec![Method::from_fn_1_1(a, b, |x: &i32| Ok(*x))])
            .unwrap();
        assert!(sheet.method_outputs(rel, 99).is_none());
    }

    #[test]
    /// Checks absence of completed-plan source classification before propagation.
    fn is_source_returns_false_before_propagate() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(0_i32);
        sheet
            .add_relationship(vec![Method::from_fn_1_1(a, b, |x: &i32| Ok(*x))])
            .unwrap();
        assert!(!sheet.is_source(a));
    }

    #[test]
    /// Checks source classification of an unclaimed input after propagation.
    fn is_source_returns_true_for_input_cell_after_propagate() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(0_i32);
        sheet
            .add_relationship(vec![Method::from_fn_1_1(a, b, |x: &i32| Ok(*x))])
            .unwrap();
        // Write to `a` so it has the highest strength and becomes the source.
        sheet.write(a, 0_i32).unwrap();
        sheet.propagate().unwrap();
        assert!(sheet.is_source(a));
    }

    #[test]
    /// Checks non-source classification of a selected method's output.
    fn is_source_returns_false_for_output_cell_after_propagate() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(0_i32);
        sheet
            .add_relationship(vec![Method::from_fn_1_1(a, b, |x: &i32| Ok(*x))])
            .unwrap();
        // Write to `a` so it has the highest strength and becomes the source.
        sheet.write(a, 0_i32).unwrap();
        sheet.propagate().unwrap();
        assert!(!sheet.is_source(b));
    }

    // ── Conditional accessor tests ─────────────────────────────────────────

    /// Builds a sheet with two keyed branches and returns its conditional identity.
    fn sheet_with_two_branch_conditional() -> (Sheet, ConditionalId) {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(0_i32);
        let p = sheet.add_cell(0_i32);

        let rel0 = sheet
            .add_relationship(vec![Method::from_fn_1_1(a, b, |v: &i32| Ok(*v))])
            .unwrap();
        let rel1 = sheet
            .add_relationship(vec![Method::from_fn_1_1(b, a, |v: &i32| Ok(*v))])
            .unwrap();

        let cid = sheet
            .add_conditional(
                MatchExpr::cell(p),
                vec![(vec![0_i32], vec![rel0]), (vec![1_i32], vec![rel1])],
                vec![],
            )
            .unwrap();
        (sheet, cid)
    }

    /// Builds a conditional fixture and identifies its default relationship.
    fn sheet_with_default_conditional() -> (Sheet, ConditionalId, RelationshipId) {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let b = sheet.add_cell(0_i32);
        let p = sheet.add_cell(99_i32); // no branch matches → default

        let rel_default = sheet
            .add_relationship(vec![Method::from_fn_1_1(a, b, |v: &i32| Ok(*v))])
            .unwrap();

        let cid = sheet
            .add_conditional::<i32>(MatchExpr::cell(p), vec![], vec![rel_default])
            .unwrap();
        (sheet, cid, rel_default)
    }

    #[test]
    /// Checks enumeration of a registered conditional identity.
    fn conditionals_returns_registered_id() {
        let (sheet, cid) = sheet_with_two_branch_conditional();
        assert!(sheet.conditionals().any(|id| id == cid));
    }

    #[test]
    /// Checks empty conditional enumeration on a new sheet.
    fn conditionals_empty_on_new_sheet() {
        let sheet = Sheet::new();
        assert_eq!(sheet.conditionals().count(), 0);
    }

    #[test]
    /// Checks the registered conditional's match-cell identity.
    fn conditional_match_cells_returns_correct_cell() {
        let mut sheet = Sheet::new();
        let p = sheet.add_cell(0_i32);
        let cid = sheet
            .add_conditional::<i32>(MatchExpr::cell(p), vec![], vec![])
            .unwrap();
        assert_eq!(sheet.conditional_match_cells(cid), Some([p].as_slice()));
    }

    #[test]
    /// Checks absent match inputs for an unknown conditional.
    fn conditional_match_cells_returns_none_for_invalid_id() {
        let sheet = Sheet::new();
        assert_eq!(
            sheet.conditional_match_cells(ConditionalId::default()),
            None
        );
    }

    #[test]
    /// Checks the authored explicit-branch count.
    fn conditional_branch_count_returns_correct_count() {
        let (sheet, cid) = sheet_with_two_branch_conditional();
        assert_eq!(sheet.conditional_branch_count(cid), Some(2));
    }

    #[test]
    /// Checks absent branch counts for an unknown conditional.
    fn conditional_branch_count_returns_none_for_invalid_id() {
        let sheet = Sheet::new();
        assert_eq!(
            sheet.conditional_branch_count(ConditionalId::default()),
            None
        );
    }

    #[test]
    /// Checks the exact authored relationship identities of both explicit branches.
    fn conditional_branch_relationships_returns_correct_rels() {
        let (sheet, cid) = sheet_with_two_branch_conditional();
        let rels0 = sheet.conditional_branch_relationships(cid, 0).unwrap();
        let rels1 = sheet.conditional_branch_relationships(cid, 1).unwrap();
        let authored: Vec<_> = sheet.relationships().collect();
        assert_eq!(rels0, [authored[0]]);
        assert_eq!(rels1, [authored[1]]);
    }

    #[test]
    /// Checks absent relationship metadata for an invalid branch index.
    fn conditional_branch_relationships_returns_none_for_out_of_bounds() {
        let (sheet, cid) = sheet_with_two_branch_conditional();
        assert!(sheet.conditional_branch_relationships(cid, 2).is_none());
    }

    #[test]
    /// Checks absent branch relationships for an unknown conditional.
    fn conditional_branch_relationships_returns_none_for_invalid_id() {
        let sheet = Sheet::new();
        assert!(
            sheet
                .conditional_branch_relationships(ConditionalId::default(), 0)
                .is_none()
        );
    }

    #[test]
    /// Checks the exact authored default-relationship identity.
    fn conditional_default_relationships_returns_correct_rels() {
        let (sheet, cid, rel_default) = sheet_with_default_conditional();
        let rels = sheet.conditional_default_relationships(cid).unwrap();
        assert_eq!(rels, [rel_default]);
    }

    #[test]
    /// Checks empty default membership when no default is declared.
    fn conditional_default_relationships_empty_when_no_default() {
        let (sheet, cid) = sheet_with_two_branch_conditional();
        assert_eq!(sheet.conditional_default_relationships(cid).unwrap(), &[]);
    }

    #[test]
    /// Checks absent default metadata for an unknown conditional.
    fn conditional_default_relationships_returns_none_for_invalid_id() {
        let sheet = Sheet::new();
        assert!(
            sheet
                .conditional_default_relationships(ConditionalId::default())
                .is_none()
        );
    }

    #[test]
    /// Checks branch-index lookup for a matching subject.
    fn conditional_active_branch_returns_matching_branch_index() {
        let (mut sheet, cid) = sheet_with_two_branch_conditional();
        let p = sheet.conditional_match_cells(cid).unwrap()[0];
        sheet.write(p, 0_i32).unwrap();
        assert_eq!(sheet.conditional_active_branch(cid).unwrap(), Some(0));
        sheet.write(p, 1_i32).unwrap();
        assert_eq!(sheet.conditional_active_branch(cid).unwrap(), Some(1));
    }

    #[test]
    /// Checks absent explicit-branch selection for an unmatched subject.
    fn conditional_active_branch_returns_none_when_no_branch_matches() {
        let (mut sheet, cid) = sheet_with_two_branch_conditional();
        let p = sheet.conditional_match_cells(cid).unwrap()[0];
        sheet.write(p, 99_i32).unwrap();
        assert_eq!(sheet.conditional_active_branch(cid).unwrap(), None);
    }

    #[test]
    /// Checks absent branch selection for an unknown conditional.
    fn conditional_active_branch_returns_none_for_invalid_id() {
        let sheet = Sheet::new();
        assert_eq!(
            sheet
                .conditional_active_branch(ConditionalId::default())
                .unwrap(),
            None
        );
    }

    #[test]
    /// Checks filter attachment rejection for an unknown governed cell.
    fn add_filter_returns_invalid_id_for_missing_cell() {
        let mut sheet = Sheet::new();
        let result = sheet.add_filter(CellId::default(), Filter::from_fn_0(|x: &i32| Ok(*x)));
        assert!(matches!(result, Err(Error::InvalidId)));
    }

    #[test]
    /// Checks that attachment alone preserves the cell's current value.
    fn add_filter_does_not_change_the_cells_current_value() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(500_i32);
        sheet
            .add_filter(a, Filter::from_fn_0(|x: &i32| Ok((*x).clamp(0, 100))))
            .unwrap();
        // add_filter never evaluates the function against the current value: the raw
        // out-of-range value survives until the next propagate().
        assert_eq!(*sheet.read::<i32>(a).unwrap(), 500);
    }

    #[test]
    /// Checks conformance of the initial value at propagation rather than attachment.
    fn propagate_after_add_filter_conforms_the_initial_value() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(500_i32);
        sheet
            .add_filter(a, Filter::from_fn_0(|x: &i32| Ok((*x).clamp(0, 100))))
            .unwrap();
        assert_eq!(*sheet.read::<i32>(a).unwrap(), 500);
        sheet.propagate().unwrap();
        // `a` has no filter args and belongs to no relationship — this is the ordinary
        // first-round case of Task 1's fix, not a special "cold start" path.
        assert_eq!(*sheet.read::<i32>(a).unwrap(), 100);
    }

    #[test]
    /// Checks rejection of a second filter on the same cell.
    fn add_filter_returns_invalid_filter_when_cell_already_has_a_filter() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(5_i32);
        sheet
            .add_filter(a, Filter::from_fn_0(|x: &i32| Ok(*x)))
            .unwrap();
        let result = sheet.add_filter(a, Filter::from_fn_0(|x: &i32| Ok(*x)));
        assert!(matches!(result, Err(Error::InvalidFilter)));
    }

    #[test]
    /// Checks rejection of a filter declaring the wrong governed-value type.
    fn add_filter_returns_invalid_filter_for_mismatched_value_type() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(5_i32);
        let result = sheet.add_filter(a, Filter::from_fn_0(|x: &f64| Ok(*x)));
        assert!(matches!(result, Err(Error::InvalidFilter)));
    }

    #[test]
    /// Checks rejection of a filter's direct dynamic self-dependency.
    fn add_filter_returns_invalid_filter_when_args_name_the_filtered_cell_itself() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(5_i32);
        let result = sheet.add_filter(
            a,
            Filter::from_fn_1(a, |x: &i32, bound: &i32| Ok((*x).min(*bound))),
        );
        assert!(matches!(result, Err(Error::InvalidFilter)));
    }

    #[test]
    /// Checks filter attachment rejection for an unknown argument.
    fn add_filter_returns_invalid_id_for_missing_arg_cell() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(5_i32);
        let result = sheet.add_filter(
            a,
            Filter::from_fn_1(CellId::default(), |x: &i32, bound: &i32| {
                Ok((*x).min(*bound))
            }),
        );
        assert!(matches!(result, Err(Error::InvalidId)));
    }

    #[test]
    /// Checks filter attachment rejection for an incompatible argument type.
    fn add_filter_returns_type_mismatch_for_wrong_arg_cell_type() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(5_i32);
        let bound = sheet.add_cell(1.0_f64); // wrong type: filter declares i32
        let result = sheet.add_filter(
            a,
            Filter::from_fn_1(bound, |x: &i32, bound: &i32| Ok((*x).min(*bound))),
        );
        assert!(matches!(result, Err(Error::TypeMismatch { .. })));
    }

    #[test]
    /// Checks filter attachment to a source-only cell.
    fn add_filter_succeeds_on_a_source_kind_cell() {
        let mut sheet = Sheet::new();
        let a = sheet.add_source(5_i32);
        assert!(
            sheet
                .add_filter(a, Filter::from_fn_0(|x: &i32| Ok((*x).clamp(0, 10))))
                .is_ok()
        );
    }

    #[test]
    /// Checks that both dynamic bounds affect a binary filter's conformed value.
    fn from_fn_2_conforms_values_through_sheet_using_both_dynamic_arguments() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(500_i32);
        let lo = sheet.add_cell(0_i32);
        let hi = sheet.add_cell(100_i32);
        sheet
            .add_filter(
                a,
                Filter::from_fn_2([lo, hi], |x: &i32, lo: &i32, hi: &i32| {
                    Ok((*x).clamp(*lo, *hi))
                }),
            )
            .unwrap();
        sheet.propagate().unwrap();
        assert_eq!(*sheet.read::<i32>(a).unwrap(), 100);

        sheet.write(a, -10_i32).unwrap();
        sheet.propagate().unwrap();
        assert_eq!(*sheet.read::<i32>(a).unwrap(), 0);
    }

    #[test]
    /// Checks direct source/effective publication by an unfiltered write.
    fn write_without_a_filter_behaves_exactly_as_before() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        sheet.write(a, 42_i32).unwrap();
        assert_eq!(*sheet.read::<i32>(a).unwrap(), 42);
    }

    #[test]
    /// Checks preservation of the raw aspiration across deferred filtering.
    fn write_leaves_the_raw_value_in_source_until_propagate_conforms_it() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        sheet
            .add_filter(a, Filter::from_fn_0(|x: &i32| Ok((*x).clamp(0, 100))))
            .unwrap();
        sheet.write(a, 500_i32).unwrap();
        // write() no longer runs the filter: the raw value stands until propagate().
        assert_eq!(*sheet.read::<i32>(a).unwrap(), 500);
        sheet.propagate().unwrap();
        assert_eq!(*sheet.read::<i32>(a).unwrap(), 100);
    }

    #[test]
    /// Checks absence of diagnostics for a conforming derived value.
    fn propagate_reports_no_violation_when_a_derived_value_conforms() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(10_i32);
        let b = sheet.add_cell(0_i32);
        sheet
            .add_filter(b, Filter::from_fn_0(|x: &i32| Ok((*x).clamp(0, 100))))
            .unwrap();
        sheet
            .add_relationship(vec![Method::from_fn_1_1(a, b, |x: &i32| Ok(*x))])
            .unwrap();
        sheet.propagate().unwrap();
        assert_eq!(*sheet.read::<i32>(b).unwrap(), 10);
        assert!(sheet.last_filter_violations.is_empty());
    }

    #[test]
    /// Checks a soft nonconformance diagnostic without rewriting a derived value.
    fn propagate_reports_not_conformed_when_a_derived_value_violates_its_filter() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(60_i32);
        let b = sheet.add_cell(0_i32);
        sheet
            .add_filter(b, Filter::from_fn_0(|x: &i32| Ok((*x).clamp(0, 100))))
            .unwrap();
        sheet
            .add_relationship(vec![Method::from_fn_1_1(a, b, |x: &i32| Ok(*x * 2))])
            .unwrap();
        sheet.propagate().unwrap();
        // 60 * 2 = 120, clamp(0, 100) => 100 != 120.
        assert_eq!(*sheet.read::<i32>(b).unwrap(), 120);
        assert!(matches!(
            sheet.last_filter_violations.get(&b),
            Some(FilterViolation::NotConformed)
        ));
    }

    #[test]
    /// Checks a soft callback-failure diagnostic for a derived value.
    fn propagate_reports_failed_when_the_filter_errors_on_a_derived_value() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(1_i32);
        let b = sheet.add_cell(0_i32);
        // Accept exactly 0 (b's initial value) so this filter's shape is exercised
        // only by the relationship's derived value (1, copied from `a`), not by
        // anything add_filter itself does — add_filter no longer evaluates a filter's
        // function at all.
        sheet
            .add_filter(
                b,
                Filter::from_fn_0(|x: &i32| {
                    if *x == 0 {
                        Ok(*x)
                    } else {
                        Err(anyhow::anyhow!("cannot conform"))
                    }
                }),
            )
            .unwrap();
        sheet
            .add_relationship(vec![Method::from_fn_1_1(a, b, |x: &i32| Ok(*x))])
            .unwrap();
        // propagate() must not abort even though the filter errors.
        sheet.propagate().unwrap();
        assert!(matches!(
            sheet.last_filter_violations.get(&b),
            Some(FilterViolation::Failed(_))
        ));
    }

    #[test]
    /// Checks a soft type-failure diagnostic for a malformed derived-value filter result.
    fn propagate_reports_failed_when_the_filter_returns_the_wrong_type_on_a_derived_value() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(1_i32);
        let b = sheet.add_cell(0_i32);
        // Returns a `f64` for a nonzero derived value, tripping
        // propagate()'s diagnostic-phase defensive check once `a`'s value (1) is
        // copied into `b` this round.
        let filter = Filter::new(TypeId::of::<i32>(), vec![], vec![], |value, _args| {
            let v = *value.downcast_ref::<i32>().unwrap();
            if v == 0 {
                Ok(Box::new(v) as Box<dyn Any>)
            } else {
                Ok(Box::new(1.5_f64) as Box<dyn Any>)
            }
        });
        sheet.add_filter(b, filter).unwrap();
        sheet
            .add_relationship(vec![Method::from_fn_1_1(a, b, |x: &i32| Ok(*x))])
            .unwrap();
        // propagate() must not abort even though the filter's function returns the
        // wrong type.
        sheet.propagate().unwrap();
        assert!(matches!(
            sheet.filter_violation(b),
            Some(FilterViolation::Failed(_))
        ));
    }

    #[test]
    /// Checks absence of nonconformance diagnostics for a successfully conformed source.
    fn propagate_never_flags_a_filtered_cell_that_stayed_a_plain_source() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(60_i32);
        sheet
            .add_filter(a, Filter::from_fn_0(|x: &i32| Ok((*x).clamp(0, 100))))
            .unwrap();
        sheet.propagate().unwrap();
        assert!(sheet.last_filter_violations.is_empty());
    }

    #[test]
    /// Checks reclamping of a source after its dynamic argument changes.
    fn propagate_reclamps_a_filtered_source_cell_when_its_argument_changes() {
        // Issue #132's exact repro.
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(50_i32);
        let bound = sheet.add_cell(100_i32);
        sheet
            .add_filter(
                a,
                Filter::from_fn_1(bound, |v: &i32, b: &i32| Ok((*v).min(*b))),
            )
            .unwrap();
        sheet.write(bound, 10_i32).unwrap();
        sheet.propagate().unwrap();
        assert_eq!(*sheet.read::<i32>(a).unwrap(), 10);
    }

    #[test]
    /// Checks that downstream methods consume the settled conformed source.
    fn propagate_reclamps_before_a_relationship_consumes_the_reclamped_value() {
        // The inequality.adm2-shaped case: a and b are linked by a two-method mutual
        // relationship (b := min(a, b); a := max(a, b)); a is the currently-source cell
        // of the pair and is filtered against a bound that just shrank. b (derived) must
        // reflect the corrected a, not the pre-reclamp one, within a single propagate().
        //
        // b is created before a so that a (created later) outranks b in strength —
        // release::resolve keeps the higher-strength cell a source (see
        // release::tests::strength_prefers_the_higher_strength_cell_as_source) — making a
        // the source and b the derived cell of the pair, as this test needs.
        let mut sheet = Sheet::new();
        let b = sheet.add_cell(20_i32);
        let a = sheet.add_cell(50_i32);
        let bound = sheet.add_cell(100_i32);
        sheet
            .add_filter(
                a,
                Filter::from_fn_1(bound, |v: &i32, bnd: &i32| Ok((*v).min(*bnd))),
            )
            .unwrap();
        sheet
            .add_relationship(vec![
                Method::from_fn_2_1([a, b], b, |x: &i32, y: &i32| Ok((*x).min(*y))),
                Method::from_fn_2_1([a, b], a, |x: &i32, y: &i32| Ok((*x).max(*y))),
            ])
            .unwrap();
        sheet.propagate().unwrap();

        sheet.write(bound, 5_i32).unwrap();
        sheet.propagate().unwrap();

        // a reclamps to min(50, 5) = 5; b's method (a.min(b)) then reads the reclamped
        // a, not the stale 50.
        assert_eq!(*sheet.read::<i32>(a).unwrap(), 5);
        assert_eq!(*sheet.read::<i32>(b).unwrap(), 5);
    }

    #[test]
    /// Checks restoration of the stored aspiration when a dynamic bound loosens.
    fn filtered_source_cell_springs_back_to_its_original_value_when_a_bound_loosens() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(50_i32);
        let bound = sheet.add_cell(100_i32);
        sheet
            .add_filter(
                a,
                Filter::from_fn_1(bound, |v: &i32, b: &i32| Ok((*v).min(*b))),
            )
            .unwrap();

        sheet.write(bound, 10_i32).unwrap();
        sheet.propagate().unwrap();
        assert_eq!(*sheet.read::<i32>(a).unwrap(), 10);

        sheet.write(bound, 100_i32).unwrap();
        sheet.propagate().unwrap();
        // a's original 50 must survive in `source` across the whole round-trip: it
        // springs back once the bound loosens again, rather than staying stuck at the
        // intermediate clamp.
        assert_eq!(*sheet.read::<i32>(a).unwrap(), 50);
    }

    #[test]
    /// Checks a soft diagnostic for a malformed successful source-filter result.
    fn filter_reclamp_records_failed_violation_when_the_filters_function_returns_the_wrong_type() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(5_i32);
        let trigger = sheet.add_cell(0_i32);
        // Returns an f64 when trigger becomes non-zero,
        // tripping FilterReclamp's check once `trigger` is updated.
        let filter = Filter::new(
            TypeId::of::<i32>(),
            vec![trigger],
            vec![TypeId::of::<i32>()],
            |value, args| {
                let v = *value.downcast_ref::<i32>().unwrap();
                let t = *args[0].downcast_ref::<i32>().unwrap();
                if t == 0 {
                    Ok(Box::new(v) as Box<dyn Any>)
                } else {
                    Ok(Box::new(1.5_f64) as Box<dyn Any>)
                }
            },
        );
        sheet.add_filter(a, filter).unwrap();

        // trigger changes, causing reclamp where the filter returns wrong type
        sheet.write(trigger, 1_i32).unwrap();
        sheet.propagate().unwrap();

        assert!(matches!(
            sheet.filter_violation(a),
            Some(FilterViolation::Failed(_))
        ));
        // The wrong-type result is discarded: the cell's stored value is unchanged.
        assert_eq!(*sheet.read::<i32>(a).unwrap(), 5);
    }

    #[test]
    /// Checks that a failed reclamp preserves the cell and does not abort propagation.
    fn filter_reclamp_failure_is_recorded_without_aborting_propagate_or_changing_the_cell() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(5_i32);
        let bound = sheet.add_cell(100_i32);
        // Accept anything up to `bound` (a's initial 5 is within bound's initial 100);
        // the write to `bound` below is what trips the filter's next live reclamp.
        sheet
            .add_filter(
                a,
                Filter::from_fn_1(bound, |v: &i32, b: &i32| {
                    if *v <= *b {
                        Ok(*v)
                    } else {
                        Err(anyhow::anyhow!("cannot conform"))
                    }
                }),
            )
            .unwrap();
        sheet.write(bound, 0_i32).unwrap();

        sheet.propagate().unwrap();

        assert!(matches!(
            sheet.filter_violation(a),
            Some(FilterViolation::Failed(_))
        ));
        // Rejected reclamp: the cell's stored value is left completely unchanged.
        assert_eq!(*sheet.read::<i32>(a).unwrap(), 5);
    }

    #[test]
    /// Checks positional lookup of a filter's dynamic argument identities.
    fn filter_args_returns_the_filters_argument_cells() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(5_i32);
        let bound = sheet.add_cell(10_i32);
        sheet
            .add_filter(
                a,
                Filter::from_fn_1(bound, |x: &i32, bound: &i32| Ok((*x).min(*bound))),
            )
            .unwrap();
        assert_eq!(sheet.filter_args(a), Some(&[bound][..]));
    }

    #[test]
    /// Checks absent argument metadata on an unfiltered cell.
    fn filter_args_returns_none_for_a_cell_with_no_filter() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(5_i32);
        assert_eq!(sheet.filter_args(a), None);
    }

    #[test]
    /// Checks absent filter arguments for an unknown cell.
    fn filter_args_returns_none_for_an_invalid_cell() {
        let sheet = Sheet::new();
        assert_eq!(sheet.filter_args(CellId::default()), None);
    }

    #[test]
    /// Checks absence of filter diagnostics before propagation.
    fn filter_violation_returns_none_before_any_propagate() {
        let mut sheet = Sheet::new();
        let cell = sheet.add_cell(100_i32);
        sheet
            .add_filter(
                cell,
                Filter::from_fn_0(|value: &i32| Ok((*value).clamp(0, 10))),
            )
            .unwrap();
        assert!(sheet.filter_violation(cell).is_none());
        assert!(sheet.filter_violation(CellId::default()).is_none());
    }

    #[test]
    /// Checks enumeration of a currently nonconforming filtered cell.
    fn filter_violated_cells_reports_a_currently_violated_filter() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(60_i32);
        let b = sheet.add_cell(0_i32);
        sheet
            .add_filter(b, Filter::from_fn_0(|x: &i32| Ok((*x).clamp(0, 100))))
            .unwrap();
        sheet
            .add_relationship(vec![Method::from_fn_1_1(a, b, |x: &i32| Ok(*x * 2))])
            .unwrap();
        sheet.propagate().unwrap();
        assert!(sheet.filter_violated_cells().any(|id| id == b));
        assert!(matches!(
            sheet.filter_violation(b),
            Some(FilterViolation::NotConformed)
        ));
    }

    #[test]
    /// Checks an empty diagnostic-contributor set when all filters conform.
    fn filter_violation_cells_is_empty_when_nothing_is_violated() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(10_i32);
        sheet
            .add_filter(a, Filter::from_fn_0(|x: &i32| Ok((*x).clamp(0, 100))))
            .unwrap();
        sheet.propagate().unwrap();
        assert!(sheet.filter_violation_cells().is_empty());
    }

    #[test]
    /// Checks root contributors of a nonconforming derived value.
    fn filter_violation_cells_includes_root_causes_of_a_violation() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(60_i32);
        let bound = sheet.add_cell(100_i32);
        let b = sheet.add_cell(0_i32);
        sheet
            .add_filter(
                b,
                Filter::from_fn_1(bound, |x: &i32, bound: &i32| Ok((*x).min(*bound))),
            )
            .unwrap();
        sheet
            .add_relationship(vec![Method::from_fn_1_1(a, b, |x: &i32| Ok(*x * 2))])
            .unwrap();
        sheet.propagate().unwrap();
        let violation_cells = sheet.filter_violation_cells();
        // `b` is forced (its relationship has only one method), so — mirroring
        // `contributing_cells`'s existing semantics — it is `a` and `bound` that
        // appear as the upstream root causes, not `b` itself. `b`'s own membership
        // is already answered by `filter_violated_cells()`, tested separately above.
        assert!(violation_cells.contains(&a));
        assert!(violation_cells.contains(&bound));
    }

    #[test]
    /// Checks root contributors of a failed filter diagnostic.
    fn filter_violation_cells_includes_root_causes_of_a_failed_violation() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(1_i32);
        let bound = sheet.add_cell(100_i32);
        let b = sheet.add_cell(0_i32);
        // Errors on a nonzero input so the relationship's derived value (copied from `a`) trips a
        // `Failed` violation instead of `NotConformed`.
        sheet
            .add_filter(
                b,
                Filter::from_fn_1(bound, |x: &i32, _bound: &i32| {
                    if *x == 0 {
                        Ok(*x)
                    } else {
                        Err(anyhow::anyhow!("cannot conform"))
                    }
                }),
            )
            .unwrap();
        sheet
            .add_relationship(vec![Method::from_fn_1_1(a, b, |x: &i32| Ok(*x))])
            .unwrap();
        sheet.propagate().unwrap();
        assert!(matches!(
            sheet.filter_violation(b),
            Some(FilterViolation::Failed(_))
        ));
        let violation_cells = sheet.filter_violation_cells();
        // Mirroring the `NotConformed` case above: `b` is forced, so `a` and `bound`
        // are the upstream root causes, not `b` itself.
        assert!(violation_cells.contains(&a));
        assert!(violation_cells.contains(&bound));
    }

    #[test]
    /// Checks reverse lookup of filter-argument dependents.
    fn filter_dependents_returns_the_cells_whose_filter_references_this_one() {
        let mut sheet = Sheet::new();
        let bound = sheet.add_cell(10_i32);
        let a = sheet.add_cell(5_i32);
        sheet
            .add_filter(
                a,
                Filter::from_fn_1(bound, |v: &i32, b: &i32| Ok((*v).min(*b))),
            )
            .unwrap();
        assert_eq!(sheet.filter_dependents(bound), &[a]);
    }

    #[test]
    /// Checks empty reverse-filter membership for an unreferenced cell.
    fn filter_dependents_is_empty_for_a_cell_no_filter_references() {
        let mut sheet = Sheet::new();
        let bound = sheet.add_cell(10_i32);
        let a = sheet.add_cell(5_i32);
        sheet
            .add_filter(a, Filter::from_fn_0(|v: &i32| Ok((*v).clamp(0, 100))))
            .unwrap();
        assert!(sheet.filter_dependents(bound).is_empty());
    }

    #[test]
    /// Checks empty reverse-filter membership for an unknown cell.
    fn filter_dependents_is_empty_for_an_invalid_cell() {
        let sheet = Sheet::new();
        assert!(sheet.filter_dependents(CellId::default()).is_empty());
    }

    #[test]
    /// Checks complete reverse membership when several filters share an argument.
    fn filter_dependents_aggregates_multiple_dependents_of_the_same_argument() {
        let mut sheet = Sheet::new();
        let bound = sheet.add_cell(10_i32);
        let a = sheet.add_cell(5_i32);
        let b = sheet.add_cell(5_i32);
        sheet
            .add_filter(
                a,
                Filter::from_fn_1(bound, |v: &i32, bd: &i32| Ok((*v).min(*bd))),
            )
            .unwrap();
        sheet
            .add_filter(
                b,
                Filter::from_fn_1(bound, |v: &i32, bd: &i32| Ok((*v).min(*bd))),
            )
            .unwrap();
        let dependents = sheet.filter_dependents(bound);
        assert_eq!(dependents.len(), 2);
        assert!(dependents.contains(&a));
        assert!(dependents.contains(&b));
    }

    #[test]
    /// Checks absent presentation metadata on an unfiltered cell.
    fn filter_kind_returns_none_for_a_cell_with_no_filter() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        assert!(sheet.filter_kind(a).is_none());
    }

    #[test]
    /// Checks opaque metadata for an ordinary filter.
    fn filter_kind_returns_opaque_for_a_plain_filter() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        sheet
            .add_filter(a, Filter::from_fn_0(|x: &i32| Ok(*x)))
            .unwrap();
        assert!(matches!(sheet.filter_kind(a), Some(FilterKind::Opaque)));
    }

    #[test]
    /// Checks range metadata for a range filter.
    fn filter_kind_returns_range_for_a_range_filter() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let filter = Filter::range(
            TypeId::of::<i32>(),
            vec![],
            vec![],
            |value, _args| Ok(Box::new(*value.downcast_ref::<i32>().unwrap()) as Box<dyn Any>),
            |_args| {
                Some((
                    Box::new(0i32) as Box<dyn Any>,
                    Box::new(100i32) as Box<dyn Any>,
                ))
            },
        );
        sheet.add_filter(a, filter).unwrap();
        assert!(matches!(
            sheet.filter_kind(a),
            Some(FilterKind::Range { .. })
        ));
    }

    #[test]
    /// Checks live range-bound values read from dynamic argument cells.
    fn filter_range_returns_live_bounds_from_argument_cells() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let lo = sheet.add_cell(0_i32);
        let hi = sheet.add_cell(100_i32);
        let filter = Filter::range(
            TypeId::of::<i32>(),
            vec![lo, hi],
            vec![TypeId::of::<i32>(), TypeId::of::<i32>()],
            |value, args| {
                let v = *value.downcast_ref::<i32>().unwrap();
                let lo = *args[0].downcast_ref::<i32>().unwrap();
                let hi = *args[1].downcast_ref::<i32>().unwrap();
                Ok(Box::new(v.clamp(lo, hi)) as Box<dyn Any>)
            },
            |args| {
                Some((
                    Box::new(*args[0].downcast_ref::<i32>().unwrap()) as Box<dyn Any>,
                    Box::new(*args[1].downcast_ref::<i32>().unwrap()) as Box<dyn Any>,
                ))
            },
        );
        sheet.add_filter(a, filter).unwrap();
        assert_eq!(sheet.filter_range::<i32>(a), Some((0, 100)));
        sheet.write(hi, 10_i32).unwrap();
        assert_eq!(sheet.filter_range::<i32>(a), Some((0, 10)));
    }

    #[test]
    /// Checks range introspection of a relationship-derived bound.
    fn filter_range_reflects_a_bound_derived_by_a_relationship_not_just_a_direct_write() {
        // `hi` isn't itself written — its value is derived from `hi_source` via a relationship —
        // exercising `filter_range`'s use of `effective()` (which sees a relationship's derived
        // override), not just `source`.
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        let lo = sheet.add_cell(0_i32);
        let hi = sheet.add_cell(100_i32);
        let hi_source = sheet.add_cell(100_i32);
        sheet
            .add_relationship(vec![Method::from_fn_1_1(hi_source, hi, |v: &i32| Ok(*v))])
            .unwrap();
        let filter = Filter::range(
            TypeId::of::<i32>(),
            vec![lo, hi],
            vec![TypeId::of::<i32>(), TypeId::of::<i32>()],
            |value, args| {
                let v = *value.downcast_ref::<i32>().unwrap();
                let lo = *args[0].downcast_ref::<i32>().unwrap();
                let hi = *args[1].downcast_ref::<i32>().unwrap();
                Ok(Box::new(v.clamp(lo, hi)) as Box<dyn Any>)
            },
            |args| {
                Some((
                    Box::new(*args[0].downcast_ref::<i32>().unwrap()) as Box<dyn Any>,
                    Box::new(*args[1].downcast_ref::<i32>().unwrap()) as Box<dyn Any>,
                ))
            },
        );
        sheet.add_filter(a, filter).unwrap();
        sheet.write(hi_source, 20_i32).unwrap();
        sheet.propagate().unwrap();
        assert_eq!(sheet.filter_range::<i32>(a), Some((0, 20)));
    }

    #[test]
    /// Checks absence of range bounds for an opaque filter.
    fn filter_range_returns_none_for_an_opaque_filter() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(0_i32);
        sheet
            .add_filter(a, Filter::from_fn_0(|x: &i32| Ok(*x)))
            .unwrap();
        assert!(sheet.filter_range::<i32>(a).is_none());
    }

    #[test]
    /// Attaches each check independently and returns IDs in registration order.
    fn add_requirement_returns_distinct_ids_on_same_cell() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(5_i32);
        let first = sheet
            .add_requirement(a, Requirement::from_fn_1(a, |x: &i32| Ok(*x > 0)))
            .unwrap();
        let result = sheet.add_requirement(a, Requirement::from_fn_1(a, |x: &i32| Ok(*x < 100)));
        let second = result.unwrap();
        assert_ne!(first, second);
        assert_eq!(sheet.cell_requirements(a), Some([first, second].as_slice()));
    }

    #[test]
    /// Reports an ordinary cell's false requirement after propagation.
    fn add_requirement_defers_false_cell_requirement_until_propagation() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(-5_i32);
        let requirement = sheet
            .add_requirement(a, Requirement::from_fn_1(a, |x: &i32| Ok(*x > 0)))
            .unwrap();
        sheet.propagate().unwrap();
        assert!(!sheet.cell_requirements_valid(a));
        assert_eq!(
            sheet.violated_requirements(a).collect::<Vec<_>>(),
            [requirement]
        );
    }

    #[test]
    /// Reports a source cell's false requirement after propagation.
    fn add_requirement_defers_false_source_requirement_until_propagation() {
        let mut sheet = Sheet::new();
        let a = sheet.add_source(-5_i32);
        let requirement = sheet
            .add_requirement(a, Requirement::from_fn_1(a, |x: &i32| Ok(*x > 0)))
            .unwrap();
        sheet.propagate().unwrap();
        assert!(!sheet.cell_requirements_valid(a));
        assert_eq!(
            sheet.violated_requirements(a).collect::<Vec<_>>(),
            [requirement]
        );
    }

    #[test]
    /// Propagates requirement-evaluation failure during propagation.
    fn add_requirement_defers_evaluation_error_until_propagation() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(5_i32);
        sheet
            .add_requirement(
                a,
                Requirement::from_fn_1(a, |_: &i32| Err(anyhow::anyhow!("boom"))),
            )
            .unwrap();
        assert!(matches!(
            sheet.propagate(),
            Err(Error::MethodFailed { sites, .. }) if sites == [ErrorSite::Cell(a)]
        ));
    }

    #[test]
    /// Checks lookup of the requirement attached to a cell.
    fn cell_has_the_requirement_it_was_given() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(5_i32);
        let rid = sheet
            .add_requirement(a, Requirement::from_fn_1(a, |x: &i32| Ok(*x > 0)))
            .unwrap();
        assert_eq!(sheet.cells[a].requirements, vec![rid]);
    }

    #[test]
    /// Checks that Out declaration returns its governed cell identity.
    fn add_out_returns_the_cell_id_directly() {
        let mut sheet = Sheet::new();
        let width = sheet.add_cell(4_i32);
        let height = sheet.add_cell(5_i32);
        let area = sheet.add_cell(0_i32);
        let cell = sheet
            .add_out(
                Method::from_fn_2_1([width, height], area, |w: &i32, h: &i32| Ok(w * h)),
                vec![],
            )
            .unwrap();
        assert_eq!(cell, area);
        assert_eq!(sheet.cell_kind(area), Some(CellKind::Out));
    }

    #[test]
    /// Checks downstream use of a fixed Out cell as an ordinary input.
    fn out_cell_is_referenceable_as_another_relationships_input() {
        let mut sheet = Sheet::new();
        let width = sheet.add_cell(4_i32);
        let height = sheet.add_cell(5_i32);
        let area = sheet.add_cell(0_i32);
        let doubled = sheet.add_cell(0_i32);
        sheet
            .add_out(
                Method::from_fn_2_1([width, height], area, |w: &i32, h: &i32| Ok(w * h)),
                vec![],
            )
            .unwrap();
        let result =
            sheet.add_relationship(vec![Method::from_fn_1_1(
                area,
                doubled,
                |a: &i32| Ok(a * 2),
            )]);
        assert!(result.is_ok());
    }

    #[test]
    /// Checks use of a fixed Out cell as a conditional subject.
    fn out_cell_is_referenceable_as_a_conditional_match_subject() {
        let mut sheet = Sheet::new();
        let flag = sheet.add_cell(0_i32);
        let derived_flag = sheet.add_cell(0_i32);
        sheet
            .add_out(
                Method::from_fn_1_1(flag, derived_flag, |f: &i32| Ok(*f)),
                vec![],
            )
            .unwrap();
        let result = sheet.add_conditional(
            MatchExpr::cell(derived_flag),
            Vec::<(Vec<i32>, Vec<RelationshipId>)>::new(),
            vec![],
        );
        assert!(result.is_ok());
    }

    #[test]
    /// Checks rejection of a second fixed writer for an Out cell.
    fn add_out_returns_invalid_cell_kind_for_a_second_writer() {
        let mut sheet = Sheet::new();
        let width = sheet.add_cell(4_i32);
        let height = sheet.add_cell(5_i32);
        let area = sheet.add_cell(0_i32);
        sheet
            .add_out(Method::from_fn_1_1(width, area, |w: &i32| Ok(*w)), vec![])
            .unwrap();
        let result = sheet.add_out(Method::from_fn_1_1(height, area, |h: &i32| Ok(*h)), vec![]);
        assert!(matches!(result, Err(Error::InvalidCellKind { .. })));
    }

    #[test]
    /// Checks legal Out promotion of a previously input-only cell.
    fn add_out_succeeds_when_target_cell_was_previously_used_only_as_an_input() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(1_i32);
        let b = sheet.add_cell(2_i32);
        sheet
            .add_relationship(vec![Method::from_fn_1_1(a, b, |x: &i32| Ok(*x))])
            .unwrap();
        let c = sheet.add_cell(0_i32);
        sheet
            .add_out(
                Method::from_fn_1_1(c, a, |x: &i32| {
                    x.checked_mul(2).ok_or_else(|| anyhow::anyhow!("overflow"))
                }),
                vec![],
            )
            .unwrap();
        assert_eq!(sheet.cell_kind(a), Some(CellKind::Out));
        sheet.write(c, 9_i32).unwrap();
        sheet.propagate().unwrap();
        assert_eq!(*sheet.read::<i32>(a).unwrap(), 18);
        assert_eq!(*sheet.read::<i32>(b).unwrap(), 18);
    }

    #[test]
    /// Checks deferred requirement evaluation on a newly declared Out cell.
    fn add_out_with_a_requirement_that_would_fail_still_succeeds_and_propagate_reports_it() {
        let mut sheet = Sheet::new();
        let width = sheet.add_cell(4_i32);
        let area = sheet.add_cell(0_i32);
        let area_cell = sheet
            .add_out(
                Method::from_fn_1_1(width, area, |w: &i32| Ok(*w)),
                vec![Requirement::from_fn_1(area, |a: &i32| Ok(*a > 100))],
            )
            .unwrap();
        sheet.propagate().unwrap();
        assert!(!sheet.cell_requirements_valid(area_cell));
        assert_eq!(sheet.violated_requirements(area_cell).count(), 1);
    }

    #[test]
    /// Checks exclusion of ordinary cells from Out enumeration.
    fn out_cells_iterates_only_out_kind_cells() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(1_i32);
        let b = sheet.add_cell(0_i32);
        let out_id = sheet
            .add_out(Method::from_fn_1_1(a, b, |x: &i32| Ok(*x)), vec![])
            .unwrap();
        let ids: Vec<CellId> = sheet.out_cells().collect();
        assert_eq!(ids, vec![out_id]);
    }

    #[test]
    /// Checks legal diagnostic-filter attachment to a fixed Out cell.
    fn add_filter_succeeds_on_a_real_out_kind_cell() {
        let mut sheet = Sheet::new();
        let width = sheet.add_cell(4_i32);
        let area = sheet.add_cell(0_i32);
        let out_cell = sheet
            .add_out(Method::from_fn_1_1(width, area, |w: &i32| Ok(*w)), vec![])
            .unwrap();
        let result = sheet.add_filter(out_cell, Filter::from_fn_0(|x: &i32| Ok((*x).clamp(0, 10))));
        assert!(result.is_ok());
    }

    #[test]
    /// Checks relevance contributors for a requirement on an ordinary cell.
    fn requirement_relevant_cells_covers_a_plain_cells_requirement_too() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(5_i32);
        sheet
            .add_requirement(a, Requirement::from_fn_1(a, |x: &i32| Ok(*x > 0)))
            .unwrap();
        sheet.propagate().unwrap();
        assert!(sheet.requirement_relevant_cells().contains(&a));
    }

    #[test]
    /// Checks violation contributors for a failed requirement on an ordinary cell.
    fn requirement_violation_cells_covers_a_plain_cells_violation_too() {
        let mut sheet = Sheet::new();
        let a = sheet.add_cell(200_i32);
        sheet
            .add_requirement(a, Requirement::from_fn_1(a, |x: &i32| Ok(*x > 100)))
            .unwrap();
        sheet.write(a, 5_i32).unwrap();
        sheet.propagate().unwrap();
        assert!(sheet.requirement_violation_cells().contains(&a));
    }
}